Merge origin/main: co-append validateFlowTemplatePaths + validateAiSurfaceAffinity to the suite

Both branches appended a rule to REFERENCE_INTEGRITY_RULES; resolution
keeps main's validateFlowTemplatePaths (#3810) first and this branch's
validateAiSurfaceAffinity last, with the suite test's fixture and
report-order assertions carrying both.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BHjroNkLkajskKbJaidko4

Author: claude

.changeset/action-alias-conflict-warning.md

@@ -0,0 +1,52 @@
+---
+"@objectstack/spec": minor
+"@objectstack/cli": patch
+---
+
+feat(spec,cli): warn the author when a deprecated action alias is discarded (#3743)
+
+#3742 made `target` beat the deprecated `execute` alias everywhere and had the
+`ActionSchema` transform **drop** the alias from its output, so "two different
+scripts for one button" became unrepresentable. What it left behind: an author
+who declares both slots with different values still loses one of the two
+handlers they wrote, **silently**. Per Prime Directive #12 that belongs at
+authoring time, so it is now reported there.
+
+**New rule — `action-target-execute-conflict` (advisory).** An action declaring
+both `target` and `execute` with different values gets a warning naming both
+handlers, stating that `target` wins, and giving the one-line fix (delete
+`execute`). Identical values in both slots are harmless duplication and stay
+quiet. It never fails the build: the resulting stack is well-defined — the cost
+is a handler that never runs, not a broken artifact.
+
+The rule must run **pre-parse**, because the parse is what consumes the alias:
+once `ObjectStackDefinitionSchema` has run there is no `execute` key left to
+report. It therefore lives in `@objectstack/spec`
+(`lintDeprecatedAliases`, exported from the package root) and is wired into
+both layers that perform the discard:
+
+- **`defineStack`** — the dominant authoring path, and the one that consumes the
+  alias earliest: it parses inside your own config module, so by the time
+  `os build` loads that module the alias is already gone. It now warns on the
+  console before parsing (once per distinct conflict per process).
+- **`os build` / `os validate`** — a new pre-parse pass covering stacks that
+  skip strict `defineStack`: a plain object default-export,
+  `defineStack(…, { strict: false })`, and inline function handlers (`target` is
+  `z.string()`, so those cannot pass strict `defineStack` and are lowered by the
+  CLI instead). Both commands lint the same input, so they agree by construction
+  (#3782).
+
+Each layer reports only its own discards, so one authored conflict produces
+exactly one warning however the stack is compiled.
+
+**Behaviour fix in the same contract.** #3742 fixed compile-time precedence by
+probing for a *callable* `target` first, which left one combination still
+resolving the alias's way: a **string** `target` beside a **function** `execute`
+bound the alias and then overwrote the canonical ref the author wrote. `target`
+now wins in every combination of string/function across the two slots, matching
+the `ActionSchema` transform — so the new warning states one precedence rule
+that is true everywhere. If you relied on an inline `execute` function winning
+over a string `target`, move it into `target`; the warning names the action.
+
+Authoring is otherwise unchanged: `execute` alone is still accepted, still
+lowered into `target`, and still documented.

.changeset/action-undoable-liveness-corrected.md

@@ -0,0 +1,38 @@
+---
+"@objectstack/spec": patch
+"@objectstack/cli": patch
+---
+
+fix(spec): `action.undoable` is `live`, not `experimental` — stop warning on a property that works (#3714)
+
+The liveness ledger marked `action.undoable` `experimental` on a #1992-era note:
+*"no runtime reader yet — neither service-automation nor objectui consume the
+action's `undoable` flag (objectui has an UndoManager but does not key off this
+field)."* That was true when written. objectui has since wired **two** readers,
+both gating real behaviour:
+
+| Reader | What the flag gates |
+|---|---|
+| app-shell `useConsoleActionRuntime.tsx:409` | builds the undo operation the success toast's Undo button invokes (`:147`) |
+| app-shell `RecordDetailView.tsx:545` | restores the record's prior field values (`:404`) |
+
+`components` `action/action-button.tsx:113` forwards the flag for exactly this
+reason, per its own comment: *"without this the flag is dropped and the handler
+never builds the undo operation."*
+
+**Why it mattered.** The CLI liveness lint warns on `experimental` as well as
+`dead`, so authoring a *working* property produced a
+`liveness-experimental-property` warning — "declared but NOT enforced at
+runtime". An author (or an AI) reading the ledger or that warning concludes
+`undoable` is aspirational and skips it, losing a shipped feature. Authoring
+`undoable: true` is now silent, and the protocol reference no longer claims
+setting it "currently has no effect".
+
+Nothing to migrate: the schema, the parsed shape, and the runtime are unchanged
+— only the classification of what they already do.
+
+This is the *understating* failure direction, the mirror of the preview-renderer
+over-claims corrected in #3685/#3711/#3686. Both directions have the same root
+cause, now written into `packages/spec/liveness/README.md`: **a ledger entry is a
+claim with a timestamp, and code moves under it in both directions** — entries
+are worth re-verifying rather than trusting indefinitely.

.changeset/adr-0105-d9-cross-org-approver-targeting.md

@@ -0,0 +1,53 @@
+---
+"@objectstack/plugin-approvals": minor
+"@objectstack/spec": minor
+"@objectstack/lint": minor
+---
+
+feat(approvals): cross-organization approver targeting — a plant document can
+require a group-side sign-off (ADR-0105 D9)
+
+One organization id used to decide three different things at once in
+`openNodeRequest`: where the request row lives, where its inbox index rows
+live, and **where its approvers are looked up**. The first two are the
+request's own organization by definition. The third is not — a group CFO holds
+her `cfo` position in the GROUP organization while the purchase order she signs
+off lives in the PLANT organization. `expandPositionUsers('cfo', <plant>)`
+matched nobody, the slot fell back to the dead `position:cfo` literal, and a
+group escalation could not be expressed at all.
+
+An approver may now declare which organization's directory resolves it:
+
+```yaml
+approvers:
+  - { type: position, value: plant_manager, group: plant }
+  - { type: position, value: cfo, organization: $root, group: finance }
+behavior: per_group
+```
+
+- **`$root` / `$parent`** walk D6's `parent_organization_id` tree, so the two
+  common intents need **no deployment knowledge** — flow metadata is portable
+  across environments while organization ids are minted per deployment. A slug
+  covers what the symbols cannot, notably a **sibling** organization (a
+  shared-services centre approving payables for every plant).
+- Declared **per approver**, so one node can require a plant manager and a
+  group CFO in parallel. A node-level form cannot express that without
+  splitting into serial nodes, which changes the semantics.
+- **Bounded, not free:** the target must share a `parent_organization_id` root
+  with the request's organization. The rule reads only the organization tree —
+  never the submitter — so one flow routes identically for everyone.
+
+Everything else fails loudly rather than quietly:
+
+- a non-`group` posture **refuses** the declaration (a `group` → `isolated`
+  migration must not silently reroute approvals);
+- an approver type with no org-scoped directory (`user` / `field` / `manager` /
+  `team`) refuses it too, and a new `approval-approver-cross-org-unsupported`
+  lint catches that at author time;
+- a targeted approver holding no membership in the request's organization is
+  dropped with a warning naming them — D2's union wall would otherwise hide the
+  request from someone already routed to, so the node's existing
+  `onEmptyApprovers` policy takes over instead of leaving an unopenable task.
+
+Nothing changes for an approver without `organization`: same resolution, same
+queries, no extra reads.

.changeset/adr-0105-d9-refuse-on-directory-less-types.md

@@ -0,0 +1,26 @@
+---
+"@objectstack/plugin-approvals": patch
+---
+
+fix(approvals): refuse `organization` on directory-less approver types instead
+of silently ignoring it (ADR-0105 D9)
+
+`user`, `field` and `manager` return EARLY in `resolveApproverSpec` — they name
+a person outright rather than expanding a directory. D9's org resolution was
+placed after those returns, so an `organization` declared on one of them never
+reached the check: it was silently INERT.
+
+That is the one behaviour ADR-0105 D9 rules out and the authoring docs
+explicitly promise against ("`organization` on those is refused at runtime").
+The `os lint` rule caught it at author time, but the runtime claim was false —
+and a stored flow that predates the lint, or one assembled programmatically,
+got no signal at all.
+
+Resolution now happens at the top of `resolveApproverSpec`, above every early
+return, so the refusal reaches all three types. The ordinary path is unchanged
+and still costs nothing: with no `organization` declared the resolver returns
+the request's organization without reading anything.
+
+Found by cloud's group-posture dogfood driving a real `group` boot — the
+resolver's own unit tests could not see it, because they call the resolver
+directly and never traverse the early return.

.changeset/ai-namespace-expresses-real-surface.md

@@ -0,0 +1,65 @@
+---
+"@objectstack/client": major
+"@objectstack/spec": major
+---
+
+feat(client,spec)!: the SDK's `ai` namespace now expresses the AI surface that exists (#3718)
+
+`client.ai` and the AI service were **disjoint sets**. The namespace held three
+methods — `nlq`, `suggest`, `insights` — whose URLs no repo has ever mounted
+(removed in v17), while `service-ai` mounted 12 routes the SDK could not reach
+at all. v17 closed the first half by deleting the dead methods. This closes the
+second: the SDK now reaches every route that is meant to be tenant API surface.
+
+| SDK | Route |
+|---|---|
+| `ai.chat(request)` | `POST /api/v1/ai/chat` — forces `stream: false`, so the JSON mode is what you get |
+| `ai.chatStream(request)` | `POST /api/v1/ai/chat` — `AsyncIterable` of UI Message Stream frames |
+| `ai.complete(request)` | `POST /api/v1/ai/complete` |
+| `ai.models()` | `GET /api/v1/ai/models` — the ADR-0028 plan-filtered picker list |
+| `ai.conversations.create/list/get/update/delete/addMessage` | the six `/api/v1/ai/conversations` routes |
+
+`ai.chatStream` returns a promise for an async iterable rather than being an
+async generator, so the request is issued — and an HTTP error thrown — when you
+call it, not when you first iterate.
+
+**Where the server is.** `service-ai` is a Cloud/EE package in the `cloud`
+repo; this repo only proxies `/api/v1/ai/**` and 404s `AI service is not
+configured` without it. Check `discovery.services` before calling, exactly as
+for any other plugin-provided namespace. For a React chat UI, `useChat()`
+(`@ai-sdk/react`) is still the better client — it speaks the same protocol
+`ai.chatStream` parses and owns message state; these methods are for callers
+that are not components.
+
+**Breaking — the spec's dead AI declarations are retired.** All three had no
+implementation anywhere and no runtime consumer:
+
+- `Ai{Nlq,Suggest,Insights}{Request,Response}[Schema]` → replaced by the wire
+  shapes of the real routes: `AiChat{Request,Response}`, `AiStreamChunk`,
+  `AiCompleteRequest`, `AiModelsResponse`, `AiConversation`, `AiMessage`,
+  `{Create,List,Update}AiConversation*`. The six retired JSON Schemas are
+  dropped from `json-schema.manifest.json` (deliberate retirement, #2978).
+- `DEFAULT_AI_ROUTES` → deleted, and `getDefaultRouteRegistrations()` returns 8
+  groups instead of 9. It declared the three phantom endpoints and had no
+  runtime consumer; re-declaring the real ones here would recreate the same
+  illusion, since they are mounted from another repo.
+- `AiProtocol` (`aiNlq?` / `aiSuggest?` / `aiInsights?`) → deleted. Nothing
+  implemented it and nothing dispatched through it. The real server contract is
+  `IAIService` + `IAIConversationService` in `@objectstack/spec/contracts`.
+
+**The guard.** `/api/v1/ai/` becomes a bounded prefix exemption in the capstone
+(#3642) alongside the control plane — bounded from both ends: only `ai.*` may
+use it, and the namespace must still be reaching it. That is not a
+wave-through. The reachability check lives where the routes are:
+`cloud`'s `packages/service-ai/src/ai-route-ledger.conformance.test.ts` reads
+the table `buildAIRoutes()` returns and drives this SDK against it, so an
+`ai.*` URL that stops resolving fails a test in the repo that mounts it. The
+wildcard-only bound stays **0** — these URLs never touch the `* /ai/**` row,
+which is what certified three dead methods for years.
+
+The four replaced client tests are worth naming: they mocked `fetch` and
+asserted the URL the client *built*, never that anything answered it, and
+passed for years against endpoints that did not exist. The new ones assert only
+what this repo can honestly know — verb, path, and the body decisions the SDK
+makes for you (`stream: false` on `chat`, the 204 on `delete`, SSE frame
+parsing) — and leave "does it resolve" to the ledger next to the routes.

.changeset/ci-node-22-pin.md

@@ -0,0 +1,39 @@
+---
+---
+
+ci: validate on the runtime we publish from — pin every workflow to Node 22 (#3825)
+
+CI ran two Node versions at once, and nobody had decided that. All 12 PR gates —
+Build Core, Test Core, TypeScript Type Check, Dogfood, ESLint, spec liveness,
+dep validation — were on **Node 20**, which reached EOL on **2026-04-30**, while
+`release.yml`, `publish-smoke.yml`, `scaffold-e2e.yml` and `showcase-smoke.yml`
+were on **22**. So code was verified on one runtime and shipped from another,
+and the runtime guarding every merge no longer received security patches.
+
+The split was drift, not policy. `release.yml` carried the receipt in a comment
+— *"22 (not 20 like the other workflows)"* — because a downstream clone pinned
+`engines.node >=22` and pnpm aborted on 20. One workflow got bumped to clear one
+error; the other twelve stayed behind, and nothing in CI could see the gap.
+
+It surfaced only by accident in #3812: a test imported `better-sqlite3@13`,
+whose `engines` say `>=22`. `engines` is a declaration, not enforcement, so it
+loaded on Node 20 and then killed the vitest worker with a **process-level
+abort** — no JS error, so the suite reported `Test Files 22 passed (23)` while
+**17 cases silently never ran**. A green check that had quietly stopped running
+the tests.
+
+All 18 `setup-node` steps now run Node 22, matching what release already used.
+
+**`.nvmrc` is now the single source of truth.** It pins contributors' local
+runtime via `nvm use` — previously there was no pin at all, so a contributor on
+Node 24 could not reproduce a Node 20 gate failure — and `check:node-version`
+(new, wired into the unfiltered, always-required `lint` job) holds every
+workflow to it. A version pin is otherwise 18 independent string literals, which
+is why this drifted invisibly for so long; bumping Node is now a one-line edit
+to `.nvmrc` plus whatever the guard reports. The guard also fails a `setup-node`
+step that pins *nothing*, which would silently inherit the runner default.
+
+Nothing about the published packages changes: `engines.node` stays `>=18.0.0`
+across all 49 of them. That is a promise to users about what ships, independent
+of what CI validates on, and tightening it is a breaking change — left for its
+own decision rather than folded in here.

.changeset/ci-node-eol-guard.md

@@ -0,0 +1,34 @@
+---
+---
+
+ci: fail the Node pin guard when the pinned runtime is out of support (#3825)
+
+`check-node-version` proved all 18 workflows agree on a Node version. It would
+have said `OK` just as cheerfully when all 18 agreed on **Node 20, three months
+after that line went EOL** — which is exactly the state #3825 found the repo in.
+Consistency was only half the invariant; the other half is that the thing they
+agree on is still receiving patches.
+
+The guard now also checks the pin's lifecycle:
+
+- **past EOL → error.** An unpatched runtime is guarding every merge.
+- **within 180 days of EOL → `::warning::`** on the PR, so the bump is scheduled
+  work rather than an emergency. It stays a warning until support actually ends —
+  failing months early would block unrelated PRs.
+- **a major the guard has no dates for → error.** Adopting Node 26 forces you to
+  record its dates rather than silently validating on an unknown runtime.
+
+Dates come from `nodejs/Release` `schedule.json`, hardcoded deliberately: a
+required gate must not depend on the network, and they move once a year.
+
+The success line now reports the runway, which surfaces something worth knowing:
+
+```
+check-node-version: OK (18 setup-node step(s) across 16 workflow(s), all on Node 22).
+  Node 22 is in maintenance; supported until 2027-04-30 (276 days).
+```
+
+**Node 22 entered maintenance on 2025-10-21** — Node 24 has been Active LTS
+since 2025-10-28. Moving to 24 is now a one-line `.nvmrc` edit, and this guard
+will list the workflows to follow. That is a separate decision; nothing here
+forces it.

.changeset/ci-test-completeness-guard.md

@@ -0,0 +1,51 @@
+---
+---
+
+ci: assert every test vitest counted actually ran (#3825)
+
+A vitest worker can die at the process level — a native module segfault, OOM, an
+abort inside a binding. There is no JS error to catch, so the cases that worker
+owned never run and the summary reports only what survived:
+
+```
+Test Files  1 passed (40)
+      Tests  21 passed (401)
+```
+
+That leads with "passed". It is **380 tests short**. #3812 hit exactly this shape
+(17 cases silently skipped, reported as `22 passed (23)`) and it was found by a
+human reading the log closely — which is not a control.
+
+**To be precise about the risk:** the run does exit non-zero, so the gate goes
+red. The failure mode is not a false green, it is **a red that reads like a
+pass** — someone triaging sees "passed" and a plausible file count and concludes
+one file flaked, rather than that a fifth of the suite never executed. This turns
+that into a specific, quantified error naming the package and the shortfall. It
+also covers the genuinely dangerous variant, where a crash lands somewhere that
+does not propagate a non-zero exit at all.
+
+`scripts/check-test-completeness.mjs` reads a saved `turbo run test` log and
+asserts, per package, that the tallies (`passed | skipped | failed`) sum to the
+declared total. Reading the log rather than wrapping vitest means no change to
+the 60+ per-package vitest configs.
+
+Wired into `ci.yml`'s Test Core (both the PR and push steps) and both Dogfood
+shards, each as a separate `if: always()` step so it runs **when the suite
+failed** — that is when it earns its keep. A red suite plus a green completeness
+check means real test failures; a red suite plus a red completeness check means a
+worker died.
+
+Two details that are load-bearing rather than incidental:
+
+- The test steps now `tee` their output, and `set -o pipefail` goes with it.
+  GitHub runs these with `bash -e`, which does **not** set pipefail, so
+  `turbo … | tee` would report *tee's* exit status and a failing suite would go
+  green. Verified both ways: with pipefail the step exits 7, without it exits 0.
+- Zero summaries in the log is a **pass with an explicit note**, not a silent
+  one — `turbo run test --affected` legitimately runs nothing when a PR touches
+  no package.
+
+Validated against the real logs from the #3830 Node 20/22 comparison rather than
+synthetic fixtures: the Node 22 log passes (`68 packages, 16678 declared and all
+16678 accounted for`), and the Node 20 log fails, naming `@objectstack/driver-sql`
+and its 380 missing tests.