nlm-memory 0.4.0

package/dist/mcp/server.js

@@ -0,0 +1,430 @@
+/**
+ * MCP adapter. Binds the `recall_sessions` and `get_session` tools directly
+ * to RecallService and SessionStore — no HTTP hop, no localhost loopback.
+ *
+ * The Python daemon's MCP server proxied through HTTP. This server runs in
+ * the same process as the rest of nlm-memory, so a tool call is a function
+ * call. Lower latency, simpler stack traces, one fewer thing to keep alive.
+ *
+ * Layering: this module knows about the inner ring (RecallService,
+ * SessionStore); core/ does not know this module exists.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { encode as toonEncode } from "@toon-format/toon";
+import { z } from "zod";
+import { logQuery } from "../core/recall/query-log.js";
+import { logFactQuery } from "../core/recall-facts/fact-query-log.js";
+import { appendCitation } from "../core/recall/citation-log.js";
+const CHARACTER_LIMIT = 25_000;
+const DEFAULT_LIMIT = 10;
+const SERVER_NAME = "nlm-memory-mcp-server";
+const SERVER_VERSION = "0.4.0";
+/** TOON encoding cuts token usage on large recall payloads. Opt in via
+ *  NLM_FORMAT=toon in the MCP server's env (see .mcp.json). Defaults to JSON. */
+const USE_TOON = process.env.NLM_FORMAT === "toon";
+function format(data) {
+    if (USE_TOON) {
+        try {
+            return toonEncode(data);
+        }
+        catch {
+            return JSON.stringify(data, null, 2);
+        }
+    }
+    return JSON.stringify(data, null, 2);
+}
+function truncate(data) {
+    const str = format(data);
+    if (str.length <= CHARACTER_LIMIT)
+        return str;
+    return format({
+        truncated: true,
+        truncation_message: "Response too large. Lower limit or fetch fewer fields via get_session.",
+    });
+}
+function ok(data) {
+    return { content: [{ type: "text", text: truncate(data) }] };
+}
+function err(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        isError: true,
+        content: [{ type: "text", text: `Error: ${message}` }],
+    };
+}
+export async function recallSessionsHandler(deps, input) {
+    try {
+        const query = {
+            query: input.query ?? "",
+            mode: input.mode ?? "hybrid",
+            limit: input.limit ?? DEFAULT_LIMIT,
+            ...(input.entity !== undefined ? { entity: input.entity } : {}),
+            ...(input.kind !== undefined ? { kind: input.kind } : {}),
+        };
+        const result = await deps.recall.search(query);
+        // Telemetry — the MCP path is the real agent-usage path; without this it
+        // is invisible to query_log.jsonl and the Recall page. Fire-and-forget,
+        // mirrors the HTTP /api/recall handler.
+        void logQuery({
+            source: "mcp",
+            query: input.query ?? null,
+            entity: input.entity ?? null,
+            kind: input.kind ?? null,
+            mode: input.mode ?? "hybrid",
+            limit: input.limit ?? DEFAULT_LIMIT,
+            nResults: result.total,
+            returnedIds: result.results.map((r) => r.id),
+        });
+        return ok(result);
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+export async function getSessionHandler(deps, input) {
+    try {
+        const session = await deps.store.getById(input.id);
+        if (!session) {
+            return err(new Error(`session ${input.id} not found`));
+        }
+        return ok(session);
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+export async function recallFactsHandler(deps, input) {
+    if (!deps.factRecall) {
+        return err(new Error("fact recall not wired in this deployment"));
+    }
+    try {
+        const query = {
+            query: input.query ?? "",
+            mode: input.mode ?? "hybrid",
+            limit: input.limit ?? DEFAULT_LIMIT,
+            ...(input.subject !== undefined ? { subject: input.subject } : {}),
+            ...(input.predicate !== undefined ? { predicate: input.predicate } : {}),
+            ...(input.kind !== undefined ? { kind: input.kind } : {}),
+            ...(input.includeSuperseded !== undefined
+                ? { includeSuperseded: input.includeSuperseded }
+                : {}),
+            ...(input.minConfidence !== undefined
+                ? { minConfidence: input.minConfidence }
+                : {}),
+        };
+        const result = await deps.factRecall.search(query);
+        // Telemetry — see recallSessionsHandler. Fire-and-forget.
+        void logFactQuery({
+            source: "mcp",
+            query: input.query ?? null,
+            subject: input.subject ?? null,
+            predicate: input.predicate ?? null,
+            kind: input.kind ?? null,
+            mode: input.mode ?? "hybrid",
+            limit: input.limit ?? DEFAULT_LIMIT,
+            nResults: result.total,
+            returnedIds: result.results.map((r) => r.id),
+        });
+        return ok(result);
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+export async function getFactHistoryHandler(deps, input) {
+    if (!deps.factStore) {
+        return err(new Error("fact store not wired in this deployment"));
+    }
+    try {
+        const chains = await deps.factStore.getHistory(input.subject, input.predicate);
+        return ok({ subject: input.subject, predicate: input.predicate ?? null, chains });
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+const CITE_SESSION_DESCRIPTION = `Log that you used a previously-surfaced session in your response. Pass the session ID. This lets NLM learn which surfaced sessions are actually useful, training a per-operator reranker over time. Call after writing your response, with one cite per surfaced session you actually drew from.`;
+const RECALL_DESCRIPTION = `Search prior AI sessions across every runtime the user has connected (Claude Code,
+Hermes, pi, Codex, Gemini, Aider). Local-first, fast (~200-400ms warm), idempotent,
+safe to call eagerly. No rate limit; no cost per call.
+
+CALL THIS FIRST — before answering — whenever the user prompt contains any of:
+
+  Decision / position questions
+    "what did we decide about X" · "did we figure out X" · "what's our take on X"
+    "have we tried X" · "where did we land on X" · "what was the conclusion"
+
+  Status / open-thread questions
+    "what's still open on X" · "where did we leave X" · "what's blocked on X"
+    "what's the state of X" · "is X done"
+
+  History / continuity questions
+    "have I worked on X" · "when did we last X" · "did we already do X"
+    "have I talked to <person>" · "what's the history with X"
+
+  Implicit references to prior context (the dangerous case — easy to miss)
+    "that pgvector thing" · "the X discussion" · "our auth approach"
+    "the one we built for <client>" · "the issue we hit last week"
+
+Not calling when the user references past work is the failure mode this tool exists
+to prevent: re-derivation of already-solved problems, contradicting prior decisions,
+re-litigating resolved open questions, ignoring the user's accumulated context.
+
+Returns ranked session digests (id, label, summary, entities, decisions, open
+questions). Call get_session for the full body when a digest looks relevant.
+
+Skip ONLY when the request is purely forward-looking with no plausible prior
+context — drafting wholly new content, naming something new, brainstorming
+greenfield ideas. When in doubt, call.
+
+When you reference a returned session in your response, call \`cite_session(id)\` to log it so the recall layer can learn what is useful.
+
+Args:
+  - query: keyword(s) to search. Token-weighted match against label, decisions,
+           open questions, and summary. Optional if entity or kind is provided.
+  - entity: filter to sessions tagged with this entity. Optional.
+  - kind: "decision" or "open" — restrict to sessions containing that marker
+          kind. Omit for any. Optional.
+  - mode: "hybrid" (default — keyword BM25 + semantic embeddings), "keyword", or
+          "semantic". Optional.
+  - limit: max results (1-100, default 10).`;
+const GET_SESSION_DESCRIPTION = `Fetch one full session by its canonical ID, including the conversational body.
+
+Call this AFTER recall_sessions when a returned digest looks relevant and the
+summary alone isn't enough to answer — e.g. you need the exact wording of a
+decision, the full reasoning behind a pivot, the specific commands that were
+run, or any quote you intend to reference verbatim.
+
+The recall_sessions digest is optimized for ranking and scanning; the full body
+contains the actual conversation transcript that produced the decision.
+
+Args:
+  - id: Canonical session ID returned by recall_sessions (e.g. "cc_abc123",
+        "sess_pgvector"). Pass the id field from the recall_sessions result.`;
+const RECALL_FACTS_DESCRIPTION = `Look up specific (subject, predicate, value) facts the user has established in
+prior sessions — model aliases, framework choices, endpoints, ports, hosts,
+deadlines, pricing, owners, dependencies, etc.
+
+CALL THIS when the user asks for a concrete value rather than a prose summary:
+
+  "what port is X on" · "what model does Y use" · "what's the endpoint for Z"
+  "what framework did we pick for X" · "who owns the X project"
+  "when's the X deadline" · "what did we set X to" · "where does X live"
+  "what version of X are we on" · "what's our X account"
+
+Prefer this over recall_sessions when the user wants the *answer*, not the
+*conversation* — facts return the exact value with provenance (source session
++ source quote), no scanning required. recall_sessions is the right tool when
+the user wants context, reasoning, or the full discussion.
+
+Returns matching Fact records ordered by recency. Superseded facts are excluded
+by default; call get_fact_history to walk the chain of how a value evolved
+("when did X flip from Fastify to Hono?").
+
+Examples:
+  recall_facts(subject="mac-pro-llm-host", predicate="model")
+    → the model alias currently exposed on the Mac Pro LLM endpoint
+  recall_facts(subject="nlm-memory-ts", predicate="framework")
+    → the web framework picked for nlm-memory-ts
+  recall_facts(subject="goat-home-services")
+    → all known facts about the GOAT engagement
+  recall_facts(query="routing", kind="decision")
+    → recent decision-kind facts mentioning routing
+
+Args:
+  - query: free-text search against fact values. Optional if subject /
+           predicate / kind is set.
+  - subject: exact-match normalized (lowercase-kebab) entity or topic name.
+  - predicate: exact-match predicate from the closed vocabulary (framework,
+               endpoint, model, port, host, owner, pricing, cost, deadline,
+               status, stack, runtime, library, version, dependency, schema,
+               integration, deployment, repo, branch, commit, description,
+               decided-on, assumption, blocker).
+  - kind: "decision" | "open" | "attribute". Optional.
+  - mode: "hybrid" (default — keyword BM25 + semantic embeddings), "keyword",
+          or "semantic".
+  - includeSuperseded: true to include outdated facts. Default false.
+  - minConfidence: lower bound on classifier confidence. Default 0.6.
+  - limit: max results (1-100, default 10).`;
+const GET_FACT_HISTORY_DESCRIPTION = `Walk the supersedence chain for a (subject, predicate) pair to see how a value
+changed over time. Call this when the user asks about evolution, history of a
+choice, or wants to understand a prior decision that's since changed:
+
+  "when did we switch from X to Y" · "what did we use before X"
+  "wasn't X different a month ago" · "history of <X choice>"
+  "why did we change from X to Y"
+
+This is the editable-timeline feature: NLM preserves rejected/replaced decisions
+as superseded entries rather than deleting them, so the reasoning trail survives.
+
+Returns chains ordered newest → oldest. The head is the current value; subsequent
+entries are predecessors, each linked forward via supersededBy.
+
+Args:
+  - subject: normalized (lowercase-kebab) entity or topic name.
+  - predicate: optional — narrow to a single (subject, predicate) chain. When
+               omitted, returns one chain per predicate for this subject.`;
+// Minimum length for a session ID to be treated as valid.
+const MIN_CITE_ID_LEN = 6;
+export async function citeSessionHandler(input) {
+    if (!input.id || input.id.length < MIN_CITE_ID_LEN) {
+        return err(new Error(`id must be at least ${MIN_CITE_ID_LEN} characters`));
+    }
+    try {
+        await appendCitation({
+            conversationId: input.conversation_id ?? "mcp_tool",
+            citedId: input.id,
+            kind: "tool_use",
+            ...(input.reason !== undefined ? { responsePreview: input.reason } : {}),
+        });
+        return ok({ logged: true, id: input.id });
+    }
+    catch (e) {
+        return err(e);
+    }
+}
+export function createMcpServer(deps) {
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    });
+    server.registerTool("recall_sessions", {
+        title: "Recall Sessions from NLM",
+        description: RECALL_DESCRIPTION,
+        inputSchema: {
+            query: z
+                .string()
+                .default("")
+                .describe("Keyword(s) to search. Optional if entity or kind is set."),
+            entity: z
+                .string()
+                .optional()
+                .describe("Filter to sessions tagged with this entity name."),
+            kind: z
+                .enum(["decision", "open"])
+                .optional()
+                .describe("Filter to sessions with a decision or open marker."),
+            mode: z
+                .enum(["keyword", "semantic", "hybrid"])
+                .optional()
+                .describe("Search mode. Defaults to hybrid (keyword BM25 + semantic embeddings)."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(DEFAULT_LIMIT)
+                .describe("Max results to return."),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (args) => recallSessionsHandler(deps, args));
+    server.registerTool("get_session", {
+        title: "Get Full NLM Session",
+        description: GET_SESSION_DESCRIPTION,
+        inputSchema: {
+            id: z.string().min(1).describe("Canonical session ID."),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (args) => getSessionHandler(deps, args));
+    if (deps.factRecall && deps.factStore) {
+        server.registerTool("recall_facts", {
+            title: "Recall Facts from NLM",
+            description: RECALL_FACTS_DESCRIPTION,
+            inputSchema: {
+                query: z
+                    .string()
+                    .default("")
+                    .describe("Free-text search against fact values. Optional if subject/predicate/kind set."),
+                subject: z
+                    .string()
+                    .optional()
+                    .describe("Exact-match normalized entity/topic (lowercase-kebab)."),
+                predicate: z
+                    .string()
+                    .optional()
+                    .describe("Exact-match predicate from the closed vocabulary."),
+                kind: z
+                    .enum(["decision", "open", "attribute"])
+                    .optional()
+                    .describe("Filter to a single fact kind."),
+                mode: z
+                    .enum(["keyword", "semantic", "hybrid"])
+                    .optional()
+                    .describe("Search mode. Defaults to hybrid (keyword BM25 + semantic embeddings)."),
+                includeSuperseded: z
+                    .boolean()
+                    .optional()
+                    .describe("Include outdated facts. Default false."),
+                minConfidence: z
+                    .number()
+                    .min(0)
+                    .max(1)
+                    .optional()
+                    .describe("Lower bound on classifier confidence. Default 0.6."),
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(100)
+                    .default(DEFAULT_LIMIT)
+                    .describe("Max results to return."),
+            },
+            annotations: {
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: true,
+            },
+        }, async (args) => recallFactsHandler(deps, args));
+        server.registerTool("get_fact_history", {
+            title: "Get Fact Supersedence History",
+            description: GET_FACT_HISTORY_DESCRIPTION,
+            inputSchema: {
+                subject: z.string().min(1).describe("Normalized entity/topic name."),
+                predicate: z
+                    .string()
+                    .optional()
+                    .describe("Narrow to one (subject, predicate) chain."),
+            },
+            annotations: {
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: true,
+            },
+        }, async (args) => getFactHistoryHandler(deps, args));
+    }
+    server.registerTool("cite_session", {
+        title: "Cite NLM Session",
+        description: CITE_SESSION_DESCRIPTION,
+        inputSchema: {
+            id: z.string().min(MIN_CITE_ID_LEN).describe("Session ID returned by recall_sessions that you referenced in your response."),
+            conversation_id: z
+                .string()
+                .optional()
+                .describe("Current conversation ID. Optional — NLM infers from context when absent."),
+            reason: z
+                .string()
+                .optional()
+                .describe("Why this session was useful. Optional but encouraged — articulating the reason is a weak training signal."),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async (args) => citeSessionHandler(args));
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

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

package/dist/ports/fact-store.d.ts

@@ -0,0 +1,82 @@
+/**
+ * FactStore — the only way core/ reads or writes the fact corpus.
+ *
+ * Companion to SessionStore. Sessions are the operator-recall unit; facts are
+ * the agent-recall projection — normalized (subject, predicate, value) triples
+ * derived from sessions, supersedence-aware. See
+ * docs/plans/factstore-design.md.
+ *
+ * Phase B.1 ships the storage port + adapter only. No extraction wired yet
+ * (B.2), no recall service (B.3), no MCP surface (B.3), no supersedence
+ * autodetect (B.4). The surface here is the minimum needed by future phases:
+ * insert one or many, look up by id, look up current (non-superseded) facts
+ * by subject and optional predicate, mark a fact superseded.
+ */
+import type { Fact, FactHistoryChain, FactKind } from "../shared/types.js";
+export interface FactQuery {
+    readonly subject: string;
+    readonly predicate?: string;
+    readonly includeSuperseded?: boolean;
+    readonly limit?: number;
+}
+export interface FactSemanticNeighbor {
+    readonly factId: string;
+    readonly distance: number;
+}
+/** Pre-filter applied at the storage layer before keyword scoring runs. */
+export interface FactListFilter {
+    readonly subject?: string;
+    readonly predicate?: string;
+    readonly kind?: FactKind;
+    readonly includeSuperseded?: boolean;
+    readonly minConfidence?: number;
+    readonly limit?: number;
+}
+export interface FactStore {
+    /** Atomically insert a single fact. Throws on duplicate id. */
+    insert(fact: Fact): Promise<void>;
+    /** Atomically insert many facts as one transaction. Throws on any duplicate id. */
+    insertMany(facts: ReadonlyArray<Fact>): Promise<void>;
+    getById(id: string): Promise<Fact | null>;
+    /**
+     * Exact-match lookup of the current (non-superseded) fact for a
+     * subject+predicate pair. Returns null if none exists. This is the hot
+     * path for deterministic supersedence on ingest (Phase B.4).
+     */
+    findCurrent(subject: string, predicate: string): Promise<Fact | null>;
+    /**
+     * List facts matching the query. Defaults: current (non-superseded) only,
+     * limit 50. Ordered by created_at descending.
+     */
+    list(query: FactQuery): Promise<ReadonlyArray<Fact>>;
+    /**
+     * List all facts attributable to a single session. Used by the UI to show
+     * a fact-count badge on a session digest, and by tests.
+     */
+    listBySession(sessionId: string): Promise<ReadonlyArray<Fact>>;
+    /**
+     * Mark `oldId` as superseded by `newId`. Both facts must exist. Reversible
+     * by passing null as newId (Phase C operator-undo affordance).
+     */
+    markSuperseded(oldId: string, newId: string | null): Promise<void>;
+    /**
+     * Pre-filtered fact list used by FactRecallService. Applies subject /
+     * predicate / kind / confidence / superseded filters at the SQL layer
+     * before keyword scoring runs in core. No ordering guarantee beyond
+     * `created_at DESC`.
+     */
+    listForRecall(filter: FactListFilter): Promise<ReadonlyArray<Fact>>;
+    /**
+     * sqlite-vec KNN over fact_embeddings. Returns up to `limit` nearest
+     * neighbors by L2 distance. The service converts distance to cosine and
+     * blends with keyword scores.
+     */
+    semanticSearch(queryVector: Float32Array, limit: number): Promise<ReadonlyArray<FactSemanticNeighbor>>;
+    /**
+     * Supersedence chain inspection. When `predicate` is provided, returns a
+     * single chain (or empty array if no facts match). When omitted, returns
+     * one chain per distinct predicate for that subject. Each chain orders
+     * newest → oldest by created_at.
+     */
+    getHistory(subject: string, predicate?: string): Promise<ReadonlyArray<FactHistoryChain>>;
+}

package/dist/ports/fact-store.js

@@ -0,0 +1,16 @@
+/**
+ * FactStore — the only way core/ reads or writes the fact corpus.
+ *
+ * Companion to SessionStore. Sessions are the operator-recall unit; facts are
+ * the agent-recall projection — normalized (subject, predicate, value) triples
+ * derived from sessions, supersedence-aware. See
+ * docs/plans/factstore-design.md.
+ *
+ * Phase B.1 ships the storage port + adapter only. No extraction wired yet
+ * (B.2), no recall service (B.3), no MCP surface (B.3), no supersedence
+ * autodetect (B.4). The surface here is the minimum needed by future phases:
+ * insert one or many, look up by id, look up current (non-superseded) facts
+ * by subject and optional predicate, mark a fact superseded.
+ */
+export {};
+//# sourceMappingURL=fact-store.js.map

package/dist/ports/fact-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact-store.js","sourceRoot":"","sources":["../../src/ports/fact-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/ports/llm-client.d.ts

@@ -0,0 +1,42 @@
+/**
+ * LLMClient — outbound LLM calls (embedding + classification).
+ *
+ * Implementations: OllamaClient (default, local), AnthropicClient, OpenAIClient.
+ * core/ only sees this interface; it never imports an HTTP client.
+ */
+export interface EmbedResult {
+    readonly vector: Float32Array;
+    readonly model: string;
+}
+export type EmbeddingKind = "query" | "document";
+/**
+ * Raw fact extracted by the classifier. No id, no source_session_id, no
+ * created_at yet — those get filled in at ingest time by extractFacts().
+ *
+ * `subject` and `predicate` come from the classifier already normalized
+ * (lowercased, trimmed) per the prompt contract, but the coercer re-normalizes
+ * defensively because LLM output is not trustworthy.
+ */
+export interface ExtractedFact {
+    readonly kind: "decision" | "open" | "attribute";
+    readonly subject: string;
+    readonly predicate: string;
+    readonly value: string;
+    readonly sourceQuote?: string;
+}
+export interface ClassifyResult {
+    readonly label: string;
+    readonly summary: string;
+    readonly entities: ReadonlyArray<string>;
+    readonly decisions: ReadonlyArray<string>;
+    readonly open: ReadonlyArray<string>;
+    readonly confidence: number;
+    readonly facts: ReadonlyArray<ExtractedFact>;
+}
+export declare class LLMUnreachableError extends Error {
+    constructor(provider: string, cause?: unknown);
+}
+export interface LLMClient {
+    embed(text: string, kind: EmbeddingKind): Promise<EmbedResult>;
+    classify(transcript: string): Promise<ClassifyResult>;
+}

package/dist/ports/llm-client.js

@@ -0,0 +1,14 @@
+/**
+ * LLMClient — outbound LLM calls (embedding + classification).
+ *
+ * Implementations: OllamaClient (default, local), AnthropicClient, OpenAIClient.
+ * core/ only sees this interface; it never imports an HTTP client.
+ */
+export class LLMUnreachableError extends Error {
+    constructor(provider, cause) {
+        super(`LLM unreachable: ${provider}`);
+        this.name = "LLMUnreachableError";
+        this.cause = cause;
+    }
+}
+//# sourceMappingURL=llm-client.js.map

package/dist/ports/llm-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-client.js","sourceRoot":"","sources":["../../src/ports/llm-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAmCH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,QAAgB,EAAE,KAAe;QAC3C,KAAK,CAAC,oBAAoB,QAAQ,EAAE,CAAC,CAAC;QACtC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF"}

package/dist/ports/logger.d.ts

@@ -0,0 +1,13 @@
+/**
+ * StructuredLogger — sole logging seam for core/.
+ *
+ * Outer layers wire a concrete logger (console, pino, file-append). Tests
+ * substitute a recording logger. core/ never calls console.log directly.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface LogFields {
+    readonly [key: string]: string | number | boolean | null | undefined;
+}
+export interface StructuredLogger {
+    log(level: LogLevel, message: string, fields?: LogFields): void;
+}

package/dist/ports/logger.js

@@ -0,0 +1,8 @@
+/**
+ * StructuredLogger — sole logging seam for core/.
+ *
+ * Outer layers wire a concrete logger (console, pino, file-append). Tests
+ * substitute a recording logger. core/ never calls console.log directly.
+ */
+export {};
+//# sourceMappingURL=logger.js.map

package/dist/ports/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/ports/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/ports/session-store.d.ts

@@ -0,0 +1,29 @@
+/**
+ * SessionStore — the only way core/ reads or writes the session corpus.
+ *
+ * Implementations live in core/storage. Adapters and use cases depend on this
+ * interface, never on better-sqlite3 directly. Swapping SQLite for Postgres
+ * tomorrow means writing a new implementation; core/ does not change.
+ */
+import type { Session, SessionStatus } from "../shared/types.js";
+export interface SessionFilter {
+    readonly entity?: string;
+    readonly hasDecisions?: boolean;
+    readonly hasOpenQuestions?: boolean;
+}
+export interface SemanticNeighbor {
+    readonly sessionId: string;
+    readonly distance: number;
+}
+export interface KeywordNeighbor {
+    readonly sessionId: string;
+    readonly score: number;
+}
+export interface SessionStore {
+    list(filter?: SessionFilter): Promise<ReadonlyArray<Session>>;
+    getById(sessionId: string): Promise<Session | null>;
+    getByIds(ids: ReadonlyArray<string>): Promise<ReadonlyArray<Session>>;
+    semanticSearch(queryVector: Float32Array, limit: number): Promise<ReadonlyArray<SemanticNeighbor>>;
+    keywordSearch(query: string, limit: number): Promise<ReadonlyArray<KeywordNeighbor>>;
+    updateStatus(sessionId: string, status: SessionStatus): Promise<void>;
+}