hippo-memory 1.72.0 → 2.1.0

package/dist/store/handoffs.d.ts

@@ -5,7 +5,7 @@ import { type ContinuityKey } from './sessions.js';
 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 {
+export interface HandoffFilter {
     unfinishedOnly?: boolean;
     maxAgeMs?: number;
     scopeFilter?: 'default-deny';
@@ -17,10 +17,16 @@ export declare function loadLatestHandoff(hippoRoot: string, tenantId: string, s
 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;
-/** 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;
-export {};
+export interface SessionEndHandoffRequest {
+    readonly tenantId: string;
+    readonly sessionId: string;
+    readonly evidence: HandoffEvidence | null;
+    readonly derived?: Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'> | null;
+    readonly key?: ContinuityKey;
+    readonly inPlace?: boolean;
+}
+/** 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, request: SessionEndHandoffRequest): SessionHandoff | null;
 //# sourceMappingURL=handoffs.d.ts.map

package/dist/store/handoffs.js

@@ -7,6 +7,14 @@ import { continuityStamp, continuityWhere, loadActiveTaskSnapshot } from './sess
 /** 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';
+function insertHandoffRow(db, tenantId, handoff, stamp, now) {
+    return 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);
+}
 /** Save a session handoff record; returns the persisted handoff. */
 export function saveSessionHandoff(hippoRoot, tenantId, handoff, key) {
     assertTenantId('saveSessionHandoff', tenantId);
@@ -16,9 +24,7 @@ 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(`\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 result = insertHandoffRow(db, tenantId, handoff, stamp, now);
         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);
@@ -48,9 +54,11 @@ 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.
-        // 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)`);
+        // 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 ?? []));
         conditions.push(`(outcome IS NULL OR outcome IN ('partial','failure'))`);
     }
@@ -107,7 +115,8 @@ export function loadHandoffById(hippoRoot, tenantId, id) {
 export function stampHandoffOutcome(hippoRoot, tenantId, sessionId, outcome) {
     assertTenantId('stampHandoffOutcome', tenantId);
     return onHandle(hippoRoot, (db) => {
-        const result = db.prepare(`
+        const result = db
+            .prepare(`
       UPDATE session_handoffs SET outcome = ?
       WHERE tenant_id = ? AND session_id = ? AND outcome IS NULL
         AND id = (
@@ -115,21 +124,27 @@ export function stampHandoffOutcome(hippoRoot, tenantId, sessionId, outcome) {
           WHERE tenant_id = ? AND session_id = ?
           ORDER BY created_at DESC, id DESC LIMIT 1
         )
-    `).run(outcome, tenantId, sessionId, tenantId, sessionId);
+    `)
+            .run(outcome, tenantId, sessionId, tenantId, sessionId);
         return Number(result.changes ?? 0);
     }, 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 newest = `SELECT id FROM session_handoffs WHERE ${conditions.join(' AND ')} ORDER BY created_at DESC, id ` +
+        `DESC LIMIT 1`;
     return onHandle(hippoRoot, (db) => {
-        const result = db.prepare(`
-      UPDATE session_handoffs SET repo_root = ?, task_id = ?, summary = ?, next_action = ?, artifacts_json = ?, scope = ?, created_at = ?,
+        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 = ?
-      WHERE id = (${newest}) AND json_valid(evidence_json) AND json_extract(evidence_json, '$.derivedFrom') = 'transcript'
-    `).run(handoff.repoRoot ?? null, handoff.taskId ?? null, handoff.summary, handoff.nextAction ?? null, JSON.stringify(handoff.artifacts ?? []), handoff.scope ?? null, new Date().toISOString(), JSON.stringify(handoff.constraints ?? []), handoff.evidence ? JSON.stringify(handoff.evidence) : null, handoff.outcome ?? null, handoff.targetRuntime ?? null, handoff.cardId ?? null, ...params);
+      WHERE id = (${newest}) AND json_valid(evidence_json) AND json_extract(evidence_json, '$.derivedFrom') =
+      'transcript'
+    `)
+            .run(handoff.repoRoot ?? null, handoff.taskId ?? null, handoff.summary, handoff.nextAction ?? null, JSON.stringify(handoff.artifacts ?? []), handoff.scope ?? null, new Date().toISOString(), JSON.stringify(handoff.constraints ?? []), handoff.evidence ? JSON.stringify(handoff.evidence) : null, handoff.outcome ?? null, handoff.targetRuntime ?? null, handoff.cardId ?? null, ...params);
         if (Number(result.changes ?? 0) === 0)
             return null;
         // SAFETY: row's shape matches HANDOFF_COLUMNS.
@@ -142,8 +157,12 @@ function transcriptHandoffSource(existing, derived, evidence) {
     if (!derived || (existing && existing.evidence?.derivedFrom !== 'transcript'))
         return null;
     // A retried session end reads the same transcript, so it must not add a second revision.
-    if (existing && existing.taskId === derived.task && existing.summary === derived.summary && existing.nextAction === derived.next_step)
+    if (existing &&
+        existing.taskId === derived.task &&
+        existing.summary === derived.summary &&
+        existing.nextAction === derived.next_step) {
         return null;
+    }
     return { snapshot: { ...derived, scope: null }, evidence: { ...evidence, derivedFrom: 'transcript' } };
 }
 function buildSessionEndHandoff(sessionId, snapshot, existing, handoffEvidence, outcome) {
@@ -167,9 +186,11 @@ function buildSessionEndHandoff(sessionId, snapshot, existing, handoffEvidence,
         cardId: carryForward ? existing.cardId : undefined,
     };
 }
-/** 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 = {}) {
+/** 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, request) {
+    const { tenantId, sessionId, evidence, derived = null, key, inPlace } = request;
     assertTenantId('writeSessionEndHandoff', tenantId);
     if (key)
         continuityStamp(key); // a partial key is a caller bug, so fail loud rather than write nothing
@@ -178,8 +199,9 @@ export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence,
     let snapshot;
     let handoffEvidence = evidence;
     let fromTranscript = false;
-    // After every reply the transcript is newer than the last compaction's snapshot, which the open chat keeps for the next one.
-    const snapshotGivesWay = options.inPlace === true && derived !== null && active?.source === 'pre-compact';
+    // After every reply the transcript is newer than the last compaction's snapshot, which the open chat keeps for the
+    // next one.
+    const snapshotGivesWay = inPlace === true && derived !== null && active?.source === 'pre-compact';
     if (active && active.session_id === sessionId && !snapshotGivesWay) {
         // Strict '>': a same-millisecond tie must not swallow the session's only write (test 6e).
         if (existing && existing.updatedAt > active.updated_at)
@@ -197,7 +219,7 @@ export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence,
     const outcome = sessionOutcome(hippoRoot, tenantId, sessionId);
     const handoff = buildSessionEndHandoff(sessionId, snapshot, existing, handoffEvidence, outcome);
     // A miss means a handoff landed since the read, and a new transcript row would hide it.
-    if (fromTranscript && options.inPlace && existing)
+    if (fromTranscript && inPlace && existing)
         return replaceTranscriptHandoff(hippoRoot, tenantId, handoff, key);
     return saveSessionHandoff(hippoRoot, tenantId, handoff, key);
 }

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

@@ -4,8 +4,8 @@ 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 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`. */
+/** 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. */
 export declare function rebuildIndex(hippoRoot: string): HippoIndex;

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

@@ -1,9 +1,9 @@
-import { withWriteScope, setMeta, isSqliteBusy, pruneConsolidationRuns, getMeta } from '../db/index.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 { buildIndexFromDb, readLastRecall, syncMirrorFiles, writeIndexMirror, writeStatsMirror, buildStatsFromDb, } from './mirrors.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`. */
@@ -18,8 +18,8 @@ export function loadLastRecall(hippoRoot) {
         return readLastRecall(db);
     }, openStore);
 }
-/** 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`. */
+/** 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) {
     onHandle(hippoRoot, (db) => {
         withWriteScope(db, 'save_index', () => {
@@ -77,7 +77,8 @@ export function updateStats(hippoRoot, delta) {
 }
 /** 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 named counter: a read-modify-write loses concurrent increments and stamps 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],

package/dist/store/index.d.ts

@@ -1,4 +1,6 @@
-export type { AmbientCandidateRequest, ContextReads, EntryRemoval, EntryTarget, EntryWrite, EntryWrites, HippoStore, KeyAudit, KeyListQuery, KeyMint, KeyRevoke, KeyWrites, OutcomeWrite, RawArchive, RecallSearchArgs, RecallWrites, SelfKeyMint, StoreGroup, StoreGroups, SupersedeWrite, VectorBackfillQuery, VectorReads, VectorRowWrite, VectorWrite, VectorWriteResult, VectorWrites, } from './port.js';
+export type { AmbientCandidateRequest, ContextReads, EntryRemoval, EntryTarget, EntryWrite, EntryWrites, HippoStore, KeyAudit, KeyListQuery, KeyMint, KeyRevoke, KeyGrants, KeyWrites, LastRecall, LastRecallWrites, OutcomeWrite, RawArchive, RecallSearchArgs, RecallWrites, SelfKeyMint, StoreGroup, StoreGroups, SupersedeWrite, VectorBackfillQuery, VectorReads, VectorRowWrite, VectorWrite, VectorWriteResult, VectorWrites, } from './port.js';
+export type { CardCreate, Cards, Conflicts, Dormant, DormantRestoreRequest, Goals, Reports, Sessions, WorkingMemoryFilter, WorkingMemoryPush, } from './port-groups.js';
 export { hasGroup, requireGroup } from './port.js';
-export * from './sqlite/store.js';
+export { narrowStore, type StoreWith } from './narrow.js';
+export { sqliteStore } from './sqlite/store.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/store/index.js

@@ -1,3 +1,4 @@
 export { hasGroup, requireGroup } from './port.js';
-export * from './sqlite/store.js';
+export { narrowStore } from './narrow.js';
+export { sqliteStore } from './sqlite/store.js';
 //# sourceMappingURL=index.js.map

package/dist/store/key-audit.d.ts

@@ -1,6 +1,7 @@
 import { type DatabaseSyncLike } from '../db/index.js';
 import type { KeyRevoke } from './port.js';
-/** The revoke and its audit row commit together, so a failed audit write leaves the key live and the caller sees the error. */
+/** The revoke and its audit row commit together, so a failed audit write leaves the key live and the caller sees the
+ * error. */
 export declare function revokeKeyAt(db: DatabaseSyncLike, revoke: KeyRevoke): string;
 export declare function auditHighIdAt(db: DatabaseSyncLike): number;
 //# sourceMappingURL=key-audit.d.ts.map

package/dist/store/key-audit.js

@@ -4,7 +4,8 @@ import { appendAuditEvent } from './audit.js';
 import { revokeApiKey } from './auth.js';
 import { withWriteScope } from '../db/index.js';
 import { selectApiKeyOwner } from './tenant-lookup.js';
-/** The revoke and its audit row commit together, so a failed audit write leaves the key live and the caller sees the error. */
+/** The revoke and its audit row commit together, so a failed audit write leaves the key live and the caller sees the
+ * error. */
 export function revokeKeyAt(db, revoke) {
     return withWriteScope(db, 'revoke_api_key', () => {
         const row = selectApiKeyOwner(db, revoke.keyId);

package/dist/store/key-writes.d.ts

@@ -11,6 +11,7 @@ export interface ScopeGrantChange {
     readonly op: 'auth_grant' | 'auth_ungrant';
     readonly actor: string;
 }
-/** The key is checked under the write lock, and the change and its audit row commit together, so a failed audit write leaves the grants as they were. */
+/** The key is checked under the write lock, and the change and its audit row commit together, so a failed audit write
+ * leaves the grants as they were. */
 export declare function changeScopeGrantAt(db: DatabaseSyncLike, { tenantId, keyId, scope, op, actor }: ScopeGrantChange): void;
 //# sourceMappingURL=key-writes.d.ts.map

package/dist/store/key-writes.js

@@ -24,13 +24,20 @@ export function createSelfKeyAt(db, mint) {
         insertApiKey(db, key);
         for (const keyId of replaced) {
             revokeApiKey(db, keyId, key.createdAt);
-            appendAuditEvent(db, { tenantId: key.tenantId, actor, op: 'auth_revoke', targetId: keyId, metadata: { replacedBy: key.keyId } });
+            appendAuditEvent(db, {
+                tenantId: key.tenantId,
+                actor,
+                op: 'auth_revoke',
+                targetId: keyId,
+                metadata: { replacedBy: key.keyId },
+            });
         }
         appendAuditEvent(db, createAuditOf(mint));
         return replaced;
     });
 }
-/** The key is checked under the write lock, and the change and its audit row commit together, so a failed audit write leaves the grants as they were. */
+/** The key is checked under the write lock, and the change and its audit row commit together, so a failed audit write
+ * leaves the grants as they were. */
 export function changeScopeGrantAt(db, { tenantId, keyId, scope, op, actor }) {
     withWriteScope(db, 'change_scope_grant', () => {
         const row = selectApiKeyOwner(db, keyId);

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

@@ -9,13 +9,16 @@ export type DeliveryWrite = (input: DeliveryEventInput) => number | null;
 /** The token rows of one turn and the delivery event that follows them. */
 export interface LedgerTurn {
     readonly uses: readonly TokenUse[];
-    /** Makes each row its own attempt: a failed one is reported here and the rest still run. Without it the first failure throws. */
+    /** Makes each row its own attempt: a failed one is reported here and the rest still run. Without it the first failure
+     * throws. */
     readonly onRowError?: <E>(error: E) => void;
     /** Runs after the rows with a writer on their connection, so the delivery event costs no second open. */
     readonly delivery?: (write: DeliveryWrite) => void;
 }
 /** Books a turn's token rows, then its delivery event, on one connection. */
 export declare function recordLedgerTurn(hippoRoot: string, turn: LedgerTurn): void;
+/** Books one token row in the store at `hippoRoot`. */
+export declare function recordTokensAt(hippoRoot: string, use: TokenUse): 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. */

package/dist/store/ledger-turn.js

@@ -1,4 +1,5 @@
-// One hook or context turn's token-ledger work by store root: each call opens hippo.db, runs on one connection and closes it.
+// 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';
@@ -51,6 +52,10 @@ export function recordLedgerTurn(hippoRoot, turn) {
         turn.delivery?.((input) => writeDeliveryEventOnHandle(db, input));
     });
 }
+/** Books one token row in the store at `hippoRoot`. */
+export function recordTokensAt(hippoRoot, use) {
+    onHandle(hippoRoot, (db) => recordTokenUse(db, use));
+}
 /** What the session last sent on `surface`, or null, as lastSentState reads it. */
 export function lastSentOnSurface(hippoRoot, tenantId, sessionId, surface) {
     return onHandle(hippoRoot, (db) => lastSentState(db, tenantId, sessionId, surface));
@@ -60,6 +65,6 @@ 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));
+        : (readPilotArm(db, sessionId, ownTenantOnly ? tenantId : undefined) ?? hashArm(sessionId, rateBp)));
 }
 //# sourceMappingURL=ledger-turn.js.map

package/dist/store/mirrors.d.ts

@@ -2,15 +2,17 @@ import { Layer, type MemoryEntry } from '../core/memory.js';
 import { openHippoDb } from '../db/index.js';
 import { type TaskSnapshot, type SessionEvent, type HippoIndex, type LegacyStats } from './rows.js';
 export declare function layerDir(root: string, layer: Layer): string;
-/** Makes the mirror folders on a store's first open in this process; a writer makes its own folder if one goes missing later. */
+/** Makes the mirror folders on a store's first open in this process; a writer makes its own folder if one goes missing
+ * later. */
 export declare function ensureMirrorDirectories(hippoRoot: string): void;
 export declare function writeActiveTaskMirror(hippoRoot: string, tenantId: string, snapshot: TaskSnapshot): void;
 export declare function removeActiveTaskMirror(hippoRoot: string, tenantId: string): void;
 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. */
+/** 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. */
@@ -21,8 +23,13 @@ export declare function buildStatsFromDb(db: ReturnType<typeof openHippoDb>): Le
 /** Write the `index.json` mirror file for an already-derived index. Exported for
  *  `rebuildIndex` (the only index.json writer) and the longmemeval benchmark. */
 export declare function writeIndexMirror(hippoRoot: string, index: HippoIndex): void;
+/** Mirror `stats` to stats.json at once, or hold it and write the latest within a second of the last write; the
+ * database counters are always current. */
 export declare function writeStatsMirror(hippoRoot: string, stats: LegacyStats): void;
-/** Mirrors are derived from SQLite and written after COMMIT, so a failed write warns instead of failing a committed change. */
+/** Write any held stats.json now, for one root or all; store close and process exit call it. */
+export declare function flushStatsMirrors(hippoRoot?: string): void;
+/** Mirrors are derived from SQLite and written after COMMIT, so a failed write warns instead of failing a committed
+ * change. */
 export declare function mirrorBestEffort(what: string, write: () => void): void;
 export declare function syncMirrorFiles(hippoRoot: string, db: ReturnType<typeof openHippoDb>): void;
 /** syncMirrorFiles for a pass that changed only `changed`: the other rows' markdown is already current. */

package/dist/store/mirrors.js

@@ -8,13 +8,20 @@ import { oncePerStore } from '../db/connect.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 '../core/markdown.js';
+import { writeFileAtomic } from '../util/atomic-write.js';
 const SCORE_DECIMALS = 3;
+// Mirrors are derived and rebuildable from the store, so they skip the fsyncs (the cost on Windows) and keep the
+// temp-and-rename atomicity.
+function writeMirror(file, text) {
+    writeFileAtomic(file, text, { durable: false });
+}
 export function layerDir(root, layer) {
     return path.join(root, layer);
 }
 // Owner-only wherever a mirror folder is made, at open or by a writer that finds it gone.
 const MIRROR_FOLDER = { recursive: true, mode: 0o700 };
-/** Makes the mirror folders on a store's first open in this process; a writer makes its own folder if one goes missing later. */
+/** Makes the mirror folders on a store's first open in this process; a writer makes its own folder if one goes missing
+ * later. */
 export function ensureMirrorDirectories(hippoRoot) {
     oncePerStore(hippoRoot, 'mirror-folders', () => {
         for (const sub of ['buffer', 'episodic', 'semantic', 'conflicts']) {
@@ -61,7 +68,7 @@ export function writeActiveTaskMirror(hippoRoot, tenantId, snapshot) {
         body.push(`## Session`, snapshot.session_id, '');
     }
     fs.mkdirSync(path.dirname(filePath), MIRROR_FOLDER);
-    fs.writeFileSync(filePath, `${fm}\n\n${body.join('\n')}`, 'utf8');
+    writeMirror(filePath, `${fm}\n\n${body.join('\n')}`);
 }
 export function removeActiveTaskMirror(hippoRoot, tenantId) {
     const filePath = activeTaskMirrorPath(hippoRoot, tenantId);
@@ -99,7 +106,7 @@ export function writeRecentSessionMirror(hippoRoot, tenantId, events) {
     }
     lines.push('');
     fs.mkdirSync(path.dirname(filePath), MIRROR_FOLDER);
-    fs.writeFileSync(filePath, `${fm}\n\n${lines.join('\n')}`, 'utf8');
+    writeMirror(filePath, `${fm}\n\n${lines.join('\n')}`);
 }
 function writeConflictMirrors(hippoRoot, conflicts) {
     const conflictDir = path.join(hippoRoot, 'conflicts');
@@ -128,7 +135,7 @@ function writeConflictMirrors(hippoRoot, conflicts) {
             `- Status: ${conflict.status}`,
             '',
         ].join('\n');
-        fs.writeFileSync(path.join(conflictDir, filename), `${fm}\n\n${body}`, 'utf8');
+        writeMirror(path.join(conflictDir, filename), `${fm}\n\n${body}`);
     }
     for (const existing of fs.readdirSync(conflictDir)) {
         if (existing === '.gitkeep')
@@ -142,7 +149,7 @@ export function writeMarkdownMirror(hippoRoot, entry) {
     removeEntryMirrors(hippoRoot, entry.id);
     const dir = layerDir(hippoRoot, entry.layer);
     fs.mkdirSync(dir, MIRROR_FOLDER);
-    fs.writeFileSync(path.join(dir, `${entry.id}.md`), serializeEntry(entry), 'utf8');
+    writeMirror(path.join(dir, `${entry.id}.md`), serializeEntry(entry));
 }
 // Every layer, Trace included: `writeMarkdownMirror` writes any layer, and a stale trace mirror
 // is the resurrection channel bootstrapLegacyStore/rebuildIndex guard against.
@@ -154,21 +161,24 @@ 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. */
+/** 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);
         return true;
     }
-    catch {
+    catch (firstErr) {
+        log.debug(`${logPrefix}: mirror cleanup for ${id} failed once, retrying: ${errorMessage(firstErr)}`, errorFields(firstErr));
         try {
             removeEntryMirrors(hippoRoot, id);
             return true;
@@ -192,7 +202,10 @@ export function purgeMirrorBestEffort(hippoRoot, id, isRaw, logPrefix) {
  *  (the only index.json writer) and the longmemeval benchmark. */
 export function buildIndexFromDb(db) {
     // SAFETY: rows' shape matches the seven columns named in the SELECT below.
-    const rows = db.prepare(`SELECT id, created, last_retrieved, strength, layer, tags_json, pinned FROM memories ORDER BY created ASC, id ASC`).all();
+    const rows = db
+        .prepare(`SELECT id, created, last_retrieved, strength, layer, tags_json, pinned FROM memories ORDER BY created ASC, id ` +
+        `ASC`)
+        .all();
     const entries = {};
     for (const row of rows) {
         // SAFETY: layer is only ever written from the Layer enum by this
@@ -213,12 +226,18 @@ 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 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();
+    // 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') ?? '[]', { table: 'meta', id: 'last_retrieval_ids', column: 'value' }),
+        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') ?? ''),
     };
 }
@@ -246,9 +265,62 @@ export function buildStatsFromDb(db) {
 export function writeIndexMirror(hippoRoot, index) {
     mirrorBestEffort('index.json', () => overwriteInPlace(path.join(hippoRoot, 'index.json'), JSON.stringify(index, null, 2)));
 }
-export function writeStatsMirror(hippoRoot, stats) {
+const STATS_MIRROR_INTERVAL_MS = 1000;
+const statsMirrors = new Map();
+let statsExitHookInstalled = false;
+function putStatsMirror(hippoRoot, stats) {
+    // A root removed before its deferred write has nothing left to mirror.
+    if (!fs.existsSync(hippoRoot))
+        return;
     mirrorBestEffort('stats.json', () => overwriteInPlace(path.join(hippoRoot, 'stats.json'), JSON.stringify(stats, null, 2)));
 }
+/** Mirror `stats` to stats.json at once, or hold it and write the latest within a second of the last write; the
+ * database counters are always current. */
+export function writeStatsMirror(hippoRoot, stats) {
+    const key = path.resolve(hippoRoot);
+    dropIdleStatsMirrors();
+    const state = statsMirrors.get(key) ?? { lastWrite: 0 };
+    statsMirrors.set(key, state);
+    const wait = state.lastWrite + STATS_MIRROR_INTERVAL_MS - Date.now();
+    if (wait <= 0) {
+        state.lastWrite = Date.now();
+        putStatsMirror(hippoRoot, stats);
+        return;
+    }
+    state.pending = stats;
+    if (state.timer !== undefined)
+        return;
+    if (!statsExitHookInstalled) {
+        process.on('exit', () => flushStatsMirrors());
+        statsExitHookInstalled = true;
+    }
+    state.timer = setTimeout(() => flushStatsMirrors(key), wait);
+    state.timer.unref();
+}
+// A root idle for a full interval needs no throttle state, so the map holds only recently written roots.
+function dropIdleStatsMirrors() {
+    const now = Date.now();
+    for (const [root, state] of statsMirrors) {
+        if (state.timer === undefined && state.pending === undefined && now - state.lastWrite >= STATS_MIRROR_INTERVAL_MS) {
+            statsMirrors.delete(root);
+        }
+    }
+}
+/** Write any held stats.json now, for one root or all; store close and process exit call it. */
+export function flushStatsMirrors(hippoRoot) {
+    const key = hippoRoot === undefined ? undefined : path.resolve(hippoRoot);
+    for (const [root, state] of statsMirrors) {
+        if (key !== undefined && root !== key)
+            continue;
+        if (state.timer !== undefined)
+            clearTimeout(state.timer);
+        state.timer = undefined;
+        const stats = state.pending;
+        statsMirrors.delete(root);
+        if (stats !== undefined)
+            putStatsMirror(root, stats);
+    }
+}
 // A truncate waits for the file's last write to reach the disk, so a file rewritten on every recall keeps its blocks.
 function overwriteInPlace(file, text) {
     const bytes = Buffer.from(text, 'utf8');
@@ -261,7 +333,8 @@ function overwriteInPlace(file, text) {
         fs.closeSync(fd);
     }
 }
-/** Mirrors are derived from SQLite and written after COMMIT, so a failed write warns instead of failing a committed change. */
+/** Mirrors are derived from SQLite and written after COMMIT, so a failed write warns instead of failing a committed
+ * change. */
 export function mirrorBestEffort(what, write) {
     try {
         write();
@@ -273,7 +346,9 @@ export function mirrorBestEffort(what, write) {
 export function syncMirrorFiles(hippoRoot, db) {
     // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
     // MemoryRow's field set.
-    const entries = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories ORDER BY created ASC, id ASC`).all();
+    const entries = db
+        .prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories ORDER BY created ASC, id ASC`)
+        .all();
     syncChangedMirrors(hippoRoot, db, entries.map(rowToEntry));
 }
 /** syncMirrorFiles for a pass that changed only `changed`: the other rows' markdown is already current. */
@@ -284,12 +359,14 @@ export function syncChangedMirrors(hippoRoot, db, changed) {
     });
     // SAFETY: conflicts' shape matches the eight columns named in the SELECT
     // above.
-    const conflicts = db.prepare(`
+    const conflicts = db
+        .prepare(`
     SELECT id, memory_a_id, memory_b_id, reason, score, status, detected_at, updated_at
     FROM memory_conflicts
     WHERE status = 'open'
     ORDER BY updated_at DESC, id DESC
-  `).all();
+  `)
+        .all();
     mirrorBestEffort('conflict mirrors', () => writeConflictMirrors(hippoRoot, conflicts.map(rowToMemoryConflict)));
     writeStatsMirror(hippoRoot, buildStatsFromDb(db));
 }

package/dist/store/narrow.d.ts

@@ -0,0 +1,6 @@
+import { type HippoStore, type StoreGroup, type StoreGroups } from './port.js';
+/** A store a gate proved holds `G`, so a handler reads `store.<group>` with no run-time check. */
+export type StoreWith<G extends StoreGroup> = HippoStore & Pick<StoreGroups, Exclude<G, 'base'>>;
+/** The one run-time check behind a `StoreWith`: throws StoreNotPortedError for the first missing group. */
+export declare function narrowStore<G extends StoreGroup>(store: HippoStore, ...groups: readonly [G, ...G[]]): StoreWith<G>;
+//# sourceMappingURL=narrow.d.ts.map

package/dist/store/narrow.js

@@ -0,0 +1,11 @@
+import { StoreNotPortedError } from '../util/sqlite-blocked.js';
+import { hasGroup } from './port.js';
+/** The one run-time check behind a `StoreWith`: throws StoreNotPortedError for the first missing group. */
+export function narrowStore(store, ...groups) {
+    for (const group of groups)
+        if (!hasGroup(store, group))
+            throw new StoreNotPortedError(store.kind, group);
+    // SAFETY: the loop above proved every group.
+    return store;
+}
+//# sourceMappingURL=narrow.js.map