hippo-memory 1.68.0 → 1.70.0

package/dist/store/candidates.js

@@ -1,21 +1,23 @@
-import { closeHippoDb } from '../db.js';
-import { scopeAdmitSql } from '../recall-scope.js';
+import { schemaFitFrom, strengthSql } from '../core/memory.js';
+import { closeHippoDb, 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 { originInSql } from '../project-identity.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 = ?';
-/** Exported so the plan test runs the exact SQL; idx_memories_pinned (db.ts v51) serves it. */
-export const AMBIENT_PINNED_WHERE = `pinned = 1 AND ${AMBIENT_SCOPED} 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 const AMBIENT_DRIFT_SQL = `SELECT 1 FROM memories WHERE ${AMBIENT_SCOPED} AND (length(created) <> 24 OR created NOT LIKE '%Z') LIMIT 1`;
+/** idx_memories_pinned (db.ts 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. */
+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;
     return origin === '' ? origins.userGlobal : origin !== null && origins.names.includes(origin);
 }
 // The newest rows `admit` keeps, newest first. The first window stays unfiltered so admit still sees, and the
 // delivery ledger still counts, the other-project rows it refuses; past it, the reads narrow to the caller's origins.
-function loadRecentRows(run, drifted, tenantId, needed, admit, origins) {
+function loadRecentRows(run, drifted, tenantId, options) {
+    const { needed, admit, origins } = options;
     const keep = origins ? (e) => admit(e) && inOrigins(e, origins) : admit;
     // `id DESC` mirrors getContext's comparator, not loadFreshRawMemories'
     // cross-ingest-stable order: that would change what the hook injects.
@@ -56,7 +58,7 @@ export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit,
         }
         if (needed > 0) {
             const drifted = db.prepare(AMBIENT_DRIFT_SQL).get(tenantId) !== undefined;
-            for (const e of loadRecentRows(run, drifted, tenantId, needed, admit, origins))
+            for (const e of loadRecentRows(run, drifted, tenantId, { needed, admit, origins }))
                 byId.set(e.id, e);
         }
         // loadAllEntries' order: rankedPinned's comparator can tie and Array.sort
@@ -69,7 +71,7 @@ export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit,
             return { entries };
         const ftsQuery = pickRarestFtsQuery(db, recall.terms);
         const recallEntries = ftsQuery
-            ? loadRecallSearchEntriesFromDb(db, ftsQuery, recall.limit, tenantId, undefined, 'exact', false, undefined, recall.ownScope)
+            ? loadRecallSearchEntriesFromDb(db, ftsQuery, { limit: recall.limit, tenantId, includeSuperseded: false, ownScope: recall.ownScope })
             : [];
         return { entries, recall: recallEntries };
     }
@@ -112,36 +114,17 @@ export function loadContextCandidates(hippoRoot, tenantId, filter) {
         closeHippoDb(db);
     }
 }
-/** Every tenant row as a StrengthRow, for whole-store health numbers; defaults match rowToEntry's. */
-export function loadStrengthRows(hippoRoot, tenantId) {
-    const db = openStore(hippoRoot);
-    try {
-        // SAFETY: rows' shape matches the columns named in the SELECT below.
-        const rows = db.prepare(`SELECT pinned, created, last_retrieved, half_life_days, retrieval_count, emotional_valence, outcome_positive, outcome_negative, tags_json
-       FROM memories WHERE tenant_id = ?`).all(tenantId);
-        return rows.map((row) => ({
-            pinned: Boolean(row.pinned),
-            created: row.created,
-            last_retrieved: row.last_retrieved,
-            half_life_days: Number(row.half_life_days ?? 7),
-            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),
-            tags: parseJsonArray(row.tags_json),
-        }));
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
 // 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. */
+ *  With `project`, only rows carrying one of those names and 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 {
@@ -149,7 +132,7 @@ 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 tenant_id = ?${originWhere} AND ${admit.sql} AND (${chunk.map(() => 'instr(content, ?) > 0').join(' OR ')})`).all(tenantId, ...(project ?? []), ...admit.params, ...chunk);
+            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 });
         }
@@ -159,6 +142,47 @@ export function loadTextsHoldingWords(hippoRoot, tenantId, words, project, admit
         closeHippoDb(db);
     }
 }
+/** 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 {
+        // 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);
+    }
+}
+function* contentsOf(rows) {
+    for (const row of rows)
+        yield row.content;
+}
+/** 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 {
+        // 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 memories WHERE tenant_id = ? GROUP BY tags_json').all(tenantId);
+            let rows = 0;
+            const tagCounts = new Map();
+            for (const group of groups) {
+                rows += group.n;
+                for (const tag of parseJsonArray(group.tags_json))
+                    tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + group.n);
+            }
+            // SHORTCUT: the text walk visits rows until a tenth of the tenant matches; a stored token count per tenant is the upgrade.
+            // SAFETY: the SELECT names exactly the one column read.
+            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);
+    }
+}
 /** 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);
@@ -172,4 +196,32 @@ export function tallySources(hippoRoot, tenantId) {
         closeHippoDb(db);
     }
 }
+// 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) {
+    // An unparseable date scores NULL in SQL and 0 in calculateStrength.
+    const strength = `COALESCE(${strengthSql(now)}, 0)`;
+    const db = openStore(hippoRoot);
+    try {
+        // 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),
+        };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 //# sourceMappingURL=candidates.js.map

package/dist/{card-detail.d.ts → store/card-detail.d.ts}

@@ -1,6 +1,6 @@
-import type { Card, CardComment, CardRun } from './card.js';
-import type { SessionHandoff } from './handoff.js';
-import { loadCardDeps } from './store-cards.js';
+import type { Card, CardComment, CardRun } from '../core/card.js';
+import type { SessionHandoff } from '../core/handoff.js';
+import { loadCardDeps } from './cards.js';
 /** A card plus everything `hippo card show` prints about it. */
 export interface CardDetail {
     card: Card;

package/dist/{card-detail.js → store/card-detail.js}

@@ -1,4 +1,4 @@
-import { loadCard, loadCardComments, loadCardDeps, loadCardRuns, loadLatestHandoffForCard } from './store-cards.js';
+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. */
 export function loadCardDetail(hippoRoot, tenantId, id) {
     const card = loadCard(hippoRoot, tenantId, id);

package/dist/{store-cards.d.ts → store/cards.d.ts}

@@ -1,11 +1,16 @@
-import { type DatabaseSyncLike } from './db.js';
-import { SessionHandoff, HandoffOutcome } from './handoff.js';
-import { Card, CardStatus, CardRun, CardComment } from './card.js';
-export declare function transitionCard(db: DatabaseSyncLike, tenantId: string, cardId: string, from: CardStatus[], to: CardStatus, extra?: {
-    setSql?: string;
-    whereSql?: string;
-    params?: unknown[];
-}): number;
+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 {
+    readonly from: CardStatus[];
+    readonly to: CardStatus;
+    readonly extra?: {
+        setSql?: string;
+        whereSql?: string;
+        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. */
 export declare function createCard(hippoRoot: string, tenantId: string, input: {
     title: string;
@@ -50,4 +55,4 @@ export declare function completeCard(hippoRoot: string, tenantId: string, id: st
 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;
-//# sourceMappingURL=store-cards.d.ts.map
+//# sourceMappingURL=cards.d.ts.map

package/dist/{store-cards.js → store/cards.js}

@@ -1,10 +1,10 @@
-import { generateId } from './memory.js';
-import { closeHippoDb } from './db.js';
-import { rowToSessionHandoff, isHandoffOutcome } from './handoff.js';
-import { CARD_TRANSITIONS, CARD_LEASE_MS } from './card.js';
+import { generateId } from '../core/memory.js';
+import { closeHippoDb, withWriteScope, withWriteScopeOr } from '../db/index.js';
+import { rowToSessionHandoff, isHandoffOutcome } from '../core/handoff.js';
+import { CARD_TRANSITIONS, CARD_LEASE_MS } from '../core/card.js';
 import { assertTenantId } from './tenant.js';
-import { openStore } from './store/open.js';
-import { HANDOFF_COLUMNS } from './store/handoffs.js';
+import { openStore } from './open.js';
+import { HANDOFF_COLUMNS } from './handoffs.js';
 const CARD_COLUMNS = 'id, title, status, assignee_runtime, repo, contract, budget, lease_until, heartbeat_at, created_at, updated_at, tenant_id, scope';
 function rowToCard(row) {
     return {
@@ -77,9 +77,8 @@ function closeLiveRun(db, tenantId, cardId, outcome, now) {
     WHERE card = ? AND tenant_id = ? AND ended IS NULL
   `).run(now, outcome, now, cardId, tenantId);
 }
-// The single status-mutating seam (rule 15): CARD_TRANSITIONS is the one
-// runtime authority, so a hand-copied wrong `from` list fails fast here.
-export function transitionCard(db, tenantId, cardId, from, to, extra) {
+export function transitionCard(db, tenantId, cardId, options) {
+    const { from, to, extra } = options;
     for (const status of from) {
         if (!CARD_TRANSITIONS[status].includes(to)) {
             throw new Error(`illegal card transition: ${status} -> ${to}`);
@@ -110,24 +109,10 @@ export function createCard(hippoRoot, tenantId, input) {
     try {
         const dependsOn = [...new Set(input.dependsOn ?? [])];
         let id = '';
-        db.exec('BEGIN IMMEDIATE');
-        try {
+        withWriteScope(db, 'create_card', () => {
             // Probe runs inside the transaction (mirrors batchWriteAndDelete): a parent
             // completing between an outside-the-lock read and the INSERT would strand the child.
-            let allParentsDone = true;
-            if (dependsOn.length > 0) {
-                const placeholders = dependsOn.map(() => '?').join(', ');
-                // SAFETY: rows' shape matches the two columns named in the SELECT below.
-                const rows = db.prepare(`SELECT id, status FROM cards WHERE tenant_id = ? AND id IN (${placeholders})`).all(tenantId, ...dependsOn);
-                const found = new Map(rows.map((r) => [r.id, r.status]));
-                // Pre-check before any write: a typo'd --depends-on can never commit a card row.
-                for (const parentId of dependsOn) {
-                    if (!found.has(parentId)) {
-                        throw new Error(`unknown parent card id: ${parentId}`);
-                    }
-                }
-                allParentsDone = dependsOn.every((pid) => found.get(pid) === 'done');
-            }
+            const allParentsDone = everyParentDone(db, tenantId, dependsOn);
             id = generateId('card');
             const now = new Date().toISOString();
             const status = dependsOn.length === 0 || allParentsDone ? 'ready' : 'backlog';
@@ -140,21 +125,29 @@ export function createCard(hippoRoot, tenantId, input) {
           INSERT INTO card_deps (parent, child, tenant_id, created_at) VALUES (?, ?, ?, ?)
         `).run(parentId, id, tenantId, now);
             }
-            db.exec('COMMIT');
-        }
-        catch (error) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* commit may have already rolled back */ }
-            throw error;
-        }
+        });
         return loadCardRow(db, tenantId, id);
     }
     finally {
         closeHippoDb(db);
     }
 }
+/** Whether every dependsOn card is done, true for none; throws on an id that is no card of the tenant. Call inside the write scope. */
+function everyParentDone(db, tenantId, dependsOn) {
+    if (dependsOn.length === 0)
+        return true;
+    const placeholders = dependsOn.map(() => '?').join(', ');
+    // SAFETY: rows' shape matches the two columns named in the SELECT below.
+    const rows = db.prepare(`SELECT id, status FROM cards WHERE tenant_id = ? AND id IN (${placeholders})`).all(tenantId, ...dependsOn);
+    const found = new Map(rows.map((r) => [r.id, r.status]));
+    // Pre-check before any write: a typo'd --depends-on can never commit a card row.
+    for (const parentId of dependsOn) {
+        if (!found.has(parentId)) {
+            throw new Error(`unknown parent card id: ${parentId}`);
+        }
+    }
+    return dependsOn.every((pid) => found.get(pid) === 'done');
+}
 /** Returns the card row for id, or null if it does not exist under this tenant. */
 export function loadCard(hippoRoot, tenantId, id) {
     assertTenantId('loadCard', tenantId);
@@ -258,37 +251,26 @@ export function claimCard(hippoRoot, tenantId, id, runtime, sessionId) {
     }
     const db = openStore(hippoRoot);
     try {
-        db.exec('BEGIN IMMEDIATE');
-        let runId = 0;
-        try {
-            const changes = transitionCard(db, tenantId, id, ['ready', 'blocked'], 'running', {
-                setSql: 'assignee_runtime = ?',
-                whereSql: 'assignee_runtime IS NULL',
-                params: [runtime],
+        const runId = withWriteScopeOr(db, 'claim_card', (rollback) => {
+            const changes = transitionCard(db, tenantId, id, {
+                from: ['ready', 'blocked'],
+                to: 'running',
+                extra: { setSql: 'assignee_runtime = ?', whereSql: 'assignee_runtime IS NULL', params: [runtime] },
             });
             if (changes === 0) {
                 if (!loadCardRow(db, tenantId, id)) {
                     throw new Error(`unknown card id: ${id}`);
                 }
-                db.exec('ROLLBACK');
-                return null;
+                return rollback(null);
             }
             const now = new Date().toISOString();
             const insert = db.prepare(`
         INSERT INTO card_runs (card, runtime, session_id, started, created_at, updated_at, tenant_id)
         VALUES (?, ?, ?, ?, ?, ?, ?)
       `).run(id, runtime, sessionId ?? null, now, now, now, tenantId);
-            runId = Number(insert.lastInsertRowid ?? 0);
-            db.exec('COMMIT');
-        }
-        catch (error) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* commit may have already rolled back */ }
-            throw error;
-        }
-        return { ...loadCardRow(db, tenantId, id), runId };
+            return Number(insert.lastInsertRowid ?? 0);
+        });
+        return runId === null ? null : { ...loadCardRow(db, tenantId, id), runId };
     }
     finally {
         closeHippoDb(db);
@@ -300,29 +282,20 @@ export function heartbeatCard(hippoRoot, tenantId, id, runId) {
     assertRunId(runId);
     const db = openStore(hippoRoot);
     try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
+        const beat = withWriteScopeOr(db, 'heartbeat_card', (rollback) => {
             const card = loadCardRow(db, tenantId, id);
             if (!card) {
                 throw new Error(`unknown card id: ${id}`);
             }
             if (card.status !== 'running' || !isLiveRun(db, tenantId, id, runId)) {
-                db.exec('ROLLBACK');
-                return null;
+                return rollback(false);
             }
             const now = new Date().toISOString();
             db.prepare(`UPDATE cards SET lease_until = ?, heartbeat_at = ? WHERE id = ? AND tenant_id = ?`)
                 .run(leaseUntilFrom(now), now, id, tenantId);
-            db.exec('COMMIT');
-        }
-        catch (error) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* commit may have already rolled back */ }
-            throw error;
-        }
-        return loadCardRow(db, tenantId, id);
+            return true;
+        });
+        return beat ? loadCardRow(db, tenantId, id) : null;
     }
     finally {
         closeHippoDb(db);
@@ -338,31 +311,22 @@ export function blockCard(hippoRoot, tenantId, id, reason, runId) {
         assertRunId(runId);
     const db = openStore(hippoRoot);
     try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
+        const blocked = withWriteScopeOr(db, 'block_card', (rollback) => {
             const allowed = runId === undefined || isLiveRun(db, tenantId, id, runId);
-            const changes = allowed ? transitionCard(db, tenantId, id, ['running'], 'blocked', { setSql: 'assignee_runtime = NULL' }) : 0;
+            const changes = allowed ? transitionCard(db, tenantId, id, { from: ['running'], to: 'blocked', extra: { setSql: 'assignee_runtime = NULL' } }) : 0;
             if (changes === 0) {
                 if (!loadCardRow(db, tenantId, id)) {
                     throw new Error(`unknown card id: ${id}`);
                 }
-                db.exec('ROLLBACK');
-                return null;
+                return rollback(false);
             }
             const now = new Date().toISOString();
             // Close the interrupted run here so completeCard's ended IS NULL scope only ever matches the live run.
             closeLiveRun(db, tenantId, id, 'blocked', now);
             insertCardComment(db, tenantId, id, 'system', reason);
-            db.exec('COMMIT');
-        }
-        catch (error) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* commit may have already rolled back */ }
-            throw error;
-        }
-        return loadCardRow(db, tenantId, id);
+            return true;
+        });
+        return blocked ? loadCardRow(db, tenantId, id) : null;
     }
     finally {
         closeHippoDb(db);
@@ -375,27 +339,18 @@ export function reviewCard(hippoRoot, tenantId, id, runId) {
         assertRunId(runId);
     const db = openStore(hippoRoot);
     try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
+        const moved = withWriteScopeOr(db, 'review_card', (rollback) => {
             const allowed = runId === undefined || isLiveRun(db, tenantId, id, runId);
-            const changes = allowed ? transitionCard(db, tenantId, id, ['running'], 'review') : 0;
+            const changes = allowed ? transitionCard(db, tenantId, id, { from: ['running'], to: 'review' }) : 0;
             if (changes === 0) {
                 if (!loadCardRow(db, tenantId, id)) {
                     throw new Error(`unknown card id: ${id}`);
                 }
-                db.exec('ROLLBACK');
-                return null;
-            }
-            db.exec('COMMIT');
-        }
-        catch (error) {
-            try {
-                db.exec('ROLLBACK');
+                return rollback(false);
             }
-            catch { /* commit may have already rolled back */ }
-            throw error;
-        }
-        return loadCardRow(db, tenantId, id);
+            return true;
+        });
+        return moved ? loadCardRow(db, tenantId, id) : null;
     }
     finally {
         closeHippoDb(db);
@@ -411,64 +366,56 @@ export function completeCard(hippoRoot, tenantId, id, outcome, runId) {
         assertRunId(runId);
     const db = openStore(hippoRoot);
     try {
-        db.exec('BEGIN IMMEDIATE');
-        let promotedChildren = [];
-        try {
+        const promoted = withWriteScopeOr(db, 'complete_card', (rollback) => {
             const target = outcome === 'success' ? 'done' : 'shelved';
             const allowed = runId === undefined || isLiveRun(db, tenantId, id, runId);
-            const changes = allowed ? transitionCard(db, tenantId, id, ['review'], target) : 0;
+            const changes = allowed ? transitionCard(db, tenantId, id, { from: ['review'], to: target }) : 0;
             if (changes === 0) {
                 if (!loadCardRow(db, tenantId, id)) {
                     throw new Error(`unknown card id: ${id}`);
                 }
-                db.exec('ROLLBACK');
-                return null;
+                return rollback(null);
             }
             const now = new Date().toISOString();
             closeLiveRun(db, tenantId, id, outcome, now);
             // Not best-effort (rule 12): promotion runs in this same transaction, so a
             // card can never be `done` with an un-evaluated child.
-            if (target === 'done') {
-                // SAFETY: rows' shape matches the single `child` column named in the SELECT below.
-                const children = db.prepare(`SELECT child FROM card_deps WHERE tenant_id = ? AND parent = ?`).all(tenantId, id).map((r) => r.child);
-                for (const childId of children) {
-                    // SAFETY: row's shape matches the single `status` column named in the SELECT below.
-                    const child = db.prepare(`SELECT status FROM cards WHERE tenant_id = ? AND id = ?`).get(tenantId, childId);
-                    if (!child || child.status !== 'backlog')
-                        continue;
-                    // SAFETY: rows' shape matches the single `parent` column named in the SELECT below.
-                    const parents = db.prepare(`SELECT parent FROM card_deps WHERE tenant_id = ? AND child = ?`).all(tenantId, childId).map((r) => r.parent);
-                    const placeholders = parents.map(() => '?').join(', ');
-                    // SAFETY: row's shape matches the single `c` column named in the SELECT below.
-                    const doneCount = db.prepare(`SELECT COUNT(*) as c FROM cards WHERE tenant_id = ? AND id IN (${placeholders}) AND status = 'done'`).get(tenantId, ...parents).c;
-                    if (doneCount === parents.length) {
-                        transitionCard(db, tenantId, childId, ['backlog'], 'ready');
-                        promotedChildren.push(childId);
-                    }
-                }
-            }
-            db.exec('COMMIT');
-        }
-        catch (error) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* commit may have already rolled back */ }
-            throw error;
-        }
-        return { card: loadCardRow(db, tenantId, id), promotedChildren };
+            return target === 'done' ? promoteUnblockedChildren(db, tenantId, id) : [];
+        });
+        return promoted === null ? null : { card: loadCardRow(db, tenantId, id), promotedChildren: promoted };
     }
     finally {
         closeHippoDb(db);
     }
 }
+/** Moves to ready each backlog child of `parentId` whose parents are all done, and returns their ids. Call inside the write scope. */
+function promoteUnblockedChildren(db, tenantId, parentId) {
+    const promotedChildren = [];
+    // SAFETY: rows' shape matches the single `child` column named in the SELECT below.
+    const children = db.prepare(`SELECT child FROM card_deps WHERE tenant_id = ? AND parent = ?`).all(tenantId, parentId).map((r) => r.child);
+    for (const childId of children) {
+        // SAFETY: row's shape matches the single `status` column named in the SELECT below.
+        const child = db.prepare(`SELECT status FROM cards WHERE tenant_id = ? AND id = ?`).get(tenantId, childId);
+        if (!child || child.status !== 'backlog')
+            continue;
+        // SAFETY: rows' shape matches the single `parent` column named in the SELECT below.
+        const parents = db.prepare(`SELECT parent FROM card_deps WHERE tenant_id = ? AND child = ?`).all(tenantId, childId).map((r) => r.parent);
+        const placeholders = parents.map(() => '?').join(', ');
+        // SAFETY: row's shape matches the single `c` column named in the SELECT below.
+        const doneCount = db.prepare(`SELECT COUNT(*) as c FROM cards WHERE tenant_id = ? AND id IN (${placeholders}) AND status = 'done'`).get(tenantId, ...parents).c;
+        if (doneCount === parents.length) {
+            transitionCard(db, tenantId, childId, { from: ['backlog'], to: 'ready' });
+            promotedChildren.push(childId);
+        }
+    }
+    return promotedChildren;
+}
 /** 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 function reclaimExpiredCards(hippoRoot, tenantId) {
     assertTenantId('reclaimExpiredCards', tenantId);
     const db = openStore(hippoRoot);
     try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
+        return withWriteScope(db, 'reclaim_expired_cards', () => {
             // Read lease times under the write lock, so a heartbeat that committed while we waited wins.
             const now = new Date().toISOString();
             // SAFETY: rows' shape matches the single `id` column named in the SELECT below.
@@ -478,19 +425,11 @@ export function reclaimExpiredCards(hippoRoot, tenantId) {
         ORDER BY id
       `).all(tenantId, now).map((r) => r.id);
             for (const id of ids) {
-                transitionCard(db, tenantId, id, ['running'], 'ready', { setSql: 'assignee_runtime = NULL' });
+                transitionCard(db, tenantId, id, { from: ['running'], to: 'ready', extra: { setSql: 'assignee_runtime = NULL' } });
                 closeLiveRun(db, tenantId, id, 'reclaimed', now);
             }
-            db.exec('COMMIT');
             return ids;
-        }
-        catch (error) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* commit may have already rolled back */ }
-            throw error;
-        }
+        });
     }
     finally {
         closeHippoDb(db);
@@ -510,4 +449,4 @@ export function addCardComment(hippoRoot, tenantId, cardId, author, body) {
         closeHippoDb(db);
     }
 }
-//# sourceMappingURL=store-cards.js.map
+//# sourceMappingURL=cards.js.map