fix(metadata-protocol): propagate the metadata-store 503 out of getMetaDiagnostics (#8855)

[hotlong]

Fixes#8855

Implements triage ruling 5302846257 as written: classify by error type through the existing discrimination and propagate the 503. Not "delete the catch"; no payload field added.

The defect

getMetaDiagnostics sweeps every metadata type and publishes four numeric facts about the corpus. Its per-type read was wrapped in an untypedcatch that continued. The comment above it named a benign reason — "type not listable in this kernel scope" — and that reason is genuinely real, which is why this PR narrows the catch instead of removing it. The catch took everything else with it, including the one error the callee exists to raise.

getMetaItems classifies a failed sys_metadata read by error type through rethrowUnlessMetadataStoreUnprovisioned: it returns normally for the one benign driver reason (isMissingTableError — the table is not provisioned yet, so items: [] IS the truth) and throws a 503 for every other read failure. That is the discrimination #5532 introduced so an outage would stop looking like emptiness. getMetaDiagnostics caught the 503 back into emptiness one layer up, then published the emptiness as a number.

Measured before writing anything

The card's repro was written but never run, and triage asked for prediction-then-measurement. Prediction was recorded first; the run matched it exactly. Protocol-level, on origin/main @ 8664a2c99, with an engine whose every read rejects:

[outage: connect ECONNREFUSED 10.0.0.5:5432] RESOLVED
total=0 scannedTypes=26 scannedItems=0 Object.keys(stats).length=0
[benign: SQLITE_ERROR: no such table: sys_metadata] RESOLVED
total=0 scannedTypes=26 scannedItems=0 Object.keys(stats).length=26
every stat = {"count":0,"locked":0,"packages":[]}

The benign run is what makes the harm legible — it is the same payload minus the stats. Two user-visible harms out of one catch:

• stats[t] is never written, so an unreadable type is absent from the response rather than zero. The Studio directory tile the field's own doc names loses the type, byte-shaped like an environment that declares none of it.
• total counts entries that failed validation, and a store nobody can read contributes none — so the endpoint whose whole job is reporting problems answered total: 0 at the exact moment it could read nothing. Green was the failure mode.

scannedTypes reported the full 26 in both runs: it is computed from the intent (targetTypes.length, fixed before the loop) and never decremented on continue.

The fix

One narrowed catch inside one method. A 503 arriving from the read is rethrown unchanged; every other failure still skips that one type, so a kernel scope that cannot enumerate one type does not fail the whole governance sweep. ADR-0110 D3: a miss and an outage are different facts with opposite dispositions, and a consumer must never read one as the other.

The envelope is propagated, not rebuilt. Re-running isMissingTableError / rethrowUnlessMetadataStoreUnprovisioned on what arrives here would re-wrap an already-shaped 503 in a second one and displace the driver error riding as cause — the object logWithheldServerFault prints for the operator (#5437). isMissingTableError walks the cause chain, so that re-wrap is not hypothetical. The pin asserts cause by identity, which is what proves propagation rather than reclassification.

The test is status === 503 rather than the narrower code check deliberately, in the direction rethrowUnlessMetadataStoreUnprovisioned's own doc argues: a false "benign" silently mis-answers a question nobody can re-ask, while a false "real" costs one 503 the caller can retry.

Scope held

• No response field added. A per-type degradation marker is a public-surface addition and the ruling reserves it for escalation. The payload type is byte-identical.
• The shared helper is untouched.rethrowUnlessMetadataStoreUnprovisioned has seven other call sites and reaches two live sibling dispatches; this PR calls the discrimination's result, it does not modify the producer. The diff sits entirely inside getMetaDiagnostics.
• No widening into packages/rest. Re-measured rather than trusted: the card's UNVERIFIED note put the handler at rest-server.ts:4759, but refactor(rest): extract the ADR-0112 error/fault-classification prologue out of rest-server.ts #8887 moved it to :3478. It already wraps the call in try/catch and routes through handleRouteError, which preserves status — so the 503 reaches the wire with no change in that lane.
• organizationId left unmeasured, per the ruling — it belongs to the [finding] The REST metadata write door stamps every audit row env-wide, so #8747's org scope cannot separate tenants on the REST-authored path #8805 tenant-scoping thread.

Verification

New pin packages/metadata-protocol/src/protocol.diagnostics-store-outage.test.ts carries the discriminating control in the same file, because a refusal pin with no positive control cannot show the discrimination is selective rather than blanket:

case	expected
outage, whole-corpus sweep	503 envelope, cause identity
outage, single-type sweep	503
outage vs first boot, side by side	benign answers, outage throws
unprovisioned sys_metadata	resolves, every type present at count: 0
a type genuinely not listable	resolves, that one type skipped, the rest counted
healthy store	resolves, real counts

"0 problems" is the right answer in the benign cell, and it is exactly the answer a blanket change would have kept producing in the wrong one.

Ablation — direction predicted before running: ordinary red, on the outage half only. Restoring the bare } catch { continue; } gives 3 failed / 3 passed, and the three reds fail by resolving with the defect's payload verbatim:

AssertionError: expected a rejection, but the sweep resolved with
{"entries":[],"total":0,"scannedTypes":26,"scannedItems":0,"stats":{}}

The three benign/selective/healthy controls stay green through the ablation — that separation is what shows the change is the outage split and not a blanket throw.

Suites (all at the head quoted below):

• @objectstack/metadata-protocol — 103 files / 1493 tests passed
• Downstream consumers (prefix filter, ...@objectstack/metadata-protocol): the three that touch this surface — @objectstack/objectql 210 files / 3675 tests, @objectstack/rest 118 files / 1948 tests, @objectstack/client 23 files / 301 tests. objectql carries diagnostics-clean-baseline.test.ts and is the consumer that went red on fix(metadata-protocol): fold publish Phase 2's object-table lookup at the producer #8867 after a green edited-package suite.

Gates — derived from the actual changed paths via scripts/pm/dispatch-gates.mjs, then re-run at the post-merge head: check:changeset-gate-self-tests, check:cross-package-test-inputs, check:durability-log-level, check:filter-alias-parity, check:objectui-changeset, check-adr-0087-registration, check-changeset-no-major, check-empty-changeset, plus the convention-triggered check:query-options-erasure, check:type-check-coverage and check:type-check-debt --re-measure, and check:nul-bytes / check:engine-double-contract / check:error-code-casing / check:adr-anchors added beyond the derived list. All pass.

TEST_DEBT measured directly on a built workspace, since @objectstack/metadata-protocol sits in the DEBT ledger and pnpm typecheck carries zero information about it: full workspace build, then --re-measure re-ran tsc per ledger entry — none above its recorded number, the package's recorded 63 unchanged, so the new test file contributes 0 errors. No ceiling raised.

---

Verified at b1de760d6 (post-merge head; the union above was run at this sha).

Generated by Claude Code

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 15, 2026 5:06pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol.

3 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx(via @objectstack/metadata-protocol)
• content/docs/kernel/services-checklist.mdx(via @objectstack/metadata-protocol)
• content/docs/protocol/kernel/http-protocol.mdx(via @objectstack/metadata-protocol)

⛔ 1 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/v9.mdx(via @objectstack/metadata-protocol)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.