@attest-ai/core 1.0.0-rc.1 → 1.0.0-rc.3

package/dist/esm/index.js

@@ -12,12 +12,16 @@ var REASON_PROVIDER_NOT_CONFIGURED = "provider_not_configured";
 var REASON_SIMULATION = "simulation";
 var REASON_MISSING_EVIDENCE = "missing_evidence";
 var REASON_SHORT_CIRCUITED = "short_circuited";
+var REASON_BUDGET_EXHAUSTED = "budget_exhausted";
+var REASON_JUDGE_ABSTAINED = "judge_abstained";
+var REASON_REPLAY_MISS = "replay_miss";
 var OUTCOME_PASS = "pass";
 var OUTCOME_FAIL = "fail";
 var OUTCOME_SKIP = "skip";
 var TYPE_SCHEMA = "schema";
 var TYPE_CONSTRAINT = "constraint";
 var TYPE_TRACE = "trace";
+var TYPE_EFFECT = "effect";
 var TYPE_CONTENT = "content";
 var TYPE_EMBEDDING = "embedding";
 var TYPE_LLM_JUDGE = "llm_judge";
@@ -55,6 +59,7 @@ function layerForType(assertionType) {
       return 2;
     case "trace":
     case "trace_tree":
+    case "effect":
       return 3;
     case "content":
       return 4;
@@ -102,6 +107,12 @@ var ProtocolDesyncError = class extends Error {
     this.diagnostics = diagnostics;
   }
 };
+var OTLPConversionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OTLPConversionError";
+  }
+};
 
 // src/proto/diagnostics.ts
 var DEFAULT_BUFFER_SIZE = 32;
@@ -208,8 +219,8 @@ function extractId(response) {
 }
 
 // src/version.ts
-var VERSION = "1.0.0-rc.1";
-var ENGINE_VERSION = "1.0.0-rc.1";
+var VERSION = "1.0.0-rc.3";
+var ENGINE_VERSION = "1.0.0-rc.3";
 
 // src/engine-manager.ts
 import { spawn, spawnSync } from "child_process";
@@ -277,7 +288,7 @@ function httpsGet(url, redirectCount = 0) {
       new Error(`Too many redirects (>${MAX_REDIRECTS}) following ${url}`)
     );
   }
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve4, reject) => {
     const client = url.startsWith("https:") ? https : http;
     client.get(url, (res) => {
       const status = res.statusCode ?? 0;
@@ -288,7 +299,7 @@ function httpsGet(url, redirectCount = 0) {
           return;
         }
         res.resume();
-        resolve(httpsGet(location, redirectCount + 1));
+        resolve4(httpsGet(location, redirectCount + 1));
         return;
       }
       if (status < 200 || status >= 300) {
@@ -298,7 +309,7 @@ function httpsGet(url, redirectCount = 0) {
       }
       const chunks = [];
       res.on("data", (chunk) => chunks.push(chunk));
-      res.on("end", () => resolve(Buffer.concat(chunks)));
+      res.on("end", () => resolve4(Buffer.concat(chunks)));
       res.on("error", reject);
     }).on("error", reject);
   });
@@ -429,8 +440,8 @@ Install options:
   }
   return [await downloadEngine(), "download"];
 }
-async function resolveEngine(explicitPath, options = {}) {
-  const [enginePath, source] = await locateEngine(explicitPath, options.allowDownload ?? true);
+async function resolveEngine(explicitPath, options2 = {}) {
+  const [enginePath, source] = await locateEngine(explicitPath, options2.allowDownload ?? true);
   const found = engineVersion(enginePath);
   if (found !== ENGINE_VERSION) {
     throw new EngineVersionMismatchError(enginePath, source, found, ENGINE_VERSION);
@@ -445,9 +456,9 @@ var EngineManager = class {
   initialized = false;
   requestId = 0;
   initResult = null;
-  constructor(options) {
-    this.enginePath = options?.enginePath ?? "";
-    this.logLevel = options?.logLevel ?? "warn";
+  constructor(options2) {
+    this.enginePath = options2?.enginePath ?? "";
+    this.logLevel = options2?.logLevel ?? "warn";
   }
   async start() {
     this.enginePath = await resolveEngine(this.enginePath || void 0);
@@ -525,11 +536,11 @@ var EngineManager = class {
     }
     this.requestId += 1;
     const requestStr = encodeRequest(this.requestId, method, params);
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve4, reject) => {
       const onLine = (line) => {
         try {
           const response = decodeResponse(line);
-          resolve(extractResult(response));
+          resolve4(extractResult(response));
         } catch (err) {
           reject(err);
         }
@@ -563,17 +574,17 @@ var EngineManager = class {
 // src/config.ts
 var _simulationMode = false;
 var _sampleRate = 0;
-function config(options) {
-  if (options.simulation !== void 0) {
-    _simulationMode = options.simulation;
+function config(options2) {
+  if (options2.simulation !== void 0) {
+    _simulationMode = options2.simulation;
   }
-  if (options.sampleRate !== void 0) {
-    if (options.sampleRate < 0 || options.sampleRate > 1) {
+  if (options2.sampleRate !== void 0) {
+    if (options2.sampleRate < 0 || options2.sampleRate > 1) {
       throw new RangeError(
-        `sampleRate must be between 0.0 and 1.0, got ${options.sampleRate}`
+        `sampleRate must be between 0.0 and 1.0, got ${options2.sampleRate}`
       );
     }
-    _sampleRate = options.sampleRate;
+    _sampleRate = options2.sampleRate;
   }
 }
 function isSimulationMode() {
@@ -602,6 +613,76 @@ function resetConfig() {
   _sampleRate = 0;
 }
 
+// src/usage.ts
+var INT_FIELDS = [
+  "model_calls",
+  "judge_calls",
+  "input_tokens",
+  "output_tokens",
+  "cached_tokens",
+  "unpriced_calls",
+  "budget_refused"
+];
+var USD_FIELDS = ["cost_usd", "retry_cost_usd"];
+function zeroUsage() {
+  return {
+    model_calls: 0,
+    judge_calls: 0,
+    input_tokens: 0,
+    output_tokens: 0,
+    cached_tokens: 0,
+    cost_usd: 0,
+    retry_cost_usd: 0,
+    unpriced_calls: 0,
+    budget_refused: 0
+  };
+}
+function addUsage(a, b) {
+  return {
+    model_calls: a.model_calls + b.model_calls,
+    judge_calls: a.judge_calls + b.judge_calls,
+    input_tokens: a.input_tokens + b.input_tokens,
+    output_tokens: a.output_tokens + b.output_tokens,
+    cached_tokens: a.cached_tokens + b.cached_tokens,
+    cost_usd: a.cost_usd + b.cost_usd,
+    retry_cost_usd: a.retry_cost_usd + b.retry_cost_usd,
+    unpriced_calls: a.unpriced_calls + b.unpriced_calls,
+    budget_refused: a.budget_refused + b.budget_refused
+  };
+}
+function sumUsage(usages) {
+  let total = zeroUsage();
+  for (const u of usages) total = addUsage(total, u);
+  return total;
+}
+function parseUsage(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new TypeError(`evaluate_batch result: usage must be an object, got ${JSON.stringify(raw)}`);
+  }
+  const obj = raw;
+  const field = (name, integer) => {
+    const v = obj[name];
+    if (typeof v !== "number" || !Number.isFinite(v) || v < 0 || integer && !Number.isInteger(v)) {
+      const kind = integer ? "a non-negative integer" : "a non-negative number";
+      throw new TypeError(`evaluate_batch result: usage.${name} must be ${kind}, got ${JSON.stringify(v)}`);
+    }
+    return v;
+  };
+  const ints = Object.fromEntries(INT_FIELDS.map((f) => [f, field(f, true)]));
+  const usd = Object.fromEntries(USD_FIELDS.map((f) => [f, field(f, false)]));
+  return { ...ints, ...usd };
+}
+function formatUsage(u) {
+  let line = `${u.model_calls} model calls \xB7 ${u.input_tokens + u.output_tokens} tokens (${u.cached_tokens} cached) \xB7 $${u.cost_usd.toFixed(4)} \xB7 retry cost $${u.retry_cost_usd.toFixed(4)}`;
+  if (u.budget_refused > 0) line += ` \xB7 ${u.budget_refused} calls refused by budget`;
+  if (u.unpriced_calls > 0) line += ` \xB7 ${u.unpriced_calls} unpriced calls not in $`;
+  return line;
+}
+function usageSummaryLine(u) {
+  if (u.model_calls === 0 && u.budget_refused === 0) return void 0;
+  return `attest usage: ${formatUsage(u)}`;
+}
+
 // src/client.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_DIAGNOSTIC_BUFFER = 32;
@@ -659,16 +740,16 @@ var AttestClient = class {
   desyncThreshold;
   desyncWindowMs;
   desynced = false;
-  constructor(engine, options) {
+  constructor(engine, options2) {
     this.engine = engine;
-    this.logger = options?.logger ?? envLoggerDefault();
+    this.logger = options2?.logger ?? envLoggerDefault();
     this.diagnosticBuffer = new ProtocolDiagnosticBuffer(
-      options?.diagnosticBufferSize ?? DEFAULT_DIAGNOSTIC_BUFFER
+      options2?.diagnosticBufferSize ?? DEFAULT_DIAGNOSTIC_BUFFER
     );
-    this.desyncThreshold = options?.desyncThreshold ?? DEFAULT_DESYNC_THRESHOLD;
-    this.desyncWindowMs = options?.desyncWindowMs ?? DEFAULT_DESYNC_WINDOW_MS;
-    if (options?.onDiagnostic !== void 0) {
-      this.diagnosticListeners.add(options.onDiagnostic);
+    this.desyncThreshold = options2?.desyncThreshold ?? DEFAULT_DESYNC_THRESHOLD;
+    this.desyncWindowMs = options2?.desyncWindowMs ?? DEFAULT_DESYNC_WINDOW_MS;
+    if (options2?.onDiagnostic !== void 0) {
+      this.diagnosticListeners.add(options2.onDiagnostic);
     }
   }
   /** Subscribe to protocol diagnostics. Returns an unsubscribe function. */
@@ -826,12 +907,12 @@ var AttestClient = class {
       throw new Error("Engine process not started.");
     }
     let capturedReqId;
-    const requestPromise = new Promise((resolve, reject) => {
+    const requestPromise = new Promise((resolve4, reject) => {
       this.writeChain = this.writeChain.then(() => {
         this.requestId += 1;
         const reqId = this.requestId;
         capturedReqId = reqId;
-        this.pending.set(reqId, { resolve, reject });
+        this.pending.set(reqId, { resolve: resolve4, reject });
         const requestStr = encodeRequest(reqId, method, params);
         cp.stdin.write(requestStr, (err) => {
           if (err) {
@@ -849,22 +930,23 @@ var AttestClient = class {
       throw err;
     });
   }
-  async evaluateBatch(trace, assertions, options) {
+  async evaluateBatch(trace, assertions, options2) {
     if (isSimulationMode()) {
       requireSimulationCapability(this.engine["initResult"]);
     }
     const params = {
       trace,
-      assertions: [...assertions]
+      assertions: [...assertions],
+      ...options2?.budget !== void 0 ? { budget: options2.budget } : {}
     };
     const raw = await this.sendRequest(
       "evaluate_batch",
       params,
-      options?.timeout
+      options2?.timeout
     );
-    return raw;
+    return { ...raw, usage: parseUsage(raw["usage"]) };
   }
-  async submitPluginResult(traceId2, pluginName, assertionId2, status, score, explanation, options) {
+  async submitPluginResult(traceId2, pluginName, assertionId2, status, score, explanation, options2) {
     const result = {
       assertion_id: assertionId2,
       status,
@@ -882,11 +964,11 @@ var AttestClient = class {
     const raw = await this.sendRequest(
       "submit_plugin_result",
       params,
-      options?.timeout
+      options2?.timeout
     );
     return Boolean(raw?.accepted ?? false);
   }
-  async queryDrift(assertionId2, windowSize = 50, options) {
+  async queryDrift(assertionId2, windowSize = 50, options2) {
     if (isSimulationMode()) {
       return {
         assertion_id: assertionId2,
@@ -901,11 +983,11 @@ var AttestClient = class {
     const raw = await this.sendRequest(
       "query_drift",
       { assertion_id: assertionId2, window_size: windowSize },
-      options?.timeout
+      options2?.timeout
     );
     return raw.report;
   }
-  async generateUserMessage(persona, conversationHistory, faultConfig, options) {
+  async generateUserMessage(persona, conversationHistory, faultConfig, options2) {
     if (isSimulationMode()) {
       return `[simulation] Hello from ${persona.name}`;
     }
@@ -919,7 +1001,7 @@ var AttestClient = class {
     const raw = await this.sendRequest(
       "generate_user_message",
       params,
-      options?.timeout
+      options2?.timeout
     );
     return String(raw.message);
   }
@@ -964,33 +1046,33 @@ var TraceBuilder = class {
     this.input = input;
     return this;
   }
-  addLlmCall(name, options) {
+  addLlmCall(name, options2) {
     this.steps.push({
       type: STEP_LLM_CALL,
       name,
-      args: options?.args,
-      result: options?.result,
-      metadata: options?.metadata
+      args: options2?.args,
+      result: options2?.result,
+      metadata: options2?.metadata
     });
     return this;
   }
-  addToolCall(name, options) {
+  addToolCall(name, options2) {
     this.steps.push({
       type: STEP_TOOL_CALL,
       name,
-      args: options?.args,
-      result: options?.result,
-      metadata: options?.metadata
+      args: options2?.args,
+      result: options2?.result,
+      metadata: options2?.metadata
     });
     return this;
   }
-  addRetrieval(name, options) {
+  addRetrieval(name, options2) {
     this.steps.push({
       type: STEP_RETRIEVAL,
       name,
-      args: options?.args,
-      result: options?.result,
-      metadata: options?.metadata
+      args: options2?.args,
+      result: options2?.result,
+      metadata: options2?.metadata
     });
     return this;
   }
@@ -1050,11 +1132,14 @@ var AgentResult = class {
   assertionResults;
   totalCost;
   totalDurationMs;
-  constructor(trace, assertionResults = [], totalCost = 0, totalDurationMs = 0) {
+  /** Attest model usage of the evaluation that produced this result. */
+  usage;
+  constructor(trace, assertionResults = [], totalCost = 0, totalDurationMs = 0, usage = zeroUsage()) {
     this.trace = trace;
     this.assertionResults = assertionResults.map(normalizeAssertionResult);
     this.totalCost = totalCost;
     this.totalDurationMs = totalDurationMs;
+    this.usage = usage;
   }
   /** True if every assertion has status "pass". */
   get passed() {
@@ -1065,10 +1150,10 @@ var AgentResult = class {
    * not_evaluated skips (fails when `strict`); otherwise pass, including
    * when only soft_fail rows are present (see `softFailures`).
    */
-  outcome(options) {
+  outcome(options2) {
     if (this.hardFailures.length > 0) return OUTCOME_FAIL;
     if (this.notEvaluated.length > 0) {
-      return options?.strict === true ? OUTCOME_FAIL : OUTCOME_SKIP;
+      return options2?.strict === true ? OUTCOME_FAIL : OUTCOME_SKIP;
     }
     return OUTCOME_PASS;
   }
@@ -1178,9 +1263,9 @@ function truncate(value, limit = 280) {
   }
   return value.slice(0, limit - 3) + "...";
 }
-function renderAssertionFailure(result, options = {}) {
-  const color = options.color ?? false;
-  const testFile = options.testFile;
+function renderAssertionFailure(result, options2 = {}) {
+  const color = options2.color ?? false;
+  const testFile = options2.testFile;
   const layer = result.layer ?? 0;
   const label = layerLabel(layer, result.type);
   const lines = [];
@@ -1233,7 +1318,8 @@ function appendJudgeMetadata(lines, meta) {
     if (meta.rubric_version) {
       rubric = `${rubric} @ ${meta.rubric_version}`;
     }
-    lines.push(`      judge:      ${meta.model} / ${rubric}`);
+    const judge = meta.provider ? `${meta.provider}/${meta.model}` : meta.model;
+    lines.push(`      judge:      ${judge} / ${rubric}`);
   }
   if (meta.prompt_hash) {
     lines.push(`      prompt:     #${meta.prompt_hash}`);
@@ -1260,8 +1346,8 @@ function appendJudgeMetadata(lines, meta) {
     );
   }
 }
-function renderSummary(result, options = {}) {
-  const color = options.color ?? false;
+function renderSummary(result, options2 = {}) {
+  const color = options2.color ?? false;
   const passN = result.passCount;
   const soft = result.assertionResults.filter(
     (r) => r.status === STATUS_SOFT_FAIL
@@ -1279,9 +1365,9 @@ function renderSummary(result, options = {}) {
   ];
   return parts.join(" | ");
 }
-function renderDiagnostics(result, options = {}) {
-  const color = options.color ?? false;
-  const includePassing = options.includePassing ?? false;
+function renderDiagnostics(result, options2 = {}) {
+  const color = options2.color ?? false;
+  const includePassing = options2.includePassing ?? false;
   const rows = includePassing ? result.assertionResults : result.assertionResults.filter((r) => r.status !== STATUS_PASS);
   if (rows.length === 0) {
     return dim("  (no failures)\n", color);
@@ -1289,7 +1375,7 @@ function renderDiagnostics(result, options = {}) {
   const out = [""];
   out.push(bold(`Attest diagnostic \u2014 ${headerCounts(result)}:`, color));
   for (const r of rows) {
-    out.push(renderAssertionFailure(r, options));
+    out.push(renderAssertionFailure(r, options2));
   }
   out.push(dim(`  Summary: ${renderSummary(result, { color })}`, color));
   return out.join("\n");
@@ -1406,9 +1492,64 @@ var TraceTree = class {
 
 // src/expect.ts
 import { randomUUID as randomUUID2 } from "crypto";
+var MAX_WORLD_BYTES = 9 * 1024 * 1024;
+var WorldChecks = class {
+  _snapshot;
+  _add;
+  constructor(snapshot, add) {
+    this._snapshot = snapshot;
+    this._add = add;
+  }
+  addCheck(spec, where) {
+    const full = { ...spec, world: this._snapshot };
+    if (where !== void 0 && Object.keys(where).length > 0) full.where = where;
+    return this._add(full);
+  }
+  /**
+   * Assert how many records of `resource` match `where`. Give `equals`, or `atMost` and/or
+   * `atLeast`. A violation reads `effect violated: 2 refunds for O-1042 (expected 1)`.
+   *
+   * @throws Error when no bound is given, or `equals` is combined with another bound.
+   *
+   * @example
+   * ```ts
+   * expect(trace).world(await world.state()).count("refunds", { equals: 1, where: { order_id: "O-1042" } });
+   * ```
+   */
+  count(resource, opts) {
+    if (opts.equals === void 0 && opts.atMost === void 0 && opts.atLeast === void 0) {
+      throw new Error("count needs equals, atMost or atLeast");
+    }
+    if (opts.equals !== void 0 && (opts.atMost !== void 0 || opts.atLeast !== void 0)) {
+      throw new Error("count: equals excludes atMost and atLeast");
+    }
+    const spec = { check: "count", resource };
+    if (opts.equals !== void 0) spec.equals = opts.equals;
+    if (opts.atMost !== void 0) spec.at_most = opts.atMost;
+    if (opts.atLeast !== void 0) spec.at_least = opts.atLeast;
+    return this.addCheck(spec, opts.where);
+  }
+  /** Assert no two matching records share the same values for field(s) `by`. */
+  unique(resource, opts) {
+    const fields = typeof opts.by === "string" ? [opts.by] : [...opts.by];
+    if (fields.length === 0) throw new Error("unique needs at least one field in by");
+    return this.addCheck({ check: "unique", resource, fields }, opts.where);
+  }
+  /**
+   * Assert every matching record carries a distinct value in field `key` (default
+   * `idempotency_key`), the record field that stores the idempotency key.
+   */
+  idempotent(resource, opts = {}) {
+    return this.addCheck(
+      { check: "idempotent", resource, field: opts.key ?? "idempotency_key" },
+      opts.where
+    );
+  }
+};
 var ExpectChain = class {
   _result;
   _assertions = [];
+  _worldBytes = 0;
   constructor(result) {
     this._result = result;
   }
@@ -1757,6 +1898,104 @@ var ExpectChain = class {
       soft: opts?.soft ?? false
     });
   }
+  // -- Layer 3: Behavior contracts (tool calls only, retries counted) --
+  /**
+   * Assert how many times a tool is called, per value of argument `per` when set.
+   *
+   * @example
+   * ```ts
+   * // fails with "issue_refund called 2× for order_id=O-1042 (max 1)"
+   * expect(result).toolCardinality("issue_refund", { per: "order_id", atMost: 1 });
+   * ```
+   */
+  toolCardinality(tool, opts) {
+    if (opts.atMost === void 0 && opts.atLeast === void 0) {
+      throw new Error("toolCardinality needs atMost, atLeast or both");
+    }
+    const spec = { check: "tool_cardinality", tool };
+    if (opts.per !== void 0) spec.per = opts.per;
+    if (opts.atLeast !== void 0) spec.min = opts.atLeast;
+    if (opts.atMost !== void 0) spec.max = opts.atMost;
+    spec.soft = opts.soft ?? false;
+    return this.add(TYPE_TRACE, spec);
+  }
+  /**
+   * Assert the tool-call trajectory matches `tools`: `strict` (same sequence,
+   * the default), `unordered` (same calls, any order), `subset` (no call
+   * outside `tools`) or `superset` (every call in `tools` made). Use
+   * {@link trajectoryPartialOrder} for ordering constraints.
+   */
+  trajectory(tools, opts) {
+    return this.add(TYPE_TRACE, {
+      check: "trajectory",
+      mode: opts?.mode ?? "strict",
+      tools,
+      soft: opts?.soft ?? false
+    });
+  }
+  /**
+   * Assert every tool in `tools` and `order` is called and each
+   * `[before, after]` pair holds as in {@link toolCalledBefore}.
+   */
+  trajectoryPartialOrder(order, opts) {
+    const spec = {
+      check: "trajectory",
+      mode: "partial_order",
+      order: order.map(([before, after]) => [before, after])
+    };
+    if (opts?.tools !== void 0) spec.tools = opts.tools;
+    spec.soft = opts?.soft ?? false;
+    return this.add(TYPE_TRACE, spec);
+  }
+  /** Assert every call to `after` has an earlier call to `before`; holds when `after` is never called. */
+  toolCalledBefore(before, after, opts) {
+    return this.add(TYPE_TRACE, { check: "tool_order", before, after, soft: opts?.soft ?? false });
+  }
+  /** Assert no block of `period` (1–4) tool calls repeats `minRepeats` (default 2) times in a row; A→B→A→B fails period 2. */
+  noToolCycles(period, opts) {
+    return this.add(TYPE_TRACE, {
+      check: "cycle",
+      period,
+      min_repeats: opts?.minRepeats ?? 2,
+      soft: opts?.soft ?? false
+    });
+  }
+  /** Assert at most `maxStreak` consecutive tool calls end in error (trace v2). */
+  maxToolFailureStreak(maxStreak, opts) {
+    return this.add(TYPE_TRACE, { check: "failure_streak", max: maxStreak, soft: opts?.soft ?? false });
+  }
+  /**
+   * Assert every call to `tool` has argument `arg` (a dot path) satisfying
+   * `op value`; holds when `tool` is never called.
+   */
+  toolArgSatisfies(tool, arg, op, value, opts) {
+    return this.add(TYPE_TRACE, {
+      check: "arg_predicate",
+      tool,
+      arg,
+      op,
+      value,
+      soft: opts?.soft ?? false
+    });
+  }
+  // -- Layer 3: Effect checks (the external system the agent acted on) --
+  /**
+   * Check effects in a world snapshot:
+   * `expect(trace).world(await world.state()).count(...)`. `null` means the test ran without
+   * a world helper: the checks are `not_evaluated` (`missing_evidence`).
+   */
+  world(snapshot) {
+    const size = new TextEncoder().encode(JSON.stringify(snapshot)).length;
+    return new WorldChecks(snapshot, (spec) => {
+      this._worldBytes += size;
+      if (this._worldBytes > MAX_WORLD_BYTES) {
+        throw new Error(
+          `effect checks would send the ${size}-byte world snapshot ${Math.floor(this._worldBytes / Math.max(size, 1))} times (${this._worldBytes} bytes), over the ${MAX_WORLD_BYTES}-byte limit of one request; use fewer checks per test or scope the world to less state`
+        );
+      }
+      return this.add(TYPE_EFFECT, spec);
+    });
+  }
   // -- Layer 4: Content --
   /**
    * Assert the output message contains the given string.
@@ -2250,6 +2489,728 @@ function attestExpect(result) {
   return new ExpectChain(new AgentResult(result));
 }
 
+// src/capture.ts
+import { spawn as spawn2 } from "child_process";
+import * as fs2 from "fs";
+import * as path2 from "path";
+import { fileURLToPath } from "url";
+var FIXTURE_VERSION = 1;
+var DEFAULT_FIXTURE_DIR = path2.join("tests", "attest", "fixtures");
+var CaptureError = class extends Error {
+  /** The fixture written, when the engine wrote one. */
+  fixture;
+  constructor(message, fixture = null) {
+    super(message);
+    this.name = "CaptureError";
+    this.fixture = fixture;
+  }
+};
+function toPath(p) {
+  return p instanceof URL ? fileURLToPath(p) : p;
+}
+function loadFixture(file) {
+  const p = toPath(file);
+  const doc = JSON.parse(fs2.readFileSync(p, "utf8"));
+  if (!isObject(doc) || doc["fixture_version"] !== FIXTURE_VERSION) {
+    throw new CaptureError(`${p}: not a fixture_version ${FIXTURE_VERSION} capture fixture`);
+  }
+  validate(p, doc);
+  return doc;
+}
+var NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function kindOf(v) {
+  if (Array.isArray(v)) return "array";
+  if (isObject(v)) return "object";
+  if (typeof v === "string" || typeof v === "boolean") return typeof v;
+  return "other";
+}
+function validate(p, doc) {
+  const need = (where, obj, fields) => {
+    if (!isObject(obj)) throw new CaptureError(`${p}: ${where} is not an object`);
+    for (const [key, kind] of Object.entries(fields)) {
+      if (kindOf(obj[key]) !== kind) throw new CaptureError(`${p}: ${where}.${key} is missing or not a ${kind}`);
+    }
+    return obj;
+  };
+  need("fixture", doc, { name: "string", source: "object", trace: "object", exchanges: "array", contracts: "array", verification: "object" });
+  if (!("world" in doc)) throw new CaptureError(`${p}: fixture.world is missing`);
+  if (!NAME_PATTERN.test(doc["name"])) {
+    throw new CaptureError(`${p}: fixture name ${JSON.stringify(doc["name"])} is not a valid fixture name`);
+  }
+  const v = need("fixture.verification", doc["verification"], {
+    verified: "boolean",
+    expect_fail: "boolean",
+    results: "array",
+    expected_failures: "array"
+  });
+  doc["contracts"].forEach(
+    (c, i) => need(`fixture.contracts[${i}]`, c, { id: "string", kind: "string", description: "string", type: "string", spec: "object" })
+  );
+  v["results"].forEach(
+    (r, i) => need(`fixture.verification.results[${i}]`, r, { contract: "string", status: "string", explanation: "string" })
+  );
+}
+function objectKey(k) {
+  if (k === "__proto__") return `[${JSON.stringify(k)}]`;
+  return /^[A-Za-z_$][\w$]*$/.test(k) ? k : JSON.stringify(k);
+}
+function comment(text) {
+  return text.replace(/[\p{Cc}\p{Zl}\p{Zp}]/gu, " ");
+}
+function ts(value) {
+  if (value === null || typeof value === "boolean" || typeof value === "number") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "string") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(ts).join(", ")}]`;
+  if (typeof value === "object") {
+    const entries = Object.entries(value).map(
+      ([k, v]) => `${objectKey(k)}: ${ts(v)}`
+    );
+    return entries.length === 0 ? "{}" : `{ ${entries.join(", ")} }`;
+  }
+  throw new Error(`value ${String(value)} has no literal`);
+}
+function str(spec, key) {
+  const v = spec[key];
+  if (typeof v !== "string") throw new Error(`missing ${key}`);
+  return v;
+}
+function options(entries) {
+  const set = entries.filter(([, v]) => v !== void 0 && v !== null && v !== false);
+  return set.length === 0 ? "" : `{ ${set.map(([k, v]) => `${k}: ${ts(v)}`).join(", ")} }`;
+}
+function call(method, args, opts) {
+  return `.${method}(${[...args, ...opts ? [opts] : []].join(", ")})`;
+}
+function dslCall(contract) {
+  const s = contract.spec;
+  const soft = s["soft"] === true ? true : void 0;
+  try {
+    if (contract.type === "trace") {
+      const check = s["check"];
+      if (check === "trajectory" && s["mode"] !== "partial_order") {
+        const mode = s["mode"] === "strict" || s["mode"] === void 0 ? void 0 : s["mode"];
+        if (!Array.isArray(s["tools"])) throw new Error("missing tools");
+        return call("trajectory", [ts(s["tools"])], options([["mode", mode], ["soft", soft]]));
+      }
+      if (check === "tool_order") {
+        return call("toolCalledBefore", [ts(str(s, "before")), ts(str(s, "after"))], options([["soft", soft]]));
+      }
+      if (check === "tool_cardinality") {
+        return call(
+          "toolCardinality",
+          [ts(str(s, "tool"))],
+          options([
+            ["per", s["per"]],
+            ["atLeast", s["min"]],
+            ["atMost", s["max"]],
+            ["soft", soft]
+          ])
+        );
+      }
+    }
+    if (contract.type === "schema" && s["target"] === "output.structured") {
+      if (typeof s["schema"] !== "object" || s["schema"] === null) throw new Error("missing schema");
+      return call("outputMatchesSchema", [ts(s["schema"])], "");
+    }
+    if (contract.type === "constraint" && s["field"] === "metadata.cost_usd" && s["operator"] === "lte") {
+      if (typeof s["value"] !== "number") throw new Error("missing value");
+      return call("costUnder", [ts(s["value"])], options([["soft", soft]]));
+    }
+  } catch (err) {
+    throw new Error(`contract ${contract.id}: malformed spec (${err.message})`);
+  }
+  throw new Error(`contract ${contract.id}: no TypeScript DSL call for ${contract.type} spec`);
+}
+function testPathFor(fixturePath) {
+  const name = path2.basename(fixturePath).replace(/\.attest\.json$/, "");
+  return path2.join(path2.dirname(path2.dirname(fixturePath)), `${name}.test.ts`);
+}
+function renderVitest(fixture, fixturePath, testPath) {
+  const calls = [];
+  const skipped = [];
+  for (const c of fixture.contracts) {
+    try {
+      calls.push([c, dslCall(c)]);
+    } catch (err) {
+      skipped.push(err.message);
+    }
+  }
+  const rel = path2.relative(path2.dirname(testPath), fixturePath).split(path2.sep).join("/");
+  const status = new Map(fixture.verification.results.map((r) => [r.contract, r.status]));
+  const expectFail = fixture.verification.expect_fail;
+  const lines = [
+    `// Contracts drafted by \`attest capture\` from fixture ${comment(ts(fixture.name))}.`,
+    "//",
+    "// Review and edit before committing: they check the captured trace without running",
+    "// the agent. Re-capturing does not overwrite this file.",
+    `import { attestExpect, loadFixture, type ExpectChain } from "@attest-ai/core";`,
+    `import { ${expectFail ? "inspect" : "evaluate"} } from "@attest-ai/vitest";`,
+    `import { describe, ${expectFail ? "expect, " : ""}it } from "vitest";`,
+    "",
+    `const FIXTURE = loadFixture(new URL(${ts(rel.startsWith(".") ? rel : `./${rel}`)}, import.meta.url));`
+  ];
+  if (skipped.length > 0) {
+    lines.push("", "// Drafted contracts without a TypeScript DSL call (left out):");
+    for (const s of skipped) lines.push(`// - ${comment(s)}`);
+  }
+  lines.push("", "function contracts(): ExpectChain {", "  return attestExpect(FIXTURE.trace)");
+  for (const [c, dsl] of calls) {
+    lines.push(`    // ${comment(`${c.id}: ${c.description}`)}`, `    ${dsl}`);
+  }
+  lines[lines.length - 1] += ";";
+  lines.push("}");
+  if (expectFail) {
+    lines.push("", "// Status of each contract on the captured incident, in contracts() order.");
+    lines.push("const EXPECTED: Array<[string, string]> = [");
+    for (const [c] of calls) lines.push(`  [${ts(c.id)}, ${ts(status.get(c.id) ?? "pass")}],`);
+    lines.push(
+      "];",
+      "",
+      `describe(${ts(fixture.name)}, () => {`,
+      `  it("reproduces the incident", async () => {`,
+      "    const result = await inspect(contracts());",
+      "",
+      "    expect(result.assertionResults.map((row) => row.status)).toEqual(EXPECTED.map(([, s]) => s));",
+      "  });",
+      "});"
+    );
+  } else {
+    lines.push(
+      "",
+      `describe(${ts(fixture.name)}, () => {`,
+      `  it("keeps its drafted contracts", async () => {`,
+      "    await evaluate(contracts());",
+      "  });",
+      "});"
+    );
+  }
+  return `${lines.join("\n")}
+`;
+}
+function emitVitest(fixturePath) {
+  const testPath = testPathFor(fixturePath);
+  const existing = fs2.lstatSync(testPath, { throwIfNoEntry: false });
+  if (existing?.isSymbolicLink()) {
+    throw new CaptureError(`${testPath} is a symbolic link; refusing to draft a test through it`);
+  }
+  if (existing !== void 0) return null;
+  const source = renderVitest(loadFixture(fixturePath), fixturePath, testPath);
+  fs2.mkdirSync(path2.dirname(testPath), { recursive: true });
+  try {
+    fs2.writeFileSync(testPath, source, { encoding: "utf8", flag: "wx" });
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      throw new CaptureError(`${testPath} appeared while drafting; left unchanged`);
+    }
+    throw err;
+  }
+  return testPath;
+}
+function serve(engine, args) {
+  const child = spawn2(engine, args, { stdio: ["pipe", "pipe", "pipe"] });
+  let stdout = "";
+  let stderr = "";
+  let resolveReady = () => void 0;
+  const ready = new Promise((resolve4) => {
+    resolveReady = resolve4;
+  });
+  const exited = new Promise((resolve4) => {
+    child.on("close", (code, signal) => {
+      resolveReady(null);
+      resolve4({ code, signal });
+    });
+    child.on("error", (err) => {
+      stderr += err.message;
+      resolveReady(null);
+      resolve4({ code: null, signal: null });
+    });
+  });
+  child.stdout.setEncoding("utf8").on("data", (chunk) => {
+    stdout += chunk;
+    const nl = stdout.indexOf("\n");
+    if (nl >= 0) resolveReady(stdout.slice(0, nl));
+  });
+  child.stderr.setEncoding("utf8").on("data", (chunk) => {
+    stderr += chunk;
+  });
+  child.stdin.on("error", () => void 0);
+  return {
+    ready,
+    async finish(finalize) {
+      if (finalize) {
+        const environ = Object.entries(process.env).flatMap(([k, v]) => v === void 0 ? [] : [`${k}=${v}`]);
+        child.stdin.write(`${JSON.stringify({ finalize: true, environ })}
+`);
+      }
+      child.stdin.end();
+      const { code, signal } = await exited;
+      return { code, signal, stdout, stderr };
+    }
+  };
+}
+function readyEnv(line) {
+  if (line === null) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  const env = parsed?.env;
+  if (typeof env !== "object" || env === null) return null;
+  const entries = Object.entries(env);
+  if (!entries.every(([, v]) => typeof v === "string")) return null;
+  return Object.fromEntries(entries);
+}
+function exitDetail(exit) {
+  const how = exit.signal !== null ? `killed by ${exit.signal}` : `exit ${String(exit.code)}`;
+  const err = exit.stderr.trim();
+  return err ? `${how}: ${err}` : how;
+}
+function restore(saved) {
+  for (const [k, v] of saved) {
+    if (v === void 0) delete process.env[k];
+    else process.env[k] = v;
+  }
+}
+var recording = false;
+async function record(name, fn, opts = {}) {
+  if (recording) throw new CaptureError("record() is already running; captures cannot overlap");
+  recording = true;
+  try {
+    return await recordExclusive(name, fn, opts);
+  } finally {
+    recording = false;
+  }
+}
+async function recordExclusive(name, fn, opts) {
+  const engine = await resolveEngine(opts.enginePath);
+  const args = ["capture", "--serve", "--name", name, "--out-dir", opts.outDir ?? DEFAULT_FIXTURE_DIR];
+  if (opts.expectFail) args.push("--expect-fail");
+  if (opts.agentId !== void 0) args.push("--agent-id", opts.agentId);
+  if (opts.world !== void 0) args.push("--world", path2.resolve(opts.world));
+  const proc = serve(engine, args);
+  const env = readyEnv(await proc.ready);
+  if (env === null) {
+    const exit2 = await proc.finish(false);
+    throw new CaptureError(`attest-engine capture --serve did not start (${exitDetail(exit2)})`);
+  }
+  const saved = new Map(Object.keys(env).map((k) => [k, process.env[k]]));
+  Object.assign(process.env, env);
+  let value;
+  try {
+    value = await fn({ name, env });
+    if (opts.flush) await opts.flush();
+  } catch (err) {
+    restore(saved);
+    await proc.finish(false);
+    throw err;
+  }
+  restore(saved);
+  const exit = await proc.finish(true);
+  process.stderr.write(exit.stderr);
+  const lines = exit.stdout.trim().split("\n");
+  if (lines.length < 2) {
+    throw new CaptureError(`capture ${name} wrote no fixture (${exitDetail(exit)})`);
+  }
+  const outcome = JSON.parse(lines[lines.length - 1] ?? "");
+  if (exit.code !== 0 || !outcome.verified) {
+    throw new CaptureError(`capture ${name}: fixture ${outcome.fixture} is not verified; no test drafted`, outcome.fixture);
+  }
+  const testFile = opts.emitTest === false ? null : emitVitest(outcome.fixture);
+  return { value, fixture: outcome.fixture, verified: true, testFile };
+}
+
+// src/replay.ts
+import { spawn as spawn3 } from "child_process";
+import * as path3 from "path";
+
+// src/egress.ts
+import * as net from "net";
+var PROVIDER_HOSTS = [
+  "api.openai.com",
+  "api.anthropic.com",
+  "generativelanguage.googleapis.com",
+  /\.openai\.azure\.com$/
+];
+var EgressBlockedError = class extends Error {
+  constructor(host) {
+    super(
+      `attest egress guard: connection to model provider ${host} blocked; the agent must reach models through the replay proxy (OPENAI_BASE_URL / ANTHROPIC_BASE_URL)`
+    );
+    this.host = host;
+    this.name = "EgressBlockedError";
+  }
+  host;
+};
+function isProviderHost(host) {
+  const h = host.toLowerCase().replace(/\.$/, "");
+  return PROVIDER_HOSTS.some((p) => typeof p === "string" ? p === h : p.test(h));
+}
+function egressBlockRequested(env = process.env) {
+  const v = (env.ATTEST_EGRESS ?? "").trim().toLowerCase();
+  if (v !== "" && v !== "block" && v !== "allow") {
+    throw new Error(`ATTEST_EGRESS must be block or allow, got ${JSON.stringify(env.ATTEST_EGRESS)}`);
+  }
+  return v === "block";
+}
+var original = null;
+var installs = 0;
+function hostOf(args) {
+  const first = Array.isArray(args[0]) ? args[0][0] : args[0];
+  if (typeof first === "object" && first !== null) {
+    const o = first;
+    return typeof o.host === "string" ? o.host : null;
+  }
+  if (typeof first === "number" || typeof first === "string" && /^\d+$/.test(first)) {
+    return typeof args[1] === "string" ? args[1] : null;
+  }
+  return null;
+}
+function installEgressGuard() {
+  installs++;
+  if (original === null) {
+    const proto = net.Socket.prototype;
+    const orig = proto.connect;
+    original = orig;
+    proto.connect = function(...args) {
+      const host = hostOf(args);
+      if (host !== null && isProviderHost(host)) {
+        const err = new EgressBlockedError(host);
+        process.nextTick(() => this.destroy(err));
+        return this;
+      }
+      return orig.apply(this, args);
+    };
+  }
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    installs--;
+    if (installs === 0) uninstallEgressGuard();
+  };
+}
+function egressGuardActive() {
+  return installs > 0;
+}
+function uninstallEgressGuard() {
+  installs = 0;
+  if (original === null) return;
+  net.Socket.prototype.connect = original;
+  original = null;
+}
+
+// src/replay.ts
+var ReplayMissError = class extends Error {
+  constructor(message, summary) {
+    super(message);
+    this.summary = summary;
+    this.name = "ReplayMissError";
+  }
+  summary;
+};
+var ReplayNotEvaluatedError = class extends Error {
+  constructor(message, summary) {
+    super(message);
+    this.summary = summary;
+    this.name = "ReplayNotEvaluatedError";
+  }
+  summary;
+};
+function escapeControl(text) {
+  return text.replace(/[\p{Cc}\p{Cf}]/gu, (c) => `\\u${(c.codePointAt(0) ?? 0).toString(16).padStart(4, "0")}`);
+}
+var ReplayError = class extends Error {
+  constructor(message) {
+    super(escapeControl(message));
+    this.name = "ReplayError";
+  }
+};
+function resolveMode(explicit, env = process.env) {
+  if (explicit !== void 0) return checkMode(explicit, "mode");
+  const fromEnv = (env.ATTEST_REPLAY ?? "").trim().toLowerCase();
+  if (fromEnv !== "") return checkMode(fromEnv, "ATTEST_REPLAY");
+  const ci = (env.CI ?? "").trim().toLowerCase();
+  return ci !== "" && ci !== "false" && ci !== "0" ? "strict" : "auto";
+}
+function checkMode(value, where) {
+  if (value === "strict" || value === "auto" || value === "off") return value;
+  throw new ReplayError(`${where} must be strict, auto or off, got ${JSON.stringify(value)}`);
+}
+var active = null;
+async function startReplay(name, opts = {}) {
+  if (!NAME_PATTERN.test(name)) throw new ReplayError(`invalid fixture name ${JSON.stringify(name)}`);
+  const resolved = resolveMode(opts.mode);
+  if (resolved === "off") return offSession(name);
+  const mode = resolved;
+  if (active !== null) throw new ReplayError(`replay of ${active} is already running; sessions cannot overlap`);
+  active = name;
+  try {
+    return await start(name, mode, opts);
+  } catch (err) {
+    active = null;
+    throw err;
+  }
+}
+function offSession(name) {
+  return {
+    name,
+    mode: "off",
+    env: {},
+    summary: null,
+    finish: () => Promise.resolve(null),
+    error: () => null,
+    check: () => Promise.resolve()
+  };
+}
+function missError(mode, summary) {
+  if (summary.misses === 0) return null;
+  const message = escapeControl(firstMiss(summary) ?? "replay miss");
+  return mode === "auto" ? new ReplayNotEvaluatedError(message, summary) : new ReplayMissError(message, summary);
+}
+async function start(name, mode, opts) {
+  const engine = await resolveEngine(opts.enginePath);
+  const fixturesDir = path3.resolve(opts.fixturesDir ?? DEFAULT_FIXTURE_DIR);
+  const blocking = egressGuardActive() || (opts.noLive ?? egressBlockRequested());
+  const args = ["replay", "--serve", "--name", name, "--fixtures-dir", fixturesDir, "--mode", mode];
+  if (blocking) args.push("--no-live");
+  const child = spawn3(engine, args, { stdio: ["pipe", "pipe", "pipe"] });
+  let stdout = "";
+  let stderr = "";
+  let resolveReady = () => void 0;
+  const ready = new Promise((resolve4) => {
+    resolveReady = resolve4;
+  });
+  const exited = new Promise((resolve4) => {
+    child.on("close", (code) => {
+      resolveReady(null);
+      resolve4(code);
+    });
+    child.on("error", (err) => {
+      stderr += err.message;
+      resolveReady(null);
+      resolve4(null);
+    });
+  });
+  child.stdout.setEncoding("utf8").on("data", (chunk) => {
+    stdout += chunk;
+    const nl = stdout.indexOf("\n");
+    if (nl >= 0) resolveReady(stdout.slice(0, nl));
+  });
+  child.stderr.setEncoding("utf8").on("data", (chunk) => {
+    stderr += chunk;
+  });
+  child.stdin.on("error", () => void 0);
+  const stop = async () => {
+    child.stdin.write("stop\n");
+    child.stdin.end();
+    return { code: await exited, stdout, stderr };
+  };
+  const env = parseEnv(await ready);
+  if (env === null) {
+    const out = await stop();
+    active = null;
+    throw new ReplayError(`attest-engine replay --serve did not start: ${out.stderr.trim() || `exit ${String(out.code)}`}`);
+  }
+  const saved = new Map(Object.keys(env).map((k) => [k, process.env[k]]));
+  Object.assign(process.env, env);
+  let summary = null;
+  let finishing = null;
+  const finish = () => {
+    finishing ??= (async () => {
+      for (const [k, v] of saved) {
+        if (v === void 0) delete process.env[k];
+        else process.env[k] = v;
+      }
+      const out = await stop();
+      active = null;
+      const parsed = parseSummary(out.stdout);
+      if (parsed === null) {
+        throw new ReplayError(`replay ${name} wrote no summary (exit ${String(out.code)}): ${out.stderr.trim()}`);
+      }
+      if (blocking && parsed.live > 0) {
+        throw new ReplayError(
+          `replay ${name}: ${String(parsed.live)} live model calls while the egress guard is blocking`
+        );
+      }
+      summary = parsed;
+      return parsed;
+    })();
+    return finishing;
+  };
+  return {
+    name,
+    mode,
+    env,
+    get summary() {
+      return summary;
+    },
+    finish,
+    error: () => summary === null ? null : missError(mode, summary),
+    check: async () => {
+      await finish();
+      const err = summary === null ? null : missError(mode, summary);
+      if (err !== null) throw err;
+    }
+  };
+}
+function parseEnv(line) {
+  if (line === null) return null;
+  try {
+    const env = JSON.parse(line).env;
+    if (typeof env !== "object" || env === null) return null;
+    const entries = Object.entries(env);
+    if (!entries.every(([, v]) => typeof v === "string")) return null;
+    return Object.fromEntries(entries);
+  } catch {
+    return null;
+  }
+}
+function parseSummary(out) {
+  const lines = out.trim().split("\n");
+  try {
+    const s = JSON.parse(lines[lines.length - 1] ?? "").summary;
+    if (s === void 0 || !Array.isArray(s.records)) return null;
+    for (const r of s.records) if (r.message !== void 0) r.message = escapeControl(r.message);
+    return s;
+  } catch {
+    return null;
+  }
+}
+function firstMiss(summary) {
+  return summary.records.find((r) => r.outcome === "miss")?.message ?? null;
+}
+function liveLine(live, costUsd, unpriced = 0) {
+  const line = `${String(live)} live model ${live === 1 ? "call" : "calls"} \xB7 $${costUsd.toFixed(2)}`;
+  return unpriced > 0 ? `${line} (+${String(unpriced)} unpriced)` : line;
+}
+
+// src/world.ts
+import { spawn as spawn4 } from "child_process";
+import * as path4 from "path";
+var STATE_PATH = "/_attest/state";
+var STATE_TIMEOUT_MS = 1e4;
+var WorldError = class extends Error {
+  constructor(message) {
+    super(escapeControl(message));
+    this.name = "WorldError";
+  }
+};
+var active2 = null;
+async function startWorld(worldFile, opts = {}) {
+  if (active2 !== null) throw new WorldError(`world ${active2} is already running; worlds cannot overlap`);
+  const file = path4.resolve(worldFile);
+  active2 = file;
+  try {
+    return await start2(file, opts);
+  } catch (err) {
+    active2 = null;
+    throw err;
+  }
+}
+async function start2(file, opts) {
+  const engine = await resolveEngine(opts.enginePath);
+  const child = spawn4(engine, ["world", "--file", file, "--serve"], { stdio: ["pipe", "pipe", "pipe"] });
+  let stdout = "";
+  let stderr = "";
+  let resolveReady = () => void 0;
+  const ready = new Promise((resolve4) => {
+    resolveReady = resolve4;
+  });
+  const exited = new Promise((resolve4) => {
+    child.on("close", (code) => {
+      resolveReady(null);
+      resolve4(code);
+    });
+    child.on("error", (err) => {
+      stderr += err.message;
+      resolveReady(null);
+      resolve4(null);
+    });
+  });
+  child.stdout.setEncoding("utf8").on("data", (chunk) => {
+    stdout += chunk;
+    const nl = stdout.indexOf("\n");
+    if (nl >= 0) resolveReady(stdout.slice(0, nl));
+  });
+  child.stderr.setEncoding("utf8").on("data", (chunk) => {
+    stderr += chunk;
+  });
+  child.stdin.on("error", () => void 0);
+  const halt = async () => {
+    child.stdin.write("stop\n");
+    child.stdin.end();
+    return { code: await exited, stdout, stderr };
+  };
+  const env = parseEnv(await ready);
+  if (env === null) {
+    const out = await halt();
+    throw new WorldError(`attest-engine world ${file} did not start: ${out.stderr.trim() || `exit ${String(out.code)}`}`);
+  }
+  const urls = Object.values(env);
+  if (urls.length !== 1) {
+    await halt();
+    throw new WorldError(`attest-engine world ${file}: want one env variable, got ${JSON.stringify(env)}`);
+  }
+  const baseUrl = urls[0];
+  const saved = new Map(Object.keys(env).map((k) => [k, process.env[k]]));
+  Object.assign(process.env, env);
+  let stopped = false;
+  let stopping = null;
+  const stop = () => {
+    stopped = true;
+    stopping ??= (async () => {
+      for (const [k, v] of saved) {
+        if (v === void 0) delete process.env[k];
+        else process.env[k] = v;
+      }
+      const out = await halt();
+      active2 = null;
+      const final = parseFinal(out.stdout);
+      if (out.code !== 0 || final === null) {
+        throw new WorldError(`attest-engine world ${file} failed (exit ${String(out.code)}): ${out.stderr.trim()}`);
+      }
+      return final;
+    })();
+    return stopping;
+  };
+  const state = async () => {
+    if (stopped) throw new WorldError(`world ${file} is stopped; use the snapshot stop() returned`);
+    const url = baseUrl + STATE_PATH;
+    let res;
+    try {
+      res = await fetch(url, { signal: AbortSignal.timeout(STATE_TIMEOUT_MS) });
+    } catch (err) {
+      throw new WorldError(`GET ${url}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (res.status !== 200) throw new WorldError(`GET ${url}: HTTP ${String(res.status)}`);
+    const body = await res.json().catch(() => {
+      throw new WorldError(`GET ${url}: the body is not JSON`);
+    });
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+      throw new WorldError(`GET ${url}: the body is not a snapshot object`);
+    }
+    return body;
+  };
+  return { path: file, env, baseUrl, state, stop };
+}
+function parseFinal(out) {
+  const lines = out.trim().split("\n");
+  try {
+    const world = JSON.parse(lines[lines.length - 1] ?? "").world;
+    if (typeof world !== "object" || world === null || Array.isArray(world)) return null;
+    return world;
+  } catch {
+    return null;
+  }
+}
+
 // src/context.ts
 import { AsyncLocalStorage } from "async_hooks";
 var activeBuilder = new AsyncLocalStorage();
@@ -2453,12 +3414,12 @@ var ContinuousEvalRunner = class {
   maxSize;
   running = false;
   loopTimer = null;
-  constructor(client, assertions, options) {
+  constructor(client, assertions, options2) {
     this.client = client;
     this.assertions = assertions;
-    this.sampler = new Sampler(options?.sampleRate ?? 1);
-    this.dispatcher = new AlertDispatcher(options?.alertWebhook, options?.alertSlackUrl);
-    this.maxSize = options?.maxSize ?? resolveQueueSize();
+    this.sampler = new Sampler(options2?.sampleRate ?? 1);
+    this.dispatcher = new AlertDispatcher(options2?.alertWebhook, options2?.alertSlackUrl);
+    this.maxSize = options2?.maxSize ?? resolveQueueSize();
   }
   get alertEmitter() {
     return this.dispatcher;
@@ -2569,13 +3530,13 @@ function loadLabelsCSV(text) {
   if (rows.length === 0) {
     throw new Error("empty CSV");
   }
-  let start = 0;
+  let start3 = 0;
   if (rows[0].length >= 2) {
     const firstHuman = parseFloatStrict(rows[0][1]);
-    if (firstHuman === null) start = 1;
+    if (firstHuman === null) start3 = 1;
   }
   const out = [];
-  for (let idx = start; idx < rows.length; idx++) {
+  for (let idx = start3; idx < rows.length; idx++) {
     const row = rows[idx];
     const lineNum = idx + 1;
     if (row.length === 0) continue;
@@ -2784,10 +3745,10 @@ var OpenAIAdapter = class {
   constructor(agentId2) {
     this.agentId = agentId2;
   }
-  traceFromResponse(response, options) {
+  traceFromResponse(response, options2) {
     const builder = new TraceBuilder(this.agentId);
-    if (options?.inputMessages) {
-      builder.setInput({ messages: options.inputMessages });
+    if (options2?.inputMessages) {
+      builder.setInput({ messages: options2.inputMessages });
     }
     const message = response.choices[0].message;
     const completionText = message.content ?? "";
@@ -2807,12 +3768,12 @@ var OpenAIAdapter = class {
     }
     builder.setOutput({
       message: completionText,
-      structured: options?.structuredOutput ?? {}
+      structured: options2?.structuredOutput ?? {}
     });
     builder.setMetadata({
       total_tokens: response.usage?.total_tokens,
-      cost_usd: options?.costUsd,
-      latency_ms: options?.latencyMs,
+      cost_usd: options2?.costUsd,
+      latency_ms: options2?.latencyMs,
       model: response.model
     });
     return builder.build();
@@ -2825,10 +3786,10 @@ var AnthropicAdapter = class {
   constructor(agentId2) {
     this.agentId = agentId2;
   }
-  traceFromResponse(response, options) {
+  traceFromResponse(response, options2) {
     const builder = new TraceBuilder(this.agentId);
-    if (options?.inputMessages) {
-      builder.setInput({ messages: options.inputMessages });
+    if (options2?.inputMessages) {
+      builder.setInput({ messages: options2.inputMessages });
     }
     const completionParts = [];
     for (const block of response.content) {
@@ -2851,8 +3812,8 @@ var AnthropicAdapter = class {
     }
     builder.setMetadata({
       total_tokens: totalTokens,
-      cost_usd: options?.costUsd,
-      latency_ms: options?.latencyMs,
+      cost_usd: options2?.costUsd,
+      latency_ms: options2?.latencyMs,
       model: response.model
     });
     return builder.build();
@@ -2865,10 +3826,10 @@ var GeminiAdapter = class {
   constructor(agentId2) {
     this.agentId = agentId2;
   }
-  traceFromResponse(response, options) {
+  traceFromResponse(response, options2) {
     const builder = new TraceBuilder(this.agentId);
-    if (options?.inputText) {
-      builder.setInput({ text: options.inputText });
+    if (options2?.inputText) {
+      builder.setInput({ text: options2.inputText });
     }
     let completionText = "";
     if (response.text != null) {
@@ -2888,9 +3849,9 @@ var GeminiAdapter = class {
     builder.addLlmCall("completion", { result: { completion: completionText } });
     builder.setOutput({ message: completionText });
     builder.setMetadata({
-      cost_usd: options?.costUsd,
-      latency_ms: options?.latencyMs,
-      model: options?.model
+      cost_usd: options2?.costUsd,
+      latency_ms: options2?.latencyMs,
+      model: options2?.model
     });
     return builder.build();
   }
@@ -2902,10 +3863,10 @@ var OllamaAdapter = class {
   constructor(agentId2) {
     this.agentId = agentId2;
   }
-  traceFromResponse(response, options) {
+  traceFromResponse(response, options2) {
     const builder = new TraceBuilder(this.agentId);
-    if (options?.inputMessages) {
-      builder.setInput({ messages: options.inputMessages });
+    if (options2?.inputMessages) {
+      builder.setInput({ messages: options2.inputMessages });
     }
     const completionText = response.message?.content ?? "";
     builder.addLlmCall("completion", {
@@ -2919,7 +3880,7 @@ var OllamaAdapter = class {
     }
     builder.setMetadata({
       total_tokens: totalTokens,
-      latency_ms: options?.latencyMs,
+      latency_ms: options2?.latencyMs,
       model: response.model
     });
     return builder.build();
@@ -2927,119 +3888,148 @@ var OllamaAdapter = class {
 };
 
 // src/adapters/otel.ts
+import { spawn as spawn5 } from "child_process";
+var CONVERT_TIMEOUT_MS = 6e4;
+var MAX_TRACE_OUTPUT_BYTES = 64 * 1024 * 1024;
+var STATUS_CODE_ERROR = 2;
 var OTelAdapter = class _OTelAdapter {
-  agentId;
-  constructor(agentId2) {
-    this.agentId = agentId2;
+  /**
+   * Build a trace from finished OpenTelemetry spans of one trace.
+   *
+   * @param agentId Trace `agent_id`; defaults to the first turn's `gen_ai.agent.name`.
+   * @throws OTLPConversionError when the engine rejects the spans.
+   */
+  static async fromSpans(spans, agentId2) {
+    return _OTelAdapter.fromOtlp(spansToOtlp(spans), agentId2);
   }
-  static fromSpans(spans, agentId2) {
-    const adapter = new _OTelAdapter(agentId2);
-    return adapter.buildTrace(spans);
+  /**
+   * Convert an OTLP/JSON export (`resourceSpans` → `scopeSpans` → `spans`).
+   *
+   * @param agentId Trace `agent_id`; defaults to the first turn's `gen_ai.agent.name`.
+   * @throws OTLPConversionError when the engine rejects the export (malformed JSON, invalid
+   *   ids or timestamps, more than one trace, non-numeric token counts, ...).
+   * @throws RangeError when a parsed export holds a non-finite number.
+   * @throws OTLPConversionError when the engine times out, overflows the output buffer or
+   *   prints no trace.
+   * @throws Error when the engine cannot start.
+   */
+  static async fromOtlp(otlp, agentId2) {
+    const payload = typeof otlp === "string" || otlp instanceof Uint8Array ? otlp : JSON.stringify(otlp, (_key, v) => {
+      if (typeof v === "number" && !Number.isFinite(v)) {
+        throw new RangeError(`OTLP export holds a non-finite number: ${String(v)}`);
+      }
+      return v;
+    });
+    const args = ["trace", "convert"];
+    if (agentId2 !== void 0) args.push("--agent-id", agentId2);
+    args.push("-");
+    const stdout = await runConvert(await resolveEngine(), args, payload);
+    try {
+      return JSON.parse(stdout);
+    } catch (err) {
+      throw new OTLPConversionError(
+        `attest-engine trace convert printed output that is not JSON: ${String(err)}`
+      );
+    }
   }
-  buildTrace(spans) {
-    const sorted = [...spans].sort((a, b) => {
-      const aTime = a.startTime[0] * 1e9 + a.startTime[1];
-      const bTime = b.startTime[0] * 1e9 + b.startTime[1];
-      return aTime - bTime;
+};
+function runConvert(engine, args, payload) {
+  return new Promise((resolve4, reject) => {
+    const child = spawn5(engine, args, { stdio: ["pipe", "pipe", "pipe"] });
+    let timer;
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      reject(e);
     });
-    const builder = new TraceBuilder(this.agentId);
-    const rootSpan = this.findRootSpan(sorted);
-    if (rootSpan) {
-      const traceId2 = rootSpan.spanContext().traceId;
-      if (traceId2) {
-        builder.setTraceId(`otel_${traceId2.slice(0, 16)}`);
+    const { stdin, stdout, stderr } = child;
+    if (stdin === null || stdout === null || stderr === null) return;
+    const out = [];
+    const err = [];
+    let outBytes = 0;
+    let failure = null;
+    const fail = (e) => {
+      failure ??= e;
+      child.kill("SIGKILL");
+    };
+    timer = setTimeout(() => {
+      fail(
+        new OTLPConversionError(
+          `attest-engine trace convert timed out after ${CONVERT_TIMEOUT_MS / 1e3}s`
+        )
+      );
+    }, CONVERT_TIMEOUT_MS);
+    stdout.on("data", (chunk) => {
+      outBytes += chunk.length;
+      if (outBytes > MAX_TRACE_OUTPUT_BYTES) {
+        fail(
+          new OTLPConversionError(
+            `attest-engine trace convert printed more than ${MAX_TRACE_OUTPUT_BYTES} bytes`
+          )
+        );
+        return;
       }
-    }
-    let outputMessage = "";
-    let totalTokens;
-    let latencyMs;
-    let model;
-    for (const span of sorted) {
-      const attrs = span.attributes ?? {};
-      const stepType = this.classifySpan(attrs, span.name);
-      if (stepType === "llm_call") {
-        const [stepArgs, stepResult] = this.extractLlmStep(attrs);
-        builder.addLlmCall(span.name, {
-          args: stepArgs,
-          result: stepResult,
-          metadata: this.spanMetadata(span)
-        });
-        const completion = attrs["gen_ai.completion"];
-        if (completion) outputMessage = String(completion);
-        const inputTokens = Number(attrs["gen_ai.usage.input_tokens"] ?? 0);
-        const outputTokens = Number(attrs["gen_ai.usage.output_tokens"] ?? 0);
-        const spanTokens = inputTokens + outputTokens;
-        if (spanTokens > 0) totalTokens = (totalTokens ?? 0) + spanTokens;
-        if (model === void 0) {
-          const responseModel = attrs["gen_ai.response.model"];
-          const requestModel = attrs["gen_ai.request.model"];
-          if (responseModel) model = String(responseModel);
-          else if (requestModel) model = String(requestModel);
-        }
-      } else if (stepType === "tool_call") {
-        const [stepArgs, stepResult] = this.extractToolStep(attrs);
-        const toolName = String(attrs["gen_ai.tool.name"] ?? span.name);
-        builder.addToolCall(toolName, {
-          args: stepArgs,
-          result: stepResult,
-          metadata: this.spanMetadata(span)
-        });
+      out.push(chunk);
+    });
+    stderr.on("data", (chunk) => err.push(chunk));
+    stdin.on("error", () => void 0);
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      if (failure !== null) {
+        reject(failure);
+        return;
       }
-    }
-    if (rootSpan) {
-      const startNs = rootSpan.startTime[0] * 1e9 + rootSpan.startTime[1];
-      const endNs = rootSpan.endTime[0] * 1e9 + rootSpan.endTime[1];
-      latencyMs = Math.floor((endNs - startNs) / 1e6);
-    }
-    builder.setOutput({ message: outputMessage });
-    builder.setMetadata({ total_tokens: totalTokens, latency_ms: latencyMs, model });
-    return builder.build();
+      if (code !== 0) {
+        const message = Buffer.concat(err).toString("utf8").trim();
+        reject(
+          new OTLPConversionError(
+            message || `attest-engine trace convert exited ${String(code ?? signal)}`
+          )
+        );
+        return;
+      }
+      resolve4(Buffer.concat(out).toString("utf8"));
+    });
+    stdin.end(payload);
+  });
+}
+function hrTimeToNanos(time, spanName) {
+  if (!Number.isSafeInteger(time[0]) || !Number.isSafeInteger(time[1])) {
+    throw new RangeError(`span ${JSON.stringify(spanName)} has a non-integer HrTime`);
   }
-  findRootSpan(spans) {
-    for (const span of spans) {
-      if (!span.parentSpanId) return span;
+  return (BigInt(time[0]) * 1000000000n + BigInt(time[1])).toString();
+}
+function anyValue(value) {
+  if (value === null || value === void 0) return {};
+  if (typeof value === "boolean") return { boolValue: value };
+  if (typeof value === "string") return { stringValue: value };
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new RangeError(`OTel attribute value must be finite, got ${String(value)}`);
     }
-    return spans[0];
+    return Number.isSafeInteger(value) ? { intValue: String(value) } : { doubleValue: value };
   }
-  classifySpan(attrs, name) {
-    const op = String(attrs["gen_ai.operation.name"] ?? "");
-    if (op === "chat" || op === "completion" || op === "generate_content" || "gen_ai.completion" in attrs) {
-      return "llm_call";
-    }
-    if (op === "tool" || "gen_ai.tool.name" in attrs) {
-      return "tool_call";
+  return { arrayValue: { values: value.map((v) => anyValue(v)) } };
+}
+function spansToOtlp(spans) {
+  const encoded = spans.map((span) => {
+    const ctx = span.spanContext();
+    const out = {
+      traceId: ctx.traceId,
+      spanId: ctx.spanId,
+      name: span.name,
+      startTimeUnixNano: hrTimeToNanos(span.startTime, span.name),
+      endTimeUnixNano: hrTimeToNanos(span.endTime, span.name),
+      attributes: Object.entries(span.attributes ?? {}).filter(([, v]) => v !== void 0).map(([key, v]) => ({ key, value: anyValue(v) }))
+    };
+    const parent = span.parentSpanContext?.spanId ?? span.parentSpanId;
+    if (parent) out["parentSpanId"] = parent;
+    if (span.status?.code === STATUS_CODE_ERROR) {
+      out["status"] = { code: STATUS_CODE_ERROR, message: span.status.message ?? "" };
     }
-    const lower = name.toLowerCase();
-    if (lower.includes("completion") || lower.includes("chat")) return "llm_call";
-    if (lower.includes("tool")) return "tool_call";
-    return void 0;
-  }
-  extractLlmStep(attrs) {
-    const args = {};
-    const result = {};
-    if ("gen_ai.request.model" in attrs) args.model = String(attrs["gen_ai.request.model"]);
-    if ("gen_ai.system" in attrs) args.system = String(attrs["gen_ai.system"]);
-    if ("gen_ai.prompt" in attrs) args.prompt = String(attrs["gen_ai.prompt"]);
-    if ("gen_ai.completion" in attrs) result.completion = String(attrs["gen_ai.completion"]);
-    if ("gen_ai.usage.input_tokens" in attrs) result.input_tokens = Number(attrs["gen_ai.usage.input_tokens"]);
-    if ("gen_ai.usage.output_tokens" in attrs) result.output_tokens = Number(attrs["gen_ai.usage.output_tokens"]);
-    if ("gen_ai.response.model" in attrs) result.model = String(attrs["gen_ai.response.model"]);
-    return [args, result];
-  }
-  extractToolStep(attrs) {
-    const args = {};
-    const result = {};
-    if ("gen_ai.tool.call.id" in attrs) args.call_id = String(attrs["gen_ai.tool.call.id"]);
-    if ("gen_ai.tool.parameters" in attrs) args.parameters = attrs["gen_ai.tool.parameters"];
-    if ("gen_ai.tool.output" in attrs) result.output = attrs["gen_ai.tool.output"];
-    return [args, result];
-  }
-  spanMetadata(span) {
-    const startNs = span.startTime[0] * 1e9 + span.startTime[1];
-    const endNs = span.endTime[0] * 1e9 + span.endTime[1];
-    return { duration_ms: Math.floor((endNs - startNs) / 1e6) };
-  }
-};
+    return out;
+  });
+  return { resourceSpans: [{ scopeSpans: [{ spans: encoded }] }] };
+}
 
 // src/adapters/langchain.ts
 var LangChainAdapter = class {
@@ -3107,13 +4097,13 @@ var LangChainAdapter = class {
    * @param options.model - Model name override.
    * @returns A finalized Trace object.
    */
-  buildTrace(options) {
+  buildTrace(options2) {
     const builder = new TraceBuilder(this.agentId);
     const latencyMs = this.startTime > 0 ? Date.now() - this.startTime : void 0;
     let totalTokens;
     for (const llm of this.llmCalls) {
       const args = {};
-      if (llm.model ?? options?.model) args.model = llm.model ?? options?.model;
+      if (llm.model ?? options2?.model) args.model = llm.model ?? options2?.model;
       const result = { completion: llm.text };
       if (llm.tokens !== void 0) {
         result.tokens = llm.tokens;
@@ -3130,9 +4120,9 @@ var LangChainAdapter = class {
     builder.setOutput({ message: outputMessage });
     builder.setMetadata({
       total_tokens: totalTokens,
-      cost_usd: options?.costUsd,
+      cost_usd: options2?.costUsd,
       latency_ms: latencyMs,
-      model: options?.model ?? this.llmCalls[0]?.model
+      model: options2?.model ?? this.llmCalls[0]?.model
     });
     return builder.build();
   }
@@ -3146,6 +4136,7 @@ export {
   AttestClient,
   CONFUSED_USER,
   COOPERATIVE_USER,
+  CaptureError,
   ContinuousEvalRunner,
   ENGINE_VERSION,
   ERR_ASSERTION_ERROR,
@@ -3154,6 +4145,7 @@ export {
   ERR_PROVIDER_ERROR,
   ERR_SESSION_ERROR,
   ERR_TIMEOUT,
+  EgressBlockedError,
   EngineManager,
   EngineTimeoutError,
   ExpectChain,
@@ -3162,6 +4154,7 @@ export {
   GeminiAdapter,
   LangChainAdapter,
   ManualAdapter,
+  OTLPConversionError,
   OTelAdapter,
   OUTCOME_FAIL,
   OUTCOME_PASS,
@@ -3172,11 +4165,17 @@ export {
   ProtocolDesyncError,
   ProtocolDiagnosticBuffer,
   ProtocolError,
+  REASON_BUDGET_EXHAUSTED,
+  REASON_JUDGE_ABSTAINED,
   REASON_MISSING_EVIDENCE,
   REASON_PROVIDER_NOT_CONFIGURED,
   REASON_PROVIDER_UNAVAILABLE,
+  REASON_REPLAY_MISS,
   REASON_SHORT_CIRCUITED,
   REASON_SIMULATION,
+  ReplayError,
+  ReplayMissError,
+  ReplayNotEvaluatedError,
   STATUS_HARD_FAIL,
   STATUS_NOT_EVALUATED,
   STATUS_PASS,
@@ -3191,6 +4190,7 @@ export {
   TIER_3,
   TYPE_CONSTRAINT,
   TYPE_CONTENT,
+  TYPE_EFFECT,
   TYPE_EMBEDDING,
   TYPE_LLM_JUDGE,
   TYPE_PLUGIN,
@@ -3200,7 +4200,10 @@ export {
   TraceBuilder,
   TraceTree,
   VERSION,
+  WorldChecks,
+  WorldError,
   activeBuilder,
+  addUsage,
   agent,
   agentId,
   assertionId,
@@ -3209,24 +4212,44 @@ export {
   config,
   decodeResponse,
   delegate,
+  dslCall,
+  egressBlockRequested,
+  emitVitest,
   encodeRequest,
   executePluginAssertion,
   extractId,
   extractResult,
+  firstMiss,
+  formatUsage,
   getSampleRate,
+  installEgressGuard,
+  isProviderHost,
   isSimulationMode,
   layerForType,
+  liveLine,
+  loadFixture,
   loadLabelsCSV,
   loadLabelsJSONL,
+  parseUsage,
   previewLine,
   promptHash,
+  record,
   renderAssertionFailure,
   renderDiagnostics,
   renderSummary,
+  renderVitest,
   requireSimulationCapability,
   resetConfig,
+  resolveMode,
   simulationEnvEnabled,
+  startReplay,
+  startWorld,
+  sumUsage,
+  testPathFor,
   tier,
-  traceId
+  traceId,
+  uninstallEgressGuard,
+  usageSummaryLine,
+  zeroUsage
 };
 //# sourceMappingURL=index.js.map