@am_shork/attest 0.5.0 → 0.7.0

package/dist/core/render.js

@@ -6,7 +6,7 @@
 // back, so the direction OpenSpec's pure-Markdown model went (Markdown as
 // truth, and the free-form drift that comes with it) stays closed.
 //
-// Three properties this file must keep:
+// Four properties this file must keep:
 //  - **Intent only.** The document says what the system promises, never what is
 //    proven or green: coverage and results are verdicts, and verdicts belong to
 //    `cover` / `verify`, which recompute them on demand. Putting them here also
@@ -20,7 +20,13 @@
 //  - **Params interpolated into the statement.** The source says
 //    "{idleTimeoutMin} minutes"; a human reader wants "30 minutes". This is the
 //    one thing the projection gives that reading the source does not.
+//  - **None of the registry's control characters survive into it.** The
+//    document is quoted prose from a repository that may not be the reader's,
+//    and it is a *file* — committed, served, and read again long after the run
+//    that wrote it. See `sanitised` for why the defence sits here rather than
+//    at the terminal write.
 import { byCodeUnit } from './order.js';
+import { control } from './terminal.js';
 const BANNER = '<!-- Generated by `attest render` — do not edit. Edit the `*.reqs.ts` registry and regenerate. -->';
 /**
  * Render the registry as a standalone Markdown document.
@@ -31,18 +37,65 @@ const BANNER = '<!-- Generated by `attest render` — do not edit. Edit the `*.r
  * worse than no gate.
  */
 export function renderMarkdown(registry) {
-    const ids = Object.keys(registry).sort(compareIds);
+    const clean = sanitised(registry);
+    const ids = Object.keys(clean).sort(compareIds);
     const out = [BANNER, '', '# Requirements', ''];
     if (ids.length === 0) {
         out.push('_No requirements are defined yet._', '');
         return out.join('\n');
     }
-    out.push(...overviewTable(registry, ids), '');
+    out.push(...overviewTable(clean, ids), '');
     for (const id of ids) {
-        out.push(...section(id, registry[id]), '');
+        out.push(...section(id, clean[id]), '');
     }
     return out.join('\n');
 }
+/**
+ * The registry with every string its author controls stripped of control
+ * characters (ATX-58).
+ *
+ * **At the entry rather than at each emitter**, which is the whole of why this
+ * defect existed. ATX-37 put every byte the *CLI* prints through `control`, and
+ * this document is built by concatenation that never went past it — so a
+ * statement carrying `ESC [2K CR` erased the reviewer's line and repainted a
+ * verdict, from `attest render` with no flag at all. Sanitising here means a
+ * field added to `Requirement` later is covered by having been added, instead of
+ * by someone remembering; four call sites each doing it is the arrangement that
+ * produced the gap in the first place.
+ *
+ * **Over the document, not over stdout.** The obvious fix — sanitise the
+ * terminal write — is wrong, and the loop that found this said so: `--out`
+ * carried the payload into the file too. That file is committed, served, and
+ * read later by `cat`, by `less -R`, or by a site generator, so the artifact
+ * outlives the run and the run is the wrong place to defend. It also keeps
+ * `--check` honest, since both sides of the comparison are built from here.
+ *
+ * Ids are not sanitised and need not be: `RegistrySchema` holds every key to
+ * `^[A-Z]+-\d+$` on **both** reader paths — the static one by construction, the
+ * evaluating one since ATX-38 — so no id can carry a control character to begin
+ * with. The container is still built without a prototype, for the reason
+ * `red-record.ts` builds its own that way: that grammar is held somewhere else,
+ * and a defence that reads an inherited key when the other one lapses is not a
+ * defence. `Object.entries` and the sort below see own keys either way.
+ */
+function sanitised(registry) {
+    const out = Object.create(null);
+    for (const [id, req] of Object.entries(registry)) {
+        out[id] = {
+            statement: control(req.statement),
+            rationale: control(req.rationale),
+            params: Object.fromEntries(Object.entries(req.params).map(([k, v]) => [control(k), sanitisedValue(v)])),
+            outOfScope: req.outOfScope.map(control),
+        };
+    }
+    return out;
+}
+/** A param value with its strings sanitised; numbers and booleans have none. */
+function sanitisedValue(value) {
+    if (Array.isArray(value))
+        return value.map((v) => (typeof v === 'string' ? control(v) : v));
+    return typeof value === 'string' ? control(value) : value;
+}
 /**
  * Line endings are a checkout artifact, not content.
  *
@@ -85,23 +138,56 @@ export function staleIssue(target, current, fresh) {
         message: `${why} Regenerate it with: ${target.command}`,
     };
 }
+/**
+ * `AUTH-3` as its two ordering keys. An id this reader cannot take apart is its
+ * own prefix with no number, which is the reading `locate.ts`'s `idPrefix`
+ * gives — the two used to disagree, and one of them was wrong.
+ *
+ * `lastIndexOf('-')` with no guard was the old spelling, and on an id with no
+ * dash it silently dropped the last character (`AUTH` → prefix `AUT`) and
+ * produced `NaN` for the number. A comparator that answers `NaN` is not merely
+ * imprecise, it is **non-transitive**: measured on
+ * `['AUTH-3','AUTH-abc','AUTH-2']` the result was `AUTH-3, AUTH-abc, AUTH-2`,
+ * which is not a sorted permutation of anything. Both cases are handled here so
+ * the comparator below is total by construction rather than by the input
+ * happening to be well-formed.
+ */
+function orderingKey(id) {
+    const at = id.indexOf('-');
+    const tail = at === -1 ? '' : id.slice(at + 1);
+    if (at === -1 || !/^\d+$/.test(tail))
+        return [id, -1];
+    return [id.slice(0, at), Number(tail)];
+}
 /**
  * Order ids the way a reader expects: prefix alphabetically, then the number
  * numerically. A plain string sort puts ATX-10 between ATX-1 and ATX-2, which
  * scrambles the document as soon as a registry reaches ten requirements.
+ *
+ * Total, and a function of the ids alone. `renderMarkdown` feeds `--check`, so
+ * an order that depends on anything else — the locale, the insertion order, the
+ * engine's tie-breaking — is a freshness gate that can disagree with the run
+ * that generated the file it is checking.
+ *
+ * A malformed id cannot reach here through any command: `RequirementIdSchema`
+ * rejects it and `render` returns early on a registry that failed to load. That
+ * is why this is robustness rather than a fix — the property being bought is
+ * that the function is correct on its own terms instead of correct because
+ * something upstream is.
  */
 function compareIds(a, b) {
-    const split = (id) => {
-        const at = id.lastIndexOf('-');
-        return [id.slice(0, at), Number(id.slice(at + 1))];
-    };
-    const [prefixA, numA] = split(a);
-    const [prefixB, numB] = split(b);
+    const [prefixA, numA] = orderingKey(a);
+    const [prefixB, numB] = orderingKey(b);
     // byCodeUnit, not localeCompare: the ordering has to be identical on every
     // machine, or `--check` would flap with the runner's locale.
     if (prefixA !== prefixB)
         return byCodeUnit(prefixA, prefixB);
-    return numA - numB;
+    if (numA !== numB)
+        return numA - numB;
+    // Same prefix and same number is only reachable for ids this reader could not
+    // take apart. Falling back to the whole id keeps the order total rather than
+    // leaving it to the sort's stability, which is a property of the engine.
+    return byCodeUnit(a, b);
 }
 /**
  * An index of the whole registry: id + the promise itself. Deliberately carries
@@ -166,14 +252,43 @@ function formatValue(value) {
  * at either end needs padding spaces.
  */
 function code(value) {
-    const longest = Math.max(0, ...[...value.matchAll(/`+/g)].map((m) => m[0].length));
+    // Accumulated, never `Math.max(0, ...runs)` (ATX-59). The spread puts one
+    // argument on the stack per backtick run, so a param holding a few hundred
+    // thousand of them exhausted it — `RangeError` out of `attest render` under
+    // the static reader, with the stack naming this function. Not backtracking,
+    // and found only by sweeping for more of it: same reachable path, same
+    // registry-chooses-the-cost shape, different mechanism.
+    let longest = 0;
+    for (const run of value.matchAll(/`+/g))
+        longest = Math.max(longest, run[0].length);
     const fence = '`'.repeat(longest + 1);
     const pad = value.startsWith('`') || value.endsWith('`') ? ' ' : '';
     return `${fence}${pad}${value}${pad}${fence}`;
 }
-/** Make prose safe inside a table cell: no row-breaking pipes, no newlines. */
+/**
+ * Make prose safe inside a table cell: no row-breaking pipes, no newlines.
+ *
+ * Each maximal whitespace run is matched once and inspected, rather than
+ * matched by the old starred-`\s`, `\n`, starred-`\s` pattern (ATX-59). That
+ * spelling puts a required character after a leading quantifier, so a
+ * whitespace run with no newline in it was consumed, failed, and re-tried one
+ * character shorter from every position in the run — quadratic, and 8.6 seconds
+ * of CPU for 120,000 spaces in one statement, reachable through `render
+ * --check` in CI without executing a line of the project.
+ *
+ * The obvious repair does not work and was measured before this one was
+ * written: `[^\S\n]*\n[^\S\n]*`, which stops the class matching the newline,
+ * came out *slower*. The backtracking was never about which characters the
+ * class held — it was about the quantifier having something after it. `\s+`
+ * has nothing after it, so there is no failure to backtrack into, and the
+ * decision moves to the callback. Byte-identical to the old pattern: a
+ * whitespace run containing a newline collapses to one space, and a run
+ * without one is left exactly as it was.
+ */
 function cell(text) {
-    return text.replace(/\s*\n\s*/g, ' ').replace(/\|/g, '\\|');
+    return text
+        .replace(/\s+/g, (ws) => (ws.includes('\n') ? ' ' : ws))
+        .replace(/\|/g, '\\|');
 }
 /** GitHub/GitLab slug for a `## AUTH-3` heading. */
 function anchor(id) {

package/dist/core/req-suite.d.ts

@@ -0,0 +1,5 @@
+/** How `requirement(id)` names its describe block. */
+export declare function requirementSuiteName(id: string): string;
+/** The requirement id a suite name carries, or `undefined` if it carries none. */
+export declare function requirementIdOf(suiteName: string): string | undefined;
+//# sourceMappingURL=req-suite.d.ts.map

package/dist/core/req-suite.js

@@ -0,0 +1,27 @@
+// The one spelling of the suite name that carries a requirement id.
+//
+// `requirement()` writes it, `runner.ts` reads it back out of the serialized
+// task tree, and the runtime's own guard reads it to find the requirement that
+// owns a scenario. That is three readers of one encoding, across a process
+// boundary — the task tree is the only channel that crosses it (design §5.4) —
+// and two spellings of one encoding are two encodings the moment either is
+// edited.
+//
+// Deliberately free of any `vitest` import, so both sides of the engine ↔
+// runner boundary (`tests/import-boundary.spec.ts`) can depend on it.
+/** How `requirement(id)` names its describe block. */
+export function requirementSuiteName(id) {
+    return `[${id}]`;
+}
+/**
+ * `.+` rather than something narrower: a delta may propose an id the registry's
+ * grammar would refuse, and this has to round-trip whatever `requirement()`
+ * wrote so the two readers agree about it (the call `readDeltaSource` makes for
+ * the same reason).
+ */
+const REQ_SUITE = /^\[(.+)\]$/;
+/** The requirement id a suite name carries, or `undefined` if it carries none. */
+export function requirementIdOf(suiteName) {
+    return REQ_SUITE.exec(suiteName)?.[1];
+}
+//# sourceMappingURL=req-suite.js.map

package/dist/core/runner.js

@@ -5,9 +5,8 @@
 import { startVitest } from 'vitest/node';
 import { configDefaults } from 'vitest/config';
 import { relativePath } from './paths.js';
+import { requirementIdOf } from './req-suite.js';
 import { byCodeUnit } from './order.js';
-/** requirement() names each describe block `[reqId]`; recover the id from that. */
-const REQ_SUITE = /^\[(.+)\]$/;
 /**
  * Vitest's own default exclusions, which every Attest run keeps on top of
  * whatever else it excludes.
@@ -73,18 +72,15 @@ export async function runAndCollect(options = {}) {
         // Reconstruct coverage from the task tree (not an in-process singleton).
         const walk = (task) => {
             if (task.type === 'suite') {
-                const m = REQ_SUITE.exec(task.name);
-                if (m) {
-                    const id = m[1];
+                const id = requirementIdOf(task.name);
+                if (id !== undefined) {
                     const set = runtimeCoverage.get(id) ?? new Set();
                     const byName = outcomes.get(id) ?? new Map();
-                    for (const c of task.tasks ?? []) {
+                    for (const c of scenariosUnder(task)) {
                         // A scenario counts as covered only if it actually executed —
                         // skipped/todo scenarios have no run result (enables §8's
                         // declared-not-run check). The same test decides whether there is
                         // an outcome to record: a skip is not a red (design §6).
-                        if (c.type !== 'test')
-                            continue;
                         const outcome = executedOutcome(c);
                         if (!outcome)
                             continue;
@@ -126,6 +122,28 @@ export async function runAndCollect(options = {}) {
         await vitest.close();
     }
 }
+/**
+ * Every scenario belonging to a requirement suite, at any depth beneath it.
+ *
+ * Direct children only was the other half of the nested-`describe` defect: a
+ * scenario grouped under one is a `test` inside a `suite` inside `[reqId]`, so
+ * even once the runtime stopped throwing it would have been invisible here —
+ * `declared-not-run`, for a scenario that ran and passed. The static parser has
+ * always recursed (`parser.ts` walks the whole subtree), and this is the seam
+ * where the two readers of one plan have to agree.
+ *
+ * Descent stops at a nested requirement suite, so a `requirement()` written
+ * inside another one keeps its own scenarios rather than donating them upward.
+ */
+function* scenariosUnder(suite) {
+    for (const child of suite.tasks ?? []) {
+        if (child.type === 'test')
+            yield child;
+        else if (child.type === 'suite' && requirementIdOf(child.name) === undefined) {
+            yield* scenariosUnder(child);
+        }
+    }
+}
 /**
  * Did this file fail before any of its tests could exist?
  *

package/dist/core/skill.js

@@ -34,6 +34,9 @@
 // workflow to an agent that trusts it. The backstop is that every mistake it
 // could cause is a diagnostic with a fix hint — a registry written the old way
 // is `registry-not-static`, and the agent corrects itself from the report.
+// It has happened once, so: read this file when a release adds a diagnostic.
+// Nothing gates that — `ATX-57` catches a code the engine cannot emit, never one
+// it can.
 /**
  * The one sentence that decides whether the workflow is ever loaded.
  *
@@ -163,6 +166,18 @@ Writing it at its merged location is what makes merging it a rename. Its relativ
 imports resolve now exactly as they will afterwards, so \`../fog\` never becomes
 \`../../../lib/game/fog\` and back again.
 
+Two things to get right when you create the file:
+
+- **Do not put it under \`changes/\`.** Nothing walks that directory, so a spec
+  left there executes in no suite and no gate — \`spec-in-change-dir\` from
+  \`attest check\`. The change folder holds \`proposal.md\`,
+  \`requirements.delta.ts\` and \`first-run.json\`, and nothing else.
+- **Pick a name whose merged form is free.** Merging renames
+  \`fog.proposed.spec.ts\` to \`fog.spec.ts\`, so if that module already has a
+  \`fog.spec.ts\` the rename would overwrite it — \`proposed-spec-name-taken\`.
+  Name it \`fog.2fa.proposed.spec.ts\` instead. Several spec files may sit beside
+  one module; Attest attributes each by the ids it declares, not by its path.
+
 \`\`\`ts
 // changes/add-2fa/requirements.delta.ts
 import { delta } from '@am_shork/attest/define';
@@ -271,13 +286,17 @@ once. Branch on \`issues[].code\`, never on \`message\`:
 | \`tests-red\` | a test is failing — the normal state until you are finished |
 | \`never-red\` | an added requirement's scenario has no recorded failing run |
 | \`uncovered-requirement\` | a requirement in the applied registry has no scenario |
-| \`declared-not-run\` | a scenario was declared but never executed (\`skip\` / \`only\`?) |
+| \`declared-not-run\` | a scenario was declared but never executed (\`skip\` / \`only\`?) — withdrawn when one of the two rows below already explains its file, so it never stands in for a load failure |
+| \`spec-load-failed\` | a spec file could not be imported, so nothing in it ran. The run output carries the import error itself; this names which file it stopped |
 | \`proposed-spec-unclaimed\` | a \`*.proposed.spec.ts\` no change's delta claims |
-| \`added-id-unmerged\` | a spec failed to load, and this change adds an id the registry on disk lacks |
+| \`added-id-unmerged\` | the same load failure, when this change also adds an id the registry on disk lacks. The specific case, and the only one reported for that file |
 | \`unbound-param\` | a \`{placeholder}\` has no matching \`params\` key |
 | \`registry-not-static\` | a registry file is not a literal the engine can read |
 | \`add-conflict\` | the delta adds an id that already exists with different content |
 | \`change-not-found\` | no \`requirements.delta.ts\` for that name |
+| \`proposed-spec-name-taken\` | a proposed spec's merged name is already held by another spec |
+| \`apply-unsupported-delta\` | \`--apply\` writes back ADDED only, and this delta carries more |
+| \`apply-no-prefix-owner\` | no registry file owns the prefix of an id this change adds |
 
 ### Four things you must not do
 
@@ -309,15 +328,36 @@ failure this framework exists to make visible:
 
 Then, and not before:
 
-1. Merge \`requirements.delta.ts\` into the main registry, and rename each of the
-   change's \`*.proposed.spec.ts\` to \`*.spec.ts\` **in place**. Nothing moves and
-   no import changes; if you find yourself editing a specifier, the spec was not
-   written at its merged location and stage 1 was the place to fix that.
-2. Move \`changes/<name>/\` to \`archive/<date>-<name>/\`.
-3. If the project commits a rendering, regenerate it: \`attest render --out
-   <file>\`. A committed document that no longer matches the registry is a
-   \`stale-spec-doc\` ERROR.
-4. Run \`attest verify\` on the merged result and report it.
+\`\`\`
+attest archive <name> --apply
+\`\`\`
+
+That finishes the merge the verdict just approved: it splices the change's ADDED
+requirements into the registry file owning their id prefix, repoints each proposed
+spec's import of \`requirements.delta.ts\` at that registry, renames the specs in
+place, and moves \`changes/<name>/\` to \`archive/<date>-<name>/\`. It re-runs the
+gate first and writes nothing if that fails, and it prints every path it touched.
+If it stops partway, run it again — each step is derived from the tree as it is,
+so a second run finishes the job rather than repeating it.
+
+Two things it does not do, and both are still yours:
+
+1. **Regenerate a committed rendering.** Nothing records where yours lives, so run
+   \`attest render --out <file>\` afterwards. A document that no longer matches the
+   registry is a \`stale-spec-doc\` ERROR.
+2. **Run the merged suite.** \`attest verify\`, on the result, reported.
+
+**It writes back ADDED only.** A delta also carrying RENAMED, REMOVED or MODIFIED
+is refused whole as \`apply-unsupported-delta\`, with nothing written — the gate
+still checked all four, so nothing about the change is unverified, but the rest is
+merged by hand.
+
+Merging by hand, when it refuses: splice the delta's entries into the registry
+file that owns their prefix; then for each \`*.proposed.spec.ts\`, **repoint its
+import of \`requirements.delta.ts\` at that registry** and rename it to
+\`*.spec.ts\` in place. That import is the one specifier a merge changes, and it
+changes because the delta moves to \`archive/\` — the spec file itself does not
+move, so nothing else about it does either. Then move the change folder.
 
 ## The commands
 
@@ -327,7 +367,7 @@ Then, and not before:
 | \`attest verify\` | runs the suite, then reports coverage and drift. |
 | \`attest cover\` | which requirements lack a scenario. |
 | \`attest render\` | the registry as Markdown for human readers; \`--check\` gates a committed copy. |
-| \`attest archive <change>\` | the completion gate for a proposed change. |
+| \`attest archive <change>\` | the completion gate for a proposed change; \`--apply\` also performs the merge it approves. |
 | \`attest status <change>\` | what that gate still wants, without running the suite. |
 
 \`verify\` starts the child run **isolated** — it does not read \`vitest.config.ts\`,

package/dist/core/splice.d.ts

@@ -0,0 +1,52 @@
+import type { Registry, Requirement } from './types.js';
+/**
+ * One registry entry, at `indent`, with no trailing comma.
+ *
+ * The separator is the caller's because only the caller knows what it is
+ * inserting between: continuing a list needs a comma before, opening an empty
+ * body needs one after, and putting that decision here would mean this function
+ * had to be told which case it was in anyway.
+ *
+ * `params` and `outOfScope` are omitted when empty rather than written as `{}`
+ * and `[]`. The schema defaults both, so the two spellings mean the same thing,
+ * and the shorter one is what a person writing this entry by hand would have
+ * produced — which is the standard for a file `--apply` is merging into rather
+ * than generating.
+ */
+export declare function requirementSource(id: string, req: Requirement, indent: string): string;
+/**
+ * `source` with `additions` inserted into its registry literal.
+ *
+ * `undefined` when the file holds no literal this can be inserted into — the
+ * same condition `readRegistrySource` reports, and one the caller has already
+ * checked, so it is a refusal to guess rather than a diagnosis.
+ *
+ * Ids are inserted in code-unit order for the reason they are emitted in it:
+ * the same delta must produce the same file twice.
+ */
+export declare function spliceRequirements(file: string, source: string, additions: Registry): string | undefined;
+/**
+ * `source` with every import of `from` repointed at `to`.
+ *
+ * The second edit `--apply` makes to a file it did not write, and the one the
+ * design record missed. Merging a proposed spec was described as a rename in
+ * place, which is true of its *location*: the file already sits where it lands,
+ * so no relative specifier moves. But a stage-1 scenario reads its proposed
+ * params out of the change's delta (ATX-48, and the whole reason a delta reads
+ * as the registry it proposes), and the delta is what step 3 moves into
+ * `archive/`. Renaming without this leaves a merged spec importing a path that
+ * no longer exists — a suite that loads nothing, reported as `declared-not-run`
+ * against scenarios that are perfectly good.
+ *
+ * The expression around the import needs nothing done to it: `reqs['AUTH-7']
+ * .params.x` reads the same on both sides, which is exactly what ATX-48 bought.
+ * So this replaces one string literal and touches nothing else — the same
+ * discipline as the splice, for the same reason.
+ *
+ * The extension is taken from the specifier being replaced rather than chosen
+ * here. Whether a project writes `./x.reqs.js` or `./x.reqs.ts` is a property of
+ * its module resolution, uniform across the project, and already answered by the
+ * specifier sitting in front of us.
+ */
+export declare function repointImport(file: string, source: string, from: string, to: string): string;
+//# sourceMappingURL=splice.d.ts.map

package/dist/core/splice.js

@@ -0,0 +1,189 @@
+// Writing a requirement into a registry file as text (design §7).
+//
+// This is the half of `--apply` the `AGENTS.md` rejection was about. That
+// proposal was refused because "each of its failure modes is destructive on a
+// file the user cannot regenerate", and the argument for why merging a delta is
+// different has one load-bearing clause: the result of a splice is checkable by
+// re-reading it. That clause only holds if the splice is a **pure insertion**.
+//
+// So nothing here renders a registry. Rendering one out of a `Registry` object
+// would be far easier and would silently drop every comment, every blank line
+// and every layout choice in a hand-written file — destroying exactly what
+// cannot be regenerated, while passing a re-read with flying colours because the
+// *values* all survived. Instead `registryInsertionPoint` hands back an offset,
+// and the only edit made to the file is text inserted at it. Every other byte is
+// the byte that was already there, which is a property a test can state.
+//
+// The generated text is therefore the one thing here that has to be right on its
+// own, and it is generated conservatively: strings are escaped rather than
+// interpolated, params are emitted in code-unit key order so the same delta
+// produces the same bytes twice, and anything the schema does not permit cannot
+// reach this file because the gate validated the delta before `--apply` ran.
+import ts from 'typescript';
+import { dirname, relative, resolve } from 'node:path';
+import { registryInsertionPoint } from './static-registry.js';
+import { toPosixPath } from './paths.js';
+import { byCodeUnit } from './order.js';
+/**
+ * A TypeScript single-quoted string literal holding exactly `value`.
+ *
+ * Hand-escaped rather than `JSON.stringify`, for one reason that is not style:
+ * the registries this writes into are single-quoted throughout, and a merged
+ * entry that arrives double-quoted is a diff hunk about quotation marks in the
+ * middle of a merge the reviewer is trying to read. Control characters go out as
+ * `\uXXXX` rather than raw, so a statement someone pasted a newline into cannot
+ * produce a file that no longer parses.
+ */
+function tsString(value) {
+    let out = "'";
+    for (const ch of value) {
+        const code = ch.codePointAt(0) ?? 0;
+        if (ch === '\\')
+            out += '\\\\';
+        else if (ch === "'")
+            out += "\\'";
+        else if (ch === '\n')
+            out += '\\n';
+        else if (ch === '\r')
+            out += '\\r';
+        else if (ch === '\t')
+            out += '\\t';
+        else if (code < 0x20 || code === 0x7f)
+            out += `\\u${code.toString(16).padStart(4, '0')}`;
+        else
+            out += ch;
+    }
+    return `${out}'`;
+}
+/** A param key, bare when it is a plain identifier and quoted when it is not. */
+function keySource(key) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : tsString(key);
+}
+function paramSource(value) {
+    if (Array.isArray(value))
+        return `[${value.map((v) => paramSource(v)).join(', ')}]`;
+    return typeof value === 'string' ? tsString(value) : String(value);
+}
+/**
+ * One registry entry, at `indent`, with no trailing comma.
+ *
+ * The separator is the caller's because only the caller knows what it is
+ * inserting between: continuing a list needs a comma before, opening an empty
+ * body needs one after, and putting that decision here would mean this function
+ * had to be told which case it was in anyway.
+ *
+ * `params` and `outOfScope` are omitted when empty rather than written as `{}`
+ * and `[]`. The schema defaults both, so the two spellings mean the same thing,
+ * and the shorter one is what a person writing this entry by hand would have
+ * produced — which is the standard for a file `--apply` is merging into rather
+ * than generating.
+ */
+export function requirementSource(id, req, indent) {
+    const inner = `${indent}  `;
+    const lines = [
+        `${indent}${tsString(id)}: {`,
+        `${inner}statement: ${tsString(req.statement)},`,
+        `${inner}rationale: ${tsString(req.rationale)},`,
+    ];
+    // Code-unit key order, so one delta applied twice writes the same bytes — the
+    // property `--apply`'s re-runnability rests on, and the reason `apply.ts`
+    // sorts the same way when it canonicalises for `add-conflict`.
+    const params = Object.entries(req.params).sort(([a], [b]) => byCodeUnit(a, b));
+    if (params.length > 0) {
+        const body = params.map(([k, v]) => `${keySource(k)}: ${paramSource(v)}`).join(', ');
+        lines.push(`${inner}params: { ${body} },`);
+    }
+    if (req.outOfScope.length > 0) {
+        lines.push(`${inner}outOfScope: [${req.outOfScope.map((s) => tsString(s)).join(', ')}],`);
+    }
+    lines.push(`${indent}}`);
+    return lines.join('\n');
+}
+/**
+ * `source` with `additions` inserted into its registry literal.
+ *
+ * `undefined` when the file holds no literal this can be inserted into — the
+ * same condition `readRegistrySource` reports, and one the caller has already
+ * checked, so it is a refusal to guess rather than a diagnosis.
+ *
+ * Ids are inserted in code-unit order for the reason they are emitted in it:
+ * the same delta must produce the same file twice.
+ */
+export function spliceRequirements(file, source, additions) {
+    const ids = Object.keys(additions).sort(byCodeUnit);
+    if (ids.length === 0)
+        return source;
+    const point = registryInsertionPoint(file, source);
+    if (!point)
+        return undefined;
+    const entries = ids
+        .map((id) => requirementSource(id, additions[id], point.indent))
+        .join(',\n');
+    const text = point.leadingComma ? `,\n${entries}` : `\n${entries},\n`;
+    return source.slice(0, point.offset) + text + source.slice(point.offset);
+}
+/**
+ * `source` with every import of `from` repointed at `to`.
+ *
+ * The second edit `--apply` makes to a file it did not write, and the one the
+ * design record missed. Merging a proposed spec was described as a rename in
+ * place, which is true of its *location*: the file already sits where it lands,
+ * so no relative specifier moves. But a stage-1 scenario reads its proposed
+ * params out of the change's delta (ATX-48, and the whole reason a delta reads
+ * as the registry it proposes), and the delta is what step 3 moves into
+ * `archive/`. Renaming without this leaves a merged spec importing a path that
+ * no longer exists — a suite that loads nothing, reported as `declared-not-run`
+ * against scenarios that are perfectly good.
+ *
+ * The expression around the import needs nothing done to it: `reqs['AUTH-7']
+ * .params.x` reads the same on both sides, which is exactly what ATX-48 bought.
+ * So this replaces one string literal and touches nothing else — the same
+ * discipline as the splice, for the same reason.
+ *
+ * The extension is taken from the specifier being replaced rather than chosen
+ * here. Whether a project writes `./x.reqs.js` or `./x.reqs.ts` is a property of
+ * its module resolution, uniform across the project, and already answered by the
+ * specifier sitting in front of us.
+ */
+export function repointImport(file, source, from, to) {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, /* setParentNodes */ true);
+    const dir = dirname(file);
+    const edits = [];
+    for (const statement of sf.statements) {
+        if (!ts.isImportDeclaration(statement))
+            continue;
+        const spec = statement.moduleSpecifier;
+        if (!ts.isStringLiteral(spec))
+            continue;
+        if (!resolvesTo(dir, spec.text, from))
+            continue;
+        const ext = spec.text.endsWith('.js') ? '.js' : spec.text.endsWith('.ts') ? '.ts' : '';
+        let target = toPosixPath(relative(dir, to));
+        if (ext)
+            target = target.replace(/\.[^./]+$/, ext);
+        // A bare `x.reqs.js` is a package specifier, not a sibling file.
+        if (!target.startsWith('.'))
+            target = `./${target}`;
+        // Inside the quotes: the file's own quote style is left exactly as it was.
+        edits.push({ start: spec.getStart(sf) + 1, end: spec.getEnd() - 1, text: target });
+    }
+    let out = source;
+    for (const edit of edits.reverse()) {
+        out = out.slice(0, edit.start) + edit.text + out.slice(edit.end);
+    }
+    return out;
+}
+/**
+ * Whether `specifier`, written in a file under `dir`, names `target`.
+ *
+ * The `.js`-for-`.ts` spelling is accepted because NodeNext resolution requires
+ * it, and a project using it writes every specifier that way — including the one
+ * this is looking for.
+ */
+function resolvesTo(dir, specifier, target) {
+    if (!specifier.startsWith('.'))
+        return false;
+    const resolved = resolve(dir, specifier);
+    return resolved === target || resolved.replace(/\.js$/, '.ts') === target;
+}
+//# sourceMappingURL=splice.js.map