hippo-memory 1.56.0 → 1.58.0

package/dist/store.js

@@ -6,15 +6,16 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { Layer, generateId, AUTO_DELETABLE_SQL, DEFAULT_HALF_LIFE_DAYS } from './memory.js';
+import { Layer, AUTO_DELETABLE_SQL, DEFAULT_HALF_LIFE_DAYS, markRetrieved } from './memory.js';
 import { dumpFrontmatter, parseFrontmatter } from './yaml.js';
 import { openHippoDb, closeHippoDb, getMeta, setMeta, isFtsAvailable, pruneConsolidationRuns, getHippoDbPath, } from './db.js';
 import { rowToSessionHandoff, isHandoffOutcome } from './handoff.js';
-import { CARD_TRANSITIONS, CARD_LEASE_MS } from './card.js';
-import { tokenize, markRetrieved } from './search.js';
+import { tokenize } from './tokenize.js';
+import { RECALL_DEFAULT_DENY_SCOPES } from './recall-scope.js';
+import { assertTenantId } from './tenant.js';
 import { isRecallBoostAblated } from './ablation.js';
 import { rarestPromptTerms, RAREST_TERM_COUNT } from './prompt-recall.js';
-import { appendAuditEvent } from './audit.js';
+import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
 import { resolveTenantId } from './tenant.js';
 import { redactSecretsStrict } from './secret-detect.js';
 import { deriveOriginProject, originFromSource, findHippoStoreDir, realpathOrResolve } from './project-identity.js';
@@ -41,9 +42,9 @@ function audit(db, op, targetId, metadata, actor = 'cli', tenantId) {
             metadata,
         });
     }
-    catch {
-        // Audit must never crash a mutation. Failures here mean the audit_log
-        // table is broken; the mutation has already succeeded.
+    catch (error) {
+        // The mutation has already succeeded; a broken audit table must not undo it.
+        reportAuditWriteFailure(op, String(error), targetId);
     }
 }
 /**
@@ -70,33 +71,6 @@ const MEMORY_SEARCH_COLUMNS = `m.id AS id, m.created AS created, m.last_retrieve
  * this for `RecallResult.windowSize` reporting so the two cannot drift.
  */
 export const DEFAULT_SEARCH_CANDIDATE_LIMIT = 200;
-/**
- * v1.7.2 — literal scopes excluded from recall by default-deny when the
- * caller passes no `scope`. The SQL clause in `loadSearchRows` and the JS
- * helper `passesScopeFilterForRecall` (src/api.ts) both read from this
- * constant. Adding a deny scope is a one-place change.
- *
- * Regex-based denies (e.g. `<source>:private:*`) stay in
- * `passesScopeFilterForRecall` as a separate JS step — they don't translate
- * cleanly to SQL.
- *
- * Invariant: never empty. An empty array would silently allow quarantine
- * scopes through both paths (SQL clause omitted, JS check vacuous). The
- * module-load assertion below pins this loudly.
- */
-export const RECALL_DEFAULT_DENY_SCOPES = ['unknown:legacy'];
-/**
- * @internal v1.7.3 — runtime guard against a future maintainer blanking a
- * load-bearing literal array. Extracted from the inline guard so the throw
- * path is directly testable. `as const` arrays widen via `readonly T[]` at
- * the call site so the empty case is reachable at runtime.
- */
-export function assertNonEmpty(arr, name) {
-    if (arr.length === 0) {
-        throw new Error(`${name} cannot be empty — would silently allow quarantine scopes`);
-    }
-}
-assertNonEmpty(RECALL_DEFAULT_DENY_SCOPES, 'RECALL_DEFAULT_DENY_SCOPES');
 function layerDir(root, layer) {
     return path.join(root, layer);
 }
@@ -2167,32 +2141,6 @@ export function incrementSleepCount(hippoRoot) {
         closeHippoDb(db);
     }
 }
-/**
- * Defensive runtime guard for tenant id arguments.
- *
- * The continuity helpers (saveActiveTaskSnapshot, listSessionEvents, etc.)
- * gained a required `tenantId` parameter in v0.41 / schema v22 to close a
- * cross-tenant data leak. TypeScript catches misbinding at compile time, but
- * JavaScript callers from older versions can silently pass a `sessionId`
- * where `tenantId` is now expected, e.g.
- *   loadLatestHandoff(root, 'sess-abc')   // WRONG: 'sess-abc' becomes the tenant
- * which would silently filter to a non-existent tenant and return null with
- * no error. This guard rejects the most common shape of that mistake (any
- * value beginning with the conventional `sess-` / `sess_` session prefix).
- *
- * False-positive cost: a tenant literally named `sess-...` will be rejected.
- * Acceptable tradeoff for catching the silent-leak class.
- */
-export function assertTenantId(fnName, value) {
-    if (typeof value !== 'string' || value.length === 0) {
-        throw new Error(`${fnName}: tenantId is required (got ${typeof value})`);
-    }
-    if (/^sess[-_]/i.test(value)) {
-        throw new Error(`${fnName}: tenantId looks like a session id ('${value}'). ` +
-            `In v0.41+ these helpers take (hippoRoot, tenantId, ...). ` +
-            `Pass the tenant id (e.g. 'default') and the session id separately.`);
-    }
-}
 export function saveActiveTaskSnapshot(hippoRoot, tenantId, snapshot) {
     assertTenantId('saveActiveTaskSnapshot', tenantId);
     const db = openStore(hippoRoot);
@@ -2849,7 +2797,8 @@ export function resolveConflict(hippoRoot, conflictId, keepId, forgetLoser = fal
 }
 // W1: the nine-column SELECT was cloned four times (plan rule 8); one
 // definition so a sixth caller can't drift from the other five.
-const HANDOFF_COLUMNS = 'id, session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, created_at, constraints_json, evidence_json, outcome, target_runtime, card_id';
+/** Column list shared by every session_handoffs SELECT; store-cards.ts reuses it for the card handoff lookup. */
+export const HANDOFF_COLUMNS = 'id, session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, created_at, constraints_json, evidence_json, outcome, target_runtime, card_id';
 /**
  * Save a session handoff record. Returns the persisted handoff.
  */
@@ -3023,511 +2972,6 @@ export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence,
         cardId: carryForward ? existing.cardId : undefined,
     });
 }
-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 {
-        id: row.id,
-        title: row.title,
-        status: row.status,
-        assigneeRuntime: row.assignee_runtime,
-        repo: row.repo,
-        contract: row.contract,
-        budget: row.budget,
-        leaseUntil: row.lease_until,
-        heartbeatAt: row.heartbeat_at,
-        createdAt: row.created_at,
-        updatedAt: row.updated_at,
-        tenantId: row.tenant_id,
-        scope: row.scope,
-    };
-}
-function loadCardRow(db, tenantId, id) {
-    // SAFETY: row's shape matches CARD_COLUMNS; status only ever holds a CardStatus value.
-    const row = db.prepare(`SELECT ${CARD_COLUMNS} FROM cards WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
-    return row ? rowToCard(row) : null;
-}
-function rowToCardRun(row) {
-    return {
-        id: row.id,
-        card: row.card,
-        runtime: row.runtime,
-        sessionId: row.session_id,
-        started: row.started,
-        ended: row.ended,
-        outcome: row.outcome,
-    };
-}
-function rowToCardComment(row) {
-    return { id: row.id, cardId: row.card_id, author: row.author, body: row.body, createdAt: row.created_at };
-}
-function insertCardComment(db, tenantId, cardId, author, body) {
-    const now = new Date().toISOString();
-    const result = db.prepare(`
-    INSERT INTO card_comments (card_id, author, body, created_at, tenant_id)
-    SELECT ?, ?, ?, ?, ? WHERE EXISTS (SELECT 1 FROM cards WHERE id = ? AND tenant_id = ?)
-  `).run(cardId, author, body, now, tenantId, cardId, tenantId);
-    if (Number(result.changes ?? 0) === 0) {
-        throw new Error(`unknown card id: ${cardId}`);
-    }
-    const id = Number(result.lastInsertRowid ?? 0);
-    return { id, cardId, author, body, createdAt: now };
-}
-function leaseUntilFrom(now) {
-    return new Date(Date.parse(now) + CARD_LEASE_MS).toISOString();
-}
-function assertRunId(runId) {
-    if (!Number.isSafeInteger(runId) || runId <= 0) {
-        throw new Error(`Invalid run id: ${runId} (expected a positive integer)`);
-    }
-}
-// A second run that has not ended means a corrupt store; throw rather than guess which run the caller means.
-function isLiveRun(db, tenantId, cardId, runId) {
-    // SAFETY: rows' shape matches the single `id` column named in the SELECT below.
-    const rows = db.prepare(`SELECT id FROM card_runs WHERE tenant_id = ? AND card = ? AND ended IS NULL`).all(tenantId, cardId);
-    if (rows.length > 1) {
-        throw new Error(`card ${cardId} has ${rows.length} runs that have not ended`);
-    }
-    return rows[0]?.id === runId;
-}
-function closeLiveRun(db, tenantId, cardId, outcome, now) {
-    db.prepare(`
-    UPDATE card_runs SET ended = ?, outcome = ?, updated_at = ?
-    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) {
-    for (const status of from) {
-        if (!CARD_TRANSITIONS[status].includes(to)) {
-            throw new Error(`illegal card transition: ${status} -> ${to}`);
-        }
-    }
-    const now = new Date().toISOString();
-    // Lease columns follow status: set on the move to running, cleared on every other move (rule 15).
-    const lease = to === 'running' ? [leaseUntilFrom(now), now] : [null, null];
-    const fromPlaceholders = from.map(() => '?').join(', ');
-    const sql = `
-    UPDATE cards SET status = ?, updated_at = ?, lease_until = ?, heartbeat_at = ?${extra?.setSql ? `, ${extra.setSql}` : ''}
-    WHERE id = ? AND tenant_id = ? AND status IN (${fromPlaceholders})${extra?.whereSql ? ` AND ${extra.whereSql}` : ''}
-  `;
-    const params = [to, now, ...lease, ...(extra?.params ?? []), cardId, tenantId, ...from];
-    const result = db.prepare(sql).run(...params);
-    return Number(result.changes ?? 0);
-}
-/** 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 function createCard(hippoRoot, tenantId, input) {
-    assertTenantId('createCard', tenantId);
-    if (input.title.trim() === '') {
-        throw new Error('title must not be empty');
-    }
-    if (input.budget !== undefined && !(Number.isSafeInteger(input.budget) && input.budget > 0)) {
-        throw new Error(`Invalid budget: ${input.budget} (expected a positive integer)`);
-    }
-    const db = openStore(hippoRoot);
-    try {
-        const dependsOn = [...new Set(input.dependsOn ?? [])];
-        let id = '';
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            // 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');
-            }
-            id = generateId('card');
-            const now = new Date().toISOString();
-            const status = dependsOn.length === 0 || allParentsDone ? 'ready' : 'backlog';
-            db.prepare(`
-        INSERT INTO cards (id, title, status, repo, contract, budget, created_at, updated_at, tenant_id)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `).run(id, input.title, status, input.repo ?? null, input.contract ?? null, input.budget ?? null, now, now, tenantId);
-            for (const parentId of dependsOn) {
-                db.prepare(`
-          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);
-    }
-}
-/** 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);
-    const db = openStore(hippoRoot);
-    try {
-        return loadCardRow(db, tenantId, id);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/** Lists cards for this tenant, optionally filtered to one status, newest-updated first. */
-export function listCards(hippoRoot, tenantId, opts = {}) {
-    assertTenantId('listCards', tenantId);
-    const db = openStore(hippoRoot);
-    try {
-        const conditions = ['tenant_id = ?'];
-        const params = [tenantId];
-        if (opts.status) {
-            conditions.push('status = ?');
-            params.push(opts.status);
-        }
-        // SAFETY: rows' shape matches CARD_COLUMNS; status only ever holds a CardStatus value.
-        const rows = db.prepare(`
-      SELECT ${CARD_COLUMNS} FROM cards WHERE ${conditions.join(' AND ')} ORDER BY updated_at DESC, id DESC
-    `).all(...params);
-        return rows.map(rowToCard);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/** Returns this card's parent and child ids from card_deps. */
-export function loadCardDeps(hippoRoot, tenantId, id) {
-    assertTenantId('loadCardDeps', tenantId);
-    const db = openStore(hippoRoot);
-    try {
-        // 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, id).map((r) => r.parent);
-        // 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);
-        return { parents, children };
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/** Returns this card's run history, most recent first. */
-export function loadCardRuns(hippoRoot, tenantId, id) {
-    assertTenantId('loadCardRuns', tenantId);
-    const db = openStore(hippoRoot);
-    try {
-        // SAFETY: rows' shape matches CardRunRow.
-        const rows = db.prepare(`
-      SELECT id, card, runtime, session_id, started, ended, outcome
-      FROM card_runs WHERE tenant_id = ? AND card = ? ORDER BY started DESC, id DESC
-    `).all(tenantId, id);
-        return rows.map(rowToCardRun);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/** Returns this card's comments, most recent first. */
-export function loadCardComments(hippoRoot, tenantId, id) {
-    assertTenantId('loadCardComments', tenantId);
-    const db = openStore(hippoRoot);
-    try {
-        // SAFETY: rows' shape matches CardCommentRow.
-        const rows = db.prepare(`
-      SELECT id, card_id, author, body, created_at
-      FROM card_comments WHERE tenant_id = ? AND card_id = ? ORDER BY created_at DESC, id DESC
-    `).all(tenantId, id);
-        return rows.map(rowToCardComment);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/** Read side of the card <-> handoff round trip: the newest handoff filed against this card. */
-export function loadLatestHandoffForCard(hippoRoot, tenantId, cardId) {
-    assertTenantId('loadLatestHandoffForCard', tenantId);
-    const db = openStore(hippoRoot);
-    try {
-        // SAFETY: row's shape matches HANDOFF_COLUMNS.
-        const row = db.prepare(`
-      SELECT ${HANDOFF_COLUMNS} FROM session_handoffs
-      WHERE tenant_id = ? AND card_id = ? ORDER BY created_at DESC, id DESC LIMIT 1
-    `).get(tenantId, cardId);
-        return row ? rowToSessionHandoff(row) : null;
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/** 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 function claimCard(hippoRoot, tenantId, id, runtime, sessionId) {
-    assertTenantId('claimCard', tenantId);
-    if (runtime.trim() === '') {
-        throw new Error('runtime must not be empty');
-    }
-    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],
-            });
-            if (changes === 0) {
-                if (!loadCardRow(db, tenantId, id)) {
-                    throw new Error(`unknown card id: ${id}`);
-                }
-                db.exec('ROLLBACK');
-                return 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 };
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/** 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 function heartbeatCard(hippoRoot, tenantId, id, runId) {
-    assertTenantId('heartbeatCard', tenantId);
-    assertRunId(runId);
-    const db = openStore(hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            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;
-            }
-            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);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/** 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 function blockCard(hippoRoot, tenantId, id, reason, runId) {
-    assertTenantId('blockCard', tenantId);
-    if (reason.trim() === '') {
-        throw new Error('reason must not be empty');
-    }
-    if (runId !== undefined)
-        assertRunId(runId);
-    const db = openStore(hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            const allowed = runId === undefined || isLiveRun(db, tenantId, id, runId);
-            const changes = allowed ? transitionCard(db, tenantId, id, ['running'], 'blocked', { 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;
-            }
-            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);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/** 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 function reviewCard(hippoRoot, tenantId, id, runId) {
-    assertTenantId('reviewCard', tenantId);
-    if (runId !== undefined)
-        assertRunId(runId);
-    const db = openStore(hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            const allowed = runId === undefined || isLiveRun(db, tenantId, id, runId);
-            const changes = allowed ? transitionCard(db, tenantId, id, ['running'], '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');
-            }
-            catch { /* commit may have already rolled back */ }
-            throw error;
-        }
-        return loadCardRow(db, tenantId, id);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/** 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. */
-export function completeCard(hippoRoot, tenantId, id, outcome, runId) {
-    assertTenantId('completeCard', tenantId);
-    if (!isHandoffOutcome(outcome)) {
-        throw new Error(`invalid card outcome: ${String(outcome)}`);
-    }
-    if (runId !== undefined)
-        assertRunId(runId);
-    const db = openStore(hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        let promotedChildren = [];
-        try {
-            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;
-            if (changes === 0) {
-                if (!loadCardRow(db, tenantId, id)) {
-                    throw new Error(`unknown card id: ${id}`);
-                }
-                db.exec('ROLLBACK');
-                return 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 };
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/** 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 {
-            // 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.
-            const ids = db.prepare(`
-        SELECT id FROM cards
-        WHERE tenant_id = ? AND status = 'running' AND (lease_until IS NULL OR lease_until < ?)
-        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' });
-                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);
-    }
-}
-/** Appends a comment to cardId in any card status; throws if cardId is not a card of this tenant. */
-export function addCardComment(hippoRoot, tenantId, cardId, author, body) {
-    assertTenantId('addCardComment', tenantId);
-    if (body.trim() === '') {
-        throw new Error('body must not be empty');
-    }
-    const db = openStore(hippoRoot);
-    try {
-        return insertCardComment(db, tenantId, cardId, author, body);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
 // ---------------------------------------------------------------------------
 // v0.30 / E1 of DAG live-coupling — dirty-flag helpers for the existing
 // DAG layer's level-2 summaries.

package/dist/tenant.d.ts

@@ -4,4 +4,26 @@ export interface ResolveOpts {
     apiKey?: string;
 }
 export declare function resolveTenantId(opts: ResolveOpts): string;
+/** A value that round-trips through JSON.stringify/JSON.parse unchanged. */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Defensive runtime guard for tenant id arguments.
+ *
+ * The continuity helpers (saveActiveTaskSnapshot, listSessionEvents, etc.)
+ * gained a required `tenantId` parameter (schema v22) to close a
+ * cross-tenant data leak. TypeScript catches misbinding at compile time, but
+ * JavaScript callers from older versions can silently pass a `sessionId`
+ * where `tenantId` is now expected, e.g.
+ *   loadLatestHandoff(root, 'sess-abc')   // WRONG: 'sess-abc' becomes the tenant
+ * which would silently filter to a non-existent tenant and return null with
+ * no error. This guard rejects the most common shape of that mistake (any
+ * value beginning with the conventional `sess-` / `sess_` session prefix).
+ *
+ * False-positive cost: a tenant literally named `sess-...` will be rejected.
+ * Acceptable tradeoff for catching the silent-leak class.
+ */
+export declare function assertTenantId(fnName: string, value: JsonValue): asserts value is string;
+export {};
 //# sourceMappingURL=tenant.d.ts.map

package/dist/tenant.js

@@ -14,4 +14,30 @@ export function resolveTenantId(opts) {
     const t = process.env.HIPPO_TENANT?.trim();
     return t ? t : 'default';
 }
+/**
+ * Defensive runtime guard for tenant id arguments.
+ *
+ * The continuity helpers (saveActiveTaskSnapshot, listSessionEvents, etc.)
+ * gained a required `tenantId` parameter (schema v22) to close a
+ * cross-tenant data leak. TypeScript catches misbinding at compile time, but
+ * JavaScript callers from older versions can silently pass a `sessionId`
+ * where `tenantId` is now expected, e.g.
+ *   loadLatestHandoff(root, 'sess-abc')   // WRONG: 'sess-abc' becomes the tenant
+ * which would silently filter to a non-existent tenant and return null with
+ * no error. This guard rejects the most common shape of that mistake (any
+ * value beginning with the conventional `sess-` / `sess_` session prefix).
+ *
+ * False-positive cost: a tenant literally named `sess-...` will be rejected.
+ * Acceptable tradeoff for catching the silent-leak class.
+ */
+export function assertTenantId(fnName, value) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`${fnName}: tenantId is required (got ${typeof value})`);
+    }
+    if (/^sess[-_]/i.test(value)) {
+        throw new Error(`${fnName}: tenantId looks like a session id ('${value}'). ` +
+            `In v0.41+ these helpers take (hippoRoot, tenantId, ...). ` +
+            `Pass the tenant id (e.g. 'default') and the session id separately.`);
+    }
+}
 //# sourceMappingURL=tenant.js.map