Repository navigation
Commit 79854f7
fix(scripts): split ablation-dist-preflight two readings so a DELETE ablation mutate leg can pass (#19640)
Fixes #19348
`scripts/ablation-dist-preflight.mjs --absent` answered two independent
questions with one marker and one exit code. Split, in the order this
repo prescribes: delete the construct that permits the error, then make
the correct shape the only spelling, and only last consider a check.
## The defect is one level down from where the card puts it, and that
matters
The card says the tree limb "implements only the restore-leg reading --
it exits 1 whenever the working tree is dirty". Measured, that is not
what the code did: `classifyTree` already derived a mutate leg, and a
DELETE ablation whose marker occurs in the source passed. The card's
**premise holds** -- a DELETE ablation's mutate leg could not pass its
own pre-flight -- but the mechanism is one level down, and finding it is
what makes the card's "second, independent trap" the **same defect seen
from the other side**:
The `dist/` reading and the tree reading ask about **two different
artifacts**, and a bundler re-spells literals between them. `tsup` emits
`label:"Operator"` for the source's `label: 'Operator'` -- different
quotes, no space after the colon. One string cannot be both. So the two
readings demanded **mutually exclusive spellings**, and the only
invocation that satisfied both at once was the one that proved nothing.
## Before -- reproduction, on `origin/main` at 34545d6
The card's repro names `packages/spec/src/ai/skill.form.ts`, which is
fenced off for this task (every region of `packages/spec/src` is held by
an open PR). The equivalent, stated exactly and reproducible by anyone:
a throwaway workspace whose source spells the literal with single quotes
and whose `dist/` carries the double-quoted emission, carrying the
unmodified script and its imports. A DELETE ablation drops the `label`
entry; both files are then re-read on disk (`grep -c`: source 1 -> 0,
dist 1 -> 0) before any verdict is taken.
| run | marker passed | `dist/` reading | tree reading | exit |
|---|---|---|---|---|
| A | `label:"Operator"` (what dist emits) | GREEN "marker absent from
all 3 built files" | **RED** "restore leg: ... 1 path still differs from
HEAD" | **1** |
| B | `label: 'Operator'` (what the source spells) | GREEN **vacuously**
-- that spelling was never in dist | green, mutate leg | **0** |
Run A is the card's reading, shape for shape. Run B is the card's second
trap, and it is the same coin: the spelling that makes the tree reading
agree is the spelling that makes the `dist/` reading meaningless.
The sharpest form of the before reading is this pair: a **correct DELETE
mutate leg** (run A) and a **genuinely unrestored tree** (a restore leg
with a leaked build-written baseline) print **byte-identical tree
verdicts and the same exit code**. The instrument could not tell them
apart.
## The ordered remedy
**1. Delete the construct that permits the error.** Three constructs,
all of them "one thing answering two questions":
- **one marker for two artifacts** -> `--source-marker=SPELLING` names
what the SOURCE carries. The tree reading probes with it; the `dist/`
reading never sees it. Omitted, the tree reading falls back to the
positional marker -- correct exactly when the build does not re-spell,
which is why every invocation in the three documents that state this
script's usage keeps working untouched.
- **one leg value for two questions** -> `classifyTree` grows a third
leg. `restore` is now asserted only on a CLEAN tree; dirt no marker
explains is `indeterminate`. Collapsing "you are restoring" into "I
cannot tell" was the defect: the failure of an inference is not a
finding, and reported as one it told a correct mutate leg to restore the
very mutation being measured. `indeterminate` stays RED -- refusing is
the safe direction -- and the refusal now carries **both** readings with
the exact remedy for each.
- **one exit code for two readings** -> 1 dist, 2 usage, 3 tree, 4 both.
A driver that trusts the status can now tell "the mutation is not in the
artifact" from "the tree is not what you think".
A `--leg=mutate` flag was considered and **rejected**: the script cannot
check a claim, and a mistaken `--leg=mutate` at a real restore leg would
switch off the leaked-artifact catch -- the one assertion here that has
already recovered a measured run. `--source-marker` demands evidence
instead, and the control below shows it cannot be used to disarm that
catch.
**2. Make the correct invocation the only spelling.** Unknown options
were discarded in silence -- `argv.includes('--absent')` plus a
`startsWith('--')` filter -- so a mistyped `--absnet` ran the OPPOSITE
mode and printed a verdict that reads exactly like a real one. Unknown
options are now a usage refusal; `--source-marker` has exactly one
spelling (joined with `=`, because with a space its value lands in the
marker position); a blank value is refused; and a marker that itself
begins with two dashes is now named rather than dropped. The wiring that
chooses the tree reading's spelling is a named export,
`treeReadingMarker`, because inline it was the one part of the split no
case could reach.
**3. The presence pre-condition -- the ruling.**
**A dist-domain presence check is NOT added, and should not be.** The
reason is the clock, not an oversight: `--absent` runs AFTER the
rebuild, so the pre-mutation `dist/` no longer exists and nothing
readable at that moment witnesses that the marker was ever in the
artifact. Every surviving proxy is the SOURCE, whose spelling is -- by
this very defect -- the one that differs. Such a check would fire on the
**correct** invocation of the card's own repro (run A above), turning a
fixed path back into a red one.
A quote-and-whitespace-normalised near-miss probe was the one candidate
that could fire, and it was measured against the card's own incident: on
that tree it finds nothing, because the construct really did leave
`dist/`. It would **not** have caught the attempt the card describes. It
buys only the narrow case "marker mis-spelled AND dist not rebuilt", at
the price of a new false-red class on non-unique markers -- which this
file's header already documents as the scan's known weakness. Rejected
on that measurement.
**The presence pre-condition IS owed, and rung 1 pays it, in the domain
where a witness survives.** With `--source-marker`, a DELETE ablation's
mutate leg is green only when a tracked path **had** that literal at
HEAD and **lost** it -- evidence that the construct existed and left --
while the `dist/` reading runs in the emitted spelling. Neither reading
is vacuous, which is exactly what the measured first attempt lacked. And
because the dist-domain half is a reading rather than a check, every
`--absent` pass now prints what it did **not** prove and names where
that reading is taken: this script in default mode on the PRISTINE
build, before the mutation.
## After -- same corpus, same commands
| run | invocation | `dist/` reading | tree reading | exit |
|---|---|---|---|---|
| A | emitted marker + `--source-marker` with the source spelling |
GREEN, non-vacuous | green, **mutate leg** | **0** |
| A | emitted marker alone | GREEN | RED "cannot tell which leg this
is", both readings named | **3** |
| B | source spelling alone | GREEN, still states what it did not prove
| green, mutate leg | 0 |
## Both directions of the control, because one direction proves nothing
- **The mutate leg passes.** Run A with `--source-marker`, exit **0**,
tree reading "mutate leg: 1 path differs from HEAD, of which 1 carries
the marker".
- **The restore leg still refuses.** Source restored, a build-written
baseline left dirty: exit **3**, and the refusal names
`packages/demo/generated/baseline.json`.
- **The new flag cannot disarm that refusal.** The same unrestored tree
with `--source-marker` passed: still exit **3**, still names the
baseline, and the message sharpens to "the `--source-marker` you named
... is not the spelling that moved".
- **Instrument-live control.** A marker still present in `dist/`
(`label:"Value"`, 1 hit, known target inside the scanned radius of 3
text files) is RED on the `dist/` reading -- so the scan is reading
those files, and the greens above are not a dead instrument.
## Red-first: two ablations, both taken from a committed tree, both
restored to the HEAD blob
There is no `dist/` mediation to prove here -- the subject is a
`scripts/*.mjs` file that `node` loads from source, with no package
`exports` between it and the runner -- so the pre-flight's own hazard
does not apply to its own ablation. On-disk landing was proved both ways
for each leg (injected text counted to 1, deleted text counted to 0)
before any verdict was read.
1. **`classifyTree`'s third leg removed.** Self-test: **15 cases RED**,
including 6 of the 9 in the new split battery. End to end, a genuinely
unrestored tree (a dirty `generated/baseline.json`) was reported
"working tree clean against HEAD" at exit **0**. Direction observed,
stated as observed: this is a **false green**, which is *more* severe
than main's false red -- `treeVerdict`'s clean branch is now keyed on
the leg, so removing the third leg routes unexplained dirt into the
clean return rather than into the restore refusal. Both are wrong; the
pins fire on either.
2. **`treeReadingMarker` reduced to `return marker`.** Self-test: 2
cases RED (exactly the wiring pins), and the card's repro under the
corrected invocation reverts to exit **3**. This is the discriminating
reading for the user-visible fix, and no pure-table case reaches it --
which is why the wiring is a named export.
Restore was proved by state, not by exit code, on every leg: worktree
blob equal to the HEAD blob, `git diff HEAD` empty, whole-tree `git
status --porcelain` empty, and the injected text counted back to 0.
## Checks
- `node scripts/ablation-dist-preflight.mjs --self-test` -- **64 cases,
5 batteries, all pass**. Two new batteries, both on the roster and both
floored, and `SELF_TEST_BATTERY_FLOOR` raised 3 -> 5 so deleting one
cannot silence it.
- The 27 gate families `scripts/pm/dispatch-gates.mjs` derives for this
path: **all green**, and all 27 were green on the pristine tree before
the change too, so no verdict here is inherited.
- `pnpm lint` (`eslint . --no-inline-config`, the whole repo, 117s) exit
0 at this branch's head. Not a narrowed run, so no narrowing to justify.
Its **positive control**: a code-shaped line injected inside a block
comment in the changed file makes the same command exit 1 with
`comment-swallow/no-code-inside-block-comment`. Worth recording that the
first control chosen -- an unused variable -- did **not** fire: only 2
rules resolve for a `scripts/*.mjs` file here (`no-restricted-imports`
and the comment-swallow rule), `no-unused-vars` is not configured, and
`parserOptions.project` is null, so type-aware linting is off.
- No typecheck family covers `scripts/*.mjs`; `node --check` passes and
the file is `.mjs`, not TypeScript.
## Changeset
**None, deliberately, and this is a departure from the dispatch word --
flagged rather than taken silently.** The repo's criterion is whether a
published surface moved. Measured: **70 published workspace packages,
zero of which name `scripts/` or this file in `files[]`** (positive
control: the same predicate fires on `dist` in `@objectstack/spec`'s
`files[]`). So nothing releases. An empty-frontmatter changeset was
written and then removed after reading
`scripts/check-empty-changeset.mjs`, which **rejects** exactly that
shape (#5471: an empty changeset is a real input to `changesets/action`
and can take its "All changesets are empty; not creating PR" branch).
The correct spelling here is the `skip-changeset` **label**, which is
the PM seat's act -- I have added no label.
## Acceptance notes
Out of scope for this PR, recorded rather than fixed:
- `scripts/ablation-replace.mjs` **restores from HEAD, not from the
pre-mutation working copy**, so running it over an uncommitted edit
destroys that edit while printing `ok restored`. Hit during this task:
it printed `blob 4f6d694 -> 22713e9104d8` going in and `blob after
restore 591ef26` coming out, compared the latter only against HEAD,
and reported success. A one-line comparison of the two blobs it already
prints would have named it. The ablation discipline does require
committing first, which is why this is a gap rather than a
contradiction.
- `scripts/ablation-replace.mjs` line 538 prints the follow-up
pre-flight command for a DELETE ablation using the **source anchor** as
the marker. That is precisely the spelling that makes the `dist/`
reading vacuous on any package whose build re-spells literals -- the
tool hands the author the wrong half of the pair. Fixing it means
teaching it `--source-marker`, which is its file, not this one.
- This file's header names
`.claude/skills/dogfood-verification/SKILL.md` as one of "three
documents that state this script's invocation"; that file no longer
mentions the script. Stale prose, no behaviour attached.
- The three documents that do state the invocation still show only the
default (present) form. Now that the default mode on the pristine build
is named as the presence reading for a DELETE ablation, that procedure
step is worth writing down where authors read it -- outside this PR's
fence.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01UDXER3sdqfeVYpEWZs5mZx)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent d3a2331 commit 79854f7
1 file changed
Lines changed: 469 additions & 48 deletions
0 commit comments