fix(state): cascade parallel completion to enclosing compound's OnDone

When a parallel state completed inside a compound, settleParallelDone's
upward-cascade arm called settleDone(parallel, ...), but settleDone gates
on n.state.IsFinal and a parallel state is never IsFinal — so the call was
a dead no-op. The enclosing compound's OnDone was silently dropped even
though the compound was complete, an asymmetry with a nested compound
reaching final (which did propagate).

Route the cascade through completion semantics instead: a new
settleEnclosingDone helper walks the ancestor spine from the parallel,
running each enclosing compound's OnDone while it is stateComplete,
innermost-first — the upward counterpart of settleInteriorDone, gating on
stateComplete exactly as it does. The parallel's own OnDone still fires
exactly once and is not re-emitted.

Un-skips the regression pin TestParallel_NestedUnderCompound_SettlesParentDone
and adds cases for two-compounds-deep recursion and the completion gate
(no cascade when an enclosing ancestor is incomplete). settleParallelDone
coverage rises from 68.8% to 86.7%. IR goldens are unaffected (they pin
static machine structure, not runtime effect streams).

Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>

Author: joshua-temple

state/parallel.go

@@ -534,17 +534,56 @@ func (i *Instance[S, E, C]) settleParallelDone(parallel S, entity C, tr *Trace)
 	if aerr != nil {
 		return eff, aname, aerr
 	}
-	// Continue settling upward if the parallel state itself completes a parent.
-	if pn.hasParent {
-		up, uname, uerr := i.settleDone(parallel, entity, tr)
-		eff = append(eff, up...)
-		if uerr != nil {
-			return eff, uname, uerr
-		}
+	// Continue settling upward through the enclosing spine. A parallel state is
+	// never IsFinal, so settleDone (which gates on IsFinal) is a no-op here;
+	// instead settle each enclosing compound through completion semantics, exactly
+	// as settleInteriorDone does for compounds interior to a region. Walking from
+	// the parallel up its ancestors, every enclosing compound that is now
+	// stateComplete records a done microstep and runs its OnDone, innermost-first,
+	// until an incomplete ancestor halts the cascade. The parallel's OWN OnDone
+	// already ran above and is not re-emitted here.
+	up, uname, uerr := i.settleEnclosingDone(parallel, entity, tr)
+	eff = append(eff, up...)
+	if uerr != nil {
+		return eff, uname, uerr
 	}
 	return eff, "", nil
 }
 
+// settleEnclosingDone settles the done/OnDone of every compound that ENCLOSES a
+// completed state, cascading innermost-first up the ancestor spine while each
+// enclosing ancestor is stateComplete. It is the upward counterpart shared by
+// settleParallelDone: a parallel state is never IsFinal, so settleDone cannot
+// carry the cascade past it; this routes through stateComplete instead, the same
+// completion gate settleInteriorDone uses. The starting state's own OnDone is the
+// caller's responsibility and is never run here.
+func (i *Instance[S, E, C]) settleEnclosingDone(start S, entity C, tr *Trace) (effects []Effect, name string, err error) {
+	m := i.machine
+
+	cur := start
+	for {
+		cn, ok := m.resolveNode(cur)
+		if !ok || !cn.hasParent {
+			return effects, "", nil
+		}
+		parent := cn.parent
+		pn, ok := m.resolveNode(parent)
+		if !ok {
+			return effects, "", nil
+		}
+		tr.note("done." + m.label(cur))
+		if !i.stateComplete(parent) {
+			return effects, "", nil
+		}
+		eff, aname, aerr := i.runActions(pn.state.OnDone, entity, tr)
+		effects = append(effects, eff...)
+		if aerr != nil {
+			return effects, aname, aerr
+		}
+		cur = parent
+	}
+}
+
 // fireFromState resolves the event from an explicit state up through its
 // ancestors (used when no region handled the event in a parallel state). eventData
 // is the already-resolved payload the matched transition's Assign reads from

state/parallel_done_cascade_test.go

@@ -85,21 +85,16 @@ func TestParallel_OnDoneActionError_SurfacesTaggedFailure(t *testing.T) {
 // the effect stream must contain BOTH, in inner-then-outer order, each exactly
 // once.
 //
-// FREEZE BLOCKER (BUG): this test is SKIPPED because it currently FAILS — it has
-// surfaced a real soundness bug in settleParallelDone's upward cascade. When a
-// parallel completes inside a compound, outer.OnDone is silently dropped (0 times,
-// want 1), even though stateComplete(outer) is true. The cascade arm calls
-// i.settleDone(parallel, ...), but settleDone guards on n.state.IsFinal and a
-// PARALLEL state is never IsFinal, so the call is a no-op. The sibling helper
-// settleInteriorDone correctly gates on stateComplete(parent) instead. A nested
-// *compound* reaching final DOES propagate (verified manually), so this is an
-// asymmetry, not intended behavior. The PIN is left in place (Skip, not deleted)
-// so it activates the moment the bug is fixed; it must NOT be deleted or weakened
-// to the buggy 0-count. See the agent return for full reproduction.
+// REGRESSION PIN (formerly a freeze blocker): settleParallelDone's upward cascade
+// once dropped the enclosing compound's OnDone because it routed through
+// settleDone, which gates on n.state.IsFinal — and a PARALLEL state is never
+// IsFinal, so the call was a dead no-op while stateComplete(outer) was true. The
+// fix routes the cascade through completion semantics (settleEnclosingDone, the
+// upward counterpart of settleInteriorDone, gating on stateComplete), so a nested
+// parallel now propagates done to its enclosing compound exactly as a nested
+// compound already did. This pin locks that emission and its inner-then-outer
+// ordering; it must NOT be weakened back to the buggy 0-count.
 func TestParallel_NestedUnderCompound_SettlesParentDone(t *testing.T) {
-	t.Skip("FREEZE BLOCKER: settleParallelDone upward cascade drops the enclosing compound's OnDone " +
-		"(settleDone gates on IsFinal, parallels are never IsFinal). Un-skip once fixed.")
-
 	note := func(s string) state.ActionFn[prCtx] {
 		return func(state.ActionCtx[prCtx]) (state.Effect, error) { return s, nil }
 	}
@@ -162,3 +157,117 @@ func TestParallel_NestedUnderCompound_SettlesParentDone(t *testing.T) {
 		t.Fatalf("effect order = %v, want Pdone before Odone (inner done settles before the enclosing compound's done)", got)
 	}
 }
+
+// TestParallel_NestedTwoCompoundsDeep_CascadesAllDone pins the RECURSIVE arm of
+// the upward cascade: a parallel "par" nested inside compound "mid" nested inside
+// compound "outer". When "par" completes in one macrostep, the done settlement
+// must walk the whole enclosing spine innermost-first — par.OnDone, then
+// mid.OnDone, then outer.OnDone — because each enclosing ancestor in turn becomes
+// stateComplete. Each fires exactly once, in spine order.
+func TestParallel_NestedTwoCompoundsDeep_CascadesAllDone(t *testing.T) {
+	note := func(s string) state.ActionFn[prCtx] {
+		return func(state.ActionCtx[prCtx]) (state.Effect, error) { return s, nil }
+	}
+	m := state.Forge[string, string, prCtx]("par-nested-2deep").
+		Action("Pdone", note("Pdone")).
+		Action("Mdone", note("Mdone")).
+		Action("Odone", note("Odone")).
+		State("off").
+		Transition("off").On("go").GoTo("par").
+		SuperState("outer").OnDone("Odone").
+		Initial("mid").
+		SuperState("mid").OnDone("Mdone").
+		Initial("par").
+		SuperState("par").OnDone("Pdone").
+		Region("a").Initial("a1").SubState("a1").SubState("af").Final().EndRegion().
+		Region("b").Initial("b1").SubState("b1").SubState("bf").Final().EndRegion().
+		EndSuperState(). // close par
+		EndSuperState(). // close mid
+		EndSuperState(). // close outer
+		Initial("off").
+		CurrentStateFn(func(prCtx) string { return "off" }).
+		Transition("a1").On("e").GoTo("af").
+		Transition("b1").On("e").GoTo("bf").
+		Quench()
+
+	inst := m.Cast(prCtx{}, state.WithInitialState("off"))
+	ctx := context.Background()
+	if res := inst.Fire(ctx, "go"); res.Err != nil {
+		t.Fatalf("entering nested parallel: %v", res.Err)
+	}
+
+	res := inst.Fire(ctx, "e")
+	if res.Err != nil {
+		t.Fatalf("e errored: %v (config=%v)", res.Err, inst.Configuration())
+	}
+
+	for _, want := range []string{"Pdone", "Mdone", "Odone"} {
+		if got := countEffect(res.Effects, want); got != 1 {
+			t.Fatalf("%s fired %d times, want exactly 1 (effects=%v)", want, got, stringEffects(res.Effects))
+		}
+	}
+
+	// Innermost-first spine order: Pdone < Mdone < Odone.
+	idx := map[string]int{"Pdone": -1, "Mdone": -1, "Odone": -1}
+	for i, e := range stringEffects(res.Effects) {
+		if _, ok := idx[e]; ok {
+			idx[e] = i
+		}
+	}
+	if idx["Pdone"] >= idx["Mdone"] || idx["Mdone"] >= idx["Odone"] {
+		t.Fatalf("effect order = %v, want Pdone < Mdone < Odone (innermost-first up the spine)", stringEffects(res.Effects))
+	}
+}
+
+// TestParallel_NestedUnderIncompleteCompound_DoesNotCascade pins the cascade's
+// completion GATE: the enclosing compound "outer" also has a sibling child "side"
+// that stays active, so "outer" is NOT stateComplete when "par" completes. The
+// parallel's own OnDone must still fire, but the enclosing compound's OnDone must
+// NOT — the cascade halts at the first incomplete ancestor. This guards against a
+// fix that unconditionally walks the spine instead of gating on stateComplete.
+func TestParallel_NestedUnderIncompleteCompound_DoesNotCascade(t *testing.T) {
+	note := func(s string) state.ActionFn[prCtx] {
+		return func(state.ActionCtx[prCtx]) (state.Effect, error) { return s, nil }
+	}
+	m := state.Forge[string, string, prCtx]("par-nested-incomplete").
+		Action("Pdone", note("Pdone")).
+		Action("Odone", note("Odone")).
+		State("off").
+		Transition("off").On("go").GoTo("par").
+		// "outer" is a parallel state with two regions: one holding "par", one
+		// holding a non-final "side". When "par" completes, outer's other region
+		// is still active and non-final, so outer is not stateComplete.
+		SuperState("outer").OnDone("Odone").
+		Region("main").Initial("par").
+		SuperState("par").OnDone("Pdone").
+		Region("a").Initial("a1").SubState("a1").SubState("af").Final().EndRegion().
+		Region("b").Initial("b1").SubState("b1").SubState("bf").Final().EndRegion().
+		EndSuperState(). // close par
+		EndRegion().     // close main region
+		Region("side").Initial("s1").SubState("s1").EndRegion().
+		EndSuperState(). // close outer
+		Initial("off").
+		CurrentStateFn(func(prCtx) string { return "off" }).
+		Transition("a1").On("e").GoTo("af").
+		Transition("b1").On("e").GoTo("bf").
+		Quench()
+
+	inst := m.Cast(prCtx{}, state.WithInitialState("off"))
+	ctx := context.Background()
+	if res := inst.Fire(ctx, "go"); res.Err != nil {
+		t.Fatalf("entering nested parallel: %v", res.Err)
+	}
+
+	res := inst.Fire(ctx, "e")
+	if res.Err != nil {
+		t.Fatalf("e errored: %v (config=%v)", res.Err, inst.Configuration())
+	}
+
+	if got := countEffect(res.Effects, "Pdone"); got != 1 {
+		t.Fatalf("par.OnDone fired %d times, want exactly 1 (effects=%v)", got, stringEffects(res.Effects))
+	}
+	if got := countEffect(res.Effects, "Odone"); got != 0 {
+		t.Fatalf("outer.OnDone fired %d times, want 0 — outer is not complete (its 'side' region is still active) (effects=%v)",
+			got, stringEffects(res.Effects))
+	}
+}