Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion docs/BREAKING_CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -1278,8 +1278,17 @@ Agent working-state checkpoints now flow exclusively through the gateway (`/gove
|---|---|---|---|---|
| **DA-01** | Actuation receipt seam & domain settlement ([`actuation.py`](../src/gateway/governance/seams/actuation.py), [`trade_executor.py`](../src/cage_finance/tools/trade_executor.py), [`broker_actuator.py`](../src/cage_finance/actuators/broker_actuator.py), [`cage_finance/tools/tool_provider.py`](../src/cage_finance/tools/tool_provider.py), [`cage_healthcare/tools/tool_provider.py`](../src/cage_healthcare/tools/tool_provider.py)) | [`ActuationReceipt.outcome`](../src/gateway/governance/seams/actuation.py) changes from `ActuationOutcome \| None = None` to required keyword-only `outcome: ActuationOutcome = field(kw_only=True)`, and `__post_init__()` raises `TypeError` for any non-`ActuationOutcome` value. [`trade_executor.py`](../src/cage_finance/tools/trade_executor.py) tracks wire dispatch structurally (`DispatchPhase`, `PreWireRejectionError`, `IndeterminateExecutionError`) instead of matching exception strings, restricts deterministic pre-execution rejections to HTTP `400`/`401`/`403` (classifying HTTP `422` and all post-dispatch transport/5xx/parse errors as `UNKNOWN`), and [`execute_trade_action()`](../src/cage_finance/tools/tool_provider.py) raises [`ActuationIndeterminateError`](../src/cage_finance/tools/tool_provider.py) (subclass of `SymbolicGovernorViolation`) on `UNKNOWN` while flipping `executed = True` before awaiting `dispatch_actuation()` so mid-flight cancellation cannot release reservations. [`administer_dose_action()`](../src/cage_healthcare/tools/tool_provider.py) returns `{"status": "INDETERMINATE", ...}` without signing a contradictory `BLOCKED` refusal receipt on `UNKNOWN`. Full `UNKNOWN` fiscal reclamation, surfacing, and resubmission safety are tracked in `POAM-2026-232`. | Previously, omitting `outcome` on `ActuationReceipt(accepted=False, ...)` silently derived `ActuationOutcome.REJECTED`, releasing CBF cash debits and `FiscalLimitGuard` headroom after an order may already have reached the venue, while defaulting to `UNKNOWN` would silently lock a full day's fiscal budget on pre-wire omissions. Making `outcome` a required keyword-only field converts every omitting construction site into an immediate `TypeError`. | Any caller, adapter, or test constructing `ActuationReceipt(...)` without keyword `outcome=ActuationOutcome.<ACCEPTED\|REJECTED\|UNKNOWN>` (or passing `outcome` positionally or as `None`) raises `TypeError`. Callers matching `administer_dose_action()` indeterminate outcomes on `status == "BLOCKED"` now receive `status == "INDETERMINATE"`. |

## Unreleased — Infrastructure Outage vs. Policy Refusal Taxonomy Split (`POAM-2026-233`)

Dependency unavailability (`OPA` circuit-breaker open, latency-budget bankruptcy, timeout, transport error, HTTP non-`2xx`, or malformed/undefined reply) now fails closed as [`ViolationKind.INFRASTRUCTURE`](../src/gateway/governance/contracts.py) / [`InfrastructureOutcome.INFRASTRUCTURE_BLOCK`](../src/gateway/governance/classification_engine.py) / [`GovernanceInfrastructureError`](../src/gateway/governance/governor/errors.py), hash-chaining an unsigned `GOVERNANCE_INFRASTRUCTURE_BLOCK` diagnostic event and returning typed HTTP `503` without fabricating a KMS-signed `GOVERNANCE_REFUSAL` policy receipt.

| Item | Area | Clean Break Description | Architectural Rationale | Failure Mode on Stale Caller |
|---|---|---|---|---|
| **FA-1** | OPA client, violation taxonomy, classifier, evidence stream, and `/validate-action` outage contract ([`policy.py`](../src/gateway/core/policy.py), [`contracts.py`](../src/gateway/governance/contracts.py), [`opa.py`](../src/gateway/governance/governor/stages/opa.py), [`pipeline.py`](../src/gateway/governance/governor/pipeline.py), [`classification_engine.py`](../src/gateway/governance/classification_engine.py), [`errors.py`](../src/gateway/governance/governor/errors.py), [`verdicts.py`](../src/gateway/governance/governor/verdicts.py), [`governor.py`](../src/gateway/governance/governor/governor.py), [`metrics.py`](../src/gateway/governance/governor/metrics.py), [`governance_middleware.py`](../src/gateway/server/governance_middleware.py), [`proof/model.py`](../proof/model.py)) | [`OPAClient.evaluate_policy()`](../src/gateway/core/policy.py) and [`PolicyClient.evaluate_policy()`](../src/gateway/governance/contracts.py) raise [`PolicyEngineUnavailableError`](../src/gateway/governance/contracts.py) (rather than returning `"DENY"`) across circuit-breaker open, latency-budget bankruptcy, transport/timeout errors, HTTP non-`2xx`, and malformed or undefined Rego replies. [`OpaStage`](../src/gateway/governance/governor/stages/opa.py) emits `OPA_UNAVAILABLE` with [`ViolationKind.INFRASTRUCTURE`](../src/gateway/governance/contracts.py). [`ClassificationEngine.classify()`](../src/gateway/governance/classification_engine.py) ranks `HARD > INFRASTRUCTURE > RELIANCE_INELIGIBLE > ...` and returns [`InfrastructureOutcome.INFRASTRUCTURE_BLOCK`](../src/gateway/governance/classification_engine.py) when `INFRASTRUCTURE` is present without `HARD`. [`handle_infrastructure_block()`](../src/gateway/governance/governor/verdicts.py) chains `GOVERNANCE_INFRASTRUCTURE_BLOCK`, increments `cage_governance_infrastructure_blocks_total{dependency,code}` (leaving `cage_governance_refusals_total`, `mark_request_refused()`, and auto-quarantine untouched), and raises [`GovernanceInfrastructureError`](../src/gateway/governance/governor/errors.py) (`receipt=None`) without constructing `RefusalReceipt` or calling the KMS signer. `POST /governance/validate-action` returns HTTP `503` (`{"error": "policy_engine_unavailable", "dependency": "opa", "failure_code": "OPA_UNAVAILABLE", "retry_after_seconds": 5}`) with `Retry-After` and no `proof_hash` or `refusal_receipt`. | Remediates Cause 1 and Consumers 1–3, 7–8, 10, and 19 of `POAM-2026-233`: previously, every OPA outage returned `"DENY"`, fabricating KMS-signed `GOVERNANCE_REFUSAL` receipts in the 7-year WORM archive, inflating `cage_governance_refusals_total` / refusal-ratio metrics, and causing `cage-client` / the financial advisor to classify a transient `503`-class dependency blip as an immutable `403` `GOVERNANCE_DENIED` policy refusal (`HARD_PAUSE`). Fail-closed blocking (`Phase2Mode.SKIP`, immediate pipeline stop, `ReservationScope` rollback, no seal) is preserved identically. | Direct callers or unit tests asserting `await OPAClient.evaluate_policy(...) == "DENY"` on circuit-breaker, timeout, HTTP non-`2xx`, or malformed/undefined responses now observe `PolicyEngineUnavailableError`. Callers of `SymbolicGovernor.validate_action()` / `govern()` or `POST /governance/validate-action` during an OPA outage observe `GovernanceInfrastructureError` (`receipt=None`) and HTTP `503` (`policy_engine_unavailable`) rather than `GovernanceError(receipt=...)` and HTTP `403`. |

---

**Last updated:** November 16, 2026
**Last updated:** November 17, 2026



Loading
Loading