删除 saveMetaItem legacy 写入分支后的三处残留:一个无生产者的 ledger 错误码 + 两处已过期的跨包注释

[os-zhuang]

观察类发现,来自 #5264 / PR #5782 的实施过程。当前不影响任何用户行为,三处都在本次改动的硬性文件面之外(packages/spec / packages/rest),所以没有顺手改,单独记一笔。

1. OVERLAY_PERSISTENCE_FAILED 失去了唯一的生产端

PR #5782 删掉 saveMetaItem 的 legacy raw-engine 分支后,OVERLAY_PERSISTENCE_FAILED 在整个仓库里没有任何生产端会再抛出它(原唯一发射点是被删分支的 catch,packages/metadata-protocol/src/protocol.ts 原 7952 行)。但它仍登记在 packages/spec/src/api/error-code-ledger.zod.ts 的 @objectstack/metadata-protocol 名下。

ledger 的自检(error-code-ledger.test.ts)只查大小写、重复与遮蔽,不查「有没有生产者」,所以这一条不会变红 —— 它就是 ADR-0112 那句「no silent fourth state」反过来的形状:注册了、但永远不会被发出。

两处 packages/rest 的测试仍在自行构造这个 error 来断言 5xx 行为,因此它们今天钉的是一个没有生产者的码(#4984 家族的 phantom check):

• packages/rest/src/rest-5xx-message-sanitization.test.ts:278 起
• packages/rest/src/rest-unknown-object-heuristic.test.ts:413 起

两条断言本身仍然有价值(它们验证的是 resolveErrorResponse 对「声明了 status 的 5xx」的处理),换一个仍有生产者的码即可,不必删。处置有两种,都需要维护者裁一下:(a) 从 ledger 摘掉这个码、两个测试改用别的已声明 5xx;(b) 保留,理由是它属于「rest 层对协议 5xx 的通用契约」而非某个具体分支 —— 那就该在 ledger 里写明它由谁发出。

2. packages/spec/src/kernel/metadata-plugin.zod.ts 的 agent 注释已过期

约 793 行,在解释「agent 为什么没有 governed write path」时写道:

saveMetaItem would route it down the legacy raw-engine branch, and nothing calls it.

结论(agent 无变更日志、以 git 为记录)完全成立且未受影响,但机制描述已经不对了:今天 saveMetaItem 会以 403 直接拒绝 code-only 类型(#5086),那条 legacy 分支也已被 #5264 删除。这段注释正是 AGENTS.md「Route & surface ownership」第 1 条点名的输入 —— grep 找得到、按它推理会得出错误的运行时模型。

3. packages/rest/src/rest-5xx-message-sanitization.test.ts 的注释在 #5263 当天就已过期

165-172 行说明为什么 saveMetaItem 的 5xx 生产者是「按形状覆盖」而非实测:

reaching its legacy raw-engine branch requires a metadata type that is neither overlay-allowed nor runtime-creatable AND an artifact-backed item of that type, and a runtime-created one is refused earlier with 403 NOT_CREATABLE.

前半句在 PR #5263 落地当天就不再成立:artifact-backed 的 code-only 类型同样在更早位置被拒(NOT_OVERRIDABLE, 403)—— 这一点 PR #5782 的不可达性复核已用 protocol.code-only-types.test.ts 的既有用例证实。有意思的是这段注释当时是对的,它只是没跟上同一周的门禁收紧,可以当作「注释里写死可达性论证」这种做法本身的样本。

建议

三条同源(都是同一次收紧留下的尾巴),但落在两个包、性质也不同:1 是词表漂移(要裁),2 和 3 是纯注释。可以合成一个小 PR 收掉,前提是 1 先有结论。

参考:#5264 / PR #5782,#5086 / PR #5263。

[os-zhuang]

分诊(发现分诊轮):持有 finding + 补域标签 domain:spec

判级:持有,不入队。 理由是前提今天尚未成立——本单的三处残留都以「PR #5782 删掉 legacy raw-engine 分支」为前件,而该 PR 目前是 open draft(05:19Z 开,未合);origin/main(1624f4a)上 OVERLAY_PERSISTENCE_FAILED 的唯一生产端 packages/metadata-protocol/src/protocol.ts:7952 仍在,ledger 里那一条今天有生产者。现在入队等于让 dev 去修一个还没发生的状态。

重启条件:PR #5782 合入 main 后重新分级(父单 #5264 pm:dispatched)。届时的处置预判:

• 第 1 项(packages/spec/src/api/error-code-ledger.zod.ts:216 的词表条目)是契约面取舍,走 ADR-0049 enforce-or-remove 由 domain:spec 座位判定;若座位认为 (a) 摘码 / (b) 保留并写明发出方需要维护者拍板,再转 needs-user-decision。
• 第 2/3 项是纯注释,可与第 1 项合成一个小 PR(正文建议成立)。

独立成立的半边,如实标注: 第 3 项(packages/rest/src/rest-5xx-message-sanitization.test.ts:165-172)的过期不依赖 #5782 ——该段注释已在 origin/main 逐字核对在场,而 PR #5782 自己的不可达性复核已证 #5263 落地当天该论证即失效。它三行注释、单独派发不划算,随第 1 项一并收即可。

域标签依据(落点,不是标题词汇): 三处落点为 packages/spec/src/api/error-code-ledger.zod.ts、packages/spec/src/kernel/metadata-plugin.zod.ts:793、packages/rest/src/rest-5xx-message-sanitization.test.ts。主要落地站点在 packages/spec,且「触 packages/spec 一律归 spec 座位」是硬规则 ⇒ domain:spec;packages/rest 那一处(域表归 domain:cli)是同一 PR 的 rider,不另拆单,派发时在派发词里申报该文件面。

前提核验(对 origin/main 1624f4a 逐条实读,本地检出 shallow 故不依赖路径历史):error-code-ledger.zod.ts:216 条目在场;metadata-plugin.zod.ts:793 注释原文在场;rest-5xx-message-sanitization.test.ts:165-172 注释原文在场;protocol.ts:7952 生产端在场(即上述前件未成立)。

查重:三仓 open issue 与 PR 各搜一遍,除同源的 #5264 / PR #5782 外无影子单;#4805(ledger 缺 cloud 条目)是另一现场,不合并。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[os-zhuang]

发现分诊（存量裁决轮，维护者 2026-08-06 委托，session_01LeEfA7CFwbJb7JJmXm2KM3）：晋级 finding → pm:queue。持有的唯一理由（PR #5782 未合）已消失——该 PR 今晨 06:03Z 合入。经 origin/main 核实：OVERLAY_PERSISTENCE_FAILED 生产端已删（metadata-protocol 零命中）而 ledger 条目仍在（error-code-ledger.zod.ts:216）、两条 rest 测试仍构造该码——ADR-0112「注册了但永不发出」反形状。第 1 项 (a) 摘码 / (b) 保留写明发出方由 spec 座位判，需拍板时转 needs-user-decision；2/3 项纯注释同 PR 收。

---

Generated by Claude Code

[hotlong]

Release-board audit (maintainer-directed re-audit of non-board domain:spec items, 2026-08-07): adding target:v17 — metadata-protocol change, size S, low-risk: retire/annotate the producer-less OVERLAY_PERSISTENCE_FAILED ledger entry (dead since PR #5782) + two stale cross-package comments; the (a)/(b) fork sits with the spec seat. Maintainer directive: protocol changes land in v17 unless large/risky. Triage seat may veto.

---

Generated by Claude Code

[hotlong]

Triage: domain:spec → domain:spec-surface (seat #6298; existing-stock migration pass, maintainer-instructed 2026-08-07). In the seat's declared face ("错误 guidance 与 alias 表"), and the admission test is about metadata legality, which an error-code ledger entry does not govern — retiring a code with no producer plus two stale comments leaves every authored document exactly as legal as before. ⚠️ One thing for the claimer to confirm first: nothing gates service error emissions on ledger membership in a way that makes the removal an acceptance change; if it does, hand the card back to domain:spec.

---

Generated by Claude Code

[hotlong]

Claim: PM loop round 2, second wave (domain:spec-surface seat #6298; batch raised to 5 per maintainer's acceleration instruction)
Session: session_01JTSZAjgtL3oR6YcpNDhW3T
Branch: claude/issue-5783-savemetaitem-residue
Worktree: objectstack-issue-5783
Domain: domain:spec-surface
File surface: packages/spec/src/api/error-code-ledger.zod.ts (entry removal), packages/spec/src/kernel/metadata-plugin.zod.ts (comment ~:793), packages/rest/src/rest-5xx-message-sanitization.test.ts + packages/rest/src/rest-unknown-object-heuristic.test.ts (re-code the two self-constructed 5xx fixtures + stale comments), possibly the stale reference comment at packages/rest/src/rest-server.ts:1070, regenerated content/docs/references/api/** (contract.mdx enum + error-code-ledger.mdx), .changeset/*.md (stop on breach; explain in the report)
Serial constraints cleared: #6145 (module header on the same ledger file) is now pm:blocked behind THIS card — no other open claim or PR touches the ledger file (in-flight #6243 sweep's ledger item is the strictness ledger .md, a different ledger). Same-day churn: metadata-plugin.zod.ts was touched today by #6072 (ADR-0122) — verify-against-origin/main clause in the prompt.
Ruling recorded (PM, restore-invariant class — veto window open in the round report): disposition (a) — remove the producer-less OVERLAY_PERSISTENCE_FAILED from the ledger; the two rest tests switch to a still-produced ledger 5xx code keeping their assertion substance. Premise (dev must verify first): zero producers repo-wide and zero consumers beyond the two named tests + stale comments; any surviving producer/consumer = fork report, not silent fallback to (b).
Container weight: S/M (cross-package text + regen), mode:subagent shared container.

---

Generated by Claude Code

[hotlong]

Review: ACCEPT — PR #6389, including the deviation from my ruling, which was correct

Reviewed by the domain:spec-surface seat (#6298, session session_01JTSZAjgtL3oR6YcpNDhW3T).

The deletion: verified independently, not taken from the report

A deletion justified as "dead code" is an assertion, not something readable from a diff, so I re-ran the reference surface myself on origin/main rather than accepting the PR's census. It matches exactly — 8 files, and zero producers:

.changeset/rest-5xx-message-withheld.md              1   historical prose
content/docs/references/api/contract.mdx             1   generated
content/docs/references/api/error-code-ledger.mdx    1   generated
packages/rest/CHANGELOG.md                           1   historical prose
packages/rest/src/rest-5xx-message-sanitization.test.ts   5   test self-constructs
packages/rest/src/rest-server.ts                     1   comment
packages/rest/src/rest-unknown-object-heuristic.test.ts   2   test self-constructs
packages/spec/src/api/error-code-ledger.zod.ts       1   the row being removed

Searching for an actual emission (code = '…' / code: '…' outside *.test.ts) returns nothing. P1 confirmed. P2 (sibling repos) and P3 (nothing gates emission on ledger membership) were checked by the dev with commands I can reproduce; P4's precedent (cloud#1124 / cloud#1136 — a documented-but-unemitted code removed with text-and-tests and no registry machinery) is the right analogue, and ADR-0087's conversion registry does govern authorable metadata shapes rather than response vocabularies.

The deviation — and why the fault was in my ruling, not the execution

My dispatch required the replacement specimen to be "a still-produced ledger 5xx code … declaring status: 500". The dev measured that this is unsatisfiable: on the resolveErrorResponse boundary, metadata-protocol has exactly three declared-5xx sites — 503/SERVICE_UNAVAILABLE and 501/NOT_IMPLEMENTED (both standard catalog, not ledger), and deleteMetaItem's 500, which declares no code at all. After this removal that boundary has no ledger-registered 5xx producer whatsoever.

That clause of mine was a mechanism assumption wearing a ruling's clothes — my framing error. The dispatch protocol exists to separate the two precisely so a dev can falsify the assumption without reopening the decision, and that is what happened here. The ruling's intent — a live producer, both ADR-0112 envelope halves asserted, sanitization substance preserved — is fully honoured. Its letter was abandoned on measurement, with the reasoning stated. Correct call.

The alternative I would have forced is worse and the dev named why: picking a ledger 500 from elsewhere (READ_SCOPE_COMPILE_FAILED) would pair an analytics code with a metadata-route mock — manufacturing a fresh phantom of exactly the class this card exists to retire, on a code that does not even reach resolveErrorResponse because /analytics/dataset/query builds its own envelope.

The replacement is stronger than what I asked for

For rest-unknown-object-heuristic.test.ts the new specimen is a strictly harder case: the retired fixture merely contained a heuristic trigger, whereas NOT_IMPLEMENTED's message is actually claimed by the limb that file was written about (it quotes the request's own object name and says "cannot"). The test now measures that first — mapDataError on the same text answers 404/OBJECT_NOT_FOUND — and only then asserts the route answers 501/NOT_IMPLEMENTED. Without that first pair the route assertion would have been vacuous: it would not have shown there was anything for the declared-status band to get in front of. Both cases still assert code and status, per the envelope clause.

Called out: the honest null result

"The ledger removal itself has no red direction, and saying so is the honest report. Restoring the row breaks nothing, because nothing pins it; that is the defect, not a gap in the verification."

That is exactly right and it is the report I want. A fabricated reverse-verification here would have been worse than none — the evidence for a dead-vocabulary removal is the search, and the search is what was shown.

Scope

17 files, of which 11 are regenerated reference pages. My claim comment scoped regen to content/docs/references/api/**; pages outside api/ move because the ApiError enum renders in many pages and its truncation counter shifts +258 more → +257 more. That is a generated consequence of the one-row removal, not scope creep, and the dev flagged it rather than letting it pass silently. content/docs/releases/ untouched. Changeset patch, correct — the ErrorCode union narrows at type level with no call site left to reject.

Landing

All 25 checks green, including both gate-bearing jobs (ESLint 15:59:16Z, TypeScript Type Check 16:10:11Z) at conclusion: success. Flipping to ready and arming auto-merge.

On merge, this unblocks #6145 (module-header doc blocks — same error-code-ledger module), which returns to the queue.

---

Generated by Claude Code