agenttwin 0.3.5 → 0.3.7

package/dist/worker.js

@@ -9,6 +9,79 @@ import { spawn } from "child_process";
 // src/runtime/http-world.ts
 import { createServer } from "http";
 import { randomBytes } from "crypto";
+import { isDeepStrictEqual } from "util";
+import { AsyncLocalStorage } from "async_hooks";
+
+// src/runtime/request-source.ts
+import { mkdtemp, writeFile, rm, realpath } from "fs/promises";
+import { tmpdir } from "os";
+import { join, resolve } from "path";
+function parseRequestSource(raw, spec) {
+  if (typeof raw !== "string" || raw.length > 1024) return;
+  try {
+    const source = JSON.parse(raw);
+    if (!source || typeof source.file !== "string" || !spec.files.includes(source.file) || !Number.isSafeInteger(source.line) || source.line < 1 || source.line > 1e6 || !Number.isSafeInteger(source.column) || source.column < 1 || source.column > 1e6) return;
+    return { file: source.file, line: source.line, column: source.column, provenance: "application-reported" };
+  } catch {
+    return;
+  }
+}
+
+// src/runtime/stripe-adapter.ts
+function stripeOperation(method, path, params, data, sequence) {
+  const error = (status, code, message, param) => ({ status, body: { error: { type: "invalid_request_error", code, message, ...param ? { param } : {} } } });
+  const match = /^\/v1\/(customers|payment_intents)(?:\/([^/]+))?(?:\/(confirm))?$/.exec(path);
+  if (!match || !["GET", "POST"].includes(method)) return void 0;
+  const [, resource, id, action] = match, collection = `/v1/${resource}`, rows = data[collection];
+  const allowed = method === "GET" ? id ? [] : ["limit", "starting_after"] : resource === "customers" && !id ? ["email", "name", "description"] : resource === "payment_intents" && !id ? ["amount", "currency", "customer", "payment_method", "confirm"] : action === "confirm" ? ["payment_method"] : void 0;
+  if (!allowed || resource === "customers" && action || resource === "payment_intents" && method === "GET" && !id) return void 0;
+  if (Object.keys(params).some((k) => !allowed.includes(k))) return void 0;
+  if (method === "GET" && !id) {
+    const limit = params.limit === void 0 ? 10 : Number(params.limit);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) return { ...error(400, "parameter_invalid_integer", "limit must be 1\u2013100", "limit"), collection };
+    const ordered = [...rows].reverse();
+    const index = params.starting_after === void 0 ? -1 : ordered.findIndex((r) => r.id === params.starting_after);
+    if (params.starting_after !== void 0 && index === -1) return { ...error(400, "resource_missing", "No such starting_after customer", "starting_after"), collection };
+    const page = ordered.slice(index + 1, index + 1 + limit);
+    return { status: 200, body: { object: "list", data: page, has_more: ordered.length > index + 1 + limit, url: collection }, collection, operation: "read" };
+  }
+  const row = id ? rows.find((r) => r.id === id) : void 0;
+  if (id && !row) return { ...error(404, "resource_missing", `No such ${resource}: '${id}'`), collection };
+  if (method === "GET") return { status: 200, body: row, collection, operation: "read" };
+  if (action === "confirm") {
+    if (row.status === "succeeded") return { status: 200, body: row, collection, operation: "replay" };
+    const payment = params.payment_method ?? row.payment_method;
+    if (payment !== "pm_card_visa" && payment !== "pm_card_chargeDeclined") return { ...error(400, "parameter_invalid", "Only pm_card_visa and pm_card_chargeDeclined are supported", "payment_method"), collection };
+    row.payment_method = payment;
+    row.status = payment === "pm_card_visa" ? "succeeded" : "requires_payment_method";
+    row.last_payment_error = payment === "pm_card_chargeDeclined" ? { code: "card_declined", decline_code: "generic_decline", message: "Your card was declined." } : null;
+    return { status: payment === "pm_card_chargeDeclined" ? 402 : 200, body: payment === "pm_card_chargeDeclined" ? { error: { type: "card_error", code: "card_declined", decline_code: "generic_decline", message: "Your card was declined.", payment_intent: structuredClone(row) } } : row, collection, record: structuredClone(row), operation: "write" };
+  }
+  const prefix = resource === "customers" ? "cus" : "pi";
+  let suffix = sequence;
+  while (rows.some((r) => r.id === `${prefix}_at_${suffix}`)) suffix++;
+  const created = { id: `${prefix}_at_${suffix}`, object: resource === "customers" ? "customer" : "payment_intent", created: 17e8, livemode: false };
+  if (resource === "customers") {
+    if (params.email !== void 0 && typeof params.email !== "string") return { ...error(400, "parameter_invalid", "email must be a string", "email"), collection };
+    Object.assign(created, { email: null, name: null, description: null, ...params });
+  } else {
+    const amount = Number(params.amount);
+    if (!Number.isSafeInteger(amount) || amount < 1) return { ...error(400, "parameter_invalid_integer", "amount must be a positive integer", "amount"), collection };
+    if (typeof params.currency !== "string" || !/^[a-z]{3}$/.test(params.currency)) return { ...error(400, "parameter_invalid", "currency must be a lowercase three-letter code", "currency"), collection };
+    if (params.customer && !data["/v1/customers"].some((r) => r.id === params.customer)) return { ...error(400, "resource_missing", "No such customer", "customer"), collection };
+    if (params.payment_method !== void 0 && !["pm_card_visa", "pm_card_chargeDeclined"].includes(String(params.payment_method))) return { ...error(400, "parameter_invalid", "Unsupported test payment method", "payment_method"), collection };
+    if (params.confirm !== void 0 && !["true", "false", true, false].includes(params.confirm)) return { ...error(400, "parameter_invalid", "confirm must be boolean", "confirm"), collection };
+    const confirm = params.confirm === "true" || params.confirm === true;
+    if (confirm && !params.payment_method) return { ...error(400, "parameter_missing", "Missing payment_method", "payment_method"), collection };
+    Object.assign(created, { amount, currency: params.currency, customer: params.customer ?? null, payment_method: params.payment_method ?? null, status: confirm && params.payment_method === "pm_card_visa" ? "succeeded" : !confirm && params.payment_method ? "requires_confirmation" : "requires_payment_method", last_payment_error: confirm && params.payment_method === "pm_card_chargeDeclined" ? { code: "card_declined", message: "Your card was declined." } : null });
+  }
+  if (rows.length >= 1e4) return { ...error(429, "world_capacity", "World record capacity reached"), collection };
+  rows.push(created);
+  const declined = resource === "payment_intents" && (params.confirm === "true" || params.confirm === true) && params.payment_method === "pm_card_chargeDeclined";
+  return { status: declined ? 402 : 200, body: declined ? { error: { type: "card_error", code: "card_declined", decline_code: "generic_decline", message: "Your card was declined.", payment_intent: structuredClone(created) } } : created, collection, record: structuredClone(created), operation: "write" };
+}
+
+// src/runtime/http-world.ts
 var HttpWorld = class {
   constructor(spec) {
     this.spec = spec;
@@ -21,21 +94,32 @@ var HttpWorld = class {
   servers = [];
   timers = /* @__PURE__ */ new Set();
   fired = false;
-  record(service, operation, path, detail) {
+  epoch = 0;
+  replayKeys = /* @__PURE__ */ new Map();
+  sourceContext = new AsyncLocalStorage();
+  record(service, operation, path, detail, record) {
     if (this.events.length >= 5e4) return;
-    this.events.push({ sequence: this.events.length + 1, service, operation, path, detail });
+    const source = this.sourceContext.getStore();
+    this.events.push({ sequence: this.events.length + 1, service, operation, path, detail, ...record ? { record: structuredClone(record) } : {}, ...source ? { source } : {} });
+  }
+  rejectUnsupported(service, method, path, detail) {
+    this.unsupported.push(`${service}: ${method} ${path}: ${detail}`);
+    this.record(service, "unsupported", path, detail);
   }
   async start() {
+    if (this.servers.length) throw new Error("World is already started");
     for (const service of this.spec.services) {
       const token = `at_world_${randomBytes(24).toString("hex")}`;
       const data = /* @__PURE__ */ Object.create(null);
       this.state[service.name] = data;
       for (const c of service.collections) data[c.path] = structuredClone(c.seed);
       const keys = /* @__PURE__ */ new Map();
-      const server = createServer(async (req, res) => {
+      this.replayKeys.set(service.name, keys);
+      const server = createServer((req, res) => this.sourceContext.run(parseRequestSource(req.headers["x-agenttwin-source"], this.spec), async () => {
+        const epoch = this.epoch;
         const send = (code, body) => {
           if (!res.destroyed) {
-            res.writeHead(code, { "content-type": "application/json" });
+            res.writeHead(code, { "content-type": "application/json", ...code === 501 ? { "X-AgentTwin-Unsupported": "true" } : {} });
             res.end(JSON.stringify(body));
           }
         };
@@ -68,7 +152,7 @@ var HttpWorld = class {
             const text = Buffer.concat(chunks).toString("utf8");
             let parsed;
             try {
-              parsed = slack && req.headers["content-type"]?.startsWith("application/x-www-form-urlencoded") ? Object.fromEntries(new URLSearchParams(text)) : JSON.parse(text);
+              parsed = (slack || service.adapter === "stripe") && req.headers["content-type"]?.startsWith("application/x-www-form-urlencoded") ? Object.fromEntries(new URLSearchParams(text)) : JSON.parse(text);
             } catch {
               send(400, { error: "expected_json_object" });
               return;
@@ -79,11 +163,50 @@ var HttpWorld = class {
             }
             payload = parsed;
           }
+          if (epoch !== this.epoch) {
+            send(409, { error: "world_reset" });
+            return;
+          }
+          if (service.adapter === "stripe") {
+            const params = payload ?? Object.fromEntries(url.searchParams);
+            const keyHeader2 = req.headers["idempotency-key"];
+            const key2 = req.method === "POST" && typeof keyHeader2 === "string" ? `${path}:${keyHeader2}` : void 0;
+            const signature2 = JSON.stringify(params);
+            const previous2 = key2 ? keys.get(key2) : void 0;
+            if (previous2) {
+              if (previous2.body !== signature2) {
+                send(400, { error: { type: "idempotency_error", message: "Keys for idempotent requests can only be used with the same parameters" } });
+                return;
+              }
+              this.record(service.name, "replay", path, "same-key response replay", previous2.record);
+              send(200, previous2.record);
+              return;
+            }
+            const result = stripeOperation(req.method ?? "", path, params, data, this.events.length + 1);
+            if (!result) {
+              this.rejectUnsupported(service.name, req.method ?? "", path, "unsupported Stripe operation or parameters");
+              send(501, { error: { type: "invalid_request_error", code: "unsupported_operation", message: "Outside the verified AgentTwin Stripe subset" }, forwardedToProduction: false });
+              return;
+            }
+            if (result.operation) this.record(service.name, result.operation, result.collection, path, "record" in result ? result.record : result.body);
+            if (key2 && result.status === 200) keys.set(key2, { body: signature2, record: structuredClone(result.body) });
+            const fault2 = this.spec.fault;
+            if (!this.fired && result.operation === "write" && fault2?.service === service.name && fault2.path === result.collection) {
+              this.fired = true;
+              this.record(service.name, "fault", result.collection, `write committed; response delayed ${fault2.delayMs}ms`);
+              const timer = setTimeout(() => {
+                this.timers.delete(timer);
+                send(result.status, result.body);
+              }, fault2.delayMs);
+              this.timers.add(timer);
+            } else send(result.status, result.body);
+            return;
+          }
           if (slack) {
             const params = payload ?? Object.fromEntries(url.searchParams);
             const allowed = slackMethod === "chat.postMessage" ? ["channel", "text"] : slackMethod === "conversations.history" ? ["channel"] : [];
             if (Object.keys(params).some((k) => !allowed.includes(k))) {
-              this.unsupported.push(`${service.name}: unsupported parameters for ${slackMethod}`);
+              this.rejectUnsupported(service.name, req.method ?? "", url.pathname, `unsupported parameters for ${slackMethod}`);
               send(501, { ok: false, error: "unsupported_parameters", forwardedToProduction: false });
               return;
             }
@@ -91,13 +214,13 @@ var HttpWorld = class {
             else if (slackMethod === "conversations.history" && ["GET", "POST"].includes(req.method ?? "")) path = "/messages";
             else if (slackMethod === "conversations.list" && ["GET", "POST"].includes(req.method ?? "")) path = "/channels";
             else {
-              this.unsupported.push(`${service.name}: ${req.method} ${url.pathname}`);
-              send(501, { ok: false, error: "unsupported_operation" });
+              this.rejectUnsupported(service.name, req.method ?? "", url.pathname, "unsupported operation");
+              send(501, { ok: false, error: "unsupported_operation", forwardedToProduction: false });
               return;
             }
           }
           if (!Object.hasOwn(data, path) || !["GET", "POST"].includes(req.method ?? "")) {
-            this.unsupported.push(`${service.name}: ${req.method} ${path}`);
+            this.rejectUnsupported(service.name, req.method ?? "", path, "unsupported operation");
             send(501, { error: "unsupported_operation", forwardedToProduction: false });
             return;
           }
@@ -136,7 +259,7 @@ var HttpWorld = class {
               send(409, { error: "idempotency_conflict" });
               return;
             }
-            this.record(service.name, "replay", path, "same-key response replay");
+            this.record(service.name, "replay", path, "same-key response replay", previous.record);
             send(200, previous.record);
             return;
           }
@@ -147,7 +270,7 @@ var HttpWorld = class {
           const reply = slack ? { ok: true, channel: row.channel, ts: row.ts, message: row } : row;
           data[path].push(row);
           if (key) keys.set(key, { body: signature, record: row });
-          this.record(service.name, "write", path, String(row.id));
+          this.record(service.name, "write", path, String(row.id), row);
           const fault = this.spec.fault;
           if (!this.fired && fault?.service === service.name && fault.path === path) {
             this.fired = true;
@@ -161,11 +284,11 @@ var HttpWorld = class {
         } catch {
           send(500, { error: "world_request_error" });
         }
-      });
+      }));
       server.requestTimeout = 1e4;
-      await new Promise((resolve, reject) => {
+      await new Promise((resolve2, reject) => {
         server.once("error", reject);
-        server.listen(0, "127.0.0.1", resolve);
+        server.listen(0, "127.0.0.1", resolve2);
       });
       this.servers.push(server);
       this.credentials[service.name] = { endpoint: `http://127.0.0.1:${server.address().port}`, token };
@@ -174,20 +297,42 @@ var HttpWorld = class {
   }
   assertions() {
     return this.spec.assertions.map((a) => {
-      const rows = this.state[a.service][a.path].filter((row) => !a.where || Object.entries(a.where).every(([k, v]) => JSON.stringify(row[k]) === JSON.stringify(v)));
+      const rows = this.state[a.service][a.path].filter((row) => !a.where || Object.entries(a.where).every(([k, v]) => isDeepStrictEqual(row[k], v)));
       return { ...a, actual: rows.length, passed: rows.length === a.count };
     });
   }
   get faultTriggered() {
     return this.fired;
   }
+  snapshot() {
+    return structuredClone(this.state);
+  }
+  quiesce() {
+    this.epoch++;
+    for (const server of this.servers) server.closeAllConnections();
+    for (const timer of this.timers) clearTimeout(timer);
+    this.timers.clear();
+  }
+  reset() {
+    this.quiesce();
+    for (const service of this.spec.services) {
+      for (const collection of service.collections) this.state[service.name][collection.path] = structuredClone(collection.seed);
+      this.replayKeys.get(service.name)?.clear();
+    }
+    this.events.length = 0;
+    this.unsupported.length = 0;
+    this.fired = false;
+    return this.snapshot();
+  }
   async close() {
+    this.epoch++;
     for (const timer of this.timers) clearTimeout(timer);
     this.timers.clear();
-    await Promise.all(this.servers.map((server) => new Promise((resolve) => {
-      server.close(() => resolve());
+    await Promise.all(this.servers.map((server) => new Promise((resolve2) => {
+      server.close(() => resolve2());
       server.closeAllConnections();
     })));
+    this.servers.length = 0;
   }
 };
 
@@ -212,7 +357,7 @@ function parseWorld(value) {
     if (!object(service) || typeof service.name !== "string" || !namePattern.test(service.name) || services.has(service.name)) invalid("service names must be unique lowercase identifiers");
     const item = service;
     if (!Array.isArray(item.collections) || !item.collections.length || item.collections.length > 20) invalid("each service needs 1\u201320 collections");
-    if (item.adapter !== void 0 && !["json-collection", "slack"].includes(String(item.adapter))) invalid("unsupported service adapter");
+    if (item.adapter !== void 0 && !["json-collection", "slack", "stripe"].includes(String(item.adapter))) invalid("unsupported service adapter");
     const paths = /* @__PURE__ */ new Set();
     for (const entry of item.collections) {
       if (!object(entry) || typeof entry.path !== "string" || !/^\/[a-zA-Z0-9_/-]+$/.test(entry.path) || entry.path.includes("//") || paths.has(entry.path)) invalid("collection paths must be unique absolute HTTP paths");
@@ -221,6 +366,7 @@ function parseWorld(value) {
       paths.add(collection.path);
     }
     if (item.adapter === "slack" && (!paths.has("/messages") || !paths.has("/channels") || paths.size !== 2)) invalid("slack adapter requires /messages and /channels collections");
+    if (item.adapter === "stripe" && (!paths.has("/v1/customers") || !paths.has("/v1/payment_intents") || paths.size !== 2)) invalid("stripe adapter requires /v1/customers and /v1/payment_intents collections");
     services.set(item.name, paths);
   }
   const known = (entry) => typeof entry.service === "string" && typeof entry.path === "string" && services.get(entry.service)?.has(entry.path);
@@ -228,6 +374,19 @@ function parseWorld(value) {
   for (const assertion of v.assertions) {
     if (!object(assertion) || !known(assertion) || !Number.isSafeInteger(assertion.count) || Number(assertion.count) < 0 || assertion.where !== void 0 && !object(assertion.where)) invalid("assertions need an existing service/path, nonnegative count, and optional where object");
   }
+  const policyIds = /* @__PURE__ */ new Set();
+  for (const field of ["forbiddenEffects", "preservedState"]) {
+    if (v[field] === void 0) continue;
+    if (!Array.isArray(v[field]) || v[field].length > 100) invalid(`${field} must contain at most 100 checks`);
+    for (const entry of v[field]) {
+      if (!object(entry) || typeof entry.id !== "string" || !namePattern.test(entry.id) || policyIds.has(entry.id) || !known(entry) || entry.where !== void 0 && !object(entry.where)) invalid(`${field} requires unique ids, known collections and an optional where object`);
+      const item = entry;
+      if (field === "forbiddenEffects" && !["write", "read", "replay"].includes(String(item.operation))) invalid("forbiddenEffects operation must be write, read or replay");
+      if (Object.keys(item).some((k) => !["id", "service", "path", "where", ...field === "forbiddenEffects" ? ["operation"] : []].includes(k))) invalid(`unknown ${field} field`);
+      policyIds.add(item.id);
+    }
+  }
+  if (v.scenario !== void 0 && (!object(v.scenario) || typeof v.scenario.id !== "string" || !namePattern.test(v.scenario.id) || !Number.isSafeInteger(v.scenario.version) || Number(v.scenario.version) < 1 || typeof v.scenario.digest !== "string" || !/^[a-f0-9]{64}$/.test(v.scenario.digest) || Object.keys(v.scenario).some((k) => !["id", "version", "digest"].includes(k)))) invalid("scenario requires id, positive version and SHA-256 digest");
   if (v.postgres !== void 0) {
     if (!object(v.postgres) || v.postgres.seedFile !== void 0 && !v.files.includes(String(v.postgres.seedFile)) || !Array.isArray(v.postgres.assertions) || !v.postgres.assertions.length || v.postgres.assertions.length > 100) invalid("postgres requires assertions and seedFile must be listed in files");
     for (const a of v.postgres.assertions) {
@@ -241,15 +400,145 @@ function parseWorld(value) {
     }
   }
   if (v.fault !== void 0 && (!object(v.fault) || !known(v.fault) || v.fault.type !== "timeout-after-write" || !Number.isInteger(v.fault.delayMs) || Number(v.fault.delayMs) < 1 || Number(v.fault.delayMs) > 1e4)) invalid("fault requires an existing service/path and delayMs 1\u201310000");
-  const keys = ["schema", "name", "workflowId", "files", "command", "timeoutSeconds", "services", "assertions", "postgres", "redis", "fault"];
+  if (v.browser !== void 0) {
+    if (!object(v.browser) || typeof v.browser.baseUrl !== "string") invalid("browser requires baseUrl");
+    const browser = v.browser;
+    let u;
+    try {
+      u = new URL(String(v.browser.baseUrl));
+    } catch {
+      invalid("browser baseUrl must be a loopback HTTP URL");
+    }
+    if (u.protocol !== "http:" || u.hostname !== "127.0.0.1" || !u.port || u.username || u.password || u.pathname !== "/" || u.search || u.hash) invalid("browser baseUrl must be http://127.0.0.1:<port>");
+    if (!Array.isArray(browser.steps) || !browser.steps.length || browser.steps.length > 100 || Object.keys(browser).some((k) => !["baseUrl", "steps"].includes(k))) invalid("browser needs 1\u2013100 steps");
+    for (const raw of browser.steps) {
+      const step = raw;
+      if (!object(step) || !["goto", "click", "fill", "expectText"].includes(String(step.action))) invalid("unsupported browser action");
+      if (step.action === "goto") {
+        if (typeof step.path !== "string" || !step.path.startsWith("/") || step.path.startsWith("//") || step.path.includes("\\") || Object.keys(step).some((k) => !["action", "path"].includes(k))) invalid("goto requires a relative application path");
+      } else {
+        if (typeof step.selector !== "string" || !step.selector || step.action === "fill" && typeof step.value !== "string" || step.action === "expectText" && typeof step.text !== "string" || Object.keys(step).some((k) => !["action", "selector", ...step.action === "fill" ? ["value"] : step.action === "expectText" ? ["text"] : []].includes(k))) invalid("invalid browser selector/action parameters");
+      }
+    }
+  }
+  if (v.background !== void 0 && (!object(v.background) || !known(v.background) || !Number.isSafeInteger(v.background.count) || Number(v.background.count) < 0 || !Number.isInteger(v.background.timeoutMs) || Number(v.background.timeoutMs) < 1 || Number(v.background.timeoutMs) > Number(v.timeoutSeconds) * 1e3 || v.background.where !== void 0 && !object(v.background.where) || Object.keys(v.background).some((k) => !["service", "path", "count", "where", "timeoutMs"].includes(k)))) invalid("background requires a known collection, expected count, optional where, and bounded timeoutMs");
+  const keys = ["schema", "name", "workflowId", "files", "command", "timeoutSeconds", "browser", "background", "services", "assertions", "forbiddenEffects", "preservedState", "scenario", "postgres", "redis", "fault"];
   if (Object.keys(v).some((k) => !keys.includes(k))) invalid("unknown world field");
   return v;
 }
 
+// src/runtime/evaluation.ts
+import { isDeepStrictEqual as isDeepStrictEqual2 } from "util";
+var matches = (row, where) => !where || Object.entries(where).every(([k, v]) => isDeepStrictEqual2(row[k], v));
+function evaluateState(spec, initial, final, events) {
+  const checks = spec.assertions.map((a, index) => {
+    const before = initial[a.service]?.[a.path];
+    const after = final[a.service]?.[a.path];
+    const actual = after?.filter((row) => matches(row, a.where)).length;
+    return {
+      id: `assertion_${index + 1}`,
+      kind: "required-outcome",
+      service: a.service,
+      path: a.path,
+      passed: actual === a.count,
+      expected: a.count,
+      actual: actual ?? null,
+      evidence: {
+        initial: `/initialState/${escape(a.service)}/${escape(a.path)}`,
+        final: `/finalState/${escape(a.service)}/${escape(a.path)}`,
+        beforeCount: before?.filter((row) => matches(row, a.where)).length ?? null,
+        eventSequences: events.filter((e) => e.service === a.service && e.path === a.path).map((e) => e.sequence)
+      }
+    };
+  });
+  const forbidden = (spec.forbiddenEffects ?? []).map((policy) => {
+    const hits = events.filter((e) => e.service === policy.service && e.path === policy.path && e.operation === policy.operation && (!policy.where || e.record !== void 0 && matches(e.record, policy.where)));
+    const unknown = events.some((e) => e.service === policy.service && e.path === policy.path && e.operation === policy.operation && policy.where && !e.record);
+    return {
+      id: policy.id,
+      kind: "forbidden-effect",
+      service: policy.service,
+      path: policy.path,
+      passed: hits.length === 0 && !unknown,
+      expected: 0,
+      actual: hits.length,
+      evidence: { eventSequences: hits.map((e) => e.sequence), evidenceGap: unknown }
+    };
+  });
+  const preserved = (spec.preservedState ?? []).map((policy) => {
+    const before = initial[policy.service]?.[policy.path];
+    const after = final[policy.service]?.[policy.path];
+    const passed = !!before && !!after && isDeepStrictEqual2(before.filter((row) => matches(row, policy.where)), after.filter((row) => matches(row, policy.where)));
+    return {
+      id: policy.id,
+      kind: "preserved-state",
+      service: policy.service,
+      path: policy.path,
+      passed,
+      expected: "unchanged",
+      actual: passed ? "unchanged" : "changed or missing",
+      evidence: { initial: `/initialState/${escape(policy.service)}/${escape(policy.path)}`, final: `/finalState/${escape(policy.service)}/${escape(policy.path)}` }
+    };
+  });
+  const taskPassed = checks.every((c) => c.passed);
+  const safe = [...forbidden, ...preserved].every((c) => c.passed);
+  return { schema: "agenttwin/evaluation-v1", outcome: !safe ? "unsafe" : taskPassed ? "passed" : "failed", taskPassed, safe, checks: [...checks, ...forbidden, ...preserved] };
+}
+var escape = (value) => value.replace(/~/g, "~0").replace(/\//g, "~1");
+
+// src/runtime/contracts.ts
+var CONTRACTS = {
+  "json-collection": {
+    version: "1.0.0",
+    authentication: "Bearer run-scoped test token",
+    operations: [
+      { method: "GET", endpoint: "<collection path>", effect: "read", response: "{data: records}", errors: ["401 invalid_test_credential", "429 world_capacity"] },
+      { method: "POST", endpoint: "<collection path>", effect: "append", response: "201 record; 200 idempotency replay", errors: ["400 expected_json_object", "409 idempotency_conflict", "413 body_too_large", "429 world_capacity"] }
+    ],
+    limitations: ["Custom API contract, not a vendor replica", "No update/delete, pagination, OAuth, webhooks or schema validation", "Idempotency compares the exact parsed JSON serialization"]
+  },
+  stripe: {
+    version: "1.0.0",
+    authentication: "Bearer run-scoped test token; official Stripe SDK configured with test endpoint",
+    operations: [
+      { method: "POST", endpoint: "/v1/customers", effect: "append customer", parameters: ["email", "name", "description"], errors: ["400 invalid parameters"] },
+      { method: "GET", endpoint: "/v1/customers[/<id>]", effect: "retrieve or list customers", parameters: ["limit", "starting_after"], errors: ["404 resource_missing", "400 invalid pagination"] },
+      { method: "POST", endpoint: "/v1/payment_intents", effect: "create test payment intent", parameters: ["amount", "currency", "customer", "payment_method", "confirm"], errors: ["400 invalid parameters", "400 resource_missing", "402 card_declined"] },
+      { method: "GET", endpoint: "/v1/payment_intents/<id>", effect: "retrieve intent", parameters: [], errors: ["404 resource_missing"] },
+      { method: "POST", endpoint: "/v1/payment_intents/<id>/confirm", effect: "test success or decline", parameters: ["payment_method"], errors: ["404 resource_missing", "400 unsupported test method", "402 card_declined"] }
+    ],
+    limitations: ["Bounded subset, not full Stripe parity; minimal object fields only; no real money", "Only pm_card_visa and pm_card_chargeDeclined test methods", "No webhooks, refunds, subscriptions, payment-method APIs, metadata, updates or deletes", "Customers list supports limit/starting_after; payment intent listing unsupported", "POST idempotency supported; reset clears records and keys; unsupported operations/parameters return 501 and make coverage incomplete"]
+  },
+  slack: {
+    version: "1.0.0",
+    authentication: "Bearer run-scoped test token; no Slack OAuth",
+    operations: [
+      { method: "POST", endpoint: "/api/chat.postMessage", effect: "append /messages", parameters: ["channel", "text"], errors: ["channel_not_found", "no_text"] },
+      { method: "GET|POST", endpoint: "/api/conversations.history", effect: "read /messages", parameters: ["channel"], errors: ["channel_not_found"] },
+      { method: "GET|POST", endpoint: "/api/conversations.list", effect: "read /channels", parameters: [], errors: [] }
+    ],
+    limitations: ["JSON and form bodies only", "No OAuth, scopes, pagination, threads, edits, deletes, attachments or webhooks", "Errors channel_not_found/no_text use HTTP 200 with ok:false", "Unmodeled parameters and operations return HTTP 501 and make coverage incomplete"]
+  }
+};
+function operationMatrix(spec) {
+  return {
+    schema: "agenttwin/contracts-v1",
+    unsupported: { status: 501, marker: "X-AgentTwin-Unsupported", coverage: "incomplete", forwardedToProduction: false },
+    adapters: CONTRACTS,
+    services: spec?.services.map((s) => ({
+      name: s.name,
+      adapter: s.adapter ?? "json-collection",
+      version: CONTRACTS[s.adapter ?? "json-collection"].version,
+      operations: s.adapter === "slack" ? CONTRACTS.slack.operations : s.adapter === "stripe" ? CONTRACTS.stripe.operations : s.collections.flatMap((c) => CONTRACTS["json-collection"].operations.map((op) => ({ ...op, endpoint: c.path })))
+    })) ?? []
+  };
+}
+
 // src/runtime/worker.ts
 var secrets = [];
 async function main() {
   const spec = parseWorld(JSON.parse(await readFile("/input/world.json", "utf8")));
+  if (spec.browser || spec.background) throw new Error("Browser and background execution require the local runtime; this hosted worker does not provision Chromium.");
   const world = new HttpWorld(spec);
   const started = Date.now();
   try {
@@ -282,9 +571,9 @@ async function main() {
       timedOut = true;
       kill();
     }, spec.timeoutSeconds * 1e3);
-    const exitCode = await new Promise((resolve, reject) => {
+    const exitCode = await new Promise((resolve2, reject) => {
       child.once("error", reject);
-      child.once("exit", resolve);
+      child.once("exit", resolve2);
     }).finally(() => {
       clearTimeout(timer);
       kill();
@@ -303,7 +592,9 @@ async function main() {
       const actual = exists.trim() === "0" ? null : output.replace(/\n$/, "");
       infrastructureAssertions.push({ service: "redis", key: assertion.key, expected: assertion.equals, actual, passed: actual === assertion.equals });
     }
-    const status = world.unsupported.length || spec.fault && !world.faultTriggered ? "incomplete" : timedOut || exitCode !== 0 ? "error" : [...assertions, ...infrastructureAssertions].every((a) => a.passed) ? "passed" : "failed";
+    const initialState = Object.fromEntries(spec.services.map((s) => [s.name, Object.fromEntries(s.collections.map((c) => [c.path, c.seed]))]));
+    const evaluation = evaluateState(spec, initialState, world.state, world.events);
+    const status = world.unsupported.length || spec.fault && !world.faultTriggered ? "incomplete" : timedOut || exitCode !== 0 ? "error" : evaluation.outcome === "passed" && infrastructureAssertions.every((a) => a.passed) ? "passed" : "failed";
     for (const c of Object.values(credentials)) {
       stdout = stdout.split(c.token).join("[test-token]");
       stderr = stderr.split(c.token).join("[test-token]");
@@ -320,6 +611,9 @@ async function main() {
       application: { command: spec.command, exitCode, timedOut, stdout, stderr },
       assertions,
       infrastructureAssertions,
+      evaluation,
+      contracts: operationMatrix(spec),
+      scenario: spec.scenario,
       fault: spec.fault ? { ...spec.fault, triggered: world.faultTriggered } : null,
       initialState: Object.fromEntries(spec.services.map((s) => [s.name, Object.fromEntries(s.collections.map((c) => [c.path, c.seed]))])),
       finalState: world.state,