fix(rest): the /meta state route tells a wired-and-failing engine apart from an absent one

[claude]

Fixes #15405

Clause-②: no

objectQLProvider has two consumers in packages/rest/src/rest-server.ts. The engine-slot repair landed for one of them (#13476, the computeExecCtx authorization-input seam, reached through wiredEngineOrLoud). The other, GET {basePath}/meta/object/:name/state/:field, reached the same provider through .catch(() => undefined) and converted every rejection straight back into the undefined a never-registered engine produces, three lines before the answer is chosen. So an engine that was wired and failed to build and an engine that was never registered both answered 404 NOT_FOUND · "Object not found" — a diagnostic route lying about the cause during exactly the incident it would be consulted in.

That line was newly load-bearing rather than long-broken. Before #13904 the shipped provider was try { ... } catch { return undefined; } and could not reject at all, so the .catch was dead code and the collapse happened one layer earlier. #13904 made the provider re-raise precisely so a consumer could see the outage. This consumer caught it back.

This is not rework on #13904 and touches nothing it pinned.

The change — two call sites in one file

site	before	after
GET {basePath}/meta/object/:name/state/:field	this.objectQLProvider(environmentId).catch(() => undefined)	wiredEngineOrLoud(Boolean(this.objectQLProvider), () => this.objectQLProvider!(environmentId))
POST {basePath}/email/send	this.emailServiceProvider(environmentId).catch(() => undefined)	seamOrUndefined(() => this.emailServiceProvider!(environmentId))

⭐ wiredEngineOrLoud, not seamOrUndefined, at the engine seam — deliberately, and against the dispatch's own generic wording. seamOrUndefined's docblock forbids it in as many words: "⛔ Do not route the data-engine seam back through this helper to 'make the seams uniform' — uniformity there IS the defect #13476 repaired." wiredEngineOrLoud is what the sibling consumer already uses, so this route now gives the answer its sibling gives rather than a third one. Both helpers invoke the provider synchronously, which is the other half of the card: a .catch attaches to the promise the call returns, so a host wiring a non-async provider throws before any promise exists and the handler is never reached.

⚠️ Reachability — a correction to the card, measured rather than reasoned

The card does not say which wiring reaches this consumer, and the answer narrows its claim. Every /meta route is wrapped by registerMetadataEndpoints's anonymous-deny gate, and that gate resolves the same engine first, through computeExecCtx. Its two branches do not agree:

gate's engine branch	on a broken engine
PROVIDER branch (wiredEngineOrLoud, no kernelManager wired)	raises — this route's own engine line is never reached
KERNEL branch (seamOrUndefined, absorbing on purpose — wiredEngineOrLoud's RESIDUE note)	absorbs — this route decides ⇐ the defect

⇒ the collapse was reachable exactly where a resolvable kernel supplies auth and the separately-wired objectQLProvider is broken: the multi-kernel wiring (rest-api-plugin.ts wires a kernelManager when the host registers one). It was not reachable in a single-kernel boot such as pnpm dev:crm, where the gate raises first. Measured on a real ObjectKernel, not inferred; §0 of the new test file pins the property (not today's exact raise shape, which belongs to another door).

What moves and what does not

Driven end to end on a real RestServer and a real ObjectKernel — nothing private is replaced, no fault is simulated by throwing a hand-made branded error into a stub:

engine fact	before	after
no objectQLProvider wired at all	404 NOT_FOUND	404 NOT_FOUND — unchanged ⭐ PIN
provider RESOLVES undefined (the seam contract declaring absence)	404 NOT_FOUND	404 NOT_FOUND — unchanged ⭐ PIN
healthy engine, object that genuinely does not exist	404 NOT_FOUND	404 NOT_FOUND — unchanged ⭐ NEGATIVE CONTROL
healthy engine, object that exists	200	200 — unchanged
provider REJECTS (wired, failed to build)	404 NOT_FOUND	503 SERVICE_UNAVAILABLE
provider THROWS SYNCHRONOUSLY (non-async host, #13280)	500	503 SERVICE_UNAVAILABLE

⭐ The pins assert the DISTINCTION, not a status code. A build answering 503 for a broken engine and for a never-registered one would satisfy every bare expect(status).toBe(503) while telling a new lie, so the table above is asserted side by side with an explicit inequality ([404, 404, 503], new Set(...).size === 2, and the codes differing). §4 goes further and derives the expected value off the sibling seam's own error object on the same fault, rather than writing a second literal beside it.

⚠️ Envelope, so nobody reads it as a second defect. The 503 arrives as the flat { error: 'Internal server error', code } every withheld 5xx on this server wears (handleRouteError, #5437), while the sibling package door emits its own nested { error: { code } }. The two doors agree on the pair that is the contract — status and machine code — and differ only in which emitter dresses it. That flat shape is pre-existing and pinned elsewhere (rest-server-meta-read-org-scope.test.ts names it verbatim); not this card's to move. pnpm check:route-envelope is green.

⚠️ POST /email/send carries only the second observation. No 404/503 question, and not reachable from the shipped wiring — both providers in rest-api-plugin.ts are declared async. Its answer is deliberately unchanged at 501 NOT_IMPLEMENTED; what changes is that the synchronous fault shape now reaches that same 501 instead of escaping past a .catch that did not exist yet and landing in the handler's own 500 EMAIL_SEND_FAILED. Repaired because it is the same retired spelling at an embedder-reachable seam, not on a claim of live impact.

Ablation — predicted in writing first, then run

Both legs mutate the committed tree, prove the mutation reached disk (marker counts and blob hash), run the pins, restore, and prove the restore by blob-hash equality plus an empty git diff HEAD. Restore is git checkout HEAD -- ABSOLUTE_PATH under a trap ... EXIT INT TERM with absolute paths. No git stash.

Predicted, before running: leg A red on the 3 cases in §2 plus the 1 in §4 (4 failed / 10 passed); leg B red on the §5 sync-throw case only (1 failed / 13 passed).

Observed:

leg	mutation reached disk	result	the cases that went red
A — restore .catch(() => undefined) at objectQLProvider	injected marker 0→1, deleted marker 1→0; blob f384ecf5 → c702672d	4 failed / 10 passed	§2 rejecting (expected 404 to be 503), §2 sync-throw (expected 500 to be 503), §2 distinction ([404,404,404] vs [404,404,503]), §4 sibling agreement (expected 404 to be 503)
B — restore .catch(() => undefined) at emailServiceProvider	injected marker 0→1, deleted marker 1→0; blob f384ecf5 → df3a6ade	1 failed / 13 passed	§5 sync-throw (expected 500 to be 501)

Both legs restored to blob f384ecf5d419b224d6b9932805a6df2347897a32 = HEAD, git diff HEAD empty. Prediction and observation match exactly, in both direction and cardinality. No dist preflight: the pins import the subject by relative path (./rest-server.js), so no package exports/dist is on the resolution path.

Verification

Head at the time of every reading below: d5248b67b8 (origin/main merged in at a016f08b8a; the merge is a message-only amend of 47a1ecd761, identical tree 664f0fe0).

• Gate families — derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack from a tree at origin/main, reconciled with --ran: 58 derived, 58 run, 0 UNRUN. Exit codes captured by redirect-then-$?, never through a pipe.
• 56 of 58 green. Two returned exit 3 PREREQUISITE NOT MET — check:dual-build-cjs-loads and check:type-check-debt — both because they read built output for the whole workspace and this container has no full pnpm build. ⛔ Recorded as NOT MEASURED, not as failures and not as passes; CI builds the closure first and is where they get their reading.
• pnpm lint (eslint . --no-inline-config, the whole repo — no narrowing) exit 0 at d5248b67b8.
• pnpm --filter @objectstack/rest test — 185 files / 3073 tests, all pass. The new file contributes 14. pnpm --filter @objectstack/rest typecheck (tsc --noEmit + check:test-typecheck) exit 0, 0 debt entries.
• pnpm --filter '@objectstack/rest^...' build (the dependency closure, downstream direction not applicable — no exported type moves) exit 0.
• Docs drift — the automated run covered none of this diff; see the dedicated section below for what was hand-swept instead.

Docs drift — the run produced NO anchor, so this was swept by hand

⛔ This is not a clean bill of health, and the drift comment says so itself. The bot reports that 1 changed file yielded no anchor — packages/rest/src/rest-server.ts, which is the only source file in this diff — so "the pages documenting them are NOT COVERED by this run". scripts/docs-audit/check-affected-docs.mjs and check-drift-comment.mjs do exit 0, but a zero from an instrument whose anchor derivation produced nothing for the file under change is not a reading. --json confirms it numerically: anchors: 0, docs: 0, detail: 0, anchorlessChanges: ["packages/rest/src/rest-server.ts"].

⚠️ The input-vs-emitter blind spot the bot discloses is live here: this diff is emitter-only, and a page that states a rule by its inputs shares no token with the emitter, so it cannot be listed on this run or any run. The sweep below was therefore done by CONTENT, over the whole of content/docs/, not by anchor.

What was searched, and the positive control. Terms: the route itself (state/:field, /state/, legalNextStates), the literal it emits (Object not found), the new answer (503, SERVICE_UNAVAILABLE, AuthzStoreUnavailable), the input-side spellings (no data plane, without a data engine, objectql not registered, no engine is wired), and every page carrying both 404 and /meta.

⭐ The control fires, and fires exactly where the tooling is blind. The content sweep found content/docs/protocol/objectql/state-machine.mdx:127, which documents this very route verbatim — and that page appears in neither the anchor run (0 anchors) nor the 13-row coarse fallback. It also found content/docs/protocol/kernel/index.mdx:298, the only non-release page in the tree that names AuthzStoreUnavailableError at all, likewise in neither list. A search that reaches two pages both automated paths miss is a search that could have returned a falsification.

Result: one candidate, reported not edited; nothing else falsified.

⚠️ CANDIDATE — content/docs/protocol/kernel/index.mdx:298. It reads, inside a comment describing resolveExecutionContext():

It rejects with AuthzStoreUnavailableError (503) only when an authorization input exists and could not be read — a failed permission-store read, or a tenancy service that is registered and failed to build.

Under the scoped reading — a statement about resolveExecutionContext(), the function named on the next line — it is untouched: this PR does not change that function, which lives in packages/runtime. Under the global reading — "that error is only ever raised where an authorization input exists" — this PR is the first change that makes it false, because wiredEngineOrLoud had exactly one caller until now (computeExecCtx, an authorization-input seam) and this adds a second on a metadata read, where the engine is consulted as the registry and no capability judgement was being sought. Proposed correction, for whoever owns that page: bound the sentence to resolveExecutionContext explicitly, or add that the REST metadata plane raises the same branded error when a wired engine cannot be resolved. ⛔ Not edited here — content/docs/** is outside this PR's declared 3-file surface.

Read and found NOT falsified:

• content/docs/protocol/objectql/state-machine.mdx:127 — the page that documents this exact route. It describes only the 200 answer body (object, field, from, next, and when next is null), which this PR pins unchanged. Not falsified; it is silent on every non-200 answer, which is a pre-existing gap rather than drift.
• content/docs/deployment/troubleshooting.mdx:174 — "Object not found" after defining it, the one page keyed on this route's 404 literal. Its three listed causes stay true, it is scoped to client.data.find, and it does not claim to be exhaustive. If anything this PR makes it more nearly complete on the /meta state route, by removing a fourth cause it never listed.
• content/docs/protocol/kernel/http-protocol.mdx — documents /meta type listings and single-item reads; never mentions the state route and states no 404-versus-503 rule for /meta.
• All 13 coarse-fallback rows read out (packageMentionDocs at c17b494dba2cf8220dbf6332eedcfbd92305c499), not dismissed as wide. Eleven contain none of this change's surface terms. content/docs/api/index.mdx:217 carries only the generic mapping 503 to SERVICE_UNAVAILABLE, which this change conforms to. content/docs/releases/v17.mdx carries the historical v17 notes on the store-outage repair; their explicit "what did NOT change, and is pinned" list (reachable-but-empty store, genuine denial, unprovisioned tables, anonymous callers) is untouched by this PR, and release notes are never edited from a code PR in any case.

What this sweep does NOT cover: pages that restate the rule in wording sharing no token with any of the searched terms. That residue is irreducible for an emitter-only diff — it is the #11430 shape the bot names — and it is stated here rather than papered over.

Changeset — MEASURED, not guessed

skip-changeset is refused on evidence. @objectstack/rest was built and npm pack --dry-run --json run; the changed route's own literal (State-machine introspection is not available in this runtime) was searched across every packed path the pack reported (10 files), not against the files[] field:

• POSITIVE CONTROL fires in dist/index.js and dist/index.cjs ⇒ this route ships.
• NEGATIVE CONTROL (a nonsense symbol) fires nowhere ⇒ the search discriminates.

⇒ .changeset/meta-state-route-engine-outage-distinguishable.md, @objectstack/rest: patch.

Clause ② — re-derived from the delivered diff, not copied

Clause-②: no.

• No accept set widens. Nothing that was refused becomes served: the two absence rows keep their 404, the healthy-engine rows are untouched, and the only movement is which refusal is named for a fault that was already being refused. POST /email/send moves 500 → 501, refusal to refusal.
• No published surface grows. No new route, no new export, and no new wire code: SERVICE_UNAVAILABLE is an existing StandardErrorCode member, reached through the existing AuthzStoreUnavailableError — authz-store-unavailable.ts says so itself: "Deliberately NOT a new code: the wire vocabulary is closed."
• It is a pull-back to a declared contract, which the criterion says does not touch clause ②. The contract is @objectstack/core's published AUTHZ_STORE_UNAVAILABLE_STATUS = 503 and wiredEngineOrLoud's own table (the engine cannot be RESOLVED: 403 → 503).

⚠️ The second look the dispatch asked for, recorded rather than waved past: an operator-visible status code does move on a published route (404 → 503, multi-kernel wiring). Under the criterion's own negative boundary that is a runtime refusal-path behaviour change, not an accept-set widening — hence no. A reviewer who reads the boundary the other way should say so; the basis is stated here so it can be overturned on the record rather than re-derived.

验收备注

• ⛔ Deliberately not widened. packages/rest/src/rest-api-plugin.ts was read only. The provider closures there belong to [finding] every OTHER shipped provider in rest-api-plugin.ts still absorbs the three-state ctx.getService throw — the #13904 shape, waiting one seam over #14251 phase 1 and are untouched.
• Noted, not filed — a third objectQLProvider consumer. POST {basePath}/batch reaches the slot with no .catch at all, so a rejection propagates to that handler's own handleRouteError. It does not carry this card's defect (it never collapses an outage into "not found"), and it was not in the card's enumeration. Whoever next audits the slot's consumer census is the reader for this. Carrier: [finding] every OTHER shipped provider in rest-api-plugin.ts still absorbs the three-state ctx.getService throw — the #13904 shape, waiting one seam over #14251's census.
• Noted, not filed — the two consumers ask different sources. On the multi-kernel wiring the gate resolves the engine from the per-environment kernel while this route asks the local-kernel objectQLProvider, which rest-api-plugin.ts documents as the "single-kernel fallback". That asymmetry is what makes the defect reachable at all; it is a wiring question one layer above this file and is not touched here. Carrier: the same census.

Authored by the domain:cli execution PM seat, session session_015QE8qk46e5CHJxyQEUjbf8. Measured on this PR, recorded because AGENTS.md says the channel-by-action cells disagree: a raw-REST edit of a PR body appends its own bare attribution block (58 bytes) whatever the payload carries, so a payload carrying the session-URL form ends with TWO footers and only a footerless payload ends with one. The session id therefore lives in this line, which an edit cannot strip.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/rest/src/rest-server.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/rest/src/rest-server.ts) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 13 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json c17b494dba2cf8220dbf6332eedcfbd92305c499 → packageMentionDocs.