test(spec): under a prerelease package label the retired-after census refuses the release triple, and the retiredAfter TSDoc names the newest published stable release

[objectstack-fleet]

Fixes #23042
Clause-②: no (the published accept set does not change: retiredAfter keeps its ${number}.${number}.${number} type; the census is a repository test, and the TSDoc states the rule the PUBLISHED rule already implies)

Under a prerelease package label (18.0.0-next.N, Changesets pre mode), a new retirement now has a stamp that tsc, the census and the PUBLISHED rule all accept: the newest published stable release, which sits below the label's release triple. The census reads the label with semver precedence (x.y.z-PRE precedes x.y.z), so 18.0.0 is refused now, during the prerelease. Before this change it passed until the census refresh after 18.0.0 ships. The retiredAfter TSDoc states the rule for both labels.

This follows triage's direction on the card (comment 6124786465) and card option B. The governed playbook half (.claude/skills/spec-property-retirement/SKILL.md:204-205) is #23057's surface; #23057 remains open and this PR does not edit that file.

What changed

• packages/spec/src/conversions/retired-after.census.test.ts
  • One helper, atOrBelowLabel(v, label). A stable label x.y.z admits x.y.z, as before. A prerelease label admits only versions strictly below x.y.z. All three comparisons against the label use it: the census well-formedness check, the "never above the package label" check, and the UNPUBLISHED release-pending range.
  • The UNPUBLISHED rule is now one function, unpublishedStampProblem(v, label, lastCensused). The label is an argument, so tests can simulate any label without depending on package.json. Under a prerelease label the range is [last censused, x.y.z). A prerelease label never takes the exact-label branch: the census never records a prerelease tarball, and that branch's stamp would be the release triple.
  • Failure text under a prerelease label tells the author to stamp the newest published stable release, never the release triple. The stable-label text is unchanged byte for byte (measured below).
  • Three new pins under a simulated label:
    • A stable label keeps the inclusive range and the exact-label rule.
    • A prerelease label refuses 18.0.0 and 18.0.1 and admits 17.4.0, 17.7.0 and 17.7.1, under both 18.0.0-next.0 and 18.0.0-next.12. It keeps the range open even when the census holds 18.0.0.
    • atOrBelowLabel on both labels.
  • Docblock: the UNPUBLISHED rule and the label paragraph now state the rule. The sentence that deferred the question to the artifact door ("this file follows that rule rather than settling it") is gone. The paragraph also covers the card's unmeasured case: a stable 17.x maintenance release published during the 18 prerelease without the retirement still accepted the old shape. Once it is censused, it raises the range's lower bound, and the entry is re-stamped to it. After GA, the PUBLISHED rule names that release as "just before" 18.0.0, because the census sorts stable releases by semver.
• packages/spec/src/conversions/types.ts: the RetiredConversionState.retiredAfter TSDoc. The old sentence was "it is the package's version label at the moment the retirement lands", which has no value that type-checks under a prerelease label. It now says the newest stable release at the moment the retirement lands. Under a stable label that is the label itself. Under a prerelease label it is the newest published stable release, below x.y.z. The maintenance-release case is stated too.
• .changeset/23042-retired-after-prerelease-stamp.md: '@objectstack/spec': patch. The TSDoc ships: before this change, dist/types-*.d.ts and .d.mts carried the old sentence (2 files). After the rebuild they carry the new text once each, and the old sentence 0 times. The census test ships nothing: files[] publishes dist and src/**/*.zod.ts, and retired-after.census has 0 hits in dist/**/*.js.

Not touched: packages/spec/src/conversions/registry.ts and the census JSON (no row needed). check:generated names no stale artifact.

Measurements

All runs on this branch. Single-file runs use pnpm --filter @objectstack/spec exec vitest run --project local --maxWorkers=2 src/conversions/retired-after.census.test.ts. Every mutation went through node scripts/ablation-replace.mjs, and every restore was proven by the tool: blob equals HEAD and git diff HEAD is empty.

• Premise reproduced at base 21c86444e, before any edit. With the label set to 18.0.0-next.0 (blob 9eba400e to 73244d5e) and declared-index-unique-scope stamped 18.0.0 (blob 96d69e4b to babee78a), the census gave Tests 9 passed (9). Base admits 18.0.0.
• Reverse verification at 2e7bb5fb2, same two mutations: Tests 2 failed | 10 passed (12). Red as expected. The "never above the package label" check and the UNPUBLISHED check both name declared-index-unique-scope.
• Real registry under a prerelease label (label mutation only): Tests 12 passed (12). No retired entry stamps a value this narrowing refuses.
• Ablation 1: the prerelease arm of atOrBelowLabel changed from "cmp(v, release) less than 0" to "less than or equal to 0" (blob 7607c543 to c094d14e). Result: Tests 2 failed | 10 passed (12); the prerelease pin and the precedence pin go red. A first attempt passed a repo-relative test path, ran no test file ("FILTER SELECTED NOTHING"), and counts as void.
• Ablation 2: the !prerelease && guard on the exact-label branch removed (blob 7607c543 to 3b70eb08). Result: Tests 1 failed | 11 passed (12); the "census holds 18.0.0" pin goes red.
• Stable-label text is byte-identical. The base census file was copied in temporarily and run beside the new one under the same mutations, then deleted (tree clean afterwards).
  • Label 17.4.0 (census caught up, so the exact-label branch): the 22-entry UNPUBLISHED failure lists are byte-identical.
  • Real label 17.7.0 with one stamp at 17.8.0 (the pending branch): the range message outside [17.4.0, 17.7.0] — refresh the census (...) is identical.
  • The "never above the package label" message differs only in vitest's own matcher suffix (expected false to be true instead of expected 1 to be less than or equal to 0). The author-facing part, ID: retiredAfter V > label 'L', is identical.
• Stamps on main (from ALL_CONVERSIONS, at 21c86444e, which includes PR feat(spec)!: retire an email template's category and isSystem — the grouping and the built-in flag nothing read (#22876) #22990): 117 retired entries out of 134. The highest stamp is 17.7.0, on 5 entries; no stamp reaches 18.0.0. packages/spec/package.json reads 17.7.0, and .changeset/pre.json has mode: pre, tag: next.

Tests and gates (head e10a43372, merge base bcebd8409)

• src/conversions at e10a43372: Test Files 11 passed (11), Tests 448 passed (448).
• pnpm --filter @objectstack/spec typecheck at e10a43372: exit 0. check:test-typecheck is OK. The census test is in the tsconfig.test.json program (--listFilesOnly: 1 hit) and has 0 debt rows.
• Whole spec local project at 2e7bb5fb2, before the second main merge: Test Files 659 passed (659), Tests 19990 passed | 1 todo. Declared narrowing: at e10a43372 that run was cut by the 595 s foreground cap under lock contention. The merge brought in spec files from other PRs and changed none of this diff's files, so that run is left to CI.
• pnpm --filter @objectstack/spec build && check:generated at e10a43372: All 14 generated artifacts are up to date.
• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 83 commands at e10a43372. All were run with exit codes captured before any pipe; --ran reports 83 derived, 81 run, 1 NOT-MEASURED, 1 UNRUN.
  • 81 exit 0. That includes check:plugin-teardown-shape --self-test, after a git fetch --depth=1 of its pinned fixture commit; check:lean-entry-closure, after an objectql closure build; and check:query-options-erasure, re-run alone with a longer cap.
  • NOT MEASURED: check:dual-build-cjs-loads. Reason: exit 3, PREREQUISITE NOT MET, it needs a whole-workspace dist. This diff changes no build input it reads.
  • NOT MEASURED: check:type-check-debt. Reason: whole-workspace build, CI owns it.
  • --ran also printed a stale-tree note: origin/main moved 7 commits past this head during the run (to 287fd6e5d). The one derived-from file that changed is scripts/engine-double-contract.pinned.json. This diff adds no engine double.
• Lint, narrowed to the 2 touched TypeScript files: eslint --no-inline-config --format json reports files 2, errors 0, warnings 0. Both files are in the population (--print-config resolves 4 and 5 rules). No type-aware linting is configured (no parserOptions.project or projectService), so this diff cannot change the verdict on any untouched file. Repo-wide pnpm lint is CI's.
• A control-byte self-scan of the 3 changed files has 0 hits, and check:nul-bytes exits 0.

Acceptance notes

Sweep of shipped sentences that state the stamp rule. git grep covered packages/spec/src, packages/metadata-core, packages/spec/scripts, scripts and content/docs, for "version label", "package label", "label at the moment" and retiredAfter. Each hit is either fixed here or listed below as outside this PR's file surface.

• packages/spec/scripts/build-retired-after-census.ts, header section "When to run it". It describes the release-pending tolerance as [last censused release, package.json label]. Under a prerelease label the upper bound is now exclusive of the release triple. The section defers to the test's docblock, and the script is not published. Outside this card's file surface. Noted, not filed.
• packages/metadata-core/src/artifact-forward-conversion.ts module docblock (the M.0.0 bullet) and artifact-forward-conversion.test.ts (the major-step block's docblock). Both say that during the prerelease "the package label still names the last 17.x release". That holds only until the first pre-mode Version Packages PR writes 18.0.0-next.N. Their stamp half ("stamped at or below that label", meaning the last 17.x release) agrees with this rule. The test docblock's "stamped at the prerelease label" means 17.7.0. The door's verdicts do not depend on the stamp for step-18 entries. Noted, not filed.
• packages/metadata-core/CHANGELOG.md:489, a released entry: "the package's own version label at that moment". It was accurate for the stable labels of its release and is release-owned. No action.
• .claude/skills/spec-property-retirement/SKILL.md:204-205 ("packages/spec/package.json 的当前版本标签"). This is skills(spec-property-retirement): under a prerelease package label, the retiredAfter checklist item stamps the newest published stable release — the governed half of #23042 #23057's surface; that card is blocked on this one.
• docs/adr/0087-metadata-protocol-upgrade-contract.md (the 2026-09-30 amendment) defines retiredAfter as "the last published @objectstack/spec whose authoring surface still accepted the old shape". That agrees with this rule, so no finding.

The PR body is written once, at creation.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 141 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 287fd6e5d054b9b1efa80f08f9e5be609edb32c2 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from d4f411b218e7d1b70ba0f82ff5aa04287ea4c504 — the merge of head e10a433726204b9a93358021a4a8d68218b8f211 into base 287fd6e5d054b9b1efa80f08f9e5be609edb32c2, 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 d4f411b218e7d1b70ba0f82ff5aa04287ea4c504 && git checkout d4f411b218e7d1b70ba0f82ff5aa04287ea4c504
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 287fd6e5d054b9b1efa80f08f9e5be609edb32c2 e10a433726204b9a93358021a4a8d68218b8f211 && git checkout -B drift-repro 287fd6e5d054b9b1efa80f08f9e5be609edb32c2 && git merge --no-ff e10a433726204b9a93358021a4a8d68218b8f211

node scripts/docs-audit/affected-docs.mjs --json 287fd6e5d054b9b1efa80f08f9e5be609edb32c2

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

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: e10a433726204b9a93358021a4a8d68218b8f211
Local-runs: none

PR #23130 for card #23042, read on 2026-10-13T03:01Z: the card body and all 4 comments (triage 6124786465, claim 6126172325, os-dev-report 6137194016, seat ACCEPT 6137230536 — the last judged independently, not adopted), the PR body, its 3-file list, the net diff against main (the GitHub diff is byte-identical, modulo index lines, to git diff from the merge base bcebd84, and origin/main at 287fd6e has not moved either non-changeset file since that base, so the net diff is exactly these 3 files, +127/−34), and the 39 check-runs on the head. Sentences were verified against origin/main and the fetched head read-only. Nothing was built, run or re-run.

① Derived judgments

Every accept-set and public-surface movement the diff implies, each judged:

• packages/spec/src/conversions/types.ts (+17/−5): TSDoc only, on RetiredConversionState.retiredAfter. The member's type ${number}.${number}.${number} is unchanged (head line 297); RetiredConversionState is file-internal (no export, line 232) and reaches consumers only through the exported union MetadataConversion (line 313, re-exported by conversions/index.ts:24). No Zod schema, JSON Schema, runtime code, api-surface file (git grep retiredAfter in packages/spec/api-surface at the head: no hit) or generated artifact moves. The only published movement is the doc comment inside dist/*.d.ts (dist is in files[]). Accept set: unchanged — right. Public surface: text only — right.
• retired-after.census.test.ts (+105/−29): a repository test, not shipped (files[] publishes dist, json-schema, liveness, prompts, src/**/*.zod.ts and the listed docs; no test file). The rule it now enforces, read off the code rather than the report:
  • atOrBelowLabel(v, label): a stable label x.y.z admits v at or below x.y.z; a prerelease label x.y.z-PRE admits only v strictly below x.y.z. It bounds all three label comparisons: census well-formedness (line 178), "never above the package label" (line 190) and the UNPUBLISHED range (line 140).
  • unpublishedStampProblem(v, label, lastCensused): under a stable label the two old branches survive with identical predicates — the exact-label branch when the census has caught up (cmp(release, lastCensused) at or below 0, which is the old !pending), else the inclusive range [lastCensused, x.y.z]; the failure strings are the old strings. Under a prerelease label the exact-label branch is never taken (the census holds stable releases only, so its tarball is never censused) and the range is [lastCensused, x.y.z): x.y.z is refused now, and the newest published stable release passes. This is exactly the card's ruled direction (triage 6124786465: under a pre-mode label a new retirement stamps the newest published stable release, never the label; the interim range excludes the prerelease's own release triple, so 18.0.0 is refused now; nothing changes under a stable label). Right.
  • Extending the strict reading to the well-formedness and "never above the label" checks (the dev's deviation 1) is right, not scope creep: with the range check alone, 18.0.0 under 18.0.0-next.N would still pass the check titled "never above the package label", and a censused 18.0.0 beside a prerelease label is a contradiction the well-formedness check should name.
• Could a test or gate pass while the rule is wrong? Today's label is stable (17.7.0, pre.json is mode: pre / tag: next but no version pass has run), so the real-registry checks exercise only the stable arm. The prerelease arm is reached by the three new simulated-label pins, which call the same two functions the real checks call (not copies), on 18.0.0-next.0 and 18.0.0-next.12: 18.0.0 and 18.0.1 refused, 17.4.0/17.7.0/17.7.1 admitted, the exact-label branch never taken even with the census at 17.7.0 or 18.0.0. The dev's two ablations (strict arm relaxed to inclusive; !prerelease guard dropped) each went red, so the pins bind the production predicates. A stable-label regression is bound by the inclusive/exact pin. The only unpinned text is the PRERELEASE message suffix, on which no verdict depends. No green-while-wrong path found.
• The artifact door is not touched and needs no change. Its window (metadata-core/src/artifact-forward-conversion.ts:37-38) replays an entry when floor is at or below E.retiredAfter, or when floor = M.0.0 and E.toMajor = M. Every entry on main stamped 17.7.0 (5 of 117 retired entries, all 5 toMajor: 18) replays for a ^18 floor through the major-step arm whatever its stamp, and the door's own module docblock already assumes a prerelease retirement is "stamped at or below" the last release of the previous line — the very rule this PR states. The unreleased .changeset/23001-prerelease-artifact-window.md on main says the same ("every retirement that lands during the v18 prerelease is stamped with the last 17.x release"). Consistent.
• Real registry today: no verdict changes (stable label; the dev's byte-identical stable-label failure lists at 17.4.0 and 17.7.0; src/conversions 448/448 at the head per the report). The first pre-mode label will be the first real exercise of the prerelease arm; the pins already hold it.
• Shipped sentences, all consistent with each other and with the rule. TSDoc (stable label: the label itself; prerelease label: the newest published stable release, below x.y.z, never the label and never x.y.z; 17.7.0 under 18.0.0-next.N; PUBLISHED entries: the stable release just before the first tarball carrying them retired; a 17.x maintenance release during the prerelease becomes the value on census refresh), the census docblock (same, plus the [last censused release, release triple) tolerance) and the changeset (same) agree. The maintenance-release clause is right by the census mechanics: the committed census is held in ascending semver order (well-formedness check), so a 17.7.1 published without the retirement sorts just before 18.0.0 and becomes "just before the first tarball that carries it retired", and the door's triple comparison opens for a ^17.7.1 floor as it should. ADR-0087's amended definition ("the last published @objectstack/spec whose authoring surface still accepted the old shape") agrees. One non-blocking wording note: the TSDoc lead "read off the package's version label" is literal only for the stable case; the bullets that follow make the prerelease case explicit, so no reader is misled.

② Semver level

• Changeset .changeset/23042-retired-after-prerelease-stamp.md: @objectstack/spec: patch — right. The diff publishes one thing: a doc comment inside the shipped .d.ts files (the dev measured the old sentence at 2 dist files before and 0 after). That is a published change, so skip-changeset would be wrong; nothing an author can write moves, so minor is not owed. Check Changeset on the head: success.
• Clause-②: no — right. The published accept set does not change: the retiredAfter type is unchanged, no schema or runtime moves, and the census test is unpublished. The PR body carries the claim's Clause-②: no line verbatim on line 2, with no (widening)/(narrowing) arm — well-formed. check:adr-0087-registration owes nothing here: a non-breaking changeset is outside that gate (its G1 case), so no disposition marker is required, and none is present.
• Changeset text is correct. It names the public member as MetadataConversion.retiredAfter (the exported name; the file-internal interface would be the wrong name for a CHANGELOG reader), states both label cases and the maintenance-release case exactly as the TSDoc does, and ends "Text only: retiredAfter keeps its ${number}.${number}.${number} type, and the accepted set does not change" — true.

③ Boundary flags

open_questions: none declared. The dev's deviations and out_of_scope_findings (report 6137194016), each answered:

Deviations

1. All three label comparisons bound by atOrBelowLabel, not only the pending branch — accepted as necessary (see ①; otherwise 18.0.0 passes under the "never above the label" title).
2. Whole spec local project cut by the foreground cap at the final head, measured 659/659 at the branch commit 2e7bb5f — accepted: the merge commit at the head changed none of this diff's files (verified: origin/main differs from the merge base at neither retired-after.census.test.ts nor types.ts), and Test Core (1–6/6) runs on the head are CI's. In progress at read time; see the gate reading below.
3. First ablation run void (repo-relative path, no file selected), re-run counted — procedural, no effect on the diff.
4. git fetch --depth=1 of a fixture commit for a self-test prerequisite — procedural; adds objects, rewrites no ref.
5. Presence probe spelled with values masked — procedural; not verifiable here, no effect on the diff.
6. Commit trailers: the session-URL trailer plus a model-free co-author trailer (read on the branch commit 2e7bb5f) — accepted; pre-push accepted it and it matches AGENTS.md's trailer rule.
7. Zero label writes; skip-changeset not applicable because a patch changeset exists — right.
8. Run cut by a usage limit and resumed from the earlier branch state e49aaec without redoing work — procedural; the net diff is judged, not the path to it.

Out-of-scope findings

1. .claude/skills/spec-property-retirement/SKILL.md:204-205 still says to stamp "packages/spec/package.json 的当前版本标签" (verified at the head) — carried by skills(spec-property-retirement): under a prerelease package label, the retiredAfter checklist item stamps the newest published stable release — the governed half of #23042 #23057 (Blocked-by: #23042, per the claim), a Tier S edit that correctly does not ride this PR. No action here.
2. packages/spec/scripts/build-retired-after-census.ts header, "When to run it": tolerance written as [last censused release, package.json label] — not shipped (scripts/ is not in files[]) and, read with semver precedence, still literally true (an 18.0.0-next.N upper bound excludes 18.0.0); it also defers to the test docblock, which now states the rule. Imprecise, not wrong; no carrier owed. Recommend skills(spec-property-retirement): under a prerelease package label, the retiredAfter checklist item stamps the newest published stable release — the governed half of #23042 #23057's author tighten it to "release triple)" in passing.
3. metadata-core/src/artifact-forward-conversion.ts docblock ("while the package label still names the last release of M-1") and artifact-forward-conversion.test.ts:680-696 ("stamped at the prerelease label", meaning the label during the prerelease, 17.7.0) — their stamp half states this rule; the "still names" clause is true until the first pre-mode version pass. Agrees in substance; no carrier owed. Note for skills(spec-property-retirement): under a prerelease package label, the retiredAfter checklist item stamps the newest published stable release — the governed half of #23042 #23057's author only.
4. packages/metadata-core/CHANGELOG.md:489, a released entry — history; no action, right.

My own sweep beyond the dev's (git grep retiredAfter at origin/main, every non-CHANGELOG hit): docs/releases-maintenance.md:450 (refresh the census after a stable publish; states no stamp rule), content/docs/releases/v17/17-5.mdx:1276 ("the last @objectstack/spec version that accepted the old shape"; agrees), .changeset/23001-* (agrees, quoted in ①), .changeset/5082-* (declared-index-unique-scope stamped 17.7.0; agrees), metadata/src/plugin.ts (reads the door's result; no rule text). No unflagged inconsistency.

Governed surfaces: none of the 3 paths is in the register (no .claude/**, docs/adr/**, skills/**, AGENTS.md, CLAUDE.md); Governed Surface Queue Guard is success. This review is owed by the dispatch's path leg (packages/spec/src/**, non-test), and the file surface matches the claim's.

Check-runs on the head at 2026-10-13T03:01Z: 39 total — 23 success (among them Check Changeset, Governed Surface Queue Guard, Lint & Repo Gates, Lint · ESLint, Spec property liveness, Type Check · source gates, the four card/branch/single-writer claim checks), 6 skipped (opt-in and docs/console gates), 10 in progress (Build Core, Test Core (1/6) to (6/6), Type Check · consumer gates, Type Check · debt ledger, Type Check · workspace). An in-progress run is not a pass: the landing waits for every one of them to conclude green. This verdict is on the contract in the diff, not on those runs.

Implemented-by: claude/issue-23042-prerelease-retired-after
Reviewed-by: session_012uFegdfR6K6uqvLzt7XsdZ

VERDICT: PASS