@tangle-network/agent-eval 0.93.0 → 0.95.0

package/dist/workflow/phase-graph.d.ts

@@ -0,0 +1,43 @@
+import type { RunTokenUsage } from '../run-record';
+import type { WorkflowTraceEvent } from './types';
+export interface WorkflowPhaseGraphNode {
+    id: string;
+    title: string;
+    startedAt?: number;
+    endedAt?: number;
+    eventCount: number;
+    branchCount: number;
+    failedBranchCount: number;
+    agentCalls: number;
+    loopCalls: number;
+    verifierCalls: number;
+    analystCalls: number;
+    reviewerCalls: number;
+    agentFailures: number;
+    loopFailures: number;
+    verifierFailures: number;
+    analystFailures: number;
+    reviewerFailures: number;
+    costUsd: number;
+    tokenUsage: RunTokenUsage;
+}
+export interface WorkflowPhaseGraphBranch {
+    id: string;
+    operation: string;
+    branchIndex: number;
+    phase: string | null;
+    status: 'started' | 'ended' | 'failed';
+    startedAt?: number;
+    endedAt?: number;
+    durationMs?: number;
+    stageCount?: number;
+    stageIndex?: number;
+    message?: string;
+    code?: string;
+}
+export interface WorkflowPhaseGraph {
+    nodes: WorkflowPhaseGraphNode[];
+    branches: WorkflowPhaseGraphBranch[];
+}
+export declare function workflowPhaseGraph(events: readonly WorkflowTraceEvent[]): WorkflowPhaseGraph;
+//# sourceMappingURL=phase-graph.d.ts.map

package/dist/workflow/phase-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-graph.d.ts","sourceRoot":"","sources":["../../src/workflow/phase-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAElD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAEjD,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,iBAAiB,EAAE,MAAM,CAAA;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,gBAAgB,EAAE,MAAM,CAAA;IACxB,eAAe,EAAE,MAAM,CAAA;IACvB,gBAAgB,EAAE,MAAM,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,aAAa,CAAA;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAA;IACtC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,sBAAsB,EAAE,CAAA;IAC/B,QAAQ,EAAE,wBAAwB,EAAE,CAAA;CACrC;AAKD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,GAAG,kBAAkB,CAwB5F"}

package/dist/workflow/promotion-gate.d.ts

@@ -0,0 +1,61 @@
+import { type RunRecord } from '../run-record';
+import { type PairedBootstrapResult } from '../statistics';
+export type WorkflowDriverPromotionDecisionVersion = 'workflow-driver-promotion-v1';
+export type WorkflowDriverPromotionRejectionCode = 'missing_baseline_records' | 'missing_candidate_records' | 'missing_holdout_pairs' | 'few_pairs' | 'insufficient_lift' | 'cost_ceiling';
+export interface WorkflowDriverPromotionPair {
+    key: string;
+    scenarioId: string;
+    seed: number;
+    baselineRunId: string;
+    candidateRunId: string;
+    baselineScore: number;
+    candidateScore: number;
+    delta: number;
+}
+export interface WorkflowDriverPromotionEvidence {
+    pairedRuns: number;
+    expectedScenarioIds: string[];
+    pairedScenarioIds: string[];
+    missingScenarioIds: string[];
+    baselineMean: number;
+    candidateMean: number;
+    lift: number;
+    liftCi: {
+        low: number;
+        high: number;
+    };
+    bootstrap: PairedBootstrapResult;
+    confidence: number;
+    resamples: number;
+    statistic: 'mean' | 'median';
+    deltaThreshold: number;
+    baselineMedianCostUsd: number;
+    candidateMedianCostUsd: number;
+    pairs: WorkflowDriverPromotionPair[];
+}
+export interface WorkflowDriverPromotionDecision {
+    schemaVersion: WorkflowDriverPromotionDecisionVersion;
+    generatedAt: string;
+    baselineStrategyId: string;
+    candidateStrategyId: string;
+    promote: boolean;
+    rejectionCode: WorkflowDriverPromotionRejectionCode | null;
+    reason: string;
+    evidence: WorkflowDriverPromotionEvidence;
+}
+export interface DecideWorkflowDriverPromotionOptions {
+    records: readonly RunRecord[] | readonly unknown[];
+    baselineStrategyId?: string;
+    candidateStrategyId?: string;
+    expectedScenarioIds?: readonly string[];
+    minPairedHoldoutRuns?: number;
+    deltaThreshold?: number;
+    confidence?: number;
+    resamples?: number;
+    seed?: number;
+    statistic?: 'mean' | 'median';
+    costPerRunCeiling?: number;
+    generatedAt?: string;
+}
+export declare function decideWorkflowDriverPromotion(options: DecideWorkflowDriverPromotionOptions): WorkflowDriverPromotionDecision;
+//# sourceMappingURL=promotion-gate.d.ts.map

package/dist/workflow/promotion-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promotion-gate.d.ts","sourceRoot":"","sources":["../../src/workflow/promotion-gate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,SAAS,EAAqB,MAAM,eAAe,CAAA;AACjE,OAAO,EAAE,KAAK,qBAAqB,EAAmB,MAAM,eAAe,CAAA;AAE3E,MAAM,MAAM,sCAAsC,GAAG,8BAA8B,CAAA;AAEnF,MAAM,MAAM,oCAAoC,GAC5C,0BAA0B,GAC1B,2BAA2B,GAC3B,uBAAuB,GACvB,WAAW,GACX,mBAAmB,GACnB,cAAc,CAAA;AAElB,MAAM,WAAW,2BAA2B;IAC1C,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,aAAa,EAAE,MAAM,CAAA;IACrB,cAAc,EAAE,MAAM,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;IACrB,cAAc,EAAE,MAAM,CAAA;IACtB,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,+BAA+B;IAC9C,UAAU,EAAE,MAAM,CAAA;IAClB,mBAAmB,EAAE,MAAM,EAAE,CAAA;IAC7B,iBAAiB,EAAE,MAAM,EAAE,CAAA;IAC3B,kBAAkB,EAAE,MAAM,EAAE,CAAA;IAC5B,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACrC,SAAS,EAAE,qBAAqB,CAAA;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,GAAG,QAAQ,CAAA;IAC5B,cAAc,EAAE,MAAM,CAAA;IACtB,qBAAqB,EAAE,MAAM,CAAA;IAC7B,sBAAsB,EAAE,MAAM,CAAA;IAC9B,KAAK,EAAE,2BAA2B,EAAE,CAAA;CACrC;AAED,MAAM,WAAW,+BAA+B;IAC9C,aAAa,EAAE,sCAAsC,CAAA;IACrD,WAAW,EAAE,MAAM,CAAA;IACnB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,mBAAmB,EAAE,MAAM,CAAA;IAC3B,OAAO,EAAE,OAAO,CAAA;IAChB,aAAa,EAAE,oCAAoC,GAAG,IAAI,CAAA;IAC1D,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,+BAA+B,CAAA;CAC1C;AAED,MAAM,WAAW,oCAAoC;IACnD,OAAO,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,OAAO,EAAE,CAAA;IAClD,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACvC,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAMD,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,oCAAoC,GAC5C,+BAA+B,CA8HjC"}

package/dist/workflow/run-record.d.ts

@@ -0,0 +1,12 @@
+import { type RunRecord } from '../run-record';
+import type { WorkflowTraceEnvelope, WorkflowTraceProjectionMetadata } from './types';
+export interface WorkflowTraceRunRecordOptions extends WorkflowTraceProjectionMetadata {
+    runId?: string;
+    score?: number;
+    raw?: Record<string, number>;
+    failureMode?: string;
+    judgeMetadata?: RunRecord['judgeMetadata'];
+    agentProfile?: RunRecord['agentProfile'];
+}
+export declare function workflowTraceToRunRecord(input: WorkflowTraceEnvelope | unknown, options: WorkflowTraceRunRecordOptions): RunRecord;
+//# sourceMappingURL=run-record.d.ts.map

package/dist/workflow/run-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-record.d.ts","sourceRoot":"","sources":["../../src/workflow/run-record.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAqB,MAAM,eAAe,CAAA;AAEjE,OAAO,KAAK,EAAE,qBAAqB,EAAE,+BAA+B,EAAE,MAAM,SAAS,CAAA;AAErF,MAAM,WAAW,6BAA8B,SAAQ,+BAA+B;IACpF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,aAAa,CAAC,EAAE,SAAS,CAAC,eAAe,CAAC,CAAA;IAC1C,YAAY,CAAC,EAAE,SAAS,CAAC,cAAc,CAAC,CAAA;CACzC;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,qBAAqB,GAAG,OAAO,EACtC,OAAO,EAAE,6BAA6B,GACrC,SAAS,CA6CX"}

package/dist/workflow/runtime-adapter.d.ts

@@ -0,0 +1,20 @@
+import type { WorkflowTopology, WorkflowTraceArtifact, WorkflowTraceEnvelope } from './types';
+export interface WorkflowTraceEnvelopeFromEventsOptions {
+    runId?: string;
+    topology?: WorkflowTopology;
+    artifacts?: readonly WorkflowTraceArtifact[];
+    metadata?: Record<string, unknown>;
+}
+export interface WorkflowRuntimeResultLike {
+    runId?: string;
+    meta?: unknown;
+    output?: unknown;
+    events: readonly unknown[];
+}
+export interface WorkflowRuntimeResultToTraceEnvelopeOptions extends Omit<WorkflowTraceEnvelopeFromEventsOptions, 'runId'> {
+    runId?: string;
+    includeOutputInMetadata?: boolean;
+}
+export declare function workflowEventsToTraceEnvelope(events: readonly unknown[], options?: WorkflowTraceEnvelopeFromEventsOptions): WorkflowTraceEnvelope;
+export declare function workflowRuntimeResultToTraceEnvelope(result: WorkflowRuntimeResultLike, options?: WorkflowRuntimeResultToTraceEnvelopeOptions): WorkflowTraceEnvelope;
+//# sourceMappingURL=runtime-adapter.d.ts.map

package/dist/workflow/runtime-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-adapter.d.ts","sourceRoot":"","sources":["../../src/workflow/runtime-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAE7F,MAAM,WAAW,sCAAsC;IACrD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,gBAAgB,CAAA;IAC3B,SAAS,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAA;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,SAAS,OAAO,EAAE,CAAA;CAC3B;AAED,MAAM,WAAW,2CACf,SAAQ,IAAI,CAAC,sCAAsC,EAAE,OAAO,CAAC;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uBAAuB,CAAC,EAAE,OAAO,CAAA;CAClC;AAED,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,SAAS,OAAO,EAAE,EAC1B,OAAO,GAAE,sCAA2C,GACnD,qBAAqB,CAcvB;AAED,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,yBAAyB,EACjC,OAAO,GAAE,2CAAgD,GACxD,qBAAqB,CAWvB"}

package/dist/workflow/sanitize.d.ts

@@ -0,0 +1,21 @@
+import { type RedactionReport, type RedactionRule } from '../trace/redact';
+import type { WorkflowTraceEnvelope } from './types';
+export interface WorkflowTraceSanitizationReport extends RedactionReport {
+    hashedArgs: number;
+    truncatedStrings: number;
+    droppedPayloadKeys: Record<string, number>;
+    droppedArtifactContents: number;
+}
+export interface SanitizeWorkflowTraceEnvelopeOptions {
+    rules?: readonly RedactionRule[];
+    maxStringLength?: number;
+    hashSalt?: string;
+    approvedArtifactUris?: readonly string[];
+    approvedArtifactKinds?: readonly string[];
+}
+export interface SanitizedWorkflowTraceEnvelopeResult {
+    envelope: WorkflowTraceEnvelope;
+    report: WorkflowTraceSanitizationReport;
+}
+export declare function sanitizeWorkflowTraceEnvelope(input: WorkflowTraceEnvelope | unknown, options?: SanitizeWorkflowTraceEnvelopeOptions): SanitizedWorkflowTraceEnvelopeResult;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/workflow/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/workflow/sanitize.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,aAAa,EAEnB,MAAM,iBAAiB,CAAA;AAExB,OAAO,KAAK,EAAyB,qBAAqB,EAAsB,MAAM,SAAS,CAAA;AAE/F,MAAM,WAAW,+BAAgC,SAAQ,eAAe;IACtE,UAAU,EAAE,MAAM,CAAA;IAClB,gBAAgB,EAAE,MAAM,CAAA;IACxB,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC1C,uBAAuB,EAAE,MAAM,CAAA;CAChC;AAED,MAAM,WAAW,oCAAoC;IACnD,KAAK,CAAC,EAAE,SAAS,aAAa,EAAE,CAAA;IAChC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACxC,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1C;AAED,MAAM,WAAW,oCAAoC;IACnD,QAAQ,EAAE,qBAAqB,CAAA;IAC/B,MAAM,EAAE,+BAA+B,CAAA;CACxC;AAUD,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,qBAAqB,GAAG,OAAO,EACtC,OAAO,GAAE,oCAAyC,GACjD,oCAAoC,CAyBtC"}

package/dist/workflow/schema.d.ts

@@ -0,0 +1,5 @@
+import type { WorkflowTraceEnvelope, WorkflowTraceEvent, WorkflowTraceSummary } from './types';
+export declare function validateWorkflowTraceEvent(input: unknown): WorkflowTraceEvent;
+export declare function validateWorkflowTraceEnvelope(input: unknown): WorkflowTraceEnvelope;
+export declare function summarizeWorkflowTrace(input: WorkflowTraceEnvelope | unknown): WorkflowTraceSummary;
+//# sourceMappingURL=schema.d.ts.map

package/dist/workflow/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/workflow/schema.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,EAErB,MAAM,SAAS,CAAA;AAIhB,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAU7E;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAwBnF;AA0BD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,qBAAqB,GAAG,OAAO,GACrC,oBAAoB,CA8CtB"}

package/dist/workflow/summary.d.ts

@@ -0,0 +1,43 @@
+import type { RunTokenUsage } from '../run-record';
+import { type WorkflowPhaseGraph } from './phase-graph';
+import type { WorkflowTraceEnvelope, WorkflowTraceSummary } from './types';
+export interface WorkflowDelegateTraceSummary {
+    index: number | null;
+    label: string | null;
+    phase: string | null;
+    costUsd: number | null;
+    tokenUsage: RunTokenUsage | null;
+    trace: unknown;
+}
+export interface WorkflowDelegateFailureSummary {
+    index: number | null;
+    label: string | null;
+    phase: string | null;
+    durationMs: number | null;
+    message: string | null;
+    code: string | null;
+}
+export interface WorkflowCheckpointTraceSummary extends WorkflowDelegateTraceSummary {
+    output: unknown;
+}
+export interface WorkflowExecutionSummary extends WorkflowTraceSummary {
+    source?: string;
+    eventKinds: Record<string, number>;
+    phases: string[];
+    phaseGraph: WorkflowPhaseGraph;
+    agentRuns: WorkflowDelegateTraceSummary[];
+    loopRuns: WorkflowDelegateTraceSummary[];
+    verifierOutputs: WorkflowCheckpointTraceSummary[];
+    analystOutputs: WorkflowCheckpointTraceSummary[];
+    reviewerOutputs: WorkflowCheckpointTraceSummary[];
+    agentFailureDetails: WorkflowDelegateFailureSummary[];
+    loopFailureDetails: WorkflowDelegateFailureSummary[];
+    verifierFailureDetails: WorkflowDelegateFailureSummary[];
+    analystFailureDetails: WorkflowDelegateFailureSummary[];
+    reviewerFailureDetails: WorkflowDelegateFailureSummary[];
+}
+export interface SummarizeWorkflowExecutionOptions {
+    source?: string;
+}
+export declare function summarizeWorkflowExecution(input: WorkflowTraceEnvelope | unknown, options?: SummarizeWorkflowExecutionOptions): WorkflowExecutionSummary;
+//# sourceMappingURL=summary.d.ts.map

package/dist/workflow/summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.d.ts","sourceRoot":"","sources":["../../src/workflow/summary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAClD,OAAO,EAAE,KAAK,kBAAkB,EAAsB,MAAM,eAAe,CAAA;AAG3E,OAAO,KAAK,EAAE,qBAAqB,EAAsB,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAE9F,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,UAAU,EAAE,aAAa,GAAG,IAAI,CAAA;IAChC,KAAK,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,8BAA8B;IAC7C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CACpB;AAED,MAAM,WAAW,8BAA+B,SAAQ,4BAA4B;IAClF,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,wBAAyB,SAAQ,oBAAoB;IACpE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAClC,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,UAAU,EAAE,kBAAkB,CAAA;IAC9B,SAAS,EAAE,4BAA4B,EAAE,CAAA;IACzC,QAAQ,EAAE,4BAA4B,EAAE,CAAA;IACxC,eAAe,EAAE,8BAA8B,EAAE,CAAA;IACjD,cAAc,EAAE,8BAA8B,EAAE,CAAA;IAChD,eAAe,EAAE,8BAA8B,EAAE,CAAA;IACjD,mBAAmB,EAAE,8BAA8B,EAAE,CAAA;IACrD,kBAAkB,EAAE,8BAA8B,EAAE,CAAA;IACpD,sBAAsB,EAAE,8BAA8B,EAAE,CAAA;IACxD,qBAAqB,EAAE,8BAA8B,EAAE,CAAA;IACvD,sBAAsB,EAAE,8BAA8B,EAAE,CAAA;CACzD;AAED,MAAM,WAAW,iCAAiC;IAChD,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,qBAAqB,GAAG,OAAO,EACtC,OAAO,GAAE,iCAAsC,GAC9C,wBAAwB,CA6B1B"}

package/dist/workflow/trace-event-fields.d.ts

@@ -0,0 +1,6 @@
+import type { RunTokenUsage } from '../run-record';
+export declare function objectRecord(value: unknown): Record<string, unknown> | null;
+export declare function stringField(record: Record<string, unknown>, key: string): string | null;
+export declare function numberField(record: Record<string, unknown>, key: string): number | null;
+export declare function tokenUsageField(value: unknown): RunTokenUsage | null;
+//# sourceMappingURL=trace-event-fields.d.ts.map

package/dist/workflow/trace-event-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-event-fields.d.ts","sourceRoot":"","sources":["../../src/workflow/trace-event-fields.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAElD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAI3E;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGvF;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGvF;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAYpE"}

package/dist/workflow/trajectory.d.ts

@@ -0,0 +1,15 @@
+import type { DatasetSplit } from '../dataset';
+import type { FeedbackTrajectory } from '../feedback-trajectory';
+import type { WorkflowTraceEnvelope } from './types';
+export interface WorkflowTraceTrajectoryOptions {
+    projectId?: string;
+    scenarioId?: string;
+    task: string;
+    split?: DatasetSplit;
+    tags?: Record<string, string>;
+    score?: number;
+    success?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export declare function workflowTraceToFeedbackTrajectory(input: WorkflowTraceEnvelope | unknown, options: WorkflowTraceTrajectoryOptions): FeedbackTrajectory;
+//# sourceMappingURL=trajectory.d.ts.map

package/dist/workflow/trajectory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trajectory.d.ts","sourceRoot":"","sources":["../../src/workflow/trajectory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAmB,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAEjF,OAAO,KAAK,EAAE,qBAAqB,EAAsB,MAAM,SAAS,CAAA;AAExE,MAAM,WAAW,8BAA8B;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,YAAY,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,qBAAqB,GAAG,OAAO,EACtC,OAAO,EAAE,8BAA8B,GACtC,kBAAkB,CAwDpB"}

package/dist/workflow/types.d.ts

@@ -0,0 +1,68 @@
+import type { WorkflowTopology } from '../harness-optimizer';
+import type { RunSplitTag, RunTokenUsage } from '../run-record';
+export type { WorkflowTopology };
+export type WorkflowTraceVersion = 'workflow-trace-v1';
+export type WorkflowTraceEventKind = 'workflow.started' | 'workflow.phase' | 'workflow.log' | 'workflow.parallel.started' | 'workflow.parallel.ended' | 'workflow.pipeline.started' | 'workflow.pipeline.ended' | 'workflow.branch.started' | 'workflow.branch.ended' | 'workflow.branch.failed' | 'workflow.agent.started' | 'workflow.agent.ended' | 'workflow.agent.failed' | 'workflow.loop.started' | 'workflow.loop.ended' | 'workflow.loop.failed' | 'workflow.verifier.started' | 'workflow.verifier.ended' | 'workflow.verifier.failed' | 'workflow.analyst.started' | 'workflow.analyst.ended' | 'workflow.analyst.failed' | 'workflow.reviewer.started' | 'workflow.reviewer.ended' | 'workflow.reviewer.failed' | 'workflow.failed' | 'workflow.ended';
+export interface WorkflowTraceEvent {
+    kind: WorkflowTraceEventKind;
+    runId: string;
+    timestamp: number;
+    payload: Record<string, unknown>;
+}
+export interface WorkflowTraceArtifact {
+    kind: string;
+    uri: string;
+    contentType?: string;
+    sha256?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface WorkflowTraceExportLinks {
+    traceArtifactUri?: string;
+    exportBundleUri?: string;
+    partnerReportUri?: string;
+    intelligenceRunUri?: string;
+}
+export interface WorkflowTraceEnvelope {
+    traceVersion: WorkflowTraceVersion;
+    runId: string;
+    topology?: WorkflowTopology;
+    events: WorkflowTraceEvent[];
+    artifacts?: WorkflowTraceArtifact[];
+    metadata?: Record<string, unknown>;
+}
+export interface WorkflowTraceSummary {
+    runId: string;
+    startedAt?: number;
+    endedAt?: number;
+    durationMs: number;
+    costUsd: number;
+    tokenUsage: RunTokenUsage;
+    phaseCount: number;
+    branchCount: number;
+    failedBranchCount: number;
+    agentCalls: number;
+    loopCalls: number;
+    verifierCalls: number;
+    analystCalls: number;
+    reviewerCalls: number;
+    agentFailures: number;
+    loopFailures: number;
+    verifierFailures: number;
+    analystFailures: number;
+    reviewerFailures: number;
+    eventCount: number;
+    failed: boolean;
+    failureMessage?: string;
+}
+export interface WorkflowTraceProjectionMetadata {
+    experimentId: string;
+    candidateId: string;
+    seed: number;
+    model: string;
+    promptHash: string;
+    configHash: string;
+    commitSha: string;
+    splitTag: RunSplitTag;
+    scenarioId?: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/workspace-inspector.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Workspace inspector — score the persisted state of an agent after a run.
+ *
+ * Many evals don't ask "did the response say the right thing" but "did the
+ * agent put the right rows in the DB / files in the vault / entities on the
+ * canvas". This is the primitive for that.
+ *
+ * Implementations read from D1, KV, filesystem, or any store — the interface
+ * is deliberately small so consumers plug in their own backends.
+ */
+export interface WorkspaceSnapshot {
+    /** Vault files: logical path → content */
+    files: Record<string, string>;
+    /** DB rows: table name → array of rows (post-validation) */
+    rows: Record<string, Array<Record<string, unknown>>>;
+    /** KV entries: key → value (scoped to whatever prefix the inspector chose) */
+    kv: Record<string, string>;
+    /** Free-form blob metadata: for large binaries the inspector stores summary, not bytes */
+    blobs?: Record<string, {
+        size: number;
+        hash?: string;
+        mimeType?: string;
+    }>;
+}
+export interface InspectorContext {
+    /** Workspace / agent / thread id — whatever the backend uses to scope the snapshot */
+    scopeId: string;
+    /** Optional scenario id — allows scenario-specific snapshot shaping */
+    scenarioId?: string;
+}
+export interface WorkspaceInspector {
+    name: string;
+    snapshot(context: InspectorContext): Promise<WorkspaceSnapshot>;
+}
+export declare class InMemoryWorkspaceInspector implements WorkspaceInspector {
+    readonly name = "in-memory";
+    private readonly snapshots;
+    set(scopeId: string, snapshot: WorkspaceSnapshot): void;
+    snapshot(context: InspectorContext): Promise<WorkspaceSnapshot>;
+}
+export interface WorkspaceAssertion {
+    name: string;
+    description?: string;
+    check(snapshot: WorkspaceSnapshot): WorkspaceAssertionResult;
+}
+export interface WorkspaceAssertionResult {
+    pass: boolean;
+    /** 0..1 — partial credit for assertions that admit it */
+    score: number;
+    detail?: string;
+}
+export declare function fileExists(path: string): WorkspaceAssertion;
+export declare function fileContains(path: string, needle: string): WorkspaceAssertion;
+export declare function rowCount(table: string, min: number, max?: number): WorkspaceAssertion;
+export declare function rowWhere<T extends Record<string, unknown>>(table: string, predicate: (row: T) => boolean, options?: {
+    min?: number;
+}): WorkspaceAssertion;
+/** Run many assertions; return aggregate pass + mean score + per-assertion details. */
+export declare function runAssertions(snapshot: WorkspaceSnapshot, assertions: WorkspaceAssertion[]): {
+    pass: boolean;
+    score: number;
+    results: Array<{
+        assertion: string;
+        result: WorkspaceAssertionResult;
+    }>;
+};
+//# sourceMappingURL=workspace-inspector.d.ts.map

package/dist/workspace-inspector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-inspector.d.ts","sourceRoot":"","sources":["../src/workspace-inspector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IACpD,8EAA8E;IAC9E,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC1B,0FAA0F;IAC1F,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC3E;AAED,MAAM,WAAW,gBAAgB;IAC/B,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAA;IACf,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;CAChE;AAMD,qBAAa,0BAA2B,YAAW,kBAAkB;IACnE,QAAQ,CAAC,IAAI,eAAc;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuC;IAEjE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAIjD,QAAQ,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAGtE;AAMD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,QAAQ,EAAE,iBAAiB,GAAG,wBAAwB,CAAA;CAC7D;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,OAAO,CAAA;IACb,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAY3D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,kBAAkB,CAgB7E;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAkBrF;AAED,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxD,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,EAC9B,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACzB,kBAAkB,CAiBpB;AAED,uFAAuF;AACvF,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,iBAAiB,EAC3B,UAAU,EAAE,kBAAkB,EAAE,GAC/B;IACD,IAAI,EAAE,OAAO,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,wBAAwB,CAAA;KAAE,CAAC,CAAA;CACxE,CAOA"}

package/dist/wrangler-deploy-runner.test.d.ts

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

package/dist/wrangler-deploy-runner.test.d.ts.map

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

package/docs/campaign-proposers.md

@@ -0,0 +1,170 @@
+# Campaign Proposers, ELI5
+
+A campaign proposer is the part of an improvement loop that says: "try this
+candidate next."
+
+It does not run your agent. It does not score anything. It only proposes a new
+surface to measure. A surface is the thing you are changing: a prompt string, a
+serialized config string, or a code/worktree surface.
+
+Use **proposer** for this role. Older optimizer APIs used "driver"; that word is
+now reserved for execution, sandbox, and router agents that actually drive
+workers.
+
+## The Loop
+
+```text
+current surface
+  -> proposer suggests candidate surfaces
+  -> runCampaign runs each candidate on scenarios
+  -> judges score the artifacts
+  -> runOptimization picks the best candidate
+  -> runImprovementLoop re-scores on holdout and gates release
+```
+
+## Proposer Input
+
+Every `SurfaceProposer.propose(ctx)` receives:
+
+| Field | Plain meaning |
+|---|---|
+| `currentSurface` | The prompt/config/code surface currently being improved. |
+| `history` | What candidates were tried before and how they scored. |
+| `findings` | Failure analysis or analyst findings from traces/eval runs. |
+| `populationSize` | How many candidates the loop asks for this generation. |
+| `generation` | Which generation number this is. |
+| `signal` | Abort signal for cancellation. |
+| `report` | Optional larger analysis report. |
+| `dataset` | Optional labeled scenario store. |
+| `paretoParents` | Optional non-dominated surfaces from prior generations. |
+
+## Proposer Output
+
+A proposer returns candidates:
+
+```ts
+{
+  surface: 'the full new prompt or config',
+  label: 'short name',
+  rationale: 'why this change should help'
+}
+```
+
+Bare surfaces are still accepted, but `label` and `rationale` make results
+auditable, so new proposers should return `ProposedCandidate`.
+
+## Which Proposer To Use
+
+| Proposer factory | Best when | Output surface |
+|---|---|---|
+| `gepaProposer` | You want a strong prompt rewrite driven by prior scores and findings. | prompt string |
+| `skillOptProposer` | You are editing a structured skill/runbook and want anchored small patches. | prompt/skill string |
+| `aceProposer` | You want append-only lessons from findings, preserving every distinct lesson. | prompt/playbook string |
+| `memoryCurationProposer` | You want compact deduped lessons from findings. | prompt/playbook string |
+| `parameterSweepProposer` | You want FAPO-style config/parameter edits from a JSON config surface. | JSON string |
+| `fapoProposer` | You want the FAPO policy: prompt first, then parameter, then structural only when evidence supports escalation. | whatever its level proposer returns |
+
+## FAPO Proposer
+
+FAPO is not "another prompt mutator." The paper describes a reviewed escalation
+policy:
+
+1. evaluate the current workflow,
+2. attribute failures to prompt, parameter/config, or structure,
+3. propose one scoped change,
+4. review the change for scope/leakage/compatibility,
+5. measure it,
+6. keep moving or escalate only when the cheaper level is exhausted.
+
+The simplest useful setup is prompt plus JSON config. Structural/code edits are
+optional and should be injected by the app or runtime layer.
+
+```ts
+import {
+  fapoProposer,
+  gepaProposer,
+  parameterSweepProposer,
+  runImprovementLoop,
+} from '@tangle-network/agent-eval/campaign'
+
+const proposer = fapoProposer({
+  scope: { allowedLevels: ['prompt', 'parameter'] },
+  promptProposer: gepaProposer({ llm, model, target: 'agent prompt' }),
+  parameterProposer: parameterSweepProposer({
+    candidates: [
+      {
+        label: 'raise-retrieval-k',
+        rationale: 'retrieval misses indicate the search budget may be too low',
+        changes: [{ path: 'retrieval.k', value: 10 }],
+      },
+    ],
+  }),
+})
+
+await runImprovementLoop({
+  scenarios: trainScenarios,
+  holdoutScenarios,
+  baselineSurface: JSON.stringify(currentConfig),
+  dispatchWithSurface,
+  judges,
+  proposer,
+  gate,
+  autoOnPromote: 'none',
+  runDir,
+  populationSize: 1,
+  maxGenerations: 10,
+})
+```
+
+If you do have a real code/worktree proposer, pass it as `structuralProposer`.
+`agent-eval` intentionally does not provide that proposer because this package
+measures candidates; the runtime or app owns code generation.
+
+For side-by-side experiments with existing proposers, use the compare entry:
+
+```ts
+import {
+  compareProposers,
+  fapoEscalationEntry,
+  gepaParetoEntry,
+} from '@tangle-network/agent-eval/campaign'
+
+await compareProposers({
+  proposers: [
+    gepaParetoEntry(config),
+    fapoEscalationEntry({
+      ...config,
+      parameterCandidates: [
+        {
+          label: 'raise-retrieval-k',
+          rationale: 'retrieval misses indicate the search budget may be too low',
+          changes: [{ path: 'retrieval.k', value: 10 }],
+        },
+      ],
+    }),
+  ],
+  baselineSurface,
+  holdoutScenarios,
+  dispatchWithSurface,
+  judges,
+  runDir,
+})
+```
+
+## Common Mistakes
+
+- Do not put eval logic inside a proposer. Put it in `dispatch` and `judges`.
+- Do not let a proposer read held-out judge scores. `ProposeContext` makes this
+  a type-level firewall.
+- Do not call FAPO a prompt-only optimizer. Its main value is evidence-based
+  escalation beyond prompt edits.
+- Do not put Claude Code or sandbox-specific code in `agent-eval`. Structural
+  code generation should be supplied as an injected `SurfaceProposer` from the
+  runtime/app layer.
+
+## Simpler Mental Model
+
+Use this sentence when wiring a loop:
+
+> The proposer chooses candidates; the campaign measures them; the gate decides
+> whether the measured winner is safe to promote.

package/docs/concepts.md

@@ -9,17 +9,21 @@ connected, or the answer lacks required sources. The package gives products a
 shared way to record runs, check outcomes, classify failures, compare variants,
 and make release decisions.
 
-## The three top-level functions
+## The top-level functions
 
-Everything funnels through `/contract`. Three entries, one shape coming back:
+Everything funnels through `/contract`. Start with `defineAgentEval()` when you
+can; drop to the raw functions when you need lower-level control.
 
 | Function | When to call it | What you give it | What you get back |
 |---|---|---|---|
+| **`defineAgentEval()`** | You have scenarios, an agent, a judge, and a baseline surface, and you want one object you can score or improve. | scenarios, agent, judge, baseline surface | `{ evaluate(), improve() }` where `evaluate()` returns a campaign result and `improve()` returns a decision packet |
 | **`selfImprove()`** | You have a closed loop — scenarios, judge, agent in hand, and you want the substrate to propose better candidates + gate them. | scenarios, agent, judge, baseline surface | `SelfImproveResult.insight: InsightReport` + ship/hold verdict + winner surface |
 | **`analyzeRuns()`** | You have observed runs (production traces, an approve/reject corpus, a CSV gold set) and want the same rigor packet without invoking an agent. | `RunRecord[]` + optional flags | `InsightReport` |
 | **Intake adapters** (`fromFeedbackTable`, `fromOtelSpans`) | Your data isn't already in `RunRecord` shape — it's in Obsidian, Sheets, an OTel collector, etc. | source-specific input | `RunRecord[]` ready to pipe into `analyzeRuns()` |
 
-The three customer maturity stages — logs only → ratings → closed loop — map exactly to the three functions. See [`customer-journeys.md`](./customer-journeys.md) for the runnable walkthroughs.
+The customer maturity stages — logs only → ratings → closed loop — map to these
+entry points. See [`customer-journeys.md`](./customer-journeys.md) for the
+runnable walkthroughs.
 
 The shape of the answer — `InsightReport` — is identical across all three paths. Distributional summary, paired-bootstrap lift CI, judge stats, inter-rater agreement, cost-quality Pareto, failure clusters, contamination check, outcome correlation, release axes, and a ranked recommendations array. Walked through section-by-section in [`insight-report.md`](./insight-report.md).
 
@@ -182,7 +186,7 @@ release decision.
 
 ## Where to go next
 
-- **Confused by "GEPA / HALO / trace analysis / drivers everywhere"?** → [self-improvement-map.md](./self-improvement-map.md) — one loop, four roles, the seven-driver catalog (production vs bench-only), and why `gepa-refine` is the same loop on a test bench.
+- **Confused by "GEPA / HALO / trace analysis / proposers everywhere"?** → [self-improvement-map.md](./self-improvement-map.md) — one loop, four roles, the proposer catalog (production vs bench-only), and why `gepa-refine` is the same loop on a test bench.
 - **Which `run*` primitive do I use, and how do I grade produced state?** → [eval-surface-map.md](./eval-surface-map.md) — the campaign/matrix/optimization/gate primitives as a pick-by-"use-when" table, plus the produced-state grading composition (verifyCompletion-as-judge — there is no persona-dispatch wrapper) and the in-band body contract.
 - **Need the layman feature map?** → [feature-guide.md](./feature-guide.md) — what each primitive does, when to use it, integration patterns, and guardrails.
 - **Just want to score a string against a rubric?** → [wire-protocol.md](./wire-protocol.md) — HTTP/RPC interface, pluggable from any language.