@gigzen/populace 0.1.0

package/README.md

@@ -0,0 +1,258 @@
+# Populace
+
+**A simulated population that uses your app through its real API — so you can
+test what needs more than one person.**
+
+**Site:** https://shakhtar-sankur.github.io/populace/  · 
+**Test report:** [the full engineering record](https://shakhtar-sankur.github.io/gigzen/test-report.html)
+ ·  A [Gigzen](https://shakhtar-sankur.github.io/gigzen/) product
+
+Some bugs only exist when two people are using your app at the same time.
+Presence, live sync, read receipts, notification fan-out, "does deleting this
+remove it for everyone", and every permission rule you wrote — none of them can
+be tested by one developer with one account, however carefully they tap through
+every screen.
+
+Populace gives you a few dozen believable people who sign up, move around a real
+city, post, like, comment, message each other and join groups — as **real
+authenticated users**, through **your own API**, with **your own permission rules
+applying**. Then it hands you a report on what broke.
+
+---
+
+## It has done this to a real, finished app
+
+![Populace report for Buzz Buzz, 9 August 2026 — no failures across 400 API calls](docs/buzzbuzz-run-2026-08-09.svg)
+
+That is the *second* run. The first one is the interesting one.
+
+### What happened, in plain English
+
+On **9 August 2026** we pointed Populace at **Buzz 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.
+
+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
+route through real streets, and behaved like a person — posting about traffic,
+reading the feed, liking and commenting on what other drivers posted, opening
+conversations, sending messages, joining a group. Nobody told Populace where the
+bugs were. Nobody told it what to look for. It just used the app.
+
+**Three and a half minutes later it had found five bugs.** The app that had
+passed a full manual test could not create a working account.
+
+### The five, one at a time
+
+**1. Signing up created no profile — every new user was broken.**
+A privacy fix earlier that day had restricted write access on the `profiles`
+table to a named list of columns, so that phone numbers could never be read by
+other users. The signup code used an *upsert*. In Postgres, `INSERT … ON CONFLICT
+DO UPDATE` needs `SELECT` permission on every column it touches — and one of
+those columns was, deliberately, unreadable. So the write was refused. Silently.
+
+Every account created after that point existed in the auth system with no
+profile row behind it. Then every post, every comment and every group join died
+on a foreign key pointing back at the row that was never written.
+
+*Why one person never sees this:* their own account already exists. You only hit
+it on a **fresh signup**, and you only notice the damage when that new user tries
+to do something. Populace creates six brand-new accounts every run, which is why
+it hit the bug in the first fifteen seconds.
+
+**2. Likes bounced back, at random.**
+The `post_likes` table has an insert policy and a delete policy, and no `UPDATE`
+policy — by design. The app used an upsert here too, so the second time anyone
+liked a post, it became `ON CONFLICT DO UPDATE` and row-level security refused
+it. The feed refreshes every 2.5 seconds, so a slightly stale "already liked"
+state was completely ordinary, and one tap in four failed.
+
+*Why one person never sees this:* with one account and one slow thumb, you rarely
+double-like anything. Six people liking each other's posts on a 2.5-second poll
+do it constantly.
+
+**3. Editing your profile failed the same way.** Same upsert, same unreadable
+column, same silent refusal.
+
+**4 and 5. Two faults in Populace's own reference adapter.**
+One passed an RPC argument under the wrong name. The other is the one worth
+dwelling on: it **ignored the error returned by a write**. Because that failure
+was swallowed at signup, the report blamed a *later* method for it — so the run
+said "post failed 14 times" when the truth was "the profile row was never
+created."
+
+An unchecked error is the precise fault this tool exists to catch, and it was
+sitting in our own code. Making that one line throw changed the report from three
+confusing symptoms into one sentence naming the real cause: *profile row not
+created: permission denied for table profiles.*
+
+### The rule worth taking away
+
+> **You cannot upsert a column you cannot select.**
+
+Three of the five bugs were the same mistake wearing different clothes. It is
+invisible in code review, invisible in a single-user walkthrough, and obvious
+within seconds to six users signing up at once.
+
+### After the fixes
+
+All five were fixed and the run repeated: the report at the top of this page.
+**No failures across 400 API calls.** Six accounts created, six accounts deleted,
+nothing left behind.
+
+**What this does not claim.** Six users for three minutes is a **correctness run,
+not a load test**, and it ran against that project while it was still empty. The
+latencies above are what six concurrent users saw and nothing more. Populace has
+been pointed at exactly one real backend so far, and that backend was ours — the
+next one should be someone else's.
+
+---
+
+## Try it in ten seconds
+
+No backend, no signup, nothing of yours touched — the demo adapter fakes a small
+app in memory.
+
+```bash
+populace demo
+```
+
+The demo app has a real bug in it: a row-level-security policy that rejects
+likes. Watch the report find it, name the policy, and exit non-zero. That exit
+code is the whole point — the run fails your build rather than telling you it
+went fine.
+
+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.
+
+---
+
+## Point it at your own app
+
+```bash
+populace init      # scaffolds populace.config.mjs + adapters/my-app.mjs
+populace doctor    # checks config, reachability and coverage WITHOUT running
+populace run
+populace clean     # removes every account a run created
+```
+
+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
+example in ~150 lines.
+
+`populace doctor` on a fresh scaffold says `2/13` and refuses to run — a method
+that exists but does nothing is not coverage.
+
+### Check the adapter before you run
+
+`doctor` tells you which methods exist. `smoke` tells you whether they work:
+
+```bash
+populace smoke
+```
+
+It creates one user, calls every method you implemented once, checks what came
+back against what the contract promises, and deletes the user again. Seconds,
+not minutes — and it reports on *your adapter*, not your app, which is the
+question you actually have while writing one.
+
+A full run against a subtly wrong adapter spends five minutes producing a report
+about nothing. This is the step that stops that.
+
+**If your API uses expiring tokens, implement `refreshSession`.** Without it,
+any run longer than your token lifetime collapses at once and the report blames
+your API for what were really expired tokens — and the run cannot even delete
+its own accounts, stranding simulated users in your environment. See it happen:
+`node examples/token-expiry/expiry-demo.mjs`
+
+## The safety guard
+
+Populace creates real accounts and writes real rows. Pointed at production it
+would put invented people in front of paying customers. So it refuses to start
+in three independent ways:
+
+1. **`environment` must declare a non-production value.** Opt in, never assumed.
+2. **`neverRunAgainst` is checked against every string in your target** — however
+   deeply nested. One match and the run is refused; no flag overrides it.
+3. **An empty denylist warns loudly**, because "I forgot to fill that in" is the
+   likeliest version of this mistake.
+
+Refusals exit non-zero, so CI catches them too.
+
+The same principle runs through the contract: **go through the front door**. Use
+the API your app actually uses — not admin keys, not service-role credentials,
+not direct database writes. A simulation that bypasses your permission rules
+proves nothing about whether they work, and permission bugs are exactly what a
+multi-user simulation is best at finding.
+
+---
+
+## What you get
+
+- **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
+- **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
+- **`populace-report.html`** beside it — one self-contained file, no scripts and nothing
+  fetched from the network, for the people who were not watching the terminal
+
+### A run always finishes
+
+Every call into your adapter has a deadline (`timeoutMs`, 20s by default). Past
+it, Populace stops waiting, records a timeout against that endpoint, and the
+other agents carry on.
+
+This matters more than it sounds. We found it the hard way: a real run against a
+flaky link froze two minutes in and sat there silently until something outside
+killed it nine minutes later. No report, no error — just a progress line that
+stopped moving. The API under test was fine; one dead socket had taken the whole
+run with it.
+
+A hang is the worst outcome a testing tool can produce, because it does not look
+like a failure. It looks like nothing, and the natural conclusion is that the
+tool is broken. So now a slow or unresponsive endpoint becomes **a line in the
+report**, which is a finding you can act on — and the run still ends with a
+verdict. Set `timeoutMs: 0` if your adapter does long work on purpose.
+
+---
+
+## What it will not tell you
+
+**Whether people want your product.** These people are generated from patterns.
+They will never surprise you the way a real customer does, they cannot tell you
+your onboarding is confusing or your pricing is wrong, and they are least
+accurate for exactly the users least represented online.
+
+Use Populace to prove your app **works**. Use real people to decide what to
+**build**. A report full of green ticks means your API held up — not that anyone
+wants what you made.
+
+---
+
+## Design notes
+
+- **The engine never learns your app.** `src/engine/` knows how to be a person;
+  everything app-specific lives in an adapter. If app logic ever leaks into the
+  engine, Populace has collapsed back into a test script.
+- **Zero runtime dependencies.** Adapters bring their own.
+- **Deterministic identities.** Agent *n* always gets the same phone number, so
+  re-runs reuse accounts instead of piling up new ones — and `populace clean`
+  can find them after a run that crashed halfway.
+- **Cheap by default.** Scripted agents cost nothing, so hundreds can run at
+  once. If you later want genuinely emergent conversation, put an LLM behind a
+  tier — a handful of expensive agents among many cheap ones, the way games vary
+  NPC detail.
+- **Concurrent, not sequential.** Everyone acts at once, because sequential
+  agents never surface a race condition.
+
+```bash
+npm test   # runs the whole product against an in-memory app — no backend needed
+```

package/adapters/buzzbuzz.mjs

@@ -0,0 +1,247 @@
+// Adapter: Buzz Buzz — a gig-driver tracking app on Supabase.
+//
+// Populace's first customer, and the reference implementation. Read this
+// alongside contract.md to see what a complete adapter looks like: it is ~140
+// lines, and it is the ONLY file in the system that knows these table names.
+//
+// Every call goes through the normal client with the publishable key, as a real
+// authenticated user, so row-level security and triggers apply exactly as they
+// do for a real driver. No service-role key, no direct database access.
+
+import { createClient } from "@supabase/supabase-js";
+
+const PASSWORD = "SimDriver!2026";
+// Matches the app's own phone→email scheme (SupabaseService.phoneToEmail).
+const phoneToEmail = (phone) => `${String(phone).replace(/\D/g, "") || "driver"}@masaya.local`;
+
+export function createAdapter(target) {
+  const url = target.url?.replace(/\/$/, "");
+  const key = target.key;
+
+  if (!url || !key) {
+    throw new Error(
+      "buzzbuzz adapter needs target.url and target.key.\n" +
+        "  Set BUZZBUZZ_TEST_URL and BUZZBUZZ_TEST_KEY in your environment.",
+    );
+  }
+
+  return {
+    name: "buzzbuzz",
+
+    // 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
+    // would cheerfully report failures that were really a typo.
+    async healthCheck() {
+      const res = await fetch(`${url}/auth/v1/health`, {
+        headers: { apikey: key },
+        signal: AbortSignal.timeout(12000),
+      });
+      if (res.status >= 500) throw new Error(`server returned ${res.status}`);
+    },
+
+    /**
+     * Cleanup capability: does this identity exist, without creating it?
+     *
+     * `clean` used to reach accounts through createUser, which signs UP when
+     * the identity is absent — so tidying an already-clean project wrote a row
+     * to the customer's auth table for every agent, purely to prove the table
+     * was empty. This is the read-only path.
+     *
+     * Returns the user when present, null when definitively absent. A transport
+     * failure throws, because "I could not look" must never be recorded as
+     * "there was nothing there".
+     */
+    async signIn({ phone }) {
+      const client = createClient(url, key, {
+        auth: { persistSession: false, autoRefreshToken: false },
+      });
+      const { data, error } = await client.auth.signInWithPassword({
+        email: phoneToEmail(phone),
+        password: PASSWORD,
+      });
+      if (!error) return data.user ? { ...data.user, client } : null;
+
+      // Supabase answers a non-existent account and a wrong password with the
+      // same message. Both mean "no simulated account we can act on"; anything
+      // else is a real fault and must surface.
+      if (/invalid login credentials|email not confirmed/i.test(error.message)) return null;
+      throw new Error(error.message);
+    },
+
+    async createUser({ name, phone, persona }) {
+      const client = createClient(url, key, {
+        auth: { persistSession: false, autoRefreshToken: false },
+      });
+      const email = phoneToEmail(phone);
+
+      let { data, error } = await client.auth.signUp({
+        email,
+        password: PASSWORD,
+        options: { data: { full_name: name, phone } },
+      });
+      if (error) {
+        // Already exists from an earlier run — reuse it rather than piling up.
+        const signUpError = error;
+        ({ data, error } = await client.auth.signInWithPassword({ email, password: PASSWORD }));
+        if (error) {
+          // Report BOTH, because the fallback's error is usually the misleading
+          // one. This threw a bare "Invalid login credentials" for two nights of
+          // debugging: the real cause was signUp being refused — a rate limit
+          // after many runs in one hour — and the sign-in then failing simply
+          // because the account had never been created. The message named the
+          // symptom and hid the cause, which sent the diagnosis the wrong way
+          // twice. Losing the first error to report the second is exactly the
+          // fault this tool exists to catch, in our own reference adapter.
+          throw new Error(`${error.message} (signup first failed: ${signUpError.message})`);
+        }
+      }
+      if (!data.user) throw new Error("no user returned");
+
+      // Check this. It used to be fire-and-forget, so when the profile row
+      // failed to insert the run carried on and every later post and group-join
+      // died on a foreign key instead — the report blamed `post` for a fault
+      // that happened during signup. An unchecked error is the exact thing this
+      // tool exists to catch, and it was in our own reference adapter.
+      // INSERT, not upsert — mirroring the app. An upsert touches `phone`, and
+      // ON CONFLICT DO UPDATE needs SELECT on the columns it touches, which
+      // privacy_lockdown deliberately removes for that column. A duplicate just
+      // means this persona signed up on an earlier run.
+      const { error: profileError } = await client.from("profiles").insert({
+        id: data.user.id,
+        full_name: name,
+        phone,
+        updated_at: new Date().toISOString(),
+      });
+      if (profileError && profileError.code !== "23505") {
+        throw new Error(`profile row not created: ${profileError.message}`);
+      }
+
+      return { id: data.user.id, client, persona };
+    },
+
+    // Supabase access tokens are short-lived (1 hour by default). We refresh
+    // EXPLICITLY rather than letting supabase-js do it in the background:
+    // autoRefreshToken is a timer we cannot see, whereas an explicit call is
+    // timed and counted like everything else, so a refresh that starts failing
+    // shows up in the report instead of quietly poisoning the whole run.
+    async refreshSession(user) {
+      const { data, error } = await user.client.auth.refreshSession();
+      if (error) throw new Error(error.message);
+      if (!data?.session) throw new Error("refresh returned no session");
+    },
+
+    async setProfile(user, persona) {
+      await user.client.from("driver_settings").upsert({
+        user_id: user.id,
+        active_app: persona.platform,
+        base_rate: persona.rate,
+        vehicle_type: persona.vehicle ?? "car",
+        share_stats: true,
+        updated_at: new Date().toISOString(),
+      });
+    },
+
+    async reportLocation(user, { lat, lng, distanceKm, earnings, platform }) {
+      await user.client.from("worker_locations").upsert({
+        user_id: user.id,
+        lat,
+        lng,
+        accuracy: 5 + Math.random() * 8,
+        active_app: platform,
+        today_distance_km: Number(distanceKm.toFixed(2)),
+        today_earnings: Number(earnings.toFixed(2)),
+        updated_at: new Date().toISOString(),
+      });
+      await user.client.from("route_points").insert({
+        user_id: user.id,
+        lat,
+        lng,
+        accuracy: 8,
+        active_app: platform,
+        recorded_at: new Date().toISOString(),
+      });
+    },
+
+    async post(user, text) {
+      const { data, error } = await user.client
+        .from("feed_posts")
+        .insert({ user_id: user.id, body: text })
+        .select("id")
+        .single();
+      if (error) throw error;
+      return data?.id;
+    },
+
+    async recentPostsByOthers(user, limit = 10) {
+      const { data } = await user.client
+        .from("feed_posts")
+        .select("id,user_id")
+        .neq("user_id", user.id)
+        .order("created_at", { ascending: false })
+        .limit(limit);
+      return (data ?? []).map((p) => ({ id: p.id, userId: p.user_id }));
+    },
+
+    async like(user, postId) {
+      // Mirrors the app: insert, and treat a duplicate as success. post_likes
+      // has no UPDATE policy, so an upsert on a repeat like is refused by RLS.
+      const { error } = await user.client
+        .from("post_likes")
+        .insert({ post_id: postId, user_id: user.id });
+      if (error && error.code !== "23505") throw error;
+    },
+
+    async comment(user, postId, text) {
+      const { error } = await user.client
+        .from("post_comments")
+        .insert({ post_id: postId, user_id: user.id, body: text });
+      if (error) throw error;
+    },
+
+    async openConversation(user, otherUserId) {
+      // The function signature is start_direct_thread(p_other uuid). PostgREST
+      // resolves RPCs by argument NAME, so passing other_user_id looked like a
+      // missing function rather than a wrong argument.
+      const { data, error } = await user.client.rpc("start_direct_thread", {
+        p_other: otherUserId,
+      });
+      if (error) throw error;
+      return data;
+    },
+
+    async sendMessage(user, conversationId, text) {
+      // chat_messages.id is a text primary key the client supplies — the app
+      // generates one per message, and the adapter was sending none at all.
+      const { error } = await user.client.from("chat_messages").insert({
+        id: `msg_${crypto.randomUUID()}`,
+        thread_id: conversationId,
+        sender_id: user.id,
+        body: text,
+        status: "sent",
+      });
+      if (error) throw error;
+    },
+
+    async listGroups(user) {
+      const { data } = await user.client.from("groups").select("id").limit(10);
+      return data ?? [];
+    },
+
+    async joinGroup(user, groupId) {
+      // Mirrors the app: ignoreDuplicates so this is ON CONFLICT DO NOTHING.
+      // A plain upsert takes the UPDATE path on a repeat join, and there is no
+      // UPDATE policy on group_members — which is the failure this adapter
+      // surfaced on a 644-call run.
+      const { error } = await user.client
+        .from("group_members")
+        .upsert({ group_id: groupId, user_id: user.id }, { ignoreDuplicates: true });
+      if (error) throw error;
+    },
+
+    async deleteUser(user) {
+      // Deliberately the app's OWN delete path, so the simulation exercises it.
+      const { error } = await user.client.rpc("delete_own_account");
+      if (error) throw error;
+    },
+  };
+}

package/adapters/contract.md

@@ -0,0 +1,164 @@
+# Writing an adapter
+
+The engine knows how to be a *person*: where they go, how chatty they are, when
+they take a break, who they talk to. It knows nothing about your app.
+
+An **adapter** is the translation layer. For each thing a simulated person can
+do, it answers one question: *"how does that happen in my product?"*
+
+```js
+export function createAdapter(target, config) {
+  return { name: "your-app", /* methods below */ };
+}
+```
+
+`target` is whatever you put in `target` in `populace.config.mjs`.
+
+---
+
+## The contract
+
+Thirteen methods. Two are required; the rest are optional, and anything you
+leave out is skipped rather than failing. A read-only app can implement three
+and get a useful run.
+
+| Method | | What it exercises in your app |
+|---|---|---|
+| `createUser({name, phone, persona, index})` | **required** | sign-up, sign-in, first-contact |
+| `setProfile(user, persona)` | | the settings a new user configures |
+| `refreshSession(user)` | **read this** | token refresh — see below |
+| `reportLocation(user, {lat, lng, distanceKm, earnings, platform})` | | high-frequency writes — the heaviest sustained load most apps take |
+| `post(user, text)` → `postId` | | content creation |
+| `recentPostsByOthers(user, limit)` → `[{id, userId}]` | | feed reads under concurrent writes, and whether permissions leak |
+| `like(user, postId)` | | high-contention writes on shared rows |
+| `comment(user, postId, text)` | | nested content and its notifications |
+| `openConversation(user, otherUserId)` → `conversationId` | | conversation creation between accounts that have never met |
+| `sendMessage(user, conversationId, text)` | | delivery, ordering, receipts, realtime fan-out |
+| `listGroups(user)` → `[{id}]` | | shared-resource reads |
+| `joinGroup(user, groupId)` | | membership writes and counter accuracy |
+| `deleteUser(user)` | **required** | account deletion and cascade |
+| `healthCheck()` | optional | lets `populace doctor` verify the target before a run |
+
+`createUser` returns a **handle** — put the session, token or client on it. You
+get that same object back as `user` on every later call.
+
+---
+
+## Two rules
+
+**1. Never point an adapter at production.**
+
+Populace refuses in three independent ways — `environment` must declare a
+non-production value, `neverRunAgainst` is checked against every string in your
+target, and an empty denylist warns loudly. Your adapter should fail loudly too.
+Simulated people appearing to real users is deception, not testing.
+
+**2. Go through the front door.**
+
+Use the same API your app uses. Not admin keys, not service-role credentials,
+not direct database writes. A simulation that bypasses your permission rules
+proves nothing about whether they work — and permission bugs are exactly what a
+multi-user simulation is best at finding.
+
+The same applies to `deleteUser`: prefer your app's own delete-account path over
+a hard delete. It is the route almost nobody tests and the one regulators ask
+about.
+
+---
+
+## Sessions expire — implement `refreshSession`
+
+If your API uses short-lived access tokens (most do), implement this. It is
+optional only because some APIs don't need it.
+
+Populace calls it every 30 minutes by default — tune with
+`session.refreshEveryMinutes`. If it throws, the agent signs in again from
+scratch rather than going quietly dead.
+
+Skipping it on an app with a 1-hour token means any run longer than an hour
+collapses at once, and the report blames **your API** for failures that were
+really expired tokens. Worse: `deleteUser` needs a live session too, so the run
+cannot clean up after itself and leaves simulated accounts stranded in your
+environment.
+
+Measured on a pretend app with a 3-second token, same population, same duration:
+
+| | no `refreshSession` | with it |
+|---|---|---|
+| API calls failed | 45 of 65 (**69%**) | 0 of 90 (**0%**) |
+| location writes accepted | 9 | 48 |
+| accounts left behind | **4** | 0 |
+
+Reproduce it yourself: `node examples/token-expiry/expiry-demo.mjs`
+
+---
+
+## Cleanup without writing to your database — `signIn`
+
+`signIn` is **not** a fourteenth contract method. It plays no part in a run, and
+it is not counted in your coverage score. It exists for one job: letting
+`populace clean` ask *"does this identity exist?"* without creating it.
+
+Without it, cleanup reaches an account through `createUser` — which signs **up**
+when the identity is absent. So cleaning an already-clean environment creates
+every simulated identity and immediately deletes it again, writing to your auth
+table purely to prove the table was empty. It also makes the per-account result
+meaningless: you cannot tell "found an abandoned account and removed it" from
+"there was nothing there".
+
+```js
+/**
+ *  user  — the account exists (attach whatever deleteUser will need)
+ *  null  — it definitively does not exist
+ *  throw — you could not find out
+ */
+async signIn({ name, phone, persona, index }) {
+  const { data, error } = await client.auth.signInWithPassword({
+    email: emailFor(phone),
+    password: PASSWORD,
+  });
+  if (!error) return data.user ? { ...data.user, client } : null;
+  if (/invalid login credentials/i.test(error.message)) return null;
+  throw new Error(error.message);   // never swallow — see below
+}
+```
+
+**Throw rather than return null when you could not look.** A network failure is
+not evidence of absence. `clean` separates the two and exits non-zero when any
+identity could not be verified, so nobody is handed a false all-clear over their
+own database.
+
+Implement it and `populace doctor` reports `Cleanup  read-only`. Leave it out and
+Populace still cleans up — it just says plainly that it is creating rows to do
+so, and that it cannot tell you what was already there.
+
+---
+
+## Re-runs
+
+Identities are deterministic — agent *n* always gets the same phone number.
+`createUser` should therefore **sign in** if the account already exists rather
+than creating a second one. This is what lets `populace clean` find and remove
+accounts after a run that crashed halfway.
+
+---
+
+## What you get back
+
+A `populace-report.json` and a terminal summary:
+
+- every failure, grouped by shape rather than exact text, with counts
+- p50 / p95 / p99 / max latency per method under N concurrent users
+- which contract methods you did **not** implement, and what each would have tested
+- whether cleanup actually succeeded
+
+---
+
+## What it will not tell you
+
+Whether people *want* your product. Simulated users are generated from patterns;
+they will not surprise you the way a real customer does, and they are least
+accurate for exactly the users least represented online.
+
+Use Populace to prove your app **works**. Use real people to decide what to
+**build**.