hippo-memory 2.0.0 → 2.1.0

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';
@@ -9,10 +10,12 @@ import { onHandle, openStore } from './open.js';
 import { chunked } from '../util/chunked.js';
 import { DIGEST_DISPLAY_CHARS } from '../util/token-text.js';
 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. */
+// 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
@@ -20,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
@@ -29,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
@@ -46,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) => {
@@ -64,7 +69,8 @@ export function loadChildrenOfSummary(hippoRoot, summaryId, tenantId) {
         return rows.map(rowToEntry);
     }, openStore);
 }
-/** loadChildrenOfSummary for many summaries in one IN query per tenant chunk; the map key is `${tenantId}\u0000${summaryId}`, each list in created order. */
+/** 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) {
@@ -104,8 +110,9 @@ export function loadChildrenOfSummaries(hippoRoot, summaries) {
 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. */
+/** 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.tenant_id);
     return onHandle(hippoRoot, (db) => {
@@ -123,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
@@ -133,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) {
@@ -143,8 +150,9 @@ function applyRebuildInSavepoint(db, summary, patch) {
     const tombstone = patch.bumpRebuildCount
         ? 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.tenant_id)
@@ -161,8 +169,9 @@ 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 },
@@ -196,8 +205,9 @@ function syncRebuiltSummary(db, summary, patch, applyContentWrite, nowIso) {
             descendant_count: patch.descendant_count,
         }, 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) => {
@@ -208,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

@@ -34,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 (${placeholders(rereadSurfaces.length)}) 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.

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;

package/dist/store/tombstone-checks.js

@@ -1,7 +1,8 @@
 // Sleep's tombstone checks run on one handle for the whole pass, owned here so no stage holds a raw one.
 import { closeHippoDb, openHippoDb } from '../db/index.js';
-import { appendAuditEvent } from './audit.js';
+import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
 import { findRejectedValue } from './rejection.js';
+import { errorMessage } from '../util/log.js';
 // Lazy so a sleep that checks nothing never opens the store; make it IMMEDIATELY before the try whose
 // finally closes it, so a throw in any phase cannot leak the handle.
 export function lazyTombstoneChecks(hippoRoot, dryRun) {
@@ -22,6 +23,14 @@ export function lazyTombstoneChecks(hippoRoot, dryRun) {
             if (db)
                 appendAuditEvent(db, event);
         },
+        auditOrCount(event) {
+            try {
+                this.audit(event);
+            }
+            catch (error) {
+                reportAuditWriteFailure(event.op, errorMessage(error), event.targetId);
+            }
+        },
         close() {
             if (handle)
                 closeHippoDb(handle);

package/dist/store/usage-reports.js

@@ -1,5 +1,6 @@
 // The token-use and failure reports, each read on one handle of its own.
-// A file apart from token-ledger-rows.ts: src/store/token-ledger.ts imports that one, so a summary there would be an import cycle.
+// A file apart from token-ledger-rows.ts: src/store/token-ledger.ts imports that one, so a summary there would be an
+// import cycle.
 import { onHandle } from './open.js';
 import { summarizeTokenUse } from './token-ledger.js';
 import { summarizeFailures } from './failure-log.js';

package/dist/store/vector-index.d.ts

@@ -15,7 +15,8 @@ export declare function replacesIndex(state: EmbeddingIndexState, model: string)
 export declare function storedIndexState(hippoRoot: string): EmbeddingIndexState;
 /** Records `identity` as what built the index under `hippoRoot`. */
 export declare function saveIndexIdentity(hippoRoot: string, identity: string): void;
-/** Every stored vector keyed by memory id; `{}` when none. Search reads only the rows it ranks via `loadStoredVectors`. */
+/** Every stored vector keyed by memory id; `{}` when none. Search reads only the rows it ranks via
+ * `loadStoredVectors`. */
 export declare function loadEmbeddingIndex(hippoRoot: string): Record<string, number[]>;
 export interface StoredVectorSummary {
     readonly ids: Set<string>;
@@ -29,17 +30,19 @@ export declare function loadStoredVectors(hippoRoot: string, ids: readonly strin
 export declare function loadStoredVectorViews(hippoRoot: string, ids: readonly string[]): Map<string, Float32Array>;
 /** Replace every stored vector with `index`; `model` defaults to the stored index identity. */
 export declare function saveEmbeddingIndex(hippoRoot: string, index: Record<string, number[]>, model?: string): void;
-/** Inserts or replaces `rows` under `model`, each row its own commit so a failure keeps the rows before it; returns how many it wrote. */
+/** Inserts or replaces `rows` under `model`, each row its own commit so a failure keeps the rows before it; returns how
+ * many it wrote. */
 export declare function saveStoredVectors(hippoRoot: string, rows: Iterable<readonly [string, readonly number[]]>, model: string): number;
-/** Drops the vectors of deleted memories under `hippoRoot`, then returns the ids that still have one. */
-export declare function pruneStoredVectors(hippoRoot: string): Set<string>;
+/** Drops the vectors of deleted memories under `hippoRoot`, then returns the ids with no vector, oldest first. */
+export declare function pruneStoredVectorsListPending(hippoRoot: string): string[];
 export declare function entriesWithoutVectorAt(db: DatabaseSyncLike, query: VectorBackfillQuery): MemoryEntry[];
 export declare function writeVectorsAt(db: DatabaseSyncLike, write: VectorWrite): VectorWriteResult;
 /** Every particle stored under `hippoRoot`. */
 export declare function loadStoredParticles(hippoRoot: string): PhysicsParticle[];
 /** Writes `particles` over their stored state under `hippoRoot`, as one batch. */
 export declare function saveStoredParticles(hippoRoot: string, particles: PhysicsParticle[]): void;
-/** Replaces every particle under `hippoRoot` with a fresh one per memory in `ids` that has an embedding; returns how many. Rows are read a page at a time. */
+/** Replaces every particle under `hippoRoot` with a fresh one per memory in `ids` that has an embedding; returns how
+ * many. Rows are read a page at a time. */
 export declare function resetStoredParticles(hippoRoot: string, ids: readonly string[], embeddingIndex: Record<string, number[]>): number;
 /** Stores a first particle for `entry`, placed at `vector`; a memory that has one keeps it. */
 export declare function seedStoredParticle(hippoRoot: string, entry: MemoryEntry, vector: number[]): void;

package/dist/store/vector-index.js

@@ -1,4 +1,5 @@
-// Owns hippo.db's stored vectors, the identity of the model that built them, and the particle rows: every read and write of the three.
+// Owns hippo.db's stored vectors, the identity of the model that built them, and the particle rows: every read and
+// write of the three.
 import { getMeta, setMeta, withWriteScope } from '../db/index.js';
 import { onHandle } from './open.js';
 import { DEFAULT_EMBEDDING_MODEL } from '../embeddings/local.js';
@@ -38,7 +39,8 @@ export function saveIndexIdentity(hippoRoot, identity) {
         setMeta(db, EMBEDDING_MODEL_META_KEY, identity);
     });
 }
-/** Every stored vector keyed by memory id; `{}` when none. Search reads only the rows it ranks via `loadStoredVectors`. */
+/** Every stored vector keyed by memory id; `{}` when none. Search reads only the rows it ranks via
+ * `loadStoredVectors`. */
 export function loadEmbeddingIndex(hippoRoot) {
     return onHandle(hippoRoot, (db) => {
         return Object.fromEntries(loadVectors(db));
@@ -72,17 +74,24 @@ export function saveEmbeddingIndex(hippoRoot, index, model) {
         replaceAllVectors(db, index, model ?? getMeta(db, EMBEDDING_MODEL_META_KEY, ''));
     });
 }
-/** Inserts or replaces `rows` under `model`, each row its own commit so a failure keeps the rows before it; returns how many it wrote. */
+/** Inserts or replaces `rows` under `model`, each row its own commit so a failure keeps the rows before it; returns how
+ * many it wrote. */
 export function saveStoredVectors(hippoRoot, rows, model) {
     return onHandle(hippoRoot, (db) => {
         return upsertVectors(db, rows, model);
     });
 }
-/** Drops the vectors of deleted memories under `hippoRoot`, then returns the ids that still have one. */
-export function pruneStoredVectors(hippoRoot) {
+/** Drops the vectors of deleted memories under `hippoRoot`, then returns the ids with no vector, oldest first. */
+export function pruneStoredVectorsListPending(hippoRoot) {
     return onHandle(hippoRoot, (db) => {
         deleteOrphanVectors(db);
-        return storedVectorIds(db);
+        // SAFETY: the SELECT names exactly the one column read.
+        const rows = db
+            .prepare(`SELECT id FROM memories
+         WHERE NOT EXISTS (SELECT 1 FROM memory_vectors v WHERE v.memory_id = memories.id)
+         ORDER BY created ASC, id ASC`)
+            .all();
+        return rows.map((r) => r.id);
     });
 }
 export function entriesWithoutVectorAt(db, query) {
@@ -101,21 +110,25 @@ function ownedIds(db, ids, tenantId) {
     const owned = new Set();
     for (const chunk of chunked([...new Set(ids)])) {
         // SAFETY: the SELECT names one column, id.
-        const rows = db.prepare(`SELECT id FROM memories WHERE +tenant_id = ? AND id IN (${placeholders(chunk.length)})`).all(tenantId, ...chunk);
+        const rows = db
+            .prepare(`SELECT id FROM memories WHERE +tenant_id = ? AND id IN (${placeholders(chunk.length)})`)
+            .all(tenantId, ...chunk);
         for (const row of rows)
             owned.add(row.id);
     }
     return owned;
 }
-// savePhysicsState opens its own transaction and overwrites, so the first particle for a memory is inserted here instead.
+// savePhysicsState opens its own transaction and overwrites, so the first particle for a memory is inserted here
+// instead.
 function insertNewParticles(db, rows) {
     const stmt = db.prepare(`
     INSERT INTO memory_physics (memory_id, position_blob, velocity_blob, mass, charge, temperature, last_simulation)
     VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT(memory_id) DO NOTHING
   `);
     for (const { memoryId, particle: p } of rows) {
-        if (p)
+        if (p) {
             stmt.run(memoryId, float32ToBuffer(p.position), float32ToBuffer(p.velocity), p.mass, p.charge, p.temperature, p.lastSimulation);
+        }
     }
 }
 export function writeVectorsAt(db, write) {
@@ -158,7 +171,8 @@ function* entriesInPages(db, ids) {
         }
     }
 }
-/** Replaces every particle under `hippoRoot` with a fresh one per memory in `ids` that has an embedding; returns how many. Rows are read a page at a time. */
+/** Replaces every particle under `hippoRoot` with a fresh one per memory in `ids` that has an embedding; returns how
+ * many. Rows are read a page at a time. */
 export function resetStoredParticles(hippoRoot, ids, embeddingIndex) {
     return onHandle(hippoRoot, (db) => {
         return resetAllPhysicsState(db, entriesInPages(db, ids), embeddingIndex);

package/dist/store/working-memory.d.ts

@@ -1,4 +1,5 @@
-/** Working Memory: bounded buffer for current-state notes, separate from long-term memory; scoped, importance-ranked, evicted past WM_MAX_ENTRIES per scope. */
+/** Working Memory: bounded buffer for current-state notes, separate from long-term memory; scoped, importance-ranked,
+ * evicted past WM_MAX_ENTRIES per scope. */
 import type { JsonValue } from '../util/json.js';
 export declare const WM_MAX_ENTRIES = 20;
 export type JsonObject = {
@@ -15,8 +16,8 @@ export interface WorkingMemoryItem {
     createdAt: string;
     updatedAt: string;
 }
-/** Push a new entry into working memory; past WM_MAX_ENTRIES the scope's lowest-importance entry is evicted (ties: oldest created_at). Returns the new
- * row ID. */
+/** Push a new entry into working memory; past WM_MAX_ENTRIES the scope's lowest-importance entry is evicted (ties:
+ * oldest created_at). Returns the new row ID. */
 export declare function wmPush(hippoRoot: string, opts: {
     scope: string;
     content: string;
@@ -39,7 +40,8 @@ export declare function wmClear(hippoRoot: string, opts?: {
     sessionId?: string;
     tenantId?: string;
 }): number;
-/** Flush working memory after session end: same as wmClear, but marks the session-boundary discard of ephemeral state. Returns the count flushed. */
+/** Flush working memory after session end: same as wmClear, but marks the session-boundary discard of ephemeral state.
+ * Returns the count flushed. */
 export declare function wmFlush(hippoRoot: string, opts?: {
     scope?: string;
     sessionId?: string;