@am_shork/attest 0.6.0 → 0.7.1

package/README.md

@@ -12,9 +12,9 @@ The killer move against drift: values a requirement **promises** (timeouts,
 limits, budgets) live **once** in its `params`, and tests read them from there —
 so a number is physically impossible to drift between the spec and the assertion.
 Values that merely tune behaviour stay ordinary constants; nothing is owed to
-anyone when a tuning knob changes. A param may be a scalar or an array of
-scalars, so list-shaped constants (vendor blacklists, id sets) get the same
-single source as a lone number.
+anyone when a tuning knob changes. A param may be any JSON value, so a
+composite constant — a vendor blacklist, a `kind -> payload` table — gets the
+same single source as a lone number, which is where drift is worst.
 
 What that does not buy is a warning when you change the value. `check` runs
 nothing, so editing a param leaves it at `✓ No issues` — nothing became unbound,
@@ -157,7 +157,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.6.0/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.7.1/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,7 @@ 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';
-import { formatCrash, formatIssues, formatScope, summarize, formatCoverage, formatStatus, } from './report.js';
+import { formatArchiveVerdict, formatCrash, formatIssues, formatScope, summarize, formatCoverage, formatStatus, } from './report.js';
 import { archiveReport, checkReport, coverReport, errorReport, initReport, renderJson, renderReport, statusReport, verifyReport, } from './json.js';
 import { packageVersion } from '../core/version.js';
 const VERSION = packageVersion();
@@ -282,23 +282,7 @@ program
     return {
         report: archiveReport(VERSION, change, blocking),
         human: () => {
-            if (blocking.length === 0) {
-                console.log(chalk.green(opts.apply
-                    ? `✓ Gate passed and merged: change "${change}".`
-                    : `✓ Gate passed: change "${change}" can be archived.`));
-                // Every path the merge touched, because this is the command that
-                // edits files the user cannot regenerate and they need to know which
-                // ones to read before committing. It is also what a working-tree
-                // check would only have approximated, and it works for someone not
-                // using version control at all.
-                for (const path of written)
-                    console.log(chalk.dim(`  ${path}`));
-            }
-            else {
-                console.log(chalk.red(`✗ Gate failed: change "${change}"`));
-                console.log(formatIssues(blocking));
-                console.log(summarize(blocking));
-            }
+            console.log(formatArchiveVerdict(change, blocking, { applied: opts.apply === true, written }));
         },
     };
 }));

package/dist/cli/json.js

@@ -112,7 +112,12 @@ export function archiveReport(version, change, blocking) {
         ...envelope({
             version,
             command: 'archive',
-            ok: blocking.length === 0,
+            // `hasError`, not `blocking.length === 0` (ATX-60). The gate deliberately
+            // keeps its non-blocking output through `--apply`, so a WARNING in here
+            // is planned for — and counting one as a failure made this command answer
+            // not-ok, exit 1, and print a failed gate *after* the merge had written
+            // the files. Every other command already asks the question this way.
+            ok: !hasError(blocking),
             issues: blocking,
         }),
         change,

package/dist/cli/report.d.ts

@@ -57,5 +57,23 @@ export declare function formatScope(scope: VerifyCounts): string;
  * the argument that keeps `render --check` comparing documents rather than bytes.
  */
 export declare function formatStatus(result: StatusResult): string;
+/**
+ * The verdict `attest archive` prints, and the lines under it.
+ *
+ * Here rather than inline in the CLI action for two reasons, and the second is
+ * the one that matters. The shell is a thin veneer that renders what the core
+ * decided; and while this lived in a closure it was the *only* copy of the
+ * verdict nothing could test — so when it asked `blocking.length === 0` of its
+ * own accord, no scenario could see that the line above the issues could call
+ * the gate failed while the JSON beside it called the command ok (ATX-60).
+ *
+ * `hasError`, the same predicate `archiveReport` uses. Not a second reading of
+ * the same array so much as the same question asked once and rendered twice —
+ * which is what the requirement is about.
+ */
+export declare function formatArchiveVerdict(change: string, blocking: Issue[], merge: {
+    applied: boolean;
+    written: readonly string[];
+}): string;
 export declare function formatCoverage(rows: CoverageRow[]): string;
 //# sourceMappingURL=report.d.ts.map

package/dist/cli/report.js

@@ -4,6 +4,7 @@ import chalk from 'chalk';
 import { docsUrl } from '../core/docs.js';
 import { byCodeUnit } from '../core/order.js';
 import { INDENT, block, inline } from '../core/terminal.js';
+import { hasError } from '../core/types.js';
 const LEVEL_TAG = {
     ERROR: (s) => chalk.red.bold(s),
     WARNING: (s) => chalk.yellow.bold(s),
@@ -184,6 +185,46 @@ export function formatStatus(result) {
     lines.push(chalk.dim(`Not a verdict: run \`attest archive ${inline(result.change)}\` to run the suite.`));
     return lines.join('\n');
 }
+/**
+ * The verdict `attest archive` prints, and the lines under it.
+ *
+ * Here rather than inline in the CLI action for two reasons, and the second is
+ * the one that matters. The shell is a thin veneer that renders what the core
+ * decided; and while this lived in a closure it was the *only* copy of the
+ * verdict nothing could test — so when it asked `blocking.length === 0` of its
+ * own accord, no scenario could see that the line above the issues could call
+ * the gate failed while the JSON beside it called the command ok (ATX-60).
+ *
+ * `hasError`, the same predicate `archiveReport` uses. Not a second reading of
+ * the same array so much as the same question asked once and rendered twice —
+ * which is what the requirement is about.
+ */
+export function formatArchiveVerdict(change, blocking, merge) {
+    if (hasError(blocking)) {
+        return [
+            chalk.red(`✗ Gate failed: change "${inline(change)}"`),
+            formatIssues(blocking),
+            summarize(blocking),
+        ].join('\n');
+    }
+    const lines = [
+        chalk.green(merge.applied
+            ? `✓ Gate passed and merged: change "${inline(change)}".`
+            : `✓ Gate passed: change "${inline(change)}" can be archived.`),
+    ];
+    // Every path the merge touched, because this is the command that edits files
+    // the user cannot regenerate and they need to know which ones to read before
+    // committing. It is also what a working-tree check would only have
+    // approximated, and it works for someone not using version control at all.
+    for (const path of merge.written)
+        lines.push(chalk.dim(`  ${inline(path)}`));
+    // A WARNING that did not fail the gate still has to be shown, or `--apply`
+    // would be quieter than the same command without it — the property
+    // `runArchiveApply` keeps its non-blocking output for.
+    if (blocking.length > 0)
+        lines.push(formatIssues(blocking), summarize(blocking));
+    return lines.join('\n');
+}
 export function formatCoverage(rows) {
     if (rows.length === 0)
         return chalk.dim('(the registry contains no requirements)');

package/dist/core/apply.js

@@ -3,7 +3,7 @@
 // Map<id, Requirement>, with content-compare on ADDED and already-synced
 // no-ops on RENAMED.
 import { RequirementIdSchema, RequirementSchema } from './schema.js';
-import { byCodeUnit } from './order.js';
+import { byCodeUnit, sortDeep } from './order.js';
 /**
  * The ids a delta ADDs — the scope of the first-red obligation (design §6).
  *
@@ -185,16 +185,13 @@ function canonical(req) {
     return JSON.stringify({
         statement: req.statement,
         rationale: req.rationale,
-        params: sortKeys(req.params),
+        // Deep, not one level: a param is a JSON value, so the nested keys of a
+        // kind -> payload table are as much a part of this string as the top-level
+        // ones, and the failure is identical one level down — an identical copy
+        // written with its inner keys in another order reported as `add-conflict`
+        // against itself. Code-unit order throughout, and `sortDeep` says why.
+        params: sortDeep(req.params),
         outOfScope: [...req.outOfScope],
     });
 }
-// Code-unit order, not localeCompare: this string is a *verdict input*.
-// localeCompare calls some distinct keys equal, and a stable sort then leaves
-// them in insertion order — so the canonical form would encode how the params
-// happened to be written, and `add-conflict` would report a requirement as
-// conflicting with an identical copy of itself.
-function sortKeys(obj) {
-    return Object.fromEntries(Object.entries(obj).sort(([a], [b]) => byCodeUnit(a, b)));
-}
 //# sourceMappingURL=apply.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", "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", "stale-spec-doc", "tests-red", "unbound-param", "uncovered-requirement", "unknown-target"];
+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"];
 export type IssueCode = (typeof ISSUE_CODES)[number];
 /**
  * The page explaining `code`, or `undefined` when nothing explains it.

package/dist/core/docs.js

@@ -36,6 +36,7 @@ export const ISSUE_CODES = [
     'modify-invalid',
     'modify-missing',
     'never-red',
+    'non-scalar-interpolation',
     'orphan-test',
     'possible-drift',
     'proposed-spec-name-taken',
@@ -48,6 +49,7 @@ export const ISSUE_CODES = [
     'rename-target-exists',
     'rename-target-invalid',
     'spec-in-change-dir',
+    'spec-load-failed',
     'stale-spec-doc',
     'tests-red',
     'unbound-param',

package/dist/core/gate.d.ts

@@ -56,6 +56,51 @@ export declare function declaredNotRunIssues(plan: AttestPlan, run: RunResult):
  * rather than asserting a cause.
  */
 export declare function unmergedIdIssues(run: RunResult, unmergedAddedIds: readonly string[]): Issue[];
+/**
+ * A spec file the runtime could not load, with no more specific cause known
+ * (design §5.4).
+ *
+ * The general case of `unmergedIdIssues`, and it exists because that one is a
+ * conjunction: it speaks only when the change also adds an id the registry on
+ * disk lacks. Every other way a spec file fails to import — a typo in a
+ * specifier, a module that throws at load, a dependency that is not installed —
+ * produced no finding naming the file at all. What the reader got instead was a
+ * `declared-not-run` per scenario in it, saying "skipped, or excluded by an
+ * `.only`?", which is a guess at a cause and the wrong one: it sends someone to
+ * audit a file for a `skip` that is not there, while the import error that
+ * explains everything is named nowhere in the report.
+ *
+ * `already` is the files a more specific diagnosis has claimed. One file gets
+ * one finding, and the specific one wins, because `added-id-unmerged` carries a
+ * fix and this carries only a fact. That is also why this could not simply be
+ * `declared-not-run` suppression, which is what it looked like from a distance:
+ * suppressing with nothing to put in its place trades a wrong message for
+ * silence, and a wrong message beats silence. The replacement had to come first.
+ *
+ * No `reqId`. A file that never loaded has no established relationship to any
+ * requirement — the ids it *would* have attested are readable from the static
+ * plan, but stating one here would name a requirement as implicated when the
+ * failure may have nothing to do with it, and a file is what did or did not
+ * load.
+ */
+export declare function specLoadFailedIssues(run: RunResult, already?: ReadonlySet<string>): Issue[];
+/**
+ * Everything a report says about scenarios that did not run: the files that
+ * failed to load, then the absences those files do not already explain.
+ *
+ * One function because two commands ask, and the answer has an *order* in it —
+ * the cause before the absences it caused, and never the absences on their own.
+ * `verify` and the gate each spelling that out is how the two came to differ in
+ * the first place: the gate learned to withdraw a misleading line and `verify`
+ * did not, so the same run produced a different diagnosis depending on which
+ * command asked. That is the clerical agreement `declaredNotRunIssues` was
+ * extracted to stop, arriving one level up.
+ *
+ * `specific` is any more precise diagnosis the caller has already emitted for
+ * these files — `added-id-unmerged` on the gate path, nothing on `verify`'s.
+ * Those files are left alone here, so one file carries one finding.
+ */
+export declare function notRunIssues(plan: AttestPlan, run: RunResult, specific?: readonly Issue[]): Issue[];
 /**
  * Never-red: a scenario attesting a requirement this change ADDs, whose first
  * observed run did not fail (design §6, mechanism 2).
@@ -85,8 +130,9 @@ export declare function neverRedIssues(plan: AttestPlan, addedIds: readonly stri
  *   2. Executable: all tests green.
  *   3. A spec file that failed to load while the change adds an id the registry
  *      on disk lacks — the reason, named before the absences it causes.
- *   4. Static coverage vs runtime coverage: every declared scenario actually
- *      ran (catches skip/only false coverage).
+ *   4. Everything else about what did not run, from `notRunIssues`: the load
+ *      failures step 3 did not claim, then static-vs-runtime coverage for the
+ *      files that did load (catches skip/only false coverage).
  *   5. Never-red: every scenario of an ADDED requirement failed on its first
  *      recorded run (design §6, mechanism 2).
  */

package/dist/core/gate.js

@@ -66,6 +66,71 @@ export function unmergedIdIssues(run, unmergedAddedIds) {
             `Merge the added requirement into the registry and run the gate again: applying a delta whose ADDED entry already exists with identical content is a no-op, so the change still documents the intent.`,
     }));
 }
+/**
+ * A spec file the runtime could not load, with no more specific cause known
+ * (design §5.4).
+ *
+ * The general case of `unmergedIdIssues`, and it exists because that one is a
+ * conjunction: it speaks only when the change also adds an id the registry on
+ * disk lacks. Every other way a spec file fails to import — a typo in a
+ * specifier, a module that throws at load, a dependency that is not installed —
+ * produced no finding naming the file at all. What the reader got instead was a
+ * `declared-not-run` per scenario in it, saying "skipped, or excluded by an
+ * `.only`?", which is a guess at a cause and the wrong one: it sends someone to
+ * audit a file for a `skip` that is not there, while the import error that
+ * explains everything is named nowhere in the report.
+ *
+ * `already` is the files a more specific diagnosis has claimed. One file gets
+ * one finding, and the specific one wins, because `added-id-unmerged` carries a
+ * fix and this carries only a fact. That is also why this could not simply be
+ * `declared-not-run` suppression, which is what it looked like from a distance:
+ * suppressing with nothing to put in its place trades a wrong message for
+ * silence, and a wrong message beats silence. The replacement had to come first.
+ *
+ * No `reqId`. A file that never loaded has no established relationship to any
+ * requirement — the ids it *would* have attested are readable from the static
+ * plan, but stating one here would name a requirement as implicated when the
+ * failure may have nothing to do with it, and a file is what did or did not
+ * load.
+ */
+export function specLoadFailedIssues(run, already = new Set()) {
+    return run.unloadedFiles
+        .filter((file) => !already.has(file))
+        .map((file) => ({
+        level: 'ERROR',
+        code: 'spec-load-failed',
+        file,
+        message: `${file} failed to load, so none of the scenarios in it ran. ` +
+            `The run output above carries the import error itself; this reports which file it stopped, because a file that never loaded reports no failures of its own. ` +
+            `Fix the import and run again — the scenarios in this file are neither passing nor failing until it loads.`,
+    }));
+}
+/**
+ * Everything a report says about scenarios that did not run: the files that
+ * failed to load, then the absences those files do not already explain.
+ *
+ * One function because two commands ask, and the answer has an *order* in it —
+ * the cause before the absences it caused, and never the absences on their own.
+ * `verify` and the gate each spelling that out is how the two came to differ in
+ * the first place: the gate learned to withdraw a misleading line and `verify`
+ * did not, so the same run produced a different diagnosis depending on which
+ * command asked. That is the clerical agreement `declaredNotRunIssues` was
+ * extracted to stop, arriving one level up.
+ *
+ * `specific` is any more precise diagnosis the caller has already emitted for
+ * these files — `added-id-unmerged` on the gate path, nothing on `verify`'s.
+ * Those files are left alone here, so one file carries one finding.
+ */
+export function notRunIssues(plan, run, specific = []) {
+    const named = new Set(specific.flatMap((i) => (i.file ? [i.file] : [])));
+    // Every unloaded file now carries a diagnosis: `specific` covers `named`, and
+    // the call below covers the rest by construction.
+    const diagnosed = new Set(run.unloadedFiles);
+    return [
+        ...specLoadFailedIssues(run, named),
+        ...declaredNotRunIssues(plan, run).filter((i) => !i.file || !diagnosed.has(i.file)),
+    ];
+}
 /**
  * Never-red: a scenario attesting a requirement this change ADDs, whose first
  * observed run did not fail (design §6, mechanism 2).
@@ -116,8 +181,9 @@ export function neverRedIssues(plan, addedIds, firstRun) {
  *   2. Executable: all tests green.
  *   3. A spec file that failed to load while the change adds an id the registry
  *      on disk lacks — the reason, named before the absences it causes.
- *   4. Static coverage vs runtime coverage: every declared scenario actually
- *      ran (catches skip/only false coverage).
+ *   4. Everything else about what did not run, from `notRunIssues`: the load
+ *      failures step 3 did not claim, then static-vs-runtime coverage for the
+ *      files that did load (catches skip/only false coverage).
  *   5. Never-red: every scenario of an ADDED requirement failed on its first
  *      recorded run (design §6, mechanism 2).
  */
@@ -133,19 +199,12 @@ export function evaluateGate({ registry, plan, run, addedIds, unmergedAddedIds,
             message: 'Some tests are failing; the change cannot be archived.',
         });
     }
-    // 3) A file that failed to load, named before the absences it produces.
+    // 3) and 4) in one push, because the order between them is not this
+    // function's to choose: the gate's own diagnosis — the one with a cause and a
+    // fix attached — and then everything `notRunIssues` says about the rest. The
+    // gate's only extra input is having that more specific diagnosis to offer.
     const unmerged = unmergedIdIssues(run, unmergedAddedIds ?? []);
-    blocking.push(...unmerged);
-    // 4) Declared-not-run: static coverage claimed, runtime never executed it.
-    //
-    // Scenarios in a file diagnosed just above are left out. Not because they
-    // ran — they could not have — but because "declared but never executed
-    // (skipped, or excluded by an .only?)" is one fact restated as a guess about
-    // a cause the line above has already established. Only when that line was
-    // emitted: with no diagnosis to replace it, a wrong message still beats
-    // silence, which is why `verify` keeps reporting them.
-    const diagnosed = new Set(unmerged.map((i) => i.file));
-    blocking.push(...declaredNotRunIssues(plan, run).filter((i) => !diagnosed.has(i.file)));
+    blocking.push(...unmerged, ...notRunIssues(plan, run, unmerged));
     // 5) Never-red: the added scenarios have to have discriminated once.
     if (addedIds && addedIds.length > 0) {
         blocking.push(...neverRedIssues(plan, addedIds, firstRun ?? {}));

package/dist/core/loader.js

@@ -35,6 +35,19 @@ import { block } from './terminal.js';
 export function sanitisedLogger(base = createLogger('error')) {
     return {
         ...base,
+        // `hasWarned` is the one member of `Logger` that is state rather than
+        // behaviour, and the spread above copies it *by value* — so the wrapper was
+        // born `false` and stayed `false` however many warnings went through it,
+        // while the base it delegates to flipped to `true`. Measured: after one
+        // `warn`, base `true` / wrapper `false`. An accessor pair makes the wrapper
+        // a view of the base rather than a snapshot of it, which is what every
+        // other member already is.
+        get hasWarned() {
+            return base.hasWarned;
+        },
+        set hasWarned(value) {
+            base.hasWarned = value;
+        },
         info: (msg, opts) => base.info(block(msg), opts),
         warn: (msg, opts) => base.warn(block(msg), opts),
         warnOnce: (msg, opts) => base.warnOnce(block(msg), opts),

package/dist/core/locate.d.ts

@@ -109,6 +109,18 @@ export declare function loadRegistry(root: string, reader: RegistryReader, files
     registry: Registry;
     issues: Issue[];
     prefixOwners: Record<string, string>;
+    /**
+     * Registry files that contributed **no ids**, relative to `root`.
+     *
+     * Not the same question as "did loading produce an ERROR": `duplicate-prefix`
+     * and `duplicate-requirement` are ERRORs raised *after* a successful read, and
+     * the ids they are about are present. Only a file whose outcome carried an
+     * issue instead of a registry is missing from the result, and a caller that
+     * 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.
+     */
+    unreadableFiles: string[];
 }>;
 /**
  * The part of an id that names the space it lives in — `AUTH` of `AUTH-3`.
@@ -128,6 +140,17 @@ export declare function idPrefix(id: string): string;
  * The paths are POSIX on every platform (see `paths.ts`): they are not only
  * displayed, they become the child run's `include` globs, where a Windows
  * separator would silently match nothing.
+ *
+ * Each source is parsed as it arrives rather than after all of them, so the peak
+ * is `PARSE_CONCURRENCY` sources rather than `files.length` and the plan is the
+ * only thing still growing with the tree. Reading them all first is the shape to
+ * avoid: input size is not ours to choose here, `check` being what this project
+ * tells people to run first on an untrusted fork MR. Measured in `[0.7.0]`.
+ *
+ * `findFiles` above is deliberately left unbounded: its fan-out is real, but the
+ * failure it invites is descriptor exhaustion, which no measurement on either
+ * development platform could produce (see CHANGELOG.md, `Under consideration`).
+ * The memory here needed no such evidence — it is arithmetic, and portable.
  */
 export declare function parseSpecs(files: string[], displayRoot: string): Promise<AttestPlan>;
 /** Parse every `*.spec.ts` under root into one merged plan (file paths shown relative to root). */

package/dist/core/locate.js

@@ -210,6 +210,7 @@ export async function loadRegistry(root, reader, files) {
     const loaded = await Promise.all(paths.map(async (file) => ({ file, outcome: await reader.read(file) })));
     const registry = {};
     const issues = [];
+    const unreadableFiles = [];
     // 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
@@ -225,6 +226,7 @@ export async function loadRegistry(root, reader, files) {
         const { outcome } = entry;
         if ('issue' in outcome) {
             issues.push({ ...outcome.issue, file: display });
+            unreadableFiles.push(display);
             continue;
         }
         // One issue per colliding prefix rather than per requirement: the fact is
@@ -262,7 +264,7 @@ export async function loadRegistry(root, reader, files) {
             }
         }
     }
-    return { registry, issues, prefixOwners: Object.fromEntries(prefixOwner) };
+    return { registry, issues, prefixOwners: Object.fromEntries(prefixOwner), unreadableFiles };
 }
 /**
  * The part of an id that names the space it lives in — `AUTH` of `AUTH-3`.
@@ -277,6 +279,12 @@ export function idPrefix(id) {
     const dash = id.indexOf('-');
     return dash === -1 ? id : id.slice(0, dash);
 }
+/**
+ * How many spec files are read at once. High enough that the walk stays I/O
+ * bound on any real project, low enough that the number of sources alive is a
+ * constant rather than the size of the input.
+ */
+const PARSE_CONCURRENCY = 32;
 /**
  * Parse the given spec files into one merged plan (paths shown relative to
  * `displayRoot`). Files are read concurrently; the merge follows the input
@@ -285,14 +293,35 @@ export function idPrefix(id) {
  * The paths are POSIX on every platform (see `paths.ts`): they are not only
  * displayed, they become the child run's `include` globs, where a Windows
  * separator would silently match nothing.
+ *
+ * Each source is parsed as it arrives rather than after all of them, so the peak
+ * is `PARSE_CONCURRENCY` sources rather than `files.length` and the plan is the
+ * only thing still growing with the tree. Reading them all first is the shape to
+ * avoid: input size is not ours to choose here, `check` being what this project
+ * tells people to run first on an untrusted fork MR. Measured in `[0.7.0]`.
+ *
+ * `findFiles` above is deliberately left unbounded: its fan-out is real, but the
+ * failure it invites is descriptor exhaustion, which no measurement on either
+ * development platform could produce (see CHANGELOG.md, `Under consideration`).
+ * The memory here needed no such evidence — it is arithmetic, and portable.
  */
 export async function parseSpecs(files, displayRoot) {
-    const sources = await Promise.all(files.map((file) => readFile(file, 'utf8')));
+    // Indexed rather than appended, so the merge below follows the input order
+    // whatever order the reads finish in.
+    const parsed = new Array(files.length);
+    let next = 0;
+    const worker = async () => {
+        for (let i = next++; i < files.length; i = next++) {
+            const file = files[i];
+            const source = await readFile(file, 'utf8');
+            parsed[i] = parseSpecFile(relativePath(displayRoot, file), source);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(PARSE_CONCURRENCY, files.length) }, worker));
     const plan = { scenarios: [], paramRefs: [] };
-    for (const [i, file] of files.entries()) {
-        const parsed = parseSpecFile(relativePath(displayRoot, file), sources[i]);
-        plan.scenarios.push(...parsed.scenarios);
-        plan.paramRefs.push(...parsed.paramRefs);
+    for (const one of parsed) {
+        plan.scenarios.push(...one.scenarios);
+        plan.paramRefs.push(...one.paramRefs);
     }
     return plan;
 }

package/dist/core/merge.js

@@ -30,7 +30,7 @@
 // at runtime on the happy path, and a later reordering would look harmless.
 import { mkdir, readFile, rename, stat } from 'node:fs/promises';
 import { join, dirname, basename } from 'node:path';
-import { repointImport, spliceRequirements } from './splice.js';
+import { repointImport, spliceRequirements, UnwritableValue } from './splice.js';
 import { writeAtomic } from './write.js';
 import { idPrefix } from './locate.js';
 import { addedIds } from './apply.js';
@@ -48,20 +48,21 @@ export function mergedSpecPath(proposed) {
  * acting on it, and a merge that did the half it understood would put the file
  * into a state no verdict describes.
  */
-async function refusals(input) {
+async function refusals(input, stamp) {
     const issues = [];
     const { delta, root, changeName } = input;
+    const archive = archivePath(input, stamp);
     // 0) The destination already exists. Checked here, before anything is
     // written, rather than at the move it is about: every refusal in this function
     // leaves the tree untouched, and one that fired after two steps had landed
     // would make "refused whole" a claim with an exception in it — which is the
     // kind of claim nobody can rely on.
-    if (await exists(archivePath(input))) {
+    if (await exists(archive)) {
         issues.push({
             level: 'ERROR',
             code: 'apply-unsupported-delta',
-            file: relativePath(root, archivePath(input)),
-            message: `${relativePath(root, archivePath(input))} already exists, so this change cannot be archived there. ` +
+            file: relativePath(root, archive),
+            message: `${relativePath(root, archive)} already exists, so this change cannot be archived there. ` +
                 `Move or remove that directory, then run this command again.`,
         });
     }
@@ -154,7 +155,15 @@ function unmergedAdded(input) {
  * claim.
  */
 export async function applyMerge(input) {
-    const refused = await refusals(input);
+    // Read once, here, and passed down. The comment on `archivePath` has always
+    // claimed the refusal and the move cannot disagree about the date; until this
+    // it computed a fresh `new Date()` on every call, four times per merge, so
+    // the property it named was precisely the one not provided. A merge that
+    // straddles midnight would have refused against one directory and written to
+    // another — rare, and silent when it happens, which is the combination this
+    // repository treats as worth the line.
+    const stamp = new Date().toISOString().slice(0, 10);
+    const refused = await refusals(input, stamp);
     if (refused.length > 0)
         return { issues: refused, written: [] };
     const { root } = input;
@@ -169,7 +178,32 @@ export async function applyMerge(input) {
     }
     for (const file of [...byFile.keys()].sort(byCodeUnit)) {
         const source = await readFile(file, 'utf8');
-        const spliced = spliceRequirements(file, source, byFile.get(file));
+        let spliced;
+        try {
+            spliced = spliceRequirements(file, source, byFile.get(file));
+        }
+        catch (err) {
+            // The emitter refused a value it cannot write as source — today only a
+            // `__proto__` param key, which the schema rejects before `--apply` runs.
+            // Caught rather than left to the CLI's crash envelope so the account of
+            // what this merge had already written survives: `--apply` is destructive
+            // and half a merge reported as a bare stack is the shape a resume cannot
+            // read. The write for *this* file has not happened — the throw is in the
+            // text generation, above `writeAtomic`.
+            if (!(err instanceof UnwritableValue))
+                throw err;
+            return {
+                issues: [
+                    {
+                        level: 'ERROR',
+                        code: 'internal-error',
+                        file: relativePath(root, file),
+                        message: `${relativePath(root, file)} could not be written: ${err.message}.`,
+                    },
+                ],
+                written,
+            };
+        }
         if (spliced === undefined) {
             // Unreachable through the command — the gate read this file as a literal
             // moments ago — so it is reported as the internal inconsistency it is
@@ -215,7 +249,7 @@ export async function applyMerge(input) {
     }
     // --- 3) Move the change folder, last.
     const from = join(root, 'changes', input.changeName);
-    const to = archivePath(input);
+    const to = archivePath(input, stamp);
     if (await exists(from)) {
         await mkdir(dirname(to), { recursive: true });
         await rename(from, to);
@@ -227,9 +261,13 @@ export async function applyMerge(input) {
  * Where a change is archived to. One function because two places ask — the
  * refusal that checks it is free, and the move that performs it — and a date
  * computed twice could straddle midnight and disagree with itself.
+ *
+ * So the date is not computed here: `stamp` comes from `applyMerge`, which
+ * reads it once for the whole operation. A pure function of its arguments is
+ * what makes "the two places cannot disagree" a property of the code rather
+ * than of how fast it ran.
  */
-function archivePath(input) {
-    const stamp = new Date().toISOString().slice(0, 10);
+function archivePath(input, stamp) {
     return join(input.root, 'archive', `${stamp}-${input.changeName}`);
 }
 async function exists(path) {