Commit 2f2bc91
committed
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
0 commit comments