eval-quality 3.2.0 → 3.4.0

package/README.md

@@ -134,7 +134,7 @@ Node.js 22.20.0 or newer. `zod` is the only production dependency.
 npm install eval-quality
 ```
 
-Every command runs through `npx`:
+Every command runs through `npx`. The four below are the grammar rather than a sequence to copy: they name files your own harness produces. [The full walkthrough](https://bmad-code-org.github.io/bmad-eval-quality/how-to/author-behavioral-contracts/) runs the same four end to end over files this repository commits, with no placeholder in the path.
 
 ```bash
 npx eval-quality compile --in contract.json --out ./eval-out

package/dist/application/index.d.ts

@@ -6,6 +6,11 @@
  * unamended.
  */
 export { digestArtifact, digestBytes, digestComposite, } from '../core/canonical/digest.ts';
+export { makePointerDenotesCollection, makeResolveOperand, referenceSetKeysOf, } from '../core/evaluate/evidence-resolution.ts';
+export type { PointerDenotesCollection, ReferenceSetKeys, ResolveOperand, } from '../core/evaluate/resolution.ts';
+export { resolveCheck } from '../core/evaluate/resolution.ts';
+export type { ResolvedValue } from '../core/evaluate/resolved-value.ts';
+export { ABSENT } from '../core/evaluate/resolved-value.ts';
 export type { FailureCode } from '../core/failure-codes.ts';
 export { FAILURE_CODES, StructuralFailure } from '../core/failure-codes.ts';
 export type { LineageChainReport, LineageFinding, } from '../core/lineage/chain.ts';
@@ -21,6 +26,7 @@ export type { QualificationFailure, QualificationFailureCode, QualificationResul
 export { QUALIFICATION_FAILURES } from '../core/score/qualification.ts';
 export type { ComparableResult, DominanceRelationValue, } from '../core/score/strength.ts';
 export { compareDominance, DOMINANCE_RELATIONS, } from '../core/score/strength.ts';
+export type { PlanIndex } from '../core/seal/plan-index.ts';
 export { compile } from './compile.ts';
 export type { Diagnostic, DiagnosticSink } from './diagnostics.ts';
 export type { PreflightFromObservationsOptions, RunPreflightOptions, } from './preflight.ts';

package/dist/application/index.js

@@ -6,6 +6,14 @@
  * unamended.
  */
 export { digestArtifact, digestBytes, digestComposite, } from '../core/canonical/digest.js';
+// The evaluator, for a consumer that resolves a check itself: the resolver,
+// the two factories that build its operand and collection predicates from a
+// contract and its observations, and the reference-set keys. `ABSENT` ships
+// beside them because a `ResolveOperand` a consumer writes has to return it,
+// and a sentinel the type names and the barrel withholds cannot be returned.
+export { makePointerDenotesCollection, makeResolveOperand, referenceSetKeysOf, } from '../core/evaluate/evidence-resolution.js';
+export { resolveCheck } from '../core/evaluate/resolution.js';
+export { ABSENT } from '../core/evaluate/resolved-value.js';
 export { FAILURE_CODES, StructuralFailure } from '../core/failure-codes.js';
 export { validateLineageChain } from '../core/lineage/chain.js';
 export { INTERCHANGE_ARTIFACT_KEYS } from '../core/schemas/artifact.js';

package/dist/gates/check-dependency-direction.js

@@ -18,6 +18,7 @@
 // appear in this file or anything it imports, or the gate fails at load.
 import { z } from 'zod';
 import { discoverSourceFiles } from './discover-source-files.js';
+import { isCode, loadTypeScriptScanner, TYPESCRIPT_UNAVAILABLE, } from './typescript-scanner.js';
 /** The gate's key in the configuration file, and the token the binary dispatches on. */
 export const DEPENDENCY_DIRECTION_GATE = 'dependency-direction';
 /**
@@ -26,7 +27,7 @@ export const DEPENDENCY_DIRECTION_GATE = 'dependency-direction';
  * description and asserted by `tests/architecture/dependency-direction.test.ts`,
  * so the ordering property below is a measured fact rather than a warning.
  */
-export const ORDERING_WITNESS_VIOLATIONS = 78;
+export const ORDERING_WITNESS_VIOLATIONS = 80;
 /** The optional peer is absent. The consumer repairs it by installing it, so it takes the usage code. */
 export const TYPESCRIPT_PEER_MISSING = 'EVAL_QUALITY_TYPESCRIPT_PEER_MISSING';
 /** A declared scan root could not be walked. Also a usage code: nothing was scanned, so nothing was answered. */
@@ -228,25 +229,24 @@ const refuse = (code, message) => ({
 /**
  * The scanner needs `typescript/unstable/ast`, and `typescript` is an optional
  * peer dependency so that a consumer running the other gates installs nothing.
- * Probing it by name is what turns a resolver stack trace into a sentence naming
- * the dependency and the gate that wanted it.
+ * `typescript-scanner.ts` is what turns a resolver stack trace into a sentence
+ * naming the dependency, the installed version and the gate that wanted it; a
+ * failure of any other shape is a bug in the scanner, not a missing peer, and
+ * is rethrown unchanged.
  *
  * `load` is injectable so a test can exercise the refusal without uninstalling
  * the package the test runner itself needs.
  */
-export async function probeTypeScript(load = () => import('typescript/unstable/ast')) {
+export async function probeTypeScript(load = () => loadTypeScriptScanner(DEPENDENCY_DIRECTION_GATE)) {
     try {
         await load();
         return { ok: true };
     }
     catch (error) {
-        if (error.code !== 'ERR_MODULE_NOT_FOUND') {
-            throw error;
+        if (isCode(error, TYPESCRIPT_UNAVAILABLE)) {
+            return { ok: false, message: error.message };
         }
-        return {
-            ok: false,
-            message: `the ${DEPENDENCY_DIRECTION_GATE} gate reads your source with the TypeScript scanner, and the optional peer dependency "typescript" is not installed here. Install it (npm install --save-dev typescript), or drop the "${DEPENDENCY_DIRECTION_GATE}" section from your configuration to stop invoking this gate. No other gate needs it.`,
-        };
+        throw error;
     }
 }
 const orderViolations = (violations) => [...violations].sort((a, b) => a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1);

package/dist/gates/check-doc-claims.js

@@ -50,6 +50,22 @@
 // sentence was rewritten fails as a dead entry. That is weaker than deciding
 // the claim and stronger than the nothing that precedes it.
 //
+// A "read" claim by itself proves only that the sentence was once registered,
+// and nothing re-checks the reading afterward: the artifact it was read from
+// can drift for years and the entry stays green. A claim may carry an `asOf`
+// pin against that: a normalized-content sha256 of the file the human actually
+// read, defaulting to the claim's own page. An edit to that file changes the
+// hash and fails the entry, which is what turns "read once" into "read, and
+// still current." A `settles` predicate needs none of this, because it already
+// re-runs every check.
+//
+// The pin only works for a subject this run can read, so it is worth nothing
+// against a fact about another repository or a live system; naming a subject
+// in this tree that is not the actual evidence, such as the page merely
+// stating the fact, buys a false sense of protection rather than none. Naming
+// the real evidence file under `subject`, in-tree, is what makes the pin mean
+// something.
+//
 // What stays outside all eight: editorial judgment, design rationale, anything
 // about the world beyond the tree, any claim about runtime behaviour that only
 // executing the code would settle, and whether a code a page names is the one
@@ -62,6 +78,7 @@
 // Run by `node` directly: Node's type stripping erases types only, so no
 // TypeScript enum, namespace, parameter property, or non-type re-export may
 // appear in this file or anything it imports.
+import { createHash } from 'node:crypto';
 import { realpathSync } from 'node:fs';
 import { lstat, readdir, readFile } from 'node:fs/promises';
 import { resolve, sep } from 'node:path';
@@ -225,6 +242,41 @@ const VocabularyBlock = z
     });
 })
     .describe('Every sentence saying a member of your vocabulary is accepted or refused agrees with the two sets.');
+/**
+ * The 64-character lowercase-hex shape a sha256 digest prints as, so a
+ * truncated or upper-cased paste is refused at configuration load rather than
+ * comparing unequal to every subject forever.
+ */
+const Sha256Hex = z
+    .string()
+    .regex(/^[0-9a-f]{64}$/, 'is not a sha256 hex digest: 64 lowercase hex characters');
+const DatedClaimAsOf = z
+    .strictObject({
+    subject: RelativePath.optional().describe("Which file the hash pins the claim to, when the judgment is about a file other than the one carrying the sentence. Defaults to the claim's own `file`. Has to be in this tree: a fact about another repository or a live system cannot be pinned, and naming the page that merely states such a fact is worse than naming nothing, since it reads as protected when it is not."),
+    hash: Sha256Hex.describe("The subject's normalized-content sha256, taken the moment a human confirmed this claim true against it."),
+})
+    .describe('Pins a `read` claim to the content a human read it against, so an edit to that content fails the gate instead of a stale confirmation passing forever. A claim resting on more than one subject wants a predicate over the set, not several pins under one key.');
+const DatedClaimEntry = z
+    .strictObject({
+    file: RelativePath,
+    key: NonEmpty.describe('A distinctive stretch of the sentence, matched literally. It names one sentence: a key short enough to match two lets a new and false claim ride in on an existing registration.'),
+    settles: z
+        .union([z.literal('read'), ModuleValue])
+        .describe('How the claim is settled. A predicate is run and a false answer fails the gate. "read" records that no artifact decides it.'),
+    reason: NonEmpty.describe('What the predicate reads, or why nothing in the tree can decide it.'),
+    asOf: DatedClaimAsOf.optional(),
+})
+    .superRefine((entry, ctx) => {
+    // A predicate already re-runs every check; a content pin beside it would be
+    // a second staleness rule racing the first, and the two can disagree.
+    if (entry.asOf !== undefined && entry.settles !== 'read') {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['asOf'],
+            message: 'is set, and settles is a predicate rather than "read"; a predicate is re-checked every run, so pinning a content hash beside it is redundant at best and contradictory at worst',
+        });
+    }
+});
 const DatedBlock = z
     .strictObject({
     triggers: z
@@ -233,15 +285,26 @@ const DatedBlock = z
         .describe('The shapes a claim takes when its truth depends on when it was written. A sentence matching one has to be registered below.'),
     headings: ProsePattern.optional().describe('A heading that says its section is about what has not happened, so every bullet under one is dated whatever words it uses.'),
     claims: z
-        .array(z.strictObject({
-        file: RelativePath,
-        key: NonEmpty.describe('A distinctive stretch of the sentence, matched literally. It names one sentence: a key short enough to match two lets a new and false claim ride in on an existing registration.'),
-        settles: z
-            .union([z.literal('read'), ModuleValue])
-            .describe('How the claim is settled. A predicate is run and a false answer fails the gate. "read" records that no artifact decides it.'),
-        reason: NonEmpty.describe('What the predicate reads, or why nothing in the tree can decide it.'),
-    }))
-        .min(1),
+        .array(DatedClaimEntry)
+        .min(1)
+        .superRefine((claims, ctx) => {
+        // One entry per sentence. Two entries sharing a `file` and `key` both
+        // pass the "seen" check below, since it is keyed on the same two
+        // values, so a duplicate is not caught there; left unrefused, it
+        // double-counts one sentence as two registered claims.
+        const seen = new Set();
+        claims.forEach((claim, index) => {
+            const key = compositeKey(claim.file, claim.key);
+            if (seen.has(key)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: [index, 'key'],
+                    message: `repeats the file and key of an earlier entry (${claim.file}: "${claim.key}"), and a dated claim is registered once; give the sentence one entry`,
+                });
+            }
+            seen.add(key);
+        });
+    }),
 })
     .describe('Every sentence whose truth depends on when it was written is registered with how it is settled.');
 const TranscriptionEntry = z.strictObject({
@@ -365,6 +428,148 @@ const sentenceAround = (line, offset) => {
     const end = stop === -1 ? line.length : offset + stop + 1;
     return line.slice(start, end);
 };
+/**
+ * A fenced code block's opening delimiter: three or more backticks or tildes,
+ * CommonMark's own two fence characters. Captured so the close can require the
+ * same character and at least as many repeats, the way CommonMark itself does:
+ * a shorter or differently-charactered run inside the fence is content, not a
+ * close.
+ */
+const FENCE_OPEN = /^(`{3,}|~{3,})/;
+const closesFence = (trimmedStart, marker) => new RegExp(`^${marker[0] === '`' ? '`' : '~'}{${marker.length},}\\s*$`).test(trimmedStart);
+/**
+ * What an `asOf` hash is taken over. Outside a fenced code block, each line's
+ * leading indentation is read as a nesting depth rather than kept byte-exact,
+ * and everything after it is trimmed of trailing whitespace and has its
+ * internal whitespace runs collapsed to one space; a run of blank lines
+ * collapses to one. Depth, not width, is what a nested list or an indented
+ * block actually carries: a formatter that reindents an existing structure
+ * two spaces to four, say, does not change what the page says and must not
+ * trip the pin, but un-nesting a list item, or nesting a new one, is a real
+ * structural change and has to. Comparing raw indentation width cannot tell
+ * these apart, so depth is tracked with a stack the way an indentation-block
+ * language is: a deeper indent than the current top pushes a new level, a
+ * shallower one pops back to it, and the line is rewritten with a canonical
+ * two-space unit per level of depth rather than its own original width. A
+ * fenced block is left byte-exact (line-ending normalized), because
+ * indentation inside one is meaning a formatter is not free to move, and
+ * either collapsing or renormalizing it would let a broken code sample hide
+ * behind a passing gate. A stray shorter or wrongly-charactered fence-like
+ * line inside an open fence does not close it, so a nested example fence
+ * stays part of the outer block's protected content.
+ *
+ * What this does not do runs in both directions. Normalization only touches
+ * whitespace, so two shapes of real change stay invisible: a hard line
+ * break's trailing two spaces can be removed, and content outside a fence
+ * that is reindented without crossing a depth boundary, such as a non-fenced
+ * indented code sample's own internal width, changes without changing the
+ * hash either, since depth tracking only sees where a line sits relative to
+ * its neighbors and not what its own further indentation means. Every other
+ * markdown-syntax change is a non-whitespace byte and always shows, which is
+ * why catching either of those needs real markdown parsing and nothing else
+ * here does. In the other direction, a table's delimiter-row padding
+ * (`|---|---|` vs `| --- | --- |`) or a prose line rewrapped to a different
+ * width changes the hash even though nothing about what the page says
+ * changed, so a formatter doing either still trips the pin it was meant to
+ * spare. A consumer whose formatter rewraps prose can avoid that one with
+ * its own `proseWrap: "preserve"` setting; this gate has no equivalent knob.
+ */
+const normalizeForHash = (text) => {
+    const lines = [];
+    let fenced = false;
+    let fenceMarker = '';
+    let blank = false;
+    // A stack of indentation widths seen on the path to the current line, the
+    // same technique an indentation-block language's own lexer uses: its
+    // length, not the raw column number on top of it, is the depth a
+    // formatter cannot change just by picking a different unit width.
+    const indentStack = [0];
+    for (const withCr of text.split('\n')) {
+        const raw = withCr.endsWith('\r') ? withCr.slice(0, -1) : withCr;
+        const trimmedStart = raw.trimStart();
+        if (fenced) {
+            if (closesFence(trimmedStart, fenceMarker)) {
+                fenced = false;
+                lines.push(trimmedStart.trimEnd());
+                blank = false;
+                continue;
+            }
+            lines.push(raw);
+            blank = false;
+            continue;
+        }
+        const opened = FENCE_OPEN.exec(trimmedStart);
+        if (opened !== null) {
+            fenced = true;
+            fenceMarker = opened[1];
+            lines.push(trimmedStart.trimEnd());
+            blank = false;
+            continue;
+        }
+        const content = trimmedStart.replace(/\s+$/, '').replace(/[ \t]+/g, ' ');
+        if (content === '') {
+            if (blank)
+                continue;
+            blank = true;
+            lines.push('');
+            continue;
+        }
+        blank = false;
+        const indent = raw.length - trimmedStart.length;
+        while (indentStack.length > 1 &&
+            indent < indentStack[indentStack.length - 1]) {
+            indentStack.pop();
+        }
+        if (indent > indentStack[indentStack.length - 1]) {
+            indentStack.push(indent);
+        }
+        const depth = indentStack.length - 1;
+        lines.push(`${'  '.repeat(depth)}${content}`);
+    }
+    // A document that ends without closing its last fence is malformed, and the
+    // trailing bytes inside that open fence are exactly the content the fenced
+    // branch above promises to keep byte-exact; trimming into them here would
+    // break that promise for the one shape that never legitimately arises in a
+    // well-formed page.
+    if (!fenced) {
+        while (lines.length > 0 && lines[0] === '')
+            lines.shift();
+        while (lines.length > 0 && lines[lines.length - 1] === '')
+            lines.pop();
+    }
+    return lines.join('\n');
+};
+/** What `dated.claims[].asOf.hash` holds: exported so a human confirming a claim can compute it. */
+export const hashOfSubject = (text) => createHash('sha256').update(normalizeForHash(text)).digest('hex');
+/**
+ * An `asOf.subject`'s content, read the way every other path this gate reads
+ * is read: a symbolic link is refused rather than followed, the same rule
+ * `walkPages` applies to a page and for the same reason, so a pin cannot be
+ * moved to point outside the tree the configuration names. A subject that is
+ * also a walked page is read from `pageText` rather than the disk a second
+ * time, which is both cheaper and, for that case, already covered by
+ * `walkPages`'s own symlink refusal.
+ */
+const readSubject = async (root, subject, pageText) => {
+    const cached = pageText.get(subject);
+    if (cached !== undefined)
+        return { kind: 'ok', body: cached.join('\n') };
+    const target = resolve(root, subject);
+    const info = await lstat(target).catch(() => null);
+    if (info === null)
+        return { kind: 'error', code: 'ENOENT' };
+    if (info.isSymbolicLink())
+        return { kind: 'symlink' };
+    try {
+        return { kind: 'ok', body: await readFile(target, 'utf8') };
+    }
+    catch (error) {
+        return {
+            kind: 'error',
+            code: error.code ?? 'EUNKNOWN',
+        };
+    }
+};
 /**
  * Which backticked tokens in a captured stretch count as list members. A
  * spelling rule covers a set whose members share a shape; a module export covers
@@ -480,7 +685,21 @@ export async function runDocClaims(root, section) {
             // this the short form is ambiguous and the check would refuse a citation
             // a reader resolves without effort.
             const qualified = new Map();
+            // A fenced block is output rather than prose, and a diagnostic a page
+            // transcribes carries the file and line of whatever tree the command
+            // ran over, which is commonly a fixture the page itself created. Read
+            // as a citation that path resolves to nothing here and the class fails
+            // on a page that is correct. The invocation check already holds a
+            // transcribed block against the bytes the run really wrote, so the
+            // claim is held either way.
+            let fenced = false;
             lines.forEach((line, index) => {
+                if (line.trimStart().startsWith('```')) {
+                    fenced = !fenced;
+                    return;
+                }
+                if (fenced)
+                    return;
                 for (const match of line.matchAll(citation)) {
                     const cited = match[1];
                     const first = Number(match[2]);
@@ -655,6 +874,7 @@ export async function runDocClaims(root, section) {
         const seen = new Set();
         let read = 0;
         let derived = 0;
+        let pinned = 0;
         for (const page of authoredPages) {
             const lines = pageText.get(page);
             let owedSection = false;
@@ -701,6 +921,29 @@ export async function runDocClaims(root, section) {
             }
             if (entry.settles === 'read') {
                 read += 1;
+                if (entry.asOf !== undefined) {
+                    pinned += 1;
+                    const subject = entry.asOf.subject ?? entry.file;
+                    const read = await readSubject(root, subject, pageText);
+                    if (read.kind === 'symlink') {
+                        fail(`${entry.file}: dated.claims holds "${entry.key}" with asOf.subject "${subject}", ` +
+                            'which is a symbolic link; name the file it resolves to, so the pin cannot be ' +
+                            'moved to point outside the tree the configuration names');
+                    }
+                    else if (read.kind === 'error') {
+                        fail(`${entry.file}: dated.claims holds "${entry.key}" with asOf.subject "${subject}", ` +
+                            `which could not be read (${read.code})`);
+                    }
+                    else {
+                        const computed = hashOfSubject(read.body);
+                        if (computed !== entry.asOf.hash) {
+                            fail(`${entry.file}: "${entry.key}" was last confirmed against ${subject} at a ` +
+                                `different content hash (stored ${entry.asOf.hash}, computed ${computed}); ` +
+                                `run \`node scripts/hash-doc-claim-subject.ts ${subject}\` and update asOf.hash, ` +
+                                'or fix/remove the entry');
+                        }
+                    }
+                }
                 continue;
             }
             derived += 1;
@@ -709,7 +952,7 @@ export async function runDocClaims(root, section) {
             fail(`${entry.file}: "${entry.key}" is no longer true; the check that settles it ` +
                 `(${entry.reason}) now answers no`);
         }
-        parts.push(`${derived + read} time-sensitive claims registered (${derived} settled by a predicate, ${read} by review)`);
+        parts.push(`${derived + read} time-sensitive claims registered (${derived} settled by a predicate, ${read} by review, ${pinned} pinned to a content hash)`);
     }
     // -----------------------------------------------------------------------
     // Class 5: named codes

package/dist/gates/check-doc-invocations.mjs

@@ -1,6 +1,13 @@
 // A published gate: every fenced command-line invocation in the pages a
-// consumer names is run against the binary they name, and the exit code is
-// compared with what the page claims.
+// consumer names is run against the binary whose spelling opens the line, and
+// the exit code is compared with what the page claims.
+//
+// A section names one binary, or several. A package that publishes two
+// commands documents both, and each one carries its own built entry, its own
+// spellings and its own installed-path prefix. Every spelling is matched
+// against the same page and the longest one wins, because two published names
+// commonly share a prefix and declaration order says nothing about which of
+// them a line belongs to.
 //
 // The check exists because the documentation once described a product this
 // repository does not contain. A usage exit is what a command line returns when
@@ -14,8 +21,12 @@
 // reported no problems. So the exit code is judged too, wherever judging it
 // means anything:
 //
-//   * A usage error and a crash always fail, for every invocation. Both are
-//     about the command line alone, so a stand-in input cannot excuse them.
+//   * A crash always fails, for every invocation, and so does a usage error the
+//     page did not declare. Both are about the command line alone, so a
+//     stand-in input cannot excuse them. A page that declares the usage exit
+//     for a faithful invocation is claiming that refusal on purpose, which is
+//     what a binary spending that code on a configuration it would not read
+//     needs.
 //   * An invocation is FAITHFUL when every input it names resolved to real
 //     bytes: a file the repository ships, a file the same page told the reader
 //     to create, or an artifact an earlier command on the page wrote. A
@@ -35,9 +46,11 @@
 // The exit code alone is a weak claim, because it is shared. One code commonly
 // covers a whole family of failures, so a page can name one failure while the
 // binary reports another and the codes still agree. A page that declares its
-// exit code may therefore transcribe the diagnostic beside it, and that block is
-// compared line for line against what the run wrote to stderr. Four rules shape
-// which block gets compared:
+// exit code may therefore transcribe the output beside it, and that block is
+// compared line for line against what the run wrote: stderr when the run wrote
+// any, and stdout otherwise, since a page documenting a command that worked is
+// quoting the answer rather than a diagnostic. Four rules shape which block gets
+// compared:
 //
 //   * The block is a `text` fence separated from the command's fence by blank
 //     lines only. Prose between them detaches it, and a fence carrying any
@@ -311,11 +324,15 @@ function describesLine(documented, actual) {
  * fence or the next unindented line.
  *
  * A `text` fence separated from a declared-exit invocation by nothing but blank
- * lines is that invocation's transcribed diagnostic, and it travels on the run
- * as `expectStderr`. Only a declared-exit invocation collects one: a page that
- * shows the output of a command that succeeded is showing stdout, and every
- * page that documents a failure prints it on stderr. The fence has to have
+ * lines is that invocation's transcribed output, and it travels on the run as
+ * `expectStderr`. Only a declared-exit invocation collects one, so a page opts
+ * in to the comparison by declaring what the run returns. The fence has to have
  * pushed exactly one such invocation, since both would carry its declaration.
+ *
+ * `spellings` is every spelling across every declared binary, already sorted
+ * longest first, and each one carries the index of the binary it belongs to.
+ * That index travels on the run, so the caller knows which entry to execute and
+ * whose installed-path prefix to resolve the arguments against.
  */
 function extractActions(file, source, spellings) {
     const lines = source.split('\n');
@@ -421,10 +438,12 @@ function extractActions(file, source, spellings) {
             index += 1;
             text = `${text.slice(0, -1).trim()} ${lines[index].trim()}`;
         }
-        const match = spellings.map((pattern) => text.match(pattern)).find(Boolean);
-        if (!match)
+        const matched = spellings
+            .map((spelling) => ({ spelling, match: text.match(spelling.pattern) }))
+            .find((candidate) => candidate.match !== null);
+        if (matched === undefined)
             continue;
-        const tail = (match[1] ?? '').trim();
+        const tail = (matched.match[1] ?? '').trim();
         if (tail === '')
             continue;
         const first = tokenize(tail)[0];
@@ -436,6 +455,7 @@ function extractActions(file, source, spellings) {
             line: startLine,
             invocation: text,
             tail,
+            binary: matched.spelling.binary,
             expectExit,
             expectStderr: null,
         };
@@ -453,12 +473,24 @@ function extractActions(file, source, spellings) {
  * section names resolves against it.
  */
 export function runDocInvocations(root, section) {
-    const entry = resolve(root, section.binary.entry);
+    // One binary is the ordinary case and stays spelled as one object. The list
+    // is built once here, so everything below reads the same shape.
+    const declared = Array.isArray(section.binary)
+        ? section.binary
+        : [section.binary];
+    const binaries = declared.map((binary) => ({
+        entry: resolve(root, binary.entry),
+        installedPrefix: binary.installedPrefix,
+    }));
     // A build is a precondition rather than an excuse. Skipping here would let
     // the gate exit 0 having executed nothing, which is the vacuous pass the
-    // whole check exists to prevent.
-    if (!existsSync(entry)) {
-        throw codedError(DOC_PATH_ERROR, `${entry} does not exist; the "doc-invocations" section names it under binary.entry, so build it before the gate runs`);
+    // whole check exists to prevent. The refusal names which binary is missing,
+    // since a reader with two of them has two build steps to choose between.
+    for (const [index, binary] of binaries.entries()) {
+        if (existsSync(binary.entry))
+            continue;
+        const field = declared.length === 1 ? 'binary.entry' : `binary[${index}].entry`;
+        throw codedError(DOC_PATH_ERROR, `${binary.entry} does not exist; the "doc-invocations" section names it under ${field}, so build it before the gate runs`);
     }
     const sampleInput = resolve(root, section.sampleInput);
     if (!existsSync(sampleInput)) {
@@ -486,12 +518,26 @@ export function runDocInvocations(root, section) {
             throw codedError(DOC_PATH_ERROR, `the "doc-invocations" section names "${page}" under pages, and that encloses the directory the configuration sits in; name a page or a directory inside it, since every fenced command under a whole repository is more than this gate should run`);
         }
     }
-    const spellings = section.binary.spellings.map(spellingPattern);
-    const context = {
-        repoRoot: resolve(root),
+    // Longest first, and the first match wins. Two published names commonly
+    // share a prefix, so matching in declaration order would let a short
+    // spelling belonging to one binary claim a line that opens with a longer
+    // spelling belonging to another, and the line would then run against the
+    // wrong entry and be judged against the wrong installed-path prefix.
+    const spellings = declared
+        .flatMap((binary, index) => binary.spellings.map((spelling) => ({
+        text: spelling.trim(),
+        pattern: spellingPattern(spelling),
+        binary: index,
+    })))
+        .sort((a, b) => b.text.length - a.text.length);
+    const repoRoot = resolve(root);
+    // One context per binary, because `installedPrefix` belongs to the binary a
+    // line matched. Two binaries on one page can map different installed paths.
+    const contexts = binaries.map((binary) => ({
+        repoRoot,
         sampleInput,
-        installedPrefix: section.binary.installedPrefix,
-    };
+        installedPrefix: binary.installedPrefix,
+    }));
     const files = section.pages
         .flatMap((page) => collectMarkdown(resolve(root, page)))
         .sort();
@@ -506,8 +552,8 @@ export function runDocInvocations(root, section) {
     let compared = 0;
     try {
         for (const [index, absolute] of files.entries()) {
-            const file = absolute.startsWith(context.repoRoot)
-                ? absolute.slice(context.repoRoot.length + 1)
+            const file = absolute.startsWith(repoRoot)
+                ? absolute.slice(repoRoot.length + 1)
                 : absolute;
             const sandbox = createPageSandbox(workDir, index);
             for (const action of extractActions(file, readFileSync(absolute, 'utf8'), spellings)) {
@@ -520,11 +566,11 @@ export function runDocInvocations(root, section) {
                     continue;
                 }
                 scanned += 1;
-                const { tokens, faithful } = realizeArguments(action.tail, sandbox, context);
+                const { tokens, faithful } = realizeArguments(action.tail, sandbox, contexts[action.binary]);
                 // The sandbox root is the working directory and stdin is closed: a
                 // relative write lands inside the sandbox, and a command that reads
                 // stdin sees an empty stream and returns at once.
-                const result = spawnSync(process.execPath, [entry, ...tokens], {
+                const result = spawnSync(process.execPath, [binaries[action.binary].entry, ...tokens], {
                     cwd: sandbox.root,
                     encoding: 'utf8',
                     input: '',
@@ -556,7 +602,14 @@ export function runDocInvocations(root, section) {
                     record('the binary crashed');
                     continue;
                 }
-                if (result.status === section.usageExit) {
+                // A usage exit is a mistyped command or a flag that stopped existing,
+                // except where the page declares it. One binary can spend the same
+                // code on a configuration it refused to read, and a page teaching a
+                // reader to recognise that refusal is making a claim about it like
+                // any other. The declaration is what separates the two, so an
+                // undeclared usage exit still fails every invocation.
+                if (result.status === section.usageExit &&
+                    action.expectExit !== section.usageExit) {
                     record('usage error: the documented command or flag does not exist');
                     continue;
                 }
@@ -580,7 +633,13 @@ export function runDocInvocations(root, section) {
                 if (action.expectStderr === null)
                     continue;
                 compared += 1;
-                const written = result.stderr.split('\n');
+                // A page documenting a rejection quotes stderr, and a page
+                // documenting a command that worked quotes stdout. A run that wrote
+                // nothing to stderr is the second case, so the block is compared
+                // against what the run actually said rather than against an empty
+                // stream. Declaring the exit code is still what attaches a block at
+                // all, so no page acquires a comparison it did not ask for.
+                const written = (result.stderr.trim() === '' ? result.stdout : result.stderr).split('\n');
                 const documented = action.expectStderr;
                 const overElided = documented.findIndex((line) => line.split(ELISION).length - 1 > section.elisionLimit);
                 if (overElided !== -1) {
@@ -612,7 +671,7 @@ export function runDocInvocations(root, section) {
     // no commands at all. The pages are there and the binary is there, so the one
     // thing left to name is the spelling list.
     if (scanned === 0) {
-        throw codedError(DOC_PATH_ERROR, `no fenced command in ${files.length} page(s) matched any spelling the "doc-invocations" section declares (${section.binary.spellings.join(', ')}); a gate that extracted nothing reports a pass over nothing`);
+        throw codedError(DOC_PATH_ERROR, `no fenced command in ${files.length} page(s) matched any spelling the "doc-invocations" section declares (${spellings.map((spelling) => spelling.text).join(', ')}); a gate that extracted nothing reports a pass over nothing`);
     }
     return { failures, scanned, judged, compared, pages: files.length };
 }

package/dist/gates/dependency-direction.js

@@ -473,6 +473,20 @@ function scanFile(file, source, files, graph, violations) {
             const openIndex = tokens[i + 1]?.kind === SyntaxKind.QuestionDotToken ? i + 2 : i + 1;
             if (tokens[openIndex]?.kind !== SyntaxKind.OpenParenToken)
                 continue;
+            // The site this arm exists for is the free identifier `require` called
+            // with a specifier. Two shapes share its tokens and are ordinary
+            // JavaScript: a member call, `sandbox.require('fs')`, where the token
+            // before is `.` or `?.`, and a method named require, `require(name) {`
+            // in an object literal or a class, where the token after the matching
+            // `)` is `{`. A call's own `)` is never followed by `{`, so
+            // `if (require('x')) {` still reads as the call it is. A consumer
+            // renaming a mock to get past this arm is a gate teaching the wrong lesson.
+            const before = tokens[i - 1]?.kind;
+            if (before === SyntaxKind.DotToken ||
+                before === SyntaxKind.QuestionDotToken ||
+                isMethodDefinition(tokens, i, openIndex)) {
+                continue;
+            }
             if (graph.commonjs === 'forbid') {
                 violations.push({
                     file,
@@ -545,6 +559,122 @@ function scanFile(file, source, files, graph, violations) {
  * against `graph` and returns every violation found, in no particular cross-file
  * order.
  */
+/**
+ * A modifier or generator marker that can sit between a declaration boundary
+ * and the member name it modifies: `async`, `static`, `get`, `set`,
+ * `readonly`, an access modifier, or `*`. Skipped when walking backward from
+ * `require` to find what actually introduces it.
+ */
+const MEMBER_MODIFIERS = new Set([
+    SyntaxKind.AsyncKeyword,
+    SyntaxKind.StaticKeyword,
+    SyntaxKind.GetKeyword,
+    SyntaxKind.SetKeyword,
+    SyntaxKind.ReadonlyKeyword,
+    SyntaxKind.PrivateKeyword,
+    SyntaxKind.PublicKeyword,
+    SyntaxKind.ProtectedKeyword,
+    SyntaxKind.AsteriskToken,
+]);
+/**
+ * Whether `require`, immediately followed by a parameter list and then `{`,
+ * actually sits where a name is declared rather than where a call's result is
+ * followed by an unrelated block statement: `const mod = require('x')` and a
+ * stray `{` on the next line tokenize exactly like a method body, and only
+ * what precedes `require` tells them apart. Skips the modifiers above, then
+ * requires the next token to be the opening brace of the object, class or
+ * interface `require` is the first member of, a `,` or `;` separating it from
+ * a prior member, a `case`/`default` label, `function` for a function
+ * declaration, or the start of the file. Anything else -- `=`, `return`, or
+ * any other token an expression puts before a call -- means this is a call.
+ *
+ * A `;` or `}` immediately before `require` stays undecidable this way: both
+ * a prior class member and a prior unrelated statement end on one, and
+ * telling them apart needs knowing what kind of block `require` sits in,
+ * which a token stream does not carry. Rare enough, and specific enough to
+ * write on purpose, that it is left as the one shape this arm still misses.
+ */
+function isDeclarationPosition(tokens, requireIndex) {
+    let j = requireIndex - 1;
+    while (j >= 0 && MEMBER_MODIFIERS.has(tokens[j]?.kind))
+        j -= 1;
+    if (j < 0)
+        return true;
+    const kind = tokens[j]?.kind;
+    return (kind === SyntaxKind.OpenBraceToken ||
+        kind === SyntaxKind.CommaToken ||
+        kind === SyntaxKind.SemicolonToken ||
+        kind === SyntaxKind.CaseKeyword ||
+        kind === SyntaxKind.DefaultKeyword ||
+        kind === SyntaxKind.FunctionKeyword);
+}
+/**
+ * Whether the parenthesised list opening at `openIndex` is a parameter list,
+ * which is to say `require` here is a method or a signature and never a call.
+ * A `{` straight after the matching `)` defers to `isDeclarationPosition`. A
+ * `:` after it is either a return-type annotation, a ternary's else, or a
+ * `case`/`default` label, and the three are told apart by looking back from
+ * `require` at bracket depth zero: a ternary has its `?` before the call and
+ * inside the same expression, a `case`/`default` label has the keyword
+ * immediately before the call and nothing between them, and a member
+ * declaration has none of those before its own `{`, `,` or `;` -- or before
+ * reaching an enclosing `(`, `[` or `{` with nothing still open inside it,
+ * which is the same boundary one level up. An unclosed list reads as a call,
+ * which is what this arm already did with a stream it could not place.
+ */
+function isMethodDefinition(tokens, requireIndex, openIndex) {
+    let depth = 0;
+    let closeIndex = -1;
+    for (let j = openIndex; j < tokens.length; j++) {
+        const kind = tokens[j]?.kind;
+        if (kind === SyntaxKind.OpenParenToken)
+            depth += 1;
+        else if (kind === SyntaxKind.CloseParenToken) {
+            depth -= 1;
+            if (depth === 0) {
+                closeIndex = j;
+                break;
+            }
+        }
+    }
+    if (closeIndex === -1)
+        return false;
+    const after = tokens[closeIndex + 1]?.kind;
+    if (after === SyntaxKind.OpenBraceToken) {
+        return isDeclarationPosition(tokens, requireIndex);
+    }
+    if (after !== SyntaxKind.ColonToken)
+        return false;
+    depth = 0;
+    for (let j = requireIndex - 1; j >= 0; j--) {
+        const kind = tokens[j]?.kind;
+        if (kind === SyntaxKind.CloseParenToken ||
+            kind === SyntaxKind.CloseBracketToken ||
+            kind === SyntaxKind.CloseBraceToken) {
+            depth += 1;
+            continue;
+        }
+        if (kind === SyntaxKind.OpenParenToken ||
+            kind === SyntaxKind.OpenBracketToken ||
+            kind === SyntaxKind.OpenBraceToken) {
+            if (depth === 0)
+                return true;
+            depth -= 1;
+            continue;
+        }
+        if (depth > 0)
+            continue;
+        if (kind === SyntaxKind.QuestionToken)
+            return false;
+        if (kind === SyntaxKind.CaseKeyword || kind === SyntaxKind.DefaultKeyword) {
+            return false;
+        }
+        if (kind === SyntaxKind.SemicolonToken || kind === SyntaxKind.CommaToken) {
+            return true;
+        }
+    }
+    return true;
+}
 export function scanSources(files, graph) {
     const fileSet = new Set(files.keys());
     const violations = [];

package/dist/gates/gate-config.js

@@ -279,6 +279,16 @@ const LicencesSection = z
  * `node_modules`, which is what keeps the pre-install path open for the two
  * gates that run before `npm ci`.
  */
+const DocumentedBinary = z
+    .strictObject({
+    entry: RelativePath.describe('The built entry point every documented command is run against. It is a precondition: a gate that skipped when it was absent would exit 0 having executed nothing.'),
+    spellings: z
+        .array(NonEmpty)
+        .min(1)
+        .describe('How your documentation writes the command, as the literal text a reader types. Each is matched at the start of a fenced line, with whitespace or end of line after it, so a sample of your own diagnostic output is left alone.'),
+    installedPrefix: NonEmpty.optional().describe('The path prefix a page uses for a file inside the installed package, such as "node_modules/your-package/". Mapping it away is what lets those examples be checked against real bytes.'),
+})
+    .describe('One binary a documented command line runs.');
 const DocInvocationsSection = z
     .strictObject({
     pages: z
@@ -286,15 +296,8 @@ const DocInvocationsSection = z
         .min(1)
         .describe("The pages whose fenced commands are run, as files or directories to walk. Naming the configuration's own directory is refused: every fenced command in a whole repository is more than this gate should run."),
     binary: z
-        .strictObject({
-        entry: RelativePath.describe('The built entry point every documented command is run against. It is a precondition: a gate that skipped when it was absent would exit 0 having executed nothing.'),
-        spellings: z
-            .array(NonEmpty)
-            .min(1)
-            .describe('How your documentation writes the command, as the literal text a reader types. Each is matched at the start of a fenced line, with whitespace or end of line after it, so a sample of your own diagnostic output is left alone.'),
-        installedPrefix: NonEmpty.optional().describe('The path prefix a page uses for a file inside the installed package, such as "node_modules/your-package/". Mapping it away is what lets those examples be checked against real bytes.'),
-    })
-        .describe('What a documented command line runs.'),
+        .union([DocumentedBinary, z.array(DocumentedBinary).min(1)])
+        .describe("What a documented command line runs. One object for a package that publishes one binary, or an array for a package that publishes several, each carrying its own entry, spellings and installedPrefix. Every spelling across every binary is matched against the same page and the longest one wins, so a short spelling belonging to one binary never claims a line that opens with a longer spelling belonging to another. Each binary's entry is its own precondition and the refusal names which one is missing. An empty array is refused, since a gate with no spelling to match extracts nothing and reports a pass over nothing."),
     sampleInput: RelativePath.describe('A file that stands in for an input only a reader has, such as `<path>`. A run that needed one is judged for usage errors and crashes and no more.'),
     usageExit: z
         .int()

package/dist/gates/lineage-ownership.js

@@ -32,39 +32,36 @@
 // appear in this file or anything it imports.
 import { z } from 'zod';
 import { discoverEntries, RelativePath, RelativePrefix, ScannedPathList, } from './scanned-paths.js';
+import { loadTypeScriptScanner, TYPESCRIPT_UNAVAILABLE, } from './typescript-scanner.js';
 /** The gate needs `typescript` and could not resolve it. */
-export const TYPESCRIPT_UNAVAILABLE = 'EVAL_QUALITY_TYPESCRIPT_UNAVAILABLE';
-const codedError = (code, message) => Object.assign(new Error(message), { code });
-const importTokenScanner = async () => {
+export { TYPESCRIPT_UNAVAILABLE };
+const importTokenScanner = (gate) => async () => {
     // `token-scan.ts` imports `typescript/unstable/ast` at its own top level, so
-    // this is the one place the dependency is reached and the one place its
-    // absence can be turned into a sentence.
-    const [ast, scan] = await Promise.all([
-        import('typescript/unstable/ast'),
-        import('./token-scan.js'),
-    ]);
+    // the loader runs first and its refusal is the one a consumer reads; the
+    // import of `token-scan.ts` follows only once the scanner is known to be there.
+    const ast = await loadTypeScriptScanner(gate);
+    const scan = await import('./token-scan.js');
     return {
         scanTokens: scan.scanTokens,
         computeLineStarts: scan.computeLineStarts,
         lineOf: scan.lineOf,
+        // `loadTypeScriptScanner` types `SyntaxKind` as a generic
+        // `Readonly<Record<string, number>>`, since its own shape check indexes
+        // it by whichever member name each of the three scanner modules reads.
+        // That check has already run and passed by the time this line executes,
+        // so every member this file reads off `Syntax` is verified present; the
+        // double cast is regaining the precise type the runtime check earned.
         syntax: ast.SyntaxKind,
     };
 };
 /**
- * The tokenizer, or a refusal naming the dependency and the gate that needs it.
- * `load` is injectable so the refusal has a test that does not require
- * uninstalling anything.
+ * The tokenizer, or the refusal `loadTypeScriptScanner` throws naming the
+ * dependency and the gate that needs it. `load` is injectable so a test can
+ * exercise that refusal without uninstalling anything the test runner itself
+ * needs.
  */
-export async function loadTokenScanner(gate, load = importTokenScanner) {
-    try {
-        return await load();
-    }
-    catch (error) {
-        if (error.code !== 'ERR_MODULE_NOT_FOUND') {
-            throw error;
-        }
-        throw codedError(TYPESCRIPT_UNAVAILABLE, `the ${gate} gate reads your source through the typescript package's own scanner, and typescript did not resolve. Install typescript to run this gate; every other gate needs nothing beyond this package.`);
-    }
+export async function loadTokenScanner(gate, load = importTokenScanner(gate)) {
+    return load();
 }
 const Identifier = z
     .string()

package/dist/gates/typescript-scanner.js

@@ -0,0 +1,181 @@
+// The one place the two source-scanning gates reach TypeScript.
+//
+// The scanner lives at `typescript/unstable/ast`, a subpath whose own name says
+// it may move, and it exists from TypeScript 7.0: the 5.x line has no such
+// subpath and the 7.x main entry exports no scanner. The optional peer range
+// says `>=5.7.0` and stays that wide on purpose. npm resolves an optional peer
+// that is present, so a range of `>=7` would turn `npm install` red for every
+// consumer with TypeScript 5 in its tree and no interest in these two gates.
+// The version fact lives here instead, spoken at the one moment it matters:
+// when a consumer runs one of the two gates.
+//
+// Three refusals, each its own because the repair is different. The package
+// is absent; the package is a version with no such subpath; the subpath is
+// there and lacks a member this build reads. The third is the quiet one: a
+// renamed enum member reads as `undefined`, `token.kind === undefined` never
+// matches, and the rule it guarded switches off with every gate green. So every
+// `SyntaxKind` member the three scanner modules read is listed below, and
+// `tests/architecture/typescript-scanner.test.ts` derives the same list from
+// their sources, so the list is not a copy a hand maintains.
+//
+// Run by `node` directly: Node's type stripping erases types only, so no
+// TypeScript enum, namespace, parameter property, or non-type re-export may
+// appear in this file or anything it imports, or the gate fails at load.
+/** `error.code` on every refusal here; the binary maps it to the usage exit. */
+export const TYPESCRIPT_UNAVAILABLE = 'EVAL_QUALITY_TYPESCRIPT_UNAVAILABLE';
+/** Where the scanner is read from, and the first TypeScript that ships it. */
+export const SCANNER_SUBPATH = 'typescript/unstable/ast';
+export const SCANNER_SHIPS_FROM = '7.0.0';
+/** Every `SyntaxKind` member `token-scan.ts`, `dependency-direction.ts` and `lineage-ownership.ts` read. */
+export const REQUIRED_SYNTAX_KINDS = [
+    'AmpersandToken',
+    'AnyKeyword',
+    'AsKeyword',
+    'AsteriskToken',
+    'AsyncKeyword',
+    'AwaitKeyword',
+    'BarToken',
+    'BigIntKeyword',
+    'BigIntLiteral',
+    'BooleanKeyword',
+    'CaseKeyword',
+    'CatchKeyword',
+    'ClassKeyword',
+    'CloseBraceToken',
+    'CloseBracketToken',
+    'CloseParenToken',
+    'ColonToken',
+    'CommaToken',
+    'ConstKeyword',
+    'DefaultKeyword',
+    'DotToken',
+    'EndOfFile',
+    'EqualsGreaterThanToken',
+    'EqualsToken',
+    'ExclamationToken',
+    'ExportKeyword',
+    'ExtendsKeyword',
+    'FalseKeyword',
+    'FirstAssignment',
+    'ForKeyword',
+    'FromKeyword',
+    'FunctionKeyword',
+    'GetKeyword',
+    'Identifier',
+    'IfKeyword',
+    'ImportKeyword',
+    'InterfaceKeyword',
+    'LastAssignment',
+    'LessThanToken',
+    'LetKeyword',
+    'MinusMinusToken',
+    'NeverKeyword',
+    'NewKeyword',
+    'NoSubstitutionTemplateLiteral',
+    'NullKeyword',
+    'NumberKeyword',
+    'NumericLiteral',
+    'ObjectKeyword',
+    'OpenBraceToken',
+    'OpenBracketToken',
+    'OpenParenToken',
+    'PlusPlusToken',
+    'PrivateKeyword',
+    'ProtectedKeyword',
+    'PublicKeyword',
+    'QuestionDotToken',
+    'QuestionToken',
+    'ReadonlyKeyword',
+    'RegularExpressionLiteral',
+    'RequireKeyword',
+    'ReturnKeyword',
+    'SemicolonToken',
+    'SetKeyword',
+    'SlashEqualsToken',
+    'SlashToken',
+    'StaticKeyword',
+    'StringKeyword',
+    'StringLiteral',
+    'SuperKeyword',
+    'SymbolKeyword',
+    'TemplateHead',
+    'TemplateTail',
+    'ThisKeyword',
+    'TrueKeyword',
+    'TypeKeyword',
+    'UndefinedKeyword',
+    'UnknownKeyword',
+    'VarKeyword',
+    'VoidKeyword',
+    'WhileKeyword',
+    'WithKeyword',
+];
+const codedError = (message) => Object.assign(new Error(message), { code: TYPESCRIPT_UNAVAILABLE });
+const defaultLoad = () => import('typescript/unstable/ast');
+// `typescript/package.json` is on the package's export map, so the version is
+// read from the install itself. A read that fails names no version rather than
+// failing the refusal that wanted it.
+const defaultVersion = async () => {
+    try {
+        const manifest = (await import('typescript/package.json', {
+            with: { type: 'json' },
+        }));
+        const version = manifest.default?.version;
+        return typeof version === 'string' ? version : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** The sentence for an absent package, shared so both gates say the same thing. */
+export const absentMessage = (gate) => `the ${gate} gate reads your source with the TypeScript scanner, and the optional peer dependency "typescript" is not installed here. Install it (npm install --save-dev typescript), or drop the "${gate}" section from your configuration to stop invoking this gate. Only the dependency-direction and field-ownership gates need it.`;
+/** Whether `error` carries `code` as a `NodeJS.ErrnoException` would, without assuming `error` is an object at all. */
+export const isCode = (error, code) => error !== null &&
+    typeof error === 'object' &&
+    error.code === code;
+/**
+ * The scanner module, or a refusal carrying `TYPESCRIPT_UNAVAILABLE` that names
+ * the gate, the installed version and the repair. Anything that is not one of
+ * the three refusals is rethrown unchanged.
+ *
+ * `load` and `readVersion` are injectable so each refusal has a case that
+ * uninstalls nothing.
+ */
+export async function loadTypeScriptScanner(gate, load = defaultLoad, readVersion = defaultVersion) {
+    let loaded;
+    try {
+        loaded = await load();
+    }
+    catch (error) {
+        if (isCode(error, 'ERR_MODULE_NOT_FOUND')) {
+            throw codedError(absentMessage(gate));
+        }
+        if (isCode(error, 'ERR_PACKAGE_PATH_NOT_EXPORTED')) {
+            const version = (await readVersion().catch(() => null)) ?? 'an unknown version';
+            throw codedError(`the ${gate} gate reads your source with the TypeScript scanner at ${SCANNER_SUBPATH}, and typescript ${version} carries no such subpath; TypeScript ships it from ${SCANNER_SHIPS_FROM}. Install typescript 7 to run this gate, or drop the "${gate}" section from your configuration to stop invoking it.`);
+        }
+        throw error;
+    }
+    const module = (loaded ?? {});
+    const missing = [];
+    if (typeof module.createScanner !== 'function')
+        missing.push('createScanner');
+    if (typeof module.computeLineStarts !== 'function') {
+        missing.push('computeLineStarts');
+    }
+    const kinds = module.SyntaxKind;
+    if (kinds === null || typeof kinds !== 'object') {
+        missing.push('SyntaxKind');
+    }
+    else {
+        for (const name of REQUIRED_SYNTAX_KINDS) {
+            if (typeof kinds[name] !== 'number')
+                missing.push(`SyntaxKind.${name}`);
+        }
+    }
+    if (missing.length > 0) {
+        const version = (await readVersion().catch(() => null)) ?? 'an unknown version';
+        throw codedError(`the ${gate} gate reads ${missing.join(', ')} from ${SCANNER_SUBPATH}, and typescript ${version} ships it without ${missing.length === 1 ? 'that name' : 'those names'}; a member this gate cannot find would switch a rule off silently, so it refuses instead. This build reads the scanner TypeScript 7 ships.`);
+    }
+    return module;
+}

package/dist/index.d.ts

@@ -4,12 +4,14 @@ export type { EvalContract } from './core/schemas/eval-contract.ts';
 export { EVAL_CONTRACT_SCHEMA_VERSION } from './core/schemas/eval-contract.ts';
 export type { EvaluatorConfiguration } from './core/schemas/evaluator-configuration.ts';
 export { EVALUATOR_CONFIGURATION_SCHEMA_VERSION } from './core/schemas/evaluator-configuration.ts';
-export type { EvidenceArtifact } from './core/schemas/evidence-artifact.ts';
+export type { CheckResolutionValue, EvidenceArtifact, } from './core/schemas/evidence-artifact.ts';
 export { EVIDENCE_ARTIFACT_SCHEMA_VERSION } from './core/schemas/evidence-artifact.ts';
+export type { Expression, Operand } from './core/schemas/expression.ts';
 export type { IsolationManifest } from './core/schemas/isolation-manifest.ts';
 export { ISOLATION_MANIFEST_SCHEMA_VERSION } from './core/schemas/isolation-manifest.ts';
 export type { PreflightCheck, PreflightVerdict, } from './core/schemas/preflight-verdict.ts';
 export { PREFLIGHT_VERDICT_SCHEMA_VERSION } from './core/schemas/preflight-verdict.ts';
+export type { JsonValue } from './core/schemas/primitives.ts';
 export type { PrivateArtifactManifest } from './core/schemas/private-artifact-manifest.ts';
 export { PRIVATE_ARTIFACT_MANIFEST_SCHEMA_VERSION } from './core/schemas/private-artifact-manifest.ts';
 export type { Probe } from './core/schemas/probe.ts';
@@ -19,7 +21,7 @@ export type { ScoringPolicy } from './core/schemas/scoring-policy.ts';
 export { SCORING_POLICY_SCHEMA_VERSION } from './core/schemas/scoring-policy.ts';
 export type { SealedEvaluatorBrief } from './core/schemas/sealed-evaluator-brief.ts';
 export { SEALED_EVALUATOR_BRIEF_SCHEMA_VERSION } from './core/schemas/sealed-evaluator-brief.ts';
-export type { SealedRunRecord } from './core/schemas/sealed-run-record.ts';
+export type { Observation, SealedRunRecord, } from './core/schemas/sealed-run-record.ts';
 export { SEALED_RUN_RECORD_SCHEMA_VERSION } from './core/schemas/sealed-run-record.ts';
 export type { FixtureReset, ManifestationWitness, SensitivityWitness, SensitivityWitnessLeg, WitnessChannel, WitnessInputs, } from './core/schemas/sensitivity-witness.ts';
-export declare const VERSION = "3.2.0";
+export declare const VERSION = "3.4.0";

package/dist/index.js

@@ -38,4 +38,4 @@ export { PROBE_SCHEMA_VERSION } from './core/schemas/probe.js';
 export { SCORING_POLICY_SCHEMA_VERSION } from './core/schemas/scoring-policy.js';
 export { SEALED_EVALUATOR_BRIEF_SCHEMA_VERSION } from './core/schemas/sealed-evaluator-brief.js';
 export { SEALED_RUN_RECORD_SCHEMA_VERSION } from './core/schemas/sealed-run-record.js';
-export const VERSION = '3.2.0';
+export const VERSION = '3.4.0';

package/dist/ports/environment-probe-port.d.ts

@@ -56,12 +56,12 @@ export declare const probeParsers: {
         }>;
         pathTemplate: import("zod").ZodString;
         channels: import("zod").ZodObject<{
-            path: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodType<import("../core/schemas/primitives.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../core/schemas/primitives.ts").JsonValue, unknown>>>;
-            query: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodType<import("../core/schemas/primitives.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../core/schemas/primitives.ts").JsonValue, unknown>>>;
+            path: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodType<import("../index.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../index.ts").JsonValue, unknown>>>;
+            query: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodType<import("../index.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../index.ts").JsonValue, unknown>>>;
             header: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>;
             body: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
                 kind: import("zod").ZodLiteral<"json">;
-                value: import("zod").ZodType<import("../core/schemas/primitives.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../core/schemas/primitives.ts").JsonValue, unknown>>;
+                value: import("zod").ZodType<import("../index.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../index.ts").JsonValue, unknown>>;
             }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
                 kind: import("zod").ZodLiteral<"absent">;
             }, import("zod/v4/core").$strict>], "kind">;
@@ -74,12 +74,12 @@ export declare const probeParsers: {
         executable: import("zod").ZodString;
         subcommandPath: import("zod").ZodArray<import("zod").ZodString>;
         channels: import("zod").ZodObject<{
-            argument: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodType<import("../core/schemas/primitives.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../core/schemas/primitives.ts").JsonValue, unknown>>>;
-            option: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodType<import("../core/schemas/primitives.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../core/schemas/primitives.ts").JsonValue, unknown>>>;
+            argument: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodType<import("../index.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../index.ts").JsonValue, unknown>>>;
+            option: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodType<import("../index.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../index.ts").JsonValue, unknown>>>;
             environment: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>;
             stdin: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
                 kind: import("zod").ZodLiteral<"json">;
-                value: import("zod").ZodType<import("../core/schemas/primitives.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../core/schemas/primitives.ts").JsonValue, unknown>>;
+                value: import("zod").ZodType<import("../index.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../index.ts").JsonValue, unknown>>;
             }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
                 kind: import("zod").ZodLiteral<"text">;
                 value: import("zod").ZodString;
@@ -94,7 +94,7 @@ export declare const probeParsers: {
         kind: import("zod").ZodLiteral<"mcp">;
         toolName: import("zod").ZodString;
         channels: import("zod").ZodObject<{
-            arguments: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodType<import("../core/schemas/primitives.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../core/schemas/primitives.ts").JsonValue, unknown>>>;
+            arguments: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodType<import("../index.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../index.ts").JsonValue, unknown>>>;
         }, import("zod/v4/core").$strict>;
     }, import("zod/v4/core").$strict>], "kind">;
     readonly response: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
@@ -106,7 +106,7 @@ export declare const probeParsers: {
         headers: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>;
         body: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
             kind: import("zod").ZodLiteral<"json">;
-            value: import("zod").ZodType<import("../core/schemas/primitives.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../core/schemas/primitives.ts").JsonValue, unknown>>;
+            value: import("zod").ZodType<import("../index.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../index.ts").JsonValue, unknown>>;
         }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
             kind: import("zod").ZodLiteral<"text">;
             value: import("zod").ZodString;
@@ -121,7 +121,7 @@ export declare const probeParsers: {
         exitCode: import("zod").ZodInt;
         stdout: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
             kind: import("zod").ZodLiteral<"json">;
-            value: import("zod").ZodType<import("../core/schemas/primitives.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../core/schemas/primitives.ts").JsonValue, unknown>>;
+            value: import("zod").ZodType<import("../index.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../index.ts").JsonValue, unknown>>;
         }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
             kind: import("zod").ZodLiteral<"text">;
             value: import("zod").ZodString;
@@ -130,7 +130,7 @@ export declare const probeParsers: {
         }, import("zod/v4/core").$strict>], "kind">;
         stderr: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
             kind: import("zod").ZodLiteral<"json">;
-            value: import("zod").ZodType<import("../core/schemas/primitives.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../core/schemas/primitives.ts").JsonValue, unknown>>;
+            value: import("zod").ZodType<import("../index.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../index.ts").JsonValue, unknown>>;
         }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
             kind: import("zod").ZodLiteral<"text">;
             value: import("zod").ZodString;
@@ -139,7 +139,7 @@ export declare const probeParsers: {
         }, import("zod/v4/core").$strict>], "kind">;
         artifacts: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
             kind: import("zod").ZodLiteral<"json">;
-            value: import("zod").ZodType<import("../core/schemas/primitives.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../core/schemas/primitives.ts").JsonValue, unknown>>;
+            value: import("zod").ZodType<import("../index.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../index.ts").JsonValue, unknown>>;
         }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
             kind: import("zod").ZodLiteral<"text">;
             value: import("zod").ZodString;
@@ -154,7 +154,7 @@ export declare const probeParsers: {
         isError: import("zod").ZodBoolean;
         result: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
             kind: import("zod").ZodLiteral<"json">;
-            value: import("zod").ZodType<import("../core/schemas/primitives.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../core/schemas/primitives.ts").JsonValue, unknown>>;
+            value: import("zod").ZodType<import("../index.ts").JsonValue, unknown, import("zod/v4/core").$ZodTypeInternals<import("../index.ts").JsonValue, unknown>>;
         }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
             kind: import("zod").ZodLiteral<"text">;
             value: import("zod").ZodString;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eval-quality",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Compile disciplined Behavioral Evaluation Contracts and score their ability to catch known defects.",
   "author": "Murat Ozcan",
   "license": "Apache-2.0",
@@ -76,6 +76,7 @@
     "check:doc-invocations": "node scripts/gates-cli.ts doc-invocations",
     "check:doc-counts": "node scripts/gates-cli.ts doc-counts",
     "check:doc-claims": "node scripts/gates-cli.ts doc-claims",
+    "hash:doc-claim-subject": "node scripts/hash-doc-claim-subject.ts",
     "lint:spine": "python3 scripts/spine-lint/lint_spine.py --registry-ad 5 --workspace-root . --fail-on high",
     "test:spine-lint": "uv run --with pytest pytest scripts/spine-lint/tests -q",
     "build:shareable": "node scripts/build-shareable.mjs",
@@ -101,6 +102,8 @@
     "check:corpus": "node scripts/check-dev-corpus.ts",
     "generate:worked-example": "node scripts/generate-worked-example.ts",
     "check:worked-example": "node scripts/check-worked-example.ts",
+    "generate:tutorials": "node scripts/generate-tutorials.ts",
+    "check:tutorials": "node scripts/check-tutorials.ts",
     "generate:version": "node scripts/generate-version.ts",
     "check:version": "node scripts/check-version.ts",
     "generate:lockfile-age-cache": "node scripts/generate-lockfile-age-cache.ts",
@@ -117,7 +120,7 @@
     "release:major": "gh workflow run publish.yml --ref main -f bump=major",
     "release:prepare": "node scripts/release-prepare.mjs",
     "release:publish": "gh workflow run publish.yml --ref main -f bump=none",
-    "validate": "npm run build && npm run typecheck && npm run lint && npm run check:docs && npm run check:doc-invocations && npm run check:shareable && npm run lint:spine && npm run check:vectors && npm run check:schemas && npm run check:ad5-registry && npm run check:ad28-registry && npm run check:ad31-table && npm run check:ad33-table && npm run check:ad21-table && npm run check:layers && npm run check:lineage && npm run check:boundary && npm run check:corpus && npm run check:doc-counts && npm run check:doc-claims && npm run check:worked-example && npm run check:version && npm run check:lockfile-age && npm run check:licences && npm run test:coverage",
+    "validate": "npm run build && npm run typecheck && npm run lint && npm run check:docs && npm run check:doc-invocations && npm run check:shareable && npm run lint:spine && npm run check:vectors && npm run check:schemas && npm run check:ad5-registry && npm run check:ad28-registry && npm run check:ad31-table && npm run check:ad33-table && npm run check:ad21-table && npm run check:layers && npm run check:lineage && npm run check:boundary && npm run check:corpus && npm run check:doc-counts && npm run check:doc-claims && npm run check:worked-example && npm run check:tutorials && npm run check:version && npm run check:lockfile-age && npm run check:licences && npm run test:coverage",
     "prepack": "npm run clean && npm run build",
     "prepublishOnly": "node scripts/assert-publish-authorized.mjs"
   },