docs(adr-0087): point the superseded retirement claim at its correction, and record the artifact-ingestion door ruling

[claude]

Fixes #17894

Records-only and purely additive: 101 insertions, 0 deletions, one file (docs/adr/0087-metadata-protocol-upgrade-contract.md). No code, no test — the code half is #16864's.

Defect 1 — a live false rule 35 lines above its own correction. The paragraph under "The load-window's second half is now mechanical" still reads, in the present tense, "a retired entry is skipped by the loader (applyConversions) and replayed only by the chain (migrate meta) and the fixture CI". It gains an in-place blockquote pointer to the two addenda that supersede it for metadata at rest. The sentence itself is NOT rewritten and NOT deleted: an accepted ADR's text binds, and a superseded decision is still a record (Prime Directive #13). The form is this corpus's own — ADR-0044 and ADR-0058 both carry exactly this blockquote shape.

Defect 2 — the artifact-ingestion door was in no addendum. The door's policy was ruled on #12772 and lived only in that issue, so a reader of this ADR met the 2026-07-31 stored-row policy and nothing about the boot seam. A ninth ## Addendum records it in the file's own addendum form (the form triage 5651629548 ruled, used eight times before): the ruling quoted verbatim from comment 5443380108, the as-built versioned window and the four branches it decides, the two in-tree doors that consume the one policy, the default-flip exclusion, the schema-layer residue boundary (comments 5448522858 / 5448958115), and the flag's live seam inventory. One as-built reading is recorded as a reading rather than smoothed over: the ruling says "authored specVersion", while what ships keys off the declared engines.protocol range floor.

Acceptance — measured both directions

origin/main at 65767d23 (827 lines) vs this branch at f7d8e9da (928 lines).

grep in the ADR	before	after
^## Addendum	8	9	the ninth addendum (not 10, not 8)
Superseded for metadata at rest	0	1	the pointer, beside the superseded sentence
skipped by the loader	1	1	the original sentence, untouched
#12772	0	6	the ruling is now in the record
artifact-ingestion	0	1	zero hits was the card's measurement
applyArtifactForwardConversions	0	1	zero hits was the card's measurement
## Addendum (2026-07-31)	1	1	control — heading intact
retiredFromLoadPath	2	2	control — instrument would have hit

Stronger than the greps for the addendum the card pins: the whole ## Addendum (2026-07-31) section is byte-identical across the two refs — md5 0b3788f178526522dd8dcac7aedb519d, 2657 bytes on both — and git diff --stat is 101 insertions with no deletions, so nothing above could have been edited.

The quoted ruling was diffed against the API body of comment 5443380108 after whitespace normalisation: verbatim match.

Gates

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 22 families for this path; all 22 were run and reconciled with --ran carrying each exit code: 22 derived, 22 run, 0 NOT-MEASURED, 0 UNRUN, every one exit 0. pnpm --filter @objectstack/lint run check:doc-formula-expressions first exited 3 (prerequisite: unbuilt @objectstack/formula / @objectstack/lint, nothing measured); the closure was built under the shared verify lock and it re-ran exit 0.

check:adr-0087-registration asserts, for this file, that the not-required disposition vocabulary it accepts and the categories this ADR documents are the same set, in both directions — it says nothing about addendum headings; the new text adds no disposition marker, and the gate is green.

Non-vacuity, proven by ablation rather than asserted. The new symbol anchor was mutated on disk to a name that does not exist (applyArtifactForwardConversions plus a ZZZ suffix; grep before/after: real 1 to 0, fake 0 to 1). node scripts/check-adr-symbol-anchors.mjs then exited 1 with [unresolved-symbol] naming that anchor at line 867 — so its green is a reading of this diff, not of nothing. Restored with git checkout HEAD -- (path); git diff HEAD empty and the file's blob hash equal to the HEAD blob (4c83b339).

Repo-wide pnpm lint — a declared narrowing, with its three readings. (1) The population comes from eslint's own config: every files: block in eslint.config.mjs globs ts,tsx,mts,cts,js,jsx,mjs,cjs only; there is no markdown block. (2) pnpm exec eslint --no-inline-config --format json over the one changed file returns one result, errorCount: 0, message "File ignored because no matching configuration was supplied." (3) Invariance: the diff is one .md file and no config file, and no type-aware linting is configured, so no untouched file's verdict can move. CI runs the full sweep regardless.

Changeset

skip-changeset: docs/adr/** ships in no package's files[], so this publishes nothing.

Acceptance notes

Noted, not filed: the ruling's "authored specVersion" and the shipped key (the declared engines.protocol floor) are not the same reading, and the difference is load-bearing — it is why the default-flip exclusion exists. It has already been carded twice — #16693 and #17885, both landed and shut — so this PR records it in the addendum instead of filing a third card. No other out-of-scope finding; the code half stays #16864's, and #17885 was not touched.

维护者速读(草稿)

改了什么 —— 一份已接受的 ADR 里的两处「记录缺陷」,只加不改:① 在 :355 那段「retired entry 被 loader 跳过」的旧话旁边加一条指向其更正的引用块(原句一个字没动);② 补上第九条 ## Addendum,把 #12772 已经裁过、却只活在 issue 里的 artifact 入口门政策写进记录。代码零改动。

为什么改 —— 那句旧话站在自己的更正上方 35 行,文档顺序保证读者先读到假的那句;而 artifact 门的整条政策在 ADR 里一个字都没有,ADR 的读者对那个 boot seam 一无所知。两条都是「把已经声明过的东西拉回记录」,不是新决定 —— 形式用的是本文件自己用过八次的 addendum 惯例。

风险与代价(含回滚) —— 风险接近零:纯文档、纯新增、无发布面、无 changeset;22 个派生门禁全绿,并用消融证明锚点门禁确实读了这份 diff。回滚 = revert 这一个 commit,没有任何代码或生成物依赖它。唯一需要您过目的判断:新 addendum 里明说「裁决写的是 authored specVersion,实际落地键的是 engines.protocol 的下界」—— 这是照实记录已落地实现,不是改裁决。

席位意见 ——

你要做的 —— governed 面(docs/adr/**),按规矩是维护者手合:本 PR 保持 draft,任何席位都不会转 ready、不入队、不挂 auto-merge。请读两处新增文字(尤其第九条 addendum 里引用 #12772 的那段是否如您所愿),认可后由您批准,席位再落地。

---

Generated by Claude Code

[claude]

• Served-tier: 657/657 claude-fable-5-1 — harness model stamp counted over this seat's own transcript (non-sidechain assistant messages) at 2026-09-13T10:32Z; get_session external_metadata.last_served_model read claude-fable-5-1 at 2026-09-13T10:31Z.

Contract review

Head: f7d8e9da (PR #17997, card #17894) — read at 2026-09-13T10:32Z by the skills seat at the contract-review tier.

Files: docs/adr/0087-metadata-protocol-upgrade-contract.md only (+101 −0). No code, no test, no changeset owed (skip-changeset). Inside the dispatched surface (claim 5652627725: this file ONLY, two edits).

① derived judgments — an ADR addendum records decisions already made; the review asks whether each recorded statement is TRUE on origin/main and whether anything is decided here that was not ruled:

1. Edit 1 — the in-place pointer. The pre-addendum sentence (「a retired entry is skipped by the loader …」) is byte-unchanged; the blockquote beneath it names the 2026-07-31 ([P2] The spec contract stops at authored source — stored metadata is rehydrated unparsed, unconverted, and ungated #3903) and 2026-09-13 (Artifacts built by released 17.x tooling are REFUSED by the 17.2 runtime: retired-key tombstones fire at artifact parse, and no artifact-ingestion door runs the ADR-0087 conversion that exists for exactly this #12772) addenda as superseding it for metadata at rest and keeps the original in place under Prime Directive [WIP] Add Chinese version of the documentation #13. Exactly dispatch item (1); the file's own convention (ADR-0044 / ADR-0058 form). Correct.
2. Edit 2 — the ninth ## Addendum (2026-09-13). The ruling sentence is quoted verbatim: seat-verified by whitespace-normalised containment against Artifacts built by released 17.x tooling are REFUSED by the 17.2 runtime: retired-key tombstones fire at artifact parse, and no artifact-ingestion door runs the ADR-0087 conversion that exists for exactly this #12772 comment 5443380108 → TRUE. Every symbol anchor resolves on origin/main (git grep, all non-zero): artifact-forward-conversion.ts#applyArtifactForwardConversions and #DEFAULT_FLIPS_NOT_REPLAYED_HERE, engine.ts#canonicalizeStoredFlow (called by registerFlow, 20 hits), stored.ts#applyConversionsToStoredItem and #StoredConversionOptions (an Omit), and both doors (packages/metadata/src/plugin.ts, packages/runtime/src/app-plugin.ts) import the one policy function. The flag inventory「three includeRetired: true literals in runtime source」is exact: four files match, the fourth (packages/spec/src/conversions/types.ts :157) is a JSDoc mention, not a literal. Heading count on origin/main 8 → 9 on this head. The as-built key (declared engines.protocol floor vs the ruling's「authored specVersion」) is RECORDED with a warning marker and attributed, not re-ruled — the right posture for an addendum. The default-flip exclusion is attributed to ADR-0087's field-required-notnull-explicit conversion asserts an implication ADR-0113 abolished — the boot calls it a forward conversion, but its output and the source it prescribes disagree at the storage layer #16693 / app-hidden-to-unpublished is replayed at the artifact-ingestion door, rewriting an authored defineApp({ hidden: true }) into an unpublished app — the default-flip class its own docblock says the retirement flag excludes it from #17885 and the schema-layer residue boundary to the Artifacts built by released 17.x tooling are REFUSED by the 17.2 runtime: retired-key tombstones fire at artifact parse, and no artifact-ingestion door runs the ADR-0087 conversion that exists for exactly this #12772 review comments; both are needed for the entry not to assert a replay the shipped code contradicts. Nothing is decided here that a card did not decide.
3. Nothing widens: no accept-set, no public face, no protocol text moved. Clause-②: no on both carriers; --pair 17997 on main's script → exit 0 at 2026-09-13T10:30Z.

② semver: docs-only; no package touched.

③ boundary flags: open_questions empty. Deviations accepted: anchoring canonicalizeStoredFlow (the symbol that exists) rather than registerFlow (which calls it); recording more than the bare ruling sentence to avoid writing a new false statement; the authored-version gap recorded in the addendum rather than filed a third time (#16693 and #17885 are shut). The dev's ablation of check:adr-symbol-anchors (mutated anchor → exit 1 naming :867, restored by blob hash) shows the anchor gate is non-vacuous on this diff.

Checks on f7d8e9da at 2026-09-13T10:30Z: 33 runs, 0 red, 3 still running (Test Core (1/6), Lint & Repo Gates, Type Check · consumer gates) — read again before landing; Test Core (1/6) is the shard that flaked on an untouched spec test on PR #17990 this hour.

Implemented-by: claude/issue-17894-adr-0087-retired-entry-and-artifact-door
Reviewed-by: session_01DAcomhvR9kKizeYgg89Vo8

Verdict: PASS — both defects of #17894 repaired additively, every recorded fact re-verified on origin/main, nothing decided beyond the cards. Governed (docs/adr/**): draft stays; needs-user-decision + reviewers os-zhuang / hotlong; landing by this seat under ruling C (#17971) once an authorized approval exists and the checks read green.

---

Generated by Claude Code

[claude]

维护者速读(终稿)

改了什么 —— 只动 ADR-0087 一个文件,只加不删(+101/−0)。两处:① 「退役条目被 loader 跳过」那句原文不动,下面加一段引用块指向 2026-07-31 与 2026-09-13 两条附录 —— 说明这句只管作者侧加载路径,静态元数据(sys_metadata 行、构建产物)要回放整条链;② 新增第九条附录,把 #12772 裁的「构建产物入口开一个按版本的窗口」记进 ADR:裁决原句逐字引用(本席核对一致),窗口怎么算(声明的 engines.protocol 下限 vs 运行时版本)、两个入口共用一个函数、默认值翻转不在窗口内、与 schema 层残留剥离的边界、includeRetired 的现存清单 —— 每个符号锚都在 origin/main 上核过。

为什么 —— 这条策略只活在 issue 里,ADR 没记;读到原句就停的人会把它带到它不成立的地方(#17894 的两个缺陷)。

风险 —— 无契约变化、无代码;一处「裁决说 authored specVersion、实现用声明范围下限」的差异是如实记录并标了 ⚠️,不是改裁。

批准即由本席按裁决 C 落地(三个 check 还在跑,落地前再读一次)。要不要批?

---

Generated by Claude Code

[claude]

Ruling C landing step — skills seat (session session_01DAcomhvR9kKizeYgg89Vo8), 2026-09-13T11:29Z. Authorized approval read: os-zhuang APPROVED on head f7d8e9da at 2026-09-13T11:26Z (review 5190544235; not dismissed), who also flipped the PR ready and enqueued it in the same minute. Seat readings at 2026-09-13T11:28Z: ① contract review of record 5652729413 names this head f7d8e9da (unchanged since); ② check-clause2-carriers --pair 17997 exit 0; ③ 40 checks on f7d8e9da, 0 pending, 0 red; ④ needs-user-decision cleared in this pass and read back (labels now documentation, size/m, skip-changeset). Queue ref gh-readonly-queue/main/pr-17997-* present. Landing record follows on card #17894 once origin/main carries (#17997).

---

Generated by Claude Code