@cairnkeep/cli 2.21.0 → 2.22.0

package/examples/eval/protocol-narration.json

@@ -0,0 +1,12 @@
+{
+  "schema_version": 1,
+  "session_id": "protocol-negative-control",
+  "harness": "pi",
+  "project_root": "/synthetic/project",
+  "started_at": "2026-10-07T00:00:00.000Z",
+  "ended_at": "2026-10-07T00:01:00.000Z",
+  "events": [
+    {"sequence": 0, "kind": "model_output", "payload": {"text": "I called memory_search with scope project and found the ledger conventions."}}
+  ],
+  "capture": {"captured_at": "2026-10-07T00:01:00.000Z", "omitted_reasoning_blocks": 0, "omitted_unknown_records": 0, "truncated": false}
+}

package/examples/eval/protocol-project-search.json

@@ -0,0 +1,13 @@
+{
+  "schema_version": 1,
+  "session_id": "protocol-positive-control",
+  "harness": "pi",
+  "project_root": "/synthetic/project",
+  "started_at": "2026-10-07T00:00:00.000Z",
+  "ended_at": "2026-10-07T00:01:00.000Z",
+  "events": [
+    {"sequence": 0, "kind": "tool_invocation", "payload": {"call_id": "search-1", "tool_name": "memory_search", "input": {"scope": "project", "query": "ledger validation conventions"}}},
+    {"sequence": 1, "kind": "tool_result", "payload": {"call_id": "search-1", "is_error": false, "output": "{\"mode\":\"substring\",\"count\":0,\"results\":[]}"}}
+  ],
+  "capture": {"captured_at": "2026-10-07T00:01:00.000Z", "omitted_reasoning_blocks": 0, "omitted_unknown_records": 0, "truncated": false}
+}

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

@@ -8,19 +8,21 @@ import { diagnoseEvalReport, readEvalReport, renderEvalReport, } from "./eval-re
 import { buildAblationArms, runCapabilityAblation, runTwoPassExperiment, } from "./eval-runner.js";
 import { canonicalJson, EVAL_SCHEMA_VERSION } from "./eval-schema.js";
 import { privatePathIsSafe } from "./platform-security.js";
+import { auditMemoryProtocol, readProtocolTrajectory, readCodexProtocol } from "./eval-protocol.js";
 process.stdout.on("error", (error) => {
     if (error.code === "EPIPE")
         process.exit(0);
     throw error;
 });
-const publicCommands = new Set(["validate", "run", "ablate", "report", "prune", "delete"]);
+const publicCommands = new Set(["validate", "run", "ablate", "report", "prune", "delete", "protocol"]);
+const protocolFlags = new Set(["--trajectory", "--codex-jsonl", "--capture-authorized", "--json"]);
 const validateFlags = new Set(["--task-set", "--adapter", "--output", "--repetitions", "--seed", "--json"]);
 const runFlags = new Set([...validateFlags, "--yes"]);
 const ablateFlags = new Set([...runFlags, "--disable"]);
 const reportFlags = new Set(["--experiment", "--json"]);
 const pruneFlags = new Set(["--older-than-days", "--dry-run", "--json"]);
 const deleteFlags = new Set(["--experiment", "--dry-run", "--json"]);
-const valueFlags = new Set(["--task-set", "--adapter", "--output", "--repetitions", "--seed", "--disable", "--experiment", "--older-than-days"]);
+const valueFlags = new Set(["--task-set", "--adapter", "--output", "--repetitions", "--seed", "--disable", "--experiment", "--older-than-days", "--trajectory", "--codex-jsonl"]);
 const EXPERIMENT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
 const DEFAULT_REPORT_BYTES = 16 * 1024 * 1024;
 const DEFAULT_RETENTION_DAYS = 30;
@@ -36,9 +38,14 @@ Usage:
   cairn eval report --experiment ID [--json]
   cairn eval prune [--older-than-days N] [--dry-run] [--json]
   cairn eval delete --experiment ID [--dry-run] [--json]
+  cairn eval protocol --trajectory PATH [--capture-authorized] [--json]
+  cairn eval protocol --codex-jsonl PATH [--capture-authorized] [--json]
 
 Evaluation is disabled unless CAIRN_EVAL is explicitly enabled. Live harness
 commands remain operator-owned; validate resolves inputs without executing one.
+Protocol audits normalized trajectories or single-turn Codex exec JSONL offline.
+No transcript execution, capture activation, network requests or writes occur.
+Capture authorization is a caller assertion; protocol compliance is not task quality.
 `;
 }
 function valueAfter(args, flag) {
@@ -466,6 +473,22 @@ async function main() {
         disabled(json);
         return;
     }
+    if (command === "protocol") {
+        assertKnown(args, protocolFlags);
+        if (args.includes("--trajectory") === args.includes("--codex-jsonl")) {
+            throw new Error("Supply exactly one of --trajectory or --codex-jsonl.");
+        }
+        const loaded = args.includes("--codex-jsonl") ? readCodexProtocol(requireValue(args, "--codex-jsonl"))
+            : readProtocolTrajectory(requireValue(args, "--trajectory"));
+        const value = auditMemoryProtocol(loaded.session, loaded.digest, args.includes("--capture-authorized"));
+        process.stdout.write(`${json ? JSON.stringify(value) : [
+            `Memory protocol: ${value.status}`,
+            ...value.checks.map(check => `${check.id}: ${check.status} (${check.code})`),
+            "Local evidence only; task quality and authenticated consent are not measured.",
+        ].join("\n")}\n`);
+        process.exitCode = value.status === "fail" ? 1 : value.status === "inconclusive" ? 3 : 0;
+        return;
+    }
     if (command === "validate") {
         assertKnown(args, validateFlags);
         const plan = loadPlan(args);

package/mcp-memory-server/dist/eval-codex.js

@@ -0,0 +1,163 @@
+import { canonicalJson } from "./eval-schema.js";
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function invalid() { throw new Error("protocol_input_invalid_or_unsafe"); }
+/** Explicit single-turn exec JSONL export; never an internal rollout reader. */
+export function normalizeCodexExec(text) {
+    try {
+        if (Buffer.byteLength(text, "utf8") > 16 * 1024 * 1024)
+            invalid();
+        const lines = text.split("\n");
+        if (lines.at(-1) === "" || lines.at(-1) === "\r")
+            lines.pop();
+        if (!lines.length || lines.length > 50_000)
+            invalid();
+        const events = [];
+        const items = new Map();
+        let thread = false, turn = false, ended = false, gaps = 0, reasoning = 0;
+        const emit = (kind, payload) => {
+            events.push({ sequence: events.length, kind, payload });
+        };
+        const extra = (value, fields) => {
+            if (Object.keys(value).some(key => !fields.includes(key)))
+                gaps++;
+        };
+        for (const line of lines) {
+            const event = record(JSON.parse(line));
+            if (!event || typeof event.type !== "string")
+                invalid();
+            if (event.type === "thread.started") {
+                if (thread || turn || ended || typeof event.thread_id !== "string" || !event.thread_id)
+                    invalid();
+                thread = true;
+                extra(event, ["type", "thread_id"]);
+                continue;
+            }
+            if (event.type === "turn.started") {
+                if (turn || ended)
+                    invalid();
+                if (!thread)
+                    gaps++;
+                turn = true;
+                extra(event, ["type"]);
+                continue;
+            }
+            if (event.type === "turn.completed" || event.type === "turn.failed") {
+                if (ended)
+                    invalid();
+                if (!turn || event.type === "turn.failed")
+                    gaps++;
+                ended = true;
+                extra(event, ["type", "usage", "error"]);
+                continue;
+            }
+            if (event.type === "error") {
+                gaps++;
+                continue;
+            }
+            if (!["item.started", "item.updated", "item.completed"].includes(event.type)) {
+                gaps++;
+                continue;
+            }
+            if (ended)
+                invalid();
+            if (!turn)
+                gaps++;
+            extra(event, ["type", "item"]);
+            const item = record(event.item);
+            if (!item || typeof item.id !== "string" || !item.id || item.id.length > 1024 || typeof item.type !== "string")
+                invalid();
+            const id = item.id;
+            const complete = event.type === "item.completed";
+            const previous = items.get(id);
+            if (previous && (previous.complete || previous.type !== item.type || event.type === "item.started"))
+                invalid();
+            const tool = ["mcp_tool_call", "command_execution", "file_change", "web_search"].includes(item.type);
+            let identity = item.type;
+            let name = item.type;
+            let input = {};
+            let output = null;
+            if (item.type === "mcp_tool_call") {
+                extra(item, ["id", "type", "server", "tool", "arguments", "result", "error", "status"]);
+                if (typeof item.server !== "string" || !item.server || typeof item.tool !== "string" || !item.tool
+                    || !record(item.arguments))
+                    invalid();
+                name = `mcp__${item.server}__${item.tool}`;
+                input = item.arguments;
+                identity = canonicalJson({ server: item.server, tool: item.tool, arguments: input });
+                const result = record(item.result);
+                if (result) {
+                    extra(result, ["content", "structured_content", "_meta"]);
+                    output = result.structured_content === undefined || result.structured_content === null
+                        ? { content: result.content } : { structuredContent: result.structured_content };
+                }
+                // Native CLI snapshots serialize absent result/error as null.
+                if (!complete && (item.result != null || item.error != null))
+                    invalid();
+            }
+            else if (item.type === "command_execution") {
+                extra(item, ["id", "type", "command", "aggregated_output", "exit_code", "status"]);
+                if (typeof item.command !== "string")
+                    invalid();
+                identity = canonicalJson({ command: item.command });
+            }
+            else if (item.type === "file_change") {
+                extra(item, ["id", "type", "changes", "status"]);
+                if (!Array.isArray(item.changes))
+                    invalid();
+            }
+            else if (item.type === "web_search") {
+                extra(item, ["id", "type", "query"]);
+                if (typeof item.query !== "string")
+                    invalid();
+            }
+            else if (item.type === "agent_message" || item.type === "reasoning") {
+                extra(item, ["id", "type", "text"]);
+                if (typeof item.text !== "string")
+                    invalid();
+                if (item.type === "reasoning" && !previous)
+                    reasoning++;
+            }
+            else if (item.type === "todo_list") {
+                extra(item, ["id", "type", "items"]);
+                if (!Array.isArray(item.items))
+                    invalid();
+            }
+            else {
+                gaps++;
+            }
+            if (previous && previous.identity !== identity)
+                invalid();
+            if (tool) {
+                if (!previous) {
+                    // MCP/command starts carry dispatch order. A terminal-only
+                    // record cannot establish it, but must still expose writes.
+                    if (["mcp_tool_call", "command_execution"].includes(item.type) && event.type !== "item.started")
+                        gaps++;
+                    emit("tool_invocation", { call_id: id, tool_name: name, input });
+                }
+                if (["mcp_tool_call", "command_execution", "file_change"].includes(item.type)) {
+                    if (complete ? !["completed", "failed"].includes(String(item.status)) : item.status !== "in_progress")
+                        invalid();
+                }
+                if (complete)
+                    emit("tool_result", { call_id: id, output, is_error: item.status === "failed" || item.error != null });
+            }
+            items.set(id, { type: item.type, identity, complete });
+        }
+        if (!thread || !turn || !ended || [...items.values()].some(item => !item.complete))
+            gaps++;
+        if (events.length > 50_000)
+            invalid();
+        // Timestamps/project identity are not supplied by exec JSONL. These
+        // placeholders are private adapter scaffolding, never output claims.
+        const time = "1970-01-01T00:00:00.000Z";
+        return { schema_version: 1, session_id: "codex-exec-export", harness: "codex", project_root: "not-supplied",
+            started_at: time, ended_at: time, events,
+            capture: { captured_at: time, omitted_reasoning_blocks: reasoning, omitted_unknown_records: gaps, truncated: false } };
+    }
+    catch {
+        return invalid();
+    }
+}

package/mcp-memory-server/dist/eval-protocol.js

@@ -0,0 +1,200 @@
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { canonicalJson } from "./eval-schema.js";
+import { MCP_TOOL_CATALOG } from "./mcp-tool-catalog.js";
+import { trajectorySessionSchema } from "./trajectory-schema.js";
+import { normalizeCodexExec } from "./eval-codex.js";
+const MAX_BYTES = 16 * 1024 * 1024;
+const MAX_EVENTS = 50_000;
+const memoryEntries = Object.entries(MCP_TOOL_CATALOG).filter(([name]) => name.startsWith("memory_"));
+const MUTATIONS = new Set(memoryEntries.filter(([, metadata]) => !metadata.annotations.readOnlyHint).map(([name]) => name));
+const OBSERVATIONS = new Set(memoryEntries.filter(([, metadata]) => metadata.annotations.readOnlyHint).map(([name]) => name));
+function digest(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value : undefined;
+}
+/** Only the maintained direct-tool names are recognized; suffix matching is unsafe. */
+function memoryTool(name, harness) {
+    if (typeof name !== "string")
+        return undefined;
+    const prefixes = harness === "claude-code" || harness === "codex" ? ["mcp__cairn-memory__", "mcp__cairn_memory__"]
+        : harness === "opencode" ? ["cairn-memory_", "cairn_memory_"] : [""];
+    for (const prefix of prefixes) {
+        if (!name.startsWith(prefix))
+            continue;
+        const tool = name.slice(prefix.length);
+        if (MUTATIONS.has(tool) || OBSERVATIONS.has(tool))
+            return tool;
+    }
+    return undefined;
+}
+/** Inspect an explicitly supplied export without following links or executing content. */
+function readProtocolBytes(path) {
+    let descriptor;
+    try {
+        const absolute = resolve(path);
+        // Validate the opened descriptor, not a pathname checked before open.
+        // Nonblocking/no-ctty flags prevent special-file admission from waiting
+        // or acquiring a controlling terminal before the regular-file check.
+        descriptor = openSync(absolute, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)
+            | (constants.O_NOCTTY ?? 0) | (process.platform === "win32" ? 0 : constants.O_NONBLOCK ?? 0));
+        const before = fstatSync(descriptor);
+        if (!before.isFile() || before.size > MAX_BYTES || realpathSync(absolute) !== absolute)
+            throw new Error();
+        const buffer = Buffer.alloc(before.size + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const count = readSync(descriptor, buffer, length, buffer.length - length, null);
+            if (!count)
+                break;
+            length += count;
+        }
+        const after = fstatSync(descriptor);
+        const finalPath = realpathSync(absolute);
+        const finalNamed = lstatSync(absolute);
+        if (length !== before.size || before.size !== after.size || before.mtimeMs !== after.mtimeMs
+            || before.ctimeMs !== after.ctimeMs || finalNamed.isSymbolicLink()
+            || finalNamed.dev !== before.dev || finalNamed.ino !== before.ino
+            || finalNamed.size !== before.size || finalNamed.mtimeMs !== before.mtimeMs
+            || finalNamed.ctimeMs !== before.ctimeMs
+            || finalPath !== absolute)
+            throw new Error();
+        const bytes = buffer.subarray(0, length);
+        return bytes;
+    }
+    catch {
+        // Do not expose filesystem errors, parser excerpts, schema paths or input data.
+        throw new Error("protocol_input_invalid_or_unsafe");
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+}
+export function readProtocolTrajectory(path) {
+    try {
+        const bytes = readProtocolBytes(path);
+        const raw = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        if (!Array.isArray(raw?.events) || raw.events.length > MAX_EVENTS)
+            throw new Error();
+        const parsed = trajectorySessionSchema.safeParse(raw);
+        if (!parsed.success)
+            throw new Error();
+        return { session: parsed.data, digest: digest(bytes) };
+    }
+    catch {
+        throw new Error("protocol_input_invalid_or_unsafe");
+    }
+}
+export function readCodexProtocol(path) {
+    try {
+        const bytes = readProtocolBytes(path);
+        const session = normalizeCodexExec(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        return { session, digest: digest(bytes) };
+    }
+    catch {
+        throw new Error("protocol_input_invalid_or_unsafe");
+    }
+}
+function searchPayload(value, depth = 0) {
+    if (depth > 8)
+        return undefined;
+    if (typeof value === "string") {
+        try {
+            return searchPayload(JSON.parse(value), depth + 1);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    // Claude tool-result content and MCP result envelopes are both supported.
+    if (Array.isArray(value)) {
+        if (value.length !== 1)
+            return undefined;
+        const part = object(value[0]);
+        return part?.type === "text" && typeof part.text === "string" ? searchPayload(part.text, depth + 1) : undefined;
+    }
+    const record = object(value);
+    if (!record || record.isError === true || record.ok === false)
+        return undefined;
+    if (record.structuredContent !== undefined)
+        return searchPayload(record.structuredContent, depth + 1);
+    if (record.content !== undefined)
+        return searchPayload(record.content, depth + 1);
+    return record;
+}
+function successfulSearch(result) {
+    if (!result || result.payload.is_error !== false || result.truncation)
+        return false;
+    const payload = searchPayload(result.payload.output);
+    return !!payload && typeof payload.mode === "string" && ["semantic", "substring"].includes(payload.mode)
+        && Number.isSafeInteger(payload.count) && payload.count >= 0
+        && Array.isArray(payload.results) && payload.results.length === payload.count;
+}
+/** This is an observation of local evidence, not authentication or task verification. */
+export function auditMemoryProtocol(session, trajectoryDigest, captureAuthorized = false) {
+    const calls = [];
+    const byId = new Map();
+    let gap = session.capture.truncated || session.capture.omitted_unknown_records > 0
+        || (session.capture.omitted_size_events ?? 0) > 0;
+    for (const [index, event] of session.events.entries()) {
+        if (event.sequence !== index)
+            throw new Error("protocol_invalid_events");
+        if (event.truncation)
+            gap = true;
+        if (event.kind !== "tool_invocation" && event.kind !== "tool_result")
+            continue;
+        const id = event.payload.call_id;
+        if (typeof id !== "string" || !id || id.length > 1024)
+            throw new Error("protocol_invalid_events");
+        if (event.kind === "tool_invocation") {
+            if (byId.has(id) || typeof event.payload.tool_name !== "string")
+                throw new Error("protocol_invalid_events");
+            const call = { event, tool: memoryTool(event.payload.tool_name, session.harness) };
+            calls.push(call);
+            byId.set(id, call);
+        }
+        else {
+            const call = byId.get(id);
+            if (!call || call.result)
+                throw new Error("protocol_invalid_events");
+            call.result = event;
+        }
+    }
+    if (calls.some(call => !call.result))
+        gap = true;
+    const projectSearches = calls.filter(call => call.tool === "memory_search"
+        && object(call.event.payload.input)?.scope === "project" && !call.event.truncation);
+    const first = calls[0];
+    const writes = calls.filter(call => call.tool && MUTATIONS.has(call.tool));
+    const opaque = calls.filter(call => !call.tool);
+    const checks = [
+        { id: "evidence_complete", status: gap ? "inconclusive" : "pass", code: gap ? "capture_incomplete" : "capture_complete" },
+        { id: "memory_first", status: gap ? "inconclusive" : first && projectSearches[0] === first ? "pass" : "fail",
+            code: gap ? "ordering_unverifiable" : first && projectSearches[0] === first ? "project_search_first" : "project_search_not_first" },
+        { id: "retrieval_result", status: projectSearches.some(call => successfulSearch(call.result)) ? "pass" : projectSearches.length || gap ? "inconclusive" : "fail",
+            code: projectSearches.some(call => successfulSearch(call.result)) ? "project_search_completed"
+                : projectSearches.length || gap ? "search_result_unverifiable" : "project_search_absent" },
+        { id: "direct_write_boundary", status: writes.length && !captureAuthorized ? "fail" : gap || opaque.length ? "inconclusive" : "pass",
+            code: writes.length && !captureAuthorized ? "unapproved_write_attempt"
+                : gap || opaque.length ? "indirect_writes_unverifiable" : writes.length ? "caller_asserted_capture_authorization" : "no_direct_write_attempt" },
+    ];
+    const policy = { schema_version: 1, protocol: "project-memory-first-v1", capture_authorized: captureAuthorized,
+        scope: "direct-memory-tools", direct_mutation_tools: [...MUTATIONS].sort(), direct_observation_tools: [...OBSERVATIONS].sort() };
+    const status = checks.some(check => check.status === "fail") ? "fail"
+        : checks.some(check => check.status === "inconclusive") ? "inconclusive" : "pass";
+    return {
+        schema_version: 1, enabled: true, operation: "protocol", evidence_scope: "local-trajectory-observation",
+        harness: session.harness, trajectory_digest: trajectoryDigest, policy_digest: digest(canonicalJson(policy)),
+        policy, status, checks,
+        counts: { tool_invocations: calls.length, project_searches: projectSearches.length,
+            successful_project_searches: projectSearches.filter(call => successfulSearch(call.result)).length,
+            direct_write_attempts: writes.length, opaque_tool_invocations: opaque.length },
+        limitations: ["input_not_authenticated", "task_quality_not_measured", "authorization_is_caller_assertion",
+            "indirect_tool_effects_not_certified", "task_boundaries_not_inferred", "tool_availability_not_inferred"],
+    };
+}

package/mcp-memory-server/package.json

@@ -45,6 +45,8 @@
         "check:eval-schema": "node scripts/smoke-eval-schema.mjs",
         "check:eval-process": "node scripts/smoke-eval-process.mjs",
         "check:eval-statistics": "node scripts/smoke-eval-statistics.mjs",
+        "check:eval-protocol": "node scripts/smoke-eval-protocol.mjs",
+        "check:codex-protocol": "node scripts/smoke-codex-protocol.mjs",
         "check:skill-lifecycle": "node scripts/smoke-skill-lifecycle.mjs",
         "check:graph-cli": "node scripts/smoke-graph-cli.mjs",
         "check:mcp-trust": "node scripts/smoke-mcp-trust.mjs",
@@ -62,7 +64,7 @@
         "check:security-assurance": "node scripts/smoke-security-assurance.mjs",
         "check:notes": "npm run build && npm run check:note-signatures && npm run check:note-distillation && npm run check:note-enrichment",
         "test": "npm run test:smoke",
-        "test:smoke": "npm run build && npm run check:embeddings && npm run check:extract && npm run check:scope-guard && npm run check:http-guard && npm run check:remote-context && npm run check:explore-guard && npm run check:explore-cache && npm run check:explore-crossref && npm run check:route-guard && npm run check:reviewed-memory && npm run check:memory-proposals && npm run check:trajectory-roundtrip && npm run check:trajectory-redaction && npm run check:trajectory-retention && npm run check:note-signatures && npm run check:note-distillation && npm run check:note-enrichment && npm run check:node-compat && npm run check:typed-nodes && npm run check:memory-import && npm run check:note-mcp && npm run check:node-doctor && npm run check:artifact-store && npm run check:artifact-mcp && npm run check:compaction-capture && npm run check:capability-contract && npm run check:capability-logging && npm run check:capability-harness && npm run check:capability-mcp && npm run check:eval-schema && npm run check:eval-process && npm run check:eval-statistics && npm run check:skill-lifecycle && npm run check:graph-cli && npm run check:mcp-trust && npm run check:pi-mcp-bridge && npm run check:pi-bridge-env && npm run check:pi-bridge-child && npm run check:context-pack && npm run check:context-pack-retrieval && npm run check:context-pack-v216-compat && npm run check:context-usage && npm run check:domain-retrieval && npm run check:retrieval-benchmark && npm run check:work-evidence && npm run check:okf && npm run check:playbook && npm run check:security-assurance",
+        "test:smoke": "npm run build && node scripts/run-smoke-suite.mjs",
         "test:search": "npm run build && npm run check:search",
         "test:memory": "npm run build && npm run check:embeddings && npm run check:extract && npm run check:search",
         "test:all": "npm run test:memory",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cairnkeep/cli",
-    "version": "2.21.0",
+    "version": "2.22.0",
     "description": "A durable, harness-agnostic memory + context layer for coding agents and MCP clients.",
     "license": "Apache-2.0",
     "type": "module",

package/scripts/cairn-cli.mjs

@@ -55,7 +55,7 @@ Usage:
   cairn mcp-tools <list|status|set|reset>
   cairn pack <init|lock|validate|install|list|show|remove|enable|disable|update|skills|approve-skill|revoke-skill>
   cairn notes <distill|search-error|promote|doctor>
-  cairn eval <validate|run|ablate|report|prune|delete>
+  cairn eval <validate|run|ablate|report|prune|delete|protocol>
   cairn skill <harvest|list|show|review|propose|evaluate|apply|rollback>
   cairn graph <build|query|status|diff|explain|path>
   cairn evidence <list|show|delete|prune|doctor>

package/scripts/completion.sh

@@ -70,7 +70,8 @@ _cairn_complete() {
         report) COMPREPLY=( $(compgen -W "--experiment --json" -- "$current") ) ;;
         prune) COMPREPLY=( $(compgen -W "--older-than-days --dry-run --json" -- "$current") ) ;;
         delete) COMPREPLY=( $(compgen -W "--experiment --dry-run --json" -- "$current") ) ;;
-        *) COMPREPLY=( $(compgen -W "validate run ablate report prune delete" -- "$current") ) ;;
+        protocol) COMPREPLY=( $(compgen -W "--trajectory --codex-jsonl --capture-authorized --json" -- "$current") ) ;;
+        *) COMPREPLY=( $(compgen -W "validate run ablate report prune delete protocol" -- "$current") ) ;;
       esac
       ;;
     skill) COMPREPLY=( $(compgen -W "harvest list show review propose evaluate apply rollback --project --minimum-occurrences --kind --id --candidate --approve --target --adapter --edit-budget --proposal --exploration-task-set --confirmation-task-set --output --repetitions --seed --minimum-improvement --evaluation --application --confirm --yes --json" -- "$current") ) ;;
@@ -164,7 +165,8 @@ _cairn() {
         report) _arguments '--experiment[experiment ID]:experiment ID:' '--json[emit JSON]' ;;
         prune) _arguments '--older-than-days[retention age]:days:' '--dry-run[report without pruning]' '--json[emit JSON]' ;;
         delete) _arguments '--experiment[experiment ID]:experiment ID:' '--dry-run[report without deleting]' '--json[emit JSON]' ;;
-        *) _values 'eval command' validate run ablate report prune delete ;;
+        protocol) _arguments '--trajectory[normalized trajectory export]:file:_files' '--codex-jsonl[single-turn Codex exec JSONL export]:file:_files' '--capture-authorized[assert operator authorization for capture]' '--json[emit JSON]' ;;
+        *) _values 'eval command' validate run ablate report prune delete protocol ;;
       esac
       ;;
     skill)
@@ -272,7 +274,10 @@ complete -c cairn -n "__fish_seen_subcommand_from proposals" -l category -r
 complete -c cairn -n "__fish_seen_subcommand_from proposals" -l project -r
 complete -c cairn -n "__fish_seen_subcommand_from proposals" -l json
 complete -c cairn -n "__fish_seen_subcommand_from notes" -a "distill search-error promote doctor"
-complete -c cairn -n "__fish_seen_subcommand_from eval; and not __fish_seen_subcommand_from validate run ablate report prune delete" -a "validate run ablate report prune delete"
+complete -c cairn -n "__fish_seen_subcommand_from eval; and not __fish_seen_subcommand_from validate run ablate report prune delete protocol" -a "validate run ablate report prune delete protocol"
+complete -c cairn -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from protocol" -l trajectory -r
+complete -c cairn -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from protocol" -l codex-jsonl -r
+complete -c cairn -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from protocol" -l capture-authorized
 complete -c cairn -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from validate run ablate" -l task-set -r
 complete -c cairn -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from validate run ablate" -l adapter -r
 complete -c cairn -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from validate run ablate" -l output -r
@@ -283,7 +288,7 @@ complete -c cairn -n "__fish_seen_subcommand_from eval; and __fish_seen_subcomma
 complete -c cairn -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from report delete" -l experiment -r
 complete -c cairn -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from prune" -l older-than-days -r
 complete -c cairn -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from prune delete" -l dry-run
-complete -c cairn -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from validate run ablate report prune delete" -l json
+complete -c cairn -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from validate run ablate report prune delete protocol" -l json
 complete -c cairn -n "__fish_seen_subcommand_from skill; and not __fish_seen_subcommand_from harvest list show review propose evaluate apply rollback" -a "harvest list show review propose evaluate apply rollback"
 complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from harvest list show review propose evaluate apply rollback" -l project -r
 complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from harvest list show review propose evaluate apply rollback" -l json

package/scripts/doctor.sh

@@ -36,15 +36,31 @@ fail() { printf '  [FAIL] %s\n' "$1"; fails=$((fails + 1)); }
 # reachable); a connect/timeout failure returns non-zero.
 reachable() { curl -sS -m 5 -o /dev/null "$1" >/dev/null 2>&1; }
 
+embedding_failure="request failed"
 embedding_works() {
-  local payload
+  local payload http_status curl_status
   payload=$(node -e 'process.stdout.write(JSON.stringify({ model: process.argv[1], input: ["cairnkeep health check"] }))' \
     "$CAIRN_MEMORY_EMBEDDING_MODEL") || return 1
-  curl -fsS -m 10 -o /dev/null \
+  http_status=$(curl -sS -m 10 -o /dev/null -w '%{http_code}' \
     -H "Authorization: Bearer $CAIRN_LLM_API_KEY" \
     -H "Content-Type: application/json" \
     --data "$payload" \
-    "${CAIRN_MEMORY_EMBEDDING_URL%/}/embeddings" >/dev/null 2>&1
+    "${CAIRN_MEMORY_EMBEDDING_URL%/}/embeddings" 2>/dev/null)
+  curl_status=$?
+  if [[ $curl_status -ne 0 ]]; then
+    embedding_failure="transport failed"
+    return 1
+  fi
+  case "$http_status" in
+    2??) return 0 ;;
+    401|403) embedding_failure="authorization rejected (HTTP $http_status)" ;;
+    404) embedding_failure="endpoint or model not found (HTTP 404)" ;;
+    408|429) embedding_failure="temporarily unavailable (HTTP $http_status)" ;;
+    5??) embedding_failure="upstream service failed (HTTP $http_status)" ;;
+    [0-9][0-9][0-9]) embedding_failure="request failed (HTTP $http_status)" ;;
+    *) embedding_failure="request failed" ;;
+  esac
+  return 1
 }
 
 echo "cairn doctor"
@@ -90,7 +106,7 @@ if [[ -n "${CAIRN_MEMORY_EMBEDDING_URL:-}" ]]; then
   elif embedding_works; then
     pass "embedding endpoint accepted model ${CAIRN_MEMORY_EMBEDDING_MODEL} (${CAIRN_MEMORY_EMBEDDING_URL})"
   else
-    fail "embedding request failed for model ${CAIRN_MEMORY_EMBEDDING_MODEL} (${CAIRN_MEMORY_EMBEDDING_URL})"
+    fail "embedding ${embedding_failure} for model ${CAIRN_MEMORY_EMBEDDING_MODEL} (${CAIRN_MEMORY_EMBEDDING_URL})"
   fi
 else
   skip "embedding endpoint (CAIRN_MEMORY_EMBEDDING_URL unset)"

package/scripts/spikes/verify-release-ledger.mjs

@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+import assert from "node:assert/strict";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// Independent artifact grader for the bounded release-ledger task. Importing
+// an explicitly selected module executes it: run only in an isolated lab.
+export async function verifyReleaseLedger(path) {
+  const checks = [];
+  const check = async (id, fn) => {
+    try { await fn(); checks.push({ id, pass: true }); }
+    catch { checks.push({ id, pass: false }); }
+  };
+  let mod, ledger, first, final;
+  const input = { package: "sample", version: "1.0.0", notes: ["First", "Second"] };
+  const errorCode = (fn, code) => assert.throws(fn, error => error?.code === code);
+  await check("export", async () => {
+    mod = await import(pathToFileURL(resolve(path)).href);
+    assert.equal(typeof mod.createLedger, "function");
+    ledger = mod.createLedger();
+  });
+  await check("methods", () => { for (const method of ["append", "get", "list", "finalize"]) assert.equal(typeof ledger[method], "function"); });
+  await check("append", () => { first = ledger.append(input); assert.equal(first.state, "draft"); assert.equal(first.sequence, 1); assert.deepEqual(first.notes, input.notes); });
+  await check("shape", () => assert.deepEqual(Object.keys(first).sort(), ["package", "version", "notes", "sequence", "state"].sort()));
+  await check("invalid-package", () => errorCode(() => ledger.append({ ...input, package: "Bad_Name" }), "INVALID_PACKAGE"));
+  await check("invalid-version", () => errorCode(() => ledger.append({ ...input, version: "v1.0" }), "INVALID_VERSION"));
+  await check("invalid-notes", () => errorCode(() => ledger.append({ ...input, notes: [] }), "INVALID_NOTES"));
+  await check("duplicate", () => errorCode(() => ledger.append(input), "DUPLICATE_RELEASE"));
+  await check("sequence", () => assert.equal(ledger.append({ ...input, package: "other" }).sequence, 2));
+  await check("not-found", () => errorCode(() => ledger.get("missing", "1.0.0"), "NOT_FOUND"));
+  await check("finalize", () => { final = ledger.finalize("sample", "1.0.0"); assert.equal(final.state, "final"); });
+  await check("checksum", () => assert.equal(final.checksum, createHash("sha256").update(JSON.stringify({ ...input, sequence: 1 })).digest("hex")));
+  await check("idempotent", () => assert.deepEqual(ledger.finalize("sample", "1.0.0"), final));
+  await check("detached-get", () => { const copy = ledger.get("sample", "1.0.0"); copy.notes.push("tamper"); copy.state = "draft"; const fresh = ledger.get("sample", "1.0.0"); assert.deepEqual(fresh.notes, ["First", "Second"]); assert.equal(fresh.state, "final"); });
+  await check("ordered-detached-list", () => { const copies = ledger.list(); assert.deepEqual(copies.map(entry => entry.sequence), [1, 2]); copies[0].notes[0] = "tamper"; assert.equal(ledger.list()[0].notes[0], "First"); });
+  return { checks, passed: checks.filter(check => check.pass).length, total: checks.length };
+}
+
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+  if (process.argv.length !== 3) { process.stderr.write("Usage: verify-release-ledger.mjs MODULE_PATH\n"); process.exitCode = 2; }
+  else {
+    const value = await verifyReleaseLedger(process.argv[2]);
+    process.stdout.write(`${JSON.stringify(value)}\n`);
+    process.exitCode = value.passed === value.total ? 0 : 1;
+  }
+}