polydeukes 0.6.1 → 0.8.0

package/dist/covenant/shell-mod.js

@@ -0,0 +1,213 @@
+/**
+ * `judgeShellModification` — the shell-mod meta-covenant's pure judge (zero I/O).
+ *
+ * Analyzes the command-line strings of *shell* tool calls (names and arg keys are injected
+ * values, never source literals) per simple command: the fixed detection rules catch writes
+ * to a protected path, undecidable structures (opaque mentions, opaque write targets) fail
+ * closed, the read-only allowlist absolves proven reads, and every other protected-path
+ * mention breaks — "mention + unproven = block". It judges only its own axis: a non-shell
+ * tool call is upheld, since the tool axis belongs to the self-mod meta-covenant and
+ * run-all co-existence depends on that boundary.
+ */
+import { isNestedShellCommand, tokenizeCommandLine } from './bash-line.js';
+import { mentionsPath, untokenizableLineCandidates } from './mention.js';
+import { commandBasename, redirectWriteRule, sedInPlaceRule, teeRule } from './mutation-rules.js';
+import { outcomeFromVerdict, UNJUDGEABLE_OUTCOME } from './run-covenant.js';
+/**
+ * Commands proven read-only by shell semantics — the default allowlist. An entry is a
+ * leading word sequence; multi-word entries exist because a bare command name (`git`) can
+ * front mutating subcommands. Omission errs toward friction, never a hole.
+ *
+ * An entry must have no way to write a file through its own arguments, since the allowlist
+ * vouches for the command head while `matchesReadOnlyEntry` never inspects trailing argv.
+ * That is why `git diff`/`git log`/`git show` are absent: all accept `--output=<file>`, a
+ * redirect-free truncating write. `git status`/`git grep` reject `--output`, so they stay.
+ */
+export const DEFAULT_READ_ONLY_COMMANDS = [
+    'cat',
+    'head',
+    'tail',
+    'grep',
+    'rg',
+    'ls',
+    'wc',
+    'diff',
+    'stat',
+    'file',
+    'echo',
+    'printf',
+    'git status',
+    'git grep',
+];
+// The rule set is fixed, not injectable: dropping a rule from an assembly would be a
+// detection hole, and no consumer needs a subset.
+const MUTATION_RULES = [redirectWriteRule, teeRule, sedInPlaceRule];
+/**
+ * True when the command's leading words match the allowlist entry's word sequence. Exported
+ * so the transcript judge's allowlist clause absolves reads by this exact comparison instead
+ * of a fork that could drift from it.
+ */
+export function matchesReadOnlyEntry(command, entry) {
+    // An empty entry would match every command vacuously (`[].every()` is true) — reject it
+    // locally so the covenant does not depend on a distant caller-side filter.
+    if (entry.length === 0)
+        return false;
+    return entry.every((entryWord, k) => {
+        const word = command.words[k];
+        if (word === undefined || word.opaque)
+            return false;
+        // The first word is compared by basename (`/bin/cat` is still `cat`); later words verbatim.
+        const text = k === 0 ? commandBasename(word) : word.text;
+        return text === entryWord;
+    });
+}
+/**
+ * Judge one simple command. Returns the break reason, or null when the command contributes
+ * to uphold. The clause order below is normative: each clause exists to be reached before
+ * the next one can absolve. `lineFullyRead` is false when the line carried a span the
+ * tokenizer could not read, which withholds the allowlist clause.
+ */
+function judgeCommand(command, protectedPaths, readOnlyEntries, lineFullyRead) {
+    // (a) Precise rules: a detected mutation whose target carries a protected path breaks.
+    for (const rule of MUTATION_RULES) {
+        for (const target of rule.detect(command)) {
+            const hit = protectedPaths.find((path) => mentionsPath(target.path, path));
+            if (hit !== undefined)
+                return `${target.rule} targets protected path ${hit}`;
+        }
+    }
+    // (b) Mention scan over word texts and redirect target texts (heredoc bodies are data —
+    // the tokenizer never surfaces them as tokens). No mention: nothing left to judge.
+    const tokens = [...command.words, ...command.redirects.map((redirect) => redirect.target)];
+    let mentioned;
+    let mentionIsOpaque = false;
+    for (const token of tokens) {
+        const hit = protectedPaths.find((path) => mentionsPath(token.text, path));
+        if (hit === undefined)
+            continue;
+        mentioned ??= hit;
+        if (token.opaque)
+            mentionIsOpaque = true;
+    }
+    if (mentioned === undefined)
+        return null;
+    // (c) A mention inside an opaque token (command substitution, process substitution,
+    // expansion, glob) is undecidable, so it breaks rather than passing.
+    if (mentionIsOpaque)
+        return `protected path ${mentioned} inside an opaque token`;
+    // (d) An opaque write target could resolve to the protected path — unprovable, so it
+    // breaks even for an allowlisted reader (order over (e) is the invariant).
+    if (command.redirects.some((r) => r.operator.includes('>') && r.target.opaque)) {
+        return `opaque redirect target alongside protected path ${mentioned}`;
+    }
+    // (e) Read-only allowlist: a proven read absolves the mention — but a nested shell
+    // (`eval`/`sh -c …`) re-parses its string args, so it can never be proven read-only even
+    // if it was injected into the allowlist. Its mention falls through to the backstop. A line
+    // carrying an unread span is refused the same way: what the scanner never read could be
+    // anything, so no head vouches for it.
+    const first = command.words[0];
+    const firstBasename = first !== undefined ? commandBasename(first) : '';
+    if (lineFullyRead &&
+        !isNestedShellCommand(firstBasename) &&
+        readOnlyEntries.some((entry) => matchesReadOnlyEntry(command, entry))) {
+        return null;
+    }
+    // (f) Backstop — mention + unproven = block.
+    return `${first?.text ?? ''} mentions protected path ${mentioned} without read-only proof`;
+}
+/**
+ * Judge a {@link CovenantInput} against the shell-mod spec (pure).
+ *
+ * For each `toolCalls[i]` whose `name` exactly equals a non-empty `shellToolNames` entry,
+ * every string value under a non-empty `commandArgNames` key is analyzed as a shell line;
+ * a shell call with zero such strings breaks (a misassembled arg name must not degrade
+ * into universal uphold). A span the tokenizer could not read breaks iff the dequoted span —
+ * or one of its shell-metacharacter fragments — mentions a protected path, and is answered
+ * before the commands so that a mention only the span can see is named as one. Non-shell
+ * calls, `subagentSpawns`, and `userMessages` are never judged.
+ */
+export function judgeShellModification(input, spec) {
+    const shellToolNames = spec.shellToolNames.filter((name) => name !== '');
+    const commandArgNames = spec.commandArgNames.filter((name) => name !== '');
+    const protectedPaths = spec.protectedPaths.filter((path) => path !== '');
+    const readOnlyEntries = spec.readOnlyCommands
+        .map((entry) => entry.split(/\s+/).filter((word) => word !== ''))
+        .filter((entry) => entry.length > 0);
+    for (const call of input.toolCalls) {
+        if (!shellToolNames.includes(call.name)) {
+            continue;
+        }
+        const lines = commandArgNames
+            .map((name) => call.args?.[name])
+            .filter((value) => typeof value === 'string');
+        if (lines.length === 0) {
+            return {
+                upheld: false,
+                reason: `unjudgeable shell call ${call.name}: no command string under any command-arg name`,
+            };
+        }
+        for (const line of lines) {
+            const { commands, unread } = tokenizeCommandLine(line);
+            // The conservative treatment applies to the span alone, not the whole line. The shell
+            // would still remove quotes and backslash escapes, so a split target like `sr"c"` or
+            // `sr\c` becomes `src` on execution — strip both before the segment-match, or the very
+            // escaping that stopped the scan defeats the scan that replaces it. Removal may
+            // over-join unrelated words, which only ever widens what breaks, never a hole. The
+            // fallback-only decomposition then covers the metachar-glued forms (`…/dist;echo x`)
+            // that no tokenizer was left to cut apart — narrowing the span must not narrow the
+            // extraction.
+            for (const span of unread) {
+                const candidates = untokenizableLineCandidates(span.text.replace(/['"\\]/g, ''));
+                const hit = protectedPaths.find((path) => candidates.some((candidate) => mentionsPath(candidate, path)));
+                if (hit !== undefined) {
+                    return {
+                        upheld: false,
+                        reason: `untokenizable command line mentions protected path ${hit}`,
+                    };
+                }
+            }
+            for (const command of commands) {
+                const reason = judgeCommand(command, protectedPaths, readOnlyEntries, unread.length === 0);
+                if (reason !== null)
+                    return { upheld: false, reason };
+            }
+        }
+    }
+    return { upheld: true };
+}
+/**
+ * Build the shell-mod registration. Routing stays path mention; the judgment is the thunk.
+ *
+ * The misassembly gate lives at the thunk's entry: zero valid entries in any of the three
+ * required lists would make {@link judgeShellModification} uphold every call, so it answers
+ * the unjudgeable outcome instead, which no enforce level softens. The allowlist is exempt
+ * — empty just means stricter.
+ */
+export function shellModRegistration(spec) {
+    const judgeSpec = {
+        protectedPaths: spec.protectedPaths,
+        shellToolNames: spec.shellTools,
+        commandArgNames: spec.commandArgs ?? [],
+        readOnlyCommands: spec.readOnlyCommands ?? DEFAULT_READ_ONLY_COMMANDS,
+    };
+    return {
+        label: 'shell-mod',
+        protectedPaths: spec.protectedPaths,
+        body: async (input) => {
+            if (judgeSpec.protectedPaths.filter((path) => path !== '').length === 0 ||
+                judgeSpec.shellToolNames.filter((name) => name !== '').length === 0 ||
+                judgeSpec.commandArgNames.filter((arg) => arg !== '').length === 0) {
+                return UNJUDGEABLE_OUTCOME;
+            }
+            try {
+                return outcomeFromVerdict(judgeShellModification(input, judgeSpec));
+            }
+            catch {
+                // Structurally unjudgeable input that passed parseInput (which validates the
+                // collection shapes, not the element ones): cannot judge means block.
+                return UNJUDGEABLE_OUTCOME;
+            }
+        },
+        ...(spec.witness !== undefined ? { witness: spec.witness } : {}),
+    };
+}

package/dist/covenant/supply.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The supply layer — what a judgment's world is made of before any judgment runs.
+ *
+ * Two verbs: `planSources` folds the registrations' `sources` bindings into a path list and
+ * a channel-kind list, and `supplySources` fills each through its own injected reader. The
+ * reading itself belongs to the composition root, which is the only place that knows how its
+ * surface observes the tree; this module opens no file and spawns no process.
+ */
+import type { ChannelReader, SourceReader } from '@polydeukes/core';
+import type { CovenantRegistration } from './dispatch.ts';
+/** `planSources` input — the registration table the judgment will run. */
+export type PlanSourcesSpec = {
+    registrations: readonly CovenantRegistration[];
+};
+/**
+ * What the registrations named, in registration then declaration order, deduplicated per
+ * axis: `files` are repo-relative paths, `channels` the channel KINDS the bindings name —
+ * two bindings on one kind are one reading, and which name each carries is the merge's own.
+ */
+export type SourcePlan = {
+    files: readonly string[];
+    channels: readonly string[];
+};
+/**
+ * `supplySources` input — a plan and the surface's readers.
+ *
+ * Both readers answer `undefined` for something that is not there and throw for every other
+ * failure, so a permission error reaches the root's fail-closed path instead of passing
+ * for an absence the declaration's `supply` policy would wave through. An ABSENT
+ * `readChannel` is the change-set surface, which has no session: every channel is absent.
+ */
+export type SupplySourcesSpec = {
+    plan: SourcePlan;
+    read: SourceReader;
+    readChannel?: ChannelReader;
+};
+/**
+ * What the readers gave back, keyed by the planned path and the planned kind. Anything a
+ * reader could not answer has no key at all — a key holding `undefined` would pass the
+ * engine's presence test as a supply that never happened.
+ */
+export type SuppliedSources = {
+    files: Record<string, string>;
+    channels: Record<string, string>;
+};
+/**
+ * The paths and channel kinds the registrations name, first occurrence winning.
+ *
+ * Order is the plan's contract: the supplied result and the witnesses built on it keep it,
+ * which is what lets two surfaces reach the same first witness.
+ */
+export declare function planSources(spec: PlanSourcesSpec): SourcePlan;
+/** Read each planned path and kind once, in plan order, keeping only what came back. */
+export declare function supplySources(spec: SupplySourcesSpec): SuppliedSources;

package/dist/covenant/supply.js

@@ -0,0 +1,50 @@
+/**
+ * The supply layer — what a judgment's world is made of before any judgment runs.
+ *
+ * Two verbs: `planSources` folds the registrations' `sources` bindings into a path list and
+ * a channel-kind list, and `supplySources` fills each through its own injected reader. The
+ * reading itself belongs to the composition root, which is the only place that knows how its
+ * surface observes the tree; this module opens no file and spawns no process.
+ */
+/**
+ * The paths and channel kinds the registrations name, first occurrence winning.
+ *
+ * Order is the plan's contract: the supplied result and the witnesses built on it keep it,
+ * which is what lets two surfaces reach the same first witness.
+ */
+export function planSources(spec) {
+    const files = [];
+    const channels = [];
+    for (const registration of spec.registrations) {
+        for (const binding of registration.sources ?? []) {
+            // A transcript is neither a path nor a channel kind: the surface hands the session
+            // to assembly directly, so there is nothing here for a reader to fetch.
+            if ('transcript' in binding)
+                continue;
+            if ('sidecar' in binding) {
+                if (!channels.includes('sidecar'))
+                    channels.push('sidecar');
+            }
+            else if (!files.includes(binding.file)) {
+                files.push(binding.file);
+            }
+        }
+    }
+    return { files, channels };
+}
+/** Read each planned path and kind once, in plan order, keeping only what came back. */
+export function supplySources(spec) {
+    const files = {};
+    for (const path of spec.plan.files) {
+        const text = spec.read(path);
+        if (text !== undefined)
+            files[path] = text;
+    }
+    const channels = {};
+    for (const kind of spec.plan.channels) {
+        const text = spec.readChannel?.(kind);
+        if (text !== undefined)
+            channels[kind] = text;
+    }
+    return { files, channels };
+}

package/dist/covenant/transcript-mod.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `judgeTranscriptModification` — the transcript-mod covenant's pure judge (zero I/O) plus
+ * the registration factory that routes on it.
+ *
+ * The transcript is judged by whole-path equality on one file, never as an ancestor, so
+ * home-directory spellings (`~`, `$HOME`, `${HOME}`, `~<user>`) are closed by the injected
+ * `home` value rather than by protecting home itself. Out-of-repo ancestor destruction is
+ * outside observation scope and passes here by design. The Bash axis follows shell-mod's
+ * ladder without the opaque-mention clause (reading a session never needs a witness); the
+ * tool axis judges proven `fileChange` targets and falls back to the `args` traversal.
+ */
+import type { CovenantInput, CovenantVerdict } from '@polydeukes/core';
+import type { CovenantRegistration, MetaCovenantRegistration } from './dispatch.ts';
+/**
+ * `TranscriptModificationSpec` — the injected axes of the judge. Empty-string entries in
+ * every list are ignored.
+ */
+export type TranscriptModificationSpec = {
+    /** the one file this covenant owns */
+    transcriptPath: string;
+    /** directory whose spellings are closed; absent or malformed leaves them open */
+    home?: string;
+    shellToolNames: string[];
+    commandArgNames: string[];
+    mutatingToolNames: string[];
+    /** read-only allowlist entries in shell-mod's format */
+    readOnlyCommands: string[];
+};
+/**
+ * Judge a {@link CovenantInput} against the transcript-mod spec (pure).
+ *
+ * Shell-tool calls are judged on the Bash axis per simple command, mutating-tool calls on
+ * the tool axis; every other call is never judged. A degenerate `transcriptPath` upholds
+ * everything.
+ *
+ * @param input - The call set to judge
+ * @param spec - The injected axes; empty strings are ignored
+ * @returns A break naming what touched the transcript, or an uphold
+ */
+export declare function judgeTranscriptModification(input: CovenantInput, spec: TranscriptModificationSpec): CovenantVerdict;
+/** `TranscriptModRegistrationSpec` — the assembly values baked into the registration. */
+export type TranscriptModRegistrationSpec = {
+    transcriptPath: string;
+    home?: string;
+    shellTools: string[];
+    commandArgs: string[];
+    mutatingTools: string[];
+    witness?: CovenantRegistration['witness'];
+};
+/**
+ * Build the transcript-mod registration. Routing is the judge itself as a `matches`
+ * predicate — `protectedPaths` stays empty so no home ancestor re-enters path-mention
+ * routing — and the telemetry subject is the canonical absolute path.
+ *
+ * The misassembly gate the other meta-covenants carry applies here too: with any of the
+ * three axis lists empty the judge can never see a call, so routing on it would go silently
+ * inert — the universal-uphold shape the gate exists to refuse. Such a spec routes every
+ * call instead and answers the unjudgeable outcome, which no enforce level softens.
+ */
+export declare function transcriptModRegistration(spec: TranscriptModRegistrationSpec): MetaCovenantRegistration;

package/dist/covenant/transcript-mod.js

@@ -0,0 +1,254 @@
+/**
+ * `judgeTranscriptModification` — the transcript-mod covenant's pure judge (zero I/O) plus
+ * the registration factory that routes on it.
+ *
+ * The transcript is judged by whole-path equality on one file, never as an ancestor, so
+ * home-directory spellings (`~`, `$HOME`, `${HOME}`, `~<user>`) are closed by the injected
+ * `home` value rather than by protecting home itself. Out-of-repo ancestor destruction is
+ * outside observation scope and passes here by design. The Bash axis follows shell-mod's
+ * ladder without the opaque-mention clause (reading a session never needs a witness); the
+ * tool axis judges proven `fileChange` targets and falls back to the `args` traversal.
+ */
+import { isNestedShellCommand, tokenizeCommandLine } from './bash-line.js';
+import { pathCandidates, pathSegments, provenChangePath, resolveDotSegments, someStringValue, untokenizableLineCandidates, } from './mention.js';
+import { commandBasename, redirectWriteRule, sedInPlaceRule, teeRule } from './mutation-rules.js';
+import { outcomeFromVerdict, UNJUDGEABLE_OUTCOME } from './run-covenant.js';
+import { DEFAULT_READ_ONLY_COMMANDS, matchesReadOnlyEntry } from './shell-mod.js';
+// The rule set is fixed, assembled exactly as shell-mod assembles it: dropping one would be
+// a detection hole, and the two judges must not diverge on what counts as a write.
+const MUTATION_RULES = [redirectWriteRule, teeRule, sedInPlaceRule];
+/** True iff two segment runs are the same path — length and every segment's text. */
+function segmentsEqual(a, b) {
+    return a.length === b.length && a.every((segment, i) => segment === b[i]);
+}
+/**
+ * Normalize the injected home value, or return `null` when it is not an absolute path
+ * naming a directory — expanding such a value would manufacture matches (`''` turns `~/x`
+ * into `/x`).
+ */
+function normalizeHome(home) {
+    if (home === undefined || !home.startsWith('/'))
+        return null;
+    const path = home.replace(/\/+$/, '');
+    const user = pathSegments(path).at(-1);
+    if (user === undefined)
+        return null;
+    return { path, user };
+}
+/**
+ * Resolve the transcript's axes, or return `null` for a degenerate `transcriptPath` (the
+ * covenant goes inert rather than matching everything). Home forms are recognized only when
+ * the transcript lives under the given home.
+ */
+function resolveTranscript(spec) {
+    const segments = pathSegments(spec.transcriptPath);
+    if (!segments.some((segment) => segment !== '.'))
+        return null;
+    const home = normalizeHome(spec.home);
+    const underHome = home !== null && spec.transcriptPath.startsWith(`${home.path}/`);
+    return {
+        target: resolveDotSegments(segments),
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: intentional shell expansion spelling
+        homePrefixes: underHome && home !== null ? ['~', '$HOME', '${HOME}', `~${home.user}`] : [],
+        homeSegments: home === null ? [] : pathSegments(home.path),
+        path: spec.transcriptPath,
+        readOnlyEntries: spec.readOnlyCommands
+            .map((entry) => entry.split(/\s+/).filter((word) => word !== ''))
+            .filter((entry) => entry.length > 0),
+    };
+}
+/**
+ * True iff a path candidate names the transcript by whole-path equality. A home prefix is
+ * substituted before dots are resolved, matching the shell's expansion order.
+ */
+function namesTranscript(candidate, transcript) {
+    const segments = pathSegments(candidate);
+    const head = segments[0];
+    const expanded = head !== undefined && transcript.homePrefixes.includes(head)
+        ? [...transcript.homeSegments, ...segments.slice(1)]
+        : segments;
+    return segmentsEqual(resolveDotSegments(expanded), transcript.target);
+}
+/**
+ * The path forms one candidate can carry: itself, plus the rooted suffix behind a glued
+ * prefix (`curl -o/abs`, `host:/abs`, `>>/abs`), which whole-path equality would otherwise
+ * miss.
+ */
+function pathForms(candidate) {
+    if (/^[/~$]/.test(candidate))
+        return [candidate];
+    const rooted = /[/~$]/.exec(candidate);
+    return rooted === null ? [candidate] : [candidate, candidate.slice(rooted.index)];
+}
+/** True iff any path candidate inside one token names the transcript. */
+function tokenNamesTranscript(token, transcript) {
+    return pathCandidates(token)
+        .flatMap(pathForms)
+        .some((candidate) => namesTranscript(candidate, transcript));
+}
+/** True iff any string value inside `value`, at any depth, names the transcript. */
+function argsNameTranscript(value, transcript) {
+    return someStringValue(value, (token) => tokenNamesTranscript(token, transcript));
+}
+/**
+ * Judge one simple command. Returns the break reason, or null when the command contributes
+ * to uphold. Clause `(d)` must stay ahead of `(e)`: an opaque write target is unprovable, so
+ * it has to break before the allowlist gets a chance to absolve it. The letters skip `(c)`
+ * because this ladder has no opaque-mention clause, matching the shell ladder's numbering
+ * rather than closing the gap. `lineFullyRead` is false when the line carried a span the
+ * tokenizer could not read, which withholds the allowlist clause.
+ */
+function judgeCommand(command, transcript, lineFullyRead) {
+    // (a) Precise rules: a detected mutation whose target is the transcript breaks.
+    for (const rule of MUTATION_RULES) {
+        for (const target of rule.detect(command)) {
+            if (tokenNamesTranscript(target.path, transcript)) {
+                return `${target.rule} targets the session transcript ${transcript.path}`;
+            }
+        }
+    }
+    // (b) Mention scan over word texts and redirect target texts. Opaque tokens are read too:
+    // this ladder has no opaque-mention clause, so their text must still register a mention for
+    // the backstop to answer. No mention: nothing left to judge.
+    const tokens = [...command.words, ...command.redirects.map((redirect) => redirect.target)];
+    if (!tokens.some((token) => tokenNamesTranscript(token.text, transcript)))
+        return null;
+    // (d) An opaque write target could resolve to the transcript itself — unprovable, so it
+    // breaks even for an allowlisted reader (order over (e) is the invariant).
+    if (command.redirects.some((r) => r.operator.includes('>') && r.target.opaque)) {
+        return `opaque redirect target alongside the session transcript ${transcript.path}`;
+    }
+    // (e) Read-only allowlist: a proven read absolves the mention, in every spelling — but a
+    // nested shell (`eval`/`sh -c …`) re-parses its string args, so it is never provably a read.
+    // A line carrying an unread span is refused the same way: reading the session is free, but
+    // only on a line we finished reading.
+    const first = command.words[0];
+    const firstBasename = first !== undefined ? commandBasename(first) : '';
+    if (lineFullyRead &&
+        !isNestedShellCommand(firstBasename) &&
+        transcript.readOnlyEntries.some((entry) => matchesReadOnlyEntry(command, entry))) {
+        return null;
+    }
+    // (f) Backstop — mention + unproven = block.
+    return `${first?.text ?? ''} names the session transcript ${transcript.path} without read-only proof`;
+}
+/** Judge one shell-tool call's command lines. Returns the break reason, or null. */
+function judgeShellCall(call, commandArgNames, transcript) {
+    // A shell call with no command string is not judged: this judge is also the router, so
+    // breaking here would record the transcript as the subject of a call that never named it.
+    const lines = commandArgNames
+        .map((name) => call.args?.[name])
+        .filter((value) => typeof value === 'string');
+    for (const line of lines) {
+        const { commands, unread } = tokenizeCommandLine(line);
+        // An unread span gets the conservative treatment: quotes and escapes are stripped as
+        // the shell would, and metachar-glued spellings are decomposed.
+        for (const span of unread) {
+            const candidates = untokenizableLineCandidates(span.text.replace(/['"\\]/g, ''));
+            if (candidates.some((candidate) => tokenNamesTranscript(candidate, transcript))) {
+                return `untokenizable command line names the session transcript ${transcript.path}`;
+            }
+        }
+        for (const command of commands) {
+            const reason = judgeCommand(command, transcript, unread.length === 0);
+            if (reason !== null)
+                return reason;
+        }
+    }
+    return null;
+}
+/** Judge one mutating tool call on its proven target, else on its `args`. Returns the break reason, or null. */
+function judgeMutatingCall(call, transcript) {
+    const changePath = provenChangePath(call);
+    if (changePath !== null) {
+        return namesTranscript(changePath, transcript)
+            ? `${call.name} would modify the session transcript ${changePath}`
+            : null;
+    }
+    // No target is proven here, so the reason reports the observation, not a write.
+    return argsNameTranscript(call.args, transcript)
+        ? `${call.name} names the session transcript ${transcript.path} with no proven target`
+        : null;
+}
+/**
+ * Judge a {@link CovenantInput} against the transcript-mod spec (pure).
+ *
+ * Shell-tool calls are judged on the Bash axis per simple command, mutating-tool calls on
+ * the tool axis; every other call is never judged. A degenerate `transcriptPath` upholds
+ * everything.
+ *
+ * @param input - The call set to judge
+ * @param spec - The injected axes; empty strings are ignored
+ * @returns A break naming what touched the transcript, or an uphold
+ */
+export function judgeTranscriptModification(input, spec) {
+    const transcript = resolveTranscript(spec);
+    if (transcript === null) {
+        return { upheld: true };
+    }
+    const shellToolNames = spec.shellToolNames.filter((name) => name !== '');
+    const commandArgNames = spec.commandArgNames.filter((name) => name !== '');
+    const mutatingToolNames = spec.mutatingToolNames.filter((name) => name !== '');
+    for (const call of input.toolCalls) {
+        if (shellToolNames.includes(call.name)) {
+            const reason = judgeShellCall(call, commandArgNames, transcript);
+            if (reason !== null)
+                return { upheld: false, reason };
+            continue;
+        }
+        if (mutatingToolNames.includes(call.name)) {
+            const reason = judgeMutatingCall(call, transcript);
+            if (reason !== null)
+                return { upheld: false, reason };
+        }
+    }
+    return { upheld: true };
+}
+/**
+ * Build the transcript-mod registration. Routing is the judge itself as a `matches`
+ * predicate — `protectedPaths` stays empty so no home ancestor re-enters path-mention
+ * routing — and the telemetry subject is the canonical absolute path.
+ *
+ * The misassembly gate the other meta-covenants carry applies here too: with any of the
+ * three axis lists empty the judge can never see a call, so routing on it would go silently
+ * inert — the universal-uphold shape the gate exists to refuse. Such a spec routes every
+ * call instead and answers the unjudgeable outcome, which no enforce level softens.
+ */
+export function transcriptModRegistration(spec) {
+    const judgeSpec = {
+        transcriptPath: spec.transcriptPath,
+        home: spec.home,
+        shellToolNames: spec.shellTools,
+        commandArgNames: spec.commandArgs,
+        mutatingToolNames: spec.mutatingTools,
+        readOnlyCommands: DEFAULT_READ_ONLY_COMMANDS,
+    };
+    const axesEmpty = judgeSpec.mutatingToolNames.filter((name) => name !== '').length === 0 ||
+        judgeSpec.shellToolNames.filter((name) => name !== '').length === 0 ||
+        judgeSpec.commandArgNames.filter((arg) => arg !== '').length === 0;
+    if (axesEmpty) {
+        return {
+            label: 'transcript-mod',
+            protectedPaths: [],
+            matches: () => spec.transcriptPath,
+            body: async () => UNJUDGEABLE_OUTCOME,
+            ...(spec.witness !== undefined ? { witness: spec.witness } : {}),
+        };
+    }
+    return {
+        label: 'transcript-mod',
+        protectedPaths: [],
+        matches: (input) => judgeTranscriptModification(input, judgeSpec).upheld ? null : spec.transcriptPath,
+        body: async (input) => {
+            try {
+                return outcomeFromVerdict(judgeTranscriptModification(input, judgeSpec));
+            }
+            catch {
+                // Structurally unjudgeable input that passed parseInput (which validates the
+                // collection shapes, not the element ones): cannot judge means block.
+                return UNJUDGEABLE_OUTCOME;
+            }
+        },
+        ...(spec.witness !== undefined ? { witness: spec.witness } : {}),
+    };
+}