hippo-memory 1.61.0 → 1.63.0

package/dist/graph-extract.js

@@ -1,16 +1,15 @@
 /**
- * E3.1 deterministic entity extraction (first slice)
- * (docs/plans/2026-06-01-e3-deterministic-extraction.md).
+ * Deterministic entity extraction.
  *
- * Populates the E3 graph from the already-structured consolidated E2-object tables -
+ * Populates the graph from the already-structured consolidated first-class object tables -
  * NO NLP, no precision gate for entities + supersedes. The graph is a pure derived
- * function of the current E2 state, so `extractGraph` is an idempotent REBUILD: clear
+ * function of the current object state, so `extractGraph` is an idempotent REBUILD: clear
  * the tenant's graph, then re-derive entities + `supersedes` relations from decisions /
- * policies / customer_notes / project_briefs (the four E2 types whose kind maps to the
+ * policies / customer_notes / project_briefs (the four object types whose kind maps to the
  * `entity_type` enum). All writes go through the src/graph.ts consolidated-source guard
  * (insertEntity / insertRelation / clearGraph); this module issues no raw SQL.
  *
- * Pass 3 (E3 cross-object, docs/plans/2026-06-02-e3-cross-object-references.md) adds the
+ * Pass 3 adds the
  * first CROSS-OBJECT relations: a deterministic NAME-MATCH heuristic that emits a
  * `references` edge when one consolidated object's text contains another entity's name.
  * It is conservative (word-boundary, length-bounded, ambiguity-guarded, per-source
@@ -27,6 +26,7 @@ import { loadPolicies } from './policies.js';
 import { loadCustomerNotes } from './customer-notes.js';
 import { loadProjectBriefs } from './project-briefs.js';
 import { assertTenantId } from './tenant.js';
+import { escapeRegex } from './escape.js';
 /** Per-type load cap (the loaders default to 100). A type whose active or superseded
  *  set exceeds this is truncated; `ExtractResult.truncated` records it so the
  *  incompleteness is observable rather than silent. */
@@ -46,8 +46,8 @@ export const MAX_TARGET_NAMES = 5000;
 function keyOf(entityType, e2Id) {
     return `${entityType}:${e2Id}`;
 }
-/** The four E2-derived extraction entity types map 1:1 to source_object_type; the other
- *  two EntityType members ('person', 'system') have no E2 table and stay unmapped. */
+/** The four object-derived extraction entity types map 1:1 to source_object_type; the other
+ *  two EntityType members ('person', 'system') have no object table and stay unmapped. */
 const ENTITY_TYPE_TO_SOURCE_OBJECT = {
     decision: 'decision',
     policy: 'policy',
@@ -56,18 +56,14 @@ const ENTITY_TYPE_TO_SOURCE_OBJECT = {
     person: undefined,
     system: undefined,
 };
-/** The E2 source-object ref for an extraction row (always set: every extracted row is an
- *  E2 object). Throws on an unmappable entityType (a graph invariant violation). */
+/** The source-object ref for an extraction row (always set: every extracted row is a
+ *  first-class object). Throws on an unmappable entityType (a graph invariant violation). */
 function sourceObjectOf(entityType, e2Id) {
     const type = ENTITY_TYPE_TO_SOURCE_OBJECT[entityType];
     if (!type)
         throw new Error(`graph-extract: entityType '${entityType}' has no source_object_type mapping`);
     return { type, id: e2Id };
 }
-/** Escape a string for safe use as a literal inside a RegExp alternation. */
-function escapeRegex(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
 /** Unordered entity-id pair key, so a relation between a,b is found in either direction. */
 function pairKey(a, b) {
     return a < b ? `${a}:${b}` : `${b}:${a}`;
@@ -95,7 +91,7 @@ textOf) {
             // loadProjectBriefs (wired at each extractGraph call site); every one of their row
             // types declares id: number, memoryId: string | null, supersededBy: number | null.
             // `any` here is the deliberate type-erasure boundary (see eslint-disable above)
-            // that lets one loop handle all four E2 row shapes.
+            // that lets one loop handle all four object row shapes.
             rows.push({
                 entityType,
                 e2Id: r.id,
@@ -109,9 +105,9 @@ textOf) {
     return { rows, hitCap };
 }
 /**
- * Idempotent rebuild of the tenant's deterministic graph from its consolidated E2
+ * Idempotent rebuild of the tenant's deterministic graph from its consolidated first-class
  * objects. Returns the entity/relation counts (+ which types were truncated at the
- * per-type cap). Safe to re-run: output is a pure function of the current E2 state.
+ * per-type cap). Safe to re-run: output is a pure function of the current object state.
  */
 export function extractGraph(hippoRoot, tenantId) {
     assertTenantId('extractGraph', tenantId);
@@ -129,50 +125,27 @@ export function extractGraph(hippoRoot, tenantId) {
         const { rows, hitCap } = loadType(hippoRoot, tenantId, src.entityType, src.loadFn, src.nameOf, src.textOf);
         return { entityType: src.entityType, rows, hitCap };
     });
-    // WRITE PHASE (codex P2): clear + every insert run in ONE transaction, so two
+    // WRITE PHASE: clear + every insert run in ONE transaction, so two
     // concurrent rebuilds serialize on the SQLite write lock (no duplicate rows)
     // and a throw mid-rebuild rolls back the clear (no bricked graph). No second
     // connection is opened inside.
     return runGraphRebuildTransaction(hippoRoot, tenantId, (txDb) => rebuildGraphRows(txDb, hippoRoot, tenantId, loaded));
 }
-/**
- * The deterministic rebuild WRITES, run inside `runGraphRebuildTransaction`'s
- * transaction (`txDb` is its connection). Clears the tenant's graph then
- * re-derives entities + `supersedes` + `references` from the preloaded rows. All
- * DB access here is on `txDb` (or in-memory) — no other connection is opened.
- */
-function rebuildGraphRows(txDb, hippoRoot, tenantId, loaded) {
-    // Rebuild from scratch: the graph is derived, so clear then re-derive.
-    clearGraph(hippoRoot, tenantId, txDb);
-    const byType = {};
-    const truncated = [];
-    const allRows = [];
-    const entityIdByKey = new Map();
-    // The mirror memory per extracted key, null once forgotten/pruned (so a supersedes
-    // edge anchors to the successor's object when the mirror is gone but still passes the
-    // memory through when it lives).
-    const memoryIdByKey = new Map();
-    // Created entities ONLY (drives Pass 3 sources + targets), in stable insertion order.
-    const created = [];
-    // Pass 1: entities. Every ACTIVE/SUPERSEDED E2 row becomes an entity ANCHORED to its
-    // authoritative E2 object (source_object_type/id) - it survives a forgotten mirror
-    // (memory_id NULL). The mirror memory is passed through only when it still exists
-    // (it remains a recall pointer until forgotten/pruned).
+// Pass 1: entities. Every ACTIVE/SUPERSEDED object row becomes an entity ANCHORED to its
+// authoritative object (source_object_type/id) - it survives a forgotten mirror
+// (memory_id NULL). The mirror memory is passed through only when it still exists
+// (it remains a recall pointer until forgotten/pruned).
+function insertEntityRows(txDb, hippoRoot, tenantId, loaded) {
+    const pass = { byType: {}, truncated: [], allRows: [], entityIdByKey: new Map(), memoryIdByKey: new Map(), created: [] };
     for (const { entityType, rows, hitCap } of loaded) {
         if (hitCap)
-            truncated.push(entityType);
-        byType[entityType] = 0;
+            pass.truncated.push(entityType);
+        pass.byType[entityType] = 0;
         for (const row of rows) {
-            allRows.push(row);
-            // Normalise the label so a long/odd-but-valid E2 name can never throw in
-            // insertEntity and (because clearGraph already ran) brick the rebuild
-            // unrebuildably. E2 name fields (decisionText / policyName) are UNCAPPED at
-            // source, and insertEntity REJECTS (not truncates) both an over-cap name AND an
-            // empty one. So: TRIM FIRST (codex 2026-06-01: >512 leading-whitespace chars
-            // would otherwise slice to a whitespace-only string -> trimmed to '' ->
-            // 'name is required' throw), THEN cap to MAX_ENTITY_NAME_LEN; if the normalised
-            // label is empty (the E2 save APIs forbid this, but be defensive) skip the row
-            // rather than throw. This closes the entire name-brick class.
+            pass.allRows.push(row);
+            // Name fields are uncapped at source and insertEntity rejects an over-cap or empty name,
+            // which after clearGraph would brick the rebuild. Trim before capping so leading
+            // whitespace cannot slice to ''; skip a still-empty label rather than throw.
             const name = (row.name ?? '').trim().slice(0, MAX_ENTITY_NAME_LEN);
             if (name.length === 0)
                 continue;
@@ -184,33 +157,35 @@ function rebuildGraphRows(txDb, hippoRoot, tenantId, loaded) {
                 sourceObject,
             }, txDb);
             const k = keyOf(row.entityType, row.e2Id);
-            entityIdByKey.set(k, entity.id);
-            memoryIdByKey.set(k, row.memoryId);
-            created.push({ entityId: entity.id, entityType: row.entityType, memoryId: row.memoryId, sourceObject, name, searchText: row.searchText ?? '', superseded: row.supersededBy !== null });
-            byType[entityType] += 1;
+            pass.entityIdByKey.set(k, entity.id);
+            pass.memoryIdByKey.set(k, row.memoryId);
+            pass.created.push({ entityId: entity.id, entityType: row.entityType, memoryId: row.memoryId, sourceObject, name, searchText: row.searchText ?? '', superseded: row.supersededBy !== null });
+            pass.byType[entityType] += 1;
         }
     }
-    // Pass 2: `supersedes` relations. For X superseded by Y (Y is the successor), emit
-    // "Y supersedes X" - but only when BOTH X and Y were EXTRACTED (e.g. Y may be closed
-    // and absent). The emit guard is ENTITY presence (entityIdByKey), not memory presence:
-    // a forgotten successor mirror must still emit the edge. The relation is anchored to Y's
-    // authoritative E2 object; Y's mirror memory is passed only when it still lives.
+    return pass;
+}
+// "Y supersedes X" - but only when BOTH X and Y were EXTRACTED (e.g. Y may be closed
+// and absent). The emit guard is ENTITY presence (entityIdByKey), not memory presence:
+// a forgotten successor mirror must still emit the edge. The relation is anchored to Y's
+// authoritative object; Y's mirror memory is passed only when it still lives.
+function insertSupersedesRelations(txDb, hippoRoot, tenantId, pass) {
     let relations = 0;
     // Entity-id pairs already related by supersedes (unordered). Pass 3 skips a references
     // edge for such a pair: a version-extends-its-predecessor's-name containment (e.g.
     // "Adopt X (managed)" contains "Adopt X") is a name artifact, not a cross-reference,
     // and supersedes already captures their relationship.
     const supersededPairs = new Set();
-    for (const row of allRows) {
+    for (const row of pass.allRows) {
         if (row.supersededBy === null)
             continue;
         const xKey = keyOf(row.entityType, row.e2Id);
         const yKey = keyOf(row.entityType, row.supersededBy);
-        const fromId = entityIdByKey.get(yKey); // successor Y
-        const toId = entityIdByKey.get(xKey); // superseded X
+        const fromId = pass.entityIdByKey.get(yKey); // successor Y
+        const toId = pass.entityIdByKey.get(xKey); // superseded X
         if (fromId === undefined || toId === undefined)
             continue;
-        const yMemoryId = memoryIdByKey.get(yKey) ?? null; // successor's mirror, null if gone
+        const yMemoryId = pass.memoryIdByKey.get(yKey) ?? null; // successor's mirror, null if gone
         insertRelation(hippoRoot, tenantId, {
             fromEntityId: fromId,
             toEntityId: toId,
@@ -221,11 +196,26 @@ function rebuildGraphRows(txDb, hippoRoot, tenantId, loaded) {
         supersededPairs.add(pairKey(fromId, toId));
         relations += 1;
     }
+    return { relations, supersededPairs };
+}
+/**
+ * The deterministic rebuild WRITES, run inside `runGraphRebuildTransaction`'s
+ * transaction (`txDb` is its connection). Clears the tenant's graph then
+ * re-derives entities + `supersedes` + `references` from the preloaded rows. All
+ * DB access here is on `txDb` (or in-memory) — no other connection is opened.
+ */
+function rebuildGraphRows(txDb, hippoRoot, tenantId, loaded) {
+    // Rebuild from scratch: the graph is derived, so clear then re-derive.
+    clearGraph(hippoRoot, tenantId, txDb);
+    const pass = insertEntityRows(txDb, hippoRoot, tenantId, loaded);
+    const { byType, truncated, created } = pass;
+    const supersedes = insertSupersedesRelations(txDb, hippoRoot, tenantId, pass);
+    let relations = supersedes.relations;
     // Pass 3: cross-object `references` edges via conservative name matching. A source's
     // text containing a target entity's name -> "source references target". Sources +
-    // targets are CREATED entities only, each anchored to its E2 source object (so the
+    // targets are CREATED entities only, each anchored to its source object (so the
     // edge survives a forgotten source mirror).
-    const references = extractReferences(hippoRoot, tenantId, created, supersededPairs, truncated, txDb);
+    const references = extractReferences(hippoRoot, tenantId, created, supersedes.supersededPairs, truncated, txDb);
     relations += references;
     const entities = created.length;
     return { entities, relations, references, byType, truncated };
@@ -234,7 +224,7 @@ function rebuildGraphRows(txDb, hippoRoot, tenantId, loaded) {
  * Pass 3. Build a target-name index from the created entities (names within the length
  * bounds, ambiguous names dropped), scan each created entity's text once with one
  * combined word-boundary regex, and emit `references` edges (self-skipped, deduped,
- * per-source capped). Each edge is anchored to the source entity's E2 object (memoryId
+ * per-source capped). Each edge is anchored to the source entity's object (memoryId
  * passed through only when the mirror lives). Returns the number of references edges written.
  */
 function extractReferences(hippoRoot, tenantId, created, supersededPairs, truncated, txDb) {
@@ -244,7 +234,7 @@ function extractReferences(hippoRoot, tenantId, created, supersededPairs, trunca
     const ambiguous = new Set();
     for (const e of created) {
         // References are among ACTIVE entities only: a superseded (outdated) row is not a
-        // current cross-reference target (codex).
+        // current cross-reference target.
         if (e.superseded)
             continue;
         // Decisions are SOURCE-only: their name is decision prose, referenced by supersedes,
@@ -275,7 +265,7 @@ function extractReferences(hippoRoot, tenantId, created, supersededPairs, trunca
         truncated.push('references-targets');
     // LONGEST name first, then alphabetical: JS regex alternation is leftmost-first, so
     // ordering longer names before their prefixes makes the match longest-at-position
-    // (`postgres pro` wins over `postgres`; codex). Deterministic, so truncation is stable.
+    // (`postgres pro` wins over `postgres`). Deterministic, so truncation is stable.
     const targetNames = [...nameToId.keys()]
         .sort((a, b) => b.length - a.length || (a < b ? -1 : a > b ? 1 : 0))
         .slice(0, MAX_TARGET_NAMES);
@@ -284,7 +274,7 @@ function extractReferences(hippoRoot, tenantId, created, supersededPairs, trunca
     let references = 0;
     for (const src of created) {
         if (src.superseded)
-            continue; // superseded sources hold only stale references (codex)
+            continue; // superseded sources hold only stale references
         if (!src.searchText)
             continue;
         const targets = new Set();

package/dist/graph-recall.d.ts

@@ -1,4 +1,4 @@
-import type { ResultCost, SearchResult } from './search/types.js';
+import { type ResultCost, type SearchResult } from './search/types.js';
 /** Hard cap on `--hops` (a higher value just walks more of a finite graph; this bounds
  *  worst-case work and keeps the flag honest). */
 export declare const MAX_HOPS = 3;
@@ -21,7 +21,7 @@ export interface GraphExpandOpts {
      *  cmdRecall: a row is visible if valid_from <= asOf AND, when superseded, its successor
      *  was not yet valid at asOf). */
     asOf?: string;
-    /** Token budget for the augmented set (defaults to 4000, matching recall's default). */
+    /** Token budget for the augmented set (defaults to DEFAULT_RECALL_BUDGET, matching recall). */
     budget?: number;
     /** Budget cost per result; defaults to the memory text. */
     cost?: ResultCost;

package/dist/graph-recall.js

@@ -1,19 +1,18 @@
 /**
- * E3.2 multi-hop graph recall (docs/plans/2026-06-02-e3.2-multihop-recall.md).
+ * Multi-hop graph recall.
  *
- * READ-ONLY consumer of the E3 graph substrate (entities/relations built by E3.1,
- * guarded by E3.3). Given the lexical recall seeds, walk the relations graph up to N
+ * READ-ONLY consumer of the graph substrate (entities/relations built by graph-extract,
+ * guarded by the graph-on-consolidated triggers). Given the lexical recall seeds, walk the relations graph up to N
  * hops and surface the memories of reached entities that the lexical search did not
  * already return.
  *
  * Relation-type-AGNOSTIC: it walks whatever edges exist. Today the graph holds only
  * `supersedes` edges (so a 1-hop walk surfaces a supersession-linked predecessor/
- * successor a lexical search may miss); the moment E3.1 emits cross-object edges
+ * successor a lexical search may miss); the moment extraction emits cross-object edges
  * (owns/depends-on/blocked-by/references) the SAME traversal lights up cross-entity
  * multi-hop with zero rework here.
  *
- * Design points (the first two were forced by the verify-stage benchmark, the rest by
- * codex review — all root-cause, not patches):
+ * Design points:
  *  1. Graph-reached memories are loaded DIRECTLY by id (tenant-scoped PK fetch), NOT
  *     intersected with the recall handler's candidate set — that set is lexically
  *     prefiltered (loadSearchRows filters by query tokens), so intersecting would exclude
@@ -29,14 +28,15 @@
  *     nothing at realistic budgets.
  *  3. BOTH the local and global stores are expanded — a global seed's entities/relations
  *     live under the global root, so graph recall must traverse each seed in the store its
- *     graph lives in (codex review).
+ *     graph lives in.
  *  4. By-id loads are chunked at 500 (loadEntriesByIds caps at 500/call), so a high-fanout
- *     traversal (--hops 3 --max-neighbors 200 -> up to 600 ids) loses none (codex review).
+ *     traversal (--hops 3 --max-neighbors 200 -> up to 600 ids) loses none.
  *
- * No graph writes (only SELECTs via graph.ts read helpers + store reads), so the E3.3
+ * No graph writes (only SELECTs via graph.ts read helpers + store reads), so the
  * check-graph-writes lint permits this module living outside graph.ts.
  */
 import { loadEntriesByIds } from './store/entry-reads.js';
+import { DEFAULT_RECALL_BUDGET } from './search/types.js';
 import { estimateTokens } from './token-ledger.js';
 import { compareEntryIdentity } from './compare.js';
 import { loadEntitiesByMemoryId, loadEntitiesByIds, loadNeighborRelations } from './graph/read.js';
@@ -61,15 +61,9 @@ function loadByIdsChunked(root, tenantId, ids) {
     }
     return out;
 }
-/** Traverse one store's graph from its seeds into `hitsByOrigin`. Pure reads; mutates `seenMemoryIds`
- *  and `seenContent` so a memory, or a share/promote copy of it, surfaces at most once across stores. */
-function produceHitsForRoot(root, baseResults, baseScoreByMemId, seenMemoryIds, seenContent, hitsByOrigin, opts) {
-    const { hops, maxNeighbors, tenantId, includeSuperseded, asOfDate, recallScope } = opts;
-    // Seeds = graph entities (in THIS store) whose source memory is a base result.
-    const seedEntities = loadEntitiesByMemoryId(root, tenantId, baseResults.map((r) => r.entry.id));
-    if (seedEntities.length === 0)
-        return;
-    // BFS, both directions, up to `hops`. `visited` prevents re-expansion (cycle-safe).
+/** BFS, both directions, up to `hops`: each reached entity's via, and the base memory it descends from. */
+function walkRelations(root, tenantId, seedEntities, hops, maxNeighbors) {
+    // `visited` prevents re-expansion (cycle-safe).
     // `originMemByEntityId` propagates the base-result memory id each reached node descends
     // from (for adjacency placement + score inheritance).
     const visitedEntityIds = new Set(seedEntities.map((e) => e.id));
@@ -118,6 +112,43 @@ function produceHitsForRoot(root, baseResults, baseScoreByMemId, seenMemoryIds,
         }
         frontier = nextFrontier;
     }
+    return { reached, originMemByEntityId };
+}
+/** The recall hard filters (as-of, superseded, scope) re-applied to a directly loaded graph-reached row. */
+function passesRecallFilters(mem, via, successorValidFrom, opts) {
+    const { includeSuperseded, asOfDate, recallScope } = opts;
+    // A node reached as the `to` endpoint of a `supersedes` edge IS the superseded
+    // (older) version — the graph is the authoritative signal (the memory mirror's
+    // `superseded_by` is NOT set by `hippo decide`, only the decisions table is). By
+    // default recall shows current truth, so drop it unless --include-superseded; the
+    // `from` endpoint (the newer successor) is always kept.
+    const isSupersededEndpoint = via.relType === 'supersedes' && via.direction === 'to';
+    if (asOfDate) {
+        if (new Date(mem.valid_from) > asOfDate)
+            return false; // not yet valid at asOf
+        if (mem.superseded_by) {
+            const succVf = successorValidFrom.get(mem.superseded_by);
+            // Visible only while its successor was NOT yet valid at asOf (matches cmdRecall).
+            if (succVf && new Date(succVf) <= asOfDate)
+                return false;
+        }
+    }
+    else if (!includeSuperseded && (mem.superseded_by || isSupersededEndpoint)) {
+        return false; // default recall drops superseded
+    }
+    return recallScope.additive
+        ? passesCliRecallScopeFilter(mem.scope ?? null, recallScope.requested)
+        : passesScopeFilterForRecall(mem.scope ?? null, recallScope.requested);
+}
+/** Traverse one store's graph from its seeds into `hitsByOrigin`. Pure reads; mutates `seenMemoryIds`
+ *  and `seenContent` so a memory, or a share/promote copy of it, surfaces at most once across stores. */
+function produceHitsForRoot(root, baseResults, baseScoreByMemId, seenMemoryIds, seenContent, hitsByOrigin, opts) {
+    const { hops, maxNeighbors, tenantId, asOfDate } = opts;
+    // Seeds = graph entities (in THIS store) whose source memory is a base result.
+    const seedEntities = loadEntitiesByMemoryId(root, tenantId, baseResults.map((r) => r.entry.id));
+    if (seedEntities.length === 0)
+        return;
+    const { reached, originMemByEntityId } = walkRelations(root, tenantId, seedEntities, hops, maxNeighbors);
     if (reached.size === 0)
         return;
     // Reached entities -> source memory ids -> load DIRECTLY by id (chunked), not lexical.
@@ -147,29 +178,7 @@ function produceHitsForRoot(root, baseResults, baseScoreByMemId, seenMemoryIds,
         if (seenContent.has(mem.content))
             continue; // share/promote copy: same text, another id
         const via = reached.get(ent.id);
-        // A node reached as the `to` endpoint of a `supersedes` edge IS the superseded
-        // (older) version — the graph is the authoritative signal (the memory mirror's
-        // `superseded_by` is NOT set by `hippo decide`, only the decisions table is). By
-        // default recall shows current truth, so drop it unless --include-superseded; the
-        // `from` endpoint (the newer successor) is always kept.
-        const isSupersededEndpoint = via.relType === 'supersedes' && via.direction === 'to';
-        if (asOfDate) {
-            if (new Date(mem.valid_from) > asOfDate)
-                continue; // not yet valid at asOf
-            if (mem.superseded_by) {
-                const succVf = successorValidFrom.get(mem.superseded_by);
-                // Visible only while its successor was NOT yet valid at asOf (matches cmdRecall).
-                if (succVf && new Date(succVf) <= asOfDate)
-                    continue;
-            }
-        }
-        else if (!includeSuperseded && (mem.superseded_by || isSupersededEndpoint)) {
-            continue; // default recall drops superseded
-        }
-        const scopeOk = recallScope.additive
-            ? passesCliRecallScopeFilter(mem.scope ?? null, recallScope.requested)
-            : passesScopeFilterForRecall(mem.scope ?? null, recallScope.requested);
-        if (!scopeOk)
+        if (!passesRecallFilters(mem, via, successorValidFrom, opts))
             continue;
         const origin = originMemByEntityId.get(ent.id) ?? baseResults[0].entry.id;
         const originScore = baseScoreByMemId.get(origin) ?? baseResults[baseResults.length - 1].score;
@@ -202,7 +211,7 @@ export function graphExpandRecall(baseResults, opts) {
     if (hops <= 0 || baseResults.length === 0)
         return baseResults;
     const maxNeighbors = opts.maxNeighbors ?? DEFAULT_MAX_NEIGHBORS;
-    const budget = opts.budget ?? 4000;
+    const budget = opts.budget ?? DEFAULT_RECALL_BUDGET;
     const includeSuperseded = opts.includeSuperseded ?? false;
     const asOfDate = opts.asOf ? new Date(opts.asOf) : null;
     const minResults = opts.minResults ?? 1;
@@ -222,8 +231,7 @@ export function graphExpandRecall(baseResults, opts) {
         return baseResults;
     // Closer hops first within each origin group, then by inherited score.
     // Hops asc and score desc are both true primary keys (unchanged);
-    // compareEntryIdentity is only the TAIL for a same-hop, same-score tie
-    // (T2, deterministic tie keys).
+    // compareEntryIdentity is only the TAIL for a same-hop, same-score tie.
     for (const hits of hitsByOrigin.values()) {
         hits.sort((a, b) => {
             const byHops = a.graphVia.hops - b.graphVia.hops;
@@ -243,16 +251,14 @@ export function graphExpandRecall(baseResults, opts) {
     // (NOTE: at a tight budget a new graph hit can displace a weakly-scored base result;
     // aggregate recall stays >= baseline, the displaced item is the lowest-value one.)
     // Protect the top --min-results base rows from eviction (graph expansion must not
-    // violate the recall min-results floor; codex P2). They are kept regardless of budget;
+    // violate the recall min-results floor). They are kept regardless of budget;
     // baseResults is score-ordered, so slice(0, N) is the top N.
     const protectedCount = Math.min(Math.max(minResults, 1), baseResults.length);
     const keep = new Set(baseResults.slice(0, protectedCount));
     const price = opts.cost ?? ((r) => r.tokens);
     let usedTokens = [...keep].reduce((s, r) => s + price(r), 0);
-    // T2 note: PLAIN stable score sort on purpose -- both input lists are
-    // deterministically ordered by this point, stability inherits that, and a
-    // base-vs-graph-hit tie keeps the BASE result first (the concat order),
-    // preserving pre-T2 semantics.
+    // PLAIN stable score sort on purpose: both input lists are already deterministically
+    // ordered, and a base-vs-graph-hit tie keeps the BASE result first (the concat order).
     for (const r of [...baseResults.slice(protectedCount), ...allHits].sort((a, b) => b.score - a.score)) {
         const tokens = price(r);
         if (usedTokens + tokens > budget)

package/dist/graph-stream.d.ts

@@ -1,9 +1,8 @@
 /**
- * L1 — graph-retrieval ranked-list stream for RRF fusion
- * (docs/plans/2026-06-02-l1-graph-rrf-stream.md).
+ * Graph-retrieval ranked-list stream for RRF fusion.
  *
- * READ-ONLY consumer of the E3 graph substrate (entities/relations built by E3.1,
- * guarded by E3.3). Produces a ranked list of `entries[]` indices ordered by graph
+ * READ-ONLY consumer of the entity/relation graph. Produces a ranked list of
+ * `entries[]` indices ordered by graph
  * proximity to the strong lexical seeds, for use as a 3rd fusion input to `rrfFuse`
  * beside BM25 + dense (src/search.ts hybridSearch, scoring:'rrf').
  *
@@ -13,10 +12,10 @@
  * themselves are never scored (they already rank via BM25/dense; scoring them would
  * double-count and dilute the orthogonal graph signal).
  *
- * Reuses the E3.2 BFS traversal shape from graph-recall.ts (loadEntitiesByMemoryId
+ * Reuses the BFS traversal shape from graph-recall.ts (loadEntitiesByMemoryId
  * seeds -> loadNeighborRelations BFS both directions, per-hop fanout cap, visited set
  * -> loadEntitiesByIds to resolve reached -> memoryId). Expands across the local AND
- * global stores. Pure reads (SELECTs only via graph.ts helpers), so the E3.3
+ * global stores. Pure reads (SELECTs only via graph.ts helpers), so the
  * check-graph-writes lint permits this module living outside graph.ts.
  *
  * The graph stream's score scale (1/lexRank seed strength x decay^hops) only sets the

package/dist/graph-stream.js

@@ -33,39 +33,40 @@ export function selectGraphSeeds(bm25Ranked, cosineRanked, seedCount) {
         .slice(0, seedCount)
         .map(([index, best]) => ({ index, strength: 1 / (best + 1) }));
 }
-/**
- * Accumulate per-entryIndex graph-proximity scores from ONE store's graph into
- * `graphScore`. Pure reads. `seeds` are the lexical seeds (index + strength); only the
- * seeds whose entities live in THIS store are expanded. The origin seed strength is
- * carried UNCHANGED along each BFS path; the per-hop decay is applied as decay^depth so
- * a neighbour's score = originSeedStrength x decay^(graph distance).
- */
-function accumulateForRoot(root, seeds, entries, memIdToIndex, graphScore, hops, decay, maxNeighbors, tenantId) {
-    if (seeds.length === 0)
-        return;
-    // The strongest seed strength per source memory id (a memId could appear once, but
-    // guard against dup indices mapping to the same memId).
-    const strengthByMemId = new Map();
-    for (const s of seeds) {
-        const memId = entries[s.index].id;
-        strengthByMemId.set(memId, Math.max(strengthByMemId.get(memId) ?? 0, s.strength));
-    }
-    const seedEntities = loadEntitiesByMemoryId(root, tenantId, [...strengthByMemId.keys()]);
-    if (seedEntities.length === 0)
-        return;
-    // entityId -> origin seed strength (carried unchanged along the path). A seed entity is
-    // loaded by memory id, so its memoryId is non-null here; the guard keeps the widened
-    // (string | null) type honest (a null-memory entity is not a lexical seed).
-    const originStrength = new Map();
-    for (const e of seedEntities) {
-        if (e.memoryId === null)
+// Pass 1: accumulate the STRONGEST reaching-seed strength per new neighbour across ALL
+// relations at this depth BEFORE committing any to `visited`. Marking a node
+// visited mid-loop would lock it to whichever relation SQLite returned first, so a later
+// edge from a STRONGER lexical seed would be dropped and the neighbour mis-scored. A node
+// already in `visited` was committed at an earlier (shorter) depth and keeps that score.
+function bestStrengthAtDepth(rels, frontierSet, visited, frontierStrength, originStrength) {
+    const bestStrengthThisDepth = new Map();
+    for (const rel of rels) {
+        const fromIn = frontierSet.has(rel.fromEntityId);
+        const toIn = frontierSet.has(rel.toEntityId);
+        let neighborId;
+        let reacherId;
+        if (fromIn && !toIn) {
+            neighborId = rel.toEntityId;
+            reacherId = rel.fromEntityId;
+        }
+        else if (toIn && !fromIn) {
+            neighborId = rel.fromEntityId;
+            reacherId = rel.toEntityId;
+        }
+        else
             continue;
-        const st = strengthByMemId.get(e.memoryId) ?? 0;
-        originStrength.set(e.id, Math.max(originStrength.get(e.id) ?? 0, st));
+        if (visited.has(neighborId))
+            continue;
+        const seedStrength = frontierStrength.get(reacherId) ?? originStrength.get(reacherId) ?? 0;
+        bestStrengthThisDepth.set(neighborId, Math.max(bestStrengthThisDepth.get(neighborId) ?? 0, seedStrength));
     }
-    const visited = new Set(seedEntities.map((e) => e.id)); // seeds never re-reached
+    return bestStrengthThisDepth;
+}
+/** BFS from the seed entities: entityId -> best originSeedStrength x decay^depth over every reached entity. */
+function reachedEntityScores(root, tenantId, seedIds, originStrength, hops, decay, maxNeighbors) {
+    const visited = new Set(seedIds); // seeds never re-reached
     const reachedScore = new Map(); // entityId -> best score
-    let frontier = seedEntities.map((e) => e.id);
+    let frontier = seedIds;
     let frontierStrength = new Map(originStrength); // entityId -> seed strength
     for (let depth = 1; depth <= hops && frontier.length > 0; depth++) {
         const frontierSet = new Set(frontier);
@@ -73,32 +74,7 @@ function accumulateForRoot(root, seeds, entries, memIdToIndex, graphScore, hops,
             limit: Math.max(maxNeighbors, maxNeighbors * frontier.length),
         });
         const hopFactor = Math.pow(decay, depth);
-        // Pass 1: accumulate the STRONGEST reaching-seed strength per new neighbour across ALL
-        // relations at this depth BEFORE committing any to `visited` (codex P2). Marking a node
-        // visited mid-loop would lock it to whichever relation SQLite returned first, so a later
-        // edge from a STRONGER lexical seed would be dropped and the neighbour mis-scored. A node
-        // already in `visited` was committed at an earlier (shorter) depth and keeps that score.
-        const bestStrengthThisDepth = new Map();
-        for (const rel of rels) {
-            const fromIn = frontierSet.has(rel.fromEntityId);
-            const toIn = frontierSet.has(rel.toEntityId);
-            let neighborId;
-            let reacherId;
-            if (fromIn && !toIn) {
-                neighborId = rel.toEntityId;
-                reacherId = rel.fromEntityId;
-            }
-            else if (toIn && !fromIn) {
-                neighborId = rel.fromEntityId;
-                reacherId = rel.toEntityId;
-            }
-            else
-                continue;
-            if (visited.has(neighborId))
-                continue;
-            const seedStrength = frontierStrength.get(reacherId) ?? originStrength.get(reacherId) ?? 0;
-            bestStrengthThisDepth.set(neighborId, Math.max(bestStrengthThisDepth.get(neighborId) ?? 0, seedStrength));
-        }
+        const bestStrengthThisDepth = bestStrengthAtDepth(rels, frontierSet, visited, frontierStrength, originStrength);
         // Pass 2: commit strongest-first (then id asc — deterministic), so the per-hop fanout cap
         // keeps the highest-scoring neighbours rather than whichever SQLite happened to return.
         const nextFrontier = [];
@@ -119,6 +95,39 @@ function accumulateForRoot(root, seeds, entries, memIdToIndex, graphScore, hops,
         frontier = nextFrontier;
         frontierStrength = nextStrength;
     }
+    return reachedScore;
+}
+/**
+ * Accumulate per-entryIndex graph-proximity scores from ONE store's graph into
+ * `graphScore`. Pure reads. `seeds` are the lexical seeds (index + strength); only the
+ * seeds whose entities live in THIS store are expanded. The origin seed strength is
+ * carried UNCHANGED along each BFS path; the per-hop decay is applied as decay^depth so
+ * a neighbour's score = originSeedStrength x decay^(graph distance).
+ */
+function accumulateForRoot(root, seeds, entries, memIdToIndex, graphScore, hops, decay, maxNeighbors, tenantId) {
+    if (seeds.length === 0)
+        return;
+    // The strongest seed strength per source memory id (a memId could appear once, but
+    // guard against dup indices mapping to the same memId).
+    const strengthByMemId = new Map();
+    for (const s of seeds) {
+        const memId = entries[s.index].id;
+        strengthByMemId.set(memId, Math.max(strengthByMemId.get(memId) ?? 0, s.strength));
+    }
+    const seedEntities = loadEntitiesByMemoryId(root, tenantId, [...strengthByMemId.keys()]);
+    if (seedEntities.length === 0)
+        return;
+    // entityId -> origin seed strength (carried unchanged along the path). A seed entity is
+    // loaded by memory id, so its memoryId is non-null here; the guard keeps the widened
+    // (string | null) type honest (a null-memory entity is not a lexical seed).
+    const originStrength = new Map();
+    for (const e of seedEntities) {
+        if (e.memoryId === null)
+            continue;
+        const st = strengthByMemId.get(e.memoryId) ?? 0;
+        originStrength.set(e.id, Math.max(originStrength.get(e.id) ?? 0, st));
+    }
+    const reachedScore = reachedEntityScores(root, tenantId, seedEntities.map((e) => e.id), originStrength, hops, decay, maxNeighbors);
     if (reachedScore.size === 0)
         return;
     // Reached entity ids -> source memory ids -> in-pool entry indices.
@@ -159,7 +168,7 @@ export function graphRankStream(entries, seeds, opts) {
     for (const root of roots) {
         accumulateForRoot(root, seeds, entries, memIdToIndex, graphScore, hops, decay, maxNeighbors, opts.tenantId);
     }
-    // Seed-exclusion guard (plan-eng-critic MED): graphScore is keyed by entryIndex
+    // Seed-exclusion guard: graphScore is keyed by entryIndex
     // GLOBALLY across roots, but each root's BFS visited-set is per-root, so a memory that
     // is a seed in one store could be reached as a neighbour in the other store and pick up
     // a score via max(). Drop every seed index so the "seeds are never scored by the graph