volcano-sdk-python 0.10.0__tar.gz → 0.10.2__tar.gz

volcano_sdk_python-0.10.2/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @Kong/team-volcano

volcano_sdk_python-0.10.2/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## Change
+
+Describe the user-visible result and the reason for the change.
+
+## Verification
+
+List the checks run and their results.
+
+## Cross-language impact
+
+Classify this change: public facade / wire contract / shared behavior / native behavior / public examples / none.
+
+- Requirement IDs and affected behavior:
+- JavaScript / Python / Ruby companion PRs, or why each is unaffected:
+- Canonical scenarios, bindings and active/staged copies:
+- Public examples updated in each affected language:
+- Native checks and shared acceptance evidence (with tested revisions):
+
+Follow the [contributor workflow](https://github.com/Kong/volcano-sdk-python/blob/main/CONTRIBUTING.md). Tooling checks and dry runs
+are not live acceptance. Record a reason for each item that does not apply.

volcano_sdk_python-0.10.2/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  workflow_call:
+  pull_request:
+  merge_group:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+permissions: {}
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.14"]
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - run: bash .github/scripts/actionlint.sh
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with:
+          version: "0.12.17"
+      - run: uv sync --locked
+      - name: Run SDK quality checks
+        run: uv run --locked poe quality
+      - name: Preserve runtime coverage
+        if: ${{ always() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: coverage-for-python-${{ matrix.python-version }}
+          path: reports/coverage.json
+          if-no-files-found: error
+      - name: Preserve test failures and property seeds
+        if: ${{ failure() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: property-failures-python-${{ matrix.python-version }}
+          path: |
+            reports/unit.xml
+            reports/coverage-unit.xml
+            reports/hypothesis/seed.txt
+          if-no-files-found: ignore
+
+  quality:
+    name: Quality Gate
+    if: ${{ always() }}
+    needs: [test]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Require every mandatory job to succeed
+        env:
+          RESULTS: ${{ toJSON(needs.*.result) }}
+        run: jq -e 'length == 1 and all(. == "success")' <<< "$RESULTS"

{volcano_sdk_python-0.10.0 → volcano_sdk_python-0.10.2}/.github/workflows/publish.yml

@@ -44,6 +44,9 @@ jobs:
     needs: [validate, check]
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    env:
+      # Only the hash-checked build task may build the project in this job.
+      UV_NO_SYNC: 'true'
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
@@ -52,8 +55,10 @@ jobs:
         with:
           python-version: '3.14'
       - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
-      - run: uv sync --frozen
-      - run: uv run python -m build
+        with:
+          version: "0.12.17"
+      - run: uv sync --locked --no-install-project --no-build
+      - run: uv run --no-sync poe build
       - name: Check package identity and release version
         env:
           RELEASE_TAG: ${{ github.event.release.tag_name }}

volcano_sdk_python-0.10.2/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.10.2"
+}

volcano_sdk_python-0.10.2/AGENTS.md

@@ -0,0 +1,14 @@
+# SDK quality
+
+- Research upstream tools before adding enforcement. Keep rules in native tool
+  configuration and orchestration in standard tasks. Add custom checks only
+  for requirements established tools cannot express; document that gap.
+- Fix failures rather than weakening rules or excluding code. Narrow exceptions
+  for verified tool limitations require human approval and an exact record in
+  `maintainers/quality-exceptions.json`. Never approve quality-policy changes
+  on a human reviewer's behalf.
+- Keep reviewer and repository-administration credentials outside ordinary
+  automation.
+- Preserve shared behavioral scenarios and coordinate contract changes with
+  `Kong/volcano-hosting` and the other SDKs.
+- Keep maintainer guidance under `maintainers/`; `docs/` is published.

{volcano_sdk_python-0.10.0 → volcano_sdk_python-0.10.2}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.10.2](https://github.com/Kong/volcano-sdk-python/compare/v0.10.1...v0.10.2) (2026-09-22)
+
+
+### Bug Fixes
+
+* retain checked durable invocation types ([#259](https://github.com/Kong/volcano-sdk-python/issues/259)) ([440da83](https://github.com/Kong/volcano-sdk-python/commit/440da8317a4255f5af1aa634e2cf90b23ec2369d))
+
+## [0.10.1](https://github.com/Kong/volcano-sdk-python/compare/v0.10.0...v0.10.1) (2026-09-22)
+
+
+### Bug Fixes
+
+* validate log containers before generated normalization ([#228](https://github.com/Kong/volcano-sdk-python/issues/228)) ([9ddf005](https://github.com/Kong/volcano-sdk-python/commit/9ddf005f791611ebe75c64c9d34dfa94e176eab6))
+
 ## [0.10.0](https://github.com/Kong/volcano-sdk-python/compare/v0.9.4...v0.10.0) (2026-09-19)
 
 

volcano_sdk_python-0.10.2/CONTRIBUTING.md

@@ -0,0 +1,113 @@
+# Contributing to the Python SDK
+
+Use Python 3.11 or newer and `uv`. CI covers Python 3.11 and 3.14.
+
+## Verify a change
+
+```shell
+uv sync --locked
+uv run --locked poe quality
+```
+
+The tasks in `pyproject.toml` run the same checks locally and in CI. Run
+`uv run --locked poe` to list them, or invoke a tool directly, such as
+`uv run --locked ruff check .`. Tool settings belong in their native
+configuration sections so editors and command-line checks agree.
+
+Use established upstream tools before writing custom enforcement. Research
+current documentation when choosing an approach. Keep repository-specific
+checks only where a standard tool cannot express the required invariant.
+
+Pytest's [strict mode](https://docs.pytest.org/en/stable/explanation/goodpractices.html#strict-mode)
+rejects unknown settings and markers, duplicate parameter IDs, and unexpected
+xfail passes. Empty parameter sets fail during collection. Keep pytest pinned
+so new strictness options enter through a reviewed dependency update.
+
+Write asyncio behavior tests as `async def` tests. Pytest-asyncio gives each test
+its own event loop with debug checks enabled. Use explicit events or barriers
+for ordering; keep direct loop management for tests of loop lifecycle itself.
+
+After updating `openapi/openapi.yaml` from Hosting's public bundle, regenerate
+the internal client with `uv run python scripts/generate_openapi.py`.
+The dry run checks active and staged phrase bindings without creating fixtures
+or exercising live behavior. Keep generated code inside `src/volcano_sdk/_generated`.
+
+## Coordinate SDK changes
+
+Follow the [Hosting SDK contract workflow](https://github.com/Kong/volcano-hosting/blob/main/.agents/skills/sdk-contract-coordination/SKILL.md).
+Hosting owns the wire contract in `api/openapi.yaml` and the behavioral contract
+in `tests/sdk-contract`. JavaScript, Python, and Ruby expose that behavior through
+handwritten, idiomatic facades; generated transport code stays internal.
+
+Classify the impact in the PR before changing the contract:
+
+| Change                                    | Required updates                                                                                                                                                               |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public facade or SDK-facing wire contract | Audit all three SDKs; update each affected facade, native tests, and public language examples. Regenerate internal clients when their wire snapshot changes.                   |
+| Shared behavior                           | Update the canonical requirement ID and Gherkin scenario in Hosting, every affected language binding, checked-in feature copies, native tests, and equivalent public examples. |
+| Native behavior                           | Add native regression coverage and document language-specific behavior. Update shared scenarios only if the shared behavior changes.                                           |
+| Public examples                           | Update equivalent examples in every affected language and verify their public API calls.                                                                                       |
+
+Explain unaffected languages and intentional language-specific differences;
+method presence alone is not evidence of equivalent behavior. Start behavior
+fixes with a failing native test. Never edit generated clients by hand.
+
+Use the same branch name across affected repositories and link the companion
+PRs. Keep each PR focused and use Conventional Commits. Obtain clean code and
+security reviews and passing required checks on the final commit before merge.
+Hosting changes also require human approval.
+
+### Roll out shared scenarios
+
+Before merging SDK code, prove it remains compatible with the currently deployed
+Hosting contract. Staging Gherkin does not keep runtime code dormant, and the
+existing release automation can publish a main-derived package. If new server
+support is required, first land a backward-compatible Hosting prerequisite or
+keep the SDK PR in draft until an explicitly reviewed release/rollout plan is in
+place. Do not merge an incompatible implementation merely because its scenario
+is staged.
+
+1. Change the canonical scenario in Hosting once. Copy its bytes into each SDK
+   and implement its native binding.
+2. Stage new scenarios under `features/staged` while Hosting main still uses the
+   older contract. Do not activate scenarios ahead of Hosting.
+3. Merge the required SDK changes before validating and merging the coordinated
+   Hosting PR. Record the Hosting and SDK revisions used by acceptance.
+4. After Hosting merges, promote those unchanged files into `features/contract`
+   and run the default binding-discovery checks. Do not keep duplicate active
+   and staged copies.
+
+Hosting CI checks out each SDK's latest `main` and records the actual tested
+SHAs. Do not introduce a checked-in pin manifest or assume a rerun uses the same
+SDK revisions. Generate and verify each SDK against its own OpenAPI snapshot;
+compatibility with the server is established by integration tests.
+
+When the wire contract changes, first build Hosting's public bundle with
+`scripts/ci/openapi-bundle.sh <output-directory>` and update the affected SDK's
+`openapi/openapi.yaml` from that bundle. Then run its generator and freshness
+check. The generator reads the vendored snapshot; it does not update that
+snapshot from Hosting. Do not use snapshot equality as a server compatibility
+gate.
+
+From a Hosting checkout, verify shared tooling and copies before review:
+
+```shell
+npm ci --prefix tests/sdk-contract --ignore-scripts
+npm test --prefix tests/sdk-contract
+bash scripts/ci/run-sdk-contract-tests_test.sh
+bash scripts/ci/run-sdk-contract-tests.sh --validate-features-only \
+  /path/to/volcano-sdk-js /path/to/volcano-sdk-python /path/to/volcano-sdk-ruby
+```
+
+Without `--validate-features-only`, the runner creates and deletes fixtures.
+Use an approved disposable environment for live runs; staging and production
+require explicit authorization. Ordinary Cloud E2E remains post-merge. Do not
+infer live acceptance from tooling checks or a nonblocking staging result.
+
+### Documentation and release boundaries
+
+`docs/` is published to the developer documentation site. Put user-facing
+examples there and maintainer instructions in this file or beside the code.
+Keep equivalent language examples current in the same coordinated change.
+Package checks validate artifacts; they do not authorize publication. Treat
+registry-installed quickstarts and release approval as separate release work.

{volcano_sdk_python-0.10.0 → volcano_sdk_python-0.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: volcano-sdk-python
-Version: 0.10.0
+Version: 0.10.2
 Summary: Official Python SDK for Volcano
 Project-URL: Homepage, https://volcano.dev
 Project-URL: Repository, https://github.com/Kong/volcano-sdk-python
@@ -16,6 +16,7 @@ Requires-Python: >=3.11
 Requires-Dist: attrs>=26.1.0
 Requires-Dist: centrifuge-python<0.7.0,>=0.6.0
 Requires-Dist: httpx<0.29.0,>=0.28.1
+Requires-Dist: typing-extensions>=4.4.0
 Provides-Extra: durable
 Requires-Dist: aws-durable-execution-sdk-python<3.0.0,>=2.0.0; extra == 'durable'
 Description-Content-Type: text/markdown
@@ -338,6 +339,10 @@ item when the execution resumes is not guaranteed, so a handler that branched on
 one would take a different path on the replay. `completion_reason` is how to tell
 why the batch ended.
 
+`@durable` accepts typed handlers. The decorated function is the platform
+entrypoint: its arguments and result are invocation envelopes, typed as `object`,
+rather than the handler's application input and result.
+
 Durable operations are synchronous here — there is no `await`, and a step's own
 function is handed a scope carrying `log` and `attempt`. A wait is held by the
 platform rather than by your code, so an execution suspended for an hour costs
@@ -974,18 +979,20 @@ The generated parsed-body-only shortcuts are not public SDK APIs.
 The realtime wrapper includes a narrow compatibility adapter for Volcano's
 project-prefixed publication channels. It still delegates connection,
 subscription, publish, and disconnect behavior to `centrifuge-python` 0.6.
+Its [interim compatibility policy](./maintainers/realtime-compatibility.md) records
+the dependency bounds, review deadline, removal criteria, and required checks.
 
 ## Develop locally
 
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for cross-language coordination and the full verification workflow.
+
+Generation fails on unsupported responses instead of omitting them. The generator
+configuration maps image and wildcard binary responses to raw-byte parsing while
+preserving the OpenAPI media types and response headers.
+
 ```shell
-uv sync --frozen
-uv run python scripts/check_openapi.py
-uv run ruff check .
-uv run ruff format --check .
-uv run mypy
-uv run pyright
-uv run pytest tests/unit -q
-uv run python -m build
+uv sync --locked
+uv run --locked poe quality
 ```
 
 Live contract scenarios require an isolated fixture produced by

{volcano_sdk_python-0.10.0 → volcano_sdk_python-0.10.2}/README.md

@@ -316,6 +316,10 @@ item when the execution resumes is not guaranteed, so a handler that branched on
 one would take a different path on the replay. `completion_reason` is how to tell
 why the batch ended.
 
+`@durable` accepts typed handlers. The decorated function is the platform
+entrypoint: its arguments and result are invocation envelopes, typed as `object`,
+rather than the handler's application input and result.
+
 Durable operations are synchronous here — there is no `await`, and a step's own
 function is handed a scope carrying `log` and `attempt`. A wait is held by the
 platform rather than by your code, so an execution suspended for an hour costs
@@ -952,18 +956,20 @@ The generated parsed-body-only shortcuts are not public SDK APIs.
 The realtime wrapper includes a narrow compatibility adapter for Volcano's
 project-prefixed publication channels. It still delegates connection,
 subscription, publish, and disconnect behavior to `centrifuge-python` 0.6.
+Its [interim compatibility policy](./maintainers/realtime-compatibility.md) records
+the dependency bounds, review deadline, removal criteria, and required checks.
 
 ## Develop locally
 
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for cross-language coordination and the full verification workflow.
+
+Generation fails on unsupported responses instead of omitting them. The generator
+configuration maps image and wildcard binary responses to raw-byte parsing while
+preserving the OpenAPI media types and response headers.
+
 ```shell
-uv sync --frozen
-uv run python scripts/check_openapi.py
-uv run ruff check .
-uv run ruff format --check .
-uv run mypy
-uv run pyright
-uv run pytest tests/unit -q
-uv run python -m build
+uv sync --locked
+uv run --locked poe quality
 ```
 
 Live contract scenarios require an isolated fixture produced by

{volcano_sdk_python-0.10.0 → volcano_sdk_python-0.10.2}/docs/README.md

@@ -131,3 +131,5 @@ See [Realtime](./realtime.md) for broadcasts, presence, database changes, and sh
 See [Authentication](./authentication.md) for account, session, email, and OAuth workflows.
 
 See [Functions](./functions.md) for invocation identity, response values, and error handling.
+
+See [Versions and compatibility](./versions.md) for runtime support, upgrades, and restoring a tested dependency set.

{volcano_sdk_python-0.10.0 → volcano_sdk_python-0.10.2}/docs/logs.md

@@ -26,6 +26,11 @@ for event in page.data:
 
 `search()` returns an immutable `LogSearchResponse` with `data`, `limit`, `has_more`, and `next_cursor`.
 
+Both log methods reject malformed response envelopes and row collections with
+`TypeError`. The response must be an object whose `data` field is a list of
+objects; an empty object is not an empty page. Page limits and activity totals
+must be integers, and `has_more` must be a boolean.
+
 ## Continue a search
 
 ```python

volcano_sdk_python-0.10.2/docs/versions.md

@@ -0,0 +1,53 @@
+---
+title: Python SDK versions
+description: Pin a tested SDK version, check runtime compatibility, upgrade safely, and restore a previous application dependency set.
+---
+
+Pin the SDK version your application has tested. For example:
+
+```text
+volcano-sdk-python==0.10.0
+```
+
+Save this requirement in your application dependency file and install it in a virtual environment.
+
+These are example versions, not a moving latest-version reference.
+Keep the resolved dependency lock used by your application and install from that lock in CI and deployment. An exact direct requirement alone does not lock transitive dependencies.
+
+## Runtime and compatibility
+
+Use Python 3.11 or later. Native CI tests Python 3.11 and 3.14; it does not test every intervening interpreter release. REST methods are synchronous, while realtime uses an asynchronous lifecycle.
+
+The package is currently on the 0.x release line. Treat a minor-version update as potentially incompatible and read its release notes before upgrading.
+JavaScript, Python and Ruby releases have independent version numbers; matching numbers are not a compatibility requirement.
+Python raises typed exceptions; JavaScript keeps its result-envelope API.
+Follow your language's public facade and examples rather than importing generated transport classes.
+
+The docs describe the current SDK source. Confirm a method is included in your installed version by checking its [release notes](https://github.com/Kong/volcano-sdk-python/releases) and [changelog](https://github.com/Kong/volcano-sdk-python/blob/main/CHANGELOG.md).
+Server-dependent features also need the corresponding Volcano API behavior; installing a newer SDK does not deploy that behavior.
+
+## Upgrade an application
+
+1. Read the release notes between your installed version and the intended version, including breaking changes and runtime requirements.
+2. Update the dependency in a branch and review the resolved lockfile changes.
+3. Run the [documented quickstart](./README.md) with a disposable test project, then run the application tests for the features you use.
+4. Deploy the tested application and dependency lock together. Retain the previous tested application revision and lock.
+
+A successful package import proves installation, not compatibility with every deployed API feature.
+
+## Restore a previous version
+
+Restore the previously tested application revision and its dependency lock together, then install from that lock in a clean environment.
+Run the same quickstart and application tests before redeploying it.
+Do not select an arbitrary older SDK version or downgrade only the top-level dependency while retaining a different transitive dependency tree.
+
+Restoring application packages does not revert server configuration, schema changes, stored data or completed operations.
+Check those dependencies before rolling back an application that changed them.
+
+## Report a compatibility problem
+
+Open an [SDK issue](https://github.com/Kong/volcano-sdk-python/issues) with the installed SDK version, runtime version, affected method, expected result and a minimal reproduction.
+Include a sanitized error category and status when available.
+Remove keys, tokens, passwords and private response bodies.
+
+For suspected vulnerabilities, including authentication or authorization regressions, follow [Kong’s vulnerability reporting process](https://konghq.com/compliance/vuln-disclosure) and email vulnerability@konghq.com. Do not post security reproductions in public issues, pull requests or discussions.

{volcano_sdk_python-0.10.0 → volcano_sdk_python-0.10.2}/features/contract_support.py

@@ -90,26 +90,27 @@ def classify_error(error: Exception) -> str:
     if matched_category is not None:
         return matched_category
     if isinstance(error, VolcanoError):
-        status = error.status
-        if status in (401, 403):
-            return "authentication error"
-        if status in (400, 422):
-            return "validation error"
-        category_by_status = {
-            HTTP_NOT_FOUND: "not found",
-            HTTP_CONFLICT: "conflict",
-            HTTP_RATE_LIMITED: "rate limited",
-        }
-        if status in category_by_status:
-            return category_by_status[status]
-        if (
-            status is not None
-            and HTTP_SERVER_ERROR_MIN <= status <= HTTP_SERVER_ERROR_MAX
-        ):
-            return "server error"
+        return classify_status(error.status)
     return "transport error"
 
 
+def classify_status(status: int | None) -> str:
+    category_by_status = {
+        401: "authentication error",
+        403: "authentication error",
+        400: "validation error",
+        422: "validation error",
+        HTTP_NOT_FOUND: "not found",
+        HTTP_CONFLICT: "conflict",
+        HTTP_RATE_LIMITED: "rate limited",
+    }
+    if status is None:
+        return "transport error"
+    if HTTP_SERVER_ERROR_MIN <= status <= HTTP_SERVER_ERROR_MAX:
+        return "server error"
+    return category_by_status.get(status, "transport error")
+
+
 class ContractWorld:
     def __init__(self, fixture: dict[str, Any]) -> None:
         self.fixture = fixture
@@ -182,6 +183,12 @@ class ContractWorld:
 
         That read is also what reconciles the stored status against the
         platform's, so it is the path a client waiting for a result takes.
+
+        Returns:
+            The execution in a terminal state.
+
+        Raises:
+            TimeoutError: If the execution stays active past the polling deadline.
         """
         deadline = time.monotonic() + DURABLE_POLL_TIMEOUT_SECONDS
         while True:
@@ -231,14 +238,19 @@ class ContractWorld:
                 callback()
             except CONTRACT_EXCEPTIONS as error:
                 failures.append(error)
-        for client in self.realtime_clients:
-            try:
-                self.run(client.realtime.disconnect())
-            except CONTRACT_EXCEPTIONS as error:
-                failures.append(error)
+        failures.extend(self.disconnect_realtime_clients())
         self.cleanup_callbacks.clear()
         self.realtime_clients.clear()
         self.loop.close()
         if failures:
             message = "Python contract cleanup failed"
             raise ExceptionGroup(message, failures)
+
+    def disconnect_realtime_clients(self) -> list[Exception]:
+        failures: list[Exception] = []
+        for client in self.realtime_clients:
+            try:
+                self.run(client.realtime.disconnect())
+            except CONTRACT_EXCEPTIONS as error:
+                failures.append(error)
+        return failures

{volcano_sdk_python-0.10.0 → volcano_sdk_python-0.10.2}/features/postgres_changes.py

@@ -91,16 +91,7 @@ async def verify_postgres_changes(world: ContractWorld) -> list[str]:
     }
     table = world.client.database(world.fixture["database_name"]).from_(table_name)
     world.cleanup_callbacks.append(lambda: table.delete().eq("id", row["id"]).execute())
-    channels = []
-    for index, client in enumerate(world.realtime_clients):
-        client.realtime.set_database_name(world.fixture["database_name"])
-        channels.append(
-            client.realtime.channel(
-                "public:" + table_name,
-                channel_type="postgres",
-                auto_fetch=index == 0,
-            )
-        )
+    channels = postgres_channels(world, table_name)
     observers = [ChangeObserver(channel, table_name, row["id"]) for channel in channels]
     try:
         await asyncio.gather(*(channel.subscribe() for channel in channels))
@@ -126,3 +117,17 @@ async def verify_postgres_changes(world: ContractWorld) -> list[str]:
             observer.close()
         await asyncio.gather(*(channel.unsubscribe() for channel in channels))
     return ["INSERT", "UPDATE"]
+
+
+def postgres_channels(world: ContractWorld, table_name: str) -> list[Channel]:
+    channels: list[Channel] = []
+    for index, client in enumerate(world.realtime_clients):
+        client.realtime.set_database_name(world.fixture["database_name"])
+        channels.append(
+            client.realtime.channel(
+                "public:" + table_name,
+                channel_type="postgres",
+                auto_fetch=index == 0,
+            )
+        )
+    return channels

{volcano_sdk_python-0.10.0 → volcano_sdk_python-0.10.2}/features/steps/sdk_contract_steps.py

@@ -955,6 +955,8 @@ def start_durable_execution_twice(context: Any) -> None:
     def operation() -> tuple[Any, Any]:
         return world.start_durable_execution(), world.start_durable_execution()
 
+    world.record(operation)
+
 
 @when("the client recovers the contract lock with caller-owned tokens")
 def recover_lock(context: Any) -> None:
@@ -1152,27 +1154,30 @@ def two_realtime_clients(context: Any) -> None:
         )
 
 
+async def publish_contract_message(world: ContractWorld) -> Any:
+    assert world.subscriber is not None
+    assert world.publisher is not None
+    received = world.loop.create_future()
+
+    def on_message(message: Any) -> None:
+        if not received.done():
+            received.set_result(message)
+
+    world.subscriber.on("message", on_message)
+    await world.publisher.send(world.realtime_message)
+    return await asyncio.wait_for(received, timeout=10)
+
+
 @when("one client subscribes and the other publishes the contract message")
 def subscribe_and_publish(context: Any) -> None:
     world = _world(context)
     if world.last_outcome is not None and not world.last_outcome.ok:
         return
 
-    async def operation() -> Any:
-        assert world.subscriber is not None
-        assert world.publisher is not None
-        received = world.loop.create_future()
-
-        def on_message(message: Any) -> None:
-            if not received.done():
-                received.set_result(message)
-
-        world.subscriber.on("message", on_message)
-        await world.publisher.send(world.realtime_message)
-        return await asyncio.wait_for(received, timeout=10)
-
     try:
-        world.last_outcome = Outcome(ok=True, value=world.run(operation()))
+        world.last_outcome = Outcome(
+            ok=True, value=world.run(publish_contract_message(world))
+        )
     except CONTRACT_EXCEPTIONS as error:
         world.last_outcome = Outcome(
             ok=False,

volcano_sdk_python-0.10.2/maintainers/coverage.md

@@ -0,0 +1,40 @@
+# Runtime coverage
+
+`uv run --locked poe coverage` measures every Python file under `src/volcano_sdk`,
+including unimported files and namespace directories. Native coverage.py
+configuration requires 100% line and branch coverage. `poe quality` includes
+this task, and CI preserves `reports/coverage.json` for each quality run.
+
+The generated OpenAPI client and declaration-only code are excluded. Coverage
+pragmas cannot suppress missing lines or branches. Tests exercise this policy
+with unimported modules, missing branches, and ineffective pragma comments.
+Examples, generator tooling, package contents, and installed consumers have
+separate smoke and gate tests; they are outside runtime coverage.
+
+Coverage runs in an isolated Python 3.12 environment with the same lockfile.
+The ordinary test task and all other quality checks still run on the selected
+Python version, including both compatibility versions in CI. uv's isolation
+keeps coverage from replacing that interpreter or its environment.
+
+The fixed coverage interpreter avoids incorrect async branch attribution on
+Python 3.11. With coverage.py 7.16.1, both `ctrace` and `pytrace` report the
+unexecuted raise below as covered and the executed false exit as missing.
+Python 3.12 reports those outcomes correctly. Run this with `coverage run
+--branch` and `coverage report -m` to reproduce:
+
+```python
+import asyncio
+
+
+async def finish(error):
+    async with asyncio.Lock():
+        if error is not None:
+            raise error
+
+
+asyncio.run(finish(None))
+```
+
+Native references: [coverage configuration](https://coverage.readthedocs.io/en/latest/config.html),
+[pytest-cov configuration](https://pytest-cov.readthedocs.io/en/latest/config.html),
+and [uv isolated execution](https://docs.astral.sh/uv/reference/cli/#uv-run--isolated).