Merge origin/main into claude/global-actions-unreachable-rw7hpk

Integrates two main-side changes that landed mid-flight, both touching the
same contract this branch changes:

- ADR-0110 (#3958): action identity is `name`, undeclared executables refuse.
  Its new tests asserted the pre-#3962 double envelope; updated to the single
  wrap, and its handler-rejection case ("NOT a 404 routing miss") now asserts
  the 400 — the distinction it exists to pin is 400-vs-404, unchanged.
- #3971: the dispatcher's `error.code` is the semantic string and `details.code`
  is PROMOTED into it. Assertions on `error.details.code` moved to `error.code`;
  `fields` stay in `details`.

Conflicts resolved in ui/actions.mdx (kept main's name-vs-target paragraph +
this branch's "failures speak HTTP" contract) and the type-dispatch test
(kept main's ADR-0110 undeclared/valve/degraded cases, adjusted the valve
run's envelope to the single wrap).

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

Author: claude

.changeset/adr-0110-action-declaration-admission.md

@@ -0,0 +1,36 @@
+---
+'@objectstack/runtime': major
+'@objectstack/objectql': minor
+'@objectstack/metadata': minor
+---
+
+**ADR-0110 — an action's identity is its `name`, and anything executable over a
+governed surface must have a declaration.**
+
+`POST /api/v1/actions/:object/:action` resolved the DECLARATION from the URL
+segment as a `name` but dispatched the HANDLER using that same segment as a
+registry key. For a target-bound action (`{ name: 'complete_task', target:
+'completeTask' }`) those are different strings, so the two documented callers
+each worked on exactly the half the other broke: the documented curl resolved
+the declaration then 404ed, while the Console's `target`-addressed call
+dispatched fine and resolved no declaration — silently skipping the ADR-0066 D4
+capability gate and the ADR-0104 param contract (#3935).
+
+- **D1/D2** — identity is always the declarative `name`; the handler key is
+  derived from the resolved declaration through a rotation now shared with the
+  MCP `run_action` bridge (`resolveActionHandlerKeys`, `executeRegisteredAction`).
+  The REST route previously rotated only the object key, never the handler key.
+- **D3 (breaking)** — declaration resolution is a trichotomy. A genuinely
+  undeclared handler is **refused (404)** with the `defineAction` to add, rather
+  than executed ungated with system privileges; an unreachable metadata plane is
+  a **503** rather than a silent ungating (`MetadataManager.loadDiagnosed` tells
+  a clean miss from an outage). `OS_ALLOW_UNDECLARED_ACTIONS=1` is the migration
+  valve — it warns on every invocation and is removed in 18.
+- **D5** — `reconcileActionRegistrations` plus `ObjectQLEngine.listRegisteredActions`
+  power a `kernel:ready` inventory logging every registered-but-undeclared
+  handler (refused at dispatch) and every declared script action bound to no
+  handler — the ADR-0078 converse, mechanised.
+- **D6** — security-gate strictness is opt-**out** (`OS_ALLOW_*`), never opt-in.
+
+Apps whose actions are all declared need no changes beyond gaining enforcement
+of the `requiredPermissions` they already declared.

.changeset/adr-0111-sharing-authorization-face.md

@@ -0,0 +1,43 @@
+---
+"@objectstack/spec": minor
+"@objectstack/plugin-sharing": minor
+"@objectstack/plugin-security": minor
+"@objectstack/rest": minor
+---
+
+fix(sharing)!: the share-management surface gains the authorization layer it never had (ADR-0111 P0, #3902)
+
+Record sharing shipped as a data layer with no authorization of its own: every
+`/data/:object/:id/shares` and `/sharing/rules` route authenticated the caller
+and then ran the service under `SYSTEM_CTX` — any signed-in user could revoke
+anyone's share, enumerate who-can-see-what, write self-grants, and define /
+evaluate org-wide sharing rules. ADR-0111's P0 rulings land here:
+
+- **D1/D2** — `ISharingService.canManageShares(object, recordId, context)`:
+  system, the record's owner, or a holder of Modify All Data (probed via the
+  new fail-closed `ISecurityService.hasWriteBypass`). Enforced in the SERVICE,
+  so every caller is covered; without plugin-security it fails closed to
+  owner-only.
+- **D4** — `revoke` is symmetric with grant, validates the share belongs to the
+  URL's record (`NOT_FOUND` on mismatch), and refuses non-`manual` rows
+  (`CONFLICT` — a rule-materialised grant would be resurrected by the next
+  reconcile).
+- **D5** — `listShares` is management-gated (invisible record → `NOT_FOUND`,
+  visible-but-not-manager → `PERMISSION_DENIED`), and the open
+  `/data/sys_record_share` read surface is self-scoped: non-admin callers see
+  only rows naming them as recipient or grantor.
+- **D6** — the whole `/sharing/rules` surface (list/create/get/delete/evaluate)
+  requires the new **`manage_sharing`** capability (D9; seeded into
+  `admin_full_access`, `manage_platform_settings` honoured as the legacy
+  equivalent), enforced in `SharingRuleService`.
+- **D7** — no inert grants: `recipientType` is narrowed to `user` (the only
+  type any gate enforces), grants on objects the sharing gates never consult
+  (public model, no `owner_id`, bypass, `controlled_by_parent`) fail with
+  `SHARING_NOT_ENABLED` (422), and the manual upsert keys on
+  `(object, record, recipient, source)` so manual and rule rows coexist.
+
+**Breaking** for callers that relied on the missing gate: unauthorized share
+management now fails with 403/404/409/422 instead of silently succeeding, and
+`ISharingService.revoke` gained an optional `scope` parameter. The verb
+boundary (edit ≠ delete, ADR-0111 D3) is NOT in this change — it lands as the
+separate P1.

.changeset/adr-0112-error-code-vocabulary.md

@@ -0,0 +1,4 @@
+---
+---
+
+ADR-0112 (error-code vocabulary decision) — docs only, releases nothing.

.changeset/default-datasource-adopt-seam.md

@@ -0,0 +1,43 @@
+---
+"@objectstack/runtime": minor
+"@objectstack/service-datasource": minor
+"@objectstack/verify": patch
+---
+
+feat(runtime,datasource): the default-datasource connect seam accepts a host driver factory — adopt pre-built instances without forking the verdict (#3826)
+
+ADR-0062 D1's open-core convergence (#3869/#3886) left one structural question
+open: a host whose `default` needs a driver the shared factory cannot build —
+the cloud distribution's `turso`, or an instance pooled BEYOND one kernel (the
+cloud control-plane driver doubles as the proxy base of every environment
+kernel; per-environment drivers are cached across kernel rebuilds) — had only
+two options, both bad: stay on the legacy pre-built `DriverPlugin` path, whose
+connect verdict lives in `ObjectQLEngine.init()` (the second implementation
+#3826 exists to retire), or fork the connect orchestration. Either re-opens the
+#3741 → #3758 drift this whole line of work is about.
+
+Two additive pieces close it:
+
+- **`DefaultDatasourcePlugin` accepts an injected `IDatasourceDriverFactory`**
+  (defaults to the shared open-core factory, byte-for-byte unchanged when
+  omitted). The factory only changes what `create()` returns — the policy-free
+  init connect, `bootCritical` fail-fast, `OS_ALLOW_DRIVER_CONNECT_FAILURE`
+  escape hatch, and the start() replay into retained admin state are identical
+  either way, and the new tests pin that (an adopted instance that cannot
+  connect takes the exact same verdict).
+- **`createPrebuiltDriverFactory(driver, { driverId?, fallback? })`** in
+  `@objectstack/service-datasource` — the "adopt an existing driver" seam the
+  first #3826 pass found missing, landed AS a factory so it composes into the
+  one connect path instead of becoming a second entry point. `create()` returns
+  the SAME instance every call: construction, pooling, and reuse stay host
+  concerns; only the verdict converges. Not for the common case — a `default`
+  expressible as `{ driver, config }` should stay a plain definition.
+
+The `@objectstack/verify` dogfood harness now boots through
+`DefaultDatasourcePlugin` (declared `sqlite-wasm` definition) instead of a
+pre-built `DriverPlugin` — so the dogfood gate exercises the same declared
+-default connect path `objectstack dev`/`serve` use, which is the §Risk
+mitigation ADR-0062 promised ("behind the dogfood gate") and did not yet have.
+The degraded-boot parity guard stays: `ObjectQLEngine.init()`'s verdict is
+still live for the boot re-verification, `DriverPlugin` escape-hatch drivers,
+and the cloud compositions until they converge onto this seam.

.changeset/dispatcher-error-code-is-semantic.md

@@ -0,0 +1,88 @@
+---
+"@objectstack/spec": minor
+"@objectstack/runtime": minor
+"@objectstack/client": patch
+---
+
+fix(runtime,spec)!: the dispatcher's `error.code` is the semantic string it always declared; the HTTP status moves to `httpStatus` (#3842)
+
+`HttpDispatcher.error()` took the HTTP status as its `code` argument and wrote it
+straight into the field `ApiErrorSchema` reserves for a semantic string, so
+`error.code` came back as `400`/`403`/`503` — a number, duplicating the response
+status and occupying the one slot a caller is meant to branch on. The real code
+then had to go somewhere else, and did, three somewhere-elses: `details.code`
+(auth gate, permission denial, anonymous deny), `details.type`
+(project-membership gate), and `error.type` (`routeNotFound`). Four sites, three
+parking spots, because the declared one was full.
+
+**FROM → TO on the wire.** A dispatcher error body
+
+```json
+{ "success": false,
+  "error": { "message": "…", "code": 403, "details": { "code": "PERMISSION_DENIED" } } }
+```
+
+is now
+
+```json
+{ "success": false,
+  "error": { "code": "PERMISSION_DENIED", "message": "…", "httpStatus": 403 } }
+```
+
+| Reading | Was | Now |
+|---|---|---|
+| semantic code | `error.details.code` / `error.details.type` / `error.type` | `error.code` |
+| HTTP status | `error.code` | `error.httpStatus` (or the response status) |
+| context | `error.details` (with the code mixed in) | `error.details` (context only, absent when empty) |
+
+**One-line fix for a direct reader:** replace `body.error.details?.code ??
+body.error.type` with `body.error.code`, and `body.error.code` with
+`body.error.httpStatus`. **SDK callers need no change** — `ObjectStackClient`
+already normalised this (`err.code` semantic, `err.httpStatus` numeric) and still
+reads the old shape, so a client newer than its server is unaffected.
+
+Every code already on the wire moves **verbatim** — `PERMISSION_DENIED`,
+`ROUTE_NOT_FOUND`, `PASSWORD_EXPIRED`, `PROJECT_MEMBERSHIP_REQUIRED`,
+`VALIDATION_FAILED`, `unauthenticated`. This change moves a field; it does not
+rename anything. Reconciling the repo's two code vocabularies is #3841, and this
+leaves it exactly one map and one enum to sweep instead of four parking spots.
+
+A branch with no code of its own is served one derived from the status, via the
+single declared map `HttpStatusErrorCodeMap` / `standardErrorCodeForHttpStatus`
+in `@objectstack/spec/api` (`403` → `permission_denied`, `503` →
+`service_unavailable`, …). Derivation is necessary because `ApiErrorSchema.code`
+is required; drawing it from `StandardErrorCode` keeps a derived code a
+catalogued one rather than an invented string.
+
+**Spec changes:**
+
+- `ApiErrorSchema` gains optional `httpStatus: number` — the precedent is
+  `EnhancedApiErrorSchema.httpStatus`. Additive.
+- `StandardErrorCode` gains `method_not_allowed` and `precondition_required`,
+  the two statuses the runtime returns that the enum could not name. Additive.
+- **Breaking — `DispatcherErrorCode`** was `'404' | '405' | '501' | '503'` (string
+  spellings of HTTP statuses, for matching against the numeric `error.code`). It
+  is now `'ROUTE_NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'NOT_IMPLEMENTED' |
+  'SERVICE_UNAVAILABLE'` — the same four members the removed `error.type` enum
+  declared, moved verbatim. FROM `DispatcherErrorCode.parse('404')` TO
+  `DispatcherErrorCode.parse('ROUTE_NOT_FOUND')`; to match a status, read
+  `error.httpStatus`. TypeScript flags every call site.
+- **Breaking — `DispatcherErrorResponseSchema`**: `error.code` is `z.string()`
+  (was `z.number().int()`), `error.type` is **removed** (folded into `code`), and
+  `error.httpStatus` / `error.details` are declared. This schema is what
+  legitimised the deviation — it declared the opposite of `ApiErrorSchema` for
+  the same field. FROM `{ code: 404, type: 'ROUTE_NOT_FOUND' }` TO
+  `{ code: 'ROUTE_NOT_FOUND', httpStatus: 404 }`.
+
+**Also aligned, because they are the same wire surface:** `dispatcher-plugin`'s
+`errorResponseBase` (the THROWN-error exit) and its inline 404, and the MCP 405.
+`errorResponseBase` previously discarded a thrown error's `.code` outright — it
+had nowhere to put it — so the two exits of one surface disagreed about what a
+caller would see; they now agree. Every body on this surface is built by one
+helper (`packages/runtime/src/error-envelope.ts`), guarded in both directions by
+`error-envelope.conformance.test.ts`: each branch driven and parsed against the
+schema imported from `packages/spec`, plus a source scan so a new branch cannot
+quietly reintroduce a numeric `code` or a `type`-as-code sibling.
+
+This deletes the #3687 pin in `http-dispatcher.test.ts`, which asked to be
+deleted rather than updated once the dispatcher was fixed.

.changeset/empty-state-gate-object-surface.md

@@ -0,0 +1,56 @@
+---
+"@objectstack/spec": patch
+---
+
+chore(spec): the empty-state gate now scans platform-object definitions, where #3896 actually happened
+
+#3945 added a gate requiring any *"empty = permissive"* statement in the spec to
+be classified on purpose. It scanned `packages/spec/src/**/*.zod.ts` — and that
+scope had a hole big enough to miss the bug it was built for.
+
+The sentence that shipped #3896, *"leave empty to share every record"*, was the
+`description` of `sys_sharing_rule.criteria_json`, which lives in
+**`plugin-sharing`**. The gate could not see its own crime scene.
+
+**Now scans `**/*.object.ts` anywhere under `packages/`** — plugins,
+`platform-objects`, `metadata-core`, and the `create-objectstack` templates
+(a starter file is the highest-leverage thing a model copies from). 214 → 290
+files.
+
+**It immediately found a real one.** `sys_user_permission_set.organization_id`
+declares *"NULL = applies in every org context"*: a user↔permission-set grant with
+no org scope applies everywhere. That is deliberate and load-bearing rather than
+an oversight — ADR-0095 D3 / ADR-0068 D2 derive the `platform_admin` posture from
+an **unscoped** `admin_full_access` grant specifically, and an org-scoped grant of
+the same set must not confer it. So the empty state is not merely wider, it is the
+distinguishing input to the highest privilege in the system. Registered `open`
+with that rationale and both enforcement sites cited, which is the point: the
+answer now lives somewhere other than a maintainer's memory.
+
+Three fixes the new surface forced, each a case of the gate being wrong in a way
+that mattered:
+
+- **Repudiated prose no longer fires.** #3929's own comment on `criteria_json`
+  reads *Deliberately NOT "leave empty to share everything"* — the gate flagged the
+  sentence recording why the gate exists. Negation is now handled for the
+  imperative form as well as the token form (`deny-all`), and the escape is
+  deliberately narrow: the negator must be attached to the phrase, not merely
+  present in the line, because a false negative here is a missed over-share.
+- **The owning property is found by nesting, not by a name list.** A field's prose
+  sits in a nested key, so the first attempt answered `description` for every
+  platform-object hit; skipping doc slots then answered `required`, the sibling
+  above it. What separates a field from its own config is indentation, so the
+  resolver now takes the nearest key at a shallower indent.
+- **The property-search window is per-surface.** A platform-object `description:`
+  can sit 15+ lines below its field name; a `.zod.ts` statement sits beside its
+  property. Widening globally would let `.zod.ts` narrative be mis-attributed to a
+  distant property — turning a correct non-failing note into a wrong failure — so
+  `.object.ts` gets a wider window and the schema surface keeps its tight one.
+
+Also makes evidence resolution honest: entries are now parsed with the liveness
+ledger's own `checkEvidence`, so prose around the paths works, several paths can
+be cited, and another repo's path (`objectui: …`) is recorded without being
+resolved here. The README already promised evidence resolved "like the ledger's";
+a single raw-path `existsSync` quietly did not.
+
+6 new unit tests (32 total). No runtime behaviour changes.

.changeset/find-data-wire-context.md

@@ -0,0 +1,46 @@
+---
+"@objectstack/metadata-protocol": patch
+---
+
+fix(metadata-protocol): findData must not take its execution context from the request (#3960)
+
+Came out of the #3946 sweep's leftover question — whether `expand`'s "advanced
+usage" (a caller-supplied `Record<string, QueryAST>` whose sub-ASTs each carry an
+`object`) is a cross-object read channel. **It is not**, and that needs saying
+because the answer is load-bearing: `expandRelatedRecords` takes its target from
+the parent schema (the expand KEY must be a real `reference` field; the sub-AST's
+`object` is never read), re-enters `engine.find` so the referenced object's RLS +
+FLS both run, `$and`-merges a nested `where` instead of spreading it over the id
+filter, and caps depth. No change needed there.
+
+What the investigation did turn up is one layer down. `findData` built its engine
+options as `{ ...request.query }` and then assigned `context` from
+`request.context` **conditionally**:
+
+- `request.query` is the caller's raw bag on every ingress — the REST
+  `POST /data/:object/query` route passes `req.body` straight in as `query`;
+- `context` sits in the known-params set, so it was not swept into the
+  implicit-filter bucket either — it survived the spread untouched;
+- so when no server context resolved, the caller's `context` *became* the
+  operation's execution context.
+
+Everything hangs off that value. plugin-security's middleware opens with
+`if (opCtx.context?.isSystem) return next()` — the entire RLS / FLS / CRUD chain
+skipped — and `__expandRead: true` collects the #2850 waiver on the object-level
+CRUD gate. Neither is ever schema-stripped on the read path:
+`ExecutionContextSchema.parse` runs only in `engine.createContext`, which reads
+do not use.
+
+Route-level `enforceAuth` is what kept this unreachable: anonymous data requests
+are refused unless a deployment sets `requireAuth: false`. That makes it a
+fail-OPEN default rather than a live exploit — and not something the protocol
+should delegate upward. `findData` now drops any inbound `context`
+unconditionally before the assignment, so the execution context can only come
+from `request.context`.
+
+Verified end-to-end at the protocol layer (a forged
+`{ isSystem, userId, __expandRead }` reached `engine.find` verbatim before, is
+dropped after). The anonymous HTTP reachability half is NOT verified — see #3960
+for exactly what was and was not reproduced. No caller regresses: the only
+in-repo builder of these args (`rest/src/import-runner.ts` `findArgsBase`) passes
+`context` at the top level, never inside `query`.

.changeset/migrate-plan-lists-datetime-convergence.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/driver-sql": minor
+"@objectstack/cli": patch
+---
+
+fix(cli,driver-sql): `os migrate plan` lists the datetime storage convergence (#3954)
+
+The datetime canonicalisation (#3912/#3942) added two steps to `initObjects`'
+physical path: a row-rewriting backfill on SQLite and a `TIMESTAMP` →
+`DATETIME(3)` column rebuild on MySQL. Both already respected the DDL deferral,
+so `plan` performed neither and `apply` performed both — the behaviour was never
+wrong. The reporting was.
+
+`PendingSchemaWork` could only express `create_table` / `add_columns`, so an
+operator saw a plan listing two added columns, confirmed it, and `apply`
+additionally rewrote every row of a datetime column — or took a metadata lock to
+rebuild one on a large table. The plan promises to show what apply will do.
+
+- `PendingSchemaWork.kind` gains `normalize_datetime_storage` and
+  `widen_datetime_columns`, plus an optional `rows` carrying how much data the
+  step touches: row-writes for the backfill, the table's size for the rebuild —
+  the number that decides "now" versus "in a maintenance window".
+- `previewDeferredSchemaWork()` measures both without performing either, reusing
+  the exact predicate each migration uses (the backfill's whole `WHERE`, the
+  widening's own `information_schema` filter) so the plan and the apply cannot
+  name different sets. A probe that cannot run is swallowed to "unlisted", never
+  to a failed plan.
+- The CLI renders them under their own heading rather than folding them into the
+  additive section, whose "created when you apply" framing carries an implicit
+  promise that the work is never data-losing. `summarizePendingSchemaWork` — the
+  line read just before typing `y` — never omits in-place work.