From ff935fa65ed38167f746a2b4f1b4707e17e6ecbb Mon Sep 17 00:00:00 2001 From: abrichr Date: Mon, 27 Jul 2026 22:30:34 -0400 Subject: [PATCH] docs: stop telling operators a halt performed nothing after the checkpoint The durable-runtime page said: When the run halts (an unhandled screen, a refuted write, an escalation) ... nothing after the checkpoint was performed. That is false for the case the same sentence names. A refuted write is a write that WAS delivered and then read back absent from the system of record; a postcondition halt is a halt on evidence collected after the click. openadapt-flow states this explicitly in `transaction.py::_reached_delivery`: "a postcondition is checked after the click, so an over-halt that aborts the run on one is proof the write was already delivered, not proof it was not." The engine models this correctly and has a terminal outcome for it. Only the prose was wrong -- and wrong in the most expensive direction, since "nothing after the checkpoint was performed" is exactly the sentence that tells a customer they have nothing to reconcile. Replaces it with what the runtime actually guarantees: everything up to the last checkpoint is verified; the halting step is not checkpointed and is not rolled back; and what it may already have done is read from the terminal `transaction_outcome` -- `HALTED_BEFORE_EFFECT` (absence positively established, nothing to reconcile) or `RECONCILIATION_REQUIRED` (reconcile before resuming). --- docs/concepts/durable-runtime.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/docs/concepts/durable-runtime.md b/docs/concepts/durable-runtime.md index e509991..f1943cd 100644 --- a/docs/concepts/durable-runtime.md +++ b/docs/concepts/durable-runtime.md @@ -19,8 +19,26 @@ its postconditions passed and, where declared, its checkpoint marks verified progress, not merely "the click fired." When the run halts (an unhandled screen, a refuted write, an escalation), it -writes a **pending escalation** into the run directory and stops. Work already -done is durably recorded; nothing after the checkpoint was performed. +writes a **pending escalation** into the run directory and stops. Everything up +to the last checkpoint is durably recorded and verified. + +The halting step itself is **not** checkpointed, and the runtime does not claim +it did nothing. Several halts happen *after* the action was delivered, because +that is when the evidence arrives: a screen postcondition is read after the +click, and a refuted write is a write that was sent and then read back absent +from the system of record. **A halt is not a rollback.** + +What the halting step may already have done is stated in the run's terminal +`transaction_outcome`, and is never inferred from the checkpoint: + +- **`HALTED_BEFORE_EFFECT`** — absence was positively established for every + consequential step. There is nothing to reconcile. +- **`RECONCILIATION_REQUIRED`** — delivery or persistence is uncertain, + conflicting, or unverifiable. Reconcile the current state before resuming; the + runtime will not blind-retry. + +The runtime never returns the first outcome to spare you the second. An empty +evidence list means verification never ran, not that nothing happened. ```mermaid flowchart LR