@gigzen/populace 0.1.0

package/src/engine/personas.mjs

@@ -0,0 +1,115 @@
+// Who the simulated people are.
+//
+// A persona is a city, a platform, a rate, and behaviour weights that decide
+// how often someone posts, chats, likes and takes breaks. The weights are the
+// whole trick: a quiet courier who never posts sitting next to a rider who
+// comments on everything is what makes a population read as people instead of
+// a loop. Identical bots find identical bugs.
+//
+// This is the built-in "mobile workers" pack. Supply your own via
+// `personas` in populace.config.mjs if your users are something else.
+
+export const CITIES = {
+  manila: { name: "Manila", lat: 14.5995, lng: 120.9842, currency: "PHP", rate: 10 },
+  mumbai: { name: "Mumbai", lat: 19.076, lng: 72.8777, currency: "INR", rate: 10 },
+  delhi: { name: "Delhi", lat: 28.6139, lng: 77.209, currency: "INR", rate: 10 },
+  jakarta: { name: "Jakarta", lat: -6.2088, lng: 106.8456, currency: "IDR", rate: 3000 },
+  bangkok: { name: "Bangkok", lat: 13.7563, lng: 100.5018, currency: "THB", rate: 6 },
+};
+
+// Chatter is per-city so a feed reads like the right place.
+const CHATTER = {
+  manila: [
+    "Heavy traffic sa EDSA southbound, mag-alternate route kayo",
+    "Surge ngayon sa BGC, sulit ang pila",
+    "Ingat sa Commonwealth, may flood sa gilid",
+    "Sino nandito sa Ortigas? Ang dami booking",
+    "Break muna, 6 hours na akong byahe",
+  ],
+  mumbai: [
+    "Andheri me bahut traffic hai, Link Road se jao",
+    "Bandra side surge chal raha hai abhi",
+    "Sion flyover pe jam, 25 min lag rahe hain",
+    "Koi Powai me hai? Bookings kaafi aa rahe hain",
+    "Chai break, subah se 80 km ho gaye",
+  ],
+  delhi: [
+    "Ring Road pe heavy jam, Outer se nikal jao",
+    "Connaught Place me surge hai abhi",
+    "Gurgaon toll pe lambi line lagi hai",
+    "Metro strike ki wajah se bookings badh gaye",
+    "Paani pi lo bhai, aaj bahut garmi hai",
+  ],
+  jakarta: [
+    "Macet parah di Sudirman, lewat jalan tikus aja",
+    "Lagi surge di Kuningan, lumayan",
+    "Hati-hati banjir di Kemang",
+    "Ada yang di Senayan? Orderan rame",
+    "Istirahat dulu, udah 7 jam narik",
+  ],
+  bangkok: [
+    "รถติดมากแถวสุขุมวิท ใช้ทางด่วนดีกว่า",
+    "ตอนนี้ราคาขึ้นแถวสีลม",
+    "ระวังน้ำท่วมแถวลาดพร้าว",
+    "ใครอยู่แถวอโศกบ้าง งานเยอะมาก",
+    "พักก่อน วิ่งมา 6 ชั่วโมงแล้ว",
+  ],
+};
+
+const REPLIES = [
+  "Thanks for the heads up 🙏",
+  "Same here, confirmed",
+  "Good to know, avoiding that route",
+  "How long is the wait?",
+  "Salamat / Thanks bhai",
+  "On my way there now",
+];
+
+const NAMES = {
+  manila: ["Jhun Ramirez", "Maricel Santos", "Dante Cruz", "Liza Bautista", "Noel Aquino"],
+  mumbai: ["Ramesh Kadam", "Priya Sharma", "Imran Shaikh", "Sunita Patil", "Arjun Nair"],
+  delhi: ["Vikas Yadav", "Neha Gupta", "Rahul Verma", "Pooja Singh", "Manoj Kumar"],
+  jakarta: ["Budi Santoso", "Siti Rahayu", "Agus Wijaya", "Dewi Lestari", "Eko Prasetyo"],
+  bangkok: ["Somchai Prasert", "Ratana Wong", "Niran Suk", "Malee Chai", "Kittipong S."],
+};
+
+const PLATFORMS = {
+  manila: ["grab", "angkas", "joyride", "foodpanda", "lalamove"],
+  mumbai: ["uber", "ola", "swiggy", "zomato", "rapido"],
+  delhi: ["uber", "ola", "blinkit", "zepto", "amazon"],
+  jakarta: ["gojek", "grab", "shopeefood", "maxim", "indrive"],
+  bangkok: ["grab", "foodpanda", "lalamove", "shopeefood", "bolt"],
+};
+
+const pick = (arr, i) => arr[i % arr.length];
+
+/** Build `count` personas spread across the given cities. */
+export function buildPersonas(count, cityKeys = Object.keys(CITIES)) {
+  const keys = cityKeys.filter((c) => CITIES[c]);
+  if (!keys.length) throw new Error(`Unknown cities. Available: ${Object.keys(CITIES).join(", ")}`);
+
+  const personas = [];
+  for (let i = 0; i < count; i++) {
+    const cityKey = keys[i % keys.length];
+    const city = CITIES[cityKey];
+    const n = Math.floor(i / keys.length);
+    personas.push({
+      id: `sim${String(i + 1).padStart(3, "0")}`,
+      cityKey,
+      city,
+      name: pick(NAMES[cityKey], n),
+      platform: pick(PLATFORMS[cityKey], n),
+      rate: city.rate,
+      // Behaviour weights — the reason the population feels human.
+      postiness: 0.05 + (i % 5) * 0.05, // 0.05 – 0.25 chance per tick
+      chattiness: 0.05 + (i % 4) * 0.06,
+      likeliness: 0.15 + (i % 3) * 0.2,
+      breakiness: 0.03 + (i % 6) * 0.02,
+      speedKmh: 18 + (i % 5) * 6, // 18–42 km/h city driving
+    });
+  }
+  return personas;
+}
+
+export const chatterFor = (cityKey, n) => pick(CHATTER[cityKey] ?? CHATTER.manila, n);
+export const replyLine = (n) => pick(REPLIES, n);

package/src/engine/world.mjs

@@ -0,0 +1,120 @@
+// Orchestrates a run: brings a population into existence, lets it live for a
+// while, then reports what happened. Knows nothing about the terminal — the CLI
+// passes callbacks in, so the same engine can drive a UI or a CI job later.
+
+import { Agent } from "./agent.mjs";
+import { buildPersonas } from "./personas.mjs";
+
+export class World {
+  constructor({ adapter, personas, options = {}, on = {} }) {
+    this.adapter = adapter;
+    this.personas = personas;
+    this.options = options;
+    this.on = on;
+    this.agents = [];
+    this.signupFailures = [];
+    this.stopping = false;
+  }
+
+  static fromConfig(config, adapter, on) {
+    const { agents = 6, cities } = config.population;
+    const personas =
+      typeof config.personas === "function"
+        ? config.personas(agents, cities)
+        : Array.isArray(config.personas)
+          ? config.personas
+          : buildPersonas(agents, cities);
+    const options = {
+      ...(config.identity || {}),
+      refreshEveryMs: (config.session?.refreshEveryMinutes ?? 30) * 60_000,
+    };
+    return new World({ adapter, personas, options, on });
+  }
+
+  /**
+   * Sign everyone in, staggered. Auth endpoints are commonly rate-limited, and
+   * a burst of simultaneous sign-ups produces a wall of 429s that looks like a
+   * bug in the customer's app when it is really a bug in this harness.
+   */
+  async populate({ staggerMs = 400 } = {}) {
+    for (const [i, persona] of this.personas.entries()) {
+      const agent = new Agent(persona, this.adapter, i, this.options);
+      try {
+        await agent.ensureAccount();
+        this.agents.push(agent);
+        this.on.joined?.(agent);
+      } catch (error) {
+        this.signupFailures.push({ persona: persona.name, error: String(error.message || error) });
+        this.on.joinFailed?.(persona, error);
+      }
+      if (staggerMs) await sleep(staggerMs);
+    }
+    return this.agents.length;
+  }
+
+  async run({ minutes = 10, tickSeconds = 5, realtime = true } = {}) {
+    const totalTicks = Math.max(1, Math.round((minutes * 60) / tickSeconds));
+    for (let tick = 1; tick <= totalTicks && !this.stopping; tick++) {
+      // Everyone acts concurrently, the way real users do. Sequential agents
+      // would never surface a race condition, which is half the reason to run
+      // a simulation at all.
+      await Promise.all(this.agents.map((a) => a.tick(tickSeconds, this)));
+      this.on.tick?.(tick, totalTicks, this);
+      if (realtime) await sleep(tickSeconds * 1000);
+    }
+    return this.totals();
+  }
+
+  /** Failures that never reached the adapter: bugs in this engine. */
+  engineErrors() {
+    return this.agents.flatMap((a) => a.engineErrors ?? []);
+  }
+
+  totals() {
+    return this.agents.reduce(
+      (acc, a) => {
+        acc.km += a.distanceKm;
+        for (const key of Object.keys(a.stats)) acc[key] = (acc[key] || 0) + a.stats[key];
+        return acc;
+      },
+      { km: 0, posts: 0, likes: 0, comments: 0, messages: 0, groups: 0, errors: 0 },
+    );
+  }
+
+  stop() {
+    this.stopping = true;
+  }
+
+  /** Remove every account this run created, through the app's own delete path. */
+  /**
+   * Three outcomes, never two. An account that was deleted, one there was
+   * nothing to delete for, and one whose deletion failed are different facts,
+   * and a cleanup line that merges the first two tells the customer their
+   * environment is clear when it may not be.
+   *
+   * `notDeleted` rather than `skipped`: the report already uses `skipped` as a
+   * boolean for --keep, and an empty array is truthy, so reusing the name would
+   * have made every clean run claim it had left its agents in place.
+   */
+  async teardown() {
+    const results = { removed: 0, notDeleted: [], failed: [] };
+    for (const agent of this.agents) {
+      try {
+        const outcome = await agent.selfDestruct();
+        if (outcome && outcome.deleted) {
+          results.removed += 1;
+        } else {
+          results.notDeleted.push({
+            name: agent.persona.name,
+            why: (outcome && outcome.why) || "nothing to delete",
+          });
+        }
+      } catch (error) {
+        results.failed.push({ name: agent.persona.name, error: String(error.message || error) });
+      }
+    }
+    return results;
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/src/html-report.mjs

@@ -0,0 +1,218 @@
+// Renders a run report as a single self-contained HTML file.
+//
+// The terminal output is for the person who started the run. This is for
+// everyone else — the colleague who wasn't watching, the client who paid for
+// the run, the ticket it gets attached to. It has to survive being emailed.
+//
+// No external anything: one file, inline CSS, no fonts or scripts fetched.
+
+const esc = (s) =>
+  String(s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+
+const pct = (n) => `${(n * 100).toFixed(n < 0.01 && n > 0 ? 2 : 1)}%`;
+const ms = (n) => (n >= 1000 ? `${(n / 1000).toFixed(1)}s` : `${Math.round(n)}ms`);
+const dur = (n) => (n >= 60000 ? `${Math.round(n / 60000)}m ${Math.round((n % 60000) / 1000)}s` : `${(n / 1000).toFixed(1)}s`);
+
+export function renderHtmlReport(report) {
+  const r = report;
+  const clean = r.verdict.status === "clean";
+  const engineBroke = (r.engineErrors?.length ?? 0) > 0;
+
+  // Latency bars are scaled to the slowest method, so the outlier is obvious
+  // at a glance rather than requiring the reader to compare numbers.
+  const slowest = Math.max(1, ...r.api.methods.map((m) => m.latencyMs.p95));
+
+  const methodRows = r.api.methods
+    .map((m) => {
+      const bad = m.failures > 0;
+      const width = Math.max(2, (m.latencyMs.p95 / slowest) * 100);
+      const errs = m.errors
+        .slice(0, 3)
+        .map((e) => `<div class="err"><span class="errn">${e.count}×</span>${esc(e.message)}</div>`)
+        .join("");
+      return `
+      <tr class="${bad ? "row-bad" : ""}">
+        <td class="mono name">${bad ? '<span class="x">✖</span>' : ""}${esc(m.method)}</td>
+        <td class="num">${m.calls}</td>
+        <td class="num ${bad ? "fail" : "zero"}">${m.failures}</td>
+        <td class="num">${ms(m.latencyMs.p50)}</td>
+        <td class="num">${ms(m.latencyMs.p95)}</td>
+        <td class="barcell"><div class="bar" style="width:${width.toFixed(1)}%"></div></td>
+      </tr>
+      ${errs ? `<tr class="errrow"><td colspan="6">${errs}</td></tr>` : ""}`;
+    })
+    .join("");
+
+  const notTested = (r.coverage.notTested || [])
+    .map(
+      (c) =>
+        `<li><span class="mono">${esc(c.method)}</span><span class="would">would have tested ${esc(c.wouldHaveTested)}</span></li>`,
+    )
+    .join("");
+
+  const problems = r.verdict.problems.map((p) => `<li>${esc(p)}</li>`).join("");
+
+  const engineBlock = engineBroke
+    ? `
+    <section class="panel danger">
+      <h2>Populace itself failed ${r.engineErrors.length} time(s)</h2>
+      <p>These failures never reached your app. They are bugs in the simulation, which
+      means <strong>this run did not test everything it claims to have tested</strong>.
+      Treat the results below as incomplete.</p>
+      <pre class="trace">${r.engineErrors.map(esc).join("\n\n")}</pre>
+    </section>`
+    : "";
+
+  const cleanupBlock = r.cleanup?.skipped
+    ? `<div class="chip warn">Cleanup skipped — ${r.population.signedIn} accounts still live</div>`
+    : r.cleanup?.failed?.length
+      ? `<div class="chip bad">Cleanup incomplete — ${r.cleanup.failed.length} accounts could not be deleted</div>`
+      : r.cleanup?.notDeleted?.length
+        ? `<div class="chip warn">Cleanup partial — ${r.cleanup.removed} removed, ${r.cleanup.notDeleted.length} had nothing to delete</div>`
+        : `<div class="chip ok">Cleanup complete — ${r.cleanup?.removed ?? 0} accounts removed</div>`;
+
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Populace report — ${esc(r.run.app)}</title>
+<style>
+:root{
+  --paper:#F4F5F7;--card:#fff;--ink:#12181D;--body:#3A454E;--muted:#6B7883;
+  --rule:#DDE2E7;--accent:#A85A0B;--ok:#2C6E4C;--bad:#A63127;--warn:#9A6A08;
+  --bar:#C9D4DC;--barbad:#E0A99F;
+  --mono:ui-monospace,"SF Mono","Cascadia Mono",Menlo,Consolas,monospace;
+  --sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Arial,sans-serif;
+}
+@media (prefers-color-scheme:dark){:root{
+  --paper:#0E1418;--card:#161E24;--ink:#E8EEF3;--body:#B0BDC7;--muted:#7B8994;
+  --rule:#26323A;--accent:#E0A45C;--ok:#5FAB80;--bad:#DE7568;--warn:#D2A24E;
+  --bar:#2E3A43;--barbad:#5C332C;}}
+:root[data-theme="dark"]{--paper:#0E1418;--card:#161E24;--ink:#E8EEF3;--body:#B0BDC7;
+  --muted:#7B8994;--rule:#26323A;--accent:#E0A45C;--ok:#5FAB80;--bad:#DE7568;
+  --warn:#D2A24E;--bar:#2E3A43;--barbad:#5C332C;}
+:root[data-theme="light"]{--paper:#F4F5F7;--card:#fff;--ink:#12181D;--body:#3A454E;
+  --muted:#6B7883;--rule:#DDE2E7;--accent:#A85A0B;--ok:#2C6E4C;--bad:#A63127;
+  --warn:#9A6A08;--bar:#C9D4DC;--barbad:#E0A99F;}
+*{box-sizing:border-box}
+body{margin:0;background:var(--paper);color:var(--body);font-family:var(--sans);
+  font-size:15.5px;line-height:1.6;-webkit-font-smoothing:antialiased}
+.wrap{max-width:900px;margin:0 auto;padding:0 22px 80px}
+h1,h2,h3{color:var(--ink);margin:0;text-wrap:balance}
+h1{font-family:var(--mono);font-size:clamp(22px,4vw,30px);letter-spacing:-.02em}
+h2{font-size:17px;font-family:var(--mono);letter-spacing:-.01em}
+.mono{font-family:var(--mono)}
+header{padding:44px 0 24px;border-bottom:2px solid var(--ink);display:flex;
+  flex-direction:column;gap:10px}
+.sub{font-family:var(--mono);font-size:12.5px;color:var(--muted)}
+.verdict{margin-top:26px;padding:20px 22px;border-radius:6px;display:flex;
+  flex-direction:column;gap:8px;border-left:4px solid}
+.verdict.ok{background:color-mix(in srgb,var(--ok) 8%,transparent);border-color:var(--ok)}
+.verdict.bad{background:color-mix(in srgb,var(--bad) 8%,transparent);border-color:var(--bad)}
+.verdict h2{color:var(--ink)}
+.verdict ul{margin:4px 0 0;padding-left:20px}
+.stats{display:grid;gap:12px;grid-template-columns:repeat(auto-fit,minmax(132px,1fr));margin-top:26px}
+.stat{background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:15px 16px}
+.stat .v{font-family:var(--mono);font-size:23px;color:var(--ink);font-weight:600;
+  letter-spacing:-.02em;font-variant-numeric:tabular-nums;display:block}
+.stat .l{font-family:var(--mono);font-size:10px;letter-spacing:.12em;
+  text-transform:uppercase;color:var(--muted)}
+section{margin-top:42px;display:flex;flex-direction:column;gap:14px}
+.panel{background:var(--card);border:1px solid var(--rule);border-radius:6px;padding:20px 22px}
+.panel.danger{border-color:var(--bad);border-left-width:4px}
+.panel.danger h2{color:var(--bad)}
+.tablewrap{overflow-x:auto;border:1px solid var(--rule);border-radius:6px;background:var(--card)}
+table{border-collapse:collapse;width:100%;min-width:600px}
+th,td{padding:10px 14px;text-align:left;border-bottom:1px solid var(--rule)}
+th{font-family:var(--mono);font-size:10px;letter-spacing:.12em;text-transform:uppercase;
+  color:var(--muted);font-weight:600}
+td.num{text-align:right;font-family:var(--mono);font-variant-numeric:tabular-nums;font-size:13.5px}
+td.name{font-size:13.5px;color:var(--ink);white-space:nowrap}
+td.zero{color:var(--muted)}
+td.fail{color:var(--bad);font-weight:600}
+.x{color:var(--bad);margin-right:6px}
+.barcell{width:120px}
+.bar{height:7px;background:var(--bar);border-radius:4px}
+.row-bad .bar{background:var(--barbad)}
+tr.errrow td{padding-top:0;border-bottom:1px solid var(--rule)}
+.err{font-family:var(--mono);font-size:12px;color:var(--bad);padding:3px 0 3px 26px}
+.errn{color:var(--muted);margin-right:8px}
+.trace{font-family:var(--mono);font-size:11.5px;white-space:pre-wrap;overflow-x:auto;
+  background:var(--paper);padding:14px;border-radius:5px;margin:0;color:var(--body)}
+ul.cov{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:9px}
+ul.cov li{display:flex;gap:14px;flex-wrap:wrap;align-items:baseline;font-size:14px}
+ul.cov .mono{color:var(--ink);min-width:170px;font-size:13px}
+.would{color:var(--muted);font-size:13.5px}
+.chip{display:inline-block;font-family:var(--mono);font-size:12px;padding:7px 13px;
+  border-radius:5px;border:1px solid}
+.chip.ok{color:var(--ok);border-color:var(--ok);background:color-mix(in srgb,var(--ok) 8%,transparent)}
+.chip.bad{color:var(--bad);border-color:var(--bad);background:color-mix(in srgb,var(--bad) 8%,transparent)}
+.chip.warn{color:var(--warn);border-color:var(--warn);background:color-mix(in srgb,var(--warn) 8%,transparent)}
+footer{margin-top:52px;padding-top:20px;border-top:1px solid var(--rule);
+  font-size:13px;color:var(--muted);display:flex;flex-direction:column;gap:6px}
+</style></head><body>
+<div class="wrap">
+
+<header>
+  <h1>${esc(r.run.app)}</h1>
+  <span class="sub">${esc(r.run.environment)} environment · ${r.population.signedIn} simulated people ·
+    ${dur(r.run.durationMs)} · ${esc(new Date(r.run.startedAt).toUTCString())}</span>
+</header>
+
+<div class="verdict ${clean ? "ok" : "bad"}">
+  <h2>${clean ? `No failures across ${r.api.calls} API calls` : "Problems found"}</h2>
+  ${clean ? "" : `<ul>${problems}</ul>`}
+</div>
+
+${engineBlock}
+
+<div class="stats">
+  <div class="stat"><span class="v">${r.api.calls}</span><span class="l">API calls</span></div>
+  <div class="stat"><span class="v" style="color:${r.api.failures ? "var(--bad)" : "var(--ok)"}">${r.api.failures}</span><span class="l">failed</span></div>
+  <div class="stat"><span class="v">${pct(r.api.failureRate)}</span><span class="l">failure rate</span></div>
+  <div class="stat"><span class="v">${r.population.signedIn}</span><span class="l">concurrent users</span></div>
+  <div class="stat"><span class="v">${esc(r.coverage.label)}</span><span class="l">coverage</span></div>
+</div>
+
+<section>
+  <h2>Your API under ${r.population.signedIn} concurrent users</h2>
+  <div class="tablewrap">
+    <table>
+      <thead><tr><th>Method</th><th style="text-align:right">Calls</th>
+        <th style="text-align:right">Fails</th><th style="text-align:right">p50</th>
+        <th style="text-align:right">p95</th><th>p95 relative</th></tr></thead>
+      <tbody>${methodRows}</tbody>
+    </table>
+  </div>
+</section>
+
+<section>
+  <h2>What the population did</h2>
+  <div class="panel">
+    ${r.activity.distanceKm} km travelled · ${r.activity.posts} posts ·
+    ${r.activity.likes} likes · ${r.activity.comments} comments ·
+    ${r.activity.messages} messages · ${r.activity.groupJoins} group joins
+  </div>
+</section>
+
+${
+  notTested
+    ? `<section>
+  <h2>Not tested — adapter implements ${esc(r.coverage.label)}</h2>
+  <div class="panel"><ul class="cov">${notTested}</ul></div>
+</section>`
+    : ""
+}
+
+<section>
+  <h2>Cleanup</h2>
+  <div>${cleanupBlock}</div>
+</section>
+
+<footer>
+  <span>Generated by Populace ${esc(r.populace.version)} · adapter <span class="mono">${esc(r.run.adapter)}</span></span>
+  <span>Simulated people are generated from patterns. This report shows whether your app
+  <strong>works</strong> — not whether anyone wants it.</span>
+</footer>
+
+</div></body></html>`;
+}

package/src/index.mjs

@@ -0,0 +1,38 @@
+// Programmatic entry point, for driving Populace from a CI job or a UI rather
+// than the terminal.
+//
+//   import { simulate } from "populace";
+//   const report = await simulate({ configPath: "./populace.config.mjs" });
+//   if (report.verdict.status !== "clean") process.exit(1);
+
+import { loadAdapter, loadConfig } from "./config.mjs";
+import { createMetrics, instrument } from "./instrument.mjs";
+import { buildReport } from "./report.mjs";
+import { World } from "./engine/world.mjs";
+
+export { loadConfig, loadAdapter, ConfigError } from "./config.mjs";
+export { CONTRACT, coverageOf } from "./contract.mjs";
+export { buildReport, renderReport, writeReport } from "./report.mjs";
+export { createMetrics, instrument, summarise } from "./instrument.mjs";
+export { World } from "./engine/world.mjs";
+export { Agent } from "./engine/agent.mjs";
+export { buildPersonas, CITIES } from "./engine/personas.mjs";
+
+export async function simulate({ configPath, overrides = {}, on = {}, cleanup = true } = {}) {
+  const config = await loadConfig({ configPath, overrides });
+  const raw = await loadAdapter(config);
+  const metrics = createMetrics();
+  const adapter = instrument(raw, metrics, { timeoutMs: config.timeoutMs, retries: config.retries, giveUpAfter: config.giveUpAfter });
+  const startedAt = Date.now();
+
+  const world = World.fromConfig(config, adapter, on);
+  await world.populate();
+  await world.run(config.population);
+
+  // Same fresh budget for the programmatic path — see cli.mjs.
+  if (cleanup) metrics.breaker?.reset();
+  const teardown = cleanup ? await world.teardown() : null;
+  metrics.endedAt = Date.now();
+
+  return buildReport({ config, adapter: raw, world, metrics, teardown, startedAt });
+}