hippo-memory 1.60.0 → 1.61.0

package/dist/eval.js

@@ -8,9 +8,9 @@
  * weights, and future scoring tweaks can be tuned against evidence instead
  * of intuition.
  */
-import { hybridSearch } from './search.js';
+import { hybridSearch } from './search/hybrid.js';
 import { searchBothHybrid } from './shared.js';
-import { isInitialized } from './store.js';
+import { isInitialized } from './store/open.js';
 // ---------------------------------------------------------------------------
 // Metrics — pure functions. K is inclusive of position K.
 // ---------------------------------------------------------------------------

package/dist/extract.js

@@ -1,5 +1,5 @@
 import { Layer, createMemory } from './memory.js';
-import { writeEntry } from './store.js';
+import { writeEntry } from './store/entry-writes.js';
 import { loadConfig } from './config.js';
 import { RejectedValueError } from './rejection.js';
 import { redactSecretsStrict } from './secret-detect.js';

package/dist/gated-write.js

@@ -2,7 +2,9 @@
 import { isContentWorthStoring } from './audit.js';
 import { RejectedValueError } from './rejection.js';
 import { detectSecret } from './secret-detect.js';
-import { auditRejectionRefusal, stampOriginProject, writeEntryDbOnly } from './store.js';
+import { auditRejectionRefusal } from './store/audit-event.js';
+import { stampOriginProject } from './store/entry-row.js';
+import { writeEntryDbOnly } from './store/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. */
 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.

package/dist/goals.d.ts

@@ -1,6 +1,6 @@
 import { type DatabaseSyncLike } from './db.js';
 import type { MemoryEntry } from './memory.js';
-import type { RerankStep } from './search.js';
+import type { RerankStep } from './search/types.js';
 export type GoalStatus = 'active' | 'suspended' | 'completed';
 export type PolicyType = 'schema-fit-biased' | 'error-prioritized' | 'recency-first' | 'hybrid';
 export interface GoalRow {
@@ -78,6 +78,8 @@ export interface GetActiveGoalsOpts {
     tenantId: string;
 }
 export declare function getActiveGoals(hippoRoot: string, opts: GetActiveGoalsOpts): Goal[];
+/** Every goal of a (tenant, session), whatever its status, oldest first. */
+export declare function getSessionGoals(hippoRoot: string, opts: GetActiveGoalsOpts): Goal[];
 export declare function getActiveGoalsWithDb(db: DatabaseSyncLike, opts: GetActiveGoalsOpts): Goal[];
 /** One `goal_recall_log` row: a boosted local memory recalled while its goal was active. */
 export interface GoalRecallLogRow {

package/dist/goals.js

@@ -129,6 +129,24 @@ export function getActiveGoals(hippoRoot, opts) {
         closeHippoDb(db);
     }
 }
+/** Every goal of a (tenant, session), whatever its status, oldest first. */
+export function getSessionGoals(hippoRoot, opts) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        // SAFETY: rows come from the SELECT below, which projects exactly GoalRow's columns.
+        const rows = db.prepare(`
+      SELECT id, session_id, tenant_id, goal_name, level, parent_goal_id, status,
+             success_condition, retrieval_policy_id, created_at, completed_at, outcome_score
+      FROM goal_stack
+      WHERE tenant_id = ? AND session_id = ?
+      ORDER BY created_at ASC
+    `).all(opts.tenantId, opts.sessionId);
+        return rows.map(rowToGoal);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 export function getActiveGoalsWithDb(db, opts) {
     // SAFETY: rows come from the SELECT above, which projects exactly
     // GoalRow's columns (in the same order goal_stack defines them).

package/dist/graph/read.d.ts

@@ -0,0 +1,73 @@
+import { type GraphTxDb, type EntityType, type GraphQueueStatus, type Entity, type Relation, type GraphQueueItem } from './types.js';
+export declare function loadEntityById(hippoRoot: string, tenantId: string, id: number): Entity | null;
+/** 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 declare function loadEntitiesByName(hippoRoot: string, tenantId: string, name: string, opts?: {
+    limit?: number;
+}, txDb?: GraphTxDb): Entity[];
+export declare function loadEntities(hippoRoot: string, tenantId: string, opts?: {
+    entityType?: EntityType;
+    limit?: number;
+}, txDb?: GraphTxDb): Entity[];
+export declare function loadRelations(hippoRoot: string, tenantId: string, opts?: {
+    fromEntityId?: number;
+    limit?: number;
+}, txDb?: GraphTxDb): Relation[];
+/**
+ * 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 declare function loadEntitiesByMemoryId(hippoRoot: string, tenantId: string, memoryIds: string[]): Entity[];
+/**
+ * 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 declare function loadEntitiesByIds(hippoRoot: string, tenantId: string, ids: number[], txDb?: GraphTxDb): Entity[];
+/**
+ * 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 declare function loadNeighborRelations(hippoRoot: string, tenantId: string, entityIds: number[], opts?: {
+    limit?: number;
+}, txDb?: GraphTxDb): Relation[];
+/**
+ * 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 declare function loadRelationsAmong(hippoRoot: string, tenantId: string, entityIds: number[], opts?: {
+    limit?: number;
+}, txDb?: GraphTxDb): Relation[];
+/**
+ * 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 declare function withGraphReadSnapshot<T>(hippoRoot: string, fn: (txDb: GraphTxDb) => T): T;
+export declare function loadExtractionQueue(hippoRoot: string, tenantId: string, opts?: {
+    status?: GraphQueueStatus;
+    limit?: number;
+}): GraphQueueItem[];
+/**
+ * The dirty tenants awaiting graph re-extraction, each with the MAX pending
+ * queue id at read time (a watermark). The sleep drain rebuilds each tenant's
+ * graph, then marks only items at or below the watermark processed, so items
+ * enqueued DURING the rebuild stay pending for the next sleep (no lost-update
+ * race). Host-wide read (the queue is per-tenant but sleep is cross-tenant).
+ */
+export declare function loadPendingExtractionTenants(hippoRoot: string): {
+    tenantId: string;
+    maxPendingId: number;
+}[];
+//# sourceMappingURL=read.d.ts.map

package/dist/graph/read.js

@@ -0,0 +1,325 @@
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { assertTenantId } from '../tenant.js';
+import { GRAPH_ENTITY_TYPES, VALID_QUEUE_STATES } from './types.js';
+import { rowToEntity, rowToRelation, rowToQueueItem, ENTITY_COLS, RELATION_COLS, QUEUE_COLS } from './rows.js';
+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);
+    }
+}
+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);
+    }
+}
+/**
+ * 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);
+    }
+}
+//# sourceMappingURL=read.js.map

package/dist/graph/rows.d.ts

@@ -0,0 +1,45 @@
+import type { Entity, Relation, GraphQueueItem } from './types.js';
+export interface EntityRow {
+    id: number;
+    tenant_id: string;
+    entity_type: string;
+    name: string;
+    memory_id: string | null;
+    source_kind: string;
+    source_object_type: string | null;
+    source_object_id: number | null;
+    created_at: string;
+}
+export interface RelationRow {
+    id: number;
+    tenant_id: string;
+    from_entity_id: number;
+    to_entity_id: number;
+    rel_type: string;
+    memory_id: string | null;
+    source_kind: string;
+    source_object_type: string | null;
+    source_object_id: number | null;
+    created_at: string;
+}
+export interface QueueRow {
+    id: number;
+    tenant_id: string;
+    memory_id: string;
+    kind: string;
+    status: string;
+    enqueued_at: string;
+    processed_at: string | null;
+}
+export declare function rowToEntity(row: EntityRow): Entity;
+export declare function rowToRelation(row: RelationRow): Relation;
+export declare function rowToQueueItem(row: QueueRow): GraphQueueItem;
+export declare const ENTITY_COLS = "id, tenant_id, entity_type, name, memory_id, source_kind, source_object_type, source_object_id, created_at";
+export declare 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";
+export declare const QUEUE_COLS = "id, tenant_id, memory_id, kind, status, enqueued_at, processed_at";
+export interface DbLike {
+    prepare(sql: string): {
+        get<T>(...params: unknown[]): T;
+    };
+}
+//# sourceMappingURL=rows.d.ts.map

package/dist/graph/rows.js

@@ -0,0 +1,51 @@
+export 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,
+    };
+}
+export 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,
+    };
+}
+export 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,
+    };
+}
+export const ENTITY_COLS = `id, tenant_id, entity_type, name, memory_id, source_kind, source_object_type, source_object_id, created_at`;
+export 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`;
+export const QUEUE_COLS = `id, tenant_id, memory_id, kind, status, enqueued_at, processed_at`;
+//# sourceMappingURL=rows.js.map

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