@am_shork/attest 0.6.0 → 0.7.1

package/dist/core/req-suite.js

@@ -0,0 +1,27 @@
+// The one spelling of the suite name that carries a requirement id.
+//
+// `requirement()` writes it, `runner.ts` reads it back out of the serialized
+// task tree, and the runtime's own guard reads it to find the requirement that
+// owns a scenario. That is three readers of one encoding, across a process
+// boundary — the task tree is the only channel that crosses it (design §5.4) —
+// and two spellings of one encoding are two encodings the moment either is
+// edited.
+//
+// Deliberately free of any `vitest` import, so both sides of the engine ↔
+// runner boundary (`tests/import-boundary.spec.ts`) can depend on it.
+/** How `requirement(id)` names its describe block. */
+export function requirementSuiteName(id) {
+    return `[${id}]`;
+}
+/**
+ * `.+` rather than something narrower: a delta may propose an id the registry's
+ * grammar would refuse, and this has to round-trip whatever `requirement()`
+ * wrote so the two readers agree about it (the call `readDeltaSource` makes for
+ * the same reason).
+ */
+const REQ_SUITE = /^\[(.+)\]$/;
+/** The requirement id a suite name carries, or `undefined` if it carries none. */
+export function requirementIdOf(suiteName) {
+    return REQ_SUITE.exec(suiteName)?.[1];
+}
+//# sourceMappingURL=req-suite.js.map

package/dist/core/runner.js

@@ -5,9 +5,8 @@
 import { startVitest } from 'vitest/node';
 import { configDefaults } from 'vitest/config';
 import { relativePath } from './paths.js';
+import { requirementIdOf } from './req-suite.js';
 import { byCodeUnit } from './order.js';
-/** requirement() names each describe block `[reqId]`; recover the id from that. */
-const REQ_SUITE = /^\[(.+)\]$/;
 /**
  * Vitest's own default exclusions, which every Attest run keeps on top of
  * whatever else it excludes.
@@ -73,18 +72,15 @@ export async function runAndCollect(options = {}) {
         // Reconstruct coverage from the task tree (not an in-process singleton).
         const walk = (task) => {
             if (task.type === 'suite') {
-                const m = REQ_SUITE.exec(task.name);
-                if (m) {
-                    const id = m[1];
+                const id = requirementIdOf(task.name);
+                if (id !== undefined) {
                     const set = runtimeCoverage.get(id) ?? new Set();
                     const byName = outcomes.get(id) ?? new Map();
-                    for (const c of task.tasks ?? []) {
+                    for (const c of scenariosUnder(task)) {
                         // A scenario counts as covered only if it actually executed —
                         // skipped/todo scenarios have no run result (enables §8's
                         // declared-not-run check). The same test decides whether there is
                         // an outcome to record: a skip is not a red (design §6).
-                        if (c.type !== 'test')
-                            continue;
                         const outcome = executedOutcome(c);
                         if (!outcome)
                             continue;
@@ -126,6 +122,26 @@ export async function runAndCollect(options = {}) {
         await vitest.close();
     }
 }
+/**
+ * Every scenario belonging to a requirement suite, at any depth beneath it.
+ *
+ * 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.
+ */
+function* scenariosUnder(suite) {
+    for (const child of suite.tasks ?? []) {
+        if (child.type === 'test')
+            yield child;
+        else if (child.type === 'suite' && requirementIdOf(child.name) === undefined) {
+            yield* scenariosUnder(child);
+        }
+    }
+}
 /**
  * Did this file fail before any of its tests could exist?
  *

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/skill.js

@@ -34,6 +34,9 @@
 // workflow to an agent that trusts it. The backstop is that every mistake it
 // could cause is a diagnostic with a fix hint — a registry written the old way
 // is `registry-not-static`, and the agent corrects itself from the report.
+// It has happened once, so: read this file when a release adds a diagnostic.
+// Nothing gates that — `ATX-57` catches a code the engine cannot emit, never one
+// it can.
 /**
  * The one sentence that decides whether the workflow is ever loaded.
  *
@@ -283,9 +286,10 @@ once. Branch on \`issues[].code\`, never on \`message\`:
 | \`tests-red\` | a test is failing — the normal state until you are finished |
 | \`never-red\` | an added requirement's scenario has no recorded failing run |
 | \`uncovered-requirement\` | a requirement in the applied registry has no scenario |
-| \`declared-not-run\` | a scenario was declared but never executed (\`skip\` / \`only\`?) |
+| \`declared-not-run\` | a scenario was declared but never executed (\`skip\` / \`only\`?) — withdrawn when one of the two rows below already explains its file, so it never stands in for a load failure |
+| \`spec-load-failed\` | a spec file could not be imported, so nothing in it ran. The run output carries the import error itself; this names which file it stopped |
 | \`proposed-spec-unclaimed\` | a \`*.proposed.spec.ts\` no change's delta claims |
-| \`added-id-unmerged\` | a spec failed to load, and this change adds an id the registry on disk lacks |
+| \`added-id-unmerged\` | the same load failure, when this change also adds an id the registry on disk lacks. The specific case, and the only one reported for that file |
 | \`unbound-param\` | a \`{placeholder}\` has no matching \`params\` key |
 | \`registry-not-static\` | a registry file is not a literal the engine can read |
 | \`add-conflict\` | the delta adds an id that already exists with different content |

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)) {

package/dist/core/status.js

@@ -29,10 +29,23 @@ import { hasRecordedRed, recordedOutcome } from './red-record.js';
  * author reads them in.
  */
 export function statusRows(addedIds, plan, firstRun) {
+    // Index the scenarios once, the way `validator.ts`'s `detectPotentialDrift`
+    // does and for the reason recorded there: filtering the whole plan per
+    // requirement is O(requirements x scenarios), and the plan here is the
+    // *merged* one, so the inner term is the whole repository's scenario count.
+    //
+    // Insertion order is plan order, which is file then line, so the scenarios a
+    // row carries stay in the order their author reads them.
+    const byReqId = new Map();
+    for (const s of plan.scenarios) {
+        const group = byReqId.get(s.reqId);
+        if (group)
+            group.push(s);
+        else
+            byReqId.set(s.reqId, [s]);
+    }
     return [...addedIds].sort(byCodeUnit).map((reqId) => {
-        const scenarios = plan.scenarios
-            .filter((s) => s.reqId === reqId)
-            .map((s) => ({
+        const scenarios = (byReqId.get(reqId) ?? []).map((s) => ({
             name: s.name,
             file: s.file,
             line: s.line,

package/dist/core/terminal.d.ts

@@ -16,9 +16,18 @@ export declare function inline(text: string): string;
 /**
  * Every C0 control except the newline, plus DEL and the C1 range, as a space.
  *
- * A space rather than deletion: removing the byte would silently splice
- * `atte` + `st` into a word that was never in the file, and a diagnostic that
- * quietly rewrites what it quotes is its own kind of wrong.
+ * A space rather than deletion, and the newline exempt by not being in the
+ * class: both are design §9.1, stated there because they hold for every artifact
+ * Attest writes rather than only for this one.
+ *
+ * The one thing §9.1 does not reach: surrogates `D800`–`DFFF` fall outside every
+ * range below, so a pair is never touched and never split — the case that makes
+ * a per-code-point rewrite look necessary when it is not.
+ *
+ * Written out rather than computed per character so the scan allocates nothing
+ * when nothing matches, which is what every real registry is; `render` calls
+ * this once per statement, rationale, param key, param value and out-of-scope
+ * entry, on the `render --check` path ATX-59 came off. Measured in `[0.7.0]`.
  */
 export declare function control(text: string): string;
 //# sourceMappingURL=terminal.d.ts.map

package/dist/core/terminal.js

@@ -19,8 +19,6 @@
 // loader has to sanitise Vite's log output for the same reason and cannot
 // import from a layer above it. Two copies of this decision is how the crash
 // path came to be missed once already.
-/** The one control character that survives: see `block`. */
-const NEWLINE = 0x0a;
 /** How far a message is indented under its header line. */
 export const INDENT = '    ';
 /**
@@ -43,17 +41,21 @@ export function inline(text) {
 /**
  * Every C0 control except the newline, plus DEL and the C1 range, as a space.
  *
- * A space rather than deletion: removing the byte would silently splice
- * `atte` + `st` into a word that was never in the file, and a diagnostic that
- * quietly rewrites what it quotes is its own kind of wrong.
+ * A space rather than deletion, and the newline exempt by not being in the
+ * class: both are design §9.1, stated there because they hold for every artifact
+ * Attest writes rather than only for this one.
+ *
+ * The one thing §9.1 does not reach: surrogates `D800`–`DFFF` fall outside every
+ * range below, so a pair is never touched and never split — the case that makes
+ * a per-code-point rewrite look necessary when it is not.
+ *
+ * Written out rather than computed per character so the scan allocates nothing
+ * when nothing matches, which is what every real registry is; `render` calls
+ * this once per statement, rationale, param key, param value and out-of-scope
+ * entry, on the `render --check` path ATX-59 came off. Measured in `[0.7.0]`.
  */
 export function control(text) {
-    return [...text]
-        .map((ch) => {
-        const c = ch.codePointAt(0);
-        const isControl = (c < 0x20 && c !== NEWLINE) || (c >= 0x7f && c <= 0x9f);
-        return isControl ? ' ' : ch;
-    })
-        .join('');
+    // eslint-disable-next-line no-control-regex -- matching control characters is the whole function.
+    return text.replace(/[\x00-\x09\x0b-\x1f\x7f-\x9f]/g, ' ');
 }
 //# sourceMappingURL=terminal.js.map

package/dist/core/types.d.ts

@@ -1,4 +1,4 @@
-export type { Requirement, Registry } from './schema.js';
+export type { Requirement, Registry, ParamValue } from './schema.js';
 export type { IssueCode } from './docs.js';
 import type { IssueCode } from './docs.js';
 /** A scenario extracted statically from a spec file (design §5.2). */

package/dist/core/validator.d.ts

@@ -15,11 +15,16 @@ export declare function uncoveredIssues(registry: Registry, plan: AttestPlan): I
  * - orphan-test: a scenario covers an unknown requirement id
  * - uncovered-requirement: a requirement has no scenario
  * - unbound-param: a statement placeholder has no matching param
+ * - non-scalar-interpolation: a statement placeholder names a structured param
  *
  * and one WARNING:
  * - rationale-placeholder: a `{name}` in a rationale, which is never interpolated
+ *
+ * `registryIncomplete` says that at least one `*.reqs.ts` failed to load, so
+ * `registry` is known to be missing whatever was in it. It changes no verdict —
+ * only what `orphan-test` advises, for the reason below.
  */
-export declare function validateStructure(registry: Registry, plan: AttestPlan): Issue[];
+export declare function validateStructure(registry: Registry, plan: AttestPlan, registryIncomplete?: boolean): Issue[];
 /**
  * Weak anti-drift heuristic (design §6, mechanism 3). Evaluated per requirement,
  * not per scenario: a requirement that owns params is quiet as soon as *any* one

package/dist/core/validator.js

@@ -30,14 +30,36 @@ export function uncoveredIssues(registry, plan) {
  * - orphan-test: a scenario covers an unknown requirement id
  * - uncovered-requirement: a requirement has no scenario
  * - unbound-param: a statement placeholder has no matching param
+ * - non-scalar-interpolation: a statement placeholder names a structured param
  *
  * and one WARNING:
  * - rationale-placeholder: a `{name}` in a rationale, which is never interpolated
+ *
+ * `registryIncomplete` says that at least one `*.reqs.ts` failed to load, so
+ * `registry` is known to be missing whatever was in it. It changes no verdict —
+ * only what `orphan-test` advises, for the reason below.
  */
-export function validateStructure(registry, plan) {
+export function validateStructure(registry, plan, registryIncomplete = false) {
     const issues = [];
     const knownIds = new Set(Object.keys(registry));
     // orphan-test: covers a requirement that does not exist.
+    //
+    // "Add it to the registry, or fix the id" is the right advice for an id that
+    // is genuinely absent, and **wrong** for one already sitting in a registry
+    // file that failed to load: the id is there, the fix is the load error, and
+    // following the hint would add a duplicate. That case is not rare when it
+    // happens — one unreadable `*.reqs.ts` orphans every scenario of every
+    // requirement it declared, so the wrong advice is also the loudest thing in
+    // the report.
+    //
+    // Which of the two this is cannot be decided here: the ids of a file that
+    // never parsed are exactly what is unavailable. So the finding stands and the
+    // *advice* names the uncertainty and the order to work in — a report that is
+    // quieter about problems it can still see would be the worse trade for a
+    // command whose contract is breadth.
+    const orphanFix = (id) => registryIncomplete
+        ? `A registry file failed to load, so ids it declares are missing here — fix that first, and add "${id}" only if it is still unknown afterwards.`
+        : `Add it to the registry, or fix the id.`;
     for (const s of plan.scenarios) {
         if (!knownIds.has(s.reqId)) {
             issues.push({
@@ -46,7 +68,7 @@ export function validateStructure(registry, plan) {
                 reqId: s.reqId,
                 file: s.file,
                 line: s.line,
-                message: `scenario "${s.name}" attests unknown requirement "${s.reqId}". Add it to the registry, or fix the id.`,
+                message: `scenario "${s.name}" attests unknown requirement "${s.reqId}". ${orphanFix(s.reqId)}`,
             });
         }
     }
@@ -57,6 +79,14 @@ export function validateStructure(registry, plan) {
     // `Object.hasOwn`, never `in`: `'toString' in {}` is true, so an `in` probe
     // silently accepts placeholders no author declared — and render.ts would then
     // interpolate the prototype method into the document.
+    //
+    // non-scalar-interpolation: the placeholder resolves, but to a value that has
+    // no reading as a sentence. This is what the schema's old scalar-or-list union
+    // was actually defending — `[object Object]` in the rendered requirement
+    // document — and it is stated here because that is where the damage is. A
+    // param the statement never names can be any shape it likes: a kind -> payload
+    // table the scenario reads is not a rendering problem, and refusing it in the
+    // schema refused the drift-prone value along with the display bug.
     for (const [id, req] of Object.entries(registry)) {
         for (const m of req.statement.matchAll(/\{(\w+)\}/g)) {
             const name = m[1];
@@ -67,6 +97,16 @@ export function validateStructure(registry, plan) {
                     reqId: id,
                     message: `Requirement "${id}" uses {${name}} in its statement, but params does not define it.`,
                 });
+                continue;
+            }
+            if (!interpolatable(req.params[name])) {
+                issues.push({
+                    level: 'ERROR',
+                    code: 'non-scalar-interpolation',
+                    reqId: id,
+                    message: `Requirement "${id}" uses {${name}} in its statement, but that param is ${shapeOf(req.params[name])}. ` +
+                        `A statement placeholder must be a scalar or a list of scalars.`,
+                });
             }
         }
     }
@@ -135,4 +175,22 @@ export function detectPotentialDrift(registry, plan, refs) {
     }
     return issues;
 }
+/**
+ * Whether a param has a reading as a run of words inside a sentence.
+ *
+ * A scalar does; a list of scalars does, as a comma-separated series. Anything
+ * deeper does not — `render` would have to choose a punctuation for structure,
+ * and every choice is a way for the document to say something the registry did
+ * not. `null` is a scalar here: it renders as `null`, which is the value.
+ */
+function interpolatable(value) {
+    const isScalar = (v) => v === null || typeof v !== 'object';
+    return Array.isArray(value) ? value.every(isScalar) : isScalar(value);
+}
+/** How to name the offending shape in the diagnostic, in the author's terms. */
+function shapeOf(value) {
+    if (Array.isArray(value))
+        return 'a list with a structured element';
+    return 'an object';
+}
 //# sourceMappingURL=validator.js.map