hippo-memory 1.55.0 → 1.57.0

package/dist/dashboard.js

@@ -9,7 +9,8 @@ import * as os from 'os';
 import * as path from 'path';
 import * as fs from 'fs';
 import { extractPathTags } from './path-context.js';
-import { loadAllEntries, listCards, listMemoryConflicts, readEntry, writeEntry } from './store.js';
+import { loadAllEntries, listMemoryConflicts, readEntry, writeEntry } from './store.js';
+import { listCards } from './store-cards.js';
 import { calculateStrength, confidenceFacets } from './memory.js';
 import { loadConfig } from './config.js';
 import { listPeers } from './shared.js';

package/dist/db.js

@@ -11,7 +11,7 @@ const require = createRequire(import.meta.url);
 // runtime (Node's built-in synchronous SQLite module); there are no bundled
 // types for it here, so this require + cast is the module's documented boundary.
 const { DatabaseSync } = require('node:sqlite');
-const CURRENT_SCHEMA_VERSION = 49;
+const CURRENT_SCHEMA_VERSION = 50;
 const MIGRATIONS = [
     {
         version: 1,
@@ -2501,6 +2501,72 @@ const MIGRATIONS = [
       `);
         },
     },
+    {
+        version: 50,
+        up: (db) => {
+            // Per-turn delivery events (src/recall-trace.ts). Additive only: no min_compatible_binary bump; rollback drops both tables
+            // and sets schema_version back to 49. No CHECK on enum columns since SQLite cannot alter one; delivery-recorder.ts unions are the allowlist.
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS delivery_events (
+          id                INTEGER PRIMARY KEY AUTOINCREMENT,
+          ts                TEXT NOT NULL,
+          ledger_version    INTEGER NOT NULL,
+          tenant_id         TEXT NOT NULL DEFAULT 'default',
+          runtime           TEXT NOT NULL,
+          event_type        TEXT NOT NULL,
+          surface           TEXT NOT NULL,
+          store_hash        TEXT NOT NULL,
+          write_store       TEXT NOT NULL,
+          project_hash      TEXT,
+          session_id        TEXT,
+          session_state     TEXT NOT NULL,
+          host_turn_id      TEXT,
+          turn_seq          INTEGER,
+          duplicate_of      INTEGER,
+          prompt_hash       TEXT,
+          prompt_length     INTEGER NOT NULL DEFAULT 0,
+          query_hash        TEXT,
+          recall_trace_id   INTEGER,
+          block_state       TEXT NOT NULL,
+          prompt_recall     INTEGER NOT NULL DEFAULT 0,
+          considered_count  INTEGER NOT NULL DEFAULT 0,
+          filtered_count    INTEGER NOT NULL DEFAULT 0,
+          selected_count    INTEGER NOT NULL DEFAULT 0,
+          emitted_count     INTEGER NOT NULL DEFAULT 0,
+          rejected_count    INTEGER NOT NULL DEFAULT 0,
+          rejected_unlisted INTEGER NOT NULL DEFAULT 0,
+          sections_shown    INTEGER NOT NULL DEFAULT 0,
+          sections_dropped  INTEGER NOT NULL DEFAULT 0,
+          budget_tokens     INTEGER NOT NULL DEFAULT 0,
+          selected_tokens   INTEGER NOT NULL DEFAULT 0,
+          injected_tokens   INTEGER NOT NULL DEFAULT 0,
+          static_hash       TEXT,
+          recall_hash       TEXT,
+          emitted_hash      TEXT,
+          elapsed_ms        INTEGER NOT NULL DEFAULT 0
+        );
+        CREATE INDEX IF NOT EXISTS idx_delivery_events_session ON delivery_events(tenant_id, session_id, id);
+        CREATE INDEX IF NOT EXISTS idx_delivery_events_ts ON delivery_events(ts);
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_delivery_events_turn
+          ON delivery_events(tenant_id, session_id, event_type, turn_seq) WHERE turn_seq IS NOT NULL;
+
+        CREATE TABLE IF NOT EXISTS delivery_candidates (
+          event_id     INTEGER NOT NULL REFERENCES delivery_events(id) ON DELETE CASCADE,
+          tenant_id    TEXT NOT NULL DEFAULT 'default',
+          memory_id    TEXT NOT NULL,          -- no FK: events outlive forgotten memories, as recall traces do
+          source_store TEXT NOT NULL,
+          pool         TEXT NOT NULL,
+          stage        TEXT NOT NULL,
+          outcome      TEXT NOT NULL,
+          reason       TEXT,
+          cand_rank    INTEGER,
+          score        REAL,
+          tokens       INTEGER,
+          PRIMARY KEY (event_id, memory_id)
+        ) WITHOUT ROWID;
+      `);
+        },
+    },
 ];
 function tableHasColumn(db, tableName, columnName) {
     if (!/^[a-z_]+$/i.test(tableName))

package/dist/decisions.js

@@ -24,7 +24,8 @@
  * step rolls all of them back. Pattern matches savePrediction (predictions.ts).
  */
 import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry, assertTenantId } from './store.js';
+import { writeEntry } from './store.js';
+import { assertTenantId } from './tenant.js';
 import { markGraphDirty, removeGraphEntitiesForObject } from './graph.js';
 import { createMemory, Layer } from './memory.js';
 import { appendAuditEvent } from './audit.js';

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/eval-stats.d.ts

@@ -120,4 +120,62 @@ export declare function passAtK(runsByTask: boolean[][], k: number): number;
  * NaN when no task has k runs.
  */
 export declare function passHatK(runsByTask: boolean[][], k: number): number;
+/** All units of one family (tasks by seeds), resampled as one block so seeds stay together. */
+export type Family<T> = readonly T[];
+/** One repository's families; a task with no lesson is a family of one. */
+export type Repository<T> = readonly Family<T>[];
+/** An {@link Estimate} with a two-sided p-value from the same resamples. */
+export interface TestedEstimate extends Estimate {
+    /** 2 x min(share <= null, share >= null), capped at 1; NaN with fewer than two repositories. */
+    readonly p: number;
+    /** Non-finite resamples, dropped; `iterations + dropped` is the number requested. */
+    readonly dropped: number;
+    /** The null the p-value tested against; {@link verdict} reads its sides from here. */
+    readonly nullValue: number;
+}
+/** Options for {@link twoLevelBootstrap}. */
+export interface TwoLevelOpts extends BootstrapOpts {
+    /** Resamples. Default 10,000. */
+    readonly iterations?: number;
+    /** Value the p-value tests against: 0 for differences, 1 for ratios. Default 0. */
+    readonly nullValue?: number;
+}
+/** Resamples repositories, then families inside each; only the repository draw carries a shared-store fault.
+ * The statistic never uses the PRNG, so a second call on one seed draws the same resamples. */
+export declare function twoLevelBootstrap<T>(repos: readonly Repository<T>[], statistic: (units: readonly T[]) => number, opts?: TwoLevelOpts): TestedEstimate;
+/** Holm step-down in input order; the family size is `ps.length`, as preregistered.
+ * A NaN stays NaN but ranks as 1, so it never loosens the others; a finite p outside [0, 1] throws. */
+export declare function holmAdjust(ps: readonly number[]): number[];
+/** One of the four mutually exclusive outcomes the preregistration allows per hypothesis. */
+export type Verdict = 'loss' | 'win' | 'tie' | 'inconclusive';
+/** What a hypothesis needs to be read; see {@link verdict}. */
+export interface VerdictSpec {
+    /** Direction that favours the treatment arm. */
+    readonly helpful: 'lower' | 'higher';
+    /** Inclusive band the interval must sit inside for a tie. */
+    readonly tieBand: readonly [number, number];
+    /** An estimate on this value or beyond it, on the helpful side, reaches the minimum effect. */
+    readonly minimumEffectAt: number;
+    /** Default 0.05. */
+    readonly alpha?: number;
+}
+/** A verdict, plus whether a win reaches the minimum effect (a win below it is a small win). */
+export interface VerdictResult {
+    readonly verdict: Verdict;
+    readonly reachesMinimum: boolean;
+}
+/** Checks in the preregistered order; the null comes from `e.nullValue`, so p and sides cannot disagree.
+ * A NaN estimate, p or bound is inconclusive, since a win or loss cannot be ruled out. */
+export declare function verdict(e: TestedEstimate, adjustedP: number, spec: VerdictSpec): VerdictResult;
+/** A win must hold under both codings of not-applicable, while a loss under either is reported. */
+export declare function combineCodings(a: VerdictResult, b: VerdictResult): VerdictResult;
+/** Outcome of the harm gate; see {@link harmGate}. */
+export interface HarmGate {
+    readonly pass: boolean;
+    readonly costOk: boolean;
+    readonly resolveOk: boolean;
+}
+/** Cost ratio's upper bound below 1.10, resolve difference's lower bound (a fraction) above -0.05.
+ * Both estimates must use alpha 0.05, the conservative reading of "upper 95% bound"; a NaN bound fails. */
+export declare function harmGate(costRatio: Estimate, resolveDiff: Estimate): HarmGate;
 //# sourceMappingURL=eval-stats.d.ts.map

package/dist/eval-stats.js

@@ -184,4 +184,115 @@ export function passHatK(runsByTask, k) {
         return Number.NaN;
     return eligible.filter((r) => r.slice(0, k).every(Boolean)).length / eligible.length;
 }
+function notANumber(nullValue, dropped) {
+    const nan = Number.NaN;
+    return { estimate: nan, low: nan, high: nan, p: nan, iterations: 0, dropped, nullValue };
+}
+function resampleUnits(repos, rand) {
+    const units = [];
+    for (let i = 0; i < repos.length; i++) {
+        const repo = repos[Math.floor(rand() * repos.length)];
+        for (let j = 0; j < repo.length; j++) {
+            for (const unit of repo[Math.floor(rand() * repo.length)])
+                units.push(unit);
+        }
+    }
+    return units;
+}
+// Inclusive on both sides, as the p-value is worded; float noise around the null breaks a tie.
+function twoSidedP(samples, nullValue) {
+    let below = 0;
+    let above = 0;
+    for (const s of samples) {
+        if (s <= nullValue)
+            below++;
+        if (s >= nullValue)
+            above++;
+    }
+    return Math.min(1, (2 * Math.min(below, above)) / samples.length);
+}
+/** Resamples repositories, then families inside each; only the repository draw carries a shared-store fault.
+ * The statistic never uses the PRNG, so a second call on one seed draws the same resamples. */
+export function twoLevelBootstrap(repos, statistic, opts = {}) {
+    const requested = opts.iterations ?? 10_000;
+    if (!Number.isInteger(requested) || requested <= 0) {
+        throw new RangeError(`iterations must be a positive integer, got ${requested}`);
+    }
+    const nullValue = opts.nullValue ?? 0;
+    const kept = repos.map((r) => r.filter((f) => f.length > 0)).filter((r) => r.length > 0);
+    if (kept.length === 0)
+        return notANumber(nullValue, 0);
+    const rand = seededRandom(opts.seed ?? 1);
+    const samples = [];
+    for (let b = 0; b < requested; b++) {
+        const value = statistic(resampleUnits(kept, rand));
+        if (Number.isFinite(value))
+            samples.push(value);
+    }
+    const dropped = requested - samples.length;
+    if (samples.length === 0)
+        return notANumber(nullValue, dropped);
+    const estimate = statistic(kept.flatMap((r) => r.flat()));
+    const p = kept.length < 2 ? Number.NaN : twoSidedP(samples, nullValue);
+    const interval = percentileInterval(samples, opts.alpha ?? 0.05);
+    return { estimate, ...interval, p, iterations: samples.length, dropped, nullValue };
+}
+/** Holm step-down in input order; the family size is `ps.length`, as preregistered.
+ * A NaN stays NaN but ranks as 1, so it never loosens the others; a finite p outside [0, 1] throws. */
+export function holmAdjust(ps) {
+    for (const p of ps) {
+        if (!Number.isNaN(p) && !(p >= 0 && p <= 1))
+            throw new RangeError(`p-value out of range: ${p}`);
+    }
+    const ranked = ps
+        .map((p, index) => ({ index, key: Number.isNaN(p) ? 1 : p }))
+        .sort((a, b) => a.key - b.key || a.index - b.index);
+    const adjusted = Array.from({ length: ps.length }, () => Number.NaN);
+    let running = 0;
+    ranked.forEach(({ index, key }, rank) => {
+        running = Math.max(running, (ps.length - rank) * key);
+        if (!Number.isNaN(ps[index]))
+            adjusted[index] = Math.min(1, running);
+    });
+    return adjusted;
+}
+/** Checks in the preregistered order; the null comes from `e.nullValue`, so p and sides cannot disagree.
+ * A NaN estimate, p or bound is inconclusive, since a win or loss cannot be ruled out. */
+export function verdict(e, adjustedP, spec) {
+    const inconclusive = { verdict: 'inconclusive', reachesMinimum: false };
+    if ([adjustedP, e.estimate, e.low, e.high].some(Number.isNaN))
+        return inconclusive;
+    const nullValue = e.nullValue;
+    const lowerIsHelpful = spec.helpful === 'lower';
+    if (adjustedP < (spec.alpha ?? 0.05)) {
+        const helpfulSide = lowerIsHelpful ? e.estimate < nullValue : e.estimate > nullValue;
+        const harmfulSide = lowerIsHelpful ? e.estimate > nullValue : e.estimate < nullValue;
+        if (harmfulSide)
+            return { verdict: 'loss', reachesMinimum: false };
+        if (helpfulSide) {
+            const reaches = lowerIsHelpful ? e.estimate <= spec.minimumEffectAt : e.estimate >= spec.minimumEffectAt;
+            return { verdict: 'win', reachesMinimum: reaches };
+        }
+    }
+    const insideBand = e.low >= spec.tieBand[0] && e.high <= spec.tieBand[1];
+    return insideBand ? { verdict: 'tie', reachesMinimum: false } : inconclusive;
+}
+/** A win must hold under both codings of not-applicable, while a loss under either is reported. */
+export function combineCodings(a, b) {
+    if (a.verdict === 'loss' || b.verdict === 'loss')
+        return { verdict: 'loss', reachesMinimum: false };
+    if (a.verdict === 'win' && b.verdict === 'win') {
+        return { verdict: 'win', reachesMinimum: a.reachesMinimum && b.reachesMinimum };
+    }
+    if (a.verdict === 'tie' && b.verdict === 'tie')
+        return { verdict: 'tie', reachesMinimum: false };
+    return { verdict: 'inconclusive', reachesMinimum: false };
+}
+/** Cost ratio's upper bound below 1.10, resolve difference's lower bound (a fraction) above -0.05.
+ * Both estimates must use alpha 0.05, the conservative reading of "upper 95% bound"; a NaN bound fails. */
+export function harmGate(costRatio, resolveDiff) {
+    const costOk = costRatio.high < 1.1;
+    const resolveOk = resolveDiff.low > -0.05;
+    return { pass: costOk && resolveOk, costOk, resolveOk };
+}
 //# sourceMappingURL=eval-stats.js.map