@cairnkeep/cli 2.3.1 → 2.5.0

package/mcp-memory-server/dist/node-store.js

@@ -0,0 +1,455 @@
+import { createHash, randomUUID } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AgentFS } from "agentfs-sdk";
+import { NODE_SCHEMA_VERSION, memoryImportEnvelopeSchema, nodeMetadataSchema, } from "./node-schema.js";
+const METADATA_TABLE = "cairn_node_metadata_v1";
+const REPLAY_TABLE = "cairn_node_import_replays_v1";
+const HISTORY_NAMESPACE = "__history__";
+const REVIEWED_NAMESPACE = "__reviewed__";
+const DEFAULT_METADATA = { schema_version: NODE_SCHEMA_VERSION, node_type: "memory", tags: [] };
+let lastMutationTime = 0;
+function mutationTimestamp() {
+    const now = Date.now();
+    lastMutationTime = Math.max(now, lastMutationTime + 1);
+    return new Date(lastMutationTime).toISOString();
+}
+function normalizeValue(value) {
+    if (typeof value === "string")
+        return value;
+    if (value === undefined || value === null)
+        return "";
+    return JSON.stringify(value);
+}
+function normalizedMetadata(nodeType = "memory", tags = []) {
+    return nodeMetadataSchema.parse({ schema_version: NODE_SCHEMA_VERSION, node_type: nodeType, tags });
+}
+function historyPrefix(key) {
+    return `${HISTORY_NAMESPACE}/${key}/`;
+}
+function historyKey(key, at) {
+    return `${historyPrefix(key)}${at}-${randomUUID()}`;
+}
+function injectMutationFailure(stage) {
+    if (process.env.CAIRN_TEST_FAIL_NODE_MUTATION === stage)
+        throw new Error(`Injected node mutation failure at ${stage}.`);
+}
+async function tableExists(agent, table) {
+    const row = await agent.getDatabase().prepare("SELECT name FROM sqlite_master WHERE type = ? AND name = ?").get("table", table);
+    return row?.name === table;
+}
+async function ensureTables(agent) {
+    await agent.getDatabase().exec(`
+        CREATE TABLE IF NOT EXISTS ${METADATA_TABLE} (
+            key TEXT PRIMARY KEY,
+            schema_version INTEGER NOT NULL,
+            node_type TEXT NOT NULL,
+            tags_json TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS ${REPLAY_TABLE} (
+            import_id TEXT PRIMARY KEY,
+            batch_digest TEXT NOT NULL,
+            committed_at TEXT NOT NULL
+        );
+    `);
+}
+async function storedMetadata(agent, key) {
+    if (!await tableExists(agent, METADATA_TABLE))
+        return undefined;
+    const row = await agent.getDatabase().prepare(`SELECT schema_version, node_type, tags_json FROM ${METADATA_TABLE} WHERE key = ?`).get(key);
+    if (!row)
+        return undefined;
+    return nodeMetadataSchema.parse({
+        schema_version: Number(row.schema_version),
+        node_type: row.node_type,
+        tags: JSON.parse(String(row.tags_json)),
+    });
+}
+async function setMetadata(agent, key, metadata, at) {
+    await agent.getDatabase().prepare(`
+        INSERT INTO ${METADATA_TABLE}(key, schema_version, node_type, tags_json, updated_at)
+        VALUES (?, ?, ?, ?, ?)
+        ON CONFLICT(key) DO UPDATE SET
+            schema_version = excluded.schema_version,
+            node_type = excluded.node_type,
+            tags_json = excluded.tags_json,
+            updated_at = excluded.updated_at
+    `).run(key, metadata.schema_version, metadata.node_type, JSON.stringify(metadata.tags), at);
+}
+export async function inImmediateNodeTransaction(agent, operation) {
+    const transaction = agent.getDatabase().transaction(operation);
+    const immediate = transaction.immediate;
+    return immediate();
+}
+export async function getNodeMetadata(agent, key) {
+    return await storedMetadata(agent, key) ?? { ...DEFAULT_METADATA, tags: [] };
+}
+export async function attachNodeMetadata(agent, scope, entry) {
+    const metadata = await getNodeMetadata(agent, entry.key);
+    return {
+        schema_version: NODE_SCHEMA_VERSION,
+        address_space: "memory",
+        scope,
+        key: entry.key,
+        value: normalizeValue(entry.value),
+        node_type: metadata.node_type,
+        tags: metadata.tags,
+    };
+}
+export async function getTypedNode(agent, scope, key) {
+    const value = await agent.kv.get(key);
+    return value === undefined ? null : attachNodeMetadata(agent, scope, { key, value });
+}
+export async function createTypedNode(options) {
+    const metadata = normalizedMetadata(options.node_type, options.tags);
+    return inImmediateNodeTransaction(options.agent, async () => {
+        await ensureTables(options.agent);
+        const current = await options.agent.kv.get(options.key);
+        if (current !== undefined) {
+            const currentNode = await attachNodeMetadata(options.agent, options.scope, { key: options.key, value: current });
+            if (currentNode.value === options.value && currentNode.node_type === metadata.node_type && JSON.stringify(currentNode.tags) === JSON.stringify(metadata.tags)) {
+                return { ok: true, scope: options.scope, key: options.key, created: false, snapshot_key: null };
+            }
+            throw new Error(`NODE_EXISTS: ${options.key} differs; use memory_supersede.`);
+        }
+        const at = mutationTimestamp();
+        await options.agent.kv.set(options.key, options.value);
+        injectMutationFailure("after-value");
+        await setMetadata(options.agent, options.key, metadata, at);
+        return { ok: true, scope: options.scope, key: options.key, created: true, snapshot_key: null };
+    });
+}
+async function supersedeTypedNodeMutation(options) {
+    await ensureTables(options.agent);
+    const current = await options.agent.kv.get(options.key);
+    if (current === undefined) {
+        const metadata = normalizedMetadata(options.node_type, options.tags);
+        const value = options.value ?? "";
+        const at = mutationTimestamp();
+        await options.agent.kv.set(options.key, value);
+        injectMutationFailure("after-value");
+        await setMetadata(options.agent, options.key, metadata, at);
+        return { ok: true, scope: options.scope, key: options.key, created: true, snapshot_key: null };
+    }
+    const previous = await attachNodeMetadata(options.agent, options.scope, { key: options.key, value: current });
+    const metadata = normalizedMetadata(options.node_type ?? previous.node_type, options.tags ?? previous.tags);
+    const value = options.value ?? previous.value;
+    const at = mutationTimestamp();
+    const snapshot = {
+        schema_version: NODE_SCHEMA_VERSION,
+        event: "supersede",
+        value: previous.value,
+        node_type: previous.node_type,
+        tags: previous.tags,
+        at,
+        reason: options.reason ?? null,
+    };
+    const snapshot_key = historyKey(options.key, at);
+    await options.agent.kv.set(snapshot_key, snapshot);
+    await options.agent.kv.set(options.key, value);
+    injectMutationFailure("after-value");
+    await setMetadata(options.agent, options.key, metadata, at);
+    return { ok: true, scope: options.scope, key: options.key, created: false, snapshot_key, previous_value: previous.value };
+}
+export async function supersedeTypedNode(options) {
+    return inImmediateNodeTransaction(options.agent, () => supersedeTypedNodeMutation(options));
+}
+async function deleteTypedNodeMutation(options) {
+    await ensureTables(options.agent);
+    const current = await options.agent.kv.get(options.key);
+    if (current === undefined)
+        return { ok: true, scope: options.scope, key: options.key, deleted: false, missing: true, snapshot_key: null };
+    const node = await attachNodeMetadata(options.agent, options.scope, { key: options.key, value: current });
+    const at = mutationTimestamp();
+    const snapshot = {
+        schema_version: NODE_SCHEMA_VERSION,
+        event: "delete",
+        value: node.value,
+        node_type: node.node_type,
+        tags: node.tags,
+        at,
+        reason: options.reason ?? null,
+    };
+    const snapshot_key = historyKey(options.key, at);
+    await options.agent.kv.set(snapshot_key, snapshot);
+    await options.agent.kv.delete(options.key);
+    injectMutationFailure("after-value");
+    await options.agent.getDatabase().prepare(`DELETE FROM ${METADATA_TABLE} WHERE key = ?`).run(options.key);
+    return { ok: true, scope: options.scope, key: options.key, deleted: true, missing: false, snapshot_key, final_snapshot: snapshot };
+}
+export async function deleteTypedNode(options) {
+    return inImmediateNodeTransaction(options.agent, () => deleteTypedNodeMutation(options));
+}
+export async function listTypedHistory(agent, key) {
+    const entries = await agent.kv.list(historyPrefix(key));
+    return entries.map((entry) => {
+        const value = entry.value;
+        if (value?.schema_version === NODE_SCHEMA_VERSION && (value.event === "supersede" || value.event === "delete")) {
+            return { key: entry.key, ...value };
+        }
+        return {
+            key: entry.key,
+            schema_version: NODE_SCHEMA_VERSION,
+            event: "supersede",
+            value: normalizeValue(value?.value ?? entry.value),
+            node_type: "memory",
+            tags: [],
+            at: String(value?.superseded_at ?? ""),
+            reason: value?.superseded_reason ?? null,
+        };
+    }).sort((left, right) => left.key.localeCompare(right.key));
+}
+export async function applyReviewedTypedNode(options) {
+    const mutation = { ...options, reason: `reviewed memory ${options.review_id}` };
+    return options.in_transaction ? supersedeTypedNodeMutation(mutation) : supersedeTypedNode(mutation);
+}
+export async function invalidateReviewedTypedNode(options) {
+    const mutation = { ...options, reason: options.reason ?? `reviewed memory ${options.review_id} invalidated` };
+    return options.in_transaction ? deleteTypedNodeMutation(mutation) : deleteTypedNode(mutation);
+}
+function canonicalBatch(envelope) {
+    return JSON.stringify({
+        schema_version: envelope.schema_version,
+        scope: envelope.scope,
+        address_space: envelope.address_space,
+        nodes: envelope.nodes.map((node) => ({
+            key: node.key,
+            value: node.value,
+            node_type: node.node_type,
+            tags: node.tags,
+            ...(node.note ? { note: node.note } : {}),
+        })).sort((left, right) => left.key.localeCompare(right.key)),
+    });
+}
+function batchDigest(envelope) {
+    return createHash("sha256").update("cairnkeep:memory-import:v1\0").update(canonicalBatch(envelope)).digest("hex");
+}
+async function classifyImportNode(agent, scope, node, policy) {
+    if (!agent)
+        return { key: node.key, action: "would_create" };
+    const current = await getTypedNode(agent, scope, node.key);
+    if (!current)
+        return { key: node.key, action: "would_create" };
+    const same = current.value === node.value && current.node_type === node.node_type && JSON.stringify(current.tags) === JSON.stringify(node.tags);
+    if (same)
+        return { key: node.key, action: "unchanged" };
+    return policy === "supersede"
+        ? { key: node.key, action: "would_replace" }
+        : { key: node.key, action: "rejected", code: "CONFLICT" };
+}
+export async function planMemoryImport(agent, input) {
+    const envelope = memoryImportEnvelopeSchema.parse(input);
+    if (envelope.address_space !== "memory")
+        throw new Error("ADDRESS_SPACE_UNSUPPORTED: node-store accepts memory imports only.");
+    const actions = [];
+    for (const node of [...envelope.nodes].sort((left, right) => left.key.localeCompare(right.key))) {
+        actions.push(await classifyImportNode(agent, envelope.scope, node, envelope.conflict_policy));
+    }
+    return { envelope, batch_digest: batchDigest(envelope), actions, conflict: actions.some((action) => action.action === "rejected") };
+}
+function counts(actions, dryRun) {
+    const result = { unchanged: 0, rejected: 0 };
+    if (dryRun) {
+        result.would_create = 0;
+        result.would_replace = 0;
+    }
+    else {
+        result.created = 0;
+        result.replaced = 0;
+    }
+    for (const action of actions) {
+        if (action.action === "would_create")
+            result.would_create = (result.would_create ?? 0) + 1;
+        else if (action.action === "would_replace")
+            result.would_replace = (result.would_replace ?? 0) + 1;
+        else if (action.action === "created")
+            result.created = (result.created ?? 0) + 1;
+        else if (action.action === "replaced")
+            result.replaced = (result.replaced ?? 0) + 1;
+        else if (action.action === "unchanged")
+            result.unchanged += 1;
+        else
+            result.rejected += 1;
+    }
+    return result;
+}
+export async function commitMemoryImport(agent, inputPlan) {
+    if (inputPlan.envelope.dry_run) {
+        return {
+            schema_version: NODE_SCHEMA_VERSION,
+            scope: inputPlan.envelope.scope,
+            address_space: inputPlan.envelope.address_space,
+            batch_digest: inputPlan.batch_digest,
+            ...(inputPlan.envelope.import_id ? { import_id: inputPlan.envelope.import_id } : {}),
+            dry_run: true,
+            conflict_policy: inputPlan.envelope.conflict_policy,
+            committed: false,
+            counts: counts(inputPlan.actions, true),
+            actions: inputPlan.actions,
+        };
+    }
+    if (!agent)
+        throw new Error("STORE_REQUIRED: a concrete AgentFS store is required for import commit.");
+    return inImmediateNodeTransaction(agent, async () => {
+        await ensureTables(agent);
+        const { envelope, batch_digest } = inputPlan;
+        if (envelope.import_id) {
+            const replay = await agent.getDatabase().prepare(`SELECT batch_digest FROM ${REPLAY_TABLE} WHERE import_id = ?`).get(envelope.import_id);
+            if (replay && replay.batch_digest !== batch_digest)
+                throw new Error(`IMPORT_ID_REUSE: ${envelope.import_id}`);
+            if (replay) {
+                const actions = envelope.nodes.map((node) => ({ key: node.key, action: "unchanged" })).sort((a, b) => a.key.localeCompare(b.key));
+                return {
+                    schema_version: NODE_SCHEMA_VERSION,
+                    scope: envelope.scope,
+                    address_space: envelope.address_space,
+                    batch_digest,
+                    import_id: envelope.import_id,
+                    dry_run: false,
+                    conflict_policy: envelope.conflict_policy,
+                    committed: true,
+                    replayed: true,
+                    counts: counts(actions, false),
+                    actions,
+                };
+            }
+        }
+        const currentPlan = await planMemoryImport(agent, envelope);
+        if (currentPlan.conflict)
+            throw new Error("CONFLICT: import contains a differing live node.");
+        const committedActions = [];
+        let mutations = 0;
+        for (const planned of currentPlan.actions) {
+            const node = envelope.nodes.find((candidate) => candidate.key === planned.key);
+            if (planned.action === "unchanged") {
+                committedActions.push(planned);
+                continue;
+            }
+            const existing = await getTypedNode(agent, envelope.scope, node.key);
+            if (existing) {
+                const at = mutationTimestamp();
+                const snapshot = { schema_version: 1, event: "supersede", value: existing.value, node_type: existing.node_type, tags: existing.tags, at, reason: `import ${envelope.import_id ?? batch_digest}` };
+                await agent.kv.set(historyKey(node.key, at), snapshot);
+                await agent.kv.set(node.key, node.value);
+                await setMetadata(agent, node.key, normalizedMetadata(node.node_type, node.tags), at);
+                committedActions.push({ key: node.key, action: "replaced" });
+            }
+            else {
+                const at = mutationTimestamp();
+                await agent.kv.set(node.key, node.value);
+                await setMetadata(agent, node.key, normalizedMetadata(node.node_type, node.tags), at);
+                committedActions.push({ key: node.key, action: "created" });
+            }
+            mutations += 1;
+            if (Number(process.env.CAIRN_TEST_FAIL_IMPORT_AFTER) === mutations)
+                throw new Error("Injected import failure.");
+        }
+        if (envelope.import_id) {
+            await agent.getDatabase().prepare(`INSERT INTO ${REPLAY_TABLE}(import_id, batch_digest, committed_at) VALUES (?, ?, ?)`).run(envelope.import_id, batch_digest, new Date().toISOString());
+        }
+        committedActions.sort((left, right) => left.key.localeCompare(right.key));
+        return {
+            schema_version: NODE_SCHEMA_VERSION,
+            scope: envelope.scope,
+            address_space: envelope.address_space,
+            batch_digest,
+            ...(envelope.import_id ? { import_id: envelope.import_id } : {}),
+            dry_run: false,
+            conflict_policy: envelope.conflict_policy,
+            committed: true,
+            counts: counts(committedActions, false),
+            actions: committedActions,
+        };
+    });
+}
+export async function doctorTypedNodeStore(options) {
+    const dbPath = join(options.baseDir, `${options.scope}.db`);
+    if (!existsSync(dbPath))
+        return { schema_version: 1, exists: false, ok: true, repaired: false, issues: [] };
+    // AgentFS opens databases in read-write WAL mode, which can checkpoint the
+    // WAL even when the caller only reads. Inspect an exact disposable copy so
+    // a non-repair doctor run is byte-pure for the authoritative store.
+    const scratch = mkdtempSync(join(tmpdir(), "cairn-node-doctor-"));
+    const scratchPath = join(scratch, `${options.scope}.db`);
+    for (const suffix of ["", "-wal", "-shm"]) {
+        if (existsSync(`${dbPath}${suffix}`))
+            copyFileSync(`${dbPath}${suffix}`, `${scratchPath}${suffix}`);
+    }
+    const inspectionAgent = await AgentFS.open({ id: options.scope, path: scratchPath });
+    const issues = [];
+    const orphanKeys = [];
+    try {
+        if (await tableExists(inspectionAgent, METADATA_TABLE)) {
+            const rows = await inspectionAgent.getDatabase().prepare(`SELECT key, schema_version, node_type, tags_json FROM ${METADATA_TABLE} ORDER BY key`).all();
+            for (const row of rows) {
+                try {
+                    nodeMetadataSchema.parse({ schema_version: Number(row.schema_version), node_type: row.node_type, tags: JSON.parse(String(row.tags_json)) });
+                }
+                catch {
+                    issues.push(`Invalid authoritative metadata for ${String(row.key)}.`);
+                    continue;
+                }
+                if (await inspectionAgent.kv.get(String(row.key)) === undefined) {
+                    issues.push(`Orphan metadata for ${String(row.key)}.`);
+                    orphanKeys.push(String(row.key));
+                }
+            }
+        }
+        if (await tableExists(inspectionAgent, REPLAY_TABLE)) {
+            const rows = await inspectionAgent.getDatabase().prepare(`SELECT import_id, batch_digest FROM ${REPLAY_TABLE} ORDER BY import_id`).all();
+            for (const row of rows) {
+                if (!/^[a-f0-9]{64}$/.test(String(row.batch_digest)))
+                    issues.push(`Invalid authoritative replay digest for ${String(row.import_id)}.`);
+            }
+        }
+    }
+    finally {
+        await inspectionAgent.close();
+        rmSync(scratch, { recursive: true, force: true });
+    }
+    const onlyOrphans = issues.length > 0 && issues.every((issue) => issue.startsWith("Orphan metadata"));
+    if (options.repair && onlyOrphans) {
+        const agent = await AgentFS.open({ id: options.scope, path: dbPath });
+        try {
+            await inImmediateNodeTransaction(agent, async () => {
+                for (const key of orphanKeys)
+                    await agent.getDatabase().prepare(`DELETE FROM ${METADATA_TABLE} WHERE key = ?`).run(key);
+            });
+        }
+        finally {
+            await agent.close();
+        }
+        return { schema_version: 1, exists: true, ok: true, repaired: true, issues: [] };
+    }
+    return { schema_version: 1, exists: true, ok: issues.length === 0, repaired: false, issues };
+}
+export const doctorNodeStore = doctorTypedNodeStore;
+export async function createNodeDoctorFixture(options) {
+    mkdirSync(options.root, { recursive: true });
+    const agent = await AgentFS.open({ id: "identity", path: join(options.root, "identity.db") });
+    try {
+        await ensureTables(agent);
+        if (options.kind !== "orphan_metadata")
+            await agent.kv.set("knowledge/doctor", "doctor fixture");
+        if (options.kind === "malformed_type") {
+            await agent.getDatabase().prepare(`INSERT INTO ${METADATA_TABLE}(key,schema_version,node_type,tags_json,updated_at) VALUES (?,?,?,?,?)`).run("knowledge/doctor", 1, "invalid", "[]", new Date().toISOString());
+        }
+        else if (options.kind === "malformed_tags") {
+            await agent.getDatabase().prepare(`INSERT INTO ${METADATA_TABLE}(key,schema_version,node_type,tags_json,updated_at) VALUES (?,?,?,?,?)`).run("knowledge/doctor", 1, "knowledge", "not-json", new Date().toISOString());
+        }
+        else if (options.kind === "orphan_metadata") {
+            await agent.getDatabase().prepare(`INSERT INTO ${METADATA_TABLE}(key,schema_version,node_type,tags_json,updated_at) VALUES (?,?,?,?,?)`).run("knowledge/orphan", 1, "knowledge", "[]", new Date().toISOString());
+        }
+        else {
+            await agent.getDatabase().prepare(`INSERT INTO ${REPLAY_TABLE}(import_id,batch_digest,committed_at) VALUES (?,?,?)`).run("doctor-replay", "invalid", new Date().toISOString());
+        }
+    }
+    finally {
+        await agent.close();
+    }
+    return { root: options.root };
+}
+export const INTERNAL_NODE_TABLES = { metadata: METADATA_TABLE, replays: REPLAY_TABLE };
+export const INTERNAL_NODE_NAMESPACES = { history: HISTORY_NAMESPACE, reviewed: REVIEWED_NAMESPACE };

package/mcp-memory-server/dist/note-cli.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+import { readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { startOperatingCapability, withCapability } from "./capability-adapter.js";
+import { isCapabilityContractEnabled, resolveCapabilityStatus } from "./capability-config.js";
+import { distillProject } from "./note-distiller.js";
+import { isNoteDistillationEnabled } from "./note-schema.js";
+import { doctorNoteStore, promoteNotes, searchHindsight } from "./note-store.js";
+process.stdout.on("error", (error) => {
+    if (error.code === "EPIPE")
+        process.exit(0);
+    throw error;
+});
+function usage() {
+    return `cairn notes — deterministic local hindsight notes
+
+Usage:
+  cairn notes distill [--project PATH] [--session ID] [--json]
+  cairn notes distill --all-projects --para-root PATH [--json]
+  cairn notes search-error [--text TEXT] [--project PATH] [--component VALUE] [--json]
+  cairn notes promote NOTE-ID --with NOTE-ID --confirm [--json]
+  cairn notes doctor [--repair] [--json]
+`;
+}
+function valueAfter(args, flag) {
+    const index = args.indexOf(flag);
+    if (index < 0)
+        return undefined;
+    const value = args[index + 1];
+    if (!value || value.startsWith("--"))
+        throw new Error(`${flag} requires a value.`);
+    return value;
+}
+function assertKnown(args, flags, positionals = 0) {
+    const valueFlags = new Set(["--project", "--session", "--para-root", "--text", "--component", "--with"]);
+    let positionalCount = 0;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg.startsWith("--")) {
+            if (!flags.includes(arg))
+                throw new Error(`unknown option "${arg}".`);
+            if (valueFlags.has(arg))
+                index += 1;
+        }
+        else
+            positionalCount += 1;
+    }
+    if (positionalCount !== positionals)
+        throw new Error(`expected ${positionals} positional argument(s).`);
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+function findTrajectoryProjects(root) {
+    const projects = [];
+    const walk = (directory, depth) => {
+        if (depth > 8)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.isSymbolicLink())
+                continue;
+            const child = join(directory, entry.name);
+            if (entry.name === ".agentfs") {
+                try {
+                    if (statSync(join(child, "trajectory.db")).isFile())
+                        projects.push(directory);
+                }
+                catch { /* no trajectory store */ }
+                continue;
+            }
+            if (entry.name.startsWith(".") || ["node_modules", "vendor"].includes(entry.name))
+                continue;
+            walk(child, depth + 1);
+        }
+    };
+    walk(resolve(root), 0);
+    return [...new Set(projects.map((project) => resolve(project)))].sort();
+}
+function disabled(json) {
+    const value = { schema_version: 1, enabled: false, reason: "CAIRN_NOTE_DISTILLATION is disabled" };
+    process.stdout.write(`${json ? JSON.stringify(value) : value.reason}\n`);
+}
+function output(value, json, human) {
+    process.stdout.write(`${json ? JSON.stringify(value) : human}\n`);
+}
+function validCorrelationId(value) {
+    return value !== undefined
+        && value !== "unknown"
+        && /^(?:cairn:)?[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/.test(value)
+        ? value
+        : undefined;
+}
+async function withEnabledCompatibility(callback) {
+    if (isNoteDistillationEnabled())
+        return callback();
+    const previous = process.env.CAIRN_NOTE_DISTILLATION;
+    process.env.CAIRN_NOTE_DISTILLATION = "1";
+    try {
+        return await callback();
+    }
+    finally {
+        if (previous === undefined)
+            delete process.env.CAIRN_NOTE_DISTILLATION;
+        else
+            process.env.CAIRN_NOTE_DISTILLATION = previous;
+    }
+}
+async function main() {
+    const [command = "help", ...args] = process.argv.slice(2);
+    if (["help", "--help", "-h"].includes(command)) {
+        process.stdout.write(usage());
+        return;
+    }
+    const json = args.includes("--json");
+    const contractEnabled = isCapabilityContractEnabled();
+    if (!contractEnabled && !isNoteDistillationEnabled()) {
+        disabled(json);
+        return;
+    }
+    if (command === "distill") {
+        assertKnown(args, ["--project", "--session", "--all-projects", "--para-root", "--json"]);
+        const allProjects = args.includes("--all-projects");
+        const project = valueAfter(args, "--project");
+        const sessionId = valueAfter(args, "--session");
+        const paraRoot = valueAfter(args, "--para-root");
+        if (allProjects && (!paraRoot || project || sessionId)) {
+            throw new Error("--all-projects requires --para-root and cannot be combined with --project or --session.");
+        }
+        if (!allProjects && paraRoot)
+            throw new Error("--para-root is valid only with --all-projects.");
+        const capabilityProjectRoot = resolve(project ?? process.cwd());
+        const correlationId = validCorrelationId(sessionId);
+        const snapshot = contractEnabled
+            ? await resolveCapabilityStatus({ projectRoot: capabilityProjectRoot })
+            : undefined;
+        const capabilityOptions = snapshot === undefined ? undefined : {
+            projectRoot: capabilityProjectRoot,
+            snapshot,
+            capabilityId: "notes.distill",
+            classification: {
+                harness: "other",
+                source: "notes-cli",
+                transport: "local-process",
+            },
+            ...(correlationId === undefined ? {} : { correlationId }),
+        };
+        const capability = snapshot?.capabilities.find(({ id }) => id === "notes.distill");
+        if (contractEnabled && capability?.enabled !== true) {
+            if (capabilityOptions)
+                await startOperatingCapability(capabilityOptions);
+            disabled(json);
+            return;
+        }
+        if (allProjects) {
+            const run = async () => {
+                const projects = findTrajectoryProjects(paraRoot);
+                const results = [];
+                for (const projectRoot of projects) {
+                    try {
+                        results.push(await distillProject({ projectRoot }));
+                    }
+                    catch (error) {
+                        results.push({
+                            schema_version: 1,
+                            enabled: true,
+                            project_root: projectRoot,
+                            created: [], updated: [], already_processed: [], enrichment_skipped: [], enrichment_failed: [],
+                            failed: [{ session_id: "*", error: error instanceof Error ? error.message : String(error) }],
+                        });
+                    }
+                }
+                return { schema_version: 1, enabled: true, projects_scanned: projects.length, results };
+            };
+            const execute = () => contractEnabled ? withEnabledCompatibility(run) : run();
+            const value = await (capabilityOptions ? withCapability(capabilityOptions, execute)() : execute());
+            output(value, json, `Scanned ${value.projects_scanned} project(s).`);
+            return;
+        }
+        const distill = () => distillProject({ projectRoot: capabilityProjectRoot, ...(sessionId ? { sessionId } : {}) });
+        const run = () => contractEnabled ? withEnabledCompatibility(distill) : distill();
+        const value = await (capabilityOptions ? withCapability(capabilityOptions, run)() : run());
+        output(value, json, `Created ${value.created.length}, updated ${value.updated.length}, already processed ${value.already_processed.length}.`);
+        return;
+    }
+    if (!isNoteDistillationEnabled()) {
+        disabled(json);
+        return;
+    }
+    if (command === "search-error") {
+        assertKnown(args, ["--project", "--text", "--component", "--json"]);
+        const text = valueAfter(args, "--text") ?? await readStdin();
+        if (!text.trim())
+            throw new Error("search-error requires --text or error text on stdin.");
+        const projectRoot = resolve(valueAfter(args, "--project") ?? process.cwd());
+        const value = await searchHindsight({ projectRoot, text, component: valueAfter(args, "--component") });
+        output(value, json, value.results.length > 0 ? value.results.map((item) => `${item.status ?? "note"}\t${item.id}\t${item.path}`).join("\n") : "No exact hindsight match found.");
+        return;
+    }
+    if (command === "promote") {
+        assertKnown(args, ["--with", "--confirm", "--json"], 1);
+        const source = args.find((arg) => !arg.startsWith("--") && args[args.indexOf(arg) - 1] !== "--with");
+        const corroborating = valueAfter(args, "--with");
+        if (!source || !corroborating)
+            throw new Error("promote requires NOTE-ID --with NOTE-ID.");
+        const value = await promoteNotes({ sourceNoteId: source, corroboratingNoteId: corroborating, confirm: args.includes("--confirm") });
+        output(value, json, `Promoted ${source} and ${corroborating} to ${value.shared_id}.`);
+        return;
+    }
+    if (command === "doctor") {
+        assertKnown(args, ["--repair", "--json"]);
+        const value = doctorNoteStore(args.includes("--repair"));
+        output(value, json, value.ok ? "Note store is healthy." : value.issues.join("\n"));
+        if (!value.ok)
+            process.exitCode = 2;
+        return;
+    }
+    throw new Error(`unknown notes command "${command}".`);
+}
+try {
+    await main();
+}
+catch (error) {
+    process.stderr.write(`cairn notes: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 2;
+}