postgresai 0.16.0-dev.1 → 0.16.0-dev.10

package/test/init.integration.test.ts

@@ -407,12 +407,14 @@ describe.skipIf(skipTests)("integration: prepare-db", () => {
     }
   }, { timeout: TEST_TIMEOUT });
 
-  // 60s timeout for PostgreSQL startup + multiple SQL queries in slow CI
-  test("explain_generic validates input and prevents SQL injection", async () => {
+  // Security regression for #387: explain_generic was a SECURITY DEFINER helper that
+  // ran caller-supplied SQL through EXPLAIN. The planner folds IMMUTABLE/STABLE functions
+  // at plan time in the definer's (superuser) context, making it an RCE/data-exfil vector.
+  // It has been removed; prepare-db must NOT create it.
+  test("explain_generic is not created by prepare-db (RCE helper removed, #387)", async () => {
     pg = await createTempPostgres();
 
     try {
-      // Run init first
       {
         const r = runCliInit([pg.adminUri, "--password", "pw1", "--skip-optional-permissions"]);
         expect(r.status).toBe(0);
@@ -422,82 +424,10 @@ describe.skipIf(skipTests)("integration: prepare-db", () => {
       await c.connect();
 
       try {
-        // Check PostgreSQL version - generic_plan requires 16+
-        const versionRes = await c.query("show server_version_num");
-        const version = parseInt(versionRes.rows[0].server_version_num, 10);
-
-        if (version < 160000) {
-          // Skip this test on older PostgreSQL versions
-          console.log("Skipping explain_generic tests: requires PostgreSQL 16+");
-          return;
-        }
-
-        // Test 1: Empty query should be rejected
-        await expect(
-          c.query("select postgres_ai.explain_generic('')")
-        ).rejects.toThrow(/query cannot be empty/);
-
-        // Test 2: Null query should be rejected
-        await expect(
-          c.query("select postgres_ai.explain_generic(null)")
-        ).rejects.toThrow(/query cannot be empty/);
-
-        // Test 3: Multiple statements (semicolon in middle) should be rejected
-        await expect(
-          c.query("select postgres_ai.explain_generic('select 1; select 2')")
-        ).rejects.toThrow(/semicolon|multiple statements/i);
-
-        // Test 4: Trailing semicolon should be stripped and work
-        {
-          const res = await c.query("select postgres_ai.explain_generic('select 1;') as result");
-          expect(res.rows[0].result).toBeTruthy();
-          expect(res.rows[0].result).toMatch(/Result/i);
-        }
-
-        // Test 5: Valid query should work
-        {
-          const res = await c.query("select postgres_ai.explain_generic('select $1::int', 'text') as result");
-          expect(res.rows[0].result).toBeTruthy();
-        }
-
-        // Test 6: JSON format should work
-        {
-          const res = await c.query("select postgres_ai.explain_generic('select 1', 'json') as result");
-          const plan = JSON.parse(res.rows[0].result);
-          expect(Array.isArray(plan)).toBe(true);
-          expect(plan[0].Plan).toBeTruthy();
-        }
-
-        // Test 7: Whitespace-only query should be rejected
-        await expect(
-          c.query("select postgres_ai.explain_generic('   ')")
-        ).rejects.toThrow(/query cannot be empty/);
-
-        // Test 8: Semicolon in string literal is rejected (documented limitation)
-        // Note: This is a known limitation - the simple heuristic cannot parse SQL strings
-        await expect(
-          c.query("select postgres_ai.explain_generic('select ''hello;world''')")
-        ).rejects.toThrow(/semicolon/i);
-
-        // Test 9: SQL comments should work (no semicolons)
-        {
-          const res = await c.query("select postgres_ai.explain_generic('select 1 -- comment') as result");
-          expect(res.rows[0].result).toBeTruthy();
-        }
-
-        // Test 10: Escaped quotes should work (no semicolons)
-        {
-          const res = await c.query("select postgres_ai.explain_generic('select ''test''''s value''') as result");
-          expect(res.rows[0].result).toBeTruthy();
-        }
-
-        // Test 11: Case-insensitive format parameter
-        {
-          const res = await c.query("select postgres_ai.explain_generic('select 1', 'JSON') as result");
-          const plan = JSON.parse(res.rows[0].result);
-          expect(Array.isArray(plan)).toBe(true);
-        }
-
+        const res = await c.query(
+          "select count(*)::int as n from pg_proc where proname = 'explain_generic' and pronamespace = (select oid from pg_namespace where nspname = 'postgres_ai')"
+        );
+        expect(res.rows[0].n).toBe(0);
       } finally {
         await c.end();
       }

package/test/joe.cli.test.ts

@@ -0,0 +1,469 @@
+import { describe, test, expect } from "bun:test";
+import { resolve } from "path";
+import { mkdtempSync } from "fs";
+import { tmpdir } from "os";
+// Importing the bin module is safe: argv parsing is gated on `import.meta.main`
+// (same pattern as monitoring.test.ts).
+import { inferCommandFromResult } from "../bin/postgres-ai";
+
+// Sync runner for OFFLINE tests only (help / fail-fast). Never use it for a test
+// that round-trips the in-process Bun.serve: spawnSync blocks the JS event loop, so
+// the fake server can't answer and the two deadlock (see runCliAsync).
+function runCli(args: string[], env: Record<string, string> = {}) {
+  const cliPath = resolve(import.meta.dir, "..", "bin", "postgres-ai.ts");
+  const bunBin = typeof process.execPath === "string" && process.execPath.length > 0 ? process.execPath : "bun";
+  const result = Bun.spawnSync([bunBin, cliPath, ...args], {
+    env: { ...process.env, ...env },
+  });
+  return {
+    status: result.exitCode,
+    stdout: new TextDecoder().decode(result.stdout),
+    stderr: new TextDecoder().decode(result.stderr),
+  };
+}
+
+// Async runner for tests that hit the fake server — keeps the event loop free.
+async function runCliAsync(args: string[], env: Record<string, string> = {}) {
+  const cliPath = resolve(import.meta.dir, "..", "bin", "postgres-ai.ts");
+  const bunBin = typeof process.execPath === "string" && process.execPath.length > 0 ? process.execPath : "bun";
+  const proc = Bun.spawn([bunBin, cliPath, ...args], {
+    env: { ...process.env, ...env },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [status, stdout, stderr] = await Promise.all([
+    proc.exited,
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  return { status, stdout, stderr };
+}
+
+/** Isolate config so tests never touch real user state; a shared dir threads sessions. */
+function isolatedEnv(extra: Record<string, string> = {}) {
+  const cfgHome = mkdtempSync(resolve(tmpdir(), "joe-cli-test-"));
+  return { XDG_CONFIG_HOME: cfgHome, HOME: cfgHome, ...extra };
+}
+
+interface RecordedRequest {
+  pathname: string;
+  body: Record<string, unknown>;
+}
+
+/**
+ * Fake PostgREST server for the Joe rpcs (backend not built yet). A `plan` on a
+ * project whose id is COLD_PROJECT stays `running` (to exercise the resume path);
+ * project id 999 returns the ai_enabled=false PT403; everything else completes.
+ */
+function startFakeApi() {
+  const requests: RecordedRequest[] = [];
+  const COLD_PROJECT = 77;
+  let nextId = 4711;
+  const commands = new Map<string, { command: string; projectId: number }>();
+
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    async fetch(req) {
+      const url = new URL(req.url);
+      const bodyText = await req.text();
+      let body: Record<string, unknown> = {};
+      try {
+        body = bodyText ? (JSON.parse(bodyText) as Record<string, unknown>) : {};
+      } catch {
+        body = {};
+      }
+      requests.push({ pathname: url.pathname, body });
+
+      const respond = (obj: unknown, status = 200): Response =>
+        new Response(JSON.stringify(obj), { status, headers: { "Content-Type": "application/json" } });
+
+      if (req.method === "POST" && url.pathname.endsWith("/rpc/projects_list")) {
+        return respond([
+          { id: 12, alias: "main-db", name: "Main DB", label: "Main DB", joe_api_v2_enabled: true, tunnel_ready: true },
+          { id: 77, alias: "cold-db", name: "Cold DB", joe_ready: true, tunnel: true },
+        ]);
+      }
+
+      if (req.method === "POST" && url.pathname.endsWith("/rpc/joe_command_submit")) {
+        const projectId = Number(body.project_id);
+        if (projectId === 999) {
+          return respond({ message: "AI features disabled for this org — enable in AI Assistant Settings" }, 403);
+        }
+        const commandId = String(nextId++);
+        commands.set(commandId, { command: String(body.command), projectId });
+        // Echo the incoming session_id, or hand back a fresh one for a null session.
+        const sessionId = body.session_id != null ? String(body.session_id) : "88";
+        return respond({ command_id: commandId, session_id: sessionId, status: "queued" });
+      }
+
+      if (req.method === "POST" && url.pathname.endsWith("/rpc/joe_command_status")) {
+        const commandId = String(body.command_id);
+        const cmd = commands.get(commandId);
+        const status = cmd && cmd.projectId === COLD_PROJECT ? "running" : "done";
+        return respond({ command_id: commandId, status, error: null });
+      }
+
+      if (req.method === "POST" && url.pathname.endsWith("/rpc/joe_command_result")) {
+        const commandId = String(body.command_id);
+        if (commandId === "424242") {
+          // A server-side terminal timeout (the dispatcher gave up on the command).
+          return respond({ command_id: commandId, status: "timed_out", error: null });
+        }
+        if (commandId === "424243") {
+          // A terminal error result (sanitized message, per joe_error_sanitize).
+          return respond({ command_id: commandId, command: "exec", status: "error", error: "Query error" });
+        }
+        const cmd = commands.get(commandId);
+        if (cmd?.command === "exec") {
+          return respond({ command_id: commandId, command: "exec", status: "done", row_count: 0, result_rows: [], notices: ["CREATE INDEX"], error: null });
+        }
+        return respond({
+          command_id: commandId,
+          status: "done",
+          queryid: "7712349901234567890",
+          plan_fingerprint: "a1b2c3d4",
+          plan_text: "Seq Scan on users  (cost=0.00..48210.00 rows=1 width=812)",
+          plan_json: { Plan: { "Node Type": "Seq Scan", "Relation Name": "users" } },
+          error: null,
+        });
+      }
+
+      return new Response("not found", { status: 404 });
+    },
+  });
+
+  const baseUrl = `http://${server.hostname}:${server.port}/api/general`;
+  return { baseUrl, requests, stop: () => server.stop(true) };
+}
+
+describe("CLI Joe command surface (grouped under `pgai joe …`)", () => {
+  test("top-level help lists the joe + dblab groups and top-level projects", () => {
+    const r = runCli(["--help"], isolatedEnv());
+    const out = `${r.stdout}\n${r.stderr}`;
+    // Joe verbs are grouped under `joe`; DBLab verbs under `dblab`. `projects`
+    // stays top-level (org-level, not a Joe endpoint).
+    for (const group of ["joe", "dblab", "projects"]) {
+      expect(out).toContain(group);
+    }
+  });
+
+  test("pgai joe --help lists all the Joe verbs", () => {
+    const r = runCli(["joe", "--help"], isolatedEnv());
+    expect(r.status).toBe(0);
+    const out = `${r.stdout}\n${r.stderr}`;
+    for (const verb of ["plan", "explain", "exec", "hypo", "activity", "terminate", "reset", "describe", "result", "status", "history"]) {
+      expect(out).toContain(verb);
+    }
+  });
+
+  test("pgai joe history (M1b) is recognized and degrades cleanly", () => {
+    // The brief's §2 documents `pgai joe history "users email" --project 12`, but the
+    // history-search backend is M1b/not built. The command must be recognized (NOT a
+    // Commander "unknown command") and exit 1 with an informative pending message.
+    const r = runCli(["joe", "history", "users email", "--project", "12"], isolatedEnv({ PGAI_API_KEY: "k" }));
+    expect(r.status).toBe(1);
+    const out = `${r.stdout}\n${r.stderr}`;
+    expect(out).toContain("not available yet");
+    expect(out).toContain("M1b");
+    expect(out).not.toContain("unknown command");
+  });
+
+  test("pgai projects prints the brief's table", async () => {
+    const api = startFakeApi();
+    try {
+      const r = await runCliAsync(["projects"], isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl }));
+      expect(r.status).toBe(0);
+      expect(r.stdout).toContain("PROJECT_ID");
+      expect(r.stdout).toContain("ALIAS");
+      expect(r.stdout).toContain("JOE");
+      expect(r.stdout).toContain("TUNNEL");
+      expect(r.stdout).toContain("main-db");
+      expect(r.stdout).toContain("ready");
+      const listReq = api.requests.find((x) => x.pathname.endsWith("/rpc/projects_list"));
+      expect(listReq).toBeDefined();
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("pgai joe plan --project 12 submits command='plan' and prints the plan", async () => {
+    const api = startFakeApi();
+    try {
+      const r = await runCliAsync(
+        ["joe", "plan", "select * from users where email = 'x@acme.io'", "--project", "12"],
+        isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
+      );
+      expect(r.status).toBe(0);
+      expect(r.stdout).toContain("Seq Scan on users");
+      // client-side plan flag
+      expect(r.stdout).toContain("⚑");
+      const submit = api.requests.find((x) => x.pathname.endsWith("/rpc/joe_command_submit"));
+      expect(submit?.body.command).toBe("plan");
+      expect(submit?.body.project_id).toBe(12);
+      // numeric project => no projects_list lookup
+      expect(api.requests.some((x) => x.pathname.endsWith("/rpc/projects_list"))).toBe(false);
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("pgai joe plan --project main-db resolves the alias via projects_list", async () => {
+    const api = startFakeApi();
+    try {
+      const r = await runCliAsync(
+        ["joe", "plan", "select 1", "--project", "main-db"],
+        isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
+      );
+      expect(r.status).toBe(0);
+      expect(api.requests.some((x) => x.pathname.endsWith("/rpc/projects_list"))).toBe(true);
+      const submit = api.requests.find((x) => x.pathname.endsWith("/rpc/joe_command_submit"));
+      expect(submit?.body.project_id).toBe(12);
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("optimize loop: joe plan then joe exec reuse the same session on one project", async () => {
+    const api = startFakeApi();
+    const env = isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl });
+    try {
+      // First command starts a fresh session; the server hands back session 88.
+      const first = await runCliAsync(["joe", "plan", "select 1", "--project", "12", "--new-session"], env);
+      expect(first.status).toBe(0);
+      // Second command auto-reuses the stored session (88) on the same project.
+      const second = await runCliAsync(["joe", "exec", "create index on users (email)", "--project", "12"], env);
+      expect(second.status).toBe(0);
+      expect(second.stdout).toContain("CREATE INDEX");
+
+      const submits = api.requests.filter((x) => x.pathname.endsWith("/rpc/joe_command_submit"));
+      expect(submits.length).toBe(2);
+      // The re-plan/exec threads the session id returned by the first submit.
+      expect(submits[0].body.session_id).toBeNull(); // --new-session
+      expect(submits[1].body.session_id).toBe("88");
+      expect(submits[1].body.command).toBe("exec");
+      // exec mints a stable idempotency key.
+      expect(typeof submits[1].body.idempotency_key).toBe("string");
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("cold clone exceeds the budget -> resume handle (exit 0), then pgai joe result", async () => {
+    const api = startFakeApi();
+    const env = isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl });
+    try {
+      // project 77 (COLD) stays `running`; --budget 0 forces immediate resume.
+      const r = await runCliAsync(["joe", "plan", "select 1", "--project", "77", "--budget", "0"], env);
+      expect(r.status).toBe(0);
+      expect(r.stdout).toContain("resume:");
+      expect(r.stdout).toMatch(/pgai joe result \d+/);
+
+      const match = r.stdout.match(/pgai joe result (\d+)/);
+      const commandId = match ? match[1] : "";
+      expect(commandId).not.toBe("");
+
+      const resumed = await runCliAsync(["joe", "result", commandId], env);
+      expect(resumed.status).toBe(0);
+      expect(resumed.stdout).toContain("Seq Scan on users");
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("pgai joe result exits 1 for a server-side timed_out command", async () => {
+    // `joe result` must match the one-shot path (printJoeOutcome): a terminal
+    // `timed_out` is a non-result — a script doing `pgai joe result $id && next`
+    // must NOT proceed.
+    const api = startFakeApi();
+    try {
+      const r = await runCliAsync(
+        ["joe", "result", "424242"],
+        isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
+      );
+      expect(r.status).toBe(1);
+      expect(r.stderr).toContain("timed out");
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("pgai joe result --json exits 1 for terminal error/timed_out (JSON still printed)", async () => {
+    // --json keeps the machine-readable body on stdout, but the exit contract
+    // must match the human output and the one-shot printJoeOutcome path: a
+    // terminal failure is a non-result.
+    const api = startFakeApi();
+    const env = isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl });
+    try {
+      const timedOut = await runCliAsync(["joe", "result", "424242", "--json"], env);
+      expect(timedOut.status).toBe(1);
+      expect((JSON.parse(timedOut.stdout) as { status: string }).status).toBe("timed_out");
+
+      const errored = await runCliAsync(["joe", "result", "424243", "--json"], env);
+      expect(errored.status).toBe(1);
+      expect((JSON.parse(errored.stdout) as { status: string }).status).toBe("error");
+
+      // Non-json error path: sanitized message on stderr, exit 1.
+      const human = await runCliAsync(["joe", "result", "424243"], env);
+      expect(human.status).toBe(1);
+      expect(human.stderr).toContain("Query error");
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("budget-expiry resume hint reports the ACTUAL --budget, not the hardcoded default", async () => {
+    const api = startFakeApi();
+    try {
+      // Project 77 (COLD) stays `running`; --budget 0 expires immediately. The
+      // hint must say "budget 0s reached" — not the DEFAULT_BUDGET_MS 25s.
+      const r = await runCliAsync(
+        ["joe", "plan", "select 1", "--project", "77", "--budget", "0"],
+        isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
+      );
+      expect(r.status).toBe(0);
+      expect(r.stdout).toContain("budget 0s reached");
+      expect(r.stdout).not.toContain("budget 25s reached");
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("ai_enabled=false submit is refused (PT403) with a clear message and exit 1", async () => {
+    const api = startFakeApi();
+    try {
+      const r = await runCliAsync(
+        ["joe", "plan", "select 1", "--project", "999"],
+        isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
+      );
+      expect(r.status).toBe(1);
+      expect(`${r.stdout}\n${r.stderr}`).toContain("AI features disabled for this org");
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("joe terminate requires a numeric pid and maps args.pid", async () => {
+    const api = startFakeApi();
+    try {
+      const r = await runCliAsync(
+        ["joe", "terminate", "4711", "--project", "12"],
+        isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
+      );
+      expect(r.status).toBe(0);
+      const submit = api.requests.find((x) => x.pathname.endsWith("/rpc/joe_command_submit"));
+      expect(submit?.body.command).toBe("terminate");
+      expect(submit?.body.args).toEqual({ pid: 4711 });
+      expect(submit?.body.sql).toBeNull();
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("joe terminate rejects a non-numeric / trailing-garbage pid (no submit)", async () => {
+    // A pid must be a bare non-negative integer. parseInt() would silently accept
+    // "12x"→12, "-5"→-5, "1.5"→1 and submit a WRONG pg_terminate_backend target.
+    // Those must be a clean, typed rejection that never reaches the submit rpc.
+    const api = startFakeApi();
+    try {
+      for (const bad of ["12x", "abc", "1.5", "0x10", "  "]) {
+        const r = await runCliAsync(
+          ["joe", "terminate", bad, "--project", "12"],
+          isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
+        );
+        expect(r.status).toBe(1);
+        expect(`${r.stdout}\n${r.stderr}`).toContain("pid must be a number");
+      }
+      expect(api.requests.some((x) => x.pathname.endsWith("/rpc/joe_command_submit"))).toBe(false);
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("joe describe maps args.object (and --variant)", async () => {
+    const api = startFakeApi();
+    try {
+      const r = await runCliAsync(
+        ["joe", "describe", "users", "--project", "12", "--variant", "\\d+"],
+        isolatedEnv({ PGAI_API_KEY: "k", PGAI_API_BASE_URL: api.baseUrl })
+      );
+      expect(r.status).toBe(0);
+      const submit = api.requests.find((x) => x.pathname.endsWith("/rpc/joe_command_submit"));
+      expect(submit?.body.command).toBe("describe");
+      expect(submit?.body.args).toEqual({ object: "users", variant: "\\d+" });
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("missing --project fails fast", () => {
+    const r = runCli(["joe", "plan", "select 1"], isolatedEnv({ PGAI_API_KEY: "k" }));
+    expect(r.status).toBe(1);
+    expect(`${r.stdout}\n${r.stderr}`).toContain("Project is required");
+  });
+
+  test("missing API key fails fast", () => {
+    const r = runCli(["joe", "plan", "select 1", "--project", "12"], isolatedEnv());
+    expect(r.status).toBe(1);
+    expect(`${r.stdout}\n${r.stderr}`).toContain("API key is required");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// inferCommandFromResult — the sole logic mapping a bare `joe_command_result`
+// body back to a command for `pgai joe result <id>` rendering. Table-driven
+// over every branch of the per-command contract matrix (CONTRACT_DECISIONS):
+// plan/explain {queryid, plan_fingerprint, plan_text, plan_json} · exec
+// {command, row_count, result_rows, notices} · hypo {hypo_plan, hypo_used} ·
+// activity/describe {snapshot} · terminate {terminated, pid} · reset {reset}.
+// The `!== undefined` chain is order-sensitive, so each contract shape is
+// pinned; per the contract every command's keys are disjoint (a hypo re-plan
+// rides in `hypo_plan`, never `plan_text`/`plan_json`), so `hypo_used` being
+// checked after the plan keys cannot misclassify a contract-shaped body.
+// ---------------------------------------------------------------------------
+
+describe("inferCommandFromResult (joe result <id> body → command)", () => {
+  const cases: Array<{ name: string; body: Parameters<typeof inferCommandFromResult>[0]; expected: ReturnType<typeof inferCommandFromResult> }> = [
+    // The `command` echo (DECISION: every result echoes `command`) short-circuits
+    // everything — even when overlapping keys are present.
+    {
+      name: "command echo short-circuits (exec despite plan keys present)",
+      body: { command: "exec", plan_text: "Seq Scan", plan_json: {}, row_count: 1, result_rows: [{ n: 1 }] },
+      expected: "exec",
+    },
+    { name: "command echo: describe (snapshot would otherwise infer activity)", body: { command: "describe", snapshot: {} }, expected: "describe" },
+    // plan / explain — either plan key suffices; null still counts (key present).
+    { name: "plan_text + plan_json → plan", body: { plan_text: "Index Scan", plan_json: { Plan: {} } }, expected: "plan" },
+    { name: "plan_text only → plan", body: { plan_text: "Index Scan" }, expected: "plan" },
+    { name: "plan_json only → plan", body: { plan_json: { Plan: {} } }, expected: "plan" },
+    { name: "null plan_text (key present) → plan", body: { plan_text: null }, expected: "plan" },
+    // exec — row_count / result_rows.
+    { name: "row_count + result_rows → exec", body: { row_count: 2, result_rows: [{ a: 1 }, { a: 2 }] }, expected: "exec" },
+    { name: "result_rows only → exec", body: { result_rows: [] }, expected: "exec" },
+    { name: "row_count 0 (falsy but present) → exec", body: { row_count: 0 }, expected: "exec" },
+    // hypo — the contract body is {hypo_plan, hypo_used}; hypo_used:false must
+    // still classify (the "would NOT be used" verdict).
+    { name: "hypo_used true + hypo_plan → hypo", body: { hypo_used: true, hypo_plan: { Plan: {} } }, expected: "hypo" },
+    { name: "hypo_used false → hypo", body: { hypo_used: false, hypo_plan: { Plan: {} } }, expected: "hypo" },
+    // terminate — terminated/pid; a false verdict still classifies.
+    { name: "terminated true → terminate", body: { terminated: true, pid: 66 }, expected: "terminate" },
+    { name: "terminated false → terminate", body: { terminated: false, pid: 66 }, expected: "terminate" },
+    // reset.
+    { name: "reset true → reset", body: { reset: true }, expected: "reset" },
+    { name: "reset false → reset", body: { reset: false }, expected: "reset" },
+    // activity / describe — both ride `snapshot`; without the `command` echo the
+    // inference picks "activity" (rendering is identical for the two).
+    { name: "snapshot → activity", body: { snapshot: [{ pid: 1 }] }, expected: "activity" },
+    // Unrecognized.
+    { name: "empty body → null", body: {}, expected: null },
+    // Only `hypo_used` classifies hypo (always present per contract); a lone
+    // hypo_plan — a contract-violating body — stays unrecognized, not "plan".
+    { name: "hypo_plan without hypo_used → null (not misclassified as plan)", body: { hypo_plan: {} }, expected: null },
+  ];
+
+  for (const c of cases) {
+    test(c.name, () => {
+      expect(inferCommandFromResult(c.body)).toBe(c.expected);
+    });
+  }
+});