Merge remote-tracking branch 'origin/main' into claude/issue-9767-empty-ledger-green-line

Author: claude

.changeset/anonymous-deny-401-code-key.md

@@ -0,0 +1,20 @@
+---
+"@objectstack/core": minor
+---
+
+feat(security): the REST 401 anonymous-deny body carries `code: "UNAUTHENTICATED"` alongside the existing `error` / `message` keys (#9487)
+
+Every other REST error family answers `{ error, code }`, with the machine code
+in `code` — the 401 family was the one outlier, answering
+`{ error: "UNAUTHENTICATED", message }` with no `code` key at all. A client
+keying on `body.code` (the shape the other families teach, and the first read
+of `@objectstack/client`'s `err.code`) read `undefined` for every
+authentication failure.
+
+`ANONYMOUS_DENY_BODY` now carries `code: "UNAUTHENTICATED"` as well.
+**Additive only** (maintainer-ruled): no key is removed or moved — `error`
+keeps holding the same code value it always has, so every existing reader
+keeps working. The wire effect surfaces through `@objectstack/rest`'s
+`enforceAuth`, which writes this constant verbatim on every `/data`, `/meta`
+and `/reports` 401. This does not settle ADR-0112 D5 (flat vs nested envelope
+convergence); both declared envelope families are unchanged in kind.

.changeset/hono-adapter-discovery-envelope.md

@@ -0,0 +1,24 @@
+---
+"@objectstack/hono": minor
+---
+
+feat(adapters): the hono adapter's two discovery bodies join the response envelope (#9436)
+
+<!-- adr-0087: not-required (no-migration-prescription) Additive wire change:
+`GET {prefix}` and `GET {prefix}/discovery` gain `success: true` beside the
+existing `data` key — nothing authorable and no key is renamed, retired or
+removed, so there is no conversion to register. Every measured reader
+(`@objectstack/client` `connect()`'s `body.data || body`, the QA http-adapter's
+`'routes' in body` discriminator, objectui's `typeof body.success === 'boolean'
+&& 'data' in body` unwrap) resolves the new shape to the same document. -->
+
+`GET {prefix}` and `GET {prefix}/discovery` answered `{ data: <discovery> }`
+with no `success` flag — one key short of the declared `BaseResponseSchema`
+envelope. They now answer `{ success: true, data: <discovery> }`.
+
+Maintainer ruling on #9436 (2026-08-18, option A), deliberately not inheriting
+#9389's pre-auth exemption: these bodies are read by SDKs, codegen and AI
+clients — the envelope's core constituency — rather than by our own shells,
+and the migration is one key. Readers that unwrapped `body.data` keep working
+unchanged; envelope-aware readers that discriminate on `success` now unwrap
+this mount correctly.

.changeset/http-requests-total-transport-seam.md

@@ -0,0 +1,55 @@
+---
+"@objectstack/plugin-hono-server": minor
+---
+
+fix(hono-server): `http_requests_total` is emitted by the transport, so every inbound mount is counted (#9650)
+
+The counter had exactly one emitter: a `Proxy` the runtime dispatcher built
+over its **own** `IHttpServer` handle. It therefore saw only the routes the
+dispatcher itself registered — and nothing else on the same server.
+
+Measured, that left at least **14** inbound surfaces uncounted, in two
+structurally different classes:
+
+- plugins that mount through `getRawApp()` — auth (`/api/v1/auth/*`),
+  metadata HMR, cloud-connection, marketplace, runtime-config, trigger-api,
+  webhooks, approvals, the console SPA. These bypass `IHttpServer` entirely,
+  so **no** wrapper at that level can ever reach them.
+- plugins that resolve `http.server` themselves and mount through the verb
+  methods — the REST data API via `RouteManager`, storage, i18n, settings,
+  datasource admin.
+
+The two highest-traffic surfaces an operator actually cares about, auth and
+the REST data API, were both in that set. The documented guidance is to alert
+on the 5xx rate derived from this counter, so a deployment could be melting
+down on `/api/v1/*` with the counter flat.
+
+The counter is now emitted from the Hono adapter itself, as a raw-app
+middleware installed at the end of `HonoServerPlugin.init()` beside
+`installMiddlewareSeam()` — the one layer every inbound request converges on,
+whatever registered the handler.
+
+**The route label is the matched PATTERN, never the concrete path.**
+`/api/v1/data/:id`, not one series per record id; `/api/v1/auth/*`, not one
+per sign-in endpoint. Cardinality has to stay bounded or the counter is
+unusable for the alerting it exists for, and the label is unfixable in place
+once dashboards are wired against the first shipped one.
+
+**Wiring.** `HonoServerPlugin` takes a new `observability.metrics` option and
+otherwise follows the canonical chain `ObservabilityServicePlugin` documents:
+explicit option, then the `observability:metrics` service, then **nothing** —
+with no backend configured no middleware is installed at all, so an
+unconfigured deployment pays no per-request cost.
+
+**Two consequences, stated rather than left to be discovered:**
+
+- **A transport that does not implement this seam reports no HTTP metrics.**
+  The seam is Hono's. Another `IHttpServer` implementation emits nothing until
+  it grows its own, and a zero there means "not instrumented", never "no
+  traffic". A response-observing hook on the `IHttpServer` contract is the
+  transport-agnostic successor and is filed separately.
+- **A request the `use()` chain refuses is still counted** — the seam is
+  installed before the middleware seam, so the inbound rate limiter's `429`
+  appears with `status="429"`. A preflight `OPTIONS` that the transport's own
+  CORS built-in answers is **not** counted: it short-circuits earlier and
+  never reaches a route.

.changeset/http-server-response-observation-seam.md

@@ -0,0 +1,45 @@
+---
+"@objectstack/spec": minor
+"@objectstack/core": patch
+"@objectstack/observability": patch
+"@objectstack/plugin-hono-server": patch
+"@objectstack/runtime": patch
+"@objectstack/http-conformance": patch
+---
+
+feat(spec): `IHttpServer` gains an optional `afterResponse` response-observing
+hook so HTTP metrics are transport-agnostic instead of Hono-only (#9835)
+
+The contract addition (additive — a new optional member plus the
+`HttpResponseObservation` / `HttpResponseObserver` types and the reserved
+`UNMATCHED_ROUTE_PATTERN` label): a transport invokes each registered observer
+exactly once per answered request with `{ method, routePattern, status,
+elapsedMs }`, after the response exists — the observation point the `use()`
+middleware contract cannot express (it runs before dispatch and never sees a
+status). `routePattern` is REQUIRED to be the registered route pattern
+(`/api/v1/data/:id`), never the concrete path, so no adapter re-decides metric
+cardinality. Optionality is feature-detected runtime-real
+(`typeof server.afterResponse === 'function'`); a transport that does not
+implement the seam reports **no** HTTP metrics — zero there means "not
+instrumented", never "no traffic".
+
+Implementations and consumers in the same change:
+
+- `@objectstack/plugin-hono-server`: `HonoHttpServer` implements the seam (the
+  ruled #9650 raw-app middleware becomes its delivery path — same reach,
+  including `getRawApp()` mounts and middleware-refused 429s); unrouted
+  requests are now labelled with the reserved `unmatched` pattern (previously
+  they could surface as `/*`).
+- `@objectstack/observability`: new `armHttpRequestCounter(server, metrics)`
+  arms the `http_requests_total` counter through the seam at most once per
+  server (first caller wins), which is what makes "exactly one counter per
+  server" structural.
+- `@objectstack/runtime`: the dispatcher offers its `observability.metrics`
+  registry to the seam (a host that wires only the dispatcher now counts every
+  inbound surface) and suppresses its own per-route copy of
+  `http_requests_total` when the transport implements the seam — retiring the
+  #9833 double count. Request-id echo, the duration histogram, the error
+  counter and the error reporter are unchanged.
+- `@objectstack/http-conformance`: `NodeHttpServer` implements the seam, and a
+  new cross-adapter conformance suite locks the semantics for both adapters.
+- `@objectstack/core`: re-exports the new contract types/constant.

.changeset/mcp-readme-shipped-surface.md

@@ -0,0 +1,68 @@
+---
+"@objectstack/mcp": patch
+---
+
+docs(mcp): rewrite the published README to the shipped host-extension surface (#9579)
+
+`packages/mcp/README.md` is in the package's `files` array with `private` unset,
+so it is the page npm renders. It told the reader to extend the server
+imperatively at six call sites:
+
+```ts
+kernel.getService('mcp').registerTool(calculateRevenueTool);
+kernel.getService('mcp').registerResource({ … });
+kernel.getService('mcp').registerPrompt({ … });
+```
+
+`MCPServerRuntime` has never had any of those members. Measured against the
+built `dist/index.d.ts`, a consumer who copies those lines gets three
+`TS2339 Property … does not exist on type 'MCPServerRuntime'`. The receiver is a
+local variable, so `check:published-readme-exports` is structurally blind to
+them — both of its halves key on a name the fence *imported*, and this one is
+neither imported nor a bare identifier.
+
+Ruled 2026-08-18: **document the shipped surface; do not grow the API to match
+the docs.** So the imperative narrative is gone and the page now documents what
+actually ships — the bridge methods (`bridgeTools`, `bridgeDataTools`,
+`bridgeResources`, `bridgePrompts`), `handleHttpRequest` / `renderSkill`, and the
+exported `registerObjectTools` / `registerActionTools` / `registerSkillPrompts`
+helpers driving an `McpServer`. Every row is probed against the built type entry
+the `exports` map resolves, and the page's one host-extension example compiles
+clean against it.
+
+Neighbouring fabrications the audit turned up, all corrected in the same pass —
+each of them was reachable only through prose or an unimported receiver, which is
+why nothing had read them:
+
+- **A tool family that does not exist.** The page listed
+  `objectstack_find` / `objectstack_findOne` / `objectstack_create` /
+  `objectstack_update` / `objectstack_delete` / `objectstack_describeObject` /
+  `objectstack_listObjects` / `objectstack_listFields` as "auto-registered". No
+  such tool name occurs anywhere in the repo. The real names are the
+  `list_objects` … `run_action` set the page listed separately, one section down.
+- **`aggregate_records` was missing** from the list that *was* correct, along
+  with the fact that it registers only when the bridge implements `aggregate`.
+- **Resource URIs were wrong in both directions.** The page taught
+  `objectstack://objects/{name}/records` (no such resource) and
+  `objectstack://objects/{name}/{id}` (real shape is
+  `…/{name}/records/{id}`), and omitted `objectstack://objects` and
+  `objectstack://metadata/types` entirely.
+- **The advertised capability block was invented.** It claimed
+  `tools.listChanged`, `resources.subscribe`, `resources.listChanged`,
+  `prompts.listChanged` and `experimental.streaming`. The server hand-declares
+  only `logging`; everything else is *derived* from what was actually registered,
+  which is the ADR-0076 D12 contract the README was contradicting. The
+  "Streaming Support" feature bullet and the streaming-resource example went with
+  it — neither names anything that ships.
+- **The stdio transport could not be started by following the page.** Neither
+  `OS_MCP_STDIO_ENABLED` nor `OS_MCP_STDIO_API_KEY` was documented, and stdio
+  auto-start refuses to boot without the key (ADR-0101, fail-closed). The three
+  client config blocks now carry both. The Debugging section also taught
+  `OS_MCP_SERVER_ENABLED=true` as the stdio switch, which is the deprecated path
+  that logs a warning.
+- **A broken relative link.** `../../spec/src/ai/` resolves above the repo root
+  from `packages/mcp/`; the target is `../spec/src/ai/`.
+
+Docs only — no runtime code changed, and no API was added. `registerTool` /
+`registerResource` / `registerPrompt` remain unbuilt by ruling; a future
+imperative API is its own card on measured pull.

.changeset/metadata-plugin-watch-default-false.md

@@ -0,0 +1,37 @@
+---
+"@objectstack/metadata": patch
+---
+
+fix(metadata): `MetadataPlugin`'s `watch` option defaults to `false`, as its own doc comment documents (#9770)
+
+`MetadataPluginOptions.watch` documents its default as ``Default: `false` (post PR-10e —
+was previously `true`)``, directly above the field. The constructor implemented the
+opposite, and it did so in **two** places, so both entry shapes resolved `true`:
+
+- the options literal `{ watch: true, ...options }` — covering a caller who **omits** the key;
+- the fallback `this.options.watch ?? true` — covering a caller who passes an explicit
+  `undefined`.
+
+Both non-test construction sites in this repo pass `watch: false` explicitly and are
+unaffected either way, which is exactly why the drift was invisible to every test and
+gate: no in-repo configuration exercised the default. `MetadataPlugin` is a public export
+(`@objectstack/metadata`, `@objectstack/metadata/node`), so the consumers who did reach it
+were **external** ones — and they reached it by doing the documented-safe thing and not
+naming the key at all. What they got was the configuration both internal call sites go out
+of their way to refuse, citing an **EMFILE** hazard at both: a recursive chokidar poll
+(`usePolling: true, interval: 1000`) over the entire project root, with `node_modules`
+excluded only by chokidar's default `ignored`.
+
+The default now resolves `false`. The flag is normalized once in the constructor
+(`watch: options.watch ?? false`) rather than spelled `{ watch: false, ...options }`,
+because a spread preserves an explicitly-passed `undefined` verbatim and not every read of
+the flag routes through a nullish fallback — the `start()`-time `FileSystemRepository`
+`disableWatch` keys on `=== false`. Coercing once makes an omitted key and an explicit
+`undefined` resolve identically at every downstream read, instead of trading one
+two-spelling divergence for another.
+
+This is a default flip, **not** a capability removal: an explicit `watch: true` still
+attaches the scanner and its watcher, and the sealed-runtime carve-out
+(`bootstrap: 'artifact-only'` forces watching off even against an explicit `watch: true`)
+is untouched. Pins cover all four shapes, asserting on the **observable** — whether a
+watcher object exists on the manager — rather than on the resolved options value alone.

.changeset/object-write-gate-five-gating-rules.md

@@ -0,0 +1,29 @@
+---
+"@objectstack/lint": minor
+---
+
+feat(lint): the five gating object rules cross the runtime publish gate — `object` writes are now judged by `validateFunctionalCompleteness`, `validateManagedApiMethods`, `lintAutonumberFormats`, `validateRuleCompilability` and `validateRuleSchemaFormats` (#4716)
+
+An `active`-state `object` save through `saveMetaItem` (Studio's field editor,
+REST `/meta` item CRUD, an MCP/AI author) is now refused with the existing 422
+`invalid_metadata` envelope when it carries a defect these five rules judge:
+an inert `summary`/`lookup`/`select` shape, a managed-API verb the object's own
+affordances refuse, an autonumber format referencing an unknown field, a
+`format` regex or `json_schema` schema the runtime's own compilers reject, or a
+`json_schema` `format` name ajv would silently drop. All five already gated
+`os validate` / `os build` / `os lint`; the runtime door — the only door a
+tenant overlay row has — ran none of them.
+
+Scope is deliberately the five **gating** rules only (the #4716 adjudication):
+the six advisory-tier object rules stay off the runtime surface, so a clean
+save's response is byte-identical and no new advisory volume reaches Studio's
+designer. Draft saves are untouched (D1), stored rows keep being served
+(ADR-0087 asymmetry — the gate's differential blames a write only for what it
+adds), and `OS_ALLOW_UNLINTED_METADATA_WRITES=1` still degrades the refusal to
+a loud log for migration windows.
+
+Boot-path note: the two schema-judging rules load ajv lazily, only when the
+judged snapshot actually carries a `json_schema` validation — an ordinary
+field edit still loads no compiler, which `runtime-lazy-deps.test.ts` now pins
+as a three-tier contract (parsers never; ajv never without a schema; ajv
+required, on demand, when one is present).

.changeset/org-identifier-session-provenance.md

@@ -0,0 +1,24 @@
+---
+'@objectstack/service-storage': patch
+'@objectstack/plugin-audit': patch
+---
+
+Attachment access hooks: read the caller's org under the blessed `organizationId` name
+
+`callerContext()` in the `sys_attachment` access kit built its fallback
+execution envelope from `session.tenantId` — an alias removed from the
+hook/action session surface in v11 (#3290). `HookContextSchema` strips a
+`tenantId` key and the engine's `buildSession` only ever emits
+`organizationId`, so on every call that reached the session fallback (no
+execution context riding along) the envelope handed to
+`ISharingService.canEdit` carried **no organization at all**. Parent-record
+access for attachments was therefore evaluated without the caller's active
+org on that path. It now reads `session.organizationId`, matching the
+`sys_comment` kit, which already did.
+
+The `sys_comment` kit's own `callerContext()` had the same read as a dead
+first arm (`s.tenantId ?? s.organizationId`); the arm is removed. That half
+is behaviour-neutral — the fallback already carried the value.
+
+Both kits gain coverage of the session-fallback path in both directions: the
+blessed name is read, and a stray removed-alias key does not become the org.

.changeset/organization-probe-discriminate.md

@@ -0,0 +1,47 @@
+---
+"@objectstack/objectql": patch
+---
+
+fix(objectql): a failed `sys_organization` probe stops reading as "this install has no organizations" (#9261)
+
+`probeInstallOrganizations` — the read the #8844 system-write organization
+resolution decides on — sat behind a bare `} catch { ids = [] }`. Every failure
+answered with the count that means *none*, and `resolveSystemWriteOrganization`
+maps 0 / 1 / 2+ organizations to *proceed unstamped* / *stamp the derived id* /
+*refuse*. So one transient probe failure silently skipped **both** halves of the
+2026-08-15 ruling:
+
+- on a `single`-posture install that really has one organization, system-context
+  inserts (a hook, a cron tick, a `runAs: system` flow) landed **unstamped** —
+  filing the row under the `__global__` pseudo-tenant and forking exactly the
+  per-organization autonumber counter and partitioned unique index the ruling
+  exists to protect;
+- on a multi-organization install, the refusal the ruling mandates
+  (`ERR_SYSTEM_WRITE_ORGANIZATION_REQUIRED`) **never fired** — fail-open on a
+  guard that must be loud.
+
+Aggravated by the memo: the invented answer was cached in
+`organizationProbeMemo`, so the outage's consequence outlived the outage — every
+later system write inherited "no organizations" until an organization write
+happened to clear it.
+
+The probe now discriminates by error TYPE, the disposition ADR-0110 D3 requires
+("the probe found nothing" and "the probe could not run" are different facts):
+
+- **benign** — `sys_organization` routes but its table was never provisioned
+  (schema sync not run yet). It cannot hold a row, so zero really is the count,
+  and first boot still proceeds unstamped. Asked through the shared
+  `isMissingTableError` predicate (`@objectstack/metadata/errors`), the same call
+  the file's sibling read seams make, never a hand-rolled code test.
+- **everything else** — connection loss, pool exhaustion, a timeout mid-boot, a
+  datasource that never connected, a permission denial — propagates with its
+  envelope intact, and is **not memoised**. The write that asked fails loudly
+  instead of being filed under a guessed topology, and the next write re-probes
+  rather than inheriting the guess. No new error code and no new response field.
+
+Measured rather than assumed: the old comment's "`sys_organization` may not be
+registered at all (a lean embedding, a bare-kernel test)" is not a second benign
+cause. An object missing from the registry does not fail the read at all on a
+driver that tolerates an unknown table (`find` returns `[]` through the normal
+path), a strict driver surfaces it as the missing table above, and an engine
+with no driver fails the write on its own object one frame before the probe runs.