@isaacriehm/cairn-core 0.4.2 → 0.5.0

package/dist/attention/serve/index.js

@@ -0,0 +1,205 @@
+/**
+ * Browser-based DEC-draft triage GUI.
+ *
+ * Spawned by `cairn attention serve` (CLI) or
+ * `cairn_attention_serve` (MCP). Operator drains the inbox in the
+ * browser instead of through `AskUserQuestion` round-trips, then
+ * clicks "I'm done" — the server writes a sentinel at
+ * `.cairn/cache/attention-done.json` that the caller polls (via
+ * `cairn_attention_wait` or by tailing the file).
+ *
+ * Why a GUI: at >15 drafts the inline `AskUserQuestion` flow burns
+ * `cairn_decision_get` calls per draft and 4-cap-per-question batches
+ * the operator through dozens of MCP turns. The browser does all the
+ * I/O directly against `.cairn/`, dropping per-triage round-trips to
+ * zero.
+ *
+ * Mechanics:
+ *   - HTTP server on a free port (or operator-supplied), bound to
+ *     127.0.0.1 so the surface is local-only.
+ *   - JSON API mirrors the existing attention handlers (bulk-accept,
+ *     dedup, resolve, restore) so all writes funnel through the same
+ *     `withWriteLock` path the MCP tools use.
+ *   - Static SPA bundle (vanilla HTML+JS+CSS) under
+ *     `cairn-core/templates/attention-ui/` — no build step.
+ *   - Idle timeout: 10 min default, reset by `/api/heartbeat`. Server
+ *     shuts down when idle exceeds the timeout or on `/api/done`.
+ */
+import { createServer } from "node:http";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { logger } from "../../logger.js";
+import { handleApi } from "./api.js";
+const log = logger("attention.serve");
+const HERE = dirname(fileURLToPath(import.meta.url));
+/**
+ * dist/attention/serve/index.js → walk up to package root, then into
+ * templates/attention-ui/. Bundled layout co-locates templates as a
+ * sibling of dist/cli.mjs (mirrors the seed.ts pattern).
+ */
+const TEMPLATES_ROOT = typeof __CAIRN_BUNDLED__ !== "undefined" && __CAIRN_BUNDLED__
+    ? join(HERE, "templates", "attention-ui")
+    : join(HERE, "..", "..", "..", "templates", "attention-ui");
+const DEFAULT_IDLE_TIMEOUT_MS = 10 * 60 * 1000;
+const DONE_TIMEOUT_GRACE_MS = 500;
+/**
+ * Per-repoRoot live-server registry. The MCP server is a single
+ * long-lived process; both `cairn_attention_serve` and
+ * `cairn_attention_wait` share this map so wait can await the live
+ * `done` promise instead of polling.
+ */
+const liveServers = new Map();
+/** Read-only accessor for `cairn_attention_wait` and tests. */
+export function getActiveAttentionServer(repoRoot) {
+    return liveServers.get(repoRoot);
+}
+/**
+ * Boot the triage server. Returns once the listener is ready;
+ * `handle.done` resolves when the operator finishes or the server
+ * idles out.
+ */
+export async function startAttentionServer(opts) {
+    const idleTimeoutMs = opts.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+    const sentinelPath = join(opts.repoRoot, ".cairn", "cache", "attention-done.json");
+    // Pre-clear any stale sentinel so the caller's wait loop isn't
+    // tricked by a previous run's payload.
+    try {
+        rmSync(sentinelPath, { force: true });
+    }
+    catch {
+        /* best-effort */
+    }
+    const counters = { accepted: 0, rejected: 0, merged: 0, edited: 0 };
+    const startedAt = new Date().toISOString();
+    let lastActivity = Date.now();
+    const touch = () => {
+        lastActivity = Date.now();
+    };
+    let resolveDone;
+    const donePromise = new Promise((resolve) => {
+        resolveDone = resolve;
+    });
+    let server;
+    let idleTimer;
+    let shutdownStarted = false;
+    const writeSentinel = (reason) => {
+        const state = {
+            reason,
+            ...counters,
+            startedAt,
+            endedAt: new Date().toISOString(),
+        };
+        try {
+            mkdirSync(dirname(sentinelPath), { recursive: true });
+            writeFileSync(sentinelPath, JSON.stringify(state, null, 2), "utf8");
+        }
+        catch (err) {
+            log.warn({ err: err instanceof Error ? err.message : String(err) }, "failed to write sentinel");
+        }
+        return state;
+    };
+    const beginShutdown = (reason) => {
+        if (shutdownStarted)
+            return;
+        shutdownStarted = true;
+        clearInterval(idleTimer);
+        const state = writeSentinel(reason);
+        setTimeout(() => {
+            server.close(() => {
+                resolveDone(state);
+            });
+        }, DONE_TIMEOUT_GRACE_MS);
+    };
+    server = createServer((req, res) => {
+        void handleRequest(req, res, {
+            repoRoot: opts.repoRoot,
+            counters,
+            touch,
+            onDone: () => beginShutdown("done"),
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(opts.port, "127.0.0.1", () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const addr = server.address();
+    const port = typeof addr === "object" && addr !== null ? addr.port : opts.port;
+    const url = `http://127.0.0.1:${port}/`;
+    idleTimer = setInterval(() => {
+        if (Date.now() - lastActivity >= idleTimeoutMs) {
+            log.info({ idleTimeoutMs }, "attention server idle — shutting down");
+            beginShutdown("idle");
+        }
+    }, 30_000);
+    if (opts.signal !== undefined) {
+        if (opts.signal.aborted) {
+            beginShutdown("abort");
+        }
+        else {
+            opts.signal.addEventListener("abort", () => beginShutdown("abort"), {
+                once: true,
+            });
+        }
+    }
+    log.info({ port, url, sentinelPath }, "attention server listening");
+    const handle = {
+        port,
+        url,
+        sentinelPath,
+        done: donePromise,
+        close: async () => {
+            beginShutdown("abort");
+            await donePromise;
+        },
+    };
+    liveServers.set(opts.repoRoot, handle);
+    void donePromise.finally(() => liveServers.delete(opts.repoRoot));
+    return handle;
+}
+async function handleRequest(req, res, ctx) {
+    ctx.touch();
+    const url = req.url ?? "/";
+    if (url === "/" || url === "/index.html") {
+        return serveStatic(res, "index.html", "text/html; charset=utf-8");
+    }
+    if (url === "/static/app.js") {
+        return serveStatic(res, "app.js", "application/javascript; charset=utf-8");
+    }
+    if (url === "/static/app.css") {
+        return serveStatic(res, "app.css", "text/css; charset=utf-8");
+    }
+    if (url.startsWith("/api/")) {
+        return handleApi(req, res, ctx);
+    }
+    res.statusCode = 404;
+    res.setHeader("content-type", "text/plain");
+    res.end("not found");
+}
+function serveStatic(res, filename, contentType) {
+    const path = join(TEMPLATES_ROOT, filename);
+    if (!existsSync(path)) {
+        res.statusCode = 500;
+        res.setHeader("content-type", "text/plain");
+        res.end(`attention-ui template missing: ${filename}`);
+        return;
+    }
+    let body;
+    try {
+        body = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        res.statusCode = 500;
+        res.setHeader("content-type", "text/plain");
+        res.end(`attention-ui template read failed: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    res.statusCode = 200;
+    res.setHeader("content-type", contentType);
+    res.setHeader("cache-control", "no-store");
+    res.end(body);
+}
+//# sourceMappingURL=index.js.map

package/dist/attention/serve/index.js.map

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

package/dist/decision-capture/id.d.ts

@@ -1,38 +1,75 @@
 /**
- * Decision + invariant id allocators. Monotonic, never reused.
+ * Content-addressed id derivation for decisions and invariants.
  *
- * Decisions: scan `.cairn/ground/decisions/` for accepted decisions AND
- * `.cairn/ground/decisions/_inbox/` for outstanding drafts. Either counts
- * toward the high-water mark — a draft that's pending operator confirmation
- * still owns its id; rejecting a draft does NOT recycle the id.
+ * Decisions: `DEC-<hash>` where `<hash>` is the first 7 hex chars of
+ *   sha256(canonicalized input). Stable across clones — two devs
+ *   that capture the same source comment in the same file produce
+ *   the same id, so concurrent adoption runs do not collide on merge.
  *
- * Invariants: scan `.cairn/ground/invariants/INV-<NNNN>.md`. Phase 7b writes
- * invariants directly to ground state (no `_inbox/` flow — they auto-promote
- * from the constraint classifier; operator edits / supersedes after the
- * fact).
+ * Invariants: same shape, `INV-<hash>`.
  *
- * Single source of truth for id allocation. The MCP write tools and the
- * init pipeline call these helpers; do NOT re-implement the scan elsewhere.
+ * On the rare hash collision against an existing on-disk id with
+ * different content, the new id extends to 8 chars. Same fallback git
+ * uses for short SHAs.
+ *
+ * Ids are never recycled — rejecting a draft renames the file to
+ * `<id>.rejected.md` so the same hash never re-allocates to a
+ * different decision.
  */
+export interface DecisionIdInput {
+    /** Title — required. Lowercased + trimmed in the hash input. */
+    title: string;
+    /** Free-text rationale or summary. */
+    rationale?: string;
+    /** Provenance source (e.g. `init-source-comments`, `init-rules-merge`, `user-record`). */
+    capture_source?: string;
+    /** Source file the decision was extracted from. */
+    source_file?: string;
+    /** Line / offset within the source file. */
+    source_offset?: number;
+    /** Original raw comment / section text. */
+    raw?: string;
+    /** Scope globs (sorted before hashing for stability). */
+    scope_globs?: string[];
+    /** Full body markdown (for manual `cairn_record_decision` calls). */
+    body_markdown?: string;
+    /**
+     * Millisecond timestamp — only set for manual user-record paths
+     * where there is no stable provenance. Source-comment / rules-merge
+     * derived ids omit this so re-running the pipeline is idempotent.
+     */
+    timestamp_ms?: number;
+}
+export interface InvariantIdInput {
+    /** Title — required. Lowercased + trimmed. */
+    title: string;
+    /** Source file the constraint was extracted from. */
+    source_file?: string;
+    /** Line / offset within the source file. */
+    source_offset?: number;
+    /** Original raw comment text. */
+    raw?: string;
+    /** Millisecond timestamp — manual writes only. */
+    timestamp_ms?: number;
+}
 /**
- * Scan both the canonical decisions dir and the `_inbox/` for
- * DEC-NNNN-prefixed files; return the set of ids found.
+ * Compute a stable `DEC-<hash>` id from the canonical input. When
+ * `existing` is supplied and the 7-char prefix collides with an id
+ * already in that set whose content differs, the id extends to 8+
+ * chars until unique.
  */
-export declare function scanExistingDecisionIds(repoRoot: string): Set<string>;
+export declare function computeDecisionId(input: DecisionIdInput, existing?: Set<string>): string;
 /**
- * Return the next free `DEC-<NNNN>` id, optionally factoring in a
- * caller-supplied set (e.g. ids the MCP tool just validated against).
+ * Compute a stable `INV-<hash>` id from the canonical input. Same
+ * collision-extension behavior as `computeDecisionId`.
  */
-export declare function allocateDecisionId(repoRoot: string, existing?: Set<string>): string;
+export declare function computeInvariantId(input: InvariantIdInput, existing?: Set<string>): string;
 /**
- * Scan `.cairn/ground/invariants/` for INV-<NNNN>-prefixed files; return the
- * set of ids found.
+ * Scan both the canonical decisions dir and `_inbox/` for
+ * `DEC-<hash>` filenames; return the set of ids found.
  */
-export declare function scanExistingInvariantIds(repoRoot: string): Set<string>;
+export declare function scanExistingDecisionIds(repoRoot: string): Set<string>;
 /**
- * Return the next free `INV-<NNNN>` id — matches the schema regex
- * at packages/cairn-core/src/ground/schemas.ts. Optionally factor in
- * a caller-supplied set so a batch of allocations doesn't collide on
- * disk before any are written.
+ * Scan `.cairn/ground/invariants/` for `INV-<hash>` filenames.
  */
-export declare function allocateInvariantId(repoRoot: string, existing?: Set<string>): string;
+export declare function scanExistingInvariantIds(repoRoot: string): Set<string>;

package/dist/decision-capture/id.js

@@ -1,29 +1,87 @@
 /**
- * Decision + invariant id allocators. Monotonic, never reused.
+ * Content-addressed id derivation for decisions and invariants.
  *
- * Decisions: scan `.cairn/ground/decisions/` for accepted decisions AND
- * `.cairn/ground/decisions/_inbox/` for outstanding drafts. Either counts
- * toward the high-water mark — a draft that's pending operator confirmation
- * still owns its id; rejecting a draft does NOT recycle the id.
+ * Decisions: `DEC-<hash>` where `<hash>` is the first 7 hex chars of
+ *   sha256(canonicalized input). Stable across clones — two devs
+ *   that capture the same source comment in the same file produce
+ *   the same id, so concurrent adoption runs do not collide on merge.
  *
- * Invariants: scan `.cairn/ground/invariants/INV-<NNNN>.md`. Phase 7b writes
- * invariants directly to ground state (no `_inbox/` flow — they auto-promote
- * from the constraint classifier; operator edits / supersedes after the
- * fact).
+ * Invariants: same shape, `INV-<hash>`.
  *
- * Single source of truth for id allocation. The MCP write tools and the
- * init pipeline call these helpers; do NOT re-implement the scan elsewhere.
+ * On the rare hash collision against an existing on-disk id with
+ * different content, the new id extends to 8 chars. Same fallback git
+ * uses for short SHAs.
+ *
+ * Ids are never recycled — rejecting a draft renames the file to
+ * `<id>.rejected.md` so the same hash never re-allocates to a
+ * different decision.
  */
+import { createHash } from "node:crypto";
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { decisionsDir, invariantsDir } from "../ground/paths.js";
-const FILENAME_RE = /^DEC-(\d{4,})(?:\.draft|\.rejected)?\.md$/;
-// Invariant filename: `INV-<NNNN>.md` — matches the schema id
-// regex /^INV-\d{4,}$/ at packages/cairn-core/src/ground/schemas.ts.
-const INVARIANT_FILENAME_RE = /^INV-(\d{4,})\.md$/;
+/** Default short-hash length (matches git short-SHA convention). */
+const HASH_LEN = 7;
+/** DEC filename: `DEC-<hex>.md`, optionally `.draft` or `.rejected`. */
+const FILENAME_RE = /^DEC-([0-9a-f]{7,})(?:\.draft|\.rejected)?\.md$/;
+/** INV filename: `INV-<hex>.md`. Matches the schema id regex in `ground/schemas.ts`. */
+const INVARIANT_FILENAME_RE = /^INV-([0-9a-f]{7,})\.md$/;
+function canonicalDecision(input) {
+    return JSON.stringify({
+        title: input.title.trim().toLowerCase(),
+        rationale: input.rationale ?? null,
+        capture_source: input.capture_source ?? null,
+        source_file: input.source_file ?? null,
+        source_offset: input.source_offset ?? null,
+        raw: input.raw ?? null,
+        scope_globs: input.scope_globs !== undefined ? [...input.scope_globs].sort() : null,
+        body_markdown: input.body_markdown ?? null,
+        timestamp_ms: input.timestamp_ms ?? null,
+    });
+}
+function canonicalInvariant(input) {
+    return JSON.stringify({
+        title: input.title.trim().toLowerCase(),
+        source_file: input.source_file ?? null,
+        source_offset: input.source_offset ?? null,
+        raw: input.raw ?? null,
+        timestamp_ms: input.timestamp_ms ?? null,
+    });
+}
+/**
+ * Compute a stable `DEC-<hash>` id from the canonical input. When
+ * `existing` is supplied and the 7-char prefix collides with an id
+ * already in that set whose content differs, the id extends to 8+
+ * chars until unique.
+ */
+export function computeDecisionId(input, existing) {
+    const digest = createHash("sha256").update(canonicalDecision(input)).digest("hex");
+    for (let len = HASH_LEN; len <= digest.length; len++) {
+        const candidate = `DEC-${digest.slice(0, len)}`;
+        if (existing === undefined || !existing.has(candidate))
+            return candidate;
+    }
+    throw new Error("computeDecisionId: hash exhaustion (impossible at sha256)");
+}
+/**
+ * Compute a stable `INV-<hash>` id from the canonical input. Same
+ * collision-extension behavior as `computeDecisionId`.
+ */
+export function computeInvariantId(input, existing) {
+    const digest = createHash("sha256").update(canonicalInvariant(input)).digest("hex");
+    for (let len = HASH_LEN; len <= digest.length; len++) {
+        const candidate = `INV-${digest.slice(0, len)}`;
+        if (existing === undefined || !existing.has(candidate))
+            return candidate;
+    }
+    throw new Error("computeInvariantId: hash exhaustion (impossible at sha256)");
+}
+/* -------------------------------------------------------------------------- */
+/* On-disk scans (used for collision check + auxiliary lookups)               */
+/* -------------------------------------------------------------------------- */
 /**
- * Scan both the canonical decisions dir and the `_inbox/` for
- * DEC-NNNN-prefixed files; return the set of ids found.
+ * Scan both the canonical decisions dir and `_inbox/` for
+ * `DEC-<hash>` filenames; return the set of ids found.
  */
 export function scanExistingDecisionIds(repoRoot) {
     const dir = decisionsDir(repoRoot);
@@ -43,31 +101,13 @@ export function scanExistingDecisionIds(repoRoot) {
             const match = name.match(FILENAME_RE);
             if (!match || !match[1])
                 continue;
-            ids.add(`DEC-${match[1].padStart(4, "0")}`);
+            ids.add(`DEC-${match[1]}`);
         }
     }
     return ids;
 }
 /**
- * Return the next free `DEC-<NNNN>` id, optionally factoring in a
- * caller-supplied set (e.g. ids the MCP tool just validated against).
- */
-export function allocateDecisionId(repoRoot, existing) {
-    const ids = existing ?? scanExistingDecisionIds(repoRoot);
-    let max = 0;
-    for (const id of ids) {
-        const m = id.match(/^DEC-(\d+)$/);
-        if (!m?.[1])
-            continue;
-        const n = Number.parseInt(m[1], 10);
-        if (Number.isFinite(n) && n > max)
-            max = n;
-    }
-    return `DEC-${(max + 1).toString().padStart(4, "0")}`;
-}
-/**
- * Scan `.cairn/ground/invariants/` for INV-<NNNN>-prefixed files; return the
- * set of ids found.
+ * Scan `.cairn/ground/invariants/` for `INV-<hash>` filenames.
  */
 export function scanExistingInvariantIds(repoRoot) {
     const dir = invariantsDir(repoRoot);
@@ -85,27 +125,8 @@ export function scanExistingInvariantIds(repoRoot) {
         const match = name.match(INVARIANT_FILENAME_RE);
         if (!match || !match[1])
             continue;
-        ids.add(`INV-${match[1].padStart(4, "0")}`);
+        ids.add(`INV-${match[1]}`);
     }
     return ids;
 }
-/**
- * Return the next free `INV-<NNNN>` id — matches the schema regex
- * at packages/cairn-core/src/ground/schemas.ts. Optionally factor in
- * a caller-supplied set so a batch of allocations doesn't collide on
- * disk before any are written.
- */
-export function allocateInvariantId(repoRoot, existing) {
-    const ids = existing ?? scanExistingInvariantIds(repoRoot);
-    let max = 0;
-    for (const id of ids) {
-        const m = id.match(/^INV-(\d+)$/);
-        if (!m?.[1])
-            continue;
-        const n = Number.parseInt(m[1], 10);
-        if (Number.isFinite(n) && n > max)
-            max = n;
-    }
-    return `INV-${(max + 1).toString().padStart(4, "0")}`;
-}
 //# sourceMappingURL=id.js.map

package/dist/decision-capture/id.js.map

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

package/dist/decision-capture/index.d.ts

@@ -1,10 +1,10 @@
 /**
  * Decision-capture surface.
  *
- * Only the monotonic id allocators remain — the Tier-1 LLM extractor +
- * refinement pipeline was orchestrator-era code (auto-extract DECs from
+ * Only the content-addressed id helpers remain — the Tier-1 LLM extractor
+ * + refinement pipeline was orchestrator-era code (auto-extract DECs from
  * sessions) that is no longer wired into the plugin flow. Operator-driven
  * DEC creation lives in the `cairn-direction` skill + the
  * `cairn_record_decision` MCP tool now.
  */
-export { allocateDecisionId, allocateInvariantId, scanExistingDecisionIds, scanExistingInvariantIds, } from "./id.js";
+export { computeDecisionId, computeInvariantId, scanExistingDecisionIds, scanExistingInvariantIds, type DecisionIdInput, type InvariantIdInput, } from "./id.js";

package/dist/decision-capture/index.js

@@ -1,11 +1,11 @@
 /**
  * Decision-capture surface.
  *
- * Only the monotonic id allocators remain — the Tier-1 LLM extractor +
- * refinement pipeline was orchestrator-era code (auto-extract DECs from
+ * Only the content-addressed id helpers remain — the Tier-1 LLM extractor
+ * + refinement pipeline was orchestrator-era code (auto-extract DECs from
  * sessions) that is no longer wired into the plugin flow. Operator-driven
  * DEC creation lives in the `cairn-direction` skill + the
  * `cairn_record_decision` MCP tool now.
  */
-export { allocateDecisionId, allocateInvariantId, scanExistingDecisionIds, scanExistingInvariantIds, } from "./id.js";
+export { computeDecisionId, computeInvariantId, scanExistingDecisionIds, scanExistingInvariantIds, } from "./id.js";
 //# sourceMappingURL=index.js.map

package/dist/decision-capture/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/decision-capture/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/decision-capture/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,GAGzB,MAAM,SAAS,CAAC"}

package/dist/drain/drain.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Layer C — SessionStart drain (plan §4.3).
+ *
+ * Reads the rich deferred logs written by Layer A
+ * (`.cairn/staleness/layer-a-deferred.jsonl`) and Layer B
+ * (`.cairn/staleness/pre-commit-deferred.jsonl`), re-checks each entry
+ * against the current source location, and applies one of three
+ * verdicts to each surviving entry:
+ *
+ *   - `same`       → strip-replace the prose block with `// §DEC-<id>`
+ *                    cite. Pure deterministic for Layer B `tier1`
+ *                    entries (the pre-commit hook already passed the
+ *                    Tier 1 floors); Haiku-judged for everything else.
+ *   - `different`  → drop the entry, no source change.
+ *   - `ambiguous`  → write to `.cairn/ground/alignment-pending/` so
+ *                    the cairn-attention skill surfaces a side-by-side
+ *                    review next session.
+ *
+ * Drain truncates both deferred logs after running. The lightweight
+ * drift events in `.cairn/staleness/log.jsonl` are an audit trail and
+ * stay.
+ *
+ * Cost: capped at `max_haiku_calls` (default 30 per plan §4.3 budget).
+ * Excess entries stay in the deferred logs for the next drain. Each
+ * Haiku call is verdict-cached at
+ * `.cairn/cache/haiku/drain-judge/<blockHash>-<decId>.json` keyed on
+ * `(block_content_hash, dec_body_hash)`, so re-running the same block
+ * against the same DEC body short-circuits without burning a call.
+ *
+ * Haiku unavailable fallback: drain attempts the deterministic re-check
+ * pass only (Layer B tier1 entries get applied; everything else stays
+ * deferred). `setHaikuAvailable(false)` raises the statusline banner.
+ */
+export type DrainJudgeVerdict = "same" | "different" | "ambiguous";
+export interface DrainArgs {
+    repoRoot: string;
+    /** When provided, drain pushes drain-progress / drain-done blips to this session's queue. */
+    sessionId?: string | null;
+    /** Hard cap on Haiku judge calls. Default 30 (plan §4.3). */
+    maxHaikuCalls?: number;
+    /** Dry run — classify but do not strip-replace, write alignment-pending, or truncate logs. */
+    dryRun?: boolean;
+    /**
+     * Inject the dedup judge — bypasses the live Haiku call. Used by
+     * smoke fixtures and the `cairn align drain --mock` debug path.
+     */
+    mockJudge?: (args: {
+        blockBody: string;
+        candidate: {
+            id: string;
+            body: string;
+        };
+    }) => Promise<DrainJudgeVerdict>;
+    /** Override Haiku availability detection (smoke fixtures). */
+    haikuAvailable?: boolean;
+}
+export interface DrainResult {
+    /** Total entries read from both deferred logs. */
+    totalEntries: number;
+    /** Entries whose source block could not be relocated (gone / edited / cited). */
+    droppedMissing: number;
+    /** Entries auto-cited via deterministic re-check (Layer B tier1). */
+    citedDeterministic: number;
+    /** Entries auto-cited via Haiku `same` verdict. */
+    citedHaiku: number;
+    /** Entries dropped via Haiku `different` verdict. */
+    droppedDifferent: number;
+    /** Entries written to alignment-pending via Haiku `ambiguous` verdict. */
+    pending: number;
+    /** Entries left in the deferred logs because the Haiku cap was hit or Haiku is offline. */
+    deferred: number;
+    /** Total Haiku calls actually issued (cache hits do not count). */
+    haikuCalls: number;
+    /** True when the drain ran without Haiku (fallback path). */
+    haikuFallback: boolean;
+}
+export declare function runDrain(args: DrainArgs): Promise<DrainResult>;