nlm-memory 0.19.0 → 0.20.1

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

@@ -0,0 +1,35 @@
+/**
+ * EntityStore -- read/write surface for the entities + entity_variants tables.
+ *
+ * Lives on Storage.entities. Both SQLite and PG adapters implement this port.
+ */
+export interface EntityRow {
+    readonly canonical: string;
+    readonly type: string;
+    readonly status: string;
+    readonly sessionCount: number;
+    readonly firstSeenSession: string | null;
+    readonly lastSeenSession: string | null;
+}
+export interface EntityStore {
+    /**
+     * Merge source entity into target entity.
+     *
+     * Semantics (both adapters, inside one transaction):
+     *   1. INSERT OR IGNORE (pg: ON CONFLICT DO NOTHING) session_entities rows
+     *      from source onto target to preserve all session links.
+     *   2. DELETE the source's session_entities rows.
+     *   3. Recompute target.session_count exactly from session_entities.
+     *   4. Widen target first_seen_session / last_seen_session to the
+     *      chronologically earliest / latest session across both entities.
+     *   5. INSERT INTO entity_variants (variant=source, canonical=target,
+     *      source_session_id=NULL) so future ingest of the old surface form
+     *      binds to the canonical.
+     *   6. Re-point any existing entity_variants rows where canonical=source
+     *      to canonical=target.
+     *   7. Keep the source entities row with status='retired', session_count=0.
+     *
+     * Errors loudly when target is missing or already retired.
+     */
+    merge(source: string, target: string): Promise<void>;
+}

package/dist/ports/entity-store.js

@@ -0,0 +1,7 @@
+/**
+ * EntityStore -- read/write surface for the entities + entity_variants tables.
+ *
+ * Lives on Storage.entities. Both SQLite and PG adapters implement this port.
+ */
+export {};
+//# sourceMappingURL=entity-store.js.map

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"fact-store.js","sourceRoot":"","sources":["../../src/ports/fact-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA4JH,uDAAuD;AACvD,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,SAAiB,EAAE,KAAa;IAChF,OAAO,GAAG,OAAO,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;AAC5C,CAAC"}
+{"version":3,"file":"fact-store.js","sourceRoot":"","sources":["../../src/ports/fact-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAoKH,uDAAuD;AACvD,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,SAAiB,EAAE,KAAa;IAChF,OAAO,GAAG,OAAO,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;AAC5C,CAAC"}

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

@@ -54,9 +54,17 @@ export interface RewriteResult {
     /** Free-text rationale for debugging; not used by the retrieval path. */
     readonly rationale?: string;
 }
+export interface WorkstreamCandidateHint {
+    readonly label: string;
+}
 export interface LLMClient {
-    embed(text: string, kind: EmbeddingKind): Promise<EmbedResult>;
+    embed(text: string, kind: EmbeddingKind, opts?: {
+        signal?: AbortSignal;
+    }): Promise<EmbedResult>;
     classify(transcript: string): Promise<ClassifyResult>;
+    /** Name which candidate workstream this session belongs to, or null for "none".
+     *  Returns the chosen candidate.label verbatim. Content is label+summary or a transcript. */
+    nameWorkstream(content: string, candidates: ReadonlyArray<WorkstreamCandidateHint>): Promise<string | null>;
     /**
      * Rewrite a recall query for better retrieval. Cheap-ish call (one-shot
      * chat completion, ~hundreds of ms locally). Implementations MUST throw

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

@@ -5,6 +5,7 @@
  * interface, never on better-sqlite3 directly. Swapping SQLite for Postgres
  * tomorrow means writing a new implementation; core/ does not change.
  */
+import type { BindingSource } from "../core/workstream/model.js";
 import type { Session, SessionStatus } from "../shared/types.js";
 export interface SessionFilter {
     readonly entity?: string;
@@ -27,11 +28,18 @@ export interface KeywordNeighbor {
  */
 export interface SearchOptions {
     readonly includeSuperseded?: boolean;
+    readonly workstreamIds?: ReadonlyArray<string>;
 }
 export interface SessionStore {
     list(filter?: SessionFilter): Promise<ReadonlyArray<Session>>;
     getById(sessionId: string): Promise<Session | null>;
     getByIds(ids: ReadonlyArray<string>): Promise<ReadonlyArray<Session>>;
+    /**
+     * Sessions whose lifespan [started_at, ended_at or open] overlaps the
+     * half-open window [fromIso, toIso). Body is omitted (callers that need it
+     * fetch by id). Ordered by started_at ascending. Used by the work-digest.
+     */
+    listByDateRange(fromIso: string, toIso: string): Promise<ReadonlyArray<Session>>;
     semanticSearch(queryVector: Float32Array, limit: number, opts?: SearchOptions): Promise<ReadonlyArray<SemanticNeighbor>>;
     keywordSearch(query: string, limit: number, opts?: SearchOptions): Promise<ReadonlyArray<KeywordNeighbor>>;
     /**
@@ -53,4 +61,8 @@ export interface SessionStore {
      * action that lets an operator retroactively retire a stale session.
      */
     markSuperseded(predecessorId: string, successorId: string): Promise<void>;
+    setWorkstreamBinding(sessionId: string, workstreamId: string | null, source: BindingSource | null, confidence: number | null): Promise<void>;
+    listSessionIdsByWorkstreams(workstreamIds: ReadonlyArray<string>): Promise<ReadonlyArray<string>>;
+    getEntities(sessionId: string): Promise<ReadonlyArray<string>>;
+    getWorkstreamIds(sessionIds: ReadonlyArray<string>): Promise<Map<string, string | null>>;
 }

package/dist/ports/storage.d.ts

@@ -1,53 +1,30 @@
 /**
  * Storage — top-level handle for NLM's fact + session corpus. Owns lifecycle
- * (init/close) and the atomic unit-of-work primitive (withTransaction).
- *
- * Read paths use the bare .facts / .sessions handles. Writes that must
- * commit together — session+facts+embeddings on ingest, supersedence chain
- * edits — go through withTransaction so the adapter chooses its own
- * atomicity mechanism (single SQLite connection, PG transaction, etc.)
- * without core/ knowing which backend it's talking to.
+ * (init/close). Read and write paths use the bare .facts / .sessions handles;
+ * adapters manage atomicity internally via explicit BEGIN/COMMIT on a PoolClient
+ * (PG) or a single WAL writer (SQLite).
  *
  * See docs/plans/2026-05-30-factstore-storage-port.md.
  */
 import type { CodeExemplarStore } from "./code-exemplar-store.js";
+import type { EntityStore } from "./entity-store.js";
 import type { FactStore } from "./fact-store.js";
 import type { SessionStore } from "./session-store.js";
 import type { SignalStore } from "./signal-store.js";
+import type { WorkstreamStore } from "./workstream-store.js";
 import type { SourceRegistryPort } from "../core/sources/source-registry.js";
 import type { ProviderRegistryPort } from "../core/providers/provider-registry.js";
-export interface StorageContext {
-    readonly facts: FactStore;
-    readonly sessions: SessionStore;
-}
 export interface Storage {
     readonly facts: FactStore;
     readonly sessions: SessionStore;
     readonly signals: SignalStore;
     readonly exemplars: CodeExemplarStore;
+    readonly workstreams: WorkstreamStore;
+    readonly entities: EntityStore;
     /** Transcript-source registry (claude-code/hermes/webhook/…). */
     readonly sources: SourceRegistryPort;
     /** LLM-provider registry (ollama/deepseek/openai/…). */
     readonly providers: ProviderRegistryPort;
-    /**
-     * Run `fn` inside an adapter-defined transaction. The handles on the
-     * provided StorageContext are bound to that transaction; reads and writes
-     * through them see one another, and either all commit or all roll back.
-     * Outer handles (storage.facts, storage.sessions) MUST NOT be used inside
-     * `fn`; adapters may enforce this with a runtime check.
-     *
-     * Callbacks MUST be synchronous. Async work (embedder calls, network I/O)
-     * runs BEFORE or AFTER withTransaction, not inside. The SQLite adapter
-     * enforces this constraint structurally (better-sqlite3 transactions are
-     * synchronous); the Postgres adapter will honor the same shape by
-     * batching sync operations into a single async txn. This keeps the
-     * port honest across backends and matches the established pattern in
-     * SqliteSessionStore.insertSession where embedding work lives outside
-     * the transaction.
-     *
-     * Nested calls are not supported. Adapters throw on nested invocation.
-     */
-    withTransaction<T>(fn: (ctx: StorageContext) => T): Promise<T>;
     /** Apply migrations / install extensions. Idempotent. */
     init(): Promise<void>;
     /** Release the underlying connection or pool. */

package/dist/ports/storage.js

@@ -1,12 +1,8 @@
 /**
  * Storage — top-level handle for NLM's fact + session corpus. Owns lifecycle
- * (init/close) and the atomic unit-of-work primitive (withTransaction).
- *
- * Read paths use the bare .facts / .sessions handles. Writes that must
- * commit together — session+facts+embeddings on ingest, supersedence chain
- * edits — go through withTransaction so the adapter chooses its own
- * atomicity mechanism (single SQLite connection, PG transaction, etc.)
- * without core/ knowing which backend it's talking to.
+ * (init/close). Read and write paths use the bare .facts / .sessions handles;
+ * adapters manage atomicity internally via explicit BEGIN/COMMIT on a PoolClient
+ * (PG) or a single WAL writer (SQLite).
  *
  * See docs/plans/2026-05-30-factstore-storage-port.md.
  */

package/dist/ports/storage.js.map

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

package/dist/ports/transcript-adapter.d.ts

@@ -31,6 +31,8 @@ export interface SessionChunk {
     readonly gitBranch: string;
     readonly text: string;
     readonly label: string;
+    /** Last assistant-turn model string seen in this chunk. Omitted when the transcript carries no model field. */
+    readonly model?: string;
     /**
      * Raw `nlm.signal` payloads found in the transcript (Pi custom_message
      * entries). Normalized + persisted by the scheduler, decoupled from session

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

@@ -0,0 +1,21 @@
+import type { Workstream } from "../core/workstream/model.js";
+export interface WorkstreamStore {
+    create(input: {
+        id: string;
+        label: string;
+    }): Promise<Workstream>;
+    getById(id: string): Promise<Workstream | null>;
+    findByNormalizedLabel(normalizedLabel: string): Promise<Workstream | null>;
+    listAll(): Promise<ReadonlyArray<Workstream>>;
+    touchLastSession(id: string, atIso: string): Promise<void>;
+    setLabel(id: string, label: string): Promise<void>;
+    setStatus(id: string, status: import("../core/workstream/model.js").WorkstreamStatus): Promise<void>;
+    /** Supersede fromId into intoId: set merged_into + status="merged", union entities, clear from's entity rows. */
+    merge(fromId: string, intoId: string): Promise<void>;
+    upsertEntities(workstreamId: string, entities: ReadonlyArray<string>): Promise<void>;
+    entitiesFor(workstreamIds: ReadonlyArray<string>): Promise<Map<string, string[]>>;
+    candidatesByEntityOverlap(entities: ReadonlyArray<string>, limit: number): Promise<ReadonlyArray<{
+        workstreamId: string;
+        entities: string[];
+    }>>;
+}

package/dist/ports/workstream-store.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=workstream-store.js.map

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

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

package/dist/shared/types.d.ts

@@ -36,6 +36,12 @@ export interface Session {
     readonly supersedes?: ReadonlyArray<string>;
     /** ID of the session that superseded this one, if any. Populated by getById; absent on bulk reads. */
     readonly supersededBy?: string | null;
+    /** Live binding to a workstream, if any. Populated by projections that select it (e.g. listByDateRange); absent elsewhere. */
+    readonly workstreamId?: string | null;
+    /** Classifier that produced this session's classification. NULL = classified before provenance tracking. */
+    readonly classifierProvider?: string | null;
+    readonly classifierModel?: string | null;
+    readonly classifierConfidence?: number | null;
 }
 /**
  * Supersedence-relation edge kinds in `session_edges.kind`.
@@ -95,6 +101,14 @@ export interface RecallQuery {
      * Task #303.
      */
     readonly includeSuperseded?: boolean;
+    /**
+     * Optional workstream id or label to filter recall results. When set, only
+     * sessions bound to the resolved workstream (or any member of its merge
+     * chain) are returned. Merge chains resolve to the live survivor. No-op
+     * when omitted or when `resolveWorkstreamMembers` is not wired into
+     * RecallServiceDeps.
+     */
+    readonly workstream?: string;
 }
 export interface RecallHit {
     readonly id: string;
@@ -150,7 +164,7 @@ export interface RecallResult {
  * docs/plans/factstore-design.md for the full design rationale.
  *
  * `kind` mirrors the marker taxonomy plus a third category for entity
- * attributes ("mac-pro-llm-host" + "endpoint" + "http://macpro:8080/v1").
+ * attributes ("local-llm-host" + "endpoint" + "http://macpro:8080/v1").
  *
  * `subject` and `predicate` are normalized (lowercased, trimmed) at extraction
  * time so the deterministic supersedence path can do exact-match collision
@@ -171,6 +185,13 @@ export interface Fact {
     readonly createdAt: string;
     readonly supersededBy: string | null;
     readonly confidence: number;
+    /**
+     * When set, the fact was retired (hard-removed from active recall). Populated
+     * by store reads; absent on bulk constructions. Recall's in-memory filter
+     * excludes any fact carrying this so retired facts can never leak through the
+     * semantic-neighbour path (where the SQL pre-filter does not apply).
+     */
+    readonly retiredAt?: string | null;
 }
 export type FactMatchField = "value" | "subject" | "predicate" | "semantic";
 export interface FactRecallQuery {
@@ -209,7 +230,7 @@ export interface FactRecallResult {
 }
 /**
  * A current high-confidence fact attached to a recall result — the hook
- * uses these to inject structured context ("polysignal uses: duckdb")
+ * uses these to inject structured context ("beacon uses: duckdb")
  * alongside the session pointer list. Selected by `pickRelatedFacts`
  * server-side using the entities of the top recall hits, the fact-store
  * confidence filter, and the spec G.1 corroborationCount.

package/fixtures/classifier-gold/README.md

@@ -0,0 +1,94 @@
+# Classifier Gold Fixtures
+
+A hand-authored evaluation set for the NLM session classifier. These fixtures
+are part of the shipped product; they run as part of the deterministic fixture
+eval in CI and are public.
+
+## What is in this set
+
+20 synthetic agent-session transcripts covering the range of sessions the
+classifier encounters in practice:
+
+| Category | IDs | Count |
+|---|---|---|
+| Coding: bug fix | 01, 02, 03 | 3 |
+| Coding: feature | 04, 05, 06 | 3 |
+| Coding: refactor | 07, 08 | 2 |
+| Ops / infra | 09, 10, 11, 12 | 4 |
+| Research / writing | 13, 14, 15 | 3 |
+| Meeting notes | 16 | 1 |
+| Low-signal / trivial | 17, 18, 19, 20 | 4 |
+
+Low-signal sessions (17-20) contain no project context, no decisions, and no
+meaningful entities. The classifier prompt instructs models to use confidence
+<= 0.4 for routine/trivial sessions. The fixture eval asserts this calibration
+in both directions (low-signal sessions must score <= 0.4; substantive sessions
+must score > 0.4).
+
+## Authorship rules
+
+All content is fully synthetic. No real projects, people, companies, or
+infrastructure appear anywhere in the transcripts or references. Invented
+names follow the pattern: single lowercase word (corvid-api, taskvine, lumens,
+pulsearch, irongate, gridhost, droneflow, bridgeauth, flarepath, vaultdb,
+axiom-worker, crestapi, orbitflow, cobalt-api). Domains are example.com.
+Paths are /opt/... or /home/dev/... style.
+
+No em dashes appear in any file in this directory. This is a hard rule for
+all text in this repository, fixtures included.
+
+## reference.json schema
+
+```json
+[
+  {
+    "id": "<transcript filename without .txt>",
+    "label": "Expected label string (4-10 words)",
+    "labelAlternates": ["alternate phrasings that also count as correct"],
+    "entities": ["exact named things the classifier must surface"],
+    "decisions": ["key phrase that must appear in a matched extracted decision"],
+    "expectLowConfidence": false
+  }
+]
+```
+
+Field notes:
+
+- `entities`: only unambiguous named things (project names, specific
+  technologies, specific error types). Do not include generic nouns. An entity
+  is matched if the reference string appears (case-insensitive) as a substring
+  in any extracted entity, or vice versa.
+- `decisions`: concrete enough to match by key-phrase overlap. The scorer
+  checks whether a reference decision's key tokens appear in at least one
+  extracted decision. Author reference decisions around the unique commitment
+  (e.g. "SELECT FOR UPDATE SKIP LOCKED") rather than generic phrasing.
+- `expectLowConfidence`: true for sessions 17-20. The classifier must return
+  confidence <= 0.4 for these or the calibration check fails.
+
+## Frozen prompt dependency
+
+The reference values are authored against the classifier prompt in:
+
+    src/core/classifier/prompt.ts (CLASSIFIER_SYSTEM_PROMPT)
+
+Specifically:
+- The label style guidance ("4-10 word string title")
+- The closed PREDICATE_VOCABULARY (for any expected facts, though facts are
+  not included in this fixture set's reference shape)
+- The confidence instruction ("Use 0.4 or below for routine/trivial sessions")
+
+If CLASSIFIER_SYSTEM_PROMPT changes materially, review all reference.json
+entries and update expectLowConfidence thresholds if the confidence instruction
+changes.
+
+## How to add a fixture
+
+1. Write a .txt transcript in transcripts/. File name: NN-category-short-slug.txt.
+   Keep it 1-6K characters. Use only invented names. No em dashes.
+2. Add an entry to reference.json. Choose entities and decisions that are
+   unambiguous: a competent extraction must find them; borderline cases must
+   not be included.
+3. Run the fixture eval to confirm your reference scores as expected:
+   `npx tsx scripts/eval/classifier-eval.ts --fixtures tests/fixtures/classifier-gold`
+4. Increment the fixture count comment at the top of
+   src/core/eval/classifier-fixture-eval.ts if it exists.