polydeukes 0.3.0 → 0.5.0

package/dist/claude-code-hook.js

@@ -1,5 +1,5 @@
 /**
- * `runClaudeCodeHook` — the assembled session-surface judgment runner (DIST-01 §3-c).
+ * `runClaudeCodeHook` — the assembled session-surface judgment runner.
  *
  * The session counterpart of {@link runCovenantCheck}, and the one place where the Claude
  * Code adapter (tool vocabulary, up-translation) and the covenant package (dispatcher +
@@ -8,17 +8,14 @@
  * a delegator that calls this function. That is what makes the session surface installable:
  * a consumer registers a hook that resolves this package instead of copying assembly.
  *
- * Wiring shape: COVENANT-03 §4.4 + COVENANT-04d §4.5 registrations consumed through
- * ADAPTER-03 §4.1 `runAdapterPath`, with `dispatchCovenants` bound to the injected dispatch
- * seam. The protection-policy data (protectedPaths / disciplines / witness) is read from the
- * root data config through {@link loadConfig} (CONFIG-03), which also attaches the config
- * file to its own surface.
+ * The protection-policy data (protectedPaths / disciplines / witness) is read from the root
+ * data config through {@link loadConfig}, which also attaches the config file to its own
+ * surface.
  *
- * The valve is the TTL witness (COVENANT-06, moved behind the verdict by COVENANT-17)
- * judged over the JSONL transcript provider (ADAPTER-04). The judge body always spawns, and
- * only an outcome that translated to blocked consults the witness — `witnessed` rows are
- * would-block only. Its defence is provenance rather than secrecy: only a real human
- * utterance carries the transcript marking `findUserMessages()` admits.
+ * The valve is the TTL witness, judged over the JSONL transcript provider. The judge body
+ * always spawns, and only an outcome that translated to blocked consults the witness —
+ * `witnessed` rows are would-block only. Its defence is provenance rather than secrecy: only
+ * a real human utterance carries the transcript marking `findUserMessages()` admits.
  *
  * fail-closed: ANY failure — an unbuilt judge body, an unreadable stdin, a missing or
  * invalid config file — resolves to `{ exitCode: 2 }` with one `blocked` record under the
@@ -26,48 +23,193 @@
  * the cheapest bypass vector there is. Recovery from an unbuilt clone is `pnpm build` (it
  * mentions no protected path, so it is never blocked).
  */
-import { existsSync, readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
+import { mkdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { join, resolve } from 'node:path';
 import { COMMAND_ARGS, evaluatePrecedent, MUTATING_TOOLS, runAdapterPath, SHELL_TOOLS, transcriptFromJsonlFile, transcriptPathFromPayload, } from '@polydeukes/adapter-claude-code';
-import { appendRecordFailOpen, normalizeProtectedPaths } from '@polydeukes/core';
-import { compileDisciplineRegistrations, dispatchCovenants, transcriptModRegistration, ttlWitness, } from '@polydeukes/covenant';
+import { appendRecordFailOpen, DEFAULT_TELEMETRY_LOG_PATH, normalizeProtectedPaths, readRecords, } from '@polydeukes/core';
+import { findUnattributed, readBaseline, snapshotBaseline, ttlWitness, writeBaseline, } from '@polydeukes/covenant';
+import { loadCovenantModule, resolveCovenantDist } from './covenant-module.js';
 import { loadConfig } from './load-config.js';
+/** The label every post-hoc state comparison row carries. */
+const BASELINE_LABEL = 'baseline';
 /**
- * Compose a judge body path and prove it exists (CONFIG-06b §4.2). A body module that was
- * never built makes node exit 1 — the same code a real break verdict returns — so nothing
- * downstream can separate an unjudgeable run from a judged one. The proof therefore belongs
- * to the act of composing the path, and a body this assembly composes no path for is never
- * proven: the throw lands in the fail-closed catch below, one blocked record and exit 2.
+ * 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.
  */
-function provenBodyPath(distDir, fileName) {
-    const modulePath = join(distDir, fileName);
-    if (!existsSync(modulePath)) {
-        throw new Error(`judge body ${modulePath} is missing — run 'pnpm build' to rebuild it`);
+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,
+        });
     }
-    return modulePath;
 }
 /**
- * Judge one declared tool call before it runs (DIST-01 §3-c). Async because the dispatcher
- * spawns covenant bodies (CORE-01) — a synchronous runner would mean reimplementing the
- * judge, which the single-dispatcher principle forbids.
+ * 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 async function runClaudeCodeHook(spec) {
-    // Env-first telemetry precedence (E2E contract), settled BEFORE any failure branch: a
-    // config that never loads still has somewhere to write its one blocked row. The config
-    // value applies after the load succeeds.
+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());
+}
+/**
+ * Where the comparison writes and what it observes, or `undefined`.
+ *
+ * The domain is derived from config rather than enumerated here, and the telemetry path is
+ * resolved by the same precedence the judgment uses so both land in one log. A config that
+ * does not load leaves NO domain, so there is nothing to compare and nothing to re-establish
+ * — the judgment path already answers that failure fail-closed, and a comparison row on top
+ * of it would report the same absence twice under a label that judges nothing.
+ */
+function comparisonSpec(spec) {
+    let config;
+    try {
+        config = loadConfig(spec.repoRoot).config;
+    }
+    catch {
+        return undefined;
+    }
+    return {
+        repoRoot: spec.repoRoot,
+        telemetryPath: spec.telemetryPath ??
+            process.env.POLYDEUKES_TELEMETRY_PATH ??
+            resolve(spec.repoRoot, config.telemetry.logPath),
+        entries: normalizeProtectedPaths({ protectedPaths: config.protectedPaths }),
+    };
+}
+/**
+ * The session surface's registration set. One assembly, two consumers: the runner below
+ * dispatches it, `explain` renders it — so what a reader is shown is the table the judgment
+ * actually uses, never a second opinion about it.
+ */
+export function assembleSessionRegistrations(spec) {
+    const { config, rootDir, covenant, transcriptPath, transcript, witness } = spec;
+    // The live transcript is the evidence channel the context family reads AND the one the
+    // witness reads, so erasing or forging it disables every context discipline while opening
+    // or shutting the human valve on the same file. It must NOT join this list: it lives deep
+    // under HOME, and a path entry makes every ancestor protected — which measured as an
+    // over-block refusing `cd /home/<user>`, `echo $HOME`, and every edit whose content
+    // carried a bare `~`. The dedicated `transcript-mod` registration below covers that one
+    // file instead: equality-only, never an ancestor. Ancestor destruction outside the
+    // repository is out of observation scope — the agent's own deny policy owns what no
+    // repo-scoped judge can reach.
+    const protectedPaths = normalizeProtectedPaths({
+        protectedPaths: config.protectedPaths ?? [],
+    });
+    const disciplines = config.disciplines ?? [];
+    const registrations = [
+        covenant.selfModRegistration({
+            protectedPaths,
+            mutatingToolNames: MUTATING_TOOLS,
+            witness,
+        }),
+        covenant.shellModRegistration({
+            protectedPaths,
+            shellTools: SHELL_TOOLS,
+            commandArgs: COMMAND_ARGS,
+            witness,
+        }),
+        // Routing is the matches predicate, never path mention, so the home directory cannot
+        // become a protected ancestor. No transcript in the payload means nothing to protect —
+        // the valve and the context family already forfeited on the same absence.
+        ...(transcriptPath === undefined
+            ? []
+            : [
+                covenant.transcriptModRegistration({
+                    transcriptPath,
+                    // The env value first, since that is what the judged shell expands `~` and
+                    // `$HOME` from. `homedir()` reads the same passwd entry bash falls back to when
+                    // HOME is unset, so a hook spawned without an environment (a service manager,
+                    // `env -i`) keeps judging the home spellings instead of silently going
+                    // absolute-only — an inert spelling closure looks identical to a passing call.
+                    home: process.env.HOME ?? homedir(),
+                    shellTools: SHELL_TOOLS,
+                    commandArgs: COMMAND_ARGS,
+                    mutatingTools: MUTATING_TOOLS,
+                    witness,
+                }),
+            ]),
+        ...covenant.compileDisciplineRegistrations({
+            disciplines,
+            rootDir,
+            shellTools: SHELL_TOOLS,
+            commandArgs: COMMAND_ARGS,
+            witness,
+            // Context-family evidence is evaluated here, at assembly: a spawned body cannot hold
+            // a transcript, and passing a path would leak JSONL knowledge into covenant. The
+            // adapter brings the evaluator for its own `subagent`/`tool` vocabulary; core owns
+            // `command`, which the compiler judges directly.
+            transcript,
+            evaluatePrecedent,
+        }),
+    ];
+    return registrations;
+}
+/**
+ * Judge one declared tool call before it runs. Async because the dispatcher spawns covenant
+ * bodies — a synchronous runner would mean reimplementing the judge, which the
+ * single-dispatcher principle forbids.
+ */
+async function judgeHookCall(spec) {
+    // Env-first telemetry precedence, settled BEFORE any failure branch: a config that never
+    // loads still has somewhere to write its one blocked row. The config value applies after
+    // the load succeeds.
     //
     // Computed INSIDE the try even though it must run first, because `join` throws on a
     // non-string repoRoot and this function's contract is that nothing escapes it — a rejection
     // would exit a delegator non-blocking, which is the cheapest bypass there is. A throw here
     // leaves `telemetryPath` undefined, which the catch tolerates: there is no root to write a
-    // row under anyway (PR #46 review).
+    // row under anyway.
     let telemetryPath;
     try {
         const envTelemetryPath = process.env.POLYDEUKES_TELEMETRY_PATH;
         telemetryPath =
-            spec.telemetryPath ?? envTelemetryPath ?? join(spec.repoRoot, '.polydeukes', 'roi.log');
+            spec.telemetryPath ?? envTelemetryPath ?? join(spec.repoRoot, DEFAULT_TELEMETRY_LOG_PATH);
         // Discovery + parse + validation are the loader's job; a throw here (absent, ambiguous,
         // unparseable, or invalid config) falls into the fail-closed catch.
         const { config } = loadConfig(spec.repoRoot);
@@ -81,31 +223,14 @@ export async function runClaudeCodeHook(spec) {
         // The transcript path travels in the raw payload only — up-translation drops it, so the
         // adapter reads it from the string. Every failure narrows to `undefined`, which leaves
         // the dispatcher on its `noopTranscript` default: lost evidence closes the valve rather
-        // than opening it (ADAPTER-04 §4.4).
+        // than opening it.
         const transcriptPath = transcriptPathFromPayload(rawPayload);
         const transcript = transcriptPath === undefined ? undefined : transcriptFromJsonlFile(transcriptPath);
-        // The live transcript is the evidence channel the context family reads AND the one the
-        // witness reads, so erasing or forging it disables every context discipline while
-        // opening or shutting the human valve on the same file. It lives outside the repository,
-        // so no config `protectedPaths` entry can reach it — and since COVENANT-07c it does NOT
-        // join this list either. A file deep under HOME makes HOME itself a protected ANCESTOR,
-        // which measured as the COVENANT-13 over-block: `cd /home/<user>` refused for two weeks,
-        // and the 07b attempt to register the home spellings alongside only widened that to
-        // `echo $HOME` and every edit whose content carried a bare `~`. Assembly knows the path
-        // AND the home value, so assembly registers a dedicated `matches` predicate over that
-        // ONE file instead (transcript-mod, below): equality-only — never an ancestor — with the
-        // `~`/`$HOME`/`${HOME}`/`~<user>` spellings closed as data, reads absolved by the
-        // read-only allowlist, and ancestor destruction outside the repository declared out of
-        // observation scope (07c §2: the agent's own deny policy owns what no repo-scoped judge
-        // can). The witness valve applies to it like any other registration.
-        const protectedPaths = normalizeProtectedPaths({
-            protectedPaths: config.protectedPaths ?? [],
-        });
         // One witness predicate shared by every registration: a witness is a session-wide
         // permission the human granted, not a per-covenant one. Absent `witness` config leaves
         // this undefined, and no verdict can be witnessed open at all. The predicate receives
-        // the transcript as its second argument from the dispatcher (CORE-04 seam), which is why
-        // the transcript is injected below rather than captured here.
+        // the transcript as its second argument from the dispatcher, which is why the transcript
+        // is injected below rather than captured here.
         const witness = config.witness === undefined
             ? undefined
             : ttlWitness({
@@ -114,120 +239,82 @@ export async function runClaudeCodeHook(spec) {
                 // Core passes the value through verbatim, so the conversion belongs to assembly.
                 ttlMs: config.witness.ttlMinutes * 60_000,
             });
-        // The judge bodies are the covenant package's dist executables — resolved through the
-        // real package (never a test alias), so the session surface spawns the same judges the
-        // commit surface does. An injected directory overrides that resolution: `createRequire`
-        // is real Node resolution and always lands on the real build, which no fixture tree can
-        // take a body away from.
-        const covenantDist = spec.covenantDist ?? dirname(createRequire(import.meta.url).resolve('@polydeukes/covenant'));
-        // Only the two unconditional registrations compose their paths here. The transcript-mod
-        // and discipline bodies are composed inside the conditions that decide whether their
-        // registrations exist at all — proving a body this run will never spawn would close a
-        // call over a file it was never going to use (CONFIG-06b §4.2 corollary).
-        const selfModBody = provenBodyPath(covenantDist, 'self-mod-body.js');
-        const shellModBody = provenBodyPath(covenantDist, 'shell-mod-body.js');
-        const disciplines = config.disciplines ?? [];
-        const pathArgs = protectedPaths.flatMap((path) => ['--protected-path', path]);
-        const registrations = [
-            {
-                label: 'self-mod',
-                protectedPaths,
-                body: {
-                    command: process.execPath,
-                    args: [
-                        selfModBody,
-                        ...pathArgs,
-                        ...MUTATING_TOOLS.flatMap((tool) => ['--mutating-tool', tool]),
-                    ],
-                },
-                witness,
-            },
-            {
-                label: 'shell-mod',
-                protectedPaths,
-                body: {
-                    command: process.execPath,
-                    args: [
-                        shellModBody,
-                        ...pathArgs,
-                        ...SHELL_TOOLS.flatMap((tool) => ['--shell-tool', tool]),
-                        ...COMMAND_ARGS.flatMap((arg) => ['--command-arg', arg]),
-                    ],
-                },
-                witness,
-            },
-            // The transcript's own registration (COVENANT-07c). Routing is the matches predicate,
-            // never path mention, so the home directory cannot become a protected ancestor. No
-            // transcript in the payload means nothing to protect — the valve and the context
-            // family already forfeited on the same absence.
-            ...(transcriptPath === undefined
-                ? []
-                : [
-                    transcriptModRegistration({
-                        transcriptPath,
-                        // The env value first, since that is what the judged shell expands `~` and
-                        // `$HOME` from. `homedir()` reads the same passwd entry bash falls back to when
-                        // HOME is unset, so a hook spawned without an environment (a service manager,
-                        // `env -i`) keeps judging the home spellings instead of silently going
-                        // absolute-only — an inert spelling closure looks identical to a passing call.
-                        home: process.env.HOME ?? homedir(),
-                        bodyCommand: process.execPath,
-                        bodyModulePath: provenBodyPath(covenantDist, 'transcript-mod-body.js'),
-                        shellTools: SHELL_TOOLS,
-                        commandArgs: COMMAND_ARGS,
-                        mutatingTools: MUTATING_TOOLS,
-                        witness,
-                    }),
-                ]),
-            // The body path is passed as a thunk, so the proof fires only where the compiler
-            // actually composes a body. Entry count cannot stand in for that: an entry may compile
-            // to a body-less skip (a `requirePrecedent` one whenever no transcript came with the
-            // payload), and the compiler appends the body-less `shell-unjudgeable` backstop even
-            // for zero entries — gating the call itself would drop that record and turn an
-            // uncomputable shell write back into a silent pass, undoing COVENANT-10b.
-            ...compileDisciplineRegistrations({
-                disciplines,
-                rootDir: spec.repoRoot,
-                bodyCommand: process.execPath,
-                bodyModulePath: () => provenBodyPath(covenantDist, 'discipline-body.js'),
-                shellTools: SHELL_TOOLS,
-                commandArgs: COMMAND_ARGS,
-                witness,
-                // Context-family evidence is evaluated here, at assembly: a spawned body cannot hold
-                // a transcript, and passing a path would leak JSONL knowledge into covenant
-                // (COVENANT-13 §4.4). The adapter brings the evaluator for its own `subagent`/`tool`
-                // vocabulary; core owns `command`, which the compiler judges directly.
-                transcript,
-                evaluatePrecedent,
-            }),
-        ];
-        // This assembly is versioned with the umbrella; the covenant dist it composes against is
-        // resolved from the installation graph, so a workspace nobody rebuilt pairs a new
-        // assembly with an old compiler — and an old compiler stores the body-path thunk itself
-        // where a string belongs. `spawn` does not reject a non-string argv entry — it
-        // stringifies it — so the judge would be spawned on the thunk's own source text, exit 1,
-        // and be recorded as a VERDICT under a discipline's label. Assert the shape and let the
-        // fail-closed catch answer instead.
-        for (const registration of registrations) {
-            if (registration.body !== undefined && typeof registration.body.args?.[0] !== 'string') {
-                throw new Error(`covenant dist predates the lazy body-path convention (registration '${registration.label}') — run 'pnpm build'`);
-            }
-        }
+        // The judges are the covenant package's built barrel — resolved through the real
+        // package (never a test alias), so the session surface runs the same judges the commit
+        // surface does. An injected directory overrides that resolution, which is how a fixture
+        // reaches a dist that real Node resolution would never land on. Awaited HERE, before
+        // any registration is composed: a dist the barrel cannot load throws now, into the
+        // fail-closed catch, instead of leaving a half-judged table behind.
+        const covenantDist = spec.covenantDist ?? resolveCovenantDist();
+        const covenant = await loadCovenantModule(covenantDist);
+        // Assembled HERE, outside the dispatch seam: a judge takes its call set as an argument,
+        // so assembly needs no payload, and an assembly throw belongs to this function's own
+        // fail-closed catch — `hook` label, `covenant hook failed closed:` on stderr. Composed
+        // inside the dispatch closure it would land in `runAdapterPath`'s catch instead, which
+        // records the adapter's label and says nothing about what broke.
+        const registrations = assembleSessionRegistrations({
+            config,
+            rootDir: spec.repoRoot,
+            covenant,
+            transcriptPath,
+            transcript,
+            witness,
+        });
         return await runAdapterPath({
             rawPayload,
             telemetryPath: logPath,
-            dispatch: (stdinPayload) => dispatchCovenants({ stdinPayload, registrations, telemetryPath: logPath, transcript }),
+            dispatch: (stdinPayload) => covenant.dispatchCovenants({
+                stdinPayload,
+                registrations,
+                telemetryPath: logPath,
+                transcript,
+            }),
         });
     }
     catch (error) {
         process.stderr.write(`covenant hook failed closed: ${error instanceof Error ? error.message : String(error)}\n`);
         // Honor the one-call-one-record invariant with a blocked record under the assembly's own
-        // label (COVENANT-07 §4.3) — never a judge's, since no judge answered. `undefined` means
-        // the failure landed before a path could even be composed (a non-string repoRoot), where
-        // there is nowhere to write and nothing to attribute the row to.
+        // label — never a judge's, since no judge answered. `undefined` means the failure landed
+        // before a path could even be composed (a non-string repoRoot), where there is nowhere
+        // to write and nothing to attribute the row to.
         if (telemetryPath !== undefined) {
             appendRecordFailOpen(telemetryPath, { event: 'blocked', label: 'hook', subject: '-' });
         }
         return { exitCode: 2 };
     }
 }
+/**
+ * The session-surface entry point: the post-hoc state comparison wrapped around the judgment.
+ *
+ * The comparison sits OUTSIDE {@link judgeHookCall}'s fail-closed try on both ends. Inside
+ * it, a comparison failure would become a blocked call — the opposite of a mechanism whose
+ * whole purpose is to record rather than stop — so each side carries its own catch and
+ * neither can reach the verdict. Observation is fail-open, the direction
+ * `appendRecordFailOpen` already established: the worst outcome is a missing datum.
+ *
+ * Order is the contract. The comparison runs first, so it reads the window the previous call
+ * left and its rows land ahead of this call's judgment; the re-establishment runs last, so
+ * this call's own judged writes are folded in rather than alarmed on next time.
+ */
+export async function runClaudeCodeHook(spec) {
+    let comparison;
+    try {
+        comparison = comparisonSpec(spec);
+        if (comparison !== undefined) {
+            compareBaseline(comparison);
+        }
+    }
+    catch {
+        // fail-open: a comparison that could not run leaves the judgment exactly as it was.
+    }
+    const result = await judgeHookCall(spec);
+    try {
+        if (comparison !== undefined) {
+            updateBaseline(comparison);
+        }
+    }
+    catch {
+        // fail-open: an unwritable baseline costs the next call's detection, never this verdict.
+    }
+    return result;
+}

package/dist/covenant-check.d.ts

@@ -1,51 +1,78 @@
 /**
- * `pdks covenant check` — the assembled commit-surface judgment runner (ADAPTER-git §4.3).
+ * `pdks covenant check` — the commit surface's composition root.
  *
- * This is the commit-surface counterpart of the session hook's composition root: the one
- * umbrella-owned place where the git adapter (staged-diff vocabulary), the covenant
- * dispatcher, and the config loader meet. Assembly order mirrors the session hook —
- * loadConfig → normalizeProtectedPaths → collect/translate → dispatchCovenants — and the
- * judge bodies it spawns are the very same covenant dist executables, so a staged change
- * receives the same verdict a session tool call would (AC-4 same-judge).
+ * Assembly mirrors the session hook — loadConfig → normalizeProtectedPaths → collect →
+ * dispatchCovenants — and spawns the same covenant dist bodies, so a change receives the
+ * verdict a session tool call would. Each change is dispatched as its own input so
+ * telemetry stays one row per file. The witness valve is a `/dev/tty` prompt that only
+ * the staged domain assembles; the other domains open no commit.
  *
- * Each staged change is dispatched as its own single-change input: one staged file is
- * the commit surface's analogue of one session tool call, so telemetry stays N:N (AC-6)
- * and `gain` reads a per-file subject rather than one opaque batch line.
- *
- * The valve is a TTY prompt (PRD §4.4 decision A): the injected `ttyPrompt` seam returns
- * the line a human typed at the terminal, compared against the config witness token in
- * FULL (COVENANT-15 — substring acceptance is forbidden). The seam's absence models a
- * non-interactive environment (CI, an AI-spawned git commit): no prompt, no witness —
- * the valve is structurally reachable only by a human at a terminal, which is the
- * commit-surface translation of "only a human utterance opens the session valve". The
- * answer is cached so one commit prompts at most once, and nothing is ever persisted —
- * a state file would be an agent-forgeable surface (PRD §7).
+ * fail-closed: a missing config, an unbuilt body, or a collector failure exits 2 with one
+ * blocked record. An empty domain is an explicit pass with no records.
+ */
+import type { CovenantRegistration } from '@polydeukes/covenant';
+import { type CovenantModule } from './covenant-module.js';
+import { loadConfig } from './load-config.js';
+/**
+ * Which observation of the commit surface a run judges. Only the collector differs between
+ * them; the IR, the assembly, and the dispatcher are one path.
  *
- * fail-closed: a missing/invalid config, an unbuilt judge body, or a collector failure
- * exits 2 with one blocked record when a telemetry path is known. An empty staging area
- * is an explicit pass (nothing to judge — the dispatcher precedent of zero matches, zero
- * records).
+ * `range` names its two refs. `ancestry: 'merge-base'` selects the `A...B` reading, whose
+ * base is the two refs' common ancestor rather than `A` itself; the adapter that owns the
+ * range grammar resolves it.
  */
-/** `runCovenantCheck` input (ADAPTER-git §4.3 — the contract covenant-check tests pin). */
+export type CheckDomain = {
+    kind: 'staged';
+} | {
+    kind: 'worktree';
+} | {
+    kind: 'range';
+    base: string;
+    head: string;
+    ancestry?: 'merge-base';
+};
+/** `runCovenantCheck` input. */
 export type CovenantCheckSpec = {
     /** Repository root — config discovery and staged collection both anchor here. */
     repoRoot: string;
-    /** Overrides the config's telemetry log path (tests and assembly injection). */
+    /**
+     * Overrides where telemetry is written (tests and assembly injection) — the first term
+     * of the precedence, ahead of the config's `telemetry.logPath` and of the default this
+     * runner settles before the config loads. Absent, both of those apply in that order.
+     */
     telemetryPath?: string;
     /** Overrides the resolved covenant dist directory (tests and assembly injection). */
     covenantDist?: string;
     /**
      * TTY valve seam: writes the given prompt and returns the line a human typed, or null
-     * for no input. ABSENT means a non-TTY environment — the valve never opens (AC-3
-     * human-only arming).
+     * for no input. ABSENT means a non-TTY environment — the valve never opens, which is
+     * what keeps it human-only.
      */
     ttyPrompt?: (prompt: string) => string | null;
+    /** Which observation to judge. ABSENT means `staged`. */
+    domain?: CheckDomain;
 };
+/** {@link assembleCommitRegistrations} input — what the commit surface's assembly needs. */
+export type CommitAssemblySpec = {
+    config: ReturnType<typeof loadConfig>['config'];
+    rootDir: string;
+    /**
+     * The covenant surface the registrations are built from — the module the caller loaded
+     * from the resolved dist, so what judges a change is what that dist carries, and what
+     * `explain` renders is what would judge it.
+     */
+    covenant: CovenantModule;
+    witness?: CovenantRegistration['witness'];
+};
+/**
+ * The commit surface's registration set — one assembly that the runner dispatches and
+ * `explain` renders.
+ */
+export declare function assembleCommitRegistrations(spec: CommitAssemblySpec): CovenantRegistration[];
 /**
- * Judge the staged changes of `repoRoot` exactly as the session surface would
- * (ADAPTER-git §4.3). Async because the dispatcher spawns covenant bodies (CORE-01) —
- * a synchronous runner would mean reimplementing the judge, which the single-dispatcher
- * principle forbids.
+ * Judge one observation of `repoRoot` exactly as the session surface would — the staged
+ * diff by default, the working tree or a ref range on request. Async because the dispatcher
+ * spawns covenant bodies. An empty domain is an explicit pass: nothing to judge, no records.
  */
 export declare function runCovenantCheck(spec: CovenantCheckSpec): Promise<{
     exitCode: 0 | 2;