hippo-memory 1.70.0 → 1.71.0

package/dist/store/delete-and-batch.js

@@ -1,5 +1,7 @@
-import { AUTO_DELETABLE_SQL } from '../core/memory.js';
-import { openHippoDb, closeHippoDb, withWriteScope } from '../db/index.js';
+import { DEFAULT_TENANT_ID } from '../util/env.js';
+import { RawAppendOnlyError } from '../core/raw-append-only.js';
+import { AUTO_DELETABLE_SQL } from './rule-sql.js';
+import { closeHippoDb, withWriteScope } from '../db/index.js';
 import { checkRejectionGuard, RejectedValueError } from './rejection.js';
 import { markSummaryDirtyInTx } from './summary-dirty.js';
 import { insertDormantRow } from './dormant.js';
@@ -8,7 +10,7 @@ import { MEMORY_SELECT_COLUMNS, rowToEntry } from './rows.js';
 import { audit } from './audit-event.js';
 import { deleteFtsRow, replaceFtsRows, stampOriginProject, upsertMemoryRow } from './entry-row.js';
 import { purgeMirrorBestEffort, mirrorBestEffort, writeMarkdownMirror } from './mirrors.js';
-import { openStore } from './open.js';
+import { onHandle, openStore } from './open.js';
 import { clock } from '../util/write-budget.js';
 /** Tables whose rows keep a first-class object's backing memory in `memory_id` (ON DELETE SET NULL); tests/dormant-memories.test.ts pins it to the schema. */
 export const MEMORY_BACKED_TABLES = ['predictions', 'decisions', 'incidents', 'processes', 'policies', 'skills', 'project_briefs', 'customer_notes'];
@@ -16,13 +18,9 @@ export const MEMORY_BACKED_TABLES = ['predictions', 'decisions', 'incidents', 'p
 const AUTOMATIC_DELETE_SQL = `${AUTO_DELETABLE_SQL}${MEMORY_BACKED_TABLES.map((t) => ` AND NOT EXISTS (SELECT 1 FROM ${t} WHERE ${t}.memory_id = memories.id)`).join('')}`;
 /** Ids of memories that back a first-class object, for passes that plan deletes before making them. A table missing from an older schema is skipped. */
 export function memoriesBackingObjects(hippoRoot) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return memoriesBackingObjectsOn(db);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 /** memoriesBackingObjects on the caller's handle. */
 export function memoriesBackingObjectsOn(db) {
@@ -42,16 +40,22 @@ export function memoriesBackingObjectsOn(db) {
     }
     return ids;
 }
-/**
- * db-scoped delete core, so a delete can compose inside a caller's transaction.
- * NO filesystem I/O: the caller's transaction may still roll back, and mirrors are written post-commit.
- *
- * `opts.suppressForgetAudit` (default false): `rejectValue` and `resolveConflict` set it because each
- * writes its own aggregate audit row, so a removed row must not ALSO emit a `forget` row.
- *
- * Returns `{tenantId, dagParentId}` for the removed row, or `null` if no row with `id`
- * existed or `automatic` refused it (pinned, raw, kept for good or backing an object at DELETE time, so a late pin wins).
- */
+// The abort text of trg_memories_raw_append_only (migration v14), the one place src matches it.
+const RAW_TRIGGER_TEXT = 'raw is append-only';
+function isRawTriggerAbort(cause) {
+    return cause instanceof Error && cause.message.includes(RAW_TRIGGER_TEXT);
+}
+/** Runs the DELETE and returns the rows it removed; the raw-row trigger's abort becomes RawAppendOnlyError. */
+function deleteMemoryRow(db, sql, id) {
+    try {
+        return Number(db.prepare(sql).run(id).changes ?? 0);
+    }
+    catch (cause) {
+        throw isRawTriggerAbort(cause) ? new RawAppendOnlyError(cause) : cause;
+    }
+}
+/** db-scoped delete core, composable inside a caller's transaction; NO filesystem I/O, mirrors are written post-commit. `suppressForgetAudit` is set by
+ * rejectValue and resolveConflict (own audit row). Returns `{tenantId, dagParentId}`, or null if absent or `automatic` refused it. */
 export function deleteEntryCore(db, id, opts) {
     // SAFETY: row's shape matches the three columns named in the SELECT above.
     const row = db
@@ -60,7 +64,7 @@ export function deleteEntryCore(db, id, opts) {
     if (!row?.id)
         return null;
     const guard = opts?.automatic ? ` AND ${AUTOMATIC_DELETE_SQL}` : '';
-    if (Number(db.prepare(`DELETE FROM memories WHERE id = ?${guard}`).run(id).changes ?? 0) === 0)
+    if (deleteMemoryRow(db, `DELETE FROM memories WHERE id = ?${guard}`, id) === 0)
         return null;
     deleteFtsRow(db, id);
     if (!opts?.suppressForgetAudit) {
@@ -69,29 +73,16 @@ export function deleteEntryCore(db, id, opts) {
     // Forgetting a child of a summary marks the parent dirty. Not atomic with the DELETE, but
     // markSummaryDirtyInTx is idempotent, so the next child mutation re-marks the parent if this fails.
     if (row.dag_parent_id) {
-        markSummaryDirtyInTx(db, row.dag_parent_id, row.tenant_id ?? 'default', opts?.actor ?? 'cli');
+        markSummaryDirtyInTx(db, row.dag_parent_id, row.tenant_id ?? DEFAULT_TENANT_ID, opts?.actor ?? 'cli');
     }
-    return { tenantId: row.tenant_id ?? 'default', dagParentId: row.dag_parent_id ?? null };
+    return { tenantId: row.tenant_id ?? DEFAULT_TENANT_ID, dagParentId: row.dag_parent_id ?? null };
 }
-/**
- * Delete an entry from SQLite and mirrors.
- *
- * `opts.actor` defaults to 'cli'. The api.* layer threads `ctx.actor` so HTTP
- * callers land with `api_key:<key_id>` in the audit log without a duplicate
- * emit from the api wrapper.
- *
- * Thin wrapper over `deleteEntryCore` (open → core → mirrors → close);
- * behavior is byte-identical to the pre-split implementation for every
- * existing caller.
- */
+/** Delete an entry from SQLite and mirrors; thin wrapper over `deleteEntryCore` (open, core, mirrors, close).
+ * `opts.actor` defaults to 'cli'; the api layer threads `ctx.actor` so HTTP callers land as `api_key:<key_id>` in the audit log. */
 export function deleteEntry(hippoRoot, id, opts) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return deleteEntryOn(db, hippoRoot, id, opts);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** deleteEntry on the caller's open store, so a loop of deletes opens the store once; each delete still commits alone. */
 function deleteEntryOn(db, hippoRoot, id, opts) {
@@ -112,26 +103,17 @@ function mergeOwnChanges(base, ours, live) {
     }
     return row;
 }
-/** Writes, deletes and dormant moves in one transaction. With `snapshot` (rows as the caller loaded them), a write keeps only
- *  the fields the caller changed, takes the rest from the live row, and never resurrects a row that is gone.
- *
- *  `dormant` (src/store/dormant.ts): each move's snapshot is inserted into `dormant_memories` and its `memories` row
- *  leaves exactly like a delete (FTS row, DAG parent dirty-mark, mirrors), in the same transaction, so a memory
- *  is never in both places or in neither. Deletes and moves both skip rows that are no longer auto-deletable
- *  (pinned, raw, kept for good or backing an object since the caller decided). Returns the ids that left `memories`, deleted or moved. */
+/** Writes, deletes and dormant moves in one transaction. With `snapshot`, a write keeps only the fields the caller changed and never resurrects a gone row.
+ * Dormant moves (src/store/dormant.ts) leave `memories` like a delete; both skip rows no longer auto-deletable. Returns ids that left `memories`. */
 export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds, opts) {
     const dormant = opts?.dormant ?? [];
     if (toWrite.length === 0 && toDeleteIds.length === 0 && dormant.length === 0)
         return [];
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // One component, so every op keeps the statement order this call has always had.
         const all = { writes: toWrite, deletes: toDeleteIds, dormant };
         return batchWriteAndDeleteOn(db, hippoRoot, [all], 0, { snapshot: opts?.snapshot, holdMs: Infinity }).removedIds;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 const failedUnits = new WeakMap();
 /** Tags a flush error with the ids of the component it stopped at, for the partial sleep audit row; the first tag wins. */
@@ -149,7 +131,13 @@ export function failedUnitOf(err) {
  *  first component boundary after `holdMs`. Returns the next component's index and the ids that left `memories`. */
 function batchWriteAndDeleteOn(db, hippoRoot, components, from, opts) {
     const now = opts.clock ?? clock;
-    const out = { written: [], removedIds: [], rejectedSkips: 0, fts: { rows: [], staleIds: [] }, dirty: { parents: new Set(), tenantById: new Map() } };
+    const out = {
+        written: [],
+        removedIds: [],
+        rejectedSkips: 0,
+        fts: { rows: [], staleIds: [] },
+        dirty: { parents: new Set(), tenantById: new Map() }
+    };
     let next = from;
     // IMMEDIATE: the tombstone probes below read before the first write, and under a deferred BEGIN a
     // concurrent `hippo reject` would make the lock upgrade fail with SQLITE_BUSY and roll back the batch.
@@ -171,7 +159,7 @@ function batchWriteAndDeleteOn(db, hippoRoot, components, from, opts) {
         // Fire dirty-mark for every collected parent INSIDE the BEGIN, so the
         // dirty flag commits atomically with the writes + deletes.
         for (const parentId of out.dirty.parents) {
-            markSummaryDirtyInTx(db, parentId, out.dirty.tenantById.get(parentId) ?? 'default', 'batch');
+            markSummaryDirtyInTx(db, parentId, out.dirty.tenantById.get(parentId) ?? DEFAULT_TENANT_ID, 'batch');
         }
     });
     reportChunk(hippoRoot, out);
@@ -231,7 +219,7 @@ function selectAutoDeletableRows(db, ids, dirty) {
     for (const row of rows) {
         if (row.dag_parent_id) {
             dirty.parents.add(row.dag_parent_id);
-            dirty.tenantById.set(row.dag_parent_id, row.tenant_id ?? 'default');
+            dirty.tenantById.set(row.dag_parent_id, row.tenant_id ?? DEFAULT_TENANT_ID);
         }
     }
     return rows;
@@ -272,7 +260,7 @@ function applyBatchWrites(db, stampedWrites, snapshot, out) {
 }
 /** True, after auditing the refusal, when the write would introduce a rejected value. */
 function isRejectedBatchWrite(db, row) {
-    const entryTenantId = row.tenantId ?? 'default';
+    const entryTenantId = row.tenantId ?? DEFAULT_TENANT_ID;
     // checkRejectionGuard, not a bare tombstone probe: a tombstone can coexist with a live same-content row,
     // and skipping every re-persist would starve it of decay/replay updates; only new or changed content is refused.
     try {
@@ -291,16 +279,12 @@ function isRejectedBatchWrite(db, row) {
 export function deleteEntriesOneByOne(hippoRoot, targets, opts) {
     if (targets.length === 0)
         return [];
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return targets.map((target) => deleteEntryOn(db, hippoRoot, target.id, { ...opts, reason: target.reason }));
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/** Commits whole components in transactions of about `budget.holdMs` on one store handle, letting other writers in between; returns the ids that left `memories`.
- *  The snapshot keeps what other writers changed after the caller loaded its rows. */
+/** Commits whole components in transactions of about `budget.holdMs`, letting other writers in between; returns the ids that left `memories`.
+ * The snapshot keeps what other writers changed after the caller loaded its rows. */
 export async function commitInChunks(hippoRoot, components, opts) {
     if (components.length === 0)
         return [];

package/dist/store/delivery-recorder.d.ts

@@ -1,8 +1,8 @@
 import type { MemoryEntry } from '../core/memory.js';
 import { type PromptRecallGate } from '../core/prompt-recall.js';
 export type DeliveryRuntime = 'claude-code' | 'codex' | 'copilot' | 'unknown';
-export type DeliveryEventType = 'prompt-submit' | 'pinned-manual' | 'pre-compact' | 'compact-resume';
-/** True for the two compaction boundary types. */
+export type DeliveryEventType = 'prompt-submit' | 'pinned-manual' | 'pre-compact' | 'compact-resume' | 'session-end' | 'context';
+/** True for the boundary types: a compaction's two hooks and the end of a session. */
 export declare const isBoundaryEvent: (type: DeliveryEventType) => boolean;
 export type DeliverySurface = 'hook' | 'context';
 export type DeliveryWriteStore = 'local' | 'global';
@@ -12,8 +12,8 @@ export type DeliveryPool = 'pin' | 'recent' | 'prompt-recall' | 'strength' | 'se
 export type DeliveryStage = 'load' | 'eligible' | 'gate' | 'budget' | 'limit' | 'final';
 export type DeliveryOutcome = 'emitted' | 'reused' | 'rejected';
 export type DeliveryRejectReason = 'budget' | 'gate-below-threshold' | 'gate-max-items' | 'duplicate' | 'scope' | 'quality' | 'limit';
-/** Row format version in `delivery_events.ledger_version`: 2 = written by a binary that can write boundary rows, so `event_type` has four values. */
-export declare const DELIVERY_LEDGER_VERSION = 2;
+/** Row format version in `delivery_events.ledger_version`: 3 = written by a binary that can write session-end and context rows, so `event_type` has six values. */
+export declare const DELIVERY_LEDGER_VERSION = 3;
 /** Rejected candidate rows kept per event; the rest only add to `rejected_unlisted`. */
 export declare const DELIVERY_REJECTED_ROW_CAP = 16;
 export interface DeliveryCandidateInput {
@@ -98,6 +98,10 @@ export interface DeliveryObserver {
         };
     }[]): void;
     selected(items: readonly DeliverySelected[]): void;
+    /** A searching call's query, `*` for none; kept as its hash, the one the recall trace stores. */
+    queried(query: string): void;
+    /** The recall trace a call that returned rows wrote; null when the write failed or the store answers no id. */
+    traced(traceId: number | null): void;
 }
 /** What the renderer sent, reported once at its exit. */
 export interface DeliveryOutcomeInput {

package/dist/store/delivery-recorder.js

@@ -2,11 +2,13 @@ import { evalNow } from '../core/ablation.js';
 import { scoreOverlap } from '../core/prompt-recall.js';
 import { hookPayloadSessionId, hookPayloadString, isSubagentPayload } from './token-ledger.js';
 import { blockHash, estimateTokens } from '../util/token-text.js';
-import { errorMessage } from '../util/log.js';
-/** True for the two compaction boundary types. */
-export const isBoundaryEvent = (type) => type === 'pre-compact' || type === 'compact-resume';
-/** Row format version in `delivery_events.ledger_version`: 2 = written by a binary that can write boundary rows, so `event_type` has four values. */
-export const DELIVERY_LEDGER_VERSION = 2;
+import { errorMessage, log } from '../util/log.js';
+/** True for the boundary types: a compaction's two hooks and the end of a session. */
+export const isBoundaryEvent = (type) => type === 'pre-compact' || type === 'compact-resume' || type === 'session-end';
+/** Only the per-prompt calls keep prompt facts; a boundary or a `hippo context` run is not a prompt. */
+const carriesPrompt = (type) => type === 'prompt-submit' || type === 'pinned-manual';
+/** Row format version in `delivery_events.ledger_version`: 3 = written by a binary that can write session-end and context rows, so `event_type` has six values. */
+export const DELIVERY_LEDGER_VERSION = 3;
 /** Rejected candidate rows kept per event; the rest only add to `rejected_unlisted`. */
 export const DELIVERY_REJECTED_ROW_CAP = 16;
 // Deeper stages were closer to being sent, so the row cap keeps them first.
@@ -46,15 +48,22 @@ function rejectId(state, id, rejection) {
         return;
     state.candidates.set(id, { ...held, stage, reason, score, tokens });
 }
+function pickedPool(p, held) {
+    if (p.promptRecall)
+        return 'prompt-recall';
+    // A ranked call's rows keep the ranking that chose them, a pinned hit included.
+    if (held?.pool === 'search' || held?.pool === 'strength')
+        return held.pool;
+    return held?.pool === 'pin' || p.entry.pinned ? 'pin' : 'recent';
+}
 function pickedRows(state) {
     const staticReused = state.outcome.staticReused === true;
     const rows = [];
     for (const p of state.picked.values()) {
-        const held = state.candidates.get(p.entry.id);
         rows.push({
             memoryId: p.entry.id,
             sourceStore: p.sourceStore,
-            pool: p.promptRecall ? 'prompt-recall' : held?.pool === 'pin' || p.entry.pinned ? 'pin' : 'recent',
+            pool: pickedPool(p, state.candidates.get(p.entry.id)),
             stage: 'final',
             outcome: staticReused && !p.promptRecall ? 'reused' : 'emitted',
             reason: null,
@@ -92,14 +101,14 @@ function buildEvent(init, payload, state, ts, startedMs) {
     const rows = [...picked, ...rejected.rows];
     const emitted = outcome.emittedText ?? null;
     const eventType = init.eventType ?? (payload.hookEvent === 'UserPromptSubmit' ? 'prompt-submit' : 'pinned-manual');
-    // A boundary row carries no prompt facts, whatever the payload holds.
-    const prompt = isBoundaryEvent(eventType) ? null : payload.prompt;
+    // Whatever the payload holds, so a hook-run `hippo context` is never matched to an earlier row by its prompt.
+    const prompt = carriesPrompt(eventType) ? payload.prompt : null;
     return {
         ts,
         tenantId: init.tenantId,
         runtime: init.runtime ?? (payload.hostTurnId !== null ? 'codex' : payload.hookEvent !== null ? 'claude-code' : 'unknown'),
         eventType,
-        surface: 'hook',
+        surface: eventType === 'context' ? 'context' : 'hook',
         storeHash: init.storeHash,
         writeStore: init.writeStore,
         projectHash: facts !== null && facts.projectName !== '' ? blockHash(facts.projectName) : null,
@@ -108,8 +117,8 @@ function buildEvent(init, payload, state, ts, startedMs) {
         hostTurnId: payload.hostTurnId,
         promptHash: prompt !== null ? blockHash(prompt) : null,
         promptLength: prompt?.length ?? 0,
-        queryHash: null,
-        recallTraceId: null,
+        queryHash: state.queryHash,
+        recallTraceId: state.recallTraceId,
         blockState: state.disabledSeen ? 'disabled' : outcome.state,
         promptRecall: facts?.promptRecall === true,
         consideredCount: new Set([...state.candidates.keys(), ...state.picked.keys()]).size,
@@ -196,7 +205,7 @@ export function createDeliveryRecorder(init) {
     const payload = readPayload(init);
     const state = {
         candidates: new Map(), picked: new Map(), filtered: new Set(), facts: null, shown: 0, dropped: 0,
-        disabledSeen: false, outcome: { state: 'empty' }, broken: null, flushed: false,
+        disabledSeen: false, outcome: { state: 'empty' }, queryHash: null, recallTraceId: null, broken: null, flushed: false,
     };
     const guard = guardFor(state, fault);
     const { qualityDropped, offer, reject, dropMissing, gated, selected } = candidateMethods(state, guard);
@@ -217,14 +226,15 @@ export function createDeliveryRecorder(init) {
         dropMissing,
         gated,
         selected,
+        queried: (query) => guard(() => { state.queryHash = blockHash(query); }),
+        traced: (traceId) => guard(() => { state.recallTraceId = traceId; }),
         delivered: (o) => guard(() => { state.outcome = { ...o }; }),
         flush: (write) => {
             if (state.flushed)
                 return;
             state.flushed = true;
             if (state.broken !== null) {
-                // Same pinned `[hippo] delivery ledger` hook stderr line as recall-trace.ts's write failure.
-                console.error(`[hippo] delivery ledger skipped: recorder failed: ${state.broken}`);
+                log.warn(`delivery ledger skipped: recorder failed: ${state.broken}`);
                 return;
             }
             if (fault === 'build')

package/dist/store/diagnostics.js

@@ -1,5 +1,6 @@
 // What `hippo doctor` and `hippo support-bundle` read from a store: one read-only open each, plain data out.
-import { closeHippoDb, countTableRows, ftsRowCounts, getMeta, getSchemaVersion, openHippoDbReadOnly } from '../db/index.js';
+import { countTableRows, ftsRowCounts, getMeta, getSchemaVersion, openHippoDbReadOnly } from '../db/index.js';
+import { onHandle } from './open.js';
 import { listTableNames } from '../db/tables.js';
 import { errorMessage } from '../util/log.js';
 import { compactionCountsAt, tokenTallySince } from './doctor-reads.js';
@@ -16,8 +17,7 @@ function attempt(read) {
 }
 /** Everything `hippo doctor` reads from one store; throws when it cannot be opened or its schema version read. */
 export function readStoreHealth(hippoRoot, cutoffs) {
-    const db = openHippoDbReadOnly(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return {
             schemaVersion: getSchemaVersion(db),
             memories: countTableRows(db, 'memories'),
@@ -28,24 +28,17 @@ export function readStoreHealth(hippoRoot, cutoffs) {
             lastSleep: attempt(() => lastConsolidationAt(db)),
             compactions: attempt(() => compactionCountsAt(db, cutoffs.stuckBefore, cutoffs.transcriptFloor)),
         };
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openHippoDbReadOnly);
 }
 /** Schema version, oldest allowed binary and row count of every table, for a support bundle; never reads a memory column. */
 export function readStoreInventory(hippoRoot) {
-    const db = openHippoDbReadOnly(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const schemaVersion = getSchemaVersion(db);
         const minCompatibleBinary = getMeta(db, 'min_compatible_binary', '') || null;
         const tables = {};
         for (const name of listTableNames(db))
             tables[name] = countTableRows(db, name);
         return { schemaVersion, minCompatibleBinary, tables };
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openHippoDbReadOnly);
 }
 //# sourceMappingURL=diagnostics.js.map

package/dist/store/dormant.d.ts

@@ -1,27 +1,12 @@
-/**
- * Dormant memories: what sleep does with a faded memory instead of deleting
- * it (config `dormant.enabled`, on by default; `retentionDays` bounds how
- * long one is kept).
- *
- * A dormant memory keeps its full content in `dormant_memories` (schema v44)
- * but is no longer a `memories` row, so recall, context, every sleep pass and
- * every other reader of `memories` stop seeing it exactly as if it had been
- * deleted. `hippo dormant` lists and searches them, `hippo dormant restore`
- * brings one back, `hippo dormant forget` deletes one for good.
- *
- * Not to be confused with the raw archive (`raw_archive`, `archiveRawMemory`,
- * `hippo forget --archive`): that path removes a raw receipt's content and
- * keeps only its metadata. A dormant memory keeps its content.
- *
- * The db-taking helpers leave the handle and any transaction to the caller.
- * The hippoRoot-taking functions at the end open one of their own, for
- * api.listDormant / restoreDormant / forgetDormant / isDormant.
- */
+/** Dormant memories: what sleep does with a faded memory instead of deleting it (config `dormant.enabled`; `retentionDays` bounds how long one is kept).
+ * Content stays in `dormant_memories` (schema v44) and the `memories` row goes, so every reader of `memories` stops seeing it, as if deleted.
+ * Not the raw archive (`raw_archive`, `archiveRawMemory`), which keeps metadata only. db-taking helpers leave the handle and transaction to the caller. */
 import { type DatabaseSyncLike } from '../db/index.js';
 import type { MemoryEntry } from '../core/memory.js';
 import type { SqlFragment } from './recall-scope.js';
 import type { WriteBudget } from '../util/write-budget.js';
-/** Why a memory went dormant: sleep's decay pass, an imported agent memory whose note was deleted, `hippo projects repair` splitting a two-project merge, or `hippo audit repair` setting aside an automatic memory with a certain defect. */
+/** Why a memory went dormant: sleep's decay pass, an imported agent memory whose note was deleted, `hippo projects repair`
+ * splitting a two-project merge, or `hippo audit repair` setting aside an automatic memory with a certain defect. */
 export type DormantReason = 'decay' | 'source-deleted' | 'project-repair' | 'quality-repair';
 /** One memory that sleep is moving out of active memory into the dormant store. */
 export interface DormantMove {
@@ -53,11 +38,7 @@ export interface ListDormantOpts {
     /** Maximum rows returned, newest first. Default 20. */
     limit?: number;
 }
-/**
- * Insert (or refresh) the dormant snapshot for `move.entry`. Does not touch
- * the `memories` row: the caller deletes it in the same transaction, so the
- * memory is never in both places or in neither.
- */
+/** Insert (or refresh) the dormant snapshot for `move.entry`; the caller deletes the `memories` row in the same transaction. */
 export declare function insertDormantRow(db: DatabaseSyncLike, move: DormantMove): void;
 /** A dormant memory's stored snapshot plus when and why it went dormant. */
 export interface DormantSnapshot {
@@ -66,10 +47,7 @@ export interface DormantSnapshot {
     strength: number;
     dormantAt: string;
 }
-/**
- * The stored snapshot for a tenant's dormant memory, or null when the tenant
- * has no dormant memory with that id (another tenant's id reads as absent).
- */
+/** A tenant's stored dormant snapshot, or null when it has none with that id (another tenant's id reads as absent). */
 export declare function readDormantSnapshot(db: DatabaseSyncLike, tenantId: string, id: string): DormantSnapshot | null;
 /** Every dormant memory of a tenant whose snapshot still reads back. */
 export declare function listDormantSnapshots(db: DatabaseSyncLike, tenantId: string): DormantSnapshot[];

package/dist/store/dormant.js

@@ -1,23 +1,8 @@
-/**
- * Dormant memories: what sleep does with a faded memory instead of deleting
- * it (config `dormant.enabled`, on by default; `retentionDays` bounds how
- * long one is kept).
- *
- * A dormant memory keeps its full content in `dormant_memories` (schema v44)
- * but is no longer a `memories` row, so recall, context, every sleep pass and
- * every other reader of `memories` stop seeing it exactly as if it had been
- * deleted. `hippo dormant` lists and searches them, `hippo dormant restore`
- * brings one back, `hippo dormant forget` deletes one for good.
- *
- * Not to be confused with the raw archive (`raw_archive`, `archiveRawMemory`,
- * `hippo forget --archive`): that path removes a raw receipt's content and
- * keeps only its metadata. A dormant memory keeps its content.
- *
- * The db-taking helpers leave the handle and any transaction to the caller.
- * The hippoRoot-taking functions at the end open one of their own, for
- * api.listDormant / restoreDormant / forgetDormant / isDormant.
- */
+/** Dormant memories: what sleep does with a faded memory instead of deleting it (config `dormant.enabled`; `retentionDays` bounds how long one is kept).
+ * Content stays in `dormant_memories` (schema v44) and the `memories` row goes, so every reader of `memories` stops seeing it, as if deleted.
+ * Not the raw archive (`raw_archive`, `archiveRawMemory`), which keeps metadata only. db-taking helpers leave the handle and transaction to the caller. */
 import { closeHippoDb, openHippoDb, withWriteScope, withWriteScopeOr } from '../db/index.js';
+import { onHandle } from './open.js';
 import { RejectedValueError, rejectionDigest } from './rejection.js';
 import { escapeLike } from '../util/escape.js';
 import { warnDamagedColumn } from '../util/stored-json.js';
@@ -27,11 +12,7 @@ import { audit, auditRejectionRefusal } from './audit-event.js';
 import { entryIdTakenAt } from './entry-reads.js';
 import { writeEntryDbOnly, writeEntryMirrors } from './entry-writes.js';
 const DEFAULT_LIST_LIMIT = 20;
-/**
- * Insert (or refresh) the dormant snapshot for `move.entry`. Does not touch
- * the `memories` row: the caller deletes it in the same transaction, so the
- * memory is never in both places or in neither.
- */
+/** Insert (or refresh) the dormant snapshot for `move.entry`; the caller deletes the `memories` row in the same transaction. */
 export function insertDormantRow(db, move) {
     db.prepare(`
     INSERT INTO dormant_memories (tenant_id, id, content, entry_json, reason, strength, dormant_at)
@@ -44,10 +25,7 @@ export function insertDormantRow(db, move) {
       dormant_at = excluded.dormant_at
   `).run(move.entry.tenantId, move.entry.id, move.entry.content, JSON.stringify(move.entry), move.reason, move.strength, move.dormantAt);
 }
-/**
- * Parse a stored snapshot back into a MemoryEntry, or null when the row no
- * longer matches the snapshot it carries (edited by hand, or truncated).
- */
+/** Parse a stored snapshot back into a MemoryEntry, or null when the row no longer matches it (edited by hand, or truncated). */
 function parseSnapshot(row) {
     try {
         // SAFETY: entry_json is only written by insertDormantRow from a MemoryEntry;
@@ -94,10 +72,7 @@ function listDormantRows(db, tenantId, opts = {}, admit = EVERY_SCOPE) {
       LIMIT ?`).all(tenantId, ...admit.params, ...terms.map((t) => `%${escapeLike(t)}%`), limit);
     return rows.map(rowToDormantMemory);
 }
-/**
- * The stored snapshot for a tenant's dormant memory, or null when the tenant
- * has no dormant memory with that id (another tenant's id reads as absent).
- */
+/** A tenant's stored dormant snapshot, or null when it has none with that id (another tenant's id reads as absent). */
 export function readDormantSnapshot(db, tenantId, id) {
     // SAFETY: row's shape matches the seven columns named in the SELECT.
     const row = db.prepare(`SELECT tenant_id, id, content, entry_json, reason, strength, dormant_at
@@ -193,23 +168,15 @@ export async function expireDormantBefore(hippoRoot, cutoffIso, opts) {
 }
 /** A tenant's dormant memories whose scope `admit` passes, newest first, read on a handle of its own. */
 export function loadDormantMemories(hippoRoot, tenantId, opts = {}, admit = EVERY_SCOPE) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return listDormantRows(db, tenantId, opts, admit);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 /** Whether a tenant holds a dormant memory with this id whose scope `admit` passes, read on a handle of its own. */
 export function holdsDormantMemory(hippoRoot, tenantId, id, admit = EVERY_SCOPE) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return hasDormantRow(db, tenantId, id, admit);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 function auditDormantRestore(db, restore, snapshot, now) {
     appendAuditEvent(db, {
@@ -244,8 +211,7 @@ function restoreInWriteScope(db, restore) {
 }
 /** Brings one dormant memory back on a single handle: the live row, the dormant delete and the audit row commit together, then its mirrors are written. */
 export function restoreDormantMemory(hippoRoot, restore) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         let outcome;
         try {
             outcome = restoreInWriteScope(db, restore);
@@ -259,24 +225,17 @@ export function restoreDormantMemory(hippoRoot, restore) {
         if (outcome.status === 'restored')
             writeEntryMirrors(hippoRoot, outcome.entry);
         return outcome;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 /** Deletes a tenant's dormant memory for good and writes its `forget` audit row, on a single handle; false when it holds none `admit` passes. */
 export function forgetDormantMemory(hippoRoot, forget) {
     const { tenantId, id, actor, admit } = forget;
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         if (!hasDormantRow(db, tenantId, id, admit) || !deleteDormantRow(db, tenantId, id))
             return false;
         // Best-effort, like every other forget audit row: the delete stands.
         audit(db, 'forget', { tenantId, actor, targetId: id, metadata: { dormant: true } });
         return true;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 //# sourceMappingURL=dormant.js.map