Merge branch 'main' into claude/issue-13798-self-test-handshake-b2

Author: claude[bot]

.changeset/auth-bindings-off-registerroutes.md

@@ -0,0 +1,42 @@
+---
+"@objectstack/plugin-auth": patch
+---
+
+fix(plugin-auth): the mail transport, brand and locale bindings no longer depend on `registerRoutes`
+
+`AuthPlugin` bound five things to the live kernel on `kernel:ready` — the
+outbound mail transport (`setEmailService`), the SMS transport
+(`setSmsService`), the deployment email locale (`setDefaultEmailLocale`), the
+brand name (`setAppName`) and the SMS locale (`setDefaultSmsLocale`) — from
+inside the same hook that mounts `/api/v1/auth/*`, and that hook was gated on
+`registerRoutes`.
+
+`registerRoutes` answers a transport-mounting question: should this plugin put
+its own routes on the kernel's `http-server`. The bindings are service
+composition, and they are true of an embedding regardless of who serves the
+routes. So an embedding that serves auth routes itself — the whole point of
+`registerRoutes: false` — came up with no mail transport, no locale on either
+channel and no brand binding. Silently: the `logger.info` lines that report the
+wiring were inside the same skipped block, and the `localization` settings
+namespace was not even read. One visible consequence was that the workspace
+language could not reach auth mail on such a host at all, and
+`/api/v1/auth/config` answered `requireEmailVerification: false` because
+`resolveRequireEmailVerification()` saw no transport.
+
+The composition block now registers as its own unconditional
+`ctx.hook('kernel:ready', …)` — the shape the sibling diagnosis and dev-seed
+hooks in this plugin already use — placed before the route hook so a routing
+host keeps the ordering the single combined hook gave it.
+
+Route registration itself stays gated: a `registerRoutes: false` kernel still
+mounts no auth routes.
+
+**Behaviour change for `registerRoutes: false` embeddings.** They now resolve
+the `email`, `sms`, `i18n` and `settings` services at `kernel:ready`, apply
+`branding.workspace_name` and `localization.locale` (subscribing to both), seed
+the built-in auth SMS templates when phone sign-in is enabled, and emit the
+four wiring `info` lines. Hosts that had compensated by wiring these by hand
+should expect the plugin's own binding to run as well; both paths are
+idempotent setters, and an explicit workspace setting keeps outranking a
+manifest default exactly as it does on a routing host. Nothing changes for a
+host that leaves `registerRoutes` at its default.

.changeset/cli-action-dedup-global-key-constant.md

@@ -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.

.changeset/compose-stacks-action-key-collision.md

@@ -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. -->

.changeset/default-agent-canonical-spelling.md

@@ -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.

.changeset/explain-flow-example-parses.md

@@ -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.

.changeset/flow-trigger-key-start-node-guidance.md

@@ -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.

.changeset/generate-field-type-vocabulary-totality.md

@@ -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.