@am_shork/attest 0.4.0 → 0.4.2

package/dist/core/apply.js

@@ -2,7 +2,7 @@
 // OpenSpec's specs-apply: RENAMED -> REMOVED -> MODIFIED -> ADDED over a
 // Map<id, Requirement>, with content-compare on ADDED and already-synced
 // no-ops on RENAMED.
-import { RequirementSchema } from './schema.js';
+import { RequirementIdSchema, RequirementSchema } from './schema.js';
 import { byCodeUnit } from './order.js';
 /**
  * The ids a delta ADDs — the scope of the first-red obligation (design §6).
@@ -24,6 +24,18 @@ export function applyDelta(base, d) {
     const issues = [];
     // 1) RENAMED
     for (const { from, to } of d.renamed ?? []) {
+        // The target before anything else, because it is an id this delta
+        // *introduces* — the same thing an ADDED key is, and held to the same
+        // grammar by the same function. Checked ahead of the source so a delta
+        // naming an impossible target is diagnosed as that, rather than as whatever
+        // the source happens to be: `rename-source-missing` would send its reader to
+        // look for a requirement when the thing to fix is on the other side of the
+        // arrow.
+        const badTarget = introducedIdIssue(to, 'rename-target-invalid', `Rename target "${to}"`);
+        if (badTarget) {
+            issues.push(badTarget);
+            continue;
+        }
         if (map.has(from)) {
             if (map.has(to)) {
                 issues.push(err('rename-target-exists', `Rename "${from}" -> "${to}" failed: "${to}" already exists.`, to));
@@ -64,6 +76,12 @@ export function applyDelta(base, d) {
     }
     // 4) ADDED (content-compare on collision)
     for (const [id, value] of Object.entries(d.added ?? {})) {
+        // The id, before the requirement. See `introducedIdIssue`.
+        const badId = introducedIdIssue(id, 'add-invalid', `Added requirement "${id}"`);
+        if (badId) {
+            issues.push(badId);
+            continue;
+        }
         const parsed = RequirementSchema.safeParse(value);
         if (!parsed.success) {
             issues.push(err('add-invalid', `Added requirement "${id}" is invalid: ${firstMessage(parsed.error)}`, id));
@@ -81,6 +99,36 @@ export function applyDelta(base, d) {
     }
     return { registry: Object.fromEntries(map), issues };
 }
+/**
+ * The one place that decides whether a delta may bring an id into the registry.
+ *
+ * A delta introduces an id in exactly two ways — as an ADDED key, and as the
+ * target of a RENAME — and neither was checked: `applyDelta` validated the
+ * requirement a delta adds and never the key it files it under, so the grammar
+ * `defineRequirements` holds every registry key to did not apply on the one
+ * other path that also creates them. The mild form is an inconsistency, and an
+ * expensive one: a change could archive under an id nobody could then write
+ * into the `*.reqs.ts` the change is supposed to merge into, so the gate passed
+ * on an end state the intent layer cannot represent.
+ *
+ * One function rather than a check at each site, for the reason `hasError` is
+ * one function and `declaredNotRunIssues` was extracted from the two commands
+ * that had a copy each: this is a single rule about a single thing, and two
+ * spellings of a grammar are two grammars the moment one of them is edited. The
+ * `code` and the noun differ because the reader's next move does — one sends
+ * them to a key in `added`, the other to the right-hand side of an arrow — and
+ * that is the whole of the difference.
+ *
+ * `prefix` is the caller's, not built here: it is the part that names the site,
+ * and composing it from a noun and an id would put the message's shape in the
+ * one place that must not care which site it is serving.
+ */
+function introducedIdIssue(id, code, prefix) {
+    const parsed = RequirementIdSchema.safeParse(id);
+    if (parsed.success)
+        return undefined;
+    return err(code, `${prefix} is invalid: ${firstMessage(parsed.error)}`, id);
+}
 function err(code, message, reqId) {
     return { level: 'ERROR', code, ...(reqId ? { reqId } : {}), message };
 }

package/dist/core/docs.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Every code the engine can put on an `Issue`, and therefore every section the
+ * troubleshooting document must have. Alphabetical, so a diff against a heading
+ * list reads as a diff.
+ *
+ * This roster is asserted against two independent things: the `code: '…'`
+ * literals in `src/`, so a new diagnostic cannot be added without landing here,
+ * and the `##` headings of both language documents, so landing here cannot
+ * produce a dead link.
+ */
+export declare const ISSUE_CODES: readonly ["add-conflict", "add-invalid", "change-not-found", "declared-not-run", "duplicate-prefix", "duplicate-requirement", "empty-spec", "internal-error", "invalid-change-name", "missing-spec-doc", "modify-invalid", "modify-missing", "never-red", "orphan-test", "possible-drift", "rationale-placeholder", "registry-invalid", "registry-no-default", "registry-not-static", "rename-source-missing", "rename-target-exists", "rename-target-invalid", "stale-spec-doc", "tests-red", "unbound-param", "uncovered-requirement", "unknown-target"];
+export type IssueCode = (typeof ISSUE_CODES)[number];
+/**
+ * The page explaining `code`, or `undefined` when nothing explains it.
+ *
+ * `undefined` rather than a best-effort link: an anchor that resolves to the
+ * top of the page looks like an answer and is not one. In this repository the
+ * roster is exhaustive, so the undefined branch is unreachable from the
+ * engine's own issues — it exists because `code` is typed `string` on `Issue`,
+ * and a caller outside the engine can put anything there.
+ */
+export declare function docsUrl(code: string): string | undefined;
+//# sourceMappingURL=docs.d.ts.map

package/dist/core/docs.js

@@ -0,0 +1,92 @@
+// The link from a diagnostic to the page that explains it (design §5.3).
+//
+// `Issue.code` is the machine-readable name of a rule, and the troubleshooting
+// document gives every rule one section whose heading *is* that code. So the
+// anchor is not a second thing to maintain — it is the code — and a link can be
+// derived rather than authored. Nothing here is hand-written per issue site,
+// which is the whole point: a diagnostic added without a link is impossible,
+// and a link pointing at a section that does not exist is caught by
+// `tests/docs-consistency.spec.ts` rather than by a reader clicking it.
+import { packageVersion } from './version.js';
+/**
+ * Every code the engine can put on an `Issue`, and therefore every section the
+ * troubleshooting document must have. Alphabetical, so a diff against a heading
+ * list reads as a diff.
+ *
+ * This roster is asserted against two independent things: the `code: '…'`
+ * literals in `src/`, so a new diagnostic cannot be added without landing here,
+ * and the `##` headings of both language documents, so landing here cannot
+ * produce a dead link.
+ */
+export const ISSUE_CODES = [
+    'add-conflict',
+    'add-invalid',
+    'change-not-found',
+    'declared-not-run',
+    'duplicate-prefix',
+    'duplicate-requirement',
+    'empty-spec',
+    'internal-error',
+    'invalid-change-name',
+    'missing-spec-doc',
+    'modify-invalid',
+    'modify-missing',
+    'never-red',
+    'orphan-test',
+    'possible-drift',
+    'rationale-placeholder',
+    'registry-invalid',
+    'registry-no-default',
+    'registry-not-static',
+    'rename-source-missing',
+    'rename-target-exists',
+    'rename-target-invalid',
+    'stale-spec-doc',
+    'tests-red',
+    'unbound-param',
+    'uncovered-requirement',
+    'unknown-target',
+];
+const DOCUMENTED = new Set(ISSUE_CODES);
+const REPO = 'https://gitlab.com/Pseudorca/attest/-/blob';
+const DOC = 'docs/en/troubleshooting.md';
+/**
+ * The version whose documents a link points at, as a git ref.
+ *
+ * Pinned to the tag of the build that printed the diagnostic, not to `main`.
+ * The two failure modes are not symmetric:
+ *
+ * - **Pinned, between a release commit and its tag** — the ref does not resolve
+ *   yet. But that window is a version nobody has installed: the manifest is
+ *   bumped and the package is not published, so no build in anyone's
+ *   `node_modules` prints those links. The 404 is unreachable in practice.
+ * - **Unpinned, after any breaking change to the codes** — a build from a year
+ *   ago links into today's document. A renamed or removed code lands on a
+ *   missing anchor, and worse, a code whose *meaning* changed lands on a
+ *   section confidently describing a different rule. That one is reachable by
+ *   every installed copy, forever, and it gets worse with every release.
+ *
+ * So the ref is `v<version>`, matching this repository's release tags. The
+ * fallback is `main`, for the one case where pinning is impossible rather than
+ * merely imprecise: `packageVersion()` answers `0.0.0` when it cannot read the
+ * manifest, and `v0.0.0` is a tag that has never existed.
+ */
+function ref() {
+    const version = packageVersion();
+    return version === '0.0.0' ? 'main' : `v${version}`;
+}
+/** Resolved once: the version cannot change while the process runs. */
+const BASE = `${REPO}/${ref()}/${DOC}`;
+/**
+ * The page explaining `code`, or `undefined` when nothing explains it.
+ *
+ * `undefined` rather than a best-effort link: an anchor that resolves to the
+ * top of the page looks like an answer and is not one. In this repository the
+ * roster is exhaustive, so the undefined branch is unreachable from the
+ * engine's own issues — it exists because `code` is typed `string` on `Issue`,
+ * and a caller outside the engine can put anything there.
+ */
+export function docsUrl(code) {
+    return DOCUMENTED.has(code) ? `${BASE}#${code}` : undefined;
+}
+//# sourceMappingURL=docs.js.map

package/dist/core/loader.d.ts

@@ -1,3 +1,25 @@
+import { type Logger } from 'vite';
+/**
+ * Vite's logger, with everything it prints put through Attest's sanitiser
+ * (ATX-37).
+ *
+ * `logLevel: 'error'` silences the chatter and not the errors, and an error
+ * here is the one message guaranteed to carry the project's own text: when a
+ * `*.reqs.ts` throws, Vite prints `Error when evaluating SSR module …: <the
+ * message>` straight to stderr, before Attest ever sees the exception. So the
+ * `registry-invalid` diagnostic built from that same error was sanitised while
+ * the raw bytes had already gone past it — a forged `ERROR` header at column 0
+ * and a `\r` to erase the line above, from a file the reviewer only ran.
+ *
+ * The whole message is treated as untrusted, which costs Vite its own colour:
+ * by the time it arrives the project's text has already been interpolated into
+ * it, so there is no half to trust. Losing colour on the one path where a
+ * registry threw is not a price worth arguing about.
+ *
+ * Exported for its own scenario. The logger a live server holds is not
+ * reachable from outside, and a guarantee nothing can fail is not a guarantee.
+ */
+export declare function sanitisedLogger(base?: Logger): Logger;
 export interface Loader {
     load<T = unknown>(absPath: string): Promise<T>;
     close(): Promise<void>;

package/dist/core/loader.js

@@ -6,11 +6,41 @@
 // requirement()/scenario(), but the `attest` barrel transitively imports
 // runtime.ts (which imports vitest), and importing vitest outside a test run
 // throws. The stub sidesteps that without affecting any read value.
-import { createServer } from 'vite';
+import { createLogger, createServer } from 'vite';
 import { mkdtempSync, writeFileSync } from 'node:fs';
 import { rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { block } from './terminal.js';
+/**
+ * Vite's logger, with everything it prints put through Attest's sanitiser
+ * (ATX-37).
+ *
+ * `logLevel: 'error'` silences the chatter and not the errors, and an error
+ * here is the one message guaranteed to carry the project's own text: when a
+ * `*.reqs.ts` throws, Vite prints `Error when evaluating SSR module …: <the
+ * message>` straight to stderr, before Attest ever sees the exception. So the
+ * `registry-invalid` diagnostic built from that same error was sanitised while
+ * the raw bytes had already gone past it — a forged `ERROR` header at column 0
+ * and a `\r` to erase the line above, from a file the reviewer only ran.
+ *
+ * The whole message is treated as untrusted, which costs Vite its own colour:
+ * by the time it arrives the project's text has already been interpolated into
+ * it, so there is no half to trust. Losing colour on the one path where a
+ * registry threw is not a price worth arguing about.
+ *
+ * Exported for its own scenario. The logger a live server holds is not
+ * reachable from outside, and a guarantee nothing can fail is not a guarantee.
+ */
+export function sanitisedLogger(base = createLogger('error')) {
+    return {
+        ...base,
+        info: (msg, opts) => base.info(block(msg), opts),
+        warn: (msg, opts) => base.warn(block(msg), opts),
+        warnOnce: (msg, opts) => base.warnOnce(block(msg), opts),
+        error: (msg, opts) => base.error(block(msg), opts),
+    };
+}
 const VITEST_STUB = 'export const describe=()=>{};export const it=()=>{};export const test=()=>{};' +
     'export const expect=()=>{};export const beforeAll=()=>{};export const afterAll=()=>{};' +
     'export const beforeEach=()=>{};export const afterEach=()=>{};export const vi={};' +
@@ -22,6 +52,10 @@ export async function createLoader() {
     const server = await createServer({
         configFile: false,
         logLevel: 'error',
+        // Not just quiet — sanitised. See `sanitisedLogger`: what survives
+        // `logLevel: 'error'` is exactly the message that carries the checked
+        // project's own text.
+        customLogger: sanitisedLogger(),
         appType: 'custom',
         // `ws: false` is load-bearing, and `middlewareMode` is not enough on its
         // own: it suppresses the HTTP server but Vite still starts the HMR

package/dist/core/pipeline.js

@@ -4,7 +4,7 @@ import { createLoader } from './loader.js';
 import { evalReader, loadRegistry, parseSpecs, parseChangeSpecs, listChangeNames, scanProject, staticReader, } from './locate.js';
 import { validateStructure, detectPotentialDrift, uncoveredIssues } from './validator.js';
 import { byCodeUnit } from './order.js';
-import { runAndCollect } from './runner.js';
+import { runAndCollect, BASE_EXCLUDE } from './runner.js';
 import { applyDelta, addedIds } from './apply.js';
 import { readDeltaSource } from './static-registry.js';
 import { statusRows, statusCounts } from './status.js';
@@ -16,7 +16,6 @@ import { writeAtomic } from './write.js';
 import { mkdir, readFile } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { relativePath } from './paths.js';
-import { configDefaults } from 'vitest/config';
 import { hasError } from './types.js';
 /**
  * Read every registry under root with the reader `options` asks for, and close
@@ -400,7 +399,7 @@ export async function runArchive(root, changeName, options = {}) {
         // Run base specs + this change's specs; exclude other proposals and archive.
         const others = (await listChangeNames(root)).filter((n) => n !== changeName);
         const exclude = [
-            ...configDefaults.exclude,
+            ...BASE_EXCLUDE,
             '**/archive/**',
             ...changeExcludeGlobs(others),
         ];

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

@@ -25,7 +25,15 @@ export type RedRecord = Record<string, Record<string, Outcome>>;
  * the whole one.
  */
 export declare function readRedRecord(root: string, changeName: string): Promise<RedRecord>;
-/** What the record says about one scenario, or undefined if it never saw it. */
+/**
+ * What the record says about one scenario, or undefined if it never saw it.
+ *
+ * Own properties only, at both levels. The containers this module builds have
+ * no prototype, so for those this is belt and braces — but `RedRecord` is an
+ * ordinary structural type and this function is the gate's single reader, so
+ * what it must not do is answer from an inherited key whoever constructed the
+ * object it was handed. `record[reqId]?.[scenario]` did exactly that.
+ */
 export declare function recordedOutcome(record: RedRecord, reqId: string, scenario: string): Outcome | undefined;
 /**
  * Whether this scenario has satisfied the first-red obligation (design §6).

package/dist/core/red-record.js

@@ -47,6 +47,30 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { z } from 'zod';
 import { byCodeUnit } from './order.js';
+/**
+ * **The record is a map, so it is built without a prototype.**
+ *
+ * Its keys are requirement ids and scenario names — the first from a delta, the
+ * second from a spec file — and on a plain object some of those strings are not
+ * keys at all. Two things followed from that, and both are about the gate:
+ *
+ * - `record[id] ??= {}` never fired for `__proto__`, because reading it yields
+ *   `Object.prototype` rather than `undefined`. The outcome was then written
+ *   onto the shared prototype of every object in the process.
+ * - A record read off disk carrying that key re-pointed the *record's* own
+ *   prototype, so `hasRecordedRed` answered `true` for a requirement the file
+ *   said nothing about — a never-red obligation satisfied by a file that
+ *   serialises back as `{}`. Evidence that can be inherited is not evidence.
+ *
+ * Prototype-free rather than a check for the few key names that misbehave: a
+ * blocklist is a second answer to "is this a data key", and the container not
+ * having a prototype is the first one. apply.ts holds the other end by refusing
+ * such an id in the delta; neither is allowed to rely on the other, because
+ * `status` reads `addedIds` without applying the delta at all.
+ */
+function emptyMap() {
+    return Object.create(null);
+}
 /** Where the record lives, relative to the project root. */
 export function redRecordPath(root, changeName) {
     return join(root, 'changes', changeName, RED_RECORD_FILE);
@@ -87,24 +111,55 @@ export async function readRedRecord(root, changeName) {
         raw = await readFile(redRecordPath(root, changeName), 'utf8');
     }
     catch {
-        return {};
+        return emptyMap();
     }
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch {
-        return {};
+        return emptyMap();
     }
     // `JSON.parse` yields `any`; nothing about the file is known until the schema
     // says so, including whether it is an object at all (`JSON.parse('null')`).
     const firstRun = isRecord(parsed) ? parsed['firstRun'] : undefined;
     const result = RedRecordSchema.safeParse(firstRun);
-    return result.success ? result.data : {};
+    return result.success ? adopt(result.data) : emptyMap();
 }
-/** What the record says about one scenario, or undefined if it never saw it. */
+/**
+ * Re-home a parsed record into containers this module owns.
+ *
+ * The validator decides what the *values* may be; this decides what the
+ * container is, and the two are separate on purpose. `JSON.parse` makes
+ * `__proto__` an ordinary own property, and whether a schema library then
+ * carries it through, drops it, or assigns it onto a plain object — swapping
+ * that object's prototype — is an implementation detail of the library. The
+ * gate cannot rest on one, so the record is copied into a map that has no
+ * prototype for such a key to reach.
+ */
+function adopt(parsed) {
+    const record = emptyMap();
+    for (const [id, outcomes] of Object.entries(parsed)) {
+        record[id] = Object.assign(emptyMap(), outcomes);
+    }
+    return record;
+}
+/**
+ * What the record says about one scenario, or undefined if it never saw it.
+ *
+ * Own properties only, at both levels. The containers this module builds have
+ * no prototype, so for those this is belt and braces — but `RedRecord` is an
+ * ordinary structural type and this function is the gate's single reader, so
+ * what it must not do is answer from an inherited key whoever constructed the
+ * object it was handed. `record[reqId]?.[scenario]` did exactly that.
+ */
 export function recordedOutcome(record, reqId, scenario) {
-    return record[reqId]?.[scenario];
+    if (!Object.hasOwn(record, reqId))
+        return undefined;
+    const outcomes = record[reqId];
+    if (outcomes === undefined || !Object.hasOwn(outcomes, scenario))
+        return undefined;
+    return outcomes[scenario];
 }
 /**
  * Whether this scenario has satisfied the first-red obligation (design §6).
@@ -130,12 +185,15 @@ export function hasRecordedRed(record, reqId, scenario) {
  */
 export function mergeRedRecord(existing, plan, run, addedIds) {
     const added = new Set(addedIds);
-    const record = {};
+    const record = emptyMap();
     // Rebuild rather than mutate, so key order is a function of the data and two
     // machines write byte-identical files (the same reason `render` orders ids
     // through one code-unit comparator).
     for (const id of Object.keys(existing).sort(byCodeUnit)) {
-        record[id] = { ...existing[id] };
+        const outcomes = existing[id];
+        if (outcomes === undefined)
+            continue;
+        record[id] = Object.assign(emptyMap(), outcomes);
     }
     let changed = false;
     for (const s of plan.scenarios) {
@@ -147,7 +205,7 @@ export function mergeRedRecord(existing, plan, run, addedIds) {
         // obligation unobserved rather than inventing a state for it.
         if (!outcome)
             continue;
-        const forId = (record[s.reqId] ??= {});
+        const forId = (record[s.reqId] ??= emptyMap());
         // Monotonic toward `fail`: a recorded fail is final, a recorded pass can
         // still be corrected by a real one. See the note at the top of this file.
         if (forId[s.name] === 'fail' || forId[s.name] === outcome)
@@ -157,7 +215,7 @@ export function mergeRedRecord(existing, plan, run, addedIds) {
     }
     // Sort within each requirement for the same byte-stability reason.
     for (const id of Object.keys(record)) {
-        const sorted = {};
+        const sorted = emptyMap();
         for (const name of Object.keys(record[id]).sort(byCodeUnit)) {
             sorted[name] = record[id][name];
         }

package/dist/core/runner.d.ts

@@ -1,5 +1,16 @@
 import { startVitest } from 'vitest/node';
 import type { RunResult } from './types.js';
+/**
+ * Vitest's own default exclusions, which every Attest run keeps on top of
+ * whatever else it excludes.
+ *
+ * Re-exported from here because this module is one of the three allowed to name
+ * `vite`/`vitest` at all (`tests/import-boundary.spec.ts`). `runArchive` needs
+ * this list to compose an exclude set of its own, and importing `vitest/config`
+ * in `pipeline.ts` to get it put the dependency on the module every static
+ * command goes through — the boundary the gate exists to hold.
+ */
+export declare const BASE_EXCLUDE: readonly string[];
 export interface RunAndCollectOptions {
     /** Project root to run. Defaults to the current working directory. */
     root?: string;

package/dist/core/runner.js

@@ -6,8 +6,19 @@ import { startVitest } from 'vitest/node';
 import { configDefaults } from 'vitest/config';
 /** 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.
+ *
+ * Re-exported from here because this module is one of the three allowed to name
+ * `vite`/`vitest` at all (`tests/import-boundary.spec.ts`). `runArchive` needs
+ * this list to compose an exclude set of its own, and importing `vitest/config`
+ * in `pipeline.ts` to get it put the dependency on the module every static
+ * command goes through — the boundary the gate exists to hold.
+ */
+export const BASE_EXCLUDE = configDefaults.exclude;
 /** Proposed / archived changes are excluded from a normal run (design §7, §8). */
-const DEFAULT_EXCLUDE = [...configDefaults.exclude, '**/changes/**', '**/archive/**'];
+const DEFAULT_EXCLUDE = [...BASE_EXCLUDE, '**/changes/**', '**/archive/**'];
 /**
  * Build the child-run options. Attest owns the run *scope* — include/exclude/
  * root/watch always come from here, so the caller can neither widen the spec

package/dist/core/schema.d.ts

@@ -16,6 +16,18 @@ export declare const RequirementSchema: z.ZodObject<{
     params?: Record<string, string | number | boolean | (string | number | boolean)[]> | undefined;
     outOfScope?: string[] | undefined;
 }>;
+/**
+ * The id grammar, on its own.
+ *
+ * Exported because the registry is not the only thing that files a requirement
+ * under an id: a delta's ADDED block does too, and `applyDelta` validated the
+ * requirement while never looking at the key it went under (design §7). So
+ * `changes/` could introduce an id `defineRequirements` would refuse — one that
+ * could therefore never be written into a `*.reqs.ts` after the change merged.
+ * One schema rather than a second regex, because two spellings of a grammar are
+ * two grammars as soon as one of them is edited.
+ */
+export declare const RequirementIdSchema: z.ZodString;
 /** The requirement registry: stable ID -> requirement (design §2, §5.1). */
 export declare const RegistrySchema: z.ZodRecord<z.ZodString, z.ZodObject<{
     statement: z.ZodEffects<z.ZodString, string, string>;

package/dist/core/schema.js

@@ -22,6 +22,20 @@ export const RequirementSchema = z.object({
         .default({}),
     outOfScope: z.array(z.string()).default([]),
 });
+/**
+ * The id grammar, on its own.
+ *
+ * Exported because the registry is not the only thing that files a requirement
+ * under an id: a delta's ADDED block does too, and `applyDelta` validated the
+ * requirement while never looking at the key it went under (design §7). So
+ * `changes/` could introduce an id `defineRequirements` would refuse — one that
+ * could therefore never be written into a `*.reqs.ts` after the change merged.
+ * One schema rather than a second regex, because two spellings of a grammar are
+ * two grammars as soon as one of them is edited.
+ */
+export const RequirementIdSchema = z
+    .string()
+    .regex(/^[A-Z]+-\d+$/, 'id must look like AUTH-3');
 /** The requirement registry: stable ID -> requirement (design §2, §5.1). */
-export const RegistrySchema = z.record(z.string().regex(/^[A-Z]+-\d+$/, 'id must look like AUTH-3'), RequirementSchema);
+export const RegistrySchema = z.record(RequirementIdSchema, RequirementSchema);
 //# sourceMappingURL=schema.js.map

package/dist/core/skill.js

@@ -148,7 +148,7 @@ export default delta({
     'AUTH-3': { params: { idleTimeoutMin: 15 } },   // 30 → 15; the assertion follows, because it reads params
   },
   removed: ['AUTH-5'],
-  renamed: [{ from: 'AUTH-2', to: 'AUTH-2-login' }],
+  renamed: [{ from: 'AUTH-2', to: 'SESSION-1' }],   // a rename target is a new id, so it obeys the id grammar
 });
 \`\`\`
 
@@ -184,6 +184,13 @@ Two consequences worth knowing before you start:
 Commit \`first-run.json\` with the change. It is evidence a reviewer reads, and
 the gate has to reach the same verdict on a CI checkout as on your machine.
 
+**Never write or edit that file yourself.** The gate trusts it and cannot check
+it: everything else Attest writes can be regenerated and compared, but a first
+run cannot be recomputed once the change is green — which is the whole reason
+the record exists. Producing it any way other than by running the gate destroys
+the only thing it is for. If it says something you did not expect, run the gate
+again; a real failing run replaces a recorded pass.
+
 To see where the change stands at any point, without paying for a run:
 
 \`\`\`
@@ -225,7 +232,7 @@ once. Branch on \`issues[].code\`, never on \`message\`:
 | \`add-conflict\` | the delta adds an id that already exists with different content |
 | \`change-not-found\` | no \`requirements.delta.ts\` for that name |
 
-### Three things you must not do
+### Four things you must not do
 
 Each turns the gate green without changing the system, which is the exact
 failure this framework exists to make visible:
@@ -240,6 +247,10 @@ failure this framework exists to make visible:
    is the drift the single source exists to prevent, and the param is typed at
    the value written in the registry, so a stale expectation stops compiling
    rather than silently passing.
+4. **Do not write or edit \`first-run.json\`.** It is the one file here the gate
+   trusts without being able to check it, so a hand-written \`"fail"\` clears
+   \`never-red\` while proving nothing at all. Run the gate before implementing;
+   that is what produces the record honestly.
 
 ### When the gate passes
 

package/dist/core/terminal.d.ts

@@ -0,0 +1,24 @@
+/** How far a message is indented under its header line. */
+export declare const INDENT = "    ";
+/**
+ * A multi-line message, safe to print under a header.
+ *
+ * A newline survives, because one diagnostic is legitimately multi-line:
+ * `registry-invalid` carries Zod's list of field errors, a stack trace is a
+ * list of frames, and flattening either would cost a real reader a real thing
+ * to save a hypothetical one. It is re-indented instead, so injected text lands
+ * inside the message block rather than at column 0 where a forged `ERROR ...`
+ * header would be indistinguishable from a real one.
+ */
+export declare function block(text: string): string;
+/** The same, for text that sits inline in a header and must stay one line. */
+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.
+ */
+export declare function control(text: string): string;
+//# sourceMappingURL=terminal.d.ts.map

package/dist/core/terminal.js

@@ -0,0 +1,59 @@
+// Text from the project under test, on its way to a terminal (ATX-37).
+//
+// Most of what Attest prints is its own prose, but the parts a reader actually
+// navigates by are not: a scenario name and a file path are quoted verbatim out
+// of the repository being checked (`orphan-test`, `declared-not-run`,
+// `never-red`), and the parser hands back the *cooked* string, so an ESC written
+// as an escape in a spec file is a real control byte by the time it arrives
+// here. So is the message of anything that repository throws, which under
+// `verify`, `archive` or `--eval` is a module Attest is running.
+//
+// That makes Attest's output a place where the repository being checked can
+// write to the terminal of whoever is checking it. On a fork MR the author is
+// not the reviewer, and the payload is a scenario name or an exception: erase
+// the lines above, repaint a red verdict green, rewrite the window title. The
+// `--json` path was never exposed — `JSON.stringify` escapes every C0
+// character — which is precisely why this has to hold on the side people read.
+//
+// **In `core/` rather than in the CLI**, though the CLI is its main caller: the
+// 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 = '    ';
+/**
+ * A multi-line message, safe to print under a header.
+ *
+ * A newline survives, because one diagnostic is legitimately multi-line:
+ * `registry-invalid` carries Zod's list of field errors, a stack trace is a
+ * list of frames, and flattening either would cost a real reader a real thing
+ * to save a hypothetical one. It is re-indented instead, so injected text lands
+ * inside the message block rather than at column 0 where a forged `ERROR ...`
+ * header would be indistinguishable from a real one.
+ */
+export function block(text) {
+    return control(text).replaceAll('\n', `\n${INDENT}`);
+}
+/** The same, for text that sits inline in a header and must stay one line. */
+export function inline(text) {
+    return control(text).replaceAll('\n', ' ');
+}
+/**
+ * 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.
+ */
+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('');
+}
+//# sourceMappingURL=terminal.js.map