@gigzen/populace 0.1.0 → 1.0.0

package/src/openapi.mjs

@@ -0,0 +1,322 @@
+// Turn an OpenAPI description into a filled-in adapter.
+//
+// Writing the adapter is the wall. Thirteen methods against someone else's API
+// is the half-hour where a new user either gets a run or gives up, and it is
+// the reason a tool that works has no users outside the company that wrote it.
+// Most serious APIs already describe themselves; this reads that description
+// and fills in what it can.
+//
+// It is deliberately a GUESS, and says so. Every match carries a confidence and
+// the evidence behind it, and anything it is unsure of is left as the template's
+// default with a TODO. A generator that quietly guessed wrong would be worse
+// than no generator: the run would fail and the adapter would look finished.
+//
+// JSON only. Populace has no runtime dependencies and a YAML parser would be
+// the first, for a convenience that `npx js-yaml` covers in one command.
+
+import fs from "node:fs";
+
+/**
+ * What each contract method looks like in a REST API, as scoring signals.
+ *
+ * `verb`  the HTTP method it almost certainly is
+ * `path`  words that appear in the URL, best first
+ * `words` words in the operationId, summary or tags
+ * `avoid` path fragments meaning this is a different endpoint in similar clothes.
+ *         Checked against the PATH ONLY. An earlier version also checked the
+ *         summary, which rejected `POST /conversations` because its description
+ *         read "start a direct message thread" — the correct answer, thrown out
+ *         by a word in its own prose.
+ */
+const SIGNALS = {
+  createUser: {
+    verb: "post",
+    path: ["signup", "sign-up", "admin/users", "register/", "auth/users", "users", "accounts"],
+    words: ["signup", "register", "create user", "create account"],
+    avoid: ["login", "signin", "sign-in", "refresh", "verify", "reset"],
+  },
+  refreshSession: {
+    verb: "post",
+    path: ["refresh", "token/refresh", "auth/token", "token"],
+    words: ["refresh", "renew token", "access token"],
+    avoid: ["revoke", "signup", "register"],
+  },
+  setProfile: {
+    verb: "patch",
+    path: ["profile", "me", "users", "account"],
+    words: ["update profile", "profile", "update user", "edit"],
+    avoid: ["password", "avatar", "delete", "settings/notification"],
+  },
+  deleteUser: {
+    verb: "delete",
+    path: ["users", "account", "me", "profile"],
+    words: ["delete account", "delete user", "remove user", "close account"],
+    avoid: ["post", "comment", "message", "group"],
+  },
+  reportLocation: {
+    verb: "post",
+    path: ["location", "locations", "position", "track", "ping", "telemetry", "gps"],
+    words: ["location", "position", "track", "heartbeat", "ping"],
+    avoid: [],
+  },
+  post: {
+    verb: "post",
+    path: ["posts", "feed", "statuses", "tweets", "entries"],
+    words: ["create post", "new post", "publish", "compose"],
+    avoid: ["comment", "like", "reply", "report"],
+  },
+  recentPostsByOthers: {
+    verb: "get",
+    path: ["feed", "posts", "timeline", "statuses", "entries"],
+    words: ["feed", "timeline", "list posts", "recent"],
+    avoid: ["comment", "like", "my", "mine", "draft"],
+  },
+  like: {
+    verb: "post",
+    path: ["like", "likes", "reactions", "favourite", "favorite", "upvote"],
+    words: ["like", "react", "favourite", "favorite", "upvote"],
+    avoid: ["unlike", "dislike", "remove"],
+  },
+  comment: {
+    verb: "post",
+    path: ["comments", "replies", "comment"],
+    words: ["comment", "reply"],
+    avoid: ["delete", "list", "edit"],
+  },
+  openConversation: {
+    verb: "post",
+    // "/dm" not "dm": as a bare substring it matches "admin", which is how
+    // openConversation ended up pointing at Gitea's POST /admin/cron/{task}.
+    path: ["conversations", "threads", "chats", "/dm", "/dms", "rooms"],
+    words: ["conversation", "thread", "start chat", "direct message", "room"],
+    avoid: ["/messages", "/send", "/read", "/typing"],
+  },
+  sendMessage: {
+    verb: "post",
+    path: ["messages", "message", "send"],
+    words: ["send message", "message", "post message"],
+    avoid: ["/read", "/typing", "/receipts"],
+  },
+  listGroups: {
+    verb: "get",
+    path: ["groups", "orgs", "organizations", "communities", "channels", "teams"],
+    words: ["list groups", "groups", "organizations", "communities", "channels"],
+    avoid: ["member", "join", "leave", "create"],
+  },
+  joinGroup: {
+    verb: "post",
+    path: ["join", "members", "membership", "subscribe"],
+    words: ["join group", "join", "add member", "subscribe"],
+    avoid: ["leave", "remove", "kick", "list"],
+  },
+};
+
+export const CONTRACT_METHODS = Object.keys(SIGNALS);
+
+/** Every operation in the document, flattened. */
+function operations(doc) {
+  const out = [];
+  for (const [path, item] of Object.entries(doc.paths || {})) {
+    if (!item || typeof item !== "object") continue;
+    for (const verb of ["get", "post", "put", "patch", "delete"]) {
+      const op = item[verb];
+      if (!op) continue;
+      out.push({
+        verb,
+        path,
+        operationId: op.operationId || "",
+        summary: op.summary || "",
+        description: (op.description || "").slice(0, 200),
+        tags: op.tags || [],
+      });
+    }
+  }
+  return out;
+}
+
+function score(op, sig) {
+  const path = op.path.toLowerCase();
+  const text = `${op.operationId} ${op.summary} ${op.tags.join(" ")}`.toLowerCase();
+  const why = [];
+  let n = 0;
+
+  for (const bad of sig.avoid) {
+    if (path.includes(bad)) return { n: -1, why: [`excluded: path contains "${bad}"`] };
+  }
+
+  // Path is the strongest signal, and earlier entries are better matches.
+  //
+  // Take the BEST match, never the sum. Summing rewarded long paths that happen
+  // to contain several keywords: against Gitea's real spec,
+  // /pulls/{index}/comments/{id}/replies scored both "comments" and "replies"
+  // and beat /issues/{index}/comments, which is the endpoint a person wants.
+  let bestWord = null;
+  sig.path.forEach((word, i) => {
+    if (!path.includes(word)) return;
+    const points = 10 - Math.min(i, 6);
+    if (!bestWord || points > bestWord.points) bestWord = { word, points };
+  });
+  if (bestWord) {
+    n += bestWord.points;
+    why.push(`path contains "${bestWord.word}"`);
+  }
+
+  if (op.verb === sig.verb) { n += 4; why.push(`${op.verb.toUpperCase()} matches`); }
+  // PUT and PATCH are used interchangeably for updates often enough to allow.
+  else if (sig.verb === "patch" && op.verb === "put") { n += 3; why.push("PUT accepted for PATCH"); }
+  else n -= 3;
+
+  for (const word of sig.words) {
+    if (text.includes(word)) { n += 3; why.push(`described as "${word}"`); }
+  }
+
+  // A shallow path is much likelier to be the main resource than a deep one.
+  // At -1 per segment this was too weak to stop a five-segment sub-resource
+  // outscoring the collection it hangs off.
+  n -= 2 * Math.max(0, op.path.split("/").filter(Boolean).length - 3);
+
+  // Did anything about the URL itself suggest this method? A verb alone must
+  // never be enough: with only that, every GET in a document matched
+  // recentPostsByOthers and listGroups, so a spec containing nothing but
+  // /health produced two confident-looking matches.
+  const hadPathSignal = why.some((w) => w.startsWith("path contains"));
+
+  return { n, why, hadPathSignal };
+}
+
+/**
+ * Match each contract method to its best operation.
+ *
+ * Confidence is deliberately coarse. Anything below `low` is reported as no
+ * match at all rather than dressed up, because a wrong path that looks
+ * confident costs more to debug than an obvious blank.
+ */
+export function match(doc) {
+  const ops = operations(doc);
+  const results = {};
+
+  for (const [method, sig] of Object.entries(SIGNALS)) {
+    let best = null;
+    for (const op of ops) {
+      const { n, why, hadPathSignal } = score(op, sig);
+      // A path signal is mandatory, not just helpful.
+      if (!hadPathSignal || n < 7) continue;
+      if (!best || n > best.n) best = { op, n, why };
+    }
+    const confidence = !best ? "none" : best.n >= 12 ? "high" : best.n >= 9 ? "medium" : "low";
+    results[method] = best && confidence !== "none"
+      ? { ...best, confidence }
+      : { op: null, n: 0, why: ["nothing in the spec looked like this"], confidence: "none" };
+  }
+  return { operationCount: ops.length, results };
+}
+
+/** Read a spec from disk, refusing YAML with a sentence rather than a stack trace. */
+export function load(specPath) {
+  const raw = fs.readFileSync(specPath, "utf8");
+  const looksYaml = /\.ya?ml$/i.test(specPath) || /^\s*(openapi|swagger)\s*:/m.test(raw);
+  if (looksYaml && !raw.trimStart().startsWith("{")) {
+    throw new Error(
+      `${specPath} looks like YAML. Populace has no runtime dependencies, so it does not ship a\n` +
+      `  YAML parser. Convert it once and point at the JSON:\n\n` +
+      `    npx js-yaml ${specPath} > openapi.json\n`,
+    );
+  }
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${specPath} is not valid JSON: ${error.message}`);
+  }
+  if (!doc.paths || typeof doc.paths !== "object") {
+    throw new Error(`${specPath} has no "paths" object, so it is not an OpenAPI description.`);
+  }
+  return doc;
+}
+
+/**
+ * Rewrite the REST template's call lines with the matched paths.
+ *
+ * The template is deliberately one `call(VERB, PATH, ...)` per method, so this
+ * is a targeted substitution rather than code generation. Everything the
+ * template already gets right — error handling, token plumbing, the refusal to
+ * return quietly on failure — is left exactly as it is.
+ */
+/**
+ * The identifier each method already has in scope, for filling path parameters.
+ *
+ * Without this, a matched path like /posts/{postId}/likes was written into the
+ * adapter as a literal string, and the adapter then requested that URL verbatim.
+ * Broken — but broken in a way that looks finished, which is the worst kind.
+ */
+const PATH_VAR = {
+  like: "postId",
+  comment: "postId",
+  sendMessage: "conversationId",
+  joinGroup: "groupId",
+  openConversation: "otherUserId",
+  setProfile: "user.id",
+  deleteUser: "user.id",
+  refreshSession: "user.id",
+};
+
+/** `/posts/{postId}/likes` → a template literal, or the raw string if we cannot fill it. */
+function pathExpression(rawPath, method) {
+  const params = [...rawPath.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
+  if (!params.length) return { code: JSON.stringify(rawPath), unresolved: [] };
+
+  const variable = PATH_VAR[method];
+  if (!variable) return { code: JSON.stringify(rawPath), unresolved: params };
+
+  // One parameter is the common case and safe to fill. Two or more means a
+  // nested resource whose second id this method does not have in scope, so it
+  // is left visible rather than guessed at.
+  if (params.length > 1) return { code: JSON.stringify(rawPath), unresolved: params.slice(1) };
+
+  return { code: "`" + rawPath.replace(/\{[^}]+\}/, "${" + variable + "}") + "`", unresolved: [] };
+}
+
+export function fill(template, matches) {
+  let out = template;
+  const applied = [];
+  const needsHand = [];
+
+  for (const [method, m] of Object.entries(matches)) {
+    if (!m.op) continue;
+    const verb = m.op.verb.toUpperCase();
+    const { code, unresolved } = pathExpression(m.op.path, method);
+    if (unresolved.length) needsHand.push({ method, path: m.op.path, params: unresolved });
+
+    // Match: await call("POST", "/posts", ...) inside `async <method>(`
+    const block = new RegExp(
+      `(async ${method}\\s*\\([^)]*\\)\\s*\\{[\\s\\S]{0,400}?call\\()"[A-Z]+",\\s*"[^"]*"`,
+    );
+    if (!block.test(out)) continue;
+    out = out.replace(block, `$1"${verb}", ${code}`);
+    applied.push({ method, verb, path: m.op.path, confidence: m.confidence, unresolved });
+  }
+
+  // A header that tells the reader exactly how much to trust what follows.
+  const banner = [
+    "/**",
+    " * GENERATED from an OpenAPI description by `populace init --from-openapi`.",
+    " *",
+    " * The paths below are a best guess made by matching endpoint names against",
+    " * the thirteen contract methods. They are a starting point, not a finished",
+    " * adapter: request bodies, field names and response shapes are still the",
+    " * template's defaults and almost certainly need editing.",
+    " *",
+    " * Run `populace smoke` before anything else. It exercises each method once",
+    " * and names the first one that is wrong.",
+    ...(needsHand.length
+      ? ["  *",
+         "  * Paths still containing {braces} need filling by hand - this method has no",
+         "  * variable in scope for them:",
+         ...needsHand.map((h) => `  *   ${h.method}: ${h.path}`)]
+      : []),
+    " */",
+    "",
+  ].join("\n");
+
+  return { source: banner + out, applied, needsHand };
+}

package/src/report.mjs

@@ -6,6 +6,7 @@
 // only shows successes is worse than no report — it manufactures confidence.
 
 import fs from "node:fs";
+import { explainReport, verdictLine } from "./explain.mjs";
 import path from "node:path";
 import { summarise } from "./instrument.mjs";
 import { coverageOf } from "./contract.mjs";
@@ -15,6 +16,22 @@ import { VERSION } from "./version.mjs";
 const pct = (n) => `${(n * 100).toFixed(1)}%`;
 const ms = (n) => (n >= 1000 ? `${(n / 1000).toFixed(1)}s` : `${Math.round(n)}ms`);
 
+/** Break a sentence onto lines of at most `width`, without splitting words. */
+function wrap(text, width) {
+  const lines = [];
+  let line = "";
+  for (const word of String(text).split(/\s+/).filter(Boolean)) {
+    if (line && line.length + 1 + word.length > width) {
+      lines.push(line);
+      line = word;
+    } else {
+      line = line ? `${line} ${word}` : word;
+    }
+  }
+  if (line) lines.push(line);
+  return lines;
+}
+
 export function buildReport({ config, adapter, world, metrics, teardown, startedAt }) {
   const api = summarise(metrics);
   const coverage = coverageOf(adapter);
@@ -219,6 +236,26 @@ export function renderReport(report) {
   }
   L.push("");
 
+  // What broke, why, and the fix - the thing a report is actually for. Rules
+  // only; anything unrecognised says so rather than inventing a cause.
+  const explained = explainReport(report);
+  if (explained.length) {
+    L.push(`  WHAT TO DO`);
+    L.push(`    ${verdictLine(explained)}`);
+    L.push("");
+    const BLAME = { app: "YOUR APP", environment: "THE PLATFORM", harness: "THE TEST CLIENT", unknown: "UNKNOWN" };
+    for (const e of explained.slice(0, 4)) {
+      L.push(`    [${BLAME[e.blame]}]  ${e.method} × ${e.count}`);
+      L.push(`      ${e.headline}`);
+      for (const line of wrap(e.why, 72)) L.push(`      ${line}`);
+      if (e.fix) {
+        L.push(`      Fix:`);
+        for (const line of wrap(e.fix, 70)) L.push(`        ${line}`);
+      }
+      L.push("");
+    }
+  }
+
   if (report.coverage.notTested.length) {
     L.push(`  NOT TESTED — adapter implements ${report.coverage.label}`);
     for (const c of report.coverage.notTested) {

package/src/selftest.mjs

@@ -9,6 +9,9 @@
 // that the failures are CAUGHT, grouped, and reflected in the verdict.
 
 import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { execFile } from "node:child_process";
 import { World } from "./engine/world.mjs";
 import { Agent } from "./engine/agent.mjs";
@@ -25,6 +28,10 @@ import {
 import { buildReport, renderReport } from "./report.mjs";
 import { canSignInOnly, CONTRACT_METHODS, coverageOf, isStub } from "./contract.mjs";
 import { diagnose } from "./diagnose.mjs";
+import { fill, match } from "./openapi.mjs";
+import { explain, explainReport, verdictLine } from "./explain.mjs";
+import { explainWithAI, isConfigured } from "./ai.mjs";
+import { checksDisabled, compare, latestVersion } from "./update.mjs";
 
 let failed = 0;
 const pending = [];
@@ -1355,6 +1362,250 @@ check("the report renders without throwing", () => {
   });
 }
 
+// --- 9. the OpenAPI adapter generator -------------------------------------
+//
+// The generator is a guess by design, so what has to hold is not "it is always
+// right" but "it never produces something broken that looks finished".
+
+const SPEC = {
+  openapi: "3.0.0",
+  paths: {
+    "/auth/signup": { post: { operationId: "registerUser", summary: "Register a new account" } },
+    "/auth/login": { post: { operationId: "login", summary: "Sign in" } },
+    "/auth/token/refresh": { post: { operationId: "refreshToken", summary: "Refresh the access token" } },
+    "/users/me": {
+      patch: { operationId: "updateProfile", summary: "Update profile" },
+      delete: { operationId: "deleteAccount", summary: "Delete account" },
+    },
+    "/locations": { post: { operationId: "reportPosition", summary: "Report current position" } },
+    "/posts": {
+      get: { operationId: "listFeed", summary: "Recent posts timeline" },
+      post: { operationId: "createPost", summary: "Create a post" },
+    },
+    "/posts/{postId}/likes": { post: { operationId: "likePost", summary: "Like a post" } },
+    "/posts/{postId}/comments": { post: { operationId: "addComment", summary: "Reply to a post" } },
+    "/conversations": { post: { operationId: "startConversation", summary: "Start a direct message thread" } },
+    "/conversations/{id}/messages": { post: { operationId: "sendMessage", summary: "Send a message" } },
+    "/groups": { get: { operationId: "listGroups", summary: "List groups" } },
+    "/groups/{id}/members": { post: { operationId: "joinGroup", summary: "Join a group" } },
+  },
+};
+
+check("the generator matches a conventional REST spec", () => {
+  const { results } = match(SPEC);
+  const expected = {
+    createUser: "POST /auth/signup",
+    refreshSession: "POST /auth/token/refresh",
+    setProfile: "PATCH /users/me",
+    deleteUser: "DELETE /users/me",
+    reportLocation: "POST /locations",
+    post: "POST /posts",
+    recentPostsByOthers: "GET /posts",
+    like: "POST /posts/{postId}/likes",
+    comment: "POST /posts/{postId}/comments",
+    openConversation: "POST /conversations",
+    sendMessage: "POST /conversations/{id}/messages",
+    listGroups: "GET /groups",
+    joinGroup: "POST /groups/{id}/members",
+  };
+  for (const [method, want] of Object.entries(expected)) {
+    const r = results[method];
+    const got = r.op ? `${r.op.verb.toUpperCase()} ${r.op.path}` : "no match";
+    if (got !== want) throw new Error(`${method}: matched ${got}, expected ${want}`);
+  }
+});
+
+check("a summary's own words never exclude the right endpoint", () => {
+  // POST /conversations is described as "start a direct message thread". An
+  // earlier version checked the `avoid` list against the summary as well as the
+  // path, so the word "message" rejected the one correct answer.
+  const { results } = match(SPEC);
+  if (results.openConversation.op?.path !== "/conversations") {
+    throw new Error("openConversation was excluded by a word in its own description");
+  }
+  // And sendMessage lives UNDER conversations, so "conversation" cannot exclude it.
+  if (results.sendMessage.op?.path !== "/conversations/{id}/messages") {
+    throw new Error("sendMessage was excluded by its parent resource's name");
+  }
+});
+
+check("a generated adapter never leaves a literal {param} in a call", () => {
+  // A path written in as a literal string would make the adapter request
+  // "/posts/{postId}/likes" verbatim: broken, and looking finished.
+  const template = fs.readFileSync(
+    path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "adapters", "template-rest.mjs"),
+    "utf8",
+  );
+  const { source } = fill(template, match(SPEC).results);
+  const leftovers = source.match(/call\("[A-Z]+", "[^"]*\{[a-zA-Z_]+\}/g);
+  if (leftovers) throw new Error(`unfilled path parameters: ${leftovers.join(", ")}`);
+  if (!source.includes("`/posts/${postId}/likes`")) {
+    throw new Error("the path parameter was not turned into a template literal");
+  }
+});
+
+check("a spec with nothing recognisable produces no false matches", () => {
+  const { results } = match({ paths: { "/health": { get: { operationId: "health" } } } });
+  const matched = Object.values(results).filter((r) => r.op).length;
+  if (matched > 0) throw new Error(`${matched} method(s) matched a spec containing only /health`);
+});
+
+// --- 10. failure explanation ----------------------------------------------
+//
+// The judgement that matters is the first one: was this the application at all?
+// Getting that wrong in either direction is worse than saying nothing.
+
+check("a transport failure is never blamed on the application", () => {
+  for (const msg of ["TypeError: fetch failed", "socket hang up", "ECONNRESET", "UND_ERR_CONNECT_TIMEOUT"]) {
+    const e = explain(msg);
+    if (e.blame !== "harness") throw new Error(`"${msg}" was blamed on ${e.blame}, not the harness`);
+  }
+});
+
+check("a provider quota is not the app's fault", () => {
+  const e = explain("Invalid login credentials (signup first failed: Request rate limit reached)");
+  if (e.blame !== "environment") throw new Error(`rate limit blamed on ${e.blame}`);
+});
+
+check("permission and constraint failures are the app's", () => {
+  for (const [msg, rule] of [
+    ["permission denied for table profiles", "rls-denied"],
+    ["duplicate key value violates unique constraint \"post_likes_pkey\"", "duplicate-key"],
+    ["insert violates foreign key constraint", "foreign-key"],
+  ]) {
+    const e = explain(msg);
+    if (e.blame !== "app") throw new Error(`"${msg}" blamed on ${e.blame}`);
+    if (e.rule !== rule) throw new Error(`"${msg}" matched ${e.rule}, expected ${rule}`);
+  }
+});
+
+check("the upsert-under-RLS bug gets its own explanation", () => {
+  // The specific mistake behind five of the first defects Populace ever found.
+  // Plain "permission denied" is true but useless; this names the cause.
+  const e = explain("permission denied for table profiles (upsert / ON CONFLICT DO UPDATE)");
+  if (e.rule !== "rls-upsert") throw new Error(`matched ${e.rule}, expected the upsert-specific rule`);
+  if (!/cannot upsert a column you cannot select/i.test(e.fix)) {
+    throw new Error("the fix does not state the actual rule");
+  }
+});
+
+check("an unrecognised failure says so rather than inventing a cause", () => {
+  const e = explain("Xyzzy plugh 42 frobnicated");
+  if (e.rule !== "none") throw new Error(`invented rule ${e.rule}`);
+  if (e.blame !== "unknown") throw new Error(`claimed blame "${e.blame}" for an unknown error`);
+});
+
+check("unclassified failures are never counted as 'not the app'", () => {
+  // The dangerous rounding: reporting "no application failures" when some
+  // failures were simply not understood turns "we cannot tell" into an
+  // all-clear.
+  const line = verdictLine([{ blame: "harness", count: 5 }, { blame: "unknown", count: 3 }]);
+  if (/^No application failures/.test(line)) {
+    throw new Error(`claimed a clean app while 3 failures were unclassified: "${line}"`);
+  }
+  if (!/could not be classified/.test(line)) throw new Error(`unclassified failures not mentioned: "${line}"`);
+});
+
+check("explanations are ordered by how much they happened", () => {
+  const ex = explainReport({
+    api: { methods: [
+      { method: "a", errors: [{ message: "fetch failed", count: 2 }] },
+      { method: "b", errors: [{ message: "fetch failed", count: 90 }] },
+    ] },
+  });
+  if (ex[0].method !== "b") throw new Error("the 90-count failure was not listed first");
+});
+
+// --- 11. the model layer is an enhancement, never a dependency ------------
+//
+// A report is complete and useful without it. Everything here is about the
+// model layer being unable to make things worse.
+
+check("without a key, the model layer returns nothing and says nothing", async () => {
+  const before = process.env.ANTHROPIC_API_KEY;
+  delete process.env.ANTHROPIC_API_KEY;
+  try {
+    if (isConfigured({})) throw new Error("reported configured with no key anywhere");
+    const out = await explainWithAI([{ method: "post", message: "something odd", count: 1 }], { config: {} });
+    if (out.length) throw new Error("returned explanations without a key");
+  } finally {
+    if (before !== undefined) process.env.ANTHROPIC_API_KEY = before;
+  }
+});
+
+check("nothing to explain means no request is made", async () => {
+  // Guards against a run with zero failures still costing an API call.
+  const out = await explainWithAI([], { config: { ai: { apiKey: "sk-ant-would-be-wrong-to-use" } } });
+  if (out.length) throw new Error("returned explanations for an empty list");
+});
+
+check("a key in config is found as well as one in the environment", () => {
+  const before = process.env.ANTHROPIC_API_KEY;
+  delete process.env.ANTHROPIC_API_KEY;
+  try {
+    if (!isConfigured({ ai: { apiKey: "sk-ant-test" } })) {
+      throw new Error("a key in populace.config.mjs was not found");
+    }
+  } finally {
+    if (before !== undefined) process.env.ANTHROPIC_API_KEY = before;
+  }
+});
+
+check("rule explanations are never labelled as coming from the model", () => {
+  // The provenance has to survive, or a reader cannot tell which explanations
+  // were deterministic and which were generated.
+  const e = explain("permission denied for table profiles");
+  if (e.source === "model") throw new Error("a rule explanation claimed to be from the model");
+  if (e.rule === "model") throw new Error("a rule explanation used the model's rule name");
+});
+
+// --- 12. the update check ------------------------------------------------
+
+check("version comparison orders releases correctly", () => {
+  const cases = [
+    ["1.0.0", "1.0.0", 0], ["1.0.1", "1.0.0", 1], ["1.0.0", "1.0.1", -1],
+    ["1.10.0", "1.9.0", 1], ["2.0.0", "1.99.99", 1], ["1.0.0", "0.1.0", 1],
+    ["1.0.0-beta.1", "1.0.0", 0],   // pre-release tags are ignored, not parsed
+  ];
+  for (const [a, b, want] of cases) {
+    const got = compare(a, b);
+    if (got !== want) throw new Error(`compare("${a}","${b}") = ${got}, expected ${want}`);
+  }
+});
+
+check("10.0.0 is newer than 9.0.0, not older", () => {
+  // String comparison would say "10" < "9". Numeric parsing is the whole point.
+  if (compare("10.0.0", "9.0.0") !== 1) throw new Error("compared version parts as strings");
+});
+
+check("CI switches the update check off without being asked", async () => {
+  // A build server should not make an outbound call nobody requested, and its
+  // logs should not carry an upgrade nag.
+  const beforeCI = process.env.CI;
+  process.env.CI = "true";
+  try {
+    if (!checksDisabled()) throw new Error("update checks stayed on under CI");
+    const v = await latestVersion();
+    if (v !== null) throw new Error("a request was made under CI");
+  } finally {
+    if (beforeCI === undefined) delete process.env.CI; else process.env.CI = beforeCI;
+  }
+});
+
+check("POPULACE_NO_UPDATE_CHECK switches it off", () => {
+  const before = process.env.POPULACE_NO_UPDATE_CHECK;
+  const beforeCI = process.env.CI;
+  delete process.env.CI;
+  process.env.POPULACE_NO_UPDATE_CHECK = "1";
+  try {
+    if (!checksDisabled()) throw new Error("the opt-out was ignored");
+  } finally {
+    if (before === undefined) delete process.env.POPULACE_NO_UPDATE_CHECK;
+    else process.env.POPULACE_NO_UPDATE_CHECK = before;
+    if (beforeCI !== undefined) process.env.CI = beforeCI;
+  }
+});
+
 // Async checks must settle before the total is printed. Exiting synchronously
 // would report "all passed" while an async assertion was still in flight — a
 // test suite lying about its own result, in a product whose entire argument is