@am_shork/attest 0.9.4 → 0.10.0

package/CHANGELOG.md

@@ -13,6 +13,527 @@ input, removes/renames a public API or `--json` field, or changes a default
 runtime behavior an existing invocation relies on — diagnostic message text is
 not API.
 
+## [0.10.0] - 2026-08-22
+
+### Changed
+
+- **The same mutation pass over the verdict and its evidence: 24 mutations of
+  `gate.ts` and `red-record.ts`, 21 dead, and two of the three survivors closed.**
+  Every step of `evaluateGate` dies when removed, including scoping
+  `open-unresolved` back to the added ids — the cut that separates it from
+  `never-red`. So do both directions of `keepOutcome`: last-write-wins, where the
+  green run at the end erases the red it exists to remember, and first-write-wins,
+  where a recorded pass can never be corrected. The 46 lines at the top of
+  `red-record.ts` arguing for that asymmetry turn out to be held from both sides.
+
+  Two gaps were real, and both are cases where an existing test passes with the
+  guard removed:
+
+  - **A record whose version is not 2 was discarded by the *schema*, not by the
+    version check.** The case that covers this uses a version-1 record keyed
+    `reqId -> name`, which fails the shape as well — so the verdict is identical
+    either way, exactly as the guard's own comment predicts. Isolating the
+    version needs a record the schema would take: a valid version-2 shape under
+    version 3. Without that, "discarded because the format moved" and "discarded
+    because the file is corrupt" were the same observation, which the comment
+    calls out as how a format change gets made without anyone deciding to.
+  - **Nothing noticed if the record invented a `pass` for a scenario that never
+    executed.** `ATX-30` says the file records *how each scenario ended on its
+    first run*; a skipped scenario has no ending, so a `pass` there is an
+    observation no run produced — in a file that is evidence a reviewer reads and
+    that cannot be recomputed once the change is green. The gate still blocks
+    either way, so no verdict moves; what moves is the advice, since `never-red`
+    picks between "rewrite the assertion" and "run the gate before implementing"
+    on exactly this distinction.
+
+  The third survivor is left alone: `open-unresolved` emitting one error per
+  requirement rather than per question breaks nothing anybody promised. `ATX-81`
+  says the static commands report **each one**, and is pinned per question;
+  `ATX-82` says the gate **blocks**, and says nothing about granularity. Two paths
+  of one shape, one held and one not, and the difference is the two sentences.
+
+  *The harness failed twice more, and the second failure is the one worth
+  keeping.* Mutating a **writer** rather than a reader damages files outside the
+  source it was applied to: `archive` writes `first-run.json` into the e2e
+  fixtures, so a mutant that flipped `keepOutcome` left a committed fixture
+  saying `pass` where it had said `fail`, and every mutant after it read as
+  killed for that reason rather than its own. Restoring tracked fixtures fixed
+  the leak that had been found; a blanket check that the working tree is clean
+  after every mutant then immediately found the one that had not been — an
+  *untracked* record a mutant created, which `git checkout` cannot remove. The
+  broad guard earned its place over the narrow fix by catching what the narrow
+  fix was not written for.
+
+- **Two guards in the registry reader had nothing holding them, found by
+  mutating every decision in `static-registry.ts` and watching what stayed
+  green.** Twenty mutations of the module's semantically load-bearing branches;
+  fourteen died to `tests/static-registry.spec.ts` and `tests/splice.spec.ts`,
+  and six survived the whole suite *and* `self/`. Two of the six were worth
+  closing, and both make the two readers answer **differently** rather than
+  merely reporting differently:
+
+  - `let reqs = defineRequirements({…}); reqs = …; export default reqs` — with
+    the `const` check removed the static reader answers the first registry while
+    the evaluator answers the second. A wrong answer rather than a refusal, which
+    is worse than any code it could have reported.
+  - `export = defineRequirements({…})` — with the `isExportEquals` check removed
+    the static reader accepts it, while the evaluator cannot run it at all.
+
+  Both now have a case in *"a registry that is not a literal"*, and both mutants
+  die to it. The other four survivors are left alone deliberately: one guard is
+  defence-in-depth behind a refusal that already happened upstream (`__proto__`
+  as an entry id, which `readRegistrySource` rejects before a merge can reach the
+  layout), one is a deliberate looseness whose comment says why, and two forbid
+  shapes that cannot compile in the first place. A test contrived to reach them
+  would assert that something upstream is still doing its job.
+
+  *The harness had to be fixed before any of it could be believed, and that is
+  the part worth carrying forward.* Its first run reported all six survivors as
+  killed. The cause was the mutation runner inheriting a working directory with
+  no test files in it, so `vitest` exited non-zero with "No test files found" and
+  every mutant read as covered — a green instrument reporting on nothing, which
+  is the exact failure `ATX-15`'s sweep guards against in as many words: *"a walk
+  that found no files satisfies 'no site orders by locale' while proving the
+  opposite of what it claims."* The runner now pins its working directory and
+  refuses to report at all unless the unmutated tree passes first.
+
+- **The differential corpus now drives the two registry *writers*, not only the
+  two readers.** `tests/static-registry.spec.ts` exists because reading a
+  registry from the AST instead of evaluating it needs the two readers held
+  against each other — but the literal they walk has a third and a fourth
+  consumer, `registryInsertionPoint` and `registryEntryLayouts`, and the table
+  was never pointed at them.
+
+  *Every registry-source defect in this release had its trigger already sitting
+  in that table.* `as-const`, `satisfies` and `parenthesised` are the three
+  spellings whose literal the writers could not locate; `key-forms` carries the
+  duplicate key whose span they located at the wrong offset, under a comment
+  that has said *"a duplicate key: last wins"* since the row was written. The
+  corpus knew about all four inputs. Nothing asked the writers about them.
+  Reverting either fix now turns the table red — measured: the unwrap on all
+  three wrapper rows, the layout guard on `key-forms`.
+
+  **What it asserts is not that every case is writable.** A source the readers
+  accept may be one the writers must refuse, and `key-forms` now is. The
+  property is that a writer's answer is always *located* or *refused for a
+  stated reason*, never the third thing — located, wrongly — and which cases are
+  refused is a table someone has to edit rather than a branch that can drift.
+
+  *Widened while pointing it: the `satisfies` row did not cover the spelling
+  that broke.* It applied the keyword to a param value, where the value reader
+  sees it, and not to the registry argument, where the walk that finds the
+  literal does — so it stayed green through a defect named after it. It now
+  carries both positions, as the `as-const` row beside it always did.
+
+- **`readArchivedChanges`' fan-out is bounded — the fourth one, and the first
+  outside `locate.ts`.** `archive.ts` read every archived first-run record
+  through a `Promise.all(names.map(…))`, so a project with N merged changes held
+  N reads and N parsed `RedRecord`s at once. It is the same shape as the other
+  three against an input nobody here chooses — an `archive/` grows by one folder
+  per change merged and is never pruned, so it is the longest-lived of the four
+  lists a project's shape decides the length of. Measured in
+  `tests/locate-fanout.spec.ts`, which now counts a fourth pool: **64 before, 32
+  after**, on 64 archived changes. Unbounded, the figure is the count of the
+  folders; bounded, it is the constant.
+
+  *Why it hid is that the pool's own doc comment names the rule and this caller
+  is not in the file that has it.* `forEachBounded` says "anything here that
+  reads a list the project's tree decides the length of belongs in this pool,
+  whatever the function around it is called" — and `readArchivedChanges` is
+  exactly that, one module over. The nearest comment to it reasons carefully
+  about concurrency and still says nothing about a bound: `inspectRedEvidence`
+  explains why it runs the archive read *after* `inspectProject` rather than
+  beside it — "overlapping them buys nothing worth a second fan-out" — which is
+  a correct answer about sequencing two reads and not a claim about what happens
+  inside either. That is the third time in this catalogue a considered comment
+  about concurrency has stood where a bound was missing. `forEachBounded` is now
+  exported for it, with a fourth constant on the reason `WALK_CONCURRENCY`
+  already gives.
+
+  **The failure this invites is memory, not descriptors — and that corrects the
+  three entries above.** Each of those closed by calling descriptor exhaustion
+  the invited failure and leaving it unmeasured. Measured now, on Linux: it is
+  not reachable through this shape at all. `fs.promises.readFile` does
+  open-read-close inside one libuv threadpool work item, so concurrent
+  *descriptors* are bounded by the threadpool and never by the fan-out — 3,000
+  unbounded in-flight reads peaked at **53** entries in `/proc/self/fd`, and the
+  read completed cleanly under `ulimit -n 256`, and again under `ulimit -n 128`
+  with `UV_THREADPOOL_SIZE=1024`. What does track the input is heap: on 2,000
+  changes of a 45 KB record, peak `heapUsed` was **352 MB unbounded against 177
+  MB bounded**, over interleaved runs — and the unbounded figure wandered from
+  329 to 580 MB across rounds while the bounded one held 177–181. The stable
+  number is the point; the retained result is the floor, and what the bound
+  removes is the transient pile on top of it. This is the portable-arithmetic
+  standard the three earlier halves were accepted on, so it needs no incident
+  report — but the *reason* is memory, and future sweeps should stop reaching
+  for `ulimit`, which does not govern this on either platform: Windows uses
+  Win32 handles, and on Linux the threadpool gets there first.
+
+  Reached only from `inspectRedEvidence` and so from `@am_shork/attest/inspect`,
+  the published subpath — no CLI command reads the archive, which is why the
+  static-command roster is untouched by this. No behaviour change and no
+  `ATX-n`, on the precedent of the other three: the changes, their order, their
+  paths and the merged record are identical, asserted beside the peak. The
+  result is built by preallocate-and-index rather than by arrival, which is what
+  keeps the sorted folder order true through a pool that completes out of order.
+
+- **The publish job runs on protected tags only, and it says so in the file
+  rather than in a settings page.** `rules` was `if: $CI_COMMIT_TAG`; it is now
+  `if: $CI_COMMIT_TAG && $CI_COMMIT_REF_PROTECTED == "true"`.
+
+  *The reason it needed to be in the file is that the comment beside it claimed
+  a defence that does not exist.* It said the reason to protect release tags had
+  changed — from exposing a masked variable to `id_tokens` being "issued to
+  protected refs only". That is not how GitLab issues them. Every job gets an ID
+  token, and the protection state travels *inside* it as the `ref_protected`
+  claim; a design that reports protection as a payload field is one where an
+  unprotected ref is handed a token too. Nothing on npm's end narrows it either:
+  a GitLab trusted publisher is namespace + project + top-level CI file path +
+  optional environment, with no ref condition available to configure.
+
+  **So the entire ref authorisation was the `rules` line — evaluated from the
+  `.gitlab-ci.yml` at the pushed tag, which is a file the pusher had just
+  written.** "Can push a tag" was therefore "can publish `@am_shork/attest` with
+  a valid provenance attestation", and the `NPM_ID_TOKEN` guard added in the
+  entry below cannot narrow it: that guard asks whether a token exists, never
+  who caused one to be minted. Protected tags in *Settings -> Repository* were
+  the only thing standing there, described by the comment as a belt-and-braces
+  extra.
+
+  This is the shape this repository keeps finding — a defence that reads as
+  present and is not, alongside `bin/attest.js`'s static import, the `hasWarned`
+  spread and `hmr: false` — arriving this time in the sentence explaining a
+  defence rather than in the code implementing one. Keep the protected-tag rule
+  in Settings as well: only that side stops the tag being created, and this side
+  only declines to publish once it has been. *Found by review, not by a run —
+  no pipeline was executed to confirm it, and the two vendor behaviours above
+  are read off GitLab's ID-token documentation and npm's trusted-publisher
+  documentation rather than measured here.*
+
+- **The publish job has no stored credential left: `NPM_TOKEN` and the
+  `_authToken` line are gone, and the guard is on `NPM_ID_TOKEN` instead.**
+  Completes what `[0.9.4]` set up. The deletion test pointed here from the
+  start — what it removes is the only long-lived credential this repository had.
+
+  *It went in on a measurement, and the measurement is the part worth keeping.*
+  The v0.9.4 release published through the trusted publisher, not the token:
+  `_npmUser` on that version is
+  `{"name":"GitLab CI/CD","trustedPublisher":{"id":"gitlab","oidcConfigId":"oidc:…"}}`,
+  by npm 11.19.0. The entry that proposed this recorded that **no account existed
+  anywhere of publishing from GitLab under OIDC** — every report was GitHub
+  Actions — and stated the inference at the strength the evidence carried. That
+  release is the first record. The token was present and unused: `oidc()`
+  overwrites the auth key on success, so the `.npmrc` line never applied.
+
+  **The job's own log could not have told us, and that is why the fallback had
+  to go.** Every path in npm's `oidc.js` logs at `verbose` or `silly` while npm's
+  default level is `notice`, so a successful exchange and a failed one produce
+  byte-identical job output — the v0.9.4 log contains no OIDC line of either
+  kind. Combine that with a fallback written never to throw and the failure mode
+  is exact: an exchange that stops working keeps publishing, on the credential
+  the exchange exists to retire, silently, with the difference visible only in
+  registry metadata nobody reads. **The property that made the rollout cheap is
+  the wrong one to keep**, and this is the first time in this file that a
+  mechanism has been removed for succeeding rather than for failing.
+
+  So the check moves in front of the irreversible step, which is the rule the
+  removed post-publish attestation check failed and this file already argued:
+  verification belongs where it can act on the answer. A missing `NPM_ID_TOKEN`
+  now fails before anything is published; a failed exchange fails the publish
+  outright, loudly and recoverably, because nothing was written.
+
+  *What is not in this repository, and is not done by this entry.* One act on
+  npmjs.com: *Require two-factor authentication and disallow tokens* on the
+  package, which is what stops a leaked token publishing it and which npm states
+  does not affect trusted publishers. Not a commit and not verifiable from here.
+
+  *The `NPM_TOKEN` CI variable stays, deliberately, and the reasoning is worth
+  recording because the first version of this entry had it wrong.* Deleting it
+  was filed beside the npm setting as though the two were equal acts. They are
+  not: the setting removes the **capability** — a token can no longer publish this
+  package — while deleting the variable removes **one copy** of a credential that
+  goes on existing in the npm account either way. Revoking it there is the act
+  that destroys it; removing it from GitLab is housekeeping. The variable is
+  masked, protected, exposed only to protected refs, and now read by no job, so
+  what it costs to keep is nothing. What the setting does not cover is measured
+  rather than assumed: it is per-package, and `@am_shork/attest` is the only
+  package in the scope, so today it covers the account's entire published
+  surface exactly. The gap it leaves is future-conditional — a second package
+  would start without the setting — and that is an obligation attached to
+  publishing a new package, not a reason to move a variable. *And the next tagged release is the test of this change*, the same way
+  v0.9.4 was the test of the last one — except that this time a regression fails
+  the release instead of quietly publishing. That is the intended trade.
+
+### Added
+
+- **`ATX-83` states the three states of that field.** What was missing was never
+  the field; it was a sentence the suite could falsify about *when* the field is
+  there. A requirement saying only "the report carries the paths the merge wrote"
+  is satisfied completely by an implementation that always emits `[]`, and that
+  implementation is wrong in exactly the case the field is reached for — a re-run
+  after a completed merge.
+
+  *Written straight into the registry, not through `changes/`.* That is how
+  existing behaviour is described here, and it is the reading `ATX-80`'s
+  `unarchived` state exists for: `never-red` asks for a recorded failing run only
+  of the ids a change is currently ADDing, so a requirement catching up to
+  behaviour that already shipped carries no such obligation and gains nothing
+  from a workflow whose point is to make a scenario fail before the code exists.
+  The scenario lives beside the other `archiveReport` ones in
+  `self/json.spec.ts`, where a reader looking at that function finds all of them.
+  Nothing records that it discriminates, which is what `unarchived` costs and is
+  worth saying rather than leaving implicit — so it was checked by hand instead:
+  with the one line that spreads the field into the report removed, the scenario
+  fails, and `verify self` reports `tests-red`.
+
+  The measurement in `tests/intent-rule-candidates.spec.ts` moved by exactly one
+  requirement — corpus 93 → 94, universal quantifiers 40 → 41 — and no verdict
+  in it flipped. It also produced the `flag:` divergence key's **fourth**
+  re-keying in four releases, every one triggered by an addition that agrees
+  with a member already there, and the `field:` key's first *extension* rather
+  than re-keying; both are noted where the rule is judged, because which of the
+  two an addition causes turns on vocabulary rather than on how related the
+  requirements are.
+
+- **`archive --apply --json` reports the paths the merge wrote.** The human
+  rendering has listed them since `--apply` shipped, on the grounds that this is
+  the command that edits files the user cannot regenerate and the reader needs to
+  know which ones to look at before committing. The `--json` reader — the one
+  most likely to be automating around the merge — got the change name and nothing
+  else. `written[]` closes that, and both renderings are now handed the same
+  bundle from one place in the shell rather than each being told separately,
+  which is the split that let the verdict disagree with itself in `[0.7.0]`.
+
+  **Absent without `--apply`, `[]` with it.** The two are different facts — no
+  merge was attempted, against a merge that ran and had nothing left to write,
+  which is the ordinary state of a re-run after a completed one — and a field
+  that spelled both `[]` could not say which. Additive, so no `SCHEMA_VERSION`
+  bump: a consumer that has never heard of the field reads the report it always
+  did. ATX-74's sweep covers it like every other string a report quotes out of
+  the checked project.
+
+### Fixed
+
+- **`first-run.json` committed different bytes for the same evidence, depending
+  on how many runs it took to gather.** `mergeRedRecord` rebuilds the record so
+  key order is a function of the data rather than of insertion — and did that at
+  two of its three levels. The rebuild sorts the requirement ids the record
+  already held; the loop after it *appends* the ids this run is the first to
+  observe, in plan order; and the pass at the bottom re-sorted the file and
+  scenario levels while walking the ids in whatever order they were in, because
+  reassigning `record[id]` does not move a key.
+
+  So a change that grew its record over several stage-1 runs committed
+  `{"Z-9": …, "A-1": …}` where the same observations reached in one run committed
+  `{"A-1": …, "Z-9": …}`. Nothing about the outcomes differs; the file does. That
+  matters twice over for this particular file: it is evidence a reviewer reads in
+  a diff, and the gate has to reach the same verdict on a CI checkout as on the
+  author's machine. It also went unnoticed once written — `changed` is decided by
+  the outcomes alone, so an unchanged record is never rewritten and a
+  wrongly-ordered one stays that way.
+
+  *ATX-15 already said this and could not catch it.* The requirement quantifies
+  over "every ordering Attest commits to disk", and the sweep attesting it is
+  deliberately narrower than its own statement: it checks *how* a site orders —
+  every `.sort` in `src/` through `byCodeUnit` — and says so, *"a `red-record.ts`
+  that stopped sorting at all is still green here, and the scenarios above are
+  what speak to the result"*. There was no such scenario for this file. There is
+  now, in `self/red-record.spec.ts`: it reaches the same evidence by both routes
+  and compares the serialised bytes. `archive.ts`'s `sortRecord` had all three
+  levels right and is what this now matches.
+
+- **`--apply` refused a registry whose literal is written with `as const`,
+  `satisfies`, or a bare pair of parentheses.** The reader takes all three —
+  `unwrap` strips the type-level wrappers before `literalValue` reads the object,
+  because none of them changes the value — so the gate read such a file, proved
+  the change green, and handed it to a merge that asked
+  `ts.isObjectLiteralExpression` of the wrapper and got `false`. Both writers
+  refused: the whole change stopped with `internal-error`, whose own message says
+  the file *"read as a registry for the gate but not for the merge"* and whose
+  comment calls the condition unreachable through the command. It was reachable
+  by writing `defineRequirements(({ … }))`.
+
+  *The fix is where the two answers diverged, not where the symptom showed.*
+  `authoringCall` is the single function both sides use to find the registry
+  literal — the module's opening note says a second walker would be a second
+  answer to "is this a literal" — and it handed back the argument node as
+  written, leaving each caller to decide whether to unwrap. The reader did and
+  the writers did not, so the disagreement the shared function exists to prevent
+  was inside it. It now unwraps once, and `literalValue`'s own call becomes the
+  no-op it should always have been.
+
+  The parenthesis is the reachable spelling and the reason this is a fix rather
+  than a nicety: `as const` and `satisfies` are opted into, while nothing about
+  `(({ … }))` looks like a type annotation anyone chose. No `SCHEMA_VERSION`
+  bump and no new code — a change that used to fail now succeeds, which is the
+  benign direction for an exit code, and the History row is what tells a reader
+  on an older build which half of the page applies to them.
+
+- **A registry key written twice made `archive --apply` write bytes outside the
+  value it was replacing — and, measured, outside the registry literal
+  altogether.** `registryEntryLayouts` keys each value's source span by name in
+  a `Map`, and `spliceModifications` walks that map to get its edits in
+  ascending offset order, which is what lets the pass at the bottom be a
+  `reverse()` rather than a sort. `Map.set` on a key it already holds keeps the
+  **first** insertion's position and takes the **last** call's value — so an
+  entry writing `params: { limit: 1, other: 'x', limit: 1 }` describes `limit`
+  at position one carrying the span of the occurrence *after* `other`, and the
+  offsets stop ascending. The earlier edit then moves the bytes under the later
+  one. On a registry the gate had just proved green, changing both values landed
+  the second one past the file's closing `});`.
+
+  *Nothing upstream refuses such a file, which is why this reached the one
+  command that writes.* A duplicate key is a TypeScript **semantic** error, and
+  `parseSource` asks only the syntactic question (`[0.9.0]`, ATX-69) — so both
+  registry readers take the file and hand back the last occurrence, `check` is
+  silent, and the gate passes. The reachable route is an ordinary copy-paste in
+  a hand-written registry, in a project that does not typecheck its
+  `*.reqs.ts`.
+
+  **Refused rather than described, at all three levels.** An entry whose keys
+  repeat is left out of the layout with the repeated key's path recorded beside
+  it, and `spliceModifications` turns that into an `apply-unsupported-delta`
+  refusal — whole, with nothing written — before a single edit is pushed. The
+  id level is not the mild one and is refused for the same reason rather than a
+  weaker one: two entries under a single id put a *later* entry's spans at an
+  *earlier* entry's position, so the disorder is between entries rather than
+  inside one. The guard stays exactly as wide as the danger — an unrelated id in
+  the same file is still written — because a merge that stopped over something
+  it was not asked to touch is the thing `--apply` refuses to do everywhere
+  else.
+
+  *The sibling defect is already in this file and did not generalise on its
+  own.* `[0.8.0]` fixed an integer-like `params` key for the identical
+  invariant — JavaScript hoists it to the front of every object, so a plain
+  object could not carry the file's order — and the repair was to move all three
+  levels to `Map`s. That answered the container and left the *keys*: a `Map`
+  keeps insertion order for every key type, and the one thing it still cannot
+  represent is one key written twice. The test added then, `rewrites two params
+  when one of them has an integer-like key`, is the shape of the three added
+  here, down to needing two changed values of different lengths — one edit
+  cannot be out of order with itself.
+
+  `verifyWritten` did catch the result and stop the merge, so the failure was
+  never silent; the file had already been overwritten by then, which is the
+  "destructive on a file the user cannot regenerate" shape the `AGENTS.md` merge
+  tool was rejected for and the reason a post-hoc check is not where this
+  belongs.
+
+  **Breaking, and narrowly so — this is the entry that decides the version
+  number.** The common case is not: a repeated key usually made the merge write
+  outside the value and the re-read then failed it, so the run already exited 1
+  and only the `code` moves — `internal-error`, raised after the registry had
+  been overwritten, becomes `apply-unsupported-delta`, raised before anything is
+  written.
+
+  But the offsets only go wrong when an earlier edit *changes length*. A
+  modification that replaces a value with one the same size shifts nothing, so
+  on `[0.9.4]` such a merge completed and completed **correctly**. Measured on a
+  registry with a duplicated `statement` and a `budgetMb: 1` → `2` patch: 0.9.4
+  merges it and it reads back as `{"budgetMb":2}`; today it refuses. That is
+  previously-valid input now rejected, which is this file's own definition of
+  breaking, so it takes the **minor** rather than the patch.
+
+  The refusal is still right — the same file with a length-changing patch is the
+  corruption above, and which of the two a merge gets is not something the author
+  chose. What the narrowness costs is that an adopter whose registry happens to
+  carry a duplicate key sees a working command start refusing, so it belongs in a
+  minor with the reason stated rather than in a patch nobody reads.
+
+  No `SCHEMA_VERSION` bump: the envelope, the `Issue` interface and the roster in
+  `core/docs.ts` are all unchanged — the refusal reuses the code `--apply`
+  already raises for a delta it will not write.
+
+  **`ATX-76` is widened to say what it always meant**, through this
+  repository's own workflow — `self/archive/2026-08-21-widen-atx-76`, the second
+  change to go through it and the first carrying a MODIFIED. Its refusal clause
+  named one instance of a class: *"when a span it would overwrite carries a
+  comment"*. Refusing a comment inside a span is not a rule about comments, it is
+  the rule that a replacement may only ever write the value it was asked to
+  write, stated at the one place that value's boundary was known to be in doubt.
+  A repeated name puts it in doubt a second way, so the clause now reads
+  *"wherever the file leaves that span uncertain"* and lists both. What is
+  **not** stated is the refusal as a mechanism: refusing is how *this*
+  implementation keeps the first clause, and a rewrite could keep it by ordering
+  the edits instead — a requirement pinned to the remedy would forbid that repair
+  for no reason.
+
+  *The defect was never that the rule was absent.* The first clause — the unit of
+  the edit is the value — has said this since `[0.9.0]`. What was missing was a
+  sentence the suite could falsify in this direction: both existing scenarios
+  assert something about a **comment**, and neither can go red when the failure
+  is that the span located was the wrong one. `self/merge.spec.ts` now carries a
+  third, looping the three sites a name can repeat with the extent pinned beside
+  the loop. Measured with the fix reverted, at the `spliceModifications` seam:
+  all three wrote without refusing; with it, all three refuse.
+
+### Documentation
+
+- **The CLI reference told readers the `--json` guarantee rests on
+  `JSON.stringify`, which is the reasoning `[0.8.0]` retired.** *Output is safe
+  to read* closed with "`--json` was never exposed: serialising escapes the same
+  characters" — true of C0 and of nothing else, so DEL and the C1 range were
+  never covered by it. The code has been right since `[0.8.0]`, where the
+  replacer in `renderJson` began stripping every string in the document as it
+  serialises one; the page kept the retired argument, in both languages, three
+  hundred lines above its own History row saying the opposite.
+
+  *The comment at the crash site in `cli/action.ts` said it too*, and that copy
+  is the one worth naming: it sat directly above `renderJson(errorReport(…))`
+  and read as a settled argument for why sanitising there was unnecessary. The
+  replacer it argues against is what makes that line safe. Nothing was
+  exploitable — this is a false rationale standing beside a working defence,
+  which is the configuration that gets a defence deleted by someone tidying up.
+
+  Found by an attack-surface review rather than by a gate, and no gate could
+  have found it: the suite checks that a `§n` a comment cites exists and that a
+  version a History table names is a heading here, never whether a sentence is
+  true. Three copies of one retired claim is what that gap looks like from
+  inside. No behaviour changed and no version moved, so there is no new History
+  row — the `[0.8.0]` row was correct all along and is what the prose now agrees
+  with.
+
+- **The method page says which shape a composite param is best at, and the
+  sample is a fixture that runs.** `intent-quality.md` already carried both
+  hazards a list-valued param has — an expectation recomputed from the param it
+  is checking, and a loop whose extent nobody pinned — as the third and fourth
+  of its five findings, named and left there with no shape attached. A **decision table**, rules pairing conditions with the
+  outputs the requirement promises, is where both arrive at once and where the
+  single source pays most, so it is now named. The section states the property
+  the shape actually rests on, which is narrower than "use a table": the
+  implementation reads only the *condition* columns, which leaves the output
+  columns an independent term — and it stops being true the moment the system
+  under test is itself driven by the same rules.
+
+  *The sample is `fixtures/consumer/requirements/cart.reqs.ts` and
+  `fixtures/consumer/cart.spec.ts`*, added here and registered in
+  `PUBLISHED_SAMPLES`, because every `ts` block this page publishes was already
+  a file the packaging test installs from a tarball and runs, and half-real
+  samples teach a reader to check which — after which they stop. **Making it
+  real is what found the constraint the section now documents**: the statement
+  cannot interpolate the table. A `{placeholder}` resolves to a scalar or a list
+  of scalars, so `{rules}` is `non-scalar-interpolation`, and the statement has
+  to name the behaviour in prose while the rules stay a param the scenario reads.
+  A draft written only as prose had it wrong and nothing would have said so.
+
+  It also landed on an existing row rather than needing a new rule:
+  `intent-rule-candidates.spec.ts` classifies it `over: 'roster'`,
+  `owner: 'registry'`, which is the branch that owes a `pin` — a registry-owned
+  list is data an author can shorten, and every assertion inside the loop still
+  passes over the shorter one. The published scenario carries that pin
+  (`expect(rules).toHaveLength(6)`), so a reader who copies the block copies the
+  counter-pressure with it.
+
+  *It was written into the README first, and has moved.* The README is the
+  pitch, the five-minute start and navigation; a hundred lines on how to write a
+  param that pins something is the method page's job, beside the two findings it
+  repairs. The README keeps one paragraph pointing at it. **The move is also
+  what showed `PUBLISHED_SAMPLES` could not say where a sample is published** —
+  it read the README and only the README, which was right while every sample
+  lived there and an obstacle the moment one did not. Each entry now carries its
+  page, so moving a sample between pages is a roster edit rather than a silent
+  loss of the gate that keeps it runnable.
+
 ## [0.9.4] - 2026-08-19
 
 ### Added
@@ -5437,33 +5958,6 @@ path the repair makes reachable; it is about **everything the repair would make
 `check` agree with**, and an entry that names the right fix can still be
 implemented wrongly by copying the half nobody has audited.
 
-- **Retiring `NPM_TOKEN`, which is now two settings on npmjs.com rather than
-  anything in this repository.** The mechanism landed under `[0.9.4]`: the
-  publish job requests an npm OIDC token and publishes through `npm`, which is
-  the only client that performs the exchange. What that did **not** do is remove
-  the credential, and the distinction is the point — enabling a trusted publisher
-  leaves an automation token just as able to publish. Two acts remain, neither of
-  them a commit:
-  **(1)** register the trusted publisher on the package — `Pseudorca`, `attest`,
-  `.gitlab-ci.yml` with the extension, the allowed actions; environment name is
-  optional and this project uses none, and shared runners are the only supported
-  kind, which the job already uses because it carries no `tags:`. Free and
-  reversible, and safe to do at any time: a failed exchange falls back to the
-  token rather than failing the publish (measured — see the `[0.9.4]`
-  entry). **(2)** set *Require two-factor authentication and disallow tokens* on
-  the package, which npm states does not affect trusted publishers. That is the
-  one that closes the loop the job's own comment opens, where an automation token
-  is used *because* a granular token fails against 2FA on writes: trusted
-  publishing does not bypass the prompt, it stops being a token.
-  *What is unmeasured, and it is not measurable from here.* Whether the exchange
-  actually succeeds against a gitlab.com project. Every documented ingredient
-  checks out and no plan requirement is stated anywhere, but there is no record
-  of anyone publishing from GitLab under OIDC — every account is GitHub Actions.
-  The first tagged release after the `[0.9.4]` change is the test, and the
-  fallback is what makes running it cheap: if the exchange fails, the release
-  still publishes and the job's verbose log says why. **Do not delete the token
-  before a release has been observed publishing without it.**
-
 ## Under consideration
 
 Candidates with **no decision yet**, between the two sections either side of it
@@ -6245,6 +6739,45 @@ have to gather again.
   release costs its adopters is not known on the day it is cut**. There is no
   measurement to date of anyone adopting either export.
 
+- **When one requirement carries several scenarios, some of those sets are
+  differential evidence and nothing in the model says which.** Prompted by an
+  external write-up (`columns.chicken-house.net`, 2025-11-10, "AI-First Testing
+  Workflow"), which ran one test case against a system's REST API and against its
+  web UI and found the empty-basket check implemented in the UI and absent from
+  the API. Neither run failed against its own expectation; the finding was that
+  two runs of the *same* case disagreed.
+
+  Attest already permits the arrangement — a `reqId` takes any number of
+  attesting scenarios, and `cover` asks only for ≥1. What it cannot see is the
+  difference between three scenarios covering three edges of one requirement and
+  three scenarios crossing three interfaces at the *same* edge. The second set
+  can be asserted to agree; the first cannot, and there is nothing to compare.
+  This repository runs the pattern on itself — `tests/static-registry.spec.ts`
+  asserts the two registry readers agree — so the structure is known to work
+  where the two adapters are known to be two adapters.
+
+  *What blocks it, in the order that decides it.* **The seam is unmeasured.** One
+  adapter is a hypothetical seam and two is a real one; nothing has been walked
+  to establish whether any adopted registry has a `reqId` whose scenarios
+  genuinely cross interfaces rather than covering one surface repeatedly. Until
+  that is counted this is a pattern observed in somebody else's codebase, and it
+  is cheap to count. **The fact is not in the model.** Which interface a scenario
+  crosses is recorded nowhere the engine reads, so supplying it means new
+  registry or spec surface — a per-scenario axis — paid for by every adopter
+  including all of the ones with a single interface, in the shape of a thing they
+  must learn not to write. Whatever carried it would also have to be a literal in
+  the AST, because `cover` executes nothing and that is not negotiable for it.
+  **There is no verdict to emit.** The engine cannot perform the comparison;
+  agreement between two runs is an assertion and assertions belong to the test.
+  The most it could report is that a requirement has scenarios on more than one
+  axis, which is information with no pass or fail attached — a new output
+  category rather than a new check. **And the prose alternative is untried.**
+  Apply the deletion test before the field: if the workflow document `init`
+  writes (§9) simply says that two scenarios crossing one requirement at
+  different interfaces should assert the same expectations, does the practice
+  happen anyway? If it does, the engine gained nothing and charged everyone a
+  field for it.
+
 ## Considered and rejected
 
 Decisions **not** to build something, kept where they can be found before the
@@ -6255,6 +6788,41 @@ it sat between 0.2.0 and 0.1.7 for two releases, where standing still meant
 sinking one version deeper each time a release was cut above it, and a rejection
 filed under a version reads as belonging to it.
 
+### Rewriting the placeholder scan in `prose` to drop its tail slice
+
+Priced on 2026-08-21, during a standing sweep for more of the ATX-59 shapes, and
+rejected by the measurement that was supposed to confirm it.
+
+`prose` (`core/render.ts`) walks a statement character by character, and at every
+`{` it runs `/^\{\w+\}/.exec(text.slice(i))`. Read as source that is the §2
+quadratic-scan shape exactly: one fresh copy of the remaining string per `{`, so
+a statement of n braces copies n²/2 bytes — and a statement is prose a fork
+contributor writes and `render --check` reads under the static reader, which is
+the class that has actually shipped defects here. The fix was to be a sticky
+`/\{\w+\}/y` with `lastIndex = i`, which allocates nothing.
+
+**It is not quadratic, because V8 does not copy.** `String.prototype.slice` on a
+string past a small threshold returns a *sliced string* — a view onto the parent
+with an offset, made in constant time — and an anchored regex over it reads only
+the few characters it needs, so the copy the source implies never happens.
+Measured through `renderMarkdown` on the built output, three adversarial shapes
+(all braces; alternating `{a`; a brace run followed by a word run), at 100k
+through 800k characters: every one of them scaled at a ratio of **1.77–1.89 per
+doubling**, i.e. linear, and 800,000 braces rendered in **106 ms** against
+ATX-59's 1,000 ms budget. A quadratic implementation at that size would be tens
+of seconds; this is the same order as the linear cases beside it.
+
+So there is no defect and no change. What the sticky rewrite would buy is a
+constant factor nobody has shown a need for, against §5's rule that
+micro-optimisation with no named input is out of scope — the input *is* named
+here, and it is already absorbed. Filed rather than dropped because the site
+reads like the defect on inspection and will be proposed again by the next sweep
+that greps for `.slice(` near a loop: the answer is that V8's representation is
+load-bearing, the measurement is the evidence, and the thing to re-run is the
+ratio rather than the reasoning. Note the limit of that claim — it rests on a V8
+representation rather than on anything the language promises, which is safe for a
+Node CLI and would not transfer to a runtime that flattens eagerly.
+
 ### Deferring the `typescript` import so `init` and `--version` do not pay it
 
 Priced on 2026-08-13, in the session that enabled the compile cache above, and
@@ -7149,6 +7717,7 @@ rather than a scorer, which ranks.
 
 ## Releases
 
+[0.10.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.10.0
 [0.9.4]: https://gitlab.com/Pseudorca/attest/-/tags/v0.9.4
 [0.9.3]: https://gitlab.com/Pseudorca/attest/-/tags/v0.9.3
 [0.9.2]: https://gitlab.com/Pseudorca/attest/-/tags/v0.9.2

package/README.md

@@ -16,28 +16,6 @@ anyone when a tuning knob changes. A param may be any JSON value, so a
 composite constant — a vendor blacklist, a `kind -> payload` table — gets the
 same single source as a lone number, which is where drift is worst.
 
-What that does not buy is a warning when you change the value. `check` runs
-nothing, so editing a param leaves it at `✓ No issues` — nothing became unbound,
-nothing became uncovered. The value cannot *diverge* from the assertion, which is
-the stronger property; noticing that it *moved* is `verify`'s job, and only when
-a scenario asserts on the value it read from `params`.
-
-Reading the param is necessary and **not sufficient**, which is worth knowing
-before you rely on it: an assertion that recomputes its expectation from the same
-param the code under test just read has no independent term, so both sides move
-together and the test stays green through any edit. Pin the expectation to
-something that does not move with the param — a fixture, a literal in the test,
-or a second independently derived value.
-
-A composite param has a second failure of its own, and it runs the other way. When
-a test **loops over** a list it read from `params`, that list is the set of cases
-the run covers: drop a member and every assertion inside the loop still passes
-over what is left, so the suite quietly tests less with nothing to show for it.
-Pin the extent beside the loop — the members against a literal when their identity
-is the promise, the length when the size is. That literal is not the copy the
-single source exists to prevent: it is not what the system is measured against,
-it is what the intent claimed to cover.
-
 ## Prerequisites
 
 - Node ≥ 20.19
@@ -134,7 +112,14 @@ for exactly one machine-readable document on stdout. Flags, per-command
 behaviour and the JSON shape are in the
 [CLI reference](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/cli-reference.md).
 
-### Working with an agent
+Reading a param is necessary and **not sufficient** — an assertion that
+recomputes its expectation from the same param the code just read has no
+independent term, and a scenario that loops over a list param covers exactly
+that list. Both have a known shape and a known repair, and both are in
+[Judging your own intent layer](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/intent-quality.md#writing-a-param-that-pins-something),
+along with the decision table — the shape a composite param is best at.
+
+## Working with an agent
 
 The engine above is only half the framework. The other half is the workflow —
 agree on intent, write the delta, drive the scenarios red, then implement to
@@ -159,7 +144,7 @@ found or pasted. See
 [`attest init`](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/cli-reference.md#attest-init)
 for the targets and what `init` deliberately does not write.
 
-### When something goes wrong
+## When something goes wrong
 
 Every diagnostic carries a `code`, and every code has a section in
 **Troubleshooting** — which the diagnostic itself links to:
@@ -167,7 +152,7 @@ Every diagnostic carries a `code`, and every code has a section in
 ```
 ERROR   registry-not-static (requirements/upload.reqs.ts:5)
     Value is not a literal.
-    → https://gitlab.com/Pseudorca/attest/-/blob/v0.9.4/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.10.0/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section

package/dist/cli/action.js

@@ -73,10 +73,14 @@ export async function runAction(command, opts, action) {
     }
     catch (err) {
         if (opts.json) {
-            // Unsanitised on purpose: `JSON.stringify` escapes every C0 character,
-            // so these bytes cannot carry one out (see report.ts). That is a claim
-            // about what this line writes and nothing wider — what the project under
-            // test writes is the divert's business, above.
+            // Sanitised, though not on this line: `renderJson` strips every string in
+            // the document as it serialises it (ATX-74), so the crash path is covered
+            // by going through the same function every other report goes through.
+            //
+            // Not by `JSON.stringify`, which is what this comment used to claim. That
+            // escapes C0 and nothing else — DEL and the C1 range survive it — so the
+            // replacer in `renderJson` is load-bearing rather than belt and braces.
+            // What the project under test writes is still the divert's business, above.
             console.log(renderJson(errorReport(VERSION, command, err)));
         }
         else {

package/dist/cli/index.js

@@ -261,10 +261,15 @@ program
     const { issues: blocking, written } = await run(root(dir), change, {
         vitestConfig: vitestConfig(opts),
     });
+    // Built once and handed to both renderings, rather than each being told
+    // separately what the merge did. Two renderings of one result agreeing by
+    // transcription is what let the verdict disagree with itself (ATX-60),
+    // and the paths are the other thing this command has to say.
+    const merge = { applied: opts.apply === true, written };
     return {
-        report: archiveReport(VERSION, change, blocking),
+        report: archiveReport(VERSION, change, blocking, merge),
         human: () => {
-            console.log(formatArchiveVerdict(change, blocking, { applied: opts.apply === true, written }));
+            console.log(formatArchiveVerdict(change, blocking, merge));
         },
     };
 }));

package/dist/cli/json.d.ts

@@ -33,6 +33,22 @@ export interface JsonReport {
     };
     /** `archive` and `status`: the change being gated or reported on. */
     change?: string;
+    /**
+     * `archive --apply` only: every path the merge touched, relative to the
+     * project root, in the order it touched them.
+     *
+     * Additive, so no SCHEMA_VERSION bump. **Absent** when `--apply` was not
+     * asked for — no merge was attempted, and there is nothing to report — while
+     * an **empty array** means the merge ran and had nothing left to write, which
+     * is the ordinary state of a re-run after a completed one. Folding the two
+     * into `[]` would make the field unable to say which happened.
+     *
+     * The human rendering has printed these since `--apply` shipped, on the
+     * grounds that this is the command that edits files the user cannot
+     * regenerate and they need to know which ones to read before committing. That
+     * argument does not stop at the reader with a terminal.
+     */
+    written?: string[];
     /** `status` only: one row per requirement the change adds. */
     progress?: StatusRow[];
     /** `status` only: roll-up of the rows by obligation state. */
@@ -83,7 +99,18 @@ export declare function renderReport(version: string, issues: Issue[], outFile?:
  * was added for, to say something the array already says.
  */
 export declare function initReport(version: string, issues: Issue[], outFiles: string[]): JsonReport;
-export declare function archiveReport(version: string, change: string, blocking: Issue[]): JsonReport;
+/**
+ * `archive`, and — when `--apply` was asked for — what the merge wrote.
+ *
+ * `merge` is the same bundle `formatArchiveVerdict` takes, passed to both from
+ * one place in the shell. The two renderings of one result had already grown
+ * apart once over the verdict (ATX-60); handing them the same object is what
+ * stops the paths from being the second thing they disagree about.
+ */
+export declare function archiveReport(version: string, change: string, blocking: Issue[], merge?: {
+    applied: boolean;
+    written: readonly string[];
+}): JsonReport;
 /**
  * `status`. The progress rows never touch the verdict: `ok` comes from the same
  * `hasError` predicate as everywhere else, over an `issues` array that carries

package/dist/cli/json.js

@@ -109,7 +109,15 @@ export function initReport(version, issues, outFiles) {
     const [only] = outFiles;
     return outFiles.length === 1 && only !== undefined ? { ...report, outFile: only } : report;
 }
-export function archiveReport(version, change, blocking) {
+/**
+ * `archive`, and — when `--apply` was asked for — what the merge wrote.
+ *
+ * `merge` is the same bundle `formatArchiveVerdict` takes, passed to both from
+ * one place in the shell. The two renderings of one result had already grown
+ * apart once over the verdict (ATX-60); handing them the same object is what
+ * stops the paths from being the second thing they disagree about.
+ */
+export function archiveReport(version, change, blocking, merge) {
     return {
         ...envelope({
             version,
@@ -123,6 +131,7 @@ export function archiveReport(version, change, blocking) {
             issues: blocking,
         }),
         change,
+        ...(merge?.applied ? { written: [...merge.written] } : {}),
     };
 }
 /**

package/dist/core/archive.js

@@ -35,11 +35,26 @@
 // present without a given scenario is one that did and then drifted.
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { forEachBounded } from './locate.js';
 import { byCodeUnit } from './order.js';
 import { relativePath } from './paths.js';
 import { keepOutcome, readRedRecordIn } from './red-record.js';
 /** The directory archived changes are moved into, under the project root. */
 const ARCHIVE_DIR = 'archive';
+/**
+ * How many archived first-run records are read at once. Its own constant for
+ * the reason `WALK_CONCURRENCY` gives, and a fourth resource: what this bounds
+ * is the *parsed records held at once*, not descriptors. `readFile` does
+ * open-read-close inside one libuv threadpool work item, so concurrent
+ * descriptors track the threadpool and never the fan-out — measured, 3,000
+ * unbounded reads peaked at 53 open handles. Heap is what tracks the input, and
+ * a project's archive grows by one folder per change merged, forever, so the
+ * list is as much the project's shape as a spec tree is.
+ * `Promise.all(names.map(...))` put every record in flight at once: measured at
+ * the `fs` seam, 64 changes peaked at 64 concurrent reads, and 2,000 records of
+ * 45 KB peaked at 352 MB of heap against 177 MB bounded.
+ */
+const ARCHIVE_CONCURRENCY = 32;
 /**
  * Read every archived change folder under `root`.
  *
@@ -67,10 +82,18 @@ export async function readArchivedChanges(root) {
         .filter((e) => e.isDirectory())
         .map((e) => e.name)
         .sort(byCodeUnit);
-    return Promise.all(names.map(async (name) => {
+    // Preallocated and written by `index`, which is how a `forEachBounded` caller
+    // keeps a stable result: the pool calls in input order but completes in
+    // whatever order the disk answers, and `names` is already sorted above.
+    const changes = new Array(names.length);
+    await forEachBounded(names, ARCHIVE_CONCURRENCY, async (name, i) => {
+        // `readRedRecordIn` catches its own read and parse, so nothing here can
+        // throw and abandon the rest — the same thing `readGuarded` is for on the
+        // registry pool, and what keeps every slot of the array above filled.
         const path = join(dir, name);
-        return { name, path: relativePath(root, path), firstRun: await readRedRecordIn(path) };
-    }));
+        changes[i] = { name, path: relativePath(root, path), firstRun: await readRedRecordIn(path) };
+    });
+    return changes;
 }
 /**
  * The archive's first-run evidence, merged across every archived change.

package/dist/core/locate.d.ts

@@ -20,6 +20,33 @@ export declare const isProposedSpecFile: (name: string) => boolean;
  * of them until its gate passes.
  */
 export declare const isSpecFile: (name: string) => boolean;
+/**
+ * Run `fn` over every item with at most `limit` of them in flight.
+ *
+ * Extracted at the second call site rather than the first, because a shape
+ * written N times is one a later fix reaches only some copies of.
+ *
+ * **There are three, and the third is the one to look for.** `findFiles` and
+ * `parseSpecs` are named for what they fan out over; `loadRegistry` is named for
+ * merging, and its concurrency sits under a comment about *ordering* that
+ * answers a different question convincingly. Anything here that reads a list the
+ * project's tree decides the length of belongs in this pool, whatever the
+ * function around it is called.
+ *
+ * The order `fn` is *called* in is the input order; the order it *completes* in
+ * is not, so a caller that needs a stable result either indexes into a
+ * preallocated array by `index` or sorts afterwards. All three callers here do
+ * one of those, deliberately — as does `readArchivedChanges`, the caller
+ * outside this file, which preallocates and writes by `index`.
+ *
+ * No result is collected and none is needed — every caller writes into something
+ * it already owns, and a version returning `T[]` would have to choose an
+ * ordering on their behalf. A throw from `fn` propagates and abandons the rest,
+ * which is the existing behaviour at all three sites: `parseSpecs` and
+ * `loadRegistry` catch per file so that one hostile source scraps only itself
+ * (ATX-65), and a failed `readdir` really does end the walk.
+ */
+export declare function forEachBounded<T>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<void>): Promise<void>;
 /**
  * Recursively find files under root whose basename matches `match`.
  *

package/dist/core/locate.js

@@ -56,7 +56,8 @@ export const isSpecFile = (name) => name.endsWith('.spec.ts') && !isProposedSpec
  * The order `fn` is *called* in is the input order; the order it *completes* in
  * is not, so a caller that needs a stable result either indexes into a
  * preallocated array by `index` or sorts afterwards. All three callers here do
- * one of those, deliberately.
+ * one of those, deliberately — as does `readArchivedChanges`, the caller
+ * outside this file, which preallocates and writes by `index`.
  *
  * No result is collected and none is needed — every caller writes into something
  * it already owns, and a version returning `T[]` would have to choose an
@@ -65,7 +66,7 @@ export const isSpecFile = (name) => name.endsWith('.spec.ts') && !isProposedSpec
  * `loadRegistry` catch per file so that one hostile source scraps only itself
  * (ATX-65), and a failed `readdir` really does end the walk.
  */
-async function forEachBounded(items, limit, fn) {
+export async function forEachBounded(items, limit, fn) {
     let cursor = 0;
     const worker = async () => {
         for (let i = cursor++; i < items.length; i = cursor++) {

package/dist/core/merge.js

@@ -319,6 +319,7 @@ function modifyRefusal(root, file, refusal) {
     const where = refusal.field ? `${refusal.reqId}.${refusal.field}` : refusal.reqId;
     const why = {
         comment: `a comment sits inside the value it would replace, and which side of that edit the comment belongs to is not something --apply can decide`,
+        'duplicate-key': `that name is written more than once in the file, so the span --apply located is not the one the registry's readers evaluate`,
         'entry-not-found': `the registry file that owns its prefix holds no entry for it`,
         'not-a-literal': `the value it would replace is not written as a literal`,
         'param-dropped': `the proved end state does not carry that param, and a delta has no way to say one was removed`,

package/dist/core/red-record.js

@@ -320,20 +320,30 @@ export function mergeRedRecord(existing, plan, run, addedIds) {
         forFile[s.name] = kept;
         changed = true;
     }
-    // Sort within each requirement, and within each file, for the same
-    // byte-stability reason.
-    for (const id of Object.keys(record)) {
+    // Sort at every level, for the same byte-stability reason — the ids included.
+    //
+    // The rebuild above sorts only the ids the record already held; the loop after
+    // it *appends* the ones this run is the first to observe, in plan order. So
+    // the ids are unsorted by the time this runs, and this is the level that has
+    // to put them in order.
+    //
+    // A rebuild rather than an in-place sort, which is the trap: reassigning
+    // `record[id]` writes a value and does not move a key, so a version of this
+    // that sorted the two inner levels while walking the ids as they came would
+    // leave the outer order exactly as it found it.
+    const sorted = emptyMap();
+    for (const id of Object.keys(record).sort(byCodeUnit)) {
         const sortedFiles = emptyMap();
         for (const file of Object.keys(record[id]).sort(byCodeUnit)) {
-            const sorted = emptyMap();
+            const names = emptyMap();
             for (const name of Object.keys(record[id][file]).sort(byCodeUnit)) {
-                sorted[name] = record[id][file][name];
+                names[name] = record[id][file][name];
             }
-            sortedFiles[file] = sorted;
+            sortedFiles[file] = names;
         }
-        record[id] = sortedFiles;
+        sorted[id] = sortedFiles;
     }
-    return { record, changed };
+    return { record: sorted, changed };
 }
 /** Serialise the record. A trailing newline, so the file is a well-formed text file. */
 export function serialiseRedRecord(changeName, record) {

package/dist/core/splice.d.ts

@@ -65,7 +65,7 @@ export interface Modification {
 export interface ModifyRefusal {
     reqId: string;
     field?: string;
-    reason: 'comment' | 'entry-not-found' | 'not-a-literal' | 'param-dropped';
+    reason: 'comment' | 'duplicate-key' | 'entry-not-found' | 'not-a-literal' | 'param-dropped';
 }
 export type ModifyResult = {
     ok: true;

package/dist/core/splice.js

@@ -252,9 +252,18 @@ export function spliceModifications(file, source, changes) {
     const edits = [];
     const wanted = new Map(changes.map((change) => [change.id, change]));
     // Ids the file does not hold, first and in code-unit order: they have no
-    // position to be reported at, and the walk below is driven by positions.
+    // position to be reported at, and the walk below is driven by positions. An
+    // entry the reader refused to describe is reported as *why* rather than as
+    // absent — a file that writes one key twice does hold the entry, and
+    // `entry-not-found` would send its reader looking for something that is
+    // there. Both are decided before a single edit is pushed, because a refusal
+    // arriving mid-walk would leave `edits` half-built for an entry whose offsets
+    // are exactly the ones not to be trusted.
     for (const id of [...wanted.keys()].sort(byCodeUnit)) {
-        if (!layouts.has(id))
+        const twice = layouts.repeated.get(id);
+        if (twice)
+            refusals.push({ reqId: id, ...twice, reason: 'duplicate-key' });
+        else if (!layouts.byId.has(id))
             refusals.push({ reqId: id, reason: 'entry-not-found' });
     }
     // **The file front to back, not the delta.** Driving the walk from the layout
@@ -268,7 +277,7 @@ export function spliceModifications(file, source, changes) {
     // It is also why the layout is `Map`s rather than objects at every level; the
     // container is what carries the order, and `registryEntryLayouts` says why an
     // object cannot.
-    for (const [id, layout] of layouts) {
+    for (const [id, layout] of layouts.byId) {
         const change = wanted.get(id);
         if (!change)
             continue;

package/dist/core/static-registry.d.ts

@@ -135,6 +135,31 @@ export interface RegistryEntryLayout {
     /** Where a new field goes, inside the entry's own body. */
     fieldInsertion: RegistryInsertion;
 }
+/**
+ * The key an entry wrote twice, as the path the author would say it —
+ * `statement`, `params.limit`.
+ *
+ * Absent when what repeats is the entry's **own id**, which no field path
+ * names: `params.limit` is a place inside a requirement, and a second entry
+ * under one id is not inside anything.
+ */
+export interface RepeatedKey {
+    field?: string;
+}
+/** Every entry's layout, and the entries this reader refuses to describe. */
+export interface RegistryLayouts {
+    /**
+     * Value spans per requirement id, in the order the file writes them.
+     *
+     * Named `byId` rather than `entries` so nothing reads `layouts.entries` as
+     * the `Map` method of that name — the order this carries is the contract,
+     * and a reader who thinks they are calling `Map.prototype.entries` is a
+     * reader who has stopped seeing it.
+     */
+    byId: Map<string, RegistryEntryLayout>;
+    /** Ids left out of {@link RegistryLayouts.byId} because a key repeats. */
+    repeated: Map<string, RepeatedKey>;
+}
 /**
  * The layout of every entry in a registry file, by requirement id.
  *
@@ -154,6 +179,26 @@ export interface RegistryEntryLayout {
  * schema's `z.record(z.string(), …)` accepts the result. A `Map` keeps insertion
  * order for every key type, so the property holds by construction rather than by
  * the keys happening not to be numbers.
+ *
+ * **A key written twice defeats that pairing, which is why it is refused rather
+ * than described.** `Map.set` on a key it already holds keeps the *first*
+ * insertion's position and takes the *last* call's value — so an entry writing
+ * `params: { limit: 1, other: 'x', limit: 1 }` yields `limit` at position one
+ * carrying the span of the occurrence that sits after `other`, and the walk's
+ * offsets stop ascending — so an earlier edit moves the bytes under a later one
+ * and the replacement lands outside the value it was addressing.
+ *
+ * Nothing upstream refuses such a file, which is why the guard is here: a
+ * duplicate key is a TypeScript *semantic* error and `parseSource` asks only
+ * the syntactic question, so both readers take the file and hand back the last
+ * occurrence, and `--apply` is the one command that writes.
+ *
+ * Refused at every level for one reason, and the id level is not the mild one:
+ * two entries under a single id put a *later* entry's spans at an *earlier*
+ * entry's position, so the disorder is between entries rather than inside one.
+ * Nothing narrower is worth the reach — an entry whose keys are ambiguous is
+ * one no verdict describes, and the file is a defect to fix rather than one to
+ * edit around.
  */
-export declare function registryEntryLayouts(file: string, source: string): Map<string, RegistryEntryLayout> | undefined;
+export declare function registryEntryLayouts(file: string, source: string): RegistryLayouts | undefined;
 //# sourceMappingURL=static-registry.d.ts.map

package/dist/core/static-registry.js

@@ -295,11 +295,23 @@ function constInitializer(sf, name) {
  * The callee is matched against the local name the import bound — an alias or a
  * namespace import is the same call — rather than against any single-argument
  * call, so `buildRegistry({…})` is not mistaken for a registry.
+ *
+ * **Unwrapped here, once, rather than by each caller.** `as const`, `satisfies`
+ * and a bare pair of parentheses do not change the value, so `literalValue`
+ * strips them before it reads — while the write side asks
+ * `ts.isObjectLiteralExpression` of whatever this hands back. A wrapper returned
+ * from here is therefore a registry the readers accept and the writers cannot
+ * locate, on the one command that edits a `*.reqs.ts`. Both sides come through
+ * this function precisely so they cannot disagree about which literal is the
+ * registry; leaving the unwrap to each caller is what puts the disagreement
+ * inside it.
  */
 function authoringCall(expr, sf, fn) {
     if (!ts.isCallExpression(expr) || expr.arguments.length !== 1)
         return undefined;
-    return callsAuthoringFn(expr, localNames(sf, fn), fn) ? expr.arguments[0] : undefined;
+    if (!callsAuthoringFn(expr, localNames(sf, fn), fn))
+        return undefined;
+    return unwrap(expr.arguments[0]);
 }
 /**
  * Whether a call is a call of `fn`, by the local names the imports bound to it.
@@ -520,31 +532,66 @@ function objectInsertion(sf, source, obj) {
  * schema's `z.record(z.string(), …)` accepts the result. A `Map` keeps insertion
  * order for every key type, so the property holds by construction rather than by
  * the keys happening not to be numbers.
+ *
+ * **A key written twice defeats that pairing, which is why it is refused rather
+ * than described.** `Map.set` on a key it already holds keeps the *first*
+ * insertion's position and takes the *last* call's value — so an entry writing
+ * `params: { limit: 1, other: 'x', limit: 1 }` yields `limit` at position one
+ * carrying the span of the occurrence that sits after `other`, and the walk's
+ * offsets stop ascending — so an earlier edit moves the bytes under a later one
+ * and the replacement lands outside the value it was addressing.
+ *
+ * Nothing upstream refuses such a file, which is why the guard is here: a
+ * duplicate key is a TypeScript *semantic* error and `parseSource` asks only
+ * the syntactic question, so both readers take the file and hand back the last
+ * occurrence, and `--apply` is the one command that writes.
+ *
+ * Refused at every level for one reason, and the id level is not the mild one:
+ * two entries under a single id put a *later* entry's spans at an *earlier*
+ * entry's position, so the disorder is between entries rather than inside one.
+ * Nothing narrower is worth the reach — an entry whose keys are ambiguous is
+ * one no verdict describes, and the file is a defect to fix rather than one to
+ * edit around.
  */
 export function registryEntryLayouts(file, source) {
     const found = registryLiteral(file, source);
     if (!found)
         return undefined;
     const { sf, literal } = found;
-    const layouts = new Map();
+    const byId = new Map();
+    const repeated = new Map();
     for (const entry of literal.properties) {
         if (!ts.isPropertyAssignment(entry))
             continue;
         const id = staticName(entry.name);
         if (id === undefined || id === '__proto__')
             continue;
+        if (byId.has(id) || repeated.has(id)) {
+            // Deleted, not left as the first occurrence: both readers take the *last*
+            // one, so describing the first would hand the writer a span whose value
+            // nothing evaluates.
+            byId.delete(id);
+            repeated.set(id, {});
+            continue;
+        }
         const body = unwrap(entry.initializer);
         if (!ts.isObjectLiteralExpression(body))
             continue;
         const fields = new Map();
         const paramKeys = new Map();
         let params;
+        /** The first repeated key seen, as the path the refusal names. */
+        let twice;
         for (const field of body.properties) {
             if (!ts.isPropertyAssignment(field))
                 continue;
             const name = staticName(field.name);
             if (name === undefined || name === '__proto__')
                 continue;
+            if (fields.has(name)) {
+                twice ??= name;
+                continue;
+            }
             // The unwrapped value, so an `as const` or a parenthesis stays outside the
             // span and survives the replacement it wraps.
             const value = unwrap(field.initializer);
@@ -559,18 +606,26 @@ export function registryEntryLayouts(file, source) {
                 const key = staticName(param.name);
                 if (key === undefined || key === '__proto__')
                     continue;
+                if (paramKeys.has(key)) {
+                    twice ??= `params.${key}`;
+                    continue;
+                }
                 const value = unwrap(param.initializer);
                 paramKeys.set(key, { start: value.getStart(sf), end: value.getEnd() });
             }
         }
-        layouts.set(id, {
+        if (twice !== undefined) {
+            repeated.set(id, { field: twice });
+            continue;
+        }
+        byId.set(id, {
             fields,
             paramKeys,
             ...(params ? { paramsInsertion: objectInsertion(sf, source, params) } : {}),
             fieldInsertion: objectInsertion(sf, source, body),
         });
     }
-    return layouts;
+    return { byId, repeated };
 }
 /**
  * The `defineRequirements({ … })` literal of a registry file, with the source

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "TDD-native spec framework: tests are the source of truth for verification, ID-bound requirements the source of truth for intent.",
   "type": "module",
   "packageManager": "pnpm@10.28.0",