deploy: edfd867

Author: github-actions[bot]

2.0/llms-full.txt

@@ -22,6 +22,10 @@ If your task is "run five queued jobs in order and bail on the first failure," L
 
 This guide covers installing the Durable Workflow PHP package for Laravel applications.
 
+If you are deciding between package embedding and the standalone server, start
+with [Deployment Modes](/docs/2.0/polyglot/deployment-modes). This page covers
+the embedded Laravel path.
+
 ## Requirements
 
 - PHP 8.1 or later
@@ -9766,21 +9770,17 @@ Not supported as an automatic operation today:
 Plan the cutover so old embedded runs drain where they started, while new runs
 start on the server.
 
-## Embedded vs Service Mode Contract
+## Deployment Mode Contract
 
-Embedded mode and service mode run the same v2 engine. The difference is where
-the control plane, worker transport, and auth boundary live.
+For the frozen embedded-vs-service comparison, see
+[Deployment Modes](/docs/2.0/polyglot/deployment-modes). This migration guide
+adds three cutover-specific rules on top of that shared contract:
 
-| Surface | Embedded mode | Service mode | What stays the same |
-| --- | --- | --- | --- |
-| Durable workflow model | The Laravel app hosts the package directly and writes durable workflow state from inside the app runtime. | The standalone server hosts the package and writes durable workflow state behind its HTTP control plane. | Workflow ids, run ids, typed history, command outcomes, retries, repair semantics, and history export remain the same v2 contract. |
-| Workflow and activity type keys | PHP code can map aliases to local classes inside the app. | Workers advertise supported type keys over HTTP registration. | Durable public type keys should stay stable and language-neutral in both modes. Do not treat PHP FQCNs as the public contract. |
-| Workflow starts and operator commands | Starts may come from `WorkflowStub`, app code, or embedded control-plane helpers. Signals, queries, updates, cancel, and terminate execute inside the embedded runtime. | Starts and operator commands go through the server API, CLI, or SDKs with explicit auth and protocol headers. | Duplicate-start policy, command ids, run targeting, and control-plane outcomes stay the same. Route follow-up commands to the runtime that accepted the start. |
-| Task delivery | Laravel queue workers claim and execute durable workflow/activity tasks inside the app deployment. | Workers long-poll the server worker protocol and complete tasks over HTTP. | Task leases, heartbeats, compatibility markers, replay, and at-least-once activity execution keep the same semantics. |
-| Visibility and diagnostics | Waterline or app-local tooling reads the embedded app's durable state. | Waterline, CLI, SDKs, and server APIs read the server's durable state. | Search attributes, memos, run detail, queue diagnostics, and history export use the same durable facts within each runtime. |
-| Auth and tenancy boundary | App auth is whatever the Laravel host exposes around its own app endpoints. | Namespace selection plus server auth tokens or signatures are mandatory API boundaries. | Namespace names, task queues, compatibility markers, and payload-codec choices should stay stable across the cutover. |
-| Runtime discovery | The app can resolve local services in-process. | Workers and clients must target an explicit server base URL. | Do not couple the migration to shared `APP_URL`, `APP_KEY`, localhost assumptions, or same-container discovery. Server mode should be configured as an explicit remote control plane. |
-| Migration boundary | Existing embedded runs continue where they started. | New server-managed runs start under the server and stay there. | There is no automatic live migration of in-flight runs between modes. Use export for audit/debugging, not as an import path for live state. |
+- Existing embedded runs keep executing where they started.
+- New server-managed runs use stable type keys, namespace names, task queues,
+  and payload codecs from the first cutover.
+- Signals, queries, updates, cancel, terminate, and archive must keep routing
+  to the runtime that owns the target run.
 
 ## Cutover Invariants
 
@@ -10061,12 +10061,108 @@ HTTP implementations, use [the worker protocol reference](/docs/2.0/polyglot/wor
 - [Python SDK](/docs/2.0/polyglot/python)
 - [Migrating to 2.0](/docs/2.0/migration)
 
+<!-- Source: docs/polyglot/deployment-modes.md -->
+
+# Deployment Modes
+
+Durable Workflow v2 ships one durable engine in two packaging shapes:
+
+- **Embedded mode** inside a Laravel application that installs the
+  `durable-workflow/workflow` package directly.
+- **Service mode** through the standalone
+  [Durable Workflow server](/docs/2.0/polyglot/server).
+
+Use this page when deciding which shape should own a workflow fleet, planning a
+cutover between them, or documenting which parts of the product contract must
+stay identical across both.
+
+## Same Durable Engine, Different Boundary
+
+Embedded mode and service mode keep one v2 kernel. What changes is the hosting,
+auth, and transport boundary around it.
+
+| Surface | Embedded mode | Service mode | Stable in both modes |
+| --- | --- | --- | --- |
+| Durable workflow model | A Laravel app hosts the package directly and writes workflow state inside the app runtime. | The standalone server hosts the same package and writes workflow state behind its HTTP control plane. | Workflow ids, run ids, typed history, command outcomes, retries, repair semantics, and history export remain the same v2 contract. |
+| Control plane | Starts and commands come from app code, `WorkflowStub`, or app-local operator tooling. | Starts and commands go through the server API, CLI, or SDKs with explicit auth and protocol headers. | Duplicate-start policy, run targeting, command ids, and named outcomes stay the same. Route follow-up commands to the runtime that accepted the start. |
+| Worker transport | Laravel queue workers execute workflow and activity tasks inside the app deployment. | Workers register, long-poll, heartbeat, and complete work over the HTTP worker protocol. | Task leases, compatibility markers, replay semantics, and at-least-once activity execution stay the same. |
+| Task dispatch default | Tasks are normally dispatched to the Laravel queue in-process with the application. | The server defaults to `task_dispatch_mode = poll` so external workers discover work over HTTP unless you explicitly override it. | The ready/leased/repair lifecycle and durable task model stay the same. |
+| Workflow and activity type keys | PHP aliases can resolve to local classes inside the app. | Workers advertise supported type keys during registration. | Public type keys should stay stable and language-neutral. Do not make PHP FQCNs the public contract. |
+| Operator surface | Waterline or app-local tooling reads the embedded app's durable state. | The server API, CLI, and SDKs read the server-owned durable state. | Visibility facts such as search attributes, memos, run status, queue diagnostics, and history export are durable facts within the runtime that owns the run. |
+| Auth and tenancy boundary | App auth is whatever the Laravel host exposes around its own routes and sessions. | Namespace selection and server auth tokens or signatures are mandatory API boundaries. | Namespace names, task queues, compatibility markers, and payload-codec choices should stay stable across a cutover. |
+| Runtime discovery | The app can resolve services in-process or through app-local configuration. | Workers and clients must target an explicit remote base URL. | Do not couple either mode to shared `APP_URL`, `APP_KEY`, localhost assumptions, or same-container discovery. |
+| Migration boundary | Existing embedded runs keep executing where they started. | New server-managed runs start on the server and stay there. | There is no automatic live migration of in-flight runs between modes. Export is for audit/debugging, not for importing live state. |
+
+## Choose Embedded Mode When
+
+- Your Laravel application owns workflow authoring, worker execution, and
+  operator access in one deployment.
+- The app's existing queue and auth model is the right boundary for workflow
+  operations.
+- You want the smallest self-contained runtime and do not need a
+  language-neutral worker protocol.
+- Your operators can use Waterline or host-app tooling as the primary workflow
+  surface.
+
+Start with [Installation](/docs/2.0/installation) and the configuration pages
+under [Run And Operate](/docs/2.0/category/run-and-operate).
+
+## Choose Service Mode When
+
+- Multiple applications or teams should share one workflow runtime.
+- Workers, control-plane callers, or operators are not all Laravel/PHP.
+- You need an explicit remote auth and namespace boundary between clients and
+  the workflow engine.
+- You want to scale API ingress, matching/dispatch, and workers independently
+  within the supported
+  [server role topology](/docs/2.0/polyglot/server-role-topology).
+
+Start with [Server](/docs/2.0/polyglot/server),
+[Self-Hosting Deployments](/docs/2.0/deployment), and the
+[Server API Reference](/docs/2.0/polyglot/server-api-reference).
+
+## Migration Tooling Between Modes
+
+The supported path from embedded mode to service mode is staged adoption, not a
+live handoff of in-flight state:
+
+- Use [Embedded to Server Migration](/docs/2.0/polyglot/embedded-to-server) for
+  the step-by-step cutover.
+- Use `GET /api/cluster/info` to confirm the target server build, topology, and
+  capability contract before switching traffic.
+- Use `POST /api/worker/register` plus the worker protocol to prove external
+  workers can serve the stable workflow and activity type keys you chose.
+- Use [CLI and Python Parity](/docs/2.0/polyglot/cli-python-parity) when
+  replacing app-local control-plane calls with server-backed automation.
+- Use Waterline or server-side history export for audit/debugging evidence; do
+  not treat export bundles as an import path for live server-managed runs.
+
+Three migration rules are non-negotiable:
+
+1. Existing runs stay on the runtime where they started.
+2. New server-managed runs use stable type keys, namespace names, task queues,
+   and payload codecs from the first cutover.
+3. Signals, queries, updates, cancel, terminate, and archive must go to the
+   runtime that owns the target run.
+
+## Related References
+
+- [Installation](/docs/2.0/installation)
+- [Server](/docs/2.0/polyglot/server)
+- [Embedded to Server Migration](/docs/2.0/polyglot/embedded-to-server)
+- [Server Role Topology](/docs/2.0/polyglot/server-role-topology)
+- [Server Config Reference](/docs/2.0/polyglot/server-config-reference)
+
 <!-- Source: docs/polyglot/server.md -->
 
 # Server
 
 The Durable Workflow server is a standalone, language-neutral workflow orchestration service. It exposes the same durable execution engine as the PHP package over HTTP, letting you write workflows in Python, PHP, or any language that speaks HTTP.
 
+If you are deciding between the standalone server and package embedding, start
+with [Deployment Modes](/docs/2.0/polyglot/deployment-modes). This page covers
+the service-mode distribution.
+
 Use the standalone server when you need:
 - **Polyglot workflows** — Python workers executing PHP-authored workflows, or vice versa
 - **Microservice orchestration** — orchestrate services written in different languages
@@ -10076,9 +10172,10 @@ Use the standalone server when you need:
 If you already run v2 embedded in a Laravel app, use the
 [embedded-to-server migration guide](/docs/2.0/polyglot/embedded-to-server) to
 prepare type keys, deploy the server beside embedded execution, connect workers,
-and route only new workflow starts to the server. That guide also freezes the
-embedded-vs-service mode contract so the cutover keeps ids, command outcomes,
-task semantics, and runtime ownership rules explicit.
+and route only new workflow starts to the server. Keep
+[Deployment Modes](/docs/2.0/polyglot/deployment-modes) nearby during that
+cutover so ids, command outcomes, task semantics, and runtime ownership rules
+stay explicit.
 
 Use [Worker Compatibility and Routing](/docs/2.0/polyglot/worker-compatibility-routing)
 when you roll mixed-version worker fleets, drain old cohorts, or need to keep