hippo-memory 1.71.0 → 2.0.0

package/dist/store/graph-reads.js

@@ -1,9 +1,11 @@
 // 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';
-const DEFAULT_GRAPH_PAGE_SIZE = 100;
+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. */
@@ -99,7 +101,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
@@ -132,7 +134,7 @@ export function loadNeighborRelations(hippoRoot, tenantId, entityIds, opts = {},
         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
@@ -163,7 +165,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
@@ -188,7 +190,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(`
@@ -207,7 +209,8 @@ export function storedGraphOn(db, tenantId, 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);
     // 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);
+    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);
     return { kinds, entities, relations };
 }
 function memoryKindsOn(db, memoryIds) {

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

@@ -1,4 +1,5 @@
 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)
@@ -8,7 +9,7 @@ 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))

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

@@ -7,13 +7,13 @@ interface ResolvedGraphSource {
     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.
+/** 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. */
-export declare function updateEntity(hippoRoot: string, tenantId: string, id: number, opts: UpdateEntityOpts, txDb?: DatabaseSyncLike): Entity | null;
-/** Insert a graph relation between two same-tenant entities, sourced from a consolidated memory. */
-export declare function insertRelation(hippoRoot: string, tenantId: string, opts: InsertRelationOpts, txDb?: DatabaseSyncLike): Relation;
+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. */
+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. */
 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. */

package/dist/store/graph-writes.js

@@ -71,8 +71,8 @@ function assertSourceObjectUsable(db, tenantId, sourceObject, label) {
         }
     }
 }
-/** 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) {
+/** 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)) {
         throw new Error(`insertEntity: entityType must be one of ${Array.from(GRAPH_ENTITY_TYPES).join('|')}; got ${opts.entityType}`);
@@ -81,25 +81,17 @@ export function insertEntity(hippoRoot, tenantId, opts, txDb) {
     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);
-    }
+    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);
 }
 function checkedName(label, raw) {
     const name = (raw ?? '').trim();
@@ -110,33 +102,26 @@ function checkedName(label, raw) {
     }
     return name;
 }
-/** Renames an entity or moves its memory provenance in place, keeping id and created_at; null when the row is gone.
+/** 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 updateEntity(hippoRoot, tenantId, id, opts, txDb) {
+export function updateEntityRow(db, tenantId, id, opts) {
     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);
-    }
+    // 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 };
 }
-/** Insert a graph relation between two same-tenant entities, sourced from a consolidated memory. */
-export function insertRelation(hippoRoot, tenantId, opts, txDb) {
+/** 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}`);
@@ -144,35 +129,27 @@ export function insertRelation(hippoRoot, tenantId, opts, txDb) {
     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)`);
-            }
+    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);
     }
+    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);
 }
 /** 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) {

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) {

package/dist/store/handoffs.d.ts

@@ -2,7 +2,7 @@ import { type SessionHandoff, type HandoffOutcome, type HandoffEvidence } from '
 import type { TaskSnapshot } from './rows.js';
 import { type ContinuityKey } from './sessions.js';
 /** Column list shared by every session_handoffs SELECT; cards.ts reuses it for the card handoff lookup. */
-export declare 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";
+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 {
@@ -17,10 +17,16 @@ export declare function loadLatestHandoff(hippoRoot: string, tenantId: string, s
 export declare function loadHandoffById(hippoRoot: string, tenantId: string, id: number): SessionHandoff | null;
 /** Stamp the outcome on a session's newest handoff, only if it has none yet. Returns rows changed. */
 export declare function stampHandoffOutcome(hippoRoot: string, tenantId: string, sessionId: string, outcome: HandoffOutcome): number;
+export interface SessionEndHandoffRequest {
+    readonly tenantId: string;
+    readonly sessionId: string;
+    readonly evidence: HandoffEvidence | null;
+    readonly derived?: Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'> | null;
+    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`. */
-export declare function writeSessionEndHandoff(hippoRoot: string, tenantId: string, sessionId: string, evidence: HandoffEvidence | null, derived?: Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'> | null, key?: ContinuityKey, options?: {
-    inPlace?: boolean;
-}): SessionHandoff | null;
+export declare function writeSessionEndHandoff(hippoRoot: string, request: SessionEndHandoffRequest): SessionHandoff | null;
 export {};
 //# sourceMappingURL=handoffs.d.ts.map

package/dist/store/handoffs.js

@@ -1,11 +1,12 @@
 import { closeHippoDb } from '../db/index.js';
 import { rowToSessionHandoff, isHandoffOutcome, } from '../core/handoff.js';
-import { scopeAdmitSql } from './recall-scope.js';
+import { scopeAdmitSql } from './rule-sql.js';
 import { assertTenantId } from './tenant.js';
 import { onHandle, openStore } from './open.js';
 import { continuityStamp, continuityWhere, loadActiveTaskSnapshot } from './sessions.js';
 /** 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';
+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';
 /** Save a session handoff record; returns the persisted handoff. */
 export function saveSessionHandoff(hippoRoot, tenantId, handoff, key) {
     assertTenantId('saveSessionHandoff', tenantId);
@@ -15,10 +16,9 @@ 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(`
-      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)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).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 = 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 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);
@@ -169,7 +169,8 @@ function buildSessionEndHandoff(sessionId, snapshot, existing, handoffEvidence,
 }
 /** 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, tenantId, sessionId, evidence, derived = null, key, options = {}) {
+export function writeSessionEndHandoff(hippoRoot, request) {
+    const { tenantId, sessionId, evidence, derived = null, key, inPlace } = request;
     assertTenantId('writeSessionEndHandoff', tenantId);
     if (key)
         continuityStamp(key); // a partial key is a caller bug, so fail loud rather than write nothing
@@ -179,7 +180,7 @@ export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence,
     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.
-    const snapshotGivesWay = options.inPlace === true && derived !== null && active?.source === 'pre-compact';
+    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).
         if (existing && existing.updatedAt > active.updated_at)
@@ -197,7 +198,7 @@ export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence,
     const outcome = sessionOutcome(hippoRoot, tenantId, sessionId);
     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)
+    if (fromTranscript && inPlace && existing)
         return replaceTranscriptHandoff(hippoRoot, tenantId, handoff, key);
     return saveSessionHandoff(hippoRoot, tenantId, handoff, key);
 }

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

@@ -1,5 +1,5 @@
 import { withWriteScope, setMeta, isSqliteBusy, pruneConsolidationRuns, getMeta } from '../db/index.js';
-import { RejectedValueError } from './rejection.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';
@@ -113,7 +113,7 @@ export function loadStats(hippoRoot) {
 export function appendConsolidationRun(hippoRoot, run) {
     onHandle(hippoRoot, (db) => {
         db.prepare(`INSERT INTO consolidation_runs(timestamp, decayed, merged, removed) VALUES (?, ?, ?, ?)`).run(run.timestamp, run.decayed, run.merged, run.removed);
-        pruneConsolidationRuns(db, 50);
+        pruneConsolidationRuns(db);
         writeStatsMirror(hippoRoot, buildStatsFromDb(db));
     }, openStore);
 }

package/dist/store/index.d.ts

@@ -1,4 +1,4 @@
-export type { AmbientCandidateRequest, ContextReads, EntryRemoval, EntryTarget, EntryWrite, EntryWrites, HippoStore, KeyAudit, KeyListQuery, KeyMint, KeyRevoke, KeyWrites, 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, KeyWrites, LastRecall, LastRecallWrites, OutcomeWrite, RawArchive, RecallSearchArgs, RecallWrites, SelfKeyMint, StoreGroup, StoreGroups, SupersedeWrite, VectorBackfillQuery, VectorReads, VectorRowWrite, VectorWrite, VectorWriteResult, VectorWrites, } from './port.js';
 export { hasGroup, requireGroup } from './port.js';
-export * from './sqlite/store.js';
+export { sqliteStore } from './sqlite/store.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/store/index.js

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

package/dist/store/key-writes.js

@@ -3,7 +3,7 @@ import { BadRequestError, ConflictError, NotFoundError } from '../core/api-error
 import { appendAuditEvent } from './audit.js';
 import { grantScope, insertApiKey, listLiveOwnedKeyIds, revokeApiKey, ungrantScope } from './auth.js';
 import { withWriteScope } from '../db/index.js';
-import { isRestrictedScope } from './recall-scope.js';
+import { isRestrictedScope } from '../core/recall-scope.js';
 import { selectApiKeyOwner } from './tenant-lookup.js';
 /** The auth_create row a mint writes; the plaintext never reaches it. */
 function createAuditOf({ key, actor, metadata }) {

package/dist/store/ledger-turn.d.ts

@@ -1,5 +1,9 @@
 import type { DeliveryEventInput } from './delivery-recorder.js';
 import { type LastSent, type TokenSurface, type TokenUse } from './token-ledger.js';
+import { type PilotArm } from './pilot-arm.js';
+/** Says why a ledger row did not land, at the level its class earns: busy warns once through
+ * noteStoreBusy, absent is debug with no stack, unexpected warns once with the error class and stack. */
+export declare function noteLedgerRowSkipped<E>(error: E): void;
 /** Stores one delivery event and returns its id, or null when the write failed. */
 export type DeliveryWrite = (input: DeliveryEventInput) => number | null;
 /** The token rows of one turn and the delivery event that follows them. */
@@ -14,4 +18,9 @@ export interface LedgerTurn {
 export declare function recordLedgerTurn(hippoRoot: string, turn: LedgerTurn): void;
 /** What the session last sent on `surface`, or null, as lastSentState reads it. */
 export declare function lastSentOnSurface(hippoRoot: string, tenantId: string, sessionId: string | null | undefined, surface: TokenSurface): LastSent | null;
+/** The session's pilot arm: `write` books it as ensurePilotArm does, else the stored arm or the hash arm. */
+export declare function pilotArmOnRoot(hippoRoot: string, tenantId: string, sessionId: string, rateBp: number, opts: {
+    write: boolean;
+    ownTenantOnly?: boolean;
+}): PilotArm;
 //# sourceMappingURL=ledger-turn.d.ts.map

package/dist/store/ledger-turn.js

@@ -1,6 +1,37 @@
+// One hook or context turn's token-ledger work by store root: each call opens hippo.db, runs on one connection and closes it.
+import { isSqliteBusy, noteStoreBusy } from '../db/index.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { lastSentState, recordTokenUse } from './token-ledger.js';
 import { onHandle } from './open.js';
+import { ensurePilotArm, hashArm, readPilotArm } from './pilot-arm.js';
 import { writeDeliveryEventOnHandle } from './recall-trace.js';
+// SQLite's result codes for a hippo.db it cannot read: a corrupt image, and a file that is no database.
+const SQLITE_CORRUPT = 11;
+const SQLITE_NOTADB = 26;
+/** The one rule for a skipped ledger row. `absent` is a store with no token_ledger table or a hippo.db
+ * SQLite cannot read; the command that owns the store reports that, and a hook must stay quiet about it. */
+function ledgerSkipClass(error) {
+    if (isSqliteBusy(error))
+        return 'busy';
+    const code = error instanceof Error && 'errcode' in error ? error.errcode : undefined;
+    if (code === SQLITE_CORRUPT || code === SQLITE_NOTADB)
+        return 'absent';
+    return errorMessage(error).includes('no such table: token_ledger') ? 'absent' : 'unexpected';
+}
+/** Says why a ledger row did not land, at the level its class earns: busy warns once through
+ * noteStoreBusy, absent is debug with no stack, unexpected warns once with the error class and stack. */
+export function noteLedgerRowSkipped(error) {
+    const skip = ledgerSkipClass(error);
+    if (skip === 'busy') {
+        noteStoreBusy('token ledger row skipped');
+        return;
+    }
+    const message = `token ledger row skipped: ${errorMessage(error)}`;
+    if (skip === 'absent')
+        log.debug(message);
+    else
+        log.warnThenDebug('token-ledger-row', message, errorFields(error));
+}
 /** Books a turn's token rows, then its delivery event, on one connection. */
 export function recordLedgerTurn(hippoRoot, turn) {
     const { onRowError } = turn;
@@ -24,4 +55,11 @@ export function recordLedgerTurn(hippoRoot, turn) {
 export function lastSentOnSurface(hippoRoot, tenantId, sessionId, surface) {
     return onHandle(hippoRoot, (db) => lastSentState(db, tenantId, sessionId, surface));
 }
+/** The session's pilot arm: `write` books it as ensurePilotArm does, else the stored arm or the hash arm. */
+export function pilotArmOnRoot(hippoRoot, tenantId, sessionId, rateBp, opts) {
+    const { ownTenantOnly } = opts;
+    return onHandle(hippoRoot, (db) => opts.write
+        ? ensurePilotArm(db, tenantId, sessionId, rateBp, { ownTenantOnly })
+        : readPilotArm(db, sessionId, ownTenantOnly ? tenantId : undefined) ?? hashArm(sessionId, rateBp));
+}
 //# sourceMappingURL=ledger-turn.js.map

package/dist/store/mirrors.js

@@ -2,13 +2,18 @@ import { DEFAULT_TENANT_ID } from '../util/env.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { Layer } from '../core/memory.js';
-import { dumpFrontmatter } from './yaml.js';
-import { getMeta } from '../db/index.js';
+import { dumpFrontmatter } from '../util/yaml.js';
+import { getMeta, CONSOLIDATION_RUNS_KEPT } from '../db/index.js';
 import { oncePerStore } from '../db/connect.js';
 import { errorFields, errorMessage, log } from '../util/log.js';
 import { parseJsonArray, INDEX_VERSION, parseLastTraceId, MEMORY_SELECT_COLUMNS, rowToEntry, rowToMemoryConflict, } from './rows.js';
-import { serializeEntry } from './markdown.js';
+import { serializeEntry } from '../core/markdown.js';
+import { writeFileAtomic } from '../util/atomic-write.js';
 const SCORE_DECIMALS = 3;
+// Mirrors are derived and rebuildable from the store, so they skip the fsyncs (the cost on Windows) and keep the temp-and-rename atomicity.
+function writeMirror(file, text) {
+    writeFileAtomic(file, text, { durable: false });
+}
 export function layerDir(root, layer) {
     return path.join(root, layer);
 }
@@ -61,7 +66,7 @@ export function writeActiveTaskMirror(hippoRoot, tenantId, snapshot) {
         body.push(`## Session`, snapshot.session_id, '');
     }
     fs.mkdirSync(path.dirname(filePath), MIRROR_FOLDER);
-    fs.writeFileSync(filePath, `${fm}\n\n${body.join('\n')}`, 'utf8');
+    writeMirror(filePath, `${fm}\n\n${body.join('\n')}`);
 }
 export function removeActiveTaskMirror(hippoRoot, tenantId) {
     const filePath = activeTaskMirrorPath(hippoRoot, tenantId);
@@ -99,7 +104,7 @@ export function writeRecentSessionMirror(hippoRoot, tenantId, events) {
     }
     lines.push('');
     fs.mkdirSync(path.dirname(filePath), MIRROR_FOLDER);
-    fs.writeFileSync(filePath, `${fm}\n\n${lines.join('\n')}`, 'utf8');
+    writeMirror(filePath, `${fm}\n\n${lines.join('\n')}`);
 }
 function writeConflictMirrors(hippoRoot, conflicts) {
     const conflictDir = path.join(hippoRoot, 'conflicts');
@@ -128,7 +133,7 @@ function writeConflictMirrors(hippoRoot, conflicts) {
             `- Status: ${conflict.status}`,
             '',
         ].join('\n');
-        fs.writeFileSync(path.join(conflictDir, filename), `${fm}\n\n${body}`, 'utf8');
+        writeMirror(path.join(conflictDir, filename), `${fm}\n\n${body}`);
     }
     for (const existing of fs.readdirSync(conflictDir)) {
         if (existing === '.gitkeep')
@@ -142,7 +147,7 @@ export function writeMarkdownMirror(hippoRoot, entry) {
     removeEntryMirrors(hippoRoot, entry.id);
     const dir = layerDir(hippoRoot, entry.layer);
     fs.mkdirSync(dir, MIRROR_FOLDER);
-    fs.writeFileSync(path.join(dir, `${entry.id}.md`), serializeEntry(entry), 'utf8');
+    writeMirror(path.join(dir, `${entry.id}.md`), serializeEntry(entry));
 }
 // Every layer, Trace included: `writeMarkdownMirror` writes any layer, and a stale trace mirror
 // is the resurrection channel bootstrapLegacyStore/rebuildIndex guard against.
@@ -223,8 +228,12 @@ export function readLastRecall(db) {
     };
 }
 export function buildStatsFromDb(db) {
-    // SAFETY: runs' shape matches the four columns named in the SELECT above.
-    const runs = db.prepare(`SELECT timestamp, decayed, merged, removed FROM consolidation_runs ORDER BY timestamp ASC, id ASC`).all();
+    // SAFETY: runs' shape matches the four columns named in the SELECT below.
+    const runs = db.prepare(`
+    SELECT timestamp, decayed, merged, removed FROM (
+      SELECT id, timestamp, decayed, merged, removed FROM consolidation_runs ORDER BY timestamp DESC, id DESC LIMIT ?
+    ) ORDER BY timestamp ASC, id ASC
+  `).all(CONSOLIDATION_RUNS_KEPT);
     return {
         total_remembered: Number(getMeta(db, 'total_remembered', '0')),
         total_recalled: Number(getMeta(db, 'total_recalled', '0')),
@@ -240,7 +249,7 @@ export function buildStatsFromDb(db) {
 /** Write the `index.json` mirror file for an already-derived index. Exported for
  *  `rebuildIndex` (the only index.json writer) and the longmemeval benchmark. */
 export function writeIndexMirror(hippoRoot, index) {
-    mirrorBestEffort('index.json', () => fs.writeFileSync(path.join(hippoRoot, 'index.json'), JSON.stringify(index, null, 2), 'utf8'));
+    mirrorBestEffort('index.json', () => overwriteInPlace(path.join(hippoRoot, 'index.json'), JSON.stringify(index, null, 2)));
 }
 export function writeStatsMirror(hippoRoot, stats) {
     mirrorBestEffort('stats.json', () => overwriteInPlace(path.join(hippoRoot, 'stats.json'), JSON.stringify(stats, null, 2)));

package/dist/store/open.d.ts

@@ -1,15 +1,12 @@
 import { type MemoryEntry } from '../core/memory.js';
 import { type DatabaseSyncLike } from '../db/index.js';
-import { type ResolveProjectIdentityOpts } from '../core/project-identity.js';
-/** Nearest ancestor store like git; the strict join is the fallback so `hippo init` still creates `<cwd>/.hippo`. */
-export declare function getHippoRoot(cwd?: string, opts?: ResolveProjectIdentityOpts): string;
-export declare function isInitialized(hippoRoot: string): boolean;
 export declare function initStore(hippoRoot: string): void;
 /** One open connection with init done on it, for callers who used to pay for `initStore` + a second `openHippoDb`. */
 export declare function openStore(hippoRoot: string, opts?: {
     busyWaitMs?: number;
 }): DatabaseSyncLike;
-/** One call on a handle of its own, closed after; pass openStore where the call also sets up mirror folders and legacy rows. */
+/** One call on a handle of its own, closed after (a request scope's handle stays open);
+ *  pass openStore where the call also sets up mirror folders and legacy rows. */
 export declare function onHandle<T>(hippoRoot: string, fn: (db: DatabaseSyncLike) => T, open?: (hippoRoot: string) => DatabaseSyncLike): T;
 /** `meta` key holding the default half-life base a store's memories are on (src/consolidate/half-life-migration.ts). */
 export declare const HALF_LIFE_BASE_META_KEY = "default_half_life_base";