@cairnkeep/cli 2.3.0 → 2.4.0

package/scripts/doctor.sh

@@ -9,6 +9,14 @@
 set -uo pipefail
 
 CAIRN_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+REPAIR_STORES=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repair) REPAIR_STORES=1; shift ;;
+    -h|--help) echo "Usage: cairn doctor [--repair]  # repair derived trajectory/artifact/typed metadata, indexes, and interrupted note transactions"; exit 0 ;;
+    *) echo "Unknown doctor option: $1" >&2; echo "Usage: cairn doctor [--repair]" >&2; exit 2 ;;
+  esac
+done
 
 # Load the project's .ai/.env if present (does not override already-set env).
 if [[ -f "$PWD/.ai/.env" ]]; then
@@ -116,6 +124,282 @@ else
   warn "sqlite3 not found — memory export unavailable (runtime and import unaffected)"
 fi
 
+# 7. Project-local trajectory store. Absence is healthy because capture is
+#    opt-in. Existing stores must pass SQLite, schema and index checks. Repair
+#    is explicit and only reconstructs metadata/indexes from valid full records.
+trajectory_cli="$CAIRN_ROOT/mcp-memory-server/dist/trajectory-cli.js"
+trajectory_dir="$PWD/.agentfs"
+if [[ -d "$trajectory_dir" && ! -w "$trajectory_dir" ]]; then
+  fail "trajectory store directory is not writable: $trajectory_dir"
+elif [[ ! -d "$trajectory_dir" && ! -w "$PWD" ]]; then
+  fail "trajectory store parent is not writable: $PWD"
+elif [[ ! -f "$trajectory_cli" ]]; then
+  fail "trajectory diagnostics unavailable — rebuild mcp-memory-server"
+else
+  trajectory_args=(doctor --json)
+  [[ $REPAIR_STORES -eq 1 ]] && trajectory_args+=(--repair)
+  trajectory_json=$(node "$trajectory_cli" "${trajectory_args[@]}" 2>/dev/null)
+  trajectory_status=$?
+  trajectory_state=$(node -e '
+try {
+  const value = JSON.parse(process.argv[1])
+  if (!value.exists) process.stdout.write("absent")
+  else if (value.ok && value.repaired) process.stdout.write("repaired")
+  else if (value.ok) process.stdout.write("ok")
+  else process.stdout.write("broken")
+} catch { process.stdout.write("invalid") }
+' "$trajectory_json" 2>/dev/null)
+  case "$trajectory_state" in
+    absent) skip "trajectory store (not present — capture is opt-in)" ;;
+    repaired) pass "trajectory store repaired (metadata/indexes rebuilt; full records preserved)" ;;
+    ok) pass "trajectory store integrity, schema and indexes are valid" ;;
+    *)
+      if [[ $REPAIR_STORES -eq 1 ]]; then
+        fail "trajectory store could not be repaired safely; preserve .agentfs/trajectory.db and inspect it manually"
+      else
+        fail "trajectory store metadata/schema/index check failed — run: cairn doctor --repair"
+      fi
+      ;;
+  esac
+  [[ $trajectory_status -eq 0 || "$trajectory_state" == "broken" ]] || true
+fi
+
+# 8. Project-local artifact store. Absence is healthy because compaction
+#    continuity and explicit artifact access are both opt-in. Repair may only
+#    rebuild derived indexes, dedupe rows, and latest pointers from valid full
+#    records; authoritative schema, digest, full-record, or SQLite corruption
+#    is never modified automatically.
+artifact_cli="$CAIRN_ROOT/mcp-memory-server/dist/artifact-cli.js"
+if [[ ! -f "$artifact_cli" ]]; then
+  fail "artifact diagnostics unavailable — rebuild mcp-memory-server"
+else
+  artifact_args=(doctor --json)
+  [[ $REPAIR_STORES -eq 1 ]] && artifact_args+=(--repair)
+  artifact_json=$(node "$artifact_cli" "${artifact_args[@]}" 2>/dev/null)
+  artifact_status=$?
+  artifact_state=$(node -e '
+try {
+  const value = JSON.parse(process.argv[1])
+  if (!value.exists) process.stdout.write("absent")
+  else if (value.ok && value.repaired) process.stdout.write("repaired")
+  else if (value.ok) process.stdout.write("ok")
+  else process.stdout.write("broken")
+} catch { process.stdout.write("invalid") }
+' "$artifact_json" 2>/dev/null)
+  case "$artifact_state" in
+    absent) skip "artifact store (not present — compaction capture and artifact access are opt-in)" ;;
+    repaired) pass "artifact store repaired (derived indexes, dedupe rows, and pointers rebuilt; authoritative records preserved)" ;;
+    ok) pass "artifact store integrity, schema, digests, indexes, pointers, and retention state are valid" ;;
+    *)
+      if [[ $REPAIR_STORES -eq 1 ]]; then
+        fail "artifact store could not be repaired safely; preserve .agentfs/artifacts.db and inspect authoritative corruption manually"
+      else
+        fail "artifact store authoritative/schema/digest/index check failed — preserve .agentfs/artifacts.db, then run: cairn doctor --repair"
+      fi
+      ;;
+  esac
+  [[ $artifact_status -eq 0 || "$artifact_state" == "broken" ]] || true
+fi
+
+# 9. Typed metadata overlays and canonical-note transaction state. The internal
+#    JSON seam enumerates only contained local databases and the one notes root;
+#    raw KV cells and unmarked Markdown bytes are never repair inputs.
+node_cli="$CAIRN_ROOT/mcp-memory-server/dist/node-cli.js"
+if [[ ! -f "$node_cli" ]]; then
+  fail "typed-node diagnostics unavailable — rebuild mcp-memory-server"
+else
+  node_args=(doctor --project-root "$PWD")
+  [[ $REPAIR_STORES -eq 1 ]] && node_args+=(--repair)
+  node_json=$(node "$node_cli" "${node_args[@]}" 2>/dev/null)
+  node_status=$?
+  node_state=$(node -e '
+try {
+  const value = JSON.parse(process.argv[1])
+  if (!value.exists) process.stdout.write("absent")
+  else if (value.ok && value.repaired) process.stdout.write("repaired")
+  else if (value.ok) process.stdout.write("ok")
+  else process.stdout.write("broken")
+} catch { process.stdout.write("invalid") }
+' "$node_json" 2>/dev/null)
+  case "$node_state" in
+    absent) skip "typed metadata and note transaction state (not present)" ;;
+    repaired) pass "typed metadata/indexes and note transactions repaired safely" ;;
+    ok) pass "typed metadata, replay state, and note transactions are valid" ;;
+    *)
+      if [[ $REPAIR_STORES -eq 1 ]]; then
+        fail "typed/note state could not be repaired safely; preserve the memory store and recovery journals before manual inspection"
+      else
+        fail "typed metadata or note transaction check failed — run: cairn doctor --repair"
+      fi
+      ;;
+  esac
+  [[ $node_status -eq 0 || "$node_state" == "broken" ]] || true
+fi
+
+# 10. Managed capability configuration and the independent callback namespace.
+# The TypeScript doctor owns all config/database reads. This shell layer accepts
+# only its fixed states, codes, canonical IDs, and setting name; raw values,
+# records, paths, parser errors, and SQLite details never cross the boundary.
+capability_cli="$CAIRN_ROOT/mcp-memory-server/dist/capability-cli.js"
+if [[ ! -f "$capability_cli" ]]; then
+  fail "capability diagnostics unavailable — rebuild mcp-memory-server"
+else
+  capability_json=$(node "$capability_cli" doctor --json 2>/dev/null)
+  capability_status=$?
+  if ! capability_mapped=$(node - "$capability_json" <<'NODE'
+const ids = new Set([
+  "memory.write", "memory.search", "notes.distill", "wiki",
+  "graph", "security.audit", "route.check", "context.explore",
+]);
+const configCodes = new Set([
+  "unknown-capability", "invalid-capability-value", "invalid-logging-value",
+  "invalid-config", "unsafe-permissions",
+]);
+const callbackCodes = new Set([
+  "sqlite-integrity-failed", "schema-missing", "schema-unsupported",
+  "invalid-record", "diagnostic-failed",
+]);
+try {
+  const value = JSON.parse(process.argv[2]);
+  const configuration = value.configuration;
+  const callbacks = value.callbacks;
+  if (value.schema_version !== 1
+      || !configuration || configuration.name !== ".ai/capabilities.json"
+      || !callbacks || callbacks.name !== ".agentfs/trajectory.db"
+      || typeof configuration.exists !== "boolean"
+      || typeof callbacks.exists !== "boolean"
+      || !["PASS", "WARN", "FAIL"].includes(configuration.state)
+      || !["PASS", "FAIL"].includes(callbacks.state)
+      || !Array.isArray(configuration.issues)
+      || !Array.isArray(callbacks.issues)) throw new Error("invalid");
+
+  const configRows = configuration.issues.map((issue) => {
+    if (!issue || typeof issue !== "object" || !configCodes.has(issue.code)) throw new Error("invalid");
+    if (issue.code === "invalid-capability-value") {
+      if (!ids.has(issue.capability_id) || issue.setting !== undefined) throw new Error("invalid");
+      return [issue.code, issue.capability_id];
+    }
+    if (issue.code === "invalid-logging-value") {
+      if (issue.setting !== "logging.callbacks" || issue.capability_id !== undefined) throw new Error("invalid");
+      return [issue.code, issue.setting];
+    }
+    if (issue.capability_id !== undefined || issue.setting !== undefined) throw new Error("invalid");
+    return [issue.code, "-"];
+  });
+  if ((configuration.state === "PASS") !== (configRows.length === 0)) throw new Error("invalid");
+  if (configuration.state === "WARN" && configRows.some(([code]) => code === "invalid-config" || code === "unsafe-permissions")) throw new Error("invalid");
+  if (configuration.state === "FAIL" && !configRows.some(([code]) => code === "invalid-config" || code === "unsafe-permissions")) throw new Error("invalid");
+
+  const callbackRows = callbacks.issues.map((code) => {
+    if (typeof code !== "string" || !callbackCodes.has(code)) throw new Error("invalid");
+    return code;
+  });
+  if ((callbacks.state === "PASS") !== (callbackRows.length === 0)) throw new Error("invalid");
+
+  console.log(["configuration", configuration.state, configuration.exists ? "present" : "absent"].join("\t"));
+  for (const [code, subject] of configRows) console.log(["configuration-issue", code, subject].join("\t"));
+  console.log(["callbacks", callbacks.state, callbacks.exists ? "present" : "absent"].join("\t"));
+  for (const code of callbackRows) console.log(["callback-issue", code, "-"].join("\t"));
+} catch {
+  process.exit(1);
+}
+NODE
+  ); then
+    fail "capability diagnostics returned an invalid value-free response"
+  else
+    while IFS=$'\t' read -r area state detail; do
+      case "$area:$state:$detail" in
+        configuration:PASS:absent)
+          pass "capability configuration (not present — managed overrides are unused)"
+          ;;
+        configuration:PASS:present)
+          pass "capability configuration schema and permissions are valid"
+          ;;
+        configuration:WARN:*|configuration:FAIL:*)
+          ;;
+        configuration-issue:unknown-capability:-)
+          warn "capability configuration contains an unknown override ID"
+          ;;
+        configuration-issue:invalid-capability-value:*)
+          warn "capability configuration has an invalid value for $detail"
+          ;;
+        configuration-issue:invalid-logging-value:logging.callbacks)
+          warn "capability configuration has an invalid value for logging.callbacks"
+          ;;
+        configuration-issue:invalid-config:-)
+          fail "capability configuration is invalid or uses an unsupported schema; preserve .ai/capabilities.json before reset"
+          ;;
+        configuration-issue:unsafe-permissions:-)
+          fail "capability configuration type or permissions are unsafe; preserve .ai/capabilities.json before recovery"
+          ;;
+        callbacks:PASS:absent)
+          pass "capability callback namespace (not present — callback logging is unused)"
+          ;;
+        callbacks:PASS:present)
+          pass "capability callback namespace schema and SQLite integrity are valid"
+          ;;
+        callbacks:FAIL:*)
+          ;;
+        callback-issue:sqlite-integrity-failed:-)
+          fail "capability callback namespace SQLite integrity failed; preserve .agentfs/trajectory.db before recovery"
+          ;;
+        callback-issue:schema-missing:-)
+          fail "capability callback namespace schema marker is missing; preserve .agentfs/trajectory.db before recovery"
+          ;;
+        callback-issue:schema-unsupported:-)
+          fail "capability callback namespace schema is unsupported; preserve .agentfs/trajectory.db before recovery"
+          ;;
+        callback-issue:invalid-record:-)
+          fail "capability callback namespace contains invalid records; preserve .agentfs/trajectory.db before recovery"
+          ;;
+        callback-issue:diagnostic-failed:-)
+          fail "capability callback namespace could not be diagnosed safely; preserve .agentfs/trajectory.db before recovery"
+          ;;
+        *)
+          fail "capability diagnostics returned an invalid value-free response"
+          ;;
+      esac
+    done <<< "$capability_mapped"
+    [[ $capability_status -eq 0 || "$capability_mapped" == *$'\tFAIL\t'* ]] ||
+      fail "capability diagnostics exited unexpectedly"
+  fi
+fi
+
+# 11. Evaluation reports. The private compiled operation resolves the owned
+# project-local report root and returns one bounded, value-free state. The
+# shell never reads report bytes and treats malformed output as unsafe.
+eval_cli="$CAIRN_ROOT/mcp-memory-server/dist/eval-cli.js"
+eval_state="unsafe"
+if [[ -f "$eval_cli" ]]; then
+  eval_json=$(node "$eval_cli" doctor-diagnosis --root "$PWD" --json 2>/dev/null | head -c 257)
+  if parsed_eval_state=$(node - "$eval_json" <<'NODE'
+const raw = process.argv[2];
+try {
+  if (Buffer.byteLength(raw, "utf8") > 64) throw new Error("invalid");
+  const value = JSON.parse(raw);
+  const keys = Object.keys(value).sort();
+  if (JSON.stringify(keys) !== JSON.stringify(["diagnosis", "schema_version"])
+      || value.schema_version !== 1
+      || !["absent", "ok", "partial", "tampered", "unsafe"].includes(value.diagnosis)) {
+    throw new Error("invalid");
+  }
+  process.stdout.write(value.diagnosis);
+} catch {
+  process.exit(1);
+}
+NODE
+  ); then
+    eval_state="$parsed_eval_state"
+  fi
+fi
+case "$eval_state" in
+  absent) skip "evaluation reports (not present — evaluation is opt-in)" ;;
+  ok) pass "evaluation reports are complete and valid" ;;
+  partial) warn "evaluation reports are partial" ;;
+  tampered) warn "evaluation report integrity check failed" ;;
+  unsafe) warn "evaluation report storage is unsafe" ;;
+esac
+
 echo
 if [[ "$fails" -gt 0 ]]; then
   echo "cairn doctor: $fails configured dependency check(s) failed."

package/scripts/fake-eval-adapter.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// Deterministic offline-framework adapter. It is fixture code, never live evidence.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+
+const MAX_REQUEST_BYTES = 1024 * 1024;
+const chunks = [];
+let requestBytes = 0;
+for await (const chunk of process.stdin) {
+  const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+  requestBytes += bytes.byteLength;
+  if (requestBytes > MAX_REQUEST_BYTES) {
+    process.stderr.write("offline-framework: request limit exceeded\n");
+    process.exit(2);
+  }
+  chunks.push(bytes);
+}
+
+let request;
+try {
+  request = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+} catch {
+  process.stderr.write("offline-framework: invalid request\n");
+  process.exit(2);
+}
+
+const required = [
+  "schema_version", "experiment_id", "task_id", "arm", "repetition", "pass",
+  "workspace_path", "notes_path", "input", "limits", "seed",
+  "expected_capability_digest", "output_path",
+];
+if (!request || typeof request !== "object"
+    || Object.keys(request).sort().join("\0") !== [...required].sort().join("\0")) {
+  process.stderr.write("offline-framework: unsupported request shape\n");
+  process.exit(2);
+}
+
+const workspace = resolve(process.cwd(), request.workspace_path);
+const sessionId = `${request.arm}-r${request.repetition}-${request.pass}-${request.task_id}`;
+if (process.env.CAIRN_FAKE_PID_FILE) writeFileSync(process.env.CAIRN_FAKE_PID_FILE, `${process.pid}\n`, { mode: 0o600 });
+
+function trajectory(events) {
+  const agentfs = join(workspace, ".agentfs");
+  mkdirSync(agentfs, { recursive: true, mode: 0o700 });
+  const database = new DatabaseSync(join(agentfs, "trajectory.db"));
+  database.exec("CREATE TABLE kv_store (key TEXT PRIMARY KEY, value TEXT NOT NULL, created_at INTEGER DEFAULT (unixepoch ()), updated_at INTEGER DEFAULT (unixepoch ()))");
+  const startedAt = "2026-01-01T00:00:00.000Z";
+  const endedAt = "2026-01-01T00:00:01.000Z";
+  const session = {
+    schema_version: 1,
+    session_id: sessionId,
+    harness: "pi",
+    project_root: workspace,
+    started_at: startedAt,
+    ended_at: endedAt,
+    events,
+    capture: {
+      captured_at: endedAt,
+      omitted_reasoning_blocks: 0,
+      omitted_unknown_records: 0,
+      truncated: false,
+    },
+  };
+  const index = {
+    schema_version: 1,
+    session_id: sessionId,
+    harness: "pi",
+    started_at: startedAt,
+    ended_at: endedAt,
+    event_count: events.length,
+    logical_bytes: Buffer.byteLength(JSON.stringify(session)),
+    full_key: `trajectory/session/${sessionId}`,
+  };
+  const insert = database.prepare("INSERT INTO kv_store(key,value) VALUES(?,?)");
+  insert.run("trajectory/meta/schema-version", "1");
+  insert.run(`trajectory/session/${sessionId}`, JSON.stringify(session));
+  insert.run(`trajectory/index/${String(Date.parse(endedAt)).padStart(16, "0")}/${sessionId}`, JSON.stringify(index));
+  database.close();
+}
+
+if (process.env.CAIRN_FAKE_CANCEL_ALL === "1"
+    || request.task_id === "offline-timeout"
+    || (request.task_id === "offline-cancellation-control" && process.env.CAIRN_FAKE_CANCEL === "1")) {
+  await new Promise((resolveWait) => setTimeout(resolveWait, 60_000));
+}
+if (request.task_id === "offline-invalid-result") {
+  process.stdout.write('{"schema_version":1,"status":"completed","unexpected":true}');
+  process.exit(0);
+}
+if (request.task_id === "offline-adapter-error") {
+  process.stdout.write(JSON.stringify({ schema_version: 1, status: "adapter_error", error_code: "designed_adapter_error" }));
+  process.exit(0);
+}
+
+writeFileSync(join(workspace, "adapter-result.txt"), `${request.task_id}:${request.pass}\n`, { mode: 0o600 });
+if (request.task_id === "offline-distillation-failure") {
+  const agentfs = join(workspace, ".agentfs");
+  mkdirSync(agentfs, { recursive: true, mode: 0o700 });
+  writeFileSync(join(agentfs, "trajectory.db"), "designed-invalid-store", { mode: 0o600 });
+} else if (request.task_id !== "offline-skipped-notes") {
+  const events = request.task_id === "offline-pass-note" ? [
+    { sequence: 0, kind: "tool_invocation", payload: { call_id: "fixture-call", tool_name: "fixture-check", input: { task: request.task_id } } },
+    { sequence: 1, kind: "tool_result", payload: { call_id: "fixture-call", is_error: true, error: "Deterministic fixture failure" } },
+  ] : [];
+  trajectory(events);
+}
+
+const result = {
+  schema_version: 1,
+  status: "completed",
+  turns: { value: request.pass === "run1" ? 2 : 1, semantics: "offline-fixture-turn" },
+  harness: { id: "cairn-offline-fake" },
+  adapter: { id: "cairn-offline-fake" },
+  model: { id: "deterministic-fixture" },
+  observed_capability_digest: request.expected_capability_digest,
+  ...(request.task_id === "offline-skipped-notes" ? {} : { trajectory_ref: sessionId }),
+  ...(request.task_id === "offline-missing-tokens" ? {} : { usage: { total_tokens: request.pass === "run1" ? 20 : 10 } }),
+};
+process.stdout.write(JSON.stringify(result));