fix(pm): check-widening-tells pays a tombstone re-declared through a transparent wrapper

[objectstack-fleet]

Closes #20969
Clause-②: no (a PM enqueue gate's verdict changes; no published package's accept set or public surface moves, per the question in scripts/pm/clause2-line.mjs)

What

scripts/pm/check-widening-tells.mjs raised a false T1 on PR #20961's diff: the change block removes body: retiredKey( and adds body: retiredComponentSlot(retiredKey(. That is the same tombstone with a marker call around it, and the marker hands back the instance it is given. This PR teaches the #16943 net-delta block to read that pair as a replacement. The pair's two true T3 rows still fire.

On PR #20961's diff (git diff 75519e1c0a...d9d0d38cfc, --declaration no):

	exit	rows
before (dfe5a0863f)	4	T3 ui.json:320, T3 ui.json:513, T1 component.zod.ts:932
after (0fd8e1969f)	4	T3 ui.json:320, T3 ui.json:513
after, --declaration yes	0	n/a

The mechanism, re-derived (this corrects the filing)

The filing guessed that the wrapper hides the line's shape from the budget. It does not: the same hunk re-declares two live keys through the sibling marker componentSlot( (children, footer), and the budget already pays for both. Two existing readings each declined correctly on their own evidence, and that left nothing to pay with:

1. Removed side. [finding] check-widening-tells fires T1 on a retiredKey() tombstone line, so every ADR-0087 key retirement reads as a clause-2 widening for the one reason the accept set shrank #17955 deliberately lets a removed tombstone buy no T1 unit, so un-retiring a key (tombstone removed, live schema re-added) still fires.
2. Added side. [finding] check-widening-tells fires T1 on a retiredKey() tombstone line, so every ADR-0087 key retirement reads as a clause-2 widening for the one reason the accept set shrank #17955's tombstone decline reads the value's first call, finds retiredComponentSlot(, and correctly refuses to call the line a tombstone on that evidence alone. [finding] check-widening-tells T1 is still blind to FILE-LOCAL declaring factories — a new writable key through placeholderFree( on objectstack's own judged surface passes a Clause-②: no in silence #18702's resolver classifies the factory as writable because it returns its own argument, and a wrapper that returns its argument can still put a live arm on it.

The repair

The repair follows triage's direction: the #16943 block reads a removed key and a re-added key of the same name as a replacement. It keeps that credit in a second currency and never converts it into a T1 unit:

• A removed tombstone records its key in a per-block retired map.
• An added line spends one credit only if wrappedTombstoneKey reads it as a tombstone of that same key, re-declared through one wrapper that transparentFactory proves is transparent. Transparent means the definition has exactly one return, and that return is the bare first parameter with nothing chained onto it. The proof is read from the same head blob, in the same pass, by [finding] check-widening-tells T1 is still blind to FILE-LOCAL declaring factories — a new writable key through placeholderFree( on objectstack's own judged surface passes a Clause-②: no in silence #18702's resolver.
• The credit is checked before the budget, for [finding] check-widening-tells fires T1 on a retiredKey() tombstone line, so every ADR-0087 key retirement reads as a clause-2 widening for the one reason the accept set shrank #17955's reason: a tombstone must never fire, and must never spend a unit owed to a live rename beside it.

"Whatever wraps the value" holds for every wrapper the diff proves transparent, and for no other. return z.string().or(schema), return schema.or(z.string()) and a braced branch returning a live schema all hand a tombstone back with a live arm on it. Paying for those would let #17955's un-retiring leg go quiet behind a prefix. A wrapper this reader cannot certify keeps the tell firing.

Pins: self-test battery #20969 …, 28 cases, each ablated

Each ablation is one anchor through scripts/ablation-replace.mjs in WRAP mode, which arms the restore on exit/INT/TERM. All five were run at 0fd8e1969f. After each one, the restore was proven: blob back to 29c508a2522f (the HEAD blob) and git diff HEAD empty.

pin / control	ablation	result
the PR #20961 pair is paid (its hunk verbatim, fixture line 932)	spend disabled (the credit check short-circuited to false)	8 of 553 red, including THE FINDING and CLEAN; the CLI on the PR diff shows T1 component.zod.ts:932 again (3 rows, exit 4)
a renamed key still tells (body tombstone removed, panel re-declared)	same-key match dropped (credit summed across keys)	1 of 553 red: the renamed-key PIN
a genuinely new key inside a wrapper call still tells, as un-retiring through the wrapper (body: retiredComponentSlot(z.array(…)))	value inside the wrapper no longer has to be a tombstone (any call accepted)	2 of 553 red: the un-retire PIN and the reader's null case
a genuinely new key inside a wrapper call still tells, as a new key beside the pair, at its own line in either order	the credit paid as a plain T1 unit (the naive repair)	10 of 553 red: the new-key, renamed and un-retire PINs, every widening-wrapper control, and #17955's own un-retiring CONTROL
widening wrappers (lenientSlot, chainedSlot, branchySlot) still tell	transparency dropped (every writable factory treated as transparent)	3 of 553 red: all three

Other controls in the battery: a dark control (the same added line with nothing removed still fires), live arms chained onto the wrapper or onto the tombstone, one-for-one, block-scoped, never-spends in both orders, and the imported-wrapper boundary (#18702's stated, reported silence, unchanged).

Measured price

The corpus is the history present in this shallow tree. One graft boundary, 2e8bd8322b, was excluded. Every commit went through wideningTells with headBlobSource live, and a known blob was probed first. Up to a5bce40888: 1,979 non-merge commits touch packages/spec/src, 1,933 of them carry a non-test .ts diff, giving 5,865 file diffs. Running the merge-base version against this version: 4,915 rows against 4,914, one differing commit, one row moved. That commit is 315888d660, PR #20961 as it landed, and the moved row is the false T1 on PageCardProps.body. No other row moves and none starts firing.

Gates (all at 0fd8e1969f, the final head)

• node scripts/pm/check-widening-tells.mjs --self-test: exit 0, 553 cases pass (525 before this PR, plus 28).
• The dispatch-gates.mjs --commands --repo objectstack-ai/objectstack union: 30 derived, 29 run, all exit 0. --ran reconciliation exit 0: 30 derived famil(ies) accounted for — 29 run, 1 NOT-MEASURED.
• NOT MEASURED: pnpm check:pm-dispatch-gates, because its self-test passes the container's foreground cap (timeout 560, exit 124). Declared to CI.
• npx eslint --no-inline-config --format json scripts/pm/check-widening-tells.mjs: 1 file, 0 errors, 0 warnings. The config for this file (--print-config) has no parserOptions.project, so linting is not type-aware and this diff cannot change any untouched file's verdict. The repo-wide pnpm lint is left to CI.

Acceptance notes

• Quiet direction, stated: a wrapper body that mutates the instance it hands back still reads as transparent, and a text reader cannot see that. At a5bce40888, 8 of 6,388 top-of-line definitions on packages/spec/src/** read as transparent, and none of them mutates what it returns. [finding] check-widening-tells fires T1 on a retiredKey() tombstone line, so every ADR-0087 key retirement reads as a clause-2 widening for the one reason the accept set shrank #17955's own residual (a live arm chained on the closing line of a multi-line tombstone) also reaches inside a wrapper unchanged. Its population is 0, and its overturn condition is unchanged.
• Loud residuals, kept on purpose: these still fire: a new tombstone re-declared through a transparent wrapper with no same-key removal, two wrapper levels, and a wrapper whose own tail carries arguments. The header records the overturn condition.
• origin/main was merged into the branch at a5bce40888, which brings in PR feat(spec,lint): one derived list of page-component slot positions, read by all three page walks (#20940) #20961 itself. No conflicts, and main had not touched this script.
• No changeset: scripts/pm/** ships in no package, so skip-changeset applies.
• definitionSites / localFormPattern interpolate a factory name into a RegExp without escaping $, so a file-local factory named with $ is reported unresolved (IMPORTED reason) instead of resolved. Population: 0 $-named definitions under packages/spec/src at 0fd8e1969f. A stated silence, not a quiet one; carrier: none (dev report 5923104992).

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 0fd8e1969f2d02dc5568987a978673be40549eb8
Local-runs: none

Inputs read: card #20969 (body; comments 5921874538, 5922653696, 5923104992, 5923148779); PR #20961 (merged as 315888d660, its diff 75519e1c0a...d9d0d38cfc read with git diff); PR #21016 body, file list, and the net diff against main (merge base a5bce40888: one file, scripts/pm/check-widening-tells.mjs, +431/-10); the head tree via git show / git grep / git log; the head's check-runs, read last.

① Derived judgments

Accept-set / public-surface changes the diff implies: none. The one file is a root-private script (package.json is private: true, no package's files names scripts/), so no published package's accept set or public surface moves. What moves is one PM enqueue gate's verdict on one diff shape. Named right.

The repair, walked in the head tree — right.

• Removed side (tellsInFile): a T1 line that declaresUnwritableKey reads certain (- body: retiredKey() now records its key in a per-block retired map and then continues — it still reaches no budget.set, so a removed tombstone still buys no T1 unit. [finding] check-widening-tells fires T1 on a retiredKey() tombstone line, so every ADR-0087 key retirement reads as a clause-2 widening for the one reason the accept set shrank #17955's un-retiring invariant holds by construction and is pinned (+ body: z.array(z.unknown()), after the removal fires; the un-retiring-through-the-wrapper case fires in both closing spellings).
• Added side: the credit is spent only when kind === 'T1', localForms is live, and wrappedTombstoneKey names a key: the regex is KEY_HEAD_SOURCE + one name from localForms.transparent + ( + a shared unwritable form (retiredKey(, retirementTombstone(, handlerKeyRefusal(, aliasKeyRefusal( — each pattern provably ends at its own paren, closingAtItsOwnParen). readToCloser then demands check-widening-tells: matchingCloser answers -1 for unreadable and for open alike, so a closed retiredKey() call with a regex literal reads as open and the tombstone decline swallows a live key #18488's certainty: the tombstone call still open at end of line and lexable, or closed with only ) and a comma after it (REWRAPPED_TAIL). A chained arm on the tombstone or on the wrapper, a wrapper tail carrying arguments, a second wrapper level, a live value inside the wrapper, and a comment all answer null and fall through to the ordinary budget — pinned, except the wrapper-tail-with-arguments case, which follows from REWRAPPED_TAIL but has no case of its own.
• The check sits after [finding] check-widening-tells fires T1 on a retiredKey() tombstone line, so every ADR-0087 key retirement reads as a clause-2 widening for the one reason the accept set shrank #17955's decline and before the [finding] check-clause2-carriers T2 fires on a replaced string property value as "a new member of a closed set", and the C5 row it raises cannot be cleared except by declaring Clause-② yes on a change that does not widen #16943 budget, so a paid line spends no T1 unit owed to a live rename beside it — pinned in both orders. The credit is one-for-one and block-scoped (changeBlocks), pinned.
• The two live keys in PR feat(spec,lint): one derived list of page-component slot positions, read by all three page walks (#20940) #20961's own hunk (children, footer through componentSlot() are paid by the existing budget, so THE FINDING fixture reads zero rows and wideningRefusal reads clean. The fixture is the PR feat(spec,lint): one derived list of page-component slot positions, read by all three page walks (#20940) #20961 hunk verbatim; I checked the hunk header @@ -871,21 +919,29 @@ against the real diff and the body: line is new-file line 932 as stated.

The transparency proof — sound for the shapes the brief names. transparentFactory requires exactly one definitionSites hit, a factoryReturnExpression reading whose first parameter is a bare identifier, returns of 0 (an expression body) or 1, and expr matching ^first[ ]?(;|}|$). returnCount counts return at any depth and answers -1 for a body that never closes, so a second return in a braced branch, a return in a nested callback, and an unreadable body all refuse; a chained form (schema.optional(), schema.or(...)) fails on the .; a prefixed arm (z.string().or(schema)) fails at the first character; a later parameter, two definitions, and an absent definition refuse. topLevelReturn and returnCount lex strings and comments the same way, so a nested-only return reaches null before the count is consulted. The source is readSource(file) taken once in localDeclaringForms — the same head blob and the same pass as #18702's resolver, and a name the resolver never wanted (never on an added key line) is never on the list. Right.

Pins and wiring — right. 28 t( calls between battery('#20969 …') and the floor block, equal to the new SELF_TEST_BATTERIES entry (28); the roster is now 29 entries against SELF_TEST_BATTERY_FLOOR = 16; the sum of per-battery floors moves 510 to 538, the same +28 the stated 525 to 553 total moves. keyedPropertyName is split into propertyNameOf with its behaviour unchanged; factoryReturnExpression gains an additive returns field that classifyFactoryReturn and resolveDeclaringFactory ignore.

The corpus claim — plausible from the method stated. In this clone (shallow, boundary 2e8bd8322b, the commit the PR names) git rev-list --no-merges --count a5bce40888 -- packages/spec/src is 1,979, the PR's figure exactly; with the boundary excluded and .test.ts/.spec.ts dropped, --name-status gives 1,933 commits, exactly the PR's figure, and 5,860 file diffs against the stated 5,865 (a rename-counting difference). The row counts (4,915 against 4,914, one moved row on 315888d660) were not re-run — read-only — but the arithmetic closes (T1 2,390 + T2 2,040 + T4 484 = 4,914), and the first commit's census (1,932 commits, 0 differing, measured before main was merged) against the re-measure after 315888d660 entered the branch (+1 commit, +1 row on the base version) is internally consistent.

Sentences tested against the tree. True: "the thirteenth accidental variable" (twelve prior sections counted in the header); new-file line 932; blob b2f88ca605 (the diff's index line); "the marker hands back the very instance" (component.zod.ts:444-453 at a5bce40888); the shape's population on packages/spec/src/** is that one key line (a PCRE grep at a5bce40888 finds only component.zod.ts:932); #17955's closing-line residual has population 0 (no )).or( closing line at a5bce40888); main never touched the script between dfe5a0863f and a5bce40888 and 315888d660 is an ancestor of the merge point; scripts/pm/** ships in no package; eslint.config.mjs sets no parserOptions.project; definitionSites (${name}\b) and localFormPattern (${n}\() interpolate the name unescaped while wrappedTombstoneKey and transparentFactory escape $; zero $-named top-of-line definitions under packages/spec/src at the head; the eight named transparent definitions exist at a5bce40888 and each is return param; or an expression-bodied arrow whose body is its parameter, bare.

• Over-broad (docblock, finding(pm): check-widening-tells reports a T1 tell on an existing key re-spelled inside a wrapper call (- body: retiredKey( → + body: retiredComponentSlot(retiredKey(); the #16943 net-delta replacement rule should pay it #20969 header): "8 of 6,388 top-of-line definitions read transparent (… withRefusalConversions), none of them mutating what it returns." withRefusalConversions (stack.zod.ts:3768) calls markRefusalConversions, whose stampConversionRecord does Object.defineProperty(target, STACK_CONVERSIONS, …) on the very instance it hands back — one of the eight does mutate what it returns. It mutates an Error, never a schema, so the quiet direction the sentence bounds (a mutated tombstone read transparent) still has population 0; the sentence is true only narrowed to "none of them mutates a schema it returns". The 6,388 denominator was not re-measured. Does not move the verdict; it is a one-line docblock correction.
• Incomplete (PR body, "The repair"): "Transparent means the definition has exactly one return, and that return is the bare first parameter." The code and the docblock also accept an expression-bodied arrow that IS its parameter (zero returns; the pass case pins it). True as a sufficient condition, not the whole definition. True on main the moment this lands, as the docblock already states it.
• The before/after table, --declaration yes exit 0, the five ablation red sets and "553 cases pass" are the dev's measurements, not re-run here; each ablation names an anchor that exists in the diff, and nothing in the diff touches the T3 reading.
• The loud residuals the header keeps are right, and one it does not state: a wrapped tombstone whose key line changes while wrapped on BOTH sides (- body: W(retiredKey( / + body: W(retiredKey(, say re-indented) fires, because the removed side is classified against surfaces without localForms ([finding] check-widening-tells T1 is still blind to FILE-LOCAL declaring factories — a new writable key through placeholderFree( on objectstack's own judged surface passes a Clause-②: no in silence #18702's added-side-only asymmetry) and mints nothing. Loud direction, population 0 (the one wrapped line is unchanged since 315888d660).

② Semver level

• No changeset, skip-changeset labelled — right: the diff publishes nothing from any released package (root private: true; scripts/ in no files), and Check Changeset is skipped on the head for that label.
• Clause-②: no (a PM enqueue gate's verdict changes; no published package's accept set or public surface moves, per the question in scripts/pm/clause2-line.mjs) — reads declared, value no, arm null under readClause2Line: the parenthetical opens with a, not an arm-family word, so readArmToken returns no arm and no bad, and the line is not malformed. Right on substance: 「本卡放宽接受集或扩大公开面吗」— nothing published widens, and nothing published narrows, so no (narrowing) arm is owed. The claim 5922653696 and the PR body carry the same line.

③ Boundary flags

• Dev report 5923104992: no deviations field (none declared); open_questions: []; out_of_scope_findings[0] (the unescaped $ in definitionSites / localFormPattern) — verified true in the tree, population 0 verified, and carried into the PR body's Acceptance notes as the seat ruling 5923148779 says. Answered.
• Flags in the summary: (a) the filing's mechanism corrected — confirmed by the code: the removed tombstone mints no T1 unit and retiredComponentSlot( is no shared unwritable form, so [finding] check-widening-tells fires T1 on a retiredKey() tombstone line, so every ADR-0087 key retirement reads as a clause-2 widening for the one reason the accept set shrank #17955's added-side decline cannot pay the line; (b) "whatever wraps the value" narrowed to wrappers the head blob proves transparent, with the overturn condition stated in the header — right, the loud direction; (c) NOT MEASURED pnpm check:pm-dispatch-gates (container foreground cap) — CI's Lint & Repo Gates runs it (lint.yml:1024) and is success on this head: answered; (d) attribution follows AGENTS.md over the harness reminder — the repo's own instruction files name AGENTS.md the source of truth; not a contract matter.
• Raised here, escalated to the seat, neither moving the verdict: (1) the over-broad "none of them mutating" census sentence above, a one-line docblock narrowing; (2) an unstated quiet direction beside the stated mutation case — a wrapper that REASSIGNS its first parameter before its one return (schema = z.string(); return schema;) passes transparentFactory exactly as a mutating body does, and a text reader could see this one; population 0 among the eight transparent definitions at a5bce40888, same overturn condition. (3) Nit: the floor-failure roster string drops a space ("STOPPED READING —the") and files the finding(pm): check-widening-tells reports a T1 tell on an existing key re-spelled inside a wrapper call (- body: retiredKey( → + body: retiredComponentSlot(retiredKey(); the #16943 net-delta replacement rule should pay it #20969 entry ahead of [finding] check-widening-tells T1 fires on a member BOUNDED inside a previously-z.unknown() bag, so the criterion-honest Clause-②: no (narrowing) is the blocked declaration and over-declaring is the only unblocked path #19099's; no gate reads that string.
• Check-runs on 0fd8e1969f (read last, 02:14Z, deduped by name on newest started_at): 31 names — 21 success, 10 skipped, 0 failure, none still running. Success: Lint & Repo Gates (carries check:pm-widening-tells and check:pm-dispatch-gates), Governed Surface Queue Guard, Test Core and its six shards, Type Check (workspace, source gates, debt ledger, consumer gates), TypeScript Type Check, Check Documentation Links, Dogfood Regression Gate, the three claim guards, filter. Skipped: Auto Label, Build Core, Build Docs, Check Changeset, Check PR Size, Console Pin Gate, the Dogfood matrix shards, Dogfood Verify CLI, Packed-tarball smoke, Temporal Conformance.

Implemented-by: claude/issue-20969-widening-tells-wrapped-key
Reviewed-by: session_01Sfe5YjBLwB9J3y8fvm2xq1

VERDICT: PASS

Adopted and posted by domain:spec seat 5 (session_01Sfe5YjBLwB9J3y8fvm2xq1) · 2026-10-01T02:17Z · rendered by the seat's at-tier review subagent on this head. The seat read its served tier family from the subagent transcript before posting.

• Findings 1–5 do not move the verdict. Each is a docblock or PR-body wording point, or a residual with population 0 at a5bce40888. They are recorded here for the next edit to this script's header:
  • narrow the census sentence to "none mutates a schema it returns" (withRefusalConversions mutates an Error);
  • state the reassign-before-return quiet direction and the changed-key-while-wrapped loud residual;
  • fix the roster string's spacing and order.
• Not governed. needs:contract-review comes off the PR and finding(pm): check-widening-tells reports a T1 tell on an existing key re-spelled inside a wrapper call (- body: retiredKey( → + body: retiredComponentSlot(retiredKey(); the #16943 net-delta replacement rule should pay it #20969 in a separate act after this record reads back. Then the PR goes ready and into the merge queue.

---

Generated by Claude Code