PHP schedule starter does not forward execution and run timeouts to StartOptions

[chrom]

Owning public component

Workflow engine

Exact version or source identity

2.4.0

Minimal reproduction and evidence

Version:

• durable-workflow/workflow: 2.4.2
• Source commit: 4fcb236
• PHP 8.4, Laravel, PostgreSQL
• Embedded Laravel backend using PHP-class workflows

Reproduction:

1. Use the package's default PhpClassScheduleStarter without an application-specific replacement.

2. Register a schedule for a simple PHP workflow.

3. Include the following timeout values in the persisted schedule action, alongside workflow_class and input:

   "execution_timeout_seconds": 120,
   "run_timeout_seconds": 60

4. Trigger the schedule.

5. Inspect the resulting workflow_runs record:

   • run_timeout_seconds
   • execution_deadline_at
   • run_deadline_at

These action field names describe the contract our application needs; we have not established that they are currently documented as supported PHP schedule fields.

Source evidence:

src/V2/Support/PhpClassScheduleStarter.php constructs StartOptions with only:

new StartOptions(
    labels: ...,
    memo: ...,
    searchAttributes: ...,
);

It does not read timeout settings from the schedule action or pass executionTimeoutSeconds / runTimeoutSeconds.

StartOptions already supports both parameters, defaulting to null. WorkflowStub uses these options to calculate and persist execution and run deadlines.

This establishes the missing forwarding path by source inspection. The reproduction above isolates that path; it does not require waiting for a workflow to time out.

Source:
https://github.com/durable-workflow/workflow/blob/4fcb23622147dd2c1f92e461e927577092120bb8/src/V2/Support/PhpClassScheduleStarter.php

Observed behavior

The default PHP schedule starter does not propagate the requested timeout values into StartOptions. Consequently, placing these values in the schedule action does not establish the corresponding deadlines on the new run.

Direct starts can supply executionTimeoutSeconds and runTimeoutSeconds through StartOptions, but the default scheduled PHP start does not expose the equivalent forwarding path.

Our application currently compensates with a custom ScheduleWorkflowStarter implementation. However, that interface is marked @internal, so enforcing these limits requires depending on an internal extension point.

This report concerns configuring deadlines at scheduled start, not a demonstrated failure of timeout enforcement after a deadline has been correctly configured.

Expected behavior and acceptance criteria

Provide a documented, supported way to configure execution and run timeouts for PHP workflows started by a schedule.

The exact field names and representation should follow the package's public contract; the suggested snake_case action fields are not a requirement.

Acceptance criteria:

1. A schedule can declare an execution timeout and a run timeout through a supported API.
2. PhpClassScheduleStarter forwards those values to StartOptions.
3. A run started with execution timeout 120 seconds and run timeout 60 seconds receives the corresponding persisted deadlines and run timeout value.
4. Manual schedule triggers and automatic scheduled occurrences apply the same configured limits.
5. Missing timeout settings preserve the existing behavior.
6. Invalid timeout values are rejected consistently with StartOptions validation.
7. Updating a schedule affects subsequent starts without rewriting deadlines of already-started runs.
8. Regression tests cover forwarding, omitted values, invalid values, and both trigger paths.
9. Documentation explains the difference between the two timeouts and how to configure them without implementing an internal starter.

If timeout fields in schedule actions are intentionally unsupported today, please treat this as a public-contract enhancement request rather than a regression report.

Dependencies and related public issues

Affected repository:

• durable-workflow/workflow

Relevant components:

• src/V2/Support/PhpClassScheduleStarter.php
• src/V2/Contracts/ScheduleWorkflowStarter.php
• src/V2/StartOptions.php
• src/V2/WorkflowStub.php
• Schedule action validation and documentation

The timeout options and deadline persistence already exist. The missing integration is between the schedule definition and the default PHP workflow starter.

Waterline is not required to reproduce this behavior. No standalone Server defect is asserted by this report.

Related public issues:

• No specific related issue has been verified for this report.
• Duplicate status has not been established.

Existing application workaround:

• Replace or decorate ScheduleWorkflowStarter to forward the timeout options.
• This depends on an @internal contract and should become unnecessary once the supported schedule API provides equivalent behavior.

Public intake checks

• I searched open and closed GitHub issues for an existing report.
• This report contains only public product context and redacted evidence.

[rmcdaniel]

Accepted as a public API enhancement, P2 / ready. No duplicate was found.

The published 2.4.2 starter at 4fcb23622147dd2c1f92e461e927577092120bb8
passes labels, memo and search attributes to StartOptions, but does not forward
execution or run timeouts. The timeout options already exist for direct starts.
The report identifies a missing supported schedule configuration path rather
than a demonstrated timeout-enforcement regression.

The implementation will define supported schedule timeout fields, validate them
with the same rules as StartOptions, and forward them through the default PHP
starter. Both manual triggers and automatic occurrences must persist the 120s
execution / 60s run limits. Omitted settings retain current behavior. Schedule
updates apply to future starts and preserve existing run deadlines.

Next action: implement this contract with regression coverage for both trigger
paths, invalid and omitted values, and schedule updates. Document the execution
timeout across retries/continuations and the timeout for an individual run.
Qualify a fresh published PHP consumer and complete affected downstream delivery
before closing this issue. Application-specific internal starter replacements
should no longer be needed to configure these limits.

[rmcdaniel]

Delivered in Workflow 2.5.0 through #639.

ScheduleManager::create() now accepts executionTimeoutSeconds and runTimeoutSeconds. Rich specs and action updates support the corresponding stored fields. Manual and automatic starts apply the same budgets, and existing runs keep their original deadlines. The schedule guide includes supported examples without a custom starter.

Verification is complete: the full source build, including coverage, and all 16 published Laravel/PHP upgrade cells pass. A fresh Packagist consumer passes 18 schedule cases with 86 assertions.

Downstream updates are merged in durable-workflow/waterline#145, durable-workflow/sample-app#146 and durable-workflow/durable-workflow.github.io#166. Both published development-image architectures pass startup qualification, and the live guide and stable manifest are verified. Server already forwards these timeouts through its remote starter, so Server and SDK versions are unchanged.