Merge origin/main — drop this branch's locks_record, keep main's lock_record

main shipped the same feature first. #3815 (`a6c3f3806`, #3814/objectui#2902)
landed `ApprovalRequestRow.lock_record`, computed `cfg?.lockRecord !== false`
off the `node_config_json` snapshot — byte-for-byte the rule this branch's
`locks_record` computes, from the same snapshot, with the same default.

Only the test file collided textually. `approval-service.ts` and the spec
contract auto-merged *clean*, which is the dangerous part: the result declared
both fields, so `GET /api/v1/approvals/requests` would have shipped one policy
under two names and every client would have had to guess which to read.

Resolved toward main: `lock_record` is already merged and released in a
changeset, so dropping it would be a breaking change layered on a duplicate.
Removed from this branch:

  - `locks_record` on `rowFromRequest` (plugin-approvals)
  - `locks_record?: boolean` on `ApprovalRequestRow` (spec contract)
  - its 3 tests — main's 3 `lock_record` tests are a superset, covering
    `openNodeRequest` / `listRequests` / `getRequest` on all three cases
  - the `locks_record` half of the changeset, which main's
    `approvals-expose-lock-record.md` already describes

The changeset is rewritten to the half that is still this branch's own
(`droppedFields` on `POST /batch`) and renamed to match; `plugin-approvals`
comes off its bump list, because after this resolution the branch no longer
touches that package. #3835 (batch creates through the create ingress) is
untouched and keeps its own changeset.

Console follow-up, NOT covered here: objectstack-ai/objectui#2914 is still open
and reads `locks_record`. It must be repointed at `lock_record` or the band
falls back to "assume locked" — the exact bug #3794 filed.

Verified after resolution: build 71/71 · spec 6836 · rest 419 (incl. all 5 new
batch tests) · plugin-approvals 318 (incl. main's 3 `lock_record` tests) ·
metadata-protocol 71 · no generated-artifact drift.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: os-zhuang

.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-d8-delegated-admin-org-role.md

@@ -14,8 +14,8 @@ subtree. That gate is implemented, unit-proven and reachable — but no principa
 could reach it in a state where it did anything:
 
 - better-auth grants `invitation: ["create"]` to `owner` and `admin` only
-  (`memberAc` holds `invitation: []`, and roles registered through
-  `additionalOrgRoles` inherited that empty statement);
+  (`memberAc` holds `invitation: []`, which every other registered role
+  inherits);
 - under a wall-enforcing posture, owners and admins are auto-elevated to
   `organization_admin` (`auto-org-admin-grant.ts`), which carries the wildcard
   `modifyAllRecords` that makes `isTenantAdmin()` true — and the gate

.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/ai-surface-affinity-lint.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/lint": minor
+"@objectstack/spec": patch
+---
+
+feat(lint): `validate-ai-surface-affinity` — skill ↔ agent surface affinity is now linted (#3820)
+
+An agent binds a product surface (`'ask'` | `'build'`, ADR-0063 §1) and a skill
+declares which surface it belongs to (`'ask'` | `'build'` | `'both'`, §3). The
+runtime refuses an incompatible binding with a **load error at chat time** —
+after parse, validate, and deploy all passed cleanly. The new rule reports that
+contradiction statically, and joins `REFERENCE_INTEGRITY_RULES`, so
+`objectstack validate`, `lint`, and `compile` all pick it up with no CLI
+changes.
+
+Scope is deliberately narrow (zero false positives by construction): only
+bindings where **both** the agent and the skill are declared in the same stack
+are checked. `agent.skills[]` names that don't resolve in-stack (kernel skills
+are runtime-registered and statically invisible) are skipped — resolving those
+namespaces is #3820 D0/D2, decided by ADR-0109 (Proposed).
+
+The spec side is doc-truth only, no schema shape changes:
+
+- `stack.agents` is documented as **platform-internal** (ADR-0063 §2 — the
+  kernel ships exactly two agents; third parties extend via skills), replacing
+  prose that still described the withdrawn ADR-0040 per-app-copilot model.
+- `stack.tools` is documented as declaration-only pending the ADR-0109 tool
+  authoring model.
+- `app.defaultAgent` is re-documented as a surface-binding knob (`'ask'`
+  implicit / `'build'` for authoring surfaces), not a custom-agent slot.
+- `SkillSchema` now states that a per-skill `permissions` field deliberately
+  does not exist (ADR-0049) — authoring one is silently stripped; access is
+  gated by `agent.access` / `agent.permissions` and per-tool authz.

.changeset/analytics-cube-gate-and-error-leak.md

@@ -0,0 +1,71 @@
+---
+"@objectstack/types": minor
+"@objectstack/service-analytics": minor
+"@objectstack/runtime": minor
+"@objectstack/rest": patch
+---
+
+fix(analytics,runtime,types): gate cube auto-inference on object existence; stop the dispatcher boundary returning raw SQL (#3867)
+
+Two independent defects on the `/analytics` surface, found while verifying #3770
+against a real server. On an authenticated CRM dev server, before this change:
+
+```
+POST /api/v1/analytics/query {"cube":"sqlite_master","measures":["count"],"dimensions":["type"]}
+→ 200 {"rows":[{"type":"index","count":262},{"type":"table","count":71},{"type":"view","count":1}],
+       "sql":"SELECT type AS \"type\", COUNT(*) AS \"count\" FROM \"sqlite_master\" GROUP BY type"}
+```
+
+That is SQLite's internal schema table — never a registered object — read
+successfully through the analytics endpoint. Not merely "the name reaches the
+driver and errors": **any table the connection can see was readable.**
+
+**① The cube name reached the driver as a table name.** `AnalyticsService.ensureCube`
+auto-infers a minimal Cube when none is registered, with `cube.sql = <the queried
+name>`. That is the intended "metric over an object" path — an `object-metric` KPI
+widget queries `crm_account` with no authored Cube — but it accepted *any* string,
+so the endpoint could aggregate over an arbitrary physical table. The
+analytics-side twin of the data-path gap #3770 closed, and it was not covered by
+that fix: #3770 gated the protocol's `analyticsQuery`, which is the *degraded
+fallback*; a deployment with `@objectstack/service-analytics` installed runs the
+real engine instead (`ctx.replaceService`).
+
+Inference is now gated on the same schema registry the data path consults, via a
+new optional `AnalyticsServiceConfig.isRegisteredObject` that `plugin.ts` wires
+from the `data` engine's `getObject`. Three-way rule: a registered Cube runs
+untouched (its `sql` is whatever it declares); an unregistered name that IS an
+object still auto-infers exactly as before; neither → `CUBE_NOT_FOUND` / 404
+raised before any SQL exists, naming both ways to make the request valid. With no
+probe configured the gate stands down and warns once — the same tiering #3770
+took for a missing registry. `generateSql` (`/analytics/sql`) is gated too.
+
+**② The dispatcher boundary returned `err.message` verbatim.** `errorResponseBase`
+is the single error exit for *every* route the dispatcher plugin mounts —
+`/analytics`, `/packages`, `/i18n`, `/storage`, `/automation`, `/auth`,
+`/notifications`, `/mcp`. `@objectstack/rest` has guarded its data routes against
+driver dumps forever (`mapDataError`); this boundary guarded nothing, so any
+driver error on any of those routes shipped its SQL to the client. Unlike ①, this
+half is unconditional — it does not depend on the cube being invalid.
+
+The leak heuristic moved out of `rest-server.ts` into `@objectstack/types` as
+`looksLikeInternalErrorLeak` (both packages already depend on it) and is now
+applied at both boundaries — one predicate, one place to widen when a new
+dialect's phrasing shows up. `mapDataError`'s behaviour is unchanged. At the
+dispatcher it applies **only to 5xx**: a 4xx message is a deliberate
+business/validation answer and must reach the caller intact. Sanitising costs no
+diagnostics — the untouched error still reaches `errorReporter` through the
+existing `__obsRecordedError` side-channel.
+
+**Also fixed in the same function:** `errorResponseBase` read only
+`err.statusCode`, while domain errors across this codebase carry `status` (and
+`HttpDispatcher.errorFromThrown` already reads `status` first). Every deliberate
+4xx thrown through a dispatcher route — including #3770's `OBJECT_NOT_FOUND` on
+the analytics fallback path — was rendered as a **500**. It now reads `status`
+then `statusCode`.
+
+**Behaviour change.** `/analytics/query` and `/analytics/sql` return 404
+`CUBE_NOT_FOUND` for a cube that is neither registered nor a registered object;
+previously the name was passed to the driver. Dashboards and KPI widgets pointed
+at real objects or authored cubes are unaffected. A 5xx on a dispatcher route
+whose message looks like a driver dump now reads `Internal server error` — check
+server logs or your error reporter for the original.