nlm-memory 0.20.0 → 0.21.0

package/dist/core/metrics/re-derivation.js

@@ -0,0 +1,87 @@
+/**
+ * re_derivation_rate: how often the same decision is re-made across sessions
+ * that share a topic but were never linked. A high rate means recall is failing
+ * to surface the prior decision, so the operator (or an agent) re-derives it.
+ *
+ * A pair counts as a re-derivation when the two sessions share at least one
+ * entity, sit more than GAP_DAYS apart, have decision text overlapping at or
+ * above JACCARD_FLOOR, and have no `continues`/`supersedes` edge linking them.
+ */
+const JACCARD_FLOOR = 0.5;
+const GAP_DAYS = 7;
+const MS_PER_DAY = 86_400_000;
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+function jaccard(a, b) {
+    const toks = (xs) => new Set(xs.join(" ").toLowerCase().split(/\W+/).filter(Boolean));
+    const A = toks(a);
+    const B = toks(b);
+    if (A.size === 0 || B.size === 0)
+        return 0;
+    let inter = 0;
+    for (const t of A)
+        if (B.has(t))
+            inter++;
+    return inter / (A.size + B.size - inter);
+}
+/**
+ * SQLite-backed deps for the CLI readout. Reads sessions started within the
+ * window along with their entity links and decision markers, plus all edges.
+ */
+export function sqliteReDerivationDeps(db) {
+    return {
+        async listSessionsWithin(windowDays) {
+            const rows = db
+                .prepare(`SELECT id, started_at AS startedAt
+             FROM sessions
+            WHERE started_at >= datetime('now', ?)
+            ORDER BY started_at ASC`)
+                .all(`-${windowDays} days`);
+            const entStmt = db.prepare("SELECT entity_canonical AS e FROM session_entities WHERE session_id = ?");
+            const decStmt = db.prepare("SELECT text AS t FROM markers WHERE session_id = ? AND kind = 'decision' ORDER BY position ASC");
+            return rows.map((r) => ({
+                id: r.id,
+                startedAt: r.startedAt,
+                entities: entStmt.all(r.id).map((x) => x.e),
+                decisions: decStmt.all(r.id).map((x) => x.t),
+            }));
+        },
+        async listEdges() {
+            return db
+                .prepare("SELECT from_session, to_session, kind FROM session_edges")
+                .all();
+        },
+    };
+}
+export async function computeReDerivationRate(deps, windowDays) {
+    const sessions = await deps.listSessionsWithin(windowDays);
+    const edges = await deps.listEdges();
+    const linked = new Set(edges
+        .filter((e) => e.kind === "continues" || e.kind === "supersedes")
+        .map((e) => [e.from_session, e.to_session].sort().join("|")));
+    const pairs = [];
+    let eligible = 0;
+    for (let i = 0; i < sessions.length; i++) {
+        for (let j = i + 1; j < sessions.length; j++) {
+            const s = sessions[i];
+            const t = sessions[j];
+            const shared = s.entities.filter((e) => t.entities.includes(e));
+            if (shared.length === 0)
+                continue;
+            eligible++;
+            const key = [s.id, t.id].sort().join("|");
+            if (linked.has(key))
+                continue;
+            const gap = Math.abs(new Date(t.startedAt).getTime() - new Date(s.startedAt).getTime()) / MS_PER_DAY;
+            if (gap <= GAP_DAYS)
+                continue;
+            const jac = jaccard(s.decisions, t.decisions);
+            if (jac >= JACCARD_FLOOR) {
+                pairs.push({ a: s.id, b: t.id, sharedEntities: shared, jaccard: round2(jac) });
+            }
+        }
+    }
+    return { rate: eligible ? pairs.length / eligible : 0, pairs, eligible };
+}
+//# sourceMappingURL=re-derivation.js.map

package/dist/core/metrics/re-derivation.js.map

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

package/dist/core/outcome/coverage.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Corpus-level Tier-B outcome coverage (#352 phase 2, Task 8).
+ *
+ * The digest's coverage block needs verdict counts across every session
+ * ended in a window (hundreds of sessions), not one session at a time.
+ * Calling `deriveOutcome` in a loop with per-session reader ports would mean
+ * one round trip per evidence type *per session*. Instead, the caller
+ * batches each evidence type into one query across the whole id set
+ * (`OutcomeCoverageInput`'s maps), and this module wraps those maps into the
+ * same narrow per-session reader shape `deriveOutcome` already expects — so
+ * the precedence logic itself is never duplicated, only its I/O is batched.
+ */
+import type { OutcomeCitation, OutcomeEdge, OutcomeSession, OutcomeSignal } from "../../ports/outcome.js";
+import type { ReDerivationPair } from "../metrics/re-derivation.js";
+export interface OutcomeCoverageInput {
+    readonly sessions: ReadonlyArray<OutcomeSession>;
+    readonly signalsBySession: ReadonlyMap<string, ReadonlyArray<OutcomeSignal>>;
+    readonly edgesBySession: ReadonlyMap<string, ReadonlyArray<OutcomeEdge>>;
+    readonly citationsBySession: ReadonlyMap<string, ReadonlyArray<OutcomeCitation>>;
+    readonly reDerivationPairs: ReadonlyArray<ReDerivationPair>;
+    /** Injected clock, forwarded to `deriveOutcome`. Defaults to `Date.now()`. */
+    readonly now?: () => Date;
+    readonly heldAfterDays?: number;
+}
+export interface OutcomeCoverage {
+    readonly total: number;
+    readonly held: number;
+    readonly overturned: number;
+    readonly builtUpon: number;
+    readonly reDerivedLater: number;
+    readonly unobserved: number;
+}
+export declare function computeOutcomeCoverage(input: OutcomeCoverageInput): Promise<OutcomeCoverage>;

package/dist/core/outcome/coverage.js

@@ -0,0 +1,46 @@
+/**
+ * Corpus-level Tier-B outcome coverage (#352 phase 2, Task 8).
+ *
+ * The digest's coverage block needs verdict counts across every session
+ * ended in a window (hundreds of sessions), not one session at a time.
+ * Calling `deriveOutcome` in a loop with per-session reader ports would mean
+ * one round trip per evidence type *per session*. Instead, the caller
+ * batches each evidence type into one query across the whole id set
+ * (`OutcomeCoverageInput`'s maps), and this module wraps those maps into the
+ * same narrow per-session reader shape `deriveOutcome` already expects — so
+ * the precedence logic itself is never duplicated, only its I/O is batched.
+ */
+import { deriveOutcome } from "./rollup.js";
+export async function computeOutcomeCoverage(input) {
+    const counts = { held: 0, overturned: 0, builtUpon: 0, reDerivedLater: 0, unobserved: 0 };
+    for (const session of input.sessions) {
+        const verdict = await deriveOutcome(session.id, {
+            sessions: { getById: async () => session },
+            signals: { listForSession: async () => input.signalsBySession.get(session.id) ?? [] },
+            edges: { listForSession: async () => input.edgesBySession.get(session.id) ?? [] },
+            citations: { listForSession: async () => input.citationsBySession.get(session.id) ?? [] },
+            reDerivationPairs: input.reDerivationPairs,
+            ...(input.now ? { now: input.now } : {}),
+            ...(input.heldAfterDays !== undefined ? { heldAfterDays: input.heldAfterDays } : {}),
+        });
+        switch (verdict.verdict) {
+            case "held":
+                counts.held++;
+                break;
+            case "overturned":
+                counts.overturned++;
+                break;
+            case "built-upon":
+                counts.builtUpon++;
+                break;
+            case "re-derived-later":
+                counts.reDerivedLater++;
+                break;
+            case "unobserved":
+                counts.unobserved++;
+                break;
+        }
+    }
+    return { total: input.sessions.length, ...counts };
+}
+//# sourceMappingURL=coverage.js.map

package/dist/core/outcome/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../../../src/core/outcome/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA6B5C,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,KAA2B;IACtE,MAAM,MAAM,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;IAE1F,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACrC,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,EAAE,EAAE;YAC9C,QAAQ,EAAE,EAAE,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,OAAO,EAAE;YAC1C,OAAO,EAAE,EAAE,cAAc,EAAE,KAAK,IAAI,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE;YACrF,KAAK,EAAE,EAAE,cAAc,EAAE,KAAK,IAAI,EAAE,CAAC,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE;YACjF,SAAS,EAAE,EAAE,cAAc,EAAE,KAAK,IAAI,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE;YACzF,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;YAC1C,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxC,GAAG,CAAC,KAAK,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,KAAK,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrF,CAAC,CAAC;QAEH,QAAQ,OAAO,CAAC,OAAO,EAAE,CAAC;YACxB,KAAK,MAAM;gBACT,MAAM,CAAC,IAAI,EAAE,CAAC;gBACd,MAAM;YACR,KAAK,YAAY;gBACf,MAAM,CAAC,UAAU,EAAE,CAAC;gBACpB,MAAM;YACR,KAAK,YAAY;gBACf,MAAM,CAAC,SAAS,EAAE,CAAC;gBACnB,MAAM;YACR,KAAK,kBAAkB;gBACrB,MAAM,CAAC,cAAc,EAAE,CAAC;gBACxB,MAAM;YACR,KAAK,YAAY;gBACf,MAAM,CAAC,UAAU,EAAE,CAAC;gBACpB,MAAM;QACV,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;AACrD,CAAC"}

package/dist/core/outcome/rollup.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Outcome rollup core (#352 phase 3 / Tier-B).
+ *
+ * Answers "did this session's decision hold up?" using only a later,
+ * independent event as evidence — never the agent's or an LLM's opinion of
+ * its own work. No LLM call anywhere in this module.
+ *
+ * Evidence precedence (sign-off amendment order — first match wins):
+ *   1. Tier-A: a `signals` row correlated to the session. Strongest evidence;
+ *      wins over every heuristic below regardless of what they'd conclude.
+ *   2. Supersession: session status superseded/replaced, or a
+ *      supersedes/replaces edge pointing at this session -> "overturned"
+ *      (high). Un-superseded 14+ days after `endedAt` -> "held" (medium).
+ *   3. Continuation: an inbound `continues` edge -> "built-upon" (medium).
+ *   4. Re-derivation: session is a member of a re-derivation pair (see
+ *      `computeReDerivationRate`) -> "re-derived-later" (medium, negative).
+ *   5. Citation: appears in evidence[] but is never the sole basis of a
+ *      non-unobserved verdict (CITATION-DEGRADED rule). Citation-only stays
+ *      "unobserved" with `producerDegraded: true`.
+ *   No evidence at all -> "unobserved" (low).
+ *
+ * Supersession scope (v1, documented per the brief's escape hatch): only
+ * session-level supersedence (`sessions.status` + `session_edges`) is
+ * checked. The action-layer's revise/dismiss-decision overlay
+ * (`@core/actions/overlay.js`) is read via raw better-sqlite3/pg handles,
+ * not a port — wiring it here would mean either poking a DB handle into a
+ * pure core module or inventing a new port purely to shave one edge case.
+ * Session-level supersedence already covers the dominant case (an operator
+ * or re-ingest retiring the whole session); revisiting per-decision overlay
+ * correlation is left to a follow-up task if it proves to matter in practice.
+ */
+import type { OutcomeDeps, OutcomeVerdict } from "../../ports/outcome.js";
+export declare function deriveOutcome(sessionId: string, deps: OutcomeDeps): Promise<OutcomeVerdict>;

package/dist/core/outcome/rollup.js

@@ -0,0 +1,113 @@
+/**
+ * Outcome rollup core (#352 phase 3 / Tier-B).
+ *
+ * Answers "did this session's decision hold up?" using only a later,
+ * independent event as evidence — never the agent's or an LLM's opinion of
+ * its own work. No LLM call anywhere in this module.
+ *
+ * Evidence precedence (sign-off amendment order — first match wins):
+ *   1. Tier-A: a `signals` row correlated to the session. Strongest evidence;
+ *      wins over every heuristic below regardless of what they'd conclude.
+ *   2. Supersession: session status superseded/replaced, or a
+ *      supersedes/replaces edge pointing at this session -> "overturned"
+ *      (high). Un-superseded 14+ days after `endedAt` -> "held" (medium).
+ *   3. Continuation: an inbound `continues` edge -> "built-upon" (medium).
+ *   4. Re-derivation: session is a member of a re-derivation pair (see
+ *      `computeReDerivationRate`) -> "re-derived-later" (medium, negative).
+ *   5. Citation: appears in evidence[] but is never the sole basis of a
+ *      non-unobserved verdict (CITATION-DEGRADED rule). Citation-only stays
+ *      "unobserved" with `producerDegraded: true`.
+ *   No evidence at all -> "unobserved" (low).
+ *
+ * Supersession scope (v1, documented per the brief's escape hatch): only
+ * session-level supersedence (`sessions.status` + `session_edges`) is
+ * checked. The action-layer's revise/dismiss-decision overlay
+ * (`@core/actions/overlay.js`) is read via raw better-sqlite3/pg handles,
+ * not a port — wiring it here would mean either poking a DB handle into a
+ * pure core module or inventing a new port purely to shave one edge case.
+ * Session-level supersedence already covers the dominant case (an operator
+ * or re-ingest retiring the whole session); revisiting per-decision overlay
+ * correlation is left to a follow-up task if it proves to matter in practice.
+ */
+const DEFAULT_HELD_AFTER_DAYS = 14;
+const MS_PER_DAY = 86_400_000;
+export async function deriveOutcome(sessionId, deps) {
+    const session = await deps.sessions.getById(sessionId);
+    if (!session) {
+        return { verdict: "unobserved", tier: "B", confidence: "low", evidence: [] };
+    }
+    // 1. Tier A: correlated signal rows are the strongest evidence and settle
+    // the verdict outright, ahead of every heuristic below.
+    const signals = await deps.signals.listForSession(sessionId);
+    if (signals.length > 0) {
+        const anyNegative = signals.some((s) => s.outcome !== "pass");
+        return {
+            verdict: anyNegative ? "overturned" : "held",
+            tier: "A",
+            confidence: "high",
+            evidence: signals.map((s) => `signal:${s.id}`),
+        };
+    }
+    const edges = await deps.edges.listForSession(sessionId);
+    // 2. Supersession beats "held" beats continuation beats re-derivation.
+    const supersedingEdge = edges.find((e) => e.toSession === sessionId && (e.kind === "supersedes" || e.kind === "replaces"));
+    if (session.status === "superseded" || session.status === "replaced" || supersedingEdge) {
+        return {
+            verdict: "overturned",
+            tier: "B",
+            confidence: "high",
+            evidence: [
+                supersedingEdge
+                    ? `edge:${supersedingEdge.kind}:${supersedingEdge.fromSession}`
+                    : `session-status:${session.status}`,
+            ],
+        };
+    }
+    const heldAfterDays = deps.heldAfterDays ?? DEFAULT_HELD_AFTER_DAYS;
+    if (session.endedAt !== null) {
+        const now = (deps.now ?? (() => new Date()))();
+        const elapsedDays = (now.getTime() - new Date(session.endedAt).getTime()) / MS_PER_DAY;
+        if (elapsedDays >= heldAfterDays) {
+            return {
+                verdict: "held",
+                tier: "B",
+                confidence: "medium",
+                evidence: [`held-after:${Math.floor(elapsedDays)}d`],
+            };
+        }
+    }
+    // 3. Continuation.
+    const continuingEdge = edges.find((e) => e.toSession === sessionId && e.kind === "continues");
+    if (continuingEdge) {
+        return {
+            verdict: "built-upon",
+            tier: "B",
+            confidence: "medium",
+            evidence: [`edge:continues:${continuingEdge.fromSession}`],
+        };
+    }
+    // 4. Re-derivation.
+    const reDerivationPair = deps.reDerivationPairs.find((p) => p.a === sessionId || p.b === sessionId);
+    if (reDerivationPair) {
+        const other = reDerivationPair.a === sessionId ? reDerivationPair.b : reDerivationPair.a;
+        return {
+            verdict: "re-derived-later",
+            tier: "B",
+            confidence: "medium",
+            evidence: [`re-derivation-pair:${other}`],
+        };
+    }
+    // 5. Citation — evidence only, never a sole basis for a non-unobserved verdict.
+    const citations = await deps.citations.listForSession(sessionId);
+    if (citations.length > 0) {
+        return {
+            verdict: "unobserved",
+            tier: "B",
+            confidence: "low",
+            evidence: citations.map((c) => `citation:${c.conversationId}`),
+            producerDegraded: true,
+        };
+    }
+    return { verdict: "unobserved", tier: "B", confidence: "low", evidence: [] };
+}
+//# sourceMappingURL=rollup.js.map

package/dist/core/outcome/rollup.js.map

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

package/dist/core/recall/citation-log.d.ts

@@ -24,6 +24,14 @@ export interface CitationStats {
     }>;
     readonly log_present: boolean;
 }
+/**
+ * A citation is only usable telemetry if it can be joined to the query fire
+ * that surfaced it — i.e. it carries a real conversation id. Test fixtures
+ * (conv_test_001), the cite_session placeholder (mcp_tool), and "unknown" can't
+ * join, so they poison every precision / reranker metric computed from the log.
+ * The write path drops them at the source; only attributable citations land.
+ */
+export declare function isAttributableConversationId(id: string): boolean;
 export declare function readCitationLog(days: number, logPath?: string): Promise<CitationEntry[]>;
 export declare function appendCitation(entry: CitationEntry, logPath?: string): Promise<void>;
 export declare function citationStats(days: number, logPath?: string): Promise<CitationStats>;

package/dist/core/recall/citation-log.js

@@ -13,6 +13,19 @@ import { homedir } from "node:os";
 function defaultLogPath() {
     return process.env["NLM_CITATION_LOG"] ?? join(homedir(), ".nlm", "citation-log.jsonl");
 }
+/**
+ * A citation is only usable telemetry if it can be joined to the query fire
+ * that surfaced it — i.e. it carries a real conversation id. Test fixtures
+ * (conv_test_001), the cite_session placeholder (mcp_tool), and "unknown" can't
+ * join, so they poison every precision / reranker metric computed from the log.
+ * The write path drops them at the source; only attributable citations land.
+ */
+export function isAttributableConversationId(id) {
+    if (!id)
+        return false;
+    const lower = id.toLowerCase();
+    return lower !== "unknown" && lower !== "mcp_tool" && !/^(conv_)?test/.test(lower);
+}
 export async function readCitationLog(days, logPath = defaultLogPath()) {
     let raw;
     try {
@@ -51,6 +64,10 @@ export async function readCitationLog(days, logPath = defaultLogPath()) {
     return results;
 }
 export async function appendCitation(entry, logPath = defaultLogPath()) {
+    // Drop unattributable / fixture citations at the source so the log stays a
+    // clean training + metric substrate (see isAttributableConversationId).
+    if (!isAttributableConversationId(entry.conversationId))
+        return;
     try {
         await mkdir(dirname(logPath), { recursive: true });
         const payload = {

package/dist/core/recall/citation-log.js.map

@@ -1 +1 @@
-{"version":3,"file":"citation-log.js","sourceRoot":"","sources":["../../../src/core/recall/citation-log.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"citation-log.js","sourceRoot":"","sources":["../../../src/core/recall/citation-log.ts"],"names":[],"mappings":"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"}

package/dist/core/recall/hook-recall-log.d.ts

@@ -5,8 +5,8 @@
  * injected ids — making it the correct join substrate for recall precision.
  *
  * Only `recall` entries (those with a wouldInject array) are surfaced events.
- * The file also holds stop / session-end / pre-compact / subagent-start
- * entries, which this reader ignores.
+ * The file also holds stop / session-end / pre-compact entries, which this
+ * reader ignores.
  *
  * Read-only telemetry path — never raises.
  */

package/dist/core/recall/hook-recall-log.js

@@ -5,8 +5,8 @@
  * injected ids — making it the correct join substrate for recall precision.
  *
  * Only `recall` entries (those with a wouldInject array) are surfaced events.
- * The file also holds stop / session-end / pre-compact / subagent-start
- * entries, which this reader ignores.
+ * The file also holds stop / session-end / pre-compact entries, which this
+ * reader ignores.
  *
  * Read-only telemetry path — never raises.
  */

package/dist/core/recall/query-intent.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Pure heuristic intent classifier for recall queries.
+ * Total: never throws, always returns one of the four labels.
+ * Dependency-free: uses only detectQueryShape from this directory.
+ */
+export type QueryIntent = "lookup" | "relational" | "temporal" | "other";
+export declare function classifyQueryIntent(query: string): QueryIntent;

package/dist/core/recall/query-intent.js

@@ -0,0 +1,25 @@
+/**
+ * Pure heuristic intent classifier for recall queries.
+ * Total: never throws, always returns one of the four labels.
+ * Dependency-free: uses only detectQueryShape from this directory.
+ */
+import { detectQueryShape } from "./query-shape.js";
+const RELATIONAL_PATTERNS = [
+    /\bdepends\s+on\b/i,
+    /\brelated\s+to\b/i,
+    /\bconnected\s+(to|with)\b/i,
+    /\bwhat\s+uses\b/i,
+    /\bdownstream\s+of\b/i,
+];
+export function classifyQueryIntent(query) {
+    if (!query.trim())
+        return "other";
+    for (const pat of RELATIONAL_PATTERNS) {
+        if (pat.test(query))
+            return "relational";
+    }
+    if (detectQueryShape(query).hasTemporal)
+        return "temporal";
+    return "lookup";
+}
+//# sourceMappingURL=query-intent.js.map

package/dist/core/recall/query-intent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-intent.js","sourceRoot":"","sources":["../../../src/core/recall/query-intent.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAIpD,MAAM,mBAAmB,GAA0B;IACjD,mBAAmB;IACnB,mBAAmB;IACnB,4BAA4B;IAC5B,kBAAkB;IAClB,sBAAsB;CACvB,CAAC;AAEF,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE;QAAE,OAAO,OAAO,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,mBAAmB,EAAE,CAAC;QACtC,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,YAAY,CAAC;IAC3C,CAAC;IACD,IAAI,gBAAgB,CAAC,KAAK,CAAC,CAAC,WAAW;QAAE,OAAO,UAAU,CAAC;IAC3D,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/core/recall/query-log.d.ts

@@ -9,6 +9,7 @@
  * ~/.nlm/query_log.jsonl. Append-only.
  */
 import type { RecallKindFilter, RecallMode } from "../../shared/types.js";
+import { type QueryIntent } from "./query-intent.js";
 export interface LogEntry {
     readonly source: string;
     /** Calling agent runtime (claude-code / hermes / pi.dev / codex / etc).
@@ -22,6 +23,9 @@ export interface LogEntry {
     readonly nResults: number;
     readonly returnedIds: ReadonlyArray<string>;
     readonly conversationId?: string;
+    /** Heuristic intent label for Phase 4 relational-recall telemetry.
+     *  Absent on log entries written before this field was added. */
+    readonly intent?: QueryIntent;
 }
 export interface StatsResult {
     readonly days: number;

package/dist/core/recall/query-log.js

@@ -11,6 +11,7 @@
 import { appendFile, mkdir, readFile, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
+import { classifyQueryIntent } from "./query-intent.js";
 function defaultLogPath() {
     return process.env["NLM_QUERY_LOG"] ?? join(homedir(), ".nlm", "query_log.jsonl");
 }
@@ -29,6 +30,7 @@ export async function logQuery(entry, logPath = defaultLogPath()) {
             limit: entry.limit,
             n_results: entry.nResults,
             returned_ids: entry.returnedIds,
+            intent: classifyQueryIntent(entry.query ?? ""),
         };
         await appendFile(logPath, JSON.stringify(payload) + "\n", "utf8");
     }
@@ -56,6 +58,7 @@ export async function readQueryLog(days, logPath = defaultLogPath()) {
             if (Date.parse(obj["ts"]) < cutoff)
                 continue;
             const convId = typeof obj["conversation_id"] === "string" ? obj["conversation_id"] : "unknown";
+            const intentRaw = obj["intent"];
             const entry = {
                 source: typeof obj["source"] === "string" ? obj["source"] : "",
                 runtime: typeof obj["runtime"] === "string" ? obj["runtime"] : null,
@@ -66,6 +69,7 @@ export async function readQueryLog(days, logPath = defaultLogPath()) {
                 limit: Number(obj["limit"] ?? 5),
                 nResults: Number(obj["n_results"] ?? 0),
                 returnedIds: obj["returned_ids"].filter((x) => typeof x === "string"),
+                ...(typeof intentRaw === "string" ? { intent: intentRaw } : {}),
             };
             results.push({ conversationId: convId, entry });
         }

package/dist/core/recall/query-log.js.map

@@ -1 +1 @@
-{"version":3,"file":"query-log.js","sourceRoot":"","sources":["../../../src/core/recall/query-log.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"query-log.js","sourceRoot":"","sources":["../../../src/core/recall/query-log.ts"],"names":[],"mappings":"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"}

package/dist/core/recall/recall-service.d.ts

@@ -10,7 +10,7 @@ import type { CodeExemplarStore } from "../../ports/code-exemplar-store.js";
 import type { FactStore } from "../../ports/fact-store.js";
 import type { LLMClient } from "../../ports/llm-client.js";
 import type { SessionStore } from "../../ports/session-store.js";
-import type { RecallQuery, RecallResult } from "../../shared/types.js";
+import type { MatchField, RecallHit, RecallQuery, RecallResult, Session } from "../../shared/types.js";
 export interface RecallServiceDeps {
     readonly store: SessionStore;
     readonly llm: LLMClient;
@@ -26,6 +26,14 @@ export interface RecallServiceDeps {
     readonly exemplarStore?: CodeExemplarStore;
     readonly codeEmbedder?: CodeEmbedder;
     readonly installScope?: string;
+    /**
+     * Optional resolver for workstream-filter queries. Given an idOrLabel,
+     * returns the array of member workstream ids (merge chains resolve to the
+     * live survivor). Passed as `workstreamIds` into both search legs so the
+     * SQL layer filters by workstream_id. When absent, `query.workstream` is a
+     * no-op. Injected by buildStack(); tests can stub with a plain fn.
+     */
+    readonly resolveWorkstreamMembers?: (idOrLabel: string) => Promise<ReadonlyArray<string>>;
 }
 export declare class RecallService {
     private readonly deps;
@@ -33,3 +41,31 @@ export declare class RecallService {
     constructor(deps: RecallServiceDeps);
     search(input: RecallQuery): Promise<RecallResult>;
 }
+interface KeywordHit {
+    readonly session: Session;
+    readonly score: number;
+    readonly matchedIn: ReadonlyArray<MatchField>;
+}
+interface SemanticHit {
+    readonly session: Session;
+    readonly similarity: number;
+}
+/**
+ * Keyword-primary hybrid merge (the inverse of the fact lane's semantic-primary
+ * banding).
+ *
+ * For sessions the dominant quality signal is FTS5 BM25: only lexically-matching
+ * sessions come back, and the keyword winner is almost always the intended hit.
+ * RRF fused by rank let strong semantic-only neighbours demote keyword winners
+ * at scale (hybrid 65% vs keyword 90% R@5 on the production decision-query set),
+ * so this bands instead of fuses: keyword hits occupy the upper band [0.5, 1.0]
+ * ranked by normalized BM25; semantic-only hits — sessions keyword never
+ * surfaced — backfill the lower band [0, 0.5).
+ *
+ * keywordScore and semanticScore stay populated as min-max normalized
+ * informational values so the UI can show "how strong was each leg." When
+ * semantic is unavailable (Ollama down) semHits is empty and this degrades to
+ * pure keyword, preserving the graceful-degradation contract.
+ */
+declare function mergeHybrid(kwHits: ReadonlyArray<KeywordHit>, semHits: ReadonlyArray<SemanticHit>): ReadonlyArray<RecallHit>;
+export { mergeHybrid as mergeHybridForTest };