dominus-sdk-python 9.0.5__tar.gz → 9.0.7__tar.gz

{dominus_sdk_python-9.0.5 → dominus_sdk_python-9.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 9.0.5
+Version: 9.0.7
 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-08-04-sdk-python/00-reading-order.md`; the latest
-cleanup audit is `docs/janitor/2026-08-04-sdk-python-cleanup-audit.md`.
+`docs/agent-guide/2026-09-03-0942-sdk-python/00-reading-order.md`; the latest
+cleanup audit is `docs/janitor/2026-09-03-0942-sdk-python-cleanup-audit.md`.
 
 ## What This Repo Ships
 
@@ -48,7 +48,7 @@ cleanup audit is `docs/janitor/2026-08-04-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.5`
+- Current package version: `9.0.6`
 
 ## Install
 

{dominus_sdk_python-9.0.5 → dominus_sdk_python-9.0.7}/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-08-04-sdk-python/00-reading-order.md`; the latest
-cleanup audit is `docs/janitor/2026-08-04-sdk-python-cleanup-audit.md`.
+`docs/agent-guide/2026-09-03-0942-sdk-python/00-reading-order.md`; the latest
+cleanup audit is `docs/janitor/2026-09-03-0942-sdk-python-cleanup-audit.md`.
 
 ## What This Repo Ships
 
@@ -15,7 +15,7 @@ cleanup audit is `docs/janitor/2026-08-04-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.5`
+- Current package version: `9.0.6`
 
 ## Install
 

{dominus_sdk_python-9.0.5 → dominus_sdk_python-9.0.7}/dominus/__init__.py

@@ -160,12 +160,24 @@ from .helpers.trace import (
 # Export error classes
 from .errors import (
     DominusError,
+    # v1 aliases (preserved — deprecated in v2, removed in v3 per ADR 0010)
     AuthenticationError,
     AuthorizationError,
-    NotFoundError,
     ValidationError,
-    ConflictError,
     ServiceError,
+    # Per-kind canonical subclasses (Seams fork 6, ADR 0010)
+    UnauthorizedError,
+    ForbiddenError,
+    NotFoundError,
+    ValidationFailedError,
+    ConflictError,
+    RateLimitedError,
+    UpstreamUnavailableError,
+    InternalError,
+    TimeoutError,
+    CanceledError,
+    UnsupportedVersionError,
+    # Stash subclasses
     StashBookmarkArtifactNotFound,
     StashBookmarkInvalidVersionRef,
     StashBookmarkDuplicateName,
@@ -178,7 +190,7 @@ from .errors import (
     TimeoutError as DominusTimeoutError,
 )
 
-__version__ = "9.0.5"
+__version__ = "9.0.6"
 __all__ = [
     # Main SDK instance
     "dominus",
@@ -262,12 +274,23 @@ __all__ = [
     "with_trace",
     # Error classes
     "DominusError",
+    # v1 aliases (preserved)
     "AuthenticationError",
     "AuthorizationError",
-    "NotFoundError",
     "ValidationError",
-    "ConflictError",
     "ServiceError",
+    # Per-kind canonical subclasses
+    "UnauthorizedError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ValidationFailedError",
+    "ConflictError",
+    "RateLimitedError",
+    "UpstreamUnavailableError",
+    "InternalError",
+    "TimeoutError",
+    "CanceledError",
+    "UnsupportedVersionError",
     "StashBookmarkArtifactNotFound",
     "StashBookmarkInvalidVersionRef",
     "StashBookmarkDuplicateName",

{dominus_sdk_python-9.0.5 → dominus_sdk_python-9.0.7}/dominus/namespaces/artifacts.py

@@ -1,5 +1,11 @@
 """
-Artifacts Namespace - Temporary artifact storage.
+Artifacts Namespace - temporary and addressed artifact storage.
+
+Positioning: this is the **escape hatch** for direct ``ar://`` addressed
+artifact workflows — use it when you already hold a canonical ``ar://`` ref.
+For new code, prefer a Stash ``artifact-v2``-backed kind (e.g. ``artifact-v1``)
+via ``dominus.stash.*``, the primary storage surface (the Two-Layer Storage
+Rule). These addressed helpers are a building block under Stash, not deprecated.
 
 Provides auto-tiered artifact storage (Redis < 1MB, B2 >= 1MB)
 with TTL-based expiration. Routes through gateway to artifact-worker.

{dominus_sdk_python-9.0.5 → dominus_sdk_python-9.0.7}/dominus/namespaces/authority.py

@@ -48,6 +48,30 @@ def _is_provisioning_bootstrap_run_kind(run_kind: Optional[str]) -> bool:
     return _normalize_run_kind_token(run_kind) == "provisioning_bootstrap"
 
 
+#: The only run kind ``GET /api/authority/runs`` surfaces. Authority rejects any
+#: other value; ``bootstrap``/``deploy_rollout`` runs are read by run id.
+LIST_RUN_KIND = "workflow"
+
+#: Canonical control-result view. Authority still defaults to the legacy
+#: top-level projection on the wire; this SDK never relies on that default.
+RESULT_VIEW_BOUND = "bound"
+
+
+def remote_command_outcome(payload: Mapping[str, Any]) -> Dict[str, Any]:
+    """Unwrap a canonical ``RemoteCommandResult`` to the remote outcome it carries.
+
+    The envelope's ``owner``/``bound_subject``/``provenance`` state who actually
+    performed the command; callers that only need the run summary use this, and
+    callers that need attribution read the envelope directly. A payload that is
+    not an envelope is returned unchanged so an upstream error body is never
+    replaced with an empty dict.
+    """
+    if isinstance(payload, Mapping) and "outcome" in payload and "bound_subject" in payload:
+        outcome = payload.get("outcome")
+        return dict(outcome) if isinstance(outcome, Mapping) else {}
+    return dict(payload)
+
+
 def _is_workflow_recipe_ref(value: Optional[str]) -> bool:
     return str(value or "").strip().startswith("recipe://workflow-recipe-v1/")
 
@@ -313,9 +337,22 @@ class AuthorityNamespace:
             timeout=self._http_timeout(timeout, 30.0),
         )
 
+    async def run_kinds(self, *, timeout: Optional[float] = None) -> Dict[str, Any]:
+        """Read the run-kind/capability matrix. ``GET /api/authority/run-kinds``.
+
+        Explicit capability discovery: callers ask which actions a kind supports
+        (and which kinds the run list surfaces) instead of guessing from run-id
+        prefixes.
+        """
+        return await self._get(
+            "/api/authority/run-kinds",
+            timeout=self._http_timeout(timeout, 30.0),
+        )
+
     async def list_runs(
         self,
         *,
+        kind: str = LIST_RUN_KIND,
         workflow_id: Optional[str] = None,
         status: Optional[str] = None,
         group: Optional[str] = None,
@@ -328,9 +365,20 @@ class AuthorityNamespace:
         offset: int = 0,
         timeout: Optional[float] = None,
     ) -> Dict[str, Any]:
-        """List Authority-backed runs. ``GET /api/authority/runs``."""
+        """List Authority-backed workflow runs. ``GET /api/authority/runs``.
+
+        This list is workflow-kind only and says so: ``kind`` is sent explicitly
+        rather than inheriting a server default that reads like a universal
+        inventory. Use :meth:`run_kinds` to see which kinds are listable.
+        """
+        if str(kind).strip().lower() != LIST_RUN_KIND:
+            raise ValueError(
+                f"Authority lists only kind={LIST_RUN_KIND!r} runs; "
+                f"{kind!r} runs are read by run id via get_run()"
+            )
         tid, tev = self._target_query_params(target_org_id, target_env)
         qs = _query_string({
+            "kind": LIST_RUN_KIND,
             "workflow_id": workflow_id,
             "status": status,
             "group": group,
@@ -378,6 +426,7 @@ class AuthorityNamespace:
             "metadata": metadata,
             **self._initiator(initiator_type, initiator_id, idempotency_key),
             **self._scope(app_slug, env, target_org_id, target_env),
+            "result_view": RESULT_VIEW_BOUND,
         })
         return await self._post(
             f"/api/authority/runs/{quote(run_id, safe='')}/cancel",
@@ -422,6 +471,7 @@ class AuthorityNamespace:
             "metadata": metadata,
             **self._initiator(initiator_type, initiator_id, idempotency_key),
             **self._scope(app_slug, env, target_org_id, target_env),
+            "result_view": RESULT_VIEW_BOUND,
         })
         return await self._post(
             f"/api/authority/runs/{quote(run_id, safe='')}/retry",
@@ -459,6 +509,7 @@ class AuthorityNamespace:
             "metadata": metadata,
             **self._initiator(initiator_type, initiator_id, idempotency_key),
             **self._scope(app_slug, env, target_org_id, target_env),
+            "result_view": RESULT_VIEW_BOUND,
         })
         return await self._post(
             f"/api/authority/runs/{quote(run_id, safe='')}/nudge",
@@ -898,6 +949,7 @@ class AuthorityNamespace:
         region: Optional[str] = None,
         system: Optional[str] = None,
         github_mode: Optional[str] = None,
+        repo_template: Optional[str] = None,
         overwrite_existing: Optional[bool] = None,
         owner_email: Optional[str] = None,
         execution_mode: Optional[str] = None,
@@ -928,6 +980,7 @@ class AuthorityNamespace:
             "region": region,
             "system": system,
             "github_mode": github_mode,
+            "repo_template": repo_template,
             "overwrite_existing": overwrite_existing,
             "owner_email": owner_email,
             "execution_mode": execution_mode,

{dominus_sdk_python-9.0.5 → dominus_sdk_python-9.0.7}/dominus/namespaces/browser.py

@@ -162,7 +162,12 @@ class BrowserNamespace:
         )
 
     async def get_run_status(self, run_id: str, *, timeout: float = 30.0) -> Dict[str, Any]:
-        """Read browser run runtime state. ``GET /api/browser/runs/{run_id}/status``."""
+        """Read browser run runtime state. ``GET /api/browser/runs/{run_id}/status``.
+
+        The envelope may carry an additive ``result_stash_ref`` (Stash palette
+        ``artifact`` selector) alongside the legacy ``result_artifact_ref``; it is
+        present only when a best-effort Stash dual-write succeeded.
+        """
         if not run_id:
             raise ValueError("run_id is required")
         return await self._get(

{dominus_sdk_python-9.0.5 → dominus_sdk_python-9.0.7}/dominus/namespaces/stash.py

@@ -1,5 +1,9 @@
 """
-Stash Namespace - per-scope durable items (credentials + configs).
+Stash Namespace - the primary kind-addressed storage surface.
+
+Store named-kind data here and let the kind registry pick the backend — you
+address items by (kind, scope, key), not by physical storage. ``ar://``
+addressed artifact workflows remain the escape hatch for foreign refs.
 
 Routes through ``/svc/stash/*`` on the Dominus gateway. The stash worker
 stores items in each project's ``stash.*`` schema and transparently falls
@@ -53,6 +57,18 @@ ManagedTableOperator = Literal[
     "after",
 ]
 
+# Live stash kind backends. The kind registry dispatches each registered kind
+# to exactly one of these; `artifact-v2` and `journal` are the newer additions
+# that previously had no typed surface in this SDK.
+StashBackend = Literal[
+    "db-row",
+    "b2-versioned-bytes",
+    "b2-pointer-text",
+    "redis-ttl",
+    "artifact-v2",
+    "journal",
+]
+
 
 class _ManagedTableFieldOptional(TypedDict, total=False):
     required: bool
@@ -536,6 +552,7 @@ class StashNamespace:
         self,
         *,
         kind: str,
+        backend: Optional[StashBackend] = None,
         is_sensitive: Optional[bool] = None,
         value_schema: Optional[Dict[str, Any]] = None,
         default_rotation_days: Optional[int] = None,
@@ -544,6 +561,8 @@ class StashNamespace:
     ) -> Dict[str, Any]:
         """Register or update a kind in stash.kind_registry. Admin-scoped."""
         body: Dict[str, Any] = {"kind": kind}
+        if backend is not None:
+            body["backend"] = backend
         if is_sensitive is not None:
             body["is_sensitive"] = is_sensitive
         if value_schema is not None:

{dominus_sdk_python-9.0.5 → dominus_sdk_python-9.0.7}/dominus/start.py

@@ -472,7 +472,7 @@ class Dominus:
             if not isinstance(error_details, dict):
                 error_details = {}
             for src in (error_payload, nested_err):
-                for key in ("code", "category", "retryable", "trace_id", "request_id"):
+                for key in ("kind", "code", "category", "retryable", "trace_id", "request_id", "correlation_id", "cause"):
                     if key in src and key not in error_details:
                         error_details[key] = src[key]
             raise_for_status(
@@ -502,7 +502,7 @@ class Dominus:
             error_details = result.get("details")
             if not isinstance(error_details, dict):
                 error_details = {}
-            for key in ("code", "category", "retryable", "trace_id", "request_id"):
+            for key in ("kind", "code", "category", "retryable", "trace_id", "request_id", "correlation_id", "cause"):
                 if key in result:
                     error_details[key] = result[key]
             raise DominusError(str(error_msg), details=error_details, endpoint=endpoint)

{dominus_sdk_python-9.0.5 → dominus_sdk_python-9.0.7}/dominus_sdk_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 9.0.5
+Version: 9.0.7
 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-08-04-sdk-python/00-reading-order.md`; the latest
-cleanup audit is `docs/janitor/2026-08-04-sdk-python-cleanup-audit.md`.
+`docs/agent-guide/2026-09-03-0942-sdk-python/00-reading-order.md`; the latest
+cleanup audit is `docs/janitor/2026-09-03-0942-sdk-python-cleanup-audit.md`.
 
 ## What This Repo Ships
 
@@ -48,7 +48,7 @@ cleanup audit is `docs/janitor/2026-08-04-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.5`
+- Current package version: `9.0.6`
 
 ## Install
 

{dominus_sdk_python-9.0.5 → dominus_sdk_python-9.0.7}/dominus_sdk_python.egg-info/SOURCES.txt

@@ -59,6 +59,7 @@ tests/test_contract.py
 tests/test_control_plane_namespaces.py
 tests/test_error_recovery_action.py
 tests/test_errors.py
+tests/test_errors_aliases.py
 tests/test_flat_commands.py
 tests/test_health.py
 tests/test_logs.py

{dominus_sdk_python-9.0.5 → dominus_sdk_python-9.0.7}/pyproject.toml

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

{dominus_sdk_python-9.0.5 → dominus_sdk_python-9.0.7}/tests/test_authority_public_vocabulary.py

@@ -515,3 +515,97 @@ async def test_authority_ensure_run_bootstrap_requires_provisioning_target_slug(
             env="production",
         )
     assert client.calls == []
+
+
+# --- Task 21: canonical run-kind discovery, honest list, bound control results --
+
+
+@pytest.mark.asyncio
+async def test_run_kinds_reads_the_explicit_capability_surface():
+    client = FakeClient()
+    ns = AuthorityNamespace(client)
+
+    await ns.run_kinds()
+
+    assert client.calls[0]["endpoint"] == "/api/authority/run-kinds"
+    assert client.calls[0]["method"] == "GET"
+
+
+@pytest.mark.asyncio
+async def test_list_runs_states_the_workflow_kind_it_actually_gets():
+    client = FakeClient()
+    ns = AuthorityNamespace(client)
+
+    await ns.list_runs(limit=5)
+
+    assert "kind=workflow" in client.calls[0]["endpoint"]
+
+
+@pytest.mark.asyncio
+async def test_list_runs_rejects_a_kind_authority_does_not_list():
+    client = FakeClient()
+    ns = AuthorityNamespace(client)
+
+    with pytest.raises(ValueError):
+        await ns.list_runs(kind="bootstrap")
+
+    assert client.calls == []
+
+
+@pytest.mark.asyncio
+async def test_run_control_calls_request_the_canonical_bound_result():
+    client = FakeClient()
+    ns = AuthorityNamespace(client)
+
+    await ns.cancel_run("run-1", reason="operator")
+    await ns.retry_run("run-1", reason="operator")
+    await ns.nudge_run("run-1", reason="operator")
+
+    assert [call["body"]["result_view"] for call in client.calls] == ["bound", "bound", "bound"]
+
+
+def test_run_control_outcome_helper_preserves_owner_and_provenance():
+    from dominus.namespaces.authority import remote_command_outcome
+
+    envelope = {
+        "owner": "workflow-manager",
+        "bound_subject": {"kind": "workflow", "canonical_id": "wf-1"},
+        "operation": "cancel",
+        "outcome": {"run_id": "run-1", "status": "cancelled"},
+        "observed_at": "2026-08-24T00:00:00Z",
+        "provenance": {"request_id": "req_1", "trace_id": "tr_1"},
+    }
+
+    assert remote_command_outcome(envelope) == {"run_id": "run-1", "status": "cancelled"}
+    # A non-envelope payload is returned untouched rather than silently emptied.
+    assert remote_command_outcome({"run_id": "run-1"}) == {"run_id": "run-1"}
+
+
+def test_bootstrap_signature_carries_repo_template():
+    bootstrap_sig = inspect.signature(AuthorityNamespace.bootstrap_provisioning_target)
+    assert "repo_template" in bootstrap_sig.parameters
+
+
+@pytest.mark.asyncio
+async def test_bootstrap_provisioning_target_carries_repo_template():
+    client = FakeClient()
+    namespace = AuthorityNamespace(client)
+    await namespace.bootstrap_provisioning_target(
+        "summit-radiology",
+        shared_app_slug="shared-core",
+        app_slug="carebridge",
+        env="production",
+        repo_template="dominus-fastapi-template",
+    )
+    assert client.calls[-1]["body"]["repo_template"] == "dominus-fastapi-template"
+
+    absent_client = FakeClient()
+    absent_namespace = AuthorityNamespace(absent_client)
+    await absent_namespace.bootstrap_provisioning_target(
+        "summit-radiology",
+        shared_app_slug="shared-core",
+        app_slug="carebridge",
+        env="production",
+    )
+    # Absent field keeps the legacy wire body byte-identical.
+    assert "repo_template" not in absent_client.calls[-1]["body"]

dominus_sdk_python-9.0.7/tests/test_errors_aliases.py

@@ -0,0 +1,277 @@
+"""
+Test per-kind canonical error subclasses and v1 alias compatibility.
+
+Seams fork 6 (ADR 0010): DominusError base + 11 per-kind subclasses;
+existing class names preserved as aliases in v1.
+"""
+import pytest
+from dominus.errors import (
+    DominusError,
+    # v1 aliases (preserved)
+    AuthenticationError,
+    AuthorizationError,
+    ValidationError,
+    ServiceError,
+    ConnectionError,
+    SecureTableError,
+    # Per-kind canonical subclasses
+    UnauthorizedError,
+    ForbiddenError,
+    NotFoundError,
+    ValidationFailedError,
+    ConflictError,
+    RateLimitedError,
+    UpstreamUnavailableError,
+    InternalError,
+    TimeoutError,
+    CanceledError,
+    UnsupportedVersionError,
+    # Stash subclasses
+    StashBookmarkArtifactNotFound,
+    StashBookmarkInvalidVersionRef,
+    StashBookmarkDuplicateName,
+    StashBookmarkUpstreamRejected,
+    StashWatchInvalidWebhookUrl,
+    StashWatchUpstreamRejected,
+    StashWatchNotFound,
+    raise_for_status,
+)
+
+CANONICAL_KINDS = [
+    "unauthorized",
+    "forbidden",
+    "not_found",
+    "validation_failed",
+    "conflict",
+    "rate_limited",
+    "upstream_unavailable",
+    "internal",
+    "timeout",
+    "canceled",
+    "unsupported_version",
+]
+
+PER_KIND_CLASSES = [
+    UnauthorizedError,
+    ForbiddenError,
+    NotFoundError,
+    ValidationFailedError,
+    ConflictError,
+    RateLimitedError,
+    UpstreamUnavailableError,
+    InternalError,
+    TimeoutError,
+    CanceledError,
+    UnsupportedVersionError,
+]
+
+
+class TestPerKindSubclasses:
+    """Each canonical kind has a DominusError subclass with the correct kind."""
+
+    def test_all_kinds_have_subclass(self):
+        kind_map = {cls.kind: cls for cls in PER_KIND_CLASSES}
+        for kind in CANONICAL_KINDS:
+            assert kind in kind_map, f"Missing subclass for kind '{kind}'"
+
+    def test_each_subclass_has_kind_attribute(self):
+        for cls in PER_KIND_CLASSES:
+            assert cls.kind in CANONICAL_KINDS, f"{cls.__name__}.kind = {cls.kind!r} not in canonical kinds"
+
+    def test_each_subclass_is_dominus_error(self):
+        for cls in PER_KIND_CLASSES:
+            assert issubclass(cls, DominusError), f"{cls.__name__} is not a DominusError subclass"
+
+    def test_instance_kind_matches_class_kind(self):
+        for cls in PER_KIND_CLASSES:
+            err = cls("test")
+            assert err.kind == cls.kind, f"{cls.__name__} instance kind mismatch: {err.kind!r} != {cls.kind!r}"
+
+
+class TestV1Aliases:
+    """v1 alias class names resolve to the canonical per-kind subclass."""
+
+    def test_authentication_error_is_unauthorized(self):
+        assert issubclass(AuthenticationError, UnauthorizedError)
+        err = AuthenticationError()
+        assert isinstance(err, UnauthorizedError)
+        assert isinstance(err, DominusError)
+        assert err.kind == "unauthorized"
+
+    def test_authorization_error_is_forbidden(self):
+        assert issubclass(AuthorizationError, ForbiddenError)
+        err = AuthorizationError()
+        assert isinstance(err, ForbiddenError)
+        assert isinstance(err, DominusError)
+        assert err.kind == "forbidden"
+
+    def test_validation_error_is_validation_failed(self):
+        assert issubclass(ValidationError, ValidationFailedError)
+        err = ValidationError()
+        assert isinstance(err, ValidationFailedError)
+        assert isinstance(err, DominusError)
+        assert err.kind == "validation_failed"
+
+    def test_service_error_is_upstream_unavailable(self):
+        assert issubclass(ServiceError, UpstreamUnavailableError)
+        err = ServiceError()
+        assert isinstance(err, UpstreamUnavailableError)
+        assert isinstance(err, DominusError)
+        assert err.kind == "upstream_unavailable"
+
+    def test_connection_error_is_upstream_unavailable(self):
+        assert issubclass(ConnectionError, UpstreamUnavailableError)
+        err = ConnectionError()
+        assert isinstance(err, UpstreamUnavailableError)
+        assert isinstance(err, DominusError)
+        assert err.kind == "upstream_unavailable"
+
+    def test_secure_table_error_is_forbidden(self):
+        assert issubclass(SecureTableError, ForbiddenError)
+        err = SecureTableError()
+        assert isinstance(err, ForbiddenError)
+        assert isinstance(err, DominusError)
+        assert err.kind == "forbidden"
+
+    def test_existing_catch_sites_still_work(self):
+        """Catching by old name still catches the canonical subclass instance."""
+        err = UnauthorizedError("bad token")
+        # Old catch pattern
+        try:
+            raise err
+        except AuthenticationError as e:
+            assert e.kind == "unauthorized"
+            assert e.message == "bad token"
+
+
+class TestStashSubclasses:
+    """Stash subclasses map to canonical per-kind bases."""
+
+    def test_stash_bookmark_not_found(self):
+        assert issubclass(StashBookmarkArtifactNotFound, NotFoundError)
+        assert StashBookmarkArtifactNotFound().kind == "not_found"
+
+    def test_stash_bookmark_invalid_ref(self):
+        assert issubclass(StashBookmarkInvalidVersionRef, ValidationFailedError)
+        assert StashBookmarkInvalidVersionRef().kind == "validation_failed"
+
+    def test_stash_bookmark_duplicate(self):
+        assert issubclass(StashBookmarkDuplicateName, ConflictError)
+        assert StashBookmarkDuplicateName().kind == "conflict"
+
+    def test_stash_bookmark_upstream(self):
+        assert issubclass(StashBookmarkUpstreamRejected, UpstreamUnavailableError)
+        assert StashBookmarkUpstreamRejected().kind == "upstream_unavailable"
+
+    def test_stash_watch_invalid_url(self):
+        assert issubclass(StashWatchInvalidWebhookUrl, ValidationFailedError)
+        assert StashWatchInvalidWebhookUrl().kind == "validation_failed"
+
+    def test_stash_watch_upstream(self):
+        assert issubclass(StashWatchUpstreamRejected, UpstreamUnavailableError)
+        assert StashWatchUpstreamRejected().kind == "upstream_unavailable"
+
+    def test_stash_watch_not_found(self):
+        assert issubclass(StashWatchNotFound, NotFoundError)
+        assert StashWatchNotFound().kind == "not_found"
+
+
+class TestRaiseForStatus:
+    """raise_for_status maps HTTP codes to canonical per-kind classes."""
+
+    def test_401_raises_unauthorized(self):
+        with pytest.raises(UnauthorizedError) as exc:
+            raise_for_status(401, "bad token")
+        assert exc.value.kind == "unauthorized"
+
+    def test_403_raises_forbidden(self):
+        with pytest.raises(ForbiddenError) as exc:
+            raise_for_status(403, "nope")
+        assert exc.value.kind == "forbidden"
+
+    def test_404_raises_not_found(self):
+        with pytest.raises(NotFoundError) as exc:
+            raise_for_status(404, "gone")
+        assert exc.value.kind == "not_found"
+
+    def test_400_raises_validation_failed(self):
+        with pytest.raises(ValidationFailedError) as exc:
+            raise_for_status(400, "bad input")
+        assert exc.value.kind == "validation_failed"
+
+    def test_409_raises_conflict(self):
+        with pytest.raises(ConflictError) as exc:
+            raise_for_status(409, "dup")
+        assert exc.value.kind == "conflict"
+
+    def test_429_raises_rate_limited(self):
+        with pytest.raises(RateLimitedError) as exc:
+            raise_for_status(429, "slow down")
+        assert exc.value.kind == "rate_limited"
+
+    def test_500_raises_upstream_unavailable(self):
+        with pytest.raises(UpstreamUnavailableError) as exc:
+            raise_for_status(500, "boom")
+        assert exc.value.kind == "upstream_unavailable"
+
+    def test_504_raises_timeout(self):
+        with pytest.raises(TimeoutError) as exc:
+            raise_for_status(504, "took too long")
+        assert exc.value.kind == "timeout"
+
+    def test_explicit_wire_kind_wins_over_status_mapping(self):
+        with pytest.raises(UnsupportedVersionError) as exc:
+            raise_for_status(
+                400,
+                "Unsupported API version",
+                {"kind": "unsupported_version", "code": "platform.api.unsupported_version"},
+            )
+        assert exc.value.kind == "unsupported_version"
+
+    def test_stash_code_dispatches_to_stash_subclass(self):
+        with pytest.raises(StashBookmarkArtifactNotFound) as exc:
+            raise_for_status(404, "bookmark gone", {"code": "stash.bookmark.artifact_not_found"})
+        assert isinstance(exc.value, NotFoundError)
+        assert exc.value.kind == "not_found"
+
+
+class TestDominusErrorKind:
+    """DominusError base class carries kind and exposes it in to_dict."""
+
+    def test_default_kind_is_internal(self):
+        err = DominusError("generic")
+        assert err.kind == "internal"
+
+    def test_explicit_kind_overrides_default(self):
+        err = DominusError("custom", kind="timeout")
+        assert err.kind == "timeout"
+
+    def test_to_dict_includes_kind(self):
+        err = UnauthorizedError("nope")
+        d = err.to_dict()
+        assert d["kind"] == "unauthorized"
+
+    def test_to_dict_emits_canonical_wire_fields(self):
+        err = NotFoundError(
+            "Missing resource",
+            details={
+                "code": "authority.resource.not_found",
+                "request_id": "req-python-envelope-1",
+                "correlation_id": "corr-python-envelope-1",
+            },
+        )
+
+        envelope = err.to_dict()
+        assert {key: envelope.get(key) for key in (
+            "kind", "code", "message", "request_id", "correlation_id",
+            "retryable", "http_status", "envelope_version",
+        )} == {
+            "kind": "not_found",
+            "code": "authority.resource.not_found",
+            "message": "Missing resource",
+            "request_id": "req-python-envelope-1",
+            "correlation_id": "corr-python-envelope-1",
+            "retryable": False,
+            "http_status": 404,
+            "envelope_version": "1",
+        }

{dominus_sdk_python-9.0.5 → dominus_sdk_python-9.0.7}/tests/test_stash_artifact_facade.py

@@ -353,3 +353,72 @@ async def test_watch_invalid_webhook_url_raises_typed_exception(monkeypatch, sdk
 
     assert exc_info.value.code == "stash.watch.invalid_webhook_url"
     assert exc_info.value.endpoint == "/svc/stash/watch"
+
+
+@pytest.mark.asyncio
+async def test_register_kind_posts_backend(monkeypatch, sdk):
+    calls = []
+
+    async def fake_request(**kwargs):
+        calls.append(kwargs)
+        return {"kind": {"kind": "artifact", "backend": "artifact-v2"}}
+
+    monkeypatch.setattr(sdk, "_request", fake_request)
+
+    result = await sdk.stash.register_kind(
+        kind="artifact",
+        backend="artifact-v2",
+        is_sensitive=False,
+        description="versioned artifacts",
+    )
+
+    assert result == {"kind": "artifact", "backend": "artifact-v2"}
+    assert calls == [
+        {
+            "endpoint": "/svc/stash/kinds/register",
+            "body": {
+                "kind": "artifact",
+                "backend": "artifact-v2",
+                "is_sensitive": False,
+                "description": "versioned artifacts",
+            },
+            "use_gateway": True,
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_register_kind_omits_backend_when_unset(monkeypatch, sdk):
+    calls = []
+
+    async def fake_request(**kwargs):
+        calls.append(kwargs)
+        return {"kind": {"kind": "document"}}
+
+    monkeypatch.setattr(sdk, "_request", fake_request)
+
+    result = await sdk.stash.register_kind(kind="document")
+
+    assert result == {"kind": "document"}
+    assert calls == [
+        {
+            "endpoint": "/svc/stash/kinds/register",
+            "body": {"kind": "document"},
+            "use_gateway": True,
+        }
+    ]
+
+
+def test_stash_backend_literal_covers_live_backends():
+    from typing import get_args
+
+    from dominus.namespaces.stash import StashBackend
+
+    assert set(get_args(StashBackend)) == {
+        "db-row",
+        "b2-versioned-bytes",
+        "b2-pointer-text",
+        "redis-ttl",
+        "artifact-v2",
+        "journal",
+    }