Merge origin/main into claude/implementation-accuracy-audit-eavdgx

Bring the docs-audit branch up to date with main (29 commits) before merge.

Conflict resolutions:
- content/docs/automation/flows.mdx: took main's newer run-history paragraph
  (sys_automation_run durable history / bounded step log) which superseded this
  branch's audit wording of the same section.
- content/docs/references/automation/meta.json: regenerated; added main's new
  `time-relative-trigger` schema to the automation "Flow & Execution" sidebar
  grouping in build-docs.ts. `gen:docs --check` green (254 files in sync).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012urEihGTAsQP2xizAqfCwt

Author: claude

.changeset/adr-0099-p1-layer0-reads-rung.md

@@ -0,0 +1,9 @@
+---
+'@objectstack/plugin-security': patch
+---
+
+ADR-0099 P1 (#3211 M2): the Layer 0 cross-tenant exemption gate now reads the carried `ctx.posture` rung (#2956) as authoritative, with the platform-admin capability probe demoted to a fallback for resolver-less contexts (delegated-admin bridge, sharing service, `getReadFilter`). The read and write (insert/update post-image) tenant checks share one decision (`computeLayeredRlsFilter`), so they cannot drift. A probe↔rung disagreement logs a defect breadcrumb and enforces the narrower rung verdict.
+
+**Behavior change (security narrowing, multi-org / `@objectstack/organizations` only):** a principal whose carried rung is not `PLATFORM_ADMIN` no longer crosses the tenant wall on private / platform-global / better-auth-managed objects, even when its resolved permission sets carry a platform-exclusive capability. Two shapes are affected: (a) a **scoped** `admin_full_access` grant (`sys_user_permission_set.organization_id` non-null), and (b) a custom set granting a platform capability (e.g. `studio.access`) piecemeal alongside a superuser bit. Both are now walled to their own org — the fail-safe direction (the carried rung is a strict subset of the probe). Single-org / env-per-database deployments are unaffected (Layer 0 is inert).
+
+**Upgrade check:** before upgrading, scan `sys_user_permission_set` for `admin_full_access` rows with a non-null `organization_id`, and custom permission sets whose `systemPermissions` intersect `{manage_metadata, manage_platform_settings, studio.access, manage_users}`. To restore cross-tenant operator access for such a principal, grant the **unscoped** `admin_full_access` instead. The `[authz/ADR-0099]` warn log names any principal hitting the divergence at runtime.

.changeset/adr-0099-p2prime-two-axis-cells.md

@@ -0,0 +1,5 @@
+---
+'@objectstack/plugin-security': patch
+---
+
+ADR-0099 P2′ (#3211 M3′): pin the two-axis Amendment in the authz matrix. The original P2 (collapse the Layer 1 tier onto posture) was rejected — Layer 1's tier input is the per-object super-bit, a per-principal × per-object delegation primitive posture cannot represent. New cells pin: seeded-face agreement (seeded super-bit holders are already ≥ TENANT_ADMIN), the load-bearing delegation cell (a MEMBER with a delegated per-object `viewAllRecords`/`modifyAllRecords` short-circuits Layer 1 yet stays walled by Layer 0 — the auditor pattern), invariant I7 (the scope axis never crosses a boundary posture has not opened), and the contrast that the bit is a real grantable capability, not conditionally inert. Test-only; zero behavior change.

.changeset/cross-object-batch-authz-hardening.md

@@ -0,0 +1,35 @@
+---
+'@objectstack/rest': patch
+'@objectstack/spec': minor
+---
+
+fix(rest): gate the cross-object transactional batch by the same per-object API rules as single-record writes (#1604)
+
+The `POST {basePath}/batch` route (issue #1604 / ADR-0034) wraps N cross-object
+create/update/delete ops in one engine transaction, but it skipped the
+per-object API-exposure gate every single-record route applies — an
+authenticated caller could write to an `apiEnabled: false` object, or run an
+operation outside an object's `apiMethods` whitelist, straight through the batch
+surface (ADR-0049 / #1889 — the same "declared ≠ enforced" hole closed for the
+generic write path in #3220 / #3213).
+
+The route now:
+
+- validates the body against a new `CrossObjectBatchRequestSchema`
+  (`@objectstack/spec/api`, Zod-First) — a malformed op, an unknown action, or a
+  missing `object` is a `400` instead of a `500`;
+- enforces `enable.apiEnabled` / `enable.apiMethods` for **every** op (metadata
+  fetched once, each distinct `(object, action)` checked) BEFORE opening the
+  transaction — `404 OBJECT_API_DISABLED` / `405 OBJECT_API_METHOD_NOT_ALLOWED`;
+- requires an `id` for `update` / `delete` (`400`);
+- rejects an unresolvable `{ $ref }` with `400 BATCH_UNRESOLVED_REF` instead of
+  silently writing a `null` FK;
+- rejects an explicit `atomic: false` (`400 BATCH_NOT_ATOMIC`) rather than
+  silently applying atomically — non-atomic per-object batches stay on
+  `POST /data/:object/batch`.
+
+`enforceApiAccess` is refactored to share the pure `apiAccessDenialFromEnable`
+check + a `loadObjectItems` helper with the batch route (single-record behavior
+unchanged). Adds `rest-batch-endpoint.test.ts` — the REST-boundary coverage
+ADR-0034 flagged as missing (commit, `$ref`, rollback surfacing, API-access
+denial, request validation).

.changeset/drill-range-datetime-tz.md

@@ -0,0 +1,25 @@
+---
+'@objectstack/core': minor
+'@objectstack/service-analytics': minor
+---
+
+feat(analytics): scope a datetime date-bucket drill to the reference-tz midnight instants (#1752 follow-up)
+
+Closes the one gap left by the initial #1752 change: a `datetime` date dimension
+bucketed under a **non-UTC reference timezone** previously fell back to a superset
+drill (its bucket boundary is that tz's midnight *instant*, which `YYYY-MM-DD`
+calendar bounds can't express).
+
+- **`@objectstack/core`** adds `zonedDateStartToUtcMs(ymd, tz)` — the UTC instant
+  at which a calendar day begins in a reference timezone (the inverse of
+  `calendarPartsInTz`). DST-safe: the offset is read from the platform tz
+  database via `Intl`, with a two-pass resolution for the rare offset-boundary
+  case; an unset/`'UTC'`/invalid zone returns plain UTC midnight.
+- **`@objectstack/service-analytics`** now emits `drillRanges` bounds per the
+  field's temporal type (ADR-0053): a `datetime` field → ISO **instant** bounds
+  at the reference tz's midnight (works under any tz, incl. DST); a `date` field
+  → `YYYY-MM-DD` calendar bounds (tz-naive, exact under any tz). An unknown field
+  type is still emitted only under UTC and omitted (superset) under a non-UTC tz.
+
+No objectui change is needed — the client already forwards whatever bound values
+the server sends into the drill filter and the `filter[field][gte|lt]` URL.

.changeset/field-form-summary-subfields.md

@@ -0,0 +1,16 @@
+---
+'@objectstack/spec': patch
+---
+
+fix(spec): declare `summaryOperations` sub-fields in the Field metadata form (#3257)
+
+`fieldForm` (the registered metadata form for editing a Field) previously
+declared `summaryOperations` as a bare `composite` with no sub-fields, so a
+protocol-driven renderer had to fall back to a raw JSON editor. It now declares
+the inner shape explicitly — `object` (`ref:object`), `function` (select),
+`field`, `relationshipField`, and `filter` (bound to `widget: 'filter-condition'`)
+— mirroring the `summaryOperations` Zod schema and surfacing the roll-up `filter`
+added in #1868. Also gates the block to `data.type == 'summary'`.
+
+Small step toward #3257 (making the Studio field designer metadata-driven rather
+than hand-coded); the live objectui inspector already edits these fields.

.changeset/hook-nested-write-timeout.md

@@ -0,0 +1,24 @@
+---
+'@objectstack/runtime': patch
+---
+
+fix(runtime): honor a hook body's declared `timeoutMs` so nested cross-object writes aren't clamped to 250ms (#1867)
+
+Hook bodies run in the QuickJS sandbox with a default 250ms timeout. The runner
+folded that engine default straight into `Math.min(...)` when resolving the
+effective timeout, so it *always* dominated for hooks: a body that declared a
+larger `timeoutMs` (the spec permits up to 30_000ms — `ScriptBody.timeoutMs`) to
+give a legitimate nested write — "when a child changes, update the parent" —
+room to settle was silently clamped back to 250ms and killed mid-flight. The
+declared knob was never enforced.
+
+The engine default is now a FALLBACK used only when no explicit timeout is
+supplied, not a hard ceiling. An explicit `body.timeoutMs` (and/or an enclosing
+hook/action timeout) is honored; when both are present the smaller wins. Bodies
+that declare nothing still get the 250ms hook / 5000ms action default, and a
+body may still LOWER its own timeout below the default.
+
+This clears the last reliability blocker for nested cross-object writes from
+hooks — the sandbox crash itself (`memory access out of bounds`) was already
+fixed by the deferred-promise host-call model — so header/rollup fields no
+longer need denormalized, hand-maintained workarounds.

.changeset/mcp-dev-connect-hint.md

@@ -0,0 +1,13 @@
+---
+'@objectstack/cli': patch
+---
+
+feat(cli): surface the MCP endpoint in the server-ready banner (#3167)
+
+The MCP server (`/api/v1/mcp`) is a default-on core capability, but nothing in
+the `os dev` / `os serve` boot output pointed to it — a developer had to already
+know it was there to connect an AI client. The server-ready banner now prints
+the MCP URL and the `SKILL.md` pointer whenever the surface is enabled
+(`isMcpServerEnabled()`, the same switch that auto-loads the plugin and gates
+the route), so an agent can operate the running app straight from the dev loop.
+Hidden when `OS_MCP_SERVER_ENABLED=false`.

.changeset/mcp-stdio-principal-admission.md

@@ -0,0 +1,26 @@
+---
+'@objectstack/mcp': minor
+---
+
+feat(mcp)!: stdio transport requires an API-key principal — fail-closed, no unscoped bridge (ADR-0101, #3246)
+
+The long-lived MCP **stdio** transport no longer reads data unscoped. It now runs
+under an env-supplied identity, closing the platform's last identity-less
+execution surface (the `mcp-stdio-authority` conformance row graduates
+`experimental` → `enforced`).
+
+- `OS_MCP_STDIO_API_KEY=osk_...` supplies the stdio identity, resolved through
+  the SAME `@objectstack/core` verify + authorization chain as the HTTP/REST
+  surfaces; the `record_by_id` resource reads via `ql.find(obj, { where:{id},
+  context })`, so RLS/FLS/tenant apply exactly as on REST `/data`. Re-resolved
+  per read, so a revoked/expired key stops working on a live session.
+- **Fail-closed** — enabling stdio auto-start (`OS_MCP_STDIO_ENABLED=true` /
+  `autoStart`) without a resolvable key throws and refuses to start. There is no
+  unscoped fallback and deliberately no `system` bypass; full authority is a key
+  minted on a platform-admin or dedicated service identity.
+
+**BREAKING (stdio auto-start only):** previously `OS_MCP_STDIO_ENABLED=true`
+(or the plugin `autoStart` option) started stdio with full, unscoped authority
+and no credential. It now requires `OS_MCP_STDIO_API_KEY`; without it, boot
+fails closed. The default-on HTTP surface and any deployment that never enables
+stdio auto-start are unaffected.

.changeset/mcp-stdio-switch-split-and-dev-connect-hint.md

@@ -0,0 +1,28 @@
+---
+'@objectstack/types': minor
+'@objectstack/mcp': minor
+'@objectstack/cli': minor
+'create-objectstack': patch
+---
+
+feat(mcp): decouple the stdio auto-start switch from the HTTP surface + surface the MCP endpoint on `os dev` boot (#3167)
+
+The MCP HTTP surface (`/api/v1/mcp`) and the long-lived stdio transport used to
+share one env var: `OS_MCP_SERVER_ENABLED=true` turned the HTTP surface on **and**
+silently auto-started the stdio transport — which bridges the raw metadata service
++ data engine with no per-request principal (unscoped). An operator setting it to
+"make sure MCP is on" got an unscoped transport as a side effect.
+
+- **`@objectstack/types`** — new `resolveMcpStdioAutoStart()`. Stdio auto-start is
+  now its own switch, `OS_MCP_STDIO_ENABLED` (default off); `OS_MCP_SERVER_ENABLED`
+  governs only the HTTP surface. The legacy `OS_MCP_SERVER_ENABLED=true` trigger
+  still starts stdio for one release, flagged as deprecated. `=false` is unchanged
+  (it only ever gated HTTP).
+- **`@objectstack/mcp`** — `MCPServerPlugin.start()` gates stdio on the new switch
+  and logs a one-time deprecation warning when started via the legacy alias.
+- **`@objectstack/cli`** — `os dev` now prints the MCP endpoint, the agent-skill
+  URL, and a ready-to-paste `claude mcp add` command on boot (gated on the HTTP
+  surface being on), so the "an agent operates the app it's building" loop is
+  discoverable at dev time.
+- **`create-objectstack`** — the blank scaffold README documents that the app is
+  itself an MCP server (the serve side), distinct from the consume-side connector.

.changeset/metadata-list-package-aware-dedup.md

@@ -0,0 +1,19 @@
+---
+'@objectstack/metadata-protocol': patch
+---
+
+fix(metadata-protocol): unscoped metadata list dedupes package-aware, not by bare name (ADR-0048 #1828)
+
+`getMetaItems` merged registry items, `sys_metadata` overlay rows, draft-preview
+rows, and MetadataService items into `Map`s keyed by bare `name`, so two installed
+packages shipping the same `type/name` (e.g. `page/home`) collapsed to one row
+(last-write-wins) on an unscoped `GET /meta/:type` whenever either package had an
+overlay — and the frontend prefer-local resolution, which reads that list, could
+no longer tell the two packages' rows apart.
+
+The three merge sites (plus the env/org pre-merge) now key by `(package, name)`,
+mirroring `getMetaItem`'s scoped-then-global-fallback resolution: colliding rows
+stay distinct each with its own `_packageId`, a package-less (env-wide) overlay
+still wins over the single artifact it customizes (ADR-0005 precedence and
+single-package behaviour unchanged), and the registry-hydration artifact graft is
+scoped to each row's own `package_id` so a collision no longer mislabels provenance.