hippo-memory 1.69.0 → 1.70.0

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

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

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

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

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

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

package/dist/store/summaries.d.ts

@@ -1,13 +1,4 @@
-import type { MemoryEntry } from '../memory.js';
-/**
- * Load summaries flagged dirty for the given tenant. Sorted by latest_at
- * DESC (NULLS LAST) so the rebuild cap (HIPPO_DAG_REBUILD_CAP, default 20)
- * takes the most-recently-changed summaries first.
- *
- * Returns full MemoryEntry shape via MEMORY_SELECT_COLUMNS + rowToEntry
- * (v28 fields are part of the standard read path).
- */
-export declare function loadDirtySummaries(hippoRoot: string, tenantId: string): MemoryEntry[];
+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
@@ -33,7 +24,7 @@ export declare function markSummaryDirty(hippoRoot: string, summaryId: string, t
  */
 export declare function loadAllL2Summaries(hippoRoot: string): MemoryEntry[];
 /**
- * Host-wide variant of loadDirtySummaries. Iterates all tenants
+ * 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.

package/dist/store/summaries.js

@@ -1,43 +1,16 @@
-import { closeHippoDb, withWriteScope } from '../db.js';
-import { assertTenantId } from '../tenant.js';
-import { findRejectedValue, rejectionDigest } from '../rejection.js';
-import { log } from '../log.js';
+import { closeHippoDb, 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 { 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.
 // ---------------------------------------------------------------------------
-/**
- * Load summaries flagged dirty for the given tenant. Sorted by latest_at
- * DESC (NULLS LAST) so the rebuild cap (HIPPO_DAG_REBUILD_CAP, default 20)
- * takes the most-recently-changed summaries first.
- *
- * Returns full MemoryEntry shape via MEMORY_SELECT_COLUMNS + rowToEntry
- * (v28 fields are part of the standard read path).
- */
-export function loadDirtySummaries(hippoRoot, tenantId) {
-    assertTenantId('loadDirtySummaries', tenantId);
-    const db = openStore(hippoRoot);
-    try {
-        // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
-        // MemoryRow's field set.
-        const rows = db.prepare(`
-      SELECT ${MEMORY_SELECT_COLUMNS}
-        FROM memories
-       WHERE summary_dirty = 1
-         AND tenant_id = ?
-         AND kind != 'archived'
-       ORDER BY latest_at DESC NULLS LAST, id ASC
-    `).all(tenantId);
-        return rows.map(rowToEntry);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
 /**
  * Mark a summary as dirty. Idempotent (re-marking dirty is a no-op + no
  * second audit row). Tenant-scoped to prevent cross-tenant writes via
@@ -70,7 +43,7 @@ export function markSummaryDirty(hippoRoot, summaryId, tenantId, actor = 'cli')
         if (result) {
             // audit() wraps appendAuditEvent in try/catch (v27 heal scenario).
             // metadata.source tells this dirty-mark apart from the other wiring layers' marks.
-            audit(db, 'summary_marked_dirty', summaryId, { dag_level: result.dag_level, source: 'E1' }, actor, tenantId);
+            audit(db, 'summary_marked_dirty', { targetId: summaryId, metadata: { dag_level: result.dag_level, source: 'E1' }, actor, tenantId });
         }
     }
     finally {
@@ -117,7 +90,7 @@ export function loadAllL2Summaries(hippoRoot) {
     }
 }
 /**
- * Host-wide variant of loadDirtySummaries. Iterates all tenants
+ * 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.
@@ -254,9 +227,9 @@ function auditRefusedRebuild(db, summary, patch, tombstone) {
     // post-rollback auditRejectionRefusal helper (writeEntry/supersede's
     // tool) is the wrong one here; a direct audit() call is correct and
     // commits with the rest of this savepoint.
-    audit(db, 'reject_refusal', summary.id, { digest: tombstone.digest, reason: tombstone.reason }, patch.actor, summary.tenantId);
+    audit(db, 'reject_refusal', { targetId: summary.id, metadata: { digest: tombstone.digest, reason: tombstone.reason }, actor: patch.actor, tenantId: summary.tenantId });
     log.warn(`applyRebuildResult: refused rebuild content for ${summary.id} — matches a rejected value ` +
-        `(digest ${tombstone.digest.slice(0, 12)}...); metadata updated, content unchanged`);
+        `(digest ${tombstone.digest.slice(0, DIGEST_DISPLAY_CHARS)}...); metadata updated, content unchanged`);
 }
 function syncRebuiltSummary(db, summary, patch, applyContentWrite, nowIso) {
     // A bare UPDATE on memories does NOT update memories_fts, so resync from the patched entry;
@@ -274,13 +247,13 @@ function syncRebuiltSummary(db, summary, patch, applyContentWrite, nowIso) {
             : summary.rebuild_count,
     };
     syncFtsRow(db, patchedEntry);
-    audit(db, 'summary_rebuilt', summary.id, {
-        // Actual level from the summary in scope, never hardcoded: L2 -> 2, L3 -> 3.
-        dag_level: summary.dag_level,
-        source: 'E3-rebuild',
-        zero_children: patch.zeroChildren,
-        descendant_count: patch.descendant_count,
-    }, patch.actor, summary.tenantId);
+    audit(db, 'summary_rebuilt', { targetId: summary.id, metadata: {
+            // Actual level from the summary in scope, never hardcoded: L2 -> 2, L3 -> 3.
+            dag_level: summary.dag_level,
+            source: 'E3-rebuild',
+            zero_children: patch.zeroChildren,
+            descendant_count: patch.descendant_count,
+        }, actor: patch.actor, tenantId: summary.tenantId });
 }
 /**
  * Clear summary_dirty on a freshly-built summary. Called by buildDag right after the child-link loop:
@@ -308,7 +281,7 @@ export function clearSummaryDirtyAfterBuild(hippoRoot, summaryId, tenantId, acto
     `).get(summaryId, tenantId);
         if (result) {
             // source tells buildDag-clean (L2) from buildEntityProfiles-clean (L3) and any future build path.
-            audit(db, 'summary_marked_clean', summaryId, { dag_level: result.dag_level, source }, actor, tenantId);
+            audit(db, 'summary_marked_clean', { targetId: summaryId, metadata: { dag_level: result.dag_level, source }, actor, tenantId });
         }
     }
     finally {

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

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

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

@@ -1,4 +1,4 @@
-import type { DatabaseSyncLike } from '../db.js';
+import type { DatabaseSyncLike } from '../db/index.js';
 /** The api_keys fields a tenant, revocation, rank or self-service ownership check reads. */
 export interface ApiKeyOwner {
     tenantId: string;

package/dist/{tenant.d.ts → store/tenant.d.ts}

@@ -1,5 +1,5 @@
-import type { DatabaseSyncLike } from './db.js';
-import type { JsonValue } from './json.js';
+import type { DatabaseSyncLike } from '../db/index.js';
+import type { JsonValue } from '../util/json.js';
 export interface ResolveOpts {
     db?: DatabaseSyncLike;
     apiKey?: string;

package/dist/{tenant.js → store/tenant.js}

@@ -1,4 +1,4 @@
-import { envTenant } from './env.js';
+import { envTenant } from '../util/env.js';
 import { validateApiKey } from './auth.js';
 export function resolveTenantId(opts) {
     if (opts.apiKey) {

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,4 +1,4 @@
-import type { DatabaseSyncLike } from './db.js';
+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`).
@@ -7,7 +7,7 @@ import type { DatabaseSyncLike } from './db.js';
  * - `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.
+ * - `pilot`: the session's pilot arm row (src/api/pilot-arm.ts); not a send, so it is 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. */
@@ -25,13 +25,6 @@ export declare const REREAD_SURFACES: readonly TokenSurface[];
 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;