@@ -0,0 +1,22 @@
+---
+"@objectstack/cli": patch
+---
+
+refactor(cli): spell the action-dedup object-less key as `GLOBAL_ACTION_OBJECT_KEY` (#14669)
+
+`os lint` dedups action declarations on the engine's composite registration key
+(`<objectName>:<name>`), and the object half of that key terminated on a bare
+`'global'` string literal in `lintConfig`'s `PREFIXED_TYPES` table. The engine's
+own writers stopped spelling the literal: PR #14667 converged
+`ObjectQLPlugin.actionObjectKey` onto the shared `GLOBAL_ACTION_OBJECT_KEY`
+constant for exactly this reason — a copy that agrees by value today is the one
+that parts from the writer in silence the day the constant moves, with no test
+in the repo able to see it. This reader now imports the constant from
+`@objectstack/objectql`, which `@objectstack/cli` already depends on.
+
+**No behaviour moves.** `GLOBAL_ACTION_OBJECT_KEY` is `'global'`, so every key
+this table builds is byte-identical to the one it built before; the #5510 dedup
+suite (`lint-namespace-prefix.test.ts`, 15 declarations over 5 objects) passes
+unchanged. Only `objectName` is read, exactly as before — the `object`/`entity`
+aliases are still rejected upstream by `ActionSchema`'s strict shape and are
+deliberately not admitted here.
@@ -0,0 +1,17 @@
+---
+'@objectstack/spec': minor
+---
+
+`composeStacks` now refuses two input stacks whose action declarations resolve to one scope-qualified runtime key — **BREAKING** accept-set narrowing, shipped as `minor` under the repo's launch-window convention for breaking changes.
+
+**The refused shape:** two (or more) input stacks that each declare an action resolving to one runtime key — `objectName:name`, or `global:name` for an object-less action. The canonical case is two packages, each legal on its own, each declaring a global action named `shared_refresh`: `composeStacks([a, b])` used to accept the pair and emit `["global:shared_refresh", "global:shared_refresh"]`, and the runtime — which registers and dispatches every action under that one exact-string key — collapsed both handlers to one registration: whichever registered second won, and the other package's action stayed a live, declared, permission-gated button whose handler was unreachable. `defineStack` refuses exactly this collision within one stack (#14686); composition was the second door in the same file that let it through.
+
+The refusal carries `composeStacks`' conflict prefix and `defineStack`'s envelope shape — `composeStacks conflict: cross-stack action key collision (N issue(s)):`, one `✗` line per colliding key — and every line names the key, **both source stacks by manifest id** (`'com.example.a' (stack #0)`; a manifest-less input is named by position), and where each declaration sits (`stack.actions[i]`, or `objects['OBJECT'].actions[j]` for an embedded one). The fix is the one the message names: rename one of the colliding actions within its scope, bind one of them to a different object, or remove the duplicate from one of the stacks. ⛔ There is no `actionConflict` option and none is coming: `composeStacks` does not pick a winner for actions (maintainer ruling, 2026-09-03).
+
+What the check judges is what composition **carries**: standalone actions from every stack (they concatenate), and each composed object's embedded actions attributed to the one stack whose object `objectConflict` handed the `actions` array to. So an embedded action that `'override'` or `'merge'` did not carry into the composed object cannot collide — that loss is the object strategy's own semantics — while a standalone action bound to an object from one stack does collide with an embedded action of the same name the composed object carries from another. Only a key declared by two or more **distinct** stacks is reported: a key an input repeats within itself is `defineStack`'s door (`strict: false` opts out there by choice), and an input built by `defineStack` legitimately carries each bound standalone action twice — as the copy the build appended to its object — which is never a collision with itself.
+
+Deliberately unchanged, as in `defineStack`: one global and one object-bound action may share a name across stacks (two keys), and one name bound to two different objects is two keys. The shipped composer, `examples/app-multi-package`, declares no colliding key and composes unchanged; no `composeStacks` caller exists in objectui or hotcrm.
+
+**Migration.** A composition refused by the new check must resolve the collision in one of the two packages — rename the action within its scope, bind it to a different object, or drop the duplicate. Which package keeps the name is an authoring decision the metadata cannot make for you.
+
+<!-- adr-0087: not-required (no-migration-prescription) a validity narrowing over existing declarations: no key is removed, renamed or re-shaped and no export moves, so the ledger has no rewrite to carry; the refusal itself names the remedy at the composition site, and choosing which of two packages keeps the action name is an authoring decision no migration entry can perform on an upgrader's behalf. -->
@@ -0,0 +1,72 @@
+---
+"@objectstack/platform-objects": patch
+"@objectstack/lint": patch
+"@objectstack/mcp": patch
+---
+
+fix(ai): author the CANONICAL agent id everywhere the platform teaches one — Studio's pin, the MCP prompt example, and the lint's value roster (#14461)
+
+`skills/objectstack-ai` tells authors that `data_chat` and `metadata_assistant`
+"are **not** vocabulary — always write `ask` / `build`". The platform then
+taught the opposite from every live example it ships. Nothing was broken at
+runtime; what was wrong is what an author copies.
+
+**Studio's pin.** `studio.app.ts` was the repo's ONLY `app.defaultAgent` usage,
+and it spelled the alias:
+
+```
+- defaultAgent: 'metadata_assistant',
++ defaultAgent: 'build',
+```
+
+The triage card left this undecidable — if the cloud plugin registered the
+agent under the legacy id, re-pinning would be a behaviour change in a
+consumer this repo cannot see. Measured instead of assumed, at `cloud`
+`main@3856fbf7`: `service-ai-studio/src/agents/metadata-assistant-agent.ts:12,40`
+ships the record as `name: BUILD_AGENT_NAME` = `'build'`, and `plugin.ts:58`
+registers `metadata_assistant` as a **one-way, resolution-only** legacy alias.
+The canonical id *is* `build`; the old pin reached it by detour.
+
+Nor is the re-pin cosmetic. Alias resolution depends on an in-memory
+`registerAgentAlias` call having run at plugin init, and cloud carries two
+defensive docblocks about that registration silently no-op'ing for real under
+bundle load ordering (`service-ai-studio/src/plugin.ts:44-57`,
+`service-ai/src/agent-runtime.ts:30-41` — "a missed alias must never hide a
+real platform agent like `build`"). The canonical id never touches the alias
+table, so this drops a load-order dependency from the platform's own flagship
+authoring surface. On the UI side nothing moves: `objectui`'s
+`AGENT_ALIAS_GROUPS` is bidirectional and canonical-first, and
+`SURFACE_DEFAULT['studio-build']` was already `'build'`.
+
+**The MCP prompt example.** `mcp-server-runtime.ts`'s `agent_prompt` argument
+described itself as `'Name of the agent to load (e.g. "data_chat",
+"metadata_assistant")'` — two retired aliases, neither canonical id present.
+That string is served to every MCP client asking what to pass, so the one
+surface that suggests a spelling to an LLM suggested the two the catalogue
+forbids. Now `(e.g. "ask", "build")`.
+
+**The lint's value roster.** `validate-ai-agent-authoring`'s `defaultAgent`
+**value** limb reused the four-name `PLATFORM_AGENT_NAMES` set, so it
+deliberately passed `metadata_assistant` — the gate that exists to make
+authoring mistakes loud waved through the exact spelling the catalogue bans,
+which is the silent-tolerance shape ADR-0078 exists to close, committed by the
+gate itself. The two limbs now read different tables, because they ask
+different questions:
+
+- **declaration limb** — unchanged, still all four names. Declaring
+  `metadata_assistant` shadows the `build` record through the alias exactly as
+  declaring `build` does.
+- **value limb** — canonical `ask` / `build` only. A legacy alias gets its own
+  rule id `default-agent-legacy-alias` (exported) and its own wording, because
+  an alias **resolves** (the app gets the agent it meant — a spelling defect)
+  while an unknown name does **not** (the pin is inert). Describing the alias
+  as "no effect" would send an author hunting a bug that is not there.
+
+Both of the #6041 ruling's operative decisions are kept intact: still
+`warning` tier, still no Zod enum narrowing. `defaultAgent: 'metadata_assistant'`
+keeps parsing, building, and resolving — the only change is that authoring it
+now says so.
+
+Not breaking: nothing an author can write was removed, and both aliases stay
+resolvable for old bookmarks and persisted `agent_id`s, which is the only job
+ADR-0063 §2 ever gave them.
@@ -0,0 +1,14 @@
+---
+'@objectstack/cli': patch
+---
+
+Fix `os explain flow`, whose example taught a flow shape the spec rejects and an assignment value nothing resolves.
+
+`os explain` is an authoring aid whose whole audience is authors — increasingly AI authors — writing their first flow, and its catalog is hand-maintained rather than derived from `FlowSchema`. The flow entry had drifted until the sample it printed could not be pasted into a working app:
+
+- `steps` and `trigger` are strict-object **aliases** on `FlowSchema` (for `nodes` and `type`), so authoring either is a loud parse error rather than a working flow. A record-change flow binds its object on the START node's `config` (`{ objectName, triggerType }`), not at the flow top level.
+- A node's per-type data lives under `config`, so the sample's top-level `field`/`value` pair were undeclared keys on a `.strict()` node schema, and the required `id` / `label` were absent. `edges` is required, and the sample declared no graph at all.
+- The value `'$currentUser'` was a `$`-prefixed sentinel no resolver in the platform recognises. Flow values interpolate with **single braces**, and the acting user is `{$User.Id}` — the filter surface's `{current_user_id}` is a different dialect that does not carry over, because assignment and `fields` values go through `interpolate`, not `interpolateFilter`.
+- An `assignment` node sets a flow **variable**, not a record field, so "auto-assign on create" is an `update_record` node. The old sample would not have written `assigned_to` even with a resolving token.
+
+The entry's field list now matches `FlowSchema` (`nodes` / `edges` / the full five-value `type` enum / `status` / `runAs`), and the example is pinned by a test that parses it against `FlowSchema` — the one guard that cannot drift alongside the catalog it checks.
@@ -0,0 +1,39 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): a top-level flow `trigger` / `triggerType` is now sent to the START node's `config`, not to a `type` rename
+
+`FlowSchema`'s alias table pointed both keys at `type`, so a flow carrying a
+top-level trigger block was refused with the rename `trigger` → `type`.
+That rename cannot be taken: `type` is the flow KIND
+(`autolaunched` | `record_change` | `schedule` | `screen` | `api`), so an author
+who followed the advice landed on
+`Invalid option: expected one of "autolaunched"|…` one round later, with the
+trigger binding still nowhere — and a `.strict()` refusal carries exactly one
+actionable sentence.
+
+The trigger does not move to `type`. It binds on the START node's `config`, as
+`{ objectName, triggerType, condition }` with a `record-*` token such as
+`record-after-create` — the shape the automation engine and the authoring-time
+`resolveFlowTriggerKind` both read. Both keys are `guidance` entries now, beside
+the `object` / `objectName` / `schedule` prescriptions that already name that
+config, so the rejection says where the binding really lives instead of
+prescribing a name:
+
+```
+Unrecognized key(s) on this flow: `trigger`.
+  • `trigger` is not a Flow field — a record-change flow binds its trigger on
+    the START node's `config` (`{ objectName, triggerType, condition }`, where
+    `triggerType` is a `record-*` token such as `record-after-create`), not at
+    the flow top level; the flow-level `type` names the flow kind
+    (`record_change`), not the binding.
+```
+
+No accept/reject behaviour changes: a top-level `trigger` / `triggerType` was
+refused before and is refused now, and `FlowSchema`'s accepted keys and its
+`type` enum are untouched — only the prescription the refusal carries. One
+measured consequence of dropping the alias row: the guidance channel matches the
+exact authored spelling (case folding is the rename channel's job), so a
+non-canonical spelling such as `triggertype` now gets the bare rejection rather
+than the rename it cannot take.
@@ -0,0 +1,40 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `os generate` now has an answer for every field type, instead of silently guessing
+
+Three hand-kept vocabularies in `generate.ts` decide what `os generate types`
+and `os generate migration` emit for a field: the TypeScript type, the SQL
+column type, and the knex builder call. None of them was ever checked against
+the `FieldType` enum they describe, and measured against the 49 members on
+`main`, **21 real members had no entry in either lookup table and 24 had no arm
+in the migration switch**.
+
+An unmapped member did not fail — it fell to the default. So a `secret` field
+scaffolded as TypeScript `unknown` and a `TEXT` column, a `location` as
+`unknown` and `TEXT`, and `address` / `composite` / `repeater` / `record` — all
+four stored as JSON on the parent row — as scalar `TEXT` columns. The output
+looked plausible and nothing said otherwise, which is what made this worth
+fixing rather than tidying.
+
+All 49 members now have an entry in all three, and the values are read off the
+platform rather than invented: the spec's ADR-0104 D1 value classes
+(`STRING_VALUE_TYPES`, `NUMERIC_VALUE_TYPES`, `STRUCTURED_JSON_TYPES`, …) decide
+the class, and `driver-sql`'s own DDL emitter — which creates the real columns —
+decides the shape. `location` becomes a JSON column, not a `POINT`: that is what
+the driver does, `POINT` is not portable to SQLite, and the spec's own value
+contract for it is `{lat, lng, altitude?, accuracy?}`. `location` and `address`
+now emit the spec's exported `Data.LocationValue` / `Data.AddressValue` types,
+so the generated interface cannot drift from the value contract.
+
+The gap can no longer reopen quietly. Both lookup tables are
+`satisfies Record<FieldType, string>`, so a field type added to the spec is a
+named compile error here; the switch — whose scrutinee is a plain string off an
+unvalidated config and so cannot carry one — is held by
+`generate-field-type-vocabulary.pin.test.ts`, which walks the real enum and
+names any member left unmapped.
+
+The runtime fallbacks (`|| 'unknown'`, `|| 'TEXT'`, `default:`) are unchanged
+and still reachable: they answer a `type` string that is not a field type at
+all, which the unvalidated authoring door can still deliver.
@@ -0,0 +1,57 @@
+---
+'@objectstack/lint': minor
+---
+
+security lint: report a `controlled_by_parent` object whose master is decided by FIELD DECLARATION ORDER (#14747)
+
+`SecurityPlugin.resolveCbpRelation` resolves the master a `controlled_by_parent`
+object derives record-level access from through three tiers — a required
+`master_detail`, then any `master_detail`, then a required `lookup` — and picks
+inside a tier with `Array.prototype.find`. So when two or more candidates sit in
+the tier that wins, the master is whichever one the field map happens to list
+first. Measured on a real kernel: an object declaring two required lookups
+resolved its security master to the first-declared one, and swapping the two
+field declarations — nothing else — repointed every row's record-level access
+to the other object. Nothing reported it: not `os validate`, not `os lint`, not
+a boot warning.
+
+New error id **`security-controlled-by-parent-ambiguous-relation`**, the mirror
+image of `security-controlled-by-parent-no-relation` (#7503): that one reports
+ZERO candidates, this one reports two or more. The message names every
+candidate — field, type and master — in declaration order, says which tier was
+tested, and says which candidate wins today and therefore which object access
+derives from right now.
+
+Only the **winning** tier is judged, and that is not a shortcut: the runtime's
+`??` chain stops at the first tier that resolves, so a tie in a lower tier is
+masked by a higher tier's single winner and is not a decision the platform ever
+makes. An object with one required `master_detail` and two required lookups is
+silent, and stays silent.
+
+`error` rather than advisory, for the inverse of the usual reason. The other
+error rules in this linter mirror a hard runtime refusal; this one has none to
+mirror precisely BECAUSE the runtime does not refuse — it silently picks — so
+author time is the only place the ambiguity can ever surface. What it does meet
+is the admissibility bar the #7503 rule states: a self-contained property of the
+object document, no per-permission-set nuance to adjudicate, and no legitimate
+reading, since two tied candidates is not an author saying which master they
+meant.
+
+This **narrows the accept set of a gating rule** — error findings fail
+`os validate` / `os compile`. Measured over the shipped corpus: the three
+`controlled_by_parent` objects in the example apps (`showcase_invoice_line`,
+`showcase_expense_line`, `crm_opportunity_line_item`) plus the 27
+`ObjectSchema.create` sites the `check:doc-security-posture` gate reads across
+226 marked prose blocks — **0 findings before and 0 after**. Each of the three
+declares exactly one required `master_detail`, so tier 1 wins with a single
+candidate. `showcase_invoice_line` is the interesting one: it also carries a
+required `lookup`, and the rule is silent because that tie-free lower tier is
+never reached.
+
+No runtime behaviour changes. `resolveCbpRelation` in this package now reads its
+tiers from one shared table so the two rules cannot disagree about which tier
+wins, and its answer is unchanged by construction: `find` over a tier is the
+first element `filter` over that tier keeps. The mirror's one deliberate
+divergence from the runtime is kept — `reference` is the only spelling accepted
+here (#5017), so a field carrying the rejected `reference_to` alias is not a
+candidate and cannot create a tie.