@am_shork/attest 0.7.3 → 0.8.0

package/dist/core/schema.d.ts

@@ -1,27 +1,17 @@
 import { z } from 'zod';
 /** A scalar param value. `null` is included: it is how an author writes "empty". */
-declare const scalar: z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodBoolean, z.ZodNull]>;
+declare const scalar: z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodBoolean, z.ZodNull]>;
 /** Any JSON value — what a param may be. */
 export type ParamValue = z.infer<typeof scalar> | ParamValue[] | {
     [key: string]: ParamValue;
 };
 /** A single behavioural contract (design §2). */
 export declare const RequirementSchema: z.ZodObject<{
-    statement: z.ZodEffects<z.ZodString, string, string>;
+    statement: z.ZodString;
     rationale: z.ZodString;
-    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<ParamValue, z.ZodTypeDef, ParamValue>>>;
-    outOfScope: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-}, "strip", z.ZodTypeAny, {
-    params: Record<string, ParamValue>;
-    statement: string;
-    rationale: string;
-    outOfScope: string[];
-}, {
-    statement: string;
-    rationale: string;
-    params?: Record<string, ParamValue> | undefined;
-    outOfScope?: string[] | undefined;
-}>;
+    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<ParamValue, unknown, z.core.$ZodTypeInternals<ParamValue, unknown>>>>;
+    outOfScope: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
 /**
  * The id grammar, on its own.
  *
@@ -34,23 +24,38 @@ export declare const RequirementSchema: z.ZodObject<{
  * two grammars as soon as one of them is edited.
  */
 export declare const RequirementIdSchema: z.ZodString;
-/** The requirement registry: stable ID -> requirement (design §2, §5.1). */
-export declare const RegistrySchema: z.ZodRecord<z.ZodString, z.ZodObject<{
-    statement: z.ZodEffects<z.ZodString, string, string>;
-    rationale: z.ZodString;
-    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<ParamValue, z.ZodTypeDef, ParamValue>>>;
-    outOfScope: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-}, "strip", z.ZodTypeAny, {
-    params: Record<string, ParamValue>;
+/**
+ * The requirement registry: stable ID -> requirement (design §2, §5.1).
+ *
+ * Guarded by `isPlainObject` for the same reason `jsonObject` is, and it is the
+ * *evaluating* reader this protects: `{ '__proto__': { … } }` swaps the
+ * prototype rather than creating a key, so the registry a loader builds from
+ * that file comes from the prototype and not from anything the file declares.
+ * The static reader refuses such a source outright (`registry-not-static`), and
+ * the two readers agreeing is a security property (design §5.2), not a
+ * convenience — so the schema has to refuse it rather than enumerate it.
+ *
+ * The guard is written over `RegistryRecord`'s input so `z.input` still
+ * describes the authoring shape: `defineRequirements` constrains its `const`
+ * type parameter to `RegistryInput`, and a guard typed as a bare record would
+ * erase every literal that constraint exists to capture.
+ */
+export declare const RegistrySchema: z.ZodPipe<z.ZodCustom<Record<string, {
     statement: string;
     rationale: string;
-    outOfScope: string[];
-}, {
+    params?: Record<string, unknown> | undefined;
+    outOfScope?: string[] | undefined;
+}>, Record<string, {
     statement: string;
     rationale: string;
-    params?: Record<string, ParamValue> | undefined;
+    params?: Record<string, unknown> | undefined;
     outOfScope?: string[] | undefined;
-}>>;
+}>>, z.ZodRecord<z.ZodString, z.ZodObject<{
+    statement: z.ZodString;
+    rationale: z.ZodString;
+    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<ParamValue, unknown, z.core.$ZodTypeInternals<ParamValue, unknown>>>>;
+    outOfScope: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>>>;
 /** Parsed (output) shapes — defaults applied. */
 export type Requirement = z.infer<typeof RequirementSchema>;
 export type Registry = z.infer<typeof RegistrySchema>;

package/dist/core/schema.js

@@ -35,9 +35,7 @@ const jsonObject = z
     .custom(isPlainObject)
     .pipe(z.record(z.string(), z.lazy(() => paramValue)));
 const paramValue = z.lazy(() => z.union([scalar, z.array(paramValue), jsonObject], {
-    errorMap: () => ({
-        message: 'expected JSON data (no functions, dates, or class instances)',
-    }),
+    error: 'expected JSON data (no functions, dates, or class instances)',
 }));
 /** A single behavioural contract (design §2). */
 export const RequirementSchema = z.object({
@@ -80,6 +78,36 @@ export const RequirementSchema = z.object({
 export const RequirementIdSchema = z
     .string()
     .regex(/^[A-Z]+-\d+$/, 'id must look like AUTH-3');
-/** The requirement registry: stable ID -> requirement (design §2, §5.1). */
-export const RegistrySchema = z.record(RequirementIdSchema, RequirementSchema);
+/**
+ * The registry's own record, before the plain-object guard below.
+ *
+ * `error` is carried explicitly because a record reports a key failure as
+ * "Invalid key in record" and does not surface the key schema's own message —
+ * and a mistyped id is the commonest way to fail this schema, so the grammar is
+ * the one thing the author needs to be told.
+ */
+const RegistryRecord = z.record(RequirementIdSchema, RequirementSchema, {
+    error: 'id must look like AUTH-3',
+});
+/**
+ * The requirement registry: stable ID -> requirement (design §2, §5.1).
+ *
+ * Guarded by `isPlainObject` for the same reason `jsonObject` is, and it is the
+ * *evaluating* reader this protects: `{ '__proto__': { … } }` swaps the
+ * prototype rather than creating a key, so the registry a loader builds from
+ * that file comes from the prototype and not from anything the file declares.
+ * The static reader refuses such a source outright (`registry-not-static`), and
+ * the two readers agreeing is a security property (design §5.2), not a
+ * convenience — so the schema has to refuse it rather than enumerate it.
+ *
+ * The guard is written over `RegistryRecord`'s input so `z.input` still
+ * describes the authoring shape: `defineRequirements` constrains its `const`
+ * type parameter to `RegistryInput`, and a guard typed as a bare record would
+ * erase every literal that constraint exists to capture.
+ */
+export const RegistrySchema = z
+    .custom(isPlainObject, {
+    error: 'a registry must be an object literal',
+})
+    .pipe(RegistryRecord);
 //# sourceMappingURL=schema.js.map

package/dist/core/skill.js

@@ -102,6 +102,19 @@ promises is a two-stage workflow, and the stages are separate on purpose.
   rule forbids, and the distinction is the whole of it — that rule is about the
   **expectation** the system is measured against; this pin asserts what the
   **intent** is.
+- **Prefer a quantifier a scenario can iterate.** A statement that says *every*,
+  *all* or *any* has a finite set of scenarios under it and nothing holding the
+  two together — the id is covered, \`check\` is green, and whether those
+  scenarios span what the sentence claims is the part no gate looks at. What
+  decides the risk is *what* the quantifier ranges over. Over the inputs one
+  place processes, representative inputs settle it. Over a list the code itself
+  enumerates, a scenario looping that same list covers a new member by
+  construction — **this is the shape to write**, and when that list lives in
+  \`params\` rather than in the code, the pin above is what keeps it honest, since
+  an author can shorten it. Over *places in the implementation*, each needing its
+  own hand-written scenario, a new place is a new obligation and nothing
+  enumerates them: that is the one that silently stops being true. When you cannot avoid it, name the places in the statement instead
+  of quantifying over them, so a reader can count what is missing.
 
 ## Rules the engine enforces
 

package/dist/core/splice.js

@@ -25,23 +25,26 @@ import { registryInsertionPoint } from './static-registry.js';
 import { toPosixPath } from './paths.js';
 import { byCodeUnit, sortDeep } from './order.js';
 /**
- * A TypeScript single-quoted string literal holding exactly `value`.
+ * The *inside* of a TypeScript string literal quoted with `quote`, holding
+ * exactly `value`.
  *
- * Hand-escaped rather than `JSON.stringify`, for one reason that is not style:
- * the registries this writes into are single-quoted throughout, and a merged
- * entry that arrives double-quoted is a diff hunk about quotation marks in the
- * middle of a merge the reviewer is trying to read. Control characters go out as
- * `\uXXXX` rather than raw, so a statement someone pasted a newline into cannot
- * produce a file that no longer parses.
+ * Split out from `tsString` because the other site that writes into a string
+ * literal — `repointImport` — writes between quotes that are already in the
+ * file, whose character is the file's choice and not this module's. Escaping
+ * has to answer to that character: `'` needs no escape inside `"…"`, and
+ * escaping it there would be a wrong byte rather than a safe one.
+ *
+ * Control characters go out as `\uXXXX` rather than raw, so a value someone
+ * pasted a newline into cannot produce a file that no longer parses.
  */
-function tsString(value) {
-    let out = "'";
+function tsStringBody(value, quote) {
+    let out = '';
     for (const ch of value) {
         const code = ch.codePointAt(0) ?? 0;
         if (ch === '\\')
             out += '\\\\';
-        else if (ch === "'")
-            out += "\\'";
+        else if (ch === quote)
+            out += `\\${ch}`;
         else if (ch === '\n')
             out += '\\n';
         else if (ch === '\r')
@@ -53,7 +56,18 @@ function tsString(value) {
         else
             out += ch;
     }
-    return `${out}'`;
+    return out;
+}
+/**
+ * A TypeScript single-quoted string literal holding exactly `value`.
+ *
+ * Hand-escaped rather than `JSON.stringify`, for one reason that is not style:
+ * the registries this writes into are single-quoted throughout, and a merged
+ * entry that arrives double-quoted is a diff hunk about quotation marks in the
+ * middle of a merge the reviewer is trying to read.
+ */
+function tsString(value) {
+    return `'${tsStringBody(value, "'")}'`;
 }
 /**
  * Thrown when a value reaches the emitter that cannot be written as source
@@ -205,10 +219,27 @@ export function repointImport(file, source, from, to) {
         // A bare `x.reqs.js` is a package specifier, not a sibling file.
         if (!target.startsWith('.'))
             target = `./${target}`;
-        // Inside the quotes: the file's own quote style is left exactly as it was.
-        edits.push({ start: spec.getStart(sf) + 1, end: spec.getEnd() - 1, text: target });
+        // Inside the quotes, so the file's own quote style is left exactly as it
+        // was — which is why the escaping is told which quote it writes between.
+        // `to` is the registry file `--apply` chose, making this the one value in
+        // the emitter the checked repository names, and a name carrying that quote
+        // would otherwise close the literal and put what follows into a committed
+        // `*.spec.ts` as code (§7). Escaped rather than refused, unlike the
+        // `__proto__` key above: a specifier is a string, and every string has a
+        // correct spelling as one.
+        const quote = source[spec.getStart(sf)];
+        edits.push({
+            start: spec.getStart(sf) + 1,
+            end: spec.getEnd() - 1,
+            text: tsStringBody(target, quote),
+        });
     }
     let out = source;
+    // Back to front, which is what makes a correction term unnecessary: an edit
+    // cannot move an offset that lies before it, so every `start`/`end` above
+    // stays valid as the string is rewritten under them. Applying these in source
+    // order works only by carrying a running delta and adding it to each
+    // subsequent pair — the same result, one more thing to get wrong.
     for (const edit of edits.reverse()) {
         out = out.slice(0, edit.start) + edit.text + out.slice(edit.end);
     }

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

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

package/dist/core/static-registry.js

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

package/dist/core/status.js

@@ -49,7 +49,7 @@ export function statusRows(addedIds, plan, firstRun) {
             name: s.name,
             file: s.file,
             line: s.line,
-            firstRun: recordedOutcome(firstRun, reqId, s.name) ?? null,
+            firstRun: recordedOutcome(firstRun, { reqId, file: s.file, name: s.name }) ?? null,
         }));
         return { reqId, state: obligationState(reqId, scenarios, firstRun), scenarios };
     });
@@ -59,7 +59,7 @@ function obligationState(reqId, scenarios, firstRun) {
         return 'no-scenario';
     // Every scenario, not any: the gate raises never-red per scenario, so one
     // proven scenario beside an unproven one is still a blocked change.
-    return scenarios.every((s) => hasRecordedRed(firstRun, reqId, s.name))
+    return scenarios.every((s) => hasRecordedRed(firstRun, { reqId, file: s.file, name: s.name }))
         ? 'proven'
         : 'unproven';
 }

package/dist/core/terminal.js

@@ -12,8 +12,11 @@
 // write to the terminal of whoever is checking it. On a fork MR the author is
 // not the reviewer, and the payload is a scenario name or an exception: erase
 // the lines above, repaint a red verdict green, rewrite the window title. The
-// `--json` path was never exposed — `JSON.stringify` escapes every C0
-// character — which is precisely why this has to hold on the side people read.
+// `--json` path was recorded here as never exposed, on the grounds that
+// `JSON.stringify` escapes every C0 character — true, and narrower than the
+// class below, which also holds DEL and C1. `cli/json.ts` now applies the same
+// rule at the point that document is serialised (ATX-74); this still has to
+// hold independently, because a stream has no such point.
 //
 // **In `core/` rather than in the CLI**, though the CLI is its main caller: the
 // loader has to sanitise Vite's log output for the same reason and cannot

package/dist/core/types.d.ts

@@ -1,11 +1,22 @@
 export type { Requirement, Registry, ParamValue } from './schema.js';
 export type { IssueCode } from './docs.js';
 import type { IssueCode } from './docs.js';
-/** A scenario extracted statically from a spec file (design §5.2). */
-export interface ParsedScenario {
+/**
+ * What identifies one scenario, everywhere the engine compares one (design §5.4).
+ *
+ * All three, and as a bundle rather than three positional strings: the file was
+ * missing from the key that `declared-not-run` and the first-run record are
+ * decided by, and adding it as a fourth `string` argument beside `reqId` and
+ * `name` would have made two adjacent parameters of one type that a caller can
+ * silently transpose. The compiler cannot catch that; a field name can.
+ */
+export interface ScenarioRef {
     reqId: string;
-    name: string;
     file: string;
+    name: string;
+}
+/** A scenario extracted statically from a spec file (design §5.2). */
+export interface ParsedScenario extends ScenarioRef {
     line: number;
 }
 /**
@@ -31,15 +42,33 @@ export type Outcome = 'pass' | 'fail';
 export interface RunResult {
     /** True when no test failed. */
     passed: boolean;
-    /** reqId -> set of scenario names that actually executed (from the task tree). */
-    runtimeCoverage: Map<string, Set<string>>;
     /**
-     * reqId -> scenario name -> how it ended. The same task-tree walk that fills
-     * `runtimeCoverage` already had to tell `pass` from `fail` to decide whether a
-     * scenario executed at all; this keeps that distinction instead of discarding
-     * it, which is what §6's mechanism 2 records.
+     * reqId -> spec file -> the scenario names that actually executed (from the
+     * task tree).
+     *
+     * **The file is part of the key, and its absence was a false green.** Keyed by
+     * `(reqId, name)` alone, two spec files declaring the same scenario name under
+     * the same `requirement()` are one entry, so whichever of them executed
+     * vouched for the other and `declared-not-run` stayed silent about a scenario
+     * that never ran — the one report this tool exists to refuse. The static plan
+     * carries `file` on every `ParsedScenario` and the task tree carries it on
+     * every file task, so only this map ever forgot it.
+     *
+     * Project-relative POSIX, like `unloadedFiles` and for the same reason: it is
+     * compared against a plan built that way (`paths.ts`).
+     */
+    runtimeCoverage: Map<string, Map<string, Set<string>>>;
+    /**
+     * reqId -> spec file -> scenario name -> how it ended. The same task-tree walk
+     * that fills `runtimeCoverage` already had to tell `pass` from `fail` to
+     * decide whether a scenario executed at all; this keeps that distinction
+     * instead of discarding it, which is what §6's mechanism 2 records.
+     *
+     * Keyed identically, and for the identical reason: the same collapse reaches
+     * `mergeRedRecord`, where a base scenario's recorded `fail` satisfied a
+     * same-named proposed scenario's first-red obligation.
      */
-    outcomes: Map<string, Map<string, Outcome>>;
+    outcomes: Map<string, Map<string, Map<string, Outcome>>>;
     /**
      * Spec files that failed to *load*, as project-relative POSIX paths.
      *

package/dist/core/validator.d.ts

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