@tangle-network/agent-eval 0.94.0 → 0.95.0

package/dist/campaign/proposers/halo.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `haloProposer` — wraps the REAL halo-engine (Inference.net's hierarchical
+ * agentic trace analyzer, `pip install halo-engine`, repo context-labs/halo)
+ * as an agent-eval `SurfaceProposer`, so HALO competes head-to-head with
+ * `gepaProposer` — and with our own `traceAnalystProposer` — inside `compareProposers`
+ * on identical traces / scenarios / held-out scoring.
+ *
+ * It PRESERVES halo's actual working usage — `analyze` shells out to the
+ * published CLI (`halo <traces.jsonl> -p <prompt> -m <model>`) and uses its real
+ * RLM findings verbatim. We do NOT reimplement its analysis; that would make the
+ * benchmark meaningless. The materialize/apply pipeline is the shared
+ * `analysisEditProposer` — identical to `traceAnalystProposer`, which is what makes
+ * the comparison apples-to-apples.
+ *
+ * Fail-loud: no traces → throw; halo errors → throw; empty findings → throw.
+ */
+import type { LlmClientOptions } from '../../llm-client';
+import type { ProposeContext, SurfaceProposer } from '../types';
+export interface HaloProposerOptions {
+    /** OpenAI-compatible base URL for BOTH halo's RLM analysis and the apply
+     *  step (e.g. the Tangle router `https://router.tangle.tools/v1`). */
+    baseUrl: string;
+    /** Bearer key (else relies on OPENAI_API_KEY in the env halo inherits). */
+    apiKey?: string;
+    /** Model for halo's `--model` (its RLM). Default 'gpt-5.4-mini' (halo's own default). */
+    model?: string;
+    /** Model used to APPLY halo's findings to the prompt surface. Default = `model`. */
+    applyModel?: string;
+    /** The real halo binary. Default 'halo' (from `pip install halo-engine`). */
+    haloBin?: string;
+    /** Resolve the OTLP traces (JSONL string) halo should analyze for THIS
+     *  generation. Returning empty throws (halo has nothing to analyze). */
+    resolveTraces: (ctx: ProposeContext) => string | Promise<string>;
+    /** halo's analysis prompt (`-p`). Default targets the failure taxonomy. */
+    analysisPrompt?: string;
+    /** halo `--max-depth` / `--max-turns` passthrough. */
+    maxDepth?: number;
+    maxTurns?: number;
+    /** Test seam: inject a fetch for the apply-step callLlm (no network in unit tests). */
+    fetchImpl?: LlmClientOptions['fetch'];
+}
+/** Wrap the real halo-engine CLI as a SurfaceProposer (prompt-tier). */
+export declare function haloProposer(opts: HaloProposerOptions): SurfaceProposer;
+//# sourceMappingURL=halo.d.ts.map

package/dist/campaign/proposers/halo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"halo.d.ts","sourceRoot":"","sources":["../../../src/campaign/proposers/halo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAK/D,MAAM,WAAW,mBAAmB;IAClC;0EACsE;IACtE,OAAO,EAAE,MAAM,CAAA;IACf,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;4EACwE;IACxE,aAAa,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAChE,2EAA2E;IAC3E,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uFAAuF;IACvF,SAAS,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;CACtC;AAKD,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,eAAe,CAgDvE"}

package/dist/campaign/proposers/halo.test.d.ts

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

package/dist/campaign/proposers/halo.test.d.ts.map

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

package/dist/campaign/proposers/memory.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `memoryCurationProposer` — a CURATOR `SurfaceProposer`, the complement to the
+ * OPTIMIZER proposers (`gepaProposer` rewrites the prompt; this one BUILDS a
+ * searchable memory of what prior trajectories taught and grafts the most
+ * relevant lessons onto the surface).
+ *
+ * Each generation it:
+ *  1. collects lessons — this generation's trace-analyst `findings` PLUS the
+ *     memory already carried in the parent surface (so memory accumulates
+ *     across generations instead of resetting);
+ *  2. curates them — normalizes, deduplicates near-identical lessons, and ranks
+ *     by recurrence (a lesson seen across many findings outranks a one-off);
+ *  3. retrieves the top-K and writes them back as a single delimited memory
+ *     block in the surface (idempotent — the block is replaced, never stacked,
+ *     so the prompt does not grow without bound).
+ *
+ * This is the substrate behind the "knowledge base of working trajectories" the
+ * agent searches: the curated block IS the retrieved memory the next run reads.
+ * Curation is DETERMINISTIC (no LLM) so a lift it produces is attributable to
+ * the lessons, not to model noise in a rewrite. An optional `distill` LLM step
+ * can compress raw findings into crisp imperatives; default is verbatim.
+ *
+ * Fail-loud: never fabricates a lesson. With no findings and no prior memory it
+ * returns no candidate (nothing learned yet — gen 0). It does not throw on an
+ * empty generation because early generations legitimately have no findings.
+ */
+import { type LlmClientOptions } from '../../llm-client';
+import type { SurfaceProposer } from '../types';
+export interface MemoryCurationProposerOptions {
+    /** Top-K lessons retained in the surface memory block. Default 12. */
+    maxEntries?: number;
+    /** Heading rendered above the lessons inside the block. Default below. */
+    sectionHeading?: string;
+    /**
+     * Optional LLM distillation: compress raw findings into crisp, generalizable
+     * one-line imperatives before curating. Omit for verbatim (deterministic).
+     */
+    distill?: {
+        baseUrl: string;
+        apiKey?: string;
+        model: string;
+        fetchImpl?: LlmClientOptions['fetch'];
+    };
+}
+/** Build the CURATOR proposer. */
+export declare function memoryCurationProposer(opts?: MemoryCurationProposerOptions): SurfaceProposer;
+//# sourceMappingURL=memory.d.ts.map

package/dist/campaign/proposers/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/campaign/proposers/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAW,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACjE,OAAO,KAAK,EAAqC,eAAe,EAAE,MAAM,UAAU,CAAA;AAYlF,MAAM,WAAW,6BAA6B;IAC5C,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE;QACR,OAAO,EAAE,MAAM,CAAA;QACf,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,KAAK,EAAE,MAAM,CAAA;QACb,SAAS,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;KACtC,CAAA;CACF;AA+CD,kCAAkC;AAClC,wBAAgB,sBAAsB,CAAC,IAAI,GAAE,6BAAkC,GAAG,eAAe,CAyDhG"}

package/dist/campaign/proposers/memory.test.d.ts

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

package/dist/campaign/proposers/memory.test.d.ts.map

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

package/dist/campaign/proposers/skill-opt.d.ts

@@ -0,0 +1,88 @@
+/**
+ * `skillOptProposer` — a patch-mode `SurfaceProposer` implementing SkillOpt
+ * (Microsoft, arXiv:2605.23904). Where `gepaProposer` regenerates the whole
+ * surface by reflection, SkillOpt proposes BOUNDED, anchored edits
+ * (add/delete/replace) to ONE skill document, so a good rule introduced
+ * earlier is not clobbered by a later sweeping rewrite. The edit budget is the
+ * paper's "textual learning rate"; a rejected-edit buffer + a slow-update
+ * meta-note steer the optimizer away from dead ends.
+ *
+ * This module is the PROPOSER — the LLM call that turns evidence into
+ * structured patches. The accept-only-if-held-out-improves loop, the budget
+ * annealing, and the rejected buffer live in the `runSkillOpt` preset, which
+ * owns the epoch hill-climb. The proposer also conforms to `SurfaceProposer`
+ * (`propose` applies its patches to the current surface and returns the
+ * candidate surfaces) so it is a drop-in for `runOptimization` and a fair
+ * entrant in `compareProposers`.
+ */
+import { type LlmClientOptions } from '../../llm-client';
+import { type SkillPatch } from '../skill-patch';
+import type { SurfaceProposer } from '../types';
+/** Evidence the optimizer reflects on: where the current surface is weakest.
+ *  Computed by the caller (the preset uses a TRAIN campaign so proposals never
+ *  see the held-out split; the generic loop derives it from history). */
+export interface SkillOptEvidence {
+    /** Lowest-scoring scenarios (drives WHICH behavior to patch). */
+    weakScenarios: Array<{
+        scenarioId: string;
+        composite: number;
+    }>;
+    /** Lowest-scoring judge dimensions (drives WHAT to patch for). */
+    weakDimensions: Array<{
+        dimension: string;
+        score: number;
+    }>;
+}
+/** A patch that was tried and not accepted — fed back to the model so it does
+ *  not re-propose a dead end (SkillOpt's rejected-edit buffer). */
+export interface RejectedEdit {
+    label: string;
+    rationale: string;
+    reason: string;
+}
+export interface ProposePatchesArgs {
+    surface: string;
+    evidence: SkillOptEvidence;
+    /** Max ops per patch this round (the annealed textual learning rate). */
+    editBudget: number;
+    rejectedBuffer: RejectedEdit[];
+    /** Slow-update meta guidance accumulated across epochs. */
+    metaNote?: string;
+    /** Analyst findings + research report rendered as a prompt block so a patch
+     *  targets a NAMED diagnosed root cause. Built by
+     *  the proposer from `ctx.findings`/`ctx.report`; the patch-native `runSkillOpt`
+     *  path may also supply it. */
+    findingsNote?: string;
+    /** How many candidate patches to propose. */
+    count: number;
+    signal: AbortSignal;
+}
+export interface SkillOptProposerOptions {
+    llm: LlmClientOptions;
+    model: string;
+    /** What the skill document governs — orients the prompt. */
+    target: string;
+    /** Default ops-per-patch cap when used as a bare `SurfaceProposer`. The
+     *  `runSkillOpt` preset overrides this per epoch as it anneals. Default 3. */
+    editBudget?: number;
+    temperature?: number;
+    maxTokens?: number;
+    /** Top-K weak scenarios/dimensions surfaced as evidence. Default 3. */
+    evidenceK?: number;
+}
+export interface SkillOptProposer extends SurfaceProposer {
+    /** Patch-native path used by `runSkillOpt` (the SkillOpt epoch loop owns
+     *  acceptance/budget/buffer). Returns structured patches, NOT surfaces. */
+    proposePatches(args: ProposePatchesArgs): Promise<SkillPatch[]>;
+}
+export declare function skillOptProposer(opts: SkillOptProposerOptions): SkillOptProposer;
+/** Parse + validate the patch response. Throws `SkillPatchParseError` when the
+ *  response is not valid JSON at all (a router/model failure the caller must
+ *  see — never a silent no-op epoch). Returns `[]` only for the legitimate
+ *  "valid JSON, zero usable patches" case. Malformed ops within a patch are
+ *  dropped (not silently mutated); each patch is truncated to the edit budget. */
+export declare class SkillPatchParseError extends Error {
+    constructor(message: string);
+}
+export declare function parseSkillPatchResponse(raw: string, maxPatches: number, editBudget: number): SkillPatch[];
+//# sourceMappingURL=skill-opt.d.ts.map

package/dist/campaign/proposers/skill-opt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-opt.d.ts","sourceRoot":"","sources":["../../../src/campaign/proposers/skill-opt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAW,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAEjE,OAAO,EAAmB,KAAK,UAAU,EAAqB,MAAM,gBAAgB,CAAA;AACpF,OAAO,KAAK,EAAqC,eAAe,EAAE,MAAM,UAAU,CAAA;AAYlF;;yEAEyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,aAAa,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC/D,kEAAkE;IAClE,cAAc,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC5D;AAED;mEACmE;AACnE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAA;IAClB,cAAc,EAAE,YAAY,EAAE,CAAA;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;mCAG+B;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,WAAW,CAAA;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,gBAAgB,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAA;IACd;kFAC8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD;+EAC2E;IAC3E,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;CAChE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,GAAG,gBAAgB,CA8DhF;AAuED;;;;kFAIkF;AAClF,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,UAAU,EAAE,CAmCd"}

package/dist/campaign/proposers/trace-analyst.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `traceAnalystProposer` — wraps agent-eval's OWN trace-analyst engine
+ * (`AnalystRegistry` over the agentic OTLP reader) as a `SurfaceProposer`.
+ * It is the symmetric opponent to `haloProposer`: both run the SAME shared
+ * `analysisEditProposer` pipeline (materialize identical traces → apply via one
+ * identical LLM edit), so a `compareProposers` lift delta isolates a single
+ * variable — ANALYSIS QUALITY. The benchmark answers "is our HALO clone as good
+ * as the real HALO?" as a held-out lift CI, not a vibe.
+ *
+ * Findings come from the REGISTRY (structured `AnalystFinding[]` carrying
+ * area / severity / recommended_action), rendered into the report the shared
+ * apply step consumes.
+ *
+ * Fail-loud: no traces → throw; analyst run errors → throw; zero findings →
+ * throw. Never fabricate a candidate.
+ */
+import { type TraceAnalystKindSpec } from '../../analyst/kind-factory';
+import type { AnalystFinding } from '../../analyst/types';
+import type { LlmClientOptions } from '../../llm-client';
+import type { ProposeContext, SurfaceProposer } from '../types';
+export interface TraceAnalystProposerOptions {
+    /** OpenAI-compatible base URL for BOTH the analyst's agentic reads and the
+     *  apply step (e.g. `https://api.deepseek.com/v1` or the Tangle router). */
+    baseUrl: string;
+    /** Bearer key. Required — the Ax AI service has no env fallback here. */
+    apiKey: string;
+    /** Model the analyst kinds use for their agentic trace reads. */
+    model: string;
+    /** Model used to APPLY findings to the prompt surface. Default = `model`.
+     *  Keep this EQUAL to haloProposer's `applyModel` for an apples-to-apples run. */
+    applyModel?: string;
+    /** Ax provider name. Default 'openai' — works for any OpenAI-compatible base
+     *  via `apiURL`. Use 'deepseek' to hit DeepSeek's native provider. */
+    provider?: string;
+    /** Which analyst kinds to run. Default = the full shipped suite. */
+    kinds?: readonly TraceAnalystKindSpec[];
+    /** Resolve the OTLP traces (JSONL string) the analyst should read for THIS
+     *  generation — identical contract to `haloProposer.resolveTraces`. */
+    resolveTraces: (ctx: ProposeContext) => string | Promise<string>;
+    /** Override the findings producer. Default: the shipped `AnalystRegistry`
+     *  over `kinds`. The unit suite injects canned findings here. */
+    analyze?: (tracePath: string, ctx: ProposeContext) => Promise<ReadonlyArray<AnalystFinding>>;
+    /** Test seam: inject a fetch for the apply-step `callLlm`. */
+    fetchImpl?: LlmClientOptions['fetch'];
+}
+/** Wrap agent-eval's trace-analyst registry as a SurfaceProposer (prompt-tier). */
+export declare function traceAnalystProposer(opts: TraceAnalystProposerOptions): SurfaceProposer;
+//# sourceMappingURL=trace-analyst.d.ts.map

package/dist/campaign/proposers/trace-analyst.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-analyst.d.ts","sourceRoot":"","sources":["../../../src/campaign/proposers/trace-analyst.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAA0B,KAAK,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AAG9F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAExD,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAG/D,MAAM,WAAW,2BAA2B;IAC1C;gFAC4E;IAC5E,OAAO,EAAE,MAAM,CAAA;IACf,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAA;IACd,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAA;IACb;sFACkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;0EACsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oEAAoE;IACpE,KAAK,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAA;IACvC;2EACuE;IACvE,aAAa,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAChE;qEACiE;IACjE,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC,CAAA;IAC5F,8DAA8D;IAC9D,SAAS,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;CACtC;AAcD,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,2BAA2B,GAAG,eAAe,CAoDvF"}

package/dist/campaign/proposers/trace-analyst.test.d.ts

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

package/dist/campaign/proposers/trace-analyst.test.d.ts.map

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

package/dist/campaign/provenance.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Loop provenance — the durable, queryable record of WHAT a self-improvement
+ * loop did and WHY, plus the OTel spans that let an OTLP collector pivot from
+ * an eval-run to the underlying candidate→cell→gate→promote chain.
+ *
+ * Two artifacts, one source of truth:
+ *
+ *   1. `LoopProvenanceRecord` — a structured JSON record capturing every
+ *      candidate (surfaceHash + label + rationale), its measured composite,
+ *      the gate decision + reasons + delta, the held-out lift, the explicit
+ *      baseline→candidate diff, and BACKEND PROVENANCE (the
+ *      `assertRealBackend` verdict + worker call count + model). This is the
+ *      ingestable audit artifact: the +lift recomputes from it, the "because
+ *      Z" rationale survives in it, and a stub backend is detectable from it.
+ *
+ *   2. `loopProvenanceSpans()` — the same chain emitted as OTLP-ingestable
+ *      `TraceSpanEvent`s, pivoted on the substrate's standard
+ *      `tangle.runId` / `tangle.scenarioId` / `tangle.cellId` /
+ *      `tangle.generation` attributes (the same pivots `/adapters/otel`
+ *      reads). The hosted `/v1/ingest/traces` endpoint receives the FULL loop,
+ *      not just the `cost.*` spans `runCampaign` already emits per cell.
+ *
+ * The record is built from the substrate's own loop result + the per-call
+ * `RunRecord`s the worker emitted — no new measurement, no recomputation that
+ * could drift from what the gate actually saw.
+ */
+import type { HostedClient } from '../hosted/client';
+import type { TraceSpanEvent } from '../hosted/types';
+import type { RunRecord } from '../run-record';
+import type { CampaignStorage } from './storage';
+import type { CampaignResult, GateDecision, GateResult, MutableSurface, Scenario } from './types';
+/** Stable sha256 (full hex) of a surface's effective text. Code surfaces hash
+ *  their worktree+base identity since the content lives in git. Distinct from
+ *  `surfaceHash` (16-char content fingerprint used as a loop identity key);
+ *  this is the byte-identical-verifiable content hash the provenance record +
+ *  `RunRecord.promptHash` carry. */
+export declare function surfaceContentHash(surface: MutableSurface): string;
+export interface LoopProvenanceCandidate {
+    /** Generation index this candidate was proposed in. */
+    generation: number;
+    /** 16-char loop-identity fingerprint (matches `GenerationCandidate.surfaceHash`). */
+    surfaceHash: string;
+    /** Full sha256 content hash — byte-identical-verifiable. */
+    contentHash: string;
+    /** Proposer label, when the proposer returned a `ProposedCandidate`. */
+    label?: string;
+    /** Proposer rationale — the "because Z". When the proposer returned a bare
+     *  surface (blind mutator) this is absent. */
+    rationale?: string;
+    /** Mean composite this candidate scored on the search split. */
+    composite: number;
+    /** Whether this candidate was promoted out of its generation. */
+    promoted: boolean;
+}
+export interface LoopProvenanceBackend {
+    /** `assertRealBackend`-grade verdict over the worker call records. */
+    verdict: 'real' | 'mixed' | 'stub';
+    /** Number of worker LLM calls captured (the audit's "worker call count"). */
+    workerCallCount: number;
+    /** Distinct model ids observed across worker calls. */
+    models: string[];
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCostUsd: number;
+}
+/**
+ * The durable provenance record. Aligns to the hosted `EvalRunEvent` path but
+ * ADDS the rationale + the explicit baseline→candidate diff (both omitted from
+ * the bare hosted event) + backend provenance.
+ */
+export interface LoopProvenanceRecord {
+    schema: 'tangle.loop-provenance.v1';
+    runId: string;
+    runDir: string;
+    timestamp: string;
+    /** Baseline + winner surface content hashes — distinguishable, byte-verifiable. */
+    baselineContentHash: string;
+    winnerContentHash: string;
+    /** Proposer label/rationale for the promoted change. Absent ⇒ winner == baseline. */
+    winnerLabel?: string;
+    winnerRationale?: string;
+    /** The explicit baseline→winner unified diff the gate decided on. */
+    diff: string;
+    /** Every candidate across every generation, each carrying its rationale. */
+    candidates: LoopProvenanceCandidate[];
+    /** The gate verdict — decision + reasons + contributing gates + delta. */
+    gate: {
+        decision: GateDecision;
+        reasons: string[];
+        delta?: number;
+        contributingGates: Array<{
+            name: string;
+            passed: boolean;
+        }>;
+    };
+    /** baseline-on-holdout composite mean. */
+    baselineHoldoutComposite: number;
+    /** winner-on-holdout composite mean. */
+    winnerHoldoutComposite: number;
+    /** winnerHoldout - baselineHoldout — RECOMPUTABLE from this record. */
+    heldOutLift: number;
+    /** Backend provenance: stub-vs-real verdict + worker call count + models. */
+    backend: LoopProvenanceBackend;
+    totalCostUsd: number;
+    totalDurationMs: number;
+}
+export interface BuildLoopProvenanceArgs<TArtifact, TScenario extends Scenario> {
+    runId: string;
+    runDir: string;
+    timestamp: string;
+    baselineSurface: MutableSurface;
+    winnerSurface: MutableSurface;
+    winnerLabel?: string;
+    winnerRationale?: string;
+    diff: string;
+    /** Per-generation candidate records straight off the loop result. */
+    generations: Array<{
+        generationIndex: number;
+        candidates: Array<{
+            surfaceHash: string;
+            composite: number;
+            label?: string;
+            rationale?: string;
+        }>;
+        promoted: string[];
+        /** Surfaces measured this generation, keyed positionally to candidates so
+         *  the content hash can be computed from the real surface text. */
+        surfaces: Array<{
+            surfaceHash: string;
+            surface: MutableSurface;
+        }>;
+    }>;
+    gate: GateResult;
+    baselineOnHoldout: CampaignResult<TArtifact, TScenario>;
+    winnerOnHoldout: CampaignResult<TArtifact, TScenario>;
+    /** Worker call records — the source for backend provenance. */
+    workerRecords: ReadonlyArray<RunRecord>;
+    totalCostUsd: number;
+    totalDurationMs: number;
+}
+/** Build the durable provenance record from a completed loop result. */
+export declare function buildLoopProvenanceRecord<TArtifact, TScenario extends Scenario>(args: BuildLoopProvenanceArgs<TArtifact, TScenario>): LoopProvenanceRecord;
+/**
+ * Build the loop's OTLP-ingestable spans from a provenance record. One root
+ * span per loop (`tangle.runId`), one span per generation, one span per
+ * candidate (carrying its surfaceHash + label), and one span for the gate
+ * decision (carrying reasons + delta + lift). Candidate + gate spans pivot on
+ * the same `tangle.runId` / `tangle.generation` attributes `/adapters/otel`
+ * reads, so the hosted collector reconstructs the full tree.
+ *
+ * Times are synthesized monotonically off a single base so the span tree is
+ * orderable; the substrate does not retain per-candidate wall-clock starts.
+ */
+export declare function loopProvenanceSpans(record: LoopProvenanceRecord, opts?: {
+    baseTimeMs?: number;
+}): TraceSpanEvent[];
+/** Canonical durable paths under the run dir. */
+export declare function provenanceRecordPath(runDir: string): string;
+export declare function provenanceSpansPath(runDir: string): string;
+export interface EmitLoopProvenanceResult {
+    record: LoopProvenanceRecord;
+    spans: TraceSpanEvent[];
+    /** Absolute paths the record + spans were written to, when storage persists. */
+    recordPath: string;
+    spansPath: string;
+}
+export interface EmitLoopProvenanceArgs<TArtifact, TScenario extends Scenario> extends BuildLoopProvenanceArgs<TArtifact, TScenario> {
+    /** Storage the record + spans are written through. */
+    storage: CampaignStorage;
+    /** When set, the spans are also shipped to the hosted `/v1/ingest/traces`
+     *  endpoint so the collector receives the full loop, not just `cost.*`. */
+    hostedClient?: HostedClient;
+}
+/**
+ * Build the provenance record + OTel spans and persist them durably under the
+ * run dir (and ship spans to a hosted collector when one is wired). Returns
+ * both artifacts so the caller can assert on / re-derive from them.
+ *
+ * Fail-loud: the durable write throws on storage failure (a swallowed write is
+ * exactly the "emitted but lost" failure this closes). The hosted span ship is
+ * the one best-effort leg — its failure is logged, not thrown, so an offline
+ * collector never fails the loop (the durable artifact is the source of truth).
+ */
+export declare function emitLoopProvenance<TArtifact, TScenario extends Scenario>(args: EmitLoopProvenanceArgs<TArtifact, TScenario>): Promise<EmitLoopProvenanceResult>;
+//# sourceMappingURL=provenance.d.ts.map

package/dist/campaign/provenance.d.ts.map

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

package/dist/campaign/run-campaign.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `runCampaign` — Pass A substrate primitive. ONE function that orchestrates
+ * scenarios → dispatch → artifacts → judges → aggregates, with full
+ * reproducibility (seed + manifest hash), cell-level resumability, bootstrap
+ * CIs, and the `LabeledScenarioStore` capture flywheel.
+ *
+ * Improvement loops (optimizer / gate / autoOnPromote) ride on top of this
+ * primitive but live in `presets/run-improvement-loop.ts`. This file keeps
+ * the core orchestrator minimal — Phase 1 of the Pass A track.
+ */
+import { type CampaignStorage } from './storage';
+import type { CampaignResult, CampaignTraceWriter, DispatchFn, JudgeConfig, LabeledScenarioStore, Scenario } from './types';
+export interface RunCampaignOptions<TScenario extends Scenario, TArtifact> {
+    scenarios: TScenario[];
+    dispatch: DispatchFn<TScenario, TArtifact>;
+    judges?: JudgeConfig<TArtifact, TScenario>[];
+    /** Required for reproducibility. Default 42. */
+    seed?: number;
+    /** Per-scenario replicates for CI bands. Default 1; raise to 5+ for
+     *  bootstrap-tight intervals on critical eval. */
+    reps?: number;
+    /** When true (default), completed cells are cached by
+     *  (manifestHash, scenarioId, rep, generation). Re-runs skip cached cells. */
+    resumable?: boolean;
+    /** Optional store — when present, every artifact + judge score is captured
+     *  with the configured `captureSource`. Capture is default ON; pass `'off'`
+     *  to disable. */
+    labeledStore?: LabeledScenarioStore | 'off';
+    captureSource?: 'production-trace' | 'eval-run' | 'manual' | 'red-team' | 'synthetic';
+    captureSourceVersionHash?: string;
+    /** Wall-clock cost cap across all cells. Cells beyond ceiling are skipped. */
+    costCeiling?: number;
+    /** Max concurrent cells. Default 2. */
+    maxConcurrency?: number;
+    /**
+     * Per-cell dispatch deadline in ms. A `dispatch` that neither resolves nor
+     * rejects within this window is a hang (a stalled model request, an
+     * exhausted runtime resource, a backend that never closes its stream). When
+     * set, the cell's `ctx.signal` is aborted and the cell is recorded as a LOUD
+     * error (`dispatch exceeded <N>ms`) so the campaign proceeds and the failure
+     * is visible — instead of one wedged cell silently hanging the whole run (and
+     * every loop/CI job above it) forever. `undefined`/`0` = unbounded (legacy).
+     */
+    dispatchTimeoutMs?: number;
+    /** Required: where artifacts + traces land. */
+    runDir: string;
+    /** Tracing posture. Default is the substrate's `FileSystemTraceStore` rooted
+     *  at `<runDir>/traces/`. `'off'` disables capture entirely — substrate
+     *  refuses this when the caller wires `autoOnPromote !== 'none'`. */
+    tracing?: 'on' | 'off';
+    /**
+     * Per-cell usage expectation — the early, fine-grained sibling of the
+     * batch `assertRealBackend` guard. A cell that produced an artifact (no
+     * error) but reported `costUsd === 0` AND zero tokens is a stub: the
+     * dispatch never reported LLM activity via `ctx.cost`. Modes:
+     *   - `'warn'` (default) — log the offending cell loudly, keep going.
+     *   - `'assert'` — throw `BackendIntegrityError` on the first such cell
+     *     (fail-fast; recommended for CI campaigns expecting real LLM calls).
+     *   - `'off'` — no check (replay / deterministic-only / offline analysis).
+     */
+    expectUsage?: 'assert' | 'warn' | 'off';
+    /** Test seam — override the wall clock for deterministic tests. */
+    now?: () => Date;
+    /** Test seam — override per-cell trace writer factory. */
+    buildTraceWriter?: (cellId: string, dir: string) => CampaignTraceWriter;
+    /** Storage backend for run/cell dirs, the resumability cache, artifacts,
+     *  and trace spans. Default: the Node filesystem (`fsCampaignStorage`).
+     *  Pass `inMemoryCampaignStorage()` to run in a filesystem-less runtime
+     *  (Cloudflare Workers, Deno, edge) — the `CampaignResult` is still
+     *  produced; artifacts/traces just aren't persisted to disk. */
+    storage?: CampaignStorage;
+    /**
+     * Optional per-cell placement strategy. Returns an opaque string the
+     * substrate forwards as `ctx.placement` to the Dispatch — placement-aware
+     * Dispatches (e.g. `httpDispatch` from `/adapters/http`) use it to route
+     * each cell to the right worker, region, or sandbox. When unset, every
+     * cell receives `ctx.placement = undefined` and behaves identically to
+     * the in-process case.
+     *
+     * @example
+     *   cellPlacement: ({ scenario }) => scenario.tags?.includes('eu') ? 'eu-west' : 'us-east'
+     */
+    cellPlacement?: (input: {
+        scenario: TScenario;
+        rep: number;
+        generation?: number;
+    }) => string | undefined;
+}
+export declare function runCampaign<TScenario extends Scenario, TArtifact>(opts: RunCampaignOptions<TScenario, TArtifact>): Promise<CampaignResult<TArtifact, TScenario>>;
+//# sourceMappingURL=run-campaign.d.ts.map

package/dist/campaign/run-campaign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-campaign.d.ts","sourceRoot":"","sources":["../../src/campaign/run-campaign.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,EAAE,KAAK,eAAe,EAAqB,MAAM,WAAW,CAAA;AACnE,OAAO,KAAK,EAKV,cAAc,EAEd,mBAAmB,EAEnB,UAAU,EAEV,WAAW,EAEX,oBAAoB,EACpB,QAAQ,EAGT,MAAM,SAAS,CAAA;AAEhB,MAAM,WAAW,kBAAkB,CAAC,SAAS,SAAS,QAAQ,EAAE,SAAS;IACvE,SAAS,EAAE,SAAS,EAAE,CAAA;IACtB,QAAQ,EAAE,UAAU,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;IAC1C,MAAM,CAAC,EAAE,WAAW,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAA;IAC5C,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;sDACkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;kFAC8E;IAC9E,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;sBAEkB;IAClB,YAAY,CAAC,EAAE,oBAAoB,GAAG,KAAK,CAAA;IAC3C,aAAa,CAAC,EAAE,kBAAkB,GAAG,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAA;IACrF,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAA;IACd;;yEAEqE;IACrE,OAAO,CAAC,EAAE,IAAI,GAAG,KAAK,CAAA;IACtB;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAA;IACvC,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;IAChB,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,mBAAmB,CAAA;IACvE;;;;oEAIgE;IAChE,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE;QACtB,QAAQ,EAAE,SAAS,CAAA;QACnB,GAAG,EAAE,MAAM,CAAA;QACX,UAAU,CAAC,EAAE,MAAM,CAAA;KACpB,KAAK,MAAM,GAAG,SAAS,CAAA;CACzB;AAED,wBAAsB,WAAW,CAAC,SAAS,SAAS,QAAQ,EAAE,SAAS,EACrE,IAAI,EAAE,kBAAkB,CAAC,SAAS,EAAE,SAAS,CAAC,GAC7C,OAAO,CAAC,cAAc,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAyH/C"}

package/dist/campaign/score-utils.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared campaign-score reductions used by every optimizer preset
+ * (`runOptimization`, `runSkillOpt`, `compareProposers`). ONE definition of
+ * "composite of a campaign" and "per-scenario / per-dimension breakdown" so
+ * the optimizers cannot drift on how a surface's score is computed.
+ */
+import type { CampaignResult, Scenario } from './types';
+/** Mean composite across a campaign: per cell, the mean of its judges'
+ *  composites; then the mean across cells. Cells with no judge scores are
+ *  skipped. Empty ⇒ 0. */
+export declare function campaignMeanComposite<TArtifact, TScenario extends Scenario>(campaign: CampaignResult<TArtifact, TScenario>): number;
+export interface CampaignBreakdown {
+    /** Mean score per judge dimension across all cells. */
+    dimensions: Record<string, number>;
+    /** Per-scenario composite (mean over reps + judges) + the judge's free-form
+     *  `notes` for that scenario (the "why" a reflective proposer grounds on). */
+    scenarios: Array<{
+        scenarioId: string;
+        composite: number;
+        notes?: string;
+    }>;
+}
+/** Per-candidate evidence a reflective/patch proposer grounds its next proposal
+ *  on: mean score per judge dimension + per-scenario composite. */
+export declare function campaignBreakdown<TArtifact, TScenario extends Scenario>(campaign: CampaignResult<TArtifact, TScenario>): CampaignBreakdown;
+//# sourceMappingURL=score-utils.d.ts.map

package/dist/campaign/score-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"score-utils.d.ts","sourceRoot":"","sources":["../../src/campaign/score-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvD;;0BAE0B;AAC1B,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,SAAS,SAAS,QAAQ,EACzE,QAAQ,EAAE,cAAc,CAAC,SAAS,EAAE,SAAS,CAAC,GAC7C,MAAM,CASR;AAED,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAClC;kFAC8E;IAC9E,SAAS,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC5E;AAED;mEACmE;AACnE,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,SAAS,SAAS,QAAQ,EACrE,QAAQ,EAAE,cAAc,CAAC,SAAS,EAAE,SAAS,CAAC,GAC7C,iBAAiB,CA4CnB"}