eval-quality 0.1.0

package/dist/application/preflight.d.ts

@@ -0,0 +1,27 @@
+import { EvalContract } from '../core/schemas/eval-contract.ts';
+import { ProbeObservation } from '../core/schemas/port-messages.ts';
+import { PreflightVerdict } from '../core/schemas/preflight-verdict.ts';
+import { Probe } from '../core/schemas/probe.ts';
+import { type EnvironmentProbePort } from '../ports/environment-probe-port.ts';
+import { type DiagnosticSink } from './diagnostics.ts';
+export type RunPreflightOptions = {
+    readonly contract: EvalContract;
+    readonly probes: readonly Probe[];
+    readonly runId: string;
+    readonly port: EnvironmentProbePort;
+    readonly signal: AbortSignal;
+    readonly sink?: DiagnosticSink;
+};
+export type PreflightFromObservationsOptions = {
+    readonly contract: EvalContract;
+    readonly probes: readonly Probe[];
+    readonly runId: string;
+    readonly observations: readonly ProbeObservation[];
+    readonly sink?: DiagnosticSink;
+};
+export declare function runPreflight(options: RunPreflightOptions): Promise<PreflightVerdict>;
+/**
+ * The same pre-flight verdict for a caller who probed by some other means:
+ * plans, skips the awaiting, reduces over observations it is handed.
+ */
+export declare function preflightFromObservations(options: PreflightFromObservationsOptions): PreflightVerdict;

package/dist/application/preflight.js

@@ -0,0 +1,131 @@
+/**
+ * The one place a pre-flight probe is awaited (AD-34: `application/` is the
+ * only layer that awaits). Parses its inputs, plans, issues every leg through
+ * the environment-probe port in plan order, reduces, and parses the verdict.
+ *
+ * `preflightFromObservations` is the same verdict for a caller that probed by
+ * some other means: it plans, skips the awaiting, and reduces over the
+ * observations it is handed. Both entry points land on one `reducePreflight`
+ * and return one `PreflightVerdict`.
+ *
+ * No decision logic lives here: every branch is a parse, an await, or a rethrow.
+ * A failed pre-flight is a verdict and a failed probe is a fault, so a
+ * `RuntimeFault` from a leg propagates.
+ */
+import { freezeArtifact } from '../core/lineage/freeze.js';
+import { planPreflight } from '../core/preflight/plan.js';
+import { reducePreflight } from '../core/preflight/reduce.js';
+import { EvalContract } from '../core/schemas/eval-contract.js';
+import { RuntimeFault } from '../core/schemas/faults.js';
+import { ProbeObservation } from '../core/schemas/port-messages.js';
+import { PreflightVerdict } from '../core/schemas/preflight-verdict.js';
+import { Probe } from '../core/schemas/probe.js';
+import { probeParsers, } from '../ports/environment-probe-port.js';
+import { emit } from './diagnostics.js';
+import { invokePort } from './invoke-port.js';
+/** Artifacts are validated in both directions (AD-28), probes included. */
+function parseProbes(input) {
+    const parsed = Probe.array().safeParse(input);
+    if (!parsed.success) {
+        throw new RuntimeFault('schema-parse-failure', 'Probe', 'input does not conform to the Probe schema', { cause: parsed.error });
+    }
+    return parsed.data;
+}
+function parseContract(input) {
+    const parsed = EvalContract.safeParse(input);
+    if (!parsed.success) {
+        throw new RuntimeFault('schema-parse-failure', 'EvalContract', 'input does not conform to the EvalContract schema', { cause: parsed.error });
+    }
+    return parsed.data;
+}
+function parseObservations(input) {
+    const parsed = ProbeObservation.array().safeParse(input);
+    if (!parsed.success) {
+        throw new RuntimeFault('schema-parse-failure', 'ProbeObservation', 'input does not conform to the ProbeObservation schema', { cause: parsed.error });
+    }
+    return parsed.data;
+}
+/**
+ * Frozen again after the outbound parse: `safeParse` returns a fresh object,
+ * so the core stage's freeze does not survive boundary validation.
+ */
+function parseVerdict(verdict) {
+    const parsed = PreflightVerdict.safeParse(verdict);
+    if (!parsed.success) {
+        throw new RuntimeFault('schema-parse-failure', 'PreflightVerdict', 'the reduced verdict does not conform to the PreflightVerdict schema', { cause: parsed.error });
+    }
+    return freezeArtifact(parsed.data);
+}
+const plannedLine = (legId) => `leg "${legId}": planned`;
+const observedLine = (legId) => `leg "${legId}": observed`;
+const closingLine = (legCount, passed) => `reduced ${legCount} leg(s): ${passed ? 'passed' : 'failed'}`;
+export async function runPreflight(options) {
+    const { runId, port, signal, sink } = options;
+    const parsedContract = parseContract(options.contract);
+    const parsedProbes = parseProbes(options.probes);
+    const plan = planPreflight({
+        contract: parsedContract,
+        probes: parsedProbes,
+        runId,
+    });
+    // Sequential: the control legs are ordered by construction, and a parallel
+    // run would reset the fixture underneath another operation's witness.
+    const observations = [];
+    for (const leg of plan.legs) {
+        emit(sink, { runId, stage: 'preflight', message: plannedLine(leg.legId) });
+        observations.push(await invokePort({
+            request: leg.request,
+            requestParser: probeParsers.request,
+            responseParser: probeParsers.response,
+            port: port.probe,
+            signal,
+            requestPath: 'ProbeRequest',
+            responsePath: 'ProbeObservation',
+        }));
+        // `invokePort` either returns an observation or throws, so every leg
+        // reaching here was answered and the unobserved line is unreachable.
+        emit(sink, { runId, stage: 'preflight', message: observedLine(leg.legId) });
+    }
+    const verdict = parseVerdict(reducePreflight(plan, { observations }));
+    emit(sink, {
+        runId,
+        stage: 'preflight',
+        message: closingLine(plan.legs.length, verdict.passed),
+    });
+    return verdict;
+}
+/**
+ * The same pre-flight verdict for a caller who probed by some other means:
+ * plans, skips the awaiting, reduces over observations it is handed.
+ */
+export function preflightFromObservations(options) {
+    const { runId, sink } = options;
+    const parsedContract = parseContract(options.contract);
+    const parsedProbes = parseProbes(options.probes);
+    const parsedObservations = parseObservations(options.observations);
+    const plan = planPreflight({
+        contract: parsedContract,
+        probes: parsedProbes,
+        runId,
+    });
+    // `reducePreflight` binds an observation to a leg by `probeId`, so the
+    // emitted lines are keyed the same way rather than by array position.
+    const answered = new Set(parsedObservations.map((observation) => observation.probeId));
+    for (const leg of plan.legs) {
+        emit(sink, { runId, stage: 'preflight', message: plannedLine(leg.legId) });
+        emit(sink, {
+            runId,
+            stage: 'preflight',
+            message: answered.has(leg.legId)
+                ? observedLine(leg.legId)
+                : `leg "${leg.legId}": no observation`,
+        });
+    }
+    const verdict = parseVerdict(reducePreflight(plan, { observations: parsedObservations }));
+    emit(sink, {
+        runId,
+        stage: 'preflight',
+        message: closingLine(plan.legs.length, verdict.passed),
+    });
+    return verdict;
+}

package/dist/application/seal.d.ts

@@ -0,0 +1,4 @@
+import type { SealedEvaluatorBrief } from '../core/schemas/sealed-evaluator-brief.ts';
+export declare function seal(input: unknown, options?: {
+    readonly strict?: boolean;
+}): SealedEvaluatorBrief;

package/dist/application/seal.js

@@ -0,0 +1,28 @@
+/**
+ * The synchronous application boundary for the seal stage. Compiles, then
+ * seals: `compile` and `seal` are one stage for a caller, and sealing an
+ * uncompiled contract emits a brief from declarations no discipline check has
+ * seen.
+ *
+ * Sequencing two pure core stages is not decision logic; `preflight.ts`
+ * already sequences plan and reduce. `StructuralFailure` and `RuntimeFault`
+ * propagate. `core/seal` throws `TypeError` on preconditions compilation does
+ * not cover, and this boundary converts those so an untyped throw never
+ * reaches a caller.
+ */
+import { RuntimeFault } from '../core/schemas/faults.js';
+import { seal as sealContract } from '../core/seal/seal.js';
+import { compile } from './compile.js';
+export function seal(input, options) {
+    const contract = compile(input, options);
+    try {
+        // `core/seal` validates the assembled brief and freezes it on the way
+        // out, so AD-28's outbound check is already done and is not repeated.
+        return sealContract(contract);
+    }
+    catch (error) {
+        if (!(error instanceof TypeError))
+            throw error;
+        throw new RuntimeFault('schema-parse-failure', 'EvalContract', `the contract compiles but cannot be sealed: ${error.message}`, { cause: error });
+    }
+}

package/dist/application/serialize.d.ts

@@ -0,0 +1,6 @@
+/**
+ * RFC 8785 canonical bytes plus a trailing newline, as text. Strip the newline
+ * and the remaining bytes are what `digestArtifact` hashes, so a caller can
+ * write a file and compute its digest from the same string.
+ */
+export declare function serializeArtifact(artifact: unknown, artifactPath: string): string;

package/dist/application/serialize.js

@@ -0,0 +1,9 @@
+import { canonicalize } from '../core/canonical/canonicalize.js';
+/**
+ * RFC 8785 canonical bytes plus a trailing newline, as text. Strip the newline
+ * and the remaining bytes are what `digestArtifact` hashes, so a caller can
+ * write a file and compute its digest from the same string.
+ */
+export function serializeArtifact(artifact, artifactPath) {
+    return `${new TextDecoder().decode(canonicalize(artifact, artifactPath))}\n`;
+}

package/dist/cli/arguments.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The command line, parsed. Pure and synchronous over an `argv` array: no
+ * filesystem, no `process`, no environment, no prompt and no terminal check,
+ * because every command is non-interactive. Paths are carried through exactly
+ * as given and resolved by the caller.
+ */
+export type Command = 'compile' | 'seal' | 'preflight';
+/** The four input flags. Closed, so a usage error can name the flag set. */
+export type InputKey = 'in' | 'contract' | 'probes' | 'observations';
+export type ParsedInvocation = {
+    readonly kind: 'help';
+    readonly command: Command | null;
+} | {
+    readonly kind: 'version';
+} | {
+    readonly kind: 'usage-error';
+    readonly message: string;
+} | {
+    readonly kind: 'run';
+    readonly command: Command;
+    readonly inputs: Readonly<Partial<Record<InputKey, string>>>;
+    readonly out: string | null;
+    readonly runId: string | null;
+    readonly strictInputs: boolean;
+    readonly strict: boolean;
+};
+export declare const COMMANDS: readonly Command[];
+export declare function parseArguments(argv: readonly string[]): ParsedInvocation;

package/dist/cli/arguments.js

@@ -0,0 +1,167 @@
+/**
+ * The command line, parsed. Pure and synchronous over an `argv` array: no
+ * filesystem, no `process`, no environment, no prompt and no terminal check,
+ * because every command is non-interactive. Paths are carried through exactly
+ * as given and resolved by the caller.
+ */
+export const COMMANDS = ['compile', 'seal', 'preflight'];
+/** The input flags each command takes, and which of them it requires. */
+const INPUT_KEYS = {
+    compile: ['in'],
+    seal: ['in'],
+    preflight: ['contract', 'probes', 'observations'],
+};
+/** `--strict-inputs` is AD-4's compile mode; `preflight` has no compile step. */
+const TAKES_STRICT_INPUTS = {
+    compile: true,
+    seal: true,
+    preflight: false,
+};
+/** `--run-id` names the run a verdict is minted for, which only `preflight` does. */
+const TAKES_RUN_ID = {
+    compile: false,
+    seal: false,
+    preflight: true,
+};
+const STDIN = '-';
+const isCommand = (token) => COMMANDS.includes(token);
+const usageError = (message) => ({
+    kind: 'usage-error',
+    message,
+});
+/** `--flag=value`, split on the first `=` so a value may contain one. */
+function splitFlag(token) {
+    const equals = token.indexOf('=');
+    if (equals === -1)
+        return { flag: token, inline: null };
+    return { flag: token.slice(0, equals), inline: token.slice(equals + 1) };
+}
+export function parseArguments(argv) {
+    const first = argv[0];
+    if (first === undefined) {
+        return usageError(`no command given; expected one of ${COMMANDS.join(', ')}`);
+    }
+    if (first === '--help' || first === '-h' || first === 'help') {
+        const target = argv[1];
+        if (target === undefined)
+            return { kind: 'help', command: null };
+        if (isCommand(target))
+            return { kind: 'help', command: target };
+        return usageError(`unknown command "${target}"; expected one of ${COMMANDS.join(', ')}`);
+    }
+    if (first === '--version' || first === '-V')
+        return { kind: 'version' };
+    if (!isCommand(first)) {
+        return usageError(`unknown command "${first}"; expected one of ${COMMANDS.join(', ')}`);
+    }
+    return parseCommand(first, argv.slice(1));
+}
+function parseCommand(command, rest) {
+    const valueFlags = new Map();
+    for (const key of INPUT_KEYS[command])
+        valueFlags.set(`--${key}`, key);
+    valueFlags.set('--out', 'out');
+    if (TAKES_RUN_ID[command])
+        valueFlags.set('--run-id', 'run-id');
+    const inputs = {};
+    const seen = new Map();
+    let out = null;
+    let runId = null;
+    let strictInputs = true;
+    let strict = false;
+    const takeValue = (flag, inline, index) => {
+        if (inline !== null) {
+            if (inline === '')
+                return usageError(`${flag} was given an empty value`);
+            return { value: inline, next: index + 1 };
+        }
+        const value = rest[index + 1];
+        if (value === undefined)
+            return usageError(`${flag} requires a value`);
+        if (value === '')
+            return usageError(`${flag} was given an empty value`);
+        // A flag-shaped token is the next flag, so the space form treats it as a
+        // missing value. Bare `-` stays legal because it names stdin, and a path
+        // beginning with `-` is what the equals form is for.
+        if (value.length > 1 && value.startsWith('-')) {
+            return usageError(`${flag} requires a value, but the next token is "${value}"; use ${flag}=${value} for a value that begins with "-"`);
+        }
+        return { value, next: index + 2 };
+    };
+    for (let index = 0; index < rest.length;) {
+        const token = rest[index];
+        if (token === '--') {
+            const positional = rest[index + 1];
+            if (positional === undefined)
+                break;
+            return usageError(`${command} takes no positional argument, but got "${positional}"`);
+        }
+        if (token === '--help' || token === '-h') {
+            return { kind: 'help', command };
+        }
+        const { flag, inline } = splitFlag(token);
+        const target = valueFlags.get(flag);
+        if (target !== undefined) {
+            const taken = takeValue(flag, inline, index);
+            if ('kind' in taken)
+                return taken;
+            const previous = seen.get(flag);
+            if (previous !== undefined && previous !== taken.value) {
+                return usageError(`${flag} given twice with different values, "${previous}" and "${taken.value}"`);
+            }
+            seen.set(flag, taken.value);
+            if (target === 'out')
+                out = taken.value;
+            else if (target === 'run-id')
+                runId = taken.value;
+            else
+                inputs[target] = taken.value;
+            index = taken.next;
+            continue;
+        }
+        if (inline !== null) {
+            return usageError(`unknown flag "${flag}" in "${token}"`);
+        }
+        if (flag === '--strict') {
+            strict = true;
+            index += 1;
+            continue;
+        }
+        if (TAKES_STRICT_INPUTS[command] && flag === '--strict-inputs') {
+            strictInputs = true;
+            index += 1;
+            continue;
+        }
+        if (TAKES_STRICT_INPUTS[command] && flag === '--no-strict-inputs') {
+            strictInputs = false;
+            index += 1;
+            continue;
+        }
+        return usageError(`unknown flag "${token}" for ${command}`);
+    }
+    const missing = INPUT_KEYS[command]
+        .filter((key) => key !== 'in' && inputs[key] === undefined)
+        .map((key) => `--${key}`);
+    if (TAKES_RUN_ID[command] && runId === null)
+        missing.push('--run-id');
+    // `PreflightVerdict.runId` is `z.string().min(1)`, which a run of spaces
+    // satisfies. It then renders as blank in every diagnostic line and names
+    // nothing a reader can correlate, so the argument surface refuses it here
+    // rather than the schema refusing what it declares legal.
+    if (runId !== null && runId.trim() === '') {
+        return usageError('--run-id must contain a non-whitespace character');
+    }
+    if (missing.length > 0) {
+        return usageError(`${command} requires ${missing.join(', ')}`);
+    }
+    // One stdin cannot serve two readers, so at most one input may be `-`.
+    const fromStdin = INPUT_KEYS[command].filter((key) => inputs[key] === STDIN);
+    if (fromStdin.length > 1) {
+        const flags = fromStdin.map((key) => `--${key}`);
+        const named = flags.length === 2
+            ? `${flags.join(' and ')} both name`
+            : `${flags.join(', ')} all name`;
+        return usageError(`only one input may read stdin, but ${named} "-"`);
+    }
+    return { kind: 'run', command, inputs, out, runId, strictInputs, strict };
+}

package/dist/cli/exit-codes.d.ts

@@ -0,0 +1,36 @@
+/**
+ * AD-21's exit codes, as a total function over what a command produced.
+ *
+ * Zero, one, and two are the verdict range. A command that produced no verdict
+ * never takes one or two, so a CI runner reading a two knows a verdict said
+ * FAIL and not that a compile failed. Zero stays plain success for every
+ * outcome, verdict or not.
+ */
+import type { Verdict } from '../application/index.ts';
+export declare const EXIT_OK = 0;
+export declare const EXIT_CONCERNS_PROMOTED = 1;
+export declare const EXIT_FAIL = 2;
+export declare const EXIT_INVALID = 3;
+export declare const EXIT_STRUCTURAL_FAILURE = 4;
+export declare const EXIT_FAULT = 5;
+/** sysexits.h EX_USAGE. Outside the verdict range and outside AD-21's codes. */
+export declare const EXIT_USAGE = 64;
+export type CommandOutcome = {
+    readonly kind: 'artifact';
+} | {
+    readonly kind: 'preflight';
+    readonly passed: boolean;
+} | {
+    readonly kind: 'verdict';
+    readonly verdict: Verdict;
+    readonly evidenceConditionsOnly: boolean;
+} | {
+    readonly kind: 'structural-failure';
+} | {
+    readonly kind: 'fault';
+} | {
+    readonly kind: 'usage-error';
+};
+export declare function exitCodeFor(outcome: CommandOutcome, options: {
+    readonly strict: boolean;
+}): number;

package/dist/cli/exit-codes.js

@@ -0,0 +1,39 @@
+export const EXIT_OK = 0;
+export const EXIT_CONCERNS_PROMOTED = 1;
+export const EXIT_FAIL = 2;
+export const EXIT_INVALID = 3;
+export const EXIT_STRUCTURAL_FAILURE = 4;
+export const EXIT_FAULT = 5;
+/** sysexits.h EX_USAGE. Outside the verdict range and outside AD-21's codes. */
+export const EXIT_USAGE = 64;
+function verdictExit(outcome, strict) {
+    if (outcome.verdict === 'FAIL')
+        return EXIT_FAIL;
+    // `--strict` promotes CONCERNS to one, "except a CONCERNS whose only firing
+    // conditions are evidence conditions, which `--strict` never promotes"
+    // (AD-21). A thinner measurement is not a claim about the system.
+    if (outcome.verdict === 'CONCERNS' &&
+        strict &&
+        !outcome.evidenceConditionsOnly) {
+        return EXIT_CONCERNS_PROMOTED;
+    }
+    return EXIT_OK;
+}
+export function exitCodeFor(outcome, options) {
+    switch (outcome.kind) {
+        case 'artifact':
+            return EXIT_OK;
+        // A failed pre-flight invalidates the run (AD-10). Invalid is 3; a 2
+        // would read as a scored FAIL verdict.
+        case 'preflight':
+            return outcome.passed ? EXIT_OK : EXIT_INVALID;
+        case 'verdict':
+            return verdictExit(outcome, options.strict);
+        case 'structural-failure':
+            return EXIT_STRUCTURAL_FAILURE;
+        case 'fault':
+            return EXIT_FAULT;
+        case 'usage-error':
+            return EXIT_USAGE;
+    }
+}

package/dist/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv: readonly string[]): Promise<void>;

package/dist/cli/main.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * The `bin` entry: the only file in the package that reads `process.argv`,
+ * reads stdin, or writes to a stream. It holds no command logic, so its whole
+ * body is building a `RunEnvironment` and turning an outcome into
+ * `process.exitCode`.
+ *
+ * `process.exit` is called nowhere. Exiting truncates a pending stdout write,
+ * and an artifact larger than a pipe buffer is the ordinary case here.
+ */
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import process from 'node:process';
+import { parseArguments } from './arguments.js';
+import { exitCodeFor } from './exit-codes.js';
+import { renderError, renderUsage } from './render.js';
+import { run } from './run.js';
+/**
+ * A path the invocation named that the filesystem will not give us. The caller
+ * chose it, so it is a usage error and takes 64, which sits outside every code
+ * AD-21 assigns.
+ */
+const PATH_ERROR_CODES = new Set([
+    'ENOENT',
+    'EACCES',
+    'EISDIR',
+    'ENOTDIR',
+    'EPERM',
+    'ELOOP',
+    'ENAMETOOLONG',
+]);
+function pathErrorOf(error) {
+    if (!(error instanceof Error))
+        return null;
+    const candidate = error;
+    if (candidate.code === undefined)
+        return null;
+    return PATH_ERROR_CODES.has(candidate.code) ? candidate : null;
+}
+/**
+ * The binary's own version. `cli/` may not import the root barrel, where
+ * `VERSION` lives, so the manifest is read beside the built file: `dist/cli/`
+ * and `src/cli/` are both two levels under the package root.
+ */
+async function packageVersion() {
+    const manifestUrl = new URL('../../package.json', import.meta.url);
+    const manifest = JSON.parse(await readFile(manifestUrl, 'utf8'));
+    return manifest.version;
+}
+/** One read to end: a canonical JSON document has no incremental meaning. */
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf8');
+}
+function environmentOf(version) {
+    return {
+        readInput: async (source) => source === null ? await readStdin() : await readFile(source, 'utf8'),
+        writeArtifact: async (path, body) => {
+            // A named `--out` that does not exist yet is an ordinary way to
+            // invoke this, and failing with a raw ENOENT dressed as a usage
+            // error helps nobody. Creating an output directory mutates no
+            // input.
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, body, 'utf8');
+        },
+        writeOut: (body) => {
+            process.stdout.write(body);
+        },
+        writeDiagnostic: (line) => {
+            process.stderr.write(`${line}\n`);
+        },
+        // `resolve` on an already-absolute path still folds `.`, `..`, and a
+        // doubled separator, which is the whole point: returning an absolute
+        // path verbatim let `/d/./a.json` and `/d/a.json` name one file and pass
+        // the collision check, and the command then overwrote its own input.
+        resolvePath: (path) => resolve(path),
+        joinPath: (directory, name) => join(directory, name),
+        sameFile: async (left, right) => {
+            try {
+                const [a, b] = await Promise.all([stat(left), stat(right)]);
+                return a.dev === b.dev && a.ino === b.ino;
+            }
+            catch {
+                // One of them is not there, so they cannot be one file. The
+                // ordinary case: an output path that does not exist yet.
+                return false;
+            }
+        },
+        version,
+    };
+}
+/**
+ * Returns nothing and communicates through `process.exitCode`, so there is one
+ * exit mechanism. The top-level call below is what makes the file executable:
+ * without it the `bin` target loads and does nothing.
+ */
+const writeStderr = (line) => {
+    process.stderr.write(`${line}\n`);
+};
+/**
+ * Every escape from `run` becomes an outcome, so every exit this binary takes
+ * is one `exitCodeFor` assigned. Letting one through would exit 1, and AD-21
+ * bars a command that produced no verdict from landing in the verdict range.
+ *
+ * `run` still rethrows a defect in our own code, and the stack still reaches
+ * stderr: what changes is the number beside it, which becomes the fault code
+ * rather than Node's default 1.
+ */
+function failureOutcome(error) {
+    const pathError = pathErrorOf(error);
+    if (pathError !== null) {
+        writeStderr(renderUsage(`${pathError.syscall ?? 'open'} "${pathError.path ?? '(unknown path)'}": ${pathError.code}`));
+        return { kind: 'usage-error' };
+    }
+    const errno = error;
+    if (error instanceof Error && typeof errno.code === 'string') {
+        // An I/O failure outside the path allowlist: a full disk, a read-only
+        // mount, an exhausted descriptor table. The caller cannot fix it by
+        // changing the command line, so it is a fault and takes five.
+        writeStderr(renderError(error));
+        return { kind: 'fault' };
+    }
+    writeStderr(error instanceof Error ? (error.stack ?? error.message) : String(error));
+    return { kind: 'fault' };
+}
+export async function main(argv) {
+    try {
+        const invocation = parseArguments(argv);
+        const environment = environmentOf(await packageVersion());
+        const { outcome } = await run(invocation, environment);
+        process.exitCode = exitCodeFor(outcome, {
+            strict: invocation.kind === 'run' && invocation.strict,
+        });
+    }
+    catch (error) {
+        // `strict` promotes a CONCERNS and nothing else, and no failure outcome
+        // is a verdict, so the value here cannot change the code.
+        process.exitCode = exitCodeFor(failureOutcome(error), { strict: false });
+    }
+}
+await main(process.argv.slice(2));

package/dist/cli/render.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The four shapes the binary writes, and the exit-code table two documents
+ * share. Every line the CLI emits is produced here, so a format change is one
+ * file.
+ */
+import { type Diagnostic } from '../application/index.ts';
+/**
+ * Delegates to `serializeArtifact`; the canonical bytes are not re-derived
+ * here, so the text written to stdout is the text `digestArtifact` hashes.
+ */
+export declare function renderArtifact(artifact: unknown, artifactPath: string): string;
+/** `eval-quality: <stage>: <runId>: <message>` */
+export declare function renderDiagnostic(diagnostic: Diagnostic): string;
+/**
+ * `eval-quality: <code>: <artifactPath>: <detail>` for either error class.
+ * Anything else falls back to `String(error)`, which is what a defect in our
+ * own code looks like from outside.
+ */
+export declare function renderError(error: unknown): string;
+/**
+ * AD-21's seven exit codes, one line each. The `--help` output and the README
+ * table are this text, so the two cannot drift.
+ */
+export declare const EXIT_CODE_TABLE = "Exit codes (AD-21):\n  0   success, and every verdict other than FAIL or a promoted CONCERNS\n  1   CONCERNS promoted by --strict\n  2   FAIL\n  3   invalid: a pre-flight verdict that did not pass\n  4   structural failure\n  5   runtime fault\n  64  usage error\n\n  1 and 2 report a scored verdict. Scoring ships in a later release, so no\n  command here reaches either yet, and --strict changes no code this binary\n  produces.";
+/** `eval-quality: usage: <message>` */
+export declare function renderUsage(message: string): string;