test: close state engine coverage gaps and fix two doc/label slips

Cover the fireFromState cross-cutting branches (commit, guard fail, guard
panic, forbidden, unhandled), the full-trace mergeTrace path through
FireSeq, the kernel typed Error and Unwrap methods, DiffMachines plus the
evolution Serialize/Decode error types, Path.States, the conformance
outcomeName branches, and the symbolic litNumber int forms.

conformance outcomeName now renders OutcomeAssignFailed as AssignFailed
instead of collapsing it to Unknown, so an assign failure stays distinct
in a scenario trace. The analysis Step godoc, previously truncated
mid-sentence, now describes the From/Event/To segment fully.

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

Author: joshua-temple

state/analysis/paths.go

@@ -23,10 +23,10 @@ import (
 // conformance harness draws from.
 
 // Step is one segment of a path: the event that fires from the segment's source
-// state, and the destination state it leads to. A path is read as: starting at the
-// initial state, fire Step[0].Event to reach Step[0].To, then Step[1].Event, and so
-// on. A path segment carries its event plus the resulting
-// `state`).
+// state and the destination state it leads to. A path is read as: starting at the
+// initial state, fire Step[0].Event to reach Step[0].To, then Step[1].Event to
+// reach Step[1].To, and so on. Each segment carries its source state (From), the
+// fired event (Event), and the state reached (To).
 type Step struct {
 	// Event is the string label of the event fired for this segment; "always" for an
 	// eventless transition traversed on the path.

state/analysis/paths_test.go

@@ -71,6 +71,42 @@ func TestShortestPaths_CoversAllReachable(t *testing.T) {
 	}
 }
 
+// TestPath_StatesAndEvents asserts Path.States renders the ordered states visited
+// (initial first, Target last) and stays consistent with Path.Events: a path of n
+// steps yields n events and n+1 states.
+func TestPath_StatesAndEvents(t *testing.T) {
+	paths, err := analysis.ShortestPaths(feedbackMachine())
+	if err != nil {
+		t.Fatalf("ShortestPaths: %v", err)
+	}
+
+	// The empty path (initial state reaching itself) is just the initial state.
+	if got := paths["question"].States("question"); len(got) != 1 || got[0] != "question" {
+		t.Fatalf("States for the empty path = %v, want [question]", got)
+	}
+
+	// A two-step path to thanks via form: question -> form -> thanks.
+	simple, err := analysis.SimplePaths(feedbackMachine())
+	if err != nil {
+		t.Fatalf("SimplePaths: %v", err)
+	}
+	viaForm := simple["thanks"][1] // sorted shortest-first; [1] is the two-step route
+	states := viaForm.States("question")
+	wantStates := []string{"question", "form", "thanks"}
+	if len(states) != len(wantStates) {
+		t.Fatalf("States = %v, want %v", states, wantStates)
+	}
+	for i := range wantStates {
+		if states[i] != wantStates[i] {
+			t.Fatalf("States[%d] = %q, want %q (full %v)", i, states[i], wantStates[i], states)
+		}
+	}
+	// States is always one longer than Events (it includes the initial state).
+	if len(states) != len(viaForm.Events())+1 {
+		t.Fatalf("len(States)=%d, len(Events)=%d; want States == Events+1", len(states), len(viaForm.Events()))
+	}
+}
+
 // TestShortestPaths_MatchesPlanPath asserts that for each single target, the
 // shortest path's length matches the kernel's PlanPath length on the same guard-free
 // machine — ShortestPaths is the multi-target generalization of PlanPath.

state/conformance/internal_test.go

@@ -0,0 +1,44 @@
+package conformance
+
+import (
+	"testing"
+
+	"github.com/stablekernel/crucible/state"
+)
+
+// TestOutcomeName_AllKernelOutcomes asserts outcomeName renders every kernel
+// Outcome by a distinct stable name, so a conformance trace never collapses two
+// different failure classes onto the same label (which would make a regression
+// compare equal). An out-of-range value falls back to "Unknown".
+func TestOutcomeName_AllKernelOutcomes(t *testing.T) {
+	cases := []struct {
+		outcome state.Outcome
+		want    string
+	}{
+		{state.OutcomeSuccess, "Success"},
+		{state.OutcomeInvalidTransition, "InvalidTransition"},
+		{state.OutcomeGuardFailed, "GuardFailed"},
+		{state.OutcomeGuardPanic, "GuardPanic"},
+		{state.OutcomePolicyDenied, "PolicyDenied"},
+		{state.OutcomeEffectError, "EffectError"},
+		{state.OutcomeAssignFailed, "AssignFailed"},
+		{state.Outcome(-1), "Unknown"},
+		{state.Outcome(9999), "Unknown"},
+	}
+
+	seen := map[string]state.Outcome{}
+	for _, tc := range cases {
+		got := outcomeName(tc.outcome)
+		if got != tc.want {
+			t.Fatalf("outcomeName(%d) = %q, want %q", tc.outcome, got, tc.want)
+		}
+		// Every named (non-Unknown) outcome must be distinct from the others, so a
+		// trace diff distinguishes the failure classes.
+		if tc.want != "Unknown" {
+			if prev, dup := seen[got]; dup {
+				t.Fatalf("outcomeName collision: %d and %d both render %q", prev, tc.outcome, got)
+			}
+			seen[got] = tc.outcome
+		}
+	}
+}

state/conformance/scenario.go

@@ -242,6 +242,8 @@ func outcomeName(o state.Outcome) string {
 		return "PolicyDenied"
 	case state.OutcomeEffectError:
 		return "EffectError"
+	case state.OutcomeAssignFailed:
+		return "AssignFailed"
 	default:
 		return "Unknown"
 	}

state/errors_test.go

@@ -0,0 +1,173 @@
+package state_test
+
+import (
+	"errors"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stablekernel/crucible/state"
+)
+
+// TestTypedErrors_Messages asserts every typed kernel error renders a non-empty,
+// self-describing message that names the offending entity. These are the
+// diagnostic surface a host logs and matches on, so the messages are part of the
+// contract.
+func TestTypedErrors_Messages(t *testing.T) {
+	cases := []struct {
+		name     string
+		err      error
+		contains []string
+	}{
+		{
+			name:     "InvalidTransition with target",
+			err:      &state.InvalidTransitionError{From: "a", To: "b", Event: "go", Reason: "guard failed"},
+			contains: []string{"invalid transition", "a", "b", "go", "guard failed"},
+		},
+		{
+			name:     "InvalidTransition without target",
+			err:      &state.InvalidTransitionError{From: "a", Event: "go", Reason: "no transition"},
+			contains: []string{"invalid transition", "a", "go", "no transition"},
+		},
+		{
+			name:     "GuardFailed",
+			err:      &state.GuardFailedError{GuardName: "isReady", Reason: "predicate returned false"},
+			contains: []string{"guard", "isReady", "predicate returned false"},
+		},
+		{
+			name:     "GuardPanic",
+			err:      &state.GuardPanicError{GuardName: "isReady", Recovered: "nil deref"},
+			contains: []string{"guard", "isReady", "panicked", "nil deref"},
+		},
+		{
+			name:     "AssignPanic",
+			err:      &state.AssignPanicError{AssignName: "fold", Recovered: "boom"},
+			contains: []string{"assign", "fold", "panicked", "boom"},
+		},
+		{
+			name:     "PolicyDenied",
+			err:      &state.PolicyDeniedError{PolicyName: "rbac", Reason: "no role"},
+			contains: []string{"policy", "rbac", "denied", "no role"},
+		},
+		{
+			name:     "UndeclaredState",
+			err:      &state.UndeclaredStateError{State: "ghost"},
+			contains: []string{"undeclared state", "ghost"},
+		},
+		{
+			name:     "UnboundRef",
+			err:      &state.UnboundRefError{Kind: "guard", Name: "g"},
+			contains: []string{"unbound", "guard", "g"},
+		},
+		{
+			name:     "MicrostepOverflow",
+			err:      &state.MicrostepOverflowError{Limit: 64, State: "loop"},
+			contains: []string{"run-to-completion", "64", "loop"},
+		},
+		{
+			name:     "NoPath",
+			err:      &state.NoPathError{From: "a", To: "z"},
+			contains: []string{"no path", "a", "z"},
+		},
+		{
+			name:     "WaitTimeout",
+			err:      &state.WaitTimeoutError{Machine: "m", Timeout: 5 * time.Second, Last: "idle"},
+			contains: []string{"WaitFor", "m", "5s", "idle"},
+		},
+		{
+			name:     "NoInitialState",
+			err:      &state.NoInitialStateError{Machine: "m"},
+			contains: []string{"cannot Cast", "m", "no CurrentStateFn"},
+		},
+		{
+			name:     "UnknownBuiltin",
+			err:      &state.UnknownBuiltinError{Name: "crucible.bogus"},
+			contains: []string{"unknown built-in action", "crucible.bogus"},
+		},
+		{
+			name:     "UnboundActor",
+			err:      &state.UnboundActorError{Name: "child"},
+			contains: []string{"unbound actor ref", "child"},
+		},
+		{
+			name:     "Snapshot with state",
+			err:      &state.SnapshotError{Op: "restore", State: "leaf", Reason: "not declared"},
+			contains: []string{"snapshot restore", "leaf", "not declared"},
+		},
+		{
+			name:     "Snapshot without state",
+			err:      &state.SnapshotError{Op: "marshal", Reason: "encode failed"},
+			contains: []string{"snapshot marshal", "encode failed"},
+		},
+		{
+			name:     "SnapshotVersion",
+			err:      &state.SnapshotVersionError{Kind: "machineVersion", Machine: "m", Got: "2", Want: "1", Reason: "major bump"},
+			contains: []string{"version mismatch", "machineVersion", "m", "2", "1", "major bump"},
+		},
+		{
+			name:     "UnsupportedSchema",
+			err:      &state.UnsupportedSchemaError{Got: "2.0", Supported: "1.0"},
+			contains: []string{"unsupported schema version", "2.0", "1.0"},
+		},
+		{
+			name:     "UnknownEffectKind",
+			err:      &state.UnknownEffectKindError{Kind: "foreign"},
+			contains: []string{"unknown effect kind", "foreign"},
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			msg := tc.err.Error()
+			if msg == "" {
+				t.Fatal("error message is empty")
+			}
+			for _, want := range tc.contains {
+				if !strings.Contains(msg, want) {
+					t.Fatalf("message %q does not contain %q", msg, want)
+				}
+			}
+		})
+	}
+}
+
+// TestActionFailedError_WrapsCause asserts ActionFailedError renders its context
+// and unwraps to the underlying cause for errors.Is / errors.As.
+func TestActionFailedError_WrapsCause(t *testing.T) {
+	cause := errors.New("downstream boom")
+	err := &state.ActionFailedError{TransitionName: "a->b", ActionName: "charge", Cause: cause}
+
+	msg := err.Error()
+	for _, want := range []string{"action", "charge", "a->b", "downstream boom"} {
+		if !strings.Contains(msg, want) {
+			t.Fatalf("message %q does not contain %q", msg, want)
+		}
+	}
+	if !errors.Is(err, cause) {
+		t.Fatal("ActionFailedError should unwrap to its cause")
+	}
+}
+
+// TestMultiRegionError_AggregatesAndUnwraps asserts MultiRegionError renders each
+// region's message and exposes them for errors.As traversal.
+func TestMultiRegionError_AggregatesAndUnwraps(t *testing.T) {
+	g := &state.GuardFailedError{GuardName: "g", Reason: "false"}
+	a := &state.AssignPanicError{AssignName: "fold", Recovered: "boom"}
+	err := &state.MultiRegionError{Errors: []error{g, a}}
+
+	msg := err.Error()
+	for _, want := range []string{"2 regions errored", "g", "fold"} {
+		if !strings.Contains(msg, want) {
+			t.Fatalf("message %q does not contain %q", msg, want)
+		}
+	}
+
+	var gf *state.GuardFailedError
+	if !errors.As(err, &gf) {
+		t.Fatal("MultiRegionError should expose a *GuardFailedError via errors.As")
+	}
+	var ap *state.AssignPanicError
+	if !errors.As(err, &ap) {
+		t.Fatal("MultiRegionError should expose an *AssignPanicError via errors.As")
+	}
+}

state/evolution/evolution_test.go

@@ -380,6 +380,81 @@ func TestDiff_NestedChildAdded_Additive(t *testing.T) {
 	}
 }
 
+// TestDiffMachines_AgreesWithDiff drives the Quenched-machine entry point and
+// asserts it classifies a breaking change identically to Diff over the same IRs.
+func TestDiffMachines_AgreesWithDiff(t *testing.T) {
+	oldM := state.Forge[string, string, any]("doc").
+		State("draft").
+		Transition("draft").On("submit").GoTo("review").
+		State("review").
+		Transition("review").On("approve").GoTo("done").
+		State("done").Final().
+		Initial("draft").
+		Quench()
+	// The updated machine drops the review->done transition: a breaking removal.
+	newM := state.Forge[string, string, any]("doc").
+		State("draft").
+		Transition("draft").On("submit").GoTo("review").
+		State("review").
+		State("done").Final().
+		Initial("draft").
+		Quench()
+
+	r, err := evolution.DiffMachines(oldM, newM)
+	if err != nil {
+		t.Fatalf("DiffMachines: %v", err)
+	}
+	if !r.Breaking() {
+		t.Fatalf("DiffMachines should report the removal as breaking, got:\n%s", r)
+	}
+	if !hasKind(r, evolution.KindTransitionRemoved) {
+		t.Fatalf("expected transition_removed, got:\n%s", r)
+	}
+}
+
+// TestDiffMachines_IdenticalIsEmpty asserts DiffMachines over the same definition
+// reports no change.
+func TestDiffMachines_IdenticalIsEmpty(t *testing.T) {
+	build := func() *state.Machine[string, string, any] {
+		return state.Forge[string, string, any]("doc").
+			State("draft").
+			Transition("draft").On("submit").GoTo("done").
+			State("done").Final().
+			Initial("draft").
+			Quench()
+	}
+	r, err := evolution.DiffMachines(build(), build())
+	if err != nil {
+		t.Fatalf("DiffMachines: %v", err)
+	}
+	if !r.Empty() {
+		t.Fatalf("identical machines should diff empty, got:\n%s", r)
+	}
+}
+
+// TestEvolutionErrorTypes_FormatAndUnwrap covers the Error and Unwrap methods of
+// SerializeError and DecodeError directly, since a Machine that fails to serialize
+// cannot be produced through the normal Forge/Quench path.
+func TestEvolutionErrorTypes_FormatAndUnwrap(t *testing.T) {
+	cause := errors.New("boom")
+
+	se := &evolution.SerializeError{Side: "old", Err: cause}
+	if !strings.Contains(se.Error(), "serialize old machine") {
+		t.Fatalf("SerializeError.Error() = %q", se.Error())
+	}
+	if !errors.Is(se, cause) {
+		t.Fatal("SerializeError should unwrap to its cause")
+	}
+
+	de := &evolution.DecodeError{Side: "new", Err: cause}
+	if !strings.Contains(de.Error(), "decode new machine") {
+		t.Fatalf("DecodeError.Error() = %q", de.Error())
+	}
+	if !errors.Is(de, cause) {
+		t.Fatal("DecodeError should unwrap to its cause")
+	}
+}
+
 func TestDiffJSON_RoundTrip(t *testing.T) {
 	old := docMachine()
 	updated := docMachine()