hippo-memory 2.0.0 → 2.1.0

package/dist/store/auth.js

@@ -10,6 +10,16 @@ export const API_KEY_PREFIX = 'hk_';
 const ID_LEN = 24; // base32 chars after prefix
 const SECRET_LEN = 32; // base32 chars after dot
 const SCRYPT_KEYLEN = 32;
+// Node's defaults, written out so a hash states the cost it was made with.
+const SCRYPT_N = 16384;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+const SCRYPT_MAXMEM = 64 * 1024 * 1024;
+// A stored row must not be able to make verify hang or exhaust memory.
+const SCRYPT_MAX_N = 2 ** 20;
+const SCRYPT_MAX_R = 32;
+const SCRYPT_MAX_P = 16;
+const DEFAULT_SCRYPT = { N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P, maxmem: SCRYPT_MAXMEM };
 const BASE32 = 'abcdefghijklmnopqrstuvwxyz234567';
 const MINTED_KEY_PATTERN = new RegExp(`^${API_KEY_PREFIX}[a-z2-7]{${ID_LEN}}\\.[a-z2-7]{${SECRET_LEN}}$`);
 function randBase32(n) {
@@ -20,24 +30,41 @@ function randBase32(n) {
     return out;
 }
 function hashKey(plaintext) {
-    // Format: scrypt$<saltHex>$<hashHex>
+    // Format: scrypt2$<N>$<r>$<p>$<saltHex>$<hashHex>
     const salt = randomBytes(16);
-    const hash = scryptSync(plaintext, salt, SCRYPT_KEYLEN);
-    return `scrypt$${salt.toString('hex')}$${hash.toString('hex')}`;
+    const hash = scryptSync(plaintext, salt, SCRYPT_KEYLEN, DEFAULT_SCRYPT);
+    return `scrypt2$${SCRYPT_N}$${SCRYPT_R}$${SCRYPT_P}$${salt.toString('hex')}$${hash.toString('hex')}`;
 }
 const verifyStats = { storeLookups: 0, scryptRuns: 0 };
 export function apiKeyVerifyStats() {
     return { ...verifyStats };
 }
-/** Null when `stored` has another shape. */
+function validCost(n, r, p) {
+    const powerOfTwo = Number.isInteger(n) && n >= 2 && (n & (n - 1)) === 0;
+    return powerOfTwo && n <= SCRYPT_MAX_N && Number.isInteger(r) && r >= 1 && r <= SCRYPT_MAX_R
+        && Number.isInteger(p) && p >= 1 && p <= SCRYPT_MAX_P && 128 * n * r <= SCRYPT_MAXMEM;
+}
+/** Null when `stored` has another shape or asks for more work than a verify may do. */
 function storedScrypt(stored) {
     const parts = stored.split('$');
-    if (parts.length !== 3 || parts[0] !== 'scrypt')
+    let params = DEFAULT_SCRYPT;
+    if (parts.length !== 3 && parts.length !== 6)
+        return null;
+    const hashHex = parts[parts.length - 1];
+    const saltHex = parts[parts.length - 2];
+    if (parts.length === 3 && parts[0] !== 'scrypt')
         return null;
-    const expected = Buffer.from(parts[2], 'hex');
+    if (parts.length === 6) {
+        const [n, r, p] = [Number(parts[1]), Number(parts[2]), Number(parts[3])];
+        if (parts[0] !== 'scrypt2' || !validCost(n, r, p))
+            return null;
+        params = { N: n, r, p, maxmem: SCRYPT_MAXMEM };
+    }
+    const expected = Buffer.from(hashHex, 'hex');
     return {
-        salt: Buffer.from(parts[1], 'hex'),
+        salt: Buffer.from(saltHex, 'hex'),
         keylen: expected.length,
+        params,
         matches: (derived) => expected.length === derived.length && timingSafeEqual(expected, derived),
     };
 }
@@ -46,7 +73,7 @@ function verifyKey(plaintext, stored) {
     if (!parsed)
         return false;
     verifyStats.scryptRuns++;
-    return parsed.matches(scryptSync(plaintext, parsed.salt, parsed.keylen));
+    return parsed.matches(scryptSync(plaintext, parsed.salt, parsed.keylen, parsed.params));
 }
 const scryptOffLoop = promisify(scrypt);
 /** Days a key lives when its mint names no expiry, so a key nobody remembers stops working by itself. */
@@ -61,28 +88,40 @@ export function insertApiKey(db, key) {
     // so the store shuts it out before the first one exists.
     if (key.expiresAt !== null)
         raiseMinBinary(db, EXPIRING_KEYS_MIN_BINARY);
-    db.prepare(`INSERT INTO api_keys (key_id, key_hash, tenant_id, label, created_at, role, owner_subject, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(key.keyId, key.keyHash, key.tenantId, key.label, key.createdAt, key.role, key.ownerSubject, key.expiresAt);
+    db.prepare(`INSERT INTO api_keys (key_id, key_hash, tenant_id, label, created_at, role, owner_subject, expires_at) VALUES ` +
+        `(?, ?, ?, ?, ?, ?, ?, ?)`).run(key.keyId, key.keyHash, key.tenantId, key.label, key.createdAt, key.role, key.ownerSubject, key.expiresAt);
 }
 export function createApiKey(db, opts) {
     const { keyId, plaintext, keyHash } = mintApiKey();
     insertApiKey(db, {
-        keyId, keyHash, tenantId: opts.tenantId, label: opts.label ?? null, role: opts.role ?? 'member', createdAt: new Date().toISOString(),
-        ownerSubject: opts.ownerSubject ?? null, expiresAt: opts.expiresAt ?? new Date(Date.now() + DEFAULT_KEY_TTL_DAYS * DAY_MS).toISOString(),
+        keyId,
+        keyHash,
+        tenantId: opts.tenantId,
+        label: opts.label ?? null,
+        role: opts.role ?? 'member',
+        createdAt: new Date().toISOString(),
+        ownerSubject: opts.ownerSubject ?? null,
+        expiresAt: opts.expiresAt ?? new Date(Date.now() + DEFAULT_KEY_TTL_DAYS * DAY_MS).toISOString(),
     });
     return { keyId, plaintext };
 }
 /** The api_keys row for `keyId` with its scope grants; null when no row matches. */
 export function readApiKeyRecord(db, keyId) {
-    // SAFETY: row comes from the SELECT above, which projects exactly key_hash, tenant_id, revoked_at, role, expires_at, owner_subject;
-    // `.get` returns undefined when no row matches key_id.
+    // SAFETY: row comes from the SELECT above, which projects exactly key_hash, tenant_id, revoked_at, role, expires_at,
+    // owner_subject; `.get` returns undefined when no row matches key_id.
     const row = db
         .prepare(`SELECT key_hash, tenant_id, revoked_at, role, expires_at, owner_subject FROM api_keys WHERE key_id = ?`)
         .get(keyId);
     if (!row)
         return null;
     return {
-        keyHash: row.key_hash, tenantId: row.tenant_id, revokedAt: row.revoked_at, role: row.role, scopes: listScopeGrants(db, keyId),
-        expiresAt: row.expires_at, ownerSubject: row.owner_subject,
+        keyHash: row.key_hash,
+        tenantId: row.tenant_id,
+        revokedAt: row.revoked_at,
+        role: row.role,
+        scopes: listScopeGrants(db, keyId),
+        expiresAt: row.expires_at,
+        ownerSubject: row.owner_subject,
     };
 }
 /** When a key stops working, in epoch ms: Infinity for null, and already past for a missing
@@ -101,7 +140,8 @@ function mintedKeyId(plaintext) {
 }
 /** True for a record that is present, unrevoked and unexpired, before any secret check. */
 function isUsable(record, now) {
-    // Ids are 120 random bits and not secret, so padding the miss path with scrypt hid nothing and let junk tokens burn CPU.
+    // Ids are 120 random bits and not secret, so padding the miss path with scrypt hid nothing and let junk tokens burn
+    // CPU.
     if (!record)
         return false;
     return !record.revokedAt && now < keyExpiryMs(record.expiresAt);
@@ -136,7 +176,8 @@ function secretDigest(plaintext) {
  * a SHA-256 of the token, never the token, and nothing about the key's state. */
 export class VerifiedKeyCache {
     capacity;
-    // Keyed on the stored hash, so a rotated or re-minted key never meets an old entry; Map order makes the first key the least recent.
+    // Keyed on the stored hash, so a rotated or re-minted key never meets an old entry; Map order makes the first key the
+    // least recent.
     proven = new Map();
     constructor(capacity) {
         this.capacity = capacity;
@@ -166,7 +207,8 @@ export class VerifiedKeyCache {
 const verifiedKeys = new VerifiedKeyCache(VERIFIED_KEY_CACHE_CAP);
 // By stored hash and token, so a burst of requests with one unproved key derives once and is charged once.
 const checksInFlight = new Map();
-/** Whether `plaintext` is the secret `keyHash` was minted from: a proved token skips scrypt, any other derives on the thread pool. */
+/** Whether `plaintext` is the secret `keyHash` was minted from: a proved token skips scrypt, any other derives on the
+ * thread pool. */
 async function secretMatches(keyId, plaintext, keyHash, bound) {
     if (verifiedKeys.has(keyHash, plaintext))
         return true;
@@ -179,7 +221,7 @@ async function secretMatches(keyId, plaintext, keyHash, bound) {
         return running;
     const derive = () => {
         verifyStats.scryptRuns++;
-        return scryptOffLoop(plaintext, parsed.salt, parsed.keylen);
+        return scryptOffLoop(plaintext, parsed.salt, parsed.keylen, parsed.params);
     };
     const check = (bound ? bound(keyId, derive) : derive()).then((derived) => {
         const matched = parsed.matches(derived);
@@ -283,7 +325,8 @@ export function listApiKeys(hippoRoot, opts) {
 export function listLiveOwnedKeyIds(db, tenantId, ownerSubject, now) {
     // SAFETY: the SELECT names exactly these two columns.
     const rows = db
-        .prepare(`SELECT key_id, expires_at FROM api_keys WHERE tenant_id = ? AND owner_subject = ? AND revoked_at IS NULL ORDER BY id`)
+        .prepare(`SELECT key_id, expires_at FROM api_keys WHERE tenant_id = ? AND owner_subject = ? AND revoked_at IS NULL ` +
+        `ORDER BY id`)
         .all(tenantId, ownerSubject);
     // Expiry is filtered here, not in SQL, so it follows the same Date.parse rule the key check uses.
     return rows.filter((r) => now < keyExpiryMs(r.expires_at)).map((r) => r.key_id);

package/dist/store/busy.d.ts

@@ -0,0 +1,9 @@
+export declare const STORE_BUSY_MESSAGE = "store busy (another hippo process holds the write lock); retry shortly";
+/** A store behind the port throws this when its lock wait runs
+ * out, so the server answers 503 as it does for a busy hippo.db. */
+export declare class StoreBusyError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+/** A held lock in any store: SQLite's busy codes or a port's StoreBusyError. */
+export declare function isStoreBusy<E>(error: E): boolean;
+//# sourceMappingURL=busy.d.ts.map

package/dist/store/busy.js

@@ -0,0 +1,16 @@
+// The busy half of the store port, apart from port.ts so that file stays under the size gate.
+import { isSqliteBusy } from '../db/busy.js';
+export const STORE_BUSY_MESSAGE = 'store busy (another hippo process holds the write lock); retry shortly';
+/** A store behind the port throws this when its lock wait runs
+ * out, so the server answers 503 as it does for a busy hippo.db. */
+export class StoreBusyError extends Error {
+    constructor(message = STORE_BUSY_MESSAGE, options) {
+        super(message, options);
+        this.name = 'StoreBusyError';
+    }
+}
+/** A held lock in any store: SQLite's busy codes or a port's StoreBusyError. */
+export function isStoreBusy(error) {
+    return error instanceof StoreBusyError || isSqliteBusy(error);
+}
+//# sourceMappingURL=busy.js.map

package/dist/store/candidates.d.ts

@@ -1,4 +1,5 @@
 import { type MemoryEntry, type ConfidenceLevel, Layer } from '../core/memory.js';
+import { type DatabaseSyncLike } from '../db/index.js';
 import { type SqlFragment } from './rule-sql.js';
 export interface AmbientRecallRequest {
     terms: string[];
@@ -32,10 +33,12 @@ export declare function loadContextCandidates(hippoRoot: string, tenantId: strin
 export type HeldText = Pick<MemoryEntry, 'content' | 'source' | 'origin_project'>;
 /** Admits every scope, for a reader that sees the whole store, such as the CLI on its own machine. */
 export declare const EVERY_SCOPE: SqlFragment;
-/** Tenant rows holding any of `words` that `admit` passes (default: team-visible); a row equal to a text apart from spacing holds its every word.
- * With `project`, only rows carrying one of those names plus user-global rows, as loadContextCandidates' filter. No `tenantId` reads every tenant. */
+/** Tenant rows holding any of `words` that `admit` passes (default: team-visible); a row equal to a text apart from
+ * spacing holds its every word. With `project`, only rows carrying one of those names plus user-global rows, as
+ * loadContextCandidates' filter. No `tenantId` reads every tenant. */
 export declare function loadTextsHoldingWords(hippoRoot: string, tenantId: string | undefined, words: readonly string[], project?: readonly string[], admit?: SqlFragment): HeldText[];
-/** A tenant's `limit` newest rows, oldest first: the tail of loadAllEntries' order, without reading the rows before it. */
+/** A tenant's `limit` newest rows, oldest first: the tail of loadAllEntries' order, without reading the rows before
+ * it. */
 export declare function loadNewestEntries(hippoRoot: string, tenantId: string, limit: number): MemoryEntry[];
 /** computeSchemaFit against a tenant's newest SCHEMA_FIT_WINDOW_ROWS rows: tag counts come from one aggregate
  * and texts stream one column, so no row is loaded. */
@@ -47,7 +50,8 @@ export interface SourceTally {
     /** `created`, a unit separator, then `id` of the source's first row in loadAllEntries' order. */
     first: string;
 }
-/** Row count and newest `created` per source, for peer listings that need no row; all tenants when `tenantId` is absent. */
+/** Row count and newest `created` per source, for peer listings that need no row; all tenants when `tenantId` is
+ * absent. */
 export declare function tallySources(hippoRoot: string, tenantId?: string): SourceTally[];
 export declare const jsonList: (column: string) => string;
 /** Whole-tenant health numbers: every row counts, superseded and archived ones too. */
@@ -62,6 +66,8 @@ export interface StrengthTallies {
 }
 /** calculateStrength over every row of a tenant in one aggregate pass, no row loaded. */
 export declare function loadStrengthTallies(hippoRoot: string, tenantId: string, now: Date, atRiskBelow: number): StrengthTallies;
+/** loadStrengthTallies on a handle the caller holds, so it can share a snapshot with other reads. */
+export declare function strengthTalliesAt(db: DatabaseSyncLike, tenantId: string, now: Date, atRiskBelow: number): StrengthTallies;
 /** What `hippo status` prints about the whole store: every tenant and superseded rows too. */
 export interface StatusCounts {
     total: number;
@@ -77,6 +83,7 @@ export interface StatusCounts {
     /** Rows that have a stored vector. */
     embedded: number;
 }
-/** The counts `hippo status` prints, from one pass over ten narrow columns: no text is read and no row array is built. */
+/** The counts `hippo status` prints, from one pass over ten narrow columns: no text is read and no row array is
+ * built. */
 export declare function loadStatusCounts(hippoRoot: string, now: Date, atRiskBelow: number): StatusCounts;
 //# sourceMappingURL=candidates.d.ts.map

package/dist/store/candidates.js

@@ -1,4 +1,4 @@
-import { FALLBACK_HALF_LIFE_DAYS, Layer, calculateStrength, facetsOf, schemaFitFrom } from '../core/memory.js';
+import { FALLBACK_HALF_LIFE_DAYS, Layer, calculateStrength, facetsOf, schemaFitFrom, } from '../core/memory.js';
 import { strengthSql } from './rule-sql.js';
 import { withReadSnapshot } from '../db/index.js';
 import { rewardFactorSql, scopeAdmitSql } from './rule-sql.js';
@@ -24,9 +24,14 @@ function loadRecentRows(run, drifted, tenantId, options) {
     const { needed, admit, origins } = options;
     const keep = origins ? (e) => admit(e) && inOrigins(e, origins) : admit;
     const window = Math.max(needed * 4, 32);
-    const originSql = origins && (origins.userGlobal ? `(origin_project = '' OR ${originInSql(origins.names)})` : originInSql(origins.names));
-    const own = { where: originSql ? `${AMBIENT_SCOPED} AND ${originSql}` : AMBIENT_SCOPED, params: [tenantId, ...(origins?.names ?? [])] };
-    // Text order is chronological only for standard UTC ISO (memory.ts), so a drifted store is read whole and re-sorted downstream.
+    const originSql = origins &&
+        (origins.userGlobal ? `(origin_project = '' OR ${originInSql(origins.names)})` : originInSql(origins.names));
+    const own = {
+        where: originSql ? `${AMBIENT_SCOPED} AND ${originSql}` : AMBIENT_SCOPED,
+        params: [tenantId, ...(origins?.names ?? [])],
+    };
+    // Text order is chronological only for standard UTC ISO (memory.ts), so a drifted store is read whole and re-sorted
+    // downstream.
     if (drifted)
         return run(`${own.where} ${NEWEST}`, [...own.params]).filter(keep);
     let read = run(`${AMBIENT_SCOPED} ${NEWEST} LIMIT ?`, [tenantId, window]);
@@ -41,12 +46,19 @@ function loadRecentRows(run, drifted, tenantId, options) {
     }
     return [...kept, ...keptPastWindow(run, own, read, needed - kept.length, keep)];
 }
-// A window of refused rows can hide older ones, so read on in keyset pages, each four times the last, until enough are kept.
+// A window of refused rows can hide older ones, so read on in keyset pages, each four times the last, until enough are
+// kept.
 function keptPastWindow(run, own, read, wanted, keep) {
     const out = [];
     let last = read[read.length - 1];
     for (let size = read.length * 4; out.length < wanted; size *= 4) {
-        const page = run(`${own.where} AND created <= ? AND (created < ? OR id < ?) ${NEWEST} LIMIT ?`, [...own.params, last.created, last.created, last.id, size]);
+        const page = run(`${own.where} AND created <= ? AND (created < ? OR id < ?) ${NEWEST} LIMIT ?`, [
+            ...own.params,
+            last.created,
+            last.created,
+            last.id,
+            size,
+        ]);
         out.push(...page.filter(keep));
         if (page.length < size)
             break;
@@ -83,13 +95,18 @@ export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit,
             return { entries };
         const ftsQuery = pickRarestFtsQuery(db, recall.terms);
         const recallEntries = ftsQuery
-            ? loadRecallSearchEntriesFromDb(db, ftsQuery, { limit: recall.limit, tenantId, includeSuperseded: false, ownScope: recall.ownScope })
+            ? loadRecallSearchEntriesFromDb(db, ftsQuery, {
+                limit: recall.limit,
+                tenantId,
+                includeSuperseded: false,
+                ownScope: recall.ownScope,
+            })
             : [];
         return { entries, recall: recallEntries };
     }, openStore);
 }
-// calculateStrength's decay exponent with its reward factor, pins first: the strongest rows, without scoring each one in JS.
-// A function, not a constant, so the outcome-slow ablation is read per query as strengthSql reads it.
+// calculateStrength's decay exponent with its reward factor, pins first: the strongest rows, without scoring each one
+// in JS. A function, not a constant, so the outcome-slow ablation is read per query as strengthSql reads it.
 const decayRankSql = () => `pinned DESC,
   CASE WHEN half_life_days > 0 THEN (julianday(?) - julianday(last_retrieved))
     / (half_life_days * ${rewardFactorSql()}) END ASC NULLS LAST,
@@ -117,14 +134,16 @@ export function loadContextCandidates(hippoRoot, tenantId, filter) {
         // SAFETY: the count row has the one column named.
         const matched = db.prepare(`SELECT COUNT(*) AS n FROM memories WHERE ${whereSql}`).get(...params).n;
         // Under the cap every match is returned, so the per-row decay math and the sort are skipped.
-        // SHORTCUT: past the cap the rank still scans the tenant; a stored decay rank column needs a schema migration, held until one is approved.
+        // SHORTCUT: past the cap the rank still scans the tenant; a stored decay rank column needs a schema migration,
+        // held until one is approved.
         const ranked = matched > cap;
         const sql = ranked
             ? `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id IN (
         SELECT id FROM memories WHERE ${whereSql} ORDER BY ${decayRankSql()} LIMIT ?
       ) ORDER BY created ASC, id ASC`
             : `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE ${whereSql} ORDER BY created ASC, id ASC`;
-        // SAFETY: both SELECTs name exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set; the rank sort carries ids only.
+        // SAFETY: both SELECTs name exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set; the rank sort carries
+        // ids only.
         const rows = db.prepare(sql).all(...params, ...(ranked ? [filter.now.toISOString(), cap] : []));
         return rows.map(rowToEntry);
     }, openStore);
@@ -133,8 +152,9 @@ export function loadContextCandidates(hippoRoot, tenantId, filter) {
 const TEAM_VISIBLE = scopeAdmitSql('');
 /** Admits every scope, for a reader that sees the whole store, such as the CLI on its own machine. */
 export const EVERY_SCOPE = Object.freeze({ sql: '1', params: [] });
-/** Tenant rows holding any of `words` that `admit` passes (default: team-visible); a row equal to a text apart from spacing holds its every word.
- * With `project`, only rows carrying one of those names plus user-global rows, as loadContextCandidates' filter. No `tenantId` reads every tenant. */
+/** Tenant rows holding any of `words` that `admit` passes (default: team-visible); a row equal to a text apart from
+ * spacing holds its every word. With `project`, only rows carrying one of those names plus user-global rows, as
+ * loadContextCandidates' filter. No `tenantId` reads every tenant. */
 export function loadTextsHoldingWords(hippoRoot, tenantId, words, project, admit = TEAM_VISIBLE) {
     const unique = [...new Set(words)];
     const out = [];
@@ -146,15 +166,21 @@ export function loadTextsHoldingWords(hippoRoot, tenantId, words, project, admit
         for (let i = 0; i < unique.length; i += 200) {
             const chunk = unique.slice(i, i + 200);
             // SAFETY: rows' shape matches the three columns named in the SELECT below.
-            const rows = db.prepare(`SELECT content, source, origin_project FROM memories WHERE ${tenantWhere}${originWhere} AND ${admit.sql} AND (${chunk.map(() => 'instr(content, ?) ' +
-                '> 0').join(' OR ')})`).all(...tenantParams, ...(project ?? []), ...admit.params, ...chunk);
-            for (const row of rows)
+            const rows = db
+                .prepare(`SELECT content, source, origin_project FROM memories WHERE ${tenantWhere}${originWhere} AND ` +
+                `${admit.sql} AND (${chunk
+                    .map(() => 'instr(content, ?) ' + '> 0')
+                    .join(' OR ')})`)
+                .all(...tenantParams, ...(project ?? []), ...admit.params, ...chunk);
+            for (const row of rows) {
                 out.push({ content: row.content, source: row.source ?? 'cli', origin_project: row.origin_project });
+            }
         }
         return out;
     }, openStore);
 }
-/** A tenant's `limit` newest rows, oldest first: the tail of loadAllEntries' order, without reading the rows before it. */
+/** A tenant's `limit` newest rows, oldest first: the tail of loadAllEntries' order, without reading the rows before
+ * it. */
 export function loadNewestEntries(hippoRoot, tenantId, limit) {
     return onHandle(hippoRoot, (db) => {
         // SAFETY: the SELECT names exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
@@ -176,7 +202,9 @@ export function schemaFitInStore(hippoRoot, tenantId, content, tags) {
         // One read transaction, so the row count and the texts come from the same snapshot.
         return withReadSnapshot(db, () => {
             // SAFETY: rows' shape matches the two columns named in the SELECT.
-            const groups = db.prepare(`SELECT tags_json, COUNT(*) AS n FROM (${newest}) GROUP BY tags_json`).all(tenantId, SCHEMA_FIT_WINDOW_ROWS);
+            const groups = db
+                .prepare(`SELECT tags_json, COUNT(*) AS n FROM (${newest}) GROUP BY tags_json`)
+                .all(tenantId, SCHEMA_FIT_WINDOW_ROWS);
             let rows = 0;
             const tagCounts = new Map();
             for (const group of groups) {
@@ -187,51 +215,61 @@ export function schemaFitInStore(hippoRoot, tenantId, content, tags) {
             // SHORTCUT: only the newest SCHEMA_FIT_WINDOW_ROWS rows count, so older tags drop out;
             // a stored per-tenant tag and token tally is the upgrade.
             // SAFETY: the SELECT names exactly the one column read.
-            const texts = db.prepare(`SELECT content FROM (${newest})`)
+            const texts = db
+                .prepare(`SELECT content FROM (${newest})`)
                 .iterate(tenantId, SCHEMA_FIT_WINDOW_ROWS);
             return schemaFitFrom(content, tags, { rows, tagCounts, contents: contentsOf(texts) });
         });
     }, openStore);
 }
-/** Row count and newest `created` per source, for peer listings that need no row; all tenants when `tenantId` is absent. */
+/** Row count and newest `created` per source, for peer listings that need no row; all tenants when `tenantId` is
+ * absent. */
 export function tallySources(hippoRoot, tenantId) {
     return onHandle(hippoRoot, (db) => {
         const where = tenantId !== undefined ? 'WHERE tenant_id = ?' : '';
         // SAFETY: rows' shape matches the four aliased columns in the SELECT below.
-        return db.prepare(`SELECT COALESCE(source, 'cli') AS source, COUNT(*) AS count, MAX(created) AS latest, MIN(created || char(31) || id) AS first
-       FROM memories ${where} GROUP BY COALESCE(source, 'cli')`).all(...(tenantId !== undefined ? [tenantId] : []));
+        return db
+            .prepare(`SELECT COALESCE(source, 'cli') AS source, COUNT(*) AS count, MAX(created) AS latest, MIN(created || ` +
+            `char(31) || id) AS first
+       FROM memories ${where} GROUP BY COALESCE(source, 'cli')`)
+            .all(...(tenantId !== undefined ? [tenantId] : []));
     }, openStore);
 }
 // A malformed or non-array JSON list reads as empty, as parseJsonArray does, instead of failing json_each.
 export const jsonList = (column) => `(CASE WHEN json_valid(${column}) AND json_type(${column}) = 'array' THEN ${column} ELSE '[]' END)`;
 /** calculateStrength over every row of a tenant in one aggregate pass, no row loaded. */
 export function loadStrengthTallies(hippoRoot, tenantId, now, atRiskBelow) {
+    return onHandle(hippoRoot, (db) => strengthTalliesAt(db, tenantId, now, atRiskBelow), openStore);
+}
+/** loadStrengthTallies on a handle the caller holds, so it can share a snapshot with other reads. */
+export function strengthTalliesAt(db, tenantId, now, atRiskBelow) {
     // An unparseable date scores NULL in SQL and 0 in calculateStrength.
     const strength = `COALESCE(${strengthSql(now)}, 0)`;
-    return onHandle(hippoRoot, (db) => {
-        // SAFETY: one aggregate row whose columns are the aliases named below.
-        const row = db.prepare(`SELECT
+    // SAFETY: one aggregate row whose columns are the aliases named below.
+    const row = db
+        .prepare(`SELECT
       COUNT(*) AS total,
       COALESCE(SUM(pinned != 0), 0) AS pinned,
       COALESCE(SUM(EXISTS (SELECT 1 FROM json_each(${jsonList('tags_json')}) WHERE value = 'error')), 0) AS errors,
       COALESCE(SUM(${strength}), 0) AS strengthSum,
       COALESCE(SUM(COALESCE(pinned, 0) = 0 AND ${strength} < ?), 0) AS atRisk
-      FROM memories WHERE tenant_id = ?`).get(atRiskBelow, tenantId);
-        return {
-            total: Number(row.total),
-            pinned: Number(row.pinned),
-            errors: Number(row.errors),
-            strengthSum: Number(row.strengthSum),
-            atRisk: Number(row.atRisk),
-        };
-    }, openStore);
+      FROM memories WHERE tenant_id = ?`)
+        .get(atRiskBelow, tenantId);
+    return {
+        total: Number(row.total),
+        pinned: Number(row.pinned),
+        errors: Number(row.errors),
+        strengthSum: Number(row.strengthSum),
+        atRisk: Number(row.atRisk),
+    };
 }
 // What calculateStrength and facetsOf read, plus the layer: no text and no JSON column.
 const STATUS_ROW_COLUMNS = [
     'layer', 'confidence', 'pinned', 'created', 'last_retrieved', 'half_life_days', 'retrieval_count',
     'emotional_valence', 'outcome_positive', 'outcome_negative',
 ];
-// Scored in JavaScript, not with strengthSql: SQLite reads fewer date shapes than Date does, so its counts would differ.
+// Scored in JavaScript, not with strengthSql: SQLite reads fewer date shapes than Date does, so its counts would
+// differ.
 function tallyStatusRows(rows, now, atRiskBelow) {
     const byLayer = { [Layer.Buffer]: 0, [Layer.Episodic]: 0, [Layer.Semantic]: 0, [Layer.Trace]: 0 };
     const byConfidence = { verified: 0, observed: 0, inferred: 0, stale: 0 };
@@ -265,7 +303,8 @@ function tallyStatusRows(rows, now, atRiskBelow) {
     const { total, pinned, atRisk, agedOut } = sums;
     return { total, byLayer, byConfidence, pinned, atRisk, agedOut, avgStrength: total > 0 ? sums.strength / total : 0 };
 }
-/** The counts `hippo status` prints, from one pass over ten narrow columns: no text is read and no row array is built. */
+/** The counts `hippo status` prints, from one pass over ten narrow columns: no text is read and no row array is
+ * built. */
 export function loadStatusCounts(hippoRoot, now, atRiskBelow) {
     return onHandle(hippoRoot, (db) => {
         // One read transaction, so the row tallies and the two counts describe the same store.

package/dist/store/capture-write.d.ts

@@ -12,6 +12,7 @@ export interface CaptureWriteOpts {
     /** Called with each captured entry after its write, so the caller can embed it; the store never picks a provider. */
     readonly onCaptured?: (entry: MemoryEntry) => void;
 }
-/** One outcome per item, in order. `keys` holds the texts already stored and gains each one written, so a repeat inside the batch is skipped. */
+/** One outcome per item, in order. `keys` holds the texts already stored and gains each one written, so a repeat inside
+ * the batch is skipped. */
 export declare function writeCapturedItems(hippoRoot: string, items: readonly CaptureItem[], keys: Set<string>, opts: CaptureWriteOpts): CapturedOutcome[];
 //# sourceMappingURL=capture-write.d.ts.map

package/dist/store/capture-write.js

@@ -5,7 +5,8 @@ import { stampOriginProject } from './entry-row.js';
 import { gatedWrite } from './gated-write.js';
 import { updateStatsOn } from './index-and-stats.js';
 import { openStore } from './open.js';
-/** One outcome per item, in order. `keys` holds the texts already stored and gains each one written, so a repeat inside the batch is skipped. */
+/** One outcome per item, in order. `keys` holds the texts already stored and gains each one written, so a repeat inside
+ * the batch is skipped. */
 export function writeCapturedItems(hippoRoot, items, keys, opts) {
     const db = openStore(hippoRoot);
     try {

package/dist/store/card-detail.d.ts

@@ -1,15 +1,15 @@
 import type { Card, CardComment, CardRun } from '../core/card.js';
 import type { SessionHandoff } from '../core/handoff.js';
-import { loadCardDeps } from './cards.js';
+import { loadCardDepsAt } from './cards.js';
 /** A card plus everything `hippo card show` prints about it. */
 export interface CardDetail {
     card: Card;
-    deps: ReturnType<typeof loadCardDeps>;
+    deps: ReturnType<typeof loadCardDepsAt>;
     runs: CardRun[];
     comments: CardComment[];
     handoff: SessionHandoff | null;
 }
-/** Loads the detail behind `hippo card show` and `GET /api/cards/:id` (null when the tenant has no such card);
- * five separate reads, so a write landing between them can show a mixed view, as `card show` always could. */
+/** Loads the detail behind `hippo card show` and `GET /api/cards/:id` (null when the tenant has no such card), the five
+ * reads on one snapshot. */
 export declare function loadCardDetail(hippoRoot: string, tenantId: string, id: string): CardDetail | null;
 //# sourceMappingURL=card-detail.d.ts.map

package/dist/store/card-detail.js

@@ -1,16 +1,23 @@
-import { loadCard, loadCardComments, loadCardDeps, loadCardRuns, loadLatestHandoffForCard } from './cards.js';
-/** Loads the detail behind `hippo card show` and `GET /api/cards/:id` (null when the tenant has no such card);
- * five separate reads, so a write landing between them can show a mixed view, as `card show` always could. */
+import { withReadSnapshot } from '../db/index.js';
+import { loadCardCommentsAt, loadCardDepsAt, loadCardRow, loadCardRunsAt, loadLatestHandoffForCardAt, } from './cards.js';
+import { onHandle, openStore } from './open.js';
+import { assertTenantId } from './tenant.js';
+/** Loads the detail behind `hippo card show` and `GET /api/cards/:id` (null when the tenant has no such card), the five
+ * reads on one snapshot. */
 export function loadCardDetail(hippoRoot, tenantId, id) {
-    const card = loadCard(hippoRoot, tenantId, id);
+    assertTenantId('loadCardDetail', tenantId);
+    return onHandle(hippoRoot, (db) => withReadSnapshot(db, () => cardDetailAt(db, tenantId, id)), openStore);
+}
+function cardDetailAt(db, tenantId, id) {
+    const card = loadCardRow(db, tenantId, id);
     if (!card)
         return null;
     return {
         card,
-        deps: loadCardDeps(hippoRoot, tenantId, id),
-        runs: loadCardRuns(hippoRoot, tenantId, id),
-        comments: loadCardComments(hippoRoot, tenantId, id),
-        handoff: loadLatestHandoffForCard(hippoRoot, tenantId, id),
+        deps: loadCardDepsAt(db, tenantId, id),
+        runs: loadCardRunsAt(db, tenantId, id),
+        comments: loadCardCommentsAt(db, tenantId, id),
+        handoff: loadLatestHandoffForCardAt(db, tenantId, id),
     };
 }
 //# sourceMappingURL=card-detail.js.map

package/dist/store/cards.d.ts

@@ -1,5 +1,7 @@
+import { type DatabaseSyncLike } from '../db/index.js';
 import { SessionHandoff, HandoffOutcome } from '../core/handoff.js';
 import { Card, CardStatus, CardRun, CardComment } from '../core/card.js';
+export declare function loadCardRow(db: DatabaseSyncLike, tenantId: string, id: string): Card | null;
 export interface TransitionCardOptions {
     readonly from: CardStatus[];
     readonly to: CardStatus;
@@ -29,34 +31,46 @@ export declare function loadCardDeps(hippoRoot: string, tenantId: string, id: st
     parents: string[];
     children: string[];
 };
+export declare function loadCardDepsAt(db: DatabaseSyncLike, tenantId: string, id: string): {
+    parents: string[];
+    children: string[];
+};
 /** Returns this card's run history, most recent first. */
 export declare function loadCardRuns(hippoRoot: string, tenantId: string, id: string): CardRun[];
+export declare function loadCardRunsAt(db: DatabaseSyncLike, tenantId: string, id: string): CardRun[];
 /** Returns this card's comments, most recent first. */
 export declare function loadCardComments(hippoRoot: string, tenantId: string, id: string): CardComment[];
+export declare function loadCardCommentsAt(db: DatabaseSyncLike, tenantId: string, id: string): CardComment[];
 /** Read side of the card <-> handoff round trip: the newest handoff filed against this card. */
 export declare function loadLatestHandoffForCard(hippoRoot: string, tenantId: string, cardId: string): SessionHandoff | null;
-/** Atomic claim: WHERE status IN (ready, blocked) AND assignee_runtime IS NULL decides the race. Throws on an unknown card id;
- * returns null for a card not ready/blocked or already claimed. Sets a CARD_LEASE_MS lease and returns the new run's id as runId. */
+export declare function loadLatestHandoffForCardAt(db: DatabaseSyncLike, tenantId: string, cardId: string): SessionHandoff | null;
+/** Atomic claim: WHERE status IN (ready, blocked) AND assignee_runtime IS NULL decides the race. Throws on an unknown
+ * card id; returns null for a card not ready/blocked or already claimed. Sets a CARD_LEASE_MS lease and returns the new
+ * run's id as runId. */
 export declare function claimCard(hippoRoot: string, tenantId: string, id: string, runtime: string, sessionId?: string): (Card & {
     runId: number;
 }) | null;
-/** Moves a running card's lease to CARD_LEASE_MS from now and records the heartbeat; updated_at is left alone. Throws on an
- * unknown card id or a run id that is not a positive integer; returns null unless the card is running and runId is its live run. */
+/** Moves a running card's lease to CARD_LEASE_MS from now and records the heartbeat; updated_at is left alone. Throws
+ * on an unknown card id or a run id that is not a positive integer; returns null unless the card is running and runId
+ * is its live run. */
 export declare function heartbeatCard(hippoRoot: string, tenantId: string, id: string, runId: number): Card | null;
 /** Requires the card be running; closes the live run as blocked and files reason as a comment. Throws on an unknown
  * card id; returns null for a card not running. When runId is given, returns null unless it is the card's live run. */
 export declare function blockCard(hippoRoot: string, tenantId: string, id: string, reason: string, runId?: number): Card | null;
-/** Requires the card be running; moves it to review, clearing its lease and heartbeat and keeping its live run. When runId is
- * given, returns null unless it is the card's live run. Throws on an unknown card id; returns null for a card not running. */
+/** Requires the card be running; moves it to review, clearing its lease and heartbeat and keeping its live run. When
+ * runId is given, returns null unless it is the card's live run. Throws on an unknown card id; returns null for a card
+ * not running. */
 export declare function reviewCard(hippoRoot: string, tenantId: string, id: string, runId?: number): Card | null;
-/** Closes the live run of a card in review: 'success' moves it to done and promotes children whose parents are all done; 'failure'/'partial' shelves it.
- * Throws on an unknown card id; returns null for a card not in review, or when `runId` is given and is not the card's live run. */
+/** Closes the live run of a card in review: 'success' moves it to done and promotes children whose parents are all
+ * done; 'failure'/'partial' shelves it. Throws on an unknown card id; returns null for a card not in review, or when
+ * `runId` is given and is not the card's live run. */
 export declare function completeCard(hippoRoot: string, tenantId: string, id: string, outcome: HandoffOutcome, runId?: number): {
     card: Card;
     promotedChildren: string[];
 } | null;
-/** Returns to ready every running card of the tenant whose lease has expired or is missing: clears its assignee, closes its live
- * run as 'reclaimed' and leaves its handoffs alone, all in one write transaction. Returns the reclaimed card ids in id order. */
+/** Returns to ready every running card of the tenant whose lease has expired or is missing: clears its assignee, closes
+ * its live run as 'reclaimed' and leaves its handoffs alone, all in one write transaction. Returns the reclaimed card
+ * ids in id order. */
 export declare function reclaimExpiredCards(hippoRoot: string, tenantId: string): string[];
 /** Appends a comment to cardId in any card status; throws if cardId is not a card of this tenant. */
 export declare function addCardComment(hippoRoot: string, tenantId: string, cardId: string, author: string, body: string): CardComment;