@am_shork/attest 0.7.3 → 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.3/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/compiler.d.ts

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

package/dist/core/compiler.js

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

package/dist/core/docs.d.ts

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

package/dist/core/docs.js

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

package/dist/core/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.d.ts

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

package/dist/core/locate.js

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

package/dist/core/parser.d.ts

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

package/dist/core/parser.js

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

package/dist/core/pipeline.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`).
  *