@ryanfw/prompt-orchestration-pipeline 1.3.2 → 1.3.3

package/src/core/__tests__/job-view.test.ts

@@ -0,0 +1,859 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { __resetWarnedFallbackKeys, normalizeJobView } from "../job-view";
+import type { JobView } from "../job-view";
+
+const JOB_ID = "job-abc-123";
+const LOCATION = "current";
+
+let warnSpy: ReturnType<typeof spyOn<Console, "warn">> | null = null;
+
+function captureWarn(): ReturnType<typeof spyOn<Console, "warn">> {
+  warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+  return warnSpy;
+}
+
+function restoreWarn(): void {
+  warnSpy?.mockRestore();
+  warnSpy = null;
+}
+
+function callsContaining(spy: ReturnType<typeof spyOn<Console, "warn">>, fragment: string): number {
+  return spy.mock.calls.filter((call) => typeof call[0] === "string" && call[0].includes(fragment)).length;
+}
+
+function warnCallsContaining(fragment: string): number {
+  return warnSpy ? callsContaining(warnSpy, fragment) : 0;
+}
+
+beforeEach(() => {
+  __resetWarnedFallbackKeys();
+  captureWarn();
+});
+
+afterEach(() => {
+  restoreWarn();
+});
+
+describe("normalizeJobView", () => {
+  describe("canonical output (AC-1)", () => {
+    test("never emits 'error' as a job status (persisted 'failed' maps to 'failed')", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "failed", tasks: { a: { state: "failed" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("failed");
+    });
+
+    test("never emits 'done' as a job status (persisted 'done' maps to 'complete')", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: { a: { state: "done" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("complete");
+    });
+
+    test("always sets id, jobId, location, and a title", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { name: "My Job", state: "pending" },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.id).toBe(JOB_ID);
+      expect(view.jobId).toBe(JOB_ID);
+      expect(view.location).toBe(LOCATION);
+      expect(view.name).toBe("My Job");
+      expect(view.title).toBe("My Job");
+    });
+
+    test("falls back to jobId for the title when name/title are missing", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ state: "pending" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.name).toBe(JOB_ID);
+      expect(view.title).toBe(JOB_ID);
+    });
+  });
+
+  describe("persisted state authoritative (AC-2 precedence 1)", () => {
+    test("state:'pending' returns 'pending' even when raw.status says 'failed'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "pending", status: "failed" },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("pending");
+    });
+
+    test("state:'running' wins over a 'failed' raw.status", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "running", status: "failed" },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("running");
+    });
+
+    test("state:'done' (persisted JobState) maps to 'complete'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ state: "done" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("complete");
+    });
+
+    test("state:'done' in current with pending tasks derives from tasks instead of hiding pending work", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: { a: { state: "done" }, b: { state: "pending" } } },
+        JOB_ID,
+        "current",
+      );
+
+      // Assert
+      expect(view.status).toBe("pending");
+    });
+
+    test("state:'done' in current with running tasks derives running status", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: { a: { state: "done" }, b: { state: "running" } } },
+        JOB_ID,
+        "current",
+      );
+
+      // Assert
+      expect(view.status).toBe("running");
+    });
+
+    test("state:'done' in complete location remains complete even when archived tasks disagree", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: { a: { state: "done" }, b: { state: "pending" } } },
+        JOB_ID,
+        "complete",
+      );
+
+      // Assert
+      expect(view.status).toBe("complete");
+    });
+
+    test("state is case-insensitive: 'FAILED' → 'failed'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ state: "FAILED" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("failed");
+    });
+  });
+
+  describe("reconciled interrupted job regression (#315, AC-2)", () => {
+    test("state:'failed' + task failed with errorContext.kind='runner-interrupted' → status:'failed' and errorContext preserved", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "failed",
+          tasks: {
+            research: {
+              state: "failed",
+              error: "runner exited without completing this task",
+              errorContext: {
+                kind: "runner-interrupted",
+                code: 1,
+                signal: null,
+                source: "child-exit",
+              },
+            },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("failed");
+      expect(view.tasks.research?.errorContext).toEqual({
+        kind: "runner-interrupted",
+        code: 1,
+        signal: null,
+        source: "child-exit",
+      });
+      expect(view.tasks.research?.error).toEqual({ message: "runner exited without completing this task" });
+    });
+
+    test("state:'failed' + job-level runner interruption preserves root errorContext", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "failed",
+          error: {
+            name: "RunnerInterrupted",
+            message: "runner exited while the job was still marked running",
+          },
+          errorContext: {
+            kind: "runner-interrupted",
+            code: 1,
+            signal: null,
+            source: "boot-sweep",
+          },
+          tasks: {
+            research: { state: "done", currentStage: null },
+            analysis: { state: "pending", currentStage: null },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("failed");
+      expect(view.error).toEqual({
+        code: "RunnerInterrupted",
+        name: "RunnerInterrupted",
+        message: "runner exited while the job was still marked running",
+      });
+      expect(view.errorContext).toEqual({
+        kind: "runner-interrupted",
+        code: 1,
+        signal: null,
+        source: "boot-sweep",
+      });
+    });
+  });
+
+  describe("waiting is never lost (AC-3)", () => {
+    test("state:'waiting' + all tasks done → 'waiting' (persisted state authoritative)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "waiting", tasks: { a: { state: "done" }, b: { state: "done" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("waiting");
+    });
+
+    test("state:'waiting' wins over a 'failed' raw.status", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "waiting", status: "failed" },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("waiting");
+    });
+  });
+
+  describe("raw.status fallback (AC-2 precedence 2)", () => {
+    test("state absent + status:'running' (no tasks) → 'running'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ status: "running" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("running");
+    });
+
+    test("state absent + status:'complete' (no tasks) → 'complete'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ status: "complete" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("complete");
+    });
+
+    test("state absent + status:'failed' (no tasks) → 'failed'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ status: "failed" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("failed");
+    });
+
+    test("state absent + status:'error' (legacy synonym) → 'failed'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ status: "error" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("failed");
+    });
+
+    test("state absent + status:'done' (legacy synonym) → 'complete'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ status: "done" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("complete");
+    });
+
+    test("status case-insensitive: 'ERROR' → 'failed'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ status: "ERROR" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("failed");
+    });
+
+    test("state unrecognized + status:'error' → 'failed'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "bogus-state", status: "error" },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("failed");
+    });
+  });
+
+  describe("task-derived fallback (AC-2 precedence 3)", () => {
+    test("state absent + no status + all tasks done → 'complete' and warns once", () => {
+      // Arrange
+      const raw = { tasks: { a: { state: "done" }, b: { state: "done" } } };
+
+      // Act
+      const view: JobView = normalizeJobView(raw, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("complete");
+      expect(warnCallsContaining(`${LOCATION}:${JOB_ID}`)).toBe(1);
+    });
+
+    test("state absent + no status + tasks failed + done → 'failed' (failed priority) and warns", () => {
+      // Arrange
+      const raw = { tasks: { a: { state: "failed" }, b: { state: "done" } } };
+
+      // Act
+      const view: JobView = normalizeJobView(raw, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("failed");
+      expect(warnCallsContaining(`${LOCATION}:${JOB_ID}`)).toBe(1);
+    });
+
+    test("state absent + no status + tasks running + done → 'running' and warns", () => {
+      // Arrange
+      const raw = { tasks: { a: { state: "running" }, b: { state: "done" } } };
+
+      // Act
+      const view: JobView = normalizeJobView(raw, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("running");
+      expect(warnCallsContaining(`${LOCATION}:${JOB_ID}`)).toBe(1);
+    });
+
+    test("state absent + no status + unrecognized status falls through to derivation", () => {
+      // Arrange
+      const raw = { status: "mystery-status", tasks: { a: { state: "done" } } };
+
+      // Act
+      const view: JobView = normalizeJobView(raw, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("complete");
+      expect(warnCallsContaining(`${LOCATION}:${JOB_ID}`)).toBe(1);
+    });
+
+    test("task-derived fallback warns once across multiple calls for the same location:jobId", () => {
+      // Arrange
+      const raw = { tasks: { a: { state: "done" } } };
+
+      // Act
+      normalizeJobView(raw, JOB_ID, LOCATION);
+      normalizeJobView(raw, JOB_ID, LOCATION);
+      normalizeJobView(raw, JOB_ID, LOCATION);
+
+      // Assert
+      expect(warnCallsContaining(`${LOCATION}:${JOB_ID}`)).toBe(1);
+    });
+
+    test("task-derived fallback warns separately for different location:jobId keys", () => {
+      // Arrange
+      const raw = { tasks: { a: { state: "done" } } };
+
+      // Act
+      normalizeJobView(raw, "job-A", "current");
+      normalizeJobView(raw, "job-B", "current");
+      normalizeJobView(raw, "job-A", "complete");
+
+      // Assert
+      expect(warnCallsContaining("current:job-A")).toBe(1);
+      expect(warnCallsContaining("current:job-B")).toBe(1);
+      expect(warnCallsContaining("complete:job-A")).toBe(1);
+    });
+  });
+
+  describe("disagreement cases (AC-4)", () => {
+    test("state:'failed' + tasks all done → 'failed' (persisted state authoritative)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "failed", tasks: { a: { state: "done" }, b: { state: "done" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("failed");
+    });
+
+    test("state:'running' + tasks all done → 'running' (persisted state authoritative)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "running", tasks: { a: { state: "done" }, b: { state: "done" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("running");
+    });
+
+    test("state absent + tasks all done → 'complete'", () => {
+      // Arrange
+      const raw = { tasks: { a: { state: "done" }, b: { state: "done" } } };
+
+      // Act
+      const view: JobView = normalizeJobView(raw, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("complete");
+      expect(warnCallsContaining(`${LOCATION}:${JOB_ID}`)).toBe(1);
+    });
+
+    test("state:'done' + tasks all done → 'complete' (agreement)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: { a: { state: "done" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("complete");
+    });
+  });
+
+  describe("liberal input, canonical output (AC-5)", () => {
+    test("status:'error' (legacy) with no valid state → 'failed'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ status: "error" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("failed");
+    });
+
+    test("state:'done' (persisted) → 'complete' and never 'done'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ state: "done" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("complete");
+      expect(view.status).not.toBe("done");
+    });
+
+    test("status:'done' (legacy) → 'complete' and never 'done'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ status: "done" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("complete");
+      expect(view.status).not.toBe("done");
+    });
+
+    test("case-insensitive: state:'DONE' → 'complete'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ state: "DONE" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("complete");
+    });
+
+    test("case-insensitive: state:'  failed  ' → 'failed'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ state: "  failed  " }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("failed");
+    });
+  });
+
+  describe("field preservation", () => {
+    test("uses finite persisted progress when present", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "running", progress: 42, tasks: { a: { state: "done" }, b: { state: "running" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.progress).toBe(42);
+    });
+
+    test("derives progress from completed tasks when persisted progress is missing", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "running", tasks: { a: { state: "done" }, b: { state: "skipped" }, c: { state: "pending" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.progress).toBe(66);
+    });
+
+    test("derives progress when persisted progress is not finite", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "running", progress: Number.NaN, tasks: { a: { state: "done" }, b: { state: "pending" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.progress).toBe(50);
+    });
+
+    test("maps live snapshot lastUpdated to updatedAt", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "running", lastUpdated: "2026-06-19T12:00:00.000Z" },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.updatedAt).toBe("2026-06-19T12:00:00.000Z");
+      expect(view.lastUpdated).toBe("2026-06-19T12:00:00.000Z");
+    });
+
+    test("prefers explicit updatedAt over lastUpdated", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "running",
+          updatedAt: "2026-06-19T12:05:00.000Z",
+          lastUpdated: "2026-06-19T12:00:00.000Z",
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.updatedAt).toBe("2026-06-19T12:05:00.000Z");
+      expect(view.lastUpdated).toBe("2026-06-19T12:00:00.000Z");
+    });
+
+    test("preserves explicit top-level costs when present", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", costs: { totalCost: 7, totalTokens: 12 } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.costs).toEqual({ totalCost: 7, totalTokens: 12 });
+    });
+
+    test("aggregates costs from task tokenUsage when top-level costs are absent", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "done",
+          tasks: {
+            alpha: { state: "done", tokenUsage: [["openai:gpt-4o", 10, 5, 0.25]] },
+            beta: { state: "done", tokenUsage: [["anthropic:claude", 7, 3, 0.5], ["bad"]] },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.costs).toEqual({
+        totalCost: 0.75,
+        totalTokens: 25,
+        totalInputTokens: 17,
+        totalOutputTokens: 8,
+      });
+      expect(view.tasks.alpha?.tokenUsage).toEqual([["openai:gpt-4o", 10, 5, 0.25]]);
+      expect(view.tasks.beta?.tokenUsage).toEqual([
+        ["anthropic:claude", 7, 3, 0.5],
+        ["bad"],
+      ]);
+    });
+
+    test("normalizes persisted string task errors to message objects", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "failed",
+          tasks: {
+            agent: { state: "failed", error: "Agent step failed" },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.tasks.agent?.error).toEqual({ message: "Agent step failed" });
+    });
+
+    test("preserves readable:false when present", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "failed", readable: false },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.readable).toBe(false);
+    });
+
+    test("preserves readable:true when present", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", readable: true },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.readable).toBe(true);
+    });
+
+    test("readable is undefined when absent (defaults to readable per #313)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ state: "done" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.readable).toBeUndefined();
+    });
+
+    test("preserves error: { code, message, path } when well-formed", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { readable: false, error: { code: "STATUS_CORRUPT", message: "bad json", path: "/tmp/x" } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.error).toEqual({ code: "STATUS_CORRUPT", message: "bad json", path: "/tmp/x" });
+    });
+
+    test("preserves error without path", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { readable: false, error: { code: "STATUS_CORRUPT", message: "bad json" } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.error).toEqual({ code: "STATUS_CORRUPT", message: "bad json" });
+    });
+
+    test("normalizes gate rejection errors from name/message", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { error: { name: "GateRejected", message: "needs another pass" } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.error).toEqual({
+        code: "GateRejected",
+        message: "needs another pass",
+        name: "GateRejected",
+      });
+    });
+
+    test("normalizes runner failures from name/message/stack", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { error: { name: "Error", message: "boom", stack: "trace" } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.error).toEqual({
+        code: "Error",
+        message: "boom",
+        name: "Error",
+        stack: "trace",
+      });
+    });
+
+    test("uses a fallback code for message-only errors", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { error: { code: 42, message: "bad" } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.error).toEqual({ code: "JOB_ERROR", message: "bad" });
+    });
+
+    test("drops error when message is not a string", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { error: { code: "STATUS_CORRUPT", message: 42 } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.error).toBeUndefined();
+    });
+  });
+
+  describe("task id synthesis (AC-8 server side)", () => {
+    test("array tasks with explicit name fields are keyed by name", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: [{ name: "alpha" }, { name: "beta" }] },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(Object.keys(view.tasks)).toEqual(["alpha", "beta"]);
+    });
+
+    test("array tasks with no name fall back to zero-based 'task-0', 'task-1'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: [{}, {}] },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(Object.keys(view.tasks)).toEqual(["task-0", "task-1"]);
+    });
+
+    test("array tasks with no name preserve order in the fallback", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: [{ state: "done" }, { state: "done" }, { state: "done" }] },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(Object.keys(view.tasks)).toEqual(["task-0", "task-1", "task-2"]);
+    });
+
+    test("mixed array (named + unnamed) uses name where present, 'task-N' otherwise", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: [{ name: "alpha" }, {}] },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(Object.keys(view.tasks)).toEqual(["alpha", "task-1"]);
+    });
+
+    test("empty-string name falls back to 'task-${index}'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: [{ name: "" }] },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(Object.keys(view.tasks)).toEqual(["task-0"]);
+    });
+
+    test("object tasks are keyed by their existing keys (pipeline order preserved)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: { plan: { state: "done" }, review: { state: "done" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(Object.keys(view.tasks)).toEqual(["plan", "review"]);
+    });
+  });
+
+  describe("robustness", () => {
+    test("non-object raw returns a JobView with empty tasks and pending status (no throw)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView("not an object", JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.tasks).toEqual({});
+      expect(view.status).toBe("pending");
+    });
+
+    test("null raw returns a JobView with empty tasks and pending status (no throw)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(null, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.tasks).toEqual({});
+      expect(view.status).toBe("pending");
+    });
+
+    test("undefined raw returns a JobView with empty tasks and pending status (no throw)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(undefined, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.tasks).toEqual({});
+      expect(view.status).toBe("pending");
+    });
+  });
+});
+
+describe("__resetWarnedFallbackKeys", () => {
+  test("clears the warn cache so a subsequent call warns again", () => {
+    // Arrange
+    const raw = { tasks: { a: { state: "done" } } };
+
+    // Act
+    normalizeJobView(raw, JOB_ID, LOCATION);
+    const firstCalls = warnCallsContaining(`${LOCATION}:${JOB_ID}`);
+    __resetWarnedFallbackKeys();
+    normalizeJobView(raw, JOB_ID, LOCATION);
+    const secondCalls = warnCallsContaining(`${LOCATION}:${JOB_ID}`);
+
+    // Assert
+    expect(firstCalls).toBe(1);
+    expect(secondCalls).toBe(2);
+  });
+});