@am_shork/attest 0.8.0 → 0.9.0

package/README.md

@@ -125,7 +125,8 @@ attest verify   # run tests + coverage + drift, graded report
 attest cover    # which requirements lack a scenario
 attest render   # the requirements as Markdown, for people who don't read TS
 attest archive <change>   # gate a proposed change: green + covered + no drift
-attest status <change>    # what that gate still wants, without running anything
+attest status <change>    # per added id: scenario written? seen red? (part of that
+                          # gate, without running anything — never a verdict)
 ```
 
 Every command takes the project root as an optional last argument, and `--json`
@@ -166,7 +167,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.8.0/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.9.0/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section

package/dist/cli/report.js

@@ -190,7 +190,15 @@ export function formatStatus(result) {
     }
     const { proven } = result.counts;
     lines.push(chalk.dim(`— ${plural(result.rows.length, 'added requirement')}, ${proven} ready to archive`));
-    lines.push(chalk.dim(`Not a verdict: run \`attest archive ${inline(result.change)}\` to run the suite.`));
+    // Two pointers, because this command answers less than a reader assumes on
+    // both sides. `archive` is the verdict it deliberately cannot give. `check` is
+    // the half it deliberately does not duplicate: a proposed spec no delta
+    // claims, or one whose merged name is taken, is a static fact about this
+    // change that `check` already reports — and reporting it here too would put a
+    // second answer to one question in the tree, which is what this project takes
+    // apart everywhere else. Naming it is the whole cost of not absorbing it.
+    lines.push(chalk.dim(`Not a verdict: run \`attest archive ${inline(result.change)}\` to run the suite, ` +
+        `\`attest check\` for the proposed specs themselves.`));
     return lines.join('\n');
 }
 /**

package/dist/core/apply.d.ts

@@ -1,5 +1,5 @@
 import type { RegistryDelta } from './registry.js';
-import type { Issue, Registry } from './types.js';
+import type { Issue, Registry, Requirement } from './types.js';
 export interface ApplyResult {
     registry: Registry;
     issues: Issue[];
@@ -12,6 +12,14 @@ export interface ApplyResult {
  * than off `delta.added`, so the two can never be scoped differently.
  */
 export declare function addedIds(d: RegistryDelta): string[];
+/**
+ * The ids a delta MODIFIEs — the scope of `--apply`'s field-level write-back.
+ *
+ * Here for the reason `addedIds` is: two places ask, the merge that writes them
+ * and the refusal that checks their prefix is owned, and a delta's operations
+ * must not be enumerated twice.
+ */
+export declare function modifiedIds(d: RegistryDelta): string[];
 /**
  * The ids a delta **claims**: what it adds, renames to, or modifies.
  *
@@ -33,4 +41,13 @@ export declare function claimedIds(d: RegistryDelta): string[];
  * base registry is never mutated. Applying the same delta twice is a no-op.
  */
 export declare function applyDelta(base: Registry, d: RegistryDelta): ApplyResult;
+/**
+ * Content equality via canonical JSON (params key order does not matter).
+ *
+ * Exported because `--apply` asks the same question twice — whether a modified
+ * entry is already what the end state says, and whether the bytes it wrote read
+ * back as it — and a second spelling of "the same requirement" is a second
+ * answer the moment `Requirement` gains a field.
+ */
+export declare function sameRequirement(a: Requirement, b: Requirement): boolean;
 //# sourceMappingURL=apply.d.ts.map

package/dist/core/apply.js

@@ -14,6 +14,16 @@ import { byCodeUnit, sortDeep } from './order.js';
 export function addedIds(d) {
     return Object.keys(d.added ?? {});
 }
+/**
+ * The ids a delta MODIFIEs — the scope of `--apply`'s field-level write-back.
+ *
+ * Here for the reason `addedIds` is: two places ask, the merge that writes them
+ * and the refusal that checks their prefix is owned, and a delta's operations
+ * must not be enumerated twice.
+ */
+export function modifiedIds(d) {
+    return Object.keys(d.modified ?? {}).sort(byCodeUnit);
+}
 /**
  * The ids a delta **claims**: what it adds, renames to, or modifies.
  *
@@ -177,8 +187,15 @@ function firstMessage(error) {
     const path = first.path.map(String).join('.');
     return path ? `${path}: ${first.message}` : first.message;
 }
-/** Content equality via canonical JSON (params key order does not matter). */
-function sameRequirement(a, b) {
+/**
+ * Content equality via canonical JSON (params key order does not matter).
+ *
+ * Exported because `--apply` asks the same question twice — whether a modified
+ * entry is already what the end state says, and whether the bytes it wrote read
+ * back as it — and a second spelling of "the same requirement" is a second
+ * answer the moment `Requirement` gains a field.
+ */
+export function sameRequirement(a, b) {
     return canonical(a) === canonical(b);
 }
 function canonical(req) {

package/dist/core/locate.d.ts

@@ -27,6 +27,20 @@ export declare const isSpecFile: (name: string) => boolean;
  * serial `for await` spent one filesystem round-trip per directory, which is
  * the dominant cost of `check` on a large repo. The result is sorted, so the
  * order never depends on which `readdir` happened to resolve first.
+ *
+ * Concurrency is bounded, for the reason `parseSpecs` bounds its own: the input
+ * size is not ours to choose, `check` being what this project tells people to
+ * run first on an untrusted fork MR. What must not come back is a fan-out whose
+ * peak is the shape of the tree rather than a constant — which is what
+ * recursing through `Promise.all(subdirs)` gave, and what
+ * `tests/locate-fanout.spec.ts` pins.
+ *
+ * A level at a time, rather than one pool over a queue that grows as directories
+ * are discovered: the pool would have to keep workers alive while the queue is
+ * momentarily empty but another worker may still push to it, and that
+ * termination condition is the part worth not owning. The cost is a barrier per
+ * depth, which is paid in tree *depth* — small, and bounded by the filesystem —
+ * while the fan-out being bounded is paid in tree *width*, which is not.
  */
 export declare function findFiles(root: string, match: (name: string) => boolean): Promise<string[]>;
 /** The file sets every command needs, collected in one pass. */
@@ -167,10 +181,11 @@ export declare function idPrefix(id: string): string;
  * 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.
+ * `findFiles` above bounds its own fan-out the same way and through the same
+ * helper. It was left unbounded when this one was capped, on the grounds that
+ * the failure it invited — descriptor exhaustion — could not be produced on
+ * either development platform; what closed it is that the peak itself is
+ * portable arithmetic, which is the standard this half was accepted on.
  */
 export declare function parseSpecs(files: string[], displayRoot: string): Promise<{
     plan: AttestPlan;

package/dist/core/locate.js

@@ -40,6 +40,44 @@ export const isProposedSpecFile = (name) => name.endsWith('.proposed.spec.ts');
  * of them until its gate passes.
  */
 export const isSpecFile = (name) => name.endsWith('.spec.ts') && !isProposedSpecFile(name);
+/**
+ * Run `fn` over every item with at most `limit` of them in flight.
+ *
+ * Extracted at the second call site rather than the first: this file has two
+ * unbounded fan-outs to close, one over directories and one over files, and
+ * a shape written twice is a shape one of the two copies will eventually be
+ * fixed without.
+ *
+ * The order `fn` is *called* in is the input order; the order it *completes* in
+ * is not, so a caller that needs a stable result either indexes into a
+ * preallocated array by `index` or sorts afterwards. Both callers here do one of
+ * those, deliberately.
+ *
+ * No result is collected and none is needed — both callers write into something
+ * they already own, and a version returning `T[]` would have to choose an
+ * ordering on their behalf. A throw from `fn` propagates and abandons the rest,
+ * which is the existing behaviour at both sites: `parseSpecs` catches per file
+ * so that one hostile spec scraps only itself (ATX-65), and a failed `readdir`
+ * really does end the walk.
+ */
+async function forEachBounded(items, limit, fn) {
+    let cursor = 0;
+    const worker = async () => {
+        for (let i = cursor++; i < items.length; i = cursor++) {
+            await fn(items[i], i);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+}
+/**
+ * How many directories are open at once during the walk. The same figure as
+ * `PARSE_CONCURRENCY` and deliberately not the same constant: the two bound
+ * different resources, and sharing one would make either impossible to tune
+ * without moving the other. High enough that the walk stays I/O bound on any
+ * real project, low enough that what is in flight is a constant rather than the
+ * shape of the input.
+ */
+const WALK_CONCURRENCY = 32;
 /**
  * Recursively find files under root whose basename matches `match`.
  *
@@ -47,25 +85,41 @@ export const isSpecFile = (name) => name.endsWith('.spec.ts') && !isProposedSpec
  * serial `for await` spent one filesystem round-trip per directory, which is
  * the dominant cost of `check` on a large repo. The result is sorted, so the
  * order never depends on which `readdir` happened to resolve first.
+ *
+ * Concurrency is bounded, for the reason `parseSpecs` bounds its own: the input
+ * size is not ours to choose, `check` being what this project tells people to
+ * run first on an untrusted fork MR. What must not come back is a fan-out whose
+ * peak is the shape of the tree rather than a constant — which is what
+ * recursing through `Promise.all(subdirs)` gave, and what
+ * `tests/locate-fanout.spec.ts` pins.
+ *
+ * A level at a time, rather than one pool over a queue that grows as directories
+ * are discovered: the pool would have to keep workers alive while the queue is
+ * momentarily empty but another worker may still push to it, and that
+ * termination condition is the part worth not owning. The cost is a barrier per
+ * depth, which is paid in tree *depth* — small, and bounded by the filesystem —
+ * while the fan-out being bounded is paid in tree *width*, which is not.
  */
 export async function findFiles(root, match) {
     const out = [];
-    const walk = async (dir) => {
-        const entries = await readdir(dir, { withFileTypes: true });
-        const subdirs = [];
-        for (const e of entries) {
-            const full = join(dir, e.name);
-            if (e.isDirectory()) {
-                if (!SKIP_DIRS.has(e.name))
-                    subdirs.push(full);
-            }
-            else if (e.isFile() && match(e.name)) {
-                out.push(full);
+    let level = [root];
+    while (level.length > 0) {
+        const next = [];
+        await forEachBounded(level, WALK_CONCURRENCY, async (dir) => {
+            const entries = await readdir(dir, { withFileTypes: true });
+            for (const e of entries) {
+                const full = join(dir, e.name);
+                if (e.isDirectory()) {
+                    if (!SKIP_DIRS.has(e.name))
+                        next.push(full);
+                }
+                else if (e.isFile() && match(e.name)) {
+                    out.push(full);
+                }
             }
-        }
-        await Promise.all(subdirs.map(walk));
-    };
-    await walk(root);
+        });
+        level = next;
+    }
     return out.sort(byCodeUnit);
 }
 /**
@@ -362,10 +416,11 @@ const PARSE_CONCURRENCY = 32;
  * 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.
+ * `findFiles` above bounds its own fan-out the same way and through the same
+ * helper. It was left unbounded when this one was capped, on the grounds that
+ * the failure it invited — descriptor exhaustion — could not be produced on
+ * either development platform; what closed it is that the peak itself is
+ * portable arithmetic, which is the standard this half was accepted on.
  */
 export async function parseSpecs(files, displayRoot) {
     // Indexed rather than appended, so the merge below follows the input order
@@ -374,24 +429,19 @@ export async function parseSpecs(files, displayRoot) {
     // 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 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 forEachBounded(files, PARSE_CONCURRENCY, async (file, i) => {
+        const display = relativePath(displayRoot, file);
+        // Per file, for the reason `readGuarded` exists above: these run
+        // concurrently, so one throw would abandon the rest and take the command
+        // with it. A hostile spec scraps only itself (ATX-65).
+        try {
+            parsed[i] = parseSpecFile(display, await readFile(file, 'utf8'));
         }
-    };
-    await Promise.all(Array.from({ length: Math.min(PARSE_CONCURRENCY, files.length) }, worker));
+        catch (err) {
+            parsed[i] = { scenarios: [], paramRefs: [] };
+            failures[i] = { ...unreadableIssue(err), file: display };
+        }
+    });
     const plan = { scenarios: [], paramRefs: [] };
     for (const one of parsed) {
         plan.scenarios.push(...one.scenarios);

package/dist/core/merge.js

@@ -4,8 +4,11 @@
 // until now a human then transcribed it by hand with nothing checking the
 // transcription. This is that step, and the whole of why it is allowed to exist
 // where the `AGENTS.md` merge tool was not: the registry is a literal Attest
-// defines, so the result of an edit is checkable by re-reading it, and the edit
-// itself is a pure insertion (`splice.ts`).
+// defines, so the result of an edit is checkable by re-reading it — and this
+// re-reads it (`verifyWritten`), rather than resting on the sentence. The edits
+// are bounded to match: an ADDED requirement is a pure insertion, and a MODIFIED
+// one replaces the span of a single value inside an entry it never rewrites
+// (`splice.ts`).
 //
 // **It is re-runnable, not atomic.** No primitive spans one edit, N renames and
 // a directory move, and a scratch copy of the project root would have to be
@@ -30,10 +33,11 @@
 // 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, UnwritableValue } from './splice.js';
+import { repointImport, spliceModifications, spliceRequirements, UnwritableValue, } from './splice.js';
+import { readRegistrySource } from './static-registry.js';
 import { writeAtomic } from './write.js';
 import { idPrefix } from './locate.js';
-import { addedIds } from './apply.js';
+import { addedIds, modifiedIds, sameRequirement } from './apply.js';
 import { byCodeUnit } from './order.js';
 import { relativePath } from './paths.js';
 /** `x.proposed.spec.ts` -> `x.spec.ts`, in place. */
@@ -48,8 +52,8 @@ 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, stamp) {
-    const issues = [];
+async function refusals(input, stamp, planned) {
+    const issues = [...planned];
     const { delta, root, changeName } = input;
     const archive = archivePath(input, stamp);
     // 0) The destination already exists. Checked here, before anything is
@@ -67,28 +71,34 @@ async function refusals(input, stamp) {
         });
     }
     // 1) Operations this does not perform. The gate applies all four in memory to
-    // reach its verdict; only writing them back is limited to ADDED, because
-    // REMOVED cannot say which comments belonged to the entry it deletes and
-    // MODIFIED is a formatting-preserving edit inside an existing literal. Both
-    // are the "destructive on a file the user cannot regenerate" shape.
+    // reach its verdict; writing them back covers ADDED and MODIFIED, and stops
+    // there because REMOVED cannot say which comments belonged to the entry it
+    // deletes — the "destructive on a file the user cannot regenerate" shape.
+    // MODIFIED was refused by this same clause until it was written at the
+    // granularity of a *value* rather than an entry, which is where that sentence
+    // stops applying and REMOVED's does not: an entry being deleted has no smaller
+    // span to fall back to (`splice.ts`).
     const unsupported = [
         delta.renamed?.length ? 'renamed' : '',
         delta.removed?.length ? 'removed' : '',
-        Object.keys(delta.modified ?? {}).length ? 'modified' : '',
     ].filter(Boolean);
     if (unsupported.length > 0) {
         issues.push({
             level: 'ERROR',
             code: 'apply-unsupported-delta',
             file: relativePath(root, join(root, 'changes', changeName)),
-            message: `--apply writes back ADDED requirements only, and this change's delta also carries ${unsupported.join(', ')}. ` +
+            message: `--apply writes back ADDED and MODIFIED requirements, and this change's delta also carries ${unsupported.join(', ')}. ` +
                 `The gate above still checked all of it — merge the remaining operations into the registry by hand, then run this command again to confirm.`,
         });
     }
-    // 2) An added id whose prefix no registry file claims. Which file it belongs
+    // 2) An id whose prefix no registry file claims. Which file it belongs
     // in — or whether a file should be created for it — is not something the gate
-    // verified, and guessing would file a requirement somewhere nobody chose.
-    for (const id of unmergedAdded(input)) {
+    // verified, and guessing would file a requirement somewhere nobody chose. Over
+    // modified ids as well as added ones: an unowned prefix is why the merge cannot
+    // find the file, and reporting it as "no entry to modify" would send the reader
+    // to look inside a file this never opened.
+    const unowned = new Set([...unmergedAdded(input), ...modifiedIds(input.delta)]);
+    for (const id of [...unowned].sort(byCodeUnit)) {
         if (input.prefixOwners[idPrefix(id)] === undefined) {
             issues.push({
                 level: 'ERROR',
@@ -146,6 +156,182 @@ function registryTargets(input, reqIds) {
 function unmergedAdded(input) {
     return addedIds(input.delta).filter((id) => !Object.hasOwn(input.base, id));
 }
+/**
+ * The requirements this change modifies that the registry on disk does not
+ * already hold in its end state.
+ *
+ * The MODIFIED half of re-runnability, and deliberately the same shape as
+ * `unmergedAdded`: derived from the tree as it currently is rather than from a
+ * list of what a previous run meant to do. An entry already equal to `applied`
+ * is not edited, so a re-run after a crash writes what is left and nothing else
+ * — and a delta restating a value it does not change writes nothing at all.
+ */
+function unmergedModified(input) {
+    const out = [];
+    for (const id of modifiedIds(input.delta)) {
+        const before = input.base[id];
+        const after = input.applied[id];
+        // A modified id the base does not have is `modify-missing`, which the gate
+        // reports and this never reaches; skipped rather than diagnosed a second
+        // time, because two commands answering for one condition is how they come to
+        // disagree.
+        if (!before || !after || sameRequirement(before, after))
+            continue;
+        out.push({ id, before, after });
+    }
+    return out;
+}
+/**
+ * What every registry file should end up holding, or why it cannot — computed
+ * without writing anything.
+ *
+ * Split from the write for one reason: a refusal that fires after two files have
+ * landed makes "refused whole" a claim with an exception in it, which is the
+ * kind of claim nobody can rely on (the note on `refusals` step 0 says the same
+ * thing about the archive destination). Both edits to a file are composed here,
+ * modification before splice, and the splice re-reads the text the modification
+ * produced rather than an offset taken before it — an insertion point is a
+ * position in a file, and the modification has just moved bytes in front of it.
+ */
+async function planRegistries(input) {
+    const { root } = input;
+    const issues = [];
+    const added = new Map();
+    const modified = new Map();
+    for (const id of unmergedAdded(input)) {
+        const file = input.prefixOwners[idPrefix(id)];
+        if (!file)
+            continue; // Refused as `apply-no-prefix-owner`; not diagnosed twice.
+        const group = added.get(file) ?? {};
+        group[id] = input.applied[id];
+        added.set(file, group);
+    }
+    for (const change of unmergedModified(input)) {
+        const file = input.prefixOwners[idPrefix(change.id)];
+        if (!file)
+            continue;
+        modified.set(file, [...(modified.get(file) ?? []), change]);
+    }
+    const files = [];
+    for (const file of [...new Set([...added.keys(), ...modified.keys()])].sort(byCodeUnit)) {
+        const source = await readFile(file, 'utf8');
+        const mods = modified.get(file) ?? [];
+        const adds = added.get(file);
+        const ids = [...mods.map((m) => m.id), ...Object.keys(adds ?? {})].sort(byCodeUnit);
+        const changed = spliceModifications(file, source, mods);
+        if (!changed) {
+            issues.push(unreadable(root, file));
+            continue;
+        }
+        if (!changed.ok) {
+            issues.push(...changed.refusals.map((r) => modifyRefusal(root, file, r)));
+            continue;
+        }
+        let text = changed.source;
+        if (adds) {
+            try {
+                const spliced = spliceRequirements(file, text, adds);
+                if (spliced === undefined) {
+                    issues.push(unreadable(root, file));
+                    continue;
+                }
+                text = spliced;
+            }
+            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 because `--apply`
+                // is destructive and a bare stack is the shape a resume cannot read.
+                if (!(err instanceof UnwritableValue))
+                    throw err;
+                issues.push({
+                    level: 'ERROR',
+                    code: 'internal-error',
+                    file: relativePath(root, file),
+                    message: `${relativePath(root, file)} could not be written: ${err.message}.`,
+                });
+                continue;
+            }
+        }
+        files.push({ file, source, text, ids });
+    }
+    return { files, issues };
+}
+/**
+ * Whether the file just written reads back as the requirements it was written
+ * from — the check the whole argument for editing a hand-written registry rests
+ * on, performed rather than argued.
+ *
+ * "The result of an edit is checkable by re-reading it" is the clause that
+ * separates this from the merge tool the `AGENTS.md` proposal was rejected for,
+ * and until MODIFIED existed nothing did the re-reading: a pure insertion is
+ * right by construction, so the sentence was load-bearing without being
+ * exercised. A replacement is not, so the re-read is here for both — the added
+ * entries included, because a check that covered only the newer half would leave
+ * the older claim in exactly the state this is fixing.
+ *
+ * What it cannot see is the other half, and saying so is the point: a re-read
+ * compares *values*, and a comment or a blank line that went missing does not
+ * appear in a `Registry` at all. That is why the edit is bounded to the span of
+ * one value rather than trusted to this (`splice.ts`).
+ */
+async function verifyWritten(input, plan) {
+    const { root } = input;
+    const back = readRegistrySource(plan.file, await readFile(plan.file, 'utf8'));
+    const wrong = back.ok
+        ? plan.ids.filter((id) => {
+            const written = back.registry[id];
+            const proved = input.applied[id];
+            return !written || !proved || !sameRequirement(written, proved);
+        })
+        : plan.ids;
+    if (wrong.length === 0)
+        return undefined;
+    return {
+        level: 'ERROR',
+        code: 'internal-error',
+        file: relativePath(root, plan.file),
+        message: `${relativePath(root, plan.file)} was written, but reading it back does not give the requirements the gate proved (${wrong.join(', ')}). ` +
+            `Check that file against the change's delta before running anything else — the merge stopped here, so the steps after it have not run.`,
+    };
+}
+/** The registry the gate read a moment ago, unreadable to the merge. */
+function unreadable(root, file) {
+    // Unreachable through the command, so it is reported as the internal
+    // inconsistency it is rather than as a diagnosis about the user's registry.
+    return {
+        level: 'ERROR',
+        code: 'internal-error',
+        file: relativePath(root, file),
+        message: `${relativePath(root, file)} read as a registry for the gate but not for the merge.`,
+    };
+}
+/**
+ * One value the merge declined to write over, as a diagnostic.
+ *
+ * The code is the one an unsupported operation already carries: to a consumer
+ * branching on `code`, "this delta has a part `--apply` does not write" is the
+ * same fact whichever part it is, and the narrowing that made most MODIFIED
+ * deltas writable should not cost anyone a new string to handle. The `reqId` and
+ * the field are what changed, and both are in the message where the reader is.
+ */
+function modifyRefusal(root, file, refusal) {
+    const where = refusal.field ? `${refusal.reqId}.${refusal.field}` : refusal.reqId;
+    const why = {
+        comment: `a comment sits inside the value it would replace, and which side of that edit the comment belongs to is not something --apply can decide`,
+        'entry-not-found': `the registry file that owns its prefix holds no entry for it`,
+        'not-a-literal': `the value it would replace is not written as a literal`,
+        'param-dropped': `the proved end state does not carry that param, and a delta has no way to say one was removed`,
+    };
+    return {
+        level: 'ERROR',
+        code: 'apply-unsupported-delta',
+        reqId: refusal.reqId,
+        file: relativePath(root, file),
+        message: `--apply cannot write "${where}" into ${relativePath(root, file)}: ${why[refusal.reason]}. ` +
+            `Merge this requirement by hand, then run this command again to confirm — nothing has been written.`,
+    };
+}
 /**
  * Perform the merge, or refuse it whole.
  *
@@ -163,67 +349,27 @@ export async function applyMerge(input) {
     // 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);
+    // Every registry edit is computed before any of them is written, which is what
+    // makes "refused whole" true of the write-back and not only of the delta's
+    // shape: a comment sitting where a modification would land, or a value the
+    // emitter cannot write, is now found with the tree still untouched. Before
+    // MODIFIED existed the text generation could only fail on a `__proto__` key
+    // and it failed one file at a time, so this was the same claim by luck.
+    const planned = await planRegistries(input);
+    const refused = await refusals(input, stamp, planned.issues);
     if (refused.length > 0)
         return { issues: refused, written: [] };
     const { root } = input;
     const written = [];
-    // --- 1) Splice, first. See the note at the top of this file.
-    const byFile = new Map();
-    for (const id of unmergedAdded(input)) {
-        const file = input.prefixOwners[idPrefix(id)];
-        const group = byFile.get(file) ?? {};
-        group[id] = input.applied[id];
-        byFile.set(file, group);
-    }
-    for (const file of [...byFile.keys()].sort(byCodeUnit)) {
-        const source = await readFile(file, 'utf8');
-        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
-            // rather than as a diagnosis about the user's registry.
-            return {
-                issues: [
-                    {
-                        level: 'ERROR',
-                        code: 'internal-error',
-                        file: relativePath(root, file),
-                        message: `${relativePath(root, file)} read as a registry for the gate but not for the merge.`,
-                    },
-                ],
-                written,
-            };
-        }
-        if (spliced !== source) {
-            await writeAtomic(file, spliced);
-            written.push(relativePath(root, file));
-        }
+    // --- 1) Write the registries, first. See the note at the top of this file.
+    for (const plan of planned.files) {
+        if (plan.text === plan.source)
+            continue;
+        await writeAtomic(plan.file, plan.text);
+        written.push(relativePath(root, plan.file));
+        const mismatch = await verifyWritten(input, plan);
+        if (mismatch)
+            return { issues: [mismatch], written };
     }
     // --- 2) Repoint each claimed spec's delta import, then rename it in place.
     //