@isaacriehm/cairn-core 0.4.3 → 0.6.0

package/dist/ground/sot-cache.js

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync } from "node:fs";
+import { writeFileSafe } from "../fs.js";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { logger } from "../logger.js";
+import { sotCachePath } from "./paths.js";
+import { SotCache } from "./schemas.js";
+const log = logger("ground.sot-cache");
+/**
+ * Sot-cache holds pre-tokenized DEC body content for the Layer A Jaccard
+ * pre-filter. Rebuilt at SessionStart, incremental on PostToolUse Write
+ * events that touch a DEC body or sot-path file. Mtime-keyed so a stale
+ * entry is detected without re-tokenizing every body on every Write.
+ */
+export function emptySotCache() {
+    return { version: 1, generated: new Date().toISOString(), entries: {} };
+}
+export function readSotCache(repoRoot) {
+    const path = sotCachePath(repoRoot);
+    if (!existsSync(path))
+        return emptySotCache();
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = SotCache.safeParse(parseYaml(raw));
+        if (!parsed.success) {
+            log.warn({ path, error: parsed.error.message }, "sot-cache invalid; treating as empty");
+            return emptySotCache();
+        }
+        return parsed.data;
+    }
+    catch (err) {
+        log.warn({ path, err }, "sot-cache read failed; treating as empty");
+        return emptySotCache();
+    }
+}
+export function writeSotCache(repoRoot, cache) {
+    const path = sotCachePath(repoRoot);
+    const next = { ...cache, generated: new Date().toISOString() };
+    writeFileSafe(path, stringifyYaml(next));
+    log.debug({ path, entries: Object.keys(next.entries).length }, "wrote sot-cache");
+    return path;
+}
+export function setEntry(cache, decId, entry) {
+    return { ...cache, entries: { ...cache.entries, [decId]: entry } };
+}
+export function getEntry(cache, decId) {
+    return cache.entries[decId] ?? null;
+}
+export function deleteEntry(cache, decId) {
+    if (cache.entries[decId] === undefined)
+        return cache;
+    const entries = { ...cache.entries };
+    delete entries[decId];
+    return { ...cache, entries };
+}
+/**
+ * Iterate all entries. Layer A's pre-filter pass calls this on each
+ * Write to compute Jaccard against every cached DEC body.
+ */
+export function entries(cache) {
+    return Object.values(cache.entries);
+}
+//# sourceMappingURL=sot-cache.js.map

package/dist/ground/sot-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sot-cache.js","sourceRoot":"","sources":["../../src/ground/sot-cache.ts"],"names":[],"mappings":"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"}

package/dist/ground/topic-index.d.ts

@@ -0,0 +1,27 @@
+import { TopicIndex, type TopicIndexEntry } from "./schemas.js";
+/**
+ * Topic-index is the ground-state file that maps content-fingerprint
+ * slugs to the DECs they belong to. Phase 5b builds it before any
+ * extractor runs so phases 6 / 7b / 7c can dedup-by-topic instead of
+ * emitting one DEC per source. Layer A's PostToolUse hook reads it on
+ * every Write to know whether a freshly typed prose block is the first
+ * sighting of its content or a repeat of an existing topic.
+ */
+export declare function emptyTopicIndex(): TopicIndex;
+export declare function readTopicIndex(repoRoot: string): TopicIndex;
+export declare function writeTopicIndex(repoRoot: string, index: TopicIndex): string;
+/**
+ * Insert or replace a topic entry. Returns the updated index.
+ */
+export declare function setTopic(index: TopicIndex, slug: string, entry: TopicIndexEntry): TopicIndex;
+/**
+ * Look up a topic by slug. Returns null if absent.
+ */
+export declare function getTopic(index: TopicIndex, slug: string): TopicIndexEntry | null;
+/**
+ * Clear `dec_id` from any topic entry that references this DEC. Used
+ * by `cairn attention undo` for tier3-creation reversal so the topic
+ * stays in the index (next phase 5b walk can re-emit the topic) but
+ * no longer points at the now-deleted DEC.
+ */
+export declare function clearDecFromTopicIndex(index: TopicIndex, decId: string): TopicIndex;

package/dist/ground/topic-index.js

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync } from "node:fs";
+import { writeFileSafe } from "../fs.js";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { logger } from "../logger.js";
+import { topicIndexPath } from "./paths.js";
+import { TopicIndex } from "./schemas.js";
+const log = logger("ground.topic-index");
+/**
+ * Topic-index is the ground-state file that maps content-fingerprint
+ * slugs to the DECs they belong to. Phase 5b builds it before any
+ * extractor runs so phases 6 / 7b / 7c can dedup-by-topic instead of
+ * emitting one DEC per source. Layer A's PostToolUse hook reads it on
+ * every Write to know whether a freshly typed prose block is the first
+ * sighting of its content or a repeat of an existing topic.
+ */
+export function emptyTopicIndex() {
+    return { version: 1, generated: new Date().toISOString(), topics: {} };
+}
+export function readTopicIndex(repoRoot) {
+    const path = topicIndexPath(repoRoot);
+    if (!existsSync(path))
+        return emptyTopicIndex();
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = TopicIndex.safeParse(parseYaml(raw));
+        if (!parsed.success) {
+            log.warn({ path, error: parsed.error.message }, "topic-index invalid; treating as empty");
+            return emptyTopicIndex();
+        }
+        return parsed.data;
+    }
+    catch (err) {
+        log.warn({ path, err }, "topic-index read failed; treating as empty");
+        return emptyTopicIndex();
+    }
+}
+export function writeTopicIndex(repoRoot, index) {
+    const path = topicIndexPath(repoRoot);
+    const next = { ...index, generated: new Date().toISOString() };
+    writeFileSafe(path, stringifyYaml(next));
+    log.debug({ path, topics: Object.keys(next.topics).length }, "wrote topic-index");
+    return path;
+}
+/**
+ * Insert or replace a topic entry. Returns the updated index.
+ */
+export function setTopic(index, slug, entry) {
+    return {
+        ...index,
+        topics: { ...index.topics, [slug]: entry },
+    };
+}
+/**
+ * Look up a topic by slug. Returns null if absent.
+ */
+export function getTopic(index, slug) {
+    return index.topics[slug] ?? null;
+}
+/**
+ * Clear `dec_id` from any topic entry that references this DEC. Used
+ * by `cairn attention undo` for tier3-creation reversal so the topic
+ * stays in the index (next phase 5b walk can re-emit the topic) but
+ * no longer points at the now-deleted DEC.
+ */
+export function clearDecFromTopicIndex(index, decId) {
+    let mutated = false;
+    const topics = {};
+    for (const [slug, entry] of Object.entries(index.topics)) {
+        if (entry.dec_id === decId) {
+            const { dec_id: _omitted, ...rest } = entry;
+            topics[slug] = rest;
+            mutated = true;
+        }
+        else {
+            topics[slug] = entry;
+        }
+    }
+    if (!mutated)
+        return index;
+    return { ...index, topics };
+}
+//# sourceMappingURL=topic-index.js.map

package/dist/ground/topic-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-index.js","sourceRoot":"","sources":["../../src/ground/topic-index.ts"],"names":[],"mappings":"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"}

package/dist/hooks/post-tool-use/index.d.ts

@@ -17,3 +17,5 @@ export { scanForCopyLeakage } from "./copy-scanner.js";
 export type { CopyIssue } from "./copy-scanner.js";
 export { readCopySafetyConfig } from "./allowlist-reader.js";
 export type { CopySafetyConfig } from "./allowlist-reader.js";
+export { alignFile, runSotAlign } from "./sot-align.js";
+export type { AlignFileArgs, AlignFileResult, CreationVerdict, DedupVerdict, } from "./sot-align.js";

package/dist/hooks/post-tool-use/index.js

@@ -12,4 +12,5 @@ export { buildLegend } from "./legend-builder.js";
 export { runWriteGuardian } from "./write-guardian.js";
 export { scanForCopyLeakage } from "./copy-scanner.js";
 export { readCopySafetyConfig } from "./allowlist-reader.js";
+export { alignFile, runSotAlign } from "./sot-align.js";
 //# sourceMappingURL=index.js.map

package/dist/hooks/post-tool-use/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hooks/post-tool-use/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,GACX,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hooks/post-tool-use/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,GACX,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/hooks/post-tool-use/sot-align.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Layer A — live SoT alignment hook (plan §4.1).
+ *
+ * `cairn hook sot-align` runs as a PostToolUse hook on Claude Code's
+ * Write/Edit. For every prose block in the just-written file the
+ * pipeline picks one of:
+ *
+ *   - **Tier 1 (deterministic, no Haiku)** — block is a verbatim/
+ *     near-verbatim duplicate of an existing accepted DEC/INV body
+ *     (Jaccard ≥ 0.85, 3-shingle ≥ 60%, length ratio 0.5-2.0).
+ *     Auto-replace with `// §DEC-<hash>` (or `# §DEC-<hash>` per
+ *     language). Statusline blip `⬡ aligned`.
+ *
+ *   - **Tier 2 — Haiku dedup judge, two-pass.**
+ *       Pass 1 (cheap, snippet + candidate body) → `same | different |
+ *       ambiguous`. `same` → cite. `different` → next candidate.
+ *       `ambiguous` → escalate to Pass 2.
+ *       Pass 2 (full bodies + ±200-char source context + step-by-step
+ *       prompt) → `same | different | augments | ambiguous`. `same`
+ *       cite; `different` next; `augments` triggers two-stage delta:
+ *         - Stage 1 — Haiku extracts the delta prose ("NO_DELTA" → same).
+ *         - Stage 2 — Haiku classifies the delta `constraint | rationale`.
+ *           constraint → fresh INV linked via `derived_from`; rationale
+ *           → fresh DEC linked via `related`. The augmented source
+ *           gains a `// §INV-<new>` / `// §DEC-<new>` cite *alongside*
+ *           the existing one (existing token preserved).
+ *       `ambiguous` (still!) → write to `.cairn/ground/alignment-
+ *       pending/<id>.md` and surface via cairn-attention.
+ *
+ *   - **Tier 3 — Haiku creation judge, two-pass.**
+ *       Pass 1 → `decision | constraint | descriptive | ambiguous`.
+ *       `descriptive` no-op (false-positive DEC creation pollutes
+ *       ground state worse than missed capture). `ambiguous` →
+ *       escalate to Pass 2 (full prose + ±200-char context + step-by-
+ *       step prompt). Pass-2-still-ambiguous → alignment-pending.
+ *
+ * Hard rules:
+ *   - The hook never blocks the Write. Failures degrade to no-op +
+ *     log; the operator's edit always succeeds.
+ *   - Per-Write call caps: max HAIKU_PASS1_CAP Pass-1 calls + max
+ *     HAIKU_PASS2_CAP Pass-2 calls per Write. Excess defers to
+ *     `.cairn/staleness/layer-a-deferred.jsonl` for Layer C drain.
+ *   - Verdict cache at `.cairn/cache/haiku/<scope>/<blockHash>-<key>.json`
+ *     so re-running the same prose hits cache instead of Haiku.
+ *   - Source files outside Claude's repo (cwd) are skipped. Markdown
+ *     (`.md`/`.mdx`) skipped entirely — operator-curated narrative is
+ *     handled by phase 5b's topic-index + the doc-drift sensor.
+ */
+export interface AlignFileArgs {
+    repoRoot: string;
+    /** Repo-relative POSIX path written by Claude Code. */
+    filePath: string;
+    /** Claude Code session id (for statusline blips). */
+    sessionId: string | null;
+    /**
+     * Mock dedup judge — Pass 1. Default uses Haiku via runClaude.
+     */
+    mockDedupJudgePass1?: (args: {
+        blockBody: string;
+        candidate: {
+            id: string;
+            body: string;
+        };
+    }) => Promise<DedupVerdictPass1>;
+    /**
+     * Mock dedup judge — Pass 2 (CoT escalation). Default uses Haiku.
+     */
+    mockDedupJudgePass2?: (args: {
+        blockBody: string;
+        blockContext: string;
+        candidate: {
+            id: string;
+            body: string;
+        };
+    }) => Promise<DedupVerdictPass2>;
+    /**
+     * Mock delta extractor (Stage 1) — extract the prose delta when
+     * Pass 2 returns `augments`. Default uses Haiku.
+     */
+    mockDeltaExtract?: (args: {
+        blockBody: string;
+        candidateBody: string;
+    }) => Promise<string>;
+    /**
+     * Mock delta classifier (Stage 2) — `constraint | rationale`.
+     * Default uses Haiku.
+     */
+    mockDeltaClassify?: (args: {
+        delta: string;
+    }) => Promise<DeltaKind>;
+    /**
+     * Mock creation judge — Pass 1. Default uses Haiku via runClaude.
+     */
+    mockCreationJudgePass1?: (args: {
+        blockBody: string;
+        file: string;
+        line: number;
+    }) => Promise<CreationVerdict>;
+    /**
+     * Mock creation judge — Pass 2 (CoT escalation). Default uses Haiku.
+     */
+    mockCreationJudgePass2?: (args: {
+        blockBody: string;
+        blockContext: string;
+        file: string;
+        line: number;
+    }) => Promise<CreationVerdict>;
+    /**
+     * Override the per-call Pass-1 Haiku cap. Default 5 — appropriate
+     * for live PostToolUse Writes where the cost has to stay tight.
+     * Layer D (`cairn fix align`) sets this much higher (e.g. 200) so a
+     * single-file sweep can fully judge every block.
+     */
+    pass1Cap?: number;
+    /** Override the per-call Pass-2 Haiku cap. Default 2. */
+    pass2Cap?: number;
+    /**
+     * When true, suppress the Tier 3 creation pipeline entirely — Tier 1
+     * + Tier 2 dedup still run. Layer D's `--no-creation` flag sets this
+     * so a sweep only consolidates duplicates without proposing fresh
+     * DECs from prose that doesn't match anything in the ledger yet.
+     */
+    skipCreation?: boolean;
+}
+type DedupVerdictPass1 = "same" | "different" | "ambiguous";
+type DedupVerdictPass2 = "same" | "different" | "augments" | "ambiguous";
+type DeltaKind = "constraint" | "rationale";
+export type CreationVerdict = "decision" | "constraint" | "descriptive" | "ambiguous";
+/** Back-compat alias preserved for external callers. */
+export type DedupVerdict = DedupVerdictPass1;
+export interface AlignFileResult {
+    /** Number of prose blocks discovered in the written file. */
+    blocksConsidered: number;
+    /** Tier 1 deterministic auto-cites. */
+    tier1Aligned: number;
+    /** Tier 2 Haiku-confirmed cites. */
+    tier2Aligned: number;
+    /** Tier 3 fresh DECs emitted. */
+    decsCreated: number;
+    /** Tier 3 fresh INVs emitted. */
+    invsCreated: number;
+    /** Augments-DEC siblings (Pass 2 delta = rationale). */
+    augmentsDecs: number;
+    /** Augments-INV siblings (Pass 2 delta = constraint). */
+    augmentsInvs: number;
+    /** Blocks queued in `.cairn/ground/alignment-pending/`. */
+    pending: number;
+    /** Blocks deferred to staleness (cap exceeded). */
+    deferredToStaleness: number;
+    /** Blocks classified as descriptive (no-op). */
+    descriptive: number;
+    /** Blocks skipped for any reason — already-cited, length floor, etc. */
+    skipped: number;
+    /** Pass-1 Haiku calls made. */
+    haikuPass1Calls: number;
+    /** Pass-2 Haiku calls made. */
+    haikuPass2Calls: number;
+    /** Total Haiku calls (Pass 1 + Pass 2 + augments stages). Back-compat. */
+    haikuCalls: number;
+}
+/**
+ * Run the Layer A pipeline against one repo-relative file.
+ */
+export declare function alignFile(args: AlignFileArgs): Promise<AlignFileResult>;
+export declare function runSotAlign(): Promise<void>;
+export {};