polydeukes 0.6.1 → 0.7.1

package/dist/covenant-check.js

@@ -1,46 +1,25 @@
 /**
- * `pdks covenant check` — the commit surface's composition root.
+ * `pdks covenant check` — the composition root both surfaces' callers reach through the bin.
  *
- * 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.
+ * The judged unit is the input IR the caller hands in; this root opens no repository. Assembly
+ * mirrors the session hook — loadConfig → normalizeProtectedPaths → dispatchCovenants — and
+ * runs the same judge bodies, so a change receives the verdict a session tool call would.
+ * Each toolCall is dispatched as its own input so telemetry stays one row per file.
  *
- * 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.
+ * fail-closed: a missing config, an input that could not be produced, or an input carrying its
+ * own `world` exits 2 with one blocked record. An input with no toolCalls is an explicit pass
+ * with no records.
  */
+import { homedir } from 'node:os';
 import { resolve } from 'node:path';
-import { collectRangeChanges, collectStagedChanges, collectWorktreeChanges, covenantInputFromStagedChanges, observationSourceReader, 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 { appendRecordFailOpen, DEFAULT_TELEMETRY_LOG_PATH, isPlainObject, normalizeProtectedPaths, transcriptFromSession, } from '@polydeukes/core';
+import { compareBaseline, updateBaseline } from './baseline.js';
+import { covenantModule } from './covenant/module.js';
+import { ttlWitness } from './covenant/ttl-witness.js';
+import { STAGED_DELETE, STAGED_WRITE } from './diff-ir.js';
 import { loadConfig } from './load-config.js';
-import { unobservedPreStateReader } from './pre-state-reader.js';
-/**
- * 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)
-        return undefined;
-    const token = witness.token.trim();
-    let verdict;
-    return (_input, _transcript, context) => {
-        if (verdict === undefined) {
-            const prompt = `covenant: '${context.label}' broke on the staged change matching '${context.subject}'.\n` +
-                'answering opens the valve for the whole commit, not just this change.\n' +
-                'type the agreed token in full to open it (enter to refuse): ';
-            verdict = false;
-            const answer = ttyPrompt(prompt);
-            verdict = answer !== null && answer.trim() === token;
-        }
-        return verdict;
-    };
-}
+import { sessionPreStateReader, unobservedPreStateReader } from './pre-state-reader.js';
+import { worktreeReader } from './worktree-reader.js';
 /**
  * One blocked record for a run that failed closed before any dispatch could judge.
  * `appendRecordFailOpen` creates the missing `.polydeukes/` of a never-judged repository,
@@ -57,38 +36,85 @@ function recordFailClosed(telemetryPath) {
     });
 }
 /**
- * The commit surface's registration set — one assembly that the runner dispatches and
- * `explain` renders.
+ * This runner's registration set — one assembly that the runner dispatches and `explain`
+ * renders.
+ *
+ * The surface picks the discipline lists; the two IR keys shape the meta-covenants and
+ * nothing else — the roster says which names route to which meta-covenant, and the session
+ * says whether there is history to protect, to bind, and to read pre-state from disk for.
  */
-export function assembleCommitRegistrations(spec) {
-    const { config, rootDir, covenant, witness } = spec;
-    const { protectedPaths: gitAdditivePaths } = resolveGitAdapterSettings({
-        namespace: 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 ?? [];
+export function assembleCheckRegistrations(spec) {
+    const { config, rootDir, covenant, surface, tools, session, transcript, witness } = spec;
+    const protectedPaths = normalizeProtectedPaths({ protectedPaths: config.protectedPaths ?? [] });
+    // The shared list first, so both surfaces read the same prefix in the rows and in
+    // `pdks explain`.
+    const surfaceDisciplines = surface === 'session' ? config.sessionDisciplines : config.changeSetDisciplines;
+    const disciplines = [...(config.disciplines ?? []), ...(surfaceDisciplines ?? [])];
+    const shellTools = tools?.shell ?? [];
+    const commandArgs = tools?.commandArgs ?? [];
+    const evidencePath = session?.evidencePath;
+    // An EMPTY roster is a host that declared it has no mutating tool, so only an ABSENT
+    // `tools` falls back to the staged names — a length check would route names no host call
+    // carries. The declared emptiness leaves no tool axis to register, the same way an empty
+    // shell roster leaves no shell axis.
+    const mutatingToolNames = tools?.mutating ?? [STAGED_WRITE, STAGED_DELETE];
     const registrations = [
-        covenant.selfModRegistration({
-            protectedPaths,
-            mutatingToolNames: [STAGED_WRITE, STAGED_DELETE],
-            witness,
-        }),
+        ...(mutatingToolNames.length === 0
+            ? []
+            : [covenant.selfModRegistration({ protectedPaths, mutatingToolNames, witness })]),
+        // No shell tool is no shell axis, not a shell axis over nothing: registering it with an
+        // empty roster would judge a command line the host said it has no tool for.
+        ...(shellTools.length === 0
+            ? []
+            : [covenant.shellModRegistration({ protectedPaths, shellTools, commandArgs, witness })]),
+        // The evidence file is what the witness and every history declaration read, so a call
+        // rewriting it could forge its own permission. Nothing to protect where the host named
+        // no evidence path.
+        ...(evidencePath === undefined
+            ? []
+            : [
+                covenant.transcriptModRegistration({
+                    transcriptPath: evidencePath,
+                    // 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.
+                    home: process.env.HOME ?? homedir(),
+                    shellTools,
+                    commandArgs,
+                    mutatingTools: mutatingToolNames,
+                    witness,
+                }),
+            ]),
         ...covenant.compileDisciplineRegistrations({
             disciplines,
             rootDir,
-            shellTools: [],
-            commandArgs: [],
-            readPreState: unobservedPreStateReader,
-            observesChangeSet: true,
+            shellTools,
+            commandArgs,
+            // A session call is judged before its tool runs, so the working tree IS the pre-state;
+            // without one the input carries the pre its own observation saw.
+            readPreState: session === undefined ? unobservedPreStateReader : sessionPreStateReader,
+            // That reader answers nothing, so the surface has no pre-state channel to complete a
+            // shell write's evidence with. Saying so keeps the absence an environment fact: a
+            // reader that answers `undefined` per location means that location failed, which
+            // blocks, and a shell call would then decide entries that never read its evidence.
+            observesPreState: session !== undefined,
+            // A diff-translated change carries the hunk's added lines as `post`, never the whole
+            // file, so a `file` binding on a staged path reads the tree — the state the change
+            // set left. A session call's `post` is the whole text it is about to write.
+            postIsWholeFile: surface === 'session',
             witness,
+            // The session itself, injected rather than its path: a declaration reading a
+            // `transcript` binding sees it flattened, and its absence is the absence of a session.
+            transcript,
         }),
     ];
     return registrations;
 }
+/**
+ * The name `explain` renders the change-set surface from — the same assembly, called with
+ * `surface: 'changeSet'` and neither IR key.
+ */
+export const assembleChangeSetRegistrations = assembleCheckRegistrations;
 /** 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`);
@@ -105,9 +131,16 @@ function failClosed(telemetryPath, error) {
 function settleConfig(spec) {
     let telemetryPath;
     try {
-        telemetryPath = spec.telemetryPath ?? resolve(spec.repoRoot, DEFAULT_TELEMETRY_LOG_PATH);
+        // The environment variable sits between the caller's path and the config's, matching
+        // what the baseline comparison in this same process already resolves — the two write
+        // to one log, so they must agree on which one. It is how a test run collects its own
+        // rows without editing the config it is measuring.
+        const envPath = process.env.POLYDEUKES_TELEMETRY_PATH;
+        telemetryPath =
+            spec.telemetryPath ?? envPath ?? resolve(spec.repoRoot, DEFAULT_TELEMETRY_LOG_PATH);
         const { config } = loadConfig({ rootDir: spec.repoRoot });
-        telemetryPath = spec.telemetryPath ?? resolve(spec.repoRoot, config.telemetry.logPath);
+        telemetryPath =
+            spec.telemetryPath ?? envPath ?? resolve(spec.repoRoot, config.telemetry.logPath);
         return { settled: true, telemetryPath, config };
     }
     catch (error) {
@@ -115,93 +148,111 @@ function settleConfig(spec) {
     }
 }
 /**
- * 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,
-            range: `${domain.base}${separator}${domain.head}`,
-        });
-    }
-    return collectStagedChanges({ repoRoot });
-}
-/**
- * The observation's change set: the paths of the collected changes that carry file-change
- * evidence, in collection order.
+ * The observation's change set: the paths of the input's toolCalls that carry file-change
+ * evidence, in input order.
  *
  * The same definition the judge derives its own set from, so both surfaces name the same
- * changes. A deletion carries evidence and stays; a binary blob, which the collector gives
- * a call with no evidence, produces no world of its own — listing it would hand the
- * change-set relations a path no world can ever answer for.
+ * changes. A deletion carries evidence and stays; a binary blob, which arrives as a call
+ * with no evidence, produces no world of its own — listing it would hand the change-set
+ * relations a path no world can ever answer for.
  */
-function changedPaths(changes) {
+function changedPaths(input) {
     const paths = [];
-    for (const call of covenantInputFromStagedChanges({ changes }).toolCalls) {
+    for (const call of input.toolCalls) {
         if (call.fileChange !== undefined)
             paths.push(call.fileChange.path);
     }
     return paths;
 }
 /**
- * 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.
+ * Assemble the registrations and dispatch every toolCall. Any throw here (a
+ * registration-build failure) is unjudgeable: block and leave one record.
  */
-async function judgeChanges(spec, domain, telemetryPath, config, changes) {
+async function judgeInput(spec, telemetryPath, config, input) {
     try {
-        // Inside the try so an invalid adapter namespace fails closed.
-        const { enforce } = resolveGitAdapterSettings({ namespace: 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);
+        // The umbrella's own judge module, so this runner runs the judges the session
+        // hook does; a test injects a module with one member replaced.
+        const covenant = spec.covenant ?? covenantModule;
         let blocked = false;
         let advisedCount = 0;
-        // Assembled ONCE for the run, not per change: a judge takes its call set as an argument,
+        const { tools, session } = input;
+        // One witness predicate shared by every registration: a witness is a session-wide
+        // permission the human granted, not a per-covenant one. It exists only where a session
+        // does — the valve reads human utterances, and an input with no session has none to
+        // read — so a session-free input assembles exactly the registrations it did before.
+        const witness = config.witness === undefined || session === undefined
+            ? undefined
+            : ttlWitness({
+                token: config.witness.token,
+                // Minutes are the human-facing unit in config; the predicate takes milliseconds.
+                ttlMs: config.witness.ttlMinutes * 60_000,
+            });
+        const transcript = session === undefined ? undefined : transcriptFromSession(session);
+        // Assembled ONCE for the run, not per call: 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({
+        const registrations = assembleCheckRegistrations({
             config,
             rootDir: spec.repoRoot,
             covenant,
+            surface: spec.surface,
+            tools,
+            session,
+            transcript,
             witness,
         });
-        // One plan and one supply for the run: the per-change loop shares them, so the tree is
-        // read once per named file rather than once per change. `changes` carries the whole
-        // observation because this surface dispatches one change at a time to keep telemetry at
+        // One plan and one supply for the run: the per-call loop shares them, so the tree is
+        // read once per named file rather than once per change. The change set carries the whole
+        // observation because this surface dispatches one call at a time to keep telemetry at
         // one row per file — a set no judge could derive from the input it is handed.
         const { files } = covenant.supplySources({
             plan: covenant.planSources({ registrations }),
-            read: observationSourceReader({ repoRoot: spec.repoRoot, observation: domain }),
+            read: worktreeReader({ repoRoot: spec.repoRoot }),
         });
-        const world = { files, changes: changedPaths(changes) };
-        for (const change of changes) {
-            const input = covenantInputFromStagedChanges({ changes: [change] });
+        // The session's channels ride into the world here rather than through a reader: the
+        // host already observed them, and this root opens no file the input did not name. An
+        // input with no session carries no channels key at all — an absent channel is a
+        // different fact from a channel that observed nothing.
+        const channels = session?.channels;
+        const world = {
+            files,
+            changes: changedPaths(input),
+            ...(channels === undefined ? {} : { channels }),
+        };
+        for (const call of input.toolCalls) {
             const { exitCode, results } = await covenant.dispatchCovenants({
-                stdinPayload: JSON.stringify(input),
+                stdinPayload: JSON.stringify({
+                    toolCalls: [call],
+                    subagentSpawns: input.subagentSpawns,
+                    userMessages: input.userMessages,
+                    // Neither the roster nor the session travels with the call: the roster is spent at
+                    // assembly (no judge body reads it), and the session is injected as the transcript,
+                    // because a dispatch's input is one judged unit rather than the session it happened in.
+                    ...(input.actor === undefined ? {} : { actor: input.actor }),
+                }),
                 registrations,
                 telemetryPath,
                 dispatcherLabel: 'covenant-check',
-                enforce,
+                enforce: spec.enforce ?? 'advise',
+                transcript,
                 world,
             });
             if (exitCode === 2)
                 blocked = true;
             advisedCount += results.filter((result) => result.event === 'advised').length;
+            // One call, one record: a call no registration routed leaves no row of its own, so
+            // the runner writes the pass under its label — the session surface does the same.
+            if (exitCode === 0 && results.length === 0) {
+                const subject = call.args?.file_path;
+                appendRecordFailOpen(telemetryPath, {
+                    event: 'passed',
+                    label: 'covenant-check',
+                    subject: typeof subject === 'string' ? subject : '-',
+                });
+            }
         }
-        // Names no level: surface-level and entry-level advice mix in one run, so the commit's
-        // fate is read from the run.
+        // Names no level: the commit's fate is read from the run.
         if (advisedCount > 0) {
             const outcome = blocked ? 'commit blocked by another verdict' : 'commit allowed';
             process.stderr.write(`covenant advisory: ${advisedCount} verdict(s) recorded as advised, ${outcome}\n`);
@@ -213,24 +264,112 @@ async function judgeChanges(spec, domain, telemetryPath, config, changes) {
     }
 }
 /**
- * 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.
+ * Reject an input whose roster or session evidence this runner cannot judge.
+ *
+ * A shape it cannot read is a block, never a default: folding a missing collection into
+ * `[]` or a bare string into a one-element list would judge an input nobody wrote. A key
+ * whose value is `undefined` reads as absent — a JSON round-trip drops it, so only an
+ * in-process caller can even write that shape.
+ */
+function assertJudgeableShape(input) {
+    const { tools, session } = input;
+    if (tools !== undefined) {
+        if (!isPlainObject(tools))
+            throw new Error('input carries a tools key that is not an object');
+        for (const key of ['mutating', 'shell', 'commandArgs']) {
+            const names = tools[key];
+            if (!Array.isArray(names))
+                throw new Error(`input carries no tools.${key} array`);
+            // A roster names tools; a non-string entry is a name no call could ever carry, and
+            // routing on it would silently leave that slot of the roster unjudged.
+            if (!names.every((name) => typeof name === 'string')) {
+                throw new Error(`input carries a non-string name in tools.${key}`);
+            }
+        }
+        // A shell tool with no argument key is a roster the shell judge cannot read: every
+        // routed call would land unjudgeable, which no posture softens. Refuse the run instead.
+        if (tools.shell.length > 0 && tools.commandArgs.length === 0) {
+            throw new Error('input carries tools.shell without a tools.commandArgs key to read');
+        }
+    }
+    if (session === undefined)
+        return;
+    if (!isPlainObject(session)) {
+        throw new Error('input carries a session key that is not an object');
+    }
+    for (const key of ['userMessages', 'toolCalls']) {
+        if (!Array.isArray(session[key]))
+            throw new Error(`input carries no session.${key} array`);
+    }
+    if (session.evidencePath !== undefined && typeof session.evidencePath !== 'string') {
+        throw new Error('input carries a session.evidencePath that is not a string');
+    }
+    if (session.channels !== undefined && !isPlainObject(session.channels)) {
+        throw new Error('input carries a session.channels that is not an object');
+    }
+    const sidecar = session.channels?.sidecar;
+    if (sidecar !== undefined && typeof sidecar !== 'string') {
+        throw new Error('input carries a session.channels.sidecar that is not text');
+    }
+}
+/**
+ * Judge one observation of `repoRoot` exactly as the session surface would, from the IR the
+ * caller hands in. Async because the dispatcher spawns covenant bodies. An input with no
+ * toolCalls is an explicit pass: nothing to judge, no records.
+ *
+ * An input carrying a session is one call of a live agent session, so the post-hoc state
+ * comparison wraps the judgment: it runs first, reading the window the previous call left,
+ * and the re-establishment runs last, folding this call's own judged writes in. Both sides
+ * sit OUTSIDE the judgment with their own catch — a mechanism whose purpose is to record
+ * rather than stop may never reach an exit code.
  */
 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;
+    let input;
     try {
-        changes = collectDomain(spec.repoRoot, domain);
+        input = typeof spec.input === 'function' ? spec.input() : spec.input;
+        // The world axis is this root's to fill. An input that supplies its own would let a
+        // caller choose the files the judge reads.
+        if ('world' in input) {
+            throw new Error('input carries a world key: the world axis is the runner’s');
+        }
+        if (!Array.isArray(input.toolCalls))
+            throw new Error('input carries no toolCalls array');
+        assertJudgeableShape(input);
     }
     catch (error) {
         return failClosed(telemetryPath, error);
     }
-    if (changes.length === 0)
-        return { exitCode: 0 };
-    return judgeChanges(spec, domain, telemetryPath, config, changes);
+    // The comparison reads and writes the log the judgment writes — the settled path, never
+    // a second resolution — and observes the protected entries the settled config names.
+    // A session call with nothing judgeable still compares and re-establishes: the window it
+    // opens is what the next call reads, and a skipped call would leave it stale.
+    let comparison;
+    if (input.session !== undefined) {
+        try {
+            comparison = {
+                repoRoot: spec.repoRoot,
+                telemetryPath,
+                entries: normalizeProtectedPaths({ protectedPaths: config.protectedPaths }),
+            };
+            compareBaseline(comparison);
+        }
+        catch {
+            // fail-open: a comparison that could not run leaves the judgment exactly as it was.
+        }
+    }
+    const result = input.toolCalls.length === 0
+        ? { exitCode: 0 }
+        : await judgeInput(spec, telemetryPath, config, input);
+    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/diff-ir.d.ts

@@ -0,0 +1,28 @@
+/**
+ * unified diff → `CovenantInput`. One pure translation, no judgment and no disk.
+ *
+ * The accepted grammar is finite: `diff --git` blocks and header-less `---`/`+++` blocks,
+ * covering creation, deletion, modification, mode-only changes, renames, and binary blobs.
+ * Anything else throws, so an unrecognised shape fails the run closed instead of translating
+ * to a partial observation.
+ *
+ * A modification's `pre`/`post` are the hunk's `-` and `+` lines, never the whole file: a
+ * unified diff carries the changed lines and the context around them, and reconstructing the
+ * file from them is not a translation. A creation and a deletion carry the whole text because
+ * every line of the file is in the hunk.
+ */
+import type { CovenantInput } from '@polydeukes/core';
+/** The tool name a staged write is dispatched under — telemetry and configs read it. */
+export declare const STAGED_WRITE = "staged-write";
+/** The tool name a staged deletion is dispatched under. */
+export declare const STAGED_DELETE = "staged-delete";
+/** {@link covenantInputFromUnifiedDiff} input — the diff text a producer wrote. */
+export type CovenantInputFromUnifiedDiffSpec = {
+    /** The whole unified diff; zero bytes is the empty observation. */
+    text: string;
+};
+/**
+ * Translate a unified diff into the covenant input IR: one toolCall per file block in input
+ * order (a rename is two, the deletion first), and no `actor` key — a diff proves no author.
+ */
+export declare function covenantInputFromUnifiedDiff(spec: CovenantInputFromUnifiedDiffSpec): CovenantInput;