Skip to content

Self-improving AI Employees for everyone

fix(deployment): fire a deployment's Start node once per generation

trohitgb4656c220d90
diff --git a/docs-internal/temporal-workflow-control.md b/docs-internal/temporal-workflow-control.md
index 0c57f7b2..02d747d0 100644
--- a/docs-internal/temporal-workflow-control.md
+++ b/docs-internal/temporal-workflow-control.md
@@ -652,8 +652,10 @@ the control plane is hardened against Temporal's per-run event-history ceiling
in-process collectors for non-canary trigger types, and the paused posture
(admission, trigger pause flags, cron schedule pause). Re-arm is idempotent:
controller `register_trigger` is keyed by listener id, legacy listener
- starts use `USE_EXISTING`, and cron schedule creation preserves server-owned
- pause state. Listener and Schedule ids use the slug the generation's Start
+ starts use `USE_EXISTING`, cron schedule creation preserves server-owned
+ pause state, and a Start node fires once per generation (its first fire
+ records a `generation_start` claim in the runtime mutation ledger, which
+ every later deploy of the same generation finds; RFC-0004 C4). Listener and Schedule ids use the slug the generation's Start
recorded in its snapshot (`workflow_slug`), not the saved one, so a rename
while it runs cannot give the re-arm a second set of ids. That slug stays
taken while the generation lives (`next_available_slug` skips it), and a
diff --git a/server/services/deployment/manager.py b/server/services/deployment/manager.py
index 540a5c26..77a1ce5b 100644
--- a/server/services/deployment/manager.py
+++ b/server/services/deployment/manager.py
@@ -545,8 +545,28 @@ class DeploymentManager:
return TriggerInfo(node_id, "cron", job_id=schedule_id)
async def _fire_start_trigger(self, node: Dict, workflow_id: str) -> TriggerInfo:
- """Fire a start trigger immediately."""
+ """Fire a start trigger, once per generation.
+
+ A generation is deployed again whenever the backend restarts and
+ re-arms it, and the Start node's run must not run again each time
+ (RFC-0004 C4). The first fire records a claim in the runtime
+ mutation ledger; a later deploy of the same generation finds it and
+ skips. Deploys outside a generation (0) fire every time, as before.
+ """
node_id = node["id"]
+ generation = self._deployments[workflow_id].generation
+ if generation > 0:
+ _, first_fire = await self.database.run_runtime_mutation(
+ resource_type="generation_start",
+ resource_id=f"{workflow_id}:g{generation}",
+ operation="fire",
+ mutation_id=f"start:{workflow_id}:g{generation}:{node_id}",
+ mutate=lambda _session: {"node_id": node_id},
+ )
+ if not first_fire:
+ logger.info("Start node already fired for this generation",
+ workflow_id=workflow_id, generation=generation, node_id=node_id)
+ return TriggerInfo(node_id, "start")
params = await self.database.get_node_parameters(node_id) or {}
initial_data_str = params.get("initial_data", "{}")
diff --git a/server/tests/services/test_start_node_once_per_generation.py b/server/tests/services/test_start_node_once_per_generation.py
new file mode 100644
index 00000000..e32ffab3
--- /dev/null
+++ b/server/tests/services/test_start_node_once_per_generation.py
@@ -0,0 +1,66 @@
+"""A deployment's Start node fires once per generation (RFC-0004 C4).
+
+Every backend restart deploys a running generation again to re-arm it,
+and the Start node's run used to start again each time. The first fire
+now records a claim in the runtime mutation ledger.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+
+from services.deployment.manager import DeploymentManager
+from services.deployment.state import DeploymentState
+
+
+def _deployed(database, generation: int) -> DeploymentManager:
+ broadcaster = MagicMock()
+ broadcaster.update_node_status = AsyncMock()
+ manager = DeploymentManager(
+ database=database,
+ execute_workflow_fn=AsyncMock(),
+ store_output_fn=AsyncMock(),
+ broadcaster=broadcaster,
+ )
+ manager._spawn_run = AsyncMock()
+ manager._deployments["wf-1"] = DeploymentState(
+ deployment_id="deploy-1",
+ workflow_id="wf-1",
+ is_running=True,
+ nodes=[],
+ edges=[],
+ session_id="session",
+ generation=generation,
+ )
+ return manager
+
+
+async def test_a_restart_does_not_fire_the_start_node_again(real_database):
+ first = _deployed(real_database, generation=3)
+ assert (await first._fire_start_trigger({"id": "start-1"}, "wf-1")).fired is True
+
+ # The backend restarts and a new manager re-arms generation 3.
+ rearmed = _deployed(real_database, generation=3)
+ info = await rearmed._fire_start_trigger({"id": "start-1"}, "wf-1")
+
+ assert first._spawn_run.await_count == 1
+ rearmed._spawn_run.assert_not_awaited()
+ assert info.fired is False
+
+
+async def test_a_new_generation_fires_the_start_node_again(real_database):
+ await _deployed(real_database, generation=3)._fire_start_trigger({"id": "start-1"}, "wf-1")
+ next_generation = _deployed(real_database, generation=4)
+
+ await next_generation._fire_start_trigger({"id": "start-1"}, "wf-1")
+
+ next_generation._spawn_run.assert_awaited_once()
+
+
+async def test_a_deploy_outside_a_generation_fires_every_time(real_database):
+ manager = _deployed(real_database, generation=0)
+
+ await manager._fire_start_trigger({"id": "start-1"}, "wf-1")
+ await manager._fire_start_trigger({"id": "start-1"}, "wf-1")
+
+ assert manager._spawn_run.await_count == 2