hippo-memory 1.45.0 → 1.47.0

package/dist/dormant.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Dormant memories: what sleep does with a faded memory instead of deleting
+ * it (config `dormant.enabled`, on by default; `retentionDays` bounds how
+ * long one is kept).
+ *
+ * A dormant memory keeps its full content in `dormant_memories` (schema v44)
+ * but is no longer a `memories` row, so recall, context, every sleep pass and
+ * every other reader of `memories` stop seeing it exactly as if it had been
+ * deleted. `hippo dormant` lists and searches them, `hippo dormant restore`
+ * brings one back, `hippo dormant forget` deletes one for good.
+ *
+ * Not to be confused with the raw archive (`raw_archive`, `archiveRawMemory`,
+ * `hippo forget --archive`): that path removes a raw receipt's content and
+ * keeps only its metadata. A dormant memory keeps its content.
+ *
+ * DB-only helpers: the caller owns the handle and any transaction. The
+ * tenant-scoped entry points are api.listDormant / restoreDormant /
+ * forgetDormant.
+ */
+import type { DatabaseSyncLike } from './db.js';
+import type { MemoryEntry } from './memory.js';
+/** Why sleep made a memory dormant. Only the decay pass does today. */
+export type DormantReason = 'decay';
+/** One memory that sleep is moving out of active memory into the dormant store. */
+export interface DormantMove {
+    /** The memory as it stood when it faded; restored verbatim apart from its recall clock. */
+    entry: MemoryEntry;
+    /** Live strength at the moment it went dormant (below the decay threshold). */
+    strength: number;
+    reason: DormantReason;
+    /** ISO time of the sleep that made it dormant. */
+    dormantAt: string;
+}
+/** A dormant memory as listed to a user. */
+export interface DormantMemory {
+    id: string;
+    tenantId: string;
+    content: string;
+    tags: string[];
+    /** Live strength when it went dormant. */
+    strength: number;
+    /** Why it went dormant (`decay`). */
+    reason: string;
+    /** ISO time it went dormant. */
+    dormantAt: string;
+}
+/** Options for {@link listDormantRows}. */
+export interface ListDormantOpts {
+    /** Whitespace-separated terms; a row must contain every term (case-insensitive substring). */
+    query?: string;
+    /** Maximum rows returned, newest first. Default 20. */
+    limit?: number;
+}
+/**
+ * Insert (or refresh) the dormant snapshot for `move.entry`. Does not touch
+ * the `memories` row: the caller deletes it in the same transaction, so the
+ * memory is never in both places or in neither.
+ */
+export declare function insertDormantRow(db: DatabaseSyncLike, move: DormantMove): void;
+/** A tenant's dormant memories, newest first, optionally filtered by search terms. */
+export declare function listDormantRows(db: DatabaseSyncLike, tenantId: string, opts?: ListDormantOpts): DormantMemory[];
+/** A dormant memory's stored snapshot plus when and why it went dormant. */
+export interface DormantSnapshot {
+    entry: MemoryEntry;
+    reason: string;
+    strength: number;
+    dormantAt: string;
+}
+/**
+ * The stored snapshot for a tenant's dormant memory, or null when the tenant
+ * has no dormant memory with that id (another tenant's id reads as absent).
+ */
+export declare function readDormantSnapshot(db: DatabaseSyncLike, tenantId: string, id: string): DormantSnapshot | null;
+/** Whether a tenant has a dormant memory with this id (snapshot readable or not). */
+export declare function hasDormantRow(db: DatabaseSyncLike, tenantId: string, id: string): boolean;
+/** Delete a tenant's dormant memory. Returns false when there was none. */
+export declare function deleteDormantRow(db: DatabaseSyncLike, tenantId: string, id: string): boolean;
+/**
+ * Delete every dormant memory in the tenant whose content has this rejection
+ * digest, so a rejected value cannot linger in dormant storage. Returns the
+ * ids removed. Same O(N) scan as the live-row sweep in reject-flow.ts.
+ */
+export declare function purgeDormantByDigest(db: DatabaseSyncLike, tenantId: string, digest: string): string[];
+/** How many dormant memories went dormant before `cutoffIso` (a dry-run count). */
+export declare function countExpiredDormant(db: DatabaseSyncLike, cutoffIso: string): number;
+/**
+ * Delete every dormant memory (all tenants) that went dormant before
+ * `cutoffIso`: the `dormant.retentionDays` window. Returns how many went.
+ */
+export declare function purgeExpiredDormant(db: DatabaseSyncLike, cutoffIso: string): number;
+//# sourceMappingURL=dormant.d.ts.map

package/dist/dormant.js

@@ -0,0 +1,121 @@
+import { rejectionDigest } from './rejection.js';
+const DEFAULT_LIST_LIMIT = 20;
+/**
+ * Insert (or refresh) the dormant snapshot for `move.entry`. Does not touch
+ * the `memories` row: the caller deletes it in the same transaction, so the
+ * memory is never in both places or in neither.
+ */
+export function insertDormantRow(db, move) {
+    db.prepare(`
+    INSERT INTO dormant_memories (tenant_id, id, content, entry_json, reason, strength, dormant_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(tenant_id, id) DO UPDATE SET
+      content = excluded.content,
+      entry_json = excluded.entry_json,
+      reason = excluded.reason,
+      strength = excluded.strength,
+      dormant_at = excluded.dormant_at
+  `).run(move.entry.tenantId, move.entry.id, move.entry.content, JSON.stringify(move.entry), move.reason, move.strength, move.dormantAt);
+}
+/** Escape LIKE metacharacters so a search term matches literally (ESCAPE '\'). */
+function escapeLike(term) {
+    return term.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+}
+/**
+ * Parse a stored snapshot back into a MemoryEntry, or null when the row no
+ * longer matches the snapshot it carries (edited by hand, or truncated).
+ */
+function parseSnapshot(row) {
+    try {
+        // SAFETY: entry_json is only written by insertDormantRow from a MemoryEntry;
+        // the id / tenant / content checks below reject a row edited out of shape.
+        const entry = JSON.parse(row.entry_json);
+        if (entry.id !== row.id || entry.tenantId !== row.tenant_id || entry.content !== row.content) {
+            return null;
+        }
+        return entry;
+    }
+    catch {
+        return null;
+    }
+}
+function rowToDormantMemory(row) {
+    const entry = parseSnapshot(row);
+    return {
+        id: row.id,
+        tenantId: row.tenant_id,
+        content: row.content,
+        tags: entry && Array.isArray(entry.tags) ? entry.tags.map(String) : [],
+        strength: row.strength,
+        reason: row.reason,
+        dormantAt: row.dormant_at,
+    };
+}
+/** A tenant's dormant memories, newest first, optionally filtered by search terms. */
+export function listDormantRows(db, tenantId, opts = {}) {
+    const terms = (opts.query ?? '').trim().split(/\s+/).filter((t) => t.length > 0);
+    const limit = opts.limit !== undefined && Number.isFinite(opts.limit) && opts.limit >= 1
+        ? Math.floor(opts.limit)
+        : DEFAULT_LIST_LIMIT;
+    const termClauses = terms.map(() => ` AND content LIKE ? ESCAPE '\\'`).join('');
+    // SAFETY: rows' shape matches the seven columns named in the SELECT.
+    const rows = db.prepare(`SELECT tenant_id, id, content, entry_json, reason, strength, dormant_at
+       FROM dormant_memories
+      WHERE tenant_id = ?${termClauses}
+      ORDER BY dormant_at DESC, id ASC
+      LIMIT ?`).all(tenantId, ...terms.map((t) => `%${escapeLike(t)}%`), limit);
+    return rows.map(rowToDormantMemory);
+}
+/**
+ * The stored snapshot for a tenant's dormant memory, or null when the tenant
+ * has no dormant memory with that id (another tenant's id reads as absent).
+ */
+export function readDormantSnapshot(db, tenantId, id) {
+    // SAFETY: row's shape matches the seven columns named in the SELECT.
+    const row = db.prepare(`SELECT tenant_id, id, content, entry_json, reason, strength, dormant_at
+       FROM dormant_memories WHERE tenant_id = ? AND id = ?`).get(tenantId, id);
+    const entry = row ? parseSnapshot(row) : null;
+    return row && entry ? { entry, reason: row.reason, strength: row.strength, dormantAt: row.dormant_at } : null;
+}
+/** Whether a tenant has a dormant memory with this id (snapshot readable or not). */
+export function hasDormantRow(db, tenantId, id) {
+    return db.prepare(`SELECT 1 FROM dormant_memories WHERE tenant_id = ? AND id = ?`).get(tenantId, id) !== undefined;
+}
+/** Delete a tenant's dormant memory. Returns false when there was none. */
+export function deleteDormantRow(db, tenantId, id) {
+    const result = db.prepare(`DELETE FROM dormant_memories WHERE tenant_id = ? AND id = ?`).run(tenantId, id);
+    return Number(result.changes ?? 0) > 0;
+}
+/**
+ * Delete every dormant memory in the tenant whose content has this rejection
+ * digest, so a rejected value cannot linger in dormant storage. Returns the
+ * ids removed. Same O(N) scan as the live-row sweep in reject-flow.ts.
+ */
+export function purgeDormantByDigest(db, tenantId, digest) {
+    // SAFETY: rows' shape matches the two columns named in the SELECT.
+    const rows = db.prepare(`SELECT id, content FROM dormant_memories WHERE tenant_id = ?`)
+        .all(tenantId);
+    const removed = [];
+    for (const row of rows) {
+        if (rejectionDigest(row.content) !== digest)
+            continue;
+        deleteDormantRow(db, tenantId, row.id);
+        removed.push(row.id);
+    }
+    return removed;
+}
+/** How many dormant memories went dormant before `cutoffIso` (a dry-run count). */
+export function countExpiredDormant(db, cutoffIso) {
+    // SAFETY: row's shape matches the single aliased COUNT column in the SELECT.
+    const row = db.prepare(`SELECT COUNT(*) AS n FROM dormant_memories WHERE dormant_at < ?`).get(cutoffIso);
+    return Number(row.n);
+}
+/**
+ * Delete every dormant memory (all tenants) that went dormant before
+ * `cutoffIso`: the `dormant.retentionDays` window. Returns how many went.
+ */
+export function purgeExpiredDormant(db, cutoffIso) {
+    const result = db.prepare(`DELETE FROM dormant_memories WHERE dormant_at < ?`).run(cutoffIso);
+    return Number(result.changes ?? 0);
+}
+//# sourceMappingURL=dormant.js.map

package/dist/eval-stats.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Statistics and cost accounting for the token-efficiency evals (ROADMAP
+ * Part IX, TE3-TE5).
+ *
+ * - Cost: price provider usage over four buckets (uncached input, cache
+ *   write, cache read, output). Raw token counts overstate savings when most
+ *   input is already cache reads, so every dollar claim goes through here.
+ * - Uncertainty: paired bootstrap over tasks, cluster bootstrap (tasks that
+ *   share a repository are not independent), and a paired ratio bootstrap for
+ *   dollars per resolved task.
+ *
+ * Deterministic: every resampling function takes a seed, so a published
+ * result can be reproduced exactly.
+ */
+/** Token usage for one model call or one whole task, split by how it is billed. */
+export interface Usage {
+    /** Input tokens billed at the base input price (not read from or written to a cache). */
+    inputTokens: number;
+    /** Input tokens written to a prompt cache. */
+    cacheWriteTokens: number;
+    /** Input tokens read from a prompt cache. */
+    cacheReadTokens: number;
+    /** Output tokens, including any reasoning tokens the provider bills as output. */
+    outputTokens: number;
+}
+/**
+ * Prices in dollars per million tokens. Take them from the provider's
+ * current price page for the exact model; this module has no built-in
+ * prices because they change.
+ */
+export interface Prices {
+    inputPerMTok: number;
+    cacheWritePerMTok: number;
+    cacheReadPerMTok: number;
+    outputPerMTok: number;
+}
+/** Sum several usages bucket by bucket. */
+export declare function addUsage(...usages: Usage[]): Usage;
+/** Dollar cost of `usage` at `prices`. */
+export declare function priceUsage(usage: Usage, prices: Prices): number;
+/**
+ * Relative prices of the cache buckets against the base input price, for
+ * cost in "uncached-equivalent tokens" when no dollar prices are given.
+ * Defaults follow Anthropic's published ratios (5-minute cache write 1.25x,
+ * cache read 0.1x); pass the ratios for another provider when needed.
+ */
+export interface CacheRatios {
+    write: number;
+    read: number;
+}
+/** Default cache price ratios (write 1.25x, read 0.1x of base input). */
+export declare const DEFAULT_CACHE_RATIOS: Readonly<CacheRatios>;
+/** Input cost of `usage` in uncached-equivalent tokens (output excluded). */
+export declare function uncachedEquivalentInput(usage: Usage, ratios?: CacheRatios): number;
+/**
+ * Mulberry32: a small seeded PRNG returning floats in [0, 1). Same seed,
+ * same stream, on every platform.
+ */
+export declare function seededRandom(seed: number): () => number;
+/** A point estimate with a percentile bootstrap confidence interval. */
+export interface Estimate {
+    estimate: number;
+    low: number;
+    high: number;
+    /** Resamples drawn. */
+    iterations: number;
+}
+/** Options shared by the bootstrap functions. */
+export interface BootstrapOpts {
+    /** Resamples. Default 5000. */
+    iterations?: number;
+    /** Two-sided level, e.g. 0.05 for a 95% interval. Default 0.05. */
+    alpha?: number;
+    /** PRNG seed. Default 1. */
+    seed?: number;
+}
+/**
+ * Paired bootstrap for the mean of per-task differences (treatment minus
+ * control on the same task). An interval that excludes zero is the bar for
+ * calling a difference real.
+ */
+export declare function pairedBootstrap(diffs: number[], opts?: BootstrapOpts): Estimate;
+/**
+ * Cluster bootstrap for the mean of per-task differences: resamples whole
+ * clusters (for example all tasks from one repository), because tasks in a
+ * cluster share causes and are not independent draws.
+ */
+export declare function clusteredPairedBootstrap(diffsByCluster: ReadonlyMap<string, number[]>, opts?: BootstrapOpts): Estimate;
+/** One task's outcome in one arm, for {@link costPerResolvedDelta}. */
+export interface ArmOutcome {
+    /** Dollars (or uncached-equivalent tokens) spent on the task. */
+    cost: number;
+    /** Whether the task was resolved. */
+    resolved: boolean;
+}
+/** Result of {@link costPerResolvedDelta}. */
+export interface CostPerResolvedDelta {
+    control: number;
+    treatment: number;
+    /** treatment minus control, with its interval. */
+    delta: Estimate;
+    /** (treatment minus control) / control, with its interval. Negative is a saving. */
+    relative: Estimate;
+}
+/**
+ * Cost per resolved task in two arms run on the same tasks, with a paired
+ * bootstrap over tasks (a task is resampled with both of its arm outcomes).
+ * `control[i]` and `treatment[i]` must be the same task. Resamples in which
+ * an arm resolves nothing are dropped; `iterations` reports how many were
+ * kept.
+ */
+export declare function costPerResolvedDelta(control: ArmOutcome[], treatment: ArmOutcome[], opts?: BootstrapOpts): CostPerResolvedDelta;
+/**
+ * pass@k: share of tasks with at least one success in their first k runs.
+ * NaN when no task has k runs (not measured, which is not the same as 0).
+ */
+export declare function passAtK(runsByTask: boolean[][], k: number): number;
+/**
+ * pass^k: share of tasks whose first k runs all succeed (consistency).
+ * NaN when no task has k runs.
+ */
+export declare function passHatK(runsByTask: boolean[][], k: number): number;
+//# sourceMappingURL=eval-stats.d.ts.map

package/dist/eval-stats.js

@@ -0,0 +1,187 @@
+/**
+ * Statistics and cost accounting for the token-efficiency evals (ROADMAP
+ * Part IX, TE3-TE5).
+ *
+ * - Cost: price provider usage over four buckets (uncached input, cache
+ *   write, cache read, output). Raw token counts overstate savings when most
+ *   input is already cache reads, so every dollar claim goes through here.
+ * - Uncertainty: paired bootstrap over tasks, cluster bootstrap (tasks that
+ *   share a repository are not independent), and a paired ratio bootstrap for
+ *   dollars per resolved task.
+ *
+ * Deterministic: every resampling function takes a seed, so a published
+ * result can be reproduced exactly.
+ */
+/** Sum several usages bucket by bucket. */
+export function addUsage(...usages) {
+    const total = { inputTokens: 0, cacheWriteTokens: 0, cacheReadTokens: 0, outputTokens: 0 };
+    for (const u of usages) {
+        total.inputTokens += u.inputTokens;
+        total.cacheWriteTokens += u.cacheWriteTokens;
+        total.cacheReadTokens += u.cacheReadTokens;
+        total.outputTokens += u.outputTokens;
+    }
+    return total;
+}
+/** Dollar cost of `usage` at `prices`. */
+export function priceUsage(usage, prices) {
+    return (usage.inputTokens * prices.inputPerMTok
+        + usage.cacheWriteTokens * prices.cacheWritePerMTok
+        + usage.cacheReadTokens * prices.cacheReadPerMTok
+        + usage.outputTokens * prices.outputPerMTok) / 1_000_000;
+}
+/** Default cache price ratios (write 1.25x, read 0.1x of base input). */
+export const DEFAULT_CACHE_RATIOS = { write: 1.25, read: 0.1 };
+/** Input cost of `usage` in uncached-equivalent tokens (output excluded). */
+export function uncachedEquivalentInput(usage, ratios = DEFAULT_CACHE_RATIOS) {
+    return usage.inputTokens + usage.cacheWriteTokens * ratios.write + usage.cacheReadTokens * ratios.read;
+}
+/**
+ * Mulberry32: a small seeded PRNG returning floats in [0, 1). Same seed,
+ * same stream, on every platform.
+ */
+export function seededRandom(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function percentileInterval(samples, alpha) {
+    const sorted = [...samples].sort((x, y) => x - y);
+    const lowIdx = Math.max(0, Math.floor((alpha / 2) * sorted.length));
+    const highIdx = Math.min(sorted.length - 1, Math.ceil((1 - alpha / 2) * sorted.length) - 1);
+    return { low: sorted[lowIdx], high: sorted[highIdx] };
+}
+function mean(xs) {
+    return xs.length === 0 ? 0 : xs.reduce((s, x) => s + x, 0) / xs.length;
+}
+/**
+ * Paired bootstrap for the mean of per-task differences (treatment minus
+ * control on the same task). An interval that excludes zero is the bar for
+ * calling a difference real.
+ */
+export function pairedBootstrap(diffs, opts = {}) {
+    const iterations = opts.iterations ?? 5000;
+    const alpha = opts.alpha ?? 0.05;
+    if (diffs.length === 0)
+        return { estimate: 0, low: 0, high: 0, iterations: 0 };
+    const rand = seededRandom(opts.seed ?? 1);
+    const n = diffs.length;
+    const samples = [];
+    for (let b = 0; b < iterations; b++) {
+        let s = 0;
+        for (let i = 0; i < n; i++)
+            s += diffs[Math.floor(rand() * n)];
+        samples.push(s / n);
+    }
+    return { estimate: mean(diffs), ...percentileInterval(samples, alpha), iterations };
+}
+/**
+ * Cluster bootstrap for the mean of per-task differences: resamples whole
+ * clusters (for example all tasks from one repository), because tasks in a
+ * cluster share causes and are not independent draws.
+ */
+export function clusteredPairedBootstrap(diffsByCluster, opts = {}) {
+    const iterations = opts.iterations ?? 5000;
+    const alpha = opts.alpha ?? 0.05;
+    const clusters = [...diffsByCluster.values()].filter((c) => c.length > 0);
+    const all = clusters.flat();
+    if (all.length === 0)
+        return { estimate: 0, low: 0, high: 0, iterations: 0 };
+    const rand = seededRandom(opts.seed ?? 1);
+    const k = clusters.length;
+    const samples = [];
+    for (let b = 0; b < iterations; b++) {
+        let sum = 0;
+        let count = 0;
+        for (let i = 0; i < k; i++) {
+            const c = clusters[Math.floor(rand() * k)];
+            for (const d of c)
+                sum += d;
+            count += c.length;
+        }
+        samples.push(count === 0 ? 0 : sum / count);
+    }
+    return { estimate: mean(all), ...percentileInterval(samples, alpha), iterations };
+}
+function costPerResolved(outcomes) {
+    const resolved = outcomes.filter((o) => o.resolved).length;
+    const cost = outcomes.reduce((s, o) => s + o.cost, 0);
+    return resolved === 0 ? Number.POSITIVE_INFINITY : cost / resolved;
+}
+/**
+ * Cost per resolved task in two arms run on the same tasks, with a paired
+ * bootstrap over tasks (a task is resampled with both of its arm outcomes).
+ * `control[i]` and `treatment[i]` must be the same task. Resamples in which
+ * an arm resolves nothing are dropped; `iterations` reports how many were
+ * kept.
+ */
+export function costPerResolvedDelta(control, treatment, opts = {}) {
+    if (control.length !== treatment.length) {
+        throw new Error('control and treatment must list the same tasks in the same order');
+    }
+    const iterations = opts.iterations ?? 5000;
+    const alpha = opts.alpha ?? 0.05;
+    const c = costPerResolved(control);
+    const t = costPerResolved(treatment);
+    const rand = seededRandom(opts.seed ?? 1);
+    const n = control.length;
+    const deltas = [];
+    const relatives = [];
+    for (let b = 0; b < iterations && n > 0; b++) {
+        const cs = [];
+        const ts = [];
+        for (let i = 0; i < n; i++) {
+            const j = Math.floor(rand() * n);
+            cs.push(control[j]);
+            ts.push(treatment[j]);
+        }
+        const cc = costPerResolved(cs);
+        const tt = costPerResolved(ts);
+        if (!Number.isFinite(cc) || !Number.isFinite(tt))
+            continue;
+        deltas.push(tt - cc);
+        relatives.push((tt - cc) / cc);
+    }
+    const finite = Number.isFinite(c) && Number.isFinite(t);
+    const empty = { low: Number.NaN, high: Number.NaN };
+    return {
+        control: c,
+        treatment: t,
+        delta: {
+            estimate: finite ? t - c : Number.NaN,
+            ...(deltas.length > 0 ? percentileInterval(deltas, alpha) : empty),
+            iterations: deltas.length,
+        },
+        relative: {
+            estimate: finite ? (t - c) / c : Number.NaN,
+            ...(relatives.length > 0 ? percentileInterval(relatives, alpha) : empty),
+            iterations: relatives.length,
+        },
+    };
+}
+/**
+ * pass@k: share of tasks with at least one success in their first k runs.
+ * NaN when no task has k runs (not measured, which is not the same as 0).
+ */
+export function passAtK(runsByTask, k) {
+    const eligible = runsByTask.filter((r) => r.length >= k);
+    if (eligible.length === 0)
+        return Number.NaN;
+    return eligible.filter((r) => r.slice(0, k).some(Boolean)).length / eligible.length;
+}
+/**
+ * pass^k: share of tasks whose first k runs all succeed (consistency).
+ * NaN when no task has k runs.
+ */
+export function passHatK(runsByTask, k) {
+    const eligible = runsByTask.filter((r) => r.length >= k);
+    if (eligible.length === 0)
+        return Number.NaN;
+    return eligible.filter((r) => r.slice(0, k).every(Boolean)).length / eligible.length;
+}
+//# sourceMappingURL=eval-stats.js.map

package/dist/failure-log.d.ts

@@ -0,0 +1,49 @@
+/** Failure log (ROADMAP CD13): every failed tool call the capture-error hook sees, stored or not. */
+import type { CaptureErrorOutcome, RoutineRule } from './capture-error.js';
+import type { DatabaseSyncLike } from './db.js';
+/** Rows older than this are pruned on write, which also bounds how far back a repeat can be found. */
+export declare const FAILURE_LOG_RETENTION_DAYS = 90;
+/** A capture-error outcome, or `store-failed` when storing the lesson threw. */
+export type FailureOutcome = CaptureErrorOutcome | 'store-failed';
+/** One failed tool call, for {@link recordFailure}. Never the failure text: it can carry paths and secrets. */
+export interface FailureEvent {
+    tenantId: string;
+    /** Host session id from the hook payload; null when it had none. */
+    sessionId?: string | null;
+    tool?: string | null;
+    outcome: FailureOutcome;
+    /** The routine check that skipped it, for `skipped-routine`. */
+    rule?: RoutineRule | null;
+    /** Hash of the lesson text's signature, the key dedupe uses; null when the payload had no readable error. */
+    sigHash?: string | null;
+    /** Hash of the untruncated error plus the command's first two words, finer than `sigHash`. */
+    detailHash?: string | null;
+    /** Override the timestamp (tests). ISO string. */
+    now?: string;
+}
+/** Append one failure row and prune rows past {@link FAILURE_LOG_RETENTION_DAYS}. */
+export declare function recordFailure(db: DatabaseSyncLike, event: FailureEvent): void;
+/** Rated failures and repeats in one session, for {@link failuresBySession}. */
+export interface SessionFailures {
+    sessionId: string;
+    /** Failures hippo treats as lessons (stored, duplicate or store-failed) in the window. */
+    failures: number;
+    /** Of those, failures whose signature another session hit first. */
+    repeats: number;
+}
+/** Rated failures per session since `sinceIso`, the input for repeat-error rate per arm (CD11, CD12). */
+export declare function failuresBySession(db: DatabaseSyncLike, tenantId: string, sinceIso: string): SessionFailures[];
+/** Failure log totals over a window, for {@link summarizeFailures}. Counts only: a rate needs a holdout arm (CD11). */
+export interface FailureSummary {
+    /** ISO start of the window (inclusive). */
+    since: string;
+    outcomes: Record<FailureOutcome, number>;
+    total: number;
+    /** Rated failures from sessions with an id: the failures a repeat is counted among. */
+    rated: number;
+    repeats: number;
+    sessions: number;
+}
+/** Sum the failure log for one tenant since `sinceIso`. */
+export declare function summarizeFailures(db: DatabaseSyncLike, tenantId: string, sinceIso: string): FailureSummary;
+//# sourceMappingURL=failure-log.d.ts.map

package/dist/failure-log.js

@@ -0,0 +1,58 @@
+/** Rows older than this are pruned on write, which also bounds how far back a repeat can be found. */
+export const FAILURE_LOG_RETENTION_DAYS = 90;
+/** Longest session id or tool name kept; the hook payload is not trusted to be short. */
+const MAX_FIELD = 128;
+/** Append one failure row and prune rows past {@link FAILURE_LOG_RETENTION_DAYS}. */
+export function recordFailure(db, event) {
+    // Normalised, because the window and prune compare timestamps as strings.
+    const now = new Date(event.now ?? Date.now()).toISOString();
+    db.prepare(`INSERT INTO failure_log (ts, tenant_id, session_id, tool, outcome, skip_rule, sig_hash, detail_hash)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(now, event.tenantId, event.sessionId?.slice(0, MAX_FIELD) ?? null, event.tool?.slice(0, MAX_FIELD) ?? null, event.outcome, event.rule ?? null, event.sigHash ?? null, event.detailHash ?? null);
+    const cutoff = new Date(Date.parse(now) - FAILURE_LOG_RETENTION_DAYS * 86_400_000).toISOString();
+    db.prepare(`DELETE FROM failure_log WHERE ts < ?`).run(cutoff);
+}
+/** Rated failures per session since `sinceIso`, the input for repeat-error rate per arm (CD11, CD12). */
+export function failuresBySession(db, tenantId, sinceIso) {
+    // SAFETY: the SELECT names exactly these three TEXT columns.
+    const rows = db.prepare(`SELECT ts, session_id, sig_hash FROM failure_log
+     WHERE tenant_id = ? AND session_id IS NOT NULL AND sig_hash IS NOT NULL
+       AND outcome IN ('stored', 'duplicate', 'store-failed')
+     ORDER BY id`).all(tenantId);
+    const firstSession = new Map();
+    const bySession = new Map();
+    for (const row of rows) {
+        if (!firstSession.has(row.sig_hash))
+            firstSession.set(row.sig_hash, row.session_id);
+        // Rows before the window are not counted but still decide which session hit a signature first.
+        if (row.ts < sinceIso)
+            continue;
+        const repeat = firstSession.get(row.sig_hash) !== row.session_id;
+        const s = bySession.get(row.session_id) ?? { sessionId: row.session_id, failures: 0, repeats: 0 };
+        bySession.set(row.session_id, { ...s, failures: s.failures + 1, repeats: s.repeats + (repeat ? 1 : 0) });
+    }
+    return [...bySession.values()];
+}
+/** Sum the failure log for one tenant since `sinceIso`. */
+export function summarizeFailures(db, tenantId, sinceIso) {
+    // SAFETY: the SELECT names exactly these two columns, TEXT and an aggregate.
+    const rows = db.prepare(`SELECT outcome, COUNT(*) AS n FROM failure_log WHERE tenant_id = ? AND ts >= ? GROUP BY outcome`).all(tenantId, sinceIso);
+    const counts = new Map(rows.map((r) => [r.outcome, Number(r.n)]));
+    const outcomes = {
+        stored: counts.get('stored') ?? 0,
+        duplicate: counts.get('duplicate') ?? 0,
+        'store-failed': counts.get('store-failed') ?? 0,
+        'skipped-interrupt': counts.get('skipped-interrupt') ?? 0,
+        'skipped-routine': counts.get('skipped-routine') ?? 0,
+        'skipped-invalid': counts.get('skipped-invalid') ?? 0,
+    };
+    const sessions = failuresBySession(db, tenantId, sinceIso);
+    return {
+        since: sinceIso,
+        outcomes,
+        total: Object.values(outcomes).reduce((sum, n) => sum + n, 0),
+        rated: sessions.reduce((sum, s) => sum + s.failures, 0),
+        repeats: sessions.reduce((sum, s) => sum + s.repeats, 0),
+        sessions: sessions.length,
+    };
+}
+//# sourceMappingURL=failure-log.js.map