@am_shork/attest 0.6.0 → 0.7.1

package/dist/core/order.d.ts

@@ -1,3 +1,20 @@
 /** Compare by UTF-16 code unit — the same order as a bare `Array#sort()`. */
 export declare function byCodeUnit(a: string, b: string): number;
+/**
+ * A JSON value with every object's keys in code-unit order, at every depth.
+ *
+ * `JSON.stringify` writes object keys in insertion order, which is *how the
+ * source happened to be written* — the thing this module exists to keep out of
+ * anything compared or committed. Two callers need the same guarantee for the
+ * same reason, one depth apart:
+ *
+ * - `apply.ts` canonicalises a requirement to decide `add-conflict`, so an
+ *   identical copy written with its keys in another order must not read as a
+ *   conflict with itself.
+ * - `render.ts` emits a structured param as JSON, and ATX-10 holds the same
+ *   registry to the same bytes.
+ *
+ * Arrays keep their order: an array is data whose order is part of the value.
+ */
+export declare function sortDeep<T>(value: T): T;
 //# sourceMappingURL=order.d.ts.map

package/dist/core/order.js

@@ -10,4 +10,29 @@
 export function byCodeUnit(a, b) {
     return a < b ? -1 : a > b ? 1 : 0;
 }
+/**
+ * A JSON value with every object's keys in code-unit order, at every depth.
+ *
+ * `JSON.stringify` writes object keys in insertion order, which is *how the
+ * source happened to be written* — the thing this module exists to keep out of
+ * anything compared or committed. Two callers need the same guarantee for the
+ * same reason, one depth apart:
+ *
+ * - `apply.ts` canonicalises a requirement to decide `add-conflict`, so an
+ *   identical copy written with its keys in another order must not read as a
+ *   conflict with itself.
+ * - `render.ts` emits a structured param as JSON, and ATX-10 holds the same
+ *   registry to the same bytes.
+ *
+ * Arrays keep their order: an array is data whose order is part of the value.
+ */
+export function sortDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortDeep);
+    // `typeof null === 'object'`, and a null param is a value like any other.
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const entries = Object.entries(value).sort(([a], [b]) => byCodeUnit(a, b));
+    return Object.fromEntries(entries.map(([k, v]) => [k, sortDeep(v)]));
+}
 //# sourceMappingURL=order.js.map

package/dist/core/pipeline.js

@@ -1,14 +1,12 @@
 // 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, 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, claimedIds } from './apply.js';
 import { readDeltaSource } from './static-registry.js';
 import { statusRows, statusCounts } from './status.js';
-import { evaluateGate, declaredNotRunIssues } from './gate.js';
+import { evaluateGate, notRunIssues } from './gate.js';
 import { renderMarkdown, staleIssue } from './render.js';
 import { mergeRedRecord, readRedRecord, redRecordPath, serialiseRedRecord, } from './red-record.js';
 import { DEFAULT_TARGET, resolveTargets } from './targets.js';
@@ -19,13 +17,52 @@ import { mkdir, readFile } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { relativePath } from './paths.js';
 import { hasError } from './types.js';
+// The runner half of the engine, reached only when a command actually needs it.
+//
+// These two are deliberately not top-level imports. `cli/index.ts` imports this
+// module whole, so a static import here resolves and evaluates `vite`,
+// `vitest/node` and `vitest/config` before `commander` has parsed an argument —
+// measured at ~900 ms, paid by `check`, `cover`, `render`, `status` without
+// `--eval` and `init`, none of which can start a run. §11's cost model is a
+// short-lived process where cold start is the whole bill, so a fixed toll on
+// every invocation outweighs anything scaling with requirement count.
+//
+// This is *not* the core/adapter package split §11 defers, and does not
+// substitute for it: `pipeline.ts` still holds both halves, so the reachability
+// `tests/import-boundary.spec.ts` cannot assert is still unassertable. What
+// moves is when the cost is paid. The specifiers stay relative and the gate
+// reads `import(...)` from the AST alongside static imports, so the boundary is
+// checked exactly as before — that is the one property this change could have
+// silently dropped, and the reason that test looks for dynamic imports at all.
+/** {@link import('./loader.js').createLoader}, resolved on first use. */
+async function createLoader() {
+    const { createLoader: create } = await import('./loader.js');
+    return create();
+}
+/**
+ * {@link import('./runner.js').runAndCollect}, resolved on first use.
+ *
+ * `BASE_EXCLUDE` gets no such wrapper: it has one caller, which is inside the
+ * function that starts the run it belongs to, so it is destructured there
+ * alongside nothing.
+ */
+async function runAndCollect(options = {}) {
+    const { runAndCollect: run } = await import('./runner.js');
+    return run(options);
+}
 /**
  * Read every registry under root with the reader `options` asks for, and close
  * whatever that reader needed. Static reading starts no Vite server at all.
+ *
+ * `borrowed` is a loader the caller is already holding open for this command.
+ * See `withLoader` for why a command with more than one thing to evaluate owns
+ * one rather than letting each read start its own.
  */
-async function readRegistry(root, options, files) {
+async function readRegistry(root, options, files, borrowed) {
     if (!options.evaluate)
         return loadRegistry(root, staticReader(), files);
+    if (borrowed)
+        return loadRegistry(root, evalReader(borrowed), files);
     const loader = await createLoader();
     try {
         return await loadRegistry(root, evalReader(loader), files);
@@ -34,22 +71,59 @@ async function readRegistry(root, options, files) {
         await loader.close();
     }
 }
+/**
+ * Run `fn` with one loader for the whole command, or with none when nothing is
+ * to be evaluated.
+ *
+ * A loader is a Vite dev server: starting one is the expensive thing on this
+ * path, and `check --eval` used to start **one per change** — `readDelta`
+ * created and closed its own on every iteration of the loop over
+ * `listChangeNames`, on top of the one `readRegistry` had already opened and
+ * closed for the same command. So the cost was 1 + N servers for a command that
+ * needs one. Ownership sits here rather than in either reader because neither
+ * of them knows how many times it is about to be called.
+ *
+ * Static commands pass `undefined` all the way down and start nothing at all,
+ * which is the property `check` without `--eval` is documented on (design §5.1)
+ * and the reason this returns an optional rather than always creating one.
+ */
+async function withLoader(options, fn) {
+    if (!options.evaluate)
+        return fn(undefined);
+    const loader = await createLoader();
+    try {
+        return await fn(loader);
+    }
+    finally {
+        await loader.close();
+    }
+}
 /** 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);
-    return [
-        ...issues,
-        ...validateStructure(registry, plan),
-        ...detectPotentialDrift(registry, plan, plan.paramRefs),
-        ...(await unclaimedProposedSpecIssues(root, scan, options)),
-        ...(await changeDirSpecIssues(root)),
-        ...proposedNameTakenIssues(root, scan),
-    ];
+    // One loader for the command, not one per thing evaluated: this is the only
+    // command that reads both the registry and every change's delta, so it is the
+    // 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);
+        return [
+            ...issues,
+            // `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
+            // that the load failure makes wrong — see `orphan-test` in
+            // `validateStructure`.
+            ...validateStructure(registry, plan, unreadableFiles.length > 0),
+            ...detectPotentialDrift(registry, plan, plan.paramRefs),
+            ...(await unclaimedProposedSpecIssues(root, scan, options, loader)),
+            ...(await changeDirSpecIssues(root)),
+            ...proposedNameTakenIssues(root, scan),
+        ];
+    });
 }
 /**
  * A proposed spec whose merged name is already taken (design §7).
@@ -131,13 +205,15 @@ async function changeDirSpecIssues(root) {
  * — a change delta is intent, and the commands that only report read it from
  * source (design §5.1).
  */
-async function unclaimedProposedSpecIssues(root, scan, options) {
+async function unclaimedProposedSpecIssues(root, scan, options, loader) {
     if (scan.proposedSpecFiles.length === 0)
         return [];
     const claimed = new Set();
     const issues = [];
+    // The loop `loader` exists for: under `--eval` this used to start and stop a
+    // Vite dev server per change.
     for (const name of await listChangeNames(root)) {
-        const read = await readDelta(root, name, options);
+        const read = await readDelta(root, name, options, loader);
         if ('issue' in read)
             issues.push(read.issue);
         else
@@ -204,17 +280,21 @@ export async function runVerify(root, options = {}) {
     const loader = await createLoader();
     let registry;
     let plan;
+    let unreadableFiles;
     const issues = [];
     try {
         const loaded = await loadRegistry(root, evalReader(loader), scan.reqsFiles);
         registry = loaded.registry;
         issues.push(...loaded.issues);
+        unreadableFiles = loaded.unreadableFiles;
         plan = await parseSpecs(scan.specFiles, root);
     }
     finally {
         await loader.close();
     }
-    issues.push(...validateStructure(registry, plan));
+    // Same as `check`: everything the loaded half supports is still reported, and
+    // only the advice that a load failure would make wrong is withdrawn.
+    issues.push(...validateStructure(registry, plan, unreadableFiles.length > 0));
     issues.push(...detectPotentialDrift(registry, plan, plan.paramRefs));
     const attesting = attestingFiles(plan);
     const counts = {
@@ -257,7 +337,13 @@ export async function runVerify(root, options = {}) {
     if (!run.passed) {
         issues.push({ level: 'ERROR', code: 'tests-red', message: 'Some tests are failing.' });
     }
-    issues.push(...declaredNotRunIssues(plan, run));
+    // The load failures first, then the absences they caused — by the same
+    // function the gate calls, which is the point. `verify` used to ask only for
+    // the absences, so an ordinary broken import surfaced as a `declared-not-run`
+    // per scenario blaming a skip, with nothing anywhere naming the file that did
+    // not load. No more specific diagnosis to pass: `added-id-unmerged` is a
+    // statement about a change's delta, and `verify` has no change.
+    issues.push(...notRunIssues(plan, run));
     return { issues, passed: run.passed, ok: run.passed && !hasError(issues), counts };
 }
 /**
@@ -284,8 +370,12 @@ export async function runCover(root, options = {}) {
     for (const s of plan.scenarios) {
         counts.set(s.reqId, (counts.get(s.reqId) ?? 0) + 1);
     }
+    // `byCodeUnit`, not a bare `.sort()`. The two give an identical result on ids
+    // that match the grammar, and that is exactly why this is worth spelling:
+    // `order.ts` exists so ordering has one spelling across the engine, which is
+    // a property that survives an edit — an identical result is not.
     const rows = Object.keys(registry)
-        .sort()
+        .sort(byCodeUnit)
         .map((reqId) => ({
         reqId,
         covered: (counts.get(reqId) ?? 0) > 0,
@@ -426,10 +516,14 @@ function changeNotFoundIssue(root, deltaPath, changeName, err) {
  * under review. `archive` evaluates unconditionally because it runs the suite
  * anyway, so declining to evaluate one more module would buy it nothing.
  */
-async function readDelta(root, changeName, options) {
+async function readDelta(root, changeName, options, borrowed) {
     const deltaPath = changeDeltaPath(root, changeName);
     if (options.evaluate) {
-        const loader = await createLoader();
+        // Borrow the caller's loader when it has one, own one otherwise. The
+        // difference matters only to the caller that reads several deltas — see
+        // `withLoader` — and a lone reader should not have to build scaffolding to
+        // ask for one delta.
+        const loader = borrowed ?? (await createLoader());
         try {
             const mod = await loader.load(deltaPath);
             if (!mod.default || typeof mod.default !== 'object') {
@@ -443,7 +537,10 @@ async function readDelta(root, changeName, options) {
             return { issue: changeNotFoundIssue(root, deltaPath, changeName, err) };
         }
         finally {
-            await loader.close();
+            // Only what this call created. Closing a borrowed loader would take it
+            // out from under the caller's next iteration.
+            if (!borrowed)
+                await loader.close();
         }
     }
     let source;
@@ -512,10 +609,20 @@ function claimedByDelta(proposed, delta) {
 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);
+    const claimed = claimedByDelta(proposed, delta);
     return {
-        scenarios: [...basePlan.scenarios, ...changePlan.scenarios],
-        paramRefs: [...basePlan.paramRefs, ...changePlan.paramRefs],
+        merged: {
+            scenarios: [...basePlan.scenarios, ...claimed.scenarios],
+            paramRefs: [...basePlan.paramRefs, ...claimed.paramRefs],
+        },
+        // Returned rather than recomputed by the caller that needs it. `--apply`
+        // renames exactly the proposed specs this change claims, and deriving that
+        // set a second time — a second `parseSpecs` and a second `claimedByDelta`
+        // over the same files — is agreement by transcription: the two answers
+        // match because the same two functions ran twice, which is the thing this
+        // codebase extracts `declaredNotRunIssues` and `uncoveredIssues` to stop
+        // relying on. One parse, one split, one answer.
+        claimed,
     };
 }
 /** Per-change progress (design §9: `attest status <change>`). */
@@ -537,7 +644,7 @@ export async function runStatus(root, changeName, options = {}) {
     if ('issue' in read)
         return nothing([read.issue]);
     const scan = await scanProject(root);
-    const plan = await changeMergedPlan(root, read.delta, scan);
+    const { merged: 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: [] };
@@ -557,7 +664,10 @@ export async function runArchive(root, changeName, options = {}) {
  */
 export async function runArchiveApply(root, changeName, options = {}) {
     const { issues, merge } = await archiveRun(root, changeName, options);
-    if (issues.some((i) => i.level === 'ERROR') || !merge)
+    // One predicate for the verdict, everywhere (ATX-60): the gate's WARNINGs
+    // survive `--apply` by design, so `some(level === 'ERROR')` spelled here by
+    // hand was a second definition of failure sitting next to the one that counts.
+    if (hasError(issues) || !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
@@ -569,10 +679,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.
@@ -589,7 +696,7 @@ async function archiveRun(root, changeName, options = {}) {
     const loader = await createLoader();
     try {
         const { registry: base, issues, prefixOwners } = await loadRegistry(root, evalReader(loader), scan.reqsFiles);
-        if (issues.some((i) => i.level === 'ERROR'))
+        if (hasError(issues))
             return { issues };
         const deltaPath = changeDeltaPath(root, changeName);
         let delta;
@@ -615,13 +722,14 @@ 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 plan = await changeMergedPlan(root, delta, scan);
+        const { merged: plan, claimed } = 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 { BASE_EXCLUDE } = await import('./runner.js');
         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
@@ -668,8 +776,9 @@ async function archiveRun(root, changeName, options = {}) {
                 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)),
+                // not this change's to move. `claimed` is the half of the plan the gate
+                // above ran, handed back by the function that built it.
+                claimedSpecs: claimedSpecsOf(root, claimed),
                 mergedSpecs: scan.specFiles,
             },
         };

package/dist/core/render.js

@@ -6,7 +6,7 @@
 // back, so the direction OpenSpec's pure-Markdown model went (Markdown as
 // truth, and the free-form drift that comes with it) stays closed.
 //
-// Three properties this file must keep:
+// Four properties this file must keep:
 //  - **Intent only.** The document says what the system promises, never what is
 //    proven or green: coverage and results are verdicts, and verdicts belong to
 //    `cover` / `verify`, which recompute them on demand. Putting them here also
@@ -20,7 +20,18 @@
 //  - **Params interpolated into the statement.** The source says
 //    "{idleTimeoutMin} minutes"; a human reader wants "30 minutes". This is the
 //    one thing the projection gives that reading the source does not.
-import { byCodeUnit } from './order.js';
+//  - **None of the registry's control characters survive into it.** The
+//    document is quoted prose from a repository that may not be the reader's,
+//    and it is a *file* — committed, served, and read again long after the run
+//    that wrote it. See `sanitised` for why the defence sits here rather than
+//    at the terminal write.
+import { byCodeUnit, 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.
@@ -31,18 +42,67 @@ const BANNER = '<!-- Generated by `attest render` — do not edit. Edit the `*.r
  * worse than no gate.
  */
 export function renderMarkdown(registry) {
-    const ids = Object.keys(registry).sort(compareIds);
+    const clean = sanitised(registry);
+    const ids = Object.keys(clean).sort(compareIds);
     const out = [BANNER, '', '# Requirements', ''];
     if (ids.length === 0) {
         out.push('_No requirements are defined yet._', '');
         return out.join('\n');
     }
-    out.push(...overviewTable(registry, ids), '');
+    out.push(...overviewTable(clean, ids), '');
     for (const id of ids) {
-        out.push(...section(id, registry[id]), '');
+        out.push(...section(id, clean[id]), '');
     }
     return out.join('\n');
 }
+/**
+ * The registry with every string its author controls stripped of control
+ * characters (ATX-58, design §9.1).
+ *
+ * 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
+ * evaluating one since ATX-38 — so no id can carry a control character to begin
+ * with. The container is still built without a prototype, for the reason
+ * `red-record.ts` builds its own that way: that grammar is held somewhere else,
+ * and a defence that reads an inherited key when the other one lapses is not a
+ * defence. `Object.entries` and the sort below see own keys either way.
+ */
+function sanitised(registry) {
+    const out = Object.create(null);
+    for (const [id, req] of Object.entries(registry)) {
+        out[id] = {
+            statement: control(req.statement),
+            rationale: control(req.rationale),
+            params: Object.fromEntries(Object.entries(req.params).map(([k, v]) => [control(k), sanitisedValue(v)])),
+            outOfScope: req.outOfScope.map(control),
+        };
+    }
+    return out;
+}
+/**
+ * A param value with 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(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.
  *
@@ -85,23 +145,51 @@ export function staleIssue(target, current, fresh) {
         message: `${why} Regenerate it with: ${target.command}`,
     };
 }
+/**
+ * `AUTH-3` as its two ordering keys. An id this reader cannot take apart is its
+ * own prefix with no number, which is the reading `locate.ts`'s `idPrefix`
+ * gives — the two used to disagree, and one of them was wrong.
+ *
+ * `lastIndexOf('-')` with no guard was the old spelling, and on an id with no
+ * dash it silently dropped the last character (`AUTH` → prefix `AUT`) and
+ * produced `NaN` for the number. A comparator that answers `NaN` is not merely
+ * imprecise, it is **non-transitive**: measured on
+ * `['AUTH-3','AUTH-abc','AUTH-2']` the result was `AUTH-3, AUTH-abc, AUTH-2`,
+ * which is not a sorted permutation of anything. Both cases are handled here so
+ * the comparator below is total by construction rather than by the input
+ * happening to be well-formed.
+ */
+function orderingKey(id) {
+    const at = id.indexOf('-');
+    const tail = at === -1 ? '' : id.slice(at + 1);
+    if (at === -1 || !/^\d+$/.test(tail))
+        return [id, -1];
+    return [id.slice(0, at), Number(tail)];
+}
 /**
  * Order ids the way a reader expects: prefix alphabetically, then the number
  * numerically. A plain string sort puts ATX-10 between ATX-1 and ATX-2, which
  * scrambles the document as soon as a registry reaches ten requirements.
+ *
+ * Total, and a function of the ids alone (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 split = (id) => {
-        const at = id.lastIndexOf('-');
-        return [id.slice(0, at), Number(id.slice(at + 1))];
-    };
-    const [prefixA, numA] = split(a);
-    const [prefixB, numB] = split(b);
+    const [prefixA, numA] = orderingKey(a);
+    const [prefixB, numB] = orderingKey(b);
     // byCodeUnit, not localeCompare: the ordering has to be identical on every
     // machine, or `--check` would flap with the runner's locale.
     if (prefixA !== prefixB)
         return byCodeUnit(prefixA, prefixB);
-    return numA - numB;
+    if (numA !== numB)
+        return numA - numB;
+    // Same prefix and same number is only reachable for ids this reader could not
+    // take apart. Falling back to the whole id keeps the order total rather than
+    // leaving it to the sort's stability, which is a property of the engine.
+    return byCodeUnit(a, b);
 }
 /**
  * An index of the whole registry: id + the promise itself. Deliberately carries
@@ -126,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}`));
@@ -152,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));
+}
+/**
+ * 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. */
+/** 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
@@ -166,14 +300,35 @@ function formatValue(value) {
  * at either end needs padding spaces.
  */
 function code(value) {
-    const longest = Math.max(0, ...[...value.matchAll(/`+/g)].map((m) => m[0].length));
+    // Accumulated, never `Math.max(0, ...runs)` (ATX-59). The spread puts one
+    // argument on the stack per backtick run, so a param holding a few hundred
+    // thousand of them exhausted it — `RangeError` out of `attest render` under
+    // the static reader, with the stack naming this function. Not backtracking,
+    // and found only by sweeping for more of it: same reachable path, same
+    // registry-chooses-the-cost shape, different mechanism.
+    let longest = 0;
+    for (const run of value.matchAll(/`+/g))
+        longest = Math.max(longest, run[0].length);
     const fence = '`'.repeat(longest + 1);
     const pad = value.startsWith('`') || value.endsWith('`') ? ' ' : '';
     return `${fence}${pad}${value}${pad}${fence}`;
 }
-/** Make prose safe inside a table cell: no row-breaking pipes, no newlines. */
+/**
+ * Make prose safe inside a table cell: no row-breaking pipes, no newlines.
+ *
+ * Each maximal whitespace run is matched once and inspected, rather than 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.replace(/\s*\n\s*/g, ' ').replace(/\|/g, '\\|');
+    return text
+        .replace(/\s+/g, (ws) => (ws.includes('\n') ? ' ' : ws))
+        .replace(/\|/g, '\\|');
 }
 /** GitHub/GitLab slug for a `## AUTH-3` heading. */
 function anchor(id) {

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

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