deploy: f13c30a

Author: github-actions[bot]

2.0/llms-full.txt

@@ -8442,7 +8442,9 @@ self-serve contract is intentionally narrow:
   `DW_V2_MATCHING_ROLE_QUEUE_WAKE=0` to `shape: "dedicated"` and
   `wake_owner: "dedicated_repair_pass"`. The same block should continue to
   advertise `partition_primitives` of `connection`, `queue`, `compatibility`,
-  and `namespace`, plus the `lease_ownership` `backpressure_model`.
+  and `namespace`, plus the `lease_ownership` `backpressure_model`. See
+  [Server Role Topology](/docs/2.0/polyglot/server-role-topology) for the
+  field-by-field meaning of the topology manifest.
 - Scale external SDK workers independently from API nodes. Workers can run on
   separate hosts or processes, but they should talk to the load-balanced API
   endpoint rather than to one sticky node.
@@ -8467,7 +8469,9 @@ product topology. Treat that as one contract with different role assignments,
 not as a second server product. If you pilot a more explicit role split later,
 keep reading `topology.current_shape`, `topology.current_roles`, and
 `topology.matching_role` from `/api/cluster/info` instead of inferring duties
-from hostnames or container names.
+from hostnames or container names. The
+[Server Role Topology](/docs/2.0/polyglot/server-role-topology) page explains
+those role assignments and the migration path in one place.
 
 Every API node should use the same auth tokens or signature keys, app version,
 workflow package version, payload-codec configuration, database connection, and
@@ -10353,6 +10357,12 @@ unsupported.
 
 ### Role topology and deployment shape
 
+The field-by-field reference for this manifest lives on
+[Server Role Topology](/docs/2.0/polyglot/server-role-topology). Keep this
+section for the inline `cluster/info` example and use the dedicated page when
+you need the supported shapes, authority boundaries, failure domains, scaling
+boundaries, or migration-path contract in one place.
+
 `GET /api/cluster/info` also publishes a `topology` manifest. It is the
 machine-readable role map for the node that answered the request, so operators
 and automation can read one contract instead of inferring node duties from
@@ -11409,12 +11419,22 @@ curl -sS "$DURABLE_WORKFLOW_SERVER_URL/api/cluster/info" \
 `/api/cluster/info` intentionally does not require the control-plane version
 header because it is the endpoint that advertises the supported versions.
 
-The same response also publishes the live topology and rollout-safety state for
-that node:
+### Cluster Topology Manifest
+
+`/api/cluster/info` also returns the node's `topology` manifest under the
+schema `durable-workflow.v2.role-topology`. That manifest is the supported way
+to discover whether the node is currently acting as `standalone_server`,
+`embedded`, or `split_control_execution`, which roles it owns, and what the
+server expects from `matching_role`, `authority_boundaries`,
+`failure_domains`, `scaling_boundaries`, and `migration_path`. The same
+response also publishes live rollout-safety state for that node.
+
+Read the manifest as follows:
 
-- `topology.current_process_class`, `topology.current_roles`, and
-  `topology.execution_mode` tell you which role shape the node is actually
-  serving.
+- `topology.current_process_class`, `topology.current_shape`,
+  `topology.current_roles`, and `topology.execution_mode` tell you which role
+  shape the node is actually serving. `current_shape` and `current_roles`
+  describe the responding node, not the full fleet.
 - `topology.matching_role.shape`, `topology.matching_role.wake_owner`, and
   `topology.matching_role.task_dispatch_mode` tell you whether broad ready-task
   discovery is happening in-worker or through a dedicated matching-role sweep.
@@ -11424,15 +11444,21 @@ that node:
   reason about.
 - `coordination_health` summarizes fleet-wide rollout and compatibility risk in
   one machine-readable block.
+- `execution_mode` distinguishes `local_queue_worker` embedded execution from
+  `remote_worker_protocol` worker-protocol execution.
+- `split_control_execution` is a supported product topology, not a second
+  server product or a different API.
 
 Example:
 
 <!-- docs-example id="server.cluster-info.topology.curl" -->
 ```bash
 curl -sS "$DURABLE_WORKFLOW_SERVER_URL/api/cluster/info" \
   -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \
-  -H "X-Namespace: default" | jq '{
+  -H "X-Namespace: default" \
+  | jq '{
     current_process_class: .topology.current_process_class,
+    current_shape: .topology.current_shape,
     current_roles: .topology.current_roles,
     execution_mode: .topology.execution_mode,
     matching_role: .topology.matching_role,
@@ -11443,6 +11469,9 @@ curl -sS "$DURABLE_WORKFLOW_SERVER_URL/api/cluster/info" \
   }'
 ```
 
+For the conceptual contract behind those fields, including the role vocabulary
+and migration path, see
+[Server Role Topology](/docs/2.0/polyglot/server-role-topology).
 ## Workflow Control Plane
 
 Workflow routes are operator/control-plane routes. They require an operator or
@@ -14302,6 +14331,186 @@ client = Client(
 
 Set the `namespace` argument to whichever tenant namespace the shared server has provisioned for your team, and use the credentials issued for that namespace. The server operator manages namespace creation — see the [server setup guide](/docs/2.0/polyglot/server) for details.
 
+<!-- Source: docs/polyglot/server-role-topology.md -->
+
+# Server Role Topology
+
+`GET /api/cluster/info` publishes the machine-readable role map for the node
+that answered the request. Use that `topology` manifest when you need to know
+which responsibilities the node owns, which durable write surfaces belong to
+each role, and how the same product contract scales from one process to a split
+control-plane and execution-plane deployment.
+
+The manifest uses the schema `durable-workflow.v2.role-topology`. It is a
+product contract, not an internal implementation detail. Operators, SDKs, CLI
+automation, and rollout tooling should read it instead of inferring duties from
+container names, hostnames, or process labels.
+
+## Why This Manifest Exists
+
+Durable Workflow keeps one durable engine across embedded mode, the standalone
+server distribution, and more explicit split-role deployments. The topology
+manifest makes that boundary explicit:
+
+- it names the legal topology shapes as product terms
+- it tells you which roles the current node owns
+- it publishes the durable write boundary for each role
+- it exposes the first failure signal and main scaling driver per role
+- it preserves one migration path instead of implying a second engine
+
+This is how you distinguish a supported topology change from a product fork.
+
+## Role Vocabulary
+
+The manifest vocabulary is fixed for v2:
+
+| Role | What it owns |
+| --- | --- |
+| `api_ingress` | HTTP termination, request authentication, namespace resolution, and handing requests to the right plane. |
+| `control_plane` | Durable workflow commands such as start, signal, update, cancel, terminate, reset, repair, and archive. |
+| `matching` | Ready-task discovery, claim arbitration, dispatch publication, and wake ownership. |
+| `history_projection` | Durable history recording, run summaries, and operator-facing projection surfaces. |
+| `scheduler` | Schedule evaluation and turning schedule fire state into workflow starts. |
+| `execution_plane` | Workflow-task replay, activity execution, task heartbeats, and task completion/failure outcomes. |
+
+The role list is intentionally logical rather than process-shaped. One process
+may host multiple roles, and one role may later move to its own process class
+without changing the contract.
+
+## Supported Deployment Shapes
+
+The server publishes the supported shapes in `topology.supported_shapes`:
+
+| Shape | Process classes | Typical use |
+| --- | --- | --- |
+| `embedded` | One `application_process` owns `control_plane`, `matching`, `history_projection`, `scheduler`, and `execution_plane`. | Laravel-app embedding with local queue workers. |
+| `standalone_server` | `server_http_node`, `scheduler_node`, and `worker_node`. | Published server image, self-hosted Compose, and the narrow small-cluster contract. |
+| `split_control_execution` | `ingress_node`, `control_plane_node`, `scheduler_node`, `matching_node`, and `execution_node`. | More explicit role isolation without introducing a second engine. |
+
+Two details matter in practice:
+
+- The published self-hosted server artifacts start in the
+  `standalone_server` shape, even though the manifest also advertises
+  `split_control_execution` as a supported product topology.
+- `current_shape` and `current_roles` describe the node you queried right now,
+  not the whole fleet. A standalone server API node reports
+  `api_ingress`, `control_plane`, `matching`, and `history_projection`; the
+  scheduler and workers are separate process classes in the same shape.
+
+For rollout planning, keep the topology page paired with
+[Self-Hosting Deployments](/docs/2.0/deployment) and
+[Rolling Upgrades](/docs/2.0/rolling-upgrades). Those pages tell you which
+shape is self-serve today; the manifest tells you which roles the node is
+actually owning.
+
+## Authority Boundaries
+
+`topology.authority_boundaries` tells you which durable write surfaces belong
+to each role. Treat it as the first guardrail before splitting a deployment:
+
+| Role | Durable write boundary |
+| --- | --- |
+| `control_plane` | `workflow_instances`, `workflow_runs.status`, `workflow_tasks.lifecycle` |
+| `execution_plane` | `workflow_tasks.outcomes`, `activity_attempts`, `worker_compatibility_heartbeats` |
+| `matching` | `workflow_tasks.leases`, `activity_tasks.leases` |
+| `history_projection` | `history_events`, `workflow_run_summaries`, `workflow_history_exports` |
+| `scheduler` | `workflow_schedules.fire_state`, `workflow_starts.scheduled` |
+| `api_ingress` | `worker_registrations` |
+
+If a process needs a durable write surface outside the roles it claims, that is
+topology drift and should be treated as a contract problem before you scale or
+split the fleet further.
+
+## Failure And Scaling Boundaries
+
+The same manifest also publishes the first expected failure signal and the main
+scaling driver for each role:
+
+| Role or failure | What operators should expect |
+| --- | --- |
+| `control_plane_down` | Operator commands fail fast; already-claimed work continues only until lease expiry. |
+| `execution_plane_down` | Ready tasks accumulate without loss; queue depth and schedule-to-start lag grow. |
+| `matching_down` | Claim rate falls while ready depth rises; current implementations fall back to direct ready-task discovery. |
+| `history_projection_down` | Durable writes continue, but projection reads may go stale and projection-lag health rises. |
+| `scheduler_down` | Scheduled workflows stop firing and the missed-schedule state becomes visible. |
+| `api_ingress_down` | External HTTP traffic stops at the edge even if embedded in-process calls still exist elsewhere. |
+
+| Role | Main scaling driver |
+| --- | --- |
+| `api_ingress` | `incoming_http_request_rate` |
+| `control_plane` | `operator_commands_and_run_lifecycle_transitions` |
+| `matching` | `ready_task_rate_and_poller_count` |
+| `history_projection` | `durable_event_rate` |
+| `scheduler` | `active_schedule_count` |
+| `execution_plane` | `workflow_and_activity_task_rate` |
+
+This is the contract behind the public operator guidance. When the deployment
+guide says the scheduler is singleton or when the rolling-upgrade guide says
+workers and API nodes roll independently, it is relying on these boundaries.
+
+## Migration Path
+
+The manifest publishes one ordered `migration_path` so a deployment can evolve
+without inventing a new engine:
+
+1. `audit_role_boundaries` so tooling can detect cross-role writes before
+   runtime shape changes.
+2. `expose_role_bindings` so hosts can swap adapters or run a role out of
+   process without patching the package.
+3. `introduce_dedicated_matching_shape` so matching can move out of the worker
+   loop without changing the claim contract.
+4. `split_history_projection` so history/projection work can move without
+   introducing a second writer.
+5. `split_scheduler` so schedule firing can sit behind explicit ownership while
+   single-replica deployments stay legal.
+6. `optional_execution_partitioning` so workers can partition by namespace,
+   connection, queue, and compatibility.
+
+Read that sequence literally. `split_control_execution` is a topology that
+keeps the same durable kernel and discovery surface; it is not a new control
+plane, a second protocol, or a hosted-only feature fork.
+
+## Reading The Topology Manifest
+
+Use `/api/cluster/info` to read the node's current role assignment:
+
+```bash
+curl -sS "$DURABLE_WORKFLOW_SERVER_URL/api/cluster/info" \
+  -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \
+  -H "X-Namespace: default" \
+  | jq '.topology | {schema, version, current_shape, current_roles, execution_mode, matching_role}'
+```
+
+Key fields to inspect:
+
+- `schema` and `version` tell you which topology manifest schema you are
+  parsing. Treat `topology.version` as the manifest version, not as the server
+  build version.
+- `current_shape` and `current_roles` tell you what the responding node owns
+  right now.
+- `execution_mode` distinguishes `local_queue_worker` embedded execution from
+  `remote_worker_protocol` standalone-server execution.
+- `matching_role` tells you whether the node still owns the in-worker wake path
+  or expects a dedicated repair/matching loop to do that work.
+- `shape_assignments`, `authority_boundaries`, `failure_domains`,
+  `scaling_boundaries`, and `migration_path` are the fields operators should
+  read before changing topology, rollout posture, or process ownership.
+
+## Related References
+
+- [Server](/docs/2.0/polyglot/server) for the general standalone-server guide
+  and the inline cluster-info example.
+- [Server API Reference](/docs/2.0/polyglot/server-api-reference) for the
+  discovery endpoint, route matrix, and required headers.
+- [Self-Hosting Deployments](/docs/2.0/deployment) for the supported
+  self-serve shapes and their operational boundaries.
+- [Rolling Upgrades](/docs/2.0/rolling-upgrades) for mixed-version rollout
+  behavior across API nodes, workers, and the scheduler.
+- [Task Matching and Dispatch](/docs/2.0/polyglot/task-matching-dispatch) for
+  the matching-role contract that `topology.matching_role` points at.
+- [Worker Compatibility Routing](/docs/2.0/polyglot/worker-compatibility-routing)
+  for build-id and compatibility-marker routing semantics across worker fleets.
+
 <!-- Source: docs/polyglot/cli-python-parity.md -->
 
 # CLI and Python Parity