@tangle-network/agent-eval 0.94.0 → 0.95.0

package/dist/fuzz/explorer-cost.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explorer-cost.test.d.ts","sourceRoot":"","sources":["../../src/fuzz/explorer-cost.test.ts"],"names":[],"mappings":""}

package/dist/fuzz/explorer.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The exploration engine — a stateful session over a behavior space.
+ *
+ * Each `step()`: allocate budget across INPUT cells (floor first, then variance
+ * steering toward the least-certain cells), propose candidates (the proposer
+ * reads current elites + findings, so the search deepens generationally),
+ * evaluate with bounded concurrency, archive the most interesting scenario per
+ * input×measured bin, and admit notable candidates that pass the validity gates.
+ * `run()` loops to budget. `coverage()`/`findings()`/`capsule()` read live state —
+ * the surface `makeExploreTools` exposes so an agent can drive the session.
+ *
+ * One evaluation log (`EvalRecord[]`) is the source of truth; allocation
+ * observations and coverage are projections of it.
+ */
+import type { CapsuleData, CoverageCell, ExploreOptions, Finding } from './types';
+export declare class BehaviorExplorer<S> {
+    private readonly opts;
+    private readonly cells;
+    private readonly cellById;
+    private readonly objective;
+    private readonly threshold;
+    private readonly floorPerCell;
+    private readonly perRoundBudget;
+    /** The single evaluation log — coverage + allocation are projections of it. */
+    private readonly log;
+    /** binId (input × measured coords) → the most interesting entry seen. */
+    private readonly archiveByBin;
+    private readonly _findings;
+    private runsUsed;
+    private candidateFindings;
+    private evalErrors;
+    private consecutiveEvalErrors;
+    private stoppedEarly;
+    private rngState;
+    /** Accumulated KNOWN dollars — unknown-cost runs never inflate it. */
+    private spentKnownUsd;
+    private costUnknownRuns;
+    constructor(opts: ExploreOptions<S>);
+    private rng;
+    private binId;
+    private allocate;
+    private objectiveContext;
+    /** Mirrors control-runtime: stop once accumulated KNOWN cost ≥ the ceiling. */
+    private costExhausted;
+    /** Fold one run's cost in: null counts as unknown (never $0); a known cost
+     *  accrues toward the budget, lands in the ledger, and fires `onCost`. */
+    /** Returns the run's known cost, `null` when tracked-but-unknown, `undefined`
+     *  when cost tracking is not wired — the log row mirrors this exactly. */
+    private recordRunCost;
+    /** Elites whose INPUT cell matches — what the proposer mutates/deepens from. */
+    private elitesFor;
+    /** One allocate → propose → evaluate → gate → archive round. */
+    step(): Promise<{
+        runs: number;
+        findings: Finding<S>[];
+    }>;
+    /** Loop `step()` until the run or dollar budget is spent, the signal aborts,
+     *  or no progress is made. */
+    run(): Promise<CapsuleData<S>>;
+    coverage(): CoverageCell[];
+    findings(): Finding<S>[];
+    capsule(): CapsuleData<S>;
+}
+//# sourceMappingURL=explorer.d.ts.map

package/dist/fuzz/explorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explorer.d.ts","sourceRoot":"","sources":["../../src/fuzz/explorer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAQH,OAAO,KAAK,EAEV,WAAW,EAEX,YAAY,EAEZ,cAAc,EACd,OAAO,EAER,MAAM,SAAS,CAAA;AAuBhB,qBAAa,gBAAgB,CAAC,CAAC;IAuBjB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAtBjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IAEvC,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiD;IACrE,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqC;IAClE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;IAC7C,OAAO,CAAC,QAAQ,CAAI;IACpB,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,UAAU,CAAI;IACtB,OAAO,CAAC,qBAAqB,CAAI;IACjC,OAAO,CAAC,YAAY,CAAuD;IAC3E,OAAO,CAAC,QAAQ,CAAQ;IACxB,sEAAsE;IACtE,OAAO,CAAC,aAAa,CAAI;IACzB,OAAO,CAAC,eAAe,CAAI;gBAEE,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC;IAiCpD,OAAO,CAAC,GAAG,CAMV;IAED,OAAO,CAAC,KAAK;IASb,OAAO,CAAC,QAAQ;IAiBhB,OAAO,CAAC,gBAAgB;IAQxB,+EAA+E;IAC/E,OAAO,CAAC,aAAa;IAIrB;8EAC0E;IAC1E;8EAC0E;IAC1E,OAAO,CAAC,aAAa;IAyBrB,gFAAgF;IAChF,OAAO,CAAC,SAAS;IAMjB,gEAAgE;IAC1D,IAAI,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,CAAA;KAAE,CAAC;IAwI/D;kCAC8B;IACxB,GAAG,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAapC,QAAQ,IAAI,YAAY,EAAE;IAI1B,QAAQ,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE;IAIxB,OAAO,IAAI,WAAW,CAAC,CAAC,CAAC;CAkB1B"}

package/dist/fuzz/fuzz-agent.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `fuzzAgent` — the adversarial batch preset over `BehaviorExplorer`.
+ *
+ * One call: explore the space to budget with the adversarial objective and
+ * return the capsule. For agent-driven, incremental, or multi-objective use,
+ * construct a `BehaviorExplorer` and drive it via `makeExploreTools`.
+ */
+import type { CapsuleData, ExploreOptions } from './types';
+export type FuzzAgentOptions<S> = Omit<ExploreOptions<S>, 'objective'> & {
+    /** Score strictly below this is a candidate failure. Default 0.5. */
+    failureThreshold?: number;
+};
+export declare function fuzzAgent<S>(opts: FuzzAgentOptions<S>): Promise<{
+    capsule: CapsuleData<S>;
+}>;
+//# sourceMappingURL=fuzz-agent.d.ts.map

package/dist/fuzz/fuzz-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fuzz-agent.d.ts","sourceRoot":"","sources":["../../src/fuzz/fuzz-agent.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAE1D,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,GAAG;IACvE,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B,CAAA;AAED,wBAAsB,SAAS,CAAC,CAAC,EAC/B,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC;IAAE,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC,CAOtC"}

package/dist/fuzz/fuzz-agent.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fuzz-agent.test.d.ts.map

package/dist/fuzz/fuzz-agent.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fuzz-agent.test.d.ts","sourceRoot":"","sources":["../../src/fuzz/fuzz-agent.test.ts"],"names":[],"mappings":""}

package/dist/fuzz/gates.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Validity gates — what separates a fuzzer from a slop generator.
+ *
+ * A notable candidate is admitted only when it is fair and reproducible. None of
+ * these are on by default: the live wiring opts in, so reported findings carry
+ * their proof.
+ */
+import type { Evaluator, ValidityGates } from './types';
+/** Combine gate sets; a candidate must pass every gate in every set. */
+export declare function composeGates<S>(...sets: Array<ValidityGates<S> | undefined>): ValidityGates<S>;
+/**
+ * Reproducibility gate. Re-run the target on a meaning-preserving rephrase of the
+ * flagged scenario; keep the finding only when the rephrase ALSO scores below the
+ * threshold. A finding that flips under a cosmetic rewrite was keyed to surface
+ * form, not the task — a false signal we must not report. Costs one extra
+ * evaluation per candidate (candidates are rare, so cheap).
+ */
+export declare function perturbationStabilityGate<S>(opts: {
+    evaluate: Evaluator<S>;
+    /** Produce a semantic-preserving rephrase. Return null to skip (treated as pass). */
+    perturb: (scenario: S) => S | null;
+    /** Score strictly below this still counts as failing. Default 0.5. */
+    failureThreshold?: number;
+}): ValidityGates<S>;
+/**
+ * Severity-floor gate. Reject borderline candidates whose score sits in a band
+ * just under the threshold — judge noise, not a real defect.
+ */
+export declare function severityFloorGate<S>(opts: {
+    failureThreshold?: number;
+    margin?: number;
+}): ValidityGates<S>;
+//# sourceMappingURL=gates.d.ts.map

package/dist/fuzz/gates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../../src/fuzz/gates.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAoB,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAEzE,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAgB9F;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,IAAI,EAAE;IACjD,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACtB,qFAAqF;IACrF,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAA;IAClC,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B,GAAG,aAAa,CAAC,CAAC,CAAC,CAUnB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,GAAG,aAAa,CAAC,CAAC,CAAC,CAMnB"}

package/dist/fuzz/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@tangle-network/agent-eval/fuzz` — behavior-space exploration.
+ *
+ * Search a target's behavior space for verified findings: tile the input plan,
+ * steer budget toward the least-certain cells, mutate (or skill-generate)
+ * scenarios, bin a quality-diversity archive by measured behavior, and admit
+ * only findings that pass the validity gates. Every run emits a `CapsuleData`
+ * artifact — coverage heat-map + minimized verified findings.
+ *
+ * Entry points: `fuzzAgent` (adversarial batch preset), `BehaviorExplorer` +
+ * `makeExploreTools` (the agent-driven session). Evaluations ARE
+ * `DefaultVerdict`s — the same spine as judges and verifiers.
+ */
+export type { BuildCapsuleInput, RenderCapsuleOptions } from './capsule';
+export { buildCapsule, renderCapsuleHtml } from './capsule';
+export type { EvalRecord } from './cube';
+export { buildCoverage, cellId, enumerateCells } from './cube';
+export { BehaviorExplorer } from './explorer';
+export type { FuzzAgentOptions } from './fuzz-agent';
+export { fuzzAgent } from './fuzz-agent';
+export { composeGates, perturbationStabilityGate, severityFloorGate } from './gates';
+export { adversarialObjective, mutationProposer, noveltyObjective } from './policies';
+export type { ExploreToolDef } from './tools';
+export { makeExploreTools } from './tools';
+export type { ArchiveEntry, BehaviorSpace, CapsuleData, Cell, CoverageCell, Evaluation, Evaluator, ExploreEvent, ExploreOptions, Finding, Objective, ObjectiveContext, ProposeContext, Proposer, RunCost, SpaceAxis, ValidityGates, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/fuzz/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fuzz/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AACxE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAC3D,YAAY,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAC7C,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AACpF,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AACrF,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAC1C,YAAY,EACV,YAAY,EACZ,aAAa,EACb,WAAW,EACX,IAAI,EACJ,YAAY,EACZ,UAAU,EACV,SAAS,EACT,YAAY,EACZ,cAAc,EACd,OAAO,EACP,SAAS,EACT,gBAAgB,EAChB,cAAc,EACd,QAAQ,EACR,OAAO,EACP,SAAS,EACT,aAAa,GACd,MAAM,SAAS,CAAA"}

package/dist/fuzz/policies.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shipped policies for the exploration engine.
+ *
+ * `Proposer` is a plain function type — an agent running a generator skill IS a
+ * proposer (`(ctx) => dispatchToSkill(ctx)`), no wrapper needed. `mutationProposer`
+ * builds the deterministic, LLM-free one from mutation operators. Objectives are
+ * interfaces because the engine reads `kind` + `threshold` off them.
+ */
+import type { AdversarialMutation } from '../rl/adversarial';
+import type { Cell, Objective, Proposer } from './types';
+/**
+ * Perturbation-based search: apply the cell's mutation operators to the current
+ * elites + seeds, deduping by id. Elites first — mutating the most interesting
+ * scenario found so far is what makes the search deepen across rounds.
+ */
+export declare function mutationProposer<S>(opts: {
+    mutationsFor: (cell: Cell) => AdversarialMutation<S>[];
+    scenarioId: (s: S) => string;
+}): Proposer<S>;
+/** Adversarial: a low headline score is interesting — find where the agent fails. */
+export declare function adversarialObjective(threshold?: number): Objective;
+/**
+ * Novelty: interesting when far from the archive in score AND measured behavior
+ * descriptor — quality-diversity's diversity pressure; drives corpus growth
+ * rather than re-finding the same hole.
+ */
+export declare function noveltyObjective(threshold?: number): Objective;
+//# sourceMappingURL=policies.d.ts.map

package/dist/fuzz/policies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policies.d.ts","sourceRoot":"","sources":["../../src/fuzz/policies.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAC5D,OAAO,KAAK,EACV,IAAI,EAEJ,SAAS,EAGT,QAAQ,EACT,MAAM,SAAS,CAAA;AAMhB;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE;IACxC,YAAY,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAA;IACtD,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAA;CAC7B,GAAG,QAAQ,CAAC,CAAC,CAAC,CAsBd;AAID,qFAAqF;AACrF,wBAAgB,oBAAoB,CAAC,SAAS,SAAM,GAAG,SAAS,CAE/D;AAcD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,SAAM,GAAG,SAAS,CAgB3D"}

package/dist/fuzz/tools.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Agent-drivable surface over a live exploration session.
+ *
+ * Framework-neutral tool defs ({name, description, parameters: JSON Schema,
+ * handler}) so the on-demand agent — not a batch script — drives the search:
+ * step it, read coverage, inspect findings, render the capsule. Transport
+ * encodings (OpenAI function shape, MCP) are one-line mappings the host owns.
+ */
+import type { BehaviorExplorer } from './explorer';
+export interface ExploreToolDef {
+    name: string;
+    description: string;
+    /** JSON Schema (draft-07+) for the arguments. */
+    parameters: Record<string, unknown>;
+    handler: (args: unknown, ctx?: {
+        signal?: AbortSignal;
+    }) => Promise<unknown>;
+}
+export declare function makeExploreTools<S>(explorer: BehaviorExplorer<S>): ExploreToolDef[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/fuzz/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/fuzz/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACnC,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC7E;AAID,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,cAAc,EAAE,CAqDnF"}

package/dist/fuzz/types.d.ts

@@ -0,0 +1,307 @@
+/**
+ * Behavior-space exploration — types.
+ *
+ * One engine searches a space of inputs against a target, scores each run with a
+ * multi-objective verdict, keeps a quality-diversity archive, and admits only
+ * findings that pass the validity gates. Adversarial fuzzing is the headline
+ * preset (`fuzzAgent`); swapping the `Objective` re-points the same engine at
+ * novelty search, curriculum growth, or user-simulation.
+ *
+ * Two kinds of coordinates, deliberately distinct:
+ *  - INPUT axes (`space.axes`) are the stratification plan — enumerable up front,
+ *    so allocation and the coverage denominator (planned vs covered) are honest.
+ *  - MEASURED descriptors (`descriptor(scenario, ev)`) are read off the rollout —
+ *    they bin the archive by what the agent DID, and never inflate the coverage
+ *    denominator (a behavior you haven't seen yet is not a planned cell).
+ *
+ * An `Evaluation` IS a `DefaultVerdict` — same spine as judges and verifiers,
+ * never a parallel score shape.
+ */
+import type { CostChannel, CostLedger } from '../cost-ledger';
+import type { AdversarialMutation } from '../rl/adversarial';
+import type { DefaultVerdict } from '../verdict';
+/** One input axis of the stratification plan (e.g. matterType, difficulty, personaRigor). */
+export interface SpaceAxis {
+    name: string;
+    values: string[];
+}
+/** The input space to stratify. Cells are the cartesian product of the axes. */
+export interface BehaviorSpace {
+    axes: SpaceAxis[];
+}
+/** One input cell: a coordinate in the stratification plan. */
+export interface Cell {
+    /** Stable id, e.g. `matterType=nda|difficulty=hard`. */
+    id: string;
+    coords: Record<string, string>;
+}
+/**
+ * The outcome of running the target against one scenario: a `DefaultVerdict`
+ * (`valid`, headline `score` in [0,1], per-dimension `scores`, `notes`) plus the
+ * fields exploration needs. Keep `scores` populated — the coverage map surfaces
+ * WHICH dimension is weak only when evaluations carry it.
+ */
+export interface Evaluation extends DefaultVerdict {
+    /** Measured behavior coordinates (e.g. `{ outcome: 'refused' }`). Bins the archive. */
+    descriptor?: Record<string, string>;
+    /** Surfaced output — drives exemplars + minimization. */
+    output?: string;
+    /** RunRecord id when the target persisted a trace. */
+    runId?: string;
+    /** Structured labels, e.g. failure classes (`hallucination`, `refusal`). */
+    labels?: string[];
+    /** Wall-clock for the evaluation, when the consumer measures it more precisely
+     *  than the engine can (e.g. excluding judge time). Engine-measured otherwise. */
+    latencyMs?: number;
+}
+/** Run the target against one scenario in a cell. */
+export type Evaluator<S> = (scenario: S, cell: Cell) => Promise<Evaluation>;
+/** Context a proposer sees — prior elites + findings let a skill-backed proposer steer. */
+export interface ProposeContext<S> {
+    cell: Cell;
+    seeds: S[];
+    /** Current archive elites whose input cell matches. */
+    elites: S[];
+    /** Verified findings so far (read-only) — probe new gaps, not re-found ones. */
+    findings: ReadonlyArray<Finding<S>>;
+    /** How many candidates to propose. */
+    count: number;
+    rng: () => number;
+}
+/**
+ * Produces candidate scenarios for a cell. A plain function — `mutationProposer`
+ * builds one from mutation operators; an agent running a generator skill IS one
+ * (`(ctx) => dispatchToSkill(ctx)`), no wrapper needed.
+ */
+export type Proposer<S> = (ctx: ProposeContext<S>) => Promise<S[]> | S[];
+/**
+ * What "interesting" means. `interest` in [0,1]; a candidate is notable (gate-
+ * checked, reported) when `interest >= threshold`. `adversarialObjective` (low
+ * score is interesting) and `noveltyObjective` (far from the archive) ship.
+ */
+export interface Objective {
+    kind: string;
+    interest(ev: Evaluation, ctx: ObjectiveContext): number;
+    /** Default 0.5. */
+    threshold?: number;
+}
+export interface ObjectiveContext {
+    archiveScores: number[];
+    archiveDescriptors: Array<Record<string, string> | undefined>;
+}
+/**
+ * Validity gates — the moat. A notable candidate is admitted ONLY when it is a
+ * fair, answerable task (`isValid`) AND reproduces under a meaning-preserving
+ * rephrase (`isUncontaminated`). Pass-through by default (testable without an
+ * LLM); live wiring supplies real gates.
+ */
+export interface ValidityGates<S> {
+    isValid?: (scenario: S, ev: Evaluation, cell: Cell) => boolean | Promise<boolean>;
+    isUncontaminated?: (scenario: S, ev: Evaluation, cell: Cell) => boolean | Promise<boolean>;
+}
+/** A gate-verified, minimized finding — the unit the capsule reports. */
+export interface Finding<S> {
+    id: string;
+    cell: Cell;
+    scenario: S;
+    /** The minimized trigger (== `scenario` when no minimizer is supplied). */
+    minimized: S;
+    /** Legible text of the minimized trigger, when `scenarioText` is supplied. */
+    text?: string;
+    /** The full multi-objective verdict. */
+    evaluation: Evaluation;
+    /** The objective's interest score that flagged it. */
+    interest: number;
+    /** Which objective flagged it. */
+    objective: string;
+}
+/** An archive elite — the most interesting scenario seen for one bin. */
+export interface ArchiveEntry<S> {
+    /** Input cell + measured descriptor coords combined, e.g. `difficulty=hard|outcome=refused`. */
+    binId: string;
+    cell: Cell;
+    scenario: S;
+    evaluation: Evaluation;
+    interest: number;
+}
+/** Summary of a sample — every aggregate carries its spread, never a bare mean. */
+export interface Distribution {
+    mean: number;
+    median: number;
+    p90: number;
+    min: number;
+    max: number;
+    n: number;
+}
+/** Per-INPUT-cell coverage — the planned-vs-covered map. */
+export interface CoverageCell {
+    cell: Cell;
+    runs: number;
+    /** Headline score distribution in [0,1]; `null` when the cell was never run
+     *  (honestly uncovered — never a fabricated zero). */
+    score: Distribution | null;
+    /** Fraction of runs the objective flagged as notable. */
+    findingRate: number;
+    /** Per-dimension score distributions — surfaces WHICH dimension is weak and
+     *  how consistently. */
+    dimensions: Record<string, Distribution>;
+    /** Evaluation wall-clock per run; engine-measured unless the evaluation
+     *  carried its own `latencyMs`. `null` when the cell was never run. */
+    latencyMs: Distribution | null;
+    /** Known dollars spent in this cell — present only when cost tracking was
+     *  wired; runs with unknown cost are counted apart, never folded in as $0. */
+    costUsd?: number;
+    costUnknownRuns?: number;
+}
+/** The artifact every exploration produces. */
+export interface CapsuleData<S> {
+    target: string;
+    objective: string;
+    /** Stamped by the caller — the engine stays clock-free and deterministic. */
+    generatedAt?: string;
+    coverage: CoverageCell[];
+    /** Verified findings, sorted by descending interest. */
+    findings: Finding<S>[];
+    /** QD archive elites (binned by input × measured coords). */
+    archive: ArchiveEntry<S>[];
+    /** Post-harden lift, filled by a second pass after an improvement. */
+    lift?: {
+        before: number;
+        after: number;
+        verdict: string;
+    };
+    stats: {
+        totalRuns: number;
+        /** Input-cell denominator — the stratification plan. */
+        cellsTotal: number;
+        cellsCovered: number;
+        /** Distinct measured-descriptor bins observed (never part of the denominator). */
+        behaviorBinsObserved: number;
+        candidateFindings: number;
+        verifiedFindings: number;
+        /** Distribution of per-cell mean scores across covered cells (cells weigh
+         *  equally — variance steering sends more runs to weak cells, so a
+         *  run-weighted average would bias low). `null` when nothing ran. */
+        robustness: Distribution | null;
+        /** Evaluation wall-clock across all runs. `null` when nothing ran. */
+        latencyMs: Distribution | null;
+        /** Known dollars spent on this exploration's runs. Present only when cost
+         *  tracking was wired (`costOf`) — absent means "not tracked", never $0. */
+        costUsd?: number;
+        /** Runs whose cost was unknown (`costOf` returned null) — counted apart,
+         *  never folded into `costUsd` as a fabricated $0. */
+        costUnknownRuns?: number;
+        /** Evaluations that threw (transport/backend failures). They consumed no
+         *  run budget and scored nothing — an infra axis, never folded into
+         *  robustness or reported as findings. */
+        evalErrors: number;
+        /** Present when the run stopped before its budget because consecutive
+         *  eval errors tripped the circuit breaker (a dead backend must not burn
+         *  the remaining budget). The capsule-so-far is complete and honest. */
+        stoppedEarly?: {
+            reason: 'eval-errors';
+            detail: string;
+        };
+    };
+}
+/**
+ * Known cost of one evaluated run. `model` attributes the spend in the ledger's
+ * per-model rollup; absent, the entry is labeled `unattributed` (the dollars are
+ * real either way — recorded as `actualCostUsd`, never an estimate).
+ */
+export interface RunCost {
+    usd: number;
+    model?: string;
+}
+export type ExploreEvent<S> = {
+    type: 'cell-allocated';
+    cell: Cell;
+    count: number;
+} | {
+    type: 'evaluated';
+    cell: Cell;
+    scenario: S;
+    evaluation: Evaluation;
+} | {
+    type: 'finding';
+    finding: Finding<S>;
+} | {
+    type: 'eval-error';
+    cell: Cell;
+    scenarioId: string;
+    message: string;
+} | {
+    type: 'round';
+    runsUsed: number;
+    budget: number;
+};
+export interface ExploreOptions<S> {
+    /** Name of the target under exploration — labels the capsule. */
+    target: string;
+    /** The input stratification plan. */
+    space: BehaviorSpace;
+    /** Candidate generator. */
+    proposer: Proposer<S>;
+    /** Runs the target → multi-objective `Evaluation`. */
+    evaluate: Evaluator<S>;
+    /** Seed corpus per cell. */
+    seedsFor: (cell: Cell) => S[] | Promise<S[]>;
+    /** Stable id for a scenario (dedup + lineage). */
+    scenarioId: (scenario: S) => string;
+    /** Human-legible text — drives capsule exemplars. */
+    scenarioText?: (scenario: S) => string;
+    /** Measured behavior coords appended to the archive bin. Default: input cell only. */
+    descriptor?: (scenario: S, ev: Evaluation) => Record<string, string>;
+    /** What "interesting" means. Default: `adversarialObjective(0.5)`. */
+    objective?: Objective;
+    /** Validity gates. Default pass-through. */
+    gates?: ValidityGates<S>;
+    /** Budget steering across input cells. `variance` chases uncertainty; `uniform` is the unsteered ablation baseline. Default `variance`. */
+    allocation?: 'variance' | 'uniform';
+    /** Total target evaluations. */
+    budget: number;
+    /** Minimum evaluations per input cell before steering. Default 2. */
+    floorPerCell?: number;
+    /** Shrink a notable scenario to its minimal trigger. Default: identity. */
+    minimize?: (scenario: S, evaluate: Evaluator<S>, cell: Cell) => Promise<S> | S;
+    /** Max concurrent `evaluate` calls. Default 1. */
+    concurrency?: number;
+    /** Stop the run after this many CONSECUTIVE eval errors (a dead backend must
+     *  not burn the remaining budget). Successes reset the streak. Default 5. */
+    maxConsecutiveEvalErrors?: number;
+    /** Cooperative cancellation. */
+    signal?: AbortSignal;
+    /** Progress stream. */
+    onProgress?: (event: ExploreEvent<S>) => void;
+    /** Deterministic seed. Default 1. */
+    seed?: number;
+    /**
+     * Cost of one evaluated run — consumer-supplied; the explorer cannot know
+     * token usage. Return null when the cost is unknown: the run is COUNTED in
+     * `stats.costUnknownRuns`, never folded into the total as $0. Required by
+     * every other cost option (`costBudgetUsd` / `ledger` / `onCost`).
+     */
+    costOf?: (scenario: S, cell: Cell, ev: Evaluation) => RunCost | null;
+    /**
+     * Hard dollar ceiling on accumulated KNOWN cost (same semantics as the
+     * control-runtime `budget.maxCostUsd`: nonnegative finite, the session stops
+     * once spent ≥ ceiling; no new evaluation starts after that). Unknown-cost
+     * runs do not consume budget — they are reported separately, so the ceiling
+     * is honest about what it can see.
+     */
+    costBudgetUsd?: number;
+    /**
+     * Sink for per-run cost entries — each known `costOf` result is recorded
+     * with channel 'agent' and `actualCostUsd` (token axes are zero: the
+     * explorer only sees dollars). Pass the program's shared `CostLedger` so
+     * `costReport` stamps fuzz spend alongside judge/analyst spend.
+     */
+    ledger?: CostLedger;
+    /** Observer fired for every known-cost run recorded. */
+    onCost?: (entry: {
+        usd: number;
+        channel: CostChannel;
+    }) => void;
+}
+export type { AdversarialMutation, DefaultVerdict };
+//# sourceMappingURL=types.d.ts.map

package/dist/fuzz/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/fuzz/types.ts"],"names":[],"mappings":"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"}