@am_shork/attest 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -13,6 +13,143 @@ 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.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
@@ -5251,6 +5388,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

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.1/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section

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/package.json

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