@am_shork/attest 0.4.3 → 0.6.0

package/dist/core/pipeline.js

@@ -1,11 +1,11 @@
 // High-level operations composing the core layers (design §9). These are
 // tool-agnostic; the CLI is a thin shell that calls them and renders the result.
 import { createLoader } from './loader.js';
-import { evalReader, loadRegistry, parseSpecs, parseChangeSpecs, listChangeNames, scanProject, staticReader, } from './locate.js';
+import { evalReader, findChangeDirSpecs, loadRegistry, listChangeNames, parseSpecs, scanProject, staticReader, } from './locate.js';
 import { validateStructure, detectPotentialDrift, uncoveredIssues } from './validator.js';
 import { byCodeUnit } from './order.js';
 import { runAndCollect, BASE_EXCLUDE } from './runner.js';
-import { applyDelta, addedIds } from './apply.js';
+import { applyDelta, addedIds, claimedIds } from './apply.js';
 import { readDeltaSource } from './static-registry.js';
 import { statusRows, statusCounts } from './status.js';
 import { evaluateGate, declaredNotRunIssues } from './gate.js';
@@ -13,6 +13,8 @@ import { renderMarkdown, staleIssue } from './render.js';
 import { mergeRedRecord, readRedRecord, redRecordPath, serialiseRedRecord, } from './red-record.js';
 import { DEFAULT_TARGET, resolveTargets } from './targets.js';
 import { writeAtomic } from './write.js';
+import { applyMerge, mergedSpecPath } from './merge.js';
+import { compilerIssue } from './compiler.js';
 import { mkdir, readFile } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { relativePath } from './paths.js';
@@ -34,6 +36,9 @@ async function readRegistry(root, options, files) {
 }
 /** Static structural check (design §9: `attest check`). */
 export async function runCheck(root, options = {}) {
+    const unusable = compilerIssue();
+    if (unusable)
+        return [unusable];
     const scan = await scanProject(root);
     const { registry, issues } = await readRegistry(root, options, scan.reqsFiles);
     const plan = await parseSpecs(scan.specFiles, root);
@@ -41,8 +46,143 @@ export async function runCheck(root, options = {}) {
         ...issues,
         ...validateStructure(registry, plan),
         ...detectPotentialDrift(registry, plan, plan.paramRefs),
+        ...(await unclaimedProposedSpecIssues(root, scan, options)),
+        ...(await changeDirSpecIssues(root)),
+        ...proposedNameTakenIssues(root, scan),
     ];
 }
+/**
+ * A proposed spec whose merged name is already taken (design §7).
+ *
+ * Merging a proposed spec is a rename in place, so the name it will take is
+ * decided the moment the file is created — and nothing stopped that name from
+ * being one a merged spec already holds. `isSpecFile` and `isProposedSpecFile`
+ * are deliberately disjoint, so `session.spec.ts` and `session.proposed.spec.ts`
+ * sit side by side without either predicate objecting; the collision only
+ * surfaces at the rename, where it would **destroy** the merged file.
+ *
+ * It is not a corner. A proposed spec is written beside the code it attests, so
+ * a change to a module that already has tests — the ordinary kind — reaches for
+ * exactly the colliding name.
+ *
+ * Reported here rather than only refused by `--apply` because the fix is a
+ * rename at authoring time and the cost of learning late is a merge stopped
+ * halfway. `--apply` checks it again regardless: this is the one failure mode of
+ * that command that would destroy work rather than halt, and a check living in a
+ * different command is not a guard.
+ */
+function proposedNameTakenIssues(root, scan) {
+    const taken = new Set(scan.specFiles);
+    return scan.proposedSpecFiles
+        .filter((p) => taken.has(mergedSpecPath(p)))
+        .map((p) => ({
+        level: 'ERROR',
+        code: 'proposed-spec-name-taken',
+        file: relativePath(root, p),
+        message: `${relativePath(root, p)} merges to ${relativePath(root, mergedSpecPath(p))}, which already exists — the rename would overwrite it. ` +
+            `Give the proposed spec a name whose merged form is free; several spec files may sit beside one module, but only one may hold each name.`,
+    }));
+}
+/**
+ * A spec still sitting under `changes/` (design §7).
+ *
+ * The companion to `unclaimedProposedSpecIssues`, and the reason both exist is
+ * the same: a spec that runs nowhere. That one covers a file at the right path
+ * no delta reaches; this one covers a file no *scan* reaches, which is the
+ * blind spot moving specs to their merged location opened underneath it.
+ *
+ * `check` rather than the gate, for the reason ATX-47 gives about its sibling
+ * and one more of its own: the gate does speak here, but it says
+ * `uncovered-requirement` — the added ids genuinely have no scenario the plan
+ * can see — and sends an author who has written those scenarios off to write
+ * them again or defer a finished requirement. `check` is both the command a
+ * pipeline runs first and, until this, the one that said nothing at all.
+ *
+ * No `reqId`: the finding is about a file and a path, and no requirement is
+ * implicated by it — the ids the file covers are exactly what cannot be read
+ * without walking it.
+ */
+async function changeDirSpecIssues(root) {
+    const files = await findChangeDirSpecs(root);
+    return files.map((abs) => {
+        const file = relativePath(root, abs);
+        return {
+            level: 'ERROR',
+            code: 'spec-in-change-dir',
+            file,
+            message: `${file} is a spec under changes/, which no command walks: it runs in neither the base suite nor any change's gate. ` +
+                `Move it beside the code it attests and name it *.proposed.spec.ts — that is where a change's specs live, and it is what lets merging one be a rename in place.`,
+        };
+    });
+}
+/**
+ * A `*.proposed.spec.ts` no change's delta claims (design §7).
+ *
+ * A proposed spec is kept out of every normal run by its name and pulled into a
+ * gate run by its requirement ids, so one whose ids no delta mentions is a file
+ * that never executes anywhere — the silent drop this marker would otherwise
+ * cost. The base suite cannot catch it (the file is excluded there by design)
+ * and neither can the gate (it is scoped to what its own delta claims), which
+ * leaves `check` as the only command positioned to see it at all.
+ *
+ * A delta that cannot be read is reported as itself rather than turned into
+ * accusations against its specs: not knowing what a change claims is a different
+ * finding from knowing it claims nothing, and `check` already owes the first one
+ * — a change delta is intent, and the commands that only report read it from
+ * source (design §5.1).
+ */
+async function unclaimedProposedSpecIssues(root, scan, options) {
+    if (scan.proposedSpecFiles.length === 0)
+        return [];
+    const claimed = new Set();
+    const issues = [];
+    for (const name of await listChangeNames(root)) {
+        const read = await readDelta(root, name, options);
+        if ('issue' in read)
+            issues.push(read.issue);
+        else
+            for (const id of claimedIds(read.delta))
+                claimed.add(id);
+    }
+    const proposed = await parseSpecs(scan.proposedSpecFiles, root);
+    const claimedFiles = new Set(proposed.scenarios.filter((s) => claimed.has(s.reqId)).map((s) => s.file));
+    // Reported per file, not per scenario: the file is the unit a run includes,
+    // so it is the unit that did or did not execute, and one line per scenario
+    // would say the same thing several times about one unread file. Driven off
+    // the scanned files rather than off the parsed scenarios, so a proposed spec
+    // that declares no scenario at all is reported too — that one is claimed by
+    // nothing for a second reason, and reading the plan alone cannot see it.
+    for (const abs of scan.proposedSpecFiles) {
+        const file = relativePath(root, abs);
+        if (claimedFiles.has(file))
+            continue;
+        issues.push({
+            level: 'ERROR',
+            code: 'proposed-spec-unclaimed',
+            file,
+            message: `${file} is a proposed spec, but no change under changes/ declares a requirement it covers, ` +
+                `so no gate run will ever include it. Add its requirement ids to that change's ` +
+                `${CHANGE_DELTA_FILE}, or rename the file to *.spec.ts if the behaviour has already merged.`,
+        });
+    }
+    return issues;
+}
+/**
+ * A verdict reached without running anything — the shape a refusal takes.
+ *
+ * `passed` is false rather than true: nothing ran, and a result claiming the
+ * suite passed because it never started is the silent-green this tool exists to
+ * refuse. The counts are zero for the same reason `Running 0 spec files` would
+ * be honest — they report what was looked at, and nothing was.
+ */
+function emptyVerify(issues) {
+    return {
+        issues,
+        passed: false,
+        ok: false,
+        counts: { requirements: 0, scenarios: 0, specFiles: 0, attesting: 0 },
+    };
+}
 /**
  * The spec files a run should execute: the ones that declare a `requirement()`.
  *
@@ -57,6 +197,9 @@ function attestingFiles(plan) {
 }
 /** Executable verification (design §9: `attest verify`). */
 export async function runVerify(root, options = {}) {
+    const unusable = compilerIssue();
+    if (unusable)
+        return emptyVerify([unusable]);
     const scan = await scanProject(root);
     const loader = await createLoader();
     let registry;
@@ -103,6 +246,7 @@ export async function runVerify(root, options = {}) {
             passed: true,
             runtimeCoverage: new Map(),
             outcomes: new Map(),
+            unloadedFiles: [],
         }
         : await runAndCollect({
             root,
@@ -128,6 +272,9 @@ export async function runVerify(root, options = {}) {
  * shape it can take.
  */
 export async function runCover(root, options = {}) {
+    const unusable = compilerIssue();
+    if (unusable)
+        return { rows: [], issues: [unusable] };
     const scan = await scanProject(root);
     const { registry, issues: loadIssues } = await readRegistry(root, options, scan.reqsFiles);
     if (hasError(loadIssues))
@@ -155,6 +302,9 @@ export async function runCover(root, options = {}) {
  * every time a line moves in a test file.
  */
 export async function runRender(root, options = {}) {
+    const unusable = compilerIssue();
+    if (unusable)
+        return { markdown: '', issues: [unusable] };
     const { registry, issues } = await readRegistry(root, options);
     // A registry that failed to load yields a document that silently omits
     // requirements. An incomplete spec doc is worse than none, so refuse.
@@ -215,10 +365,9 @@ export async function runInit(root, names) {
  * MR title.
  *
  * The test is path safety, not a character whitelist: the name never reaches a
- * glob (only *sibling* names do, and changeExcludeGlobs escapes those), so
- * `feat(auth)` or a name with a space is a perfectly good directory and there
- * is no reason for the gate to refuse it. Rejecting only what can escape the
- * directory keeps the guard exactly as wide as the danger.
+ * glob, so `feat(auth)` or a name with a space is a perfectly good directory
+ * and there is no reason for the gate to refuse it. Rejecting only what can
+ * escape the directory keeps the guard exactly as wide as the danger.
  */
 function isSafeChangeName(name) {
     return (name !== '' &&
@@ -229,29 +378,21 @@ function isSafeChangeName(name) {
         !name.includes('\0'));
 }
 /**
- * The globs that keep *other* proposals out of a change's gate run.
+ * Escape a path so a run's `include` matches that file and nothing else.
  *
- * Sibling names come from `readdir`, not from the guard above, so they are
- * escaped: a directory called `feat(auth)` pasted in raw is a *pattern*, it
- * matches nothing, and that sibling's specs silently join the run — quietly
- * widening the scope of the one check that decides "done".
+ * The backslash comes first, and it is the one that matters most: it is glob's
+ * own escape character, so a path containing one is not merely unescaped, it
+ * silently rewrites the pattern around it — `a\b` reads as an escaped `b` and
+ * matches `ab`, never the file itself. These paths come from the tree, not from
+ * the change-name guard above, so they are escaped rather than refused: a file
+ * that exists is not ours to reject.
+ *
+ * This used to escape *sibling change names* too, for the exclude globs that
+ * kept other proposals out of a gate run. Those globs are gone with the
+ * directory that made them possible; the include list is now the plan's own
+ * files, which is a set rather than a pattern.
  */
-export function changeExcludeGlobs(others) {
-    return others.map((n) => `**/changes/${escapeGlob(n)}/**`);
-}
 function escapeGlob(name) {
-    // The backslash comes first, and it is the one that matters most: it is
-    // glob's own escape character, so a name containing one is not merely
-    // unescaped, it silently rewrites the pattern around it. On POSIX a
-    // backslash is a legal filename character, so `changes/a\b` produced the
-    // exclude glob `**/changes/a\b/**`, which globbing reads as an escaped `b` —
-    // matching `ab`, never the directory itself. That sibling's specs then
-    // joined the gate run, quietly widening the scope of the one check that
-    // decides whether a change is done.
-    //
-    // Escaped rather than rejected, because these names are not the change name
-    // the guard above screens: they come from `readdir`, and a directory that
-    // exists is not ours to refuse.
     return name.replace(/[\\*?[\]{}()!+@|^$]/g, '\\$&');
 }
 /** The delta a change is declared in (design §7). */
@@ -325,14 +466,53 @@ async function readDelta(root, changeName, options) {
         },
     };
 }
+/**
+ * One entry per claimed proposed spec, carrying the ids it declares a scenario
+ * for — what `--apply` needs to know which registry to repoint its import at.
+ *
+ * Built from the plan rather than by re-parsing, so the files `--apply` touches
+ * are exactly the files the gate ran.
+ */
+function claimedSpecsOf(root, plan) {
+    const byFile = new Map();
+    for (const sc of plan.scenarios) {
+        const set = byFile.get(sc.file) ?? new Set();
+        set.add(sc.reqId);
+        byFile.set(sc.file, set);
+    }
+    return [...byFile.entries()]
+        .sort(([a], [b]) => byCodeUnit(a, b))
+        .map(([file, ids]) => ({ file: join(root, file), reqIds: [...ids].sort(byCodeUnit) }));
+}
+/** Split a plan over the proposed specs into the part one delta claims. */
+function claimedByDelta(proposed, delta) {
+    const claimed = new Set(claimedIds(delta));
+    // A file is claimed whole or not at all. Scenarios in one file can name
+    // several requirements, and running half a file is not something Vitest can
+    // be asked for — the run scope is a set of files — so a per-scenario split
+    // would make the static plan describe a run that cannot happen.
+    const files = new Set(proposed.scenarios.filter((s) => claimed.has(s.reqId)).map((s) => s.file));
+    const scenarios = proposed.scenarios.filter((s) => files.has(s.file));
+    // A `ParamRef` records a requirement and a scenario name, not a file, so it
+    // is carried by the scenario it was seen in rather than filtered on its own.
+    // Dropping the pair down to `reqId` would let a param read in a *merged*
+    // scenario silence the drift heuristic for a proposed one, and vice versa.
+    const key = (reqId, scenario) => JSON.stringify([reqId, scenario]);
+    const kept = new Set(scenarios.map((s) => key(s.reqId, s.name)));
+    return {
+        scenarios,
+        paramRefs: proposed.paramRefs.filter((p) => kept.has(key(p.reqId, p.scenario))),
+    };
+}
 /**
  * The static plan a change is gated and reported against: the base suite plus
- * the change's own specs (design §8). Takes the spec files rather than finding
- * them, so a caller that already scanned the tree does not walk it twice.
+ * the specs this change's delta claims (design §8). Takes the scan rather than
+ * walking the tree again, so a caller that already scanned does not repeat it.
  */
-async function changeMergedPlan(root, changeName, specFiles) {
-    const basePlan = await parseSpecs(specFiles, root);
-    const changePlan = await parseChangeSpecs(root, changeName);
+async function changeMergedPlan(root, delta, scan) {
+    const basePlan = await parseSpecs(scan.specFiles, root);
+    const proposed = await parseSpecs(scan.proposedSpecFiles, root);
+    const changePlan = claimedByDelta(proposed, delta);
     return {
         scenarios: [...basePlan.scenarios, ...changePlan.scenarios],
         paramRefs: [...basePlan.paramRefs, ...changePlan.paramRefs],
@@ -340,6 +520,7 @@ async function changeMergedPlan(root, changeName, specFiles) {
 }
 /** Per-change progress (design §9: `attest status <change>`). */
 export async function runStatus(root, changeName, options = {}) {
+    const unusable = compilerIssue();
     const nothing = (issues) => ({
         change: changeName,
         rows: [],
@@ -350,27 +531,66 @@ export async function runStatus(root, changeName, options = {}) {
     // gate checks it: under `--eval` the name reaches a module that is executed.
     if (!isSafeChangeName(changeName))
         return nothing([invalidChangeNameIssue(changeName)]);
+    if (unusable)
+        return nothing([unusable]);
     const read = await readDelta(root, changeName, options);
     if ('issue' in read)
         return nothing([read.issue]);
     const scan = await scanProject(root);
-    const plan = await changeMergedPlan(root, changeName, scan.specFiles);
+    const plan = await changeMergedPlan(root, read.delta, scan);
     const firstRun = await readRedRecord(root, changeName);
     const rows = statusRows(addedIds(read.delta), plan, firstRun);
     return { change: changeName, rows, counts: statusCounts(rows), issues: [] };
 }
 /** Archive gate for a change (design §8, §9: `attest archive <change>`). */
 export async function runArchive(root, changeName, options = {}) {
+    return (await archiveRun(root, changeName, options)).issues;
+}
+/**
+ * The gate, and — only if it passes — the merge it approved
+ * (`attest archive <change> --apply`).
+ *
+ * The gate runs first and unconditionally, in this same call. A merge acting on
+ * an earlier run's verdict would let an unfinished change be filed as done, and
+ * "done" having a hard definition is the whole claim of the tool; so a red gate
+ * writes nothing, and there is no flag that skips it.
+ */
+export async function runArchiveApply(root, changeName, options = {}) {
+    const { issues, merge } = await archiveRun(root, changeName, options);
+    if (issues.some((i) => i.level === 'ERROR') || !merge)
+        return { issues, written: [] };
+    const result = await applyMerge({ root, changeName, ...merge });
+    // The gate's non-blocking output is kept: a WARNING the gate raised is still
+    // true after the merge, and dropping it here would make `--apply` quieter than
+    // the same command without it.
+    return { issues: [...issues, ...result.issues], written: result.written };
+}
+/**
+ * The gate, plus what finishing the merge would need.
+ *
+ * One function rather than a gate and a separate `--apply` path, because the
+ * merge must act on **this** run's verdict. A second traversal could reach a
+ * different answer than the one just printed — and a command able to file a
+ * change as done against a stale verdict removes the hard definition of "done"
+ * that is this tool's whole claim.
+ *
+ * `merge` is absent exactly when there is nothing to act on: a rejected name, an
+ * unreadable delta, or a registry that would not load.
+ */
+async function archiveRun(root, changeName, options = {}) {
     // Checked before any loader starts: nothing should be resolved, let alone
     // evaluated, on behalf of a name we have already rejected.
     if (!isSafeChangeName(changeName))
-        return [invalidChangeNameIssue(changeName)];
+        return { issues: [invalidChangeNameIssue(changeName)] };
+    const unusable = compilerIssue();
+    if (unusable)
+        return { issues: [unusable] };
     const scan = await scanProject(root);
     const loader = await createLoader();
     try {
-        const { registry: base, issues } = await loadRegistry(root, evalReader(loader), scan.reqsFiles);
+        const { registry: base, issues, prefixOwners } = await loadRegistry(root, evalReader(loader), scan.reqsFiles);
         if (issues.some((i) => i.level === 'ERROR'))
-            return issues;
+            return { issues };
         const deltaPath = changeDeltaPath(root, changeName);
         let delta;
         try {
@@ -387,22 +607,22 @@ export async function runArchive(root, changeName, options = {}) {
             delta = mod.default;
         }
         catch (err) {
-            return [changeNotFoundIssue(root, deltaPath, changeName, err)];
+            return { issues: [changeNotFoundIssue(root, deltaPath, changeName, err)] };
         }
         const applied = applyDelta(base, delta);
         if (applied.issues.length > 0)
-            return applied.issues;
+            return { issues: applied.issues };
         // Static plan = merged base suite + this change's specs (design §8), by the
         // same function `status` reports against — a progress report computed over a
         // different spec set than the gate uses would be a report about nothing.
-        const plan = await changeMergedPlan(root, changeName, scan.specFiles);
-        // Run base specs + this change's specs; exclude other proposals and archive.
-        const others = (await listChangeNames(root)).filter((n) => n !== changeName);
-        const exclude = [
-            ...BASE_EXCLUDE,
-            '**/archive/**',
-            ...changeExcludeGlobs(others),
-        ];
+        const plan = await changeMergedPlan(root, delta, scan);
+        // Other proposals need no exclude glob of their own: the include list below
+        // is the plan's own files, and the plan holds only the proposed specs this
+        // delta claims. That is what replaced `**/changes/<sibling>/**` — with the
+        // specs no longer living under `changes/`, a directory glob could not have
+        // told two proposals apart, and one kept alongside the claim check would be
+        // a second scoping rule able to disagree with it.
+        const exclude = [...BASE_EXCLUDE, '**/archive/**'];
         // Same run scope as `verify`: only the files that declare a requirement().
         // The gate must not go red because a repo's incumbent suite happens to sit
         // under the same root as the change being archived.
@@ -429,7 +649,30 @@ export async function runArchive(root, changeName, options = {}) {
                 await writeAtomic(redRecordPath(root, changeName), serialiseRedRecord(changeName, merged.record));
             }
         }
-        return evaluateGate({ registry: applied.registry, plan, run, addedIds: added, firstRun });
+        // Against `base`, not `applied`: the child run imported the registry from
+        // disk, so what matters is what that file has, not what the gate computed.
+        const unmergedAddedIds = added.filter((id) => !Object.hasOwn(base, id));
+        return {
+            issues: evaluateGate({
+                registry: applied.registry,
+                plan,
+                run,
+                addedIds: added,
+                unmergedAddedIds,
+                firstRun,
+            }),
+            merge: {
+                delta,
+                base,
+                applied: applied.registry,
+                prefixOwners,
+                // The plan's proposed files, not every proposed file on disk: `--apply`
+                // renames what *this* change claims, and a sibling proposal's spec is
+                // not this change's to move.
+                claimedSpecs: claimedSpecsOf(root, claimedByDelta(await parseSpecs(scan.proposedSpecFiles, root), delta)),
+                mergedSpecs: scan.specFiles,
+            },
+        };
     }
     finally {
         await loader.close();

package/dist/core/registry.d.ts

@@ -75,10 +75,69 @@ export interface RegistryDelta {
     }[];
 }
 /**
- * Declare a registry delta for a change. This is an identity pass-through that
- * fixes the authoring surface; ordered idempotent application
- * (RENAMED -> REMOVED -> MODIFIED -> ADDED) lives in applyDelta (design §7).
+ * The requirements a delta ADDs, keyed by id and typed at the params written —
+ * the same shape {@link defineRequirements} returns, over the half of a change
+ * that introduces requirements.
+ *
+ * MODIFIED ids are deliberately absent. A modified requirement's end state is
+ * the base entry with the patch applied, and the base is not in this file; a
+ * view that showed the patch alone would answer `params.x` with the proposed
+ * value and `params.y` with `undefined` for a key the requirement has. That is
+ * a shape that reads as the merged requirement and is not one, which is worse
+ * than not offering it.
+ */
+type ProposedRequirements<T extends RegistryDelta> = T extends {
+    added: infer A;
+} ? {
+    [K in keyof A]: Omit<Requirement, 'params'> & {
+        params: DefinedParams<A[K]>;
+    };
+} : unknown;
+/**
+ * What `delta()` returns: the delta itself, also readable as the registry of
+ * what it proposes.
+ *
+ * The union is safe by grammar rather than by convention — a requirement id
+ * matches `/^[A-Z]+-\d+$/` (`RequirementIdSchema`), so no id can ever be spelled
+ * `added`, `modified`, `removed` or `renamed`. That is what lets one value carry
+ * both surfaces without either shadowing the other.
+ *
+ * There is no index signature, unlike {@link DefinedRegistry}. That one keeps
+ * its because `reqs[id]` with an `id: string` is a real pattern in a shared test
+ * helper over a whole registry; the ids a single change adds are few and known
+ * at the call site, so the stricter shape costs nothing and rejects a mistyped
+ * id outright instead of leaving it to `check`.
+ */
+export type DefinedDelta<T extends RegistryDelta> = T & ProposedRequirements<T>;
+/**
+ * Declare a registry delta for a change (design §7). Ordered idempotent
+ * application (RENAMED -> REMOVED -> MODIFIED -> ADDED) lives in applyDelta.
+ *
+ * The returned value is the delta *and* the registry of the requirements it
+ * adds, so a stage-1 scenario reads a proposed param with the expression a
+ * merged one uses — `reqs['AUTH-7'].params.totpWindowSec`, not
+ * `d.added!['AUTH-7']!.params!.totpWindowSec as number`. Stage 1 is where the
+ * scenario must be written and must go red, which made it the one stage where
+ * the workflow pushed the author off `params`, the single source the whole tool
+ * exists to reward — and then billed them the rewrite at merge for having
+ * complied. Now merging a spec changes its import and nothing else.
+ *
+ * Still no validation, deliberately. A delta carrying an id the registry would
+ * refuse is an `add-invalid` / `rename-target-invalid` ERROR from the gate
+ * (ATX-41), which is where a reviewer sees it; throwing here would move that
+ * verdict into whichever command happened to evaluate the file first.
+ */
+export declare function delta<const T extends RegistryDelta>(d: T): DefinedDelta<T>;
+/**
+ * A delta, also keyed by the ids it ADDs. The one place that shape is built.
+ *
+ * Both readers go through this — `delta()` on the evaluated path, and
+ * `readDeltaSource` on the static one — because the differential suite asserts
+ * the two agree about what a delta *is*, and a second copy of this three-line
+ * spread is exactly the kind of agreement that holds by transcription until it
+ * does not. A new object rather than a mutated argument, so the literal a
+ * caller wrote is still the literal they hold.
  */
-export declare function delta(d: RegistryDelta): RegistryDelta;
+export declare function withProposedRequirements<T extends RegistryDelta>(d: T): T;
 export {};
 //# sourceMappingURL=registry.d.ts.map

package/dist/core/registry.js

@@ -34,11 +34,37 @@ export function defineRequirements(input) {
     return result.data;
 }
 /**
- * Declare a registry delta for a change. This is an identity pass-through that
- * fixes the authoring surface; ordered idempotent application
- * (RENAMED -> REMOVED -> MODIFIED -> ADDED) lives in applyDelta (design §7).
+ * Declare a registry delta for a change (design §7). Ordered idempotent
+ * application (RENAMED -> REMOVED -> MODIFIED -> ADDED) lives in applyDelta.
+ *
+ * The returned value is the delta *and* the registry of the requirements it
+ * adds, so a stage-1 scenario reads a proposed param with the expression a
+ * merged one uses — `reqs['AUTH-7'].params.totpWindowSec`, not
+ * `d.added!['AUTH-7']!.params!.totpWindowSec as number`. Stage 1 is where the
+ * scenario must be written and must go red, which made it the one stage where
+ * the workflow pushed the author off `params`, the single source the whole tool
+ * exists to reward — and then billed them the rewrite at merge for having
+ * complied. Now merging a spec changes its import and nothing else.
+ *
+ * Still no validation, deliberately. A delta carrying an id the registry would
+ * refuse is an `add-invalid` / `rename-target-invalid` ERROR from the gate
+ * (ATX-41), which is where a reviewer sees it; throwing here would move that
+ * verdict into whichever command happened to evaluate the file first.
  */
 export function delta(d) {
-    return d;
+    return withProposedRequirements(d);
+}
+/**
+ * A delta, also keyed by the ids it ADDs. The one place that shape is built.
+ *
+ * Both readers go through this — `delta()` on the evaluated path, and
+ * `readDeltaSource` on the static one — because the differential suite asserts
+ * the two agree about what a delta *is*, and a second copy of this three-line
+ * spread is exactly the kind of agreement that holds by transcription until it
+ * does not. A new object rather than a mutated argument, so the literal a
+ * caller wrote is still the literal they hold.
+ */
+export function withProposedRequirements(d) {
+    return { ...d, ...(d.added ?? {}) };
 }
 //# sourceMappingURL=registry.js.map