@am_shork/attest 0.7.0 → 0.7.2

package/dist/core/pipeline.js

@@ -109,9 +109,13 @@ export async function runCheck(root, options = {}) {
     // only one where that distinction is worth anything.
     return withLoader(options, async (loader) => {
         const { registry, issues, unreadableFiles } = await readRegistry(root, options, scan.reqsFiles, loader);
-        const plan = await parseSpecs(scan.specFiles, root);
+        const { plan, issues: unreadableSpecs } = await parseSpecs(scan.specFiles, root);
         return [
             ...issues,
+            // A spec the parser could not read is reported here rather than dropped:
+            // `check`'s contract is breadth, and a file silently contributing no
+            // scenarios reads as a file with no scenarios (ATX-65).
+            ...unreadableSpecs,
             // `check` keeps reporting on a registry that only half-loaded,
             // deliberately: its contract is breadth, and the findings from the files
             // that *did* load are all still true. What it must not do is advise work
@@ -220,7 +224,14 @@ async function unclaimedProposedSpecIssues(root, scan, options, loader) {
             for (const id of claimedIds(read.delta))
                 claimed.add(id);
     }
-    const proposed = await parseSpecs(scan.proposedSpecFiles, root);
+    const { plan: proposed, issues: unreadable } = await parseSpecs(scan.proposedSpecFiles, root);
+    issues.push(...unreadable);
+    // A file that would not parse declares no scenarios, so the loop below would
+    // find it claimed by nothing and call it unclaimed — a true sentence about a
+    // file whose real problem is that it could not be read, and a fix hint
+    // pointing at work that must not be done. Same shape as `orphan-test` after a
+    // registry fails to load (ATX-62), and refused here for the same reason.
+    const unreadableFiles = new Set(unreadable.map((i) => i.file));
     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
@@ -230,7 +241,7 @@ async function unclaimedProposedSpecIssues(root, scan, options, loader) {
     // 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))
+        if (claimedFiles.has(file) || unreadableFiles.has(file))
             continue;
         issues.push({
             level: 'ERROR',
@@ -287,7 +298,9 @@ export async function runVerify(root, options = {}) {
         registry = loaded.registry;
         issues.push(...loaded.issues);
         unreadableFiles = loaded.unreadableFiles;
-        plan = await parseSpecs(scan.specFiles, root);
+        const parsedSpecs = await parseSpecs(scan.specFiles, root);
+        plan = parsedSpecs.plan;
+        issues.push(...parsedSpecs.issues);
     }
     finally {
         await loader.close();
@@ -365,7 +378,7 @@ export async function runCover(root, options = {}) {
     const { registry, issues: loadIssues } = await readRegistry(root, options, scan.reqsFiles);
     if (hasError(loadIssues))
         return { rows: [], issues: loadIssues };
-    const plan = await parseSpecs(scan.specFiles, root);
+    const { plan, issues: unreadableSpecs } = await parseSpecs(scan.specFiles, root);
     const counts = new Map();
     for (const s of plan.scenarios) {
         counts.set(s.reqId, (counts.get(s.reqId) ?? 0) + 1);
@@ -381,7 +394,7 @@ export async function runCover(root, options = {}) {
         covered: (counts.get(reqId) ?? 0) > 0,
         scenarioCount: counts.get(reqId) ?? 0,
     }));
-    return { rows, issues: [...loadIssues, ...uncoveredIssues(registry, plan)] };
+    return { rows, issues: [...loadIssues, ...unreadableSpecs, ...uncoveredIssues(registry, plan)] };
 }
 /**
  * Markdown projection of the intent layer (design §9: `attest render`).
@@ -607,10 +620,15 @@ function claimedByDelta(proposed, delta) {
  * walking the tree again, so a caller that already scanned does not repeat it.
  */
 async function changeMergedPlan(root, delta, scan) {
-    const basePlan = await parseSpecs(scan.specFiles, root);
-    const proposed = await parseSpecs(scan.proposedSpecFiles, root);
-    const claimed = claimedByDelta(proposed, delta);
+    const base = await parseSpecs(scan.specFiles, root);
+    const proposedSpecs = await parseSpecs(scan.proposedSpecFiles, root);
+    const basePlan = base.plan;
+    const claimed = claimedByDelta(proposedSpecs.plan, delta);
     return {
+        // A spec neither parse could read blocks the gate rather than vanishing
+        // from it: an unreadable proposed spec is a scenario the gate would
+        // otherwise report as absent (ATX-65).
+        issues: [...base.issues, ...proposedSpecs.issues],
         merged: {
             scenarios: [...basePlan.scenarios, ...claimed.scenarios],
             paramRefs: [...basePlan.paramRefs, ...claimed.paramRefs],
@@ -679,10 +697,7 @@ export async function runArchiveApply(root, changeName, options = {}) {
  * 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 must act on **this** run's verdict (design §8).
  *
  * `merge` is absent exactly when there is nothing to act on: a rejected name, an
  * unreadable delta, or a registry that would not load.
@@ -725,7 +740,12 @@ async function archiveRun(root, changeName, options = {}) {
         // 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 { merged: plan, claimed } = await changeMergedPlan(root, delta, scan);
+        const { merged: plan, claimed, issues: unreadableSpecs } = await changeMergedPlan(root, delta, scan);
+        // Before the run, not after: an unreadable spec means the gate cannot see
+        // what that file declared, so letting the suite start would grade the
+        // change against a plan known to be short (ATX-65).
+        if (unreadableSpecs.length > 0)
+            return { issues: unreadableSpecs };
         // 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

package/dist/core/render.js

@@ -25,8 +25,13 @@
 //    and it is a *file* — committed, served, and read again long after the run
 //    that wrote it. See `sanitised` for why the defence sits here rather than
 //    at the terminal write.
-import { byCodeUnit } from './order.js';
+import { byCodeUnit, sortDeep } from './order.js';
 import { control } from './terminal.js';
+/** Whether a value reads as words in a sentence — a scalar, or a list of them. */
+function isFlat(value) {
+    const scalar = (v) => v === null || typeof v !== 'object';
+    return Array.isArray(value) ? value.every(scalar) : scalar(value);
+}
 const BANNER = '<!-- Generated by `attest render` — do not edit. Edit the `*.reqs.ts` registry and regenerate. -->';
 /**
  * Render the registry as a standalone Markdown document.
@@ -52,23 +57,11 @@ export function renderMarkdown(registry) {
 }
 /**
  * The registry with every string its author controls stripped of control
- * characters (ATX-58).
- *
- * **At the entry rather than at each emitter**, which is the whole of why this
- * defect existed. ATX-37 put every byte the *CLI* prints through `control`, and
- * this document is built by concatenation that never went past it — so a
- * statement carrying `ESC [2K CR` erased the reviewer's line and repainted a
- * verdict, from `attest render` with no flag at all. Sanitising here means a
- * field added to `Requirement` later is covered by having been added, instead of
- * by someone remembering; four call sites each doing it is the arrangement that
- * produced the gap in the first place.
+ * characters (ATX-58, design §9.1).
  *
- * **Over the document, not over stdout.** The obvious fix — sanitise the
- * terminal write — is wrong, and the loop that found this said so: `--out`
- * carried the payload into the file too. That file is committed, served, and
- * read later by `cat`, by `less -R`, or by a site generator, so the artifact
- * outlives the run and the run is the wrong place to defend. It also keeps
- * `--check` honest, since both sides of the comparison are built from here.
+ * This is the entry §9.1 names: sanitising here rather than at each emitter is
+ * what makes a field added to `Requirement` later covered by having been added,
+ * and what keeps the obligation over the document rather than over stdout.
  *
  * Ids are not sanitised and need not be: `RegistrySchema` holds every key to
  * `^[A-Z]+-\d+$` on **both** reader paths — the static one by construction, the
@@ -90,11 +83,25 @@ function sanitised(registry) {
     }
     return out;
 }
-/** A param value with its strings sanitised; numbers and booleans have none. */
+/**
+ * A param value with every string in it sanitised; numbers, booleans and `null`
+ * have none.
+ *
+ * Recursive, over keys as well as values. A param is a JSON value, so the
+ * author-controlled strings inside one are at arbitrary depth — and a walk that
+ * stops at the first level would leave exactly the nested ones unsanitised,
+ * which is the shape the params of a `kind -> payload` table have. §9.1 puts the
+ * defence over the whole document; a depth limit is a hole in it.
+ */
 function sanitisedValue(value) {
+    if (typeof value === 'string')
+        return control(value);
     if (Array.isArray(value))
-        return value.map((v) => (typeof v === 'string' ? control(v) : v));
-    return typeof value === 'string' ? control(value) : value;
+        return value.map(sanitisedValue);
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [control(k), sanitisedValue(v)]));
+    }
+    return value;
 }
 /**
  * Line endings are a checkout artifact, not content.
@@ -164,16 +171,11 @@ function orderingKey(id) {
  * numerically. A plain string sort puts ATX-10 between ATX-1 and ATX-2, which
  * scrambles the document as soon as a registry reaches ten requirements.
  *
- * Total, and a function of the ids alone. `renderMarkdown` feeds `--check`, so
- * an order that depends on anything else — the locale, the insertion order, the
- * engine's tie-breaking — is a freshness gate that can disagree with the run
- * that generated the file it is checking.
- *
- * A malformed id cannot reach here through any command: `RequirementIdSchema`
- * rejects it and `render` returns early on a registry that failed to load. That
- * is why this is robustness rather than a fix — the property being bought is
- * that the function is correct on its own terms instead of correct because
- * something upstream is.
+ * Total, and a function of the ids alone (design §9.1). A malformed id cannot
+ * reach here through any command — `RequirementIdSchema` rejects it and `render`
+ * returns early on a registry that failed to load — so this is the robustness
+ * §9.1 asks for rather than a fix: the function is correct on its own terms
+ * instead of correct because something upstream is.
  */
 function compareIds(a, b) {
     const [prefixA, numA] = orderingKey(a);
@@ -212,6 +214,15 @@ function section(id, req) {
     const params = Object.entries(req.params);
     if (params.length > 0) {
         out.push('', '| Param | Value |', '| --- | --- |', ...params.map(([name, value]) => `| ${code(name)} | ${cell(formatValue(value))} |`));
+        // A structured param goes below the table, not in it: a fenced block cannot
+        // live in a table cell — `cell` strips the newlines that make it a fence —
+        // and a nested object squeezed onto one line is the unreadable case, which
+        // is precisely the shape a `kind -> payload` table has.
+        for (const [name, value] of params) {
+            if (isFlat(value))
+                continue;
+            out.push('', `${code(name)}:`, '', ...jsonBlock(value));
+        }
     }
     if (req.outOfScope.length > 0) {
         out.push('', '**Out of scope**', '', ...req.outOfScope.map((s) => `- ${s}`));
@@ -238,13 +249,50 @@ function interpolate(statement, params) {
  */
 function plain(value) {
     const one = (v) => v.replace(/([*_`[\]\\])/g, '\\$1');
-    return Array.isArray(value) ? value.map((v) => one(String(v))).join(', ') : one(String(value));
+    return Array.isArray(value)
+        ? value.map((v) => one(inlineText(v))).join(', ')
+        : one(inlineText(value));
 }
-/** A param value as code, for the params table. */
+/**
+ * One param value as a run of text.
+ *
+ * `String(v)` on an object is `[object Object]`, and this function is the last
+ * place that can be stopped. It is not stopped by `non-scalar-interpolation`:
+ * `render` reads the registry and nothing else — no spec parse, so no
+ * `AttestPlan`, so no `validateStructure` — and `attest render` therefore runs
+ * happily on a registry `check` would refuse. Compact sorted JSON is not a good
+ * sentence, but it is the value, and `check` says what to do about it. A
+ * rendering that reports the shape wrongly is worse than one that reads oddly.
+ */
+function inlineText(value) {
+    return value === null || typeof value !== 'object'
+        ? String(value)
+        : JSON.stringify(sortDeep(value));
+}
+/** A param value as code, for the params table. Structured values go below it. */
 function formatValue(value) {
+    if (!isFlat(value))
+        return '_see below_';
     return Array.isArray(value)
-        ? value.map((v) => code(String(v))).join(', ')
-        : code(String(value));
+        ? value.map((v) => code(inlineText(v))).join(', ')
+        : code(inlineText(value));
+}
+/**
+ * A structured param as a fenced JSON block.
+ *
+ * Keys sorted at every depth, because `JSON.stringify` writes them in insertion
+ * order and ATX-10 holds the same registry to the same bytes. The fence is
+ * measured rather than fixed at three for the reason `code` measures its own: the
+ * value is author-controlled, and a JSON string may contain a run of backticks
+ * that closes a fence written blind.
+ */
+function jsonBlock(value) {
+    const text = JSON.stringify(sortDeep(value), null, 2);
+    let longest = 0;
+    for (const run of text.matchAll(/`+/g))
+        longest = Math.max(longest, run[0].length);
+    const fence = '`'.repeat(Math.max(3, longest + 1));
+    return [`${fence}json`, text, fence];
 }
 /**
  * Wrap text in a code span that survives backticks in the value: the fence has
@@ -268,22 +316,14 @@ function code(value) {
 /**
  * Make prose safe inside a table cell: no row-breaking pipes, no newlines.
  *
- * Each maximal whitespace run is matched once and inspected, rather than
- * matched by the old starred-`\s`, `\n`, starred-`\s` pattern (ATX-59). That
- * spelling puts a required character after a leading quantifier, so a
- * whitespace run with no newline in it was consumed, failed, and re-tried one
- * character shorter from every position in the run — quadratic, and 8.6 seconds
- * of CPU for 120,000 spaces in one statement, reachable through `render
- * --check` in CI without executing a line of the project.
- *
- * The obvious repair does not work and was measured before this one was
- * written: `[^\S\n]*\n[^\S\n]*`, which stops the class matching the newline,
- * came out *slower*. The backtracking was never about which characters the
- * class held — it was about the quantifier having something after it. `\s+`
- * has nothing after it, so there is no failure to backtrack into, and the
- * decision moves to the callback. Byte-identical to the old pattern: a
- * whitespace run containing a newline collapses to one space, and a run
- * without one is left exactly as it was.
+ * Each maximal whitespace run is matched once and inspected, rather than split
+ * across a pattern that puts a required character after a leading quantifier
+ * (ATX-59). `\s+` has nothing after it to fail against, so there is no
+ * backtracking to be quadratic in, and the newline decision moves to the
+ * callback. That is the property to preserve: any rewrite that puts a literal
+ * behind a quantifier here reintroduces it, including the narrower character
+ * class that looks like the obvious repair, which came out slower. Measured in
+ * `[0.7.0]`.
  */
 function cell(text) {
     return text

package/dist/core/runner.js

@@ -125,12 +125,10 @@ export async function runAndCollect(options = {}) {
 /**
  * Every scenario belonging to a requirement suite, at any depth beneath it.
  *
- * Direct children only was the other half of the nested-`describe` defect: a
- * scenario grouped under one is a `test` inside a `suite` inside `[reqId]`, so
- * even once the runtime stopped throwing it would have been invisible here —
- * `declared-not-run`, for a scenario that ran and passed. The static parser has
- * always recursed (`parser.ts` walks the whole subtree), and this is the seam
- * where the two readers of one plan have to agree.
+ * Recursive, not direct children only: this is the seam design §5.4 names, where
+ * the two readers of one plan have to descend the same way. A scenario grouped
+ * under a nested `describe` is a `test` inside a `suite` inside `[reqId]`, and
+ * taking direct children makes it invisible here while `parser.ts` still sees it.
  *
  * Descent stops at a nested requirement suite, so a `requirement()` written
  * inside another one keeps its own scenarios rather than donating them upward.

package/dist/core/schema.d.ts

@@ -1,19 +1,25 @@
 import { z } from 'zod';
+/** A scalar param value. `null` is included: it is how an author writes "empty". */
+declare const scalar: z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodBoolean, z.ZodNull]>;
+/** Any JSON value — what a param may be. */
+export type ParamValue = z.infer<typeof scalar> | ParamValue[] | {
+    [key: string]: ParamValue;
+};
 /** A single behavioural contract (design §2). */
 export declare const RequirementSchema: z.ZodObject<{
     statement: z.ZodEffects<z.ZodString, string, string>;
     rationale: z.ZodString;
-    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodBoolean]>, "many">]>>>;
+    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<ParamValue, z.ZodTypeDef, ParamValue>>>;
     outOfScope: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
-    params: Record<string, string | number | boolean | (string | number | boolean)[]>;
+    params: Record<string, ParamValue>;
     statement: string;
     rationale: string;
     outOfScope: string[];
 }, {
     statement: string;
     rationale: string;
-    params?: Record<string, string | number | boolean | (string | number | boolean)[]> | undefined;
+    params?: Record<string, ParamValue> | undefined;
     outOfScope?: string[] | undefined;
 }>;
 /**
@@ -32,17 +38,17 @@ export declare const RequirementIdSchema: z.ZodString;
 export declare const RegistrySchema: z.ZodRecord<z.ZodString, z.ZodObject<{
     statement: z.ZodEffects<z.ZodString, string, string>;
     rationale: z.ZodString;
-    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodBoolean]>, "many">]>>>;
+    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<ParamValue, z.ZodTypeDef, ParamValue>>>;
     outOfScope: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
-    params: Record<string, string | number | boolean | (string | number | boolean)[]>;
+    params: Record<string, ParamValue>;
     statement: string;
     rationale: string;
     outOfScope: string[];
 }, {
     statement: string;
     rationale: string;
-    params?: Record<string, string | number | boolean | (string | number | boolean)[]> | undefined;
+    params?: Record<string, ParamValue> | undefined;
     outOfScope?: string[] | undefined;
 }>>;
 /** Parsed (output) shapes — defaults applied. */
@@ -51,4 +57,5 @@ export type Registry = z.infer<typeof RegistrySchema>;
 /** Authoring (input) shapes — params / outOfScope optional. */
 export type RequirementInput = z.input<typeof RequirementSchema>;
 export type RegistryInput = z.input<typeof RegistrySchema>;
+export {};
 //# sourceMappingURL=schema.d.ts.map

package/dist/core/schema.js

@@ -2,6 +2,43 @@
 // This is the single source of truth for the shape of the intent layer; the
 // Requirement / Registry TypeScript types are inferred from it.
 import { z } from 'zod';
+/** A scalar param value. `null` is included: it is how an author writes "empty". */
+const scalar = z.union([z.number(), z.string(), z.boolean(), z.null()]);
+/**
+ * An object literal and nothing else.
+ *
+ * The guard runs on the *input*, before `z.record` copies own keys into a fresh
+ * object, because that copy is exactly what hides the case it is here for:
+ * `{ __proto__: { … } }` swaps the prototype rather than creating a key, so the
+ * parsed value is `{}` and the taint is invisible one step later. The static
+ * reader refuses that source outright (`registry-not-static`); without this the
+ * evaluating reader would call the same file green, and the two readers agreeing
+ * is the property `tests/static-registry.spec.ts` exists to hold.
+ *
+ * A class instance and a `Date` fail here too, which is the other half of what
+ * "JSON data" means — both survive `typeof v === 'object'` and neither has a
+ * meaningful rendering.
+ */
+function isPlainObject(input) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input))
+        return false;
+    // Both spellings, because they are not the same thing and the static reader
+    // refuses both: a literal `__proto__:` swaps the prototype, while the key
+    // arriving through `JSON.parse` is an own property that survives into the
+    // registry and means something else to every later reader of it.
+    if (Object.hasOwn(input, '__proto__'))
+        return false;
+    const proto = Object.getPrototypeOf(input);
+    return proto === Object.prototype || proto === null;
+}
+const jsonObject = z
+    .custom(isPlainObject)
+    .pipe(z.record(z.string(), z.lazy(() => paramValue)));
+const paramValue = z.lazy(() => z.union([scalar, z.array(paramValue), jsonObject], {
+    errorMap: () => ({
+        message: 'expected JSON data (no functions, dates, or class instances)',
+    }),
+}));
 /** A single behavioural contract (design §2). */
 export const RequirementSchema = z.object({
     statement: z
@@ -10,24 +47,23 @@ export const RequirementSchema = z.object({
         message: 'statement must contain the RFC-2119 keyword SHALL or MUST',
     }),
     rationale: z.string().min(10, 'rationale must not be empty (the intent layer has to say why)'),
-    // A param is a scalar or a homogeneous-enough list of scalars. Lists (vendor
-    // 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)], {
-            errorMap: () => ({ message: 'expected a string, number, boolean, or an array of those' }),
-        });
-    })())
-        .default({}),
+    // A param is any JSON value. Lists (vendor blacklists, id sets) are the most
+    // drift-prone constants, so keeping them out of params left the highest-risk
+    // values unguarded; the same argument runs one step further, because a
+    // kind -> payload table drifts harder than a list and was the one shape left
+    // outside. A param still has exactly one owner (the spec) read by exactly one
+    // place (the scenario), whatever its depth.
+    //
+    // What the old scalar-or-list union was really protecting was the *rendering*:
+    // `{payloadKinds}` interpolated into a statement as `[object Object]`. That is
+    // a property of the interpolation point, not of the value, so it is enforced
+    // there — `non-scalar-interpolation` in `validator.ts`, and defensively in
+    // `render.ts`, which runs without the validator. This union keeps its own
+    // message anyway, because a union's default one is the word "Invalid input",
+    // which names neither what was given nor what is accepted, and the values that
+    // now reach it are the ones JSON has no place for: a function, a Date, a class
+    // instance.
+    params: z.record(z.string(), paramValue).default({}),
     outOfScope: z.array(z.string()).default([]),
 });
 /**

package/dist/core/splice.d.ts

@@ -1,4 +1,15 @@
 import type { Registry, Requirement } from './types.js';
+/**
+ * Thrown when a value reaches the emitter that cannot be written as source
+ * without the written form meaning something else than the value.
+ *
+ * A separate class rather than a bare `Error` because `merge.ts` has to tell it
+ * from an I/O failure: this one is an invariant of *this* module, and the
+ * caller's job on catching it is to report an internal inconsistency while
+ * keeping the account of what it had already written.
+ */
+export declare class UnwritableValue extends Error {
+}
 /**
  * One registry entry, at `indent`, with no trailing comma.
  *
@@ -28,18 +39,8 @@ export declare function spliceRequirements(file: string, source: string, additio
 /**
  * `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.
+ * The second edit `--apply` makes to a file it did not write: "renamed in place"
+ * is true of the spec's location and not of its imports (design §8, ATX-48).
  * So this replaces one string literal and touches nothing else — the same
  * discipline as the splice, for the same reason.
  *

package/dist/core/splice.js

@@ -23,7 +23,7 @@ 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';
+import { byCodeUnit, sortDeep } from './order.js';
 /**
  * A TypeScript single-quoted string literal holding exactly `value`.
  *
@@ -55,13 +55,62 @@ function tsString(value) {
     }
     return `${out}'`;
 }
-/** A param key, bare when it is a plain identifier and quoted when it is not. */
+/**
+ * Thrown when a value reaches the emitter that cannot be written as source
+ * without the written form meaning something else than the value.
+ *
+ * A separate class rather than a bare `Error` because `merge.ts` has to tell it
+ * from an I/O failure: this one is an invariant of *this* module, and the
+ * caller's job on catching it is to report an internal inconsistency while
+ * keeping the account of what it had already written.
+ */
+export class UnwritableValue extends Error {
+}
+/**
+ * A param key, bare when it is a plain identifier and quoted when it is not.
+ *
+ * `__proto__` is neither, and quoting is not the repair — `{'__proto__': x}`
+ * swaps the prototype in a literal exactly as the bare form does, and the one
+ * spelling that would create an own property, `{['__proto__']: x}`, is a
+ * computed key the static reader refuses. So there is no text this function
+ * could emit whose evaluation is the value it was handed, and the only correct
+ * move is to refuse.
+ *
+ * Unreachable through any command today: `RequirementSchema` rejects a nested
+ * `__proto__` and `z.record` drops a top-level one, so `--apply` validates the
+ * delta before a value gets here. It is checked anyway because this is the one
+ * site that *writes* a registry, and the guard on the reading side
+ * (`static-registry.ts`, "refuse, so a file the evaluator also rejects stays
+ * rejected") is worth nothing if the writer can produce the file the reader
+ * exists to refuse. A defence that holds only because something upstream holds
+ * is not a defence — the same standard `compareIds` is written to.
+ */
 function keySource(key) {
+    if (key === '__proto__') {
+        throw new UnwritableValue('a param key named __proto__ cannot be written as source');
+    }
     return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : tsString(key);
 }
+/**
+ * One param value as TypeScript source.
+ *
+ * Recursive over objects as well as arrays: a param is a JSON value, and the
+ * fallback here is `String(value)` — which writes `[object Object]` into a
+ * `*.reqs.ts` that `--apply` then merges and commits. Key order is the caller's
+ * job: `requirementSource` runs the whole params record through `sortDeep`, so
+ * emitting in iteration order here *is* code-unit order at every depth.
+ */
 function paramSource(value) {
     if (Array.isArray(value))
         return `[${value.map((v) => paramSource(v)).join(', ')}]`;
+    if (value !== null && typeof value === 'object') {
+        const body = Object.entries(value)
+            .map(([k, v]) => `${keySource(k)}: ${paramSource(v)}`)
+            .join(', ');
+        return body === '' ? '{}' : `{ ${body} }`;
+    }
+    // `String` is right for the rest and only for the rest: number, boolean, and
+    // `null` — whose spelling is `null`, which is also the literal that reads back.
     return typeof value === 'string' ? tsString(value) : String(value);
 }
 /**
@@ -85,10 +134,12 @@ export function requirementSource(id, req, indent) {
         `${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));
+    // Code-unit key order at every depth, so one delta applied twice writes the
+    // same bytes — the property `--apply`'s re-runnability rests on, and the
+    // reason `apply.ts` canonicalises through the same `sortDeep` for
+    // `add-conflict`. Depth matters because a param is a JSON value: nested keys
+    // are as much of the emitted text as the outer ones.
+    const params = Object.entries(sortDeep(req.params));
     if (params.length > 0) {
         const body = params.map(([k, v]) => `${keySource(k)}: ${paramSource(v)}`).join(', ');
         lines.push(`${inner}params: { ${body} },`);
@@ -125,18 +176,8 @@ export function spliceRequirements(file, source, additions) {
 /**
  * `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.
+ * The second edit `--apply` makes to a file it did not write: "renamed in place"
+ * is true of the spec's location and not of its imports (design §8, ATX-48).
  * So this replaces one string literal and touches nothing else — the same
  * discipline as the splice, for the same reason.
  *

package/dist/core/static-registry.js

@@ -251,6 +251,12 @@ function literalValue(node) {
         return true;
     if (expr.kind === ts.SyntaxKind.FalseKeyword)
         return false;
+    // `null` is a keyword, not a literal node, so it falls off the end of this
+    // function unless it is named here — and falling off means `registry-not-static`
+    // for the whole file, not a rejected param. The schema accepts `null`; a reader
+    // that does not is the two of them disagreeing about what a registry is.
+    if (expr.kind === ts.SyntaxKind.NullKeyword)
+        return null;
     if (ts.isPrefixUnaryExpression(expr)) {
         const operand = unwrap(expr.operand);
         if (ts.isNumericLiteral(operand)) {