[cross-repo from workflow#395] server + workflow + sdk-python: make replay verification a first-class platform contract (#18)

Author: durable-workflow-ops

README.md

@@ -203,6 +203,28 @@ infers the workflow type and input from that event; otherwise pass
 contains the commands the workflow would emit next, including determinism
 failures surfaced as workflow failure commands.
 
+For CI and operator replay gates, the package also installs offline
+verification commands:
+
+```bash
+durable-workflow-replay-verify tests/fixtures/golden_history \
+  --workflows my_app.workflows:all_workflows \
+  --output replay-report.json
+
+durable-workflow-replay-verify exported-history-bundles \
+  --simulate-bundles \
+  --output replay-simulation.json
+
+durable-workflow-history-bundle-verify exported-history-bundles/run-001.json \
+  --output integrity-report.json
+```
+
+`durable-workflow-replay-verify` emits the same verdict and
+`promotion_decision` vocabulary as the platform replay contract. Golden-history
+mode replays cross-runtime fixtures against registered workflow classes;
+`--simulate-bundles` integrity-checks every exported history bundle in a
+directory and reports missing bundle evidence as a blocking result.
+
 ## External payload storage
 
 Large payload offload is opt-in. `serializer.external_storage_envelope(...)`

pyproject.toml

@@ -56,6 +56,10 @@ Documentation = "https://durable-workflow.github.io/docs/2.0/polyglot/python"
 Repository = "https://github.com/durable-workflow/sdk-python"
 Issues = "https://github.com/durable-workflow/sdk-python/issues"
 
+[project.scripts]
+durable-workflow-replay-verify = "durable_workflow.replay_verify:main"
+durable-workflow-history-bundle-verify = "durable_workflow.history_bundle_verify:main"
+
 [tool.setuptools.packages.find]
 where = ["src"]
 

src/durable_workflow/__init__.py

@@ -138,6 +138,10 @@
 from .replay_verify import (
     CaseReport as ReplayCaseReport,
     GoldenHistoryReport,
+    SimulationReport,
+    aggregate_verdicts,
+    promotion_decision_for,
+    simulate_bundles,
     verify_golden_history,
     verify_replay,
 )
@@ -287,6 +291,10 @@
     "replay",
     "GoldenHistoryReport",
     "ReplayCaseReport",
+    "SimulationReport",
+    "aggregate_verdicts",
+    "promotion_decision_for",
+    "simulate_bundles",
     "verify_golden_history",
     "verify_replay",
     "HISTORY_BUNDLE_SCHEMA",

src/durable_workflow/replay_verify.py

@@ -661,6 +661,7 @@ def simulate_bundles(
                 VERDICT_DRIFTED: 0,
                 VERDICT_FAILED: 0,
             },
+            missing_bundles=[str(directory)],
             error=f"Bundle directory [{directory}] does not exist.",
         )
 
@@ -674,6 +675,15 @@ def simulate_bundles(
         VERDICT_FAILED: 0,
     }
 
+    if not paths:
+        return SimulationReport(
+            verdict=VERDICT_FAILED,
+            promotion_decision=PROMOTION_BLOCK_AND_INVESTIGATE,
+            summary=summary,
+            missing_bundles=[str(directory / "*.json")],
+            error=f"No history-export bundle JSON files were found in [{directory}].",
+        )
+
     bundles: list[BundleEntry] = []
     verdicts: list[str] = []
 
@@ -709,7 +719,7 @@ def simulate_bundles(
         summary["total"] += 1
         summary[verdict] += 1
 
-    overall = aggregate_verdicts(verdicts) if verdicts else VERDICT_FAILED
+    overall = aggregate_verdicts(verdicts)
 
     return SimulationReport(
         verdict=overall,

tests/test_replay_verify.py

@@ -428,6 +428,17 @@ def test_simulate_bundles_returns_failed_for_missing_directory(tmp_path: Path) -
 
     assert report.verdict == VERDICT_FAILED
     assert report.promotion_decision == PROMOTION_BLOCK_AND_INVESTIGATE
+    assert report.missing_bundles == [str(tmp_path / "no-such-dir")]
+    assert report.error is not None
+
+
+def test_simulate_bundles_returns_failed_when_directory_has_no_bundles(tmp_path: Path) -> None:
+    report = simulate_bundles(tmp_path)
+
+    assert report.verdict == VERDICT_FAILED
+    assert report.promotion_decision == PROMOTION_BLOCK_AND_INVESTIGATE
+    assert report.summary["total"] == 0
+    assert report.missing_bundles == [str(tmp_path / "*.json")]
     assert report.error is not None