dominus-sdk-python 9.0.11__tar.gz → 9.0.13__tar.gz

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 9.0.11
+Version: 9.0.13
 Summary: Python SDK for the Dominus gateway-first platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License-Expression: LicenseRef-Proprietary
@@ -38,8 +38,8 @@ Async Python SDK for the Dominus gateway-first service plane.
 ## Agent Guide
 
 Start with `docs/agent-guide/INDEX.md`. The current snapshot is
-`docs/agent-guide/2026-09-14-1300-sdk-python/00-reading-order.md`; the latest
-cleanup audit is `docs/janitor/2026-09-14-1300-sdk-python-cleanup-audit.md`.
+`docs/agent-guide/2026-09-19-1300-sdk-python/00-reading-order.md`; the latest
+cleanup audit is `docs/janitor/2026-09-19-1300-sdk-python-cleanup-audit.md`.
 
 ## What This Repo Ships
 
@@ -48,7 +48,7 @@ cleanup audit is `docs/janitor/2026-09-14-1300-sdk-python-cleanup-audit.md`.
 - Gateway-scoped client mode for MCP and other user-JWT sessions
 - Transport compatibility for wrapped `{success,data}` responses and unwrapped Warden/control-plane success objects
 - Local helpers for JWT verification, trace propagation, retries, and console capture
-- Current package version: `9.0.11`
+- Current package version: `9.0.13`
 
 ## Install
 

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.13}/README.md

@@ -5,8 +5,8 @@ Async Python SDK for the Dominus gateway-first service plane.
 ## Agent Guide
 
 Start with `docs/agent-guide/INDEX.md`. The current snapshot is
-`docs/agent-guide/2026-09-14-1300-sdk-python/00-reading-order.md`; the latest
-cleanup audit is `docs/janitor/2026-09-14-1300-sdk-python-cleanup-audit.md`.
+`docs/agent-guide/2026-09-19-1300-sdk-python/00-reading-order.md`; the latest
+cleanup audit is `docs/janitor/2026-09-19-1300-sdk-python-cleanup-audit.md`.
 
 ## What This Repo Ships
 
@@ -15,7 +15,7 @@ cleanup audit is `docs/janitor/2026-09-14-1300-sdk-python-cleanup-audit.md`.
 - Gateway-scoped client mode for MCP and other user-JWT sessions
 - Transport compatibility for wrapped `{success,data}` responses and unwrapped Warden/control-plane success objects
 - Local helpers for JWT verification, trace propagation, retries, and console capture
-- Current package version: `9.0.11`
+- Current package version: `9.0.13`
 
 ## Install
 

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.13}/dominus/__init__.py

@@ -121,6 +121,7 @@ from .namespaces.platform import PlatformNamespace
 from .namespaces.coder import CoderNamespace
 from .namespaces.publisher import PublisherNamespace
 from .namespaces.stash import StashNamespace, StashTablesNamespace
+from .namespaces.usage import UsageNamespace
 
 # Export AI namespace for agent-runtime operations
 from .namespaces.ai import (
@@ -190,7 +191,7 @@ from .errors import (
     TimeoutError as DominusTimeoutError,
 )
 
-__version__ = "9.0.11"
+__version__ = "9.0.13"
 __all__ = [
     # Main SDK instance
     "dominus",
@@ -249,6 +250,7 @@ __all__ = [
     "PublisherNamespace",
     "StashNamespace",
     "StashTablesNamespace",
+    "UsageNamespace",
     # AI namespace for agent-runtime operations
     "AiNamespace",
     "RagSubNamespace",

dominus_sdk_python-9.0.13/dominus/helpers/auth.py

@@ -0,0 +1,57 @@
+"""
+Token resolution helper.
+
+Handles resolution of authentication token from environment variables.
+No hardcoded tokens supported - environment variable only.
+"""
+import os
+from typing import Optional
+
+
+def _resolve_token() -> Optional[str]:
+    """
+    Resolve auth token from environment variable.
+
+    Precedence: DOMINUS_USER_TOKEN outranks DOMINUS_TOKEN. This is intentional
+    (the README quick start is a gateway user-token flow), but it means an
+    ambient operator token silently shadows a project PSK. Callers that intend
+    project-PSK auth must scrub DOMINUS_USER_TOKEN (and DOMINUS_MCP_USER_TOKEN)
+    from the environment before importing this package.
+
+    Note: When fetching from Infisical via Sovereign, the secret is stored as
+    PROVISION_DOMINUS_TOKEN but should be set as DOMINUS_TOKEN in environment.
+    The PROVISION_ prefix is dropped when setting environment variables.
+
+    Returns:
+        Token string or None if not set
+    """
+    return os.getenv("DOMINUS_USER_TOKEN") or os.getenv("DOMINUS_TOKEN")
+
+
+def _shadowed_token_hint(token: Optional[str]) -> Optional[str]:
+    """
+    Diagnose a token that may have been shadowed by environment precedence.
+
+    Returns a message naming BOTH variables when, and only when, the ambiguity
+    is real: DOMINUS_USER_TOKEN and DOMINUS_TOKEN are both set AND ``token`` is
+    the shadowing value that precedence selected. A caller-supplied token that
+    is not the environment's chosen value was never ambiguous, so it returns
+    None, as does any environment where only one variable is set.
+
+    Args:
+        token: The token an auth attempt actually used
+
+    Returns:
+        Diagnostic message, or None when there is nothing ambiguous to report
+    """
+    user_token = os.getenv("DOMINUS_USER_TOKEN")
+    psk_token = os.getenv("DOMINUS_TOKEN")
+    if not user_token or not psk_token or token != user_token:
+        return None
+    return (
+        "DOMINUS_USER_TOKEN outranks DOMINUS_TOKEN (dominus/helpers/auth.py) and "
+        "both are set in this environment, so this attempt authenticated with "
+        "DOMINUS_USER_TOKEN. If you intended project-PSK auth, unset "
+        "DOMINUS_USER_TOKEN (and DOMINUS_MCP_USER_TOKEN) before importing the "
+        "SDK and retry."
+    )

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.13}/dominus/helpers/core.py

@@ -11,6 +11,7 @@ import json
 import time
 from typing import Any, Optional
 
+from .auth import _shadowed_token_hint
 from .cache import dominus_cache, gateway_circuit_breaker, exponential_backoff_with_jitter
 
 # Max retries for HTTP requests (reduced from implicit to explicit)
@@ -349,6 +350,13 @@ def is_jwt_valid(jwt_token: str) -> bool:
         return False
 
 
+def _mint_failure_message(message: str, shadow_hint: Optional[str]) -> str:
+    """Append the token-shadowing diagnostic to a failed-mint message."""
+    if not shadow_hint:
+        return message
+    return f"{message}\n{shadow_hint}"
+
+
 async def _get_service_jwt(psk_token: str, base_url: str) -> str:
     """
     Get service JWT by calling gateway /jwt/mint with PSK.
@@ -392,6 +400,10 @@ async def _get_service_jwt(psk_token: str, base_url: str) -> str:
     body_json = {"method": "auth.self", "params": {}}
     body_b64 = _b64_encode(body_json)
 
+    # A rejected mint is indistinguishable from a bad PSK when an ambient
+    # DOMINUS_USER_TOKEN shadowed the intended project PSK at import.
+    shadow_hint = _shadowed_token_hint(psk_token)
+
     # Retry loop for JWT minting
     JWT_MINT_RETRIES = 3
     last_error = None
@@ -419,7 +431,9 @@ async def _get_service_jwt(psk_token: str, base_url: str) -> str:
                 if not result.get("success"):
                     error_msg = result.get("error", "Unknown auth error")
                     gateway_circuit_breaker.record_failure()
-                    raise RuntimeError(f"Auth error: {error_msg}")
+                    raise RuntimeError(
+                        _mint_failure_message(f"Auth error: {error_msg}", shadow_hint)
+                    )
 
                 data = result.get("data", {})
                 jwt = data.get("access_token") or data.get("token")
@@ -465,7 +479,9 @@ async def _get_service_jwt(psk_token: str, base_url: str) -> str:
                 raise RuntimeError(f"Failed to get JWT: {e}") from e
             # For other errors, we've already handled retries in the status check above
             gateway_circuit_breaker.record_failure()
-            raise RuntimeError(f"Failed to get JWT: {e}") from e
+            raise RuntimeError(
+                _mint_failure_message(f"Failed to get JWT: {e}", shadow_hint)
+            ) from e
 
     # Should not reach here, but just in case
     gateway_circuit_breaker.record_failure()

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.13}/dominus/namespaces/__init__.py

@@ -28,6 +28,7 @@ from .platform import PlatformNamespace
 from .coder import CoderNamespace
 from .publisher import PublisherNamespace
 from .stash import StashNamespace, StashTablesNamespace
+from .usage import UsageNamespace
 from .ai import (
     AiNamespace,
     RagSubNamespace,
@@ -65,6 +66,7 @@ __all__ = [
     "PublisherNamespace",
     "StashNamespace",
     "StashTablesNamespace",
+    "UsageNamespace",
     "AiNamespace",
     "RagSubNamespace",
     "ArtifactsSubNamespace",

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.13}/dominus/namespaces/authority.py

@@ -56,6 +56,11 @@ LIST_RUN_KIND = "workflow"
 #: top-level projection on the wire; this SDK never relies on that default.
 RESULT_VIEW_BOUND = "bound"
 
+#: Canonical coherent deploy read view. Authority still serves the legacy
+#: ``latest_deployment_*`` projection when ``view`` is omitted; this SDK never
+#: relies on that default, and carries no legacy fallback.
+DEPLOY_VIEW_COHERENT = "coherent"
+
 
 def remote_command_outcome(payload: Mapping[str, Any]) -> Dict[str, Any]:
     """Unwrap a canonical ``RemoteCommandResult`` to the remote outcome it carries.
@@ -72,6 +77,35 @@ def remote_command_outcome(payload: Mapping[str, Any]) -> Dict[str, Any]:
     return dict(payload)
 
 
+def coherent_deploy_state(payload: Mapping[str, Any]) -> Dict[str, Any]:
+    """Split a coherent deploy read into current state, labeled history, provenance.
+
+    A coherent read returns the deploy's one current rollout, its executor
+    history, and the provenance naming which rollout is current. This accessor
+    keeps that separation intact so history can never be read as current state:
+    ``current_rollout`` stays ``None`` when Authority reports the read as
+    partial (an unset or unresolvable ``current_rollout_id``), and the newest
+    history entry is never substituted for it. ``partial`` restates the
+    provenance flag for callers that branch on it.
+    """
+    envelope: Mapping[str, Any] = payload if isinstance(payload, Mapping) else {}
+    provenance = envelope.get("provenance")
+    provenance = dict(provenance) if isinstance(provenance, Mapping) else {}
+    current = envelope.get("current_rollout")
+    history = envelope.get("executor_history")
+    return {
+        "deploy": dict(envelope.get("deploy") or {}),
+        "current_rollout": dict(current) if isinstance(current, Mapping) else None,
+        "executor_history": (
+            [dict(row) for row in history if isinstance(row, Mapping)]
+            if isinstance(history, list)
+            else []
+        ),
+        "provenance": provenance,
+        "partial": bool(provenance.get("partial")),
+    }
+
+
 def _is_workflow_recipe_ref(value: Optional[str]) -> bool:
     return str(value or "").strip().startswith("recipe://workflow-recipe-v1/")
 
@@ -1077,11 +1111,21 @@ class AuthorityNamespace:
         )
 
     async def get_deploy(self, deploy_id: str, *, timeout: Optional[float] = None) -> Dict[str, Any]:
-        """Get deploy by id. ``GET /api/authority/deploys/{deploy_id}``."""
+        """Get deploy by id in coherent current state.
+
+        ``GET /api/authority/deploys/{deploy_id}?view=coherent`` returns
+        ``{deploy, current_rollout, executor_history, provenance}``: the single
+        current rollout, the executor history labeled as history, and the
+        provenance naming which rollout is current (``partial`` when Authority
+        cannot resolve one). The view is requested explicitly so the read never
+        rides the server's legacy default, and there is no legacy fallback.
+        Use :func:`coherent_deploy_state` to read the sections apart.
+        """
         if not deploy_id:
             raise ValueError("deploy_id is required")
+        qs = _query_string({"view": DEPLOY_VIEW_COHERENT})
         return await self._get(
-            f"/api/authority/deploys/{quote(deploy_id, safe='')}",
+            f"/api/authority/deploys/{quote(deploy_id, safe='')}{qs}",
             timeout=self._http_timeout(timeout, 30.0),
         )
 

dominus_sdk_python-9.0.13/dominus/namespaces/usage.py

@@ -0,0 +1,214 @@
+"""
+Usage Namespace - Dominus consumption and provider-cost reporting.
+
+Canonical SDK entry point for the dominus-usage service's authorized read
+surface: summary, evidence, coverage, and explain. All four route through
+the gateway (``use_gateway=True``), which maps ``/api/usage/*`` ->
+``/svc/usage/*`` upstream to dominus-usage.
+
+This namespace is a thin pass-through: it never converts quantities/amounts
+to float, never infers a default window or grouping (the service applies
+last-7-days / meter+project+environment+logical_service when omitted), and
+never adds a token of its own. An explicitly minted human bearer reaches
+Usage unchanged via the existing ``Dominus(gateway_user_token=...)``
+constructor behavior, exactly like ``dominus.authority.*``.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Sequence, TYPE_CHECKING, Union
+from urllib.parse import urlencode
+
+if TYPE_CHECKING:
+    from ..start import Dominus
+
+
+def _query_string(params: Dict[str, Any]) -> str:
+    """Build a ``?...`` query string, repeating the key for list/tuple values."""
+    pairs: list[tuple[str, str]] = []
+    for key, value in params.items():
+        if value is None or value == "":
+            continue
+        if isinstance(value, (list, tuple)):
+            for item in value:
+                if item is None or item == "":
+                    continue
+                pairs.append((key, str(item)))
+        else:
+            pairs.append((key, str(value)))
+    if not pairs:
+        return ""
+    return "?" + urlencode(pairs)
+
+
+class UsageNamespace:
+    """
+    Usage service namespace: typed consumption and provider-cost reads.
+
+    Usage::
+
+        await dominus.usage.summary(since="2026-09-01T00:00:00Z", meter="ai.tokens.input")
+        await dominus.usage.evidence(project_id="proj_123", limit=100)
+        await dominus.usage.coverage()
+        await dominus.usage.explain(observation_id="obs_123")
+    """
+
+    def __init__(self, client: "Dominus"):
+        self._client = client
+
+    async def _get(self, endpoint: str, *, timeout: float = 30.0) -> Dict[str, Any]:
+        return await self._client._request(
+            endpoint=endpoint,
+            method="GET",
+            use_gateway=True,
+            timeout=timeout,
+        )
+
+    async def summary(
+        self,
+        *,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+        group_by: Optional[Union[str, Sequence[str]]] = None,
+        project_id: Optional[str] = None,
+        environment: Optional[str] = None,
+        logical_service: Optional[str] = None,
+        family_root_id: Optional[str] = None,
+        meter: Optional[str] = None,
+        provider: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> Dict[str, Any]:
+        """Unit-aware usage rows plus distinct provider-reported/estimated cost.
+
+        ``GET /api/usage/summary``. Omitting ``since``/``until`` uses the
+        service's last-7-days default; omitting ``group_by`` uses its default
+        grouping. Quantities/amounts are returned as decimal strings, never
+        converted to float.
+        """
+        qs = _query_string(
+            {
+                "since": since,
+                "until": until,
+                "group_by": group_by,
+                "project_id": project_id,
+                "environment": environment,
+                "logical_service": logical_service,
+                "family_root_id": family_root_id,
+                "meter": meter,
+                "provider": provider,
+            }
+        )
+        return await self._get(f"/api/usage/summary{qs}", timeout=timeout)
+
+    async def evidence(
+        self,
+        *,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+        project_id: Optional[str] = None,
+        environment: Optional[str] = None,
+        logical_service: Optional[str] = None,
+        family_root_id: Optional[str] = None,
+        meter: Optional[str] = None,
+        provider: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> Dict[str, Any]:
+        """Cursor-paginated observation/provider-source evidence.
+
+        ``GET /api/usage/evidence``. ``limit`` defaults to 100 and is bounded
+        to 500 server-side; pass the response's ``next_cursor`` back in to
+        page forward.
+        """
+        qs = _query_string(
+            {
+                "since": since,
+                "until": until,
+                "project_id": project_id,
+                "environment": environment,
+                "logical_service": logical_service,
+                "family_root_id": family_root_id,
+                "meter": meter,
+                "provider": provider,
+                "limit": limit,
+                "cursor": cursor,
+            }
+        )
+        return await self._get(f"/api/usage/evidence{qs}", timeout=timeout)
+
+    async def coverage(
+        self,
+        *,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+        project_id: Optional[str] = None,
+        environment: Optional[str] = None,
+        logical_service: Optional[str] = None,
+        family_root_id: Optional[str] = None,
+        meter: Optional[str] = None,
+        provider: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> Dict[str, Any]:
+        """Registered meter/source coverage, freshness, and gap reasons.
+
+        ``GET /api/usage/coverage``. Never reports unsupported capture as
+        complete; ``gaps`` names each unavailable reason explicitly.
+        """
+        qs = _query_string(
+            {
+                "since": since,
+                "until": until,
+                "project_id": project_id,
+                "environment": environment,
+                "logical_service": logical_service,
+                "family_root_id": family_root_id,
+                "meter": meter,
+                "provider": provider,
+            }
+        )
+        return await self._get(f"/api/usage/coverage{qs}", timeout=timeout)
+
+    async def explain(
+        self,
+        *,
+        observation_id: Optional[str] = None,
+        operation_id: Optional[str] = None,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+        project_id: Optional[str] = None,
+        environment: Optional[str] = None,
+        logical_service: Optional[str] = None,
+        family_root_id: Optional[str] = None,
+        meter: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> Dict[str, Any]:
+        """Explanation linking permitted observations, attempts, and cost basis.
+
+        ``GET /api/usage/explain``. Exactly one of ``observation_id`` or
+        ``operation_id`` must be supplied; supplying both (or neither) is
+        rejected locally before the request is sent, matching the service's
+        own ambiguous-selector rejection. The remaining filters narrow which
+        observations can match an ``operation_id`` lookup; they are inert for
+        an ``observation_id`` lookup, which the service resolves unfiltered.
+        """
+        if bool(observation_id) == bool(operation_id):
+            raise ValueError(
+                "usage.explain requires exactly one of observation_id or operation_id"
+            )
+        qs = _query_string(
+            {
+                "observation_id": observation_id,
+                "operation_id": operation_id,
+                "since": since,
+                "until": until,
+                "project_id": project_id,
+                "environment": environment,
+                "logical_service": logical_service,
+                "family_root_id": family_root_id,
+                "meter": meter,
+            }
+        )
+        return await self._get(f"/api/usage/explain{qs}", timeout=timeout)
+
+
+__all__ = ["UsageNamespace"]

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.13}/dominus/start.py

@@ -196,6 +196,10 @@ class Dominus:
         from .namespaces.recipes import RecipesNamespace
         self.recipes = RecipesNamespace(self)
 
+        # Usage service (dominus-usage; consumption and provider-cost reports)
+        from .namespaces.usage import UsageNamespace
+        self.usage = UsageNamespace(self)
+
         # Cache for JWT public key
         self._public_key_cache = None
 

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.13}/dominus_sdk_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 9.0.11
+Version: 9.0.13
 Summary: Python SDK for the Dominus gateway-first platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License-Expression: LicenseRef-Proprietary
@@ -38,8 +38,8 @@ Async Python SDK for the Dominus gateway-first service plane.
 ## Agent Guide
 
 Start with `docs/agent-guide/INDEX.md`. The current snapshot is
-`docs/agent-guide/2026-09-14-1300-sdk-python/00-reading-order.md`; the latest
-cleanup audit is `docs/janitor/2026-09-14-1300-sdk-python-cleanup-audit.md`.
+`docs/agent-guide/2026-09-19-1300-sdk-python/00-reading-order.md`; the latest
+cleanup audit is `docs/janitor/2026-09-19-1300-sdk-python-cleanup-audit.md`.
 
 ## What This Repo Ships
 
@@ -48,7 +48,7 @@ cleanup audit is `docs/janitor/2026-09-14-1300-sdk-python-cleanup-audit.md`.
 - Gateway-scoped client mode for MCP and other user-JWT sessions
 - Transport compatibility for wrapped `{success,data}` responses and unwrapped Warden/control-plane success objects
 - Local helpers for JWT verification, trace propagation, retries, and console capture
-- Current package version: `9.0.11`
+- Current package version: `9.0.13`
 
 ## Install
 

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.13}/dominus_sdk_python.egg-info/SOURCES.txt

@@ -44,6 +44,7 @@ dominus/namespaces/secrets.py
 dominus/namespaces/secure.py
 dominus/namespaces/stash.py
 dominus/namespaces/sync.py
+dominus/namespaces/usage.py
 dominus/namespaces/warden.py
 dominus/namespaces/workflow.py
 dominus/services/__init__.py
@@ -76,7 +77,9 @@ tests/test_recipes_stash_routing.py
 tests/test_secrets_presence_contract.py
 tests/test_stash_artifact_facade.py
 tests/test_stash_tables_namespace.py
+tests/test_token_precedence.py
 tests/test_transport_compat.py
+tests/test_usage_namespace.py
 tests/test_version_consistency.py
 tests/test_workflow_lifecycle.py
 tests/test_workflow_refs.py

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dominus-sdk-python"
-version = "9.0.11"
+version = "9.0.13"
 description = "Python SDK for the Dominus gateway-first platform"
 readme = "README.md"
 license = "LicenseRef-Proprietary"

{dominus_sdk_python-9.0.11 → dominus_sdk_python-9.0.13}/tests/test_authority_public_vocabulary.py

@@ -611,6 +611,91 @@ async def test_bootstrap_provisioning_target_carries_repo_template():
     assert "repo_template" not in absent_client.calls[-1]["body"]
 
 
+# --- Task 16: singular deploy reader reads coherent current state --
+
+
+@pytest.mark.asyncio
+async def test_get_deploy_requests_the_coherent_view_explicitly():
+    from dominus.namespaces.authority import DEPLOY_VIEW_COHERENT
+
+    client = FakeClient()
+    ns = AuthorityNamespace(client)
+
+    await ns.get_deploy("deploy::dominus-authority--production")
+
+    assert client.calls[0]["method"] == "GET"
+    assert client.calls[0]["endpoint"] == (
+        "/api/authority/deploys/deploy%3A%3Adominus-authority--production?view=coherent"
+    )
+    # The view is named on the wire, never inherited from the server default.
+    assert DEPLOY_VIEW_COHERENT == "coherent"
+
+
+def test_coherent_deploy_state_keeps_current_and_history_labeled_apart():
+    from dominus.namespaces.authority import coherent_deploy_state
+
+    state = coherent_deploy_state(
+        {
+            "deploy": {"deploy_id": "deploy-1", "app_slug": "carebridge"},
+            "current_rollout": {"rollout_id": "rollout-2", "generation": 7},
+            "executor_history": [
+                {"rollout_id": "rollout-1", "generation": 6},
+                {"rollout_id": "rollout-2", "generation": 7, "is_current": True},
+            ],
+            "provenance": {
+                "view": "coherent",
+                "source": "current_rollout",
+                "rollout_id": "rollout-2",
+                "generation": 7,
+                "is_current": True,
+                "partial": False,
+            },
+        }
+    )
+
+    assert state["current_rollout"]["rollout_id"] == "rollout-2"
+    assert [row["rollout_id"] for row in state["executor_history"]] == ["rollout-1", "rollout-2"]
+    assert state["provenance"]["generation"] == 7
+    assert state["partial"] is False
+
+
+def test_coherent_deploy_state_never_substitutes_history_for_a_missing_current_rollout():
+    from dominus.namespaces.authority import coherent_deploy_state
+
+    state = coherent_deploy_state(
+        {
+            "deploy": {"deploy_id": "deploy-2"},
+            "current_rollout": None,
+            "executor_history": [{"rollout_id": "rollout-9", "generation": 3}],
+            "provenance": {
+                "view": "coherent",
+                "source": None,
+                "rollout_id": None,
+                "is_current": False,
+                "partial": True,
+            },
+        }
+    )
+
+    # An unresolved current rollout stays an explicit partial; the newest
+    # history entry is not promoted into its place.
+    assert state["current_rollout"] is None
+    assert state["partial"] is True
+    assert [row["rollout_id"] for row in state["executor_history"]] == ["rollout-9"]
+
+
+def test_coherent_deploy_state_tolerates_a_non_envelope_payload():
+    from dominus.namespaces.authority import coherent_deploy_state
+
+    state = coherent_deploy_state({"code": "authority.deploy_not_found"})
+
+    assert state["deploy"] == {}
+    assert state["current_rollout"] is None
+    assert state["executor_history"] == []
+    assert state["provenance"] == {}
+    assert state["partial"] is False
+
+
 def test_bootstrap_signature_carries_standalone_and_root_role():
     bootstrap_sig = inspect.signature(AuthorityNamespace.bootstrap_provisioning_target)
     assert "standalone" in bootstrap_sig.parameters