@h-rig/runtime 0.0.6-alpha.0

package/dist/src/control-plane/memory-sync/db.js

@@ -0,0 +1,753 @@
+// @bun
+// packages/runtime/src/control-plane/memory-sync/db.ts
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "fs";
+import { dirname } from "path";
+
+// packages/runtime/src/control-plane/memory-sync/types.ts
+var NO_MATCH_RETRIEVAL_CANONICAL_KEY = "__memory_recall__:none";
+
+// packages/runtime/src/control-plane/memory-sync/db.ts
+var SCHEMA_STATEMENTS = [
+  `CREATE TABLE IF NOT EXISTS memory_events (
+    event_id TEXT PRIMARY KEY,
+    event_type TEXT NOT NULL,
+    canonical_key TEXT NOT NULL,
+    summary TEXT,
+    kind TEXT,
+    category TEXT,
+    confidence REAL,
+    source_run_id TEXT,
+    source_task_id TEXT,
+    branch TEXT,
+    source_canonical_key TEXT,
+    replacement_canonical_key TEXT,
+    retrieval_query TEXT,
+    retrieval_rank INTEGER,
+    feedback_outcome TEXT,
+    details_json TEXT,
+    created_at TEXT NOT NULL
+  )`,
+  `CREATE TABLE IF NOT EXISTS memory_items (
+    canonical_key TEXT PRIMARY KEY,
+    summary TEXT NOT NULL,
+    kind TEXT,
+    category TEXT,
+    status TEXT NOT NULL,
+    confidence REAL NOT NULL,
+    source_run_id TEXT,
+    source_task_id TEXT,
+    branch TEXT,
+    details_json TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    last_event_id TEXT NOT NULL,
+    superseded_by TEXT,
+    embedding TEXT
+  )`,
+  `CREATE TABLE IF NOT EXISTS memory_links (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    from_key TEXT NOT NULL,
+    to_key TEXT NOT NULL,
+    relation TEXT NOT NULL,
+    source_event_id TEXT NOT NULL,
+    created_at TEXT NOT NULL
+  )`,
+  `CREATE TABLE IF NOT EXISTS task_runs (
+    run_id TEXT PRIMARY KEY,
+    task_id TEXT,
+    branch TEXT,
+    first_event_id TEXT,
+    last_event_id TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+  )`,
+  `CREATE TABLE IF NOT EXISTS retrieval_feedback (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    canonical_key TEXT NOT NULL,
+    outcome TEXT NOT NULL,
+    retrieval_rank INTEGER,
+    source_run_id TEXT,
+    source_task_id TEXT,
+    query_text TEXT,
+    source_event_id TEXT NOT NULL,
+    created_at TEXT NOT NULL
+  )`
+];
+var MEMORY_EVENT_COLUMNS = [
+  ["summary", "TEXT"],
+  ["kind", "TEXT"],
+  ["category", "TEXT"],
+  ["confidence", "REAL"],
+  ["source_run_id", "TEXT"],
+  ["source_task_id", "TEXT"],
+  ["branch", "TEXT"],
+  ["source_canonical_key", "TEXT"],
+  ["replacement_canonical_key", "TEXT"],
+  ["retrieval_query", "TEXT"],
+  ["retrieval_rank", "INTEGER"],
+  ["feedback_outcome", "TEXT"],
+  ["details_json", "TEXT"]
+];
+var MEMORY_ITEM_COLUMNS = [
+  ["kind", "TEXT"],
+  ["category", "TEXT"],
+  ["branch", "TEXT"],
+  ["details_json", "TEXT"],
+  ["superseded_by", "TEXT"],
+  ["embedding", "TEXT"]
+];
+function jsonText(value) {
+  if (value == null) {
+    return null;
+  }
+  return JSON.stringify(value);
+}
+function parseJsonRecord(value) {
+  if (typeof value !== "string" || value.length === 0) {
+    return null;
+  }
+  return JSON.parse(value);
+}
+function parseEmbedding(value) {
+  if (typeof value !== "string" || value.length === 0) {
+    return null;
+  }
+  return JSON.parse(value);
+}
+function rowString(row, key) {
+  const value = row[key];
+  return value == null ? null : String(value);
+}
+function eventSummary(event) {
+  return "summary" in event ? event.summary : null;
+}
+function eventKind(event) {
+  return "kind" in event ? event.kind : null;
+}
+function eventCategory(event) {
+  return "category" in event ? event.category ?? null : null;
+}
+function eventConfidence(event) {
+  return "confidence" in event ? event.confidence : null;
+}
+function eventDetails(event) {
+  return "details" in event ? event.details ?? null : null;
+}
+function eventSourceCanonicalKey(event) {
+  return "sourceCanonicalKey" in event ? event.sourceCanonicalKey : null;
+}
+function eventReplacementCanonicalKey(event) {
+  return "replacementCanonicalKey" in event ? event.replacementCanonicalKey : null;
+}
+function eventRetrievalQuery(event) {
+  return "retrievalQuery" in event ? event.retrievalQuery ?? null : null;
+}
+function eventRetrievalRank(event) {
+  return "retrievalRank" in event ? event.retrievalRank : null;
+}
+function eventFeedbackOutcome(event) {
+  return "feedbackOutcome" in event ? event.feedbackOutcome : null;
+}
+function normalizeStatement(statement, args) {
+  if (typeof statement === "string") {
+    return { sql: statement, args };
+  }
+  return {
+    sql: statement.sql,
+    args: statement.args ?? args
+  };
+}
+function normalizeBindings(bindings) {
+  return (bindings ?? []).map((binding) => binding === undefined ? null : binding);
+}
+function statementVerb(sql) {
+  const match = sql.trim().match(/^[A-Za-z]+/);
+  return match ? match[0].toUpperCase() : "";
+}
+function isMutationStatement(sql) {
+  return new Set([
+    "ALTER",
+    "ATTACH",
+    "BEGIN",
+    "COMMIT",
+    "CREATE",
+    "DELETE",
+    "DETACH",
+    "DROP",
+    "END",
+    "INSERT",
+    "REINDEX",
+    "RELEASE",
+    "REPLACE",
+    "ROLLBACK",
+    "SAVEPOINT",
+    "UPDATE",
+    "VACUUM"
+  ]).has(statementVerb(sql));
+}
+function executeSqlite(sqlite, statement, args) {
+  const normalized = normalizeStatement(statement, args);
+  const bindings = normalizeBindings(normalized.args);
+  if (isMutationStatement(normalized.sql)) {
+    const result = bindings.length > 0 ? sqlite.run(normalized.sql, ...bindings) : sqlite.run(normalized.sql);
+    return {
+      rows: [],
+      rowsAffected: Number(result.changes)
+    };
+  }
+  const query = sqlite.query(normalized.sql);
+  const rows = bindings.length > 0 ? query.all(...bindings) : query.all();
+  return {
+    rows,
+    rowsAffected: 0
+  };
+}
+function createTransaction(sqlite, mode) {
+  sqlite.run(mode === "write" ? "BEGIN IMMEDIATE" : "BEGIN");
+  let active = true;
+  return {
+    async execute(statement, args) {
+      if (!active) {
+        throw new Error("memory transaction is closed");
+      }
+      return executeSqlite(sqlite, statement, args);
+    },
+    async commit() {
+      if (!active) {
+        return;
+      }
+      sqlite.run("COMMIT");
+      active = false;
+    },
+    async rollback() {
+      if (!active) {
+        return;
+      }
+      sqlite.run("ROLLBACK");
+      active = false;
+    },
+    close() {
+      if (!active) {
+        return;
+      }
+      try {
+        sqlite.run("ROLLBACK");
+      } catch {} finally {
+        active = false;
+      }
+    }
+  };
+}
+function createMemoryDbClient(sqlite) {
+  return {
+    async execute(statement, args) {
+      return executeSqlite(sqlite, statement, args);
+    },
+    async transaction(mode) {
+      return createTransaction(sqlite, mode);
+    },
+    close() {
+      sqlite.close();
+    }
+  };
+}
+async function listColumns(executor, tableName) {
+  const result = await executor.execute(`PRAGMA table_info(${tableName})`);
+  return new Set(result.rows.map((row) => String(row.name)));
+}
+async function ensureColumns(executor, tableName, columns) {
+  const existing = await listColumns(executor, tableName);
+  for (const [columnName, definition] of columns) {
+    if (!existing.has(columnName)) {
+      await executor.execute(`ALTER TABLE ${tableName} ADD COLUMN ${columnName} ${definition}`);
+    }
+  }
+}
+async function ensureSchema(db) {
+  for (const statement of SCHEMA_STATEMENTS) {
+    await db.client.execute(statement);
+  }
+  await ensureColumns(db.client, "memory_events", MEMORY_EVENT_COLUMNS);
+  await ensureColumns(db.client, "memory_items", MEMORY_ITEM_COLUMNS);
+}
+function toMemoryItemRow(row) {
+  return {
+    canonicalKey: String(row.canonical_key),
+    summary: String(row.summary),
+    kind: rowString(row, "kind"),
+    category: rowString(row, "category"),
+    status: String(row.status),
+    confidence: Number(row.confidence),
+    sourceRunId: rowString(row, "source_run_id"),
+    sourceTaskId: rowString(row, "source_task_id"),
+    branch: rowString(row, "branch"),
+    details: parseJsonRecord(row.details_json),
+    createdAt: String(row.created_at),
+    updatedAt: String(row.updated_at),
+    lastEventId: String(row.last_event_id),
+    supersededBy: rowString(row, "superseded_by"),
+    embedding: parseEmbedding(row.embedding)
+  };
+}
+function toMemoryEventRow(row) {
+  return {
+    eventId: String(row.event_id),
+    eventType: String(row.event_type),
+    canonicalKey: String(row.canonical_key),
+    summary: rowString(row, "summary") ?? "",
+    createdAt: String(row.created_at)
+  };
+}
+async function hasMemoryItem(executor, canonicalKey) {
+  const result = await executor.execute({
+    sql: "SELECT 1 AS present FROM memory_items WHERE canonical_key = ? LIMIT 1",
+    args: [canonicalKey]
+  });
+  return result.rows.length > 0;
+}
+async function assertMemoryItemExists(executor, canonicalKey, errorPrefix) {
+  if (!await hasMemoryItem(executor, canonicalKey)) {
+    throw new Error(`${errorPrefix}: unknown memory ${canonicalKey}`);
+  }
+}
+async function upsertTaskRun(executor, event) {
+  if (!event.sourceRunId) {
+    return;
+  }
+  await executor.execute({
+    sql: `
+      INSERT INTO task_runs (
+        run_id,
+        task_id,
+        branch,
+        first_event_id,
+        last_event_id,
+        created_at,
+        updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(run_id) DO UPDATE SET
+        task_id = COALESCE(excluded.task_id, task_runs.task_id),
+        branch = COALESCE(excluded.branch, task_runs.branch),
+        last_event_id = excluded.last_event_id,
+        updated_at = excluded.updated_at
+    `,
+    args: [
+      event.sourceRunId,
+      event.sourceTaskId ?? null,
+      event.branch ?? null,
+      event.eventId,
+      event.eventId,
+      event.createdAt,
+      event.createdAt
+    ]
+  });
+}
+async function insertEventRow(executor, event) {
+  await executor.execute({
+    sql: `
+      INSERT INTO memory_events (
+        event_id,
+        event_type,
+        canonical_key,
+        summary,
+        kind,
+        category,
+        confidence,
+        source_run_id,
+        source_task_id,
+        branch,
+        source_canonical_key,
+        replacement_canonical_key,
+        retrieval_query,
+        retrieval_rank,
+        feedback_outcome,
+        details_json,
+        created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `,
+    args: [
+      event.eventId,
+      event.eventType,
+      event.canonicalKey,
+      eventSummary(event),
+      eventKind(event),
+      eventCategory(event),
+      eventConfidence(event),
+      event.sourceRunId ?? null,
+      event.sourceTaskId ?? null,
+      event.branch ?? null,
+      eventSourceCanonicalKey(event),
+      eventReplacementCanonicalKey(event),
+      eventRetrievalQuery(event),
+      eventRetrievalRank(event),
+      eventFeedbackOutcome(event),
+      jsonText(eventDetails(event)),
+      event.createdAt
+    ]
+  });
+}
+async function upsertProjectedMemory(executor, event, status = "active") {
+  await executor.execute({
+    sql: `
+      INSERT INTO memory_items (
+        canonical_key,
+        summary,
+        kind,
+        category,
+        status,
+        confidence,
+        source_run_id,
+        source_task_id,
+        branch,
+        details_json,
+        created_at,
+        updated_at,
+        last_event_id,
+        superseded_by,
+        embedding
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)
+      ON CONFLICT(canonical_key) DO UPDATE SET
+        summary = excluded.summary,
+        kind = excluded.kind,
+        category = excluded.category,
+        status = excluded.status,
+        confidence = COALESCE(excluded.confidence, memory_items.confidence),
+        source_run_id = COALESCE(excluded.source_run_id, memory_items.source_run_id),
+        source_task_id = COALESCE(excluded.source_task_id, memory_items.source_task_id),
+        branch = COALESCE(excluded.branch, memory_items.branch),
+        details_json = COALESCE(excluded.details_json, memory_items.details_json),
+        updated_at = excluded.updated_at,
+        last_event_id = excluded.last_event_id,
+        superseded_by = excluded.superseded_by,
+        embedding = excluded.embedding
+    `,
+    args: [
+      event.canonicalKey,
+      eventSummary(event),
+      eventKind(event),
+      eventCategory(event),
+      status,
+      eventConfidence(event) ?? 0,
+      event.sourceRunId ?? null,
+      event.sourceTaskId ?? null,
+      event.branch ?? null,
+      jsonText(eventDetails(event)),
+      event.createdAt,
+      event.createdAt,
+      event.eventId,
+      eventReplacementCanonicalKey(event)
+    ]
+  });
+}
+async function insertMemoryLink(executor, fromKey, toKey, relation, event) {
+  await executor.execute({
+    sql: `
+      INSERT INTO memory_links (from_key, to_key, relation, source_event_id, created_at)
+      VALUES (?, ?, ?, ?, ?)
+    `,
+    args: [fromKey, toKey, relation, event.eventId, event.createdAt]
+  });
+}
+async function markSuperseded(executor, event) {
+  const result = await executor.execute({
+    sql: `
+      UPDATE memory_items
+      SET
+        status = 'superseded',
+        superseded_by = ?,
+        updated_at = ?,
+        last_event_id = ?
+      WHERE canonical_key = ?
+    `,
+    args: [eventReplacementCanonicalKey(event), event.createdAt, event.eventId, event.canonicalKey]
+  });
+  if ((result.rowsAffected ?? 0) === 0) {
+    throw new Error(`cannot supersede unknown memory ${event.canonicalKey}`);
+  }
+  if (eventReplacementCanonicalKey(event)) {
+    await insertMemoryLink(executor, event.canonicalKey, eventReplacementCanonicalKey(event), "superseded_by", event);
+  }
+}
+async function activeMemoryItem(executor, canonicalKey) {
+  const result = await executor.execute({
+    sql: `
+      SELECT
+        canonical_key,
+        summary,
+        kind,
+        category,
+        status,
+        confidence,
+        source_run_id,
+        source_task_id,
+        branch,
+        details_json,
+        created_at,
+        updated_at,
+        last_event_id,
+        superseded_by,
+        embedding
+      FROM memory_items
+      WHERE canonical_key = ?
+      LIMIT 1
+    `,
+    args: [canonicalKey]
+  });
+  const row = result.rows[0];
+  return row ? toMemoryItemRow(row) : null;
+}
+async function markRetracted(executor, event) {
+  const result = await executor.execute({
+    sql: `
+      UPDATE memory_items
+      SET
+        status = 'retracted',
+        updated_at = ?,
+        last_event_id = ?
+      WHERE canonical_key = ?
+    `,
+    args: [event.createdAt, event.eventId, event.canonicalKey]
+  });
+  if ((result.rowsAffected ?? 0) === 0) {
+    throw new Error(`cannot retract unknown memory ${event.canonicalKey}`);
+  }
+}
+async function recordRetrievalFeedback(executor, event) {
+  await executor.execute({
+    sql: `
+      INSERT INTO retrieval_feedback (
+        canonical_key,
+        outcome,
+        retrieval_rank,
+        source_run_id,
+        source_task_id,
+        query_text,
+        source_event_id,
+        created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `,
+    args: [
+      event.canonicalKey,
+      eventFeedbackOutcome(event) ?? "ignored",
+      eventRetrievalRank(event),
+      event.sourceRunId ?? null,
+      event.sourceTaskId ?? null,
+      eventRetrievalQuery(event),
+      event.eventId,
+      event.createdAt
+    ]
+  });
+}
+async function applyReinforcement(executor, event) {
+  const existing = await activeMemoryItem(executor, event.canonicalKey);
+  if (!existing) {
+    throw new Error(`cannot reinforce unknown memory ${event.canonicalKey}`);
+  }
+  if (existing.status !== "active") {
+    throw new Error(`cannot reinforce non-active memory ${event.canonicalKey}`);
+  }
+  const result = await executor.execute({
+    sql: `
+      UPDATE memory_items
+      SET
+        status = 'active',
+        confidence = ?,
+        source_run_id = COALESCE(?, source_run_id),
+        source_task_id = COALESCE(?, source_task_id),
+        branch = COALESCE(?, branch),
+        updated_at = ?,
+        last_event_id = ?,
+        superseded_by = NULL
+      WHERE canonical_key = ?
+    `,
+    args: [
+      eventConfidence(event),
+      event.sourceRunId ?? null,
+      event.sourceTaskId ?? null,
+      event.branch ?? null,
+      event.createdAt,
+      event.eventId,
+      event.canonicalKey
+    ]
+  });
+  if ((result.rowsAffected ?? 0) === 0) {
+    throw new Error(`cannot reinforce unknown memory ${event.canonicalKey}`);
+  }
+}
+async function validateEventTargets(executor, event) {
+  switch (event.eventType) {
+    case "observed":
+      return;
+    case "promoted":
+    case "corrected":
+      await assertMemoryItemExists(executor, event.sourceCanonicalKey, `cannot ${event.eventType}`);
+      return;
+    case "superseded":
+      await assertMemoryItemExists(executor, event.replacementCanonicalKey, "cannot supersede");
+      await assertMemoryItemExists(executor, event.canonicalKey, "cannot supersede");
+      return;
+    case "retracted":
+    case "feedback_recorded":
+      await assertMemoryItemExists(executor, event.canonicalKey, `cannot ${event.eventType}`);
+      return;
+    case "reinforced":
+      await assertMemoryItemExists(executor, event.canonicalKey, "cannot reinforce");
+      return;
+    case "retrieved":
+      if (event.retrievalRank === 0 && event.canonicalKey === NO_MATCH_RETRIEVAL_CANONICAL_KEY) {
+        return;
+      }
+      await assertMemoryItemExists(executor, event.canonicalKey, `cannot ${event.eventType}`);
+      return;
+    default: {
+      const _exhaustive = event;
+      return _exhaustive;
+    }
+  }
+}
+async function openMemoryDb(dbPath) {
+  mkdirSync(dirname(dbPath), { recursive: true });
+  const sqlite = new Database(dbPath, { create: true, strict: true });
+  const client = createMemoryDbClient(sqlite);
+  const db = {
+    path: dbPath,
+    client,
+    async close() {
+      client.close();
+    }
+  };
+  await ensureSchema(db);
+  return db;
+}
+async function applyMemoryEvent(db, event) {
+  const transaction = await db.client.transaction("write");
+  try {
+    await validateEventTargets(transaction, event);
+    await insertEventRow(transaction, event);
+    await upsertTaskRun(transaction, event);
+    switch (event.eventType) {
+      case "observed":
+        await upsertProjectedMemory(transaction, event, "active");
+        break;
+      case "promoted":
+        await upsertProjectedMemory(transaction, event, "active");
+        if (event.sourceCanonicalKey) {
+          await insertMemoryLink(transaction, event.canonicalKey, event.sourceCanonicalKey, "promoted_from", event);
+        }
+        break;
+      case "corrected":
+        await upsertProjectedMemory(transaction, event, "active");
+        if (event.sourceCanonicalKey) {
+          await insertMemoryLink(transaction, event.canonicalKey, event.sourceCanonicalKey, "corrected_from", event);
+        }
+        break;
+      case "superseded":
+        await markSuperseded(transaction, event);
+        break;
+      case "retracted":
+        await markRetracted(transaction, event);
+        break;
+      case "reinforced":
+        await applyReinforcement(transaction, event);
+        break;
+      case "retrieved":
+        break;
+      case "feedback_recorded":
+        await recordRetrievalFeedback(transaction, event);
+        break;
+    }
+    await transaction.commit();
+  } catch (error) {
+    await transaction.rollback();
+    throw error;
+  } finally {
+    transaction.close();
+  }
+}
+async function setMemoryItemEmbedding(db, canonicalKey, embedding) {
+  await db.client.execute({
+    sql: `
+      UPDATE memory_items
+      SET embedding = ?
+      WHERE canonical_key = ?
+    `,
+    args: [JSON.stringify(embedding), canonicalKey]
+  });
+}
+async function getMemoryItemByKey(db, canonicalKey) {
+  const result = await db.client.execute({
+    sql: `
+      SELECT
+        canonical_key,
+        summary,
+        kind,
+        category,
+        status,
+        confidence,
+        source_run_id,
+        source_task_id,
+        branch,
+        details_json,
+        created_at,
+        updated_at,
+        last_event_id,
+        superseded_by,
+        embedding
+      FROM memory_items
+      WHERE canonical_key = ?
+      LIMIT 1
+    `,
+    args: [canonicalKey]
+  });
+  const row = result.rows[0];
+  return row ? toMemoryItemRow(row) : null;
+}
+async function listActiveMemoryItems(db) {
+  const result = await db.client.execute(`
+    SELECT
+      canonical_key,
+      summary,
+      kind,
+      category,
+      status,
+      confidence,
+      source_run_id,
+      source_task_id,
+      branch,
+      details_json,
+      created_at,
+      updated_at,
+      last_event_id,
+      superseded_by,
+      embedding
+    FROM memory_items
+    WHERE status = 'active'
+    ORDER BY canonical_key
+  `);
+  return result.rows.map((row) => toMemoryItemRow(row));
+}
+async function hasMemoryEvent(db, eventId) {
+  const result = await db.client.execute({
+    sql: "SELECT 1 AS present FROM memory_events WHERE event_id = ? LIMIT 1",
+    args: [eventId]
+  });
+  return result.rows.length > 0;
+}
+async function listMemoryEvents(db) {
+  const result = await db.client.execute(`
+    SELECT event_id, event_type, canonical_key, summary, created_at
+    FROM memory_events
+    ORDER BY created_at, event_id
+  `);
+  return result.rows.map((row) => toMemoryEventRow(row));
+}
+export {
+  setMemoryItemEmbedding,
+  openMemoryDb,
+  listMemoryEvents,
+  listActiveMemoryItems,
+  hasMemoryEvent,
+  getMemoryItemByKey,
+  applyMemoryEvent
+};