Select the native tuple Server 3.3.2 and chart 1.1.0

docs/deployment.md

@@ -268,6 +268,62 @@ command-level Compose examples in the
 [Official Image + Compose](https://github.com/durable-workflow/server/blob/main/docs/server-reference.md#official-image--compose)
 section.
 
+### Upgrading from Server 3.0.x to 3.3.2 {#native-schema-upgrade-3-0-to-3-3}
+
+Server 3.3.2 crosses three minor releases from 3.0.x and changes the native
+schema. On MySQL, MariaDB and PostgreSQL it moves from version 8 (3.0.x and
+3.1.0) through 10 (3.2.0) to 11 (3.3.0 to 3.3.2). On SQLite it moves from 8
+to 10. A Server never upgrades its schema at startup: 3.3.2 started on a
+version 8 database refuses with `native_schema_upgrade_required`, so changing
+`DW_SERVER_IMAGE` alone leaves the new Server unable to start. The 3.3.2
+image's `schema-upgrade` command upgrades a version 8 database directly. The
+[3.3.0 upgrade notes](https://github.com/durable-workflow/server/blob/3.3.2/docs/releases/3.3.0.md#upgrade)
+describe the step, and the Helm chart's
+[Chart 1.1.0 / Server 3.3.2 notes](%%artifact.helmChartUpgradeUrl%%#chart-110--server-332-native)
+list the schema steps and the runtime changes from 3.0.5 to 3.3.2.
+
+For the single-node Compose deployment:
+
+1. Stop the Server and leave MySQL running:
+
+   ```bash
+   docker compose --env-file durable-workflow.prod.env \
+     -f docker-compose.published.yml stop server
+   ```
+2. Back up MySQL and `server_storage`, and record the current image
+   reference. This backup is the only way back to 3.0.x.
+3. Change `DW_SERVER_IMAGE` to the 3.3.2 image, pull it and run
+   `schema-upgrade` once:
+
+   ```bash
+   docker compose --env-file durable-workflow.prod.env \
+     -f docker-compose.published.yml pull server
+   docker compose --env-file durable-workflow.prod.env \
+     -f docker-compose.published.yml run --rm --no-deps server schema-upgrade
+   ```
+
+   It prints the backend and the schema versions before and after, for
+   example `"from_schema_version":8,"schema_version":11,"status":"upgraded"`.
+   On a database that is already current it only verifies the schema.
+4. Start the Server with
+   `docker compose --env-file durable-workflow.prod.env -f docker-compose.published.yml up -d --wait`,
+   then confirm `/api/ready`, `/api/cluster/info` (`version` is `3.3.2`) and
+   worker registration.
+
+- **PostgreSQL:** the version 10 and 11 steps build their indexes with a plain
+  `CREATE INDEX`, which blocks writes to `workflow_tasks` until the build
+  finishes. On a large `workflow_tasks` table, plan the downtime for it.
+- **MySQL and MariaDB:** DDL commits on its own there, so the upgrade marks the
+  database as upgrading until it finishes, and every Server refuses it
+  meanwhile with `native_schema_upgrade_incomplete`. If an upgrade is
+  interrupted, run `schema-upgrade` again to resume it.
+- **Rollback needs the backup.** There is no schema downgrade. A 3.0.x Server
+  refuses an upgraded database with `native_schema_newer_than_binary`. To go
+  back, restore the backup taken in step 2, which discards everything written
+  after it, and then start the 3.0.x image.
+
+The worker protocol stays at `1.20` and the control plane at version `2`.
+
 ## Small clustered deployments
 
 :::note PHP Server 2.x contract
@@ -540,6 +596,19 @@ the PHP 2.x worker, scheduler, bootstrap job and Redis. To move to
 and keep `runtime: php` until the takeover is done. See the chart's
 [UPGRADING notes](%%artifact.helmChartUpgradeUrl%%).
 
+Chart 1.1.0 changes the default image from Server 3.0.5 to 3.3.2, which needs
+the [native schema upgrade](#native-schema-upgrade-3-0-to-3-3) from 8 to 11.
+An ordinary `helm upgrade` from chart 1.0.x changes only the image, and the new
+pods refuse to start with `native_schema_upgrade_required`. Follow the chart's
+[Chart 1.1.0 / Server 3.3.2 steps](%%artifact.helmChartUpgradeUrl%%#chart-110--server-332-native):
+scale the Server to zero with autoscaling off, back up the database, then
+upgrade to chart 1.1.0 with `native.schemaUpgrade.enabled=true`. Its
+`pre-upgrade` hook runs `schema-upgrade` once before the new pods start, and
+only when Helm's `lookup` shows every Server stopped. Argo CD, Flux and
+`helm template` renders refuse the hook; use the chart README's manual Job
+instead. A `helm rollback` to a chart 1.0.x revision does not bring the Server
+back, because 3.0.x refuses the upgraded database: restore the backup instead.
+
 ### Choosing a chart release {#helm-chart-selection}
 
 One chart release records the Server image it was tested against in `Chart.yaml`'s `appVersion`; the chart and Server have independent version numbers. The selected [compatibility tuple](./compatibility.md#last-qualified-reproducible-tuple) pairs chart **%%artifact.helmChartVersion%%** with Server **%%artifact.helmChartAppVersion%%**, from the same release metadata as the table and install command. Its [published OCI/package receipt](%%artifact.helmChartQualificationUrl%%) verifies that pairing, not a fresh Kubernetes installation.

docs/polyglot/database-support.md

@@ -10,16 +10,16 @@ workers rather than a runtime database.
 
 A declared compatibility baseline is not proof that every later version is
 qualified. Source tests and installed, published artifacts are different
-evidence. This snapshot binds Workflow 2.20.3 source and Server 3.0.5 release
+evidence. This snapshot binds Workflow 2.20.3 source and Server 3.3.2 release
 receipts. It does not change runtime compatibility or establish a lowest/newest
 tested range.
 
 | Engine | Declared compatibility | Observed source qualification | Published-artifact qualification |
 | --- | --- | --- | --- |
-| MySQL | Embedded: 8.0 baseline. Server: 8.0 baseline. | Core: 26.10.0 in the original floating-image feature jobs. Server profiles: 8.0.46 and 8.4.5. | Core observation is release-source-bound. Server 3.0.5 Compose uses floating `mysql:8.0` for schema/health smoke, not a full execution/capacity/TLS qualification. |
-| PostgreSQL | Embedded: 13 baseline. Server: 13 baseline. | Core: 18.6. Server profiles: 16.15 and 17.11. | Core observation is release-source-bound. No Server 3.0.5-index-bound PostgreSQL endpoint receipt was found in the inspected release inventory. |
-| MariaDB | Embedded: 10.5 baseline. Server accepts `mariadb`; no version baseline is established here. | Core: 10.5.29. Server profile: 10.11.19. | Core observation is release-source-bound. No Server 3.0.5-index-bound MariaDB endpoint receipt was found in the inspected release inventory. |
-| SQLite | Embedded capability/tests include SQLite. Server declares a 3.35 baseline. | The original Core source jobs did not emit the SQLite library version. | Installed Core 2.20.3 acceptance exercised SQLite, without establishing a library-version range. Server's frozen 3.1.0 candidate corpus is separate from stable 3.0.5. |
+| MySQL | Embedded: 8.0 baseline. Server: 8.0 baseline. | Core: 26.10.0 in the original floating-image feature jobs. Server profiles: 8.0.46 and 8.4.5. | Core observation is release-source-bound. Server 3.3.2's release smoke and exact-index Compose smoke use digest-pinned MySQL 8.0 for start/health checks, not a full execution/capacity/TLS qualification. |
+| PostgreSQL | Embedded: 13 baseline. Server: 13 baseline. | Core: 18.6. Server profiles: 16.15 and 17.11. | Core observation is release-source-bound. Server 3.3.2's release smoke cold-starts each architecture's image on digest-pinned PostgreSQL 17 for readiness and cluster info only, not a full execution/capacity/TLS qualification. |
+| MariaDB | Embedded: 10.5 baseline. Server accepts `mariadb`; no version baseline is established here. | Core: 10.5.29. Server profile: 10.11.19. | Core observation is release-source-bound. No Server 3.3.2-index-bound MariaDB endpoint receipt was found in the inspected release evidence. |
+| SQLite | Embedded capability/tests include SQLite. Server declares a 3.35 baseline. | The original Core source jobs did not emit the SQLite library version. | Installed Core 2.20.3 acceptance exercised SQLite, without establishing a library-version range. Server 3.3.2's release smoke cold-starts on SQLite, also without a library-version range. |
 | SQL Server | Published embedded Core advertises `sqlsrv`, but it remains unqualified. Server qualification is not established here. | No SQL Server job was recovered from the published Core matrix. The proposed backend guard is separate source work. | No corresponding release qualification was recovered. Do not infer support from the embedded capability advertisement. |
 
 ## Reading the evidence {#reading-the-evidence}
@@ -33,12 +33,20 @@ covers 67 SQLite-backed stream/replay/fake cases. Neither a PHP version nor a
 floating image selector supplies an unreported database version.
 
 The [Server inventory](https://github.com/durable-workflow/server/issues/563#issuecomment-6642659277)
-separates native and legacy PHP source-job scopes. The
+separates native and legacy PHP source-job scopes. For Server 3.3.2, the
+[release run](https://github.com/durable-workflow/server/actions/runs/42591612884)
+cold-starts the amd64 and arm64 images on SQLite, PostgreSQL 17 and MySQL 8.0,
+checks `/api/ready` and authenticated cluster info, and stops each with SIGTERM.
+The [exact-index Compose smoke](https://github.com/durable-workflow/server/actions/runs/42602031026)
+has four architecture/profile cells against index `sha256:4aeceb42…`. Both
+`local` and `production` use MySQL, with `mysql:8.0` pinned by digest. The
+[3.3.2 delivery record](https://github.com/durable-workflow/server/issues/325#issuecomment-6739628227)
+accepts both. These runs start empty databases. They do not upgrade
+an existing one, qualify write capacity or verify TLS, and their logs do not
+report an exact engine patch version. The earlier
 [stable 3.0.5 receipt](https://github.com/durable-workflow/server/issues/563#issuecomment-6643169603)
-has four architecture/profile Compose smoke cells. Both `local` and `production`
-use MySQL. The inspected logs do not recover an exact companion version/digest,
-write-capacity qualification or verified TLS. Source profiles and a frozen
-candidate do not qualify a different published image.
+had the same Compose shape with a floating `mysql:8.0`. Source profiles do not
+qualify a different published image.
 
 ## Vendor lifecycle and distributed engines {#vendor-lifecycle-and-distributed-engines}
 

docs/polyglot/server.md

@@ -516,22 +516,37 @@ curl http://localhost:8080/api/cluster/info \
 
 Returns the build identity, capability flags, protocol manifests, limits and
 discovery for the namespace named by `X-Namespace` (or the `namespace` query
-parameter, else `default`). Abridged output from the 3.0.5 image:
+parameter, else `default`). Abridged output from the 3.3.2 image:
 
 ```json
 {
-  "version": "3.0.5",
+  "version": "3.3.2",
   "implementation": "rust",
   "development": false,
   "server_id": "2145ce2abb12",
   "default_namespace": "default",
+  "supported_sdk_versions": {
+    "php": ">=3.8.1,<4.0.0",
+    "python": ">=2.13.0,<3.0.0",
+    "rust": ">=4.10.3,<5.0.0",
+    "cli": ">=2.0.0,<3.0.0"
+  },
+  "client_compatibility": {
+    "schema": "durable-workflow.v2.client-compatibility",
+    "version": 2,
+    "authority": "protocol_manifests",
+    "fail_closed": true,
+    "...": "..."
+  },
   "capabilities": {
     "workflow_tasks": true,
     "activity_tasks": true,
     "signals": true,
     "queries": true,
     "updates": true,
     "schedules": true,
+    "child_workflow_start_turn": true,
+    "condition_wait_occurrence_deadline": true,
     "timer_runtime_contract": false,
     "payload_codecs": ["avro"],
     "response_compression": []
@@ -571,7 +586,7 @@ Key field notes for client code:
 - The build version is `version`, not `server_version`. `implementation` is
   `"rust"` on the native Server.
 - Check `control_plane.version` and `worker_protocol.version` before calling
-  the API. Native 3.0.5 serves control plane `2` and worker protocol `1.20`,
+  the API. Native 3.3.2 serves control plane `2` and worker protocol `1.20`,
   and accepts worker requests that send any protocol version from `1.0` to
   `1.20`.
 - Workflow-task commands live under
@@ -580,8 +595,11 @@ Key field notes for client code:
   native does not serve. `response_compression` is empty because native sends
   uncompressed responses.
 - `native_unqualified` lists each member of the PHP 2.x response that native
-  leaves out, with the reason. It includes `topology`,
-  `supported_sdk_versions` and `client_compatibility`.
+  leaves out, with the reason. It includes `topology`.
+- Since 3.1.0, native also serves `supported_sdk_versions` and
+  `client_compatibility`, which the CLI's `server:info` and `doctor` read.
+  `client_compatibility.authority` is `"protocol_manifests"`: check the
+  protocol manifests, not the SDK ranges, before calling the API.
 - The sole payload codec is Avro: `capabilities.payload_codecs` is exactly
   `["avro"]`.
 - `qualified_for_php_takeover` is always `false`. It describes the running

i18n/de/docusaurus-plugin-content-docs/current/deployment.md

@@ -195,6 +195,37 @@ Upgrade-Reihenfolge:
 
 Der native Server prüft sein Schema beim Start. Patch-Veröffentlichungen innerhalb einer nativen Minor-Linie behalten das Schema bei, daher genügt ein Image-Wechsel. Eine Veröffentlichung, deren Hinweise eine Schemaänderung ankündigen, benötigt zusätzlich den Befehl `schema-upgrade` des Images, ausgeführt nach einer Datenbanksicherung, während alle Server gestoppt sind. Die Server-Referenz enthält aktuelle Compose-Befehlsbeispiele unter [Offizielles Image + Compose](https://github.com/durable-workflow/server/blob/main/docs/server-reference.md#official-image--compose).
 
+### Upgrade von Server 3.0.x auf 3.3.2 {#native-schema-upgrade-3-0-to-3-3}
+
+Server 3.3.2 liegt drei Minor-Veröffentlichungen nach 3.0.x und ändert das native Schema. Auf MySQL, MariaDB und PostgreSQL wechselt es von Version 8 (3.0.x und 3.1.0) über 10 (3.2.0) auf 11 (3.3.0 bis 3.3.2). Auf SQLite wechselt es von 8 auf 10. Ein Server aktualisiert sein Schema nie beim Start: 3.3.2 verweigert auf einer Datenbank mit Version 8 den Start mit `native_schema_upgrade_required`, daher kann der neue Server nicht starten, wenn nur `DW_SERVER_IMAGE` geändert wird. Der Befehl `schema-upgrade` des 3.3.2-Images aktualisiert eine Datenbank mit Version 8 direkt. Die [Upgrade-Hinweise zu 3.3.0](https://github.com/durable-workflow/server/blob/3.3.2/docs/releases/3.3.0.md#upgrade) beschreiben den Schritt, und die [Hinweise zu Chart 1.1.0 / Server 3.3.2](%%artifact.helmChartUpgradeUrl%%#chart-110--server-332-native) des Helm-Charts führen die Schemaschritte und die Laufzeitänderungen von 3.0.5 auf 3.3.2 auf.
+
+Für die Compose-Bereitstellung auf einem einzelnen Knoten:
+
+1. Stoppen Sie den Server und lassen Sie MySQL weiterlaufen:
+
+   ```bash
+   docker compose --env-file durable-workflow.prod.env \
+     -f docker-compose.published.yml stop server
+   ```
+2. Sichern Sie MySQL und `server_storage` und halten Sie die aktuelle Image-Referenz fest. Diese Sicherung ist der einzige Weg zurück zu 3.0.x.
+3. Ändern Sie `DW_SERVER_IMAGE` auf das 3.3.2-Image, rufen Sie es ab und führen Sie `schema-upgrade` einmal aus:
+
+   ```bash
+   docker compose --env-file durable-workflow.prod.env \
+     -f docker-compose.published.yml pull server
+   docker compose --env-file durable-workflow.prod.env \
+     -f docker-compose.published.yml run --rm --no-deps server schema-upgrade
+   ```
+
+   Der Befehl gibt das Backend und die Schemaversionen vorher und nachher aus, zum Beispiel `"from_schema_version":8,"schema_version":11,"status":"upgraded"`. Auf einer bereits aktuellen Datenbank prüft er nur das Schema.
+4. Starten Sie den Server mit `docker compose --env-file durable-workflow.prod.env -f docker-compose.published.yml up -d --wait` und bestätigen Sie dann `/api/ready`, `/api/cluster/info` (`version` ist `3.3.2`) und die Worker-Registrierung.
+
+- **PostgreSQL:** Die Schritte zu Version 10 und 11 erstellen ihre Indizes mit einem einfachen `CREATE INDEX`, das Schreibzugriffe auf `workflow_tasks` blockiert, bis der Aufbau abgeschlossen ist. Planen Sie bei einer großen Tabelle `workflow_tasks` die Ausfallzeit dafür ein.
+- **MySQL und MariaDB:** DDL wird dort eigenständig committet, daher markiert das Upgrade die Datenbank bis zu seinem Abschluss als im Upgrade befindlich, und jeder Server verweigert sie währenddessen mit `native_schema_upgrade_incomplete`. Wird ein Upgrade unterbrochen, führen Sie `schema-upgrade` erneut aus, um es fortzusetzen.
+- **Ein Rollback erfordert die Sicherung.** Es gibt kein Schema-Downgrade. Ein 3.0.x-Server verweigert eine aktualisierte Datenbank mit `native_schema_newer_than_binary`. Um zurückzuwechseln, stellen Sie die in Schritt 2 erstellte Sicherung wieder her, wodurch alles danach Geschriebene verworfen wird, und starten dann das 3.0.x-Image.
+
+Das Worker-Protokoll bleibt bei `1.20` und die Steuerungsebene bei Version `2`.
+
 ## Kleine Clusterbereitstellungen {#small-clustered-deployments}
 
 :::note Vertrag des PHP-Servers 2.x
@@ -405,6 +436,8 @@ Chart 1.x betreibt standardmäßig den nativen Server (`runtime: native`): ein S
 
 Ein bestehender PHP-2.x-Release wechselt bei einem gewöhnlichen Upgrade nicht auf den nativen Server: Das Chart verweigert das Upgrade, bis Sie `runtime` ausdrücklich setzen. Setzen Sie `runtime: php`, um Worker, Scheduler, Bootstrap-Job und Redis von PHP 2.x zu behalten. Um auf `runtime: native` zu wechseln, folgen Sie dem [Runbook zur nativen Übernahme](%%artifact.serverTakeoverRunbookUrl%%) und behalten `runtime: php` bei, bis die Übernahme abgeschlossen ist. Siehe die [UPGRADING-Hinweise](%%artifact.helmChartUpgradeUrl%%) des Charts.
 
+Chart 1.1.0 ändert das Standard-Image von Server 3.0.5 auf 3.3.2, das das [native Schema-Upgrade](#native-schema-upgrade-3-0-to-3-3) von 8 auf 11 erfordert. Ein gewöhnliches `helm upgrade` von Chart 1.0.x ändert nur das Image, und die neuen Pods verweigern den Start mit `native_schema_upgrade_required`. Folgen Sie den [Schritten zu Chart 1.1.0 / Server 3.3.2](%%artifact.helmChartUpgradeUrl%%#chart-110--server-332-native) des Charts: Skalieren Sie den Server bei ausgeschaltetem Autoscaling auf null, sichern Sie die Datenbank und führen Sie dann das Upgrade auf Chart 1.1.0 mit `native.schemaUpgrade.enabled=true` aus. Sein `pre-upgrade`-Hook führt `schema-upgrade` einmal aus, bevor die neuen Pods starten, und nur, wenn Helms `lookup` zeigt, dass alle Server gestoppt sind. Renderings durch Argo CD, Flux und `helm template` verweigern den Hook; verwenden Sie stattdessen den manuellen Job aus der README des Charts. Ein `helm rollback` auf eine Revision von Chart 1.0.x bringt den Server nicht zurück, weil 3.0.x die aktualisierte Datenbank verweigert: Stellen Sie stattdessen die Sicherung wieder her.
+
 ### Einen Chart-Release auswählen {#helm-chart-selection}
 
 Jeder Chart-Release hält das getestete Server-Image in der `appVersion` der `Chart.yaml` fest; Chart und Server haben unabhängige Versionsnummern. Die ausgewählte [kompatible Kombination](./compatibility.md#last-qualified-reproducible-tuple) verbindet Chart **%%artifact.helmChartVersion%%** mit Server **%%artifact.helmChartAppVersion%%** aus denselben Release-Metadaten wie Tabelle und Installationsbefehl. Der [Prüfbericht zu OCI/veröffentlichtem Paket](%%artifact.helmChartQualificationUrl%%) bestätigt diese Kombination, keine neue Kubernetes-Installation.