@am_shork/attest 0.7.3 → 0.7.4

package/CHANGELOG.md

@@ -13,6 +13,232 @@ 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.7.4] - 2026-08-08
+
+### Added
+
+- **`ATX-37`'s three unattested sites are closed, and the sweep that was going
+  to close them is rejected instead.** The requirement says *everything* the CLI
+  writes to a terminal replaces the control characters in text it quotes from
+  the project under test, and the `QUANTIFIED` table had carried four `null`
+  rows against it since `[0.7.0]`: the status rows, the coverage table, the
+  archive verdict, and the path `--out` echoes. Three of those are formatters
+  interpolating a reqId, a change name or a written path — correct by reading,
+  attested by nothing, which is the state a `sites` quantifier is the only kind
+  able to reach in silence. Three scenarios now drive them with hostile input,
+  covering six interpolations, and each was **proven able to go red by injection
+  before being believed**: `inline` removed from the status row's id, from the
+  merged path, from the archive verdict's change name, and from the coverage
+  row's id — four defects, each failing exactly one scenario and no other. The
+  fourth `null` stays: `--out` needs a filename holding a control character,
+  which NTFS refuses and Linux permits, and an unmeasured half is what a `null`
+  records.
+  **A fifth injection is why the archive verdict is asserted three times.**
+  Reading the diff caught what the site list does not resolve to: `change` is
+  interpolated by three separate expressions in that one function — merged,
+  archivable, and gate-failed — and the first draft covered two of them, leaving
+  `inline` deletable from the third with the whole suite green. A `sites` row
+  names sites at the granularity a sentence uses, and a branch is finer than
+  that; the injection is what tells the two apart.
+  **Re-measuring the proposal before building it is what split it in two**, and
+  the figures moved in both directions. `src/cli/report.ts` has 8 exports of
+  which **7** are `format*` — the eighth is `summarize`, so the entry's "eight
+  formatters" was already one off its own wording. The "eight fixtures, one per
+  signature" was worse: there are 7 distinct parameter types, `Issue[]` is
+  shared by three functions, and the honest cost of the fix turned out to be two
+  fixtures extending ones `self/report.spec.ts` already builds. And the entry
+  **undercounted its own benefit** — "three currently-correct sites" is three
+  *formatters* carrying six interpolations.
+
+- **The `✗` samples are bound to a fixture whose rejection the suite asserts.**
+  A page showing input the engine must *reject* was the one kind of sample
+  nothing could see going stale: it carries no version, names no `src/` symbol,
+  and keeps its page's structure perfectly, so every gate in
+  `tests/docs-consistency.spec.ts` passed while the claim underneath it aged.
+  The failure that mattered is asymmetric — a stale runnable sample stops
+  working when a reader pastes it, while a stale counterexample is a reader
+  taught a rule that is no longer a rule, which is worse than teaching nothing.
+  A `✗` annotated with a code the engine can emit is now bound to a fixture,
+  byte-equal the way `fixtures/consumer/` is bound to the README, and the
+  fixture is **run through the reader the documented command uses** — the code
+  and the line it produces are compared with the code and the line the page
+  shows. The line is the half that catches the shape a code-only assertion would
+  not: a fixture still rejected, for a different reason, having quietly stopped
+  demonstrating what it is quoted for.
+  **Re-measuring the entry before building it moved its cost by a factor.** It
+  was filed as the expensive half, "a fixture per diagnostic". Of the 33 fenced
+  `ts` blocks in the README and `docs/en/**`, 8 carry a `✗`, 3 name a code the
+  engine can emit, and 1 of those 3 is elided (`duplicate-prefix`, taught as two
+  one-line registries whose bodies are `{ /* … */ }`) — leaving one sample,
+  quoted on two pages, bound to one fixture. The count was never the reason it
+  sat: what it was really waiting for is the thing that makes the roster hold,
+  which is that the binding is a **sweep** rather than a list. A new `✗ code`
+  block on any English page is bound to a fixture or fails as `unbound`, so the
+  next diagnostic pays a fixture because it is obliged to, not because someone
+  remembered the roster existed.
+  **Proven able to go red before being believed**, since a gate over samples
+  that are all currently correct has never failed and cannot be trusted until it
+  does: four mutations, one per way the binding can rot — the page edited away
+  from the fixture, the fixture made static so the engine accepts it, a `✗`
+  sample added bound to nothing, and the defect moved to a line the annotation
+  does not mark. Each was reported naming the page or the fixture.
+  *Two limits, both structural.* **English only**: `docs/zh/**` matches
+  `docs/en/**` down to the comments inside its samples, so byte-equality is a
+  claim only one side can carry, and what covers the Chinese side is the parity
+  gate from `[0.4.3]` holding the code-sample sequences equal — structure, not
+  meaning. And an **elided block is excluded by rule**, not by omission from the
+  roster: `{ /* … */ }` is what makes that sample readable and also what makes it
+  unrunnable. The residual risk recorded in `[0.4.3]` does *not* apply here —
+  the byte gate and the run proving the fixture still fails are in the same
+  file, so a fixture that stopped being rejected cannot pass by living in a
+  suite nobody connected to the page.
+
+- **`ATX-15` is swept over `src/` from the AST, rather than attested one site at
+  a time.** The requirement quantifies over *sites* — every ordering committed to
+  disk or compared for equality — and `sites` is the one shape the quantifier
+  table records as able to stop being true in silence: a new site is a new
+  obligation and nothing enumerates them. Two of its five sites were `null`:
+  `red-record.ts` sorts ids and scenario names into `first-run.json`, and
+  `splice.ts` sorts ids and param keys into the registry file `--apply` writes.
+  Both are committed to disk, both were correct, and neither had a scenario. A
+  scenario per site would have closed those two and left the shape untouched,
+  because site six would have been unattested the day it was added. The sweep
+  instead makes the roster one the **code** owns — every `.sort`/`.toSorted` in
+  `src/` is a member — so a new ordering site is covered by construction. The
+  sanctioned comparator, the sort methods and the banned APIs are `ATX-15`
+  params, read by the scenario, pinned against literals for the reason the
+  domain table states: shrinking a list a scenario iterates removes a case and
+  everything left still passes.
+  **Stated narrowly enough to be true: it constrains how a site orders, not that
+  it orders.** A `red-record.ts` that stopped sorting altogether is still green
+  here, and the three hand-written scenarios are what speak to the result. That
+  is the honest limit of what a sweep can prove, and the table records it rather
+  than letting the row read as fully discharged.
+  **It was proven able to go red against the real corpus before being believed** —
+  three injected defects, one per shape the rule admits: a `localeCompare`
+  comparator in `red-record.ts`, a bare `.sort()` in `splice.ts`, and a
+  hand-rolled comparator in `merge.ts` that never reaches `byCodeUnit`. Each was
+  reported with its file, line and offending source. A gate asserting a property
+  that already holds everywhere has never been red and cannot become so until it
+  fires, so a negative control is not optional for it; a second scenario keeps
+  one in the suite permanently, including the case a line-wise scan gets wrong.
+  **Re-measuring the proposal's figures before building it changed two of
+  them**, which is the section's own rule and the reason it is worth restating:
+  the entry claimed 21 `.sort` call sites (there are **20** — the 21st was a
+  comment, which a regex counts and an AST does not), and two exceptions to
+  "names `byCodeUnit` on the call line" (there are **six**: one delegating to a
+  local `compareIds`, five inline arrows). The exception count being 3× what was
+  written is what made following local delegation part of the rule rather than a
+  footnote. The `localeCompare` figure moved the same way and in the direction
+  that matters most: **both occurrences in `src/` are comments explaining why it
+  is not used**, so a line-wise regex would have opened at 100% false positives.
+  Reading from the AST was the entry's own recommendation; it turns out to have
+  been the difference between a gate and a nuisance.
+  One shape the rule admits was not in the proposal and is worth naming:
+  `report.ts` sorts by `b.count - a.count || byCodeUnit(…)`. A numeric term is
+  legitimate, so the rule is "every comparator **reaches** the sanctioned one",
+  never "sorts only by code unit" — a stricter rule would have been red on
+  correct code the day it was written.
+
+### Fixed
+
+- **`attest check` answered `✓ No issues.` for a `*.reqs.ts` that does not
+  compile.** TypeScript's parser is error-tolerant by design: handed a file
+  truncated before its closing `});` it recovers the object literal and returns a
+  tree anyway, so the static reader read it as a *complete* registry and reported
+  nothing at all — while `--eval` on the same bytes said `registry-invalid`. Two
+  readers of one file disagreeing about whether it is even a file is the
+  condition the differential suite exists to prevent, and that suite could not
+  have caught it: it runs over registries that all compile. Nothing was looking
+  at `parseDiagnostics`, which is the one field that says so.
+  **The reach is three readers, not one**, because the tolerance belongs to the
+  compiler rather than to any reader: `parser.ts`, `static-registry.ts` and
+  `splice.ts` all open with the same `createSourceFile` call. The same half-saved
+  file was also a spec whose scenarios above the break still counted as coverage,
+  a delta whose ids `status` still reported, and — the site that writes rather
+  than reports — an insertion offset `attest apply` would have spliced a new
+  requirement into. All four now refuse it: the three readers as
+  `unreadable-file`, and the insertion point by returning the `undefined` it
+  already documents as its refusal to guess, because a write path that throws
+  mid-merge is worse than one that declines.
+  The diagnostic carries the **line** the syntax error is on, through both
+  shapes of refusal — the readers return it, and the spec parser carries it
+  through the throw its guard already catches. Without that second half the same
+  code would have had a line for a registry and none for a spec, for one
+  condition.
+  `unreadable-file` rather than a new code: `ATX-65` already states this
+  obligation for a file the parser cannot read, and the reader's situation is
+  identical — nothing in the file was checked, everything else in the run still
+  was. What `ATX-65` did not state is the *detection*, which is the whole of what
+  was missing; it was written for a parser that throws, and a parser that quietly
+  succeeds needs a different question asked of it.
+  **Syntactic only, and that is what makes it safe rather than merely narrow.**
+  `parseDiagnostics` is the parser's own list, so a type error, an unresolved
+  import and a name that does not exist are all absent from it — Attest does not
+  typecheck an adopter's project and this does not start. Measured over the 129
+  TypeScript files in this repository with every fixture included: zero carry a
+  parse diagnostic, so nothing valid today starts failing. The one reader left
+  deliberately tolerant is the id recovery added above, which runs only on files
+  a reader has already refused.
+
+- **Two scenarios named by a template literal were invisible to the static
+  plan.** `self/half-loaded.spec.ts` generated one scenario per command, and the
+  parser reads names from the AST — so `cover` counted one scenario where two
+  ran, and `archive`'s never-red gate could never have seen the second. Found
+  while binding the new requirement's roster to a scenario the plan declares.
+  Both are now one scenario looping the roster, which is the shape `ATX-64`
+  already used; the label on each `expect` is what the generated name was buying,
+  and it survives a failure. **The engine is not changed**: a name a static
+  reader cannot resolve is not a defect in the reader, and the failure it
+  produces on a requirement covered *only* that way is `uncovered-requirement`,
+  which is loud.
+
+### Changed
+
+- **One unreadable `*.reqs.ts` reported a finding per scenario that attested it,
+  and the finding was about the file.** The ids that file declares are missing
+  from the run, so every scenario covering one of them was an `orphan-test` —
+  measured on a registry of three requirements: six ERRORs, of which one was the
+  cause and five were its shadow, with the true finding at the top where the wall
+  of red pushes it out of view. Those scenarios are now reported once per
+  registry file as `orphan-from-failed-registry` (WARNING), naming the file, the
+  count and the ids; the same case is now two ERRORs and one WARNING. A WARNING
+  because the load failure is already an ERROR and is present whenever this is,
+  so no verdict moves and this cannot make a broken registry pass.
+  **What unblocked it was that the question was framed wrongly**, and the entry
+  under `Under consideration` had carried that framing for two releases: it asked
+  for a prefix→file mapping, which is exactly what a file that never parsed
+  cannot give — and could only have been recovered from the file *name*, which
+  this repository is its own counterexample to (`attest.reqs.ts` holds `ATX-*`,
+  the evidence that killed the prefix-matches-filename rule). The **ids** are
+  written in the source, and reading them back needs no naming convention that
+  nothing enforces. It is also strictly more precise than the prefix would have
+  been: a genuine typo sharing a prefix with the broken file stays reported.
+  Recall is partial and the direction of the miss is why that is acceptable — an
+  id not recovered keeps its `orphan-test`, so the report stays noisy and never
+  wrong. Measured over the ways a registry fails: a truncated file, a missing
+  default export, a non-literal value, a schema-invalid entry, a module that
+  throws at import and a spread from another module all yield their ids; only a
+  registry the file *computes* yields none, and that source contains no id to
+  find. The recovery is a source read that returns ids and nothing else — it
+  builds no registry, so it is not a second reader and cannot become the
+  evaluation fallback `registry-not-static` refuses.
+  Stated as a replacement rather than a suppression for the reason `ATX-62`
+  records about `spec-load-failed`: suppressing with nothing in its place trades
+  a wrong message for silence, and a wrong message beats silence.
+
+- **The hedged `orphan-test` advice added in `[0.7.0]` was applied to every
+  orphan in the report, including the ones it does not describe.** Any registry
+  file failing to load switched *all* of them to "a registry file failed to load
+  — fix that first, and add this id only if it is still unknown afterwards",
+  so a genuine typo was told to wait for work that has nothing to do with it.
+  The hedge now fires only where the uncertainty is real: when a failed file's
+  ids could not be recovered. When they all could, an orphan none of them claims
+  is genuinely unknown and gets the plain advice back.
+
+`SCHEMA_VERSION` is unchanged: a new `code` value is additive, and no envelope
+field moved.
+
 ## [0.7.3] - 2026-08-07
 
 ### Fixed
@@ -3647,34 +3873,17 @@ about itself, which is three things.
 **An entry can sit here for releases on the strength of a figure nobody has
 checked.** The discipline aims at keeping the *argument*, not at re-testing the
 evidence under it, so the first act of building one is re-measuring what it
-claims rather than implementing what it proposes. That has paid twice: once
-killing an entry outright, when the spans it rested on turned out not to be
-spans; once correcting an entry's headline number before a line of it was
-written. **What a release costs its adopters is not known on the day it is cut**
+claims rather than implementing what it proposes. That has paid three times:
+once killing an entry outright, when the spans it rested on turned out not to be
+spans; twice correcting an entry's own numbers before a line of it was written —
+a call-site count that a regex had inflated, and a cost filed as "a fixture per
+diagnostic" that the corpus put at one fixture. **What a release costs its adopters is not known on the day it is cut**
 — several entries arrived from one adoption report, about shapes the tool made
 someone work around without ever erroring. And **the fixes with no observable
 symptom are worth batching**: individually none justifies a commit, together they
 cost about an hour, and they are the group no gate could have found, since having
 no symptom is the definition of what a gate cannot see.
 
-- **Binding the `✗` samples to fixtures whose rejection is asserted.** A sample
-  showing input the engine must *reject* can be bound the way a runnable one is,
-  to a fixture whose rejection is the thing under test — which is what
-  `fixtures/eval-invalid-registry` already is. This is the more valuable half of
-  what was once one entry with the region-marking below, because a counterexample
-  that quietly stopped being a counterexample is the one kind of stale sample
-  that actively teaches the wrong thing: a reader shown "this fails" about input
-  the engine now accepts is worse off than one shown nothing. It is also the
-  expensive half, needing a fixture per diagnostic, which is why it was never the
-  free part of that entry and is now the only part left in it.
-  *The mirror rule caps what can be claimed on the Chinese side.* `docs/zh/**`
-  matches `docs/en/**` down to the comments inside its code samples, so
-  byte-equality holds on one side only and the zh blocks stay translated prose
-  around the same code — the parity gate in `[0.4.3]` covers them, and it covers
-  structure, not meaning. The residual risk recorded with the whole-file half in
-  `[0.4.3]` — that the gate and the run proving the fixture still works live in
-  different suites — applies here identically.
-
 ## Under consideration
 
 Candidates with **no decision yet**, between the two sections either side of it
@@ -3706,41 +3915,6 @@ have to gather again.
   npm's current trusted-publisher documentation for GitLab support before
   writing any YAML.
 
-- **A static sweep for the two properties claimed over the whole of `src/`.**
-  The quantifier table's first strict read left three rows wanting the same
-  thing, and the repo already owns the idiom: `tests/import-boundary.spec.ts` is
-  a sweep over the import graph asserting a cross-cutting property no runtime
-  test can see, written for the same reason — "only the graph shows it".
-  *The two candidates, and they are not equally shippable.* `ATX-15` is the easy
-  one: **no `.sort` outside `byCodeUnit`, and no `localeCompare`.** Measured over
-  `src/` today — 21 `.sort` call sites, every one reaching `byCodeUnit`, but only
-  19 naming it on the call line: `render.ts` goes through its own `compareIds`,
-  and `merge.ts` through a comparator that spans two lines. The only four
-  occurrences of `localeCompare` are comments explaining why it is not used. A sweep would have **zero false positives on the current corpus**,
-  which is the bar `divergent-param` failed and `compound-requirement` cleared —
-  and those two exceptions are already the warning that this needs the AST rather
-  than a line-wise regex, plus a rule for a comparator that delegates. `ATX-37` is the hard one: what it needs is "every project-derived
-  string interpolated into a terminal line goes through `inline`", and that is
-  not a token scan. The shape that would work is a scenario driving every
-  exported `format*` in `src/cli/report.ts` with hostile input — a real roster,
-  since the module's exports are what a new formatter joins — but each takes a
-  different argument type, so it needs a hostile fixture per signature rather
-  than one loop.
-  *What blocks the decision.* Two things, one per candidate. The `ATX-15` sweep
-  is cheap and precise and would be **the first rule in this repository that
-  polices how `src/` is written rather than what it does** — a lint rule wearing
-  a scenario's clothes, and the question is whether that belongs in `self/` (as
-  an obligation `ATX-15` already carries) or in `tests/` beside the import
-  boundary. Filing it under `ATX-15` makes it a permanent obligation with a
-  scenario; filing it in `tests/` makes it deletable in a green diff, which
-  `ATX-57`'s rationale argues against in as many words. The `ATX-37` roster is
-  blocked on cost rather than principle: eight formatters, eight fixtures, and
-  the honest count of what it buys is three currently-correct sites.
-  *Why neither is urgent.* Both properties hold everywhere today, verified by
-  reading. What is missing is not correctness but the thing that keeps it — and
-  the measurement above is what a re-proposal would otherwise have to gather
-  again.
-
 - **Bounding the fan-out in `findFiles` and `parseSpecs`.** Both walk the
   project with no concurrency limit: `findFiles` recurses through
   `Promise.all(subdirs.map(walk))`, so every directory in the tree is opened at
@@ -3976,17 +4150,34 @@ have to gather again.
   weaker signal "some registry file failed to load, so suppress all
   `orphan-test`" is the other candidate and is a strictly worse `check` on a
   multi-file registry, where the other files are fine and their orphans are real.
-  **The wrong *advice* has been separated out and fixed; the noise has not.**
-  `[0.7.0]` changes `orphan-test`'s fix hint when any registry file failed
-  to load, so the loudest line in that report stops telling the reader to add an
-  id that already exists. That needed no mapping, because it claims nothing about
-  *which* orphans came from the broken file — only that the command cannot tell,
-  and what order to work in. It is worth separating because the two halves were
-  filed as one problem and are not: **being wrong** was fixable today at the cost
-  of a sentence, and **being loud** is the part still blocked on the mapping
-  above. The entry stays open on exactly that, with one blocker retired: the
-  measured six derived findings from one cause are still six, and only one of
-  them has stopped pointing at work that must not be done.
+  **The wrong *advice* was separated out and fixed in `[0.7.0]`; the noise is
+  fixed under `[Unreleased]`, and the blocker above was the wrong question.**
+  The mapping this entry called for could not be recovered, and did not have to
+  be: what a suppression needs is not the broken file's *prefix* but the ids it
+  declares, and those are written in its source. Reading them back is a source
+  read that returns ids and builds nothing, so the failure modes that matter —
+  a truncated file, a missing default export, a non-literal value, a
+  schema-invalid entry, a module that throws at import — all give them up. The
+  six derived findings from one cause are now two ERRORs and one WARNING, and
+  the collapse is per id rather than per prefix, which is strictly more precise
+  than what was blocked: a genuine typo sharing a prefix with the broken file
+  stays reported. **The lesson is the entry, not the fix.** It sat here for two
+  releases behind a blocker stated as "the mapping is unavailable", which was
+  true and was about a mapping nothing needed; the evidence it carried was about
+  the right problem and the mechanism it proposed was not, and nothing rereads a
+  blocker that has already been written down. That is the same failure the
+  section's own preamble records about a figure nobody re-checks, one level up:
+  the *shape* of the proposal goes stale as quietly as its numbers do.
+  *What is left of this entry is only the original question* — whether `check`
+  and `verify` should refuse a half-loaded registry outright, the way `cover`
+  and `render` do — **and the evidence that motivated it has been spent.** The
+  argument for refusing was never the load failure itself; it was the wall of
+  derived findings burying it, and that wall is gone. What remains is the
+  breadth argument recorded above, which points the other way for both commands.
+  It stays here rather than moving down because "the reason to do it was
+  removed" is not the same as "it was decided against", and the case would come
+  back the moment another finding is found to scale with a broken registry
+  rather than with the number of problems.
 
 - **A statement that quantifies over a surface, with scenarios covering only the
   part that existed when it was written.** Found by reading, and it had already
@@ -4035,7 +4226,7 @@ have to gather again.
   agreed to maintain it.
 
 - **Whether a requirement can ever be retired, and what it costs that none can.**
-  The registry is at 62 requirements and 160 scenarios, roughly 2.6 each, and
+  The registry is at **69 requirements and 192 scenarios, 2.78 each**, and
   every one is a permanent obligation: `uncovered-requirement` is an ERROR, so a
   requirement without a scenario cannot exist, and nothing ever removes one.
   `delta.removed` exists and `applyDelta` applies it, but `--apply` refuses to
@@ -4057,10 +4248,29 @@ have to gather again.
   requirement, where the scenario should move rather than go. Only the second is
   really about cost, and it is the one where deleting the intent to save the
   scenario inverts what the whole tool claims — that intent outlives its tests.
-  Nothing here is urgent while the number is 61. It is filed now because the
-  moment to write the argument down is while the reasoning is available, and
-  because a project whose requirement count only rises should have decided in
-  advance what would make one leave.
+  Nothing here is urgent at 69. It is filed now because the moment to write the
+  argument down is while the reasoning is available, and because a project whose
+  requirement count only rises should have decided in advance what would make
+  one leave.
+  *The figures above were restated on 2026-08-08, and how they were wrong is
+  itself the section's own warning happening.* As filed on 2026-08-03 this entry
+  said "62 requirements and 160 scenarios, roughly 2.6 each" while closing on
+  "the number is 61" — an inconsistency inside one entry, and the closing half
+  was the right one. Re-measured at the entry's own commit with the current
+  parser: **61 requirements, 156 scenarios**, so both opening figures were wrong
+  on the day they were written, and only the ratio survived. Measured the same
+  way today it is 69 and 192, and the method is the same one `verify self`
+  prints — the control is that today's `self/` counted this way returns exactly
+  what the runner does, which is what makes the 2026-08-03 number trustworthy. The
+  cheap way — `grep -c 'scenario('` — answers 211 against today's true 192, and
+  is what would have been reached for: comments and prose count, which is the
+  `ATX-15` error again.
+  **What moved in five days sharpens the argument rather than dating it.** +8
+  requirements and +36 scenarios, concentrated in three sessions rather than
+  accrued at a rate, so nothing here is a trend line. The part worth keeping is
+  the ratio: 2.56 → 2.78. The cost of a requirement is not flat and it is not
+  falling, which is the premise the whole entry rests on, and it is the first
+  time this file has had two measurements of it to compare.
 
 ## Considered and rejected
 
@@ -4302,6 +4512,46 @@ skill file. A pointer is cheap enough to be resident, it is their edit in their
 file, and it cannot go stale — the file it names is the one `init` keeps
 current.
 
+### A sweep driving every exported `format*` with hostile input
+
+The mechanism `ATX-37` sat under `Under consideration` waiting for, kept there
+on cost, and killed by measuring that cost rather than by paying it. The three
+sites it was aimed at are closed under `[Unreleased]` by hand-written scenarios;
+what is rejected is the roster, and the argument is that **`src/cli/report.ts`'s
+exports are the wrong roster in both directions at once.**
+
+*Too wide.* Three of the eight exports cannot carry project-derived text at all:
+`summarize` and `formatScope` take `VerifyCounts`, which is four numbers, and
+`formatRepeats` prints a count, a `Level` and an `IssueCode` — both fixed
+rosters. A hostile fixture for those has nothing hostile to put in it, so a loop
+over the exports either forces three members that **cannot go red**, which is
+the defect this project ships a gate against, or carries an exclusion list —
+and an exclusion list is precisely what `ATX-15`'s sweep avoided by making the
+roster one the code owns.
+
+*Too narrow.* The statement is over everything the CLI writes to a terminal, and
+every site that has escaped it so far was outside this module: the `status`
+header was built and printed in `cli/index.ts`, the loader's writes are in
+`core/loader.ts`, and the `render` document that `ATX-58` was carved out for is
+in `core/render.ts`. A roster of formatters is neither necessary nor sufficient
+for the sentence, and the reading that made it look sufficient — that the
+formatters are the whole surface — is the exact assumption the `status` header
+falsified when it was found.
+
+*And the general form is the §0 wall.* "Every project-derived string
+interpolated into a terminal line goes through `inline`" needs to know which
+values are project-derived, which is prose judgement over a data flow. That is
+the ground truth `tests/intent-rule-candidates.spec.ts` records as the reason
+none of this can ever be an engine rule, and it does not become computable by
+being asked about this repository instead of someone else's.
+
+*What keeps the property instead* is the `QUANTIFIED` row itself — hand-judged,
+one entry per site, every named scenario asserted to exist. That is a
+counter-pressure rather than a detector, it holds for one registry whose authors
+agreed to maintain it, and after this change exactly one of its `ATX-37` sites
+is open. This reopens only if a site escapes that a roster of formatters would
+have caught, which none of the four so far would have been.
+
 ### A Codex target for `attest init`
 
 Evaluated when `init` grew `--target` and shipped for Claude Code, Cursor and
@@ -4386,6 +4636,7 @@ requirement, and human review at propose is still the whole answer. What is
 rejected is grouping as a way to assist it, and this reopens only on a
 contradiction that grouping would have caught.
 
+[0.7.4]: https://gitlab.com/Pseudorca/attest/-/tags/v0.7.4
 [0.7.3]: https://gitlab.com/Pseudorca/attest/-/tags/v0.7.3
 [0.7.2]: https://gitlab.com/Pseudorca/attest/-/tags/v0.7.2
 [0.7.1]: https://gitlab.com/Pseudorca/attest/-/tags/v0.7.1

package/README.md

@@ -166,7 +166,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.7.3/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.7.4/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section

package/dist/core/compiler.d.ts

@@ -1,3 +1,4 @@
+import ts from 'typescript';
 import type { Issue } from './types.js';
 /**
  * The range the readers are written against.
@@ -36,5 +37,36 @@ interface CompilerSurface {
  * requirement and every file in the project is equally unreadable because of it.
  */
 export declare function compilerIssue(compiler?: CompilerSurface): Issue | undefined;
+/**
+ * A source that does not compile, thrown where a reader has no failure channel
+ * of its own.
+ *
+ * `parseSpecFile` returns a plan and nothing else, so its refusal has to be a
+ * throw — and `parseSpecs` already catches every throw per file (ATX-65). The
+ * class exists so the *line* survives that trip: without it the position is
+ * prose inside the message, and `unreadable-file` would carry `line` when a
+ * registry failed to compile and not when a spec did, for one condition.
+ */
+export declare class SourceNotCompiled extends Error {
+    readonly line?: number | undefined;
+    constructor(message: string, line?: number | undefined);
+}
+/**
+ * `ts.createSourceFile`, refusing a source that does not compile.
+ *
+ * Every reader that turns source into a *value* goes through this. The one that
+ * deliberately does not is `declaredIdsFromSource`, which runs only on files a
+ * reader has already refused — recovering the ids of a broken registry is the
+ * whole of its job, and a strict parse there would take the diagnostic that
+ * names them away again.
+ */
+export declare function parseSource(file: string, source: string): {
+    sf: ts.SourceFile;
+} | {
+    error: {
+        message: string;
+        line?: number;
+    };
+};
 export {};
 //# sourceMappingURL=compiler.d.ts.map

package/dist/core/compiler.js

@@ -61,4 +61,82 @@ export function compilerIssue(compiler = ts) {
             `If a resolution or override pins the compiler for the whole tree, exclude Attest from it or move that pin back into the supported range.`,
     };
 }
+/**
+ * The syntax error a source carries, or `undefined` when it compiles.
+ *
+ * **`ts.createSourceFile` recovers**: handed a file that does not compile it
+ * still returns a tree, built from what the parser guessed the author meant. So
+ * a tree is not evidence that a file compiles, and every reader that turns
+ * source into a value has to ask separately (ATX-69).
+ *
+ * Lives here because this module already owns what the compiler does and does
+ * not promise — it names `parser.ts`, `static-registry.ts` and `splice.ts` as
+ * the three that open with `createSourceFile`, which is exactly the set that has
+ * to ask this question.
+ *
+ * **Syntactic only, and that is the whole of what keeps it safe.**
+ * `parseDiagnostics` is populated by the parser, so a type error, an unresolved
+ * import and a name that does not exist are all *absent* from it — checking it
+ * cannot turn Attest into a typechecker of someone's project, which it is not
+ * and must not become.
+ *
+ * What "does not compile" means is "does not compile under the TypeScript Attest
+ * resolved", which is the same limit ATX-65 records about parser depth: the
+ * bound belongs to the compiler this is built on, not to a promise this project
+ * is in a position to make.
+ */
+function syntaxError(sf) {
+    // `parseDiagnostics` is not on the public `SourceFile` type — it is
+    // TypeScript's own field, which is why nothing here found it by reading the
+    // signature. Declared *optional* so reaching for it stays honest: a compiler
+    // that stops populating it degrades to reading the recovered tree rather than
+    // throwing, which is the same fail-open `compilerIssue` above is written for.
+    const diagnostics = sf.parseDiagnostics;
+    const first = diagnostics?.[0];
+    if (!first)
+        return undefined;
+    // The first error only. A syntax error cascades — a stray token measured four
+    // of them, where the truncation this was found on measured one — and the ones
+    // after the first are artefacts of the parser's recovery from it, so listing
+    // them describes the recovery rather than the file.
+    const message = ts.flattenDiagnosticMessageText(first.messageText, ' ');
+    const count = diagnostics.length;
+    const suffix = count > 1 ? ` (and ${count - 1} more)` : '';
+    return {
+        message: `${message}${suffix}`,
+        line: sf.getLineAndCharacterOfPosition(first.start).line + 1,
+    };
+}
+/**
+ * A source that does not compile, thrown where a reader has no failure channel
+ * of its own.
+ *
+ * `parseSpecFile` returns a plan and nothing else, so its refusal has to be a
+ * throw — and `parseSpecs` already catches every throw per file (ATX-65). The
+ * class exists so the *line* survives that trip: without it the position is
+ * prose inside the message, and `unreadable-file` would carry `line` when a
+ * registry failed to compile and not when a spec did, for one condition.
+ */
+export class SourceNotCompiled extends Error {
+    line;
+    constructor(message, line) {
+        super(message);
+        this.line = line;
+        this.name = 'SourceNotCompiled';
+    }
+}
+/**
+ * `ts.createSourceFile`, refusing a source that does not compile.
+ *
+ * Every reader that turns source into a *value* goes through this. The one that
+ * deliberately does not is `declaredIdsFromSource`, which runs only on files a
+ * reader has already refused — recovering the ids of a broken registry is the
+ * whole of its job, and a strict parse there would take the diagnostic that
+ * names them away again.
+ */
+export function parseSource(file, source) {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, /* setParentNodes */ true);
+    const error = syntaxError(sf);
+    return error ? { error } : { sf };
+}
 //# sourceMappingURL=compiler.js.map

package/dist/core/docs.d.ts

@@ -8,7 +8,7 @@
  * and the `##` headings of both language documents, so landing here cannot
  * produce a dead link.
  */
-export declare const ISSUE_CODES: readonly ["add-conflict", "add-invalid", "added-id-unmerged", "apply-no-prefix-owner", "apply-unsupported-delta", "change-not-found", "compiler-unsupported", "declared-not-run", "duplicate-prefix", "duplicate-requirement", "empty-spec", "internal-error", "invalid-change-name", "missing-spec-doc", "modify-invalid", "modify-missing", "never-red", "non-scalar-interpolation", "orphan-test", "possible-drift", "proposed-spec-name-taken", "proposed-spec-unclaimed", "rationale-placeholder", "registry-invalid", "registry-no-default", "registry-not-static", "rename-source-missing", "rename-target-exists", "rename-target-invalid", "spec-in-change-dir", "spec-load-failed", "stale-spec-doc", "tests-red", "unbound-param", "uncovered-requirement", "unknown-target", "unreadable-file", "unsafe-target-path"];
+export declare const ISSUE_CODES: readonly ["add-conflict", "add-invalid", "added-id-unmerged", "apply-no-prefix-owner", "apply-unsupported-delta", "change-not-found", "compiler-unsupported", "declared-not-run", "duplicate-prefix", "duplicate-requirement", "empty-spec", "internal-error", "invalid-change-name", "missing-spec-doc", "modify-invalid", "modify-missing", "never-red", "non-scalar-interpolation", "orphan-from-failed-registry", "orphan-test", "possible-drift", "proposed-spec-name-taken", "proposed-spec-unclaimed", "rationale-placeholder", "registry-invalid", "registry-no-default", "registry-not-static", "rename-source-missing", "rename-target-exists", "rename-target-invalid", "spec-in-change-dir", "spec-load-failed", "stale-spec-doc", "tests-red", "unbound-param", "uncovered-requirement", "unknown-target", "unreadable-file", "unsafe-target-path"];
 export type IssueCode = (typeof ISSUE_CODES)[number];
 /**
  * The page explaining `code`, or `undefined` when nothing explains it.

package/dist/core/docs.js

@@ -37,6 +37,7 @@ export const ISSUE_CODES = [
     'modify-missing',
     'never-red',
     'non-scalar-interpolation',
+    'orphan-from-failed-registry',
     'orphan-test',
     'possible-drift',
     'proposed-spec-name-taken',

package/dist/core/locate.d.ts

@@ -91,6 +91,20 @@ export declare function evalReader(loader: Loader): RegistryReader;
  * execute user code — and were advertised as static while doing exactly that.
  */
 export declare function staticReader(): RegistryReader;
+/**
+ * A registry file that contributed no ids, and the ids its source still names.
+ *
+ * `ids` is empty when nothing could be recovered — a registry the file computes
+ * rather than writes out, or a source that could not be read at all — and an
+ * empty list is the honest answer, not a failure: it says the ids of that file
+ * are unknown, which is a different thing from that file declaring none.
+ */
+export interface UnreadableRegistry {
+    /** Path relative to the project root, as every `Issue.file` is. */
+    readonly file: string;
+    /** Requirement ids recovered from the source; possibly none. */
+    readonly ids: readonly string[];
+}
 /**
  * Read and merge every `*.reqs.ts` registry under root, with the given reader.
  * A registry the reader rejects becomes its own ERROR; a duplicate id across
@@ -110,7 +124,8 @@ export declare function loadRegistry(root: string, reader: RegistryReader, files
     issues: Issue[];
     prefixOwners: Record<string, string>;
     /**
-     * Registry files that contributed **no ids**, relative to `root`.
+     * Registry files that contributed **no ids**, relative to `root`, each with
+     * whatever ids its source still says it declares.
      *
      * Not the same question as "did loading produce an ERROR": `duplicate-prefix`
      * and `duplicate-requirement` are ERRORs raised *after* a successful read, and
@@ -119,8 +134,13 @@ export declare function loadRegistry(root: string, reader: RegistryReader, files
      * re-derived that from the issue codes would be maintaining a second answer
      * to a question this loop already knows — the mistake `prefixOwners` is here
      * to avoid one shape of.
+     *
+     * The ids come with the file for the same reason: `validateStructure` has to
+     * separate a scenario attesting a *broken* file's requirement from one
+     * attesting an id that does not exist, and re-deriving which file an id
+     * belongs to somewhere else would be that same second answer.
      */
-    unreadableFiles: string[];
+    unreadable: UnreadableRegistry[];
 }>;
 /**
  * The part of an id that names the space it lives in — `AUTH` of `AUTH-3`.

package/dist/core/locate.js

@@ -4,10 +4,11 @@ import { readdir, readFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { relativePath } from './paths.js';
 import { parseSpecFile } from './parser.js';
-import { readRegistrySource } from './static-registry.js';
+import { declaredIdsFromSource, readRegistrySource } from './static-registry.js';
 import { RegistryValidationError } from './registry.js';
 import { RegistrySchema } from './schema.js';
 import { byCodeUnit } from './order.js';
+import { SourceNotCompiled } from './compiler.js';
 // Proposed changes and archived changes are excluded from normal scanning:
 // a change's requirements/specs only count once its gate passes and it is
 // merged (design §7, §8). `attest archive <name>` includes them explicitly.
@@ -107,11 +108,17 @@ function unreadableIssue(err) {
     // the run, and narrowing would make that promise true only of the one trigger
     // that has been measured.
     const detail = err instanceof Error ? err.message : String(err);
+    // The one throw that carries a position: a source that does not compile knows
+    // which line stopped it, and a syntax error without a line is most of the
+    // diagnostic gone. Narrowing to enrich, never to decide — everything still
+    // arrives here and still becomes this issue, which is the promise above.
+    const line = err instanceof SourceNotCompiled ? err.line : undefined;
     return {
         level: 'ERROR',
         code: 'unreadable-file',
         message: `Could not be read, so nothing in it was checked: ${detail}. ` +
             `Everything else in this run was still reported.`,
+        ...(line === undefined ? {} : { line }),
     };
 }
 /**
@@ -226,6 +233,18 @@ export function staticReader() {
         },
     };
 }
+/** Ids recoverable from a registry file that would not load; none if it will not even open. */
+async function declaredIds(absPath) {
+    try {
+        return declaredIdsFromSource(basename(absPath), await readFile(absPath, 'utf8'));
+    }
+    catch {
+        // The file that failed to load is already reported. A second failure
+        // reading it changes nothing about that diagnosis and must not replace it
+        // with a crash — this path only ever *adds* precision to another finding.
+        return [];
+    }
+}
 /**
  * Read and merge every `*.reqs.ts` registry under root, with the given reader.
  * A registry the reader rejects becomes its own ERROR; a duplicate id across
@@ -247,7 +266,7 @@ export async function loadRegistry(root, reader, files) {
     const loaded = await Promise.all(paths.map(async (file) => ({ file, outcome: await readGuarded(reader, file) })));
     const registry = {};
     const issues = [];
-    const unreadableFiles = [];
+    const unreadable = [];
     // Which file first claimed each id prefix. The prefix is the only unit above
     // the requirement (design §11) and nothing allocates it, so two files
     // claiming one is the collision no command would otherwise report — the ids
@@ -263,7 +282,13 @@ export async function loadRegistry(root, reader, files) {
         const { outcome } = entry;
         if ('issue' in outcome) {
             issues.push({ ...outcome.issue, file: display });
-            unreadableFiles.push(display);
+            // Read the source again for the ids alone. Both readers land here, and the
+            // evaluating one has not read the text at all — a file that threw on
+            // import produced an exception and no bytes. One extra read of a file that
+            // is already an ERROR is not a cost worth arranging around, and sharing
+            // the reader's source instead would mean the two readers passing different
+            // things to one diagnostic.
+            unreadable.push({ file: display, ids: await declaredIds(entry.file) });
             continue;
         }
         // One issue per colliding prefix rather than per requirement: the fact is
@@ -301,7 +326,7 @@ export async function loadRegistry(root, reader, files) {
             }
         }
     }
-    return { registry, issues, prefixOwners: Object.fromEntries(prefixOwner), unreadableFiles };
+    return { registry, issues, prefixOwners: Object.fromEntries(prefixOwner), unreadable };
 }
 /**
  * The part of an id that names the space it lives in — `AUTH` of `AUTH-3`.

package/dist/core/parser.d.ts

@@ -1,3 +1,15 @@
 import type { AttestPlan } from './types.js';
+/**
+ * Throws when `source` does not compile, rather than returning a plan built out
+ * of what the parser recovered from it — a spec truncated mid-file was handing
+ * back the scenarios above the break, so the file counted as coverage while not
+ * compiling. `parseSpecs` turns the throw into the per-file `unreadable-file`
+ * its guard already produces (ATX-65), which is why this can throw at all: the
+ * loop that owns "one file's failure is not the run's failure" is already there.
+ *
+ * A throw rather than a result type, unlike the registry readers, because this
+ * returns a plan and has no failure channel of its own; adding one would change
+ * every caller to say what the guard above them already says.
+ */
 export declare function parseSpecFile(file: string, source: string): AttestPlan;
 //# sourceMappingURL=parser.d.ts.map

package/dist/core/parser.js

@@ -3,9 +3,25 @@
 // requirement()/scenario() calls with literal ids, and grabs the line number
 // at parse time — OpenSpec's "parse into strong types, capture the line now".
 import ts from 'typescript';
+import { parseSource, SourceNotCompiled } from './compiler.js';
+/**
+ * Throws when `source` does not compile, rather than returning a plan built out
+ * of what the parser recovered from it — a spec truncated mid-file was handing
+ * back the scenarios above the break, so the file counted as coverage while not
+ * compiling. `parseSpecs` turns the throw into the per-file `unreadable-file`
+ * its guard already produces (ATX-65), which is why this can throw at all: the
+ * loop that owns "one file's failure is not the run's failure" is already there.
+ *
+ * A throw rather than a result type, unlike the registry readers, because this
+ * returns a plan and has no failure channel of its own; adding one would change
+ * every caller to say what the guard above them already says.
+ */
 export function parseSpecFile(file, source) {
-    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, 
-    /* setParentNodes */ true);
+    const parsed = parseSource(file, source);
+    if ('error' in parsed) {
+        throw new SourceNotCompiled(`this file does not compile (${parsed.error.message})`, parsed.error.line);
+    }
+    const sf = parsed.sf;
     const scenarios = [];
     const paramRefs = [];
     const seenRefs = new Set(); // dedupe: one ref per (reqId, scenario)

package/dist/core/pipeline.js

@@ -108,7 +108,7 @@ export async function runCheck(root, options = {}) {
     // command that reads both the registry and every change's delta, so it is the
     // only one where that distinction is worth anything.
     return withLoader(options, async (loader) => {
-        const { registry, issues, unreadableFiles } = await readRegistry(root, options, scan.reqsFiles, loader);
+        const { registry, issues, unreadable } = await readRegistry(root, options, scan.reqsFiles, loader);
         const { plan, issues: unreadableSpecs } = await parseSpecs(scan.specFiles, root);
         return [
             ...issues,
@@ -121,7 +121,7 @@ export async function runCheck(root, options = {}) {
             // that *did* load are all still true. What it must not do is advise work
             // that the load failure makes wrong — see `orphan-test` in
             // `validateStructure`.
-            ...validateStructure(registry, plan, unreadableFiles.length > 0),
+            ...validateStructure(registry, plan, unreadable),
             ...detectPotentialDrift(registry, plan, plan.paramRefs),
             ...(await unclaimedProposedSpecIssues(root, scan, options, loader)),
             ...(await changeDirSpecIssues(root)),
@@ -291,13 +291,13 @@ export async function runVerify(root, options = {}) {
     const loader = await createLoader();
     let registry;
     let plan;
-    let unreadableFiles;
+    let unreadable;
     const issues = [];
     try {
         const loaded = await loadRegistry(root, evalReader(loader), scan.reqsFiles);
         registry = loaded.registry;
         issues.push(...loaded.issues);
-        unreadableFiles = loaded.unreadableFiles;
+        unreadable = loaded.unreadable;
         const parsedSpecs = await parseSpecs(scan.specFiles, root);
         plan = parsedSpecs.plan;
         issues.push(...parsedSpecs.issues);
@@ -307,7 +307,7 @@ export async function runVerify(root, options = {}) {
     }
     // Same as `check`: everything the loaded half supports is still reported, and
     // only the advice that a load failure would make wrong is withdrawn.
-    issues.push(...validateStructure(registry, plan, unreadableFiles.length > 0));
+    issues.push(...validateStructure(registry, plan, unreadable));
     issues.push(...detectPotentialDrift(registry, plan, plan.paramRefs));
     const attesting = attestingFiles(plan);
     const counts = {

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

@@ -1,7 +1,7 @@
 import type { RegistryDelta } from './registry.js';
 import type { Registry } from './types.js';
 /** Codes this reader can produce; each is also produced by the evaluating path. */
-export type StaticReadCode = 'registry-invalid' | 'registry-no-default' | 'registry-not-static';
+export type StaticReadCode = 'registry-invalid' | 'registry-no-default' | 'registry-not-static' | 'unreadable-file';
 export type StaticReadResult = {
     ok: true;
     registry: Registry;
@@ -13,7 +13,7 @@ export type StaticReadResult = {
 };
 export declare function readRegistrySource(file: string, source: string): StaticReadResult;
 /** Codes the delta reader can produce; both are codes `archive` already emits. */
-export type DeltaReadCode = 'change-not-found' | 'registry-not-static';
+export type DeltaReadCode = 'change-not-found' | 'registry-not-static' | 'unreadable-file';
 export type DeltaReadResult = {
     ok: true;
     delta: RegistryDelta;
@@ -39,6 +39,38 @@ export type DeltaReadResult = {
  * (write the value inline, or `--eval`) is the same sentence either way.
  */
 export declare function readDeltaSource(file: string, source: string): DeltaReadResult;
+/**
+ * The requirement ids a source *declares*, read from a file that could not be
+ * read as a registry (design §5.3).
+ *
+ * This is not a second registry reader and cannot become one: it returns ids and
+ * nothing else, it validates none of them, and no command builds a `Registry`
+ * from what it finds. What it exists for is the question `orphan-test` cannot
+ * otherwise answer — is this scenario attesting an id that a *broken* file
+ * declares, or one that genuinely does not exist — and the answer decides
+ * whether a finding is a fact or fallout.
+ *
+ * It reads the ids rather than the file's id *prefix*, which is what this was
+ * first framed as needing. The prefix cannot be recovered from a path: this
+ * repository's own registry is `attest.reqs.ts` holding `ATX-*`, which is the
+ * evidence that killed the prefix-matches-filename rule (see CHANGELOG,
+ * `Considered and rejected`). The ids are in the source, so nothing has to be
+ * inferred from a naming convention that nothing enforces.
+ *
+ * Recall is partial by construction, and the direction of the miss is the point:
+ * an id it does not find keeps its `orphan-test`, so the report stays noisy —
+ * never wrong. Measured over the failure modes that produce an unreadable
+ * registry: a truncated file, a missing default export, a non-literal *value*, a
+ * schema-invalid entry, a module that throws at import, and a spread of ids from
+ * another module all yield the ids written in this file; only a registry built
+ * by a call — `export default buildReqs()` — yields none, and that file contains
+ * no id to find.
+ *
+ * `ts.createSourceFile` is deliberately error-tolerant, which is what lets the
+ * first of those cases work at all: the parser recovers an object literal from a
+ * file that does not compile.
+ */
+export declare function declaredIdsFromSource(file: string, source: string): string[];
 /**
  * Where a new entry may be written into a registry file's literal, as an offset
  * into its source (design §7).

package/dist/core/static-registry.js

@@ -20,6 +20,7 @@
 // value is fixed by the source text — a second walker would be a second answer
 // to "is this a literal", and those two answers must not be able to disagree.
 import ts from 'typescript';
+import { parseSource } from './compiler.js';
 import { RegistryValidationError, withProposedRequirements } from './registry.js';
 import { RegistrySchema } from './schema.js';
 /** The authoring function a registry file must default-export the result of. */
@@ -45,7 +46,20 @@ class NotStatic extends Error {
  * has to be run — and only the prose around it differs.
  */
 function extractLiteralExport(file, source, fn, noun) {
-    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, /* setParentNodes */ true);
+    // Strict: a source that does not compile is refused here rather than read out
+    // of whatever the parser recovered from it. Before this, a registry truncated
+    // before its closing `});` came back as a complete registry.
+    const parsed = parseSource(file, source);
+    if ('error' in parsed) {
+        return {
+            ok: false,
+            reason: 'syntax',
+            message: `This ${noun} does not compile (${parsed.error.message}), so nothing in it was checked. ` +
+                `Fix the syntax error and run again.`,
+            ...(parsed.error.line === undefined ? {} : { line: parsed.error.line }),
+        };
+    }
+    const sf = parsed.sf;
     const lineOf = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
     const exported = defaultExportExpression(sf);
     if (!exported) {
@@ -91,10 +105,25 @@ function failure(extracted, code) {
         ...(extracted.line === undefined ? {} : { line: extracted.line }),
     };
 }
+/**
+ * What this reader calls the three ways extraction fails; `DELTA_CODE` below is
+ * the other half.
+ *
+ * A table per reader rather than a ternary in each, because only one row
+ * differs in kind: `syntax` is the same answer for both — a file that does not
+ * compile is not a registry problem or a delta problem, it is not a file — and
+ * two readers spelling that differently is exactly the disagreement this module
+ * opens by refusing to allow.
+ */
+const REGISTRY_CODE = {
+    syntax: 'unreadable-file',
+    'no-default': 'registry-no-default',
+    'not-static': 'registry-not-static',
+};
 export function readRegistrySource(file, source) {
     const extracted = extractLiteralExport(file, source, DEFINE, 'registry');
     if (!extracted.ok) {
-        return failure(extracted, extracted.reason === 'no-default' ? 'registry-no-default' : 'registry-not-static');
+        return failure(extracted, REGISTRY_CODE[extracted.reason]);
     }
     const result = RegistrySchema.safeParse(extracted.value);
     if (!result.success) {
@@ -109,6 +138,12 @@ export function readRegistrySource(file, source) {
     }
     return { ok: true, registry: result.data };
 }
+/** The delta reader's half of the table above `readRegistrySource`. */
+const DELTA_CODE = {
+    syntax: 'unreadable-file',
+    'no-default': 'change-not-found',
+    'not-static': 'registry-not-static',
+};
 /**
  * Read a change's `delta({ … })` from its source (design §7).
  *
@@ -127,7 +162,7 @@ export function readRegistrySource(file, source) {
 export function readDeltaSource(file, source) {
     const extracted = extractLiteralExport(file, source, DELTA, 'delta');
     if (!extracted.ok) {
-        return failure(extracted, extracted.reason === 'no-default' ? 'change-not-found' : 'registry-not-static');
+        return failure(extracted, DELTA_CODE[extracted.reason]);
     }
     const value = extracted.value;
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
@@ -148,6 +183,78 @@ export function readDeltaSource(file, source) {
     // thing that would notice, and it should have nothing to notice.
     return { ok: true, delta: withProposedRequirements(value) };
 }
+/**
+ * The requirement ids a source *declares*, read from a file that could not be
+ * read as a registry (design §5.3).
+ *
+ * This is not a second registry reader and cannot become one: it returns ids and
+ * nothing else, it validates none of them, and no command builds a `Registry`
+ * from what it finds. What it exists for is the question `orphan-test` cannot
+ * otherwise answer — is this scenario attesting an id that a *broken* file
+ * declares, or one that genuinely does not exist — and the answer decides
+ * whether a finding is a fact or fallout.
+ *
+ * It reads the ids rather than the file's id *prefix*, which is what this was
+ * first framed as needing. The prefix cannot be recovered from a path: this
+ * repository's own registry is `attest.reqs.ts` holding `ATX-*`, which is the
+ * evidence that killed the prefix-matches-filename rule (see CHANGELOG,
+ * `Considered and rejected`). The ids are in the source, so nothing has to be
+ * inferred from a naming convention that nothing enforces.
+ *
+ * Recall is partial by construction, and the direction of the miss is the point:
+ * an id it does not find keeps its `orphan-test`, so the report stays noisy —
+ * never wrong. Measured over the failure modes that produce an unreadable
+ * registry: a truncated file, a missing default export, a non-literal *value*, a
+ * schema-invalid entry, a module that throws at import, and a spread of ids from
+ * another module all yield the ids written in this file; only a registry built
+ * by a call — `export default buildReqs()` — yields none, and that file contains
+ * no id to find.
+ *
+ * `ts.createSourceFile` is deliberately error-tolerant, which is what lets the
+ * first of those cases work at all: the parser recovers an object literal from a
+ * file that does not compile.
+ */
+export function declaredIdsFromSource(file, source) {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, /* setParentNodes */ true);
+    const names = localNames(sf, DEFINE);
+    const ids = new Set();
+    // Any `defineRequirements({ … })` in the file, not only the exported one: the
+    // failure being diagnosed is often that the call is not where it should be —
+    // `export const registry = …` is a whole failure mode — and the ids are no
+    // less declared for it. Scoped to that call's argument all the same, so an
+    // id-shaped key in unrelated data is not mistaken for a requirement.
+    const visit = (node) => {
+        // `arguments.length > 0` rather than `=== 1`, which is what the reader
+        // demands: this runs on files the reader has already refused, so being
+        // stricter than it here could only lose ids it is not deciding anything by.
+        if (ts.isCallExpression(node) && node.arguments.length > 0 && callsAuthoringFn(node, names, DEFINE)) {
+            const arg = unwrap(node.arguments[0]);
+            if (ts.isObjectLiteralExpression(arg)) {
+                for (const prop of arg.properties) {
+                    const name = prop.name;
+                    if (!name)
+                        continue;
+                    if (!ts.isStringLiteral(name) && !ts.isIdentifier(name))
+                        continue;
+                    if (REQUIREMENT_ID.test(name.text))
+                        ids.add(name.text);
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return [...ids];
+}
+/**
+ * The id shape, as a bare regex rather than through `RequirementIdSchema`.
+ *
+ * Nothing is being validated here — a key that does not look like an id is
+ * simply not one, and there is no author to tell. Kept identical to the schema's
+ * pattern by `tests/static-registry.spec.ts`, which is the only place the two
+ * spellings can be held together.
+ */
+const REQUIREMENT_ID = /^[A-Z]+-\d+$/;
 /**
  * The expression a file default-exports, following one level of local binding.
  *
@@ -191,10 +298,20 @@ function constInitializer(sf, name) {
 function authoringCall(expr, sf, fn) {
     if (!ts.isCallExpression(expr) || expr.arguments.length !== 1)
         return undefined;
-    const callee = expr.expression;
-    const named = (ts.isIdentifier(callee) && localNames(sf, fn).has(callee.text)) ||
-        (ts.isPropertyAccessExpression(callee) && callee.name.text === fn);
-    return named ? expr.arguments[0] : undefined;
+    return callsAuthoringFn(expr, localNames(sf, fn), fn) ? expr.arguments[0] : undefined;
+}
+/**
+ * Whether a call is a call of `fn`, by the local names the imports bound to it.
+ *
+ * One predicate for both readers of this question — the extraction above and the
+ * id recovery below — because they must not be able to disagree about what
+ * counts as the authoring call. An alias rule taught to one and not the other
+ * would make recovery silently miss exactly the files the reader refuses.
+ */
+function callsAuthoringFn(call, names, fn) {
+    const callee = call.expression;
+    return ((ts.isIdentifier(callee) && names.has(callee.text)) ||
+        (ts.isPropertyAccessExpression(callee) && callee.name.text === fn));
 }
 /** Local names bound to the imported `fn`, including aliases. */
 function localNames(sf, fn) {
@@ -329,7 +446,15 @@ function numericValue(node) {
     return value;
 }
 export function registryInsertionPoint(file, source) {
-    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, /* setParentNodes */ true);
+    // The write site, and the one where a recovered AST does damage rather than
+    // merely misreports: an offset taken from a file that does not compile would
+    // splice a new requirement into it. `undefined` is this function's documented
+    // refusal to guess, and a source that will not parse is the clearest case of
+    // one there is.
+    const parsed = parseSource(file, source);
+    if ('error' in parsed)
+        return undefined;
+    const sf = parsed.sf;
     const exported = defaultExportExpression(sf);
     if (!exported)
         return undefined;

package/dist/core/validator.d.ts

@@ -1,3 +1,4 @@
+import type { UnreadableRegistry } from './locate.js';
 import type { AttestPlan, Issue, ParamRef, Registry } from './types.js';
 /**
  * Uncovered requirements: intent exists but no scenario attests it (design §5.3).
@@ -20,11 +21,15 @@ export declare function uncoveredIssues(registry: Registry, plan: AttestPlan): I
  * and one WARNING:
  * - rationale-placeholder: a `{name}` in a rationale, which is never interpolated
  *
- * `registryIncomplete` says that at least one `*.reqs.ts` failed to load, so
- * `registry` is known to be missing whatever was in it. It changes no verdict —
- * only what `orphan-test` advises, for the reason below.
+ * and one more WARNING, which exists only when a registry file failed to load:
+ * - orphan-from-failed-registry: the scenarios attesting ids that file declares
+ *
+ * `unreadable` is the `*.reqs.ts` files that failed to load, each with the ids
+ * its source still names (see `loadRegistry`). It changes no verdict — only
+ * which findings are stated per scenario and which are stated once, for the
+ * reason below.
  */
-export declare function validateStructure(registry: Registry, plan: AttestPlan, registryIncomplete?: boolean): Issue[];
+export declare function validateStructure(registry: Registry, plan: AttestPlan, unreadable?: readonly UnreadableRegistry[]): Issue[];
 /**
  * Weak anti-drift heuristic (design §6, mechanism 3). Evaluated per requirement,
  * not per scenario: a requirement that owns params is quiet as soon as *any* one

package/dist/core/validator.js

@@ -1,5 +1,6 @@
 // Structural validation + anti-drift heuristic (design §5.3, §6).
 // Graded reporting: ERROR / WARNING / INFO, each with file + line + fix hint.
+import { byCodeUnit } from './order.js';
 /**
  * Uncovered requirements: intent exists but no scenario attests it (design §5.3).
  *
@@ -35,11 +36,15 @@ export function uncoveredIssues(registry, plan) {
  * and one WARNING:
  * - rationale-placeholder: a `{name}` in a rationale, which is never interpolated
  *
- * `registryIncomplete` says that at least one `*.reqs.ts` failed to load, so
- * `registry` is known to be missing whatever was in it. It changes no verdict —
- * only what `orphan-test` advises, for the reason below.
+ * and one more WARNING, which exists only when a registry file failed to load:
+ * - orphan-from-failed-registry: the scenarios attesting ids that file declares
+ *
+ * `unreadable` is the `*.reqs.ts` files that failed to load, each with the ids
+ * its source still names (see `loadRegistry`). It changes no verdict — only
+ * which findings are stated per scenario and which are stated once, for the
+ * reason below.
  */
-export function validateStructure(registry, plan, registryIncomplete = false) {
+export function validateStructure(registry, plan, unreadable = []) {
     const issues = [];
     const knownIds = new Set(Object.keys(registry));
     // orphan-test: covers a requirement that does not exist.
@@ -50,27 +55,75 @@ export function validateStructure(registry, plan, registryIncomplete = false) {
     // following the hint would add a duplicate. That case is not rare when it
     // happens — one unreadable `*.reqs.ts` orphans every scenario of every
     // requirement it declared, so the wrong advice is also the loudest thing in
-    // the report.
+    // the report. Measured on one broken registry of three requirements: six
+    // ERRORs, of which one was the cause and five were its shadow.
+    //
+    // Which of the two a given orphan is *can* be decided here, because
+    // `loadRegistry` brings back the ids the broken file's source still names. So
+    // the scenarios attesting those ids are not reported one by one: they are
+    // fallout from a finding already in the report, and the fallout is stated once
+    // per file that caused it. That is the same move `duplicate-prefix` makes —
+    // the fact is about the file, not about each requirement that reveals it — and
+    // the same order ATX-62 records for `spec-load-failed`: the replacement comes
+    // first, the withdrawal follows it, because suppressing with nothing in its
+    // place trades a wrong message for silence.
     //
-    // Which of the two this is cannot be decided here: the ids of a file that
-    // never parsed are exactly what is unavailable. So the finding stands and the
-    // *advice* names the uncertainty and the order to work in — a report that is
-    // quieter about problems it can still see would be the worse trade for a
-    // command whose contract is breadth.
-    const orphanFix = (id) => registryIncomplete
-        ? `A registry file failed to load, so ids it declares are missing here — fix that first, and add "${id}" only if it is still unknown afterwards.`
+    // Nothing is lost by collapsing them. The replacement names the file, the
+    // count and the ids, so a reader can still see which scenarios are affected;
+    // the load failure is already an ERROR, so the verdict cannot move; and the
+    // scenarios themselves are not defective — they will be verified normally the
+    // moment the registry loads.
+    const swallowed = new Map(unreadable.map((u) => [u.file, []]));
+    const ownerOf = new Map();
+    for (const u of unreadable)
+        for (const id of u.ids)
+            ownerOf.set(id, u.file);
+    // An unreadable file whose ids could not be recovered leaves the question open
+    // for every orphan that is not claimed by another one, and the hedged advice
+    // is what an open question sounds like. When every unreadable file gave up its
+    // ids, an orphan none of them claims is genuinely unknown — and gets the plain
+    // advice it deserves, which the hedge had been withdrawing from correct
+    // findings too.
+    const someFileOpaque = unreadable.some((u) => u.ids.length === 0);
+    const orphanFix = (id) => someFileOpaque
+        ? `A registry file failed to load and its ids could not be read, so "${id}" may be one of them — fix that first, and add it only if it is still unknown afterwards.`
         : `Add it to the registry, or fix the id.`;
     for (const s of plan.scenarios) {
-        if (!knownIds.has(s.reqId)) {
-            issues.push({
-                level: 'ERROR',
-                code: 'orphan-test',
-                reqId: s.reqId,
-                file: s.file,
-                line: s.line,
-                message: `scenario "${s.name}" attests unknown requirement "${s.reqId}". ${orphanFix(s.reqId)}`,
-            });
+        if (knownIds.has(s.reqId))
+            continue;
+        const owner = ownerOf.get(s.reqId);
+        if (owner !== undefined) {
+            swallowed.get(owner).push(s.reqId);
+            continue;
         }
+        issues.push({
+            level: 'ERROR',
+            code: 'orphan-test',
+            reqId: s.reqId,
+            file: s.file,
+            line: s.line,
+            message: `scenario "${s.name}" attests unknown requirement "${s.reqId}". ${orphanFix(s.reqId)}`,
+        });
+    }
+    // WARNING, not ERROR: the defect is the load failure, which is an ERROR of its
+    // own and always present when this is. Reporting it a second time at the same
+    // level would say a broken registry is two problems.
+    //
+    // No `reqId`: the finding is about a file and the set of ids it took down with
+    // it, and no single requirement is implicated — the same reason
+    // `duplicate-prefix` and `spec-load-failed` carry none.
+    for (const u of unreadable) {
+        const ids = swallowed.get(u.file);
+        if (ids.length === 0)
+            continue;
+        const unique = [...new Set(ids)].sort(byCodeUnit);
+        issues.push({
+            level: 'WARNING',
+            code: 'orphan-from-failed-registry',
+            file: u.file,
+            message: `${ids.length} ${ids.length === 1 ? 'scenario attests' : 'scenarios attest'} ids ${u.file} declares (${unique.join(', ')}), and it failed to load — so those ids are missing from this run. ` +
+                `They are not orphans: fix the load failure reported above and they will be verified as usual.`,
+        });
     }
     // uncovered-requirement: intent exists but no scenario attests it. Shared
     // with `cover`, so the two commands cannot drift apart.

package/package.json

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