@gigzen/populace 0.1.0

package/src/config.mjs

@@ -0,0 +1,186 @@
+// Config loading and the production safety guard.
+//
+// The guard is the most important code in this product. Populace creates REAL
+// accounts and writes REAL rows through a customer's REAL API. Pointed at
+// production it would put invented people in front of paying users — that is
+// deception, not testing, and it is painful to unpick afterwards.
+//
+// So the guard is deliberately hard to get past by accident, and it refuses in
+// three independent ways. Any one of them is enough to stop a run.
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+export class ConfigError extends Error {}
+
+const strip = (u) => String(u || "").trim().replace(/\/+$/, "").toLowerCase();
+
+/** Pull every string out of a nested object, so we can scan a whole target block. */
+function stringsIn(value, found = []) {
+  if (typeof value === "string") found.push(value);
+  else if (Array.isArray(value)) value.forEach((v) => stringsIn(v, found));
+  else if (value && typeof value === "object") Object.values(value).forEach((v) => stringsIn(v, found));
+  return found;
+}
+
+const DEFAULTS = {
+  environment: "test",
+  // How long any single adapter call may take before it is recorded as a
+  // timeout and the run moves on. Without this a dead socket hangs the whole
+  // simulation. Set 0 to disable if your adapter does legitimately long work.
+  timeoutMs: 20_000,
+  // Extra attempts for calls that never reached the server. Transport only —
+  // an error your API actually returned is a finding and is never retried.
+  retries: 3,
+  // 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,
+  population: { agents: 6, cities: ["manila", "mumbai"], tickSeconds: 5, minutes: 10 },
+  // Comfortably inside a 1-hour token, which is the common default.
+  session: { refreshEveryMinutes: 30 },
+  report: { path: "populace-report.json" },
+};
+
+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;
+  const file = path.resolve(cwd, configPath || "populace.config.mjs");
+
+  if (!fs.existsSync(file)) {
+    throw new ConfigError(
+      `No config found at ${path.relative(cwd, file) || file}\n\n` +
+        `  Create one with:   populace init\n` +
+        `  Or point at one:   populace run --config path/to/populace.config.mjs`,
+    );
+  }
+
+  const loaded = (await import(pathToFileURL(file).href)).default;
+  if (!loaded || typeof loaded !== "object") {
+    throw new ConfigError(`${path.basename(file)} must \`export default\` a config object.`);
+  }
+
+  const config = {
+    ...DEFAULTS,
+    ...loaded,
+    population: {
+      ...DEFAULTS.population,
+      ...(loaded.population || {}),
+      ...populationOverrides,
+    },
+    session: { ...DEFAULTS.session, ...(loaded.session || {}) },
+    report: {
+      ...DEFAULTS.report,
+      ...(loaded.report || {}),
+      // --report wins over the config file, so a run can put its output
+      // somewhere else without editing anything.
+      ...(overrides.reportPath ? { path: overrides.reportPath } : {}),
+    },
+    _dir: path.dirname(file),
+    _file: file,
+  };
+
+  if (!config.adapter) {
+    throw new ConfigError(`Config is missing \`adapter\` — the path to your adapter module.`);
+  }
+
+  guardProduction(config);
+  return config;
+}
+
+/**
+ * Three independent refusals. Each exists because a different mistake is easy
+ * to make at 1am, and the cost of getting it wrong is borne by the customer's
+ * real users rather than by whoever made the mistake.
+ */
+export function guardProduction(config) {
+  const refuse = (why, fix) => {
+    throw new ConfigError(`REFUSING TO RUN\n\n  ${why}\n\n  ${fix}`);
+  };
+
+  // 1. The environment must SAY it is not production. Opt in, never assume.
+  const env = String(config.environment || "").toLowerCase();
+  if (!["test", "staging", "dev", "development", "sandbox", "local"].includes(env)) {
+    refuse(
+      env === "production" || env === "prod"
+        ? `The config declares environment: "${config.environment}".`
+        : `The config declares environment: "${config.environment || "(unset)"}", which is not a recognised non-production environment.`,
+      `Populace only runs against test environments. Set environment: "test"\n` +
+        `  in ${path.basename(config._file || "populace.config.mjs")} — and make sure that is actually true.`,
+    );
+  }
+
+  // 2. Explicit denylist — a customer names their production hosts once and can
+  //    never hit them again, however the config is later edited.
+  const denied = [
+    ...(config.neverRunAgainst || []),
+    ...String(process.env.POPULACE_PRODUCTION_URLS || "")
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean),
+  ].map(strip);
+
+  if (denied.length) {
+    const targets = stringsIn(config.target).map(strip).filter(Boolean);
+    const hit = targets.find((t) => denied.some((d) => d && (t === d || t.includes(d) || d.includes(t))));
+    if (hit) {
+      refuse(
+        `The target matches a host listed in neverRunAgainst:\n    ${hit}`,
+        `Simulated people must never be visible to real users.\n` +
+          `  Point \`target\` at a separate test environment.`,
+      );
+    }
+  }
+
+  // 3. A live-looking hostname with nothing declared to protect it. Not proof of
+  //    production, so this one is a warning rather than a refusal — but it is
+  //    loud, because "I forgot to fill in neverRunAgainst" is the likeliest
+  //    version of this mistake.
+  if (!denied.length) {
+    config._warnings = [
+      ...(config._warnings || []),
+      `neverRunAgainst is empty. List your production URLs there so this can never point at them.`,
+    ];
+  }
+  return config;
+}
+
+/** Load the customer's adapter module and sanity-check its shape. */
+export async function loadAdapter(config) {
+  const file = path.resolve(config._dir || process.cwd(), config.adapter);
+  if (!fs.existsSync(file)) {
+    throw new ConfigError(`Adapter not found: ${config.adapter}\n  Looked in ${file}`);
+  }
+  const mod = await import(pathToFileURL(file).href);
+  const factory = mod.createAdapter || mod.default;
+  if (typeof factory !== "function") {
+    throw new ConfigError(
+      `${config.adapter} must export \`createAdapter(config)\`.\n` +
+        `  See adapters/contract.md for the full contract.`,
+    );
+  }
+  // An adapter that refuses to build is almost always a configuration mistake
+  // (a missing env var, usually). Present it as one instead of a stack trace —
+  // the person hitting this is evaluating the product in their first minute.
+  let adapter;
+  try {
+    adapter = await factory(config.target ?? {}, config);
+  } catch (error) {
+    throw new ConfigError(
+      `Adapter "${path.basename(config.adapter)}" could not start:\n\n` +
+        `  ${String(error.message || error).replace(/\n/g, "\n  ")}\n\n` +
+        `  Check \`target\` in ${path.basename(config._file || "populace.config.mjs")}.`,
+    );
+  }
+  if (!adapter || typeof adapter !== "object") {
+    throw new ConfigError(`createAdapter() must return an object of methods.`);
+  }
+  if (typeof adapter.createUser !== "function") {
+    throw new ConfigError(
+      `Adapter "${adapter.name || config.adapter}" has no createUser().\n` +
+        `  That is the one method every adapter must implement — without an\n` +
+        `  identity there is nobody to simulate.`,
+    );
+  }
+  return adapter;
+}

package/src/contract.mjs

@@ -0,0 +1,130 @@
+// The adapter contract, as data.
+//
+// Kept here rather than only in prose so that `populace doctor` can tell a
+// customer exactly which parts of their app the simulation will and will not
+// exercise — before they spend a run finding out.
+
+export const CONTRACT = [
+  {
+    method: "createUser",
+    required: true,
+    group: "identity",
+    exercises: "sign-up, sign-in, and whatever your app does on first contact with a new account",
+  },
+  {
+    method: "setProfile",
+    group: "identity",
+    exercises: "the settings a new user configures before they start",
+  },
+  {
+    method: "refreshSession",
+    group: "identity",
+    exercises: "token refresh — without it, any run longer than your token lifetime collapses and looks like your API failing",
+  },
+  {
+    method: "reportLocation",
+    group: "world",
+    exercises: "high-frequency writes — the heaviest sustained load most apps take",
+  },
+  { method: "post", group: "social", exercises: "user-generated content creation" },
+  {
+    method: "recentPostsByOthers",
+    group: "social",
+    exercises: "feed reads under concurrent writes, and whether your permission rules leak",
+  },
+  { method: "like", group: "social", exercises: "high-contention writes on shared rows" },
+  { method: "comment", group: "social", exercises: "nested content and its notifications" },
+  {
+    method: "openConversation",
+    group: "messaging",
+    exercises: "conversation creation between two accounts that have never met",
+  },
+  {
+    method: "sendMessage",
+    group: "messaging",
+    exercises: "delivery, ordering, receipts, and realtime fan-out",
+  },
+  { method: "listGroups", group: "groups", exercises: "shared-resource reads" },
+  { method: "joinGroup", group: "groups", exercises: "membership writes and counter accuracy" },
+  {
+    method: "deleteUser",
+    required: true,
+    group: "cleanup",
+    exercises: "account deletion and cascade — the path almost nobody tests",
+  },
+];
+
+export const CONTRACT_METHODS = CONTRACT.map((c) => c.method);
+
+/**
+ * `signIn` is a CLEANUP CAPABILITY, deliberately not a fourteenth contract
+ * method.
+ *
+ * It takes no part in a run. It exists only so `clean` can ask "does this
+ * identity exist?" without creating it. Without it, clean reaches an account
+ * through createUser — which signs UP when the identity is absent — so
+ * cleaning an already-clean environment writes a row to the customer's auth
+ * table for every agent purely to prove the table is empty, and the per-account
+ * result cannot distinguish "found and removed" from "was never there".
+ *
+ * Kept out of CONTRACT on purpose: coverage is a statement about how much of
+ * the customer's app a RUN exercises, and folding a cleanup-only capability
+ * into that denominator would drop every existing adapter to 13/14 and make the
+ * published "13-method contract" wrong without anything having got worse.
+ * It is reported separately instead.
+ *
+ * Shape:
+ *   async signIn({ name, phone, persona, index })
+ *     -> user   when the account exists
+ *     -> null   when it definitively does not
+ *     throws    on transport or unexpected failure (never swallow — a failure
+ *               to look is not evidence of absence)
+ */
+export const CLEANUP_CAPABILITY = {
+  method: "signIn",
+  exercises:
+    "checking whether a simulated identity exists without creating it, so cleanup never writes to your auth table",
+};
+
+/** True when the adapter can be asked about an account without creating one. */
+export function canSignInOnly(adapter) {
+  const fn = adapter?.[CLEANUP_CAPABILITY.method];
+  return typeof fn === "function" && !isStub(fn);
+}
+
+/**
+ * A method that exists but does nothing is NOT coverage.
+ *
+ * Without this, a freshly scaffolded adapter reports 12/12 and produces a
+ * clean run while testing absolutely nothing — the worst possible outcome for
+ * a tool whose entire value is telling you the truth about your app.
+ */
+export function isStub(fn) {
+  if (typeof fn !== "function") return true;
+  const src = Function.prototype.toString.call(fn);
+  const open = src.indexOf("{");
+  const close = src.lastIndexOf("}");
+  if (open === -1 || close <= open) return false; // concise arrow — real code
+  const body = src
+    .slice(open + 1, close)
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/\/\/.*$/gm, "")
+    .trim();
+  if (!body) return true;
+  return /^throw\s+new\s+\w*Error\s*\(\s*(["'`]).*not implemented.*\1\s*\)\s*;?$/i.test(body);
+}
+
+export function coverageOf(adapter) {
+  const implemented = [];
+  const missing = [];
+  for (const entry of CONTRACT) {
+    const fn = adapter?.[entry.method];
+    (typeof fn === "function" && !isStub(fn) ? implemented : missing).push(entry);
+  }
+  return {
+    implemented,
+    missing,
+    ratio: implemented.length / CONTRACT.length,
+    label: `${implemented.length}/${CONTRACT.length}`,
+  };
+}

package/src/diagnose.mjs

@@ -0,0 +1,40 @@
+// What `populace doctor` decides, separated from how it prints.
+//
+// The decision used to live inside the command, interleaved with console.log
+// and process.exitCode, which meant the one thing that stops a customer running
+// a useless simulation — "are you actually ready?" — could not be tested
+// without spawning a process and matching strings. This is the judgement on its
+// own, as data.
+
+import { canSignInOnly, coverageOf } from "./contract.mjs";
+
+/**
+ * @param {object}  o
+ * @param {object}  o.config      loaded config
+ * @param {object}  o.adapter     the raw adapter
+ * @param {boolean|null} o.reachable  true / false / null when not checked
+ * @returns {{coverage, cleanup, guarded, blockers: string[], ready: boolean}}
+ */
+export function diagnose({ config, adapter, reachable = null }) {
+  const coverage = coverageOf(adapter);
+  const blockers = [];
+
+  // Order matters only for the message; both are reported when both apply.
+  if (reachable === false) blockers.push("the target is unreachable");
+
+  const missingRequired = coverage.missing.filter((c) => c.required);
+  if (missingRequired.length) {
+    blockers.push(
+      `${missingRequired.map((c) => c.method).join(" and ")} ` +
+        `${missingRequired.length > 1 ? "are" : "is"} required`,
+    );
+  }
+
+  return {
+    coverage,
+    cleanup: canSignInOnly(adapter) ? "read-only" : "create-then-delete",
+    guarded: (config?.neverRunAgainst || []).length,
+    blockers,
+    ready: blockers.length === 0,
+  };
+}

package/src/engine/agent.mjs

@@ -0,0 +1,264 @@
+// One simulated person.
+//
+// This file knows how to BE someone — where they move, how often they post,
+// when they take a break, who they talk to. It knows nothing about any
+// particular app: every action goes through an adapter (adapters/contract.md).
+//
+// That separation is the product. Pointing the simulation at a different app
+// means writing one adapter, not editing this file. If app-specific logic ever
+// creeps in here, Populace has quietly collapsed back into a test script.
+
+import { advance, buildRoute, haversineKm } from "./geo.mjs";
+import { chatterFor, replyLine } from "./personas.mjs";
+
+const chance = (p) => Math.random() < p;
+const pickOne = (arr) => arr[Math.floor(Math.random() * arr.length)];
+
+export class Agent {
+  constructor(persona, adapter, index, options = {}) {
+    this.persona = persona;
+    this.adapter = adapter;
+    this.index = index;
+
+    // Deterministic identity per agent, so re-runs REUSE accounts rather than
+    // leaving a trail of abandoned ones across a customer's test environment.
+    const prefix = options.phonePrefix ?? "0900";
+    this.phone = `${prefix}${String(1000000 + index).slice(-7)}`;
+
+    this.route = buildRoute(persona.city, index + 1);
+    this.legIndex = 0;
+    this.progressKm = 0;
+    this.position = this.route[0];
+    this.distanceKm = 0;
+    this.earnings = 0;
+    this.onBreak = false;
+    this.log = [];
+    this.stats = { posts: 0, likes: 0, comments: 0, messages: 0, groups: 0, reauths: 0, errors: 0 };
+    // Failures that did not come from the adapter — i.e. bugs in this engine.
+    this.engineErrors = [];
+
+    // Access tokens expire. A run longer than the token lifetime would see
+    // every agent start failing at once — and a customer would reasonably read
+    // that as THEIR API collapsing under load. Lying to someone about their own
+    // system is the worst failure this product could have, so sessions are
+    // refreshed on a cadence well inside any normal expiry.
+    this.refreshEveryMs = options.refreshEveryMs ?? 30 * 60 * 1000;
+    this.lastRefreshAt = Date.now();
+  }
+
+  note(what) {
+    this.log.push(what);
+    if (this.log.length > 6) this.log.shift();
+  }
+
+  /** Only call adapter methods the adapter actually implements. */
+  can(method) {
+    return typeof this.adapter[method] === "function";
+  }
+
+  /**
+   * Ask whether this person's account exists, WITHOUT creating it.
+   *
+   *   user      — it exists, and we are now signed in as them
+   *   null      — it definitively does not exist
+   *   undefined — the adapter cannot tell us (no signIn capability)
+   *
+   * The three-way answer matters: cleanup must never turn "I could not look"
+   * into "there was nothing there".
+   */
+  async findAccount() {
+    if (!this.can("signIn")) return undefined;
+    const user = await this.adapter.signIn({
+      name: this.persona.name,
+      phone: this.phone,
+      persona: this.persona,
+      index: this.index,
+    });
+    this.user = user || null;
+    return user || null;
+  }
+
+  async ensureAccount() {
+    this.user = await this.adapter.createUser({
+      name: this.persona.name,
+      phone: this.phone,
+      persona: this.persona,
+      index: this.index,
+    });
+    if (this.can("setProfile")) await this.adapter.setProfile(this.user, this.persona);
+    this.lastRefreshAt = Date.now();
+    this.note("signed in");
+    return this.user.id;
+  }
+
+  /**
+   * Keep this person's session alive.
+   *
+   * Two layers on purpose. A refresh is cheap and usual; re-authenticating from
+   * scratch is the fallback for when the refresh token itself has gone. An
+   * agent that silently 401s for the rest of a run still LOOKS busy in the
+   * table while testing nothing at all, which is the failure mode this exists
+   * to prevent.
+   */
+  async ensureFreshSession() {
+    if (!this.can("refreshSession") || !this.user) return;
+    if (Date.now() - this.lastRefreshAt < this.refreshEveryMs) return;
+
+    this.lastRefreshAt = Date.now();
+    try {
+      await this.adapter.refreshSession(this.user);
+      this.note("refreshed session");
+    } catch {
+      await this.ensureAccount();
+      this.stats.reauths += 1;
+      this.note("re-authenticated");
+    }
+  }
+
+  /** One step of a life: move a little, then maybe do something social. */
+  async tick(secondsPerTick, world) {
+    try {
+      // Before anything else — including while on a break, since a break can
+      // easily outlast a token.
+      await this.ensureFreshSession();
+
+      if (this.onBreak) {
+        if (chance(0.35)) {
+          this.onBreak = false;
+          this.note("back on the road");
+        }
+        return;
+      }
+      if (chance(this.persona.breakiness)) {
+        this.onBreak = true;
+        this.note("taking a break");
+        return;
+      }
+
+      // --- move ---
+      const km = (this.persona.speedKmh / 3600) * secondsPerTick;
+      const next = advance(this.route, this.legIndex, this.progressKm, km);
+      this.distanceKm += haversineKm(this.position, next.position);
+      this.earnings = this.distanceKm * this.persona.rate;
+      this.position = next.position;
+      this.legIndex = next.legIndex;
+      this.progressKm = next.progressKm;
+
+      if (this.can("reportLocation")) {
+        await this.adapter.reportLocation(this.user, {
+          lat: this.position.lat,
+          lng: this.position.lng,
+          distanceKm: this.distanceKm,
+          earnings: this.earnings,
+          platform: this.persona.platform,
+        });
+      }
+
+      // --- social ---
+      if (chance(this.persona.postiness)) await this.post();
+      if (chance(this.persona.likeliness)) await this.reactToSomeone();
+      if (chance(this.persona.chattiness)) await this.chat(world);
+      if (chance(0.02)) await this.joinAGroup();
+    } catch (error) {
+      // An adapter failure is expected material: the instrumentation wrapper has
+      // already recorded it, and one person's app breaking should not end
+      // everyone else's shift.
+      //
+      // An UNTAGGED failure never reached the adapter, so it is a bug in this
+      // engine. Swallowing it silently would let Populace break and still print
+      // a clean report — the same defect as the failure-rate tolerance band that
+      // was removed from the verdict, and worse here, because the tool would be
+      // vouching for an app it never actually exercised.
+      this.stats.errors += 1;
+      if (!error?.fromAdapter) {
+        this.engineErrors.push(String(error?.stack || error?.message || error).slice(0, 300));
+      }
+      this.note(`error: ${String(error.message || error).slice(0, 60)}`);
+    }
+  }
+
+  async post() {
+    if (!this.can("post")) return;
+    const body = chatterFor(this.persona.cityKey, this.stats.posts + this.index);
+    await this.adapter.post(this.user, body);
+    this.stats.posts += 1;
+    this.note(`posted: ${body.slice(0, 34)}…`);
+  }
+
+  /**
+   * Take the id out of whatever the adapter returned.
+   *
+   * The contract says these methods return "posts" and "groups" without saying
+   * they must be objects, and plenty of APIs answer a list endpoint with bare
+   * ids. `smoke` already accepted both — it used `first.id ?? first` — but the
+   * engine did not, so an adapter returning strings passed the smoke test and
+   * then failed on the first tick of a real run. That is exactly the "subtly
+   * wrong adapter" case smoke exists to rule out, so the two now agree.
+   */
+  static idOf(item) {
+    if (item === null || item === undefined) return undefined;
+    if (typeof item === "object") return item.id ?? item.uuid ?? item._id ?? item.key;
+    return item;                                  // already a bare id
+  }
+
+  async reactToSomeone() {
+    if (!this.can("recentPostsByOthers") || !this.can("like")) return;
+    const posts = await this.adapter.recentPostsByOthers(this.user, 10);
+    if (!posts?.length) return;
+    const target = pickOne(posts);
+    const targetId = Agent.idOf(target);
+    if (targetId === undefined) return;
+    await this.adapter.like(this.user, targetId);
+    this.stats.likes += 1;
+
+    if (chance(0.4) && this.can("comment")) {
+      const body = replyLine(this.stats.comments + this.index);
+      await this.adapter.comment(this.user, targetId, body);
+      this.stats.comments += 1;
+      this.note(`commented "${body.slice(0, 22)}…"`);
+    } else {
+      this.note("liked a post");
+    }
+  }
+
+  async chat(world) {
+    if (!this.can("openConversation") || !this.can("sendMessage")) return;
+    const others = world.agents.filter((a) => a.user && a.user.id !== this.user.id);
+    if (!others.length) return;
+    const other = pickOne(others);
+
+    const conversationId = await this.adapter.openConversation(this.user, other.user.id);
+    if (!conversationId) return;
+    await this.adapter.sendMessage(this.user, conversationId, replyLine(this.stats.messages + this.index));
+    this.stats.messages += 1;
+    this.note(`messaged ${other.persona.name.split(" ")[0]}`);
+  }
+
+  async joinAGroup() {
+    if (!this.can("listGroups") || !this.can("joinGroup")) return;
+    const groups = await this.adapter.listGroups(this.user);
+    if (!groups?.length) return;
+    const group = pickOne(groups);
+    const groupId = Agent.idOf(group);
+    if (groupId === undefined) return;
+    await this.adapter.joinGroup(this.user, groupId);
+    this.stats.groups += 1;
+    this.note(`joined ${groupId}`);
+  }
+
+  /**
+   * Delete this person's account, and say whether that actually happened.
+   *
+   * It used to return undefined on the two paths where it does nothing — no
+   * deleteUser on the adapter, or no account to delete — which teardown counted
+   * as a successful removal. A run could therefore report "Cleanup complete —
+   * 6 accounts removed" having deleted none of them. The caller has to be able
+   * to tell "done" from "there was nothing to do".
+   */
+  async selfDestruct() {
+    if (!this.can("deleteUser")) return { deleted: false, why: "adapter has no deleteUser" };
+    if (!this.user) return { deleted: false, why: "no account to delete" };
+    await this.adapter.deleteUser(this.user);
+    return { deleted: true };
+  }
+}

package/src/engine/geo.mjs

@@ -0,0 +1,59 @@
+// Movement.
+//
+// People don't teleport. Each one gets a looping set of waypoints around their
+// city and walks between them at their own speed, so the location updates your
+// app receives look like a real shift rather than a random-number generator.
+
+const R = 6371; // km
+
+export function haversineKm(a, b) {
+  const dLat = ((b.lat - a.lat) * Math.PI) / 180;
+  const dLng = ((b.lng - a.lng) * Math.PI) / 180;
+  const la1 = (a.lat * Math.PI) / 180;
+  const la2 = (b.lat * Math.PI) / 180;
+  const h = Math.sin(dLat / 2) ** 2 + Math.sin(dLng / 2) ** 2 * Math.cos(la1) * Math.cos(la2);
+  return 2 * R * Math.asin(Math.sqrt(h));
+}
+
+/** A closed loop of waypoints around a centre, unique per seed. */
+export function buildRoute(center, seed, legs = 6, radiusKm = 4) {
+  const pts = [];
+  const jitter = (n) => (Math.sin(seed * 12.9898 + n * 78.233) * 43758.5453) % 1;
+  for (let i = 0; i < legs; i++) {
+    const angle = (i / legs) * Math.PI * 2 + jitter(i);
+    const r = radiusKm * (0.55 + Math.abs(jitter(i + 7)) * 0.75);
+    pts.push({
+      lat: center.lat + (r / 111) * Math.cos(angle),
+      lng: center.lng + (r / (111 * Math.cos((center.lat * Math.PI) / 180))) * Math.sin(angle),
+    });
+  }
+  return pts;
+}
+
+/**
+ * Advance along the route by `km`, returning the new position and leg index.
+ * Wraps around the loop so a shift can run indefinitely.
+ */
+export function advance(route, legIndex, progressKm, km) {
+  let leg = legIndex;
+  let progress = progressKm + km;
+  for (let guard = 0; guard < route.length * 2; guard++) {
+    const from = route[leg % route.length];
+    const to = route[(leg + 1) % route.length];
+    const legKm = haversineKm(from, to);
+    if (progress < legKm || legKm === 0) {
+      const t = legKm === 0 ? 0 : progress / legKm;
+      return {
+        position: {
+          lat: from.lat + (to.lat - from.lat) * t,
+          lng: from.lng + (to.lng - from.lng) * t,
+        },
+        legIndex: leg,
+        progressKm: progress,
+      };
+    }
+    progress -= legKm;
+    leg += 1;
+  }
+  return { position: route[0], legIndex: 0, progressKm: 0 };
+}

package/src/engine/index.mjs

@@ -0,0 +1,4 @@
+export { Agent } from "./agent.mjs";
+export { World } from "./world.mjs";
+export { buildPersonas, chatterFor, replyLine, CITIES } from "./personas.mjs";
+export { advance, buildRoute, haversineKm } from "./geo.mjs";