rmcdaniel · Oct 23, 2026 · Oct 23, 2026
diff --git a/docs/deployment.md b/docs/deployment.md
@@ -6,6 +6,8 @@ description: Choose a supported Durable Workflow v2 self-hosting path and the ar
 
 # Self-Hosting Deployments
 
+For self-hosted or Cloud runtime changes, follow [moving between runtimes](/docs/polyglot/runtime-migration/). Keep existing runs at their source while new starts move.
+
 Durable Workflow v2 supports several self-hosted shapes. Pick the smallest path
 that matches the environment you operate, then keep the image, database, cache,
 auth, readiness, and upgrade contract explicit.

diff --git a/docs/laravel-adoption.md b/docs/laravel-adoption.md
@@ -563,6 +563,8 @@ that explicit validated import operation creates Server-owned state.
 Retiring an old package, queue, table, secret, or Waterline deployment is the
 last step, never the cutover mechanism.
 
+For moves between service-mode runtimes, use [moving between runtimes](/docs/polyglot/runtime-migration/). Server-sourced history export is not live-state import.
+
 ## Continue with the chosen path
 
 - [Stable v1 installation](/docs/1.x/installation/)

diff --git a/docs/polyglot/cloud-control-plane.md b/docs/polyglot/cloud-control-plane.md
@@ -548,6 +548,8 @@ pause/resume operation. Planned SLA terms use the same provisioned-time model at
 own rates, minimums and caps. Use the plan's returned `billing_terms` when
 interpreting usage; historical invoices keep their accepted terms.
 
+Before deprovisioning, follow [moving between runtimes](/docs/polyglot/runtime-migration/#preserve-evidence): retain verified history and payload evidence, and confirm that all source-owned runs are terminal. Capacity billing continues while the source remains provisioned.
+
 Export the same evidence as CSV or a JSON report when a downstream finance
 system needs a file handoff:
 

diff --git a/docs/polyglot/deployment-modes.md b/docs/polyglot/deployment-modes.md
@@ -150,6 +150,8 @@ Three migration rules are non-negotiable:
 
 ## Related References
 
+[Moving between runtimes](/docs/polyglot/runtime-migration/) covers self-hosted-to-self-hosted, self-hosted-to-Cloud and Cloud-to-self-hosted drain and cutover.
+
 - [Installation](/docs/installation)
 - [Server](/docs/polyglot/server)
 - [PHP SDK](/docs/polyglot/php)

diff --git a/docs/polyglot/runtime-migration.md b/docs/polyglot/runtime-migration.md
@@ -0,0 +1,48 @@
+---
+title: "Moving between runtimes"
+description: "Drain existing runs and move new starts between self-hosted Server deployments and Cloud."
+tags:
+  - migration
+  - operations
+  - polyglot
+---
+
+# Moving between runtimes
+
+Move new starts to the destination while existing runs finish on their source. This procedure covers independent service-mode runtimes. A history export preserves evidence; it does not transfer a live Server-sourced run. The supported [embedded-v2 import](./embedded-to-server.md#phase-e-import-eligible-embedded-v2-runs) accepts eligible embedded sources only.
+
+## Choose the destination {#paths}
+
+| Move | Destination preparation |
+| --- | --- |
+| Self-hosted Server to another self-hosted Server | Deploy the destination with its own authoritative database, payload storage and credentials. Follow the [deployment guide](../deployment.md). |
+| Self-hosted Server to Cloud | Provision the destination namespace and verify its returned runtime URL, credentials and capabilities. Follow [Cloud setup](./cloud-control-plane.md). |
+| Cloud to self-hosted Server | Prepare the self-hosted destination and its SDK workers before changing application traffic. Keep the Cloud source provisioned while its runs drain. |
+
+## Prepare both runtimes {#prepare}
+
+Record each source endpoint, namespace, workflow instance and run ID, task queue, workflow/activity type and payload-store dependency. Preserve a tested recovery path for self-hosted storage. A Cloud move does not grant access to a database backup or copy Cloud credentials to the destination. Verify the actual destination release and capabilities, role credentials, worker registrations and advertised types.
+
+## Switch new starts in small groups {#cutover}
+
+1. Run the destination and its workers beside the source. Complete a uniquely identified canary with representative activities and results. Keep its side effects isolated from real business work.
+2. Inventory every start producer: application calls, schedules, webhook/bridge adapters and service calls. Choose a cutover point for one workflow family. Coordinate schedule pauses and destination registration so both runtimes do not start the same occurrence.
+3. Route that family’s new starts to the destination. Keep an application-owned record of which endpoint and namespace accepted each workflow. Reusing a business key on another runtime does not provide cross-runtime deduplication.
+4. Keep signals, approvals, updates, queries, cancellation and result/history reads pointed at the runtime owning the run. Keep source workers, queues, timers, credentials and payload access available. Changing a client URL does not move accepted work or its activity leases.
+5. Check outcomes and failures before moving the next family. If a start has an uncertain transport outcome, resolve it at the original runtime before submitting it elsewhere. A long-lived run that never reaches terminal state has not drained.
+
+## Preserve evidence before retirement {#preserve-evidence}
+
+Export the history you must retain, including every required continuation run, original payload bytes and codecs. Check completeness and integrity with a compatible consumer, and retain the exact producer identity. [History export and replay guidance](../testing.md#service-sdk-replay) explains the separate checks. Audit exports do not make Server-sourced runs eligible for live import.
+
+Use the producer actually serving the export. Core 2.11.4 alone does not qualify Server, bundled CLI, SDK HTTP or Cloud exports. Follow the separate [Server HTTP producer/image qualification](https://github.com/durable-workflow/server/issues/692). Old lossy bundles remain invalid. Do not change numbers or checksums to force acceptance, and do not destroy the authoritative source while required evidence is unavailable or unverifiable.
+
+## Retire the source last {#retire-source}
+
+Confirm that no source-owned nonterminal runs remain across every relevant namespace and all list pages. Include waiting parents/children and runs created by remaining start producers. A healthy endpoint, an empty first page or unavailable metrics does not prove zero open work. Confirm that no callers, callbacks or workers still depend on the source and that required archives are readable.
+
+Only then retire self-hosted resources or deprovision the Cloud runtime. Cloud capacity charges continue while it remains provisioned, including while idle or draining. Deprovisioning removes active runtime data and credentials and is not pause/resume. Use the existing plan’s returned billing terms; this procedure creates no automatic refund or billing exception.
+
+## Roll back routing without moving runs {#rollback}
+
+Route future starts back only to a healthy, compatible source. Runs already accepted by the destination remain destination-owned and need its workers and command routing until terminal. Preserve both ownership records and prevent duplicate starts. Do not restore old source storage over newer accepted state or resume a second live copy of a run.
diff --git a/i18n/de/docusaurus-plugin-content-docs/current/deployment.md b/i18n/de/docusaurus-plugin-content-docs/current/deployment.md
@@ -6,6 +6,8 @@ description: Einen unterstützten Selbsthosting-Weg für Durable Workflow v2 und
 
 # Selbsthosting-Bereitstellungen {#self-hosting-deployments}
 
+Für den Wechsel zwischen selbst gehosteten Laufzeiten und Cloud folgen Sie [Workloads zwischen Laufzeiten verschieben](/docs/polyglot/runtime-migration/). Bestehende Läufe bleiben auf der Quelle, während neue Starts verlagert werden.
+
 Durable Workflow v2 unterstützt mehrere selbst gehostete Formen. Wählen Sie den kleinsten Weg, der zu Ihrer Betriebsumgebung passt, und halten Sie Verträge für Image, Datenbank, Cache, Authentifizierung, Bereitschaft und Upgrades explizit.
 
 Dieser Leitfaden behandelt die eigenständige Serverdistribution. Betreiben Sie das Laravel-Paket eingebettet in Ihrer Anwendung, verwenden Sie stattdessen die Seiten zu Paketinstallation und -konfiguration. Durable Workflow Cloud ist eine separate verwaltete Dienstoption, bei der Cloud Laufzeit, Persistenz, Platzierung und Wiederherstellung betreibt. Ein selbst gehosteter Server wird niemals an Cloud angebunden. Siehe [Verwaltete Cloud-Laufzeit](/docs/polyglot/cloud-control-plane). Der aktuelle Cloud-Vertrag umfasst eine verwaltete Laufzeit und Wiederherstellungsgrenze in einer einzelnen Region. Er verspricht keine regionsübergreifende Replikation, automatisches regionales Failover oder Failback.

diff --git a/i18n/de/docusaurus-plugin-content-docs/current/laravel-adoption.md b/i18n/de/docusaurus-plugin-content-docs/current/laravel-adoption.md
@@ -486,6 +486,8 @@ Verwenden Sie für den Selbsthosting-Import das vollständige [Migrationsverfahr
 
 Ein altes Paket, eine Warteschlange, Tabelle, ein Geheimnis oder eine Waterline-Bereitstellung wird zuletzt stillgelegt. Dies ist nie der Umstellungsmechanismus.
 
+Für Wechsel zwischen Laufzeiten im Service-Modus verwenden Sie [Workloads zwischen Laufzeiten verschieben](/docs/polyglot/runtime-migration/). Server-Verlaufsexport ist kein Import laufenden Zustands.
+
 ## Mit dem gewählten Weg fortfahren {#continue-with-the-chosen-path}
 
 - [Stabile v1-Installation](/docs/1.x/installation/)

diff --git a/i18n/de/docusaurus-plugin-content-docs/current/polyglot/cloud-control-plane.md b/i18n/de/docusaurus-plugin-content-docs/current/polyglot/cloud-control-plane.md
@@ -568,6 +568,8 @@ dasselbe Modell bereitgestellter Zeit mit eigenen Sätzen, Mindest- und
 Höchstbeträgen. Verwenden Sie beim Interpretieren der Nutzung die vom Plan
 zurückgegebenen `billing_terms`. Historische Rechnungen behalten ihre akzeptierten Bedingungen.
 
+Folgen Sie vor der Deprovisionierung [Workloads zwischen Laufzeiten verschieben](/docs/polyglot/runtime-migration/#preserve-evidence): Bewahren Sie geprüfte Verlaufs- und Payload-Nachweise auf und bestätigen Sie den Endzustand aller Quell-Läufe. Kapazitätskosten laufen weiter, solange die Quelle bereitgestellt ist.
+
 Exportieren Sie dieselben Nachweise als CSV oder JSON-Bericht, wenn ein
 nachgelagertes Finanzsystem eine Datei benötigt:
 

diff --git a/i18n/de/docusaurus-plugin-content-docs/current/polyglot/deployment-modes.md b/i18n/de/docusaurus-plugin-content-docs/current/polyglot/deployment-modes.md
@@ -98,6 +98,8 @@ Drei Regeln sind verbindlich:
 
 ## Weitere Referenzen {#related-references}
 
+[Workloads zwischen Laufzeiten verschieben](/docs/polyglot/runtime-migration/) beschreibt das Auslaufen und Umschalten zwischen selbst gehosteten Servern, von Server zu Cloud und von Cloud zu Server.
+
 - [Installation](/docs/installation)
 - [Server](/docs/polyglot/server)
 - [PHP-SDK](/docs/polyglot/php)

diff --git a/i18n/de/docusaurus-plugin-content-docs/current/polyglot/runtime-migration.md b/i18n/de/docusaurus-plugin-content-docs/current/polyglot/runtime-migration.md
@@ -0,0 +1,48 @@
+---
+title: "Workloads zwischen Laufzeiten verschieben"
+description: "Bestehende Läufe beenden lassen und neue Starts zwischen selbst gehosteten Servern und Cloud verlagern."
+tags:
+  - migration
+  - operations
+  - polyglot
+---
+
+# Workloads zwischen Laufzeiten verschieben
+
+Leiten Sie neue Starts zum Ziel, während bestehende Läufe auf ihrer Quelle enden. Dieses Verfahren gilt für unabhängige Laufzeiten im Service-Modus. Ein Verlaufsexport erhält Nachweise, überträgt aber keinen laufenden Server-Lauf. Der unterstützte [Embedded-v2-Import](./embedded-to-server.md#phase-e-import-eligible-embedded-v2-runs) akzeptiert nur geeignete Embedded-Quellen.
+
+## Ziel auswählen {#paths}
+
+| Wechsel | Zielvorbereitung |
+| --- | --- |
+| Selbst gehosteter Server zu anderem selbst gehosteten Server | Stellen Sie das Ziel mit eigener maßgeblicher Datenbank, Payload-Speicher und Zugangsdaten bereit. Folgen Sie der [Bereitstellungsanleitung](../deployment.md). |
+| Selbst gehosteter Server zu Cloud | Stellen Sie den Ziel-Namespace bereit und prüfen Sie zurückgegebene Laufzeit-URL, Zugangsdaten und Fähigkeiten. Folgen Sie der [Cloud-Einrichtung](./cloud-control-plane.md). |
+| Cloud zu selbst gehostetem Server | Bereiten Sie Ziel und SDK-Worker vor, bevor Sie den Anwendungsverkehr ändern. Lassen Sie die Cloud-Quelle bereitgestellt, während ihre Läufe enden. |
+
+## Beide Laufzeiten vorbereiten {#prepare}
+
+Erfassen Sie Quell-Endpunkt, Namespace, Workflow-Instanz- und Lauf-ID, Task Queue, Workflow-/Activity-Typen und Payload-Speicherabhängigkeiten. Erhalten Sie einen getesteten Wiederherstellungsweg für selbst gehosteten Speicher. Ein Cloud-Wechsel gewährt keinen Zugriff auf ein Datenbankbackup und kopiert keine Cloud-Zugangsdaten zum Ziel. Prüfen Sie tatsächliche Zielversion und Fähigkeiten, Rollen-Zugangsdaten, Worker-Registrierungen und gemeldete Typen.
+
+## Neue Starts in kleinen Gruppen umstellen {#cutover}
+
+1. Betreiben Sie Ziel und Worker neben der Quelle. Schließen Sie einen eindeutig identifizierten Canary-Lauf mit repräsentativen Activities und Ergebnissen ab. Trennen Sie seine Auswirkungen von echten Geschäftsvorgängen.
+2. Erfassen Sie alle Startquellen: Anwendungsaufrufe, Zeitpläne, Webhook-/Bridge-Adapter und Service-Aufrufe. Wählen Sie einen Umschaltpunkt für eine Workflow-Familie. Stimmen Sie Zeitplanpausen und Zielregistrierung so ab, dass beide Laufzeiten nicht denselben Termin starten.
+3. Leiten Sie neue Starts dieser Familie zum Ziel. Halten Sie in der Anwendung fest, welcher Endpunkt und Namespace jeden Workflow angenommen hat. Ein erneut verwendeter Geschäftsschlüssel auf einer anderen Laufzeit bietet keine laufzeitübergreifende Deduplizierung.
+4. Leiten Sie Signale, Freigaben, Updates, Abfragen, Abbrüche sowie Ergebnis- und Verlaufsabrufe weiter zur zuständigen Laufzeit. Erhalten Sie Quell-Worker, Queues, Timer, Zugangsdaten und Payload-Zugriff. Eine geänderte Client-URL verschiebt weder angenommene Arbeit noch deren Activity-Leases.
+5. Prüfen Sie Ergebnisse und Fehler vor der nächsten Familie. Bei ungewissem Startergebnis durch Transportfehler klären Sie es zuerst auf der ursprünglichen Laufzeit, bevor Sie anderswo starten. Ein langlebiger Lauf ohne Endzustand ist noch nicht abgeschlossen.
+
+## Nachweise vor der Stilllegung sichern {#preserve-evidence}
+
+Exportieren Sie den aufzubewahrenden Verlauf einschließlich aller erforderlichen Fortsetzungsläufe, ursprünglichen Payload-Bytes und Codecs. Prüfen Sie Vollständigkeit und Integrität mit einem kompatiblen Verbraucher und bewahren Sie die genaue Erzeugeridentität auf. Die [Anleitung zu Verlaufsexport und Replay](../testing.md#service-sdk-replay) erklärt die getrennten Prüfungen. Audit-Exporte erlauben keinen Import laufenden Server-Zustands.
+
+Prüfen Sie den Erzeuger, der den Export tatsächlich liefert. Core 2.11.4 allein qualifiziert keine Server-, mitgelieferten CLI-, SDK-HTTP- oder Cloud-Exporte. Beachten Sie die separate [Qualifikation des Server-HTTP-Erzeugers und Images](https://github.com/durable-workflow/server/issues/692). Alte verlustbehaftete Bundles bleiben ungültig. Ändern Sie weder Zahlen noch Prüfsummen, um die Annahme zu erzwingen, und zerstören Sie die maßgebliche Quelle nicht, solange erforderliche Nachweise fehlen oder nicht prüfbar sind.
+
+## Quelle zuletzt stilllegen {#retire-source}
+
+Bestätigen Sie für alle relevanten Namespaces und alle Listenseiten, dass keine nicht terminalen Quell-Läufe verbleiben. Berücksichtigen Sie wartende Eltern/Kinder und Läufe verbleibender Startquellen. Ein gesunder Endpunkt, eine leere erste Seite oder fehlende Metriken beweisen keine leere Arbeitsmenge. Prüfen Sie, dass keine Aufrufer, Callbacks oder Worker mehr von der Quelle abhängen und erforderliche Archive lesbar sind.
+
+Entfernen Sie erst dann selbst gehostete Ressourcen oder deprovisionieren Sie die Cloud-Laufzeit. Cloud-Kapazitätskosten laufen weiter, solange sie bereitgestellt ist, auch im Leerlauf oder beim Auslaufen. Die Deprovisionierung entfernt aktive Laufzeitdaten und Zugangsdaten und ist keine Pause mit Fortsetzung. Es gelten die zurückgegebenen Bedingungen des bestehenden Plans; dieses Verfahren schafft weder automatische Erstattung noch Abrechnungsausnahme.
+
+## Routing zurücknehmen, ohne Läufe zu verschieben {#rollback}
+
+Leiten Sie künftige Starts nur zu einer gesunden, kompatiblen Quelle zurück. Vom Ziel bereits angenommene Läufe bleiben dort und benötigen dessen Worker und Befehlsrouting bis zum Endzustand. Erhalten Sie beide Zuständigkeitsverzeichnisse und verhindern Sie doppelte Starts. Stellen Sie keinen alten Quellspeicher über neuerem angenommenem Zustand wieder her und starten Sie keine zweite aktive Kopie eines Laufs.
diff --git a/i18n/de/source-hashes.json b/i18n/de/source-hashes.json
@@ -27,7 +27,7 @@
   "defining-workflows/workflow-id.md": "91b94211e2f8f405895ad82cfe2ef9baadb7a2cbd06e9c1e7aa6362231e0d424",
   "defining-workflows/workflow-status.md": "8e8cb27ff44c890d489d89bf166375acfdfaecabd990a2235e106fab1592d529",
   "defining-workflows/workflows.md": "f467bc73de32aa5d722c61ce085065460382ae7dd44cea4625847d9fcdc4c97c",
-  "deployment.md": "dd0b6bd184eda12e67922121a09c7f3c98346bde01be1d4c3217f168db5fd7ca",
+  "deployment.md": "9742b8637f568aafd5b61e7de97a368aad6faf95a4efd40323269477edfdfba1",
   "failures-and-recovery.md": "7df0b7ce4139b789d8988ce2bf640c388225daa28731b88719e4777f61e40a4c",
   "features/activity-execution-model.md": "e8c37520ae46a7efb30438f4fc06bf893c1df430cb1f92c48963697adaf09082",
   "features/cancel-and-terminate.md": "c678fc7a0c9b11f0e1bee295aff259de9803219c0aa6769fb801622799e7deb1",
@@ -59,7 +59,7 @@
   "how-it-works.md": "90454c37f4244297d5c11bcc59549859acf59f88d15ecd26f0a6951c115f86eb",
   "installation.md": "1e2e04a8f23414d0e81c72b166700fd6350129ab81b2f22a6205856c23741967",
   "introduction.md": "06bf96d164d402d4e376c6308b20f96d324110b2e0cf96c2a1a67b39906072e3",
-  "laravel-adoption.md": "978f2333bf5ce38ebc58619ca3f50a087572a3b0c28d52bc06843bc341010684",
+  "laravel-adoption.md": "dd998f6ac33691f793ffcecce78dea82aef7c6d22b1344d5d6ab5234619db8a8",
   "mcp-workflows.md": "1c0b5bb7f2e5c7ca835dfdfa57bbe8f6624172c855f4e225057ac2377abf360e",
   "migration.md": "53659987d64f3fc66c935bed55ec4227689185a23970f31327773fa408f5cf22",
   "monitoring.md": "202278c1196508df5ff00d34cfe94fd2d60dfb7fd2fcb768cf37864c7605de0a",
@@ -71,8 +71,8 @@
   "polyglot/cli-python-parity.md": "acf1acbf15ca9cdf069154699c5fbf8c1d1fd3241a32d201ac10b8ec76c038be",
   "polyglot/cli-reference.md": "b20db162aa91cc85ea64528a061753a99f053b33b6141664ce1194e711c641cc",
   "polyglot/cli.mdx": "024a3f73e1c700a7fa142ec64a7edde03303f12507f4eb4a9161e0e944f7431b",
-  "polyglot/cloud-control-plane.md": "09a3487e496100dfcef854c56bc12cb8193c7267236cd992b7defc40b7ecb706",
-  "polyglot/deployment-modes.md": "ee38a2ca890e6ba5d52fffa1fa0bc65e64a1fc82e47af92463983e523d4e3f49",
+  "polyglot/cloud-control-plane.md": "bb375e598dd1afa3207171047fb81b0cb82c382ce535ab415cb09dc10f6d748e",
+  "polyglot/deployment-modes.md": "7b508db4be86c92de76cfd8dfd946d93941c8a6f0a601a161d4d3fd1711bf97f",
   "polyglot/embedded-to-server.md": "21a7e4c9439a73db3a97fd9b0610749faabf7c449806fe0ad55a0924f50d3b80",
   "polyglot/external-execution.md": "410728db1107c328d0cb129cbf0c58f4fa8c6427e0406610d6801dfeb8a2db31",
   "polyglot/invocable-carrier.md": "d32d8b5c7c33204b342f977e0af734166d91e96073db1a49ccb4d414a6d67380",
@@ -83,6 +83,7 @@
   "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959",
   "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c",
   "polyglot/python.md": "d55056ca7638df07b7267bc6d62e635b954957b99620478e861df90558860df3",
+  "polyglot/runtime-migration.md": "5a78713bb8cb74aea58f6d5d826400d968a405f69c6ff17fdf2f7decb1d14b71",
   "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3",
   "polyglot/rust.md": "af91b22c93a7fe6833df156371d99bb105740684915bc73af4576f6de2897e10",
   "polyglot/server-api-reference.md": "e94af77a13b341d6fdc9941d4ee94e5053ab932d2e77069b238eb33351414e83",

diff --git a/i18n/es/docusaurus-plugin-content-docs/current/deployment.md b/i18n/es/docusaurus-plugin-content-docs/current/deployment.md
@@ -6,6 +6,8 @@ description: Elige una opción admitida de alojamiento propio de Durable Workflo
 
 # Despliegues autogestionados {#self-hosting-deployments}
 
+Para cambiar entre runtimes autogestionados o Cloud, siga [trasladar cargas entre runtimes](/docs/polyglot/runtime-migration/). Las ejecuciones existentes permanecen en el origen mientras se trasladan los nuevos inicios.
+
 Durable Workflow v2 admite varias topologías autogestionadas. Elige la más
 sencilla que corresponda al entorno que operas y define explícitamente el
 contrato de imagen, base de datos, caché, autenticación, disponibilidad y actualización.