hippo-memory 1.69.0 → 1.71.0

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

@@ -1,27 +1,15 @@
-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);
-    }
-}
-/** 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. */
+// 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 { onHandle } from './open.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`, bounded by `limit` in SQL with a deterministic order, so graph-view focus finds `--entity NAME` directly
+ * without materializing every same-name row. */
 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 +30,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 +60,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,47 +85,10 @@ 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);
-    }
-}
-/**
- * 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 const IN_LIST_CHUNK = 400;
+/** Load entities by primary id (the BFS-reached rows whose `memory_id` maps back to a recall result). Tenant-scoped, read-only. */
 export function loadEntitiesByIds(hippoRoot, tenantId, ids, txDb) {
     assertTenantId('loadEntitiesByIds', tenantId);
     if (ids.length === 0)
@@ -163,29 +114,21 @@ export function loadEntitiesByIds(hippoRoot, tenantId, ids, txDb) {
             closeHippoDb(ownDb);
     }
 }
-/**
- * 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
- * must be a non-negative integer (the raw `LIMIT ?` rejects a fractional value).
- */
+/** All relations touching ANY of `entityIds` in EITHER direction: the per-hop neighbour query for multi-hop traversal, one query for the whole frontier
+ * (no N+1). `limit` caps rows and must be a non-negative integer (raw `LIMIT ?` rejects a fraction). */
 export function loadNeighborRelations(hippoRoot, tenantId, entityIds, opts = {}, txDb) {
     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}`);
     }
     const ownDb = txDb ? null : openHippoDb(hippoRoot);
     const db = txDb ?? ownDb;
     try {
-        // `limit` is applied PER CHUNK; a frontier spanning >IN_LIST_CHUNK ids could return
-        // up to limit*chunks rows before the by-id dedup below. Harmless for multi-hop recall (the
-        // frontier is bounded by maxNeighbors <= 200 << IN_LIST_CHUNK, so a single chunk,
-        // and the BFS re-enforces the per-hop fanout cap), but note the semantics if a
-        // tighter total cap is ever needed.
+        // `limit` applies PER CHUNK, so a frontier over IN_LIST_CHUNK ids could return limit*chunks rows before the dedup below;
+        // harmless today (frontier <= maxNeighbors 200, one chunk, BFS re-enforces the fanout cap).
         const byId = new Map();
         for (let i = 0; i < entityIds.length; i += IN_LIST_CHUNK) {
             const slice = entityIds.slice(i, i + IN_LIST_CHUNK);
@@ -207,18 +150,13 @@ export function loadNeighborRelations(hippoRoot, tenantId, entityIds, opts = {},
             closeHippoDb(ownDb);
     }
 }
-/**
- * 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.
- */
+/** Relations with BOTH endpoints in `entityIds` (edges AMONG the set), for the graph-view focus subgraph; `LIMIT` caps only intra-union edges,
+ * so no out-of-union row evicts a valid one. The caller bounds `entityIds` (<= 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}`);
     }
@@ -240,85 +178,57 @@ export function loadRelationsAmong(hippoRoot, tenantId, entityIds, opts = {}, tx
             closeHippoDb(ownDb);
     }
 }
-/**
- * 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 withGraphReadSnapshot(hippoRoot, fn) {
-    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;
+/** Map consolidated source memory ids to their graph entities: the SEED step of multi-hop recall. 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 [];
+    return onHandle(hippoRoot, (db) => {
+        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));
         }
-    }
-    finally {
-        closeHippoDb(db);
-    }
+        return out;
+    });
 }
-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}`);
-    }
-    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);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+/** 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 };
 }
-/**
- * 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);
-    }
+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) {
+    return onHandle(hippoRoot, (db) => {
+        return storedGraphOn(db, tenantId, memoryIds);
+    });
+}
+/** Run `fn` in ONE read transaction (a single WAL snapshot) so every `load*` read via `txDb` sees a consistent view
+ * even if a rebuild commits concurrently (it clears and reinserts entities, so separate reads could mix old entity ids with new relation ids). */
+export function withGraphReadSnapshot(hippoRoot, fn) {
+    return onHandle(hippoRoot, (db) => {
+        return withReadSnapshot(db, () => fn(db));
+    });
 }
-//# sourceMappingURL=read.js.map
+//# sourceMappingURL=graph-reads.js.map

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

@@ -1,25 +1,19 @@
-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';
-/** 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). */
+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 forget/prune
+ * (memory_id may go NULL) and is re-validated by the rebuild, not a hard FK. */
 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 {
@@ -27,9 +21,7 @@ export interface Entity {
     tenantId: string;
     entityType: EntityType;
     name: string;
-    /** The consolidated source memory this entity was extracted from. NULL once the
-     *  mirror is forgotten/pruned (ON DELETE SET NULL) - the entity then survives via
-     *  its source_object provenance. */
+    /** The consolidated source memory this entity came from; NULL once the mirror is forgotten/pruned (ON DELETE SET NULL), then provenance is source_object. */
     memoryId: string | null;
     sourceKind: SourceKind;
     /** The authoritative object this entity is anchored to (object-provenance path).
@@ -51,6 +43,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 +79,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 +115,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,7 +1,17 @@
+// 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/
-    // SourceObjectType enum values, so the row's column values match those types.
+    // SAFETY: entity_type/source_kind/source_object_type are DB CHECK-constrained to exactly the EntityType/SourceKind/SourceObjectType enum values,
+    // so the row's column values match those types.
     return {
         id: row.id,
         tenantId: row.tenant_id,
@@ -15,9 +25,8 @@ export function rowToEntity(row) {
     };
 }
 export function rowToRelation(row) {
-    // SAFETY: rel_type/source_kind/source_object_type are DB CHECK-constrained
-    // (see db.ts CREATE TABLE relations) to exactly the RelationType/SourceKind/
-    // SourceObjectType enum values, so the row's column values match those types.
+    // SAFETY: rel_type/source_kind/source_object_type are DB CHECK-constrained to exactly the RelationType/SourceKind/SourceObjectType enum values,
+    // so the row's column values match those types.
     return {
         id: row.id,
         tenantId: row.tenant_id,
@@ -31,10 +40,11 @@ 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
-    // values, so the row's column values match those types.
+    // SAFETY: kind/status are DB CHECK-constrained to exactly the SourceKind/GraphQueueStatus enum values,
+    // so the row's column values match those types.
     return {
         id: row.id,
         tenantId: row.tenant_id,
@@ -45,7 +55,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,13 @@
+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

package/dist/store/graph-view-rows.js

@@ -0,0 +1,68 @@
+import { IN_LIST_CHUNK, loadEntities, loadEntitiesByIds, loadEntitiesByName, loadNeighborRelations, loadRelations, loadRelationsAmong } from './graph-reads.js';
+/** 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 += IN_LIST_CHUNK) {
+        const slice = ids.slice(i, i + IN_LIST_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));
+}
+function wholeGraphRows({ hippoRoot, db, tenantId }, limit) {
+    const entities = loadEntities(hippoRoot, tenantId, { limit }, db);
+    const relations = loadRelations(hippoRoot, tenantId, { limit }, db);
+    return { entities, relations, truncated: entities.length >= limit || relations.length >= limit };
+}
+/** The named entities with their 1-hop neighbours and the edges among that union; null when the caller may read none of the named ones. */
+function focusRows({ hippoRoot, db, tenantId }, name, limit, canRead) {
+    // The name is queried directly, so it is found on a graph larger than `limit`; one name can map to many entities, so the matches are capped.
+    const named = loadEntitiesByName(hippoRoot, tenantId, name, { limit }, db);
+    // A hidden focus must not answer through its neighbours that the name exists.
+    const focus = readableOnly(db, tenantId, named, canRead);
+    if (focus.length === 0)
+        return null;
+    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);
+    const entities = loadEntitiesByIds(hippoRoot, tenantId, unionIds, db);
+    // Both endpoints in the set: neighbour-to-neighbour edges are included, and the LIMIT never drops one for an out-of-union row.
+    const relations = loadRelationsAmong(hippoRoot, tenantId, unionIds, { limit }, db);
+    const 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;
+    return { entities, relations, truncated };
+}
+/** 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 function graphViewRows(hippoRoot, db, tenantId, spec) {
+    const source = { hippoRoot, db, tenantId };
+    const raw = spec.entity !== undefined ? focusRows(source, spec.entity, spec.limit, spec.canRead) : wholeGraphRows(source, spec.limit);
+    if (raw === null)
+        return { entities: [], relations: [], truncated: false };
+    return {
+        entities: readableOnly(db, tenantId, raw.entities, spec.canRead),
+        relations: readableOnly(db, tenantId, raw.relations, spec.canRead),
+        truncated: raw.truncated,
+    };
+}
+//# sourceMappingURL=graph-view-rows.js.map

package/dist/store/graph-writes.d.ts

@@ -0,0 +1,33 @@
+import { type DatabaseSyncLike } from '../db/index.js';
+import { type EntityType, type RelationType, type SourceKind, type SourceObjectType, type SourceObjectRef, type Entity, type Relation, type InsertEntityOpts, type InsertRelationOpts, type UpdateEntityOpts } from './graph-rows.js';
+/** Resolve `source_kind` for a graph row from AT LEAST ONE valid provenance path, mirroring the DB trigger guard; raw is rejected.
+ * MEMORY path: exists, same-tenant, consolidated. OBJECT path (`memoryId` null): same-tenant, active|superseded, yields 'distilled'. All-null is rejected. */
+interface ResolvedGraphSource {
+    sourceKind: SourceKind;
+    memoryId: string | null;
+}
+export declare function resolveConsolidatedSource(db: DatabaseSyncLike, tenantId: string, memoryId: string | null, sourceObject: SourceObjectRef | null, label: string): ResolvedGraphSource;
+/** 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?: DatabaseSyncLike): 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?: DatabaseSyncLike): Entity | null;
+/** Insert a graph relation between two same-tenant entities, sourced from a consolidated memory. */
+export declare function insertRelation(hippoRoot: string, tenantId: string, opts: InsertRelationOpts, txDb?: DatabaseSyncLike): Relation;
+/** The source object still holds the loader's rule (active or superseded); a closed or gone one gets no new graph row. */
+export declare function objectInForce(db: DatabaseSyncLike, tenantId: string, ref: SourceObjectRef): boolean;
+/** The lowest-id entity of this type anchored to the source object, which is the row a rebuild keeps. */
+export declare function entityIdBySource(db: DatabaseSyncLike, tenantId: string, entityType: EntityType, sourceObject: SourceObjectRef): number | undefined;
+export declare function relationPresent(db: DatabaseSyncLike, tenantId: string, fromEntityId: number, toEntityId: number, relType: RelationType): boolean;
+export declare function deleteEntityRow(db: DatabaseSyncLike, tenantId: string, id: number): void;
+export declare function deleteRelationRow(db: DatabaseSyncLike, tenantId: string, id: number): void;
+/** 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: DatabaseSyncLike) => T, opts?: {
+    busyWaitMs?: number;
+}): T;
+/** Remove graph rows sourced from one MIRRORLESS object by (type, id) on close: with no mirror memory `markGraphDirty` cannot enqueue a rebuild.
+ * Fail-soft like `markGraphDirty`; the explicit relations DELETE also covers a relation whose OWN provenance is this object. */
+export declare function removeGraphEntitiesForObject(hippoRoot: string, tenantId: string, sourceObjectType: SourceObjectType, sourceObjectId: number): void;
+export {};
+//# sourceMappingURL=graph-writes.d.ts.map