docs(metadata): correct the retiredKey tombstone's minor version in the published 17.3.0 CHANGELOG entry

[baozhoutao]

Closes #16277

What

packages/metadata/CHANGELOG.md's ## 17.3.0 section (entry 54e2d36, #12772) described a measured pre-fix incident as:

... and spec 17.2.0's retiredKey tombstone refused the boot with no operator remedy ...

packages/spec/CHANGELOG.md files the allowRestore/allowPurge object-permission retirement (8af88dd, #12497, ADR-0049) under its own ## 17.3.0 section; its ## 17.2.0 section mentions neither key nor #12497 (grep count 0 over that section). The two changelogs disagreed on which minor version the tombstone shipped in.

Why

Triage located both entries by section-heading structure (spec's 17.3.0 heading precedes the entry, its 17.2.0 heading follows it) and showed the CHANGELOG evidence points at one reading, but drew a deliberate boundary: "CHANGELOG absence is not release absence" — it does not prove the code. The PM dispatch comment on #16277 ran the missing tag-level check:

• @objectstack/cli@17.2.0: packages/spec/src/security/permission.zod.ts:157-158 declares allowRestore/allowPurge as live, ordinary z.boolean() fields — not retiredKey(). Zero files under packages/spec/src/migrations/entries/retired-keys/ match either name at that tag.
• @objectstack/cli@17.3.0: packages/spec/src/migrations/entries/retired-keys/18.security__ObjectPermission__allowRestore.ts exists, headed #12497 — ADR-0049 enforce-or-remove.

I independently reconfirmed this on origin/main: git log --oneline --all -- 'packages/spec/src/migrations/entries/retired-keys/*allowRestore*' returns 8af88ddb0b feat(spec): retire the allowRestore / allowPurge object-permission bits (#12497, ADR-0049) (#12619) as the sole introducing commit, matching spec's ## 17.3.0 entry hash (8af88dd) exactly — no earlier commit touches that path.

⇒ The tombstone shipped with spec 17.3.0, not 17.2.0. The metadata entry's minor version is a slip.

The fix

Per the principle the filer, triage and the PM dispatch all converge on: cite the major version in prose, not the minor, unless the minor distinction itself carries information. It doesn't here — the incident is about the tombstone existing at all, not about which 17.x introduced it. The platform's own parse-time removal message already does this, and it is the one sentence both CHANGELOGs already agree on:

objects.OBJECT.allowRestore was removed in @objectstack/spec 17 (ADR-0049) ...

So spec 17.2.0's → spec 17's. One word, one line. The sentence no longer depends on a minor version that can be wrong.

Hard-stop condition: is hand-correcting a published CHANGELOG entry settled practice here?

Triage and the PM dispatch both flagged this as a hard stop — CHANGELOGs are changeset-generated, not hand-maintained, and this repo's discipline is release notes written centrally at release time. I searched git log on both CHANGELOG files for precedent before touching anything. It is settled practice, exercised repeatedly:

• eabdd66f45 — "correct three false sentences in the published 17.3.0 release text" (docs(changelog): correct three false sentences in the published 17.3.0 release text — the reversed depends_on justification and the ListView binding paragraph in both CHANGELOGs #16881) — direct in-place text replacement across two packages' CHANGELOGs, explicitly reasoned: "Released CHANGELOG text is treated as release-owned, so this is a dedicated docs-only PR riding on no code change."
• c3b6da4bca — "correct the offer-set claim in the icon-withdrawal CHANGELOG entry" (fix(spec): correct the offer-set claim in the icon-withdrawal CHANGELOG entry #15454) — same shape: "Text-only correction... no code, no test, no changeset."
• 222be390bb — "correct the withdrawn os migrate meta claim in the published 17.0.0 app-area retirement entry" (docs(spec): correct the withdrawn os migrate meta claim in the published 17.0.0 app-area retirement entry #11644) — same shape, plus a > **Correction:** blockquote convention for cases where the surrounding sentence needs to record what the released artifact originally said.
• eb91ebacbc — an earlier instance of the same pattern ([spec] #4610/#4535-C3 Notification 退役的墓碑与 changelog 需事实更正:objectui 侧确有 export … from 消费者;FROM→TO 指引会引导编译失败的替换 #5781, [spec] packages/spec/CHANGELOG.md 的 17.0.0-rc.2 段落仍带着「the server does not walk areas」—— GA 段落改对后同一文件会自相矛盾 #5809).

This PR follows the eabdd66f45/c3b6da4bca shape: a direct, minimal, in-place word substitution, no blockquote annotation, because nothing here needs to preserve a record of "what the released text used to claim" beyond what this PR description and its commit message already do — the change is a single version-number word, not a restated fact.

Out of scope (per the dispatch brief)

The issue's third measurement (ObjectPermissionSchema.safeParse: presence/truthiness asymmetry on allowRestore/allowPurge) is explicitly out of scope for this card. I re-ran it (pnpm --filter @objectstack/spec exec tsx against packages/spec/src/security/permission.zod.ts's ObjectPermissionSchema) and confirmed — with a more precise characterization than the original report (it's not a truthy/falsy split; only the literal false parses, everything else refuses, and no post-parse consumer guard can ever observe either key) — and filed it separately: #17425.

Verification

• packages/metadata/CHANGELOG.md is the only file touched: git diff --stat → 1 file changed, 1 insertion(+), 1 deletion(-).
• pnpm check:nul-bytes — pass (exit 0).
• pnpm check:published-files — pass (exit 0); confirms CHANGELOG.md is a required-but-not-content-scanned package artifact.
• pnpm check:doc-authoring — pass (exit 0); no internal issue-id introduced (spec 17's carries no #NNNN).
• No test or gate parses packages/metadata/CHANGELOG.md content for correctness — the gates that name CHANGELOG.md (check-published-files.mjs, check-published-readme-exports.mjs) treat it as a required, opaque, packed artifact, never scan its prose. The gates that DO parse packages/spec/CHANGELOG.md prose for release tooling (check-release-notes.mjs, check-release-page-status.mjs, check-release-section-coverage.mjs, sync-release-index-currency.mjs) key on packages/spec/CHANGELOG.md specifically, not packages/metadata/CHANGELOG.md, and none of the four appear in this diff's derived gate set (node scripts/pm/dispatch-gates.mjs --commands).
• No build/typecheck applicable: the diff touches no packages/*/src/**, so no package's dist/ is affected.
• skip-changeset label applied — measured, not asserted: no published surface moves (prose-only CHANGELOG correction), matching the precedent PRs above, all of which shipped without a changeset.

Clause-②: no

---

🤖 Generated with Claude Code

https://claude.ai/code/session_012GKcPZbMoGq7WPzKLfRBTU

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/metadata/CHANGELOG.md), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/metadata/CHANGELOG.md) — pages documenting those are invisible to this run
• 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 — 15 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 92242041e738eec91b2ccd4e29c845682b53bb4a → packageMentionDocs.