`auditMetaItem`'s unqualified `catch` reports ANY failed audit read as `{events: []}` — the compliance trail says "no entries" when the read broke

[os-zhuang]

Found while implementing #9426 (PR #9637), by the Zone-2 check that card asked for: confirm the missing-capability path and the unprovisioned-table path are genuinely separate. They are — and measuring that is what exposed this, one layer down. Filed rather than ridden on that PR: #9426's declared file surface is packages/rest/src/rest-server.ts, and this lands in a different package.

The measurement

packages/metadata-protocol/src/protocol.ts, closing the read inside ObjectStackProtocolImplementation.auditMetaItem (locate by text, not line number — this file moves):

} catch (err: any) {
    // Table not provisioned (legacy env) or driver doesn't
    // expose `find` — return empty rather than 500ing the tab.
    console.warn(
        `[Protocol] auditMetaItem read failed for ${request.type}/${request.name}: ${err?.message ?? err}`,
    );
    return { events: [] };
}

The comment names two benign causes. The catch is unqualified and takes every other one with them: a driver connection failure, a permission error, a malformed row, a query bug, a timeout. All of them are reported to the caller as the well-formed statement "this item has no audit entries".

ADR-0110 D3 — a miss and a fault are different facts. This is the same collapse #9426 fixed at the route, but at the layer below it, and the harm shape is worse in one respect: at the route the condition was a static capability gap, whereas here it is a transient read failure, so the same item can report a full trail one minute and a clean one the next, with nothing on the wire distinguishing them.

⚠️ Consequence, same as #9426's: this is the compliance surface. auditMetaItem is the read behind GET /api/v1/meta/:type/:name/audit, which exists so Studio's 审计日志 / Audit log tab can show "who tried what and whether a lock blocked it". An empty answer reads as nobody touched this item. A console.warn on the server is not an answer to the reader.

Control — this is a discriminating finding, not a blanket claim about catch

The same defect class has been filed and closed repeatedly in this package, which is what makes an unswept survivor worth naming rather than assuming:

• getMetaItem 的 overlay 读用裸 catch 把「sys_metadata 不可达」吞成「该项不存在」—— GET /meta/:type/:name 在存储故障时回一个无 code 的 400「not found」 #5532 — getMetaItem's overlay read swallowed "sys_metadata unreachable" into "item does not exist" (closed)
• MetadataProtocol.listCommits 把 commit store 读不到答成 [] —— ADR-0067 时间线上「无历史」与「读不到」不可分辨(零日志,JSDoc 里写着这是设计) #5980 — MetadataProtocol.listCommits answered an unreadable commit store with [] (closed)
• [finding] diffMetaItem answers 200 with an empty diff when sys_metadata_history is unreadable — an outage is indistinguishable from "nothing changed" #8833 — diffMetaItem answered 200 with an empty diff when sys_metadata_history was unreadable (closed)
• [metadata-protocol] SysMetadataRepository 的 nextEventSeq()/nextItemVersion() 同样把读失败当「表还没建」，静默从 1 重新发号 —— #4825 在 canonical 路径上的同形缺陷 #4867 — SysMetadataRepository.nextEventSeq() / nextItemVersion() read a failed read as "table not created yet" (closed)

So the sweep that produced this had a real chance of finding nothing here. It did not.

Scope note — what #9637 does and does not change

PR #9637 refuses at the route when the protocol has no auditMetaItem method at all. It does not touch this path and deliberately leaves the unprovisioned-table answer intact, because the two are separate frames in separate packages and only the first was #9426's card. This one is still open after that PR merges.

What would close it

Not obvious enough to assert here, and there is a real design question — which is why this is filed rather than fixed:

1. Narrow the catch to the two conditions the comment already names (missing table / driver without find) and let everything else propagate, so the route's existing handleRouteError turns it into an honest 5xx. Keeps the documented empty-array promise exactly as documented.
2. Distinguish on the wire — a third state beside "read, no entries" and "read failed". That is a response-shape decision and would be fenced to packages/spec, the same fence [finding] The REST references route answers a MISSING findReferencesToMeta capability with {references: []} — "nothing depends on this item", one layer above the defect #9190 just closed #9326 and The REST audit route answers a MISSING auditMetaItem capability with {events: []} — a compliance surface reporting "this item has no audit trail" #9426 both carried.

Option 1 looks like the one that needs no contract decision, but the choice belongs to triage, and #8901 (the read-seam failure-propagation vocabulary) may govern how the propagating half is expected to be spelled.

Dedup

Searched open issues for auditMetaItem, for the empty-collection-on-read-failure shape in metadata-protocol, and for the audit route generally. Nearest cards are #8747 (auditMetaItem's org scope — closed, different defect on the same method), #9426 (the route's missing-capability limb — this card's sibling, open) and the four closed same-class cards listed above. None covers this catch. No duplicate.

Related

#9426 / PR #9637 (the route limb, same class, one layer up) · #9326 / PR #9425 · #8896 (the empty-accumulator harm shape) · #8901 (read-seam failure-propagation vocabulary) · ADR-0110 D3

[os-support-ai]

Triage: lands in packages/metadata-protocol ⇒ domain:metadata; type Bug; promoted to pm:queue. Auto-adjudicated (triage seat, mechanical boundary test): Option 1 — narrow the catch to the two conditions its own comment names (missing table / driver without find) and let everything else propagate to handleRouteError. This does not widen the acceptance set or the public surface: it restores the declared ADR-0110 D3 contract (a miss and a fault are different facts), exactly the shape of the four closed same-class cards (#5532, #5980, #8833, #4867). Option 2 (a third wire state) would be a spec-fenced contract change and is not commissioned — if implementation shows the narrow-catch cannot express the fix, stop and report a fork per the standard clause.

Four-prism:

1. Platform long-term coherence — shrinks an undocumented exception back to the documented empty-array promise; same seam-vocabulary as the The REST audit route answers a MISSING auditMetaItem capability with {events: []} — a compliance surface reporting "this item has no audit trail" #9426 route fix one layer up.
2. Measured business pull — compliance surface: the audit tab can currently show "clean" for an item whose read failed; transient flavor makes it unreproducible for the reader.
3. AI-agent error-resistance — loud 5xx over silent tolerant []; the tolerant arm is precisely where agent-authored driver bugs go to hide.
4. Startup scope discipline — no new surface, no new state; two-condition narrowing plus a pin.

Dispatch notes: check the current state of #8901 (read-seam failure-propagation vocabulary) before spelling the propagating half; sibling PR #9637 (route limb) may still be in flight — serial-check packages/rest vs this card's packages/metadata-protocol surface (expected disjoint). Veto window open; listed in this round's adjudication section.

---

Generated by Claude Code

[os-elon]

Claim: PM loop round 1
Session: session_019yDEhPBC3tcGkW9bkce1HM
Branch: claude/issue-9638-audit-read-catch-narrowing
Worktree: objectstack-issue-9638
Domain: domain:metadata
File surface: packages/metadata-protocol/src/protocol.ts — the catch closing the read inside ObjectStackProtocolImplementation.auditMetaItem (locate by symbol; this file moves within hours) — plus its pin in the package's test suite (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus
Clause-②: no — see the reasoning below, and the fork clause that binds if it turns out otherwise
Serial constraints cleared: no card in pm:dispatched touches packages/metadata-protocol (verified against the full 16-card dispatched listing). Sibling PR #9637 (#9426's route limb) is in packages/rest — a different package, expected disjoint; verify it is merged or its surface is clear before you open your PR. This round's other metadata cards are in different packages: #9701 (packages/metadata), #9735 (packages/platform-objects).

---

裁决(不可重裁)— triage auto-adjudication 5329460613

Option 1 — narrow the catch to the two conditions its own comment already names (missing table / driver without find) and let everything else propagate to handleRouteError.

This restores the declared ADR-0110 D3 contract (a miss and a fault are different facts) and keeps the documented empty-array promise exactly as documented. It is the shape of the four closed same-class cards (#5532, #5980, #8833, #4867).

⛔ Option 2 (a third wire state distinguishing "read failed" on the wire) is NOT commissioned — that is a response-shape change, spec-fenced to packages/spec. ⛔ Do not build it, ⛔ do not widen PublishMetaItemResponseSchema or any sibling.

Premise — verified on origin/main @ 6cb88d9 this round, ⛔ not inherited

✅ The unqualified catch is still there: the [Protocol] auditMetaItem read failed for … warn sits at protocol.ts:6502, returning { events: [] }. Positive control: auditMetaItem returns 11 hits in the same file, so the reading is a measurement, not a dead grep.

PM 机制假设(须实测,鼓励证伪)

• The benign set may be two distinct errors, not one. The comment names "table not provisioned (legacy env)" and "driver doesn't expose find". Those are plausibly a declared isMissingTableError from @objectstack/metadata/errors and something else entirely for a driver lacking the method. ⭐ Measure which error each path actually produces before wiring the predicate — a predicate written against an assumed error shape is a fail-open that looks like a fix.
• The read-seam invention rule has no declared failure-propagation vocabulary, so "the catch reported the failure" is uncheckable — the blocker measured under #8845 #8901 may govern the spelling of the propagating half. It tracks the read-seam failure-propagation vocabulary. Read its current state and follow it if it has settled a spelling; if it has not, say so and choose, ⛔ do not block on it.

PM 建议的路线(可选,实测优先)

The #8895 worked pattern — discriminate, return the empty answer only for the benign cause, let everything else propagate. Prefer it because the reviewer already knows it; ⛔ but if measurement says the seam differs, follow the measurement and tell me.

⛔ The fork clause that makes the Clause-②: no safe

I judge this not clause-② : the accept set does not widen and no request that is accepted today becomes rejected — a fault stops being disguised as an empty success. Triage reached the same verdict by the mechanical boundary test.

⛔ But if implementation shows the narrow-catch cannot express the fix without a response-shape or contract change — STOP and report a fork. Do not proceed on a lower tier through a contract change. That is the exact condition under which this card's tier is wrong, and the dev is the one positioned to see it.

Required in the PR

• A pin that a non-benign failure now propagates (an honest 5xx through handleRouteError), and a pin that the benign cause still answers { events: [] } — both halves, or the fix is unverified in one direction.
• ⭐ Anti-vacuity: assert on the real response path. A "defect" assertion that passes against an empty read proves nothing — this repo has been bitten by exactly that (body.item.fields vs body.data.item.fields).

Gates for this surface — a LEAD, not a spec

From the tree at dispatch time; ⛔ re-derive against your actual diff:
pnpm check:cross-package-test-inputs · pnpm check:durability-log-level · pnpm check:filter-alias-parity · node scripts/check-cross-package-test-inputs.mjs · node scripts/docs-audit/check-affected-docs.mjs

⚠️ Read-coupling, named because the file surfaces do not show it: #9657 is pm:dispatched in domain:devx and is changing check-durability-degradation-log-level — the gate that judges exactly the catch you are rewriting, and one of the gates on your list. If it flips under you mid-run, report it; ⛔ do not fight it green, ⛔ do not raise a baseline. Baselines may only shrink.

⚠️ A new test file also moves check:type-check-debt --re-measure, which needs the workspace closure BUILT — on an unbuilt worktree it refuses, and that refusal means NOT MEASURED, ⛔ never "not applicable to me".

---

Generated by Claude Code