hippo-memory 2.0.0 → 2.1.0

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

@@ -10,7 +10,8 @@ import { parseJsonArray, INDEX_VERSION, parseLastTraceId, MEMORY_SELECT_COLUMNS,
 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.
+// 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 });
 }
@@ -19,7 +20,8 @@ export function layerDir(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']) {
@@ -159,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;
@@ -197,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
@@ -218,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') ?? ''),
     };
 }
@@ -251,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');
@@ -266,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();
@@ -278,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. */
@@ -289,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

package/dist/store/open.d.ts

@@ -5,6 +5,10 @@ export declare function initStore(hippoRoot: string): void;
 export declare function openStore(hippoRoot: string, opts?: {
     busyWaitMs?: number;
 }): DatabaseSyncLike;
+/** A connection with no mirror or legacy setup, for a caller that already ran `initStore`. */
+export declare function openBareHandle(hippoRoot: string, opts?: {
+    busyWaitMs?: number;
+}): DatabaseSyncLike;
 /** One call on a handle of its own, closed after (a request scope's handle stays open);
  *  pass openStore where the call also sets up mirror folders and legacy rows. */
 export declare function onHandle<T>(hippoRoot: string, fn: (db: DatabaseSyncLike) => T, open?: (hippoRoot: string) => DatabaseSyncLike): T;
@@ -12,7 +16,5 @@ export declare function onHandle<T>(hippoRoot: string, fn: (db: DatabaseSyncLike
 export declare const HALF_LIFE_BASE_META_KEY = "default_half_life_base";
 /** `meta` key set once no memory of a decision, incident or other object sits on the old flat 90 days. */
 export declare const TYPED_HALF_LIFE_META_KEY = "typed_half_life_on_default";
-/** The flat half-life the decision, incident and other object writers gave their memories before they took the default. */
-export declare const LEGACY_TYPED_HALF_LIFE = 90;
 export declare function loadLegacyEntriesFromMarkdown(hippoRoot: string): MemoryEntry[];
 //# sourceMappingURL=open.d.ts.map

package/dist/store/open.js

@@ -18,7 +18,8 @@ export function initStore(hippoRoot) {
 export function openStore(hippoRoot, opts) {
     // Open first: a folder marked for another store must refuse before any mirror folder appears.
     const { db, facts } = openHippoDbWithFacts(hippoRoot, opts);
-    // A store worker's reader: its writer ran the steps below before this thread was sent a job, and this connection cannot write them.
+    // A store worker's reader: its writer ran the steps below before this thread was sent a job, and this connection
+    // cannot write them.
     if (currentRequestStores()?.setupDoneFor === hippoRoot)
         return db;
     try {
@@ -44,6 +45,10 @@ export function openStore(hippoRoot, opts) {
         throw error;
     }
 }
+/** A connection with no mirror or legacy setup, for a caller that already ran `initStore`. */
+export function openBareHandle(hippoRoot, opts) {
+    return openHippoDb(hippoRoot, opts);
+}
 /** One call on a handle of its own, closed after (a request scope's handle stays open);
  *  pass openStore where the call also sets up mirror folders and legacy rows. */
 export function onHandle(hippoRoot, fn, open = openHippoDb) {
@@ -59,10 +64,8 @@ export function onHandle(hippoRoot, fn, open = openHippoDb) {
 export const HALF_LIFE_BASE_META_KEY = 'default_half_life_base';
 /** `meta` key set once no memory of a decision, incident or other object sits on the old flat 90 days. */
 export const TYPED_HALF_LIFE_META_KEY = 'typed_half_life_on_default';
-/** The flat half-life the decision, incident and other object writers gave their memories before they took the default. */
-export const LEGACY_TYPED_HALF_LIFE = 90;
-/** A store with no memories starts on the current default half-life base so `hippo sleep` never migrates it; one that holds memories but no recorded base
- * predates the record and keeps the legacy 7-day base until sleep migrates it. */
+/** A store with no memories starts on the current default half-life base so `hippo sleep` never migrates it; one that
+ * holds memories but no recorded base predates the record and keeps the legacy 7-day base until sleep migrates it. */
 function recordHalfLifeBaseForNewStore(db) {
     if (getMeta(db, HALF_LIFE_BASE_META_KEY, '') !== '')
         return;
@@ -104,7 +107,12 @@ function importLegacyEntries(db, hippoRoot, legacyEntries) {
         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;
@@ -151,7 +159,7 @@ export function loadLegacyEntriesFromMarkdown(hippoRoot) {
                     entries.push(entry);
             }
             catch (err) {
-                log.warn(`store: skipped unreadable legacy file ${file}: ${errorMessage(err)}`);
+                log.warn(`store: skipped unreadable legacy file ${file}: ${errorMessage(err)}`, errorFields(err));
             }
         }
     }
@@ -163,7 +171,7 @@ function readLegacyJsonObject(file) {
         parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
     }
     catch (err) {
-        log.warn(`store: unreadable ${path.basename(file)} read as empty: ${errorMessage(err)}`);
+        log.warn(`store: unreadable ${path.basename(file)} read as empty: ${errorMessage(err)}`, errorFields(err));
         return null;
     }
     if (!isJsonObject(parsed)) {
@@ -177,7 +185,8 @@ function loadLegacyIndexFile(hippoRoot) {
     const empty = { version: 1, entries: {}, last_retrieval_ids: [], last_trace_id: null };
     if (!fs.existsSync(indexPath))
         return empty;
-    // SAFETY: index.json is written by writeIndexMirror as a HippoIndex; readers default every field, so only the object shape is checked.
+    // SAFETY: index.json is written by writeIndexMirror as a HippoIndex; readers default every field, so only the object
+    // shape is checked.
     return readLegacyJsonObject(indexPath) ?? empty;
 }
 function loadLegacyStatsFile(hippoRoot) {

package/dist/store/pilot-arm.d.ts

@@ -2,7 +2,8 @@ import { type DatabaseSyncLike } from '../db/index.js';
 export type PilotArm = 'hippo' | 'holdout';
 /** Deterministic split: the same session and rate always land in the same arm. */
 export declare function hashArm(sessionId: string, rateBp: number): PilotArm;
-/** The session's first stored arm, or null; never writes. Without `tenantId` any tenant's row counts, since on one machine a session has one arm. */
+/** The session's first stored arm, or null; never writes. Without `tenantId` any tenant's row counts, since on one
+ * machine a session has one arm. */
 export declare function readPilotArm(db: DatabaseSyncLike, sessionId: string, tenantId?: string): PilotArm | null;
 /** The stored arm, else the hash arm written once; on any error the hash arm comes back unrecorded. */
 export declare function ensurePilotArm(db: DatabaseSyncLike, tenantId: string, sessionId: string, rateBp: number, opts?: {

package/dist/store/pilot-arm.js

@@ -1,8 +1,9 @@
 // Pilot arm: one token_ledger row per session names its arm, `hippo` or `holdout`, so a pilot can compare them.
-// `items` holds the holdout rate in basis points; readers outside this repo depend on these rows, so their shape is fixed.
+// `items` holds the holdout rate in basis points; readers outside this repo depend on these rows, so their shape is
+// fixed.
 import { createHash } from 'node:crypto';
 import { HOOK_DB_WAIT_MS, scopedBusyWait, withWriteScope } from '../db/index.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorMessage, log, errorFields } from '../util/log.js';
 import { firstPilotArmHash } from './token-ledger-rows.js';
 import { recordTokenUse } from './token-ledger.js';
 /** Deterministic split: the same session and rate always land in the same arm. */
@@ -10,13 +11,15 @@ export function hashArm(sessionId, rateBp) {
     const bucket = parseInt(createHash('sha256').update(sessionId).digest('hex').slice(0, 8), 16) % 10000;
     return bucket < rateBp ? 'holdout' : 'hippo';
 }
-/** The session's first stored arm, or null; never writes. Without `tenantId` any tenant's row counts, since on one machine a session has one arm. */
+/** The session's first stored arm, or null; never writes. Without `tenantId` any tenant's row counts, since on one
+ * machine a session has one arm. */
 export function readPilotArm(db, sessionId, tenantId) {
     const row = firstPilotArmHash(db, sessionId, tenantId);
     return row?.block_hash === 'holdout' || row?.block_hash === 'hippo' ? row.block_hash : null;
 }
 /** The stored arm, else the hash arm written once; on any error the hash arm comes back unrecorded. */
-// The wait is the caller's lock-wait scope (a hook's 1 s, a server request's 250 ms); it holds on a handle opened in that scope.
+// The wait is the caller's lock-wait scope (a hook's 1 s, a server request's 250 ms); it holds on a handle opened in
+// that scope.
 export function ensurePilotArm(db, tenantId, sessionId, rateBp, opts = {}) {
     const hashed = hashArm(sessionId, rateBp);
     const readTenant = opts.ownTenantOnly ? tenantId : undefined;
@@ -28,14 +31,23 @@ export function ensurePilotArm(db, tenantId, sessionId, rateBp, opts = {}) {
         return withWriteScope(db, 'pilot_arm', () => {
             const stored = readPilotArm(db, sessionId, readTenant);
             if (stored === null) {
-                recordTokenUse(db, { tenantId, sessionId, surface: 'pilot', event: 'arm', items: rateBp, tokens: 0, hash: hashed, now: opts.now });
+                recordTokenUse(db, {
+                    tenantId,
+                    sessionId,
+                    surface: 'pilot',
+                    event: 'arm',
+                    items: rateBp,
+                    tokens: 0,
+                    hash: hashed,
+                    now: opts.now,
+                });
             }
             return stored ?? hashed;
         }, { busyWaitMs: scopedBusyWait() ?? HOOK_DB_WAIT_MS });
     }
     catch (err) {
         // A prompt hook must not fail on pilot bookkeeping; concurrent callers still agree on the hash arm.
-        log.debug(`pilot arm not stored, using the hash arm: ${errorMessage(err)}`);
+        log.debug(`pilot arm not stored, using the hash arm: ${errorMessage(err)}`, errorFields(err));
         return hashed;
     }
 }

package/dist/store/planning-fallacy-evidence.d.ts

@@ -1,8 +1,8 @@
 import { type PredictionBaserate } from './predictions.js';
 export interface ClassResolution {
     classTag: string | null;
-    /** True when >=2 classes tied at the best overlap score AND best >= 1. Caller emits `recall_autodebias_hint_tiebreak` and returns a null hint
-     * (silent: an alphabetical tiebreak would show the wrong class half the time). */
+    /** True when >=2 classes tied at the best overlap score AND best >= 1. Caller emits `recall_autodebias_hint_tiebreak`
+     * and returns a null hint (silent: an alphabetical tiebreak would show the wrong class half the time). */
     tiebreak: boolean;
 }
 /** The prediction class a forward claim resolves to, and that class's closed-prediction stats when one resolved. */

package/dist/store/planning-fallacy-evidence.js

@@ -1,7 +1,8 @@
 import { onHandle } from './open.js';
 import { computePredictionBaserate } from './predictions.js';
-/** Resolve a query-token set to a unique best-matching class_tag for the tenant: lower-cased token overlap, best score >= 1 AND above the 2nd-best.
- * TENANT-GLOBAL by design, not scope-filtered (base rates need the full sample): class_tag NAMES can cross scopes; use opaque names or HIPPO_AUTODEBIAS=off. */
+/** Resolve a query-token set to a unique best-matching class_tag for the tenant: lower-cased token overlap, best score
+ * >= 1 AND above the 2nd-best. TENANT-GLOBAL by design, not scope-filtered (base rates need the full sample): class_tag
+ * NAMES can cross scopes; use opaque names or HIPPO_AUTODEBIAS=off. */
 function resolveClassFromTokens(hippoRoot, tenantId, queryTokens) {
     if (queryTokens.length === 0)
         return { classTag: null, tiebreak: false };
@@ -27,8 +28,8 @@ function resolveClassFromTokens(hippoRoot, tenantId, queryTokens) {
                 bestClass = class_tag;
             }
             else if (score === bestScore && score > 0) {
-                // Tie at current best: bump secondBest, do NOT update bestClass (an alphabetical tiebreak would pick the wrong class on ambiguous queries; stay silent
-                // on tie).
+                // Tie at current best: bump secondBest, do NOT update bestClass (an alphabetical tiebreak would pick the wrong
+                // class on ambiguous queries; stay silent on tie).
                 secondBest = score;
             }
             else if (score > secondBest) {
@@ -46,7 +47,9 @@ function resolveClassFromTokens(hippoRoot, tenantId, queryTokens) {
 export function planningFallacyEvidenceAt(hippoRoot, tenantId, classQueryTokens) {
     const resolution = resolveClassFromTokens(hippoRoot, tenantId, classQueryTokens);
     // emitAudit=false: the recall_autodebias_hint row carries n_closed and mean_ratio, so predict_baserate stays off.
-    const baserate = resolution.classTag ? computePredictionBaserate(hippoRoot, tenantId, resolution.classTag, 'recall', false) : null;
+    const baserate = resolution.classTag
+        ? computePredictionBaserate(hippoRoot, tenantId, resolution.classTag, 'recall', false)
+        : null;
     return { ...resolution, baserate };
 }
 //# sourceMappingURL=planning-fallacy-evidence.js.map

package/dist/store/port/agent-import.d.ts

@@ -0,0 +1,62 @@
+import type { MemoryEntry } from '../../core/memory.js';
+import type { AppendAuditOpts } from '../audit.js';
+import type { DormantSnapshot } from '../dormant.js';
+import type { RenameSourceOptions } from '../entry-writes.js';
+import type { GatedWriteResult } from '../gated-write.js';
+import type { ProjectTagReads } from '../project-tags.js';
+import type { SetAsideResult, SetAsideWhy } from '../set-aside.js';
+/** The calls one container's sync makes inside its transaction, bound to the target store's handle and root. */
+export interface ContainerTx {
+    liveBySourcePrefix(tenantId: string, prefix: string): MemoryEntry[];
+    dormantBySourcePrefix(tenantId: string, prefix: string): DormantSnapshot[];
+    readDormant(tenantId: string, id: string): DormantSnapshot | null;
+    deleteDormant(tenantId: string, id: string): void;
+    replaceDormant(tenantId: string, id: string, entry: MemoryEntry): void;
+    entryIdTaken(id: string): boolean;
+    /** True when `text` matches a rejected-value tombstone of the tenant. */
+    isRejected(tenantId: string, text: string): boolean;
+    renameSource(tenantId: string, id: string, from: string, to: string): number;
+    renameSourceAndOrigin(tenantId: string, id: string, move: RenameSourceOptions): number;
+    setTags(entry: MemoryEntry): void;
+    supersede(tenantId: string, id: string, newId: string): boolean;
+    markSummaryDirty(summaryId: string, tenantId: string, actor: string): void;
+    appendAudit(event: AppendAuditOpts): void;
+    gatedWrite(entry: MemoryEntry, opts: {
+        actor: string;
+        worthCheck: boolean;
+    }): GatedWriteResult;
+    setAside(tag: string, row: MemoryEntry, why: SetAsideWhy): SetAsideResult;
+    /** The entry with the target store's origin stamped when it has none. */
+    stampOrigin(entry: MemoryEntry): MemoryEntry;
+}
+/** One open target store; close releases its handle, and a stand-in's folder with it. */
+export interface ImportTarget {
+    readonly root: string;
+    /** The tenant the import writes as. */
+    readonly tenantId: string;
+    liveBySourcePrefix(prefix: string): MemoryEntry[];
+    rowsOutsideSourcePrefix(prefix: string, origins: readonly string[] | null): Array<{
+        id: string;
+        content: string;
+        source: string;
+    }>;
+    projectTagReads(): ProjectTagReads;
+    /** `work` in one write scope, or a trial scope that rolls back on `dryRun`. */
+    inContainer<T>(scope: string, dryRun: boolean, work: (tx: ContainerTx) => T): T;
+    writeMirror(entry: MemoryEntry): void;
+    removeMirror(id: string): void;
+    bumpRemembered(count: number): void;
+    close(): void;
+}
+export interface AgentImport {
+    /** Creates the store at `root` with its folders. */
+    create(root: string): void;
+    open(root: string, opts: {
+        busyWaitMs?: number;
+    }): ImportTarget;
+    /** An empty store in a scratch folder a dry run plans against. */
+    openStandIn(): ImportTarget;
+    /** True when `err` means another writer held the store past its wait. */
+    isBusy<E>(err: E): boolean;
+}
+//# sourceMappingURL=agent-import.d.ts.map

package/dist/store/port/agent-import.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent-import.js.map