@am_shork/attest 0.4.3 → 0.6.0

package/dist/core/runner.js

@@ -4,6 +4,8 @@
 // never crosses the process boundary; the serialized task tree does.
 import { startVitest } from 'vitest/node';
 import { configDefaults } from 'vitest/config';
+import { relativePath } from './paths.js';
+import { byCodeUnit } from './order.js';
 /** requirement() names each describe block `[reqId]`; recover the id from that. */
 const REQ_SUITE = /^\[(.+)\]$/;
 /**
@@ -17,8 +19,21 @@ const REQ_SUITE = /^\[(.+)\]$/;
  * command goes through — the boundary the gate exists to hold.
  */
 export const BASE_EXCLUDE = configDefaults.exclude;
-/** Proposed / archived changes are excluded from a normal run (design §7, §8). */
-const DEFAULT_EXCLUDE = [...BASE_EXCLUDE, '**/changes/**', '**/archive/**'];
+/**
+ * Proposed / archived changes are excluded from a normal run (design §7, §8).
+ *
+ * The `.proposed.spec.ts` glob is the one carrying the weight now: a proposal's
+ * specs sit at their merged location, next to the code they attest, so nothing
+ * about *where* they are keeps them out of a run. They are red by construction
+ * until their change is implemented, and a default run that swept them up would
+ * report a project as broken for the whole life of every change in flight.
+ */
+const DEFAULT_EXCLUDE = [
+    ...BASE_EXCLUDE,
+    '**/*.proposed.spec.ts',
+    '**/changes/**',
+    '**/archive/**',
+];
 /**
  * Build the child-run options. Attest owns the run *scope* — include/exclude/
  * root/watch always come from here, so the caller can neither widen the spec
@@ -88,20 +103,42 @@ export async function runAndCollect(options = {}) {
         // that notices if the task tree ever stops having a `type`, a `name` or a
         // `result.state`. An `as unknown as` here bought nothing and blinded it to
         // exactly the change that would silently empty the runtime coverage.
-        for (const file of vitest.state.getFiles())
+        const unloadedFiles = [];
+        for (const file of vitest.state.getFiles()) {
             walk(file);
+            // Relative and POSIX for the reason everything derived from the root is
+            // (`paths.ts`): this becomes an `Issue.file`, which a `--json` consumer
+            // diffs across two CI runs that may not share an operating system.
+            if (failedToLoad(file)) {
+                unloadedFiles.push(relativePath(options.root ?? process.cwd(), file.filepath));
+            }
+        }
+        unloadedFiles.sort(byCodeUnit);
         // No optional call and no `?? 0` default: `getCountOfFailedTests` is a
         // required method on Vitest's state, so the guard was dead at the type
         // level — and had it ever become live it defaulted the wrong way, reading a
         // missing API as zero failures and turning a red suite green. This is the
         // one boolean in the engine that must never fail open.
         const passed = vitest.state.getCountOfFailedTests() === 0;
-        return { passed, runtimeCoverage, outcomes };
+        return { passed, runtimeCoverage, outcomes, unloadedFiles };
     }
     finally {
         await vitest.close();
     }
 }
+/**
+ * Did this file fail before any of its tests could exist?
+ *
+ * Errors recorded on the *file* rather than on a test are collection errors —
+ * the module threw while being imported. Measured rather than assumed: a spec
+ * whose assertion fails carries `errors: 0` at the file level and one failing
+ * test task, while a spec whose import throws carries `errors: 1` and no tasks
+ * at all. Both leave `result.state` at `fail`, which is why the state alone
+ * cannot tell them apart.
+ */
+function failedToLoad(file) {
+    return (file.result?.errors?.length ?? 0) > 0;
+}
 /** The outcome of a task that ran, or `undefined` when it did not run at all. */
 function executedOutcome(task) {
     const state = task.result?.state;

package/dist/core/schema.js

@@ -14,10 +14,18 @@ export const RequirementSchema = z.object({
     // blacklists, id sets) are the most drift-prone constants, so keeping them out
     // of params left the highest-risk values unguarded; an array still has exactly
     // one owner (the spec) read by exactly one place (the scenario).
+    // The union carries its own message because a union's default one is the
+    // word "Invalid input", which names neither what was given nor what is
+    // accepted. A nested object is the value that reaches it — a table of
+    // kind -> weight is the natural thing to try — and the constraint that
+    // refuses it is stated nowhere the author is looking, so the message is
+    // where they find it.
     params: z
         .record(z.string(), (() => {
         const scalar = z.union([z.number(), z.string(), z.boolean()]);
-        return z.union([scalar, z.array(scalar)]);
+        return z.union([scalar, z.array(scalar)], {
+            errorMap: () => ({ message: 'expected a string, number, boolean, or an array of those' }),
+        });
     })())
         .default({}),
     outOfScope: z.array(z.string()).default([]),

package/dist/core/skill.js

@@ -74,12 +74,22 @@ promises is a two-stage workflow, and the stages are separate on purpose.
   a limit, a list of names — is written **once**, in the requirement's \`params\`,
   and the scenario reads it from there. The number then cannot drift between the
   spec and the assertion, because there is only one of it.
+- **What earns a param: promises, not tuning.** A value belongs in \`params\` when
+  the requirement promises it — a timeout the user is owed, a budget someone would
+  file a bug about. A value that only tunes behaviour (a search depth, a cache
+  size) stays an ordinary constant: nothing is owed if it changes, and a registry
+  that accumulates every knob in the project is one of the ways intent bloats.
 - **What that does not buy.** \`attest check\` executes nothing, so editing a
   param value leaves it at \`✓ No issues\` — nothing became unbound or uncovered.
   The single source makes a value impossible to *diverge*; it does not announce
   that it *moved*. Only \`verify\` goes red, and only when a scenario asserts on
-  the value it read from params. That is the reason to read params **inside** the
-  assertion rather than beside it.
+  the value it read from params.
+- **Reading the param is necessary, not sufficient.** An assertion that
+  recomputes its expectation from the same param the code under test just read
+  has no independent term: both sides move together, and the scenario stays green
+  through any edit. Pin the expectation to something that does not move with the
+  param — a fixture, a literal in the test, or a second independently derived
+  value.
 
 ## Rules the engine enforces
 
@@ -128,10 +138,43 @@ Then write the change folder. \`<name>\` is one directory name inside
 \`\`\`
 changes/<name>/
 ├── proposal.md              # why, and what is out of scope. Prose, for humans.
-├── requirements.delta.ts    # the intent change
-└── specs/*.spec.ts          # the scenarios that must pass for it to be done
+└── requirements.delta.ts    # the intent change
 \`\`\`
 
+**The change's scenarios do not live in that folder.** Each goes where it will
+live once the change is merged — beside the code it attests, in the same
+directory as the specs already there — under the name \`*.proposed.spec.ts\`:
+
+\`\`\`
+lib/game/specs/
+├── board.spec.ts            # already merged
+└── fog.proposed.spec.ts     # this change's, and ../fog already resolves
+\`\`\`
+
+That name is the whole mechanism. It keeps the file out of \`attest verify\` and
+out of a plain \`vitest run\` while the change is in flight — the scenarios are
+red by construction — and \`attest archive <name>\` pulls it in by the requirement
+ids it covers: a change claims the proposed specs that declare a scenario for an
+id it ADDs, renames to, or MODIFIEs. Nothing lists paths anywhere, so nothing can
+fall out of step. A proposed spec no change claims is a \`proposed-spec-unclaimed\`
+ERROR from \`attest check\`, because it would otherwise run nowhere at all.
+
+Writing it at its merged location is what makes merging it a rename. Its relative
+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';
@@ -156,8 +199,22 @@ The delta applies \`RENAMED → REMOVED → MODIFIED → ADDED\`, idempotently:
 ADDED id that already exists with identical content is a no-op, with different
 content it is a conflict.
 
+**A delta also reads as the registry of what it adds**, so a scenario written now
+reads a proposed param exactly as it will after the merge:
+
+\`\`\`ts
+import reqs from '../../changes/add-2fa/requirements.delta.ts';   // ← only this line changes at merge
+const window = reqs['AUTH-7'].params.totpWindowSec;               // typed at 30, no cast
+\`\`\`
+
+Never hand-write an accessor for a proposed param, and never copy the literal
+into the assertion: both are a second place the value lives, opened during the
+one stage where the assertion is being authored against a value nobody has
+implemented yet. MODIFIED ids are deliberately not readable this way — the end
+state is the base entry with the patch applied, and the base is not in that file.
+
 **The scenarios must be red.** Every added requirement needs at least one
-scenario under \`changes/<name>/specs/\`, and at this stage they must fail —
+scenario in a \`*.proposed.spec.ts\`, and at this stage they must fail —
 they describe behaviour that does not exist yet. Prove it:
 
 \`\`\`
@@ -227,10 +284,15 @@ once. Branch on \`issues[].code\`, never on \`message\`:
 | \`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\`?) |
+| \`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 |
 | \`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
 
@@ -247,6 +309,12 @@ failure this framework exists to make visible:
    is the drift the single source exists to prevent, and the param is typed at
    the value written in the registry, so a stale expectation stops compiling
    rather than silently passing.
+   *One thing to know before implementation code reads a param this change
+   ADDs:* the suite imports your \`*.reqs.ts\` from disk, while the gate applies
+   the delta in memory — so that read throws at import and the gate answers
+   \`added-id-unmerged\`. Merge the added requirement into the registry and run
+   again; the \`added:\` entry stays, because applying it a second time with
+   identical content is a no-op.
 4. **Do not write or edit \`first-run.json\`.** It is the one file here the gate
    trusts without being able to check it, so a hand-written \`"fail"\` clears
    \`never-red\` while proving nothing at all. Run the gate before implementing;
@@ -256,13 +324,36 @@ failure this framework exists to make visible:
 
 Then, and not before:
 
-1. Merge \`requirements.delta.ts\` into the main registry, and the change's specs
-   into the main suite.
-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
 
@@ -272,7 +363,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

package/dist/core/static-registry.d.ts

@@ -39,4 +39,34 @@ export type DeltaReadResult = {
  * (write the value inline, or `--eval`) is the same sentence either way.
  */
 export declare function readDeltaSource(file: string, source: string): DeltaReadResult;
+/**
+ * Where a new entry may be written into a registry file's literal, as an offset
+ * into its source (design §7).
+ *
+ * The insertion point rather than a rewritten file, because `--apply` must not
+ * regenerate a `*.reqs.ts`. Every registry this tool merges into is hand-written
+ * and hand-commented, and rendering one back out of a `Registry` object would
+ * silently drop every comment and every choice of layout in it — the
+ * "destructive on a file the user cannot regenerate" shape the `AGENTS.md`
+ * proposal was rejected for. An offset lets the splice be a pure insertion: every
+ * other byte of the file is the byte that was there before, which is a property
+ * that can be stated and tested rather than hoped for.
+ *
+ * Lives here because this is the module that already knows how to find the
+ * literal, and the one place `typescript` is imported for that job. A second
+ * walker would be a second answer to "where does this registry's body end".
+ *
+ * `undefined` when the file is not a registry this tool can read — the same
+ * condition `readRegistrySource` reports as `registry-not-static` or
+ * `registry-no-default`, and the caller has already run that check.
+ */
+export interface RegistryInsertion {
+    /** Offset to insert at. Everything before and after it is preserved. */
+    offset: number;
+    /** The indentation the file's existing entries use, reproduced for new ones. */
+    indent: string;
+    /** Whether the insertion has to open with a `,` — false only for an empty registry. */
+    leadingComma: boolean;
+}
+export declare function registryInsertionPoint(file: string, source: string): RegistryInsertion | undefined;
 //# sourceMappingURL=static-registry.d.ts.map

package/dist/core/static-registry.js

@@ -20,7 +20,7 @@
 // value is fixed by the source text — a second walker would be a second answer
 // to "is this a literal", and those two answers must not be able to disagree.
 import ts from 'typescript';
-import { RegistryValidationError } from './registry.js';
+import { RegistryValidationError, withProposedRequirements } from './registry.js';
 import { RegistrySchema } from './schema.js';
 /** The authoring function a registry file must default-export the result of. */
 const DEFINE = 'defineRequirements';
@@ -142,7 +142,11 @@ export function readDeltaSource(file, source) {
     // function deliberately does not make (see the note above on why a delta is
     // not schema-validated here), which is the worst thing an assertion can do —
     // look like verification.
-    return { ok: true, delta: value };
+    // Augmented exactly as `delta()` augments the evaluated one, through the same
+    // function: a delta reads as the registry of what it adds (design §7), and the
+    // two readers must not disagree about that — the differential suite is the
+    // thing that would notice, and it should have nothing to notice.
+    return { ok: true, delta: withProposedRequirements(value) };
 }
 /**
  * The expression a file default-exports, following one level of local binding.
@@ -318,4 +322,40 @@ function numericValue(node) {
         throw new NotStatic(node, 'a number this reader cannot spell out');
     return value;
 }
+export function registryInsertionPoint(file, source) {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, /* setParentNodes */ true);
+    const exported = defaultExportExpression(sf);
+    if (!exported)
+        return undefined;
+    const arg = authoringCall(exported, sf, 'defineRequirements');
+    if (!arg || !ts.isObjectLiteralExpression(arg))
+        return undefined;
+    const last = arg.properties[arg.properties.length - 1];
+    if (!last) {
+        // An empty registry: open the body rather than continue it. The trailing
+        // newline is written by the caller, so `{` does not end up sharing a line
+        // with the entry and the closing `}`.
+        return { offset: arg.getStart(sf) + 1, indent: indentOf(sf, source, arg) + '  ', leadingComma: false };
+    }
+    // Deliberately the *end of the last property*, not the end of the literal:
+    // inserting here sits before any trailing comma the file already has, so one
+    // leading comma is correct whether or not that comma is present, and the
+    // file's own trailing-comma style is left exactly as it was.
+    return { offset: last.getEnd(), indent: indentOf(sf, source, last), leadingComma: true };
+}
+/**
+ * The whitespace a node's line opens with.
+ *
+ * Read out of the source rather than computed from the column, so a file
+ * indented with tabs is continued with tabs. Anything else on the line (a
+ * property sharing a line with another) falls back to two spaces, which is the
+ * only case where this guesses.
+ */
+function indentOf(sf, source, node) {
+    const start = node.getStart(sf);
+    const { line } = sf.getLineAndCharacterOfPosition(start);
+    const lineStart = sf.getPositionOfLineAndCharacter(line, 0);
+    const prefix = source.slice(lineStart, start);
+    return /^[\t ]*$/.test(prefix) ? prefix : '  ';
+}
 //# sourceMappingURL=static-registry.js.map

package/dist/core/types.d.ts

@@ -40,6 +40,16 @@ export interface RunResult {
      * it, which is what §6's mechanism 2 records.
      */
     outcomes: Map<string, Map<string, Outcome>>;
+    /**
+     * Spec files that failed to *load*, as project-relative POSIX paths.
+     *
+     * A file whose module threw at import has no tasks at all, so every other
+     * signal it produces is an absence: no coverage, no outcomes, and scenarios
+     * the static plan declared but the runtime never saw. Those absences are
+     * indistinguishable from a `skip` unless the load failure is carried
+     * separately, which is what this is.
+     */
+    unloadedFiles: string[];
 }
 /** Severity levels for graded reporting (design §5.3). */
 export type Level = 'ERROR' | 'WARNING' | 'INFO';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.4.3",
+  "version": "0.6.0",
   "description": "TDD-native spec framework: tests are the source of truth for verification, ID-bound requirements the source of truth for intent.",
   "type": "module",
   "engines": {