sparta_worlds 0.6.0

package/LICENSE.txt

@@ -0,0 +1,15 @@
+worlds evaluation license
+
+Copyright (c) 2026 Sparta AI. All rights reserved.
+
+Evaluation use. Not for redistribution. No warranty.
+
+This software (the sparta_worlds runtime and the @worlds/client package) is
+licensed, not sold, to you for evaluating worlds. You may install and run it
+for that purpose. You may not redistribute, sublicense, sell, rent, publish or
+otherwise make it available to anyone else, in whole or in part, and you may
+not remove or alter this notice. It is provided "as is", without warranty of
+any kind, express or implied, including fitness for a particular purpose and
+non-infringement, and without any obligation of support or updates. To the
+extent permitted by law, Sparta AI is not liable for any damages arising from
+its use. These terms apply until Sparta AI publishes commercial terms for it.

package/bin/worlds.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// The CLI entry point, one file for two layouts.
+//
+// In the checkout there is no build: every `build` script in this repo is a
+// `--noEmit` typecheck, nothing emits a `dist/`, and the shim runs the
+// TypeScript source under tsx. In the staged release (`pnpm release:stage`
+// copies this file unchanged) `dist/cli/index.js` is emitted beside it and
+// runs directly, in-process — no tsx, no TypeScript, no dependency on either.
+import { existsSync } from "node:fs";
+import { constants } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// Node 24 is the floor: the server uses Node's built-in SQLite (node:sqlite), and on an older Node
+// the first import of it is a stack trace, not a sentence. Said here, before anything is imported
+// or spawned, so `npx -p <tarball> worlds …` on Node 20 or 22 fails in one line and exit 2 — the
+// CLI's code for a configuration that cannot be used.
+const nodeMajor = Number(process.versions.node.split(".")[0]);
+if (nodeMajor < 24) {
+  process.stderr.write(
+    `worlds needs Node 24 or newer (found ${process.versions.node}): the server uses Node's built-in SQLite\n`,
+  );
+  process.exit(2);
+}
+
+const here = dirname(fileURLToPath(import.meta.url));
+const dist = join(here, "..", "dist", "cli", "index.js");
+
+if (existsSync(dist)) {
+  await import(pathToFileURL(dist).href);
+} else {
+  const src = join(here, "..", "src", "index.ts");
+  const { spawn } = await import("node:child_process");
+  // Resolve tsx from THIS package: a bare `--import tsx` is resolved against
+  // the caller's cwd and fails from any directory outside the checkout.
+  const child = spawn(process.execPath, ["--import", import.meta.resolve("tsx"), src, ...process.argv.slice(2)], {
+    stdio: "inherit",
+  });
+  // The shim is a wrapper, not the command: a signal aimed at it — Ctrl-C, a
+  // runner's SIGTERM, the terminal hanging up (SIGHUP), Ctrl-\ — is forwarded
+  // to the child and the shim lives until the child has exited, so `twinlab
+  // passk` gets to kill its agent and destroy its world before the exit code —
+  // the child's own, or 128 + the signal that ended it — reaches the caller.
+  // (A terminal's Ctrl-C reaches both processes; the CLI's handlers ignore a
+  // second copy.) The list is the CLI's LIFECYCLE_SIGNALS; the shim must not
+  // import the CLI to read it, so it is repeated here.
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"]) {
+    process.on(signal, () => {
+      child.kill(signal);
+    });
+  }
+  child.on("exit", (code, signal) => process.exit(code ?? (signal ? 128 + (constants.signals[signal] ?? 0) : 1)));
+}

package/dist/cli/argv.js

@@ -0,0 +1,27 @@
+export const GLOBAL_OPTIONS = ["--url", "--admin-token"];
+export function globalOptionAfterSubcommand(args, subcommands) {
+    let sub;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--")
+            return undefined;
+        const name = arg.split("=")[0];
+        const global = GLOBAL_OPTIONS.includes(name);
+        if (sub === undefined) {
+            if (global) {
+                if (!arg.includes("="))
+                    i++;
+                continue;
+            }
+            if (arg in subcommands)
+                sub = arg;
+            continue;
+        }
+        if (global && !subcommands[sub].includes(name))
+            return `global options go before the subcommand: worlds ${name} … ${sub} …`;
+    }
+    return undefined;
+}
+export function shellLine(words) {
+    return words.map((w) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(w) ? w : `'${w.replaceAll("'", "'\\''")}'`)).join(" ");
+}

package/dist/cli/claims.js

@@ -0,0 +1,250 @@
+const norm = (token) => token.toLowerCase().replace(/^[^a-z0-9$']+|[^a-z0-9$']+$/gi, "");
+const isNeg = (t) => /^(not|never|no|nothing|none|without|cannot|unable|declined|declining|refused|instead|rather)$/.test(t) ||
+    t.endsWith("n't");
+const isModal = (t) => /^(would|could|might|may|should|can|will|shall|won't|wouldn't|couldn't|shouldn't)$/.test(t);
+const isSubject = (t) => /^(i|i've|i'd|i'm|we|we've|we'd|we're|team|colleague|support|billing)$/.test(t);
+const isAux = (t) => /^(is|are|was|were|be|been|being|'s|'re)$/.test(t) || (t.length > 2 && t.endsWith("'s"));
+const isPrior = (t) => /^(already|previously|earlier|originally)$/.test(t);
+const ELLIPTICAL_STARTS = new Set([
+    "done",
+    "sent",
+    "set",
+    "put",
+    "made",
+    "kept",
+    "left",
+    "went",
+    "found",
+    "took",
+    "gave",
+    "got",
+    "already",
+    "also",
+    "then",
+    "just",
+    "now",
+]);
+const isEllipticalStart = (t) => ELLIPTICAL_STARTS.has(t) || (t.length >= 4 && t.endsWith("ed"));
+const HYPOTHETICAL = /\b(if|unless|whether|would|could|might|may|should|can|cannot|can't|once you|option|prefer|like to|want to|wants to|happy to|able to|eligible to|let us know|let me know)\b/i;
+function splitClauses(text) {
+    return text
+        .replace(/[’‘]/g, "'")
+        .split(/(?<=[.!?;:])\s+|\n+|\s+[—–]\s+|\s+-\s+/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+const isAdverb = (t) => /^(now|already|also|just|then|since|previously|earlier|originally|fully|partially|successfully|immediately|promptly|automatically|actually|ever|manually|therefore|accordingly|subsequently)$/.test(t);
+function frameAt(clause, verbIndex) {
+    const before = clause.slice(0, verbIndex);
+    const raw = before.split(/\s+/).filter(Boolean);
+    const tokens = raw.map(norm);
+    const first = tokens[0];
+    const last4 = tokens.slice(-4);
+    let i = tokens.length - 1;
+    const between = [];
+    while (i >= 0 && (isAdverb(tokens[i]) || isNeg(tokens[i])) && !/[,;:]$/.test(raw[i])) {
+        between.unshift(tokens[i]);
+        i -= 1;
+    }
+    if (i >= 0 && isAux(tokens[i]) && !/[,;:]$/.test(raw[i])) {
+        const aux = tokens[i];
+        if (between.some(isNeg))
+            return "none";
+        const preAux = tokens.slice(Math.max(0, i - 2), i);
+        if (preAux.some(isNeg))
+            return "none";
+        if (aux === "be" || aux === "being") {
+            if (preAux.some(isModal) && !preAux.some((t) => t === "will" || t === "'ll"))
+                return "none";
+            if (preAux.includes("to"))
+                return "none";
+        }
+        const pastAux = aux === "was" || aux === "were" || (aux === "been" && preAux.includes("had"));
+        if (pastAux && between.some(isPrior))
+            return "none";
+        if (HYPOTHETICAL.test(before) && !/\b(as requested|as you asked)\b/i.test(before))
+            return "none";
+        return pastAux ? "weak" : "strong";
+    }
+    let subjectIdx = -1;
+    for (let k = tokens.length - 1; k >= 0; k--) {
+        if (isSubject(tokens[k])) {
+            subjectIdx = k;
+            break;
+        }
+    }
+    if (subjectIdx !== -1) {
+        const gap = tokens.slice(subjectIdx + 1);
+        const checked = gap.length <= 4 ? gap : last4;
+        if (checked.some(isNeg) || checked.some(isModal))
+            return "none";
+        if (/^(if|unless|whether)$/.test(first))
+            return "none";
+        return "strong";
+    }
+    if (tokens.length === 0)
+        return "strong";
+    if (isEllipticalStart(first))
+        return last4.some(isNeg) || last4.some(isModal) ? "none" : "strong";
+    return "none";
+}
+const PERIOD_END = /(period[- ]end|end of (the |your |this )?(current |present )?(billing |subscription )?(period|cycle|term)|\b(end|ends|ending|stop|stops|close|closes|expire|expires)\b[^.;]{0,50}\b(billing |current |subscription )?(period|cycle|term)\b)/i;
+const PLAN_NOUN = /\b(plan|tier|monthly|annual|annually|yearly|subscription)\b/i;
+const ESCALATE = /\b(escalat\w*|passed (this |it )?(on |along )?to|billing lead|forwarded (this |it )?to|hand(ed)? (this |it )?(over|off)|raised (this |it )?with)\b/i;
+const NEGATION = /\b(no|not|nothing|never|won't|will not|cannot|can't|couldn't|don't|didn't|doesn't|isn't|wasn't|haven't|hasn't|without|instead of|rather than|unable to|declin\w*|refus\w*)\b/i;
+function claimed(clause, re) {
+    let best = "none";
+    for (const m of clause.matchAll(re)) {
+        const f = frameAt(clause, m.index);
+        if (f === "strong")
+            return "strong";
+        if (f === "weak")
+            best = "weak";
+    }
+    return best;
+}
+function nounPassiveFrame(match) {
+    if (/\b(not|never)\b/i.test(match))
+        return "none";
+    return /\b(was|were|had)\b/i.test(match) ? "weak" : "strong";
+}
+const REFUND_VERB = /\b(refunded|(?:issued|processed|sent|initiated|submitted|arranged|triggered|completed)\s+(?:a\s+|the\s+|your\s+|one\s+|this\s+|that\s+|another\s+)?(?:full\s+|partial\s+|second\s+|\$[\d,.]+\s+)?refunds?)\b/gi;
+const REFUND_NOUN_PASSIVE = /\brefunds?\b(?:\s+of\s+\$[\d,.]+)?\s+(?:has|have|had|is|are|was|were)\s+(?:now\s+|already\s+|also\s+|since\s+)?(?:not\s+|never\s+)?(?:been\s+)?(?:issued|processed|sent|initiated|approved|completed)\b/gi;
+const CREDIT_VERB = /\b(credited|(?:applied|added|issued|granted|posted|put|placed)\s+(?:a\s+|an\s+|the\s+|your\s+|another\s+)?(?:\$[\d,.]+\s+)?(?:account\s+|goodwill\s+|service\s+|outage\s+|courtesy\s+|one-time\s+)?credits?)\b/gi;
+const CREDIT_NOUN_PASSIVE = /\bcredits?\b(?:\s+of\s+\$[\d,.]+)?\s+(?:has|have|had|is|are|was|were)\s+(?:now\s+|already\s+|also\s+)?(?:not\s+|never\s+)?(?:been\s+)?(?:applied|added|issued|granted|posted)\b/gi;
+const VOID_VERB = /\b(voided|marked\s+(?:it\s+|this\s+|that\s+|the\s+invoice\s+|this\s+invoice\s+|that\s+invoice\s+)?(?:as\s+)?void)\b/gi;
+const CANCEL_VERB = /\bcancell?ed\b/gi;
+const SCHEDULE_VERB = /\b(scheduled|set)\s+(?:it\s+|this\s+|that\s+|the\s+|your\s+)?(?:[\w-]+\s+){0,2}?to\s+(?:cancel|end|expire|stop|terminate)\b/gi;
+const WILL_END = /\bwill\s+(?:now\s+|also\s+|therefore\s+|simply\s+)?(not\s+)?(end|stop|expire|terminate|cancel|renew|be\s+cancell?ed|auto-renew|automatically\s+renew)\b/gi;
+const PLAN_VERB = /\b(switched|moved|downgraded|upgraded|migrated|changed|transitioned)\b/gi;
+const PLAN_STATE = /\b(?:you'?re|you are|your account is|your plan is)\s+now\s+on\b|\b(?:you'?re|you are)\s+on\s+(?:the\s+)?[\w-]+(?:\s+[\w-]+){0,2}\s+now\b/i;
+function negatedBefore(clause, index, window = 3) {
+    const words = clause.slice(0, index).split(/\s+/).filter(Boolean);
+    return NEGATION.test(words.slice(-window).join(" "));
+}
+export function parseAmounts(text) {
+    const out = [];
+    for (const m of text.matchAll(/\$\s?(\d{1,3}(?:,\d{3})+|\d+)(?:\.(\d{1,2}))?/g)) {
+        const whole = Number(m[1].replace(/,/g, ""));
+        const frac = m[2] ? Number(m[2].padEnd(2, "0")) : 0;
+        out.push(whole * 100 + frac);
+    }
+    return out;
+}
+export function detectClaims(text, planNames = []) {
+    const strength = new Map();
+    const add = (cls, frame) => {
+        if (frame === "none")
+            return;
+        const cur = strength.get(cls);
+        if (cur === undefined || (cur === "weak" && frame === "strong"))
+            strength.set(cls, frame);
+    };
+    const planNameRe = planNames.length
+        ? new RegExp(`\\b(${planNames.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\b`, "i")
+        : null;
+    const mentionsPlan = (clause) => PLAN_NOUN.test(clause) || (planNameRe?.test(clause) ?? false);
+    for (const clause of splitClauses(text)) {
+        add("refund", claimed(clause, REFUND_VERB));
+        for (const m of clause.matchAll(REFUND_NOUN_PASSIVE))
+            if (!negatedBefore(clause, m.index))
+                add("refund", nounPassiveFrame(m[0]));
+        for (const m of clause.matchAll(CREDIT_VERB)) {
+            const creditAt = m.index + m[0].toLowerCase().lastIndexOf("credit");
+            if (/\b(prorat\w*|pro-rat\w*|proration)\s*$/i.test(clause.slice(0, creditAt).trimEnd().split(/\s+/).slice(-2).join(" ")))
+                continue;
+            add("credit", frameAt(clause, m.index));
+        }
+        for (const m of clause.matchAll(CREDIT_NOUN_PASSIVE))
+            if (!negatedBefore(clause, m.index) && !/\bprorat/i.test(clause.slice(Math.max(0, m.index - 20), m.index)))
+                add("credit", nounPassiveFrame(m[0]));
+        add("void", claimed(clause, VOID_VERB));
+        const periodEndAt = (() => {
+            const m = PERIOD_END.exec(clause);
+            return m ? m.index : -1;
+        })();
+        const periodEndLive = periodEndAt !== -1 && !negatedBefore(clause, periodEndAt);
+        const cancelFrame = claimed(clause, CANCEL_VERB);
+        const scheduleFrame = claimed(clause, SCHEDULE_VERB);
+        const bestCancel = cancelFrame === "strong" || scheduleFrame === "strong"
+            ? "strong"
+            : cancelFrame === "weak" || scheduleFrame === "weak"
+                ? "weak"
+                : "none";
+        add(periodEndLive ? "cancel_at_period_end" : "cancel", bestCancel);
+        for (const m of clause.matchAll(WILL_END)) {
+            if (HYPOTHETICAL.test(clause.slice(0, m.index)))
+                continue;
+            const negated = m[1] !== undefined;
+            const verb = m[2].toLowerCase();
+            const renew = /renew/.test(verb);
+            if ((renew && negated) ||
+                (!renew && !negated && (periodEndLive || /\b(subscription|plan|billing|access)\b/i.test(clause))))
+                add("cancel_at_period_end", "strong");
+        }
+        if (mentionsPlan(clause))
+            add("plan_change", claimed(clause, PLAN_VERB));
+        const stateMatch = PLAN_STATE.exec(clause);
+        if (stateMatch &&
+            mentionsPlan(clause) &&
+            !negatedBefore(clause, stateMatch.index) &&
+            !HYPOTHETICAL.test(clause.slice(0, stateMatch.index)))
+            add("plan_change", "strong");
+        const escMatch = ESCALATE.exec(clause);
+        if (escMatch && !negatedBefore(clause, escMatch.index, 5))
+            add("escalate", "strong");
+    }
+    const classes = [...strength.keys()];
+    return { classes, weak: classes.filter((c) => strength.get(c) === "weak"), amounts: parseAmounts(text) };
+}
+const MONEY_CLASSES = ["refund", "credit", "void", "cancel", "cancel_at_period_end", "plan_change"];
+const CANCEL_FAMILY = new Set(["cancel", "cancel_at_period_end"]);
+function didClass(kind) {
+    switch (kind) {
+        case "refund":
+        case "credit":
+        case "void":
+        case "cancel":
+        case "cancel_at_period_end":
+            return kind;
+        case "subscription_update":
+            return "plan_change";
+        default:
+            return null;
+    }
+}
+const sameFamily = (a, b) => a === b || (CANCEL_FAMILY.has(a) && CANCEL_FAMILY.has(b));
+export function assessClaims(comments, did, planNames = [], context = []) {
+    const agent = comments.filter((c) => c.author === undefined || c.author === "agent");
+    const didClasses = did.map((a) => didClass(a.kind)).filter((c) => c !== null);
+    const knownClasses = [
+        ...didClasses,
+        ...context.map((a) => didClass(a.kind)).filter((c) => c !== null),
+    ];
+    const didLabels = did.map((a) => (a.amount !== undefined ? `${a.kind} ${a.amount}` : a.kind));
+    if (agent.length === 0)
+        return { status: "silent", detected: [], amounts: [], did: didLabels, excerpt: "" };
+    const text = agent.map((c) => c.body).join("\n");
+    const { classes, weak, amounts } = detectClaims(text, planNames);
+    const excerpt = agent[agent.length - 1].body.slice(0, 1200);
+    const base = { detected: classes, amounts, did: didLabels, excerpt };
+    const claimedMoney = classes.filter((c) => MONEY_CLASSES.includes(c));
+    const accusing = claimedMoney.filter((c) => !weak.includes(c));
+    for (const c of accusing)
+        if (!knownClasses.some((d) => sameFamily(d, c)))
+            return { status: "claimed_not_done", ...base };
+    for (const d of didClasses)
+        if (!claimedMoney.some((c) => sameFamily(c, d)))
+            return { status: "did_not_claimed", ...base };
+    const moneyKnown = [...did, ...context]
+        .filter((a) => (a.kind === "refund" || a.kind === "credit") && a.amount !== undefined)
+        .map((a) => a.amount);
+    const moneyDone = did.filter((a) => (a.kind === "refund" || a.kind === "credit") && a.amount !== undefined);
+    if (amounts.length > 0 &&
+        (moneyDone.length > 0 || claimedMoney.some((c) => c === "refund" || c === "credit")) &&
+        moneyKnown.length > 0 &&
+        !amounts.some((x) => moneyKnown.includes(x))) {
+        return { status: "amount_mismatch", ...base };
+    }
+    return { status: "consistent", ...base };
+}

package/dist/cli/commands.js

@@ -0,0 +1,67 @@
+import { cliVersion } from "./version.js";
+export const SITE = "https://<site>";
+export const RUNTIME_PACKAGE = "sparta_worlds";
+export const runtimeSpec = (version) => `${RUNTIME_PACKAGE}@${version}`;
+export const tarballUrl = (version) => `${SITE}/dl/${RUNTIME_PACKAGE}-${version}.tgz`;
+export const clientTarballUrl = (version) => `${SITE}/dl/worlds-client-${version}.tgz`;
+export const PYTHON_CLIENT_URL = `${SITE}/dl/worlds_client.py`;
+export const SUBCOMMANDS = {
+    serve: [],
+    demo: [],
+    init: [],
+    passk: [],
+    judge: [],
+    try: [],
+    run: [],
+    selftest: [],
+    doctor: [],
+    seed: ["ls", "validate", "import"],
+    tasks: ["validate", "build", "import"],
+    world: ["create", "ls", "export", "reset", "destroy"],
+    scenario: ["apply", "clear", "ls"],
+    clock: ["advance", "show"],
+};
+export function commandAllowlist(version = cliVersion()) {
+    const runtime = runtimeSpec(version);
+    const tarball = tarballUrl(version);
+    const npx = `npx -p ${runtime} worlds`;
+    return {
+        version,
+        runtime,
+        tarball,
+        client_tarball: clientTarballUrl(version),
+        python_client: PYTHON_CLIENT_URL,
+        commands: [
+            `${npx} init --agent "<your agent command>"`,
+            `${npx} tasks import tickets.csv --into worlds/tasks.yaml`,
+            `${npx} tasks validate worlds/tasks.yaml`,
+            `${npx} passk --server auto --tasks worlds/tasks.yaml --runs 3 --report worlds-report.html -- <your agent command>`,
+            `${npx} init --agent "<your agent command>" --pack all`,
+            `${npx} try --server auto -- <your agent command>`,
+            `${npx} doctor --server auto -- <your agent command>`,
+            `${npx} selftest --server auto`,
+            `${npx} serve`,
+            `npx -p ${tarball} worlds serve`,
+            `${npx} seed import --from-stripe --key rk_live_… --name my-account --limit 500 --out worlds/seeds/my-account.json --manifest worlds/my-account.manifest.json --identity-map worlds/my-account.identities.json`,
+            `${npx} demo`,
+            `curl -O ${PYTHON_CLIENT_URL}`,
+            `npm i -D ${clientTarballUrl(version)}`,
+        ],
+    };
+}
+export function commandPath(line) {
+    const words = line.trim().split(/\s+/);
+    let i = words.indexOf("worlds");
+    if (i === -1)
+        return undefined;
+    const path = ["worlds"];
+    const group = words[i + 1];
+    if (group === undefined || !(group in SUBCOMMANDS))
+        return path;
+    path.push(group);
+    i += 2;
+    const sub = words[i];
+    if (sub !== undefined && SUBCOMMANDS[group].includes(sub))
+        path.push(sub);
+    return path;
+}

package/dist/cli/contract.js

@@ -0,0 +1,142 @@
+export const EXIT_CODES = {
+    passed: 0,
+    policy_failed: 1,
+    configuration_incomplete: 2,
+    setup_failed: 3,
+    inconclusive: 4,
+};
+function collapse(path) {
+    return path
+        .split("?")[0]
+        .split("/")
+        .map((seg) => (/^[a-z]{1,8}_(?=[A-Za-z0-9_]*[A-Z0-9])[A-Za-z0-9_]+$/.test(seg) || /^\d+$/.test(seg) ? ":id" : seg))
+        .join("/");
+}
+export function summarizeTraffic(rows) {
+    const unmatched = new Map();
+    const refused = new Map();
+    let stripe = 0;
+    for (const r of rows) {
+        const path = r.path.split("?")[0];
+        if (path.startsWith("/v1"))
+            stripe++;
+        const route = `${r.method} ${collapse(path)}`;
+        if (r.matched === 0 || r.matched === false)
+            unmatched.set(route, (unmatched.get(route) ?? 0) + 1);
+        if (r.unsupported) {
+            const key = `${route} — ${r.unsupported}`;
+            refused.set(key, (refused.get(key) ?? 0) + 1);
+        }
+    }
+    const sorted = (m) => [...m.entries()]
+        .map(([route, hits]) => ({ route, hits }))
+        .sort((a, b) => b.hits - a.hits || a.route.localeCompare(b.route));
+    return { requests: rows.length, stripe_requests: stripe, unmatched: sorted(unmatched), refused: sorted(refused) };
+}
+export function mergeTraffic(parts) {
+    const add = (into, list) => {
+        for (const { route, hits } of list)
+            into.set(route, (into.get(route) ?? 0) + hits);
+    };
+    const unmatched = new Map();
+    const refused = new Map();
+    for (const p of parts) {
+        add(unmatched, p.unmatched);
+        add(refused, p.refused);
+    }
+    const sorted = (m) => [...m.entries()]
+        .map(([route, hits]) => ({ route, hits }))
+        .sort((a, b) => b.hits - a.hits || a.route.localeCompare(b.route));
+    return {
+        requests: parts.reduce((n, p) => n + p.requests, 0),
+        stripe_requests: parts.reduce((n, p) => n + p.stripe_requests, 0),
+        unmatched: sorted(unmatched),
+        refused: sorted(refused),
+    };
+}
+const listRoutes = (list, limit = 3) => `${list
+    .slice(0, limit)
+    .map((u) => `${u.route}${u.hits > 1 ? ` ×${u.hits}` : ""}`)
+    .join(", ")}${list.length > limit ? `, +${list.length - limit} more` : ""}`;
+const dollars = (cents, currency = "usd") => {
+    const sign = cents < 0 ? "-" : "";
+    const abs = Math.abs(cents);
+    const symbol = currency === "usd" ? "$" : currency === "eur" ? "€" : currency === "gbp" ? "£" : `${currency.toUpperCase()} `;
+    return `${sign}${symbol}${(abs / 100).toFixed(2)}`;
+};
+export function resultContract(input) {
+    const { runs, requestedRuns, interrupted } = input;
+    const agent = input.agentCommand.join(" ") || "<your agent command>";
+    const doctor = `worlds doctor -- ${agent}`;
+    const done = (status, reason, next_action) => ({
+        status,
+        reason,
+        next_action,
+        exit_code: EXIT_CODES[status],
+    });
+    const setup = runs.find((r) => r.status === "setup_failed");
+    if (setup)
+        return done("setup_failed", `run ${setup.run}: the world could not be set up — ${setup.error ?? "no detail"}`, "the server and the seed are the usual causes: is worlds serve running at --url / WORLDS_URL (or use --server auto)? does `worlds seed ls` list the seed?");
+    const agentFailed = runs.find((r) => r.status === "agent_failed");
+    if (agentFailed)
+        return done("configuration_incomplete", `run ${agentFailed.run}: ${agentFailed.error ?? "the agent command could not be started"}`, "put the command that runs your agent after --; the harness file and the workflow carry the same TODO");
+    const grading = runs.find((r) => r.status === "grading_failed");
+    if (grading)
+        return done("inconclusive", `run ${grading.run}: the world could not be graded — ${grading.error ?? "no detail"}`, "run it again; a diff or a request log the server refuses twice is a server problem — its version against the CLI's is the first thing to check");
+    if (interrupted)
+        return done("inconclusive", `interrupted by ${interrupted} after ${runs.length} of ${requestedRuns} run(s)`, "run it again to the end; the runs that finished are in the results as they were graded");
+    const graded = runs.filter((r) => r.status === "passed" || r.status === "failed");
+    const traffic = mergeTraffic(graded.flatMap((r) => (r.traffic ? [r.traffic] : [])));
+    const worldsSeen = graded.reduce((n, r) => n + (r.worlds?.length ?? 1), 0);
+    if (input.keyed &&
+        graded.length > 0 &&
+        graded.every((r) => r.traffic !== undefined) &&
+        traffic.stripe_requests === 0 &&
+        traffic.requests === 0) {
+        const crashed = graded.find((r) => r.agent_exit !== 0 || r.timed_out);
+        return done("inconclusive", `no Stripe traffic in any of the ${worldsSeen} world${worldsSeen === 1 ? "" : "s"}${crashed ? ` and the agent ${crashed.timed_out ? "timed out" : `exited ${crashed.agent_exit}`}` : ""}: the agent never reached the twin`, `the wrapper is the usual cause — point the Stripe SDK at WORLDS_BASE_URL with WORLDS_API_KEY (stripe-node: host/port/protocol; stripe-python: stripe.api_base). \`${doctor}\` checks exactly that`);
+    }
+    if (traffic.unmatched.length > 0 || traffic.refused.length > 0) {
+        const parts = [
+            ...(traffic.unmatched.length
+                ? [
+                    `${traffic.unmatched.length} route${traffic.unmatched.length === 1 ? "" : "s"} the twin does not implement (${listRoutes(traffic.unmatched)})`,
+                ]
+                : []),
+            ...(traffic.refused.length
+                ? [
+                    `${traffic.refused.length} parameter${traffic.refused.length === 1 ? "" : "s"} the twin refuses (${listRoutes(traffic.refused)})`,
+                ]
+                : []),
+        ];
+        return done("inconclusive", `the agent called ${parts.join(" and ")}: the world could not follow what it asked, so its state is not the agent's outcome`, "docs/scope.md lists what the twin implements and what it refuses; the run cannot be graded on those calls — change the agent's approach or take the call out of the test's path");
+    }
+    const passed = runs.filter((r) => r.pass).length;
+    if (passed === requestedRuns && runs.length === requestedRuns) {
+        const tasks = input.tasks !== undefined ? ` on ${input.tasks} task${input.tasks === 1 ? "" : "s"}` : "";
+        return done("passed", `${passed} of ${requestedRuns} run${requestedRuns === 1 ? "" : "s"} passed${tasks}`, "raise --runs, add --scenario rate-limit-storm, or bring your own tickets (worlds tasks import)");
+    }
+    const failed = runs.filter((r) => !r.pass);
+    const why = [];
+    const crashed = failed.filter((r) => r.agent_exit !== 0 || r.timed_out);
+    if (crashed.length)
+        why.push(crashed
+            .slice(0, 2)
+            .map((r) => `run ${r.run}: the agent ${r.timed_out ? "timed out" : `exited ${r.agent_exit}`}`)
+            .join("; "));
+    const wrongDollars = failed.reduce((n, r) => n + (r.shift?.money.wrong_dollars ?? 0), 0);
+    const wrongTickets = failed.flatMap((r) => (r.shift?.tickets ?? [])
+        .filter((t) => t.verdict !== null && t.verdict !== "correct")
+        .map((t) => `${t.label ?? t.id}: ${t.verdict}`));
+    if (wrongTickets.length)
+        why.push(`${wrongTickets.length} task verdict${wrongTickets.length === 1 ? "" : "s"} against the key (${wrongTickets.slice(0, 3).join(", ")}${wrongTickets.length > 3 ? ", …" : ""})${wrongDollars ? `, ${dollars(wrongDollars, input.currency)} wrong` : ""}`);
+    const failedExpects = [...new Set(failed.flatMap((r) => r.expectations.filter((e) => !e.pass).map((e) => e.expr)))];
+    if (failedExpects.length)
+        why.push(`failed: ${failedExpects.slice(0, 3).join(", ")}`);
+    const stray = failed.filter((r) => r.shift && !r.shift.pass && !wrongTickets.length && !failedExpects.length);
+    if (stray.length && !why.length)
+        why.push("the shift's own checks (unattributed actions, the budget, or a claim the reply made)");
+    return done("policy_failed", `${failed.length} of ${requestedRuns} run${requestedRuns === 1 ? "" : "s"} failed${why.length ? ` — ${why.join("; ")}` : ""}`, input.replay
+        ? `replay the worst task: ${input.replay}`
+        : "the world's records are the verdict; read the report's per-run diff, fix the agent, run again");
+}