@graphrefly/graphrefly 0.27.0 → 0.29.0

package/dist/index-DwjJGKxV.d.ts

@@ -0,0 +1,357 @@
+import { a as Node } from './node-Dd6wHSib.js';
+import { NodeInput } from './extra/sources.js';
+import { a as GraphOptions, G as Graph } from './graph-Qjg9gWHI.js';
+import { T as TopicGraph } from './index-DuB5aO4-.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 attachStorage: 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.
+ */
+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`, `attachStorage`, `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`,
+     * `attachStorage`, 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`,
+     * `attachStorage`, 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 RefineStatus as b, type RefineLoopOptions 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 };

package/dist/{index-B6EhDnjH.d.cts → index-H_oxVec5.d.cts}

@@ -1,4 +1,4 @@
-import { a as Graph } from './graph-DNCrvZSn.cjs';
+import { G as Graph } from './graph-DgohqXK-.cjs';
 
 /** Zustand-compatible Store API. */
 interface StoreApi<T> {

package/dist/{index-3lsddbbS.d.ts → index-IMAHq-ia.d.ts}

@@ -1,4 +1,4 @@
-import { N as Node } from './node-BmerH3kS.js';
+import { a as Node } from './node-Dd6wHSib.js';
 
 /**
  * Options for creating an atom.

package/dist/{index-B1tloyhO.d.cts → index-U1nir7MX.d.cts}

@@ -1,5 +1,5 @@
 import { Ref, WatchSource } from 'vue';
-import { N as Node } from './node-BmerH3kS.cjs';
+import { a as Node } from './node-Dd6wHSib.cjs';
 
 /**
  * Subscribe to a read-only `Node<T>` as a Vue `Ref<T>`. Auto-unsubscribes on scope disposal.

package/dist/index-Vg7tORgk.d.ts

@@ -0,0 +1,86 @@
+import { a as Node } from './node-Dd6wHSib.js';
+import { G as Graph, a as GraphOptions } from './graph-Qjg9gWHI.js';
+
+/**
+ * Job queue patterns (roadmap §4.2).
+ *
+ * Queue / flow primitives modeled as graph factories:
+ * - `jobQueue()` — claim/ack/nack workflow with reactive depth.
+ * - `jobFlow()` — multi-stage queue chain.
+ *
+ * Topic / subscription / hub primitives live in `patterns/messaging`.
+ */
+
+type JobState = "queued" | "inflight";
+type JobEnvelope<T> = {
+    id: string;
+    payload: T;
+    attempts: number;
+    metadata: Readonly<Record<string, unknown>>;
+    state: JobState;
+};
+type JobQueueOptions = {
+    graph?: GraphOptions;
+};
+declare class JobQueueGraph<T> extends Graph {
+    private readonly _pending;
+    private readonly _jobs;
+    private _seq;
+    readonly pending: Node<readonly string[]>;
+    readonly jobs: Node<ReadonlyMap<string, JobEnvelope<T>>>;
+    readonly depth: Node<number>;
+    constructor(name: string, opts?: JobQueueOptions);
+    enqueue(payload: T, opts?: {
+        id?: string;
+        metadata?: Record<string, unknown>;
+    }): string;
+    claim(limit?: number): readonly JobEnvelope<T>[];
+    ack(id: string): boolean;
+    nack(id: string, opts?: {
+        requeue?: boolean;
+    }): boolean;
+}
+type JobFlowOptions = {
+    graph?: GraphOptions;
+    stages?: readonly string[];
+    maxPerPump?: number;
+};
+declare class JobFlowGraph<T> extends Graph {
+    private readonly _stageNames;
+    private readonly _queues;
+    private readonly _completed;
+    readonly completed: Node<readonly JobEnvelope<T>[]>;
+    readonly completedCount: Node<number>;
+    constructor(name: string, opts?: JobFlowOptions);
+    stages(): readonly string[];
+    queue(stage: string): JobQueueGraph<T>;
+    enqueue(payload: T, opts?: {
+        id?: string;
+        metadata?: Record<string, unknown>;
+    }): string;
+    retainedCompleted(): readonly JobEnvelope<T>[];
+}
+/**
+ * Creates a Pulsar-inspired job queue graph with claim/ack/nack workflow.
+ */
+declare function jobQueue<T>(name: string, opts?: JobQueueOptions): JobQueueGraph<T>;
+/**
+ * Creates an autonomous multi-stage queue chain graph.
+ */
+declare function jobFlow<T>(name: string, opts?: JobFlowOptions): JobFlowGraph<T>;
+
+type index_JobEnvelope<T> = JobEnvelope<T>;
+type index_JobFlowGraph<T> = JobFlowGraph<T>;
+declare const index_JobFlowGraph: typeof JobFlowGraph;
+type index_JobFlowOptions = JobFlowOptions;
+type index_JobQueueGraph<T> = JobQueueGraph<T>;
+declare const index_JobQueueGraph: typeof JobQueueGraph;
+type index_JobQueueOptions = JobQueueOptions;
+type index_JobState = JobState;
+declare const index_jobFlow: typeof jobFlow;
+declare const index_jobQueue: typeof jobQueue;
+declare namespace index {
+  export { type index_JobEnvelope as JobEnvelope, index_JobFlowGraph as JobFlowGraph, type index_JobFlowOptions as JobFlowOptions, index_JobQueueGraph as JobQueueGraph, type index_JobQueueOptions as JobQueueOptions, type index_JobState as JobState, index_jobFlow as jobFlow, index_jobQueue as jobQueue };
+}
+
+export { type JobEnvelope as J, JobFlowGraph as a, type JobFlowOptions as b, JobQueueGraph as c, type JobQueueOptions as d, type JobState as e, jobQueue as f, index as i, jobFlow as j };