hippo-memory 1.18.0 → 1.20.0

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

package/dist/graph-view.js.map

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

package/dist/graph.d.ts

@@ -17,6 +17,11 @@
  * enqueue-hook + E3.1 entity extraction will call. No operator surface (CLI/HTTP/SDK)
  * until E3.2 multi-hop recall.
  */
+import { openHippoDb } from './db.js';
+/** The DB connection handle `openHippoDb` returns. Threaded (optionally) through
+ *  the graph writers so `extractGraph` can run clear + all inserts in ONE
+ *  transaction — see `runGraphRebuildTransaction`. */
+export type GraphTxDb = ReturnType<typeof openHippoDb>;
 export type EntityType = 'person' | 'project' | 'customer' | 'system' | 'policy' | 'decision';
 export type RelationType = 'owns' | 'supersedes' | 'depends-on' | 'blocked-by' | 'references';
 export type GraphQueueStatus = 'pending' | 'processed' | 'skipped';
@@ -72,21 +77,28 @@ export interface InsertRelationOpts {
  * 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): Entity;
+export declare function insertEntity(hippoRoot: string, tenantId: string, opts: InsertEntityOpts, txDb?: GraphTxDb): Entity;
 /**
  * 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): Relation;
+export declare function insertRelation(hippoRoot: string, tenantId: string, opts: InsertRelationOpts, txDb?: GraphTxDb): Relation;
 export declare function loadEntityById(hippoRoot: string, tenantId: string, id: number): Entity | null;
+/** Entities with an exact `name` (read), bounded by `limit` in SQL with a
+ *  deterministic order. Lets the graph-view focus query find the `--entity NAME`
+ *  entity DIRECTLY (not from a globally-capped list) WITHOUT materializing every
+ *  same-name row when a name maps to many entities. */
+export declare function loadEntitiesByName(hippoRoot: string, tenantId: string, name: string, opts?: {
+    limit?: number;
+}, txDb?: GraphTxDb): Entity[];
 export declare function loadEntities(hippoRoot: string, tenantId: string, opts?: {
     entityType?: EntityType;
     limit?: number;
-}): Entity[];
+}, txDb?: GraphTxDb): Entity[];
 export declare function loadRelations(hippoRoot: string, tenantId: string, opts?: {
     fromEntityId?: number;
     limit?: number;
-}): Relation[];
+}, txDb?: GraphTxDb): Relation[];
 /**
  * Map consolidated source memory ids -> their graph entities. The SEED step of E3.2
  * multi-hop recall (recall result memory ids -> entities to traverse from). Tenant-
@@ -97,7 +109,7 @@ export declare function loadEntitiesByMemoryId(hippoRoot: string, tenantId: stri
  * Load entities by their primary ids. Resolves the entity rows reached during the BFS
  * (whose `memory_id` maps back to a recall result). Tenant-scoped, read-only.
  */
-export declare function loadEntitiesByIds(hippoRoot: string, tenantId: string, ids: number[]): Entity[];
+export declare function loadEntitiesByIds(hippoRoot: string, tenantId: string, ids: number[], txDb?: GraphTxDb): Entity[];
 /**
  * All relations touching ANY of `entityIds` in EITHER direction (from OR to) — the
  * per-hop neighbour query for E3.2 multi-hop traversal. ONE query for the whole frontier
@@ -107,7 +119,26 @@ export declare function loadEntitiesByIds(hippoRoot: string, tenantId: string, i
  */
 export declare function loadNeighborRelations(hippoRoot: string, tenantId: string, entityIds: number[], opts?: {
     limit?: number;
-}): Relation[];
+}, txDb?: GraphTxDb): Relation[];
+/**
+ * Relations with BOTH endpoints in `entityIds` (edges AMONG the set, not merely
+ * touching it). Read. Used by the graph-view focus subgraph so the displayed
+ * edges are exactly the intra-union edges: the `LIMIT` only caps genuinely-many
+ * intra-union edges — no out-of-union row can evict a valid in-set edge. The
+ * caller bounds `entityIds` (<= the view limit), so a single query is safe.
+ */
+export declare function loadRelationsAmong(hippoRoot: string, tenantId: string, entityIds: number[], opts?: {
+    limit?: number;
+}, txDb?: GraphTxDb): Relation[];
+/**
+ * Run `fn` inside ONE read transaction (a single WAL snapshot) so every graph read
+ * it performs — pass the supplied `txDb` to the `load*` functions — sees a consistent
+ * view, even if a `graph extract` / sleep-drain rebuild commits concurrently between
+ * reads (the rebuild clears + reinserts entities, so separate reads could otherwise
+ * mix old entity ids with new relation ids). Reads only; the connection is opened
+ * once and closed after.
+ */
+export declare function withGraphReadSnapshot<T>(hippoRoot: string, fn: (txDb: GraphTxDb) => T): T;
 /**
  * Enqueue a consolidated memory for later graph extraction. Rejects a raw / missing /
  * cross-tenant memory (the DB trigger is the backstop). The producer hook in
@@ -133,5 +164,43 @@ export declare function markExtractionProcessed(hippoRoot: string, tenantId: str
  * writer), so the E3.3 CI lint permits this `DELETE FROM entities`. Does NOT touch
  * graph_extraction_queue (the enqueue-hook's domain).
  */
-export declare function clearGraph(hippoRoot: string, tenantId: string): number;
+export declare function clearGraph(hippoRoot: string, tenantId: string, txDb?: GraphTxDb): number;
+/**
+ * Run a full graph rebuild for one tenant inside a single transaction. `clearGraph`
+ * + every `insertEntity`/`insertRelation` call made inside `fn` (passing the supplied
+ * `txDb`) share the one connection and its `BEGIN IMMEDIATE` write lock, so the
+ * rebuild is ATOMIC: two concurrent rebuilds serialize on the write lock (the second
+ * waits, then re-derives cleanly) instead of interleaving into duplicate rows, and a
+ * throw mid-rebuild ROLLS BACK the clear (no bricked/empty graph). The sole sanctioned
+ * place to wrap graph writes in a transaction.
+ */
+export declare function runGraphRebuildTransaction<T>(hippoRoot: string, tenantId: string, fn: (txDb: GraphTxDb) => T): 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 E2 write. Graph staleness is
+ * recoverable (next sleep / manual `graph extract`); a broken `hippo decide` is
+ * not. Called POST-COMMIT from the E2 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;
+/**
+ * The dirty tenants awaiting graph re-extraction, each with the MAX pending
+ * queue id at read time (a watermark). The sleep drain rebuilds each tenant's
+ * graph, then marks only items at or below the watermark processed, so items
+ * enqueued DURING the rebuild stay pending for the next sleep (no lost-update
+ * race). Host-wide read (the queue is per-tenant but sleep is cross-tenant).
+ */
+export declare function loadPendingExtractionTenants(hippoRoot: string): {
+    tenantId: string;
+    maxPendingId: number;
+}[];
+/**
+ * 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=graph.d.ts.map

package/dist/graph.d.ts.map

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