merge: main into claude/issue-3957-review-8c0daf (2nd) — regenerate the api reference

Only conflict was `content/docs/references/api/errors.mdx`, an AUTO-GEN file that
both sides touched: main through #4054's authoring-key sweep, this branch through
`FieldErrorSchema.label`. Took main's copy and re-ran `gen:schema && gen:docs`
rather than hand-merging a generated artifact.

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

Author: baozhoutao

.changeset/adr-0114-field-errors-rename.md

@@ -0,0 +1,30 @@
+---
+"@objectstack/spec": major
+---
+
+feat(spec)!: `EnhancedApiError.fieldErrors` → `fields`, tombstoned (ADR-0114 D4, #3977)
+
+Completes ADR-0114 D4, which the field-level catalog PR (#4035) decided but left
+unexecuted because retiring an authorable key needs its own sequence.
+
+**FROM → TO:** `EnhancedApiError.fieldErrors` → `EnhancedApiError.fields`. The array
+and its element shape are unchanged — only the property name.
+
+The wire has always carried `fields`: the validators, import coercion,
+`validation-failure.ts`, `@objectstack/client` and the console's field-error
+extractor all say `fields`. `fieldErrors` was declared and emitted by nobody, so
+anyone reading `error.fieldErrors` was reading a field no server sent — ADR-0078's
+silently-inert declaration, sitting on the error envelope.
+
+**The old key is tombstoned, not deleted.** `EnhancedApiErrorSchema` is not
+`.strict()`, so a plain removal would let a producer still writing `fieldErrors`
+parse clean and lose the per-field detail — a validation failure that mentions no
+field. Writing it now fails with the rename prescription instead
+(`retiredKey()`, ADR-0104).
+
+**Migration:** read `error.fields`. There is nothing to run: this is a response
+envelope, so no stack, example or template carries the key and `os migrate meta`
+has no source to rewrite. The change is recorded as a semantic chain entry
+(`enhanced-api-error-field-errors-renamed`) with its reason and acceptance
+criterion, which is what reaches the generated upgrade guide and the
+`spec_changes` MCP tool.

.changeset/analytics-timedimension-projection.md

@@ -0,0 +1,19 @@
+---
+"@objectstack/service-analytics": patch
+---
+
+fix(analytics): project a `timeDimensions` bucket into the result rows and fields (#4033)
+
+An analytics query that buckets by `timeDimensions` alone grouped correctly —
+the echoed SQL read `date_trunc('month', due_date) AS "due_date"` — but the row
+mapper and `buildFieldMeta` both enumerated `query.dimensions` only, so the
+bucket never reached the caller: rows carried just the measures and `fields`
+never mentioned the dimension. A trend chart got N values and no x-axis. The
+same query written with `dimensions: ['due_date']` was unaffected, which is why
+it went unnoticed.
+
+Grouping, row mapping and field metadata now derive the projected set from one
+`projectedDimensions()` helper — `dimensions` plus every *granular*
+`timeDimensions` entry not already among them. A `timeDimensions` entry without
+a granularity contributes only its `dateRange` predicate and stays out of the
+projection, so no phantom column is declared.

.changeset/close-out-sweep-inert-keys.md

@@ -0,0 +1,36 @@
+---
+"@objectstack/spec": major
+---
+
+refactor(spec)!: the #3896 close-out sweep — fourteen inert authoring keys leave the surface
+
+The enforce-or-remove worklist across the remaining metadata types, each key
+tombstoned at its schema with the prescription (`retiredKey`) and stripped by
+a protocol-17 conversion (`os migrate meta` rewrites sources):
+
+- **action** `shortcut` / `bulkEnabled` — no keydown path ever dispatched a
+  shortcut; the multi-select toolbar reads the view's `bulkActions`.
+- **flow** `active` / `template`, node `outputSchema`, errorHandling
+  `fallbackNodeId` — `active: false` never stopped a flow (`status` is the
+  enforced lifecycle; the default even read as disabled while the engine
+  treated unset as enabled); faults route via per-node fault edges.
+- **view** list `responsive` / `performance`, form `defaultSort` / `aria` —
+  no renderer read any of them. List `aria`/`data` stay live, and **form
+  `data` survived the sweep**: the removal attempt broke the build —
+  `defineForm` writes `data.provider='schema'` onto every metadata form —
+  which re-verified the entry; its ledger verdict is corrected instead.
+- **dashboard** `aria` / `performance`, widget `performance` (+ the orphaned
+  `PerformanceConfigSchema`) — no renderer applied them; virtual scrolling is
+  the live top-level `virtualScroll`.
+- **agent** `knowledge` (+ `AIKnowledgeSchema`) — declaring sources/indexes
+  never scoped retrieval: `search_knowledge` takes `sourceIds` from the LLM's
+  tool-call arguments. The protocol-17 `topics`→`sources` rename is absorbed
+  into the removal pre-release.
+- **skill** `triggerPhrases` — phrases were never matched; activation is
+  `triggerConditions` ∩ the agent's `skills[]` allowlist.
+
+Docs-shaped annotation fields (`hook.label`/`description`, `flow.description`)
+are deliberately KEPT and so noted in the ledger — they document intent for
+the next reader and are exempt from enforce-or-remove. The stale report
+`aria`/`performance` ledger entries (schema already clean) are deleted as
+hygiene.

.changeset/cross-object-batch-501-code.md

@@ -0,0 +1,22 @@
+---
+"@objectstack/rest": patch
+---
+
+fix(rest): give the bare 501 error exits a machine `code` (#4067)
+
+Most REST error exits already carry a typed `code` (`VALIDATION_FAILED`,
+`BATCH_NOT_ATOMIC`, `BATCH_TOO_LARGE`, `PERMISSION_DENIED`), and the clone /
+search 501s already answer `{ error, code: 'NOT_IMPLEMENTED' }`. Four 501 exits
+still returned a bare `{ error: '<string>' }` with no code, so a client could
+only key on the prose:
+
+- the cross-object transactional batch route (`POST {basePath}/batch`) when the
+  runtime has no `transaction()` — the last untyped exit on that route, whose
+  siblings (`BATCH_NOT_ATOMIC`, `VALIDATION_FAILED`, the `enforceBatchSize`
+  `BATCH_TOO_LARGE`) were already typed by the #3897 / #3933 / #3939 line;
+- the two `saveMetaItem`-unsupported exits;
+- the UI-view-resolution-unsupported exit.
+
+Each now carries `code: 'NOT_IMPLEMENTED'`, matching the clone / search 501s.
+Additive only — the `error` message is unchanged and no status changes — so
+existing clients are unaffected; new ones can branch on the code.

.changeset/datetime-storage-form-memory-mongodb.md

@@ -0,0 +1,40 @@
+---
+"@objectstack/driver-memory": patch
+"@objectstack/driver-mongodb": patch
+---
+
+fix(driver-memory,driver-mongodb): `Field.datetime` has one storage form per driver (#4047)
+
+The non-SQL counterpart of ADR-0053 D-B (#3912). Both drivers let the writer
+decide a datetime value's runtime type, and both compare across types by type
+bracket rather than by value — so a string comparand never matched a `Date`
+value, in either direction, for **every** operator including `$gte`.
+
+A datetime column genuinely held both forms: the drivers' own
+`created_at`/`updated_at` defaults bind a `Date` (mongo) or an ISO string
+(memory), while REST/JSON writes, relative-date tokens and `initialData`
+fixtures supply the other. A dashboard date window therefore answered with
+whichever half happened to match the comparand's type — on MongoDB, where
+`created_at` is a BSON `Date` and dashboard bounds are strings, that meant
+**no rows at all**, which is worse than the final-day loss #3777 fixed.
+
+Each driver now has one canonical form, applied on write and to every filter
+comparand:
+
+| Driver | `datetime` | `date` |
+|---|---|---|
+| `driver-mongodb` | BSON `Date` — the dialect's native instant, its `timestamptz` | `YYYY-MM-DD` text |
+| `driver-memory` | canonical UTC ISO text (sorts chronologically under the string comparison mingo performs; survives JSON persistence) | `YYYY-MM-DD` text |
+
+Both learn their temporal fields from `syncSchema`, so an object that was never
+declared is left exactly as written — the drivers do not guess types from
+values. `driver-memory` additionally converges rows already in the table when
+the schema arrives, which catches `initialData` fixtures and anything a
+persistence adapter restored (the in-memory analogue of
+`backfillCanonicalDatetimes`, and idempotent like it).
+
+`Field.date` deliberately stays timezone-naive text on both — converting it to
+an instant would invent a midnight and re-couple it to a zone. The
+calendar-day bound semantics from #3777/#4042 are unchanged and now compose
+with the converged storage: the whole-day rewrite runs on the calendar string
+first, and only the resulting bound is converted to the storage form.

.changeset/hono-standalone-discovery-computed.md

@@ -0,0 +1,42 @@
+---
+"@objectstack/plugin-hono-server": patch
+---
+
+fix(plugin-hono-server): compute the standalone discovery `routes` from real registrations, and cede to the real owner (#4018)
+
+`registerStandardEndpoints` served a **fully static** discovery: a hardcoded
+`routes` table listing `auth` / `packages` / `analytics` / `workflow` /
+`automation` / `ai` / `notifications` / `i18n` / `storage` / `ui` regardless of
+what the host actually mounted. A standalone Hono deployment therefore
+advertised ten route families and 404'd on every one no plugin bridged — the
+"advertise a route that doesn't exist" class ADR-0076 D12 exists to kill, and
+the reason this surface disagreed with the two real discovery builders
+(`HttpDispatcher.getDiscoveryInfo`, `metadata-protocol`'s `getDiscovery`), which
+both compute per service at runtime.
+
+Two changes, no new discovery implementation to keep in sync:
+
+- **Single owner (D11 / OQ#9).** When `@objectstack/rest` or the runtime
+  dispatcher is on the kernel, this surface no longer registers
+  `${prefix}/discovery` — that plugin owns it. Both register during plugin
+  `start()`, i.e. before this `kernel:ready` hook, and Hono is
+  first-registration-wins, so they already shadowed this handler in every
+  composed deployment: the cede changes no served payload, it removes a third
+  one nobody read. `/.well-known/objectstack` is ceded to the dispatcher only
+  (REST never registers it), so a REST-without-dispatcher host keeps the
+  redirect.
+
+- **Computed, not hardcoded (D12).** When this surface does own `/discovery`,
+  `routes` is derived per request from the app's live route table: a family is
+  advertised iff a route is really registered at or under its base path. A
+  wildcard mounted *above* the base (global `/*` middleware, `/api/v1/*`) does
+  not count as a mount.
+
+**What changes for you.** On a standalone `HonoServerPlugin` host (no REST, no
+dispatcher), `GET /api/v1/discovery` now omits every family nothing mounts —
+most visibly `routes.metadata`, since `/api/v1/meta` ships with
+`@objectstack/rest` / the dispatcher. Clients that read a route out of
+discovery and call it stop getting a 404; `@objectstack/client` falls back to
+the conventional path for any omitted key, so `client.connect()` is unaffected.
+Composed deployments (`os serve`, cloud) are unchanged — the dispatcher's
+service-aware discovery was already the one being served.

.changeset/inert-rule-warn-dedupe.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/plugin-sharing": patch
+---
+
+fix(sharing): the criteria-less-rule warn is once per rule per process, plus one boot aggregate (#3929 follow-up)
+
+Pre-dedup the fail-closed evaluator warned on EVERY pass — per evaluation and
+per reconciled write — so one legacy criteria-less rule could dominate a
+deployment's log. Enforcement is unchanged (such a rule still matches
+nothing and its grants are revoked on reconcile); the warn now fires once
+per rule per process, and the boot backfill emits a single operator-facing
+aggregate (count + rule names + the fix: repair the criteria or set
+active: false).

.changeset/pin-control-flow-designer-forms.md

@@ -0,0 +1,30 @@
+---
+---
+
+Tests only — no package changes, nothing to release.
+
+Pins the published `configSchema` of the `loop` / `parallel` / `try_catch`
+descriptors, which had no assertions at all: the designer's input for the whole
+control-flow trio was unguarded (#4045 step A).
+
+The assertions capture *intent*, not just current bytes. All three publish a form
+description that is deliberately **shallower and looser** than its Zod counterpart
+in `control-flow.zod.ts`:
+
+- region keys (`loop.body`, `parallel.branches[].nodes/edges`, `try_catch.try/catch`)
+  publish `{ type: 'array' }` with **no `items`**, so the designer treats a sub-graph
+  as opaque — it is edited on the canvas, not in a property form. The Zod is
+  `FlowRegionSchema` (`z.array(FlowNodeSchema)`), which would generate the entire
+  FlowNode/FlowEdge definition nested there;
+- `collection` is `z.string().min(1)` and `iteratorVariable` is `.default('item')`
+  in Zod, yet the form publishes neither `minLength` nor `default`.
+
+This matters for the rest of #4045: the plan (and the issue) assumed these three
+were redundant copies awaiting de-duplication by a single Zod source. They are not
+— they are a second artifact with a different job, and the differences are
+deliberate. With these pinned, any move toward a generated `configSchema` either
+keeps them green or has to state explicitly why the designer contract changed.
+
+Verified to bite: simulating what a naive `z.toJSONSchema` swap would emit (deep
+`items` under `body.nodes`, plus `minLength`/`default`) turns both new `loop` tests
+red.

.changeset/retire-batch-validate-only.md

@@ -0,0 +1,38 @@
+---
+"@objectstack/spec": major
+---
+
+feat(spec)!: retire `BatchOptions.validateOnly` — a dry-run flag that was never implemented (#4052)
+
+`BatchOptions.validateOnly` promised a dry-run — "validate records without
+persisting changes" — but no batch surface ever read it. `updateManyData`,
+`deleteManyData` and `batchData` all persist regardless, so a caller sending
+`options.validateOnly: true` to PREVIEW a mutation got it executed. That is the
+dangerous direction of "declared ≠ enforced": a flag lying about a data-safety
+guarantee, not merely an inert no-op.
+
+There is no dry-run today. Rather than back-fill an implementation to match a
+promise nothing kept — a real no-commit batch has its own design space (cascade
+and constraint semantics under rollback, a response contract that reports each
+row's would-succeed verdict) — the key is retired so it can be reintroduced
+deliberately when there is a real need.
+
+**Breaking change.**
+
+- `BatchOptions.validateOnly` is a retired key. It is tombstoned (`retiredKey`)
+  in `BatchOptionsSchema`, so authoring it now fails with a fix-it prescription
+  rather than being silently stripped (the ADR-0104 / #3733 quiet-failure class).
+  The `BatchOptions` type's `validateOnly` becomes `never`.
+- The retirement is HTTP-only (the key never appeared in stored stack metadata),
+  so it is recorded as a semantic migration on the protocol-18 chain step
+  (`batch-options-validate-only-retired`) — a TODO for API callers, not a stack
+  conversion.
+
+**Migration.** Stop sending `options.validateOnly` on `/batch`, `/updateMany`
+and `/deleteMany`. It never previewed anything; removing it changes no behaviour.
+If you need to validate a batch without writing, follow #4052 so a real
+no-commit preview can be designed.
+
+Also fixes a dangling documentation reference: the `/createMany` route
+registration named `requestSchema: 'CreateManyRequestSchema'`, a schema no
+module ever exported — pointed at the real `CreateManyDataRequestSchema`.

.changeset/retire-dev-analytics-stub.md

@@ -0,0 +1,13 @@
+---
+'@objectstack/plugin-dev': patch
+'@objectstack/runtime': patch
+---
+
+Retire the dev-mode `analytics` stub, and make the dispatcher gate `/analytics` on `handlerReady` rather than on service presence (#4000).
+
+Retiring the degraded analytics shim (#3891) made an empty `analytics` slot the honest signal: `/api/v1/analytics/*` 404s and discovery reports `unavailable`. `plugin-dev` refilled that slot with a stub, which re-created the retired shape in dev mode — the dispatcher gated on "is a service registered", so the stub was called like a real engine and its empty result came back as a 200.
+
+- `plugin-dev` no longer registers an `analytics` dev stub; the slot stays empty (`NO_DEV_STUB_SERVICES`). Every other dev stub is unchanged.
+- The `/analytics` domain, its route-mount gate, and discovery's `routes`/`features` now share one predicate (`isAnalyticsServiceServeable`): a service that self-declares `handlerReady: false` (ADR-0076 D12 — `__serviceInfo`, or plugin-dev's legacy `_dev: true`) is treated as an empty slot. A `degraded` implementation that genuinely serves requests keeps serving; `discovery.services.analytics` still reports a registered stub as `status: 'stub'`, which says more than `unavailable` would.
+
+FROM → TO for dev setups that relied on the stub answering `POST /api/v1/analytics/query` with `{ rows: [], fields: [] }`: install the real engine — `@objectstack/service-analytics` runs an InMemory strategy and needs no database of its own. Nothing else changes; hosts that already install it (including `os serve`, where `analytics` is in `ALWAYS_ON_CAPABILITIES`) are unaffected.