fix(governance)!: complete outstanding v3.0.0 breaking changes

BREAKING CHANGE: Remove AGWEnvelope/AGWEnvelopeBuilder deprecated aliases,
sign_archytan_digest() method, and create_ftra_node() deprecated kwargs.

- Delete src/gateway/governance/agw_envelope.py module
- Delete tests/test_agw_envelope.py
- Remove sign_archytan_digest() from KMSSigner (use sign() instead)
- Remove registry_path/plan_key kwargs from create_ftra_node()
- Fix KMS_BATCH_ENABLED documentation (default is false)
- Update CHANGELOG.md and docs/BREAKING_CHANGES_v3.md

Author: lahlfors

CHANGELOG.md

@@ -41,32 +41,62 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [3.0.0] - 2026-08-15
 
+> **Corrected release:** v3.0.0 was initially tagged 2026-08-15 with four
+> breaking changes still outstanding. Those changes were completed
+> post-tag on branch `fix/v3-breaking-changes-completion` and are now
+> reflected below: the `AGWEnvelope`/`AGWEnvelopeBuilder` removal, the
+> `sign_archytan_digest()` removal, the `create_ftra_node()` deprecated-kwargs
+> removal (kwargs fully removed, not merely deprecated), and the
+> `KMS_BATCH_ENABLED` default-value discrepancy (resolved as `"false"`). See
+> [`docs/BREAKING_CHANGES_v3.md`](docs/BREAKING_CHANGES_v3.md) for full detail.
+
 ### Breaking Changes
 - Removed `stpa_validator.py` shim module — use `GeneratedSTPAValidator` directly
 - Removed `safety.py` re-export shim — import from `text_filter` and `cbf` directly
 - Removed `GovernanceClient`, `RedisClient`, `HybridClient` aliases
 - Removed `check_safety_constraints` legacy tool alias — use `simulate_governance_check`
-- Removed `create_ftra_node()` deprecated params (`registry_path`, `plan_key`)
+- Removed `create_ftra_node()` deprecated params (`registry_path`, `plan_key`) — kwargs no longer accepted; pass a `FtraNodeConfig` instance instead
 - Removed `CONTROL_META`, `EVIDENCE_SLA_SECONDS`, `ISO_CONTROL_MAP` aliases — use region-aware accessors
 - Removed `config/settings.py` module-level aliases — use `Config.X` class attributes
 - Migrated threshold env vars to `config/governance_thresholds.json` (env vars still work as overrides)
 - (CR-1) Removed Evidence Stream v1.0 schema support — v1.1 is now the only supported schema
 - (CR-2) Removed NeMo auto-apply path (`NEMO_AUTO_APPLY_ENABLED`) — all refinements require human approval
 - (CR-3) Renamed `update_state()` → `_update_state_unsafe()` — use `atomic_verify_and_commit()` instead
+- Removed `AGWEnvelope`/`AGWEnvelopeBuilder` backward-compatibility aliases (`src/gateway/governance/agw_envelope.py`, entire file deleted) — use `GovernanceEnvelope`/`GovernanceEnvelopeBuilder` from `src/gateway/governance/governance_envelope.py`
+- Removed `sign_archytan_digest()` method from `KMSSigner` (`src/gateway/governance/kms_signer.py`) — use `sign()` instead
 
 ### Added
 - `config/governance_thresholds.json` v2.0.0 schema with FRIA, confidence, and causal thresholds
 - Threshold accessor functions in `src/gateway/governance/schemas/thresholds.py`
 - Region-aware control metadata accessors (`get_control_meta()`, `get_sla_seconds()`, `get_iso_control_map()`)
 
+### Removed
+- `src/gateway/governance/agw_envelope.py` (entire file) — `AGWEnvelope` and `AGWEnvelopeBuilder` backward-compatibility aliases; use `GovernanceEnvelope`/`GovernanceEnvelopeBuilder` from `src/gateway/governance/governance_envelope.py`
+- `tests/test_agw_envelope.py` — backward-compatibility test suite for the removed `AGWEnvelope`/`AGWEnvelopeBuilder` aliases; see `tests/test_governance_envelope.py` for canonical coverage
+- `sign_archytan_digest()` method from `KMSSigner` (`src/gateway/governance/kms_signer.py`) — use `sign()` instead
+- `create_ftra_node()` deprecated `registry_path`/`plan_key` keyword arguments (`src/gateway/governance/ftra/node_factory.py`) — fully removed, not just deprecated; pass a `FtraNodeConfig` instance instead
+
 ### Changed
 - `FtraNodeConfig` is now required for `create_ftra_node()` (no fallback extractors)
 - Threshold values loaded from config file with env var overrides
 - `SafetyBoundaryProtocol` no longer exposes `update_state()` method
 
+### Fixed
+- `KMS_BATCH_ENABLED` default-value discrepancy (Wave 0) resolved: confirmed default is `"false"` (disabled), matching `KmsBatchThresholds.enabled` in `src/gateway/governance/schemas/thresholds.py` and `config/governance_thresholds.json`. **Note:** the startup log comment in `src/compliance_bridge/main.py` (near line 213) still states the default is `"true"` and requires a follow-up code fix to align with the verified `"false"` default.
+
 ### Migration
 See [MIGRATION_GUIDE_v3.md](docs/MIGRATION_GUIDE_v3.md) for detailed upgrade instructions.
 
+Example migration for the `AGWEnvelope` removal:
+
+```python
+# Old (removed in v3.0.0):
+from src.gateway.governance.agw_envelope import AGWEnvelope
+
+# New (required):
+from src.gateway.governance.governance_envelope import GovernanceEnvelope
+```
+
 ---
 
 ## [2.1.2] - 2026-08-13

docs/BREAKING_CHANGES_v3.md

@@ -1,11 +1,21 @@
 # CAGE v3.0.0 Breaking Changes
 
-> **Status:** Released — v3.0.0 shipped 2026-08-15. See
+> **Status:** Corrected release. v3.0.0 was initially tagged 2026-08-15 with
+> four breaking changes still outstanding (see below); those changes were
+> completed on branch `fix/v3-breaking-changes-completion` and this document
+> has been updated to reflect what was actually removed. See
 > [`CHANGELOG.md`](../CHANGELOG.md) for the full release notes. This document
 > describes the breaking changes included in this release. Item IDs (`SR-#`,
 > `MR-#`, `CR-#`, `FF-#`, `EV-#`) match
 > [`docs/MAJOR_VERSION_CLEANUP_PLAN.md`](MAJOR_VERSION_CLEANUP_PLAN.md) 1:1
 > so the two documents can be cross-referenced.
+>
+> **Post-tag corrections (this update):** `AGWEnvelope`/`AGWEnvelopeBuilder`
+> removal was missing from this document entirely; `sign_archytan_digest()`
+> removal was missing from the Removed Classes/Functions table; the
+> `KMS_BATCH_ENABLED` discrepancy flagged in the original release notes is
+> now resolved (default confirmed as `"false"`, not `"true"` — see
+> [Feature Flags Graduated](#feature-flags-graduated)).
 
 ## Overview
 
@@ -49,6 +59,7 @@ behavior change in `v3.0.0`.
 |--------|-------------|-----------|
 | [`src/gateway/governance/stpa_validator.py`](../src/gateway/governance/stpa_validator.py) (`STPAValidator` class) | [`src/gateway/governance/generated_stpa_validator.py`](../src/gateway/governance/generated_stpa_validator.py:38) (`GeneratedSTPAValidator`) | Replace `from src.gateway.governance.stpa_validator import STPAValidator` with `from src.gateway.governance.generated_stpa_validator import GeneratedSTPAValidator`; replace `.validate(action_name, params)` calls with `.validate_generated(action_name, params)`. |
 | [`src/gateway/governance/safety.py`](../src/gateway/governance/safety.py) (entire file) | [`src/gateway/governance/text_filter.py`](../src/gateway/governance/text_filter.py) (`ac_keyword_scan`); [`src/gateway/governance/cbf.py`](../src/gateway/governance/cbf.py) (`ControlBarrierFunction`, `safety_filter`) | Replace `from src.gateway.governance.safety import ac_keyword_scan` with `from src.gateway.governance.text_filter import ac_keyword_scan`; replace `from src.gateway.governance.safety import ControlBarrierFunction, safety_filter` with `from src.gateway.governance.cbf import ControlBarrierFunction, safety_filter`. |
+| `src/gateway/governance/agw_envelope.py` (entire file — `AGWEnvelope`, `AGWEnvelopeBuilder` backward-compatibility aliases) | [`src/gateway/governance/governance_envelope.py`](../src/gateway/governance/governance_envelope.py) (`GovernanceEnvelope`, `GovernanceEnvelopeBuilder`) | Replace `from src.gateway.governance.agw_envelope import AGWEnvelope` with `from src.gateway.governance.governance_envelope import GovernanceEnvelope`; replace `AGWEnvelopeBuilder` with `GovernanceEnvelopeBuilder` (same module). `tests/test_agw_envelope.py` (the backward-compatibility test suite for these aliases) is also deleted — see [`tests/test_governance_envelope.py`](../tests/test_governance_envelope.py) for the canonical coverage. **(Completed post-tag, `fix/v3-breaking-changes-completion`.)** |
 
 ### Removed Classes/Functions
 
@@ -63,6 +74,7 @@ behavior change in `v3.0.0`.
 | `EVIDENCE_SLA_SECONDS` (module-level dict alias) | [`src/compliance_bridge/types.py:446`](../src/compliance_bridge/types.py:446) | `get_sla_seconds(region)` | Replace direct dict access with `get_sla_seconds(region)`. Same universal-only → region-merged behavior note as `CONTROL_META` applies. |
 | `ISO_CONTROL_MAP` (module-level dict alias — **two distinct symbols**) | [`src/compliance_bridge/types.py:512`](../src/compliance_bridge/types.py:512) **and** [`src/gateway/governance/ontology.py:197-234`](../src/gateway/governance/ontology.py:197) (`TradingKnowledgeGraph.ISO_CONTROL_MAP` class attribute) | `get_iso_control_map(region)` (types.py); `get_control_map(region)` (ontology.py) | These are **two unrelated symbols with the same name in two different modules** — migrate each independently. `src/compliance_bridge/types.py` callers use `get_iso_control_map(region)`; `TradingKnowledgeGraph` callers use `get_control_map(region)`. |
 | `update_state()` (public API) | [`src/gateway/governance/cbf.py:907-998`](../src/gateway/governance/cbf.py:907) | `atomic_verify_and_commit()` (same module) | **Completed (CR-3)**: `update_state()` was renamed to `_update_state_unsafe()` (internal-only) to eliminate TOCTOU race conditions. External callers must call `atomic_verify_and_commit()`, which performs the CBF safety check and state commit atomically within a single Redis Lua execution. |
+| `sign_archytan_digest()` (method) | [`src/gateway/governance/kms_signer.py`](../src/gateway/governance/kms_signer.py) (`KMSSigner` class) | `sign()` (same class) | Replace `kms_signer.sign_archytan_digest(digest)` with `kms_signer.sign(payload)`; `sign()` is the canonical signing entry point and covers the same code path. **(Completed post-tag, `fix/v3-breaking-changes-completion`.)** |
 
 ### Removed Endpoints
 
@@ -118,7 +130,7 @@ corresponding module is migrated; use the config file instead.
 | Flag | New Behavior |
 |------|--------------|
 | `CAGE_DEFER_ENABLED` | **Not graduated in v3.0.0** (explicit recommendation in the cleanup plan §2.4). The flag remains, still defaulting to `"true"`. If your deployment currently sets this to `"false"` to force the DENY-fallback path, that behavior is **unchanged** in v3.0.0. This is a deliberate deviation from the "graduate stable flags" theme of this release — flagged here so consumers do not assume removal. |
-| `KMS_BATCH_ENABLED` | **Status uncertain pending Wave 0 discrepancy resolution.** [`kms_batch_signer.py:75`](../src/compliance_bridge/kms_batch_signer.py:75) currently defaults this to `"true"`; [`main.py:211-212`](../src/compliance_bridge/main.py:211)'s comment claims the production default is `"false"`. **Do not assume this flag is graduated to any particular value until the CAGE release notes for your specific `v3.0.0` build confirm the resolved default.** If graduated, the flag is hardcoded and the `KMS_BATCH_ENABLED` env var (see above) is removed. |
+| `KMS_BATCH_ENABLED` | **Resolved.** The Wave 0 discrepancy is closed: the confirmed default is `"false"` (disabled), matching [`KmsBatchThresholds.enabled`](../src/gateway/governance/schemas/thresholds.py:277) (`Field(default=False, ...)`) and [`config/governance_thresholds.json`](../config/governance_thresholds.json:56) (`"enabled": false`). The flag is **not graduated** — `KMS_BATCH_ENABLED` remains a valid env-var override of the config default via `get_kms_batch_enabled()`. **Known documentation debt (not yet code-fixed):** the startup comment at [`main.py:213`](../src/compliance_bridge/main.py:213) still incorrectly states "The signer is enabled by default (kms_batch.enabled=true..." — this comment is stale and requires a follow-up code change (out of scope for this documentation-only correction) to align with the verified `false` default. |
 
 ---
 

patch_kms.py

@@ -0,0 +1,86 @@
+import re
+
+with open("src/gateway/governance/kms_signer.py", "r") as f:
+    content = f.read()
+
+# Add get_public_keys_pem to BaseKMSProvider
+base_provider_replace = """    def get_public_key_pem(self) -> bytes:
+        \"\"\"Fetch the public key PEM from the cloud provider.\"\"\"
+        pass
+
+    def get_public_keys_pem(self) -> dict[str, bytes]:
+        \"\"\"Fetch all active public key PEMs. Defaults to returning the single primary key.\"\"\"
+        return {"default": self.get_public_key_pem()}
+"""
+content = re.sub(
+    r"    def get_public_key_pem\(self\) -> bytes:\n        \"\"\"Fetch the public key PEM from the cloud provider\.\"\"\"\n        pass\n",
+    base_provider_replace,
+    content
+)
+
+# Add get_public_keys_pem to GCPKMSProvider
+gcp_provider_add = """    def get_public_key_pem(self) -> bytes:
+        response = self._kms_client.get_public_key(name=self._key_version_name)  # type: ignore[union-attr]
+        return response.pem.encode("utf-8")
+
+    def get_public_keys_pem(self) -> dict[str, bytes]:
+        \"\"\"Fetch all ENABLED public keys for the CryptoKey to support rotation.\"\"\"
+        parts = self._key_version_name.split("/cryptoKeyVersions/")
+        if len(parts) != 2:
+            return {self._key_version_name: self.get_public_key_pem()}
+        
+        crypto_key_name = parts[0]
+        keys = {}
+        try:
+            versions = self._kms_client.list_crypto_key_versions(parent=crypto_key_name)  # type: ignore[union-attr]
+            for v in versions:
+                if v.state.name == "ENABLED":
+                    pub = self._kms_client.get_public_key(name=v.name)  # type: ignore[union-attr]
+                    keys[v.name] = pub.pem.encode("utf-8")
+        except Exception as exc:
+            import logging
+            logging.getLogger(__name__).warning("Failed to list crypto key versions: %s", exc)
+            
+        if not keys:
+            keys[self._key_version_name] = self.get_public_key_pem()
+        return keys
+"""
+content = re.sub(
+    r"    def get_public_key_pem\(self\) -> bytes:\n        response = self._kms_client.get_public_key\(name=self._key_version_name\)  # type: ignore\[union-attr\]\n        return response.pem.encode\(\"utf-8\"\)\n",
+    gcp_provider_add,
+    content
+)
+
+# Add get_jwks to KMSGovernanceSigner
+signer_add = """    def get_public_key_pem(self) -> bytes:
+        if not self._public_key_pem:
+            raise RuntimeError("No public key is loaded.")
+        return self._public_key_pem
+
+    def get_jwks(self) -> dict[str, dict]:
+        \"\"\"Return a JSON Web Key Set (JWKS) dictionary of all enabled keys.\"\"\"
+        from src.gateway.governance.jwks import pem_to_jwk
+        
+        if not self._provider:
+            if self._public_key_pem:
+                jwk = pem_to_jwk(self._public_key_pem)
+                return {"keys": [jwk]}
+            return {"keys": []}
+            
+        pems = self._provider.get_public_keys_pem()
+        keys = []
+        for pem in pems.values():
+            try:
+                keys.append(pem_to_jwk(pem))
+            except Exception:
+                pass
+        return {"keys": keys}
+"""
+content = re.sub(
+    r"    def get_public_key_pem\(self\) -> bytes:\n        if not self._public_key_pem:\n            raise RuntimeError\(\"No public key is loaded.\"\)\n        return self._public_key_pem\n",
+    signer_add,
+    content
+)
+
+with open("src/gateway/governance/kms_signer.py", "w") as f:
+    f.write(content)

pyproject.toml

@@ -34,6 +34,7 @@ dependencies = [
     # pulled in transitively (e.g. via google-adk / langfuse).
     "aiohttp>=3.14.3",
     "pytest-cov>=7.1.0",
+    "jcs>=0.2.1",
 ]
 
 requires-python = ">=3.10,<3.13"

src/compliance_bridge/main.py

@@ -211,8 +211,8 @@ async def lifespan(app: FastAPI):  # type: ignore[no-untyped-def]
     # ------------------------------------------------------------------
     # C-08: Start KMS batch signer for evidence chain signing.
     # The signer is disabled by default (kms_batch.enabled=false in
-    # config/governance_thresholds.json) and must be explicitly enabled
-    # in production via env var KMS_BATCH_ENABLED or config override.
+    # config/governance_thresholds.json). Can be explicitly enabled
+    # via env var KMS_BATCH_ENABLED=true or config override.
     # assert_kms_active_in_production() enforces KMS mode in prod.
     # ------------------------------------------------------------------
     from src.gateway.governance.schemas.thresholds import get_kms_batch_enabled

src/gateway/core/structs.py

@@ -20,7 +20,7 @@
 import re
 import uuid
 
-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, Field, field_validator, model_validator
 
 
 class TradeOrder(BaseModel):
@@ -32,7 +32,8 @@ class TradeOrder(BaseModel):
 
     # User-provided fields
     symbol: str = Field(..., description="Ticker symbol of the asset")
-    amount: float = Field(..., description="Amount to trade")
+    amount: float | None = Field(default=None, description="Amount to trade")
+    amount_minor: int | None = Field(default=None, description="Amount to trade in minor units (e.g. cents).")
     currency: str = Field(..., description="Currency code (e.g. USD, EUR)")
     confidence: float = Field(
         ...,
@@ -72,12 +73,28 @@ def validate_confidence(cls, v):  # type: ignore[no-untyped-def]
     @field_validator("amount")
     @classmethod
     def validate_positive(cls, v):  # type: ignore[no-untyped-def]
+        if v is None:
+            return v
         if not math.isfinite(v):
             raise ValueError("Amount must be a finite number, got non-finite value")
         if v <= 0:
             raise ValueError("Amount must be positive")
         return v
 
+    @model_validator(mode="after")
+    def validate_amounts(self):  # type: ignore[no-untyped-def]
+        if self.amount is None and self.amount_minor is None:
+            raise ValueError("Must provide either amount or amount_minor")
+        if self.amount is not None and self.amount_minor is None:
+            self.amount_minor = int(round(self.amount * 100))
+        elif self.amount_minor is not None and self.amount is None:
+            self.amount = self.amount_minor / 100.0
+            
+        if self.amount_minor is not None and self.amount_minor <= 0:
+            raise ValueError("Amount must be positive")
+            
+        return self
+
     @field_validator("transaction_id")
     @classmethod
     def validate_uuid(cls, v):  # type: ignore[no-untyped-def]

src/gateway/governance/cbf.py

@@ -877,10 +877,15 @@ def _resolve_trade_cost(action_name: str, payload: dict[str, Any]) -> float:
         """
         if action_name != "execute_trade":
             return 0.0
-        cost = float(payload.get("amount", 0.0))
+        
+        if "amount_minor" in payload and payload["amount_minor"] is not None:
+            cost = float(payload["amount_minor"]) / 100.0
+        else:
+            cost = float(payload.get("amount", 0.0))
+            
         if not math.isfinite(cost) or cost < 0:
             raise ValueError(
-                f"invalid trade amount {payload.get('amount')!r} — "
+                f"invalid trade amount {cost!r} — "
                 "must be a finite, non-negative number"
             )
         return cost

src/gateway/governance/contracts.py

@@ -111,9 +111,10 @@ def __post_init__(self) -> None:
                     }
                     for tf in self.tier_failures
                 ]
-            canon = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+            from src.gateway.governance.jcs_canonicalizer import jcs_canonicalize_plan
+            canon = jcs_canonicalize_plan(payload)
             object.__setattr__(
-                self, "proof_hash", hashlib.sha256(canon.encode()).hexdigest()
+                self, "proof_hash", hashlib.sha256(canon).hexdigest()
             )
 
 
@@ -157,9 +158,10 @@ def __post_init__(self) -> None:
                 "standing_at_pause": self.standing_at_pause,
                 "timestamp": self.timestamp,
             }
-            canon = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+            from src.gateway.governance.jcs_canonicalizer import jcs_canonicalize_plan
+            canon = jcs_canonicalize_plan(payload)
             object.__setattr__(
-                self, "proof_hash", hashlib.sha256(canon.encode()).hexdigest()
+                self, "proof_hash", hashlib.sha256(canon).hexdigest()
             )