@graphrefly/graphrefly 0.41.0 → 0.42.0

package/dist/index-8s-Qm-gz.d.ts

@@ -1,218 +0,0 @@
-import { N as Node, A as Actor, P as PolicyRuleData } from './node-BYInONRr.js';
-import { G as Graph, b as GraphDescribeOutput, a as GraphOptions, d as GraphDescribeOptions, D as DescribeFilter } from './graph-BkIkog4h.js';
-import { P as PolicyGateGraph, a as PolicyViolation } from './index-Ck35nA-T.js';
-import { T as TopicGraph } from './index-40ZT4MHj.js';
-
-/**
- * Composable safety layer (roadmap §9.0b — Tier 5.1 Wave-B rebuild).
- *
- * {@link guardedExecution} wraps any {@link Graph} with:
- *
- * - {@link policyGate} — reactive ABAC (Tier 2.3 rename of `policyEnforcer`),
- *   policies stored as a `Node` so LLMs / humans can update them at runtime.
- *   Full transitive dynamic coverage via `watchTopologyTree`.
- * - Reactive {@link GuardedExecutionGraph.scopedDescribeNode} — a thin
- *   delegate over `target.describe({ reactive: true, actor })` that re-derives
- *   on every settle (topology change, error transition, actor swap).
- * - The enforcer's `violations` topic is republished as `violations` on
- *   the wrapper, composable with {@link graphLens}'s `health`.
- * - The wrapper-level `lints` topic surfaces non-policy diagnostic warnings
- *   (`empty-policies` / `audit-no-effect` / `no-actor`) so misconfigurations
- *   are caught reactively rather than via thrown errors at scattered call sites.
- * - The `scope` derived publishes the current configuration tuple
- *   (`{actor, mode, policiesCount}`) for dashboards.
- *
- * V1 scope: policies + actor + reactive scoped describe + lints + scope.
- * Budget-as-option is NOT in V1 — it requires a cost-tracking design that
- * hasn't landed yet. Callers who need a budget limit today append a
- * budget-aware {@link PolicyRuleData} to the policies list (check current
- * cost and `deny` when exhausted).
- *
- * @module
- */
-
-/** Diagnostic warning published on {@link GuardedExecutionGraph.lints}. */
-interface GuardedExecutionLint {
-    /**
-     * - `"empty-policies"` — `policies` Node emitted an empty array in
-     *   `mode: "enforce"`. Static empty arrays throw at construction; this
-     *   covers the reactive case.
-     * - `"audit-no-effect"` — `mode: "audit"` plus the target has no per-node
-     *   guards, so `scopedDescribeNode` filters by per-node guards only and
-     *   policies will never gate visibility (they still populate `violations`
-     *   on writes).
-     * - `"no-actor"` — neither a wrapper-configured nor per-call actor was
-     *   supplied. `scopedDescribeNode` falls back to "describe everything"
-     *   for the corresponding subscription.
-     */
-    kind: "empty-policies" | "audit-no-effect" | "no-actor";
-    message: string;
-    timestamp_ns: number;
-}
-/** Configuration tuple published on {@link GuardedExecutionGraph.scope}. */
-interface GuardedScope {
-    /** The wrapper-configured default actor, or `null` when none configured. */
-    actor: Actor | null;
-    mode: "audit" | "enforce";
-    /** Current policy count (reactive — re-emits on `policies` Node updates). */
-    policiesCount: number;
-}
-/** Options for {@link guardedExecution}. */
-interface GuardedExecutionOptions {
-    /**
-     * Policies enforced against every guarded write. Static list or a live
-     * `Node<readonly PolicyRuleData[]>` (LLM-updatable).
-     *
-     * **Empty-policies handling:**
-     * - Static empty array + `mode: "enforce"` throws `RangeError` at
-     *   construction (deny-by-default is almost certainly a misconfiguration).
-     * - Node-supplied empty array + `mode: "enforce"` emits a one-time
-     *   `"empty-policies"` lint on first such emission (the wrapper can't
-     *   throw mid-run — surface the warning reactively).
-     * - `mode: "audit"` tolerates empty policies (no guards stacked; policies
-     *   only feed the `violations` channel on writes).
-     */
-    policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>;
-    /**
-     * Default actor used when the caller invokes
-     * {@link GuardedExecutionGraph.scopedDescribeNode} without an override.
-     * Accepts a static {@link Actor} or a `Node<Actor>` — when a Node is
-     * supplied, the reactive describe re-derives on every actor emission so
-     * harnesses binding a per-turn actor get a single live describe Node
-     * instead of re-creating one per turn.
-     *
-     * Omit to scope per-call only. A `"no-actor"` lint fires once per instance
-     * if neither a configured nor per-call actor is ever supplied (the
-     * resulting describe is unscoped — full visibility).
-     */
-    actor?: Actor | Node<Actor>;
-    /**
-     * `"enforce"` (default) — push guards onto target nodes so disallowed
-     * writes throw {@link GuardDenied}.
-     * `"audit"` — record would-be denials to the `violations` topic without
-     * blocking writes.
-     */
-    mode?: "audit" | "enforce";
-    /** Ring-buffer cap for the `violations` topic. Default 1000 (inherited from policyGate). */
-    violationsLimit?: number;
-    /** Ring-buffer cap for the `lints` topic. Default 64 — each lint kind fires at most once per instance. */
-    lintsLimit?: number;
-    /** Wrapper graph name. Default `${target.name}_guarded`. */
-    name?: string;
-    /** Wrapper graph options. */
-    graph?: GraphOptions;
-}
-/**
- * Wrapper over a target {@link Graph} providing reactive ABAC + reactive
- * scoped describe + diagnostic lints. Mounts a {@link PolicyGateGraph} under
- * `enforcer`, a {@link TopicGraph} of {@link GuardedExecutionLint} under
- * `lints`, and a `scope` derived publishing `{actor, mode, policiesCount}`.
- *
- * @category patterns
- */
-declare class GuardedExecutionGraph extends Graph {
-    readonly enforcer: PolicyGateGraph;
-    readonly violations: TopicGraph<PolicyViolation>;
-    readonly lints: TopicGraph<GuardedExecutionLint>;
-    readonly scope: Node<GuardedScope>;
-    /**
-     * Canonical reactive describe scoped to the wrapper's configured `actor`.
-     * Subscribes ONCE at construction; lifecycle owned by the wrapper (disposed
-     * on `wrapper.destroy()`). Use this property for the common case
-     * (long-lived consumer wanting "describe scoped to my actor"); use
-     * {@link scopedDescribeNode} only when a per-call actor override or
-     * different `detail`/`fields` is required.
-     *
-     * Re-derives on every settle of the target graph: structural changes,
-     * status transitions (errors flip nodes into `"errored"`), and actor
-     * emissions (when a `Node<Actor>` is bound, including the SENTINEL bridge
-     * applied internally — see qa G1B).
-     */
-    readonly scopedDescribe: Node<GraphDescribeOutput>;
-    private readonly _target;
-    private readonly _actorNode;
-    private readonly _mode;
-    private readonly _firedLintKinds;
-    constructor(target: Graph, opts: GuardedExecutionOptions);
-    private _fireLint;
-    /**
-     * **Per-call escape hatch.** Prefer {@link scopedDescribe} (the mounted
-     * property) for the common case of "describe scoped to my actor." Use
-     * this method ONLY when you need a per-call actor override or different
-     * `detail`/`fields`/`filter`.
-     *
-     * Returns a live `Node<GraphDescribeOutput>` scoped to the supplied (or
-     * configured) actor, plus an explicit `dispose` for caller-controlled
-     * lifecycle. Re-derives on every settle of the target graph: structural
-     * changes, status transitions, and actor emissions (when a `Node<Actor>`
-     * is bound).
-     *
-     * **Lifecycle (qa G1A — EC1 fix).** Each call instantiates a fresh
-     * `target.describe({reactive: true})` handle (with its own version state,
-     * observe handle, transitive topology subscriptions, derived + keepalive).
-     * The caller MUST invoke the returned `dispose()` when finished to release
-     * these resources. Disposers ARE also tracked on the wrapper graph so
-     * `wrapper.destroy()` cleans up any handles the caller forgot — but a
-     * long-lived wrapper with heavy per-call usage will leak until destroy
-     * unless `dispose()` is called explicitly.
-     *
-     * @param actorOverride - Optional per-call override. Static {@link Actor}
-     *   or `Node<Actor>`. Omit to use the wrapper-configured default.
-     * @param opts - Standard {@link GraphDescribeOptions} fields (`detail`,
-     *   `fields`, `filter`). `actor` / `reactive` / `reactiveName` are
-     *   controlled by the wrapper.
-     * @returns `{node, dispose}` — `node` is the live describe Node; `dispose`
-     *   tears down the underlying reactive describe subscription idempotently.
-     */
-    scopedDescribeNode(actorOverride?: Actor | Node<Actor>, opts?: Omit<GraphDescribeOptions, "actor" | "reactive" | "reactiveName">): {
-        node: Node<GraphDescribeOutput>;
-        dispose: () => void;
-    };
-    /** The wrapped graph (escape hatch for tooling). */
-    get target(): Graph;
-}
-/**
- * Wrap a {@link Graph} with {@link policyGate} plus a reactive scoped describe
- * lens. Returns a {@link GuardedExecutionGraph} that can be mounted, diffed,
- * or composed with {@link graphLens}.
- *
- * @param target - The graph to guard.
- * @param opts - See {@link GuardedExecutionOptions}.
- *
- * @example
- * ```ts
- * const guarded = guardedExecution(app, {
- *   actor: state<Actor>({ type: "human", id: "alice" }), // reactive — re-derive on swap
- *   policies: [
- *     { effect: "allow", action: "read", actorType: "human" },
- *     { effect: "deny", action: "write", pathPattern: "system::*" },
- *   ],
- *   mode: "enforce",
- * });
- *
- * // Canonical: subscribe to the mounted reactive describe (no per-call leak).
- * guarded.scopedDescribe.subscribe((msgs) => { /* live describe per actor / topology change *\/ });
- * // Per-call escape hatch (different actor / detail) — caller manages dispose.
- * const detailed = guarded.scopedDescribeNode(undefined, { detail: "standard" });
- * try { detailed.node.subscribe(/* … *\/); } finally { detailed.dispose(); }
- * guarded.violations.events.subscribe(msgs => console.log("violations:", msgs));
- * guarded.lints.events.subscribe(msgs => console.warn("lints:", msgs));
- * guarded.scope.subscribe(msgs => console.log("scope:", msgs));
- * ```
- *
- * @category patterns
- */
-declare function guardedExecution(target: Graph, opts: GuardedExecutionOptions): GuardedExecutionGraph;
-
-declare const index_DescribeFilter: typeof DescribeFilter;
-type index_GuardedExecutionGraph = GuardedExecutionGraph;
-declare const index_GuardedExecutionGraph: typeof GuardedExecutionGraph;
-type index_GuardedExecutionLint = GuardedExecutionLint;
-type index_GuardedExecutionOptions = GuardedExecutionOptions;
-type index_GuardedScope = GuardedScope;
-declare const index_guardedExecution: typeof guardedExecution;
-declare namespace index {
-  export { index_DescribeFilter as DescribeFilter, index_GuardedExecutionGraph as GuardedExecutionGraph, type index_GuardedExecutionLint as GuardedExecutionLint, type index_GuardedExecutionOptions as GuardedExecutionOptions, type index_GuardedScope as GuardedScope, index_guardedExecution as guardedExecution };
-}
-
-export { GuardedExecutionGraph as G, type GuardedExecutionLint as a, type GuardedExecutionOptions as b, type GuardedScope as c, guardedExecution as g, index as i };

package/dist/index-BgjS2b8N.d.ts

@@ -1,366 +0,0 @@
-import { N as Node } from './node-BYInONRr.js';
-import { NodeInput } from './extra/sources.js';
-import { a as GraphOptions, G as Graph } from './graph-BkIkog4h.js';
-import { T as TopicGraph } from './index-40ZT4MHj.js';
-
-/**
- * refineLoop — universal prompt/artifact optimization loop as a reactive Graph.
- *
- * Roadmap §9.8 (Wave 2.5). The loop is a 4-topic reactive pipeline:
- *
- *   iterationTrigger ──▶ GENERATE ──▶ EVALUATE ──▶ ANALYZE ──▶ DECIDE
- *                            │                                   │
- *                            └───────  feedback + trigger  ◀─────┘
- *
- * Each stage is a `TopicGraph` so dispatches stay O(1) per subscriber (cursor-
- * based) and every iteration is observable, replayable, and checkpointable.
- *
- * Composition invariants (from COMPOSITION-GUIDE):
- *  - §7 feedback cycle: only `iterationTrigger` drives re-generation. Strategy
- *    + feedback + dataset are read via closure updaters (§28 factory-time seed)
- *    so mid-run swaps apply to the NEXT iteration, never retrigger the current.
- *  - §28 factory-time seed: strategy, lastFeedback, prevCandidates, dataset
- *    closures captured at wiring time + updated via subscribe handlers so the
- *    first activation doesn't drop the initial pair.
- *  - §32 nested-drain state-mirror: the decide-effect writes `lastFeedback`
- *    BEFORE bumping `iterationTrigger` inside its `batch()`, guaranteeing the
- *    mirror is current when the next-iteration wave reaches the generate fn.
- *  - §19 terminal-emission: history / best emit once per iteration (settled),
- *    not on every intermediate wave.
- *  - §27 attachSnapshotStorage: the whole graph is checkpointable — pause overnight,
- *    resume tomorrow from the exact iteration count, candidate set, strategy.
- *
- * Scope clamp (v1): core factory + `RefineStrategy<T>` + `blindVariation` and
- * `errorCritique` built-ins + budget gating + checkpoint/resume.
- * `mutateAndRefine` / registry / `autoSelectStrategy` / `optimizeCatalog` /
- * `refineExecutor` are deferred.
- *
- * @module
- */
-
-/** A single task row — the unit the evaluator scores one candidate against. */
-interface DatasetItem {
-    readonly id: string;
-    readonly [k: string]: unknown;
-}
-/**
- * One candidate's score on one task. Higher is better by convention.
- *
- * Set `candidateIndex` when the evaluator fans out scores across multiple
- * candidates (e.g. `candidates × tasks`). `pickBest` aggregates mean scores
- * per `candidateIndex` when present; when absent, falls back to positional
- * alignment (`scores[i]` ↔ `candidates[i]`).
- */
-interface EvalResult {
-    readonly taskId: string;
-    readonly score: number;
-    readonly error?: string;
-    readonly detail?: unknown;
-    /** 0-based index into the `candidates` batch this score belongs to. */
-    readonly candidateIndex?: number;
-}
-/** Aggregated feedback the strategy produces from a scores batch. */
-interface Feedback {
-    readonly summary: string;
-    readonly critique?: unknown;
-    readonly weakTasks?: readonly string[];
-    readonly score: number;
-}
-/**
- * Strategy interface — plain object, no base class. Strategies implement three
- * pure hooks; the loop infrastructure wraps them in reactive nodes so every
- * decision is visible in `describe()`.
- *
- * `generate` may be sync or async. Async generates yield a microtask per
- * iteration — that's what gives `pause()` / `setStrategy()` a window to
- * interleave. **A fully synchronous `generate` will drain the entire loop
- * during factory activation** (all iterations run before `refineLoop()`
- * returns), which is usually not what you want for observable, steerable
- * loops. Real strategies that call LLMs / evals are async and Just Work;
- * custom sync strategies for tests are fine but should be marked `async`
- * to match real cadence.
- */
-interface RefineStrategy<T> {
-    readonly name: string;
-    /** Produce initial candidates from the seed. Called at iteration 0. */
-    seed(seed: T): readonly T[];
-    /** Reduce scores to feedback. Pure function. */
-    analyze(scores: readonly EvalResult[], candidates: readonly T[]): Feedback;
-    /**
-     * Generate next-iteration candidates from feedback + prior candidates.
-     * Async allowed — the loop awaits via `fromAny`.
-     */
-    generate(feedback: Feedback, candidates: readonly T[]): Promise<readonly T[]> | readonly T[];
-}
-/**
- * Evaluator shape — Shape 4 (2026-04-22): both `candidates` and `dataset` are
- * reactive nodes; the evaluator's returned node IS the EVALUATE topic's source
- * (no glue). Implementers can batch-eval (e.g. `funnel` with concurrency) or
- * map per-candidate — user's code.
- *
- * **`EvalResult.candidateIndex` semantics.** Optional per-result field.
- * When present, multi-candidate aggregators ({@link errorCritique}'s
- * `pickBest`) score per index, picking the candidate with the highest
- * mean score. When absent across all results, those aggregators fall back
- * to positional matching against `candidates[0]` — meaning a strategy that
- * generates >1 candidate but emits unindexed scores effectively only ever
- * critiques the first candidate. Set `candidateIndex` whenever the
- * evaluator's score corresponds to a specific candidate in the batch.
- */
-type Evaluator<T> = (candidates: Node<readonly T[]>, dataset: Node<readonly DatasetItem[]>) => Node<readonly EvalResult[]>;
-/**
- * Early-stop controls. Each field fans into its own derived node; the four
- * combine via `||` into `converged: Node<boolean>`. Callers see exactly
- * which rule tripped via `status` / the DECIDE topic's `reason`.
- */
-interface ConvergenceOptions {
-    /** Stop when aggregate score has not improved for N iterations. */
-    patience?: number;
-    /** Stop when aggregate score reaches or exceeds this. */
-    minScore?: number;
-    /** Stop when absolute delta between consecutive scores falls below this. */
-    minDelta?: number;
-    /** Stop after N total evaluations (iteration count × per-iter candidates). */
-    maxEvaluations?: number;
-    /** Stop after N iterations. Always set a finite bound in production. */
-    maxIterations?: number;
-}
-/** Emitted to the GENERATE topic each time the strategy produces a batch. */
-interface GenerateEvent<T> {
-    readonly iteration: number;
-    readonly candidates: readonly T[];
-    readonly timestamp_ns: number;
-}
-/** Emitted to the EVALUATE topic when scores settle for an iteration. */
-interface EvaluateEvent<T> {
-    readonly iteration: number;
-    readonly candidates: readonly T[];
-    readonly scores: readonly EvalResult[];
-    readonly timestamp_ns: number;
-}
-/** Emitted to the ANALYZE topic — strategy's reduction over scores. */
-interface AnalyzeEvent<T> {
-    readonly iteration: number;
-    readonly candidates: readonly T[];
-    readonly feedback: Feedback;
-    readonly timestamp_ns: number;
-}
-/** Emitted to the DECIDE topic — branch taken this iteration. */
-interface DecideEvent {
-    readonly iteration: number;
-    readonly decision: "continue" | "converged" | "budget" | "paused";
-    readonly reason?: string;
-    readonly timestamp_ns: number;
-}
-type RefineStatus = "running" | "converged" | "budget" | "paused" | "errored";
-interface Iteration<T> {
-    readonly n: number;
-    readonly candidates: readonly T[];
-    readonly scores: readonly EvalResult[];
-    readonly feedback: Feedback;
-    /** `null` iff the candidate batch for this iteration was empty. */
-    readonly best: T | null;
-    readonly bestScore: number;
-    readonly timestamp_ns: number;
-}
-interface RefineLoopOptions extends ConvergenceOptions {
-    /** Reactive dataset OR a plain array (auto-wrapped into `state`). */
-    dataset: NodeInput<readonly DatasetItem[]> | readonly DatasetItem[];
-    /** Total teacher calls cap across iterations. Default: unlimited. */
-    budget?: number;
-    /** Graph name. Default: `"refine-loop"`. */
-    name?: string;
-    /** Extra graph options forwarded to the underlying `Graph`. */
-    graph?: GraphOptions;
-}
-/**
- * Return type — extends Graph so all observability tools (`describe`,
- * `explain`, `observe`, `attachSnapshotStorage`, `snapshot`) Just Work.
- */
-interface RefineLoopGraph<T> extends Graph {
-    readonly best: Node<T | null>;
-    readonly score: Node<number>;
-    readonly status: Node<RefineStatus>;
-    readonly history: Node<readonly Iteration<T>[]>;
-    readonly strategy: Node<RefineStrategy<T>>;
-    readonly iteration: Node<number>;
-    /** Stage topics — subscribe for per-stage streaming / cursor consumers. */
-    readonly generate: TopicGraph<GenerateEvent<T>>;
-    readonly evaluate: TopicGraph<EvaluateEvent<T>>;
-    readonly analyze: TopicGraph<AnalyzeEvent<T>>;
-    readonly decide: TopicGraph<DecideEvent>;
-    /** Swap the active strategy mid-run (human-in-the-loop handoff). */
-    setStrategy(next: RefineStrategy<T>): void;
-    /** Pause after the current iteration completes. */
-    pause(): void;
-    /** Resume a paused loop. */
-    resume(): void;
-}
-declare function refineLoop<T>(seed: T, evaluator: Evaluator<T>, initialStrategy: RefineStrategy<T>, opts: RefineLoopOptions): RefineLoopGraph<T>;
-/**
- * Context passed to a `blindVariation` teacher per call. `reportCost` is a
- * per-call hook — see `BlindVariationOptions.tokens`.
- */
-interface BlindVariationContext<T> {
-    readonly prior: T;
-    /**
-     * Report tokens consumed by this teacher call. Aggregated per iteration
-     * and flushed to `opts.tokens` in the strategy's `finally` block so
-     * partial spend is preserved when the teacher throws mid-batch.
-     */
-    readonly reportCost: (tokens: number) => void;
-}
-interface BlindVariationOptions<T> {
-    /** Name — default: `"blindVariation"`. */
-    name?: string;
-    /** Number of candidates generated per iteration. Default: 4. */
-    width?: number;
-    /**
-     * Run teacher calls in parallel via `Promise.all`. Default `true` — the
-     * common case (independent LLM calls). Set `false` to run sequentially
-     * via `for/await` when teachers share stateful resources (rate limiters,
-     * rolling context, serial API ordering) that don't tolerate concurrency.
-     */
-    parallel?: boolean;
-    /**
-     * Optional cost counter node. Running total tokens reported via
-     * `ctx.reportCost` during each iteration is added to this node in the
-     * strategy's `finally` block — fires on success AND on teacher throw so
-     * partial spend is never lost. User owns the node; wire to `budgetGate`,
-     * `attachSnapshotStorage`, telemetry, etc.
-     */
-    tokens?: Node<number>;
-    /**
-     * Teacher — given `{prior, reportCost}`, produce one variant. Async
-     * allowed. Called `width` times per iteration. Call `ctx.reportCost(n)`
-     * to track tokens consumed per call (optional, no-op if `opts.tokens`
-     * is not set).
-     */
-    teacher: (ctx: BlindVariationContext<T>) => Promise<T> | T;
-}
-/**
- * Simplest built-in strategy: generate N variants per iteration via the
- * supplied `teacher`; no feedback-informed steering (equivalent to Random
- * Search). Validates the loop infrastructure end-to-end and is the baseline
- * every other strategy should outperform.
- *
- * `analyze` records the mean score and flags the worst task — strategies that
- * care about per-task critique layer on top.
- */
-declare function blindVariation<T>(opts: BlindVariationOptions<T>): RefineStrategy<T>;
-/**
- * Context passed to an `errorCritique` teacher. `critique` is the pre-formatted
- * summary a prompt template can drop in verbatim; `failures` carries the
- * structured evidence (per-task error / score / detail) for richer prompts.
- */
-interface ErrorCritiqueContext<T> {
-    readonly prior: T;
-    readonly critique: string;
-    readonly failures: readonly EvalResult[];
-    /**
-     * Report tokens consumed by this teacher call. Aggregated per iteration
-     * and flushed to `opts.tokens` in the strategy's `finally` block so
-     * partial spend is preserved when the teacher throws mid-batch.
-     */
-    readonly reportCost: (tokens: number) => void;
-}
-interface ErrorCritiqueOptions<T> {
-    /** Name — default: `"errorCritique"`. */
-    name?: string;
-    /** Number of candidates generated per iteration. Default: 4. */
-    width?: number;
-    /**
-     * Cut-off below which a task is classified as a failure and fed into the
-     * critique. Default: the batch mean — any task scoring below the batch
-     * mean is a failure. Pass a number for an absolute cut-off, or a function
-     * for per-batch computation (e.g. a percentile). When the default mean
-     * is non-finite (NaN / ±Infinity from a degenerate evaluator), ALL scores
-     * are treated as failures so the critique loop continues to steer.
-     */
-    failureThreshold?: number | ((scores: readonly EvalResult[]) => number);
-    /** Cap on failure samples packed into the critique. Default: 5. */
-    maxFailureSamples?: number;
-    /**
-     * Format failures into the `critique` string passed to the teacher. Default
-     * joins `- taskId (score=N) | error: …` lines. Override to shape LLM prompts.
-     *
-     * **Note:** the `feedback` argument is a shell with `{score, weakTasks}`
-     * populated; `summary` is empty because `analyze` computes the final summary
-     * AFTER `formatCritique` runs (the summary embeds the formatted count).
-     * Rely on `failures` and `feedback.score` — do not read `feedback.summary`
-     * here.
-     */
-    formatCritique?: (failures: readonly EvalResult[], feedback: Feedback) => string;
-    /**
-     * Run teacher calls in parallel via `Promise.all`. Default `true` — the
-     * common case (independent LLM calls). Set `false` to run sequentially
-     * via `for/await` when teachers share stateful resources (rate limiters,
-     * rolling context, serial API ordering) that don't tolerate concurrency.
-     */
-    parallel?: boolean;
-    /**
-     * Optional cost counter node. Running total tokens reported via
-     * `ctx.reportCost` during each iteration is added to this node in the
-     * strategy's `finally` block — fires on success AND on teacher throw so
-     * partial spend is never lost. User owns the node; wire to `budgetGate`,
-     * `attachSnapshotStorage`, telemetry, etc.
-     */
-    tokens?: Node<number>;
-    /**
-     * Teacher — given `{prior, critique, failures, reportCost}`, produce one
-     * refined variant. Called `width` times per iteration. Async allowed.
-     * Call `ctx.reportCost(n)` to track tokens consumed per call (optional,
-     * no-op if `opts.tokens` is not set).
-     */
-    teacher: (ctx: ErrorCritiqueContext<T>) => Promise<T> | T;
-}
-/**
- * Critique-driven strategy (ProTeGi-style "textual gradient"). Each iteration:
- *   1. `analyze` classifies tasks scoring below a threshold as failures, picks
- *      the best candidate from the batch, and packs both plus a formatted
- *      critique string into `feedback.critique` as a private payload.
- *   2. `generate` unpacks that payload and calls the teacher with
- *      `{prior, critique, failures, reportCost}` `width` times, returning the
- *      refined batch.
- *
- * The teacher receives a pre-formatted string (drop into an LLM prompt) AND
- * the structured failure list (for richer prompts that want per-task detail).
- * Throws on empty candidate batches — matches `blindVariation`'s contract
- * (no silent zero-candidate cycles).
- *
- * When `setStrategy()` swaps this strategy in mid-run, the first `generate`
- * may receive a `Feedback` produced by the prior strategy (no private payload);
- * the fallback path uses `candidates[last]` as the prior and the feedback
- * summary as the critique, so the loop keeps running without a stall. When a
- * private payload IS present, `priv.critiqueText` takes precedence over any
- * edits a caller made to `feedback.summary` — treat `critique` as the
- * strategy-owned channel.
- */
-declare function errorCritique<T>(opts: ErrorCritiqueOptions<T>): RefineStrategy<T>;
-
-type index_AnalyzeEvent<T> = AnalyzeEvent<T>;
-type index_BlindVariationContext<T> = BlindVariationContext<T>;
-type index_BlindVariationOptions<T> = BlindVariationOptions<T>;
-type index_ConvergenceOptions = ConvergenceOptions;
-type index_DatasetItem = DatasetItem;
-type index_DecideEvent = DecideEvent;
-type index_ErrorCritiqueContext<T> = ErrorCritiqueContext<T>;
-type index_ErrorCritiqueOptions<T> = ErrorCritiqueOptions<T>;
-type index_EvalResult = EvalResult;
-type index_EvaluateEvent<T> = EvaluateEvent<T>;
-type index_Evaluator<T> = Evaluator<T>;
-type index_Feedback = Feedback;
-type index_GenerateEvent<T> = GenerateEvent<T>;
-type index_Iteration<T> = Iteration<T>;
-type index_RefineLoopGraph<T> = RefineLoopGraph<T>;
-type index_RefineLoopOptions = RefineLoopOptions;
-type index_RefineStatus = RefineStatus;
-type index_RefineStrategy<T> = RefineStrategy<T>;
-declare const index_blindVariation: typeof blindVariation;
-declare const index_errorCritique: typeof errorCritique;
-declare const index_refineLoop: typeof refineLoop;
-declare namespace index {
-  export { type index_AnalyzeEvent as AnalyzeEvent, type index_BlindVariationContext as BlindVariationContext, type index_BlindVariationOptions as BlindVariationOptions, type index_ConvergenceOptions as ConvergenceOptions, type index_DatasetItem as DatasetItem, type index_DecideEvent as DecideEvent, type index_ErrorCritiqueContext as ErrorCritiqueContext, type index_ErrorCritiqueOptions as ErrorCritiqueOptions, type index_EvalResult as EvalResult, type index_EvaluateEvent as EvaluateEvent, type index_Evaluator as Evaluator, type index_Feedback as Feedback, type index_GenerateEvent as GenerateEvent, type index_Iteration as Iteration, type index_RefineLoopGraph as RefineLoopGraph, type index_RefineLoopOptions as RefineLoopOptions, type index_RefineStatus as RefineStatus, type index_RefineStrategy as RefineStrategy, index_blindVariation as blindVariation, index_errorCritique as errorCritique, index_refineLoop as refineLoop };
-}
-
-export { type AnalyzeEvent as A, type BlindVariationContext as B, type ConvergenceOptions as C, type DatasetItem as D, type Evaluator as E, type Feedback as F, type GenerateEvent as G, type Iteration as I, type RefineStrategy as R, type EvalResult as a, type RefineLoopOptions as b, type RefineStatus as c, type BlindVariationOptions as d, type DecideEvent as e, type ErrorCritiqueContext as f, type ErrorCritiqueOptions as g, type EvaluateEvent as h, index as i, type RefineLoopGraph as j, blindVariation as k, errorCritique as l, refineLoop as r };