CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[0.2.2] - 2026-10-21

Changed

• Bumped duroxide-pg from 0.1.36 to 0.1.37.

[0.2.1] - 2026-10-12

Changed

• Bumped duroxide dependency — 0.1.30 → 0.1.32 (race fixes and shutdown, below). 0.1.31 was reserved and never published.
• Bumped duroxide-pg dependency — 0.1.35 → 0.1.36. Under heavy load, an orchestration fetched from PostgreSQL could come with a lock that had already expired. Every ack then failed with Invalid lock token, and the message was retried for as long as the load lasted. The lock now starts when the instance is claimed (migration 0025). An SDK version built with duroxide-pg 0.1.35 refuses a database that has this migration.
• runtime.shutdown(timeout_ms) returns as soon as the runtime stops. timeout_ms (default 1000) is now the longest it waits for in-flight work before cancelling the rest, not a fixed delay. Shutdown also stops every task the runtime started, so no poller keeps a database connection open after it returns.
• A signal sent to a dropped wait_for_event is discarded. When a wait_for_event loses a ctx.race(), a signal already given to it is no longer handed to a later wait for the same event. The later wait receives the next signal. Before, it could receive the stale value, fail replay, or wait forever.
• A duplicate start does not change a running instance. client.start_orchestration() for an instance that already has history is ignored; it can no longer replace the instance's orchestration name, version or input. A sub-orchestration whose instance id collides with a running instance now fails its parent, as it already did for a finished one.

Fixed

• A queue read that loses a race takes no message. A drain loop that races ctx.dequeue_event() against a short timer could fail with nondeterministic: history schedule but no emitted action, skip a message, or read one twice when the timer won and a message arrived in the same batch. A dropped read is now cancelled where it is dropped, so replay picks the same winners as the first run.
• continue_as_new carries exactly the unread messages. A dropped or still-pending read counted as a consumer, so a message could be lost at continue-as-new. The runtime now carries every message that no read returned (at most 100, as before).
• Inputs that arrive while an instance continues as new are kept. Queue messages, signals and cancellation requests that arrived between two executions could be deleted. They now go to the next execution.
• ctx.get_kv_all_keys() and ctx.prune_kv_values_updated_before() use key order. Replay could fail with nondeterministic: kv clear mismatch after a prune.

The queue, signal and continue-as-new changes apply to executions started by duroxide 0.1.32 or later. An execution started by an older runtime keeps the old behaviour until it completes or continues as new. See the duroxide migration guide for details and rolling upgrades.

Added

• tests/test_races.py — drain loops that race ctx.dequeue_event() against a timer: every message arrives once and in order, also across continue_as_new.
• tests/test_kv_store.py — KV keys are listed and pruned in key order, and a replayed prune matches.

[0.2.0] - 2026-10-04

Changed

• Breaking: ctx.race() and ctx.race_typed() raise when the winner failed. Before, a winning activity or sub-orchestration that failed came back like a success: {"index": ..., "value": ...}, with the error text in value. Nothing marked it as an error. Now the yield raises the same exception as yielding that task on its own: same type, same message. If the orchestration does not catch it, the orchestration fails.
  • Winners that succeeded, timers, events and dequeued messages return {"index": ..., "value": ...} as before.
  • Code that read the error text from value must catch the exception instead.
  • A race over a task type that race() does not support now raises unsupported task in select. Before, it returned that text as the value.
  • Instances in flight: if a history already holds a race won by a failed task, the replay now raises at that race. If the code then takes a different path than the first run did, the instance fails. Upgrade when no such instance is running.

Added

• worker_lock_renewal_buffer_ms, session_lock_timeout_ms, session_lock_renewal_buffer_ms runtime options — map to worker_lock_renewal_buffer, session_lock_timeout and session_lock_renewal_buffer of the Rust runtime. Keyword arguments of RuntimeOptions, added after the existing ones. With these, every lock timeout and renewal buffer of the runtime can be set from Python.
• tests/test_lock_options.py — checks that every lock option reaches the runtime, from the renewal intervals the runtime logs.

[0.1.29] - 2026-10-03

Fixed

• Replays of the same instance no longer share a native context. The synchronous context calls (ctx.set_kv_value / ctx.get_kv_value and the other KV calls, ctx.set_custom_status / ctx.get_custom_status, and ctx.trace_*) found the Rust OrchestrationContext by instance ID. Two replays of one instance can be alive in the same process: a replay that lost its orchestration lock (for example after the process stalled for longer than the lock timeout) keeps running until its commit is rejected, and another dispatcher slot can fetch the instance again. Calls from one replay then reached the other. The replay that held the lock could commit events it never produced, and the next replay failed with nondeterministic: kv set mismatch or nondeterministic: schedule mismatch. The context is now looked up by a token that is new for every invocation, the same way activity contexts already work.

Changed

• Bumped duroxide-pg dependency — 0.1.34 → 0.1.35.

Added

• orchestrator_lock_timeout_ms, orchestrator_lock_renewal_buffer_ms, max_attempts runtime options — map to orchestrator_lock_timeout, orchestrator_lock_renewal_buffer and max_attempts of the Rust runtime. Keyword arguments of RuntimeOptions, added after the existing ones.
• tests/test_replay_isolation.py — regression tests that stop the process in the middle of a replay for longer than the orchestration lock timeout (POSIX only).

[0.1.28] - 2026-09-03

Changed

• Stable ABI wheels — Publish cp39-abi3 wheels so each platform wheel supports Python 3.9 through 3.14.

[0.1.27] - 2026-07-29

Changed

• Bumped duroxide dependency — 0.1.29 → 0.1.30.

[0.1.26] - 2026-05-25

Changed

• Bumped duroxide-pg dependency — 0.1.32 → 0.1.34
• Updated PostgreSQL Rust bindings to construct providers through the new ProviderConfig::url(...) / ProviderConfig::entra(...) plus PostgresProvider::new_with_config(config) initialization API.
• Kept duroxide dependency pinned at 0.1.29.

[0.1.25] - 2026-05-09

Added

• PostgresEntraOptions — new Python class for tuning Microsoft Entra ID (Azure AD) authentication: keyword-only optional fields audience, max_connections, acquire_timeout_ms, and refresh_interval_ms.
• PostgresProvider.connect_with_entra(host, port, database, user, options=None) — connect to Azure Database for PostgreSQL Flexible Server via Entra token auth. Tokens are fetched and refreshed automatically via the DefaultAzureCredential chain (managed identity, environment variables, Azure CLI, etc.).
• PostgresProvider.connect_with_schema_and_entra(host, port, database, user, schema, options=None) — same as above with a custom schema for multi-tenant isolation.

Changed

• Bumped duroxide dependency — 0.1.28 → 0.1.29
• Bumped duroxide-pg dependency — 0.1.30 → 0.1.32

Added

• Linux ARM64 wheel - Build and publish a manylinux aarch64 (aarch64-unknown-linux-gnu) wheel so pip install duroxide works in Linux ARM64 containers without compiling from source.
• Linux ARM64 CI smoke - Run local wheel and post-publish registry smoke on ubuntu-24.04-arm.

[0.1.22] - 2026-04-23

Fixed

• Linux wheel build — Install openssl-devel (manylinux_2_28) / libssl-dev (Debian) in the before-script-linux step so the new native-tls backend can find OpenSSL via pkg-config. Previous attempt (0.1.21) tagged but never published because every Linux wheel job failed with "Could not find openssl via pkg-config".

[0.1.21] - 2026-04-23

Changed

• Bumped duroxide dependency — 0.1.27 → 0.1.28 (drops transitive ring crate via SQLx native-tls upstream)
• Bumped duroxide-pg dependency — 0.1.29 → 0.1.30 (same ring-drop cascade)
• No source changes in the Python SDK; pure dependency uplift

⚠️ Do not use 0.1.21 — never published to PyPI. Use 0.1.22.

[0.1.20] - 2026-04-17

Added

• Cross-platform packaging smoke tests in ci/smoke/ that install the built wheel on ubuntu, macos-14, macos-13, and windows-latest before publish, plus a post-publish registry smoke. Publish is gated on all-platform smoke success.

Changed

• Pinned manylinux_2_28 with an explicit python3.12 interpreter for the Linux wheel build (upstream manylinux: auto regressed).

[0.1.19] - 2026-04-06

Changed

• Bumped duroxide-pg from 0.1.28 to 0.1.29.
• Fixes migration race condition on concurrent startup (microsoft/duroxide#10).
• Cached plan invalidation (0A000) now retryable.

[0.1.18] - 2026-04-04

Added

• client.get_orchestration_stats(instance_id) exposing per-instance history, queue carry-forward, and KV usage counters.

Changed

• Bumped duroxide to 0.1.27 and duroxide-pg to 0.1.28.
• Updated exported KV limits to MAX_KV_KEYS = 150 and MAX_KV_VALUE_BYTES = 65536.

[0.1.16] - 2026-03-15

Changed

• Bumped duroxide to 0.1.26, duroxide-pg to 0.1.27.
• KV delta table support: fixes read-modify-write replay poisoning by separating current-execution mutations from prior-execution snapshots.

Added

• KV read-modify-write counter e2e test (sample_kv_read_modify_write_counter).

[0.1.15] - 2026-03-14

Changed

• Bumped duroxide dependency to 0.1.25.
• Patched local builds to use the sibling ../../providers/duroxide-pg checkout until a crates.io release includes the KV snapshot changes required by duroxide 0.1.25.
• Renamed KV APIs to the new kv_-prefixed surface: ctx.set_kv_value(), ctx.get_kv_value(), ctx.clear_kv_value(), ctx.clear_all_kv_values(), ctx.get_kv_value_from_instance(), client.get_kv_value(), and client.wait_for_kv_value().
• Raised MAX_KV_KEYS from 10 to 100.

Added

• New orchestration KV helpers: ctx.get_kv_all_values(), ctx.get_kv_all_keys(), ctx.get_kv_length(), and ctx.prune_kv_values_updated_before(cutoff_ms).
• New typed client conveniences: client.get_kv_value_typed() and client.wait_for_kv_value_typed().

[0.1.14] - 2026-03-13

• KV store support: Durable key-value store for per-instance state
  • OrchestrationContext: set_value(), get_value(), clear_value(), clear_all_values()
  • Client: get_value(), wait_for_value()
  • Constants: MAX_KV_KEYS, MAX_KV_VALUE_BYTES
• Added KV e2e tests (test_kv_store.py)
• Bumped duroxide to 0.1.24, duroxide-pg to 0.1.25

[0.1.13] - 2026-03-08

Added

• 5 new e2e tests: heterogeneous workers pipeline, starvation-safe tagged activity fallback, dual runtime tag cooperation, nested error handling propagation, error recovery with logging.
• MAX_WORKER_TAGS (5) and MAX_TAG_NAME_BYTES (256) constants exported.

Changed

• Bumped duroxide core from 0.1.22 to 0.1.23 (activity tag ack validation test).
• Bumped duroxide-pg from local path to published 0.1.24 (tag routing + migration fixes).

[0.1.10] - 2026-02-28

Added

• Typed APIs parity pass: typed scheduling/wait/event/dequeue variants and typed-path tests.
• Async block and advanced-feature parity suites aligned with Node/Java/.NET structure.

Changed

• Unified schedule/whenAll/whenAny terminology across docs and examples.
• Rust bridge and SDK parity hardening updates for cross-SDK consistency.

[0.1.9] - 2026-02-21

Added

• ctx.get_custom_status() — read the current custom status value from within an orchestration. Returns the status string or None if none has been set. Reflects all set_custom_status/reset_custom_status calls, including across turn boundaries and continue-as-new.

Changed

• Upgraded duroxide to 0.1.20, duroxide-pg to 0.1.22

[0.1.8] - 2026-02-15

Added

• Custom Status documentation — user guide and architecture docs for ctx.set_custom_status(), ctx.reset_custom_status(), and client.wait_for_status_change()
• Event Queues documentation — user guide and architecture docs for ctx.dequeue_event() and client.enqueue_event()
• Retry on Session documentation — user guide docs for ctx.schedule_activity_with_retry_on_session()
• Copilot Chat pattern — real-world example combining event queues, custom status, and continue-as-new for interactive chat bots
• Updated README with custom status, event queues, and retry-on-session API examples

Changed

• Bumped duroxide dependency to 0.1.19

Deprecated

• client.raise_event_persistent() — use client.enqueue_event() instead
• ctx.schedule_wait_persistent() — use ctx.dequeue_event() instead

[0.1.7] - 2026-02-14

Added

• Custom Status API — ctx.set_custom_status(status) and ctx.reset_custom_status() for setting/clearing custom status from within orchestrations (fire-and-forget, no yield needed)
• Custom Status on OrchestrationResult — custom_status and custom_status_version fields now available on all status results (get_status, wait_for_orchestration, wait_for_status_change)
• client.wait_for_status_change(instance_id, last_seen_version, poll_interval_ms, timeout_ms) — polls for custom status changes on an orchestration instance
• Event Queue API — ctx.dequeue_event(queue_name) for FIFO mailbox-style event consumption in orchestrations, paired with client.enqueue_event(instance_id, queue_name, data) for sending messages
• ctx.schedule_activity_with_retry_on_session(name, input, retry, session_id) — retry with session affinity (all attempts pinned to the same worker)
• Queue event kinds (QueueSubscribed, QueueEventDelivered) now included in read_execution_history event data

Changed

• Bumped duroxide dependency to 0.1.19
• Bumped duroxide-pg dependency to 0.1.21

[0.1.6] - 2026-02-13

Added

• init_tracing(log_file, log_level?, log_format?) — install a file-based tracing subscriber before runtime.start(). Uses first-writer-wins (try_init) so the runtime's built-in subscriber silently no-ops if one is already installed. Supports "json", "pretty", and "compact" (default) log formats.
• 3 new tests for init_tracing: import check, file write, invalid path error

[0.1.5] - 2026-02-12

Fixed

• Reverted premature tracing init change from 0.1.4 (library handles this correctly)

[0.1.3] - 2026-02-12

Added

• data field on history events (read_execution_history) — exposes activity results, inputs, errors, timer fire times, and all event-specific content as JSON strings
• Execution history example in README Admin APIs section
• New test: test_read_execution_history_data

[0.1.2] - 2026-02-10

Added

• ctx.get_client() on ActivityContext — activities can now start orchestrations, raise events, etc.
• runtime.metrics_snapshot() — get runtime metric counters (orchestration starts/completions, activity results, provider errors)
• Observability options on PyRuntimeOptions: log_level, log_format, service_name, service_version
• 5 new e2e tests: retry exhaustion, continue-as-new version upgrade, version routing, activity get_client, metrics snapshot (54 total)

[0.1.1] - 2026-02-10

Fixed

• README doc links now use absolute GitHub URLs so they work on PyPI

[0.1.0] - 2026-02-10

Added

• Generator-based orchestration API with deterministic replay
• Activity support with cooperative cancellation (ctx.is_cancelled())
• all() (fan-out/fan-in) and race() (select) composition primitives
• Durable timers (schedule_timer) and external events (wait_for_event)
• Sub-orchestrations (blocking and fire-and-forget)
• Continue-as-new for eternal orchestrations
• Versioned orchestration registration
• Deterministic utc_now() and new_guid()
• SQLite provider (in-memory and file-based)
• PostgreSQL provider via duroxide-pg-opt (long-polling with LISTEN/NOTIFY)
• Schema isolation for PostgreSQL (connect_with_schema)
• Full admin API: list instances, get info, executions, history, tree, delete, prune
• Structured tracing via Rust tracing crate (controlled by RUST_LOG)
• Activity retry with configurable backoff policy
• Decorator-based registration (@runtime.register_activity, @runtime.register_orchestration)
• Runtime with configurable concurrency and poll intervals
• 49 tests across e2e, races, admin API, and scenario suites
• Documentation: user guide, architecture guide