Bind schedule ticks through a scheduler role seam

Author: durable-workflow-ops

docs/architecture/control-plane-split.md

@@ -242,6 +242,15 @@ Authority:
   `Workflow\V2\Support\ScheduleManager` when invoked by an
   authenticated operator.
 
+Canonical implementation surface:
+
+- `Workflow\V2\Contracts\SchedulerRole` and
+  `Workflow\V2\Support\DefaultSchedulerRole` own the scheduler-role
+  tick entrypoint exposed by `workflow:v2:schedule-tick`.
+- `Workflow\V2\Support\ScheduleManager` and
+  `Workflow\V2\Contracts\ScheduleWorkflowStarter` remain the
+  schedule-lifecycle and scheduled-start boundary inside that role.
+
 Guarantees:
 
 - The scheduler is the **only** role authorised to fire scheduled
@@ -467,16 +476,20 @@ each step independently.
    an out-of-process adapter can replace the binding without
    patching the package. Today's bindings are
    `WorkflowControlPlane`, `OperatorObservabilityRepository`,
-   `MatchingRole`, `HistoryProjectionRole`, `WorkflowTaskBridge`,
-   `ActivityTaskBridge`, `LongPollWakeStore`, and the scheduler's
+   `MatchingRole`, `HistoryProjectionRole`, `SchedulerRole`,
+   `WorkflowTaskBridge`, `ActivityTaskBridge`,
+   `LongPollWakeStore`, and the scheduler's
    `ScheduleWorkflowStarter`. The matching role now crosses the
    queue-loop wake and dedicated daemon entrypoints through
    `DefaultMatchingRole`, so a future out-of-process adapter can
    replace that binding without patching `Looping` listeners or
    `workflow:v2:repair-pass`. The history/projection role now
    crosses the matching seam through `DefaultHistoryProjectionRole`,
    so a future out-of-process adapter can replace that binding
-   without patching the claim paths.
+   without patching the claim paths. The scheduler role now crosses
+   `workflow:v2:schedule-tick` through `DefaultSchedulerRole`, so a
+   future out-of-process adapter can replace that binding without
+   patching the command entrypoint.
 3. **Introduce the dedicated matching shape.** The Phase 3
    contract already allows a dedicated matching role; Phase 4
    provides the deployment guidance for running it as a separate

src/Commands/V2ScheduleTickCommand.php

@@ -7,7 +7,7 @@
 use Illuminate\Console\Command;
 use JsonException;
 use Symfony\Component\Console\Attribute\AsCommand;
-use Workflow\V2\Support\ScheduleManager;
+use Workflow\V2\Contracts\SchedulerRole;
 
 #[AsCommand(name: 'workflow:v2:schedule-tick')]
 class V2ScheduleTickCommand extends Command
@@ -17,9 +17,15 @@ class V2ScheduleTickCommand extends Command
 
     protected $description = 'Evaluate all due workflow v2 schedules and trigger matching workflows';
 
+    public function __construct(
+        private readonly SchedulerRole $schedulerRole,
+    ) {
+        parent::__construct();
+    }
+
     public function handle(): int
     {
-        $results = ScheduleManager::tick();
+        $results = $this->schedulerRole->tick();
 
         if ((bool) $this->option('json')) {
             try {

src/Providers/WorkflowServiceProvider.php

@@ -24,6 +24,7 @@
 use Workflow\V2\Contracts\LongPollWakeStore;
 use Workflow\V2\Contracts\MatchingRole;
 use Workflow\V2\Contracts\OperatorObservabilityRepository;
+use Workflow\V2\Contracts\SchedulerRole;
 use Workflow\V2\Contracts\ScheduleWorkflowStarter;
 use Workflow\V2\Contracts\WorkflowControlPlane;
 use Workflow\V2\Contracts\WorkflowTaskBridge;
@@ -41,6 +42,7 @@
 use Workflow\V2\Support\DefaultHistoryProjectionRole;
 use Workflow\V2\Support\DefaultMatchingRole;
 use Workflow\V2\Support\DefaultOperatorObservabilityRepository;
+use Workflow\V2\Support\DefaultSchedulerRole;
 use Workflow\V2\Support\DefaultWorkflowControlPlane;
 use Workflow\V2\Support\DefaultWorkflowTaskBridge;
 use Workflow\V2\Support\LongPollCacheValidator;
@@ -70,6 +72,8 @@ public function register(): void
 
         $this->app->singleton(WorkflowControlPlane::class, DefaultWorkflowControlPlane::class);
 
+        $this->app->singletonIf(SchedulerRole::class, DefaultSchedulerRole::class);
+
         $this->app->singleton(ScheduleWorkflowStarter::class, PhpClassScheduleStarter::class);
 
         // Register default LongPollWakeStore implementation if not already bound

src/V2/Contracts/SchedulerRole.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Workflow\V2\Contracts;
+
+/**
+ * Binding seam for the scheduler role's due-schedule tick.
+ *
+ * Hosts that want to move schedule evaluation out of process can bind a
+ * replacement implementation without patching the package command entrypoint.
+ */
+interface SchedulerRole
+{
+    /**
+     * @return list<array{
+     *     schedule_id: string,
+     *     instance_id: string|null,
+     *     outcome?: string,
+     *     error?: string
+     * }>
+     */
+    public function tick(int $limit = 100): array;
+}

src/V2/Support/DefaultSchedulerRole.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Workflow\V2\Support;
+
+use Workflow\V2\Contracts\SchedulerRole;
+
+final class DefaultSchedulerRole implements SchedulerRole
+{
+    public function tick(int $limit = 100): array
+    {
+        return ScheduleManager::tick($limit);
+    }
+}

tests/Unit/Commands/V2ScheduleTickCommandTest.php

@@ -0,0 +1,82 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Commands;
+
+use Tests\TestCase;
+use Workflow\V2\Contracts\SchedulerRole;
+
+final class V2ScheduleTickCommandTest extends TestCase
+{
+    public function testItUsesTheSchedulerRoleBindingForScheduleTicks(): void
+    {
+        $fake = new class() implements SchedulerRole {
+            public ?int $lastTickLimit = null;
+
+            public function tick(int $limit = 100): array
+            {
+                $this->lastTickLimit = $limit;
+
+                return [[
+                    'schedule_id' => 'billing-report',
+                    'instance_id' => 'wf-billing-report',
+                    'outcome' => 'scheduled',
+                ]];
+            }
+        };
+
+        $this->app->instance(SchedulerRole::class, $fake);
+
+        $expected = [[
+            'schedule_id' => 'billing-report',
+            'instance_id' => 'wf-billing-report',
+            'outcome' => 'scheduled',
+        ]];
+
+        $this->artisan('workflow:v2:schedule-tick', [
+            '--json' => true,
+        ])
+            ->expectsOutput(json_encode($expected, JSON_UNESCAPED_SLASHES))
+            ->assertSuccessful();
+
+        $this->assertSame(100, $fake->lastTickLimit);
+    }
+
+    public function testItReportsHumanScheduleTickOutputFromTheBoundRole(): void
+    {
+        $fake = new class() implements SchedulerRole {
+            public function tick(int $limit = 100): array
+            {
+                return [[
+                    'schedule_id' => 'nightly-rebuild',
+                    'instance_id' => 'wf-nightly-rebuild',
+                    'outcome' => 'scheduled',
+                ]];
+            }
+        };
+
+        $this->app->instance(SchedulerRole::class, $fake);
+
+        $this->artisan('workflow:v2:schedule-tick')
+            ->expectsOutput('[nightly-rebuild] → wf-nightly-rebuild')
+            ->expectsOutput('Processed 1 schedule(s).')
+            ->assertSuccessful();
+    }
+
+    public function testItReportsWhenNoSchedulesAreDue(): void
+    {
+        $fake = new class() implements SchedulerRole {
+            public function tick(int $limit = 100): array
+            {
+                return [];
+            }
+        };
+
+        $this->app->instance(SchedulerRole::class, $fake);
+
+        $this->artisan('workflow:v2:schedule-tick')
+            ->expectsOutput('No schedules due.')
+            ->assertSuccessful();
+    }
+}

tests/Unit/Providers/WorkflowServiceProviderTest.php

@@ -20,6 +20,7 @@
 use Workflow\V2\Contracts\HistoryProjectionRole;
 use Workflow\V2\Contracts\MatchingRole;
 use Workflow\V2\Contracts\OperatorObservabilityRepository;
+use Workflow\V2\Contracts\SchedulerRole;
 use Workflow\V2\Enums\RunStatus;
 use Workflow\V2\Enums\TaskStatus;
 use Workflow\V2\Enums\TaskType;
@@ -123,6 +124,18 @@ public function testMatchingRoleBindingDefersToAppBinding(): void
         $this->assertSame($custom, $this->app->make(MatchingRole::class));
     }
 
+    public function testSchedulerRoleBindingDefersToAppBinding(): void
+    {
+        $custom = $this->createMock(SchedulerRole::class);
+
+        $this->app->offsetUnset(SchedulerRole::class);
+        $this->app->singleton(SchedulerRole::class, static fn () => $custom);
+
+        (new WorkflowServiceProvider($this->app))->register();
+
+        $this->assertSame($custom, $this->app->make(SchedulerRole::class));
+    }
+
     public function testProviderMergesV2DefaultsIntoLegacyPublishedConfig(): void
     {
         config()->set('workflows', [
@@ -226,6 +239,7 @@ public function testCommandsAreRegistered(): void
             'workflow:v2:history-export',
             'workflow:v2:repair-pass',
             'workflow:v2:rebuild-projections',
+            'workflow:v2:schedule-tick',
         ];
 
         foreach ($expectedCommands as $command) {

tests/Unit/V2/ControlPlaneSplitDocumentationTest.php

@@ -72,6 +72,8 @@ final class ControlPlaneSplitDocumentationTest extends TestCase
         'OperatorObservabilityRepository',
         'OperatorMetrics',
         'OperatorQueueVisibility',
+        'SchedulerRole',
+        'DefaultSchedulerRole',
         'ScheduleManager',
         'ScheduleTriggerResult',
         'ScheduleStartResult',