hippo-memory 1.70.0 → 1.71.0

package/dist/store/graph-reads.js

@@ -1,13 +1,12 @@
 // 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` (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 +88,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 +114,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 +127,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 +150,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 +178,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 +199,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) {
@@ -244,29 +220,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,33 +1,18 @@
 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).
- */
+/** 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 entities, sourced from a consolidated memory.
- * Both entities must exist in the same tenant; the source memory must be consolidated.
- */
+/** 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;
@@ -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,10 +71,7 @@ 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).
- */
+/** 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) {
     assertTenantId('insertEntity', tenantId);
     if (!GRAPH_ENTITY_TYPES.has(opts.entityType)) {
@@ -142,10 +135,7 @@ export function updateEntity(hippoRoot, tenantId, id, opts, txDb) {
             closeHippoDb(db);
     }
 }
-/**
- * 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.
- */
+/** Insert a graph relation between two same-tenant entities, sourced from a consolidated memory. */
 export function insertRelation(hippoRoot, tenantId, opts, txDb) {
     assertTenantId('insertRelation', tenantId);
     if (!GRAPH_RELATION_TYPES.has(opts.relType)) {
@@ -221,33 +211,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

package/dist/store/handoffs.d.ts

@@ -1,11 +1,9 @@
 import { type SessionHandoff, type HandoffOutcome, type HandoffEvidence } from '../core/handoff.js';
 import type { TaskSnapshot } from './rows.js';
 import { type ContinuityKey } from './sessions.js';
-/** Column list shared by every session_handoffs SELECT; store-cards.ts reuses it for the card handoff lookup. */
+/** Column list shared by every session_handoffs SELECT; cards.ts reuses it for the card handoff lookup. */
 export declare const HANDOFF_COLUMNS = "id, session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, created_at, constraints_json, evidence_json, outcome, target_runtime, card_id";
-/**
- * Save a session handoff record. Returns the persisted handoff.
- */
+/** Save a session handoff record; returns the persisted handoff. */
 export declare function saveSessionHandoff(hippoRoot: string, tenantId: string, handoff: Omit<SessionHandoff, 'updatedAt'>, key?: ContinuityKey): SessionHandoff;
 interface HandoffFilter {
     unfinishedOnly?: boolean;
@@ -15,16 +13,12 @@ interface HandoffFilter {
 }
 /** Load the most recent handoff, optionally filtered by session ID. */
 export declare function loadLatestHandoff(hippoRoot: string, tenantId: string, sessionId?: string, opts?: HandoffFilter, key?: ContinuityKey): SessionHandoff | null;
-/**
- * Load a specific handoff by its row ID.
- */
+/** Load a specific handoff by its row ID. */
 export declare function loadHandoffById(hippoRoot: string, tenantId: string, id: number): SessionHandoff | null;
 /** Stamp the outcome on a session's newest handoff, only if it has none yet. Returns rows changed. */
 export declare function stampHandoffOutcome(hippoRoot: string, tenantId: string, sessionId: string, outcome: HandoffOutcome): number;
-/** Auto-write a handoff at session-end from the session's active snapshot, else from `derived`, its transcript state.
- * @param evidence best-effort git state; outcome comes from the newest session_complete event.
- * @param options.inPlace rewrite an earlier transcript read instead of adding a revision, for a close that runs after every reply.
- * @returns null when neither source is the session's, a newer handoff covers the snapshot, the session's latest handoff was not read off its transcript or already holds `derived`, or, in place, a handoff landed after the read. */
+/** Session-end handoff from the active snapshot, else `derived` transcript state; `inPlace` rewrites an earlier transcript read instead of adding a revision.
+ * Returns null when no source is the session's, a newer handoff covers it, or the latest one is not transcript-derived or already holds `derived`. */
 export declare function writeSessionEndHandoff(hippoRoot: string, tenantId: string, sessionId: string, evidence: HandoffEvidence | null, derived?: Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'> | null, key?: ContinuityKey, options?: {
     inPlace?: boolean;
 }): SessionHandoff | null;

package/dist/store/handoffs.js

@@ -1,14 +1,12 @@
-import { closeHippoDb, openHippoDb } from '../db/index.js';
+import { closeHippoDb } from '../db/index.js';
 import { rowToSessionHandoff, isHandoffOutcome, } from '../core/handoff.js';
 import { scopeAdmitSql } from './recall-scope.js';
 import { assertTenantId } from './tenant.js';
-import { openStore } from './open.js';
+import { onHandle, openStore } from './open.js';
 import { continuityStamp, continuityWhere, loadActiveTaskSnapshot } from './sessions.js';
-/** Column list shared by every session_handoffs SELECT; store-cards.ts reuses it for the card handoff lookup. */
+/** Column list shared by every session_handoffs SELECT; cards.ts reuses it for the card handoff lookup. */
 export const HANDOFF_COLUMNS = 'id, session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, created_at, constraints_json, evidence_json, outcome, target_runtime, card_id';
-/**
- * Save a session handoff record. Returns the persisted handoff.
- */
+/** Save a session handoff record; returns the persisted handoff. */
 export function saveSessionHandoff(hippoRoot, tenantId, handoff, key) {
     assertTenantId('saveSessionHandoff', tenantId);
     const stamp = key ? continuityStamp(key) : null;
@@ -50,8 +48,7 @@ function handoffConditions(tenantId, sessionId, opts, key) {
         params.push(opts.excludeSessionId);
     }
     if (opts.unfinishedOnly) {
-        // Restrict to each session's newest revision first: stampHandoffOutcome
-        // only stamps the newest row, so an older null-outcome revision must not resurrect.
+        // Restrict to each session's newest revision first: stampHandoffOutcome only stamps the newest row, so an older null-outcome revision must not resurrect.
         // Keyed, the newest is the owner's own, so another owner's newer revision cannot hide it.
         conditions.push(`id IN (SELECT MAX(id) FROM session_handoffs WHERE tenant_id = ?${owned ? ` AND ${owned.sql}` : ''} GROUP BY session_id)`);
         params.push(tenantId, ...(owned?.params ?? []));
@@ -89,9 +86,7 @@ export function loadLatestHandoff(hippoRoot, tenantId, sessionId, opts = {}, key
         closeHippoDb(db);
     }
 }
-/**
- * Load a specific handoff by its row ID.
- */
+/** Load a specific handoff by its row ID. */
 export function loadHandoffById(hippoRoot, tenantId, id) {
     assertTenantId('loadHandoffById', tenantId);
     const db = openStore(hippoRoot);
@@ -111,8 +106,7 @@ export function loadHandoffById(hippoRoot, tenantId, id) {
 /** Stamp the outcome on a session's newest handoff, only if it has none yet. Returns rows changed. */
 export function stampHandoffOutcome(hippoRoot, tenantId, sessionId, outcome) {
     assertTenantId('stampHandoffOutcome', tenantId);
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const result = db.prepare(`
       UPDATE session_handoffs SET outcome = ?
       WHERE tenant_id = ? AND session_id = ? AND outcome IS NULL
@@ -123,17 +117,14 @@ export function stampHandoffOutcome(hippoRoot, tenantId, sessionId, outcome) {
         )
     `).run(outcome, tenantId, sessionId, tenantId, sessionId);
         return Number(result.changes ?? 0);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/** Rewrites the session's newest handoff when it is still a transcript read, in one statement so a handoff written meanwhile is never overwritten; null when none was rewritten. */
+/** Rewrites the session's newest handoff when it is still a transcript read, in one statement so a handoff written meanwhile is never overwritten; null
+ * when none was rewritten. */
 function replaceTranscriptHandoff(hippoRoot, tenantId, handoff, key) {
     const { conditions, params } = handoffConditions(tenantId, handoff.sessionId, {}, key);
     const newest = `SELECT id FROM session_handoffs WHERE ${conditions.join(' AND ')} ORDER BY created_at DESC, id DESC LIMIT 1`;
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const result = db.prepare(`
       UPDATE session_handoffs SET repo_root = ?, task_id = ?, summary = ?, next_action = ?, artifacts_json = ?, scope = ?, created_at = ?,
         constraints_json = ?, evidence_json = ?, outcome = ?, target_runtime = ?, card_id = ?
@@ -144,10 +135,7 @@ function replaceTranscriptHandoff(hippoRoot, tenantId, handoff, key) {
         // SAFETY: row's shape matches HANDOFF_COLUMNS.
         const row = db.prepare(`SELECT ${HANDOFF_COLUMNS} FROM session_handoffs WHERE id = (${newest})`).get(...params);
         return row ? rowToSessionHandoff(row) : null;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 function transcriptHandoffSource(existing, derived, evidence) {
     // Only an earlier transcript read gives way; `hippo handoff create` and unmarked older handoffs keep winning.
@@ -179,10 +167,8 @@ function buildSessionEndHandoff(sessionId, snapshot, existing, handoffEvidence,
         cardId: carryForward ? existing.cardId : undefined,
     };
 }
-/** Auto-write a handoff at session-end from the session's active snapshot, else from `derived`, its transcript state.
- * @param evidence best-effort git state; outcome comes from the newest session_complete event.
- * @param options.inPlace rewrite an earlier transcript read instead of adding a revision, for a close that runs after every reply.
- * @returns null when neither source is the session's, a newer handoff covers the snapshot, the session's latest handoff was not read off its transcript or already holds `derived`, or, in place, a handoff landed after the read. */
+/** Session-end handoff from the active snapshot, else `derived` transcript state; `inPlace` rewrites an earlier transcript read instead of adding a revision.
+ * Returns null when no source is the session's, a newer handoff covers it, or the latest one is not transcript-derived or already holds `derived`. */
 export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence, derived = null, key, options = {}) {
     assertTenantId('writeSessionEndHandoff', tenantId);
     if (key)
@@ -216,8 +202,7 @@ export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence,
     return saveSessionHandoff(hippoRoot, tenantId, handoff, key);
 }
 function sessionOutcome(hippoRoot, tenantId, sessionId) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: row's shape matches the single `content` column below.
         const content = db.prepare(`
       SELECT content FROM session_events
@@ -225,9 +210,6 @@ function sessionOutcome(hippoRoot, tenantId, sessionId) {
       ORDER BY created_at DESC, id DESC LIMIT 1
     `).get(tenantId, sessionId)?.content;
         return isHandoffOutcome(content) ? content : null;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 //# sourceMappingURL=handoffs.js.map