PSA/ee/docs/plans/2026-04-09-workflow-v2-runtime-worker-ownership-split/PRD.md

# PRD — Workflow V2 Runtime Worker Ownership Split

- Slug: `workflow-v2-runtime-worker-ownership-split`
- Date: `2026-04-09`
- Status: Draft
- Parent context:
  - `ee/docs/plans/2026-04-08-workflow-v2-temporal-native-runtime/`
  - `ee/docs/plans/2026-04-08-workflow-v2-temporal-hard-cutover-remediation/`

## Summary

Move authored Workflow Runtime V2 Temporal execution out of `temporal-worker` and into `workflow-worker`, then repair the package/runtime layering so the authored runtime has a clean worker-safe core surface and a separate bootstrap surface.

The intended end state is:

- `workflow-worker` owns authored Workflow Runtime V2 Temporal execution on queue `workflow-runtime-v2`
- `workflow-worker` continues to own workflow event-stream ingress and other authored-workflow support duties
- `temporal-worker` continues to own non-authored/domain Temporal workflows only
- `@alga-psa/workflows` stops exposing a mixed runtime/bootstrap boundary that drags app-only or source-layout-specific dependencies into standalone worker startup

## Problem

The current authored runtime placement and package shape create both operational confusion and concrete boot failures.

### 1. Wrong operational ownership for authored workflows
A manually started authored workflow launches successfully into Temporal, but Temporal UI shows no worker polling the `workflow-runtime-v2` queue. Today that queue is effectively tied to `temporal-worker`, even though authored workflow ingress, projections, and support duties already live with `workflow-worker`.

This splits authored workflow responsibility across two workers and makes debugging harder:

- authored workflow event ingress lives in `workflow-worker`
- authored runtime execution lives in `temporal-worker`
- domain/job Temporal workflows also live in `temporal-worker`

The result is unclear ownership and slower diagnosis when authored runs stall.

### 2. The current workflow runtime package boundary is not real enough for a standalone worker
The current `@alga-psa/workflows/runtime` surface mixes:

- runtime core exports
- AI/bootstrap wiring
- email/action registration side effects
- repo-relative imports into `shared/...` and `packages/ee/src/...`
- path alias assumptions such as `@shared/*`

That package shape works in app/source mode, but it is not a stable worker-safe boundary. Built artifacts are still coupled to repo layout and transitive app concerns.

### 3. Temporal worker startup failures are exposing the architectural issue
The immediate failures seen in local runtime validation are symptoms of the deeper boundary problem:

- dist artifacts reaching back into repo source structure
- worker startup pulling in modules unrelated to authored runtime execution
- path alias and dist/export mismatches surfacing only in standalone worker mode

If left unfixed, this will continue to make authored runtime execution brittle across local, CI, and deployment environments.

## Goals

1. Make `workflow-worker` the permanent execution owner of authored Workflow Runtime V2 Temporal runs.
2. Keep `temporal-worker` responsible only for non-authored/domain Temporal workflows.
3. Preserve a single-process `workflow-worker` model that handles both authored workflow support duties and authored Temporal queue polling.
4. Split `@alga-psa/workflows` into a clean worker-safe runtime core surface and a separate bootstrap/app-wiring surface.
5. Eliminate source-layout-relative and unresolved alias dependencies from authored runtime startup paths.
6. Make local and deployed authored workflow execution operationally intuitive: authored runtime issues should be diagnosable from `workflow-worker` first.

## Non-goals

- Full package extraction of authored runtime into an entirely new npm workspace/package.
- Retirement of `temporal-worker` as a whole.
- Migration of non-authored/domain Temporal workflows into `workflow-worker`.
- Broad redesign of workflow authoring UX.
- Reintroducing the legacy DB runtime as an execution fallback.

## Users and Primary Flows

### Primary users

- Platform engineers responsible for authored workflow runtime correctness
- Operators debugging stalled or failed authored workflow runs
- Developers running EE workflow runtime locally

### Primary flows

#### Flow 1: Manual/API authored run starts
1. A user starts an authored Workflow Runtime V2 run from UI or API.
2. The server launches the Temporal workflow on queue `workflow-runtime-v2`.
3. `workflow-worker` picks up the Temporal task and executes the authored workflow.
4. The run progresses without depending on `temporal-worker`.

#### Flow 2: Event ingress resumes authored waits
1. `workflow-worker` consumes workflow event ingress.
2. It resolves candidate authored Temporal waits/runs.
3. It signals Temporal-backed authored runs.
4. The same `workflow-worker` process family owns both ingress and authored runtime execution, making failures easier to trace.

#### Flow 3: Domain/job workflows continue unchanged
1. Existing non-authored Temporal workflows continue polling on `temporal-worker`.
2. Removing `workflow-runtime-v2` from `temporal-worker` does not affect tenant/domain/job/schedule workflows that are not part of authored Workflow Runtime V2.

## UX / UI Notes

- No workflow authoring UX changes are required.
- Temporal UI should show an active worker for the `workflow-runtime-v2` queue once `workflow-worker` is running.
- Run support/debug flow should become simpler:
  - authored workflow execution problem → inspect `workflow-worker`
  - non-authored/domain Temporal problem → inspect `temporal-worker`
- Existing run/event/projected UI surfaces should continue to behave the same as long as projections remain correct.

## Requirements

### Functional Requirements

#### FR-1: Authored runtime ownership
- `workflow-worker` must poll the Temporal queue used for authored Workflow Runtime V2 execution.
- The authored runtime queue remains `workflow-runtime-v2` unless an explicit rename is separately approved.
- Authored Workflow Runtime V2 Temporal workflows must execute successfully with only `workflow-worker` running, assuming Temporal server is available.

#### FR-2: Temporal worker scope reduction
- `temporal-worker` must stop polling `workflow-runtime-v2`.
- `temporal-worker` must continue polling all approved non-authored/domain queues.
- Removing authored queue ownership from `temporal-worker` must not break unrelated Temporal workflows.

#### FR-3: Single-process workflow-worker ownership
- The same `workflow-worker` process/container must own:
  - workflow event-stream ingress/support paths
  - authored Workflow Runtime V2 Temporal queue polling
- This must not require a second sidecar process inside the `workflow-worker` container.

#### FR-4: Runtime core vs bootstrap split
- `@alga-psa/workflows` must expose a worker-safe authored runtime core surface with no app/bootstrap side effects.
- AI inference service wiring, AI action registration, and similar app/bootstrap concerns must live in a separate bootstrap-oriented surface.
- `workflow-worker` must import only the worker-safe runtime/core surface plus explicit worker-safe registrations it truly needs.

#### FR-5: Worker-safe import graph
- Authored runtime startup paths used by `workflow-worker` must not depend on:
  - unresolved `@shared/*` aliases
  - raw repo-relative imports into unrelated source trees
  - UI-only or app-only modules
- Built artifacts used in worker contexts must be self-contained enough to resolve through stable package exports or explicit local worker-owned files.

#### FR-6: Clear runtime initialization contract
- Runtime initialization required by `workflow-worker` must be explicit and deterministic.
- Worker-safe initialization must register only what authored runtime execution actually needs.
- Server/bootstrap initialization may register additional app-facing behavior, but that must not leak into worker-safe core by accident.

#### FR-7: Compose and environment alignment
- Local Docker/compose wiring must reflect the new ownership model.
- `workflow-worker` must receive the Temporal environment and queue configuration required to poll authored workflow tasks.
- `temporal-worker` configuration must no longer imply ownership of authored workflow runtime.

#### FR-8: Backward-compatible run launch contract
- Existing authored run launch and signal helpers may continue targeting Temporal queue `workflow-runtime-v2`.
- The move in ownership from `temporal-worker` to `workflow-worker` must not require API/UI changes to start or signal authored runs.

#### FR-9: Operability and support clarity
- Logs should make it obvious that `workflow-worker` has started Temporal polling for authored runtime.
- Logs/config should make it obvious that `temporal-worker` is not expected to own `workflow-runtime-v2` anymore.

### Non-functional Requirements

- Prefer explicit boundaries over hidden fallback behavior.
- Fail fast when worker-safe runtime code accidentally depends on bootstrap/app-only layers.
- Keep authored runtime deterministic and replay-safe.
- Minimize the blast radius to non-authored/domain Temporal workflows.
- Preserve local-development practicality; the authored runtime should be testable without package-layout hacks.

## Data / API / Integrations

### Relevant files

- `services/workflow-worker/src/index.ts`
- `services/workflow-worker/Dockerfile`
- `services/workflow-worker/src/v2/WorkflowRuntimeV2EventStreamWorker.ts`
- `ee/temporal-workflows/src/worker.ts`
- `ee/temporal-workflows/src/workflows/workflow-runtime-v2-run-workflow.ts`
- `ee/temporal-workflows/src/activities/workflow-runtime-v2-activities.ts`
- `ee/packages/workflows/src/runtime/index.ts`
- `ee/packages/workflows/package.json`
- `docker-compose.ee.yaml`
- `docker-compose.temporal.ee.yaml`

### Integration notes

- Temporal workflow definitions and activities for authored Workflow Runtime V2 may still physically live under `ee/temporal-workflows` initially, but operational ownership moves to `workflow-worker`.
- If shared code from `ee/temporal-workflows` is reused by `workflow-worker`, the import/build contract must be explicit and worker-safe.
- Build/export fixes should prefer stable package/module boundaries over additional container-only symlink hacks.

## Risks

1. **Partial move leaves both workers polling authored queue**
   - Mitigation: explicit queue ownership changes plus startup tests/log assertions.

2. **Move breaks non-authored Temporal workflows accidentally**
   - Mitigation: keep `temporal-worker` scope narrow and validate non-authored queue config separately.

3. **Runtime split is incomplete and worker-safe boundary still leaks bootstrap concerns**
   - Mitigation: define and test the intended core/bootstrap surfaces explicitly.

4. **Docker/compose changes hide code-level layering issues temporarily**
   - Mitigation: require worker-safe import/build validation outside compose where practical.

5. **Legacy DB polling path becomes confused with authored Temporal polling**
   - Mitigation: keep authored Temporal ownership clearly separated from optional legacy DB polling flags.

## Rollout / Migration Notes

- This is an architecture change, not a local-only workaround.
- Existing authored Workflow Runtime V2 runs continue to use Temporal as execution authority.
- The operational owner of authored queue polling changes from `temporal-worker` to `workflow-worker`.
- Local environment and deployment manifests must be updated consistently so only `workflow-worker` owns authored queue polling.
- No authored-run API contract change is required for callers.

## Open Questions

1. Should authored Temporal workflow definitions/activities remain physically housed under `ee/temporal-workflows` for now, or should a later follow-up relocate them closer to `workflow-worker`?
2. Which exact bootstrap registrations should remain app/server-only versus worker-safe shared registrations?
3. Do we want an explicit startup assertion that fails if both workers are configured to poll `workflow-runtime-v2`?

## Acceptance Criteria / Definition of Done

This plan is done when:

1. Starting an authored Workflow Runtime V2 run results in `workflow-worker` polling and executing queue `workflow-runtime-v2`.
2. `temporal-worker` no longer polls `workflow-runtime-v2` but continues running non-authored/domain Temporal workflows.
3. `workflow-worker` can start authored runtime execution in the same process/container that already handles event-stream ingress.
4. `@alga-psa/workflows` exposes a worker-safe runtime/core surface that does not depend on bootstrap/app-only wiring.
5. Worker startup paths no longer depend on unresolved `@shared/*` aliases or repo-layout-relative source hops.
6. Local EE smoke testing shows Temporal UI reporting active workers for authored queue ownership through `workflow-worker`.
7. Focused tests cover queue ownership, worker startup, authored run execution, and runtime boundary separation.