dominus-sdk-python 7.0.0__tar.gz → 7.1.0__tar.gz

{dominus_sdk_python-7.0.0 → dominus_sdk_python-7.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 7.0.0
+Version: 7.1.0
 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-06-27-0849-agent-guide-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: `7.0.0`
+- Current package version: `7.1.0`
 
 ## Install
 
@@ -141,6 +141,54 @@ buffer_cleanup = await dominus.logs.run_archive_buffer_maintenance(
 schedules = await dominus.authority.list_schedules(all_scopes=True)
 ```
 
+## Stash Managed Tables
+
+`dominus.stash.tables` provides a typed client for small, scoped JSONB tables
+without exposing SQL. Every call requires `env`, `scope` (`self` or `group`),
+and `table`; self and group tables resolve to independent project and shared
+databases.
+
+```python
+spec = await dominus.stash.tables.define(
+    env="production",
+    scope="self",
+    table="jobs",
+    if_revision=0,
+    primary_key={"field": "id", "generate": "uuid"},
+    fields={
+        "id": {"type": "uuid", "required": True},
+        "status": {"type": "string", "required": True},
+        "priority": {"type": "integer"},
+    },
+)
+
+row = await dominus.stash.tables.put_row(
+    env="production",
+    scope="self",
+    table="jobs",
+    if_revision=0,
+    row={"status": "queued", "priority": 5},
+)
+
+page = await dominus.stash.tables.select(
+    env="production",
+    scope="self",
+    table="jobs",
+    where={
+        "or": [
+            {"field": "status", "op": "eq", "value": "queued"},
+            {"field": "priority", "op": "gte", "value": 5},
+        ]
+    },
+    page_size=50,
+)
+```
+
+Use `if_revision` for table definitions and single-row put/delete compare-and-
+swap. `update_where` instead requires `if_spec_revision` and `max_affected`.
+Cursors are opaque keyset tokens. `delete_row` is a hard delete and returns a
+durable mutation receipt; there is no soft-delete or restore lifecycle.
+
 ## Browser Automation
 
 `dominus.browser` exposes the first-class Dominus browser automation primitive through authenticated gateway routes under `/svc/browser/*`. SDK methods use `/api/browser/*` internally with gateway routing enabled; worker-local routes remain `/health` and `/runs/*`.
@@ -230,7 +278,7 @@ JWT and selected scope headers directly through Gateway.
 | `platform` | Platform Worker | Group/repository policy decisions with actor attribution |
 | `coder` | Coder Runtime | Policy-bound Coder run lifecycle with workflow/pipeline recipe launch sources |
 | `publisher` | Publisher | Release/channel/signing build and artifact operations |
-| `stash` | Stash | Stash items, kinds, bookmarks, watches, artifact facade |
+| `stash` | Stash | Items, managed tables, kinds, bookmarks, watches, artifact facade |
 | `recipes` | Recipe Worker | Recipe type registry, publish, validate, get/list |
 | `fastapi` | Local decorators | `@jwt`, `@psk`, `@scopes(...)` |
 

{dominus_sdk_python-7.0.0 → dominus_sdk_python-7.1.0}/README.md

@@ -15,7 +15,7 @@ cleanup audit is `docs/janitor/2026-06-27-0849-agent-guide-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: `7.0.0`
+- Current package version: `7.1.0`
 
 ## Install
 
@@ -108,6 +108,54 @@ buffer_cleanup = await dominus.logs.run_archive_buffer_maintenance(
 schedules = await dominus.authority.list_schedules(all_scopes=True)
 ```
 
+## Stash Managed Tables
+
+`dominus.stash.tables` provides a typed client for small, scoped JSONB tables
+without exposing SQL. Every call requires `env`, `scope` (`self` or `group`),
+and `table`; self and group tables resolve to independent project and shared
+databases.
+
+```python
+spec = await dominus.stash.tables.define(
+    env="production",
+    scope="self",
+    table="jobs",
+    if_revision=0,
+    primary_key={"field": "id", "generate": "uuid"},
+    fields={
+        "id": {"type": "uuid", "required": True},
+        "status": {"type": "string", "required": True},
+        "priority": {"type": "integer"},
+    },
+)
+
+row = await dominus.stash.tables.put_row(
+    env="production",
+    scope="self",
+    table="jobs",
+    if_revision=0,
+    row={"status": "queued", "priority": 5},
+)
+
+page = await dominus.stash.tables.select(
+    env="production",
+    scope="self",
+    table="jobs",
+    where={
+        "or": [
+            {"field": "status", "op": "eq", "value": "queued"},
+            {"field": "priority", "op": "gte", "value": 5},
+        ]
+    },
+    page_size=50,
+)
+```
+
+Use `if_revision` for table definitions and single-row put/delete compare-and-
+swap. `update_where` instead requires `if_spec_revision` and `max_affected`.
+Cursors are opaque keyset tokens. `delete_row` is a hard delete and returns a
+durable mutation receipt; there is no soft-delete or restore lifecycle.
+
 ## Browser Automation
 
 `dominus.browser` exposes the first-class Dominus browser automation primitive through authenticated gateway routes under `/svc/browser/*`. SDK methods use `/api/browser/*` internally with gateway routing enabled; worker-local routes remain `/health` and `/runs/*`.
@@ -197,7 +245,7 @@ JWT and selected scope headers directly through Gateway.
 | `platform` | Platform Worker | Group/repository policy decisions with actor attribution |
 | `coder` | Coder Runtime | Policy-bound Coder run lifecycle with workflow/pipeline recipe launch sources |
 | `publisher` | Publisher | Release/channel/signing build and artifact operations |
-| `stash` | Stash | Stash items, kinds, bookmarks, watches, artifact facade |
+| `stash` | Stash | Items, managed tables, kinds, bookmarks, watches, artifact facade |
 | `recipes` | Recipe Worker | Recipe type registry, publish, validate, get/list |
 | `fastapi` | Local decorators | `@jwt`, `@psk`, `@scopes(...)` |
 

{dominus_sdk_python-7.0.0 → dominus_sdk_python-7.1.0}/dominus/__init__.py

@@ -115,7 +115,7 @@ from .namespaces.warden import WardenNamespace
 from .namespaces.platform import PlatformNamespace
 from .namespaces.coder import CoderNamespace
 from .namespaces.publisher import PublisherNamespace
-from .namespaces.stash import StashNamespace
+from .namespaces.stash import StashNamespace, StashTablesNamespace
 
 # Export AI namespace for agent-runtime operations
 from .namespaces.ai import (
@@ -173,7 +173,7 @@ from .errors import (
     TimeoutError as DominusTimeoutError,
 )
 
-__version__ = "7.0.0"
+__version__ = "7.1.0"
 __all__ = [
     # Main SDK instance
     "dominus",
@@ -228,6 +228,7 @@ __all__ = [
     "CoderNamespace",
     "PublisherNamespace",
     "StashNamespace",
+    "StashTablesNamespace",
     # AI namespace for agent-runtime operations
     "AiNamespace",
     "RagSubNamespace",

{dominus_sdk_python-7.0.0 → dominus_sdk_python-7.1.0}/dominus/namespaces/__init__.py

@@ -22,7 +22,7 @@ from .warden import WardenNamespace
 from .platform import PlatformNamespace
 from .coder import CoderNamespace
 from .publisher import PublisherNamespace
-from .stash import StashNamespace
+from .stash import StashNamespace, StashTablesNamespace
 from .ai import (
     AiNamespace,
     RagSubNamespace,
@@ -56,6 +56,7 @@ __all__ = [
     "CoderNamespace",
     "PublisherNamespace",
     "StashNamespace",
+    "StashTablesNamespace",
     "AiNamespace",
     "RagSubNamespace",
     "ArtifactsSubNamespace",

{dominus_sdk_python-7.0.0 → dominus_sdk_python-7.1.0}/dominus/namespaces/stash.py

@@ -5,7 +5,17 @@ Routes through ``/svc/stash/*`` on the Dominus gateway. The stash worker
 stores items in each project's ``stash.*`` schema and transparently falls
 back to a designated shared project on read.
 """
-from typing import Any, Dict, List, Optional, TYPE_CHECKING
+from typing import (
+    Any,
+    Dict,
+    List,
+    Literal,
+    Mapping,
+    Optional,
+    TYPE_CHECKING,
+    TypedDict,
+    Union,
+)
 from urllib.parse import urlencode
 
 if TYPE_CHECKING:
@@ -14,11 +24,324 @@ if TYPE_CHECKING:
 BookmarkRef = Dict[str, Any]
 WatcherRef = Dict[str, Any]
 
+ManagedTableEnv = Literal["development", "staging", "production"]
+ManagedTableScope = Literal["self", "group"]
+ManagedTableFieldType = Literal[
+    "string",
+    "uuid",
+    "number",
+    "integer",
+    "boolean",
+    "timestamp",
+    "json",
+]
+ManagedTablePrimaryKeyGeneration = Literal["none", "uuid"]
+ManagedTableEnumValue = Union[str, int, float, bool]
+ManagedTableOperator = Literal[
+    "eq",
+    "ne",
+    "in",
+    "prefix",
+    "contains",
+    "is_null",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "between",
+    "before",
+    "after",
+]
+
+
+class _ManagedTableFieldOptional(TypedDict, total=False):
+    required: bool
+    nullable: bool
+    enum: List[ManagedTableEnumValue]
+    min_length: int
+    max_length: int
+    min: Union[int, float]
+    max: Union[int, float]
+
+
+class ManagedTableField(_ManagedTableFieldOptional):
+    type: ManagedTableFieldType
+
+
+class ManagedTablePrimaryKey(TypedDict):
+    field: str
+    generate: ManagedTablePrimaryKeyGeneration
+
+
+class ManagedTableSpec(TypedDict):
+    table: str
+    revision: int
+    primary_key: ManagedTablePrimaryKey
+    fields: Dict[str, ManagedTableField]
+    created_at: str
+    updated_at: str
+    scope: ManagedTableScope
+
+
+class ManagedTableRowView(TypedDict):
+    row_key: str
+    data: Dict[str, Any]
+    revision: int
+    schema_revision: int
+    stale_schema: bool
+    created_at: str
+    updated_at: str
+
+
+class ManagedTableRow(ManagedTableRowView):
+    table: str
+    scope: ManagedTableScope
+
+
+class _ManagedTablePredicateOptional(TypedDict, total=False):
+    value: Any
+
+
+class ManagedTablePredicate(_ManagedTablePredicateOptional):
+    field: str
+    op: ManagedTableOperator
+
+
+ManagedTableLeafAndGroup = TypedDict(
+    "ManagedTableLeafAndGroup",
+    {"and": List[ManagedTablePredicate]},
+)
+ManagedTableLeafOrGroup = TypedDict(
+    "ManagedTableLeafOrGroup",
+    {"or": List[ManagedTablePredicate]},
+)
+ManagedTableLeafGroup = Union[ManagedTableLeafAndGroup, ManagedTableLeafOrGroup]
+ManagedTableWhereClause = Union[ManagedTablePredicate, ManagedTableLeafGroup]
+ManagedTableAndGroup = TypedDict(
+    "ManagedTableAndGroup",
+    {"and": List[ManagedTableWhereClause]},
+)
+ManagedTableOrGroup = TypedDict(
+    "ManagedTableOrGroup",
+    {"or": List[ManagedTableWhereClause]},
+)
+ManagedTableWhere = Union[
+    List[ManagedTableWhereClause],
+    ManagedTableAndGroup,
+    ManagedTableOrGroup,
+]
+
+
+class ManagedTableOrderBy(TypedDict):
+    field: str
+    direction: Literal["asc", "desc"]
+
+
+class ManagedTableSelectResult(TypedDict):
+    rows: List[ManagedTableRowView]
+    next_cursor: Optional[str]
+    spec_revision: int
+    table: str
+    scope: ManagedTableScope
+
+
+class ManagedTableMutationReceipt(TypedDict):
+    mutation_id: str
+    created_at: str
+
+
+class _ManagedTableMutationRowOptional(TypedDict, total=False):
+    updated_at: str
+
+
+class ManagedTableMutationRow(_ManagedTableMutationRowOptional):
+    row_key: str
+    revision: int
+    schema_revision: int
+
+
+class ManagedTableUpdateResult(TypedDict):
+    matched_count: int
+    affected_count: int
+    rows: List[ManagedTableMutationRow]
+    receipt: ManagedTableMutationReceipt
+    table: str
+    scope: ManagedTableScope
+
+
+class ManagedTableDeleteResult(TypedDict):
+    deleted: Literal[True]
+    row_key: str
+    revision: int
+    schema_revision: int
+    receipt: ManagedTableMutationReceipt
+    table: str
+    scope: ManagedTableScope
+
 
 def _facade_query(*, env: str, kind: str, scope: str, key: str) -> str:
     return urlencode({"env": env, "kind": kind, "scope": scope, "key": key})
 
 
+class StashTablesNamespace:
+    """Typed client for Stash-managed JSONB tables."""
+
+    def __init__(self, client: "Dominus"):
+        self._client = client
+
+    async def define(
+        self,
+        *,
+        env: ManagedTableEnv,
+        scope: ManagedTableScope,
+        table: str,
+        if_revision: int,
+        primary_key: ManagedTablePrimaryKey,
+        fields: Mapping[str, ManagedTableField],
+    ) -> ManagedTableSpec:
+        """Create or revision-guard a managed table definition."""
+        return await self._client._request(
+            endpoint="/svc/stash/tables/define",
+            method="POST",
+            body={
+                "env": env,
+                "scope": scope,
+                "table": table,
+                "if_revision": if_revision,
+                "primary_key": dict(primary_key),
+                "fields": dict(fields),
+            },
+            use_gateway=True,
+        )
+
+    async def put_row(
+        self,
+        *,
+        env: ManagedTableEnv,
+        scope: ManagedTableScope,
+        table: str,
+        if_revision: int,
+        row: Mapping[str, Any],
+    ) -> ManagedTableRow:
+        """Create or fully replace one row under exact row revision CAS."""
+        return await self._client._request(
+            endpoint="/svc/stash/tables/put-row",
+            method="POST",
+            body={
+                "env": env,
+                "scope": scope,
+                "table": table,
+                "if_revision": if_revision,
+                "row": dict(row),
+            },
+            use_gateway=True,
+        )
+
+    async def get_row(
+        self,
+        *,
+        env: ManagedTableEnv,
+        scope: ManagedTableScope,
+        table: str,
+        key: Union[str, int],
+    ) -> ManagedTableRow:
+        """Read one managed-table row by its declared primary key."""
+        return await self._client._request(
+            endpoint="/svc/stash/tables/get-row",
+            method="POST",
+            body={
+                "env": env,
+                "scope": scope,
+                "table": table,
+                "key": key,
+            },
+            use_gateway=True,
+        )
+
+    async def select(
+        self,
+        *,
+        env: ManagedTableEnv,
+        scope: ManagedTableScope,
+        table: str,
+        where: Optional[ManagedTableWhere] = None,
+        order_by: Optional[ManagedTableOrderBy] = None,
+        page_size: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> ManagedTableSelectResult:
+        """Select one keyset page using the bounded managed-table grammar."""
+        body: Dict[str, Any] = {"env": env, "scope": scope, "table": table}
+        if where is not None:
+            body["where"] = where
+        if order_by is not None:
+            body["order_by"] = dict(order_by)
+        if page_size is not None:
+            body["page_size"] = page_size
+        if cursor is not None:
+            body["cursor"] = cursor
+        return await self._client._request(
+            endpoint="/svc/stash/tables/select",
+            method="POST",
+            body=body,
+            use_gateway=True,
+        )
+
+    async def update_where(
+        self,
+        *,
+        env: ManagedTableEnv,
+        scope: ManagedTableScope,
+        table: str,
+        where: ManagedTableWhere,
+        if_spec_revision: int,
+        max_affected: int,
+        set: Optional[Mapping[str, Any]] = None,
+        remove: Optional[List[str]] = None,
+    ) -> ManagedTableUpdateResult:
+        """Patch a bounded match set under exact active-spec revision CAS."""
+        body: Dict[str, Any] = {
+            "env": env,
+            "scope": scope,
+            "table": table,
+            "where": where,
+            "if_spec_revision": if_spec_revision,
+            "max_affected": max_affected,
+        }
+        if set is not None:
+            body["set"] = dict(set)
+        if remove is not None:
+            body["remove"] = list(remove)
+        return await self._client._request(
+            endpoint="/svc/stash/tables/update-where",
+            method="POST",
+            body=body,
+            use_gateway=True,
+        )
+
+    async def delete_row(
+        self,
+        *,
+        env: ManagedTableEnv,
+        scope: ManagedTableScope,
+        table: str,
+        key: Union[str, int],
+        if_revision: int,
+    ) -> ManagedTableDeleteResult:
+        """Hard-delete one row under exact row revision CAS."""
+        return await self._client._request(
+            endpoint="/svc/stash/tables/delete-row",
+            method="POST",
+            body={
+                "env": env,
+                "scope": scope,
+                "table": table,
+                "key": key,
+                "if_revision": if_revision,
+            },
+            use_gateway=True,
+        )
+
+
 class StashNamespace:
     """
     Stash worker namespace.
@@ -34,6 +357,7 @@ class StashNamespace:
 
     def __init__(self, client: "Dominus"):
         self._client = client
+        self.tables = StashTablesNamespace(client)
 
     async def upsert(
         self,

{dominus_sdk_python-7.0.0 → dominus_sdk_python-7.1.0}/dominus_sdk_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 7.0.0
+Version: 7.1.0
 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-06-27-0849-agent-guide-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: `7.0.0`
+- Current package version: `7.1.0`
 
 ## Install
 
@@ -141,6 +141,54 @@ buffer_cleanup = await dominus.logs.run_archive_buffer_maintenance(
 schedules = await dominus.authority.list_schedules(all_scopes=True)
 ```
 
+## Stash Managed Tables
+
+`dominus.stash.tables` provides a typed client for small, scoped JSONB tables
+without exposing SQL. Every call requires `env`, `scope` (`self` or `group`),
+and `table`; self and group tables resolve to independent project and shared
+databases.
+
+```python
+spec = await dominus.stash.tables.define(
+    env="production",
+    scope="self",
+    table="jobs",
+    if_revision=0,
+    primary_key={"field": "id", "generate": "uuid"},
+    fields={
+        "id": {"type": "uuid", "required": True},
+        "status": {"type": "string", "required": True},
+        "priority": {"type": "integer"},
+    },
+)
+
+row = await dominus.stash.tables.put_row(
+    env="production",
+    scope="self",
+    table="jobs",
+    if_revision=0,
+    row={"status": "queued", "priority": 5},
+)
+
+page = await dominus.stash.tables.select(
+    env="production",
+    scope="self",
+    table="jobs",
+    where={
+        "or": [
+            {"field": "status", "op": "eq", "value": "queued"},
+            {"field": "priority", "op": "gte", "value": 5},
+        ]
+    },
+    page_size=50,
+)
+```
+
+Use `if_revision` for table definitions and single-row put/delete compare-and-
+swap. `update_where` instead requires `if_spec_revision` and `max_affected`.
+Cursors are opaque keyset tokens. `delete_row` is a hard delete and returns a
+durable mutation receipt; there is no soft-delete or restore lifecycle.
+
 ## Browser Automation
 
 `dominus.browser` exposes the first-class Dominus browser automation primitive through authenticated gateway routes under `/svc/browser/*`. SDK methods use `/api/browser/*` internally with gateway routing enabled; worker-local routes remain `/health` and `/runs/*`.
@@ -230,7 +278,7 @@ JWT and selected scope headers directly through Gateway.
 | `platform` | Platform Worker | Group/repository policy decisions with actor attribution |
 | `coder` | Coder Runtime | Policy-bound Coder run lifecycle with workflow/pipeline recipe launch sources |
 | `publisher` | Publisher | Release/channel/signing build and artifact operations |
-| `stash` | Stash | Stash items, kinds, bookmarks, watches, artifact facade |
+| `stash` | Stash | Items, managed tables, kinds, bookmarks, watches, artifact facade |
 | `recipes` | Recipe Worker | Recipe type registry, publish, validate, get/list |
 | `fastapi` | Local decorators | `@jwt`, `@psk`, `@scopes(...)` |
 

{dominus_sdk_python-7.0.0 → dominus_sdk_python-7.1.0}/dominus_sdk_python.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ README.md
 pyproject.toml
 dominus/__init__.py
 dominus/errors.py
+dominus/py.typed
 dominus/start.py
 dominus/config/__init__.py
 dominus/config/endpoints.py
@@ -64,6 +65,7 @@ tests/test_publisher_namespace.py
 tests/test_recipes_namespace.py
 tests/test_recipes_stash_routing.py
 tests/test_stash_artifact_facade.py
+tests/test_stash_tables_namespace.py
 tests/test_transport_compat.py
 tests/test_workflow_lifecycle.py
 tests/test_workflow_refs.py

dominus_sdk_python-7.1.0/dominus_sdk_python.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

{dominus_sdk_python-7.0.0 → dominus_sdk_python-7.1.0}/pyproject.toml

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

{dominus_sdk_python-7.0.0 → dominus_sdk_python-7.1.0}/tests/test_namespace_barrel_exports.py

@@ -1,3 +1,5 @@
+from pathlib import Path
+
 import dominus
 import dominus.namespaces
 
@@ -24,3 +26,16 @@ def test_top_level_all_lists_stash_and_publisher():
 def test_namespaces_all_lists_stash_and_publisher():
     assert "StashNamespace" in dominus.namespaces.__all__
     assert "PublisherNamespace" in dominus.namespaces.__all__
+
+
+def test_stash_tables_namespace_is_exported_from_both_barrels():
+    from dominus import StashTablesNamespace as TopLevelStashTablesNamespace
+    from dominus.namespaces import StashTablesNamespace as NamespaceStashTablesNamespace
+
+    assert TopLevelStashTablesNamespace is NamespaceStashTablesNamespace
+    assert "StashTablesNamespace" in dominus.__all__
+    assert "StashTablesNamespace" in dominus.namespaces.__all__
+
+
+def test_package_includes_declared_pep561_marker():
+    assert Path(dominus.__file__).with_name("py.typed").is_file()

dominus_sdk_python-7.1.0/tests/test_stash_tables_namespace.py

@@ -0,0 +1,294 @@
+import pytest
+
+import dominus.start as start_module
+
+
+@pytest.fixture()
+def sdk(monkeypatch):
+    monkeypatch.setattr(start_module, "_VALIDATION_ERROR", None)
+    monkeypatch.setattr(start_module, "_TOKEN", "a" * 64)
+    monkeypatch.setattr(start_module, "_VALIDATED", False)
+    monkeypatch.setattr(start_module, "_BASE_URL", "https://gateway.example")
+    monkeypatch.setattr(start_module, "_GATEWAY_URL", "https://gateway.example")
+    return start_module.Dominus()
+
+
+@pytest.mark.asyncio
+async def test_define_managed_table_posts_exact_worker_body(monkeypatch, sdk):
+    calls = []
+
+    async def fake_request(**kwargs):
+        calls.append(kwargs)
+        return {"table": "jobs", "revision": 1, "scope": "self"}
+
+    monkeypatch.setattr(sdk, "_request", fake_request)
+
+    result = await sdk.stash.tables.define(
+        env="production",
+        scope="self",
+        table="jobs",
+        if_revision=0,
+        primary_key={"field": "id", "generate": "uuid"},
+        fields={
+            "id": {"type": "uuid", "required": True},
+            "status": {"type": "string", "required": True},
+        },
+    )
+
+    assert result == {"table": "jobs", "revision": 1, "scope": "self"}
+    assert calls == [
+        {
+            "endpoint": "/svc/stash/tables/define",
+            "method": "POST",
+            "body": {
+                "env": "production",
+                "scope": "self",
+                "table": "jobs",
+                "if_revision": 0,
+                "primary_key": {"field": "id", "generate": "uuid"},
+                "fields": {
+                    "id": {"type": "uuid", "required": True},
+                    "status": {"type": "string", "required": True},
+                },
+            },
+            "use_gateway": True,
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_put_row_uses_row_revision_cas(monkeypatch, sdk):
+    calls = []
+
+    async def fake_request(**kwargs):
+        calls.append(kwargs)
+        return {"row_key": "job-1", "revision": 3, "schema_revision": 2}
+
+    monkeypatch.setattr(sdk, "_request", fake_request)
+
+    result = await sdk.stash.tables.put_row(
+        env="staging",
+        scope="group",
+        table="jobs",
+        if_revision=2,
+        row={"id": "job-1", "status": "ready"},
+    )
+
+    assert result["revision"] == 3
+    assert calls == [
+        {
+            "endpoint": "/svc/stash/tables/put-row",
+            "method": "POST",
+            "body": {
+                "env": "staging",
+                "scope": "group",
+                "table": "jobs",
+                "if_revision": 2,
+                "row": {"id": "job-1", "status": "ready"},
+            },
+            "use_gateway": True,
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_get_row_posts_integer_key_without_revision(monkeypatch, sdk):
+    calls = []
+
+    async def fake_request(**kwargs):
+        calls.append(kwargs)
+        return {"row_key": "42", "data": {"id": 42}}
+
+    monkeypatch.setattr(sdk, "_request", fake_request)
+
+    result = await sdk.stash.tables.get_row(
+        env="development",
+        scope="self",
+        table="jobs",
+        key=42,
+    )
+
+    assert result["row_key"] == "42"
+    assert calls == [
+        {
+            "endpoint": "/svc/stash/tables/get-row",
+            "method": "POST",
+            "body": {
+                "env": "development",
+                "scope": "self",
+                "table": "jobs",
+                "key": 42,
+            },
+            "use_gateway": True,
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_select_omits_optional_query_fields_by_default(monkeypatch, sdk):
+    calls = []
+
+    async def fake_request(**kwargs):
+        calls.append(kwargs)
+        return {"rows": [], "next_cursor": None, "spec_revision": 1}
+
+    monkeypatch.setattr(sdk, "_request", fake_request)
+
+    result = await sdk.stash.tables.select(
+        env="production",
+        scope="self",
+        table="jobs",
+    )
+
+    assert result["next_cursor"] is None
+    assert calls == [
+        {
+            "endpoint": "/svc/stash/tables/select",
+            "method": "POST",
+            "body": {
+                "env": "production",
+                "scope": "self",
+                "table": "jobs",
+            },
+            "use_gateway": True,
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_select_passes_shallow_boolean_filter_and_opaque_cursor(monkeypatch, sdk):
+    calls = []
+
+    async def fake_request(**kwargs):
+        calls.append(kwargs)
+        return {"rows": [], "next_cursor": "next-token", "spec_revision": 4}
+
+    monkeypatch.setattr(sdk, "_request", fake_request)
+    where = {
+        "or": [
+            {"field": "status", "op": "eq", "value": "ready"},
+            {
+                "and": [
+                    {"field": "priority", "op": "gte", "value": 5},
+                    {"field": "enabled", "op": "eq", "value": True},
+                ]
+            },
+        ]
+    }
+
+    result = await sdk.stash.tables.select(
+        env="production",
+        scope="group",
+        table="jobs",
+        where=where,
+        order_by={"field": "priority", "direction": "desc"},
+        page_size=25,
+        cursor="opaque-token",
+    )
+
+    assert result["next_cursor"] == "next-token"
+    assert calls == [
+        {
+            "endpoint": "/svc/stash/tables/select",
+            "method": "POST",
+            "body": {
+                "env": "production",
+                "scope": "group",
+                "table": "jobs",
+                "where": where,
+                "order_by": {"field": "priority", "direction": "desc"},
+                "page_size": 25,
+                "cursor": "opaque-token",
+            },
+            "use_gateway": True,
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_update_where_uses_spec_revision_and_guard_limit(monkeypatch, sdk):
+    calls = []
+
+    async def fake_request(**kwargs):
+        calls.append(kwargs)
+        return {
+            "matched_count": 1,
+            "affected_count": 1,
+            "rows": [{"row_key": "job-1", "revision": 2, "schema_revision": 4}],
+            "receipt": {"mutation_id": "mutation-1", "created_at": "2026-07-15T12:00:00.000Z"},
+        }
+
+    monkeypatch.setattr(sdk, "_request", fake_request)
+    where = [{"field": "status", "op": "eq", "value": "queued"}]
+
+    result = await sdk.stash.tables.update_where(
+        env="production",
+        scope="group",
+        table="jobs",
+        where=where,
+        set={"status": "ready"},
+        remove=["note"],
+        if_spec_revision=4,
+        max_affected=10,
+    )
+
+    assert result["receipt"]["mutation_id"] == "mutation-1"
+    assert calls == [
+        {
+            "endpoint": "/svc/stash/tables/update-where",
+            "method": "POST",
+            "body": {
+                "env": "production",
+                "scope": "group",
+                "table": "jobs",
+                "where": where,
+                "set": {"status": "ready"},
+                "remove": ["note"],
+                "if_spec_revision": 4,
+                "max_affected": 10,
+            },
+            "use_gateway": True,
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_delete_row_uses_row_revision_and_returns_hard_delete_receipt(monkeypatch, sdk):
+    calls = []
+
+    async def fake_request(**kwargs):
+        calls.append(kwargs)
+        return {
+            "deleted": True,
+            "row_key": "job-1",
+            "revision": 3,
+            "schema_revision": 4,
+            "receipt": {"mutation_id": "delete-1", "created_at": "2026-07-15T12:00:00.000Z"},
+        }
+
+    monkeypatch.setattr(sdk, "_request", fake_request)
+
+    result = await sdk.stash.tables.delete_row(
+        env="production",
+        scope="self",
+        table="jobs",
+        key="job-1",
+        if_revision=3,
+    )
+
+    assert result["deleted"] is True
+    assert result["receipt"]["mutation_id"] == "delete-1"
+    assert calls == [
+        {
+            "endpoint": "/svc/stash/tables/delete-row",
+            "method": "POST",
+            "body": {
+                "env": "production",
+                "scope": "self",
+                "table": "jobs",
+                "key": "job-1",
+                "if_revision": 3,
+            },
+            "use_gateway": True,
+        }
+    ]