polydeukes 0.3.0 → 0.5.0

package/dist/covenant-check.js

@@ -1,57 +1,27 @@
 /**
- * `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/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).
+ * 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 { existsSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { dirname, join, resolve } from 'node:path';
-import { collectStagedChanges, covenantInputFromStagedChanges, resolveGitAdapterSettings, STAGED_DELETE, STAGED_WRITE, } from '@polydeukes/adapter-git';
-import { appendRecord, normalizeProtectedPaths } from '@polydeukes/core';
-import { compileDisciplineRegistrations, dispatchCovenants, } from '@polydeukes/covenant';
+import { resolve } from 'node:path';
+import { collectRangeChanges, collectStagedChanges, collectWorktreeChanges, covenantInputFromStagedChanges, resolveGitAdapterSettings, STAGED_DELETE, STAGED_WRITE, } from '@polydeukes/adapter-git';
+import { appendRecordFailOpen, DEFAULT_TELEMETRY_LOG_PATH, normalizeProtectedPaths, } from '@polydeukes/core';
+import { loadCovenantModule, resolveCovenantDist } from './covenant-module.js';
 import { loadConfig } from './load-config.js';
 /**
- * Build the witness predicate for the TTY valve, or undefined when no valve can exist
- * (no witness configured, or no TTY seam — both leave the dispatcher with no way to open
- * one at all). The valve IS the witness: the judge has already broken, and the human at
- * the terminal supplies the pass condition themselves, sudo-style. The prompt fires
- * lazily on the first registration that actually BROKE and names it from the dispatcher's
- * context (COVENANT-17 §4.5) — the label and the MATCHED entry, the same subject the
- * telemetry row carries, so screen and log never disagree. The human reads what broke,
- * on what, and how far one answer reaches. The verdict is cached: one commit, at most
- * one prompt, full-token equality only — and the token itself is never printed, or
- * typing it from memory would become copying it off the screen.
- *
- * Both comparison sides are trimmed, mirroring the session valve: `ttlWitness` trims the
- * config token at assembly precisely because config validation accepts a padded value,
- * and it compares the utterance's first line trimmed — without the same normalisation
- * here, one padded token would open the session surface and permanently shut this one
- * (PR #41 review). The cache latches CLOSED before the seam is consulted: a throwing
- * seam must not retry on the next broken registration, or the prompt's own commit-wide
- * promise becomes a lie (AC §5.3 one commit, at most one prompt).
+ * The TTY witness predicate, or undefined when no valve can exist (no witness configured
+ * or no TTY seam). It fires on the first registration that broke, names it from the
+ * dispatcher's context, and caches the answer: one commit, at most one prompt, full-token
+ * equality. Both sides are trimmed like the session valve, since config validation accepts
+ * a padded token. The cache latches closed before the seam is consulted so a throwing seam
+ * never re-prompts.
  */
 function ttyWitnessValve(witness, ttyPrompt) {
     if (witness === undefined || ttyPrompt === undefined)
@@ -71,150 +41,123 @@ function ttyWitnessValve(witness, ttyPrompt) {
     };
 }
 /**
- * Compose a judge body's module path and prove the file is there (CONFIG-06b §4.2).
- * Spawning an absent module succeeds and its child exits 1 — the code a break verdict
- * returns — so a judge that ran no line would arrive as a violation and, under `advise`,
- * be waved through. Nothing downstream can separate the two (`translateExitCode` sees
- * that number alone), so the proof happens here, before the spawn. Producing the path
- * and proving it are one step on purpose: a path that skipped the proof cannot be
- * constructed, and only the bodies this surface actually composes are proven.
+ * One blocked record for a run that failed closed before any dispatch could judge.
+ * `appendRecordFailOpen` creates the missing `.polydeukes/` of a never-judged repository,
+ * and a telemetry failure never softens the exit. An undefined path (non-string
+ * `repoRoot`) leaves no root to write under.
  */
-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;
-}
-/** One blocked record for a run that failed closed before any dispatch could judge. */
 function recordFailClosed(telemetryPath) {
     if (telemetryPath === undefined)
         return;
-    try {
-        appendRecord(telemetryPath, {
-            timestamp: new Date().toISOString(),
-            event: 'blocked',
-            label: 'covenant-check',
-            subject: '-',
-        });
-    }
-    catch {
-        // A telemetry failure must never soften the blocking exit (session-hook precedent).
-    }
+    appendRecordFailOpen(telemetryPath, {
+        event: 'blocked',
+        label: 'covenant-check',
+        subject: '-',
+    });
 }
 /**
- * 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 async function runCovenantCheck(spec) {
-    let config;
-    try {
-        ({ config } = loadConfig(spec.repoRoot));
-    }
-    catch (error) {
-        process.stderr.write(`covenant check failed closed: ${error instanceof Error ? error.message : String(error)}\n`);
-        recordFailClosed(spec.telemetryPath);
-        return { exitCode: 2 };
-    }
-    const telemetryPath = spec.telemetryPath ?? resolve(spec.repoRoot, config.telemetry.logPath);
-    let changes;
+export function assembleCommitRegistrations(spec) {
+    const { config, rootDir, covenant, witness } = spec;
+    const { protectedPaths: gitAdditivePaths } = resolveGitAdapterSettings(config.adapters?.git);
+    // Union of the common list and the git-additive one, common first so first-occurrence
+    // dedupe is deterministic. The session hook reads the common list alone.
+    const protectedPaths = normalizeProtectedPaths({
+        protectedPaths: [...(config.protectedPaths ?? []), ...gitAdditivePaths],
+    });
+    const disciplines = config.disciplines ?? [];
+    const registrations = [
+        covenant.selfModRegistration({
+            protectedPaths,
+            mutatingToolNames: [STAGED_WRITE, STAGED_DELETE],
+            witness,
+        }),
+        // No shell axis here, so command-family entries are left out. Context-family entries
+        // stay in: with no transcript the compiler gives them skip registrations, which record
+        // `skipped` on a match.
+        ...covenant.compileDisciplineRegistrations({
+            disciplines: disciplines.filter((entry) => entry.forbidCommand === undefined),
+            rootDir,
+            shellTools: [],
+            commandArgs: [],
+            witness,
+        }),
+    ];
+    return registrations;
+}
+/** One stage's failure disposition: the stderr line, the recorded row, and exit 2. */
+function failClosed(telemetryPath, error) {
+    process.stderr.write(`covenant check failed closed: ${error instanceof Error ? error.message : String(error)}\n`);
+    recordFailClosed(telemetryPath);
+    return { exitCode: 2 };
+}
+/**
+ * Settle the telemetry path and load the config once, or fail closed. The provisional
+ * path is settled before the load so a config that never loads still has somewhere to
+ * write its blocked row; both terms use `resolve` so a relative `repoRoot` cannot send
+ * them to different files. The provisional term sits inside the try because `resolve`
+ * throws on a non-string `repoRoot`.
+ */
+function settleConfig(spec) {
+    let telemetryPath;
     try {
-        changes = collectStagedChanges(spec.repoRoot);
+        telemetryPath = spec.telemetryPath ?? resolve(spec.repoRoot, DEFAULT_TELEMETRY_LOG_PATH);
+        const { config } = loadConfig(spec.repoRoot);
+        telemetryPath = spec.telemetryPath ?? resolve(spec.repoRoot, config.telemetry.logPath);
+        return { settled: true, telemetryPath, config };
     }
     catch (error) {
-        process.stderr.write(`covenant check failed closed: ${error instanceof Error ? error.message : String(error)}\n`);
-        recordFailClosed(telemetryPath);
-        return { exitCode: 2 };
+        return { settled: false, ...failClosed(telemetryPath, error) };
     }
-    if (changes.length === 0) {
-        return { exitCode: 0 };
+}
+/**
+ * Collect the changes of one domain. The three collectors return the same shape, so
+ * everything downstream of this dispatch is one path.
+ */
+function collectDomain(repoRoot, domain) {
+    if (domain.kind === 'worktree')
+        return collectWorktreeChanges(repoRoot);
+    if (domain.kind === 'range') {
+        const separator = domain.ancestry === 'merge-base' ? '...' : '..';
+        return collectRangeChanges(repoRoot, `${domain.base}${separator}${domain.head}`);
     }
-    // Everything from here on is judgment assembly and dispatch: any throw (an unbuilt or
-    // unresolvable covenant dist, a registration-build failure) is unjudgeable and must
-    // both block AND leave one blocked record — the session hook's one-call-one-record
-    // invariant, which an unrecorded propagation to the bin's catch would narrow
-    // (review F5).
+    return collectStagedChanges(repoRoot);
+}
+/**
+ * Assemble the registrations and dispatch every collected change. Any throw here (an
+ * unbuilt dist, a registration-build failure) is unjudgeable: block and leave one record.
+ */
+async function judgeChanges(spec, domain, telemetryPath, config, changes) {
     try {
-        // The adapter namespace validator throws on unknown levels/keys (CONFIG-06 §4.2) —
-        // resolved inside this try so a misconfiguration fails closed, never softens.
-        const { enforce, protectedPaths: gitAdditivePaths } = resolveGitAdapterSettings(config.adapters?.git);
-        // The commit surface judges the UNION of the common list and the git namespace's
-        // additive one (CONFIG-08 §4.2) — common first, so first-occurrence dedupe inside
-        // the one normalization pass is deterministic. The session hook reads the common
-        // list alone; that asymmetry is the contract, not an omission.
-        const protectedPaths = normalizeProtectedPaths({
-            protectedPaths: [...(config.protectedPaths ?? []), ...gitAdditivePaths],
-        });
-        // The judge bodies are the covenant package's dist executables — resolved through
-        // the real package (never a test alias), so the commit surface spawns the same
-        // judges the session hook does. An injected directory overrides that resolution:
-        // `createRequire` is real Node resolution and always lands on the real build, which
-        // no fixture can take a body away from.
-        const covenantDist = spec.covenantDist ?? dirname(createRequire(import.meta.url).resolve('@polydeukes/covenant'));
-        // Under advise the TTY valve is structurally absent (CONFIG-06 §4.6): a verdict
-        // already passes, so there is nothing to witness and the prompt must never fire.
-        const witness = enforce === 'advise' ? undefined : ttyWitnessValve(config.witness, spec.ttyPrompt);
-        const disciplines = config.disciplines ?? [];
-        const registrations = [
-            {
-                label: 'self-mod',
-                protectedPaths,
-                body: {
-                    command: process.execPath,
-                    args: [
-                        provenBodyPath(covenantDist, 'self-mod-body.js'),
-                        ...protectedPaths.flatMap((path) => ['--protected-path', path]),
-                        ...[STAGED_WRITE, STAGED_DELETE].flatMap((tool) => ['--mutating-tool', tool]),
-                    ],
-                },
-                witness,
-            },
-            // Command-family entries are excluded: the commit surface has no shell axis (a
-            // staged diff carries no commands), so registering them would be spawn waste by
-            // design (PRD §2) — a vacuous exclusion, hence recorded nowhere. Path and delta
-            // families judge the staged fileChanges as-is.
-            //
-            // Context-family entries are NOT filtered out any more. No transcript is injected
-            // here, so the compiler gives them skip registrations, and a skip records one
-            // `skipped` exactly when its trigger matches a staged change (COVENANT-13 §4.5).
-            // The commit surface stopped being a special case: an absent evidence channel gets
-            // the same disposition on both surfaces, and the scope gate comes free with the
-            // routing every registration already carries.
-            //
-            // The body path is passed as a thunk, so the proof fires only where the compiler
-            // actually composes a body (CONFIG-06b §4.2 corollary). Entry count cannot stand in
-            // for that: an entry may compile to a body-less skip — every `requirePrecedent` one
-            // does here, since this surface injects neither transcript nor evaluator — and the
-            // compiler appends the body-less `shell-unjudgeable` backstop even for zero entries,
-            // so gating the call itself would drop that record.
-            ...compileDisciplineRegistrations({
-                disciplines: disciplines.filter((entry) => entry.forbidCommand === undefined),
-                rootDir: spec.repoRoot,
-                bodyCommand: process.execPath,
-                bodyModulePath: () => provenBodyPath(covenantDist, 'discipline-body.js'),
-                shellTools: [],
-                commandArgs: [],
-                witness,
-            }),
-        ];
-        // The commit surface resolves the compiler through the installed package, so a
-        // workspace whose dist predates the lazy body-path convention hands back the thunk
-        // itself where a string belongs. `spawn` stringifies rather than rejects it, which
-        // would spawn the judge on the thunk's own source text and record the exit 1 as a
-        // verdict under a discipline's label — the confusion this ticket removes, arriving
-        // through the build-skew door. Assert the shape and let the fail-closed catch answer.
-        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'`);
-            }
-        }
+        // Inside the try so an invalid adapter namespace fails closed.
+        const { enforce } = resolveGitAdapterSettings(config.adapters?.git);
+        // Real Node resolution of the covenant package, so the commit surface runs the same
+        // judges the session hook does; tests inject a directory instead. Awaited before any
+        // registration is composed, so a dist the barrel cannot load fails the run closed here
+        // rather than leaving a half-judged table behind.
+        const covenantDist = spec.covenantDist ?? resolveCovenantDist();
+        const covenant = await loadCovenantModule(covenantDist);
+        // No valve under advise (nothing to witness) and none outside `staged`.
+        const witness = enforce === 'advise' || domain.kind !== 'staged'
+            ? undefined
+            : ttyWitnessValve(config.witness, spec.ttyPrompt);
         let blocked = false;
         let advisedCount = 0;
+        // Assembled ONCE for the run, not per change: a judge takes its call set as an argument,
+        // so the table is payload-free. Recompiling per file would repeat every compile-time
+        // side effect — the stderr line a config-faulted discipline names itself with would
+        // print once per staged file rather than once.
+        const registrations = assembleCommitRegistrations({
+            config,
+            rootDir: spec.repoRoot,
+            covenant,
+            witness,
+        });
         for (const change of changes) {
             const input = covenantInputFromStagedChanges([change]);
-            const { exitCode, results } = await dispatchCovenants({
+            const { exitCode, results } = await covenant.dispatchCovenants({
                 stdinPayload: JSON.stringify(input),
                 registrations,
                 telemetryPath,
@@ -225,14 +168,37 @@ export async function runCovenantCheck(spec) {
                 blocked = true;
             advisedCount += results.filter((result) => result.event === 'advised').length;
         }
+        // Names no level: surface-level and entry-level advice mix in one run, so the commit's
+        // fate is read from the run.
         if (advisedCount > 0) {
-            process.stderr.write(`covenant advisory (enforce: advise): ${advisedCount} verdict(s) recorded, commit allowed\n`);
+            const outcome = blocked ? 'commit blocked by another verdict' : 'commit allowed';
+            process.stderr.write(`covenant advisory: ${advisedCount} verdict(s) recorded as advised, ${outcome}\n`);
         }
         return { exitCode: blocked ? 2 : 0 };
     }
     catch (error) {
-        process.stderr.write(`covenant check failed closed: ${error instanceof Error ? error.message : String(error)}\n`);
-        recordFailClosed(telemetryPath);
-        return { exitCode: 2 };
+        return failClosed(telemetryPath, error);
     }
 }
+/**
+ * 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 async function runCovenantCheck(spec) {
+    const settlement = settleConfig(spec);
+    if (!settlement.settled)
+        return { exitCode: settlement.exitCode };
+    const { telemetryPath, config } = settlement;
+    const domain = spec.domain ?? { kind: 'staged' };
+    let changes;
+    try {
+        changes = collectDomain(spec.repoRoot, domain);
+    }
+    catch (error) {
+        return failClosed(telemetryPath, error);
+    }
+    if (changes.length === 0)
+        return { exitCode: 0 };
+    return judgeChanges(spec, domain, telemetryPath, config, changes);
+}

package/dist/covenant-module.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The covenant package as a resolved artifact — the existence proof both composition roots
+ * share.
+ *
+ * What the roots prove is the package IMPORT itself. The barrel is eager: a dist missing one
+ * of the modules it references throws on import, before any assembly can compose a
+ * registration, and the surface's own fail-closed catch records that as one `blocked` row. A
+ * partially loaded judge set has no representation here — an ESM import either fully succeeds
+ * or throws.
+ *
+ * The `covenantDist` seam selects WHICH dist is imported, so a fixture can inject a gutted
+ * mirror where real Node resolution would always land on the healthy build.
+ */
+import type * as covenant from '@polydeukes/covenant';
+/** The covenant surface both roots assemble against. */
+export type CovenantModule = typeof covenant;
+/** Where real Node resolution puts the covenant package's built barrel. */
+export declare function resolveCovenantDist(): string;
+/**
+ * Import the covenant barrel from `distDir`, naming the recovery command when it will not
+ * load. The message carries the loader's own text, which names the module that is missing;
+ * a reader locked out by an unbuilt or half-built dist needs both that name and the one
+ * command that fixes it.
+ */
+export declare function loadCovenantModule(distDir: string): Promise<CovenantModule>;

package/dist/covenant-module.js

@@ -0,0 +1,34 @@
+/**
+ * The covenant package as a resolved artifact — the existence proof both composition roots
+ * share.
+ *
+ * What the roots prove is the package IMPORT itself. The barrel is eager: a dist missing one
+ * of the modules it references throws on import, before any assembly can compose a
+ * registration, and the surface's own fail-closed catch records that as one `blocked` row. A
+ * partially loaded judge set has no representation here — an ESM import either fully succeeds
+ * or throws.
+ *
+ * The `covenantDist` seam selects WHICH dist is imported, so a fixture can inject a gutted
+ * mirror where real Node resolution would always land on the healthy build.
+ */
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** Where real Node resolution puts the covenant package's built barrel. */
+export function resolveCovenantDist() {
+    return join(createRequire(import.meta.url).resolve('@polydeukes/covenant'), '..');
+}
+/**
+ * Import the covenant barrel from `distDir`, naming the recovery command when it will not
+ * load. The message carries the loader's own text, which names the module that is missing;
+ * a reader locked out by an unbuilt or half-built dist needs both that name and the one
+ * command that fixes it.
+ */
+export async function loadCovenantModule(distDir) {
+    try {
+        return (await import(pathToFileURL(join(distDir, 'index.js')).href));
+    }
+    catch (error) {
+        throw new Error(`the covenant judges could not be loaded from ${distDir} — run 'pnpm build' to rebuild them: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}