harness-sdk-python 0.18.0__tar.gz → 0.19.0__tar.gz

{harness_sdk_python-0.18.0 → harness_sdk_python-0.19.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: harness-sdk-python
-Version: 0.18.0
+Version: 0.19.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
 Requires-Python: <4.0,>=3.12
-Requires-Dist: pinned<0.13,>=0.12.0
-Requires-Dist: statewire<0.10,>=0.9.2
+Requires-Dist: pinned<0.14,>=0.13.0
+Requires-Dist: statewire<0.11,>=0.10.0
 Provides-Extra: deepagents
 Requires-Dist: deepagents>=0.6.12; extra == 'deepagents'
 Requires-Dist: langchain-core>=0.3; extra == 'deepagents'

{harness_sdk_python-0.18.0 → harness_sdk_python-0.19.0}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "harness-sdk-python"
-version = "0.18.0"
+version = "0.19.0"
 description = "RunManager: the harness-sdk runs subsystem for Python Statewire hosts"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.12,<4.0"
-dependencies = ["statewire>=0.9.2,<0.10", "pinned>=0.12.0,<0.13"]
+dependencies = ["statewire>=0.10.0,<0.11", "pinned>=0.13.0,<0.14"]
 
 [project.optional-dependencies]
 postgres = ["langgraph-checkpoint-postgres>=2.0.0"]

{harness_sdk_python-0.18.0 → harness_sdk_python-0.19.0}/src/harness_sdk/run_manager.py

@@ -29,8 +29,11 @@ own continuation state (``ctx.state`` or an external checkpointer).
 ``epoch`` counts the entry's dispatches (not redeliveries); a ``run/stop``
 carrying an ``epoch`` other than the live one rejects. A mid-run stop or
 rewind opens a stopping window (``stopping: {reason}`` plus, for rewinds, the
-staged dispatch as ``nextDispatch``); on run end one envelope promotes
-``nextDispatch`` into ``dispatching`` and clears the window.
+staged dispatch as ``nextDispatch``) and ``status`` reads ``stopping`` until
+the run settles; the ``run/stop`` verdict follows that settle and its flush,
+so a settled stop covers every durable effect the runner enlisted. On run end
+one envelope promotes ``nextDispatch`` into ``dispatching`` and clears the
+window.
 """
 
 import asyncio
@@ -38,7 +41,7 @@ import logging
 from dataclasses import dataclass, field
 from typing import Any, AsyncIterator, Callable, Coroutine, Iterable, Protocol
 
-from pinned.trays import Tray, TrayDescriptor, TrayCtx
+from pinned.trays import Tray, TrayDescriptor, TrayCtx, inbox
 from pinned.traystore import persistent, persistent_outbox, persistent_queue
 from statepatch import observable
 from statewire import StatewireReject
@@ -78,6 +81,15 @@ def _reject(reason: str, message: str) -> StatewireReject:
     return StatewireReject(message, payload={"reason": reason})
 
 
+def _public(message: dict[str, Any]) -> dict[str, Any]:
+    """The message without its admission tag; the wire state is public."""
+    return {k: v for k, v in message.items() if k != "~admit"}
+
+
+def _public_record(record: dict[str, Any]) -> dict[str, Any]:
+    return {**record, "messages": [_public(m) for m in record["messages"]]}
+
+
 def _run_id_of(params: Any) -> str:
     run_id = params.get("runId") if isinstance(params, dict) else None
     if not isinstance(run_id, str) or run_id == "":
@@ -204,6 +216,7 @@ class RunManager(Tray):
     stopReason = persistent(None)
     dispatchedIds = persistent([])
     dispatching = observable(None)  # view: the unconfirmed batch record
+    steerView = observable([])  # view: the steer lane without admission tags
 
     state = observable(
         {
@@ -211,12 +224,13 @@ class RunManager(Tray):
             "status": status,
             "epoch": epoch,
             "queue": queue,
-            "steerQueue": steerQueue,
+            "steerQueue": steerView,
             "dispatching": dispatching,
             "stopping": stopping,
             "nextDispatch": nextDispatch,
             "inputRequests": inputRequests,
             "error": error,
+            "stopReason": stopReason,
         }
     )
 
@@ -225,6 +239,7 @@ class RunManager(Tray):
         self._intake: list[Any] = []
         self._outcome: Any = None
         self._stop_staged = False
+        self._stop_waiters: list["asyncio.Future[Any]"] = []
         self._staged_rewind: _Rewind | None = None
         self._batch: list[tuple[str, dict[str, Any]]] = []
         self._pending_takes = 0
@@ -245,7 +260,10 @@ class RunManager(Tray):
         self._thread = api
         self._schedule = api.schedule
         self._hydrate_machine()
+        self._mirror_steer()
+        unsubscribe = self.steerQueue.subscribe(lambda _op: self._mirror_steer())
         yield
+        unsubscribe()
 
     class Thread(Protocol):
         """The thread projection RunManager reads; the host owns the tree."""
@@ -277,14 +295,16 @@ class RunManager(Tray):
             record = recorded["item"]["record"]
             lanes = recorded["item"]["lanes"]
             self._batch = list(zip(lanes, record["messages"]))
-            self.dispatching.value = record
+            self.dispatching.value = _public_record(record)
         else:
             self.dispatching.value = None
         if recorded is not None:
             # heal a dispatch torn after its outbox write landed
             self._clear_input()
             self.error.value = None
-            self._set_status("running")
+            self._set_status(
+                "stopping" if self.stopping.value is not None else "running"
+            )
         staged = self.nextDispatch.value
         if (
             staged is not None
@@ -356,6 +376,9 @@ class RunManager(Tray):
     def _is_dispatching(self, message_id: str) -> bool:
         return any(item["id"] == message_id for _, item in self._batch)
 
+    def _mirror_steer(self) -> None:
+        self.steerView.value = [_public(item) for item in self.steerQueue.value]
+
     def _sync_steering(self) -> None:
         ctx = self._run_live
         if ctx is None:
@@ -381,6 +404,12 @@ class RunManager(Tray):
             self._apply(entry, fx)
         return fx
 
+    def _resolve_stop_waiters(self) -> None:
+        waiters, self._stop_waiters = self._stop_waiters, []
+        for future in waiters:
+            if not future.done():
+                future.set_result(None)
+
     def _settle_applied(self, fx: _Effects) -> None:
         for future, applied, result in fx.staged_sends:
             applied()
@@ -417,6 +446,7 @@ class RunManager(Tray):
                 self._idle_action(fx)
             if self.outcome.value is not None:
                 self.outcome.value = None  # the follow-on's writes are enlisted ahead
+            self._resolve_stop_waiters()
         if self._in_flight() and (
             self._stop_staged or self._staged_rewind is not None
         ):
@@ -434,7 +464,9 @@ class RunManager(Tray):
                     self._staged_rewind = None
                     self.nextDispatch.value = None
                 self.stopping.value = {"reason": "stop"}
-            if not entry.future.done():
+                self._set_status("stopping")
+                self._stop_waiters.append(entry.future)  # the verdict waits for the settle
+            elif not entry.future.done():
                 entry.future.set_result(None)
             return
         if isinstance(entry, _Continue):
@@ -577,7 +609,7 @@ class RunManager(Tray):
             if added:
                 self.dispatchedIds.value = [*known, *added]
         self._set_status("running")
-        self.dispatching.value = record
+        self.dispatching.value = _public_record(record)
         self._idle.clear()
         self.kick()
 
@@ -610,7 +642,7 @@ class RunManager(Tray):
     def _make_run_ctx(self, item: Any) -> "RunManager.RunContext":
         record = item["record"]
         messages = [
-            {k: v for k, v in message.items() if k != "meta"}
+            {k: v for k, v in message.items() if k not in ("meta", "~admit")}
             for message in record["messages"]
         ]
         ctx = RunManager.RunContext(
@@ -692,6 +724,7 @@ class RunManager(Tray):
                 rewind.applied_sent = True
             self._set_status("stopped")
             self.outcome.value = None
+            self._resolve_stop_waiters()
             self._settle_applied(fx)
             self._idle.set()
             raise  # staged intake settled; a cancelled run starts no dispatch
@@ -849,7 +882,7 @@ class RunManager(Tray):
         self._batch.append((e.lane, self._stamped(e.message, e.meta)))
         self.dispatching.value = {
             "trigger": self._send_trigger(),
-            "messages": [item for _, item in self._batch],
+            "messages": [_public(item) for _, item in self._batch],
         }
 
     def _dispatch_staged(
@@ -880,6 +913,7 @@ class RunManager(Tray):
         self._staged_rewind = rewind
         if self._in_flight():
             self.stopping.value = {"reason": rewind.type}
+            self._set_status("stopping")
             self.nextDispatch.value = self._record_of(
                 rewind.type,
                 list(rewind.messages),
@@ -1321,6 +1355,15 @@ class RunManager(Tray):
     ) -> Any:
         return await self._send("steerQueue", params, meta, applied)
 
+    @inbox
+    def admit_steer(self, message: dict[str, Any]) -> None:
+        """Durably admit one steer message; a ``ctx.dispatch`` target."""
+        if not isinstance(message, dict) or not isinstance(message.get("id"), str):
+            raise TypeError(f"a steer message needs a string id, got {message!r}")
+        self.steerQueue.append(self._stamped(message, message.get("meta")))
+        self._sync_steering()
+        self._schedule(self._advance)
+
     async def dequeue(self, params: Any) -> None:
         message_id = params.get("messageId") if isinstance(params, dict) else None
         if not isinstance(message_id, str):
@@ -1328,7 +1371,7 @@ class RunManager(Tray):
         return await self._stage(_Dequeue(message_id))
 
     def _check_rewind_gate(self, command: str) -> None:
-        if self._status() == "running":
+        if self._status() in ("running", "stopping"):
             if "rewind-during-run" not in self.capabilities:
                 raise _reject(
                     "capability-missing",
@@ -1402,7 +1445,11 @@ class RunManager(Tray):
         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":
+        stop_held = (self.stopping.value or {}).get("reason") == "stop"
+        # a rewind-held window still admits a stop: it clears the staged rewind
+        if status not in ("running", "stopping") or (
+            status == "stopping" and stop_held
+        ):
             raise _reject("wrong-state", f"run/stop is rejected in {status}")
         run_id = _run_id_of(params)
         if run_id != self.runId.value:
@@ -1551,13 +1598,17 @@ class RunManager(Tray):
             added = [item["id"] for item in items if item["id"] not in known]
             if added:
                 manager.dispatchedIds.value = [*known, *added]
-            manager.dispatching.value = {"trigger": "steer", "messages": items}
+            manager.dispatching.value = {
+                "trigger": "steer",
+                "messages": [_public(item) for item in items],
+            }
             self._ctx._message_meta.update(
                 {item["id"]: item.get("meta") for item in items}
             )
             manager._sync_steering()
             return tuple(
-                {k: v for k, v in item.items() if k != "meta"} for item in items
+                {k: v for k, v in item.items() if k not in ("meta", "~admit")}
+                for item in items
             )
 
     @dataclass(frozen=True, eq=False)
@@ -1644,6 +1695,7 @@ class RunManager(Tray):
 
         def enlist(self, effect: Any) -> None:
             """Enlist an opaque durable effect ordered with the machine's writes."""
+            self._ensure_active()
             self._tray_ctx.enlist(effect)
 
         def _ensure_active(self) -> None:

harness_sdk_python-0.19.0/tests/test_admit_steer.py

@@ -0,0 +1,118 @@
+"""Contract: ``RunManager.admit_steer`` is the ``ctx.dispatch`` target for
+durable steering — a pooled command admits one steer message exactly once
+across a crash redelivery, and the public seams (``steering.take()``,
+``ctx.messages``, the replicated state view) never carry the admission tag
+the durable queue record keeps for redelivery dedup."""
+
+import asyncio
+import copy
+
+from pinned import PinnedWorker
+from pinned.testing import MemoryStateStore
+from run_helpers import Script, add, msg
+from statewire_helpers import apply_ops, attach_of, post_frame, statewire_client
+
+from harness_sdk import RunManager, run_manager
+from statewire import Statewire, command
+
+
+def make_host(script: Script):
+    class Host(Statewire):
+        gate = asyncio.Event()
+        live = None
+
+        async def lifespan(self):
+            type(self).live = self
+            self.state = {}
+            yield
+
+        async def get_message_meta(self, message_id):
+            return await script.get_message_meta(message_id)
+
+        @run_manager()
+        async def runs(self, ctx):
+            return await script.run(ctx)
+
+        @command("run/steerDurable")
+        async def steer_durable(self, params, *, ctx):
+            runs = await self.runs.get()
+            outcome = await ctx.dispatch(runs.admit_steer, params["message"])
+            await type(self).gate.wait()
+            return {"outcome": outcome}
+
+        @command("run/enqueue")
+        async def run_enqueue(self, params, *, ctx):
+            runs = await self.runs.get()
+            return await runs.enqueue(params, applied=ctx.applied)
+
+    return Host
+
+
+def statement(seq, method, params):
+    return {"method": method, "params": [params], "seq": seq}
+
+
+async def cmds_until(stream, entry, limit=10):
+    seen = []
+    for _ in range(limit):
+        event = await stream.next_event()
+        seen.extend(event.get("cmd", []))
+        if entry in seen:
+            return seen
+    raise AssertionError(f"{entry} never rode the stream: {seen}")
+
+
+async def test_admit_steer_admits_exactly_once_and_the_run_sees_no_tag():
+    store = MemoryStateStore()
+    script = Script()
+    host = make_host(script)
+    async with statewire_client(host, worker=PinnedWorker(state_store=store)) as (
+        app,
+        client,
+    ):
+        async with attach_of(app, {"headers": {}}) as stream:
+            await stream.next_event()
+            frame = {
+                "cmd": [statement(1, "run/steerDurable", {"message": msg("s1")})]
+            }
+            assert (await post_frame(client, frame)).status_code == 200
+            machine = await host.live.runs.get()
+            while not machine.steerQueue.value:
+                await asyncio.sleep(0)
+            await host.live._frontier.wait()
+
+    script2 = Script()
+    host2 = make_host(script2)
+    host2.gate.set()
+    async with statewire_client(host2, worker=PinnedWorker(state_store=store)) as (
+        app,
+        client,
+    ):
+        async with attach_of(app, {"headers": {}}) as stream:
+            replica: dict = {}
+            apply_ops(replica, copy.deepcopy(await stream.next_event()))
+            # replay of the redelivered seq re-emits its recorded outcome
+            frame = {
+                "cmd": [statement(1, "run/steerDurable", {"message": msg("s1")})]
+            }
+            assert (await post_frame(client, frame)).status_code == 200
+            await cmds_until(
+                stream,
+                {"seq": 1, "type": "result", "payload": {"outcome": "admitted"}},
+            )
+            machine = await host2.live.runs.get()
+            # the durable record keeps the dedup tag; the state view never shows it
+            (entry,) = machine.steerQueue.value
+            assert entry["~admit"] == ["c1", 1]
+            assert replica["runs"][0]["steerQueue"] == [msg("s1")]
+
+            frame = {"cmd": [statement(2, "run/enqueue", add("m1"))]}
+            assert (await post_frame(client, frame)).status_code == 200
+            call = await script2.next_call()
+            call.applied()
+            (taken,) = call.ctx.steering.take()
+            assert taken == msg("s1")
+            call.applied()
+            call.finish(RunManager.Complete())
+            await cmds_until(stream, {"seq": 2, "dur": True})
+            assert machine.steerQueue.value == []

{harness_sdk_python-0.18.0 → harness_sdk_python-0.19.0}/tests/test_batches.py

@@ -59,27 +59,15 @@ async def test_steer_and_stop_in_one_batch_nets_to_stop():
             [("run/steer", add("s1")), ("run/stop", {"runId": await drv.run_id()})]
         )
         assert (await drv.res(first))["type"] == "accepted"
-        assert (await drv.res(first + 1))["type"] == "accepted"
+        assert (await drv.res(first + 1, terminal=False))["type"] == "pending"
         await asyncio.wait_for(call.ctx.stop_requested.wait(), 5)
         call.finish(RunManager.Stop(dispatch_queue=False))
+        assert (await drv.res(first + 1))["type"] == "accepted"
         await drv.wait_status("stopped")
         assert queue_ids(drv.replica, "steerQueue") == ["s1"]
         script.no_call()
 
 
-async def test_stop_settles_at_the_stopping_write():
-    script = Script()
-    async with run_host(script) as (drv, host):
-        drv.post("run/enqueue", add("m1"))
-        call = await script.next_call()
-        call.applied()
-        settled = await drv.stop()
-        assert settled["type"] == "accepted"
-        assert drv.replica["status"] == "running"
-        call.finish(RunManager.Stop(dispatch_queue=False))
-        await drv.wait_status("stopped")
-
-
 class TailScript(Script):
     """get_message_meta suspends, pushing staging past the handler prefix."""
 

{harness_sdk_python-0.18.0 → harness_sdk_python-0.19.0}/tests/test_durability.py

@@ -110,9 +110,11 @@ async def test_a_stale_epoch_stop_rejects_across_a_redelivery():
         assert redelivered.ctx.attempts == 2
         await drv2.wait(lambda s: run_of(s)["epoch"] == 1)  # deliveries never bump it
         assert_rejected(await drv2.stop({"epoch": 2}, terminal=False), "wrong-state")
-        assert (await drv2.stop({"epoch": 1}))["type"] == "accepted"
-        assert redelivered.ctx.stop_requested.is_set()
+        pending = await drv2.stop({"epoch": 1}, terminal=False)
+        assert pending["type"] == "pending"
+        await asyncio.wait_for(redelivered.ctx.stop_requested.wait(), 5)
         redelivered.finish(RunManager.Stop(dispatch_queue=False))
+        assert (await drv2.res(pending["seq"]))["type"] == "accepted"
         await drv2.wait_status("stopped")
 
 
@@ -159,6 +161,7 @@ async def test_a_staged_rewind_survives_a_crash_in_the_stopping_window():
     async with run_host(script2, store=crashed, capabilities=REWIND) as (drv2, host2):
         redelivered = await script2.next_call()
         assert redelivered.ctx.stop_requested.is_set()
+        assert drv2.replica["status"] == "stopping"  # the window hydrates with its status
         redelivered.finish(RunManager.Stop(dispatch_queue=False))
         rewind = await script2.next_call()
         assert rewind.ctx.trigger == "message-edit"
@@ -169,6 +172,30 @@ async def test_a_staged_rewind_survives_a_crash_in_the_stopping_window():
         await drv2.wait_status("ready")
 
 
+async def test_the_stopping_status_survives_a_crash_in_the_stop_window():
+    store = MemoryStateStore()
+    script = Script()
+    async with run_host(script, store=store) as (drv, host):
+        drv.post("run/enqueue", add("m1"))
+        call = await script.next_call()
+        call.applied()
+        await drv.stop(terminal=False)
+        await asyncio.wait_for(call.ctx.stop_requested.wait(), 5)
+        await drv.wait_status("stopping")
+        await flush(host)
+        crashed = survivors(store)
+
+    script2 = Script()
+    async with run_host(script2, store=crashed) as (drv2, host2):
+        assert drv2.replica["status"] == "stopping"
+        assert run_of(drv2.replica)["stopping"] == {"reason": "stop"}
+        redelivered = await script2.next_call()
+        assert redelivered.ctx.stop_requested.is_set()
+        redelivered.finish(RunManager.Stop(dispatch_queue=False))
+        await drv2.wait_status("stopped")
+        assert run_of(drv2.replica)["stopping"] is None
+
+
 async def test_an_applied_batch_redelivers_as_a_resume():
     store = MemoryStateStore()
     script = Script()
@@ -269,3 +296,30 @@ async def test_input_answers_survive_a_restart_mid_answering():
         resumed.applied()
         resumed.finish(RunManager.Complete())
         await drv2.wait_status("ready")
+
+
+async def test_the_stop_reason_survives_a_restart_until_the_next_dispatch():
+    store = MemoryStateStore()
+    script = Script()
+    async with run_host(script, store=store) as (drv, host):
+        drv.post("run/enqueue", add("m1"))
+        call = await script.next_call()
+        call.applied()
+        await drv.stop({"reason": "user-stop"}, terminal=False)
+        call.finish(RunManager.Stop(dispatch_queue=False))
+        await drv.wait_status("stopped")
+        assert drv.run["stopReason"] == "user-stop"
+        await flush(host)
+        crashed = survivors(store)
+
+    script2 = Script()
+    async with run_host(script2, store=crashed) as (drv2, host2):
+        assert drv2.replica["status"] == "stopped"
+        assert drv2.run["stopReason"] == "user-stop"
+        drv2.post("run/enqueue", add("m2"))
+        drained = await script2.next_call()
+        assert drained.ctx.trigger == "stop-continue"
+        await drv2.wait(lambda s: run_of(s)["stopReason"] is None)
+        drained.applied()
+        drained.finish(RunManager.Complete())
+        await drv2.wait_status("ready")

{harness_sdk_python-0.18.0 → harness_sdk_python-0.19.0}/tests/test_outcomes.py

@@ -21,6 +21,7 @@ async def test_activation_mounts_the_ready_entry():
                     "nextDispatch": None,
                     "inputRequests": None,
                     "error": None,
+                    "stopReason": None,
                 }
             ],
         }

{harness_sdk_python-0.18.0 → harness_sdk_python-0.19.0}/tests/test_restore.py

@@ -40,6 +40,7 @@ async def test_a_fresh_store_seeds_ready():
             "nextDispatch": None,
             "inputRequests": None,
             "error": None,
+            "stopReason": None,
         }
         script.no_call()
 

{harness_sdk_python-0.18.0 → harness_sdk_python-0.19.0}/tests/test_run_crash_sweep.py

@@ -5,8 +5,8 @@ limit; each scenario is swept over every crash point. Whatever prefix
 survived, the restarted machine must satisfy: an accepted message or edit is
 either consumed by a durably settled dispatch or delivered exactly once after
 the restart; an accepted input answer reaches a run's input_outcomes; status
-"input-required" always carries inputRequests; and a fresh send still reaches
-a run.
+"input-required" always carries inputRequests; an open stop window and status
+"stopping" imply each other; and a fresh send still reaches a run.
 
 The redelivery lands on the correct arm of the run callback: a batch not yet
 durably applied re-presents in dispatch mode with the full record, a durably
@@ -266,6 +266,10 @@ async def flush(runs) -> None:
 def check_wire(runs) -> None:
     if runs.status.value == "input-required":
         assert runs.inputRequests.value, "input-required without inputRequests"
+    if runs.stopping.value is not None:
+        assert runs.status.value == "stopping", "an open stop window without its status"
+    elif runs.status.value == "stopping":
+        raise AssertionError("stopping status without an open stop window")
 
 
 async def settle_call(runs, call, seen: set[str]) -> None:

{harness_sdk_python-0.18.0 → harness_sdk_python-0.19.0}/tests/test_stop_continue.py

@@ -1,7 +1,7 @@
 import asyncio
 
 import pytest
-from run_helpers import Script, add, assert_rejected, run_host, run_of
+from run_helpers import Script, add, assert_rejected, machine, run_host, run_of
 
 from harness_sdk import RunManager
 
@@ -15,7 +15,7 @@ async def test_stop_is_not_optimistic():
         pending = await drv.stop(terminal=False)
         assert pending["type"] == "pending"
         await asyncio.wait_for(call.ctx.stop_requested.wait(), 5)
-        assert drv.replica["status"] == "running"
+        await drv.wait_status("stopping")
         call.finish(RunManager.Stop(dispatch_queue=False))
         settled = await drv.res(pending["seq"])
         assert settled["type"] == "accepted"
@@ -45,12 +45,15 @@ async def test_stop_reason_is_visible_on_the_start_context():
         call = await script.next_call()
         call.applied()
         assert call.ctx.stop_reason is None
+        await drv.run_id()
+        assert drv.run["stopReason"] is None
         pending = await drv.stop({"reason": "user-stop"}, terminal=False)
         await asyncio.wait_for(call.ctx.stop_requested.wait(), 5)
         assert call.ctx.stop_reason == "user-stop"
         call.finish(RunManager.Stop(dispatch_queue=False))
         assert (await drv.res(pending["seq"]))["type"] == "accepted"
         await drv.wait_status("stopped")
+        assert drv.run["stopReason"] == "user-stop"
 
 
 async def test_stop_reason_resets_for_the_next_run():
@@ -64,6 +67,7 @@ async def test_stop_reason_resets_for_the_next_run():
         call.finish(RunManager.Stop(dispatch_queue=True))
         drain = await script.next_call()
         assert drain.ctx.stop_reason is None
+        await drv.wait(lambda s: run_of(s)["stopReason"] is None)
 
 
 async def test_stop_rejects_malformed_params():
@@ -195,6 +199,52 @@ async def test_stop_settles_even_when_the_run_completes_normally():
         await drv.wait_status("ready")
 
 
+async def test_stop_verdict_awaits_the_settle_and_the_checkpoint_drain():
+    script = Script()
+    async with run_host(script) as (drv, host):
+        drv.post("run/enqueue", add("m1"))
+        call = await script.next_call()
+        call.applied()
+        release = asyncio.Event()
+        durable = asyncio.Event()
+
+        async def checkpoint():
+            await release.wait()
+            durable.set()
+
+        call.ctx.enlist(checkpoint())
+        runs = await machine(host.live)
+        verdict = asyncio.ensure_future(
+            runs.stop({"runId": await drv.run_id()}, applied=lambda: None)
+        )
+        await asyncio.wait_for(call.ctx.stop_requested.wait(), 5)
+        await asyncio.sleep(0.02)
+        assert not verdict.done()  # the run is still winding down
+        call.finish(RunManager.Stop(dispatch_queue=False))
+        await asyncio.wait_for(runs.idle.wait(), 5)
+        assert runs.status.value == "stopped"
+        await asyncio.sleep(0.02)
+        assert not verdict.done()  # the checkpoint drain is still open
+        release.set()
+        assert await asyncio.wait_for(verdict, 5) is None
+        assert durable.is_set()  # every enlisted checkpoint durable before the verdict
+
+
+async def test_a_late_enlist_after_the_run_settled_raises():
+    script = Script()
+    async with run_host(script) as (drv, host):
+        drv.post("run/enqueue", add("m1"))
+        call = await script.next_call()
+        await drv.run_id()
+        call.applied()
+        call.finish(RunManager.Complete())
+        await drv.wait(lambda s: run_of(s)["runId"] is None)
+        straggler = asyncio.sleep(0)
+        with pytest.raises(RuntimeError, match="settled"):
+            call.ctx.enlist(straggler)
+        straggler.close()
+
+
 @pytest.mark.parametrize(
     "end,continue_type",
     [("error", "error-continue"), ("stopped", "stop-continue")],

{harness_sdk_python-0.18.0 → harness_sdk_python-0.19.0}/tests/test_stopping_window.py

@@ -1,10 +1,12 @@
 """Contract: the stopping window. Three openers — run/stop, mid-run
 edit/reload, and the enqueue/steer edit-of-dispatched form — write
-``stopping: {reason}`` (plus the staged rewind as ``nextDispatch``) and
-settle accepted with that write, ``status`` staying "running". On run end
-one envelope promotes ``nextDispatch`` into ``dispatching`` and clears the
-window; a later stop/rewind replaces the staged dispatch, whose command
-already settled at its admission write."""
+``stopping: {reason}`` (plus the staged rewind as ``nextDispatch``) and flip
+``status`` to "stopping" in the same envelope. Rewind commands settle
+accepted with that write; the run/stop verdict follows the run's settle. On
+run end one envelope promotes ``nextDispatch`` into ``dispatching`` and
+clears the window; a later stop/rewind replaces the staged dispatch, whose
+command already settled at its admission write. A second run/stop inside the
+window rejects wrong-state."""
 
 import asyncio
 import copy
@@ -13,6 +15,7 @@ import pytest
 from run_helpers import (
     Script,
     add,
+    assert_rejected,
     edit_params,
     msg,
     queue_ids,
@@ -57,26 +60,40 @@ async def start_run(drv, script, *, parent="p0"):
     return call
 
 
-async def test_stop_opens_the_window_and_settles_with_its_write():
+async def test_stop_opens_the_window_and_flips_status_to_stopping():
     script = Script()
     async with run_host(script) as (drv, host):
         call = await start_run(drv, script)
-        settled = await drv.stop()
-        assert settled["type"] == "accepted"
-        assert drv.replica["status"] == "running"
+        pending = await drv.stop(terminal=False)
+        assert pending["type"] == "pending"
+        await drv.wait_status("stopping")
         assert drv.run["stopping"] == {"reason": "stop"}
         assert drv.run["nextDispatch"] is None
         opened = next(
-            state
-            for env, state in states(drv)
-            if any(r["seq"] == settled["seq"] for r in env.get("res", []))
+            state for _, state in states(drv) if state.get("status") == "stopping"
         )
         assert window_of(opened) == ({"reason": "stop"}, None)
         call.finish(RunManager.Stop(dispatch_queue=False))
+        assert (await drv.res(pending["seq"]))["type"] == "accepted"
         await drv.wait_status("stopped")
         assert drv.run["stopping"] is None
 
 
+async def test_a_second_stop_inside_the_window_rejects_wrong_state():
+    script = Script()
+    async with run_host(script) as (drv, host):
+        call = await start_run(drv, script)
+        run_id = await drv.run_id()
+        pending = await drv.stop(terminal=False)
+        await drv.wait_status("stopping")
+        assert_rejected(
+            await drv.command("run/stop", {"runId": run_id}), "wrong-state"
+        )
+        call.finish(RunManager.Stop(dispatch_queue=False))
+        assert (await drv.res(pending["seq"]))["type"] == "accepted"
+        await drv.wait_status("stopped")
+
+
 async def test_mid_run_edit_stages_the_window_and_promotes_in_one_envelope():
     script = Script()
     async with run_host(script, capabilities=("rewind", "rewind-during-run")) as (
@@ -87,7 +104,7 @@ async def test_mid_run_edit_stages_the_window_and_promotes_in_one_envelope():
         seq = drv.post("run/edit", edit_params("m1", msg("m2"), anchor="p0"))
         await asyncio.wait_for(call.ctx.stop_requested.wait(), 5)
         await drv.wait(lambda s: run_of(s)["stopping"] is not None)
-        assert drv.replica["status"] == "running"
+        assert drv.replica["status"] == "stopping"
         assert drv.run["stopping"] == {"reason": "message-edit"}
         staged = drv.run["nextDispatch"]
         assert staged == {
@@ -161,7 +178,7 @@ async def test_edit_of_dispatched_message_opens_the_window(command):
         call = await start_run(drv, script)
         seq = drv.post(command, target(message=msg("m1", "edited")))
         await drv.wait(lambda s: run_of(s)["stopping"] is not None)
-        assert drv.replica["status"] == "running"
+        assert drv.replica["status"] == "stopping"
         assert drv.run["stopping"] == {"reason": "message-edit"}
         assert drv.run["nextDispatch"] == {
             "trigger": "message-edit",
@@ -210,11 +227,12 @@ async def test_stop_clears_a_staged_rewind():
         seq = drv.post("run/edit", edit_params("m1", msg("m2"), anchor="p0"))
         await drv.wait(lambda s: run_of(s)["nextDispatch"] is not None)
         assert (await drv.res(seq))["type"] == "accepted"
-        settled = await drv.stop()
-        assert settled["type"] == "accepted"
+        pending = await drv.stop(terminal=False)
+        assert pending["type"] == "pending"
         await drv.wait(lambda s: run_of(s)["stopping"] == {"reason": "stop"})
         assert drv.run["nextDispatch"] is None
         call.finish(RunManager.Stop(dispatch_queue=False))
+        assert (await drv.res(pending["seq"]))["type"] == "accepted"
         await drv.wait_status("stopped")
         script.no_call()
 
@@ -253,6 +271,7 @@ ENTRY_KEYS = {
     "nextDispatch",
     "inputRequests",
     "error",
+    "stopReason",
 }