polydeukes 0.3.0 → 0.4.0

package/dist/claude-code-hook.d.ts

@@ -38,9 +38,18 @@ export type ClaudeCodeHookSpec = {
     covenantDist?: string;
 };
 /**
- * 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 entry point: the post-hoc state comparison wrapped around the judgment
+ * (COVENANT-14 §2-f).
+ *
+ * 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 declare function runClaudeCodeHook(spec: ClaudeCodeHookSpec): Promise<{
     exitCode: 0 | 2;

package/dist/claude-code-hook.js

@@ -26,13 +26,13 @@
  * 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 { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 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, normalizeProtectedPaths } from '@polydeukes/core';
-import { compileDisciplineRegistrations, dispatchCovenants, transcriptModRegistration, ttlWitness, } from '@polydeukes/covenant';
+import { appendRecordFailOpen, DEFAULT_TELEMETRY_LOG_PATH, normalizeProtectedPaths, readRecords, } from '@polydeukes/core';
+import { compileDisciplineRegistrations, dispatchCovenants, findUnattributed, readBaseline, snapshotBaseline, transcriptModRegistration, ttlWitness, writeBaseline, } from '@polydeukes/covenant';
 import { loadConfig } from './load-config.js';
 /**
  * Compose a judge body path and prove it exists (CONFIG-06b §4.2). A body module that was
@@ -48,12 +48,103 @@ function provenBodyPath(distDir, fileName) {
     }
     return modulePath;
 }
+/** The label every post-hoc state comparison row carries (COVENANT-14 §2-d). */
+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).
+ *
+ * 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 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 (§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.
+        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,
+        });
+    }
+}
+/**
+ * Re-establish the baseline at hook call END (COVENANT-14 §5).
+ *
+ * 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.
+ */
+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` (COVENANT-14 §6).
+ *
+ * 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 }),
+    };
+}
 /**
  * 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.
  */
-export async function runClaudeCodeHook(spec) {
+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.
@@ -67,7 +158,7 @@ export async function runClaudeCodeHook(spec) {
     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);
@@ -231,3 +322,39 @@ export async function runClaudeCodeHook(spec) {
         return { exitCode: 2 };
     }
 }
+/**
+ * The session-surface entry point: the post-hoc state comparison wrapped around the judgment
+ * (COVENANT-14 §2-f).
+ *
+ * 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

@@ -22,15 +22,21 @@
  * 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).
+ * 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).
  */
 /** `runCovenantCheck` input (ADAPTER-git §4.3 — the contract covenant-check tests pin). */
 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 (ADAPTER-git-b §4.1). Absent, both of those
+     * apply in that order.
+     */
     telemetryPath?: string;
     /** Overrides the resolved covenant dist directory (tests and assembly injection). */
     covenantDist?: string;

package/dist/covenant-check.js

@@ -22,15 +22,16 @@
  * 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).
+ * 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).
  */
 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 { appendRecordFailOpen, DEFAULT_TELEMETRY_LOG_PATH, normalizeProtectedPaths, } from '@polydeukes/core';
 import { compileDisciplineRegistrations, dispatchCovenants, } from '@polydeukes/covenant';
 import { loadConfig } from './load-config.js';
 /**
@@ -86,21 +87,25 @@ function provenBodyPath(distDir, fileName) {
     }
     return modulePath;
 }
-/** One blocked record for a run that failed closed before any dispatch could judge. */
+/**
+ * One blocked record for a run that failed closed before any dispatch could judge.
+ *
+ * The write goes through `appendRecordFailOpen` rather than the mkdir-free `appendRecord`:
+ * a repository that has never been judged has no `.polydeukes/` directory — the shape
+ * `pdks init` leaves every consumer in — and the raw append would fail open on ENOENT,
+ * turning the very first fail-closed run into an unrecorded block. The wrapper carries both
+ * the parent-directory guarantee and the fail-open contract, so a telemetry failure still
+ * never softens the blocking exit. An undefined path is tolerated here because a non-string
+ * `repoRoot` leaves no root to write a row under.
+ */
 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
@@ -109,16 +114,35 @@ function recordFailClosed(telemetryPath) {
  * principle forbids.
  */
 export async function runCovenantCheck(spec) {
+    // Telemetry precedence settled BEFORE the failure branch (session-hook precedent): a config
+    // that never loads still has somewhere to write its one blocked row, and the config value
+    // replaces the provisional default once the load succeeds. The provisional default spells
+    // itself with the loader's own constant, so both terms converge on one source.
+    //
+    // Computed INSIDE the try even though it must run first, because `resolve` throws on a
+    // non-string repoRoot and that throw must not escape as a rejection. It leaves
+    // `telemetryPath` undefined, which the catch tolerates: there is no root to write a row
+    // under anyway.
+    //
+    // Both terms compose with `resolve`, never `join`: a relative repoRoot would leave the
+    // provisional path relative and the post-load one absolute, so a run whose config failed
+    // to load would write its row to a different file than the same repository's judgment
+    // rows — and a relative path is re-read against the cwd at append time, which need not
+    // be the cwd this ran under. The bin always passes `process.cwd()`, so the divergence is
+    // reachable only through this exported function, whose `repoRoot` promises no
+    // absoluteness (PR #57 review).
+    let telemetryPath;
     let config;
     try {
+        telemetryPath = spec.telemetryPath ?? resolve(spec.repoRoot, DEFAULT_TELEMETRY_LOG_PATH);
         ({ config } = loadConfig(spec.repoRoot));
+        telemetryPath = spec.telemetryPath ?? resolve(spec.repoRoot, config.telemetry.logPath);
     }
     catch (error) {
         process.stderr.write(`covenant check failed closed: ${error instanceof Error ? error.message : String(error)}\n`);
-        recordFailClosed(spec.telemetryPath);
+        recordFailClosed(telemetryPath);
         return { exitCode: 2 };
     }
-    const telemetryPath = spec.telemetryPath ?? resolve(spec.repoRoot, config.telemetry.logPath);
     let changes;
     try {
         changes = collectStagedChanges(spec.repoRoot);