Native: serve client_compatibility in cluster info with native-qualified ranges #1005

Gap

Published PHP 2.11.8 serves client_compatibility in /api/cluster/info (app/Support/ClientCompatibility.php, schema durable-workflow.v2.client-compatibility v2):

• authority: "protocol_manifests", with fail_closed: true;
• required_protocols;
• per-client supported_versions and requires.

Native 3.0.x leaves the block out and names it in native_unqualified ("Native publishes no client compatibility matrix yet", rust/src/runtime/cluster_info.rs:135). The CLI agent found the gap. General asked for it in 3.1.0 (lobby 7636).

Who reads it

Only the published CLI: src/Support/CompatibilityDiagnostics.php, used by doctor, server:info and the startup warning. The SDKs don't read it. The CLI:

• skips every check when the block is absent, which is native today, so a CLI outside the window gets no warning;
• warns unless authority === "protocol_manifests";
• warns when its version is outside clients.cli.supported_versions;
• checks the server's auth composition, external task input contract or external task result contract whenever the block requires them, through required_protocols.* or clients.cli.requires.

Constraint: cite only what native serves

PHP's required_protocols and requires cite contracts native doesn't publish:

• skew_refusal_matrix_contract;
• worker_protocol.external_execution_surface_contract, external_executor_config_contract, invocable_carrier_contract, external_task_input_contract and external_task_result_contract.

These are all false or absent in native's capabilities / native_unqualified. Copying PHP's block would make the CLI demand contracts native can't show. So native's block must cite only what native serves:

• control_plane: version "2", header, request_contract;
• worker_protocol: version "1.20", header;
• auth_composition: native's auth_composition_contract schema and version.

Proposed native block

Same schema and version (durable-workflow.v2.client-compatibility, 2), with authority: "protocol_manifests", top_level_version_role: "informational" and fail_closed: true.

• required_protocols: only the three above, each built from the same values native serves elsewhere in cluster info, so it can't drift from them.
• clients.cli: supported_versions: ">=2.0.0,<3.0.0" (the Rust CLI ships as a 2.x minor, per General on cli#72), requiring auth_composition.version, control_plane.version and control_plane.request_contract.
• clients.sdk-php, sdk-python, sdk-rust: supported_versions from installed qualification against native. The candidate ranges are below, for General to confirm. requires is limited to the served protocols above plus worker_protocol.version.

Contract fixture

• tests/Fixtures/ServerParity/cluster-capabilities.json: remove client_compatibility from native's native_unqualified and present overrides, and pin native's exact block as a native expectation. PHP keeps its published block unchanged.
• The cluster-capabilities probe: record the block's value as well as its presence.
• The contract: compare native's block exactly, refuse a native block that cites an unserved protocol, and refuse an unknown implementation.
• Counterfactuals: 3.0.5's absent block fails; a PHP-copied block fails on its unserved protocols; and an out-of-range CLI version produces the CLI warning.

Decisions for General

1. SDK ranges: confirm, or change, the three ranges above. In particular, does a Rust floor of 4.10.3 stand while 4.11.1's lifecycle gate is open?
2. supported_sdk_versions: PHP's top-level member uses the same source (ClientCompatibility::supportedSdkVersions()), and native also lists it in native_unqualified. Should it ship in the same change, with the same ranges?

🤖 Generated with Claude Code