npm - polydeukes - Versions diffs - 0.5.0 → 0.6.0 - Mend

polydeukes 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (38) hide show

package/README.ko.md +9 -3
package/README.md +12 -4
package/dist/baseline.d.ts +82 -0
package/dist/baseline.js +166 -0
package/dist/bin.d.ts +1 -1
package/dist/bin.js +19 -2
package/dist/claude-code-hook.d.ts +7 -5
package/dist/claude-code-hook.js +69 -17
package/dist/claude-code.d.ts +6 -0
package/dist/claude-code.js +6 -0
package/dist/covenant-check.d.ts +10 -17
package/dist/covenant-check.js +44 -12
package/dist/covenant-module.d.ts +2 -2
package/dist/covenant-module.js +9 -1
package/dist/docs/configuration.md +1 -1
package/dist/docs/installation.md +41 -12
package/dist/docs/reference/adapter-claude-code.md +6 -4
package/dist/docs/reference/adapter-git.md +8 -6
package/dist/docs/reference/configuration.md +222 -104
package/dist/docs/reference/core.md +11 -5
package/dist/docs/reference/covenant.md +31 -23
package/dist/docs/reference/polydeukes.md +62 -34
package/dist/docs/troubleshooting.md +36 -9
package/dist/explain.d.ts +3 -5
package/dist/explain.js +48 -47
package/dist/index.d.ts +2 -3
package/dist/index.js +1 -2
package/dist/init-claude-code.d.ts +5 -3
package/dist/init-claude-code.js +76 -30
package/dist/init-grok.d.ts +51 -0
package/dist/init-grok.js +242 -0
package/dist/load-config.d.ts +5 -1
package/dist/load-config.js +2 -1
package/dist/pre-state-reader.d.ts +22 -0
package/dist/pre-state-reader.js +32 -0
package/dist/scaffold-project.js +48 -8
package/dist/schema/polydeukes.schema.json +38 -91
package/package.json +7 -7

package/README.ko.md CHANGED Viewed

@@ -11,7 +11,7 @@
 ## 여기 담긴 것
-- **`loadConfig(rootDir)`.** config 디스커버리입니다. 주어진 루트 바로 아래에서 정확히 하나의
+- **`loadConfig({ rootDir })`.** config 디스커버리입니다. 주어진 루트 바로 아래에서 정확히 하나의
   데이터 config(`polydeukes.config` 파일의 yaml·yml·json 형태)를 찾아, 안전 스키마로 해석하고
   (설정 데이터는 결코 실행되지 않습니다) 코어의 `defineConfig()`에 검증을 맡깁니다. 모든 실패
   분기는 예외를 던집니다(throw). 조용한 기본값은 금지이고, 발견된 파일은 자기 자신을 보호
@@ -20,8 +20,8 @@
   pre-commit 판정 러너로, 스테이징 영역의 변경을 `@polydeukes/adapter-git`이 수집해
   약속(covenant) 입력 IR로 번역하고, 세션 훅이 부르는 바로 그 in-process 판정기로 보냅니다.
   판정기는 하나, 표면은 여럿입니다. `--worktree`와 `--range <base>..<head>`는 같은 판정을
-  작업 트리나 ref 범위에 진단 호출로 돌리며, 증인 프롬프트는 뜨지 않습니다. 맥락족 규율(discipline, `requirePrecedent`)도 다른 규율과
-  똑같이 조립되지만, 읽을 세션이 없으므로 스킵 등록이 됩니다. 스테이징 변경과 매치하면 자기
+  작업 트리나 ref 범위에 진단 호출로 돌리며, 증인 프롬프트는 뜨지 않습니다. 세션을 읽는 선언(`precedent`와 다른 이력 기전)도 다른 규율과
+  똑같이 조립되지만, 읽을 세션이 없으므로 자기 `supply: pass`가 처분합니다. 스테이징 변경과 매치하면 자기
   id와 그 변경을 담은 `skipped` 이벤트를 남기고 커밋은 진행됩니다. 여기서 판정하면 걸리는
   커밋마다 정당하게 통과할 길 없이 막히고, 아예 걸러내면 게이트가 물러섰다는 사실이 가려집니다.
   세션 표면이 읽을 transcript를 갖지 못했을 때와 같은 처분입니다. 빈 스테이징은 명시적
@@ -36,6 +36,12 @@
   방금 등록한 훅 자신이 보호 대상이기 때문입니다. config 철자 둘이 공존하는 트리, 파싱되지 않는
   settings 파일, 해소되지 않는 패키지는 전부 선행 조건 실패입니다. 반쯤 배선된 트리를 남기는
   대신 파일을 하나도 만들지 않습니다.
+- **`pdks init grok`.** Grok 세션 표면 설치기입니다. 선행 검사와 공유 스캐폴드는 같고, 이 경로가
+  지는 것은 `.grok/hooks/`입니다(timeout 60인 JSON 등록, Claude 위임자가 없을 때만 위임자 파일).
+  Claude 훅 파일이 이미 있으면 JSON command가 그 파일을 가리켜 판정기를 둘 스폰하지 않습니다.
+  나중에 어느 설치기를 다시 돌려도, 설치기가 심은 grok-mjs command는 같은 방식으로 재조준되고,
+  JSON matcher는 그 command의 `.claude/settings.json` 항목을 따릅니다. Grok는 command와
+  matcher가 모두 같을 때만 등록 둘을 하나로 접기 때문입니다. 이미 열린 Grok 세션은 시작 때 훅 스냅샷을 유지합니다. 증인 밸브는 Grok에서 열리지 않습니다.
 - **`pdks docs [topic]`.** 오프라인 문서 열람기입니다. 영어 가이드와 레퍼런스 층이 빌드 시점에
   `dist/docs`로 복사되므로, 소비자의 AI 파트너는 검색 엔진이 색인한 아무 판본이 아니라 판정을
   수행하는 코드와 함께 실린 문서를 읽습니다. 인자 없이 부르면 토픽 다섯을 열거하는데, 에이전트가

package/README.md CHANGED Viewed

@@ -11,7 +11,7 @@ one-way, through the core alone.
 ## What lives here
-- **`loadConfig(rootDir)`** — config discovery. Exactly one root data config (a
+- **`loadConfig({ rootDir })`** — config discovery. Exactly one root data config (a
   `polydeukes.config` file in yaml, yml, or json form) directly under the given root, parsed with
   a safe schema (config data is never executable) and validated by the core's `defineConfig()`.
   Every failure branch throws — silent defaults are forbidden — and the discovered file attaches
@@ -21,8 +21,8 @@ one-way, through the core alone.
   translated into the covenant input IR, and dispatched through the very in-process judges the
   session hook calls — one judge, every surface. `--worktree` and `--range <base>..<head>` run the same
   judgment over the working tree or a ref range as a diagnostic call, with no witness prompt.
-  Context-family disciplines (`requirePrecedent`) assemble
-  here like any other, but with no session to read they become skip registrations: when one
+  Declarations that read the session (`precedent` and the other history mechanisms) assemble
+  here like any other, but with no session to read their `supply: pass` takes over: when one
   matches a staged change it records a `skipped` event carrying its id and that change, and the
   commit proceeds. Judging them would block every matching commit with no legitimate pass path;
   filtering them out would hide that a gate stood down. It is the same disposition the session
@@ -34,7 +34,7 @@ one-way, through the core alone.
   it carries a `why`, and for each skip the compiler's reason — the one that otherwise reaches
   stderr only when the cause is a config fault. No judge thunk is called and no telemetry row is
   written. A config that cannot be loaded fails at exit `2` with stdout at zero bytes.
-- **`pdks init claude-code`** — the session-surface installer. It proves `polydeukes` resolves
+- **`pdks init claude-code`** — the Claude Code session-surface installer. It proves `polydeukes` resolves
   from the target project before writing anything, then creates what every distribution path
   shares (the data config and its `.polydeukes/` ignore line) and what this path owns (a delegator
   hook, its `.claude/settings.json` registration merged into whatever that file already carries,
@@ -45,6 +45,14 @@ one-way, through the core alone.
   hook it just registered is itself protected. Two coexisting config spellings, an unparseable
   settings file, and a package that cannot be resolved are all precondition failures: each leaves
   zero files rather than a half-wired tree.
+- **`pdks init grok`** — the Grok session-surface installer. Same preflight and shared scaffold;
+  this path owns `.grok/hooks/` (JSON registration with timeout 60, and a delegator file only when
+  no Claude delegator is on disk). If the Claude hook file already exists, the JSON command points
+  at it so two judges are not spawned. A later run of either installer retargets an
+  installer-generated grok-mjs command the same way, and the JSON matcher follows the
+  `.claude/settings.json` entry for that command — Grok collapses two registrations only when
+  command and matcher both match. An already-open Grok session keeps the hook snapshot from
+  start. The witness valve does not open on Grok.
 - **`pdks docs [topic]`** — the offline documentation reader. The English guides and the reference
   layer are copied into `dist/docs` at build time, so a consumer's AI partner reads the
   documentation that shipped with the code doing the judging instead of whichever release a search

package/dist/baseline.d.ts ADDED Viewed

@@ -0,0 +1,82 @@
+/**
+ * Post-hoc state comparison — the baseline comparator.
+ *
+ * The session surface judges declared calls, so a write nobody declared leaves no row at
+ * all. This module answers the same question from the other end: summarize the protected
+ * entries' on-disk state, and after the fact name the entries whose state moved with no
+ * judgment row explaining it. It records rather than blocks — every failure shape here
+ * resolves to a value, never a throw.
+ *
+ * Split the way the telemetry module is: {@link findUnattributed} is pure and
+ * {@link snapshotBaseline} / {@link writeBaseline} / {@link readBaseline} are the I/O
+ * points.
+ */
+import type { TelemetryRecord } from '@polydeukes/core';
+/** One hash per protected entry, keyed by the entry exactly as configured. */
+export type BaselineSnapshot = Record<string, string>;
+/**
+ * The baseline file's contents: the entry hashes plus the instant the attribution window
+ * opens at. Named for the file rather than the concept — `Baseline` already belongs to the
+ * delta family, where it means a file's prior CONTENT, not a protection snapshot.
+ *
+ * The two fields travel together because they are read together — pairing one comparison's
+ * hashes with another's cut would silently mis-attribute, undetectably.
+ */
+export type StoredBaseline = {
+    entries: BaselineSnapshot;
+    cutAt?: string;
+};
+/**
+ * Summarize each entry's on-disk state as one sha256.
+ *
+ * `entries` are repo-relative paths of either shape — a file or a directory. Every entry
+ * keeps a key whatever its state, so the diff always sees it; a missing entry simply hashes
+ * to the empty set.
+ */
+export declare function snapshotBaseline(spec: {
+    rootDir: string;
+    entries: string[];
+}): BaselineSnapshot;
+/**
+ * The entries whose hash changed and that no window row explains (pure).
+ *
+ * Attribution is asked per entry, never per window: "the window holds an attributing row"
+ * and "THIS entry's change has one" are different claims, and answering the first is the
+ * fail-open shape this repository already shipped once.
+ *
+ * The window is cut by `cutAt` — rows at or after that instant, which are the ones written
+ * since the previous comparison. Cutting by time rather than by a record count keeps the
+ * bound meaningful when the log is trimmed or rotated; a positional index would point past
+ * the end and empty the window for every later call. An absent cut admits every row: over-
+ * attributing costs one missed alarm in a session that is already anomalous, while under-
+ * attributing floods an ordinary one and teaches the reader to ignore the alarm entirely.
+ *
+ * Only entries the previous baseline already watched are compared. An entry the config just
+ * added has no prior hash, and reporting it would make editing one's own policy look
+ * identical to a tamper; an entry the config dropped is simply no longer watched.
+ */
+export declare function findUnattributed(spec: {
+    previous: BaselineSnapshot;
+    current: BaselineSnapshot;
+    records: TelemetryRecord[];
+    cutAt?: string;
+}): string[];
+/**
+ * Write the baseline file.
+ *
+ * `cutAt` is the instant this comparison ran, so the next one attributes from rows written
+ * at or after it. Written at call END, so the rows explaining what this call itself changed
+ * fall before the cut — the snapshot beside them already absorbed those changes.
+ */
+export declare function writeBaseline(path: string, snapshot: BaselineSnapshot, cutAt?: string): void;
+/**
+ * Read the baseline — entries and window cut in ONE parse — or `null`.
+ *
+ * One parse rather than two: reading the hashes and the cut separately lets a concurrent
+ * write land between them, pairing one comparison's state with another's window bound. That
+ * mismatch changes which entries are attributed and leaves no trace anywhere.
+ *
+ * Absence and corruption are the same signal — re-establish and record — so neither throws.
+ * Observation is fail-open: the worst outcome is a missing datum, never a blocked call.
+ */
+export declare function readBaseline(path: string): StoredBaseline | null;

package/dist/baseline.js ADDED Viewed

@@ -0,0 +1,166 @@
+/**
+ * Post-hoc state comparison — the baseline comparator.
+ *
+ * The session surface judges declared calls, so a write nobody declared leaves no row at
+ * all. This module answers the same question from the other end: summarize the protected
+ * entries' on-disk state, and after the fact name the entries whose state moved with no
+ * judgment row explaining it. It records rather than blocks — every failure shape here
+ * resolves to a value, never a throw.
+ *
+ * Split the way the telemetry module is: {@link findUnattributed} is pure and
+ * {@link snapshotBaseline} / {@link writeBaseline} / {@link readBaseline} are the I/O
+ * points.
+ */
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * The two verdict words that explain a change — the ones that mean a mutation of a
+ * protected entry was judged and let through anyway.
+ *
+ * `witnessed` is a break a human opened in person; `advised` is one an advise-level surface
+ * recorded without stopping. Both name a write the session knew about, so the change that
+ * follows is accounted for.
+ *
+ * The other four do not attribute, each for its own reason. `passed` means the call was
+ * judged and did NOT break the covenant — on a protected entry that is a mention, not a
+ * mutation, so it explains no later change; admitting it is what let a read-only call
+ * absolve a tamper. `blocked` stops the call, so what follows is not its doing, and
+ * admitting it would make provoking a block a licence for every later write to that entry
+ * (the residue a blocked call really left is present when that same call compares, reported
+ * there once, and folded into its own re-establishment). `skipped` is a recorded absence of
+ * judgment, which explains nothing. `unattributed` must never silence its own successor.
+ */
+const ATTRIBUTING_EVENTS = ['witnessed', 'advised'];
+/**
+ * Fold one file's path and content into `hash`.
+ *
+ * The path participates, so a rename with byte-identical content still moves the entry's
+ * hash. An unreadable file contributes a fixed absence marker rather than aborting the
+ * walk — absence is a state, and a file that vanished mid-walk is exactly the state the
+ * comparison exists to see. The marker leads with an escaped NUL so no readable file's
+ * contents can collide with it; written as an escape rather than a literal byte, which
+ * would make this source a binary file to git and hide it from every diff.
+ */
+function foldFile(hash, absolutePath, key) {
+    hash.update(key);
+    try {
+        hash.update(readFileSync(absolutePath));
+    }
+    catch {
+        hash.update('\0absent');
+    }
+}
+/**
+ * Fold everything reachable under `absolutePath` into `hash`, in sorted order.
+ *
+ * Sorted so an unchanged tree hashes identically twice — directory iteration order is not
+ * a guarantee, and a nondeterministic term would read as a change on every call. A path
+ * that is a file, or that does not exist at all, is not a traversal failure: six of the
+ * live config's thirteen entries name a file, and a vanished entry hashes to the empty set.
+ */
+function foldEntry(hash, rootDir, relPath) {
+    let children;
+    try {
+        children = readdirSync(join(rootDir, relPath), { withFileTypes: true });
+    }
+    catch {
+        foldFile(hash, join(rootDir, relPath), relPath);
+        return;
+    }
+    for (const child of [...children].sort((a, b) => a.name.localeCompare(b.name))) {
+        foldEntry(hash, rootDir, `${relPath}/${child.name}`);
+    }
+}
+/**
+ * Summarize each entry's on-disk state as one sha256.
+ *
+ * `entries` are repo-relative paths of either shape — a file or a directory. Every entry
+ * keeps a key whatever its state, so the diff always sees it; a missing entry simply hashes
+ * to the empty set.
+ */
+export function snapshotBaseline(spec) {
+    const snapshot = {};
+    for (const entry of spec.entries) {
+        const hash = createHash('sha256');
+        foldEntry(hash, spec.rootDir, entry);
+        snapshot[entry] = hash.digest('hex');
+    }
+    return snapshot;
+}
+/**
+ * The entries whose hash changed and that no window row explains (pure).
+ *
+ * Attribution is asked per entry, never per window: "the window holds an attributing row"
+ * and "THIS entry's change has one" are different claims, and answering the first is the
+ * fail-open shape this repository already shipped once.
+ *
+ * The window is cut by `cutAt` — rows at or after that instant, which are the ones written
+ * since the previous comparison. Cutting by time rather than by a record count keeps the
+ * bound meaningful when the log is trimmed or rotated; a positional index would point past
+ * the end and empty the window for every later call. An absent cut admits every row: over-
+ * attributing costs one missed alarm in a session that is already anomalous, while under-
+ * attributing floods an ordinary one and teaches the reader to ignore the alarm entirely.
+ *
+ * Only entries the previous baseline already watched are compared. An entry the config just
+ * added has no prior hash, and reporting it would make editing one's own policy look
+ * identical to a tamper; an entry the config dropped is simply no longer watched.
+ */
+export function findUnattributed(spec) {
+    const cutAt = spec.cutAt;
+    const attributed = new Set(spec.records
+        .filter((record) => cutAt === undefined || record.timestamp >= cutAt)
+        .filter((record) => ATTRIBUTING_EVENTS.includes(record.event))
+        .map((record) => record.subject));
+    return Object.keys(spec.current).filter((entry) => entry in spec.previous &&
+        spec.current[entry] !== spec.previous[entry] &&
+        !attributed.has(entry));
+}
+/**
+ * Write the baseline file.
+ *
+ * `cutAt` is the instant this comparison ran, so the next one attributes from rows written
+ * at or after it. Written at call END, so the rows explaining what this call itself changed
+ * fall before the cut — the snapshot beside them already absorbed those changes.
+ */
+export function writeBaseline(path, snapshot, cutAt) {
+    writeFileSync(path, JSON.stringify({ entries: snapshot, cutAt }));
+}
+/**
+ * Read the baseline — entries and window cut in ONE parse — or `null`.
+ *
+ * One parse rather than two: reading the hashes and the cut separately lets a concurrent
+ * write land between them, pairing one comparison's state with another's window bound. That
+ * mismatch changes which entries are attributed and leaves no trace anywhere.
+ *
+ * Absence and corruption are the same signal — re-establish and record — so neither throws.
+ * Observation is fail-open: the worst outcome is a missing datum, never a blocked call.
+ */
+export function readBaseline(path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    // Validate what the comparison will use: valid JSON of the wrong shape parses fine and
+    // then crashes the diff, which the fail-open wiring swallows — detection would go dark
+    // with no re-establishment and no row.
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    const { entries, cutAt } = parsed;
+    if (typeof entries !== 'object' || entries === null || Array.isArray(entries)) {
+        return null;
+    }
+    if (Object.values(entries).some((value) => typeof value !== 'string')) {
+        return null;
+    }
+    // An unparseable cut degrades to absent, which admits the whole window — the same safe
+    // direction {@link findUnattributed} takes, rather than a bound nobody can trust.
+    return {
+        entries: entries,
+        cutAt: typeof cutAt === 'string' ? cutAt : undefined,
+    };
+}

package/dist/bin.d.ts CHANGED Viewed

@@ -2,7 +2,7 @@
 /**
  * `pdks` / `polydeukes` — the umbrella bin.
  *
- * A thin argv shim: four subcommands, each matched by direct comparison against a finite
+ * A thin argv shim: each subcommand is matched by direct comparison against a finite
  * table. Anything else prints usage and exits 2 — an unknown argument must never pass
  * silently (fail-closed, the same posture as an unjudgeable payload).
  *

package/dist/bin.js CHANGED Viewed

@@ -2,7 +2,7 @@
 /**
  * `pdks` / `polydeukes` — the umbrella bin.
  *
- * A thin argv shim: four subcommands, each matched by direct comparison against a finite
+ * A thin argv shim: each subcommand is matched by direct comparison against a finite
  * table. Anything else prints usage and exits 2 — an unknown argument must never pass
  * silently (fail-closed, the same posture as an unjudgeable payload).
  *
@@ -88,6 +88,23 @@ if (args.length === 2 && args[0] === 'init' && args[1] === 'claude-code') {
         process.exit(2);
     }
 }
+if (args.length === 2 && args[0] === 'init' && args[1] === 'grok') {
+    try {
+        const { initGrok } = await import('./init-grok.js');
+        const { created, skipped } = initGrok({ projectRoot: process.cwd() });
+        for (const path of created) {
+            process.stdout.write(`created ${path}\n`);
+        }
+        for (const path of skipped) {
+            process.stdout.write(`skipped ${path} (already present)\n`);
+        }
+        process.exit(0);
+    }
+    catch (error) {
+        process.stderr.write(`pdks init grok failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(2);
+    }
+}
 if (args[0] === 'docs' && args.length <= 2) {
     try {
         // Imported inside the try for the same reason `init` is: the query core and the
@@ -149,7 +166,7 @@ function parseCheckDomain(flags) {
 }
 const domain = args[0] === 'covenant' && args[1] === 'check' ? parseCheckDomain(args.slice(2)) : null;
 if (domain === null) {
-    process.stderr.write('usage: pdks covenant check [--worktree | --range <base>..<head>] | pdks explain | pdks init claude-code | pdks docs [topic]\n');
+    process.stderr.write('usage: pdks covenant check [--worktree | --range <base>..<head>] | pdks explain | pdks init claude-code | pdks init grok | pdks docs [topic]\n');
     process.exit(2);
 }
 try {

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

@@ -25,8 +25,12 @@
  */
 import { type CanonicalTranscript } from '@polydeukes/core';
 import { type CovenantRegistration } from '@polydeukes/covenant';
-import { type CovenantModule } from './covenant-module.js';
-import { loadConfig } from './load-config.js';
+import { type CovenantModule } from './covenant-module.ts';
+import { loadConfig } from './load-config.ts';
+/** {@link runClaudeCodeHook} result — the exit code the hook process leaves with. */
+export type ClaudeCodeHookOutcome = {
+    exitCode: 0 | 2;
+};
 /** `runClaudeCodeHook` input — the `CovenantCheckSpec` shape, session side. */
 export type ClaudeCodeHookSpec = {
     /** Repository root — config discovery and discipline glob scoping both anchor here. */
@@ -72,6 +76,4 @@ export declare function assembleSessionRegistrations(spec: SessionAssemblySpec):
  * 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;
-}>;
+export declare function runClaudeCodeHook(spec: ClaudeCodeHookSpec): Promise<ClaudeCodeHookOutcome>;

package/dist/claude-code-hook.js CHANGED Viewed

@@ -26,11 +26,13 @@
 import { mkdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { 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 { findUnattributed, readBaseline, snapshotBaseline, ttlWitness, writeBaseline, } from '@polydeukes/covenant';
+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';
+import { sessionPreStateReader } from './pre-state-reader.js';
 /** The label every post-hoc state comparison row carries. */
 const BASELINE_LABEL = 'baseline';
 /**
@@ -109,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;
@@ -129,9 +131,9 @@ function comparisonSpec(spec) {
  */
 export function assembleSessionRegistrations(spec) {
     const { config, rootDir, covenant, transcriptPath, transcript, witness } = spec;
-    // The live transcript is the evidence channel the context family reads AND the one the
-    // witness reads, so erasing or forging it disables every context discipline while opening
-    // or shutting the human valve on the same file. It must NOT join this list: it lives deep
+    // 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
@@ -156,7 +158,7 @@ export function assembleSessionRegistrations(spec) {
         }),
         // 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.
+        // the valve and every history declaration already forfeited on the same absence.
         ...(transcriptPath === undefined
             ? []
             : [
@@ -179,17 +181,56 @@ export function assembleSessionRegistrations(spec) {
             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,
-            // Context-family evidence is evaluated here, at assembly: a spawned body cannot hold
-            // a transcript, and passing a path would leak JSONL knowledge into covenant. The
-            // adapter brings the evaluator for its own `subagent`/`tool` vocabulary; core owns
-            // `command`, which the compiler judges directly.
+            // 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,
-            evaluatePrecedent,
         }),
     ];
     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
@@ -212,20 +253,20 @@ 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.
-        const transcriptPath = transcriptPathFromPayload(rawPayload);
-        const transcript = transcriptPath === undefined ? undefined : transcriptFromJsonlFile(transcriptPath);
+        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
@@ -260,6 +301,16 @@ async function judgeHookCall(spec) {
             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,
@@ -268,6 +319,7 @@ async function judgeHookCall(spec) {
                 registrations,
                 telemetryPath: logPath,
                 transcript,
+                world: { files, channels },
             }),
         });
     }

package/dist/claude-code.d.ts ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -10,26 +10,21 @@
  * 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.js';
-import { loadConfig } from './load-config.js';
+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.
  *
- * `range` names its two refs. `ancestry: 'merge-base'` selects the `A...B` reading, whose
- * base is the two refs' common ancestor rather than `A` itself; the adapter that owns the
- * range grammar resolves it.
+ * 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.
  */
-export type CheckDomain = {
-    kind: 'staged';
-} | {
-    kind: 'worktree';
-} | {
-    kind: 'range';
-    base: string;
-    head: string;
-    ancestry?: 'merge-base';
+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 = {
@@ -74,6 +69,4 @@ export declare function assembleCommitRegistrations(spec: CommitAssemblySpec): C
  * diff by default, the working tree or a ref range on request. Async because the dispatcher
  * spawns covenant bodies. An empty domain is an explicit pass: nothing to judge, no records.
  */
-export declare function runCovenantCheck(spec: CovenantCheckSpec): Promise<{
-    exitCode: 0 | 2;
-}>;
+export declare function runCovenantCheck(spec: CovenantCheckSpec): Promise<CovenantCheckOutcome>;