nlm-memory 0.20.0 → 0.21.0

package/dist/cli/scope-backfill.js

@@ -0,0 +1,237 @@
+/**
+ * `nlm scope backfill`: derive and stamp scope on legacy corpus rows.
+ *
+ * Cascade order: sessions -> facts -> exemplars -> signals -> workstreams.
+ * --dry-run (default): computes would-change counts and writes nothing.
+ * --apply: writes; only fills scope IS NULL rows; idempotent.
+ */
+import { open } from "node:fs/promises";
+import Database from "better-sqlite3";
+import { deriveScope } from "../core/scope/derive-scope.js";
+/** Read at most this many bytes from the head of a transcript to find cwd. */
+const HEAD_BYTES = 8_192;
+/**
+ * Bounded head-read that matches the claude-code adapter's cwd extraction
+ * exactly (src/core/adapters/claude-code.ts:144):
+ *   if (!projectDir && typeof evt["cwd"] === "string") projectDir = evt["cwd"];
+ *
+ * Also covers pi-runtime JSONL: the pi adapter reads cwd from the
+ * `type: "session"` event on line 1 (src/core/adapters/pi.ts:124-126);
+ * taking the first `cwd` field on any line subsumes that shape.
+ *
+ * Reads at most HEAD_BYTES from the file start, splits into lines, parses
+ * each as JSON, and returns the value of the first "cwd" string field found.
+ * A first line longer than HEAD_BYTES arrives truncated, fails JSON.parse,
+ * and is skipped: fail-closed to NULL, never a mis-parse.
+ */
+async function readCwdFromTranscript(transcriptPath) {
+    let fd;
+    try {
+        fd = await open(transcriptPath, "r");
+        const buf = Buffer.alloc(HEAD_BYTES);
+        const { bytesRead } = await fd.read(buf, 0, HEAD_BYTES, 0);
+        const head = buf.toString("utf8", 0, bytesRead);
+        for (const line of head.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let evt;
+            try {
+                evt = JSON.parse(trimmed);
+            }
+            catch {
+                continue;
+            }
+            if (typeof evt["cwd"] === "string" && evt["cwd"]) {
+                return { cwd: evt["cwd"] };
+            }
+        }
+        return { cwd: null };
+    }
+    catch (err) {
+        const code = err.code;
+        const skipReason = code === "ENOENT" || code === "EACCES" || code === "EPERM"
+            ? "missing"
+            : "malformed";
+        return { cwd: null, skipReason };
+    }
+    finally {
+        await fd?.close().catch(() => { });
+    }
+}
+function inc(counter, scope) {
+    counter[scope] = (counter[scope] ?? 0) + 1;
+}
+function emptyTable() {
+    return { total: 0, byScope: {} };
+}
+export async function runScopeBackfill(opts) {
+    const { db, apply, aliasMap } = opts;
+    const sessionRows = db
+        .prepare("SELECT id, transcript_path FROM sessions WHERE scope IS NULL AND transcript_path IS NOT NULL")
+        .all();
+    const derivedScopes = new Map();
+    let missingCount = 0;
+    let malformedCount = 0;
+    let noCwdCount = 0;
+    for (const row of sessionRows) {
+        const { cwd, skipReason } = await readCwdFromTranscript(row.transcript_path);
+        if (skipReason === "missing") {
+            missingCount++;
+            continue;
+        }
+        if (skipReason === "malformed") {
+            malformedCount++;
+            continue;
+        }
+        if (!cwd) {
+            noCwdCount++;
+            continue;
+        }
+        const scope = deriveScope(cwd, aliasMap);
+        if (scope === null)
+            continue;
+        derivedScopes.set(row.id, scope);
+    }
+    const result = {
+        dryRun: !apply,
+        sessions: emptyTable(),
+        facts: emptyTable(),
+        exemplars: emptyTable(),
+        signals: emptyTable(),
+        workstreams: emptyTable(),
+        skipped: { missingTranscript: missingCount, malformed: malformedCount, noCwdFound: noCwdCount },
+    };
+    for (const scope of derivedScopes.values()) {
+        result.sessions.total++;
+        inc(result.sessions.byScope, scope);
+    }
+    const performUpdates = () => {
+        const updateSession = db.prepare("UPDATE sessions SET scope = ? WHERE id = ? AND scope IS NULL");
+        for (const [id, scope] of derivedScopes) {
+            updateSession.run(scope, id);
+        }
+        const factRows = db
+            .prepare(`
+        SELECT s.scope, COUNT(f.id) AS n
+        FROM facts f
+        JOIN sessions s ON f.source_session_id = s.id
+        WHERE f.scope IS NULL AND s.scope IS NOT NULL
+        GROUP BY s.scope
+      `)
+            .all();
+        for (const { scope, n } of factRows) {
+            result.facts.total += n;
+            inc(result.facts.byScope, scope);
+        }
+        db.prepare(`
+      UPDATE facts
+      SET scope = (SELECT s.scope FROM sessions s WHERE s.id = facts.source_session_id)
+      WHERE scope IS NULL
+        AND source_session_id IN (SELECT id FROM sessions WHERE scope IS NOT NULL)
+    `).run();
+        const exemplarRows = db
+            .prepare(`
+        SELECT s.scope, COUNT(e.id) AS n
+        FROM code_exemplars e
+        JOIN sessions s ON e.session_id = s.id
+        WHERE e.scope IS NULL AND s.scope IS NOT NULL
+        GROUP BY s.scope
+      `)
+            .all();
+        for (const { scope, n } of exemplarRows) {
+            result.exemplars.total += n;
+            inc(result.exemplars.byScope, scope);
+        }
+        db.prepare(`
+      UPDATE code_exemplars
+      SET scope = (SELECT s.scope FROM sessions s WHERE s.id = code_exemplars.session_id)
+      WHERE scope IS NULL
+        AND session_id IN (SELECT id FROM sessions WHERE scope IS NOT NULL)
+    `).run();
+        const signalRows = db
+            .prepare(`
+        SELECT s.scope, COUNT(sig.id) AS n
+        FROM signals sig
+        JOIN sessions s ON sig.session_id = s.id
+        WHERE sig.scope IS NULL AND s.scope IS NOT NULL AND s.scope != 'global'
+        GROUP BY s.scope
+      `)
+            .all();
+        for (const { scope, n } of signalRows) {
+            result.signals.total += n;
+            inc(result.signals.byScope, scope);
+        }
+        db.prepare(`
+      UPDATE signals
+      SET scope = (SELECT s.scope FROM sessions s WHERE s.id = signals.session_id)
+      WHERE scope IS NULL
+        AND session_id IS NOT NULL
+        AND session_id IN (
+          SELECT id FROM sessions WHERE scope IS NOT NULL AND scope != 'global'
+        )
+    `).run();
+        const pendingWorkstreams = db
+            .prepare("SELECT id FROM workstreams WHERE scope IS NULL")
+            .all();
+        const getMemberScopes = db.prepare("SELECT scope FROM sessions WHERE workstream_id = ?");
+        const updateWs = db.prepare("UPDATE workstreams SET scope = ? WHERE id = ? AND scope IS NULL");
+        for (const ws of pendingWorkstreams) {
+            const members = getMemberScopes.all(ws.id);
+            if (members.length === 0)
+                continue;
+            if (members.some((m) => m.scope === null))
+                continue;
+            const unique = new Set(members.map((m) => m.scope));
+            if (unique.size !== 1)
+                continue;
+            const wsScope = [...unique][0];
+            result.workstreams.total++;
+            inc(result.workstreams.byScope, wsScope);
+            updateWs.run(wsScope, ws.id);
+        }
+    };
+    if (apply) {
+        db.transaction(performUpdates)();
+    }
+    else {
+        db.exec("BEGIN");
+        try {
+            performUpdates();
+        }
+        finally {
+            db.exec("ROLLBACK");
+        }
+    }
+    return result;
+}
+export function formatBackfillResult(result, write) {
+    const heading = result.dryRun
+        ? "scope backfill (dry run -- no writes):"
+        : "scope backfill applied:";
+    write(`${heading}\n`);
+    const rows = [
+        ["sessions", result.dryRun ? "would change" : "stamped", result.sessions],
+        ["facts", result.dryRun ? "would cascade" : "cascaded", result.facts],
+        ["exemplars", result.dryRun ? "would cascade" : "cascaded", result.exemplars],
+        ["signals", result.dryRun ? "would cascade" : "cascaded", result.signals],
+        ["workstreams", result.dryRun ? "would cascade" : "cascaded", result.workstreams],
+    ];
+    for (const [table, verb, data] of rows) {
+        const entries = Object.entries(data.byScope);
+        const breakdown = entries.length > 0
+            ? `  [${entries.map(([s, c]) => `${s}: ${c}`).join(", ")}]`
+            : "";
+        write(`  ${table.padEnd(12)}${String(data.total).padStart(4)} ${verb}${breakdown}\n`);
+    }
+    const { missingTranscript, malformed, noCwdFound } = result.skipped;
+    const skipTotal = missingTranscript + malformed + noCwdFound;
+    if (skipTotal > 0) {
+        write(`  skipped:     ${skipTotal}` +
+            ` (missing transcript: ${missingTranscript}, malformed: ${malformed}, no cwd found: ${noCwdFound})\n`);
+    }
+    else {
+        write(`  skipped:        0\n`);
+    }
+}
+//# sourceMappingURL=scope-backfill.js.map

package/dist/cli/scope-backfill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-backfill.js","sourceRoot":"","sources":["../../src/cli/scope-backfill.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAG5D,8EAA8E;AAC9E,MAAM,UAAU,GAAG,KAAK,CAAC;AAEzB;;;;;;;;;;;;;GAaG;AACH,KAAK,UAAU,qBAAqB,CAClC,cAAsB;IAEtB,IAAI,EAAgD,CAAC;IACrD,IAAI,CAAC;QACH,EAAE,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACrC,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACrC,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;QAC3D,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC;QAChD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACpC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YAC5B,IAAI,CAAC,OAAO;gBAAE,SAAS;YACvB,IAAI,GAA4B,CAAC;YACjC,IAAI,CAAC;gBACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAA4B,CAAC;YACvD,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS;YACX,CAAC;YACD,IAAI,OAAO,GAAG,CAAC,KAAK,CAAC,KAAK,QAAQ,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjD,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,CAAC;QACH,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;IACvB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,MAAM,UAAU,GACd,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,OAAO;YACxD,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,WAAW,CAAC;QAClB,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IACnC,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACpC,CAAC;AACH,CAAC;AAID,SAAS,GAAG,CAAC,OAAmB,EAAE,KAAa;IAC7C,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;AAC7C,CAAC;AAiBD,SAAS,UAAU;IACjB,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AACnC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAItC;IACC,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IAGrC,MAAM,WAAW,GAAG,EAAE;SACnB,OAAO,CACN,8FAA8F,CAC/F;SACA,GAAG,EAAE,CAAC;IAET,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAChD,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,cAAc,GAAG,CAAC,CAAC;IACvB,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,MAAM,qBAAqB,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;QAC7E,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,YAAY,EAAE,CAAC;YACf,SAAS;QACX,CAAC;QACD,IAAI,UAAU,KAAK,WAAW,EAAE,CAAC;YAC/B,cAAc,EAAE,CAAC;YACjB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,UAAU,EAAE,CAAC;YACb,SAAS;QACX,CAAC;QACD,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACzC,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QAC7B,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACnC,CAAC;IAED,MAAM,MAAM,GAAmB;QAC7B,MAAM,EAAE,CAAC,KAAK;QACd,QAAQ,EAAE,UAAU,EAAE;QACtB,KAAK,EAAE,UAAU,EAAE;QACnB,SAAS,EAAE,UAAU,EAAE;QACvB,OAAO,EAAE,UAAU,EAAE;QACrB,WAAW,EAAE,UAAU,EAAE;QACzB,OAAO,EAAE,EAAE,iBAAiB,EAAE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE;KAChG,CAAC;IAEF,KAAK,MAAM,KAAK,IAAI,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC;QAC3C,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACxB,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,cAAc,GAAG,GAAG,EAAE;QAC1B,MAAM,aAAa,GAAG,EAAE,CAAC,OAAO,CAC9B,8DAA8D,CAC/D,CAAC;QACF,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,aAAa,EAAE,CAAC;YACxC,aAAa,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC/B,CAAC;QAID,MAAM,QAAQ,GAAG,EAAE;aAChB,OAAO,CAAe;;;;;;OAMtB,CAAC;aACD,GAAG,EAAE,CAAC;QACT,KAAK,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,QAAQ,EAAE,CAAC;YACpC,MAAM,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;YACxB,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACnC,CAAC;QACD,EAAE,CAAC,OAAO,CAAC;;;;;KAKV,CAAC,CAAC,GAAG,EAAE,CAAC;QAET,MAAM,YAAY,GAAG,EAAE;aACpB,OAAO,CAAe;;;;;;OAMtB,CAAC;aACD,GAAG,EAAE,CAAC;QACT,KAAK,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,YAAY,EAAE,CAAC;YACxC,MAAM,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC,CAAC;YAC5B,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACvC,CAAC;QACD,EAAE,CAAC,OAAO,CAAC;;;;;KAKV,CAAC,CAAC,GAAG,EAAE,CAAC;QAET,MAAM,UAAU,GAAG,EAAE;aAClB,OAAO,CAAe;;;;;;OAMtB,CAAC;aACD,GAAG,EAAE,CAAC;QACT,KAAK,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,UAAU,EAAE,CAAC;YACtC,MAAM,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;YAC1B,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACrC,CAAC;QACD,EAAE,CAAC,OAAO,CAAC;;;;;;;;KAQV,CAAC,CAAC,GAAG,EAAE,CAAC;QAGT,MAAM,kBAAkB,GAAG,EAAE;aAC1B,OAAO,CAAY,gDAAgD,CAAC;aACpE,GAAG,EAAE,CAAC;QAGT,MAAM,eAAe,GAAG,EAAE,CAAC,OAAO,CAChC,oDAAoD,CACrD,CAAC;QACF,MAAM,QAAQ,GAAG,EAAE,CAAC,OAAO,CACzB,iEAAiE,CAClE,CAAC;QAEF,KAAK,MAAM,EAAE,IAAI,kBAAkB,EAAE,CAAC;YACpC,MAAM,OAAO,GAAG,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YAC3C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YACnC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC;gBAAE,SAAS;YACpD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAe,CAAC,CAAC,CAAC;YAC9D,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC;gBAAE,SAAS;YAChC,MAAM,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAE,CAAC;YAChC,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;YAC3B,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACzC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC,CAAC;IAEF,IAAI,KAAK,EAAE,CAAC;QACV,EAAE,CAAC,WAAW,CAAC,cAAc,CAAC,EAAE,CAAC;IACnC,CAAC;SAAM,CAAC;QACN,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACjB,IAAI,CAAC;YACH,cAAc,EAAE,CAAC;QACnB,CAAC;gBAAS,CAAC;YACT,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,MAAsB,EACtB,KAA0B;IAE1B,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM;QAC3B,CAAC,CAAC,wCAAwC;QAC1C,CAAC,CAAC,yBAAyB,CAAC;IAC9B,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;IAEtB,MAAM,IAAI,GAAiD;QACzD,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC;QACzE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC;QACrE,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC;QAC7E,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,OAAO,CAAC;QACzE,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,WAAW,CAAC;KAClF,CAAC;IAEF,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7C,MAAM,SAAS,GACb,OAAO,CAAC,MAAM,GAAG,CAAC;YAChB,CAAC,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAC3D,CAAC,CAAC,EAAE,CAAC;QACT,KAAK,CAAC,KAAK,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,SAAS,IAAI,CAAC,CAAC;IACxF,CAAC;IAED,MAAM,EAAE,iBAAiB,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC;IACpE,MAAM,SAAS,GAAG,iBAAiB,GAAG,SAAS,GAAG,UAAU,CAAC;IAC7D,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;QAClB,KAAK,CACH,kBAAkB,SAAS,EAAE;YAC3B,yBAAyB,iBAAiB,gBAAgB,SAAS,mBAAmB,UAAU,KAAK,CACxG,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,uBAAuB,CAAC,CAAC;IACjC,CAAC;AACH,CAAC"}

package/dist/cli/scope-coverage.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `nlm scope coverage`: per-table and recall-weighted scope coverage fractions.
+ *
+ * READ-ONLY: opens the DB with { readonly: true }; never writes.
+ * No env flags consulted. No recall behavior change.
+ */
+export interface TableCoverage {
+    total: number;
+    stamped: number;
+    unstamped: number;
+    stamped_fraction: number;
+    byScope: Record<string, number>;
+}
+export interface OverallCoverage {
+    total: number;
+    stamped: number;
+    unstamped: number;
+    stamped_fraction: number;
+}
+export interface RecallWeightedStats {
+    distinctReturnedIds: number;
+    foundInDb: number;
+    scoped: number;
+    fraction: number;
+}
+export interface RecallWeightedCoverage extends RecallWeightedStats {
+    bySurface: Record<string, RecallWeightedStats>;
+}
+export interface CoverageResult {
+    sessions: TableCoverage;
+    facts: TableCoverage;
+    code_exemplars: TableCoverage;
+    signals: TableCoverage;
+    workstreams: TableCoverage;
+    overall: OverallCoverage;
+    recallWeighted: RecallWeightedCoverage | null;
+    queryLogNote: string | null;
+}
+export declare function runScopeCoverage(opts: {
+    dbPath: string;
+    queryLogPath?: string;
+    window?: number;
+}): Promise<CoverageResult>;
+export declare function formatCoverageResult(result: CoverageResult, write: (s: string) => void): void;

package/dist/cli/scope-coverage.js

@@ -0,0 +1,205 @@
+/**
+ * `nlm scope coverage`: per-table and recall-weighted scope coverage fractions.
+ *
+ * READ-ONLY: opens the DB with { readonly: true }; never writes.
+ * No env flags consulted. No recall behavior change.
+ */
+import Database from "better-sqlite3";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { recentQueryLog } from "../core/recall/recent-log.js";
+function overallOf(tables) {
+    let total = 0;
+    let stamped = 0;
+    for (const t of tables) {
+        total += t.total;
+        stamped += t.stamped;
+    }
+    return {
+        total,
+        stamped,
+        unstamped: total - stamped,
+        stamped_fraction: total === 0 ? 0 : stamped / total,
+    };
+}
+function tableStats(db, table) {
+    const agg = db
+        .prepare(`SELECT COUNT(*) AS total, SUM(CASE WHEN scope IS NOT NULL THEN 1 ELSE 0 END) AS scoped FROM "${table}"`)
+        .get();
+    const total = agg.total;
+    const scoped = agg.scoped ?? 0;
+    const rows = db
+        .prepare(`SELECT scope, COUNT(*) AS n FROM "${table}" WHERE scope IS NOT NULL GROUP BY scope`)
+        .all();
+    const byScope = {};
+    for (const { scope, n } of rows) {
+        byScope[scope] = n;
+    }
+    return {
+        total,
+        stamped: scoped,
+        unstamped: total - scoped,
+        stamped_fraction: total === 0 ? 0 : scoped / total,
+        byScope,
+    };
+}
+function defaultQueryLogPath() {
+    return process.env["NLM_QUERY_LOG"] ?? join(homedir(), ".nlm", "query_log.jsonl");
+}
+const CHUNK_SIZE = 999;
+export async function runScopeCoverage(opts) {
+    const entryWindow = opts.window ?? 200;
+    if (!Number.isFinite(entryWindow) || entryWindow <= 0) {
+        throw new Error(`invalid --window: ${String(opts.window)} (expected a positive integer)`);
+    }
+    const db = new Database(opts.dbPath, { readonly: true });
+    try {
+        const sessions = tableStats(db, "sessions");
+        const facts = tableStats(db, "facts");
+        const code_exemplars = tableStats(db, "code_exemplars");
+        const signals = tableStats(db, "signals");
+        const workstreams = tableStats(db, "workstreams");
+        const overall = overallOf([sessions, facts, code_exemplars, signals, workstreams]);
+        const logPath = opts.queryLogPath ?? defaultQueryLogPath();
+        if (!existsSync(logPath)) {
+            return {
+                sessions,
+                facts,
+                code_exemplars,
+                signals,
+                workstreams,
+                overall,
+                recallWeighted: null,
+                queryLogNote: `query log not found at ${logPath}`,
+            };
+        }
+        const entries = recentQueryLog(entryWindow, logPath);
+        const idSet = new Set();
+        const idsBySurface = new Map();
+        for (const entry of entries) {
+            let surfaceIds = idsBySurface.get(entry.source);
+            if (!surfaceIds) {
+                surfaceIds = new Set();
+                idsBySurface.set(entry.source, surfaceIds);
+            }
+            for (const id of entry.returnedIds) {
+                idSet.add(id);
+                surfaceIds.add(id);
+            }
+        }
+        if (idSet.size === 0) {
+            return {
+                sessions,
+                facts,
+                code_exemplars,
+                signals,
+                workstreams,
+                overall,
+                recallWeighted: { distinctReturnedIds: 0, foundInDb: 0, scoped: 0, fraction: 0, bySurface: {} },
+                queryLogNote: null,
+            };
+        }
+        // Recalled ids span the corpus tables (session recall returns session
+        // ids, fact recall fact ids, code recall exemplar ids); resolve each id
+        // to its scope across all three, first match wins.
+        const scopeById = new Map();
+        const ids = [...idSet];
+        for (const table of ["sessions", "facts", "code_exemplars"]) {
+            for (let i = 0; i < ids.length; i += CHUNK_SIZE) {
+                const chunk = ids.slice(i, i + CHUNK_SIZE).filter((id) => !scopeById.has(id));
+                if (chunk.length === 0)
+                    continue;
+                const placeholders = chunk.map(() => "?").join(", ");
+                const rows = db
+                    .prepare(`SELECT id, scope FROM "${table}" WHERE id IN (${placeholders})`)
+                    .all(...chunk);
+                for (const row of rows) {
+                    if (!scopeById.has(row.id))
+                        scopeById.set(row.id, row.scope);
+                }
+            }
+        }
+        const statsFor = (set) => {
+            let foundInDb = 0;
+            let scoped = 0;
+            for (const id of set) {
+                const scope = scopeById.get(id);
+                if (scope === undefined)
+                    continue;
+                foundInDb++;
+                if (scope !== null)
+                    scoped++;
+            }
+            return {
+                distinctReturnedIds: set.size,
+                foundInDb,
+                scoped,
+                fraction: foundInDb === 0 ? 0 : scoped / foundInDb,
+            };
+        };
+        const bySurface = {};
+        for (const [source, surfaceIds] of idsBySurface) {
+            if (surfaceIds.size > 0)
+                bySurface[source] = statsFor(surfaceIds);
+        }
+        return {
+            sessions,
+            facts,
+            code_exemplars,
+            signals,
+            workstreams,
+            overall,
+            recallWeighted: { ...statsFor(idSet), bySurface },
+            queryLogNote: null,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+export function formatCoverageResult(result, write) {
+    write("scope coverage:\n\n");
+    write("  per-table:\n");
+    const tables = [
+        ["sessions", result.sessions],
+        ["facts", result.facts],
+        ["code_exemplars", result.code_exemplars],
+        ["signals", result.signals],
+        ["workstreams", result.workstreams],
+    ];
+    for (const [name, cov] of tables) {
+        const pct = `${(cov.stamped_fraction * 100).toFixed(1)}%`;
+        const counts = `${cov.stamped}/${cov.total} stamped (${pct})`;
+        const entries = Object.entries(cov.byScope);
+        const breakdown = entries.length > 0
+            ? `  [${entries.map(([s, c]) => `${s}: ${c}`).join(", ")}]`
+            : "";
+        write(`    ${name.padEnd(15)} ${counts}${breakdown}\n`);
+    }
+    const o = result.overall;
+    const overallPct = `${(o.stamped_fraction * 100).toFixed(1)}%`;
+    write(`    ${"overall".padEnd(15)} ${o.stamped}/${o.total} stamped (${overallPct})\n`);
+    write("\n");
+    if (result.queryLogNote !== null) {
+        write(`  recall-weighted: skipped -- ${result.queryLogNote}\n`);
+    }
+    else if (result.recallWeighted !== null) {
+        const rw = result.recallWeighted;
+        const pct = `${(rw.fraction * 100).toFixed(1)}%`;
+        write(`  recall-weighted (recalled ids from last window):\n`);
+        write(`    distinct ids: ${rw.distinctReturnedIds}\n`);
+        write(`    found in db:  ${rw.foundInDb}\n`);
+        write(`    scoped:       ${rw.scoped}\n`);
+        write(`    fraction:     ${pct}\n`);
+        const surfaces = Object.entries(rw.bySurface);
+        if (surfaces.length > 0) {
+            write(`  per-surface:\n`);
+            for (const [source, s] of surfaces) {
+                const sPct = `${(s.fraction * 100).toFixed(1)}%`;
+                write(`    ${source.padEnd(15)} ${s.scoped}/${s.foundInDb} scoped (${sPct}, ${s.distinctReturnedIds} ids)\n`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=scope-coverage.js.map

package/dist/cli/scope-coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-coverage.js","sourceRoot":"","sources":["../../src/cli/scope-coverage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAwC9D,SAAS,SAAS,CAAC,MAAoC;IACrD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,KAAK,IAAI,CAAC,CAAC,KAAK,CAAC;QACjB,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC;IACvB,CAAC;IACD,OAAO;QACL,KAAK;QACL,OAAO;QACP,SAAS,EAAE,KAAK,GAAG,OAAO;QAC1B,gBAAgB,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,KAAK;KACpD,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,EAAqB,EAAE,KAAa;IAEtD,MAAM,GAAG,GAAG,EAAE;SACX,OAAO,CACN,gGAAgG,KAAK,GAAG,CACzG;SACA,GAAG,EAAG,CAAC;IACV,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;IACxB,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC;IAG/B,MAAM,IAAI,GAAG,EAAE;SACZ,OAAO,CACN,qCAAqC,KAAK,0CAA0C,CACrF;SACA,GAAG,EAAE,CAAC;IACT,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,KAAK,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC;QAChC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAED,OAAO;QACL,KAAK;QACL,OAAO,EAAE,MAAM;QACf,SAAS,EAAE,KAAK,GAAG,MAAM;QACzB,gBAAgB,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,KAAK;QAClD,OAAO;KACR,CAAC;AACJ,CAAC;AAED,SAAS,mBAAmB;IAC1B,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,iBAAiB,CAAC,CAAC;AACpF,CAAC;AAED,MAAM,UAAU,GAAG,GAAG,CAAC;AAEvB,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAItC;IACC,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC;IACvC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,qBAAqB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,gCAAgC,CAAC,CAAC;IAC5F,CAAC;IACD,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAEzD,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,UAAU,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;QAC5C,MAAM,KAAK,GAAG,UAAU,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QACtC,MAAM,cAAc,GAAG,UAAU,CAAC,EAAE,EAAE,gBAAgB,CAAC,CAAC;QACxD,MAAM,OAAO,GAAG,UAAU,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;QAC1C,MAAM,WAAW,GAAG,UAAU,CAAC,EAAE,EAAE,aAAa,CAAC,CAAC;QAClD,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC;QAEnF,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,IAAI,mBAAmB,EAAE,CAAC;QAE3D,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACzB,OAAO;gBACL,QAAQ;gBACR,KAAK;gBACL,cAAc;gBACd,OAAO;gBACP,WAAW;gBACX,OAAO;gBACP,cAAc,EAAE,IAAI;gBACpB,YAAY,EAAE,0BAA0B,OAAO,EAAE;aAClD,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAG,cAAc,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACrD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;QAChC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAuB,CAAC;QACpD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,UAAU,GAAG,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAChD,IAAI,CAAC,UAAU,EAAE,CAAC;gBAChB,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;gBAC/B,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;YAC7C,CAAC;YACD,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;gBACnC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACd,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;QAED,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACrB,OAAO;gBACL,QAAQ;gBACR,KAAK;gBACL,cAAc;gBACd,OAAO;gBACP,WAAW;gBACX,OAAO;gBACP,cAAc,EAAE,EAAE,mBAAmB,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE;gBAC/F,YAAY,EAAE,IAAI;aACnB,CAAC;QACJ,CAAC;QAED,sEAAsE;QACtE,wEAAwE;QACxE,mDAAmD;QACnD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAC;QACnD,MAAM,GAAG,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;QACvB,KAAK,MAAM,KAAK,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,gBAAgB,CAAC,EAAE,CAAC;YAC5D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,UAAU,EAAE,CAAC;gBAChD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;gBAC9E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;oBAAE,SAAS;gBACjC,MAAM,YAAY,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACrD,MAAM,IAAI,GAAG,EAAE;qBACZ,OAAO,CAAC,0BAA0B,KAAK,kBAAkB,YAAY,GAAG,CAAC;qBACzE,GAAG,CAAC,GAAG,KAAK,CAAgD,CAAC;gBAChE,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;oBACvB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;wBAAE,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;gBAC/D,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAG,CAAC,GAAwB,EAAuB,EAAE;YACjE,IAAI,SAAS,GAAG,CAAC,CAAC;YAClB,IAAI,MAAM,GAAG,CAAC,CAAC;YACf,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;gBACrB,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAChC,IAAI,KAAK,KAAK,SAAS;oBAAE,SAAS;gBAClC,SAAS,EAAE,CAAC;gBACZ,IAAI,KAAK,KAAK,IAAI;oBAAE,MAAM,EAAE,CAAC;YAC/B,CAAC;YACD,OAAO;gBACL,mBAAmB,EAAE,GAAG,CAAC,IAAI;gBAC7B,SAAS;gBACT,MAAM;gBACN,QAAQ,EAAE,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,SAAS;aACnD,CAAC;QACJ,CAAC,CAAC;QAEF,MAAM,SAAS,GAAwC,EAAE,CAAC;QAC1D,KAAK,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,IAAI,YAAY,EAAE,CAAC;YAChD,IAAI,UAAU,CAAC,IAAI,GAAG,CAAC;gBAAE,SAAS,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;QACpE,CAAC;QAED,OAAO;YACL,QAAQ;YACR,KAAK;YACL,cAAc;YACd,OAAO;YACP,WAAW;YACX,OAAO;YACP,cAAc,EAAE,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE;YACjD,YAAY,EAAE,IAAI;SACnB,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAAsB,EAAE,KAA0B;IACrF,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAC7B,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAExB,MAAM,MAAM,GAAmC;QAC7C,CAAC,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC;QAC7B,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC;QACvB,CAAC,gBAAgB,EAAE,MAAM,CAAC,cAAc,CAAC;QACzC,CAAC,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC;QAC3B,CAAC,aAAa,EAAE,MAAM,CAAC,WAAW,CAAC;KACpC,CAAC;IAEF,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,MAAM,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,gBAAgB,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;QAC1D,MAAM,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,KAAK,aAAa,GAAG,GAAG,CAAC;QAC9D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC5C,MAAM,SAAS,GACb,OAAO,CAAC,MAAM,GAAG,CAAC;YAChB,CAAC,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAC3D,CAAC,CAAC,EAAE,CAAC;QACT,KAAK,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,MAAM,GAAG,SAAS,IAAI,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC;IACzB,MAAM,UAAU,GAAG,GAAG,CAAC,CAAC,CAAC,gBAAgB,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IAC/D,KAAK,CAAC,OAAO,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,KAAK,aAAa,UAAU,KAAK,CAAC,CAAC;IAEvF,KAAK,CAAC,IAAI,CAAC,CAAC;IAEZ,IAAI,MAAM,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;QACjC,KAAK,CAAC,iCAAiC,MAAM,CAAC,YAAY,IAAI,CAAC,CAAC;IAClE,CAAC;SAAM,IAAI,MAAM,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;QAC1C,MAAM,EAAE,GAAG,MAAM,CAAC,cAAc,CAAC;QACjC,MAAM,GAAG,GAAG,GAAG,CAAC,EAAE,CAAC,QAAQ,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;QACjD,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC9D,KAAK,CAAC,qBAAqB,EAAE,CAAC,mBAAmB,IAAI,CAAC,CAAC;QACvD,KAAK,CAAC,qBAAqB,EAAE,CAAC,SAAS,IAAI,CAAC,CAAC;QAC7C,KAAK,CAAC,qBAAqB,EAAE,CAAC,MAAM,IAAI,CAAC,CAAC;QAC1C,KAAK,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;QACpC,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,KAAK,CAAC,kBAAkB,CAAC,CAAC;YAC1B,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,QAAQ,EAAE,CAAC;gBACnC,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,QAAQ,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;gBACjD,KAAK,CAAC,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,SAAS,YAAY,IAAI,KAAK,CAAC,CAAC,mBAAmB,SAAS,CAAC,CAAC;YAChH,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/core/actions/overlay.d.ts

@@ -5,38 +5,52 @@
  * at read time without mutating the underlying store.
  *
  * Shared by buildDataset (UI projection) and SqliteSessionStore (recall
- * path), so the same overlay drives both surfaces. Append-only — every
+ * path), so the same overlay drives both surfaces. Append-only; every
  * mutation lives as a row in `actions`.
  */
 import type Database from "better-sqlite3";
+import type { Pool } from "pg";
 export interface ActionOverlay {
     readonly dismissedAlerts: Set<string>;
     readonly snoozedAlerts: Map<string, string>;
     readonly retiredEntities: Set<string>;
     readonly snoozedEntities: Map<string, string>;
     readonly labeledEntities: Map<string, string>;
-    /** entity canonical → new display label. Storage canonical is untouched;
+    /** entity canonical -> new display label. Storage canonical is untouched;
      *  legacy-name recall still resolves because sessions stay tagged with
      *  the original canonical. Last non-reverted rename per subject wins. */
     readonly renamedEntities: Map<string, string>;
     /** open-question ids resolved without becoming decisions */
     readonly resolvedOpens: Set<string>;
-    /** open-question id → resolution text (becomes a decision at projection time) */
+    /** open-question id -> resolution text (becomes a decision at projection time) */
     readonly promotedOpens: Map<string, string>;
     /** decision ids hidden from the projection (the underlying session body keeps the original line). */
     readonly dismissedDecisions: Set<string>;
-    /** decision id → corrected text shown in place of the original. */
+    /** decision id -> corrected text shown in place of the original. */
     readonly revisedDecisions: Map<string, string>;
-    /** entity canonical → user-asserted coherence bucket. Overrides the
+    /** entity canonical -> user-asserted coherence bucket. Overrides the
      *  computed (session_count + age) classification at projection time;
      *  last non-reverted write wins. */
     readonly coherenceOverrides: Map<string, "active" | "sparse" | "stale">;
-    /** source canonical → target canonical. Source is hidden at projection
+    /** source canonical -> target canonical. Source is hidden at projection
      *  time (treated as retired); target absorbs the source's session count. */
     readonly mergedEntities: Map<string, string>;
 }
+export interface ActionRow {
+    kind: string;
+    subject_type: string;
+    subject_id: string;
+    payload: string | null;
+}
 export declare const EMPTY_OVERLAY: ActionOverlay;
+/**
+ * Pure reducer: folds a sequence of action rows (ordered by id, reverted rows
+ * excluded by caller) into an ActionOverlay. Used by both the SQLite and PG
+ * loaders so the projection logic is shared and not duplicated per backend.
+ */
+export declare function reduceActionRows(rows: ReadonlyArray<ActionRow>): ActionOverlay;
 export declare function loadActionOverlay(db: Database.Database): ActionOverlay;
+export declare function loadActionOverlayPg(pool: Pool): Promise<ActionOverlay>;
 /**
  * Stable id for an open question: `${sessionId}::${hash12(text)}`. Both
  * sides (overlay creators and consumers) compute it the same way so action

package/dist/core/actions/overlay.js

@@ -5,7 +5,7 @@
  * at read time without mutating the underlying store.
  *
  * Shared by buildDataset (UI projection) and SqliteSessionStore (recall
- * path), so the same overlay drives both surfaces. Append-only — every
+ * path), so the same overlay drives both surfaces. Append-only; every
  * mutation lives as a row in `actions`.
  */
 export const EMPTY_OVERLAY = {
@@ -22,12 +22,12 @@ export const EMPTY_OVERLAY = {
     coherenceOverrides: new Map(),
     mergedEntities: new Map(),
 };
-export function loadActionOverlay(db) {
-    const hasActions = db
-        .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='actions'")
-        .get();
-    if (!hasActions)
-        return EMPTY_OVERLAY;
+/**
+ * Pure reducer: folds a sequence of action rows (ordered by id, reverted rows
+ * excluded by caller) into an ActionOverlay. Used by both the SQLite and PG
+ * loaders so the projection logic is shared and not duplicated per backend.
+ */
+export function reduceActionRows(rows) {
     const overlay = {
         dismissedAlerts: new Set(),
         snoozedAlerts: new Map(),
@@ -42,16 +42,6 @@ export function loadActionOverlay(db) {
         coherenceOverrides: new Map(),
         mergedEntities: new Map(),
     };
-    // ORDER BY id keeps reducer deterministic: later writes overwrite earlier
-    // ones, so the latest non-reverted rename per subject wins.
-    const rows = db
-        .prepare(`
-      SELECT kind, subject_type, subject_id, payload
-      FROM actions
-      WHERE reverted_by IS NULL
-      ORDER BY id
-    `)
-        .all();
     const now = new Date().toISOString();
     for (const r of rows) {
         const payload = r.payload ? safeParse(r.payload) : null;
@@ -114,13 +104,37 @@ export function loadActionOverlay(db) {
                 overlay.coherenceOverrides.set(r.subject_id, state);
             }
             else {
-                // Empty payload reverts to the computed bucket.
                 overlay.coherenceOverrides.delete(r.subject_id);
             }
         }
     }
     return overlay;
 }
+export function loadActionOverlay(db) {
+    const hasActions = db
+        .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='actions'")
+        .get();
+    if (!hasActions)
+        return EMPTY_OVERLAY;
+    // ORDER BY id keeps reducer deterministic: later writes overwrite earlier
+    // ones, so the latest non-reverted rename per subject wins.
+    const rows = db
+        .prepare(`
+      SELECT kind, subject_type, subject_id, payload
+      FROM actions
+      WHERE reverted_by IS NULL
+      ORDER BY id
+    `)
+        .all();
+    return reduceActionRows(rows);
+}
+export async function loadActionOverlayPg(pool) {
+    const result = await pool.query(`SELECT kind, subject_type, subject_id, payload
+     FROM actions
+     WHERE reverted_by IS NULL
+     ORDER BY id`);
+    return reduceActionRows(result.rows);
+}
 /**
  * Stable id for an open question: `${sessionId}::${hash12(text)}`. Both
  * sides (overlay creators and consumers) compute it the same way so action