polydeukes 0.4.0 → 0.6.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,33 +23,21 @@
  * 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, mkdirSync, 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 { COMMAND_ARGS, evaluatePrecedent, MUTATING_TOOLS, runAdapterPath, SHELL_TOOLS, transcriptFromJsonlFile, transcriptPathFromPayload, } from '@polydeukes/adapter-claude-code';
-import { appendRecordFailOpen, DEFAULT_TELEMETRY_LOG_PATH, normalizeProtectedPaths, readRecords, } from '@polydeukes/core';
-import { compileDisciplineRegistrations, dispatchCovenants, findUnattributed, readBaseline, snapshotBaseline, transcriptModRegistration, ttlWitness, writeBaseline, } from '@polydeukes/covenant';
+import { join, resolve } from 'node:path';
+import { COMMAND_ARGS, MUTATING_TOOLS, runAdapterPath, SHELL_TOOLS, sessionChannelReader, sessionSourceReader, transcriptFromJsonlFile, transcriptPathFromPayload, } from '@polydeukes/adapter-claude-code';
+import { appendRecordFailOpen, DEFAULT_TELEMETRY_LOG_PATH, isPlainObject, normalizeProtectedPaths, readRecords, } from '@polydeukes/core';
+import { ttlWitness } from '@polydeukes/covenant';
+import { findUnattributed, readBaseline, snapshotBaseline, writeBaseline } from './baseline.js';
+import { loadCovenantModule, resolveCovenantDist } from './covenant-module.js';
 import { loadConfig } from './load-config.js';
-/**
- * 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.
- */
-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`);
-    }
-    return modulePath;
-}
-/** The label every post-hoc state comparison row carries (COVENANT-14 §2-d). */
+import { sessionPreStateReader } from './pre-state-reader.js';
+/** The label every post-hoc state comparison row carries. */
 const BASELINE_LABEL = 'baseline';
 /**
  * Compare the protected entries' on-disk state against the stored baseline and record what
- * moved with no judgment explaining it (COVENANT-14 §2-f).
+ * 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 —
@@ -68,9 +53,9 @@ function compareBaseline(spec) {
     const { records } = readRecords(spec.telemetryPath);
     const stored = readBaseline(baselinePath);
     if (stored === null) {
-        // Absence and corruption are the same signal (§2-e). The baseline file is deliberately
-        // 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.
+        // 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,
@@ -96,7 +81,7 @@ function compareBaseline(spec) {
     }
 }
 /**
- * Re-establish the baseline at hook call END (COVENANT-14 §5).
+ * 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
@@ -115,7 +100,7 @@ function updateBaseline(spec) {
     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` (COVENANT-14 §6).
+ * 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
@@ -126,7 +111,7 @@ function updateBaseline(spec) {
 function comparisonSpec(spec) {
     let config;
     try {
-        config = loadConfig(spec.repoRoot).config;
+        config = loadConfig({ rootDir: spec.repoRoot }).config;
     }
     catch {
         return undefined;
@@ -140,20 +125,127 @@ function comparisonSpec(spec) {
     };
 }
 /**
- * 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.
+ * 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 session a history declaration reads AND the one the witness
+    // reads, so erasing or forging it disables every history 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 every history declaration 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,
+            readPreState: sessionPreStateReader,
+            // One PreToolUse call is the whole observation, so the derived change set is a
+            // singleton and a change-set declaration cannot be judged here — it records `skipped`,
+            // the shape the commit surface gives a history declaration.
+            observesChangeSet: false,
+            witness,
+            // The session itself, injected rather than its path: a declaration reading a
+            // `transcript` binding sees it flattened, and passing a path would leak JSONL
+            // knowledge into covenant.
+            transcript,
+        }),
+    ];
+    return registrations;
+}
+/**
+ * This runtime's mutating+shell roster, rewritten onto the Claude vocabulary the adapter
+ * already judges. Claude names are not keys, so an existing Write/Edit/Bash envelope
+ * passes through. A name outside the table is left alone — that is a declared limit,
+ * recorded as the adapter's funnel pass, never a parse fault. The map lives here, not in
+ * the adapter, so the adapter stays Claude-vocabulary-only.
+ */
+const GROK_TOOL_NAME_MAP = {
+    write: 'Write',
+    search_replace: 'Edit',
+    run_terminal_command: 'Bash',
+};
+/**
+ * Rewrite Grok tool names in a raw PreToolUse payload. Invalid JSON is left as the original
+ * string so the existing fail-closed path still runs — this function must not throw.
+ */
+function rewriteGrokToolNames(rawPayload) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawPayload);
+    }
+    catch {
+        return rawPayload;
+    }
+    if (!isPlainObject(parsed))
+        return rawPayload;
+    for (const key of ['tool_name', 'toolName']) {
+        const value = parsed[key];
+        if (typeof value !== 'string')
+            continue;
+        const mapped = GROK_TOOL_NAME_MAP[value];
+        if (mapped !== undefined)
+            parsed[key] = mapped;
+    }
+    return JSON.stringify(parsed);
+}
+/**
+ * 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 (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.
+    // 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;
@@ -161,42 +253,25 @@ async function judgeHookCall(spec) {
             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);
+        const { config } = loadConfig({ rootDir: spec.repoRoot });
         telemetryPath =
             spec.telemetryPath ?? envTelemetryPath ?? resolve(spec.repoRoot, config.telemetry.logPath);
         // Settled for the rest of the happy path. The `let` above exists so the catch can still
         // record when a failure lands before this point; a closure cannot narrow it, so the
         // dispatch seam below takes this const instead.
         const logPath = telemetryPath;
-        const rawPayload = spec.rawPayload ?? readFileSync(0, 'utf-8');
+        const rawPayload = rewriteGrokToolNames(spec.rawPayload ?? readFileSync(0, 'utf-8'));
         // 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).
-        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 ?? [],
-        });
+        // than opening it.
+        const transcriptPath = transcriptPathFromPayload({ rawPayload });
+        const transcript = transcriptPath === undefined ? undefined : transcriptFromJsonlFile({ path: transcriptPath });
         // 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({
@@ -205,117 +280,55 @@ async function judgeHookCall(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,
+        });
+        // The world axis: files read from disk under the repository root, channels read beside
+        // the session's transcript. The disk is the pre-edit state on this surface; the rule
+        // that the judged change's own `post` overrides it belongs to the judge, so the root
+        // supplies what it read and nothing more. No `changes` list either — one PreToolUse call
+        // is the whole observation, and the judge derives that set from the input.
+        const { files, channels } = covenant.supplySources({
+            plan: covenant.planSources({ registrations }),
+            read: sessionSourceReader({ repoRoot: spec.repoRoot }),
+            readChannel: sessionChannelReader({ transcriptPath }),
+        });
         return await runAdapterPath({
             rawPayload,
             telemetryPath: logPath,
-            dispatch: (stdinPayload) => dispatchCovenants({ stdinPayload, registrations, telemetryPath: logPath, transcript }),
+            dispatch: (stdinPayload) => covenant.dispatchCovenants({
+                stdinPayload,
+                registrations,
+                telemetryPath: logPath,
+                transcript,
+                world: { files, channels },
+            }),
         });
     }
     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: '-' });
         }
@@ -323,8 +336,7 @@ async function judgeHookCall(spec) {
     }
 }
 /**
- * The session-surface entry point: the post-hoc state comparison wrapped around the judgment
- * (COVENANT-14 §2-f).
+ * 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

package/dist/claude-code.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `polydeukes/claude-code` — the session surface's entry point.
+ *
+ * The delegator a consumer project's PreToolUse hook imports: one verb and its spec type.
+ */
+export { type ClaudeCodeHookOutcome, type ClaudeCodeHookSpec, runClaudeCodeHook, } from './claude-code-hook.ts';

package/dist/claude-code.js

@@ -0,0 +1,6 @@
+/**
+ * `polydeukes/claude-code` — the session surface's entry point.
+ *
+ * The delegator a consumer project's PreToolUse hook imports: one verb and its spec type.
+ */
+export { runClaudeCodeHook, } from './claude-code-hook.js';

package/dist/covenant-check.d.ts

@@ -1,58 +1,72 @@
 /**
- * `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 Observation } from '@polydeukes/adapter-git';
+import type { CovenantRegistration } from '@polydeukes/covenant';
+import { type CovenantModule } from './covenant-module.ts';
+import { loadConfig } from './load-config.ts';
+/**
+ * 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. The telemetry path is settled before the first failure
- * branch can be taken (ADAPTER-git-b §4.1), so the record has somewhere to land even when
- * the config that names its path never loaded. An empty staging area is an explicit pass
- * (nothing to judge — the dispatcher precedent of zero matches, zero records).
+ * The adapter that owns the git grammar owns the type: its supply body reads a path the way
+ * each observation sees the tree, and this root names the same fact for its callers.
  */
-/** `runCovenantCheck` input (ADAPTER-git §4.3 — the contract covenant-check tests pin). */
+export type CheckDomain = Observation;
+/** {@link runCovenantCheck} result — the exit code the check process leaves with. */
+export type CovenantCheckOutcome = {
+    exitCode: 0 | 2;
+};
+/** `runCovenantCheck` input. */
 export type CovenantCheckSpec = {
     /** Repository root — config discovery and staged collection both anchor here. */
     repoRoot: string;
     /**
      * 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 (ADAPTER-git-b §4.1). Absent, both of those
-     * apply in that order.
+     * 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'];
 };
 /**
- * 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.
+ * The commit surface's registration set — one assembly that the runner dispatches and
+ * `explain` renders.
  */
-export declare function runCovenantCheck(spec: CovenantCheckSpec): Promise<{
-    exitCode: 0 | 2;
-}>;
+export declare function assembleCommitRegistrations(spec: CommitAssemblySpec): CovenantRegistration[];
+/**
+ * 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<CovenantCheckOutcome>;