dominus-sdk-python 9.0.1__tar.gz → 9.0.2__tar.gz

{dominus_sdk_python-9.0.1 → dominus_sdk_python-9.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 9.0.1
+Version: 9.0.2
 Summary: Python SDK for the Dominus gateway-first platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License-Expression: LicenseRef-Proprietary
@@ -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.1`
+- Current package version: `9.0.2`
 
 ## Install
 
@@ -60,85 +60,59 @@ pip install dominus-sdk-python[dev]
 
 ## Quick Start
 
-```python
-import os
-from dominus import dominus
-
-os.environ["DOMINUS_TOKEN"] = "your-psk-token"
+Token-required hello using only the developer-stable catalog verbs. Set project
+scope with `DOMINUS_PROJECT` or CLI `select_project`. Other SDK namespaces exist
+for operators and advanced use; this path is the stable teaching surface.
 
-value = await dominus.secrets.get("DB_URL")
-users = await dominus.db.query("users", filters={"status": "active"})
-await dominus.redis.set("session:123", {"user": "john"}, ttl=3600)
+Set both values before the Python process imports the SDK singleton:
 
-run = await dominus.workflow.ensure(
-    workflow_recipe_ref="recipe://workflow-recipe-v1/report-cycle@v3",
-    subject="PCM47474562",
-    company="summit-radiology",
-)
+```bash
+export DOMINUS_TOKEN="your-psk-token"
+export DOMINUS_PROJECT="your-project-slug"
+```
 
-timeline = await dominus.authority.get_run_timeline(
-    run["run_id"],
-    since="2026-04-11T08:33:00Z",
-    until="2026-04-11T09:33:00Z",
-)
+```python
+import asyncio
+import base64
 
-timeline_archive = await dominus.authority.get_timeline_archive_status(
-    app_slug="carebridge-summit",
-    env="production",
-)
-archive_batch = await dominus.authority.archive_timelines(
-    max_hours=24,
-    max_runtime_ms=600000,
-)
-logs_archive = await dominus.logs.get_archive_status(
-    all_scopes=True,
-    include_buffer=True,
-    limit=5,
-)
-machine_logs = await dominus.logs.tail(
-    machine_id="mach-abc-123",
-    since="2026-04-11T08:33:00Z",
-    level="error",
-)
-policy = await dominus.platform.ensure_policy_decision(
-    {
-        "group": "dominus",
-        "repository": "carebridgesystems/dominus-platform-worker",
-    },
-    actor_context={"type": "user", "id": "operator-1"},
-)
-coder_run = await dominus.coder.ensure_run(
-    policy_decision_id=policy["data"]["policy_decision"]["decision_id"],
-    workflow_recipe_ref="recipe://workflow-recipe-v1/coder-feature@head",
-    repository="carebridgesystems/dominus-platform-worker",
-    executor="managed_anthropic",
-    instructions="Fix failing tests",
-    actor_context={"type": "user", "id": "operator-1"},
-)
+from dominus import dominus
 
-# Archive maintenance is explicit and dry-run first.
-verify = await dominus.authority.verify_timeline_archive_manifests(
-    since="2026-04-01T00:00:00Z",
-    until="2026-04-02T00:00:00Z",
-)
-prune = await dominus.logs.prune_archive_retention(
-    retention_days=90,
-    dry_run=True,
-)
-buffer_proof = await dominus.logs.dry_run_archive_buffer_maintenance(
-    sample_limit=100,
-)
-buffer_cleanup = await dominus.logs.run_archive_buffer_maintenance(
-    dry_run=False,
-    confirm="DELETE_ARCHIVE_BUFFER_RESIDUE",
-    salvage_missing_archive=True,
-    sample_limit=500,
-    max_archive_buckets=24,
-    batch_runs=5,
-    max_runtime_ms=8000,
-)
 
-schedules = await dominus.authority.list_schedules(all_scopes=True)
+async def main() -> None:
+    run = await dominus.workflow.ensure(
+        workflow_recipe_ref="recipe://workflow-recipe-v1/hello@v1",
+    )
+
+    await dominus.artifacts.store_v2(
+        group="your-group",
+        owner="your-project-slug",
+        environment="production",
+        kind="blob",
+        artifact_key="hello",
+        data=base64.b64encode(b"hello dominus").decode("ascii"),
+    )
+    artifact = await dominus.artifacts.retrieve_v2(
+        group="your-group",
+        owner="your-project-slug",
+        environment="production",
+        kind="blob",
+        artifact_key="hello",
+    )
+
+    stash_result = await dominus.stash.upsert(
+        kind="config",
+        scope={"env": "production"},
+        value={"greeting": "hello"},
+        item_key="hello",
+    )
+    await dominus.stash.get(stash_result["item"]["id"])
+
+    timeline = await dominus.authority.get_run_timeline(run["run_id"])
+    verdict = await dominus.authority.get_run_verdict(run["run_id"])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
 ```
 
 ## Stash Managed Tables

{dominus_sdk_python-9.0.1 → dominus_sdk_python-9.0.2}/README.md

@@ -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.1`
+- Current package version: `9.0.2`
 
 ## Install
 
@@ -27,85 +27,59 @@ pip install dominus-sdk-python[dev]
 
 ## Quick Start
 
-```python
-import os
-from dominus import dominus
-
-os.environ["DOMINUS_TOKEN"] = "your-psk-token"
+Token-required hello using only the developer-stable catalog verbs. Set project
+scope with `DOMINUS_PROJECT` or CLI `select_project`. Other SDK namespaces exist
+for operators and advanced use; this path is the stable teaching surface.
 
-value = await dominus.secrets.get("DB_URL")
-users = await dominus.db.query("users", filters={"status": "active"})
-await dominus.redis.set("session:123", {"user": "john"}, ttl=3600)
+Set both values before the Python process imports the SDK singleton:
 
-run = await dominus.workflow.ensure(
-    workflow_recipe_ref="recipe://workflow-recipe-v1/report-cycle@v3",
-    subject="PCM47474562",
-    company="summit-radiology",
-)
+```bash
+export DOMINUS_TOKEN="your-psk-token"
+export DOMINUS_PROJECT="your-project-slug"
+```
 
-timeline = await dominus.authority.get_run_timeline(
-    run["run_id"],
-    since="2026-04-11T08:33:00Z",
-    until="2026-04-11T09:33:00Z",
-)
+```python
+import asyncio
+import base64
 
-timeline_archive = await dominus.authority.get_timeline_archive_status(
-    app_slug="carebridge-summit",
-    env="production",
-)
-archive_batch = await dominus.authority.archive_timelines(
-    max_hours=24,
-    max_runtime_ms=600000,
-)
-logs_archive = await dominus.logs.get_archive_status(
-    all_scopes=True,
-    include_buffer=True,
-    limit=5,
-)
-machine_logs = await dominus.logs.tail(
-    machine_id="mach-abc-123",
-    since="2026-04-11T08:33:00Z",
-    level="error",
-)
-policy = await dominus.platform.ensure_policy_decision(
-    {
-        "group": "dominus",
-        "repository": "carebridgesystems/dominus-platform-worker",
-    },
-    actor_context={"type": "user", "id": "operator-1"},
-)
-coder_run = await dominus.coder.ensure_run(
-    policy_decision_id=policy["data"]["policy_decision"]["decision_id"],
-    workflow_recipe_ref="recipe://workflow-recipe-v1/coder-feature@head",
-    repository="carebridgesystems/dominus-platform-worker",
-    executor="managed_anthropic",
-    instructions="Fix failing tests",
-    actor_context={"type": "user", "id": "operator-1"},
-)
+from dominus import dominus
 
-# Archive maintenance is explicit and dry-run first.
-verify = await dominus.authority.verify_timeline_archive_manifests(
-    since="2026-04-01T00:00:00Z",
-    until="2026-04-02T00:00:00Z",
-)
-prune = await dominus.logs.prune_archive_retention(
-    retention_days=90,
-    dry_run=True,
-)
-buffer_proof = await dominus.logs.dry_run_archive_buffer_maintenance(
-    sample_limit=100,
-)
-buffer_cleanup = await dominus.logs.run_archive_buffer_maintenance(
-    dry_run=False,
-    confirm="DELETE_ARCHIVE_BUFFER_RESIDUE",
-    salvage_missing_archive=True,
-    sample_limit=500,
-    max_archive_buckets=24,
-    batch_runs=5,
-    max_runtime_ms=8000,
-)
 
-schedules = await dominus.authority.list_schedules(all_scopes=True)
+async def main() -> None:
+    run = await dominus.workflow.ensure(
+        workflow_recipe_ref="recipe://workflow-recipe-v1/hello@v1",
+    )
+
+    await dominus.artifacts.store_v2(
+        group="your-group",
+        owner="your-project-slug",
+        environment="production",
+        kind="blob",
+        artifact_key="hello",
+        data=base64.b64encode(b"hello dominus").decode("ascii"),
+    )
+    artifact = await dominus.artifacts.retrieve_v2(
+        group="your-group",
+        owner="your-project-slug",
+        environment="production",
+        kind="blob",
+        artifact_key="hello",
+    )
+
+    stash_result = await dominus.stash.upsert(
+        kind="config",
+        scope={"env": "production"},
+        value={"greeting": "hello"},
+        item_key="hello",
+    )
+    await dominus.stash.get(stash_result["item"]["id"])
+
+    timeline = await dominus.authority.get_run_timeline(run["run_id"])
+    verdict = await dominus.authority.get_run_verdict(run["run_id"])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
 ```
 
 ## Stash Managed Tables

{dominus_sdk_python-9.0.1 → dominus_sdk_python-9.0.2}/dominus/__init__.py

@@ -178,7 +178,7 @@ from .errors import (
     TimeoutError as DominusTimeoutError,
 )
 
-__version__ = "9.0.1"
+__version__ = "9.0.2"
 __all__ = [
     # Main SDK instance
     "dominus",

{dominus_sdk_python-9.0.1 → dominus_sdk_python-9.0.2}/dominus_sdk_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 9.0.1
+Version: 9.0.2
 Summary: Python SDK for the Dominus gateway-first platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License-Expression: LicenseRef-Proprietary
@@ -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.1`
+- Current package version: `9.0.2`
 
 ## Install
 
@@ -60,85 +60,59 @@ pip install dominus-sdk-python[dev]
 
 ## Quick Start
 
-```python
-import os
-from dominus import dominus
-
-os.environ["DOMINUS_TOKEN"] = "your-psk-token"
+Token-required hello using only the developer-stable catalog verbs. Set project
+scope with `DOMINUS_PROJECT` or CLI `select_project`. Other SDK namespaces exist
+for operators and advanced use; this path is the stable teaching surface.
 
-value = await dominus.secrets.get("DB_URL")
-users = await dominus.db.query("users", filters={"status": "active"})
-await dominus.redis.set("session:123", {"user": "john"}, ttl=3600)
+Set both values before the Python process imports the SDK singleton:
 
-run = await dominus.workflow.ensure(
-    workflow_recipe_ref="recipe://workflow-recipe-v1/report-cycle@v3",
-    subject="PCM47474562",
-    company="summit-radiology",
-)
+```bash
+export DOMINUS_TOKEN="your-psk-token"
+export DOMINUS_PROJECT="your-project-slug"
+```
 
-timeline = await dominus.authority.get_run_timeline(
-    run["run_id"],
-    since="2026-04-11T08:33:00Z",
-    until="2026-04-11T09:33:00Z",
-)
+```python
+import asyncio
+import base64
 
-timeline_archive = await dominus.authority.get_timeline_archive_status(
-    app_slug="carebridge-summit",
-    env="production",
-)
-archive_batch = await dominus.authority.archive_timelines(
-    max_hours=24,
-    max_runtime_ms=600000,
-)
-logs_archive = await dominus.logs.get_archive_status(
-    all_scopes=True,
-    include_buffer=True,
-    limit=5,
-)
-machine_logs = await dominus.logs.tail(
-    machine_id="mach-abc-123",
-    since="2026-04-11T08:33:00Z",
-    level="error",
-)
-policy = await dominus.platform.ensure_policy_decision(
-    {
-        "group": "dominus",
-        "repository": "carebridgesystems/dominus-platform-worker",
-    },
-    actor_context={"type": "user", "id": "operator-1"},
-)
-coder_run = await dominus.coder.ensure_run(
-    policy_decision_id=policy["data"]["policy_decision"]["decision_id"],
-    workflow_recipe_ref="recipe://workflow-recipe-v1/coder-feature@head",
-    repository="carebridgesystems/dominus-platform-worker",
-    executor="managed_anthropic",
-    instructions="Fix failing tests",
-    actor_context={"type": "user", "id": "operator-1"},
-)
+from dominus import dominus
 
-# Archive maintenance is explicit and dry-run first.
-verify = await dominus.authority.verify_timeline_archive_manifests(
-    since="2026-04-01T00:00:00Z",
-    until="2026-04-02T00:00:00Z",
-)
-prune = await dominus.logs.prune_archive_retention(
-    retention_days=90,
-    dry_run=True,
-)
-buffer_proof = await dominus.logs.dry_run_archive_buffer_maintenance(
-    sample_limit=100,
-)
-buffer_cleanup = await dominus.logs.run_archive_buffer_maintenance(
-    dry_run=False,
-    confirm="DELETE_ARCHIVE_BUFFER_RESIDUE",
-    salvage_missing_archive=True,
-    sample_limit=500,
-    max_archive_buckets=24,
-    batch_runs=5,
-    max_runtime_ms=8000,
-)
 
-schedules = await dominus.authority.list_schedules(all_scopes=True)
+async def main() -> None:
+    run = await dominus.workflow.ensure(
+        workflow_recipe_ref="recipe://workflow-recipe-v1/hello@v1",
+    )
+
+    await dominus.artifacts.store_v2(
+        group="your-group",
+        owner="your-project-slug",
+        environment="production",
+        kind="blob",
+        artifact_key="hello",
+        data=base64.b64encode(b"hello dominus").decode("ascii"),
+    )
+    artifact = await dominus.artifacts.retrieve_v2(
+        group="your-group",
+        owner="your-project-slug",
+        environment="production",
+        kind="blob",
+        artifact_key="hello",
+    )
+
+    stash_result = await dominus.stash.upsert(
+        kind="config",
+        scope={"env": "production"},
+        value={"greeting": "hello"},
+        item_key="hello",
+    )
+    await dominus.stash.get(stash_result["item"]["id"])
+
+    timeline = await dominus.authority.get_run_timeline(run["run_id"])
+    verdict = await dominus.authority.get_run_verdict(run["run_id"])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
 ```
 
 ## Stash Managed Tables

{dominus_sdk_python-9.0.1 → dominus_sdk_python-9.0.2}/dominus_sdk_python.egg-info/SOURCES.txt

@@ -62,6 +62,7 @@ tests/test_platform_coder_namespaces.py
 tests/test_provisioning_parity.py
 tests/test_public_exports.py
 tests/test_publisher_namespace.py
+tests/test_readme_quickstart_catalog.py
 tests/test_recipes_namespace.py
 tests/test_recipes_stash_routing.py
 tests/test_secrets_presence_contract.py

{dominus_sdk_python-9.0.1 → dominus_sdk_python-9.0.2}/pyproject.toml

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

dominus_sdk_python-9.0.2/tests/test_readme_quickstart_catalog.py

@@ -0,0 +1,128 @@
+"""Executable contract for the README developer-stable Quick Start."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import sys
+import textwrap
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+README = ROOT / "README.md"
+
+SDK_PYTHON_CATALOG = frozenset(
+    {
+        "workflow.ensure",
+        "artifacts.store_v2",
+        "artifacts.retrieve_v2",
+        "stash.upsert",
+        "stash.get",
+        "authority.get_run_timeline",
+        "authority.get_run_verdict",
+    }
+)
+
+FORBIDDEN = re.compile(r"summit|carebridge|PCM47474562|report-cycle", re.IGNORECASE)
+
+
+def _quick_start_section(readme: str) -> str:
+    start = readme.index("## Quick Start")
+    rest = readme[start:]
+    next_heading = rest.find("\n## ", len("## Quick Start"))
+    return rest if next_heading < 0 else rest[:next_heading]
+
+
+def _fenced(section: str, language: str) -> tuple[int, str]:
+    marker = f"```{language}\n"
+    start = section.index(marker)
+    body_start = start + len(marker)
+    end = section.index("```", body_start)
+    return start, section[body_start:end]
+
+
+def test_quick_start_scope_precedes_import_and_methods_match_catalog() -> None:
+    section = _quick_start_section(README.read_text(encoding="utf-8"))
+    shell_index, shell = _fenced(section, "bash")
+    python_index, body = _fenced(section, "python")
+
+    assert shell_index < python_index
+    assert 'export DOMINUS_TOKEN="your-psk-token"' in shell
+    assert 'export DOMINUS_PROJECT="your-project-slug"' in shell
+    assert "os.environ" not in body
+    assert "from dominus import dominus" in body
+    assert not FORBIDDEN.search(body), "Quick Start still has CareBridge-shaped nouns"
+
+    found = set(re.findall(r"\bdominus\.([a-z0-9_]+)\.([a-z0-9_]+)\b", body))
+    identifiers = {f"{namespace}.{method}" for namespace, method in found}
+    assert identifiers == SDK_PYTHON_CATALOG
+
+
+def test_quick_start_executes_in_fresh_process_with_live_transport_shapes() -> None:
+    child = textwrap.dedent(
+        r'''
+        import asyncio
+        import base64
+        import sys
+        from pathlib import Path
+
+        readme = Path(sys.argv[1]).read_text(encoding="utf-8")
+        section = readme[readme.index("## Quick Start"):]
+        marker = "```python\n"
+        start = section.index(marker) + len(marker)
+        body = section[start:section.index("```", start)]
+
+        from dominus import dominus
+
+        asyncio.run(dominus._ensure_ready())
+        calls = []
+
+        async def fake_request(**kwargs):
+            calls.append(kwargs)
+            endpoint = kwargs["endpoint"]
+            if endpoint == "/api/authority/runs/ensure":
+                return {"run_id": "run-1"}
+            if endpoint == "/svc/stash/items/upsert":
+                return {"item": {"id": "stash-1"}, "scope_origin": "own"}
+            if endpoint == "/svc/stash/items/get":
+                return {"item": {"id": "stash-1"}}
+            return {}
+
+        dominus._request = fake_request
+        exec(compile(body, "README.md#quick-start", "exec"), {"__name__": "__main__"})
+
+        endpoints = [call["endpoint"] for call in calls]
+        assert endpoints == [
+            "/api/authority/runs/ensure",
+            "/api/artifact/v2/store",
+            "/api/artifact/v2/retrieve",
+            "/svc/stash/items/upsert",
+            "/svc/stash/items/get",
+            "/api/authority/runs/run-1/timeline",
+            "/api/authority/runs/run-1/verdict",
+        ], endpoints
+        assert calls[0]["body"]["workflow_recipe_ref"] == "recipe://workflow-recipe-v1/hello@v1"
+        assert calls[1]["body"]["data"] == base64.b64encode(b"hello dominus").decode("ascii")
+        assert base64.b64decode(calls[1]["body"]["data"], validate=True) == b"hello dominus"
+        assert calls[3]["body"] == {
+            "kind": "config",
+            "scope": {"env": "production"},
+            "value": {"greeting": "hello"},
+            "item_key": "hello",
+        }
+        assert calls[4]["body"] == {"id": "stash-1"}
+        '''
+    )
+    env = os.environ.copy()
+    env["DOMINUS_TOKEN"] = "a" * 64
+    env["DOMINUS_PROJECT"] = "your-project-slug"
+    result = subprocess.run(
+        [sys.executable, "-c", child, str(README)],
+        cwd=ROOT,
+        env=env,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    assert result.returncode == 0, f"stdout={result.stdout}\nstderr={result.stderr}"