hippo-memory 1.70.0 → 1.72.0

package/dist/store/handoffs.d.ts

@@ -1,11 +1,9 @@
 import { type SessionHandoff, type HandoffOutcome, type HandoffEvidence } from '../core/handoff.js';
 import type { TaskSnapshot } from './rows.js';
 import { type ContinuityKey } from './sessions.js';
-/** Column list shared by every session_handoffs SELECT; store-cards.ts reuses it for the card handoff lookup. */
-export declare const HANDOFF_COLUMNS = "id, session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, created_at, constraints_json, evidence_json, outcome, target_runtime, card_id";
-/**
- * Save a session handoff record. Returns the persisted handoff.
- */
+/** Column list shared by every session_handoffs SELECT; cards.ts reuses it for the card handoff lookup. */
+export declare const HANDOFF_COLUMNS: string;
+/** Save a session handoff record; returns the persisted handoff. */
 export declare function saveSessionHandoff(hippoRoot: string, tenantId: string, handoff: Omit<SessionHandoff, 'updatedAt'>, key?: ContinuityKey): SessionHandoff;
 interface HandoffFilter {
     unfinishedOnly?: boolean;
@@ -15,16 +13,12 @@ interface HandoffFilter {
 }
 /** Load the most recent handoff, optionally filtered by session ID. */
 export declare function loadLatestHandoff(hippoRoot: string, tenantId: string, sessionId?: string, opts?: HandoffFilter, key?: ContinuityKey): SessionHandoff | null;
-/**
- * Load a specific handoff by its row ID.
- */
+/** Load a specific handoff by its row ID. */
 export declare function loadHandoffById(hippoRoot: string, tenantId: string, id: number): SessionHandoff | null;
 /** Stamp the outcome on a session's newest handoff, only if it has none yet. Returns rows changed. */
 export declare function stampHandoffOutcome(hippoRoot: string, tenantId: string, sessionId: string, outcome: HandoffOutcome): number;
-/** Auto-write a handoff at session-end from the session's active snapshot, else from `derived`, its transcript state.
- * @param evidence best-effort git state; outcome comes from the newest session_complete event.
- * @param options.inPlace rewrite an earlier transcript read instead of adding a revision, for a close that runs after every reply.
- * @returns null when neither source is the session's, a newer handoff covers the snapshot, the session's latest handoff was not read off its transcript or already holds `derived`, or, in place, a handoff landed after the read. */
+/** Session-end handoff from the active snapshot, else `derived` transcript state; `inPlace` rewrites an earlier transcript read instead of adding a revision.
+ * Returns null when no source is the session's, a newer handoff covers it, or the latest one is not transcript-derived or already holds `derived`. */
 export declare function writeSessionEndHandoff(hippoRoot: string, tenantId: string, sessionId: string, evidence: HandoffEvidence | null, derived?: Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'> | null, key?: ContinuityKey, options?: {
     inPlace?: boolean;
 }): SessionHandoff | null;

package/dist/store/handoffs.js

@@ -1,14 +1,13 @@
-import { closeHippoDb, openHippoDb } from '../db/index.js';
+import { closeHippoDb } from '../db/index.js';
 import { rowToSessionHandoff, isHandoffOutcome, } from '../core/handoff.js';
-import { scopeAdmitSql } from './recall-scope.js';
+import { scopeAdmitSql } from './rule-sql.js';
 import { assertTenantId } from './tenant.js';
-import { openStore } from './open.js';
+import { onHandle, openStore } from './open.js';
 import { continuityStamp, continuityWhere, loadActiveTaskSnapshot } from './sessions.js';
-/** Column list shared by every session_handoffs SELECT; store-cards.ts reuses it for the card handoff lookup. */
-export const HANDOFF_COLUMNS = 'id, session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, created_at, constraints_json, evidence_json, outcome, target_runtime, card_id';
-/**
- * Save a session handoff record. Returns the persisted handoff.
- */
+/** Column list shared by every session_handoffs SELECT; cards.ts reuses it for the card handoff lookup. */
+export const HANDOFF_COLUMNS = 'id, session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, created_at, constraints_json, ' +
+    'evidence_json, outcome, target_runtime, card_id';
+/** Save a session handoff record; returns the persisted handoff. */
 export function saveSessionHandoff(hippoRoot, tenantId, handoff, key) {
     assertTenantId('saveSessionHandoff', tenantId);
     const stamp = key ? continuityStamp(key) : null;
@@ -17,10 +16,9 @@ export function saveSessionHandoff(hippoRoot, tenantId, handoff, key) {
     // Scope is stored as given; read-side default-deny in api.recall + cmdRecall
     // continuity excludes slack:private:* and 'unknown:legacy'.
     try {
-        const result = db.prepare(`
-      INSERT INTO session_handoffs(session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, tenant_id, created_at, constraints_json, evidence_json, outcome, target_runtime, card_id, owner_subject, origin_project)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(handoff.sessionId, handoff.repoRoot ?? null, handoff.taskId ?? null, handoff.summary, handoff.nextAction ?? null, JSON.stringify(handoff.artifacts ?? []), handoff.scope ?? null, tenantId, now, JSON.stringify(handoff.constraints ?? []), handoff.evidence ? JSON.stringify(handoff.evidence) : null, handoff.outcome ?? null, handoff.targetRuntime ?? null, handoff.cardId ?? null, stamp?.owner ?? null, stamp?.origin ?? null);
+        const result = db.prepare(`\n      INSERT INTO session_handoffs(session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, tenant_id, created_at, ` +
+            `constraints_json, evidence_json, outcome, target_runtime, card_id, owner_subject, origin_project)\n` +
+            `      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\n    `).run(handoff.sessionId, handoff.repoRoot ?? null, handoff.taskId ?? null, handoff.summary, handoff.nextAction ?? null, JSON.stringify(handoff.artifacts ?? []), handoff.scope ?? null, tenantId, now, JSON.stringify(handoff.constraints ?? []), handoff.evidence ? JSON.stringify(handoff.evidence) : null, handoff.outcome ?? null, handoff.targetRuntime ?? null, handoff.cardId ?? null, stamp?.owner ?? null, stamp?.origin ?? null);
         const id = Number(result.lastInsertRowid ?? 0);
         // SAFETY: row's shape matches HANDOFF_COLUMNS.
         const row = db.prepare(`SELECT ${HANDOFF_COLUMNS} FROM session_handoffs WHERE id = ?`).get(id);
@@ -50,8 +48,7 @@ function handoffConditions(tenantId, sessionId, opts, key) {
         params.push(opts.excludeSessionId);
     }
     if (opts.unfinishedOnly) {
-        // Restrict to each session's newest revision first: stampHandoffOutcome
-        // only stamps the newest row, so an older null-outcome revision must not resurrect.
+        // Restrict to each session's newest revision first: stampHandoffOutcome only stamps the newest row, so an older null-outcome revision must not resurrect.
         // Keyed, the newest is the owner's own, so another owner's newer revision cannot hide it.
         conditions.push(`id IN (SELECT MAX(id) FROM session_handoffs WHERE tenant_id = ?${owned ? ` AND ${owned.sql}` : ''} GROUP BY session_id)`);
         params.push(tenantId, ...(owned?.params ?? []));
@@ -89,9 +86,7 @@ export function loadLatestHandoff(hippoRoot, tenantId, sessionId, opts = {}, key
         closeHippoDb(db);
     }
 }
-/**
- * Load a specific handoff by its row ID.
- */
+/** Load a specific handoff by its row ID. */
 export function loadHandoffById(hippoRoot, tenantId, id) {
     assertTenantId('loadHandoffById', tenantId);
     const db = openStore(hippoRoot);
@@ -111,8 +106,7 @@ export function loadHandoffById(hippoRoot, tenantId, id) {
 /** Stamp the outcome on a session's newest handoff, only if it has none yet. Returns rows changed. */
 export function stampHandoffOutcome(hippoRoot, tenantId, sessionId, outcome) {
     assertTenantId('stampHandoffOutcome', tenantId);
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const result = db.prepare(`
       UPDATE session_handoffs SET outcome = ?
       WHERE tenant_id = ? AND session_id = ? AND outcome IS NULL
@@ -123,17 +117,14 @@ export function stampHandoffOutcome(hippoRoot, tenantId, sessionId, outcome) {
         )
     `).run(outcome, tenantId, sessionId, tenantId, sessionId);
         return Number(result.changes ?? 0);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/** Rewrites the session's newest handoff when it is still a transcript read, in one statement so a handoff written meanwhile is never overwritten; null when none was rewritten. */
+/** Rewrites the session's newest handoff when it is still a transcript read, in one statement so a handoff written meanwhile is never overwritten; null
+ * when none was rewritten. */
 function replaceTranscriptHandoff(hippoRoot, tenantId, handoff, key) {
     const { conditions, params } = handoffConditions(tenantId, handoff.sessionId, {}, key);
     const newest = `SELECT id FROM session_handoffs WHERE ${conditions.join(' AND ')} ORDER BY created_at DESC, id DESC LIMIT 1`;
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const result = db.prepare(`
       UPDATE session_handoffs SET repo_root = ?, task_id = ?, summary = ?, next_action = ?, artifacts_json = ?, scope = ?, created_at = ?,
         constraints_json = ?, evidence_json = ?, outcome = ?, target_runtime = ?, card_id = ?
@@ -144,10 +135,7 @@ function replaceTranscriptHandoff(hippoRoot, tenantId, handoff, key) {
         // SAFETY: row's shape matches HANDOFF_COLUMNS.
         const row = db.prepare(`SELECT ${HANDOFF_COLUMNS} FROM session_handoffs WHERE id = (${newest})`).get(...params);
         return row ? rowToSessionHandoff(row) : null;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 function transcriptHandoffSource(existing, derived, evidence) {
     // Only an earlier transcript read gives way; `hippo handoff create` and unmarked older handoffs keep winning.
@@ -179,10 +167,8 @@ function buildSessionEndHandoff(sessionId, snapshot, existing, handoffEvidence,
         cardId: carryForward ? existing.cardId : undefined,
     };
 }
-/** Auto-write a handoff at session-end from the session's active snapshot, else from `derived`, its transcript state.
- * @param evidence best-effort git state; outcome comes from the newest session_complete event.
- * @param options.inPlace rewrite an earlier transcript read instead of adding a revision, for a close that runs after every reply.
- * @returns null when neither source is the session's, a newer handoff covers the snapshot, the session's latest handoff was not read off its transcript or already holds `derived`, or, in place, a handoff landed after the read. */
+/** Session-end handoff from the active snapshot, else `derived` transcript state; `inPlace` rewrites an earlier transcript read instead of adding a revision.
+ * Returns null when no source is the session's, a newer handoff covers it, or the latest one is not transcript-derived or already holds `derived`. */
 export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence, derived = null, key, options = {}) {
     assertTenantId('writeSessionEndHandoff', tenantId);
     if (key)
@@ -216,8 +202,7 @@ export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence,
     return saveSessionHandoff(hippoRoot, tenantId, handoff, key);
 }
 function sessionOutcome(hippoRoot, tenantId, sessionId) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: row's shape matches the single `content` column below.
         const content = db.prepare(`
       SELECT content FROM session_events
@@ -225,9 +210,6 @@ function sessionOutcome(hippoRoot, tenantId, sessionId) {
       ORDER BY created_at DESC, id DESC LIMIT 1
     `).get(tenantId, sessionId)?.content;
         return isHandoffOutcome(content) ? content : null;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 //# sourceMappingURL=handoffs.js.map

package/dist/store/index-and-stats.d.ts

@@ -4,16 +4,10 @@ import type { HippoIndex, LegacyStats } from './rows.js';
 export declare function loadIndex(hippoRoot: string): HippoIndex;
 /** The last recall's ids and its trace alone, for a caller that needs no index entry. */
 export declare function loadLastRecall(hippoRoot: string): Pick<HippoIndex, 'last_retrieval_ids' | 'last_trace_id'>;
-/**
- * Persist mutable index metadata. Entry rows themselves are derived from SQLite.
- *
- * `last_retrieval_ids` and `last_trace_id` commit in one transaction: callers fold a fresh trace id
- * into the index and rely on both keys moving together. index.json is left to `rebuildIndex`.
- */
+/** Persist mutable index metadata (entry rows are derived from SQLite); `last_retrieval_ids` and `last_trace_id` commit in one transaction, as callers
+ * rely on both moving together. index.json is left to `rebuildIndex`. */
 export declare function saveIndex(hippoRoot: string, index: Pick<HippoIndex, 'last_retrieval_ids' | 'last_trace_id'>): void;
-/**
- * Rebuild mirrors from SQLite, importing any legacy markdown files not already present.
- */
+/** Rebuild mirrors from SQLite, importing any legacy markdown files not already present. */
 export declare function rebuildIndex(hippoRoot: string): HippoIndex;
 export declare function updateStats(hippoRoot: string, delta: {
     remembered?: number;
@@ -32,9 +26,7 @@ export declare function appendConsolidationRun(hippoRoot: string, run: {
 }): void;
 /** Rows a tenant created since the last sleep (runs are host-wide), looking back at most 24 hours. */
 export declare function countCreatedSinceLastSleep(hippoRoot: string, tenantId: string, now?: Date): number;
-/**
- * Session decay context: provides the data needed for session-based and adaptive decay.
- */
+/** Session decay context: the data needed for session-based and adaptive decay. */
 export interface SessionDecayContext {
     /** Total number of sleep (consolidation) cycles completed. */
     sleepCount: number;
@@ -43,13 +35,8 @@ export interface SessionDecayContext {
 }
 /** Timestamp of the latest consolidation run, or undefined when there is none. */
 export declare function lastConsolidationAt(db: DatabaseSyncLike): string | undefined;
-/**
- * Load the session decay context from the store.
- * Uses consolidation_runs timestamps to compute session intervals.
- */
+/** Load the session decay context; session intervals come from consolidation_runs timestamps. */
 export declare function loadSessionDecayContext(hippoRoot: string): SessionDecayContext;
-/**
- * Increment the sleep counter. Called after each consolidation run.
- */
+/** Increment the sleep counter after each consolidation run. */
 export declare function incrementSleepCount(hippoRoot: string): void;
 //# sourceMappingURL=index-and-stats.d.ts.map

package/dist/store/index-and-stats.js

@@ -1,55 +1,36 @@
-import { closeHippoDb, withWriteScope, setMeta, isSqliteBusy, pruneConsolidationRuns, getMeta } from '../db/index.js';
-import { RejectedValueError } from './rejection.js';
+import { withWriteScope, setMeta, isSqliteBusy, pruneConsolidationRuns, getMeta } from '../db/index.js';
+import { RejectedValueError } from '../core/api-errors.js';
 import { log } from '../util/log.js';
 import { audit } from './audit-event.js';
 import { stampOriginProjectForImport, upsertEntryRow } from './entry-row.js';
 import { buildIndexFromDb, readLastRecall, syncMirrorFiles, writeIndexMirror, writeStatsMirror, buildStatsFromDb } from './mirrors.js';
-import { openStore, loadLegacyEntriesFromMarkdown } from './open.js';
+import { onHandle, openStore, loadLegacyEntriesFromMarkdown } from './open.js';
 import { DAY_MS } from '../util/time.js';
 /** Load the derived index from SQLite. Read-only: index.json is only ever written by `rebuildIndex`. */
 export function loadIndex(hippoRoot) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return buildIndexFromDb(db);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** The last recall's ids and its trace alone, for a caller that needs no index entry. */
 export function loadLastRecall(hippoRoot) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return readLastRecall(db);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Persist mutable index metadata. Entry rows themselves are derived from SQLite.
- *
- * `last_retrieval_ids` and `last_trace_id` commit in one transaction: callers fold a fresh trace id
- * into the index and rely on both keys moving together. index.json is left to `rebuildIndex`.
- */
+/** Persist mutable index metadata (entry rows are derived from SQLite); `last_retrieval_ids` and `last_trace_id` commit in one transaction, as callers
+ * rely on both moving together. index.json is left to `rebuildIndex`. */
 export function saveIndex(hippoRoot, index) {
-    const db = openStore(hippoRoot);
-    try {
+    onHandle(hippoRoot, (db) => {
         withWriteScope(db, 'save_index', () => {
             setMeta(db, 'last_retrieval_ids', JSON.stringify(index.last_retrieval_ids ?? []));
             setMeta(db, 'last_trace_id', index.last_trace_id ?? '');
         });
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Rebuild mirrors from SQLite, importing any legacy markdown files not already present.
- */
+/** Rebuild mirrors from SQLite, importing any legacy markdown files not already present. */
 export function rebuildIndex(hippoRoot) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: rows' shape matches the single `id` column selected above.
         const existingIds = new Set(db.prepare(`SELECT id FROM memories`).all().map((row) => row.id));
         const legacyEntries = loadLegacyEntriesFromMarkdown(hippoRoot).filter((entry) => !existingIds.has(entry.id));
@@ -67,7 +48,12 @@ export function rebuildIndex(hippoRoot) {
                     catch (err) {
                         if (err instanceof RejectedValueError) {
                             rejectedCount++;
-                            audit(db, 'reject_refusal', { targetId: err.entryId, metadata: { digest: err.digest, reason: err.reason }, actor: 'cli', tenantId: err.tenantId });
+                            audit(db, 'reject_refusal', {
+                                targetId: err.entryId,
+                                metadata: { digest: err.digest, reason: err.reason },
+                                actor: 'cli',
+                                tenantId: err.tenantId
+                            });
                             continue;
                         }
                         throw err;
@@ -82,25 +68,16 @@ export function rebuildIndex(hippoRoot) {
         const index = buildIndexFromDb(db);
         writeIndexMirror(hippoRoot, index);
         return index;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 export function updateStats(hippoRoot, delta) {
-    const db = openStore(hippoRoot);
-    try {
+    onHandle(hippoRoot, (db) => {
         updateStatsOn(db, hippoRoot, delta);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** updateStats on the caller's open store, so a loop of writes opens the store once. */
 export function updateStatsOn(db, hippoRoot, delta) {
-    // One atomic statement per counter, and only for counters the caller
-    // named: the read-modify-write this replaces both lost increments to a
-    // concurrent writer and stamped stale values over the untouched two.
+    // One atomic statement per named counter: a read-modify-write loses concurrent increments and stamps stale values over the untouched two.
     const increments = [
         ['total_remembered', delta.remembered ?? 0],
         ['total_recalled', delta.recalled ?? 0],
@@ -129,37 +106,25 @@ export function updateStatsUnlessBusy(hippoRoot, delta, committed) {
     }
 }
 export function loadStats(hippoRoot) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return buildStatsFromDb(db);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 export function appendConsolidationRun(hippoRoot, run) {
-    const db = openStore(hippoRoot);
-    try {
+    onHandle(hippoRoot, (db) => {
         db.prepare(`INSERT INTO consolidation_runs(timestamp, decayed, merged, removed) VALUES (?, ?, ?, ?)`).run(run.timestamp, run.decayed, run.merged, run.removed);
-        pruneConsolidationRuns(db, 50);
+        pruneConsolidationRuns(db);
         writeStatsMirror(hippoRoot, buildStatsFromDb(db));
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** Rows a tenant created since the last sleep (runs are host-wide), looking back at most 24 hours. */
 export function countCreatedSinceLastSleep(hippoRoot, tenantId, now = new Date()) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const dayAgo = new Date(now.getTime() - DAY_MS).toISOString();
         const row = db.prepare(`SELECT COUNT(*) AS n FROM memories WHERE tenant_id = ?
          AND created > MAX(?, COALESCE((SELECT MAX(timestamp) FROM consolidation_runs), ''))`).get(tenantId, dayAgo);
         return row.n;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** Timestamp of the latest consolidation run, or undefined when there is none. */
 export function lastConsolidationAt(db) {
@@ -167,13 +132,9 @@ export function lastConsolidationAt(db) {
     const row = db.prepare(`SELECT timestamp FROM consolidation_runs ORDER BY timestamp DESC, id DESC LIMIT 1`).get();
     return row?.timestamp;
 }
-/**
- * Load the session decay context from the store.
- * Uses consolidation_runs timestamps to compute session intervals.
- */
+/** Load the session decay context; session intervals come from consolidation_runs timestamps. */
 export function loadSessionDecayContext(hippoRoot) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // Get recent consolidation timestamps (last 20)
         // SAFETY: rows' shape matches the single `timestamp` column above.
         const rows = db.prepare(`SELECT timestamp FROM consolidation_runs ORDER BY timestamp DESC, id DESC LIMIT 20`).all();
@@ -190,22 +151,13 @@ export function loadSessionDecayContext(hippoRoot) {
         const avgMs = totalInterval / (timestamps.length - 1);
         const avgDays = avgMs / DAY_MS;
         return { sleepCount, avgSessionIntervalDays: Math.max(0, avgDays) };
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Increment the sleep counter. Called after each consolidation run.
- */
+/** Increment the sleep counter after each consolidation run. */
 export function incrementSleepCount(hippoRoot) {
-    const db = openStore(hippoRoot);
-    try {
+    onHandle(hippoRoot, (db) => {
         const current = Number(getMeta(db, 'sleep_count', '0')) || 0;
         setMeta(db, 'sleep_count', String(current + 1));
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 //# sourceMappingURL=index-and-stats.js.map

package/dist/store/key-writes.js

@@ -3,7 +3,7 @@ import { BadRequestError, ConflictError, NotFoundError } from '../core/api-error
 import { appendAuditEvent } from './audit.js';
 import { grantScope, insertApiKey, listLiveOwnedKeyIds, revokeApiKey, ungrantScope } from './auth.js';
 import { withWriteScope } from '../db/index.js';
-import { isRestrictedScope } from './recall-scope.js';
+import { isRestrictedScope } from '../core/recall-scope.js';
 import { selectApiKeyOwner } from './tenant-lookup.js';
 /** The auth_create row a mint writes; the plaintext never reaches it. */
 function createAuditOf({ key, actor, metadata }) {

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

@@ -1,5 +1,9 @@
 import type { DeliveryEventInput } from './delivery-recorder.js';
 import { type LastSent, type TokenSurface, type TokenUse } from './token-ledger.js';
+import { type PilotArm } from './pilot-arm.js';
+/** Says why a ledger row did not land, at the level its class earns: busy warns once through
+ * noteStoreBusy, absent is debug with no stack, unexpected warns once with the error class and stack. */
+export declare function noteLedgerRowSkipped<E>(error: E): void;
 /** Stores one delivery event and returns its id, or null when the write failed. */
 export type DeliveryWrite = (input: DeliveryEventInput) => number | null;
 /** The token rows of one turn and the delivery event that follows them. */
@@ -14,4 +18,9 @@ export interface LedgerTurn {
 export declare function recordLedgerTurn(hippoRoot: string, turn: LedgerTurn): void;
 /** What the session last sent on `surface`, or null, as lastSentState reads it. */
 export declare function lastSentOnSurface(hippoRoot: string, tenantId: string, sessionId: string | null | undefined, surface: TokenSurface): LastSent | null;
+/** The session's pilot arm: `write` books it as ensurePilotArm does, else the stored arm or the hash arm. */
+export declare function pilotArmOnRoot(hippoRoot: string, tenantId: string, sessionId: string, rateBp: number, opts: {
+    write: boolean;
+    ownTenantOnly?: boolean;
+}): PilotArm;
 //# sourceMappingURL=ledger-turn.d.ts.map

package/dist/store/ledger-turn.js

@@ -1,6 +1,37 @@
+// One hook or context turn's token-ledger work by store root: each call opens hippo.db, runs on one connection and closes it.
+import { isSqliteBusy, noteStoreBusy } from '../db/index.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { lastSentState, recordTokenUse } from './token-ledger.js';
 import { onHandle } from './open.js';
+import { ensurePilotArm, hashArm, readPilotArm } from './pilot-arm.js';
 import { writeDeliveryEventOnHandle } from './recall-trace.js';
+// SQLite's result codes for a hippo.db it cannot read: a corrupt image, and a file that is no database.
+const SQLITE_CORRUPT = 11;
+const SQLITE_NOTADB = 26;
+/** The one rule for a skipped ledger row. `absent` is a store with no token_ledger table or a hippo.db
+ * SQLite cannot read; the command that owns the store reports that, and a hook must stay quiet about it. */
+function ledgerSkipClass(error) {
+    if (isSqliteBusy(error))
+        return 'busy';
+    const code = error instanceof Error && 'errcode' in error ? error.errcode : undefined;
+    if (code === SQLITE_CORRUPT || code === SQLITE_NOTADB)
+        return 'absent';
+    return errorMessage(error).includes('no such table: token_ledger') ? 'absent' : 'unexpected';
+}
+/** Says why a ledger row did not land, at the level its class earns: busy warns once through
+ * noteStoreBusy, absent is debug with no stack, unexpected warns once with the error class and stack. */
+export function noteLedgerRowSkipped(error) {
+    const skip = ledgerSkipClass(error);
+    if (skip === 'busy') {
+        noteStoreBusy('token ledger row skipped');
+        return;
+    }
+    const message = `token ledger row skipped: ${errorMessage(error)}`;
+    if (skip === 'absent')
+        log.debug(message);
+    else
+        log.warnThenDebug('token-ledger-row', message, errorFields(error));
+}
 /** Books a turn's token rows, then its delivery event, on one connection. */
 export function recordLedgerTurn(hippoRoot, turn) {
     const { onRowError } = turn;
@@ -24,4 +55,11 @@ export function recordLedgerTurn(hippoRoot, turn) {
 export function lastSentOnSurface(hippoRoot, tenantId, sessionId, surface) {
     return onHandle(hippoRoot, (db) => lastSentState(db, tenantId, sessionId, surface));
 }
+/** The session's pilot arm: `write` books it as ensurePilotArm does, else the stored arm or the hash arm. */
+export function pilotArmOnRoot(hippoRoot, tenantId, sessionId, rateBp, opts) {
+    const { ownTenantOnly } = opts;
+    return onHandle(hippoRoot, (db) => opts.write
+        ? ensurePilotArm(db, tenantId, sessionId, rateBp, { ownTenantOnly })
+        : readPilotArm(db, sessionId, ownTenantOnly ? tenantId : undefined) ?? hashArm(sessionId, rateBp));
+}
 //# sourceMappingURL=ledger-turn.js.map

package/dist/store/mirrors.d.ts

@@ -9,12 +9,8 @@ export declare function removeActiveTaskMirror(hippoRoot: string, tenantId: stri
 export declare function writeRecentSessionMirror(hippoRoot: string, tenantId: string, events: SessionEvent[]): void;
 export declare function writeMarkdownMirror(hippoRoot: string, entry: MemoryEntry): void;
 export declare function removeEntryMirrors(hippoRoot: string, id: string): void;
-/**
- * Best-effort mirror purge. Retries the unlink once (most failures are transient locks); the reaper only
- * scans `raw_archive`, so a non-raw id's second failure logs the leftover path(s) to delete by hand.
- *
- * Returns true if the mirror ended up purged (first or second attempt).
- */
+/** Best-effort mirror purge: retries the unlink once (most failures are transient locks); the reaper only scans `raw_archive`,
+ * so a non-raw id's second failure logs the leftover path(s) to delete by hand. Returns true if the mirror ended up purged. */
 export declare function purgeMirrorBestEffort(hippoRoot: string, id: string, isRaw: boolean, logPrefix: string): boolean;
 /** Derive the current `HippoIndex` from SQLite. Exported for `rebuildIndex`
  *  (the only index.json writer) and the longmemeval benchmark. */

package/dist/store/mirrors.js

@@ -1,12 +1,13 @@
+import { DEFAULT_TENANT_ID } from '../util/env.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { Layer } from '../core/memory.js';
-import { dumpFrontmatter } from './yaml.js';
-import { getMeta } from '../db/index.js';
+import { dumpFrontmatter } from '../util/yaml.js';
+import { getMeta, CONSOLIDATION_RUNS_KEPT } from '../db/index.js';
 import { oncePerStore } from '../db/connect.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { parseJsonArray, INDEX_VERSION, parseLastTraceId, MEMORY_SELECT_COLUMNS, rowToEntry, rowToMemoryConflict, } from './rows.js';
-import { serializeEntry } from './markdown.js';
+import { serializeEntry } from '../core/markdown.js';
 const SCORE_DECIMALS = 3;
 export function layerDir(root, layer) {
     return path.join(root, layer);
@@ -21,16 +22,14 @@ export function ensureMirrorDirectories(hippoRoot) {
         }
     });
 }
-// Tenant-scoped mirror file paths. The single-tenant 'default' deployment
-// keeps the original `active-task.md` / `recent-session.md` filenames for
-// on-disk back-compat; multi-tenant deployments get a `.<tenantId>` suffix
-// so tenant B saving cannot overwrite tenant A's mirror file.
+// Tenant-scoped mirror paths: the 'default' tenant keeps the original `active-task.md` / `recent-session.md` names;
+// other tenants get a `.<tenantId>` suffix so one cannot overwrite another's mirror.
 function activeTaskMirrorPath(hippoRoot, tenantId) {
-    const file = tenantId === 'default' ? 'active-task.md' : `active-task.${tenantId}.md`;
+    const file = tenantId === DEFAULT_TENANT_ID ? 'active-task.md' : `active-task.${tenantId}.md`;
     return path.join(hippoRoot, 'buffer', file);
 }
 function recentSessionMirrorPath(hippoRoot, tenantId) {
-    const file = tenantId === 'default' ? 'recent-session.md' : `recent-session.${tenantId}.md`;
+    const file = tenantId === DEFAULT_TENANT_ID ? 'recent-session.md' : `recent-session.${tenantId}.md`;
     return path.join(hippoRoot, 'buffer', file);
 }
 export function writeActiveTaskMirror(hippoRoot, tenantId, snapshot) {
@@ -155,22 +154,15 @@ export function removeEntryMirrors(hippoRoot, id) {
         }
     }
 }
-/**
- * Mirror paths for `id` still on disk, walked like `removeEntryMirrors`, so a failed purge
- * with no reaper to retry it can name the stuck file.
- */
+/** Mirror paths for `id` still on disk, walked like `removeEntryMirrors`, so a failed purge with no reaper to retry it can name the stuck file. */
 function getExistingEntryMirrorPaths(hippoRoot, id) {
     // Layer list kept in lockstep with removeEntryMirrors.
     return [Layer.Buffer, Layer.Episodic, Layer.Semantic, Layer.Trace]
         .map((layer) => path.join(layerDir(hippoRoot, layer), `${id}.md`))
         .filter((file) => fs.existsSync(file));
 }
-/**
- * Best-effort mirror purge. Retries the unlink once (most failures are transient locks); the reaper only
- * scans `raw_archive`, so a non-raw id's second failure logs the leftover path(s) to delete by hand.
- *
- * Returns true if the mirror ended up purged (first or second attempt).
- */
+/** Best-effort mirror purge: retries the unlink once (most failures are transient locks); the reaper only scans `raw_archive`,
+ * so a non-raw id's second failure logs the leftover path(s) to delete by hand. Returns true if the mirror ended up purged. */
 export function purgeMirrorBestEffort(hippoRoot, id, isRaw, logPrefix) {
     try {
         removeEntryMirrors(hippoRoot, id);
@@ -184,13 +176,13 @@ export function purgeMirrorBestEffort(hippoRoot, id, isRaw, logPrefix) {
         catch (secondErr) {
             const msg = errorMessage(secondErr);
             if (isRaw) {
-                log.error(`${logPrefix}: mirror cleanup failed for ${id} (will retry via reaper on next open): ${msg}`);
+                log.error(`${logPrefix}: mirror cleanup failed for ${id} (will retry via reaper on next open): ${msg}`, errorFields(secondErr));
             }
             else {
                 const leftover = getExistingEntryMirrorPaths(hippoRoot, id);
                 const pathsNote = leftover.length > 0 ? leftover.join(', ') : `${id}.md (path unresolved)`;
                 log.error(`${logPrefix}: mirror cleanup failed for ${id} - no automatic retry exists for this file, ` +
-                    `delete it manually: ${pathsNote} (${msg})`);
+                    `delete it manually: ${pathsNote} (${msg})`, errorFields(secondErr));
             }
             return false;
         }
@@ -211,7 +203,7 @@ export function buildIndexFromDb(db) {
             file: path.join(layer, `${row.id}.md`),
             layer,
             strength: Number(row.strength ?? 0),
-            tags: parseJsonArray(row.tags_json),
+            tags: parseJsonArray(row.tags_json, { table: 'memories', id: row.id, column: 'tags_json' }),
             created: row.created,
             last_retrieved: row.last_retrieved,
             pinned: Boolean(row.pinned),
@@ -221,19 +213,22 @@ export function buildIndexFromDb(db) {
 }
 /** The last recall's ids and its trace, the two meta keys saveIndex writes together. */
 export function readLastRecall(db) {
-    // Read both lockstep keys in ONE statement: two autocommit SELECTs could straddle a concurrent
-    // saveIndex and hand back a mismatched last_retrieval_ids / last_trace_id pair.
+    // Read both lockstep keys in ONE statement: two autocommit SELECTs could straddle a concurrent saveIndex and return a mismatched pair.
     // SAFETY: lockstepRows' shape matches the key/value columns named above.
     const lockstepRows = db.prepare(`SELECT key, value FROM meta WHERE key IN ('last_retrieval_ids', 'last_trace_id')`).all();
     const lockstep = new Map(lockstepRows.map((r) => [r.key, r.value]));
     return {
-        last_retrieval_ids: parseJsonArray(lockstep.get('last_retrieval_ids') ?? '[]'),
+        last_retrieval_ids: parseJsonArray(lockstep.get('last_retrieval_ids') ?? '[]', { table: 'meta', id: 'last_retrieval_ids', column: 'value' }),
         last_trace_id: parseLastTraceId(lockstep.get('last_trace_id') ?? ''),
     };
 }
 export function buildStatsFromDb(db) {
-    // SAFETY: runs' shape matches the four columns named in the SELECT above.
-    const runs = db.prepare(`SELECT timestamp, decayed, merged, removed FROM consolidation_runs ORDER BY timestamp ASC, id ASC`).all();
+    // SAFETY: runs' shape matches the four columns named in the SELECT below.
+    const runs = db.prepare(`
+    SELECT timestamp, decayed, merged, removed FROM (
+      SELECT id, timestamp, decayed, merged, removed FROM consolidation_runs ORDER BY timestamp DESC, id DESC LIMIT ?
+    ) ORDER BY timestamp ASC, id ASC
+  `).all(CONSOLIDATION_RUNS_KEPT);
     return {
         total_remembered: Number(getMeta(db, 'total_remembered', '0')),
         total_recalled: Number(getMeta(db, 'total_recalled', '0')),
@@ -249,7 +244,7 @@ export function buildStatsFromDb(db) {
 /** Write the `index.json` mirror file for an already-derived index. Exported for
  *  `rebuildIndex` (the only index.json writer) and the longmemeval benchmark. */
 export function writeIndexMirror(hippoRoot, index) {
-    mirrorBestEffort('index.json', () => fs.writeFileSync(path.join(hippoRoot, 'index.json'), JSON.stringify(index, null, 2), 'utf8'));
+    mirrorBestEffort('index.json', () => overwriteInPlace(path.join(hippoRoot, 'index.json'), JSON.stringify(index, null, 2)));
 }
 export function writeStatsMirror(hippoRoot, stats) {
     mirrorBestEffort('stats.json', () => overwriteInPlace(path.join(hippoRoot, 'stats.json'), JSON.stringify(stats, null, 2)));