hippo-memory 1.70.0 → 1.71.0

package/dist/store/summaries.d.ts

@@ -1,50 +1,13 @@
 import type { MemoryEntry } from '../core/memory.js';
-/**
- * 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.
- */
+/** 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, newest change first. 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;
@@ -54,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,77 +1,18 @@
-import { closeHippoDb, withWriteScope } from '../db/index.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';
+import { onHandle, openStore } from './open.js';
 import { DIGEST_DISPLAY_CHARS } from '../util/token-text.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.
-// ---------------------------------------------------------------------------
-/**
- * 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', { targetId: summaryId, metadata: { 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.
- */
+// 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(`
@@ -84,23 +25,12 @@ export function loadAllL2Summaries(hippoRoot) {
        ORDER BY created ASC, id ASC
     `).all();
         return rows.map(rowToEntry);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Dirty summaries, newest change first. 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(`
@@ -111,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(`
@@ -139,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
@@ -197,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)
@@ -220,14 +118,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 (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', { targetId: summary.id, metadata: { digest: tombstone.digest, reason: tombstone.reason }, actor: patch.actor, tenantId: 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, DIGEST_DISPLAY_CHARS)}...); metadata updated, content unchanged`);
 }
@@ -255,20 +153,13 @@ function syncRebuiltSummary(db, summary, patch, applyContentWrite, nowIso) {
             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
@@ -283,9 +174,6 @@ export function clearSummaryDirtyAfterBuild(hippoRoot, summaryId, tenantId, acto
             // 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 });
         }
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 //# sourceMappingURL=summaries.js.map

package/dist/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/index.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

@@ -5,21 +5,7 @@ export interface ResolveOpts {
     apiKey?: string;
 }
 export declare function resolveTenantId(opts: ResolveOpts): string;
-/**
- * Defensive runtime guard for tenant id arguments.
- *
- * The continuity helpers (saveActiveTaskSnapshot, listSessionEvents, etc.)
- * gained a required `tenantId` parameter (schema v22) to close a
- * cross-tenant data leak. TypeScript catches misbinding at compile time, but
- * JavaScript callers from older versions can silently pass a `sessionId`
- * where `tenantId` is now expected, e.g.
- *   loadLatestHandoff(root, 'sess-abc')   // WRONG: 'sess-abc' becomes the tenant
- * which would silently filter to a non-existent tenant and return null with
- * no error. This guard rejects the most common shape of that mistake (any
- * value beginning with the conventional `sess-` / `sess_` session prefix).
- *
- * False-positive cost: a tenant literally named `sess-...` will be rejected.
- * Acceptable tradeoff for catching the silent-leak class.
- */
+/** 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,27 +9,12 @@ export function resolveTenantId(opts) {
             throw new Error('invalid api key');
         return ctx.tenantId;
     }
-    // L1: empty / whitespace-only HIPPO_TENANT must fall through to 'default'.
-    // `??` only catches undefined, so HIPPO_TENANT="" leaked through as the
-    // literal empty string 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();
 }
-/**
- * Defensive runtime guard for tenant id arguments.
- *
- * The continuity helpers (saveActiveTaskSnapshot, listSessionEvents, etc.)
- * gained a required `tenantId` parameter (schema v22) to close a
- * cross-tenant data leak. TypeScript catches misbinding at compile time, but
- * JavaScript callers from older versions can silently pass a `sessionId`
- * where `tenantId` is now expected, e.g.
- *   loadLatestHandoff(root, 'sess-abc')   // WRONG: 'sess-abc' becomes the tenant
- * which would silently filter to a non-existent tenant and return null with
- * no error. This guard rejects the most common shape of that mistake (any
- * value beginning with the conventional `sess-` / `sess_` session prefix).
- *
- * False-positive cost: a tenant literally named `sess-...` will be rejected.
- * Acceptable tradeoff for catching the silent-leak class.
- */
+/** 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.d.ts

@@ -1,27 +1,13 @@
 import { type DatabaseSyncLike } from '../db/index.js';
-/**
- * Where a block of memory text was sent.
- * - `hook`: the per-prompt `UserPromptSubmit` hook (`hippo context --pinned-only`).
- * - `hook_recall`: the same hook's prompt-recall section.
- * - `compact_resume`: the snapshot the SessionStart(compact) hook prints (`hippo compact-resume`).
- * - `context`, `recall`: the CLI commands.
- * - `mcp_recall`, `mcp_context`: the MCP tools.
- * - `http_recall`, `http_context`, `http_assemble`: the HTTP API.
- * - `pilot`: the session's pilot arm row (src/api/pilot-arm.ts); not a send, so it is 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. */
 export declare const REREAD_SURFACES: readonly TokenSurface[];
-/**
- * What happened to a block.
- * - `inject`: sent to the agent.
- * - `skip`: identical to the session's last injected block, so not sent again.
- * - `reset`: the host compacted its context, so the next block must be sent.
- * - `reread`: tokens later calls read again, booked at session end as one row per session, hook surface and UTC day of the calls.
- * - `arm`: the pilot assignment; `block_hash` is `hippo` or `holdout`, `items` the holdout rate in basis points.
- */
+/** 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;
@@ -41,9 +27,7 @@ export interface TokenUse {
     /** Override the timestamp (tests). ISO string. */
     now?: string;
 }
-/**
- * Append one ledger row and prune rows past {@link TOKEN_LEDGER_RETENTION_DAYS}.
- */
+/** Append one ledger row and prune rows past {@link TOKEN_LEDGER_RETENTION_DAYS}. */
 export declare function recordTokenUse(db: DatabaseSyncLike, use: TokenUse): void;
 /** What a session last sent on a surface, for {@link lastSentState}. */
 export interface LastSent {
@@ -52,18 +36,10 @@ export interface LastSent {
     /** Consecutive `skip` rows since that injection. */
     skipsSince: number;
 }
-/**
- * The last block this session injected on `surface`, or null when the
- * session has injected nothing, a `reset` came after it, or there is no
- * session id (without one, the caller 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 an unchanged block after that many
- * consecutive skips, so a long session still sees its pinned rules near the
- * latest turn; 0 never resends an unchanged block.
- */
+/** 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 {
@@ -98,10 +74,7 @@ export interface TokenSummary {
     /** Sessions whose re-reads were counted at session end; open or crashed sessions are not. */
     rereadSessions: number;
 }
-/**
- * Sum the ledger for one tenant since `sinceIso`. Surfaces with no rows are
- * omitted.
- */
+/** Sum the ledger for one tenant since `sinceIso`; surfaces with no rows are omitted. */
 export declare function summarizeTokenUse(db: DatabaseSyncLike, tenantId: string, sinceIso: string): TokenSummary;
 /** JSON-value string check without a runtime `typeof` (anti-slop rule). */
 interface ModelTagged {
@@ -126,11 +99,8 @@ export interface SessionTokens {
     /** Blocks sent. */
     injections: number;
 }
-/**
- * Ledger totals per session id since `sinceIso`, across every surface.
- * Claude Code hook rows carry the host's session id, which is also the
- * transcript file name, so these join to the host's own 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 {
@@ -149,7 +119,7 @@ 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 one transaction, one per {@link REREAD_SURFACES} surface and UTC day; returns the tokens booked. */
-export declare function recordRereads(db: DatabaseSyncLike, tenantId: string, sessionId: string, calls: readonly ApiCall[]): number;
+/** 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