kandev/apps/web/lib/workflows/replay-cycle-analysis.test.ts

import { describe, expect, it } from "vitest";
import { workflowId } from "@/lib/types/ids";
import type { WorkflowStep } from "@/lib/types/http";
import type {
  OnTurnCompleteAction,
  OnTurnStartAction,
  TransitionConfig,
} from "@/lib/types/workflow-actions";
import {
  analyzeIntroducedWorkflowReplayCycles,
  analyzeWorkflowReplayCycles,
} from "./replay-cycle-analysis";

const NOW = "2026-07-15T00:00:00.000Z";
const SHORT_RETURN_STEP_ID = "short-return";
const WORK_STEP_ID = "work";
const EXISTING_STEP_ID = "a-existing";
const ALTERNATE_STEP_ID = "z-existing";

function step(
  id: string,
  position: number,
  options: {
    autoStart?: boolean;
    name?: string;
    prompt?: string;
    onTurnStart?: OnTurnStartAction[];
    onTurnComplete?: OnTurnCompleteAction[];
  } = {},
): WorkflowStep {
  return {
    id,
    workflow_id: workflowId("workflow-1"),
    name: options.name ?? id,
    position,
    color: "bg-neutral-400",
    prompt: options.prompt,
    events: {
      on_enter: options.autoStart ? [{ type: "auto_start_agent" }] : [],
      on_turn_start: options.onTurnStart,
      on_turn_complete: options.onTurnComplete,
    },
    created_at: NOW,
    updated_at: NOW,
  };
}

function moveToStep(target: string, config: TransitionConfig = {}): OnTurnCompleteAction {
  return { type: "move_to_step", config: { ...config, step_id: target } };
}

function guardedMoveToStep(target: string): OnTurnCompleteAction {
  return moveToStep(target, {
    if: { wait_for_quorum: { role: "reviewer", threshold: "all_approve" } },
  });
}

describe("replay cycle detection", () => {
  it("reports a fully automatic next/previous replay cycle as blocking", () => {
    const diagnostics = analyzeWorkflowReplayCycles([
      step("build", 0, {
        autoStart: true,
        onTurnComplete: [{ type: "move_to_next" }],
      }),
      step("review", 1, {
        autoStart: true,
        onTurnComplete: [{ type: "move_to_previous" }],
      }),
    ]);

    expect(diagnostics).toHaveLength(2);
    expect(diagnostics[0]).toEqual({
      identity: expect.any(String),
      severity: "blocking",
      autoStartStepId: "build",
      autoStartStepName: "build",
      affectedStepIds: ["build", "review"],
      trace: [
        {
          sourceStepId: "build",
          sourceStepName: "build",
          trigger: "on_turn_complete",
          actionKind: "move_to_next",
          destinationStepId: "review",
          destinationStepName: "review",
          requiresUserInvolvement: false,
        },
        {
          sourceStepId: "review",
          sourceStepName: "review",
          trigger: "on_turn_complete",
          actionKind: "move_to_previous",
          destinationStepId: "build",
          destinationStepName: "build",
          requiresUserInvolvement: false,
        },
      ],
      promptSource: "task_description",
    });
  });

  it("treats on_turn_start from an auto-start step as automatic", () => {
    const [diagnostic] = analyzeWorkflowReplayCycles([
      step("work", 0, {
        autoStart: true,
        onTurnStart: [{ type: "move_to_next" }],
      }),
      step("review", 1, {
        autoStart: true,
        onTurnComplete: [{ type: "move_to_previous" }],
      }),
    ]);

    expect(diagnostic.severity).toBe("blocking");
    expect(diagnostic.trace.map((hop) => hop.requiresUserInvolvement)).toEqual([false, false]);
  });

  it("marks on_turn_start from a non-auto-start step as user-mediated", () => {
    const [diagnostic] = analyzeWorkflowReplayCycles([
      step("work", 0, {
        autoStart: true,
        onTurnComplete: [{ type: "move_to_next" }],
      }),
      step("review", 1, { onTurnStart: [{ type: "move_to_next" }] }),
      step("finish", 2, {
        autoStart: true,
        onTurnComplete: [moveToStep("work")],
      }),
    ]);

    expect(diagnostic.severity).toBe("warning");
    expect(diagnostic.trace.map((hop) => hop.requiresUserInvolvement)).toEqual([
      false,
      true,
      false,
    ]);
  });

  it("does not report the built-in Kanban return because on_turn_start skips on_enter", () => {
    const diagnostics = analyzeWorkflowReplayCycles([
      step("backlog", 0, {
        onTurnStart: [{ type: "move_to_next" }],
        onTurnComplete: [moveToStep("review")],
      }),
      step("in-progress", 1, {
        autoStart: true,
        onTurnComplete: [moveToStep("review")],
      }),
      step("review", 2, { onTurnStart: [{ type: "move_to_previous" }] }),
      step("done", 3, {
        onTurnStart: [{ type: "move_to_step", config: { step_id: "in-progress" } }],
      }),
    ]);

    expect(diagnostics).toEqual([]);
  });
});

describe("replay cycle severity", () => {
  it("marks an on_turn_complete hop from a non-auto-start source as user-mediated", () => {
    const [diagnostic] = analyzeWorkflowReplayCycles([
      step("work", 0, {
        autoStart: true,
        onTurnComplete: [{ type: "move_to_next" }],
      }),
      step("review", 1, { onTurnComplete: [{ type: "move_to_previous" }] }),
    ]);

    expect(diagnostic.severity).toBe("warning");
    expect(diagnostic.trace.map((hop) => hop.requiresUserInvolvement)).toEqual([false, true]);
  });

  it("marks an approval-gated hop as user-mediated", () => {
    const [diagnostic] = analyzeWorkflowReplayCycles([
      step("work", 0, {
        autoStart: true,
        onTurnComplete: [{ type: "move_to_next", config: { requires_approval: true } }],
      }),
      step("review", 1, {
        autoStart: true,
        onTurnComplete: [{ type: "move_to_previous" }],
      }),
    ]);

    expect(diagnostic.severity).toBe("warning");
    expect(diagnostic.trace.map((hop) => hop.requiresUserInvolvement)).toEqual([true, false]);
  });

  it("treats guarded transitions as possible automatic paths", () => {
    const [diagnostic] = analyzeWorkflowReplayCycles([
      step("work", 0, {
        autoStart: true,
        onTurnComplete: [
          {
            type: "move_to_next",
            config: { if: { wait_for_quorum: { role: "reviewer", threshold: "all_approve" } } },
          },
        ],
      }),
      step("review", 1, {
        autoStart: true,
        onTurnComplete: [{ type: "move_to_previous" }],
      }),
    ]);

    expect(diagnostic.severity).toBe("blocking");
  });
});

describe("replay transition resolution", () => {
  it("ignores lower-priority moves after an unconditional transition", () => {
    const diagnostics = analyzeWorkflowReplayCycles([
      step("work", 0, {
        autoStart: true,
        onTurnComplete: [{ type: "move_to_next" }, moveToStep("work")],
      }),
      step("done", 1),
    ]);

    expect(diagnostics).toEqual([]);
  });

  it("keeps fallback moves after a guarded transition", () => {
    const [diagnostic] = analyzeWorkflowReplayCycles([
      step("work", 0, {
        autoStart: true,
        onTurnComplete: [
          {
            type: "move_to_next",
            config: { if: { wait_for_quorum: { role: "reviewer", threshold: "all_approve" } } },
          },
          moveToStep("work"),
        ],
      }),
      step("done", 1),
    ]);

    expect(diagnostic.severity).toBe("blocking");
    expect(diagnostic.trace).toHaveLength(1);
    expect(diagnostic.trace[0].actionKind).toBe("move_to_step");
  });

  it("resolves explicit targets and ignores dangling targets", () => {
    const valid = analyzeWorkflowReplayCycles([
      step("work", 0, { autoStart: true, onTurnComplete: [moveToStep("review")] }),
      step("review", 1, {
        autoStart: true,
        onTurnComplete: [moveToStep("work")],
      }),
    ]);
    const dangling = analyzeWorkflowReplayCycles([
      step("work", 0, { autoStart: true, onTurnComplete: [moveToStep("missing")] }),
      step("review", 1, {
        autoStart: true,
        onTurnComplete: [moveToStep("work")],
      }),
    ]);

    expect(valid).toHaveLength(2);
    expect(dangling).toEqual([]);
  });

  it("ignores malformed explicit targets without throwing", () => {
    const malformed = { type: "move_to_step" } as OnTurnCompleteAction;

    expect(
      analyzeWorkflowReplayCycles([
        step("work", 0, { autoStart: true, onTurnComplete: [malformed] }),
      ]),
    ).toEqual([]);
  });

  it("uses position order for relative transitions after a reorder", () => {
    const before = analyzeWorkflowReplayCycles([
      step("work", 0, {
        autoStart: true,
        onTurnComplete: [{ type: "move_to_next" }],
      }),
      step("review", 1, {
        autoStart: true,
        onTurnComplete: [{ type: "move_to_previous" }],
      }),
      step("done", 2),
    ]);
    const after = analyzeWorkflowReplayCycles([
      step("work", 0, {
        autoStart: true,
        onTurnComplete: [{ type: "move_to_next" }],
      }),
      step("review", 2, {
        autoStart: true,
        onTurnComplete: [{ type: "move_to_previous" }],
      }),
      step("done", 1),
    ]);

    expect(before.map((diagnostic) => diagnostic.autoStartStepId)).toEqual(["work", "review"]);
    expect(after).toEqual([]);
  });

  it("does not report cycles that never re-enter an auto-start step", () => {
    const diagnostics = analyzeWorkflowReplayCycles([
      step("backlog", 0, { onTurnComplete: [{ type: "move_to_next" }] }),
      step("review", 1, { onTurnComplete: [{ type: "move_to_previous" }] }),
    ]);

    expect(diagnostics).toEqual([]);
  });
});

describe("replay cycle search bounds", () => {
  it("selects deterministically without enumerating every path in a dense branching graph", () => {
    const layerCount = 16;
    const branchCount = 3;
    const layers = Array.from({ length: layerCount }, (_, layerIndex) =>
      Array.from(
        { length: branchCount },
        (_, branchIndex) => `layer-${String(layerIndex).padStart(2, "0")}-${branchIndex}`,
      ),
    );
    const denseSteps = [
      step("work", 0, {
        autoStart: true,
        onTurnComplete: [...layers[0]].reverse().map(guardedMoveToStep),
      }),
      ...layers.flatMap((layer, layerIndex) =>
        layer.map((id, branchIndex) =>
          step(id, layerIndex * branchCount + branchIndex + 1, {
            onTurnComplete:
              layerIndex === layerCount - 1
                ? [moveToStep("work")]
                : [...layers[layerIndex + 1]].reverse().map(guardedMoveToStep),
          }),
        ),
      ),
    ];

    const [diagnostic] = analyzeWorkflowReplayCycles(denseSteps);

    expect(diagnostic.trace.map((hop) => hop.destinationStepId)).toEqual([
      ...layers.map(([lexicallyFirst]) => lexicallyFirst),
      "work",
    ]);
  });
});

describe("replay diagnostic selection", () => {
  it("selects a blocking trace before a warning trace", () => {
    const [diagnostic] = analyzeWorkflowReplayCycles([
      step("work", 0, {
        autoStart: true,
        onTurnStart: [{ type: "move_to_step", config: { step_id: "manual-return" } }],
        onTurnComplete: [moveToStep(SHORT_RETURN_STEP_ID)],
      }),
      step("manual-return", 1, { onTurnComplete: [moveToStep("work")] }),
      step(SHORT_RETURN_STEP_ID, 2, {
        autoStart: true,
        onTurnComplete: [moveToStep("work")],
      }),
    ]);

    expect(diagnostic.severity).toBe("blocking");
    expect(diagnostic.trace.map((hop) => hop.destinationStepId)).toEqual([
      SHORT_RETURN_STEP_ID,
      "work",
    ]);
  });

  it("selects the shortest trace when candidates have equal severity", () => {
    const [diagnostic] = analyzeWorkflowReplayCycles([
      step("work", 0, {
        autoStart: true,
        onTurnStart: [{ type: "move_to_step", config: { step_id: SHORT_RETURN_STEP_ID } }],
        onTurnComplete: [moveToStep("long-a")],
      }),
      step(SHORT_RETURN_STEP_ID, 1, { onTurnComplete: [moveToStep("work")] }),
      step("long-a", 2, { onTurnComplete: [moveToStep("long-b")] }),
      step("long-b", 3, {
        autoStart: true,
        onTurnComplete: [moveToStep("work")],
      }),
    ]);

    expect(diagnostic.severity).toBe("warning");
    expect(diagnostic.trace.map((hop) => hop.destinationStepId)).toEqual([
      SHORT_RETURN_STEP_ID,
      "work",
    ]);
  });

  it("keeps identity stable across names and prompt changes", () => {
    const original = analyzeWorkflowReplayCycles([
      step("work", 0, { autoStart: true, onTurnComplete: [moveToStep("review")] }),
      step("review", 1, {
        autoStart: true,
        onTurnComplete: [moveToStep("work")],
      }),
    ]);
    const renamed = analyzeWorkflowReplayCycles([
      step("work", 0, {
        autoStart: true,
        name: "Implementation",
        prompt: "Use {{task_prompt}} carefully",
        onTurnComplete: [moveToStep("review")],
      }),
      step("review", 1, {
        autoStart: true,
        name: "Code review",
        onTurnComplete: [moveToStep("work")],
      }),
    ]);

    expect(renamed.map((diagnostic) => diagnostic.identity)).toEqual(
      original.map((diagnostic) => diagnostic.identity),
    );
  });

  it.each([
    [undefined, "task_description"],
    ["", "task_description"],
    ["Before\n{{task_prompt}}\nAfter", "step_prompt_with_task_description"],
    ["Review the implementation", "step_prompt"],
  ] as const)("classifies prompt %j as %s", (prompt, expected) => {
    const [diagnostic] = analyzeWorkflowReplayCycles([
      step("work", 0, {
        autoStart: true,
        prompt,
        onTurnComplete: [moveToStep("work")],
      }),
    ]);

    expect(diagnostic.promptSource).toBe(expected);
  });

  it("uses input order to break equal-position ties and returns diagnostics in that order", () => {
    const steps = [
      step("second", 0, { autoStart: true, onTurnComplete: [moveToStep("second")] }),
      step("first", 0, { autoStart: true, onTurnComplete: [moveToStep("first")] }),
    ];

    expect(
      analyzeWorkflowReplayCycles(steps).map((diagnostic) => diagnostic.autoStartStepId),
    ).toEqual(["second", "first"]);
  });
});

describe("introduced replay cycle inventory", () => {
  it("detects a new alternate loop when the preferred trace is unchanged", () => {
    const baseline = [
      step(WORK_STEP_ID, 0, {
        autoStart: true,
        onTurnComplete: [guardedMoveToStep(EXISTING_STEP_ID)],
      }),
      step(EXISTING_STEP_ID, 1, {
        autoStart: true,
        onTurnComplete: [moveToStep(WORK_STEP_ID)],
      }),
      step("z-new", 2, {
        autoStart: true,
        onTurnComplete: [moveToStep(WORK_STEP_ID)],
      }),
    ];
    const proposed = [
      {
        ...baseline[0],
        events: {
          ...baseline[0].events,
          on_turn_complete: [guardedMoveToStep(EXISTING_STEP_ID), guardedMoveToStep("z-new")],
        },
      },
      ...baseline.slice(1),
    ];

    expect(analyzeWorkflowReplayCycles(proposed)[0].trace[0].destinationStepId).toBe(
      EXISTING_STEP_ID,
    );
    expect(
      analyzeIntroducedWorkflowReplayCycles(baseline, proposed)[0].trace.map(
        (hop) => hop.destinationStepId,
      ),
    ).toEqual(["z-new", WORK_STEP_ID]);
  });

  it("does not reclassify an existing alternate loop when the preferred trace is removed", () => {
    const baseline = [
      step(WORK_STEP_ID, 0, {
        autoStart: true,
        onTurnComplete: [guardedMoveToStep("a-preferred"), guardedMoveToStep(ALTERNATE_STEP_ID)],
      }),
      step("a-preferred", 1, {
        autoStart: true,
        onTurnComplete: [moveToStep(WORK_STEP_ID)],
      }),
      step(ALTERNATE_STEP_ID, 2, {
        autoStart: true,
        onTurnComplete: [moveToStep(WORK_STEP_ID)],
      }),
    ];
    const proposed = [
      {
        ...baseline[0],
        events: {
          ...baseline[0].events,
          on_turn_complete: [guardedMoveToStep(ALTERNATE_STEP_ID)],
        },
      },
      ...baseline.slice(1),
    ];

    expect(analyzeWorkflowReplayCycles(proposed)[0].trace[0].destinationStepId).toBe(
      ALTERNATE_STEP_ID,
    );
    expect(analyzeIntroducedWorkflowReplayCycles(baseline, proposed)).toEqual([]);
  });
});

describe("bounded replay cycle inventory", () => {
  it("fails conservatively when alternate cycle inventory is truncated", () => {
    const existingStepIds = Array.from(
      { length: 257 },
      (_, index) => `existing-${index.toString().padStart(3, "0")}`,
    );
    const baseline = [
      step(WORK_STEP_ID, 0, {
        autoStart: true,
        onTurnComplete: existingStepIds.map(guardedMoveToStep),
      }),
      ...existingStepIds.map((stepId, index) =>
        step(stepId, index + 1, {
          onTurnComplete: [moveToStep(WORK_STEP_ID)],
        }),
      ),
    ];
    const newStepId = "new-beyond-inventory-cap";
    const proposed = [
      {
        ...baseline[0],
        events: {
          ...baseline[0].events,
          on_turn_complete: [
            ...(baseline[0].events?.on_turn_complete ?? []),
            guardedMoveToStep(newStepId),
          ],
        },
      },
      ...baseline.slice(1),
      step(newStepId, baseline.length, {
        onTurnComplete: [moveToStep(WORK_STEP_ID)],
      }),
    ];

    expect(analyzeIntroducedWorkflowReplayCycles(baseline, proposed)).toHaveLength(1);
  });
});