hippo-memory 1.54.0 → 1.56.0

package/dist/delivery-recorder.d.ts

@@ -0,0 +1,127 @@
+import type { MemoryEntry } from './memory.js';
+import { type PromptRecallGate } from './prompt-recall.js';
+export type DeliveryRuntime = 'claude-code' | 'codex' | 'unknown';
+export type DeliveryEventType = 'prompt-submit' | 'pinned-manual';
+export type DeliverySurface = 'hook' | 'context';
+export type DeliveryWriteStore = 'local' | 'global';
+export type DeliverySessionState = 'payload' | 'env' | 'missing' | 'subagent';
+export type DeliveryBlockState = 'sent' | 'reused' | 'reused-recall-sent' | 'empty' | 'disabled';
+export type DeliveryPool = 'pin' | 'recent' | 'prompt-recall' | 'strength' | 'search';
+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;
+/** Rejected candidate rows kept per event; the rest only add to `rejected_unlisted`. */
+export declare const DELIVERY_REJECTED_ROW_CAP = 16;
+export interface DeliveryCandidateInput {
+    memoryId: string;
+    sourceStore: DeliveryWriteStore;
+    pool: DeliveryPool;
+    stage: DeliveryStage;
+    outcome: DeliveryOutcome;
+    reason: DeliveryRejectReason | null;
+    rank: number | null;
+    score: number | null;
+    tokens: number | null;
+}
+/** One event as the writer stores it; the writer adds `turn_seq`, `duplicate_of` and the format version. */
+export interface DeliveryEventInput {
+    ts: string;
+    tenantId: string;
+    runtime: DeliveryRuntime;
+    eventType: DeliveryEventType;
+    surface: DeliverySurface;
+    storeHash: string;
+    writeStore: DeliveryWriteStore;
+    projectHash: string | null;
+    sessionId: string | null;
+    sessionState: DeliverySessionState;
+    hostTurnId: string | null;
+    promptHash: string | null;
+    promptLength: number;
+    queryHash: string | null;
+    recallTraceId: number | null;
+    blockState: DeliveryBlockState;
+    promptRecall: boolean;
+    consideredCount: number;
+    filteredCount: number;
+    selectedCount: number;
+    emittedCount: number;
+    rejectedCount: number;
+    rejectedUnlisted: number;
+    sectionsShown: number;
+    sectionsDropped: number;
+    budgetTokens: number;
+    selectedTokens: number;
+    injectedTokens: number;
+    staticHash: string | null;
+    recallHash: string | null;
+    emittedHash: string | null;
+    elapsedMs: number;
+    candidates: readonly DeliveryCandidateInput[];
+}
+export interface DeliveryFacts {
+    projectName: string;
+    budgetTokens: number;
+    promptRecall: boolean;
+}
+/** The shape of a returned context entry the observer reads. */
+export interface DeliverySelected {
+    entry: MemoryEntry;
+    score: number;
+    tokens: number;
+    isGlobal?: boolean;
+    promptRecall?: boolean;
+}
+/** What getContext reports while it selects. Every method only reads; none changes what is selected. */
+export interface DeliveryObserver {
+    facts(facts: DeliveryFacts): void;
+    sections(shown: number, dropped: number): void;
+    /** Returns `admit`'s own answer unchanged and lets its throws through. */
+    watchAdmit(admit: (e: MemoryEntry) => boolean): (e: MemoryEntry) => boolean;
+    /** The loader's quality floor dropped a row admit let through; with prompt recall on, eligibility reports it instead. */
+    qualityDropped(entry: MemoryEntry, isGlobal: boolean): void;
+    disabled(): void;
+    /** No `pool` means pin or recent by the entry's own flag. */
+    offer(entries: readonly MemoryEntry[], isGlobal: boolean, pool?: DeliveryPool): void;
+    reject(entry: MemoryEntry, stage: DeliveryStage, reason: DeliveryRejectReason, score?: number, tokens?: number): void;
+    dropMissing(before: readonly MemoryEntry[], after: readonly MemoryEntry[], stage: DeliveryStage, reason: DeliveryRejectReason): void;
+    gated(prompt: ReadonlySet<string>, candidates: readonly {
+        id: string;
+        tokens: ReadonlySet<string>;
+    }[], gate: PromptRecallGate, kept: readonly {
+        item: {
+            id: string;
+        };
+    }[]): void;
+    selected(items: readonly DeliverySelected[]): void;
+}
+/** What the renderer sent, reported once at its exit. */
+export interface DeliveryOutcomeInput {
+    state: DeliveryBlockState;
+    staticHash?: string | null;
+    recallHash?: string | null;
+    /** The exact text the agent receives: the hook's additionalContext, or every stdout byte, newline included. */
+    emittedText?: string | null;
+    /** The static block was skipped as unchanged, so its entries are reused, not sent. */
+    staticReused?: boolean;
+}
+export interface DeliveryRecorder extends DeliveryObserver {
+    readonly root: string;
+    delivered(outcome: DeliveryOutcomeInput): void;
+    /** Builds the event and hands it to `write` once per call; throws on an injected fault, and writes nothing once broken. */
+    flush(write: (input: DeliveryEventInput) => number | null): void;
+}
+export interface DeliveryRecorderInit {
+    /** The store the event is written to. */
+    root: string;
+    storeHash: string;
+    writeStore: DeliveryWriteStore;
+    tenantId: string;
+    stdinText?: string;
+    envSessionId?: string;
+}
+/** 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

@@ -0,0 +1,218 @@
+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;
+/** 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.
+const STAGE_DEPTH = new Map([
+    ['load', 0], ['eligible', 1], ['gate', 2], ['budget', 3], ['limit', 4], ['final', 5],
+]);
+function storeOf(isGlobal) {
+    return isGlobal === true ? 'global' : 'local';
+}
+function byDepthThenScore(a, b) {
+    const depth = (STAGE_DEPTH.get(b.stage ?? 'load') ?? 0) - (STAGE_DEPTH.get(a.stage ?? 'load') ?? 0);
+    if (depth !== 0)
+        return depth;
+    const score = (b.score ?? Number.NEGATIVE_INFINITY) - (a.score ?? Number.NEGATIVE_INFINITY);
+    if (score !== 0 && !Number.isNaN(score))
+        return score;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+/** 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 = process.env.HIPPO_TEST_DELIVERY_FAULT ?? '';
+    const payloadSession = hookPayloadSessionId(init.stdinText);
+    const subagent = isSubagentPayload(init.stdinText);
+    const envSession = init.envSessionId !== undefined && init.envSessionId !== '' ? init.envSessionId : null;
+    const prompt = hookPayloadString(init.stdinText, 'prompt');
+    const rawTurnId = hookPayloadString(init.stdinText, 'turn_id');
+    const hostTurnId = rawTurnId !== null && rawTurnId.trim() !== '' ? rawTurnId : null;
+    const hookEvent = hookPayloadString(init.stdinText, 'hook_event_name');
+    const sessionState = subagent
+        ? 'subagent'
+        : payloadSession !== null ? 'payload' : envSession !== null ? 'env' : 'missing';
+    const candidates = new Map();
+    const picked = new Map();
+    const filtered = new Set();
+    let facts = null;
+    let shown = 0;
+    let dropped = 0;
+    let disabledSeen = false;
+    let outcome = { state: 'empty' };
+    let broken = null;
+    let flushed = false;
+    const guard = (fn) => {
+        if (broken !== null)
+            return;
+        try {
+            if (fault === 'observe')
+                throw new Error('injected observe fault');
+            fn();
+        }
+        catch (error) {
+            broken = error instanceof Error ? error.message : String(error);
+        }
+    };
+    const rejectId = (id, stage, reason, score, tokens) => {
+        const held = candidates.get(id);
+        // First rejection wins; an id never offered is not a candidate of this call.
+        if (!held || held.reason !== null)
+            return;
+        candidates.set(id, { ...held, stage, reason, score, tokens });
+    };
+    const build = () => {
+        if (fault === 'build')
+            throw new Error('injected build fault');
+        const staticReused = outcome.staticReused === true;
+        const rows = [];
+        for (const p of picked.values()) {
+            const held = 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',
+                stage: 'final',
+                outcome: staticReused && !p.promptRecall ? 'reused' : 'emitted',
+                reason: null,
+                rank: p.rank,
+                score: p.score,
+                tokens: p.tokens,
+            });
+        }
+        const rejected = [];
+        let undecided = 0;
+        for (const c of candidates.values()) {
+            if (picked.has(c.id))
+                continue;
+            if (c.reason === null)
+                undecided += 1;
+            else
+                rejected.push(c);
+        }
+        rejected.sort(byDepthThenScore);
+        for (const c of rejected.slice(0, DELIVERY_REJECTED_ROW_CAP)) {
+            rows.push({
+                memoryId: c.id, sourceStore: c.sourceStore, pool: c.pool, stage: c.stage ?? 'load', outcome: 'rejected',
+                reason: c.reason, rank: null, score: c.score, tokens: c.tokens,
+            });
+        }
+        const overflow = Math.max(0, rejected.length - DELIVERY_REJECTED_ROW_CAP);
+        const emitted = outcome.emittedText ?? null;
+        return {
+            ts,
+            tenantId: init.tenantId,
+            runtime: hostTurnId !== null ? 'codex' : hookEvent !== null ? 'claude-code' : 'unknown',
+            eventType: hookEvent === 'UserPromptSubmit' ? 'prompt-submit' : 'pinned-manual',
+            surface: 'hook',
+            storeHash: init.storeHash,
+            writeStore: init.writeStore,
+            projectHash: facts !== null && facts.projectName !== '' ? blockHash(facts.projectName) : null,
+            sessionId: payloadSession ?? envSession,
+            sessionState,
+            hostTurnId,
+            promptHash: prompt !== null ? blockHash(prompt) : null,
+            promptLength: prompt?.length ?? 0,
+            queryHash: null,
+            recallTraceId: null,
+            blockState: disabledSeen ? 'disabled' : outcome.state,
+            promptRecall: facts?.promptRecall === true,
+            consideredCount: new Set([...candidates.keys(), ...picked.keys()]).size,
+            filteredCount: filtered.size,
+            selectedCount: picked.size,
+            emittedCount: rows.filter((r) => r.outcome === 'emitted').length,
+            rejectedCount: rejected.length + undecided,
+            rejectedUnlisted: overflow + undecided,
+            sectionsShown: shown,
+            sectionsDropped: dropped,
+            budgetTokens: facts?.budgetTokens ?? 0,
+            selectedTokens: [...picked.values()].reduce((sum, p) => sum + p.tokens, 0),
+            injectedTokens: emitted !== null ? estimateTokens(emitted) : 0,
+            staticHash: outcome.staticHash ?? null,
+            recallHash: outcome.recallHash ?? null,
+            emittedHash: emitted !== null ? blockHash(emitted) : null,
+            elapsedMs: Math.max(0, Date.now() - startedMs),
+            candidates: rows,
+        };
+    };
+    return {
+        root: init.root,
+        facts: (f) => guard(() => { facts = { ...f }; }),
+        sections: (s, d) => guard(() => { shown = s; dropped = d; }),
+        watchAdmit: (admit) => (e) => {
+            const ok = admit(e);
+            if (!ok)
+                guard(() => { filtered.add(e.id); });
+            return ok;
+        },
+        qualityDropped: (e, isGlobal) => guard(() => {
+            filtered.add(e.id);
+            if (!candidates.has(e.id)) {
+                candidates.set(e.id, {
+                    id: e.id, sourceStore: storeOf(isGlobal), pool: 'recent', stage: null, reason: null, score: null, tokens: null,
+                });
+            }
+            rejectId(e.id, 'load', 'quality', null, null);
+        }),
+        disabled: () => guard(() => { disabledSeen = true; }),
+        offer: (entries, isGlobal, pool) => guard(() => {
+            for (const e of entries) {
+                const held = candidates.get(e.id);
+                const wanted = pool ?? (e.pinned ? 'pin' : 'recent');
+                // A loaded recent row the prompt-recall gate then judges belongs to that pool.
+                const relabel = held !== undefined && held.reason === null && held.pool === 'recent' && wanted === 'prompt-recall';
+                if (held !== undefined && !relabel)
+                    continue;
+                candidates.set(e.id, {
+                    id: e.id, sourceStore: storeOf(isGlobal), pool: wanted, stage: null, reason: null, score: null, tokens: null,
+                });
+            }
+        }),
+        reject: (e, stage, reason, score, tokens) => guard(() => rejectId(e.id, stage, reason, score ?? null, 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(e.id, stage, reason, null, null);
+        }),
+        gated: (prompt, items, gate, kept) => guard(() => {
+            const keptIds = new Set(kept.map((g) => g.item.id));
+            for (const c of items) {
+                if (keptIds.has(c.id))
+                    continue;
+                const { score, shared } = scoreOverlap(prompt, c.tokens, gate.metric);
+                const cleared = score >= gate.threshold && shared >= gate.minShared;
+                rejectId(c.id, 'gate', cleared ? 'gate-max-items' : 'gate-below-threshold', score, null);
+            }
+        }),
+        selected: (items) => guard(() => {
+            picked.clear();
+            items.forEach((r, i) => {
+                picked.set(r.entry.id, {
+                    entry: r.entry, rank: i + 1, score: r.score, tokens: r.tokens,
+                    sourceStore: storeOf(r.isGlobal), promptRecall: r.promptRecall === true,
+                });
+            });
+        }),
+        delivered: (o) => guard(() => { outcome = { ...o }; }),
+        flush: (write) => {
+            if (flushed)
+                return;
+            flushed = true;
+            if (broken !== null) {
+                console.error(`[hippo] delivery ledger skipped: recorder failed: ${broken}`);
+                return;
+            }
+            const input = build();
+            if (fault === 'flush')
+                throw new Error('injected flush fault');
+            write(input);
+        },
+    };
+}
+//# sourceMappingURL=delivery-recorder.js.map

package/dist/hooks.d.ts

@@ -156,7 +156,7 @@ export declare function codexHomeDir(home?: string, env?: Readonly<Record<string
 /** Codex counts as installed only when its config folder exists: Codex itself refuses a CODEX_HOME that is not a folder. */
 export declare function isCodexPresent(home?: string): boolean;
 /** Codex hashes each hook and skips new or changed ones until the user reviews them in `/hooks`, so the reminder says what they would trust. */
-export declare const CODEX_TRUST_LINE = "The per-prompt hook sends your pinned memories plus the five most recent ones. Codex runs hippo's hooks only after you trust them once in `/hooks`.";
+export declare const CODEX_TRUST_LINE = "The per-prompt hook sends your pinned memories plus up to 5 that match the prompt. Codex runs hippo's hooks only after you trust them once in `/hooks`.";
 /**
  * Default log path consumed by `hippo last-sleep`. Shared fallback when
  * a caller doesn't pass --path explicitly.

package/dist/hooks.js

@@ -134,7 +134,7 @@ export function isCodexPresent(home = homeDir()) {
     return fs.statSync(codexHomeDir(home), { throwIfNoEntry: false })?.isDirectory() === true;
 }
 /** Codex hashes each hook and skips new or changed ones until the user reviews them in `/hooks`, so the reminder says what they would trust. */
-export const CODEX_TRUST_LINE = "The per-prompt hook sends your pinned memories plus the five most recent ones. Codex runs hippo's hooks only after you trust them once in `/hooks`.";
+export const CODEX_TRUST_LINE = "The per-prompt hook sends your pinned memories plus up to 5 that match the prompt. Codex runs hippo's hooks only after you trust them once in `/hooks`.";
 /**
  * Default log path consumed by `hippo last-sleep`. Shared fallback when
  * a caller doesn't pass --path explicitly.

package/dist/recall-trace.d.ts

@@ -17,6 +17,7 @@
  */
 import { type DatabaseSyncLike } from './db.js';
 import type { RerankStep } from './search.js';
+import { type DeliveryEventInput } from './delivery-recorder.js';
 /** One ranked result to persist alongside its trace row. */
 export interface RecallTraceResultInput {
     memoryId: string;
@@ -114,4 +115,72 @@ export interface RecordTraceOutcomeInput {
  * Fail-soft: never throws.
  */
 export declare function recordTraceOutcome(db: DatabaseSyncLike, input: RecordTraceOutcomeInput): void;
+/** Pruned on write, counted back from the event's ts capped at the real clock, so a far-future fake time spares real rows. */
+export declare const DELIVERY_LEDGER_RETENTION_DAYS = 90;
+/** Lock wait for the ledger's own connection: a busy store drops the row rather than slow the hook. */
+export declare const DELIVERY_LEDGER_WAIT_MS = 50;
+/** Two prompt-identical events without a host turn id this close together are one turn fired twice. */
+export declare const DELIVERY_DUPLICATE_WINDOW_MS = 2000;
+/** One stored `delivery_candidates` row. */
+export interface DeliveryCandidateRow {
+    event_id: number;
+    tenant_id: string;
+    memory_id: string;
+    source_store: string;
+    pool: string;
+    stage: string;
+    outcome: string;
+    reason: string | null;
+    cand_rank: number | null;
+    score: number | null;
+    tokens: number | null;
+}
+/** One stored `delivery_events` row with its candidate rows. */
+export interface DeliveryEventRow {
+    id: number;
+    ts: string;
+    ledger_version: number;
+    tenant_id: string;
+    runtime: string;
+    event_type: string;
+    surface: string;
+    store_hash: string;
+    write_store: string;
+    project_hash: string | null;
+    session_id: string | null;
+    session_state: string;
+    host_turn_id: string | null;
+    turn_seq: number | null;
+    duplicate_of: number | null;
+    prompt_hash: string | null;
+    prompt_length: number;
+    query_hash: string | null;
+    recall_trace_id: number | null;
+    block_state: string;
+    prompt_recall: number;
+    considered_count: number;
+    filtered_count: number;
+    selected_count: number;
+    emitted_count: number;
+    rejected_count: number;
+    rejected_unlisted: number;
+    sections_shown: number;
+    sections_dropped: number;
+    budget_tokens: number;
+    selected_tokens: number;
+    injected_tokens: number;
+    static_hash: string | null;
+    recall_hash: string | null;
+    emitted_hash: string | null;
+    elapsed_ms: number;
+    candidates: DeliveryCandidateRow[];
+}
+/** One event plus its candidates in one write transaction, then prune; fail-soft. The caller must not hold a transaction on `db`. */
+export declare function writeDeliveryEvent(db: DatabaseSyncLike, input: DeliveryEventInput): number | null;
+/** Write on a short-lived connection that waits at most {@link DELIVERY_LEDGER_WAIT_MS} for the lock. Fail-soft. */
+export declare function writeDeliveryEventAtRoot(root: string, input: DeliveryEventInput): number | null;
+/** On a caller's open handle, which saves a second open and close per turn; the handle's own lock wait comes back after. */
+export declare function writeDeliveryEventOnHandle(db: DatabaseSyncLike, input: DeliveryEventInput): number | null;
+/** A session's delivery events in write order, each with its candidate rows; `sessionId` null reads session-less events. */
+export declare function readDeliveryEvents(db: DatabaseSyncLike, tenantId: string, sessionId: string | null): DeliveryEventRow[];
 //# sourceMappingURL=recall-trace.d.ts.map

package/dist/recall-trace.js

@@ -17,6 +17,7 @@
  */
 import { createHash } from 'node:crypto';
 import { openHippoDb, closeHippoDb } from './db.js';
+import { DELIVERY_LEDGER_VERSION } from './delivery-recorder.js';
 /**
  * Strip a RerankStep down to {stage, multiplier, scoreBefore, scoreAfter}
  * before persisting (F3 privacy fix, codex cross-model finding). `note` is
@@ -183,4 +184,139 @@ export function recordTraceOutcome(db, input) {
         console.error(`[hippo] recall trace outcome write failed: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+/** Pruned on write, counted back from the event's ts capped at the real clock, so a far-future fake time spares real rows. */
+export const DELIVERY_LEDGER_RETENTION_DAYS = 90;
+/** Lock wait for the ledger's own connection: a busy store drops the row rather than slow the hook. */
+export const DELIVERY_LEDGER_WAIT_MS = 50;
+/** Two prompt-identical events without a host turn id this close together are one turn fired twice. */
+export const DELIVERY_DUPLICATE_WINDOW_MS = 2000;
+const DELIVERY_EVENT_COLUMNS = [
+    'ts', 'ledger_version', 'tenant_id', 'runtime', 'event_type', 'surface', 'store_hash', 'write_store', 'project_hash',
+    'session_id', 'session_state', 'host_turn_id', 'turn_seq', 'duplicate_of', 'prompt_hash', 'prompt_length', 'query_hash',
+    'recall_trace_id', 'block_state', 'prompt_recall', 'considered_count', 'filtered_count', 'selected_count', 'emitted_count',
+    'rejected_count', 'rejected_unlisted', 'sections_shown', 'sections_dropped', 'budget_tokens', 'selected_tokens',
+    'injected_tokens', 'static_hash', 'recall_hash', 'emitted_hash', 'elapsed_ms',
+];
+function findDuplicateTurn(db, input) {
+    if (input.hostTurnId !== null) {
+        // SAFETY: a single `id` column, undefined when no row matches.
+        const row = db.prepare(`
+      SELECT id FROM delivery_events
+      WHERE tenant_id = ? AND session_id = ? AND event_type = ? AND host_turn_id = ? AND turn_seq IS NOT NULL
+      ORDER BY id LIMIT 1
+    `).get(input.tenantId, input.sessionId, input.eventType, input.hostTurnId);
+        return row?.id ?? null;
+    }
+    if (input.promptHash === null)
+        return null;
+    // SAFETY: rows carry exactly the `id` and `ts` columns selected.
+    const rows = db.prepare(`
+    SELECT id, ts FROM delivery_events
+    WHERE tenant_id = ? AND session_id = ? AND event_type = ? AND prompt_hash = ? AND host_turn_id IS NULL AND turn_seq IS NOT NULL
+    ORDER BY id
+  `).all(input.tenantId, input.sessionId, input.eventType, input.promptHash);
+    const at = Date.parse(input.ts);
+    // Absolute difference: two hook processes can commit out of ts order.
+    return rows.find((r) => Math.abs(Date.parse(r.ts) - at) <= DELIVERY_DUPLICATE_WINDOW_MS)?.id ?? null;
+}
+function nextTurnSeq(db, input) {
+    // SAFETY: a single MAX aggregate aliased `m`, NULL when the session has no turns yet.
+    const row = db.prepare(`
+    SELECT MAX(turn_seq) AS m FROM delivery_events
+    WHERE tenant_id = ? AND session_id = ? AND event_type = ? AND turn_seq IS NOT NULL
+  `).get(input.tenantId, input.sessionId, input.eventType);
+    return (row.m ?? 0) + 1;
+}
+/** One event plus its candidates in one write transaction, then prune; fail-soft. The caller must not hold a transaction on `db`. */
+export function writeDeliveryEvent(db, input) {
+    try {
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            // Missing-session and sub-agent events are not turns of a session, so they get no number and no duplicate check.
+            const isTurn = input.sessionId !== null && (input.sessionState === 'payload' || input.sessionState === 'env');
+            const duplicateOf = isTurn ? findDuplicateTurn(db, input) : null;
+            const turnSeq = isTurn && duplicateOf === null ? nextTurnSeq(db, input) : null;
+            const values = [
+                input.ts, DELIVERY_LEDGER_VERSION, input.tenantId, input.runtime, input.eventType, input.surface, input.storeHash,
+                input.writeStore, input.projectHash, input.sessionId, input.sessionState, input.hostTurnId, turnSeq, duplicateOf,
+                input.promptHash, input.promptLength, input.queryHash, input.recallTraceId, input.blockState, input.promptRecall ? 1 : 0,
+                input.consideredCount, input.filteredCount, input.selectedCount, input.emittedCount, input.rejectedCount,
+                input.rejectedUnlisted, input.sectionsShown, input.sectionsDropped, input.budgetTokens, input.selectedTokens,
+                input.injectedTokens, input.staticHash, input.recallHash, input.emittedHash, Math.round(input.elapsedMs),
+            ];
+            const eventId = Number(db.prepare(`
+        INSERT INTO delivery_events (${DELIVERY_EVENT_COLUMNS.join(', ')})
+        VALUES (${DELIVERY_EVENT_COLUMNS.map(() => '?').join(', ')})
+      `).run(...values).lastInsertRowid);
+            const insertCandidate = db.prepare(`
+        INSERT INTO delivery_candidates (event_id, tenant_id, memory_id, source_store, pool, stage, outcome, reason, cand_rank, score, tokens)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+            for (const c of input.candidates) {
+                insertCandidate.run(eventId, input.tenantId, c.memoryId, c.sourceStore, c.pool, c.stage, c.outcome, c.reason, c.rank, c.score, c.tokens);
+            }
+            const pruneFrom = Math.min(Date.parse(input.ts), Date.now());
+            const cutoff = new Date(pruneFrom - DELIVERY_LEDGER_RETENTION_DAYS * 86_400_000).toISOString();
+            db.prepare(`DELETE FROM delivery_events WHERE ts < ?`).run(cutoff);
+            db.exec('COMMIT');
+            return eventId;
+        }
+        catch (error) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* SQLite may already have rolled back (SQLITE_FULL, IOERR); keep the original error */ }
+            throw error;
+        }
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.error(`[hippo] delivery ledger write failed: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+/** Write on a short-lived connection that waits at most {@link DELIVERY_LEDGER_WAIT_MS} for the lock. Fail-soft. */
+export function writeDeliveryEventAtRoot(root, input) {
+    let db;
+    try {
+        db = openHippoDb(root, { busyWaitMs: DELIVERY_LEDGER_WAIT_MS });
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.error(`[hippo] delivery ledger write failed: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+    try {
+        return writeDeliveryEvent(db, input);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** On a caller's open handle, which saves a second open and close per turn; the handle's own lock wait comes back after. */
+export function writeDeliveryEventOnHandle(db, input) {
+    const prior = Math.trunc(Number(db.prepare('PRAGMA busy_timeout').get().timeout));
+    db.exec(`PRAGMA busy_timeout = ${DELIVERY_LEDGER_WAIT_MS}`);
+    try {
+        return writeDeliveryEvent(db, input);
+    }
+    finally {
+        db.exec(`PRAGMA busy_timeout = ${prior}`);
+    }
+}
+/** A session's delivery events in write order, each with its candidate rows; `sessionId` null reads session-less events. */
+export function readDeliveryEvents(db, tenantId, sessionId) {
+    // SAFETY: SELECT * over delivery_events returns exactly the columns DeliveryEventRow names, less `candidates`.
+    const events = db.prepare(`SELECT * FROM delivery_events WHERE tenant_id = ? AND session_id IS ? ORDER BY id`)
+        .all(tenantId, sessionId);
+    const candidates = db.prepare(`
+    SELECT * FROM delivery_candidates WHERE event_id = ?
+    ORDER BY outcome = 'rejected', cand_rank, memory_id
+  `);
+    return events.map((e) => ({
+        ...e,
+        // SAFETY: SELECT * over delivery_candidates returns exactly the columns DeliveryCandidateRow names.
+        candidates: candidates.all(e.id),
+    }));
+}
 //# sourceMappingURL=recall-trace.js.map

package/dist/session-digest.js

@@ -23,8 +23,6 @@ export const MAX_FILES = 10;
 export const MAX_DIGEST_CHARS = 1200;
 /** Bounds a detached worker's memory; the final message sits at the end, so a tail read loses nothing. */
 export const READ_CAP_BYTES = 64 * 1024 * 1024;
-/** The pinned hook shows the newest 5 memories, so older digests were never injected. */
-const RECENT_DIGESTS = 5;
 const CLAUDE_EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
 function transcriptItem(value) {
     return isObjectLike(value) && 'type' in value ? value : null;
@@ -441,12 +439,10 @@ export function isSessionDigestRow(entry) {
 export function sessionDigestId(tenantId, key) {
     return `mem_${createHash('sha256').update(`${SESSION_DIGEST_TAG}\n${tenantId}\n${key}`).digest('hex').slice(0, 12)}`;
 }
-/** What hippo could have injected into the session: recent digests and the ambient handoff, never this session's own. */
+/** What hippo could have injected into the session: any live digest (prompt recall reaches old ones) and the ambient handoff, never this session's own. */
 function injectedTexts(hippoRoot, opts) {
     const digests = loadAllEntries(hippoRoot, opts.tenantId)
         .filter((e) => isSessionDigestRow(e) && !e.superseded_by && e.source_session_id !== opts.key)
-        .sort((a, b) => (a.created < b.created ? 1 : a.created > b.created ? -1 : 0))
-        .slice(0, RECENT_DIGESTS)
         .map((e) => e.content);
     const handoff = loadLatestHandoff(hippoRoot, opts.tenantId, undefined, {
         unfinishedOnly: true,

package/dist/token-ledger.d.ts

@@ -116,6 +116,8 @@ interface ModelTagged {
 export declare function isSyntheticMessage(message: ModelTagged): boolean;
 /** A hook payload's non-empty `session_id`, or null; with `requiredSource`, also null when its `source` differs. */
 export declare function hookPayloadSessionId(stdinText: string | undefined, requiredSource?: string | null): string | null;
+/** A hook payload's string `field` as sent, or null when the payload or the field is missing or not a string. */
+export declare function hookPayloadString(stdinText: string | undefined, field: string): string | null;
 /** Whether a hook fired inside a sub-agent, the only payload with `agent_id` (https://code.claude.com/docs/en/hooks#common-input-fields).
  *  Its `session_id` is the parent's, so a sub-agent's blocks and compactions must not count as the parent's. */
 export declare function isSubagentPayload(stdinText: string | undefined): boolean;

package/dist/token-ledger.js

@@ -174,6 +174,11 @@ export function hookPayloadSessionId(stdinText, requiredSource = null) {
         return null;
     return sessionId;
 }
+/** A hook payload's string `field` as sent, or null when the payload or the field is missing or not a string. */
+export function hookPayloadString(stdinText, field) {
+    const value = parseHookPayload(stdinText)?.[field];
+    return isJsonString(value) ? value : null;
+}
 /** Whether a hook fired inside a sub-agent, the only payload with `agent_id` (https://code.claude.com/docs/en/hooks#common-input-fields).
  *  Its `session_id` is the parent's, so a sub-agent's blocks and compactions must not count as the parent's. */
 export function isSubagentPayload(stdinText) {

package/dist/version.d.ts

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export declare const PACKAGE_VERSION = "1.54.0";
+export declare const PACKAGE_VERSION = "1.56.0";
 /** Compares plain x.y.z versions, positive if a > b; tags throw so the rollback guard never misfires silently. */
 export declare function compareSemver(a: string, b: string): number;
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export const PACKAGE_VERSION = '1.54.0';
+export const PACKAGE_VERSION = '1.56.0';
 /** Compares plain x.y.z versions, positive if a > b; tags throw so the rollback guard never misfires silently. */
 export function compareSemver(a, b) {
     const parse = (v) => {