Retire the paper metadata-customization protocol with its full coupling set

[os-trump]

Fixes #13135

Retires the paper metadata-customization protocol with the full coupling set the fork report measured. The single-module deletion the original card described does not compile — any compiling PR performs the wider removal — so this PR performs it declared rather than incidentally.

Charter

• Maintainer ruling — [finding] spec ships a three-layer metadata-customization protocol (MetadataOverlaySchema, field-level change tracking) with zero consumers — published reference docs describe an unimplemented customization architecture #12057 comment 5459699497 (2026-08-29), verbatim and untranslated: 「同意」. Retirement under ADR-0049 enforce-or-remove adopted; re-scope explicitly not taken.
• Decision analysis the ruling adopts — [finding] spec ships a three-layer metadata-customization protocol (MetadataOverlaySchema, field-level change tracking) with zero consumers — published reference docs describe an unimplemented customization architecture #12057 comment 5451376436, recommendation A (widened retirement) with its pre-registered execution chain.
• Measurement base — [finding] spec ships a three-layer metadata-customization protocol (MetadataOverlaySchema, field-level change tracking) with zero consumers — published reference docs describe an unimplemented customization architecture #12057 comment 5451357017 (fork report), which established that the narrow option was non-executable and named the couplings removed here.
• Model-level record — ADR-0126 §6.4 supersedes the module: "nothing may build against it".

What is removed

1. packages/spec/src/kernel/metadata-customization.zod.ts — whole module, plus its kernel/index.ts barrel line (replaced by a comment naming the two mechanisms that actually ship).
2. kernel/metadata-plugin.zod.ts — the authorable customizationPolicies and mergeStrategy keys, retired through the spec-property-retirement routes in full: retiredKey() tombstones, RETIRED_KEYS_BY_MAJOR[18] entries, ledgers. Not a bare delete.
3. api/metadata.zod.ts §5 — the Overlay/Customization contracts for REST endpoints no adapter ever served. Section numbering is preserved: ids are claims, not positions.
4. contracts/metadata-service.ts — the optional getOverlay / saveOverlay / removeOverlay / getEffective members typed against MetadataOverlay.
5. kernel/metadata-loader.zod.ts — persistence.overlayWritable, tombstoned (the nested object is not strict, so a plain deletion would strip the key in silence).
6. packages/metadata — the in-memory overlay limb on MetadataManager, its test cases, the 'overlay' feature-log entry, and the three-way-merge ROADMAP.md row (which ADR-0126 rules out rather than defers).
7. type-alias-convention.pin.test.ts — the four vacated Iso408-411 rows, with the machine-checked count re-baselined 837 to 833 in both the prose and the title the runtime companion checks against.
8. Regenerated artifacts: api-surface, export-origins, authorable-surface, authorable-defaults, json-schema manifests, the reference tree (the kernel/metadata-customization page disappears with the module), the strictness-ledger counts, and the skill reference index.

Registered: 10 RETIRED_DEFS_BY_MAJOR[18] entries, 3 RETIRED_KEYS_BY_MAJOR[18] tombstones, the D3 semantic entry metadata-customization-protocol-retired, and a retirement pin test.

Judgment calls, stated because a reviewer should be able to disagree with them

• minor, not major, and prescriptions registered under 18. v17.0.0 was cut before this landed, so the removal ships on the 17.x line under the launch-window convention while the prescription lives at the major boundary where os migrate meta users look. This follows the 18.api__PackageRollbackResponse precedent, whose entry carries the same reconciliation paragraph. It is also the only lawful choice mechanically: check-changeset-no-major.mjs refuses a major bump, and its verdict here is This diff introduces no major bump. Note this reads differently from the Epic: packaged-metadata customization (ADR-0126) — flows first, v17 line #12150 epic's line that the removal "rides the next major (v18)" — that line predates the v17 cut, and the registry major (18) is what it names in substance.
• No D2 conversion for the three tombstoned keys. The conversion chain walks a normalized stack and applyConversionsToStoredItem maps a metadata type onto one of its collections. Plugin and manager configs are neither — PLURAL_TO_SINGULAR has no plugins entry — so a MetadataConversion here would be a transform with no seam that ever runs. The prescription reaches authors through the tombstone and the D3 semantic entry instead. Same reasoning as the sibling kernel/MetadataPluginConfig:additionalTypes entry.
• Issue ids stripped from the three prescriptions. check:doc-authoring flags an internal issue id in customer-facing spec text: a customer reading a parse refusal has no tracker. Each prescription keeps ADR-0049 enforce-or-remove plus its ADR-0126 / ADR-0005 FROM-to-TO mapping, so none is left bare — which that rule requires.
• content/docs/references/kernel/ page count re-declared 31 to 30 in quick-reference.mdx. The curated table's own row count (17) is untouched: no row ever pointed at the deleted page.
• llms.txt re-derived, not digit-patched (CI caught this one). check:llms-txt reddened on the first push: deleting the module takes src/kernel/ from 32 to 31 and the domain-summed total from 208 to 207, in a hand-kept file that ships to AI consumers with deliberately no generator. Both rows were re-read per the gate's own instruction rather than having their numbers swapped: the heading's method prose stays true and is what explains 207 against the 208 .zod.ts files on disk (src/stack.zod.ts sits outside any domain directory), every other domain row was re-counted independently and already matched, and the kernel row's Key Schemas column never named the removed module. A third correction the gate does not catch: the section-6 contract table lists IMetadataService methods and overlay was one of them — true at the base commit (4 members), false now (0). Left alone it would have shipped inside the npm tarball telling an AI consumer to generate metadataService.saveOverlay(...). Dropped. ⛔ Deliberately not folded in: the same row also claims delete, which resolves to 0 members at the base commit too (the interface spells it unregister) — pre-existing and unrelated, so it is reported rather than fixed here.
• The WIP history could not be squashed. This branch carries three wip: commits pushed by the predecessor dispatch before it terminated. Rewriting them requires a force-push, which AGENTS.md multi-agent rule 3 forbids without exception ("Never git push --force / --force-with-lease"). They are therefore still on the branch. Please compose the squash message from this PR's title and body rather than from the concatenated commit list.

Explicitly not in this PR

• ADR-0126 §6.4's factual correction — a separate governed-surface card owns it (ADR-0126 §6.4 factual correction: "consumed by zero runtime packages" was instrument blindness — the paper customization module had a build-against consumer in packages/metadata at the measured ref #13136, PR docs(adr): correct ADR-0126 §6.4 — the paper protocol's zero-consumer reading was instrument blindness #13139 in flight). ⛔ Not edited here.
• objectui's comment-only mention — cosmetic, no action.
• The inline vocabulary twins that do not import the module (api/package-api.zod.ts mergeStrategy enum, kernel/package-upgrade.zod.ts) — separately declared surfaces, untouched.

Reverse verification

A compile probe placed inside packages/metadata so @objectstack/spec resolves through the package exports map into the built dist, not src/:

• Positive controls — MetadataPluginConfigSchema from @objectstack/spec/kernel and MetadataBulkResponseSchema from @objectstack/spec/api both compile clean, so the entries resolve and the negative legs below are readings rather than a broken module path. An earlier run of this probe from a directory with no resolution path failed its control and was discarded.
• Negative legs — TS2724: '"@objectstack/spec/kernel"' has no exported member named 'MetadataOverlaySchema', the same for the MetadataOverlay type, and TS2724: '"@objectstack/spec/api"' has no exported member named 'MetadataOverlayResponseSchema'.
• Tombstones, type side — all three retired keys resolve to undefined-only on the authoring side, and writing a value fails: TS2322: Type '{ type: string; }[]' is not assignable to type 'undefined'. The control asserting a surviving key is not undefined-only passes, and deliberately flipping that control to the wrong expectation makes it fail, so the harness is falsifiable.
• Tombstones, runtime side — MetadataPluginConfigSchema.safeParse refuses at path=customizationPolicies, expected=never, with the prescription itself as the message.
• Artifacts — api-surface/kernel.json carried 17 rows matching the retired protocol at the base commit and carries 0 now; content/docs/references/kernel/metadata-customization.mdx is gone, with 0 residual references in the kernel meta.json, the kernel index and the references index.

Validation

All readings below are at 86d100046, the branch head — taken after the second origin/main merge and after the final commit, not before it.

A note on that second merge. The charter predicted this collision and it happened: PR #13133 (from #12384) landed on main while this branch was in validation, and its content/docs/kernel/contracts/metadata-service.mdx edit restored the saveOverlay / getEffective teaching block in the Org-Level Customization section. Resolved in favour of deletion, as the charter directs — the retired members' teaching goes with them. The page now carries the ADR-0005 org-overlay description in that slot. A sweep of content/ finds no remaining call site for any of the four retired members.

Gate family derived mechanically, no hand-fed paths: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack, three-dot semantics against the merge base. Exit codes were captured before any pipe in every run.

Quoting the gates' own verdict lines:

• pnpm --filter @objectstack/spec check:generated — ✓ All 14 generated artifacts are up to date. (covers api-surface, export-origins, authorable-surface plus its .base.json anchor, json schemas, content/docs/references/**, skill docs and refs, the strictness ledger, liveness and test-typecheck)
• pnpm --filter @objectstack/spec typecheck — clean, and check:test-typecheck: OK — @objectstack/spec's test layer compiles under packages/spec/tsconfig.test.json
• pnpm --filter @objectstack/spec check:llms-txt — 97 claim(s) re-derived — every advertised symbol resolves against api-surface/ (17 entry points), every subpath is a real exports key, the inventory matches src/ (14 domains, 207 schemas) and the package table matches the workspace (68 published).
• pnpm check:type-check-debt --re-measure — OK — 31 ledger entr(ies) re-measured in 245.6s, 1570 raw tsc error(s) total, none above its recorded number. with surplus: none
• pnpm check:doc-authoring — ✓ doc authoring guard: 13326 customer-facing string(s) across 686 spec sources clean — no internal issue-id references.
• pnpm check:quick-reference-counts — ✓ ... every "(N of M schemas)" heading matches its table AND content/docs/references/
• pnpm --filter @objectstack/spec check:skill-examples — ✅ 260 prose examples type-check across 3 surface(s)
• pnpm check:i18n — OK (9 package(s) — all bundles in sync, no undeclared authoring keys).
• node scripts/check-adr-0087-registration.mjs, check:liveness, check:empty-state, check:strictness-ledger, check:variant-docs, check:meta-url-spelling, check:type-check-coverage, check:dual-build-cjs-loads, check:nul-bytes — all exit 0
• Every one of the 11 source audits check:generated declares it does not run was executed this round (llms-txt, empty-state, skill-examples, template-manifests, variant-docs, exported-any, dual-source-exports, entry-nameability, browser-reachable-entries, scripts-typecheck, objectui-pin-citations) — all green. Running only a subset of that list is how the llms.txt staleness reached CI.
• The remaining 55 derived families ran green in one sweep at this commit (re-run after the merge, not carried over from an earlier head).

Two families in the derived set were NOT MEASURED here, and neither is a pass:

• node scripts/check-test-completeness.mjs — PREREQUISITE NOT MET — this gate grades a saved turbo run test log, and no log was named (exit 3 since fix(scripts): refuse a logless check-test-completeness run instead of answering exit 1 #13152; CI tees the log and passes the path).
• node scripts/pm/check-half-states.mjs — PREREQUISITE NOT MET — the token in the environment is not a valid GitHub credential, exit 3, whose own text says "no reading at all". The lint-required pnpm check:pm-half-states is green.

check:react-declaration-parity is the standing EXTERNAL_INPUT_REQUIRED case: its right-hand side is objectui's sdui.manifest.json, which this repo cannot produce.

Suites, both at 86d100046: packages/spec — Test Files 443 passed (443), Tests 11746 passed (11746); packages/metadata — Test Files 38 passed (38), Tests 669 passed (669). packages/metadata has no typecheck script — it is covered by the DEBT ledger, so its type story is the ratchet verdict above, not a per-package script that would have matched nothing and exited 0.

skills/** readings

The diff touches one published-skill file, and it is a generated index (gen:skill-refs) whose line leaves with the module it names.

• Changed file skills/objectstack-platform/references/_index.md: 62 to 61 lines (net -1).
• Whole package, sum of every SKILL.md under skills/objectstack-platform/: 1286 to 1286 lines (unchanged).
• Whole published tree, sum of every SKILL.md under skills/: 10515 to 10515 lines (unchanged).

Net is a deletion, so no expansion budget is consumed.

Landing posture — please read before touching the merge controls

• ⛔ This PR stays DRAFT. Do not mark it ready, do not enable auto-merge, do not enqueue it. Waiting in draft is the intended end state.
• needs:contract-review is attached and stays. Clause-② applies on both legs: PATH (packages/spec/src/**) and CONTENT (a public-export deletion narrows the published face).
• The diff touches a governed surface — skills/objectstack-platform/references/_index.md is under skills/**, which AGENTS.md Prime Directive 14 names. One path hit forks the whole PR, so ⛔ no AI seat merges, queues, or arms auto-merge on it, and landing needs either an approval pinned to the current head by a GOVERNED_APPROVERS account or the maintainer's hand-merge. The governed file cannot be split out: check:skill-refs compares that generated index against the spec source, so the line must leave in the same commit as the module.
• Implementation tier was opus under the recorded quota-exhaustion exemption (maintainer 2026-08-13, verbatim: 「fable 如果用完了,可以用 opus」), after the fable-tier dispatch terminated on an HTTP 429; needs:contract-review is the compensating control.

Out-of-scope finding

Filed unassigned: #13185 — ADR-0005 still names metadata-customization.zod.ts as a kept, future-phase model. Governed surface, so it is not touched here; it may fold into #13136's ADR pass if a reviewer prefers one governed PR.

Authored by the os-dev seat of session session_01LpRNHxWZgSUgVnFT9mQQo4 (https://claude.ai/code/session_01LpRNHxWZgSUgVnFT9mQQo4), continuing the quota-terminated dispatch on the predecessor's surviving branch. This trailing line is deliberate: on this repo a body PATCH has been measured to trim the attribution footer, so the session URL is kept in prose where it survives.

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/metadata, @objectstack/spec, touching 40 documentable anchor(s). ⚠️ 25 changed file(s) yielded no anchor (packages/metadata/ROADMAP.md, packages/spec/api-surface/api.json, packages/spec/api-surface/kernel.json, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

11 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/api/client-sdk.mdx (via MetadataPlugin (symbol))
• content/docs/api/index.mdx (via MetadataPlugin (symbol))
• content/docs/automation/flows.mdx (via MetadataPlugin (symbol))
• content/docs/concepts/metadata-lifecycle.mdx (via IMetadataService (symbol), MetadataManager (symbol))
• content/docs/kernel/contracts/cache-service.mdx (via IMetadataService (symbol))
• content/docs/kernel/contracts/index.mdx (via IMetadataService (symbol))
• content/docs/kernel/contracts/metadata-service.mdx (via IMetadataService (symbol), MetadataOverlay (symbol), getEffective (symbol), getOverlay (symbol), removeOverlay (symbol), saveOverlay (symbol))
• content/docs/kernel/index.mdx (via IMetadataService (symbol))
• content/docs/kernel/services-checklist.mdx (via MetadataPlugin (symbol))
• content/docs/plugins/adding-a-metadata-type.mdx (via MetadataManager (symbol))
• content/docs/protocol/kernel/metadata-service.mdx (via MetadataManager (symbol), MetadataManagerConfigSchema (symbol), MetadataPlugin (symbol), MetadataPluginConfigSchema (symbol), saveOverlay (symbol))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/implementation-status.mdx (via MetadataManager (symbol), MetadataPlugin (symbol))
• content/docs/releases/v17.mdx (via MetadataManager (symbol))

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.

What this run could not see

• 25 changed file(s) yielded no anchor (packages/metadata/ROADMAP.md, packages/spec/api-surface/api.json, packages/spec/api-surface/kernel.json, …) — pages documenting those are invisible to this run
• 6 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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 — 128 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 47d9b77b1c957aeb47fc67b1fa15c8eef2110af9 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from e6270d951a9986e74ab951f80386232f5f4fc093 — the merge of head 86d1000469ac5b87472f238dac2b16ecc043cc4c into base 47d9b77b1c957aeb47fc67b1fa15c8eef2110af9, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin e6270d951a9986e74ab951f80386232f5f4fc093 && git checkout e6270d951a9986e74ab951f80386232f5f4fc093
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 47d9b77b1c957aeb47fc67b1fa15c8eef2110af9 86d1000469ac5b87472f238dac2b16ecc043cc4c && git checkout -B drift-repro 47d9b77b1c957aeb47fc67b1fa15c8eef2110af9 && git merge --no-ff 86d1000469ac5b87472f238dac2b16ecc043cc4c

node scripts/docs-audit/affected-docs.mjs --json 47d9b77b1c957aeb47fc67b1fa15c8eef2110af9

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 47d9b77b1c957aeb47fc67b1fa15c8eef2110af9 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 33253819694 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Test Core (1/6) — 失败步骤: Run this shard's tests

  @objectstack/cli:test:  FAIL  test/serve-publishes-bound-port.e2e.test.ts > #13062 the non-zero half — nothing an ordinary boot publishes may move > follows the DEV AUTO-SHIFT onto the port it really 
    ↳ 失败原因: @objectstack/cli:test: Error: ENOENT: no such file or directory, open '/tmp/os-bound-port-home-W8xEQm/runtime.env_local.json'
  

↳ 失败原因 是判读的关键：超时（Test timed out in … / Hook timed out in …）多半是负载/时序，不是本 PR 的回归；
断言（AssertionError: …）才指向真实的行为改变。两者的 FAIL 行长得一模一样，只有这一行能区分。

跨 PR 相同签名（24h，按失败测试文件聚合）：

• test/serve-publishes-bound-port.e2e.test.ts — 24h 内已弹出 21 个 PR（feat(spec): re-introduce fieldGroups[].visibleWhen with its enforcement side #13030、Hold the isSystem census page to the code: committed AST census, population gate, converted anchors #13051、docs(adr): ADR-0129 records the enforced object-naming contract; decision letters for the letter-cited ADRs #13067、fix(ci): count speculative-stack inheritance as one hit in merge-queue triage #13107、fix(rest): the /data declared-4xx body carries human language in error, not the ADR-0111 CODE: prefix #13124、feat(metadata): the artifact door registers stack-declared capabilities (#12892 step 1) #13125、fix(tooling): declare kebab-case diagnostic codes a separate vocabulary, in one place #13130、docs(kernel): teach the dot-qualified view item name in metadata-service.mdx #13133、docs(devx): correct the stale collector claim on the js-comment-mask entry #13140、fix(scripts): close an ADR-0087 framed region at the same or a shallower heading, not at any heading #13142、feat(pm): record a passive boot marker on every verify-lock invocation, so cross-restart evidence about /tmp accumulates by itself #13145、fix(client): declare the response the meta reset door actually sends on both deleteItem twins #13148、fix(scripts): refuse a logless check-test-completeness run instead of answering exit 1 #13152、chore(pm): unstale the release-aftercare ceiling comment in the line ratchet #13161、docs(objectui): repair the section-tier and action-tier visibility examples on the two protocol pages #13162、feat(lint): ratchet the relationship carrier shape at field-def positions #13174、fix(spec): widen AnalyticsResultResponseSchema and TriggerFlowResponseSchema data to producer-contract parity #13184、Retire the paper metadata-customization protocol with its full coupling set #13186、fix(service-analytics): wire the typecheck script and clear the 10 errors the unwired gate hid #13188、docs(spec): state at the renderer that section-grammar headings are not stable anchors #13199、fix(spec): judge react-block registry inputs against the full node contract #13202），分属 17 条投机栈 ⇒ 17 次独立命中。汇总 issue：Queue-flake anchor: test/serve-publishes-bound-port.e2e.test.ts #13221（新建）
• ⚠️ 24h 评论账本没读完（超过 5 页仍未读到窗口尽头），所以上面的「不同 PR 数」是下界，不是全量。

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 23 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」；已有汇总 issue ⇒ flaky/环境问题实锤，去那张 issue 上谈，修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)