@gigzen/populace 1.3.2 → 1.3.4

package/README.md

@@ -25,18 +25,19 @@ applying**. Then it hands you a report on what broke.
 
 ---
 
-## It has done this to a real, finished app
+## It has done this to a real app
 
 ![Populace report for Buzz, 21 August 2026 — no failures across 932,455 API calls from 200 simulated drivers across 20 cities in 11 countries](docs/buzz-run-2026-08-21.svg)
 
-That is the *second* run. The first one is the interesting one.
+That is a later run. The first one is the interesting one.
 
 ### What happened, in plain English
 
 On **9 August 2026** we pointed Populace at **Buzz** — a gig-worker platform
 on Android with a live Postgres backend, 17 tables and 48 row-level-security
-policies. It was finished. It was signed. It had been through a full manual test
-of every screen by the person who wrote it, and it had passed.
+policies. It has since been renamed [**Waggle**](https://shakhtar-sankur.github.io/gigzen/waggle.html).
+It had not launched yet, but it was signed, and it had been through a full manual
+test of every screen by the person who wrote it, and it had passed.
 
 We started six simulated drivers: three in **Manila**, three in **Mumbai**. Each
 one signed up for a real account, set a profile, started driving a plausible
@@ -137,6 +138,20 @@ Two files land in whatever directory you ran it from: `populace-report.json` for
 CI, and `populace-report.html`, which is one self-contained page you can email
 to someone who was not watching your terminal.
 
+### Or skip the terminal
+
+[**Populace Studio**](https://github.com/Shakhtar-Sankur/populace/releases/latest) is
+the same engine in a window, for Windows, with no Node or npm needed. Download the
+installer or the portable build and check it against `SHA256SUMS.txt` on the release.
+Neither is code-signed yet, so Windows SmartScreen will warn before the first launch.
+
+Studio shows every simulated person on a world map as they move, and a box per contract
+method with its live latency. A method your adapter implements but the run never called is
+drawn dashed and named in the verdict, so it is not counted as covered. When something breaks,
+Studio shows the failing method and the database's own error text while the run is still
+going. It does not reimplement the engine: every run is the same command a terminal would
+issue, and Studio prints that command.
+
 ---
 
 ## Point it at your own app
@@ -152,7 +167,7 @@ You write **one adapter** — thirteen small methods, each answering "how does
 this happen in my app?". Two are required (`createUser`, `deleteUser`);
 everything else is optional and anything you skip is reported as untested rather
 than quietly passing. Full spec in [adapters/contract.md](adapters/contract.md),
-and [adapters/buzzbuzz.mjs](adapters/buzzbuzz.mjs) is a complete real-world
+and [adapters/waggle.mjs](adapters/waggle.mjs) is a complete real-world
 example in ~150 lines.
 
 `populace doctor` on a fresh scaffold says `2/13` and refuses to run — a method
@@ -418,7 +433,7 @@ multi-user simulation is best at finding.
 - **A populated app** instead of an empty one — the cold-start problem, solved for demos and for judging your own UX
 - **Multi-user paths exercised** without recruiting humans: presence, receipts, realtime fan-out, membership counts
 - **Permission rules tested by users who genuinely have different identities**
-- **Latency per endpoint** (p50/p95/p99/max) under N concurrent users
+- **Latency per endpoint** (p50/p95/max) under N concurrent users
 - **Failures grouped by shape**, not exact text, so one bug is one line rather than fifty
 - **Account deletion actually tested** — the path almost nobody exercises and the one regulators ask about
 - **`populace-report.json`** for CI; the run exits non-zero when problems are found

package/adapters/{buzzbuzz.mjs → waggle.mjs}

@@ -1,4 +1,8 @@
-// Adapter: Buzz — a gig-driver tracking app on Supabase.
+// Adapter: Waggle — a gig-driver tracking app on Supabase.
+//
+// (This file was adapters/buzzbuzz.mjs until the app was renamed Waggle. The
+// table names and the phone-to-email scheme below are the app's own and did
+// not change with the name.)
 //
 // Populace's first customer, and the reference implementation. Read this
 // alongside contract.md to see what a complete adapter looks like: it is ~140
@@ -20,13 +24,13 @@ export function createAdapter(target) {
 
   if (!url || !key) {
     throw new Error(
-      "buzzbuzz adapter needs target.url and target.key.\n" +
+      "waggle adapter needs target.url and target.key.\n" +
         "  Set BUZZBUZZ_TEST_URL and BUZZBUZZ_TEST_KEY in your environment.",
     );
   }
 
   return {
-    name: "buzzbuzz",
+    name: "waggle",
 
     // supabase-js RETURNS network errors rather than throwing, so without this
     // a wrong URL looks identical to "that account doesn't exist" — and a run

package/examples/rest-api/adapter.mjs

@@ -2,7 +2,7 @@
  * An adapter for a plain REST API — the second one Populace has ever had, and
  * the reason the portability claim is more than a hope.
  *
- * Read this next to adapters/buzzbuzz.mjs. They share no library, no id type,
+ * Read this next to adapters/waggle.mjs. They share no library, no id type,
  * no error convention and no auth mechanism, and the engine cannot tell them
  * apart. That is the whole argument.
  *

package/examples/{buzzbuzz → waggle}/populace.config.mjs

@@ -3,11 +3,11 @@
 // Run it — PowerShell (Windows):
 //   $env:BUZZBUZZ_TEST_URL="https://<your-TEST-project>.supabase.co"
 //   $env:BUZZBUZZ_TEST_KEY="<test project publishable key>"
-//   node src/cli.mjs run --config examples/buzzbuzz/populace.config.mjs
+//   node src/cli.mjs run --config examples/waggle/populace.config.mjs
 //
 // Run it — bash/zsh (macOS, Linux):
 //   BUZZBUZZ_TEST_URL=... BUZZBUZZ_TEST_KEY=... \
-//     node src/cli.mjs run --config examples/buzzbuzz/populace.config.mjs
+//     node src/cli.mjs run --config examples/waggle/populace.config.mjs
 //
 // The test project needs the same schema as production. Run these against it:
 //   schema.sql · social_features.sql · groups.sql · direct_messages.sql
@@ -18,7 +18,7 @@
 
 export default {
   app: "Buzz",
-  adapter: "../../adapters/buzzbuzz.mjs",
+  adapter: "../../adapters/waggle.mjs",
   environment: "test",
 
   target: {

package/examples/{buzzbuzz-local → waggle-local}/populace.config.mjs

@@ -1,6 +1,6 @@
 // Buzz against the local Supabase stack, at a scale the hosted project refuses.
 //
-// Why this file exists rather than reusing examples/buzzbuzz:
+// Why this file exists rather than reusing examples/waggle:
 //
 // The hosted test project applies Supabase's default auth rate limit of 30 sign
 // ups per five minutes per IP address. Measured on 2026-08-24: a 250-driver run
@@ -20,11 +20,11 @@
 //   npx supabase start
 //
 // Then either pick this file in Populace Studio, or:
-//   node src/cli.mjs run --config examples/buzzbuzz-local/populace.config.mjs
+//   node src/cli.mjs run --config examples/waggle-local/populace.config.mjs
 
 export default {
   app: "Buzz",
-  adapter: "../../adapters/buzzbuzz.mjs",
+  adapter: "../../adapters/waggle.mjs",
   environment: "test",
 
   // The local stack's fixed development address and publishable key. These are
@@ -35,7 +35,7 @@ export default {
     key: "sb_publishable_ACJWlzQHlZjBrEguHvfOxg_3BJgxAaH",
   },
 
-  // Kept identical to examples/buzzbuzz. A local run is no reason to relax the
+  // Kept identical to examples/waggle. A local run is no reason to relax the
   // guard: if one of these ever appears in `target.url` above, refuse to start.
   neverRunAgainst: [
     "https://rqzuuvlougzhynckvqzd.supabase.co",

package/package.json

@@ -1,60 +1,60 @@
-{
-  "name": "@gigzen/populace",
-  "version": "1.3.2",
-  "description": "A simulated population that uses your app through its real API, so you can test what needs more than one person.",
-  "type": "module",
-  "bin": {
-    "populace": "./src/cli.mjs"
-  },
-  "main": "./src/index.mjs",
-  "exports": {
-    ".": "./src/index.mjs",
-    "./engine": "./src/engine/index.mjs"
-  },
-  "files": [
-    "src",
-    "adapters",
-    "examples",
-    "!**/populace-report.json",
-    "!**/populace-report.html",
-    "!examples/buzzbuzz/run-test.ps1",
-    "populace.config.example.mjs",
-    "README.md",
-    "LICENSE",
-    "action.yml"
-  ],
-  "scripts": {
-    "demo": "node src/cli.mjs demo",
-    "doctor": "node src/cli.mjs doctor",
-    "test": "node src/selftest.mjs",
-    "prepublishOnly": "node src/selftest.mjs"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "simulation",
-    "testing",
-    "load-testing",
-    "multi-user",
-    "synthetic-users",
-    "qa"
-  ],
-  "license": "AGPL-3.0-only",
-  "dependencies": {},
-  "devDependencies": {
-    "@supabase/supabase-js": "^2.45.0"
-  },
-  "author": "Sankur Kundu <sankur.kundu.tw@gmail.com>",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Shakhtar-Sankur/populace.git"
-  },
-  "homepage": "https://github.com/Shakhtar-Sankur/populace#readme",
-  "bugs": {
-    "url": "https://github.com/Shakhtar-Sankur/populace/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@gigzen/populace",
+  "version": "1.3.4",
+  "description": "A simulated population that uses your app through its real API, so you can test what needs more than one person.",
+  "type": "module",
+  "bin": {
+    "populace": "./src/cli.mjs"
+  },
+  "main": "./src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./engine": "./src/engine/index.mjs"
+  },
+  "files": [
+    "src",
+    "adapters",
+    "examples",
+    "!**/populace-report.json",
+    "!**/populace-report.html",
+    "!examples/waggle/run-test.ps1",
+    "populace.config.example.mjs",
+    "README.md",
+    "LICENSE",
+    "action.yml"
+  ],
+  "scripts": {
+    "demo": "node src/cli.mjs demo",
+    "doctor": "node src/cli.mjs doctor",
+    "test": "node src/selftest.mjs",
+    "prepublishOnly": "node src/selftest.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "simulation",
+    "testing",
+    "load-testing",
+    "multi-user",
+    "synthetic-users",
+    "qa"
+  ],
+  "license": "AGPL-3.0-only",
+  "dependencies": {},
+  "devDependencies": {
+    "@supabase/supabase-js": "^2.45.0"
+  },
+  "author": "Sankur Kundu <sankur.kundu.tw@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Shakhtar-Sankur/populace.git"
+  },
+  "homepage": "https://github.com/Shakhtar-Sankur/populace#readme",
+  "bugs": {
+    "url": "https://github.com/Shakhtar-Sankur/populace/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/html-report.mjs

@@ -50,6 +50,15 @@ export function renderHtmlReport(report) {
     )
     .join("");
 
+  // Implemented but never called. Kept apart from notTested because the fix is
+  // different: nothing to write, the run just has to reach it.
+  const notExercised = (r.coverage.notExercised || [])
+    .map(
+      (c) =>
+        `<li><span class="mono">${esc(c.method)}</span><span class="would">still untested: ${esc(c.wouldHaveTested)}</span></li>`,
+    )
+    .join("");
+
   const problems = r.verdict.problems.map((p) => `<li>${esc(p)}</li>`).join("");
 
   const engineBlock = engineBroke
@@ -170,7 +179,7 @@ ${engineBlock}
   <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 class="stat"><span class="v">${esc(r.coverage.label)}</span><span class="l">methods exercised</span></div>
 </div>
 
 <section>
@@ -194,10 +203,19 @@ ${engineBlock}
   </div>
 </section>
 
+${
+  notExercised
+    ? `<section>
+  <h2>Not exercised — implemented, but this run never called it</h2>
+  <div class="panel"><ul class="cov">${notExercised}</ul></div>
+</section>`
+    : ""
+}
+
 ${
   notTested
     ? `<section>
-  <h2>Not tested — adapter implements ${esc(r.coverage.label)}</h2>
+  <h2>Not tested — adapter implements ${esc(r.coverage.implementedLabel ?? r.coverage.label)}</h2>
   <div class="panel"><ul class="cov">${notTested}</ul></div>
 </section>`
     : ""

package/src/report.mjs

@@ -66,15 +66,39 @@ export function buildReport({ config, adapter, world, metrics, teardown, started
       groupJoins: totals.groups,
     },
     api,
-    coverage: {
-      label: coverage.label,
-      implemented: coverage.implemented.map((c) => c.method),
-      notTested: coverage.missing.map((c) => ({ method: c.method, wouldHaveTested: c.exercises })),
-    },
+    coverage: coverageFor(coverage, api),
     cleanup: teardown ?? { skipped: true, note: "Agents were left in place. Run `populace clean`." },
   };
 }
 
+/**
+ * Coverage counts what RAN, not what exists.
+ *
+ * It used to be the adapter's implemented count, so a three-minute run printed
+ * "Coverage was 13/13" having never once called refreshSession, which fires
+ * every thirty minutes. That is the same overclaim `isStub` exists to stop — a
+ * method credited as tested because it is there — just one step later.
+ *
+ * `label` is exercised/total. `implementedLabel` keeps what the adapter
+ * provides, because "not tested because you never wrote it" and "not tested
+ * because this run never reached it" have different fixes.
+ */
+function coverageFor(coverage, api) {
+  const total = coverage.implemented.length + coverage.missing.length;
+  const called = new Set((api.methods || []).filter((m) => m.calls > 0).map((m) => m.method));
+  const exercised = coverage.implemented.filter((c) => called.has(c.method));
+  return {
+    label: `${exercised.length}/${total}`,
+    implementedLabel: coverage.label,
+    implemented: coverage.implemented.map((c) => c.method),
+    exercised: exercised.map((c) => c.method),
+    notExercised: coverage.implemented
+      .filter((c) => !called.has(c.method))
+      .map((c) => ({ method: c.method, wouldHaveTested: c.exercises })),
+    notTested: coverage.missing.map((c) => ({ method: c.method, wouldHaveTested: c.exercises })),
+  };
+}
+
 /**
  * Deliberately conservative. Anything unproven is called unproven, never
  * "passed" — including a run where nothing failed because nothing ran.
@@ -256,8 +280,16 @@ export function renderReport(report) {
     }
   }
 
+  if (report.coverage.notExercised?.length) {
+    L.push(`  NOT EXERCISED — implemented, but this run never called it (coverage ${report.coverage.label})`);
+    for (const c of report.coverage.notExercised) {
+      L.push(`    · ${c.method.padEnd(21)} still untested: ${c.wouldHaveTested}`);
+    }
+    L.push("");
+  }
+
   if (report.coverage.notTested.length) {
-    L.push(`  NOT TESTED — adapter implements ${report.coverage.label}`);
+    L.push(`  NOT TESTED — adapter implements ${report.coverage.implementedLabel ?? report.coverage.label}`);
     for (const c of report.coverage.notTested) {
       L.push(`    · ${c.method.padEnd(21)} would have tested ${c.wouldHaveTested}`);
     }

package/src/selftest.mjs

@@ -27,6 +27,7 @@ import {
 } from "./instrument.mjs";
 import { guardProduction } from "./config.mjs";
 import { buildReport, renderReport } from "./report.mjs";
+import { renderHtmlReport } from "./html-report.mjs";
 import { canSignInOnly, CONTRACT_METHODS, coverageOf, isStub } from "./contract.mjs";
 import { diagnose } from "./diagnose.mjs";
 import { fill, match } from "./openapi.mjs";
@@ -348,6 +349,58 @@ check("skipped methods are listed with what they would have tested", () => {
   assert.ok(skipped?.wouldHaveTested.length > 10, "a gap should say what it costs you");
 });
 
+// Coverage is what RAN. A hosted run on 12 September printed "Coverage was
+// 13/13" having never called refreshSession, which fires every 30 minutes and
+// the run lasted under five. Implemented is not exercised.
+check("coverage counts methods that ran, not methods that exist", () => {
+  const ran = new Set(cleanReport.api.methods.filter((m) => m.calls > 0).map((m) => m.method));
+  const { coverage } = cleanReport;
+  for (const m of coverage.exercised) assert.ok(ran.has(m), `${m} counted as exercised with no calls`);
+  for (const c of coverage.notExercised) assert.ok(!ran.has(c.method), `${c.method} ran but is listed as not exercised`);
+  assert.equal(
+    coverage.exercised.length + coverage.notExercised.length,
+    coverage.implemented.length,
+    "every implemented method is either exercised or named as not",
+  );
+  assert.equal(coverage.label, `${coverage.exercised.length}/13`, "the headline label is the exercised count");
+});
+
+// A first draft of the next check guarded itself with "if the adapter does not
+// implement refreshSession, return" — and the in-memory adapter does not, so it
+// passed without asserting anything. It now builds the exact case it is about:
+// refreshSession implemented for real, and a run far too short to reach it.
+const idleAdapter = {
+  ...inMemoryAdapter(),
+  async refreshSession(user) {
+    await Promise.resolve();
+    return user;
+  },
+};
+const idleMetrics = createMetrics();
+const idleWorld = new World({
+  adapter: instrument(idleAdapter, idleMetrics),
+  personas: buildPersonas(3, ["manila"]),
+});
+await idleWorld.populate({ staggerMs: 0 });
+await idleWorld.run({ minutes: 1, tickSeconds: 5, realtime: false });
+const idleTeardown = await idleWorld.teardown();
+idleMetrics.endedAt = Date.now();
+const idleReport = buildReport({
+  config, adapter: idleAdapter, world: idleWorld,
+  metrics: idleMetrics, teardown: idleTeardown, startedAt: Date.now() - 5000,
+});
+
+check("an implemented method that never ran is named, and not counted", () => {
+  const { coverage } = idleReport;
+  assert.ok(coverage.implemented.includes("refreshSession"), "setup: refreshSession must be implemented");
+  assert.ok(!coverage.exercised.includes("refreshSession"), "a one-minute run cannot reach a 30-minute refresh");
+  const idle = coverage.notExercised.find((c) => c.method === "refreshSession");
+  assert.ok(idle?.wouldHaveTested.length > 10, "a never-called method should say what stays untested");
+  assert.notEqual(coverage.label, coverage.implementedLabel, "exercised must not quietly equal implemented");
+  assert.ok(/NOT EXERCISED/.test(renderReport(idleReport)), "the terminal report must say so");
+  assert.ok(/Not exercised/.test(renderHtmlReport(idleReport)), "and so must the page people share");
+});
+
 // --- 4b. cleanup that does not write to the customer's database -----------
 // clean reaches an account through createUser, which SIGNS UP when the identity
 // is absent. On an already-clean environment that creates every simulated