hippo-memory 2.0.0 → 2.1.0

package/dist/store/entry-writes.js

@@ -7,21 +7,38 @@ 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.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. */
-export function writeEntryWithHook(hippoRoot, entry, opts) {
+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) {
@@ -49,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) => {
@@ -104,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.
@@ -117,7 +136,8 @@ 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',
@@ -154,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();
@@ -196,7 +217,8 @@ export function setEntryTagsInTx(db, entry) {
         .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.tenant_id);
     deleteFtsRow(db, entry.id);
@@ -211,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) {
@@ -222,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

@@ -25,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(*).
@@ -106,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) => {
@@ -144,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] : [])))];
@@ -183,7 +179,8 @@ export function localGoalRecallRows(db, rows) {
     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;
@@ -226,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)

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

@@ -1,7 +1,7 @@
 import { type DatabaseSyncLike } from '../db/index.js';
 import { type EntityType, type Entity, type Relation, type StoredGraph } from './graph-rows.js';
-/** Entities with an exact `name`, bounded by `limit` in SQL with a deterministic order, so graph-view focus finds `--entity NAME` directly
- * without materializing every same-name row. */
+/** Entities with an exact `name`, bounded by `limit` in SQL with a deterministic order, so graph-view focus finds
+ * `--entity NAME` directly without materializing every same-name row. */
 export declare function loadEntitiesByName(hippoRoot: string, tenantId: string, name: string, opts?: {
     limit?: number;
 }, txDb?: DatabaseSyncLike): Entity[];
@@ -16,26 +16,31 @@ export declare function loadRelations(hippoRoot: string, tenantId: string, opts?
 /** Chunk size for IN-list queries: well under SQLite's 999-bound-variable default
  *  (leaves headroom for the tenant_id param + the doubled list in neighbour lookups). */
 export declare const IN_LIST_CHUNK = 400;
-/** Load entities by primary id (the BFS-reached rows whose `memory_id` maps back to a recall result). Tenant-scoped, read-only. */
+/** Load entities by primary id (the BFS-reached rows whose `memory_id` maps back to a recall result). Tenant-scoped,
+ * read-only. */
 export declare function loadEntitiesByIds(hippoRoot: string, tenantId: string, ids: number[], txDb?: DatabaseSyncLike): Entity[];
-/** All relations touching ANY of `entityIds` in EITHER direction: the per-hop neighbour query for multi-hop traversal, one query for the whole frontier
- * (no N+1). `limit` caps rows and must be a non-negative integer (raw `LIMIT ?` rejects a fraction). */
+/** All relations touching ANY of `entityIds` in EITHER direction: the per-hop neighbour query for multi-hop traversal,
+ * one query for the whole frontier (no N+1). `limit` caps rows and must be a non-negative integer (raw `LIMIT ?`
+ * rejects a fraction). */
 export declare function loadNeighborRelations(hippoRoot: string, tenantId: string, entityIds: number[], opts?: {
     limit?: number;
 }, txDb?: DatabaseSyncLike): Relation[];
-/** Relations with BOTH endpoints in `entityIds` (edges AMONG the set), for the graph-view focus subgraph; `LIMIT` caps only intra-union edges,
- * so no out-of-union row evicts a valid one. The caller bounds `entityIds` (<= view limit), so a single query is safe. */
+/** Relations with BOTH endpoints in `entityIds` (edges AMONG the set), for the graph-view focus subgraph; `LIMIT` caps
+ * only intra-union edges, so no out-of-union row evicts a valid one. The caller bounds `entityIds` (<= view limit), so
+ * a single query is safe. */
 export declare function loadRelationsAmong(hippoRoot: string, tenantId: string, entityIds: number[], opts?: {
     limit?: number;
 }, txDb?: DatabaseSyncLike): Relation[];
-/** Map consolidated source memory ids to their graph entities: the SEED step of multi-hop recall. Tenant-scoped, read-only; chunks the IN-list under the
- * SQLite variable cap. */
+/** Map consolidated source memory ids to their graph entities: the SEED step of multi-hop recall. Tenant-scoped,
+ * read-only; chunks the IN-list under the SQLite variable cap. */
 export declare function loadEntitiesByMemoryId(hippoRoot: string, tenantId: string, memoryIds: string[]): Entity[];
-/** The stored rows a rebuild diffs against, read on the caller's handle so the diff and the apply can share one write lock. */
+/** The stored rows a rebuild diffs against, read on the caller's handle so the diff and the apply can share one write
+ * lock. */
 export declare function storedGraphOn(db: DatabaseSyncLike, tenantId: string, memoryIds: readonly string[]): StoredGraph;
 /** storedGraphOn on its own connection, outside any write lock. */
 export declare function loadStoredGraph(hippoRoot: string, tenantId: string, memoryIds: readonly string[]): StoredGraph;
 /** Run `fn` in ONE read transaction (a single WAL snapshot) so every `load*` read via `txDb` sees a consistent view
- * even if a rebuild commits concurrently (it clears and reinserts entities, so separate reads could mix old entity ids with new relation ids). */
+ * even if a rebuild commits concurrently (it clears and reinserts entities, so separate reads could mix old entity ids
+ * with new relation ids). */
 export declare function withGraphReadSnapshot<T>(hippoRoot: string, fn: (txDb: DatabaseSyncLike) => T): T;
 //# sourceMappingURL=graph-reads.d.ts.map

package/dist/store/graph-reads.js

@@ -1,4 +1,5 @@
-// The graph reads a view and a traversal share. Each opens hippo.db itself unless the caller hands it the handle its snapshot runs on.
+// The graph reads a view and a traversal share. Each opens hippo.db itself unless the caller hands it the handle its
+// snapshot runs on.
 import { DEFAULT_LIST_LIMIT } from '../util/limits.js';
 import { openHippoDb, closeHippoDb, withReadSnapshot } from '../db/index.js';
 import { onHandle } from './open.js';
@@ -7,8 +8,8 @@ import { GRAPH_ENTITY_TYPES, rowToEntity, rowToRelation, ENTITY_COLS, RELATION_C
 import { placeholders } from '../util/sql.js';
 const DEFAULT_GRAPH_PAGE_SIZE = DEFAULT_LIST_LIMIT;
 const DEFAULT_GRAPH_SCAN_LIMIT = 1000;
-/** Entities with an exact `name`, bounded by `limit` in SQL with a deterministic order, so graph-view focus finds `--entity NAME` directly
- * without materializing every same-name row. */
+/** Entities with an exact `name`, bounded by `limit` in SQL with a deterministic order, so graph-view focus finds
+ * `--entity NAME` directly without materializing every same-name row. */
 export function loadEntitiesByName(hippoRoot, tenantId, name, opts = {}, txDb) {
     assertTenantId('loadEntitiesByName', tenantId);
     const limit = opts.limit ?? DEFAULT_GRAPH_PAGE_SIZE;
@@ -90,7 +91,8 @@ export function loadRelations(hippoRoot, tenantId, opts = {}, txDb) {
 /** Chunk size for IN-list queries: well under SQLite's 999-bound-variable default
  *  (leaves headroom for the tenant_id param + the doubled list in neighbour lookups). */
 export const IN_LIST_CHUNK = 400;
-/** Load entities by primary id (the BFS-reached rows whose `memory_id` maps back to a recall result). Tenant-scoped, read-only. */
+/** Load entities by primary id (the BFS-reached rows whose `memory_id` maps back to a recall result). Tenant-scoped,
+ * read-only. */
 export function loadEntitiesByIds(hippoRoot, tenantId, ids, txDb) {
     assertTenantId('loadEntitiesByIds', tenantId);
     if (ids.length === 0)
@@ -116,8 +118,9 @@ export function loadEntitiesByIds(hippoRoot, tenantId, ids, txDb) {
             closeHippoDb(ownDb);
     }
 }
-/** All relations touching ANY of `entityIds` in EITHER direction: the per-hop neighbour query for multi-hop traversal, one query for the whole frontier
- * (no N+1). `limit` caps rows and must be a non-negative integer (raw `LIMIT ?` rejects a fraction). */
+/** All relations touching ANY of `entityIds` in EITHER direction: the per-hop neighbour query for multi-hop traversal,
+ * one query for the whole frontier (no N+1). `limit` caps rows and must be a non-negative integer (raw `LIMIT ?`
+ * rejects a fraction). */
 export function loadNeighborRelations(hippoRoot, tenantId, entityIds, opts = {}, txDb) {
     assertTenantId('loadNeighborRelations', tenantId);
     if (entityIds.length === 0)
@@ -129,8 +132,8 @@ export function loadNeighborRelations(hippoRoot, tenantId, entityIds, opts = {},
     const ownDb = txDb ? null : openHippoDb(hippoRoot);
     const db = txDb ?? ownDb;
     try {
-        // `limit` applies PER CHUNK, so a frontier over IN_LIST_CHUNK ids could return limit*chunks rows before the dedup below;
-        // harmless today (frontier <= maxNeighbors 200, one chunk, BFS re-enforces the fanout cap).
+        // `limit` applies PER CHUNK, so a frontier over IN_LIST_CHUNK ids could return limit*chunks rows before the dedup
+        // below; harmless today (frontier <= maxNeighbors 200, one chunk, BFS re-enforces the fanout cap).
         const byId = new Map();
         for (let i = 0; i < entityIds.length; i += IN_LIST_CHUNK) {
             const slice = entityIds.slice(i, i + IN_LIST_CHUNK);
@@ -152,8 +155,9 @@ export function loadNeighborRelations(hippoRoot, tenantId, entityIds, opts = {},
             closeHippoDb(ownDb);
     }
 }
-/** Relations with BOTH endpoints in `entityIds` (edges AMONG the set), for the graph-view focus subgraph; `LIMIT` caps only intra-union edges,
- * so no out-of-union row evicts a valid one. The caller bounds `entityIds` (<= view limit), so a single query is safe. */
+/** Relations with BOTH endpoints in `entityIds` (edges AMONG the set), for the graph-view focus subgraph; `LIMIT` caps
+ * only intra-union edges, so no out-of-union row evicts a valid one. The caller bounds `entityIds` (<= view limit), so
+ * a single query is safe. */
 export function loadRelationsAmong(hippoRoot, tenantId, entityIds, opts = {}, txDb) {
     assertTenantId('loadRelationsAmong', tenantId);
     if (entityIds.length === 0)
@@ -180,8 +184,8 @@ export function loadRelationsAmong(hippoRoot, tenantId, entityIds, opts = {}, tx
             closeHippoDb(ownDb);
     }
 }
-/** Map consolidated source memory ids to their graph entities: the SEED step of multi-hop recall. Tenant-scoped, read-only; chunks the IN-list under the
- * SQLite variable cap. */
+/** Map consolidated source memory ids to their graph entities: the SEED step of multi-hop recall. Tenant-scoped,
+ * read-only; chunks the IN-list under the SQLite variable cap. */
 export function loadEntitiesByMemoryId(hippoRoot, tenantId, memoryIds) {
     assertTenantId('loadEntitiesByMemoryId', tenantId);
     if (memoryIds.length === 0)
@@ -203,11 +207,15 @@ export function loadEntitiesByMemoryId(hippoRoot, tenantId, memoryIds) {
         return out;
     });
 }
-/** The stored rows a rebuild diffs against, read on the caller's handle so the diff and the apply can share one write lock. */
+/** The stored rows a rebuild diffs against, read on the caller's handle so the diff and the apply can share one write
+ * lock. */
 export function storedGraphOn(db, tenantId, memoryIds) {
     const kinds = memoryKindsOn(db, memoryIds);
     // SAFETY: the SELECT names exactly the columns of StoredEntity.
-    const entities = db.prepare(`SELECT id, entity_type, name, memory_id, source_kind, source_object_type, source_object_id FROM entities WHERE tenant_id = ? ORDER BY id`).all(tenantId);
+    const entities = db
+        .prepare(`SELECT id, entity_type, name, memory_id, source_kind, source_object_type, source_object_id FROM entities ` +
+        `WHERE tenant_id = ? ORDER BY id`)
+        .all(tenantId);
     // SAFETY: the SELECT names exactly the columns of StoredRelation.
     const relations = db.prepare(`SELECT id, from_entity_id, to_entity_id, rel_type, memory_id, source_kind, source_object_type, source_object_id ` +
         `FROM relations WHERE tenant_id = ? ORDER BY id`).all(tenantId);
@@ -228,7 +236,8 @@ export function loadStoredGraph(hippoRoot, tenantId, memoryIds) {
     });
 }
 /** Run `fn` in ONE read transaction (a single WAL snapshot) so every `load*` read via `txDb` sees a consistent view
- * even if a rebuild commits concurrently (it clears and reinserts entities, so separate reads could mix old entity ids with new relation ids). */
+ * even if a rebuild commits concurrently (it clears and reinserts entities, so separate reads could mix old entity ids
+ * with new relation ids). */
 export function withGraphReadSnapshot(hippoRoot, fn) {
     return onHandle(hippoRoot, (db) => {
         return withReadSnapshot(db, () => fn(db));