harness-sdk-python 0.13.3__tar.gz → 0.14.0__tar.gz

{harness_sdk_python-0.13.3 → harness_sdk_python-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: harness-sdk-python
-Version: 0.13.3
+Version: 0.14.0
 Summary: RunManager: the harness-sdk runs subsystem for Python Statewire hosts
 Project-URL: Repository, https://github.com/assistant-ui/harness-sdk
 License-Expression: MIT

{harness_sdk_python-0.13.3 → harness_sdk_python-0.14.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "harness-sdk-python"
-version = "0.13.3"
+version = "0.14.0"
 description = "RunManager: the harness-sdk runs subsystem for Python Statewire hosts"
 readme = "README.md"
 license = "MIT"

{harness_sdk_python-0.13.3 → harness_sdk_python-0.14.0}/src/harness_sdk/run_manager.py

@@ -17,9 +17,15 @@ or ``dispatching``), mid-run edit/reload with the stopping window,
 
 ``entry["dispatching"]`` is the dispatch record (absent between an applied and
 the next dispatch or take): the payload the run callback receives.
-``ctx.applied()`` clears it; ``steering.take()`` may refill it — at most one
-unapplied batch ever exists. Settle consumes the delivered batch, applied or not;
-steer entries still undelivered in the lane stay queued for the next run.
+``ctx.applied()`` confirms it; ``steering.take()`` may refill it — at most one
+unconfirmed batch ever exists. Settle consumes a confirmed batch; a batch
+still unconfirmed at settle returns to the front of its lanes. ``Complete``
+with an unconfirmed batch settles as an error. Steer entries still
+undelivered in the lane stay queued for the next run.
+
+``entry["epoch"]`` counts the entry's dispatches; a ``run/stop`` carrying an
+``epoch`` other than the live one rejects, so a replayed stop never ends a
+later leg of the same ``runId``.
 
 A mid-run stop or rewind opens a stopping window on the entry:
 ``stopping: {reason}`` plus, for rewinds, the staged dispatch as
@@ -534,6 +540,7 @@ class RunManager:
         self._dispatch_record = dict(record)
         self._stop_reason = None
         entry = self._ensure_entry()
+        entry["epoch"] = (plain(entry.get("epoch")) or 0) + 1
         entry["dispatching"] = record
         entry.pop("error", None)
         if messages:
@@ -570,6 +577,8 @@ class RunManager:
                     "run must return a RunManager outcome, got "
                     f"{type(outcome).__name__}"
                 )
+            if isinstance(outcome, RunManager.Complete) and self._dispatching:
+                raise RuntimeError("run returned Complete with an unconfirmed batch")
         except asyncio.CancelledError:
             self._settle(ctx)
             self._set_status("stopped")
@@ -593,12 +602,18 @@ class RunManager:
             self._ctx = None
             self._task = None
         self._dispatch_record = None
-        self._dispatching = []
         entry = self._ensure_entry()
-        record = plain(entry.get("dispatching"))
-        if record is not None and record["trigger"] != "steer" and record["messages"]:
-            self._dispatched_ids = ()
-        entry.pop("dispatching", None)
+        if self._dispatching:
+            self._unstage_dispatching()
+        else:
+            record = plain(entry.get("dispatching"))
+            if (
+                record is not None
+                and record["trigger"] != "steer"
+                and record["messages"]
+            ):
+                self._dispatched_ids = ()
+            entry.pop("dispatching", None)
         entry.pop("stopping", None)
 
     def _applied(self) -> None:
@@ -1212,6 +1227,9 @@ class RunManager:
         reason = (params or {}).get("reason", _ABSENT)
         if reason is not _ABSENT and not isinstance(reason, str):
             raise _reject("invalid-message", "reason must be a string")
+        epoch = (params or {}).get("epoch", _ABSENT)
+        if epoch is not _ABSENT and (isinstance(epoch, bool) or not isinstance(epoch, int)):
+            raise _reject("invalid-message", "epoch must be an integer")
         status = self._status()
         if status != "running":
             raise _reject("wrong-state", f"run/stop is rejected in {status}")
@@ -1220,6 +1238,10 @@ class RunManager:
             raise _reject(
                 "wrong-state", f"runId {run_id!r} does not name the live run"
             )
+        if epoch is not _ABSENT and epoch != plain(self._entry()["epoch"]):
+            raise _reject(
+                "wrong-state", f"epoch {epoch} does not name the live dispatch"
+            )
         if reason is not _ABSENT:
             self._stop_reason = reason
         entry = _Stop()
@@ -1411,7 +1433,7 @@ class RunManager:
                 raise RuntimeError("this run has already settled")
 
         def applied(self) -> None:
-            """Applied the current batch: clears the dispatch record."""
+            """Confirms the current batch durable: clears the dispatch record so settle consumes it."""
             self._ensure_active()
             self._manager._applied()
 

{harness_sdk_python-0.13.3 → harness_sdk_python-0.14.0}/tests/test_applied_visibility.py

@@ -60,7 +60,7 @@ async def test_parked_send_applies_with_its_queue_insert():
         call.finish(RunManager.Complete())
 
 
-async def test_unapplied_run_end_consumes_the_direct_dispatch():
+async def test_unconfirmed_run_end_requeues_the_direct_dispatch():
     script = Script()
     async with run_host(script) as (drv, host):
         seq = drv.post("run/enqueue", add("m1"))
@@ -69,10 +69,10 @@ async def test_unapplied_run_end_consumes_the_direct_dispatch():
         assert dispatching_ids(covered_state(drv, seq)) == ["m1"]
         call.fail(RuntimeError("boom"))
         await drv.wait_status("error")
-        assert queue_ids(drv.replica, "queue") == []
+        assert queue_ids(drv.replica, "queue") == ["m1"]
 
 
-async def test_unapplied_run_end_consumes_the_direct_steer_send():
+async def test_unconfirmed_run_end_requeues_the_direct_steer_send():
     script = Script()
     async with run_host(script) as (drv, host):
         seq = drv.post("run/steer", add("s1"))
@@ -81,7 +81,7 @@ async def test_unapplied_run_end_consumes_the_direct_steer_send():
         assert dispatching_ids(covered_state(drv, seq)) == ["s1"]
         call.fail(RuntimeError("boom"))
         await drv.wait_status("error")
-        assert queue_ids(drv.replica, "steerQueue") == []
+        assert queue_ids(drv.replica, "steerQueue") == ["s1"]
         assert queue_ids(drv.replica, "queue") == []
 
 

{harness_sdk_python-0.13.3 → harness_sdk_python-0.14.0}/tests/test_dispatching.py

@@ -78,7 +78,7 @@ async def test_applied_clears_dispatching_with_the_message_append():
         call.finish(RunManager.Complete())
 
 
-async def test_unapplied_run_end_consumes_the_delivered_item():
+async def test_unconfirmed_run_end_requeues_the_delivered_item_ahead():
     script = Script()
     async with run_host(script) as (drv, host):
         drv.post("run/enqueue", add("m1"))
@@ -88,7 +88,7 @@ async def test_unapplied_run_end_consumes_the_delivered_item():
         await drv.side("run/stop", {"runId": await drv.run_id()})
         call.finish(RunManager.Stop(dispatch_queue=False))
         await drv.wait_status("stopped")
-        assert queue_ids(drv.replica, "queue") == ["m2"]
+        assert queue_ids(drv.replica, "queue") == ["m1", "m2"]
         assert dispatching_ids(drv.replica) == []
         assert residence(drv, "m2") == ["queue"]
 

{harness_sdk_python-0.13.3 → harness_sdk_python-0.14.0}/tests/test_settle.py

@@ -1,9 +1,10 @@
 """Contract: command settlement. Every initiator settles accepted with its
 state-visible application — sends with their insert (a lane entry or a direct
 ``dispatching`` entry), edit/reload/continue at their dispatch. The run's
-outcome never travels through settlement: settle consumes every delivered
-item, applied or not; steer entries still undelivered in the lane stay queued,
-and any failure lands on ``state.error``."""
+outcome never travels through settlement: ``applied()`` confirms the delivered
+batch and settle consumes it; a batch still unconfirmed at settle returns to
+the front of its lanes, ``Complete`` with an unconfirmed batch settles as an
+error, and any failure lands on ``state.error``."""
 
 import asyncio
 
@@ -50,7 +51,7 @@ async def test_run_reject_lands_the_payload_on_state_error():
         )
         assert (await drv.res(seq))["type"] == "accepted"
         await drv.wait_status("error")
-        assert queue_ids(drv.replica, "queue") == []
+        assert queue_ids(drv.replica, "queue") == ["m1"]
         assert drv.run["error"] == {
             "message": "payment required",
             "reason": "payment-required",
@@ -58,18 +59,19 @@ async def test_run_reject_lands_the_payload_on_state_error():
         }
 
 
-async def test_unapplied_run_end_settles_the_send_accepted():
-    script = Script()
-    async with run_host(script) as (drv, host):
-        for name, outcome in [
-            ("m1", lambda call: call.fail(RuntimeError("boom"))),
-            ("m2", lambda call: call.finish(RunManager.Error(dispatch_queue=False))),
-        ]:
-            seq = drv.post("run/enqueue", add(name))
-            outcome(await script.next_call())
+async def test_unconfirmed_run_end_requeues_the_send():
+    for end in [
+        lambda call: call.fail(RuntimeError("boom")),
+        lambda call: call.finish(RunManager.Error(dispatch_queue=False)),
+    ]:
+        script = Script()
+        async with run_host(script) as (drv, host):
+            seq = drv.post("run/enqueue", add("m1"))
+            end(await script.next_call())
             assert (await drv.res(seq))["type"] == "accepted"
             await drv.wait_status("error")
-            assert queue_ids(drv.replica, "queue") == []
+            assert queue_ids(drv.replica, "queue") == ["m1"]
+            assert queue_ids(drv.replica, "steerQueue") == []
 
 
 async def test_rewind_settles_before_the_reruns_end():
@@ -88,14 +90,14 @@ async def test_rewind_settles_before_the_reruns_end():
                 await drv.wait_status("stopped")
 
 
-async def test_unapplied_run_end_consumes_the_delivered_batch():
+async def test_unconfirmed_run_end_requeues_the_delivered_batch():
     script = Script()
     async with run_host(script) as (drv, host):
         drv.batch([("run/enqueue", add("m1")), ("run/enqueue", add("m2"))])
         call = await script.next_call()
         call.fail(RuntimeError("boom"))
         await drv.wait_status("error")
-        assert queue_ids(drv.replica, "queue") == []
+        assert queue_ids(drv.replica, "queue") == ["m1", "m2"]
         assert drv.run["error"] == {"message": "boom"}
         await drv.command("run/steer", add("s1"), terminal=False)
         continued = await script.next_call()
@@ -104,7 +106,7 @@ async def test_unapplied_run_end_consumes_the_delivered_batch():
         assert [m["id"] for m in continued.ctx.steering.take()] == ["s1"]
 
 
-async def test_unapplied_run_end_consumes_taken_steered_items():
+async def test_unconfirmed_run_end_requeues_taken_steered_items():
     script = Script()
     async with run_host(script) as (drv, host):
         drv.post("run/enqueue", add("m1"))
@@ -115,7 +117,7 @@ async def test_unapplied_run_end_consumes_taken_steered_items():
         call.ctx.steering.take()
         call.fail(RuntimeError("boom"))
         await drv.wait_status("error")
-        assert queue_ids(drv.replica, "steerQueue") == []
+        assert queue_ids(drv.replica, "steerQueue") == ["s1"]
         assert queue_ids(drv.replica, "queue") == []
 
 
@@ -130,14 +132,17 @@ async def test_applied_removes_the_entries_for_good():
         assert queue_ids(drv.replica, "queue") == []
 
 
-async def test_complete_without_applied_consumes_the_dispatch():
+async def test_complete_with_unconfirmed_batch_settles_as_error():
     script = Script()
     async with run_host(script) as (drv, host):
         seq = drv.post("run/enqueue", add("m1"))
         (await script.next_call()).finish(RunManager.Complete())
         assert (await drv.res(seq))["type"] == "accepted"
-        await drv.wait_status("ready")
-        assert drv.replica["runs"] == []
+        await drv.wait_status("error")
+        assert queue_ids(drv.replica, "queue") == ["m1"]
+        assert drv.run["error"] == {
+            "message": "run returned Complete with an unconfirmed batch"
+        }
         script.no_call()
 
 
@@ -165,9 +170,9 @@ async def test_stop_lands_while_a_steer_is_parked():
         await asyncio.wait_for(call.ctx.stop_requested.wait(), 5)
         call.finish(RunManager.Stop(dispatch_queue=False))
         await drv.wait_status("stopped")
-        # The undelivered steer stays parked; the delivered dispatch is consumed.
+        # The undelivered steer stays parked; the unconfirmed dispatch requeues.
         assert queue_ids(drv.replica, "steerQueue") == ["s1"]
-        assert queue_ids(drv.replica, "queue") == []
+        assert queue_ids(drv.replica, "queue") == ["m1"]
 
 
 async def test_rewind_edit_settles_at_its_dispatch():
@@ -195,7 +200,7 @@ async def test_rewind_rerun_failure_lands_on_state_error():
         assert drv.run["error"] == {"message": "payment required", "code": 402}
 
 
-async def test_task_cancellation_consumes_entries_and_settles_sends():
+async def test_task_cancellation_requeues_entries_and_settles_sends():
     script = Script()
     async with run_host(script) as (drv, host):
         seq = drv.batch([("run/enqueue", add("m1")), ("run/enqueue", add("m2"))])
@@ -204,7 +209,7 @@ async def test_task_cancellation_consumes_entries_and_settles_sends():
         task.cancel()
         assert (await drv.res(seq))["type"] == "accepted"
         await drv.wait_status("stopped")
-        assert queue_ids(drv.replica, "queue") == []
+        assert queue_ids(drv.replica, "queue") == ["m1", "m2"]
         assert task.cancelled()
 
 

{harness_sdk_python-0.13.3 → harness_sdk_python-0.14.0}/tests/test_stop_continue.py

@@ -336,3 +336,45 @@ async def test_same_tick_send_and_continue_dispatch_one_run_with_messages():
         continued.applied()
         continued.finish(RunManager.Complete())
         await drv.wait_status("ready")
+
+
+async def test_stop_with_the_live_epoch_is_accepted():
+    script = Script()
+    async with run_host(script) as (drv, host):
+        drv.post("run/enqueue", add("m1"))
+        call = await script.next_call()
+        call.applied()
+        await drv.wait(lambda s: bool(s["runs"]) and s["runs"][0].get("epoch") == 1)
+        pending = await drv.stop({"epoch": 1}, terminal=False)
+        call.finish(RunManager.Stop(dispatch_queue=False))
+        assert (await drv.res(pending["seq"]))["type"] == "accepted"
+        await drv.wait_status("stopped")
+
+
+async def test_stale_epoch_stop_cannot_end_a_later_leg():
+    script = Script()
+    async with run_host(script) as (drv, host):
+        drv.post("run/enqueue", add("m1"))
+        call = await script.next_call()
+        call.applied()
+        await drv.stop(terminal=False)
+        call.finish(RunManager.Stop(dispatch_queue=False))
+        await drv.wait_status("stopped")
+        await drv.command("run/enqueue", add("m2"), terminal=False)
+        leg2 = await script.next_call()
+        assert leg2.ctx.trigger == "stop-continue"
+        await drv.wait(lambda s: s["runs"][0].get("epoch") == 2)
+        assert_rejected(await drv.stop({"epoch": 1}), "wrong-state")
+        assert drv.replica["status"] == "running"
+        leg2.applied()
+        leg2.finish(RunManager.Complete())
+
+
+async def test_stop_rejects_a_non_integer_epoch():
+    script = Script()
+    async with run_host(script) as (drv, host):
+        drv.post("run/enqueue", add("m1"))
+        call = await script.next_call()
+        call.applied()
+        assert_rejected(await drv.stop({"epoch": "1"}), "invalid-message")
+        call.finish(RunManager.Complete())

{harness_sdk_python-0.13.3 → harness_sdk_python-0.14.0}/tests/test_stopping_window.py

@@ -249,6 +249,7 @@ async def test_entry_keys_are_absent_when_empty():
         await drv.wait_status("running")
         assert set(drv.run.keys()) == {
             "runId",
+            "epoch",
             "status",
             "queue",
             "steerQueue",
@@ -258,4 +259,11 @@ async def test_entry_keys_are_absent_when_empty():
         await drv.wait(lambda s: "dispatching" not in s["runs"][0])
         call.fail(RuntimeError("boom"))
         await drv.wait_status("error")
-        assert set(drv.run.keys()) == {"runId", "status", "queue", "steerQueue", "error"}
+        assert set(drv.run.keys()) == {
+            "runId",
+            "epoch",
+            "status",
+            "queue",
+            "steerQueue",
+            "error",
+        }