Replace PHP Server with a compatible Rust runtime and safe in-place upgrade #325

Current delivery — November 9, 2026

Native 3.3.2 is released and Latest. Final cross-repository delivery receipt.

• Release source/tag: 660217dd1ac62701eb1fc26b08fbbaf825e777d1. Published index: sha256:4aeceb423ee4c8931f00ec2936149ac6b2a75479243b3930f9c6336ccdebf912 in both registries. Exact3.3.2 and rolling3.3/3/latest resolve to that index; exact3.3.0/3.3.1 remain intact.
• Native: write a run of local activity records with one statement per table #1068 and Native: read workflow descriptions from one bounded coherent snapshot #1075 are completed: bounded ordered local-record batching and one-connection coherent workflow descriptions, including MySQL/MariaDB READ COMMITTED controls. Source/backend/main checks and all CodeQL languages passed. Earlier source/download NONPASSs remain attributed; original WIP refs are preserved.
• Publication42591612884/a1, both architectures'3backend smokes/provenance, protected corpus42602023810 and four-cell Compose42602031026, default-resolution42600498794 and published PHP42600504863 are accepted. No build, qualifier, cancel or report duty remains live.
• Subject-only runner#1114 is retained at b7337c1f91c3bc2eea0baaa9d41930220051386f, contained in current signed main 5bde7ed3. The fixed runner branch must remain; it is exactly one subject-only commit ahead of the release source.
• Sample App#334 has signed main 98e8b49d,36source/30main successful checks, all9published runtime surfaces and all9language combinations. Developer image42610919065 passed7/7; both public registries serve sha256:c6eceb459ad78391ce9b82a45daa62ed665f0ae6ca19f0255802a79a7308acfc, and both embedded tuples match Git. Its completed source topic is absent; local/WIP refs remain.
• Alias42612524622/a1 and GitHub Release42613125047/a1 are accepted. Release439079426 has the reviewed full notes and correct Latest designation. Native GitHub Releases should include tagged notes and recognize the complete body #1111 remains the source fix for full-note generation/idempotence; this delivery used one guarded body-only note augmentation and did not rerun the old writer.
• SDK3.11.0 is already published with Prepare Server 2.4.26 and Helm chart 0.1.122 #269 installed acceptance. These internal Server changes need no unchanged SDK release. Schema/protocol1.20/capabilities and documented rollback constraints remain unchanged. No benchmark speedup or Cloud adoption is claimed.

Six Native P0s remain open: #1063(partial), #1074 and #1076(isolated measurement reconciliation of code already present since3.2.0), #1077, #1078 and #1079. sdk-php#341 depends on the accepted #1078 producer contract and a later SDK release. No supported date covers that whole remaining backlog. General owns the next source/measurement slices; Cloud runtime/security work and #1111 retain their separate owning records.

Objective

Replace the PHP/Apache Durable Workflow Server with a faster Rust successor in
this repository. Existing published SDKs, CLI, Waterline and sample applications
must work unchanged. Operators experience a major version upgrade of the same
product, with the same API, behavior, data and operational surfaces.

The PHP Server remains working as a reference throughout development. The
embedded Laravel Workflow package remains a first-class product. This is accepted
implementation work assigned to a dedicated maintainer, not a new architecture
comparison or a claim that Rust is already faster.

Constraints

Repository and delivery

• No new repositories. Rust lives in durable-workflow/server.
• Land small, coherent PRs on main frequently. Do not accumulate the rewrite
  on a long-lived branch or break the PHP Server while landing foundations.
• Keep a running, contributor-readable log in this repository with the current
  plan, significant design decisions, verified outcomes, filed issues, the
  fixture cases they block and the next concrete action.
• Choose the architecture and established Rust libraries with engineering
  judgment. Explain significant choices briefly and link the proving fixtures.
• Follow ordinary review, CI, release and branch-cleanup rules.

Contract, parity and embedded mode

• Published specifications and shared fixtures define observable behavior.
  Neither implementation wins by default. When they disagree, settle the
  contract first, then correct whichever implementation is wrong.
• Establish a shared fixture corpus, recorder and differential runner that can
  target a server URL. Reuse existing protocol specifications, conformance
  scenarios and benchmark tooling rather than creating a second software factory.
• Run the shared fixtures against embedded Laravel, PHP Server and Rust Server.
  Workflow package changes also remain tested against a real HTTP Server.
• Default to parity for existing and new observable capabilities. Define the
  contract and fixtures first, implement a feature in both servers (including
  necessary Workflow package changes), and pass the same fixtures on both.
  A simple, slower PHP implementation is acceptable.
• Internal scheduling, sharding and pooling mechanics without an observable
  contract need no PHP counterpart.
• If an observable capability cannot reasonably exist in PHP, advertise an
  explicit capability flag, mark its fixtures Rust-only and record why.
  Do not disguise incomplete parity as an internal optimization.
• Preserve the existing Avro payload protocol, errors, authentication and
  authorization, namespaces, durable identities and history, worker leases and
  fencing, retries, cancellation, timers, schedules, visibility and recovery.
  Execute the required PHP/Python/Rust worker directions, rather than assuming
  an HTTP schema comparison proves them.

Database isolation and one-way upgrade

• Support SQLite, MariaDB/MySQL and PostgreSQL using the current database tables
  and stored data. Rust owns its versioned forward migrations.
• Ordinary development and differential runs use separate isolated databases
  for PHP, Rust and embedded targets. Never run different implementations
  concurrently against one database.
• The only cross-implementation shared-database exception is the dedicated
  sequential upgrade test: PHP writes and stops, then Rust takes over that
  same database. Multi-node replicas are tested within their own isolated
  deployment, not against another implementation's state.
• Upgrade existing deployments in place. HTTP export/import remains a way to
  move data between deployments, not the upgrade route.
• Require a backup before mutation and stop the PHP fleet before takeover.
  Make interruption resume safely or fail without corrupting state.
• Record a schema marker. All affected PHP startup/worker/bootstrap paths must
  refuse an upgraded database before migration or durable writes can occur.
• There is no PHP rollback after upgrade and no mixed PHP/Rust fleet.
  Rust migrations need not preserve post-upgrade PHP schema compatibility.
  The PHP reference continues to work against its own non-upgraded database.
• Inventory stored PHP-serialized values, class names and framework conventions.
  Handle each with a read-compatibility path or documented one-time conversion.
  Do not silently discard data that Rust cannot interpret.
• Preserve acknowledged work, durable history, pending workflows, timers,
  leases, credentials and external payload references/bytes across takeover.

Operations and performance

• Preserve existing image names, supported image architectures, DW_*
  configuration, health/readiness, bootstrap, Compose and Helm layouts, metrics,
  diagnostics, graceful shutdown and recovery.
• Document a migration path for anything that cannot carry over directly,
  such as a PHP authentication-provider class.
• Record a reproducible PHP baseline before judging Rust. Use exact published
  artifacts, workloads, hardware, resource limits, commands and raw results.
• Rust must meet or beat PHP throughput, memory and idle long-poll cost.
  Verify timers and lease renewals remain healthy during CPU-heavy load.
  Do not accept apparent gains from lost work, backlog, swapping or an
  unmeasured drain. Repeat promising measurements and recheck baseline drift.
• Do not change customer pricing, Cloud production or managed rollout as part
  of the Server rewrite. Exact Rust artifacts need their own Cloud qualification.

Work order

1. Establish the safety net: current contract inventory, shared fixtures,
   recorder, URL-targeted runner, meaningful embedded/HTTP coverage and
   reproducible PHP baseline.
2. Land the Rust foundations and vertical slices in small reviewed merges,
   keeping PHP operational.
3. Run the differential suite after every change. Record intentional contract
   decisions and convert every defect into a focused shared regression.
4. Complete all capabilities and actual SDK/worker directions, database and
   multi-node qualification, performance proof and operational compatibility.
5. Finish migration tooling, backup-first upgrade tests, operator documentation
   and major-version cutover preparation. Release through the repository's
   existing decision and publication process, then verify published artifacts.

Acceptance

• Shared fixtures, recorder and URL-targeted differential runner are usable
  by a contributor from the public repositories.
• PHP Server stays operational and embedded Laravel remains first class.
  Shared contracts pass on embedded, PHP Server and Rust Server.
• Every required fixture passes with actual published PHP/Python/Rust SDKs
  and every meaningful supported workflow/activity/child direction executed.
  Existing CLI, Waterline and sample apps work unchanged.
• Multi-node kill/restart tests prove no lost durable work, no duplicate
  committed outcomes and no acceptance of stale worker attempts. External
  effects retain their explicit application-idempotency contract.
• Conformance and multi-node suites pass on SQLite, MariaDB/MySQL and
  PostgreSQL. Database topology and limits are explicit.
• Rust meets or beats the recorded PHP baseline for throughput, memory and
  idle long polls. Timers and lease renewals remain healthy under CPU-heavy load.
• Existing images/configuration/bootstrap/Compose/Helm/health/readiness/
  shutdown/diagnostics remain usable, with documented migrations for exceptions.
• A backup-first in-place upgrade starts from data written by the last PHP
  release, with pending workflows, timers and leases, and continues under Rust
  on each supported database.
• Interrupted upgrade resumes or fails safely. PHP reliably refuses the
  upgraded schema. No concurrent mixed fleet or post-upgrade PHP rollback.
• Stored PHP-specific values and external payloads have tested compatible
  reads or explicit one-time conversions.
• Operator upgrade/cutover documentation, major-release readiness,
  exact publication identities and downstream verification are complete.
• The running repository log lets a maintainer see decisions, blockers,
  blocked fixture cases and the next action without private workspace context.

Ownership

A dedicated Rust Server maintainer owns this issue and its scoped implementation,
tests and cutover preparation. Coordinate necessary cross-repository contract
and Workflow changes through linked owning records. Other maintainers should
avoid competing implementation of this rewrite while that assignment is active.