polydeukes 0.6.1 → 0.7.1

package/README.ko.md

@@ -2,47 +2,33 @@
 
 [English](./README.md) · **한국어**
 
-Polydeukes는 우산 패키지입니다. 이 패키지 하나에 `pdks` 실행 파일, 설정 로더,
-커밋 표면 실행기, 세션 표면 실행기 서브패스, 동봉 스키마가 모두 포함돼 있습니다.
+Polydeukes는 우산 패키지입니다. 이 패키지 하나에 `pdks` 실행 파일, 판정기,
+두 표면의 조립 루트, 세션 표면 실행기 서브패스, 동봉 스키마가 모두 포함돼 있습니다.
 
 <a id="overview"></a>
 ## 개요
 
-공개 계약 심볼과 진입점은 다음과 같습니다.
+공개 계약 진입점은 다음과 같습니다.
 
-- `loadConfig`
-- `runCovenantCheck`
-- `ResolvedConfig`
-- `polydeukes/claude-code` → `runClaudeCodeHook`
+- `pdks` / `polydeukes` — 실행 파일
 - `polydeukes/schema.json`
+
+CLI 명령은 다음과 같습니다.
+
 - `pdks covenant check`
-- `pdks init claude-code`
-- `pdks init grok`
+- `pdks init`
+- `pdks-grok init` (`@polydeukes/adapter-grok`가 제공)
 - `pdks explain`
 - `pdks docs [topic]`
 
 <a id="public-symbols"></a>
 ## 공개 심볼
 
-```ts
-import { loadConfig, runCovenantCheck } from 'polydeukes';
-import { runClaudeCodeHook } from 'polydeukes/claude-code';
-```
-
-```ts
-function loadConfig(spec: { rootDir: string }): {
-  config: import('@polydeukes/core').ResolvedConfig;
-  configPath: string;
-};
-
-function runCovenantCheck(spec: {
-  repoRoot: string;
-  telemetryPath?: string;
-  covenantDist?: string;
-  ttyPrompt?: (prompt: string) => string | null;
-  domain?: unknown;
-}): Promise<{ exitCode: 0 | 2 }>;
-```
+없습니다. 이 패키지는 TypeScript 진입점을 공개하지 않습니다. `import 'polydeukes'`는
+`ERR_PACKAGE_PATH_NOT_EXPORTED`로 실패하고, 사용자가 닿는 것은 `pdks` 실행 파일과 동봉된
+스키마입니다. 표면은 판정기에 표준 입력으로 입력을 넘기고 종료 코드를 읽습니다. 에이전트
+어댑터의 훅이 하는 일이 바로 그것입니다. 이 패키지를 peer 의존으로 선언하고 import 없이
+실행 파일을 스폰합니다.
 
 <a id="see-also"></a>
 ## 같이 보기

package/README.md

@@ -2,48 +2,34 @@
 
 **English** · [한국어](./README.ko.md)
 
-Polydeukes is the umbrella package. Install this package; it ships the `pdks` bin, the config
-loader, the commit-surface runner, the session-surface runner subpath, and the bundled schema
+Polydeukes is the umbrella package. Install this package; it ships the `pdks` bin, the judge,
+both surfaces' composition roots, the session-surface runner subpath, and the bundled schema
 artifact.
 
 <a id="overview"></a>
 ## Overview
 
-Public contract symbols and entry points:
+Public contract entry points:
 
-- `loadConfig`
-- `runCovenantCheck`
-- `ResolvedConfig`
-- `polydeukes/claude-code` → `runClaudeCodeHook`
+- `pdks` / `polydeukes` — the bin
 - `polydeukes/schema.json`
+
+CLI commands:
+
 - `pdks covenant check`
-- `pdks init claude-code`
-- `pdks init grok`
+- `pdks init`
+- `pdks-grok init` (ships with `@polydeukes/adapter-grok`)
 - `pdks explain`
 - `pdks docs [topic]`
 
 <a id="public-symbols"></a>
 ## Public symbols
 
-```ts
-import { loadConfig, runCovenantCheck } from 'polydeukes';
-import { runClaudeCodeHook } from 'polydeukes/claude-code';
-```
-
-```ts
-function loadConfig(spec: { rootDir: string }): {
-  config: import('@polydeukes/core').ResolvedConfig;
-  configPath: string;
-};
-
-function runCovenantCheck(spec: {
-  repoRoot: string;
-  telemetryPath?: string;
-  covenantDist?: string;
-  ttyPrompt?: (prompt: string) => string | null;
-  domain?: unknown;
-}): Promise<{ exitCode: 0 | 2 }>;
-```
+None. This package publishes no TypeScript entry point: `import 'polydeukes'` fails with
+`ERR_PACKAGE_PATH_NOT_EXPORTED`, and what a consumer reaches is the `pdks` bin and the
+bundled schema. A surface hands the judge its input on stdin and reads the exit code, which
+is what an agent adapter's hook does — it takes this package as a peer dependency and
+spawns the bin rather than importing it.
 
 <a id="see-also"></a>
 ## See also

package/dist/baseline.d.ts

@@ -11,7 +11,7 @@
  * {@link snapshotBaseline} / {@link writeBaseline} / {@link readBaseline} are the I/O
  * points.
  */
-import type { TelemetryRecord } from '@polydeukes/core';
+import { type TelemetryRecord } from '@polydeukes/core';
 /** One hash per protected entry, keyed by the entry exactly as configured. */
 export type BaselineSnapshot = Record<string, string>;
 /**
@@ -80,3 +80,39 @@ export declare function writeBaseline(path: string, snapshot: BaselineSnapshot,
  * Observation is fail-open: the worst outcome is a missing datum, never a blocked call.
  */
 export declare function readBaseline(path: string): StoredBaseline | null;
+/** The label every post-hoc state comparison row carries. */
+export declare const BASELINE_LABEL = "baseline";
+/**
+ * Compare the protected entries' on-disk state against the stored baseline and record what
+ * moved with no judgment explaining it.
+ *
+ * Runs at hook call START, before this call's own judgment rows land, so the window it reads
+ * is the one the previous comparison left open. Returns the record count as of right now —
+ * where the NEXT window opens, which {@link updateBaseline} persists at call end.
+ *
+ * The comparison records, it never blocks: no row it writes and no failure it hits changes
+ * a verdict or an exit code, which is why every caller keeps it outside the judgment path.
+ */
+export declare function compareBaseline(spec: {
+    repoRoot: string;
+    telemetryPath: string;
+    entries: string[];
+}): void;
+/**
+ * Re-establish the baseline at hook call END.
+ *
+ * At call end rather than right after the comparison: refreshing at comparison time would
+ * miss whatever this call's own judged writes changed, leaving detection permanently one
+ * call behind.
+ *
+ * The cut is stamped HERE, beside the snapshot, not at the comparison that opened the call.
+ * Both describe the same instant — everything this call did is already folded into the
+ * hashes — so the rows explaining it belong before the cut. Stamping the earlier instant
+ * instead would re-admit this call's own judgment rows into the next window, where they
+ * would attribute a change they had nothing to do with: a call that merely MENTIONED a
+ * protected entry would then absolve any tamper that followed it.
+ */
+export declare function updateBaseline(spec: {
+    repoRoot: string;
+    entries: string[];
+}): void;

package/dist/baseline.js

@@ -12,8 +12,9 @@
  * points.
  */
 import { createHash } from 'node:crypto';
-import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { appendRecordFailOpen, readRecords, } from '@polydeukes/core';
 /**
  * The two verdict words that explain a change — the ones that mean a mutation of a
  * protected entry was judged and let through anyway.
@@ -164,3 +165,69 @@ export function readBaseline(path) {
         cutAt: typeof cutAt === 'string' ? cutAt : undefined,
     };
 }
+/** The label every post-hoc state comparison row carries. */
+export const BASELINE_LABEL = 'baseline';
+/**
+ * Compare the protected entries' on-disk state against the stored baseline and record what
+ * moved with no judgment explaining it.
+ *
+ * Runs at hook call START, before this call's own judgment rows land, so the window it reads
+ * is the one the previous comparison left open. Returns the record count as of right now —
+ * where the NEXT window opens, which {@link updateBaseline} persists at call end.
+ *
+ * The comparison records, it never blocks: no row it writes and no failure it hits changes
+ * a verdict or an exit code, which is why every caller keeps it outside the judgment path.
+ */
+export function compareBaseline(spec) {
+    const baselinePath = join(spec.repoRoot, '.polydeukes', 'baseline.json');
+    // Read before any row of this comparison lands, so the rows this call is about to write
+    // cannot fall inside the window they would then explain away.
+    const { records } = readRecords(spec.telemetryPath);
+    const stored = readBaseline(baselinePath);
+    if (stored === null) {
+        // Absence and corruption are the same signal. The baseline file is NOT on the protection
+        // list — protecting it would need a comparison of its own — so its disappearance has to
+        // stay legible in the log instead.
+        appendRecordFailOpen(spec.telemetryPath, {
+            event: 'unattributed',
+            label: BASELINE_LABEL,
+            subject: baselinePath,
+        });
+        return;
+    }
+    const changed = findUnattributed({
+        previous: stored.entries,
+        current: snapshotBaseline({ rootDir: spec.repoRoot, entries: spec.entries }),
+        records,
+        // The cut travels with the hashes it belongs to, from the one read above. Rows older
+        // than it were already spent explaining the state that snapshot recorded.
+        cutAt: stored.cutAt,
+    });
+    // One row per changed entry — an aggregate row could not say WHICH gate definition moved.
+    for (const entry of changed) {
+        appendRecordFailOpen(spec.telemetryPath, {
+            event: 'unattributed',
+            label: BASELINE_LABEL,
+            subject: entry,
+        });
+    }
+}
+/**
+ * Re-establish the baseline at hook call END.
+ *
+ * At call end rather than right after the comparison: refreshing at comparison time would
+ * miss whatever this call's own judged writes changed, leaving detection permanently one
+ * call behind.
+ *
+ * The cut is stamped HERE, beside the snapshot, not at the comparison that opened the call.
+ * Both describe the same instant — everything this call did is already folded into the
+ * hashes — so the rows explaining it belong before the cut. Stamping the earlier instant
+ * instead would re-admit this call's own judgment rows into the next window, where they
+ * would attribute a change they had nothing to do with: a call that merely MENTIONED a
+ * protected entry would then absolve any tamper that followed it.
+ */
+export function updateBaseline(spec) {
+    const dotDir = join(spec.repoRoot, '.polydeukes');
+    mkdirSync(dotDir, { recursive: true });
+    writeBaseline(join(dotDir, 'baseline.json'), snapshotBaseline({ rootDir: spec.repoRoot, entries: spec.entries }), new Date().toISOString());
+}

package/dist/bin.d.ts

@@ -6,9 +6,8 @@
  * table. Anything else prints usage and exits 2 — an unknown argument must never pass
  * silently (fail-closed, the same posture as an unjudgeable payload).
  *
- * The real TTY is wired HERE, not in the library: the runner receives an injectable
- * seam, and this shim binds it to /dev/tty. When /dev/tty cannot be opened (git run by
- * CI or by an agent-spawned shell — no controlling terminal), the seam stays absent and
- * the witness valve is structurally unreachable, so only a human at a terminal can arm it.
+ * `covenant check` reads its observation from stdin and nothing else: the IR JSON by
+ * default, a unified diff under `--diff`. No other file descriptor is opened, so the
+ * process never asks a human anything.
  */
 export {};

package/dist/bin.js

@@ -6,50 +6,41 @@
  * table. Anything else prints usage and exits 2 — an unknown argument must never pass
  * silently (fail-closed, the same posture as an unjudgeable payload).
  *
- * The real TTY is wired HERE, not in the library: the runner receives an injectable
- * seam, and this shim binds it to /dev/tty. When /dev/tty cannot be opened (git run by
- * CI or by an agent-spawned shell — no controlling terminal), the seam stays absent and
- * the witness valve is structurally unreachable, so only a human at a terminal can arm it.
+ * `covenant check` reads its observation from stdin and nothing else: the IR JSON by
+ * default, a unified diff under `--diff`. No other file descriptor is opened, so the
+ * process never asks a human anything.
  */
-import { closeSync, openSync, readFileSync, readSync, writeSync } from 'node:fs';
+import { readFileSync, readSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 /**
- * Bind the TTY prompt seam to /dev/tty, or undefined when no terminal exists. The runner
- * composes the prompt text (it is the side that knows what broke); this shim only writes
- * it and reads the line back.
+ * Read stdin to EOF. `readFileSync(0)` returns only what the first read delivers, so a
+ * diff larger than the pipe buffer would arrive truncated and translate to a partial
+ * observation; this loops until a read answers zero bytes.
  */
-function openTtyPrompt() {
-    let fd;
-    try {
-        fd = openSync('/dev/tty', 'r+');
-    }
-    catch {
-        return undefined;
-    }
-    return (prompt) => {
+function readStdin() {
+    const chunks = [];
+    const buffer = Buffer.alloc(65536);
+    for (;;) {
+        let bytes;
         try {
-            writeSync(fd, prompt);
-            const buffer = Buffer.alloc(4096);
-            const bytes = readSync(fd, buffer, 0, buffer.length, null);
-            return buffer
-                .subarray(0, Math.max(bytes, 0))
-                .toString('utf-8')
-                .replace(/\r?\n$/, '');
+            bytes = readSync(0, buffer, 0, buffer.length, null);
         }
-        catch {
-            return null;
+        catch (error) {
+            const { code } = error;
+            // A pipe with no writer left answers EOF this way on some platforms; EAGAIN is a
+            // non-blocking fd with nothing ready yet, which is not the end of the input.
+            if (code === 'EOF')
+                break;
+            if (code === 'EAGAIN')
+                continue;
+            throw error;
         }
-        finally {
-            try {
-                closeSync(fd);
-            }
-            catch {
-                // An EBADF thrown from this finally would override the `return null` above and
-                // escape the seam.
-            }
-        }
-    };
+        if (bytes === 0)
+            break;
+        chunks.push(Buffer.from(buffer.subarray(0, bytes)));
+    }
+    return Buffer.concat(chunks).toString('utf-8');
 }
 /**
  * Write `text` to stdout and end the process — exit 0 once the write drains, exit 2 when
@@ -65,14 +56,14 @@ async function emitAndExit(text) {
     process.exit(0);
 }
 const args = process.argv.slice(2);
-if (args.length === 2 && args[0] === 'init' && args[1] === 'claude-code') {
+if (args.length === 1 && args[0] === 'init') {
     try {
-        // Imported inside the try, not above it: ESM imports are eager, so the installer stays
+        // Imported inside the try, not above it: ESM imports are eager, so the scaffold stays
         // off `covenant check`'s load path, which a pre-commit hook spawns on every commit. A
         // rejected import outside the try would reach node's unhandled-rejection exit 1, the
         // exact crash this bin refuses to make.
-        const { initClaudeCode } = await import('./init-claude-code.js');
-        const { created, skipped } = initClaudeCode({ projectRoot: process.cwd() });
+        const { scaffoldProject } = await import('./scaffold-project.js');
+        const { created, skipped } = scaffoldProject(process.cwd());
         for (const path of created) {
             process.stdout.write(`created ${path}\n`);
         }
@@ -84,24 +75,7 @@ if (args.length === 2 && args[0] === 'init' && args[1] === 'claude-code') {
     catch (error) {
         // A precondition failure leaves zero files; the message names what the user has to do
         // before running this again.
-        process.stderr.write(`pdks init claude-code failed: ${error instanceof Error ? error.message : String(error)}\n`);
-        process.exit(2);
-    }
-}
-if (args.length === 2 && args[0] === 'init' && args[1] === 'grok') {
-    try {
-        const { initGrok } = await import('./init-grok.js');
-        const { created, skipped } = initGrok({ projectRoot: process.cwd() });
-        for (const path of created) {
-            process.stdout.write(`created ${path}\n`);
-        }
-        for (const path of skipped) {
-            process.stdout.write(`skipped ${path} (already present)\n`);
-        }
-        process.exit(0);
-    }
-    catch (error) {
-        process.stderr.write(`pdks init grok failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.stderr.write(`pdks init failed: ${error instanceof Error ? error.message : String(error)}\n`);
         process.exit(2);
     }
 }
@@ -142,48 +116,57 @@ if (args.length === 1 && args[0] === 'explain') {
     }
 }
 /**
- * Read the `covenant check` flags as a domain, or null when the argv is not one of the
- * three recognized forms: no flags is the staged diff, `--worktree` is the working tree,
- * and `--range <base>..<head>` (or `...` for the merge-base reading) is a ref range.
+ * Read the `covenant check` flags, or null for any argv outside the finite table: `--diff`
+ * at most once, `--enforce` at most once with `advise` or `block`, in either order, and
+ * nothing else.
  */
-function parseCheckDomain(flags) {
-    if (flags.length === 0)
-        return { kind: 'staged' };
-    if (flags.length === 1 && flags[0] === '--worktree')
-        return { kind: 'worktree' };
-    if (flags.length !== 2 || flags[0] !== '--range')
-        return null;
-    const range = flags[1];
-    if (range.startsWith('--'))
-        return null;
-    const mergeBase = range.includes('...');
-    const separator = mergeBase ? '...' : '..';
-    const at = range.indexOf(separator);
-    if (at === -1)
-        return null;
-    const base = range.slice(0, at);
-    const head = range.slice(at + separator.length);
-    if (base === '' || head === '')
+function parseCheckFlags(flags) {
+    let diffMode = false;
+    let enforce;
+    for (let i = 0; i < flags.length; i += 1) {
+        const flag = flags[i];
+        if (flag === '--diff' && !diffMode) {
+            diffMode = true;
+            continue;
+        }
+        if (flag === '--enforce' && enforce === undefined) {
+            const level = flags[i + 1];
+            if (level !== 'advise' && level !== 'block')
+                return null;
+            enforce = level;
+            i += 1;
+            continue;
+        }
         return null;
-    return { kind: 'range', base, head, ...(mergeBase && { ancestry: 'merge-base' }) };
+    }
+    return { diffMode, enforce };
 }
-const domain = args[0] === 'covenant' && args[1] === 'check' ? parseCheckDomain(args.slice(2)) : null;
-if (domain === null) {
-    process.stderr.write('usage: pdks covenant check [--worktree | --range <base>..<head>] | pdks explain | pdks init claude-code | pdks init grok | pdks docs [topic | search <query> | show <document-id>]\n');
+const check = args[0] === 'covenant' && args[1] === 'check' ? parseCheckFlags(args.slice(2)) : null;
+if (check === null) {
+    process.stderr.write('usage: pdks covenant check [--diff] [--enforce advise|block] | pdks explain | pdks init | pdks docs [topic | search <query> | show <document-id>]\n');
     process.exit(2);
 }
+const { diffMode, enforce } = check;
 try {
     // Loaded here rather than at the top of the file. This runner statically pulls in the
-    // git adapter, the core, and the judge, so a top-level import made every subcommand
-    // wait on all three resolving — and `docs` is the one that has to answer in a tree
-    // where they do not, since a package installed but never built is exactly the state
-    // `pdks docs install` is asked about. The catch below already answers for whatever
-    // this import cannot do, at the same exit 2 it answers everything else with.
+    // core and the judge, so a top-level import made every subcommand wait on both
+    // resolving — and `docs` is the one that has to answer in a tree where they do not,
+    // since a package installed but never built is exactly the state `pdks docs install`
+    // is asked about. The catch below already answers for whatever this import cannot do,
+    // at the same exit 2 it answers everything else with.
     const { runCovenantCheck } = await import('./covenant-check.js');
+    const { covenantInputFromUnifiedDiff } = await import('./diff-ir.js');
+    const text = readStdin();
     const { exitCode } = await runCovenantCheck({
         repoRoot: process.cwd(),
-        ttyPrompt: openTtyPrompt(),
-        domain,
+        // A thunk, not a value: the runner settles the telemetry path before calling it, so a
+        // translation or parse failure lands as the same one blocked row every other
+        // fail-closed branch leaves.
+        input: () => (diffMode ? covenantInputFromUnifiedDiff({ text }) : JSON.parse(text)),
+        // The input mode is the surface: a diff is a finished change set, anything else is one
+        // call the caller observed.
+        surface: diffMode ? 'changeSet' : 'session',
+        ...(enforce !== undefined && { enforce }),
     });
     process.exit(exitCode);
 }

package/dist/covenant/bash-line.d.ts

@@ -0,0 +1,130 @@
+/**
+ * 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.
+ */
+/** A single word token with a static-opacity flag (`opaque` = value not knowable). */
+export type WordToken = {
+    text: string;
+    opaque: boolean;
+};
+/** A redirect operator paired with its target word (`>` `>>` `<` `2>` `&>`). */
+export type RedirectToken = {
+    operator: string;
+    target: WordToken;
+};
+/**
+ * One heredoc body a command declared, with its delimiter's quoting. `literal` means the
+ * delimiter was quoted, so the body is written verbatim; an unquoted delimiter expands its
+ * body, which only a consumer can decide what to do about.
+ */
+export type HeredocBody = {
+    body: string;
+    literal: boolean;
+};
+/**
+ * One simple command: its word tokens, any redirect operators, and the heredoc bodies it
+ * declared (in declaration order — absent when it declared none).
+ */
+export type SimpleCommand = {
+    words: WordToken[];
+    redirects: RedirectToken[];
+    heredocs?: HeredocBody[];
+};
+/**
+ * A span of the line the scanner could not read, with the reason it stopped. `reason` is a
+ * telemetry pass-through value: no consumer branches on it.
+ */
+export type UnreadSpan = {
+    text: string;
+    reason: string;
+};
+/**
+ * A half-open span `[start, end)` of the line bash hands to a command as stdin data instead
+ * of executing: a heredoc body, or a herestring's target word.
+ */
+export type DataSpan = {
+    start: number;
+    end: number;
+};
+/**
+ * The tokenizer's result: the commands it read, plus one span per failure it hit. A failure
+ * does not discard the line — the read commands reach precise judgment and only the spans
+ * fall to a consumer's conservative treatment. An empty `unread` is the "fully read" signal.
+ *
+ * `data` lists the stdin-data spans in source order, non-overlapping: heredoc bodies and
+ * herestring words bash hands over without expanding them. A body under an unquoted
+ * delimiter that carries `$` or a backtick, and an opaque herestring word, are text bash
+ * runs first and are not data. A span the scanner could not finish reading is never among
+ * them either, so unread bytes stay on the command line.
+ */
+export type TokenizeResult = {
+    commands: SimpleCommand[];
+    unread: UnreadSpan[];
+    data: DataSpan[];
+};
+/** A detected mutation target (path) with the name of the rule that found it. */
+export type MutationTarget = {
+    path: string;
+    rule: string;
+};
+/**
+ * A detection rule seam: a pure function over a single simple command that returns the
+ * mutation targets it detects.
+ */
+export type MutationRule = {
+    name: string;
+    detect(command: SimpleCommand): MutationTarget[];
+};
+/** A structure that cannot be decided deterministically, with the reason why. */
+export type Indeterminate = {
+    reason: string;
+};
+/** The extraction result — detected mutations and undecidable structures, kept separate. */
+export type MutationAnalysis = {
+    mutations: MutationTarget[];
+    indeterminate: Indeterminate[];
+};
+/**
+ * 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 declare function isNestedShellCommand(commandName: string): boolean;
+/**
+ * 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 declare function commandNameWord(command: SimpleCommand): WordToken | undefined;
+/**
+ * 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 declare function tokenizeCommandLine(line: string): TokenizeResult;
+/**
+ * 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 declare function executedText(line: string): string;
+/**
+ * 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 declare function extractMutations(line: string, rules: MutationRule[]): MutationAnalysis;