hippo-memory 1.68.0 → 1.70.0

package/dist/store/entry-writes.d.ts

@@ -1,5 +1,5 @@
-import { type MemoryEntry } from '../memory.js';
-import { type DatabaseSyncLike } from '../db.js';
+import { type MemoryEntry } from '../core/memory.js';
+import { type DatabaseSyncLike } from '../db/index.js';
 export interface WriteEntryOptions {
     actor?: string;
     afterWrite?: (db: DatabaseSyncLike, memoryId: string) => void;
@@ -7,8 +7,12 @@ export interface WriteEntryOptions {
     afterCommit?: () => void;
 }
 export declare function writeEntry(hippoRoot: string, entry: MemoryEntry, opts?: WriteEntryOptions): void;
-/** writeEntry on the caller's open store, so a loop of writes opens the store once; each row still commits alone. */
-export declare function writeEntryOn(db: DatabaseSyncLike, hippoRoot: string, entry: MemoryEntry, opts?: WriteEntryOptions): void;
+/** writeEntry for each of `entries` in one transaction, so all land or none; each keeps its audit row, and mirrors follow the commit. Returns how many were written. */
+export declare function writeEntriesTogether(hippoRoot: string, entries: readonly MemoryEntry[]): number;
+/** writeEntry for each of `entries` on one open store, so the open and its lock wait are paid once; each row commits alone, and none opens the store when the list is empty. */
+export declare function writeEntriesSeparately(hippoRoot: string, entries: readonly MemoryEntry[]): void;
+/** Adds `tag` to each of a tenant's rows that lacks it, in `ids` order, each read fresh on one open store and committed alone; an id the tenant does not hold is skipped. */
+export declare function addTagToEntries(hippoRoot: string, tenantId: string, ids: readonly string[], tag: string): void;
 /**
  * DB-only write path. Caller owns the open `db` handle. Runs upsert +
  * afterWrite hook + audit row inside one withWriteScope. Caller
@@ -26,6 +30,8 @@ export declare function writeEntryDbOnly(db: DatabaseSyncLike, entry: MemoryEntr
     actor?: string;
     afterWrite?: (db: DatabaseSyncLike, memoryId: string) => void;
 }): void;
+/** What follows a row's upsert inside its write scope: the remember row, last of the write's audit rows, then the summary parent's dirty mark. */
+export declare function auditEntryWrite(db: DatabaseSyncLike, entry: MemoryEntry, actor: string): void;
 /** Markdown mirror path, invoked AFTER commit (a rolled-back tx must leave no orphan markdown). */
 export declare function writeEntryMirrors(hippoRoot: string, entry: MemoryEntry): void;
 /** The caller passes the eval-only recall-boost ablation switch, so the store never reads experiment config itself. */
@@ -44,4 +50,27 @@ export declare function strengthenRetrievedOn(db: DatabaseSyncLike, ids: readonl
 export declare function setEntryTagsInTx(db: DatabaseSyncLike, entry: MemoryEntry): void;
 /** Removes a row from `memories` and full-text search on the caller's transaction, as sleep's dormant move does, and marks its summary parent dirty. */
 export declare function deleteEntryRowInTx(db: DatabaseSyncLike, entry: MemoryEntry, actor: string): void;
+/** One half-life per memory id, on the caller's transaction. */
+export declare function setHalfLivesAt(db: DatabaseSyncLike, rows: readonly {
+    id: string;
+    halfLifeDays: number;
+}[]): void;
+/** Moves every row of `from` in a tenant to project `into`. */
+export declare function restampOriginProjectAt(db: DatabaseSyncLike, tenantId: string, from: string, into: string): void;
+/** Stamps each id with its project. */
+export declare function stampOriginProjectsAt(db: DatabaseSyncLike, tenantId: string, rows: readonly {
+    id: string;
+    origin: string;
+}[]): void;
+/** Renames a live row's source from `from` to `to`; the count is 0 when another writer moved or superseded it first. */
+export declare function renameEntrySourceAt(db: DatabaseSyncLike, tenantId: string, id: string, from: string, to: string): number;
+export interface RenameSourceOptions {
+    readonly from: string;
+    readonly to: string;
+    readonly origin: string | null;
+}
+/** Renames a row's source and, when `origin` is not null, its project; the count is 0 when the row is gone or moved. */
+export declare function renameEntrySourceAndOriginAt(db: DatabaseSyncLike, tenantId: string, id: string, options: RenameSourceOptions): number;
+/** Marks `id` superseded by `newId`; false when another writer superseded it first. */
+export declare function supersedeEntryAt(db: DatabaseSyncLike, tenantId: string, id: string, newId: string): boolean;
 //# sourceMappingURL=entry-writes.d.ts.map

package/dist/store/entry-writes.js

@@ -1,10 +1,10 @@
-import { markRetrieved } from '../memory.js';
-import { closeHippoDb, openHippoDb, rethrowIfSqliteBlocked, withWriteScope } from '../db.js';
-import { RejectedValueError } from '../rejection.js';
-import { markSummaryDirtyInTx } from '../summary-dirty.js';
-import { log } from '../log.js';
-import { MEMORY_SELECT_COLUMNS, rowToEntry } from './rows.js';
+import { markRetrieved } from '../core/memory.js';
+import { closeHippoDb, openHippoDb, rethrowIfSqliteBlocked, withWriteScope } from '../db/index.js';
+import { RejectedValueError } from './rejection.js';
+import { markSummaryDirtyInTx } from './summary-dirty.js';
+import { errorMessage, log } from '../util/log.js';
 import { auditRejectionRefusal, audit } from './audit-event.js';
+import { selectEntriesByIds } from './entry-reads.js';
 import { stampOriginProject, upsertEntryRow, syncFtsRow, deleteFtsRow } from './entry-row.js';
 import { mirrorBestEffort, writeMarkdownMirror } from './mirrors.js';
 import { openStore } from './open.js';
@@ -17,8 +17,60 @@ export function writeEntry(hippoRoot, entry, opts) {
         closeHippoDb(db);
     }
 }
+/** writeEntry for each of `entries` in one transaction, so all land or none; each keeps its audit row, and mirrors follow the commit. Returns how many were written. */
+export function writeEntriesTogether(hippoRoot, entries) {
+    const stamped = entries.map((entry) => stampOriginProject(hippoRoot, entry));
+    const db = openStore(hippoRoot);
+    try {
+        withWriteScope(db, 'write_entries_together', () => {
+            for (const entry of stamped)
+                writeEntryDbOnly(db, entry);
+        });
+        for (const entry of stamped)
+            writeEntryMirrors(hippoRoot, entry);
+    }
+    catch (error) {
+        // The scope has unwound, so the refusal row outlives the rollback, as writeEntryOn's does.
+        if (error instanceof RejectedValueError)
+            auditRejectionRefusal(db, error, 'cli');
+        throw error;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    return stamped.length;
+}
+/** writeEntry for each of `entries` on one open store, so the open and its lock wait are paid once; each row commits alone, and none opens the store when the list is empty. */
+export function writeEntriesSeparately(hippoRoot, entries) {
+    if (entries.length === 0)
+        return;
+    const db = openStore(hippoRoot);
+    try {
+        for (const entry of entries)
+            writeEntryOn(db, hippoRoot, entry);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Adds `tag` to each of a tenant's rows that lacks it, in `ids` order, each read fresh on one open store and committed alone; an id the tenant does not hold is skipped. */
+export function addTagToEntries(hippoRoot, tenantId, ids, tag) {
+    const db = openStore(hippoRoot);
+    try {
+        const live = selectEntriesByIds(db, ids, tenantId);
+        for (const id of new Set(ids)) {
+            const entry = live.get(id);
+            if (!entry || entry.tags.includes(tag))
+                continue;
+            writeEntryOn(db, hippoRoot, { ...entry, tags: [...entry.tags, tag] });
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 /** writeEntry on the caller's open store, so a loop of writes opens the store once; each row still commits alone. */
-export function writeEntryOn(db, hippoRoot, entry, opts) {
+function writeEntryOn(db, hippoRoot, entry, opts) {
     try {
         const stamped = stampOriginProject(hippoRoot, entry);
         writeEntryDbOnly(db, stamped, opts);
@@ -55,16 +107,20 @@ export function writeEntryDbOnly(db, entry, opts) {
         if (opts?.afterWrite) {
             opts.afterWrite(db, entry.id);
         }
-        audit(db, 'remember', entry.id, {
+        auditEntryWrite(db, entry, opts?.actor ?? 'cli');
+    });
+}
+/** What follows a row's upsert inside its write scope: the remember row, last of the write's audit rows, then the summary parent's dirty mark. */
+export function auditEntryWrite(db, entry, actor) {
+    audit(db, 'remember', { targetId: entry.id, metadata: {
             kind: entry.kind ?? 'distilled',
             scope: entry.scope ?? null,
-        }, opts?.actor ?? 'cli', entry.tenantId);
-        // A child write marks its summary parent dirty for the sleep-cycle rebuild; most writes
-        // have no parent, so the hot path pays one null check.
-        if (entry.dag_parent_id) {
-            markSummaryDirtyInTx(db, entry.dag_parent_id, entry.tenantId, opts?.actor ?? 'cli');
-        }
-    });
+        }, actor, tenantId: entry.tenantId });
+    // A child write marks its summary parent dirty for the sleep-cycle rebuild; most writes
+    // have no parent, so the hot path pays one null check.
+    if (entry.dag_parent_id) {
+        markSummaryDirtyInTx(db, entry.dag_parent_id, entry.tenantId, actor);
+    }
 }
 /** Markdown mirror path, invoked AFTER commit (a rolled-back tx must leave no orphan markdown). */
 export function writeEntryMirrors(hippoRoot, entry) {
@@ -104,23 +160,15 @@ export function strengthenRetrievedInOwnTx(db, ids, opts) {
     }
 }
 function warnStrengthenFailed(error) {
-    log.warn(`retrieval stats not saved (${error instanceof Error ? error.message : String(error)})`);
+    log.warn(`retrieval stats not saved (${errorMessage(error)})`);
 }
 /** strengthenRetrieved on the caller's handle, inside the caller's transaction. Throws; the caller decides. */
 export function strengthenRetrievedOn(db, ids, opts) {
     const found = new Set();
     if (ids.length === 0 || opts.recallBoostAblated)
         return found;
-    const { tenantId } = opts;
-    const tenantClause = tenantId !== undefined ? ' AND tenant_id = ?' : '';
-    const select = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id = ?${tenantClause}`);
-    const live = [];
-    for (const id of ids) {
-        // SAFETY: the SELECT names exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
-        const row = (tenantId !== undefined ? select.get(id, tenantId) : select.get(id));
-        if (row)
-            live.push(rowToEntry(row));
-    }
+    const byId = selectEntriesByIds(db, ids, opts.tenantId);
+    const live = [...new Set(ids)].flatMap((id) => byId.get(id) ?? []);
     const update = db.prepare('UPDATE memories SET retrieval_count = ?, last_retrieved = ?, half_life_days = ?, strength = ? WHERE id = ?');
     for (const e of markRetrieved(live)) {
         update.run(e.retrieval_count, e.last_retrieved, e.half_life_days, e.strength, e.id);
@@ -141,4 +189,38 @@ export function deleteEntryRowInTx(db, entry, actor) {
     if (entry.dag_parent_id)
         markSummaryDirtyInTx(db, entry.dag_parent_id, entry.tenantId, actor);
 }
+/** One half-life per memory id, on the caller's transaction. */
+export function setHalfLivesAt(db, rows) {
+    const update = db.prepare('UPDATE memories SET half_life_days = ? WHERE id = ?');
+    for (const r of rows)
+        update.run(r.halfLifeDays, r.id);
+}
+/** Moves every row of `from` in a tenant to project `into`. */
+export function restampOriginProjectAt(db, tenantId, from, into) {
+    db.prepare(`UPDATE memories SET origin_project = ?, updated_at = datetime('now') WHERE tenant_id = ? AND origin_project = ?`)
+        .run(into, tenantId, from);
+}
+/** Stamps each id with its project. */
+export function stampOriginProjectsAt(db, tenantId, rows) {
+    const stamp = db.prepare(`UPDATE memories SET origin_project = ?, updated_at = datetime('now') WHERE tenant_id = ? AND id = ?`);
+    for (const { id, origin } of rows)
+        stamp.run(origin, tenantId, id);
+}
+/** Renames a live row's source from `from` to `to`; the count is 0 when another writer moved or superseded it first. */
+export function renameEntrySourceAt(db, tenantId, id, from, to) {
+    const moved = db.prepare(`UPDATE memories SET source = ? WHERE id = ? AND tenant_id = ? AND source = ? AND superseded_by IS NULL`).run(to, id, tenantId, from);
+    return Number(moved.changes ?? 0);
+}
+/** Renames a row's source and, when `origin` is not null, its project; the count is 0 when the row is gone or moved. */
+export function renameEntrySourceAndOriginAt(db, tenantId, id, options) {
+    const { from, to, origin } = options;
+    const done = db.prepare(`UPDATE memories SET source = ?, origin_project = COALESCE(?, origin_project) WHERE id = ? AND tenant_id = ? AND source = ?`).run(to, origin, id, tenantId, from);
+    return Number(done.changes ?? 0);
+}
+/** Marks `id` superseded by `newId`; false when another writer superseded it first. */
+export function supersedeEntryAt(db, tenantId, id, newId) {
+    const result = db.prepare(`UPDATE memories SET superseded_by = ? WHERE id = ? AND tenant_id = ? AND superseded_by IS NULL`)
+        .run(newId, id, tenantId);
+    return Number(result.changes ?? 0) !== 0;
+}
 //# sourceMappingURL=entry-writes.js.map

package/dist/{failure-log.d.ts → store/failure-log.d.ts}

@@ -1,5 +1,8 @@
-import type { CaptureErrorOutcome, RoutineRule } from './capture/failure-reading.js';
-import type { DatabaseSyncLike } from './db.js';
+import type { DatabaseSyncLike } from '../db/index.js';
+/** Why a failure was not stored, or `stored`. */
+export type CaptureErrorOutcome = 'stored' | 'duplicate' | 'skipped-interrupt' | 'skipped-routine' | 'skipped-invalid';
+/** Which routine check skipped a failure; the log keeps it so declines can be told apart from empty searches. */
+export type RoutineRule = 'declined' | 'os-permission' | 'no-match' | 'search-tool' | 'quiet-exit';
 /** Rows older than this are pruned on write, which also bounds how far back a repeat can be found. */
 export declare const FAILURE_LOG_RETENTION_DAYS = 90;
 /** A capture-error outcome, or `store-failed` when storing the lesson threw. */
@@ -52,6 +55,8 @@ export interface FailureSummary {
     repeats: number;
     sessions: number;
 }
+/** Failed tool calls logged since `sinceIso`, in every tenant; throws when the table is missing. */
+export declare function countFailuresSince(db: DatabaseSyncLike, sinceIso: string): number;
 /** Sum the failure log for one tenant since `sinceIso`. */
 export declare function summarizeFailures(db: DatabaseSyncLike, tenantId: string, sinceIso: string): FailureSummary;
 //# sourceMappingURL=failure-log.d.ts.map

package/dist/{failure-log.js → store/failure-log.js}

@@ -1,5 +1,6 @@
 /** Failure log: every failed tool call the capture-error hook sees, stored or not. */
-import { ConflictError } from './api-errors.js';
+import { ConflictError } from '../core/api-errors.js';
+import { DAY_MS } from '../util/time.js';
 /** Rows older than this are pruned on write, which also bounds how far back a repeat can be found. */
 export const FAILURE_LOG_RETENTION_DAYS = 90;
 /** Longest session id or tool name kept; the hook payload is not trusted to be short. */
@@ -10,7 +11,7 @@ export function recordFailure(db, event) {
     const now = new Date(event.now ?? Date.now()).toISOString();
     db.prepare(`INSERT INTO failure_log (ts, tenant_id, session_id, tool, outcome, skip_rule, sig_hash, detail_hash, owner_subject, origin_project, request_id)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(now, event.tenantId, event.sessionId?.slice(0, MAX_FIELD) ?? null, event.tool?.slice(0, MAX_FIELD) ?? null, event.outcome, event.rule ?? null, event.sigHash ?? null, event.detailHash ?? null, event.ownerSubject ?? null, event.originProject ?? null, event.requestId ?? null);
-    const cutoff = new Date(Date.parse(now) - FAILURE_LOG_RETENTION_DAYS * 86_400_000).toISOString();
+    const cutoff = new Date(Date.parse(now) - FAILURE_LOG_RETENTION_DAYS * DAY_MS).toISOString();
     db.prepare(`DELETE FROM failure_log WHERE ts < ?`).run(cutoff);
 }
 /** The outcome logged for a caller's request id, or null, so a retried send finds the first one; another session's id is a ConflictError. */
@@ -49,6 +50,12 @@ export function failuresBySession(db, tenantId, sinceIso) {
     }
     return [...bySession.values()];
 }
+/** Failed tool calls logged since `sinceIso`, in every tenant; throws when the table is missing. */
+export function countFailuresSince(db, sinceIso) {
+    // SAFETY: COUNT aggregate row.
+    const row = db.prepare(`SELECT COUNT(*) AS n FROM failure_log WHERE ts >= ?`).get(sinceIso);
+    return Number(row?.n ?? 0);
+}
 /** Sum the failure log for one tenant since `sinceIso`. */
 export function summarizeFailures(db, tenantId, sinceIso) {
     // SAFETY: the SELECT names exactly these two columns, TEXT and an aggregate.

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

@@ -1,6 +1,6 @@
-import { type DatabaseSyncLike } from './db.js';
-import type { MemoryEntry } from './memory.js';
-import type { RerankStep } from './search/types.js';
+import { type DatabaseSyncLike } from '../db/index.js';
+import type { MemoryEntry } from '../core/memory.js';
+import type { RerankStep } from '../core/search-types.js';
 export type GoalStatus = 'active' | 'suspended' | 'completed';
 export type PolicyType = 'schema-fit-biased' | 'error-prioritized' | 'recency-first' | 'hybrid';
 export interface GoalRow {
@@ -40,8 +40,6 @@ export interface RetrievalPolicy {
     weightOutcome: number;
     errorPriority: number;
 }
-export declare const MAX_ACTIVE_GOAL_DEPTH = 3;
-export declare const MAX_FINAL_MULTIPLIER = 3;
 export declare function rowToGoal(row: GoalRow): Goal;
 export interface PushGoalOpts {
     sessionId: string;
@@ -59,19 +57,6 @@ export interface PushGoalOpts {
     };
 }
 export declare function pushGoal(hippoRoot: string, opts: PushGoalOpts): Goal;
-/**
- * Depth-cap enforcer shared by pushGoalWithDb and resumeGoal.
- * If the (tenant, session) has >= MAX_ACTIVE_GOAL_DEPTH active goals,
- * suspend the oldest `overflow` ones.
- *
- * **Precondition: caller MUST already be inside a `BEGIN IMMEDIATE`
- * transaction.** Helper does not open or commit -- name reflects this so it
- * is impossible to misread the contract at a call site. Both existing call
- * sites (pushGoalWithDb, resumeGoal) wrap in `BEGIN IMMEDIATE` already.
- *
- * @internal Internal goal-stack invariant. Subject to change.
- */
-export declare function enforceDepthCapWithinTx(db: DatabaseSyncLike, tenantId: string, sessionId: string): void;
 export declare function pushGoalWithDb(db: DatabaseSyncLike, opts: PushGoalOpts): Goal;
 export interface GetActiveGoalsOpts {
     sessionId: string;
@@ -87,7 +72,6 @@ export interface ActiveGoals {
 export declare function activeGoalsWithPolicies(hippoRoot: string, opts: GetActiveGoalsOpts): ActiveGoals;
 /** Every goal of a (tenant, session), whatever its status, oldest first. */
 export declare function getSessionGoals(hippoRoot: string, opts: GetActiveGoalsOpts): Goal[];
-export declare function getActiveGoalsWithDb(db: DatabaseSyncLike, opts: GetActiveGoalsOpts): Goal[];
 /** One `goal_recall_log` row: a boosted local memory recalled while its goal was active. */
 export interface GoalRecallLogRow {
     goalId: string;
@@ -97,7 +81,7 @@ export interface GoalRecallLogRow {
     recalledAt: string;
     score: number;
 }
-/** Options shared by {@link computeGoalStackBoost} and {@link boostByGoals}. */
+/** Options of {@link boostByGoals}. */
 export interface GoalStackBoostOpts {
     sessionId: string;
     tenantId: string;
@@ -114,35 +98,11 @@ export interface GoalStackBoost<R> {
     results: R[];
     log: GoalRecallLogRow[];
 }
-export declare function loadGoalPolicies(db: DatabaseSyncLike, active: readonly Goal[]): Map<string, RetrievalPolicy>;
 /** The rows whose memory lives in this store: goal_recall_log.memory_id references memories, so a global row would fail
  *  the insert. A global result keeps its boost; it only earns no log row, so no outcome propagation. */
 export declare function localGoalRecallRows(db: DatabaseSyncLike, rows: readonly GoalRecallLogRow[]): GoalRecallLogRow[];
-/**
- * dlPFC goal-stack boost. Applies the multi-goal boost to entry-backed scored
- * rows when (tenant, session) has active goals and returns the log rows to
- * write, without writing them; {@link writeGoalRecallLog} persists them.
- *
- * Caller responsibilities:
- *   - Do NOT call when an explicit `goalTag` is set (caller's gate)
- *   - Pass entry-backed rows (with `entry.tags`, `entry.id`, optional
- *     `entry.schema_fit`)
- *   - Manage the db handle lifecycle (helper neither opens nor closes)
- *   - Recompute `tokens` after if returned rows are projected to a budgeted
- *     shape
- *
- * Log rows cover the top `limit` boosted rows that live in this store's
- * `memories` table (global-only ids are skipped to keep the FK on
- * goal_recall_log.memory_id valid).
- *
- * @internal Recall ranking helper. Subject to change.
- */
-export declare function computeGoalStackBoost<R extends {
-    entry: MemoryEntry;
-    score: number;
-}>(db: DatabaseSyncLike, results: R[], opts: GoalStackBoostOpts): GoalStackBoost<R>;
-/** {@link computeGoalStackBoost} over goals already read, touching no store. Its log keeps rows whose memory is global,
- *  since only the store can tell them apart; {@link localGoalRecallRows} drops those before the write. */
+/** The goal-stack boost over goals already read, touching no store; a caller skips it under an explicit goal tag. Its log covers the top
+ *  `limit` rows and keeps those whose memory is global, since only the store can tell them apart; {@link localGoalRecallRows} drops those before the write. */
 export declare function boostByGoals<R extends {
     entry: MemoryEntry;
     score: number;

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

@@ -1,8 +1,9 @@
-// src/goals.ts
+// src/store/goals.ts
 import { randomUUID } from 'node:crypto';
-import { openHippoDb, closeHippoDb } from './db.js';
-export const MAX_ACTIVE_GOAL_DEPTH = 3;
-export const MAX_FINAL_MULTIPLIER = 3.0;
+import { openHippoDb, closeHippoDb, withWriteScope } from '../db/index.js';
+import { compareScoresDesc } from '../core/compare.js';
+const MAX_ACTIVE_GOAL_DEPTH = 3;
+const MAX_FINAL_MULTIPLIER = 3.0;
 export function rowToGoal(row) {
     return {
         id: row.id,
@@ -40,7 +41,7 @@ export function pushGoal(hippoRoot, opts) {
  *
  * @internal Internal goal-stack invariant. Subject to change.
  */
-export function enforceDepthCapWithinTx(db, tenantId, sessionId) {
+function enforceDepthCapWithinTx(db, tenantId, sessionId) {
     // SAFETY: the row comes from the SELECT above, which projects exactly one
     // column, `c`, as a COUNT(*).
     const activeCount = db.prepare(`
@@ -66,21 +67,10 @@ export function pushGoalWithDb(db, opts) {
     const id = `g_${randomUUID().replace(/-/g, '').slice(0, 16)}`;
     const createdAt = new Date().toISOString();
     let policyId = null;
-    db.exec('BEGIN IMMEDIATE');
-    try {
+    withWriteScope(db, 'push_goal', () => {
         // Depth cap: count active for (tenant, session); suspend oldest if at cap.
         enforceDepthCapWithinTx(db, opts.tenantId, opts.sessionId);
-        if (opts.parentGoalId) {
-            // SAFETY: the row comes from the SELECT above, which projects exactly
-            // the tenant_id and session_id columns of goal_stack.
-            const parent = db.prepare(`SELECT tenant_id, session_id FROM goal_stack WHERE id = ?`).get(opts.parentGoalId);
-            if (!parent) {
-                throw new Error(`parent goal not found: ${opts.parentGoalId}`);
-            }
-            if (parent.tenant_id !== opts.tenantId || parent.session_id !== opts.sessionId) {
-                throw new Error(`parent goal ${opts.parentGoalId} belongs to a different (tenant, session)`);
-            }
-        }
+        assertParentInSession(db, opts);
         // Parent goal_stack row first (FK target).
         db.prepare(`
       INSERT INTO goal_stack
@@ -90,23 +80,9 @@ export function pushGoalWithDb(db, opts) {
     `).run(id, opts.sessionId, opts.tenantId, opts.goalName, opts.level ?? 0, opts.parentGoalId ?? null, opts.successCondition ?? null, createdAt);
         // Optional policy row, then point goal_stack.retrieval_policy_id at it.
         if (opts.policy) {
-            policyId = `rp_${randomUUID().replace(/-/g, '').slice(0, 16)}`;
-            db.prepare(`
-        INSERT INTO retrieval_policy
-          (id, goal_id, policy_type, weight_schema_fit, weight_recency, weight_outcome, error_priority)
-        VALUES (?, ?, ?, ?, ?, ?, ?)
-      `).run(policyId, id, opts.policy.policyType, opts.policy.weightSchemaFit ?? 1.0, opts.policy.weightRecency ?? 1.0, opts.policy.weightOutcome ?? 1.0, opts.policy.errorPriority ?? 1.0);
-            db.prepare(`UPDATE goal_stack SET retrieval_policy_id = ? WHERE id = ?`).run(policyId, id);
-        }
-        db.exec('COMMIT');
-    }
-    catch (err) {
-        try {
-            db.exec('ROLLBACK');
+            policyId = insertRetrievalPolicy(db, id, opts.policy);
         }
-        catch { /* already rolled back; keep the original error */ }
-        throw err;
-    }
+    });
     return {
         id,
         sessionId: opts.sessionId,
@@ -120,6 +96,30 @@ export function pushGoalWithDb(db, opts) {
         createdAt,
     };
 }
+function assertParentInSession(db, opts) {
+    if (!opts.parentGoalId)
+        return;
+    // SAFETY: the row comes from the SELECT above, which projects exactly
+    // the tenant_id and session_id columns of goal_stack.
+    const parent = db.prepare(`SELECT tenant_id, session_id FROM goal_stack WHERE id = ?`).get(opts.parentGoalId);
+    if (!parent) {
+        throw new Error(`parent goal not found: ${opts.parentGoalId}`);
+    }
+    if (parent.tenant_id !== opts.tenantId || parent.session_id !== opts.sessionId) {
+        throw new Error(`parent goal ${opts.parentGoalId} belongs to a different (tenant, session)`);
+    }
+}
+/** Insert the policy row, then point goal_stack.retrieval_policy_id at it; returns the new policy id. */
+function insertRetrievalPolicy(db, goalId, policy) {
+    const policyId = `rp_${randomUUID().replace(/-/g, '').slice(0, 16)}`;
+    db.prepare(`
+    INSERT INTO retrieval_policy
+      (id, goal_id, policy_type, weight_schema_fit, weight_recency, weight_outcome, error_priority)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(policyId, goalId, policy.policyType, policy.weightSchemaFit ?? 1.0, policy.weightRecency ?? 1.0, policy.weightOutcome ?? 1.0, policy.errorPriority ?? 1.0);
+    db.prepare(`UPDATE goal_stack SET retrieval_policy_id = ? WHERE id = ?`).run(policyId, goalId);
+    return policyId;
+}
 export function getActiveGoals(hippoRoot, opts) {
     const db = openHippoDb(hippoRoot);
     try {
@@ -158,7 +158,7 @@ export function getSessionGoals(hippoRoot, opts) {
         closeHippoDb(db);
     }
 }
-export function getActiveGoalsWithDb(db, opts) {
+function getActiveGoalsWithDb(db, opts) {
     // SAFETY: rows come from the SELECT above, which projects exactly
     // GoalRow's columns (in the same order goal_stack defines them).
     const rows = db.prepare(`
@@ -174,7 +174,7 @@ export function getActiveGoalsWithDb(db, opts) {
 // can compose onto the base goal-tag boost. Composed result is hard-capped
 // at MAX_FINAL_MULTIPLIER (3.0x) BEFORE applying to score -- even an
 // `errorPriority: 9.0` policy cannot exceed 3.0x.
-export function loadGoalPolicies(db, active) {
+function loadGoalPolicies(db, active) {
     const policiesByGoalId = new Map();
     for (const g of active) {
         if (!g.retrievalPolicyId)
@@ -259,34 +259,8 @@ export function localGoalRecallRows(db, rows) {
     const localIds = new Set(local.map((r) => r.id));
     return rows.filter((r) => localIds.has(r.memoryId));
 }
-/**
- * dlPFC goal-stack boost. Applies the multi-goal boost to entry-backed scored
- * rows when (tenant, session) has active goals and returns the log rows to
- * write, without writing them; {@link writeGoalRecallLog} persists them.
- *
- * Caller responsibilities:
- *   - Do NOT call when an explicit `goalTag` is set (caller's gate)
- *   - Pass entry-backed rows (with `entry.tags`, `entry.id`, optional
- *     `entry.schema_fit`)
- *   - Manage the db handle lifecycle (helper neither opens nor closes)
- *   - Recompute `tokens` after if returned rows are projected to a budgeted
- *     shape
- *
- * Log rows cover the top `limit` boosted rows that live in this store's
- * `memories` table (global-only ids are skipped to keep the FK on
- * goal_recall_log.memory_id valid).
- *
- * @internal Recall ranking helper. Subject to change.
- */
-export function computeGoalStackBoost(db, results, opts) {
-    const goals = getActiveGoalsWithDb(db, { sessionId: opts.sessionId, tenantId: opts.tenantId });
-    if (goals.length === 0)
-        return { results, log: [] };
-    const boost = boostByGoals(results, { goals, policies: loadGoalPolicies(db, goals) }, opts);
-    return { results: boost.results, log: localGoalRecallRows(db, boost.log) };
-}
-/** {@link computeGoalStackBoost} over goals already read, touching no store. Its log keeps rows whose memory is global,
- *  since only the store can tell them apart; {@link localGoalRecallRows} drops those before the write. */
+/** The goal-stack boost over goals already read, touching no store; a caller skips it under an explicit goal tag. Its log covers the top
+ *  `limit` rows and keeps those whose memory is global, since only the store can tell them apart; {@link localGoalRecallRows} drops those before the write. */
 export function boostByGoals(results, active, opts) {
     const { trace } = opts;
     if (active.goals.length === 0)
@@ -325,7 +299,7 @@ export function boostByGoals(results, active, opts) {
         // tail -- a re-sort of an already deterministically-ordered ranking
         // inherits its determinism via sort stability, and ties preserve the
         // prior (meaningful) rank instead of reordering by content.
-        .sort((a, b) => b.score - a.score);
+        .sort((a, b) => compareScoresDesc(a.score, b.score));
     return { results: boosted, log: buildGoalRecallLog(boosted, matchesByEntryId, goalsByTag, opts) };
 }
 /**
@@ -353,18 +327,14 @@ export function completeGoal(hippoRoot, goalId, opts) {
     try {
         const completedAt = new Date().toISOString();
         const score = opts.outcomeScore ?? null;
-        db.exec('BEGIN IMMEDIATE');
-        try {
+        withWriteScope(db, 'complete_goal', () => {
             // SAFETY: the row comes from the SELECT above, which projects exactly
             // the created_at and status columns of goal_stack.
             const goalRow = db.prepare(`SELECT created_at, status FROM goal_stack WHERE id = ?`).get(goalId);
-            if (!goalRow) {
-                db.exec('COMMIT');
+            if (!goalRow)
                 return;
-            }
             if (goalRow.status === 'completed') {
                 // Already completed -- second call is a no-op for idempotency.
-                db.exec('COMMIT');
                 return;
             }
             db.prepare(`
@@ -394,15 +364,7 @@ export function completeGoal(hippoRoot, goalId, opts) {
           `).run(multiplier, goalId, goalRow.created_at, completedAt);
                 }
             }
-            db.exec('COMMIT');
-        }
-        catch (err) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* already rolled back; keep the original error */ }
-            throw err;
-        }
+        });
     }
     finally {
         closeHippoDb(db);
@@ -420,26 +382,15 @@ export function suspendGoal(hippoRoot, goalId) {
 export function resumeGoal(hippoRoot, goalId) {
     const db = openHippoDb(hippoRoot);
     try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
+        withWriteScope(db, 'resume_goal', () => {
             // SAFETY: the row comes from the SELECT above, which projects exactly
             // the session_id, tenant_id, and status columns of goal_stack.
             const row = db.prepare(`SELECT session_id, tenant_id, status FROM goal_stack WHERE id = ?`).get(goalId);
-            if (!row || row.status !== 'suspended') {
-                db.exec('COMMIT');
+            if (!row || row.status !== 'suspended')
                 return;
-            }
             enforceDepthCapWithinTx(db, row.tenant_id, row.session_id);
             db.prepare(`UPDATE goal_stack SET status = 'active' WHERE id = ?`).run(goalId);
-            db.exec('COMMIT');
-        }
-        catch (err) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* already rolled back; keep the original error */ }
-            throw err;
-        }
+        });
     }
     finally {
         closeHippoDb(db);

package/dist/store/graph-queue.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Fail-soft producer hook: mark a tenant dirty for graph re-extraction by
+ * enqueuing its consolidated mirror memory. NEVER throws into the caller — a
+ * graph-dirty signal failing must not abort a core object write. Graph staleness is
+ * recoverable (next sleep / manual `graph extract`); a broken `hippo decide` is
+ * not. Called POST-COMMIT from the graph-source save/close mutations of
+ * decision, policy, customer_note and project_brief. A null memoryId (a
+ * forgotten mirror) is a no-op.
+ */
+export declare function markGraphDirty(hippoRoot: string, tenantId: string, memoryId: string | null): void;
+/**
+ * Mark every pending queue item for a tenant with `id <= maxId` processed, in
+ * one UPDATE. Status/processed_at only, so the consolidated-source guard trigger
+ * is not involved. Returns the count marked.
+ * The `<= maxId` watermark excludes items enqueued after the drain snapshot.
+ */
+export declare function markPendingProcessedUpTo(hippoRoot: string, tenantId: string, maxId: number): number;
+/**
+ * The dirty tenants awaiting graph re-extraction, each with the MAX pending
+ * queue id at read time (a watermark). The sleep drain rebuilds each tenant's
+ * graph, then marks only items at or below the watermark processed, so items
+ * enqueued DURING the rebuild stay pending for the next sleep (no lost-update
+ * race). Host-wide read (the queue is per-tenant but sleep is cross-tenant).
+ */
+export declare function loadPendingExtractionTenants(hippoRoot: string): {
+    tenantId: string;
+    maxPendingId: number;
+}[];
+//# sourceMappingURL=graph-queue.d.ts.map