@isaacriehm/cairn-core 0.1.0

package/dist/lock.js

@@ -0,0 +1,129 @@
+/**
+ * Per-write filesystem lock for `.cairn/` global state.
+ *
+ * Per docs/PLUGIN_ARCHITECTURE.md §7 (Concurrency): every write to global
+ * state (`.cairn/ground/`, `.cairn/baseline/`, `.cairn/inbox/`) is
+ * serialized through `.cairn/.write-lock` so concurrent Claude Code
+ * sessions don't race. Reads are unlocked. Whole-operation locks
+ * (`.gc-lock`, `.audit-lock`) are separate — see acquireOperationLock.
+ *
+ * Design:
+ *   - `wx` (O_CREAT | O_EXCL) atomic-create on the lock file. PID written
+ *     inside so stale-holder detection can recover from crashes.
+ *   - Stale-lock recovery: if the holder PID is gone, claim the lock.
+ *   - Polling backoff with deadline. Brief contention; long waits indicate
+ *     deadlock and surface as timeout errors.
+ */
+import { mkdir, open, readFile, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_POLL_MS = 50;
+/**
+ * Acquire `.cairn/.write-lock` for the lifetime of `fn`. Releases on
+ * success or error. Stale locks (holder PID is dead) are reclaimed.
+ */
+export async function withWriteLock(repoRoot, fn, opts = {}) {
+    return withLockAtPath(join(repoRoot, ".cairn", ".write-lock"), fn, opts);
+}
+/**
+ * Acquire a named operation lock (e.g. `.gc-lock`, `.audit-lock`) for the
+ * lifetime of `fn`. If the lock is held, this throws immediately rather
+ * than waiting — callers (sweep, audit) use this to bail with "another
+ * operation in progress".
+ */
+export async function acquireOperationLock(repoRoot, lockName, fn) {
+    const lockPath = join(repoRoot, ".cairn", lockName);
+    await mkdir(dirname(lockPath), { recursive: true });
+    const acquired = await tryAcquire(lockPath);
+    if (!acquired) {
+        throw new OperationLockHeldError(lockName, await readHolderPid(lockPath));
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        await unlink(lockPath).catch(() => { });
+    }
+}
+export class OperationLockHeldError extends Error {
+    lockName;
+    holderPid;
+    constructor(lockName, holderPid) {
+        super(`operation lock ${lockName} is held${holderPid !== null ? ` by pid ${holderPid}` : ""}`);
+        this.lockName = lockName;
+        this.holderPid = holderPid;
+        this.name = "OperationLockHeldError";
+    }
+}
+async function withLockAtPath(lockPath, fn, opts) {
+    await mkdir(dirname(lockPath), { recursive: true });
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
+    const deadline = Date.now() + timeoutMs;
+    // Spin until acquired or deadline.
+    while (true) {
+        if (await tryAcquire(lockPath))
+            break;
+        if (await reclaimIfStale(lockPath)) {
+            if (await tryAcquire(lockPath))
+                break;
+        }
+        if (Date.now() >= deadline) {
+            const holder = await readHolderPid(lockPath);
+            throw new Error(`write lock timeout after ${timeoutMs}ms${holder !== null ? ` (held by pid ${holder})` : ""}`);
+        }
+        await sleep(pollMs);
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        await unlink(lockPath).catch(() => { });
+    }
+}
+async function tryAcquire(lockPath) {
+    try {
+        const fd = await open(lockPath, "wx");
+        await fd.write(`${process.pid}\n`);
+        await fd.close();
+        return true;
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            return false;
+        throw err;
+    }
+}
+async function readHolderPid(lockPath) {
+    try {
+        const body = await readFile(lockPath, "utf8");
+        const n = Number.parseInt(body.trim(), 10);
+        return Number.isFinite(n) ? n : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function reclaimIfStale(lockPath) {
+    const pid = await readHolderPid(lockPath);
+    if (pid === null)
+        return false;
+    if (isProcessAlive(pid))
+        return false;
+    await unlink(lockPath).catch(() => { });
+    return true;
+}
+function isProcessAlive(pid) {
+    try {
+        // Sending signal 0 throws if the process doesn't exist.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=lock.js.map

package/dist/lock.js.map

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

package/dist/logger.d.ts

@@ -0,0 +1,13 @@
+import { type Logger } from "pino";
+export declare function logger(module: string): Logger;
+export declare const rootLogger: Logger;
+/**
+ * Redirect all subsequent pino output to `absPath`. Creates parent dirs as
+ * needed. Returns the path written to. Subsequent calls swap to the new
+ * file (the previous stream stays open for whatever Node's GC decides).
+ */
+export declare function setLogFile(absPath: string): string;
+/** Re-route logger output to stderr. Useful for long-lived daemons. */
+export declare function setLogStderr(): void;
+/** Drop logger output entirely. Used by smokes that don't want noise. */
+export declare function setLogNull(): void;

package/dist/logger.js

@@ -0,0 +1,78 @@
+import { createWriteStream, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { Writable } from "node:stream";
+import { pino } from "pino";
+/**
+ * Pino destination indirection. By default pino logs go to a black-hole
+ * writable so structured log lines never leak into a CLI's terminal output.
+ * Init / daemon / watch flows call `setLogFile(path)` early to redirect to
+ * a file. Long-lived background processes (daemon) can call `setLogStderr()`
+ * to fall back to stderr.
+ *
+ * Children created via `logger(module)` write to whichever destination is
+ * currently active at the time of the write — child references stay valid
+ * across redirection.
+ */
+let activeDestination = nullStream();
+const proxyStream = new Writable({
+    write(chunk, _encoding, callback) {
+        try {
+            const buf = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+            activeDestination.write(buf, () => callback());
+        }
+        catch (err) {
+            callback(err instanceof Error ? err : new Error(String(err)));
+        }
+    },
+});
+const root = pino({
+    level: process.env["CAIRN_LOG_LEVEL"] ?? "info",
+    base: { pid: process.pid },
+    redact: {
+        paths: [
+            "*.token",
+            "*.password",
+            "*.secret",
+            "*.apiKey",
+            "*.api_key",
+            "headers.authorization",
+            "headers.cookie",
+        ],
+        censor: "[redacted]",
+    },
+    timestamp: pino.stdTimeFunctions.isoTime,
+}, proxyStream);
+export function logger(module) {
+    return root.child({ module });
+}
+export const rootLogger = root;
+/**
+ * Redirect all subsequent pino output to `absPath`. Creates parent dirs as
+ * needed. Returns the path written to. Subsequent calls swap to the new
+ * file (the previous stream stays open for whatever Node's GC decides).
+ */
+export function setLogFile(absPath) {
+    mkdirSync(dirname(absPath), { recursive: true });
+    const stream = createWriteStream(absPath, {
+        flags: "a",
+        encoding: "utf8",
+    });
+    activeDestination = stream;
+    return absPath;
+}
+/** Re-route logger output to stderr. Useful for long-lived daemons. */
+export function setLogStderr() {
+    activeDestination = process.stderr;
+}
+/** Drop logger output entirely. Used by smokes that don't want noise. */
+export function setLogNull() {
+    activeDestination = nullStream();
+}
+function nullStream() {
+    return new Writable({
+        write(_chunk, _enc, callback) {
+            callback();
+        },
+    });
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAoB,MAAM,SAAS,CAAC;AACzE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,IAAI,EAAe,MAAM,MAAM,CAAC;AAEzC;;;;;;;;;;GAUG;AAEH,IAAI,iBAAiB,GAA0B,UAAU,EAAE,CAAC;AAE5D,MAAM,WAAW,GAAG,IAAI,QAAQ,CAAC;IAC/B,KAAK,CAAC,KAAsB,EAAE,SAAS,EAAE,QAAQ;QAC/C,IAAI,CAAC;YACH,MAAM,GAAG,GACP,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;YACjE,iBAAiB,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;QACjD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAChE,CAAC;IACH,CAAC;CACF,CAAC,CAAC;AAEH,MAAM,IAAI,GAAW,IAAI,CACvB;IACE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,MAAM;IAC/C,IAAI,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;IAC1B,MAAM,EAAE;QACN,KAAK,EAAE;YACL,SAAS;YACT,YAAY;YACZ,UAAU;YACV,UAAU;YACV,WAAW;YACX,uBAAuB;YACvB,gBAAgB;SACjB;QACD,MAAM,EAAE,YAAY;KACrB;IACD,SAAS,EAAE,IAAI,CAAC,gBAAgB,CAAC,OAAO;CACzC,EACD,WAAW,CACZ,CAAC;AAEF,MAAM,UAAU,MAAM,CAAC,MAAc;IACnC,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAC;AAE/B;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACjD,MAAM,MAAM,GAAgB,iBAAiB,CAAC,OAAO,EAAE;QACrD,KAAK,EAAE,GAAG;QACV,QAAQ,EAAE,MAAM;KACjB,CAAC,CAAC;IACH,iBAAiB,GAAG,MAAM,CAAC;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,YAAY;IAC1B,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;AACrC,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,UAAU;IACxB,iBAAiB,GAAG,UAAU,EAAE,CAAC;AACnC,CAAC;AAED,SAAS,UAAU;IACjB,OAAO,IAAI,QAAQ,CAAC;QAClB,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ;YAC1B,QAAQ,EAAE,CAAC;QACb,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/mcp/bootstrap-guard.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Bootstrap guard for MCP write tools.
+ *
+ * Spec: PLUGIN_ARCHITECTURE §17 Layer 4 (degraded mode).
+ *
+ * Each MCP write tool calls `requireBootstrap(repoRoot)` at the top of its
+ * executor. When the clone is unbootstrapped, the helper returns a
+ * `BOOTSTRAP_REQUIRED` envelope and the tool short-circuits — no lock, no
+ * filesystem write. Read tools (decision-get, search, etc.) skip this guard
+ * entirely, matching spec §17 "MCP read tools work (read-only)".
+ *
+ * Bootstrap state is cheap to inspect (one `git config --get`); we don't
+ * cache because a session that ran `cairn join` mid-conversation should
+ * be able to write on its next call.
+ */
+import { type McpErrorPayload } from "./errors.js";
+/**
+ * The guard only blocks when *all three* are true:
+ *   1. `<repoRoot>/.git/` exists (otherwise this isn't a real clone)
+ *   2. `<repoRoot>/.cairn/config.yaml` exists (otherwise the project
+ *      isn't actually cairn-adopted yet — `cairn init` will land it)
+ *   3. `git config core.hooksPath` is *not* `.cairn/git-hooks`
+ *
+ * Everything else passes through. This keeps unit / smoke fixtures that
+ * scaffold a partial `.cairn/` from being incorrectly degraded; the only
+ * scenario that trips the guard is a real adopted project on a clone where
+ * `cairn join` hasn't run yet.
+ */
+export declare function requireBootstrap(repoRoot: string): McpErrorPayload | null;

package/dist/mcp/bootstrap-guard.js

@@ -0,0 +1,47 @@
+/**
+ * Bootstrap guard for MCP write tools.
+ *
+ * Spec: PLUGIN_ARCHITECTURE §17 Layer 4 (degraded mode).
+ *
+ * Each MCP write tool calls `requireBootstrap(repoRoot)` at the top of its
+ * executor. When the clone is unbootstrapped, the helper returns a
+ * `BOOTSTRAP_REQUIRED` envelope and the tool short-circuits — no lock, no
+ * filesystem write. Read tools (decision-get, search, etc.) skip this guard
+ * entirely, matching spec §17 "MCP read tools work (read-only)".
+ *
+ * Bootstrap state is cheap to inspect (one `git config --get`); we don't
+ * cache because a session that ran `cairn join` mid-conversation should
+ * be able to write on its next call.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { inspectJoinState } from "../join/index.js";
+import { mcpError } from "./errors.js";
+/**
+ * The guard only blocks when *all three* are true:
+ *   1. `<repoRoot>/.git/` exists (otherwise this isn't a real clone)
+ *   2. `<repoRoot>/.cairn/config.yaml` exists (otherwise the project
+ *      isn't actually cairn-adopted yet — `cairn init` will land it)
+ *   3. `git config core.hooksPath` is *not* `.cairn/git-hooks`
+ *
+ * Everything else passes through. This keeps unit / smoke fixtures that
+ * scaffold a partial `.cairn/` from being incorrectly degraded; the only
+ * scenario that trips the guard is a real adopted project on a clone where
+ * `cairn join` hasn't run yet.
+ */
+export function requireBootstrap(repoRoot) {
+    if (!existsSync(join(repoRoot, ".git")))
+        return null;
+    if (!existsSync(join(repoRoot, ".cairn", "config.yaml")))
+        return null;
+    const state = inspectJoinState({ repoRoot });
+    if (state.hooksPathSet)
+        return null;
+    return mcpError("BOOTSTRAP_REQUIRED", "this clone is not bootstrapped — run `cairn join` (or pick [a] on the inline SessionStart prompt) before cairn write tools engage", {
+        project_cairn_version: state.projectCairnVersion,
+        hooks_path_value: state.hooksPathValue,
+        sessions_dir_ready: state.sessionsDirReady,
+        remediation: "cairn join",
+    });
+}
+//# sourceMappingURL=bootstrap-guard.js.map

package/dist/mcp/bootstrap-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap-guard.js","sourceRoot":"","sources":["../../src/mcp/bootstrap-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAwB,MAAM,aAAa,CAAC;AAE7D;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACrD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACtE,MAAM,KAAK,GAAG,gBAAgB,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC7C,IAAI,KAAK,CAAC,YAAY;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO,QAAQ,CACb,oBAAoB,EACpB,mIAAmI,EACnI;QACE,qBAAqB,EAAE,KAAK,CAAC,mBAAmB;QAChD,gBAAgB,EAAE,KAAK,CAAC,cAAc;QACtC,kBAAkB,EAAE,KAAK,CAAC,gBAAgB;QAC1C,WAAW,EAAE,YAAY;KAC1B,CACF,CAAC;AACJ,CAAC"}

package/dist/mcp/context.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Per-server context. Set at server start; passed to every tool handler.
+ *
+ * The MCP server is started with `--repo-root <path>` (or CAIRN_REPO_ROOT
+ * env). All tool handlers operate against this root. The orchestrator pins a
+ * mirror checkout SHA and starts a server with that mirror's path as repoRoot.
+ *
+ * `sessionId` is stamped onto every invalidation event emitted by a write
+ * tool. When the plugin spawns the MCP server it forwards Claude Code's
+ * session_id; CLI invocations leave it null.
+ */
+export interface McpContext {
+    repoRoot: string;
+    /** Optional run id — when set, telemetry writes per-run; otherwise, top-level. */
+    runId?: string;
+    /** Claude Code session id of the spawning client, when known. */
+    sessionId?: string | null;
+}
+export declare function createContext(opts: {
+    repoRoot: string;
+    runId?: string;
+    sessionId?: string | null;
+}): McpContext;

package/dist/mcp/context.js

@@ -0,0 +1,9 @@
+import { resolve } from "node:path";
+export function createContext(opts) {
+    return {
+        repoRoot: resolve(opts.repoRoot),
+        ...(opts.runId !== undefined ? { runId: opts.runId } : {}),
+        ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/mcp/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/mcp/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqBpC,MAAM,UAAU,aAAa,CAAC,IAI7B;IACC,OAAO;QACL,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC;QAChC,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvE,CAAC;AACJ,CAAC"}

package/dist/mcp/errors.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Error envelope per MCP_SURFACE §"Failure modes".
+ *
+ * Tools NEVER throw. They return either a success payload or an error envelope
+ * shaped as { error: { code, message, details? } }. The envelope is wrapped in
+ * the MCP `CallToolResult` content text.
+ */
+export type McpErrorCode = "VALIDATION_FAILED" | "TOOL_NOT_FOUND" | "PATH_OUTSIDE_REPO" | "PATH_HISTORICAL_USE_QUERY_HISTORY" | "PATH_NOT_ALLOWED" | "FILE_NOT_FOUND" | "DAEMON_UNAVAILABLE" | "OPERATION_TIMEOUT" | "DECISION_NOT_FOUND" | "DECISION_ID_TAKEN" | "INVALID_ASSERTION_KIND" | "SUPERSEDES_NOT_FOUND" | "INVARIANT_NOT_FOUND" | "TOPIC_NOT_REGISTERED" | "RUN_NOT_FOUND" | "TASK_NOT_FOUND" | "NOT_ALLOWED" | "NOT_IMPLEMENTED" | "BOOTSTRAP_REQUIRED";
+export interface McpErrorPayload {
+    error: {
+        code: McpErrorCode;
+        message: string;
+        details?: unknown;
+    };
+}
+export declare function mcpError(code: McpErrorCode, message: string, details?: unknown): McpErrorPayload;
+export declare function isMcpError(payload: unknown): payload is McpErrorPayload;

package/dist/mcp/errors.js

@@ -0,0 +1,23 @@
+/**
+ * Error envelope per MCP_SURFACE §"Failure modes".
+ *
+ * Tools NEVER throw. They return either a success payload or an error envelope
+ * shaped as { error: { code, message, details? } }. The envelope is wrapped in
+ * the MCP `CallToolResult` content text.
+ */
+export function mcpError(code, message, details) {
+    return {
+        error: {
+            code,
+            message,
+            ...(details !== undefined ? { details } : {}),
+        },
+    };
+}
+export function isMcpError(payload) {
+    return (typeof payload === "object" &&
+        payload !== null &&
+        "error" in payload &&
+        typeof payload.error === "object");
+}
+//# sourceMappingURL=errors.js.map

package/dist/mcp/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/mcp/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA+BH,MAAM,UAAU,QAAQ,CACtB,IAAkB,EAClB,OAAe,EACf,OAAiB;IAEjB,OAAO;QACL,KAAK,EAAE;YACL,IAAI;YACJ,OAAO;YACP,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9C;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAgB;IACzC,OAAO,CACL,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,KAAK,IAAI;QAChB,OAAO,IAAI,OAAO;QAClB,OAAQ,OAA8B,CAAC,KAAK,KAAK,QAAQ,CAC1D,CAAC;AACJ,CAAC"}

package/dist/mcp/history/index.d.ts

@@ -0,0 +1,6 @@
+export { walkArchive } from "./walker.js";
+export type { ArchiveFile, WalkArchiveOptions, WalkArchiveResult } from "./walker.js";
+export { HISTORY_SUMMARIZER_SYSTEM_PROMPT, buildHistorySummarizerUserPrompt, CAIRN_HISTORY_SUMMARIZE_PROMPT_ID, CAIRN_HISTORY_SUMMARIZE_VERSION, } from "./prompt.js";
+export { HISTORY_SUMMARIZER_OUTPUT_SCHEMA } from "./schema.js";
+export { runHistorySummarizer, runQueryHistory, } from "./summarizer.js";
+export type { QueryHistoryResponse, RunQueryHistoryArgs, SummarizedClaim, } from "./summarizer.js";

package/dist/mcp/history/index.js

@@ -0,0 +1,5 @@
+export { walkArchive } from "./walker.js";
+export { HISTORY_SUMMARIZER_SYSTEM_PROMPT, buildHistorySummarizerUserPrompt, CAIRN_HISTORY_SUMMARIZE_PROMPT_ID, CAIRN_HISTORY_SUMMARIZE_VERSION, } from "./prompt.js";
+export { HISTORY_SUMMARIZER_OUTPUT_SCHEMA } from "./schema.js";
+export { runHistorySummarizer, runQueryHistory, } from "./summarizer.js";
+//# sourceMappingURL=index.js.map

package/dist/mcp/history/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp/history/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EACL,gCAAgC,EAChC,gCAAgC,EAChC,iCAAiC,EACjC,+BAA+B,GAChC,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gCAAgC,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,oBAAoB,EACpB,eAAe,GAChB,MAAM,iBAAiB,CAAC"}

package/dist/mcp/history/prompt.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Tier-1 (Haiku) summarizer prompts for cairn_query_history.
+ *
+ * Constraint: the LLM emits ONLY structured claims; raw historical
+ * content never reaches the agent's context. Each claim cites a
+ * concrete source_path + source_lines so the operator (and any future
+ * audit) can verify the summary against the original.
+ *
+ * The prompt id + version are committed in source so a behavior change
+ * here is a versioned change in the source tree, not a silent runtime
+ * update.
+ */
+import type { ArchiveFile } from "./walker.js";
+export declare const CAIRN_HISTORY_SUMMARIZE_PROMPT_ID = "cairn.history_summarize.v1";
+export declare const CAIRN_HISTORY_SUMMARIZE_VERSION = "v1";
+export declare const HISTORY_SUMMARIZER_SYSTEM_PROMPT = "You are the **history summarizer** for an agent cairn's two-zone read separation. The agent calling you cannot read .archive/ files directly \u2014 by design. You read those files on its behalf and emit a structured response with cited claims. Only your structured response reaches the agent's context.\n\nYour job: read N historical files and the operator's scope question. Produce per-claim records that capture what the historical files said, with full citation, dates, and supersedes-tags pointing at currently-canonical decisions when they exist.\n\n## Hard contract\n\nEvery claim you emit MUST include:\n\n- `claim` \u2014 one-sentence factual statement of what the historical content said. Past-tense. Imperative voice avoided. Example: \"The project considered using a JSONB expression index on commandPayload->>'userId' for dashboard queries.\" NOT \"The project should use a JSONB index\" \u2014 that is current-tense and reads as canon.\n- `as_of` \u2014 ISO date when the source content was authored / valid. Use the file's frontmatter `generated` or `verified-at`, the bucket date in the path (`.archive/2026-05-pre-cairn/`), or the most explicit date you can find in the body. If genuinely unknown, set the bucket date.\n- `source_path` \u2014 the repo-relative path EXACTLY as given in the file headers. Do not invent a path or a hash.\n- `source_lines` \u2014 line range like \"320-410\" or a single line \"47\". Required so the operator can audit your summary by opening the original file.\n- `superseded_by` \u2014 when an accepted decision in the supplied \"Currently-accepted decisions\" list directly relates to the historical claim, set the DEC-NNNN id. Otherwise set null. Do NOT invent decision ids.\n\n## When you should set `no_relevant_history: true`\n\nThe supplied files don't contain anything relevant to the operator's scope question. Better to short-circuit than to fabricate a summary. The cairn returns an empty claims array with a one-line caveat.\n\n## When you should set `summary_caveat`\n\nAnything important about the input that affects how the agent should treat your output:\n- \"Summary covers 8 files; 3 additional matches were truncated.\"\n- \"All claims are from a single bucket dated 2026-04-23; nothing more recent in scope.\"\n\n## What you must NOT do\n\n- Do NOT issue a recommendation. Your output is descriptive (what was said), not prescriptive (what to do).\n- Do NOT phrase claims as if they are current truth. Always past-tense + cited.\n- Do NOT invent paths, line ranges, decision ids, or dates. If you can't find a value, set what's required by schema and skip the claim.\n- Do NOT emit a free-form preamble before the JSON.\n- Do NOT emit fields not in the schema.\n\nOutput ONLY the JSON object.";
+export interface BuildHistoryUserPromptArgs {
+    /** Operator's free-text scope description. */
+    scope: string;
+    /** Repo-relative pathHint glob, when provided. */
+    pathHint?: string;
+    since?: string;
+    until?: string;
+    files: ArchiveFile[];
+    /** Optional ledger of currently-accepted decisions for supersedes inference. */
+    acceptedDecisions: {
+        id: string;
+        title: string;
+        scope_globs?: string[];
+    }[];
+}
+export declare function buildHistorySummarizerUserPrompt(args: BuildHistoryUserPromptArgs): string;

package/dist/mcp/history/prompt.js

@@ -0,0 +1,99 @@
+/**
+ * Tier-1 (Haiku) summarizer prompts for cairn_query_history.
+ *
+ * Constraint: the LLM emits ONLY structured claims; raw historical
+ * content never reaches the agent's context. Each claim cites a
+ * concrete source_path + source_lines so the operator (and any future
+ * audit) can verify the summary against the original.
+ *
+ * The prompt id + version are committed in source so a behavior change
+ * here is a versioned change in the source tree, not a silent runtime
+ * update.
+ */
+export const CAIRN_HISTORY_SUMMARIZE_PROMPT_ID = "cairn.history_summarize.v1";
+export const CAIRN_HISTORY_SUMMARIZE_VERSION = "v1";
+export const HISTORY_SUMMARIZER_SYSTEM_PROMPT = `You are the **history summarizer** for an agent cairn's two-zone read separation. The agent calling you cannot read .archive/ files directly — by design. You read those files on its behalf and emit a structured response with cited claims. Only your structured response reaches the agent's context.
+
+Your job: read N historical files and the operator's scope question. Produce per-claim records that capture what the historical files said, with full citation, dates, and supersedes-tags pointing at currently-canonical decisions when they exist.
+
+## Hard contract
+
+Every claim you emit MUST include:
+
+- \`claim\` — one-sentence factual statement of what the historical content said. Past-tense. Imperative voice avoided. Example: "The project considered using a JSONB expression index on commandPayload->>'userId' for dashboard queries." NOT "The project should use a JSONB index" — that is current-tense and reads as canon.
+- \`as_of\` — ISO date when the source content was authored / valid. Use the file's frontmatter \`generated\` or \`verified-at\`, the bucket date in the path (\`.archive/2026-05-pre-cairn/\`), or the most explicit date you can find in the body. If genuinely unknown, set the bucket date.
+- \`source_path\` — the repo-relative path EXACTLY as given in the file headers. Do not invent a path or a hash.
+- \`source_lines\` — line range like "320-410" or a single line "47". Required so the operator can audit your summary by opening the original file.
+- \`superseded_by\` — when an accepted decision in the supplied "Currently-accepted decisions" list directly relates to the historical claim, set the DEC-NNNN id. Otherwise set null. Do NOT invent decision ids.
+
+## When you should set \`no_relevant_history: true\`
+
+The supplied files don't contain anything relevant to the operator's scope question. Better to short-circuit than to fabricate a summary. The cairn returns an empty claims array with a one-line caveat.
+
+## When you should set \`summary_caveat\`
+
+Anything important about the input that affects how the agent should treat your output:
+- "Summary covers 8 files; 3 additional matches were truncated."
+- "All claims are from a single bucket dated 2026-04-23; nothing more recent in scope."
+
+## What you must NOT do
+
+- Do NOT issue a recommendation. Your output is descriptive (what was said), not prescriptive (what to do).
+- Do NOT phrase claims as if they are current truth. Always past-tense + cited.
+- Do NOT invent paths, line ranges, decision ids, or dates. If you can't find a value, set what's required by schema and skip the claim.
+- Do NOT emit a free-form preamble before the JSON.
+- Do NOT emit fields not in the schema.
+
+Output ONLY the JSON object.`;
+const PER_FILE_HEADER_PREVIEW_LINES = 800;
+export function buildHistorySummarizerUserPrompt(args) {
+    const sections = [];
+    sections.push("## Operator scope question");
+    sections.push(args.scope.trim());
+    sections.push("");
+    sections.push("## Filters applied to the .archive/ walk");
+    sections.push(`path_hint: ${args.pathHint ?? "(none — full archive)"}`);
+    sections.push(`since: ${args.since ?? "(none — beginning of time)"}`);
+    sections.push(`until: ${args.until ?? "(none — present)"}`);
+    sections.push(`matched_files: ${args.files.length}`);
+    if (args.acceptedDecisions.length > 0) {
+        sections.push("");
+        sections.push("## Currently-accepted decisions (for supersedes inference)");
+        sections.push("Each line: `<DEC-id> — <title>  (scope: <globs>)`. If a historical claim directly contradicts or has been replaced by one of these, cite the id in `superseded_by`. Otherwise set null. Do NOT invent ids.");
+        sections.push("");
+        for (const d of args.acceptedDecisions.slice(0, 30)) {
+            const scope = d.scope_globs && d.scope_globs.length > 0 ? d.scope_globs.join(", ") : "(no scope)";
+            sections.push(`- **${d.id}** — ${d.title}  (scope: ${scope})`);
+        }
+        if (args.acceptedDecisions.length > 30) {
+            sections.push(`…(${args.acceptedDecisions.length - 30} additional accepted decisions omitted)`);
+        }
+    }
+    sections.push("");
+    sections.push("## Historical files (line-numbered)");
+    if (args.files.length === 0) {
+        sections.push("(none — return `no_relevant_history: true`)");
+    }
+    for (const f of args.files) {
+        sections.push("");
+        sections.push(`### ${f.relPath}  (bucket: ${f.bucket}, archive_date: ${f.archiveDate}${f.truncated ? ", TRUNCATED" : ""})`);
+        sections.push("```");
+        sections.push(numberLines(f.content, PER_FILE_HEADER_PREVIEW_LINES));
+        sections.push("```");
+    }
+    sections.push("");
+    sections.push("## Your task");
+    sections.push("Emit the JSON object per the schema. Cite source_path EXACTLY as the headers above show. Output ONLY the JSON object.");
+    return sections.join("\n");
+}
+function numberLines(text, maxLines) {
+    const lines = text.split(/\r?\n/);
+    const truncated = lines.length > maxLines;
+    const slice = truncated ? lines.slice(0, maxLines) : lines;
+    const padWidth = String(slice.length).length;
+    const out = slice.map((line, i) => `${String(i + 1).padStart(padWidth, " ")}  ${line}`);
+    if (truncated)
+        out.push(`…[${lines.length - maxLines} more lines elided]`);
+    return out.join("\n");
+}
+//# sourceMappingURL=prompt.js.map

package/dist/mcp/history/prompt.js.map

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

package/dist/mcp/history/schema.d.ts

@@ -0,0 +1,58 @@
+/**
+ * JSON Schema enforced by `claude --json-schema` for the history
+ * summarizer Tier-1 call.
+ *
+ * Per MCP_SURFACE.md §"cairn_query_history": every claim MUST carry
+ * source_path, source_lines, as_of, and a supersedes-tag (string DEC-id
+ * or null). The cairn post-resolves currently_canonical_pointer from
+ * the decisions ledger after the LLM returns — keeps the LLM's
+ * responsibilities tight (cite + summarize) and makes the canonical
+ * cross-reference mechanical.
+ */
+export declare const HISTORY_SUMMARIZER_OUTPUT_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly claims: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly claim: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly as_of: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly source_path: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly source_lines: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly superseded_by: {
+                        readonly anyOf: readonly [{
+                            readonly type: "string";
+                            readonly pattern: "^DEC-\\d{4,}$";
+                        }, {
+                            readonly type: "null";
+                        }];
+                    };
+                };
+                readonly required: readonly ["claim", "as_of", "source_path", "source_lines"];
+            };
+        };
+        readonly summary_caveat: {
+            readonly type: "string";
+        };
+        readonly no_relevant_history: {
+            readonly type: "boolean";
+        };
+    };
+    readonly required: readonly ["claims"];
+};