ledgix-python 0.1.0__tar.gz → 0.1.2__tar.gz

{ledgix_python-0.1.0 → ledgix_python-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ledgix-python
-Version: 0.1.0
+Version: 0.1.2
 Summary: Agent-agnostic compliance shim for SOX 404 policy enforcement via the ALCV Vault
 Project-URL: Homepage, https://github.com/ledgix-dev/python-sdk
 Project-URL: Documentation, https://docs.ledgix.dev
@@ -75,6 +75,8 @@ Set environment variables (prefix: `LEDGIX_`):
 | `LEDGIX_VAULT_API_KEY` | `""` | API key for Vault auth |
 | `LEDGIX_VAULT_TIMEOUT` | `30.0` | Request timeout (seconds) |
 | `LEDGIX_VERIFY_JWT` | `true` | Verify A-JWT signatures |
+| `LEDGIX_JWT_ISSUER` | `alcv-vault` | Expected A-JWT issuer |
+| `LEDGIX_JWT_AUDIENCE` | `ledgix-sdk` | Expected A-JWT audience |
 | `LEDGIX_AGENT_ID` | `default-agent` | Agent identifier |
 
 Or pass a `VaultConfig` directly:
@@ -175,4 +177,4 @@ python demo.py
 
 ## License
 
-MIT
+MIT

{ledgix_python-0.1.0 → ledgix_python-0.1.2}/README.md

@@ -35,6 +35,8 @@ Set environment variables (prefix: `LEDGIX_`):
 | `LEDGIX_VAULT_API_KEY` | `""` | API key for Vault auth |
 | `LEDGIX_VAULT_TIMEOUT` | `30.0` | Request timeout (seconds) |
 | `LEDGIX_VERIFY_JWT` | `true` | Verify A-JWT signatures |
+| `LEDGIX_JWT_ISSUER` | `alcv-vault` | Expected A-JWT issuer |
+| `LEDGIX_JWT_AUDIENCE` | `ledgix-sdk` | Expected A-JWT audience |
 | `LEDGIX_AGENT_ID` | `default-agent` | Agent identifier |
 
 Or pass a `VaultConfig` directly:
@@ -135,4 +137,4 @@ python demo.py
 
 ## License
 
-MIT
+MIT

{ledgix_python-0.1.0 → ledgix_python-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ledgix-python"
-version = "0.1.0"
+version = "0.1.2"
 description = "Agent-agnostic compliance shim for SOX 404 policy enforcement via the ALCV Vault"
 readme = "README.md"
 license = { text = "MIT" }

{ledgix_python-0.1.0 → ledgix_python-0.1.2}/src/ledgix_python/__init__.py

@@ -18,6 +18,7 @@ from .config import VaultConfig
 from .enforce import VaultContext, vault_enforce
 from .exceptions import (
     ClearanceDeniedError,
+    ManualReviewTimeoutError,
     PolicyRegistrationError,
     LedgixError,
     TokenVerificationError,
@@ -30,7 +31,7 @@ from .models import (
     PolicyRegistrationResponse,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 
 __all__ = [
     # Core
@@ -47,6 +48,7 @@ __all__ = [
     # Exceptions
     "LedgixError",
     "ClearanceDeniedError",
+    "ManualReviewTimeoutError",
     "VaultConnectionError",
     "TokenVerificationError",
     "PolicyRegistrationError",

{ledgix_python-0.1.0 → ledgix_python-0.1.2}/src/ledgix_python/client.py

@@ -4,14 +4,20 @@
 from __future__ import annotations
 
 import json
+import random
+import time
+from collections.abc import Awaitable, Callable
 from typing import Any
 
 import httpx
 import jwt
 
+_RETRYABLE_STATUS_CODES: frozenset[int] = frozenset({429, 500, 502, 503, 504})
+
 from .config import VaultConfig
 from .exceptions import (
     ClearanceDeniedError,
+    ManualReviewTimeoutError,
     PolicyRegistrationError,
     TokenVerificationError,
     VaultConnectionError,
@@ -72,6 +78,66 @@ class LedgixClient:
             )
         return self._async_client
 
+    # ------------------------------------------------------------------
+    # Retry helpers
+    # ------------------------------------------------------------------
+
+    def _backoff_delay(self, attempt: int) -> float:
+        """Exponential backoff with full jitter, capped at 30 seconds."""
+        delay = min(30.0, self.config.retry_base_delay * (2 ** attempt))
+        return random.uniform(0.0, delay)
+
+    def _sync_retry(self, fn: Callable[[], httpx.Response]) -> httpx.Response:
+        """Execute an HTTP callable with retry and exponential backoff.
+
+        Retries on ``httpx.TransportError`` (network errors, timeouts) and on
+        retryable HTTP status codes (429, 5xx). Raises ``VaultConnectionError``
+        after all attempts are exhausted.
+        """
+        last_exc: httpx.TransportError | None = None
+        response: httpx.Response | None = None
+        for attempt in range(self.config.max_retries + 1):
+            try:
+                response = fn()
+            except httpx.TransportError as exc:
+                last_exc = exc
+                if attempt < self.config.max_retries:
+                    time.sleep(self._backoff_delay(attempt))
+                    continue
+                raise VaultConnectionError(str(exc)) from exc
+            if response.status_code in _RETRYABLE_STATUS_CODES and attempt < self.config.max_retries:
+                time.sleep(self._backoff_delay(attempt))
+                continue
+            return response
+        if last_exc is not None:
+            raise VaultConnectionError(str(last_exc)) from last_exc
+        assert response is not None
+        return response
+
+    async def _async_retry(self, fn: Callable[[], Awaitable[httpx.Response]]) -> httpx.Response:
+        """Async variant of ``_sync_retry``."""
+        import asyncio
+
+        last_exc: httpx.TransportError | None = None
+        response: httpx.Response | None = None
+        for attempt in range(self.config.max_retries + 1):
+            try:
+                response = await fn()
+            except httpx.TransportError as exc:
+                last_exc = exc
+                if attempt < self.config.max_retries:
+                    await asyncio.sleep(self._backoff_delay(attempt))
+                    continue
+                raise VaultConnectionError(str(exc)) from exc
+            if response.status_code in _RETRYABLE_STATUS_CODES and attempt < self.config.max_retries:
+                await asyncio.sleep(self._backoff_delay(attempt))
+                continue
+            return response
+        if last_exc is not None:
+            raise VaultConnectionError(str(last_exc)) from last_exc
+        assert response is not None
+        return response
+
     # ------------------------------------------------------------------
     # Clearance — sync
     # ------------------------------------------------------------------
@@ -84,19 +150,20 @@ class LedgixClient:
             VaultConnectionError: If the Vault is unreachable.
         """
         try:
-            response = self._get_sync_client().post(
-                "/request-clearance",
-                content=request.model_dump_json(),
+            response = self._sync_retry(
+                lambda: self._get_sync_client().post(
+                    "/request-clearance",
+                    content=request.model_dump_json(),
+                )
             )
             response.raise_for_status()
-        except httpx.ConnectError as exc:
-            raise VaultConnectionError(str(exc)) from exc
         except httpx.HTTPStatusError as exc:
             raise VaultConnectionError(
                 f"Vault returned HTTP {exc.response.status_code}: {exc.response.text}"
             ) from exc
 
         clearance = ClearanceResponse.model_validate(response.json())
+        clearance = self._resolve_pending_clearance(clearance)
 
         if not clearance.approved:
             raise ClearanceDeniedError(
@@ -121,19 +188,20 @@ class LedgixClient:
             VaultConnectionError: If the Vault is unreachable.
         """
         try:
-            response = await self._get_async_client().post(
-                "/request-clearance",
-                content=request.model_dump_json(),
+            response = await self._async_retry(
+                lambda: self._get_async_client().post(
+                    "/request-clearance",
+                    content=request.model_dump_json(),
+                )
             )
             response.raise_for_status()
-        except httpx.ConnectError as exc:
-            raise VaultConnectionError(str(exc)) from exc
         except httpx.HTTPStatusError as exc:
             raise VaultConnectionError(
                 f"Vault returned HTTP {exc.response.status_code}: {exc.response.text}"
             ) from exc
 
         clearance = ClearanceResponse.model_validate(response.json())
+        clearance = await self._aresolve_pending_clearance(clearance)
 
         if not clearance.approved:
             raise ClearanceDeniedError(
@@ -153,13 +221,13 @@ class LedgixClient:
     def register_policy(self, policy: PolicyRegistration) -> PolicyRegistrationResponse:
         """Register a policy with the Vault (sync)."""
         try:
-            response = self._get_sync_client().post(
-                "/register-policy",
-                content=policy.model_dump_json(),
+            response = self._sync_retry(
+                lambda: self._get_sync_client().post(
+                    "/register-policy",
+                    content=policy.model_dump_json(),
+                )
             )
             response.raise_for_status()
-        except httpx.ConnectError as exc:
-            raise VaultConnectionError(str(exc)) from exc
         except httpx.HTTPStatusError as exc:
             raise PolicyRegistrationError(
                 f"Vault returned HTTP {exc.response.status_code}: {exc.response.text}"
@@ -170,13 +238,13 @@ class LedgixClient:
     async def aregister_policy(self, policy: PolicyRegistration) -> PolicyRegistrationResponse:
         """Register a policy with the Vault (async)."""
         try:
-            response = await self._get_async_client().post(
-                "/register-policy",
-                content=policy.model_dump_json(),
+            response = await self._async_retry(
+                lambda: self._get_async_client().post(
+                    "/register-policy",
+                    content=policy.model_dump_json(),
+                )
             )
             response.raise_for_status()
-        except httpx.ConnectError as exc:
-            raise VaultConnectionError(str(exc)) from exc
         except httpx.HTTPStatusError as exc:
             raise PolicyRegistrationError(
                 f"Vault returned HTTP {exc.response.status_code}: {exc.response.text}"
@@ -188,13 +256,43 @@ class LedgixClient:
     # JWKS + A-JWT verification
     # ------------------------------------------------------------------
 
+    def _resolve_pending_clearance(self, clearance: ClearanceResponse) -> ClearanceResponse:
+        if clearance.status not in {"processing", "pending_review"}:
+            return clearance
+
+        deadline = time.monotonic() + self.config.review_timeout
+        while time.monotonic() < deadline:
+            time.sleep(self.config.review_poll_interval)
+            response = self._get_sync_client().get(f"/clearance-status/{clearance.request_id}")
+            response.raise_for_status()
+            clearance = ClearanceResponse.model_validate(response.json())
+            if clearance.status not in {"processing", "pending_review"}:
+                return clearance
+        raise ManualReviewTimeoutError(clearance.request_id)
+
+    async def _aresolve_pending_clearance(self, clearance: ClearanceResponse) -> ClearanceResponse:
+        if clearance.status not in {"processing", "pending_review"}:
+            return clearance
+
+        import asyncio
+
+        deadline = time.monotonic() + self.config.review_timeout
+        while time.monotonic() < deadline:
+            await asyncio.sleep(self.config.review_poll_interval)
+            response = await self._get_async_client().get(f"/clearance-status/{clearance.request_id}")
+            response.raise_for_status()
+            clearance = ClearanceResponse.model_validate(response.json())
+            if clearance.status not in {"processing", "pending_review"}:
+                return clearance
+        raise ManualReviewTimeoutError(clearance.request_id)
+
     def fetch_jwks(self) -> dict[str, Any]:
         """Fetch the Vault's JWKS (JSON Web Key Set) for token verification (sync)."""
         try:
-            response = self._get_sync_client().get("/.well-known/jwks.json")
+            response = self._sync_retry(
+                lambda: self._get_sync_client().get("/.well-known/jwks.json")
+            )
             response.raise_for_status()
-        except httpx.ConnectError as exc:
-            raise VaultConnectionError(str(exc)) from exc
         except httpx.HTTPStatusError as exc:
             raise VaultConnectionError(
                 f"Failed to fetch JWKS: HTTP {exc.response.status_code}"
@@ -206,10 +304,10 @@ class LedgixClient:
     async def afetch_jwks(self) -> dict[str, Any]:
         """Fetch the Vault's JWKS for token verification (async)."""
         try:
-            response = await self._get_async_client().get("/.well-known/jwks.json")
+            response = await self._async_retry(
+                lambda: self._get_async_client().get("/.well-known/jwks.json")
+            )
             response.raise_for_status()
-        except httpx.ConnectError as exc:
-            raise VaultConnectionError(str(exc)) from exc
         except httpx.HTTPStatusError as exc:
             raise VaultConnectionError(
                 f"Failed to fetch JWKS: HTTP {exc.response.status_code}"
@@ -227,37 +325,31 @@ class LedgixClient:
             TokenVerificationError: If the token is invalid, expired, or
                 the JWKS cannot be fetched.
         """
-        return self._verify_token_internal(token, sync=True)
+        if self._jwks_cache is None:
+            self.fetch_jwks()
+        return self._decode_token(token)
 
     async def averify_token(self, token: str) -> dict[str, Any]:
-        """Verify an A-JWT using the Vault's public key (async)."""
-        return self._verify_token_internal(token, sync=False)
-
-    def _verify_token_internal(self, token: str, sync: bool = True) -> dict[str, Any]:
-        """Shared verification logic.
+        """Verify an A-JWT using the Vault's public key (async).
 
-        Note: For async callers this is still synchronous internally
-        because PyJWT is sync. The async variant pre-fetches JWKS
-        asynchronously before calling this.
+        Raises:
+            TokenVerificationError: If the token is invalid, expired, or
+                the JWKS cannot be fetched.
         """
         if self._jwks_cache is None:
-            if sync:
-                self.fetch_jwks()
-            else:
-                # In async context, caller must have pre-fetched JWKS.
-                # Fall back to sync fetch if cache is empty.
-                self.fetch_jwks()
+            await self.afetch_jwks()
+        return self._decode_token(token)
 
+    def _decode_token(self, token: str) -> dict[str, Any]:
+        """Verify an A-JWT against the cached JWKS. JWKS must already be populated."""
         if not self._jwks_cache:
             raise TokenVerificationError("No JWKS available from Vault")
 
         try:
-            # Extract the first key from the JWKS
             jwks = self._jwks_cache
             if "keys" not in jwks or not jwks["keys"]:
                 raise TokenVerificationError("JWKS contains no keys")
 
-            # Build a PyJWT key from the JWK
             key_data = jwks["keys"][0]
             public_key = jwt.algorithms.OKPAlgorithm.from_jwk(json.dumps(key_data))
 
@@ -265,10 +357,16 @@ class LedgixClient:
                 token,
                 public_key,
                 algorithms=["EdDSA"],
-                options={"verify_exp": True},
+                audience=self.config.jwt_audience,
+                issuer=self.config.jwt_issuer,
+                options={"verify_exp": True, "require": ["exp", "iss", "aud", "sub"]},
             )
+            if decoded.get("sub") != "clearance":
+                raise TokenVerificationError("Invalid A-JWT: unexpected subject")
             return decoded
 
+        except TokenVerificationError:
+            raise
         except jwt.ExpiredSignatureError as exc:
             raise TokenVerificationError("A-JWT has expired") from exc
         except jwt.InvalidTokenError as exc:

{ledgix_python-0.1.0 → ledgix_python-0.1.2}/src/ledgix_python/config.py

@@ -32,8 +32,26 @@ class VaultConfig(BaseSettings):
     verify_jwt: bool = True
     """Whether to verify A-JWTs returned by the Vault using its JWKS endpoint."""
 
+    jwt_issuer: str = "alcv-vault"
+    """Expected issuer for Vault A-JWTs."""
+
+    jwt_audience: str = "ledgix-sdk"
+    """Expected audience for Vault A-JWTs."""
+
     agent_id: str = "default-agent"
     """Identifier for the agent using this SDK instance."""
 
     session_id: str = ""
     """Optional session identifier for grouping related clearance requests."""
+
+    review_poll_interval: float = 2.0
+    """Polling interval in seconds while waiting for manual review."""
+
+    review_timeout: float = 300.0
+    """Maximum wait time in seconds for a pending manual review decision."""
+
+    max_retries: int = 3
+    """Number of retry attempts for transient failures (connection errors, 5xx responses)."""
+
+    retry_base_delay: float = 0.5
+    """Base delay in seconds for exponential backoff between retries (full jitter applied)."""

{ledgix_python-0.1.0 → ledgix_python-0.1.2}/src/ledgix_python/enforce.py

@@ -148,17 +148,23 @@ def _extract_tool_args(
     args: tuple[Any, ...],
     kwargs: dict[str, Any],
 ) -> dict[str, Any]:
-    """Best-effort extraction of function arguments as a dict for the clearance request."""
+    """Best-effort extraction of function arguments as a dict for the clearance request.
+
+    Skips ``self``, private parameters (prefixed with ``_``), ``*args``, and
+    ``**kwargs`` captures so only named, user-visible parameters are included.
+    """
     try:
         sig = inspect.signature(func)
         bound = sig.bind_partial(*args, **kwargs)
         bound.apply_defaults()
-        # Filter out internal kwargs
-        return {
-            k: v
-            for k, v in bound.arguments.items()
-            if not k.startswith("_") and k != "self"
-        }
-    except Exception:
-        # Fallback: just return kwargs
+        result: dict[str, Any] = {}
+        for name, value in bound.arguments.items():
+            if name.startswith("_") or name == "self":
+                continue
+            param = sig.parameters[name]
+            if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+                continue
+            result[name] = value
+        return result
+    except (TypeError, ValueError):
         return {k: v for k, v in kwargs.items() if not k.startswith("_")}

{ledgix_python-0.1.0 → ledgix_python-0.1.2}/src/ledgix_python/exceptions.py

@@ -23,6 +23,15 @@ class ClearanceDeniedError(LedgixError):
         super().__init__(f"Clearance denied: {reason}")
 
 
+class ManualReviewTimeoutError(LedgixError):
+    """Raised when a pending manual review decision does not resolve before timeout."""
+
+    def __init__(self, request_id: str | None = None) -> None:
+        self.request_id = request_id
+        suffix = f" ({request_id})" if request_id else ""
+        super().__init__(f"Manual review timed out{suffix}")
+
+
 class VaultConnectionError(LedgixError):
     """Raised when the SDK cannot reach the Vault server."""
 

{ledgix_python-0.1.0 → ledgix_python-0.1.2}/src/ledgix_python/models.py

@@ -27,10 +27,19 @@ class ClearanceRequest(BaseModel):
 class ClearanceResponse(BaseModel):
     """Response from the Vault's ``/request-clearance`` endpoint."""
 
+    status: str = Field(default="denied", description="Decision state: processing, approved, denied, or pending_review")
     approved: bool = Field(..., description="Whether the tool call was approved")
+    requires_manual_review: bool = Field(default=False, description="Whether the request is pending human review")
     token: str | None = Field(default=None, description="Signed A-JWT if approved, None if denied")
     reason: str = Field(default="", description="Human-readable explanation of the decision")
     request_id: str = Field(default="", description="Vault-assigned unique ID for this request")
+    confidence: float = Field(default=0.0, ge=0.0, le=1.0, description="Judge confidence score")
+    minimum_confidence_score: float = Field(
+        default=0.0,
+        ge=0.0,
+        le=1.0,
+        description="Client-configured minimum confidence score for auto approval",
+    )
 
 
 class PolicyRegistration(BaseModel):

{ledgix_python-0.1.0 → ledgix_python-0.1.2}/tests/conftest.py

@@ -36,6 +36,8 @@ def sample_jwt(ed25519_private_key: Ed25519PrivateKey) -> str:
     """Create a valid A-JWT for testing."""
     payload = {
         "sub": "clearance",
+        "iss": "alcv-vault",
+        "aud": "ledgix-sdk",
         "tool": "stripe_refund",
         "amount": 45.0,
         "iat": datetime.now(timezone.utc),
@@ -50,6 +52,8 @@ def expired_jwt(ed25519_private_key: Ed25519PrivateKey) -> str:
     """Create an expired A-JWT for testing."""
     payload = {
         "sub": "clearance",
+        "iss": "alcv-vault",
+        "aud": "ledgix-sdk",
         "tool": "stripe_refund",
         "iat": datetime.now(timezone.utc) - timedelta(hours=1),
         "exp": datetime.now(timezone.utc) - timedelta(minutes=5),
@@ -80,8 +84,11 @@ def vault_config() -> VaultConfig:
         vault_api_key="test-api-key",
         vault_timeout=5.0,
         verify_jwt=False,
+        jwt_issuer="alcv-vault",
+        jwt_audience="ledgix-sdk",
         agent_id="test-agent",
         session_id="test-session",
+        max_retries=0,
     )
 
 
@@ -92,8 +99,26 @@ def vault_config_with_jwt() -> VaultConfig:
         vault_api_key="test-api-key",
         vault_timeout=5.0,
         verify_jwt=True,
+        jwt_issuer="alcv-vault",
+        jwt_audience="ledgix-sdk",
         agent_id="test-agent",
         session_id="test-session",
+        max_retries=0,
+    )
+
+
+@pytest.fixture
+def vault_config_retry() -> VaultConfig:
+    """Config with retries enabled and zero backoff delay for fast retry tests."""
+    return VaultConfig(
+        vault_url="https://vault.test",
+        vault_api_key="test-api-key",
+        vault_timeout=5.0,
+        verify_jwt=False,
+        agent_id="test-agent",
+        session_id="test-session",
+        max_retries=2,
+        retry_base_delay=0.0,
     )
 
 
@@ -119,6 +144,7 @@ def client_with_jwt(vault_config_with_jwt: VaultConfig) -> LedgixClient:
 @pytest.fixture
 def approved_response(sample_jwt: str) -> dict:
     return {
+        "status": "approved",
         "approved": True,
         "token": sample_jwt,
         "reason": "Policy check passed",
@@ -129,6 +155,7 @@ def approved_response(sample_jwt: str) -> dict:
 @pytest.fixture
 def denied_response() -> dict:
     return {
+        "status": "denied",
         "approved": False,
         "token": None,
         "reason": "Amount exceeds $100 limit",

{ledgix_python-0.1.0 → ledgix_python-0.1.2}/tests/test_client.py

@@ -109,6 +109,30 @@ class TestRequestClearance:
         assert body["tool_args"]["amount"] == 99
         assert body["agent_id"] == "my-agent"
 
+    @respx.mock
+    def test_processing_polls_until_approved(self, client: LedgixClient, approved_response: dict):
+        processing_response = {
+            "status": "processing",
+            "approved": False,
+            "token": None,
+            "reason": "Queued",
+            "request_id": "req-processing-001",
+            "confidence": 0.0,
+            "minimum_confidence_score": 0.8,
+        }
+        respx.post("https://vault.test/request-clearance").mock(
+            return_value=Response(202, json=processing_response)
+        )
+        respx.get("https://vault.test/clearance-status/req-processing-001").mock(
+            return_value=Response(200, json={**approved_response, "request_id": "req-processing-001"})
+        )
+
+        request = ClearanceRequest(tool_name="stripe_refund", tool_args={"amount": 45})
+        result = client.request_clearance(request)
+
+        assert result.approved is True
+        assert result.request_id == "req-processing-001"
+
 
 # ──────────────────────────────────────────────────────────────────────
 # Clearance — async
@@ -290,6 +314,100 @@ class TestTokenVerification:
 # ──────────────────────────────────────────────────────────────────────
 
 
+# ──────────────────────────────────────────────────────────────────────
+# Retry behaviour
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestRetry:
+    """Tests for automatic retry with exponential backoff."""
+
+    @respx.mock
+    def test_retries_on_connection_error_then_succeeds(
+        self, vault_config_retry: VaultConfig, approved_response: dict
+    ):
+        client = LedgixClient(config=vault_config_retry)
+        route = respx.post("https://vault.test/request-clearance").mock(
+            side_effect=[
+                httpx.ConnectError("Connection refused"),
+                httpx.ConnectError("Connection refused"),
+                Response(200, json=approved_response),
+            ]
+        )
+
+        request = ClearanceRequest(tool_name="stripe_refund", tool_args={"amount": 45})
+        result = client.request_clearance(request)
+
+        assert result.approved is True
+        assert route.call_count == 3
+        client.close()
+
+    @respx.mock
+    def test_retries_on_5xx_then_succeeds(
+        self, vault_config_retry: VaultConfig, approved_response: dict
+    ):
+        client = LedgixClient(config=vault_config_retry)
+        respx.post("https://vault.test/request-clearance").mock(
+            side_effect=[
+                Response(503, text="Service Unavailable"),
+                Response(503, text="Service Unavailable"),
+                Response(200, json=approved_response),
+            ]
+        )
+
+        request = ClearanceRequest(tool_name="stripe_refund", tool_args={"amount": 45})
+        result = client.request_clearance(request)
+
+        assert result.approved is True
+        client.close()
+
+    @respx.mock
+    def test_raises_after_exhausting_retries(self, vault_config_retry: VaultConfig):
+        client = LedgixClient(config=vault_config_retry)
+        respx.post("https://vault.test/request-clearance").mock(
+            side_effect=httpx.ConnectError("Connection refused")
+        )
+
+        request = ClearanceRequest(tool_name="stripe_refund", tool_args={"amount": 45})
+        with pytest.raises(VaultConnectionError):
+            client.request_clearance(request)
+        client.close()
+
+    @respx.mock
+    def test_does_not_retry_on_4xx(self, vault_config_retry: VaultConfig):
+        client = LedgixClient(config=vault_config_retry)
+        route = respx.post("https://vault.test/request-clearance").mock(
+            return_value=Response(400, text="Bad Request")
+        )
+
+        request = ClearanceRequest(tool_name="stripe_refund", tool_args={"amount": 45})
+        with pytest.raises(VaultConnectionError):
+            client.request_clearance(request)
+
+        # 400 is not retryable — should only be called once
+        assert route.call_count == 1
+        client.close()
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_async_retries_on_connection_error(
+        self, vault_config_retry: VaultConfig, approved_response: dict
+    ):
+        client = LedgixClient(config=vault_config_retry)
+        respx.post("https://vault.test/request-clearance").mock(
+            side_effect=[
+                httpx.ConnectError("Connection refused"),
+                Response(200, json=approved_response),
+            ]
+        )
+
+        request = ClearanceRequest(tool_name="stripe_refund", tool_args={"amount": 45})
+        result = await client.arequest_clearance(request)
+
+        assert result.approved is True
+        await client.aclose()
+
+
 class TestClientLifecycle:
     """Tests for context manager and close behavior."""