hippo-memory 1.70.0 → 1.71.0

package/dist/store/auth.d.ts

@@ -75,7 +75,8 @@ 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;
 export declare function validateApiKey(db: DatabaseSyncLike, plaintext: string): ValidateResult;
-/** 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. */
+/** 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 proven;
@@ -86,7 +87,8 @@ export declare class VerifiedKeyCache {
 }
 /** 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. */
+/** 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;
 /** Grant `keyId` read access to one restricted `scope`. Idempotent. */
@@ -99,10 +101,8 @@ export interface ApiKeyListItem {
     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[];

package/dist/store/auth.js

@@ -54,9 +54,8 @@ export function mintApiKey() {
     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);
@@ -71,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);
@@ -84,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;
@@ -130,7 +129,8 @@ const VERIFIED_KEY_CACHE_CAP = 1_000;
 function secretDigest(plaintext) {
     return createHash('sha256').update(plaintext).digest();
 }
-/** 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. */
+/** 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;
     // 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.
@@ -192,7 +192,8 @@ async function secretMatches(keyId, plaintext, keyHash, bound) {
     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. */
+/** 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)

package/dist/store/candidates.d.ts

@@ -1,4 +1,4 @@
-import { type MemoryEntry } from '../core/memory.js';
+import { type MemoryEntry, type ConfidenceLevel, Layer } from '../core/memory.js';
 import { type SqlFragment } from './recall-scope.js';
 export interface AmbientRecallRequest {
     terms: string[];
@@ -32,8 +32,8 @@ 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;
-/** 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. 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. */
 export declare function loadNewestEntries(hippoRoot: string, tenantId: string, limit: number): MemoryEntry[];
@@ -61,4 +61,21 @@ 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;
+/** 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

package/dist/store/candidates.js

@@ -1,14 +1,15 @@
-import { schemaFitFrom, strengthSql } from '../core/memory.js';
-import { closeHippoDb, withReadSnapshot } from '../db/index.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 { scopeAdmitSql } from './recall-scope.js';
 import { MEMORY_SELECT_COLUMNS, rowToEntry, parseJsonArray } from './rows.js';
-import { openStore } from './open.js';
+import { onHandle, openStore } from './open.js';
 import { originInSql } from '../core/project-identity.js';
 import { pickRarestFtsQuery, loadRecallSearchEntriesFromDb } from './search-rows.js';
 const AMBIENT_SCOPED = 'superseded_by IS NULL AND tenant_id = ?';
-/** idx_memories_pinned (db.ts v51) serves it. */
+/** idx_memories_pinned (migration v51) serves it. */
 const AMBIENT_PINNED_WHERE = `pinned = 1 AND ${AMBIENT_SCOPED} ORDER BY created ASC, id ASC`;
-/** idx_memories_created_drift (db.ts v51) serves it. */
+/** idx_memories_created_drift (migration v51) serves it. */
 const AMBIENT_DRIFT_SQL = `SELECT 1 FROM memories WHERE ${AMBIENT_SCOPED} AND (length(created) <> 24 OR created NOT LIKE '%Z') LIMIT 1`;
 function inOrigins(e, origins) {
     const origin = e.origin_project ?? null;
@@ -47,8 +48,7 @@ export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit,
     // A SQL LIMIT takes an integer; the Array.slice this replaced truncated one,
     // and include_recent is any non-negative finite number at the HTTP edge.
     const needed = Math.trunc(recentNeeded);
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: every `where` below starts from MEMORY_SELECT_COLUMNS' table.
         const run = (where, params) => db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE ${where}`).all(...params).map(rowToEntry);
         const byId = new Map();
@@ -74,10 +74,7 @@ export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit,
             ? loadRecallSearchEntriesFromDb(db, ftsQuery, { limit: recall.limit, tenantId, includeSuperseded: false, ownScope: recall.ownScope })
             : [];
         return { entries, recall: recallEntries };
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 // calculateStrength's decay exponent with its reward factor, pins first: the strongest rows, without scoring each one in JS.
 const DECAY_RANK_SQL = `pinned DESC,
@@ -102,32 +99,27 @@ export function loadContextCandidates(hippoRoot, tenantId, filter) {
         where.push(`(origin_project = '' OR ${originInSql(filter.project)})`);
         params.push(...filter.project);
     }
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: the outer SELECT names exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set; the rank sort carries ids only.
         const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id IN (
         SELECT id FROM memories WHERE ${where.join(' AND ')} ORDER BY ${DECAY_RANK_SQL} LIMIT ?
       ) ORDER BY created ASC, id ASC`).all(...params, filter.now.toISOString(), Math.max(0, Math.trunc(filter.cap)));
         return rows.map(rowToEntry);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 // No owner: for session capture, a personal or connector-private row must never stop a team copy being written.
 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: [] });
-/** 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. 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 = [];
     const tenantWhere = tenantId === undefined ? '1' : 'tenant_id = ?';
     const tenantParams = tenantId === undefined ? [] : [tenantId];
     const originWhere = project === undefined ? '' : ` AND (origin_project = '' OR ${originInSql(project)})`;
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // Chunked so one statement stays far under SQLite's bound-parameter limit.
         for (let i = 0; i < unique.length; i += 200) {
             const chunk = unique.slice(i, i + 200);
@@ -137,22 +129,15 @@ export function loadTextsHoldingWords(hippoRoot, tenantId, words, project, admit
                 out.push({ content: row.content, source: row.source ?? 'cli', origin_project: row.origin_project });
         }
         return out;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** 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) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: the SELECT names exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
         const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE tenant_id = ? ORDER BY created DESC, id DESC LIMIT ?`).all(tenantId, limit);
         return rows.reverse().map(rowToEntry);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 function* contentsOf(rows) {
     for (const row of rows)
@@ -160,8 +145,7 @@ function* contentsOf(rows) {
 }
 /** computeSchemaFit against every row of a tenant: tag counts come from one aggregate and texts stream one column, so no row is loaded. */
 export function schemaFitInStore(hippoRoot, tenantId, content, tags) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // 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.
@@ -178,23 +162,16 @@ export function schemaFitInStore(hippoRoot, tenantId, content, tags) {
             const texts = db.prepare('SELECT content FROM memories WHERE tenant_id = ?').iterate(tenantId);
             return schemaFitFrom(content, tags, { rows, tagCounts, contents: contentsOf(texts) });
         });
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** 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) {
-    const db = openStore(hippoRoot);
-    try {
+    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] : []));
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, 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)`;
@@ -202,8 +179,7 @@ export const jsonList = (column) => `(CASE WHEN json_valid(${column}) AND json_t
 export function loadStrengthTallies(hippoRoot, tenantId, now, atRiskBelow) {
     // An unparseable date scores NULL in SQL and 0 in calculateStrength.
     const strength = `COALESCE(${strengthSql(now)}, 0)`;
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: one aggregate row whose columns are the aliases named below.
         const row = db.prepare(`SELECT
       COUNT(*) AS total,
@@ -219,9 +195,62 @@ export function loadStrengthTallies(hippoRoot, tenantId, now, atRiskBelow) {
             strengthSum: Number(row.strengthSum),
             atRisk: Number(row.atRisk),
         };
+    }, openStore);
+}
+// 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.
+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 };
+    const sums = { total: 0, strength: 0, pinned: 0, atRisk: 0, agedOut: 0 };
+    for (const row of rows) {
+        // rowToEntry's defaults for these columns, so a row scores as its loaded entry would.
+        const entry = {
+            pinned: Boolean(row.pinned),
+            confidence: row.confidence ?? 'observed',
+            created: row.created,
+            last_retrieved: row.last_retrieved,
+            half_life_days: Number(row.half_life_days ?? FALLBACK_HALF_LIFE_DAYS),
+            retrieval_count: Number(row.retrieval_count ?? 0),
+            emotional_valence: row.emotional_valence ?? 'neutral',
+            outcome_positive: Number(row.outcome_positive ?? 0),
+            outcome_negative: Number(row.outcome_negative ?? 0),
+        };
+        const strength = calculateStrength(entry, now);
+        const facets = facetsOf(entry, now);
+        sums.total++;
+        sums.strength += strength;
+        byLayer[row.layer] = (byLayer[row.layer] ?? 0) + 1;
+        byConfidence[facets.tier] = (byConfidence[facets.tier] ?? 0) + 1;
+        if (entry.pinned)
+            sums.pinned++;
+        if (strength < atRiskBelow)
+            sums.atRisk++;
+        if (facets.agedOut)
+            sums.agedOut++;
     }
-    finally {
-        closeHippoDb(db);
-    }
+    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. */
+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.
+        return withReadSnapshot(db, () => {
+            // loadAllEntries' order, so the strengths add up in the order they did and the average rounds the same.
+            // SAFETY: the SELECT names exactly StatusRow's columns, and the store writes `layer` only from the Layer enum.
+            const rows = db.prepare(`SELECT ${STATUS_ROW_COLUMNS.join(', ')} FROM memories ORDER BY created ASC, id ASC`).iterate();
+            const tallies = tallyStatusRows(rows, now, atRiskBelow);
+            // SAFETY: one row whose columns are the two aliases named below.
+            const counts = db.prepare(`SELECT
+        (SELECT COUNT(*) FROM memory_conflicts WHERE status = 'open') AS openConflicts,
+        (SELECT COUNT(*) FROM memory_vectors WHERE memory_id IN (SELECT id FROM memories)) AS embedded`).get();
+            return { ...tallies, openConflicts: Number(counts.openConflicts), embedded: Number(counts.embedded) };
+        });
+    }, openStore);
 }
 //# sourceMappingURL=candidates.js.map

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

@@ -9,6 +9,7 @@ export interface CardDetail {
     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);
+ * five separate reads, so a write landing between them can show a mixed view, as `card show` always could. */
 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,5 +1,6 @@
 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. */
+/** 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. */
 export function loadCardDetail(hippoRoot, tenantId, id) {
     const card = loadCard(hippoRoot, tenantId, id);
     if (!card)

package/dist/store/cards.d.ts

@@ -1,4 +1,3 @@
-import { type DatabaseSyncLike } from '../db/index.js';
 import { SessionHandoff, HandoffOutcome } from '../core/handoff.js';
 import { Card, CardStatus, CardRun, CardComment } from '../core/card.js';
 export interface TransitionCardOptions {
@@ -10,8 +9,8 @@ export interface TransitionCardOptions {
         params?: unknown[];
     };
 }
-export declare function transitionCard(db: DatabaseSyncLike, tenantId: string, cardId: string, options: TransitionCardOptions): number;
-/** Creates a card; status is ready with no deps or once every dependsOn id is done, else backlog. An unknown dependsOn id throws and commits nothing. A repeated dependsOn id is recorded once. */
+/** Creates a card; status is ready with no deps or once every dependsOn id is done, else backlog.
+ * An unknown dependsOn id throws and commits nothing. A repeated dependsOn id is recorded once. */
 export declare function createCard(hippoRoot: string, tenantId: string, input: {
     title: string;
     repo?: string;
@@ -36,22 +35,28 @@ export declare function loadCardRuns(hippoRoot: string, tenantId: string, id: st
 export declare function loadCardComments(hippoRoot: string, 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. */
+/** 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. */
+/** 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;
-/** Requires the card be in review; closes the live run with outcome. Outcome 'success' moves the card to done and, in the same transaction, promotes any child whose parents are now all done; 'failure' or 'partial' moves it to shelved and promotes nothing. Throws on an unknown card id; returns null for a card not in review. When runId is given, returns null unless it is 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;