hippo-memory 1.59.0 → 1.61.0

package/dist/graph/types.d.ts

@@ -0,0 +1,83 @@
+import { openHippoDb } from '../db.js';
+/** The DB connection handle `openHippoDb` returns. Threaded (optionally) through
+ *  the graph writers so `extractGraph` can run clear + all inserts in ONE
+ *  transaction — see `runGraphRebuildTransaction`. */
+export type GraphTxDb = ReturnType<typeof openHippoDb>;
+export type EntityType = 'person' | 'project' | 'customer' | 'system' | 'policy' | 'decision';
+export type RelationType = 'owns' | 'supersedes' | 'depends-on' | 'blocked-by' | 'references';
+export type GraphQueueStatus = 'pending' | 'processed' | 'skipped';
+/** The consolidated source kinds the graph is permitted to index (never 'raw'). */
+export type SourceKind = 'distilled' | 'superseded';
+/** The authoritative E2 object types a graph row may be anchored to (the object
+ *  provenance path, alongside the memory path). Maps to source_object_type. */
+export type SourceObjectType = 'decision' | 'policy' | 'customer' | 'project';
+/** A soft (type,id) pointer to the authoritative E2 row a graph row descends from.
+ *  Survives a mirror memory forget/prune (memory_id may go NULL); the rebuild
+ *  re-validates it (it is not a hard FK). */
+export interface SourceObjectRef {
+    type: SourceObjectType;
+    id: number;
+}
+export declare const GRAPH_ENTITY_TYPES: ReadonlySet<EntityType>;
+export declare const GRAPH_RELATION_TYPES: ReadonlySet<RelationType>;
+export declare const VALID_QUEUE_STATES: ReadonlySet<GraphQueueStatus>;
+export declare const MAX_ENTITY_NAME_LEN = 512;
+export interface Entity {
+    id: number;
+    tenantId: string;
+    entityType: EntityType;
+    name: string;
+    /** The consolidated source memory this entity was extracted from. NULL once the
+     *  mirror is forgotten/pruned (ON DELETE SET NULL) - the entity then survives via
+     *  its source_object provenance. */
+    memoryId: string | null;
+    sourceKind: SourceKind;
+    /** The authoritative E2 object this entity is anchored to (E2-provenance path).
+     *  Set for E2-sourced entities; absent for memory-only (prose/NLP) entities. */
+    sourceObjectType?: SourceObjectType;
+    sourceObjectId?: number;
+    createdAt: string;
+}
+export interface Relation {
+    id: number;
+    tenantId: string;
+    fromEntityId: number;
+    toEntityId: number;
+    relType: RelationType;
+    /** NULL once the mirror is forgotten/pruned; the relation survives via source_object. */
+    memoryId: string | null;
+    sourceKind: SourceKind;
+    sourceObjectType?: SourceObjectType;
+    sourceObjectId?: number;
+    createdAt: string;
+}
+export interface GraphQueueItem {
+    id: number;
+    tenantId: string;
+    memoryId: string;
+    kind: SourceKind;
+    status: GraphQueueStatus;
+    enqueuedAt: string;
+    processedAt: string | null;
+}
+export interface InsertEntityOpts {
+    entityType: EntityType;
+    name: string;
+    /** A consolidated (distilled/superseded) memory; raw is rejected. NULL/omitted when
+     *  the entity is anchored only to its E2 source object (mirror forgotten/pruned). */
+    memoryId?: string | null;
+    /** The authoritative E2 object this entity descends from. Required when memoryId is
+     *  null; optional alongside a live memory (both paths may be set). */
+    sourceObject?: SourceObjectRef;
+}
+export interface InsertRelationOpts {
+    fromEntityId: number;
+    toEntityId: number;
+    relType: RelationType;
+    /** A consolidated (distilled/superseded) memory; raw is rejected. NULL/omitted when
+     *  the relation is anchored only to its E2 source object. */
+    memoryId?: string | null;
+    /** The authoritative E2 object this relation descends from. */
+    sourceObject?: SourceObjectRef;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/graph/types.js

@@ -0,0 +1,11 @@
+export const GRAPH_ENTITY_TYPES = new Set([
+    'person', 'project', 'customer', 'system', 'policy', 'decision',
+]);
+export const GRAPH_RELATION_TYPES = new Set([
+    'owns', 'supersedes', 'depends-on', 'blocked-by', 'references',
+]);
+export const VALID_QUEUE_STATES = new Set([
+    'pending', 'processed', 'skipped',
+]);
+export const MAX_ENTITY_NAME_LEN = 512;
+//# sourceMappingURL=types.js.map

package/dist/graph/write.d.ts

@@ -0,0 +1,93 @@
+/**
+ * E3.3 graph layer over consolidated state - the graph-on-consolidated guard.
+ * (docs/plans/2026-06-01-e3-graph-guard.md).
+ *
+ * A graph of canonical `entities` (person/project/customer/system/policy/decision) and
+ * `relations` (owns/supersedes/depends-on/blocked-by/references) sits ON TOP OF
+ * consolidated memories. The hard rule: the graph NEVER indexes the raw layer - every
+ * entity and relation references a memory whose `kind IN ('distilled','superseded')`,
+ * never `kind='raw'`. Enforced at the DB level (CHECK on source_kind/kind + BEFORE
+ * INSERT and BEFORE UPDATE triggers that tie source_kind/kind to the FK'd memory's
+ * actual kind and enforce tenant-match - relations also reject cross-tenant edges), so
+ * the forbidden state is unrepresentable regardless of code path. These helpers
+ * surface the same guard as clear throws BEFORE hitting the trigger backstop.
+ *
+ * Scope (E3.3 first slice): the substrate + the guard + a thin insert/load/enqueue
+ * API. The `graph_extraction_queue` is the interface the deferred `hippo sleep`
+ * enqueue-hook + E3.1 entity extraction will call. No operator surface (CLI/HTTP/SDK)
+ * until E3.2 multi-hop recall.
+ */
+import { type GraphTxDb, type SourceObjectType, type Entity, type Relation, type GraphQueueItem, type InsertEntityOpts, type InsertRelationOpts } from './types.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;
+/**
+ * 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.
+ */
+export declare function insertRelation(hippoRoot: string, tenantId: string, opts: InsertRelationOpts, txDb?: GraphTxDb): Relation;
+/**
+ * Enqueue a consolidated memory for later graph extraction. Rejects a raw / missing /
+ * cross-tenant memory (the DB trigger is the backstop). The producer hook in
+ * `hippo sleep` is deferred (E3.1); this is the API it will call.
+ */
+export declare function enqueueExtraction(hippoRoot: string, tenantId: string, memoryId: string): GraphQueueItem;
+/**
+ * Mark a queue item terminal (processed | skipped). Only `status`/`processed_at`
+ * change, so the consolidated-source guard trigger (which fires on
+ * memory_id/kind/tenant_id changes) is not involved. CAS on the current status to a
+ * 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 E3.3 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;
+/**
+ * Fail-soft producer hook: mark a tenant dirty for graph re-extraction by
+ * enqueuing its consolidated mirror memory. NEVER throws into the caller — a
+ * graph-dirty signal failing must not abort a core E2 write. Graph staleness is
+ * recoverable (next sleep / manual `graph extract`); a broken `hippo decide` is
+ * not. Called POST-COMMIT from the E2 graph-source save/close mutations of
+ * decision, policy, customer_note and project_brief. A null memoryId (a
+ * forgotten mirror) is a no-op.
+ */
+export declare function markGraphDirty(hippoRoot: string, tenantId: string, memoryId: string | null): void;
+/**
+ * Remove the graph rows sourced from one E2 object, by its (type, id). Used when a
+ * MIRRORLESS object is closed: it has no mirror memory, so `markGraphDirty` cannot
+ * enqueue a rebuild (the queue is memory-keyed). Closing must still drop the object's
+ * now-stale entity + edges from the graph, so we remove them directly here. Fail-soft
+ * like `markGraphDirty` (never throws into the E2 close caller; graph staleness is
+ * recoverable). Deleting the entity cascade-deletes any relation where it is an endpoint
+ * (relations FK entities ON DELETE CASCADE); the explicit relations DELETE also covers a
+ * relation whose OWN provenance is this object (defensive — every such edge has the object
+ * as an endpoint today, so the cascade already covers it). DELETE fires no BEFORE
+ * INSERT/UPDATE guard trigger.
+ */
+export declare function removeGraphEntitiesForObject(hippoRoot: string, tenantId: string, sourceObjectType: SourceObjectType, sourceObjectId: number): void;
+/**
+ * Mark every pending queue item for a tenant with `id <= maxId` processed, in
+ * one UPDATE. Status/processed_at only, so the consolidated-source guard trigger
+ * is not involved (same as markExtractionProcessed). Returns the count marked.
+ * The `<= maxId` watermark excludes items enqueued after the drain snapshot.
+ */
+export declare function markPendingProcessedUpTo(hippoRoot: string, tenantId: string, maxId: number): number;
+//# sourceMappingURL=write.d.ts.map

package/dist/{graph.js → graph/write.js}

@@ -17,74 +17,17 @@
  * enqueue-hook + E3.1 entity extraction will call. No operator surface (CLI/HTTP/SDK)
  * until E3.2 multi-hop recall.
  */
-import { openHippoDb, closeHippoDb } from './db.js';
-import { assertTenantId } from './tenant.js';
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { assertTenantId } from '../tenant.js';
+import { log } from '../log.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 = {
     decision: 'decisions',
     policy: 'policies',
     customer: 'customer_notes',
     project: 'project_briefs',
 };
-export const GRAPH_ENTITY_TYPES = new Set([
-    'person', 'project', 'customer', 'system', 'policy', 'decision',
-]);
-export const GRAPH_RELATION_TYPES = new Set([
-    'owns', 'supersedes', 'depends-on', 'blocked-by', 'references',
-]);
-export const VALID_QUEUE_STATES = new Set([
-    'pending', 'processed', 'skipped',
-]);
-export const MAX_ENTITY_NAME_LEN = 512;
-function rowToEntity(row) {
-    // SAFETY: entity_type/source_kind/source_object_type are DB CHECK-constrained
-    // (see db.ts CREATE TABLE entities) to exactly the EntityType/SourceKind/
-    // SourceObjectType enum values, so the row's column values match those types.
-    return {
-        id: row.id,
-        tenantId: row.tenant_id,
-        entityType: row.entity_type,
-        name: row.name,
-        memoryId: row.memory_id,
-        sourceKind: row.source_kind,
-        sourceObjectType: row.source_object_type === null ? undefined : row.source_object_type,
-        sourceObjectId: row.source_object_id === null ? undefined : row.source_object_id,
-        createdAt: row.created_at,
-    };
-}
-function rowToRelation(row) {
-    // SAFETY: rel_type/source_kind/source_object_type are DB CHECK-constrained
-    // (see db.ts CREATE TABLE relations) to exactly the RelationType/SourceKind/
-    // SourceObjectType enum values, so the row's column values match those types.
-    return {
-        id: row.id,
-        tenantId: row.tenant_id,
-        fromEntityId: row.from_entity_id,
-        toEntityId: row.to_entity_id,
-        relType: row.rel_type,
-        memoryId: row.memory_id,
-        sourceKind: row.source_kind,
-        sourceObjectType: row.source_object_type === null ? undefined : row.source_object_type,
-        sourceObjectId: row.source_object_id === null ? undefined : row.source_object_id,
-        createdAt: row.created_at,
-    };
-}
-function rowToQueueItem(row) {
-    // SAFETY: kind/status are DB CHECK-constrained (see db.ts CREATE TABLE
-    // graph_extraction_queue) to exactly the SourceKind/GraphQueueStatus enum
-    // values, so the row's column values match those types.
-    return {
-        id: row.id,
-        tenantId: row.tenant_id,
-        memoryId: row.memory_id,
-        kind: row.kind,
-        status: row.status,
-        enqueuedAt: row.enqueued_at,
-        processedAt: row.processed_at,
-    };
-}
-const ENTITY_COLS = `id, tenant_id, entity_type, name, memory_id, source_kind, source_object_type, source_object_id, created_at`;
-const RELATION_COLS = `id, tenant_id, from_entity_id, to_entity_id, rel_type, memory_id, source_kind, source_object_type, source_object_id, created_at`;
-const QUEUE_COLS = `id, tenant_id, memory_id, kind, status, enqueued_at, processed_at`;
 function resolveConsolidatedSource(db, tenantId, memoryId, sourceObject, label) {
     let memKind = null;
     let effectiveMemoryId = memoryId;
@@ -226,274 +169,6 @@ export function insertRelation(hippoRoot, tenantId, opts, txDb) {
             closeHippoDb(ownDb);
     }
 }
-export function loadEntityById(hippoRoot, tenantId, id) {
-    assertTenantId('loadEntityById', tenantId);
-    const db = 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);
-        return row ? rowToEntity(row) : null;
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/** Entities with an exact `name` (read), bounded by `limit` in SQL with a
- *  deterministic order. Lets the graph-view focus query find the `--entity NAME`
- *  entity DIRECTLY (not from a globally-capped list) WITHOUT materializing every
- *  same-name row when a name maps to many entities. */
-export function loadEntitiesByName(hippoRoot, tenantId, name, opts = {}, txDb) {
-    assertTenantId('loadEntitiesByName', tenantId);
-    const limit = opts.limit ?? 100;
-    if (!Number.isInteger(limit) || limit < 0) {
-        throw new Error(`loadEntitiesByName: limit must be a non-negative integer; got ${limit}`);
-    }
-    const ownDb = txDb ? null : openHippoDb(hippoRoot);
-    const db = txDb ?? ownDb;
-    try {
-        // SAFETY: rows' shape matches the columns named in ENTITY_COLS above.
-        const rows = db.prepare(`
-      SELECT ${ENTITY_COLS} FROM entities WHERE tenant_id = ? AND name = ?
-      ORDER BY id ASC LIMIT ?
-    `).all(tenantId, name, limit);
-        return rows.map(rowToEntity);
-    }
-    finally {
-        if (ownDb)
-            closeHippoDb(ownDb);
-    }
-}
-export function loadEntities(hippoRoot, tenantId, opts = {}, txDb) {
-    assertTenantId('loadEntities', tenantId);
-    const limit = opts.limit ?? 100;
-    if (opts.entityType && !GRAPH_ENTITY_TYPES.has(opts.entityType)) {
-        throw new Error(`loadEntities: entityType must be one of ${Array.from(GRAPH_ENTITY_TYPES).join('|')}; got ${opts.entityType}`);
-    }
-    const ownDb = txDb ? null : openHippoDb(hippoRoot);
-    const db = txDb ?? ownDb;
-    try {
-        const clauses = ['tenant_id = ?'];
-        const params = [tenantId];
-        if (opts.entityType) {
-            clauses.push('entity_type = ?');
-            params.push(opts.entityType);
-        }
-        params.push(limit);
-        // SAFETY: rows' shape matches the columns named in ENTITY_COLS above.
-        const rows = db.prepare(`
-      SELECT ${ENTITY_COLS} FROM entities
-      WHERE ${clauses.join(' AND ')}
-      ORDER BY created_at DESC, id DESC
-      LIMIT ?
-    `).all(...params);
-        return rows.map(rowToEntity);
-    }
-    finally {
-        if (ownDb)
-            closeHippoDb(ownDb);
-    }
-}
-export function loadRelations(hippoRoot, tenantId, opts = {}, txDb) {
-    assertTenantId('loadRelations', tenantId);
-    const limit = opts.limit ?? 100;
-    const ownDb = txDb ? null : openHippoDb(hippoRoot);
-    const db = txDb ?? ownDb;
-    try {
-        const clauses = ['tenant_id = ?'];
-        const params = [tenantId];
-        if (opts.fromEntityId !== undefined) {
-            clauses.push('from_entity_id = ?');
-            params.push(opts.fromEntityId);
-        }
-        params.push(limit);
-        // SAFETY: rows' shape matches the columns named in RELATION_COLS above.
-        const rows = db.prepare(`
-      SELECT ${RELATION_COLS} FROM relations
-      WHERE ${clauses.join(' AND ')}
-      ORDER BY created_at DESC, id DESC
-      LIMIT ?
-    `).all(...params);
-        return rows.map(rowToRelation);
-    }
-    finally {
-        if (ownDb)
-            closeHippoDb(ownDb);
-    }
-}
-// ---------------------------------------------------------------------------
-// E3.2 multi-hop recall read helpers (SELECT-only; the check-graph-writes lint
-// permits these here and in the read-only consumer src/graph-recall.ts).
-// ---------------------------------------------------------------------------
-/** 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). */
-const IN_LIST_CHUNK = 400;
-/**
- * Map consolidated source memory ids -> their graph entities. The SEED step of E3.2
- * multi-hop recall (recall result memory ids -> entities to traverse from). 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)
-        return [];
-    const db = openHippoDb(hippoRoot);
-    try {
-        const out = [];
-        for (let i = 0; i < memoryIds.length; i += IN_LIST_CHUNK) {
-            const slice = memoryIds.slice(i, i + IN_LIST_CHUNK);
-            const ph = slice.map(() => '?').join(',');
-            // T2: no ORDER BY meant chunk-local scan order decided ties; id ASC
-            // makes it deterministic (entities.id is an autoincrement integer PK).
-            // SAFETY: rows' shape matches the columns named in ENTITY_COLS above.
-            const rows = db.prepare(`
-        SELECT ${ENTITY_COLS} FROM entities
-        WHERE tenant_id = ? AND memory_id IN (${ph})
-        ORDER BY id ASC
-      `).all(tenantId, ...slice);
-            out.push(...rows.map(rowToEntity));
-        }
-        return out;
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/**
- * Load entities by their primary ids. Resolves the entity rows reached during the BFS
- * (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)
-        return [];
-    const ownDb = txDb ? null : openHippoDb(hippoRoot);
-    const db = txDb ?? ownDb;
-    try {
-        const out = [];
-        for (let i = 0; i < ids.length; i += IN_LIST_CHUNK) {
-            const slice = ids.slice(i, i + IN_LIST_CHUNK);
-            const ph = slice.map(() => '?').join(',');
-            // SAFETY: rows' shape matches the columns named in ENTITY_COLS above.
-            const rows = db.prepare(`
-        SELECT ${ENTITY_COLS} FROM entities
-        WHERE tenant_id = ? AND id IN (${ph})
-      `).all(tenantId, ...slice);
-            out.push(...rows.map(rowToEntity));
-        }
-        return out;
-    }
-    finally {
-        if (ownDb)
-            closeHippoDb(ownDb);
-    }
-}
-/**
- * All relations touching ANY of `entityIds` in EITHER direction (from OR to) — the
- * per-hop neighbour query for E3.2 multi-hop traversal. ONE query for the whole frontier
- * (not one per node): this is the bidirectional read `loadRelations` (from-only) lacks,
- * and avoids an N+1 across BFS frontier nodes. `limit` caps rows for the frontier and
- * must be a non-negative integer (the raw `LIMIT ?` rejects a fractional value).
- */
-export function loadNeighborRelations(hippoRoot, tenantId, entityIds, opts = {}, txDb) {
-    assertTenantId('loadNeighborRelations', tenantId);
-    if (entityIds.length === 0)
-        return [];
-    const limit = opts.limit ?? 1000;
-    if (!Number.isInteger(limit) || limit < 0) {
-        throw new Error(`loadNeighborRelations: limit must be a non-negative integer; got ${limit}`);
-    }
-    const ownDb = txDb ? null : openHippoDb(hippoRoot);
-    const db = txDb ?? ownDb;
-    try {
-        // `limit` is applied PER CHUNK; a frontier spanning >IN_LIST_CHUNK ids could return
-        // up to limit*chunks rows before the by-id dedup below. Harmless for E3.2 (the
-        // frontier is bounded by maxNeighbors <= 200 << IN_LIST_CHUNK, so a single chunk,
-        // and the BFS re-enforces the per-hop fanout cap), but note the semantics if a
-        // tighter total cap is ever needed.
-        const byId = new Map();
-        for (let i = 0; i < entityIds.length; i += IN_LIST_CHUNK) {
-            const slice = entityIds.slice(i, i + IN_LIST_CHUNK);
-            const ph = slice.map(() => '?').join(',');
-            // SAFETY: rows' shape matches the columns named in RELATION_COLS above.
-            const rows = db.prepare(`
-        SELECT ${RELATION_COLS} FROM relations
-        WHERE tenant_id = ? AND (from_entity_id IN (${ph}) OR to_entity_id IN (${ph}))
-        ORDER BY created_at DESC, id DESC
-        LIMIT ?
-      `).all(tenantId, ...slice, ...slice, limit);
-            for (const r of rows)
-                byId.set(r.id, rowToRelation(r));
-        }
-        return Array.from(byId.values());
-    }
-    finally {
-        if (ownDb)
-            closeHippoDb(ownDb);
-    }
-}
-/**
- * Relations with BOTH endpoints in `entityIds` (edges AMONG the set, not merely
- * touching it). Read. Used by the graph-view focus subgraph so the displayed
- * edges are exactly the intra-union edges: the `LIMIT` only caps genuinely-many
- * intra-union edges — no out-of-union row can evict a valid in-set edge. The
- * caller bounds `entityIds` (<= the view limit), so a single query is safe.
- */
-export function loadRelationsAmong(hippoRoot, tenantId, entityIds, opts = {}, txDb) {
-    assertTenantId('loadRelationsAmong', tenantId);
-    if (entityIds.length === 0)
-        return [];
-    const limit = opts.limit ?? 1000;
-    if (!Number.isInteger(limit) || limit < 0) {
-        throw new Error(`loadRelationsAmong: limit must be a non-negative integer; got ${limit}`);
-    }
-    const ownDb = txDb ? null : openHippoDb(hippoRoot);
-    const db = txDb ?? ownDb;
-    try {
-        const ph = entityIds.map(() => '?').join(',');
-        // SAFETY: rows' shape matches the columns named in RELATION_COLS above.
-        const rows = db.prepare(`
-      SELECT ${RELATION_COLS} FROM relations
-      WHERE tenant_id = ? AND from_entity_id IN (${ph}) AND to_entity_id IN (${ph})
-      ORDER BY created_at DESC, id DESC
-      LIMIT ?
-    `).all(tenantId, ...entityIds, ...entityIds, limit);
-        return rows.map(rowToRelation);
-    }
-    finally {
-        if (ownDb)
-            closeHippoDb(ownDb);
-    }
-}
-/**
- * Run `fn` inside ONE read transaction (a single WAL snapshot) so every graph read
- * it performs — pass the supplied `txDb` to the `load*` functions — sees a consistent
- * view, even if a `graph extract` / sleep-drain rebuild commits concurrently between
- * reads (the rebuild clears + reinserts entities, so separate reads could otherwise
- * mix old entity ids with new relation ids). Reads only; the connection is opened
- * once and closed after.
- */
-export function withGraphReadSnapshot(hippoRoot, fn) {
-    const db = openHippoDb(hippoRoot);
-    try {
-        db.exec('BEGIN');
-        try {
-            const out = fn(db);
-            db.exec('COMMIT');
-            return out;
-        }
-        catch (e) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* ignore */ }
-            throw e;
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
 // ---------------------------------------------------------------------------
 // Extraction queue (the interface the deferred sleep enqueue-hook + E3.1 will use)
 // ---------------------------------------------------------------------------
@@ -525,34 +200,6 @@ export function enqueueExtraction(hippoRoot, tenantId, memoryId) {
         closeHippoDb(db);
     }
 }
-export function loadExtractionQueue(hippoRoot, tenantId, opts = {}) {
-    assertTenantId('loadExtractionQueue', tenantId);
-    const limit = opts.limit ?? 100;
-    if (opts.status && !VALID_QUEUE_STATES.has(opts.status)) {
-        throw new Error(`loadExtractionQueue: status must be one of ${Array.from(VALID_QUEUE_STATES).join('|')}; got ${opts.status}`);
-    }
-    const db = openHippoDb(hippoRoot);
-    try {
-        const clauses = ['tenant_id = ?'];
-        const params = [tenantId];
-        if (opts.status) {
-            clauses.push('status = ?');
-            params.push(opts.status);
-        }
-        params.push(limit);
-        // SAFETY: rows' shape matches the columns named in QUEUE_COLS above.
-        const rows = db.prepare(`
-      SELECT ${QUEUE_COLS} FROM graph_extraction_queue
-      WHERE ${clauses.join(' AND ')}
-      ORDER BY enqueued_at ASC, id ASC
-      LIMIT ?
-    `).all(...params);
-        return rows.map(rowToQueueItem);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
 /**
  * Mark a queue item terminal (processed | skipped). Only `status`/`processed_at`
  * change, so the consolidated-source guard trigger (which fires on
@@ -665,10 +312,7 @@ export function markGraphDirty(hippoRoot, tenantId, memoryId) {
     catch (err) {
         // Logged (warn) so a SYSTEMATIC enqueue failure surfaces to operators, but
         // swallowed so the already-committed E2 write is never rolled back.
-        // SAFETY: this is a best-effort log message only; property access on any
-        // JS value is safe (undefined if absent), preserving the existing lenient
-        // formatting even when something non-Error was thrown.
-        console.warn(`markGraphDirty: enqueue failed for tenant=${tenantId} memory=${memoryId}: ${err.message}`);
+        log.warn(`markGraphDirty: enqueue failed for tenant=${tenantId} memory=${memoryId}: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
 /**
@@ -707,34 +351,7 @@ export function removeGraphEntitiesForObject(hippoRoot, tenantId, sourceObjectTy
         }
     }
     catch (err) {
-        // SAFETY: this is a best-effort log message only; property access on any
-        // JS value is safe (undefined if absent), preserving the existing lenient
-        // formatting even when something non-Error was thrown.
-        console.warn(`removeGraphEntitiesForObject: failed for tenant=${tenantId} ${sourceObjectType}#${sourceObjectId}: ${err.message}`);
-    }
-}
-/**
- * The dirty tenants awaiting graph re-extraction, each with the MAX pending
- * queue id at read time (a watermark). The sleep drain rebuilds each tenant's
- * graph, then marks only items at or below the watermark processed, so items
- * enqueued DURING the rebuild stay pending for the next sleep (no lost-update
- * race). Host-wide read (the queue is per-tenant but sleep is cross-tenant).
- */
-export function loadPendingExtractionTenants(hippoRoot) {
-    const db = openHippoDb(hippoRoot);
-    try {
-        // SAFETY: rows' shape matches the two aliased columns (tenant_id, max_id)
-        // named in the SELECT above.
-        const rows = db.prepare(`
-      SELECT tenant_id AS tenant_id, MAX(id) AS max_id
-      FROM graph_extraction_queue
-      WHERE status = 'pending'
-      GROUP BY tenant_id
-    `).all();
-        return rows.map((r) => ({ tenantId: r.tenant_id, maxPendingId: Number(r.max_id) }));
-    }
-    finally {
-        closeHippoDb(db);
+        log.warn(`removeGraphEntitiesForObject: failed for tenant=${tenantId} ${sourceObjectType}#${sourceObjectId}: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
 /**
@@ -759,4 +376,4 @@ export function markPendingProcessedUpTo(hippoRoot, tenantId, maxId) {
         closeHippoDb(db);
     }
 }
-//# sourceMappingURL=graph.js.map
+//# sourceMappingURL=write.js.map

package/dist/graph-extract.js

@@ -20,7 +20,8 @@
  * skill/incident/process entities (not in the entity_type enum - needs a migration); the
  * `hippo sleep` enqueue-hook.
  */
-import { clearGraph, insertEntity, insertRelation, runGraphRebuildTransaction, MAX_ENTITY_NAME_LEN } from './graph.js';
+import { clearGraph, insertEntity, insertRelation, runGraphRebuildTransaction } from './graph/write.js';
+import { MAX_ENTITY_NAME_LEN } from './graph/types.js';
 import { loadDecisions } from './decisions.js';
 import { loadPolicies } from './policies.js';
 import { loadCustomerNotes } from './customer-notes.js';

package/dist/graph-recall.d.ts

@@ -1,4 +1,4 @@
-import type { ResultCost, SearchResult } from './search.js';
+import type { ResultCost, SearchResult } from './search/types.js';
 /** Hard cap on `--hops` (a higher value just walks more of a finite graph; this bounds
  *  worst-case work and keeps the flag honest). */
 export declare const MAX_HOPS = 3;

package/dist/graph-recall.js

@@ -36,10 +36,10 @@
  * No graph writes (only SELECTs via graph.ts read helpers + store reads), so the E3.3
  * check-graph-writes lint permits this module living outside graph.ts.
  */
-import { loadEntriesByIds } from './store.js';
+import { loadEntriesByIds } from './store/entry-reads.js';
 import { estimateTokens } from './token-ledger.js';
 import { compareEntryIdentity } from './compare.js';
-import { loadEntitiesByMemoryId, loadEntitiesByIds, loadNeighborRelations, } from './graph.js';
+import { loadEntitiesByMemoryId, loadEntitiesByIds, loadNeighborRelations } from './graph/read.js';
 import { passesCliRecallScopeFilter, passesScopeFilterForRecall } from './recall-scope.js';
 /** Hard cap on `--hops` (a higher value just walks more of a finite graph; this bounds
  *  worst-case work and keeps the flag honest). */

package/dist/graph-stream.js

@@ -1,4 +1,4 @@
-import { loadEntitiesByMemoryId, loadEntitiesByIds, loadNeighborRelations, } from './graph.js';
+import { loadEntitiesByMemoryId, loadEntitiesByIds, loadNeighborRelations } from './graph/read.js';
 import { MAX_HOPS, DEFAULT_MAX_NEIGHBORS } from './graph-recall.js';
 /** Default hops expanded from each seed (MVP; hard cap MAX_HOPS=3 reused from graph-recall). */
 export const DEFAULT_GRAPH_HOPS = 2;