@am_shork/attest 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -13,6 +13,208 @@ 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.9.2] - 2026-08-17
+
+### Added
+
+- **`@am_shork/attest/inspect`: read what a project declares, without executing
+  it and without acquiring the runner peer.** One function,
+  `inspectProject(root)`, answering the requirements a project declares, the
+  scenarios declared for each, and the issues that stopped a file being read.
+  Nothing about the quality of any of it — that is the ground truth this project
+  refuses to compute for someone else's requirements (design §0).
+
+  *Why it exists rather than what it does.* Everything this repository knows
+  about the quality of its own intent layer is a hand-judged table in
+  `tests/intent-rule-candidates.spec.ts`, and the check that keeps such a table
+  from rotting is that a scenario a row names is one a spec really declares. An
+  adopter could not write that check: the package exported the authoring API and
+  nothing else, so `parseSpecs` and the static registry read were internal and
+  **the scenario names of their own project were unreachable** — not
+  undocumented, unreachable. This is the enabling half of the judgement-table
+  proposal under *Under consideration*, and deliberately only that half: it
+  ships no schema and decides nothing, and it is the only thing that can produce
+  the second table that proposal is waiting for.
+
+  *One function, not the four internals it composes,* because `loadRegistry`
+  takes a reader and which of the two runs is a security property fixed by the
+  command, never chosen by a caller (design §5.1). The static reader is welded
+  in and no parameter can change it.
+
+  *And its import closure names neither runner peer,* so a consumer that only
+  analyses acquires neither `vite` nor `vitest` — the same argument `./define`
+  was added on (design §10). Measured on the built entry: ten modules, and the
+  only bare specifiers in the closure are `typescript`, `zod` and two node
+  builtins. That claim is gated over the **built** package rather than the
+  source, because `locate.ts` names `loader.ts` in a type-only import that the
+  emit erases: the two graphs differ by exactly that edge, and it is the edge
+  the promise is about. `tests/import-boundary.spec.ts` holds the source side,
+  where a type-only mention still counts as *naming* the runner, and its
+  reachability walk now follows runtime edges only for the same reason.
+
+  Additive: no command, flag, exit code or `--json` field changes, and nothing
+  that used to pass now fails.
+
+- **"Judging your own intent layer" (`docs/{en,zh}/intent-quality.md`): the four
+  things no gate is looking at, and a method for building your own
+  counter-pressure out of them.** For an existing adopter, on the back of the
+  export above.
+
+  *A method with no template, and the omission is the point.* The page states
+  the four **findings** — coverage is binary so lumping is free, a quantifier is
+  unread, an iterated `params` list is a run's domain, an assertion can echo
+  rather than pin — and the two **mechanical properties** that make a
+  hand-judged record a counter-pressure rather than a note: completeness
+  (something enumerable must force a row) and rot-binding (a scenario a row
+  names must be asserted to exist). Both generalise without assuming a single
+  column. What it withholds is this repository's own answer — the four tables
+  in `tests/intent-rule-candidates.spec.ts` — and it asks a reader to reach that
+  file only after doing the hand pass, saying why rather than hiding it: there
+  is one such table in existence and its author wrote both the schema and every
+  answer in it, so a second one built from someone else's corpus is evidence
+  while one built from ours is an echo. That is the fourth finding turned on the
+  question itself.
+  The worked example is deliberately **one column**, so the shape that comes
+  back is not a copy of the shape that went out, and the report the page asks
+  for names the thing worth most: *the column you needed that we do not have.*
+
+## [0.9.1] - 2026-08-13
+
+### Changed
+
+- **Every command starts 11–28% faster, from three lines in `bin/attest.js`.**
+  `typescript` is the fixed toll on an `attest` invocation and nothing about the
+  design can move it: measured, the CLI's dependency graph costs ~790 ms to load
+  and the compiler is ~672 ms of that, against ~28 ms for commander, ~17 ms for
+  chalk and ~70 ms for zod. It is also not deferrable — every command except
+  `init` reads a registry or a spec through the AST, so the import is needed and
+  not merely eager. What *is* movable is the price of the same load, and Node's
+  compile cache moves it: V8 keeps its compilation output between runs. Two
+  independent A/B rounds, nine interleaved runs each, median — `check self`
+  1153 → 970 and 1106 → 971 ms, `cover self` 1122 → 951 and 1346 → 1195 ms,
+  `status` 1110 → 923 ms, `init` 904 → 711 and 1365 → 984 ms. The absolute
+  numbers move with the machine; the direction did not, in either round or on
+  any command.
+  **The launcher's import had to become dynamic, and that is the load-bearing
+  half.** A static `import` is hoisted and its whole graph evaluated before any
+  statement in the file runs, so with one the cache is enabled *after*
+  `typescript` has already been compiled and does nothing whatever — while still
+  reporting success and leaving every command working. Measured: the static
+  spelling came back at 873 ms against an unpatched 897 ms, inside the noise,
+  where the dynamic one is 669 ms. A defence that reads as present and is not is
+  this repository's dominant failure shape, and it fits in a three-line file.
+  No behaviour changes: same output, same exit codes, same files. The cache is
+  optional-chained, because `engines` allows Node 20 and the API arrived in
+  22.1 — on an older runtime the speed-up is simply absent. It never throws, and
+  a cache directory that cannot be written returns a status this ignores, since
+  the only thing a failure costs is the saving. It is written under the OS temp
+  directory and never into the project, which is the one place every other file
+  Attest writes belongs.
+
+- **`loadRegistry`'s fan-out is bounded — the third one, where `[0.9.0]` closed
+  "both".** That entry is not wrong about what it did; it is wrong about how many
+  there were. `locate.ts` reads registry files through a
+  `Promise.all(paths.map(…))` of its own, so `check` on a tree carrying N
+  `*.reqs.ts` held N reads and N `SourceFile`s at once — the same shape, on the
+  same command, against the same input nobody here chooses. Measured in
+  `tests/locate-fanout.spec.ts`, which now counts a third pool: **64 before, 32
+  after**, on 64 registry files. Unbounded, the figure is the count of the files;
+  bounded, it is the constant.
+  *Why it hid is the part worth keeping.* The other two live in functions named
+  for walking and parsing, and both had a comment about concurrency saying
+  nothing about a bound. This one has a comment that reads as a considered
+  decision — "read the files concurrently, then fold the results in sorted file
+  order: the issue list stays deterministic regardless of which one finished
+  first" — and it is a correct, load-bearing answer to a *different* question.
+  Something that has visibly been thought about does not get thought about again,
+  which is what put a third copy of one shape past a fix that named itself as
+  covering all of them.
+  *The reader is what makes it more than arithmetic here.* `parseSpecs` bounds
+  sources; this bounds whatever the reader holds, which under `--eval`,
+  `verify` and `archive` is a Vite SSR module evaluation rather than a string.
+  Hence a third constant rather than sharing one, on the reason `WALK_CONCURRENCY`
+  already gives: the three bound different resources and cannot be tuned
+  together.
+  Descriptor exhaustion is still the failure it invites and still unmeasured —
+  Windows uses Win32 handles rather than POSIX descriptors, so `ulimit -n` does
+  not govern it there, and Linux is the half CI runs. The peak is portable
+  arithmetic, which is the standard both earlier halves were accepted on.
+  No behaviour change and no `ATX-n`, on that same precedent: the registry, the
+  issue list, its order and `prefixOwners` are identical, all asserted beside the
+  peak. The fold is now driven by index rather than by arrival, which is what
+  keeps "sorted file order" true through a pool that completes out of order —
+  the same indexing `parseSpecs` uses, for the same reason.
+
+### Fixed
+
+- **`--apply` wrote a `*.reqs.ts` that no longer parses, when a MODIFIED entry
+  changed two `params` and one of them had an integer-like key.** The write-back
+  rests on an ordering property stated in `splice.ts` and nowhere enforced: the
+  walk emits its edits in ascending offset order, so the pass at the bottom can
+  be a `reverse()` rather than a numeric sort — "an ordering that holds by
+  construction beats one restored after the fact". It did not hold by
+  construction. `registryEntryLayouts` handed the layout back as plain objects,
+  and **JavaScript hoists an integer-like key to the front of every object**, so
+  `params: { budgetMb: 12, 10: 'ten' }` was described in an order the file never
+  wrote. A `params` key genuinely can be a number: `staticName` spells a numeric
+  literal key as `String(value)` and the schema's `z.record(z.string(), …)`
+  accepts the result, on both reader paths.
+  The consequence is the one shape this command must not have. With the order
+  reversed, the lower edit was applied first and every offset after it shifted
+  underneath the spans still to be written — measured, changing `budgetMb`
+  `12 → 4096` alongside `10: 'ten' → 'a'` produced `params: { budgetMb: 4096,
+  10'a'n' },`, off by exactly the two bytes the first replacement grew. The
+  registry was **already on disk** by then: `applyMerge` writes each file before
+  `verifyWritten` re-reads it, so the re-read caught it and stopped the merge —
+  which is what that check is for — but what it stopped at was a hand-written,
+  hand-commented registry left unparseable, and the merge's own account of the
+  failure is an `internal-error` naming the file.
+  The fix is the containers, not a sort. `fields`, `paramKeys` and the layout map
+  itself are `Map`s, which keep insertion order for every key type, so the
+  property is back to holding by construction rather than by the keys happening
+  not to be numbers — the standard `keySource` and `compareIds` are already
+  written to, arriving at the one place that had been resting on an upstream
+  grammar. Contained to `splice.ts`, which is the only consumer.
+  No new requirement: ATX-76 already says the write-back replaces *the source
+  span of each value that changed*, and this was a defect against that sentence
+  rather than a gap in it. The regression sits in `tests/splice.spec.ts`, at the
+  seam the invariant lives on; reaching it through a `self/` scenario would need
+  a whole fixture project to express one numeric key, for a weaker signal.
+
+- **The package shipped a file its own `exports` map forbade reading.** npm puts
+  `package.json` in every tarball whatever `files` says, and the map named only
+  `.` and `./define` — so `@am_shork/attest/package.json`, which tooling reaches
+  for to read a dependency's version, came back
+  `ERR_PACKAGE_PATH_NOT_EXPORTED`. Measured against a real installed tarball,
+  not reasoned about. Fixed by naming it, which is the whole change.
+  *The test that should have caught it was checking the wrong half.* "Ships the
+  entry points the exports map promises" asserted that `dist/index.js`,
+  `dist/core/registry.js` and `bin/attest.js` **exist** in the install — which an
+  `exports` map blocking every subpath would leave exactly as true. Existence and
+  reachability are decided by different fields, `files` shipping the bytes and
+  `exports` deciding what may address them, so one cannot stand in for the other.
+  `tests/consumer.spec.ts` now resolves each promised specifier from inside the
+  consumer project, asserting line by line so the diff names the one that
+  stopped. It went red on `./package.json` and green on the other two, which is
+  what says the new test measures the thing rather than the fix.
+
+- **`cli/report.ts` was carrying a false reason for a defence, and it
+  contradicted `render.ts`.** The comment on `formatCoverage` justified
+  sanitising a requirement id with "under `--eval` the registry is whatever the
+  module exported, and `evalReader` checks that it is an object and nothing
+  further" — true when it was written, and untrue since ATX-38 made the
+  evaluating reader validate against the same schema as the static one. So
+  `^[A-Z]+-\d+$` holds on both paths, `render.ts` says so explicitly, and the two
+  modules read as disagreeing about whether a registry id can carry a control
+  character.
+  The sanitising stays and the reason is corrected: the grammar is held
+  somewhere else, `CoverageRow.reqId` is a `string`, and the function is
+  exported — a defence that lapses when the other one does is not a defence,
+  which is the standard `splice.ts`'s `keySource` is already written to. No
+  behaviour change; the call was, and remains, one that cannot fire through any
+  command. Recorded because in this repository a comment is the decision record,
+  and a false one is read as evidence the next time the question comes up.
+
 ## [0.9.0] - 2026-08-12
 
 ### Added
@@ -4945,7 +5147,21 @@ have to gather again.
   far past the two registry readers' current surface. **(3)** No mechanism is yet
   known that separates "the assertion pins this independently" from "the assertion
   echoes it" without executing the scenario twice under different values — which
-  is mutation testing, a much larger thing to own.
+  is mutation testing, a much larger thing to own. *One has since been built and
+  scored, and it does not lift this blocker.* The syntactic candidate — flag a
+  scenario whose expectation is derived from the param the code under test
+  consumed, decided inside one body without executing anything — flags 9 params
+  here, of which **4 are real echoes and 5 are pinned by something outside the
+  body it cannot see**. Under half precision, and the failure is the one
+  predicted above rather than a tuning problem: what pins a value is often a
+  fixture or a second derivation in another file, so a single-body detector is
+  looking in the wrong place by construction. The newest false positive is the
+  clearest instance — `ATX-79.subpath` is compared against `package.json`, which
+  is not the code under test and does not read the registry, so the independent
+  term is in another file entirely. Precision has fallen on every addition
+  measured so far, which is the direction that matters. The score is quoted from the
+  suite's snapshot and re-read with the judgement-table entry above, which is
+  where the same measurement is used for a different decision.
   **The guidance half has shipped; this entry is now only about the detector.**
   "Read the param inside the assertion" was insufficient and half-wrong as
   written, and `[0.5.0]` replaces it everywhere it appeared — README, the
@@ -5241,6 +5457,98 @@ have to gather again.
   and the second report of the same shape, which this measurement does not
   supply and does not replace.
 
+- **An outward-facing form of the judgement tables, so an adopter can run this
+  counter-pressure on their own registry.**
+  `tests/intent-rule-candidates.spec.ts` maintains four hand-judged tables over
+  this repo's registry and enforces their completeness. Design §11 records the
+  properties they defend and that nothing enforces any of them; what the tables
+  add is a counter-pressure holding for **one** registry whose authors agreed to
+  maintain it. An adopter got none of it, and the reason was sharper
+  than "nobody wrote it for them": the package exported `requirement`,
+  `scenario`, `defineRequirements`, `delta` and types, and nothing else.
+  `parseSpecs`, `findFiles` and `readRegistrySource` were internal, so an
+  adopter **could not enumerate their own scenario names** — the table's central
+  rot check, that a claimed scenario is one a spec really declares, was not
+  merely unwritten downstream but unreachable. **That half shipped under
+  `[0.9.2]` as `@am_shork/attest/inspect`** and is recorded at the foot of
+  this entry; what stays here is the schema built on top of it, and the three
+  blockers below are untouched by the export.
+  *The shape that makes it shippable at all is a split, not a feature.* The
+  engine can compute which ids exist, which statements match the universal
+  quantifier regex, which params are list-valued, and whether a named scenario
+  is declared — all four already, all statically. It cannot compute how many
+  obligations a requirement carries, what a quantifier ranges over, or whether a
+  scenario iterates a param. So the shippable object is **the enforcement, never
+  the judgement**: an opt-in `*.judge.ts` read by the same static reader and
+  under the same literal-only rule the registry is (it is metadata about
+  requirements under review, so `check` must execute nothing to read it), whose
+  contents are entirely the adopter's. Opting in is creating the file; once it
+  exists, `requirement-unjudged`, `orphan-judgement`, `unbound-site` and
+  `quantifier-unjudged` make it complete and keep it from rotting. The
+  asymmetry is the only way this can exist without Attest asserting a ground
+  truth it refuses to compute (§0), and it is the same asymmetry `never-red`
+  already runs on: the archive gate would owe judgement only for ids a change
+  ADDs, so a brownfield adoption is not blocked wholesale.
+  *One part of the existing table cannot ship in any form.* `DOMAINS.pin` comes
+  in two kinds — a scenario name, checkable against the AST, and a **source-text
+  fragment** grepped out of the spec file. The second is asserting on the
+  wording of somebody's test, which is the `Issue.message` category error under
+  another name. Only the scenario-name kind is exportable, and what that costs
+  is real: the grep is what caught a deleted pin that `toContain` had passed.
+  *Why no detector ships with it, and this is the part that is already
+  measured.* Three rule families were built and scored against the whole corpus
+  (86 entries, counting a fixture id once per registry file) before any was
+  written into the engine, which is the order `divergent-param` was originally
+  designed in the wrong way round. Every figure below is a quotation of the
+  suite's inline snapshots; the snapshot is the fresh copy, and this paragraph
+  is only ever as fresh as its last edit.
+  **(1) `compound-requirement`** — 34 requirements carry more than one
+  obligation, it flags 16, is **wrong about none**, and misses 18. Never wrong
+  and nearly blind, and the 18 are the form the coverage incentive actually
+  rewards: extra clauses under a single keyword. **(2) The widened variant** —
+  29 correct, but 14 wrong and still 5 missed, and it is silenced by deleting an
+  "and". A rule whose cheapest fix degrades the artifact it protects does not
+  ship, and its precision falls as the registry grows. **(3) `divergent-param`**
+  — 5 divergences on this repo, **all 5 judged wrong**, zero true positives ever
+  recorded. The `code` group now spans 19 ids, and the failure is structural
+  rather than a matter of naming: the key is built by discarding the evidence of
+  relatedness, so the one genuinely paired divergence in the group is the one it
+  cannot show, and the key has churned three times under `flag` on additions
+  that changed no verdict. A fourth candidate — the echo detector, scored at
+  half precision — belongs to the tautology entry above and is not re-quoted
+  here, because a figure stated in two places goes stale in one. Taken together
+  these are the measured range of what a token or single-body detector over
+  prose can do here, and they are why the proposal is enforcement-only.
+  *What blocks the decision — three things.* **(1) One adapter.** This
+  repository's table is the only one that exists, and its author wrote both the
+  schema and every answer in it. By this project's own rule a second table is
+  what makes the seam real, and freezing a `Judgement` type now is deciding for
+  everyone from 34 requirements written by one person. **(2) The breaking form
+  of this was already rejected** — see *Countable obligations* below — and one
+  of its three reasons survives the separate-file shape intact: **nothing can
+  force the count to be true.** The other two do not survive, which is what is
+  new here: a separate artifact touches no `--json` field, no delta apply and no
+  `render` output, and completeness *across ids* is computable in a way
+  completeness *within* an obligation array never was. So this is a re-proposal
+  with one of three objections answered and the sharpest one standing.
+  **(3) `quantifier-unjudged` reuses a rejected detector as its trigger.**
+  Firing on the quantifier token was rejected below at 43% reach and 70% wrong;
+  the claim here is that the same regex is acceptable when it asks a question an
+  author discharges in one line (`over: 'values'`) rather than issuing a
+  verdict. That claim is untested on anyone who did not also write the regex.
+  *The half that is not blocked has shipped, under `[0.9.2]`.*
+  `@am_shork/attest/inspect` is one function answering what a project declares —
+  AST-only, no runner peer, landing on the existing static/executing boundary.
+  It ships no schema and decides nothing, which is why it could go ahead of the
+  three blockers rather than waiting on them. What it changes about this entry
+  is the *kind* of thing that is now missing: the mechanism is no longer
+  unreachable, only unwritten, so a second table is something an adopter can
+  build rather than something only this repository could.
+  *What would decide it:* one judgement table maintained by someone who did not
+  design it. If it comes back the same shape, the seam is real and the schema
+  follows; if it comes back different, `inspect` was the whole answer and the
+  schema never needs to exist.
+
 ## Considered and rejected
 
 Decisions **not** to build something, kept where they can be found before the
@@ -5251,6 +5559,40 @@ 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.
 
+### 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
+rejected on the size of what it actually reaches. The proposal was the move
+`pipeline.ts` already makes for the runner half — `vite`/`vitest` behind an
+`await import(...)`, on the argument that a short-lived process pays cold start
+as the whole bill — applied a second time to the AST half.
+
+The two are not the same shape, and the measurement is why. The runner lazy-load
+took a cost off five of seven commands, because `check`, `cover`, `render`,
+`status` and `init` genuinely cannot start a run. The AST half has one
+beneficiary: **every command except `init` reads a registry or a spec through the
+compiler**, so for `check`, `cover`, `render`, `status`, `verify` and `archive`
+deferring the import moves when the 672 ms is paid and not whether. What is left
+is `init`, which is run once per project, and `--version` / `--help`. Against the
+compile cache — which took 11–28% off *all* of them for three lines — the
+remaining prize is roughly a further 260 ms on `init` alone.
+
+The structural price is not small either, and it is concentrated in the wrong
+place. Everything funnels into the compiler through `pipeline.ts`'s static graph,
+including two edges that are easy to miss: `status` reaches it via
+`red-record.ts` → `merge.ts` → `splice.ts`, for the single path function
+`mergedSpecPath`. So deferring it is not one thunk beside the existing two; it is
+`runInit` and its destination resolution leaving `pipeline.ts`, and
+`resolveOutFile`'s stated property — private to that module "rather than
+something a shell is trusted to call" — weakening to pay for it. A once-per-project
+command is not worth that.
+
+Worth reopening if either half of the arithmetic moves: a `typescript` whose AST
+surface can be imported without the checker (the `typescript/unstable/ast*` entry
+points `core/compiler.ts` already names, once they stop saying unstable), or a
+second command that needs none of it. `mergedSpecPath` sitting in the heavy
+module is independently worth fixing whether or not this is.
+
 ### Widening `status` to the rest of the gate's static half
 
 Scoped and decided on 2026-08-12, in the session that gave `status` its two
@@ -5693,24 +6035,27 @@ quotation of that snapshot and is only ever as fresh as the last edit here —
 read the snapshot when the number is what matters. *`compound-requirement`
 (WARNING) — rejected.* More than one RFC-2119 keyword in one `statement` is
 objectively more than one obligation. Measured (figures re-read from the suite,
-which is the only place they are not prose): of the 8 requirements in the corpus
-carrying more than one, it flags 3 (`ATX-10`, `ATX-21`, `ATX-26`) and misses
-`ATX-5`, `ATX-9`, `ATX-13`, `ATX-14`, `ATX-17` — every one that packs clauses
-under a single keyword, which is the form the coverage incentive actually
-rewards. A wider variant (keyword plus a coordinating `and`/`while`/`;`) reaches
-7 of 8, at 3 wrong hits (`ATX-6`, `ATX-22`, `ATX-23`) rather than the 1 recorded
-when it was first scored — so reach is not the deciding argument, and the
-precision it trades away grows with the registry. This is: both variants are
+which is the only place they are not prose): of the 34 requirements in the
+corpus carrying more than one, it flags 16 and misses 18 — every one of those 18
+packs clauses under a single keyword, which is the form the coverage incentive
+actually rewards. A wider variant (keyword plus a coordinating `and`/`while`/`;`)
+reaches 29 of 34, at 14 wrong hits rather than the 3 quoted here when the corpus
+was half this size and the 1 recorded when it was first scored — so reach is not
+the deciding argument, and the precision it trades away grows with the registry,
+which three successive re-readings of this paragraph have now measured rather
+than predicted. This is: both variants are
 silenced by deleting the word that triggered them, and neither can tell that
 deletion from a real split. `SHALL do A and MUST do B` clears the warning as
 `SHALL do A and do B` — same two obligations, one fewer normative keyword. A
 rule whose cheapest fix degrades the artifact it protects does not ship.
 *`divergent-param` (WARNING) — rejected.* One param name declared with different
-values in two requirements sharing an id prefix. Measured: it fires twice on
-this repo and both firings are wrong — `idleTimeoutMin` (`15` in `ATX-3`, `30`
-in `ATX-10`), unrelated illustrative fixtures, and `code` (`registry-not-static`
-in `ATX-17`, `empty-spec` in `ATX-18`, `rationale-placeholder` in `ATX-21`),
-diagnostics that could not possibly agree. The second arrived on its own when
+values in two requirements sharing an id prefix. Measured: it fires 5 times on
+this repo and **every firing is judged wrong** — `idleTimeoutMin` (`15` in
+`ATX-3`, `30` in `ATX-10`), unrelated illustrative fixtures, and `code`
+(`registry-not-static` in `ATX-17`, `empty-spec` in `ATX-18`,
+`rationale-placeholder` in `ATX-21`), diagnostics that could not possibly agree.
+That second group has since grown to span **19 ids**, and two more param names
+have joined it on the same structure (`flag`, `payloadKinds`). The second arrived on its own when
 `ATX-18` was added and grew a third member on its own again when `ATX-21` was,
 then `ATX-25`, then `ATX-26`, which is the more damning half: a generic param
 name collides more often as a registry grows, so the false-positive rate rises
@@ -5727,8 +6072,19 @@ firing. Until it appeared, every false positive had been on the single name
 workaround and therefore left the rule arguably salvageable. It is not the word:
 two requirements owning unrelated constants of the same *kind* is the structure,
 and any registry large enough to be worth linting has it. Still zero true
-positives, now across a 34-entry corpus (the `corpus` figure in the suite's
+positives, now across an 86-entry corpus (the `corpus` figure in the suite's
 snapshot, which counts a fixture id once per registry file that declares it).
+**Two failure modes have been measured since, and both are about the key rather
+than the threshold.** The grouping keeps one id per distinct value, so two
+requirements naming the *same* constant — the case a reader would most want
+compared — are the pair the key deduplicates away; that has now happened twice,
+most sharply on `ATX-18`/`ATX-77`, a pair split deliberately because each is
+falsifiable in a direction the other is blind to. And the key's *identity*
+moves when a requirement agreeing with an existing member is added, so a finding
+has to be re-judged by hand while nothing about it changed — three re-keyings
+across three releases under `flag` alone, none of which moved a verdict. A rule
+whose output churns on additions that agree with it is one whose maintenance
+cost is a function of registry growth, on top of the zero precision above.
 The escape hatch it was blocked on has since been designed and does not rescue
 it: with no config file the only workable shape is an additive
 `independentParams?: string[]` on the requirement (a CLI flag is per-invocation

package/README.md

@@ -167,7 +167,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.0/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.9.2/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section
@@ -180,6 +180,7 @@ isn't. In `--json` the same link is on each issue as `docsUrl`.
 | **CLI reference** — every command, flag and JSON field | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/cli-reference.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/cli-reference.md) |
 | **Troubleshooting** — one section per issue code | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/troubleshooting.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/troubleshooting.md) |
 | **Design** — the authoritative design of the framework | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/attest-design.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/attest-design.md) |
+| **Judging your own intent layer** — what no gate checks, and a method for it | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/intent-quality.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/intent-quality.md) |
 | **Feedback template** — report how adoption actually went | [en](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/feedback.template.md) | [中文](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/zh/feedback.template.md) |
 
 The change workflow is not here: it is what `attest init` writes into your

package/bin/attest.js

@@ -1,3 +1,44 @@
 #!/usr/bin/env node
 // Thin launcher: delegates to the built CLI shell (src/cli -> dist/cli).
-import '../dist/cli/index.js';
+//
+// **The compile cache is enabled here because here is the only place it can
+// be.** `typescript` is the fixed toll on every invocation: measured on this
+// machine, the CLI's whole dependency graph costs ~790 ms to load and the
+// compiler is ~672 ms of it, against ~28 ms for commander, ~17 ms for chalk and
+// ~70 ms for zod. Nothing can move that by loading it later, either — every
+// command except `init` reads a registry or a spec through the AST, so the
+// import is not merely eager, it is *needed*. What a code cache changes is the
+// price of the same load: V8 keeps its compilation output between runs, and the
+// saving lands on the commands a pipeline actually repeats. Measured over two
+// independent A/B rounds, nine interleaved runs each, median: **11% to 28% off
+// every command** — `check self` 1153 -> 970 and 1106 -> 971 ms, `cover self`
+// 1122 -> 951 and 1346 -> 1195 ms, `status` 1110 -> 923 ms, `init` 904 -> 711
+// and 1365 -> 984 ms. Quoted as a range because the absolute figures move with
+// whatever else the machine is doing; the direction did not, across either
+// round or any command in them.
+//
+// **The import below has to stay dynamic, and this is the whole reason.** A
+// static `import` is hoisted and its module graph is evaluated *before* any
+// statement in this file runs — so with one, the call above happens after
+// `typescript` has already been compiled and the cache does nothing at all. It
+// still returns success, and every command still works, so there is nothing to
+// notice: measured, the static spelling came back at 873 ms against an
+// unpatched 897 ms, i.e. inside the noise, while the dynamic one is 669 ms.
+// That is this repository's dominant failure shape — a defence that reads as
+// present and is not — arriving in a three-line file.
+//
+// Optional-chained because `engines` allows Node 20 and this API arrived in
+// 22.1: on an older runtime the speed-up is absent, which is the right
+// behaviour for an optimisation and not a reason to refuse to start. It never
+// throws either — a cache directory that cannot be written comes back as a
+// status this deliberately ignores, since the only thing a failure costs is the
+// saving above.
+//
+// The cache lands under the OS temp directory, never in the project: every
+// other file Attest writes is one the user commits (see `core/write.ts`), and
+// this is the one that must not be.
+import module from 'node:module';
+
+module.enableCompileCache?.();
+
+await import('../dist/cli/index.js');

package/dist/cli/report.js

@@ -250,10 +250,16 @@ export function formatCoverage(rows) {
         const detail = r.covered
             ? chalk.dim(`${r.scenarioCount} scenario${r.scenarioCount === 1 ? '' : 's'}`)
             : chalk.red('no scenario');
-        // Sanitised, even though a registry id has been through the schema's
-        // `^[A-Z]+-\d+$`: that is true of the *static* reader only. Under
-        // `--eval` the registry is whatever the module exported, and `evalReader`
-        // checks that it is an object and nothing further.
+        // Sanitised even though a registry id cannot carry a control character:
+        // `^[A-Z]+-\d+$` holds on both reader paths — the static one by
+        // construction, the evaluating one since ATX-38 — so this can never fire.
+        // It stays because the grammar is held somewhere else, and a defence that
+        // lapses when the other one does is not a defence; `CoverageRow.reqId` is
+        // a `string`, and this function is exported. Same standard as
+        // `splice.ts`'s `keySource`, and the reason it is not an inconsistency
+        // with `render.ts` deciding the opposite: that one states it need *not*
+        // sanitise ids, which is true, and builds its container prototype-free
+        // anyway for exactly this reason.
         return `  ${mark} ${chalk.bold(inline(r.reqId))}  ${detail}`;
     })
         .join('\n');

package/dist/core/locate.js

@@ -43,22 +43,27 @@ export const isSpecFile = (name) => name.endsWith('.spec.ts') && !isProposedSpec
 /**
  * Run `fn` over every item with at most `limit` of them in flight.
  *
- * Extracted at the second call site rather than the first: this file has two
- * unbounded fan-outs to close, one over directories and one over files, and
- * a shape written twice is a shape one of the two copies will eventually be
- * fixed without.
+ * 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. Both callers here do one of
- * those, deliberately.
+ * preallocated array by `index` or sorts afterwards. All three callers here do
+ * one of those, deliberately.
  *
- * No result is collected and none is needed — both callers write into something
- * they already own, and a version returning `T[]` would have to choose an
+ * 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 both sites: `parseSpecs` catches per file
- * so that one hostile spec scraps only itself (ATX-65), and a failed `readdir`
- * really does end the walk.
+ * 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.
  */
 async function forEachBounded(items, limit, fn) {
     let cursor = 0;
@@ -299,6 +304,14 @@ async function declaredIds(absPath) {
         return [];
     }
 }
+/**
+ * How many registry files are read at once. A third figure equal to the other
+ * two and, for the reason `WALK_CONCURRENCY` gives, a third constant: what this
+ * bounds is neither directories nor spec sources but whatever the *reader*
+ * holds — a source and a `SourceFile` under `staticReader`, a Vite SSR module
+ * evaluation under `evalReader` — and those are not tunable together.
+ */
+const REGISTRY_CONCURRENCY = 32;
 /**
  * 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
@@ -317,7 +330,16 @@ export async function loadRegistry(root, reader, files) {
     const paths = files ?? (await scanProject(root)).reqsFiles;
     // Read the files concurrently, then fold the results in sorted file order:
     // the issue list stays deterministic regardless of which one finished first.
-    const loaded = await Promise.all(paths.map(async (file) => ({ file, outcome: await readGuarded(reader, file) })));
+    //
+    // Indexed rather than appended, exactly as `parseSpecs` does it and for the
+    // same reason: `forEachBounded` *calls* in input order and *completes* in
+    // whatever order the reads finish, so the fold below is driven by position.
+    const outcomes = new Array(paths.length);
+    await forEachBounded(paths, REGISTRY_CONCURRENCY, async (file, i) => {
+        // `readGuarded` catches, so nothing here can throw and abandon the rest —
+        // which is the one thing the pool does not do for its caller.
+        outcomes[i] = await readGuarded(reader, file);
+    });
     const registry = {};
     const issues = [];
     const unreadable = [];
@@ -331,9 +353,10 @@ export async function loadRegistry(root, reader, files) {
     // have to turn a display path back into one; the messages below relativise at
     // the point they are built, which is where the reader's path belongs anyway.
     const prefixOwner = new Map();
-    for (const entry of loaded) {
-        const display = relativePath(root, entry.file);
-        const { outcome } = entry;
+    for (let i = 0; i < paths.length; i += 1) {
+        const file = paths[i];
+        const outcome = outcomes[i];
+        const display = relativePath(root, file);
         if ('issue' in outcome) {
             issues.push({ ...outcome.issue, file: display });
             // Read the source again for the ids alone. Both readers land here, and the
@@ -342,7 +365,7 @@ export async function loadRegistry(root, reader, files) {
             // 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) });
+            unreadable.push({ file: display, ids: await declaredIds(file) });
             continue;
         }
         // One issue per colliding prefix rather than per requirement: the fact is
@@ -353,9 +376,9 @@ export async function loadRegistry(root, reader, files) {
             const prefix = idPrefix(id);
             const owner = prefixOwner.get(prefix);
             if (owner === undefined) {
-                prefixOwner.set(prefix, entry.file);
+                prefixOwner.set(prefix, file);
             }
-            else if (owner !== entry.file && !reported.has(prefix)) {
+            else if (owner !== file && !reported.has(prefix)) {
                 reported.add(prefix);
                 // No `reqId`: this is about two files, not about any one of the
                 // requirements that happen to reveal it.

package/dist/core/splice.js

@@ -239,7 +239,7 @@ export function spliceModifications(file, source, changes) {
     // 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.
     for (const id of [...wanted.keys()].sort(byCodeUnit)) {
-        if (!layouts[id])
+        if (!layouts.has(id))
             refusals.push({ reqId: id, reason: 'entry-not-found' });
     }
     // **The file front to back, not the delta.** Driving the walk from the layout
@@ -250,7 +250,10 @@ export function spliceModifications(file, source, changes) {
     // bottom be a `reverse()` rather than a numeric sort, which ATX-15 does not
     // allow in `src/` and would be the wrong shape anyway — an ordering that holds
     // by construction beats one restored after the fact.
-    for (const [id, layout] of Object.entries(layouts)) {
+    // 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) {
         const change = wanted.get(id);
         if (!change)
             continue;
@@ -280,7 +283,7 @@ export function spliceModifications(file, source, changes) {
         const openField = (name, value) => {
             opened.push(`${layout.fieldInsertion.indent}${name}: ${value}`);
         };
-        for (const [name, span] of Object.entries(layout.fields)) {
+        for (const [name, span] of layout.fields) {
             if (name === 'statement' || name === 'rationale') {
                 if (before[name] !== after[name])
                     out.at(name, span, tsString(after[name]));
@@ -296,18 +299,18 @@ export function spliceModifications(file, source, changes) {
             // Any other field is one the schema does not define, and not this
             // module's to rewrite or to remove.
         }
-        if (!layout.fields['statement'] && before.statement !== after.statement) {
+        if (!layout.fields.has('statement') && before.statement !== after.statement) {
             openField('statement', tsString(after.statement));
         }
-        if (!layout.fields['rationale'] && before.rationale !== after.rationale) {
+        if (!layout.fields.has('rationale') && before.rationale !== after.rationale) {
             openField('rationale', tsString(after.rationale));
         }
-        if (!layout.fields['params']) {
+        if (!layout.fields.has('params')) {
             const fresh = freshParams(before, after);
             if (fresh.length > 0)
                 openField('params', `{ ${fresh.join(', ')} }`);
         }
-        if (!layout.fields['outOfScope'] && !sameValue(before.outOfScope, after.outOfScope)) {
+        if (!layout.fields.has('outOfScope') && !sameValue(before.outOfScope, after.outOfScope)) {
             openField('outOfScope', outOfScopeSource(after.outOfScope));
         }
         if (opened.length > 0) {
@@ -360,11 +363,11 @@ function editParams(layout, before, after, out) {
     // Named rather than skipped, so the guard does not depend on something
     // upstream holding.
     for (const key of Object.keys(before.params).sort(byCodeUnit)) {
-        if (!layout.paramKeys[key] && !sameValue(before.params[key], after.params[key])) {
+        if (!layout.paramKeys.has(key) && !sameValue(before.params[key], after.params[key])) {
             out.refuse(`params.${key}`, 'not-a-literal');
         }
     }
-    for (const [key, span] of Object.entries(layout.paramKeys)) {
+    for (const [key, span] of layout.paramKeys) {
         if (!Object.hasOwn(after.params, key))
             continue;
         const value = after.params[key];

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

@@ -123,10 +123,13 @@ export interface ValueSpan {
  * this hands back, so they cannot be written over by anything using it.
  */
 export interface RegistryEntryLayout {
-    /** Value span of each field the entry writes, by field name. */
-    fields: Record<string, ValueSpan>;
-    /** Value span of each key of `params`, when the entry writes one as a literal. */
-    paramKeys: Record<string, ValueSpan>;
+    /** Value span of each field the entry writes, by field name, in file order. */
+    fields: Map<string, ValueSpan>;
+    /**
+     * Value span of each key of `params`, when the entry writes one as a literal,
+     * in file order.
+     */
+    paramKeys: Map<string, ValueSpan>;
     /** Where a new `params` key goes — absent when the entry writes no `params`. */
     paramsInsertion?: RegistryInsertion;
     /** Where a new field goes, inside the entry's own body. */
@@ -141,6 +144,16 @@ export interface RegistryEntryLayout {
  * this cannot describe (a computed key, a value built by a call) are absent from
  * the result rather than partially described, which the caller reads as a
  * refusal for that id: an entry nothing can locate is not one to edit.
+ *
+ * **Maps at all three levels, because the iteration order is the contract.**
+ * `spliceModifications` walks this in file order to get its edits in ascending
+ * offset order, which is what lets it apply them with a `reverse()` rather than
+ * a sort. A plain object cannot carry that order: an *integer-like* key is
+ * hoisted to the front of every JavaScript object, and a `params` key can be
+ * one — `staticName` spells a numeric literal key as `String(value)`, and the
+ * 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.
  */
-export declare function registryEntryLayouts(file: string, source: string): Record<string, RegistryEntryLayout> | undefined;
+export declare function registryEntryLayouts(file: string, source: string): Map<string, RegistryEntryLayout> | undefined;
 //# sourceMappingURL=static-registry.d.ts.map

package/dist/core/static-registry.js

@@ -510,13 +510,23 @@ function objectInsertion(sf, source, obj) {
  * this cannot describe (a computed key, a value built by a call) are absent from
  * the result rather than partially described, which the caller reads as a
  * refusal for that id: an entry nothing can locate is not one to edit.
+ *
+ * **Maps at all three levels, because the iteration order is the contract.**
+ * `spliceModifications` walks this in file order to get its edits in ascending
+ * offset order, which is what lets it apply them with a `reverse()` rather than
+ * a sort. A plain object cannot carry that order: an *integer-like* key is
+ * hoisted to the front of every JavaScript object, and a `params` key can be
+ * one — `staticName` spells a numeric literal key as `String(value)`, and the
+ * 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.
  */
 export function registryEntryLayouts(file, source) {
     const found = registryLiteral(file, source);
     if (!found)
         return undefined;
     const { sf, literal } = found;
-    const layouts = {};
+    const layouts = new Map();
     for (const entry of literal.properties) {
         if (!ts.isPropertyAssignment(entry))
             continue;
@@ -526,8 +536,8 @@ export function registryEntryLayouts(file, source) {
         const body = unwrap(entry.initializer);
         if (!ts.isObjectLiteralExpression(body))
             continue;
-        const fields = {};
-        const paramKeys = {};
+        const fields = new Map();
+        const paramKeys = new Map();
         let params;
         for (const field of body.properties) {
             if (!ts.isPropertyAssignment(field))
@@ -538,7 +548,7 @@ export function registryEntryLayouts(file, source) {
             // 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);
-            fields[name] = { start: value.getStart(sf), end: value.getEnd() };
+            fields.set(name, { start: value.getStart(sf), end: value.getEnd() });
             if (name === 'params' && ts.isObjectLiteralExpression(value))
                 params = value;
         }
@@ -550,15 +560,15 @@ export function registryEntryLayouts(file, source) {
                 if (key === undefined || key === '__proto__')
                     continue;
                 const value = unwrap(param.initializer);
-                paramKeys[key] = { start: value.getStart(sf), end: value.getEnd() };
+                paramKeys.set(key, { start: value.getStart(sf), end: value.getEnd() });
             }
         }
-        layouts[id] = {
+        layouts.set(id, {
             fields,
             paramKeys,
             ...(params ? { paramsInsertion: objectInsertion(sf, source, params) } : {}),
             fieldInsertion: objectInsertion(sf, source, body),
-        };
+        });
     }
     return layouts;
 }

package/dist/inspect.d.ts

@@ -0,0 +1,54 @@
+import type { Issue, ParsedScenario, Registry } from './core/types.js';
+export type { Issue, ParsedScenario, Registry, Requirement } from './core/types.js';
+/** What a project declares, read without executing any of it. */
+export interface Inspection {
+    /**
+     * Every requirement declared under the root, merged across registry files.
+     *
+     * A registry file that could not be read statically contributes nothing here
+     * and one entry to {@link Inspection.issues} — so an empty result never means
+     * "this project has no requirements" without the issues saying why.
+     */
+    readonly registry: Registry;
+    /**
+     * The scenarios each requirement id has, in declaration order.
+     *
+     * A `Map` rather than a record, and not only for the key type: a record keyed
+     * by ids from a file on disk is the `Object.prototype` hazard ATX-42 exists
+     * for, and a `Map` has no prototype chain to read a requirement out of. The
+     * cost is that `JSON.stringify` renders it as `{}` — a caller serialising
+     * this owes `Object.fromEntries`, and the type is a `Map` so that the
+     * conversion is a decision rather than a surprise.
+     *
+     * An id with no scenarios is absent rather than present-and-empty — the same
+     * distinction `cover` reports, and the one a coverage check is asking about.
+     */
+    readonly scenarios: ReadonlyMap<string, readonly ParsedScenario[]>;
+    /**
+     * Everything that stopped a *file* being read, in the shape every command
+     * reports: one unreadable file scraps itself and nothing else (ATX-65), which
+     * is what lets a caller report on the rest of the project.
+     *
+     * Not a promise that nothing throws. A root that cannot be walked at all is a
+     * caller's mistake rather than a finding about a project, and rejects.
+     */
+    readonly issues: readonly Issue[];
+}
+/**
+ * Read the requirements and scenarios declared under `root`, executing nothing.
+ *
+ * `root` is the project directory, resolved here so a relative one behaves the
+ * same as an absolute one rather than half-working: the walk would find the
+ * files either way, and only the relative paths in the result would be wrong,
+ * which is the shape of bug that survives a demo.
+ *
+ * Every `file` in the result is relative to that root and POSIX-spelled on
+ * every platform (`paths.ts`) — the spelling a caller can compare against and
+ * store, on a value that would otherwise carry the host's separator.
+ *
+ * The registry read and the spec parse are independent, so they run
+ * concurrently — each already bounds its own fan-out over a tree whose size is
+ * not ours to choose.
+ */
+export declare function inspectProject(root: string): Promise<Inspection>;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/inspect.js

@@ -0,0 +1,68 @@
+// The static reading layer, as a second public entry point (design §10).
+//
+// Why it exists: everything this repository knows about the quality of its own
+// requirements is a hand-judged table in `tests/intent-rule-candidates.spec.ts`,
+// and the check that keeps such a table from rotting is "the scenario this row
+// names is one a spec really declares". An adopter could not write that check.
+// The package exported the authoring API and nothing else, so the ids, the
+// statements and above all the *scenario names* of their own project were
+// unreachable from outside — not merely undocumented, unreachable. That is what
+// this entry point answers, and the deliberate limit is that it answers only
+// that: it reports what a project declares, and judges none of it (design §0).
+//
+// **One function rather than the four internals it composes**, and the reason is
+// a security property rather than convenience. `loadRegistry` takes a
+// `RegistryReader`, and which reader runs is fixed by the command — never chosen
+// by a caller, never a fallback — because one of the two executes the project's
+// code and the other does not (design §5.1). Exporting the readers would hand
+// that choice to an adopter, which is the one thing the two-adapter seam must
+// never allow. What is exported therefore has the static reader welded in, and
+// there is no parameter that could change it.
+//
+// The same rule decides the import graph: nothing here may reach `vite` or
+// `vitest`, so a consumer that only analyses does not acquire the runner peer.
+// `tests/import-boundary.spec.ts` gates that rather than leaving it to review —
+// this module is on the short list of entry points whose closure is walked.
+import { resolve } from 'node:path';
+import { loadRegistry, parseSpecs, scanProject, staticReader } from './core/locate.js';
+/**
+ * Read the requirements and scenarios declared under `root`, executing nothing.
+ *
+ * `root` is the project directory, resolved here so a relative one behaves the
+ * same as an absolute one rather than half-working: the walk would find the
+ * files either way, and only the relative paths in the result would be wrong,
+ * which is the shape of bug that survives a demo.
+ *
+ * Every `file` in the result is relative to that root and POSIX-spelled on
+ * every platform (`paths.ts`) — the spelling a caller can compare against and
+ * store, on a value that would otherwise carry the host's separator.
+ *
+ * The registry read and the spec parse are independent, so they run
+ * concurrently — each already bounds its own fan-out over a tree whose size is
+ * not ours to choose.
+ */
+export async function inspectProject(root) {
+    const projectRoot = resolve(root);
+    const { reqsFiles, specFiles } = await scanProject(projectRoot);
+    const [loaded, parsed] = await Promise.all([
+        loadRegistry(projectRoot, staticReader(), reqsFiles),
+        parseSpecs(specFiles, projectRoot),
+    ]);
+    const scenarios = new Map();
+    for (const scenario of parsed.plan.scenarios) {
+        const existing = scenarios.get(scenario.reqId);
+        if (existing === undefined)
+            scenarios.set(scenario.reqId, [scenario]);
+        else
+            existing.push(scenario);
+    }
+    return {
+        registry: loaded.registry,
+        scenarios,
+        // Registry issues before spec issues, and each already in sorted file
+        // order: the list is a function of the project rather than of which read
+        // finished first, so two runs over one tree answer identically.
+        issues: [...loaded.issues, ...parsed.issues],
+    };
+}
+//# sourceMappingURL=inspect.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "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": {
@@ -25,7 +25,12 @@
     "./define": {
       "types": "./dist/core/registry.d.ts",
       "default": "./dist/core/registry.js"
-    }
+    },
+    "./inspect": {
+      "types": "./dist/inspect.d.ts",
+      "default": "./dist/inspect.js"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",