feat(durable): add wait_for_approval and the approvals client

[subnetmarco]

Change

Durable workflows can wait for a person's approval. Tracks https://github.com/Kong/volcano-hosting/pull/1678.

• ctx.wait_for_approval(name, *, title, description=None, details=None, timeout=None) suspends the execution until a person approves or denies, or the timeout passes, and returns an ApprovalDecision. Registration runs inside the callback submitter, so a replay never registers twice; a timeout resolves to status="expired".
• Registration retries network errors, 404, 429, 5xx and 409 approval_not_ready within one 30 s deadline. Each attempt is bounded as a whole (connect, headers, and body) by min(10 s, remaining). The request is validated against the 64 KiB body limit before the callback opens.
• name must be printable ASCII of at most 237 characters, since it is the runtime's operation name, and NUL is refused anywhere in the text or details. details is copied when checked, so a later change by the caller cannot alter what was validated. A host lookup that stalls is bounded by its attempt's deadline.
• client.durable.approvals: list, get, stats, approve, deny. A project access token is refused deciding with PermissionDeniedError.
• The decision parser trusts only status; comment, decided_by, and decided_at read as empty when malformed, so a recorded decision never fails a replay. decided_at must be an RFC 3339 date-time, matching JavaScript.
• The runtime wrapper is built once per process; each approval reads its execution from the runtime context.
• OpenAPI operations synced from Hosting.

Verification

• poe checks: pass. Policy, audit, generated client, ruff, mypy, basedpyright, 2615 tests at 100% line and branch coverage, package check, and all four tox environments.
• test_realtime_presence_sync_coalesces_latest_backpressured_state is timing-sensitive under heavy load and also fails intermittently on main; it passed in the final run.

Cross-language impact

Classify this change: public facade / wire contract / shared behavior.

• Requirement IDs and affected behavior: SDK-DURABLE-005 to SDK-DURABLE-010 (request, list, approve, deny, stats, project-token refusal, repeated and conflicting decisions).
• JavaScript / Python / Ruby companion PRs: feat(durable): add waitForApproval and the approvals client volcano-sdk-js#315, feat(durable): list, read, and decide durable approvals volcano-sdk-ruby#341. Ruby has no durable authoring, so it covers the client methods only.
• Canonical scenarios, bindings and active/staged copies: tests/sdk-contract/features/durable-approvals.feature with JS, Python, and Ruby bindings in https://github.com/Kong/volcano-hosting/pull/1678.
• Public examples updated in each affected language: docs/functions.md and README.md here; JS and Ruby in their PRs; Hosting's docs/public/functions/durable-approvals.md.
• Native checks and shared acceptance evidence: native checks above at this branch's head. Live acceptance runs in Hosting's staging validation after Hosting deploys approvals; not run yet.

Merge order

1. SDK releases: a maintainer merges and releases the JS SDK 1.16 (feat(durable): add waitForApproval and the approvals client volcano-sdk-js#315), Python SDK 0.14 (feat(durable): add wait_for_approval and the approvals client #389), and the Ruby SDK (feat(durable): list, read, and decide durable approvals volcano-sdk-ruby#341). Hosting's E2E fixtures install those versions from the registries. Until Hosting deploys, the new approval methods get 404.
2. CLI (feat(durable): add durable approvals commands volcano-cli#282), with a one-time maintainer override of localmode-e2e. That suite needs a nightly local-mode image with approvals, which exists only once Hosting merges. Hosting's merge queue runs its CLI E2E against CLI main, so the CLI goes first.
3. Hosting (https://github.com/Kong/volcano-hosting/pull/1678).
4. Dashboard (https://github.com/Kong/volcano-web/pull/836, https://github.com/Kong/volcano-web/pull/837, then https://github.com/Kong/volcano-web/pull/832) and agent skills (docs(durable): teach agents to request and decide durable approvals volcano-skills#57).

[subnetmarco]

Reviewed at 424d6f4. The core holds up against the runtime and Hosting:

• Registration runs in the checkpointed submitter, and a retried POST is idempotent by callback id.
• The runtime's own retry is disabled, and running out of the deadline fails the execution instead of hanging.
• Only CallbackTimeoutError becomes expired, and PermissionDeniedError subclasses AuthenticationError.
• The 64 KiB check measures the exact UTF-8 bytes sent, and the retry policy matches JS.

ruff, mypy, basedpyright, and the generated-client check pass. pytest gives 2626 passed and 1 failed, and the failure comes from FORCE_COLOR=0 in the local shell.

Release order: Hosting's E2E pins volcano-sdk-python~=0.14.0, so this needs to be released before Hosting merges (details on Kong/volcano-hosting#1678).