@equationalapplications/core-llm-wiki 4.6.0 → 4.7.0

package/dist/index.mjs

@@ -62,6 +62,19 @@ async function setupDatabase(db, prefix) {
       key TEXT PRIMARY KEY,
       value TEXT NOT NULL
     );
+
+    CREATE TABLE IF NOT EXISTS ${prefix}outbox (
+      id TEXT PRIMARY KEY,
+      entity_id TEXT NOT NULL,
+      table_name TEXT NOT NULL,
+      record_id TEXT NOT NULL,
+      operation TEXT NOT NULL,
+      payload TEXT NOT NULL,
+      created_at INTEGER NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS ${prefix}outbox_entity_id_created_at
+      ON ${prefix}outbox (entity_id, created_at);
   `);
 }
 
@@ -77,8 +90,8 @@ var MIGRATIONS = [
     version: 2,
     description: "Remove FTS5; add embedding column for semantic retrieval",
     run: async (db, prefix) => {
-      await db.withTransactionAsync(async () => {
-        await db.execAsync(`
+      await db.withTransactionAsync(async (tx) => {
+        await tx.execAsync(`
           DROP TRIGGER IF EXISTS ${prefix}entries_ai;
           DROP TRIGGER IF EXISTS ${prefix}entries_ad;
           DROP TRIGGER IF EXISTS ${prefix}entries_au;
@@ -106,6 +119,25 @@ var MIGRATIONS = [
         );
       }
     }
+  },
+  {
+    version: 4,
+    description: "Create outbox table for change data capture",
+    run: async (db, prefix) => {
+      await db.execAsync(`
+        CREATE TABLE IF NOT EXISTS ${prefix}outbox (
+          id TEXT PRIMARY KEY,
+          entity_id TEXT NOT NULL,
+          table_name TEXT NOT NULL,
+          record_id TEXT NOT NULL,
+          operation TEXT NOT NULL,
+          payload TEXT NOT NULL,
+          created_at INTEGER NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS ${prefix}outbox_entity_id_created_at
+          ON ${prefix}outbox (entity_id, created_at);
+      `);
+    }
   }
 ];
 for (let i = 1; i < MIGRATIONS.length; i++) {
@@ -139,6 +171,1249 @@ var PrunePartialFailureError = class extends Error {
   }
 };
 
+// src/repositories/BaseRepository.ts
+var BaseRepository = class {
+  constructor(db, prefix) {
+    this.db = db;
+    this.prefix = prefix;
+  }
+  /**
+   * Return the DB executor for a given transaction handle.
+   * If tx is provided, use it; otherwise fall back to this.db.
+   */
+  getExecutor(tx) {
+    return tx ?? this.db;
+  }
+};
+
+// src/repositories/EntryRepository.ts
+function mapRowToFact(row) {
+  const tags = (() => {
+    if (Array.isArray(row.tags)) return row.tags;
+    try {
+      const p = JSON.parse(row.tags);
+      if (Array.isArray(p)) return p;
+    } catch {
+    }
+    return [];
+  })();
+  return {
+    id: row.id,
+    entity_id: row.entity_id,
+    title: row.title,
+    body: row.body,
+    tags,
+    confidence: row.confidence,
+    source_type: row.source_type,
+    source_hash: row.source_hash ?? null,
+    source_ref: row.source_ref ?? null,
+    created_at: Number(row.created_at),
+    updated_at: Number(row.updated_at),
+    last_accessed_at: row.last_accessed_at === null || row.last_accessed_at === void 0 ? null : Number(row.last_accessed_at),
+    deleted_at: row.deleted_at != null ? Number(row.deleted_at) : null,
+    access_count: Number(row.access_count ?? 0)
+  };
+}
+var EntryRepository = class extends BaseRepository {
+  constructor(db, prefix, outbox) {
+    super(db, prefix);
+    this.outbox = outbox;
+    this.chunkSize = 500;
+  }
+  /**
+   * Fetch facts by IDs, optionally scoped to entity IDs.
+   * Returns facts in the order of the input IDs (first match wins).
+   */
+  async findByIds(ids, scopedEntityIds, tx) {
+    const executor = this.getExecutor(tx);
+    const rows = [];
+    const entityClause = scopedEntityIds && scopedEntityIds.length > 0 ? ` AND entity_id IN (${scopedEntityIds.map(() => "?").join(",")})` : "";
+    const entityParams = scopedEntityIds ?? [];
+    for (let i = 0; i < ids.length; i += this.chunkSize) {
+      const chunk = ids.slice(i, i + this.chunkSize);
+      const placeholders = chunk.map(() => "?").join(",");
+      const chunkRows = await executor.getAllAsync(
+        `SELECT * FROM ${this.prefix}entries WHERE id IN (${placeholders})${entityClause} AND deleted_at IS NULL`,
+        [...chunk, ...entityParams]
+      );
+      rows.push(...chunkRows);
+    }
+    const byId = new Map(rows.map((r) => [r.id, r]));
+    return ids.map((id) => byId.get(id)).filter((r) => r !== void 0).map(mapRowToFact);
+  }
+  /**
+   * Upsert a WikiFact. Nullable fields set to null when fact value is null.
+   * Returns { changes, lastInsertRowId }.
+   * `tx` is REQUIRED to ensure atomic outbox staging.
+   */
+  async upsert(fact, tx) {
+    const executor = this.getExecutor(tx);
+    const now = Date.now();
+    const tagsJson = JSON.stringify(fact.tags);
+    const embeddingBlob = this.normalizeEmbeddingBlob(fact.embedding_blob);
+    const existingRow = await executor.getFirstAsync(
+      `SELECT id FROM ${this.prefix}entries WHERE id = ?`,
+      [fact.id]
+    );
+    const operation = fact.deleted_at ? "DELETE" : existingRow ? "UPDATE" : "INSERT";
+    const result = await executor.runAsync(
+      `INSERT INTO ${this.prefix}entries (
+        id, entity_id, title, body, tags, confidence, source_type,
+        source_hash, source_ref, created_at, updated_at, last_accessed_at, access_count,
+        deleted_at, embedding_blob, embedding
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        entity_id = excluded.entity_id,
+        title = excluded.title,
+        body = excluded.body,
+        tags = excluded.tags,
+        confidence = excluded.confidence,
+        source_type = excluded.source_type,
+        source_hash = excluded.source_hash,
+        source_ref = excluded.source_ref,
+        updated_at = excluded.updated_at,
+        last_accessed_at = excluded.last_accessed_at,
+        access_count = excluded.access_count,
+        deleted_at = excluded.deleted_at,
+        embedding_blob = CASE WHEN excluded.embedding_blob IS NULL THEN embedding_blob ELSE excluded.embedding_blob END,
+        embedding = NULL`,
+      [
+        fact.id,
+        fact.entity_id,
+        fact.title,
+        fact.body,
+        tagsJson,
+        fact.confidence,
+        fact.source_type,
+        fact.source_hash,
+        fact.source_ref,
+        fact.created_at,
+        now,
+        fact.last_accessed_at === null ? null : fact.last_accessed_at,
+        fact.access_count,
+        fact.deleted_at ?? null,
+        embeddingBlob ?? null,
+        null
+      ]
+    );
+    await this.outbox.push({
+      entityId: fact.entity_id,
+      tableName: "entries",
+      recordId: fact.id,
+      operation,
+      payload: fact
+    }, tx);
+    return result;
+  }
+  /**
+   * Normalize an embedding blob value to Uint8Array or null.
+   */
+  normalizeEmbeddingBlob(blob) {
+    if (blob instanceof Uint8Array) return blob;
+    if (blob !== null && blob !== void 0 && typeof blob === "object") {
+      const obj = blob;
+      if (obj["type"] === "Buffer" && Array.isArray(obj["data"])) {
+        return new Uint8Array(obj["data"]);
+      }
+      const entries = Object.keys(obj);
+      if (entries.length > 0 && entries.every((k) => /^\d+$/.test(k))) {
+        const len = entries.length;
+        const arr = new Uint8Array(len);
+        for (let i = 0; i < len; i++) arr[i] = obj[String(i)] ?? 0;
+        return arr;
+      }
+    }
+    return null;
+  }
+  /**
+   * Fetch existing rows by IDs and return id/entity_id/updated_at for import collision resolution.
+   */
+  async findExistingMetadataByIds(ids, tx) {
+    const executor = this.getExecutor(tx);
+    const rows = [];
+    for (let i = 0; i < ids.length; i += this.chunkSize) {
+      const chunk = ids.slice(i, i + this.chunkSize);
+      const placeholders = chunk.map(() => "?").join(",");
+      const chunkRows = await executor.getAllAsync(
+        `SELECT id, entity_id, updated_at FROM ${this.prefix}entries WHERE id IN (${placeholders})`,
+        chunk
+      );
+      rows.push(...chunkRows.map((row) => ({ id: row.id, entity_id: row.entity_id, updated_at: Number(row.updated_at) })));
+    }
+    return rows;
+  }
+  async findIdById(id, entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT id FROM ${this.prefix}entries WHERE id = ? AND entity_id = ?`,
+      [id, entityId]
+    );
+    return row?.id ?? null;
+  }
+  async findIdsBySource(entityId, sourceRef, sourceHash, tx, includeDeleted = false) {
+    const executor = this.getExecutor(tx);
+    let sql = `SELECT id FROM ${this.prefix}entries WHERE entity_id = ?`;
+    const args = [entityId];
+    if (sourceRef !== null) {
+      sql += ` AND source_ref = ?`;
+      args.push(sourceRef);
+    }
+    if (sourceHash !== null) {
+      sql += ` AND source_hash = ?`;
+      args.push(sourceHash);
+    }
+    if (!includeDeleted) {
+      sql += ` AND deleted_at IS NULL`;
+    }
+    const rows = await executor.getAllAsync(sql, args);
+    return rows.map((row) => row.id);
+  }
+  async upsertForImport(fact, tx) {
+    const executor = this.getExecutor(tx);
+    const tagsJson = JSON.stringify(fact.tags);
+    const embeddingBlob = this.normalizeEmbeddingBlob(fact.embedding_blob);
+    const result = await executor.runAsync(
+      `INSERT INTO ${this.prefix}entries (
+        id, entity_id, title, body, tags, confidence, source_type,
+        source_hash, source_ref, created_at, updated_at, last_accessed_at, access_count,
+        deleted_at, embedding_blob, embedding
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        entity_id = excluded.entity_id,
+        title = excluded.title,
+        body = excluded.body,
+        tags = excluded.tags,
+        confidence = excluded.confidence,
+        source_type = excluded.source_type,
+        source_hash = excluded.source_hash,
+        source_ref = excluded.source_ref,
+        created_at = excluded.created_at,
+        updated_at = excluded.updated_at,
+        last_accessed_at = excluded.last_accessed_at,
+        access_count = excluded.access_count,
+        deleted_at = excluded.deleted_at,
+        embedding_blob = excluded.embedding_blob,
+        embedding = NULL`,
+      [
+        fact.id,
+        fact.entity_id,
+        fact.title,
+        fact.body,
+        tagsJson,
+        fact.confidence,
+        fact.source_type,
+        fact.source_hash,
+        fact.source_ref,
+        fact.created_at,
+        fact.updated_at,
+        fact.last_accessed_at === null ? null : fact.last_accessed_at,
+        fact.access_count,
+        fact.deleted_at ?? null,
+        embeddingBlob ?? null,
+        null
+      ]
+    );
+    return result;
+  }
+  /**
+   * Soft-delete a single entry by ID scoped to entityId. Sets deleted_at + updated_at.
+   * `tx` is REQUIRED to ensure atomic outbox staging.
+   */
+  async softDelete(entryId, entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const now = Date.now();
+    const result = await executor.runAsync(
+      `UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE id = ? AND entity_id = ? AND deleted_at IS NULL`,
+      [now, now, entryId, entityId]
+    );
+    await this.outbox.push({
+      entityId,
+      tableName: "entries",
+      recordId: entryId,
+      operation: "DELETE",
+      payload: { id: entryId, entity_id: entityId, deleted_at: now }
+    }, tx);
+    return result;
+  }
+  /**
+   * Soft-delete entries by source_ref and/or source_hash within a transaction.
+   * Stages a DELETE outbox entry for each row in the same transaction.
+   * `tx` is REQUIRED.
+   * Returns the number of rows deleted.
+   */
+  async softDeleteBySource(entityId, tx, sourceRef, sourceHash) {
+    const executor = this.getExecutor(tx);
+    const now = Date.now();
+    let q = `UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`;
+    const args = [now, now, entityId];
+    if (sourceRef) {
+      q += ` AND source_ref = ?`;
+      args.push(sourceRef);
+    }
+    if (sourceHash) {
+      q += ` AND source_hash = ?`;
+      args.push(sourceHash);
+    }
+    let selectQ = `SELECT id FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL`;
+    const selectArgs = [entityId];
+    if (sourceRef) {
+      selectQ += ` AND source_ref = ?`;
+      selectArgs.push(sourceRef);
+    }
+    if (sourceHash) {
+      selectQ += ` AND source_hash = ?`;
+      selectArgs.push(sourceHash);
+    }
+    const idsToDelete = await executor.getAllAsync(selectQ, selectArgs);
+    const result = await executor.runAsync(q, args);
+    for (const row of idsToDelete) {
+      await this.outbox.push({
+        entityId,
+        tableName: "entries",
+        recordId: row.id,
+        operation: "DELETE",
+        payload: { id: row.id, entity_id: entityId, deleted_at: now }
+      }, tx);
+    }
+    return result.changes;
+  }
+  /**
+   * Fetch IDs + entity_ids of soft-deleted rows older than cutoff for a given entity.
+   * Used by runPrune().
+   */
+  async getPrunableMetadata(entityId, cutoff, tx) {
+    const executor = this.getExecutor(tx);
+    return executor.getAllAsync(
+      `SELECT id, entity_id FROM ${this.prefix}entries
+       WHERE entity_id = ? AND deleted_at IS NOT NULL AND deleted_at <= ?`,
+      [entityId, cutoff]
+    );
+  }
+  /**
+   * Fetch all non-deleted entries for an entity, ordered by updated_at DESC.
+   * Used by _getFullBundle().
+   */
+  async findAllByEntityId(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const rows = await executor.getAllAsync(
+      `SELECT * FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL ORDER BY updated_at DESC`,
+      [entityId]
+    );
+    return rows.map(mapRowToFact);
+  }
+  /**
+   * Fetch recent non-deleted entries for an entity (limited), ordered by updated_at DESC.
+   * Used by _doRunLibrarian().
+   */
+  async findRecentByEntityId(entityId, limit, tx) {
+    const executor = this.getExecutor(tx);
+    const rows = await executor.getAllAsync(
+      `SELECT * FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL ORDER BY updated_at DESC LIMIT ?`,
+      [entityId, limit]
+    );
+    return rows.map(mapRowToFact);
+  }
+  /**
+   * Count non-deleted entries for the given entities whose embedding_blob dimension
+   * doesn't match queryVecLength. Used by read() to detect model-switch mismatches.
+   */
+  async countDimensionMismatched(entityIds, queryVecLength, tx) {
+    if (entityIds.length === 0) return 0;
+    const executor = this.getExecutor(tx);
+    const placeholders = entityIds.map(() => "?").join(",");
+    const row = await executor.getFirstAsync(
+      `SELECT COUNT(*) AS cnt FROM ${this.prefix}entries
+       WHERE entity_id IN (${placeholders}) AND deleted_at IS NULL
+         AND embedding_blob IS NOT NULL
+         AND (CAST(length(embedding_blob) AS INTEGER) % 4 = 0)
+         AND (CAST(length(embedding_blob) AS INTEGER) / 4) != ?`,
+      [...entityIds, queryVecLength]
+    );
+    return row?.cnt ?? 0;
+  }
+  /**
+   * Count non-deleted entries for entityId that are stale relative to targetDim
+   * (either no blob or wrong dimension). Used by runReembed() per-entity skip logic.
+   */
+  async countStaleForEntity(entityId, targetDim, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT COUNT(*) AS cnt FROM ${this.prefix}entries
+       WHERE entity_id = ? AND deleted_at IS NULL
+         AND (
+           embedding_blob IS NULL
+           OR (CAST(length(embedding_blob) AS INTEGER) / 4) != ?
+         )`,
+      [entityId, targetDim]
+    );
+    return row?.cnt ?? 0;
+  }
+  /**
+   * Count non-deleted entries with stale or unconverted embeddings relative to `dim`.
+   * Used by _reconcileEmbeddingDimension() to decide when to promote the pending
+   * embedding_dimension value.
+   */
+  async countStaleEmbeddings(dim, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT COUNT(*) AS cnt FROM ${this.prefix}entries
+       WHERE deleted_at IS NULL
+         AND (
+           (embedding_blob IS NOT NULL AND (CAST(length(embedding_blob) AS INTEGER) / 4) != ?)
+           OR (embedding_blob IS NULL AND embedding IS NOT NULL)
+         )`,
+      [dim]
+    );
+    return row?.cnt ?? 0;
+  }
+  /**
+   * Bulk delete pruned entries (already soft-deleted) by IDs.
+   * Used by runPrune(). Returns total number of deleted rows.
+   * `tx` is REQUIRED so outbox deletion events are staged atomically.
+   */
+  async bulkDeletePruned(entityId, cutoff, ids, tx) {
+    const executor = this.getExecutor(tx);
+    let totalChanges = 0;
+    const chunkSize = 500;
+    for (let i = 0; i < ids.length; i += chunkSize) {
+      const chunk = ids.slice(i, i + chunkSize);
+      const placeholders = chunk.map(() => "?").join(",");
+      const result = await executor.runAsync(
+        `DELETE FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NOT NULL AND deleted_at <= ? AND id IN (${placeholders})`,
+        [entityId, cutoff, ...chunk]
+      );
+      totalChanges += result.changes;
+      if (result.changes > 0) {
+        for (const id of chunk) {
+          await this.outbox.push({
+            entityId,
+            tableName: "entries",
+            recordId: id,
+            operation: "DELETE",
+            payload: { id, entity_id: entityId, deleted_at: cutoff }
+          }, tx);
+        }
+      }
+    }
+    return totalChanges;
+  }
+  /**
+   * Mark orphaned entries (never accessed, old) as deleted.
+   * Used by _doRunHeal().
+   */
+  async markOrphaned(entityId, orphanThreshold, tx) {
+    const executor = this.getExecutor(tx);
+    const now = Date.now();
+    const orphanedRows = await executor.getAllAsync(
+      `SELECT id FROM ${this.prefix}entries
+       WHERE entity_id = ? AND access_count = 0 AND created_at <= ? AND source_type != 'immutable_document' AND deleted_at IS NULL`,
+      [entityId, orphanThreshold]
+    );
+    if (orphanedRows.length === 0) return 0;
+    const result = await executor.runAsync(
+      `UPDATE ${this.prefix}entries
+       SET deleted_at = ?, updated_at = ?
+       WHERE entity_id = ? AND access_count = 0 AND created_at <= ? AND source_type != 'immutable_document' AND deleted_at IS NULL`,
+      [now, now, entityId, orphanThreshold]
+    );
+    for (const row of orphanedRows) {
+      await this.outbox.push({
+        entityId,
+        tableName: "entries",
+        recordId: row.id,
+        operation: "DELETE",
+        payload: { id: row.id, entity_id: entityId, deleted_at: now }
+      }, tx);
+    }
+    return result.changes;
+  }
+  /**
+   * Downgrade stale inferred entries to 'tentative'.
+   * Used by _doRunHeal().
+   */
+  async downgradeStaleInferred(entityId, staleThreshold, tx) {
+    const executor = this.getExecutor(tx);
+    const now = Date.now();
+    const eligibleRows = await executor.getAllAsync(
+      `SELECT id FROM ${this.prefix}entries
+       WHERE entity_id = ? AND confidence = 'inferred'
+         AND (last_accessed_at <= ? OR (last_accessed_at IS NULL AND created_at <= ?))
+         AND source_type != 'immutable_document' AND deleted_at IS NULL`,
+      [entityId, staleThreshold, staleThreshold]
+    );
+    if (eligibleRows.length === 0) return 0;
+    const result = await executor.runAsync(
+      `UPDATE ${this.prefix}entries
+       SET confidence = 'tentative', updated_at = ?
+       WHERE entity_id = ? AND confidence = 'inferred' AND (last_accessed_at <= ? OR (last_accessed_at IS NULL AND created_at <= ?)) AND source_type != 'immutable_document' AND deleted_at IS NULL`,
+      [now, entityId, staleThreshold, staleThreshold]
+    );
+    for (const row of eligibleRows) {
+      await this.outbox.push({
+        entityId,
+        tableName: "entries",
+        recordId: row.id,
+        operation: "UPDATE",
+        payload: { id: row.id, entity_id: entityId, confidence: "tentative", updated_at: now }
+      }, tx);
+    }
+    return result.changes;
+  }
+  /**
+   * Downgrade specific entries to 'tentative' by IDs.
+   * Used by _doRunHeal().
+   */
+  async downgradeByIds(ids, entityId, tx) {
+    if (ids.length === 0) return;
+    const executor = this.getExecutor(tx);
+    const now = Date.now();
+    const placeholders = ids.map(() => "?").join(",");
+    await executor.runAsync(
+      `UPDATE ${this.prefix}entries SET confidence = 'tentative', updated_at = ? WHERE id IN (${placeholders}) AND entity_id = ?`,
+      [now, ...ids, entityId]
+    );
+    for (const id of ids) {
+      await this.outbox.push({
+        entityId,
+        tableName: "entries",
+        recordId: id,
+        operation: "UPDATE",
+        payload: { id, entity_id: entityId, confidence: "tentative", updated_at: now }
+      }, tx);
+    }
+  }
+  /**
+   * Soft-delete specific entries by IDs.
+   * Used by _doRunHeal().
+   */
+  async softDeleteByIds(ids, entityId, tx) {
+    if (ids.length === 0) return;
+    const executor = this.getExecutor(tx);
+    const now = Date.now();
+    const placeholders = ids.map(() => "?").join(",");
+    await executor.runAsync(
+      `UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE id IN (${placeholders}) AND entity_id = ?`,
+      [now, now, ...ids, entityId]
+    );
+    for (const id of ids) {
+      await this.outbox.push({
+        entityId,
+        tableName: "entries",
+        recordId: id,
+        operation: "DELETE",
+        payload: { id, entity_id: entityId, deleted_at: now }
+      }, tx);
+    }
+  }
+  /**
+   * Bulk soft-delete all entries for an entity.
+   * Stages DELETE outbox entries for each row in the same transaction.
+   * `tx` is REQUIRED.
+   */
+  async bulkSoftDeleteByEntityId(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const now = Date.now();
+    const idsToDelete = await executor.getAllAsync(
+      `SELECT id FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL`,
+      [entityId]
+    );
+    const result = await executor.runAsync(
+      `UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`,
+      [now, now, entityId]
+    );
+    for (const row of idsToDelete) {
+      await this.outbox.push({
+        entityId,
+        tableName: "entries",
+        recordId: row.id,
+        operation: "DELETE",
+        payload: { id: row.id, entity_id: entityId, deleted_at: now }
+      }, tx);
+    }
+    return result.changes;
+  }
+  async findMiniSearchRows(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    if (entityId !== void 0) {
+      return executor.getAllAsync(
+        `SELECT id, entity_id, title, body, tags FROM ${this.prefix}entries WHERE deleted_at IS NULL AND entity_id = ?`,
+        [entityId]
+      );
+    }
+    return executor.getAllAsync(
+      `SELECT id, entity_id, title, body, tags FROM ${this.prefix}entries WHERE deleted_at IS NULL`
+    );
+  }
+  async updateEmbeddingBlob(id, blob, tx) {
+    const executor = this.getExecutor(tx);
+    await executor.runAsync(
+      `UPDATE ${this.prefix}entries SET embedding_blob = ?, embedding = NULL WHERE id = ?`,
+      [blob, id]
+    );
+  }
+  async hasLegacySourceTypes(tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT 1 AS one FROM ${this.prefix}entries WHERE source_type IN ('user_document', 'agent_inferred') LIMIT 1`,
+      []
+    );
+    return row != null;
+  }
+  async countLegacySourceTypes(tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT COUNT(*) as count FROM ${this.prefix}entries WHERE source_type IN ('user_document', 'agent_inferred')`,
+      []
+    );
+    return row?.count ?? 0;
+  }
+  async findAllForReembed(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    if (entityId !== void 0) {
+      return executor.getAllAsync(
+        `SELECT * FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL`,
+        [entityId]
+      );
+    }
+    return executor.getAllAsync(
+      `SELECT * FROM ${this.prefix}entries WHERE deleted_at IS NULL`
+    );
+  }
+  async findRowsForSourceRefMigration(tx) {
+    const executor = this.getExecutor(tx);
+    return executor.getAllAsync(
+      `SELECT rowid, source_ref FROM ${this.prefix}entries
+       WHERE source_ref IS NOT NULL
+         AND (
+           TRIM(source_ref) != source_ref
+           OR INSTR(source_ref, '/') > 0
+           OR INSTR(source_ref, '\\') > 0
+           OR INSTR(source_ref, CHAR(0)) > 0
+           OR source_ref GLOB '*[^-A-Za-z0-9._ ]*'
+         )`
+    );
+  }
+  async updateSourceRefByRowid(rowid, sourceRef, tx) {
+    const executor = this.getExecutor(tx);
+    await executor.runAsync(
+      `UPDATE ${this.prefix}entries SET source_ref = ? WHERE rowid = ?`,
+      [sourceRef, rowid]
+    );
+  }
+  async findLatestSourceHash(entityId, sourceRef, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT source_hash FROM ${this.prefix}entries
+       WHERE entity_id = ? AND source_ref = ? AND deleted_at IS NULL
+       ORDER BY updated_at DESC
+       LIMIT 1`,
+      [entityId, sourceRef]
+    );
+    return row?.source_hash ?? null;
+  }
+  async findMetadataByIds(ids, tx) {
+    if (ids.length === 0) return [];
+    const executor = this.getExecutor(tx);
+    const rows = [];
+    for (let i = 0; i < ids.length; i += this.chunkSize) {
+      const chunk = ids.slice(i, i + this.chunkSize);
+      const placeholders = chunk.map(() => "?").join(",");
+      const chunkRows = await executor.getAllAsync(
+        `SELECT id, entity_id, updated_at, access_count FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND deleted_at IS NULL`,
+        chunk
+      );
+      rows.push(...chunkRows);
+    }
+    return rows;
+  }
+  async findWithEmbeddingsByIds(ids, tx) {
+    if (ids.length === 0) return [];
+    const executor = this.getExecutor(tx);
+    const rows = [];
+    for (let i = 0; i < ids.length; i += this.chunkSize) {
+      const chunk = ids.slice(i, i + this.chunkSize);
+      const placeholders = chunk.map(() => "?").join(",");
+      const chunkRows = await executor.getAllAsync(
+        `SELECT id, entity_id, embedding_blob, embedding, updated_at, access_count FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND deleted_at IS NULL`,
+        chunk
+      );
+      rows.push(...chunkRows);
+    }
+    return rows;
+  }
+  async findMetadataByEntityIds(entityIds, tx) {
+    if (entityIds.length === 0) return [];
+    const executor = this.getExecutor(tx);
+    const placeholders = entityIds.map(() => "?").join(",");
+    return executor.getAllAsync(
+      `SELECT id, entity_id, updated_at, access_count FROM ${this.prefix}entries WHERE entity_id IN (${placeholders}) AND deleted_at IS NULL`,
+      [...entityIds]
+    );
+  }
+  async findWithEmbeddingsByEntityIds(entityIds, tx) {
+    if (entityIds.length === 0) return [];
+    const executor = this.getExecutor(tx);
+    const placeholders = entityIds.map(() => "?").join(",");
+    return executor.getAllAsync(
+      `SELECT id, entity_id, embedding_blob, embedding, updated_at, access_count FROM ${this.prefix}entries WHERE entity_id IN (${placeholders}) AND deleted_at IS NULL`,
+      [...entityIds]
+    );
+  }
+  async findEmbeddingsByIds(ids, tx) {
+    if (ids.length === 0) return [];
+    const executor = this.getExecutor(tx);
+    const rows = [];
+    for (let i = 0; i < ids.length; i += this.chunkSize) {
+      const chunk = ids.slice(i, i + this.chunkSize);
+      const placeholders = chunk.map(() => "?").join(",");
+      const chunkRows = await executor.getAllAsync(
+        `SELECT id, embedding_blob, embedding FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND deleted_at IS NULL`,
+        chunk
+      );
+      rows.push(...chunkRows);
+    }
+    return rows;
+  }
+  async trackAccess(ids, now, tx) {
+    if (ids.length === 0) return;
+    const executor = this.getExecutor(tx);
+    for (let i = 0; i < ids.length; i += this.chunkSize) {
+      const chunk = ids.slice(i, i + this.chunkSize);
+      const placeholders = chunk.map(() => "?").join(",");
+      await executor.runAsync(
+        `UPDATE ${this.prefix}entries SET access_count = access_count + 1, last_accessed_at = ? WHERE id IN (${placeholders})`,
+        [now, ...chunk]
+      );
+    }
+  }
+  getLegacyMigrationSQL() {
+    return [
+      `-- Migrate legacy source_type values (targets your WikiMemory prefix: ${this.prefix})`,
+      `UPDATE ${this.prefix}entries SET source_type = 'immutable_document' WHERE source_type = 'user_document';`,
+      `UPDATE ${this.prefix}entries SET source_type = 'librarian_inferred' WHERE source_type = 'agent_inferred';`
+    ].join("\n");
+  }
+  async findRecentByEntityIds(entityIds, limit, tx) {
+    if (entityIds.length === 0) return [];
+    const executor = this.getExecutor(tx);
+    const placeholders = entityIds.map(() => "?").join(",");
+    const rows = await executor.getAllAsync(
+      `SELECT * FROM ${this.prefix}entries WHERE entity_id IN (${placeholders}) AND deleted_at IS NULL ORDER BY updated_at DESC LIMIT ?`,
+      [...entityIds, limit]
+    );
+    return rows.map(mapRowToFact);
+  }
+};
+
+// src/utils/ids.ts
+function generateId(prefix = "") {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return prefix + crypto.randomUUID().replace(/-/g, "").substring(0, 24);
+  }
+  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return prefix + Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("").substring(0, 24);
+  }
+  return prefix + Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
+}
+
+// src/repositories/OutboxRepository.ts
+var OutboxRepository = class extends BaseRepository {
+  /**
+   * Insert a new outbox event within the provided transaction.
+   * `tx` is required — callers must always pass the active transaction
+   * so the write is atomic with the main table mutation.
+   */
+  async push(params, tx) {
+    const executor = this.getExecutor(tx);
+    const id = generateId("out_");
+    const now = Date.now();
+    await executor.runAsync(
+      `INSERT INTO ${this.prefix}outbox (id, entity_id, table_name, record_id, operation, payload, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      [id, params.entityId, params.tableName, params.recordId, params.operation, JSON.stringify(params.payload), now]
+    );
+  }
+  /**
+   * Fetch pending outbox rows ordered by created_at ASC.
+   * Reads directly from `this.db` (not a transaction).
+   */
+  async fetchPending(limit = 50) {
+    return this.db.getAllAsync(
+      `SELECT * FROM ${this.prefix}outbox ORDER BY created_at ASC LIMIT ?`,
+      [limit]
+    );
+  }
+  /**
+   * Delete acknowledged outbox rows by their IDs.
+   * No-op when `ids` is empty.
+   * Deletes directly from `this.db` (not a transaction).
+   */
+  async acknowledge(ids) {
+    if (ids.length === 0) return;
+    const placeholders = ids.map(() => "?").join(", ");
+    await this.db.runAsync(
+      `DELETE FROM ${this.prefix}outbox WHERE id IN (${placeholders})`,
+      ids
+    );
+  }
+};
+
+// src/repositories/TaskRepository.ts
+function mapRowToTask(row) {
+  return {
+    id: row.id,
+    entity_id: row.entity_id,
+    description: row.description,
+    status: row.status,
+    priority: Number(row.priority),
+    created_at: Number(row.created_at),
+    updated_at: Number(row.updated_at),
+    resolved_at: row.resolved_at != null ? Number(row.resolved_at) : null,
+    deleted_at: row.deleted_at != null ? Number(row.deleted_at) : null
+  };
+}
+var TaskRepository = class extends BaseRepository {
+  constructor(db, prefix, outbox) {
+    super(db, prefix);
+    this.outbox = outbox;
+  }
+  /**
+   * Fetch a single task by ID. Returns null if not found or soft-deleted.
+   */
+  async findById(id) {
+    const row = await this.db.getFirstAsync(
+      `SELECT * FROM ${this.prefix}tasks WHERE id = ? AND deleted_at IS NULL`,
+      [id]
+    );
+    return row ? mapRowToTask(row) : null;
+  }
+  /**
+   * Fetch all pending/in_progress tasks for the given entity IDs.
+   * Returns empty array when entityIds is empty.
+   */
+  async findAllPending(entityIds, limit) {
+    if (entityIds.length === 0) return [];
+    const placeholders = entityIds.map(() => "?").join(", ");
+    const sql = `SELECT * FROM ${this.prefix}tasks WHERE entity_id IN (${placeholders}) AND status IN ('pending', 'in_progress') AND deleted_at IS NULL ORDER BY priority DESC, created_at ASC` + (limit != null ? ` LIMIT ?` : "");
+    const params = limit != null ? [...entityIds, limit] : [...entityIds];
+    const rows = await this.db.getAllAsync(sql, params);
+    return rows.map(mapRowToTask);
+  }
+  async findExistingMetadataByIds(ids, tx) {
+    const executor = this.getExecutor(tx);
+    const rows = [];
+    const chunkSize = 500;
+    for (let i = 0; i < ids.length; i += chunkSize) {
+      const chunk = ids.slice(i, i + chunkSize);
+      const placeholders = chunk.map(() => "?").join(",");
+      const chunkRows = await executor.getAllAsync(
+        `SELECT id, entity_id, updated_at FROM ${this.prefix}tasks WHERE id IN (${placeholders})`,
+        chunk
+      );
+      rows.push(...chunkRows.map((row) => ({ id: row.id, entity_id: row.entity_id, updated_at: Number(row.updated_at) })));
+    }
+    return rows;
+  }
+  /**
+   * Upsert a WikiTask within the provided transaction.
+   * Uses ON CONFLICT(id) DO UPDATE (not INSERT OR REPLACE).
+   * Stages an outbox entry in the same transaction.
+   * `tx` is REQUIRED.
+   */
+  async upsert(task, tx, updatedAt) {
+    const executor = this.getExecutor(tx);
+    const now = Number.isFinite(updatedAt) ? updatedAt : Date.now();
+    const existingRow = await executor.getFirstAsync(
+      `SELECT id FROM ${this.prefix}tasks WHERE id = ?`,
+      [task.id]
+    );
+    const operation = task.deleted_at != null ? "DELETE" : existingRow ? "UPDATE" : "INSERT";
+    await executor.runAsync(
+      `INSERT INTO ${this.prefix}tasks (
+        id, entity_id, description, status, priority,
+        created_at, updated_at, resolved_at, deleted_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        entity_id = excluded.entity_id,
+        description = excluded.description,
+        status = excluded.status,
+        priority = excluded.priority,
+        updated_at = excluded.updated_at,
+        resolved_at = excluded.resolved_at,
+        deleted_at = excluded.deleted_at`,
+      [
+        task.id,
+        task.entity_id,
+        task.description,
+        task.status,
+        task.priority,
+        task.created_at,
+        now,
+        // updated_at set by repo or import override
+        task.resolved_at ?? null,
+        task.deleted_at ?? null
+      ]
+    );
+    await this.outbox.push(
+      {
+        entityId: task.entity_id,
+        tableName: "tasks",
+        recordId: task.id,
+        operation,
+        payload: task
+      },
+      tx
+    );
+  }
+  async upsertForImport(task, tx, updatedAt) {
+    const executor = this.getExecutor(tx);
+    const now = Number.isFinite(updatedAt) ? updatedAt : Date.now();
+    await executor.runAsync(
+      `INSERT INTO ${this.prefix}tasks (
+        id, entity_id, description, status, priority,
+        created_at, updated_at, resolved_at, deleted_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        entity_id = excluded.entity_id,
+        description = excluded.description,
+        status = excluded.status,
+        priority = excluded.priority,
+        updated_at = excluded.updated_at,
+        resolved_at = excluded.resolved_at,
+        deleted_at = excluded.deleted_at`,
+      [
+        task.id,
+        task.entity_id,
+        task.description,
+        task.status,
+        task.priority,
+        task.created_at,
+        now,
+        task.resolved_at ?? null,
+        task.deleted_at ?? null
+      ]
+    );
+  }
+  /**
+   * Soft-delete a task by ID. Sets deleted_at and updated_at.
+   * Stages a DELETE outbox entry in the same transaction.
+   * `tx` is REQUIRED.
+   */
+  async softDelete(id, entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const now = Date.now();
+    await executor.runAsync(
+      `UPDATE ${this.prefix}tasks SET deleted_at = ?, updated_at = ? WHERE id = ? AND entity_id = ? AND deleted_at IS NULL`,
+      [now, now, id, entityId]
+    );
+    await this.outbox.push(
+      {
+        entityId,
+        tableName: "tasks",
+        recordId: id,
+        operation: "DELETE",
+        payload: { id, entity_id: entityId, deleted_at: now }
+      },
+      tx
+    );
+  }
+  /**
+   * Fetch all non-deleted tasks for an entity, ordered by priority DESC, created_at ASC.
+   * Used by _getFullBundle().
+   */
+  async findAllByEntityId(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const rows = await executor.getAllAsync(
+      `SELECT * FROM ${this.prefix}tasks WHERE entity_id = ? AND deleted_at IS NULL ORDER BY priority DESC, created_at ASC`,
+      [entityId]
+    );
+    return rows.map(mapRowToTask);
+  }
+  /**
+   * Bulk delete pruned tasks (already soft-deleted) by cutoff date.
+   * Used by runPrune(). Returns number of deleted rows.
+   */
+  async bulkDeletePruned(entityId, cutoff, tx) {
+    const executor = this.getExecutor(tx);
+    const rowsToDelete = await executor.getAllAsync(
+      `SELECT id, deleted_at FROM ${this.prefix}tasks WHERE entity_id = ? AND deleted_at IS NOT NULL AND deleted_at <= ?`,
+      [entityId, cutoff]
+    );
+    if (rowsToDelete.length === 0) return 0;
+    const result = await executor.runAsync(
+      `DELETE FROM ${this.prefix}tasks WHERE entity_id = ? AND deleted_at IS NOT NULL AND deleted_at <= ?`,
+      [entityId, cutoff]
+    );
+    for (const row of rowsToDelete) {
+      await this.outbox.push(
+        {
+          entityId,
+          tableName: "tasks",
+          recordId: row.id,
+          operation: "DELETE",
+          payload: { id: row.id, entity_id: entityId, deleted_at: row.deleted_at }
+        },
+        tx
+      );
+    }
+    return result.changes;
+  }
+  /**
+   * Soft-delete a task by ID within a transaction.
+   * Stages a DELETE outbox entry in the same transaction.
+   * `tx` is REQUIRED.
+   */
+  async softDeleteById(id, entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const now = Date.now();
+    const result = await executor.runAsync(
+      `UPDATE ${this.prefix}tasks SET deleted_at = ?, updated_at = ? WHERE id = ? AND entity_id = ? AND deleted_at IS NULL`,
+      [now, now, id, entityId]
+    );
+    if (result.changes > 0) {
+      await this.outbox.push(
+        {
+          entityId,
+          tableName: "tasks",
+          recordId: id,
+          operation: "DELETE",
+          payload: { id, entity_id: entityId, deleted_at: now }
+        },
+        tx
+      );
+    }
+    return result;
+  }
+  /**
+   * Bulk soft-delete all tasks for an entity.
+   * Stages DELETE outbox entries for each row in the same transaction.
+   * `tx` is REQUIRED.
+   */
+  async bulkSoftDeleteByEntityId(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const now = Date.now();
+    const idsToDelete = await executor.getAllAsync(
+      `SELECT id FROM ${this.prefix}tasks WHERE entity_id = ? AND deleted_at IS NULL`,
+      [entityId]
+    );
+    const result = await executor.runAsync(
+      `UPDATE ${this.prefix}tasks SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`,
+      [now, now, entityId]
+    );
+    for (const row of idsToDelete) {
+      await this.outbox.push({
+        entityId,
+        tableName: "tasks",
+        recordId: row.id,
+        operation: "DELETE",
+        payload: { id: row.id, entity_id: entityId, deleted_at: now }
+      }, tx);
+    }
+    return result.changes;
+  }
+};
+
+// src/repositories/EventRepository.ts
+var EventRepository = class extends BaseRepository {
+  /**
+   * Insert a new event row.
+   * Pass `tx` to participate in a caller-owned transaction; omit to run against the default db.
+   */
+  async add(event, tx) {
+    const executor = this.getExecutor(tx);
+    await executor.runAsync(
+      `INSERT INTO ${this.prefix}events (id, entity_id, event_type, summary, related_entry_id, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+      [
+        event.id,
+        event.entity_id,
+        event.event_type,
+        event.summary,
+        event.related_entry_id ?? null,
+        event.created_at
+      ]
+    );
+  }
+  async addIgnoreDuplicate(event, tx) {
+    const executor = this.getExecutor(tx);
+    await executor.runAsync(
+      `INSERT OR IGNORE INTO ${this.prefix}events (id, entity_id, event_type, summary, related_entry_id, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+      [
+        event.id,
+        event.entity_id,
+        event.event_type,
+        event.summary,
+        event.related_entry_id ?? null,
+        event.created_at
+      ]
+    );
+  }
+  /**
+   * Return the most recent events for an entity, newest first.
+   * Defaults to a limit of 50.
+   */
+  async getRecent(entityId, limit = 50) {
+    return this.db.getAllAsync(
+      `SELECT * FROM ${this.prefix}events WHERE entity_id = ? ORDER BY created_at DESC LIMIT ?`,
+      [entityId, limit]
+    );
+  }
+  /**
+   * Return the most recent events for the given entity IDs, newest first.
+   * Defaults to a limit of 50.
+   */
+  async getRecentForEntities(entityIds, limit = 50) {
+    if (entityIds.length === 0) return [];
+    const placeholders = entityIds.map(() => "?").join(", ");
+    return this.db.getAllAsync(
+      `SELECT * FROM ${this.prefix}events WHERE entity_id IN (${placeholders}) ORDER BY created_at DESC LIMIT ?`,
+      [...entityIds, limit]
+    );
+  }
+  /**
+   * Delete events for an entity that were created at or before the given cutoff timestamp.
+   * Returns the number of deleted rows.
+   */
+  async prune(entityId, cutoff) {
+    return this.db.runAsync(
+      `DELETE FROM ${this.prefix}events WHERE entity_id = ? AND created_at <= ?`,
+      [entityId, cutoff]
+    );
+  }
+  /**
+   * Return the total number of events stored for an entity.
+   * `tx` is optional — pass an active transaction handle for atomic reads.
+   */
+  async count(entityId, tx) {
+    const executor = tx ?? this.db;
+    const row = await executor.getFirstAsync(
+      `SELECT COUNT(*) as count FROM ${this.prefix}events WHERE entity_id = ?`,
+      [entityId]
+    );
+    return row?.count ?? 0;
+  }
+  /**
+   * Return all events for an entity in chronological (ASC) order.
+   * When limit is provided, fetches newest-first then reverses to preserve chronological order.
+   */
+  async getByEntityId(entityId, limit) {
+    if (limit != null) {
+      const rows = await this.db.getAllAsync(
+        `SELECT * FROM ${this.prefix}events WHERE entity_id = ? ORDER BY created_at DESC LIMIT ?`,
+        [entityId, limit]
+      );
+      return rows.slice().reverse();
+    }
+    return this.db.getAllAsync(
+      `SELECT * FROM ${this.prefix}events WHERE entity_id = ? ORDER BY created_at ASC`,
+      [entityId]
+    );
+  }
+};
+
+// src/repositories/MetadataRepository.ts
+var MetadataRepository = class extends BaseRepository {
+  // CHECKPOINTS TABLE METHODS
+  async getCheckpoint(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT memory_checkpoint, heal_checkpoint FROM ${this.prefix}checkpoints WHERE entity_id = ?`,
+      [entityId]
+    );
+    if (!row) return {};
+    return {
+      memory: row.memory_checkpoint ?? void 0,
+      heal: row.heal_checkpoint ?? void 0
+    };
+  }
+  async updateCheckpoint(entityId, updates, tx) {
+    const fields = [];
+    const values = [];
+    if (updates.memory !== void 0) {
+      fields.push("memory_checkpoint = ?");
+      values.push(updates.memory);
+    }
+    if (updates.heal !== void 0) {
+      fields.push("heal_checkpoint = ?");
+      values.push(updates.heal);
+    }
+    if (fields.length === 0) return;
+    const executor = this.getExecutor(tx);
+    await executor.runAsync(
+      `INSERT INTO ${this.prefix}checkpoints (entity_id, memory_checkpoint, heal_checkpoint)
+       VALUES (?, ?, ?)
+       ON CONFLICT(entity_id) DO UPDATE SET ${fields.join(", ")}`,
+      [entityId, updates.memory ?? 0, updates.heal ?? 0, ...values]
+    );
+  }
+  async deleteCheckpoint(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    await executor.runAsync(
+      `DELETE FROM ${this.prefix}checkpoints WHERE entity_id = ?`,
+      [entityId]
+    );
+  }
+  // META TABLE METHODS
+  async getMeta(key, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT value FROM ${this.prefix}meta WHERE key = ?`,
+      [key]
+    );
+    return row ? row.value : null;
+  }
+  async setMeta(key, value, tx) {
+    const executor = this.getExecutor(tx);
+    await executor.runAsync(
+      `INSERT INTO ${this.prefix}meta (key, value) VALUES (?, ?)
+       ON CONFLICT(key) DO UPDATE SET value = excluded.value`,
+      [key, value]
+    );
+  }
+  async clearDimensionMismatch(tx) {
+    const executor = this.getExecutor(tx);
+    await executor.runAsync(
+      `DELETE FROM ${this.prefix}meta WHERE key = 'embedding_dimension_mismatch'`
+    );
+  }
+  async tableExists(tableName, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT name FROM sqlite_master WHERE type='table' AND name=?`,
+      [tableName]
+    );
+    return row != null;
+  }
+  async getTableDdl(tableName, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT sql FROM sqlite_master WHERE type='table' AND name=?`,
+      [tableName]
+    );
+    return row?.sql ?? null;
+  }
+  async vacuum() {
+    await this.db.execAsync(`PRAGMA wal_checkpoint(TRUNCATE)`);
+    await this.db.execAsync(`VACUUM`);
+  }
+  async getDistinctEntityIds(tx) {
+    const executor = this.getExecutor(tx);
+    const rows = await executor.getAllAsync(
+      `SELECT DISTINCT entity_id FROM (
+         SELECT entity_id FROM ${this.prefix}entries WHERE deleted_at IS NULL
+         UNION
+         SELECT entity_id FROM ${this.prefix}tasks WHERE deleted_at IS NULL
+         UNION
+         SELECT entity_id FROM ${this.prefix}events
+       ) ORDER BY entity_id`
+    );
+    return rows.map((r) => r.entity_id);
+  }
+};
+
 // src/prompts.ts
 var LIBRARIAN_SYSTEM_PROMPT = `You are a knowledge extraction agent. Your job is to analyze recent episodic events and extract stable facts and actionable tasks about the user or entity.
 Return ONLY a valid JSON object matching this schema:
@@ -290,9 +1565,6 @@ function parseJsonResponse(text) {
   if (end === -1) throw new SyntaxError("No JSON object/array found in LLM response");
   return JSON.parse(text.slice(start, end + 1));
 }
-function generateId(prefix = "") {
-  return prefix + Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
-}
 function safeSlice(value, start, end) {
   const length = value.length;
   let safeStart = start < 0 ? Math.max(length + start, 0) : Math.min(start, length);
@@ -461,6 +1733,11 @@ var _WikiMemory = class _WikiMemory {
     this.db = db;
     this.options = options;
     this.prefix = options.config?.tablePrefix || "llm_wiki_";
+    this.outboxRepo = new OutboxRepository(db, this.prefix);
+    this.entryRepo = new EntryRepository(db, this.prefix, this.outboxRepo);
+    this.taskRepo = new TaskRepository(db, this.prefix, this.outboxRepo);
+    this.eventRepo = new EventRepository(db, this.prefix);
+    this.metadataRepo = new MetadataRepository(db, this.prefix);
   }
   normalizeMiniSearchRow(row) {
     return {
@@ -480,10 +1757,7 @@ var _WikiMemory = class _WikiMemory {
   }
   async rebuildMiniSearchIndex(entityId) {
     if (entityId) {
-      const rows2 = await this.db.getAllAsync(
-        `SELECT id, entity_id, title, body, tags FROM ${this.prefix}entries WHERE deleted_at IS NULL AND entity_id = ?`,
-        [entityId]
-      );
+      const rows2 = await this.entryRepo.findMiniSearchRows(entityId);
       const previousIds = this.miniSearchEntryIdsByEntity.get(entityId);
       if (previousIds) {
         for (const id of previousIds) {
@@ -497,7 +1771,7 @@ var _WikiMemory = class _WikiMemory {
       this.miniSearchEntryIdsByEntity.set(entityId, new Set(documents2.map((document) => document.id)));
       return;
     }
-    const rows = await this.db.getAllAsync(`SELECT id, entity_id, title, body, tags FROM ${this.prefix}entries WHERE deleted_at IS NULL`);
+    const rows = await this.entryRepo.findMiniSearchRows();
     this.miniSearch.removeAll();
     this.miniSearchEntryIdsByEntity.clear();
     const documents = rows.map((row) => this.normalizeMiniSearchRow(row));
@@ -511,25 +1785,17 @@ var _WikiMemory = class _WikiMemory {
     }
   }
   async storeEmbeddingDimension(dim) {
-    const existing = await this.db.getFirstAsync(
-      `SELECT value FROM ${this.prefix}meta WHERE key = 'embedding_dimension'`
-    );
+    const existing = await this.metadataRepo.getMeta("embedding_dimension");
     if (existing) {
-      const storedDim = parseInt(existing.value, 10);
+      const storedDim = parseInt(existing, 10);
       if (storedDim !== dim) {
         console.warn(
           `[WikiMemory] Embedding dimension mismatch: stored ${storedDim}, got ${dim}. Call runReembed() to rebuild embeddings with the new model.`
         );
-        await this.db.runAsync(
-          `INSERT OR REPLACE INTO ${this.prefix}meta (key, value) VALUES ('embedding_dimension_mismatch', ?)`,
-          [String(dim)]
-        );
+        await this.metadataRepo.setMeta("embedding_dimension_mismatch", String(dim), this.db);
       }
     } else {
-      await this.db.runAsync(
-        `INSERT OR REPLACE INTO ${this.prefix}meta (key, value) VALUES ('embedding_dimension', ?)`,
-        [String(dim)]
-      );
+      await this.metadataRepo.setMeta("embedding_dimension", String(dim), this.db);
     }
   }
   /**
@@ -539,28 +1805,13 @@ var _WikiMemory = class _WikiMemory {
    * stuck on the MiniSearch fallback.
    */
   async _reconcileEmbeddingDimension() {
-    const mismatch = await this.db.getFirstAsync(
-      `SELECT value FROM ${this.prefix}meta WHERE key = 'embedding_dimension_mismatch'`
-    );
-    if (!mismatch) return;
-    const newDim = parseInt(mismatch.value, 10);
-    const residual = await this.db.getFirstAsync(
-      `SELECT COUNT(*) AS cnt FROM ${this.prefix}entries
-       WHERE deleted_at IS NULL
-         AND (
-           (embedding_blob IS NOT NULL AND (CAST(length(embedding_blob) AS INTEGER) / 4) != ?)
-           OR (embedding_blob IS NULL AND embedding IS NOT NULL)
-         )`,
-      [newDim]
-    );
-    if (!residual || residual.cnt === 0) {
-      await this.db.runAsync(
-        `INSERT OR REPLACE INTO ${this.prefix}meta (key, value) VALUES ('embedding_dimension', ?)`,
-        [mismatch.value]
-      );
-      await this.db.runAsync(
-        `DELETE FROM ${this.prefix}meta WHERE key = 'embedding_dimension_mismatch'`
-      );
+    const mismatchValue = await this.metadataRepo.getMeta("embedding_dimension_mismatch");
+    if (!mismatchValue) return;
+    const newDim = parseInt(mismatchValue, 10);
+    const residualCount = await this.entryRepo.countStaleEmbeddings(newDim);
+    if (residualCount === 0) {
+      await this.metadataRepo.setMeta("embedding_dimension", mismatchValue, this.db);
+      await this.metadataRepo.clearDimensionMismatch(this.db);
     }
   }
   async embedFact(fact) {
@@ -598,10 +1849,7 @@ var _WikiMemory = class _WikiMemory {
       }
       await this.storeEmbeddingDimension(float32Vector.length);
       const blob = new Uint8Array(float32Vector.buffer);
-      await this.db.runAsync(
-        `UPDATE ${this.prefix}entries SET embedding_blob = ?, embedding = NULL WHERE id = ?`,
-        [blob, fact.id]
-      );
+      await this.entryRepo.updateEmbeddingBlob(fact.id, blob);
       try {
         await this._notifyEmbeddingPersisted(fact.entity_id, fact.id, float32Vector);
       } catch (hookErr) {
@@ -634,28 +1882,12 @@ var _WikiMemory = class _WikiMemory {
     );
   }
   async assertNoLegacySourceTypes() {
-    const legacyProbe = await this.db.getFirstAsync(
-      `SELECT 1 AS one FROM ${this.prefix}entries
-       WHERE source_type IN ('user_document', 'agent_inferred')
-       LIMIT 1`,
-      []
-    );
-    if (!legacyProbe) return;
-    const legacyCount = await this.db.getFirstAsync(
-      `SELECT COUNT(*) as count FROM ${this.prefix}entries
-       WHERE source_type IN ('user_document', 'agent_inferred')`,
-      []
-    );
-    const count = legacyCount?.count ?? 0;
-    const migrationSQL = `
--- Migrate legacy source_type values (targets your WikiMemory prefix: ${this.prefix})
-UPDATE ${this.prefix}entries SET source_type = 'immutable_document' WHERE source_type = 'user_document';
-UPDATE ${this.prefix}entries SET source_type = 'librarian_inferred' WHERE source_type = 'agent_inferred';
-    `.trim();
+    if (!await this.entryRepo.hasLegacySourceTypes()) return;
+    const count = await this.entryRepo.countLegacySourceTypes();
     throw new Error(
       `Database contains ${count} entries with legacy source_type values ('user_document' or 'agent_inferred'). These enum values were renamed in this release. Running without migration would allow legacy 'user_document' facts to bypass immutability guards, causing data corruption.
 
-${migrationSQL}
+${this.entryRepo.getLegacyMigrationSQL()}
 
 After running the migration SQL, restart your application.`
     );
@@ -712,77 +1944,45 @@ After running the migration SQL, restart your application.`
     }
   }
   async setup() {
-    const entriesExistedBeforeSetup = await this.db.getFirstAsync(
-      `SELECT name FROM sqlite_master WHERE type='table' AND name=?`,
-      [`${this.prefix}entries`]
-    );
+    const entriesExistedBeforeSetup = await this.metadataRepo.tableExists(`${this.prefix}entries`);
     await setupDatabase(this.db, this.prefix);
     let currentVersion;
     if (!entriesExistedBeforeSetup) {
-      await this.db.runAsync(
-        `INSERT OR REPLACE INTO ${this.prefix}meta (key, value) VALUES ('schema_version', ?)`,
-        [String(CURRENT_SCHEMA_VERSION)]
-      );
+      await this.metadataRepo.setMeta("schema_version", String(CURRENT_SCHEMA_VERSION), this.db);
       currentVersion = CURRENT_SCHEMA_VERSION;
     } else {
-      const metaRow = await this.db.getFirstAsync(
-        `SELECT value FROM ${this.prefix}meta WHERE key = 'schema_version'`
-      );
-      if (metaRow) {
-        currentVersion = parseInt(metaRow.value, 10);
+      const schemaVersionValue = await this.metadataRepo.getMeta("schema_version");
+      if (schemaVersionValue) {
+        currentVersion = parseInt(schemaVersionValue, 10);
         if (!Number.isFinite(currentVersion)) currentVersion = 0;
       } else {
-        const ftsMeta = await this.db.getFirstAsync(
-          `SELECT sql FROM sqlite_master WHERE type='table' AND name=?`,
-          [`${this.prefix}entries_fts`]
-        );
-        const hasPorter = /tokenize\s*=\s*['"]porter\s+unicode61['"]/i.test(ftsMeta?.sql ?? "");
+        const ftsDdl = await this.metadataRepo.getTableDdl(`${this.prefix}entries_fts`);
+        const hasPorter = /tokenize\s*=\s*['"]porter\s+unicode61['"]/i.test(ftsDdl ?? "");
         currentVersion = hasPorter ? 1 : 0;
       }
     }
     for (const migration of MIGRATIONS) {
       if (migration.version > currentVersion) {
         await migration.run(this.db, this.prefix);
-        await this.db.runAsync(
-          `INSERT OR REPLACE INTO ${this.prefix}meta (key, value) VALUES ('schema_version', ?)`,
-          [String(migration.version)]
-        );
+        await this.metadataRepo.setMeta("schema_version", String(migration.version), this.db);
         currentVersion = migration.version;
       }
     }
     if (entriesExistedBeforeSetup) {
-      const metaCheck = await this.db.getFirstAsync(
-        `SELECT value FROM ${this.prefix}meta WHERE key = 'schema_version'`
-      );
-      if (!metaCheck) {
-        await this.db.runAsync(
-          `INSERT OR REPLACE INTO ${this.prefix}meta (key, value) VALUES ('schema_version', ?)`,
-          [String(currentVersion)]
-        );
+      const schemaVersionCheck = await this.metadataRepo.getMeta("schema_version");
+      if (!schemaVersionCheck) {
+        await this.metadataRepo.setMeta("schema_version", String(currentVersion), this.db);
       }
     }
     if (entriesExistedBeforeSetup) {
       await this.assertNoLegacySourceTypes();
     }
-    const rows = await this.db.getAllAsync(`
-      SELECT rowid, source_ref FROM ${this.prefix}entries
-      WHERE source_ref IS NOT NULL
-        AND (
-          TRIM(source_ref) != source_ref
-          OR INSTR(source_ref, '/') > 0
-          OR INSTR(source_ref, '\\') > 0
-          OR INSTR(source_ref, CHAR(0)) > 0
-          OR source_ref GLOB '*[^-A-Za-z0-9._ ]*'
-        )
-    `);
-    await this.db.withTransactionAsync(async () => {
+    const rows = await this.entryRepo.findRowsForSourceRefMigration();
+    await this.db.withTransactionAsync(async (tx) => {
       for (const row of rows) {
         const normalized = normalizeSourceRef(row.source_ref);
         if (normalized !== row.source_ref) {
-          await this.db.runAsync(
-            `UPDATE ${this.prefix}entries SET source_ref = ? WHERE rowid = ?`,
-            [normalized, row.rowid]
-          );
+          await this.entryRepo.updateSourceRefByRowid(row.rowid, normalized, tx);
         }
       }
     });
@@ -797,15 +1997,9 @@ After running the migration SQL, restart your application.`
     if (!normalizedHash) {
       throw new Error(`Invalid sourceHash: must be a 64-character hex string (normalized to lowercase)`);
     }
-    const row = await this.db.getFirstAsync(
-      `SELECT source_hash FROM ${this.prefix}entries
-       WHERE entity_id = ? AND source_ref = ? AND deleted_at IS NULL
-       ORDER BY updated_at DESC
-       LIMIT 1`,
-      [entityId, normalizedRef]
-    );
-    if (!row) return true;
-    const normalizedStoredHash = row.source_hash ? normalizeSourceHash(row.source_hash) : null;
+    const storedHash = await this.entryRepo.findLatestSourceHash(entityId, normalizedRef);
+    if (storedHash === null) return true;
+    const normalizedStoredHash = normalizeSourceHash(storedHash);
     return normalizedStoredHash !== normalizedHash;
   }
   _pruneKey(entityId) {
@@ -916,11 +2110,7 @@ After running the migration SQL, restart your application.`
       let deletedEvents = 0;
       if (retainSoftDeletedFor !== null) {
         const cutoff = now - retainSoftDeletedFor * 864e5;
-        const entriesToDelete = await this.db.getAllAsync(
-          `SELECT id, entity_id FROM ${this.prefix}entries
-           WHERE entity_id = ? AND deleted_at IS NOT NULL AND deleted_at <= ?`,
-          [entityId, cutoff]
-        );
+        const entriesToDelete = await this.entryRepo.getPrunableMetadata(entityId, cutoff);
         const succeeded = [];
         let failure = null;
         for (const row of entriesToDelete) {
@@ -932,24 +2122,13 @@ After running the migration SQL, restart your application.`
             break;
           }
         }
-        if (succeeded.length > 0) {
-          const chunkSize = 500;
-          for (let i = 0; i < succeeded.length; i += chunkSize) {
-            const chunk = succeeded.slice(i, i + chunkSize);
-            const placeholders = chunk.map(() => "?").join(",");
-            const entryResult = await this.db.runAsync(
-              `DELETE FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NOT NULL AND deleted_at <= ? AND id IN (${placeholders})`,
-              [entityId, cutoff, ...chunk.map((r) => r.id)]
-            );
-            deletedEntries += entryResult.changes;
+        const succeededIds = succeeded.map((r) => r.id);
+        await this.db.withTransactionAsync(async (tx) => {
+          if (succeededIds.length > 0) {
+            deletedEntries = await this.entryRepo.bulkDeletePruned(entityId, cutoff, succeededIds, tx);
           }
-        }
-        const taskResult = await this.db.runAsync(
-          `DELETE FROM ${this.prefix}tasks
-           WHERE entity_id = ? AND deleted_at IS NOT NULL AND deleted_at <= ?`,
-          [entityId, cutoff]
-        );
-        deletedTasks = taskResult.changes;
+          deletedTasks = await this.taskRepo.bulkDeletePruned(entityId, cutoff, tx);
+        });
         if (failure) {
           await this.rebuildMiniSearchIndex(entityId);
           this.vectorCache.delete(entityId);
@@ -982,16 +2161,11 @@ After running the migration SQL, restart your application.`
       }
       if (retainEventsFor !== null) {
         const cutoff = now - retainEventsFor * 864e5;
-        const eventResult = await this.db.runAsync(
-          `DELETE FROM ${this.prefix}events
-           WHERE entity_id = ? AND created_at <= ?`,
-          [entityId, cutoff]
-        );
+        const eventResult = await this.eventRepo.prune(entityId, cutoff);
         deletedEvents = eventResult.changes;
       }
       if (vacuum) {
-        await this.db.execAsync(`PRAGMA wal_checkpoint(TRUNCATE)`);
-        await this.db.execAsync(`VACUUM`);
+        await this.metadataRepo.vacuum();
       }
       await this.rebuildMiniSearchIndex(entityId);
       this.vectorCache.delete(entityId);
@@ -1047,27 +2221,17 @@ After running the migration SQL, restart your application.`
               "embed() returned an empty or non-finite vector. Falling back to keyword search."
             );
           }
-          const storedDimRow = await this.db.getFirstAsync(
-            `SELECT value FROM ${this.prefix}meta WHERE key = 'embedding_dimension'`
-          );
-          if (storedDimRow) {
-            const storedDim = parseInt(storedDimRow.value, 10);
+          const storedDimValue = await this.metadataRepo.getMeta("embedding_dimension");
+          if (storedDimValue) {
+            const storedDim = parseInt(storedDimValue, 10);
             if (storedDim !== queryVec.length) {
               throw new Error(
                 `Embedding dimension mismatch: stored ${storedDim}, query has ${queryVec.length}. Call runReembed() to rebuild embeddings with the new model.`
               );
             }
           }
-          const mismatchScope = this._entityInClause(scoredEntityIds);
-          const mismatchedCount = await this.db.getFirstAsync(
-            `SELECT COUNT(*) AS cnt FROM ${this.prefix}entries
-             WHERE ${mismatchScope.clause} AND deleted_at IS NULL
-               AND embedding_blob IS NOT NULL
-               AND (CAST(length(embedding_blob) AS INTEGER) % 4 = 0)
-               AND (CAST(length(embedding_blob) AS INTEGER) / 4) != ?`,
-            [...mismatchScope.params, queryVec.length]
-          );
-          if (mismatchedCount && mismatchedCount.cnt > 0) {
+          const mismatchedCount = await this.entryRepo.countDimensionMismatched(scoredEntityIds, queryVec.length);
+          if (mismatchedCount > 0) {
             throw new Error(
               `Some facts have embeddings that do not match the current model dimension. Call runReembed() to rebuild all embeddings consistently.`
             );
@@ -1091,31 +2255,10 @@ After running the migration SQL, restart your application.`
                 candidateRows = null;
               } else {
                 const topKIds = topKResults.map((r) => r.id);
-                const inClauseChunkSize = 500;
                 if (useRanker) {
-                  const rows = [];
-                  for (let i = 0; i < topKIds.length; i += inClauseChunkSize) {
-                    const idChunk = topKIds.slice(i, i + inClauseChunkSize);
-                    const placeholders = idChunk.map(() => "?").join(",");
-                    const chunkRows = await this.db.getAllAsync(
-                      `SELECT id, entity_id, updated_at, access_count FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND deleted_at IS NULL`,
-                      idChunk
-                    );
-                    rows.push(...chunkRows);
-                  }
-                  candidateRows = rows;
+                  candidateRows = await this.entryRepo.findMetadataByIds(topKIds);
                 } else {
-                  const rows = [];
-                  for (let i = 0; i < topKIds.length; i += inClauseChunkSize) {
-                    const idChunk = topKIds.slice(i, i + inClauseChunkSize);
-                    const placeholders = idChunk.map(() => "?").join(",");
-                    const chunkRows = await this.db.getAllAsync(
-                      `SELECT id, entity_id, embedding_blob, embedding, updated_at, access_count FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND deleted_at IS NULL`,
-                      idChunk
-                    );
-                    rows.push(...chunkRows);
-                  }
-                  candidateRows = rows;
+                  candidateRows = await this.entryRepo.findWithEmbeddingsByIds(topKIds);
                 }
                 if (weight !== void 0 && weight < 1) {
                   const maxMsScore = Math.max(1, topKResults[0]?.score ?? 1);
@@ -1125,17 +2268,9 @@ After running the migration SQL, restart your application.`
             }
           } else {
             if (useRanker) {
-              const entityScope = this._entityInClause(scoredEntityIds);
-              candidateRows = await this.db.getAllAsync(
-                `SELECT id, entity_id, updated_at, access_count FROM ${this.prefix}entries WHERE ${entityScope.clause} AND deleted_at IS NULL`,
-                entityScope.params
-              );
+              candidateRows = await this.entryRepo.findMetadataByEntityIds(scoredEntityIds);
             } else {
-              const entityScope = this._entityInClause(scoredEntityIds);
-              candidateRows = await this.db.getAllAsync(
-                `SELECT id, entity_id, embedding_blob, embedding, updated_at, access_count FROM ${this.prefix}entries WHERE ${entityScope.clause} AND deleted_at IS NULL`,
-                entityScope.params
-              );
+              candidateRows = await this.entryRepo.findWithEmbeddingsByEntityIds(scoredEntityIds);
             }
             if (weight !== void 0 && weight < 1) {
               const entityIdSet = new Set(scoredEntityIds);
@@ -1298,19 +2433,8 @@ After running the migration SQL, restart your application.`
                   let fallbackRows = candidateRows;
                   if (fallbackRows && fallbackRows.length > 0 && !("embedding_blob" in fallbackRows[0])) {
                     const rowIds = fallbackRows.map((r) => r.id);
-                    const embeddingsMap = /* @__PURE__ */ new Map();
-                    const chunkSize = 500;
-                    for (let i = 0; i < rowIds.length; i += chunkSize) {
-                      const idChunk = rowIds.slice(i, i + chunkSize);
-                      const placeholders = idChunk.map(() => "?").join(",");
-                      const embeddingRows = await this.db.getAllAsync(
-                        `SELECT id, embedding_blob, embedding FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND deleted_at IS NULL`,
-                        idChunk
-                      );
-                      for (const row of embeddingRows) {
-                        embeddingsMap.set(row.id, { embedding_blob: row.embedding_blob, embedding: row.embedding });
-                      }
-                    }
+                    const embeddingRows = await this.entryRepo.findEmbeddingsByIds(rowIds);
+                    const embeddingsMap = new Map(embeddingRows.map((row) => [row.id, row]));
                     fallbackRows = fallbackRows.map((r) => ({
                       ...r,
                       embedding_blob: embeddingsMap.get(r.id)?.embedding_blob ?? null,
@@ -1451,57 +2575,15 @@ After running the migration SQL, restart your application.`
       if (facts.length > 0) {
         const ids = facts.map((f) => f.id);
         const now = Date.now();
-        const accessChunkSize = 500;
-        for (let i = 0; i < ids.length; i += accessChunkSize) {
-          const idChunk = ids.slice(i, i + accessChunkSize);
-          const placeholders = idChunk.map(() => "?").join(",");
-          await this.db.runAsync(
-            `UPDATE ${this.prefix}entries
-             SET access_count = access_count + 1, last_accessed_at = ?
-             WHERE id IN (${placeholders})`,
-            [now, ...idChunk]
-          );
-        }
+        await this.entryRepo.trackAccess(ids, now);
       }
     } else {
-      const entityScope = this._entityInClause(entityIds);
-      const rawFacts = await this.db.getAllAsync(
-        `SELECT * FROM ${this.prefix}entries
-         WHERE ${entityScope.clause} AND deleted_at IS NULL
-         ORDER BY updated_at DESC
-         LIMIT ?`,
-        [...entityScope.params, maxResults]
-      );
-      facts = rawFacts.map((f) => {
-        const { embedding: _embedding, embedding_blob: _blob, ...rest } = f;
-        return {
-          ...rest,
-          tags: typeof rest.tags === "string" ? JSON.parse(rest.tags) : rest.tags
-        };
-      });
+      facts = await this.entryRepo.findRecentByEntityIds(entityIds, maxResults);
     }
+    const eventsLimit = Math.min(10 * entityIds.length, 100);
     const [tasks, events] = await Promise.all([
-      (async () => {
-        const entityScope = this._entityInClause(entityIds);
-        const tasksLimit = entityIds.length === 1 ? void 0 : Math.min(20 * entityIds.length, 200);
-        return this.db.getAllAsync(
-          `SELECT * FROM ${this.prefix}tasks
-           WHERE ${entityScope.clause} AND status IN ('pending', 'in_progress') AND deleted_at IS NULL
-           ORDER BY priority DESC, created_at ASC${tasksLimit !== void 0 ? "\n           LIMIT ?" : ""}`,
-          tasksLimit !== void 0 ? [...entityScope.params, tasksLimit] : entityScope.params
-        );
-      })(),
-      (async () => {
-        const entityScope = this._entityInClause(entityIds);
-        const eventsLimit = Math.min(10 * entityIds.length, 100);
-        return this.db.getAllAsync(
-          `SELECT * FROM ${this.prefix}events
-           WHERE ${entityScope.clause}
-           ORDER BY created_at DESC
-           LIMIT ?`,
-          [...entityScope.params, eventsLimit]
-        );
-      })()
+      this.taskRepo.findAllPending(entityIds, entityIds.length === 1 ? void 0 : Math.min(20 * entityIds.length, 200)),
+      entityIds.length === 1 ? this.eventRepo.getRecent(entityIds[0], eventsLimit) : this.eventRepo.getRecentForEntities(entityIds, eventsLimit)
     ]);
     let factScores;
     if (exposeMetadata && trimmedQuery && scoreByFactId) {
@@ -1544,40 +2626,12 @@ After running the migration SQL, restart your application.`
     if (updatedAtDiff !== 0) return updatedAtDiff;
     return a.id.localeCompare(b.id);
   }
-  /**
-   * Build SQL IN clause with placeholders for multiple entity IDs.
-   */
-  _entityInClause(entityIds) {
-    if (entityIds.length === 0) return { clause: "1=0", params: [] };
-    const placeholders = entityIds.map(() => "?").join(",");
-    return { clause: `entity_id IN (${placeholders})`, params: [...entityIds] };
-  }
   /**
    * Hydrate full facts by ID. Pass scopedEntityIds to restrict to requested namespaces in SQL
    * (defense-in-depth against a rogue VectorRanker returning cross-entity IDs).
    */
-  async _hydrateFactsByIds(ids, scopedEntityIds) {
-    const fullRows = [];
-    const chunkSize = 500;
-    const entityClause = scopedEntityIds && scopedEntityIds.length > 0 ? ` AND entity_id IN (${scopedEntityIds.map(() => "?").join(",")})` : "";
-    const entityParams = scopedEntityIds && scopedEntityIds.length > 0 ? [...scopedEntityIds] : [];
-    for (let i = 0; i < ids.length; i += chunkSize) {
-      const idChunk = ids.slice(i, i + chunkSize);
-      const placeholders = idChunk.map(() => "?").join(",");
-      const chunkRows = await this.db.getAllAsync(
-        `SELECT * FROM ${this.prefix}entries WHERE id IN (${placeholders})${entityClause} AND deleted_at IS NULL`,
-        [...idChunk, ...entityParams]
-      );
-      fullRows.push(...chunkRows);
-    }
-    const byId = new Map(fullRows.map((row) => [row.id, row]));
-    return ids.map((id) => byId.get(id)).filter((fact) => fact !== void 0).map((fact) => {
-      const { embedding: _embedding, embedding_blob: _blob, ...rest } = fact;
-      return {
-        ...rest,
-        tags: typeof rest.tags === "string" ? JSON.parse(rest.tags) : rest.tags
-      };
-    });
+  async _hydrateFactsByIds(ids, scopedEntityIds, tx) {
+    return this.entryRepo.findByIds(ids, scopedEntityIds, tx);
   }
   /**
    * Strip potentially sensitive data from ranker errors before exposing to host callbacks.
@@ -1709,53 +2763,60 @@ After running the migration SQL, restart your application.`
     if (!["observation", "decision", "action", "outcome"].includes(eventType)) {
       eventType = "observation";
     }
-    await this.db.runAsync(`
-      INSERT INTO ${this.prefix}events (id, entity_id, event_type, summary, related_entry_id, created_at)
-      VALUES (?, ?, ?, ?, ?, ?)
-    `, [id, entityId, eventType, event.summary, event.related_entry_id || null, now]);
-    const threshold = this.options.config?.autoLibrarianThreshold || 20;
-    const [row, cp] = await Promise.all([
-      this.db.getFirstAsync(`SELECT COUNT(*) as count FROM ${this.prefix}events WHERE entity_id = ?`, [entityId]),
-      this.db.getFirstAsync(`SELECT * FROM ${this.prefix}checkpoints WHERE entity_id = ?`, [entityId])
-    ]);
-    const count = row?.count || 0;
-    let memoryCheckpoint = cp?.memory_checkpoint || 0;
-    if (memoryCheckpoint > count) memoryCheckpoint = 0;
-    if (count - memoryCheckpoint >= threshold) {
-      const jobKey = this._librarianKey(entityId);
-      if (!this.activeMaintenanceJobs.has(jobKey) && !this.activeMaintenanceJobs.has(this._pruneKey(entityId)) && !this._isReembedActive(entityId) && !this._isImportActiveFor(entityId) && !this._isForgetActiveFor(entityId)) {
-        this.activeMaintenanceJobs.add(jobKey);
-        this._notifyStatusSubscribers(entityId);
-        this.runLibrarianThenMaybeHeal(entityId, count).catch(console.error).finally(() => {
-          this.activeMaintenanceJobs.delete(jobKey);
-          this._notifyStatusSubscribers(entityId);
-        });
+    const newEvent = {
+      id,
+      entity_id: entityId,
+      event_type: eventType,
+      summary: event.summary,
+      related_entry_id: event.related_entry_id || null,
+      created_at: now
+    };
+    let shouldRunLibrarian = false;
+    let librarianCount = 0;
+    let librarianJobKey = null;
+    await this.db.withTransactionAsync(async (tx) => {
+      await this.eventRepo.add(newEvent, tx);
+      const threshold = this.options.config?.autoLibrarianThreshold || 20;
+      const [count, cp] = await Promise.all([
+        this.eventRepo.count(entityId, tx),
+        this.metadataRepo.getCheckpoint(entityId, tx)
+      ]);
+      let memoryCheckpoint = cp.memory ?? 0;
+      if (memoryCheckpoint > count) memoryCheckpoint = 0;
+      if (count - memoryCheckpoint >= threshold) {
+        const jobKey = this._librarianKey(entityId);
+        if (!this.activeMaintenanceJobs.has(jobKey) && !this.activeMaintenanceJobs.has(this._pruneKey(entityId)) && !this._isReembedActive(entityId) && !this._isImportActiveFor(entityId) && !this._isForgetActiveFor(entityId)) {
+          shouldRunLibrarian = true;
+          librarianCount = count;
+          librarianJobKey = jobKey;
+          await this.metadataRepo.updateCheckpoint(entityId, { memory: count }, tx);
+        }
       }
+    });
+    if (shouldRunLibrarian && librarianJobKey !== null) {
+      this.activeMaintenanceJobs.add(librarianJobKey);
+      this._notifyStatusSubscribers(entityId);
+      this.runLibrarianThenMaybeHeal(entityId, librarianCount).catch(console.error).finally(() => {
+        this.activeMaintenanceJobs.delete(librarianJobKey);
+        this._notifyStatusSubscribers(entityId);
+      });
     }
   }
   async runLibrarianThenMaybeHeal(entityId, currentEventCount) {
     await this._doRunLibrarian(entityId);
-    await this.db.runAsync(`
-      INSERT INTO ${this.prefix}checkpoints (entity_id, memory_checkpoint) 
-      VALUES (?, ?) 
-      ON CONFLICT(entity_id) DO UPDATE SET memory_checkpoint = ?
-    `, [entityId, currentEventCount, currentEventCount]);
     const autoHealThreshold = this.options.config?.autoHealThreshold || 100;
-    const cp = await this.db.getFirstAsync(`SELECT * FROM ${this.prefix}checkpoints WHERE entity_id = ?`, [entityId]);
-    let healCheckpoint = cp?.heal_checkpoint || 0;
+    const cp = await this.metadataRepo.getCheckpoint(entityId, this.db);
+    let healCheckpoint = cp.heal ?? 0;
     if (healCheckpoint > currentEventCount) healCheckpoint = 0;
-    if (currentEventCount - healCheckpoint >= autoHealThreshold) {
+    const shouldRunHeal = currentEventCount - healCheckpoint >= autoHealThreshold;
+    if (shouldRunHeal) {
       const healKey = this._healKey(entityId);
       if (!this.activeMaintenanceJobs.has(healKey)) {
         this.activeMaintenanceJobs.add(healKey);
         this._notifyStatusSubscribers(entityId);
         try {
           await this._doRunHeal(entityId);
-          await this.db.runAsync(`
-            INSERT INTO ${this.prefix}checkpoints (entity_id, heal_checkpoint) 
-            VALUES (?, ?) 
-            ON CONFLICT(entity_id) DO UPDATE SET heal_checkpoint = ?
-          `, [entityId, currentEventCount, currentEventCount]);
+          await this.metadataRepo.updateCheckpoint(entityId, { heal: currentEventCount }, this.db);
         } finally {
           this.activeMaintenanceJobs.delete(healKey);
           this._notifyStatusSubscribers(entityId);
@@ -1764,18 +2825,8 @@ After running the migration SQL, restart your application.`
     }
   }
   async _doRunLibrarian(entityId) {
-    const events = await this.db.getAllAsync(`
-      SELECT * FROM ${this.prefix}events
-      WHERE entity_id = ?
-      ORDER BY created_at DESC
-      LIMIT 50
-    `, [entityId]);
-    const currentFactsRows = await this.db.getAllAsync(`
-      SELECT * FROM ${this.prefix}entries
-      WHERE entity_id = ? AND deleted_at IS NULL
-      ORDER BY updated_at DESC
-      LIMIT 100
-    `, [entityId]);
+    const events = await this.eventRepo.getRecent(entityId, 50);
+    const currentFactsRows = await this.entryRepo.findRecentByEntityId(entityId, 100);
     const currentFacts = currentFactsRows.map((f) => {
       const { embedding: _embedding, embedding_blob: _blob, ...rest } = f;
       return {
@@ -1799,12 +2850,13 @@ ${JSON.stringify(currentFacts, null, 2)}`;
     const validTasks = tasks.map(validateTask).filter((t) => t !== null);
     const now = Date.now();
     const insertedFacts = [];
-    await this.db.withTransactionAsync(async () => {
+    await this.db.withTransactionAsync(async (tx) => {
+      const factsForDedupe = await this.entryRepo.findRecentByEntityId(entityId, 100, tx);
       for (const fact of validFacts) {
         const newTokens = titleTokens(fact.title);
         let skip = false;
         if (newTokens.size >= MIN_TOKENS_TO_QUALIFY) {
-          for (const existing of currentFactsRows) {
+          for (const existing of factsForDedupe) {
             if (existing.source_type !== "librarian_inferred") continue;
             const existingTokens = titleTokens(existing.title);
             if (existingTokens.size >= MIN_TOKENS_TO_QUALIFY) {
@@ -1817,18 +2869,29 @@ ${JSON.stringify(currentFacts, null, 2)}`;
         }
         if (skip) continue;
         const id = generateId("fact_");
-        await this.db.runAsync(`
-          INSERT INTO ${this.prefix}entries (id, entity_id, title, body, tags, confidence, source_type, created_at, updated_at)
-          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-        `, [id, entityId, fact.title, fact.body, JSON.stringify(fact.tags), fact.confidence, "librarian_inferred", now, now]);
+        const factObj = {
+          id,
+          entity_id: entityId,
+          title: fact.title,
+          body: fact.body,
+          tags: fact.tags,
+          confidence: fact.confidence,
+          source_type: "librarian_inferred",
+          source_hash: null,
+          source_ref: null,
+          created_at: now,
+          updated_at: now,
+          last_accessed_at: null,
+          access_count: 0,
+          deleted_at: null
+        };
+        await this.entryRepo.upsert(factObj, tx);
         insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
       }
       for (const task of validTasks) {
         const id = generateId("task_");
-        await this.db.runAsync(`
-          INSERT INTO ${this.prefix}tasks (id, entity_id, description, status, priority, created_at, updated_at)
-          VALUES (?, ?, ?, ?, ?, ?, ?)
-        `, [id, entityId, task.description, "pending", task.priority, now, now]);
+        const taskObj = { id, entity_id: entityId, description: task.description, status: "pending", priority: task.priority, created_at: now, updated_at: now, resolved_at: null, deleted_at: null };
+        await this.taskRepo.upsert(taskObj, tx);
       }
     });
     await this.rebuildMiniSearchIndex(entityId);
@@ -1849,27 +2912,19 @@ ${JSON.stringify(currentFacts, null, 2)}`;
     if (staleInferredAfterDays !== null && (typeof staleInferredAfterDays !== "number" || !Number.isFinite(staleInferredAfterDays) || staleInferredAfterDays < 0)) {
       throw new Error("Invalid staleInferredAfterDays: must be a finite number >= 0 or null");
     }
-    await this.db.withTransactionAsync(async () => {
+    await this.db.withTransactionAsync(async (tx) => {
       if (orphanAfterDays !== null) {
         const orphanThreshold = now - orphanAfterDays * MS_PER_DAY;
-        await this.db.runAsync(`
-          UPDATE ${this.prefix}entries
-          SET deleted_at = ?, updated_at = ?
-          WHERE entity_id = ? AND access_count = 0 AND created_at <= ? AND source_type != 'immutable_document' AND deleted_at IS NULL
-        `, [now, now, entityId, orphanThreshold]);
+        await this.entryRepo.markOrphaned(entityId, orphanThreshold, tx);
       }
       if (staleInferredAfterDays !== null) {
         const staleThreshold = now - staleInferredAfterDays * MS_PER_DAY;
-        await this.db.runAsync(`
-          UPDATE ${this.prefix}entries
-          SET confidence = 'tentative', updated_at = ?
-          WHERE entity_id = ? AND confidence = 'inferred' AND (last_accessed_at <= ? OR (last_accessed_at IS NULL AND created_at <= ?)) AND source_type != 'immutable_document' AND deleted_at IS NULL
-        `, [now, entityId, staleThreshold, staleThreshold]);
+        await this.entryRepo.downgradeStaleInferred(entityId, staleThreshold, tx);
       }
     });
-    const allFactsRows = await this.db.getAllAsync(`SELECT * FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL`, [entityId]);
-    const allTasks = await this.db.getAllAsync(`SELECT * FROM ${this.prefix}tasks WHERE entity_id = ? AND status IN ('pending', 'in_progress') AND deleted_at IS NULL`, [entityId]);
-    const recentEvents = await this.db.getAllAsync(`SELECT * FROM ${this.prefix}events WHERE entity_id = ? ORDER BY created_at DESC LIMIT 20`, [entityId]);
+    const allFactsRows = await this.entryRepo.findAllByEntityId(entityId);
+    const allTasks = await this.taskRepo.findAllPending([entityId]);
+    const recentEvents = await this.eventRepo.getRecent(entityId, 20);
     const healCandidates = allFactsRows.filter((f) => f.source_type !== "immutable_document");
     const documentAnchors = allFactsRows.filter((f) => f.source_type === "immutable_document").map(({ id, title, source_ref }) => ({ id, title, source_ref }));
     const userPrompt = `Heal Candidates:
@@ -1902,19 +2957,28 @@ The following document anchors are provided for contradiction detection only. Do
     const validNewFacts = newFacts.map(validateFact).filter((f) => f !== null);
     const insertedFacts = [];
     const uniqueDeletedFactIds = Array.from(new Set(safeDeleted));
-    await this.db.withTransactionAsync(async () => {
-      for (const id of safeDowngraded) {
-        await this.db.runAsync(`UPDATE ${this.prefix}entries SET confidence = 'tentative', updated_at = ? WHERE id = ? AND entity_id = ?`, [now, id, entityId]);
-      }
-      for (const id of safeDeleted) {
-        await this.db.runAsync(`UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE id = ? AND entity_id = ?`, [now, now, id, entityId]);
-      }
+    await this.db.withTransactionAsync(async (tx) => {
+      await this.entryRepo.downgradeByIds(safeDowngraded, entityId, tx);
+      await this.entryRepo.softDeleteByIds(safeDeleted, entityId, tx);
       for (const fact of validNewFacts) {
         const id = generateId("fact_");
-        await this.db.runAsync(`
-          INSERT INTO ${this.prefix}entries (id, entity_id, title, body, tags, confidence, source_type, created_at, updated_at)
-          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-        `, [id, entityId, fact.title, fact.body, JSON.stringify(fact.tags), fact.confidence, "librarian_inferred", now, now]);
+        const factObj = {
+          id,
+          entity_id: entityId,
+          title: fact.title,
+          body: fact.body,
+          tags: fact.tags,
+          confidence: fact.confidence,
+          source_type: "librarian_inferred",
+          source_hash: null,
+          source_ref: null,
+          created_at: now,
+          updated_at: now,
+          last_accessed_at: null,
+          access_count: 0,
+          deleted_at: null
+        };
+        await this.entryRepo.upsert(factObj, tx);
         insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
       }
     });
@@ -2038,12 +3102,7 @@ The following document anchors are provided for contradiction detection only. Do
     }
     this.activeMaintenanceJobs.add(reembedKey);
     try {
-      const where = entityId ? `entity_id = ? AND deleted_at IS NULL` : `deleted_at IS NULL`;
-      const params = entityId ? [entityId] : [];
-      const rows = await this.db.getAllAsync(
-        `SELECT * FROM ${this.prefix}entries WHERE ${where}`,
-        params
-      );
+      const rows = await this.entryRepo.findAllForReembed(entityId);
       if (entityId) {
         this.vectorCache.delete(entityId);
       } else {
@@ -2052,22 +3111,12 @@ The following document anchors are provided for contradiction detection only. Do
       const skipExisting = opts?.skipExisting ?? false;
       let effectiveSkip = skipExisting;
       if (skipExisting) {
-        const mismatchRow = await this.db.getFirstAsync(
-          `SELECT value FROM ${this.prefix}meta WHERE key = 'embedding_dimension_mismatch'`
-        );
-        if (mismatchRow) {
+        const mismatchValue = await this.metadataRepo.getMeta("embedding_dimension_mismatch");
+        if (mismatchValue) {
           if (entityId) {
-            const mismatchDim = parseInt(mismatchRow.value, 10);
-            const staleForEntity = await this.db.getFirstAsync(
-              `SELECT COUNT(*) AS cnt FROM ${this.prefix}entries
-               WHERE entity_id = ? AND deleted_at IS NULL
-                 AND (
-                   embedding_blob IS NULL
-                   OR (CAST(length(embedding_blob) AS INTEGER) / 4) != ?
-                 )`,
-              [entityId, mismatchDim]
-            );
-            if (staleForEntity && staleForEntity.cnt > 0) effectiveSkip = false;
+            const mismatchDim = parseInt(mismatchValue, 10);
+            const staleCount = await this.entryRepo.countStaleForEntity(entityId, mismatchDim);
+            if (staleCount > 0) effectiveSkip = false;
           } else {
             effectiveSkip = false;
           }
@@ -2159,19 +3208,10 @@ The following document anchors are provided for contradiction detection only. Do
     this.vectorCache.clear();
   }
   async _getFullBundle(entityId, opts) {
-    const maxEvents = opts?.maxEvents;
-    const eventsQuery = maxEvents != null ? `SELECT * FROM ${this.prefix}events WHERE entity_id = ? ORDER BY created_at DESC LIMIT ?` : `SELECT * FROM ${this.prefix}events WHERE entity_id = ? ORDER BY created_at ASC`;
-    const eventsParams = maxEvents != null ? [entityId, maxEvents] : [entityId];
-    const [factsRaw, tasks, eventsRaw] = await Promise.all([
-      this.db.getAllAsync(
-        `SELECT * FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL ORDER BY updated_at DESC`,
-        [entityId]
-      ),
-      this.db.getAllAsync(
-        `SELECT * FROM ${this.prefix}tasks WHERE entity_id = ? AND deleted_at IS NULL ORDER BY priority DESC, created_at ASC`,
-        [entityId]
-      ),
-      this.db.getAllAsync(eventsQuery, eventsParams)
+    const [factsRaw, tasks, events] = await Promise.all([
+      this.entryRepo.findAllByEntityId(entityId),
+      this.taskRepo.findAllByEntityId(entityId),
+      this.eventRepo.getByEntityId(entityId, opts?.maxEvents)
     ]);
     const facts = factsRaw.map((f) => {
       const { embedding: _embedding, embedding_blob, ...rest } = f;
@@ -2186,7 +3226,6 @@ The following document anchors are provided for contradiction detection only. Do
         tags: typeof factBase.tags === "string" ? JSON.parse(factBase.tags) : factBase.tags
       };
     });
-    const events = maxEvents != null ? eventsRaw.slice().reverse() : eventsRaw;
     return { facts, tasks, events };
   }
   async exportDump(entityIds) {
@@ -2194,16 +3233,7 @@ The following document anchors are provided for contradiction detection only. Do
     if (entityIds && entityIds.length > 0) {
       ids = Array.from(new Set(entityIds));
     } else {
-      const rows = await this.db.getAllAsync(`
-        SELECT DISTINCT entity_id FROM (
-          SELECT entity_id FROM ${this.prefix}entries WHERE deleted_at IS NULL
-          UNION
-          SELECT entity_id FROM ${this.prefix}tasks WHERE deleted_at IS NULL
-          UNION
-          SELECT entity_id FROM ${this.prefix}events
-        ) ORDER BY entity_id
-      `);
-      ids = rows.map((r) => r.entity_id);
+      ids = await this.metadataRepo.getDistinctEntityIds();
     }
     const entities = {};
     const BATCH = 3;
@@ -2269,48 +3299,26 @@ The following document anchors are provided for contradiction detection only. Do
     const factsWithPreservedBlob = /* @__PURE__ */ new Map();
     const preservedBlobDims = /* @__PURE__ */ new Set();
     const softDeletedFactIds = [];
-    await this.db.withTransactionAsync(async () => {
+    await this.db.withTransactionAsync(async (tx) => {
       if (!merge) {
-        const toDelete = await this.db.getAllAsync(
-          `SELECT id FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL`,
-          [entityId]
-        );
-        softDeletedFactIds.push(...toDelete.map((r) => r.id));
-        const now = Date.now();
-        await this.db.runAsync(
-          `UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`,
-          [now, now, entityId]
-        );
-        await this.db.runAsync(
-          `UPDATE ${this.prefix}tasks SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`,
-          [now, now, entityId]
-        );
-        await this.db.runAsync(
-          `DELETE FROM ${this.prefix}checkpoints WHERE entity_id = ?`,
-          [entityId]
-        );
+        const deletedLiveFactIds = await this.entryRepo.findIdsBySource(entityId, null, null, tx, false);
+        softDeletedFactIds.push(...deletedLiveFactIds);
+        await this.entryRepo.bulkSoftDeleteByEntityId(entityId, tx);
+        await this.taskRepo.bulkSoftDeleteByEntityId(entityId, tx);
+        await this.metadataRepo.deleteCheckpoint(entityId, tx);
       }
       const factIds = bundle.facts.map((fact) => fact.id);
       const existingFactsById = /* @__PURE__ */ new Map();
-      const factLookupChunkSize = 500;
-      for (let i = 0; i < factIds.length; i += factLookupChunkSize) {
-        const factIdChunk = factIds.slice(i, i + factLookupChunkSize);
-        if (factIdChunk.length === 0) continue;
-        const placeholders = factIdChunk.map(() => "?").join(", ");
-        const existingFacts = await this.db.getAllAsync(
-          `SELECT id, entity_id, updated_at FROM ${this.prefix}entries WHERE id IN (${placeholders})`,
-          factIdChunk
-        );
-        for (const existingFact of existingFacts) {
-          existingFactsById.set(existingFact.id, existingFact);
-        }
+      const existingFacts = await this.entryRepo.findExistingMetadataByIds(factIds, tx);
+      for (const existingFact of existingFacts) {
+        existingFactsById.set(existingFact.id, existingFact);
       }
       for (const fact of bundle.facts) {
         const sourceType = this._normalizeImportedSourceType(String(fact.source_type), {
           entityId,
           factId: fact.id
         });
-        const tagsJson = JSON.stringify(Array.isArray(fact.tags) ? fact.tags : []);
+        JSON.stringify(Array.isArray(fact.tags) ? fact.tags : []);
         const safeUpdatedAt = Number.isFinite(fact.updated_at) ? fact.updated_at : 0;
         const existing = existingFactsById.get(fact.id);
         const rawBlobRaw = fact.embedding_blob;
@@ -2355,55 +3363,38 @@ The following document anchors are provided for contradiction detection only. Do
           if (merge) {
             if (safeUpdatedAt <= existing.updated_at) continue;
           }
-          if (blobData != null) {
-            await this.db.runAsync(
-              `UPDATE ${this.prefix}entries SET entity_id = ?, title = ?, body = ?, tags = ?, confidence = ?, source_type = ?, source_hash = ?, source_ref = ?, created_at = ?, updated_at = ?, last_accessed_at = ?, access_count = ?, deleted_at = ?, embedding_blob = ?, embedding = NULL WHERE id = ?`,
-              [entityId, fact.title, fact.body, tagsJson, fact.confidence, sourceType, fact.source_hash, fact.source_ref, fact.created_at, safeUpdatedAt, fact.last_accessed_at, fact.access_count, fact.deleted_at, blobData, fact.id]
-            );
-            factsWithPreservedBlob.set(fact.id, blobData);
-            if (!fact.deleted_at) preservedBlobDims.add(blobData.byteLength / 4);
-          } else {
-            await this.db.runAsync(
-              `UPDATE ${this.prefix}entries SET entity_id = ?, title = ?, body = ?, tags = ?, confidence = ?, source_type = ?, source_hash = ?, source_ref = ?, created_at = ?, updated_at = ?, last_accessed_at = ?, access_count = ?, deleted_at = ?, embedding_blob = NULL, embedding = NULL WHERE id = ?`,
-              [entityId, fact.title, fact.body, tagsJson, fact.confidence, sourceType, fact.source_hash, fact.source_ref, fact.created_at, safeUpdatedAt, fact.last_accessed_at, fact.access_count, fact.deleted_at, fact.id]
-            );
-          }
-          existingFactsById.set(fact.id, { id: fact.id, entity_id: entityId, updated_at: safeUpdatedAt });
-          upsertedFactIds.add(fact.id);
-          if (fact.deleted_at) upsertedDeletedFactIds.add(fact.id);
-        } else {
-          if (blobData != null) {
-            await this.db.runAsync(
-              `INSERT INTO ${this.prefix}entries (id, entity_id, title, body, tags, confidence, source_type, source_hash, source_ref, created_at, updated_at, last_accessed_at, access_count, deleted_at, embedding_blob) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-              [fact.id, entityId, fact.title, fact.body, tagsJson, fact.confidence, sourceType, fact.source_hash, fact.source_ref, fact.created_at, safeUpdatedAt, fact.last_accessed_at, fact.access_count, fact.deleted_at, blobData]
-            );
-            factsWithPreservedBlob.set(fact.id, blobData);
-            if (!fact.deleted_at) preservedBlobDims.add(blobData.byteLength / 4);
-          } else {
-            await this.db.runAsync(
-              `INSERT INTO ${this.prefix}entries (id, entity_id, title, body, tags, confidence, source_type, source_hash, source_ref, created_at, updated_at, last_accessed_at, access_count, deleted_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-              [fact.id, entityId, fact.title, fact.body, tagsJson, fact.confidence, sourceType, fact.source_hash, fact.source_ref, fact.created_at, safeUpdatedAt, fact.last_accessed_at, fact.access_count, fact.deleted_at]
-            );
-          }
-          existingFactsById.set(fact.id, { id: fact.id, entity_id: entityId, updated_at: safeUpdatedAt });
-          upsertedFactIds.add(fact.id);
-          if (fact.deleted_at) upsertedDeletedFactIds.add(fact.id);
         }
+        const factObj = {
+          id: fact.id,
+          entity_id: entityId,
+          title: fact.title,
+          body: fact.body,
+          tags: Array.isArray(fact.tags) ? fact.tags : [],
+          confidence: fact.confidence,
+          source_type: sourceType,
+          source_hash: fact.source_hash,
+          source_ref: fact.source_ref,
+          created_at: fact.created_at,
+          updated_at: safeUpdatedAt,
+          last_accessed_at: fact.last_accessed_at,
+          access_count: fact.access_count,
+          deleted_at: fact.deleted_at,
+          embedding_blob: blobData ?? void 0
+        };
+        await this.entryRepo.upsertForImport(factObj, tx);
+        if (blobData != null) {
+          factsWithPreservedBlob.set(fact.id, blobData);
+          if (!fact.deleted_at) preservedBlobDims.add(blobData.byteLength / 4);
+        }
+        existingFactsById.set(fact.id, { id: fact.id, entity_id: entityId, updated_at: safeUpdatedAt });
+        upsertedFactIds.add(fact.id);
+        if (fact.deleted_at) upsertedDeletedFactIds.add(fact.id);
       }
       const taskIds = bundle.tasks.map((task) => task.id);
       const existingTasksById = /* @__PURE__ */ new Map();
-      const taskLookupChunkSize = 500;
-      for (let i = 0; i < taskIds.length; i += taskLookupChunkSize) {
-        const taskIdChunk = taskIds.slice(i, i + taskLookupChunkSize);
-        if (taskIdChunk.length === 0) continue;
-        const placeholders = taskIdChunk.map(() => "?").join(", ");
-        const existingTasks = await this.db.getAllAsync(
-          `SELECT id, entity_id, updated_at FROM ${this.prefix}tasks WHERE id IN (${placeholders})`,
-          taskIdChunk
-        );
-        for (const existingTask of existingTasks) {
-          existingTasksById.set(existingTask.id, existingTask);
-        }
+      const existingTasks = await this.taskRepo.findExistingMetadataByIds(taskIds, tx);
+      for (const existingTask of existingTasks) {
+        existingTasksById.set(existingTask.id, existingTask);
       }
       for (const task of bundle.tasks) {
         const safeUpdatedAt = Number.isFinite(task.updated_at) ? task.updated_at : 0;
@@ -2416,25 +3407,29 @@ The following document anchors are provided for contradiction detection only. Do
           if (merge) {
             if (safeUpdatedAt <= existing.updated_at) continue;
           }
-          await this.db.runAsync(
-            `UPDATE ${this.prefix}tasks SET entity_id = ?, description = ?, status = ?, priority = ?, created_at = ?, updated_at = ?, resolved_at = ?, deleted_at = ? WHERE id = ?`,
-            [entityId, task.description, task.status, task.priority, task.created_at, safeUpdatedAt, task.resolved_at, task.deleted_at, task.id]
-          );
-          existingTasksById.set(task.id, { id: task.id, entity_id: entityId, updated_at: safeUpdatedAt });
-        } else {
-          await this.db.runAsync(
-            `INSERT INTO ${this.prefix}tasks (id, entity_id, description, status, priority, created_at, updated_at, resolved_at, deleted_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-            [task.id, entityId, task.description, task.status, task.priority, task.created_at, safeUpdatedAt, task.resolved_at, task.deleted_at]
-          );
-          existingTasksById.set(task.id, { id: task.id, entity_id: entityId, updated_at: safeUpdatedAt });
         }
+        await this.taskRepo.upsertForImport({
+          id: task.id,
+          entity_id: entityId,
+          description: task.description,
+          status: task.status,
+          priority: task.priority,
+          created_at: task.created_at,
+          updated_at: safeUpdatedAt,
+          resolved_at: task.resolved_at,
+          deleted_at: task.deleted_at
+        }, tx, safeUpdatedAt);
+        existingTasksById.set(task.id, { id: task.id, entity_id: entityId, updated_at: safeUpdatedAt });
       }
       for (const event of bundle.events) {
-        await this.db.runAsync(
-          `INSERT OR IGNORE INTO ${this.prefix}events (id, entity_id, event_type, summary, related_entry_id, created_at)
-             VALUES (?, ?, ?, ?, ?, ?)`,
-          [event.id, entityId, event.event_type, event.summary, event.related_entry_id ?? null, event.created_at]
-        );
+        await this.eventRepo.addIgnoreDuplicate({
+          id: event.id,
+          entity_id: entityId,
+          event_type: event.event_type,
+          summary: event.summary,
+          related_entry_id: event.related_entry_id ?? null,
+          created_at: event.created_at
+        }, tx);
       }
     });
     this.vectorCache.delete(entityId);
@@ -2472,43 +3467,27 @@ The following document anchors are provided for contradiction detection only. Do
       }
     }
     try {
-      const canonicalRow = await this.db.getFirstAsync(
-        `SELECT value FROM ${this.prefix}meta WHERE key = 'embedding_dimension'`
-      );
-      const canonicalDim = canonicalRow ? parseInt(canonicalRow.value, 10) : null;
+      const canonicalDimValue = await this.metadataRepo.getMeta("embedding_dimension");
+      const canonicalDim = canonicalDimValue ? parseInt(canonicalDimValue, 10) : null;
       if (preservedBlobDims.size === 1) {
         const preservedDim = [...preservedBlobDims][0];
         if (canonicalDim === null || canonicalDim === preservedDim) {
           await this.storeEmbeddingDimension(preservedDim);
-          const staleMismatch = await this.db.getFirstAsync(
-            `SELECT value FROM ${this.prefix}meta WHERE key = 'embedding_dimension_mismatch'`
-          );
-          if (staleMismatch && parseInt(staleMismatch.value, 10) !== preservedDim) {
-            await this.db.runAsync(
-              `INSERT OR REPLACE INTO ${this.prefix}meta (key, value) VALUES ('embedding_dimension_mismatch', ?)`,
-              [String(preservedDim)]
-            );
+          const staleMismatchValue = await this.metadataRepo.getMeta("embedding_dimension_mismatch");
+          if (staleMismatchValue && parseInt(staleMismatchValue, 10) !== preservedDim) {
+            await this.metadataRepo.setMeta("embedding_dimension_mismatch", String(preservedDim), this.db);
           }
           await this._reconcileEmbeddingDimension();
         } else {
-          await this.db.runAsync(
-            `INSERT OR REPLACE INTO ${this.prefix}meta (key, value) VALUES ('embedding_dimension_mismatch', ?)`,
-            [String(canonicalDim)]
-          );
+          await this.metadataRepo.setMeta("embedding_dimension_mismatch", String(canonicalDim), this.db);
         }
       } else if (preservedBlobDims.size > 1) {
         if (canonicalDim === null) {
           const sortedPreservedBlobDims = [...preservedBlobDims].sort((a, b) => a - b);
           await this.storeEmbeddingDimension(sortedPreservedBlobDims[0]);
-          await this.db.runAsync(
-            `INSERT OR REPLACE INTO ${this.prefix}meta (key, value) VALUES ('embedding_dimension_mismatch', ?)`,
-            [String(sortedPreservedBlobDims[0])]
-          );
+          await this.metadataRepo.setMeta("embedding_dimension_mismatch", String(sortedPreservedBlobDims[0]), this.db);
         } else {
-          await this.db.runAsync(
-            `INSERT OR REPLACE INTO ${this.prefix}meta (key, value) VALUES ('embedding_dimension_mismatch', ?)`,
-            [String(canonicalDim)]
-          );
+          await this.metadataRepo.setMeta("embedding_dimension_mismatch", String(canonicalDim), this.db);
         }
       }
     } finally {
@@ -2542,79 +3521,44 @@ The following document anchors are provided for contradiction detection only. Do
       let deletedEntries = 0;
       let deletedTasks = 0;
       const deletedEntryIds = [];
-      if (params.clearAll) {
-        const newDeletions = await this.db.getAllAsync(
-          `SELECT id FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL`,
-          [entityId]
-        );
-        const alreadySoftDeleted = await this.db.getAllAsync(
-          `SELECT id FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NOT NULL`,
-          [entityId]
-        );
-        deletedEntryIds.push(...newDeletions.map((e) => e.id), ...alreadySoftDeleted.map((e) => e.id));
-        const [entriesRes, tasksRes] = await Promise.all([
-          this.db.runAsync(`UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`, [now, now, entityId]),
-          this.db.runAsync(`UPDATE ${this.prefix}tasks SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`, [now, now, entityId])
-        ]);
-        await this.db.runAsync(`UPDATE ${this.prefix}checkpoints SET memory_checkpoint = 0, heal_checkpoint = 0 WHERE entity_id = ?`, [entityId]);
-        deletedEntries = entriesRes.changes;
-        deletedTasks = tasksRes.changes;
-      } else {
-        const hasIdSelectors = params.entryId !== void 0 || params.taskId !== void 0;
-        const hasSourceSelectors = params.sourceRef !== void 0 || params.sourceHash !== void 0;
-        if (hasIdSelectors && hasSourceSelectors) {
-          throw new Error("forget() params are mutually exclusive: use entryId/taskId together, or sourceRef/sourceHash together, but not both in the same call");
-        }
-        const sourceRef = params.sourceRef !== void 0 ? normalizeSourceRef(params.sourceRef) : null;
-        if (params.sourceRef !== void 0 && !sourceRef) throw new Error("Invalid sourceRef");
-        const sourceHash = params.sourceHash !== void 0 ? normalizeSourceHash(params.sourceHash) : null;
-        if (params.sourceHash !== void 0 && !sourceHash) throw new Error("Invalid sourceHash (must be 64-char hex string)");
-        if (params.entryId) {
-          const entry = await this.db.getFirstAsync(
-            `SELECT id FROM ${this.prefix}entries WHERE id = ? AND entity_id = ?`,
-            [params.entryId, entityId]
-          );
-          if (entry) deletedEntryIds.push(entry.id);
-        }
-        if (sourceRef || sourceHash) {
-          let q = `SELECT id FROM ${this.prefix}entries WHERE entity_id = ?`;
-          const args = [entityId];
-          if (sourceRef) {
-            q += ` AND source_ref = ?`;
-            args.push(sourceRef);
+      await this.db.withTransactionAsync(async (tx) => {
+        if (params.clearAll) {
+          deletedEntryIds.push(...await this.entryRepo.findIdsBySource(entityId, null, null, tx, true));
+          const entriesRes = await this.entryRepo.bulkSoftDeleteByEntityId(entityId, tx);
+          const tasksRes = await this.taskRepo.bulkSoftDeleteByEntityId(entityId, tx);
+          await this.metadataRepo.updateCheckpoint(entityId, { memory: 0, heal: 0 }, tx);
+          deletedEntries = entriesRes;
+          deletedTasks = tasksRes;
+        } else {
+          const hasIdSelectors = params.entryId !== void 0 || params.taskId !== void 0;
+          const hasSourceSelectors = params.sourceRef !== void 0 || params.sourceHash !== void 0;
+          if (hasIdSelectors && hasSourceSelectors) {
+            throw new Error("forget() params are mutually exclusive: use entryId/taskId together, or sourceRef/sourceHash together, but not both in the same call");
           }
-          if (sourceHash) {
-            q += ` AND source_hash = ?`;
-            args.push(sourceHash);
+          const sourceRef = params.sourceRef !== void 0 ? normalizeSourceRef(params.sourceRef) : null;
+          if (params.sourceRef !== void 0 && !sourceRef) throw new Error("Invalid sourceRef");
+          const sourceHash = params.sourceHash !== void 0 ? normalizeSourceHash(params.sourceHash) : null;
+          if (params.sourceHash !== void 0 && !sourceHash) throw new Error("Invalid sourceHash (must be 64-char hex string)");
+          if (params.entryId) {
+            const entryId = await this.entryRepo.findIdById(params.entryId, entityId, tx);
+            if (entryId) deletedEntryIds.push(entryId);
           }
-          const entriesToDelete = await this.db.getAllAsync(q, args);
-          deletedEntryIds.push(...entriesToDelete.map((e) => e.id));
-        }
-        const entryPromise = params.entryId ? this.db.runAsync(`UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE id = ? AND entity_id = ? AND deleted_at IS NULL`, [now, now, params.entryId, entityId]) : null;
-        const taskPromise = params.taskId ? this.db.runAsync(`UPDATE ${this.prefix}tasks SET deleted_at = ?, updated_at = ? WHERE id = ? AND entity_id = ? AND deleted_at IS NULL`, [now, now, params.taskId, entityId]) : null;
-        let refPromise = null;
-        if (sourceRef || sourceHash) {
-          let q = `UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`;
-          const args = [now, now, entityId];
-          if (sourceRef) {
-            q += ` AND source_ref = ?`;
-            args.push(sourceRef);
+          if (sourceRef || sourceHash) {
+            deletedEntryIds.push(...await this.entryRepo.findIdsBySource(entityId, sourceRef, sourceHash, tx, true));
           }
-          if (sourceHash) {
-            q += ` AND source_hash = ?`;
-            args.push(sourceHash);
-          }
-          refPromise = this.db.runAsync(q, args);
+          const entryPromise = params.entryId ? this.entryRepo.softDelete(params.entryId, entityId, tx).then((r) => r.changes > 0) : null;
+          const taskDeletedPromise = params.taskId ? this.taskRepo.softDeleteById(params.taskId, entityId, tx).then((r) => r.changes > 0) : null;
+          const refPromise = sourceRef || sourceHash ? this.entryRepo.softDeleteBySource(entityId, tx, sourceRef, sourceHash) : null;
+          const [entryResult, taskResult, refResult] = await Promise.all([
+            entryPromise ?? Promise.resolve(false),
+            taskDeletedPromise ?? Promise.resolve(false),
+            refPromise ?? Promise.resolve(0)
+          ]);
+          if (entryResult) deletedEntries++;
+          if (taskResult) deletedTasks++;
+          deletedEntries += refResult;
         }
-        const [entryResult, taskResult, refResult] = await Promise.all([
-          entryPromise ?? Promise.resolve(null),
-          taskPromise ?? Promise.resolve(null),
-          refPromise ?? Promise.resolve(null)
-        ]);
-        if (entryResult) deletedEntries += entryResult.changes;
-        if (taskResult) deletedTasks += taskResult.changes;
-        if (refResult) deletedEntries += refResult.changes;
-      }
+      });
       await this.rebuildMiniSearchIndex(entityId);
       this.vectorCache.delete(entityId);
       const uniqueDeletedIds = Array.from(new Set(deletedEntryIds));
@@ -2713,25 +3657,28 @@ ${chunk}`;
       const now = Date.now();
       const insertedFacts = [];
       const deletedSourceFactIds = [];
-      await this.db.withTransactionAsync(async () => {
-        const existingSourceFacts = await this.db.getAllAsync(
-          `SELECT id FROM ${this.prefix}entries WHERE source_ref = ? AND entity_id = ? AND deleted_at IS NULL`,
-          [sourceRef, entityId]
-        );
-        for (const row of existingSourceFacts) {
-          deletedSourceFactIds.push(row.id);
-        }
-        await this.db.runAsync(
-          `UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE source_ref = ? AND entity_id = ? AND deleted_at IS NULL`,
-          [now, now, sourceRef, entityId]
-        );
+      await this.db.withTransactionAsync(async (tx) => {
+        deletedSourceFactIds.push(...await this.entryRepo.findIdsBySource(entityId, sourceRef, null, tx, false));
+        await this.entryRepo.softDeleteBySource(entityId, tx, sourceRef, null);
         for (const fact of allValidFacts) {
           const id = generateId("fact_");
-          await this.db.runAsync(
-            `INSERT INTO ${this.prefix}entries (id, entity_id, title, body, tags, confidence, source_type, source_hash, source_ref, created_at, updated_at)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-            [id, entityId, fact.title, fact.body, JSON.stringify(fact.tags), fact.confidence, "immutable_document", sourceHash, sourceRef, now, now]
-          );
+          const wikiFact = {
+            id,
+            entity_id: entityId,
+            title: fact.title,
+            body: fact.body,
+            tags: fact.tags,
+            confidence: fact.confidence,
+            source_type: "immutable_document",
+            source_hash: sourceHash,
+            source_ref: sourceRef,
+            created_at: now,
+            updated_at: now,
+            last_accessed_at: null,
+            access_count: 0,
+            deleted_at: null
+          };
+          await this.entryRepo.upsert(wikiFact, tx);
           insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
         }
       });