feat(shadow): require deterministic risk decision for receipt admission

Co-Authored-By: Codex <noreply@openai.com>

Author: Pigbibi

README.md

@@ -44,15 +44,34 @@ policy-gate receipt、风险摘要、deployment bundle 或前一账本回执缺
 Alpaca，也不代表 P5 已启用或 P4/P6 已获许可。后续部署会为该纯控制步骤单独接入受限的
 工件读取、create-only 回执写入与状态发布。
 
-现已定义 P5 后置的 `qsl.tqqq_shadow_receipt_admission.v1`：它只能封装 controller 已返回的
-`RECEIPT_READY` 结果和已复核的虚拟账本回执。`CreateOnlyShadowReceiptStore` 是未来受限工件
-存储的最小接口：按 `cycle_id` 原子地 create-if-absent，已存在时读取后按 admission digest 对账；
-digest 不同只返回 `PARKED/receipt_conflict`，绝不覆盖。仓内 `InMemoryShadowReceiptStore` 仅用于
-确定性测试与本地回放，不连接文件系统、GCS、GitHub Actions、券商或任何凭据。
-
-未来每个 P5 周期必须先提供完整 forward observation、独立 policy-gate receipt、风险摘要和
-deployment bundle，且（如果存在）上一账本回执必须有效；任一缺失/无效仍由 controller 返回
-`PARKED`。只有 `RECEIPT_READY` 才可调用该 create-only port；本次没有添加 cron、环境变量或部署。
+P5 后置 admission 现为 `qsl.tqqq_shadow_receipt_admission.v2`。它除了 controller 已返回的
+`RECEIPT_READY` 结果和已复核的虚拟账本回执，还必须消费一个
+`qsl.tqqq_shadow_risk_gate_decision_envelope.v1`。该 envelope 包含 QSL
+`qsl.deterministic_risk_gate_decision.v1` 的完整、可重算摘要，以及与本 P5 cycle 的
+`cycle_id`、`computed_at` 和 `qsl.forward_observation_risk_control.v1` 三元组绑定。
+
+适配器不导入、不复制或重新执行 `QuantRuntimeSettings` 的风险内核；它只严格检查 QSL decision
+的闭合字段、canonical SHA-256、`ALLOW_NEW_RISK`、`CLOSED` breaker 建议、
+`manual_reset_required=true` 及上述 P5 绑定。写入的 v2 admission 只保留脱敏的 source
+risk-control、risk-gate policy id/version/SHA-256 和 decision SHA-256；不会保留账户、价格、
+notional、投影金额或订单材料。
+
+缺少 envelope、结构/摘要无效、cycle/时间/source risk-control 不匹配，或 decision 为
+`NEW_RISK_PROHIBITED` 时，`persist_shadow_cycle_outcome` 都在读取或调用存储前返回 `PARKED`；
+不会自动 reset breaker。`CreateOnlyShadowReceiptStore` 仍是未来受限工件存储的最小接口：按
+`cycle_id` 原子地 create-if-absent，已存在时读取后按 admission digest 对账；digest 不同只返回
+`PARKED/receipt_conflict`，绝不覆盖。仓内 `InMemoryShadowReceiptStore` 仅用于确定性测试与本地
+回放，不连接文件系统、GCS、GitHub Actions、券商或任何凭据。
+
+未来每个 P5 周期必须先提供完整 forward observation、独立 policy-gate receipt、风险摘要、
+deployment bundle 和通过上述 adapter 的 deterministic risk decision，且（如果存在）上一账本回执
+必须有效；任一缺失/无效仍由 controller 或 admission 返回 `PARKED`。只有同时满足
+`RECEIPT_READY` 与风险决定的 create-only port 才可写入；本次没有添加 cron、环境变量或部署。
+
+这仍不是账户级 shadow 启动：真正启用前，独立 gateway 必须从受限、已对账的快照运行 QSL risk
+kernel，生成 per-cycle envelope，并与 policy-gate 身份、工件读取和持久化 adapter 一起部署；AI、
+网页、GitHub Actions、策略代码都不能伪造输入或 reset breaker。此仓没有任何此类身份、账户、
+券商或网络能力。
 
 ```bash
 python -m alpaca_platform.shadow_ledger --input cycle.json --output receipt.json

src/alpaca_platform/__init__.py

@@ -23,6 +23,17 @@
     validate_shadow_receipt_admission,
     validate_shadow_receipt_persistence_result,
 )
+from .shadow_risk_gate_decision import (
+    DETERMINISTIC_RISK_GATE_DECISION_SCHEMA,
+    P5_RISK_GATE_DECISION_ENVELOPE_SCHEMA,
+    P5_RISK_GATE_DECISION_REFERENCE_SCHEMA,
+    ShadowRiskGateDecisionError,
+    ShadowRiskGateDecisionMismatchError,
+    ShadowRiskGateDecisionProhibitedError,
+    build_p5_risk_gate_decision_reference,
+    calculate_p5_risk_gate_decision_envelope_sha256,
+    validate_p5_risk_gate_decision_reference,
+)
 from .shadow_scheduler import (
     SCHEDULER_RESULT_SCHEMA,
     ShadowCycleOutcome,
@@ -33,7 +44,10 @@
 
 __all__ = [
     "ADMISSION_SCHEMA",
+    "DETERMINISTIC_RISK_GATE_DECISION_SCHEMA",
     "FORWARD_OBSERVATION_SCHEMA",
+    "P5_RISK_GATE_DECISION_ENVELOPE_SCHEMA",
+    "P5_RISK_GATE_DECISION_REFERENCE_SCHEMA",
     "PERSISTENCE_RESULT_SCHEMA",
     "POLICY_GATE_RECEIPT_SCHEMA",
     "SCHEDULER_RESULT_SCHEMA",
@@ -42,15 +56,21 @@
     "ShadowCycleOutcome",
     "ShadowLedgerError",
     "ShadowReceiptStoreError",
+    "ShadowRiskGateDecisionError",
+    "ShadowRiskGateDecisionMismatchError",
+    "ShadowRiskGateDecisionProhibitedError",
     "ShadowSchedulerError",
+    "build_p5_risk_gate_decision_reference",
     "build_shadow_ledger_receipt",
     "build_shadow_receipt_admission",
     "build_tqqq_shadow_cycle_input",
     "calculate_forward_observation_sha256",
+    "calculate_p5_risk_gate_decision_envelope_sha256",
     "calculate_policy_gate_receipt_sha256",
     "calculate_shadow_receipt_admission_sha256",
     "persist_shadow_cycle_outcome",
     "run_tqqq_shadow_cycle",
+    "validate_p5_risk_gate_decision_reference",
     "validate_shadow_cycle_input",
     "validate_shadow_ledger_receipt",
     "validate_shadow_receipt_admission",

src/alpaca_platform/shadow_receipt_store.py

@@ -1,10 +1,11 @@
 """Create-only, no-broker persistence seam for bounded P5 shadow receipts.
 
 This module runs only after ``shadow_scheduler``.  It wraps an already
-validated ``RECEIPT_READY`` result in a closed admission artifact and exposes a
-small create-only storage port.  The included in-memory implementation is for
-tests/local deterministic replay only: it has no filesystem, network,
-credential, market-data, broker, or scheduler dependency.
+validated ``RECEIPT_READY`` result in a closed admission artifact only after a
+separately produced deterministic risk decision passes its bounded adapter.
+It exposes a small create-only storage port.  The included in-memory
+implementation is for tests/local deterministic replay only: it has no
+filesystem, network, credential, market-data, broker, or scheduler dependency.
 """
 
 from __future__ import annotations
@@ -16,13 +17,20 @@
 from typing import Any, Protocol
 
 from .shadow_ledger import ShadowLedgerError, validate_shadow_ledger_receipt
+from .shadow_risk_gate_decision import (
+    ShadowRiskGateDecisionError,
+    ShadowRiskGateDecisionMismatchError,
+    ShadowRiskGateDecisionProhibitedError,
+    build_p5_risk_gate_decision_reference,
+    validate_p5_risk_gate_decision_reference,
+)
 from .shadow_scheduler import (
     ShadowCycleOutcome,
     ShadowSchedulerError,
     validate_shadow_scheduler_result,
 )
 
-ADMISSION_SCHEMA = "qsl.tqqq_shadow_receipt_admission.v1"
+ADMISSION_SCHEMA = "qsl.tqqq_shadow_receipt_admission.v2"
 PERSISTENCE_RESULT_SCHEMA = "qsl.tqqq_shadow_receipt_persistence_result.v1"
 
 _DIGEST = re.compile(r"^[0-9a-f]{64}$")
@@ -32,6 +40,7 @@
     "computed_at",
     "scheduler_result",
     "shadow_receipt",
+    "risk_gate_decision",
     "admission_sha256",
 }
 _PERSISTENCE_RESULT_FIELDS = {
@@ -51,6 +60,10 @@
     "prior_receipt_invalid",
     "cycle_input_invalid",
     "ledger_receipt_invalid",
+    "risk_gate_decision_missing",
+    "risk_gate_decision_invalid",
+    "risk_gate_decision_mismatch",
+    "risk_gate_decision_prohibited",
     "receipt_conflict",
 }
 
@@ -139,24 +152,40 @@ def validate_shadow_receipt_admission(value: Any) -> dict[str, Any]:
         _fail("shadow receipt admission computed_at must match controller result")
     if result["shadow_receipt_sha256"] != receipt["receipt_sha256"]:
         _fail("shadow receipt admission scheduler result must bind ledger receipt digest")
+    try:
+        risk_gate_decision = validate_p5_risk_gate_decision_reference(
+            value["risk_gate_decision"],
+            expected_source_risk_control=receipt["risk_control"],
+            expected_computed_at=result["computed_at"],
+        )
+    except ShadowRiskGateDecisionMismatchError as exc:
+        raise ShadowReceiptStoreError("shadow receipt admission risk-gate decision does not match this P5 receipt") from exc
+    except ShadowRiskGateDecisionError as exc:
+        raise ShadowReceiptStoreError("shadow receipt admission risk-gate decision is invalid") from exc
     normalized = {
         "schema": ADMISSION_SCHEMA,
         "cycle_id": result["cycle_id"],
         "computed_at": result["computed_at"],
         "scheduler_result": result,
         "shadow_receipt": receipt,
+        "risk_gate_decision": risk_gate_decision,
         "admission_sha256": _digest(value["admission_sha256"], "shadow receipt admission.admission_sha256"),
     }
     if normalized["admission_sha256"] != calculate_shadow_receipt_admission_sha256(normalized):
         _fail("shadow receipt admission.admission_sha256 mismatch")
     return normalized
 
 
-def build_shadow_receipt_admission(outcome: ShadowCycleOutcome) -> dict[str, Any]:
+def build_shadow_receipt_admission(
+    outcome: ShadowCycleOutcome,
+    *,
+    risk_gate_decision: Any,
+) -> dict[str, Any]:
     """Convert one controller ``RECEIPT_READY`` outcome into an admission.
 
-    This function cannot create a ledger receipt.  A parked result, a missing
-    receipt, or an inconsistent outcome is rejected before a store is called.
+    This function cannot create a ledger receipt or a risk decision.  A parked
+    result, a missing receipt, a prohibited decision, or an inconsistent
+    binding is rejected before a store is called.
     """
     try:
         result = validate_shadow_scheduler_result(outcome.result)
@@ -166,12 +195,23 @@ def build_shadow_receipt_admission(outcome: ShadowCycleOutcome) -> dict[str, Any
         _fail("only a RECEIPT_READY controller outcome can be admitted")
     if outcome.receipt is None:
         _fail("RECEIPT_READY controller outcome must include a ledger receipt")
+    try:
+        receipt = validate_shadow_ledger_receipt(outcome.receipt)
+    except ShadowLedgerError as exc:
+        raise ShadowReceiptStoreError("RECEIPT_READY controller outcome ledger receipt is invalid") from exc
+    risk_gate_reference = build_p5_risk_gate_decision_reference(
+        risk_gate_decision,
+        expected_cycle_id=result["cycle_id"],
+        expected_computed_at=result["computed_at"],
+        expected_source_risk_control=receipt["risk_control"],
+    )
     admission: dict[str, Any] = {
         "schema": ADMISSION_SCHEMA,
         "cycle_id": result["cycle_id"],
         "computed_at": result["computed_at"],
         "scheduler_result": result,
-        "shadow_receipt": outcome.receipt,
+        "shadow_receipt": receipt,
+        "risk_gate_decision": risk_gate_reference,
         "admission_sha256": "",
     }
     admission["admission_sha256"] = calculate_shadow_receipt_admission_sha256(admission)
@@ -269,11 +309,15 @@ def create_if_absent(self, admission: Mapping[str, Any]) -> bool:
 def persist_shadow_cycle_outcome(
     outcome: ShadowCycleOutcome,
     store: CreateOnlyShadowReceiptStore,
+    *,
+    risk_gate_decision: Any | None = None,
 ) -> dict[str, Any]:
     """Persist a ready P5 receipt once, or return a closed parked/reconciled result.
 
-    It never promotes P5, retries missing inputs, or writes a parked result. A
-    conflicting immutable cycle returns ``PARKED`` and remains untouched.
+    It never promotes P5, resets a breaker, retries missing inputs, or writes a
+    parked result.  A missing, prohibited, or mismatched deterministic risk
+    decision returns ``PARKED`` before the store is read or called.  A
+    conflicting immutable cycle also returns ``PARKED`` and remains untouched.
     """
     try:
         controller_result = validate_shadow_scheduler_result(outcome.result)
@@ -291,7 +335,44 @@ def persist_shadow_cycle_outcome(
             admission_sha256=None,
         )
 
-    admission = build_shadow_receipt_admission(outcome)
+    if risk_gate_decision is None:
+        return _persistence_result(
+            cycle_id=controller_result["cycle_id"],
+            computed_at=controller_result["computed_at"],
+            status="PARKED",
+            reason_code="risk_gate_decision_missing",
+            shadow_receipt_sha256=None,
+            admission_sha256=None,
+        )
+    try:
+        admission = build_shadow_receipt_admission(outcome, risk_gate_decision=risk_gate_decision)
+    except ShadowRiskGateDecisionProhibitedError:
+        return _persistence_result(
+            cycle_id=controller_result["cycle_id"],
+            computed_at=controller_result["computed_at"],
+            status="PARKED",
+            reason_code="risk_gate_decision_prohibited",
+            shadow_receipt_sha256=None,
+            admission_sha256=None,
+        )
+    except ShadowRiskGateDecisionMismatchError:
+        return _persistence_result(
+            cycle_id=controller_result["cycle_id"],
+            computed_at=controller_result["computed_at"],
+            status="PARKED",
+            reason_code="risk_gate_decision_mismatch",
+            shadow_receipt_sha256=None,
+            admission_sha256=None,
+        )
+    except ShadowRiskGateDecisionError:
+        return _persistence_result(
+            cycle_id=controller_result["cycle_id"],
+            computed_at=controller_result["computed_at"],
+            status="PARKED",
+            reason_code="risk_gate_decision_invalid",
+            shadow_receipt_sha256=None,
+            admission_sha256=None,
+        )
     cycle_id = admission["cycle_id"]
     existing = store.read(cycle_id)
     created = existing is None and store.create_if_absent(admission)