@gigzen/populace 1.0.0 → 1.2.0

package/README.md

@@ -267,9 +267,13 @@ export ANTHROPIC_API_KEY=sk-ant-...
 populace explain
 ```
 
-Rules run first and the model only ever sees what they could not name — so most
-runs never call it at all, and the ones that do send a handful of short strings.
-Explanations that came from the model are labelled as such.
+Rules run first and the model only ever sees what they could not name, so most
+runs never call it at all. What is sent, exactly: the method name, the error
+message truncated to 500 characters, how many times it happened, and two
+latency numbers. No URL, no credential, no persona, nothing about your
+configuration. Note that the error message is your application's own text, so
+it can carry a table or column name — read one before you enable this if that
+matters to you. Explanations that came from the model are labelled as such.
 
 **What is sent, exactly:** the method name, the error text, how many times it
 happened, and that method's p50/p95. Nothing else — no target URL, no keys, no

package/examples/buzzbuzz-local/populace.config.mjs

@@ -0,0 +1,63 @@
+// Buzz against the local Supabase stack, at a scale the hosted project refuses.
+//
+// Why this file exists rather than reusing examples/buzzbuzz:
+//
+// 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
+// signs in 35 people and every remaining identity fails with "Request rate limit
+// reached". That limit is correct for real users, who each arrive from their own
+// address. A load test is the one case where every request shares a single IP,
+// so it is the one case the limit cannot accommodate.
+//
+// The local stack raises it in supabase/config.toml, which a hosted project
+// cannot do from a file. So large runs belong here.
+//
+// Everything is self-contained: no environment variables. Studio passes a config
+// path and nothing else, so a config that reads process.env works from a shell
+// and silently targets `undefined` when launched from Explorer.
+//
+// Start the backend first, from i-want-to-make-one-app:
+//   npx supabase start
+//
+// Then either pick this file in Populace Studio, or:
+//   node src/cli.mjs run --config examples/buzzbuzz-local/populace.config.mjs
+
+export default {
+  app: "Buzz",
+  adapter: "../../adapters/buzzbuzz.mjs",
+  environment: "test",
+
+  // The local stack's fixed development address and publishable key. These are
+  // the same on every machine that runs `supabase start` — they are not secrets
+  // and nothing outside this computer can reach them.
+  target: {
+    url: "http://127.0.0.1:54321",
+    key: "sb_publishable_ACJWlzQHlZjBrEguHvfOxg_3BJgxAaH",
+  },
+
+  // Kept identical to examples/buzzbuzz. 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",
+    "https://ypdaetbeexyepswyhbui.supabase.co",
+  ],
+
+  population: {
+    agents: 250,
+    // The same twenty-five cities as the 200-driver run of 23 August, so head
+    // count is the only variable that changed between the two.
+    cities: [
+      "manila", "mumbai", "delhi", "jakarta", "saopaulo",
+      "mexicocity", "bogota", "lima", "lagos", "nairobi",
+      "accra", "cairo", "johannesburg", "istanbul", "dubai",
+      "riyadh", "moscow", "kyiv", "warsaw", "madrid",
+      "almaty", "tashkent", "baku", "casablanca", "amman",
+    ],
+    minutes: 20,
+    tickSeconds: 2,
+    engagement: 4,
+  },
+
+  identity: { phonePrefix: "0900" },
+  report: { path: "populace-report.json" },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gigzen/populace",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "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": {
@@ -15,6 +15,9 @@
     "src",
     "adapters",
     "examples",
+    "!**/populace-report.json",
+    "!**/populace-report.html",
+    "!examples/buzzbuzz/run-test.ps1",
     "populace.config.example.mjs",
     "README.md",
     "LICENSE",

package/src/cli.mjs

@@ -12,6 +12,7 @@ import { fileURLToPath } from "node:url";
 import { ConfigError, loadAdapter, loadConfig } from "./config.mjs";
 import { createMetrics, instrument } from "./instrument.mjs";
 import { buildReport, renderReport, writeReport } from "./report.mjs";
+import { createProgress } from "./progress.mjs";
 import { canSignInOnly } from "./contract.mjs";
 import { isTransportError } from "./net.mjs";
 import { diagnose } from "./diagnose.mjs";
@@ -55,6 +56,7 @@ function overridesFromFlags() {
   if (flag("cities")) o.cities = String(flag("cities")).split(",").map((s) => s.trim()).filter(Boolean);
   if (flag("engagement")) o.engagement = Number(flag("engagement"));
   if (flag("report")) o.reportPath = flag("report");
+  if (flag("stagger")) o.signupStaggerMs = Number(flag("stagger"));
   return o;
 }
 
@@ -187,6 +189,28 @@ async function doctor() {
 
   const d = diagnose({ config, adapter: raw, reachable });
 
+  // --json for anything that has to describe a config without printing it -
+  // the desktop app shows this on the Run screen, so you can see what you are
+  // about to point a population at before you start one.
+  if (has("json")) {
+    console.log(JSON.stringify({
+      app: config.app || null,
+      environment: config.environment,
+      adapter: config.adapter,
+      target: config.target?.url || null,
+      coverage: d.coverage,
+      guarded: d.guarded,
+      cleanup: d.cleanup,
+      reachable,
+      reachError: reachable === false ? reachError : null,
+      ready: d.ready,
+      blockers: d.blockers,
+      population: config.population,
+    }));
+    if (!d.ready) process.exitCode = 1;
+    return;
+  }
+
   console.log(`
   Config    ${path.basename(config._file)}`);
   console.log(`  App       ${config.app || raw.name || "(unnamed)"}`);
@@ -231,13 +255,41 @@ async function run() {
   const startedAt = Date.now();
 
   const { agents, cities, minutes, tickSeconds } = config.population;
+
+  // Anything watching this run rather than reading it - the desktop app today,
+  // a dashboard tomorrow - gets the same numbers the terminal table shows,
+  // every tick, as JSON. Off unless asked, so ordinary output is untouched.
+  const progress = createProgress({ enabled: flag("progress") === "json" });
+  progress.start(config);
+
   console.log(`\n  Bringing ${agents} people to life across ${cities.join(", ")}…\n`);
 
+  // Sign-ups are counted here rather than in the engine, so the engine keeps
+  // knowing nothing about who is watching.
+  let joinedSoFar = 0;
   const world = World.fromConfig(config, adapter, {
-    joined: (a) => console.log(`   ✓ ${a.persona.name} (${a.persona.city.name}, ${a.persona.platform})`),
-    joinFailed: (p, e) => console.log(`   ✖ ${p.name}: ${e.message}`),
+    joined: (a) => {
+      console.log(`   ✓ ${a.persona.name} (${a.persona.city.name}, ${a.persona.platform})`);
+      progress.joining({
+        done: ++joinedSoFar, total: agents, ok: true,
+        name: a.persona.name, city: a.persona.city.name,
+      });
+    },
+    joinFailed: (p, e) => {
+      console.log(`   ✖ ${p.name}: ${e.message}`);
+      progress.joining({
+        done: ++joinedSoFar, total: agents, ok: false,
+        name: p.name, city: p.city?.name,
+      });
+    },
+    // Said out loud, because waiting silently is indistinguishable from hanging.
+    // Retrying a throttled sign-up can add seconds per person, and a run that
+    // pauses without explanation is a run somebody kills.
+    joinThrottled: (p, attempt) =>
+      console.log(`   … ${p.name}: rate limited, waiting (attempt ${attempt})`),
     tick: (n, total, w) => {
       render(config, n, total, w);
+      progress.tick(n, total, w, metrics);
       // Stop as soon as the target is judged gone. Grinding out the remaining
       // ticks against a dead host wastes the operator's time and adds nothing
       // to the report.
@@ -280,6 +332,7 @@ async function run() {
 
   metrics.endedAt = Date.now();
   const report = buildReport({ config, adapter: raw, world, metrics, teardown, startedAt });
+  progress.done(report);
   const files = writeReport(report, config);
   console.log(renderReport(report));
   console.log(`  Report:  ${displayPath(files.json)}`);
@@ -617,6 +670,19 @@ async function explainCmd() {
   }
 
   const explained = explainReport(report);
+
+  // --json for anything rendering this itself rather than reading a terminal.
+  // Same explanations, same order; only the presentation differs, so a window
+  // cannot show a cause the command line would not.
+  if (has("json")) {
+    console.log(JSON.stringify({
+      report: reportPath,
+      verdict: explained.length ? verdictLine(explained) : null,
+      explained,
+    }));
+    return;
+  }
+
   if (!explained.length) {
     console.log(`
   Nothing failed in ${displayPath(reportPath)}. Nothing to explain.
@@ -707,6 +773,8 @@ if (!commands[command]) {
     --tick <seconds>                  simulated seconds per step
     --cities <a,b>                    ${Object.keys(CITIES).join(", ")}
     --engagement <x>                  how busy people are; 1 = normal, 5 = relentless
+    --stagger <ms>                    gap between sign-ups; raise it for a
+                                      throttled auth endpoint (default 400)
     --report <path>                   where to write the report
     --keep                            leave accounts in place after a run
     --file <path>                     which report to re-open (report)

package/src/config.mjs

@@ -36,6 +36,19 @@ const DEFAULTS = {
   // Consecutive unreachable calls before Populace declares the target down and
   // stops, instead of retrying every call for the rest of the run. 0 disables.
   giveUpAfter: 12,
+  // Gap between sign-ups. Auth endpoints are throttled far harder than the rest
+  // of an API — Supabase's default is 30 sign-ups per five minutes per address,
+  // and 400ms is 2.5 per second. That default is right for real users, who each
+  // arrive from their own address, and impossible for a simulation, where every
+  // request shares one. Raise this to fit a target you do not control; a hosted
+  // Supabase project needs about 10_000.
+  signupStaggerMs: 400,
+  // When a sign-up is refused *for being too fast*, wait and try that person
+  // again rather than recording them as a failure. A rate limit says nothing
+  // about the application under test, so counting it as a finding is a lie.
+  // Backoff is this value times the attempt number. 0 disables retrying.
+  signupRateLimitBackoffMs: 5_000,
+  signupRateLimitRetries: 2,
   population: { agents: 6, cities: ["manila", "mumbai"], tickSeconds: 5, minutes: 10 },
   // Comfortably inside a 1-hour token, which is the common default.
   session: { refreshEveryMinutes: 30 },
@@ -43,8 +56,8 @@ const DEFAULTS = {
 };
 
 export async function loadConfig({ configPath, cwd = process.cwd(), overrides = {} } = {}) {
-  // reportPath is not a population setting; keep it out of that spread.
-  const { reportPath: _reportPath, ...populationOverrides } = overrides;
+  // Neither of these is a population setting; keep them out of that spread.
+  const { reportPath: _reportPath, signupStaggerMs: _stagger, ...populationOverrides } = overrides;
   const file = path.resolve(cwd, configPath || "populace.config.mjs");
 
   if (!fs.existsSync(file)) {
@@ -63,6 +76,9 @@ export async function loadConfig({ configPath, cwd = process.cwd(), overrides =
   const config = {
     ...DEFAULTS,
     ...loaded,
+    // --stagger wins over the config file, so a run can be paced to fit a target
+    // whose rate limit is not yours to change.
+    ...(overrides.signupStaggerMs ? { signupStaggerMs: overrides.signupStaggerMs } : {}),
     population: {
       ...DEFAULTS.population,
       ...(loaded.population || {}),

package/src/engine/world.mjs

@@ -27,6 +27,13 @@ export class World {
     const options = {
       ...(config.identity || {}),
       refreshEveryMs: (config.session?.refreshEveryMinutes ?? 30) * 60_000,
+      // Sign-up pacing, so populate() does not have to be told twice. These were
+      // hardcoded in populate() until 2026-08-24, which meant a target throttling
+      // harder than 2.5 sign-ups a second could not be tested at all without
+      // editing this package's source.
+      signupStaggerMs: config.signupStaggerMs,
+      signupRateLimitBackoffMs: config.signupRateLimitBackoffMs,
+      signupRateLimitRetries: config.signupRateLimitRetries,
     };
     return new World({ adapter, personas, options, on });
   }
@@ -36,16 +43,37 @@ export class World {
    * 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 } = {}) {
+  async populate({
+    staggerMs = this.options?.signupStaggerMs ?? 400,
+    rateLimitBackoffMs = this.options?.signupRateLimitBackoffMs ?? 5_000,
+    rateLimitRetries = this.options?.signupRateLimitRetries ?? 2,
+  } = {}) {
     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);
+      let attempt = 0;
+      for (;;) {
+        const agent = new Agent(persona, this.adapter, i, this.options);
+        try {
+          await agent.ensureAccount();
+          this.agents.push(agent);
+          this.on.joined?.(agent);
+          break;
+        } catch (error) {
+          const message = String(error.message || error);
+          // Being refused for going too fast is the target pacing us, not a
+          // defect in it. Waiting is the honest response: at a hosted default of
+          // 30 sign-ups per five minutes a 250-person run otherwise loses 215
+          // people to an error that says nothing about the app under test.
+          const throttled = /rate limit|429|too many requests/i.test(message);
+          if (throttled && rateLimitBackoffMs > 0 && attempt < rateLimitRetries) {
+            attempt += 1;
+            this.on.joinThrottled?.(persona, attempt);
+            await sleep(rateLimitBackoffMs * attempt);
+            continue;
+          }
+          this.signupFailures.push({ persona: persona.name, error: message, throttled });
+          this.on.joinFailed?.(persona, error);
+          break;
+        }
       }
       if (staggerMs) await sleep(staggerMs);
     }

package/src/progress.mjs

@@ -0,0 +1,153 @@
+// A machine-readable view of a run, for anything watching it happen.
+//
+// The engine already knows everything anyone could want each tick - every
+// person's city, platform, distance, activity and position, and the latency of
+// every method. In a terminal it draws all of that as a table. Piped anywhere
+// else it deliberately drops to a heartbeat every fifth of the run, because a
+// full table written into a CI log would bury the report under thousands of
+// screens of scrollback.
+//
+// That is right for CI and wrong for a window. Populace Studio spawns the CLI
+// with its output piped, so it received the CI version: at a one-second tick
+// over fifteen minutes, one update every three minutes. The application looked
+// frozen while a quarter of a million calls went through it.
+//
+// So the data was never missing - only the transport. This is the transport.
+//
+//   populace run --progress json
+//
+// Each line is `@@populace@@` followed by one JSON object. The prefix means a
+// reader can pick these out of ordinary output without ambiguity, and nothing
+// is emitted at all unless asked, so a human's terminal is unchanged.
+//
+// Percentiles are not computed every tick. summarise() sorts every recorded
+// duration, and at a quarter of a million calls that is real work to do once a
+// second for numbers nobody can read that fast.
+
+export const PROGRESS_PREFIX = "@@populace@@";
+
+/**
+ * Cheap per-method counters, straight off the metrics map - no sorting.
+ *
+ * The most common error message travels with them when there is one. A count
+ * of failures tells a watcher that something is wrong; only the message tells
+ * them what, and waiting for the report to find out is a long time to sit in
+ * front of a run that is already broken.
+ */
+function counters(metrics) {
+  return [...metrics.methods.values()].map((e) => {
+    const row = {
+      method: e.method,
+      calls: e.calls,
+      apiFailures: e.apiFailures,
+      transportFailures: e.transportFailures,
+      retries: e.retries,
+    };
+    if (e.failures && e.errors?.size) {
+      let top = null;
+      for (const [message, count] of e.errors) if (!top || count > top.count) top = { message, count };
+      if (top) row.error = { message: top.message.slice(0, 300), count: top.count };
+    }
+    return row;
+  });
+}
+
+/** p50 and p95 per method. Costs a sort per method, so it runs rarely. */
+function latencies(metrics) {
+  const out = {};
+  for (const e of metrics.methods.values()) {
+    if (!e.durations.length) continue;
+    const sorted = [...e.durations].sort((a, b) => a - b);
+    const at = (p) => sorted[Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length))];
+    out[e.method] = { p50: Math.round(at(50)), p95: Math.round(at(95)) };
+  }
+  return out;
+}
+
+/**
+ * @param {object} options
+ * @param {boolean} options.enabled   emit anything at all
+ * @param {number}  options.everyLatency  ticks between percentile refreshes
+ * @param {(line: string) => void} options.write
+ */
+export function createProgress({ enabled, everyLatency = 5, write = (l) => process.stdout.write(l) } = {}) {
+  if (!enabled) return { start() {}, joining() {}, tick() {}, done() {} };
+
+  const emit = (event) => {
+    try {
+      write(`${PROGRESS_PREFIX}${JSON.stringify(event)}\n`);
+    } catch {
+      // A watcher that has gone away is not a reason to fail a run.
+    }
+  };
+
+  const startedAt = Date.now();
+
+  return {
+    start(config) {
+      emit({
+        type: "start",
+        app: config.app || "populace",
+        environment: config.environment,
+        agents: config.population.agents,
+        cities: config.population.cities,
+        minutes: config.population.minutes,
+        tickSeconds: config.population.tickSeconds,
+        engagement: config.population.engagement ?? 1,
+      });
+    },
+
+    /**
+     * One event per person as they sign in, before any tick exists.
+     *
+     * Signing 250 people in takes minutes, and until this existed a watcher had
+     * nothing to show for it: every counter read zero, the progress bar stayed
+     * empty and the clock counted down as though the run were already under way.
+     * A window that looks identical to a hung one is a window people kill.
+     */
+    joining({ done, total, name, city, ok }) {
+      emit({ type: "joining", done, total, name, city, ok });
+    },
+
+    tick(tickNo, totalTicks, world, metrics) {
+      const t = world.totals();
+      emit({
+        type: "tick",
+        tick: tickNo,
+        totalTicks,
+        elapsedMs: Date.now() - startedAt,
+        totals: {
+          km: Number(t.km.toFixed(2)),
+          posts: t.posts || 0,
+          likes: t.likes || 0,
+          comments: t.comments || 0,
+          messages: t.messages || 0,
+          groupJoins: t.groupJoins || 0,
+          errors: t.errors || 0,
+        },
+        // Short keys: this is written once a second with a row per person, and
+        // the field names would otherwise be most of the bytes.
+        people: world.agents.map((a) => ({
+          n: a.persona.name,
+          c: a.persona.city.name,
+          y: a.persona.city.country,
+          p: a.persona.platform,
+          k: Number(a.distanceKm.toFixed(1)),
+          o: a.stats.posts || 0,
+          l: a.stats.likes || 0,
+          m: a.stats.messages || 0,
+          e: a.stats.errors || 0,
+          b: Boolean(a.onBreak),
+          la: Number(a.position.lat.toFixed(3)),
+          lo: Number(a.position.lng.toFixed(3)),
+        })),
+        methods: counters(metrics),
+        latency: tickNo % everyLatency === 0 || tickNo === totalTicks ? latencies(metrics) : undefined,
+      });
+    },
+
+    done(report) {
+      emit({ type: "done", verdict: report?.verdict?.status || "unknown" });
+    },
+  };
+}

package/src/selftest.mjs

@@ -1610,6 +1610,78 @@ check("POPULACE_NO_UPDATE_CHECK switches it off", () => {
 // would report "all passed" while an async assertion was still in flight — a
 // test suite lying about its own result, in a product whose entire argument is
 // that a report must never claim more than it has earned.
+// --- sign-up pacing and throttling -----------------------------------------
+// A rate limit is the target pacing us; a real error is a finding. Waiting out
+// the first is honest and waiting out the second would hide a defect, so the two
+// must never be treated alike. Added 2026-08-24 after a 250-person run lost 215
+// people to a limit that said nothing about the app under test.
+{
+  const persona = () => ({
+    name: "Test Person",
+    city: { name: "Manila", country: "PH", lat: 14.6, lng: 121 },
+    platform: "grab", rhythm: {}, engagement: 1,
+  });
+  const stub = (fail) => ({
+    createUser: fail,
+    async setProfile() {}, async refreshSession() {}, async reportLocation() {},
+    async post() {}, async recentPostsByOthers() { return []; }, async like() {},
+    async comment() {}, async openConversation() { return { id: "c" }; },
+    async sendMessage() {}, async listGroups() { return []; }, async joinGroup() {},
+    async deleteUser() {},
+  });
+  const throttling = (times) => {
+    let n = 0;
+    return stub(async () => {
+      if (n++ < times) throw new Error("Request rate limit reached");
+      return { id: "u" + n, token: "t" };
+    });
+  };
+  const world = (adapter, options, on = {}) =>
+    new World({ adapter, personas: [persona()], options, on });
+  const pacing = { signupRateLimitBackoffMs: 10, signupRateLimitRetries: 2, signupStaggerMs: 0 };
+
+  const recovered = world(throttling(2), pacing);
+  const attempts = [];
+  recovered.on.joinThrottled = (_p, a) => attempts.push(a);
+  await recovered.populate();
+  check("a sign-up refused for being too fast is retried, not counted as a failure", () => {
+    assert.equal(recovered.agents.length, 1, "the person should end up signed in");
+    assert.equal(recovered.signupFailures.length, 0, "a rate limit is not a finding");
+    assert.deepEqual(attempts, [1, 2], "each wait should be announced, not silent");
+  });
+
+  const exhausted = world(throttling(99), pacing);
+  await exhausted.populate();
+  check("a rate limit that never lets up is recorded with its cause intact", () => {
+    assert.equal(exhausted.agents.length, 0);
+    assert.equal(exhausted.signupFailures[0].throttled, true,
+      "the report must be able to tell throttling from a broken API");
+  });
+
+  let realErrorCalls = 0;
+  const genuine = world(stub(async () => {
+    realErrorCalls += 1;
+    throw new Error("duplicate key violates unique constraint");
+  }), pacing);
+  await genuine.populate();
+  check("a genuine sign-up error is never retried or waited out", () => {
+    assert.equal(realErrorCalls, 1, "retrying a finding would hide it");
+    assert.equal(genuine.signupFailures[0].throttled, false);
+  });
+
+  const paced = new World({
+    adapter: throttling(0), personas: [persona(), persona(), persona()],
+    options: { signupStaggerMs: 120 }, on: {},
+  });
+  const startedAt = Date.now();
+  await paced.populate();
+  const elapsed = Date.now() - startedAt;
+  check("signupStaggerMs actually paces sign-ups", () => {
+    assert.ok(elapsed >= 240,
+      `three people at 120ms apart should take at least 240ms, took ${elapsed}ms`);
+  });
+}
+
 await Promise.all(pending);
 
 console.log(