feat(repo): test xstate's guard evaluation as a conformance spec and give checkStateIn a data-last form

[systemfsoftware-maker]

Capability 6 (guards) of @systemfsoftware/xstate: guard evaluation gets one conformance spec over a hand-written admission model, and its decisions move into src/transitionGuards.ts, which joins the mutate set.

What changes

• src/transitionGuards.ts (new, mutated, linted, tsgo-enrolled). It holds the pure decisions:
  • checkStateIn, moved from utils.ts, now with a data-last form checkStateIn(stateValue)(snapshot) dispatched by argument count;
  • candidate admission, in order: event pattern, session matcher, internal guard, then the transition function;
  • the selection rule for a transition function's outcome (a returned value admits unless it is undefined; an enqueued effect admits and is not reusable);
  • first-admitted-candidate in document order.
• The shell keeps the user-code calls. stateUtils.ts still runs the transition function and catches the effect signal, then hands the tagged outcome to the core. StateNode.next and the eventless walk use the core's decisions. The evaluateCandidate pass-through, utils.ts's matchesEvent and checkStateIn, and stateUtils.ts's isStateId re-export are gone.
• Tests. tests/guards.conformance.test.ts (13 cases) replaces test/guards.test.ts and test/stateIn.test.ts; both leave the two unguarded lists.

The spec

A Conformance.sequential check over generated machines on one fixed parallel topology (regions L and R; L holds compound p with c1 and c2, plus q; R holds r1 and r2; context { n }; events GO{k} and TICK). Each node's on slot for each event is generated:

• Absent, a string target (GO: '#q'; setup's types forbid the bare string, so its machines use { target }), an event pattern { target, matches: { k } }, or a transition function whose predicate is Always, Never, a context threshold, a payload threshold, a guards.atLeast source, or matchesState(path, value), and whose outcome is a move, a targetless stay (optionally bumping the context), or an emitted effect;
• eventless slots on c2 and r2;
• three factories (createMachine, setup, .provide, where provide's guard wins) and two drivers (actor with can and on('effect'); pure initialTransition/transition).

The model predicts, per step, the state value, context.n, can(event), the emitted effects and the active ids read through checkStateIn in both call forms. A liveness ledger requires each slot kind on every side its semantics allow (Target admitted, Absent rejected, Pattern and Fn both admitted and rejected), each fallback depth (p, the region, the root), a cross-region interim eventless step, every factory and driver, and checkStateIn true and false in both forms. Two planted subjects (a rejection written as {}, an effect outcome that enqueues nothing) must be judged model-diverged.

Cases:

• A custom guard with parameters admits only when the context and the event together clear the threshold
• A declared target admits the event and moves the actor to it
• A guard in one region reads the interim value another region reached in the same macrostep
• A guard source receives exactly the arguments the transition function passes
• A guard source the machine does not implement leaves the actor in error status with a TypeError naming it
• A rejection that returns an empty object consumes the event and is caught as a model divergence
• A transition function that throws leaves the actor in error status with that error
• A zero-parameter guard source is called with no arguments
• An effect outcome that enqueues nothing falls through and is caught as a model divergence
• Every machine and event sequence the model draws from seed 1 admits exactly what the published guards admit
• Every machine and event sequence the model draws from seed 2 admits exactly what the published guards admit
• Every machine and event sequence the model draws from seed 3 admits exactly what the published guards admit
• checkStateIn answers path strings and state values like snapshot.matches, in both forms

Behaviour-to-test map (CONST-T9)

Replaces packages/xstate/test/guards.test.ts and packages/xstate/test/stateIn.test.ts.
Covering scenarios are the Gherkin titles in packages/xstate/tests/guards.conformance.test.ts:

• OUTLINE — Every machine and event sequence the model draws from seed <seed> admits exactly what the published guards admit (scenario outline, seeds 1/2/3).
• STATEIN — checkStateIn answers path strings and state values like snapshot.matches, in both forms.
• TARGET — A declared target admits the event and moves the actor to it.
• CUSTOM — A custom guard with parameters admits only when the context and the event together clear the threshold.
• INTERIM — A guard in one region reads the interim value another region reached in the same macrostep.
• MISSING — A guard source the machine does not implement leaves the actor in error status with a TypeError naming it.
• THROW — A transition function that throws leaves the actor in error status with that error.
• ARGS — A guard source receives exactly the arguments the transition function passes.
• ZERO — A zero-parameter guard source is called with no arguments.
• DIVERGE_EMPTY — A rejection that returns an empty object consumes the event and is caught as a model divergence.
• DIVERGE_EFFECT — An effect outcome that enqueues nothing falls through and is caught as a model divergence.

guards.test.ts (24 it, 2 skipped)

guard conditions › should transition only if condition is met → OUTLINE (+ the model's Fn slot with a ContextAtLeast evaluator admits when the pre-event context clears the threshold, over both drivers and all three factories).
guard conditions › should transition if condition based on event is met → OUTLINE (+ the model's Fn slot with a PayloadAtLeast evaluator on GO admits; Named/Payload admission).
guard conditions › should not transition if condition based on event is not met → OUTLINE (+ the same Fn slot rejects, so the event falls through to the ancestor; ledger rejected.Fn).
guard conditions › should not transition if no condition is met → OUTLINE (+ a Fn slot returning undefined admits nothing; the model predicts the unchanged value and the ledger records the rejection, matching the old test's "no actions fired" assertion).
guard conditions › should work with defined string transitions → OUTLINE (+ Target slots: a plain string target always admits).
guard conditions › should work with guard objects → OUTLINE (+ Fn slots; the old test's guard-object syntax had already been collapsed to inline transition functions, so the behaviour is the generated Fn slots).
guard conditions › should work with defined string transitions (condition not met) → OUTLINE (+ the Fn/Target slots whose condition fails).
guard conditions › should guard against transition → OUTLINE (+ Fn slots whose when is Never/a false predicate never admit — the "guard against" case).
guard conditions › should allow a matching transition → OUTLINE (+ the model's In evaluator, matchesState(path, value) on the pre-event value, admits).
guard conditions › should check guards with interim states → INTERIM (+ a region-R always reads the interim value of region L after L moved in the same macrostep; the old test's A3→A4→A5 eventless chain is the same one-microstep interim step).

[function] guard conditions › should transition only if condition is met → OUTLINE.
[function] guard conditions › should transition if condition based on event is met → OUTLINE.
[function] guard conditions › should not transition if condition based on event is not met → OUTLINE.
[function] guard conditions › should not transition if no condition is met → OUTLINE.
[function] guard conditions › should work with defined string transitions → OUTLINE.
[function] guard conditions › should work with guard objects → OUTLINE.
[function] guard conditions › should work with defined string transitions (condition not met) → OUTLINE.
[function] guard conditions › it.skip should allow a matching transition → OUTLINE (+ same machine as the live guard conditions › should allow a matching transition; skipped in the old suite, the matching behaviour is the model's In evaluator).
[function] guard conditions › it.skip should check guards with interim states → INTERIM (+ same machine as the live guard conditions › should check guards with interim states; skipped in the old suite).

custom guards › should evaluate custom guards → CUSTOM (+ exactly the old machine: guards-style source with count + event.value > 3; the scenario asserts event value 4 reaches active and value 3 stays inactive).
guards - other › should allow for a fallback target to be a simple string → OUTLINE (+ the model's Fn slot with a Go outcome admits and moves to its target, which is the old test's function returning { target: 'c' }; TARGET pins the declared-target form).
guards - unknown references › should throw on a guard reference that is not implemented → MISSING (+ same guards.isRedy call: actor reaches status: 'error' with a TypeError whose message matches /guards[^\s]*isRedy[^\s]* is not a function/).
guards - plain function sources › passes only the caller-supplied params to the source → ARGS (+ same probe: guards.isAbove(context.count, 3) records [5, 3] and admits).
guards - plain function sources › supports zero-param guards → ZERO (+ a zero-parameter source is callable and admits).

stateIn.test.ts (9 it, 1 skipped)

transition "in" check › should transition if string state path matches current state value → STATEIN (+ the hand-written parallel machine answers a full state value { a: 'a1', b: 'b2' } true and a partial { a: 'a2' } false; the outline's In evaluator covers matchesState on the pre-event value).
transition "in" check › should transition if state node ID matches current state value → STATEIN (+ checkStateIn(snapshot, '#b_b2') true, and data-last checkStateIn('#b_b2')(snapshot) true).
transition "in" check › should not transition if string state path does not match current state value → STATEIN (+ checkStateIn(snapshot, '#b_b1') and data-last false for an inactive id).
transition "in" check › should not transition if state value matches current state value → STATEIN (+ the scenario's { a: 'a2' } false case; the old title is misnamed, the old test does transition when the b-region value matches).
transition "in" check › matching should be relative to grandparent (match) → STATEIN (+ checkStateIn(self.getSnapshot(), '#bar1') is an id-active lookup; the scenario answers ids true in both forms).
transition "in" check › matching should be relative to grandparent (no match) → STATEIN (+ the same id lookup false).
transition "in" check › should work to forbid events → OUTLINE (+ the parent node's In guard on { red: 'stop' } and the region fallback are the model's In slot with a fallback to the region/root).
transition "in" check › should be possible to use a referenced stateIn guard → OUTLINE (+ a Named guard source inside a transition function; the model's Named evaluator calls guards.atLeast, and the ledger records a named source asked under each factory).
transition "in" check › it.skip should be possible to check an ID with a path → uncovered: the test was already skipped in the old suite (its stateIn('#b.B1') guard was commented out and replaced by an inline matchesState('#b.B1', value) call), and no live case exercises the compound #id.child path form; the fixed scenario covers ids and plain paths, which is the form the old suite's live tests use.

Fixed scenarios added for behaviour the outline does not reach

• INTERIM — the old should check guards with interim states multi-region, one-microstep eventless step (the outline's In slots are absolute paths only, so a dedicated scenario pins the interim-value read).
• CUSTOM — the old custom guards › should evaluate custom guards parameterised source.
• TARGET — a declared target moving the actor, pinning admission distinct from the generated Target slots.
• MISSING / THROW / ARGS / ZERO / STATEIN — the error and guard-argument behaviours, each with a hand-written expectation.

Target form note

The generated Target slot emits the published bare-string form (GO: '#q') for the createMachine and provide factories; the setup factory builds the same topology with the object form ({ target: '#q' }) because setup's TransitionConfigOrTarget has no bare-string member and validates on keys against the declared event schemas. Both forms feed the engine's same admission, so the model predicts one behaviour.

API report

etc/xstate.api.md gains one overload; the other diffs in etc/ are chunk-hash renames in ae-forgotten-export comments.

export function checkStateIn(stateValue: StateValue): (snapshot: AnyMachineSnapshot) => boolean;

Changeset .changeset/guards-capability.md (minor) declares it.

Mutated set

packages/xstate/stryker.config.ts adds src/transitionGuards.ts. This PR's own release-gate run is to be the mutation proof: 0 Survived and 0 NoCoverage in that file. No run on this head has finished yet: runs 37956675935 and 37962882414 lost their runner mid-shard (exit 143), and run 37959701505's shard ended with exit 3 during the checker stage.

Enrolment (XS1)

src/transitionGuards.ts and the spec join the lint script, tsconfig.tsgo.json and XS1's enrolled list in packages/AGENTS.md. No disable comments; no casts or any in the spec or its fixtures.

Gates (local, on the head)

• bin/dprint check, tsc -b, tsc -p tsconfig.test.json --noEmit, pnpm run lint, pnpm run lint:tsgo (14 src files checked, 0 diagnostics), pnpm run build (API check included): all exit 0.
• Spec, seeds 1, 2 and 3: 13 passed each, identical case names.
• Full xstate suite, seeds 1, 2 and 3: 137 files, 2334 passed, 23 skipped, 3 todo on each. Before the deletion it was 139 files, 2364 passed, 26 skipped; the two deleted files held 30 passing and 3 skipped cases.
• No local mutation testing of any kind.