@am_shork/attest 0.9.4 → 0.11.0

package/README.md

@@ -16,28 +16,6 @@ anyone when a tuning knob changes. A param may be any JSON value, so a
 composite constant — a vendor blacklist, a `kind -> payload` table — gets the
 same single source as a lone number, which is where drift is worst.
 
-What that does not buy is a warning when you change the value. `check` runs
-nothing, so editing a param leaves it at `✓ No issues` — nothing became unbound,
-nothing became uncovered. The value cannot *diverge* from the assertion, which is
-the stronger property; noticing that it *moved* is `verify`'s job, and only when
-a scenario asserts on the value it read from `params`.
-
-Reading the param is necessary and **not sufficient**, which is worth knowing
-before you rely on it: an assertion that recomputes its expectation from the same
-param the code under test just read has no independent term, so both sides move
-together and the test 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.
-
-A composite param has a second failure of its own, and it runs the other way. When
-a test **loops over** a list it read from `params`, that list is the set of cases
-the run covers: drop a member and every assertion inside the loop still passes
-over what is left, so the suite quietly tests less with nothing to show for it.
-Pin the extent beside the loop — the members against a literal when their identity
-is the promise, the length when the size is. That literal is not the copy the
-single source exists to prevent: it is not what the system is measured against,
-it is what the intent claimed to cover.
-
 ## Prerequisites
 
 - Node ≥ 20.19
@@ -134,7 +112,14 @@ for exactly one machine-readable document on stdout. Flags, per-command
 behaviour and the JSON shape are in the
 [CLI reference](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/cli-reference.md).
 
-### Working with an agent
+Reading a param is necessary and **not sufficient** — an assertion that
+recomputes its expectation from the same param the code just read has no
+independent term, and a scenario that loops over a list param covers exactly
+that list. Both have a known shape and a known repair, and both are in
+[Judging your own intent layer](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/intent-quality.md#writing-a-param-that-pins-something),
+along with the decision table — the shape a composite param is best at.
+
+## Working with an agent
 
 The engine above is only half the framework. The other half is the workflow —
 agree on intent, write the delta, drive the scenarios red, then implement to
@@ -146,12 +131,19 @@ attest init --target cursor    # .cursor/rules/attest.mdc
 attest init --target copilot   # .github/instructions/attest.instructions.md
 ```
 
-"Red before you implement" is enforced rather than advised: `archive` records how
-each of a change's scenarios ended on its first run, into
-`changes/<name>/first-run.json`, and blocks with `never-red` on any requirement
-the delta adds whose scenarios were never seen to fail. Commit `first-run.json`
-with the change — it is the evidence, and CI has to reach the same verdict as
-you do.
+"Every scenario has been seen to fail" is enforced rather than advised:
+`archive` records how each of a change's scenarios ended in every run it
+observes, into `changes/<name>/first-run.json`, and blocks with `never-red` on
+any requirement the delta adds whose scenarios were never seen to fail. Commit
+`first-run.json` with the change — it is the evidence, and CI has to reach the
+same verdict as you do.
+
+**It does not require you to write the test first.** A recorded failure is
+permanent and a recorded pass is not, so a failure observed after the
+implementation exists satisfies the gate exactly like one observed before it:
+if you wrote the intent, the scenario and the code together, remove the
+implementation, run `archive`, and put it back. What is enforced is that the
+assertion can fail — not the order you worked in.
 
 An agent loads the document on its own — its description is already in the
 agent's context, or its path matches what you have open — so nothing has to be
@@ -159,7 +151,7 @@ found or pasted. See
 [`attest init`](https://gitlab.com/Pseudorca/attest/-/blob/main/docs/en/cli-reference.md#attest-init)
 for the targets and what `init` deliberately does not write.
 
-### When something goes wrong
+## When something goes wrong
 
 Every diagnostic carries a `code`, and every code has a section in
 **Troubleshooting** — which the diagnostic itself links to:
@@ -167,7 +159,7 @@ Every diagnostic carries a `code`, and every code has a section in
 ```
 ERROR   registry-not-static (requirements/upload.reqs.ts:5)
     Value is not a literal.
-    → https://gitlab.com/Pseudorca/attest/-/blob/v0.9.4/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.11.0/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section

package/dist/cli/action.js

@@ -73,10 +73,14 @@ export async function runAction(command, opts, action) {
     }
     catch (err) {
         if (opts.json) {
-            // Unsanitised on purpose: `JSON.stringify` escapes every C0 character,
-            // so these bytes cannot carry one out (see report.ts). That is a claim
-            // about what this line writes and nothing wider — what the project under
-            // test writes is the divert's business, above.
+            // Sanitised, though not on this line: `renderJson` strips every string in
+            // the document as it serialises it (ATX-74), so the crash path is covered
+            // by going through the same function every other report goes through.
+            //
+            // Not by `JSON.stringify`, which is what this comment used to claim. That
+            // escapes C0 and nothing else — DEL and the C1 range survive it — so the
+            // replacer in `renderJson` is load-bearing rather than belt and braces.
+            // What the project under test writes is still the divert's business, above.
             console.log(renderJson(errorReport(VERSION, command, err)));
         }
         else {

package/dist/cli/index.js

@@ -261,10 +261,15 @@ program
     const { issues: blocking, written } = await run(root(dir), change, {
         vitestConfig: vitestConfig(opts),
     });
+    // Built once and handed to both renderings, rather than each being told
+    // separately what the merge did. Two renderings of one result agreeing by
+    // transcription is what let the verdict disagree with itself (ATX-60),
+    // and the paths are the other thing this command has to say.
+    const merge = { applied: opts.apply === true, written };
     return {
-        report: archiveReport(VERSION, change, blocking),
+        report: archiveReport(VERSION, change, blocking, merge),
         human: () => {
-            console.log(formatArchiveVerdict(change, blocking, { applied: opts.apply === true, written }));
+            console.log(formatArchiveVerdict(change, blocking, merge));
         },
     };
 }));

package/dist/cli/json.d.ts

@@ -33,6 +33,22 @@ export interface JsonReport {
     };
     /** `archive` and `status`: the change being gated or reported on. */
     change?: string;
+    /**
+     * `archive --apply` only: every path the merge touched, relative to the
+     * project root, in the order it touched them.
+     *
+     * Additive, so no SCHEMA_VERSION bump. **Absent** when `--apply` was not
+     * asked for — no merge was attempted, and there is nothing to report — while
+     * an **empty array** means the merge ran and had nothing left to write, which
+     * is the ordinary state of a re-run after a completed one. Folding the two
+     * into `[]` would make the field unable to say which happened.
+     *
+     * The human rendering has printed these since `--apply` shipped, on the
+     * grounds that this is the command that edits files the user cannot
+     * regenerate and they need to know which ones to read before committing. That
+     * argument does not stop at the reader with a terminal.
+     */
+    written?: string[];
     /** `status` only: one row per requirement the change adds. */
     progress?: StatusRow[];
     /** `status` only: roll-up of the rows by obligation state. */
@@ -83,7 +99,18 @@ export declare function renderReport(version: string, issues: Issue[], outFile?:
  * was added for, to say something the array already says.
  */
 export declare function initReport(version: string, issues: Issue[], outFiles: string[]): JsonReport;
-export declare function archiveReport(version: string, change: string, blocking: Issue[]): JsonReport;
+/**
+ * `archive`, and — when `--apply` was asked for — what the merge wrote.
+ *
+ * `merge` is the same bundle `formatArchiveVerdict` takes, passed to both from
+ * one place in the shell. The two renderings of one result had already grown
+ * apart once over the verdict (ATX-60); handing them the same object is what
+ * stops the paths from being the second thing they disagree about.
+ */
+export declare function archiveReport(version: string, change: string, blocking: Issue[], merge?: {
+    applied: boolean;
+    written: readonly string[];
+}): JsonReport;
 /**
  * `status`. The progress rows never touch the verdict: `ok` comes from the same
  * `hasError` predicate as everywhere else, over an `issues` array that carries

package/dist/cli/json.js

@@ -109,7 +109,15 @@ export function initReport(version, issues, outFiles) {
     const [only] = outFiles;
     return outFiles.length === 1 && only !== undefined ? { ...report, outFile: only } : report;
 }
-export function archiveReport(version, change, blocking) {
+/**
+ * `archive`, and — when `--apply` was asked for — what the merge wrote.
+ *
+ * `merge` is the same bundle `formatArchiveVerdict` takes, passed to both from
+ * one place in the shell. The two renderings of one result had already grown
+ * apart once over the verdict (ATX-60); handing them the same object is what
+ * stops the paths from being the second thing they disagree about.
+ */
+export function archiveReport(version, change, blocking, merge) {
     return {
         ...envelope({
             version,
@@ -123,6 +131,7 @@ export function archiveReport(version, change, blocking) {
             issues: blocking,
         }),
         change,
+        ...(merge?.applied ? { written: [...merge.written] } : {}),
     };
 }
 /**

package/dist/core/archive.js

@@ -35,11 +35,26 @@
 // present without a given scenario is one that did and then drifted.
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { forEachBounded } from './locate.js';
 import { byCodeUnit } from './order.js';
 import { relativePath } from './paths.js';
 import { keepOutcome, readRedRecordIn } from './red-record.js';
 /** The directory archived changes are moved into, under the project root. */
 const ARCHIVE_DIR = 'archive';
+/**
+ * How many archived first-run records are read at once. Its own constant for
+ * the reason `WALK_CONCURRENCY` gives, and a fourth resource: what this bounds
+ * is the *parsed records held at once*, not descriptors. `readFile` does
+ * open-read-close inside one libuv threadpool work item, so concurrent
+ * descriptors track the threadpool and never the fan-out — measured, 3,000
+ * unbounded reads peaked at 53 open handles. Heap is what tracks the input, and
+ * a project's archive grows by one folder per change merged, forever, so the
+ * list is as much the project's shape as a spec tree is.
+ * `Promise.all(names.map(...))` put every record in flight at once: measured at
+ * the `fs` seam, 64 changes peaked at 64 concurrent reads, and 2,000 records of
+ * 45 KB peaked at 352 MB of heap against 177 MB bounded.
+ */
+const ARCHIVE_CONCURRENCY = 32;
 /**
  * Read every archived change folder under `root`.
  *
@@ -67,10 +82,18 @@ export async function readArchivedChanges(root) {
         .filter((e) => e.isDirectory())
         .map((e) => e.name)
         .sort(byCodeUnit);
-    return Promise.all(names.map(async (name) => {
+    // Preallocated and written by `index`, which is how a `forEachBounded` caller
+    // keeps a stable result: the pool calls in input order but completes in
+    // whatever order the disk answers, and `names` is already sorted above.
+    const changes = new Array(names.length);
+    await forEachBounded(names, ARCHIVE_CONCURRENCY, async (name, i) => {
+        // `readRedRecordIn` catches its own read and parse, so nothing here can
+        // throw and abandon the rest — the same thing `readGuarded` is for on the
+        // registry pool, and what keeps every slot of the array above filled.
         const path = join(dir, name);
-        return { name, path: relativePath(root, path), firstRun: await readRedRecordIn(path) };
-    }));
+        changes[i] = { name, path: relativePath(root, path), firstRun: await readRedRecordIn(path) };
+    });
+    return changes;
 }
 /**
  * The archive's first-run evidence, merged across every archived change.

package/dist/core/gate.d.ts

@@ -102,17 +102,27 @@ export declare function specLoadFailedIssues(run: RunResult, already?: ReadonlyS
  */
 export declare function notRunIssues(plan: AttestPlan, run: RunResult, specific?: readonly Issue[]): Issue[];
 /**
- * Never-red: a scenario attesting a requirement this change ADDs, whose first
- * observed run did not fail (design §6, mechanism 2).
+ * Never-red: a scenario attesting a requirement this change ADDs, which no run
+ * the gate observed has seen fail (design §6, mechanism 2).
  *
  * This is the half of the gate that certifies the tests ever *discriminated*.
  * Green at archive time says only that they pass now — a scenario that asserted
  * nothing has been green since the commit that added it and clears every other
  * check identically. The two states are reported apart because the fixes differ:
- * a first run that passed means the scenario does not test what it claims, while
- * no observation at all means the workflow's stage-1 step was skipped, and the
- * remedy for the second is to run the gate before implementing rather than to
- * rewrite anything.
+ * a scenario observed passing and never failing does not test what it claims,
+ * while no observation at all means no run has been taken yet, and the remedy
+ * for the second is to take one rather than to rewrite anything.
+ *
+ * **The obligation is discrimination, and it says nothing about ordering.** The
+ * record is monotonic toward failure but a pass is provisional (`red-record.ts`),
+ * so a failure observed *after* the implementation exists replaces a recorded
+ * pass and satisfies this exactly like one observed before it. Running the gate
+ * first is the cheapest route to the evidence and not the only one: removing the
+ * implementation, running the gate, and restoring it produces the same fact by
+ * the same command. Nothing here could enforce an order anyway — a stage-1 red
+ * can come from a typo in the spec rather than from the requirement being
+ * unimplemented, so an earlier observation was never stronger evidence, only
+ * earlier.
  *
  * Scoped to ADDED ids only. A requirement written straight into the base
  * registry — which is how existing behaviour gets described, in a brownfield

package/dist/core/gate.js

@@ -132,17 +132,27 @@ export function notRunIssues(plan, run, specific = []) {
     ];
 }
 /**
- * Never-red: a scenario attesting a requirement this change ADDs, whose first
- * observed run did not fail (design §6, mechanism 2).
+ * Never-red: a scenario attesting a requirement this change ADDs, which no run
+ * the gate observed has seen fail (design §6, mechanism 2).
  *
  * This is the half of the gate that certifies the tests ever *discriminated*.
  * Green at archive time says only that they pass now — a scenario that asserted
  * nothing has been green since the commit that added it and clears every other
  * check identically. The two states are reported apart because the fixes differ:
- * a first run that passed means the scenario does not test what it claims, while
- * no observation at all means the workflow's stage-1 step was skipped, and the
- * remedy for the second is to run the gate before implementing rather than to
- * rewrite anything.
+ * a scenario observed passing and never failing does not test what it claims,
+ * while no observation at all means no run has been taken yet, and the remedy
+ * for the second is to take one rather than to rewrite anything.
+ *
+ * **The obligation is discrimination, and it says nothing about ordering.** The
+ * record is monotonic toward failure but a pass is provisional (`red-record.ts`),
+ * so a failure observed *after* the implementation exists replaces a recorded
+ * pass and satisfies this exactly like one observed before it. Running the gate
+ * first is the cheapest route to the evidence and not the only one: removing the
+ * implementation, running the gate, and restoring it produces the same fact by
+ * the same command. Nothing here could enforce an order anyway — a stage-1 red
+ * can come from a typo in the spec rather than from the requirement being
+ * unimplemented, so an earlier observation was never stronger evidence, only
+ * earlier.
  *
  * Scoped to ADDED ids only. A requirement written straight into the base
  * registry — which is how existing behaviour gets described, in a brownfield
@@ -165,8 +175,8 @@ export function neverRedIssues(plan, addedIds, firstRun) {
             file: s.file,
             line: s.line,
             message: outcome === 'pass'
-                ? `scenario "${s.name}" passed on its first run, so it never showed that ${s.reqId} was unimplemented; give it an assertion that fails without the change and run the gate again — a later failing run replaces this record.`
-                : `scenario "${s.name}" has no recorded first run for ${s.reqId}; run \`attest archive\` before implementing, so ${RED_RECORD_FILE} records it failing.`,
+                ? `scenario "${s.name}" was observed passing and never failing, so it has not shown that it can fail without ${s.reqId} being implemented; give it an assertion that discriminates and run the gate again — a later failing run replaces this record.`
+                : `scenario "${s.name}" has no observed run recorded for ${s.reqId}; run \`attest archive\` with the implementation absent — before writing it, or with it removed — so ${RED_RECORD_FILE} records the scenario failing.`,
         });
     }
     return issues;

package/dist/core/locate.d.ts

@@ -20,6 +20,33 @@ export declare const isProposedSpecFile: (name: string) => boolean;
  * of them until its gate passes.
  */
 export declare const isSpecFile: (name: string) => boolean;
+/**
+ * Run `fn` over every item with at most `limit` of them in flight.
+ *
+ * Extracted at the second call site rather than the first, because a shape
+ * written N times is one a later fix reaches only some copies of.
+ *
+ * **There are three, and the third is the one to look for.** `findFiles` and
+ * `parseSpecs` are named for what they fan out over; `loadRegistry` is named for
+ * merging, and its concurrency sits under a comment about *ordering* that
+ * answers a different question convincingly. Anything here that reads a list the
+ * project's tree decides the length of belongs in this pool, whatever the
+ * function around it is called.
+ *
+ * The order `fn` is *called* in is the input order; the order it *completes* in
+ * is not, so a caller that needs a stable result either indexes into a
+ * preallocated array by `index` or sorts afterwards. All three callers here do
+ * one of those, deliberately — as does `readArchivedChanges`, the caller
+ * outside this file, which preallocates and writes by `index`.
+ *
+ * No result is collected and none is needed — every caller writes into something
+ * it already owns, and a version returning `T[]` would have to choose an
+ * ordering on their behalf. A throw from `fn` propagates and abandons the rest,
+ * which is the existing behaviour at all three sites: `parseSpecs` and
+ * `loadRegistry` catch per file so that one hostile source scraps only itself
+ * (ATX-65), and a failed `readdir` really does end the walk.
+ */
+export declare function forEachBounded<T>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<void>): Promise<void>;
 /**
  * Recursively find files under root whose basename matches `match`.
  *

package/dist/core/locate.js

@@ -56,7 +56,8 @@ export const isSpecFile = (name) => name.endsWith('.spec.ts') && !isProposedSpec
  * The order `fn` is *called* in is the input order; the order it *completes* in
  * is not, so a caller that needs a stable result either indexes into a
  * preallocated array by `index` or sorts afterwards. All three callers here do
- * one of those, deliberately.
+ * one of those, deliberately — as does `readArchivedChanges`, the caller
+ * outside this file, which preallocates and writes by `index`.
  *
  * No result is collected and none is needed — every caller writes into something
  * it already owns, and a version returning `T[]` would have to choose an
@@ -65,7 +66,7 @@ export const isSpecFile = (name) => name.endsWith('.spec.ts') && !isProposedSpec
  * `loadRegistry` catch per file so that one hostile source scraps only itself
  * (ATX-65), and a failed `readdir` really does end the walk.
  */
-async function forEachBounded(items, limit, fn) {
+export async function forEachBounded(items, limit, fn) {
     let cursor = 0;
     const worker = async () => {
         for (let i = cursor++; i < items.length; i = cursor++) {

package/dist/core/merge.js

@@ -319,6 +319,7 @@ function modifyRefusal(root, file, refusal) {
     const where = refusal.field ? `${refusal.reqId}.${refusal.field}` : refusal.reqId;
     const why = {
         comment: `a comment sits inside the value it would replace, and which side of that edit the comment belongs to is not something --apply can decide`,
+        'duplicate-key': `that name is written more than once in the file, so the span --apply located is not the one the registry's readers evaluate`,
         'entry-not-found': `the registry file that owns its prefix holds no entry for it`,
         'not-a-literal': `the value it would replace is not written as a literal`,
         'param-dropped': `the proved end state does not carry that param, and a delta has no way to say one was removed`,

package/dist/core/red-record.d.ts

@@ -18,11 +18,11 @@ export declare function redRecordPath(root: string, changeName: string): string;
 /** The file name, exported so a diagnostic can name it without rebuilding it. */
 export declare const RED_RECORD_FILE = "first-run.json";
 /**
- * reqId -> spec file -> scenario name -> the outcome of its first observed run.
+ * reqId -> spec file -> scenario name -> the strongest outcome observed for it.
  *
- * Deliberately not a list of "red scenarios": a scenario whose first run passed
- * is the case mechanism 2 exists to catch, so it has to be recorded as a fact
- * rather than as an absence. An absence then means only one thing — never
+ * Deliberately not a list of "red scenarios": a scenario only ever observed
+ * passing is the case mechanism 2 exists to catch, so it has to be recorded as a
+ * fact rather than as an absence. An absence then means only one thing — never
  * observed at all — and the gate can report the two separately.
  *
  * **The file level is what identifies a scenario, and it was missing.** A

package/dist/core/red-record.js

@@ -1,5 +1,13 @@
-// Mechanism 2's record: what each of a change's scenarios did the *first* time
-// it ran (design §6).
+// Mechanism 2's record: the strongest outcome the gate has ever observed for
+// each of a change's scenarios (design §6).
+//
+// Not "the first run", which is what the file is named after and what this was
+// once described as. The record is revised — see the asymmetry below — and the
+// difference is the whole reason the *order* of the observations is free: an
+// author who has already written the implementation earns the evidence by
+// removing it, running the gate, and restoring it. The file keeps its name
+// because archived records already carry it (`inspect.ts`) and a rename would
+// spend that to fix a word.
 //
 // §8's gate requires green at archive time. That certifies "these tests pass",
 // not "these tests ever discriminated" — a scenario that asserted nothing has
@@ -36,7 +44,8 @@
 // change red. Once a scenario has been seen to fail, nothing can take it back.
 //
 // Provisional pass: plain first-write-wins was the first design here, and it
-// makes the defect this mechanism exists to catch *unrecoverable*. A scenario
+// makes the defect this mechanism exists to catch *unrecoverable*, and it is
+// also what would have made the ordering real. A scenario
 // that passed on its first run is one that asserts nothing; the fix is to give
 // it a real assertion and watch it fail — but under first-write-wins that
 // observation could never be recorded, so the only way out was deleting the
@@ -320,20 +329,30 @@ export function mergeRedRecord(existing, plan, run, addedIds) {
         forFile[s.name] = kept;
         changed = true;
     }
-    // Sort within each requirement, and within each file, for the same
-    // byte-stability reason.
-    for (const id of Object.keys(record)) {
+    // Sort at every level, for the same byte-stability reason — the ids included.
+    //
+    // The rebuild above sorts only the ids the record already held; the loop after
+    // it *appends* the ones this run is the first to observe, in plan order. So
+    // the ids are unsorted by the time this runs, and this is the level that has
+    // to put them in order.
+    //
+    // A rebuild rather than an in-place sort, which is the trap: reassigning
+    // `record[id]` writes a value and does not move a key, so a version of this
+    // that sorted the two inner levels while walking the ids as they came would
+    // leave the outer order exactly as it found it.
+    const sorted = emptyMap();
+    for (const id of Object.keys(record).sort(byCodeUnit)) {
         const sortedFiles = emptyMap();
         for (const file of Object.keys(record[id]).sort(byCodeUnit)) {
-            const sorted = emptyMap();
+            const names = emptyMap();
             for (const name of Object.keys(record[id][file]).sort(byCodeUnit)) {
-                sorted[name] = record[id][file][name];
+                names[name] = record[id][file][name];
             }
-            sortedFiles[file] = sorted;
+            sortedFiles[file] = names;
         }
-        record[id] = sortedFiles;
+        sorted[id] = sortedFiles;
     }
-    return { record, changed };
+    return { record: sorted, changed };
 }
 /** Serialise the record. A trailing newline, so the file is a well-formed text file. */
 export function serialiseRedRecord(changeName, record) {

package/dist/core/registry.d.ts

@@ -115,8 +115,34 @@ type ProposedRequirements<T extends RegistryDelta> = T extends {
  * 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`.
+ *
+ * **`added` is withheld from the type although the value still carries it**, and
+ * that is the one place this shape deliberately understates its own object. Both
+ * `reqs['AUTH-7'].params.x` and `d.added['AUTH-7'].params.x` are correct during
+ * stage 1; only the first survives `--apply`, which repoints the specifier at
+ * the merged registry, and a registry has no `added`. Nothing else catches that:
+ * the gate runs before the rename, `check` executes nothing, and the compiler
+ * sees whichever half is on disk — so the difference appears one command later,
+ * as a `spec-load-failed` naming the file and not the cause.
+ *
+ * The optional `never` rather than a bare `Omit` is load-bearing.
+ * `RegistryDelta`'s four fields are all optional, so an added-only delta with
+ * `added` removed has *no* property in common with it and TypeScript's weak-type
+ * check refuses `applyDelta(base, delta({ added: … }))` outright — nine call
+ * sites in this tree, none of them wrong. An optional property restores the
+ * overlap while still refusing the read, and the refusal survives the escape
+ * hatches that would make it advisory: `d.added!` and `d.added?.[…]` both land
+ * on `never`, and only an explicit `as any` compiles.
+ *
+ * `modified`, `removed` and `renamed` are left alone on purpose. They vanish at
+ * the merge too, but none of them has a by-id equivalent — there is no correct
+ * spelling to redirect an author to, so a spec reading one is reading delta-only
+ * data rather than misspelling a right thing, which is a different defect and
+ * has never been reported.
  */
-export type DefinedDelta<T extends RegistryDelta> = T & ProposedRequirements<T>;
+export type DefinedDelta<T extends RegistryDelta> = Omit<T, 'added'> & {
+    added?: never;
+} & ProposedRequirements<T>;
 /**
  * Declare a registry delta for a change (design §7). Ordered idempotent
  * application (RENAMED -> REMOVED -> MODIFIED -> ADDED) lives in applyDelta.
@@ -130,6 +156,10 @@ export type DefinedDelta<T extends RegistryDelta> = T & ProposedRequirements<T>;
  * exists to reward — and then billed them the rewrite at merge for having
  * complied. Now merging a spec changes its import and nothing else.
  *
+ * That rejected expression is now rejected by the compiler rather than by
+ * this comment — {@link DefinedDelta} withholds `added`, because it was the
+ * one wrong spelling that stage 1 could not tell from the right one.
+ *
  * 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

package/dist/core/registry.js

@@ -48,6 +48,10 @@ export function defineRequirements(input) {
  * exists to reward — and then billed them the rewrite at merge for having
  * complied. Now merging a spec changes its import and nothing else.
  *
+ * That rejected expression is now rejected by the compiler rather than by
+ * this comment — {@link DefinedDelta} withholds `added`, because it was the
+ * one wrong spelling that stage 1 could not tell from the right one.
+ *
  * 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