Skip to content

💫 Toolkit to help you get started with SDD or any other process!

121 KB
Raw Blame
"""Behavioral contracts for scoped calls and durable execution occurrences."""

from collections import Counter
from datetime import date
import json
import threading

import pytest
import yaml

from specify_cli.workflows import STEP_REGISTRY
from specify_cli.workflows.base import RunStatus, StepBase, StepResult, StepStatus
from specify_cli.workflows.engine import (
    RunState,
    WorkflowDefinition,
    WorkflowEngine,
    validate_workflow,
)


def definition(name, steps, **fields):
    return WorkflowDefinition(
        {"workflow": {"id": name, "name": name}, "steps": steps, **fields}
    )


def install(root, child, enabled=True):
    from specify_cli.workflows.catalog import WorkflowRegistry

    directory = root / ".specify" / "workflows" / child.id
    directory.mkdir(parents=True, exist_ok=True)
    (directory / "workflow.yml").write_text(
        yaml.safe_dump(child.data), encoding="utf-8"
    )
    registry = WorkflowRegistry(root)
    registry.add(child.id, {"version": "1.0.0", "enabled": enabled})
    return directory


def call(target="child", **extra):
    return {"id": "call", "type": "workflow", "workflow": target, **extra}


@pytest.fixture
def probe(monkeypatch):
    counts = Counter()

    class Probe(StepBase):
        type_key = "probe"

        def execute(self, config, context):
            from specify_cli.workflows.expressions import evaluate_expression

            counts[config["id"]] += 1
            value = evaluate_expression(config.get("value"), context)
            status = config.get("status", "completed")
            if config.get("await") and not context.inputs.get("approve"):
                status = "paused"
            return StepResult(
                StepStatus(status), output={"value": value, **config.get("output", {})}
            )

    monkeypatch.setitem(STEP_REGISTRY, "probe", Probe())
    return counts


def test_declared_output_and_scope_isolation(tmp_path, probe):
    child = definition(
        "child",
        [
            {"id": "inspect", "type": "probe", "value": "{{ inputs.value }}"},
            {
                "id": "private",
                "type": "probe",
                "value": "{{ steps.parent.output.value }}",
            },
        ],
        inputs={"value": {"type": "string"}},
        outputs={
            "value": {"value": "{{ steps.inspect.output.value }}"},
            "hidden": {"value": "{{ steps.private.output.value }}"},
        },
    )
    install(tmp_path, child)
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {"id": "parent", "type": "probe", "value": "secret"},
                call(input={"value": "mapped"}),
                {
                    "id": "consume",
                    "type": "probe",
                    "value": "{{ steps.call.output.value }}",
                },
            ],
        )
    )
    assert state.status == RunStatus.COMPLETED
    assert state.step_results["call"]["output"] == {
        "workflow": "child",
        "status": "completed",
        "value": "mapped",
        "hidden": None,
    }
    assert state.step_results["consume"]["output"]["value"] == "mapped"
    assert "inspect" not in state.step_results
    assert len(list((tmp_path / ".specify/workflows/runs").iterdir())) == 1


def test_called_workflow_dir_resolves_definition_symlink(tmp_path, monkeypatch, probe):
    import specify_cli.workflows._execution as execution

    resolved_dir = tmp_path / "resolved-child"
    resolved_dir.mkdir()
    symlink_dir = tmp_path / "linked-child"
    symlink_dir.symlink_to(resolved_dir, target_is_directory=True)
    child = definition(
        "child",
        [{"id": "path", "type": "probe", "value": "{{ context.workflow_dir }}"}],
        outputs={"workflow-dir": {"value": "{{ steps.path.output.value }}"}},
    )
    child.source_path = symlink_dir / "workflow.yml"
    monkeypatch.setattr(execution, "resolve_target", lambda *_: child)

    state = WorkflowEngine(tmp_path).execute(definition("parent", [call()]))

    assert state.status == RunStatus.COMPLETED, state.error
    assert state.step_results["call"]["output"]["workflow-dir"] == str(
        resolved_dir
    )


def test_concurrent_nested_calls_keep_downstream_aliases_local(
    tmp_path, monkeypatch, probe
):
    install(
        tmp_path,
        definition(
            "child",
            [{"id": "work", "type": "probe"}],
            inputs={"value": {"type": "number"}},
            outputs={"value": {"value": "{{ inputs.value }}"}},
        ),
    )
    barrier = threading.Barrier(2, timeout=5)
    consumed = {}

    class Consume(StepBase):
        type_key = "consume"

        def execute(self, config, context):
            barrier.wait()
            consumed[context.item] = context.steps["call"]["output"]["value"]
            return StepResult(StepStatus.COMPLETED)

    monkeypatch.setitem(STEP_REGISTRY, "consume", Consume())
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {
                    "id": "spread",
                    "type": "fan-out",
                    "items": [1, 2],
                    "max_concurrency": 2,
                    "step": {
                        "id": "branch",
                        "type": "if",
                        "condition": True,
                        "then": [
                            call(input={"value": "{{ item }}"}),
                            {"id": "consume", "type": "consume"},
                        ],
                    },
                }
            ],
        )
    )
    assert state.status == RunStatus.COMPLETED
    assert consumed == {1: 1, 2: 2}
    items = RunState.load(state.run_id, tmp_path).execution["sequence"]["nodes"][0][
        "children"
    ]
    results = [
        item["nodes"][0]["children"][0]["nodes"][0]["result"]["output"]["value"]
        for item in items
    ]
    assert results == [1, 2]
    assert "call" not in state.step_results


def test_nested_resume_freezes_branch_binding_and_completed_prefix(tmp_path, probe):
    child = definition(
        "child",
        [
            {"id": "prepare", "type": "probe"},
            {"id": "wait", "type": "probe", "await": True},
        ],
        inputs={"approve": {"type": "boolean", "default": False}},
    )
    directory = install(tmp_path, child)
    root = definition(
        "parent",
        [
            {
                "id": "route",
                "type": "if",
                "condition": "{{ inputs.choose }}",
                "then": [call(input={"approve": "{{ inputs.approve }}"})],
                "else": [{"id": "wrong", "type": "probe"}],
            }
        ],
        inputs={
            "choose": {"type": "boolean", "default": True},
            "approve": {"type": "boolean", "default": False},
        },
    )
    state = WorkflowEngine(tmp_path).execute(root)
    assert state.status == RunStatus.PAUSED
    (directory / "workflow.yml").write_text("invalid", encoding="utf-8")
    state = WorkflowEngine(tmp_path).resume(state.run_id, {"choose": False})
    assert state.status == RunStatus.PAUSED
    state = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})
    assert state.status == RunStatus.COMPLETED
    assert probe == {"prepare": 1, "wait": 3}


@pytest.mark.parametrize(
    "status,aborted,handled,expected",
    [
        ("failed", False, False, "failed"),
        ("failed", False, True, "completed"),
        ("failed", True, True, "aborted"),
        ("paused", False, True, "paused"),
    ],
)
def test_call_outcomes(tmp_path, probe, status, aborted, handled, expected):
    install(
        tmp_path,
        definition(
            "child",
            [
                {
                    "id": "work",
                    "type": "probe",
                    "status": status,
                    "output": {"aborted": aborted},
                },
            ],
        ),
    )
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                call(continue_on_error=handled),
                {"id": "after", "type": "probe"},
            ],
        )
    )
    assert state.status.value == expected
    assert probe["after"] == (expected == "completed")
    assert state.step_results["call"]["output"]["status"] == (
        "aborted" if aborted else status
    )


@pytest.mark.parametrize(
    "target", [" child", "child\n", "CHILD", "../child", "runs", 123, date(2026, 1, 1)]
)
def test_invalid_targets_are_handled_failures(tmp_path, probe, target):
    state = WorkflowEngine(tmp_path).execute(
        definition("parent", [call(target, continue_on_error=True)])
    )
    assert state.status == RunStatus.COMPLETED
    assert state.step_results["call"]["status"] == "failed"
    RunState.load(state.run_id, tmp_path)


@pytest.mark.parametrize(
    "mapping",
    [{"unknown": "x"}, {"value": []}, {"value": date(2026, 1, 1)}, [1], None],
)
def test_invalid_inputs_do_not_execute_child(tmp_path, probe, mapping):
    install(
        tmp_path,
        definition(
            "child",
            [{"id": "work", "type": "probe"}],
            inputs={"value": {"type": "string", "required": True}},
        ),
    )
    state = WorkflowEngine(tmp_path).execute(
        definition("parent", [call(input=mapping)])
    )
    assert state.status == RunStatus.FAILED
    assert not probe
    RunState.load(state.run_id, tmp_path)


def test_child_exception_propagates_despite_continue_on_error(tmp_path, monkeypatch):
    class Explode(StepBase):
        type_key = "explode"

        def execute(self, config, context):
            raise RuntimeError("child exploded")

    monkeypatch.setitem(STEP_REGISTRY, "explode", Explode())
    install(tmp_path, definition("child", [{"id": "work", "type": "explode"}]))

    with pytest.raises(RuntimeError, match="child exploded"):
        WorkflowEngine(tmp_path).execute(
            definition("parent", [call(continue_on_error=True)])
        )


@pytest.mark.parametrize("location", ["input", "output"])
def test_call_expression_errors_propagate_despite_continue_on_error(
    tmp_path, probe, location
):
    child = definition(
        "child",
        [{"id": "work", "type": "probe"}],
        inputs={"value": {"type": "string"}},
        outputs=(
            {"value": {"value": "{{ inputs.value | from_json }}"}}
            if location == "output"
            else {}
        ),
    )
    install(tmp_path, child)
    config = call(
        input={
            "value": (
                "{{ inputs.value | from_json }}" if location == "input" else "not json"
            )
        },
        continue_on_error=True,
    )

    with pytest.raises(ValueError, match="from_json: invalid JSON"):
        WorkflowEngine(tmp_path).execute(
            definition(
                "parent",
                [config],
                inputs={"value": {"type": "string", "default": "not json"}},
            )
        )


@pytest.mark.parametrize("handled", [False, True])
def test_output_failure_retries_only_finalization(
    tmp_path, monkeypatch, probe, handled
):
    import specify_cli.workflows._execution as execution
    from specify_cli.workflows.composition import CallError

    install(tmp_path, definition("child", [{"id": "work", "type": "probe"}]))
    original = execution.evaluate_outputs
    monkeypatch.setattr(
        execution,
        "evaluate_outputs",
        lambda *_: (_ for _ in ()).throw(CallError("bad output")),
    )
    state = WorkflowEngine(tmp_path).execute(
        definition("parent", [call(continue_on_error=handled)])
    )
    assert state.status == (
        RunStatus.COMPLETED if handled else RunStatus.FAILED
    )
    if handled:
        assert probe["work"] == 1
        return
    state = WorkflowEngine(tmp_path).resume(state.run_id)
    assert state.status == RunStatus.FAILED
    monkeypatch.setattr(execution, "evaluate_outputs", original)
    state = WorkflowEngine(tmp_path).resume(state.run_id)
    assert state.status == RunStatus.COMPLETED
    assert probe["work"] == 1


def test_output_expression_failure_retries_only_finalization(tmp_path, probe):
    install(
        tmp_path,
        definition(
            "child",
            [{"id": "work", "type": "probe"}],
            inputs={"value": {"type": "string"}},
            outputs={"value": {"value": "{{ inputs.value | from_json }}"}},
        ),
    )
    root = definition(
        "parent",
        [call(input={"value": "{{ inputs.value }}"})],
        inputs={"value": {"type": "string", "default": "not json"}},
    )

    with pytest.raises(ValueError, match="from_json: invalid JSON"):
        WorkflowEngine(tmp_path).execute(root, run_id="output-expression")

    state = WorkflowEngine(tmp_path).resume(
        "output-expression",
        {"value": '{"ok": true}'},
    )

    assert state.status == RunStatus.COMPLETED
    assert probe["work"] == 1
    assert state.step_results["call"]["output"]["value"] == {"ok": True}


@pytest.mark.parametrize("status", [RunStatus.PAUSED, RunStatus.FAILED])
def test_resume_accepts_paused_and_failed_tree_backed_runs(tmp_path, probe, status):
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [{"id": "wait", "type": "probe", "status": status.value}],
        )
    )
    assert state.status == status

    resumed = WorkflowEngine(tmp_path).resume(state.run_id)

    assert resumed.status == status


def test_resume_rejects_running_tree_backed_run_without_writes(tmp_path, probe):
    state = WorkflowEngine(tmp_path).execute(
        definition("parent", [{"id": "wait", "type": "probe", "await": True}])
    )
    path = state.runs_dir / "state.json"
    data = json.loads(path.read_text())
    data["status"] = RunStatus.RUNNING.value
    path.write_text(json.dumps(data))
    before = path.read_bytes()

    with pytest.raises(ValueError, match="Cannot resume run .* 'running'"):
        WorkflowEngine(tmp_path).resume(state.run_id)

    assert path.read_bytes() == before


def test_legacy_resume_adapts_once(tmp_path, probe):
    root = definition(
        "parent",
        [
            {"id": "before", "type": "probe"},
            {"id": "wait", "type": "probe", "await": True},
        ],
        inputs={"approve": {"type": "boolean", "default": False}},
    )
    state = WorkflowEngine(tmp_path).execute(root)
    path = state.runs_dir / "state.json"
    data = json.loads(path.read_text())
    del data["execution"]
    path.write_text(json.dumps(data))
    state = WorkflowEngine(tmp_path).resume(state.run_id)
    assert state.status == RunStatus.PAUSED
    state = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})
    assert state.status == RunStatus.COMPLETED
    assert probe == {"before": 1, "wait": 3}


def test_version_one_tree_rejected_without_writes(tmp_path, probe):
    state = WorkflowEngine(tmp_path).execute(
        definition("parent", [{"id": "wait", "type": "probe", "await": True}])
    )
    path = state.runs_dir / "state.json"
    data = json.loads(path.read_text())
    data["execution"]["version"] = 1
    path.write_text(json.dumps(data))
    before = {p.name: p.read_bytes() for p in state.runs_dir.iterdir()}

    with pytest.raises(ValueError, match="Unsupported execution version"):
        WorkflowEngine(tmp_path).resume(state.run_id)

    assert {p.name: p.read_bytes() for p in state.runs_dir.iterdir()} == before


@pytest.mark.parametrize(
    "mutation",
    [
        lambda tree: tree.update(version=99),
        lambda tree: tree["sequence"].update(nodes=[]),
        lambda tree: tree["sequence"]["nodes"][0].update(phase="nonsense"),
        lambda tree: tree["sequence"]["nodes"][0]["binding"].pop("workflow_dir"),
        lambda tree: tree["sequence"]["nodes"][0]["binding"].update(
            workflow_dir=42
        ),
        lambda tree: tree["sequence"]["nodes"][0]["binding"].update(
            workflow_dir={}
        ),
        lambda tree: tree["sequence"]["nodes"][0]["binding"].update(
            definition=42
        ),
    ],
)
def test_bad_checkpoint_rejected_without_writes(tmp_path, probe, mutation):
    install(
        tmp_path,
        definition(
            "child",
            [{"id": "wait", "type": "probe", "await": True}],
            inputs={"approve": {"type": "boolean", "default": False}},
        ),
    )
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [call(input={"approve": "{{ inputs.approve }}"})],
            inputs={"approve": {"type": "boolean", "default": False}},
        )
    )
    path = state.runs_dir / "state.json"
    data = json.loads(path.read_text())
    mutation(data["execution"])
    path.write_text(json.dumps(data))
    before = path.read_bytes()
    with pytest.raises(ValueError):
        WorkflowEngine(tmp_path).resume(state.run_id)
    assert path.read_bytes() == before


@pytest.mark.parametrize("index", [0, 1])
def test_unbound_workflow_children_rejected_without_writes(tmp_path, probe, index):
    install(tmp_path, definition("child", [{"id": "work", "type": "probe"}]))
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                call(id="first"),
                call(id="second"),
                {"id": "wait", "type": "probe", "await": True},
            ],
            inputs={"approve": {"type": "boolean", "default": False}},
        )
    )
    assert state.status == RunStatus.PAUSED
    path = state.runs_dir / "state.json"
    data = json.loads(path.read_text())
    data["execution"]["sequence"]["nodes"][index].pop("binding")
    path.write_text(json.dumps(data))
    before = path.read_bytes()

    with pytest.raises(ValueError):
        WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})

    assert path.read_bytes() == before


def test_completed_container_with_unfinished_child_rejected(tmp_path, probe):
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {
                    "id": "route",
                    "type": "if",
                    "condition": True,
                    "then": [{"id": "work", "type": "probe"}],
                },
                {"id": "wait", "type": "probe", "await": True},
            ],
            inputs={"approve": {"type": "boolean", "default": False}},
        )
    )
    path = state.runs_dir / "state.json"
    data = json.loads(path.read_text())
    data["execution"]["sequence"]["nodes"][0]["children"][0]["nodes"][0] = {
        "phase": "ready"
    }
    path.write_text(json.dumps(data))
    before = path.read_bytes()

    with pytest.raises(ValueError):
        WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})

    assert path.read_bytes() == before
    assert probe["work"] == 1


@pytest.mark.parametrize("child_phase", ["ready", "blocked"])
def test_completed_workflow_call_with_unfinished_child_rejected(
    tmp_path, probe, child_phase
):
    install(
        tmp_path,
        definition(
            "child",
            [{"id": "work", "type": "probe"}, {"id": "wait", "type": "probe", "await": True}],
            inputs={"approve": {"type": "boolean", "default": False}},
        ),
    )
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [call(input={"approve": "{{ inputs.approve }}"}), {"id": "pause", "type": "probe", "await": True}],
            inputs={"approve": {"type": "boolean", "default": False}},
        )
    )
    path = state.runs_dir / "state.json"
    data = json.loads(path.read_text())
    call_node = data["execution"]["sequence"]["nodes"][0]
    call_node.update(phase="done", outcome="completed")
    if child_phase == "ready":
        call_node["children"][0]["nodes"][1] = {"phase": "ready"}
    path.write_text(json.dumps(data))
    before = path.read_bytes()

    with pytest.raises(ValueError, match="Completed execution has unfinished children"):
        WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})

    assert path.read_bytes() == before


def test_handled_failed_workflow_call_can_retain_blocked_child(tmp_path, probe):
    install(
        tmp_path,
        definition(
            "child",
            [
                {"id": "fail", "type": "probe", "status": "failed"},
                {"id": "unreached", "type": "probe"},
            ],
        ),
    )

    state = WorkflowEngine(tmp_path).execute(
        definition("parent", [call(continue_on_error=True)])
    )

    assert state.status == RunStatus.COMPLETED
    assert state.step_results["call"]["status"] == "failed"
    assert RunState.load(state.run_id, tmp_path).status == RunStatus.COMPLETED


def test_bound_call_without_source_path_resumes_with_null_workflow_dir(
    tmp_path, monkeypatch, probe
):
    import specify_cli.workflows._execution as execution

    child = definition(
        "child",
        [{"id": "wait", "type": "probe", "await": True}],
        inputs={"approve": {"type": "boolean", "default": False}},
    )
    monkeypatch.setattr(execution, "resolve_target", lambda *_: child)
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [call(input={"approve": "{{ inputs.approve }}"})],
            inputs={"approve": {"type": "boolean", "default": False}},
        )
    )
    assert state.status == RunStatus.PAUSED
    assert state.execution["sequence"]["nodes"][0]["binding"]["workflow_dir"] is None

    state = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})

    assert state.status == RunStatus.COMPLETED


@pytest.mark.parametrize("failure_after_replace", [False, True])
def test_checkpoint_failure_leaves_running_run_not_resumable(
    tmp_path, monkeypatch, probe, failure_after_replace
):
    from specify_cli.workflows._execution import CheckpointError

    original = RunState._atomic_write_json
    failed = False

    def write(path, data):
        nonlocal failed
        record = data.get("step_results", {}).get("work")
        if path.name == "state.json" and record and not failed:
            failed = True
            if failure_after_replace:
                original(path, data)
            raise OSError("checkpoint failure")
        original(path, data)

    monkeypatch.setattr(RunState, "_atomic_write_json", staticmethod(write))
    with pytest.raises(CheckpointError, match="checkpoint failure"):
        WorkflowEngine(tmp_path).execute(
            definition("parent", [{"id": "work", "type": "probe"}]), run_id="fault"
        )
    disk = json.loads(
        (tmp_path / ".specify/workflows/runs/fault/state.json").read_text()
    )
    node = disk["execution"]["sequence"]["nodes"][0]
    assert node["phase"] == ("done" if failure_after_replace else "ready")
    assert ("work" in disk["step_results"]) is failure_after_replace
    with pytest.raises(
        ValueError, match="Cannot resume run 'fault' with status 'running'"
    ):
        WorkflowEngine(tmp_path).resume("fault")
    assert probe["work"] == 1


def _interrupt_state_write(monkeypatch, when):
    """Raise ``KeyboardInterrupt`` from the first ``state.json`` write matching *when*."""
    original = RunState._atomic_write_json
    fired = []

    def write(path, data):
        if path.name == "state.json" and not fired and when(data):
            fired.append(path)
            raise KeyboardInterrupt
        original(path, data)

    monkeypatch.setattr(RunState, "_atomic_write_json", staticmethod(write))
    return fired


def _logged_events(state):
    log = (state.runs_dir / "log.jsonl").read_text(encoding="utf-8").splitlines()
    return [json.loads(line)["event"] for line in log]


@pytest.mark.parametrize("scope", ["root", "workflow-call"])
def test_interrupt_during_checkpoint_pauses_run(tmp_path, monkeypatch, probe, scope):
    steps = [{"id": "first", "type": "probe"}, {"id": "second", "type": "probe"}]
    if scope == "workflow-call":
        install(tmp_path, definition("child", steps))
        steps = [call()]
    # Interrupt the checkpoint that marks ``second`` active, after ``first`` ran.
    fired = _interrupt_state_write(
        monkeypatch, lambda data: data.get("current_step_id") == "second"
    )

    state = WorkflowEngine(tmp_path).execute(definition("parent", steps))

    # A graceful interrupt is not a checkpoint failure: it reaches the engine's
    # pause path, even inside a called workflow.
    assert fired
    assert state.status == RunStatus.PAUSED
    assert RunState.load(state.run_id, tmp_path).status == RunStatus.PAUSED
    assert _logged_events(state)[-1] == "workflow_interrupted"
    assert probe == {"first": 1}

    state = WorkflowEngine(tmp_path).resume(state.run_id)

    assert state.status == RunStatus.COMPLETED
    assert probe == {"first": 1, "second": 1}


def test_interrupt_during_resume_checkpoint_pauses_run(tmp_path, monkeypatch, probe):
    root = definition(
        "parent",
        [
            {"id": "wait", "type": "probe", "await": True},
            {"id": "next", "type": "probe"},
        ],
        inputs={"approve": {"type": "boolean", "default": False}},
    )
    state = WorkflowEngine(tmp_path).execute(root)
    assert state.status == RunStatus.PAUSED
    # Interrupt the checkpoint that records ``wait`` as completed on resume.
    fired = _interrupt_state_write(
        monkeypatch,
        lambda data: data.get("step_results", {}).get("wait", {}).get("status")
        == "completed",
    )

    state = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})

    assert fired
    assert state.status == RunStatus.PAUSED
    assert RunState.load(state.run_id, tmp_path).status == RunStatus.PAUSED
    assert _logged_events(state)[-1] == "workflow_interrupted"

    state = WorkflowEngine(tmp_path).resume(state.run_id)

    # The interrupted checkpoint's transition is saved by the pause, so the
    # completed ``wait`` is not run a third time.
    assert state.status == RunStatus.COMPLETED
    assert probe == {"wait": 2, "next": 1}


@pytest.mark.parametrize("failure", [KeyboardInterrupt, RuntimeError])
def test_leave_failure_preserves_step_exception(tmp_path, monkeypatch, failure):
    from specify_cli.workflows._execution import Execution

    class Explode(StepBase):
        type_key = "explode"

        def execute(self, config, context):
            raise failure("boom")

    original_transition = Execution.transition

    def transition(self, operation, occurrence, *args, **kwargs):
        if operation == "leave":
            raise ValueError("leave failed")
        return original_transition(self, operation, occurrence, *args, **kwargs)

    monkeypatch.setitem(STEP_REGISTRY, "explode", Explode())
    monkeypatch.setattr(Execution, "transition", transition)
    engine = WorkflowEngine(tmp_path)
    root = definition("parent", [{"id": "work", "type": "explode"}])
    if failure is KeyboardInterrupt:
        state = engine.execute(root, run_id="leave-failure")
        assert state.status == RunStatus.PAUSED
        assert _logged_events(state)[-1] == "workflow_interrupted"
    else:
        with pytest.raises(RuntimeError, match="boom"):
            engine.execute(root, run_id="leave-failure")
        state = RunState.load("leave-failure", tmp_path)
        assert state.error == "boom"


def test_checkpoint_failure_stops_concurrent_fan_out_logging(tmp_path, monkeypatch):
    import specify_cli.workflows._execution as execution
    from specify_cli.workflows._execution import CheckpointError

    items = {}
    first_committed = threading.Event()
    second_failed = threading.Event()

    class Sync(StepBase):
        type_key = "sync"

        def execute(self, config, context):
            items[threading.current_thread()] = context.item
            if context.item == 2:
                assert first_committed.wait(5)
            return StepResult(output={"value": context.item})

    original_transition = execution.Execution.transition
    original_notify = execution.Execution.notify
    original_write = RunState._atomic_write_json

    def transition(self, *args, **kwargs):
        item = items.get(threading.current_thread())
        try:
            original_transition(self, *args, **kwargs)
        except CheckpointError:
            if item == 2:
                second_failed.set()
            raise

    def notify(self, operation, occurrence, **kwargs):
        if items.get(threading.current_thread()) == 1 and operation == "finish":
            # Item 1 committed and released the lock; item 2 now fails its
            # checkpoint before item 1 emits its completion event.
            first_committed.set()
            assert second_failed.wait(5)
        return original_notify(self, operation, occurrence, **kwargs)

    def write(path, data):
        if items.get(threading.current_thread()) == 2:
            raise OSError("disk full")
        original_write(path, data)

    monkeypatch.setitem(STEP_REGISTRY, "sync", Sync())
    monkeypatch.setattr(execution.Execution, "transition", transition)
    monkeypatch.setattr(execution.Execution, "notify", notify)
    monkeypatch.setattr(RunState, "_atomic_write_json", staticmethod(write))
    with pytest.raises(CheckpointError):
        WorkflowEngine(tmp_path).execute(
            definition(
                "parent",
                [
                    {
                        "id": "fan",
                        "type": "fan-out",
                        "items": [1, 2],
                        "max_concurrency": 2,
                        "step": {"type": "sync"},
                    }
                ],
            ),
            run_id="concurrent-fault",
        )

    assert second_failed.is_set()
    log = tmp_path / ".specify/workflows/runs/concurrent-fault/log.jsonl"
    events = [json.loads(line) for line in log.read_text().splitlines()]
    item_events = [
        (entry["event"], entry["step_id"])
        for entry in events
        if entry.get("step_id", "").startswith("fan:")
    ]
    assert sorted(item_events) == [
        ("step_started", "fan:item:0"),
        ("step_started", "fan:item:1"),
    ]


def test_completion_log_failure_does_not_replay_committed_step(
    tmp_path, monkeypatch, probe
):
    original = RunState.append_log
    failed = False

    def log(self, entry):
        nonlocal failed
        if entry["event"] == "step_completed" and not failed:
            failed = True
            raise OSError("log failed")
        original(self, entry)

    monkeypatch.setattr(RunState, "append_log", log)
    with pytest.raises(OSError, match="log failed"):
        WorkflowEngine(tmp_path).execute(
            definition("parent", [{"id": "work", "type": "probe"}]), run_id="log"
        )
    state = WorkflowEngine(tmp_path).resume("log")
    assert state.status == RunStatus.COMPLETED
    assert probe["work"] == 1


def test_container_completion_log_failure_does_not_replay_expansion(
    tmp_path, monkeypatch, probe
):
    original = RunState.append_log
    failed = False
    expanded = 0

    class Expand(StepBase):
        type_key = "expand"

        def execute(self, config, context):
            nonlocal expanded
            expanded += 1
            return StepResult(
                StepStatus.COMPLETED,
                next_steps=[{"id": "work", "type": "probe"}],
            )

    def log(self, entry):
        nonlocal failed
        if entry == {
            "event": "step_completed",
            "step_id": "expand",
            "status": "completed",
        } and not failed:
            failed = True
            raise OSError("log failed")
        original(self, entry)

    monkeypatch.setitem(STEP_REGISTRY, "expand", Expand())
    monkeypatch.setattr(RunState, "append_log", log)
    with pytest.raises(OSError, match="log failed"):
        WorkflowEngine(tmp_path).execute(
            definition("parent", [{"id": "expand", "type": "expand"}]),
            run_id="container-log",
        )

    state = WorkflowEngine(tmp_path).resume("container-log")

    assert state.status == RunStatus.COMPLETED
    assert expanded == 1
    assert probe["work"] == 1


@pytest.mark.parametrize("kind", ["if", "while", "do-while", "fan-out"])
def test_expansion_resume_preserves_completed_work(tmp_path, probe, kind):
    body = [
        {"id": "prepare", "type": "probe"},
        {"id": "wait", "type": "probe", "await": True},
    ]
    config = {"id": "outer", "type": kind, "condition": True, "max_iterations": 2}
    if kind == "if":
        config["then"] = body
    elif kind == "fan-out":
        config.update(
            items=[1, 2],
            max_concurrency=2,
            step={"id": "branch", "type": "if", "condition": True, "then": body},
        )
    else:
        config["steps"] = body
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [config],
            inputs={"approve": {"type": "boolean", "default": False}},
        )
    )
    assert state.status == RunStatus.PAUSED
    state = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})
    assert state.status == RunStatus.COMPLETED
    assert probe["prepare"] == (1 if kind == "if" else 2)


def test_replay_restores_fan_out_item_aliases_from_completed_if(tmp_path, probe):
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {
                    "id": "route",
                    "type": "if",
                    "condition": True,
                    "then": [
                        {
                            "id": "fan",
                            "type": "fan-out",
                            "items": [1],
                            "step": {
                                "id": "template",
                                "type": "probe",
                                "value": "{{ item }}",
                            },
                        }
                    ],
                },
                {"id": "wait", "type": "probe", "await": True},
                {
                    "id": "join",
                    "type": "fan-in",
                    "wait_for": ["fan"],
                    "output": {"merged": "{{ steps.fan.output.results }}"},
                },
            ],
            inputs={"approve": {"type": "boolean", "default": False}},
        )
    )
    assert state.status == RunStatus.PAUSED

    state = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})

    assert state.status == RunStatus.COMPLETED
    assert state.step_results["fan:template:0"]["output"] == {"value": 1}
    assert state.step_results["join"]["output"]["merged"] == [{"value": 1}]


def test_resume_restores_completed_fan_out_item_aliases(tmp_path, monkeypatch, probe):
    class PauseSecond(StepBase):
        type_key = "pause-second"

        def execute(self, config, context):
            if context.item == 2 and not context.inputs["approve"]:
                return StepResult(StepStatus.PAUSED)
            return StepResult(output={"value": context.item})

    monkeypatch.setitem(STEP_REGISTRY, "pause-second", PauseSecond())
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {
                    "id": "fan",
                    "type": "fan-out",
                    "items": [1, 2],
                    "step": {"id": "template", "type": "pause-second"},
                },
                {
                    "id": "join",
                    "type": "fan-in",
                    "wait_for": ["fan"],
                    "output": {"merged": "{{ steps.fan.output.results }}"},
                },
            ],
            inputs={"approve": {"type": "boolean", "default": False}},
        )
    )
    assert state.status == RunStatus.PAUSED

    state = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})

    assert state.status == RunStatus.COMPLETED
    assert state.step_results["fan:template:0"]["output"] == {"value": 1}
    assert state.step_results["fan:template:1"]["output"] == {"value": 2}
    assert state.step_results["join"]["output"]["merged"] == [
        {"value": 1},
        {"value": 2},
    ]


def test_fan_out_template_is_private_to_the_execution_tree(tmp_path, probe):
    template = {"id": "template", "type": "probe", "value": "{{ item }}"}
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {"id": "fan", "type": "fan-out", "items": [1, 2], "step": template},
                {"id": "wait", "type": "probe", "await": True},
                {"id": "join", "type": "fan-in", "wait_for": ["fan"]},
                {
                    "id": "read",
                    "type": "probe",
                    "value": "{{ steps.fan.output.step_template }}",
                },
            ],
            inputs={"approve": {"type": "boolean", "default": False}},
        )
    )
    assert state.status == RunStatus.PAUSED
    paused_output = RunState.load(state.run_id, tmp_path).step_results["fan"]["output"]

    state = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})

    assert state.status == RunStatus.COMPLETED
    # The template stays in the private execution source that drives the items.
    node = state.execution["sequence"]["nodes"][0]
    assert yaml.safe_load(node["template"]) == template
    item_results = [{"value": 1}, {"value": 2}]
    expected = {
        "items": [1, 2],
        "max_concurrency": 1,
        "item_count": 2,
        "results": item_results,
    }
    # It is published neither in the fan-out output (live, replayed, or
    # persisted) nor in a fan-in aggregate, and expressions cannot read it.
    for output in (
        paused_output,
        state.step_results["fan"]["output"],
        RunState.load(state.run_id, tmp_path).step_results["fan"]["output"],
    ):
        assert output == expected
    assert state.step_results["join"]["output"]["results"] == [expected]
    assert state.step_results["read"]["output"]["value"] is None


def test_replay_keeps_private_nested_fan_out_aliases_private(tmp_path, probe):
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {
                    "id": "outer",
                    "type": "fan-out",
                    "items": [1],
                    "step": {
                        "id": "outer-item",
                        "type": "fan-out",
                        "items": [1],
                        "step": {"id": "inner", "type": "probe"},
                    },
                },
                {"id": "wait", "type": "probe", "await": True},
            ],
            inputs={"approve": {"type": "boolean", "default": False}},
        )
    )
    assert state.status == RunStatus.PAUSED

    state = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})

    assert state.status == RunStatus.COMPLETED
    assert "outer:outer-item:0" in state.step_results
    assert "outer:outer-item:0:inner:0" not in state.step_results


def test_replay_does_not_execute_completed_fan_out_or_emit_callbacks(tmp_path, probe):
    callbacks = []
    engine = WorkflowEngine(tmp_path)
    engine.on_step_start = lambda step_id, _label: callbacks.append(step_id)
    root = definition(
        "parent",
        [
            {
                "id": "fan",
                "type": "fan-out",
                "items": [1, 2],
                "step": {
                    "id": "template",
                    "type": "probe",
                    "value": "{{ item }}",
                },
            },
            {"id": "wait", "type": "probe", "await": True},
        ],
        inputs={"approve": {"type": "boolean", "default": False}},
    )
    state = engine.execute(root)
    assert state.status == RunStatus.PAUSED
    assert probe == {"template": 2, "wait": 1}
    callbacks.clear()

    state = engine.resume(state.run_id, {"approve": True})

    assert state.status == RunStatus.COMPLETED
    assert probe == {"template": 2, "wait": 2}
    assert callbacks == ["wait"]
    assert [
        (entry["event"], entry["step_id"])
        for entry in state.log_entries
        if entry["event"] in {"step_started", "step_completed"}
    ] == [("step_started", "wait"), ("step_completed", "wait")]


def test_fan_out_item_aliases_are_projected_under_run_lock(tmp_path, monkeypatch):
    from specify_cli.workflows._execution import Execution

    class PauseSecond(StepBase):
        type_key = "pause-second"

        def execute(self, config, context):
            if context.item == 2 and not context.inputs["approve"]:
                return StepResult(StepStatus.PAUSED)
            return StepResult(output={"value": context.item})

    monkeypatch.setitem(STEP_REGISTRY, "pause-second", PauseSecond())
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {
                    "id": "fan",
                    "type": "fan-out",
                    "items": [1, 2],
                    "max_concurrency": 2,
                    "step": {"id": "template", "type": "pause-second"},
                }
            ],
            inputs={"approve": {"type": "boolean", "default": False}},
        )
    )
    assert state.status == RunStatus.PAUSED
    owned = []
    original = Execution.project_alias

    def spy(self, context, name, result):
        owned.append(self.state._lock._is_owned())
        return original(self, context, name, result)

    monkeypatch.setattr(Execution, "project_alias", spy)
    state = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})

    assert state.status == RunStatus.COMPLETED
    assert owned and all(owned)
    assert state.step_results["fan:template:0"]["output"] == {"value": 1}
    assert state.step_results["fan:template:1"]["output"] == {"value": 2}


def test_replay_does_not_start_worker_threads(tmp_path, monkeypatch, probe):
    import specify_cli.workflows._execution as execution

    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {
                    "id": "fan",
                    "type": "fan-out",
                    "items": [1, 2],
                    "max_concurrency": 2,
                    "step": {"id": "template", "type": "probe"},
                },
                {"id": "wait", "type": "probe", "await": True},
            ],
            inputs={"approve": {"type": "boolean", "default": False}},
        )
    )
    assert state.status == RunStatus.PAUSED

    class NoThreads:
        def __init__(self, *args, **kwargs):
            raise AssertionError("replay must not start worker threads")

    monkeypatch.setattr(execution, "ThreadPoolExecutor", NoThreads)
    state = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})

    assert state.status == RunStatus.COMPLETED
    assert probe == {"template": 2, "wait": 2}


def test_fan_out_without_children_survives_replay(tmp_path, probe):
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {"id": "fan", "type": "fan-out", "items": [1, 2], "step": {}},
                {"id": "wait", "type": "probe", "await": True},
            ],
            inputs={"approve": {"type": "boolean", "default": False}},
        )
    )
    assert state.status == RunStatus.PAUSED

    state = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})

    assert state.status == RunStatus.COMPLETED
    assert state.step_results["fan"]["output"]["results"] == []


def test_replay_does_not_evaluate_completed_loop_condition(
    tmp_path, monkeypatch, probe
):
    import specify_cli.workflows._execution as execution

    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {
                    "id": "loop",
                    "type": "do-while",
                    "condition": False,
                    "steps": [{"id": "work", "type": "probe"}],
                },
                {"id": "wait", "type": "probe", "await": True},
            ],
            inputs={"approve": {"type": "boolean", "default": False}},
        )
    )
    assert state.status == RunStatus.PAUSED
    monkeypatch.setattr(
        execution,
        "evaluate_condition",
        lambda *_: pytest.fail("replay must not evaluate loop conditions"),
    )

    state = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})

    assert state.status == RunStatus.COMPLETED
    assert probe == {"work": 1, "wait": 2}


def test_replay_does_not_commit_completed_nodes(tmp_path, monkeypatch, probe):
    import specify_cli.workflows._execution as execution

    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {"id": "done", "type": "probe"},
                {"id": "wait", "type": "probe", "await": True},
            ],
            inputs={"approve": {"type": "boolean", "default": False}},
        )
    )
    assert state.status == RunStatus.PAUSED
    original = execution.Execution.transition
    committed = []

    def transition(self, operation, occurrence, changes=None, **kwargs):
        if occurrence.node["phase"] == "done":
            committed.append(occurrence.node)
        return original(self, operation, occurrence, changes, **kwargs)

    monkeypatch.setattr(execution.Execution, "transition", transition)

    state = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})

    assert state.status == RunStatus.COMPLETED
    assert committed == []


def test_composed_fan_out_joins_container_results(tmp_path, probe):
    install(
        tmp_path,
        definition(
            "child",
            [
                {
                    "id": "fan",
                    "type": "fan-out",
                    "items": [1, 2],
                    "step": {
                        "id": "template",
                        "type": "probe",
                        "value": "{{ item }}",
                    },
                },
                {
                    "id": "join",
                    "type": "fan-in",
                    "wait_for": ["fan"],
                    "output": {"merged": "{{ steps.fan.output.results }}"},
                },
            ],
            outputs={"results": {"value": "{{ steps.join.output.merged }}"}},
        ),
    )

    state = WorkflowEngine(tmp_path).execute(definition("parent", [call()]))

    assert state.status == RunStatus.COMPLETED
    assert state.step_results["call"]["output"]["results"] == [
        {"value": 1},
        {"value": 2},
    ]
    assert "fan:template:0" not in state.step_results
    assert "fan:template:1" not in state.step_results


def test_fan_in_rejects_fan_out_item_alias():
    for alias in ("fan:template:0", "fan:template:not-an-item"):
        errors = validate_workflow(
            definition(
                "parent",
                [
                    {
                        "id": "fan",
                        "type": "fan-out",
                        "items": [1],
                        "step": {"id": "template", "type": "probe"},
                    },
                    {"id": "join", "type": "fan-in", "wait_for": [alias]},
                ],
            )
        )

        assert any("unknown or not-yet-declared" in error for error in errors), alias


def test_fan_in_rejects_item_alias_at_runtime():
    from specify_cli.workflows.base import StepContext
    from specify_cli.workflows.step.fan_in import FanInStep

    result = FanInStep().execute(
        {"id": "join", "type": "fan-in", "wait_for": ["fan:template:0"]},
        StepContext(),
    )

    assert result.status == StepStatus.FAILED
    assert "fan-out item alias" in (result.error or "")


def test_fan_in_container_join_in_loop_sees_current_iteration(tmp_path, monkeypatch, probe):
    calls = []

    class Varying(StepBase):
        type_key = "varying"

        def execute(self, config, context):
            calls.append(1)
            items = [10, 20] if len(calls) == 1 else [30, 40]
            return StepResult(output={"items": items})

    monkeypatch.setitem(STEP_REGISTRY, "varying", Varying())
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {
                    "id": "loop",
                    "type": "do-while",
                    "condition": True,
                    "max_iterations": 2,
                    "steps": [
                        {"id": "varying", "type": "varying"},
                        {
                            "id": "fan",
                            "type": "fan-out",
                            "items": "{{ steps.varying.output.items }}",
                            "step": {
                                "id": "template",
                                "type": "probe",
                                "value": "{{ item }}",
                            },
                        },
                        {
                            "id": "join",
                            "type": "fan-in",
                            "wait_for": ["fan"],
                            "output": {"merged": "{{ steps.fan.output.results }}"},
                        },
                    ],
                }
            ],
        )
    )

    assert state.status == RunStatus.COMPLETED
    assert state.step_results["join"]["output"]["merged"] == [
        {"value": 30},
        {"value": 40},
    ]


def test_fan_out_in_later_loop_iteration_uses_qualified_aliases(tmp_path, probe):
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {
                    "id": "loop",
                    "type": "do-while",
                    "condition": True,
                    "max_iterations": 2,
                    "steps": [
                        {
                            "id": "fan",
                            "type": "fan-out",
                            "items": [1, 2],
                            "step": {
                                "id": "template",
                                "type": "probe",
                                "value": "{{ item }}",
                            },
                        }
                    ],
                }
            ],
        )
    )

    assert state.status == RunStatus.COMPLETED
    assert state.step_results["fan:template:0"]["output"]["value"] == 1
    assert state.step_results["fan:template:1"]["output"]["value"] == 2
    assert state.step_results["loop:fan:1:template:0"]["output"]["value"] == 1
    assert state.step_results["loop:fan:1:template:1"]["output"]["value"] == 2


def test_fan_out_events_and_callbacks_use_qualified_item_ids(tmp_path, probe):
    callbacks = []
    engine = WorkflowEngine(tmp_path)
    engine.on_step_start = lambda step_id, _label: callbacks.append(step_id)

    state = engine.execute(
        definition(
            "parent",
            [
                {
                    "id": "fan",
                    "type": "fan-out",
                    "items": [1, 2],
                    "step": {"id": "template", "type": "probe"},
                }
            ],
        )
    )

    events = [
        (entry["event"], entry["step_id"])
        for entry in state.log_entries
        if entry["event"] in {"step_started", "step_completed"}
    ]
    assert callbacks == ["fan", "fan:template:0", "fan:template:1"]
    assert events == [
        ("step_started", "fan"),
        ("step_completed", "fan"),
        ("step_started", "fan:template:0"),
        ("step_completed", "fan:template:0"),
        ("step_started", "fan:template:1"),
        ("step_completed", "fan:template:1"),
    ]


def test_unnamed_fan_out_templates_use_item_id_for_results_and_events(tmp_path, probe):
    callbacks = []
    engine = WorkflowEngine(tmp_path)
    engine.on_step_start = lambda step_id, _label: callbacks.append(step_id)

    state = engine.execute(
        definition(
            "parent",
            [
                {
                    "id": "fan",
                    "type": "fan-out",
                    "items": [1],
                    "step": {"type": "probe", "value": "{{ item }}"},
                }
            ],
        )
    )

    item_events = [
        entry["step_id"]
        for entry in state.log_entries
        if entry["event"] in {"step_started", "step_completed"}
        and entry["step_id"].startswith("fan:")
    ]
    assert callbacks == ["fan", "fan:item:0"]
    assert item_events == ["fan:item:0", "fan:item:0"]
    assert state.step_results["fan:item:0"]["output"] == {"value": 1}


def test_loop_events_and_callbacks_use_qualified_iteration_ids(tmp_path, probe):
    callbacks = []
    engine = WorkflowEngine(tmp_path)
    engine.on_step_start = lambda step_id, _label: callbacks.append(step_id)

    state = engine.execute(
        definition(
            "parent",
            [
                {
                    "id": "loop",
                    "type": "do-while",
                    "condition": True,
                    "max_iterations": 2,
                    "steps": [{"id": "body", "type": "probe"}],
                }
            ],
        )
    )

    events = [
        (entry["event"], entry["step_id"])
        for entry in state.log_entries
        if entry["event"] in {"step_started", "step_completed"}
    ]
    assert callbacks == ["loop", "body", "loop:body:1"]
    assert events == [
        ("step_started", "loop"),
        ("step_completed", "loop"),
        ("step_started", "body"),
        ("step_completed", "body"),
        ("step_started", "loop:body:1"),
        ("step_completed", "loop:body:1"),
    ]


def test_private_scope_events_include_execution_path_and_workflow_id(tmp_path, probe):
    callbacks = []
    engine = WorkflowEngine(tmp_path)
    engine.on_step_start = lambda step_id, _label: callbacks.append(step_id)
    install(tmp_path, definition("child", [{"id": "work", "type": "probe"}]))
    state = engine.execute(definition("parent", [call()]))

    call_entries = [
        entry
        for entry in state.log_entries
        if entry.get("step_id") == "call" and entry["event"].startswith("step_")
    ]
    child_entries = [
        entry
        for entry in state.log_entries
        if entry.get("step_id") == "work" and entry["event"].startswith("step_")
    ]
    assert all("execution_path" not in entry for entry in call_entries)
    assert all("workflow_id" not in entry for entry in call_entries)
    assert all(entry["workflow_id"] == "child" for entry in child_entries)
    assert all(entry["execution_path"] == [0, "workflow", 0] for entry in child_entries)
    assert callbacks == ["call", "work"]


def test_completed_workflow_call_replay_emits_no_events(tmp_path, probe):
    callbacks = []
    engine = WorkflowEngine(tmp_path)
    engine.on_step_start = lambda step_id, _label: callbacks.append(step_id)
    install(tmp_path, definition("child", [{"id": "work", "type": "probe"}]))
    root = definition(
        "parent",
        [
            call(),
            {"id": "wait", "type": "probe", "await": True},
        ],
        inputs={"approve": {"type": "boolean", "default": False}},
    )

    state = engine.execute(root)
    assert state.status == RunStatus.PAUSED
    callbacks.clear()

    state = engine.resume(state.run_id, {"approve": True})

    events = [
        (entry["event"], entry["step_id"])
        for entry in state.log_entries
        if entry["event"] in {"step_started", "step_completed"}
    ]
    assert state.status == RunStatus.COMPLETED
    assert callbacks == ["wait"]
    assert events == [("step_started", "wait"), ("step_completed", "wait")]


def test_unfinished_workflow_call_emits_events_on_resume(tmp_path, probe):
    callbacks = []
    engine = WorkflowEngine(tmp_path)
    engine.on_step_start = lambda step_id, _label: callbacks.append(step_id)
    install(
        tmp_path,
        definition(
            "child",
            [{"id": "wait", "type": "probe", "await": True}],
            inputs={"approve": {"type": "boolean", "default": False}},
        ),
    )
    root = definition(
        "parent",
        [call(input={"approve": "{{ inputs.approve }}"})],
        inputs={"approve": {"type": "boolean", "default": False}},
    )

    state = engine.execute(root)
    assert state.status == RunStatus.PAUSED
    callbacks.clear()

    state = engine.resume(state.run_id, {"approve": True})

    events = [
        (entry["event"], entry["step_id"])
        for entry in state.log_entries
        if entry["event"] in {"step_started", "step_completed"}
    ]
    assert state.status == RunStatus.COMPLETED
    assert callbacks == ["call", "wait"]
    assert events == [
        ("step_started", "call"),
        ("step_started", "wait"),
        ("step_completed", "wait"),
        ("step_completed", "call"),
    ]


@pytest.mark.parametrize(
    "failure, expected",
    [(RuntimeError, RunStatus.FAILED), (KeyboardInterrupt, RunStatus.PAUSED)],
)
def test_resumed_call_discards_status_of_previous_attempt(
    tmp_path, monkeypatch, probe, failure, expected
):
    from specify_cli.workflows._execution import scope_summaries

    explode = {"enabled": True}

    class Explode(StepBase):
        type_key = "explode"

        def execute(self, config, context):
            if explode["enabled"]:
                raise failure("boom")
            return StepResult(StepStatus.COMPLETED)

    monkeypatch.setitem(STEP_REGISTRY, "explode", Explode())
    install(
        tmp_path,
        definition(
            "child",
            [
                {"id": "wait", "type": "probe", "await": True},
                {"id": "work", "type": "explode"},
            ],
            inputs={"approve": {"type": "boolean", "default": False}},
        ),
    )
    root = definition(
        "parent",
        [call(input={"approve": "{{ inputs.approve }}"})],
        inputs={"approve": {"type": "boolean", "default": False}},
    )
    engine = WorkflowEngine(tmp_path)
    state = engine.execute(root)
    assert state.status == RunStatus.PAUSED
    run_id = state.run_id

    if failure is RuntimeError:
        with pytest.raises(RuntimeError, match="boom"):
            engine.resume(run_id, {"approve": True})
    else:
        engine.resume(run_id, {"approve": True})

    state = RunState.load(run_id, tmp_path)
    node = state.execution["sequence"]["nodes"][0]
    assert state.status == expected
    assert node["phase"] == "children"
    assert not {"result", "outcome", "error"} & node.keys()
    assert scope_summaries(state.execution, state.status.value) == [
        {"scope_path": ["call"], "workflow_id": "child", "status": expected.value}
    ]

    explode["enabled"] = False
    state = engine.resume(run_id)
    assert state.status == RunStatus.COMPLETED
    assert state.step_results["call"]["output"]["status"] == "completed"
    assert probe["wait"] == 2


@pytest.mark.parametrize(
    "failure, expected",
    [(RuntimeError, RunStatus.FAILED), (KeyboardInterrupt, RunStatus.PAUSED)],
)
def test_retried_unbound_call_discards_status_of_failed_binding(
    tmp_path, monkeypatch, probe, failure, expected
):
    from specify_cli.workflows._execution import scope_summaries

    explode = {"enabled": True}

    class Explode(StepBase):
        type_key = "explode"

        def execute(self, config, context):
            if explode["enabled"]:
                raise failure("boom")
            return StepResult(StepStatus.COMPLETED)

    monkeypatch.setitem(STEP_REGISTRY, "explode", Explode())
    engine = WorkflowEngine(tmp_path)
    state = engine.execute(definition("parent", [call()]))
    run_id = state.run_id
    node = state.execution["sequence"]["nodes"][0]
    assert state.status == RunStatus.FAILED
    assert node["phase"] == "blocked"
    assert node["result"]["output"]["status"] == "failed"
    assert "binding" not in node

    # The target becomes available; the retry binds and its child then halts.
    install(tmp_path, definition("child", [{"id": "work", "type": "explode"}]))
    if failure is RuntimeError:
        with pytest.raises(RuntimeError, match="boom"):
            engine.resume(run_id)
    else:
        engine.resume(run_id)

    state = RunState.load(run_id, tmp_path)
    node = state.execution["sequence"]["nodes"][0]
    assert state.status == expected
    assert scope_summaries(state.execution, state.status.value) == [
        {"scope_path": ["call"], "workflow_id": "child", "status": expected.value}
    ]
    assert node["phase"] == "children"
    assert node["binding"]["workflow"] == "child"
    assert not {"result", "outcome", "error"} & node.keys()

    explode["enabled"] = False
    state = engine.resume(run_id)
    assert state.status == RunStatus.COMPLETED
    assert state.step_results["call"]["output"]["status"] == "completed"


def test_retried_unbound_call_that_fails_again_records_new_failure(tmp_path, probe):
    engine = WorkflowEngine(tmp_path)
    state = engine.execute(definition("parent", [call()]))
    assert state.status == RunStatus.FAILED

    state = engine.resume(state.run_id)

    node = state.execution["sequence"]["nodes"][0]
    assert state.status == RunStatus.FAILED
    assert node["phase"] == "blocked"
    assert "binding" not in node
    assert node["result"]["output"]["status"] == "failed"
    assert not probe


@pytest.mark.parametrize(
    "template, expected_event, status",
    [
        ({"status": "failed"}, "step_failed", RunStatus.FAILED),
        (
            {"status": "failed", "continue_on_error": True},
            "step_continue_on_error",
            RunStatus.COMPLETED,
        ),
        (
            {"status": "failed", "output": {"aborted": True}},
            "workflow_aborted",
            RunStatus.ABORTED,
        ),
    ],
)
def test_fan_out_failure_events_use_qualified_item_ids(
    tmp_path, probe, template, expected_event, status
):
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {
                    "id": "fan",
                    "type": "fan-out",
                    "items": [1],
                    "step": {"id": "template", "type": "probe", **template},
                }
            ],
        )
    )

    failures = [
        entry
        for entry in state.log_entries
        if entry["event"] in {
            "step_failed",
            "step_continue_on_error",
            "workflow_aborted",
        }
    ]
    assert state.status == status
    assert len(failures) == 1
    assert failures[0]["step_id"] == "fan:template:0"
    assert failures[0]["event"] == expected_event


@pytest.mark.parametrize("mode", ["unknown", "disabled", "mismatch", "cycle"])
def test_resolution_failures_are_call_failures(tmp_path, probe, mode):
    if mode != "unknown":
        child = definition(
            "child",
            [call("parent") if mode == "cycle" else {"id": "work", "type": "probe"}],
        )
        directory = install(tmp_path, child, enabled=mode != "disabled")
        if mode == "mismatch":
            child.data["workflow"]["id"] = "other"
            (directory / "workflow.yml").write_text(yaml.safe_dump(child.data))
    state = WorkflowEngine(tmp_path).execute(
        definition("parent", [call(continue_on_error=True)])
    )
    assert state.status == RunStatus.COMPLETED
    assert state.step_results["call"]["status"] == "failed"
    assert not probe


@pytest.mark.parametrize(
    "error, handled",
    [
        (ValueError("bad overlay"), True),
        (FileNotFoundError("gone"), True),
        (RuntimeError("resolver bug"), False),
    ],
)
def test_only_resolver_contract_errors_are_call_failures(
    tmp_path, monkeypatch, probe, error, handled
):
    from specify_cli.workflows.overlay.resolver import WorkflowResolver

    install(tmp_path, definition("child", [{"id": "work", "type": "probe"}]))

    def resolve(self, workflow_id):
        raise error

    monkeypatch.setattr(WorkflowResolver, "resolve", resolve)
    parent = definition("parent", [call(continue_on_error=True)])
    if handled:
        state = WorkflowEngine(tmp_path).execute(parent)
        assert state.status == RunStatus.COMPLETED
        assert state.step_results["call"]["status"] == "failed"
    else:
        with pytest.raises(RuntimeError, match="resolver bug"):
            WorkflowEngine(tmp_path).execute(parent)
    assert not probe


@pytest.mark.parametrize(
    "child_continue, call_continue", [(False, False), (True, False), (False, True)]
)
def test_unknown_child_step_is_a_reported_call_failure(
    tmp_path, monkeypatch, probe, child_continue, call_continue
):
    class TemporarilyInstalled(StepBase):
        type_key = "temporarily-installed"

        def execute(self, config, context):
            return StepResult(StepStatus.COMPLETED)

    monkeypatch.setitem(STEP_REGISTRY, "temporarily-installed", TemporarilyInstalled())
    install(
        tmp_path,
        definition(
            "child",
            [
                {"id": "wait", "type": "probe", "await": True},
                {
                    "id": "missing",
                    "type": "temporarily-installed",
                    "continue_on_error": child_continue,
                }
            ],
            inputs={"approve": {"type": "boolean", "default": False}},
        ),
    )
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                call(
                    input={"approve": "{{ inputs.approve }}"},
                    continue_on_error=call_continue,
                ),
                {"id": "after", "type": "probe"},
            ],
            inputs={"approve": {"type": "boolean", "default": False}},
        )
    )
    assert state.status == RunStatus.PAUSED
    monkeypatch.delitem(STEP_REGISTRY, "temporarily-installed")
    state = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})

    error = "Unknown step type: 'temporarily-installed'"
    events = [entry["event"] for entry in state.log_entries]
    # The missing step itself is terminal inside the child, as at the root.
    assert [
        entry["event"]
        for entry in state.log_entries
        if entry.get("step_id") == "missing" and entry.get("workflow_id") == "child"
    ] == ["step_started", "step_failed"]
    if call_continue:
        # At the call boundary it is a reported child failure.
        assert state.status == RunStatus.COMPLETED
        assert state.step_results["call"]["status"] == "failed"
        assert state.step_results["call"]["output"]["error"] == error
        assert probe == {"wait": 2, "after": 1}
        assert "step_continue_on_error" in events
    else:
        assert state.status == RunStatus.FAILED
        assert state.error == error
        assert probe == {"wait": 2}
        assert "step_continue_on_error" not in events


@pytest.mark.parametrize("call_continue", [False, True])
def test_unknown_child_step_at_bind_is_a_reported_call_failure(
    tmp_path, monkeypatch, probe, call_continue
):
    install(
        tmp_path,
        definition("child", [{"id": "missing", "type": "later-installed"}]),
    )
    parent = definition(
        "parent",
        [call(continue_on_error=call_continue), {"id": "after", "type": "probe"}],
    )
    state = WorkflowEngine(tmp_path).execute(parent, run_id="bind")

    assert "invalid type 'later-installed'" in state.step_results["call"]["error"]
    assert "binding" not in state.execution["sequence"]["nodes"][0]
    if call_continue:
        # Same treatment as an implementation that disappears after binding.
        assert state.status == RunStatus.COMPLETED
        assert state.step_results["call"]["status"] == "failed"
        assert probe == {"after": 1}
        return

    assert state.status == RunStatus.FAILED
    assert not probe

    class LaterInstalled(StepBase):
        type_key = "later-installed"

        def execute(self, config, context):
            return StepResult(StepStatus.COMPLETED)

    monkeypatch.setitem(STEP_REGISTRY, "later-installed", LaterInstalled())
    state = WorkflowEngine(tmp_path).resume("bind")

    assert state.status == RunStatus.COMPLETED
    assert state.step_results["call"]["status"] == "completed"
    assert probe == {"after": 1}


def test_step_reported_unknown_type_error_is_handled_like_any_failure(
    tmp_path, monkeypatch, probe
):
    class Mimic(StepBase):
        type_key = "mimic"

        def execute(self, config, context):
            return StepResult(StepStatus.FAILED, error="Unknown step type: 'mimic'")

    monkeypatch.setitem(STEP_REGISTRY, "mimic", Mimic())
    install(tmp_path, definition("child", [{"id": "work", "type": "mimic"}]))
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {"id": "direct", "type": "mimic", "continue_on_error": True},
                call(continue_on_error=True),
                {"id": "after", "type": "probe"},
            ],
        )
    )

    assert state.status == RunStatus.COMPLETED
    assert state.step_results["direct"]["status"] == "failed"
    assert state.step_results["call"]["status"] == "failed"
    assert probe == {"after": 1}


def test_unknown_step_type_resumes_after_reinstall(tmp_path, monkeypatch, probe):
    class Reinstalled(StepBase):
        type_key = "temporarily-installed"

        def execute(self, config, context):
            return StepResult(StepStatus.COMPLETED)

    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [{"id": "missing", "type": "temporarily-installed"}],
        ),
        run_id="reinstall",
    )
    assert state.status == RunStatus.FAILED

    monkeypatch.setitem(STEP_REGISTRY, "temporarily-installed", Reinstalled())
    state = WorkflowEngine(tmp_path).resume("reinstall")

    assert state.status == RunStatus.COMPLETED
    assert state.step_results["missing"]["status"] == "completed"


@pytest.mark.parametrize("workers", [1, 2])
@pytest.mark.parametrize("named", [False, True])
def test_unknown_fan_out_template_step_always_fails_despite_continue_on_error(
    tmp_path, monkeypatch, probe, workers, named
):
    local_name = "missing" if named else "step-0"
    alias_name = "missing" if named else "item"
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                # An inherited same-name result must not become the item result.
                {"id": local_name, "type": "probe", "value": "parent"},
                {
                    "id": "fan",
                    "type": "fan-out",
                    "items": [1, 2],
                    "max_concurrency": workers,
                    "step": {
                        **({"id": "missing"} if named else {}),
                        "type": "not-installed",
                        "continue_on_error": True,
                    },
                },
                {"id": "after", "type": "probe"},
            ],
        )
    )

    assert state.status == RunStatus.FAILED
    assert state.error == "Unknown step type: 'not-installed'"
    assert probe == {local_name: 1}
    assert set(state.step_results) == {local_name, "fan"}
    saved = RunState.load(state.run_id, tmp_path)
    assert saved.step_results == state.step_results
    assert saved.step_results["fan"]["output"]["results"] == [{}]
    events = [entry["event"] for entry in state.log_entries]
    assert "step_failed" in events
    assert "step_continue_on_error" not in events
    item_events = {}
    for entry in state.log_entries:
        if entry.get("step_id", "").startswith("fan:"):
            item_events.setdefault(entry["step_id"], []).append(entry["event"])
    assert item_events
    assert all(
        events == ["step_started", "step_failed"] for events in item_events.values()
    )

    class Reinstalled(StepBase):
        type_key = "not-installed"

        def execute(self, config, context):
            return StepResult(output={"value": context.item})

    monkeypatch.setitem(STEP_REGISTRY, "not-installed", Reinstalled())
    state = WorkflowEngine(tmp_path).resume(state.run_id)

    assert state.status == RunStatus.COMPLETED
    assert probe == {local_name: 1, "after": 1}
    assert state.step_results["fan"]["output"]["results"] == [
        {"value": 1}, {"value": 2}
    ]
    for index, value in enumerate([1, 2]):
        assert state.step_results[f"fan:{alias_name}:{index}"]["output"] == {
            "value": value
        }
    assert RunState.load(state.run_id, tmp_path).step_results == state.step_results


def test_diamond_and_depth_limit(tmp_path, probe):
    install(tmp_path, definition("leaf", [{"id": "work", "type": "probe"}]))
    for name in ("left", "right"):
        install(tmp_path, definition(name, [call("leaf")]))
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {**call("left"), "id": "left"},
                {**call("right"), "id": "right"},
            ],
        )
    )
    assert state.status == RunStatus.COMPLETED
    assert probe["work"] == 2
    for index in range(1, 18):
        install(
            tmp_path,
            definition(
                f"level-{index}",
                [call(f"level-{index + 1}")]
                if index < 17
                else [{"id": "too-deep", "type": "probe"}],
            ),
        )
    state = WorkflowEngine(tmp_path).execute(definition("parent", [call("level-1")]))
    assert state.status == RunStatus.FAILED
    assert "depth 16" in state.error
    assert probe["too-deep"] == 0


def test_output_validation_rejects_reserved_and_yaml_native_values(tmp_path, probe):
    from specify_cli.workflows.composition import require_json, validate_outputs

    circular = []
    circular.append(circular)
    for value in (circular, date(2026, 1, 1), {1: "key"}, float("nan")):
        with pytest.raises(ValueError, match="JSON-safe"):
            require_json(value)
    for outputs in (
        {"status": {"value": "oops"}},
        {"value": {"wrong": 1}},
        {"value": {"value": date(2026, 1, 1)}},
    ):
        assert validate_outputs(outputs)


def test_nested_gate_reporting_uses_active_occurrence(tmp_path, probe):
    from specify_cli.workflows._commands import _workflow_run_payload

    install(
        tmp_path,
        definition(
            "child",
            [{"id": "review", "type": "gate", "message": "Approve", "mode": "manual"}],
        ),
    )
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {
                    "id": "route",
                    "type": "if",
                    "condition": True,
                    "then": [call()],
                }
            ],
        )
    )
    assert state.status == RunStatus.PAUSED
    payload = _workflow_run_payload(RunState.load(state.run_id, tmp_path))
    # Private scopes report the child-relative occurrence ID (own namespace).
    assert payload["current_step_id"] == "review"
    assert payload["gate"]["step_id"] == "review"
    assert payload["gate"]["scope_path"] == ["route", "call"]
    assert payload["workflow_scopes"][0]["status"] == "paused"


@pytest.mark.parametrize("failure, expected", [
    (KeyboardInterrupt, "paused"),
    (RuntimeError, "failed"),
])
def test_interrupted_bound_call_reports_run_outcome(tmp_path, monkeypatch, probe, failure, expected):
    from specify_cli.workflows._commands import _workflow_run_payload

    class Explode(StepBase):
        type_key = "explode"

        def execute(self, config, context):
            raise failure("boom")

    monkeypatch.setitem(STEP_REGISTRY, "explode", Explode())
    install(tmp_path, definition("first", [{"id": "done", "type": "probe"}]))
    install(tmp_path, definition("child", [{"id": "work", "type": "explode"}]))
    engine = WorkflowEngine(tmp_path)
    root = definition("parent", [call("first", id="prior"), call()])
    if failure is RuntimeError:
        with pytest.raises(RuntimeError, match="boom"):
            engine.execute(root, run_id="interrupted-call")
    else:
        assert engine.execute(root, run_id="interrupted-call").status == RunStatus.PAUSED

    saved = RunState.load("interrupted-call", tmp_path)
    payload = _workflow_run_payload(saved)
    assert payload["status"] == expected
    assert payload["workflow_scopes"] == [
        {"scope_path": ["prior"], "workflow_id": "first", "status": "completed"},
        {"scope_path": ["call"], "workflow_id": "child", "status": expected},
    ]


def test_rebind_failure_has_one_failed_caller_outcome(tmp_path, probe):
    from specify_cli.workflows._execution import scope_summaries

    install(
        tmp_path,
        definition(
            "child",
            [{"id": "wait", "type": "probe", "await": True}],
            inputs={"approve": {"type": "boolean"}},
        ),
    )
    root = definition(
        "parent",
        [call(input={"approve": "{{ inputs.approve }}"}, continue_on_error=True)],
        inputs={"approve": {"type": "string", "default": "false"}},
    )
    state = WorkflowEngine(tmp_path).execute(root)
    assert state.status == RunStatus.PAUSED
    before = RunState.load(state.run_id, tmp_path).execution["sequence"]["nodes"][0]

    with pytest.raises(ValueError, match="expected a boolean"):
        WorkflowEngine(tmp_path).resume(state.run_id, {"approve": "invalid"})

    failed = RunState.load(state.run_id, tmp_path)
    node = failed.execution["sequence"]["nodes"][0]
    assert failed.status == RunStatus.FAILED
    # Invalid inputs fail the run, not the call: the re-entered call keeps its
    # binding and children and records no outcome of its own.
    assert node["phase"] == "children"
    assert not {"result", "outcome", "error"} & node.keys()
    assert node["binding"] == before["binding"]
    assert node["children"] == before["children"]
    assert scope_summaries(failed.execution, failed.status.value) == [
        {"scope_path": ["call"], "workflow_id": "child", "status": "failed"}
    ]
    assert WorkflowEngine(tmp_path).resume(
        state.run_id, {"approve": "true"}
    ).status == RunStatus.COMPLETED


@pytest.mark.parametrize("depth", [1, 2])
def test_verdict_input_remains_forbidden_through_calls_in_fan_out(
    tmp_path, probe, depth
):
    child = definition(
        "child",
        [
            {
                "id": "review",
                "type": "gate",
                "message": "Review",
                "verdict_input": "approve",
            }
        ],
        inputs={"approve": {"type": "string", "default": ""}},
    )
    install(tmp_path, child)
    if depth == 2:
        install(
            tmp_path,
            definition(
                "middle",
                [call("child", input={"approve": "{{ inputs.approve }}"})],
                inputs={"approve": {"type": "string", "default": ""}},
            ),
        )
    target = "middle" if depth == 2 else "child"
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {
                    "id": "fan",
                    "type": "fan-out",
                    "items": ["item"],
                    "step": {
                        "id": "call",
                        "type": "workflow",
                        "workflow": target,
                        "input": {"approve": ""},
                    },
                }
            ],
        )
    )

    assert state.status == RunStatus.FAILED
    assert "not supported inside fan-out templates" in state.error


def test_workflow_result_does_not_inherit_parent_defaults(tmp_path, probe):
    install(
        tmp_path,
        definition(
            "child",
            [{"id": "work", "type": "probe"}],
            workflow={
                "id": "child",
                "name": "child",
                "integration": "child",
                "model": "child-model",
                "options": {"x": 2},
            },
        ),
    )
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [call()],
            workflow={
                "id": "parent",
                "name": "parent",
                "integration": "parent",
                "model": "parent-model",
                "options": {"x": 1},
            },
        )
    )

    call_result = state.step_results["call"]
    assert call_result["integration"] is None
    assert call_result["model"] is None
    assert call_result["options"] == {}
    assert call_result["input"] == {}


def test_child_context_does_not_inherit_item_or_fan_in(tmp_path, probe):
    install(
        tmp_path,
        definition(
            "child",
            [
                {"id": "item", "type": "probe", "value": "{{ item }}"},
                {"id": "fan-in", "type": "probe", "value": "{{ fan_in }}"},
            ],
            outputs={
                "item": {"value": "{{ steps.item.output.value }}"},
                "fan-in": {"value": "{{ steps.fan-in.output.value }}"},
            },
        ),
    )

    state = WorkflowEngine(tmp_path).execute(definition("parent", [call()]))

    assert state.status == RunStatus.COMPLETED
    assert state.step_results["call"]["output"] == {
        "workflow": "child",
        "status": "completed",
        "item": None,
        "fan-in": {},
    }


def test_rebind_keeps_unmapped_auto_input(tmp_path, probe):
    marker = tmp_path / ".specify" / "integration.json"
    marker.parent.mkdir()
    marker.write_text('{"version": 1, "default_integration": "first"}')
    install(
        tmp_path,
        definition(
            "child",
            [{"id": "wait", "type": "probe", "await": True}],
            inputs={
                "approve": {"type": "boolean", "default": False},
                "integration": {"type": "string", "default": "auto"},
            },
        ),
    )
    root = definition(
        "parent",
        [call(input={"approve": "{{ inputs.approve }}"})],
        inputs={"approve": {"type": "boolean", "default": False}},
    )
    state = WorkflowEngine(tmp_path).execute(root)
    assert state.status == RunStatus.PAUSED
    marker.write_text('{"version": 1, "default_integration": "second"}')

    state = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})

    assert state.status == RunStatus.COMPLETED
    binding = state.execution["sequence"]["nodes"][0]["binding"]
    assert binding["inputs"] == {"approve": True, "integration": "first"}


@pytest.mark.parametrize("change", ["disable", "uninstall"])
def test_bound_call_uses_snapshot_after_target_changes(tmp_path, probe, change):
    child = definition(
        "child",
        [{"id": "wait", "type": "probe", "await": True}],
        inputs={"approve": {"type": "boolean", "default": False}},
    )
    directory = install(tmp_path, child)
    root = definition(
        "parent",
        [call(input={"approve": "{{ inputs.approve }}"})],
        inputs={"approve": {"type": "boolean", "default": False}},
    )
    state = WorkflowEngine(tmp_path).execute(root)
    assert state.status == RunStatus.PAUSED
    if change == "disable":
        from specify_cli.workflows.catalog import WorkflowRegistry

        WorkflowRegistry(tmp_path).add("child", {"version": "1.0.0", "enabled": False})
    else:
        directory.rename(tmp_path / "removed-child")

    resumed = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})

    assert resumed.status == RunStatus.COMPLETED


@pytest.mark.parametrize("change", ["disable", "uninstall"])
def test_unbound_call_checks_target_when_resume_reaches_it(tmp_path, probe, change):
    child = definition("child", [{"id": "work", "type": "probe"}])
    directory = install(tmp_path, child)
    root = definition(
        "parent",
        [
            {
                "id": "wait",
                "type": "gate",
                "message": "Wait",
                "verdict_input": "approve",
            },
            call(continue_on_error=True),
        ],
        inputs={"approve": {"type": "string", "default": ""}},
    )
    state = WorkflowEngine(tmp_path).execute(root)
    assert state.status == RunStatus.PAUSED
    if change == "disable":
        from specify_cli.workflows.catalog import WorkflowRegistry

        WorkflowRegistry(tmp_path).add("child", {"version": "1.0.0", "enabled": False})
    else:
        directory.rename(tmp_path / "removed-child")

    resumed = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": "approve"})

    assert resumed.status == RunStatus.COMPLETED
    assert resumed.step_results["call"]["status"] == "failed"
    assert not probe


@pytest.mark.parametrize(
    "status,handled", [("failed", False), ("paused", False), ("failed", True)]
)
def test_unsuccessful_expansion_never_executes_children(
    tmp_path, monkeypatch, probe, status, handled
):
    class Expand(StepBase):
        type_key = "expand"

        def execute(self, config, context):
            return StepResult(
                StepStatus(status), next_steps=[{"id": "wrong", "type": "probe"}]
            )

    monkeypatch.setitem(STEP_REGISTRY, "expand", Expand())
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {
                    "id": "expand",
                    "type": "expand",
                    "continue_on_error": handled,
                }
            ],
        )
    )
    assert state.status.value == ("completed" if handled else status)
    assert not probe
    RunState.load(state.run_id, tmp_path)


def test_custom_expansion_is_frozen_across_resume(tmp_path, monkeypatch, probe):
    class Expand(StepBase):
        type_key = "expand"

        def execute(self, config, context):
            probe["expand"] += 1
            return StepResult(
                StepStatus.COMPLETED,
                next_steps=[
                    {"id": f"prefix-{probe['expand']}", "type": "probe"},
                    {"id": "wait", "type": "probe", "await": True},
                ],
            )

    monkeypatch.setitem(STEP_REGISTRY, "expand", Expand())
    root = definition(
        "parent",
        [{"id": "expand", "type": "expand"}],
        inputs={"approve": {"type": "boolean", "default": False}},
    )
    state = WorkflowEngine(tmp_path).execute(root)
    state = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})
    assert state.status == RunStatus.COMPLETED
    assert probe == {"expand": 1, "prefix-1": 1, "wait": 2}


def test_native_yaml_definition_and_long_id_roundtrip(tmp_path, probe):
    target = "a" * 240
    child = definition(
        target, [{"id": "review", "type": "gate", "message": date(2026, 1, 1)}]
    )
    install(tmp_path, child)
    state = WorkflowEngine(tmp_path).execute(definition("parent", [call(target)]))
    assert state.status == RunStatus.PAUSED
    saved = RunState.load(state.run_id, tmp_path)
    binding = saved.execution["sequence"]["nodes"][0]["binding"]
    assert yaml.safe_load(binding["definition"])["steps"][0]["message"] == date(
        2026, 1, 1
    )
    assert WorkflowEngine(tmp_path).resume(state.run_id).status == RunStatus.PAUSED


@pytest.mark.parametrize("scope", ["root", "if", "workflow", "fan-out"])
def test_yaml_native_gate_template_survives_checkpoint_and_resume(tmp_path, monkeypatch, scope):
    monkeypatch.setattr("sys.stdin.isatty", lambda: False)
    gate = {"id": "wait", "type": "gate", "message": date(2026, 1, 1)}
    steps = [gate]
    if scope == "if":
        steps = [{"id": "branch", "type": "if", "condition": True, "then": steps}]
    elif scope == "workflow":
        install(tmp_path, definition("child", steps))
        steps = [call()]
    elif scope == "fan-out":
        steps = [{"id": "fan", "type": "fan-out", "items": [0, 1], "step": gate}]
    engine = WorkflowEngine(tmp_path)
    state = engine.execute(definition("parent", steps))
    assert state.status == RunStatus.PAUSED
    state = engine.resume(state.run_id)
    assert state.status == RunStatus.PAUSED
    from specify_cli.workflows._execution import walk_execution

    gates = [config for config, _, _, _ in walk_execution(state.execution["sequence"])
             if config.get("type") == "gate"]
    assert gates and all(config["message"] == date(2026, 1, 1) for config in gates)


@pytest.mark.parametrize("offset", [1, 2, 3])
def test_resume_rejects_offset_skipping_blocked_step_without_writes(tmp_path, probe, offset):
    steps = [{"id": "wait", "type": "probe", "await": True},
             {"id": "later", "type": "probe"}]
    engine = WorkflowEngine(tmp_path)
    state = engine.execute(definition("parent", steps))
    path = state.runs_dir / "state.json"
    data = json.loads(path.read_text())
    data["execution"].update(offset=offset, sequence={
        "source": yaml.safe_dump(steps[offset:]),
        "nodes": [{"phase": "ready"} for _ in steps[offset:]],
    })
    path.write_text(json.dumps(data))
    before = {p.name: p.read_bytes() for p in state.runs_dir.iterdir()}
    with pytest.raises(ValueError, match="offset"):
        engine.resume(state.run_id)
    assert {p.name: p.read_bytes() for p in state.runs_dir.iterdir()} == before
    assert probe == {"wait": 1}


@pytest.mark.parametrize("scope", ["step", "if", "workflow", "fan-out"])
def test_lifecycle_start_is_tree_backed_and_replay_does_not_restart(tmp_path, probe, scope):
    from specify_cli.workflows._execution import walk_execution

    work = {"id": "work", "type": "probe"}
    steps = [work]
    if scope == "if":
        steps = [{"id": "branch", "type": "if", "condition": True, "then": steps}]
    elif scope == "workflow":
        install(tmp_path, definition("child", steps))
        steps = [call()]
    elif scope == "fan-out":
        steps = [{"id": "fan", "type": "fan-out", "items": [0, 1],
                  "max_concurrency": 2, "step": work}]
    steps.append({"id": "wait", "type": "probe", "await": True})
    engine = WorkflowEngine(tmp_path)
    announced = []

    def started(step_id, label):
        saved = RunState.load("lifecycle", tmp_path)
        matches = [node for _, node, _, name in walk_execution(saved.execution["sequence"])
                   if name == step_id]
        assert any(node.get("active") for node in matches)
        announced.append(step_id)

    engine.on_step_start = started
    state = engine.execute(definition("parent", steps), run_id="lifecycle")
    assert state.status == RunStatus.PAUSED
    assert all(not node.get("active") for _, node, _, _ in walk_execution(state.execution["sequence"]))
    before = probe.copy()
    announced.clear()
    engine.resume(state.run_id)
    assert announced == ["wait"]
    assert probe["work"] == before["work"]


@pytest.mark.parametrize("mutation", [
    lambda node: node.update(active=True),
    lambda node: node.update(active="yes"),
    lambda node: node.update(template="- invalid\n"),
    lambda node: node.update(fan_results={}),
    lambda node: node.update(fan_results={"a": 1}),
])
def test_lifecycle_rejects_invalid_completed_fan_out_without_writes(tmp_path, probe, mutation):
    engine = WorkflowEngine(tmp_path)
    state = engine.execute(definition("parent", [
        {"id": "fan", "type": "fan-out", "items": [0],
         "step": {"id": "work", "type": "probe"}},
        {"id": "wait", "type": "probe", "await": True},
    ]))
    path = state.runs_dir / "state.json"
    data = json.loads(path.read_text())
    mutation(data["execution"]["sequence"]["nodes"][0])
    path.write_text(json.dumps(data))
    before = {p.name: p.read_bytes() for p in state.runs_dir.iterdir()}
    with pytest.raises(ValueError):
        engine.resume(state.run_id)
    assert {p.name: p.read_bytes() for p in state.runs_dir.iterdir()} == before


@pytest.mark.parametrize("field,value", [("fan_results", []), ("template", "{}\n")])
def test_non_fan_out_rejects_fan_out_fields(tmp_path, probe, field, value):
    state = WorkflowEngine(tmp_path).execute(definition("parent", [
        {"id": "work", "type": "probe"},
        {"id": "wait", "type": "probe", "await": True},
    ]))
    path = state.runs_dir / "state.json"
    data = json.loads(path.read_text())
    data["execution"]["sequence"]["nodes"][0][field] = value
    path.write_text(json.dumps(data))
    before = {p.name: p.read_bytes() for p in state.runs_dir.iterdir()}

    with pytest.raises(ValueError, match="Invalid fan-out"):
        WorkflowEngine(tmp_path).resume(state.run_id)

    assert {p.name: p.read_bytes() for p in state.runs_dir.iterdir()} == before


@pytest.mark.parametrize("invalid", ["restart-completed", "override-phase", "finish-unfinished", "foreign-field"])
def test_lifecycle_rejects_invalid_transitions_before_mutation(tmp_path, probe, invalid):
    from copy import deepcopy
    from specify_cli.workflows._execution import Execution, Occurrence
    from specify_cli.workflows.base import StepContext

    config = {"id": "branch", "type": "if", "condition": True,
              "then": [{"id": "wait", "type": "probe", "await": True}]}
    engine = WorkflowEngine(tmp_path)
    state = engine.execute(definition("parent", [config]))
    node = state.execution["sequence"]["nodes"][0]
    occurrence = Occurrence(config, node, StepContext(), ("parent",), (0,), True, "branch")
    executor = Execution(engine, state, STEP_REGISTRY)
    if invalid == "restart-completed":
        occurrence = Occurrence(
            {"id": "done", "type": "probe"},
            {"phase": "done", "result": {"status": "completed", "output": {}}},
            StepContext(), ("parent",), (0,), True, "done",
        )
        operation, changes = "begin", {}
    elif invalid == "override-phase":
        operation, changes = "begin", {"phase": "done"}
    elif invalid == "foreign-field":
        operation, changes = "iterate", {"result": {"status": "completed", "output": {}}}
    else:
        operation, changes = "settle", {"outcome": "completed", "error": None}
    before_node = deepcopy(occurrence.node)
    before_files = {p.name: p.read_bytes() for p in state.runs_dir.iterdir()}
    with pytest.raises(ValueError):
        executor.transition(operation, occurrence, changes)
    assert occurrence.node == before_node
    assert {p.name: p.read_bytes() for p in state.runs_dir.iterdir()} == before_files


def test_execution_shares_workflow_fan_out_and_loop_sources(tmp_path, probe):
    child = definition(
        "child",
        [{"id": "work", "type": "probe"}],
    )
    install(tmp_path, child)
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                call(),
                {
                    "id": "fan",
                    "type": "fan-out",
                    "items": [1, 2],
                    "step": {"id": "item", "type": "probe"},
                },
                {
                    "id": "loop",
                    "type": "do-while",
                    "condition": True,
                    "max_iterations": 2,
                    "steps": [{"id": "body", "type": "probe"}],
                },
                {"id": "wait", "type": "probe", "await": True},
            ],
        )
    )

    tree = json.loads((state.runs_dir / "state.json").read_text())["execution"]
    call_node, fan_node, loop_node, _ = tree["sequence"]["nodes"]
    assert "source" not in call_node["children"][0]
    assert "source" not in fan_node["children"][0]
    assert "source" not in fan_node["children"][1]
    assert "source" in loop_node["children"][0]
    assert "source" not in loop_node["children"][1]
    assert yaml.safe_load(call_node["binding"]["definition"])["steps"] == [
        {"id": "work", "type": "probe"}
    ]
    RunState.load(state.run_id, tmp_path)


@pytest.mark.parametrize(
    "mutation",
    [
        lambda tree: tree["sequence"]["nodes"][0]["children"][0].update(
            source="[]\n"
        ),
        lambda tree: tree["sequence"]["nodes"][1]["children"][0].update(
            source="[]\n"
        ),
        lambda tree: tree["sequence"]["nodes"][2]["children"][1].update(
            source="[]\n"
        ),
        lambda tree: tree["sequence"]["nodes"][0]["children"][0]["nodes"].append(
            {"phase": "ready"}
        ),
    ],
)
def test_shared_execution_sources_reject_local_copies(tmp_path, probe, mutation):
    child = definition("child", [{"id": "work", "type": "probe"}])
    install(tmp_path, child)
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                call(),
                {
                    "id": "fan",
                    "type": "fan-out",
                    "items": [1],
                    "step": {"id": "item", "type": "probe"},
                },
                {
                    "id": "loop",
                    "type": "do-while",
                    "condition": True,
                    "max_iterations": 2,
                    "steps": [{"id": "body", "type": "probe"}],
                },
                {"id": "wait", "type": "probe", "await": True},
            ],
        )
    )
    path = state.runs_dir / "state.json"
    data = json.loads(path.read_text())
    mutation(data["execution"])
    path.write_text(json.dumps(data))
    before = path.read_bytes()

    with pytest.raises(ValueError, match="Invalid execution sequence"):
        WorkflowEngine(tmp_path).resume(state.run_id)

    assert path.read_bytes() == before


@pytest.mark.parametrize("items", [1, 4])
def test_fan_out_saves_once_per_item_transition(tmp_path, monkeypatch, probe, items):
    original = RunState.save
    saves = 0

    def save(self):
        nonlocal saves
        saves += 1
        original(self)

    monkeypatch.setattr(RunState, "save", save)
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {
                    "id": "fan",
                    "type": "fan-out",
                    "items": list(range(items)),
                    "max_concurrency": 1,
                    "step": {"id": "item", "type": "probe"},
                }
            ],
        )
    )

    assert state.status == RunStatus.COMPLETED
    # Each started occurrence (fan and items) is checkpointed before it runs,
    # and each item result once more before it is done.
    assert saves == 2 * items + 6


def test_fan_out_snapshot_size_does_not_scale_with_template_length(tmp_path, probe):
    def size(items, length):
        root = tmp_path / f"fan-{items}-{length}"
        state = WorkflowEngine(root).execute(
            definition(
                "parent",
                [
                    {
                        "id": "fan",
                        "type": "fan-out",
                        "items": list(range(items)),
                        "max_concurrency": 1,
                        "step": {
                            "id": "item",
                            "type": "probe",
                            "payload": "x" * length,
                        },
                    }
                ],
            )
        )
        return (state.runs_dir / "state.json").stat().st_size

    small_one, large_one = size(1, 128), size(1, 4096)
    small_many, large_many = size(4, 128), size(4, 4096)

    assert large_many - small_many <= large_one - small_one + 256


def test_loop_snapshot_size_does_not_scale_with_body_length(tmp_path, probe):
    def size(iterations, length):
        root = tmp_path / f"loop-{iterations}-{length}"
        state = WorkflowEngine(root).execute(
            definition(
                "parent",
                [
                    {
                        "id": "loop",
                        "type": "do-while",
                        "condition": True,
                        "max_iterations": iterations,
                        "steps": [
                            {
                                "id": "body",
                                "type": "probe",
                                "payload": "x" * length,
                            }
                        ],
                    }
                ],
            )
        )
        return (state.runs_dir / "state.json").stat().st_size

    small_one, large_one = size(1, 128), size(1, 4096)
    small_many, large_many = size(4, 128), size(4, 4096)

    assert large_many - small_many <= large_one - small_one + 256


def test_loop_transition_validation_does_not_rewalk_prior_iterations(
    tmp_path, monkeypatch, probe
):
    import specify_cli.workflows._execution as execution

    original = execution.yaml.safe_load
    counts = []

    def parse(source):
        counts[-1] += 1
        return original(source)

    monkeypatch.setattr(execution.yaml, "safe_load", parse)
    for iterations in (20, 40):
        counts.append(0)
        state = WorkflowEngine(tmp_path / str(iterations)).execute(
            definition("parent", [{
                "id": "loop", "type": "do-while", "condition": True,
                "max_iterations": iterations,
                "steps": [{"id": "body", "type": "probe"}],
            }])
        )
        assert state.status == RunStatus.COMPLETED
    assert counts[1] < counts[0] * 2.5


def test_tree_backed_resume_has_no_setup_checkpoint(tmp_path, monkeypatch, probe):
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [{"id": "wait", "type": "probe", "await": True}],
            inputs={"approve": {"type": "boolean", "default": False}},
        )
    )
    original = RunState.save
    saves = 0

    def save(self):
        nonlocal saves
        saves += 1
        original(self)

    monkeypatch.setattr(RunState, "save", save)
    state = WorkflowEngine(tmp_path).resume(state.run_id, {"approve": True})

    assert state.status == RunStatus.COMPLETED
    # Restarting ``wait`` persists it as active before it runs, then its result.
    assert saves == 4


def test_exact_depth_limit_is_allowed(tmp_path, probe):
    for index in range(1, 17):
        install(
            tmp_path,
            definition(
                f"level-{index}",
                [call(f"level-{index + 1}")]
                if index < 16
                else [{"id": "work", "type": "probe"}],
            ),
        )
    state = WorkflowEngine(tmp_path).execute(definition("parent", [call("level-1")]))
    assert state.status == RunStatus.COMPLETED
    assert probe["work"] == 1


@pytest.mark.parametrize(
    "template",
    [
        {"id": "mixed", "type": "mixed"},
        {
            "id": "mixed",
            "type": "if",
            "condition": True,
            "then": [{"id": "inner", "type": "mixed"}],
        },
        call("child", id="mixed", input={"n": "{{ item }}"}),
    ],
    ids=["step", "if-container", "workflow-call"],
)
def test_aborted_fanout_sibling_is_never_restarted(tmp_path, monkeypatch, template):
    barrier = threading.Barrier(2, timeout=5)
    counts = Counter()

    class Mixed(StepBase):
        type_key = "mixed"

        def execute(self, config, context):
            item = context.item if context.item is not None else context.inputs["n"]
            counts[item] += 1
            if not context.is_resume:
                barrier.wait()
            if item == 0:
                return StepResult(
                    StepStatus.COMPLETED if context.is_resume else StepStatus.PAUSED
                )
            return StepResult(StepStatus.FAILED, output={"aborted": True})

    monkeypatch.setitem(STEP_REGISTRY, "mixed", Mixed())
    install(
        tmp_path,
        definition(
            "child",
            [{"id": "inner", "type": "mixed"}],
            inputs={"n": {"type": "number"}},
        ),
    )
    root = definition(
        "parent",
        [
            {
                "id": "spread",
                "type": "fan-out",
                "items": [0, 1],
                "max_concurrency": 2,
                "step": template,
            }
        ],
    )
    state = WorkflowEngine(tmp_path).execute(root)
    assert state.status == RunStatus.PAUSED
    state = WorkflowEngine(tmp_path).resume(state.run_id)
    assert state.status == RunStatus.ABORTED
    assert counts == {0: 2, 1: 1}
    # Replaying the aborted item keeps the result it published when it ran.
    published = state.step_results["spread:mixed:1"]["output"]
    assert published
    for results in (
        state.step_results["spread"]["output"]["results"],
        RunState.load(state.run_id, tmp_path).step_results["spread"]["output"][
            "results"
        ],
    ):
        assert results[1] == published


FAN_OUT_ITEM_TEMPLATES = [
    {"id": "tmpl", "type": "snap"},
    {
        "id": "tmpl",
        "type": "if",
        "condition": True,
        "then": [{"id": "inner", "type": "snap"}],
    },
    call("child", id="tmpl", input={"n": "{{ item }}"}),
]
FAN_OUT_ITEM_TEMPLATE_IDS = ["step", "if-container", "workflow-call"]


@pytest.mark.parametrize("max_concurrency", [1, 3], ids=["sequential", "parallel"])
@pytest.mark.parametrize(
    "template", FAN_OUT_ITEM_TEMPLATES, ids=FAN_OUT_ITEM_TEMPLATE_IDS
)
def test_resumed_fan_out_item_sees_its_uninterrupted_context(
    tmp_path, monkeypatch, probe, template, max_concurrency
):
    """Exact resume must re-run a fan-out item in the context it has in a run
    that never paused. Replay reconstructs item contexts from the checkpoint,
    so any difference (for example, a result the live run adds only after its
    items) is a live/replay gap."""
    from dataclasses import asdict

    pause = {"enabled": False}
    seen = {}

    class Snap(StepBase):
        type_key = "snap"

        def execute(self, config, context):
            item = context.item if context.item is not None else context.inputs["n"]
            view = asdict(context)
            del view["run_id"], view["is_resume"]
            phase = "resume" if context.is_resume else pause["enabled"]
            seen.setdefault(phase, {})[item] = view
            if item == 1 and pause["enabled"] and not context.is_resume:
                return StepResult(StepStatus.PAUSED, output={"item": item})
            return StepResult(output={"item": item})

    monkeypatch.setitem(STEP_REGISTRY, "snap", Snap())
    install(
        tmp_path,
        definition(
            "child",
            [{"id": "inner", "type": "snap"}],
            inputs={"n": {"type": "number"}},
        ),
    )
    root = definition(
        "parent",
        [
            {"id": "setup", "type": "probe", "value": "ready"},
            {
                "id": "fan",
                "type": "fan-out",
                "items": [0, 1, 2],
                "max_concurrency": max_concurrency,
                "step": template,
            },
        ],
    )
    state = WorkflowEngine(tmp_path).execute(root)
    assert state.status == RunStatus.COMPLETED
    pause["enabled"] = True
    state = WorkflowEngine(tmp_path).execute(root)
    assert state.status == RunStatus.PAUSED

    state = WorkflowEngine(tmp_path).resume(state.run_id)

    assert state.status == RunStatus.COMPLETED
    resumed = seen["resume"]
    assert 1 in resumed
    for item, view in resumed.items():
        assert view == seen[False][item], f"item {item} context differs on resume"


def test_resumed_fan_out_items_do_not_see_partial_results(tmp_path, monkeypatch):
    seen = []

    class Look(StepBase):
        type_key = "look"

        def execute(self, config, context):
            seen.append("results" in context.steps["fan"]["output"])
            if context.item == 1 and not context.is_resume:
                return StepResult(StepStatus.PAUSED, output={"item": 1})
            return StepResult(output={"item": context.item})

    monkeypatch.setitem(STEP_REGISTRY, "look", Look())
    root = definition(
        "parent",
        [
            {
                "id": "fan",
                "type": "fan-out",
                "items": [0, 1, 2],
                "step": {"id": "look", "type": "look"},
            }
        ],
    )
    state = WorkflowEngine(tmp_path).execute(root)
    assert state.status == RunStatus.PAUSED
    # The paused fan-out still reports its partial results.
    assert state.step_results["fan"]["output"]["results"] == [{"item": 0}, {"item": 1}]

    state = WorkflowEngine(tmp_path).resume(state.run_id)

    assert state.status == RunStatus.COMPLETED
    # Items never see the engine-added results: not live, not after resume.
    assert seen == [False, False, False, False]
    assert state.step_results["fan"]["output"]["results"] == [
        {"item": 0},
        {"item": 1},
        {"item": 2},
    ]


NAN_SNAPSHOT = """
schema_version: "1.0"
workflow:
  id: nan-snapshot
  name: NaN Snapshot
  version: "1.0.0"
inputs:
  approve:
    type: boolean
    default: false
steps:
  - id: fan
    type: fan-out
    items: [1, 2]
    max_concurrency: .nan
    step:
      type: probe
      value: "{{ item }}"
  - id: wait
    type: probe
    await: true
"""


def test_resume_accepts_native_yaml_nan_in_snapshot(tmp_path, probe):
    state = WorkflowEngine(tmp_path).execute(
        WorkflowDefinition.from_string(NAN_SNAPSHOT), run_id="nan"
    )
    assert state.status == RunStatus.PAUSED
    copy = tmp_path / ".specify/workflows/runs/nan/workflow.yml"
    data = yaml.safe_load(copy.read_text(encoding="utf-8"))
    # Key order is not part of the snapshot identity.
    data["steps"][0] = dict(reversed(list(data["steps"][0].items())))
    copy.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")

    state = WorkflowEngine(tmp_path).resume("nan", {"approve": True})

    assert state.status == RunStatus.COMPLETED, state.error
    assert state.step_results["fan"]["output"]["results"] == [
        {"value": 1}, {"value": 2}
    ]
    assert probe == {"item": 2, "wait": 2}


def test_resume_rejects_changed_workflow_snapshot(tmp_path, probe):
    state = WorkflowEngine(tmp_path).execute(
        WorkflowDefinition.from_string(NAN_SNAPSHOT), run_id="changed"
    )
    assert state.status == RunStatus.PAUSED
    copy = tmp_path / ".specify/workflows/runs/changed/workflow.yml"
    data = yaml.safe_load(copy.read_text(encoding="utf-8"))
    data["steps"][0]["items"] = [1, 2, 3]
    copy.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")

    with pytest.raises(ValueError, match="root sequence differs"):
        WorkflowEngine(tmp_path).resume("changed", {"approve": True})

def test_paused_fan_out_item_reports_qualified_current_step_id(tmp_path, probe):
    callbacks = []
    engine = WorkflowEngine(tmp_path)
    engine.on_step_start = lambda step_id, _label: callbacks.append(step_id)

    state = engine.execute(
        definition(
            "parent",
            [
                {
                    "id": "fan",
                    "type": "fan-out",
                    "items": [1],
                    "step": {"id": "item", "type": "probe", "status": "paused"},
                }
            ],
        )
    )

    assert state.status == RunStatus.PAUSED
    assert state.current_step_id == "fan:item:0"
    assert "fan:item:0" in state.step_results
    assert RunState.load(state.run_id, tmp_path).current_step_id == "fan:item:0"
    assert callbacks[-1] == "fan:item:0"


def test_paused_later_loop_iteration_reports_qualified_current_step_id(
    tmp_path, monkeypatch
):
    calls = Counter()

    class PauseSecond(StepBase):
        type_key = "pause-second"

        def execute(self, config, context):
            calls[config["id"]] += 1
            if calls[config["id"]] == 2:
                return StepResult(StepStatus.PAUSED)
            return StepResult(output={})

    monkeypatch.setitem(STEP_REGISTRY, "pause-second", PauseSecond())
    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {
                    "id": "loop",
                    "type": "do-while",
                    "condition": True,
                    "max_iterations": 3,
                    "steps": [{"id": "body", "type": "pause-second"}],
                }
            ],
        )
    )

    assert state.status == RunStatus.PAUSED
    assert state.current_step_id == "loop:body:1"
    assert "loop:body:1" in state.step_results
    assert RunState.load(state.run_id, tmp_path).current_step_id == "loop:body:1"


@pytest.mark.parametrize(
    ("steps", "expected"),
    [
        (
            [{"id": "first", "type": "probe"}, {"id": "observe", "type": "observe"}],
            [("observe", 1)],
        ),
        (
            [
                {"id": "first", "type": "probe"},
                {
                    "id": "loop",
                    "type": "do-while",
                    "condition": True,
                    "max_iterations": 2,
                    "steps": [{"id": "observe", "type": "observe"}],
                },
            ],
            [("observe", 1), ("loop:observe:1", 1)],
        ),
        (
            [
                {"id": "first", "type": "probe"},
                {
                    "id": "fan",
                    "type": "fan-out",
                    "items": [1, 2],
                    "step": {"id": "observe", "type": "observe"},
                },
            ],
            [("fan:observe:0", 1), ("fan:observe:1", 1)],
        ),
    ],
    ids=["root", "later-loop-iteration", "fan-out-item"],
)
def test_running_step_is_persisted_before_it_executes(
    tmp_path, monkeypatch, probe, steps, expected
):
    seen = []

    class Observe(StepBase):
        type_key = "observe"

        def execute(self, config, context):
            persisted = RunState.load(context.run_id, tmp_path)
            seen.append((persisted.current_step_id, persisted.current_step_index))
            return StepResult(output={})

    monkeypatch.setitem(STEP_REGISTRY, "observe", Observe())

    state = WorkflowEngine(tmp_path).execute(definition("parent", steps))

    assert state.status == RunStatus.COMPLETED
    assert seen == expected


def _record_persisted_step_on_start(engine, tmp_path, seen):
    """Record the persisted ``current_step_id`` whenever a step start is announced."""

    def on_step_start(step_id, label):
        (path,) = (tmp_path / ".specify/workflows/runs").glob("*/state.json")
        persisted = json.loads(path.read_text(encoding="utf-8"))["current_step_id"]
        seen.append((step_id, label, persisted))

    engine.on_step_start = on_step_start
    return engine


def test_workflow_call_is_persisted_before_it_starts(tmp_path, probe):
    install(tmp_path, definition("grandchild", [{"id": "leaf", "type": "probe"}]))
    install(
        tmp_path,
        definition(
            "child",
            [
                {"id": "prepare", "type": "probe"},
                {"id": "nested", "type": "workflow", "workflow": "grandchild"},
            ],
        ),
    )
    seen = []
    engine = _record_persisted_step_on_start(WorkflowEngine(tmp_path), tmp_path, seen)

    state = engine.execute(definition("parent", [{"id": "first", "type": "probe"}, call()]))

    assert state.status == RunStatus.COMPLETED
    # Like every other step, a call (top-level and nested inside a called
    # workflow, by its workflow-relative ID) is checkpointed as the active step
    # before its start is logged and announced.
    assert seen == [
        ("first", "probe", "first"),
        ("call", "workflow", "call"),
        ("prepare", "probe", "prepare"),
        ("nested", "workflow", "nested"),
        ("leaf", "probe", "leaf"),
    ]


def test_resumed_bound_workflow_call_is_persisted_before_it_starts(tmp_path, probe):
    install(
        tmp_path,
        definition(
            "child",
            [{"id": "wait", "type": "probe", "await": True}],
            inputs={"approve": {"type": "boolean", "default": False}},
        ),
    )
    root = definition(
        "parent",
        [call(input={"approve": "{{ inputs.approve }}"})],
        inputs={"approve": {"type": "boolean", "default": False}},
    )
    state = WorkflowEngine(tmp_path).execute(root)
    assert state.status == RunStatus.PAUSED
    assert RunState.load(state.run_id, tmp_path).current_step_id == "wait"
    seen = []
    engine = _record_persisted_step_on_start(WorkflowEngine(tmp_path), tmp_path, seen)

    state = engine.resume(state.run_id, {"approve": True})

    assert state.status == RunStatus.COMPLETED
    # The already-bound call skips binding, which previously held the only
    # pre-child checkpoint; it must still persist itself before re-announcing.
    assert seen == [("call", "workflow", "call"), ("wait", "probe", "wait")]


def test_workflow_call_start_checkpoint_failure_logs_no_start(tmp_path, monkeypatch, probe):
    from specify_cli.workflows._execution import CheckpointError

    install(tmp_path, definition("child", [{"id": "inner", "type": "probe"}]))
    original = RunState._atomic_write_json

    def write(path, data):
        if path.name == "state.json" and data.get("current_step_id") == "call":
            raise OSError("checkpoint failure")
        original(path, data)

    monkeypatch.setattr(RunState, "_atomic_write_json", staticmethod(write))
    callbacks = []
    engine = WorkflowEngine(tmp_path)
    engine.on_step_start = lambda step_id, label: callbacks.append(step_id)

    with pytest.raises(CheckpointError, match="checkpoint failure"):
        engine.execute(
            definition("parent", [{"id": "first", "type": "probe"}, call()]),
            run_id="fault",
        )

    runs = tmp_path / ".specify/workflows/runs/fault"
    started = [
        entry["step_id"]
        for entry in map(json.loads, (runs / "log.jsonl").read_text().splitlines())
        if entry["event"] == "step_started"
    ]
    disk = json.loads((runs / "state.json").read_text())
    node = disk["execution"]["sequence"]["nodes"][1]
    # The failed start checkpoint is not followed by a start event, a callback,
    # or target binding.
    assert started == ["first"]
    assert callbacks == ["first"]
    assert disk["current_step_id"] == "first"
    assert node["phase"] == "ready"
    assert "binding" not in node
    assert probe["inner"] == 0


def test_failed_fan_out_item_exception_reports_qualified_current_step_id(
    tmp_path, monkeypatch
):
    class Boom(StepBase):
        type_key = "boom"

        def execute(self, config, context):
            raise RuntimeError("boom")

    monkeypatch.setitem(STEP_REGISTRY, "boom", Boom())
    engine = WorkflowEngine(tmp_path)
    with pytest.raises(RuntimeError, match="boom"):
        engine.execute(
            definition(
                "parent",
                [
                    {
                        "id": "fan",
                        "type": "fan-out",
                        "items": [1],
                        "step": {"id": "blast", "type": "boom"},
                    }
                ],
            ),
            run_id="boom",
        )

    loaded = RunState.load("boom", tmp_path)
    assert loaded.status == RunStatus.FAILED
    assert loaded.current_step_id == "fan:blast:0"


def test_paused_fan_out_gate_payload_reports_qualified_step_id(tmp_path):
    from specify_cli.workflows._commands import _workflow_run_payload

    state = WorkflowEngine(tmp_path).execute(
        definition(
            "parent",
            [
                {
                    "id": "fan",
                    "type": "fan-out",
                    "items": [1],
                    "step": {"id": "review", "type": "gate", "message": "Approve"},
                }
            ],
        )
    )

    assert state.status == RunStatus.PAUSED
    payload = _workflow_run_payload(RunState.load(state.run_id, tmp_path))
    assert payload["current_step_id"] == "fan:review:0"
    assert payload["gate"]["step_id"] == "fan:review:0"
    assert payload["gate"]["message"] == "Approve"


def test_gate_message_keeps_typed_template_result(tmp_path):
    from specify_cli.workflows._commands import _workflow_run_payload

    workflow = definition(
        "parent",
        [{"id": "gate", "type": "gate", "message": "{{ inputs.notice }}"}],
        inputs={"notice": {"type": "number"}},
    )
    assert validate_workflow(workflow) == []

    state = WorkflowEngine(tmp_path).execute(workflow, {"notice": 42})

    assert state.status == RunStatus.PAUSED
    loaded = RunState.load(state.run_id, tmp_path)
    message = loaded.step_results["gate"]["output"]["message"]
    assert message == 42
    assert isinstance(message, int)
    assert _workflow_run_payload(loaded)["gate"]["message"] == "42"


def test_gate_message_stores_non_json_literal_as_text(tmp_path):
    state = WorkflowEngine(tmp_path).execute(
        definition("parent", [{"id": "gate", "type": "gate", "message": date(2026, 1, 1)}])
    )

    assert state.status == RunStatus.PAUSED
    loaded = RunState.load(state.run_id, tmp_path)
    assert loaded.step_results["gate"]["output"]["message"] == "2026-01-01"


def test_fan_out_worker_exception_stops_dispatch_before_earlier_items_finish(
    tmp_path, monkeypatch
):
    from types import SimpleNamespace

    from specify_cli.workflows import _execution

    halted_seen = threading.Event()

    class ObservedEvent(threading.Event):
        def set(self):
            super().set()
            halted_seen.set()

    monkeypatch.setattr(_execution, "threading", SimpleNamespace(Event=ObservedEvent))
    started = set()
    lock = threading.Lock()

    class Blow(StepBase):
        type_key = "blow"

        def execute(self, config, context):
            with lock:
                started.add(context.item)
            if context.item == 2:
                raise RuntimeError("boom")
            if context.item in {0, 1}:
                # Earlier items finish only after the failure halts dispatch.
                halted_seen.wait(2)
            return StepResult(output={"value": context.item})

    monkeypatch.setitem(STEP_REGISTRY, "blow", Blow())
    with pytest.raises(RuntimeError, match="boom"):
        WorkflowEngine(tmp_path).execute(
            definition(
                "parent",
                [
                    {
                        "id": "fan",
                        "type": "fan-out",
                        "items": [0, 1, 2, 3, 4, 5],
                        "max_concurrency": 3,
                        "step": {"id": "item", "type": "blow"},
                    }
                ],
            )
        )

    assert started == {0, 1, 2}