fix: unify codex queues json shape

2026-05-20 20:00:39 +00:00
parent 949540235c
commit c6a27e6c2b
4 changed files with 164 additions and 7 deletions
@@ -0,0 +1,140 @@
+import { codexQueuesQueryForTest } from "./src/code-queue";
+
+type JsonRecord = Record<string, unknown>;
+
+function assertCondition(condition: unknown, message: string, detail: JsonRecord = {}): void {
+  if (!condition) throw new Error(`${message}: ${JSON.stringify(detail)}`);
+}
+
+function asRecord(value: unknown): JsonRecord {
+  assertCondition(typeof value === "object" && value !== null && !Array.isArray(value), "expected JSON object", { value });
+  return value as JsonRecord;
+}
+
+function asArray(value: unknown): unknown[] {
+  assertCondition(Array.isArray(value), "expected JSON array", { value });
+  return value as unknown[];
+}
+
+function fixtureResponse(): JsonRecord {
+  return {
+    ok: true,
+    status: 200,
+    body: {
+      ok: true,
+      queue: {
+        total: 4,
+        queueCount: 3,
+        activeQueueIds: ["alpha"],
+        activeTaskIds: ["task-running"],
+        queuedTaskIds: ["task-queued"],
+        counts: { running: 1, queued: 2, succeeded: 1 },
+        unreadTerminal: 1,
+        executionDiagnostics: {
+          state: "split-brain",
+          splitBrain: true,
+          heartbeatFreshTaskIds: ["task-running"],
+          databaseActiveTaskCount: 1,
+          databaseActiveTaskIds: ["task-running"],
+          schedulerActiveRunSlotCount: 1,
+          schedulerActiveTaskIds: ["task-running"],
+        },
+      },
+      queues: [
+        {
+          id: "alpha",
+          name: "Alpha",
+          total: 1,
+          counts: { running: 1, queued: 0 },
+          unreadTerminal: 0,
+          activeTaskId: "task-running",
+          runnableTaskId: null,
+          updatedAt: "2026-05-20T00:00:00.000Z",
+        },
+        {
+          id: "beta",
+          name: "Beta",
+          total: 2,
+          counts: { running: 0, queued: 2 },
+          unreadTerminal: 0,
+          activeTaskId: null,
+          runnableTaskId: "task-queued",
+          updatedAt: "2026-05-20T00:01:00.000Z",
+        },
+        {
+          id: "gamma",
+          name: "Gamma",
+          total: 1,
+          counts: { succeeded: 1 },
+          unreadTerminal: 1,
+          activeTaskId: null,
+          runnableTaskId: null,
+          updatedAt: "2026-05-20T00:02:00.000Z",
+        },
+      ],
+    },
+  };
+}
+
+function assertQueuesShape(label: string, result: unknown, expectedView: string): void {
+  const data = asRecord(result);
+  const queues = asRecord(data.queues);
+  assertCondition(queues.view === expectedView, `${label} view mismatch`, queues);
+  const items = asArray(queues.items);
+  assertCondition(items.length === 3, `${label} must expose queue rows at data.queues.items[]`, queues);
+  const first = asRecord(items[0]);
+  assertCondition(first.id === "alpha", `${label} first item id mismatch`, first);
+  const firstCounts = asRecord(first.counts);
+  assertCondition(firstCounts.running === 1, `${label} item counts should be preserved`, first);
+  const counts = asRecord(queues.counts);
+  assertCondition(counts.running === 1 && counts.queued === 2, `${label} global counts should be preserved`, counts);
+  const diagnostics = asRecord(queues.executionDiagnostics);
+  assertCondition(diagnostics.state === "split-brain", `${label} executionDiagnostics should be preserved`, diagnostics);
+  assertCondition(diagnostics.effectiveLiveness === "live", `${label} diagnostics should retain derived liveness`, diagnostics);
+  assertCondition(Array.isArray(queues.activeTaskIds), `${label} activeTaskIds should be present`, queues);
+  assertCondition(Array.isArray(queues.queuedTaskIds), `${label} queuedTaskIds should be present`, queues);
+}
+
+export function runCodeQueueQueuesShapeContract(): JsonRecord {
+  const fetcher = (path: string): JsonRecord => {
+    assertCondition(path === "/api/microservices/code-queue/proxy/api/queues", "codex queues should use stable proxy path", { path });
+    return fixtureResponse();
+  };
+
+  const summary = codexQueuesQueryForTest([], fetcher);
+  assertQueuesShape("summary", summary, "summary");
+  const summaryQueues = asRecord(asRecord(summary).queues);
+  assertCondition(summaryQueues.deprecatedFullArray === undefined, "summary should not expose deprecated full array compatibility field", summaryQueues);
+
+  const full = codexQueuesQueryForTest(["--full"], fetcher);
+  assertQueuesShape("full", full, "full");
+  const fullQueues = asRecord(asRecord(full).queues);
+  assertCondition(!Array.isArray(fullQueues), "full queues payload must be an object, not the deprecated array shape", fullQueues);
+  assertCondition(fullQueues.bounded === false, "full without --limit should preserve complete queue listing semantics", fullQueues);
+  const deprecatedFullArray = asArray(fullQueues.deprecatedFullArray);
+  assertCondition(deprecatedFullArray.length === 3, "full should expose deprecated array only under a compatibility field", fullQueues);
+  const compatibility = asRecord(fullQueues.compatibility);
+  assertCondition(compatibility.stablePath === "data.queues.items[]", "compatibility metadata should document stable path", compatibility);
+  assertCondition(compatibility.deprecated === true, "compatibility metadata should mark old array path deprecated", compatibility);
+
+  const limitedFull = codexQueuesQueryForTest(["--full", "--limit", "2"], fetcher);
+  const limitedFullQueues = asRecord(asRecord(limitedFull).queues);
+  assertCondition(limitedFullQueues.bounded === true, "full with explicit --limit should be bounded", limitedFullQueues);
+  assertCondition(asArray(limitedFullQueues.items).length === 2, "full with explicit --limit should limit data.queues.items[]", limitedFullQueues);
+
+  return {
+    ok: true,
+    checks: [
+      "summary data.queues.items[] shape",
+      "summary queue metadata",
+      "full data.queues.items[] shape",
+      "full queue metadata",
+      "deprecated full array compatibility field",
+      "full explicit limit remains bounded",
+    ],
+  };
+}
+
+if (import.meta.main) {
+  process.stdout.write(`${JSON.stringify(runCodeQueueQueuesShapeContract(), null, 2)}\n`);
+}