@gigzen/populace 0.1.0

package/examples/rest-api/adapter.mjs

@@ -0,0 +1,166 @@
+/**
+ * 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,
+ * no error convention and no auth mechanism, and the engine cannot tell them
+ * apart. That is the whole argument.
+ *
+ * If your API looks like this one — HTTP, JSON, a bearer token — you can copy
+ * this file and change the URLs.
+ */
+
+export function createAdapter(target) {
+  const base = target.url.replace(/\/$/, "");
+
+  /**
+   * The contract hands an adapter a name, a phone and a persona — never a
+   * password. Choosing one is the adapter's job, exactly as the Buzz Buzz
+   * reference adapter does, because only you know what your API will accept.
+   *
+   * A constant is right here: identities are deterministic so that a re-run
+   * signs back in rather than piling up new accounts, and that only works if
+   * the credential is stable too.
+   */
+  const PASSWORD = "PopulaceDemo!2026";
+
+  /**
+   * One place where HTTP becomes either a value or a thrown Error.
+   *
+   * Populace groups failures by shape, so the message must describe the fault
+   * and not the request: "409 on /likes" tells you which endpoint is unhappy,
+   * whereas including the post id would make every occurrence unique and turn
+   * one bug into fifty lines in the report.
+   */
+  async function call(method, path, { token, body } = {}) {
+    const res = await fetch(`${base}${path}`, {
+      method,
+      headers: {
+        ...(body ? { "content-type": "application/json" } : {}),
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+      },
+      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";
+      // Never swallow this. An adapter that returns on failure makes the report
+      // blame a later method for an earlier fault — the exact defect Populace's
+      // own first run found in its own reference adapter.
+      throw new Error(`${res.status} on ${method} ${path}: ${detail}`);
+    }
+    return payload;
+  }
+
+  return {
+    name: "rest-api-demo",
+
+    async healthCheck() {
+      const res = await fetch(`${base}/health`, { signal: AbortSignal.timeout(10000) });
+      if (!res.ok) throw new Error(`health check returned ${res.status}`);
+    },
+
+    // ── identity ────────────────────────────────────────────────────────
+    // Signature per adapters/contract.md: { name, phone, persona, index }.
+    async createUser({ name, phone }) {
+      const out = await call("POST", "/auth/signup", {
+        body: { phone, password: PASSWORD, name },
+      });
+      // The handle is whatever later calls need. Here that is an integer id and
+      // a token; for Buzz Buzz it was a UUID and a client object. The engine
+      // only ever reads `.id`.
+      return { id: out.id, token: out.token };
+    },
+
+    // Lets `populace clean` check for leftovers without creating accounts to
+    // find out whether they exist.
+    async signIn({ phone }) {
+      try {
+        const out = await call("POST", "/auth/signin", {
+          body: { phone, password: PASSWORD },
+        });
+        return { id: out.id, token: out.token };
+      } catch (error) {
+        if (/^401/.test(error.message)) return null;   // genuinely not there
+        throw error;                                    // anything else is real
+      }
+    },
+
+    // The server issues 15-minute tokens. Without this a run longer than that
+    // collapses at once, the report blames the API, and cleanup cannot even
+    // delete its own accounts.
+    async refreshSession(user) {
+      const out = await call("POST", "/auth/refresh", { token: user.token });
+      user.token = out.token;
+      return user;
+    },
+
+    async setProfile(user, persona) {
+      await call("PATCH", "/me", {
+        token: user.token,
+        body: { name: persona.name, city: persona.city?.name },
+      });
+    },
+
+    async deleteUser(user) {
+      await call("DELETE", "/me", { token: user.token });
+    },
+
+    // ── movement ────────────────────────────────────────────────────────
+    async reportLocation(user, { lat, lng, distanceKm }) {
+      await call("POST", "/locations", {
+        token: user.token,
+        body: { lat, lng, km: distanceKm },
+      });
+    },
+
+    // ── social ──────────────────────────────────────────────────────────
+    async post(user, body) {
+      const out = await call("POST", "/posts", { token: user.token, body: { body } });
+      return out.id;                     // the engine needs this for like/comment
+    },
+
+    // Returns bare integer ids, not row objects. Perfectly legal under the
+    // contract, and the shape that used to break the engine.
+    async recentPostsByOthers(user) {
+      return await call("GET", "/posts/others", { token: user.token });
+    },
+
+    async like(user, postId) {
+      await call("POST", "/likes", { token: user.token, body: { postId } });
+    },
+
+    async comment(user, postId, body) {
+      await call("POST", "/comments", { token: user.token, body: { postId, body } });
+    },
+
+    // ── messaging ───────────────────────────────────────────────────────
+    async openConversation(user, otherUserId) {
+      const out = await call("POST", "/threads", {
+        token: user.token,
+        body: { otherUserId },
+      });
+      return out.id;
+    },
+
+    async sendMessage(user, threadId, body) {
+      await call("POST", "/messages", { token: user.token, body: { threadId, body } });
+    },
+
+    // ── groups ──────────────────────────────────────────────────────────
+    async listGroups(user) {
+      return await call("GET", "/groups", { token: user.token });
+    },
+
+    async joinGroup(user, groupId) {
+      await call("POST", "/groups/join", { token: user.token, body: { groupId } });
+    },
+  };
+}

package/examples/rest-api/populace.config.mjs

@@ -0,0 +1,40 @@
+/**
+ * Populace against a plain REST API.
+ *
+ * Two terminals:
+ *
+ *   node examples/rest-api/server.mjs
+ *   node src/cli.mjs run --config examples/rest-api/populace.config.mjs
+ *
+ * Nothing to sign up for and nothing to configure — the server is in this
+ * repository, holds everything in memory, and forgets it all when you stop it.
+ */
+
+export default {
+  app: "REST API demo",
+  adapter: "./adapter.mjs",
+  environment: "test",
+
+  target: {
+    url: process.env.REST_DEMO_URL || "http://127.0.0.1:8787",
+  },
+
+  // The demo server binds to loopback and has no real authentication, so it
+  // cannot be a production host. The guard is here anyway: an empty denylist
+  // warns loudly, and "the config I copied had nothing in it" is the likeliest
+  // way someone ends up pointing this at something real.
+  neverRunAgainst: [
+    "https://api.example.com",
+    "https://production",
+  ],
+
+  population: {
+    agents: 6,
+    cities: ["manila", "mumbai"],
+    minutes: 2,
+    tickSeconds: 3,
+  },
+
+  identity: { phonePrefix: "0700" },
+  report: { path: "populace-report.json" },
+};

package/examples/rest-api/server.mjs

@@ -0,0 +1,247 @@
+/**
+ * A small REST API, deliberately unlike the Supabase one Populace grew up on.
+ *
+ * The point of this file is not the server. It is the claim it lets us test:
+ * that the engine is app-agnostic. Populace had only ever been pointed at one
+ * real backend, and that backend was ours — a testing tool that has only tested
+ * its author's own app has not been shown to be portable.
+ *
+ * So every architectural choice here disagrees with Buzz Buzz on purpose:
+ *
+ *   Buzz Buzz / Supabase          this server
+ *   ────────────────────          ───────────────────────────────
+ *   supabase-js client            plain fetch over HTTP
+ *   UUID string ids               INTEGER ids
+ *   {data, error} tuples          HTTP status codes + {error: "..."}
+ *   session object on the client  Bearer token in an Authorization header
+ *   list endpoints return rows    list endpoints return BARE ID ARRAYS
+ *   RLS refuses in the database   the handler refuses in application code
+ *
+ * The bare id arrays matter most: that shape is what caught the engine reading
+ * `target.id` off a string. If this file agreed with Buzz Buzz it would prove
+ * nothing.
+ *
+ * Zero dependencies, in-memory, and it binds to 127.0.0.1 only — it is a test
+ * fixture, not something to deploy.
+ *
+ *   node examples/rest-api/server.mjs        # starts on :8787
+ */
+
+import http from "node:http";
+import crypto from "node:crypto";
+
+const PORT = Number(process.env.PORT || 8787);
+
+/* ── storage ───────────────────────────────────────────────────────────── */
+const db = {
+  users: new Map(),        // id -> { id, phone, password, name, city, deleted }
+  tokens: new Map(),       // token -> { userId, expiresAt }
+  posts: [],               // { id, authorId, body }
+  likes: new Set(),        // `${postId}:${userId}`
+  comments: [],            // { id, postId, authorId, body }
+  threads: [],             // { id, a, b }
+  messages: [],            // { id, threadId, senderId, body }
+  groups: [{ id: 1, name: "Night shift" }, { id: 2, name: "Airport runs" }],
+  members: new Set(),      // `${groupId}:${userId}`
+  locations: [],           // { userId, lat, lng, km }
+};
+
+let nextId = 1;
+const newId = () => nextId++;                    // INTEGER ids, not UUIDs
+
+/* Short-lived on purpose: a run longer than this must call the refresh
+   endpoint, which is how adapters that forget refreshSession get caught. */
+const TOKEN_TTL_MS = 15 * 60 * 1000;
+
+function issueToken(userId) {
+  const token = crypto.randomBytes(24).toString("hex");
+  db.tokens.set(token, { userId, expiresAt: Date.now() + TOKEN_TTL_MS });
+  return token;
+}
+
+function authenticate(req) {
+  const header = req.headers.authorization || "";
+  const token = header.startsWith("Bearer ") ? header.slice(7) : null;
+  if (!token) return { error: 401, message: "missing bearer token" };
+  const entry = db.tokens.get(token);
+  if (!entry) return { error: 401, message: "unknown token" };
+  if (entry.expiresAt < Date.now()) return { error: 401, message: "token expired" };
+  const user = db.users.get(entry.userId);
+  if (!user || user.deleted) return { error: 401, message: "account no longer exists" };
+  return { user, token };
+}
+
+/* ── helpers ───────────────────────────────────────────────────────────── */
+const send = (res, status, body) => {
+  const payload = body === undefined ? "" : JSON.stringify(body);
+  res.writeHead(status, {
+    "content-type": "application/json",
+    "content-length": Buffer.byteLength(payload),
+  });
+  res.end(payload);
+};
+
+const readBody = (req) =>
+  new Promise((resolve, reject) => {
+    let raw = "";
+    req.on("data", (c) => {
+      raw += c;
+      if (raw.length > 1e6) reject(new Error("body too large"));
+    });
+    req.on("end", () => {
+      if (!raw) return resolve({});
+      try { resolve(JSON.parse(raw)); } catch { reject(new Error("invalid JSON")); }
+    });
+    req.on("error", reject);
+  });
+
+/* ── routes ────────────────────────────────────────────────────────────── */
+const routes = {
+  "GET /health": async () => [200, { ok: true }],
+
+  "POST /auth/signup": async (_req, body) => {
+    if (!body.phone || !body.password) return [400, { error: "phone and password required" }];
+    // Deterministic identities mean re-runs re-use accounts rather than piling
+    // up new ones, so signup on an existing phone is a sign-in.
+    const existing = [...db.users.values()].find((u) => u.phone === body.phone && !u.deleted);
+    if (existing) {
+      if (existing.password !== body.password) return [401, { error: "wrong password" }];
+      return [200, { id: existing.id, token: issueToken(existing.id) }];
+    }
+    const id = newId();
+    db.users.set(id, { id, phone: body.phone, password: body.password, name: body.name || "", deleted: false });
+    return [201, { id, token: issueToken(id) }];
+  },
+
+  "POST /auth/signin": async (_req, body) => {
+    const user = [...db.users.values()].find((u) => u.phone === body.phone && !u.deleted);
+    if (!user || user.password !== body.password) return [401, { error: "invalid credentials" }];
+    return [200, { id: user.id, token: issueToken(user.id) }];
+  },
+
+  "POST /auth/refresh": async (req) => {
+    const header = req.headers.authorization || "";
+    const token = header.startsWith("Bearer ") ? header.slice(7) : null;
+    const entry = token && db.tokens.get(token);
+    // An EXPIRED token can still be refreshed; an unknown one cannot.
+    if (!entry) return [401, { error: "unknown token" }];
+    db.tokens.delete(token);
+    return [200, { token: issueToken(entry.userId) }];
+  },
+
+  "PATCH /me": async (req, body, auth) => {
+    auth.user.name = body.name ?? auth.user.name;
+    auth.user.city = body.city ?? auth.user.city;
+    return [200, { id: auth.user.id }];
+  },
+
+  "DELETE /me": async (_req, _body, auth) => {
+    auth.user.deleted = true;
+    for (const [t, e] of db.tokens) if (e.userId === auth.user.id) db.tokens.delete(t);
+    return [204, undefined];
+  },
+
+  "POST /locations": async (_req, body, auth) => {
+    if (typeof body.lat !== "number" || typeof body.lng !== "number") {
+      return [400, { error: "lat and lng must be numbers" }];
+    }
+    db.locations.push({ userId: auth.user.id, lat: body.lat, lng: body.lng, km: body.km ?? 0 });
+    return [201, { ok: true }];
+  },
+
+  "POST /posts": async (_req, body, auth) => {
+    if (!body.body) return [400, { error: "body required" }];
+    const id = newId();
+    db.posts.push({ id, authorId: auth.user.id, body: body.body });
+    return [201, { id }];
+  },
+
+  // Bare ids, not objects. This is the shape that caught the engine.
+  "GET /posts/others": async (_req, _body, auth) =>
+    [200, db.posts.filter((p) => p.authorId !== auth.user.id).slice(-10).map((p) => p.id)],
+
+  "POST /likes": async (_req, body, auth) => {
+    const post = db.posts.find((p) => p.id === body.postId);
+    if (!post) return [404, { error: "no such post" }];
+    const key = `${body.postId}:${auth.user.id}`;
+    // Liking twice is a no-op, not an error. The Supabase version got this
+    // wrong via upsert, and any port of that mistake would show up here.
+    db.likes.add(key);
+    return [201, { ok: true }];
+  },
+
+  "POST /comments": async (_req, body, auth) => {
+    const post = db.posts.find((p) => p.id === body.postId);
+    if (!post) return [404, { error: "no such post" }];
+    const id = newId();
+    db.comments.push({ id, postId: body.postId, authorId: auth.user.id, body: body.body });
+    return [201, { id }];
+  },
+
+  "POST /threads": async (_req, body, auth) => {
+    const other = Number(body.otherUserId);
+    if (!Number.isInteger(other)) return [400, { error: "otherUserId must be an integer" }];
+    if (other === auth.user.id) return [400, { error: "cannot open a thread with yourself" }];
+    if (!db.users.has(other)) return [404, { error: "no such user" }];
+    const found = db.threads.find(
+      (t) => (t.a === auth.user.id && t.b === other) || (t.a === other && t.b === auth.user.id),
+    );
+    if (found) return [200, { id: found.id }];
+    const id = newId();
+    db.threads.push({ id, a: auth.user.id, b: other });
+    return [201, { id }];
+  },
+
+  "POST /messages": async (_req, body, auth) => {
+    const thread = db.threads.find((t) => t.id === Number(body.threadId));
+    if (!thread) return [404, { error: "no such thread" }];
+    // Refused in application code rather than by a database policy — a
+    // different enforcement point from Buzz Buzz, deliberately.
+    if (thread.a !== auth.user.id && thread.b !== auth.user.id) {
+      return [403, { error: "not a participant in this thread" }];
+    }
+    const id = newId();
+    db.messages.push({ id, threadId: thread.id, senderId: auth.user.id, body: body.body });
+    return [201, { id }];
+  },
+
+  "GET /groups": async () => [200, db.groups.map((g) => g.id)],   // bare ids again
+
+  "POST /groups/join": async (_req, body, auth) => {
+    const group = db.groups.find((g) => g.id === Number(body.groupId));
+    if (!group) return [404, { error: "no such group" }];
+    db.members.add(`${group.id}:${auth.user.id}`);   // idempotent, like /likes
+    return [201, { ok: true }];
+  },
+};
+
+const PUBLIC = new Set(["GET /health", "POST /auth/signup", "POST /auth/signin", "POST /auth/refresh"]);
+
+const server = http.createServer(async (req, res) => {
+  const url = new URL(req.url, `http://${req.headers.host}`);
+  const key = `${req.method} ${url.pathname}`;
+  const handler = routes[key];
+  if (!handler) return send(res, 404, { error: `no route for ${key}` });
+
+  try {
+    const body = ["POST", "PATCH", "PUT"].includes(req.method) ? await readBody(req) : {};
+    let auth = null;
+    if (!PUBLIC.has(key)) {
+      auth = authenticate(req);
+      if (auth.error) return send(res, auth.error, { error: auth.message });
+    }
+    const [status, payload] = await handler(req, body, auth);
+    send(res, status, payload);
+  } catch (error) {
+    send(res, 400, { error: error.message });
+  }
+});
+
+// 127.0.0.1, never 0.0.0.0: this has no real authentication and must not be
+// reachable from another machine.
+server.listen(PORT, "127.0.0.1", () => {
+  console.log(`  demo REST API on http://127.0.0.1:${PORT}`);
+  console.log(`  integer ids · bearer tokens · bare id arrays · ${TOKEN_TTL_MS / 60000}min token TTL`);
+});
+
+export { server, db };

package/examples/token-expiry/expiry-demo.mjs

@@ -0,0 +1,119 @@
+// A visible before/after for the session-expiry defect.
+//
+//   node examples/token-expiry/expiry-demo.mjs
+//
+// Both runs use the SAME population against the SAME pretend app — an app whose
+// access tokens expire after 3 seconds. The only difference is whether the
+// adapter implements refreshSession().
+//
+// This is the failure worth demonstrating because of how it LIES: the agents
+// keep moving, the table keeps updating, the run looks healthy — while every
+// single call is rejected. A customer would read that as their own API falling
+// over under load.
+
+import { World } from "../../src/engine/world.mjs";
+import { buildPersonas } from "../../src/engine/personas.mjs";
+import { createMetrics, instrument, summarise } from "../../src/instrument.mjs";
+
+const TOKEN_TTL_MS = 3000;
+
+function pretendApp({ supportsRefresh }) {
+  const sessions = new Map();
+  const seen = { posts: 0, locations: 0 };
+
+  const assertLive = (user) => {
+    const expiresAt = sessions.get(user.id);
+    if (!expiresAt || Date.now() > expiresAt) {
+      throw new Error(`JWT expired (token issued for user ${user.id})`);
+    }
+  };
+
+  const adapter = {
+    name: supportsRefresh ? "with-refresh" : "no-refresh",
+    async createUser({ name, phone }) {
+      const id = `u_${phone}`;
+      sessions.set(id, Date.now() + TOKEN_TTL_MS);
+      return { id, name };
+    },
+    async setProfile(user) {
+      assertLive(user);
+    },
+    async reportLocation(user) {
+      assertLive(user);
+      seen.locations += 1;
+    },
+    async post(user) {
+      assertLive(user);
+      seen.posts += 1;
+      return `p${seen.posts}`;
+    },
+    async recentPostsByOthers(user) {
+      assertLive(user);
+      return [];
+    },
+    async deleteUser(user) {
+      assertLive(user);
+      sessions.delete(user.id);
+    },
+    seen,
+  };
+
+  if (supportsRefresh) {
+    adapter.refreshSession = async (user) => {
+      if (!sessions.has(user.id)) throw new Error("no session to refresh");
+      sessions.set(user.id, Date.now() + TOKEN_TTL_MS);
+    };
+  }
+  return adapter;
+}
+
+async function go({ supportsRefresh }) {
+  const app = pretendApp({ supportsRefresh });
+  const metrics = createMetrics();
+  const world = new World({
+    adapter: instrument(app, metrics),
+    personas: buildPersonas(4, ["manila", "mumbai"]),
+    // Refresh well inside the 3s token, the same way the real default sits
+    // well inside a 1-hour one.
+    options: { refreshEveryMs: 1200 },
+  });
+
+  await world.populate({ staggerMs: 0 });
+  await world.run({ minutes: 0.25, tickSeconds: 1, realtime: true });
+  metrics.endedAt = Date.now();
+
+  const api = summarise(metrics);
+  const teardown = await world.teardown();
+  return { api, world, app, teardown };
+}
+
+const pct = (n) => `${(n * 100).toFixed(0)}%`;
+const row = (label, a, b) => console.log(`  ${label.padEnd(30)}${String(a).padStart(18)}${String(b).padStart(18)}`);
+
+console.log(`\n  Pretend app: access tokens expire after ${TOKEN_TTL_MS / 1000}s. Run lasts ~15s.\n`);
+
+process.stdout.write("  running WITHOUT refreshSession… ");
+const before = await go({ supportsRefresh: false });
+console.log("done");
+process.stdout.write("  running WITH refreshSession…    ");
+const after = await go({ supportsRefresh: true });
+console.log("done\n");
+
+console.log("  " + "─".repeat(64));
+row("", "no refreshSession", "with refresh");
+console.log("  " + "─".repeat(64));
+row("API calls attempted", before.api.calls, after.api.calls);
+row("API calls FAILED", before.api.failures, after.api.failures);
+row("failure rate", pct(before.api.failureRate), pct(after.api.failureRate));
+row("location writes accepted", before.app.seen.locations, after.app.seen.locations);
+row("posts accepted", before.app.seen.posts, after.app.seen.posts);
+row("accounts cleaned up", before.teardown.removed, after.teardown.removed);
+row("accounts LEFT BEHIND", before.teardown.failed.length, after.teardown.failed.length);
+console.log("  " + "─".repeat(64));
+
+const topBefore = before.api.methods.find((m) => m.failures)?.errors[0];
+if (topBefore) console.log(`\n  What the broken run reported: "${topBefore.message}"`);
+console.log(
+  `\n  Both runs kept ${before.world.agents.length} agents "alive" on screen the whole time.\n` +
+    `  Only the numbers show that one of them stopped testing anything after ${TOKEN_TTL_MS / 1000}s.\n`,
+);

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@gigzen/populace",
+  "version": "0.1.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": {
+    "populace": "./src/cli.mjs"
+  },
+  "main": "./src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./engine": "./src/engine/index.mjs"
+  },
+  "files": [
+    "src",
+    "adapters",
+    "examples",
+    "populace.config.example.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "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"
+  }
+}