@am_shork/attest 0.7.4 → 0.8.0

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

package/dist/cli/index.js

@@ -13,7 +13,6 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { resolve } from 'node:path';
-import { writeAtomic } from '../core/write.js';
 import { runCheck, runVerify, runCover, runArchive, runArchiveApply, runInit, runRender, runRenderCheck, runStatus, DEFAULT_TARGET, TARGET_NAMES, } from '../core/pipeline.js';
 import { hasError } from '../core/types.js';
 // The one project-derived value this shell still interpolates itself. `--out`
@@ -135,12 +134,16 @@ program
     if (opts.json && !opts.out && !opts.check) {
         cmd.error('error: --json requires --out <file> (stdout cannot carry both the document and the report)');
     }
-    const dest = opts.out ? resolve(process.cwd(), opts.out) : undefined;
+    // Both spellings of the destination, because both are needed downstream: the
+    // resolved one is what the filesystem is given, the typed one is what a
+    // diagnostic echoes. Where it may point, and the write itself, are the
+    // pipeline's — this shell decides what to print and nothing else.
+    const out = opts.out ? { file: resolve(process.cwd(), opts.out), display: opts.out } : undefined;
     return runAction('render', opts, async () => {
         if (opts.check) {
             // The fix hint has to be the command the user can actually re-run from
             // here: their own --out string, and the [dir] they passed.
-            const issues = await runRenderCheck(root(dir), dest, {
+            const issues = await runRenderCheck(root(dir), out.file, {
                 display: opts.out,
                 command: `attest render${dir ? ` ${dir}` : ''} --out ${opts.out}`,
             }, { evaluate: opts.eval });
@@ -156,10 +159,10 @@ program
                 },
             };
         }
-        const { markdown, issues } = await runRender(root(dir), { evaluate: opts.eval });
-        // Never overwrite a good document with the output of a broken registry.
-        if (!hasError(issues) && dest)
-            await writeAtomic(dest, markdown);
+        const { markdown, issues, wrote } = await runRender(root(dir), {
+            evaluate: opts.eval,
+            out,
+        });
         return {
             report: renderReport(VERSION, issues, opts.out),
             human: () => {
@@ -167,7 +170,7 @@ program
                     console.log(formatIssues(issues));
                     console.log(summarize(issues));
                 }
-                else if (dest) {
+                else if (wrote) {
                     console.log(chalk.green(`✓ Wrote ${inline(opts.out ?? '')}`));
                 }
                 else {

package/dist/cli/json.d.ts

@@ -100,6 +100,31 @@ export declare function statusReport(version: string, result: StatusResult): Jso
  * empty stdout and a stack trace on stderr.
  */
 export declare function errorReport(version: string, command: JsonCommand, err: unknown): JsonReport;
-/** Serialize a report for stdout. Pretty-printed: still one parseable document. */
+/**
+ * Serialize a report for stdout. Pretty-printed: still one parseable document.
+ *
+ * Every string in it loses its control characters first (design §9.1). The
+ * machine surface was recorded as exempt because `JSON.stringify` escapes every
+ * C0 character — true, and narrower than the rule: §9.1's class also holds DEL
+ * and the C1 range, and `JSON.stringify` emits those verbatim. `U+009B` is
+ * 8-bit CSI, the same introducer as `ESC [` on a terminal that reads
+ * UTF-8-decoded C1 as control — so a scenario name or a thrown message can
+ * drive the terminal of someone reading the JSON rather than parsing it, from
+ * `check --json`, which executes nothing.
+ *
+ * Applied here rather than at the report builders, and that is §9.1's own
+ * distinction rather than a preference: this is a *document*, not a stream. It
+ * has one point of assembly, before any of it is seen, so an obligation sitting
+ * there covers a field nobody has added yet — as `outFiles` and `docsUrl` both
+ * were. The terminal path is sanitised at each write site for the opposite
+ * reason, recorded in core/terminal.ts.
+ *
+ * A replacer rather than a walk over the fields that carry project text —
+ * `issues[].message`, `issues[].file`, `change`, `outFile`, `outFiles` today —
+ * because enumerating them is the arrangement that leaves the next one out. It
+ * costs nothing on the fields that cannot carry a control character: `control`
+ * allocates when something matches, and nothing does. Non-mutating, because a
+ * caller may render the same report for a human afterwards.
+ */
 export declare function renderJson(report: JsonReport): string;
 //# sourceMappingURL=json.d.ts.map

package/dist/cli/json.js

@@ -6,6 +6,7 @@
 // and every command emits the same envelope (tool/version/command/ok/summary/
 // issues) plus command-specific fields.
 import { docsUrl } from '../core/docs.js';
+import { control } from '../core/terminal.js';
 import { hasError } from '../core/types.js';
 /** Bumped whenever the emitted shape changes incompatibly. */
 export const SCHEMA_VERSION = 1;
@@ -156,8 +157,33 @@ export function errorReport(version, command, err) {
     const issue = { level: 'ERROR', code: 'internal-error', message };
     return envelope({ version, command, ok: false, issues: [issue] });
 }
-/** Serialize a report for stdout. Pretty-printed: still one parseable document. */
+/**
+ * Serialize a report for stdout. Pretty-printed: still one parseable document.
+ *
+ * Every string in it loses its control characters first (design §9.1). The
+ * machine surface was recorded as exempt because `JSON.stringify` escapes every
+ * C0 character — true, and narrower than the rule: §9.1's class also holds DEL
+ * and the C1 range, and `JSON.stringify` emits those verbatim. `U+009B` is
+ * 8-bit CSI, the same introducer as `ESC [` on a terminal that reads
+ * UTF-8-decoded C1 as control — so a scenario name or a thrown message can
+ * drive the terminal of someone reading the JSON rather than parsing it, from
+ * `check --json`, which executes nothing.
+ *
+ * Applied here rather than at the report builders, and that is §9.1's own
+ * distinction rather than a preference: this is a *document*, not a stream. It
+ * has one point of assembly, before any of it is seen, so an obligation sitting
+ * there covers a field nobody has added yet — as `outFiles` and `docsUrl` both
+ * were. The terminal path is sanitised at each write site for the opposite
+ * reason, recorded in core/terminal.ts.
+ *
+ * A replacer rather than a walk over the fields that carry project text —
+ * `issues[].message`, `issues[].file`, `change`, `outFile`, `outFiles` today —
+ * because enumerating them is the arrangement that leaves the next one out. It
+ * costs nothing on the fields that cannot carry a control character: `control`
+ * allocates when something matches, and nothing does. Non-mutating, because a
+ * caller may render the same report for a human afterwards.
+ */
 export function renderJson(report) {
-    return JSON.stringify(report, null, 2);
+    return JSON.stringify(report, (_key, value) => (typeof value === 'string' ? control(value) : value), 2);
 }
 //# sourceMappingURL=json.js.map

package/dist/core/gate.js

@@ -16,7 +16,7 @@ import { RED_RECORD_FILE, hasRecordedRed, recordedOutcome, } from './red-record.
 export function declaredNotRunIssues(plan, run) {
     const issues = [];
     for (const s of plan.scenarios) {
-        if (!run.runtimeCoverage.get(s.reqId)?.has(s.name)) {
+        if (!run.runtimeCoverage.get(s.reqId)?.get(s.file)?.has(s.name)) {
             issues.push({
                 level: 'ERROR',
                 code: 'declared-not-run',
@@ -155,9 +155,9 @@ export function neverRedIssues(plan, addedIds, firstRun) {
     for (const s of plan.scenarios) {
         if (!added.has(s.reqId))
             continue;
-        if (hasRecordedRed(firstRun, s.reqId, s.name))
+        if (hasRecordedRed(firstRun, s))
             continue;
-        const outcome = recordedOutcome(firstRun, s.reqId, s.name);
+        const outcome = recordedOutcome(firstRun, s);
         issues.push({
             level: 'ERROR',
             code: 'never-red',

package/dist/core/locate.js

@@ -5,7 +5,7 @@ import { basename, join } from 'node:path';
 import { relativePath } from './paths.js';
 import { parseSpecFile } from './parser.js';
 import { declaredIdsFromSource, readRegistrySource } from './static-registry.js';
-import { RegistryValidationError } from './registry.js';
+import { registryValidationMessage } from './registry-issues.js';
 import { RegistrySchema } from './schema.js';
 import { byCodeUnit } from './order.js';
 import { SourceNotCompiled } from './compiler.js';
@@ -191,13 +191,13 @@ export function evalReader(loader) {
             const parsed = RegistrySchema.safeParse(exported);
             if (!parsed.success) {
                 // The same code, the same prefix and the same rendering of the field
-                // errors as `readRegistrySource` — going through RegistryValidationError
-                // keeps the message identical rather than merely similar.
+                // errors as `readRegistrySource` — sharing one formatter keeps the
+                // message identical rather than merely similar.
                 return {
                     issue: {
                         level: 'ERROR',
                         code: 'registry-invalid',
-                        message: `Failed to load registry: ${new RegistryValidationError(parsed.error.issues).message}`,
+                        message: `Failed to load registry: ${registryValidationMessage(parsed.error.issues)}`,
                     },
                 };
             }

package/dist/core/pipeline.d.ts

@@ -81,6 +81,20 @@ export interface RenderResult {
     markdown: string;
     /** Registry-loading issues — rendering a half-loaded registry would lie. */
     issues: Issue[];
+    /** Whether the document reached `out.file`. False whenever `out` is absent. */
+    wrote: boolean;
+}
+/**
+ * A destination `render` was asked to write, as the two spellings it needs.
+ *
+ * `file` is resolved against the caller's working directory and is what the
+ * filesystem is given; `display` is the string the user typed, and is what a
+ * diagnostic has to echo so the path in the report is the path they can act on.
+ * They travel together because a destination is not usable without both.
+ */
+export interface RenderOut {
+    file: string;
+    display: string;
 }
 /**
  * Markdown projection of the intent layer (design §9: `attest render`).
@@ -90,7 +104,9 @@ export interface RenderResult {
  * `*.reqs.ts` files, so a committed rendering can be gated without going stale
  * every time a line moves in a test file.
  */
-export declare function runRender(root: string, options?: ReadOptions): Promise<RenderResult>;
+export declare function runRender(root: string, options?: ReadOptions & {
+    out?: RenderOut | undefined;
+}): Promise<RenderResult>;
 /**
  * Freshness gate for a committed rendering (`attest render --check`).
  *

package/dist/core/pipeline.js

@@ -14,7 +14,7 @@ import { writeAtomic } from './write.js';
 import { applyMerge, mergedSpecPath } from './merge.js';
 import { compilerIssue } from './compiler.js';
 import { mkdir, readFile, realpath } from 'node:fs/promises';
-import { basename, dirname, join } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { isInside, relativePath } from './paths.js';
 import { hasError } from './types.js';
 // The runner half of the engine, reached only when a command actually needs it.
@@ -405,15 +405,38 @@ export async function runCover(root, options = {}) {
  * every time a line moves in a test file.
  */
 export async function runRender(root, options = {}) {
+    // The compiler guard stays the first statement, as it is in every other entry
+    // point (ATX-56): a TypeScript with no AST API is a refusal about the
+    // toolchain, and it outranks anything this run could say about the caller's
+    // paths or registry.
     const unusable = compilerIssue();
     if (unusable)
-        return { markdown: '', issues: [unusable] };
+        return { markdown: '', issues: [unusable], wrote: false };
+    // Then the destination, before the registry is read, so a refused path is the
+    // only thing reported: a run that cannot write anywhere has no reason to also
+    // tell the user about their registry, and the report a pipeline reads should
+    // name the one thing that has to change.
+    const dest = options.out ? await resolveOutFile(root, options.out) : undefined;
+    if (dest && !dest.ok)
+        return { markdown: '', issues: [dest.issue], wrote: false };
     const { registry, issues } = await readRegistry(root, options);
     // A registry that failed to load yields a document that silently omits
-    // requirements. An incomplete spec doc is worse than none, so refuse.
+    // requirements. An incomplete spec doc is worse than none, so refuse — and
+    // since the write is below this line, refusing is also what keeps a broken
+    // registry from overwriting a good committed document.
     if (hasError(issues))
-        return { markdown: '', issues };
-    return { markdown: renderMarkdown(registry), issues };
+        return { markdown: '', issues, wrote: false };
+    const markdown = renderMarkdown(registry);
+    // The write lives here rather than in the CLI, and that is the whole of what
+    // ATX-73 is structurally about: while it sat in the shell it was the one
+    // `writeAtomic` call outside this layer, and it reached the filesystem
+    // without the resolution `runInit` had performed since ATX-66. Resolving and
+    // writing in one function is what stops the two from coming apart again —
+    // a later caller cannot forget a step it never had to take.
+    if (!dest)
+        return { markdown, issues, wrote: false };
+    await writeAtomic(dest.dest, markdown);
+    return { markdown, issues, wrote: true };
 }
 /**
  * Freshness gate for a committed rendering (`attest render --check`).
@@ -423,10 +446,29 @@ export async function runRender(root, options = {}) {
  * alongside a gate that fails when the file no longer matches its source.
  */
 export async function runRenderCheck(root, outFile, target, options = {}) {
+    // Called here despite the delegation further down, because the resolution
+    // below it runs first: the guard has to be the first statement of an entry
+    // point (ATX-56), and delegation cannot supply that once anything precedes
+    // it. Same precedence in both, for the reason `runRender` states.
+    const unusable = compilerIssue();
+    if (unusable)
+        return [unusable];
+    // Resolved before it is read, not only before it is written. A link along the
+    // path makes this compare a fresh document against a file outside the project
+    // — and both verdicts that can produce are ones the gate reports normally, so
+    // the wrong answer is indistinguishable from a right one.
+    //
+    // `target` already carries the spelling a diagnostic must echo, so the pair
+    // `resolveOutFile` wants is assembled here rather than asked of the caller:
+    // taking a `RenderOut` beside a `RenderTarget` would make the shell pass the
+    // same string twice, which is a clump waiting to disagree with itself.
+    const dest = await resolveOutFile(root, { file: outFile, display: target.display });
+    if (!dest.ok)
+        return [dest.issue];
     const { markdown, issues } = await runRender(root, options);
     if (hasError(issues))
         return issues;
-    const current = await readFile(outFile, 'utf8').catch(() => undefined);
+    const current = await readFile(dest.dest, 'utf8').catch(() => undefined);
     const stale = staleIssue(target, current, markdown);
     return stale ? [...issues, stale] : issues;
 }
@@ -467,12 +509,7 @@ export async function runInit(root, names) {
             writes.push({ target, dest: resolved.dest });
         }
         else {
-            refusals.push({
-                level: 'ERROR',
-                code: 'unsafe-target-path',
-                file: target.file,
-                message: `Refusing to write ${target.file}: it resolves to ${resolved.escape}, outside the project. Remove the link at that path and re-run.`,
-            });
+            refusals.push(unsafeTargetPathIssue(target.file, resolved.escape));
         }
     }
     if (refusals.length > 0)
@@ -485,6 +522,61 @@ export async function runInit(root, names) {
     }
     return { files, issues };
 }
+/**
+ * Where a `render` destination really lands, or the refusal that a link
+ * redirected it (design §9: ownership of the path is checked, and who named the
+ * path decides what the refusal is about).
+ *
+ * `init` names its own destinations, so every one of them is checked; `--out`
+ * is the caller's path, and that is the whole of the difference between the two
+ * callers. A path spelled outside the project is the user asking for a file
+ * outside the project — `--out ../site/SPEC.md` is a destination, not an
+ * escape, and refusing it would be refusing the flag. What is not visible in
+ * the argument is a *link* along a path that reads as staying inside, which is
+ * the one a checkout can plant: the victim's `--out` is the string their README
+ * or CI already documents, and the content redirected is the document their
+ * repository wrote.
+ *
+ * So the check applies exactly when the destination is lexically inside the
+ * root, and it is `resolveDest`'s, unchanged. The leaf needs no separate
+ * defence and never did — `writeAtomic` lands by `rename`, which replaces a
+ * symlink rather than following it — but it is resolved with the rest anyway,
+ * because a link there is still a file the user made deliberately and this
+ * refuses rather than destroys it.
+ *
+ * Both entry points that name a destination come through here — the one that
+ * writes it and the one that reads it back to date it — which is why this is
+ * private to this module rather than something a shell is trusted to call.
+ */
+async function resolveOutFile(root, out) {
+    const dest = resolve(out.file);
+    const realRoot = await realpath(root).catch(() => root);
+    // Asked against both spellings of the root, because they differ whenever the
+    // project itself sits under a link: `dest` is built from the caller's cwd, so
+    // it is lexical, and testing only the resolved root would skip the check for
+    // every such checkout — failing open on exactly the layout that has links in
+    // it. `''` is the root itself, which is a directory and not a destination.
+    const rel = isInside(root, dest)
+        ? relativePath(root, dest)
+        : isInside(realRoot, dest)
+            ? relativePath(realRoot, dest)
+            : undefined;
+    if (rel === undefined || rel === '')
+        return { ok: true, dest };
+    const resolved = await resolveDest(realRoot, rel);
+    return resolved.ok
+        ? { ok: true, dest: resolved.dest }
+        : { ok: false, issue: unsafeTargetPathIssue(out.display, resolved.escape) };
+}
+/** The one refusal both destination checks report (design §9). */
+function unsafeTargetPathIssue(display, escape) {
+    return {
+        level: 'ERROR',
+        code: 'unsafe-target-path',
+        file: display,
+        message: `Refusing to write ${display}: it resolves to ${escape}, outside the project. Remove the link at that path and re-run.`,
+    };
+}
 /**
  * Where a target's file really goes, or the path outside the project that
  * asking put it at (design §9: ownership of the path is checked, not assumed).

package/dist/core/red-record.d.ts

@@ -1,17 +1,26 @@
-import type { AttestPlan, Outcome, RunResult } from './types.js';
+import type { AttestPlan, Outcome, RunResult, ScenarioRef } from './types.js';
 /** Where the record lives, relative to the project root. */
 export declare function redRecordPath(root: string, changeName: string): string;
 /** The file name, exported so a diagnostic can name it without rebuilding it. */
 export declare const RED_RECORD_FILE = "first-run.json";
 /**
- * reqId -> scenario name -> the outcome of its first observed run.
+ * reqId -> spec file -> scenario name -> the outcome of its first observed run.
  *
  * Deliberately not a list of "red scenarios": a scenario whose first run passed
  * is the case mechanism 2 exists to catch, so it has to be recorded as a fact
  * rather than as an absence. An absence then means only one thing — never
  * observed at all — and the gate can report the two separately.
+ *
+ * **The file level is what identifies a scenario, and it was missing.** A
+ * scenario is `(reqId, file, name)` in the static plan and was `(reqId, name)`
+ * here, so two spec files declaring the same name under one added requirement
+ * shared an entry — and because the record is monotonic toward `fail`, one of
+ * them going red satisfied the other's first-red obligation. Nested rather than
+ * a composite key string, so no separator has to be chosen that a path or a
+ * scenario name could contain, and so the committed file stays something a
+ * reviewer reads (design §6).
  */
-export type RedRecord = Record<string, Record<string, Outcome>>;
+export type RedRecord = Record<string, Record<string, Record<string, Outcome>>>;
 /**
  * Read the record for a change. A missing or unreadable file is an empty
  * record, never an error: the first stage-1 run legitimately finds nothing, and
@@ -34,7 +43,7 @@ export declare function readRedRecord(root: string, changeName: string): Promise
  * what it must not do is answer from an inherited key whoever constructed the
  * object it was handed. `record[reqId]?.[scenario]` did exactly that.
  */
-export declare function recordedOutcome(record: RedRecord, reqId: string, scenario: string): Outcome | undefined;
+export declare function recordedOutcome(record: RedRecord, ref: ScenarioRef): Outcome | undefined;
 /**
  * Whether this scenario has satisfied the first-red obligation (design §6).
  *
@@ -44,7 +53,7 @@ export declare function recordedOutcome(record: RedRecord, reqId: string, scenar
  * apart — the same argument that extracted `declaredNotRunIssues` and
  * `uncoveredIssues` from the commands that had a copy each.
  */
-export declare function hasRecordedRed(record: RedRecord, reqId: string, scenario: string): boolean;
+export declare function hasRecordedRed(record: RedRecord, ref: ScenarioRef): boolean;
 /**
  * Fold this run's outcomes into the record, for the scenarios that carry an
  * obligation — those covering a requirement this change ADDs.

package/dist/core/red-record.js

@@ -47,6 +47,32 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { z } from 'zod';
 import { byCodeUnit } from './order.js';
+import { mergedSpecPath } from './merge.js';
+import { toPosixPath } from './paths.js';
+/**
+ * The file half of a scenario's identity, as this record spells it.
+ *
+ * A scenario is `(reqId, file, name)` — but the one file this record is about
+ * is a **proposed** spec, and `--apply` renames it in place as step 2 of the
+ * merge. Keyed by the name on disk, a resume after that rename looked up
+ * `app2.spec.ts` in a record written under `app2.proposed.spec.ts`, found
+ * nothing, and blocked a change whose scenarios had been observed red — the
+ * gate refusing its own evidence. Rewriting the record beside the rename was
+ * the alternative and is worse: two files that must move together, in a design
+ * whose whole resume story is that each step is separately idempotent.
+ *
+ * So the key is the **merged** spelling from the start, which the rename cannot
+ * move. It still separates two spec files, which is the collapse this key
+ * exists to prevent; what it deliberately does not separate is one file from
+ * its own proposed name, because those are the same file.
+ *
+ * Through `toPosixPath` because `mergedSpecPath` rebuilds the path with
+ * `node:path`, which on Windows hands back a backslash — and this is a
+ * comparison key against a plan built on POSIX separators (`paths.ts`).
+ */
+function fileKey(file) {
+    return toPosixPath(mergedSpecPath(file));
+}
 /**
  * **The record is a map, so it is built without a prototype.**
  *
@@ -92,7 +118,7 @@ export const RED_RECORD_FILE = 'first-run.json';
  * The gate was never at risk — `hasRecordedRed` compares against `'fail'`, so an
  * unrecognised value blocks exactly like a missing one. This closes the report.
  */
-const RedRecordSchema = z.record(z.string(), z.record(z.string(), z.enum(['pass', 'fail'])));
+const RedRecordSchema = z.record(z.string(), z.record(z.string(), z.record(z.string(), z.enum(['pass', 'fail']))));
 /**
  * Read the record for a change. A missing or unreadable file is an empty
  * record, never an error: the first stage-1 run legitimately finds nothing, and
@@ -122,8 +148,15 @@ export async function readRedRecord(root, changeName) {
     }
     // `JSON.parse` yields `any`; nothing about the file is known until the schema
     // says so, including whether it is an object at all (`JSON.parse('null')`).
-    const firstRun = isRecord(parsed) ? parsed['firstRun'] : undefined;
-    const result = RedRecordSchema.safeParse(firstRun);
+    // The version is checked rather than inferred from whether the shape happens
+    // to parse. A version-1 record keyed `reqId -> name` would fail the schema
+    // anyway and be discarded whole, which is the safe direction — but "discarded
+    // because the format moved" and "discarded because the file is corrupt" are
+    // different facts, and reading one as the other is how a format change gets
+    // made without anyone deciding to make it.
+    if (!isRecord(parsed) || parsed['version'] !== 2)
+        return emptyMap();
+    const result = RedRecordSchema.safeParse(parsed['firstRun']);
     return result.success ? adopt(result.data) : emptyMap();
 }
 /**
@@ -139,8 +172,16 @@ export async function readRedRecord(root, changeName) {
  */
 function adopt(parsed) {
     const record = emptyMap();
-    for (const [id, outcomes] of Object.entries(parsed)) {
-        record[id] = Object.assign(emptyMap(), outcomes);
+    for (const [id, byFile] of Object.entries(parsed)) {
+        const files = emptyMap();
+        // Every level, not just the two that existed before: the file level is as
+        // much a key taken from a string this module did not choose as the other
+        // two, and a container with a prototype is what the whole comment above is
+        // about.
+        for (const [file, outcomes] of Object.entries(byFile)) {
+            files[file] = Object.assign(emptyMap(), outcomes);
+        }
+        record[id] = files;
     }
     return record;
 }
@@ -153,13 +194,17 @@ function adopt(parsed) {
  * what it must not do is answer from an inherited key whoever constructed the
  * object it was handed. `record[reqId]?.[scenario]` did exactly that.
  */
-export function recordedOutcome(record, reqId, scenario) {
-    if (!Object.hasOwn(record, reqId))
+export function recordedOutcome(record, ref) {
+    if (!Object.hasOwn(record, ref.reqId))
         return undefined;
-    const outcomes = record[reqId];
-    if (outcomes === undefined || !Object.hasOwn(outcomes, scenario))
+    const byFile = record[ref.reqId];
+    const key = fileKey(ref.file);
+    if (byFile === undefined || !Object.hasOwn(byFile, key))
         return undefined;
-    return outcomes[scenario];
+    const outcomes = byFile[key];
+    if (outcomes === undefined || !Object.hasOwn(outcomes, ref.name))
+        return undefined;
+    return outcomes[ref.name];
 }
 /**
  * Whether this scenario has satisfied the first-red obligation (design §6).
@@ -170,8 +215,8 @@ export function recordedOutcome(record, reqId, scenario) {
  * apart — the same argument that extracted `declaredNotRunIssues` and
  * `uncoveredIssues` from the commands that had a copy each.
  */
-export function hasRecordedRed(record, reqId, scenario) {
-    return recordedOutcome(record, reqId, scenario) === 'fail';
+export function hasRecordedRed(record, ref) {
+    return recordedOutcome(record, ref) === 'fail';
 }
 /**
  * Fold this run's outcomes into the record, for the scenarios that carry an
@@ -190,42 +235,55 @@ export function mergeRedRecord(existing, plan, run, addedIds) {
     // machines write byte-identical files (the same reason `render` orders ids
     // through one code-unit comparator).
     for (const id of Object.keys(existing).sort(byCodeUnit)) {
-        const outcomes = existing[id];
-        if (outcomes === undefined)
+        const byFile = existing[id];
+        if (byFile === undefined)
             continue;
-        record[id] = Object.assign(emptyMap(), outcomes);
+        const files = emptyMap();
+        for (const file of Object.keys(byFile).sort(byCodeUnit)) {
+            const outcomes = byFile[file];
+            if (outcomes === undefined)
+                continue;
+            files[file] = Object.assign(emptyMap(), outcomes);
+        }
+        record[id] = files;
     }
     let changed = false;
     for (const s of plan.scenarios) {
         if (!added.has(s.reqId))
             continue;
-        const outcome = run.outcomes.get(s.reqId)?.get(s.name);
+        const outcome = run.outcomes.get(s.reqId)?.get(s.file)?.get(s.name);
         // No outcome means the scenario did not execute. That is `declared-not-run`,
         // reported by the gate on its own terms; writing nothing here leaves the
         // obligation unobserved rather than inventing a state for it.
         if (!outcome)
             continue;
         const forId = (record[s.reqId] ??= emptyMap());
+        const forFile = (forId[fileKey(s.file)] ??= emptyMap());
         // Monotonic toward `fail`: a recorded fail is final, a recorded pass can
         // still be corrected by a real one. See the note at the top of this file.
-        if (forId[s.name] === 'fail' || forId[s.name] === outcome)
+        if (forFile[s.name] === 'fail' || forFile[s.name] === outcome)
             continue;
-        forId[s.name] = outcome;
+        forFile[s.name] = outcome;
         changed = true;
     }
-    // Sort within each requirement for the same byte-stability reason.
+    // Sort within each requirement, and within each file, for the same
+    // byte-stability reason.
     for (const id of Object.keys(record)) {
-        const sorted = emptyMap();
-        for (const name of Object.keys(record[id]).sort(byCodeUnit)) {
-            sorted[name] = record[id][name];
+        const sortedFiles = emptyMap();
+        for (const file of Object.keys(record[id]).sort(byCodeUnit)) {
+            const sorted = emptyMap();
+            for (const name of Object.keys(record[id][file]).sort(byCodeUnit)) {
+                sorted[name] = record[id][file][name];
+            }
+            sortedFiles[file] = sorted;
         }
-        record[id] = sorted;
+        record[id] = sortedFiles;
     }
     return { record, changed };
 }
 /** Serialise the record. A trailing newline, so the file is a well-formed text file. */
 export function serialiseRedRecord(changeName, record) {
-    const file = { version: 1, change: changeName, firstRun: record };
+    const file = { version: 2, change: changeName, firstRun: record };
     return `${JSON.stringify(file, null, 2)}\n`;
 }
 /** Container check only — what is *in* it is the schema's business, not this. */

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

@@ -0,0 +1,30 @@
+/**
+ * One structural failure from validating a registry.
+ *
+ * Deliberately not the validator's own issue type: `issues` is reached through
+ * the `./define` subpath, so its element type is a public contract, and §10's
+ * fourth encapsulation rule keeps a dependency's type off one. These two fields
+ * are the whole of what this project consumes — nothing reads `code`,
+ * `expected`, `received` or `fatal`.
+ *
+ * `path` is `PropertyKey[]` rather than `(string | number)[]` because that is
+ * the wider of the two spellings zod has used, so a validator issue assigns to
+ * this without a cast in either direction. Keep it the wider one: narrowing it
+ * would put the next reshape of that type back on the boundary.
+ */
+export interface RegistryValidationIssue {
+    path: PropertyKey[];
+    message: string;
+}
+/**
+ * The message `RegistryValidationError` carries, available without one.
+ *
+ * Three sites report `registry-invalid` — the throwing path in
+ * `defineRequirements`, and the two readers in `locate.ts` and
+ * `static-registry.ts` that report it without throwing — and their messages
+ * have to be identical rather than merely similar. Sharing this function is
+ * what makes that structural rather than a coincidence maintained by hand, so
+ * a new site formats through here and does not grow a fourth spelling.
+ */
+export declare function registryValidationMessage(issues: readonly RegistryValidationIssue[]): string;
+//# sourceMappingURL=registry-issues.d.ts.map