hippo-memory 1.70.0 → 1.72.0

package/dist/store/graph-reads.js

@@ -1,13 +1,13 @@
 // 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 { DEFAULT_LIST_LIMIT } from '../util/limits.js';
 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_PAGE_SIZE = DEFAULT_LIST_LIMIT;
 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. */
+/** 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 ?? DEFAULT_GRAPH_PAGE_SIZE;
@@ -89,10 +89,7 @@ export function loadRelations(hippoRoot, tenantId, opts = {}, txDb) {
 /** 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 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.
- */
+/** 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)
@@ -118,13 +115,8 @@ 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)
@@ -136,11 +128,8 @@ export function loadNeighborRelations(hippoRoot, tenantId, entityIds, opts = {},
     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);
@@ -162,13 +151,8 @@ 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)
@@ -195,17 +179,13 @@ export function loadRelationsAmong(hippoRoot, tenantId, entityIds, opts = {}, tx
             closeHippoDb(ownDb);
     }
 }
-/**
- * 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.
- */
+/** 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 [];
-    const db = openHippoDb(hippoRoot);
-    try {
+    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);
@@ -220,10 +200,7 @@ export function loadEntitiesByMemoryId(hippoRoot, tenantId, memoryIds) {
             out.push(...rows.map(rowToEntity));
         }
         return out;
-    }
-    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) {
@@ -231,7 +208,8 @@ export function storedGraphOn(db, tenantId, 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);
+    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) {
@@ -244,29 +222,15 @@ function memoryKindsOn(db, memoryIds) {
 }
 /** storedGraphOn on its own connection, outside any write lock. */
 export function loadStoredGraph(hippoRoot, tenantId, memoryIds) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return storedGraphOn(db, tenantId, memoryIds);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
-/**
- * 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.
- */
+/** 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) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return withReadSnapshot(db, () => fn(db));
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 //# sourceMappingURL=graph-reads.js.map

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

@@ -6,9 +6,8 @@ export type SourceKind = 'distilled' | 'superseded';
  *  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). */
+/** 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;
@@ -22,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).

package/dist/store/graph-rows.js

@@ -10,9 +10,8 @@ export const VALID_QUEUE_STATES = new Set([
 ]);
 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,
@@ -26,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,
@@ -45,9 +43,8 @@ export function rowToRelation(row) {
 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,

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

@@ -6,7 +6,8 @@ export interface GraphViewSpec {
     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. */
+/** 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

@@ -52,7 +52,8 @@ function focusRows({ hippoRoot, db, tenantId }, name, limit, canRead) {
         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. */
+/** 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);

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

@@ -1,34 +1,19 @@
 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 the `source_kind` for a graph row from AT LEAST ONE valid provenance path,
- * with the no-raw invariant intact. The code-level mirror of the DB trigger guard (the
- * trigger is the unbypassable backstop). Two paths:
- *  - MEMORY path (`memoryId` not null): the memory must exist, be same-tenant, and be
- *    consolidated (distilled/superseded); raw is rejected. Returns its kind.
- *  - OBJECT path (`memoryId` null, `sourceObject` set): the object row must exist, be
- *    same-tenant, and have status active|superseded (4-way per object table). Objects are
- *    consolidated BY CONSTRUCTION, so this returns 'distilled'.
- * All-null (no memory AND no source object) is rejected.
- */
+/** 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.
+/** Insert a graph entity on the caller's handle; throws if the source memory is missing / cross-tenant / raw (the DB trigger is the backstop). */
+export declare function insertEntityRow(db: DatabaseSyncLike, tenantId: string, opts: InsertEntityOpts): Entity;
+/** Renames an entity or moves its memory provenance in place on the caller's handle, 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 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?: DatabaseSyncLike): Relation;
+export declare function updateEntityRow(db: DatabaseSyncLike, tenantId: string, id: number, opts: UpdateEntityOpts): Entity | null;
+/** Insert a graph relation between two same-tenant entities on the caller's handle, sourced from a consolidated memory. */
+export declare function insertRelationRow(db: DatabaseSyncLike, tenantId: string, opts: InsertRelationOpts): 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. */
@@ -41,18 +26,8 @@ export declare function deleteRelationRow(db: DatabaseSyncLike, tenantId: string
 export declare function runGraphRebuildTransaction<T>(hippoRoot: string, tenantId: string, fn: (txDb: DatabaseSyncLike) => T, opts?: {
     busyWaitMs?: number;
 }): T;
-/**
- * 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.
- */
+/** 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

package/dist/store/graph-writes.js

@@ -1,6 +1,7 @@
 // The writer of the entities and relations tables. Every row resolves a consolidated source first, never a raw memory;
 // the schema triggers are the backstop for a write that skips this module.
 import { openHippoDb, closeHippoDb, withWriteScope } from '../db/index.js';
+import { onHandle } from './open.js';
 import { assertTenantId } from './tenant.js';
 import { errorMessage, log } from '../util/log.js';
 import { GRAPH_ENTITY_TYPES, GRAPH_RELATION_TYPES, MAX_ENTITY_NAME_LEN, rowToEntity, rowToRelation, ENTITY_COLS, RELATION_COLS } from './graph-rows.js';
@@ -29,10 +30,8 @@ function checkSourceMemory(db, tenantId, memoryId, sourceObject, label) {
         // the SELECT above.
         const row = db.prepare(`SELECT kind, tenant_id FROM memories WHERE id = ?`).get(memoryId);
         if (!row) {
-            // Stale / forgotten mirror. Tolerate it IFF a valid source object provides provenance:
-            // graph-extract reads object rows then inserts, and a mirror forgotten/pruned in that window
-            // must NOT roll back the whole tenant rebuild - the active object survives mirror loss.
-            // Anchor to the object; drop the dead memory pointer.
+            // Stale/forgotten mirror: tolerate it IFF a valid source object gives provenance, so a mirror pruned mid graph-extract does not roll back the tenant
+            // rebuild; anchor to the object and drop the dead memory pointer.
             if (sourceObject == null) {
                 throw new Error(`${label}: source memory ${memoryId} not found`);
             }
@@ -54,18 +53,15 @@ function checkSourceMemory(db, tenantId, memoryId, sourceObject, label) {
     return { memKind, effectiveMemoryId };
 }
 function assertSourceObjectUsable(db, tenantId, sourceObject, label) {
-    // Validate the object pointer WHENEVER it is provided, not only when memory is null:
-    // a dual-set row whose object is wrong/closed/cross-tenant would become
-    // the active provenance after ON DELETE SET NULL and could then block the memory delete.
+    // Validate the object pointer WHENEVER provided: a dual-set row with a bad object would become the provenance after ON DELETE SET NULL and could block
+    // the memory delete.
     if (sourceObject != null) {
         const table = SOURCE_OBJECT_TABLE[sourceObject.type];
         if (!table) {
             throw new Error(`${label}: unsupported source_object_type '${sourceObject.type}'`);
         }
-        // `table` is a fixed value from the SOURCE_OBJECT_TABLE map (never user-supplied), so
-        // this string interpolation is safe; `id`/`tenant_id` stay parametrized.
-        // SAFETY: row's shape matches the single `status` column named in the
-        // SELECT above.
+        // `table` is a fixed SOURCE_OBJECT_TABLE value (never user-supplied), so interpolation is safe; `id`/`tenant_id` stay parametrized.
+        // SAFETY: row's shape matches the single `status` column named in the SELECT above.
         const row = db.prepare(`SELECT status FROM ${table} WHERE id = ? AND tenant_id = ?`).get(sourceObject.id, tenantId);
         if (!row) {
             throw new Error(`${label}: source ${sourceObject.type} ${sourceObject.id} not found for tenant ${tenantId}`);
@@ -75,11 +71,8 @@ function assertSourceObjectUsable(db, tenantId, sourceObject, label) {
         }
     }
 }
-/**
- * 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 function insertEntity(hippoRoot, tenantId, opts, txDb) {
+/** Insert a graph entity on the caller's handle; throws if the source memory is missing / cross-tenant / raw (the DB trigger is the backstop). */
+export function insertEntityRow(db, tenantId, opts) {
     assertTenantId('insertEntity', tenantId);
     if (!GRAPH_ENTITY_TYPES.has(opts.entityType)) {
         throw new Error(`insertEntity: entityType must be one of ${Array.from(GRAPH_ENTITY_TYPES).join('|')}; got ${opts.entityType}`);
@@ -88,25 +81,17 @@ export function insertEntity(hippoRoot, tenantId, opts, txDb) {
     const now = new Date().toISOString();
     const memoryId = opts.memoryId ?? null;
     const sourceObject = opts.sourceObject ?? null;
-    const ownDb = txDb ? null : openHippoDb(hippoRoot);
-    const db = txDb ?? ownDb;
-    try {
-        const { sourceKind, memoryId: effectiveMemoryId } = resolveConsolidatedSource(db, tenantId, memoryId, sourceObject, 'insertEntity');
-        const result = db.prepare(`
-      INSERT INTO entities(tenant_id, entity_type, name, memory_id, source_kind, source_object_type, source_object_id, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(tenantId, opts.entityType, name, effectiveMemoryId, sourceKind, sourceObject?.type ?? null, sourceObject?.id ?? null, now);
-        const id = Number(result.lastInsertRowid ?? 0);
-        // SAFETY: row's shape matches the columns named in ENTITY_COLS above.
-        const row = db.prepare(`SELECT ${ENTITY_COLS} FROM entities WHERE id = ?`).get(id);
-        if (!row)
-            throw new Error('insertEntity: failed to reload inserted entity');
-        return rowToEntity(row);
-    }
-    finally {
-        if (ownDb)
-            closeHippoDb(ownDb);
-    }
+    const { sourceKind, memoryId: effectiveMemoryId } = resolveConsolidatedSource(db, tenantId, memoryId, sourceObject, 'insertEntity');
+    const result = db.prepare(`
+    INSERT INTO entities(tenant_id, entity_type, name, memory_id, source_kind, source_object_type, source_object_id, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(tenantId, opts.entityType, name, effectiveMemoryId, sourceKind, sourceObject?.type ?? null, sourceObject?.id ?? null, now);
+    const id = Number(result.lastInsertRowid ?? 0);
+    // SAFETY: row's shape matches the columns named in ENTITY_COLS above.
+    const row = db.prepare(`SELECT ${ENTITY_COLS} FROM entities WHERE id = ?`).get(id);
+    if (!row)
+        throw new Error('insertEntity: failed to reload inserted entity');
+    return rowToEntity(row);
 }
 function checkedName(label, raw) {
     const name = (raw ?? '').trim();
@@ -117,36 +102,26 @@ function checkedName(label, raw) {
     }
     return name;
 }
-/** Renames an entity or moves its memory provenance in place, keeping id and created_at; null when the row is gone.
+/** Renames an entity or moves its memory provenance in place on the caller's handle, 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 function updateEntity(hippoRoot, tenantId, id, opts, txDb) {
+export function updateEntityRow(db, tenantId, id, opts) {
     assertTenantId('updateEntity', tenantId);
     const name = checkedName('updateEntity', opts.name);
-    const db = txDb ?? 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);
-        if (!row)
-            return null;
-        const entity = rowToEntity(row);
-        const sourceObject = entity.sourceObjectType === undefined || entity.sourceObjectId === undefined
-            ? null
-            : { type: entity.sourceObjectType, id: entity.sourceObjectId };
-        const resolved = resolveConsolidatedSource(db, tenantId, opts.memoryId ?? null, sourceObject, 'updateEntity');
-        db.prepare(`UPDATE entities SET name = ?, memory_id = ?, source_kind = ? WHERE id = ? AND tenant_id = ?`)
-            .run(name, resolved.memoryId, resolved.sourceKind, id, tenantId);
-        return { ...entity, name, memoryId: resolved.memoryId, sourceKind: resolved.sourceKind };
-    }
-    finally {
-        if (db !== txDb)
-            closeHippoDb(db);
-    }
+    // 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);
+    if (!row)
+        return null;
+    const entity = rowToEntity(row);
+    const sourceObject = entity.sourceObjectType === undefined || entity.sourceObjectId === undefined
+        ? null
+        : { type: entity.sourceObjectType, id: entity.sourceObjectId };
+    const resolved = resolveConsolidatedSource(db, tenantId, opts.memoryId ?? null, sourceObject, 'updateEntity');
+    db.prepare(`UPDATE entities SET name = ?, memory_id = ?, source_kind = ? WHERE id = ? AND tenant_id = ?`)
+        .run(name, resolved.memoryId, resolved.sourceKind, id, tenantId);
+    return { ...entity, name, memoryId: resolved.memoryId, sourceKind: resolved.sourceKind };
 }
-/**
- * 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 function insertRelation(hippoRoot, tenantId, opts, txDb) {
+/** Insert a graph relation between two same-tenant entities on the caller's handle, sourced from a consolidated memory. */
+export function insertRelationRow(db, tenantId, opts) {
     assertTenantId('insertRelation', tenantId);
     if (!GRAPH_RELATION_TYPES.has(opts.relType)) {
         throw new Error(`insertRelation: relType must be one of ${Array.from(GRAPH_RELATION_TYPES).join('|')}; got ${opts.relType}`);
@@ -154,35 +129,27 @@ export function insertRelation(hippoRoot, tenantId, opts, txDb) {
     const now = new Date().toISOString();
     const memoryId = opts.memoryId ?? null;
     const sourceObject = opts.sourceObject ?? null;
-    const ownDb = txDb ? null : openHippoDb(hippoRoot);
-    const db = txDb ?? ownDb;
-    try {
-        for (const [eid, role] of [[opts.fromEntityId, 'from'], [opts.toEntityId, 'to']]) {
-            // SAFETY: ent's shape matches the single `tenant_id` column named in
-            // the SELECT above.
-            const ent = db.prepare(`SELECT tenant_id FROM entities WHERE id = ?`).get(eid);
-            if (!ent)
-                throw new Error(`insertRelation: ${role}_entity ${eid} not found`);
-            if (ent.tenant_id !== tenantId) {
-                throw new Error(`insertRelation: ${role}_entity ${eid} belongs to another tenant (no cross-tenant edges)`);
-            }
+    for (const [eid, role] of [[opts.fromEntityId, 'from'], [opts.toEntityId, 'to']]) {
+        // SAFETY: ent's shape matches the single `tenant_id` column named in
+        // the SELECT above.
+        const ent = db.prepare(`SELECT tenant_id FROM entities WHERE id = ?`).get(eid);
+        if (!ent)
+            throw new Error(`insertRelation: ${role}_entity ${eid} not found`);
+        if (ent.tenant_id !== tenantId) {
+            throw new Error(`insertRelation: ${role}_entity ${eid} belongs to another tenant (no cross-tenant edges)`);
         }
-        const { sourceKind, memoryId: effectiveMemoryId } = resolveConsolidatedSource(db, tenantId, memoryId, sourceObject, 'insertRelation');
-        const result = db.prepare(`
-      INSERT INTO relations(tenant_id, from_entity_id, to_entity_id, rel_type, memory_id, source_kind, source_object_type, source_object_id, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(tenantId, opts.fromEntityId, opts.toEntityId, opts.relType, effectiveMemoryId, sourceKind, sourceObject?.type ?? null, sourceObject?.id ?? null, now);
-        const id = Number(result.lastInsertRowid ?? 0);
-        // SAFETY: row's shape matches the columns named in RELATION_COLS above.
-        const row = db.prepare(`SELECT ${RELATION_COLS} FROM relations WHERE id = ?`).get(id);
-        if (!row)
-            throw new Error('insertRelation: failed to reload inserted relation');
-        return rowToRelation(row);
-    }
-    finally {
-        if (ownDb)
-            closeHippoDb(ownDb);
     }
+    const { sourceKind, memoryId: effectiveMemoryId } = resolveConsolidatedSource(db, tenantId, memoryId, sourceObject, 'insertRelation');
+    const result = db.prepare(`
+    INSERT INTO relations(tenant_id, from_entity_id, to_entity_id, rel_type, memory_id, source_kind, source_object_type, source_object_id, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(tenantId, opts.fromEntityId, opts.toEntityId, opts.relType, effectiveMemoryId, sourceKind, sourceObject?.type ?? null, sourceObject?.id ?? null, now);
+    const id = Number(result.lastInsertRowid ?? 0);
+    // SAFETY: row's shape matches the columns named in RELATION_COLS above.
+    const row = db.prepare(`SELECT ${RELATION_COLS} FROM relations WHERE id = ?`).get(id);
+    if (!row)
+        throw new Error('insertRelation: failed to reload inserted relation');
+    return rowToRelation(row);
 }
 /** The source object still holds the loader's rule (active or superseded); a closed or gone one gets no new graph row. */
 export function objectInForce(db, tenantId, ref) {
@@ -221,33 +188,19 @@ export function runGraphRebuildTransaction(hippoRoot, tenantId, fn, opts) {
         closeHippoDb(db);
     }
 }
-/**
- * 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.
- */
+/** 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 function removeGraphEntitiesForObject(hippoRoot, tenantId, sourceObjectType, sourceObjectId) {
     try {
         assertTenantId('removeGraphEntitiesForObject', tenantId);
-        const db = openHippoDb(hippoRoot);
-        try {
+        onHandle(hippoRoot, (db) => {
             withWriteScope(db, 'remove_graph_entities', () => {
                 db.prepare(`DELETE FROM relations WHERE tenant_id = ? AND source_object_type = ? AND source_object_id = ?`)
                     .run(tenantId, sourceObjectType, sourceObjectId);
                 db.prepare(`DELETE FROM entities WHERE tenant_id = ? AND source_object_type = ? AND source_object_id = ?`)
                     .run(tenantId, sourceObjectType, sourceObjectId);
             });
-        }
-        finally {
-            closeHippoDb(db);
-        }
+        });
     }
     catch (err) {
         log.warn(`removeGraphEntitiesForObject: failed for tenant=${tenantId} ${sourceObjectType}#${sourceObjectId}: ${errorMessage(err)}`);

package/dist/store/half-life.d.ts

@@ -20,7 +20,8 @@ export interface HalfLifeMove {
 }
 /** The base this store's memories are on: 7 days when none was ever recorded. */
 export declare function recordedHalfLifeBase(hippoRoot: string): number;
-/** Moves the store's half-lives to base `to` as `plan` decides from the rows read here, then records the base. `outcome` is null when no move is due; a dry run plans and writes nothing. */
+/** Moves the store's half-lives to base `to` as `plan` decides from the rows read here, then
+ * records the base. `outcome` is null when no move is due; a dry run plans and writes nothing. */
 export declare function moveHalfLives<R>(hippoRoot: string, to: number, opts: {
     dryRun: boolean;
     actor: string;

package/dist/store/half-life.js

@@ -1,10 +1,10 @@
 // A half-life move reads, writes, audits and records its base on one handle, so it commits whole or not at all.
-import { closeHippoDb, getMeta, openHippoDb, setMeta, withWriteScope } from '../db/index.js';
+import { getMeta, setMeta, withWriteScope } from '../db/index.js';
 import { appendAuditEvent } from './audit.js';
 import { conflictResolveAuditsAt, resolvedConflictsAt } from './conflicts.js';
 import { objectMemoryRowsAt, selectAllEntries } from './entry-reads.js';
 import { setHalfLivesAt } from './entry-writes.js';
-import { HALF_LIFE_BASE_META_KEY, TYPED_HALF_LIFE_META_KEY, openStore } from './open.js';
+import { onHandle, HALF_LIFE_BASE_META_KEY, TYPED_HALF_LIFE_META_KEY, openStore } from './open.js';
 /** The base every store used before the base was recorded. */
 const LEGACY_HALF_LIFE_BASE = 7;
 function readBase(db) {
@@ -13,13 +13,9 @@ function readBase(db) {
 }
 /** The base this store's memories are on: 7 days when none was ever recorded. */
 export function recordedHalfLifeBase(hippoRoot) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return readBase(db);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 function readRows(db, from, typedPending) {
     const all = selectAllEntries(db);
@@ -44,13 +40,18 @@ function writeMove(db, move, old, actor) {
         record[e.id] = old.get(e.id);
     }
     for (const [tenantId, oldHalfLives] of byTenant) {
-        appendAuditEvent(db, { tenantId, actor, op: 'half_life_migrate', metadata: { from: move.from, to: move.to, ids: Object.keys(oldHalfLives), oldHalfLives } });
+        appendAuditEvent(db, {
+            tenantId,
+            actor,
+            op: 'half_life_migrate',
+            metadata: { from: move.from, to: move.to, ids: Object.keys(oldHalfLives), oldHalfLives }
+        });
     }
 }
-/** Moves the store's half-lives to base `to` as `plan` decides from the rows read here, then records the base. `outcome` is null when no move is due; a dry run plans and writes nothing. */
+/** Moves the store's half-lives to base `to` as `plan` decides from the rows read here, then
+ * records the base. `outcome` is null when no move is due; a dry run plans and writes nothing. */
 export function moveHalfLives(hippoRoot, to, opts, plan) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const run = () => {
             const from = readBase(db);
             const typedPending = getMeta(db, TYPED_HALF_LIFE_META_KEY, '') === '';
@@ -69,9 +70,6 @@ export function moveHalfLives(hippoRoot, to, opts, plan) {
         };
         // Plan, write, audit and record the base under one write lock, so a concurrent write or sleep cannot interleave.
         return opts.dryRun ? run() : withWriteScope(db, 'migrate_half_life', run);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 //# sourceMappingURL=half-life.js.map