hippo-memory 1.69.0 → 1.71.0

package/dist/store/tenant.js

@@ -0,0 +1,28 @@
+import { envTenant } from '../util/env.js';
+import { validateApiKey } from './auth.js';
+export function resolveTenantId(opts) {
+    if (opts.apiKey) {
+        if (!opts.db)
+            throw new Error('resolveTenantId: db required when apiKey is set');
+        const ctx = validateApiKey(opts.db, opts.apiKey);
+        if (!ctx.valid || !ctx.tenantId)
+            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.
+    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. */
+export function assertTenantId(fnName, value) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`${fnName}: tenantId is required (got ${typeof value})`);
+    }
+    if (/^sess[-_]/i.test(value)) {
+        throw new Error(`${fnName}: tenantId looks like a session id ('${value}'). ` +
+            `In v0.41+ these helpers take (hippoRoot, tenantId, ...). ` +
+            `Pass the tenant id (e.g. 'default') and the session id separately.`);
+    }
+}
+//# sourceMappingURL=tenant.js.map

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

@@ -0,0 +1,61 @@
+import type { DatabaseSyncLike } from '../db/index.js';
+import type { TokenSurface } from './token-ledger.js';
+export interface TokenRowInput {
+    ts: string;
+    tenantId: string;
+    sessionId: string | null;
+    surface: string;
+    event: string;
+    items: number;
+    tokens: number;
+    blockHash: string | null;
+}
+export declare function insertTokenRow(db: DatabaseSyncLike, row: TokenRowInput): void;
+export declare function pruneTokenRowsBefore(db: DatabaseSyncLike, cutoffIso: string): void;
+export interface LedgerAnchor {
+    id: number;
+    event: string;
+    block_hash: string | null;
+}
+/** The session's newest inject or reset row on a surface. */
+export declare function latestInjectOrReset(db: DatabaseSyncLike, tenantId: string, sessionId: string, surface: string): LedgerAnchor | undefined;
+export declare function countSkipsAfter(db: DatabaseSyncLike, tenantId: string, sessionId: string, surface: string, afterId: number): {
+    n: number;
+} | undefined;
+export interface SurfaceTotalsRow {
+    surface: string;
+    injected: number;
+    tokens: number;
+    skipped: number;
+    avoided: number;
+    reread: number;
+    sessions: number;
+}
+export declare function surfaceTotals(db: DatabaseSyncLike, tenantId: string, sinceIso: string): SurfaceTotalsRow[];
+export interface SessionTotalsRow {
+    sessions: number;
+    hook_sessions: number;
+    reread_sessions: number;
+    tokens: number | null;
+}
+/** Window-wide session counts; `rereadSurfaces` are the hook surfaces whose sessions count as hook sessions. */
+export declare function sessionTotals(db: DatabaseSyncLike, tenantId: string, sinceIso: string, rereadSurfaces: readonly TokenSurface[]): SessionTotalsRow | undefined;
+export interface SessionTokenRow {
+    session_id: string;
+    sent: number;
+    skipped: number;
+    injections: number;
+}
+export declare function sessionTokenRows(db: DatabaseSyncLike, tenantId: string, sinceIso: string): SessionTokenRow[];
+export interface InjectedBlockRow {
+    ts: string;
+    surface: TokenSurface;
+    tokens: number;
+}
+export declare function injectedBlocks(db: DatabaseSyncLike, tenantId: string, sessionId: string, surfaces: readonly TokenSurface[]): InjectedBlockRow[];
+export declare function deleteRereadRows(db: DatabaseSyncLike, tenantId: string, sessionId: string): void;
+/** The first stored pilot arm hash for a session, optionally of one tenant. */
+export declare function firstPilotArmHash(db: DatabaseSyncLike, sessionId: string, tenantId?: string): {
+    block_hash: string | null;
+} | undefined;
+//# sourceMappingURL=token-ledger-rows.d.ts.map

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

@@ -0,0 +1,68 @@
+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);
+}
+export function pruneTokenRowsBefore(db, cutoffIso) {
+    db.prepare(`DELETE FROM token_ledger WHERE ts < ?`).run(cutoffIso);
+}
+/** The session's newest inject or reset row on a surface. */
+export function latestInjectOrReset(db, tenantId, sessionId, surface) {
+    // SAFETY: the SELECT names exactly these three columns.
+    return db.prepare(`SELECT id, event, block_hash FROM token_ledger
+     WHERE tenant_id = ? AND session_id = ? AND surface = ? AND event IN ('inject', 'reset')
+     ORDER BY id DESC LIMIT 1`).get(tenantId, sessionId, surface);
+}
+export function countSkipsAfter(db, tenantId, sessionId, surface, afterId) {
+    // SAFETY: the SELECT names exactly this one aggregate column.
+    return db.prepare(`SELECT COUNT(*) AS n FROM token_ledger
+     WHERE tenant_id = ? AND session_id = ? AND surface = ? AND event = 'skip' AND id > ?`).get(tenantId, sessionId, surface, afterId);
+}
+export function surfaceTotals(db, tenantId, sinceIso) {
+    // SAFETY: the SELECT names exactly these columns, all aggregates or TEXT.
+    return db.prepare(`SELECT surface,
+            SUM(CASE WHEN event = 'inject' THEN 1 ELSE 0 END) AS injected,
+            SUM(CASE WHEN event = 'inject' THEN tokens ELSE 0 END) AS tokens,
+            SUM(CASE WHEN event = 'skip' THEN 1 ELSE 0 END) AS skipped,
+            SUM(CASE WHEN event = 'skip' THEN tokens ELSE 0 END) AS avoided,
+            SUM(CASE WHEN event = 'reread' THEN tokens ELSE 0 END) AS reread,
+            COUNT(DISTINCT session_id) AS sessions
+     FROM token_ledger
+     WHERE tenant_id = ? AND ts >= ?
+     GROUP BY surface`).all(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,
+            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);
+}
+export function sessionTokenRows(db, tenantId, sinceIso) {
+    // SAFETY: the SELECT names exactly these columns, all aggregates or TEXT.
+    return db.prepare(`SELECT session_id,
+            SUM(CASE WHEN event = 'inject' THEN tokens ELSE 0 END) AS sent,
+            SUM(CASE WHEN event = 'skip' THEN tokens ELSE 0 END) AS skipped,
+            SUM(CASE WHEN event = 'inject' THEN 1 ELSE 0 END) AS injections
+     FROM token_ledger
+     WHERE tenant_id = ? AND ts >= ? AND session_id IS NOT NULL AND event <> 'arm'
+     GROUP BY session_id`).all(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);
+}
+export function deleteRereadRows(db, tenantId, sessionId) {
+    db.prepare(`DELETE FROM token_ledger WHERE tenant_id = ? AND session_id = ? AND event = 'reread'`).run(tenantId, sessionId);
+}
+/** The first stored pilot arm hash for a session, optionally of one tenant. */
+export function firstPilotArmHash(db, sessionId, tenantId) {
+    const params = tenantId === undefined ? [sessionId] : [sessionId, tenantId];
+    // SAFETY: the SELECT names exactly this one column.
+    return db.prepare(`SELECT block_hash FROM token_ledger WHERE session_id = ?${tenantId === undefined ? '' : ' AND tenant_id = ?'}
+     AND surface = 'pilot' AND event = 'arm' ORDER BY id LIMIT 1`).get(...params);
+}
+//# sourceMappingURL=token-ledger-rows.js.map

package/dist/{token-ledger.d.ts → store/token-ledger.d.ts}

@@ -1,37 +1,16 @@
-import type { DatabaseSyncLike } from './db.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/pilot-arm.ts); not a send, so it is in no surface list.
- */
+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). */
 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;
-/**
- * Rough token estimate: characters / 4. The single estimate behind every
- * token budget and ledger count in hippo.
- */
-export declare function estimateTokens(text: string): number;
-/** Stable 16-hex-char hash of a rendered block, for change detection. */
-export declare function blockHash(text: string): string;
 /** One ledger write. */
 export interface TokenUse {
     tenantId: string;
@@ -48,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 {
@@ -59,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 {
@@ -105,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 {
@@ -133,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 {
@@ -156,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

package/dist/{token-ledger.js → store/token-ledger.js}

@@ -1,31 +1,13 @@
-/**
- * Token ledger: what memory text hippo hands agents,
- * and how many tokens it costs.
- *
- * One row per block of memory text sent to an agent, on every surface: the
- * per-prompt hook, the block `hippo compact-resume` restores after compaction,
- * `hippo context`, `hippo recall`, the MCP tools and the HTTP API. The ledger
- * answers the question a buyer asks first ("what does this cost me per
- * session?") and is the input for the token-savings evals.
- *
- * Every later model call re-reads a sent block until the host compacts; at session end the worker counts
- * those calls from the transcript as `reread` rows for the {@link REREAD_SURFACES} blocks, dated by call day.
- *
- * It also backs inject-only-on-change: the per-prompt hook compares the
- * hash of the block it is about to send with the last block it sent in the
- * same session and records a `skip` instead of sending it again.
- *
- * Token counts use {@link estimateTokens} (characters / 4), the same estimate
- * every budget in hippo uses. Rows hold counts, surfaces, session ids and
- * hashes, never memory content or query text.
- *
- * DB helpers take the caller's handle; {@link readApiCalls} streams one
- * transcript file. Writes are best-effort at the call sites; a ledger failure
- * must never break recall.
- */
-import { createHash } from 'node:crypto';
+/** 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 { isJsonString } from './json.js';
+import { withWriteScope } from '../db/index.js';
+import { onHandle } from './open.js';
+import { isJsonString, isJsonObjectLiteral } from '../util/json.js';
+import { DAY_MS } from '../util/time.js';
+import { countSkipsAfter, deleteRereadRows, injectedBlocks, insertTokenRow, latestInjectOrReset, pruneTokenRowsBefore, sessionTokenRows, sessionTotals, surfaceTotals, } from './token-ledger-rows.js';
+import { DATE_PREFIX_CHARS } from '../util/token-text.js';
 /** All surfaces, in report order. */
 export const TOKEN_SURFACES = [
     'hook', 'hook_recall', 'compact_resume', 'context', 'recall', 'mcp_recall', 'mcp_context',
@@ -35,52 +17,34 @@ export const TOKEN_SURFACES = [
 export const REREAD_SURFACES = ['hook', 'hook_recall', 'compact_resume'];
 /** Rows older than this are pruned on write. */
 export const TOKEN_LEDGER_RETENTION_DAYS = 90;
-/**
- * Rough token estimate: characters / 4. The single estimate behind every
- * token budget and ledger count in hippo.
- */
-export function estimateTokens(text) {
-    return Math.ceil(text.length / 4);
-}
-/** Stable 16-hex-char hash of a rendered block, for change detection. */
-export function blockHash(text) {
-    return createHash('sha256').update(text).digest('hex').slice(0, 16);
-}
-/**
- * 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 function recordTokenUse(db, use) {
     const now = use.now ?? new Date().toISOString();
-    db.prepare(`INSERT INTO token_ledger (ts, tenant_id, session_id, surface, event, items, tokens, block_hash)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(now, use.tenantId, use.sessionId ?? null, use.surface, use.event, Math.max(0, Math.round(use.items)), Math.max(0, Math.round(use.tokens)), use.hash ?? null);
-    const cutoff = new Date(Date.parse(now) - TOKEN_LEDGER_RETENTION_DAYS * 86_400_000).toISOString();
-    db.prepare(`DELETE FROM token_ledger WHERE ts < ?`).run(cutoff);
-}
-/**
- * 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).
- */
+    insertTokenRow(db, {
+        ts: now,
+        tenantId: use.tenantId,
+        sessionId: use.sessionId ?? null,
+        surface: use.surface,
+        event: use.event,
+        items: Math.max(0, Math.round(use.items)),
+        tokens: Math.max(0, Math.round(use.tokens)),
+        blockHash: use.hash ?? null,
+    });
+    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). */
 export function lastSentState(db, tenantId, sessionId, surface) {
     if (!sessionId)
         return null;
-    // SAFETY: the SELECT names exactly these three columns.
-    const anchor = db.prepare(`SELECT id, event, block_hash FROM token_ledger
-     WHERE tenant_id = ? AND session_id = ? AND surface = ? AND event IN ('inject', 'reset')
-     ORDER BY id DESC LIMIT 1`).get(tenantId, sessionId, surface);
+    const anchor = latestInjectOrReset(db, tenantId, sessionId, surface);
     if (!anchor || anchor.event === 'reset' || !anchor.block_hash)
         return null;
-    // SAFETY: the SELECT names exactly this one aggregate column.
-    const skips = db.prepare(`SELECT COUNT(*) AS n FROM token_ledger
-     WHERE tenant_id = ? AND session_id = ? AND surface = ? AND event = 'skip' AND id > ?`).get(tenantId, sessionId, surface, anchor.id);
+    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 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 function shouldSkipUnchanged(last, hash, refreshTurns) {
     if (!last || last.hash !== hash)
         return false;
@@ -88,22 +52,9 @@ export function shouldSkipUnchanged(last, hash, refreshTurns) {
         return false;
     return true;
 }
-/**
- * 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 function summarizeTokenUse(db, tenantId, sinceIso) {
-    // SAFETY: the SELECT names exactly these columns, all aggregates or TEXT.
-    const rows = db.prepare(`SELECT surface,
-            SUM(CASE WHEN event = 'inject' THEN 1 ELSE 0 END) AS injected,
-            SUM(CASE WHEN event = 'inject' THEN tokens ELSE 0 END) AS tokens,
-            SUM(CASE WHEN event = 'skip' THEN 1 ELSE 0 END) AS skipped,
-            SUM(CASE WHEN event = 'skip' THEN tokens ELSE 0 END) AS avoided,
-            SUM(CASE WHEN event = 'reread' THEN tokens ELSE 0 END) AS reread,
-            COUNT(DISTINCT session_id) AS sessions
-     FROM token_ledger
-     WHERE tenant_id = ? AND ts >= ?
-     GROUP BY surface`).all(tenantId, sinceIso);
+    const rows = surfaceTotals(db, tenantId, sinceIso);
     const bySurface = new Map(rows.map((r) => [r.surface, r]));
     const surfaces = [];
     for (const surface of TOKEN_SURFACES) {
@@ -120,13 +71,7 @@ export function summarizeTokenUse(db, tenantId, sinceIso) {
             sessions: Number(r.sessions),
         });
     }
-    // SAFETY: the SELECT names exactly these four aggregate columns.
-    const perSession = db.prepare(`SELECT COUNT(DISTINCT session_id) AS sessions,
-            COUNT(DISTINCT CASE WHEN event <> 'reset' AND surface IN (${REREAD_SURFACES.map(() => '?').join(', ')}) 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(...REREAD_SURFACES, tenantId, sinceIso);
+    const perSession = sessionTotals(db, tenantId, sinceIso, REREAD_SURFACES);
     const sessionCount = Number(perSession?.sessions ?? 0);
     const sessionTokens = Number(perSession?.tokens ?? 0);
     return {
@@ -145,10 +90,6 @@ export function summarizeTokenUse(db, tenantId, sinceIso) {
 export function isSyntheticMessage(message) {
     return message.model === '<synthetic>';
 }
-/** JSON-value plain-object check (excludes arrays and null). */
-function isJsonObject(value) {
-    return value !== undefined && value !== null && !Array.isArray(value) && value.constructor === Object;
-}
 /** A Claude Code hook payload on stdin as a JSON object; null when empty, malformed or not an object. */
 function parseHookPayload(stdinText) {
     if (!stdinText || stdinText.trim() === '')
@@ -156,7 +97,7 @@ function parseHookPayload(stdinText) {
     try {
         // SAFETY: JSON.parse returns a JSON value by definition.
         const payload = JSON.parse(stdinText.trim());
-        return isJsonObject(payload) ? payload : null;
+        return isJsonObjectLiteral(payload) ? payload : null;
     }
     catch {
         // Malformed is one of the null cases the docblock names.
@@ -184,21 +125,10 @@ export function isSubagentPayload(stdinText) {
     const agentId = parseHookPayload(stdinText)?.agent_id;
     return isJsonString(agentId) && agentId.trim() !== '';
 }
-/**
- * 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 function tokensBySession(db, tenantId, sinceIso) {
-    // SAFETY: the SELECT names exactly these columns, all aggregates or TEXT.
-    const rows = db.prepare(`SELECT session_id,
-            SUM(CASE WHEN event = 'inject' THEN tokens ELSE 0 END) AS sent,
-            SUM(CASE WHEN event = 'skip' THEN tokens ELSE 0 END) AS skipped,
-            SUM(CASE WHEN event = 'inject' THEN 1 ELSE 0 END) AS injections
-     FROM token_ledger
-     WHERE tenant_id = ? AND ts >= ? AND session_id IS NOT NULL AND event <> 'arm'
-     GROUP BY session_id`).all(tenantId, sinceIso);
-    return rows.map((r) => ({
+    return sessionTokenRows(db, tenantId, sinceIso).map((r) => ({
         sessionId: r.session_id,
         sent: Number(r.sent),
         skipped: Number(r.skipped),
@@ -227,7 +157,7 @@ export async function readApiCalls(transcriptPath) {
                 continue;
             }
             // Sidechain calls, sidechain compactions and `<synthetic>` messages never touch the main context.
-            if (!isJsonObject(entry) || entry.isSidechain === true)
+            if (!isJsonObjectLiteral(entry) || entry.isSidechain === true)
                 continue;
             if (entry.subtype === 'compact_boundary') {
                 compactions += 1;
@@ -235,9 +165,9 @@ export async function readApiCalls(transcriptPath) {
             }
             // One call spans lines sharing a message id.
             const message = entry.message;
-            if (entry.type !== 'assistant' || !isJsonObject(message))
+            if (entry.type !== 'assistant' || !isJsonObjectLiteral(message))
                 continue;
-            if (!isJsonObject(message.usage) || isSyntheticMessage(message) || !isJsonString(message.id))
+            if (!isJsonObjectLiteral(message.usage) || isSyntheticMessage(message) || !isJsonString(message.id))
                 continue;
             if (seen.has(message.id))
                 continue;
@@ -260,17 +190,19 @@ export function carryingCalls(calls, at) {
         return [];
     return calls.filter((call) => call.at > at && call.compactions === first.compactions);
 }
-/** Replace a session's `reread` rows in one transaction, one per {@link REREAD_SURFACES} surface and UTC day; returns the tokens booked. */
-export function recordRereads(db, tenantId, sessionId, calls) {
-    db.exec('BEGIN IMMEDIATE');
-    let committed = false;
-    try {
-        // SAFETY: the SELECT names exactly these three columns.
-        const rows = db.prepare(`SELECT ts, surface, tokens FROM token_ledger
-       WHERE tenant_id = ? AND session_id = ? AND event = 'inject' AND surface IN (${REREAD_SURFACES.map(() => '?').join(', ')})`).all(tenantId, sessionId, ...REREAD_SURFACES);
+/** 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);
+    });
+}
+/** One transaction, so a refused row leaves the session's earlier re-read rows in place. */
+function replaceRereadRows(db, tenantId, sessionId, calls) {
+    return withWriteScope(db, 'record_rereads', () => {
+        const rows = injectedBlocks(db, tenantId, sessionId, REREAD_SURFACES);
         const days = new Map();
         const add = (surface, at, rereads, tokens) => {
-            const key = `${surface} ${new Date(at).toISOString().slice(0, 10)}`;
+            const key = `${surface} ${new Date(at).toISOString().slice(0, DATE_PREFIX_CHARS)}`;
             const day = days.get(key) ?? { surface, at, rereads: 0, tokens: 0 };
             days.set(key, { surface, at: Math.max(day.at, at), rereads: day.rereads + rereads, tokens: day.tokens + tokens });
         };
@@ -282,23 +214,13 @@ export function recordRereads(db, tenantId, sessionId, calls) {
             for (const call of carryingCalls(calls, sentAt).slice(1))
                 add(row.surface, call.at, 1, Number(row.tokens));
         }
-        db.prepare(`DELETE FROM token_ledger WHERE tenant_id = ? AND session_id = ? AND event = 'reread'`).run(tenantId, sessionId);
+        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(),
             });
         }
-        db.exec('COMMIT');
-        committed = true;
         return [...days.values()].reduce((sum, day) => sum + day.tokens, 0);
-    }
-    finally {
-        if (!committed) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* preserve the original throw */ }
-        }
-    }
+    });
 }
 //# sourceMappingURL=token-ledger.js.map

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

@@ -0,0 +1,12 @@
+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. */
+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;
+    close(): void;
+}
+export declare function lazyTombstoneChecks(hippoRoot: string, dryRun: boolean): TombstoneChecks;
+//# sourceMappingURL=tombstone-checks.d.ts.map

package/dist/store/tombstone-checks.js

@@ -0,0 +1,31 @@
+// 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 { findRejectedValue } from './rejection.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) {
+    let handle = null;
+    const opened = () => {
+        if (dryRun)
+            return null;
+        handle ??= openHippoDb(hippoRoot);
+        return handle;
+    };
+    return {
+        find(tenantId, digest) {
+            const db = opened();
+            return db ? findRejectedValue(db, tenantId, digest) : null;
+        },
+        audit(event) {
+            const db = opened();
+            if (db)
+                appendAuditEvent(db, event);
+        },
+        close() {
+            if (handle)
+                closeHippoDb(handle);
+        },
+    };
+}
+//# sourceMappingURL=tombstone-checks.js.map

package/dist/store/usage-reports.d.ts

@@ -0,0 +1,7 @@
+import { type TokenSummary } from './token-ledger.js';
+import { type FailureSummary } from './failure-log.js';
+/** One tenant's token ledger totals since `sinceIso`. */
+export declare function tokenUseSummary(hippoRoot: string, tenantId: string, sinceIso: string): TokenSummary;
+/** One tenant's failure log totals since `sinceIso`. */
+export declare function failureLogSummary(hippoRoot: string, tenantId: string, sinceIso: string): FailureSummary;
+//# sourceMappingURL=usage-reports.d.ts.map

package/dist/store/usage-reports.js

@@ -0,0 +1,18 @@
+// 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.
+import { onHandle } from './open.js';
+import { summarizeTokenUse } from './token-ledger.js';
+import { summarizeFailures } from './failure-log.js';
+/** One tenant's token ledger totals since `sinceIso`. */
+export function tokenUseSummary(hippoRoot, tenantId, sinceIso) {
+    return onHandle(hippoRoot, (db) => {
+        return summarizeTokenUse(db, tenantId, sinceIso);
+    });
+}
+/** One tenant's failure log totals since `sinceIso`. */
+export function failureLogSummary(hippoRoot, tenantId, sinceIso) {
+    return onHandle(hippoRoot, (db) => {
+        return summarizeFailures(db, tenantId, sinceIso);
+    });
+}
+//# sourceMappingURL=usage-reports.js.map