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

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

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

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

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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.9.4 → volcano_sdk_python-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: volcano-sdk-python
-Version: 0.9.4
+Version: 0.10.0
 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

{volcano_sdk_python-0.9.4 → volcano_sdk_python-0.10.0}/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

volcano_sdk_python-0.10.0/features/contract/durable.feature

@@ -0,0 +1,34 @@
+Feature: SDK durable execution contract
+
+  @durable @SDK-DURABLE-001
+  Scenario: Starting a durable execution returns a handle, not a result
+    Given a service-role client
+    When the client starts the contract durable function
+    Then the SDK operation succeeds
+    And the started execution carries its id, function, name, region, and creation time
+    And the started execution is not terminal and carries no result
+
+  @durable @SDK-DURABLE-002
+  Scenario: One execution name starts one execution
+    Given a service-role client
+    When the client starts the contract durable function twice under one execution name
+    Then the SDK operation succeeds
+    And both starts return the same execution
+
+  @durable @SDK-DURABLE-003
+  Scenario: An owner-scoped read follows an execution to its result
+    Given a service-role client
+    And a project-owner client
+    When the client starts the contract durable function
+    And the owner reads the execution until it is terminal
+    Then the SDK operation succeeds
+    And the execution succeeded carrying the function's result
+
+  @durable @SDK-DURABLE-004
+  Scenario: An owner-scoped list includes the started execution
+    Given a service-role client
+    And a project-owner client
+    When the client starts the contract durable function
+    And the owner lists the durable function's executions
+    Then the SDK operation succeeds
+    And the listed executions include the started execution

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

@@ -3,6 +3,7 @@ from __future__ import annotations
 import asyncio
 import os
 import secrets
+import time
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
@@ -14,6 +15,7 @@ from volcano_sdk import (
     NotFoundError,
     RateLimitedError,
     ServerError,
+    Session,
     TransportError,
     ValidationError,
     VolcanoClient,
@@ -23,7 +25,12 @@ from volcano_sdk import (
 if TYPE_CHECKING:
     from collections.abc import Awaitable, Callable
 
-    from volcano_sdk.models import AuthChangeEvent, LockLease, Session
+    from volcano_sdk.models import (
+        AuthChangeEvent,
+        DurableExecution,
+        DurableExecutionPage,
+        LockLease,
+    )
     from volcano_sdk.realtime import Channel
 
 HTTP_NOT_FOUND = 404
@@ -32,6 +39,17 @@ HTTP_RATE_LIMITED = 429
 HTTP_SERVER_ERROR_MIN = 500
 HTTP_SERVER_ERROR_MAX = 599
 
+# A durable execution is started asynchronously and observed through a status
+# read, so it settles in seconds. Bounded, so a scenario reports a timeout
+# instead of hanging the lane.
+DURABLE_POLL_INTERVAL_SECONDS = 5
+DURABLE_POLL_TIMEOUT_SECONDS = 300
+
+# The platform token is not an auth session: it cannot be refreshed and belongs
+# to no auth user. The SDK carries a credential as a session and requires a
+# complete one, so the rest of the owner's session is a placeholder.
+OWNER_SESSION_PLACEHOLDER = "sdk-contract-platform-token-has-no-auth-session"
+
 CONTRACT_EXCEPTIONS = (
     CentrifugeError,
     KeyError,
@@ -104,6 +122,20 @@ class ContractWorld:
             anon_key=fixture["anon_key"],
             service_key=fixture["service_key"],
         )
+        # Reading or stopping an execution is owner-scoped, so its client
+        # carries the project's own token as its session. Neither key above can
+        # reach those routes.
+        self.owner_client = VolcanoClient(
+            api_url=fixture["api_url"],
+            anon_key=fixture["anon_key"],
+        )
+        self.owner_client.auth.set_session(
+            Session(
+                access_token=fixture["platform_token"],
+                refresh_token=OWNER_SESSION_PLACEHOLDER,
+                user_id=OWNER_SESSION_PLACEHOLDER,
+            )
+        )
         suffix = f"py-{os.getpid()}-{secrets.token_hex(5)}"
         self.storage_path = f"{fixture['storage_path']}.{suffix}"
         self.realtime_channel = f"{fixture['realtime_channel']}-{suffix}"
@@ -113,6 +145,9 @@ class ContractWorld:
             "event": "message",
             "value": f"volcano-sdk-contract-{suffix}",
         }
+        self.durable_execution_name = f"{fixture['durable_function_name']}-{suffix}"
+        self.durable_payload = {"value": f"volcano-sdk-contract-{suffix}"}
+        self.started_execution: DurableExecution | None = None
         self.last_outcome: Outcome | None = None
         self.previous_session: Session | None = None
         self.signed_out_session: Session | None = None
@@ -133,6 +168,44 @@ class ContractWorld:
     def run(self, operation: Awaitable[Any]) -> Any:
         return self.loop.run_until_complete(operation)
 
+    def start_durable_execution(self) -> DurableExecution:
+        execution = self.service_client.durable.start(
+            self.fixture["durable_function_name"],
+            self.durable_payload,
+            execution_name=self.durable_execution_name,
+        )
+        self.started_execution = execution
+        return execution
+
+    def follow_durable_execution(self, execution_id: str) -> DurableExecution:
+        """Poll an execution to a terminal status under the owner's credential.
+
+        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.
+        """
+        deadline = time.monotonic() + DURABLE_POLL_TIMEOUT_SECONDS
+        while True:
+            execution = self.owner_client.durable.get(
+                self.fixture["project_id"],
+                self.fixture["durable_function_name"],
+                execution_id,
+            )
+            if execution.is_terminal:
+                return execution
+            if time.monotonic() >= deadline:
+                message = (
+                    f"durable execution {execution_id} was still "
+                    f"{execution.status} after {DURABLE_POLL_TIMEOUT_SECONDS}s"
+                )
+                raise TimeoutError(message)
+            time.sleep(DURABLE_POLL_INTERVAL_SECONDS)
+
+    def list_durable_executions(self) -> DurableExecutionPage:
+        return self.owner_client.durable.list(
+            self.fixture["project_id"],
+            self.fixture["durable_function_name"],
+        )
+
     def record(self, operation: Callable[[], Any]) -> Outcome:
         try:
             self.last_outcome = Outcome(ok=True, value=operation())

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

@@ -937,6 +937,25 @@ def released_lease_not_held(context: Any) -> None:
     assert world.last_outcome.value["released"] is True
 
 
+@given("a project-owner client")
+def project_owner_client(context: Any) -> None:
+    assert _world(context).fixture["platform_token"]
+
+
+@when("the client starts the contract durable function")
+def start_durable_execution(context: Any) -> None:
+    world = _world(context)
+    world.record(world.start_durable_execution)
+
+
+@when("the client starts the contract durable function twice under one execution name")
+def start_durable_execution_twice(context: Any) -> None:
+    world = _world(context)
+
+    def operation() -> tuple[Any, Any]:
+        return world.start_durable_execution(), world.start_durable_execution()
+
+
 @when("the client recovers the contract lock with caller-owned tokens")
 def recover_lock(context: Any) -> None:
     world = _world(context)
@@ -964,6 +983,70 @@ def recover_lock(context: Any) -> None:
     world.record(operation)
 
 
+@then("the started execution carries its id, function, name, region, and creation time")
+def started_execution_is_addressable(context: Any) -> None:
+    world = _world(context)
+    assert world.last_outcome is not None
+    execution = world.last_outcome.value
+    assert execution.id
+    assert execution.function_id
+    assert execution.name == world.durable_execution_name
+    assert execution.region
+    assert execution.created_at is not None
+
+
+@then("the started execution is not terminal and carries no result")
+def started_execution_is_a_handle(context: Any) -> None:
+    world = _world(context)
+    assert world.last_outcome is not None
+    assert world.last_outcome.value.is_terminal is False
+    assert world.last_outcome.value.result is None
+
+
+@then("both starts return the same execution")
+def both_starts_return_one_execution(context: Any) -> None:
+    world = _world(context)
+    assert world.last_outcome is not None
+    first, second = world.last_outcome.value
+    assert second.id == first.id
+    assert second.name == first.name
+
+
+@when("the owner reads the execution until it is terminal")
+def read_execution_until_terminal(context: Any) -> None:
+    world = _world(context)
+    if world.last_outcome is not None and not world.last_outcome.ok:
+        return
+    assert world.started_execution is not None
+    execution_id = world.started_execution.id
+    world.record(lambda: world.follow_durable_execution(execution_id))
+
+
+@then("the execution succeeded carrying the function's result")
+def execution_succeeded_with_result(context: Any) -> None:
+    world = _world(context)
+    assert world.last_outcome is not None
+    assert world.last_outcome.value.status == "succeeded"
+    assert world.last_outcome.value.result == {"echoed": world.durable_payload["value"]}
+
+
+@when("the owner lists the durable function's executions")
+def list_durable_executions(context: Any) -> None:
+    world = _world(context)
+    if world.last_outcome is not None and not world.last_outcome.ok:
+        return
+    world.record(world.list_durable_executions)
+
+
+@then("the listed executions include the started execution")
+def listed_executions_include_the_started_one(context: Any) -> None:
+    world = _world(context)
+    assert world.last_outcome is not None
+    assert world.started_execution is not None
+    listed = {execution.id for execution in world.last_outcome.value.executions}
+    assert world.started_execution.id in listed
+
+
 @then("recovery and renewal preserve the held lease until release")
 def recovered_lock_lifecycle(context: Any) -> None:
     world = _world(context)