hippo-memory 1.72.0 → 2.1.0

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

@@ -2,29 +2,42 @@ 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;
     /** Runs after the row commits and before the mirrors, on an idle connection; keep it best-effort. */
     afterCommit?: () => void;
 }
-/** Write an entry to SQLite and refresh mirrors; `opts.afterWrite` runs in the same SAVEPOINT as the INSERT, so a throw rolls the row back.
- * `opts.actor` defaults to 'cli'; the api layer passes the resolved actor so the audit log gets one row per write. */
+/** Store-side only, never exported from a package entry: `afterWrite` hands the write's own db handle to the hook. */
+export interface WriteEntryInternalOptions extends WriteEntryOptions {
+    /** Runs in the same SAVEPOINT as the INSERT, so a throw rolls the row back. */
+    afterWrite?: (db: DatabaseSyncLike, memoryId: string) => void;
+}
+/** Write an entry to SQLite and refresh mirrors. `opts.actor` defaults to 'cli'; the api layer passes the resolved
+ * actor, so the audit log gets one row per write. */
 export declare function writeEntry(hippoRoot: string, entry: MemoryEntry, opts?: WriteEntryOptions): void;
+/** Writes a promoted copy; with `auditAs` the `promote` audit row joins the INSERT's SAVEPOINT, so both or neither. */
+export declare function writePromotedEntry(hippoRoot: string, entry: MemoryEntry, opts: {
+    readonly actor?: string;
+    readonly sourceId: string;
+    readonly auditAs?: {
+        tenantId: string;
+        actor: string;
+    };
+}): 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; an empty list opens no store. */
 export declare function writeEntriesTogether(hippoRoot: string, entries: readonly MemoryEntry[]): number;
 /** Runs `fill` in one transaction; each `put` writes one entry and returns false when the store rejects its value,
- * leaving that row's refusal audit and the rest of the batch. Mirrors follow the commit. Returns how many were written. */
+ * leaving that row's refusal audit and the rest of the batch. Mirrors follow the commit. Returns how many were
+ * written. */
 export declare function writeEntriesSkippingRejected(hippoRoot: string, fill: (put: (entry: MemoryEntry) => boolean) => void, actor?: string): number;
 /** 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: upsert, afterWrite hook and audit row inside one withWriteScope; the caller owns `db` and must call `writeEntryMirrors` after any
- * outer tx commits, so a rolled-back tx never leaves orphan markdown. The audit row commits atomically with the INSERT. */
-export declare function writeEntryDbOnly(db: DatabaseSyncLike, entry: MemoryEntry, opts?: {
-    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. */
+/** DB-only write path: upsert, afterWrite hook and audit row inside one withWriteScope; the caller owns `db` and must
+ * call `writeEntryMirrors` after any outer tx commits, so a rolled-back tx never leaves orphan markdown. The audit row
+ * commits atomically with the INSERT. */
+export declare function writeEntryDbOnly(db: DatabaseSyncLike, entry: MemoryEntry, opts?: Pick<WriteEntryInternalOptions, 'actor' | 'afterWrite'>): 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;
@@ -36,13 +49,15 @@ export interface StrengthenOptions {
 /** Strengthen what a read returned: update only the four retrieval columns on the live row, never a stale copy.
  *  Best effort: a failure logs and never fails the read. Returns the ids found in this store. */
 export declare function strengthenRetrieved(hippoRoot: string, ids: readonly string[], opts: StrengthenOptions): Set<string>;
-/** strengthenRetrieved on an open handle in its own write scope, a savepoint inside a caller's transaction, so a recall's last writes share one handle. */
+/** strengthenRetrieved on an open handle in its own write scope, a savepoint inside a caller's transaction, so a
+ * recall's last writes share one handle. */
 export declare function strengthenRetrievedInOwnTx(db: DatabaseSyncLike, ids: readonly string[], opts: StrengthenOptions): Set<string>;
 /** strengthenRetrieved on the caller's handle, inside the caller's transaction. Throws; the caller decides. */
 export declare function strengthenRetrievedOn(db: DatabaseSyncLike, ids: readonly string[], opts: StrengthenOptions): Set<string>;
 /** Rewrites a live row's tags and its full-text row on the caller's transaction, with no audit row. */
 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. */
+/** 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 {

package/dist/store/entry-writes.js

@@ -2,21 +2,43 @@ import { strengthAblation } from '../core/ablation.js';
 import { markRetrieved } from '../core/memory.js';
 import { closeHippoDb, openHippoDb, withWriteScope } from '../db/index.js';
 import { rethrowIfSqliteBlocked } from '../util/sqlite-blocked.js';
+import { chunked } from '../util/chunked.js';
 import { RejectedValueError } from '../core/api-errors.js';
 import { markSummaryDirtyInTx } from './summary-dirty.js';
 import { errorMessage, log } from '../util/log.js';
 import { auditRejectionRefusal, audit } from './audit-event.js';
+import { appendAuditEvent } from './audit.js';
 import { selectEntriesByIds } from './entry-reads.js';
 import { stampOriginProject, upsertEntryRow, syncFtsRow, deleteFtsRow } from './entry-row.js';
 import { mirrorBestEffort, writeMarkdownMirror } from './mirrors.js';
 import { onHandle, openStore } from './open.js';
-/** Write an entry to SQLite and refresh mirrors; `opts.afterWrite` runs in the same SAVEPOINT as the INSERT, so a throw rolls the row back.
- * `opts.actor` defaults to 'cli'; the api layer passes the resolved actor so the audit log gets one row per write. */
+/** Write an entry to SQLite and refresh mirrors. `opts.actor` defaults to 'cli'; the api layer passes the resolved
+ * actor, so the audit log gets one row per write. */
 export function writeEntry(hippoRoot, entry, opts) {
+    writeEntryWithHook(hippoRoot, entry, opts);
+}
+/** writeEntry for store code that needs the write's own handle: `opts.afterWrite` shares the INSERT's SAVEPOINT. */
+function writeEntryWithHook(hippoRoot, entry, opts) {
     onHandle(hippoRoot, (db) => {
         writeEntryOn(db, hippoRoot, entry, opts);
     }, openStore);
 }
+/** Writes a promoted copy; with `auditAs` the `promote` audit row joins the INSERT's SAVEPOINT, so both or neither. */
+export function writePromotedEntry(hippoRoot, entry, opts) {
+    const { auditAs, sourceId } = opts;
+    writeEntryWithHook(hippoRoot, entry, {
+        actor: opts.actor,
+        afterWrite: auditAs && ((db, globalId) => {
+            appendAuditEvent(db, {
+                tenantId: auditAs.tenantId,
+                actor: auditAs.actor,
+                op: 'promote',
+                targetId: globalId,
+                metadata: { sourceId },
+            });
+        }),
+    });
+}
 /** 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; an empty list opens no store. */
 export function writeEntriesTogether(hippoRoot, entries) {
@@ -44,7 +66,8 @@ export function writeEntriesTogether(hippoRoot, entries) {
     return stamped.length;
 }
 /** Runs `fill` in one transaction; each `put` writes one entry and returns false when the store rejects its value,
- * leaving that row's refusal audit and the rest of the batch. Mirrors follow the commit. Returns how many were written. */
+ * leaving that row's refusal audit and the rest of the batch. Mirrors follow the commit. Returns how many were
+ * written. */
 export function writeEntriesSkippingRejected(hippoRoot, fill, actor = 'cli') {
     const written = [];
     onHandle(hippoRoot, (db) => {
@@ -99,8 +122,9 @@ function writeEntryOn(db, hippoRoot, entry, opts) {
         throw error;
     }
 }
-/** DB-only write path: upsert, afterWrite hook and audit row inside one withWriteScope; the caller owns `db` and must call `writeEntryMirrors` after any
- * outer tx commits, so a rolled-back tx never leaves orphan markdown. The audit row commits atomically with the INSERT. */
+/** DB-only write path: upsert, afterWrite hook and audit row inside one withWriteScope; the caller owns `db` and must
+ * call `writeEntryMirrors` after any outer tx commits, so a rolled-back tx never leaves orphan markdown. The audit row
+ * commits atomically with the INSERT. */
 export function writeEntryDbOnly(db, entry, opts) {
     // Inside a caller's transaction (e.g. supersede's BEGIN IMMEDIATE) the scope is a SAVEPOINT,
     // so a throw here rolls back only this write and leaves the outer open.
@@ -112,16 +136,17 @@ export function writeEntryDbOnly(db, entry, opts) {
         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. */
+/** 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,
-        }, actor, tenantId: entry.tenantId });
+        }, actor, tenantId: entry.tenant_id });
     // 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);
+        markSummaryDirtyInTx(db, entry.dag_parent_id, entry.tenant_id, actor);
     }
 }
 /** Markdown mirror path, invoked AFTER commit (a rolled-back tx must leave no orphan markdown). */
@@ -149,7 +174,8 @@ export function strengthenRetrieved(hippoRoot, ids, opts) {
         closeHippoDb(db);
     }
 }
-/** strengthenRetrieved on an open handle in its own write scope, a savepoint inside a caller's transaction, so a recall's last writes share one handle. */
+/** strengthenRetrieved on an open handle in its own write scope, a savepoint inside a caller's transaction, so a
+ * recall's last writes share one handle. */
 export function strengthenRetrievedInOwnTx(db, ids, opts) {
     if (ids.length === 0 || opts.recallBoostAblated)
         return new Set();
@@ -164,6 +190,8 @@ export function strengthenRetrievedInOwnTx(db, ids, opts) {
 function warnStrengthenFailed(error) {
     log.warn(`retrieval stats not saved (${errorMessage(error)})`);
 }
+/** Rows per recall-write statement: five bound values each, far under SQLite's parameter limit. */
+const RETRIEVAL_UPDATE_CHUNK = 100;
 /** 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();
@@ -171,25 +199,31 @@ export function strengthenRetrievedOn(db, ids, opts) {
         return found;
     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, undefined, { ablation: strengthAblation() })) {
-        update.run(e.retrieval_count, e.last_retrieved, e.half_life_days, e.strength, e.id);
-        found.add(e.id);
+    const updated = markRetrieved(live, undefined, { ablation: strengthAblation() });
+    // One UPDATE ... FROM per chunk of rows instead of one statement per row.
+    for (const chunk of chunked(updated, RETRIEVAL_UPDATE_CHUNK)) {
+        const values = chunk.map(() => '(?, ?, ?, ?, ?)').join(', ');
+        db.prepare(`WITH v(id, rc, lr, hl, st) AS (VALUES ${values})
+       UPDATE memories SET retrieval_count = v.rc, last_retrieved = v.lr, half_life_days = v.hl, strength = v.st
+       FROM v WHERE memories.id = v.id`).run(...chunk.flatMap((e) => [e.id, e.retrieval_count, e.last_retrieved, e.half_life_days, e.strength]));
+        for (const e of chunk)
+            found.add(e.id);
     }
     return found;
 }
 /** Rewrites a live row's tags and its full-text row on the caller's transaction, with no audit row. */
 export function setEntryTagsInTx(db, entry) {
     db.prepare(`UPDATE memories SET tags_json = ?, updated_at = datetime('now') WHERE id = ? AND tenant_id = ?`)
-        .run(JSON.stringify(entry.tags), entry.id, entry.tenantId);
+        .run(JSON.stringify(entry.tags), entry.id, entry.tenant_id);
     syncFtsRow(db, entry);
 }
-/** 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. */
+/** 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 function deleteEntryRowInTx(db, entry, actor) {
-    db.prepare('DELETE FROM memories WHERE id = ? AND tenant_id = ?').run(entry.id, entry.tenantId);
+    db.prepare('DELETE FROM memories WHERE id = ? AND tenant_id = ?').run(entry.id, entry.tenant_id);
     deleteFtsRow(db, entry.id);
     if (entry.dag_parent_id)
-        markSummaryDirtyInTx(db, entry.dag_parent_id, entry.tenantId, actor);
+        markSummaryDirtyInTx(db, entry.dag_parent_id, entry.tenant_id, actor);
 }
 /** One half-life per memory id, on the caller's transaction. */
 export function setHalfLivesAt(db, rows) {
@@ -199,8 +233,7 @@ export function setHalfLivesAt(db, rows) {
 }
 /** 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);
+    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) {
@@ -210,18 +243,24 @@ export function stampOriginProjectsAt(db, tenantId, rows) {
 }
 /** 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);
+    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);
+    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`)
+    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;
 }

package/dist/store/failure-log-at.js

@@ -1,6 +1,6 @@
 // The failure log on a handle of its own, for code that has a folder and no connection.
 import { onHandle } from './open.js';
-import { recordFailure, requestOutcome, settleFailureOutcome } from './failure-log.js';
+import { recordFailure, requestOutcome, settleFailureOutcome, } from './failure-log.js';
 /** {@link recordFailure} on a handle of its own. */
 export function recordFailureAt(hippoRoot, event) {
     return onHandle(hippoRoot, (db) => recordFailure(db, event));

package/dist/store/failure-log.d.ts

@@ -30,9 +30,11 @@ export interface FailureEvent {
 }
 /** Prune rows past {@link FAILURE_LOG_RETENTION_DAYS}, then append one failure row; returns the new row's id. */
 export declare function recordFailure(db: DatabaseSyncLike, event: FailureEvent): number;
-/** 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. */
+/** 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. */
 export declare function requestOutcome(db: DatabaseSyncLike, tenantId: string, requestId: string, sessionId: string): FailureOutcome | null;
-/** A retry that stored what the first try could not rewrites that row, since the request id allows one row per tenant. */
+/** A retry that stored what the first try could not rewrites that row, since the request id allows one row per
+ * tenant. */
 export declare function settleFailureOutcome(db: DatabaseSyncLike, tenantId: string, requestId: string, outcome: FailureOutcome): void;
 /** Rated failures and repeats in one session, for {@link failuresBySession}. */
 export interface SessionFailures {

package/dist/store/failure-log.js

@@ -12,22 +12,29 @@ export function recordFailure(db, event) {
     // Prune first: nothing after the insert can throw, so a returned id always means a committed row.
     const cutoff = new Date(Date.parse(now) - FAILURE_LOG_RETENTION_DAYS * DAY_MS).toISOString();
     db.prepare(`DELETE FROM failure_log WHERE ts < ?`).run(cutoff);
-    const inserted = 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 inserted = 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);
     return Number(inserted.lastInsertRowid);
 }
-/** 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. */
+/** 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. */
 export function requestOutcome(db, tenantId, requestId, sessionId) {
-    const row = db.prepare(`SELECT outcome, session_id FROM failure_log WHERE tenant_id = ? AND request_id = ?`)
+    const row = db
+        .prepare(`SELECT outcome, session_id FROM failure_log WHERE tenant_id = ? AND request_id = ?`)
         .get(tenantId, requestId);
     if (row === undefined)
         return null;
     // Sessions are owner-bound, so this also keeps one owner from reading or settling another's row; compared as stored.
-    if (row.session_id !== sessionId.slice(0, MAX_FIELD))
+    if (row.session_id !== sessionId.slice(0, MAX_FIELD)) {
         throw new ConflictError('request id belongs to another session');
+    }
     return row.outcome;
 }
-/** A retry that stored what the first try could not rewrites that row, since the request id allows one row per tenant. */
+/** A retry that stored what the first try could not rewrites that row, since the request id allows one row per
+ * tenant. */
 export function settleFailureOutcome(db, tenantId, requestId, outcome) {
     db.prepare(`UPDATE failure_log SET outcome = ? WHERE tenant_id = ? AND request_id = ?`).run(outcome, tenantId, requestId);
 }

package/dist/store/gated-write.d.ts

@@ -1,9 +1,9 @@
 import type { DatabaseSyncLike } from '../db/index.js';
 import type { MemoryEntry } from '../core/memory.js';
 export type GatedWriteResult = 'written' | 'skipped:not-worth-storing' | 'skipped:secret' | 'skipped:rejected';
-/** Runs on the caller's handle so it nests in the caller's transaction (writeEntry would open a second handle and wait on that lock); the
- * caller mirrors after commit with an entry it stamped itself. The rejection audit lands inside that transaction, which is safe because
- * a batch that rolls back stays `summarised` and replay writes the audit again. */
+/** Runs on the caller's handle so it nests in the caller's transaction (writeEntry would open a second handle and wait
+ * on that lock); the caller mirrors after commit with an entry it stamped itself. The rejection audit lands inside that
+ * transaction, which is safe because a batch that rolls back stays `summarised` and replay writes the audit again. */
 export declare function gatedWrite(db: DatabaseSyncLike, hippoRoot: string, entry: MemoryEntry, opts?: {
     actor?: string;
     worthCheck?: boolean;

package/dist/store/gated-write.js

@@ -5,9 +5,9 @@ import { detectSecret } from '../util/secret-detect.js';
 import { auditRejectionRefusal } from './audit-event.js';
 import { stampOriginProject } from './entry-row.js';
 import { writeEntryDbOnly } from './entry-writes.js';
-/** Runs on the caller's handle so it nests in the caller's transaction (writeEntry would open a second handle and wait on that lock); the
- * caller mirrors after commit with an entry it stamped itself. The rejection audit lands inside that transaction, which is safe because
- * a batch that rolls back stays `summarised` and replay writes the audit again. */
+/** Runs on the caller's handle so it nests in the caller's transaction (writeEntry would open a second handle and wait
+ * on that lock); the caller mirrors after commit with an entry it stamped itself. The rejection audit lands inside that
+ * transaction, which is safe because a batch that rolls back stays `summarised` and replay writes the audit again. */
 export function gatedWrite(db, hippoRoot, entry, opts) {
     // Off for imported agent memories: a person wrote those notes, and a one-line preference fails the check.
     if (opts?.worthCheck !== false && !isContentWorthStoring(entry.content))

package/dist/store/goals.d.ts

@@ -60,7 +60,6 @@ export interface GetActiveGoalsOpts {
     sessionId: string;
     tenantId: string;
 }
-export declare function getActiveGoals(hippoRoot: string, opts: GetActiveGoalsOpts): Goal[];
 /** A session's active goals, oldest first, and the retrieval policy of each goal that names one. */
 export interface ActiveGoals {
     readonly goals: Goal[];
@@ -82,12 +81,14 @@ export interface GoalRecallLogRow {
 /** 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[];
-/** INSERT OR IGNORE: UNIQUE(memory_id, goal_id) makes a re-recall during the same goal life a no-op for outcome attribution. */
+/** INSERT OR IGNORE: UNIQUE(memory_id, goal_id) makes a re-recall during the same goal life a no-op for outcome
+ * attribution. */
 export declare function writeGoalRecallLog(db: DatabaseSyncLike, rows: readonly GoalRecallLogRow[]): void;
 export interface CompleteGoalOpts {
     outcomeScore?: number;
-    /** When true, skip the strength-multiplier propagation (default false); status still goes to 'completed' and `outcome_score` is still recorded.
-     * The idempotency guard returns early on a second `completeGoal` call before this flag is read. */
+    /** When true, skip the strength-multiplier propagation (default false); status still goes to 'completed' and
+     * `outcome_score` is still recorded. The idempotency guard returns early on a second `completeGoal` call before this
+     * flag is read. */
     noPropagate?: boolean;
 }
 export declare function completeGoal(hippoRoot: string, goalId: string, opts: CompleteGoalOpts): void;

package/dist/store/goals.js

@@ -2,6 +2,7 @@
 import { randomUUID } from 'node:crypto';
 import { withWriteScope } from '../db/index.js';
 import { onHandle } from './open.js';
+import { placeholders } from '../util/sql.js';
 const MAX_ACTIVE_GOAL_DEPTH = 3;
 export function rowToGoal(row) {
     return {
@@ -24,8 +25,8 @@ export function pushGoal(hippoRoot, opts) {
         return pushGoalWithDb(db, opts);
     });
 }
-/** Depth-cap enforcer for pushGoalWithDb and resumeGoal: suspends the oldest `overflow` goals; **caller MUST be inside a `BEGIN IMMEDIATE` transaction**.
- * @internal Internal goal-stack invariant. Subject to change. */
+/** Depth-cap enforcer for pushGoalWithDb and resumeGoal: suspends the oldest `overflow` goals; **caller MUST be inside
+ * a `BEGIN IMMEDIATE` transaction**. @internal Internal goal-stack invariant. Subject to change. */
 function enforceDepthCapWithinTx(db, tenantId, sessionId) {
     // SAFETY: the row comes from the SELECT above, which projects exactly one
     // column, `c`, as a COUNT(*).
@@ -105,11 +106,6 @@ function insertRetrievalPolicy(db, goalId, policy) {
     db.prepare(`UPDATE goal_stack SET retrieval_policy_id = ? WHERE id = ?`).run(policyId, goalId);
     return policyId;
 }
-export function getActiveGoals(hippoRoot, opts) {
-    return onHandle(hippoRoot, (db) => {
-        return getActiveGoalsWithDb(db, opts);
-    });
-}
 /** The active goals and their policies on one handle, so a goal and its policy never disagree. */
 export function activeGoalsWithPolicies(hippoRoot, opts) {
     return onHandle(hippoRoot, (db) => {
@@ -143,7 +139,8 @@ function getActiveGoalsWithDb(db, opts) {
   `).all(opts.tenantId, opts.sessionId);
     return rows.map(rowToGoal);
 }
-// Per-goal retrieval_policy multipliers compose onto the base goal-tag boost and are hard-capped at MAX_FINAL_MULTIPLIER (3.0x) before scoring.
+// Per-goal retrieval_policy multipliers compose onto the base goal-tag boost and are hard-capped at
+// MAX_FINAL_MULTIPLIER (3.0x) before scoring.
 function loadGoalPolicies(db, active) {
     const policiesByGoalId = new Map();
     const policyIds = [...new Set(active.flatMap((g) => (g.retrievalPolicyId ? [g.retrievalPolicyId] : [])))];
@@ -152,7 +149,7 @@ function loadGoalPolicies(db, active) {
     // SAFETY: the SELECT projects exactly these seven retrieval_policy columns; MAX_ACTIVE_GOAL_DEPTH bounds the IN list.
     const rows = db.prepare(`
     SELECT id, goal_id, policy_type, weight_schema_fit, weight_recency, weight_outcome, error_priority
-    FROM retrieval_policy WHERE id IN (${policyIds.map(() => '?').join(',')})
+    FROM retrieval_policy WHERE id IN (${placeholders(policyIds.length)})
   `).all(...policyIds);
     const byId = new Map(rows.map((row) => [row.id, row]));
     for (const g of active) {
@@ -178,11 +175,12 @@ export function localGoalRecallRows(db, rows) {
         return [];
     const ids = [...new Set(rows.map((r) => r.memoryId))];
     // SAFETY: the SELECT projects exactly one column, `id`, from memories.
-    const local = db.prepare(`SELECT id FROM memories WHERE id IN (${ids.map(() => '?').join(',')})`).all(...ids);
+    const local = db.prepare(`SELECT id FROM memories WHERE id IN (${placeholders(ids.length)})`).all(...ids);
     const localIds = new Set(local.map((r) => r.id));
     return rows.filter((r) => localIds.has(r.memoryId));
 }
-/** INSERT OR IGNORE: UNIQUE(memory_id, goal_id) makes a re-recall during the same goal life a no-op for outcome attribution. */
+/** INSERT OR IGNORE: UNIQUE(memory_id, goal_id) makes a re-recall during the same goal life a no-op for outcome
+ * attribution. */
 export function writeGoalRecallLog(db, rows) {
     if (rows.length === 0)
         return;
@@ -225,7 +223,8 @@ export function completeGoal(hippoRoot, goalId, opts) {
                 else if (score < NEGATIVE_OUTCOME_THRESHOLD)
                     multiplier = STRENGTH_DECAY;
                 if (multiplier !== 1) {
-                    // Lifespan window: only recalls during this goal's active life; UNIQUE(memory_id, goal_id) gives one adjustment per pair.
+                    // Lifespan window: only recalls during this goal's active life; UNIQUE(memory_id, goal_id) gives one
+                    // adjustment per pair.
                     db.prepare(`
             UPDATE memories
             SET strength = MIN(1.0, MAX(0.0, strength * ?))

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

@@ -0,0 +1,21 @@
+import type { GraphOp, StoredGraph } from './graph-rows.js';
+export interface ApplyGraphOpsResult {
+    readonly next: number;
+    readonly skipped: number;
+}
+export interface ApplyGraphOpsOptions {
+    readonly from: number;
+    readonly holdMs: number;
+    readonly clock?: () => number;
+}
+/**
+ * Applies `ops` from index `opts.from` in one rebuild transaction and stops at the first op boundary past
+ * `opts.holdMs`.
+ *  Returns where the next chunk starts and how many ops were skipped as stale. */
+export declare function applyGraphOps(hippoRoot: string, tenantId: string, ops: readonly GraphOp[], opts: ApplyGraphOpsOptions & {
+    readonly busyWaitMs?: number;
+}): ApplyGraphOpsResult;
+/** Reads the stored graph, diffs it with `diff` and applies every op under one lock, so two concurrent rebuilds
+ * serialize instead of both inserting a missing row. Returns how many ops were skipped as stale. */
+export declare function rebuildGraphUnderLock(hippoRoot: string, tenantId: string, memoryIds: readonly string[], diff: (stored: StoredGraph) => readonly GraphOp[]): number;
+//# sourceMappingURL=graph-apply.d.ts.map

package/dist/{graph/write.js → store/graph-apply.js}

@@ -1,15 +1,21 @@
-// Applies a rebuild's op list on the caller's transaction. The statements and the consolidated-source guard sit in the store's graph writers.
-import { assertTenantId } from '../store/tenant.js';
 import { clock } from '../util/write-budget.js';
-import { deleteEntityRow, deleteRelationRow, entityIdBySource, insertEntityRow, insertRelationRow, objectInForce, relationPresent, updateEntityRow } from '../store/graph-writes.js';
+import { storedGraphOn } from './graph-reads.js';
+import { deleteEntityRow, deleteRelationRow, entityIdBySource, insertEntityRow, insertRelationRow, objectInForce, relationPresent, runGraphRebuildTransaction, updateEntityRow, } from './graph-writes.js';
 function insertDesiredRelation(db, tenantId, rel) {
     const fromEntityId = entityIdBySource(db, tenantId, rel.from.entityType, rel.from.sourceObject);
     const toEntityId = entityIdBySource(db, tenantId, rel.to.entityType, rel.to.sourceObject);
-    if (fromEntityId === undefined || toEntityId === undefined || !objectInForce(db, tenantId, rel.sourceObject))
+    if (fromEntityId === undefined || toEntityId === undefined || !objectInForce(db, tenantId, rel.sourceObject)) {
         return false;
+    }
     if (relationPresent(db, tenantId, fromEntityId, toEntityId, rel.relType))
         return false;
-    insertRelationRow(db, tenantId, { fromEntityId, toEntityId, relType: rel.relType, memoryId: rel.memoryId, sourceObject: rel.sourceObject });
+    insertRelationRow(db, tenantId, {
+        fromEntityId,
+        toEntityId,
+        relType: rel.relType,
+        memoryId: rel.memoryId,
+        sourceObject: rel.sourceObject,
+    });
     return true;
 }
 /** Applies one op; false when a writer since the diff made it stale, which the next run's diff repairs. */
@@ -27,18 +33,17 @@ function applyGraphOp(db, tenantId, op) {
             return updateEntityRow(db, tenantId, op.id, op.entity) !== null;
         case 'insertEntity':
             // A mirrorless object closed since the load is never enqueued again, so a stale insert would stay for good.
-            if (!objectInForce(db, tenantId, op.entity.sourceObject) || entityIdBySource(db, tenantId, op.entity.entityType, op.entity.sourceObject) !== undefined)
+            if (!objectInForce(db, tenantId, op.entity.sourceObject) ||
+                entityIdBySource(db, tenantId, op.entity.entityType, op.entity.sourceObject) !== undefined) {
                 return false;
+            }
             insertEntityRow(db, tenantId, op.entity);
             return true;
         case 'insertRelation':
             return insertDesiredRelation(db, tenantId, op.relation);
     }
 }
-/** Applies `ops` from index `opts.from` on the caller's open transaction and stops at the first op boundary past `opts.holdMs`.
- *  Returns where the next chunk starts and how many ops were skipped as stale. */
-export function applyGraphOps(db, tenantId, ops, opts) {
-    assertTenantId('applyGraphOps', tenantId);
+function applyGraphOpsOn(db, tenantId, ops, opts) {
     const now = opts.clock ?? clock;
     const begunAt = now();
     let next = opts.from;
@@ -52,4 +57,19 @@ export function applyGraphOps(db, tenantId, ops, opts) {
     }
     return { next, skipped };
 }
-//# sourceMappingURL=write.js.map
+/**
+ * Applies `ops` from index `opts.from` in one rebuild transaction and stops at the first op boundary past
+ * `opts.holdMs`.
+ *  Returns where the next chunk starts and how many ops were skipped as stale. */
+export function applyGraphOps(hippoRoot, tenantId, ops, opts) {
+    return runGraphRebuildTransaction(hippoRoot, tenantId, (db) => applyGraphOpsOn(db, tenantId, ops, opts), { busyWaitMs: opts.busyWaitMs });
+}
+/** Reads the stored graph, diffs it with `diff` and applies every op under one lock, so two concurrent rebuilds
+ * serialize instead of both inserting a missing row. Returns how many ops were skipped as stale. */
+export function rebuildGraphUnderLock(hippoRoot, tenantId, memoryIds, diff) {
+    return runGraphRebuildTransaction(hippoRoot, tenantId, (db) => {
+        const ops = diff(storedGraphOn(db, tenantId, memoryIds));
+        return applyGraphOpsOn(db, tenantId, ops, { from: 0, holdMs: Infinity }).skipped;
+    });
+}
+//# sourceMappingURL=graph-apply.js.map

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

@@ -1,11 +1,14 @@
-/** Fail-soft producer hook: mark a tenant dirty for graph re-extraction by enqueuing its consolidated mirror memory. NEVER throws: a failed dirty signal
- * must not abort an object write. Call POST-COMMIT from the graph-source save/close mutations; a null memoryId (forgotten mirror) is a no-op. */
+/** Fail-soft producer hook: mark a tenant dirty for graph re-extraction by enqueuing its consolidated mirror memory.
+ * NEVER throws: a failed dirty signal must not abort an object write. Call POST-COMMIT from the graph-source save/close
+ * mutations; a null memoryId (forgotten mirror) is a no-op. */
 export declare function markGraphDirty(hippoRoot: string, tenantId: string, memoryId: string | null): void;
-/** Mark every pending item for a tenant with `id <= maxId` processed in one UPDATE (status/processed_at only, so the source guard trigger is not involved).
- * The watermark excludes items enqueued after the drain snapshot. Returns the count marked. */
+/** Mark every pending item for a tenant with `id <= maxId` processed in one UPDATE (status/processed_at only, so the
+ * source guard trigger is not involved). The watermark excludes items enqueued after the drain snapshot. Returns the
+ * count marked. */
 export declare function markPendingProcessedUpTo(hippoRoot: string, tenantId: string, maxId: number): number;
-/** Dirty tenants awaiting graph re-extraction, each with the MAX pending queue id at read time (a watermark); host-wide, as sleep is cross-tenant.
- * The drain marks only items at or below it processed, so items enqueued DURING the rebuild stay pending (no lost update). */
+/** Dirty tenants awaiting graph re-extraction, each with the MAX pending queue id at read time (a watermark);
+ * host-wide, as sleep is cross-tenant. The drain marks only items at or below it processed, so items enqueued DURING
+ * the rebuild stay pending (no lost update). */
 export declare function loadPendingExtractionTenants(hippoRoot: string): {
     tenantId: string;
     maxPendingId: number;

package/dist/store/graph-queue.js

@@ -1,10 +1,12 @@
-// The graph extraction queue: the consolidated memories that wait for a graph rebuild, and the watermark the sleep drain marks them by.
+// The graph extraction queue: the consolidated memories that wait for a graph rebuild, and the watermark the sleep
+// drain marks them by.
 import { onHandle } from './open.js';
 import { assertTenantId } from './tenant.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorMessage, log, errorFields } from '../util/log.js';
 import { rowToQueueItem, QUEUE_COLS } from './graph-rows.js';
 import { resolveConsolidatedSource } from './graph-writes.js';
-/** Enqueue a consolidated memory for later graph extraction; rejects a raw / missing / cross-tenant memory (the DB trigger is the backstop). */
+/** Enqueue a consolidated memory for later graph extraction; rejects a raw / missing / cross-tenant memory (the DB
+ * trigger is the backstop). */
 function enqueueExtraction(hippoRoot, tenantId, memoryId) {
     assertTenantId('enqueueExtraction', tenantId);
     const now = new Date().toISOString();
@@ -24,8 +26,9 @@ function enqueueExtraction(hippoRoot, tenantId, memoryId) {
         return rowToQueueItem(row);
     });
 }
-/** Fail-soft producer hook: mark a tenant dirty for graph re-extraction by enqueuing its consolidated mirror memory. NEVER throws: a failed dirty signal
- * must not abort an object write. Call POST-COMMIT from the graph-source save/close mutations; a null memoryId (forgotten mirror) is a no-op. */
+/** Fail-soft producer hook: mark a tenant dirty for graph re-extraction by enqueuing its consolidated mirror memory.
+ * NEVER throws: a failed dirty signal must not abort an object write. Call POST-COMMIT from the graph-source save/close
+ * mutations; a null memoryId (forgotten mirror) is a no-op. */
 export function markGraphDirty(hippoRoot, tenantId, memoryId) {
     if (!memoryId)
         return;
@@ -35,11 +38,12 @@ export function markGraphDirty(hippoRoot, tenantId, memoryId) {
     catch (err) {
         // Logged (warn) so a SYSTEMATIC enqueue failure surfaces to operators, but
         // swallowed so the already-committed object write is never rolled back.
-        log.warn(`markGraphDirty: enqueue failed for tenant=${tenantId} memory=${memoryId}: ${errorMessage(err)}`);
+        log.warn(`markGraphDirty: enqueue failed for tenant=${tenantId} memory=${memoryId}: ${errorMessage(err)}`, errorFields(err));
     }
 }
-/** Mark every pending item for a tenant with `id <= maxId` processed in one UPDATE (status/processed_at only, so the source guard trigger is not involved).
- * The watermark excludes items enqueued after the drain snapshot. Returns the count marked. */
+/** Mark every pending item for a tenant with `id <= maxId` processed in one UPDATE (status/processed_at only, so the
+ * source guard trigger is not involved). The watermark excludes items enqueued after the drain snapshot. Returns the
+ * count marked. */
 export function markPendingProcessedUpTo(hippoRoot, tenantId, maxId) {
     assertTenantId('markPendingProcessedUpTo', tenantId);
     const now = new Date().toISOString();
@@ -52,8 +56,9 @@ export function markPendingProcessedUpTo(hippoRoot, tenantId, maxId) {
         return Number(res.changes ?? 0);
     });
 }
-/** Dirty tenants awaiting graph re-extraction, each with the MAX pending queue id at read time (a watermark); host-wide, as sleep is cross-tenant.
- * The drain marks only items at or below it processed, so items enqueued DURING the rebuild stay pending (no lost update). */
+/** Dirty tenants awaiting graph re-extraction, each with the MAX pending queue id at read time (a watermark);
+ * host-wide, as sleep is cross-tenant. The drain marks only items at or below it processed, so items enqueued DURING
+ * the rebuild stay pending (no lost update). */
 export function loadPendingExtractionTenants(hippoRoot) {
     return onHandle(hippoRoot, (db) => {
         // SAFETY: rows' shape matches the two aliased columns (tenant_id, max_id)