hippo-memory 1.69.0 → 1.71.0

package/dist/graph/view.js

@@ -0,0 +1,265 @@
+/** 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 { 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;
+/** 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 function buildGraphModel(hippoRoot, tenantId, opts = {}) {
+    const limit = opts.limit ?? DEFAULT_VIEW_LIMIT;
+    // 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 one model gives the same positions.
+ *  Non-finite coordinates are clamped to the viewport centre and all positions to the bounds. */
+export function layoutGraph(model, opts = {}) {
+    const width = opts.width ?? LAYOUT_W;
+    const height = opts.height ?? LAYOUT_H;
+    const iterations = opts.iterations ?? DEFAULT_LAYOUT_ITERATIONS;
+    const nodes = model.nodes;
+    const n = nodes.length;
+    if (n === 0)
+        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 }));
+        addRepulsion(nodes, pos, disp, k);
+        addAttraction(model.edges, idIndex, pos, disp, k);
+        const temp = Math.max(1, (width / 10) * (1 - iter / iterations));
+        applyDisplacement(nodes, pos, disp, temp, width, height);
+    }
+    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, zoom, click-to-highlight. It reads the inlined model via JSON.parse (never innerHTML)
+// and uses no template literals or `${}`, so it nests in this module's 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");
+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);
+        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('');
+}
+function renderNodeSvg(model, pos) {
+    return model.nodes
+        .map((node) => {
+        const p = pos.get(node.id);
+        if (!p)
+            return '';
+        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="${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.
+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))];
+    return types
+        .map((t) => `<span style="color:${nodeColor(t)}">●</span> ${escapeHtml(t)}`)
+        .join('  ');
+}
+/** 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 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">',
+        '<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: `text` nodes at the same deterministic layout positions, `edges[]` linking them by id. */
+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=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