volcano-sdk-python 0.9.4__tar.gz → 0.10.1__tar.gz

volcano_sdk_python-0.10.1/.github/CODEOWNERS

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

volcano_sdk_python-0.10.1/.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.1/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+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
+      - run: uv sync --locked
+      - name: Run SDK quality checks
+        run: uv run --locked poe quality
+      - 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/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.1/.release-please-manifest.json

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

volcano_sdk_python-0.10.1/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.9.4 → volcano_sdk_python-0.10.1}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* **durable:** start, follow and author durable executions ([#133](https://github.com/Kong/volcano-sdk-python/issues/133)) ([f97aeee](https://github.com/Kong/volcano-sdk-python/commit/f97aeee64760d9c4b5458199b5692f5811b5a840))
+
 ## [0.9.4](https://github.com/Kong/volcano-sdk-python/compare/v0.9.3...v0.9.4) (2026-09-18)
 
 

volcano_sdk_python-0.10.1/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.9.4 → volcano_sdk_python-0.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: volcano-sdk-python
-Version: 0.9.4
+Version: 0.10.1
 Summary: Official Python SDK for Volcano
 Project-URL: Homepage, https://volcano.dev
 Project-URL: Repository, https://github.com/Kong/volcano-sdk-python
@@ -16,8 +16,8 @@ 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: python-dateutil<3.0.0,>=2.9.0.post0
-Requires-Dist: typing-extensions>=4.15.0
+Provides-Extra: durable
+Requires-Dist: aws-durable-execution-sdk-python<3.0.0,>=2.0.0; extra == 'durable'
 Description-Content-Type: text/markdown
 
 # Volcano Python SDK
@@ -84,6 +84,27 @@ function = client.functions.invoke(
 )
 print(function.status, function.version, function.data)
 
+execution = client.durable.start(
+    "order-pipeline",
+    {"order_id": 4417},
+    execution_name="order-4417",
+)
+print(execution.id, execution.status)
+
+execution = client.durable.get(
+    "00000000-0000-4000-8000-000000000001", "order-pipeline", execution.id
+)
+print(execution.is_terminal, execution.result)
+
+executions = client.durable.list(
+    "00000000-0000-4000-8000-000000000001", "order-pipeline", status="running"
+)
+print(executions.total, executions.has_more)
+
+client.durable.stop(
+    "00000000-0000-4000-8000-000000000001", "order-pipeline", execution.id
+)
+
 # Project logs use a control-plane project token, not this end-user session.
 logs_client = VolcanoClient(
     anon_key="ak_your_anon_key", access_token="vpat_your_project_token"
@@ -239,6 +260,91 @@ prevents replay under another identity. The call preserves its original payload
 A function's own response, HTTP 403, or a network failure never triggers this retry.
 Anonymous and service keys do not refresh.
 
+`durable.start()` begins an execution of a deployed durable function and returns
+a handle rather than a result: an execution can run for hours, so its result is
+read back with `durable.get()`. It takes the credential `functions.invoke()`
+takes, and is the only durable operation an application credential may perform.
+An `execution_name` makes the start idempotent — starting again under the same
+name returns the execution that already exists rather than beginning a second
+one, and is charged once.
+
+`durable.get()`, `durable.list()` and `durable.stop()` are owner-scoped and need
+the project's own platform token, because an execution is addressed by its id
+alone and an anonymous key is held by everyone who loads the page. Neither an
+auth-user session from `sign_in()` nor a service key is accepted -- the routes
+take a user token, and anything else is answered 401. Poll them from a backend.
+`get()` carries `result` once the execution has succeeded and `error` when it
+failed; `result_expired` separates a result the platform has discarded from a
+function that returned nothing. `is_terminal` reports whether the execution has
+stopped changing, and counts `unknown` — the status the platform writes for an
+outcome it could not determine — as finished. `stop()` is accepted rather than
+awaited: what it returns is the execution read back after asking, often still
+`running`, so poll `get()` to see it reach `stopped`. Repeating a stop is safe.
+
+## Write a durable function
+
+`volcano_sdk.durable_authoring` is what the durable function itself is written
+against. It needs a durable-capable runtime — `python3.13` or `python3.14` — and
+`volcano-sdk-python` in the function's `requirements.txt`. Nothing else: the runtime
+that does the checkpointing is installed by Volcano when it builds a function
+deployed as durable.
+
+Importing this module never requires that runtime, so a standard function or a
+script that imports it still installs and runs; the handler fails only when it
+is actually invoked somewhere durable execution does not exist.
+
+```python
+from volcano_sdk.durable_authoring import durable
+
+
+@durable
+def handler(event, ctx):
+    charge = ctx.step("charge", lambda scope: charge_card(event["order_id"]))
+
+    ctx.wait("settle", "30s")
+
+    packed = ctx.map(
+        event["items"],
+        lambda item, item_ctx, index: item_ctx.step("pack-item", lambda s: pack(item)),
+        "pack",
+    )
+
+    return {"charged": charge["id"], "packed": packed.results}
+```
+
+Every context operation is checkpointed: what finished is recorded, and a
+resumed execution replays that recorded outcome instead of doing the work again.
+That is the one rule the handler has to respect — the code between operations
+runs again on every resume, so it has to reach the same operations in the same
+order. Keep decisions that must not change inside a `step`, and do not branch on
+the clock or a random value.
+
+| Operation | What it does |
+|---|---|
+| `ctx.step(name, fn, retry=..., at_most_once=...)` | Runs one atomic operation and records its result. `retry=False` fails on the first error; `RetryOptions` sets attempts and backoff. |
+| `ctx.wait(name, duration)` | Suspends the execution. `"30s"`, `"2h"`, `"1m30s"`, a whole number of seconds, or `{"hours": 2}`. |
+| `ctx.wait_until(check, options, name=None)` | Polls your own state until `options.until` holds, suspending between checks. `options.initial_state` is required. |
+| `ctx.map(items, fn, name=None, options=None)` | Runs the same work over every item, each in its own child context. |
+| `ctx.parallel(branches, name=None, options=None)` | Runs independent branches at the same time. |
+| `ctx.child(name, fn)` | Groups operations under one recorded context. |
+| `ctx.log` | The execution's logger, suppressed while an operation is replayed. |
+
+`ctx.map` and `ctx.parallel` both return a batch result: `items` (the items that
+finished, each with `index`, `status`, `result`, `error`), `results`, `errors`,
+`succeeded`, `failed`, `completed`, `completion_reason`, and `throw_if_failed()`.
+`options.min_succeeded` ends the batch while other items are still running, and
+those are not in the result — whether the platform can reproduce an in-flight
+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 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
+nothing while it waits. Running the handler anywhere durable execution does not
+exist raises `DurableRuntimeMissingError` rather than an import error from an
+unfamiliar package.
+
 `logs.search()` returns an immutable page of retained runtime or deployment log
 events. Pass `next_cursor` back as `cursor` to continue a search. `logs.activity()`
 returns immutable time buckets using the same resource selector and query syntax.
@@ -830,6 +936,29 @@ included. Tune a channel's batching with `fetch_batch_window_ms` and
 without querying their rows. Pass `None` to `set_database_name()` to disable
 row fetching for every channel.
 
+## Dependencies
+
+Installing `volcano-sdk-python` pulls in three packages, plus their own transitive
+dependencies:
+
+| Package                                                            | Why                                        |
+| ------------------------------------------------------------------ | ------------------------------------------ |
+| [`httpx`](https://pypi.org/project/httpx/)                         | The HTTP client every request goes through |
+| [`attrs`](https://pypi.org/project/attrs/)                         | The generated client's models              |
+| [`centrifuge-python`](https://pypi.org/project/centrifuge-python/) | The realtime protocol client               |
+
+A durable function you deploy needs one more, and you do not install it:
+Volcano adds it when it builds the function.
+
+| Package                                                                                          | Why                                                                   |
+| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| [`aws-durable-execution-sdk-python`](https://pypi.org/project/aws-durable-execution-sdk-python/) | Checkpointing. `volcano_sdk.durable_authoring` is written on top of it |
+
+The `durable` extra installs it if you want it yourself — to run a durable
+handler in your own tests, or to pin a version, since the build leaves a
+function that pins the runtime exactly as it is. A function's `requirements.txt`
+does not need it otherwise.
+
 ## Compatibility
 
 CI tests the SDK on Python 3.11 and 3.14. Its public facade is intentionally
@@ -845,18 +974,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.9.4 → volcano_sdk_python-0.10.1}/README.md

@@ -62,6 +62,27 @@ function = client.functions.invoke(
 )
 print(function.status, function.version, function.data)
 
+execution = client.durable.start(
+    "order-pipeline",
+    {"order_id": 4417},
+    execution_name="order-4417",
+)
+print(execution.id, execution.status)
+
+execution = client.durable.get(
+    "00000000-0000-4000-8000-000000000001", "order-pipeline", execution.id
+)
+print(execution.is_terminal, execution.result)
+
+executions = client.durable.list(
+    "00000000-0000-4000-8000-000000000001", "order-pipeline", status="running"
+)
+print(executions.total, executions.has_more)
+
+client.durable.stop(
+    "00000000-0000-4000-8000-000000000001", "order-pipeline", execution.id
+)
+
 # Project logs use a control-plane project token, not this end-user session.
 logs_client = VolcanoClient(
     anon_key="ak_your_anon_key", access_token="vpat_your_project_token"
@@ -217,6 +238,91 @@ prevents replay under another identity. The call preserves its original payload
 A function's own response, HTTP 403, or a network failure never triggers this retry.
 Anonymous and service keys do not refresh.
 
+`durable.start()` begins an execution of a deployed durable function and returns
+a handle rather than a result: an execution can run for hours, so its result is
+read back with `durable.get()`. It takes the credential `functions.invoke()`
+takes, and is the only durable operation an application credential may perform.
+An `execution_name` makes the start idempotent — starting again under the same
+name returns the execution that already exists rather than beginning a second
+one, and is charged once.
+
+`durable.get()`, `durable.list()` and `durable.stop()` are owner-scoped and need
+the project's own platform token, because an execution is addressed by its id
+alone and an anonymous key is held by everyone who loads the page. Neither an
+auth-user session from `sign_in()` nor a service key is accepted -- the routes
+take a user token, and anything else is answered 401. Poll them from a backend.
+`get()` carries `result` once the execution has succeeded and `error` when it
+failed; `result_expired` separates a result the platform has discarded from a
+function that returned nothing. `is_terminal` reports whether the execution has
+stopped changing, and counts `unknown` — the status the platform writes for an
+outcome it could not determine — as finished. `stop()` is accepted rather than
+awaited: what it returns is the execution read back after asking, often still
+`running`, so poll `get()` to see it reach `stopped`. Repeating a stop is safe.
+
+## Write a durable function
+
+`volcano_sdk.durable_authoring` is what the durable function itself is written
+against. It needs a durable-capable runtime — `python3.13` or `python3.14` — and
+`volcano-sdk-python` in the function's `requirements.txt`. Nothing else: the runtime
+that does the checkpointing is installed by Volcano when it builds a function
+deployed as durable.
+
+Importing this module never requires that runtime, so a standard function or a
+script that imports it still installs and runs; the handler fails only when it
+is actually invoked somewhere durable execution does not exist.
+
+```python
+from volcano_sdk.durable_authoring import durable
+
+
+@durable
+def handler(event, ctx):
+    charge = ctx.step("charge", lambda scope: charge_card(event["order_id"]))
+
+    ctx.wait("settle", "30s")
+
+    packed = ctx.map(
+        event["items"],
+        lambda item, item_ctx, index: item_ctx.step("pack-item", lambda s: pack(item)),
+        "pack",
+    )
+
+    return {"charged": charge["id"], "packed": packed.results}
+```
+
+Every context operation is checkpointed: what finished is recorded, and a
+resumed execution replays that recorded outcome instead of doing the work again.
+That is the one rule the handler has to respect — the code between operations
+runs again on every resume, so it has to reach the same operations in the same
+order. Keep decisions that must not change inside a `step`, and do not branch on
+the clock or a random value.
+
+| Operation | What it does |
+|---|---|
+| `ctx.step(name, fn, retry=..., at_most_once=...)` | Runs one atomic operation and records its result. `retry=False` fails on the first error; `RetryOptions` sets attempts and backoff. |
+| `ctx.wait(name, duration)` | Suspends the execution. `"30s"`, `"2h"`, `"1m30s"`, a whole number of seconds, or `{"hours": 2}`. |
+| `ctx.wait_until(check, options, name=None)` | Polls your own state until `options.until` holds, suspending between checks. `options.initial_state` is required. |
+| `ctx.map(items, fn, name=None, options=None)` | Runs the same work over every item, each in its own child context. |
+| `ctx.parallel(branches, name=None, options=None)` | Runs independent branches at the same time. |
+| `ctx.child(name, fn)` | Groups operations under one recorded context. |
+| `ctx.log` | The execution's logger, suppressed while an operation is replayed. |
+
+`ctx.map` and `ctx.parallel` both return a batch result: `items` (the items that
+finished, each with `index`, `status`, `result`, `error`), `results`, `errors`,
+`succeeded`, `failed`, `completed`, `completion_reason`, and `throw_if_failed()`.
+`options.min_succeeded` ends the batch while other items are still running, and
+those are not in the result — whether the platform can reproduce an in-flight
+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 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
+nothing while it waits. Running the handler anywhere durable execution does not
+exist raises `DurableRuntimeMissingError` rather than an import error from an
+unfamiliar package.
+
 `logs.search()` returns an immutable page of retained runtime or deployment log
 events. Pass `next_cursor` back as `cursor` to continue a search. `logs.activity()`
 returns immutable time buckets using the same resource selector and query syntax.
@@ -808,6 +914,29 @@ included. Tune a channel's batching with `fetch_batch_window_ms` and
 without querying their rows. Pass `None` to `set_database_name()` to disable
 row fetching for every channel.
 
+## Dependencies
+
+Installing `volcano-sdk-python` pulls in three packages, plus their own transitive
+dependencies:
+
+| Package                                                            | Why                                        |
+| ------------------------------------------------------------------ | ------------------------------------------ |
+| [`httpx`](https://pypi.org/project/httpx/)                         | The HTTP client every request goes through |
+| [`attrs`](https://pypi.org/project/attrs/)                         | The generated client's models              |
+| [`centrifuge-python`](https://pypi.org/project/centrifuge-python/) | The realtime protocol client               |
+
+A durable function you deploy needs one more, and you do not install it:
+Volcano adds it when it builds the function.
+
+| Package                                                                                          | Why                                                                   |
+| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| [`aws-durable-execution-sdk-python`](https://pypi.org/project/aws-durable-execution-sdk-python/) | Checkpointing. `volcano_sdk.durable_authoring` is written on top of it |
+
+The `durable` extra installs it if you want it yourself — to run a durable
+handler in your own tests, or to pin a version, since the build leaves a
+function that pins the runtime exactly as it is. A function's `requirements.txt`
+does not need it otherwise.
+
 ## Compatibility
 
 CI tests the SDK on Python 3.11 and 3.14. Its public facade is intentionally
@@ -823,18 +952,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.9.4 → volcano_sdk_python-0.10.1}/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.9.4 → volcano_sdk_python-0.10.1}/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