@tangle-network/agent-eval 0.12.0 → 0.14.0

package/dist/index.js

@@ -1,3 +1,12 @@
+import {
+  LlmCallError,
+  LlmClient,
+  callLlm,
+  callLlmJson,
+  probeLlm,
+  stripFencedJson
+} from "./chunk-ITN4YOZY.js";
+
 // src/client.ts
 var ProductClient = class {
   baseUrl;
@@ -1926,6 +1935,244 @@ function rand(bytes) {
   return Array.from(arr).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 
+// src/experiment-tracker-fs.ts
+var FileSystemExperimentStore = class {
+  dir;
+  maxBytes;
+  index;
+  loaded = false;
+  constructor(options) {
+    this.dir = options.dir;
+    this.maxBytes = options.maxBytes ?? 32 * 1024 * 1024;
+  }
+  async saveExperiment(exp) {
+    const idx = await this.load();
+    await idx.saveExperiment(exp);
+    await this.append("experiments", exp);
+  }
+  async getExperiment(id) {
+    const idx = await this.load();
+    return idx.getExperiment(id);
+  }
+  async listExperiments() {
+    const idx = await this.load();
+    return idx.listExperiments();
+  }
+  async saveRun(run) {
+    const idx = await this.load();
+    await idx.saveRun(run);
+    await this.append("runs", run);
+  }
+  async getRun(id) {
+    const idx = await this.load();
+    return idx.getRun(id);
+  }
+  async listRuns(experimentId) {
+    const idx = await this.load();
+    return idx.listRuns(experimentId);
+  }
+  async ensureDir() {
+    const fs = await import("fs/promises");
+    await fs.mkdir(this.dir, { recursive: true });
+  }
+  async append(name, record) {
+    await this.ensureDir();
+    const fs = await import("fs/promises");
+    const path = await import("path");
+    const active = path.join(this.dir, `${name}.ndjson`);
+    try {
+      const stat = await fs.stat(active);
+      if (stat.size >= this.maxBytes) {
+        const rolled = path.join(this.dir, `${name}.${Date.now()}.ndjson`);
+        await fs.rename(active, rolled);
+      }
+    } catch {
+    }
+    await fs.appendFile(active, JSON.stringify(record) + "\n", "utf8");
+  }
+  async load() {
+    if (this.loaded && this.index) return this.index;
+    const fs = await import("fs/promises");
+    const path = await import("path");
+    const store = new InMemoryExperimentStore();
+    try {
+      const entries = await fs.readdir(this.dir);
+      const sorted = entries.filter((f) => f.endsWith(".ndjson")).sort((a, b) => a.localeCompare(b));
+      for (const file of sorted) {
+        const full = path.join(this.dir, file);
+        const content = await fs.readFile(full, "utf8");
+        const base = file.split(".")[0];
+        for (const line of content.split("\n")) {
+          if (!line.trim()) continue;
+          let record;
+          try {
+            record = JSON.parse(line);
+          } catch {
+            continue;
+          }
+          if (base === "experiments") {
+            await store.saveExperiment(record);
+          } else if (base === "runs") {
+            await store.saveRun(record);
+          }
+        }
+      }
+    } catch {
+    }
+    this.index = store;
+    this.loaded = true;
+    return store;
+  }
+};
+
+// src/experiment-tracker-d1.ts
+var SCHEMA_VERSION = 1;
+var D1ExperimentStore = class {
+  db;
+  experimentsTable;
+  runsTable;
+  metaTable;
+  schemaReady = false;
+  constructor(options) {
+    this.db = options.db;
+    const prefix = options.tablePrefix ?? "agent_eval_";
+    this.experimentsTable = `${prefix}experiments`;
+    this.runsTable = `${prefix}runs`;
+    this.metaTable = `${prefix}meta`;
+  }
+  /**
+   * Idempotent schema setup. Safe to call before every operation; the second
+   * call short-circuits via `schemaReady`. Most consumers will call it once
+   * during Worker bootstrap.
+   */
+  async ensureSchema() {
+    if (this.schemaReady) return;
+    const ddl = `
+      CREATE TABLE IF NOT EXISTS ${this.experimentsTable} (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        metadata_json TEXT
+      );
+      CREATE TABLE IF NOT EXISTS ${this.runsTable} (
+        id TEXT PRIMARY KEY,
+        experiment_id TEXT NOT NULL,
+        name TEXT,
+        status TEXT NOT NULL,
+        started_at TEXT NOT NULL,
+        completed_at TEXT,
+        config_json TEXT NOT NULL,
+        report_json TEXT,
+        error TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_${this.runsTable}_experiment ON ${this.runsTable}(experiment_id);
+      CREATE INDEX IF NOT EXISTS idx_${this.runsTable}_started ON ${this.runsTable}(started_at);
+      CREATE TABLE IF NOT EXISTS ${this.metaTable} (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+      INSERT OR REPLACE INTO ${this.metaTable}(key, value) VALUES ('schema_version', '${SCHEMA_VERSION}');
+    `;
+    await this.db.exec(ddl.trim().replace(/\s+/g, " "));
+    this.schemaReady = true;
+  }
+  async saveExperiment(exp) {
+    await this.ensureSchema();
+    await this.db.prepare(
+      `INSERT INTO ${this.experimentsTable}(id, name, created_at, metadata_json)
+         VALUES (?1, ?2, ?3, ?4)
+         ON CONFLICT(id) DO UPDATE SET
+           name = excluded.name,
+           created_at = excluded.created_at,
+           metadata_json = excluded.metadata_json`
+    ).bind(exp.id, exp.name, exp.createdAt, exp.metadata ? JSON.stringify(exp.metadata) : null).run();
+  }
+  async getExperiment(id) {
+    await this.ensureSchema();
+    const row = await this.db.prepare(
+      `SELECT id, name, created_at, metadata_json
+         FROM ${this.experimentsTable}
+         WHERE id = ?1`
+    ).bind(id).first();
+    return row ? rowToExperiment(row) : null;
+  }
+  async listExperiments() {
+    await this.ensureSchema();
+    const { results } = await this.db.prepare(
+      `SELECT id, name, created_at, metadata_json
+         FROM ${this.experimentsTable}
+         ORDER BY created_at DESC`
+    ).all();
+    return results.map(rowToExperiment);
+  }
+  async saveRun(run) {
+    await this.ensureSchema();
+    await this.db.prepare(
+      `INSERT INTO ${this.runsTable}(id, experiment_id, name, status, started_at, completed_at, config_json, report_json, error)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)
+         ON CONFLICT(id) DO UPDATE SET
+           experiment_id = excluded.experiment_id,
+           name = excluded.name,
+           status = excluded.status,
+           started_at = excluded.started_at,
+           completed_at = excluded.completed_at,
+           config_json = excluded.config_json,
+           report_json = excluded.report_json,
+           error = excluded.error`
+    ).bind(
+      run.id,
+      run.experimentId,
+      run.name ?? null,
+      run.status,
+      run.startedAt,
+      run.completedAt ?? null,
+      JSON.stringify(run.config),
+      run.report ? JSON.stringify(run.report) : null,
+      run.error ?? null
+    ).run();
+  }
+  async getRun(id) {
+    await this.ensureSchema();
+    const row = await this.db.prepare(
+      `SELECT id, experiment_id, name, status, started_at, completed_at, config_json, report_json, error
+         FROM ${this.runsTable}
+         WHERE id = ?1`
+    ).bind(id).first();
+    return row ? rowToRun(row) : null;
+  }
+  async listRuns(experimentId) {
+    await this.ensureSchema();
+    const { results } = await this.db.prepare(
+      `SELECT id, experiment_id, name, status, started_at, completed_at, config_json, report_json, error
+         FROM ${this.runsTable}
+         WHERE experiment_id = ?1
+         ORDER BY started_at DESC`
+    ).bind(experimentId).all();
+    return results.map(rowToRun);
+  }
+};
+function rowToExperiment(row) {
+  return {
+    id: row.id,
+    name: row.name,
+    createdAt: row.created_at,
+    ...row.metadata_json ? { metadata: JSON.parse(row.metadata_json) } : {}
+  };
+}
+function rowToRun(row) {
+  return {
+    id: row.id,
+    experimentId: row.experiment_id,
+    ...row.name ? { name: row.name } : {},
+    status: row.status,
+    startedAt: row.started_at,
+    ...row.completed_at ? { completedAt: row.completed_at } : {},
+    config: JSON.parse(row.config_json),
+    ...row.report_json ? { report: JSON.parse(row.report_json) } : {},
+    ...row.error ? { error: row.error } : {}
+  };
+}
+
 // src/power-analysis.ts
 function requiredSampleSize(opts) {
   const effect = opts.effect;
@@ -8058,212 +8305,6 @@ async function euAiActReport(ctx, signals) {
   };
 }
 
-// src/llm-client.ts
-var LlmCallError = class extends Error {
-  constructor(message, status, body, model) {
-    super(message);
-    this.status = status;
-    this.body = body;
-    this.model = model;
-    this.name = "LlmCallError";
-  }
-  status;
-  body;
-  model;
-};
-var DEFAULT_BASE_URL = "https://router.tangle.tools/v1";
-var DEFAULT_TIMEOUT_MS = 6e4;
-var DEFAULT_MAX_RETRIES = 3;
-var RETRYABLE_STATUS = /* @__PURE__ */ new Set([429, 502, 503, 504]);
-function isRetryableError(err) {
-  if (err instanceof LlmCallError) return RETRYABLE_STATUS.has(err.status);
-  if (err instanceof Error) {
-    return err.name === "AbortError" || err.name === "TimeoutError" || /fetch failed|ECONNRESET|ETIMEDOUT|EAI_AGAIN/i.test(err.message);
-  }
-  return false;
-}
-function parseRetryAfter(headers) {
-  const h = headers.get("retry-after");
-  if (!h) return null;
-  const asNumber = Number(h);
-  if (Number.isFinite(asNumber) && asNumber > 0) return asNumber * 1e3;
-  const asDate = Date.parse(h);
-  if (Number.isFinite(asDate)) return Math.max(0, asDate - Date.now());
-  return null;
-}
-function backoffMs(attempt) {
-  return Math.min(500 * Math.pow(2, attempt), 16e3);
-}
-function buildHeaders(opts) {
-  const headers = {
-    "Content-Type": "application/json",
-    Accept: "application/json"
-  };
-  if (opts.authHeader) {
-    headers[opts.authHeader.name] = opts.authHeader.value;
-  } else if (opts.bearer || opts.apiKey) {
-    headers.Authorization = `Bearer ${opts.bearer ?? opts.apiKey}`;
-  }
-  return headers;
-}
-function isSchemaRejection(status, body) {
-  if (status !== 400) return false;
-  const lower = body.toLowerCase();
-  return lower.includes("response_format") || lower.includes("json_schema") || lower.includes("is unavailable") || lower.includes("not supported");
-}
-function buildBody(req, forceJsonObject) {
-  const body = {
-    model: req.model,
-    messages: req.messages,
-    temperature: req.temperature ?? 0
-  };
-  if (req.maxTokens != null) body.max_tokens = req.maxTokens;
-  if (req.jsonSchema && !forceJsonObject) {
-    body.response_format = {
-      type: "json_schema",
-      json_schema: { name: req.jsonSchema.name, schema: req.jsonSchema.schema, strict: true }
-    };
-  } else if (req.jsonMode || req.jsonSchema) {
-    body.response_format = { type: "json_object" };
-  }
-  return body;
-}
-async function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-function stripFencedJson(raw) {
-  const trimmed = raw.trim();
-  const m = trimmed.match(/^```(?:json)?\s*\n?([\s\S]*?)\n?```\s*$/);
-  return m ? m[1].trim() : trimmed;
-}
-async function callLlm(req, opts = {}) {
-  const baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-  const url = `${baseUrl}/chat/completions`;
-  const timeoutMs = req.timeoutMs ?? opts.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
-  const fetchFn = opts.fetch ?? globalThis.fetch;
-  const headers = buildHeaders(opts);
-  let lastErr;
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    const controller = new AbortController();
-    const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
-    const started = Date.now();
-    try {
-      const res = await fetchFn(url, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(buildBody(req, false)),
-        signal: controller.signal
-      });
-      clearTimeout(timeoutHandle);
-      if (!res.ok) {
-        const body = await res.text();
-        const err = new LlmCallError(
-          `LLM call ${res.status}: ${body.slice(0, 300)}`,
-          res.status,
-          body,
-          req.model
-        );
-        if (RETRYABLE_STATUS.has(res.status) && attempt < maxRetries - 1) {
-          lastErr = err;
-          const retryAfter = parseRetryAfter(res.headers);
-          await sleep(retryAfter ?? backoffMs(attempt));
-          continue;
-        }
-        throw err;
-      }
-      const json = await res.json();
-      const choice = json.choices?.[0];
-      const usageRaw = json.usage ?? {};
-      const costFromProxy = json._response_cost ?? json.cost_usd;
-      return {
-        content: choice?.message?.content ?? "",
-        usage: {
-          promptTokens: Number(usageRaw.prompt_tokens ?? 0),
-          completionTokens: Number(usageRaw.completion_tokens ?? 0),
-          totalTokens: Number(usageRaw.total_tokens ?? 0),
-          cachedPromptTokens: usageRaw.prompt_tokens_details && typeof usageRaw.prompt_tokens_details === "object" ? Number(
-            usageRaw.prompt_tokens_details.cached_tokens ?? 0
-          ) : void 0
-        },
-        costUsd: typeof costFromProxy === "number" ? costFromProxy : null,
-        model: json.model ?? req.model,
-        durationMs: Date.now() - started,
-        raw: json
-      };
-    } catch (err) {
-      clearTimeout(timeoutHandle);
-      lastErr = err;
-      if (attempt < maxRetries - 1 && isRetryableError(err)) {
-        await sleep(backoffMs(attempt));
-        continue;
-      }
-      throw err;
-    }
-  }
-  throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
-}
-async function callLlmJson(req, opts = {}) {
-  try {
-    const result = await callLlm({ ...req, jsonMode: req.jsonMode ?? !req.jsonSchema }, opts);
-    const value = parseJsonSafely(result.content, result.model);
-    return { value, result };
-  } catch (err) {
-    if (err instanceof LlmCallError && isSchemaRejection(err.status, err.body) && req.jsonSchema) {
-      const degradedReq = { ...req, jsonMode: true, jsonSchema: void 0 };
-      const result = await callLlm(degradedReq, opts);
-      const value = parseJsonSafely(result.content, result.model);
-      return { value, result };
-    }
-    throw err;
-  }
-}
-function parseJsonSafely(content, model) {
-  const stripped = stripFencedJson(content);
-  try {
-    return JSON.parse(stripped);
-  } catch (err) {
-    throw new Error(
-      `LLM returned non-JSON content (model=${model}): ${err instanceof Error ? err.message : String(err)}
---- raw content ---
-${content.slice(0, 800)}`
-    );
-  }
-}
-async function probeLlm(model, opts = {}) {
-  const start = Date.now();
-  try {
-    await callLlm(
-      {
-        model,
-        messages: [{ role: "user", content: "ping" }],
-        maxTokens: 64,
-        timeoutMs: opts.timeoutMs ?? 3e4
-      },
-      opts
-    );
-    return { ok: true, latencyMs: Date.now() - start, error: null };
-  } catch (err) {
-    return {
-      ok: false,
-      latencyMs: Date.now() - start,
-      error: err instanceof Error ? err.message : String(err)
-    };
-  }
-}
-var LlmClient = class {
-  constructor(opts = {}) {
-    this.opts = opts;
-  }
-  opts;
-  call(req, per) {
-    return callLlm(req, { ...this.opts, ...per });
-  }
-  callJson(req, per) {
-    return callLlmJson(req, { ...this.opts, ...per });
-  }
-};
-
 // src/multi-layer-verifier.ts
 function gradeSemanticStatus(input) {
   if (!input.available) return "error";
@@ -9497,6 +9538,49 @@ function extractErrorCount(text, opts = {}) {
 // src/reference-replay.ts
 import { appendFileSync as appendFileSync2, existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync4 } from "fs";
 import { dirname as dirname2 } from "path";
+
+// src/concurrency.ts
+var Mutex = class {
+  locked = false;
+  waiters = [];
+  async acquire() {
+    if (!this.locked) {
+      this.locked = true;
+      return () => this.release();
+    }
+    return new Promise((resolve) => {
+      this.waiters.push(() => {
+        resolve(() => this.release());
+      });
+    });
+  }
+  release() {
+    const next = this.waiters.shift();
+    if (next) {
+      next();
+    } else {
+      this.locked = false;
+    }
+  }
+  async runExclusive(fn) {
+    const release = await this.acquire();
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+  /** True iff someone holds the lock right now. Diagnostics only. */
+  get isLocked() {
+    return this.locked;
+  }
+  /** Pending waiter count. Diagnostics only. */
+  get pending() {
+    return this.waiters.length;
+  }
+};
+
+// src/reference-replay.ts
 var DEFAULT_MATCH_THRESHOLD = 0.55;
 var ALL_SPLITS = ["train", "dev", "test", "holdout"];
 async function runReferenceReplay(cases, options) {
@@ -9597,15 +9681,29 @@ function inMemoryReferenceReplayStore(initial = []) {
     }
   };
 }
+var jsonlStoreLocks = /* @__PURE__ */ new Map();
+function getJsonlStoreLock(path) {
+  let m = jsonlStoreLocks.get(path);
+  if (!m) {
+    m = new Mutex();
+    jsonlStoreLocks.set(path, m);
+  }
+  return m;
+}
 function jsonlReferenceReplayStore(path) {
+  const lock = getJsonlStoreLock(path);
   return {
     async save(run) {
-      mkdirSync2(dirname2(path), { recursive: true });
-      appendFileSync2(path, JSON.stringify(run) + "\n");
+      await lock.runExclusive(() => {
+        mkdirSync2(dirname2(path), { recursive: true });
+        appendFileSync2(path, JSON.stringify(run) + "\n");
+      });
     },
     async list() {
-      if (!existsSync4(path)) return [];
-      return readJsonl(path);
+      return lock.runExclusive(() => {
+        if (!existsSync4(path)) return [];
+        return readJsonl(path);
+      });
     }
   };
 }
@@ -10231,6 +10329,561 @@ function samePopulation(a, b) {
   return b.every((id) => setA.has(id));
 }
 
+// src/jsonl-trial-cache.ts
+import { appendFileSync as appendFileSync4, existsSync as existsSync6, mkdirSync as mkdirSync4, readFileSync as readFileSync5 } from "fs";
+import { dirname as dirname4 } from "path";
+
+// src/locked-jsonl-appender.ts
+import { appendFileSync as appendFileSync3, existsSync as existsSync5, mkdirSync as mkdirSync3 } from "fs";
+import { dirname as dirname3 } from "path";
+var mutexes = /* @__PURE__ */ new Map();
+function getMutex(path) {
+  let m = mutexes.get(path);
+  if (!m) {
+    m = new Mutex();
+    mutexes.set(path, m);
+  }
+  return m;
+}
+var LockedJsonlAppender = class {
+  constructor(path) {
+    this.path = path;
+    this.mutex = getMutex(path);
+    if (!existsSync5(dirname3(path))) {
+      mkdirSync3(dirname3(path), { recursive: true });
+    }
+  }
+  path;
+  mutex;
+  async append(entry) {
+    const line = `${JSON.stringify(entry)}
+`;
+    await this.mutex.runExclusive(() => {
+      appendFileSync3(this.path, line);
+    });
+  }
+};
+function resetLockedAppendersForTesting() {
+  mutexes.clear();
+}
+
+// src/jsonl-trial-cache.ts
+var JsonlTrialCache = class {
+  map = /* @__PURE__ */ new Map();
+  path;
+  appender;
+  constructor(path) {
+    this.path = path;
+    if (existsSync6(path)) {
+      for (const line of readFileSync5(path, "utf-8").split("\n")) {
+        if (!line.trim()) continue;
+        try {
+          const entry = JSON.parse(line);
+          this.map.set(entry.key, entry.result);
+        } catch {
+        }
+      }
+    } else {
+      mkdirSync4(dirname4(path), { recursive: true });
+    }
+    this.appender = new LockedJsonlAppender(path);
+  }
+  get(key) {
+    return this.map.get(key);
+  }
+  set(key, value) {
+    this.map.set(key, value);
+    const line = { key, result: value, writtenAt: Date.now() };
+    void this.appender.append(line);
+  }
+  size() {
+    return this.map.size;
+  }
+  /**
+   * Synchronous fallback path for tests / CLI tools that want to be sure
+   * the line is on disk before returning. Bypasses the mutex (single-
+   * threaded callers only).
+   */
+  setSync(key, value) {
+    this.map.set(key, value);
+    const line = { key, result: value, writtenAt: Date.now() };
+    appendFileSync4(this.path, `${JSON.stringify(line)}
+`);
+  }
+};
+
+// src/evolution-telemetry.ts
+import { appendFileSync as appendFileSync5, existsSync as existsSync7, mkdirSync as mkdirSync5, readFileSync as readFileSync6, writeFileSync } from "fs";
+import { dirname as dirname5 } from "path";
+var MutationTelemetry = class {
+  appender;
+  constructor(path) {
+    this.appender = new LockedJsonlAppender(path);
+  }
+  async record(attempt) {
+    await this.appender.append(attempt);
+  }
+};
+var TrialTelemetry = class {
+  appender;
+  constructor(path) {
+    this.appender = new LockedJsonlAppender(path);
+  }
+  async record(attempt) {
+    await this.appender.append(attempt);
+  }
+};
+var LineageRecorder = class {
+  path;
+  snapshotPath;
+  mutex = new Mutex();
+  nodes = /* @__PURE__ */ new Map();
+  kindOf;
+  constructor(path, kindOf) {
+    this.path = path;
+    this.snapshotPath = `${path}.snapshot`;
+    this.kindOf = kindOf ?? defaultKindOf;
+    mkdirSync5(dirname5(path), { recursive: true });
+    if (existsSync7(this.snapshotPath)) {
+      try {
+        const parsed = JSON.parse(readFileSync6(this.snapshotPath, "utf-8"));
+        for (const n of parsed) this.nodes.set(n.id, n);
+      } catch {
+      }
+    }
+    if (existsSync7(path)) {
+      try {
+        for (const line of readFileSync6(path, "utf-8").split("\n")) {
+          if (!line.trim()) continue;
+          try {
+            const entry = JSON.parse(line);
+            const prev = this.nodes.get(entry.id);
+            this.nodes.set(entry.id, { ...prev, ...entry });
+          } catch {
+          }
+        }
+      } catch {
+      }
+    }
+    if (existsSync7(path) && this.nodes.size === 0) {
+      try {
+        const raw = readFileSync6(path, "utf-8").trim();
+        if (raw.startsWith("[")) {
+          const parsed = JSON.parse(raw);
+          for (const n of parsed) this.nodes.set(n.id, n);
+        }
+      } catch {
+      }
+    }
+  }
+  async upsert(node) {
+    await this.mutex.runExclusive(() => {
+      const prev = this.nodes.get(node.id);
+      this.nodes.set(node.id, { ...prev, ...node });
+      try {
+        if (existsSync7(this.path)) {
+          const head = readFileSync6(this.path, { encoding: "utf-8", flag: "r" }).slice(0, 1);
+          if (head === "[") {
+            writeFileSync(this.path, "");
+          }
+        }
+      } catch {
+      }
+      appendFileSync5(this.path, `${JSON.stringify(this.nodes.get(node.id))}
+`);
+    });
+  }
+  async upsertVariant(variant) {
+    await this.upsert({
+      id: variant.id,
+      parentId: variant.parentId ?? null,
+      generation: variant.generation,
+      kind: this.kindOf(variant),
+      ...variant.rationale ? { rationale: variant.rationale } : {}
+    });
+  }
+  snapshot() {
+    return [...this.nodes.values()];
+  }
+  /**
+   * Write the current consolidated state to `<path>.snapshot` so external
+   * tools can read it without replaying the event log. Idempotent.
+   */
+  async compact() {
+    await this.mutex.runExclusive(() => {
+      writeFileSync(this.snapshotPath, JSON.stringify([...this.nodes.values()], null, 2));
+    });
+  }
+};
+function defaultKindOf(variant) {
+  if (variant.parentId === void 0) return "seed";
+  const payload = variant.payload;
+  if (payload && typeof payload === "object" && payload.codeMutation) return "code";
+  return "prompt";
+}
+function emptyGenBucket() {
+  return {
+    mutatorPromptUsd: 0,
+    mutatorCodeUsd: 0,
+    scorerPromptUsd: 0,
+    scorerCodeUsd: 0,
+    trialsCounted: 0,
+    cachedTrials: 0
+  };
+}
+var CostLedger = class {
+  totals = {
+    mutatorPromptUsd: 0,
+    mutatorCodeUsd: 0,
+    scorerPromptUsd: 0,
+    scorerCodeUsd: 0,
+    trialsCounted: 0,
+    cachedTrials: 0,
+    poolBusyMs: 0,
+    poolUtilizationPct: 0,
+    byGeneration: {}
+  };
+  path;
+  mutex = new Mutex();
+  constructor(path) {
+    this.path = path;
+    if (existsSync7(path)) {
+      try {
+        const loaded = JSON.parse(readFileSync6(path, "utf-8"));
+        for (const k of Object.keys(this.totals)) {
+          if (k === "byGeneration") {
+            if (loaded.byGeneration && typeof loaded.byGeneration === "object") {
+              this.totals.byGeneration = loaded.byGeneration;
+            }
+            continue;
+          }
+          const v = loaded[k];
+          if (typeof v === "number" && Number.isFinite(v)) {
+            this.totals[k] = v;
+          }
+        }
+      } catch {
+      }
+    } else {
+      mkdirSync5(dirname5(path), { recursive: true });
+    }
+  }
+  genBucket(generation) {
+    if (generation === void 0) return null;
+    const key = String(generation);
+    if (!this.totals.byGeneration[key]) {
+      this.totals.byGeneration[key] = emptyGenBucket();
+    }
+    return this.totals.byGeneration[key];
+  }
+  async addMutation(channel, usd, opts = {}) {
+    await this.mutex.runExclusive(() => {
+      const bucket = this.genBucket(opts.generation);
+      if (channel === "prompt") {
+        this.totals.mutatorPromptUsd += usd;
+        if (bucket) bucket.mutatorPromptUsd += usd;
+      } else {
+        this.totals.mutatorCodeUsd += usd;
+        if (bucket) bucket.mutatorCodeUsd += usd;
+      }
+      this.persist();
+    });
+  }
+  async addTrial(channel, usd, cached, opts = {}) {
+    await this.mutex.runExclusive(() => {
+      const bucket = this.genBucket(opts.generation);
+      if (cached) {
+        this.totals.cachedTrials++;
+        this.totals.trialsCounted++;
+        if (bucket) {
+          bucket.cachedTrials++;
+          bucket.trialsCounted++;
+        }
+        this.persist();
+        return;
+      }
+      if (channel === "prompt") {
+        this.totals.scorerPromptUsd += usd;
+        if (bucket) bucket.scorerPromptUsd += usd;
+      } else {
+        this.totals.scorerCodeUsd += usd;
+        if (bucket) bucket.scorerCodeUsd += usd;
+      }
+      this.totals.trialsCounted++;
+      if (bucket) bucket.trialsCounted++;
+      this.persist();
+    });
+  }
+  async setPoolUtilization(busyMs, totalMs) {
+    await this.mutex.runExclusive(() => {
+      this.totals.poolBusyMs = busyMs;
+      this.totals.poolUtilizationPct = totalMs > 0 ? 100 * busyMs / totalMs : 0;
+      this.persist();
+    });
+  }
+  snapshot() {
+    const totalUsd = this.totals.mutatorPromptUsd + this.totals.mutatorCodeUsd + this.totals.scorerPromptUsd + this.totals.scorerCodeUsd;
+    const byGeneration = Object.entries(this.totals.byGeneration).map(([g, b]) => ({ generation: Number(g), ...b })).sort((a, b) => a.generation - b.generation);
+    return {
+      totalUsd,
+      mutatorPromptUsd: this.totals.mutatorPromptUsd,
+      mutatorCodeUsd: this.totals.mutatorCodeUsd,
+      scorerPromptUsd: this.totals.scorerPromptUsd,
+      scorerCodeUsd: this.totals.scorerCodeUsd,
+      trialsCounted: this.totals.trialsCounted,
+      cachedTrials: this.totals.cachedTrials,
+      poolBusyMs: this.totals.poolBusyMs,
+      poolUtilizationPct: this.totals.poolUtilizationPct,
+      byGeneration
+    };
+  }
+  persist() {
+    writeFileSync(this.path, JSON.stringify(this.totals, null, 2));
+  }
+};
+
+// src/composite-mutator.ts
+function createCompositeMutator(opts) {
+  const recentScores = [];
+  const plateauThreshold = opts.plateauThreshold ?? 0.02;
+  const plateauPatience = opts.plateauPatience ?? 2;
+  function pickMode(args) {
+    recentScores.push(args.parentAggregate.meanScore);
+    switch (opts.policy) {
+      case "primary-only":
+        return { mode: "primary", reason: "policy=primary-only" };
+      case "secondary-only":
+        if (!opts.secondary) return { mode: "primary", reason: "secondary-only requested but no secondary mutator wired" };
+        return { mode: "secondary", reason: "policy=secondary-only" };
+      case "alternate":
+        if (!opts.secondary) return { mode: "primary", reason: "alternate requested but no secondary mutator wired" };
+        return args.generation % 2 === 1 ? { mode: "secondary", reason: `alternate: gen${args.generation} odd \u2192 secondary` } : { mode: "primary", reason: `alternate: gen${args.generation} even \u2192 primary` };
+      case "plateau": {
+        if (!opts.secondary) return { mode: "primary", reason: "plateau requested but no secondary mutator wired" };
+        if (recentScores.length <= plateauPatience) {
+          return { mode: "primary", reason: "plateau: warming up with primary mutations" };
+        }
+        const window = recentScores.slice(-plateauPatience - 1);
+        const deltas = window.slice(1).map((v, i) => v - window[i]);
+        const stagnant = deltas.every((d) => d < plateauThreshold);
+        if (stagnant) {
+          return {
+            mode: "split",
+            reason: `plateau detected (${deltas.map((d) => d.toFixed(3)).join(", ")}) \u2192 split`
+          };
+        }
+        return {
+          mode: "primary",
+          reason: `plateau: still improving (${deltas[deltas.length - 1].toFixed(3)})`
+        };
+      }
+    }
+  }
+  return {
+    async mutate(args) {
+      const { mode, reason } = pickMode(args);
+      opts.onPolicyDecision?.({ generation: args.generation, chose: mode, reason });
+      if (mode === "primary") return opts.primary.mutate(args);
+      if (mode === "secondary" && opts.secondary) return opts.secondary.mutate(args);
+      if (mode === "split" && opts.secondary) {
+        const secondaryShare = Math.ceil(args.childCount / 2);
+        const primaryShare = args.childCount - secondaryShare;
+        const [primaryChildren, secondaryChildren] = await Promise.all([
+          opts.primary.mutate({ ...args, childCount: primaryShare }),
+          opts.secondary.mutate({ ...args, childCount: secondaryShare })
+        ]);
+        return [...primaryChildren, ...secondaryChildren];
+      }
+      return opts.primary.mutate(args);
+    }
+  };
+}
+
+// src/sandbox-pool.ts
+function createSandboxPool(opts) {
+  if (opts.size < 1) throw new Error(`sandbox pool size must be >= 1 (got ${opts.size})`);
+  const slots = [];
+  const waiters = [];
+  const mutex = new Mutex();
+  let nextSlotId = 0;
+  let totalCheckouts = 0;
+  let busyMs = 0;
+  const startedAt = Date.now();
+  async function acquireSlot() {
+    let mintId;
+    const ready = await mutex.runExclusive(async () => {
+      const idle = slots.find((s) => !s.busy);
+      if (idle) {
+        idle.busy = true;
+        return idle;
+      }
+      if (slots.length < opts.size) {
+        mintId = `slot_${nextSlotId++}`;
+        return null;
+      }
+      return null;
+    });
+    if (ready) return ready;
+    if (mintId !== void 0) {
+      const resource = await opts.factory.create(mintId);
+      const state = {
+        slot: { id: mintId, resource },
+        busy: true
+      };
+      await mutex.runExclusive(() => {
+        slots.push(state);
+      });
+      return state;
+    }
+    return new Promise((resolve) => {
+      waiters.push((s) => {
+        s.busy = true;
+        resolve(s);
+      });
+    });
+  }
+  function releaseSlot(state) {
+    void (async () => {
+      try {
+        if (opts.factory.reset) await opts.factory.reset(state.slot);
+      } catch (err) {
+        console.warn(`[sandbox-pool] reset failed for slot ${state.slot.id}:`, err);
+      }
+      state.busy = false;
+      const next = waiters.shift();
+      if (next) next(state);
+    })();
+  }
+  async function checkout() {
+    const state = await acquireSlot();
+    const checkoutStart = Date.now();
+    totalCheckouts++;
+    return {
+      slot: state.slot,
+      release: () => {
+        busyMs += Date.now() - checkoutStart;
+        releaseSlot(state);
+      }
+    };
+  }
+  async function withSlot(fn) {
+    const { slot, release } = await checkout();
+    try {
+      return await fn(slot);
+    } finally {
+      release();
+    }
+  }
+  async function drain() {
+    const snapshot = await mutex.runExclusive(() => {
+      const taken = slots.splice(0, slots.length);
+      for (const w of waiters.splice(0, waiters.length)) {
+        void w;
+      }
+      return taken;
+    });
+    await Promise.allSettled(snapshot.map((s) => opts.factory.destroy(s.slot)));
+  }
+  function utilization() {
+    return {
+      busyMs,
+      totalMs: Date.now() - startedAt,
+      checkouts: totalCheckouts
+    };
+  }
+  return {
+    checkout,
+    withSlot,
+    drain,
+    poolSize: () => slots.length,
+    activeCheckouts: () => slots.filter((s) => s.busy).length,
+    utilization
+  };
+}
+
+// src/code-mutator.ts
+function createSandboxCodeMutator(opts) {
+  const childIdFor = opts.childIdFor ?? ((parent, generation, index) => `${parent.id}.g${generation}.code.${index}`);
+  const labelFor = opts.labelFor ?? ((outcome, parent, _generation, index) => outcome.description?.slice(0, 80) ?? `${parent.label} \u2192 code.${index}`);
+  return {
+    async mutate(args) {
+      const { parent, parentAggregate, topTrials, bottomTrials, childCount, generation } = args;
+      const startedAt = Date.now();
+      const outcomes = await opts.pool.withSlot(async (slot) => {
+        try {
+          return await opts.runner({
+            slot,
+            parent,
+            parentAggregate,
+            topTrials,
+            bottomTrials,
+            childCount,
+            generation
+          });
+        } catch (err) {
+          return [{
+            ok: false,
+            failureReason: "runner_error",
+            description: err instanceof Error ? err.message : String(err),
+            latencyMs: Date.now() - startedAt
+          }];
+        }
+      });
+      const variants = [];
+      let index = 0;
+      for (const outcome of outcomes) {
+        const childId = outcome.childId ?? childIdFor(parent, generation, index);
+        if (opts.mutationTelemetry) {
+          await opts.mutationTelemetry.record({
+            ts: Date.now(),
+            channel: "code",
+            generation,
+            parentId: parent.id,
+            childId: outcome.ok ? childId : null,
+            ok: outcome.ok,
+            failureReason: outcome.failureReason,
+            description: outcome.description,
+            latencyMs: outcome.latencyMs,
+            diffBytes: outcome.diffBytes,
+            filesTouched: outcome.filesTouched,
+            agentSteps: outcome.agentSteps,
+            costUsd: outcome.costUsd
+          });
+        }
+        if (opts.costLedger && outcome.costUsd !== void 0) {
+          await opts.costLedger.addMutation("code", outcome.costUsd, { generation });
+        }
+        if (outcome.ok) {
+          const variant = {
+            id: childId,
+            payload: opts.toVariantPayload(outcome, parent),
+            generation,
+            parentId: parent.id,
+            label: labelFor(outcome, parent, generation, index),
+            ...outcome.rationale ? { rationale: outcome.rationale } : {}
+          };
+          variants.push(variant);
+          if (opts.lineage) {
+            await opts.lineage.upsert({
+              id: variant.id,
+              parentId: variant.parentId ?? null,
+              generation: variant.generation,
+              kind: "code",
+              ...variant.rationale ? { rationale: variant.rationale } : {}
+            });
+          }
+        }
+        index++;
+      }
+      if (opts.costLedger) {
+        const u = opts.pool.utilization();
+        await opts.costLedger.setPoolUtilization(u.busyMs, u.totalMs);
+      }
+      return variants;
+    }
+  };
+}
+
 // src/golden-matcher.ts
 function matchGoldens(goldens, candidates, options = {}) {
   const extract = options.text ?? defaultExtract5;
@@ -10593,7 +11246,9 @@ export {
   BudgetGuard,
   BuilderSession,
   ConvergenceTracker,
+  CostLedger,
   CostTracker,
+  D1ExperimentStore,
   DEFAULT_AGENT_SLOS,
   DEFAULT_COMPLEXITY_WEIGHTS,
   DEFAULT_RULES as DEFAULT_FAILURE_RULES,
@@ -10611,6 +11266,7 @@ export {
   ERROR_COUNT_PATTERNS,
   ExperimentTracker,
   FAILURE_CLASSES,
+  FileSystemExperimentStore,
   FileSystemOutcomeStore,
   FileSystemTraceStore,
   HoldoutAuditor,
@@ -10621,12 +11277,17 @@ export {
   InMemoryTraceStore,
   InMemoryTrialCache,
   InMemoryWorkspaceInspector,
+  JsonlTrialCache,
   JudgeRunner,
+  LineageRecorder,
   LlmCallError,
   LlmClient,
+  LockedJsonlAppender,
   MODEL_PRICING,
   MetricsCollector,
   MultiLayerVerifier,
+  MutationTelemetry,
+  Mutex,
   OTEL_AGENT_EVAL_SCOPE,
   OptimizationLoop,
   PairwiseSteeringOptimizer,
@@ -10644,6 +11305,7 @@ export {
   TRACE_SCHEMA_VERSION,
   TokenCounter,
   TraceEmitter,
+  TrialTelemetry,
   UNIVERSAL_FINDERS,
   adversarialJudge,
   aggregateLlm,
@@ -10688,11 +11350,14 @@ export {
   correlateLayers,
   correlationStudy,
   createAntiSlopJudge,
+  createCompositeMutator,
   createCustomJudge,
   createDefaultReviewer,
   createDomainExpertJudge,
   createIntentMatchJudge,
   createLlmReviewer,
+  createSandboxCodeMutator,
+  createSandboxPool,
   createSemanticConceptJudge,
   crossTraceDiff,
   crowdingDistance,
@@ -10803,6 +11468,7 @@ export {
   replayScorerOverCorpus,
   replayTraceThroughJudge,
   requiredSampleSize,
+  resetLockedAppendersForTesting,
   resumeBuilderSession,
   rowCount,
   rowWhere,