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

Author: claude

.changeset/discovery-metadata-slot-computed.md

@@ -0,0 +1,18 @@
+---
+'@objectstack/metadata-protocol': patch
+'@objectstack/runtime': patch
+---
+
+Both discovery builders now compute the `metadata` service entry from the implementation that fills the slot, instead of hardcoding opposite verdicts for it (#4089).
+
+`metadata` sat in a "kernel-provided (always available)" block above the loop that reads `__serviceInfo`, hardcoded separately in each builder — and the two disagreed about the same slot:
+
+- `@objectstack/runtime`'s dispatcher declared it permanently `status: 'degraded'` with `message: 'In-memory registry; DB persistence pending'`, so a stack with `MetadataPlugin` and a real `sys_metadata` table was still reported as having no persistence.
+- `@objectstack/metadata-protocol` declared the same slot permanently `status: 'available'`, so the kernel's in-memory fallback (`createMemoryMetadata`, auto-registered when no metadata plugin is present) read exactly like a persisted registry — the `__serviceInfo` marker #4058 gave it went unread here.
+
+Both now read the registered service's `__serviceInfo` (via `readServiceSelfInfo`) and report what it declares:
+
+- kernel in-memory fallback, or plugin-dev's dev registry → `status: 'degraded'` plus that implementation's own `message`, which names what is missing and what to install.
+- `MetadataPlugin` (or any implementation carrying no marker) → `status: 'available'` with no message.
+
+`handlerReady: true` is now stated unconditionally on both sides: it answers "is `/api/v1/meta` mounted?", and that route is served by the protocol whichever implementation occupies the slot — a degraded service in it does not unmount the route. Nothing about routing, gating, or dispatch changes; consumers that treat `status` as a capability claim (AI agents, the console) simply stop being told two different things by two hosts.

.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/serve-boots-without-artifact.md

@@ -0,0 +1,65 @@
+---
+'@objectstack/cli': patch
+'@objectstack/core': patch
+'@objectstack/metadata': patch
+'@objectstack/runtime': patch
+---
+
+fix(cli,core,metadata,runtime): `os serve` boots with no compiled artifact — the platform does not need an application to start (#4085)
+
+The artifact (`dist/objectstack.json`) defines an **application**. ObjectStack is
+a development platform, so it has to start without one — but `os serve
+objectstack.config.ts` died during boot whenever the artifact was absent:
+
+```
+  Loading objectstack.config.ts...
+[StandaloneStack] artifact read FAILED: path='…/dist/objectstack.json' error=ENOENT…
+
+  ✗ Service 'manifest' is async - use await
+```
+
+Exit 1 — on a **known-good app** (`examples/app-todo` fails the same way with
+only its `dist/objectstack.json` moved aside), and on every freshly authored
+project between `os init` and its first `os compile`. The message named neither
+the missing artifact nor a fix, so it read as an internal kernel fault.
+
+Three separate faults, each of which alone was enough to refuse the boot:
+
+- **`serve` registered the config-derived `AppPlugin` before the stack's own
+  `plugins[]`.** Registration order *is* the kernel's init/start order, and that
+  slot sits ahead of `ObjectQLPlugin` (which registers `manifest`/`objectql`) and
+  `DefaultDatasourcePlugin` (which connects the database the app seeds through).
+  The wrap is now **appended** to `plugins[]`, the same slot
+  `createStandaloneStack` gives its artifact-derived `AppPlugin` — so config-boot
+  and artifact-boot share one plugin order. The artifact path never hit this,
+  which is exactly what made a plugin-**order** bug look artifact-related.
+
+- **`ctx.getService()` reported a never-registered service as "is async".**
+  `PluginLoader.getService` is an `async` method, so its return value is *always*
+  a Promise and its internal "not found" rejection can never surface
+  synchronously — the kernel read the answer off that Promise and told every
+  caller to `await` a service that did not exist, while the `not found` branch
+  below it was unreachable. It now decides from the registry: absent ⇒
+  `[Kernel] Service 'x' not found`, registered-but-uninstantiated ⇒ the unchanged
+  `Service 'x' is async - use await`. The same crash now reads
+  `[Kernel] Service 'manifest' not found`, which points at the layer that is
+  actually wrong.
+
+- **`MetadataPlugin` treated an absent `local-file` artifact as fatal.**
+  `createStandaloneStack` always points it at `dist/objectstack.json`, so a stack
+  with no app at all could not boot. A **missing** local artifact is now "nothing
+  compiled yet": it logs, starts empty, and leaves the artifact watcher armed, so
+  a later `os compile` hydrates the running server. The tolerance is
+  ENOENT-only — a malformed or unreadable artifact stays fatal — and
+  `bootstrap: 'artifact-only'` (sealed runtime, where the artifact *is* the
+  deployment) keeps failing loudly rather than silently serving an empty runtime.
+
+`[StandaloneStack] artifact read FAILED … ENOENT` is likewise no longer shouted
+at callers for whom "no artifact" is a healthy state; a present-but-unusable
+artifact keeps the loud warning.
+
+Pinned by an e2e pair that drives the real `os serve` with **no `os compile`
+anywhere**: an app defined only by `objectstack.config.ts` (asserting its object
+is in the started plugin set, not merely that boot survived) and a bare
+`export default {}` platform. The #4012 fixture drops the `os compile` this bug
+had forced on it.

.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/client-sdk.mdx

@@ -40,7 +40,11 @@ async function main() {
 
   // 2. Check available services
   console.log('Services:', discovery.services);
-  // → { metadata: { enabled: true, status: 'degraded' }, data: { enabled: true, status: 'available' }, auth: { enabled: false, ... } }
+  // → { metadata: { enabled: true, status: 'degraded', message: 'In-memory metadata registry — …' },
+  //     data: { enabled: true, status: 'available' }, auth: { enabled: false, ... } }
+  // `metadata` reports the implementation actually behind it: `degraded` plus a
+  // message naming what is missing while the kernel's in-memory fallback fills
+  // the slot, `available` once MetadataPlugin provides a persisted registry.
 
   // 3. Query data
   const tasks = await client.data.find('todo_task', {

content/docs/api/index.mdx

@@ -132,6 +132,8 @@ Returns the full discovery manifest.
 
 Disabled/uninstalled route keys (e.g. `auth`, `analytics`, `workflow`) are omitted from `routes` entirely rather than set to `null`; check `services` to tell "not installed" apart from "installed but not yet mounted here." The sample above shows a minimal install: `analytics` reports `unavailable` and advertises no route until `@objectstack/service-analytics` registers the engine — the dispatcher then also mounts `/api/v1/analytics/*` (the routes are capability-conditional; an uninstalled capability answers 404 for every method).
 
+`metadata` is reported from whatever implementation fills its slot, so the sample's `available` is the `MetadataPlugin` case (a persisted `sys_metadata` registry). A stack running the kernel's in-memory fallback instead reports `status: "degraded"` with a `message` naming what is missing and what to install. `handlerReady` is `true` either way: `/api/v1/meta` is served by the protocol, so the route is mounted whichever registry sits behind it.
+
 ### `GET /.well-known/objectstack`
 
 Served by the runtime dispatcher (`@objectstack/runtime`), not `@objectstack/rest` — its body is wrapped as `{ "data": { ... } }` and includes fields (`name`, `environment`, `features`, `locale`) that the `@objectstack/rest`-served `/api/v1` response above does not. The client SDK's `connect()` tries `/api/v1/discovery` first and falls back to this endpoint, unwrapping either `body.data` or the bare `body`.

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>
 
 ---