hippo-memory 1.69.0 → 1.71.0

package/dist/store/delete-and-batch.js

@@ -1,28 +1,26 @@
-import { AUTO_DELETABLE_SQL } from '../memory.js';
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { checkRejectionGuard, RejectedValueError } from '../rejection.js';
-import { markSummaryDirtyInTx } from '../summary-dirty.js';
-import { insertDormantRow } from '../dormant.js';
-import { log } from '../log.js';
+import { DEFAULT_TENANT_ID } from '../util/env.js';
+import { RawAppendOnlyError } from '../core/raw-append-only.js';
+import { AUTO_DELETABLE_SQL } from './rule-sql.js';
+import { closeHippoDb, withWriteScope } from '../db/index.js';
+import { checkRejectionGuard, RejectedValueError } from './rejection.js';
+import { markSummaryDirtyInTx } from './summary-dirty.js';
+import { insertDormantRow } from './dormant.js';
+import { log } from '../util/log.js';
 import { MEMORY_SELECT_COLUMNS, rowToEntry } from './rows.js';
 import { audit } from './audit-event.js';
 import { deleteFtsRow, replaceFtsRows, stampOriginProject, upsertMemoryRow } from './entry-row.js';
 import { purgeMirrorBestEffort, mirrorBestEffort, writeMarkdownMirror } from './mirrors.js';
-import { openStore } from './open.js';
-import { clock } from '../write-budget.js';
+import { onHandle, openStore } from './open.js';
+import { clock } from '../util/write-budget.js';
 /** Tables whose rows keep a first-class object's backing memory in `memory_id` (ON DELETE SET NULL); tests/dormant-memories.test.ts pins it to the schema. */
 export const MEMORY_BACKED_TABLES = ['predictions', 'decisions', 'incidents', 'processes', 'policies', 'skills', 'project_briefs', 'customer_notes'];
 /** Deleting a memory that backs an object nulls the object's link, and no restore can repair it, so no automatic pass may. */
 const AUTOMATIC_DELETE_SQL = `${AUTO_DELETABLE_SQL}${MEMORY_BACKED_TABLES.map((t) => ` AND NOT EXISTS (SELECT 1 FROM ${t} WHERE ${t}.memory_id = memories.id)`).join('')}`;
 /** Ids of memories that back a first-class object, for passes that plan deletes before making them. A table missing from an older schema is skipped. */
 export function memoriesBackingObjects(hippoRoot) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return memoriesBackingObjectsOn(db);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 /** memoriesBackingObjects on the caller's handle. */
 export function memoriesBackingObjectsOn(db) {
@@ -42,16 +40,22 @@ export function memoriesBackingObjectsOn(db) {
     }
     return ids;
 }
-/**
- * db-scoped delete core, so a delete can compose inside a caller's transaction.
- * NO filesystem I/O: the caller's transaction may still roll back, and mirrors are written post-commit.
- *
- * `opts.suppressForgetAudit` (default false): `rejectValue` and `resolveConflict` set it because each
- * writes its own aggregate audit row, so a removed row must not ALSO emit a `forget` row.
- *
- * Returns `{tenantId, dagParentId}` for the removed row, or `null` if no row with `id`
- * existed or `automatic` refused it (pinned, raw, kept for good or backing an object at DELETE time, so a late pin wins).
- */
+// The abort text of trg_memories_raw_append_only (migration v14), the one place src matches it.
+const RAW_TRIGGER_TEXT = 'raw is append-only';
+function isRawTriggerAbort(cause) {
+    return cause instanceof Error && cause.message.includes(RAW_TRIGGER_TEXT);
+}
+/** Runs the DELETE and returns the rows it removed; the raw-row trigger's abort becomes RawAppendOnlyError. */
+function deleteMemoryRow(db, sql, id) {
+    try {
+        return Number(db.prepare(sql).run(id).changes ?? 0);
+    }
+    catch (cause) {
+        throw isRawTriggerAbort(cause) ? new RawAppendOnlyError(cause) : cause;
+    }
+}
+/** db-scoped delete core, composable inside a caller's transaction; NO filesystem I/O, mirrors are written post-commit. `suppressForgetAudit` is set by
+ * rejectValue and resolveConflict (own audit row). Returns `{tenantId, dagParentId}`, or null if absent or `automatic` refused it. */
 export function deleteEntryCore(db, id, opts) {
     // SAFETY: row's shape matches the three columns named in the SELECT above.
     const row = db
@@ -60,52 +64,29 @@ export function deleteEntryCore(db, id, opts) {
     if (!row?.id)
         return null;
     const guard = opts?.automatic ? ` AND ${AUTOMATIC_DELETE_SQL}` : '';
-    if (Number(db.prepare(`DELETE FROM memories WHERE id = ?${guard}`).run(id).changes ?? 0) === 0)
+    if (deleteMemoryRow(db, `DELETE FROM memories WHERE id = ?${guard}`, id) === 0)
         return null;
     deleteFtsRow(db, id);
     if (!opts?.suppressForgetAudit) {
-        audit(db, 'forget', id, opts?.reason ? { reason: opts.reason } : undefined, opts?.actor ?? 'cli', row.tenant_id);
+        audit(db, 'forget', { targetId: id, metadata: opts?.reason ? { reason: opts.reason } : undefined, actor: opts?.actor ?? 'cli', tenantId: row.tenant_id });
     }
     // Forgetting a child of a summary marks the parent dirty. Not atomic with the DELETE, but
     // markSummaryDirtyInTx is idempotent, so the next child mutation re-marks the parent if this fails.
     if (row.dag_parent_id) {
-        markSummaryDirtyInTx(db, row.dag_parent_id, row.tenant_id ?? 'default', opts?.actor ?? 'cli');
+        markSummaryDirtyInTx(db, row.dag_parent_id, row.tenant_id ?? DEFAULT_TENANT_ID, opts?.actor ?? 'cli');
     }
-    return { tenantId: row.tenant_id ?? 'default', dagParentId: row.dag_parent_id ?? null };
+    return { tenantId: row.tenant_id ?? DEFAULT_TENANT_ID, dagParentId: row.dag_parent_id ?? null };
 }
-/**
- * Delete an entry from SQLite and mirrors.
- *
- * `opts.actor` defaults to 'cli'. The api.* layer threads `ctx.actor` so HTTP
- * callers land with `api_key:<key_id>` in the audit log without a duplicate
- * emit from the api wrapper.
- *
- * Thin wrapper over `deleteEntryCore` (open → core → mirrors → close);
- * behavior is byte-identical to the pre-split implementation for every
- * existing caller.
- */
+/** Delete an entry from SQLite and mirrors; thin wrapper over `deleteEntryCore` (open, core, mirrors, close).
+ * `opts.actor` defaults to 'cli'; the api layer threads `ctx.actor` so HTTP callers land as `api_key:<key_id>` in the audit log. */
 export function deleteEntry(hippoRoot, id, opts) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return deleteEntryOn(db, hippoRoot, id, opts);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** deleteEntry on the caller's open store, so a loop of deletes opens the store once; each delete still commits alone. */
-export function deleteEntryOn(db, hippoRoot, id, opts) {
-    db.exec('BEGIN IMMEDIATE');
-    let result;
-    try {
-        result = deleteEntryCore(db, id, opts);
-        db.exec('COMMIT');
-    }
-    catch (err) {
-        if (db.isTransaction !== false)
-            db.exec('ROLLBACK');
-        throw err;
-    }
+function deleteEntryOn(db, hippoRoot, id, opts) {
+    const result = withWriteScope(db, 'delete_entry', () => deleteEntryCore(db, id, opts));
     if (!result)
         return false;
     purgeMirrorBestEffort(hippoRoot, id, false, 'deleteEntry');
@@ -122,30 +103,21 @@ function mergeOwnChanges(base, ours, live) {
     }
     return row;
 }
-/** Writes, deletes and dormant moves in one transaction. With `snapshot` (rows as the caller loaded them), a write keeps only
- *  the fields the caller changed, takes the rest from the live row, and never resurrects a row that is gone.
- *
- *  `dormant` (src/dormant.ts): each move's snapshot is inserted into `dormant_memories` and its `memories` row
- *  leaves exactly like a delete (FTS row, DAG parent dirty-mark, mirrors), in the same transaction, so a memory
- *  is never in both places or in neither. Deletes and moves both skip rows that are no longer auto-deletable
- *  (pinned, raw, kept for good or backing an object since the caller decided). Returns the ids that left `memories`, deleted or moved. */
+/** Writes, deletes and dormant moves in one transaction. With `snapshot`, a write keeps only the fields the caller changed and never resurrects a gone row.
+ * Dormant moves (src/store/dormant.ts) leave `memories` like a delete; both skip rows no longer auto-deletable. Returns ids that left `memories`. */
 export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds, opts) {
     const dormant = opts?.dormant ?? [];
     if (toWrite.length === 0 && toDeleteIds.length === 0 && dormant.length === 0)
         return [];
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // One component, so every op keeps the statement order this call has always had.
         const all = { writes: toWrite, deletes: toDeleteIds, dormant };
         return batchWriteAndDeleteOn(db, hippoRoot, [all], 0, { snapshot: opts?.snapshot, holdMs: Infinity }).removedIds;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 const failedUnits = new WeakMap();
 /** Tags a flush error with the ids of the component it stopped at, for the partial sleep audit row; the first tag wins. */
-export function noteFailedUnit(err, component) {
+function noteFailedUnit(err, component) {
     if (!component || failedUnits.has(err))
         return;
     const ids = [...component.writes.map((e) => e.id), ...component.deletes, ...component.dormant.map((m) => m.entry.id)];
@@ -157,15 +129,20 @@ export function failedUnitOf(err) {
 }
 /** batchWriteAndDelete on the caller's open store from component `from`, each component whole, closing the transaction at the
  *  first component boundary after `holdMs`. Returns the next component's index and the ids that left `memories`. */
-export function batchWriteAndDeleteOn(db, hippoRoot, components, from, opts) {
+function batchWriteAndDeleteOn(db, hippoRoot, components, from, opts) {
     const now = opts.clock ?? clock;
+    const out = {
+        written: [],
+        removedIds: [],
+        rejectedSkips: 0,
+        fts: { rows: [], staleIds: [] },
+        dirty: { parents: new Set(), tenantById: new Map() }
+    };
+    let next = from;
     // IMMEDIATE: the tombstone probes below read before the first write, and under a deferred BEGIN a
     // concurrent `hippo reject` would make the lock upgrade fail with SQLITE_BUSY and roll back the batch.
-    db.exec('BEGIN IMMEDIATE');
-    const begunAt = now();
-    const out = { written: [], removedIds: [], rejectedSkips: 0, fts: { rows: [], staleIds: [] }, dirty: { parents: new Set(), tenantById: new Map() } };
-    let next = from;
-    try {
+    withWriteScope(db, 'flush_chunk', () => {
+        const begunAt = now();
         do {
             const at = next++;
             try {
@@ -182,19 +159,9 @@ export function batchWriteAndDeleteOn(db, hippoRoot, components, from, opts) {
         // Fire dirty-mark for every collected parent INSIDE the BEGIN, so the
         // dirty flag commits atomically with the writes + deletes.
         for (const parentId of out.dirty.parents) {
-            markSummaryDirtyInTx(db, parentId, out.dirty.tenantById.get(parentId) ?? 'default', 'batch');
-        }
-        db.exec('COMMIT');
-    }
-    catch (error) {
-        if (db.isTransaction !== false) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* preserve the original throw and its unit tag */ }
+            markSummaryDirtyInTx(db, parentId, out.dirty.tenantById.get(parentId) ?? DEFAULT_TENANT_ID, 'batch');
         }
-        throw error;
-    }
+    });
     reportChunk(hippoRoot, out);
     return { next, removedIds: out.removedIds };
 }
@@ -252,7 +219,7 @@ function selectAutoDeletableRows(db, ids, dirty) {
     for (const row of rows) {
         if (row.dag_parent_id) {
             dirty.parents.add(row.dag_parent_id);
-            dirty.tenantById.set(row.dag_parent_id, row.tenant_id ?? 'default');
+            dirty.tenantById.set(row.dag_parent_id, row.tenant_id ?? DEFAULT_TENANT_ID);
         }
     }
     return rows;
@@ -293,7 +260,7 @@ function applyBatchWrites(db, stampedWrites, snapshot, out) {
 }
 /** True, after auditing the refusal, when the write would introduce a rejected value. */
 function isRejectedBatchWrite(db, row) {
-    const entryTenantId = row.tenantId ?? 'default';
+    const entryTenantId = row.tenantId ?? DEFAULT_TENANT_ID;
     // checkRejectionGuard, not a bare tombstone probe: a tombstone can coexist with a live same-content row,
     // and skipping every re-persist would starve it of decay/replay updates; only new or changed content is refused.
     try {
@@ -301,11 +268,52 @@ function isRejectedBatchWrite(db, row) {
     }
     catch (err) {
         if (err instanceof RejectedValueError) {
-            audit(db, 'reject_refusal', row.id, { digest: err.digest, reason: err.reason }, 'sleep-batch', entryTenantId);
+            audit(db, 'reject_refusal', { targetId: row.id, metadata: { digest: err.digest, reason: err.reason }, actor: 'sleep-batch', tenantId: entryTenantId });
             return true;
         }
         throw err;
     }
     return false;
 }
+/** Deletes each target in its own transaction on one store handle; `true` where the row went. */
+export function deleteEntriesOneByOne(hippoRoot, targets, opts) {
+    if (targets.length === 0)
+        return [];
+    return onHandle(hippoRoot, (db) => {
+        return targets.map((target) => deleteEntryOn(db, hippoRoot, target.id, { ...opts, reason: target.reason }));
+    }, openStore);
+}
+/** Commits whole components in transactions of about `budget.holdMs`, letting other writers in between; returns the ids that left `memories`.
+ * The snapshot keeps what other writers changed after the caller loaded its rows. */
+export async function commitInChunks(hippoRoot, components, opts) {
+    if (components.length === 0)
+        return [];
+    const { snapshot, budget } = opts;
+    const removed = [];
+    // The wait is an option rather than a PRAGMA, so a shared hook handle keeps its own.
+    const db = openStore(hippoRoot, { busyWaitMs: opts.busyWaitMs });
+    let next = 0;
+    try {
+        let committedAt = 0;
+        while (next < components.length) {
+            if (next > 0)
+                await budget.pause(committedAt);
+            const chunk = batchWriteAndDeleteOn(db, hippoRoot, components, next, { snapshot, holdMs: budget.holdMs, clock: budget.clock });
+            committedAt = budget.clock();
+            next = chunk.next;
+            for (const id of chunk.removedIds)
+                removed.push(id);
+        }
+    }
+    catch (err) {
+        // A unit that threw is already tagged; a throw outside one (a pause, BEGIN or COMMIT) names the chunk's first unit.
+        if (err instanceof Error)
+            noteFailedUnit(err, components[next]);
+        throw err;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    return removed;
+}
 //# sourceMappingURL=delete-and-batch.js.map

package/dist/{delivery-recorder.d.ts → store/delivery-recorder.d.ts}

@@ -1,7 +1,9 @@
-import type { MemoryEntry } from './memory.js';
-import { type PromptRecallGate } from './prompt-recall.js';
+import type { MemoryEntry } from '../core/memory.js';
+import { type PromptRecallGate } from '../core/prompt-recall.js';
 export type DeliveryRuntime = 'claude-code' | 'codex' | 'copilot' | 'unknown';
-export type DeliveryEventType = 'prompt-submit' | 'pinned-manual';
+export type DeliveryEventType = 'prompt-submit' | 'pinned-manual' | 'pre-compact' | 'compact-resume' | 'session-end' | 'context';
+/** True for the boundary types: a compaction's two hooks and the end of a session. */
+export declare const isBoundaryEvent: (type: DeliveryEventType) => boolean;
 export type DeliverySurface = 'hook' | 'context';
 export type DeliveryWriteStore = 'local' | 'global';
 export type DeliverySessionState = 'payload' | 'env' | 'missing' | 'subagent';
@@ -10,8 +12,8 @@ export type DeliveryPool = 'pin' | 'recent' | 'prompt-recall' | 'strength' | 'se
 export type DeliveryStage = 'load' | 'eligible' | 'gate' | 'budget' | 'limit' | 'final';
 export type DeliveryOutcome = 'emitted' | 'reused' | 'rejected';
 export type DeliveryRejectReason = 'budget' | 'gate-below-threshold' | 'gate-max-items' | 'duplicate' | 'scope' | 'quality' | 'limit';
-/** Row format version written to `delivery_events.ledger_version`. */
-export declare const DELIVERY_LEDGER_VERSION = 1;
+/** Row format version in `delivery_events.ledger_version`: 3 = written by a binary that can write session-end and context rows, so `event_type` has six values. */
+export declare const DELIVERY_LEDGER_VERSION = 3;
 /** Rejected candidate rows kept per event; the rest only add to `rejected_unlisted`. */
 export declare const DELIVERY_REJECTED_ROW_CAP = 16;
 export interface DeliveryCandidateInput {
@@ -96,6 +98,10 @@ export interface DeliveryObserver {
         };
     }[]): void;
     selected(items: readonly DeliverySelected[]): void;
+    /** A searching call's query, `*` for none; kept as its hash, the one the recall trace stores. */
+    queried(query: string): void;
+    /** The recall trace a call that returned rows wrote; null when the write failed or the store answers no id. */
+    traced(traceId: number | null): void;
 }
 /** What the renderer sent, reported once at its exit. */
 export interface DeliveryOutcomeInput {
@@ -123,7 +129,12 @@ export interface DeliveryRecorderInit {
     envSessionId?: string;
     /** Set by the caller's runtime flag; Copilot payloads carry hook_event_name too, so inference would say claude-code. */
     runtime?: DeliveryRuntime;
+    /** Set by hooks that are not prompt or context calls; without it the payload's hook event decides. */
+    eventType?: DeliveryEventType;
 }
+export type DeliveryFault = 'observe' | 'build' | 'flush';
+/** Makes every recorder created afterwards throw at one stage. Only tests call it; the shipped CLI and server have no route here. */
+export declare function _setDeliveryFaultForTests(fault: DeliveryFault | null): void;
 /** A recorder for one call; every observer method is guarded, and a throw marks it broken instead of escaping. */
 export declare function createDeliveryRecorder(init: DeliveryRecorderInit): DeliveryRecorder;
 //# sourceMappingURL=delivery-recorder.d.ts.map

package/dist/{delivery-recorder.js → store/delivery-recorder.js}

@@ -1,11 +1,14 @@
-// In-memory observer for one pinned-only context call: what was considered, why each was rejected, what reached stdout.
-// No DB access (the caller hands build()'s output to src/recall-trace.ts); hashes, ids, counts and enums only, never text.
-import { envTestDeliveryFault } from './env.js';
-import { evalNow } from './ablation.js';
-import { scoreOverlap } from './prompt-recall.js';
-import { blockHash, estimateTokens, hookPayloadSessionId, hookPayloadString, isSubagentPayload } from './token-ledger.js';
-/** Row format version written to `delivery_events.ledger_version`. */
-export const DELIVERY_LEDGER_VERSION = 1;
+import { evalNow } from '../core/ablation.js';
+import { scoreOverlap } from '../core/prompt-recall.js';
+import { hookPayloadSessionId, hookPayloadString, isSubagentPayload } from './token-ledger.js';
+import { blockHash, estimateTokens } from '../util/token-text.js';
+import { errorMessage, log } from '../util/log.js';
+/** True for the boundary types: a compaction's two hooks and the end of a session. */
+export const isBoundaryEvent = (type) => type === 'pre-compact' || type === 'compact-resume' || type === 'session-end';
+/** Only the per-prompt calls keep prompt facts; a boundary or a `hippo context` run is not a prompt. */
+const carriesPrompt = (type) => type === 'prompt-submit' || type === 'pinned-manual';
+/** Row format version in `delivery_events.ledger_version`: 3 = written by a binary that can write session-end and context rows, so `event_type` has six values. */
+export const DELIVERY_LEDGER_VERSION = 3;
 /** Rejected candidate rows kept per event; the rest only add to `rejected_unlisted`. */
 export const DELIVERY_REJECTED_ROW_CAP = 16;
 // Deeper stages were closer to being sent, so the row cap keeps them first.
@@ -37,22 +40,30 @@ function readPayload(init) {
         : payloadSession !== null ? 'payload' : envSession !== null ? 'env' : 'missing';
     return { payloadSession, envSession, prompt, hostTurnId, hookEvent, sessionState };
 }
-function rejectId(state, id, stage, reason, score, tokens) {
+function rejectId(state, id, rejection) {
+    const { stage, reason, score, tokens } = rejection;
     const held = state.candidates.get(id);
     // First rejection wins; an id never offered is not a candidate of this call.
     if (!held || held.reason !== null)
         return;
     state.candidates.set(id, { ...held, stage, reason, score, tokens });
 }
+function pickedPool(p, held) {
+    if (p.promptRecall)
+        return 'prompt-recall';
+    // A ranked call's rows keep the ranking that chose them, a pinned hit included.
+    if (held?.pool === 'search' || held?.pool === 'strength')
+        return held.pool;
+    return held?.pool === 'pin' || p.entry.pinned ? 'pin' : 'recent';
+}
 function pickedRows(state) {
     const staticReused = state.outcome.staticReused === true;
     const rows = [];
     for (const p of state.picked.values()) {
-        const held = state.candidates.get(p.entry.id);
         rows.push({
             memoryId: p.entry.id,
             sourceStore: p.sourceStore,
-            pool: p.promptRecall ? 'prompt-recall' : held?.pool === 'pin' || p.entry.pinned ? 'pin' : 'recent',
+            pool: pickedPool(p, state.candidates.get(p.entry.id)),
             stage: 'final',
             outcome: staticReused && !p.promptRecall ? 'reused' : 'emitted',
             reason: null,
@@ -89,22 +100,25 @@ function buildEvent(init, payload, state, ts, startedMs) {
     const rejected = rejectedRows(state);
     const rows = [...picked, ...rejected.rows];
     const emitted = outcome.emittedText ?? null;
+    const eventType = init.eventType ?? (payload.hookEvent === 'UserPromptSubmit' ? 'prompt-submit' : 'pinned-manual');
+    // Whatever the payload holds, so a hook-run `hippo context` is never matched to an earlier row by its prompt.
+    const prompt = carriesPrompt(eventType) ? payload.prompt : null;
     return {
         ts,
         tenantId: init.tenantId,
         runtime: init.runtime ?? (payload.hostTurnId !== null ? 'codex' : payload.hookEvent !== null ? 'claude-code' : 'unknown'),
-        eventType: payload.hookEvent === 'UserPromptSubmit' ? 'prompt-submit' : 'pinned-manual',
-        surface: 'hook',
+        eventType,
+        surface: eventType === 'context' ? 'context' : 'hook',
         storeHash: init.storeHash,
         writeStore: init.writeStore,
         projectHash: facts !== null && facts.projectName !== '' ? blockHash(facts.projectName) : null,
         sessionId: payload.payloadSession ?? payload.envSession,
         sessionState: payload.sessionState,
         hostTurnId: payload.hostTurnId,
-        promptHash: payload.prompt !== null ? blockHash(payload.prompt) : null,
-        promptLength: payload.prompt?.length ?? 0,
-        queryHash: null,
-        recallTraceId: null,
+        promptHash: prompt !== null ? blockHash(prompt) : null,
+        promptLength: prompt?.length ?? 0,
+        queryHash: state.queryHash,
+        recallTraceId: state.recallTraceId,
         blockState: state.disabledSeen ? 'disabled' : outcome.state,
         promptRecall: facts?.promptRecall === true,
         consideredCount: new Set([...state.candidates.keys(), ...state.picked.keys()]).size,
@@ -135,7 +149,7 @@ function candidateMethods(state, guard) {
                     id: e.id, sourceStore: storeOf(isGlobal), pool: 'recent', stage: null, reason: null, score: null, tokens: null,
                 });
             }
-            rejectId(state, e.id, 'load', 'quality', null, null);
+            rejectId(state, e.id, { stage: 'load', reason: 'quality', score: null, tokens: null });
         }),
         offer: (entries, isGlobal, pool) => guard(() => {
             for (const e of entries) {
@@ -150,12 +164,12 @@ function candidateMethods(state, guard) {
                 });
             }
         }),
-        reject: (e, stage, reason, score, tokens) => guard(() => rejectId(state, e.id, stage, reason, score ?? null, tokens ?? null)),
+        reject: (e, stage, reason, score, tokens) => guard(() => rejectId(state, e.id, { stage, reason, score: score ?? null, tokens: tokens ?? null })),
         dropMissing: (before, after, stage, reason) => guard(() => {
             const kept = new Set(after.map((e) => e.id));
             for (const e of before)
                 if (!kept.has(e.id))
-                    rejectId(state, e.id, stage, reason, null, null);
+                    rejectId(state, e.id, { stage, reason, score: null, tokens: null });
         }),
         gated: (prompt, items, gate, kept) => guard(() => {
             const keptIds = new Set(kept.map((g) => g.item.id));
@@ -164,7 +178,7 @@ function candidateMethods(state, guard) {
                     continue;
                 const { score, shared } = scoreOverlap(prompt, c.tokens, gate.metric);
                 const cleared = score >= gate.threshold && shared >= gate.minShared;
-                rejectId(state, c.id, 'gate', cleared ? 'gate-max-items' : 'gate-below-threshold', score, null);
+                rejectId(state, c.id, { stage: 'gate', reason: cleared ? 'gate-max-items' : 'gate-below-threshold', score, tokens: null });
             }
         }),
         selected: (items) => guard(() => {
@@ -178,29 +192,22 @@ function candidateMethods(state, guard) {
         }),
     };
 }
+let injectedFault = null;
+/** Makes every recorder created afterwards throw at one stage. Only tests call it; the shipped CLI and server have no route here. */
+export function _setDeliveryFaultForTests(fault) {
+    injectedFault = fault;
+}
 /** A recorder for one call; every observer method is guarded, and a throw marks it broken instead of escaping. */
 export function createDeliveryRecorder(init) {
     const startedMs = Date.now();
     const ts = evalNow().toISOString();
-    // Test-only fault injection, as HIPPO_FAKE_NOW is for time.
-    const fault = envTestDeliveryFault();
+    const fault = injectedFault;
     const payload = readPayload(init);
     const state = {
         candidates: new Map(), picked: new Map(), filtered: new Set(), facts: null, shown: 0, dropped: 0,
-        disabledSeen: false, outcome: { state: 'empty' }, broken: null, flushed: false,
-    };
-    const guard = (fn) => {
-        if (state.broken !== null)
-            return;
-        try {
-            if (fault === 'observe')
-                throw new Error('injected observe fault');
-            fn();
-        }
-        catch (error) {
-            state.broken = error instanceof Error ? error.message : String(error);
-        }
+        disabledSeen: false, outcome: { state: 'empty' }, queryHash: null, recallTraceId: null, broken: null, flushed: false,
     };
+    const guard = guardFor(state, fault);
     const { qualityDropped, offer, reject, dropMissing, gated, selected } = candidateMethods(state, guard);
     return {
         root: init.root,
@@ -219,14 +226,15 @@ export function createDeliveryRecorder(init) {
         dropMissing,
         gated,
         selected,
+        queried: (query) => guard(() => { state.queryHash = blockHash(query); }),
+        traced: (traceId) => guard(() => { state.recallTraceId = traceId; }),
         delivered: (o) => guard(() => { state.outcome = { ...o }; }),
         flush: (write) => {
             if (state.flushed)
                 return;
             state.flushed = true;
             if (state.broken !== null) {
-                // Same pinned `[hippo] delivery ledger` hook stderr line as recall-trace.ts's write failure.
-                console.error(`[hippo] delivery ledger skipped: recorder failed: ${state.broken}`);
+                log.warn(`delivery ledger skipped: recorder failed: ${state.broken}`);
                 return;
             }
             if (fault === 'build')
@@ -238,4 +246,18 @@ export function createDeliveryRecorder(init) {
         },
     };
 }
+function guardFor(state, fault) {
+    return (fn) => {
+        if (state.broken !== null)
+            return;
+        try {
+            if (fault === 'observe')
+                throw new Error('injected observe fault');
+            fn();
+        }
+        catch (error) {
+            state.broken = errorMessage(error);
+        }
+    };
+}
 //# sourceMappingURL=delivery-recorder.js.map

package/dist/store/descendant-page.d.ts

@@ -0,0 +1,12 @@
+import type { DatabaseSyncLike } from '../db/index.js';
+import type { MemoryEntry } from '../core/memory.js';
+import type { DescendantPage, SummaryDescendants } from './port.js';
+export interface PagedWalk {
+    readonly tenantId: string;
+    readonly summary: MemoryEntry;
+    readonly depth: number;
+    readonly page: DescendantPage;
+}
+/** The walk `summaryWithDescendants` documents, with `levels` cut to the first `page.rows` rows and each level's full count in `sizes`. */
+export declare function pagedDescendants(db: DatabaseSyncLike, walk: PagedWalk, summaryAdmitted: boolean): SummaryDescendants;
+//# sourceMappingURL=descendant-page.d.ts.map

package/dist/store/descendant-page.js

@@ -0,0 +1,99 @@
+import { chunked, selectEntriesByIds, TENANT_IS } from './entry-reads.js';
+import { MEMORY_SELECT_COLUMNS, rowToEntry } from './rows.js';
+const marks = (ids) => ids.map(() => '?').join(',');
+/** The walk `summaryWithDescendants` documents, with `levels` cut to the first `page.rows` rows and each level's full count in `sizes`. */
+export function pagedDescendants(db, walk, summaryAdmitted) {
+    const sizes = [];
+    const levels = [];
+    const seen = new Set([walk.summary.id]);
+    let room = Math.max(0, walk.page.rows);
+    let parents = summaryAdmitted ? [walk.summary.id] : [];
+    for (let level = 0; level < walk.depth && parents.length > 0; level++) {
+        const counted = level === walk.depth - 1 ? countedLevel(db, walk, parents, room) : null;
+        const read = counted ?? keyedLevel(db, walk, parents, { seen, room });
+        if (read.size === 0)
+            break;
+        sizes.push(read.size);
+        levels.push(read.rows);
+        room -= read.rows.length;
+        parents = read.ids;
+    }
+    return { summary: walk.summary, levels, sizes };
+}
+// Reads four short columns of every child, since the level below needs each admitted id as a parent.
+function keyedLevel(db, walk, parents, at) {
+    const byParent = new Map();
+    for (const chunk of chunked([...parents])) {
+        // SAFETY: the SELECT names exactly ChildKey's four columns, and the WHERE keeps dag_parent_id a string.
+        const keys = db.prepare(`SELECT id, dag_parent_id, scope, origin_project FROM memories WHERE dag_parent_id IN (${marks(chunk)}) AND ${TENANT_IS} ORDER BY created ASC, id ASC`).all(...chunk, walk.tenantId);
+        for (const key of keys) {
+            const bucket = byParent.get(key.dag_parent_id);
+            if (bucket)
+                bucket.push(key);
+            else
+                byParent.set(key.dag_parent_id, [key]);
+        }
+    }
+    const ids = [];
+    for (const parentId of parents) {
+        for (const key of byParent.get(parentId) ?? []) {
+            if (at.seen.has(key.id) || !walk.page.admit(key))
+                continue;
+            at.seen.add(key.id);
+            ids.push(key.id);
+        }
+    }
+    const shown = ids.slice(0, Math.max(0, at.room));
+    const whole = selectEntriesByIds(db, shown, walk.tenantId);
+    return { ids, size: ids.length, rows: shown.flatMap((id) => whole.get(id) ?? []) };
+}
+/** The last level counted in SQL and read up to `room` rows; null when a row there is refused, which only the keyed read can leave out.
+ *  A row has one parent and a parent is read at one level, so the summary is the only row an earlier level can already hold. */
+function countedLevel(db, walk, parents, room) {
+    const perParent = new Map();
+    for (const chunk of chunked([...parents])) {
+        // SAFETY: the SELECT names exactly ChildGroup's four fields, and the WHERE keeps dag_parent_id a string.
+        const groups = db.prepare(`SELECT dag_parent_id, scope, origin_project, COUNT(*) AS n FROM memories WHERE dag_parent_id IN (${marks(chunk)}) AND ${TENANT_IS} AND id <> ? GROUP BY dag_parent_id, scope, origin_project`).all(...chunk, walk.tenantId, walk.summary.id);
+        for (const group of groups) {
+            if (!walk.page.admit(group))
+                return null;
+            perParent.set(group.dag_parent_id, (perParent.get(group.dag_parent_id) ?? 0) + Number(group.n));
+        }
+    }
+    let size = 0;
+    for (const n of perParent.values())
+        size += n;
+    return { ids: [], size, rows: firstRows(db, walk, parents.filter((id) => perParent.has(id)), { perParent, room }) };
+}
+// Every parent before the one the page ends in is read whole in one statement; that last one is read under a LIMIT.
+function firstRows(db, walk, parents, at) {
+    const whole = [];
+    let left = at.room;
+    for (const parentId of parents) {
+        if (left <= 0)
+            break;
+        const n = at.perParent.get(parentId) ?? 0;
+        if (n >= left)
+            return [...childrenInOrder(db, walk, whole, -1), ...childrenInOrder(db, walk, [parentId], left)];
+        whole.push(parentId);
+        left -= n;
+    }
+    return childrenInOrder(db, walk, whole, -1);
+}
+/** Children parent by parent, each parent's by created then id; a negative `limit` reads them all. */
+function childrenInOrder(db, walk, parents, limit) {
+    const byParent = new Map();
+    for (const chunk of chunked([...parents])) {
+        // SAFETY: selects exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
+        const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE dag_parent_id IN (${marks(chunk)}) AND ${TENANT_IS} AND id <> ? ORDER BY created ASC, id ASC LIMIT ?`).all(...chunk, walk.tenantId, walk.summary.id, limit);
+        for (const row of rows) {
+            const bucket = byParent.get(row.dag_parent_id ?? '');
+            if (bucket)
+                bucket.push(rowToEntry(row));
+            else
+                byParent.set(row.dag_parent_id ?? '', [rowToEntry(row)]);
+        }
+    }
+    return parents.flatMap((id) => byParent.get(id) ?? []);
+}
+//# sourceMappingURL=descendant-page.js.map