Skip to content

CONFORMANCE.md

Latest commit

 

History

History
145 lines (122 loc) · 7.71 KB

CONFORMANCE.md

File metadata and controls

145 lines (122 loc) · 7.71 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
namespace_runtime_contract public scenario manifest at https://durable-workflow.github.io/platform-conformance/namespace-runtime-scenarios.json stable, suite v8 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
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.

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.

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 8, 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