@gigzen/populace 0.1.0

package/adapters/template-rest.mjs

@@ -0,0 +1,192 @@
+/**
+ * Adapter template — REST API with a bearer token.
+ *
+ * This is not a sketch. It is the adapter from examples/rest-api/, which has
+ * been run against a live server: 430 API calls, 0 failures, 13/13 methods.
+ * Every URL and field name below is marked EDIT — change those and the wiring
+ * around them already works.
+ *
+ * Start it up and see for yourself before you change anything:
+ *
+ *   node examples/rest-api/server.mjs
+ *   populace smoke --config examples/rest-api/populace.config.mjs
+ *
+ * Two rules, both in adapters/contract.md:
+ *   1. Never point this at production.
+ *   2. Go through your real API. No admin keys, no direct database writes — a
+ *      simulation that bypasses your permission rules proves nothing about
+ *      whether they work.
+ */
+
+export function createAdapter(target, config) {
+  const base = target.url.replace(/\/$/, "");
+
+  /**
+   * The contract hands you a name, a phone and a persona — never a password.
+   * Choosing one is your job, because only you know what your API accepts.
+   *
+   * It must be STABLE. Identities are deterministic so that a re-run signs
+   * back into the same accounts instead of piling up new ones, and that only
+   * works if the credential is stable too.
+   */
+  const PASSWORD = "PopulaceSim!2026";           // EDIT if your rules differ
+
+  /**
+   * One place where HTTP becomes either a value or a thrown Error.
+   *
+   * Two things here matter more than they look:
+   *
+   * NEVER RETURN QUIETLY ON FAILURE. An adapter that swallows an error makes
+   * the report blame a later method for an earlier fault. Populace's own first
+   * run found exactly that bug in its own reference adapter: the report said
+   * "post failed 14 times" when the truth was "the profile row was never
+   * created".
+   *
+   * DESCRIBE THE FAULT, NOT THE REQUEST. Failures are grouped by shape, so
+   * "409 on POST /likes" collapses into one line. Put the post id in the
+   * message and one bug becomes fifty.
+   */
+  async function call(method, path, { token, body } = {}) {
+    const res = await fetch(`${base}${path}`, {
+      method,
+      headers: {
+        ...(body ? { "content-type": "application/json" } : {}),
+        ...(token ? { authorization: `Bearer ${token}` } : {}),   // EDIT: header scheme
+      },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(15000),
+    });
+
+    if (res.status === 204) return undefined;
+
+    const text = await res.text();
+    let payload;
+    try { payload = text ? JSON.parse(text) : undefined; } catch { payload = undefined; }
+
+    if (!res.ok) {
+      const detail = payload?.error || text.slice(0, 120) || "no body";
+      throw new Error(`${res.status} on ${method} ${path}: ${detail}`);
+    }
+    return payload;
+  }
+
+  return {
+    name: "my-app",                                             // EDIT
+
+    // doctor calls this, so an unreachable target is caught before you spend
+    // a run finding out.
+    async healthCheck() {
+      const res = await fetch(`${base}/health`, { signal: AbortSignal.timeout(10000) });   // EDIT
+      if (!res.ok) throw new Error(`health check returned ${res.status}`);
+    },
+
+    // ── identity ────────────────────────────────────────────────────────
+    // REQUIRED. The argument is exactly this shape; see adapters/contract.md.
+    // Return a HANDLE — you get it back as `user` on every later call, so put
+    // the token, session or client on it. The engine only ever reads `.id`.
+    async createUser({ name, phone, persona, index }) {
+      const out = await call("POST", "/auth/signup", {          // EDIT
+        body: { phone, password: PASSWORD, name },              // EDIT: field names
+      });
+      return { id: out.id, token: out.token };                  // EDIT: response shape
+    },
+
+    // Optional but worth it: lets `populace clean` check for leftover accounts
+    // without CREATING them to find out whether they exist. Return null when
+    // the account genuinely is not there, and throw for anything else — the
+    // difference is what stops "I could not look" being reported as "nothing
+    // was there".
+    async signIn({ phone }) {
+      try {
+        const out = await call("POST", "/auth/signin", {        // EDIT
+          body: { phone, password: PASSWORD },
+        });
+        return { id: out.id, token: out.token };
+      } catch (error) {
+        if (/^401/.test(error.message)) return null;
+        throw error;
+      }
+    },
+
+    // IMPLEMENT THIS IF YOUR TOKENS EXPIRE. Populace calls it periodically.
+    // Without it, any run longer than your token lifetime collapses all at
+    // once, the report blames your API for what were really expired tokens,
+    // and cleanup cannot delete its own accounts — leaving simulated people
+    // in your environment.
+    async refreshSession(user) {
+      const out = await call("POST", "/auth/refresh", { token: user.token });   // EDIT
+      user.token = out.token;
+      return user;
+    },
+
+    async setProfile(user, persona) {
+      await call("PATCH", "/me", {                              // EDIT
+        token: user.token,
+        body: { name: persona.name, city: persona.city?.name },
+      });
+    },
+
+    // REQUIRED. The path almost nobody exercises, and the one regulators ask
+    // about.
+    async deleteUser(user) {
+      await call("DELETE", "/me", { token: user.token });       // EDIT
+    },
+
+    // ── movement ────────────────────────────────────────────────────────
+    // Usually the heaviest sustained write load an app takes. Delete if your
+    // product has no location.
+    async reportLocation(user, { lat, lng, distanceKm, earnings, platform }) {
+      await call("POST", "/locations", {                        // EDIT
+        token: user.token,
+        body: { lat, lng, km: distanceKm },
+      });
+    },
+
+    // ── social ──────────────────────────────────────────────────────────
+    // Must return the new post's id, or `like` and `comment` have nothing to
+    // act on.
+    async post(user, text) {
+      const out = await call("POST", "/posts", { token: user.token, body: { body: text } });  // EDIT
+      return out.id;
+    },
+
+    // Return an array. Objects with an `id`, or bare ids — both are accepted.
+    // This is the call that catches a feed leaking other people's rows.
+    async recentPostsByOthers(user, limit) {
+      return await call("GET", "/posts/others", { token: user.token });          // EDIT
+    },
+
+    async like(user, postId) {
+      await call("POST", "/likes", { token: user.token, body: { postId } });     // EDIT
+    },
+
+    async comment(user, postId, text) {
+      await call("POST", "/comments", { token: user.token, body: { postId, body: text } });   // EDIT
+    },
+
+    // ── messaging ───────────────────────────────────────────────────────
+    async openConversation(user, otherUserId) {
+      const out = await call("POST", "/threads", {              // EDIT
+        token: user.token,
+        body: { otherUserId },
+      });
+      return out.id;                                            // conversation id
+    },
+
+    async sendMessage(user, conversationId, text) {
+      await call("POST", "/messages", {                         // EDIT
+        token: user.token,
+        body: { threadId: conversationId, body: text },
+      });
+    },
+
+    // ── groups ──────────────────────────────────────────────────────────
+    async listGroups(user) {
+      return await call("GET", "/groups", { token: user.token });               // EDIT
+    },
+
+    async joinGroup(user, groupId) {
+      await call("POST", "/groups/join", { token: user.token, body: { groupId } });  // EDIT
+    },
+  };
+}

package/adapters/template.mjs

@@ -0,0 +1,80 @@
+// Your adapter.
+//
+// Each method answers one question: "when a simulated person does this, what
+// happens in MY app?" Delete the ones that don't apply — anything you leave out
+// is skipped, and `populace doctor` will tell you exactly what that costs you
+// in coverage.
+//
+// Two rules, both in adapters/contract.md:
+//   1. Never point this at production.
+//   2. Go through your real API. No admin keys, no direct database writes.
+//      A simulation that bypasses your permission rules proves nothing about
+//      whether they work.
+
+export function createAdapter(target, config) {
+  return {
+    name: "my-app",
+
+    // Optional, but `populace doctor` uses it to check the target is up before
+    // you spend a run finding out that it isn't.
+    async healthCheck() {
+      const res = await fetch(`${target.url}/health`, { signal: AbortSignal.timeout(10000) });
+      if (!res.ok) throw new Error(`health check returned ${res.status}`);
+    },
+
+    // --- identity (createUser is REQUIRED) --------------------------------
+    // Create or re-use an account. Return a handle — you'll get it back on
+    // every later call, so put the session/token/client on it.
+    // Re-runs should REUSE accounts, not pile up new ones.
+    async createUser({ name, phone, persona, index }) {
+      // const session = await signUpOrSignIn(...)
+      // return { id: session.userId, session };
+      throw new Error("createUser not implemented");
+    },
+
+    async setProfile(user, persona) {},
+
+    // If your API uses expiring access tokens, IMPLEMENT THIS. Populace calls
+    // it every 30 minutes (see session.refreshEveryMinutes). Without it, a run
+    // longer than your token lifetime fails everywhere at once and the report
+    // blames your API — and cleanup can't run either, leaving simulated
+    // accounts stranded in your environment.
+    async refreshSession(user) {},
+
+    // --- the world --------------------------------------------------------
+    // Called every tick with a new position and running totals. Skip it
+    // entirely if your app has no location.
+    async reportLocation(user, { lat, lng, distanceKm, earnings, platform }) {},
+
+    // --- social -----------------------------------------------------------
+    // Empty bodies below are treated as NOT implemented, and `populace doctor`
+    // will list them as untested rather than pretending they passed. Fill in
+    // the ones your app has; delete the ones it doesn't.
+    async post(user, text) {
+      // return postId
+    },
+    async recentPostsByOthers(user, limit) {
+      // return [{ id, userId }]
+    },
+    async like(user, postId) {},
+    async comment(user, postId, text) {},
+
+    async openConversation(user, otherUserId) {
+      // return conversationId
+    },
+    async sendMessage(user, conversationId, text) {},
+
+    async listGroups(user) {
+      // return [{ id }]
+    },
+    async joinGroup(user, groupId) {},
+
+    // --- cleanup (REQUIRED) -----------------------------------------------
+    // Must fully remove the account. Prefer your app's OWN delete-account path
+    // so the simulation exercises it too — it is the route almost nobody tests
+    // and the one regulators ask about.
+    async deleteUser(user) {
+      throw new Error("deleteUser not implemented");
+    },
+  };
+}

package/examples/buzzbuzz/populace-report.html

@@ -0,0 +1,245 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Populace report — Buzz Buzz</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>Buzz Buzz</h1>
+  <span class="sub">test environment · 10 simulated people ·
+    14m 38s · Sat, 15 Aug 2026 11:18:42 GMT</span>
+</header>
+
+<div class="verdict ok">
+  <h2>No failures across 2030 API calls</h2>
+  
+</div>
+
+
+
+<div class="stats">
+  <div class="stat"><span class="v">2030</span><span class="l">API calls</span></div>
+  <div class="stat"><span class="v" style="color:var(--ok)">0</span><span class="l">failed</span></div>
+  <div class="stat"><span class="v">0.0%</span><span class="l">failure rate</span></div>
+  <div class="stat"><span class="v">10</span><span class="l">concurrent users</span></div>
+  <div class="stat"><span class="v">13/13</span><span class="l">coverage</span></div>
+</div>
+
+<section>
+  <h2>Your API under 10 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>
+      <tr class="">
+        <td class="mono name">reportLocation</td>
+        <td class="num">892</td>
+        <td class="num zero">0</td>
+        <td class="num">711ms</td>
+        <td class="num">1.0s</td>
+        <td class="barcell"><div class="bar" style="width:100.0%"></div></td>
+      </tr>
+      
+      <tr class="">
+        <td class="mono name">recentPostsByOthers</td>
+        <td class="num">298</td>
+        <td class="num zero">0</td>
+        <td class="num">241ms</td>
+        <td class="num">349ms</td>
+        <td class="barcell"><div class="bar" style="width:34.8%"></div></td>
+      </tr>
+      
+      <tr class="">
+        <td class="mono name">like</td>
+        <td class="num">296</td>
+        <td class="num zero">0</td>
+        <td class="num">238ms</td>
+        <td class="num">319ms</td>
+        <td class="barcell"><div class="bar" style="width:31.8%"></div></td>
+      </tr>
+      
+      <tr class="">
+        <td class="mono name">post</td>
+        <td class="num">139</td>
+        <td class="num zero">0</td>
+        <td class="num">240ms</td>
+        <td class="num">313ms</td>
+        <td class="barcell"><div class="bar" style="width:31.2%"></div></td>
+      </tr>
+      
+      <tr class="">
+        <td class="mono name">comment</td>
+        <td class="num">123</td>
+        <td class="num zero">0</td>
+        <td class="num">243ms</td>
+        <td class="num">326ms</td>
+        <td class="barcell"><div class="bar" style="width:32.5%"></div></td>
+      </tr>
+      
+      <tr class="">
+        <td class="mono name">openConversation</td>
+        <td class="num">110</td>
+        <td class="num zero">0</td>
+        <td class="num">245ms</td>
+        <td class="num">336ms</td>
+        <td class="barcell"><div class="bar" style="width:33.5%"></div></td>
+      </tr>
+      
+      <tr class="">
+        <td class="mono name">sendMessage</td>
+        <td class="num">110</td>
+        <td class="num zero">0</td>
+        <td class="num">244ms</td>
+        <td class="num">351ms</td>
+        <td class="barcell"><div class="bar" style="width:35.0%"></div></td>
+      </tr>
+      
+      <tr class="">
+        <td class="mono name">listGroups</td>
+        <td class="num">16</td>
+        <td class="num zero">0</td>
+        <td class="num">250ms</td>
+        <td class="num">312ms</td>
+        <td class="barcell"><div class="bar" style="width:31.1%"></div></td>
+      </tr>
+      
+      <tr class="">
+        <td class="mono name">joinGroup</td>
+        <td class="num">16</td>
+        <td class="num zero">0</td>
+        <td class="num">235ms</td>
+        <td class="num">311ms</td>
+        <td class="barcell"><div class="bar" style="width:31.0%"></div></td>
+      </tr>
+      
+      <tr class="">
+        <td class="mono name">createUser</td>
+        <td class="num">10</td>
+        <td class="num zero">0</td>
+        <td class="num">601ms</td>
+        <td class="num">834ms</td>
+        <td class="barcell"><div class="bar" style="width:83.2%"></div></td>
+      </tr>
+      
+      <tr class="">
+        <td class="mono name">setProfile</td>
+        <td class="num">10</td>
+        <td class="num zero">0</td>
+        <td class="num">249ms</td>
+        <td class="num">392ms</td>
+        <td class="barcell"><div class="bar" style="width:39.1%"></div></td>
+      </tr>
+      
+      <tr class="">
+        <td class="mono name">deleteUser</td>
+        <td class="num">10</td>
+        <td class="num zero">0</td>
+        <td class="num">320ms</td>
+        <td class="num">508ms</td>
+        <td class="barcell"><div class="bar" style="width:50.6%"></div></td>
+      </tr>
+      </tbody>
+    </table>
+  </div>
+</section>
+
+<section>
+  <h2>What the population did</h2>
+  <div class="panel">
+    36 km travelled · 139 posts ·
+    296 likes · 123 comments ·
+    110 messages · 16 group joins
+  </div>
+</section>
+
+
+
+<section>
+  <h2>Cleanup</h2>
+  <div><div class="chip ok">Cleanup complete — 10 accounts removed</div></div>
+</section>
+
+<footer>
+  <span>Generated by Populace 0.1.0 · adapter <span class="mono">../../adapters/buzzbuzz.mjs</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>