@am_shork/attest 0.7.0 → 0.7.2

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

package/dist/cli/action.d.ts

@@ -0,0 +1,48 @@
+import { type JsonCommand, type JsonReport } from './json.js';
+/** What an action produces: the machine report plus how to render it for humans. */
+export interface Rendered {
+    report: JsonReport;
+    human: () => void;
+}
+export interface ActionOptions {
+    json?: boolean;
+}
+/**
+ * Send everything written to `process.stdout` to stderr until the returned
+ * function is called.
+ *
+ * This is what keeps the `--json` promise against output Attest does not write
+ * — the third obligation on the machine surface in design §9.1, stated there
+ * because it belongs to the command shell rather than to any emitter, and
+ * attested by ATX-64. The child Vitest run of `verify`/`archive` executes
+ * project code,
+ * and a bare `process.stdout.write` in a spec reaches this stream — `silent:
+ * true` only suppresses Vitest's *console interception*, which such a write
+ * never enters. Measured: the child's writes do arrive through the parent's
+ * `process.stdout.write` rather than through a separately inherited descriptor,
+ * which is why patching it here is sufficient and a change of Vitest pool is
+ * the thing that could quietly make it insufficient. The scenario under ATX-64
+ * runs a real child run for that reason, rather than asserting on this function
+ * with a stub.
+ *
+ * Diverted, not discarded: a human reading a red pipeline still needs the run
+ * output, and stderr is the stream no `--json` consumer parses. It is not
+ * sanitised on the way — `verify` executes project code by design, so painting
+ * the terminal is not a capability this path lacked (design §9.1 scopes its
+ * guarantee to what Attest itself writes).
+ */
+export declare function divertStdout(): () => void;
+/**
+ * Run one command's work with a single output + exit-code contract:
+ *  - success: print the JSON report (`--json`) or the human rendering, and set
+ *    the exit code from `report.ok` — the one source of the verdict.
+ *  - failure: under `--json`, still emit one parseable `internal-error`
+ *    envelope on stdout; otherwise print the stack on stderr. Exit code 1.
+ *
+ * Under `--json` the action runs with stdout diverted, so the report is the
+ * only thing on that stream. The divert is released before either rendering
+ * runs — the report has to reach the real stdout, and the human path was never
+ * under the promise.
+ */
+export declare function runAction(command: JsonCommand, opts: ActionOptions, action: () => Promise<Rendered>): Promise<void>;
+//# sourceMappingURL=action.d.ts.map

package/dist/cli/action.js

@@ -0,0 +1,100 @@
+// The convergence point every command passes through: one output, one exit
+// code (design §9). It lives here rather than in `cli/index.ts` because that
+// module calls `program.parseAsync()` at import time — importing it to test the
+// contract would run the CLI. The interface is the test surface, so the
+// contract moved to where a scenario can cross the same seam a command does.
+import { renderJson, errorReport } from './json.js';
+import { formatCrash } from './report.js';
+import { packageVersion } from '../core/version.js';
+const VERSION = packageVersion();
+/**
+ * Send everything written to `process.stdout` to stderr until the returned
+ * function is called.
+ *
+ * This is what keeps the `--json` promise against output Attest does not write
+ * — the third obligation on the machine surface in design §9.1, stated there
+ * because it belongs to the command shell rather than to any emitter, and
+ * attested by ATX-64. The child Vitest run of `verify`/`archive` executes
+ * project code,
+ * and a bare `process.stdout.write` in a spec reaches this stream — `silent:
+ * true` only suppresses Vitest's *console interception*, which such a write
+ * never enters. Measured: the child's writes do arrive through the parent's
+ * `process.stdout.write` rather than through a separately inherited descriptor,
+ * which is why patching it here is sufficient and a change of Vitest pool is
+ * the thing that could quietly make it insufficient. The scenario under ATX-64
+ * runs a real child run for that reason, rather than asserting on this function
+ * with a stub.
+ *
+ * Diverted, not discarded: a human reading a red pipeline still needs the run
+ * output, and stderr is the stream no `--json` consumer parses. It is not
+ * sanitised on the way — `verify` executes project code by design, so painting
+ * the terminal is not a capability this path lacked (design §9.1 scopes its
+ * guarantee to what Attest itself writes).
+ */
+export function divertStdout() {
+    const stream = process.stdout;
+    // The prior *state* of the property, not the function it held. `write` is
+    // inherited from `Writable.prototype`, so the patch below is a new own
+    // property and undoing it means removing that property — assigning the old
+    // function back would leave a bound copy shadowing the prototype forever, and
+    // would silently swallow anyone else's patch on a nested divert.
+    const owned = Object.getOwnPropertyDescriptor(stream, 'write');
+    const divert = (chunk, encoding, callback) => typeof encoding === 'function'
+        ? process.stderr.write(chunk, encoding)
+        : process.stderr.write(chunk, encoding, callback);
+    stream.write = divert;
+    return () => {
+        if (owned)
+            Object.defineProperty(stream, 'write', owned);
+        else
+            Reflect.deleteProperty(stream, 'write');
+    };
+}
+/**
+ * Run one command's work with a single output + exit-code contract:
+ *  - success: print the JSON report (`--json`) or the human rendering, and set
+ *    the exit code from `report.ok` — the one source of the verdict.
+ *  - failure: under `--json`, still emit one parseable `internal-error`
+ *    envelope on stdout; otherwise print the stack on stderr. Exit code 1.
+ *
+ * Under `--json` the action runs with stdout diverted, so the report is the
+ * only thing on that stream. The divert is released before either rendering
+ * runs — the report has to reach the real stdout, and the human path was never
+ * under the promise.
+ */
+export async function runAction(command, opts, action) {
+    try {
+        const { report, human } = await withStdoutDiverted(opts.json === true, action);
+        if (opts.json)
+            console.log(renderJson(report));
+        else
+            human();
+        process.exitCode = report.ok ? 0 : 1;
+    }
+    catch (err) {
+        if (opts.json) {
+            // Unsanitised on purpose: `JSON.stringify` escapes every C0 character,
+            // so these bytes cannot carry one out (see report.ts). That is a claim
+            // about what this line writes and nothing wider — what the project under
+            // test writes is the divert's business, above.
+            console.log(renderJson(errorReport(VERSION, command, err)));
+        }
+        else {
+            console.error(formatCrash(err));
+        }
+        process.exitCode = 1;
+    }
+}
+/** Run `action` with stdout diverted when `divert`, restoring on every path. */
+async function withStdoutDiverted(divert, action) {
+    if (!divert)
+        return action();
+    const release = divertStdout();
+    try {
+        return await action();
+    }
+    finally {
+        release();
+    }
+}
+//# sourceMappingURL=action.js.map

package/dist/cli/index.js

@@ -7,14 +7,22 @@
 // The exit code is always derived from that report's `ok`, so the JSON verdict
 // and the process status can never disagree — including on the crash path,
 // where the report is an `internal-error` envelope instead of a bare stack.
+//
+// Both halves of that promise are kept by `runAction` (cli/action.ts), which is
+// where the contract is stated and tested; this file only supplies the work.
 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`
+// is argv, which on a fork MR pipeline is written by the repository's own CI
+// config — so it is the project's text, not the operator's (ATX-37).
+import { inline } from '../core/terminal.js';
+import { runAction } from './action.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 { archiveReport, checkReport, coverReport, initReport, renderReport, statusReport, verifyReport, } from './json.js';
 import { packageVersion } from '../core/version.js';
 const VERSION = packageVersion();
 /** `runArchive` in the shape `--apply` returns, so the two share one call site. */
@@ -47,34 +55,6 @@ const VITEST_CONFIG_HELP = 'load this Vitest config in the child run (transforms
 function vitestConfig(opts) {
     return opts.vitestConfig ? resolve(process.cwd(), opts.vitestConfig) : undefined;
 }
-/**
- * Run one command's work with a single output + exit-code contract:
- *  - success: print the JSON report (`--json`) or the human rendering, and set
- *    the exit code from `report.ok` — the one source of the verdict.
- *  - failure: under `--json`, still emit one parseable `internal-error`
- *    envelope on stdout; otherwise print the stack on stderr. Exit code 1.
- */
-async function runAction(command, opts, action) {
-    try {
-        const { report, human } = await action();
-        if (opts.json)
-            console.log(renderJson(report));
-        else
-            human();
-        process.exitCode = report.ok ? 0 : 1;
-    }
-    catch (err) {
-        if (opts.json) {
-            // Unsanitised on purpose: `JSON.stringify` escapes every C0 character, so
-            // the machine surface was never the exposed one (see report.ts).
-            console.log(renderJson(errorReport(VERSION, command, err)));
-        }
-        else {
-            console.error(formatCrash(err));
-        }
-        process.exitCode = 1;
-    }
-}
 program
     .command('check')
     .description('Static structural validation (fast CI pre-check); runs no project code.')
@@ -168,7 +148,7 @@ program
                 report: renderReport(VERSION, issues, opts.out),
                 human: () => {
                     if (issues.length === 0)
-                        console.log(chalk.green(`✓ ${opts.out} is up to date.`));
+                        console.log(chalk.green(`✓ ${inline(opts.out ?? '')} is up to date.`));
                     else {
                         console.log(formatIssues(issues));
                         console.log(summarize(issues));
@@ -188,7 +168,7 @@ program
                     console.log(summarize(issues));
                 }
                 else if (dest) {
-                    console.log(chalk.green(`✓ Wrote ${opts.out}`));
+                    console.log(chalk.green(`✓ Wrote ${inline(opts.out ?? '')}`));
                 }
                 else {
                     process.stdout.write(markdown);
@@ -261,7 +241,6 @@ program
                 console.log(summarize(result.issues));
                 return;
             }
-            console.log(chalk.bold(`Change: ${result.change}`));
             console.log(formatStatus(result));
         },
     };

package/dist/cli/report.js

@@ -166,7 +166,15 @@ const STATE_MARK = {
  * the argument that keeps `render --check` comparing documents rather than bytes.
  */
 export function formatStatus(result) {
-    const lines = [];
+    // The header is built here rather than in the CLI action, and that is a fix
+    // rather than a tidy-up. It was interpolated and printed in `cli/index.ts`,
+    // which put it past the sanitiser — three lines above a closing line that
+    // puts the same value through `inline`. `ATX-37` covers "everything the CLI
+    // writes to a terminal", and a write that lives in the shell can only be
+    // attested by spawning a process, because `cli/index.ts` runs the CLI at
+    // import. Moving the line to the module that already owns this report makes
+    // the obligation reachable by a scenario — the interface is the test surface.
+    const lines = [chalk.bold(`Change: ${inline(result.change)}`)];
     if (result.rows.length === 0) {
         lines.push(chalk.dim('(this change adds 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", "spec-load-failed", "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", "unreadable-file"];
 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',
@@ -54,6 +55,7 @@ export const ISSUE_CODES = [
     'unbound-param',
     'uncovered-requirement',
     'unknown-target',
+    'unreadable-file',
 ];
 const DOCUMENTED = new Set(ISSUE_CODES);
 const REPO = 'https://gitlab.com/Pseudorca/attest/-/blob';

package/dist/core/locate.d.ts

@@ -141,22 +141,21 @@ export declare function idPrefix(id: string): string;
  * 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. The
- * previous `Promise.all(files.map(readFile))` held every spec file in memory at
- * once — measured at ~47 MiB on a synthetic tree of 6000 files — for input size
- * that is not ours to choose, since `check` is the command this project tells
- * people to run first on an untrusted fork MR. Parsing at the point of arrival
- * makes the peak `PARSE_CONCURRENCY` sources instead of `files.length`, and the
- * plan is the only thing that still grows with the tree.
+ * 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). */
-export declare function parseAllSpecFiles(root: string): Promise<AttestPlan>;
+export declare function parseSpecs(files: string[], displayRoot: string): Promise<{
+    plan: AttestPlan;
+    issues: Issue[];
+}>;
 /**
  * Spec-shaped files sitting under `root/changes` — the location a change's
  * specs used to live at, and which nothing walks any more (design §7).

package/dist/core/locate.js

@@ -95,6 +95,43 @@ export async function scanProject(root) {
     }
     return { reqsFiles, specFiles, proposedSpecFiles };
 }
+/**
+ * The message an unreadable file gets, in one place because two call sites
+ * raise it — a registry and a spec — and they must not drift into two
+ * descriptions of one condition (ATX-65).
+ */
+function unreadableIssue(err) {
+    // `RangeError` in practice, from the call stack running out inside
+    // TypeScript's recursive-descent parser. Caught as `unknown` rather than
+    // narrowed to it: the guard's promise is that *no* throw from one file ends
+    // 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);
+    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.`,
+    };
+}
+/**
+ * `reader.read`, with a throw turned into an issue about that file.
+ *
+ * At the loop rather than inside either reader, because what is being kept is a
+ * property of the *run* — one file's failure is not the run's failure — and
+ * both readers need it. `readRegistry` folds these concurrently, so an
+ * uncaught throw here rejects the whole `Promise.all` and ends the command:
+ * measured, a 20,000-deep literal in one `params` value reduced `attest check`
+ * to a single `internal-error` (design §5.1, ATX-65).
+ */
+async function readGuarded(reader, file) {
+    try {
+        return await reader.read(file);
+    }
+    catch (err) {
+        return { issue: unreadableIssue(err) };
+    }
+}
 /**
  * Read registries by **executing** the module through the Vite loader.
  *
@@ -207,7 +244,7 @@ export async function loadRegistry(root, reader, files) {
     const paths = files ?? (await scanProject(root)).reqsFiles;
     // Read the files concurrently, then fold the results in sorted file order:
     // the issue list stays deterministic regardless of which one finished first.
-    const loaded = await Promise.all(paths.map(async (file) => ({ file, outcome: await reader.read(file) })));
+    const loaded = await Promise.all(paths.map(async (file) => ({ file, outcome: await readGuarded(reader, file) })));
     const registry = {};
     const issues = [];
     const unreadableFiles = [];
@@ -294,13 +331,11 @@ const PARSE_CONCURRENCY = 32;
  * 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. The
- * previous `Promise.all(files.map(readFile))` held every spec file in memory at
- * once — measured at ~47 MiB on a synthetic tree of 6000 files — for input size
- * that is not ours to choose, since `check` is the command this project tells
- * people to run first on an untrusted fork MR. Parsing at the point of arrival
- * makes the peak `PARSE_CONCURRENCY` sources instead of `files.length`, and the
- * plan is the only thing that still grows with the tree.
+ * 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
@@ -311,12 +346,24 @@ export async function parseSpecs(files, displayRoot) {
     // Indexed rather than appended, so the merge below follows the input order
     // whatever order the reads finish in.
     const parsed = new Array(files.length);
+    // Same index space, so a file contributes either a parse or an issue and the
+    // two lists cannot disagree about which file is which.
+    const failures = 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);
+            const display = relativePath(displayRoot, file);
+            // Per file, for the reason `readGuarded` exists above: these run
+            // concurrently, so one throw rejects the whole `Promise.all` and takes
+            // the command with it. A hostile spec scraps only itself (ATX-65).
+            try {
+                parsed[i] = parseSpecFile(display, await readFile(file, 'utf8'));
+            }
+            catch (err) {
+                parsed[i] = { scenarios: [], paramRefs: [] };
+                failures[i] = { ...unreadableIssue(err), file: display };
+            }
         }
     };
     await Promise.all(Array.from({ length: Math.min(PARSE_CONCURRENCY, files.length) }, worker));
@@ -325,11 +372,7 @@ export async function parseSpecs(files, displayRoot) {
         plan.scenarios.push(...one.scenarios);
         plan.paramRefs.push(...one.paramRefs);
     }
-    return plan;
-}
-/** Parse every `*.spec.ts` under root into one merged plan (file paths shown relative to root). */
-export async function parseAllSpecFiles(root) {
-    return parseSpecs(await findFiles(root, isSpecFile), root);
+    return { plan, issues: failures.filter((i) => i !== undefined) };
 }
 /**
  * Spec-shaped files sitting under `root/changes` — the location a change's

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';
@@ -178,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

package/dist/core/order.d.ts

@@ -1,3 +1,20 @@
 /** Compare by UTF-16 code unit — the same order as a bare `Array#sort()`. */
 export declare function byCodeUnit(a: string, b: string): number;
+/**
+ * A JSON value with every object's keys in code-unit order, at every depth.
+ *
+ * `JSON.stringify` writes object keys in insertion order, which is *how the
+ * source happened to be written* — the thing this module exists to keep out of
+ * anything compared or committed. Two callers need the same guarantee for the
+ * same reason, one depth apart:
+ *
+ * - `apply.ts` canonicalises a requirement to decide `add-conflict`, so an
+ *   identical copy written with its keys in another order must not read as a
+ *   conflict with itself.
+ * - `render.ts` emits a structured param as JSON, and ATX-10 holds the same
+ *   registry to the same bytes.
+ *
+ * Arrays keep their order: an array is data whose order is part of the value.
+ */
+export declare function sortDeep<T>(value: T): T;
 //# sourceMappingURL=order.d.ts.map

package/dist/core/order.js

@@ -10,4 +10,29 @@
 export function byCodeUnit(a, b) {
     return a < b ? -1 : a > b ? 1 : 0;
 }
+/**
+ * A JSON value with every object's keys in code-unit order, at every depth.
+ *
+ * `JSON.stringify` writes object keys in insertion order, which is *how the
+ * source happened to be written* — the thing this module exists to keep out of
+ * anything compared or committed. Two callers need the same guarantee for the
+ * same reason, one depth apart:
+ *
+ * - `apply.ts` canonicalises a requirement to decide `add-conflict`, so an
+ *   identical copy written with its keys in another order must not read as a
+ *   conflict with itself.
+ * - `render.ts` emits a structured param as JSON, and ATX-10 holds the same
+ *   registry to the same bytes.
+ *
+ * Arrays keep their order: an array is data whose order is part of the value.
+ */
+export function sortDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortDeep);
+    // `typeof null === 'object'`, and a null param is a value like any other.
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const entries = Object.entries(value).sort(([a], [b]) => byCodeUnit(a, b));
+    return Object.fromEntries(entries.map(([k, v]) => [k, sortDeep(v)]));
+}
 //# sourceMappingURL=order.js.map