Merge remote-tracking branch 'origin/main' into claude/envelope-drift-route-modules-v2zoky

Author: claude

.changeset/adr-0115-plugin-dev-stub-table-verdict.md

@@ -0,0 +1,4 @@
+---
+---
+
+docs(adr-0115): record the #4093 evaluation verdict — plugin-dev's fill-every-slot stub table is retired as a design; the plugin converges to pure assembly. Tiered disposition (fabricators first with a production guard; core's fallback family becomes the one copy with #4089; the working in-memory tier points at the real packages that already exist), sequenced behind the in-flight #4086. Implementation tracked in #4104. Documentation only; releases nothing.

.changeset/degraded-boot-stderr-premise.md

@@ -0,0 +1,46 @@
+---
+'@objectstack/types': patch
+'@objectstack/objectql': patch
+'@objectstack/runtime': patch
+'@objectstack/cli': patch
+---
+
+**Correct the stale premise left behind by #4012: the degraded-boot stderr copy
+survives the operator's LOG LEVEL, not `os serve`'s boot-quiet window.**
+
+`emitDegradedBootBanner` writes the `OS_ALLOW_DRIVER_CONNECT_FAILURE` banner to
+stderr in addition to `logger.warn`, and every comment and test name explaining
+why cited the same reason: `os serve` swallowed all of stdout while the kernel
+booted, and `Logger` routes `warn` to stdout. #4012 fixed that — the boot window
+now buffers and replays `warn`-and-above — which retires the *stated*
+justification for a duplicate that is nonetheless still load-bearing:
+
+`Logger.write()` returns before touching a stream when the record is below
+`config.level`, so at `--log-level error`, `fatal` or `silent` the banner's
+`logger.warn` reaches **no** stream at all. A production host at `error` is
+exactly the deployment this escape hatch exists for, and exactly where a
+logger-only banner would vanish. Removing the stderr copy on the strength of
+#4012 would therefore have been a regression — so this documents the reason that
+is still true, in the places someone would read before deleting it:
+`degraded-boot.ts`, the engine's emit site, and all three parity tests
+(objectql, runtime, service-datasource), which are renamed off "which `os serve`
+boot-quiet cannot swallow" to "which the operator log level cannot filter away".
+
+The objectql parity test now proves the claim instead of asserting around it: it
+drives a **real** `ObjectLogger` at `level: 'error'` and requires the banner on
+stderr *and* nothing on stdout. Set the level to `warn` and it fails — so the
+test is pinned to the level filter rather than passing for any reason.
+
+Also corrected in the same sweep, all comment-only, all previously overstating
+what #4012 had not yet fixed:
+
+- the automation wiring summary (`format.ts`, `serve.ts`, its test) claimed the
+  boot window swallowed the engine's binding warnings. Its real justification is
+  stronger and unchanged: a flow that silently fails to arm emits **no** log line
+  at any level, so binding state has to be read off the live engine — absence of
+  a warning was never evidence of a bound flow.
+- the seed summary (`seed-summary.ts`, `format.ts`, its test) and `AppPlugin`'s
+  seed-outcome note attributed the silence to the boot window; the operative
+  gate is that `SeedLoader`'s result logs are `info`, under the default `warn`.
+
+No behavior changes.

.changeset/dispatcher-handler-ready-gate.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/runtime': patch
+'@objectstack/metadata-protocol': patch
+---
+
+Gate every dispatcher service domain on `handlerReady` instead of on slot occupancy (#4058 step 2).
+
+#4000 made the `/analytics` domain execute ADR-0076 D12's third conclusion ("consumers treat only `handlerReady: true` as a real capability"); every other domain still gated on "is a service registered", so a self-declared stub occupying `automation` / `notification` / `ai` / `file-storage` / `i18n` was called like a real implementation and its fabricated answer went out as a 200. Step 1 (#4082) made the two kinds of dev implementation distinguishable; this is the gate that reads the distinction.
+
+- The `/analytics`, `/automation`, `/notifications`, `/ai`, `/storage` and `/i18n` domains, the route-mount gate, discovery's `routes`/`features`, and the metadata-protocol builder's route advertisement now share one predicate (`isServiceServeable`): a slot whose occupant self-declares `handlerReady: false` is answered exactly as an empty slot is — the domain's existing 404, or the explicit 501 `/storage` and `/i18n` use. One predicate, so what is advertised and what is served cannot disagree.
+- `handlerReady`, not `status`, is the test. An implementation that declares `degraded` defaults to `handlerReady: true` and keeps serving — which is why the in-memory `file-storage` and `i18n` implementations are unaffected.
+- `discovery.services.*` stays presence-gated: a registered stub still reports `{ enabled: true, status: 'stub', handlerReady: false }` (with no `route`), which says strictly more than collapsing it to `unavailable` would.
+- `/ai` improves for the stub case: an occupied-but-unserveable slot used to fall through to a 503 "AI service routes not yet initialized" and lose the `GET /ai/agents` empty-list answer the console polls for on every navigation. Both are restored.
+
+No change for a host whose services are real implementations. If you register your own stub under one of those six slots and relied on the dispatcher calling it, either drop the `handlerReady: false` self-declaration (declare `degraded` if it genuinely serves) or install the real service. Not gated, deliberately: `/data`, `/meta`, `/auth` and the security path — their dev stubs back the dev stack's own core loop, and gating them would 404 the dev stack itself.

.changeset/localized-field-validation-messages.md

@@ -0,0 +1,73 @@
+---
+"@objectstack/spec": minor
+"@objectstack/objectql": minor
+"@objectstack/rest": minor
+"@objectstack/runtime": patch
+---
+
+fix(spec,objectql,rest,runtime): field-validation messages answer in the caller's language, named by the field's label (#3957)
+
+The write path built every built-in validation message by concatenating the **API
+field name** into a **hardcoded English** template. Those strings are what the
+Console toast, the CSV-import row report, the CLI and any custom client display
+verbatim, so a Chinese-locale user importing a bad row read:
+
+```
+第 1 行:penalty_amount must be ≥ 0
+```
+
+…for a field declared `label: '处罚金额'` with a full `zh-CN` bundle loaded. The
+form layer localized the *same* constraint correctly (the browser's native
+`min`), so the language flipped depending on which layer caught the value.
+
+**Three things changed.**
+
+1. **The message is rendered in the caller's locale** from a built-in catalog
+   (`BUILTIN_VALIDATION_MESSAGES`, `@objectstack/spec/system`) shipping `en`,
+   `zh-CN`, `ja-JP`, `es-ES` — the same four locales as the platform bundles.
+   The locale comes from `ExecutionContext.locale`, whose contract already read
+   "Drives message catalogs"; this is the consumer that makes that true. Both
+   HTTP entries (REST server, runtime dispatcher) now resolve it from the
+   request's `Accept-Language` / `?locale` first, falling back to the workspace
+   `localization.locale` — so a rejection message and the field labels around it
+   can no longer disagree.
+
+2. **The field is named by its label, never the API name**: translation bundle
+   (`objects.<obj>.fields.<f>.label`) → declared `label` → API name as the last
+   resort. `FieldValidationError.field` still carries the API name so a form can
+   focus the right input.
+
+3. **The constraint is exposed as data**, so a client can format its own text
+   instead of parsing the sentence:
+   `{ field, code, message, label, constraint: { min: 0 } }`. This rides
+   ADR-0114's existing `constraint` / `value` positions on `FieldErrorSchema`
+   (`constraint` tightens from `unknown` to `Record<string, unknown>`) rather
+   than adding a parallel payload — `label` is the only new field. The bag
+   carries `min`/`max`/`minLength`/`maxLength`/`actual`/`allowed`/`type`, and the
+   message templates interpolate from exactly those keys.
+
+Covered end-to-end, not only in the validator: single and batch insert,
+single-id and multi-row update, ADR-0113's clear-out rejection, the object-level
+rule evaluator's own built-in messages (`requiredWhen`, per-option gating,
+state-machine fallbacks), and the importer's cell-coercion, required pre-check
+and #3956 bound pre-check messages — all of which land in the same row report.
+
+**What this changes for consumers.**
+
+- `code` is unchanged (ADR-0114's `FieldErrorCode`) and remains the thing to
+  match on. Message keys are finer-grained than codes — `invalid_datetime`,
+  `invalid_option_value`, `required_cleared` are rendering detail and never reach
+  the wire — so localization never splits the client-facing vocabulary.
+- `message` **text changes**: it is localized, and it names the field by label
+  even in English (`Budget must be ≥ 0`, not `budget must be ≥ 0`). Anything
+  asserting on the old English string should match `code` (and now
+  `constraint`) instead.
+- An author-written validation-rule `message` is never touched — it is already
+  in the language its author chose.
+- A deployment can override any built-in message with a `translation` item
+  defining `validation.field.<messageKey>` (e.g.
+  `validation.field.min_value: '{{label}}不得小于 {{min}} 元'`).
+- The importer's reference-failure message no longer names the target object's
+  API name (`no sys_user matches "…"`): naming internal identifiers is the
+  defect being fixed, and the column plus the offending value are what an
+  importer can act on.

.changeset/memory-datasource-ephemeral-per-pool.md

@@ -0,0 +1,51 @@
+---
+"@objectstack/service-datasource": patch
+---
+
+fix(datasource): a `memory` datasource is ephemeral again, and each pool gets its own store (#4083)
+
+The shared driver factory built `new InMemoryDriver()` for `driver: 'memory'` with
+no config, so the pool inherited that driver's own `persistence: 'auto'` default —
+in Node, a file adapter at the **relative, process-global** path
+`.objectstack/data/memory-driver.json`. Two consequences, neither intended:
+
+- **It was not ephemeral.** The pool flushed its whole store into the server's
+  working directory (on an unref'd 2s autosave timer, and again at teardown) and
+  reloaded it on the next boot. That is the opposite of what the driver id
+  promises the operator who asks for it — `OS_DATABASE_DRIVER=memory` is
+  documented as *ephemeral, not real SQL* — and it means a "throwaway" datasource
+  left state in the deploy directory.
+- **Every memory pool in a process shared one destination.** The default path
+  carries no per-datasource component, so two `driver: 'memory'` datasources
+  loaded and saved the same file: each saw the other's tables, and the last
+  teardown to flush clobbered the other's rows.
+
+Both were visible as an intermittent test failure. The ADR-0062 D1 federated-read
+acceptance seeds 2 rows into an auto-connected external memory datasource and
+reads them back; it returned 2 rows on a clean checkout and 2×N on the Nth run in
+the same tree — passing in CI (always run #1, always a fresh checkout) and
+failing locally for anyone who ran it twice. Whether a given run leaked depended
+on the autosave timer, which is what made it look flaky rather than wrong.
+
+- The factory now builds the memory pool with **`persistence: false` by default**.
+- It also **honors the datasource's own `config`**, which was previously dropped
+  entirely: `initialData` and `strictMode` never reached the driver.
+- When an author *does* opt into persistence (`config.persistence`), the default
+  destination is **scoped to the datasource** —
+  `.objectstack/data/memory-<name>.json` / `objectstack:memory-db:<name>` — so
+  pools stay independent. An explicit `path`/`key`, or a custom `adapter`, is
+  left exactly as written.
+- The dev-only sqlite step-down's last-resort in-memory driver
+  (`resolveSqliteDriver`, #2229) is built the same way, making its own
+  "not persistent" contract true.
+
+`InMemoryDriver`'s documented defaults are unchanged — constructing one directly
+still auto-detects persistence. Only the datasource-scoped pools this factory
+builds changed.
+
+**Migration.** A deployment relying on `driver: 'memory'` state surviving a
+restart was relying on a bug, and should declare it: set
+`config: { persistence: 'file' }` on the datasource (now written to a
+per-datasource file), or use a real driver — `sqlite`/`sqlite-wasm` give durable
+storage with real SQL. Existing `.objectstack/data/memory-driver.json` files are
+no longer read; delete them.

.changeset/savemeta-persists-normalized-operators.md

@@ -0,0 +1,50 @@
+---
+"@objectstack/metadata-protocol": minor
+---
+
+feat(metadata): `saveMeta` persists the operator spellings the spec normalized (objectui#2945)
+
+`ViewFilterRuleSchema.operator` is `z.preprocess(normalizeFilterOperator, …)`, so
+a stored `notEquals` / `gt` / `isNull` is folded to its canonical form during
+save-time validation — and then the result was thrown away. `saveMetaItem`
+persists the authored body verbatim, deliberately: `parsed.data` strips the
+Studio-only auxiliary fields (`isPinned`, `isDefault`, `sortOrder`) that ride
+along with an overlay document (ADR-0005 §Validation).
+
+The consequence is that **every save mints new legacy-alias rows.** The ~30
+entries in `VIEW_FILTER_OPERATOR_ALIASES` are documented as *"a migration bridge
+[that] may be dropped in a future major"*, but there is no point at which the
+last alias row is behind you, so the bridge can never be dismantled — a
+migration that rewrote every existing row would be obsolete the moment the next
+console personalization PUT landed. That is prerequisite 2 of the vocabulary
+consolidation blocked in objectstack-ai/objectui#2945.
+
+`graftNormalizedOperators` grafts the normalization back on without giving up the
+verbatim body. It walks the authored value and `parsed.data` in lockstep **by
+structure** and copies across exactly one thing: an `operator` whose parsed value
+differs from the authored one.
+
+- **No key list to maintain.** `ViewFilterRule[]` appears at five declared sites
+  today (view `filter`, `ViewTab.filter`, page `filterBy`, and two
+  `component.zod.ts` block props) and the structural walk covers all of them,
+  plus any added later. Enumerating paths would have reproduced in this file the
+  exact duplication #2945 exists to remove.
+- **Nothing else moves.** Only an `operator` string is rewritten, and only where
+  both sides are strings — so a `$`-token `FilterCondition`, a different operator
+  vocabulary entirely, cannot be reshaped by accident. No key is added, removed,
+  reordered or defaulted; the unary `{field, operator}` form does not acquire a
+  `value` even though the schema's own output would give it one.
+- **Nothing is allocated when nothing changed**, so a body already written in
+  canonical form is returned by identity.
+
+Behaviour change worth stating plainly: a `GET` after a `PUT` now returns the
+canonical spelling rather than the one the author sent. That is the spelling the
+spec defines, every renderer accepts it (objectstack-ai/objectui#2974,
+objectstack-ai/objectui#2989 pinned all three of objectui's translation tables to
+the full vocabulary), and it is the point of the change. Existing rows are not
+touched — this stops the bleeding, it is not the migration.
+
+Verified: 11 new tests, including one that drives **every** alias the spec still
+folds through the real `ViewMetadataSchema` and asserts the persisted body comes
+out canonical; full `@objectstack/metadata-protocol` suite 110 tests / 18 files
+green.

content/docs/kernel/services-checklist.mdx

@@ -135,6 +135,32 @@ The discovery endpoint returns a `services` map so clients know what is availabl
 }
 ```
 
+#### `stub` vs `degraded` — and what the dispatcher does with each
+
+A service may self-declare that it is not the full thing (ADR-0076 D12), via a
+`__serviceInfo: { status, handlerReady?, message? }` property on the registered
+instance — see [Services → presence is not capability](./services.mdx) for how
+an in-process caller reads it. The two values mean different things, and for the
+HTTP surface the difference is load-bearing (#4058):
+
+| Declared | `handlerReady` default | Meaning | Dispatcher behaviour |
+|:---|:---|:---|:---|
+| `degraded` | `true` | Really does the work, with reduced capability (in-memory, no persistence, no cross-process fan-out) | **Served normally.** Route advertised, requests handled. |
+| `stub` | `false` | Fabricates its answers — reports success for work that never happened | **Treated as an EMPTY slot.** Route not advertised, request answered exactly as if nothing were registered (404, or the domain's 501). |
+
+Only `handlerReady` is consulted, never `status` — so an implementation that
+declares `degraded` but explicitly sets `handlerReady: false` is also treated as
+empty. The rule is enforced by one predicate (`isServiceServeable`) shared by
+the service domains, the route-mount gate, and both discovery builders, so what
+is advertised and what is served cannot disagree. It applies to the
+dispatcher-owned domains: `/analytics`, `/automation`, `/notifications`, `/ai`,
+`/storage`, `/i18n`.
+
+The `services` map still reports a registered stub as
+`{ enabled: true, status: "stub", handlerReady: false }` rather than collapsing
+it to `unavailable` — "something is in this slot, and it is a fake" says more
+than "install a plugin".
+
 ---
 
 ## 2. data Service ✅ Implemented
@@ -193,6 +219,13 @@ self-declared stub (`handlerReady: false`, ADR-0076 D12) exactly like an empty
 one — routes unmounted, request 404. To use analytics locally, install the real
 engine; `@objectstack/service-analytics` runs an InMemory strategy, so it needs
 no database of its own.
+
+**And it is no longer analytics-only** (#4058 step 2): every dispatcher-owned
+domain now gates on `handlerReady`, so a slot occupied by a self-declared `stub`
+— `automation`, `notification`, `ai`, wherever one is registered — answers as an
+empty slot does. The implementations that really do the work in memory declare
+`degraded` and keep serving. See
+[`stub` vs `degraded`](#stub-vs-degraded--and-what-the-dispatcher-does-with-each).
 </Callout>
 
 ### Features (via `@objectstack/service-analytics`)