polydeukes 0.6.0 → 0.7.1

package/dist/covenant/bash-line.js

@@ -0,0 +1,566 @@
+/**
+ * Bash command-line tokenizer + mutation-target extraction core.
+ *
+ * Pure functions only — zero I/O, spawn, or logging. A hand-rolled single-pass character
+ * scanner recognizes quote state (`'`, `"`, `$'…'`, `\`), control operators
+ * (`;` `&&` `||` `|` `&`), redirect operators (`>` `>>` `>|` `<` `2>` `&>`, attached `>f`),
+ * and marks tokens opaque when their static value is unknowable (command substitution,
+ * parameter expansion, globs).
+ *
+ * Fail-closed: no input ever throws. A construct the scanner cannot finish reading yields a
+ * partial result — the commands it did read, plus one `unread` span per failure; in
+ * {@link extractMutations} each span becomes one indeterminate entry. Block/allow
+ * decisions, read-only allowlists, and detection rules live in the judges that consume this.
+ */
+// Reinterpretation-boundary declaration, NOT a blocklist: a command whose first word is
+// one of these re-parses its string arguments in a nested shell, so the tokenizer honestly
+// reports indeterminate rather than parsing into it. Deliberately a small explicit set —
+// residual vectors such as indirect path computation are telemetry's concern in the judges,
+// not something this set should grow to chase.
+const NESTED_SHELL_COMMANDS = new Set(['eval', 'bash', 'sh', 'zsh']);
+/**
+ * True when `commandName` (a command word's basename) re-parses its string arguments in a
+ * nested shell — the reinterpretation boundary the tokenizer refuses to parse into. A judge
+ * can consult this to refuse to treat such a command as provably read-only.
+ */
+export function isNestedShellCommand(commandName) {
+    return NESTED_SHELL_COMMANDS.has(commandName);
+}
+// A `NAME=VALUE` assignment word, the prefix bash allows (any number of them) before the
+// command name.
+const ASSIGNMENT_WORD = /^[A-Za-z_][A-Za-z0-9_]*=/;
+/**
+ * The word that names the command, skipping any leading assignments — undefined when the
+ * command is nothing but assignments.
+ *
+ * Read at the nested-shell boundary only. There an unskipped assignment hides `bash` behind
+ * `FOO=1` and the line passes with confidence; for the read-only allowlist and precedent
+ * evidence the same miss is the conservative direction, so those keep reading `words[0]`.
+ */
+export function commandNameWord(command) {
+    let i = 0;
+    while (i < command.words.length && ASSIGNMENT_WORD.test(command.words[i].text))
+        i += 1;
+    return command.words[i];
+}
+/**
+ * True if a double-quoted fragment carries a dynamic construct whose value is unknowable.
+ * Only expansion and command substitution run inside double quotes — bash does not glob
+ * there, so `*` and `?` are opacity grounds outside quotes only.
+ */
+function quotedFragmentIsOpaque(fragment) {
+    return fragment.includes('$') || fragment.includes('`');
+}
+// Inside double quotes bash removes a backslash only before these characters; before
+// anything else it stays literal content (`"a\|b"` is the four bytes `a\|b`). The same
+// set decides the pairing, so an escaped `"` never closes the string.
+const DOUBLE_QUOTE_ESCAPES = new Set(['$', '`', '"', '\\']);
+/**
+ * Scan a double-quoted string whose opening `"` sits at `open`. Returns the content bash
+ * would pass and the index just past the closing quote; a string that never closes is read
+ * to the end of input and reported `closed: false`, never discarded.
+ */
+function scanDoubleQuoted(line, open) {
+    let text = '';
+    let i = open + 1;
+    while (i < line.length) {
+        const ch = line[i];
+        if (ch === '\\') {
+            const next = line[i + 1];
+            // `\`+newline is a line continuation inside double quotes too — both characters go.
+            if (next === '\n') {
+                i += 2;
+                continue;
+            }
+            if (next !== undefined && DOUBLE_QUOTE_ESCAPES.has(next)) {
+                text += next;
+                i += 2;
+                continue;
+            }
+            text += ch;
+            i += 1;
+            continue;
+        }
+        // Always `decoded`: the escape set above IS bash's whole rule inside double quotes, so
+        // the text is the bytes bash passes with nothing left untranslated.
+        if (ch === '"')
+            return { text, next: i + 1, closed: true, decoded: true };
+        text += ch;
+        i += 1;
+    }
+    return { text, next: line.length, closed: false, decoded: true };
+}
+// The ANSI-C escapes decoded inside `$'…'`. Deliberately not the whole table: an escape
+// that is not listed keeps its backslash, which is bash's own answer for one it does not
+// recognize (measured: `$'\q'` is the two bytes `\q`).
+const ANSI_C_ESCAPES = { n: '\n', t: '\t', "'": "'", '\\': '\\' };
+/**
+ * Scan an ANSI-C quoted string (`$'…'`) whose opening `'` sits at `open`. Returns the
+ * DECODED bytes and the index just past the closing quote; a string that never closes is
+ * read to the end of input and reported `closed: false`. Decoding is not cosmetic: the word
+ * text becomes written-content evidence downstream, so handing back the source spelling
+ * would record bytes bash never writes.
+ *
+ * An escape the table does not carry sets `decoded: false`, and the caller turns that into
+ * opacity. Keeping the source spelling and calling it decided would assert bytes bash never
+ * writes AS CONFIDENT EVIDENCE: `$'\x64ist'` would be filed as the literal `\x64ist` while
+ * bash writes `dist`, so a judge reading written content compares a string that never
+ * existed and upholds with no unjudgeable row. Completing the table is NOT the fix — the
+ * next unlisted escape reproduces it. Declining to claim knowledge is.
+ */
+function scanAnsiCQuoted(line, open) {
+    let text = '';
+    let decoded = true;
+    let i = open + 1;
+    while (i < line.length) {
+        const ch = line[i];
+        if (ch === '\\') {
+            const next = line[i + 1];
+            if (next === undefined)
+                break;
+            const replacement = ANSI_C_ESCAPES[next];
+            if (replacement === undefined)
+                decoded = false;
+            text += replacement ?? `\\${next}`;
+            i += 2;
+            continue;
+        }
+        if (ch === "'")
+            return { text, next: i + 1, closed: true, decoded };
+        text += ch;
+        i += 1;
+    }
+    return { text, next: line.length, closed: false, decoded };
+}
+/**
+ * Close a word on an unterminated quote whose opening character sits at `open`: the rest of
+ * the input is consumed, the word is opaque (its value depends on bytes the shell never
+ * received), and the raw span is reported. All three quote forms and the backtick branch of
+ * {@link scanWord} share this treatment.
+ */
+function unreadFrom(line, open, text) {
+    return {
+        word: { text, opaque: true },
+        next: line.length,
+        unread: { text: line.slice(open), reason: 'unclosed quote' },
+    };
+}
+/**
+ * Scan one word starting at `i`, honoring quotes and escapes. Returns the assembled word
+ * and the index just past it; an unclosed quote also returns the span it could not read.
+ */
+function scanWord(line, start) {
+    let text = '';
+    let opaque = false;
+    let i = start;
+    while (i < line.length) {
+        const ch = line[i];
+        // Whitespace and control/redirect operators terminate a word (outside quotes).
+        // Newlines count too: they separate commands, like `;`. Inside quotes they remain
+        // word content — the quote branches below consume across them.
+        if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r')
+            break;
+        if (ch === ';' || ch === '|' || ch === '&' || ch === '<' || ch === '>')
+            break;
+        if (ch === '\\') {
+            // Backslash escape: the next character is literal, never a separator or expansion.
+            const nextCh = line[i + 1];
+            if (nextCh === '\n') {
+                // `\`+newline is a shell line continuation: elide both characters (the word
+                // continues on the next physical line) rather than inserting a literal newline.
+                i += 2;
+                continue;
+            }
+            if (nextCh === '\r' && line[i + 2] === '\n') {
+                i += 3;
+                continue;
+            }
+            if (nextCh !== undefined) {
+                text += nextCh;
+                i += 2;
+                continue;
+            }
+            text += ch;
+            i += 1;
+            continue;
+        }
+        if (ch === "'") {
+            // Single quotes: literal content, no expansion — never contributes opacity.
+            const close = line.indexOf("'", i + 1);
+            // The dequoted content JOINS the word in progress rather than starting a new one:
+            // `pack'ages/…` is one shell word, and splitting it leaves two halves that each
+            // match nothing.
+            if (close === -1)
+                return unreadFrom(line, i, text + line.slice(i + 1));
+            text += line.slice(i + 1, close);
+            i = close + 1;
+            continue;
+        }
+        if (ch === '"') {
+            // Double quotes: expansions still apply, so scan for opacity within.
+            const quoted = scanDoubleQuoted(line, i);
+            if (!quoted.closed)
+                return unreadFrom(line, i, text + quoted.text);
+            if (quotedFragmentIsOpaque(quoted.text))
+                opaque = true;
+            text += quoted.text;
+            i = quoted.next;
+            continue;
+        }
+        if (ch === '$' && line[i + 1] === "'") {
+            // ANSI-C quoting: bash decodes the escapes and passes a string constant, so a fully
+            // decoded one is decided — an expansion it is not, and marking it opaque would be
+            // wrong. An escape this scanner cannot translate is the opposite case: the text is
+            // source spelling, not the bytes bash passes, so the word's value is NOT known and
+            // saying otherwise files evidence for a string that never existed.
+            const quoted = scanAnsiCQuoted(line, i + 1);
+            if (!quoted.closed)
+                return unreadFrom(line, i, text + quoted.text);
+            if (!quoted.decoded)
+                opaque = true;
+            text += quoted.text;
+            i = quoted.next;
+            continue;
+        }
+        if (ch === '$' && line[i + 1] === '(') {
+            // Command substitution `$(…)` with nesting — consume to the matching close paren. A
+            // substitution that never closes has swallowed the rest of the line into this one
+            // opaque word, so it reports an unread span exactly like an unterminated quote does:
+            // without it the line would answer "fully read" and file no unjudgeable entry.
+            const scan = matchParen(line, i + 1);
+            const chunk = line.slice(i, scan.end);
+            if (!scan.closed)
+                return unreadFrom(line, i, text + chunk);
+            text += chunk;
+            opaque = true;
+            i = scan.end;
+            continue;
+        }
+        if (ch === '`') {
+            // Backtick command substitution — consume to the closing backtick.
+            const close = line.indexOf('`', i + 1);
+            const end = close === -1 ? line.length : close + 1;
+            text += line.slice(i, end);
+            opaque = true;
+            i = end;
+            continue;
+        }
+        // Ordinary character. Mark opacity for parameter expansion / globs.
+        if (ch === '$' || ch === '*' || ch === '?')
+            opaque = true;
+        text += ch;
+        i += 1;
+    }
+    return { word: { text, opaque }, next: i };
+}
+function matchParen(line, open) {
+    let depth = 0;
+    for (let i = open; i < line.length; i++) {
+        const ch = line[i];
+        // Quoting suspends the count: a `)` inside `"[^)]+"` is regex content, not a close paren.
+        // Counting it ends the substitution early and every quote after it pairs one position off.
+        if (ch === '\\') {
+            i += 1;
+            continue;
+        }
+        if (ch === "'") {
+            const close = line.indexOf("'", i + 1);
+            if (close === -1)
+                return { end: line.length, closed: false };
+            i = close;
+            continue;
+        }
+        if (ch === '"') {
+            const quoted = scanDoubleQuoted(line, i);
+            if (!quoted.closed)
+                return { end: line.length, closed: false };
+            i = quoted.next - 1;
+            continue;
+        }
+        if (ch === '(')
+            depth += 1;
+        else if (ch === ')') {
+            depth -= 1;
+            if (depth === 0)
+                return { end: i + 1, closed: true };
+        }
+    }
+    // Ran off the end with the nesting still open — the same unread condition as an
+    // unterminated quote above, reported the same way.
+    return { end: line.length, closed: false };
+}
+/**
+ * Recognize a redirect operator at `i`; returns the operator text and its length, or null.
+ * Longest forms first within each family, and a single-digit fd prefix is folded into the
+ * operator (`2>`, `2>>`, `2>&`) — it is only an fd when it starts a token, matching bash.
+ */
+function scanRedirect(line, i) {
+    const three = line.slice(i, i + 3);
+    const two = three.slice(0, 2);
+    const ch = three[0];
+    // Fd prefix: bash folds ANY all-digit run immediately before `>` into the redirect
+    // (`12> f` sends fd 12 to f; tee receives no "12" operand), so the scan must too.
+    let digitEnd = i;
+    while (digitEnd < line.length && line[digitEnd] >= '0' && line[digitEnd] <= '9')
+        digitEnd += 1;
+    if (digitEnd > i && line[digitEnd] === '>') {
+        // `|` joins the tail set for `N>|`, which bash accepts as a write (`&>|` does not
+        // exist — a syntax error — so the `&>` family below is left alone).
+        const tail = line[digitEnd + 1];
+        const end = tail === '>' || tail === '&' || tail === '|' ? digitEnd + 2 : digitEnd + 1;
+        return { operator: line.slice(i, end), length: end - i };
+    }
+    if (three === '&>>')
+        return { operator: '&>>', length: 3 };
+    // `>|` truncates past `noclobber` — a write like `>`, and graded as one by the `>` it
+    // contains. `<&` is the read-direction twin of `>&` and closes an fd as `<&-`; without it
+    // the `-` never reads as a target and a valid line dies.
+    if (two === '>>' || two === '>|' || two === '&>' || two === '>&' || two === '<&') {
+        return { operator: two, length: 2 };
+    }
+    if (ch === '>')
+        return { operator: '>', length: 1 };
+    // Heredoc family, longest match first so `<<EOF` is never a lone `<` with an empty
+    // (fail-closing) target — `<<<` herestring, `<<-` tab-stripping heredoc, `<<`.
+    if (three === '<<<' || three === '<<-')
+        return { operator: three, length: 3 };
+    if (two === '<<')
+        return { operator: '<<', length: 2 };
+    if (ch === '<')
+        return { operator: '<', length: 1 };
+    return null;
+}
+/** Recognize a control operator at `i`; returns its text, or null. */
+function scanControl(line, i) {
+    const two = line.slice(i, i + 2);
+    if (two === '&&')
+        return '&&';
+    if (two === '||')
+        return '||';
+    const ch = line[i];
+    if (ch === ';' || ch === '|' || ch === '&')
+        return ch;
+    return null;
+}
+/**
+ * Consume queued heredoc bodies starting at `start` (just past the opening newline), in
+ * queue order. Body lines are data — never parsed as commands — until a line equals the
+ * delimiter (`<<-` allows leading tabs), or end of input (bash ends at EOF too). Each body
+ * is recorded on the command that declared it, in the bytes bash would write (tabs
+ * stripped under `<<-`, the `\r` of CRLF dropped), and its span in the original line is
+ * appended to `data`. Returns the index just past the last consumed body.
+ */
+function consumeHeredocBodies(line, start, pending, data) {
+    let i = start;
+    for (const heredoc of pending) {
+        let body = '';
+        const bodyStart = i;
+        // Where the body ends in the ORIGINAL line: the start of the delimiter line, or end of
+        // input when the delimiter never arrives. The delimiter line itself is not data.
+        let bodyEnd = i;
+        while (i < line.length) {
+            let end = line.indexOf('\n', i);
+            if (end === -1)
+                end = line.length;
+            let bodyLine = line.slice(i, end);
+            if (bodyLine.endsWith('\r'))
+                bodyLine = bodyLine.slice(0, -1);
+            const lineStart = i;
+            i = end + 1;
+            const stripped = heredoc.stripTabs ? bodyLine.replace(/^\t+/, '') : bodyLine;
+            if (stripped === heredoc.delimiter) {
+                bodyEnd = lineStart;
+                break;
+            }
+            body += `${stripped}\n`;
+            bodyEnd = Math.min(i, line.length);
+        }
+        // An unquoted delimiter leaves the body subject to expansion, so a `$(…)` or backtick
+        // in it is text bash executes — that body stays on the command line. An empty body
+        // has no bytes to delete and reports no span.
+        const expands = !heredoc.literal && /[$`]/.test(body);
+        if (bodyEnd > bodyStart && !expands)
+            data.push({ start: bodyStart, end: bodyEnd });
+        heredoc.owner.heredocs = [
+            ...(heredoc.owner.heredocs ?? []),
+            { body, literal: heredoc.literal },
+        ];
+    }
+    return i;
+}
+/**
+ * Tokenize one shell line into simple commands. Never throws, and never discards what it
+ * read: a construct it cannot finish reading is recorded as an `unread` span and the scan
+ * carries on.
+ */
+export function tokenizeCommandLine(line) {
+    const commands = [];
+    const unread = [];
+    const data = [];
+    let current = { words: [], redirects: [] };
+    // Heredoc delimiters queued on the current line, consumed in order at the next newline.
+    let pendingHeredocs = [];
+    let i = 0;
+    while (i < line.length) {
+        const ch = line[i];
+        if (ch === ' ' || ch === '\t') {
+            i += 1;
+            continue;
+        }
+        // Newline (or CRLF, or a lone CR — every scanWord terminator needs a consuming
+        // branch here, or the loop stalls) separates commands like `;`, then feeds any
+        // queued heredocs their body lines.
+        if (ch === '\n' || ch === '\r') {
+            commands.push(current);
+            current = { words: [], redirects: [] };
+            i += ch === '\r' && line[i + 1] === '\n' ? 2 : 1;
+            i = consumeHeredocBodies(line, i, pendingHeredocs, data);
+            pendingHeredocs = [];
+            continue;
+        }
+        // Process substitution `<(…)` / `>(…)` is a word-level filename token bash EXECUTES,
+        // not a redirect. Consume the whole `(…)` (matching nested parens) as one opaque word,
+        // scanned before the redirect operators would split on the leading `<`/`>` — otherwise
+        // the inner command's args leak as top-level words and a first-word allowlist could
+        // absolve them while the inner write runs.
+        if ((ch === '<' || ch === '>') && line[i + 1] === '(') {
+            const scan = matchParen(line, i + 1);
+            current.words.push({ text: line.slice(i, scan.end), opaque: true });
+            // A substitution that never closes swallowed the rest of the line into that one word,
+            // so the span is recorded rather than left to read as fully parsed.
+            if (!scan.closed)
+                unread.push({ text: line.slice(i), reason: 'unclosed quote' });
+            i = scan.end;
+            continue;
+        }
+        // Redirects are scanned before control operators so `&>` is not mistaken for a lone `&`.
+        const redirect = scanRedirect(line, i);
+        if (redirect !== null) {
+            let j = i + redirect.length;
+            while (line[j] === ' ' || line[j] === '\t')
+                j += 1;
+            // A spaced process substitution is the redirect's target (`echo x > >(wc -c)` is
+            // valid bash): consume the whole `(…)` as ONE opaque target, exactly as the attached
+            // word-level branch above does — scanning it as an ordinary word would leak the inner
+            // command's arguments to top level, where a first-word allowlist could absolve them.
+            if ((line[j] === '<' || line[j] === '>') && line[j + 1] === '(') {
+                const scan = matchParen(line, j + 1);
+                current.redirects.push({
+                    operator: redirect.operator,
+                    target: { text: line.slice(j, scan.end), opaque: true },
+                });
+                if (!scan.closed)
+                    unread.push({ text: line.slice(j), reason: 'unclosed quote' });
+                i = scan.end;
+                continue;
+            }
+            const scanned = scanWord(line, j);
+            if (scanned.unread !== undefined) {
+                // The target position ran into an unterminated quote: record the span and drop the
+                // redirect rather than claim a target nobody could read.
+                unread.push(scanned.unread);
+                i = scanned.next;
+                continue;
+            }
+            // A redirect with no target is a bash syntax error, but a LOCAL one: everything past
+            // the operator is still readable, so the span is recorded and the scan resumes there
+            // instead of throwing the line away.
+            if (scanned.word.text === '') {
+                unread.push({ text: line.slice(i, j), reason: 'missing redirect target' });
+                i = j;
+                continue;
+            }
+            if (redirect.operator === '<<' || redirect.operator === '<<-') {
+                // bash never expands a heredoc delimiter, so the body's end is decidable from the
+                // literal text even for `<<$D` — no fail-closed branch here.
+                pendingHeredocs.push({
+                    delimiter: scanned.word.text,
+                    stripTabs: redirect.operator === '<<-',
+                    // A quoting character ANYWHERE in the delimiter makes the body literal
+                    // (`<<E"O"F` and `<<\EOF` both stop expansion), and `scanWord` has already
+                    // removed those characters — so the raw span is the only place to read it.
+                    literal: /['"\\]/.test(line.slice(j, scanned.next)),
+                    owner: current,
+                });
+                i = scanned.next;
+                continue;
+            }
+            // Process substitution (`>(…)`/`<(…)`): the real path lives inside the substitution
+            // and is not statically knowable — an opaque target, never a confident path.
+            const target = scanned.word.text.startsWith('(')
+                ? { ...scanned.word, opaque: true }
+                : scanned.word;
+            // A herestring's target word is stdin data, not a command: bash passes it as written,
+            // quotes included, so the span covers the raw word. An opaque word (`$(…)`, a
+            // backtick, a bare `(`) is text bash expands first, so it stays on the command line.
+            if (redirect.operator === '<<<' && !target.opaque) {
+                data.push({ start: j, end: scanned.next });
+            }
+            current.redirects.push({ operator: redirect.operator, target });
+            i = scanned.next;
+            continue;
+        }
+        const control = scanControl(line, i);
+        if (control !== null) {
+            commands.push(current);
+            current = { words: [], redirects: [] };
+            i += control.length;
+            continue;
+        }
+        const scanned = scanWord(line, i);
+        if (scanned.unread !== undefined)
+            unread.push(scanned.unread);
+        current.words.push(scanned.word);
+        i = scanned.next;
+    }
+    commands.push(current);
+    // Drop empty commands produced by leading/trailing/adjacent operators (e.g. ";;").
+    const nonEmpty = commands.filter((c) => c.words.length > 0 || c.redirects.length > 0);
+    return { commands: nonEmpty, unread, data };
+}
+/**
+ * The executed text of a command line: the line with every `data` span deleted and nothing
+ * put in its place, so the words bash runs keep their spelling and line structure. Bytes
+ * the scanner could not finish reading are not data spans and stay as written.
+ */
+export function executedText(line) {
+    const { data } = tokenizeCommandLine(line);
+    let text = '';
+    let cut = 0;
+    for (const span of data) {
+        text += line.slice(cut, span.start);
+        cut = span.end;
+    }
+    return text + line.slice(cut);
+}
+/**
+ * Extract mutation targets from a shell line via injected rules. A simple command
+ * contributes an indeterminate entry when it is a nested-shell call OR contains any opaque
+ * word (in which case its rules are still applied, but an undecidable structure is present);
+ * each unread span yields one more. Never throws.
+ */
+export function extractMutations(line, rules) {
+    const result = tokenizeCommandLine(line);
+    const mutations = [];
+    const indeterminate = result.unread.map((span) => ({ reason: span.reason }));
+    for (const command of result.commands) {
+        // Nested shell = reinterpretation boundary: report indeterminate, do not parse inside.
+        // Matched by command basename (`/bin/sh` → `sh`), the same boundary shell-mod's
+        // allowlist clause uses, so a leading-path nested shell is not missed by a raw compare.
+        const name = commandNameWord(command);
+        const nameBasename = name !== undefined ? name.text.slice(name.text.lastIndexOf('/') + 1) : '';
+        if (name !== undefined && isNestedShellCommand(nameBasename)) {
+            indeterminate.push({ reason: `nested shell execution: ${name.text}` });
+            continue;
+        }
+        // An opaque word or redirect target (command substitution, parameter expansion, glob)
+        // has an unknowable value — honestly indeterminate rather than a confident pass.
+        if (command.words.some((w) => w.opaque) || command.redirects.some((r) => r.target.opaque)) {
+            indeterminate.push({ reason: 'opaque token' });
+        }
+        for (const rule of rules) {
+            mutations.push(...rule.detect(command));
+        }
+    }
+    return { mutations, indeterminate };
+}

package/dist/covenant/declaration-engine.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The declaration engine — `judge = relate ∘ extract` as a pure function of one `World`.
+ *
+ * `compileDeclaration` resolves a shape-validated declaration against the extract registry
+ * and answers either something judgeable or a config fault naming where the declaration is
+ * wrong; it never throws. `judgeDeclaration` then runs the extraction pipelines over a
+ * world value and evaluates the relations, answering a verdict. `witnessOpens` evaluates
+ * the witness block on its own, so a caller can let a satisfied condition stand after the
+ * verdict without re-reading it.
+ *
+ * The engine knows nothing but its two arguments: no files, no tools, no session. Whatever
+ * a host can express as named values in a `World` it can judge here.
+ */
+import type { AlgebraDeclaration, BinaryStep, ExtractStep, RelateEntry } from '@polydeukes/core';
+import { type ConfigFault, type World } from './extract-steps.ts';
+import { type Witness } from './relations.ts';
+export type { ConfigFault, Items, SessionSnapshot, World } from './extract-steps.ts';
+export { EXTRACT_STEPS, UNARY_STEP_NAMES } from './extract-steps.ts';
+export type { Witness } from './relations.ts';
+/** One entry's failure: the text a human reads, and the elements that produced it. */
+export type Break = {
+    readonly id: string;
+    readonly message: string;
+    readonly witnesses: readonly Witness[];
+};
+/**
+ * What one judgment answers. `not-applicable` separates the two ways a call goes unjudged —
+ * outside the declaration's scope, or missing a source the declaration lets pass.
+ */
+export type DeclarationVerdict = {
+    readonly kind: 'pass';
+} | {
+    readonly kind: 'broken';
+    readonly breaks: readonly Break[];
+} | {
+    readonly kind: 'not-applicable';
+    readonly reason: 'scope' | 'supply-pass';
+    readonly source?: string;
+} | {
+    readonly kind: 'supply-error';
+    readonly source: string;
+    readonly reason: string;
+};
+type CompiledPipeline = {
+    readonly name: string;
+    readonly paired: boolean;
+    readonly references: readonly string[];
+    readonly combinator?: BinaryStep;
+    readonly steps: readonly ExtractStep[];
+};
+type CompiledScope = {
+    readonly source: string;
+    readonly include: readonly RegExp[];
+    readonly exclude: readonly RegExp[];
+};
+/** The opaque result of compiling one declaration; only this module reads inside it. */
+export type CompiledDeclaration = {
+    readonly pipelines: ReadonlyMap<string, CompiledPipeline>;
+    readonly relate: readonly RelateEntry[];
+    readonly supply: Readonly<Record<string, 'error' | 'pass' | 'empty'>>;
+    readonly scope?: CompiledScope;
+    readonly witness?: {
+        readonly pipelines: ReadonlyMap<string, CompiledPipeline>;
+        readonly relate: readonly RelateEntry[];
+    };
+};
+/** `compileDeclaration` input — the shape-validated declaration to resolve. */
+export type CompileDeclarationSpec = {
+    declaration: AlgebraDeclaration;
+};
+/**
+ * Resolve a shape-validated declaration into something judgeable, or answer the first thing
+ * wrong with it: a step outside the registry, an argument outside a step's closed keys, an
+ * uncompilable expression, or a paired extraction where a single one belongs.
+ */
+export declare function compileDeclaration(spec: CompileDeclarationSpec): CompiledDeclaration | ConfigFault;
+/**
+ * Whether the declaration's scope admits this world — the routing question, asked without
+ * judging. A surface routes on the same predicate the judgment starts with, so a world it
+ * sends to the body is never one the body answers `not-applicable` for.
+ */
+export declare function scopeAdmits(compiled: CompiledDeclaration, world: World): boolean;
+/** `judgeDeclaration` input — one compiled declaration and the world it is judged against. */
+export type JudgeDeclarationSpec = {
+    compiled: CompiledDeclaration;
+    world: World;
+};
+/**
+ * Judge one compiled declaration against one world.
+ *
+ * The scope decides first, so a declaration that does not apply never reads a source it
+ * would have failed on. Then every relate entry is evaluated in declaration order, one
+ * break per entry that does not hold. The first supply failure ends the judgment: a
+ * partially read world produces no partial verdict.
+ */
+export declare function judgeDeclaration(spec: JudgeDeclarationSpec): DeclarationVerdict;
+/** `witnessOpens` input — one compiled declaration and the world its witness is asked about. */
+export type WitnessOpensSpec = {
+    compiled: CompiledDeclaration;
+    world: World;
+};
+/**
+ * Whether the declaration's witness condition holds for this world — the valve that stands
+ * after the verdict. It is closed unless every witness entry holds: a declaration with no
+ * witness block, a world outside the scope, and a source the witness cannot read all leave
+ * it shut, so the valve opens only on a condition that was actually met.
+ */
+export declare function witnessOpens(spec: WitnessOpensSpec): boolean;