hippo-memory 1.69.0 → 1.70.0

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

@@ -0,0 +1,67 @@
+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. */
+function readableOnly(db, tenantId, items, canRead) {
+    if (!canRead)
+        return items;
+    const ids = [...new Set(items.flatMap((i) => (i.memoryId === null ? [] : [i.memoryId])))];
+    const readable = new Set();
+    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(',')})`)
+            .all(tenantId, ...slice);
+        for (const r of rows)
+            if (canRead(r.scope))
+                readable.add(r.id);
+    }
+    return items.filter((i) => i.memoryId === null || readable.has(i.memoryId));
+}
+function wholeGraphRows({ hippoRoot, db, tenantId }, limit) {
+    const entities = loadEntities(hippoRoot, tenantId, { limit }, db);
+    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. */
+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.
+    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);
+    if (focus.length === 0)
+        return null;
+    const focusIds = focus.map((e) => e.id);
+    const hop = loadNeighborRelations(hippoRoot, tenantId, focusIds, { limit }, db);
+    const union = new Set(focusIds);
+    let neighboursCapped = false;
+    for (const r of hop) {
+        if (union.size >= limit) {
+            neighboursCapped = true; // node cap filled before all neighbours were added
+            break;
+        }
+        union.add(r.fromEntityId);
+        union.add(r.toEntityId);
+    }
+    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.
+    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
+        neighboursCapped || // node cap filled before all neighbours were consumed
+        union.size > unionIds.length ||
+        relations.length >= limit;
+    return { entities, relations, truncated };
+}
+/** What `GraphReads.graphRows` answers, read on `db`: the caller opens the one 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);
+    if (raw === null)
+        return { entities: [], relations: [], truncated: false };
+    return {
+        entities: readableOnly(db, tenantId, raw.entities, spec.canRead),
+        relations: readableOnly(db, tenantId, raw.relations, spec.canRead),
+        truncated: raw.truncated,
+    };
+}
+//# sourceMappingURL=graph-view-rows.js.map

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

@@ -0,0 +1,58 @@
+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 the `source_kind` for a graph row from AT LEAST ONE valid provenance path,
+ * with the no-raw invariant intact. The code-level mirror of the DB trigger guard (the
+ * trigger is the unbypassable backstop). Two paths:
+ *  - MEMORY path (`memoryId` not null): the memory must exist, be same-tenant, and be
+ *    consolidated (distilled/superseded); raw is rejected. Returns its kind.
+ *  - OBJECT path (`memoryId` null, `sourceObject` set): the object row must exist, be
+ *    same-tenant, and have status active|superseded (4-way per object table). Objects are
+ *    consolidated BY CONSTRUCTION, so this returns 'distilled'.
+ * All-null (no memory AND no source object) 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 extracted from a consolidated memory. Throws if the source
+ * memory is missing / cross-tenant / raw (the DB trigger is the backstop).
+ */
+export declare function insertEntity(hippoRoot: string, tenantId: string, opts: InsertEntityOpts, txDb?: DatabaseSyncLike): Entity;
+/** Renames an entity or moves its memory provenance in place, keeping id and created_at; null when the row is gone.
+ *  A delete plus an insert would cascade away every relation that points at it. */
+export declare function updateEntity(hippoRoot: string, tenantId: string, id: number, opts: UpdateEntityOpts, txDb?: DatabaseSyncLike): Entity | null;
+/**
+ * Insert a graph relation between two entities, sourced from a consolidated memory.
+ * Both entities must exist in the same tenant; the source memory must be consolidated.
+ */
+export declare function insertRelation(hippoRoot: string, tenantId: string, opts: InsertRelationOpts, txDb?: DatabaseSyncLike): Relation;
+/** 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;
+export declare function relationPresent(db: DatabaseSyncLike, tenantId: string, fromEntityId: number, toEntityId: number, relType: RelationType): boolean;
+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. */
+export declare function runGraphRebuildTransaction<T>(hippoRoot: string, tenantId: string, fn: (txDb: DatabaseSyncLike) => T, opts?: {
+    busyWaitMs?: number;
+}): T;
+/**
+ * Remove the graph rows sourced from one first-class object, by its (type, id). Used when a
+ * MIRRORLESS object is closed: it has no mirror memory, so `markGraphDirty` cannot
+ * enqueue a rebuild (the queue is memory-keyed). Closing must still drop the object's
+ * now-stale entity + edges from the graph, so we remove them directly here. Fail-soft
+ * like `markGraphDirty` (never throws into the object close caller; graph staleness is
+ * recoverable). Deleting the entity cascade-deletes any relation where it is an endpoint
+ * (relations FK entities ON DELETE CASCADE); the explicit relations DELETE also covers a
+ * relation whose OWN provenance is this object (defensive — every such edge has the object
+ * as an endpoint today, so the cascade already covers it). DELETE fires no BEFORE
+ * INSERT/UPDATE guard trigger.
+ */
+export declare function removeGraphEntitiesForObject(hippoRoot: string, tenantId: string, sourceObjectType: SourceObjectType, sourceObjectId: number): void;
+export {};
+//# sourceMappingURL=graph-writes.d.ts.map

package/dist/store/graph-writes.js

@@ -0,0 +1,256 @@
+// The writer of the entities and relations tables. Every row resolves a consolidated source first, never a raw memory;
+// the schema triggers are the backstop for a write that skips this module.
+import { openHippoDb, closeHippoDb, withWriteScope } from '../db/index.js';
+import { assertTenantId } from './tenant.js';
+import { errorMessage, log } 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',
+    policy: 'policies',
+    customer: 'customer_notes',
+    project: 'project_briefs',
+};
+export function resolveConsolidatedSource(db, tenantId, memoryId, sourceObject, label) {
+    const { memKind, effectiveMemoryId } = checkSourceMemory(db, tenantId, memoryId, sourceObject, label);
+    assertSourceObjectUsable(db, tenantId, sourceObject, label);
+    // source_kind is the memory's kind when a memory is present, else 'distilled' for an
+    // object-only row (objects are consolidated by construction). All-null is rejected.
+    if (memKind != null)
+        return { sourceKind: memKind, memoryId: effectiveMemoryId };
+    if (sourceObject != null)
+        return { sourceKind: 'distilled', memoryId: null };
+    throw new Error(`${label}: graph row needs a memory or a source object`);
+}
+function checkSourceMemory(db, tenantId, memoryId, sourceObject, label) {
+    let memKind = null;
+    let effectiveMemoryId = memoryId;
+    if (memoryId != null) {
+        // SAFETY: row's shape matches the two columns (kind, tenant_id) named in
+        // 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 provides provenance:
+            // graph-extract reads object rows then inserts, and a mirror forgotten/pruned in that window
+            // must NOT roll back the whole tenant rebuild - the active object survives mirror loss.
+            // Anchor to the object; drop the dead memory pointer.
+            if (sourceObject == null) {
+                throw new Error(`${label}: source memory ${memoryId} not found`);
+            }
+            effectiveMemoryId = null;
+        }
+        else if (row.tenant_id !== tenantId) {
+            throw new Error(`${label}: source memory ${memoryId} belongs to another tenant`);
+        }
+        else if (row.kind === 'raw') {
+            throw new Error(`${label}: source memory ${memoryId} is raw; the graph indexes consolidated state only`);
+        }
+        else if (row.kind !== 'distilled' && row.kind !== 'superseded') {
+            throw new Error(`${label}: source memory ${memoryId} has unsupported kind '${row.kind}'`);
+        }
+        else {
+            memKind = row.kind;
+        }
+    }
+    return { memKind, effectiveMemoryId };
+}
+function assertSourceObjectUsable(db, tenantId, sourceObject, label) {
+    // Validate the object pointer WHENEVER it is provided, not only when memory is null:
+    // a dual-set row whose object is wrong/closed/cross-tenant would become
+    // the active provenance after ON DELETE SET NULL and could then 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 value from the SOURCE_OBJECT_TABLE map (never user-supplied), so
+        // this string 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)`);
+        }
+    }
+}
+/**
+ * Insert a graph entity extracted from a consolidated memory. Throws if the source
+ * memory is missing / cross-tenant / raw (the DB trigger is the backstop).
+ */
+export function insertEntity(hippoRoot, tenantId, opts, txDb) {
+    assertTenantId('insertEntity', tenantId);
+    if (!GRAPH_ENTITY_TYPES.has(opts.entityType)) {
+        throw new Error(`insertEntity: entityType must be one of ${Array.from(GRAPH_ENTITY_TYPES).join('|')}; got ${opts.entityType}`);
+    }
+    const name = checkedName('insertEntity', opts.name);
+    const now = new Date().toISOString();
+    const memoryId = opts.memoryId ?? null;
+    const sourceObject = opts.sourceObject ?? null;
+    const ownDb = txDb ? null : openHippoDb(hippoRoot);
+    const db = txDb ?? ownDb;
+    try {
+        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)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).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);
+        if (!row)
+            throw new Error('insertEntity: failed to reload inserted entity');
+        return rowToEntity(row);
+    }
+    finally {
+        if (ownDb)
+            closeHippoDb(ownDb);
+    }
+}
+function checkedName(label, raw) {
+    const name = (raw ?? '').trim();
+    if (name.length === 0)
+        throw new Error(`${label}: name is required`);
+    if (name.length > MAX_ENTITY_NAME_LEN) {
+        throw new Error(`${label}: name exceeds the ${MAX_ENTITY_NAME_LEN}-char cap`);
+    }
+    return name;
+}
+/** Renames an entity or moves its memory provenance in place, keeping id and created_at; null when the row is gone.
+ *  A delete plus an insert would cascade away every relation that points at it. */
+export function updateEntity(hippoRoot, tenantId, id, opts, txDb) {
+    assertTenantId('updateEntity', tenantId);
+    const name = checkedName('updateEntity', opts.name);
+    const db = txDb ?? openHippoDb(hippoRoot);
+    try {
+        // SAFETY: row's shape matches the columns named in ENTITY_COLS above.
+        const row = db.prepare(`SELECT ${ENTITY_COLS} FROM entities WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
+        if (!row)
+            return null;
+        const entity = rowToEntity(row);
+        const sourceObject = entity.sourceObjectType === undefined || entity.sourceObjectId === undefined
+            ? null
+            : { type: entity.sourceObjectType, id: entity.sourceObjectId };
+        const resolved = resolveConsolidatedSource(db, tenantId, opts.memoryId ?? null, sourceObject, 'updateEntity');
+        db.prepare(`UPDATE entities SET name = ?, memory_id = ?, source_kind = ? WHERE id = ? AND tenant_id = ?`)
+            .run(name, resolved.memoryId, resolved.sourceKind, id, tenantId);
+        return { ...entity, name, memoryId: resolved.memoryId, sourceKind: resolved.sourceKind };
+    }
+    finally {
+        if (db !== txDb)
+            closeHippoDb(db);
+    }
+}
+/**
+ * Insert a graph relation between two entities, sourced from a consolidated memory.
+ * Both entities must exist in the same tenant; the source memory must be consolidated.
+ */
+export function insertRelation(hippoRoot, tenantId, opts, txDb) {
+    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;
+    const ownDb = txDb ? null : openHippoDb(hippoRoot);
+    const db = txDb ?? ownDb;
+    try {
+        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.
+            const ent = db.prepare(`SELECT tenant_id FROM entities WHERE id = ?`).get(eid);
+            if (!ent)
+                throw new Error(`insertRelation: ${role}_entity ${eid} not found`);
+            if (ent.tenant_id !== tenantId) {
+                throw new Error(`insertRelation: ${role}_entity ${eid} belongs to another tenant (no cross-tenant edges)`);
+            }
+        }
+        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)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).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);
+        if (!row)
+            throw new Error('insertRelation: failed to reload inserted relation');
+        return rowToRelation(row);
+    }
+    finally {
+        if (ownDb)
+            closeHippoDb(ownDb);
+    }
+}
+/** 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];
+    // SAFETY: row's shape matches the single `status` column named in the SELECT.
+    const row = db.prepare(`SELECT status FROM ${table} WHERE id = ? AND tenant_id = ?`).get(ref.id, tenantId);
+    return row?.status === 'active' || row?.status === 'superseded';
+}
+/** 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);
+    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);
+    return present !== undefined;
+}
+export function deleteEntityRow(db, tenantId, id) {
+    db.prepare(`DELETE FROM entities WHERE id = ? AND tenant_id = ?`).run(id, tenantId);
+}
+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. */
+export function runGraphRebuildTransaction(hippoRoot, tenantId, fn, opts) {
+    assertTenantId('runGraphRebuildTransaction', tenantId);
+    const db = openHippoDb(hippoRoot, opts);
+    try {
+        return withWriteScope(db, 'graph_rebuild', () => fn(db));
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Remove the graph rows sourced from one first-class object, by its (type, id). Used when a
+ * MIRRORLESS object is closed: it has no mirror memory, so `markGraphDirty` cannot
+ * enqueue a rebuild (the queue is memory-keyed). Closing must still drop the object's
+ * now-stale entity + edges from the graph, so we remove them directly here. Fail-soft
+ * like `markGraphDirty` (never throws into the object close caller; graph staleness is
+ * recoverable). Deleting the entity cascade-deletes any relation where it is an endpoint
+ * (relations FK entities ON DELETE CASCADE); the explicit relations DELETE also covers a
+ * relation whose OWN provenance is this object (defensive — every such edge has the object
+ * as an endpoint today, so the cascade already covers it). DELETE fires no BEFORE
+ * INSERT/UPDATE guard trigger.
+ */
+export function removeGraphEntitiesForObject(hippoRoot, tenantId, sourceObjectType, sourceObjectId) {
+    try {
+        assertTenantId('removeGraphEntitiesForObject', tenantId);
+        const db = openHippoDb(hippoRoot);
+        try {
+            withWriteScope(db, 'remove_graph_entities', () => {
+                db.prepare(`DELETE FROM relations WHERE tenant_id = ? AND source_object_type = ? AND source_object_id = ?`)
+                    .run(tenantId, sourceObjectType, sourceObjectId);
+                db.prepare(`DELETE FROM entities WHERE tenant_id = ? AND source_object_type = ? AND source_object_id = ?`)
+                    .run(tenantId, sourceObjectType, sourceObjectId);
+            });
+        }
+        finally {
+            closeHippoDb(db);
+        }
+    }
+    catch (err) {
+        log.warn(`removeGraphEntitiesForObject: failed for tenant=${tenantId} ${sourceObjectType}#${sourceObjectId}: ${errorMessage(err)}`);
+    }
+}
+//# sourceMappingURL=graph-writes.js.map

package/dist/store/half-life.d.ts

@@ -0,0 +1,34 @@
+import type { MemoryEntry } from '../core/memory.js';
+import { conflictResolveAuditsAt, resolvedConflictsAt } from './conflicts.js';
+import { objectMemoryRowsAt } from './entry-reads.js';
+/** What a move is planned from. The object and conflict rows are read only while the typed move is pending. */
+export interface HalfLifeRows {
+    /** The base the store's memories are on. */
+    from: number;
+    /** True until the store has moved its object memories off their old flat half-life. */
+    typedPending: boolean;
+    all: MemoryEntry[];
+    objectRows: ReturnType<typeof objectMemoryRowsAt>;
+    conflictAudits: ReturnType<typeof conflictResolveAuditsAt>;
+    resolvedConflicts: ReturnType<typeof resolvedConflictsAt>;
+}
+/** Copies carrying their new half-life, and the bases their audit rows name. */
+export interface HalfLifeMove {
+    from: number;
+    to: number;
+    entries: readonly MemoryEntry[];
+}
+/** The base this store's memories are on: 7 days when none was ever recorded. */
+export declare function recordedHalfLifeBase(hippoRoot: string): number;
+/** Moves the store's half-lives to base `to` as `plan` decides from the rows read here, then records the base. `outcome` is null when no move is due; a dry run plans and writes nothing. */
+export declare function moveHalfLives<R>(hippoRoot: string, to: number, opts: {
+    dryRun: boolean;
+    actor: string;
+}, plan: (rows: HalfLifeRows) => {
+    moves: readonly HalfLifeMove[];
+    outcome: R;
+}): {
+    from: number;
+    outcome: R | null;
+};
+//# sourceMappingURL=half-life.d.ts.map

package/dist/store/half-life.js

@@ -0,0 +1,77 @@
+// A half-life move reads, writes, audits and records its base on one handle, so it commits whole or not at all.
+import { closeHippoDb, getMeta, openHippoDb, setMeta, withWriteScope } from '../db/index.js';
+import { appendAuditEvent } from './audit.js';
+import { conflictResolveAuditsAt, resolvedConflictsAt } from './conflicts.js';
+import { objectMemoryRowsAt, selectAllEntries } from './entry-reads.js';
+import { setHalfLivesAt } from './entry-writes.js';
+import { HALF_LIFE_BASE_META_KEY, TYPED_HALF_LIFE_META_KEY, openStore } from './open.js';
+/** The base every store used before the base was recorded. */
+const LEGACY_HALF_LIFE_BASE = 7;
+function readBase(db) {
+    const raw = Number(getMeta(db, HALF_LIFE_BASE_META_KEY, String(LEGACY_HALF_LIFE_BASE)));
+    return Number.isFinite(raw) && raw > 0 ? raw : LEGACY_HALF_LIFE_BASE;
+}
+/** The base this store's memories are on: 7 days when none was ever recorded. */
+export function recordedHalfLifeBase(hippoRoot) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        return readBase(db);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+function readRows(db, from, typedPending) {
+    const all = selectAllEntries(db);
+    return {
+        from,
+        typedPending,
+        all,
+        objectRows: typedPending ? objectMemoryRowsAt(db) : [],
+        conflictAudits: typedPending ? conflictResolveAuditsAt(db) : [],
+        resolvedConflicts: typedPending ? resolvedConflictsAt(db) : [],
+    };
+}
+/** Writes the move, then one audit event per tenant with each id's old half-life, so the move can be undone. */
+function writeMove(db, move, old, actor) {
+    setHalfLivesAt(db, move.entries.map((e) => ({ id: e.id, halfLifeDays: e.half_life_days })));
+    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);
+        if (!record)
+            byTenant.set(e.tenantId, (record = {}));
+        record[e.id] = old.get(e.id);
+    }
+    for (const [tenantId, oldHalfLives] of byTenant) {
+        appendAuditEvent(db, { tenantId, actor, op: 'half_life_migrate', metadata: { from: move.from, to: move.to, ids: Object.keys(oldHalfLives), oldHalfLives } });
+    }
+}
+/** Moves the store's half-lives to base `to` as `plan` decides from the rows read here, then records the base. `outcome` is null when no move is due; a dry run plans and writes nothing. */
+export function moveHalfLives(hippoRoot, to, opts, plan) {
+    const db = openStore(hippoRoot);
+    try {
+        const run = () => {
+            const from = readBase(db);
+            const typedPending = getMeta(db, TYPED_HALF_LIFE_META_KEY, '') === '';
+            if (!(Number.isFinite(to) && to > 0) || (from === to && !typedPending))
+                return { from, outcome: null };
+            const rows = readRows(db, from, typedPending);
+            const { moves, outcome } = plan(rows);
+            if (opts.dryRun)
+                return { from, outcome };
+            const old = new Map(rows.all.map((e) => [e.id, e.half_life_days]));
+            for (const move of moves)
+                writeMove(db, move, old, opts.actor);
+            setMeta(db, HALF_LIFE_BASE_META_KEY, String(to));
+            setMeta(db, TYPED_HALF_LIFE_META_KEY, '1');
+            return { from, outcome };
+        };
+        // Plan, write, audit and record the base under one write lock, so a concurrent write or sleep cannot interleave.
+        return opts.dryRun ? run() : withWriteScope(db, 'migrate_half_life', run);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=half-life.js.map

package/dist/store/handoffs.d.ts

@@ -1,4 +1,4 @@
-import { type SessionHandoff, type HandoffOutcome, type HandoffEvidence } from '../handoff.js';
+import { type SessionHandoff, type HandoffOutcome, type HandoffEvidence } from '../core/handoff.js';
 import type { TaskSnapshot } from './rows.js';
 import { type ContinuityKey } from './sessions.js';
 /** Column list shared by every session_handoffs SELECT; store-cards.ts reuses it for the card handoff lookup. */

package/dist/store/handoffs.js

@@ -1,7 +1,7 @@
-import { closeHippoDb, openHippoDb } from '../db.js';
-import { rowToSessionHandoff, isHandoffOutcome, } from '../handoff.js';
-import { scopeAdmitSql } from '../recall-scope.js';
-import { assertTenantId } from '../tenant.js';
+import { closeHippoDb, openHippoDb } from '../db/index.js';
+import { rowToSessionHandoff, isHandoffOutcome, } from '../core/handoff.js';
+import { scopeAdmitSql } from './recall-scope.js';
+import { assertTenantId } from './tenant.js';
 import { openStore } from './open.js';
 import { continuityStamp, continuityWhere, loadActiveTaskSnapshot } from './sessions.js';
 /** Column list shared by every session_handoffs SELECT; store-cards.ts reuses it for the card handoff lookup. */
@@ -149,6 +149,36 @@ function replaceTranscriptHandoff(hippoRoot, tenantId, handoff, key) {
         closeHippoDb(db);
     }
 }
+function transcriptHandoffSource(existing, derived, evidence) {
+    // Only an earlier transcript read gives way; `hippo handoff create` and unmarked older handoffs keep winning.
+    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)
+        return null;
+    return { snapshot: { ...derived, scope: null }, evidence: { ...evidence, derivedFrom: 'transcript' } };
+}
+function buildSessionEndHandoff(sessionId, snapshot, existing, handoffEvidence, outcome) {
+    // A same-task refresh carries forward envelope fields nobody cleared; a scope
+    // mismatch must not leak private metadata into an unscoped envelope.
+    const carryForward = existing != null && existing.taskId === snapshot.task
+        && (existing.scope ?? null) === (snapshot.scope ?? null);
+    return {
+        version: 1,
+        sessionId,
+        repoRoot: carryForward ? existing.repoRoot : undefined,
+        taskId: snapshot.task,
+        summary: snapshot.summary,
+        nextAction: snapshot.next_step,
+        artifacts: carryForward ? existing.artifacts : [],
+        scope: snapshot.scope,
+        evidence: handoffEvidence,
+        outcome,
+        constraints: carryForward ? existing.constraints : undefined,
+        targetRuntime: carryForward ? existing.targetRuntime : undefined,
+        cardId: carryForward ? existing.cardId : undefined,
+    };
+}
 /** Auto-write a handoff at session-end from the session's active snapshot, else from `derived`, its transcript state.
  * @param evidence best-effort git state; outcome comes from the newest session_complete event.
  * @param options.inPlace rewrite an earlier transcript read instead of adding a revision, for a close that runs after every reply.
@@ -171,36 +201,15 @@ export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence,
         snapshot = active;
     }
     else {
-        // Only an earlier transcript read gives way; `hippo handoff create` and unmarked older handoffs keep winning.
-        if (!derived || (existing && existing.evidence?.derivedFrom !== 'transcript'))
+        const fromDerived = transcriptHandoffSource(existing, derived, evidence);
+        if (!fromDerived)
             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)
-            return null;
-        snapshot = { ...derived, scope: null };
-        handoffEvidence = { ...evidence, derivedFrom: 'transcript' };
+        snapshot = fromDerived.snapshot;
+        handoffEvidence = fromDerived.evidence;
         fromTranscript = true;
     }
     const outcome = sessionOutcome(hippoRoot, tenantId, sessionId);
-    // A same-task refresh carries forward envelope fields nobody cleared; a scope
-    // mismatch must not leak private metadata into an unscoped envelope.
-    const carryForward = existing != null && existing.taskId === snapshot.task
-        && (existing.scope ?? null) === (snapshot.scope ?? null);
-    const handoff = {
-        version: 1,
-        sessionId,
-        repoRoot: carryForward ? existing.repoRoot : undefined,
-        taskId: snapshot.task,
-        summary: snapshot.summary,
-        nextAction: snapshot.next_step,
-        artifacts: carryForward ? existing.artifacts : [],
-        scope: snapshot.scope,
-        evidence: handoffEvidence,
-        outcome,
-        constraints: carryForward ? existing.constraints : undefined,
-        targetRuntime: carryForward ? existing.targetRuntime : undefined,
-        cardId: carryForward ? existing.cardId : undefined,
-    };
+    const handoff = buildSessionEndHandoff(sessionId, snapshot, existing, handoffEvidence, outcome);
     // A miss means a handoff landed since the read, and a new transcript row would hide it.
     if (fromTranscript && options.inPlace && existing)
         return replaceTranscriptHandoff(hippoRoot, tenantId, handoff, key);

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

@@ -1,13 +1,16 @@
+import { type DatabaseSyncLike } from '../db/index.js';
 import type { HippoIndex, LegacyStats } from './rows.js';
 /** Load the derived index from SQLite. Read-only: index.json is only ever written by `rebuildIndex`. */
 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 themselves are derived from SQLite.
  *
  * `last_retrieval_ids` and `last_trace_id` commit in one transaction: callers fold a fresh trace id
  * into the index and rely on both keys moving together. index.json is left to `rebuildIndex`.
  */
-export declare function saveIndex(hippoRoot: string, index: HippoIndex): void;
+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.
  */
@@ -17,6 +20,8 @@ export declare function updateStats(hippoRoot: string, delta: {
     recalled?: number;
     forgotten?: number;
 }): void;
+/** updateStats on the caller's open store, so a loop of writes opens the store once. */
+export declare function updateStatsOn(db: DatabaseSyncLike, hippoRoot: string, delta: Parameters<typeof updateStats>[1]): void;
 export declare function updateStatsUnlessBusy(hippoRoot: string, delta: Parameters<typeof updateStats>[1], committed: string): void;
 export declare function loadStats(hippoRoot: string): LegacyStats;
 export declare function appendConsolidationRun(hippoRoot: string, run: {
@@ -36,6 +41,8 @@ export interface SessionDecayContext {
     /** Average interval between recent sleep cycles, in days. 0 if < 2 cycles. */
     avgSessionIntervalDays: number;
 }
+/** Timestamp of the latest consolidation run, or undefined when there is none. */
+export declare function lastConsolidationAt(db: DatabaseSyncLike): string | undefined;
 /**
  * Load the session decay context from the store.
  * Uses consolidation_runs timestamps to compute session intervals.