Merge remote-tracking branch 'origin/main' into claude/plugin-boot-logs-visibility-12kkwh

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/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/retire-dispatcher-storage-bridge.md

@@ -0,0 +1,63 @@
+---
+"@objectstack/runtime": minor
+"@objectstack/hono": minor
+"@objectstack/plugin-dev": patch
+---
+
+fix(runtime,hono,plugin-dev): retire the dispatcher's `/storage` bridge — it never spoke the storage contract (#4087)
+
+`POST /api/v1/storage/upload` and `GET /api/v1/storage/file/:id` were a
+dispatcher-side bridge to the `file-storage` service slot, written against a
+service shape that does not exist:
+
+- **Upload** called the contract's `upload(key, data, options?)` as
+  `upload(file, { request })` — the parsed file object landed in the `key`
+  slot and `{ request }` in `data`. That is a `TypeError` against every
+  implementation in the repo (`S3StorageAdapter`, `LocalStorageAdapter`,
+  `SwappableStorageService`, plugin-dev's in-memory one), not a
+  near-miss: `Buffer.from({}) → ERR_INVALID_ARG_TYPE`, or an object used as
+  an S3 object key / `path.join` segment.
+- **Download** branched on `result.url` / `result.redirect` / `result.stream`
+  / `result.mimeType` while the contract's `download(key)` resolves a
+  `Buffer`, so every branch fell through and the route answered a
+  JSON-serialized Buffer.
+
+Both routes are removed, along with `HttpDispatcher.handleStorage()`, the
+`/storage` domain registration, the dispatcher-plugin mounts and the two route
+ledger rows.
+
+**Migration.** There is nothing to migrate off in practice — neither route
+could complete a request. (They were reachable: `service-storage` mounts
+`/storage/upload/presigned`, not `/storage/upload`, so nothing shadowed them.
+They simply had no caller — no SDK method builds those URLs.)
+`/api/v1/storage` is `@objectstack/service-storage`'s surface and always was
+the working one:
+
+- Upload — FROM `POST /api/v1/storage/upload` TO the presigned protocol
+  (`POST /storage/upload/presigned` → direct `PUT` to the returned URL →
+  `POST /storage/upload/complete`), or `client.storage.upload(file)`, which
+  runs all three steps.
+- Download — FROM `GET /api/v1/storage/file/:id` TO
+  `GET /storage/files/:fileId/url` (`client.storage.getDownloadUrl(fileId)`)
+  for a signed URL, or `GET /storage/files/:fileId` for a stable browser URL
+  that 302s to it.
+
+Install `@objectstack/service-storage` to get those routes; without it
+`/api/v1/storage` now has no handler, which is the same answer every other
+uninstalled capability gives.
+
+Two follow-on corrections keep `declared === enforced`:
+
+- `@objectstack/hono` no longer mounts `app.all('<prefix>/storage/*')`. That
+  wildcard claimed the whole `/storage` subtree for the two dead routes, so
+  every other path under it — service-storage's protocol above all — got the
+  bridge's own 404 rather than falling through. Storage is ordinary catch-all
+  traffic now.
+- Discovery keeps gating `routes.storage` on `isServiceServeable` — the shared
+  `handlerReady` predicate #4058 step 2 introduced — and plugin-dev's in-memory
+  implementation now self-declares `handlerReady: false`. #4058 deliberately
+  left that one serving because the `/storage` bridge was still there to serve
+  it; with the bridge retired nothing routes HTTP to that slot, so `false` is
+  the honest value — the position `realtime` has held since ADR-0076 D12. The
+  implementation keeps working for in-process callers; it is simply no longer
+  advertised as a reachable HTTP capability.

.changeset/unknown-key-strictness-step3.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/spec": major
+---
+
+feat(spec)!: reject unknown keys on the approval authoring schemas (#4001 step 3)
+
+Third click of the unknown-key strictness ratchet (flow + permission in
+#4071, RLS / sharing / position in #4099). Approval is a v17-new authoring
+surface — tightened while young, before stored volume exists:
+
+- **`automation/approval.zod.ts`** — `ApprovalNodeConfigSchema`,
+  `ApprovalNodeApproverSchema`, `ApprovalEscalationSchema`, and
+  `DecisionOutputDefSchema` are `.strict()` with fixable errors. An approval
+  gate that quietly ignores half its config is the worst instance of the
+  ADR-0078 trap — the request routes, but not the way the author declared.
+- The published JSON schema (`getApprovalNodeConfigJsonSchema`) now carries
+  `additionalProperties: false` into the Studio property form AND
+  `registerFlow()`'s per-node config validation (#4027/#4040), so an unknown
+  key inside an approval node's `config` is rejected at registration too.
+
+**Migration.** Any key now rejected was previously stripped and had no
+runtime effect — removing or renaming it never changes behavior. Mappings
+baked into the errors include the ADR-0019 re-home map for process-era
+concepts: `steps` → successive approval NODES on the canvas, `entryCriteria`
+→ the condition on the entering edge, `onApprove` / `onReject` → the nodes
+wired to the `approve` / `reject` out-edges, `rejectionBehavior` → a declared
+back-edge (ADR-0044) with `maxRevisions`. Plus spelling aliases:
+`mode` / `approvalMode` → `behavior`, `quorum` → `minApprovals`,
+`statusField` → `approvalStatusField`, `org` → `organization`,
+`expandAs` → `resolveAs`, `timeout` / `hours` / `sla` → `timeoutHours`,
+`to` / `target` → `escalateTo`, `name` → `key`, `widget` → `type`.

.changeset/wildcard-fallthrough-guard.md

@@ -0,0 +1,27 @@
+---
+---
+
+chore(tooling): enumerate namespace-claiming wildcard mounts and require each to be classified (#4116)
+
+Release-nothing: adds `scripts/check-wildcard-fallthrough.mjs` plus its CI step.
+No package code changes.
+
+A handler mounted on `<prefix>/*` claims an entire namespace, and Hono runs
+handlers matching a path in registration order with the first Response winning.
+So a TERMINAL wildcard — one that always answers and never yields — makes every
+other route under that prefix reachable only when it happens to register first.
+That shape has cost four fixes (#2567, #4018, #4088/#4092, cloud#923) and every
+one was found by hand, after the fact, by someone reading the code for an
+unrelated reason.
+
+The two driven tests #4092 and cloud#923 shipped each pin one catch-all, and are
+structurally unable to cover the next wildcard someone mounts. What never existed
+is the enumeration. This scan is it: three states (`yields`, verified from the AST
+so the entry cannot rot; `exempt` with a reason; `ratchet` naming the issue), and
+a mount the scan finds but the ledger does not declare is an error, never a
+default — the same shape as `check-route-envelope.mjs` (#3843).
+
+It found 13 namespace-claiming mounts where a manual grep had found 3, including
+two real, previously untracked instances of the #4088 defect in
+`packages/adapters/hono` (`${prefix}/auth/*` and `${prefix}/storage/*`), now
+ratcheted under #4117.

.github/workflows/lint.yml

@@ -123,6 +123,19 @@ jobs:
       - name: Error-code casing guard
         run: pnpm check:error-code-casing
 
+      # Namespace-wildcard fall-through guard (#4116). A handler mounted on
+      # `<prefix>/*` claims the whole namespace, and Hono's first-registered
+      # handler that answers wins — so a TERMINAL wildcard makes every other
+      # route under that prefix reachable only by registration luck. That shape
+      # has now cost four fixes (#2567, #4018, #4088/#4092, cloud#923) and every
+      # one was found by hand, never by CI. Per-plugin tests cannot cover the
+      # next one; what was missing is the ENUMERATION. Three states — yields
+      # (verified from the AST, so it cannot rot) / exempt-with-reason / ratchet
+      # — and an undeclared mount is an error, never a default. Runs its own
+      # --self-test first.
+      - name: Wildcard fall-through guard
+        run: pnpm check:wildcard-fallthrough
+
       # Release-notes drift guard: the platform is one version-locked train, so
       # every released @objectstack/spec major must have a curated, navigable
       # release page at content/docs/releases/v<major>.mdx. Catches the gap that

content/docs/api/plugin-endpoints.mdx

@@ -144,10 +144,43 @@ protocol `ai.chatStream` parses and owns message state for you.
 
 ### File Storage (`/storage`) — Plugin Required
 
-| Method | Endpoint | Description |
-|:-------|:---------|:------------|
-| POST | `/storage/upload` | Upload a file |
-| GET | `/storage/file/:id` | Download a file |
+Provided by `@objectstack/service-storage`, which registers these routes on the
+host HTTP server. Uploads are a three-step protocol — ask for a presigned
+target, send the bytes straight to it, then commit — so the bytes never proxy
+through the API server, and the same shape works for S3, local disk, or any
+other adapter.
+
+| Method | Endpoint | SDK | Description |
+|:-------|:---------|:----|:------------|
+| POST | `/storage/upload/presigned` | `storage.getPresignedUrl` | Step 1 — mint an upload target for a new `sys_file` row |
+| POST | `/storage/upload/complete` | `storage.upload` | Step 3 — commit the uploaded bytes |
+| POST | `/storage/upload/chunked` | `storage.initChunkedUpload` | Open a chunked / resumable session |
+| PUT | `/storage/upload/chunked/:uploadId/chunk/:chunkIndex` | `storage.uploadPart` | Send one chunk |
+| POST | `/storage/upload/chunked/:uploadId/complete` | `storage.completeChunkedUpload` | Assemble the parts |
+| GET | `/storage/upload/chunked/:uploadId/progress` | `storage.resumeUpload` | Read session progress (first step of a resume) |
+| GET | `/storage/files/:fileId/url` | `storage.getDownloadUrl` | Resolve a short-lived signed download URL |
+| GET | `/storage/files/:fileId` | — | Stable browser URL; 302s to the same signed URL (what file fields carry) |
+
+`storage.upload(file)` runs steps 1–3 for you, including the direct-to-storage
+`PUT` in step 2.
+
+<Callout type="warn">
+**This table used to list two routes that never worked (#4087).** `POST
+/storage/upload` and `GET /storage/file/:id` were a dispatcher-side bridge to
+the `file-storage` service, written against a service shape that does not
+exist: it called `upload(key, data, options?)` as `upload(file, { request })` —
+a `TypeError` against every implementation in the repo — and read the `Buffer`
+that `download(key)` resolves as if it were a `{ url | stream | mimeType }`
+descriptor. They stayed mounted and reachable — nothing shadowed them — so
+anyone who followed this table got a 500; everyone who followed the SDK used
+the protocol above and never touched them.
+
+Both routes are retired. `/storage` is service-storage's surface — install that
+package to get it. Discovery advertises the route only when the occupant of the
+`file-storage` slot actually mounts HTTP handlers, so an in-memory dev
+implementation now reports `handlerReady: false` and no `routes.storage`
+instead of pointing at a path with nothing behind it.
+</Callout>
 
 ---
 

content/docs/data-modeling/drivers.mdx

@@ -353,20 +353,34 @@ equivalent age-based reap.
 ## Memory Driver
 
 The in-memory driver keeps records in plain in-process objects (queried via
-[`mingo`](https://github.com/kofrasa/mingo)). Data is lost when the process exits.
+[`mingo`](https://github.com/kofrasa/mingo)).
 It is the **last-resort fallback** in dev mode: `objectstack dev` prefers native
 SQLite (`better-sqlite3`), falls back to the pure-JS WASM SQLite driver if the
 native binary is unavailable, and only drops to the in-memory driver if WASM also
 fails to load. Set `OS_DATABASE_DRIVER=memory` to select it explicitly.
 
+**Whether data survives the process depends on how the driver is built** (#4083):
+
+| How it is built | Persistence |
+| :--- | :--- |
+| A **declared datasource** — `{ driver: 'memory' }` in a stack/app config | **Ephemeral.** Nothing is written to disk unless the declaration sets `config.persistence` — and when it does, the destination is scoped per datasource, so two memory datasources never share one file. |
+| `new InMemoryDriver()` **constructed directly** | `persistence: 'auto'` — under Node that means a JSON file at `.objectstack/data/memory-driver.json`, relative to the process's working directory, reloaded on the next boot. |
+
+Pass `persistence: false` for a driver you construct yourself and want purely in
+memory — a test, for instance, which should neither depend on nor leave behind
+state in the working directory. Two directly-constructed `'auto'` drivers in one
+process still share that single default path.
+
 ```typescript
 import { InMemoryDriver } from '@objectstack/driver-memory';
 
-new InMemoryDriver();
+new InMemoryDriver({ persistence: false });   // pure memory
+new InMemoryDriver();                         // 'auto' — file-backed under Node
 ```
 
 <Callout type="tip">
-Use the memory driver for unit tests. It requires no setup and runs instantly.
+Use the memory driver for unit tests. It requires no setup and runs instantly —
+with `persistence: false`, so one run cannot see what an earlier run left behind.
 </Callout>
 
 ## Local Environment Runtime