hippo-memory 1.69.0 → 1.70.0

package/dist/store/delete-and-batch.d.ts

@@ -1,6 +1,7 @@
-import { type MemoryEntry } from '../memory.js';
-import { openHippoDb, type DatabaseSyncLike } from '../db.js';
-import { type DormantMove } from '../dormant.js';
+import { type MemoryEntry } from '../core/memory.js';
+import { openHippoDb, type DatabaseSyncLike } from '../db/index.js';
+import { type DormantMove } from './dormant.js';
+import { type WriteBudget } 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 declare const MEMORY_BACKED_TABLES: readonly ["predictions", "decisions", "incidents", "processes", "policies", "skills", "project_briefs", "customer_notes"];
 /** 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. */
@@ -42,16 +43,10 @@ export declare function deleteEntry(hippoRoot: string, id: string, opts?: {
     reason?: string;
     automatic?: boolean;
 }): boolean;
-/** deleteEntry on the caller's open store, so a loop of deletes opens the store once; each delete still commits alone. */
-export declare function deleteEntryOn(db: DatabaseSyncLike, hippoRoot: string, id: string, opts?: {
-    actor?: string;
-    reason?: string;
-    automatic?: boolean;
-}): boolean;
 /** 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
+ *  `dormant` (src/store/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. */
@@ -65,20 +60,21 @@ export interface FlushComponent {
     deletes: readonly string[];
     dormant: readonly DormantMove[];
 }
-/** Tags a flush error with the ids of the component it stopped at, for the partial sleep audit row; the first tag wins. */
-export declare function noteFailedUnit(err: Error, component: FlushComponent | undefined): void;
 /** The ids noteFailedUnit tagged `err` with, if a flush threw it. */
 export declare function failedUnitOf(err: Error | null): string[] | undefined;
-/** 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 declare function batchWriteAndDeleteOn(db: DatabaseSyncLike, hippoRoot: string, components: readonly FlushComponent[], from: number, opts: {
-    snapshot?: ReadonlyMap<string, MemoryEntry>;
-    holdMs: number;
-    clock?: () => number;
-}): FlushChunk;
-/** Where the next transaction starts, and the ids this one removed from `memories`. */
-export interface FlushChunk {
-    next: number;
-    removedIds: string[];
-}
+/** Deletes each target in its own transaction on one store handle; `true` where the row went. */
+export declare function deleteEntriesOneByOne(hippoRoot: string, targets: readonly {
+    id: string;
+    reason: string;
+}[], opts: {
+    actor?: string;
+    automatic?: boolean;
+}): boolean[];
+/** Commits whole components in transactions of about `budget.holdMs` on one store handle, 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 declare function commitInChunks(hippoRoot: string, components: readonly FlushComponent[], opts: {
+    snapshot: ReadonlyMap<string, MemoryEntry>;
+    budget: WriteBudget;
+    busyWaitMs: number;
+}): Promise<string[]>;
 //# sourceMappingURL=delete-and-batch.d.ts.map

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

@@ -1,15 +1,15 @@
-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 { AUTO_DELETABLE_SQL } from '../core/memory.js';
+import { openHippoDb, 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 { 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. */
@@ -64,7 +64,7 @@ export function deleteEntryCore(db, id, opts) {
         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.
@@ -94,18 +94,8 @@ export function deleteEntry(hippoRoot, id, opts) {
     }
 }
 /** 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');
@@ -125,7 +115,7 @@ function mergeOwnChanges(base, ours, live) {
 /** 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
+ *  `dormant` (src/store/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. */
@@ -145,7 +135,7 @@ export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds, opts) {
 }
 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 +147,14 @@ 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;
-    // 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 {
+    // 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.
+    withWriteScope(db, 'flush_chunk', () => {
+        const begunAt = now();
         do {
             const at = next++;
             try {
@@ -184,17 +173,7 @@ export function batchWriteAndDeleteOn(db, hippoRoot, components, from, opts) {
         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 */ }
-        }
-        throw error;
-    }
+    });
     reportChunk(hippoRoot, out);
     return { next, removedIds: out.removedIds };
 }
@@ -301,11 +280,56 @@ 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 [];
+    const db = openStore(hippoRoot);
+    try {
+        return targets.map((target) => deleteEntryOn(db, hippoRoot, target.id, { ...opts, reason: target.reason }));
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Commits whole components in transactions of about `budget.holdMs` on one store handle, 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';
+/** True for the two compaction boundary types. */
+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`: 2 = written by a binary that can write boundary rows, so `event_type` has four values. */
+export declare const DELIVERY_LEDGER_VERSION = 2;
 /** Rejected candidate rows kept per event; the rest only add to `rejected_unlisted`. */
 export declare const DELIVERY_REJECTED_ROW_CAP = 16;
 export interface DeliveryCandidateInput {
@@ -123,7 +125,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,12 @@
-// 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 } from '../util/log.js';
+/** True for the two compaction boundary types. */
+export const isBoundaryEvent = (type) => type === 'pre-compact' || type === 'compact-resume';
+/** Row format version in `delivery_events.ledger_version`: 2 = written by a binary that can write boundary rows, so `event_type` has four values. */
+export const DELIVERY_LEDGER_VERSION = 2;
 /** 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,7 +38,8 @@ 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)
@@ -89,11 +91,14 @@ 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');
+    // A boundary row carries no prompt facts, whatever the payload holds.
+    const prompt = isBoundaryEvent(eventType) ? null : payload.prompt;
     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',
+        eventType,
         surface: 'hook',
         storeHash: init.storeHash,
         writeStore: init.writeStore,
@@ -101,8 +106,8 @@ function buildEvent(init, payload, state, ts, startedMs) {
         sessionId: payload.payloadSession ?? payload.envSession,
         sessionState: payload.sessionState,
         hostTurnId: payload.hostTurnId,
-        promptHash: payload.prompt !== null ? blockHash(payload.prompt) : null,
-        promptLength: payload.prompt?.length ?? 0,
+        promptHash: prompt !== null ? blockHash(prompt) : null,
+        promptLength: prompt?.length ?? 0,
         queryHash: null,
         recallTraceId: null,
         blockState: state.disabledSeen ? 'disabled' : outcome.state,
@@ -135,7 +140,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 +155,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 +169,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 +183,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);
-        }
-    };
+    const guard = guardFor(state, fault);
     const { qualityDropped, offer, reject, dropMissing, gated, selected } = candidateMethods(state, guard);
     return {
         root: init.root,
@@ -238,4 +236,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

package/dist/store/diagnostics.d.ts

@@ -0,0 +1,47 @@
+import { type CompactionCounts, type TokenTally } from './doctor-reads.js';
+import type { JsonObject } from './working-memory.js';
+/** One read's value, or the message of the error that stopped it, so a broken table never hides the reads beside it. */
+export type Attempt<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** ISO times the health reads count from. */
+export interface HealthCutoffs {
+    /** Token and failure rows at or after this count. */
+    readonly since: string;
+    /** A compaction unfinished since before this is stuck. */
+    readonly stuckBefore: string;
+    /** A started compaction older than this is past replaying. */
+    readonly transcriptFloor: string;
+}
+export interface StoreHealth {
+    readonly schemaVersion: number;
+    /** Null when the table is missing or unreadable. */
+    readonly memories: number | null;
+    readonly dormant: number | null;
+    /** Null inside a read that worked means the store has no full-text index. */
+    readonly fts: Attempt<{
+        memories: number;
+        fts: number;
+    } | null>;
+    readonly tokens: Attempt<TokenTally>;
+    readonly failures: Attempt<number>;
+    /** Undefined inside a read that worked means the store never slept. */
+    readonly lastSleep: Attempt<string | undefined>;
+    readonly compactions: Attempt<CompactionCounts>;
+}
+/** Everything `hippo doctor` reads from one store; throws when it cannot be opened or its schema version read. */
+export declare function readStoreHealth(hippoRoot: string, cutoffs: HealthCutoffs): StoreHealth;
+export interface StoreInventory {
+    readonly schemaVersion: number;
+    /** Oldest hippo binary the store allows, or null when it names none. */
+    readonly minCompatibleBinary: string | null;
+    /** Row count by table name; null for a table that cannot be counted. */
+    readonly tables: JsonObject;
+}
+/** Schema version, oldest allowed binary and row count of every table, for a support bundle; never reads a memory column. */
+export declare function readStoreInventory(hippoRoot: string): StoreInventory;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/store/diagnostics.js

@@ -0,0 +1,51 @@
+// What `hippo doctor` and `hippo support-bundle` read from a store: one read-only open each, plain data out.
+import { closeHippoDb, countTableRows, ftsRowCounts, getMeta, getSchemaVersion, openHippoDbReadOnly } from '../db/index.js';
+import { listTableNames } from '../db/tables.js';
+import { errorMessage } from '../util/log.js';
+import { compactionCountsAt, tokenTallySince } from './doctor-reads.js';
+import { countFailuresSince } from './failure-log.js';
+import { lastConsolidationAt } from './index-and-stats.js';
+function attempt(read) {
+    try {
+        return { ok: true, value: read() };
+    }
+    catch (err) {
+        // The caller turns the message into its own check, so the error stops here.
+        return { ok: false, message: errorMessage(err) };
+    }
+}
+/** Everything `hippo doctor` reads from one store; throws when it cannot be opened or its schema version read. */
+export function readStoreHealth(hippoRoot, cutoffs) {
+    const db = openHippoDbReadOnly(hippoRoot);
+    try {
+        return {
+            schemaVersion: getSchemaVersion(db),
+            memories: countTableRows(db, 'memories'),
+            dormant: countTableRows(db, 'dormant_memories'),
+            fts: attempt(() => ftsRowCounts(db)),
+            tokens: attempt(() => tokenTallySince(db, cutoffs.since)),
+            failures: attempt(() => countFailuresSince(db, cutoffs.since)),
+            lastSleep: attempt(() => lastConsolidationAt(db)),
+            compactions: attempt(() => compactionCountsAt(db, cutoffs.stuckBefore, cutoffs.transcriptFloor)),
+        };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Schema version, oldest allowed binary and row count of every table, for a support bundle; never reads a memory column. */
+export function readStoreInventory(hippoRoot) {
+    const db = openHippoDbReadOnly(hippoRoot);
+    try {
+        const schemaVersion = getSchemaVersion(db);
+        const minCompatibleBinary = getMeta(db, 'min_compatible_binary', '') || null;
+        const tables = {};
+        for (const name of listTableNames(db))
+            tables[name] = countTableRows(db, name);
+        return { schemaVersion, minCompatibleBinary, tables };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=diagnostics.js.map

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

@@ -0,0 +1,16 @@
+import type { DatabaseSyncLike } from '../db/index.js';
+export interface CompactionCounts {
+    total: number;
+    summarised: number;
+    started: number;
+}
+/** Compaction records in all, those with a summary whose memories never got saved, and those still without a summary; each cutoff is an ISO time. */
+export declare function compactionCountsAt(db: DatabaseSyncLike, stuckBefore: string, transcriptFloor: string): CompactionCounts;
+export interface TokenTally {
+    injected: number;
+    tokensSent: number;
+    tokensReread: number;
+}
+/** Memory blocks injected since `sinceIso`, the tokens they sent and the tokens later model calls re-read. */
+export declare function tokenTallySince(db: DatabaseSyncLike, sinceIso: string): TokenTally;
+//# sourceMappingURL=doctor-reads.d.ts.map