hippo-memory 1.69.0 → 1.70.0

package/dist/store/graph-queue.js

@@ -0,0 +1,101 @@
+// The graph extraction queue: the consolidated memories that wait for a graph rebuild, and the watermark the sleep drain marks them by.
+import { openHippoDb, closeHippoDb } from '../db/index.js';
+import { assertTenantId } from './tenant.js';
+import { errorMessage, log } from '../util/log.js';
+import { rowToQueueItem, QUEUE_COLS } from './graph-rows.js';
+import { resolveConsolidatedSource } from './graph-writes.js';
+/**
+ * Enqueue a consolidated memory for later graph extraction. Rejects a raw / missing /
+ * cross-tenant memory (the DB trigger is the backstop).
+ */
+function enqueueExtraction(hippoRoot, tenantId, memoryId) {
+    assertTenantId('enqueueExtraction', tenantId);
+    const now = new Date().toISOString();
+    const db = openHippoDb(hippoRoot);
+    try {
+        // enqueue is memory-keyed (no source object), so a missing memory still throws (correct -
+        // you cannot enqueue a forgotten mirror); memoryId is non-null here by construction.
+        const { sourceKind } = resolveConsolidatedSource(db, tenantId, memoryId, null, 'enqueueExtraction');
+        const result = db.prepare(`
+      INSERT INTO graph_extraction_queue(tenant_id, memory_id, kind, status, enqueued_at, processed_at)
+      VALUES (?, ?, ?, 'pending', ?, NULL)
+    `).run(tenantId, memoryId, sourceKind, now);
+        const id = Number(result.lastInsertRowid ?? 0);
+        // SAFETY: row's shape matches the columns named in QUEUE_COLS above.
+        const row = db.prepare(`SELECT ${QUEUE_COLS} FROM graph_extraction_queue WHERE id = ?`).get(id);
+        if (!row)
+            throw new Error('enqueueExtraction: failed to reload queue item');
+        return rowToQueueItem(row);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * 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 function markGraphDirty(hippoRoot, tenantId, memoryId) {
+    if (!memoryId)
+        return;
+    try {
+        enqueueExtraction(hippoRoot, tenantId, memoryId);
+    }
+    catch (err) {
+        // Logged (warn) so a SYSTEMATIC enqueue failure surfaces to operators, but
+        // swallowed so the already-committed object write is never rolled back.
+        log.warn(`markGraphDirty: enqueue failed for tenant=${tenantId} memory=${memoryId}: ${errorMessage(err)}`);
+    }
+}
+/**
+ * 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. Returns the count marked.
+ * The `<= maxId` watermark excludes items enqueued after the drain snapshot.
+ */
+export function markPendingProcessedUpTo(hippoRoot, tenantId, maxId) {
+    assertTenantId('markPendingProcessedUpTo', tenantId);
+    const now = new Date().toISOString();
+    const db = openHippoDb(hippoRoot);
+    try {
+        const res = db.prepare(`
+      UPDATE graph_extraction_queue
+      SET status = 'processed', processed_at = ?
+      WHERE tenant_id = ? AND status = 'pending' AND id <= ?
+    `).run(now, tenantId, maxId);
+        return Number(res.changes ?? 0);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * 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 function loadPendingExtractionTenants(hippoRoot) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        // SAFETY: rows' shape matches the two aliased columns (tenant_id, max_id)
+        // named in the SELECT above.
+        const rows = db.prepare(`
+      SELECT tenant_id AS tenant_id, MAX(id) AS max_id
+      FROM graph_extraction_queue
+      WHERE status = 'pending'
+      GROUP BY tenant_id
+    `).all();
+        return rows.map((r) => ({ tenantId: r.tenant_id, maxPendingId: Number(r.max_id) }));
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=graph-queue.js.map

package/dist/{graph/read.d.ts → store/graph-reads.d.ts}

@@ -1,33 +1,30 @@
-import { type GraphTxDb, type EntityType, type GraphQueueStatus, type Entity, type Relation, type GraphQueueItem } from './types.js';
-export declare function loadEntityById(hippoRoot: string, tenantId: string, id: number): Entity | null;
+import { type DatabaseSyncLike } from '../db/index.js';
+import { type EntityType, type Entity, type Relation, type StoredGraph } from './graph-rows.js';
 /** 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[];
+}, txDb?: DatabaseSyncLike): Entity[];
 export declare function loadEntities(hippoRoot: string, tenantId: string, opts?: {
     entityType?: EntityType;
     limit?: number;
-}, txDb?: GraphTxDb): Entity[];
+}, txDb?: DatabaseSyncLike): Entity[];
 export declare function loadRelations(hippoRoot: string, tenantId: string, opts?: {
     fromEntityId?: number;
     limit?: number;
-}, txDb?: GraphTxDb): Relation[];
-/**
- * Map consolidated source memory ids -> their graph entities. The SEED step of
- * multi-hop recall (recall result memory ids -> entities to traverse from). Tenant-
- * scoped, read-only; chunks the IN-list under the SQLite variable cap.
- */
-export declare function loadEntitiesByMemoryId(hippoRoot: string, tenantId: string, memoryIds: string[]): Entity[];
+}, txDb?: DatabaseSyncLike): Relation[];
+/** Chunk size for IN-list queries: well under SQLite's 999-bound-variable default
+ *  (leaves headroom for the tenant_id param + the doubled list in neighbour lookups). */
+export declare const IN_LIST_CHUNK = 400;
 /**
  * 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[], txDb?: GraphTxDb): Entity[];
+export declare function loadEntitiesByIds(hippoRoot: string, tenantId: string, ids: number[], txDb?: DatabaseSyncLike): Entity[];
 /**
- * All relations touching ANY of `entityIds` in EITHER direction (from OR to) — the
+ * All relations touching ANY of `entityIds` in EITHER direction (from OR to): the
  * per-hop neighbour query for multi-hop traversal. ONE query for the whole frontier
  * (not one per node): this is the bidirectional read `loadRelations` (from-only) lacks,
  * and avoids an N+1 across BFS frontier nodes. `limit` caps rows for the frontier and
@@ -35,39 +32,34 @@ export declare function loadEntitiesByIds(hippoRoot: string, tenantId: string, i
  */
 export declare function loadNeighborRelations(hippoRoot: string, tenantId: string, entityIds: number[], opts?: {
     limit?: number;
-}, txDb?: GraphTxDb): Relation[];
+}, txDb?: DatabaseSyncLike): 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
+ * 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[];
+}, txDb?: DatabaseSyncLike): Relation[];
+/**
+ * Map consolidated source memory ids -> their graph entities. The SEED step of
+ * multi-hop recall (recall result memory ids -> entities to traverse from). Tenant-
+ * scoped, read-only; chunks the IN-list under the SQLite variable cap.
+ */
+export declare function loadEntitiesByMemoryId(hippoRoot: string, tenantId: string, memoryIds: string[]): Entity[];
+/** The stored rows a rebuild diffs against, read on the caller's handle so the diff and the apply can share one write lock. */
+export declare function storedGraphOn(db: DatabaseSyncLike, tenantId: string, memoryIds: readonly string[]): StoredGraph;
+/** storedGraphOn on its own connection, outside any write lock. */
+export declare function loadStoredGraph(hippoRoot: string, tenantId: string, memoryIds: readonly string[]): StoredGraph;
 /**
  * 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
+ * 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;
-export declare function loadExtractionQueue(hippoRoot: string, tenantId: string, opts?: {
-    status?: GraphQueueStatus;
-    limit?: number;
-}): GraphQueueItem[];
-/**
- * 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;
-}[];
-//# sourceMappingURL=read.d.ts.map
+export declare function withGraphReadSnapshot<T>(hippoRoot: string, fn: (txDb: DatabaseSyncLike) => T): T;
+//# sourceMappingURL=graph-reads.d.ts.map

package/dist/{graph/read.js → store/graph-reads.js}

@@ -1,27 +1,16 @@
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { assertTenantId } from '../tenant.js';
-import { GRAPH_ENTITY_TYPES, VALID_QUEUE_STATES } from './types.js';
-import { rowToEntity, rowToRelation, rowToQueueItem, ENTITY_COLS, RELATION_COLS, QUEUE_COLS } from './rows.js';
-export function loadEntityById(hippoRoot, tenantId, id) {
-    assertTenantId('loadEntityById', tenantId);
-    const db = openHippoDb(hippoRoot);
-    try {
-        // SAFETY: row's shape matches the columns named in ENTITY_COLS above.
-        const row = db.prepare(`SELECT ${ENTITY_COLS} FROM entities WHERE id = ? AND tenant_id = ?`)
-            .get(id, tenantId);
-        return row ? rowToEntity(row) : null;
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
+// The graph reads a view and a traversal share. Each opens hippo.db itself unless the caller hands it the handle its snapshot runs on.
+import { openHippoDb, closeHippoDb, withReadSnapshot } from '../db/index.js';
+import { assertTenantId } from './tenant.js';
+import { GRAPH_ENTITY_TYPES, rowToEntity, rowToRelation, ENTITY_COLS, RELATION_COLS } from './graph-rows.js';
+const DEFAULT_GRAPH_PAGE_SIZE = 100;
+const DEFAULT_GRAPH_SCAN_LIMIT = 1000;
 /** 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 function loadEntitiesByName(hippoRoot, tenantId, name, opts = {}, txDb) {
     assertTenantId('loadEntitiesByName', tenantId);
-    const limit = opts.limit ?? 100;
+    const limit = opts.limit ?? DEFAULT_GRAPH_PAGE_SIZE;
     if (!Number.isInteger(limit) || limit < 0) {
         throw new Error(`loadEntitiesByName: limit must be a non-negative integer; got ${limit}`);
     }
@@ -42,7 +31,7 @@ export function loadEntitiesByName(hippoRoot, tenantId, name, opts = {}, txDb) {
 }
 export function loadEntities(hippoRoot, tenantId, opts = {}, txDb) {
     assertTenantId('loadEntities', tenantId);
-    const limit = opts.limit ?? 100;
+    const limit = opts.limit ?? DEFAULT_GRAPH_PAGE_SIZE;
     if (opts.entityType && !GRAPH_ENTITY_TYPES.has(opts.entityType)) {
         throw new Error(`loadEntities: entityType must be one of ${Array.from(GRAPH_ENTITY_TYPES).join('|')}; got ${opts.entityType}`);
     }
@@ -72,7 +61,7 @@ export function loadEntities(hippoRoot, tenantId, opts = {}, txDb) {
 }
 export function loadRelations(hippoRoot, tenantId, opts = {}, txDb) {
     assertTenantId('loadRelations', tenantId);
-    const limit = opts.limit ?? 100;
+    const limit = opts.limit ?? DEFAULT_GRAPH_PAGE_SIZE;
     const ownDb = txDb ? null : openHippoDb(hippoRoot);
     const db = txDb ?? ownDb;
     try {
@@ -97,43 +86,9 @@ export function loadRelations(hippoRoot, tenantId, opts = {}, txDb) {
             closeHippoDb(ownDb);
     }
 }
-// ---------------------------------------------------------------------------
-// Multi-hop recall read helpers (SELECT-only; the check-graph-writes lint
-// permits these here and in the read-only consumer src/graph-recall.ts).
-// ---------------------------------------------------------------------------
 /** Chunk size for IN-list queries: well under SQLite's 999-bound-variable default
  *  (leaves headroom for the tenant_id param + the doubled list in neighbour lookups). */
-const IN_LIST_CHUNK = 400;
-/**
- * Map consolidated source memory ids -> their graph entities. The SEED step of
- * multi-hop recall (recall result memory ids -> entities to traverse from). Tenant-
- * scoped, read-only; chunks the IN-list under the SQLite variable cap.
- */
-export function loadEntitiesByMemoryId(hippoRoot, tenantId, memoryIds) {
-    assertTenantId('loadEntitiesByMemoryId', tenantId);
-    if (memoryIds.length === 0)
-        return [];
-    const db = openHippoDb(hippoRoot);
-    try {
-        const out = [];
-        for (let i = 0; i < memoryIds.length; i += IN_LIST_CHUNK) {
-            const slice = memoryIds.slice(i, i + IN_LIST_CHUNK);
-            const ph = slice.map(() => '?').join(',');
-            // id ASC so chunk-local scan order never decides ties (id is an autoincrement PK).
-            // SAFETY: rows' shape matches the columns named in ENTITY_COLS above.
-            const rows = db.prepare(`
-        SELECT ${ENTITY_COLS} FROM entities
-        WHERE tenant_id = ? AND memory_id IN (${ph})
-        ORDER BY id ASC
-      `).all(tenantId, ...slice);
-            out.push(...rows.map(rowToEntity));
-        }
-        return out;
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
+export const IN_LIST_CHUNK = 400;
 /**
  * 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.
@@ -164,7 +119,7 @@ export function loadEntitiesByIds(hippoRoot, tenantId, ids, txDb) {
     }
 }
 /**
- * All relations touching ANY of `entityIds` in EITHER direction (from OR to) — the
+ * All relations touching ANY of `entityIds` in EITHER direction (from OR to): the
  * per-hop neighbour query for multi-hop traversal. ONE query for the whole frontier
  * (not one per node): this is the bidirectional read `loadRelations` (from-only) lacks,
  * and avoids an N+1 across BFS frontier nodes. `limit` caps rows for the frontier and
@@ -174,7 +129,7 @@ export function loadNeighborRelations(hippoRoot, tenantId, entityIds, opts = {},
     assertTenantId('loadNeighborRelations', tenantId);
     if (entityIds.length === 0)
         return [];
-    const limit = opts.limit ?? 1000;
+    const limit = opts.limit ?? DEFAULT_GRAPH_SCAN_LIMIT;
     if (!Number.isInteger(limit) || limit < 0) {
         throw new Error(`loadNeighborRelations: limit must be a non-negative integer; got ${limit}`);
     }
@@ -211,14 +166,14 @@ export function loadNeighborRelations(hippoRoot, tenantId, entityIds, opts = {},
  * 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
+ * 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 function loadRelationsAmong(hippoRoot, tenantId, entityIds, opts = {}, txDb) {
     assertTenantId('loadRelationsAmong', tenantId);
     if (entityIds.length === 0)
         return [];
-    const limit = opts.limit ?? 1000;
+    const limit = opts.limit ?? DEFAULT_GRAPH_SCAN_LIMIT;
     if (!Number.isInteger(limit) || limit < 0) {
         throw new Error(`loadRelationsAmong: limit must be a non-negative integer; got ${limit}`);
     }
@@ -241,84 +196,77 @@ export function loadRelationsAmong(hippoRoot, tenantId, entityIds, opts = {}, tx
     }
 }
 /**
- * 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.
+ * Map consolidated source memory ids -> their graph entities. The SEED step of
+ * multi-hop recall (recall result memory ids -> entities to traverse from). Tenant-
+ * scoped, read-only; chunks the IN-list under the SQLite variable cap.
  */
-export function withGraphReadSnapshot(hippoRoot, fn) {
+export function loadEntitiesByMemoryId(hippoRoot, tenantId, memoryIds) {
+    assertTenantId('loadEntitiesByMemoryId', tenantId);
+    if (memoryIds.length === 0)
+        return [];
     const db = openHippoDb(hippoRoot);
     try {
-        db.exec('BEGIN');
-        try {
-            const out = fn(db);
-            db.exec('COMMIT');
-            return out;
-        }
-        catch (e) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* ignore */ }
-            throw e;
+        const out = [];
+        for (let i = 0; i < memoryIds.length; i += IN_LIST_CHUNK) {
+            const slice = memoryIds.slice(i, i + IN_LIST_CHUNK);
+            const ph = slice.map(() => '?').join(',');
+            // id ASC so chunk-local scan order never decides ties (id is an autoincrement PK).
+            // SAFETY: rows' shape matches the columns named in ENTITY_COLS above.
+            const rows = db.prepare(`
+        SELECT ${ENTITY_COLS} FROM entities
+        WHERE tenant_id = ? AND memory_id IN (${ph})
+        ORDER BY id ASC
+      `).all(tenantId, ...slice);
+            out.push(...rows.map(rowToEntity));
         }
+        return out;
     }
     finally {
         closeHippoDb(db);
     }
 }
-export function loadExtractionQueue(hippoRoot, tenantId, opts = {}) {
-    assertTenantId('loadExtractionQueue', tenantId);
-    const limit = opts.limit ?? 100;
-    if (opts.status && !VALID_QUEUE_STATES.has(opts.status)) {
-        throw new Error(`loadExtractionQueue: status must be one of ${Array.from(VALID_QUEUE_STATES).join('|')}; got ${opts.status}`);
-    }
+/** The stored rows a rebuild diffs against, read on the caller's handle so the diff and the apply can share one write lock. */
+export function storedGraphOn(db, tenantId, memoryIds) {
+    const kinds = memoryKindsOn(db, memoryIds);
+    // SAFETY: the SELECT names exactly the columns of StoredEntity.
+    const entities = db.prepare(`SELECT id, entity_type, name, memory_id, source_kind, source_object_type, source_object_id FROM entities WHERE tenant_id = ? ORDER BY id`).all(tenantId);
+    // SAFETY: the SELECT names exactly the columns of StoredRelation.
+    const relations = db.prepare(`SELECT id, from_entity_id, to_entity_id, rel_type, memory_id, source_kind, source_object_type, source_object_id FROM relations WHERE tenant_id = ? ORDER BY id`).all(tenantId);
+    return { kinds, entities, relations };
+}
+function memoryKindsOn(db, memoryIds) {
+    if (memoryIds.length === 0)
+        return new Map();
+    // SAFETY: the SELECT names exactly the two columns of the row type.
+    const rows = db.prepare(`SELECT id, kind FROM memories WHERE id IN (SELECT value FROM json_each(?))`)
+        .all(JSON.stringify(memoryIds));
+    return new Map(rows.map((row) => [row.id, row.kind]));
+}
+/** storedGraphOn on its own connection, outside any write lock. */
+export function loadStoredGraph(hippoRoot, tenantId, memoryIds) {
     const db = openHippoDb(hippoRoot);
     try {
-        const clauses = ['tenant_id = ?'];
-        const params = [tenantId];
-        if (opts.status) {
-            clauses.push('status = ?');
-            params.push(opts.status);
-        }
-        params.push(limit);
-        // SAFETY: rows' shape matches the columns named in QUEUE_COLS above.
-        const rows = db.prepare(`
-      SELECT ${QUEUE_COLS} FROM graph_extraction_queue
-      WHERE ${clauses.join(' AND ')}
-      ORDER BY enqueued_at ASC, id ASC
-      LIMIT ?
-    `).all(...params);
-        return rows.map(rowToQueueItem);
+        return storedGraphOn(db, tenantId, memoryIds);
     }
     finally {
         closeHippoDb(db);
     }
 }
 /**
- * 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).
+ * 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 function loadPendingExtractionTenants(hippoRoot) {
+export function withGraphReadSnapshot(hippoRoot, fn) {
     const db = openHippoDb(hippoRoot);
     try {
-        // SAFETY: rows' shape matches the two aliased columns (tenant_id, max_id)
-        // named in the SELECT above.
-        const rows = db.prepare(`
-      SELECT tenant_id AS tenant_id, MAX(id) AS max_id
-      FROM graph_extraction_queue
-      WHERE status = 'pending'
-      GROUP BY tenant_id
-    `).all();
-        return rows.map((r) => ({ tenantId: r.tenant_id, maxPendingId: Number(r.max_id) }));
+        return withReadSnapshot(db, () => fn(db));
     }
     finally {
         closeHippoDb(db);
     }
 }
-//# sourceMappingURL=read.js.map
+//# sourceMappingURL=graph-reads.js.map

package/dist/{graph/types.d.ts → store/graph-rows.d.ts}

@@ -1,16 +1,11 @@
-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';
 /** The consolidated source kinds the graph is permitted to index (never 'raw'). */
 export type SourceKind = 'distilled' | 'superseded';
 /** The authoritative first-class object types a graph row may be anchored to (the object
  *  provenance path, alongside the memory path). Maps to source_object_type. */
 export type SourceObjectType = 'decision' | 'policy' | 'customer' | 'project';
+export declare const GRAPH_ENTITY_TYPES: ReadonlySet<EntityType>;
 /** A soft (type,id) pointer to the authoritative object row a graph row descends from.
  *  Survives a mirror memory forget/prune (memory_id may go NULL); the rebuild
  *  re-validates it (it is not a hard FK). */
@@ -18,8 +13,8 @@ export interface SourceObjectRef {
     type: SourceObjectType;
     id: number;
 }
-export declare const GRAPH_ENTITY_TYPES: ReadonlySet<EntityType>;
 export declare const GRAPH_RELATION_TYPES: ReadonlySet<RelationType>;
+export type GraphQueueStatus = 'pending' | 'processed' | 'skipped';
 export declare const VALID_QUEUE_STATES: ReadonlySet<GraphQueueStatus>;
 export declare const MAX_ENTITY_NAME_LEN = 512;
 export interface Entity {
@@ -51,6 +46,33 @@ export interface Relation {
     sourceObjectId?: number;
     createdAt: string;
 }
+export interface EntityRow {
+    id: number;
+    tenant_id: string;
+    entity_type: string;
+    name: string;
+    memory_id: string | null;
+    source_kind: string;
+    source_object_type: string | null;
+    source_object_id: number | null;
+    created_at: string;
+}
+export interface RelationRow {
+    id: number;
+    tenant_id: string;
+    from_entity_id: number;
+    to_entity_id: number;
+    rel_type: string;
+    memory_id: string | null;
+    source_kind: string;
+    source_object_type: string | null;
+    source_object_id: number | null;
+    created_at: string;
+}
+export declare function rowToEntity(row: EntityRow): Entity;
+export declare function rowToRelation(row: RelationRow): Relation;
+export declare const ENTITY_COLS = "id, tenant_id, entity_type, name, memory_id, source_kind, source_object_type, source_object_id, created_at";
+export declare const RELATION_COLS = "id, tenant_id, from_entity_id, to_entity_id, rel_type, memory_id, source_kind, source_object_type, source_object_id, created_at";
 export interface GraphQueueItem {
     id: number;
     tenantId: string;
@@ -60,6 +82,17 @@ export interface GraphQueueItem {
     enqueuedAt: string;
     processedAt: string | null;
 }
+export interface QueueRow {
+    id: number;
+    tenant_id: string;
+    memory_id: string;
+    kind: string;
+    status: string;
+    enqueued_at: string;
+    processed_at: string | null;
+}
+export declare function rowToQueueItem(row: QueueRow): GraphQueueItem;
+export declare const QUEUE_COLS = "id, tenant_id, memory_id, kind, status, enqueued_at, processed_at";
 export interface InsertEntityOpts {
     entityType: EntityType;
     name: string;
@@ -85,4 +118,31 @@ export interface InsertRelationOpts {
     /** The authoritative object this relation descends from. */
     sourceObject?: SourceObjectRef;
 }
-//# sourceMappingURL=types.d.ts.map
+/** The entity columns a rebuild diffs against. */
+export interface StoredEntity {
+    id: number;
+    entity_type: string;
+    name: string;
+    memory_id: string | null;
+    source_kind: string;
+    source_object_type: string | null;
+    source_object_id: number | null;
+}
+/** The relation columns a rebuild diffs against. */
+export interface StoredRelation {
+    id: number;
+    from_entity_id: number;
+    to_entity_id: number;
+    rel_type: string;
+    memory_id: string | null;
+    source_kind: string;
+    source_object_type: string | null;
+    source_object_id: number | null;
+}
+/** One tenant's stored graph as a rebuild reads it, with the kind of each memory the desired rows name. */
+export interface StoredGraph {
+    readonly kinds: ReadonlyMap<string, string>;
+    readonly entities: readonly StoredEntity[];
+    readonly relations: readonly StoredRelation[];
+}
+//# sourceMappingURL=graph-rows.d.ts.map

package/dist/{graph/rows.js → store/graph-rows.js}

@@ -1,3 +1,14 @@
+// The graph's entity, relation and queue rows as hippo.db holds them, and the types every reader and writer of them shares.
+export const GRAPH_ENTITY_TYPES = new Set([
+    'person', 'project', 'customer', 'system', 'policy', 'decision',
+]);
+export const GRAPH_RELATION_TYPES = new Set([
+    'owns', 'supersedes', 'depends-on', 'blocked-by', 'references',
+]);
+export const VALID_QUEUE_STATES = new Set([
+    'pending', 'processed', 'skipped',
+]);
+export const MAX_ENTITY_NAME_LEN = 512;
 export function rowToEntity(row) {
     // SAFETY: entity_type/source_kind/source_object_type are DB CHECK-constrained
     // (see db.ts CREATE TABLE entities) to exactly the EntityType/SourceKind/
@@ -31,6 +42,8 @@ export function rowToRelation(row) {
         createdAt: row.created_at,
     };
 }
+export const ENTITY_COLS = `id, tenant_id, entity_type, name, memory_id, source_kind, source_object_type, source_object_id, created_at`;
+export const RELATION_COLS = `id, tenant_id, from_entity_id, to_entity_id, rel_type, memory_id, source_kind, source_object_type, source_object_id, created_at`;
 export function rowToQueueItem(row) {
     // SAFETY: kind/status are DB CHECK-constrained (see db.ts CREATE TABLE
     // graph_extraction_queue) to exactly the SourceKind/GraphQueueStatus enum
@@ -45,7 +58,5 @@ export function rowToQueueItem(row) {
         processedAt: row.processed_at,
     };
 }
-export const ENTITY_COLS = `id, tenant_id, entity_type, name, memory_id, source_kind, source_object_type, source_object_id, created_at`;
-export const RELATION_COLS = `id, tenant_id, from_entity_id, to_entity_id, rel_type, memory_id, source_kind, source_object_type, source_object_id, created_at`;
 export const QUEUE_COLS = `id, tenant_id, memory_id, kind, status, enqueued_at, processed_at`;
-//# sourceMappingURL=rows.js.map
+//# sourceMappingURL=graph-rows.js.map

package/dist/store/graph-view-rows.d.ts

@@ -0,0 +1,12 @@
+import type { DatabaseSyncLike } from '../db/index.js';
+import type { GraphRows } from './port.js';
+type CanRead = (scope: string | null) => boolean;
+export interface GraphViewSpec {
+    readonly entity?: string;
+    readonly limit: number;
+    readonly canRead?: CanRead;
+}
+/** What `GraphReads.graphRows` answers, read on `db`: the caller opens the one snapshot that keeps entity ids and relation ids from two different rebuilds apart. */
+export declare function graphViewRows(hippoRoot: string, db: DatabaseSyncLike, tenantId: string, spec: GraphViewSpec): GraphRows;
+export {};
+//# sourceMappingURL=graph-view-rows.d.ts.map