hippo-memory 1.69.0 → 1.71.0

package/dist/{graph-recall.js → graph/recall.js}

@@ -1,46 +1,12 @@
-/**
- * Multi-hop graph recall.
- *
- * 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 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:
- *  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
- *     exactly the lexically-orthogonal neighbours graph recall exists to surface. We
- *     re-apply the recall HARD filters to the directly-loaded rows: the FULL bi-temporal
- *     as-of rule (valid_from <= asOf AND, for a superseded row, successor.valid_from >
- *     asOf — same as cmdRecall) and the default superseded-drop. SCOPE is intentionally
- *     NOT re-applied: the CLI caller (cmdRecall) does not hard-filter scope either (it
- *     only soft-boosts it). Rows are tenant-scoped + archived-excluded (loadEntriesByIds).
- *  2. A graph hit inherits its origin seed's relevance (minus a per-hop discount) and is
- *     placed adjacent to that seed; budget selection is by score so a high-value hit wins
- *     a token slot over a noise distractor. Dead-last appending made the feature do
- *     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.
- *  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.
- *
- * 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';
-import { passesCliRecallScopeFilter, passesScopeFilterForRecall } from './recall-scope.js';
+/** Multi-hop graph recall: a READ-ONLY walk of the relations graph from the lexical seeds, surfacing reached entities' memories the lexical search missed.
+ *  Reached rows load by id (not intersected with the lexically prefiltered candidates), then the recall hard filters are re-applied.
+ *  Hits inherit their seed's score minus a per-hop discount; both stores are expanded; no writes, so check-graph-writes permits it outside graph.ts. */
+import { loadEntriesByIds } from '../store/entry-reads.js';
+import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
+import { estimateTokens } from '../util/token-text.js';
+import { compareEntryIdentity, compareScoresDesc } from '../core/compare.js';
+import { loadEntitiesByMemoryId, loadEntitiesByIds, loadNeighborRelations } from '../store/graph-reads.js';
+import { passesCliRecallScopeFilter, passesScopeFilterForRecall } from '../store/recall-scope.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 const MAX_HOPS = 3;
@@ -63,14 +29,10 @@ function loadByIdsChunked(root, tenantId, ids) {
 }
 /** 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).
+    // `visited` makes expansion cycle-safe; `originMemByEntityId` carries each node's base-result memory id for adjacency placement and score inheritance.
     const visitedEntityIds = new Set(seedEntities.map((e) => e.id));
     const reached = new Map();
-    // A seed/reached entity whose mirror was forgotten/pruned has a null memoryId; the map
-    // tolerates null so traversal still propagates origin, and the null is dropped before
-    // any memory load below (a mirror-less node has no memory to surface).
+    // A seed/reached entity whose mirror was forgotten or pruned has a null memoryId; traversal still propagates origin and the null is dropped before any load.
     const originMemByEntityId = new Map();
     for (const se of seedEntities)
         originMemByEntityId.set(se.id, se.memoryId);
@@ -117,11 +79,8 @@ function walkRelations(root, tenantId, seedEntities, hops, maxNeighbors) {
 /** 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.
+    // The `to` endpoint of a `supersedes` edge IS the superseded version; the graph is authoritative because `hippo decide` does not set `superseded_by`.
+    // Drop it unless --include-superseded; the newer `from` endpoint is always kept.
     const isSupersededEndpoint = via.relType === 'supersedes' && via.direction === 'to';
     if (asOfDate) {
         if (new Date(mem.valid_from) > asOfDate)
@@ -142,7 +101,8 @@ function passesRecallFilters(mem, via, successorValidFrom, opts) {
 }
 /** 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) {
+function produceHitsForRoot(root, baseResults, accumulators, opts) {
+    const { baseScoreByMemId, seenMemoryIds, seenContent, hitsByOrigin } = accumulators;
     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));
@@ -151,22 +111,9 @@ function produceHitsForRoot(root, baseResults, baseScoreByMemId, seenMemoryIds,
     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.
-    // A mirror-less reached entity (memoryId === null) has no memory to load: drop its null
-    // id BEFORE it reaches loadByIdsChunked / the Set<string> (it cannot be recall-surfaced;
-    // it stays in entities/relations for graph extract / visualization).
     const reachedEntities = loadEntitiesByIds(root, tenantId, [...reached.keys()]);
-    const needLoad = [...new Set(reachedEntities
-            .map((e) => e.memoryId)
-            .filter((id) => id !== null && !seenMemoryIds.has(id)))];
-    const loadedById = new Map(loadByIdsChunked(root, tenantId, needLoad).map((m) => [m.id, m]));
-    // For the bi-temporal as-of rule on a superseded reached row we need its successor's
-    // valid_from. Batch-load the successors referenced by the loaded rows.
-    let successorValidFrom = new Map();
-    if (asOfDate) {
-        const succIds = [...new Set([...loadedById.values()].map((m) => m.superseded_by).filter((id) => !!id))];
-        successorValidFrom = new Map(loadByIdsChunked(root, tenantId, succIds).map((m) => [m.id, m.valid_from]));
-    }
+    const loadedById = loadReachedMemories(root, tenantId, reachedEntities, seenMemoryIds);
+    const successorValidFrom = loadSuccessorValidFrom(root, tenantId, loadedById, asOfDate);
     for (const ent of reachedEntities) {
         if (ent.memoryId === null)
             continue; // mirror-less node: not recall-surfaced
@@ -184,37 +131,46 @@ function produceHitsForRoot(root, baseResults, baseScoreByMemId, seenMemoryIds,
         const originScore = baseScoreByMemId.get(origin) ?? baseResults[baseResults.length - 1].score;
         seenMemoryIds.add(mem.id);
         seenContent.add(mem.content);
-        const hit = {
-            entry: mem,
-            score: originScore * (1 - HOP_DISCOUNT * via.hops),
-            bm25: 0, cosine: 0,
-            tokens: estimateTokens(mem.content),
-            graphVia: via,
-        };
+        const hit = buildGraphHit(mem, via, originScore);
         if (!hitsByOrigin.has(origin))
             hitsByOrigin.set(origin, []);
         hitsByOrigin.get(origin).push(hit);
     }
 }
-/**
- * Augment `baseResults` with memories reached by walking the graph `hops` edges out from
- * the seed results' entities (across the local AND global stores). Each graph hit is
- * inserted directly after the base result it descends from, scored just below that seed;
- * the base list's own order is preserved. Token-budget-bounded; deduped against the base
- * set and across stores.
- *
- * No-op (returns `baseResults` unchanged) when `hops <= 0`, there are no base results, the
- * graph is empty, no seed maps to an entity, or nothing new survives the filters/budget.
- */
+function buildGraphHit(mem, via, originScore) {
+    return {
+        entry: mem,
+        score: originScore * (1 - HOP_DISCOUNT * via.hops),
+        bm25: 0, cosine: 0,
+        tokens: estimateTokens(mem.content),
+        graphVia: via,
+    };
+}
+// Reached entities -> source memory ids -> load by id (chunked). A mirror-less entity (memoryId === null) has no memory to surface,
+// so drop its null id before it reaches loadByIdsChunked.
+function loadReachedMemories(root, tenantId, reachedEntities, seenMemoryIds) {
+    const needLoad = [...new Set(reachedEntities
+            .map((e) => e.memoryId)
+            .filter((id) => id !== null && !seenMemoryIds.has(id)))];
+    return new Map(loadByIdsChunked(root, tenantId, needLoad).map((m) => [m.id, m]));
+}
+// For the bi-temporal as-of rule on a superseded reached row we need its successor's
+// valid_from. Batch-load the successors referenced by the loaded rows.
+function loadSuccessorValidFrom(root, tenantId, loadedById, asOfDate) {
+    if (!asOfDate)
+        return new Map();
+    const succIds = [...new Set([...loadedById.values()].map((m) => m.superseded_by).filter((id) => !!id))];
+    return new Map(loadByIdsChunked(root, tenantId, succIds).map((m) => [m.id, m.valid_from]));
+}
+/** Augment `baseResults` with memories reached by walking `hops` graph edges from the seeds across local AND global stores, each placed after its seed.
+ *  Returns `baseResults` unchanged when `hops <= 0`, there are no base results, or nothing new survives the filters and the token budget. */
 export function graphExpandRecall(baseResults, opts) {
     const { hops, hippoRoot, globalRoot, tenantId } = opts;
     if (hops <= 0 || baseResults.length === 0)
         return baseResults;
     const maxNeighbors = opts.maxNeighbors ?? DEFAULT_MAX_NEIGHBORS;
-    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;
     const recallScope = opts.recallScope ?? {};
     const baseScoreByMemId = new Map(baseResults.map((r) => [r.entry.id, r.score]));
     const seenMemoryIds = new Set(baseResults.map((r) => r.entry.id));
@@ -223,49 +179,50 @@ export function graphExpandRecall(baseResults, opts) {
     // Expand against each distinct store the seeds may live in (local + global).
     const roots = globalRoot && globalRoot !== hippoRoot ? [hippoRoot, globalRoot] : [hippoRoot];
     for (const root of roots) {
-        produceHitsForRoot(root, baseResults, baseScoreByMemId, seenMemoryIds, seenContent, hitsByOrigin, {
+        produceHitsForRoot(root, baseResults, { baseScoreByMemId, seenMemoryIds, seenContent, hitsByOrigin }, {
             hops, maxNeighbors, tenantId, includeSuperseded, asOfDate, recallScope,
         });
     }
     if (hitsByOrigin.size === 0)
         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.
+    sortHitsWithinOrigin(hitsByOrigin);
+    const allHits = [...hitsByOrigin.values()].flat();
+    const keep = selectWithinBudget(baseResults, allHits, opts);
+    return mergeKeptHits(baseResults, hitsByOrigin, keep);
+}
+function sortHitsWithinOrigin(hitsByOrigin) {
+    // Closer hops first within each origin group, then by inherited score; compareEntryIdentity only breaks same-hop, same-score ties.
     for (const hits of hitsByOrigin.values()) {
         hits.sort((a, b) => {
             const byHops = a.graphVia.hops - b.graphVia.hops;
             if (byHops !== 0)
                 return byHops;
-            const byScore = b.score - a.score;
+            const byScore = compareScoresDesc(a.score, b.score);
             return byScore !== 0 ? byScore : compareEntryIdentity(a.entry, b.entry);
         });
     }
-    const allHits = [...hitsByOrigin.values()].flat();
-    // Budget SELECTION by score (not by position): a high-value graph hit (it inherits its
-    // origin seed's relevance) must be able to win a token slot over a low-score lexical
-    // distractor — otherwise a tight --budget keeps the noise and drops the memory --hops
-    // surfaced. The greedy pack uses `continue` (not `break`), so a hit's origin seed is
-    // NOT guaranteed kept just because the hit is; the DISPLAY loop guards that (a hit is
-    // emitted ONLY under a kept seed, never orphaned). At least one result is always kept.
-    // (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). They are kept regardless of budget;
-    // baseResults is score-ordered, so slice(0, N) is the top N.
+}
+function selectWithinBudget(baseResults, allHits, opts) {
+    const budget = opts.budget ?? DEFAULT_RECALL_BUDGET;
+    const minResults = opts.minResults ?? 1;
+    // Budget selection is by score, not position, so a high-value graph hit can beat a low-score lexical distractor; the greedy pack uses `continue`,
+    // so the DISPLAY loop emits a hit only under a kept seed. The top --min-results base rows are never evicted; at least one result is kept.
     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);
     // 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)) {
+    for (const r of [...baseResults.slice(protectedCount), ...allHits].sort((a, b) => compareScoresDesc(a.score, b.score))) {
         const tokens = price(r);
         if (usedTokens + tokens > budget)
             continue;
         usedTokens += tokens;
         keep.add(r);
     }
+    return keep;
+}
+function mergeKeptHits(baseResults, hitsByOrigin, keep) {
     // DISPLAY order: base order preserved (it may be MMR-diversified); each kept new hit
     // placed directly after the seed it descends from. Hits emit ONLY under a kept seed.
     const merged = [];
@@ -283,4 +240,4 @@ export function graphExpandRecall(baseResults, opts) {
     }
     return emittedHit ? merged : baseResults; // nothing new survived budget -> original base
 }
-//# sourceMappingURL=graph-recall.js.map
+//# sourceMappingURL=recall.js.map

package/dist/graph/stream.d.ts

@@ -0,0 +1,38 @@
+/** Graph-retrieval ranked-list stream for RRF fusion: READ-ONLY, ranks `entries[]` indices by graph proximity to the strong lexical seeds.
+ *  Unlike graph recall it only re-ranks in-pool, graph-reached, non-seed entries; scoring seeds would double-count BM25/dense.
+ *  The score scale only sets the order inside this stream (RRF re-ranks by 1/(k + graphRank)), so do not tune it for a fused-score effect. */
+import type { MemoryEntry } from '../core/memory.js';
+/** Default hops expanded from each seed (MVP; hard cap MAX_HOPS=3 reused from graph recall). */
+export declare const DEFAULT_GRAPH_HOPS = 2;
+/** Default per-hop multiplicative decay applied to the seed strength. */
+export declare const DEFAULT_GRAPH_DECAY = 0.5;
+/** Default number of top lexical seeds expanded from. */
+export declare const DEFAULT_GRAPH_SEED_COUNT = 10;
+/** Recommended RRF weight for the graph stream — a CLI-only convenience default. The
+ *  library `graphStream.weight` option stays REQUIRED (opt-in is explicit). */
+export declare const DEFAULT_GRAPH_STREAM_WEIGHT = 0.5;
+/** A lexical seed to expand the graph from: a candidate index + its lexical strength. */
+export interface GraphSeed {
+    /** Index into the caller's `entries[]`. */
+    index: number;
+    /** Lexical strength (1/lexRank); higher = stronger seed. Propagated x decay^hops. */
+    strength: number;
+}
+export interface GraphStreamOpts {
+    hippoRoot: string;
+    tenantId: string;
+    /** The global store root, when distinct + initialized (where global seeds' graph lives). */
+    globalRoot?: string;
+    /** Hops to expand from each seed. Clamped to [1, MAX_HOPS]. Default DEFAULT_GRAPH_HOPS. */
+    hops?: number;
+    /** Per-hop multiplicative decay on the seed strength. Default DEFAULT_GRAPH_DECAY. */
+    decay?: number;
+    /** Per-hop fanout cap. Default DEFAULT_MAX_NEIGHBORS. */
+    maxNeighbors?: number;
+}
+/** Pick the top `seedCount` candidates by best lexical rank (lowest position across BM25 and dense), strength = 1/(bestRank + 1). Pure. */
+export declare function selectGraphSeeds(bm25Ranked: ReadonlyArray<number>, cosineRanked: ReadonlyArray<number>, seedCount: number): GraphSeed[];
+/** Produce the graph-retrieval ranked list: `entries[]` indices by graph proximity (desc) to the lexical `seeds`; absent indices fall to rrfFuse absentRank.
+ *  Returns `[]` when there are no seeds/entries, the graph is empty, or nothing reached is in-pool, so the caller skips the 3rd fusion list. */
+export declare function graphRankStream(entries: ReadonlyArray<MemoryEntry>, seeds: ReadonlyArray<GraphSeed>, opts: GraphStreamOpts): number[];
+//# sourceMappingURL=stream.d.ts.map

package/dist/{graph-stream.js → graph/stream.js}

@@ -1,6 +1,6 @@
-import { loadEntitiesByMemoryId, loadEntitiesByIds, loadNeighborRelations } from './graph/read.js';
-import { MAX_HOPS, DEFAULT_MAX_NEIGHBORS } from './graph-recall.js';
-/** Default hops expanded from each seed (MVP; hard cap MAX_HOPS=3 reused from graph-recall). */
+import { loadEntitiesByMemoryId, loadEntitiesByIds, loadNeighborRelations } from '../store/graph-reads.js';
+import { MAX_HOPS, DEFAULT_MAX_NEIGHBORS } from './recall.js';
+/** Default hops expanded from each seed (MVP; hard cap MAX_HOPS=3 reused from graph recall). */
 export const DEFAULT_GRAPH_HOPS = 2;
 /** Default per-hop multiplicative decay applied to the seed strength. */
 export const DEFAULT_GRAPH_DECAY = 0.5;
@@ -9,11 +9,7 @@ export const DEFAULT_GRAPH_SEED_COUNT = 10;
 /** Recommended RRF weight for the graph stream — a CLI-only convenience default. The
  *  library `graphStream.weight` option stays REQUIRED (opt-in is explicit). */
 export const DEFAULT_GRAPH_STREAM_WEIGHT = 0.5;
-/**
- * Pick the top `seedCount` candidates by best lexical rank (lowest position across the
- * BM25 and dense ranked lists), with strength = 1/(bestRank + 1). Pure; exported for
- * direct unit testing. A candidate present in either ranked list is eligible.
- */
+/** Pick the top `seedCount` candidates by best lexical rank (lowest position across BM25 and dense), strength = 1/(bestRank + 1). Pure. */
 export function selectGraphSeeds(bm25Ranked, cosineRanked, seedCount) {
     if (seedCount <= 0)
         return [];
@@ -33,11 +29,8 @@ export function selectGraphSeeds(bm25Ranked, cosineRanked, seedCount) {
         .slice(0, seedCount)
         .map(([index, best]) => ({ index, strength: 1 / (best + 1) }));
 }
-// 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.
+// Pass 1: take the STRONGEST reaching-seed strength per new neighbour across ALL relations at this depth before committing any to `visited`;
+// marking mid-loop would lock a node to whichever relation SQLite returned first and drop a stronger seed's later edge.
 function bestStrengthAtDepth(rels, frontierSet, visited, frontierStrength, originStrength) {
     const bestStrengthThisDepth = new Map();
     for (const rel of rels) {
@@ -63,7 +56,8 @@ function bestStrengthAtDepth(rels, frontierSet, visited, frontierStrength, origi
     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) {
+function reachedEntityScores(root, tenantId, seedIds, originStrength, options) {
+    const { hops, decay, maxNeighbors } = options;
     const visited = new Set(seedIds); // seeds never re-reached
     const reachedScore = new Map(); // entityId -> best score
     let frontier = seedIds;
@@ -97,14 +91,10 @@ function reachedEntityScores(root, tenantId, seedIds, originStrength, hops, deca
     }
     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) {
+/** Accumulate per-entryIndex graph-proximity scores from ONE store's graph into `graphScore`; only seeds whose entities live in THIS store are expanded.
+ *  A neighbour's score = originSeedStrength x decay^(graph distance); the seed strength is carried unchanged along each BFS path. */
+function accumulateForRoot(root, seeds, entries, options) {
+    const { memIdToIndex, graphScore, hops, decay, maxNeighbors, tenantId } = options;
     if (seeds.length === 0)
         return;
     // The strongest seed strength per source memory id (a memId could appear once, but
@@ -117,9 +107,7 @@ function accumulateForRoot(root, seeds, entries, memIdToIndex, graphScore, hops,
     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).
+    // entityId -> origin seed strength. Seeds load by memory id so memoryId is non-null here; the guard keeps the widened (string | null) type honest.
     const originStrength = new Map();
     for (const e of seedEntities) {
         if (e.memoryId === null)
@@ -127,7 +115,7 @@ function accumulateForRoot(root, seeds, entries, memIdToIndex, graphScore, hops,
         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);
+    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.
@@ -144,14 +132,8 @@ function accumulateForRoot(root, seeds, entries, memIdToIndex, graphScore, hops,
         graphScore.set(idx, Math.max(graphScore.get(idx) ?? 0, score));
     }
 }
-/**
- * Produce the graph-retrieval ranked list: `entries[]` indices ordered by graph
- * proximity (desc) to the lexical `seeds`. Only graph-reached, in-pool, non-seed
- * indices appear; the rest are absent (-> rrfFuse absentRank). Pure reads.
- *
- * Returns `[]` when there are no seeds/entries, the graph is empty, no seed maps to an
- * entity, or nothing reached is in-pool — the caller then skips the 3rd fusion list.
- */
+/** Produce the graph-retrieval ranked list: `entries[]` indices by graph proximity (desc) to the lexical `seeds`; absent indices fall to rrfFuse absentRank.
+ *  Returns `[]` when there are no seeds/entries, the graph is empty, or nothing reached is in-pool, so the caller skips the 3rd fusion list. */
 export function graphRankStream(entries, seeds, opts) {
     if (seeds.length === 0 || entries.length === 0)
         return [];
@@ -166,13 +148,10 @@ export function graphRankStream(entries, seeds, opts) {
         ? [opts.hippoRoot, opts.globalRoot]
         : [opts.hippoRoot];
     for (const root of roots) {
-        accumulateForRoot(root, seeds, entries, memIdToIndex, graphScore, hops, decay, maxNeighbors, opts.tenantId);
+        accumulateForRoot(root, seeds, entries, { memIdToIndex, graphScore, hops, decay, maxNeighbors, tenantId: opts.tenantId });
     }
-    // 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
-    // stream" invariant holds across roots, not just within a single store's traversal.
+    // Seed-exclusion guard: graphScore is keyed by entryIndex across roots but each root's visited-set is per-root, so a seed in one store
+    // could score as a neighbour in the other; drop every seed index so "seeds are never graph-scored" holds across roots.
     for (const s of seeds)
         graphScore.delete(s.index);
     if (graphScore.size === 0)
@@ -182,4 +161,4 @@ export function graphRankStream(entries, seeds, opts) {
         return d !== 0 ? d : a - b; // score desc, then index asc (deterministic)
     });
 }
-//# sourceMappingURL=graph-stream.js.map
+//# sourceMappingURL=stream.js.map

package/dist/graph/view.d.ts

@@ -0,0 +1,50 @@
+/** Graph observability and visualization, READ-ONLY over the entity/relation graph (no writes, so `scripts/check-graph-writes.mjs` stays green).
+ *  Shared by `hippo graph show|view` and the HTTP `GET /v1/graph` route, which all build the same `GraphModel`. */
+import type { GraphRows } from '../store/port.js';
+import type { EntityType, RelationType } from '../store/graph-rows.js';
+export interface GraphNode {
+    id: number;
+    type: EntityType;
+    name: string;
+}
+export interface GraphEdge {
+    from: number;
+    to: number;
+    relType: RelationType;
+}
+export interface GraphModel {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    /** Conservative "maybe incomplete" flag: true when a loader returned exactly
+     *  its limit (the graph MAY be truncated). Can over-report, never under-report. */
+    truncated: boolean;
+}
+/** Default bound for the CLI viewer / show so an unbounded set is never laid out. */
+export declare const DEFAULT_VIEW_LIMIT = 500;
+/** Build the view-model (reads only); with `opts.entity`, a focus subgraph of the entities named so plus their 1-hop neighbours.
+ *  Dangling edges (an endpoint outside the node set) are always dropped. */
+export declare function buildGraphModel(hippoRoot: string, tenantId: string, opts?: {
+    entity?: string;
+    limit?: number;
+    canRead?: (scope: string | null) => boolean;
+}): GraphModel;
+/** The reply model of the rows a store read: an edge with an endpoint outside the node set is dropped. */
+export declare function graphModelOf({ entities, relations, truncated }: GraphRows): GraphModel;
+/** Deterministic Fruchterman-Reingold-style force layout: seeded circular init, fixed iterations, no `Math.random`, so one model gives the same positions.
+ *  Non-finite coordinates are clamped to the viewport centre and all positions to the bounds. */
+export declare function layoutGraph(model: GraphModel, opts?: {
+    width?: number;
+    height?: number;
+    iterations?: number;
+}): Map<number, {
+    x: number;
+    y: number;
+}>;
+/** HTML-escape for SVG text / title / markup content (XSS guard). */
+export declare function escapeHtml(s: string): string;
+/** Render the model as a self-contained, offline interactive HTML node-link diagram with server-side deterministic positions.
+ *  The model is inlined as `<script type="application/json">` with `<`, `>`, `&` unicode-escaped so a `</script>` in an entity name cannot break out. */
+export declare function renderGraphHtml(model: GraphModel): string;
+/** Render the model as a JSON Canvas (jsoncanvas.org) document: `text` nodes at the same deterministic layout positions, `edges[]` linking them by id. */
+export declare function renderGraphCanvas(model: GraphModel): string;
+//# sourceMappingURL=view.d.ts.map