[cross-repo from workflow#135] GitHub #582: server + workflow: v2 architecture Phase 4: control-plane and execution-plane role split (#127)

Author: durable-workflow-ops

app/Support/ServerTopology.php

@@ -59,6 +59,7 @@ public static function info(): array
             'scaling_boundaries' => self::scalingBoundaries(),
             'supported_topologies' => self::supportedTopologies(),
             'migration_path' => self::migrationPath(),
+            'kernel_invariants' => self::kernelInvariants(),
         ];
     }
 
@@ -611,7 +612,8 @@ private static function supportedTopologies(): array
     /**
      * @return list<array{
      *     step: string,
-     *     result: string
+     *     result: string,
+     *     reversible: bool
      * }>
      */
     private static function migrationPath(): array
@@ -620,26 +622,75 @@ private static function migrationPath(): array
             [
                 'step' => 'audit_role_boundaries',
                 'result' => 'tooling flags cross-role writes before runtime shape changes',
+                'reversible' => true,
             ],
             [
                 'step' => 'expose_role_bindings',
                 'result' => 'container seams allow out-of-process adapters without patching the package',
+                'reversible' => true,
             ],
             [
                 'step' => 'introduce_dedicated_matching_shape',
                 'result' => 'matching can run as its own process class without changing the claim contract',
+                'reversible' => true,
             ],
             [
                 'step' => 'split_history_projection',
                 'result' => 'history and projections can move out of process without introducing a second writer',
+                'reversible' => true,
             ],
             [
                 'step' => 'split_scheduler',
                 'result' => 'schedule firing can move behind leader election while single-replica deployments stay legal',
+                'reversible' => true,
             ],
             [
                 'step' => 'optional_execution_partitioning',
                 'result' => 'workers can partition by namespace, connection, queue, and compatibility',
+                'reversible' => true,
+            ],
+        ];
+    }
+
+    /**
+     * @return list<array{
+     *     id: string,
+     *     summary: string,
+     *     applies_to: list<string>
+     * }>
+     */
+    private static function kernelInvariants(): array
+    {
+        return [
+            [
+                'id' => 'single_persistence_engine',
+                'summary' => 'one workflow database backs every topology shape; role split does not introduce a second persistence engine',
+                'applies_to' => ['embedded', 'standalone_server', 'split_control_execution'],
+            ],
+            [
+                'id' => 'single_worker_protocol',
+                'summary' => 'one HTTP worker protocol carries claim, complete, fail, and heartbeat traffic across every topology; role split does not fork the worker contract',
+                'applies_to' => ['embedded', 'standalone_server', 'split_control_execution'],
+            ],
+            [
+                'id' => 'single_history_writer',
+                'summary' => 'history_events has exactly one durable writer per logical event regardless of where the history/projection role runs',
+                'applies_to' => ['embedded', 'standalone_server', 'split_control_execution'],
+            ],
+            [
+                'id' => 'single_control_authority_per_run',
+                'summary' => 'every mutation of a given workflow run routes through one control-plane authority; per-run row locks serialise transitions across replicas',
+                'applies_to' => ['embedded', 'standalone_server', 'split_control_execution'],
+            ],
+            [
+                'id' => 'embedded_topology_remains_supported',
+                'summary' => 'the embedded shape where one process fills every role MUST stay legal; existing embedded hosts are never forced to migrate',
+                'applies_to' => ['embedded', 'standalone_server', 'split_control_execution'],
+            ],
+            [
+                'id' => 'role_split_is_topology_only',
+                'summary' => 'splitting roles is a topology change, not a product fork; collapsing the roles back onto a single process is always a legal topology',
+                'applies_to' => ['embedded', 'standalone_server', 'split_control_execution'],
             ],
         ];
     }

tests/Feature/ClusterInfoCompatibilityTest.php

@@ -101,6 +101,7 @@ public function test_cluster_info_is_a_versionless_protocol_discovery_contract()
                     'scaling_boundaries',
                     'supported_topologies',
                     'migration_path',
+                    'kernel_invariants',
                 ],
                 'coordination_health' => [
                     'schema',

tests/Feature/ClusterInfoTest.php

@@ -256,6 +256,44 @@ public function test_it_publishes_role_topology_for_the_current_server_node(): v
             ->assertJsonPath(
                 'topology.migration_path.5.step',
                 'optional_execution_partitioning',
+            )
+            ->assertJsonPath('topology.migration_path.0.reversible', true)
+            ->assertJsonPath('topology.migration_path.5.reversible', true)
+            ->assertJsonPath(
+                'topology.kernel_invariants.0.id',
+                'single_persistence_engine',
+            )
+            ->assertJsonPath(
+                'topology.kernel_invariants.1.id',
+                'single_worker_protocol',
+            )
+            ->assertJsonPath(
+                'topology.kernel_invariants.2.id',
+                'single_history_writer',
+            )
+            ->assertJsonPath(
+                'topology.kernel_invariants.3.id',
+                'single_control_authority_per_run',
+            )
+            ->assertJsonPath(
+                'topology.kernel_invariants.4.id',
+                'embedded_topology_remains_supported',
+            )
+            ->assertJsonPath(
+                'topology.kernel_invariants.5.id',
+                'role_split_is_topology_only',
+            )
+            ->assertJsonPath(
+                'topology.kernel_invariants.0.applies_to.0',
+                'embedded',
+            )
+            ->assertJsonPath(
+                'topology.kernel_invariants.0.applies_to.1',
+                'standalone_server',
+            )
+            ->assertJsonPath(
+                'topology.kernel_invariants.0.applies_to.2',
+                'split_control_execution',
             );
     }