ctx-mcp 0.1.0

package/src/storage/queries.ts

@@ -0,0 +1,294 @@
+import type { StorageEngine } from "./engine.js";
+
+export type TraceRow = {
+  trace_id: string;
+  workflow_id: string | null;
+  actor: string | null;
+  intent: string;
+  tags_json: string;
+  metadata_json: string;
+  started_at: number;
+  finished_at: number | null;
+  status: string | null;
+  outcome_json: string | null;
+};
+
+export type NodeRow = {
+  node_id: string;
+  trace_id: string;
+  type: string;
+  summary: string;
+  data_json: string;
+  confidence: number | null;
+  metadata_json: string;
+  created_at: number;
+};
+
+export type EdgeRow = {
+  edge_id: string;
+  trace_id: string;
+  from_node_id: string;
+  to_node_id: string;
+  relation_type: string;
+  data_json: string;
+  created_at: number;
+};
+
+export type ArtifactRow = {
+  artifact_id: string;
+  trace_id: string;
+  node_id: string | null;
+  artifact_type: string;
+  content: string;
+  redaction_level: string;
+  metadata_json: string;
+  sha256: string;
+  created_at: number;
+};
+
+export function insertTrace(engine: StorageEngine, row: TraceRow): void {
+  engine.exec(
+    `INSERT INTO traces(
+      trace_id, workflow_id, actor, intent, tags_json, metadata_json, started_at, finished_at, status, outcome_json
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?);`,
+    [
+      row.trace_id,
+      row.workflow_id,
+      row.actor,
+      row.intent,
+      row.tags_json,
+      row.metadata_json,
+      row.started_at,
+      row.finished_at,
+      row.status,
+      row.outcome_json,
+    ]
+  );
+}
+
+export function insertNode(engine: StorageEngine, row: NodeRow): void {
+  engine.exec(
+    `INSERT INTO nodes(
+      node_id, trace_id, type, summary, data_json, confidence, metadata_json, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?);`,
+    [
+      row.node_id,
+      row.trace_id,
+      row.type,
+      row.summary,
+      row.data_json,
+      row.confidence,
+      row.metadata_json,
+      row.created_at,
+    ]
+  );
+}
+
+export function insertEdge(engine: StorageEngine, row: EdgeRow): void {
+  engine.exec(
+    `INSERT INTO edges(
+      edge_id, trace_id, from_node_id, to_node_id, relation_type, data_json, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?);`,
+    [
+      row.edge_id,
+      row.trace_id,
+      row.from_node_id,
+      row.to_node_id,
+      row.relation_type,
+      row.data_json,
+      row.created_at,
+    ]
+  );
+}
+
+export function insertArtifact(engine: StorageEngine, row: ArtifactRow): void {
+  engine.exec(
+    `INSERT INTO artifacts(
+      artifact_id, trace_id, node_id, artifact_type, content, redaction_level, metadata_json, sha256, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?);`,
+    [
+      row.artifact_id,
+      row.trace_id,
+      row.node_id,
+      row.artifact_type,
+      row.content,
+      row.redaction_level,
+      row.metadata_json,
+      row.sha256,
+      row.created_at,
+    ]
+  );
+}
+
+export function finishTrace(
+  engine: StorageEngine,
+  traceId: string,
+  finishedAt: number,
+  status: string | null,
+  outcomeJson: string | null
+): void {
+  engine.exec(
+    `UPDATE traces
+      SET finished_at = ?, status = ?, outcome_json = ?
+      WHERE trace_id = ?;`,
+    [finishedAt, status, outcomeJson, traceId]
+  );
+}
+
+export function getTrace(engine: StorageEngine, traceId: string): TraceRow | null {
+  return engine.queryOne<TraceRow>("SELECT * FROM traces WHERE trace_id = ?;", [traceId]);
+}
+
+export function getAllTraces(engine: StorageEngine): TraceRow[] {
+  return engine.queryAll<TraceRow>("SELECT * FROM traces ORDER BY started_at DESC;");
+}
+
+export function getNode(engine: StorageEngine, nodeId: string): NodeRow | null {
+  return engine.queryOne<NodeRow>("SELECT * FROM nodes WHERE node_id = ?;", [nodeId]);
+}
+
+export function getTraceNodes(engine: StorageEngine, traceId: string): NodeRow[] {
+  return engine.queryAll<NodeRow>("SELECT * FROM nodes WHERE trace_id = ? ORDER BY created_at ASC;", [traceId]);
+}
+
+export function getTraceEdges(engine: StorageEngine, traceId: string): EdgeRow[] {
+  return engine.queryAll<EdgeRow>("SELECT * FROM edges WHERE trace_id = ? ORDER BY created_at ASC;", [traceId]);
+}
+
+export function getTraceArtifacts(engine: StorageEngine, traceId: string): ArtifactRow[] {
+  return engine.queryAll<ArtifactRow>(
+    "SELECT * FROM artifacts WHERE trace_id = ? ORDER BY created_at ASC;",
+    [traceId]
+  );
+}
+
+export function getArtifactsForNodes(engine: StorageEngine, nodeIds: string[]): ArtifactRow[] {
+  if (nodeIds.length === 0) return [];
+  const placeholders = nodeIds.map(() => "?").join(",");
+  return engine.queryAll<ArtifactRow>(
+    `SELECT * FROM artifacts WHERE node_id IN (${placeholders}) ORDER BY created_at ASC;`,
+    nodeIds
+  );
+}
+
+export function searchNodes(
+  engine: StorageEngine,
+  opts: {
+    traceId?: string;
+    type?: string;
+    text?: string;
+    limit: number;
+    offset: number;
+  }
+): NodeRow[] {
+  if (opts.text && hasFts(engine)) {
+    const where: string[] = [];
+    const params: unknown[] = [];
+
+    if (opts.traceId) {
+      where.push("n.trace_id = ?");
+      params.push(opts.traceId);
+    }
+    if (opts.type) {
+      where.push("n.type = ?");
+      params.push(opts.type);
+    }
+
+    where.push("nodes_fts MATCH ?");
+    params.push(opts.text);
+
+    const clause = where.length ? `WHERE ${where.join(" AND ")}` : "";
+    const sql = `SELECT n.* FROM nodes n JOIN nodes_fts ON nodes_fts.rowid = n.rowid ${clause}\n      ORDER BY n.created_at DESC LIMIT ? OFFSET ?;`;
+    params.push(opts.limit, opts.offset);
+
+    return engine.queryAll<NodeRow>(sql, params);
+  }
+
+  const where: string[] = [];
+  const params: unknown[] = [];
+
+  if (opts.traceId) {
+    where.push("trace_id = ?");
+    params.push(opts.traceId);
+  }
+  if (opts.type) {
+    where.push("type = ?");
+    params.push(opts.type);
+  }
+  if (opts.text) {
+    where.push("summary LIKE ?");
+    params.push(`%${opts.text}%`);
+  }
+
+  const clause = where.length ? `WHERE ${where.join(" AND ")}` : "";
+  const sql = `SELECT * FROM nodes ${clause} ORDER BY created_at DESC LIMIT ? OFFSET ?;`;
+  params.push(opts.limit, opts.offset);
+
+  return engine.queryAll<NodeRow>(sql, params);
+}
+
+export function searchNodesForTraces(
+  engine: StorageEngine,
+  opts: {
+    traceIds: string[];
+    type?: string;
+    text?: string;
+    limit: number;
+    offset: number;
+  }
+): NodeRow[] {
+  if (opts.traceIds.length === 0) return [];
+
+  const placeholders = opts.traceIds.map(() => "?").join(",");
+
+  if (opts.text && hasFts(engine)) {
+    const where: string[] = [`n.trace_id IN (${placeholders})`];
+    const params: unknown[] = [...opts.traceIds];
+
+    if (opts.type) {
+      where.push("n.type = ?");
+      params.push(opts.type);
+    }
+
+    where.push("nodes_fts MATCH ?");
+    params.push(opts.text);
+
+    const clause = `WHERE ${where.join(" AND ")}`;
+    const sql = `SELECT n.* FROM nodes n JOIN nodes_fts ON nodes_fts.rowid = n.rowid ${clause}
+      ORDER BY n.created_at DESC LIMIT ? OFFSET ?;`;
+    params.push(opts.limit, opts.offset);
+
+    return engine.queryAll<NodeRow>(sql, params);
+  }
+
+  const where: string[] = [`trace_id IN (${placeholders})`];
+  const params: unknown[] = [...opts.traceIds];
+
+  if (opts.type) {
+    where.push("type = ?");
+    params.push(opts.type);
+  }
+  if (opts.text) {
+    where.push("summary LIKE ?");
+    params.push(`%${opts.text}%`);
+  }
+
+  const clause = `WHERE ${where.join(" AND ")}`;
+  const sql = `SELECT * FROM nodes ${clause} ORDER BY created_at DESC LIMIT ? OFFSET ?;`;
+  params.push(opts.limit, opts.offset);
+
+  return engine.queryAll<NodeRow>(sql, params);
+}
+
+const ftsCache = new WeakMap<StorageEngine, boolean>();
+
+function hasFts(engine: StorageEngine): boolean {
+  const cached = ftsCache.get(engine);
+  if (cached !== undefined) return cached;
+  const row = engine.queryOne<{ name: string }>(
+    "SELECT name FROM sqlite_master WHERE type='table' AND name='nodes_fts';"
+  );
+  const enabled = Boolean(row?.name);
+  ftsCache.set(engine, enabled);
+  return enabled;
+}

package/src/storage/sqljsEngine.ts

@@ -0,0 +1,207 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+import initSqlJs, { type Database, type SqlJsStatic } from "sql.js";
+
+import type { StorageEngine, TxFn } from "./engine.js";
+import { defaultMigrations, type Migration } from "./migrations.js";
+import { atomicWriteFile } from "../util/fs.js";
+
+export type SqlJsEngineOptions = {
+  dbPath?: string;
+  flushDebounceMs?: number;
+  locateFile?: (file: string) => string;
+  onLog?: (msg: string) => void;
+  migrations?: Migration[];
+};
+
+export class SqlJsEngine implements StorageEngine {
+  private SQL!: SqlJsStatic;
+  private db!: Database;
+  private dbPath: string;
+  private dirty = false;
+  private flushTimer: NodeJS.Timeout | null = null;
+  private flushDebounceMs: number;
+  private onLog: (msg: string) => void;
+  private locateFile?: (file: string) => string;
+  private migrations: Migration[];
+
+  constructor(opts: SqlJsEngineOptions = {}) {
+    const defaultDir = path.join(os.homedir(), ".decision-trace");
+    const defaultPath = path.join(defaultDir, "trace.db");
+    const require = createRequire(import.meta.url);
+    const wasmPath = require.resolve("sql.js/dist/sql-wasm.wasm");
+    const defaultLocateFile = (file: string) =>
+      file.endsWith(".wasm") ? wasmPath : file;
+
+    this.dbPath = opts.dbPath || process.env.TRACE_DB_PATH || defaultPath;
+    this.flushDebounceMs = opts.flushDebounceMs ?? 1000;
+    this.onLog = opts.onLog ?? (() => undefined);
+    this.locateFile = opts.locateFile ?? defaultLocateFile;
+    this.migrations = opts.migrations ?? defaultMigrations;
+  }
+
+  async init(): Promise<void> {
+    fs.mkdirSync(path.dirname(this.dbPath), { recursive: true });
+
+    this.SQL = await initSqlJs({ locateFile: this.locateFile });
+
+    let dbBytes: Uint8Array | undefined;
+    if (fs.existsSync(this.dbPath)) {
+      const buf = fs.readFileSync(this.dbPath);
+      dbBytes = new Uint8Array(buf);
+      this.onLog(`Loaded DB from ${this.dbPath} (${buf.length} bytes)`);
+    } else {
+      this.onLog(`Creating new DB at ${this.dbPath}`);
+    }
+
+    this.db = new this.SQL.Database(dbBytes);
+
+    try {
+      this.exec("PRAGMA foreign_keys = ON;");
+      this.exec("PRAGMA journal_mode = WAL;");
+      this.exec("PRAGMA synchronous = NORMAL;");
+      this.exec("PRAGMA temp_store = MEMORY;");
+    } catch {
+      // Ignore pragma failures.
+    }
+
+    this.applyMigrations();
+    this.installShutdownHooks();
+
+    await this.flushNow();
+  }
+
+  transaction<T>(fn: TxFn<T>): T {
+    this.exec("BEGIN;");
+    try {
+      const out = fn();
+      this.exec("COMMIT;");
+      this.markDirty();
+      return out;
+    } catch (err) {
+      this.exec("ROLLBACK;");
+      throw err;
+    }
+  }
+
+  exec(sql: string, params?: unknown[]): void {
+    if (!params || params.length === 0) {
+      this.db.exec(sql);
+      return;
+    }
+    const stmt = this.db.prepare(sql);
+    try {
+      stmt.bind(params as any[]);
+      while (stmt.step()) {
+        // consume
+      }
+    } finally {
+      stmt.free();
+    }
+  }
+
+  queryAll<T = unknown>(sql: string, params?: unknown[]): T[] {
+    const stmt = this.db.prepare(sql);
+    try {
+      if (params) stmt.bind(params as any[]);
+      const rows: T[] = [];
+      while (stmt.step()) {
+        rows.push(stmt.getAsObject() as T);
+      }
+      return rows;
+    } finally {
+      stmt.free();
+    }
+  }
+
+  queryOne<T = unknown>(sql: string, params?: unknown[]): T | null {
+    const rows = this.queryAll<T>(sql, params);
+    return rows.length ? rows[0] : null;
+  }
+
+  async flushIfDirty(): Promise<void> {
+    if (!this.dirty) return;
+    await this.flushNow();
+  }
+
+  async flushNow(): Promise<void> {
+    const bytes = this.db.export();
+    const buf = Buffer.from(bytes);
+
+    atomicWriteFile(this.dbPath, buf);
+
+    this.dirty = false;
+    this.onLog(`Flushed DB to ${this.dbPath} (${buf.length} bytes)`);
+  }
+
+  private markDirty(): void {
+    this.dirty = true;
+    if (this.flushTimer) return;
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      void this.flushIfDirty();
+    }, this.flushDebounceMs);
+  }
+
+  private applyMigrations(): void {
+    this.exec(`
+      CREATE TABLE IF NOT EXISTS schema_version (
+        version INTEGER NOT NULL
+      );
+    `);
+
+    const row = this.queryOne<{ version: number }>(
+      "SELECT version FROM schema_version LIMIT 1;"
+    );
+    const current = row?.version ?? 0;
+
+    let version = current;
+    for (const migration of this.migrations) {
+      if (migration.version <= version) continue;
+      this.onLog(`Applying migration v${migration.version}`);
+      try {
+        this.exec(migration.sql);
+      } catch (err) {
+        if (migration.optional) {
+          this.onLog(
+            `Migration v${migration.version} failed (continuing): ${(err as Error).message}`
+          );
+          continue;
+        }
+        throw err;
+      }
+      version = migration.version;
+      if (current === 0) {
+        this.exec("DELETE FROM schema_version;");
+        this.exec("INSERT INTO schema_version(version) VALUES (?);", [version]);
+      } else {
+        this.exec("UPDATE schema_version SET version=?;", [version]);
+      }
+    }
+  }
+
+  private installShutdownHooks(): void {
+    const flushAndExit = async (signal: string) => {
+      this.onLog(`Received ${signal}; flushing DB...`);
+      try {
+        await this.flushIfDirty();
+      } finally {
+        process.exit(0);
+      }
+    };
+
+    process.once("SIGINT", () => void flushAndExit("SIGINT"));
+    process.once("SIGTERM", () => void flushAndExit("SIGTERM"));
+
+    process.once("beforeExit", () => {
+      try {
+        void this.flushIfDirty();
+      } catch {
+        // Ignore shutdown flush errors.
+      }
+    });
+  }
+}

package/src/util/fs.ts

@@ -0,0 +1,15 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function mkdirp(dir: string): void {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+export function atomicWriteFile(targetPath: string, data: Buffer): void {
+  const dir = path.dirname(targetPath);
+  mkdirp(dir);
+
+  const tmpPath = `${targetPath}.tmp`;
+  fs.writeFileSync(tmpPath, data);
+  fs.renameSync(tmpPath, targetPath);
+}

package/src/util/hashing.ts

@@ -0,0 +1,5 @@
+import crypto from "node:crypto";
+
+export function sha256(text: string): string {
+  return crypto.createHash("sha256").update(text, "utf8").digest("hex");
+}

package/src/util/ids.ts

@@ -0,0 +1,8 @@
+import crypto from "node:crypto";
+
+export function newId(): string {
+  if (typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return crypto.randomBytes(16).toString("hex");
+}

package/src/util/redact.ts

@@ -0,0 +1,26 @@
+const DEFAULT_PATTERNS: RegExp[] = [
+  /sk-[A-Za-z0-9_-]{16,}/g,
+  /AIza[0-9A-Za-z_-]{35}/g,
+  /(?<=Bearer\s)[A-Za-z0-9._-]+/g,
+  /(?<=apikey=)[A-Za-z0-9._-]+/gi,
+];
+
+export type RedactionResult = {
+  redacted: string;
+  wasRedacted: boolean;
+};
+
+export function redactSecrets(input: string, patterns: RegExp[] = DEFAULT_PATTERNS): RedactionResult {
+  let redacted = input;
+  let wasRedacted = false;
+
+  for (const pattern of patterns) {
+    const next = redacted.replace(pattern, "[REDACTED]");
+    if (next !== redacted) {
+      wasRedacted = true;
+      redacted = next;
+    }
+  }
+
+  return { redacted, wasRedacted };
+}

package/tests/explain.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import { explainDecision } from "../src/explain/explain.js";
+import type { ArtifactRow, EdgeRow, NodeRow } from "../src/storage/queries.js";
+
+const nodes: NodeRow[] = [
+  {
+    node_id: "assumption-1",
+    trace_id: "t1",
+    type: "Assumption",
+    summary: "Assume X",
+    data_json: "{}",
+    confidence: null,
+    metadata_json: "{}",
+    created_at: 1,
+  },
+  {
+    node_id: "decision-1",
+    trace_id: "t1",
+    type: "Decision",
+    summary: "Decide Y",
+    data_json: "{}",
+    confidence: null,
+    metadata_json: "{}",
+    created_at: 2,
+  },
+  {
+    node_id: "outcome-1",
+    trace_id: "t1",
+    type: "Outcome",
+    summary: "Outcome Z",
+    data_json: "{}",
+    confidence: null,
+    metadata_json: "{}",
+    created_at: 3,
+  },
+];
+
+const edges: EdgeRow[] = [
+  {
+    edge_id: "e1",
+    trace_id: "t1",
+    from_node_id: "assumption-1",
+    to_node_id: "decision-1",
+    relation_type: "justified_by",
+    data_json: "{}",
+    created_at: 1,
+  },
+  {
+    edge_id: "e2",
+    trace_id: "t1",
+    from_node_id: "decision-1",
+    to_node_id: "outcome-1",
+    relation_type: "causes",
+    data_json: "{}",
+    created_at: 2,
+  },
+];
+
+const artifacts: ArtifactRow[] = [
+  {
+    artifact_id: "artifact-1",
+    trace_id: "t1",
+    node_id: "decision-1",
+    artifact_type: "log",
+    content: "decision detail",
+    redaction_level: "internal",
+    metadata_json: "{}",
+    sha256: "abc",
+    created_at: 2,
+  },
+];
+
+describe("explainDecision", () => {
+  it("groups upstream nodes and finds outcome", () => {
+    const explanation = explainDecision("decision-1", nodes, edges, artifacts, 3);
+
+    expect(explanation.assumptions).toHaveLength(1);
+    expect(explanation.outcome?.node_id).toBe("outcome-1");
+    expect(explanation.artifacts).toHaveLength(1);
+  });
+});