hippo-memory 1.72.0 → 2.1.0

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

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

package/dist/store/graph-reads.js

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

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

@@ -21,7 +21,8 @@ export interface Entity {
     tenantId: string;
     entityType: EntityType;
     name: string;
-    /** The consolidated source memory this entity came from; NULL once the mirror is forgotten/pruned (ON DELETE SET NULL), then provenance is source_object. */
+    /** The consolidated source memory this entity came from; NULL once the mirror is forgotten/pruned (ON DELETE SET
+     * NULL), then provenance is source_object. */
     memoryId: string | null;
     sourceKind: SourceKind;
     /** The authoritative object this entity is anchored to (object-provenance path).
@@ -68,8 +69,8 @@ export interface RelationRow {
 }
 export declare function rowToEntity(row: EntityRow): Entity;
 export declare function rowToRelation(row: RelationRow): Relation;
-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 ENTITY_COLS: string;
+export declare const RELATION_COLS: string;
 export interface GraphQueueItem {
     id: number;
     tenantId: string;
@@ -142,4 +143,41 @@ export interface StoredGraph {
     readonly entities: readonly StoredEntity[];
     readonly relations: readonly StoredRelation[];
 }
+/** 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;
+};
 //# sourceMappingURL=graph-rows.d.ts.map

package/dist/store/graph-rows.js

@@ -1,4 +1,5 @@
-// The graph's entity, relation and queue rows as hippo.db holds them, and the types every reader and writer of them shares.
+// The graph's entity, relation and queue rows as hippo.db holds them, and the types every reader and writer of them
+// shares.
 export const GRAPH_ENTITY_TYPES = new Set([
     'person', 'project', 'customer', 'system', 'policy', 'decision',
 ]);
@@ -10,8 +11,8 @@ export const VALID_QUEUE_STATES = new Set([
 ]);
 export const MAX_ENTITY_NAME_LEN = 512;
 export function rowToEntity(row) {
-    // SAFETY: entity_type/source_kind/source_object_type are DB CHECK-constrained to exactly the EntityType/SourceKind/SourceObjectType enum values,
-    // so the row's column values match those types.
+    // SAFETY: entity_type/source_kind/source_object_type are DB CHECK-constrained 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,
@@ -25,8 +26,8 @@ export function rowToEntity(row) {
     };
 }
 export function rowToRelation(row) {
-    // SAFETY: rel_type/source_kind/source_object_type are DB CHECK-constrained to exactly the RelationType/SourceKind/SourceObjectType enum values,
-    // so the row's column values match those types.
+    // SAFETY: rel_type/source_kind/source_object_type are DB CHECK-constrained 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,
@@ -40,8 +41,10 @@ export function rowToRelation(row) {
         createdAt: row.created_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 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 function rowToQueueItem(row) {
     // SAFETY: kind/status are DB CHECK-constrained to exactly the SourceKind/GraphQueueStatus enum values,
     // so the row's column values match those types.

package/dist/store/graph-view-rows.js

@@ -1,5 +1,7 @@
-import { IN_LIST_CHUNK, loadEntities, loadEntitiesByIds, loadEntitiesByName, loadNeighborRelations, loadRelations, loadRelationsAmong } from './graph-reads.js';
-/** The items whose source memory `canRead` admits: a NULL memoryId has no scope to hide, and a missing memory fails closed. */
+import { IN_LIST_CHUNK, loadEntities, loadEntitiesByIds, loadEntitiesByName, loadNeighborRelations, loadRelations, loadRelationsAmong, } from './graph-reads.js';
+import { placeholders } from '../util/sql.js';
+/** The items whose source memory `canRead` admits: a NULL memoryId has no scope to hide, and a missing memory fails
+ * closed. */
 function readableOnly(db, tenantId, items, canRead) {
     if (!canRead)
         return items;
@@ -8,7 +10,8 @@ function readableOnly(db, tenantId, items, canRead) {
     for (let i = 0; i < ids.length; i += IN_LIST_CHUNK) {
         const slice = ids.slice(i, i + IN_LIST_CHUNK);
         // SAFETY: rows' shape matches the id and scope columns named in the SELECT.
-        const rows = db.prepare(`SELECT id, scope FROM memories WHERE +tenant_id = ? AND id IN (${slice.map(() => '?').join(',')})`)
+        const rows = db
+            .prepare(`SELECT id, scope FROM memories WHERE +tenant_id = ? AND id IN (${placeholders(slice.length)})`)
             .all(tenantId, ...slice);
         for (const r of rows)
             if (canRead(r.scope))
@@ -21,9 +24,11 @@ function wholeGraphRows({ hippoRoot, db, tenantId }, limit) {
     const relations = loadRelations(hippoRoot, tenantId, { limit }, db);
     return { entities, relations, truncated: entities.length >= limit || relations.length >= limit };
 }
-/** The named entities with their 1-hop neighbours and the edges among that union; null when the caller may read none of the named ones. */
+/** The named entities with their 1-hop neighbours and the edges among that union; null when the caller may read none of
+ * the named ones. */
 function focusRows({ hippoRoot, db, tenantId }, name, limit, canRead) {
-    // The name is queried directly, so it is found on a graph larger than `limit`; one name can map to many entities, so the matches are capped.
+    // The name is queried directly, so it is found on a graph larger than `limit`; one name can map to many entities, so
+    // the matches are capped.
     const named = loadEntitiesByName(hippoRoot, tenantId, name, { limit }, db);
     // A hidden focus must not answer through its neighbours that the name exists.
     const focus = readableOnly(db, tenantId, named, canRead);
@@ -43,7 +48,8 @@ function focusRows({ hippoRoot, db, tenantId }, name, limit, canRead) {
     }
     const unionIds = [...union].slice(0, limit);
     const entities = loadEntitiesByIds(hippoRoot, tenantId, unionIds, db);
-    // Both endpoints in the set: neighbour-to-neighbour edges are included, and the LIMIT never drops one for an out-of-union row.
+    // Both endpoints in the set: neighbour-to-neighbour edges are included, and the LIMIT never drops one for an
+    // out-of-union row.
     const relations = loadRelationsAmong(hippoRoot, tenantId, unionIds, { limit }, db);
     const truncated = named.length >= limit ||
         hop.length >= limit || // neighbour scan capped -> a 1-hop neighbour may be omitted
@@ -56,7 +62,9 @@ function focusRows({ hippoRoot, db, tenantId }, name, limit, canRead) {
  * snapshot that keeps entity ids and relation ids from two different rebuilds apart. */
 export function graphViewRows(hippoRoot, db, tenantId, spec) {
     const source = { hippoRoot, db, tenantId };
-    const raw = spec.entity !== undefined ? focusRows(source, spec.entity, spec.limit, spec.canRead) : wholeGraphRows(source, spec.limit);
+    const raw = spec.entity !== undefined
+        ? focusRows(source, spec.entity, spec.limit, spec.canRead)
+        : wholeGraphRows(source, spec.limit);
     if (raw === null)
         return { entities: [], relations: [], truncated: false };
     return {

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

@@ -1,20 +1,24 @@
 import { type DatabaseSyncLike } from '../db/index.js';
 import { type EntityType, type RelationType, type SourceKind, type SourceObjectType, type SourceObjectRef, type Entity, type Relation, type InsertEntityOpts, type InsertRelationOpts, type UpdateEntityOpts } from './graph-rows.js';
-/** Resolve `source_kind` for a graph row from AT LEAST ONE valid provenance path, mirroring the DB trigger guard; raw is rejected.
- * MEMORY path: exists, same-tenant, consolidated. OBJECT path (`memoryId` null): same-tenant, active|superseded, yields 'distilled'. All-null is rejected. */
+/** Resolve `source_kind` for a graph row from AT LEAST ONE valid provenance path, mirroring the DB trigger guard; raw
+ * is rejected. MEMORY path: exists, same-tenant, consolidated. OBJECT path (`memoryId` null): same-tenant,
+ * active|superseded, yields 'distilled'. All-null is rejected. */
 interface ResolvedGraphSource {
     sourceKind: SourceKind;
     memoryId: string | null;
 }
 export declare function resolveConsolidatedSource(db: DatabaseSyncLike, tenantId: string, memoryId: string | null, sourceObject: SourceObjectRef | null, label: string): ResolvedGraphSource;
-/** Insert a graph entity on the caller's handle; throws if the source memory is missing / cross-tenant / raw (the DB trigger is the backstop). */
+/** Insert a graph entity on the caller's handle; throws if the source memory is missing / cross-tenant / raw (the DB
+ * trigger is the backstop). */
 export declare function insertEntityRow(db: DatabaseSyncLike, tenantId: string, opts: InsertEntityOpts): Entity;
-/** Renames an entity or moves its memory provenance in place on the caller's handle, 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. */
+/** Renames an entity or moves its memory provenance in place on the caller's handle, 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 updateEntityRow(db: DatabaseSyncLike, tenantId: string, id: number, opts: UpdateEntityOpts): Entity | null;
-/** Insert a graph relation between two same-tenant entities on the caller's handle, sourced from a consolidated memory. */
+/** Insert a graph relation between two same-tenant entities on the caller's handle, sourced from a consolidated
+ * memory. */
 export declare function insertRelationRow(db: DatabaseSyncLike, tenantId: string, opts: InsertRelationOpts): Relation;
-/** The source object still holds the loader's rule (active or superseded); a closed or gone one gets no new graph row. */
+/** The source object still holds the loader's rule (active or superseded); a closed or gone one gets no new graph
+ * row. */
 export declare function objectInForce(db: DatabaseSyncLike, tenantId: string, ref: SourceObjectRef): boolean;
 /** The lowest-id entity of this type anchored to the source object, which is the row a rebuild keeps. */
 export declare function entityIdBySource(db: DatabaseSyncLike, tenantId: string, entityType: EntityType, sourceObject: SourceObjectRef): number | undefined;
@@ -22,12 +26,14 @@ export declare function relationPresent(db: DatabaseSyncLike, tenantId: string,
 export declare function deleteEntityRow(db: DatabaseSyncLike, tenantId: string, id: number): void;
 export declare function deleteRelationRow(db: DatabaseSyncLike, tenantId: string, id: number): void;
 /** 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. */
+ * 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: DatabaseSyncLike) => T, opts?: {
     busyWaitMs?: number;
 }): T;
-/** Remove graph rows sourced from one MIRRORLESS object by (type, id) on close: with no mirror memory `markGraphDirty` cannot enqueue a rebuild.
- * Fail-soft like `markGraphDirty`; the explicit relations DELETE also covers a relation whose OWN provenance is this object. */
+/** Remove graph rows sourced from one MIRRORLESS object by (type, id) on close: with no mirror memory `markGraphDirty`
+ * cannot enqueue a rebuild. Fail-soft like `markGraphDirty`; the explicit relations DELETE also covers a relation whose
+ * OWN provenance is this object. */
 export declare function removeGraphEntitiesForObject(hippoRoot: string, tenantId: string, sourceObjectType: SourceObjectType, sourceObjectId: number): void;
 export {};
 //# sourceMappingURL=graph-writes.d.ts.map

package/dist/store/graph-writes.js

@@ -3,7 +3,7 @@
 import { openHippoDb, closeHippoDb, withWriteScope } from '../db/index.js';
 import { onHandle } from './open.js';
 import { assertTenantId } from './tenant.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorMessage, log, errorFields } from '../util/log.js';
 import { GRAPH_ENTITY_TYPES, GRAPH_RELATION_TYPES, MAX_ENTITY_NAME_LEN, rowToEntity, rowToRelation, ENTITY_COLS, RELATION_COLS } from './graph-rows.js';
 const SOURCE_OBJECT_TABLE = {
     decision: 'decisions',
@@ -30,8 +30,8 @@ function checkSourceMemory(db, tenantId, memoryId, sourceObject, label) {
         // the SELECT above.
         const row = db.prepare(`SELECT kind, tenant_id FROM memories WHERE id = ?`).get(memoryId);
         if (!row) {
-            // Stale/forgotten mirror: tolerate it IFF a valid source object gives provenance, so a mirror pruned mid graph-extract does not roll back the tenant
-            // rebuild; anchor to the object and drop the dead memory pointer.
+            // Stale/forgotten mirror: tolerate it IFF a valid source object gives provenance, so a mirror pruned mid
+            // graph-extract does not roll back the tenant rebuild; anchor to the object and drop the dead memory pointer.
             if (sourceObject == null) {
                 throw new Error(`${label}: source memory ${memoryId} not found`);
             }
@@ -53,25 +53,29 @@ function checkSourceMemory(db, tenantId, memoryId, sourceObject, label) {
     return { memKind, effectiveMemoryId };
 }
 function assertSourceObjectUsable(db, tenantId, sourceObject, label) {
-    // Validate the object pointer WHENEVER provided: a dual-set row with a bad object would become the provenance after ON DELETE SET NULL and could block
-    // the memory delete.
+    // Validate the object pointer WHENEVER provided: a dual-set row with a bad object would become the provenance after
+    // ON DELETE SET NULL and could block the memory delete.
     if (sourceObject != null) {
         const table = SOURCE_OBJECT_TABLE[sourceObject.type];
         if (!table) {
             throw new Error(`${label}: unsupported source_object_type '${sourceObject.type}'`);
         }
-        // `table` is a fixed SOURCE_OBJECT_TABLE value (never user-supplied), so interpolation is safe; `id`/`tenant_id` stay parametrized.
-        // SAFETY: row's shape matches the single `status` column named in the SELECT above.
-        const row = db.prepare(`SELECT status FROM ${table} WHERE id = ? AND tenant_id = ?`).get(sourceObject.id, tenantId);
+        // `table` is a fixed SOURCE_OBJECT_TABLE value (never user-supplied), so interpolation is safe; `id`/`tenant_id`
+        // stay parametrized. SAFETY: row's shape matches the single `status` column named in the SELECT above.
+        const row = db
+            .prepare(`SELECT status FROM ${table} WHERE id = ? AND tenant_id = ?`)
+            .get(sourceObject.id, tenantId);
         if (!row) {
             throw new Error(`${label}: source ${sourceObject.type} ${sourceObject.id} not found for tenant ${tenantId}`);
         }
         if (row.status !== 'active' && row.status !== 'superseded') {
-            throw new Error(`${label}: source ${sourceObject.type} ${sourceObject.id} has status '${row.status}' (must be active|superseded)`);
+            throw new Error(`${label}: source ${sourceObject.type} ${sourceObject.id} has status '${row.status}' (must be ` +
+                `active|superseded)`);
         }
     }
 }
-/** Insert a graph entity on the caller's handle; throws if the source memory is missing / cross-tenant / raw (the DB trigger is the backstop). */
+/** Insert a graph entity on the caller's handle; throws if the source memory is missing / cross-tenant / raw (the DB
+ * trigger is the backstop). */
 export function insertEntityRow(db, tenantId, opts) {
     assertTenantId('insertEntity', tenantId);
     if (!GRAPH_ENTITY_TYPES.has(opts.entityType)) {
@@ -82,10 +86,13 @@ export function insertEntityRow(db, tenantId, opts) {
     const memoryId = opts.memoryId ?? null;
     const sourceObject = opts.sourceObject ?? null;
     const { sourceKind, memoryId: effectiveMemoryId } = resolveConsolidatedSource(db, tenantId, memoryId, sourceObject, 'insertEntity');
-    const result = db.prepare(`
-    INSERT INTO entities(tenant_id, entity_type, name, memory_id, source_kind, source_object_type, source_object_id, created_at)
+    const result = db
+        .prepare(`
+    INSERT INTO entities(tenant_id, entity_type, name, memory_id, source_kind, source_object_type, source_object_id,
+    created_at)
     VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(tenantId, opts.entityType, name, effectiveMemoryId, sourceKind, sourceObject?.type ?? null, sourceObject?.id ?? null, now);
+  `)
+        .run(tenantId, opts.entityType, name, effectiveMemoryId, sourceKind, sourceObject?.type ?? null, sourceObject?.id ?? null, now);
     const id = Number(result.lastInsertRowid ?? 0);
     // SAFETY: row's shape matches the columns named in ENTITY_COLS above.
     const row = db.prepare(`SELECT ${ENTITY_COLS} FROM entities WHERE id = ?`).get(id);
@@ -102,8 +109,8 @@ function checkedName(label, raw) {
     }
     return name;
 }
-/** Renames an entity or moves its memory provenance in place on the caller's handle, 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. */
+/** Renames an entity or moves its memory provenance in place on the caller's handle, 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 updateEntityRow(db, tenantId, id, opts) {
     assertTenantId('updateEntity', tenantId);
     const name = checkedName('updateEntity', opts.name);
@@ -116,19 +123,10 @@ export function updateEntityRow(db, tenantId, id, opts) {
         ? 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);
+    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 };
 }
-/** Insert a graph relation between two same-tenant entities on the caller's handle, sourced from a consolidated memory. */
-export function insertRelationRow(db, tenantId, opts) {
-    assertTenantId('insertRelation', tenantId);
-    if (!GRAPH_RELATION_TYPES.has(opts.relType)) {
-        throw new Error(`insertRelation: relType must be one of ${Array.from(GRAPH_RELATION_TYPES).join('|')}; got ${opts.relType}`);
-    }
-    const now = new Date().toISOString();
-    const memoryId = opts.memoryId ?? null;
-    const sourceObject = opts.sourceObject ?? null;
+function assertEndpointsInTenant(db, tenantId, opts) {
     for (const [eid, role] of [[opts.fromEntityId, 'from'], [opts.toEntityId, 'to']]) {
         // SAFETY: ent's shape matches the single `tenant_id` column named in
         // the SELECT above.
@@ -139,11 +137,26 @@ export function insertRelationRow(db, tenantId, opts) {
             throw new Error(`insertRelation: ${role}_entity ${eid} belongs to another tenant (no cross-tenant edges)`);
         }
     }
+}
+/** Insert a graph relation between two same-tenant entities on the caller's handle, sourced from a consolidated
+ * memory. */
+export function insertRelationRow(db, tenantId, opts) {
+    assertTenantId('insertRelation', tenantId);
+    if (!GRAPH_RELATION_TYPES.has(opts.relType)) {
+        throw new Error(`insertRelation: relType must be one of ${Array.from(GRAPH_RELATION_TYPES).join('|')}; got ${opts.relType}`);
+    }
+    const now = new Date().toISOString();
+    const memoryId = opts.memoryId ?? null;
+    const sourceObject = opts.sourceObject ?? null;
+    assertEndpointsInTenant(db, tenantId, opts);
     const { sourceKind, memoryId: effectiveMemoryId } = resolveConsolidatedSource(db, tenantId, memoryId, sourceObject, 'insertRelation');
-    const result = db.prepare(`
-    INSERT INTO relations(tenant_id, from_entity_id, to_entity_id, rel_type, memory_id, source_kind, source_object_type, source_object_id, created_at)
+    const result = db
+        .prepare(`
+    INSERT INTO relations(tenant_id, from_entity_id, to_entity_id, rel_type, memory_id, source_kind, source_object_type,
+    source_object_id, created_at)
     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(tenantId, opts.fromEntityId, opts.toEntityId, opts.relType, effectiveMemoryId, sourceKind, sourceObject?.type ?? null, sourceObject?.id ?? null, now);
+  `)
+        .run(tenantId, opts.fromEntityId, opts.toEntityId, opts.relType, effectiveMemoryId, sourceKind, sourceObject?.type ?? null, sourceObject?.id ?? null, now);
     const id = Number(result.lastInsertRowid ?? 0);
     // SAFETY: row's shape matches the columns named in RELATION_COLS above.
     const row = db.prepare(`SELECT ${RELATION_COLS} FROM relations WHERE id = ?`).get(id);
@@ -151,7 +164,8 @@ export function insertRelationRow(db, tenantId, opts) {
         throw new Error('insertRelation: failed to reload inserted relation');
     return rowToRelation(row);
 }
-/** The source object still holds the loader's rule (active or superseded); a closed or gone one gets no new graph row. */
+/** The source object still holds the loader's rule (active or superseded); a closed or gone one gets no new graph
+ * row. */
 export function objectInForce(db, tenantId, ref) {
     // `table` comes from the fixed SOURCE_OBJECT_TABLE map, never from input.
     const table = SOURCE_OBJECT_TABLE[ref.type];
@@ -162,12 +176,18 @@ export function objectInForce(db, tenantId, ref) {
 /** The lowest-id entity of this type anchored to the source object, which is the row a rebuild keeps. */
 export function entityIdBySource(db, tenantId, entityType, sourceObject) {
     // 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, entityType, sourceObject.type, sourceObject.id);
+    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, entityType, sourceObject.type, sourceObject.id);
     return row?.id;
 }
 export function relationPresent(db, tenantId, fromEntityId, toEntityId, relType) {
     // 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, relType);
+    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, relType);
     return present !== undefined;
 }
 export function deleteEntityRow(db, tenantId, id) {
@@ -177,7 +197,8 @@ export function deleteRelationRow(db, tenantId, id) {
     db.prepare(`DELETE FROM relations WHERE id = ? AND tenant_id = ?`).run(id, tenantId);
 }
 /** 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. */
+ * 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, opts);
@@ -188,8 +209,9 @@ export function runGraphRebuildTransaction(hippoRoot, tenantId, fn, opts) {
         closeHippoDb(db);
     }
 }
-/** Remove graph rows sourced from one MIRRORLESS object by (type, id) on close: with no mirror memory `markGraphDirty` cannot enqueue a rebuild.
- * Fail-soft like `markGraphDirty`; the explicit relations DELETE also covers a relation whose OWN provenance is this object. */
+/** Remove graph rows sourced from one MIRRORLESS object by (type, id) on close: with no mirror memory `markGraphDirty`
+ * cannot enqueue a rebuild. Fail-soft like `markGraphDirty`; the explicit relations DELETE also covers a relation whose
+ * OWN provenance is this object. */
 export function removeGraphEntitiesForObject(hippoRoot, tenantId, sourceObjectType, sourceObjectId) {
     try {
         assertTenantId('removeGraphEntitiesForObject', tenantId);
@@ -203,7 +225,8 @@ export function removeGraphEntitiesForObject(hippoRoot, tenantId, sourceObjectTy
         });
     }
     catch (err) {
-        log.warn(`removeGraphEntitiesForObject: failed for tenant=${tenantId} ${sourceObjectType}#${sourceObjectId}: ${errorMessage(err)}`);
+        log.warn(`removeGraphEntitiesForObject: failed for tenant=${tenantId} ${sourceObjectType}#${sourceObjectId}: ` +
+            `${errorMessage(err)}`, errorFields(err));
     }
 }
 //# sourceMappingURL=graph-writes.js.map

package/dist/store/half-life.js

@@ -34,9 +34,9 @@ function writeMove(db, move, old, actor) {
     const byTenant = new Map();
     for (const e of move.entries) {
         // One record per tenant, filled in place: copying it per row made the write grow with the square of the store.
-        let record = byTenant.get(e.tenantId);
+        let record = byTenant.get(e.tenant_id);
         if (!record)
-            byTenant.set(e.tenantId, (record = {}));
+            byTenant.set(e.tenant_id, (record = {}));
         record[e.id] = old.get(e.id);
     }
     for (const [tenantId, oldHalfLives] of byTenant) {