hippo-memory 1.19.0 → 1.21.0

package/dist/graph-stream.d.ts

@@ -0,0 +1,71 @@
+/**
+ * L1 — graph-retrieval ranked-list stream for RRF fusion
+ * (docs/plans/2026-06-02-l1-graph-rrf-stream.md).
+ *
+ * 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
+ * proximity to the strong lexical seeds, for use as a 3rd fusion input to `rrfFuse`
+ * beside BM25 + dense (src/search.ts hybridSearch, scoring:'rrf').
+ *
+ * DISTINCT from graph-recall.ts: that INJECTS out-of-pool neighbours post-hoc; this
+ * RE-RANKS within the already-filtered candidate pool. It only assigns ranks to
+ * entries that are (a) graph-reached from a seed AND (b) present in `entries[]`. Seeds
+ * 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
+ * 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
+ * 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
+ * WITHIN-graph-stream ORDERING; RRF then re-ranks the list by 1/(k + graphRank), so the
+ * absolute magnitude is washed out by fusion. Do not tune the scale expecting a
+ * fused-score effect — only the induced order matters.
+ */
+import type { MemoryEntry } from './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 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.
+ */
+export declare function selectGraphSeeds(bm25Ranked: ReadonlyArray<number>, cosineRanked: ReadonlyArray<number>, seedCount: number): GraphSeed[];
+/**
+ * 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.
+ */
+export declare function graphRankStream(entries: ReadonlyArray<MemoryEntry>, seeds: ReadonlyArray<GraphSeed>, opts: GraphStreamOpts): number[];
+//# sourceMappingURL=graph-stream.d.ts.map

package/dist/graph-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-stream.d.ts","sourceRoot":"","sources":["../src/graph-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAQ/C,gGAAgG;AAChG,eAAO,MAAM,kBAAkB,IAAI,CAAC;AACpC,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,yDAAyD;AACzD,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAC3C;+EAC+E;AAC/E,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C,yFAAyF;AACzF,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,EACjC,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,EACnC,SAAS,EAAE,MAAM,GAChB,SAAS,EAAE,CAgBb;AAmGD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,EACnC,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,EAC/B,IAAI,EAAE,eAAe,GACpB,MAAM,EAAE,CA+BV"}

package/dist/graph-stream.js

@@ -0,0 +1,170 @@
+import { loadEntitiesByMemoryId, loadEntitiesByIds, loadNeighborRelations, } from './graph.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). */
+export const DEFAULT_GRAPH_HOPS = 2;
+/** Default per-hop multiplicative decay applied to the seed strength. */
+export const DEFAULT_GRAPH_DECAY = 0.5;
+/** Default number of top lexical seeds expanded from. */
+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.
+ */
+export function selectGraphSeeds(bm25Ranked, cosineRanked, seedCount) {
+    if (seedCount <= 0)
+        return [];
+    const bestPos = new Map();
+    const consider = (list) => {
+        for (let p = 0; p < list.length; p++) {
+            const idx = list[p];
+            const prev = bestPos.get(idx);
+            if (prev === undefined || p < prev)
+                bestPos.set(idx, p);
+        }
+    };
+    consider(bm25Ranked);
+    consider(cosineRanked);
+    return [...bestPos.entries()]
+        .sort((a, b) => a[1] - b[1] || a[0] - b[0]) // best rank asc, then index asc (deterministic)
+        .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).
+    const originStrength = new Map();
+    for (const e of seedEntities) {
+        const st = strengthByMemId.get(e.memoryId) ?? 0;
+        originStrength.set(e.id, Math.max(originStrength.get(e.id) ?? 0, st));
+    }
+    const visited = new Set(seedEntities.map((e) => e.id)); // seeds never re-reached
+    const reachedScore = new Map(); // entityId -> best score
+    let frontier = seedEntities.map((e) => e.id);
+    let frontierStrength = new Map(originStrength); // entityId -> seed strength
+    for (let depth = 1; depth <= hops && frontier.length > 0; depth++) {
+        const frontierSet = new Set(frontier);
+        const rels = loadNeighborRelations(root, tenantId, frontier, {
+            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));
+        }
+        // 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 = [];
+        const nextStrength = new Map();
+        const ordered = [...bestStrengthThisDepth.keys()].sort((a, b) => {
+            const d = bestStrengthThisDepth.get(b) - bestStrengthThisDepth.get(a);
+            return d !== 0 ? d : a - b;
+        });
+        for (const neighborId of ordered) {
+            if (nextFrontier.length >= maxNeighbors)
+                break; // per-hop fanout cap (strongest kept)
+            const seedStrength = bestStrengthThisDepth.get(neighborId);
+            visited.add(neighborId);
+            reachedScore.set(neighborId, Math.max(reachedScore.get(neighborId) ?? 0, seedStrength * hopFactor));
+            nextStrength.set(neighborId, seedStrength);
+            nextFrontier.push(neighborId);
+        }
+        frontier = nextFrontier;
+        frontierStrength = nextStrength;
+    }
+    if (reachedScore.size === 0)
+        return;
+    // Reached entity ids -> source memory ids -> in-pool entry indices.
+    const reachedEntities = loadEntitiesByIds(root, tenantId, [...reachedScore.keys()]);
+    for (const ent of reachedEntities) {
+        const idx = memIdToIndex.get(ent.memoryId);
+        if (idx === undefined)
+            continue; // reached memory is not in the candidate pool
+        const score = reachedScore.get(ent.id) ?? 0;
+        if (score <= 0)
+            continue;
+        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.
+ */
+export function graphRankStream(entries, seeds, opts) {
+    if (seeds.length === 0 || entries.length === 0)
+        return [];
+    const hops = Math.min(Math.max(opts.hops ?? DEFAULT_GRAPH_HOPS, 1), MAX_HOPS);
+    const decay = opts.decay ?? DEFAULT_GRAPH_DECAY;
+    const maxNeighbors = opts.maxNeighbors ?? DEFAULT_MAX_NEIGHBORS;
+    const memIdToIndex = new Map();
+    for (let i = 0; i < entries.length; i++)
+        memIdToIndex.set(entries[i].id, i);
+    const graphScore = new Map();
+    const roots = opts.globalRoot && opts.globalRoot !== opts.hippoRoot
+        ? [opts.hippoRoot, opts.globalRoot]
+        : [opts.hippoRoot];
+    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
+    // 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.
+    for (const s of seeds)
+        graphScore.delete(s.index);
+    if (graphScore.size === 0)
+        return [];
+    return [...graphScore.keys()].sort((a, b) => {
+        const d = (graphScore.get(b) ?? 0) - (graphScore.get(a) ?? 0);
+        return d !== 0 ? d : a - b; // score desc, then index asc (deterministic)
+    });
+}
+//# sourceMappingURL=graph-stream.js.map

package/dist/graph-stream.js.map

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

package/dist/graph-view.d.ts

@@ -0,0 +1,72 @@
+/**
+ * E3 graph observability + visualization — READ-ONLY over the entity/relation
+ * graph (docs/plans/2026-06-02-graph-observability.md).
+ *
+ * This module only READS the graph (`loadEntities` / `loadRelations`) and renders
+ * view-models; it issues no INSERT/UPDATE/DELETE, so `scripts/check-graph-writes.mjs`
+ * stays green. Used by the CLI (`hippo graph show` / `hippo graph view`) and the
+ * HTTP `GET /v1/graph` route, which all build the same `GraphModel`.
+ */
+import { type EntityType, type RelationType } from './graph.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 from the graph (reads only). With `opts.entity`, returns a
+ * focus subgraph: every entity whose name === entity, plus their 1-hop neighbours,
+ * plus the edges among that union. Dangling edges (an endpoint outside the node
+ * set) are always dropped.
+ */
+export declare function buildGraphModel(hippoRoot: string, tenantId: string, opts?: {
+    entity?: string;
+    limit?: number;
+}): GraphModel;
+/**
+ * Deterministic Fruchterman-Reingold-style force layout. Seeded circular init +
+ * fixed iterations, NO `Math.random`, so the same model always yields the same
+ * positions (testable, stable output). Non-finite coordinates from a degenerate
+ * step are clamped to the viewport centre; all positions are clamped in-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, dependency-free, offline interactive HTML
+ * node-link diagram. Positions are computed server-side (deterministic). User
+ * strings are escaped per sink: SVG `<text>`/`<title>` via `escapeHtml`; the model
+ * is inlined in a `<script type="application/json">` block with `<`/`>`/`&`
+ * unicode-escaped so a `</script>` inside an entity name cannot break out (the
+ * client `JSON.parse`s it back and never `innerHTML`s a user string).
+ */
+export declare function renderGraphHtml(model: GraphModel): string;
+/**
+ * Render the model as a JSON Canvas (jsoncanvas.org) document — `nodes[]` of
+ * type `text` positioned by the same deterministic layout, `edges[]` linking
+ * them by id. Opens natively in Obsidian. Pure JSON; entity names live in the
+ * `text` field (Obsidian renders/sanitizes them).
+ */
+export declare function renderGraphCanvas(model: GraphModel): string;
+//# sourceMappingURL=graph-view.d.ts.map

package/dist/graph-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-view.d.ts","sourceRoot":"","sources":["../src/graph-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAUL,KAAK,UAAU,EACf,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AACD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,YAAY,CAAC;CACvB;AACD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB;uFACmF;IACnF,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,qFAAqF;AACrF,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,UAAU,CA8DZ;AAKD;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAClE,GAAG,CAAC,MAAM,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA2EvC;AAED,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAO5C;AAoDD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CA2DzD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAqB3D"}

package/dist/graph-view.js

@@ -0,0 +1,310 @@
+/**
+ * E3 graph observability + visualization — READ-ONLY over the entity/relation
+ * graph (docs/plans/2026-06-02-graph-observability.md).
+ *
+ * This module only READS the graph (`loadEntities` / `loadRelations`) and renders
+ * view-models; it issues no INSERT/UPDATE/DELETE, so `scripts/check-graph-writes.mjs`
+ * stays green. Used by the CLI (`hippo graph show` / `hippo graph view`) and the
+ * HTTP `GET /v1/graph` route, which all build the same `GraphModel`.
+ */
+import { loadEntities, loadEntitiesByName, loadEntitiesByIds, loadRelations, loadNeighborRelations, loadRelationsAmong, withGraphReadSnapshot, } from './graph.js';
+/** Default bound for the CLI viewer / show so an unbounded set is never laid out. */
+export const DEFAULT_VIEW_LIMIT = 500;
+/**
+ * Build the view-model from the graph (reads only). With `opts.entity`, returns a
+ * focus subgraph: every entity whose name === entity, plus their 1-hop neighbours,
+ * plus the edges among that union. Dangling edges (an endpoint outside the node
+ * set) are always dropped.
+ */
+export function buildGraphModel(hippoRoot, tenantId, opts = {}) {
+    const limit = opts.limit ?? DEFAULT_VIEW_LIMIT;
+    // All reads run inside ONE read snapshot so a concurrent `graph extract` /
+    // sleep-drain rebuild can't make the model mix old entity ids with new relation
+    // ids (codex P2). Every load* call below is passed the snapshot connection `db`.
+    return withGraphReadSnapshot(hippoRoot, (db) => {
+        let nodeEntities;
+        let relations;
+        let truncated;
+        if (opts.entity !== undefined) {
+            // Focus subgraph. (1) Query the named entity DIRECTLY (by name, not from a
+            // globally-capped list) so it is found even on a graph larger than `limit`.
+            // (2) A name can map to MANY entities (e.g. many notes for one customer), so
+            // cap the focus matches. (3) Discover 1-hop neighbours and cap the UNION to
+            // `limit` nodes. (4) Load ALL edges AMONG the union so neighbour-to-neighbour
+            // edges that don't touch the focus are included too. (codex P2s.)
+            const focus = loadEntitiesByName(hippoRoot, tenantId, opts.entity, { limit }, db);
+            if (focus.length === 0)
+                return { nodes: [], edges: [], truncated: false };
+            const focusIds = focus.map((e) => e.id);
+            const hop = loadNeighborRelations(hippoRoot, tenantId, focusIds, { limit }, db);
+            const union = new Set(focusIds);
+            let neighboursCapped = false;
+            for (const r of hop) {
+                if (union.size >= limit) {
+                    neighboursCapped = true; // node cap filled before all neighbours were added
+                    break;
+                }
+                union.add(r.fromEntityId);
+                union.add(r.toEntityId);
+            }
+            const unionIds = [...union].slice(0, limit);
+            nodeEntities = loadEntitiesByIds(hippoRoot, tenantId, unionIds, db);
+            // Edges AMONG the union (BOTH endpoints in the set): includes
+            // neighbour-to-neighbour edges, and the LIMIT can never drop a valid in-union
+            // edge in favour of out-of-union rows (codex P2).
+            relations = loadRelationsAmong(hippoRoot, tenantId, unionIds, { limit }, db);
+            truncated =
+                focus.length >= limit ||
+                    hop.length >= limit || // neighbour scan capped -> a 1-hop neighbour may be omitted (codex P2)
+                    neighboursCapped || // node cap filled before all neighbours were consumed (codex P2)
+                    union.size > unionIds.length ||
+                    relations.length >= limit;
+        }
+        else {
+            nodeEntities = loadEntities(hippoRoot, tenantId, { limit }, db);
+            relations = loadRelations(hippoRoot, tenantId, { limit }, db);
+            truncated = nodeEntities.length >= limit || relations.length >= limit;
+        }
+        const nodeIds = new Set(nodeEntities.map((e) => e.id));
+        const nodes = nodeEntities.map((e) => ({
+            id: e.id,
+            type: e.entityType,
+            name: e.name,
+        }));
+        const edges = relations
+            .filter((r) => nodeIds.has(r.fromEntityId) && nodeIds.has(r.toEntityId))
+            .map((r) => ({ from: r.fromEntityId, to: r.toEntityId, relType: r.relType }));
+        return { nodes, edges, truncated };
+    });
+}
+const LAYOUT_W = 1000;
+const LAYOUT_H = 700;
+/**
+ * Deterministic Fruchterman-Reingold-style force layout. Seeded circular init +
+ * fixed iterations, NO `Math.random`, so the same model always yields the same
+ * positions (testable, stable output). Non-finite coordinates from a degenerate
+ * step are clamped to the viewport centre; all positions are clamped in-bounds.
+ */
+export function layoutGraph(model, opts = {}) {
+    const width = opts.width ?? LAYOUT_W;
+    const height = opts.height ?? LAYOUT_H;
+    const iterations = opts.iterations ?? 300;
+    const cx = width / 2;
+    const cy = height / 2;
+    const nodes = model.nodes;
+    const n = nodes.length;
+    const pos = new Map();
+    if (n === 0)
+        return pos;
+    if (n === 1) {
+        pos.set(nodes[0].id, { x: cx, y: cy });
+        return pos;
+    }
+    const radius = Math.min(width, height) * 0.4;
+    nodes.forEach((node, i) => {
+        const angle = (2 * Math.PI * i) / n;
+        pos.set(node.id, { x: cx + radius * Math.cos(angle), y: cy + radius * Math.sin(angle) });
+    });
+    const idIndex = new Map(nodes.map((node, i) => [node.id, i]));
+    const k = Math.sqrt((width * height) / n); // ideal edge length
+    for (let iter = 0; iter < iterations; iter++) {
+        const disp = nodes.map(() => ({ x: 0, y: 0 }));
+        // Repulsion between all pairs.
+        for (let i = 0; i < n; i++) {
+            const pi = pos.get(nodes[i].id);
+            for (let j = i + 1; j < n; j++) {
+                const pj = pos.get(nodes[j].id);
+                const dx = pi.x - pj.x;
+                const dy = pi.y - pj.y;
+                const dist = Math.hypot(dx, dy) || 0.01;
+                const rep = (k * k) / dist;
+                const ux = dx / dist;
+                const uy = dy / dist;
+                disp[i].x += ux * rep;
+                disp[i].y += uy * rep;
+                disp[j].x -= ux * rep;
+                disp[j].y -= uy * rep;
+            }
+        }
+        // Attraction along edges.
+        for (const e of model.edges) {
+            const i = idIndex.get(e.from);
+            const j = idIndex.get(e.to);
+            if (i === undefined || j === undefined)
+                continue;
+            const pi = pos.get(e.from);
+            const pj = pos.get(e.to);
+            const dx = pi.x - pj.x;
+            const dy = pi.y - pj.y;
+            const dist = Math.hypot(dx, dy) || 0.01;
+            const att = (dist * dist) / k;
+            const ux = dx / dist;
+            const uy = dy / dist;
+            disp[i].x -= ux * att;
+            disp[i].y -= uy * att;
+            disp[j].x += ux * att;
+            disp[j].y += uy * att;
+        }
+        // Apply with cooling; clamp.
+        const temp = Math.max(1, (width / 10) * (1 - iter / iterations));
+        nodes.forEach((node, i) => {
+            const p = pos.get(node.id);
+            const dl = Math.hypot(disp[i].x, disp[i].y) || 0.01;
+            let nx = p.x + (disp[i].x / dl) * Math.min(dl, temp);
+            let ny = p.y + (disp[i].y / dl) * Math.min(dl, temp);
+            if (!Number.isFinite(nx))
+                nx = cx;
+            if (!Number.isFinite(ny))
+                ny = cy;
+            p.x = Math.max(20, Math.min(width - 20, nx));
+            p.y = Math.max(20, Math.min(height - 20, ny));
+        });
+    }
+    return pos;
+}
+/** HTML-escape for SVG text / title / markup content (XSS guard). */
+export function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+const NODE_COLORS = {
+    decision: '#6366f1',
+    policy: '#10b981',
+    customer: '#f59e0b',
+    project: '#ec4899',
+    person: '#3b82f6',
+    system: '#64748b',
+};
+// Client script: pan (drag bg), zoom (wheel), click-to-highlight a node's edges +
+// neighbours. Reads the inlined model via JSON.parse (never innerHTML), so user
+// strings never reach an HTML sink here. No template literals / `${}` so it nests
+// safely inside this module's own template strings.
+const CLIENT_JS = [
+    "(function(){",
+    "  var svg=document.getElementById('g');",
+    "  var vb=svg.getAttribute('viewBox').split(' ').map(Number);",
+    "  var view={x:vb[0],y:vb[1],w:vb[2],h:vb[3]};",
+    "  function apply(){svg.setAttribute('viewBox',view.x+' '+view.y+' '+view.w+' '+view.h);}",
+    "  var panning=false,sx=0,sy=0;",
+    "  svg.addEventListener('mousedown',function(e){if(e.target.closest('.node'))return;panning=true;sx=e.clientX;sy=e.clientY;});",
+    "  window.addEventListener('mouseup',function(){panning=false;});",
+    "  window.addEventListener('mousemove',function(e){if(!panning)return;var r=svg.getBoundingClientRect();var k=view.w/r.width;view.x-=(e.clientX-sx)*k;view.y-=(e.clientY-sy)*k;sx=e.clientX;sy=e.clientY;apply();});",
+    "  svg.addEventListener('wheel',function(e){e.preventDefault();var r=svg.getBoundingClientRect();var mx=view.x+(e.clientX-r.left)/r.width*view.w;var my=view.y+(e.clientY-r.top)/r.height*view.h;var f=e.deltaY<0?0.9:1.1;view.x=mx-(mx-view.x)*f;view.y=my-(my-view.y)*f;view.w*=f;view.h*=f;apply();},{passive:false});",
+    "  var data={};try{data=JSON.parse(document.getElementById('graph-data').textContent);}catch(_){}",
+    "  var adj={};(data.edges||[]).forEach(function(e){(adj[e.from]=adj[e.from]||[]).push(e.to);(adj[e.to]=adj[e.to]||[]).push(e.from);});",
+    "  var active=null;",
+    "  document.querySelectorAll('.node').forEach(function(g){g.addEventListener('click',function(ev){ev.stopPropagation();var id=g.getAttribute('data-id');if(active===id){clearHi();active=null;return;}active=id;highlight(id);});});",
+    "  svg.addEventListener('click',function(){clearHi();active=null;});",
+    "  function clearHi(){svg.classList.remove('focused');document.querySelectorAll('.hi').forEach(function(el){el.classList.remove('hi');});}",
+    "  function highlight(id){clearHi();svg.classList.add('focused');var keep={};keep[id]=1;(adj[id]||[]).forEach(function(n){keep[n]=1;});document.querySelectorAll('.node').forEach(function(g){if(keep[g.getAttribute('data-id')])g.classList.add('hi');});document.querySelectorAll('.edge').forEach(function(l){if(l.getAttribute('data-from')===id||l.getAttribute('data-to')===id)l.classList.add('hi');});}",
+    "})();",
+].join("\n");
+const STYLE = [
+    "html,body{margin:0;height:100%;background:#0b1020;font-family:ui-sans-serif,system-ui,sans-serif}",
+    "#g{width:100vw;height:100vh;cursor:grab}",
+    "#g:active{cursor:grabbing}",
+    ".edge{stroke:#475569;stroke-width:1}",
+    ".node circle{stroke:#0b1020;stroke-width:1.5}",
+    ".node text{fill:#e2e8f0;font-size:11px;pointer-events:none}",
+    ".node{cursor:pointer}",
+    "#g.focused .node{opacity:.18}",
+    "#g.focused .edge{opacity:.07}",
+    "#g.focused .node.hi{opacity:1}",
+    "#g.focused .edge.hi{opacity:1;stroke:#e2e8f0}",
+    ".legend{position:fixed;top:10px;left:12px;color:#94a3b8;font-size:12px;line-height:1.6}",
+    ".legend b{color:#e2e8f0}",
+].join("\n");
+/**
+ * Render the model as a SELF-CONTAINED, dependency-free, offline interactive HTML
+ * node-link diagram. Positions are computed server-side (deterministic). User
+ * strings are escaped per sink: SVG `<text>`/`<title>` via `escapeHtml`; the model
+ * is inlined in a `<script type="application/json">` block with `<`/`>`/`&`
+ * unicode-escaped so a `</script>` inside an entity name cannot break out (the
+ * client `JSON.parse`s it back and never `innerHTML`s a user string).
+ */
+export function renderGraphHtml(model) {
+    const pos = layoutGraph(model);
+    const color = (t) => NODE_COLORS[t] ?? '#64748b';
+    const edgeSvg = model.edges
+        .map((e) => {
+        const a = pos.get(e.from);
+        const b = pos.get(e.to);
+        if (!a || !b)
+            return '';
+        return (`<line class="edge" data-from="${e.from}" data-to="${e.to}" ` +
+            `x1="${a.x.toFixed(1)}" y1="${a.y.toFixed(1)}" x2="${b.x.toFixed(1)}" y2="${b.y.toFixed(1)}"/>`);
+    })
+        .join('');
+    const nodeSvg = model.nodes
+        .map((node) => {
+        const p = pos.get(node.id);
+        if (!p)
+            return '';
+        const label = node.name.length > 22 ? node.name.slice(0, 21) + '…' : node.name;
+        return (`<g class="node" data-id="${node.id}" transform="translate(${p.x.toFixed(1)},${p.y.toFixed(1)})">` +
+            `<title>${escapeHtml(node.type + ': ' + node.name)}</title>` +
+            `<circle r="7" fill="${color(node.type)}"/>` +
+            `<text x="10" y="4">${escapeHtml(label)}</text>` +
+            `</g>`);
+    })
+        .join('');
+    // Safe inline JSON for the client: unicode-escape the HTML-significant chars so
+    // the content cannot terminate the <script> block; JSON.parse restores them.
+    const dataJson = JSON.stringify(model)
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/&/g, '\\u0026');
+    const types = [...new Set(model.nodes.map((nd) => nd.type))];
+    const legend = types
+        .map((t) => `<span style="color:${color(t)}">●</span> ${escapeHtml(t)}`)
+        .join('  ');
+    return [
+        '<!doctype html>',
+        '<html lang="en"><head><meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        '<title>hippo graph</title>',
+        '<style>' + STYLE + '</style></head><body>',
+        `<div class="legend"><b>hippo graph</b> · ${model.nodes.length} entities · ${model.edges.length} relations` +
+            (model.truncated ? ' · <b style="color:#f59e0b">truncated</b>' : '') +
+            `<br>${legend}<br><span style="color:#64748b">drag to pan · scroll to zoom · click a node to focus</span></div>`,
+        `<svg id="g" viewBox="0 0 ${LAYOUT_W} ${LAYOUT_H}" preserveAspectRatio="xMidYMid meet">`,
+        `<g id="edges">${edgeSvg}</g><g id="nodes">${nodeSvg}</g>`,
+        '</svg>',
+        `<script type="application/json" id="graph-data">${dataJson}</script>`,
+        '<script>' + CLIENT_JS + '</script>',
+        '</body></html>',
+    ].join('\n');
+}
+/**
+ * Render the model as a JSON Canvas (jsoncanvas.org) document — `nodes[]` of
+ * type `text` positioned by the same deterministic layout, `edges[]` linking
+ * them by id. Opens natively in Obsidian. Pure JSON; entity names live in the
+ * `text` field (Obsidian renders/sanitizes them).
+ */
+export function renderGraphCanvas(model) {
+    const pos = layoutGraph(model, { width: 2400, height: 1600 });
+    const nodes = model.nodes.map((node) => {
+        const p = pos.get(node.id) ?? { x: 0, y: 0 };
+        return {
+            id: `n${node.id}`,
+            type: 'text',
+            x: Math.round(p.x),
+            y: Math.round(p.y),
+            width: 240,
+            height: 60,
+            text: `**${node.type}**\n${node.name}`,
+        };
+    });
+    const edges = model.edges.map((e, i) => ({
+        id: `e${i}`,
+        fromNode: `n${e.from}`,
+        toNode: `n${e.to}`,
+        label: e.relType,
+    }));
+    return JSON.stringify({ nodes, edges }, null, 2);
+}
+//# sourceMappingURL=graph-view.js.map