hippo-memory 1.68.0 → 1.70.0

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

@@ -1,8 +1,10 @@
 import { createHash } from 'node:crypto';
-import { canAutoDelete } from './memory.js';
-import { log } from './log.js';
-import { keysetAfter } from './keyset.js';
-import { automaticDefect, hasNoSpecificity, isFragment, isReleaseCommitNoise, substantiveWordCount, } from './memory-quality.js';
+import { canAutoDelete } from '../core/memory.js';
+import { closeHippoDb, openHippoDb, withWriteScope } from '../db/index.js';
+import { log } from '../util/log.js';
+import { keysetAfter } from '../util/keyset.js';
+import { warnDamagedColumn } from '../util/stored-json.js';
+import { automaticDefect, hasNoSpecificity, isFragment, isReleaseCommitNoise, substantiveWordCount, } from '../core/memory-quality.js';
 export function auditMemory(entry, backsObject = false) {
     const issue = classifyMemory(entry);
     // Error means "auto-remove"; a pinned, raw, kept-for-good or object-backing row is never auto-removed, so it can only warn.
@@ -136,6 +138,16 @@ export function auditQueryFields(query) {
 export function appendAuditEvent(db, opts) {
     db.prepare(`INSERT INTO audit_log (ts, tenant_id, actor, op, target_id, metadata_json) VALUES (?, ?, ?, ?, ?, ?)`).run(new Date().toISOString(), opts.tenantId, opts.actor, opts.op, opts.targetId ?? null, JSON.stringify(opts.metadata ?? {}, bigintSafeReplacer));
 }
+/** One audit row in the store under `hippoRoot`, as its own write. */
+export function recordAuditEvent(hippoRoot, event) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        appendAuditEvent(db, event);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 let auditWriteFailures = 0;
 /** For callers that keep a mutation when its audit row fails: the failure is logged and counted, never silent. */
 export function reportAuditWriteFailure(op, reason, targetId) {
@@ -146,6 +158,10 @@ export function reportAuditWriteFailure(op, reason, targetId) {
 export function auditWriteFailureCount() {
     return auditWriteFailures;
 }
+/** Adds the failures a store worker counted on its own thread, so the process reports one number. */
+export function addAuditWriteFailures(count) {
+    auditWriteFailures += count;
+}
 export function queryAuditEvents(db, opts) {
     const where = ['tenant_id = ?'];
     const params = [opts.tenantId];
@@ -191,6 +207,37 @@ export function listAuditEventsAfter(db, opts) {
         .all(...params, limit);
     return rows.map(rowToAuditEvent);
 }
+/** How many of a tenant's audit rows are older than `cutoff`. */
+function countAuditBefore(db, tenantId, cutoff) {
+    // SAFETY: row comes from `SELECT COUNT(*) AS c`; COUNT(*) always yields exactly one row with a
+    // numeric `c` column (number or bigint depending on the node:sqlite driver's integer handling).
+    const row = db
+        .prepare(`SELECT COUNT(*) AS c FROM audit_log WHERE tenant_id = ? AND ts < ?`)
+        .get(tenantId, cutoff);
+    return Number(row.c);
+}
+/** Deletes a tenant's audit rows older than `cutoff`; returns how many went. */
+function deleteAuditBefore(db, tenantId, cutoff) {
+    const result = db
+        .prepare(`DELETE FROM audit_log WHERE tenant_id = ? AND ts < ?`)
+        .run(tenantId, cutoff);
+    return Number(result.changes ?? 0);
+}
+/** Latest time each target got a good outcome, from the audit rows, read on a handle of its own; unlike queryAuditEvents it has no row cap. */
+export function confirmedOutcomeTimes(hippoRoot, tenantId) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        // SAFETY: the SELECT list is exactly target_id and ts; no other shape reaches this cast.
+        const rows = db.prepare(`SELECT target_id, MAX(ts) AS ts FROM audit_log
+         WHERE tenant_id = ? AND op = 'outcome' AND target_id IS NOT NULL
+           AND json_extract(metadata_json, '$.good') = 1
+         GROUP BY target_id`).all(tenantId);
+        return new Map(rows.map((r) => [r.target_id, r.ts]));
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 const AUDIT_COLUMNS = 'id, ts, tenant_id, actor, op, target_id, metadata_json';
 function rowToAuditEvent(r) {
     return {
@@ -202,10 +249,10 @@ function rowToAuditEvent(r) {
         // typed AuditOp at the INSERT call site, so every stored value is a valid AuditOp.
         op: r.op,
         targetId: r.target_id,
-        metadata: safeJsonParse(r.metadata_json),
+        metadata: safeJsonParse(r.metadata_json, r.id),
     };
 }
-function safeJsonParse(raw) {
+function safeJsonParse(raw, id) {
     try {
         const v = JSON.parse(raw);
         // SAFETY: JSON.parse only ever returns a plain object, array, string, number,
@@ -216,7 +263,45 @@ function safeJsonParse(raw) {
     }
     catch {
         // Malformed metadata reads as empty so the audit row itself stays listable.
+        warnDamagedColumn({ table: 'audit_log', id, column: 'metadata_json' }, 'not valid JSON');
         return {};
     }
 }
+/** Appends each event as its own write on one handle, so a row that fails drops only itself. Returns the rows that failed, for the caller to report. */
+export function recordAuditEventsRowByRow(hippoRoot, events) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        const failed = [];
+        for (const event of events) {
+            try {
+                appendAuditEvent(db, event);
+            }
+            catch (error) {
+                failed.push({ event, error });
+            }
+        }
+        return failed;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Deletes a tenant's audit rows older than the cutoff and records the prune in the same write scope, so neither lands alone; returns the row count. */
+export function pruneAuditRows(hippoRoot, prune) {
+    const { tenantId, cutoff, actor, olderThanDays } = prune;
+    const db = openHippoDb(hippoRoot);
+    try {
+        if (prune.dryRun)
+            return countAuditBefore(db, tenantId, cutoff);
+        return withWriteScope(db, 'audit_prune', () => {
+            const count = deleteAuditBefore(db, tenantId, cutoff);
+            // Written after the delete with ts = now, so the cutoff just applied cannot take it.
+            appendAuditEvent(db, { tenantId, actor, op: 'audit_prune', metadata: { cutoff, count, dryRun: false, olderThanDays } });
+            return count;
+        });
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 //# sourceMappingURL=audit.js.map

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

@@ -1,6 +1,6 @@
-import type { DatabaseSyncLike } from './db.js';
-import { type KeysetPosition } from './keyset.js';
-import type { HippoStore } from './store-port.js';
+import { type DatabaseSyncLike } from '../db/index.js';
+import { type KeysetPosition } from '../util/keyset.js';
+import type { HippoStore } from './index.js';
 /** Every minted API key starts with this, so the server can route a bearer token by shape. */
 export declare const API_KEY_PREFIX = "hk_";
 /** Counts since process start, so a flood of bad tokens shows as scrypt work, not just as 401s. */
@@ -74,44 +74,25 @@ export interface ApiKeyRecord {
 }
 /** The api_keys row for `keyId` with its scope grants; null when no row matches. */
 export declare function readApiKeyRecord(db: DatabaseSyncLike, keyId: string): ApiKeyRecord | null;
-/** A key that passed every check, with the time it stops working so a cache entry never outlives it. */
-export interface CheckedApiKey {
-    key: VerifiedApiKey;
-    expiresAtMs: number;
-    keyHash: string;
-}
 export declare function validateApiKey(db: DatabaseSyncLike, plaintext: string): ValidateResult;
-/** How long a verified key is trusted without a store read; also the ceiling on a revoke made by another process. */
-export declare const VERIFIED_KEY_TTL_MS = 60000;
-/** LRU of verified keys with an absolute TTL. Holds a SHA-256 of the token, never the token. */
+/** LRU of the tokens that matched a stored key hash, so a repeat skips scrypt. Holds a SHA-256 of the token, never the token, and nothing about the key's state. */
 export declare class VerifiedKeyCache {
     private readonly capacity;
-    private readonly ttlMs;
-    private readonly entries;
-    private deletes;
-    constructor(capacity: number, ttlMs: number);
+    private readonly proven;
+    constructor(capacity: number);
     get size(): number;
-    /** Moves on every delete, so a store read that straddled a revoke or grant is not cached. */
-    get epoch(): number;
-    /** The entry this exact token was verified into, fresh or lapsed. */
-    private match;
-    get(hippoRoot: string, keyId: string, plaintext: string, now: number): VerifiedApiKey | undefined;
-    /** The key hash this exact token was last verified against, kept past the TTL so a re-check can skip scrypt. */
-    verifiedHash(hippoRoot: string, keyId: string, plaintext: string): string | undefined;
-    set(hippoRoot: string, keyId: string, plaintext: string, found: CheckedApiKey, now: number): void;
-    delete(keyId: string): void;
+    has(keyHash: string, plaintext: string): boolean;
+    add(keyHash: string, plaintext: string): void;
 }
-/** Verify a bearer API key against `store`, served at `hippoRoot`; a cache hit skips both scrypt and the store. Null when invalid. A token whose cache entry lapsed re-reads its record without scrypt; a throw from `beforeScrypt` refuses before scrypt runs. */
-export declare function verifyApiKeyCached(hippoRoot: string, plaintext: string, store: HippoStore, beforeScrypt?: () => void): Promise<VerifiedApiKey | null>;
+/** A caller's limit on scrypt work, called once per derivation: it may throw to refuse `derive` or hold it in a queue. */
+type DerivationBound = (keyId: string, derive: () => Promise<Buffer>) => Promise<Buffer>;
+/** Verify a bearer API key against `store`, null when invalid. The key's row is read on every call, so a revoke, expiry, role or scope change by any process applies on the next one. */
+export declare function verifyApiKeyCached(plaintext: string, store: HippoStore, bound?: DerivationBound): Promise<VerifiedApiKey | null>;
 export declare function revokeApiKey(db: DatabaseSyncLike, keyId: string, at?: string): void;
-/** A store other than hippo.db revokes without this process's cache, so its caller drops the key here once the revoke commits. */
-export declare function forgetVerifiedKey(keyId: string): void;
 /** Grant `keyId` read access to one restricted `scope`. Idempotent. */
 export declare function grantScope(db: DatabaseSyncLike, keyId: string, scope: string): void;
 /** Revoke `keyId`'s grant on `scope`. Not an error when no such grant exists. */
 export declare function ungrantScope(db: DatabaseSyncLike, keyId: string, scope: string): void;
-/** Every restricted scope `keyId` may read. */
-export declare function listScopeGrants(db: DatabaseSyncLike, keyId: string): string[];
 export interface ApiKeyListItem {
     keyId: string;
     tenantId: string;
@@ -150,7 +131,9 @@ export interface ApiKeyListRow {
 }
 /** Keys newest first, with their row ids, filtered and limited in SQL. */
 export declare function listApiKeyRows(db: DatabaseSyncLike, opts: ListApiKeysOpts): ApiKeyListRow[];
-export declare function listApiKeys(db: DatabaseSyncLike, opts: ListApiKeysOpts): ApiKeyListItem[];
+/** Keys of every tenant under `hippoRoot` unless `opts.tenantId` names one. */
+export declare function listApiKeys(hippoRoot: string, opts: ListApiKeysOpts): ApiKeyListItem[];
 /** Ids of the unrevoked, unexpired keys `ownerSubject` minted in `tenantId`, oldest first. */
 export declare function listLiveOwnedKeyIds(db: DatabaseSyncLike, tenantId: string, ownerSubject: string, now: number): string[];
+export {};
 //# sourceMappingURL=auth.d.ts.map

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

@@ -1,7 +1,9 @@
-import { createHash, randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
-import { raiseMinBinary } from './db/meta.js';
-import { keysetAfter } from './keyset.js';
-import { EXPIRING_KEYS_MIN_BINARY } from './version.js';
+import { createHash, randomBytes, scrypt, scryptSync, timingSafeEqual } from 'node:crypto';
+import { promisify } from 'node:util';
+import { closeHippoDb, openHippoDb } from '../db/index.js';
+import { raiseMinBinary } from '../db/meta.js';
+import { keysetAfter } from '../util/keyset.js';
+import { EXPIRING_KEYS_MIN_BINARY } from '../util/version.js';
 /** Every minted API key starts with this, so the server can route a bearer token by shape. */
 export const API_KEY_PREFIX = 'hk_';
 const ID_LEN = 24; // base32 chars after prefix
@@ -26,16 +28,26 @@ const verifyStats = { storeLookups: 0, scryptRuns: 0 };
 export function apiKeyVerifyStats() {
     return { ...verifyStats };
 }
-function verifyKey(plaintext, stored) {
+/** Null when `stored` has another shape. */
+function storedScrypt(stored) {
     const parts = stored.split('$');
     if (parts.length !== 3 || parts[0] !== 'scrypt')
-        return false;
-    const salt = Buffer.from(parts[1], 'hex');
+        return null;
     const expected = Buffer.from(parts[2], 'hex');
+    return {
+        salt: Buffer.from(parts[1], 'hex'),
+        keylen: expected.length,
+        matches: (derived) => expected.length === derived.length && timingSafeEqual(expected, derived),
+    };
+}
+function verifyKey(plaintext, stored) {
+    const parsed = storedScrypt(stored);
+    if (!parsed)
+        return false;
     verifyStats.scryptRuns++;
-    const actual = scryptSync(plaintext, salt, expected.length);
-    return expected.length === actual.length && timingSafeEqual(expected, actual);
+    return parsed.matches(scryptSync(plaintext, parsed.salt, parsed.keylen));
 }
+const scryptOffLoop = promisify(scrypt);
 export function mintApiKey() {
     const keyId = `${API_KEY_PREFIX}${randBase32(ID_LEN)}`;
     const plaintext = `${keyId}.${randBase32(SECRET_LEN)}`;
@@ -85,138 +97,127 @@ function keyExpiryMs(expiresAt) {
 function mintedKeyId(plaintext) {
     return MINTED_KEY_PATTERN.test(plaintext) ? plaintext.slice(0, API_KEY_PREFIX.length + ID_LEN) : null;
 }
-/** Revocation, expiry, then the secret, against a stored record. Null for any failure. */
-function checkApiKey(keyId, record, now, secretMatches) {
+/** 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.
     if (!record)
-        return null;
-    const expiresAtMs = keyExpiryMs(record.expiresAt);
-    if (record.revokedAt || now >= expiresAtMs || !secretMatches(record.keyHash))
-        return null;
+        return false;
+    return !record.revokedAt && now < keyExpiryMs(record.expiresAt);
+}
+/** The verified key a usable record whose secret matched carries. */
+function verifiedKeyOf(keyId, record) {
     // Fail-safe to least privilege: any role value but 'admin' reads as 'member'.
     const role = record.role === 'admin' ? 'admin' : 'member';
     const key = { tenantId: record.tenantId, keyId, role, scopes: [...record.scopes] };
     // Only a real name counts as an owner; anything else leaves the key keyed on its own id.
     if (record.ownerSubject)
         key.ownerSubject = record.ownerSubject;
-    return { key, expiresAtMs, keyHash: record.keyHash };
+    return key;
 }
 /** One full check against the store: shape, row, revocation, expiry, then scrypt. Null for any failure. */
 function lookupApiKey(db, plaintext, now) {
     const keyId = mintedKeyId(plaintext);
-    return keyId === null ? null : checkApiKey(keyId, readApiKeyRecord(db, keyId), now, (hash) => verifyKey(plaintext, hash));
+    if (keyId === null)
+        return null;
+    const record = readApiKeyRecord(db, keyId);
+    return isUsable(record, now) && verifyKey(plaintext, record.keyHash) ? verifiedKeyOf(keyId, record) : null;
 }
 export function validateApiKey(db, plaintext) {
     const found = lookupApiKey(db, plaintext, Date.now());
-    return found ? { valid: true, ...found.key } : { valid: false };
+    return found ? { valid: true, ...found } : { valid: false };
 }
-/** How long a verified key is trusted without a store read; also the ceiling on a revoke made by another process. */
-export const VERIFIED_KEY_TTL_MS = 60_000;
 const VERIFIED_KEY_CACHE_CAP = 1_000;
 function secretDigest(plaintext) {
     return createHash('sha256').update(plaintext).digest();
 }
-/** LRU of verified keys with an absolute TTL. Holds a SHA-256 of the token, never the token. */
+/** LRU of the tokens that matched a stored key hash, so a repeat skips scrypt. Holds a SHA-256 of the token, never the token, and nothing about the key's state. */
 export class VerifiedKeyCache {
     capacity;
-    ttlMs;
-    // Map iterates in insertion order, so re-inserting on a hit makes the first key the least recent.
-    entries = new Map();
-    deletes = 0;
-    constructor(capacity, ttlMs) {
+    // 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;
-        this.ttlMs = ttlMs;
     }
     get size() {
-        return this.entries.size;
+        return this.proven.size;
     }
-    /** Moves on every delete, so a store read that straddled a revoke or grant is not cached. */
-    get epoch() {
-        return this.deletes;
-    }
-    /** The entry this exact token was verified into, fresh or lapsed. */
-    match(hippoRoot, keyId, plaintext) {
-        const entry = this.entries.get(keyId);
-        if (!entry || entry.hippoRoot !== hippoRoot)
-            return undefined;
+    has(keyHash, plaintext) {
+        const digest = this.proven.get(keyHash);
         // A wrong secret misses but leaves the entry, so a flood of bad guesses cannot evict a good key.
-        return timingSafeEqual(entry.digest, secretDigest(plaintext)) ? entry : undefined;
-    }
-    get(hippoRoot, keyId, plaintext, now) {
-        const entry = this.match(hippoRoot, keyId, plaintext);
-        if (!entry || now >= entry.expiresAt)
-            return undefined;
-        this.entries.delete(keyId);
-        this.entries.set(keyId, entry);
-        return { ...entry.key, scopes: [...entry.key.scopes] };
+        if (!digest || !timingSafeEqual(digest, secretDigest(plaintext)))
+            return false;
+        this.proven.delete(keyHash);
+        this.proven.set(keyHash, digest);
+        return true;
     }
-    /** The key hash this exact token was last verified against, kept past the TTL so a re-check can skip scrypt. */
-    verifiedHash(hippoRoot, keyId, plaintext) {
-        return this.match(hippoRoot, keyId, plaintext)?.keyHash;
-    }
-    set(hippoRoot, keyId, plaintext, found, now) {
-        this.entries.delete(keyId);
-        if (this.entries.size >= this.capacity) {
-            const oldest = this.entries.keys().next();
+    add(keyHash, plaintext) {
+        this.proven.delete(keyHash);
+        if (this.proven.size >= this.capacity) {
+            const oldest = this.proven.keys().next();
             if (!oldest.done)
-                this.entries.delete(oldest.value);
+                this.proven.delete(oldest.value);
         }
-        const frozen = Object.freeze({ ...found.key, scopes: [...found.key.scopes] });
-        // A key that expires inside the TTL leaves the cache at its expiry, so the cache never extends its life.
-        const expiresAt = Math.min(now + this.ttlMs, found.expiresAtMs);
-        this.entries.set(keyId, { hippoRoot, digest: secretDigest(plaintext), key: frozen, keyHash: found.keyHash, expiresAt });
-    }
-    delete(keyId) {
-        this.deletes++;
-        this.entries.delete(keyId);
+        this.proven.set(keyHash, secretDigest(plaintext));
     }
 }
-// SHORTCUT: per-process cache, so a revoke or scope change made by another process (the CLI) lands within VERIFIED_KEY_TTL_MS; a shared revocation epoch in the store if that is too slow.
-const verifiedKeys = new VerifiedKeyCache(VERIFIED_KEY_CACHE_CAP, VERIFIED_KEY_TTL_MS);
-/** Verify a bearer API key against `store`, served at `hippoRoot`; a cache hit skips both scrypt and the store. Null when invalid. A token whose cache entry lapsed re-reads its record without scrypt; a throw from `beforeScrypt` refuses before scrypt runs. */
-export async function verifyApiKeyCached(hippoRoot, plaintext, store, beforeScrypt) {
+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. */
+async function secretMatches(keyId, plaintext, keyHash, bound) {
+    if (verifiedKeys.has(keyHash, plaintext))
+        return true;
+    const parsed = storedScrypt(keyHash);
+    if (!parsed)
+        return false;
+    const id = `${keyHash}\u0000${plaintext}`;
+    const running = checksInFlight.get(id);
+    if (running)
+        return running;
+    const derive = () => {
+        verifyStats.scryptRuns++;
+        return scryptOffLoop(plaintext, parsed.salt, parsed.keylen);
+    };
+    const check = (bound ? bound(keyId, derive) : derive()).then((derived) => {
+        const matched = parsed.matches(derived);
+        // Only successes are kept: keeping misses would let junk tokens fill the cache and evict real keys.
+        if (matched)
+            verifiedKeys.add(keyHash, plaintext);
+        return matched;
+    });
+    checksInFlight.set(id, check);
+    const forget = () => {
+        checksInFlight.delete(id);
+    };
+    void check.then(forget, forget);
+    return check;
+}
+/** Verify a bearer API key against `store`, null when invalid. The key's row is read on every call, so a revoke, expiry, role or scope change by any process applies on the next one. */
+export async function verifyApiKeyCached(plaintext, store, bound) {
     const keyId = mintedKeyId(plaintext);
     if (keyId === null)
         return null;
-    const hit = verifiedKeys.get(hippoRoot, keyId, plaintext, Date.now());
-    if (hit)
-        return hit;
-    const provenHash = verifiedKeys.verifiedHash(hippoRoot, keyId, plaintext);
     verifyStats.storeLookups++;
-    const epoch = verifiedKeys.epoch;
-    const found = checkApiKey(keyId, await store.findApiKey(keyId), Date.now(), (hash) => {
-        if (hash === provenHash)
-            return true;
-        beforeScrypt?.();
-        return verifyKey(plaintext, hash);
-    });
-    // Only successes are cached: caching misses would let junk tokens fill the cache and evict real keys.
-    if (found && verifiedKeys.epoch === epoch)
-        verifiedKeys.set(hippoRoot, keyId, plaintext, found, Date.now());
-    return found?.key ?? null;
+    const record = await store.findApiKey(keyId);
+    if (!isUsable(record, Date.now()))
+        return null;
+    return (await secretMatches(keyId, plaintext, record.keyHash, bound)) ? verifiedKeyOf(keyId, record) : null;
 }
 export function revokeApiKey(db, keyId, at = new Date().toISOString()) {
     db.prepare(`UPDATE api_keys SET revoked_at = ? WHERE key_id = ? AND revoked_at IS NULL`)
         .run(at, keyId);
-    verifiedKeys.delete(keyId);
-}
-/** A store other than hippo.db revokes without this process's cache, so its caller drops the key here once the revoke commits. */
-export function forgetVerifiedKey(keyId) {
-    verifiedKeys.delete(keyId);
 }
 /** Grant `keyId` read access to one restricted `scope`. Idempotent. */
 export function grantScope(db, keyId, scope) {
     db.prepare(`INSERT INTO api_key_scope_grants (key_id, scope, granted_at) VALUES (?, ?, ?)
      ON CONFLICT(key_id, scope) DO NOTHING`).run(keyId, scope, new Date().toISOString());
-    verifiedKeys.delete(keyId);
 }
 /** Revoke `keyId`'s grant on `scope`. Not an error when no such grant exists. */
 export function ungrantScope(db, keyId, scope) {
     db.prepare(`DELETE FROM api_key_scope_grants WHERE key_id = ? AND scope = ?`).run(keyId, scope);
-    verifiedKeys.delete(keyId);
 }
 /** Every restricted scope `keyId` may read. */
-export function listScopeGrants(db, keyId) {
+function listScopeGrants(db, keyId) {
     // SAFETY: rows' shape matches the single `scope` column named in the SELECT above.
     const rows = db
         .prepare(`SELECT scope FROM api_key_scope_grants WHERE key_id = ? ORDER BY scope`)
@@ -263,8 +264,15 @@ export function listApiKeyRows(db, opts) {
         },
     }));
 }
-export function listApiKeys(db, opts) {
-    return listApiKeyRows(db, opts).map(r => r.key);
+/** Keys of every tenant under `hippoRoot` unless `opts.tenantId` names one. */
+export function listApiKeys(hippoRoot, opts) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        return listApiKeyRows(db, opts).map(r => r.key);
+    }
+    finally {
+        closeHippoDb(db);
+    }
 }
 /** Ids of the unrevoked, unexpired keys `ownerSubject` minted in `tenantId`, oldest first. */
 export function listLiveOwnedKeyIds(db, tenantId, ownerSubject, now) {

package/dist/store/candidates.d.ts

@@ -1,5 +1,5 @@
-import type { MemoryEntry, StrengthInputs } from '../memory.js';
-import { type SqlFragment } from '../recall-scope.js';
+import { type MemoryEntry } from '../core/memory.js';
+import { type SqlFragment } from './recall-scope.js';
 export interface AmbientRecallRequest {
     terms: string[];
     limit: number;
@@ -9,10 +9,6 @@ export interface AmbientLoadResult {
     entries: MemoryEntry[];
     recall?: MemoryEntry[];
 }
-/** Exported so the plan test runs the exact SQL; idx_memories_pinned (db.ts v51) serves it. */
-export declare const AMBIENT_PINNED_WHERE = "pinned = 1 AND superseded_by IS NULL AND tenant_id = ? ORDER BY created ASC, id ASC";
-/** Exported so the plan test runs the exact SQL; idx_memories_created_drift (db.ts v51) serves it. */
-export declare const AMBIENT_DRIFT_SQL = "SELECT 1 FROM memories WHERE superseded_by IS NULL AND tenant_id = ? AND (length(created) <> 24 OR created NOT LIKE '%Z') LIMIT 1";
 /** The origins a caller's recent rows may carry: its project names, and user-global ('') rows when `userGlobal`. */
 export interface RecentOrigins {
     readonly names: readonly string[];
@@ -33,14 +29,16 @@ export interface ContextCandidateFilter {
 }
 /** Live tenant rows passing `filter`, at most `filter.cap`, in loadAllEntries' order; below the cap, every such row. */
 export declare function loadContextCandidates(hippoRoot: string, tenantId: string, filter: ContextCandidateFilter): MemoryEntry[];
-/** A row's strength inputs and tags, without its text or the JSON lists a full row parses. */
-export type StrengthRow = StrengthInputs & Pick<MemoryEntry, 'tags'>;
-/** Every tenant row as a StrengthRow, for whole-store health numbers; defaults match rowToEntry's. */
-export declare function loadStrengthRows(hippoRoot: string, tenantId: string): StrengthRow[];
 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;
 /** Text, source and origin of tenant rows holding any of `words` that `admit` passes, by default the team-visible ones; a row equal to a text apart from spacing holds its every word.
- *  With `project`, only rows carrying one of those names and user-global rows, as loadContextCandidates' filter. */
-export declare function loadTextsHoldingWords(hippoRoot: string, tenantId: string, words: readonly string[], project?: readonly string[], admit?: SqlFragment): HeldText[];
+ *  With `project`, only rows carrying one of those names and 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. */
+export declare function loadNewestEntries(hippoRoot: string, tenantId: string, limit: number): MemoryEntry[];
+/** computeSchemaFit against every row of a tenant: tag counts come from one aggregate and texts stream one column, so no row is loaded. */
+export declare function schemaFitInStore(hippoRoot: string, tenantId: string, content: string, tags: readonly string[]): number;
 export interface SourceTally {
     source: string;
     count: number;
@@ -50,4 +48,17 @@ export interface SourceTally {
 }
 /** 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. */
+export interface StrengthTallies {
+    total: number;
+    pinned: number;
+    /** Rows tagged exactly `error`. */
+    errors: number;
+    strengthSum: number;
+    /** Unpinned rows whose strength is under `atRiskBelow`. */
+    atRisk: number;
+}
+/** 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;
 //# sourceMappingURL=candidates.d.ts.map