Merge pull request #407 from QuantStrategyLab/codex/execution-receipt-adapter

feat: publish bounded LongBridge execution receipts

Author: Pigbibi

.github/workflows/execution-report-heartbeat.yml

@@ -113,7 +113,7 @@ jobs:
 
       - name: Publish read-only runtime execution evidence
         if: matrix.target.label == 'PAPER'
-        uses: QuantStrategyLab/QuantRuntimeSettings/actions/publish-runtime-execution-evidence@f28bee6a4e28e2aead5fb37bd3213c12dd419e29
+        uses: QuantStrategyLab/QuantRuntimeSettings/actions/publish-runtime-execution-evidence@813ba38c4adb759e143503c8e6b70715090391cc
         with:
           source-id: runtime-reports-longbridge
           report-platform: longbridge

application/execution_receipt_adapter.py

@@ -0,0 +1,50 @@
+"""Bounded execution-receipt facts derived from LongBridge cycle results."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from quant_platform_kit.common.execution_receipts import (
+    attach_runtime_execution_receipt,
+    resolve_execution_receipt_fact,
+)
+
+
+def attach_cycle_execution_receipt(
+    report: dict[str, Any],
+    cycle_result: object,
+) -> dict[str, Any]:
+    """Attach only facts that the LongBridge cycle result explicitly carries.
+
+    ``action_done`` confirms a local order-submission step, not a broker fill.
+    A populated ``pending_orders`` list wins over it and produces a
+    reconciliation requirement instead.
+    """
+
+    pending_orders = tuple(getattr(cycle_result, "pending_orders", ()) or ())
+    outcome, confirmation = resolve_execution_receipt_fact(
+        dry_run=bool(report.get("dry_run")),
+        submission_attempted=bool(getattr(cycle_result, "action_done", False)),
+        reconciliation_required=bool(pending_orders),
+    )
+    return attach_runtime_execution_receipt(
+        report,
+        outcome=outcome,
+        broker_confirmation=confirmation,
+    )
+
+
+def attach_terminal_fallback_execution_receipt(report: dict[str, Any]) -> dict[str, Any]:
+    """Attach a conservative fact when the cycle exits before a result exists."""
+
+    failed = str(report.get("status") or "").strip().lower() == "error"
+    outcome, confirmation = resolve_execution_receipt_fact(
+        dry_run=bool(report.get("dry_run")),
+        submission_attempted=failed,
+        failed=failed,
+    )
+    return attach_runtime_execution_receipt(
+        report,
+        outcome=outcome,
+        broker_confirmation=confirmation,
+    )

main.py

@@ -15,6 +15,10 @@
 import google.auth
 import requests
 from application.monitor_dispatcher import dispatch_due_monitors, load_monitor_targets
+from application.execution_receipt_adapter import (
+    attach_cycle_execution_receipt,
+    attach_terminal_fallback_execution_receipt,
+)
 from application.runtime_broker_adapters import build_runtime_broker_adapters
 from application.runtime_composer import build_runtime_composer
 from application.rebalance_service import run_strategy as run_rebalance_cycle
@@ -811,6 +815,13 @@ def run_strategy(*, force_run: bool = False, validation_only: bool = False, vali
                 message="Strategy signal snapshot",
                 **signal_snapshot,
             )
+        try:
+            attach_cycle_execution_receipt(report, cycle_result)
+        except ValueError:
+            # Test/legacy runtime reports without a release attestation remain
+            # evidence-missing; receipt metadata must not change a completed
+            # strategy cycle into a failure.
+            pass
         finalize_runtime_report(
             report,
             status="ok",
@@ -876,6 +887,13 @@ def run_strategy(*, force_run: bool = False, validation_only: bool = False, vali
         )
         return False
     finally:
+        if "execution_receipt" not in report:
+            try:
+                attach_terminal_fallback_execution_receipt(report)
+            except ValueError:
+                # Legacy targets remain evidence-missing; receipt metadata
+                # cannot affect strategy execution or error handling.
+                pass
         try:
             report_path = reporting_adapters.persist_execution_report(report)
             print(f"execution_report {report_path}", flush=True)

pyproject.toml

@@ -18,7 +18,7 @@ dependencies = [
     "google-cloud-storage",
     "google-auth",
     "longport==3.0.23",
-    "quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@ee8d996392f96e8bdf40988bd68ae30bf5911d2d",
+    "quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@b567acd52a6afa6caca3e35648d4347a1ce13ab1",
     "us-equity-strategies @ git+https://github.com/QuantStrategyLab/UsEquityStrategies.git@4584de176ca27955270471284663a13a2ce7f828",
     "hk-equity-strategies @ git+https://github.com/QuantStrategyLab/HkEquityStrategies.git@c526f2ed869c59f37a494d5fd3a64be299855ec8",
 ]
@@ -61,5 +61,5 @@ include = [
 
 [tool.uv]
 override-dependencies = [
-  "quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@ee8d996392f96e8bdf40988bd68ae30bf5911d2d",
+  "quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@b567acd52a6afa6caca3e35648d4347a1ce13ab1",
 ]

qsl.toml

@@ -5,7 +5,7 @@ upgrade_ring = "ring_d"
 allow_legacy = false
 
 [qsl.requires]
-quant_platform_kit = "ee8d996392f96e8bdf40988bd68ae30bf5911d2d"
+quant_platform_kit = "b567acd52a6afa6caca3e35648d4347a1ce13ab1"
 us_equity_strategies = "4584de176ca27955270471284663a13a2ce7f828"
 hk_equity_strategies = "c526f2ed869c59f37a494d5fd3a64be299855ec8"
 

tests/test_execution_receipt_adapter.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+import unittest
+
+from application.execution_receipt_adapter import attach_cycle_execution_receipt
+
+
+REVISION = "a" * 40
+
+
+def _report() -> dict[str, object]:
+    return {
+        "platform": "longbridge",
+        "strategy_profile": "sg_us_equity_rotation",
+        "dry_run": False,
+        "runtime_target": {"execution_mode": "paper"},
+        "runtime_release_receipt": {
+            "attestation_state": "self_attested",
+            "strategy_release": {"strategy_revision": REVISION},
+        },
+    }
+
+
+class ExecutionReceiptAdapterTest(unittest.TestCase):
+    def test_submission_does_not_claim_broker_acknowledgement(self) -> None:
+        report = _report()
+
+        attach_cycle_execution_receipt(report, SimpleNamespace(action_done=True, pending_orders=()))
+
+        self.assertEqual(report["execution_receipt"]["outcome"], "submitted")
+        self.assertEqual(report["execution_receipt"]["broker_confirmation"], "not_observed")
+
+    def test_pending_orders_require_reconciliation(self) -> None:
+        report = _report()
+
+        attach_cycle_execution_receipt(
+            report,
+            SimpleNamespace(action_done=True, pending_orders=({"symbol": "QQQ"},)),
+        )
+
+        self.assertEqual(report["execution_receipt"]["outcome"], "reconciliation_required")
+
+    def test_dry_run_never_claims_submission(self) -> None:
+        report = _report()
+        report["dry_run"] = True
+
+        attach_cycle_execution_receipt(report, SimpleNamespace(action_done=True, pending_orders=()))
+
+        self.assertEqual(report["execution_receipt"]["outcome"], "no_action")