Skip to content

CONFORMANCE.md

Latest commit

 

History

History
186 lines (159 loc) · 10.6 KB

CONFORMANCE.md

File metadata and controls

186 lines (159 loc) · 10.6 KB

Platform Conformance — Python SDK Claim

The durable_workflow Python SDK participates in the platform conformance suite specified in workflow/docs/architecture/platform-conformance-suite.md and mirrored by Workflow\V2\Support\PlatformConformanceSuite. This document is the per-repo claim: it lists the conformance targets the SDK claims, the fixtures it serves, and the release gate that blocks publication when conformance is broken.

Claimed targets

The Python SDK claims two targets from the suite's matrix:

  • official_sdk — first-party SDK distributed by the project. Implements worker_protocol (worker side), history_event_wire_formats (replay), and official_sdks (own row in the surface stability contract).
  • worker_protocol_implementation — worker plane and frozen history event replay.

Fixture and runtime scenario sources

Category Source path Status
control_plane_request_response tests/fixtures/control-plane/ stable, parity-shared with cli
signal_query_runtime_contract tests/test_signals.py, tests/test_queries.py, tests/test_worker.py and the public scenario manifest at https://durable-workflow.github.io/platform-conformance/signal-query-runtime-scenarios.json stable, parity-shared with PHP worker, CLI, and server routes
search_attribute_runtime_contract public scenario manifest at https://durable-workflow.github.io/platform-conformance/search-attribute-runtime-scenarios.json stable, parity-shared with PHP worker, CLI, Waterline, and server query behavior
namespace_runtime_contract public scenario manifest at https://durable-workflow.github.io/platform-conformance/namespace-runtime-scenarios.json stable, suite v12 runtime coverage for namespace isolation and SDK namespace selection
child_workflow_runtime_contract public scenario manifest at https://durable-workflow.github.io/platform-conformance/child-workflow-runtime-scenarios.json stable, parity-shared with PHP worker and server child-workflow runtime behavior
saga_runtime_contract public scenario manifest at https://durable-workflow.github.io/platform-conformance/saga-runtime-scenarios.json stable, parity-shared with PHP workflow compensation, cross-language activities, replay, CLI, and Waterline visibility
worker_versioning_runtime_contract public scenario manifest at https://durable-workflow.github.io/platform-conformance/worker-versioning-runtime-scenarios.json stable, parity-shared with PHP workers, CLI, Waterline, and server worker routing behavior
worker_task_lifecycle tests/fixtures/external-task-input/, tests/fixtures/external-task-result/ stable
history_replay_bundles tests/fixtures/golden_history/ and the public replay scenario manifest at https://durable-workflow.github.io/platform-conformance/replay-runtime-scenarios.json stable, parity-shared with workflow golden bundles and the full runtime replay scenario matrix

The fixtures in this repo are exercised today by:

  • tests/test_control_plane_parity_fixtures.py
  • tests/test_history_event_contract.py
  • tests/test_signals.py
  • tests/test_queries.py
  • tests/test_worker.py
  • tests/test_replay.py
  • tests/test_golden_history_replay.py
  • scripts/check-cli-parity.py
  • durable-workflow-python-conformance --manifest
  • the cli-parity job in .github/workflows/ci.yml

These are the per-repo gates that already enforce the contract; the public conformance harness, when it lands, will read the same fixtures from this repo's declared paths.

Published-artifact Python parity contract

The package ships a machine-readable contract in durable_workflow.python_conformance and exposes it through the durable-workflow-python-conformance console script. Host conformance runners use this contract to distinguish a Python worker smoke test from the full published-artifact property.

Host runners should collect their published-artifact observations into the host-evidence shape exposed by:

durable-workflow-python-conformance --host-evidence --pretty
durable-workflow-python-conformance --compose host-evidence.json --pretty > python-conformance-result.json
durable-workflow-python-conformance --evaluate python-conformance-result.json --pretty

The composer materializes one row for every required scenario and capability. Rows with no recorded evidence are emitted as not_covered, preserving a non-passing result with focused gate failures instead of letting smoke-only evidence look complete. Runner-native aliases such as scenarioEvidence, capabilityResults, officialCli, firstUserFlow, traces, and languageNeutralityAudit are accepted as input to the composer; they are normalized into the canonical result fields before evaluation. Scenario and capability IDs may use the canonical snake_case names or the runbook-style hyphenated names such as server-up, python-worker-connects, and result-returned. Nested runner tables such as capabilityTable.rows, resolved artifact/source fields, boolean passed cells, nested protocolTraces.controlPlane / protocolTraces.workerProtocol captures, and no-PHP audit check aliases are also normalized before evaluation. For CLI result-path evidence, host runners should use the actual published CLI surfaces that return terminal workflow output: workflow:start --wait, workflow:describe, or workflow:show-run --follow.

The result gate requires one result for every scenario below, all marked pass, before the Python SDK conformance property can pass:

  • published_artifact_install_only
  • official_cli_install_start_result_path
  • cold_first_user_setup
  • python_worker_registration
  • activity_backed_workflow_execution
  • workflow_result_surface
  • worker_restart_activity_and_signal_state
  • protocol_trace_capture
  • php_assumption_audit
  • capability_table_complete

A passing result must also record concrete artifact versions for server, cli, sdk-python, workflow, and waterline; run timestamps; protocol traces; a no-PHP-assumption audit; and the complete capability table. Any omitted scenario, placeholder artifact version, runner-blocked cell, unsupported public surface, or non-pass scenario without linked findings is nonconforming.

This SDK claim follows the currently published platform conformance contract and public scenario manifests. Draft categories are not release-blocking here until the published contract advertises them and their manifests resolve publicly.

Release gate

A release of durable_workflow (PyPI) must produce a passing harness result document before tag, with the conformance level at full or provisional (provisional categories enumerated in release notes).

Field Value
Required claimed targets official_sdk, worker_protocol_implementation
Required suite version PlatformConformanceSuite::VERSION (currently 12, mirrored at /platform-conformance-contract.json)
CI job platform-conformance (lands when the harness reference implementation publishes; until then cli-parity, test_history_event_contract.py, and durable-workflow-python-conformance --evaluate cover the same ground)
Block on nonconforming yes
Artifact attached to release harness result document, schema durable-workflow.v2.platform-conformance.result

A nonconforming result blocks the release. A failure in a provisional category emits a warning and does not block.

SDK neutrality posture

Python is the highest-value non-PHP first-party SDK and is treated as a priority posture under the platform-wide SDK neutrality contract (schema durable-workflow.v2.sdk-neutrality.contract, mirrored at /sdk-neutrality-contract.json on the docs site). The contract's purpose is to keep public Durable contracts implementable in any language without protocol redesign; this SDK exists in part to validate that the worker protocol, control plane, and replay fixtures behave the same way outside PHP.

Concretely, that means this SDK never persists Python-only state across a public boundary: no pickle, no Python-only exception class matching, no __qualname__ leaking into the wire format. Failure shapes use stable string codes; workflow, activity, child-workflow, and exception types are identified by registered string names; replay fixtures under tests/fixtures/golden_history/ are JSON conforming to the published history_event_payloads and replay_bundle JSON Schemas. Any new test fixture or public helper added to this SDK that would only round-trip through Python is a contract violation, even if no test in this repo notices.

Cross-references