hippo-memory 1.69.0 → 1.71.0

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,54 +74,35 @@ 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;
     label: string | null;
     createdAt: string;
     revokedAt: string | null;
-    /**
-     * Authorization role bound to the key, from the `role` column (schema migration v26).
-     * Fail-safe-to-member cast: any non-'admin' value reads as 'member'.
-     */
+    /** Authorization role from the `role` column (schema migration v26).
+     * Fail-safe cast: any non-'admin' value reads as 'member'. */
     role: 'admin' | 'member';
     /** Restricted scopes this key may read. */
     scopes: 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,25 +28,34 @@ 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)}`;
     return { keyId, plaintext, keyHash: hashKey(plaintext) };
 }
 export function insertApiKey(db, key) {
-    // openHippoDb runs runMigrations synchronously before returning the db handle,
-    // so migration v26 (adds role column) is in place before this INSERT runs.
-    // An older binary ignores expires_at and would honour an expired key, so the store shuts it out before the first one exists.
+    // Migration v26 (role column) has already run; an older binary ignores expires_at and would honour an expired 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);
@@ -59,9 +70,8 @@ export function createApiKey(db, opts) {
 }
 /** 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);
@@ -72,7 +82,8 @@ export function readApiKeyRecord(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 field (a store that predates expiry) or a stamp that does not parse, so both fail closed. */
+/** When a key stops working, in epoch ms: Infinity for null, and already past for a missing
+ * field (a store that predates expiry) or a stamp that does not parse, so both fail closed. */
 function keyExpiryMs(expiresAt) {
     if (expiresAt === null)
         return Infinity;
@@ -85,138 +96,129 @@ 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 +265,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, type ConfidenceLevel, Layer } 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'>;
-/** 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[];
+/** 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. */
+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,34 @@ 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;
+/** What `hippo status` prints about the whole store: every tenant and superseded rows too. */
+export interface StatusCounts {
+    total: number;
+    byLayer: Record<Layer, number>;
+    byConfidence: Record<ConfidenceLevel, number>;
+    pinned: number;
+    /** Rows whose strength is under the caller's line; unlike StrengthTallies, pinned rows count. */
+    atRisk: number;
+    agedOut: number;
+    avgStrength: number;
+    /** Open conflicts of every tenant, the rows listMemoryConflicts returns when given no tenant. */
+    openConflicts: number;
+    /** 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. */
+export declare function loadStatusCounts(hippoRoot: string, now: Date, atRiskBelow: number): StatusCounts;
 //# sourceMappingURL=candidates.d.ts.map