Merge branch 'feat/state-v1-freeze': crucible/state v1.0 freeze-ready RC

Resolves the v1.0 freeze-readiness gap analysis: parallel-region commit-path correctness (K1-K7, T1/T4/T5), frozen public surface (B1-B6, A1/A2, C1, D1/D2), analysis/evolution/conformance correctness with advisory banners, and resume-equivalence/determinism property tests. Not tagged; the v1.0.0 lock is pending human sign-off.

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

Author: joshua-temple

state/CHANGELOG.md

@@ -9,6 +9,142 @@ A machine definition is treated as a schema: see the
 counts as an additive (minor) versus breaking (major) change. Use the
 `state/evolution` package to classify a machine change and decide the bump.
 
+## [Unreleased] — v1.0.0 release candidate
+
+Freeze-ready, pending human sign-off. This release candidate resolves the v1.0
+freeze-readiness gap analysis: the parallel-region commit path now matches the
+documented semantics, the serialized IR round-trips losslessly, and the frozen
+public surface is locked. It is intentionally **not tagged**; the data model,
+serialized IR, context model, effect envelope, and emission-ordering contract are
+ready to freeze on sign-off. The `analysis`, `evolution`, `conformance`, and
+`verify` subpackages ship as advisory (not part of the frozen contract).
+
+### Fixed
+
+- A `Raise` declared on a region-internal transition is now delivered instead of
+  silently dropped (kernel parallel-region commit path).
+- A region-internal transition targeting a same-region history pseudostate now
+  resolves history correctly instead of leaving the pseudostate permanently stuck as
+  an active leaf.
+- A compound nested inside a parallel region now emits its done event and fires
+  `OnDone` when its leaf reaches final.
+- A parallel state that completes inside an enclosing compound now cascades that
+  compound's `OnDone` (and any guarded completion transition) up the spine, instead
+  of silently dropping it; the parallel's own `OnDone` still fires exactly once.
+- Region transition and entry actions now observe the threaded, exit-assign-folded
+  context, consistent with the main commit path.
+- Eventless (`Always`) transitions now fire in every active parallel region and no
+  longer collapse a sibling region's configuration.
+- Exiting a parallel state now runs every active region leaf's `OnExit` actions
+  innermost-first, in declaration order; an event handled only by a sibling region
+  of an outer parallel is now delivered through nested parallels correctly.
+- A panicking host action is recovered into a typed `ActionPanicError` instead of
+  crashing `Fire`.
+- An event matched by a guard-failed candidate inside a region now bubbles to the
+  parallel-state-level handler instead of causing the fire to fail silently.
+- The raised-event queue is reset when a macrostep errors, so a queued event no
+  longer leaks into the next `Fire`.
+- Effects are emitted only on a fully successful `Fire`; a failed fire emits no
+  effects (transactional effect emission on the main commit path).
+- `Snapshot`/`Restore` preserves bounded-history (`WithHistory(n)`) retention
+  instead of reverting to unbounded.
+- `SnapshotActors` refuses a non-quiesced actor tree with a typed
+  `NonQuiescentActorError` instead of silently dropping queued messages.
+- `Trace.AssignsApplied` is aggregated across all microsteps of a macrostep instead
+  of reporting only the triggering microstep's assigns.
+- `Region`, `Invocation`, and `IOSpec` IR nodes now preserve unknown JSON fields and
+  `Meta` losslessly, making the lossless round-trip guarantee true for every
+  IR-reachable node type.
+- `GuardPanicError` and `AssignPanicError` now `Unwrap` to the recovered error, and
+  `SnapshotError` exposes its cause, so `errors.As`/`errors.Is` can reach a wrapped
+  sentinel through any of them.
+- `SchemaOf` returns an honest `SchemaAny` for interface, func, chan, and complex
+  types instead of coercing them to `SchemaString`.
+- Builder cursor consumers (`When`, `Do`, `Assign`, `Raise`, `GoTo`, and friends)
+  now panic with an actionable construction-time message when no transition is open,
+  instead of silently dropping the call.
+- `analysis` honors wildcard (`OnAny`) edges and excludes forbidden (`Forbid` /
+  `ForbidAny`) edges from reachability and dead-end analysis, removing false
+  unreachable and dead-end findings.
+- `evolution` now detects transition order/priority, guard-operator structure,
+  initial-child, history, context-schema, and eventless-edge changes, and classifies
+  any unmodeled structural difference as breaking (fail-safe), closing silent
+  under-reporting of behavior-changing edits.
+- `conformance` compares effects order-sensitively and payload-aware, and captures
+  trace and final context, so it no longer passes a reordering or wrong-payload
+  regression.
+- The pointer-context determinism diagnostic is advisory and is not rejected under
+  `Quench(Strict())`; pointer context remains a supported escape hatch.
+
+### Added
+
+- Typed errors `ActionPanicError`, `RegionEscapeError`, `HistoryCrossRegionError`,
+  and `NonQuiescentActorError`; `Quench` now rejects a region-escaping transition
+  target and a cross-region history target at build time.
+- `WithRestoreInspector` and `WithRestoreLogger` restore options to re-attach
+  observability after `Restore`.
+- `SchemaAny` schema kind; `Cause` field on `SnapshotError`.
+- A v1.0 interface-surface freeze: `ContextView` is sealed (crucible-only) while
+  `Clock`, `ContextCodec`, `Snapshotter`, and `ActorInstance` are documented as
+  frozen, host-implementable interfaces grown post-v1 via optional interfaces, with
+  compile-time conformance assertions.
+- `analysis` finding kinds `KindUndefinedTarget` and `KindInternalError`.
+- `conformance` `WithSnapshotSink` option and `AssertEffectsPayloads`.
+- `verify` kind-specific `Finding` accessors (`IsReachable`, `Holds`, `Violated`,
+  `Covered`).
+- An advisory pointer-context determinism diagnostic surfaced through Temper/Assay.
+
+### Changed
+
+- `WaitMode`, `HistoryType`, and `ActorKind` integer wire values are documented as
+  frozen and append-only; `JournalRandom` is specified to ride
+  `JournalEntry.Payload`.
+
+### Documentation
+
+- Stability banners: `analysis`, `evolution`, `conformance`, `verify`, and
+  `verify/symbolic` are documented as advisory (not part of the frozen contract);
+  `expr` documents its guard-expression semantics and deterministic evaluation
+  environment as part of the v1.0 contract.
+- `verify` docs corrected to state that bounded simulation enumerates
+  configurations (not traces), the covering suite is a structural guarantee, and
+  only the holding verdict is exact.
+- Documented that `Instance` is not safe for concurrent use; that timer absolute
+  deadlines are a host concern (`ResumeEffects` re-arms at the full declared delay
+  while `durable` persists deadlines); the guard eval-error asymmetry (eventless
+  guards fail closed, event-driven guards fail loud); the v1.0 stability scope; and
+  the known limitation that entering a compound via initial descent onto a final
+  leaf does not raise that compound's done event.
+- `Trace.PoliciesEvaluated` documented as reserved (always empty in v1.0).
+
+### Tests
+
+- Exhaustive symbolic op-table regression tests over every guard operator (the only
+  unsoundness-capable code path).
+- Seeded property tests for snapshot resume-equivalence and parallel-region
+  determinism.
+- Regression tests porting the parallel-region kernel probes: Raise-in-region,
+  history-into-region, interior-compound done, sibling-region eventless and exit,
+  nested-parallel delivery, and a simultaneous-region-completion pin.
+
+### Deferred to a future release (with reason)
+
+- Entering a compound via initial descent directly onto a final leaf does not raise
+  that compound's done event (documented known limitation; additively fixable, but
+  emission-changing, so deferred to an opt-in minor).
+- The transactional-effects fix is scoped to the main commit path; the region
+  commit path retains partial-emit-on-error behavior at the freeze.
+- `verify.Finding.Reachable` polarity reshape (verify is advisory; additive
+  kind-specific accessors are provided instead of a breaking field change).
+- `conformance` `Assertion.Expected`/`Event` payload reshape and auto-derived effect
+  assertions in generated goldens (advisory; needs a host entity/codec, which would
+  be a breaking change).
+- Snapshot-carried absolute timer deadlines (`Pending.TimerDeadlines`) — documented
+  as a host concern in v1.0; additive in a later release.
+- Post-v1.0 performance items: lazy hot-path trace-string construction, ref-slice
+  copy-on-write, trace-history bounding, and random-IR fixpoint and
+  eventless-termination fuzzing.
+
 ## [1.0.0]
 
 The first stable release. The 0.2.0 to 1.0.0 step finalizes the breaking changes

state/action_panic_test.go

@@ -0,0 +1,92 @@
+package state_test
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/stablekernel/crucible/state"
+)
+
+// apctx is a tiny entity for the action-panic regression tests.
+type apctx struct{}
+
+// errActionBoom is a sentinel error a panicking action panics with, so the test
+// can assert errors.Is reaches it through ActionPanicError.Unwrap.
+var errActionBoom = errors.New("action boom")
+
+// TestActionPanic_OnEntrySurfacesTyped asserts a panicking OnEntry action is
+// recovered into a *ActionPanicError on FireResult.Err rather than crashing Fire.
+func TestActionPanic_OnEntrySurfacesTyped(t *testing.T) {
+	m := state.Forge[string, string, apctx]("ap-entry").
+		Action("boom", func(state.ActionCtx[apctx]) (state.Effect, error) { panic("kaboom") }).
+		State("from").
+		State("to").OnEntry("boom").
+		Transition("from").On("go").GoTo("to").
+		Initial("from").
+		Quench()
+
+	inst := m.Cast(apctx{}, state.WithInitialState("from"))
+	res := inst.Fire(context.Background(), "go")
+
+	if res.Err == nil {
+		t.Fatalf("want non-nil FireResult.Err from panicking OnEntry action")
+	}
+	var ap *state.ActionPanicError
+	if !errors.As(res.Err, &ap) {
+		t.Fatalf("want *ActionPanicError, got %T: %v", res.Err, res.Err)
+	}
+	if ap.ActionName != "boom" {
+		t.Fatalf("ActionName = %q, want %q", ap.ActionName, "boom")
+	}
+}
+
+// TestActionPanic_TransitionActionSurfacesTyped asserts a panicking transition
+// action (Do) is recovered into a *ActionPanicError on FireResult.Err.
+func TestActionPanic_TransitionActionSurfacesTyped(t *testing.T) {
+	m := state.Forge[string, string, apctx]("ap-trans").
+		Action("boom", func(state.ActionCtx[apctx]) (state.Effect, error) { panic("kaboom") }).
+		State("from").
+		State("to").
+		Transition("from").On("go").GoTo("to").Do("boom").
+		Initial("from").
+		Quench()
+
+	inst := m.Cast(apctx{}, state.WithInitialState("from"))
+	res := inst.Fire(context.Background(), "go")
+
+	if res.Err == nil {
+		t.Fatalf("want non-nil FireResult.Err from panicking transition action")
+	}
+	var ap *state.ActionPanicError
+	if !errors.As(res.Err, &ap) {
+		t.Fatalf("want *ActionPanicError, got %T: %v", res.Err, res.Err)
+	}
+	if ap.ActionName != "boom" {
+		t.Fatalf("ActionName = %q, want %q", ap.ActionName, "boom")
+	}
+}
+
+// TestActionPanic_UnwrapsInnerError asserts that when an action panics with a
+// sentinel error value, errors.Is reaches that inner error through
+// ActionPanicError.Unwrap, and errors.As still reaches the *ActionPanicError.
+func TestActionPanic_UnwrapsInnerError(t *testing.T) {
+	m := state.Forge[string, string, apctx]("ap-unwrap").
+		Action("boom", func(state.ActionCtx[apctx]) (state.Effect, error) { panic(errActionBoom) }).
+		State("from").
+		State("to").
+		Transition("from").On("go").GoTo("to").Do("boom").
+		Initial("from").
+		Quench()
+
+	inst := m.Cast(apctx{}, state.WithInitialState("from"))
+	res := inst.Fire(context.Background(), "go")
+
+	var ap *state.ActionPanicError
+	if !errors.As(res.Err, &ap) {
+		t.Fatalf("want *ActionPanicError, got %T: %v", res.Err, res.Err)
+	}
+	if !errors.Is(res.Err, errActionBoom) {
+		t.Fatalf("errors.Is did not reach errActionBoom through Unwrap: %v", res.Err)
+	}
+}

state/actor.go

@@ -30,10 +30,20 @@ import "context"
 // verbatim; ActorKindMachine marks the invocation as spawning a child MACHINE
 // actor, so entering the owning state emits a SpawnActor effect instead of a
 // StartService effect, and the host's ActorSystem (not a ServiceRunner) runs it.
+//
+// It serializes as a bare omitempty integer, so its numeric values are part of
+// the FROZEN v1.0 wire contract — a recorded Invocation encodes its kind by the
+// integer. The mapping is append-only: existing values may never be reordered or
+// repurposed; a new actor kind may only be added with the next unused integer.
+// The frozen value -> meaning mapping is:
+//
+//	0 = ActorKindService (the invoked-services default, a host-run unit of work)
+//	1 = ActorKindMachine (invoke a child machine as an actor)
 type ActorKind int
 
 // Actor kinds. ActorKindService is the invoked-services default (a host-run unit
-// of work); ActorKindMachine invokes a child machine as an actor.
+// of work); ActorKindMachine invokes a child machine as an actor. The integers
+// are a frozen, append-only wire contract (see ActorKind).
 const (
 	ActorKindService ActorKind = iota
 	ActorKindMachine
@@ -275,6 +285,12 @@ type actorAdapter[S comparable, E comparable, C any] struct {
 	inst    *Instance[S, E, C]
 	output  func(*Instance[S, E, C]) any
 	pending []Effect
+	// fireErr holds the FireResult.Err from the most recent DeliverFire, so the
+	// ActorSystem's guarded step can settle a child whose fire failed (e.g. a
+	// recovered action/guard/assign panic surfaced as a typed error) as a failure
+	// rather than silently swallowing it. It is read once via FireErr and cleared
+	// at the start of each DeliverFire.
+	fireErr error
 }
 
 // NewActor adapts a Cast child *Instance into an ActorInstance an ActorSystem can
@@ -326,11 +342,13 @@ func isActorEffect(eff Effect) bool {
 // ChildEffects and reports whether the child reached its final state plus its
 // output.
 func (a *actorAdapter[S, E, C]) DeliverFire(ctx context.Context, event any) (bool, any) {
+	a.fireErr = nil
 	ev, ok := event.(E)
 	if !ok {
 		return a.inst.InFinal(), a.outputIfDone()
 	}
 	res := a.inst.Fire(ctx, ev)
+	a.fireErr = res.Err
 	for _, eff := range res.Effects {
 		if isActorEffect(eff) {
 			a.pending = append(a.pending, eff)
@@ -340,6 +358,14 @@ func (a *actorAdapter[S, E, C]) DeliverFire(ctx context.Context, event any) (boo
 	return done, a.outputIfDone()
 }
 
+// FireErr returns the FireResult.Err from the most recent DeliverFire, or nil
+// when that step fired cleanly. The ActorSystem reads it (via the unexported
+// fireErrer interface) to settle a child whose fire failed — for instance a host
+// action that panicked and was recovered into a typed ActionPanicError — as a
+// failure that routes onError or escalates, rather than swallowing it. It is not
+// part of the public ActorInstance contract.
+func (a *actorAdapter[S, E, C]) FireErr() error { return a.fireErr }
+
 // ChildEffects returns and drains the buffered child actor effects — the
 // SpawnActor / StopActor lifecycle effects and the SendTo / SendParent /
 // RespondToSender / ForwardEvent communication effects the child emitted — so the

state/actor_escalation.go

@@ -2,6 +2,7 @@ package state
 
 import (
 	"context"
+	"errors"
 	"fmt"
 )
 
@@ -230,9 +231,32 @@ func deliverFireGuarded(ctx context.Context, inst ActorInstance, event any) (don
 		}
 	}()
 	done, output = inst.DeliverFire(ctx, event)
+	// A clean Go step may still have returned a FireResult.Err: the kernel now
+	// recovers a panicking host action/guard/assign into a typed error rather than
+	// letting it unwind, so a child failure surfaces here instead of as a Go panic.
+	// Treat it as a failure so it settles (routing onError or escalating). A panic
+	// recovered into an *ActionPanicError is re-rendered as an *ErrActorPanic
+	// carrying the original recovered value, preserving the panic-failure surface.
+	if fe, ok := inst.(fireErrer); ok {
+		if err := fe.FireErr(); err != nil {
+			var ap *ActionPanicError
+			if errors.As(err, &ap) {
+				return false, nil, &ErrActorPanic{Value: ap.Recovered}
+			}
+			return false, nil, err
+		}
+	}
 	return done, output, nil
 }
 
+// fireErrer is the optional interface a backing ActorInstance implements to expose
+// the FireResult.Err of its most recent DeliverFire, so deliverFireGuarded can
+// settle a child whose fire failed without that error having been a Go panic. The
+// in-process actorAdapter implements it; a host's own ActorInstance need not.
+type fireErrer interface {
+	FireErr() error
+}
+
 // inspectActorEscalated feeds one actor-escalation inspection event to the system's
 // inspector when one is registered. Like the other inspect helpers it short-circuits
 // on the nil-inspector default and must be called without the system mutex held.