hippo-memory 2.0.0 → 2.1.0

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,6 +1,7 @@
-import { IN_LIST_CHUNK, loadEntities, loadEntitiesByIds, loadEntitiesByName, loadNeighborRelations, loadRelations, loadRelationsAmong } from './graph-reads.js';
+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. */
+/** 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;
@@ -9,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 (${placeholders(slice.length)})`)
+        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))
@@ -22,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);
@@ -44,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
@@ -57,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/handoffs.d.ts

@@ -5,7 +5,7 @@ import { type ContinuityKey } from './sessions.js';
 export declare const HANDOFF_COLUMNS: string;
 /** Save a session handoff record; returns the persisted handoff. */
 export declare function saveSessionHandoff(hippoRoot: string, tenantId: string, handoff: Omit<SessionHandoff, 'updatedAt'>, key?: ContinuityKey): SessionHandoff;
-interface HandoffFilter {
+export interface HandoffFilter {
     unfinishedOnly?: boolean;
     maxAgeMs?: number;
     scopeFilter?: 'default-deny';
@@ -25,8 +25,8 @@ export interface SessionEndHandoffRequest {
     readonly key?: ContinuityKey;
     readonly inPlace?: boolean;
 }
-/** Session-end handoff from the active snapshot, else `derived` transcript state; `inPlace` rewrites an earlier transcript read instead of adding a revision.
- * Returns null when no source is the session's, a newer handoff covers it, or the latest one is not transcript-derived or already holds `derived`. */
+/** Session-end handoff from the active snapshot, else `derived` transcript state; `inPlace` rewrites an earlier
+ * transcript read instead of adding a revision. Returns null when no source is the session's, a newer handoff covers
+ * it, or the latest one is not transcript-derived or already holds `derived`. */
 export declare function writeSessionEndHandoff(hippoRoot: string, request: SessionEndHandoffRequest): SessionHandoff | null;
-export {};
 //# sourceMappingURL=handoffs.d.ts.map

package/dist/store/handoffs.js

@@ -7,6 +7,14 @@ import { continuityStamp, continuityWhere, loadActiveTaskSnapshot } from './sess
 /** Column list shared by every session_handoffs SELECT; cards.ts reuses it for the card handoff lookup. */
 export const HANDOFF_COLUMNS = 'id, session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, created_at, constraints_json, ' +
     'evidence_json, outcome, target_runtime, card_id';
+function insertHandoffRow(db, tenantId, handoff, stamp, now) {
+    return db
+        .prepare(`\n      INSERT INTO session_handoffs(session_id, repo_root, task_id, summary, next_action, artifacts_json, ` +
+        `scope, tenant_id, created_at, ` +
+        `constraints_json, evidence_json, outcome, target_runtime, card_id, owner_subject, origin_project)\n` +
+        `      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\n    `)
+        .run(handoff.sessionId, handoff.repoRoot ?? null, handoff.taskId ?? null, handoff.summary, handoff.nextAction ?? null, JSON.stringify(handoff.artifacts ?? []), handoff.scope ?? null, tenantId, now, JSON.stringify(handoff.constraints ?? []), handoff.evidence ? JSON.stringify(handoff.evidence) : null, handoff.outcome ?? null, handoff.targetRuntime ?? null, handoff.cardId ?? null, stamp?.owner ?? null, stamp?.origin ?? null);
+}
 /** Save a session handoff record; returns the persisted handoff. */
 export function saveSessionHandoff(hippoRoot, tenantId, handoff, key) {
     assertTenantId('saveSessionHandoff', tenantId);
@@ -16,9 +24,7 @@ export function saveSessionHandoff(hippoRoot, tenantId, handoff, key) {
     // Scope is stored as given; read-side default-deny in api.recall + cmdRecall
     // continuity excludes slack:private:* and 'unknown:legacy'.
     try {
-        const result = db.prepare(`\n      INSERT INTO session_handoffs(session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, tenant_id, created_at, ` +
-            `constraints_json, evidence_json, outcome, target_runtime, card_id, owner_subject, origin_project)\n` +
-            `      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\n    `).run(handoff.sessionId, handoff.repoRoot ?? null, handoff.taskId ?? null, handoff.summary, handoff.nextAction ?? null, JSON.stringify(handoff.artifacts ?? []), handoff.scope ?? null, tenantId, now, JSON.stringify(handoff.constraints ?? []), handoff.evidence ? JSON.stringify(handoff.evidence) : null, handoff.outcome ?? null, handoff.targetRuntime ?? null, handoff.cardId ?? null, stamp?.owner ?? null, stamp?.origin ?? null);
+        const result = insertHandoffRow(db, tenantId, handoff, stamp, now);
         const id = Number(result.lastInsertRowid ?? 0);
         // SAFETY: row's shape matches HANDOFF_COLUMNS.
         const row = db.prepare(`SELECT ${HANDOFF_COLUMNS} FROM session_handoffs WHERE id = ?`).get(id);
@@ -48,9 +54,11 @@ function handoffConditions(tenantId, sessionId, opts, key) {
         params.push(opts.excludeSessionId);
     }
     if (opts.unfinishedOnly) {
-        // Restrict to each session's newest revision first: stampHandoffOutcome only stamps the newest row, so an older null-outcome revision must not resurrect.
-        // Keyed, the newest is the owner's own, so another owner's newer revision cannot hide it.
-        conditions.push(`id IN (SELECT MAX(id) FROM session_handoffs WHERE tenant_id = ?${owned ? ` AND ${owned.sql}` : ''} GROUP BY session_id)`);
+        // Restrict to each session's newest revision first: stampHandoffOutcome only stamps the newest row, so an older
+        // null-outcome revision must not resurrect. Keyed, the newest is the owner's own, so another owner's newer revision
+        // cannot hide it.
+        conditions.push(`id IN (SELECT MAX(id) FROM session_handoffs WHERE tenant_id = ?${owned ? ` AND ${owned.sql}` : ''} GROUP BY ` +
+            `session_id)`);
         params.push(tenantId, ...(owned?.params ?? []));
         conditions.push(`(outcome IS NULL OR outcome IN ('partial','failure'))`);
     }
@@ -107,7 +115,8 @@ export function loadHandoffById(hippoRoot, tenantId, id) {
 export function stampHandoffOutcome(hippoRoot, tenantId, sessionId, outcome) {
     assertTenantId('stampHandoffOutcome', tenantId);
     return onHandle(hippoRoot, (db) => {
-        const result = db.prepare(`
+        const result = db
+            .prepare(`
       UPDATE session_handoffs SET outcome = ?
       WHERE tenant_id = ? AND session_id = ? AND outcome IS NULL
         AND id = (
@@ -115,21 +124,27 @@ export function stampHandoffOutcome(hippoRoot, tenantId, sessionId, outcome) {
           WHERE tenant_id = ? AND session_id = ?
           ORDER BY created_at DESC, id DESC LIMIT 1
         )
-    `).run(outcome, tenantId, sessionId, tenantId, sessionId);
+    `)
+            .run(outcome, tenantId, sessionId, tenantId, sessionId);
         return Number(result.changes ?? 0);
     }, openStore);
 }
-/** Rewrites the session's newest handoff when it is still a transcript read, in one statement so a handoff written meanwhile is never overwritten; null
- * when none was rewritten. */
+/** Rewrites the session's newest handoff when it is still a transcript read, in one statement so a handoff written
+ * meanwhile is never overwritten; null when none was rewritten. */
 function replaceTranscriptHandoff(hippoRoot, tenantId, handoff, key) {
     const { conditions, params } = handoffConditions(tenantId, handoff.sessionId, {}, key);
-    const newest = `SELECT id FROM session_handoffs WHERE ${conditions.join(' AND ')} ORDER BY created_at DESC, id DESC LIMIT 1`;
+    const newest = `SELECT id FROM session_handoffs WHERE ${conditions.join(' AND ')} ORDER BY created_at DESC, id ` +
+        `DESC LIMIT 1`;
     return onHandle(hippoRoot, (db) => {
-        const result = db.prepare(`
-      UPDATE session_handoffs SET repo_root = ?, task_id = ?, summary = ?, next_action = ?, artifacts_json = ?, scope = ?, created_at = ?,
+        const result = db
+            .prepare(`
+      UPDATE session_handoffs SET repo_root = ?, task_id = ?, summary = ?, next_action = ?, artifacts_json = ?, scope =
+      ?, created_at = ?,
         constraints_json = ?, evidence_json = ?, outcome = ?, target_runtime = ?, card_id = ?
-      WHERE id = (${newest}) AND json_valid(evidence_json) AND json_extract(evidence_json, '$.derivedFrom') = 'transcript'
-    `).run(handoff.repoRoot ?? null, handoff.taskId ?? null, handoff.summary, handoff.nextAction ?? null, JSON.stringify(handoff.artifacts ?? []), handoff.scope ?? null, new Date().toISOString(), JSON.stringify(handoff.constraints ?? []), handoff.evidence ? JSON.stringify(handoff.evidence) : null, handoff.outcome ?? null, handoff.targetRuntime ?? null, handoff.cardId ?? null, ...params);
+      WHERE id = (${newest}) AND json_valid(evidence_json) AND json_extract(evidence_json, '$.derivedFrom') =
+      'transcript'
+    `)
+            .run(handoff.repoRoot ?? null, handoff.taskId ?? null, handoff.summary, handoff.nextAction ?? null, JSON.stringify(handoff.artifacts ?? []), handoff.scope ?? null, new Date().toISOString(), JSON.stringify(handoff.constraints ?? []), handoff.evidence ? JSON.stringify(handoff.evidence) : null, handoff.outcome ?? null, handoff.targetRuntime ?? null, handoff.cardId ?? null, ...params);
         if (Number(result.changes ?? 0) === 0)
             return null;
         // SAFETY: row's shape matches HANDOFF_COLUMNS.
@@ -142,8 +157,12 @@ function transcriptHandoffSource(existing, derived, evidence) {
     if (!derived || (existing && existing.evidence?.derivedFrom !== 'transcript'))
         return null;
     // A retried session end reads the same transcript, so it must not add a second revision.
-    if (existing && existing.taskId === derived.task && existing.summary === derived.summary && existing.nextAction === derived.next_step)
+    if (existing &&
+        existing.taskId === derived.task &&
+        existing.summary === derived.summary &&
+        existing.nextAction === derived.next_step) {
         return null;
+    }
     return { snapshot: { ...derived, scope: null }, evidence: { ...evidence, derivedFrom: 'transcript' } };
 }
 function buildSessionEndHandoff(sessionId, snapshot, existing, handoffEvidence, outcome) {
@@ -167,8 +186,9 @@ function buildSessionEndHandoff(sessionId, snapshot, existing, handoffEvidence,
         cardId: carryForward ? existing.cardId : undefined,
     };
 }
-/** Session-end handoff from the active snapshot, else `derived` transcript state; `inPlace` rewrites an earlier transcript read instead of adding a revision.
- * Returns null when no source is the session's, a newer handoff covers it, or the latest one is not transcript-derived or already holds `derived`. */
+/** Session-end handoff from the active snapshot, else `derived` transcript state; `inPlace` rewrites an earlier
+ * transcript read instead of adding a revision. Returns null when no source is the session's, a newer handoff covers
+ * it, or the latest one is not transcript-derived or already holds `derived`. */
 export function writeSessionEndHandoff(hippoRoot, request) {
     const { tenantId, sessionId, evidence, derived = null, key, inPlace } = request;
     assertTenantId('writeSessionEndHandoff', tenantId);
@@ -179,7 +199,8 @@ export function writeSessionEndHandoff(hippoRoot, request) {
     let snapshot;
     let handoffEvidence = evidence;
     let fromTranscript = false;
-    // After every reply the transcript is newer than the last compaction's snapshot, which the open chat keeps for the next one.
+    // After every reply the transcript is newer than the last compaction's snapshot, which the open chat keeps for the
+    // next one.
     const snapshotGivesWay = inPlace === true && derived !== null && active?.source === 'pre-compact';
     if (active && active.session_id === sessionId && !snapshotGivesWay) {
         // Strict '>': a same-millisecond tie must not swallow the session's only write (test 6e).

package/dist/store/index-and-stats.d.ts

@@ -4,8 +4,8 @@ import type { HippoIndex, LegacyStats } from './rows.js';
 export declare function loadIndex(hippoRoot: string): HippoIndex;
 /** The last recall's ids and its trace alone, for a caller that needs no index entry. */
 export declare function loadLastRecall(hippoRoot: string): Pick<HippoIndex, 'last_retrieval_ids' | 'last_trace_id'>;
-/** Persist mutable index metadata (entry rows are derived from SQLite); `last_retrieval_ids` and `last_trace_id` commit in one transaction, as callers
- * rely on both moving together. index.json is left to `rebuildIndex`. */
+/** Persist mutable index metadata (entry rows are derived from SQLite); `last_retrieval_ids` and `last_trace_id` commit
+ * in one transaction, as callers rely on both moving together. index.json is left to `rebuildIndex`. */
 export declare function saveIndex(hippoRoot: string, index: Pick<HippoIndex, 'last_retrieval_ids' | 'last_trace_id'>): void;
 /** Rebuild mirrors from SQLite, importing any legacy markdown files not already present. */
 export declare function rebuildIndex(hippoRoot: string): HippoIndex;

package/dist/store/index-and-stats.js

@@ -1,9 +1,9 @@
-import { withWriteScope, setMeta, isSqliteBusy, pruneConsolidationRuns, getMeta } from '../db/index.js';
+import { withWriteScope, setMeta, isSqliteBusy, pruneConsolidationRuns, getMeta, } from '../db/index.js';
 import { RejectedValueError } from '../core/api-errors.js';
 import { log } from '../util/log.js';
 import { audit } from './audit-event.js';
 import { stampOriginProjectForImport, upsertEntryRow } from './entry-row.js';
-import { buildIndexFromDb, readLastRecall, syncMirrorFiles, writeIndexMirror, writeStatsMirror, buildStatsFromDb } from './mirrors.js';
+import { buildIndexFromDb, readLastRecall, syncMirrorFiles, writeIndexMirror, writeStatsMirror, buildStatsFromDb, } from './mirrors.js';
 import { onHandle, openStore, loadLegacyEntriesFromMarkdown } from './open.js';
 import { DAY_MS } from '../util/time.js';
 /** Load the derived index from SQLite. Read-only: index.json is only ever written by `rebuildIndex`. */
@@ -18,8 +18,8 @@ export function loadLastRecall(hippoRoot) {
         return readLastRecall(db);
     }, openStore);
 }
-/** Persist mutable index metadata (entry rows are derived from SQLite); `last_retrieval_ids` and `last_trace_id` commit in one transaction, as callers
- * rely on both moving together. index.json is left to `rebuildIndex`. */
+/** Persist mutable index metadata (entry rows are derived from SQLite); `last_retrieval_ids` and `last_trace_id` commit
+ * in one transaction, as callers rely on both moving together. index.json is left to `rebuildIndex`. */
 export function saveIndex(hippoRoot, index) {
     onHandle(hippoRoot, (db) => {
         withWriteScope(db, 'save_index', () => {
@@ -77,7 +77,8 @@ export function updateStats(hippoRoot, delta) {
 }
 /** updateStats on the caller's open store, so a loop of writes opens the store once. */
 export function updateStatsOn(db, hippoRoot, delta) {
-    // One atomic statement per named counter: a read-modify-write loses concurrent increments and stamps stale values over the untouched two.
+    // One atomic statement per named counter: a read-modify-write loses concurrent increments and stamps stale values
+    // over the untouched two.
     const increments = [
         ['total_remembered', delta.remembered ?? 0],
         ['total_recalled', delta.recalled ?? 0],

package/dist/store/index.d.ts

@@ -1,4 +1,6 @@
-export type { AmbientCandidateRequest, ContextReads, EntryRemoval, EntryTarget, EntryWrite, EntryWrites, HippoStore, KeyAudit, KeyListQuery, KeyMint, KeyRevoke, KeyWrites, LastRecall, LastRecallWrites, OutcomeWrite, RawArchive, RecallSearchArgs, RecallWrites, SelfKeyMint, StoreGroup, StoreGroups, SupersedeWrite, VectorBackfillQuery, VectorReads, VectorRowWrite, VectorWrite, VectorWriteResult, VectorWrites, } from './port.js';
+export type { AmbientCandidateRequest, ContextReads, EntryRemoval, EntryTarget, EntryWrite, EntryWrites, HippoStore, KeyAudit, KeyListQuery, KeyMint, KeyRevoke, KeyGrants, KeyWrites, LastRecall, LastRecallWrites, OutcomeWrite, RawArchive, RecallSearchArgs, RecallWrites, SelfKeyMint, StoreGroup, StoreGroups, SupersedeWrite, VectorBackfillQuery, VectorReads, VectorRowWrite, VectorWrite, VectorWriteResult, VectorWrites, } from './port.js';
+export type { CardCreate, Cards, Conflicts, Dormant, DormantRestoreRequest, Goals, Reports, Sessions, WorkingMemoryFilter, WorkingMemoryPush, } from './port-groups.js';
 export { hasGroup, requireGroup } from './port.js';
+export { narrowStore, type StoreWith } from './narrow.js';
 export { sqliteStore } from './sqlite/store.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/store/index.js

@@ -1,3 +1,4 @@
 export { hasGroup, requireGroup } from './port.js';
+export { narrowStore } from './narrow.js';
 export { sqliteStore } from './sqlite/store.js';
 //# sourceMappingURL=index.js.map

package/dist/store/key-audit.d.ts

@@ -1,6 +1,7 @@
 import { type DatabaseSyncLike } from '../db/index.js';
 import type { KeyRevoke } from './port.js';
-/** The revoke and its audit row commit together, so a failed audit write leaves the key live and the caller sees the error. */
+/** The revoke and its audit row commit together, so a failed audit write leaves the key live and the caller sees the
+ * error. */
 export declare function revokeKeyAt(db: DatabaseSyncLike, revoke: KeyRevoke): string;
 export declare function auditHighIdAt(db: DatabaseSyncLike): number;
 //# sourceMappingURL=key-audit.d.ts.map