@botiverse/k-carrier 0.1.0

package/harness/src/artifact-factory/run.ts

@@ -0,0 +1,107 @@
+/**
+ * Guarded command execution — run a binary/command as a real child
+ * process, capturing stdout/stderr and exit code, with a hard timeout
+ * kill (a hang-on-quiesce artifact must never hang the harness).
+ *
+ * This is the process-management primitive the harness needs across the
+ * board: the factory teeth run bare artifacts, the black-box --bin mode
+ * runs the binary's declared commands with args + env. The fake-host
+ * daemon (harness/src/fake-host/) will later standardize the full
+ * spawn/probe/pgrep conventions on top of it.
+ */
+import { spawn } from "node:child_process";
+import { closeSync, openSync, readSync } from "node:fs";
+import * as path from "node:path";
+
+export interface RunResult {
+  stdout: string;
+  stderr: string;
+  /** Exit code, or null if the process was killed by timeout / failed to spawn. */
+  code: number | null;
+  timedOut: boolean;
+}
+
+export interface RunOptions {
+  /** Extra env vars (merged over process.env). */
+  env?: Record<string, string>;
+  /** Hard timeout; the child is SIGKILLed past it. Default 5000ms. */
+  timeoutMs?: number;
+}
+
+/** PATH with the running node's bin dir first (shebang `env node` works). */
+function nodeFirstPath(): string {
+  const nodeBin = path.dirname(process.execPath);
+  return `${nodeBin}${path.delimiter}${process.env.PATH ?? ""}`;
+}
+
+/**
+ * How to spawn an artifact on THIS platform.
+ *
+ * The factory's demo artifact is a single node script whose first line is a
+ * `#!/usr/bin/env node` shebang — one file, one sha256, swappable bytes. On
+ * POSIX the kernel honors the shebang, so the artifact is spawned directly
+ * (which also keeps the exec-bit reality exercised). Windows has no shebang:
+ * spawning the file raises EFTYPE. Routing through the running node binary
+ * keeps the ARTIFACT BYTES identical on every platform — only the execution
+ * convention forks, never the artifact model.
+ *
+ * The sniff is content-based (leading `#!` + "node" on the shebang line), not
+ * extension-based, because the artifact deliberately has no extension. A real
+ * adopter binary on Windows is a PE `.exe` — no `#!` — and spawns directly.
+ * An unreadable file falls through to a direct spawn so missing-target
+ * failure semantics stay exactly what the caller would have seen.
+ */
+export function commandForArtifact(filePath: string, args: string[]): { cmd: string; args: string[] } {
+  if (process.platform !== "win32") return { cmd: filePath, args };
+  try {
+    const fd = openSync(filePath, "r");
+    try {
+      const head = Buffer.alloc(64);
+      const n = readSync(fd, head, 0, head.length, 0);
+      const firstLine = head.subarray(0, n).toString("utf8").split("\n")[0] ?? "";
+      if (firstLine.startsWith("#!") && firstLine.includes("node")) {
+        return { cmd: process.execPath, args: [filePath, ...args] };
+      }
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    // unreadable/missing: spawn directly and let the caller see the real error
+  }
+  return { cmd: filePath, args };
+}
+
+export function runCommand(cmd: string, args: string[], opts: RunOptions = {}): Promise<RunResult> {
+  const routed = commandForArtifact(cmd, args);
+  const child = spawn(routed.cmd, routed.args, {
+    env: { ...process.env, PATH: nodeFirstPath(), ...opts.env },
+  });
+  let stdout = "";
+  let stderr = "";
+  let timedOut = false;
+  child.stdout.on("data", (d: Buffer) => {
+    stdout += String(d);
+  });
+  child.stderr.on("data", (d: Buffer) => {
+    stderr += String(d);
+  });
+  return new Promise<RunResult>((resolve) => {
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, opts.timeoutMs ?? 5000);
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ stdout, stderr, code, timedOut });
+    });
+    child.on("error", () => {
+      clearTimeout(timer);
+      resolve({ stdout, stderr, code: null, timedOut });
+    });
+  });
+}
+
+/** Run a bare artifact with no args (factory teeth convenience). */
+export function runArtifact(artifactPath: string, timeoutMs = 5000): Promise<RunResult> {
+  return runCommand(artifactPath, [], { timeoutMs });
+}

package/harness/src/blackbox.ts

@@ -0,0 +1,284 @@
+/**
+ * Black-box `--bin` mode (harness-design §1.75/§1.76).
+ *
+ * Given a REAL binary (`k-harness --bin ./mytool`), the harness:
+ *  1. loads the binary's `k.target.ts` command declarations (REQUIRED —
+ *     missing = typed FAIL, the harness never guesses commands);
+ *  2. starts a fake-server and publishes a target release via
+ *     artifact-factory (the fixture loop);
+ *  3. drives the binary through its declared commands and asserts from
+ *     OUTSIDE: exit codes, on-disk bytes, next-run version.
+ *
+ * Contract checks are typed FAILs (CONTRACT_* / BLACKBOX_* codes) — they
+ * are mechanical acceptance, NOT tooth-review material (§1.76 ③: commands
+ * that don't run / status output that violates the schema fail directly).
+ *
+ * Config surface: the binary reads its releaseBase from the K_RELEASE_BASE
+ * env var (the demo's contract; real apps wire their own config).
+ */
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { type Profile } from "./teeth/registry.ts";
+import { createSandbox } from "./scenario/sandbox.ts";
+import { buildReceipt, type CheckResult, type Receipt } from "./receipt.ts";
+import { FakeServer } from "./fake-server/server.ts";
+import { ArtifactFactory } from "./artifact-factory/factory.ts";
+import { runCommand } from "./artifact-factory/run.ts";
+import { sha256Hex } from "./fake-server/manifest.ts";
+import { loadTarget, type BlackBoxTarget } from "./target.ts";
+
+export { loadTarget, type BlackBoxTarget, TARGET_FILE } from "./target.ts";
+
+export const DEFAULT_TARGET_VERSION = "2.0.0";
+export const RELEASE_BASE_ENV = "K_RELEASE_BASE";
+
+/** Run a declared command; returns the raw result (contract checks decide). */
+async function runDeclared(binPath: string, args: string[], env: Record<string, string>) {
+  return runCommand(binPath, args, { env });
+}
+
+/** sha256 of the binary's own file (the "on-disk" external assertion). */
+async function fileSha256(binPath: string): Promise<string> {
+  return sha256Hex(new Uint8Array(await fs.readFile(binPath)));
+}
+
+/**
+ * §1.76 ① status output schema: {ProcessEvidence, TxnState,
+ * ConvergenceReport} — the three existing core types, no new schema.
+ * Returns null when valid, else a human-readable reason.
+ */
+export function validateStatusOutput(text: string): string | null {
+  let obj: unknown;
+  try {
+    obj = JSON.parse(text);
+  } catch {
+    return "status output is not valid JSON";
+  }
+  if (typeof obj !== "object" || obj === null) return "status output must be a JSON object";
+  const o = obj as Record<string, unknown>;
+
+  const evidence = o.ProcessEvidence as Record<string, unknown> | undefined;
+  if (!evidence) return "missing ProcessEvidence";
+  if (typeof evidence.version !== "string") return "ProcessEvidence.version must be a string";
+  if (typeof evidence.pid !== "number") return "ProcessEvidence.pid must be a number";
+  if (typeof evidence.startId !== "string") return "ProcessEvidence.startId must be a string";
+
+  const txn = o.TxnState as Record<string, unknown> | undefined;
+  if (!txn) return "missing TxnState";
+  const PHASES = [
+    "idle",
+    "staged",
+    "handing-over",
+    "running-experiment",
+    "readback",
+    "promoted",
+    "rolled-back",
+  ];
+  if (typeof txn.phase !== "string" || !PHASES.includes(txn.phase)) {
+    return `TxnState.phase must be one of ${PHASES.join("/")}`;
+  }
+  if (typeof txn.stableVersion !== "string") return "TxnState.stableVersion must be a string";
+  if (txn.experimentVersion !== null && typeof txn.experimentVersion !== "string") {
+    return "TxnState.experimentVersion must be a string or null";
+  }
+  if (txn.rollbackReason !== null && typeof txn.rollbackReason !== "string") {
+    return "TxnState.rollbackReason must be a string or null";
+  }
+
+  const converge = o.ConvergenceReport as Record<string, unknown> | undefined;
+  if (!converge) return "missing ConvergenceReport";
+  for (const key of ["binaryAtTarget", "hostLifecycleConverged"] as const) {
+    const pred = converge[key] as Record<string, unknown> | null | undefined;
+    // null is a legal, meaningful value for hostLifecycleConverged: the app
+    // declared no OS-lifecycle surface, so nothing was observed. Distinct from
+    // a missing field, which means the status shape itself is wrong.
+    if (pred === null && key === "hostLifecycleConverged") continue;
+    if (!pred) return `ConvergenceReport.${key} missing`;
+    if (typeof pred.passed !== "boolean") return `${key}.passed must be a boolean`;
+    if (typeof pred.source !== "string") return `${key}.source must be a string`;
+    if (typeof pred.observedAtMs !== "number") return `${key}.observedAtMs must be a number`;
+    if (typeof pred.detail !== "object" || pred.detail === null) {
+      return `${key}.detail must be an object`;
+    }
+  }
+  return null;
+}
+
+export interface BinModeOptions {
+  binPath: string;
+  profile: Profile;
+  targetVersion?: string;
+  /** Explicit --target <path>; defaults to <binDir>/k.target.ts. */
+  targetPath?: string;
+  /** Injectable server for tests that want a pre-seeded release store. */
+  server?: FakeServer;
+}
+
+/** The three contract checks of bin mode, run sequentially in one sandbox. */
+export async function runBinMode(opts: BinModeOptions): Promise<Receipt> {
+  const startedAtMs = Date.now();
+  const binPath = path.resolve(opts.binPath);
+  const binDir = path.dirname(binPath);
+  const targetVersion = opts.targetVersion ?? DEFAULT_TARGET_VERSION;
+  const checks: CheckResult[] = [];
+
+  const sb = await createSandbox({ prefix: "k-harness-bin" });
+  const server = opts.server ?? new FakeServer({ storeDir: path.join(sb.dir, "store") });
+  const startedServer = opts.server === undefined;
+  try {
+    // Binary-present guard: a missing binary is a typed FAIL, not a crash.
+    let binStat;
+    try {
+      binStat = await fs.stat(binPath);
+    } catch {
+      checks.push({
+        id: "contract.binary-present",
+        status: "fail",
+        error: "CONTRACT_BIN_MISSING: binary does not exist",
+        durationMs: 0,
+      });
+      return buildReceipt({
+        mode: "bin",
+        profile: opts.profile,
+        target: binPath,
+        checks,
+        startedAtMs,
+        durationMs: Date.now() - startedAtMs,
+      });
+    }
+    checks.push({ id: "contract.binary-present", status: "pass", error: null, durationMs: 0 });
+    // Windows executability is by extension, not file mode (no exec bits);
+    // the mode check is POSIX-only.
+    if (!(binStat.mode & 0o111) && process.platform !== "win32") {
+      checks.push({
+        id: "contract.binary-executable",
+        status: "fail",
+        error: "CONTRACT_BIN_NOT_EXECUTABLE: binary is not executable",
+        durationMs: 0,
+      });
+      return buildReceipt({
+        mode: "bin",
+        profile: opts.profile,
+        target: binPath,
+        checks,
+        startedAtMs,
+        durationMs: Date.now() - startedAtMs,
+      });
+    }
+    checks.push({ id: "contract.binary-executable", status: "pass", error: null, durationMs: 0 });
+
+    if (startedServer) await server.start();
+
+    // Target declaration check — REQUIRED, no guessing: a missing or
+    // invalid k.target.ts is a typed FAIL that stops the run.
+    const tTarget = Date.now();
+    let target: BlackBoxTarget;
+    try {
+      const loadOpts: { binDir: string; explicitPath?: string } = { binDir };
+      if (opts.targetPath !== undefined) loadOpts.explicitPath = opts.targetPath;
+      target = (await loadTarget(loadOpts)).target;
+      checks.push(passCheck("contract.target-declarations", tTarget));
+    } catch (err) {
+      const msg = (err as Error).message;
+      const code = msg.startsWith("BLACKBOX_TARGET_REQUIRED")
+        ? "BLACKBOX_TARGET_REQUIRED"
+        : "BLACKBOX_TARGET_INVALID";
+      checks.push(failCheck("contract.target-declarations", code, msg, tTarget));
+      return buildReceipt({
+        mode: "bin",
+        profile: opts.profile,
+        target: binPath,
+        checks,
+        startedAtMs,
+        durationMs: Date.now() - startedAtMs,
+      });
+    }
+
+    // Publish the target release (artifact-factory closes the loop).
+    const factory = new ArtifactFactory({ cacheDir: path.join(sb.dir, "cache") });
+    await factory.makeRelease({
+      version: targetVersion,
+      behavior: "ok",
+      store: server.store,
+    });
+
+    const env = { ...target.env, [RELEASE_BASE_ENV]: server.url };
+
+    // Contract 1: the declared version command runs and prints a version.
+    {
+      const t0 = Date.now();
+      const r = await runDeclared(binPath, target.version, env);
+      if (r.timedOut) {
+        checks.push(failCheck("contract.version-command", "CONTRACT_CMD_TIMEOUT", "version command timed out", t0));
+      } else if (r.code !== 0) {
+        checks.push(failCheck("contract.version-command", "CONTRACT_CMD_EXIT", `version command exited ${r.code}: ${r.stderr.trim()}`, t0));
+      } else if (r.stdout.trim() === "") {
+        checks.push(failCheck("contract.version-command", "CONTRACT_CMD_EMPTY_OUTPUT", "version command printed nothing", t0));
+      } else {
+        checks.push(passCheck("contract.version-command", t0));
+      }
+    }
+
+    // Contract 2: self upgrade — on-disk bytes change, next run is the target.
+    {
+      const t0 = Date.now();
+      const before = await fileSha256(binPath);
+      const r = await runDeclared(binPath, target.selfUpgrade, env);
+      const after = await fileSha256(binPath);
+      if (r.timedOut) {
+        checks.push(failCheck("contract.self-upgrade", "CONTRACT_CMD_TIMEOUT", "self upgrade timed out", t0));
+      } else if (r.code !== 0) {
+        checks.push(failCheck("contract.self-upgrade", "CONTRACT_CMD_EXIT", `self upgrade exited ${r.code}: ${r.stderr.trim()}`, t0));
+      } else if (after === before) {
+        checks.push(failCheck("contract.self-upgrade", "CONTRACT_UPGRADE_SELF_UNCHANGED", "binary bytes unchanged after upgrade", t0));
+      } else {
+        const v = await runDeclared(binPath, target.version, env);
+        if (v.timedOut || v.code !== 0) {
+          checks.push(failCheck("contract.self-upgrade", "CONTRACT_NEXT_RUN_VERSION", `next-run version command failed (exit ${v.code})`, t0));
+        } else if (v.stdout.trim() === targetVersion) {
+          checks.push(passCheck("contract.self-upgrade", t0));
+        } else {
+          checks.push(failCheck("contract.self-upgrade", "CONTRACT_NEXT_RUN_VERSION", `next run reports ${JSON.stringify(v.stdout.trim())}, expected ${targetVersion}`, t0));
+        }
+      }
+    }
+
+    // Contract 3: status schema — only when the binary declares status.
+    if (target.status) {
+      const t0 = Date.now();
+      const r = await runDeclared(binPath, target.status, env);
+      const schemaError = r.timedOut
+        ? "status command timed out"
+        : r.code === 0
+          ? validateStatusOutput(r.stdout)
+          : `status exited ${r.code}`;
+      if (schemaError) {
+        checks.push(failCheck("contract.status-schema", "CONTRACT_STATUS_SCHEMA", schemaError, t0));
+      } else {
+        checks.push(passCheck("contract.status-schema", t0));
+      }
+    } else {
+      checks.push({ id: "contract.status-schema", status: "na", error: null, durationMs: 0 });
+    }
+  } finally {
+    if (startedServer) await server.stop();
+    await sb.teardown();
+  }
+
+  return buildReceipt({
+    mode: "bin",
+    profile: opts.profile,
+    target: binPath,
+    checks,
+    startedAtMs,
+    durationMs: Date.now() - startedAtMs,
+  });
+}
+
+function passCheck(id: string, startedAtMs: number): CheckResult {
+  return { id, status: "pass", error: null, durationMs: Date.now() - startedAtMs };
+}
+
+function failCheck(id: string, code: string, message: string, startedAtMs: number): CheckResult {
+  return { id, status: "fail", error: `${code}: ${message}`, durationMs: Date.now() - startedAtMs };
+}

package/harness/src/cli.ts

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+/**
+ * k-harness — the harness CLI (harness-design §1.75/§1.76).
+ *
+ *   k-harness --list [--profile <p>]            what cases exist, and where to read one
+ *   k-harness --profile <swap|service>          run the tier-filtered teeth
+ *   k-harness --bin ./mytool [--profile swap]          black-box: drive the real
+ *                                                     binary through its declared
+ *                                                     commands (k.target.ts REQUIRED)
+ *   k-harness --adapter <path> [--profile service]    run the adopter contract subset
+ *                                                     against an external adapter
+ *   k-harness sim [--seed N | --seeds N --start-seed N]  seeded deterministic simulation
+ *   k-harness --json                                  machine-readable receipt
+ *   k-harness --target-version <v>                    version served by --bin mode
+ *   k-harness --target <path>                         explicit target file for --bin
+ *   k-harness --help
+ *
+ * Exit code 0 iff the receipt result is "pass". Receipt: structured, human
+ * + CI readable (harness-design §1.3).
+ */
+import { runProfile, runAdapter } from "./runner.ts";
+import { allTeeth, teethFor, ALL_CAPABILITIES } from "./teeth/registry.ts";
+import "./teeth/index.ts"; // registers all teeth (side effect)
+import { runBinMode, type BinModeOptions } from "./blackbox.ts";
+import { printReceipt } from "./receipt.ts";
+import type { Profile } from "./teeth/registry.ts";
+import { SMOKE_SEEDS, sequentialSeeds } from "./sim/corpus.ts";
+import { runSimulationBatch, type SimulationBatch } from "./sim/run.ts";
+import { recordFailures } from "./sim/record.ts";
+
+const USAGE = `k-harness — K acceptance harness
+
+Usage:
+  k-harness --list [--profile <swap|service>] [--json]
+  k-harness --profile <swap|service> [--json]
+  k-harness --bin <path-to-binary> [--profile swap] [--target-version <v>] [--target <path>] [--json]
+  k-harness --adapter <path-to-module> [--profile service] [--json]
+  k-harness sim [--seed <uint32> | --seeds <count> [--start-seed <uint32>]] [--record-failures <path>] [--json]
+  k-harness --help
+
+Options:
+  --list               list the acceptance cases (teeth) and where each is defined
+  --profile <p>        tier-filtered tooth set (swap | service)
+  --bin <path>         black-box mode: drive a real binary (k.target.ts REQUIRED)
+  --adapter <path>     adapter mode: contract subset against an external adapter
+                       (module default export: (stateDir) => HostDriver)
+  sim                  deterministic simulator; no seed flags = fixed PR smoke corpus
+  --seed <n>           replay one exact uint32 seed (decimal or 0x...)
+  --seeds <n>          run n sequential seeds (nightly/extended mode)
+  --start-seed <n>     first seed for --seeds (default 1)
+  --record-failures <path>
+                       atomically merge failing seeds here (default .k-harness/sim-failures.json)
+  --target <path>      explicit target file for --bin (default <bin-dir>/k.target.ts)
+  --target-version <v> version the --bin fake-server serves (default 2.0.0)
+  --json               print the receipt as JSON (human lines always printed)
+  --help               this message
+`;
+
+function parseArgs(argv: string[]): {
+  list: boolean;
+  profile: Profile | null;
+  binPath: string | null;
+  adapterPath: string | null;
+  targetVersion: string | null;
+  targetPath: string | null;
+  json: boolean;
+  sim: boolean;
+  seed: number | null;
+  seedCount: number | null;
+  startSeed: number | null;
+  failurePath: string;
+} {
+  const out = {
+    list: false,
+    profile: null as Profile | null,
+    binPath: null as string | null,
+    adapterPath: null as string | null,
+    targetVersion: null as string | null,
+    targetPath: null as string | null,
+    json: false,
+    sim: false,
+    seed: null as number | null,
+    seedCount: null as number | null,
+    startSeed: null as number | null,
+    failurePath: ".k-harness/sim-failures.json",
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = (): string => {
+      const v = argv[i + 1];
+      if (v === undefined) throw new Error(`flag ${arg} requires a value`);
+      i += 1;
+      return v;
+    };
+    switch (arg) {
+      case "--profile": {
+        const v = next();
+        if (v !== "swap" && v !== "service" && v !== "service") {
+          throw new Error(`--profile must be swap|service, got ${v}`);
+        }
+        out.profile = v;
+        break;
+      }
+      case "--bin":
+        out.binPath = next();
+        break;
+      case "--adapter":
+        out.adapterPath = next();
+        break;
+      case "sim":
+        out.sim = true;
+        break;
+      case "--seed":
+        out.seed = parseUint32(next(), "--seed");
+        break;
+      case "--seeds":
+        out.seedCount = parsePositiveInteger(next(), "--seeds");
+        break;
+      case "--start-seed":
+        out.startSeed = parseUint32(next(), "--start-seed");
+        break;
+      case "--record-failures":
+        out.failurePath = next();
+        break;
+      case "--target-version":
+        out.targetVersion = next();
+        break;
+      case "--target":
+        out.targetPath = next();
+        break;
+      case "--list":
+        out.list = true;
+        break;
+      case "--json":
+        out.json = true;
+        break;
+      case "--help":
+        return out;
+      default:
+        throw new Error(`unknown flag ${arg}`);
+    }
+  }
+  return out;
+}
+
+function parseUint32(raw: string, flag: string): number {
+  const value = /^0x[0-9a-f]+$/i.test(raw) ? Number.parseInt(raw.slice(2), 16) : Number(raw);
+  if (!Number.isSafeInteger(value) || value < 0 || value > 0xffffffff) {
+    throw new Error(`${flag} must be a uint32, got ${raw}`);
+  }
+  return value >>> 0;
+}
+
+function parsePositiveInteger(raw: string, flag: string): number {
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(`${flag} must be a positive integer, got ${raw}`);
+  }
+  return value;
+}
+
+function printSimulation(batch: SimulationBatch, json: boolean): void {
+  if (json) {
+    console.log(JSON.stringify(batch, null, 2));
+    return;
+  }
+  console.log(`k-harness sim (${batch.summary.total} seeds)`);
+  for (const result of batch.results.filter((item) => item.status === "fail")) {
+    console.log(`  ✖ seed ${result.seed} — ${result.failure}`);
+    console.log(`    replay: ${result.replay}`);
+  }
+  console.log(
+    `faults: delay=${batch.coverage.delay} crash-before=${batch.coverage["crash-before"]} crash-after=${batch.coverage["crash-after"]} fail-before=${batch.coverage["fail-before"]} partial-write=${batch.coverage["partial-write"]} reorder-volatile=${batch.coverage["reorder-volatile"]}`,
+  );
+  console.log(`result: ${batch.result} — ${batch.summary.pass} pass, ${batch.summary.fail} fail`);
+}
+
+/**
+ * Print the case inventory. Answers "which acceptance cases exist and where
+ * do I read one" -- previously only answerable by grepping, because a tooth
+ * is deliberately split across three files (registration / body / self-check)
+ * and none of them is a list.
+ *
+ * `where` is the registration site, captured at registration rather than
+ * declared, so it cannot drift from the code it points at.
+ */
+function listTeeth(profile: Profile | null, json: boolean): void {
+  const teeth = profile ? teethFor(profile, ALL_CAPABILITIES) : allTeeth();
+  if (json) {
+    console.log(JSON.stringify(
+      teeth.map((t) => ({
+        id: t.id,
+        profiles: t.profiles,
+        layers: t.layers,
+        kind: t.kind.kind,
+        mustRed: t.mustRed.map((m) => m.mutate),
+        where: t.registeredAt ?? null,
+      })),
+      null,
+      2,
+    ));
+    return;
+  }
+  const scope = profile ? `profile ${profile}` : "all profiles";
+  console.log(`k-harness: ${teeth.length} acceptance cases (${scope})\n`);
+  for (const t of teeth) {
+    console.log(`${t.id}`);
+    console.log(`  ${t.kind.kind} · layers ${t.layers.join(",")} · profiles ${t.profiles.join(",")}`);
+    console.log(`  defined at ${t.registeredAt ?? "(unknown)"}`);
+    // The must-red list is the honest part: it is what this case claims it
+    // would catch. A case with a vague one is a case that proves little.
+    for (const m of t.mustRed) console.log(`  goes red if: ${m.mutate}`);
+    console.log("");
+  }
+}
+
+async function main(): Promise<number> {
+  const raw = process.argv.slice(2);
+  if (raw.includes("--help")) {
+    console.log(USAGE);
+    return 0;
+  }
+  const args = parseArgs(raw);
+  if (args.list) {
+    listTeeth(args.profile, args.json);
+    return 0;
+  }
+  if (args.sim) {
+    if (args.binPath || args.adapterPath || args.profile !== null) {
+      throw new Error("sim is mutually exclusive with --profile, --bin, and --adapter");
+    }
+    if (args.seed !== null && args.seedCount !== null) {
+      throw new Error("--seed and --seeds are mutually exclusive");
+    }
+    if (args.startSeed !== null && args.seedCount === null) {
+      throw new Error("--start-seed requires --seeds");
+    }
+    let seeds: number[];
+    if (args.seed === null) {
+      seeds =
+        args.seedCount === null
+          ? [...SMOKE_SEEDS]
+          : sequentialSeeds(args.startSeed ?? 1, args.seedCount);
+    } else {
+      seeds = [args.seed];
+    }
+    const batch = await runSimulationBatch(seeds);
+    if (batch.result === "fail") {
+      await recordFailures(args.failurePath, batch.results);
+    }
+    printSimulation(batch, args.json);
+    return batch.result === "pass" ? 0 : 1;
+  }
+  if (args.binPath && args.adapterPath) throw new Error("--bin and --adapter are mutually exclusive");
+  if (!args.binPath && !args.adapterPath && !args.profile) throw new Error("need one of --list, --profile, --bin, --adapter, sim");
+
+  const profile: Profile = args.profile ?? (args.binPath ? "swap" : "service");
+
+  let receipt;
+  if (args.binPath) {
+    const binOpts: BinModeOptions = { binPath: args.binPath, profile };
+    if (args.targetVersion !== null) binOpts.targetVersion = args.targetVersion;
+    if (args.targetPath !== null) binOpts.targetPath = args.targetPath;
+    receipt = await runBinMode(binOpts);
+  } else if (args.adapterPath) {
+    receipt = await runAdapter(profile, args.adapterPath);
+  } else {
+    receipt = await runProfile(profile);
+  }
+  printReceipt(receipt, args.json);
+  return receipt.result === "pass" ? 0 : 1;
+}
+
+try {
+  const code = await main();
+  process.exitCode = code;
+} catch (err) {
+  console.error(`k-harness: ${(err as Error).message}`);
+  console.error(USAGE);
+  process.exitCode = 2;
+}