nlm-memory 0.4.0

package/dist/core/storage/sqlite-fact-store.js

@@ -0,0 +1,256 @@
+/**
+ * SqliteFactStore — the canonical FactStore implementation, sharing the same
+ * better-sqlite3 connection as SqliteSessionStore so session+facts ingest can
+ * commit in one transaction (Section 5 of factstore-design.md).
+ *
+ * Constructor takes an already-opened, already-migrated Database handle from
+ * SqliteSessionStore.rawDb(). It does not open its own connection. This is
+ * the only way to get a single-writer SQLite to behave atomically across
+ * both stores without WAL ordering surprises.
+ *
+ * Surface evolution:
+ *   B.1 — insert, getById, findCurrent, list, listBySession, markSuperseded
+ *   B.2 — insertManyInTxn (atomic session+facts ingest), embedding write helper
+ *   B.3 — listForRecall (pre-filter for FactRecallService), semanticSearch,
+ *         getHistory (supersedence chain inspection)
+ *   B.4 — auto-supersedence on (subject, predicate) collision (deferred)
+ */
+export class SqliteFactStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async insert(fact) {
+        this.insertStmt().run(this.toRow(fact));
+    }
+    async insertMany(facts) {
+        if (facts.length === 0)
+            return;
+        const stmt = this.insertStmt();
+        const txn = this.db.transaction((rows) => {
+            for (const row of rows)
+                stmt.run(row);
+        });
+        txn(facts.map((f) => this.toRow(f)));
+    }
+    /**
+     * Insert facts inside an already-open transaction (no own txn opened).
+     * Callable only from code that has already begun a transaction on the same
+     * connection — currently SqliteSessionStore.insertSession. Phase B.2: this
+     * is how session+facts ingest commits atomically (Section 5 of the plan).
+     */
+    insertManyInTxn(facts) {
+        if (facts.length === 0)
+            return;
+        const stmt = this.insertStmt();
+        for (const f of facts)
+            stmt.run(this.toRow(f));
+    }
+    async getById(id) {
+        const row = this.db
+            .prepare(`SELECT id, kind, subject, predicate, value, source_session_id,
+                source_quote, created_at, superseded_by, confidence
+         FROM facts WHERE id = ?`)
+            .get(id);
+        return row ? this.rowToFact(row) : null;
+    }
+    async findCurrent(subject, predicate) {
+        const row = this.db
+            .prepare(`SELECT id, kind, subject, predicate, value, source_session_id,
+                source_quote, created_at, superseded_by, confidence
+         FROM facts
+         WHERE subject = ? AND predicate = ? AND superseded_by IS NULL
+         ORDER BY created_at DESC
+         LIMIT 1`)
+            .get(subject, predicate);
+        return row ? this.rowToFact(row) : null;
+    }
+    async list(query) {
+        const limit = Math.max(1, Math.trunc(query.limit ?? 50));
+        const includeSuperseded = query.includeSuperseded === true;
+        const where = ["subject = ?"];
+        const params = [query.subject];
+        if (query.predicate !== undefined) {
+            where.push("predicate = ?");
+            params.push(query.predicate);
+        }
+        if (!includeSuperseded)
+            where.push("superseded_by IS NULL");
+        params.push(limit);
+        const rows = this.db
+            .prepare(`SELECT id, kind, subject, predicate, value, source_session_id,
+                source_quote, created_at, superseded_by, confidence
+         FROM facts
+         WHERE ${where.join(" AND ")}
+         ORDER BY created_at DESC
+         LIMIT ?`)
+            .all(...params);
+        return rows.map((r) => this.rowToFact(r));
+    }
+    async listBySession(sessionId) {
+        const rows = this.db
+            .prepare(`SELECT id, kind, subject, predicate, value, source_session_id,
+                source_quote, created_at, superseded_by, confidence
+         FROM facts
+         WHERE source_session_id = ?
+         ORDER BY created_at ASC`)
+            .all(sessionId);
+        return rows.map((r) => this.rowToFact(r));
+    }
+    async listForRecall(filter) {
+        const where = [];
+        const params = [];
+        if (filter.subject !== undefined) {
+            where.push("subject = ?");
+            params.push(filter.subject);
+        }
+        if (filter.predicate !== undefined) {
+            where.push("predicate = ?");
+            params.push(filter.predicate);
+        }
+        if (filter.kind !== undefined) {
+            where.push("kind = ?");
+            params.push(filter.kind);
+        }
+        if (filter.minConfidence !== undefined) {
+            where.push("confidence >= ?");
+            params.push(filter.minConfidence);
+        }
+        if (filter.includeSuperseded !== true) {
+            where.push("superseded_by IS NULL");
+        }
+        const limit = Math.max(1, Math.trunc(filter.limit ?? 500));
+        params.push(limit);
+        const sql = `
+      SELECT id, kind, subject, predicate, value, source_session_id,
+             source_quote, created_at, superseded_by, confidence
+      FROM facts
+      ${where.length > 0 ? "WHERE " + where.join(" AND ") : ""}
+      ORDER BY created_at DESC
+      LIMIT ?
+    `;
+        const rows = this.db
+            .prepare(sql)
+            .all(...params);
+        return rows.map((r) => this.rowToFact(r));
+    }
+    async semanticSearch(queryVector, limit) {
+        const k = Math.max(1, Math.trunc(limit));
+        const blob = Buffer.from(queryVector.buffer, queryVector.byteOffset, queryVector.byteLength);
+        const rows = this.db
+            .prepare(`
+        SELECT fact_id, distance
+        FROM fact_embeddings
+        WHERE embedding MATCH ?
+          AND k = ?
+        ORDER BY distance
+      `)
+            .all(blob, k);
+        return rows.map((r) => ({ factId: r.fact_id, distance: r.distance }));
+    }
+    async getHistory(subject, predicate) {
+        const sql = predicate
+            ? `SELECT id, kind, subject, predicate, value, source_session_id,
+                source_quote, created_at, superseded_by, confidence
+         FROM facts
+         WHERE subject = ? AND predicate = ?
+         ORDER BY predicate ASC, created_at DESC`
+            : `SELECT id, kind, subject, predicate, value, source_session_id,
+                source_quote, created_at, superseded_by, confidence
+         FROM facts
+         WHERE subject = ?
+         ORDER BY predicate ASC, created_at DESC`;
+        const rows = predicate
+            ? this.db.prepare(sql).all(subject, predicate)
+            : this.db.prepare(sql).all(subject);
+        const byPred = new Map();
+        for (const r of rows) {
+            const fact = this.rowToFact(r);
+            const bucket = byPred.get(fact.predicate);
+            if (bucket)
+                bucket.push(fact);
+            else
+                byPred.set(fact.predicate, [fact]);
+        }
+        const chains = [];
+        for (const [pred, history] of byPred.entries()) {
+            chains.push({ subject, predicate: pred, history });
+        }
+        return chains;
+    }
+    /**
+     * Insert (or replace) the embedding row for a fact. Best-effort: callers
+     * trap embedder errors so an unreachable Ollama doesn't roll back ingest.
+     * vec0 doesn't UPDATE, so this is a DELETE+INSERT pair.
+     */
+    upsertEmbedding(factId, vector) {
+        const blob = Buffer.from(vector.buffer, vector.byteOffset, vector.byteLength);
+        this.db.prepare("DELETE FROM fact_embeddings WHERE fact_id = ?").run(factId);
+        this.db
+            .prepare("INSERT INTO fact_embeddings (fact_id, embedding) VALUES (?, ?)")
+            .run(factId, blob);
+    }
+    async markSuperseded(oldId, newId) {
+        if (newId !== null && oldId === newId) {
+            throw new Error("A fact cannot supersede itself");
+        }
+        const txn = this.db.transaction(() => {
+            const old = this.db
+                .prepare("SELECT id FROM facts WHERE id = ?")
+                .get(oldId);
+            if (!old)
+                throw new Error(`Fact ${oldId} not found`);
+            if (newId !== null) {
+                const next = this.db
+                    .prepare("SELECT id FROM facts WHERE id = ?")
+                    .get(newId);
+                if (!next)
+                    throw new Error(`Fact ${newId} not found`);
+            }
+            this.db
+                .prepare("UPDATE facts SET superseded_by = ? WHERE id = ?")
+                .run(newId, oldId);
+        });
+        txn();
+    }
+    insertStmt() {
+        return this.db.prepare(`
+      INSERT INTO facts (
+        id, kind, subject, predicate, value, source_session_id,
+        source_quote, created_at, superseded_by, confidence
+      ) VALUES (
+        @id, @kind, @subject, @predicate, @value, @source_session_id,
+        @source_quote, @created_at, @superseded_by, @confidence
+      )
+    `);
+    }
+    toRow(fact) {
+        return {
+            id: fact.id,
+            kind: fact.kind,
+            subject: fact.subject,
+            predicate: fact.predicate,
+            value: fact.value,
+            source_session_id: fact.sourceSessionId,
+            source_quote: fact.sourceQuote,
+            created_at: fact.createdAt,
+            superseded_by: fact.supersededBy,
+            confidence: fact.confidence,
+        };
+    }
+    rowToFact(row) {
+        return {
+            id: row.id,
+            kind: row.kind,
+            subject: row.subject,
+            predicate: row.predicate,
+            value: row.value,
+            sourceSessionId: row.source_session_id,
+            sourceQuote: row.source_quote,
+            createdAt: row.created_at,
+            supersededBy: row.superseded_by,
+            confidence: row.confidence,
+        };
+    }
+}
+//# sourceMappingURL=sqlite-fact-store.js.map

package/dist/core/storage/sqlite-fact-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-fact-store.js","sourceRoot":"","sources":["../../../src/core/storage/sqlite-fact-store.ts"],"names":[],"mappings":"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"}

package/dist/core/storage/sqlite-session-store.d.ts

@@ -0,0 +1,152 @@
+/**
+ * SqliteSessionStore — the canonical SessionStore implementation backed by
+ * better-sqlite3 with the sqlite-vec extension loaded for KNN search.
+ *
+ * Layering note: core/ imports this concrete class only at the composition
+ * root (CLI / server bootstrap). The recall use case and every other piece
+ * of core depends on the SessionStore *port*, never on this file.
+ *
+ * Schema parity with the Python daemon: sessions row + session_entities +
+ * markers + session_embeddings (vec0). Idle-status overlay (computed from
+ * transcript mtime) is deferred to a later phase — A.2 returns the persisted
+ * status verbatim.
+ */
+import Database from "better-sqlite3";
+import type { KeywordNeighbor, SemanticNeighbor, SessionFilter, SessionStore } from "../../ports/session-store.js";
+import type { Session, SessionStatus } from "../../shared/types.js";
+import type { Fact } from "../../shared/types.js";
+import type { SqliteFactStore } from "./sqlite-fact-store.js";
+export interface SqliteSessionStoreOptions {
+    readonly dbPath: string;
+    readonly migrationsDir: string;
+    readonly readonly?: boolean;
+}
+/** Full ingest payload for SqliteSessionStore.insertSession. */
+export interface IngestRecord {
+    readonly id: string;
+    readonly runtime: string;
+    readonly runtimeSessionId: string | null;
+    readonly startedAt: string;
+    readonly endedAt: string | null;
+    readonly durationMin: number | null;
+    readonly label: string;
+    readonly summary: string;
+    readonly body: string | null;
+    readonly status: SessionStatus;
+    readonly transcriptKind: string | null;
+    readonly transcriptPath: string | null;
+    readonly transcriptOffset: number | null;
+    readonly transcriptLength: number | null;
+    readonly entities: ReadonlyArray<string>;
+    readonly decisions: ReadonlyArray<string>;
+    readonly openQuestions: ReadonlyArray<string>;
+}
+export interface RecentWrite {
+    id: string;
+    runtime: string;
+    label: string;
+    summary: string;
+    createdAt: string;
+}
+export interface RecentMarker {
+    sessionId: string;
+    kind: "decision" | "open";
+    text: string;
+    label: string;
+    createdAt: string;
+}
+export declare class SqliteSessionStore implements SessionStore {
+    private readonly db;
+    constructor(opts: SqliteSessionStoreOptions);
+    close(): void;
+    /**
+     * Drains the WAL into the main database and truncates the -wal file.
+     * WAL mode is on but nothing else checkpoints, so the file grows
+     * unbounded under continuous readers. The daemon calls this on an
+     * interval. Synchronous — keep the WAL small so each call is cheap.
+     */
+    checkpoint(): void;
+    /** Raw db handle for ingest helpers (Scheduler, scanOnce). Avoid using
+     *  directly from the recall path — it bypasses the SessionStore port. */
+    rawDb(): Database.Database;
+    /** Recently-written sessions ordered by created_at desc. Powers /live Writes column. */
+    recentWrites(limit: number): RecentWrite[];
+    /** Recently-extracted markers ordered by session created_at desc. Powers /live Decisions column. */
+    recentMarkers(limit: number): RecentMarker[];
+    /**
+     * Atomic ingest: writes the session row, markers, entity rows + links,
+     * supersedes edge (if any), and the embedding (best-effort) in one
+     * transaction. Idempotent on re-ingest — ON CONFLICT updates the session
+     * in place; markers are deleted and rewritten; entity links use INSERT OR
+     * IGNORE; embedding row is DELETE+INSERT (vec0 doesn't UPDATE).
+     *
+     * Mirrors Python's SQLiteStore.insert_session. Markdown projection is not
+     * yet ported and skipped here.
+     */
+    insertSession(record: IngestRecord, embedder?: import("../../ports/llm-client.js").LLMClient | null, supersedes?: string | null, factSink?: {
+        factStore: SqliteFactStore;
+        facts: ReadonlyArray<Fact>;
+    } | null): Promise<void>;
+    private deleteSessionChunks;
+    private insertChunkEmbedding;
+    /**
+     * Phase B.5 — backfill entry point. Writes facts (with deterministic
+     * supersedence + best-effort embeddings) for an EXISTING session row
+     * without touching it. Opens its own transaction; callers must not be
+     * inside one. The session row must already exist in `sessions` or the
+     * FK on facts.source_session_id rejects.
+     *
+     * Use this when ingesting facts after the fact — e.g. running the
+     * classifier across a historical corpus that predates the B.2 ingest
+     * write path. The live ingest path (`insertSession`) keeps using the
+     * internal helpers directly so session+facts commit together.
+     */
+    insertFactsForSession(sessionId: string, factStore: SqliteFactStore, facts: ReadonlyArray<Fact>, embedder?: import("../../ports/llm-client.js").LLMClient | null): Promise<void>;
+    /**
+     * Sync core of the fact-ingest block. Runs inside an EXISTING transaction
+     * — opens no txn of its own. Used by both `insertSession` (Phase B.2
+     * atomic ingest) and `insertFactsForSession` (Phase B.5 backfill).
+     *
+     * Behavior (mirrored across both callers):
+     *   1. DELETE prior facts attributed to this session (idempotent on
+     *      backfill, drops stale rows on re-ingest).
+     *   2. Insert all new facts atomically.
+     *   3. For each, mark the prior current (subject, predicate) fact as
+     *      superseded — Phase B.4 deterministic supersedence policy.
+     *
+     * Ordering: inserts before updates so the supersedence FK target exists.
+     * CASCADE-SET-NULL on `superseded_by` handles chain repair on re-ingest.
+     */
+    private applyFactsInTxn;
+    /**
+     * Best-effort per-fact embedding. Writes `${subject} ${predicate} ${value}`
+     * embeddings to fact_embeddings via FactStore.upsertEmbedding. Per-fact
+     * failures don't abort the batch, and never affect committed fact rows.
+     */
+    private embedFacts;
+    list(filter?: SessionFilter): Promise<ReadonlyArray<Session>>;
+    getById(sessionId: string): Promise<Session | null>;
+    /**
+     * Batched session fetch for the recall path. Deliberately omits the
+     * `body` column — body is ~48KB/row of session markdown that recall
+     * never reads, and SELECTing it for the corpus is what wedged the
+     * daemon. Resolved sessions carry `body: ""`.
+     */
+    getByIds(ids: ReadonlyArray<string>): Promise<ReadonlyArray<Session>>;
+    semanticSearch(queryVector: Float32Array, limit: number): Promise<ReadonlyArray<SemanticNeighbor>>;
+    /**
+     * Lexical recall via the sessions_fts FTS5 index. BM25 column weights
+     * favour label over summary over body. Returns sessions ranked best-first
+     * with a positive score (the negated bm25() value — bm25 is more negative
+     * for better matches). User input is tokenized and rebuilt into a quoted
+     * OR query so FTS5 metacharacters cannot reach the MATCH parser.
+     */
+    keywordSearch(query: string, limit: number): Promise<ReadonlyArray<KeywordNeighbor>>;
+    updateStatus(sessionId: string, status: SessionStatus): Promise<void>;
+    insertSessionForTest(session: Session): void;
+    insertEmbeddingForTest(sessionId: string, vector: Float32Array): void;
+    insertChunkEmbeddingForTest(sessionId: string, chunkIdx: number, vector: Float32Array): void;
+    private loadEntities;
+    private loadMarkers;
+    private rowToSession;
+}