refactor: name error types with the idiomatic *Error suffix

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

Author: joshua-temple

source/statemachine/drive.go

@@ -167,15 +167,15 @@ func emitEffects(ctx context.Context, sink Sink, effects []state.Effect) error {
 // errors.Is(err, source.ErrInvalidForState); otherwise it reports false and the
 // caller treats the error as transient.
 func classifyFire[K comparable, E any](err error, event E, from K) (*source.GuardRejection, bool) {
-	var invalid *state.ErrInvalidTransition
+	var invalid *state.InvalidTransitionError
 	if errors.As(err, &invalid) {
 		return &source.GuardRejection{
 			Event: fmt.Sprint(event),
 			State: invalid.From,
 			Err:   err,
 		}, true
 	}
-	var guard *state.ErrGuardFailed
+	var guard *state.GuardFailedError
 	if errors.As(err, &guard) {
 		return &source.GuardRejection{
 			Event: fmt.Sprint(event),

source/statemachine/drivefunc.go

@@ -18,7 +18,7 @@ import (
 // flows back to the binding.
 //
 // A nil error and a result whose Err is nil is a successful transition; a result
-// carrying a [state.ErrInvalidTransition] or [state.ErrGuardFailed] is the
+// carrying a [state.InvalidTransitionError] or [state.GuardFailedError] is the
 // state-aware rejection. Returning a non-nil error (not the FireResult.Err) is a
 // transient failure resolving the instance — a nak.
 type FireFunc[K comparable, E comparable] func(ctx context.Context, key K, event E) (state.FireResult[K], error)

state/CHANGELOG.md

@@ -29,7 +29,7 @@ representative hot-path numbers.
   preserves unknown fields on nested nodes (machine, state, transition, `Ref`,
   `GuardNode`) so a document written by a newer build round-trips losslessly
   through an older one, and rejects only a higher *major* schema version (the
-  typed `*ErrUnsupportedSchema`). IR encoding is deterministic (stable key order)
+  typed `*UnsupportedSchemaError`). IR encoding is deterministic (stable key order)
   so a definition hashes and diffs reproducibly.
 - Closed-enum extension policy. Every IR enum that may grow (guard op, state
   kind, param type, descriptor kind, effect kind) has a documented
@@ -96,7 +96,7 @@ representative hot-path numbers.
   on `NewEffectRegistry`) decodes it back to a concrete effect. Per the
   closed-enum extension policy, an unrecognized effect kind is preserved verbatim
   on load (surfaced as `UnknownEffect`) and rejected only at dispatch
-  (`EffectRegistry.Dispatchable` returns the typed `*ErrUnknownEffectKind`), never
+  (`EffectRegistry.Dispatchable` returns the typed `*UnknownEffectKindError`), never
   silently dropped or applied. Effects remain data the host applies; the kernel
   does not execute them. The `Effect` alias stays `any`, so bare domain effects
   are unaffected.
@@ -220,7 +220,7 @@ representative hot-path numbers.
   - **Declarative invoke + service registry.** A state declares
     `Invocation{ID, Src, Input, OnDone, OnError}`; service implementations bind by
     name through `Registry.Service` / `Builder.Service`, parallel to guards and
-    actions. An unbound service ref fails `Quench` with the typed `*ErrUnboundRef`
+    actions. An unbound service ref fails `Quench` with the typed `*UnboundRefError`
     (`Kind: "service"`), consistent with unbound guards/actions. Authored via the
     DSL `Invoke(src, ...InvokeOption)` whose outcomes are options —
     `WithInvokeOnDone` / `WithInvokeOnError` — alongside `WithInput`,
@@ -333,8 +333,8 @@ representative hot-path numbers.
     (e.g. `And(Or(g1, g2), Not(g3))`). Evaluation short-circuits exactly like a
     plain multi-guard transition: `And` stops at the first false, `Or` at the
     first true. A failing composite reports the failing leaf(s) when cheap, else
-    the composite, preserving the typed `ErrGuardFailed`; a leaf panic still
-    surfaces as `ErrGuardPanic`.
+    the composite, preserving the typed `GuardFailedError`; a leaf panic still
+    surfaces as `GuardPanicError`.
   - **`stateIn(state)`.** A first-class, config-aware built-in guard, true when
     the instance's active configuration includes the named state (its active
     leaves and their ancestor spine), so it is correct for atomic, compound, and
@@ -370,7 +370,7 @@ representative hot-path numbers.
     transitions until the configuration is stable, recording each as a Trace
     microstep. The internal queue is macrostep-local, so `Fire` stays pure. An
     unhandled raised event is ignored; a non-settling raise/eventless cycle fails fast
-    with the typed `ErrMicrostepOverflow`.
+    with the typed `MicrostepOverflowError`.
   - DSL also gains `Always()` to author eventless transitions directly (previously
     IR-only). The wildcard target, forbidden marker, reenter flag, and raised-event
     list serialize in the IR and round-trip losslessly through JSON; `raise` is
@@ -460,6 +460,22 @@ representative hot-path numbers.
   the service settled and an empty slice when the id is not in flight. A caller
   that checked the old `ok` bool now checks `len(results) > 0` and reads
   `results[0]` for the routed result.
+- **BREAKING: the struct error types are renamed from the `Err*` prefix to the
+  idiomatic `*Error` suffix.** The `Err*` prefix is the Go convention for sentinel
+  error values, not for struct types a caller inspects with `errors.As`; these are
+  all struct types with no sentinel vars. `ErrInvalidTransition`, `ErrGuardFailed`,
+  `ErrGuardPanic`, `ErrAssignPanic`, `ErrPolicyDenied`, `ErrUndeclaredState`,
+  `ErrUnboundRef`, `ErrActionFailed`, `ErrMicrostepOverflow`, `ErrNoPath`,
+  `ErrNoInitialState`, `ErrUnknownBuiltin`, `ErrUnboundActor`, `ErrUnsupportedSchema`,
+  `ErrUnknownEffectKind`, and `MultiRegionErr` become `InvalidTransitionError`,
+  `GuardFailedError`, `GuardPanicError`, `AssignPanicError`, `PolicyDeniedError`,
+  `UndeclaredStateError`, `UnboundRefError`, `ActionFailedError`,
+  `MicrostepOverflowError`, `NoPathError`, `NoInitialStateError`,
+  `UnknownBuiltinError`, `UnboundActorError`, `UnsupportedSchemaError`,
+  `UnknownEffectKindError`, and `MultiRegionError`, matching the already-correct
+  `WaitTimeoutError`, `SnapshotError`, `SnapshotVersionError`, and `VerifyError`.
+  Behavior and fields are unchanged; update the type name at each `errors.As`
+  target, type switch, and struct literal.
 - The determinism and ordering contract is now explicit and frozen: emission
   order is exit → transition → entry across the cascade, declaration order within
   a set, fixed parallel-region order, and the run-to-completion interleave for
@@ -468,7 +484,7 @@ representative hot-path numbers.
 
 ### Fixed
 
-- `Cast` returns the typed `*ErrInvalidTransition` consistently for an event that
+- `Cast` returns the typed `*InvalidTransitionError` consistently for an event that
   matches no transition, including inside parallel regions, so a caller can
   distinguish "no transition" from other failures uniformly.
 - On-entry lifecycle effects (`after` / `invoke` / actor `spawn`) are now emitted

state/actor.go

@@ -176,7 +176,7 @@ func evalActorBuiltinAction(a Ref) (Effect, error) {
 		id, _ := a.Params[stopActorIDParam].(string)
 		return StopActor{ID: id}, nil
 	default:
-		return nil, &ErrUnknownBuiltin{Name: a.Name}
+		return nil, &UnknownBuiltinError{Name: a.Name}
 	}
 }
 

state/actor_comms.go

@@ -167,6 +167,6 @@ func evalCommBuiltinAction(a Ref) (Effect, error) {
 		systemID, _ := a.Params[sendToSystemIDParam].(string)
 		return ForwardEvent{TargetID: target, SystemID: systemID}, nil
 	default:
-		return nil, &ErrUnknownBuiltin{Name: a.Name}
+		return nil, &UnknownBuiltinError{Name: a.Name}
 	}
 }

state/actor_escalation_test.go

@@ -409,8 +409,8 @@ func TestActorEscalation_UnboundSrc_NoOnError_Escalates(t *testing.T) {
 	if esc == nil {
 		t.Fatal("unbound-src spawn failure was swallowed; LastEscalation = nil")
 	}
-	var unbound *state.ErrUnboundActor
+	var unbound *state.UnboundActorError
 	if !errors.As(esc, &unbound) {
-		t.Fatalf("escalation cause is not *ErrUnboundActor: %v", esc)
+		t.Fatalf("escalation cause is not *UnboundActorError: %v", esc)
 	}
 }

state/actor_system.go

@@ -313,7 +313,7 @@ func (s *ActorSystem[S, E, C]) spawn(ctx context.Context, e SpawnActor) {
 	s.mu.Unlock()
 
 	if !ok {
-		s.routeError(ctx, e, &ErrUnboundActor{Name: e.Src.Name})
+		s.routeError(ctx, e, &UnboundActorError{Name: e.Src.Name})
 		return
 	}
 	inst, err := behavior(e.Input)

state/assign_test.go

@@ -283,7 +283,7 @@ func TestAssign_ParallelRegionFolds(t *testing.T) {
 }
 
 // TestAssign_ParallelRegionPanicStopsCommit asserts a region reducer that panics
-// surfaces as OutcomeAssignFailed / *ErrAssignPanic and stops the commit — it
+// surfaces as OutcomeAssignFailed / *AssignPanicError and stops the commit — it
 // must not silently no-op, which was the prior behavior on the parallel path.
 func TestAssign_ParallelRegionPanicStopsCommit(t *testing.T) {
 	m := state.Forge[string, string, acct]("par-assign-panic").
@@ -309,9 +309,9 @@ func TestAssign_ParallelRegionPanicStopsCommit(t *testing.T) {
 	if res.Err == nil {
 		t.Fatal("panicking region reducer should fail the fire")
 	}
-	var ap *state.ErrAssignPanic
+	var ap *state.AssignPanicError
 	if !errors.As(res.Err, &ap) {
-		t.Fatalf("error = %v, want *ErrAssignPanic", res.Err)
+		t.Fatalf("error = %v, want *AssignPanicError", res.Err)
 	}
 	if ap.AssignName != "boom" {
 		t.Fatalf("assign name = %q, want boom", ap.AssignName)
@@ -386,9 +386,9 @@ func TestAssign_PanicStopsCommit(t *testing.T) {
 	if res.Err == nil {
 		t.Fatal("panicking reducer should fail the fire")
 	}
-	var ap *state.ErrAssignPanic
+	var ap *state.AssignPanicError
 	if !errors.As(res.Err, &ap) {
-		t.Fatalf("error = %v, want *ErrAssignPanic", res.Err)
+		t.Fatalf("error = %v, want *AssignPanicError", res.Err)
 	}
 	if ap.AssignName != "boom" {
 		t.Fatalf("assign name = %q, want boom", ap.AssignName)
@@ -399,7 +399,7 @@ func TestAssign_PanicStopsCommit(t *testing.T) {
 }
 
 // TestAssign_UnboundRefFailsQuench asserts a transition that wires an unregistered
-// assign fails Quench with the typed *ErrUnboundRef (Kind "assign"), exactly like
+// assign fails Quench with the typed *UnboundRefError (Kind "assign"), exactly like
 // an unbound guard, action, or service.
 func TestAssign_UnboundRefFailsQuench(t *testing.T) {
 	defer func() {
@@ -411,9 +411,9 @@ func TestAssign_UnboundRefFailsQuench(t *testing.T) {
 		if !ok {
 			t.Fatalf("panic value is not an error: %T", r)
 		}
-		var ub *state.ErrUnboundRef
+		var ub *state.UnboundRefError
 		if !errors.As(err, &ub) {
-			t.Fatalf("panic = %v, want *ErrUnboundRef", err)
+			t.Fatalf("panic = %v, want *UnboundRefError", err)
 		}
 		if ub.Kind != "assign" || ub.Name != "ghost" {
 			t.Fatalf("unbound ref = {%q, %q}, want {assign, ghost}", ub.Kind, ub.Name)

state/binding.go

@@ -171,7 +171,7 @@ func (r *Registry[C]) bindGuard(name string, b GuardBinding[C]) {
 // The binding is wired into the same name path Guard uses, so a guard registered
 // this way is indistinguishable to the kernel from a Go-func guard — it resolves
 // by name at Provide/Quench, evaluates synchronously inside the pure Fire step, and
-// surfaces a panic as the same typed ErrGuardPanic. The binding's EvalGuard is
+// surfaces a panic as the same typed GuardPanicError. The binding's EvalGuard is
 // adapted to a GuardFn over the in-process context view so the fire-time fast path
 // (which reads r.guards) finds it; the binding is also recorded on the parallel
 // binding seam so a future out-of-process transport can swap it under the same name.

state/binding_test.go

@@ -173,17 +173,17 @@ func TestRegistry_AssignBindingRecorded(t *testing.T) {
 }
 
 // TestEvalAssign_UnboundRefFailsClosed asserts the defensive fire-time guard:
-// an assign ref with no bound reducer surfaces as a typed *ErrAssignPanic and
+// an assign ref with no bound reducer surfaces as a typed *AssignPanicError and
 // leaves the context unchanged, rather than silently dropping the fold.
 func TestEvalAssign_UnboundRefFailsClosed(t *testing.T) {
 	m := Forge[string, string, bindOrder]("x").State("a").Initial("a").Quench()
 	next, err := m.evalAssign(Ref{Name: "ghost"}, bindOrder{Amount: 3}, nil)
 	if err == nil {
 		t.Fatal("unbound assign ref should fail")
 	}
-	var ap *ErrAssignPanic
+	var ap *AssignPanicError
 	if !errors.As(err, &ap) || ap.AssignName != "ghost" {
-		t.Fatalf("error = %v, want *ErrAssignPanic{ghost}", err)
+		t.Fatalf("error = %v, want *AssignPanicError{ghost}", err)
 	}
 	if next.Amount != 3 {
 		t.Fatalf("context changed on unbound assign: %+v", next)