darwin-agents 0.4.9 → 0.5.0-alpha.2

package/dist/src/evolution/pareto.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Darwin — Pareto-Front Selection (Phase 2 A2, S1185 follow-up).
+ *
+ * Pure functions for multi-objective optimization in the GEPA-style
+ * reflective optimizer. The classic Pareto definition:
+ *
+ *   A "dominates" B iff:
+ *     - For ALL objectives O: A[O] is at least as good as B[O].
+ *     - For at LEAST ONE objective O: A[O] is strictly better than B[O].
+ *
+ *   A "non-dominated" variant is one that is not dominated by any other.
+ *   The non-dominated set is the Pareto front.
+ *
+ * This module is **pure** — no LLM calls, no I/O, no Date.now(). Tests
+ * are fully deterministic.
+ *
+ * Reference: GEPA (Genetic-Pareto) reflective optimizer
+ * https://gepa-ai.github.io/gepa/ — Pareto-efficient search over text
+ * components with LLM-guided reflection.
+ */
+/**
+ * One objective in a multi-objective Pareto comparison.
+ *
+ * @example
+ *   import type { DarwinMetrics } from "darwin-agents";
+ *   const objectives: ParetoObjective<DarwinMetrics>[] = [
+ *     { key: "qualityScore", direction: "maximize" },
+ *     { key: "sourceCount",  direction: "maximize" },
+ *     { key: "durationMs",   direction: "minimize" },
+ *     { key: "outputLength", direction: "maximize" },
+ *   ];
+ *
+ * Or use the pre-built {@link DARWIN_DEFAULT_OBJECTIVES} constant.
+ */
+export interface ParetoObjective<T> {
+    /** Field on the variant to compare. Must hold a finite number. */
+    key: keyof T;
+    /**
+     * `"maximize"` if higher = better (qualityScore, sourceCount).
+     * `"minimize"` if lower = better (durationMs, cost).
+     */
+    direction: "maximize" | "minimize";
+    /**
+     * Optional weight for tie-breaking scalarisation only — does NOT
+     * affect strict Pareto dominance. Default 1.
+     *
+     * **Scale warning (S1185 R1 Critic Finding M4):** weights operate on
+     * the raw objective values. If your objectives have very different
+     * scales (e.g. cost in dollars 0-10000 vs success-rate 0-1), the
+     * larger-scale objective dominates the scalarised sum regardless of
+     * weight. Pre-normalise your objectives to comparable ranges before
+     * relying on {@link paretoSelect}'s truncation step. Strict
+     * dominance ({@link dominates}, {@link nonDominatedFront}) is
+     * unaffected — per-dimension comparison handles scale correctly.
+     */
+    weight?: number;
+}
+/**
+ * Pre-built objective set matching `DarwinMetrics` field names.
+ *
+ * Drop-in default for `paretoSelect`/`GepaOptimizer.nextGeneration`
+ * when you optimise the standard Darwin metrics. Note that
+ * `outputLength` is direction `"maximize"` because Darwin uses output
+ * length as a proxy for completeness/depth in its existing weight
+ * scheme — if your domain treats long outputs as worse, override the
+ * direction in a custom array.
+ */
+export declare const DARWIN_DEFAULT_OBJECTIVES: ReadonlyArray<ParetoObjective<{
+    qualityScore: number;
+    sourceCount: number;
+    durationMs: number;
+    outputLength: number;
+}>>;
+/**
+ * True iff `a` Pareto-dominates `b` over the given objectives.
+ *
+ * Returns false if either side has a non-finite value for any objective
+ * (NaN/Infinity are treated as "not comparable" — defensive against
+ * malformed variants poisoning the front).
+ */
+export declare function dominates<T extends Record<string, unknown>>(a: T, b: T, objectives: ReadonlyArray<ParetoObjective<T>>): boolean;
+/**
+ * Return the subset of `variants` that are NOT dominated by any other
+ * variant in the set. This is the Pareto front.
+ *
+ * Empty input → empty output. Single variant → that variant. Naive
+ * O(N²) implementation which is fine for the N≤20 variant pools the
+ * GEPA optimizer works with.
+ *
+ * Duplicates (identical objective vectors) are all kept — no variant
+ * dominates an identical one (strictlyBetterSomewhere stays false).
+ */
+export declare function nonDominatedFront<T extends Record<string, unknown>>(variants: ReadonlyArray<T>, objectives: ReadonlyArray<ParetoObjective<T>>): T[];
+/**
+ * Scalarise a variant to a single number for tie-breaking. Sum of
+ * normalised direction-adjusted values × weight. NOT used for strict
+ * Pareto dominance — only when a fixed-size pick is needed after the
+ * front is identified (e.g. carrying 3 best forward to next GEPA
+ * generation).
+ *
+ * Non-finite values contribute 0 (defensive).
+ */
+export declare function scalarise<T extends Record<string, unknown>>(variant: T, objectives: ReadonlyArray<ParetoObjective<T>>): number;
+/**
+ * Pareto-select up to `maxKeep` variants:
+ *   1. Compute non-dominated front.
+ *   2. If front size ≤ maxKeep: return front.
+ *   3. If front size > maxKeep: sort by scalarised score (descending),
+ *      keep top maxKeep.
+ *
+ * Use this when the GEPA generation budget is fixed (e.g. carry exactly
+ * 3 variants to the next round) but the Pareto front happens to be
+ * larger.
+ */
+export declare function paretoSelect<T extends Record<string, unknown>>(variants: ReadonlyArray<T>, objectives: ReadonlyArray<ParetoObjective<T>>, maxKeep?: number): T[];
+//# sourceMappingURL=pareto.d.ts.map

package/dist/src/evolution/pareto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pareto.d.ts","sourceRoot":"","sources":["../../../src/evolution/pareto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC,CAAC;IACb;;;OAGG;IACH,SAAS,EAAE,UAAU,GAAG,UAAU,CAAC;IACnC;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,EAAE,aAAa,CAAC,eAAe,CAAC;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC,CAKD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,CAAC,EAAE,CAAC,EACJ,CAAC,EAAE,CAAC,EACJ,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,GAC5C,OAAO,CAeT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,GAC5C,CAAC,EAAE,CAoBL;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,OAAO,EAAE,CAAC,EACV,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,GAC5C,MAAM,CAUR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,EAC7C,OAAO,CAAC,EAAE,MAAM,GACf,CAAC,EAAE,CAML"}

package/dist/src/evolution/pareto.js

@@ -0,0 +1,140 @@
+/**
+ * Darwin — Pareto-Front Selection (Phase 2 A2, S1185 follow-up).
+ *
+ * Pure functions for multi-objective optimization in the GEPA-style
+ * reflective optimizer. The classic Pareto definition:
+ *
+ *   A "dominates" B iff:
+ *     - For ALL objectives O: A[O] is at least as good as B[O].
+ *     - For at LEAST ONE objective O: A[O] is strictly better than B[O].
+ *
+ *   A "non-dominated" variant is one that is not dominated by any other.
+ *   The non-dominated set is the Pareto front.
+ *
+ * This module is **pure** — no LLM calls, no I/O, no Date.now(). Tests
+ * are fully deterministic.
+ *
+ * Reference: GEPA (Genetic-Pareto) reflective optimizer
+ * https://gepa-ai.github.io/gepa/ — Pareto-efficient search over text
+ * components with LLM-guided reflection.
+ */
+/**
+ * Pre-built objective set matching `DarwinMetrics` field names.
+ *
+ * Drop-in default for `paretoSelect`/`GepaOptimizer.nextGeneration`
+ * when you optimise the standard Darwin metrics. Note that
+ * `outputLength` is direction `"maximize"` because Darwin uses output
+ * length as a proxy for completeness/depth in its existing weight
+ * scheme — if your domain treats long outputs as worse, override the
+ * direction in a custom array.
+ */
+export const DARWIN_DEFAULT_OBJECTIVES = [
+    { key: "qualityScore", direction: "maximize", weight: 0.5 },
+    { key: "sourceCount", direction: "maximize", weight: 0.15 },
+    { key: "outputLength", direction: "maximize", weight: 0.1 },
+    { key: "durationMs", direction: "minimize", weight: 0.25 },
+];
+/**
+ * True iff `a` Pareto-dominates `b` over the given objectives.
+ *
+ * Returns false if either side has a non-finite value for any objective
+ * (NaN/Infinity are treated as "not comparable" — defensive against
+ * malformed variants poisoning the front).
+ */
+export function dominates(a, b, objectives) {
+    if (objectives.length === 0)
+        return false;
+    let strictlyBetterSomewhere = false;
+    for (const obj of objectives) {
+        const av = a[obj.key];
+        const bv = b[obj.key];
+        if (typeof av !== "number" || typeof bv !== "number")
+            return false;
+        if (!Number.isFinite(av) || !Number.isFinite(bv))
+            return false;
+        // Normalise direction so "better" is always ">" in comparison.
+        const aNorm = obj.direction === "maximize" ? av : -av;
+        const bNorm = obj.direction === "maximize" ? bv : -bv;
+        if (aNorm < bNorm)
+            return false; // a is worse on this objective → not dominating
+        if (aNorm > bNorm)
+            strictlyBetterSomewhere = true;
+    }
+    return strictlyBetterSomewhere;
+}
+/**
+ * Return the subset of `variants` that are NOT dominated by any other
+ * variant in the set. This is the Pareto front.
+ *
+ * Empty input → empty output. Single variant → that variant. Naive
+ * O(N²) implementation which is fine for the N≤20 variant pools the
+ * GEPA optimizer works with.
+ *
+ * Duplicates (identical objective vectors) are all kept — no variant
+ * dominates an identical one (strictlyBetterSomewhere stays false).
+ */
+export function nonDominatedFront(variants, objectives) {
+    if (variants.length === 0)
+        return [];
+    if (objectives.length === 0) {
+        // Without objectives no variant dominates any other — keep all.
+        return [...variants];
+    }
+    const result = [];
+    for (let i = 0; i < variants.length; i++) {
+        const candidate = variants[i];
+        let dominated = false;
+        for (let j = 0; j < variants.length; j++) {
+            if (i === j)
+                continue;
+            if (dominates(variants[j], candidate, objectives)) {
+                dominated = true;
+                break;
+            }
+        }
+        if (!dominated)
+            result.push(candidate);
+    }
+    return result;
+}
+/**
+ * Scalarise a variant to a single number for tie-breaking. Sum of
+ * normalised direction-adjusted values × weight. NOT used for strict
+ * Pareto dominance — only when a fixed-size pick is needed after the
+ * front is identified (e.g. carrying 3 best forward to next GEPA
+ * generation).
+ *
+ * Non-finite values contribute 0 (defensive).
+ */
+export function scalarise(variant, objectives) {
+    let total = 0;
+    for (const obj of objectives) {
+        const v = variant[obj.key];
+        if (typeof v !== "number" || !Number.isFinite(v))
+            continue;
+        const weight = obj.weight ?? 1;
+        const directionAdjusted = obj.direction === "maximize" ? v : -v;
+        total += directionAdjusted * weight;
+    }
+    return total;
+}
+/**
+ * Pareto-select up to `maxKeep` variants:
+ *   1. Compute non-dominated front.
+ *   2. If front size ≤ maxKeep: return front.
+ *   3. If front size > maxKeep: sort by scalarised score (descending),
+ *      keep top maxKeep.
+ *
+ * Use this when the GEPA generation budget is fixed (e.g. carry exactly
+ * 3 variants to the next round) but the Pareto front happens to be
+ * larger.
+ */
+export function paretoSelect(variants, objectives, maxKeep) {
+    const front = nonDominatedFront(variants, objectives);
+    if (typeof maxKeep !== "number" || front.length <= maxKeep)
+        return front;
+    return [...front]
+        .sort((a, b) => scalarise(b, objectives) - scalarise(a, objectives))
+        .slice(0, maxKeep);
+}
+//# sourceMappingURL=pareto.js.map

package/dist/src/evolution/pareto.js.map

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

package/dist/src/evolution/reflector.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Darwin — Reflective Text Feedback (Phase 2 A2, S1185 follow-up).
+ *
+ * GEPA's signature insight: instead of guiding mutation by a single
+ * scalar reward, give the optimizer rich TEXT feedback ("what went
+ * wrong, what to fix, what NOT to change") and let it synthesise the
+ * mutation from that feedback.
+ *
+ * This module is a pure TS port of the GEPA-style reflector — no
+ * Python sidecar, no hard dep on `@gepa-ai/gepa`. The reflector takes
+ * a current prompt + a set of (variant, score, trace) feedbacks and
+ * asks an injected LLM to write a SMALLEST-POSSIBLE-EDIT mutation of
+ * the current prompt that addresses the failure modes.
+ *
+ * Reference snippet from GEPA docs:
+ *
+ *   "Make the smallest possible targeted edit to fix the identified
+ *    failure mode. Preserve all existing correct behavior. Do not
+ *    rewrite from scratch."
+ *
+ * The module is composable with the existing `PromptOptimizer` —
+ * `GepaOptimizer` (next file) coordinates Reflector + paretoSelect into
+ * a generation loop. The reflector itself is single-shot.
+ *
+ * **Inspired by, not lifted from** the official `gepa-ai/gepa` Python
+ * library. This is a pure TS port of GEPA's core ideas (Pareto-front +
+ * reflective mutation) — see `optimizer-gepa.ts` for the deliberate
+ * deviations from Algorithm 1/2 of the GEPA paper (arxiv 2507.19457).
+ * For a feature-complete GEPA experience use the upstream Python tool.
+ *
+ * **Single-LM design note (R1 Research Finding F7, S1185):** GEPA's
+ * official guidance is to use a STRONGER LM for reflection than for
+ * task execution (their `reflection_lm` parameter). This adapter
+ * intentionally accepts only one injected `RunPromptFn` to keep the
+ * V0.5 alpha surface minimal. Stronger-reflection-LM support
+ * (`reflectionRunPrompt` override) is deferred to V0.5.1 — pass a
+ * higher-tier model in your single `runPrompt` callback as a workaround.
+ */
+import type { ExecutionTrace } from "../types.js";
+import type { RunPromptFn } from "./run-prompt-fn.js";
+export type { RunPromptFn };
+/** One variant's evaluation feedback, fed into the reflector. */
+export interface ReflectiveFeedback {
+    /** Identifier of the variant this feedback refers to (e.g. "v3"). */
+    variantId: string;
+    /** Scalar score for at-a-glance ranking. */
+    score: number;
+    /**
+     * Rich text feedback describing what went well, what failed, and
+     * (ideally) WHY. The richer this is, the better the mutation. GEPA
+     * docs recommend including: expected vs. actual, specific issue
+     * analysis, and any provider-side error class.
+     */
+    textFeedback: string;
+    /** Optional execution trace (A1 trajectory) for tool-level context. */
+    trace?: ExecutionTrace;
+    /** Optional: the variant's prompt text itself (helps the reflector compare). */
+    variantPrompt?: string;
+}
+/**
+ * Options accepted by {@link Reflector#reflect}.
+ */
+export interface ReflectOptions {
+    /**
+     * Override the reflection prompt template. Default is GEPA's
+     * "smallest possible targeted edit" template. Use a custom template
+     * when you want different mutation pressure (e.g. exploratory vs.
+     * conservative).
+     */
+    reflectionPromptTemplate?: string;
+    /**
+     * Max characters of `textFeedback` included per variant. Default
+     * 2000 — keeps the meta-prompt under typical context windows even
+     * with N=5 variants.
+     */
+    feedbackCap?: number;
+    /**
+     * Hard upper bound on the returned mutated-prompt length. Default
+     * `Math.max(currentPrompt.length * 1.3, 3500)` — same growth ceiling
+     * as `PromptOptimizer.generateVariant` for symmetry.
+     */
+    maxMutationLength?: number;
+}
+/**
+ * Single-shot reflector. Wraps one LLM call that takes the current
+ * prompt + per-variant feedback and returns a mutated prompt.
+ */
+export declare class Reflector {
+    private readonly runPrompt;
+    constructor(runPrompt: RunPromptFn);
+    /**
+     * Build a reflection meta-prompt and ask the injected LLM for a
+     * mutated prompt. Returns the mutated prompt text (cleaned + capped).
+     *
+     * Throws `TypeError` if `currentPrompt` is empty or `feedbacks` is
+     * empty — meaningless inputs are a programmer bug, not a runtime
+     * edge.
+     */
+    reflect(currentPrompt: string, feedbacks: ReadonlyArray<ReflectiveFeedback>, opts?: ReflectOptions): Promise<string>;
+    /** Single-feedback formatter. */
+    private formatFeedback;
+    /** Strip markdown fences and leading/trailing whitespace. */
+    private cleanOutput;
+    /** Truncate at the last sentence/newline boundary within `maxLength`. */
+    private truncateAtSentenceBoundary;
+}
+//# sourceMappingURL=reflector.d.ts.map

package/dist/src/evolution/reflector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflector.d.ts","sourceRoot":"","sources":["../../../src/evolution/reflector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAKtD,YAAY,EAAE,WAAW,EAAE,CAAC;AAE5B,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAsBD;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;gBAE5B,SAAS,EAAE,WAAW;IAOlC;;;;;;;OAOG;IACG,OAAO,CACX,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,aAAa,CAAC,kBAAkB,CAAC,EAC5C,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,MAAM,CAAC;IA+ClB,iCAAiC;IACjC,OAAO,CAAC,cAAc;IA2BtB,6DAA6D;IAC7D,OAAO,CAAC,WAAW;IAQnB,yEAAyE;IACzE,OAAO,CAAC,0BAA0B;CAUnC"}

package/dist/src/evolution/reflector.js

@@ -0,0 +1,158 @@
+/**
+ * Darwin — Reflective Text Feedback (Phase 2 A2, S1185 follow-up).
+ *
+ * GEPA's signature insight: instead of guiding mutation by a single
+ * scalar reward, give the optimizer rich TEXT feedback ("what went
+ * wrong, what to fix, what NOT to change") and let it synthesise the
+ * mutation from that feedback.
+ *
+ * This module is a pure TS port of the GEPA-style reflector — no
+ * Python sidecar, no hard dep on `@gepa-ai/gepa`. The reflector takes
+ * a current prompt + a set of (variant, score, trace) feedbacks and
+ * asks an injected LLM to write a SMALLEST-POSSIBLE-EDIT mutation of
+ * the current prompt that addresses the failure modes.
+ *
+ * Reference snippet from GEPA docs:
+ *
+ *   "Make the smallest possible targeted edit to fix the identified
+ *    failure mode. Preserve all existing correct behavior. Do not
+ *    rewrite from scratch."
+ *
+ * The module is composable with the existing `PromptOptimizer` —
+ * `GepaOptimizer` (next file) coordinates Reflector + paretoSelect into
+ * a generation loop. The reflector itself is single-shot.
+ *
+ * **Inspired by, not lifted from** the official `gepa-ai/gepa` Python
+ * library. This is a pure TS port of GEPA's core ideas (Pareto-front +
+ * reflective mutation) — see `optimizer-gepa.ts` for the deliberate
+ * deviations from Algorithm 1/2 of the GEPA paper (arxiv 2507.19457).
+ * For a feature-complete GEPA experience use the upstream Python tool.
+ *
+ * **Single-LM design note (R1 Research Finding F7, S1185):** GEPA's
+ * official guidance is to use a STRONGER LM for reflection than for
+ * task execution (their `reflection_lm` parameter). This adapter
+ * intentionally accepts only one injected `RunPromptFn` to keep the
+ * V0.5 alpha surface minimal. Stronger-reflection-LM support
+ * (`reflectionRunPrompt` override) is deferred to V0.5.1 — pass a
+ * higher-tier model in your single `runPrompt` callback as a workaround.
+ */
+const DEFAULT_FEEDBACK_CAP = 2000;
+const DEFAULT_REFLECTION_TEMPLATE = `
+You are a prompt-engineering reflector. Below is an instruction prompt followed by feedback from {N} variant evaluations.
+
+CURRENT INSTRUCTION:
+\`\`\`
+{CURRENT_PROMPT}
+\`\`\`
+
+VARIANT FEEDBACKS:
+{FEEDBACKS}
+
+Task: produce the SMALLEST POSSIBLE TARGETED EDIT of the CURRENT INSTRUCTION that:
+  - addresses the lowest-scoring failure modes identified above,
+  - preserves all existing correct behavior (do NOT rewrite from scratch),
+  - keeps the same overall length envelope (no growth beyond ~30%).
+
+Return ONLY the updated instruction text. No prose, no explanations, no markdown fences.
+`.trim();
+/**
+ * Single-shot reflector. Wraps one LLM call that takes the current
+ * prompt + per-variant feedback and returns a mutated prompt.
+ */
+export class Reflector {
+    runPrompt;
+    constructor(runPrompt) {
+        if (typeof runPrompt !== "function") {
+            throw new TypeError("Reflector: runPrompt must be a function");
+        }
+        this.runPrompt = runPrompt;
+    }
+    /**
+     * Build a reflection meta-prompt and ask the injected LLM for a
+     * mutated prompt. Returns the mutated prompt text (cleaned + capped).
+     *
+     * Throws `TypeError` if `currentPrompt` is empty or `feedbacks` is
+     * empty — meaningless inputs are a programmer bug, not a runtime
+     * edge.
+     */
+    async reflect(currentPrompt, feedbacks, opts = {}) {
+        if (typeof currentPrompt !== "string" || currentPrompt.length === 0) {
+            throw new TypeError("Reflector.reflect: currentPrompt must be a non-empty string");
+        }
+        if (feedbacks.length === 0) {
+            throw new TypeError("Reflector.reflect: feedbacks must contain at least one entry");
+        }
+        const template = opts.reflectionPromptTemplate ?? DEFAULT_REFLECTION_TEMPLATE;
+        // R1 V0.5.0-alpha.2 Critic Finding H2 + R2 Critic Finding R2-C1
+        // (S1185): clamp feedbackCap to a positive finite integer.
+        // `Math.max(1, Math.floor(NaN))` is `NaN` — would silently zero
+        // every feedback (`slice(0, NaN) === ""`). Explicit `Number.isFinite`
+        // guard rejects NaN/Infinity and falls back to the default.
+        const rawCap = opts.feedbackCap ?? DEFAULT_FEEDBACK_CAP;
+        const cap = Number.isFinite(rawCap) && rawCap > 0
+            ? Math.floor(rawCap)
+            : DEFAULT_FEEDBACK_CAP;
+        const feedbackBlock = feedbacks
+            .map((f, i) => this.formatFeedback(f, i + 1, cap))
+            .join("\n\n");
+        // R1 V0.5.0-alpha.2 Critic Finding H1 (S1185): substitute
+        // `{CURRENT_PROMPT}` LAST so a user prompt that happens to contain
+        // `{N}` or `{FEEDBACKS}` literally cannot trigger double-substitution.
+        // String.prototype.replace replaces only the first occurrence — by
+        // ordering the user-controlled substitution last, no template-injection
+        // path remains.
+        const metaPrompt = template
+            .replace("{N}", String(feedbacks.length))
+            .replace("{FEEDBACKS}", feedbackBlock)
+            .replace("{CURRENT_PROMPT}", currentPrompt);
+        let mutated = await this.runPrompt(metaPrompt);
+        mutated = this.cleanOutput(mutated);
+        const maxLength = opts.maxMutationLength ?? Math.max(Math.round(currentPrompt.length * 1.3), 3500);
+        if (mutated.length > maxLength) {
+            mutated = this.truncateAtSentenceBoundary(mutated, maxLength);
+        }
+        return mutated;
+    }
+    /** Single-feedback formatter. */
+    formatFeedback(fb, index, cap) {
+        const cappedText = fb.textFeedback.length > cap
+            ? fb.textFeedback.slice(0, cap) + "\n[...truncated]"
+            : fb.textFeedback;
+        const lines = [
+            `=== Variant ${index} — ${fb.variantId} (score ${fb.score.toFixed(2)}) ===`,
+            `Feedback:`,
+            cappedText,
+        ];
+        if (fb.trace) {
+            const toolNames = Array.from(new Set((fb.trace.toolCalls ?? []).map((c) => c.tool))).slice(0, 5);
+            if (toolNames.length > 0) {
+                lines.push(`Trace summary: ${fb.trace.turnCount} turns, ` +
+                    `${fb.trace.toolCalls?.length ?? 0} tool calls (top: ${toolNames.join(", ")}), ` +
+                    `${fb.trace.errors?.length ?? 0} errors.`);
+            }
+        }
+        return lines.join("\n");
+    }
+    /** Strip markdown fences and leading/trailing whitespace. */
+    cleanOutput(raw) {
+        let out = raw.trim();
+        // Strip ```...``` fences if the LLM ignored "no fences"
+        const fence = out.match(/^```[a-z]*\n?([\s\S]*?)\n?```$/i);
+        if (fence)
+            out = fence[1].trim();
+        return out;
+    }
+    /** Truncate at the last sentence/newline boundary within `maxLength`. */
+    truncateAtSentenceBoundary(text, maxLength) {
+        if (text.length <= maxLength)
+            return text;
+        const truncated = text.slice(0, maxLength);
+        const lastPeriod = truncated.lastIndexOf(".");
+        const lastNewline = truncated.lastIndexOf("\n");
+        const cutPoint = Math.max(lastPeriod, lastNewline);
+        return cutPoint > maxLength * 0.7
+            ? truncated.slice(0, cutPoint + 1)
+            : truncated;
+    }
+}
+//# sourceMappingURL=reflector.js.map

package/dist/src/evolution/reflector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflector.js","sourceRoot":"","sources":["../../../src/evolution/reflector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAsDH,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAClC,MAAM,2BAA2B,GAAG;;;;;;;;;;;;;;;;;CAiBnC,CAAC,IAAI,EAAE,CAAC;AAET;;;GAGG;AACH,MAAM,OAAO,SAAS;IACH,SAAS,CAAc;IAExC,YAAY,SAAsB;QAChC,IAAI,OAAO,SAAS,KAAK,UAAU,EAAE,CAAC;YACpC,MAAM,IAAI,SAAS,CAAC,yCAAyC,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CACX,aAAqB,EACrB,SAA4C,EAC5C,OAAuB,EAAE;QAEzB,IAAI,OAAO,aAAa,KAAK,QAAQ,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpE,MAAM,IAAI,SAAS,CAAC,6DAA6D,CAAC,CAAC;QACrF,CAAC;QACD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,SAAS,CAAC,8DAA8D,CAAC,CAAC;QACtF,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,wBAAwB,IAAI,2BAA2B,CAAC;QAC9E,gEAAgE;QAChE,2DAA2D;QAC3D,gEAAgE;QAChE,sEAAsE;QACtE,4DAA4D;QAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,IAAI,oBAAoB,CAAC;QACxD,MAAM,GAAG,GACP,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC;YACnC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;YACpB,CAAC,CAAC,oBAAoB,CAAC;QAE3B,MAAM,aAAa,GAAG,SAAS;aAC5B,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;aACjD,IAAI,CAAC,MAAM,CAAC,CAAC;QAEhB,0DAA0D;QAC1D,mEAAmE;QACnE,uEAAuE;QACvE,mEAAmE;QACnE,wEAAwE;QACxE,gBAAgB;QAChB,MAAM,UAAU,GAAG,QAAQ;aACxB,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;aACxC,OAAO,CAAC,aAAa,EAAE,aAAa,CAAC;aACrC,OAAO,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;QAE9C,IAAI,OAAO,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QAC/C,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAEpC,MAAM,SAAS,GACb,IAAI,CAAC,iBAAiB,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,GAAG,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;QACnF,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;YAC/B,OAAO,GAAG,IAAI,CAAC,0BAA0B,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAChE,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,iCAAiC;IACzB,cAAc,CACpB,EAAsB,EACtB,KAAa,EACb,GAAW;QAEX,MAAM,UAAU,GACd,EAAE,CAAC,YAAY,CAAC,MAAM,GAAG,GAAG;YAC1B,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,kBAAkB;YACpD,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC;QACtB,MAAM,KAAK,GAAa;YACtB,eAAe,KAAK,MAAM,EAAE,CAAC,SAAS,WAAW,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO;YAC3E,WAAW;YACX,UAAU;SACX,CAAC;QACF,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;YACb,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAC1B,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CACvD,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YACd,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACzB,KAAK,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC,KAAK,CAAC,SAAS,UAAU;oBACvD,GAAG,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC,qBAAqB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;oBAChF,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC,UAAU,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,6DAA6D;IACrD,WAAW,CAAC,GAAW;QAC7B,IAAI,GAAG,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QACrB,wDAAwD;QACxD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;QAC3D,IAAI,KAAK;YAAE,GAAG,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC;QAClC,OAAO,GAAG,CAAC;IACb,CAAC;IAED,yEAAyE;IACjE,0BAA0B,CAAC,IAAY,EAAE,SAAiB;QAChE,IAAI,IAAI,CAAC,MAAM,IAAI,SAAS;YAAE,OAAO,IAAI,CAAC;QAC1C,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QAC3C,MAAM,UAAU,GAAG,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAC9C,MAAM,WAAW,GAAG,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;QACnD,OAAO,QAAQ,GAAG,SAAS,GAAG,GAAG;YAC/B,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,GAAG,CAAC,CAAC;YAClC,CAAC,CAAC,SAAS,CAAC;IAChB,CAAC;CACF"}

package/dist/src/evolution/run-prompt-fn.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared type for LLM-call injection.
+ *
+ * Both `PromptOptimizer` and `Reflector` accept an injected function
+ * with this signature so the optimizer/reflector stays provider-agnostic.
+ * Extracted to its own file (S1185 R1 Analyst Finding A1) so the
+ * signature has a single source of truth — future evolution
+ * (e.g. adding an `options` param) updates one declaration, not two.
+ */
+export type RunPromptFn = (prompt: string) => Promise<string>;
+//# sourceMappingURL=run-prompt-fn.d.ts.map

package/dist/src/evolution/run-prompt-fn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-prompt-fn.d.ts","sourceRoot":"","sources":["../../../src/evolution/run-prompt-fn.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC"}

package/dist/src/evolution/run-prompt-fn.js

@@ -0,0 +1,11 @@
+/**
+ * Shared type for LLM-call injection.
+ *
+ * Both `PromptOptimizer` and `Reflector` accept an injected function
+ * with this signature so the optimizer/reflector stays provider-agnostic.
+ * Extracted to its own file (S1185 R1 Analyst Finding A1) so the
+ * signature has a single source of truth — future evolution
+ * (e.g. adding an `options` param) updates one declaration, not two.
+ */
+export {};
+//# sourceMappingURL=run-prompt-fn.js.map

package/dist/src/evolution/run-prompt-fn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-prompt-fn.js","sourceRoot":"","sources":["../../../src/evolution/run-prompt-fn.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/src/index.d.ts

@@ -17,7 +17,9 @@
  */
 export { defineAgent, defineConfig, loadConfig, loadConfigSync } from './core/agent.js';
 export { runAgent } from './core/runner.js';
-export type { AgentDefinition, DarwinConfig, DarwinExperiment, DarwinMetrics, DarwinPattern, DarwinState, ExperimentFeedback, EvolutionConfig, Learning, McpServerConfig, MemoryProvider, MetricWeights, PromptVersion, PromptVersionStats, RunResult, SafetyThresholds, } from './types.js';
+export { createTraceCapture } from './core/trace-capture.js';
+export type { TraceCapture, TraceCaptureOptions } from './core/trace-capture.js';
+export type { AgentDefinition, DarwinConfig, DarwinExperiment, DarwinMetrics, DarwinPattern, DarwinState, ExecutionTrace, ExperimentFeedback, EvolutionConfig, Learning, McpServerConfig, MemoryProvider, MetricWeights, PromptVersion, PromptVersionStats, RunResult, SafetyThresholds, TraceToolCall, TraceTokenUsage, TraceTurnError, } from './types.js';
 export { DEFAULT_WEIGHTS, DEFAULT_SAFETY } from './types.js';
 export { writer, researcher, critic, analyst, builtinAgents } from './agents/index.js';
 export { createProvider } from './providers/index.js';
@@ -29,4 +31,8 @@ export { ClaudeCliProvider } from './providers/claude-cli.js';
 export { createMemory, SqliteMemoryProvider, PostgresMemoryProvider } from './memory/index.js';
 export { loadNotificationConfig } from './evolution/notifications.js';
 export type { NotificationConfig } from './evolution/notifications.js';
+export { dominates, nonDominatedFront, paretoSelect, scalarise, DARWIN_DEFAULT_OBJECTIVES, type ParetoObjective, } from './evolution/pareto.js';
+export { Reflector, type ReflectiveFeedback, type ReflectOptions, } from './evolution/reflector.js';
+export type { RunPromptFn } from './evolution/run-prompt-fn.js';
+export { GepaOptimizer, type ScoredVariant, type GenerateOptions as GepaGenerateOptions, type NextGenerationOptions as GepaNextGenerationOptions, } from './evolution/optimizer-gepa.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACxF,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAG5C,YAAY,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,QAAQ,EACR,eAAe,EACf,cAAc,EACd,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,SAAS,EACT,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG7D,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACvG,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAG9D,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAG/F,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AACtE,YAAY,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACxF,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAG5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAGjF,YAAY,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,QAAQ,EACR,eAAe,EACf,cAAc,EACd,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG7D,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACvG,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAG9D,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAG/F,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AACtE,YAAY,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,SAAS,EACT,yBAAyB,EACzB,KAAK,eAAe,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,SAAS,EACT,KAAK,kBAAkB,EACvB,KAAK,cAAc,GACpB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EACL,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,eAAe,IAAI,mBAAmB,EAC3C,KAAK,qBAAqB,IAAI,yBAAyB,GACxD,MAAM,+BAA+B,CAAC"}

package/dist/src/index.js

@@ -18,6 +18,8 @@
 // Core API
 export { defineAgent, defineConfig, loadConfig, loadConfigSync } from './core/agent.js';
 export { runAgent } from './core/runner.js';
+// V0.5.0-alpha.1 — Execution Trace Capture (S1184 Phase 2 A1)
+export { createTraceCapture } from './core/trace-capture.js';
 // Constants
 export { DEFAULT_WEIGHTS, DEFAULT_SAFETY } from './types.js';
 // Built-in Agents
@@ -32,4 +34,8 @@ export { ClaudeCliProvider } from './providers/claude-cli.js';
 export { createMemory, SqliteMemoryProvider, PostgresMemoryProvider } from './memory/index.js';
 // Notifications
 export { loadNotificationConfig } from './evolution/notifications.js';
+// V0.5.0-alpha.2 — GEPA-Style Reflective Optimizer (S1185 Phase 2 A2)
+export { dominates, nonDominatedFront, paretoSelect, scalarise, DARWIN_DEFAULT_OBJECTIVES, } from './evolution/pareto.js';
+export { Reflector, } from './evolution/reflector.js';
+export { GepaOptimizer, } from './evolution/optimizer-gepa.js';
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,WAAW;AACX,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACxF,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAsB5C,YAAY;AACZ,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE7D,kBAAkB;AAClB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvF,YAAY;AACZ,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,SAAS;AACT,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAE/F,gBAAgB;AAChB,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,WAAW;AACX,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACxF,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,8DAA8D;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AA2B7D,YAAY;AACZ,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE7D,kBAAkB;AAClB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvF,YAAY;AACZ,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,SAAS;AACT,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAE/F,gBAAgB;AAChB,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAGtE,sEAAsE;AACtE,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,SAAS,EACT,yBAAyB,GAE1B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,SAAS,GAGV,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,aAAa,GAId,MAAM,+BAA+B,CAAC"}

package/dist/src/memory/postgres-memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postgres-memory.d.ts","sourceRoot":"","sources":["../../../src/memory/postgres-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACX,QAAQ,EACR,cAAc,EACd,aAAa,EAEb,YAAY,EACb,MAAM,aAAa,CAAC;AAcrB,qBAAa,sBAAuB,YAAW,cAAc;IAC3D,OAAO,CAAC,IAAI,CAAwB;IACpC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,YAAY;IAa1B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiCrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,cAAc,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCpD,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAgB3E,iBAAiB,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAsDnD,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAYjE,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAejE,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAc/C,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAmC/D,QAAQ,IAAI,OAAO,CAAC,WAAW,CAAC;IAehC,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAUlD;;;OAGG;IACG,WAAW,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAqChF,OAAO,CAAC,OAAO;YAOD,YAAY;IA2E1B;;;;;;;;;OASG;YACW,qBAAqB;CAuLpC"}
+{"version":3,"file":"postgres-memory.d.ts","sourceRoot":"","sources":["../../../src/memory/postgres-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EAEX,QAAQ,EACR,cAAc,EACd,aAAa,EAEb,YAAY,EACb,MAAM,aAAa,CAAC;AAcrB,qBAAa,sBAAuB,YAAW,cAAc;IAC3D,OAAO,CAAC,IAAI,CAAwB;IACpC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,YAAY;IAa1B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiCrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,cAAc,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAyCpD,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAgB3E,iBAAiB,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAsDnD,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAYjE,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAejE,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAc/C,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAmC/D,QAAQ,IAAI,OAAO,CAAC,WAAW,CAAC;IAehC,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAUlD;;;OAGG;IACG,WAAW,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAqChF,OAAO,CAAC,OAAO;YAOD,YAAY;IAsF1B;;;;;;;;;OASG;YACW,qBAAqB;CAuLpC"}