hippo-memory 1.69.0 → 1.71.0

package/dist/store/sqlite/worker-ops.js

@@ -0,0 +1,93 @@
+/** Store methods answered by a worker, base ones under `base`. Tagged by effect, not name: predictionBaserate (audit row) and bumpRecallStats
+ * (stats.json) are writes. A read that opens through `openStore` is a read: the writer runs that open's setup before any reader serves. */
+export const WORKER_OPS = {
+    base: {
+        findApiKey: 'read',
+        searchRecallEntries: 'read',
+        entriesByIds: 'read',
+        activeGoals: 'read',
+        freshRawEntries: 'read',
+        continuity: 'read',
+        planningFallacyEvidence: 'read',
+        appendAuditEvents: 'write',
+        finishRecall: 'write',
+        bumpRecallStats: 'write',
+        recordTokens: 'write',
+    },
+    vectors: {
+        embeddingIndexState: 'read',
+        storedVectors: 'read',
+        nearestEntries: 'read',
+        physicsParticles: 'read',
+    },
+    vectorViews: {
+        storedVectorViews: 'read',
+    },
+    keyAudit: {
+        revokeApiKey: 'write',
+        auditEventsAfter: 'read',
+        auditHighId: 'read',
+    },
+    keyWrites: {
+        createApiKey: 'write',
+        createSelfApiKey: 'write',
+        listApiKeys: 'read',
+    },
+    vectorWrites: {
+        entriesWithoutVector: 'read',
+        writeVectors: 'write',
+    },
+    entryWrites: {
+        writeEntry: 'write',
+        applyOutcome: 'write',
+        supersede: 'write',
+        archiveRaw: 'write',
+        forget: 'write',
+    },
+    contextReads: {
+        unfinishedHandoff: 'read',
+        ambientCandidates: 'server',
+        contextCandidates: 'read',
+        ambientTallies: 'read',
+    },
+    predictions: {
+        savePrediction: 'write',
+        closePrediction: 'write',
+        predictionById: 'read',
+        listPredictions: 'read',
+        predictionBaserate: 'write',
+    },
+    dagReads: {
+        sessionRawEntries: 'read',
+        sessionRawCount: 'read',
+        summaryWithDescendants: 'server',
+    },
+    auditLog: {
+        listAuditEvents: 'read',
+    },
+    quarantine: {
+        listQuarantined: 'read',
+        approveQuarantined: 'write',
+        rejectQuarantined: 'write',
+    },
+    graphReads: {
+        graphRows: 'read',
+    },
+    objects: {
+        listObjects: 'read',
+        objectById: 'read',
+        closeObject: 'write',
+        saveObject: 'write',
+        openIncident: 'write',
+        resolveIncident: 'write',
+        policiesInForce: 'read',
+        activeSkillsByName: 'read',
+        briefReceipts: 'read',
+    },
+    readiness: {
+        ping: 'read',
+    },
+};
+/** Sent by the executor itself and by no store method: the writer runs the store's open-time setup once, before any reader is sent a job. */
+export const STORE_SETUP_OP = 'setup';
+//# sourceMappingURL=worker-ops.js.map

package/dist/store/sqlite/worker-store.d.ts

@@ -0,0 +1,8 @@
+import type { HippoStore, StoreGroups } from '../port.js';
+import { type SqliteExecutor } from './executor.js';
+/** Whether `store` answers its `loop: 'off'` routes from worker threads, so a hippo.db open on the server thread inside one is a defect. */
+export declare function runsOffLoop(store: HippoStore): boolean;
+/** `sqliteStore` with the worker-backed methods in place of its in-process ones; close() closes `executor` and resolves once its threads have exited.
+ *  `executor` defaults to threads of the store's own, with the server's lock wait. */
+export declare function workerSqliteStore(hippoRoot: string, executor?: SqliteExecutor): HippoStore & StoreGroups;
+//# sourceMappingURL=worker-store.d.ts.map

package/dist/store/sqlite/worker-store.js

@@ -0,0 +1,79 @@
+// hippo.db as serve() runs it by default: the methods in the op table answer from worker threads, the rest still run on the calling thread.
+import { existsSync } from 'node:fs';
+import { getHippoDbPath } from '../../db/index.js';
+import { currentDeadline, currentRequestId } from '../../util/request-scope.js';
+import { createSqliteExecutor } from './executor.js';
+import { sqliteStore } from './store.js';
+import { vectorCopiesOf, vectorViewsOf } from './vector-pack.js';
+import { WORKER_OPS } from './worker-ops.js';
+const offLoopStores = new WeakSet();
+/** Whether `store` answers its `loop: 'off'` routes from worker threads, so a hippo.db open on the server thread inside one is a defect. */
+export function runsOffLoop(store) {
+    return offLoopStores.has(store);
+}
+function send(executor, op, args, mode) {
+    const deadline = currentDeadline();
+    const call = executor.call(op, args, { mode, requestId: currentRequestId(), deadlineAt: deadline?.at });
+    // The request's own timer then waits for this call's answer, which names what became of a write.
+    return deadline ? deadline.track(call) : call;
+}
+/** `inProcess` with each method the op table places on a worker answered from one, so a new method of a group needs its tag and no body here. */
+function onWorkers(executor, group, places, inProcess) {
+    const moved = Object.entries(places).flatMap(([method, place]) => (place === 'server' ? [] : [[
+            method,
+            (...args) => send(executor, `${group}.${method}`, args, place),
+        ]]));
+    return { ...inProcess, ...Object.fromEntries(moved) };
+}
+// The two reads that return vectors: the worker answers with one moved buffer, and the port's Map is rebuilt here. No ids reads nothing, as in process.
+function vectorGroups(executor, inProcess) {
+    const { vectors, vectorViews } = WORKER_OPS;
+    const pack = (op, ids, mode) => send(executor, op, [ids], mode);
+    return {
+        vectors: {
+            ...onWorkers(executor, 'vectors', vectors, inProcess),
+            storedVectors: async (ids) => (ids.length === 0 ? new Map() : vectorCopiesOf(await pack('vectors.storedVectors', ids, vectors.storedVectors))),
+        },
+        vectorViews: {
+            storedVectorViews: async (ids) => (ids.length === 0
+                ? new Map()
+                : vectorViewsOf(await pack('vectorViews.storedVectorViews', ids, vectorViews.storedVectorViews))),
+        },
+    };
+}
+// A probe must not create the store, and a worker's first job sets it up, so a root with no hippo.db is ready before any thread starts.
+function probing(hippoRoot, served) {
+    return {
+        ping: async () => {
+            if (existsSync(getHippoDbPath(hippoRoot)))
+                await served.ping();
+        },
+    };
+}
+/** `sqliteStore` with the worker-backed methods in place of its in-process ones; close() closes `executor` and resolves once its threads have exited.
+ *  `executor` defaults to threads of the store's own, with the server's lock wait. */
+export function workerSqliteStore(hippoRoot, executor = createSqliteExecutor(hippoRoot)) {
+    const inProcess = sqliteStore(hippoRoot);
+    const { keyAudit, keyWrites, vectorWrites, entryWrites, contextReads, predictions, dagReads, auditLog, quarantine, graphReads, objects } = WORKER_OPS;
+    const store = {
+        ...inProcess,
+        ...onWorkers(executor, 'base', WORKER_OPS.base, inProcess),
+        ...vectorGroups(executor, inProcess.vectors),
+        keyAudit: onWorkers(executor, 'keyAudit', keyAudit, inProcess.keyAudit),
+        keyWrites: onWorkers(executor, 'keyWrites', keyWrites, inProcess.keyWrites),
+        vectorWrites: onWorkers(executor, 'vectorWrites', vectorWrites, inProcess.vectorWrites),
+        entryWrites: onWorkers(executor, 'entryWrites', entryWrites, inProcess.entryWrites),
+        contextReads: onWorkers(executor, 'contextReads', contextReads, inProcess.contextReads),
+        predictions: onWorkers(executor, 'predictions', predictions, inProcess.predictions),
+        dagReads: onWorkers(executor, 'dagReads', dagReads, inProcess.dagReads),
+        auditLog: onWorkers(executor, 'auditLog', auditLog, inProcess.auditLog),
+        quarantine: onWorkers(executor, 'quarantine', quarantine, inProcess.quarantine),
+        graphReads: onWorkers(executor, 'graphReads', graphReads, inProcess.graphReads),
+        objects: onWorkers(executor, 'objects', objects, inProcess.objects),
+        readiness: probing(hippoRoot, onWorkers(executor, 'readiness', WORKER_OPS.readiness, inProcess.readiness)),
+        close: () => executor.close(),
+    };
+    offLoopStores.add(store);
+    return store;
+}
+//# sourceMappingURL=worker-store.js.map

package/dist/store/summaries.d.ts

@@ -1,59 +1,13 @@
-import type { MemoryEntry } from '../memory.js';
-/**
- * Load summaries flagged dirty for the given tenant. Sorted by latest_at
- * DESC (NULLS LAST) so the rebuild cap (HIPPO_DAG_REBUILD_CAP, default 20)
- * takes the most-recently-changed summaries first.
- *
- * Returns full MemoryEntry shape via MEMORY_SELECT_COLUMNS + rowToEntry
- * (v28 fields are part of the standard read path).
- */
-export declare function loadDirtySummaries(hippoRoot: string, tenantId: string): MemoryEntry[];
-/**
- * Mark a summary as dirty. Idempotent (re-marking dirty is a no-op + no
- * second audit row). Tenant-scoped to prevent cross-tenant writes via
- * parent-lookup. Called from invalidation.ts / writeEntry /
- * forgetMemory / archiveRawMemory whenever a child is invalidated,
- * superseded, forgotten, or archived.
- *
- * Quietly no-ops if the target row doesn't exist or isn't a level-2/3
- * summary. Emits a 'summary_marked_dirty' audit row on actual
- * state transitions (0 -> 1) via the audit() helper, which try/catches
- * for missing audit_log (the v27 self-heal scenario).
- */
-export declare function markSummaryDirty(hippoRoot: string, summaryId: string, tenantId: string, actor?: string): void;
-/**
- * Host-wide loader for L2 topic summaries without an L3 parent.
- * Used by consolidate phase 1.9 (buildEntityProfiles) to cluster L2s into
- * L3 entity profiles. Mirrors loadAllDirtySummaries: SQL-level
- * filter is cheaper than reusing in-memory `survivors` (which doesn't
- * contain L2s freshly created by phase 1.7 buildDag).
- *
- * Returns entries with tenantId attached so per-cluster writes stay
- * tenant-scoped via summary.tenantId.
- */
+import type { MemoryEntry } from '../core/memory.js';
+/** Host-wide loader for L2 topic summaries without an L3 parent, for consolidate phase 1.9 (buildEntityProfiles); SQL-level filter, since in-memory
+ * `survivors` lacks L2s created by phase 1.7. Entries carry tenantId so per-cluster writes stay tenant-scoped. */
 export declare function loadAllL2Summaries(hippoRoot: string): MemoryEntry[];
-/**
- * Host-wide variant of loadDirtySummaries. Iterates all tenants
- * in one query so consolidate.ts (host-wide per L106-109) does not need a
- * per-tenant loop. Each returned MemoryEntry carries its own tenantId (via
- * rowToEntry), so per-summary children + rebuild UPDATE stay tenant-scoped.
- *
- * Sort: latest_at DESC NULLS LAST, id ASC — same as per-tenant variant so
- * HIPPO_DAG_REBUILD_CAP takes most-recently-changed summaries first.
- */
+/** Dirty summaries across all tenants in one query, newest change first (latest_at DESC NULLS LAST, id ASC) so HIPPO_DAG_REBUILD_CAP takes the most
+ * recently changed. Each entry carries its own tenantId so the children read and rebuild UPDATE stay tenant-scoped. */
 export declare function loadAllDirtySummaries(hippoRoot: string): MemoryEntry[];
-/**
- * Load live children of a DAG summary. Used by
- * rebuildDirtySummaries to regenerate content from the CURRENT child set
- * (not the children at create-time). Skips archived. Tenant-scoped
- * (defence in depth — dag_parent_id is unique-ish but tenant guard is
- * cheap). created column is TEXT NOT NULL since db.ts schema v1.
- */
+/** Live (non-archived) children of a DAG summary, so a rebuild regenerates from the CURRENT child set; tenant-scoped as defence in depth. */
 export declare function loadChildrenOfSummary(hippoRoot: string, summaryId: string, tenantId: string): MemoryEntry[];
-/**
- * Patch applied by applyRebuildResult. Two-branch shape
- * (bumpRebuildCount false for zero-child case, true for normal rebuild).
- */
+/** Patch applied by applyRebuildResult; `bumpRebuildCount` is false for the zero-child case, true for a normal rebuild. */
 export interface RebuildPatch {
     content: string;
     descendant_count: number;
@@ -63,28 +17,13 @@ export interface RebuildPatch {
     zeroChildren: boolean;
     actor: string;
 }
-/**
- * Apply a rebuild result to a dirty summary. Atomic: one
- * prepared UPDATE statement plus syncFtsRow inside one write scope.
- * WHERE includes `AND summary_dirty = 1` so concurrent sleep's race-loser
- * becomes a no-op (no rebuild_count bump, no audit row).
- *
- * Returns `{ changed, refused }`. `changed` is true when this call's UPDATE
- * (content or metadata-only) affected a row; false on race-loss / unknown id
- * / archived / wrong dag_level. `refused` is true only when a tombstone hit
- * suppressed the content write AND the metadata UPDATE still landed — see
- * the return-semantics comment below for the full contract.
- */
+/** Apply a rebuild result to a dirty summary in one write scope (UPDATE plus syncFtsRow); `AND summary_dirty = 1` makes a concurrent race-loser a no-op.
+ * Returns `{ changed, refused }`: `refused` only when a tombstone hit suppressed the content write while the metadata UPDATE still landed. */
 export declare function applyRebuildResult(hippoRoot: string, summary: MemoryEntry, patch: RebuildPatch): {
     changed: boolean;
     refused: boolean;
 };
-/**
- * Clear summary_dirty on a freshly-built summary. Called by buildDag right after the child-link loop:
- * each member's writeEntry marks the new parent dirty, so the same cycle's rebuild would redo every new summary.
- *
- * Idempotent: no-op + no audit if summary isn't dirty. Audit
- * source='buildDag-clean' distinguishes it from the rebuild's source.
- */
+/** Clear summary_dirty on a new summary after buildDag's child-link loop (each member's writeEntry marks the parent dirty, so the same cycle would rebuild it).
+ * Idempotent (no-op, no audit if not dirty); audit source='buildDag-clean' distinguishes it from the rebuild's. */
 export declare function clearSummaryDirtyAfterBuild(hippoRoot: string, summaryId: string, tenantId: string, actor?: string, source?: string): void;
 //# sourceMappingURL=summaries.d.ts.map

package/dist/store/summaries.js

@@ -1,104 +1,18 @@
-import { closeHippoDb, withWriteScope } from '../db.js';
-import { assertTenantId } from '../tenant.js';
-import { findRejectedValue, rejectionDigest } from '../rejection.js';
-import { log } from '../log.js';
+import { withWriteScope } from '../db/index.js';
+import { assertTenantId } from './tenant.js';
+import { findRejectedValue, rejectionDigest } from './rejection.js';
+import { log } from '../util/log.js';
 import { MEMORY_SELECT_COLUMNS, rowToEntry } from './rows.js';
 import { audit } from './audit-event.js';
 import { syncFtsRow } from './entry-row.js';
-import { openStore } from './open.js';
-// ---------------------------------------------------------------------------
-// Dirty-flag helpers for DAG summaries: child writes mark a summary dirty, and the
-// sleep-cycle rebuild enumerates candidates without scanning every memory row.
-// ---------------------------------------------------------------------------
-/**
- * Load summaries flagged dirty for the given tenant. Sorted by latest_at
- * DESC (NULLS LAST) so the rebuild cap (HIPPO_DAG_REBUILD_CAP, default 20)
- * takes the most-recently-changed summaries first.
- *
- * Returns full MemoryEntry shape via MEMORY_SELECT_COLUMNS + rowToEntry
- * (v28 fields are part of the standard read path).
- */
-export function loadDirtySummaries(hippoRoot, tenantId) {
-    assertTenantId('loadDirtySummaries', tenantId);
-    const db = openStore(hippoRoot);
-    try {
-        // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
-        // MemoryRow's field set.
-        const rows = db.prepare(`
-      SELECT ${MEMORY_SELECT_COLUMNS}
-        FROM memories
-       WHERE summary_dirty = 1
-         AND tenant_id = ?
-         AND kind != 'archived'
-       ORDER BY latest_at DESC NULLS LAST, id ASC
-    `).all(tenantId);
-        return rows.map(rowToEntry);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/**
- * Mark a summary as dirty. Idempotent (re-marking dirty is a no-op + no
- * second audit row). Tenant-scoped to prevent cross-tenant writes via
- * parent-lookup. Called from invalidation.ts / writeEntry /
- * forgetMemory / archiveRawMemory whenever a child is invalidated,
- * superseded, forgotten, or archived.
- *
- * Quietly no-ops if the target row doesn't exist or isn't a level-2/3
- * summary. Emits a 'summary_marked_dirty' audit row on actual
- * state transitions (0 -> 1) via the audit() helper, which try/catches
- * for missing audit_log (the v27 self-heal scenario).
- */
-export function markSummaryDirty(hippoRoot, summaryId, tenantId, actor = 'cli') {
-    assertTenantId('markSummaryDirty', tenantId);
-    const db = openStore(hippoRoot);
-    try {
-        // RETURNING dag_level reads the actual level in the same round trip.
-        // SAFETY: result's shape matches the single `dag_level` column returned
-        // above.
-        const result = db.prepare(`
-      UPDATE memories
-         SET summary_dirty = 1
-       WHERE id = ?
-         AND tenant_id = ?
-         AND dag_level IN (2, 3)
-         AND summary_dirty = 0
-         AND kind != 'archived'
-      RETURNING dag_level
-    `).get(summaryId, tenantId);
-        if (result) {
-            // audit() wraps appendAuditEvent in try/catch (v27 heal scenario).
-            // metadata.source tells this dirty-mark apart from the other wiring layers' marks.
-            audit(db, 'summary_marked_dirty', summaryId, { dag_level: result.dag_level, source: 'E1' }, actor, tenantId);
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-// ---------------------------------------------------------------------------
-// Sleep-cycle rebuild surface.
-//
-// loadAllDirtySummaries / loadChildrenOfSummary / applyRebuildResult /
-// clearSummaryDirtyAfterBuild live HERE (not in dag.ts) because they need
-// module-private MEMORY_SELECT_COLUMNS, MemoryRow, rowToEntry, audit,
-// syncFtsRow, assertTenantId. dag.ts owns only the thin orchestrator
-// rebuildDirtySummaries() that calls into these.
-// ---------------------------------------------------------------------------
-/**
- * Host-wide loader for L2 topic summaries without an L3 parent.
- * Used by consolidate phase 1.9 (buildEntityProfiles) to cluster L2s into
- * L3 entity profiles. Mirrors loadAllDirtySummaries: SQL-level
- * filter is cheaper than reusing in-memory `survivors` (which doesn't
- * contain L2s freshly created by phase 1.7 buildDag).
- *
- * Returns entries with tenantId attached so per-cluster writes stay
- * tenant-scoped via summary.tenantId.
- */
+import { onHandle, openStore } from './open.js';
+import { DIGEST_DISPLAY_CHARS } from '../util/token-text.js';
+// Sleep-cycle rebuild surface: lives here, not in src/consolidate/dag.ts, because it needs module-private MEMORY_SELECT_COLUMNS, MemoryRow, rowToEntry,
+// audit, syncFtsRow and assertTenantId. dag.ts keeps only the thin orchestrator rebuildDirtySummaries().
+/** Host-wide loader for L2 topic summaries without an L3 parent, for consolidate phase 1.9 (buildEntityProfiles); SQL-level filter, since in-memory
+ * `survivors` lacks L2s created by phase 1.7. Entries carry tenantId so per-cluster writes stay tenant-scoped. */
 export function loadAllL2Summaries(hippoRoot) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
         // MemoryRow's field set.
         const rows = db.prepare(`
@@ -111,23 +25,12 @@ export function loadAllL2Summaries(hippoRoot) {
        ORDER BY created ASC, id ASC
     `).all();
         return rows.map(rowToEntry);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Host-wide variant of loadDirtySummaries. Iterates all tenants
- * in one query so consolidate.ts (host-wide per L106-109) does not need a
- * per-tenant loop. Each returned MemoryEntry carries its own tenantId (via
- * rowToEntry), so per-summary children + rebuild UPDATE stay tenant-scoped.
- *
- * Sort: latest_at DESC NULLS LAST, id ASC — same as per-tenant variant so
- * HIPPO_DAG_REBUILD_CAP takes most-recently-changed summaries first.
- */
+/** Dirty summaries across all tenants in one query, newest change first (latest_at DESC NULLS LAST, id ASC) so HIPPO_DAG_REBUILD_CAP takes the most
+ * recently changed. Each entry carries its own tenantId so the children read and rebuild UPDATE stay tenant-scoped. */
 export function loadAllDirtySummaries(hippoRoot) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
         // MemoryRow's field set.
         const rows = db.prepare(`
@@ -138,22 +41,12 @@ export function loadAllDirtySummaries(hippoRoot) {
        ORDER BY latest_at DESC NULLS LAST, id ASC
     `).all();
         return rows.map(rowToEntry);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Load live children of a DAG summary. Used by
- * rebuildDirtySummaries to regenerate content from the CURRENT child set
- * (not the children at create-time). Skips archived. Tenant-scoped
- * (defence in depth — dag_parent_id is unique-ish but tenant guard is
- * cheap). created column is TEXT NOT NULL since db.ts schema v1.
- */
+/** Live (non-archived) children of a DAG summary, so a rebuild regenerates from the CURRENT child set; tenant-scoped as defence in depth. */
 export function loadChildrenOfSummary(hippoRoot, summaryId, tenantId) {
     assertTenantId('loadChildrenOfSummary', tenantId);
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
         // MemoryRow's field set.
         const rows = db.prepare(`
@@ -166,32 +59,15 @@ export function loadChildrenOfSummary(hippoRoot, summaryId, tenantId) {
        ORDER BY created ASC
     `).all(summaryId, tenantId);
         return rows.map(rowToEntry);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Apply a rebuild result to a dirty summary. Atomic: one
- * prepared UPDATE statement plus syncFtsRow inside one write scope.
- * WHERE includes `AND summary_dirty = 1` so concurrent sleep's race-loser
- * becomes a no-op (no rebuild_count bump, no audit row).
- *
- * Returns `{ changed, refused }`. `changed` is true when this call's UPDATE
- * (content or metadata-only) affected a row; false on race-loss / unknown id
- * / archived / wrong dag_level. `refused` is true only when a tombstone hit
- * suppressed the content write AND the metadata UPDATE still landed — see
- * the return-semantics comment below for the full contract.
- */
+/** Apply a rebuild result to a dirty summary in one write scope (UPDATE plus syncFtsRow); `AND summary_dirty = 1` makes a concurrent race-loser a no-op.
+ * Returns `{ changed, refused }`: `refused` only when a tombstone hit suppressed the content write while the metadata UPDATE still landed. */
 export function applyRebuildResult(hippoRoot, summary, patch) {
     assertTenantId('applyRebuildResult', summary.tenantId);
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return withWriteScope(db, 'rebuild_summary', () => applyRebuildInSavepoint(db, summary, patch));
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 // ONE prepared UPDATE per branch. Test #8 inspects the SQL string.
 const REBUILD_CONTENT_SQL = `UPDATE memories
@@ -224,13 +100,8 @@ function applyRebuildInSavepoint(db, summary, patch) {
     const tombstone = patch.bumpRebuildCount
         ? findRejectedValue(db, summary.tenantId, rejectionDigest(patch.content))
         : null;
-    // On a hit: do NOT write the new content. Fall through to the SAME
-    // metadata-only behavior the zero-child branch already has —
-    // descendant_count/earliest_at/latest_at update + summary_dirty
-    // cleared, no content write, no rebuild_count bump. Clearing dirty
-    // (rather than leaving it set) is deliberate: leaving it dirty would
-    // make every following sleep cycle re-attempt and re-refuse the
-    // identical rebuild forever (the DAG-loop this fix closes).
+    // On a tombstone hit, write no content: take the zero-child metadata-only path (descendant_count/earliest_at/latest_at, summary_dirty cleared, no
+    // rebuild_count bump). Clearing dirty is deliberate: leaving it set would make every later sleep re-attempt and re-refuse the same rebuild forever.
     const applyContentWrite = patch.bumpRebuildCount && !tombstone;
     const result = applyContentWrite
         ? db.prepare(REBUILD_CONTENT_SQL).run(patch.content, patch.descendant_count, patch.earliest_at, patch.latest_at, nowIso, summary.id, summary.tenantId)
@@ -247,16 +118,16 @@ function applyRebuildInSavepoint(db, summary, patch) {
 }
 /** Audit and log a rebuild whose content matched a rejected value; metadata still landed. */
 function auditRefusedRebuild(db, summary, patch, tombstone) {
-    // refused === true here (same condition, narrowed for the tombstone.*
-    // access below). Best-effort refusal audit, written INLINE inside
-    // this still-open SAVEPOINT — nothing here rolls back on a refusal
-    // (the metadata UPDATE above already committed to this savepoint), so the
-    // post-rollback auditRejectionRefusal helper (writeEntry/supersede's
-    // tool) is the wrong one here; a direct audit() call is correct and
-    // commits with the rest of this savepoint.
-    audit(db, 'reject_refusal', summary.id, { digest: tombstone.digest, reason: tombstone.reason }, patch.actor, summary.tenantId);
+    // refused === true here (narrowed for the tombstone.* access). Best-effort refusal audit written INLINE in this still-open SAVEPOINT (the metadata
+    // UPDATE already committed to it), so a direct audit() call is correct, not the post-rollback auditRejectionRefusal.
+    audit(db, 'reject_refusal', {
+        targetId: summary.id,
+        metadata: { digest: tombstone.digest, reason: tombstone.reason },
+        actor: patch.actor,
+        tenantId: summary.tenantId
+    });
     log.warn(`applyRebuildResult: refused rebuild content for ${summary.id} — matches a rejected value ` +
-        `(digest ${tombstone.digest.slice(0, 12)}...); metadata updated, content unchanged`);
+        `(digest ${tombstone.digest.slice(0, DIGEST_DISPLAY_CHARS)}...); metadata updated, content unchanged`);
 }
 function syncRebuiltSummary(db, summary, patch, applyContentWrite, nowIso) {
     // A bare UPDATE on memories does NOT update memories_fts, so resync from the patched entry;
@@ -274,28 +145,21 @@ function syncRebuiltSummary(db, summary, patch, applyContentWrite, nowIso) {
             : summary.rebuild_count,
     };
     syncFtsRow(db, patchedEntry);
-    audit(db, 'summary_rebuilt', summary.id, {
-        // Actual level from the summary in scope, never hardcoded: L2 -> 2, L3 -> 3.
-        dag_level: summary.dag_level,
-        source: 'E3-rebuild',
-        zero_children: patch.zeroChildren,
-        descendant_count: patch.descendant_count,
-    }, patch.actor, summary.tenantId);
+    audit(db, 'summary_rebuilt', { targetId: summary.id, metadata: {
+            // Actual level from the summary in scope, never hardcoded: L2 -> 2, L3 -> 3.
+            dag_level: summary.dag_level,
+            source: 'E3-rebuild',
+            zero_children: patch.zeroChildren,
+            descendant_count: patch.descendant_count,
+        }, actor: patch.actor, tenantId: summary.tenantId });
 }
-/**
- * Clear summary_dirty on a freshly-built summary. Called by buildDag right after the child-link loop:
- * each member's writeEntry marks the new parent dirty, so the same cycle's rebuild would redo every new summary.
- *
- * Idempotent: no-op + no audit if summary isn't dirty. Audit
- * source='buildDag-clean' distinguishes it from the rebuild's source.
- */
+/** Clear summary_dirty on a new summary after buildDag's child-link loop (each member's writeEntry marks the parent dirty, so the same cycle would rebuild it).
+ * Idempotent (no-op, no audit if not dirty); audit source='buildDag-clean' distinguishes it from the rebuild's. */
 export function clearSummaryDirtyAfterBuild(hippoRoot, summaryId, tenantId, actor = 'cli', source = 'buildDag-clean') {
     assertTenantId('clearSummaryDirtyAfterBuild', tenantId);
-    const db = openStore(hippoRoot);
-    try {
+    onHandle(hippoRoot, (db) => {
         // RETURNING dag_level reads the actual level so audit metadata stays accurate without an extra SELECT.
-        // SAFETY: result's shape matches the single `dag_level` column returned
-        // below.
+        // SAFETY: result's shape matches the single `dag_level` column returned below.
         const result = db.prepare(`
       UPDATE memories
          SET summary_dirty = 0
@@ -308,11 +172,8 @@ export function clearSummaryDirtyAfterBuild(hippoRoot, summaryId, tenantId, acto
     `).get(summaryId, tenantId);
         if (result) {
             // source tells buildDag-clean (L2) from buildEntityProfiles-clean (L3) and any future build path.
-            audit(db, 'summary_marked_clean', summaryId, { dag_level: result.dag_level, source }, actor, tenantId);
+            audit(db, 'summary_marked_clean', { targetId: summaryId, metadata: { dag_level: result.dag_level, source }, actor, tenantId });
         }
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 //# sourceMappingURL=summaries.js.map

package/dist/{summary-dirty.d.ts → store/summary-dirty.d.ts}

@@ -1,4 +1,4 @@
-import type { DatabaseSyncLike } from './db.js';
+import type { DatabaseSyncLike } from '../db/index.js';
 /** Runs in the caller's transaction so the mark commits or rolls back with the child change; only a 0 to 1 flip is audited. */
 export declare function markSummaryDirtyInTx(db: DatabaseSyncLike, summaryId: string, tenantId: string, actor: string): void;
 //# sourceMappingURL=summary-dirty.d.ts.map

package/dist/{summary-dirty.js → store/summary-dirty.js}

@@ -1,4 +1,4 @@
-// Leaf module so store.ts and raw-archive.ts can both mark a parent summary dirty without importing each other.
+// Leaf module so entry-writes.ts and raw-archive.ts can both mark a parent summary dirty without importing each other.
 import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
 /** Runs in the caller's transaction so the mark commits or rolls back with the child change; only a 0 to 1 flip is audited. */
 export function markSummaryDirtyInTx(db, summaryId, tenantId, actor) {

package/dist/store/tenant-lookup.d.ts

@@ -1,4 +1,4 @@
-import type { DatabaseSyncLike } from '../db.js';
+import { type DatabaseSyncLike } from '../db/index.js';
 /** The api_keys fields a tenant, revocation, rank or self-service ownership check reads. */
 export interface ApiKeyOwner {
     tenantId: string;
@@ -13,4 +13,9 @@ export declare function selectMemoryReach(db: DatabaseSyncLike, id: string): {
     tenantId: string;
     scope: string | null;
 } | undefined;
+/** `selectMemoryReach` for the store under `hippoRoot`, with no mirror setup and no full row read. */
+export declare function memoryReach(hippoRoot: string, id: string): {
+    tenantId: string;
+    scope: string | null;
+} | undefined;
 //# sourceMappingURL=tenant-lookup.d.ts.map

package/dist/store/tenant-lookup.js

@@ -1,4 +1,5 @@
 // Owner lookups by id: the tenant and scope checks in src/api and the CLI's key-tenant lookup share these queries.
+import { onHandle } from './open.js';
 /** The owner row of `keyId`, or undefined when no such key exists. */
 export function selectApiKeyOwner(db, keyId) {
     // SAFETY: row's shape matches the four columns named in the SELECT.
@@ -13,4 +14,10 @@ export function selectMemoryReach(db, id) {
     const row = db.prepare(`SELECT tenant_id, scope FROM memories WHERE id = ?`).get(id);
     return row && { tenantId: row.tenant_id, scope: row.scope };
 }
+/** `selectMemoryReach` for the store under `hippoRoot`, with no mirror setup and no full row read. */
+export function memoryReach(hippoRoot, id) {
+    return onHandle(hippoRoot, (db) => {
+        return selectMemoryReach(db, id);
+    });
+}
 //# sourceMappingURL=tenant-lookup.js.map

package/dist/store/tenant.d.ts

@@ -0,0 +1,11 @@
+import type { DatabaseSyncLike } from '../db/index.js';
+import type { JsonValue } from '../util/json.js';
+export interface ResolveOpts {
+    db?: DatabaseSyncLike;
+    apiKey?: string;
+}
+export declare function resolveTenantId(opts: ResolveOpts): string;
+/** Runtime guard for tenant id args: an older JS caller can pass a `sessionId` as the tenant (`loadLatestHandoff(root, 'sess-abc')`) and silently get null.
+ * Rejects values starting `sess-` / `sess_`; a tenant literally named `sess-...` is refused, an accepted tradeoff. */
+export declare function assertTenantId(fnName: string, value: JsonValue): asserts value is string;
+//# sourceMappingURL=tenant.d.ts.map