Skip to content

Commit 2f2bc91

Browse files
Freeze v2 control-plane and execution-plane role split contract
Issue #582 opens Phase 4 of the v2 multi-node architecture roadmap, which splits the uniform node model into named roles that can scale and fail independently. Today every node carries API ingress, control plane, matching, history/projection, scheduling, and execution responsibilities; Phase 4 gives each of those a documented authority boundary so later phases can move them out of process without re-litigating what each role is allowed to mutate. This lands the contract doc and a pinning test. docs/architecture/control-plane-split.md: - scopes the contract to role taxonomy, authority boundaries, failure domains, scaling boundaries, supported topologies, migration path, protocol-version coordination, worker-registration authority, and operator-visible role state - freezes six named roles (control plane, execution plane, matching, history/projection, scheduler, API ingress) with explicit authority over the durable mutation surfaces they own - pins the authority-boundary table across workflow_instances, workflow_runs, workflow_tasks, activity executions and attempts, history events, run summaries, workflow_schedules, worker_compatibility_heartbeats, and worker_registrations so cross- role writes are forbidden by contract instead of convention - freezes the three supported deployment topologies (embedded, standalone server, split control/execution) and guarantees the embedded and standalone-server shapes keep working without topology-specific configuration after the split lands - describes the per-role failure modes so operators see how outages propagate, including the degraded-projection and missed-scheduler states that must surface through OperatorMetrics rather than through inferred behaviour - states the protocol-version coordination rule so mixed-version safety across the split is explicit (worker protocol, control-plane protocol, and internal role-to-role bindings each carry their own negotiated version) - leaves scheduler leader election and rollout-safety enforcement to Phase 6 (#584) and replacement of the shared wake backend to Phase 5 (#583) so Phase 4 is not forced to solve both at once tests/Unit/V2/ControlPlaneSplitDocumentationTest.php: - asserts every named heading, term, referenced class, HTTP route, and authority-surface name is present so operator, CLI, Waterline, cloud, and SDK coverage can rely on the contract's vocabulary - pins the embedded and standalone-server support guarantees, the "execution plane is the only role running user code" rule, the control-plane authority rule, the exactly-once history-writer rule, the synchronous-projection guarantee, the reads-allowed/writes-forbidden rule, the protocol-version coordination rule, and the "splitting a role MUST NOT reduce observability" rule - explicitly requires the document to defer Phase 5 (#583) and Phase 6 (#584) so future phases extend the contract instead of silently redefining it Execution-plane routing, claim enforcement, and the dispatched job classes named by Phase 2 (#580) and Phase 3 (#581) are preserved verbatim; this contract adds the role-split language around them rather than changing them. Verified: - bash scripts/check-public-boundary.sh (exit 0) - vendor/bin/phpunit tests/Unit/V2/ControlPlaneSplitDocumentationTest.php (21 tests, 126 assertions, OK) against PHP 8.1 - vendor/bin/ecs check tests/Unit/V2/ControlPlaneSplitDocumentationTest.php (no errors)
1 parent a1b3eac commit 2f2bc91

2 files changed

Lines changed: 1053 additions & 0 deletions

File tree

0 commit comments

Comments
 (0)