hippo-memory 1.72.0 → 2.1.0

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

@@ -1,23 +1,31 @@
-// 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.
+// 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 { currentDeadline, currentRequestId, currentSignal } 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';
+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. */
+/** 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 });
+    const call = executor.call(op, args, {
+        mode,
+        requestId: currentRequestId(),
+        deadlineAt: deadline?.at,
+        signal: currentSignal(),
+    });
     // 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. */
+/** `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,
@@ -25,23 +33,25 @@ function onWorkers(executor, group, places, inProcess) {
         ]]));
     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.
+// 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))),
+            storedVectors: async (ids) => ids.length === 0 ? new Map() : vectorCopiesOf(await pack('vectors.storedVectors', ids, vectors.storedVectors)),
         },
         vectorViews: {
-            storedVectorViews: async (ids) => (ids.length === 0
+            storedVectorViews: async (ids) => ids.length === 0
                 ? new Map()
-                : vectorViewsOf(await pack('vectorViews.storedVectorViews', ids, vectorViews.storedVectorViews))),
+                : 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.
+// 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 () => {
@@ -50,11 +60,11 @@ function probing(hippoRoot, served) {
         },
     };
 }
-/** `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. */
+/** `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 { keyAudit, keyWrites, vectorWrites, entryWrites, contextReads, predictions, dagReads, auditLog, quarantine, graphReads, objects, } = WORKER_OPS;
     const store = {
         ...inProcess,
         ...onWorkers(executor, 'base', WORKER_OPS.base, inProcess),

package/dist/store/summaries.d.ts

@@ -1,13 +1,25 @@
-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. */
+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[];
-/** Dirty summaries across all tenants, newest change first (latest_at DESC NULLS LAST, id ASC), at most `limit` (all when omitted)
- * so HIPPO_DAG_REBUILD_CAP reads only the most recently changed. Each entry carries its tenantId so later writes stay tenant-scoped. */
+/** Dirty summaries across all tenants, newest change first (latest_at DESC NULLS LAST, id ASC), at most `limit` (all
+ * when omitted) so HIPPO_DAG_REBUILD_CAP reads only the most recently changed. Each entry carries its tenantId so later
+ * writes stay tenant-scoped. */
 export declare function loadAllDirtySummaries(hippoRoot: string, limit?: number): MemoryEntry[];
-/** Live (non-archived) children of a DAG summary, so a rebuild regenerates from the CURRENT child set; tenant-scoped as defence in depth. */
+/** 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; `bumpRebuildCount` is false for the zero-child case, true for a normal rebuild. */
+/** loadChildrenOfSummary for many summaries in one IN query per tenant chunk; the map key is
+ * `${tenantId}\u0000${summaryId}`, each list in created order. */
+export declare function loadChildrenOfSummaries(hippoRoot: string, summaries: ReadonlyArray<{
+    id: string;
+    tenant_id: string;
+}>): Map<string, MemoryEntry[]>;
+/** Key into the map loadChildrenOfSummaries returns. */
+export declare function childrenKey(tenantId: string, summaryId: string): string;
+/** 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;
@@ -17,13 +29,15 @@ export interface RebuildPatch {
     zeroChildren: boolean;
     actor: string;
 }
-/** 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. */
+/** 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 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. */
+/** 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,3 +1,4 @@
+import { DAG_LEVEL } from '../core/memory.js';
 import { withWriteScope } from '../db/index.js';
 import { assertTenantId } from './tenant.js';
 import { findRejectedValue, rejectionDigest } from './rejection.js';
@@ -6,11 +7,15 @@ import { MEMORY_SELECT_COLUMNS, rowToEntry } from './rows.js';
 import { audit } from './audit-event.js';
 import { syncFtsRow } from './entry-row.js';
 import { onHandle, openStore } from './open.js';
+import { chunked } from '../util/chunked.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. */
+import { placeholders } from '../util/sql.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) {
     return onHandle(hippoRoot, (db) => {
         // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
@@ -18,7 +23,7 @@ export function loadAllL2Summaries(hippoRoot) {
         const rows = db.prepare(`
       SELECT ${MEMORY_SELECT_COLUMNS}
         FROM memories
-       WHERE dag_level = 2
+       WHERE dag_level = ${DAG_LEVEL.topic}
          AND dag_parent_id IS NULL
          AND kind != 'archived'
          AND superseded_by IS NULL
@@ -27,8 +32,9 @@ export function loadAllL2Summaries(hippoRoot) {
         return rows.map(rowToEntry);
     }, openStore);
 }
-/** Dirty summaries across all tenants, newest change first (latest_at DESC NULLS LAST, id ASC), at most `limit` (all when omitted)
- * so HIPPO_DAG_REBUILD_CAP reads only the most recently changed. Each entry carries its tenantId so later writes stay tenant-scoped. */
+/** Dirty summaries across all tenants, newest change first (latest_at DESC NULLS LAST, id ASC), at most `limit` (all
+ * when omitted) so HIPPO_DAG_REBUILD_CAP reads only the most recently changed. Each entry carries its tenantId so later
+ * writes stay tenant-scoped. */
 export function loadAllDirtySummaries(hippoRoot, limit) {
     return onHandle(hippoRoot, (db) => {
         // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
@@ -44,7 +50,8 @@ export function loadAllDirtySummaries(hippoRoot, limit) {
         return rows.map(rowToEntry);
     }, openStore);
 }
-/** Live (non-archived) children of a DAG summary, so a rebuild regenerates from the CURRENT child set; tenant-scoped as defence in depth. */
+/** 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);
     return onHandle(hippoRoot, (db) => {
@@ -62,10 +69,52 @@ export function loadChildrenOfSummary(hippoRoot, summaryId, tenantId) {
         return rows.map(rowToEntry);
     }, openStore);
 }
-/** 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. */
+/** loadChildrenOfSummary for many summaries in one IN query per tenant chunk; the map key is
+ * `${tenantId}\u0000${summaryId}`, each list in created order. */
+export function loadChildrenOfSummaries(hippoRoot, summaries) {
+    const byTenant = new Map();
+    for (const s of summaries) {
+        assertTenantId('loadChildrenOfSummaries', s.tenant_id);
+        const ids = byTenant.get(s.tenant_id) ?? [];
+        ids.push(s.id);
+        byTenant.set(s.tenant_id, ids);
+    }
+    const out = new Map();
+    onHandle(hippoRoot, (db) => {
+        for (const [tenantId, ids] of byTenant) {
+            for (const slice of chunked(ids)) {
+                // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
+                const rows = db.prepare(`
+          SELECT ${MEMORY_SELECT_COLUMNS}
+            FROM memories
+           WHERE dag_parent_id IN (${placeholders(slice.length)})
+             AND tenant_id = ?
+             AND kind != 'archived'
+             AND superseded_by IS NULL
+           ORDER BY created ASC
+        `).all(...slice, tenantId);
+                for (const entry of rows.map(rowToEntry)) {
+                    const key = childrenKey(tenantId, entry.dag_parent_id ?? '');
+                    const list = out.get(key);
+                    if (list)
+                        list.push(entry);
+                    else
+                        out.set(key, [entry]);
+                }
+            }
+        }
+    }, openStore);
+    return out;
+}
+/** Key into the map loadChildrenOfSummaries returns. */
+export function childrenKey(tenantId, summaryId) {
+    return `${tenantId}\u0000${summaryId}`;
+}
+/** 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);
+    assertTenantId('applyRebuildResult', summary.tenant_id);
     return onHandle(hippoRoot, (db) => {
         return withWriteScope(db, 'rebuild_summary', () => applyRebuildInSavepoint(db, summary, patch));
     }, openStore);
@@ -81,7 +130,7 @@ const REBUILD_CONTENT_SQL = `UPDATE memories
                   summary_dirty = 0
             WHERE id = ?
               AND tenant_id = ?
-              AND dag_level IN (2, 3)
+              AND dag_level IN (${DAG_LEVEL.topic}, ${DAG_LEVEL.entity})
               AND summary_dirty = 1
               AND kind != 'archived'`;
 const REBUILD_METADATA_SQL = `UPDATE memories
@@ -91,7 +140,7 @@ const REBUILD_METADATA_SQL = `UPDATE memories
                   summary_dirty = 0
             WHERE id = ?
               AND tenant_id = ?
-              AND dag_level IN (2, 3)
+              AND dag_level IN (${DAG_LEVEL.topic}, ${DAG_LEVEL.entity})
               AND summary_dirty = 1
               AND kind != 'archived'`;
 function applyRebuildInSavepoint(db, summary, patch) {
@@ -99,14 +148,15 @@ function applyRebuildInSavepoint(db, summary, patch) {
     // Check tombstones before choosing the UPDATE: this direct UPDATE bypasses upsertEntryRow's guard, and
     // a deterministic rebuild would otherwise re-assert a rejected value every sleep cycle.
     const tombstone = patch.bumpRebuildCount
-        ? findRejectedValue(db, summary.tenantId, rejectionDigest(patch.content))
+        ? findRejectedValue(db, summary.tenant_id, rejectionDigest(patch.content))
         : null;
-    // 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.
+    // 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)
-        : db.prepare(REBUILD_METADATA_SQL).run(patch.descendant_count, patch.earliest_at, patch.latest_at, summary.id, summary.tenantId);
+        ? db.prepare(REBUILD_CONTENT_SQL).run(patch.content, patch.descendant_count, patch.earliest_at, patch.latest_at, nowIso, summary.id, summary.tenant_id)
+        : db.prepare(REBUILD_METADATA_SQL).run(patch.descendant_count, patch.earliest_at, patch.latest_at, summary.id, summary.tenant_id);
     // `changed` means THIS call's UPDATE hit a row, so a refusal still settles the cycle (false would retry
     // the doomed rebuild forever); `refused` lets the caller count it as refused rather than rebuilt.
     const changed = (result.changes ?? 0) > 0;
@@ -119,13 +169,14 @@ 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 (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.
+    // 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
+        tenantId: summary.tenant_id
     });
     log.warn(`applyRebuildResult: refused rebuild content for ${summary.id} — matches a rejected value ` +
         `(digest ${tombstone.digest.slice(0, DIGEST_DISPLAY_CHARS)}...); metadata updated, content unchanged`);
@@ -139,7 +190,7 @@ function syncRebuiltSummary(db, summary, patch, applyContentWrite, nowIso) {
         descendant_count: patch.descendant_count,
         earliest_at: patch.earliest_at,
         latest_at: patch.latest_at,
-        summary_dirty: 0,
+        summary_dirty: false,
         last_rebuilt_at: applyContentWrite ? nowIso : summary.last_rebuilt_at,
         rebuild_count: applyContentWrite
             ? (summary.rebuild_count ?? 0) + 1
@@ -152,10 +203,11 @@ function syncRebuiltSummary(db, summary, patch, applyContentWrite, nowIso) {
             source: 'E3-rebuild',
             zero_children: patch.zeroChildren,
             descendant_count: patch.descendant_count,
-        }, actor: patch.actor, tenantId: summary.tenantId });
+        }, actor: patch.actor, tenantId: summary.tenant_id });
 }
-/** 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. */
+/** 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);
     onHandle(hippoRoot, (db) => {
@@ -166,14 +218,19 @@ export function clearSummaryDirtyAfterBuild(hippoRoot, summaryId, tenantId, acto
          SET summary_dirty = 0
        WHERE id = ?
          AND tenant_id = ?
-         AND dag_level IN (2, 3)
+         AND dag_level IN (${DAG_LEVEL.topic}, ${DAG_LEVEL.entity})
          AND summary_dirty = 1
          AND kind != 'archived'
       RETURNING dag_level
     `).get(summaryId, tenantId);
         if (result) {
             // source tells buildDag-clean (L2) from buildEntityProfiles-clean (L3) and any future build path.
-            audit(db, 'summary_marked_clean', { targetId: summaryId, metadata: { dag_level: result.dag_level, source }, actor, tenantId });
+            audit(db, 'summary_marked_clean', {
+                targetId: summaryId,
+                metadata: { dag_level: result.dag_level, source },
+                actor,
+                tenantId,
+            });
         }
     }, openStore);
 }

package/dist/store/summary-dirty.d.ts

@@ -1,4 +1,5 @@
 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. */
+/** 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/store/summary-dirty.js

@@ -1,6 +1,7 @@
 // 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. */
+/** 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) {
     // SAFETY: result's shape matches the single `dag_level` column returned below.
     const result = db.prepare(`

package/dist/store/tenant.d.ts

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

package/dist/store/tenant.js

@@ -9,12 +9,13 @@ export function resolveTenantId(opts) {
             throw new Error('invalid api key');
         return ctx.tenantId;
     }
-    // Empty/whitespace-only HIPPO_TENANT must fall through to 'default': `??` only catches undefined, so '' leaked through and broke every downstream tenant
-    // filter.
+    // Empty/whitespace-only HIPPO_TENANT must fall through to 'default': `??` only catches undefined, so '' leaked
+    // through and broke every downstream tenant filter.
     return envTenant();
 }
-/** 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. */
+/** 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 function assertTenantId(fnName, value) {
     if (typeof value !== 'string' || value.length === 0) {
         throw new Error(`${fnName}: tenantId is required (got ${typeof value})`);

package/dist/store/token-ledger-rows.js

@@ -1,3 +1,4 @@
+import { placeholders } from '../util/sql.js';
 export function insertTokenRow(db, row) {
     db.prepare(`INSERT INTO token_ledger (ts, tenant_id, session_id, surface, event, items, tokens, block_hash)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(row.ts, row.tenantId, row.sessionId, row.surface, row.event, row.items, row.tokens, row.blockHash);
@@ -33,12 +34,15 @@ export function surfaceTotals(db, tenantId, sinceIso) {
 /** Window-wide session counts; `rereadSurfaces` are the hook surfaces whose sessions count as hook sessions. */
 export function sessionTotals(db, tenantId, sinceIso, rereadSurfaces) {
     // SAFETY: the SELECT names exactly these four aggregate columns.
-    return db.prepare(`SELECT COUNT(DISTINCT session_id) AS sessions,
-            COUNT(DISTINCT CASE WHEN event <> 'reset' AND surface IN (${rereadSurfaces.map(() => '?').join(', ')}) THEN session_id END) AS hook_sessions,
+    return db
+        .prepare(`SELECT COUNT(DISTINCT session_id) AS sessions,
+            COUNT(DISTINCT CASE WHEN event <> 'reset' AND surface IN (${placeholders(rereadSurfaces.length)}) THEN
+            session_id END) AS hook_sessions,
             COUNT(DISTINCT CASE WHEN event = 'reread' THEN session_id END) AS reread_sessions,
             SUM(CASE WHEN event = 'inject' THEN tokens ELSE 0 END) AS tokens
      FROM token_ledger
-     WHERE tenant_id = ? AND ts >= ? AND session_id IS NOT NULL AND event <> 'arm'`).get(...rereadSurfaces, tenantId, sinceIso);
+     WHERE tenant_id = ? AND ts >= ? AND session_id IS NOT NULL AND event <> 'arm'`)
+        .get(...rereadSurfaces, tenantId, sinceIso);
 }
 export function sessionTokenRows(db, tenantId, sinceIso) {
     // SAFETY: the SELECT names exactly these columns, all aggregates or TEXT.
@@ -53,7 +57,7 @@ export function sessionTokenRows(db, tenantId, sinceIso) {
 export function injectedBlocks(db, tenantId, sessionId, surfaces) {
     // SAFETY: the SELECT names exactly these three columns.
     return db.prepare(`SELECT ts, surface, tokens FROM token_ledger
-     WHERE tenant_id = ? AND session_id = ? AND event = 'inject' AND surface IN (${surfaces.map(() => '?').join(', ')})`).all(tenantId, sessionId, ...surfaces);
+     WHERE tenant_id = ? AND session_id = ? AND event = 'inject' AND surface IN (${placeholders(surfaces.length)})`).all(tenantId, sessionId, ...surfaces);
 }
 export function deleteRereadRows(db, tenantId, sessionId) {
     db.prepare(`DELETE FROM token_ledger WHERE tenant_id = ? AND session_id = ? AND event = 'reread'`).run(tenantId, sessionId);

package/dist/store/token-ledger.d.ts

@@ -1,13 +1,15 @@
 import { type DatabaseSyncLike } from '../db/index.js';
-/** Where a block was sent: `hook`/`hook_recall` (per-prompt hook), `compact_resume`, `context`/`recall` (CLI), `mcp_*`, `http_*`,
- * and `pilot` (session pilot arm row, src/api/pilot-arm.ts; not a send, so in no surface list). */
+/** Where a block was sent: `hook`/`hook_recall` (per-prompt hook), `compact_resume`, `context`/`recall` (CLI), `mcp_*`,
+ * `http_*`, and `pilot` (session pilot arm row, src/api/pilot-arm.ts; not a send, so in no surface list). */
 export type TokenSurface = 'hook' | 'hook_recall' | 'compact_resume' | 'context' | 'recall' | 'mcp_recall' | 'mcp_context' | 'http_recall' | 'http_context' | 'http_assemble' | 'pilot';
 /** All surfaces, in report order. */
 export declare const TOKEN_SURFACES: readonly TokenSurface[];
-/** Surfaces whose re-reads are counted: only a hook payload tells a sub-agent's block from its parent's, as both carry one session id. */
+/** Surfaces whose re-reads are counted: only a hook payload tells a sub-agent's block from its parent's, as both carry
+ * one session id. */
 export declare const REREAD_SURFACES: readonly TokenSurface[];
-/** What happened to a block: `inject` (sent), `skip` (identical to the last injected block), `reset` (host compacted, next must send), `reread` (tokens
- * later calls read again, booked at session end), `arm` (pilot assignment; `block_hash` is `hippo` or `holdout`, `items` the holdout rate in bp). */
+/** What happened to a block: `inject` (sent), `skip` (identical to the last injected block), `reset` (host compacted,
+ * next must send), `reread` (tokens later calls read again, booked at session end), `arm` (pilot assignment;
+ * `block_hash` is `hippo` or `holdout`, `items` the holdout rate in bp). */
 export type TokenEvent = 'inject' | 'skip' | 'reset' | 'reread' | 'arm';
 /** Rows older than this are pruned on write. */
 export declare const TOKEN_LEDGER_RETENTION_DAYS = 90;
@@ -36,10 +38,11 @@ export interface LastSent {
     /** Consecutive `skip` rows since that injection. */
     skipsSince: number;
 }
-/** The last block this session injected on `surface`, or null if none, a `reset` came after it, or there is no session id (the caller then always injects). */
+/** The last block this session injected on `surface`, or null if none, a `reset` came after it, or there is no session
+ * id (the caller then always injects). */
 export declare function lastSentState(db: DatabaseSyncLike, tenantId: string, sessionId: string | null | undefined, surface: TokenSurface): LastSent | null;
-/** Whether a block identical to the session's last injection should be skipped; `refreshTurns` resends it after that many consecutive skips so a long
- * session still sees its pinned rules, 0 never resends. */
+/** Whether a block identical to the session's last injection should be skipped; `refreshTurns` resends it after that
+ * many consecutive skips so a long session still sees its pinned rules, 0 never resends. */
 export declare function shouldSkipUnchanged(last: LastSent | null, hash: string, refreshTurns: number): boolean;
 /** Per-surface totals for {@link summarizeTokenUse}. */
 export interface TokenSurfaceSummary {
@@ -52,7 +55,8 @@ export interface TokenSurfaceSummary {
     skipped: number;
     /** Tokens those skipped blocks would have cost. */
     tokensAvoided: number;
-    /** Tokens of these blocks that later model calls read again, from sessions that have ended; 0 off {@link REREAD_SURFACES}. */
+    /** Tokens of these blocks that later model calls read again, from sessions that have ended; 0 off {@link
+     * REREAD_SURFACES}. */
     tokensReread: number;
     /** Distinct session ids seen (rows without one are not counted). */
     sessions: number;
@@ -80,7 +84,8 @@ export declare function summarizeTokenUse(db: DatabaseSyncLike, tenantId: string
 interface ModelTagged {
     model?: unknown;
 }
-/** Claude Code writes its own API errors and limit notices as assistant lines from this model; no model call made them. */
+/** Claude Code writes its own API errors and limit notices as assistant lines from this model; no model call made
+ * them. */
 export declare function isSyntheticMessage(message: ModelTagged): boolean;
 /** Tokens hippo sent and skipped in one session, for {@link tokensBySession}. */
 export interface SessionTokens {
@@ -92,8 +97,8 @@ export interface SessionTokens {
     /** Blocks sent. */
     injections: number;
 }
-/** Ledger totals per session id since `sinceIso`, across surfaces; hook rows carry the host's session id (the transcript file name), so they join to its
- * usage records. */
+/** Ledger totals per session id since `sinceIso`, across surfaces; hook rows carry the host's session id (the
+ * transcript file name), so they join to its usage records. */
 export declare function tokensBySession(db: DatabaseSyncLike, tenantId: string, sinceIso: string): SessionTokens[];
 /** One model API call in a host transcript, for {@link recordRereads}. */
 export interface ApiCall {
@@ -112,7 +117,8 @@ export interface TranscriptCalls {
 export declare function readApiCalls(transcriptPath: string): Promise<TranscriptCalls>;
 /** Calls that carried a block sent at `at` (epoch ms): every later call in the first later call's context window. */
 export declare function carryingCalls(calls: readonly ApiCall[], at: number): ApiCall[];
-/** Replace a session's `reread` rows in `hippoRoot`'s store, one per {@link REREAD_SURFACES} surface and UTC day; returns the tokens booked. */
+/** Replace a session's `reread` rows in `hippoRoot`'s store, one per {@link REREAD_SURFACES} surface and UTC day;
+ * returns the tokens booked. */
 export declare function recordRereads(hippoRoot: string, tenantId: string, sessionId: string, calls: readonly ApiCall[]): number;
 export {};
 //# sourceMappingURL=token-ledger.d.ts.map

package/dist/store/token-ledger.js

@@ -1,6 +1,7 @@
-/** Token ledger: one row per block of memory text sent to an agent on any surface, with its token cost; the input for the token-savings evals.
- * Backs inject-only-on-change: the hook records a `skip` when the block hash matches the session's last; `reread` rows cover {@link REREAD_SURFACES} blocks.
- * Counts use {@link estimateTokens} (chars / 4); rows never hold content or query text. Writes are best-effort: a ledger failure must not break recall. */
+/** Token ledger: one row per block of memory text sent to an agent on any surface, with its token cost; the input for
+ * the token-savings evals. Backs inject-only-on-change: the hook records a `skip` when the block hash matches the
+ * session's last; `reread` rows cover {@link REREAD_SURFACES} blocks. Counts use {@link estimateTokens} (chars / 4);
+ * rows never hold content or query text. Writes are best-effort: a ledger failure must not break recall. */
 import { open } from 'node:fs/promises';
 import { withWriteScope } from '../db/index.js';
 import { onHandle } from './open.js';
@@ -13,7 +14,8 @@ export const TOKEN_SURFACES = [
     'hook', 'hook_recall', 'compact_resume', 'context', 'recall', 'mcp_recall', 'mcp_context',
     'http_recall', 'http_context', 'http_assemble',
 ];
-/** Surfaces whose re-reads are counted: only a hook payload tells a sub-agent's block from its parent's, as both carry one session id. */
+/** Surfaces whose re-reads are counted: only a hook payload tells a sub-agent's block from its parent's, as both carry
+ * one session id. */
 export const REREAD_SURFACES = ['hook', 'hook_recall', 'compact_resume'];
 /** Rows older than this are pruned on write. */
 export const TOKEN_LEDGER_RETENTION_DAYS = 90;
@@ -33,7 +35,8 @@ export function recordTokenUse(db, use) {
     const cutoff = new Date(Date.parse(now) - TOKEN_LEDGER_RETENTION_DAYS * DAY_MS).toISOString();
     pruneTokenRowsBefore(db, cutoff);
 }
-/** The last block this session injected on `surface`, or null if none, a `reset` came after it, or there is no session id (the caller then always injects). */
+/** The last block this session injected on `surface`, or null if none, a `reset` came after it, or there is no session
+ * id (the caller then always injects). */
 export function lastSentState(db, tenantId, sessionId, surface) {
     if (!sessionId)
         return null;
@@ -43,8 +46,8 @@ export function lastSentState(db, tenantId, sessionId, surface) {
     const skips = countSkipsAfter(db, tenantId, sessionId, surface, anchor.id);
     return { hash: anchor.block_hash, skipsSince: Number(skips?.n ?? 0) };
 }
-/** Whether a block identical to the session's last injection should be skipped; `refreshTurns` resends it after that many consecutive skips so a long
- * session still sees its pinned rules, 0 never resends. */
+/** Whether a block identical to the session's last injection should be skipped; `refreshTurns` resends it after that
+ * many consecutive skips so a long session still sees its pinned rules, 0 never resends. */
 export function shouldSkipUnchanged(last, hash, refreshTurns) {
     if (!last || last.hash !== hash)
         return false;
@@ -86,12 +89,13 @@ export function summarizeTokenUse(db, tenantId, sinceIso) {
         rereadSessions: Number(perSession?.reread_sessions ?? 0),
     };
 }
-/** Claude Code writes its own API errors and limit notices as assistant lines from this model; no model call made them. */
+/** Claude Code writes its own API errors and limit notices as assistant lines from this model; no model call made
+ * them. */
 export function isSyntheticMessage(message) {
     return message.model === '<synthetic>';
 }
-/** Ledger totals per session id since `sinceIso`, across surfaces; hook rows carry the host's session id (the transcript file name), so they join to its
- * usage records. */
+/** Ledger totals per session id since `sinceIso`, across surfaces; hook rows carry the host's session id (the
+ * transcript file name), so they join to its usage records. */
 export function tokensBySession(db, tenantId, sinceIso) {
     return sessionTokenRows(db, tenantId, sinceIso).map((r) => ({
         sessionId: r.session_id,
@@ -149,13 +153,15 @@ export async function readApiCalls(transcriptPath) {
 }
 /** Calls that carried a block sent at `at` (epoch ms): every later call in the first later call's context window. */
 export function carryingCalls(calls, at) {
-    // Windows come from file order, not boundary timestamps: the compact-resume block is booked before its boundary's timestamp.
+    // Windows come from file order, not boundary timestamps: the compact-resume block is booked before its boundary's
+    // timestamp.
     const first = calls.find((call) => call.at > at);
     if (!first)
         return [];
     return calls.filter((call) => call.at > at && call.compactions === first.compactions);
 }
-/** Replace a session's `reread` rows in `hippoRoot`'s store, one per {@link REREAD_SURFACES} surface and UTC day; returns the tokens booked. */
+/** Replace a session's `reread` rows in `hippoRoot`'s store, one per {@link REREAD_SURFACES} surface and UTC day;
+ * returns the tokens booked. */
 export function recordRereads(hippoRoot, tenantId, sessionId, calls) {
     return onHandle(hippoRoot, (db) => {
         return replaceRereadRows(db, tenantId, sessionId, calls);
@@ -173,7 +179,8 @@ function replaceRereadRows(db, tenantId, sessionId, calls) {
         };
         for (const row of rows) {
             const sentAt = Date.parse(row.ts);
-            // Dated by when the calls happened, so a --days window counts re-reads in it; the empty send-day row keeps the session in coverage.
+            // Dated by when the calls happened, so a --days window counts re-reads in it; the empty send-day row keeps the
+            // session in coverage.
             add(row.surface, sentAt, 0, 0);
             // The first carrying call is the send itself; every later one is a re-read.
             for (const call of carryingCalls(calls, sentAt).slice(1))
@@ -182,7 +189,13 @@ function replaceRereadRows(db, tenantId, sessionId, calls) {
         deleteRereadRows(db, tenantId, sessionId);
         for (const day of days.values()) {
             recordTokenUse(db, {
-                tenantId, sessionId, surface: day.surface, event: 'reread', items: day.rereads, tokens: day.tokens, now: new Date(day.at).toISOString(),
+                tenantId,
+                sessionId,
+                surface: day.surface,
+                event: 'reread',
+                items: day.rereads,
+                tokens: day.tokens,
+                now: new Date(day.at).toISOString(),
             });
         }
         return [...days.values()].reduce((sum, day) => sum + day.tokens, 0);

package/dist/store/tombstone-checks.d.ts

@@ -1,11 +1,14 @@
 import { type AppendAuditOpts } from './audit.js';
 import { type RejectedValueRow } from './rejection.js';
-/** Tombstone lookups and their refusal audit rows on one handle: opened on first use, never under dryRun, closed once. */
+/** Tombstone lookups and their refusal audit rows on one handle: opened on first use, never under dryRun, closed
+ * once. */
 export interface TombstoneChecks {
     /** The tenant's tombstone for `digest`; null when there is none, and always under dryRun. */
     find(tenantId: string, digest: string): RejectedValueRow | null;
     /** One audit row on the same handle; nothing under dryRun. */
     audit(event: AppendAuditOpts): void;
+    /** `audit`, with a failed write logged and counted instead of thrown, for a refusal that stands without its row. */
+    auditOrCount(event: AppendAuditOpts): void;
     close(): void;
 }
 export declare function lazyTombstoneChecks(hippoRoot: string, dryRun: boolean): TombstoneChecks;