hippo-memory 1.63.1 → 1.64.0

package/dist/entry/session-text.d.ts

@@ -0,0 +1,7 @@
+export { collectSessionTurns, sessionTail, type SessionTurn } from '../capture/transcript.js';
+export { scrubForSharing } from '../share-scrub.js';
+export { transcriptWorkingState, WORKING_STATE_CAPS } from '../capture/working-state.js';
+export { lessonFromFailure, failureReport, type FailureReport } from '../capture/failure-reading.js';
+export { collectHandoffEvidence } from '../handoff-evidence.js';
+export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../compaction-items.js';
+//# sourceMappingURL=session-text.d.ts.map

package/dist/entry/session-text.js

@@ -0,0 +1,8 @@
+// The hippo-memory/session-text subpath: what a hook reads from a session (turns, working state, failures, git state, compaction items) and the sharing scrub, with no store, database or server in its imports.
+export { collectSessionTurns, sessionTail } from '../capture/transcript.js';
+export { scrubForSharing } from '../share-scrub.js';
+export { transcriptWorkingState, WORKING_STATE_CAPS } from '../capture/working-state.js';
+export { lessonFromFailure, failureReport } from '../capture/failure-reading.js';
+export { collectHandoffEvidence } from '../handoff-evidence.js';
+export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../compaction-items.js';
+//# sourceMappingURL=session-text.js.map

package/dist/extract.js

@@ -7,6 +7,7 @@ import { fetchWithRetry, llmTimeoutMs } from './http-retry.js';
 import { neverAutoShareTags } from './shared.js';
 import { log } from './log.js';
 import { isJsonString } from './json.js';
+import { certainDefect } from './memory-quality.js';
 const EXTRACTION_PROMPT = `You are extracting factual statements from a conversation or memory entry. Extract 1-8 standalone factual statements that would be useful to remember later.
 
 Rules:
@@ -90,6 +91,11 @@ export function storeExtractedFacts(hippoRoot, source, facts) {
     let rejected = 0;
     const baseHalfLifeDays = loadConfig(hippoRoot).defaultHalfLifeDays;
     for (const fact of facts) {
+        const defect = certainDefect(fact.content);
+        if (defect !== null) {
+            log.warn(`storeExtractedFacts: skipped automatic quality defect (${defect})`);
+            continue;
+        }
         const tags = ['extracted', ...inheritedTags, ...fact.tags];
         const entry = { ...createMemory(fact.content, {
                 layer: Layer.Semantic,

package/dist/failure-log.d.ts

@@ -1,5 +1,4 @@
-/** Failure log: every failed tool call the capture-error hook sees, stored or not. */
-import type { CaptureErrorOutcome, RoutineRule } from './capture-error.js';
+import type { CaptureErrorOutcome, RoutineRule } from './capture/failure-reading.js';
 import type { DatabaseSyncLike } from './db.js';
 /** 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;
@@ -18,11 +17,20 @@ export interface FailureEvent {
     sigHash?: string | null;
     /** Hash of the untruncated error plus the command's first two words, finer than `sigHash`. */
     detailHash?: string | null;
+    /** A shared-store caller's owner and project; null on a local store. */
+    ownerSubject?: string | null;
+    originProject?: string | null;
+    /** The client's queue record id, so a retried send finds the earlier row. */
+    requestId?: string | null;
     /** Override the timestamp (tests). ISO string. */
     now?: string;
 }
 /** Append one failure row and prune rows past {@link FAILURE_LOG_RETENTION_DAYS}. */
 export declare function recordFailure(db: DatabaseSyncLike, event: FailureEvent): void;
+/** 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. */
+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 {
     sessionId: string;

package/dist/failure-log.js

@@ -1,3 +1,5 @@
+/** Failure log: every failed tool call the capture-error hook sees, stored or not. */
+import { ConflictError } from './api-errors.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. */
@@ -6,11 +8,26 @@ const MAX_FIELD = 128;
 export function recordFailure(db, event) {
     // Normalised, because the window and prune compare timestamps as strings.
     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)
-     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);
+    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();
     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. */
+export function requestOutcome(db, tenantId, requestId, sessionId) {
+    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))
+        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. */
+export function settleFailureOutcome(db, tenantId, requestId, outcome) {
+    db.prepare(`UPDATE failure_log SET outcome = ? WHERE tenant_id = ? AND request_id = ?`).run(outcome, tenantId, requestId);
+}
 /** Rated failures per session since `sinceIso`, the input for repeat-error rate per arm. */
 export function failuresBySession(db, tenantId, sinceIso) {
     // SAFETY: the SELECT names exactly these three TEXT columns.

package/dist/gated-write.js

@@ -1,5 +1,5 @@
 // The one write path for text no person typed into hippo: capture, compaction items and imported agent memories.
-import { isContentWorthStoring } from './audit.js';
+import { isContentWorthStoring } from './memory-quality.js';
 import { RejectedValueError } from './rejection.js';
 import { detectSecret } from './secret-detect.js';
 import { auditRejectionRefusal } from './store/audit-event.js';

package/dist/graph/delta.d.ts

@@ -0,0 +1,44 @@
+import type { GraphTxDb, EntityType, RelationType, SourceObjectRef } from './types.js';
+/** What names an object-derived entity across rebuilds; v38 has no UNIQUE on it, so the diff keeps one row per key. */
+export interface NaturalKey {
+    readonly entityType: EntityType;
+    readonly sourceObject: SourceObjectRef;
+}
+export interface DesiredEntity extends NaturalKey {
+    readonly name: string;
+    readonly memoryId: string | null;
+}
+export interface DesiredRelation {
+    readonly from: NaturalKey;
+    readonly to: NaturalKey;
+    readonly relType: RelationType;
+    readonly memoryId: string | null;
+    readonly sourceObject: SourceObjectRef;
+}
+export interface DesiredGraph {
+    readonly entities: readonly DesiredEntity[];
+    readonly relations: readonly DesiredRelation[];
+}
+export type GraphOp = {
+    readonly op: 'deleteEntity';
+    readonly id: number;
+} | {
+    readonly op: 'updateEntity';
+    readonly id: number;
+    readonly entity: DesiredEntity;
+} | {
+    readonly op: 'insertEntity';
+    readonly entity: DesiredEntity;
+} | {
+    readonly op: 'deleteRelation';
+    readonly id: number;
+} | {
+    readonly op: 'insertRelation';
+    readonly relation: DesiredRelation;
+};
+export declare function entityKey(k: NaturalKey): string;
+/** Ops that turn the stored graph into `desired`, in apply order; reads only, and keeps the lowest id per natural key. */
+export declare function graphDelta(db: GraphTxDb, tenantId: string, desired: DesiredGraph): GraphOp[];
+/** graphDelta on its own connection and outside any write lock; the apply re-checks each op against what changed since. */
+export declare function readGraphDelta(hippoRoot: string, tenantId: string, desired: DesiredGraph): GraphOp[];
+//# sourceMappingURL=delta.d.ts.map

package/dist/graph/delta.js

@@ -0,0 +1,109 @@
+// Diffs the derived graph against the stored rows, so a rebuild writes only what changed and an entity keeps the id its relations hang on.
+import { openHippoDb, closeHippoDb } from '../db.js';
+const keyText = (entityType, objectType, objectId) => `${entityType}|${objectType}:${objectId}`;
+export function entityKey(k) {
+    return keyText(k.entityType, k.sourceObject.type, k.sourceObject.id);
+}
+function storedKey(row) {
+    if (row.source_object_type === null || row.source_object_id === null)
+        return null;
+    return keyText(row.entity_type, row.source_object_type, row.source_object_id);
+}
+const relationKey = (from, to, relType) => `${from}>${to}|${relType}`;
+/** The (memory, kind) pair a write would store: a missing mirror leaves the object path, which is 'distilled'. */
+function provenanceOf(memoryId, kinds) {
+    const kind = memoryId === null ? undefined : kinds.get(memoryId);
+    return kind === undefined ? '|distilled' : `${memoryId}|${kind}`;
+}
+function memoryKindsOf(db, desired) {
+    const ids = new Set();
+    for (const row of [...desired.entities, ...desired.relations])
+        if (row.memoryId !== null)
+            ids.add(row.memoryId);
+    if (ids.size === 0)
+        return new Map();
+    // SAFETY: the SELECT names exactly the two columns of the row type.
+    const rows = db.prepare(`SELECT id, kind FROM memories WHERE id IN (SELECT value FROM json_each(?))`)
+        .all(JSON.stringify([...ids]));
+    return new Map(rows.map((r) => [r.id, r.kind]));
+}
+function firstByKey(rows, keyOf) {
+    const out = new Map();
+    for (const row of rows) {
+        const key = keyOf(row);
+        if (!out.has(key))
+            out.set(key, row);
+    }
+    return out;
+}
+function diffEntities(stored, desired, kinds) {
+    const wanted = firstByKey(desired, entityKey);
+    const kept = new Map();
+    const deletes = [];
+    for (const row of stored) {
+        const key = storedKey(row);
+        if (key === null || kept.has(key) || !wanted.has(key))
+            deletes.push({ op: 'deleteEntity', id: row.id });
+        else
+            kept.set(key, row);
+    }
+    const updates = [];
+    const inserts = [];
+    for (const [key, entity] of wanted) {
+        const row = kept.get(key);
+        if (!row)
+            inserts.push({ op: 'insertEntity', entity });
+        else if (row.name !== entity.name || `${row.memory_id ?? ''}|${row.source_kind}` !== provenanceOf(entity.memoryId, kinds)) {
+            updates.push({ op: 'updateEntity', id: row.id, entity });
+        }
+    }
+    const keptKeyById = new Map([...kept].map(([key, row]) => [row.id, key]));
+    return { ops: [...deletes, ...updates, ...inserts], keptKeyById };
+}
+function diffRelations(stored, desired, keptKeyById, kinds) {
+    const wanted = firstByKey(desired, (r) => relationKey(entityKey(r.from), entityKey(r.to), r.relType));
+    const kept = new Set();
+    const deletes = [];
+    for (const row of stored) {
+        const from = keptKeyById.get(row.from_entity_id);
+        const to = keptKeyById.get(row.to_entity_id);
+        // An edge on a deleted entity goes with it through the v38 cascade.
+        if (from === undefined || to === undefined)
+            continue;
+        const key = relationKey(from, to, row.rel_type);
+        const want = wanted.get(key);
+        const same = want !== undefined && !kept.has(key)
+            && `${row.memory_id ?? ''}|${row.source_kind}` === provenanceOf(want.memoryId, kinds)
+            && row.source_object_type === want.sourceObject.type && row.source_object_id === want.sourceObject.id;
+        if (same)
+            kept.add(key);
+        else
+            deletes.push({ op: 'deleteRelation', id: row.id });
+    }
+    const inserts = [];
+    for (const [key, relation] of wanted)
+        if (!kept.has(key))
+            inserts.push({ op: 'insertRelation', relation });
+    return [...deletes, ...inserts];
+}
+/** Ops that turn the stored graph into `desired`, in apply order; reads only, and keeps the lowest id per natural key. */
+export function graphDelta(db, tenantId, desired) {
+    const kinds = memoryKindsOf(db, desired);
+    // 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);
+    // 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);
+    const entityDelta = diffEntities(entities, desired.entities, kinds);
+    return [...entityDelta.ops, ...diffRelations(relations, desired.relations, entityDelta.keptKeyById, kinds)];
+}
+/** graphDelta on its own connection and outside any write lock; the apply re-checks each op against what changed since. */
+export function readGraphDelta(hippoRoot, tenantId, desired) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        return graphDelta(db, tenantId, desired);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=delta.js.map

package/dist/graph/types.d.ts

@@ -70,6 +70,11 @@ export interface InsertEntityOpts {
      *  null; optional alongside a live memory (both paths may be set). */
     sourceObject?: SourceObjectRef;
 }
+/** What an in-place entity update may change; type and source object are the row's identity and stay. */
+export interface UpdateEntityOpts {
+    name: string;
+    memoryId?: string | null;
+}
 export interface InsertRelationOpts {
     fromEntityId: number;
     toEntityId: number;

package/dist/graph/write.d.ts

@@ -11,12 +11,16 @@
  * the forbidden state is unrepresentable regardless of code path. These helpers
  * surface the same guard as clear throws BEFORE hitting the trigger backstop.
  */
-import { type GraphTxDb, type SourceObjectType, type Entity, type Relation, type GraphQueueItem, type InsertEntityOpts, type InsertRelationOpts } from './types.js';
+import { type GraphTxDb, type SourceObjectType, type Entity, type Relation, type GraphQueueItem, type InsertEntityOpts, type InsertRelationOpts, type UpdateEntityOpts } from './types.js';
+import type { GraphOp } from './delta.js';
 /**
  * Insert a graph entity extracted from a consolidated memory. Throws if the source
  * memory is missing / cross-tenant / raw (the DB trigger is the backstop).
  */
 export declare function insertEntity(hippoRoot: string, tenantId: string, opts: InsertEntityOpts, txDb?: GraphTxDb): Entity;
+/** Renames an entity or moves its memory provenance in place, keeping id and created_at; null when the row is gone.
+ *  A delete plus an insert would cascade away every relation that points at it. */
+export declare function updateEntity(hippoRoot: string, tenantId: string, id: number, opts: UpdateEntityOpts, txDb?: GraphTxDb): Entity | null;
 /**
  * Insert a graph relation between two entities, sourced from a consolidated memory.
  * Both entities must exist in the same tenant; the source memory must be consolidated.
@@ -34,25 +38,21 @@ export declare function enqueueExtraction(hippoRoot: string, tenantId: string, m
  * non-terminal 'pending'.
  */
 export declare function markExtractionProcessed(hippoRoot: string, tenantId: string, id: number, status?: 'processed' | 'skipped'): GraphQueueItem;
-/**
- * Delete ALL entities for a tenant (relations cascade via the from/to FKs). Returns
- * the number of entities deleted. The rebuild primitive for graph extraction: the
- * deterministic graph is a pure derived function of the consolidated objects, so an
- * extract clears then re-derives. Lives in graph.ts (the sole sanctioned graph
- * writer), so the CI lint permits this `DELETE FROM entities`. Does NOT touch
- * graph_extraction_queue (the enqueue-hook's domain).
- */
-export declare function clearGraph(hippoRoot: string, tenantId: string, txDb?: GraphTxDb): number;
-/**
- * Run a full graph rebuild for one tenant inside a single transaction. `clearGraph`
- * + every `insertEntity`/`insertRelation` call made inside `fn` (passing the supplied
- * `txDb`) share the one connection and its `BEGIN IMMEDIATE` write lock, so the
- * rebuild is ATOMIC: two concurrent rebuilds serialize on the write lock (the second
- * waits, then re-derives cleanly) instead of interleaving into duplicate rows, and a
- * throw mid-rebuild ROLLS BACK the clear (no bricked/empty graph). The sole sanctioned
- * place to wrap graph writes in a transaction.
- */
-export declare function runGraphRebuildTransaction<T>(hippoRoot: string, tenantId: string, fn: (txDb: GraphTxDb) => T): T;
+export interface ApplyGraphOpsResult {
+    readonly next: number;
+    readonly skipped: number;
+}
+/** Applies `ops` from index `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 declare function applyGraphOps(db: GraphTxDb, hippoRoot: string, tenantId: string, ops: readonly GraphOp[], from: number, opts: {
+    readonly holdMs: number;
+    readonly clock?: () => number;
+}): ApplyGraphOpsResult;
+/** Runs one tenant's graph writes in `fn` on `txDb` under one BEGIN IMMEDIATE, so two rebuilds serialize instead of
+ *  interleaving and a throw rolls back the whole chunk. The sole sanctioned place to wrap graph writes in a transaction. */
+export declare function runGraphRebuildTransaction<T>(hippoRoot: string, tenantId: string, fn: (txDb: GraphTxDb) => T, opts?: {
+    busyWaitMs?: number;
+}): T;
 /**
  * Fail-soft producer hook: mark a tenant dirty for graph re-extraction by
  * enqueuing its consolidated mirror memory. NEVER throws into the caller — a

package/dist/graph/write.js

@@ -14,6 +14,7 @@
 import { openHippoDb, closeHippoDb } from '../db.js';
 import { assertTenantId } from '../tenant.js';
 import { log } from '../log.js';
+import { clock } from '../write-budget.js';
 import { GRAPH_ENTITY_TYPES, GRAPH_RELATION_TYPES, MAX_ENTITY_NAME_LEN } from './types.js';
 import { rowToEntity, rowToRelation, rowToQueueItem, ENTITY_COLS, RELATION_COLS, QUEUE_COLS } from './rows.js';
 const SOURCE_OBJECT_TABLE = {
@@ -92,12 +93,7 @@ export function insertEntity(hippoRoot, tenantId, opts, txDb) {
     if (!GRAPH_ENTITY_TYPES.has(opts.entityType)) {
         throw new Error(`insertEntity: entityType must be one of ${Array.from(GRAPH_ENTITY_TYPES).join('|')}; got ${opts.entityType}`);
     }
-    const name = (opts.name ?? '').trim();
-    if (name.length === 0)
-        throw new Error('insertEntity: name is required');
-    if (name.length > MAX_ENTITY_NAME_LEN) {
-        throw new Error(`insertEntity: name exceeds the ${MAX_ENTITY_NAME_LEN}-char cap`);
-    }
+    const name = checkedName('insertEntity', opts.name);
     const now = new Date().toISOString();
     const memoryId = opts.memoryId ?? null;
     const sourceObject = opts.sourceObject ?? null;
@@ -121,6 +117,40 @@ export function insertEntity(hippoRoot, tenantId, opts, txDb) {
             closeHippoDb(ownDb);
     }
 }
+function checkedName(label, raw) {
+    const name = (raw ?? '').trim();
+    if (name.length === 0)
+        throw new Error(`${label}: name is required`);
+    if (name.length > MAX_ENTITY_NAME_LEN) {
+        throw new Error(`${label}: name exceeds the ${MAX_ENTITY_NAME_LEN}-char cap`);
+    }
+    return name;
+}
+/** Renames an entity or moves its memory provenance in place, keeping id and created_at; null when the row is gone.
+ *  A delete plus an insert would cascade away every relation that points at it. */
+export function updateEntity(hippoRoot, tenantId, id, opts, txDb) {
+    assertTenantId('updateEntity', tenantId);
+    const name = checkedName('updateEntity', opts.name);
+    const db = txDb ?? openHippoDb(hippoRoot);
+    try {
+        // SAFETY: row's shape matches the columns named in ENTITY_COLS above.
+        const row = db.prepare(`SELECT ${ENTITY_COLS} FROM entities WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
+        if (!row)
+            return null;
+        const entity = rowToEntity(row);
+        const sourceObject = entity.sourceObjectType === undefined || entity.sourceObjectId === undefined
+            ? null
+            : { type: entity.sourceObjectType, id: entity.sourceObjectId };
+        const resolved = resolveConsolidatedSource(db, tenantId, opts.memoryId ?? null, sourceObject, 'updateEntity');
+        db.prepare(`UPDATE entities SET name = ?, memory_id = ?, source_kind = ? WHERE id = ? AND tenant_id = ?`)
+            .run(name, resolved.memoryId, resolved.sourceKind, id, tenantId);
+        return { ...entity, name, memoryId: resolved.memoryId, sourceKind: resolved.sourceKind };
+    }
+    finally {
+        if (db !== txDb)
+            closeHippoDb(db);
+    }
+}
 /**
  * Insert a graph relation between two entities, sourced from a consolidated memory.
  * Both entities must exist in the same tenant; the source memory must be consolidated.
@@ -229,39 +259,76 @@ export function markExtractionProcessed(hippoRoot, tenantId, id, status = 'proce
         closeHippoDb(db);
     }
 }
-/**
- * Delete ALL entities for a tenant (relations cascade via the from/to FKs). Returns
- * the number of entities deleted. The rebuild primitive for graph extraction: the
- * deterministic graph is a pure derived function of the consolidated objects, so an
- * extract clears then re-derives. Lives in graph.ts (the sole sanctioned graph
- * writer), so the CI lint permits this `DELETE FROM entities`. Does NOT touch
- * graph_extraction_queue (the enqueue-hook's domain).
- */
-export function clearGraph(hippoRoot, tenantId, txDb) {
-    assertTenantId('clearGraph', tenantId);
-    const ownDb = txDb ? null : openHippoDb(hippoRoot);
-    const db = txDb ?? ownDb;
-    try {
-        const res = db.prepare(`DELETE FROM entities WHERE tenant_id = ?`).run(tenantId);
-        return Number(res.changes ?? 0);
+/** The source object still holds the loader's rule (active or superseded); a closed or gone one gets no new graph row. */
+function objectInForce(db, tenantId, ref) {
+    // `table` comes from the fixed SOURCE_OBJECT_TABLE map, never from input.
+    const table = SOURCE_OBJECT_TABLE[ref.type];
+    // SAFETY: row's shape matches the single `status` column named in the SELECT.
+    const row = db.prepare(`SELECT status FROM ${table} WHERE id = ? AND tenant_id = ?`).get(ref.id, tenantId);
+    return row?.status === 'active' || row?.status === 'superseded';
+}
+function entityIdByKey(db, tenantId, key) {
+    // SAFETY: row's shape matches the single `id` column named in the SELECT.
+    const row = db.prepare(`SELECT id FROM entities WHERE tenant_id = ? AND entity_type = ? AND source_object_type = ? AND source_object_id = ? ORDER BY id LIMIT 1`).get(tenantId, key.entityType, key.sourceObject.type, key.sourceObject.id);
+    return row?.id;
+}
+function insertDesiredRelation(db, hippoRoot, tenantId, rel) {
+    const fromEntityId = entityIdByKey(db, tenantId, rel.from);
+    const toEntityId = entityIdByKey(db, tenantId, rel.to);
+    if (fromEntityId === undefined || toEntityId === undefined || !objectInForce(db, tenantId, rel.sourceObject))
+        return false;
+    // SAFETY: row's shape matches the single aliased column named in the SELECT.
+    const present = db.prepare(`SELECT 1 AS hit FROM relations WHERE tenant_id = ? AND from_entity_id = ? AND to_entity_id = ? AND rel_type = ? LIMIT 1`).get(tenantId, fromEntityId, toEntityId, rel.relType);
+    if (present)
+        return false;
+    insertRelation(hippoRoot, tenantId, { fromEntityId, toEntityId, relType: rel.relType, memoryId: rel.memoryId, sourceObject: rel.sourceObject }, db);
+    return true;
+}
+/** Applies one op; false when a writer since the diff made it stale, which the next run's diff repairs. */
+function applyGraphOp(db, hippoRoot, tenantId, op) {
+    switch (op.op) {
+        case 'deleteEntity':
+            db.prepare(`DELETE FROM entities WHERE id = ? AND tenant_id = ?`).run(op.id, tenantId);
+            return true;
+        case 'deleteRelation':
+            db.prepare(`DELETE FROM relations WHERE id = ? AND tenant_id = ?`).run(op.id, tenantId);
+            return true;
+        case 'updateEntity':
+            if (!objectInForce(db, tenantId, op.entity.sourceObject))
+                return false;
+            return updateEntity(hippoRoot, tenantId, op.id, op.entity, db) !== 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) || entityIdByKey(db, tenantId, op.entity) !== undefined)
+                return false;
+            insertEntity(hippoRoot, tenantId, op.entity, db);
+            return true;
+        case 'insertRelation':
+            return insertDesiredRelation(db, hippoRoot, tenantId, op.relation);
     }
-    finally {
-        if (ownDb)
-            closeHippoDb(ownDb);
+}
+/** Applies `ops` from index `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, hippoRoot, tenantId, ops, from, opts) {
+    assertTenantId('applyGraphOps', tenantId);
+    const now = opts.clock ?? clock;
+    const begunAt = now();
+    let next = from;
+    let skipped = 0;
+    while (next < ops.length) {
+        if (!applyGraphOp(db, hippoRoot, tenantId, ops[next]))
+            skipped += 1;
+        next += 1;
+        if (now() - begunAt >= opts.holdMs)
+            break;
     }
+    return { next, skipped };
 }
-/**
- * Run a full graph rebuild for one tenant inside a single transaction. `clearGraph`
- * + every `insertEntity`/`insertRelation` call made inside `fn` (passing the supplied
- * `txDb`) share the one connection and its `BEGIN IMMEDIATE` write lock, so the
- * rebuild is ATOMIC: two concurrent rebuilds serialize on the write lock (the second
- * waits, then re-derives cleanly) instead of interleaving into duplicate rows, and a
- * throw mid-rebuild ROLLS BACK the clear (no bricked/empty graph). The sole sanctioned
- * place to wrap graph writes in a transaction.
- */
-export function runGraphRebuildTransaction(hippoRoot, tenantId, fn) {
+/** Runs one tenant's graph writes in `fn` on `txDb` under one BEGIN IMMEDIATE, so two rebuilds serialize instead of
+ *  interleaving and a throw rolls back the whole chunk. The sole sanctioned place to wrap graph writes in a transaction. */
+export function runGraphRebuildTransaction(hippoRoot, tenantId, fn, opts) {
     assertTenantId('runGraphRebuildTransaction', tenantId);
-    const db = openHippoDb(hippoRoot);
+    const db = openHippoDb(hippoRoot, opts);
     try {
         db.exec('BEGIN IMMEDIATE');
         let committed = false;
@@ -325,7 +392,7 @@ export function removeGraphEntitiesForObject(hippoRoot, tenantId, sourceObjectTy
         assertTenantId('removeGraphEntitiesForObject', tenantId);
         const db = openHippoDb(hippoRoot);
         try {
-            db.exec('BEGIN');
+            db.exec('BEGIN IMMEDIATE');
             db.prepare(`DELETE FROM relations WHERE tenant_id = ? AND source_object_type = ? AND source_object_id = ?`)
                 .run(tenantId, sourceObjectType, sourceObjectId);
             db.prepare(`DELETE FROM entities WHERE tenant_id = ? AND source_object_type = ? AND source_object_id = ?`)

package/dist/graph-extract.d.ts

@@ -3,11 +3,11 @@
  *
  * Populates the graph from the already-structured consolidated first-class object tables -
  * NO NLP, no precision gate for entities + supersedes. The graph is a pure derived
- * function of the current object state, so `extractGraph` is an idempotent REBUILD: clear
- * the tenant's graph, then re-derive entities + `supersedes` relations from decisions /
+ * function of the current object state, so `extractGraph` is an idempotent REBUILD: derive
+ * entities + `supersedes` relations from decisions /
  * policies / customer_notes / project_briefs (the four object types whose kind maps to the
- * `entity_type` enum). All writes go through the src/graph.ts consolidated-source guard
- * (insertEntity / insertRelation / clearGraph); this module issues no raw SQL.
+ * `entity_type` enum), then write only their difference from the stored rows. All writes go
+ * through the src/graph/write.ts consolidated-source guard; this module issues no raw SQL.
  *
  * Pass 3 adds the
  * first CROSS-OBJECT relations: a deterministic NAME-MATCH heuristic that emits a
@@ -19,6 +19,9 @@
  * skill/incident/process entities (not in the entity_type enum - needs a migration); the
  * `hippo sleep` enqueue-hook.
  */
+import { type EntityType } from './graph/types.js';
+import { type DesiredGraph } from './graph/delta.js';
+import { type WriteBudget } from './write-budget.js';
 /** Per-type load cap (the loaders default to 100). A type whose active or superseded
  *  set exceeds this is truncated; `ExtractResult.truncated` records it so the
  *  incompleteness is observable rather than silent. */
@@ -44,11 +47,42 @@ export interface ExtractResult {
     /** Entity types whose active or superseded load hit MAX_EXTRACT_PER_TYPE (the graph
      *  is under-extracted for those). */
     truncated: string[];
+    /** Writes left out because a writer changed their row or object after the diff; set only when above 0. */
+    skipped?: number;
 }
-/**
- * Idempotent rebuild of the tenant's deterministic graph from its consolidated first-class
- * objects. Returns the entity/relation counts (+ which types were truncated at the
- * per-type cap). Safe to re-run: output is a pure function of the current object state.
- */
+/** A consolidated object row normalised to the fields extraction needs. */
+export interface ExtractRow {
+    entityType: EntityType;
+    /** The object table id (unique only WITHIN its table, hence keyed with entityType). */
+    e2Id: number;
+    name: string;
+    /** The object's full text searched for OTHER entities' names in Pass 3. */
+    searchText: string;
+    memoryId: string | null;
+    /** The successor's object id (Y) when this row (X) is superseded; null otherwise. */
+    supersededBy: number | null;
+}
+/** One object type's loaded rows. */
+export interface LoadedType {
+    entityType: EntityType;
+    rows: ExtractRow[];
+    /** True when either status load filled MAX_EXTRACT_PER_TYPE. */
+    hitCap: boolean;
+}
+/** Every source type's rows, each read on its own connection; callers load before any write lock is taken. */
+export declare function loadGraphSources(hippoRoot: string, tenantId: string): LoadedType[];
+/** The graph the loaded objects imply, plus the counts ExtractResult reports. */
+export interface DerivedGraph extends DesiredGraph {
+    byType: Record<string, number>;
+    truncated: string[];
+    references: number;
+}
+/** The tenant's graph as a pure function of its loaded objects; the write side diffs it against what is stored. */
+export declare function deriveGraph(loaded: readonly LoadedType[]): DerivedGraph;
+/** Idempotent rebuild of the tenant's graph from its consolidated objects, in one transaction; safe to re-run.
+ *  Returns the derived counts and which types hit the per-type cap. */
 export declare function extractGraph(hippoRoot: string, tenantId: string): ExtractResult;
+/** extractGraph for sleep: diffs outside the lock, then applies in transactions of about `budget.holdMs` with a pause
+ *  between them. A run stopped between chunks leaves a mixed graph that the next run's diff finishes. */
+export declare function extractGraphChunked(hippoRoot: string, tenantId: string, budget?: WriteBudget): Promise<ExtractResult>;
 //# sourceMappingURL=graph-extract.d.ts.map