PSA/ee/docs/plans/2026-06-09-temporal-only-workflow-engine/PRD.md

PRD: Temporal-only workflow engine

Design: ../2026-06-09-temporal-only-workflow-engine-design.md Branch: fix/workflow-replay-noop

Problem

Workflow runtime V2 ships two execution engines — Temporal and a legacy DB-polling engine — selected per-process by environment flags. The API server and the workflow worker can disagree about which engine is live, and the Temporal producer and worker can resolve different task queues. Either mismatch strands new runs: a workflow_runs row is created, stays RUNNING with zero steps, and the operator experiences the Run/Replay button as doing nothing. A customer reported exactly this (with video); internal testing on a correctly-configured stack could not reproduce it.

Adjacent defects in the same surface: the Run Studio shows Retry/Resume/ Requeue buttons that hard-fail with 409 on Temporal runs; Replay submits the redacted input_json as an explicit payload override when redaction is configured; and a queued-but-unworked run gives no visual indication that anything is wrong.

User value

Operators get a run/replay surface where every visible control works on every run, misconfiguration can no longer silently strand runs, and a genuinely stuck run announces itself instead of impersonating a healthy one.

Goals

1. Temporal is the only execution engine; no flag combination can produce a run that nothing executes.
2. One task queue constant shared by producer and worker; no env override.
3. Legacy DB-only run controls (retry/resume/requeue) and the dead DB interpreter are deleted, not stranded as dead code.
4. Replay never submits redacted payloads and lands the operator on the new run.
5. Runs that are queued but unworked for >60s are visibly flagged.
6. Stranded non-Temporal runs in existing databases are finalized honestly (CANCELED with an explanatory error).
7. Every EE compose stack includes Temporal; the overlay file disappears.

Non-goals

• Temporal-native retry-from-failed-step (Replay is the recovery path).
• Re-launching historical stranded runs on Temporal.
• Deleting the engine column, 'db' historical values, or the workflow_run_snapshots table (kept for reading pre-cutover runs).
• Refactoring the Temporal interpreter/activities themselves.
• New monitoring/alerting beyond the in-app stuck-run banner.

Primary flows

1. Run now: designer or runs-list → Run dialog → startWorkflowRunAction → launchPublishedWorkflowRun → always engine='temporal', always client.workflow.start on the contract task queue → navigate to run page.
2. Replay: run details → Replay → unedited payload sends nothing (server uses original unredacted input_json); edited payload sends the edit → new Temporal run → UI navigates to it.
3. Cancel / quota resume: always the Temporal signal path.
4. Stuck run: run page shows "queued, waiting for worker" banner when RUNNING + zero steps + age > 60s.

Data / migration

One Knex migration: workflow_runs where engine is null or 'db' and status in (RUNNING,WAITING) → status='CANCELED', completed_at=now(), error_json noting the temporal-only cutover; resolve their open workflow_run_waits. Terminal rows untouched.

Risks

• Test rewrite breadth: ~60–80 e2e/integration cases drive the DB executor directly; rewrites must preserve coverage of run semantics, not just delete it. Mitigation: the ~50-case Temporal interpreter suite already covers step semantics; migrate only control-surface tests.
• Hidden DB-engine dependents: any deployment or script still setting WORKFLOW_RUNTIME_V2_ENABLE_TEMPORAL_POLLING=false will now run Temporal regardless. Compose defaults are updated in this change; external/infra repos must be swept separately.
• Migration on large tables: status update is bounded by an index on status; affected rows expected to be few.

Acceptance criteria

• grep -r WORKFLOW_RUNTIME_V2_ENABLE over the repo returns nothing (code, compose, tests).
• No code path writes engine other than 'temporal'.
• Producer and worker both compile against the single task-queue constant; the env var is gone.
• Retry/Resume/Requeue buttons, actions, and routes are gone; Replay, Cancel, Export remain and work on Temporal runs.
• Unedited Replay of a redaction-configured run executes with the original payload (verified by run input of the new run).
• Replay navigates to the new run.
• A run with zero steps older than 60s renders the queued-warning banner.
• Migration cancels a seeded stranded run and resolves its waits; leaves terminal rows and Temporal runs untouched.
• docker compose -f docker-compose.ee.yaml brings up a stack where a manually started workflow executes end to end.
• Full test suite green.