@gigzen/populace 0.1.0

package/examples/buzzbuzz/populace-report.json

@@ -0,0 +1,280 @@
+{
+  "populace": {
+    "version": "0.1.0",
+    "generatedAt": "2026-08-15T11:32:20.651Z"
+  },
+  "run": {
+    "app": "Buzz Buzz",
+    "adapter": "../../adapters/buzzbuzz.mjs",
+    "environment": "test",
+    "startedAt": "2026-08-15T11:18:42.515Z",
+    "durationMs": 818136,
+    "population": {
+      "agents": 10,
+      "cities": [
+        "manila",
+        "mumbai"
+      ],
+      "tickSeconds": 5,
+      "minutes": 10
+    }
+  },
+  "verdict": {
+    "status": "clean",
+    "problems": [],
+    "apiFailures": 0,
+    "transportFailures": 0,
+    "failingMethods": []
+  },
+  "population": {
+    "requested": 10,
+    "signedIn": 10,
+    "signupFailures": []
+  },
+  "engineErrors": [],
+  "activity": {
+    "distanceKm": 36,
+    "posts": 139,
+    "likes": 296,
+    "comments": 123,
+    "messages": 110,
+    "groupJoins": 16
+  },
+  "api": {
+    "calls": 2030,
+    "failures": 0,
+    "apiFailures": 0,
+    "transportFailures": 0,
+    "retries": 0,
+    "failureRate": 0,
+    "apiFailureRate": 0,
+    "network": {
+      "retries": 0,
+      "transportFailures": 0,
+      "retryRate": 0,
+      "healthy": true,
+      "gaveUp": false,
+      "gaveUpAfter": null,
+      "outages": 0
+    },
+    "durationMs": 818132,
+    "methods": [
+      {
+        "method": "reportLocation",
+        "calls": 892,
+        "failures": 0,
+        "apiFailures": 0,
+        "transportFailures": 0,
+        "retries": 0,
+        "failureRate": 0,
+        "latencyMs": {
+          "p50": 711,
+          "p95": 1003,
+          "p99": 2371,
+          "max": 3178
+        },
+        "errors": []
+      },
+      {
+        "method": "recentPostsByOthers",
+        "calls": 298,
+        "failures": 0,
+        "apiFailures": 0,
+        "transportFailures": 0,
+        "retries": 0,
+        "failureRate": 0,
+        "latencyMs": {
+          "p50": 241,
+          "p95": 349,
+          "p99": 416,
+          "max": 622
+        },
+        "errors": []
+      },
+      {
+        "method": "like",
+        "calls": 296,
+        "failures": 0,
+        "apiFailures": 0,
+        "transportFailures": 0,
+        "retries": 0,
+        "failureRate": 0,
+        "latencyMs": {
+          "p50": 238,
+          "p95": 319,
+          "p99": 385,
+          "max": 760
+        },
+        "errors": []
+      },
+      {
+        "method": "post",
+        "calls": 139,
+        "failures": 0,
+        "apiFailures": 0,
+        "transportFailures": 0,
+        "retries": 0,
+        "failureRate": 0,
+        "latencyMs": {
+          "p50": 240,
+          "p95": 313,
+          "p99": 383,
+          "max": 614
+        },
+        "errors": []
+      },
+      {
+        "method": "comment",
+        "calls": 123,
+        "failures": 0,
+        "apiFailures": 0,
+        "transportFailures": 0,
+        "retries": 0,
+        "failureRate": 0,
+        "latencyMs": {
+          "p50": 243,
+          "p95": 326,
+          "p99": 387,
+          "max": 683
+        },
+        "errors": []
+      },
+      {
+        "method": "openConversation",
+        "calls": 110,
+        "failures": 0,
+        "apiFailures": 0,
+        "transportFailures": 0,
+        "retries": 0,
+        "failureRate": 0,
+        "latencyMs": {
+          "p50": 245,
+          "p95": 336,
+          "p99": 375,
+          "max": 626
+        },
+        "errors": []
+      },
+      {
+        "method": "sendMessage",
+        "calls": 110,
+        "failures": 0,
+        "apiFailures": 0,
+        "transportFailures": 0,
+        "retries": 0,
+        "failureRate": 0,
+        "latencyMs": {
+          "p50": 244,
+          "p95": 351,
+          "p99": 393,
+          "max": 780
+        },
+        "errors": []
+      },
+      {
+        "method": "listGroups",
+        "calls": 16,
+        "failures": 0,
+        "apiFailures": 0,
+        "transportFailures": 0,
+        "retries": 0,
+        "failureRate": 0,
+        "latencyMs": {
+          "p50": 250,
+          "p95": 312,
+          "p99": 312,
+          "max": 312
+        },
+        "errors": []
+      },
+      {
+        "method": "joinGroup",
+        "calls": 16,
+        "failures": 0,
+        "apiFailures": 0,
+        "transportFailures": 0,
+        "retries": 0,
+        "failureRate": 0,
+        "latencyMs": {
+          "p50": 235,
+          "p95": 311,
+          "p99": 311,
+          "max": 311
+        },
+        "errors": []
+      },
+      {
+        "method": "createUser",
+        "calls": 10,
+        "failures": 0,
+        "apiFailures": 0,
+        "transportFailures": 0,
+        "retries": 0,
+        "failureRate": 0,
+        "latencyMs": {
+          "p50": 601,
+          "p95": 834,
+          "p99": 834,
+          "max": 834
+        },
+        "errors": []
+      },
+      {
+        "method": "setProfile",
+        "calls": 10,
+        "failures": 0,
+        "apiFailures": 0,
+        "transportFailures": 0,
+        "retries": 0,
+        "failureRate": 0,
+        "latencyMs": {
+          "p50": 249,
+          "p95": 392,
+          "p99": 392,
+          "max": 392
+        },
+        "errors": []
+      },
+      {
+        "method": "deleteUser",
+        "calls": 10,
+        "failures": 0,
+        "apiFailures": 0,
+        "transportFailures": 0,
+        "retries": 0,
+        "failureRate": 0,
+        "latencyMs": {
+          "p50": 320,
+          "p95": 508,
+          "p99": 508,
+          "max": 508
+        },
+        "errors": []
+      }
+    ]
+  },
+  "coverage": {
+    "label": "13/13",
+    "implemented": [
+      "createUser",
+      "setProfile",
+      "refreshSession",
+      "reportLocation",
+      "post",
+      "recentPostsByOthers",
+      "like",
+      "comment",
+      "openConversation",
+      "sendMessage",
+      "listGroups",
+      "joinGroup",
+      "deleteUser"
+    ],
+    "notTested": []
+  },
+  "cleanup": {
+    "removed": 10,
+    "notDeleted": [],
+    "failed": []
+  }
+}

package/examples/buzzbuzz/populace.config.mjs

@@ -0,0 +1,51 @@
+// Populace's first customer: Buzz Buzz, a gig-driver tracking app.
+//
+// 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
+//
+// Run it — bash/zsh (macOS, Linux):
+//   BUZZBUZZ_TEST_URL=... BUZZBUZZ_TEST_KEY=... \
+//     node src/cli.mjs run --config examples/buzzbuzz/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
+//   realtime.sql · fix_chat_rls.sql · user_content_control.sql
+//   work_apps_global.sql · privacy_lockdown.sql
+// …and turn OFF Authentication → Providers → Email → "Confirm email",
+// otherwise nobody can sign in after signing up.
+
+export default {
+  app: "Buzz Buzz",
+  adapter: "../../adapters/buzzbuzz.mjs",
+  environment: "test",
+
+  target: {
+    url: process.env.BUZZBUZZ_TEST_URL,
+    key: process.env.BUZZBUZZ_TEST_KEY,
+  },
+
+  // Buzz Buzz's LIVE project. If BUZZBUZZ_TEST_URL is ever set to this by
+  // accident, Populace refuses to start. Real drivers must never see invented
+  // people on their map.
+  // Both of these are real. rqzuuvlougzhynckvqzd is the original project, which
+  // is still running; ypdaetbeexyepswyhbui became production on 2026-08-09.
+  // The clean run recorded against the latter happened while it was empty and
+  // had no real drivers on it — that window has closed, and it must not be
+  // simulated against again.
+  neverRunAgainst: [
+    "https://rqzuuvlougzhynckvqzd.supabase.co",
+    "https://ypdaetbeexyepswyhbui.supabase.co",
+  ],
+
+  population: {
+    agents: 8,
+    cities: ["manila", "mumbai"],
+    minutes: 10,
+    tickSeconds: 5,
+  },
+
+  identity: { phonePrefix: "0900" },
+  report: { path: "populace-report.json" },
+};

package/examples/buzzbuzz/run-test.ps1

@@ -0,0 +1,61 @@
+# Run the Buzz Buzz simulation from Windows PowerShell.
+#
+# Exists because the bash one-liner does not work here: PowerShell 5.1 has no
+# `&&` statement separator and no `VAR=value command` prefix, so pasting the
+# Unix form fails with "The token '&&' is not a valid statement separator".
+#
+#   .\run-test.ps1                    # 6 drivers, 5 minutes
+#   .\run-test.ps1 -Agents 4 -Minutes 3
+#   .\run-test.ps1 -Clean             # just remove any leftover accounts
+#
+# Run it from anywhere; it locates itself.
+
+param(
+  [int]$Agents  = 6,
+  [int]$Minutes = 5,
+  [switch]$Clean
+)
+
+$ErrorActionPreference = "Stop"
+Set-Location $PSScriptRoot
+
+# Deliberately no NODE_OPTIONS here. An earlier version set
+# --dns-result-order=ipv6first to work around connection failures on a NAT64
+# link. Measuring it afterwards showed 40/40 successful connections both with
+# and without the flag — the failures were the link recovering on its own, not
+# address-family ordering. The workaround was cargo cult, so it is gone.
+
+# The isolated test project. Never a production host — populace.config.mjs
+# lists the live ones in neverRunAgainst and refuses them before loading.
+$env:BUZZBUZZ_TEST_URL = "https://jqepegeifmnfofeyebrz.supabase.co"
+$env:BUZZBUZZ_TEST_KEY = "sb_publishable_ZkOhFsiQBrKMB5pc2Ub1Vw_V5oxsBE1"
+
+$cli = Join-Path $PSScriptRoot "..\..\src\cli.mjs"
+
+if ($Clean) {
+  node $cli clean
+  exit $LASTEXITCODE
+}
+
+Write-Host ""
+Write-Host "  Checking the target before running..." -ForegroundColor Cyan
+node $cli doctor
+if ($LASTEXITCODE -ne 0) {
+  Write-Host ""
+  Write-Host "  doctor says not ready — stopping here rather than burning a run." -ForegroundColor Yellow
+  exit 1
+}
+
+node $cli run --agents $Agents --minutes $Minutes
+$code = $LASTEXITCODE
+
+# A run exits non-zero when it FINDS something. That is the tool working, not
+# the tool failing, so say so rather than leaving a bare red exit code.
+Write-Host ""
+if ($code -eq 0) {
+  Write-Host "  Run finished with no failures." -ForegroundColor Green
+} else {
+  Write-Host "  Run finished and found problems — see the report above." -ForegroundColor Yellow
+  Write-Host "  That is the expected outcome when there is something to find." -ForegroundColor DarkGray
+}
+exit $code

package/examples/demo/adapters/demo.mjs

@@ -0,0 +1,90 @@
+// A pretend app, so Populace can be evaluated in ten seconds with no backend.
+//
+// It stores everything in memory and fakes plausible network latency. One
+// endpoint is deliberately slow and one deliberately flaky, so the report has
+// something real to say — which is the point of the demo. A demo where
+// everything passes teaches you nothing about what the tool is for.
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const latency = (base, spread) => sleep(base + Math.random() * spread);
+
+export function createAdapter() {
+  const db = { users: new Map(), posts: [], likes: 0, comments: 0, messages: 0, groups: [{ id: "riders" }, { id: "couriers" }] };
+  let likeCalls = 0;
+
+  return {
+    name: "demo",
+
+    async healthCheck() {
+      await latency(20, 30);
+    },
+
+    async createUser({ name, phone }) {
+      await latency(80, 120);
+      const id = `u_${phone}`;
+      db.users.set(id, { id, name });
+      return { id, name };
+    },
+
+    async setProfile() {
+      await latency(30, 40);
+    },
+
+    async reportLocation() {
+      await latency(15, 25);
+    },
+
+    async post(user, text) {
+      await latency(40, 60);
+      const post = { id: `p${db.posts.length}`, userId: user.id, text };
+      db.posts.push(post);
+      return post.id;
+    },
+
+    // Deliberately the slow one: an unindexed feed query is the single most
+    // common thing a simulation like this uncovers.
+    async recentPostsByOthers(user, limit = 10) {
+      await latency(180, 320);
+      return db.posts.filter((p) => p.userId !== user.id).slice(-limit);
+    },
+
+    // Deliberately the broken one: a permission rule that rejects some writes.
+    async like() {
+      await latency(25, 35);
+      likeCalls += 1;
+      if (likeCalls % 4 === 0) {
+        throw new Error(`new row violates row-level security policy "post_likes_insert"`);
+      }
+      db.likes += 1;
+    },
+
+    async comment() {
+      await latency(35, 45);
+      db.comments += 1;
+    },
+
+    async openConversation() {
+      await latency(50, 70);
+      return "thread_1";
+    },
+
+    async sendMessage() {
+      await latency(30, 40);
+      db.messages += 1;
+    },
+
+    async listGroups() {
+      await latency(25, 30);
+      return db.groups;
+    },
+
+    async joinGroup() {
+      await latency(40, 50);
+    },
+
+    async deleteUser(user) {
+      await latency(60, 80);
+      db.users.delete(user.id);
+    },
+  };
+}