hippo-memory 1.68.0 → 1.70.0

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

@@ -2,33 +2,17 @@
  * Graph observability and visualization, READ-ONLY over the entity/relation
  * graph.
  *
- * This module only READS the graph (`loadEntities` / `loadRelations`) and renders
+ * This module only READS the graph (through the store's graph reads) 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/read.js';
+import { withGraphReadSnapshot } from '../store/graph-reads.js';
+import { graphViewRows } from '../store/graph-view-rows.js';
+const DEFAULT_LAYOUT_ITERATIONS = 300;
+const NODE_LABEL_MAX_CHARS = 22;
 /** Default bound for the CLI viewer / show so an unbounded set is never laid out. */
 export const DEFAULT_VIEW_LIMIT = 500;
-// graph/read.ts's IN-list chunk, so one statement stays far under SQLite's bound-parameter limit.
-const MEMORY_ID_CHUNK = 400;
-/** The items whose source memory `canRead` admits: a NULL memoryId has no scope to hide, and a missing memory fails closed. */
-function readableOnly(db, tenantId, items, canRead) {
-    if (!canRead)
-        return items;
-    const ids = [...new Set(items.flatMap((i) => (i.memoryId === null ? [] : [i.memoryId])))];
-    const readable = new Set();
-    for (let i = 0; i < ids.length; i += MEMORY_ID_CHUNK) {
-        const slice = ids.slice(i, i + MEMORY_ID_CHUNK);
-        // SAFETY: rows' shape matches the id and scope columns named in the SELECT.
-        const rows = db.prepare(`SELECT id, scope FROM memories WHERE tenant_id = ? AND id IN (${slice.map(() => '?').join(',')})`)
-            .all(tenantId, ...slice);
-        for (const r of rows)
-            if (canRead(r.scope))
-                readable.add(r.id);
-    }
-    return items.filter((i) => i.memoryId === null || readable.has(i.memoryId));
-}
 /**
  * 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,
@@ -37,71 +21,90 @@ function readableOnly(db, tenantId, items, canRead) {
  */
 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. 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.
-            const named = loadEntitiesByName(hippoRoot, tenantId, opts.entity, { limit }, db);
-            // A hidden focus must not answer through its neighbours that the name exists.
-            const focus = readableOnly(db, tenantId, named, opts.canRead);
-            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.
-            relations = loadRelationsAmong(hippoRoot, tenantId, unionIds, { limit }, db);
-            truncated =
-                named.length >= limit ||
-                    hop.length >= limit || // neighbour scan capped -> a 1-hop neighbour may be omitted
-                    neighboursCapped || // node cap filled before all neighbours were consumed
-                    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;
-        }
-        nodeEntities = readableOnly(db, tenantId, nodeEntities, opts.canRead);
-        relations = readableOnly(db, tenantId, relations, opts.canRead);
-        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 };
-    });
+    // One read snapshot, so a concurrent graph rebuild cannot make the model mix old entity ids with new relation ids.
+    return withGraphReadSnapshot(hippoRoot, (db) => graphModelOf(graphViewRows(hippoRoot, db, tenantId, { entity: opts.entity, limit, canRead: opts.canRead })));
+}
+/** The reply model of the rows a store read: an edge with an endpoint outside the node set is dropped. */
+export function graphModelOf({ entities, relations, truncated }) {
+    const nodeIds = new Set(entities.map((e) => e.id));
+    const nodes = entities.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;
+function seedCircle(nodes, width, height) {
+    const pos = new Map();
+    const n = nodes.length;
+    const radius = Math.min(width, height) * 0.4;
+    nodes.forEach((node, i) => {
+        const angle = (2 * Math.PI * i) / n;
+        pos.set(node.id, {
+            x: width / 2 + radius * Math.cos(angle),
+            y: height / 2 + radius * Math.sin(angle),
+        });
+    });
+    return pos;
+}
+function addRepulsion(nodes, pos, disp, k) {
+    const n = nodes.length;
+    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;
+        }
+    }
+}
+function addAttraction(edges, idIndex, pos, disp, k) {
+    for (const e of 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;
+    }
+}
+function applyDisplacement(nodes, pos, disp, temp, width, height) {
+    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 = width / 2;
+        if (!Number.isFinite(ny))
+            ny = height / 2;
+        p.x = Math.max(20, Math.min(width - 20, nx));
+        p.y = Math.max(20, Math.min(height - 20, ny));
+    });
+}
 /**
  * Deterministic Fruchterman-Reingold-style force layout. Seeded circular init +
  * fixed iterations, NO `Math.random`, so the same model always yields the same
@@ -111,77 +114,22 @@ const LAYOUT_H = 700;
 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 iterations = opts.iterations ?? DEFAULT_LAYOUT_ITERATIONS;
     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) });
-    });
+        return new Map();
+    if (n === 1)
+        return new Map([[nodes[0].id, { x: width / 2, y: height / 2 }]]);
+    const pos = seedCircle(nodes, width, height);
     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.
+        addRepulsion(nodes, pos, disp, k);
+        addAttraction(model.edges, idIndex, pos, disp, k);
         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));
-        });
+        applyDisplacement(nodes, pos, disp, temp, width, height);
     }
     return pos;
 }
@@ -241,18 +189,9 @@ const STYLE = [
     ".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
+const nodeColor = (t) => NODE_COLORS[t] ?? '#64748b';
+function renderEdgeSvg(model, pos) {
+    return model.edges
         .map((e) => {
         const a = pos.get(e.from);
         const b = pos.get(e.to);
@@ -262,29 +201,50 @@ export function renderGraphHtml(model) {
             `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
+}
+function renderNodeSvg(model, pos) {
+    return 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;
+        const label = node.name.length > NODE_LABEL_MAX_CHARS ? node.name.slice(0, NODE_LABEL_MAX_CHARS - 1) + '…' : 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)}"/>` +
+            `<circle r="7" fill="${nodeColor(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)
+}
+// Safe inline JSON for the client: unicode-escape the HTML-significant chars so
+// the content cannot terminate the <script> block; JSON.parse restores them.
+function inlineModelJson(model) {
+    return JSON.stringify(model)
         .replace(/</g, '\\u003c')
         .replace(/>/g, '\\u003e')
         .replace(/&/g, '\\u0026');
+}
+function renderLegend(model) {
     const types = [...new Set(model.nodes.map((nd) => nd.type))];
-    const legend = types
-        .map((t) => `<span style="color:${color(t)}">●</span> ${escapeHtml(t)}`)
+    return types
+        .map((t) => `<span style="color:${nodeColor(t)}">●</span> ${escapeHtml(t)}`)
         .join('  ');
+}
+/**
+ * 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 edgeSvg = renderEdgeSvg(model, pos);
+    const nodeSvg = renderNodeSvg(model, pos);
+    const dataJson = inlineModelJson(model);
+    const legend = renderLegend(model);
     return [
         '<!doctype html>',
         '<html lang="en"><head><meta charset="utf-8">',
@@ -330,4 +290,4 @@ export function renderGraphCanvas(model) {
     }));
     return JSON.stringify({ nodes, edges }, null, 2);
 }
-//# sourceMappingURL=graph-view.js.map
+//# sourceMappingURL=view.js.map

package/dist/graph/write.d.ts

@@ -1,86 +1,14 @@
-/**
- * Graph layer over consolidated state - the graph-on-consolidated guard.
- *
- * A graph of canonical `entities` (person/project/customer/system/policy/decision) and
- * `relations` (owns/supersedes/depends-on/blocked-by/references) sits ON TOP OF
- * consolidated memories. The hard rule: the graph NEVER indexes the raw layer - every
- * entity and relation references a memory whose `kind IN ('distilled','superseded')`,
- * never `kind='raw'`. Enforced at the DB level (CHECK on source_kind/kind + BEFORE
- * INSERT and BEFORE UPDATE triggers that tie source_kind/kind to the FK'd memory's
- * actual kind and enforce tenant-match - relations also reject cross-tenant edges), so
- * the forbidden state is unrepresentable regardless of code path. These helpers
- * surface the same guard as clear throws BEFORE hitting the trigger backstop.
- */
-import { type GraphTxDb, type SourceObjectType, type Entity, type Relation, type GraphQueueItem, type InsertEntityOpts, type InsertRelationOpts, type UpdateEntityOpts } from './types.js';
+import type { DatabaseSyncLike } from '../db/index.js';
 import type { GraphOp } from './delta.js';
-/**
- * Insert a graph entity extracted from a consolidated memory. Throws if the source
- * memory is missing / cross-tenant / raw (the DB trigger is the backstop).
- */
-export declare function insertEntity(hippoRoot: string, tenantId: string, opts: InsertEntityOpts, txDb?: GraphTxDb): Entity;
-/** Renames an entity or moves its memory provenance in place, keeping id and created_at; null when the row is gone.
- *  A delete plus an insert would cascade away every relation that points at it. */
-export declare function updateEntity(hippoRoot: string, tenantId: string, id: number, opts: UpdateEntityOpts, txDb?: GraphTxDb): Entity | null;
-/**
- * Insert a graph relation between two entities, sourced from a consolidated memory.
- * Both entities must exist in the same tenant; the source memory must be consolidated.
- */
-export declare function insertRelation(hippoRoot: string, tenantId: string, opts: InsertRelationOpts, txDb?: GraphTxDb): Relation;
-/**
- * Enqueue a consolidated memory for later graph extraction. Rejects a raw / missing /
- * cross-tenant memory (the DB trigger is the backstop).
- */
-export declare function enqueueExtraction(hippoRoot: string, tenantId: string, memoryId: string): GraphQueueItem;
-/**
- * Mark a queue item terminal (processed | skipped). Only `status`/`processed_at`
- * change, so the consolidated-source guard trigger (which fires on
- * memory_id/kind/tenant_id changes) is not involved. CAS on the current status to a
- * non-terminal 'pending'.
- */
-export declare function markExtractionProcessed(hippoRoot: string, tenantId: string, id: number, status?: 'processed' | 'skipped'): GraphQueueItem;
 export interface ApplyGraphOpsResult {
     readonly next: number;
     readonly skipped: number;
 }
-/** Applies `ops` from index `from` on the caller's open transaction and stops at the first op boundary past `opts.holdMs`.
+/** Applies `ops` from index `opts.from` on the caller's open transaction and stops at the first op boundary past `opts.holdMs`.
  *  Returns where the next chunk starts and how many ops were skipped as stale. */
-export declare function applyGraphOps(db: GraphTxDb, hippoRoot: string, tenantId: string, ops: readonly GraphOp[], from: number, opts: {
+export declare function applyGraphOps(db: DatabaseSyncLike, hippoRoot: string, tenantId: string, ops: readonly GraphOp[], opts: {
+    readonly from: number;
     readonly holdMs: number;
     readonly clock?: () => number;
 }): ApplyGraphOpsResult;
-/** Runs one tenant's graph writes in `fn` on `txDb` under one BEGIN IMMEDIATE, so two rebuilds serialize instead of
- *  interleaving and a throw rolls back the whole chunk. The sole sanctioned place to wrap graph writes in a transaction. */
-export declare function runGraphRebuildTransaction<T>(hippoRoot: string, tenantId: string, fn: (txDb: GraphTxDb) => T, opts?: {
-    busyWaitMs?: number;
-}): T;
-/**
- * Fail-soft producer hook: mark a tenant dirty for graph re-extraction by
- * enqueuing its consolidated mirror memory. NEVER throws into the caller — a
- * graph-dirty signal failing must not abort a core object write. Graph staleness is
- * recoverable (next sleep / manual `graph extract`); a broken `hippo decide` is
- * not. Called POST-COMMIT from the graph-source save/close mutations of
- * decision, policy, customer_note and project_brief. A null memoryId (a
- * forgotten mirror) is a no-op.
- */
-export declare function markGraphDirty(hippoRoot: string, tenantId: string, memoryId: string | null): void;
-/**
- * Remove the graph rows sourced from one first-class object, by its (type, id). Used when a
- * MIRRORLESS object is closed: it has no mirror memory, so `markGraphDirty` cannot
- * enqueue a rebuild (the queue is memory-keyed). Closing must still drop the object's
- * now-stale entity + edges from the graph, so we remove them directly here. Fail-soft
- * like `markGraphDirty` (never throws into the object close caller; graph staleness is
- * recoverable). Deleting the entity cascade-deletes any relation where it is an endpoint
- * (relations FK entities ON DELETE CASCADE); the explicit relations DELETE also covers a
- * relation whose OWN provenance is this object (defensive — every such edge has the object
- * as an endpoint today, so the cascade already covers it). DELETE fires no BEFORE
- * INSERT/UPDATE guard trigger.
- */
-export declare function removeGraphEntitiesForObject(hippoRoot: string, tenantId: string, sourceObjectType: SourceObjectType, sourceObjectId: number): void;
-/**
- * Mark every pending queue item for a tenant with `id <= maxId` processed, in
- * one UPDATE. Status/processed_at only, so the consolidated-source guard trigger
- * is not involved (same as markExtractionProcessed). Returns the count marked.
- * The `<= maxId` watermark excludes items enqueued after the drain snapshot.
- */
-export declare function markPendingProcessedUpTo(hippoRoot: string, tenantId: string, maxId: number): number;
 //# sourceMappingURL=write.d.ts.map