Update duroxide-python for duroxide 0.1.25: KV API renames, new bulk APIs

- Bump duroxide dependency to 0.1.25
- Rename KV methods: set_value→set_kv_value, get_value→get_kv_value, etc.
- Add bulk KV functions: get_kv_all_values, get_kv_all_keys, get_kv_length
- Add prune_kv_values function

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: affandar

CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [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

Cargo.toml

@@ -1,14 +1,14 @@
 [package]
 name = "duroxide-python"
-version = "0.1.14"
+version = "0.1.15"
 edition = "2021"
 
 [lib]
 name = "duroxide_python"
 crate-type = ["cdylib"]
 
 [dependencies]
-duroxide = { version = "0.1.24", features = ["sqlite"] }
+duroxide = { version = "0.1.25", features = ["sqlite"] }
 duroxide-pg = { version = "0.1.25" }
 pyo3 = { version = "0.23", features = ["extension-module"] }
 async-trait = "0.1"
@@ -19,5 +19,8 @@ dotenvy = "0.15"
 parking_lot = "0.12"
 tracing-subscriber = { version = "0.3", features = ["fmt", "env-filter", "json"] }
 
+[patch.crates-io]
+duroxide-pg = { path = "../../providers/duroxide-pg" }
+
 [profile.release]
 lto = true

README.md

@@ -16,10 +16,10 @@ Write durable workflows as Python generators. The Rust runtime handles replay, p
 - **Deterministic replay** — safe resume after crashes
 - **SQLite & PostgreSQL** — pluggable storage providers
 - **Custom Status** — `ctx.set_custom_status()` / `ctx.reset_custom_status()` for orchestration progress reporting, `client.wait_for_status_change()` for efficient polling
-- **KV Store** — durable per-instance state via `ctx.set_value()` / `ctx.get_value()` / `ctx.clear_value()` / `ctx.clear_all_values()`, plus `client.get_value()` / `client.wait_for_value()`
+- **KV Store** — durable per-instance state via `ctx.set_kv_value()` / `ctx.get_kv_value()` / `ctx.get_kv_all_values()` / `ctx.get_kv_all_keys()` / `ctx.get_kv_length()` / `ctx.clear_kv_value()` / `ctx.clear_all_kv_values()` / `ctx.prune_kv_values_updated_before()`, plus `client.get_kv_value()` / `client.wait_for_kv_value()`
 - **Event Queues** — `ctx.dequeue_event(queue_name)` for FIFO mailbox-style message passing, `client.enqueue_event()` to send messages
 - **Retry on Session** — `ctx.schedule_activity_with_retry_on_session()` for retry with session affinity
-- **Tag Routing** — worker tags for activity affinity (`MAX_WORKER_TAGS=5`, `MAX_TAG_NAME_BYTES=256`, `MAX_KV_KEYS=10`, `MAX_KV_VALUE_BYTES=16384`)
+- **Tag Routing** — worker tags for activity affinity (`MAX_WORKER_TAGS=5`, `MAX_TAG_NAME_BYTES=256`, `MAX_KV_KEYS=100`, `MAX_KV_VALUE_BYTES=16384`)
 - **Admin APIs** — instance management, metrics, pruning
 - **Activity client access** — `ctx.get_client()` lets activities start new orchestrations
 - **Runtime metrics** — `metrics_snapshot()` for orchestration/activity counters
@@ -186,17 +186,20 @@ Durable per-instance key-value state for orchestration coordination and request/
 ```python
 @runtime.register_orchestration("KvWorkflow")
 def kv_workflow(ctx, input):
-    ctx.set_value("status", "running")
+    ctx.set_kv_value("status", "running")
     result = yield ctx.schedule_activity("Compute", input)
-    ctx.set_value("result", str(result))
-    return result
+    ctx.set_kv_value("result", str(result))
+    snapshot = ctx.get_kv_all_values()
+    keys = ctx.get_kv_all_keys()
+    count = ctx.get_kv_length()
+    return {"result": result, "snapshot": snapshot, "keys": keys, "count": count}
 
 # External reads
-status = client.wait_for_value("instance-1", "status", 10000)
-result = client.get_value("instance-1", "result")
+status = client.wait_for_kv_value("instance-1", "status", 10000)
+result = client.get_kv_value("instance-1", "result")
 ```
 
-KV entries are scoped to a single orchestration instance and remain readable after completion until the instance is deleted or pruned.
+KV entries are scoped to a single orchestration instance and remain readable after completion until the instance is deleted or pruned. Use `ctx.prune_kv_values_updated_before(cutoff_ms)` to deterministically clear stale keys from prior turns when you only want to retain newer state.
 
 ## Event Queues
 

docs/architecture.md

@@ -359,30 +359,30 @@ KV operations are fire-and-forget orchestration context calls backed by provider
 ```
 Python                              Rust (PyO3)                        Provider (DB)
 ──────                              ───────────                        ─────────────
-ctx.set_value("status", "ready")
+ctx.set_kv_value("status", "ready")
   │
-  └─► orchestration_set_value(instance_id, "status", "ready")
+  └─► orchestration_set_kv_value(instance_id, "status", "ready")
         │
         └─► ORCHESTRATION_CTXS.get(instance_id)
               │
-              └─► ctx.set_value("status", "ready")
+              └─► ctx.set_kv_value("status", "ready")
                     │
                     └─► provider.upsert KV row for (instance_id, key)
 
-client.get_value(id, "status")
+client.get_kv_value(id, "status")
   │
-  └─► py.allow_threads(|| TOKIO_RT.block_on(client.get_value(id, "status")))
+  └─► py.allow_threads(|| TOKIO_RT.block_on(client.get_kv_value(id, "status")))
         │
-        └─► provider.get_value(id, "status")
+        └─► provider.get_kv_value(id, "status")
 
-client.wait_for_value(id, "status", timeout_ms)
+client.wait_for_kv_value(id, "status", timeout_ms)
   │
-  └─► py.allow_threads(|| TOKIO_RT.block_on(client.wait_for_value(...)))
+  └─► py.allow_threads(|| TOKIO_RT.block_on(client.wait_for_kv_value(...)))
         │
-        └─► repeated provider.get_value(...) polling until key exists or timeout
+        └─► repeated provider.get_kv_value(...) polling until key exists or timeout
 ```
 
-Cross-orchestration reads use the built-in `__duroxide_syscall:get_kv_value` activity. In Python this is exposed as `ctx.get_value_from_instance(instance_id, key)` and replays like any other scheduled activity.
+Cross-orchestration reads use the built-in `__duroxide_syscall:get_kv_value` activity. In Python this is exposed as `ctx.get_kv_value_from_instance(instance_id, key)` and replays like any other scheduled activity. The local in-memory snapshot also exposes `ctx.get_kv_all_values()`, `ctx.get_kv_all_keys()`, `ctx.get_kv_length()`, and `ctx.prune_kv_values_updated_before(cutoff_ms)` for bulk inspection and pruning without yielding.
 
 ## Event Queue Data Flow
 

docs/user-guide.md

@@ -387,29 +387,35 @@ KV entries are durable metadata scoped to a single orchestration instance. They
 ```python
 @runtime.register_orchestration("RequestServer")
 def request_server(ctx, input):
-    ctx.set_value("status", "ready")
+    ctx.set_kv_value("status", "ready")
     request = yield ctx.wait_for_event("request")
     response = request["command"][::-1]
-    ctx.set_value(f"response:{request['op_id']}", response)
+    ctx.set_kv_value(f"response:{request['op_id']}", response)
     return "done"
 
-status = client.wait_for_value("server-1", "status", 10000)
-response = client.get_value("server-1", "response:op-1")
+status = client.wait_for_kv_value("server-1", "status", 10000)
+response = client.get_kv_value("server-1", "response:op-1")
 ```
 
 **OrchestrationContext methods:**
-- `ctx.set_value(key, value)` — set or overwrite a key
-- `ctx.get_value(key)` — read the current value for a key in the active instance
-- `ctx.clear_value(key)` — remove a single key
-- `ctx.clear_all_values()` — clear all keys for the active instance
-- `ctx.get_value_from_instance(instance_id, key)` — read another instance's KV via the built-in syscall activity
+- `ctx.set_kv_value(key, value)` — set or overwrite a key
+- `ctx.get_kv_value(key)` — read the current value for a key in the active instance
+- `ctx.get_kv_all_values()` — return a snapshot dict of all current KV entries
+- `ctx.get_kv_all_keys()` — return the list of active keys
+- `ctx.get_kv_length()` — return the number of active keys
+- `ctx.clear_kv_value(key)` — remove a single key
+- `ctx.clear_all_kv_values()` — clear all keys for the active instance
+- `ctx.prune_kv_values_updated_before(cutoff_ms)` — prune keys older than the provided persisted-update cutoff
+- `ctx.get_kv_value_from_instance(instance_id, key)` — read another instance's KV via the built-in syscall activity
 
 **Client methods:**
-- `client.get_value(instance_id, key)` — read a key immediately
-- `client.wait_for_value(instance_id, key, timeout_ms)` — block until the key exists or timeout
+- `client.get_kv_value(instance_id, key)` — read a key immediately
+- `client.get_kv_value_typed(instance_id, key)` — read a key and JSON-decode it
+- `client.wait_for_kv_value(instance_id, key, timeout_ms)` — block until the key exists or timeout
+- `client.wait_for_kv_value_typed(instance_id, key, timeout_ms)` — wait for a key and JSON-decode it
 
 **Limits:**
-- `MAX_KV_KEYS = 10`
+- `MAX_KV_KEYS = 100`
 - `MAX_KV_VALUE_BYTES = 16384`
 
 ## Event Queues — Persistent FIFO Message Passing

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "duroxide"
-version = "0.1.14"
+version = "0.1.15"
 description = "Python SDK for the Duroxide durable execution runtime"
 readme = "README.md"
 license = { text = "MIT" }

python/duroxide/__init__.py

@@ -183,21 +183,32 @@ def wait_for_status_change(
         )
         return _parse_status(result)
 
-    def get_value(self, instance_id: str, key: str) -> "Optional[str]":
+    def get_kv_value(self, instance_id: str, key: str) -> "Optional[str]":
         """Read a single KV entry for the given instance."""
-        return self._native.get_value(instance_id, key)
+        return self._native.get_kv_value(instance_id, key)
 
-    def wait_for_value(self, instance_id: str, key: str, timeout_ms: int = 30000) -> str:
+    def get_kv_value_typed(self, instance_id: str, key: str):
+        """Read a single KV entry for the given instance and JSON-decode it."""
+        raw = self.get_kv_value(instance_id, key)
+        if raw is None:
+            return None
+        return json.loads(raw)
+
+    def wait_for_kv_value(self, instance_id: str, key: str, timeout_ms: int = 30000) -> str:
         """Wait for a KV value to be set on an instance."""
         try:
-            return self._native.wait_for_value(instance_id, key, timeout_ms)
+            return self._native.wait_for_kv_value(instance_id, key, timeout_ms)
         except RuntimeError as exc:
             if "timed out" in str(exc).lower():
                 raise TimeoutError(
                     f"Timed out waiting for value '{key}' on instance '{instance_id}'"
                 ) from exc
             raise
 
+    def wait_for_kv_value_typed(self, instance_id: str, key: str, timeout_ms: int = 30000):
+        """Wait for a KV value to be set on an instance and JSON-decode it."""
+        return json.loads(self.wait_for_kv_value(instance_id, key, timeout_ms))
+
     def cancel_instance(self, instance_id: str, reason: str = None):
         self._native.cancel_instance(instance_id, reason)
 
@@ -439,7 +450,7 @@ def metrics_snapshot(self):
 # Tag limits
 MAX_WORKER_TAGS = 5
 MAX_TAG_NAME_BYTES = 256
-MAX_KV_KEYS = 10
+MAX_KV_KEYS = 100
 MAX_KV_VALUE_BYTES = 16384
 
 

python/duroxide/context.py

@@ -16,10 +16,14 @@
     orchestration_set_custom_status,
     orchestration_reset_custom_status,
     orchestration_get_custom_status,
-    orchestration_set_value,
-    orchestration_get_value,
-    orchestration_clear_value,
-    orchestration_clear_all_values,
+    orchestration_set_kv_value,
+    orchestration_get_kv_value,
+    orchestration_get_kv_all_values,
+    orchestration_get_kv_all_keys,
+    orchestration_get_kv_length,
+    orchestration_clear_kv_value,
+    orchestration_clear_all_kv_values,
+    orchestration_prune_kv_values,
     activity_trace_log,
     activity_is_cancelled,
     activity_tag,
@@ -459,23 +463,39 @@ def get_custom_status(self) -> Optional[str]:
         """
         return orchestration_get_custom_status(self.instance_id)
 
-    def set_value(self, key: str, value: str):
+    def set_kv_value(self, key: str, value: str):
         """Set a key-value pair scoped to this orchestration instance."""
-        orchestration_set_value(self.instance_id, str(key), str(value))
+        orchestration_set_kv_value(self.instance_id, str(key), str(value))
 
-    def get_value(self, key: str) -> Optional[str]:
+    def get_kv_value(self, key: str) -> Optional[str]:
         """Get the current value for a key. Returns None if not set."""
-        return orchestration_get_value(self.instance_id, str(key))
+        return orchestration_get_kv_value(self.instance_id, str(key))
 
-    def clear_value(self, key: str):
+    def get_kv_all_values(self) -> dict[str, str]:
+        """Return a snapshot of all key-value pairs for this orchestration instance."""
+        return orchestration_get_kv_all_values(self.instance_id)
+
+    def get_kv_all_keys(self) -> list[str]:
+        """Return the list of KV keys currently set on this orchestration instance."""
+        return orchestration_get_kv_all_keys(self.instance_id)
+
+    def get_kv_length(self) -> int:
+        """Return the number of KV entries currently set on this orchestration instance."""
+        return orchestration_get_kv_length(self.instance_id)
+
+    def clear_kv_value(self, key: str):
         """Remove a single key from the KV store."""
-        orchestration_clear_value(self.instance_id, str(key))
+        orchestration_clear_kv_value(self.instance_id, str(key))
 
-    def clear_all_values(self):
+    def clear_all_kv_values(self):
         """Clear ALL key-value pairs for this orchestration instance."""
-        orchestration_clear_all_values(self.instance_id)
+        orchestration_clear_all_kv_values(self.instance_id)
+
+    def prune_kv_values_updated_before(self, cutoff_ms: int) -> int:
+        """Prune KV entries whose last persisted update is older than cutoff_ms."""
+        return orchestration_prune_kv_values(self.instance_id, cutoff_ms)
 
-    def get_value_from_instance(self, instance_id: str, key: str) -> ScheduledTask:
+    def get_kv_value_from_instance(self, instance_id: str, key: str) -> ScheduledTask:
         """Read a KV value from another orchestration instance via the built-in syscall activity."""
         return ScheduledTask({
             "type": "activity",