examples, docs, ergonomics and code review fixes

src/wf_core/runtime/lineage.py

@@ -215,6 +215,10 @@ def _lineage_chain(
     run: RunState, *, scope_id: str, lineage_id: str
 ) -> Iterator[LineageState]:
     lineage = _lineage(run, scope_id=scope_id, lineage_id=lineage_id)
-    if lineage.parent_id is not None:
-        yield from _lineage_chain(run, scope_id=scope_id, lineage_id=lineage.parent_id)
-    yield lineage
+    reverse_chain: list[LineageState] = []
+    while True:
+        reverse_chain.append(lineage)
+        if lineage.parent_id is None:
+            break
+        lineage = _lineage(run, scope_id=scope_id, lineage_id=lineage.parent_id)
+    yield from reversed(reverse_chain)

src/wf_core/runtime/ops/state.py

@@ -53,8 +53,19 @@ class StatePatch:
 
         New runtime code should prefer ordered `writes`. `changes` stays as the
         public trace-facing view and as parse compatibility for old barrier
-        metadata/tests that predate `StateWrite`.
+        metadata/tests that predate `StateWrite`. If both are supplied, they
+        must describe identical incoming writes; otherwise trace and replay
+        semantics would disagree.
         """
+        if self.changes and self.writes:
+            derived_changes = {
+                str(write.path): write.incoming_value for write in self.writes
+            }
+            if self.changes != derived_changes:
+                raise ValueError(
+                    "StatePatch constructed with inconsistent changes and writes"
+                )
+            return
         if not self.changes and self.writes:
             self.changes = {
                 str(write.path): write.incoming_value for write in self.writes

src/wf_core/runtime/preparation.py

@@ -37,7 +37,13 @@ def prepare_resume(
     interrupted_workflow: Workflow | None = None,
     interrupted_reducers: Mapping[str, ReducerDefinition] | None = None,
 ) -> WorkflowIndex | None:
-    """Validate and normalize a run state before resume execution."""
+    """Validate and normalize a run state before resume execution.
+
+    `workflow` and `reducers` always describe the outer run. For a routed
+    child interrupt, `interrupted_workflow` and `interrupted_reducers` identify
+    the child scope that owns the interrupt step, so resume bindings commit
+    inside that scope before outer scheduling continues.
+    """
     if run.workflow_name != workflow.name:
         raise WorkflowExecutionError(
             f"run state belongs to workflow {run.workflow_name!r}, not {workflow.name!r}"