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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: harness-sdk-python
-Version: 0.19.0
+Version: 0.20.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.19.0 → harness_sdk_python-0.20.0}/pyproject.toml

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

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

@@ -6,13 +6,21 @@ tray's durable records are the machine's authoritative state, and the mounted
 view rides ``state["runs"][0]`` (plus a top-level ``status`` mirror). A crash
 at any point resumes the machine from its records: the in-flight dispatch
 redelivers from the outbox (``ctx.attempts`` counts durable deliveries,
-``ctx.state``/``set_state`` is the run's durable checkpoint), lanes, the
-stopping window, a staged rewind (``nextDispatch``), and pending input
-requests all hydrate back.
+``ctx.state``/``set_state`` is the run's durable checkpoint), and lanes, a
+staged rewind (``nextDispatch``), and pending input requests all hydrate
+back.
+
+``status`` is derived, never stored: a recorded dispatch (the outbox) means
+``running`` — ``stopping`` while a live stop intent (a staged stop or staged
+rewind) is open — and with no recorded dispatch the durable facts decide:
+``halted`` reads ``error``/``stopped``, pending ``inputRequests`` read
+``input-required``, and bare facts read ``ready``. A crash drops live stop
+intent; the pooled ``run/stop`` redelivers and re-stages it, and a staged
+rewind hydrates back from ``nextDispatch``.
 
 Commands stage entries into an intake list and an advance applies them in
-order, then takes exactly one action based on status and net effect
-(rewind > send-dispatch > continue > input-resume). Every initiator applies
+order, then takes exactly one action based on the derived status and net
+effect (rewind > send-dispatch > continue > input-resume). Every initiator applies
 and settles accepted with its state-visible application, and every verb's
 verdict follows the admission's durable flush. ``entry["dispatching"]`` is
 the unconfirmed batch record; ``ctx.applied()`` confirms it durably,
@@ -192,8 +200,8 @@ class _Effects:
 
 
 class RunManager(Tray):
-    """One thread's run machine: durable lanes, dispatch outbox, stopping
-    window, staged rewind, and input requests, driven by the tray pump."""
+    """One thread's run machine: durable lanes, dispatch outbox, staged
+    rewind, and input requests, driven by the tray pump; status is derived."""
 
     capabilities: frozenset[str] = frozenset()
     max_queued: int = 50
@@ -207,14 +215,15 @@ class RunManager(Tray):
     batchApplied = persistent(False)
     confirmedTakes = persistent(0)
     runId = persistent(None)
-    status = persistent("ready")
     epoch = persistent(0)
-    stopping = persistent(None)
+    halted = persistent(None)  # off-wire settle fact: "error" | "stop" | None
     nextDispatch = persistent(None)
     inputRequests = persistent(None)
     error = persistent(None)
     stopReason = persistent(None)
     dispatchedIds = persistent([])
+    status = observable("ready")  # view: derived by _publish_status
+    stopping = observable(None)  # view: the open stop window, derived
     dispatching = observable(None)  # view: the unconfirmed batch record
     steerView = observable([])  # view: the steer lane without admission tags
 
@@ -302,9 +311,7 @@ class RunManager(Tray):
             # heal a dispatch torn after its outbox write landed
             self._clear_input()
             self.error.value = None
-            self._set_status(
-                "stopping" if self.stopping.value is not None else "running"
-            )
+            self.halted.value = None
         staged = self.nextDispatch.value
         if (
             staged is not None
@@ -337,6 +344,7 @@ class RunManager(Tray):
             }
         if not self._in_flight():
             self._idle.set()
+        self._publish_status()
         self._schedule(self._advance)  # reconcile a torn advance segment
 
     # ─── State access ───────────────────────────────────────
@@ -344,17 +352,36 @@ class RunManager(Tray):
     def _in_flight(self) -> bool:
         return self.outbox.value is not None
 
-    def _status(self) -> str:
-        return self.status.value
+    def _stop_intent(self) -> str | None:
+        if self._stop_staged:
+            return "stop"
+        if self._staged_rewind is not None:
+            return self._staged_rewind.type
+        return None
 
-    def _set_status(self, status: str) -> None:
-        self.status.value = status
+    def _status(self) -> str:
+        if self._in_flight():
+            return "running" if self._stop_intent() is None else "stopping"
+        if self.halted.value == "error":
+            return "error"
+        if self.halted.value == "stop":
+            return "stopped"
+        if self.inputRequests.value:
+            return "input-required"
+        return "ready"
+
+    def _publish_status(self) -> None:
+        status = self._status()
+        if self.status.value != status:
+            self.status.value = status
+        window = {"reason": self._stop_intent()} if status == "stopping" else None
+        if self.stopping.value != window:
+            self.stopping.value = window
 
     def _to_ready(self) -> None:
         self.runId.value = None
         self.epoch.value = 0
         self.dispatchedIds.value = []
-        self.status.value = "ready"
 
     def _lane(self, lane: str) -> Any:
         return self.queue if lane == "queue" else self.steerQueue
@@ -452,6 +479,7 @@ class RunManager(Tray):
         ):
             if self._run_live is not None:
                 self._run_live.stop_requested.set()
+        self._publish_status()
         self._settle_applied(fx)
         if not self._in_flight():
             self._idle.set()
@@ -463,8 +491,6 @@ class RunManager(Tray):
                 if self._staged_rewind is not None:
                     self._staged_rewind = None
                     self.nextDispatch.value = None
-                self.stopping.value = {"reason": "stop"}
-                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)
@@ -526,14 +552,13 @@ class RunManager(Tray):
             self._input_requests = [dict(r) for r in requests]
             self._input_answers = {}
             self.inputRequests.value = [dict(r) for r in requests]
-            self._set_status("input-required")
             return
         if outcome["dispatchQueue"] and self._pop_dispatchable():
             return
         error = outcome.get("error")
         if error is not None:
             self.error.value = error
-        self._set_status("error" if kind == "error" else "stopped")
+        self.halted.value = "error" if kind == "error" else "stop"
 
     # ─── Dispatch and settle ────────────────────────────────
 
@@ -596,10 +621,10 @@ class RunManager(Tray):
         self._fresh = True
         self._reclaim(item)  # the record owns its sources: consume them behind it
         self.nextDispatch.value = None
-        self.stopping.value = None
         self._clear_input()
         self.batchApplied.value = False
         self.error.value = None
+        self.halted.value = None
         stripped = [
             {k: v for k, v in message.items() if k != "meta"} for message in messages
         ]
@@ -608,7 +633,6 @@ class RunManager(Tray):
             added = [m["id"] for m in stripped if m["id"] not in known]
             if added:
                 self.dispatchedIds.value = [*known, *added]
-        self._set_status("running")
         self.dispatching.value = _public_record(record)
         self._idle.clear()
         self.kick()
@@ -660,7 +684,7 @@ class RunManager(Tray):
             ),
             _tray_ctx=self._make_ctx(),
         )
-        if self.stopping.value is not None or self._stop_staged:
+        if self._stop_intent() is not None:
             ctx.stop_requested.set()
         return ctx
 
@@ -722,9 +746,10 @@ class RunManager(Tray):
                 )
                 rewind.applied()
                 rewind.applied_sent = True
-            self._set_status("stopped")
+            self.halted.value = "stop"
             self.outcome.value = None
             self._resolve_stop_waiters()
+            self._publish_status()
             self._settle_applied(fx)
             self._idle.set()
             raise  # staged intake settled; a cancelled run starts no dispatch
@@ -743,7 +768,7 @@ class RunManager(Tray):
                 "error": error,
             }
             self._settle(ctx)
-            self._set_status("error")
+            self.halted.value = "error"
             self.error.value = error
             self._advance()
             return
@@ -799,7 +824,6 @@ class RunManager(Tray):
             self.dispatchedIds.value = kept
 
     def _finish_settle(self) -> None:
-        self.stopping.value = None
         self.confirmedTakes.value = 0
         self.batchApplied.value = False
         self._clear_dispatch_state()  # commits confirmed takes; drops the run's checkpoint
@@ -844,7 +868,8 @@ class RunManager(Tray):
             self._lane(lane).insert(0, item)
 
     def _dispatchable(self, lane: str) -> bool:
-        if self._in_flight() or self._staged_rewind is not None:
+        # an unconsumed outcome means the settle is mid-drain: its follow-on decides
+        if self._in_flight() or self._staged_rewind is not None or self.outcome.value is not None:
             return False
         if self._batch:
             return True
@@ -912,8 +937,6 @@ class RunManager(Tray):
     def _stage_rewind(self, rewind: _Rewind) -> None:
         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),
@@ -1445,7 +1468,7 @@ 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()
-        stop_held = (self.stopping.value or {}).get("reason") == "stop"
+        stop_held = self._stop_staged
         # 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

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

@@ -1,8 +1,10 @@
 """Contract: the durable seams of the run machine. A verdict never outruns the
 admission's flush; a crash redelivers the in-flight dispatch with its checkpoint
-and its epoch; and the rich mid-flight state — the stopping window with its
-staged rewind, the applied batch, an unconfirmed steering take, and
-half-answered input requests — all hydrate back on the restarted machine.
+and its epoch; and the rich mid-flight state — a staged rewind with its
+derived stopping window, the applied batch, an unconfirmed steering take, and
+half-answered input requests — all hydrate back on the restarted machine. A
+bare stop window is live intent: it drops at the crash and a re-issued stop
+re-opens it on the redelivered run.
 Torn storage segments are swept exhaustively in test_run_crash_sweep.py.
 """
 
@@ -172,7 +174,7 @@ 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():
+async def test_a_crash_in_the_stop_window_redelivers_the_run_without_the_window():
     store = MemoryStateStore()
     script = Script()
     async with run_host(script, store=store) as (drv, host):
@@ -187,11 +189,15 @@ async def test_the_stopping_status_survives_a_crash_in_the_stop_window():
 
     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"}
+        assert drv2.replica["status"] == "running"
+        assert run_of(drv2.replica)["stopping"] is None
         redelivered = await script2.next_call()
-        assert redelivered.ctx.stop_requested.is_set()
+        assert not redelivered.ctx.stop_requested.is_set()
+        pending = await drv2.stop(terminal=False)  # a re-issued stop re-opens it
+        await asyncio.wait_for(redelivered.ctx.stop_requested.wait(), 5)
+        await drv2.wait_status("stopping")
         redelivered.finish(RunManager.Stop(dispatch_queue=False))
+        assert (await drv2.res(pending["seq"]))["type"] == "accepted"
         await drv2.wait_status("stopped")
         assert run_of(drv2.replica)["stopping"] is None
 

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

@@ -1,3 +1,5 @@
+import asyncio
+
 import pytest
 from run_helpers import Script, add, machine, queue_ids, run_host, run_of
 
@@ -137,6 +139,35 @@ async def test_unknown_capability_rejects_at_decoration():
         run_manager(capabilities=("time-travel",))
 
 
+async def test_a_send_landing_in_the_settle_drain_parks_for_the_follow_on():
+    script = Script()
+    async with run_host(script) as (drv, host):
+        runs = await machine(host.live)
+        drv.post("run/enqueue", add("m1"))
+        call = await script.next_call()
+        call.applied()
+        held: list = []
+        real, runs._schedule = runs._schedule, held.append
+        try:
+            task = asyncio.ensure_future(
+                runs.enqueue(add("m2", anchor="m1"), applied=lambda: None)
+            )
+            for _ in range(100):
+                if runs._intake:
+                    break
+                await asyncio.sleep(0)
+            assert runs._intake, "the enqueue never staged"
+        finally:
+            runs._schedule = real
+        call.finish(RunManager.Complete())  # the enqueue lands in the settle advance
+        follow = await script.next_call()
+        assert [m["id"] for m in follow.ctx.messages] == ["m2"]
+        await asyncio.wait_for(task, 5)
+        follow.applied()
+        follow.finish(RunManager.Complete())
+        await drv.wait_status("ready")
+
+
 async def test_idle_spans_the_drain_chain():
     script = Script()
     async with run_host(script) as (drv, host):

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

@@ -4,9 +4,11 @@ A SinglesStore lands writes one key at a time and dies for good after its
 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; an open stop window and status
-"stopping" imply each other; and a fresh send still reaches a run.
+the restart; an accepted input answer reaches a run's input_outcomes; the
+published status matches the derivation facts (a recorded dispatch reads
+running/stopping, "stopped"/"error" carry the halted fact, "input-required"
+carries inputRequests, the stop window rides status "stopping"); 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
@@ -264,12 +266,20 @@ async def flush(runs) -> None:
 
 
 def check_wire(runs) -> None:
-    if runs.status.value == "input-required":
+    status = runs.status.value
+    in_flight = runs.outbox.value is not None
+    assert (status in ("running", "stopping")) == in_flight, (
+        f"status {status!r} contradicts the dispatch record"
+    )
+    if status == "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")
+    if status in ("stopped", "error"):
+        expected = "stop" if status == "stopped" else "error"
+        assert runs.halted.value == expected, f"{status} without its halted fact"
+    if status == "stopping":
+        assert runs.stopping.value is not None, "stopping without an open stop window"
+    else:
+        assert runs.stopping.value is None, "an open stop window without its status"
 
 
 async def settle_call(runs, call, seen: set[str]) -> None:
@@ -568,6 +578,25 @@ async def verify_rewind(runs, script, trace, seen, calls):
     await probe(runs, script, seen, "a1")
 
 
+async def drive_stop(runs, script, trace, spawn):
+    send = spawn(runs.enqueue(add("m1"), applied=lambda: None))
+    call = await script.next_call(2)
+    await step(send)
+    trace.accepted.add("m1")
+    apply_batch(call, "batch")
+    stop = spawn(runs.stop({"reason": "user-stop"}, applied=lambda: None))
+    await step(call.ctx.stop_requested.wait())
+    call.finish(RunManager.Stop(dispatch_queue=False))
+    await step(stop)
+    await flush(runs)
+    assert runs.status.value == "stopped"
+    assert runs.stopReason.value == "user-stop"
+
+
+async def verify_stop(runs, script, trace, seen, calls):
+    await probe(runs, script, seen, None)
+
+
 async def drive_cancel(runs, script, trace, spawn):
     send = spawn(runs.enqueue(add("m1"), applied=lambda: None))
     call = await script.next_call(2)
@@ -618,6 +647,8 @@ test_rewind_promotion_survives_every_crash_point = sweep(
     drive_rewind, verify_rewind, capabilities=REWIND, thread=True
 )
 
+test_stop_settle_survives_every_crash_point = sweep(drive_stop, verify_stop)
+
 test_cancel_with_in_drain_rewind_survives_every_crash_point = sweep(
     drive_cancel, verify_cancel, capabilities=REWIND, thread=True
 )

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

@@ -1,5 +1,5 @@
 """Contract: the stopping window. Three openers — run/stop, mid-run
-edit/reload, and the enqueue/steer edit-of-dispatched form — write
+edit/reload, and the enqueue/steer edit-of-dispatched form — publish
 ``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