[systemfsoftware-maker]

Capability 5 of 31 (graph): @systemfsoftware/xstate/graph is judged by one conformance spec over a hand-written model and no longer by its ported tests. The five published path functions also gain data-last forms (ruling 186).

• Spec: packages/xstate/tests/graph.conformance.test.ts (20 cases: a 3-seed outline plus 17 fixed scenarios), model tests/__fixtures__/graph.model.ts, subject fixture tests/__fixtures__/graph.ts.
• Deleted: the 8 src/graph/test files (91 cases, 3 skipped, plus a 1,232-line snapshot) and src/graph/types.test.ts.

Behaviour-to-test map (CONST-T9)

Every it in the deleted packages/xstate/src/graph test files, mapped to the
conformance spec (packages/xstate/tests/graph.conformance.test.ts), its model
(__fixtures__/graph.model.ts) and its subject fixture (__fixtures__/graph.ts).

Coverage keys:

• outline — the seeded scenarioOutline "Every machine, sequence and query the
  model draws from seed agrees with the published graph API" (seeds 1–3); the
  bracket names the Traverse operation / query option / Structure field it exercises.
• fixed — a hand-written scenario in the same spec.
• types — a row of typeLevelContract (checked by tsc, no runner import).
• uncovered — not exercised, with the reason.

src/graph/types.test.ts (type-only → typeLevelContract)

• getEvents should be allowed to return a mutable array → types row 1 (events: [{ type: 'FOO' }]).
• getEvents should be allowed to return a readonly array → types row 2 (as const).
• events should allow known event → types row 3 (declared FOO accepted).
• events should not require all event types (array literal expression) → types row 1 (a subset is accepted).
• events should not require all event types (tuple) → types row 2.
• events should not require all event types (function) → types row 3 (function form).
• events should not allow unknown events → types row 4 (@ts-expect-error type: 'UNKNOWN').
• events should only allow props of a specific event → types row 5 (@ts-expect-error other).
• serializeEvent should be allowed to return plain string → types row 6.
• serializeState should be allowed to return plain string → types row 7.

src/graph/test/adjacency.test.ts

• model generates an adjacency map (converted to an array) → outline: adjacency (target/limit/serialize/input), via getAdjacencyMap + adjacencyMapToArray.
• function generates an adjacency map (converted to an array) → outline: adjacency + customEvents (array and function forms of options.events).

src/graph/test/dieHard.test.ts (bounded counter+guard machine)

• shortest paths › should generate the right number of paths (2) → outline: shortest + counter machine; covered generically, not the literal 2.
• shortest paths › replays <path> (×2, generated) → outline: shortest paths are replayed and their step events compared.
• simple paths › should generate the right number of paths (14) → outline: simple + counter machine.
• simple paths › replays <path> (×14, generated) → outline: simple paths replayed and compared.
• paths from events › replays the path → outline: Replay (sequence + candidate) + fixed "Replaying a finite sequence on plain logic…".
• paths from events › should return no paths if the target does not match the last entered state → outline: Replay target/stop with toState.
• simple paths with a narrower target › should generate the right number of paths (6) → outline: simple + target.
• simple paths with a narrower target › replays <path> (×6, generated) → outline: simple + target, paths replayed.

src/graph/test/graph.test.ts

• getDescendantStateNodes() › should return an array of all nodes → outline: Structure descendantIds (pre-order).
• getDescendantStateNodes() › should return an array of all nodes (parallel) → outline: parallel + Structure descendantIds (a fixed parallel machine's descendant order and per-region targets).
• getShortestPaths() › should return a mapping of shortest paths to all states → outline: shortest.
• getShortestPaths() › should return a mapping of shortest paths to all states (parallel) → outline: parallel (a fixed parallel machine's shortest state sequences, compared order-insensitively).
• getShortestPaths() › the initial state should have a single-length path → outline: shortest (init-only path) + fixed replay scenario (weight 1).
• getShortestPaths() › it.skip 'should not throw when a condition is present' → uncovered: skipped upstream; guard conditions are exercised via the counter guard, not a guard throwing.
• getShortestPaths() › it.skip 'should represent conditional paths based on context' → uncovered: skipped upstream; conditional/targeted paths via target are covered.
• getSimplePaths() › should return a mapping of arrays of simple paths to all states → outline: simple.
• getSimplePaths() › should return a mapping of simple paths to all states (parallel) → outline: parallel (a fixed parallel machine's simple state sequences, compared order-insensitively).
• getSimplePaths() › should return multiple paths for equivalent transitions → outline: simple (dedup by (state,event) with distinct targets collapse to one edge — one path per distinct transition target).
• getSimplePaths() › should return a single-length path for the initial state → outline: simple init-only path.
• getSimplePaths() › should return value-based paths → outline: serialize: 'value'.
• getSimplePaths() › should support filtering disabled events → outline: filter + fixed "adjacency that ignores the event filter is caught".
• getPathFromEvents() › should return a path to the last entered state by the event sequence → outline: Replay candidate: 'last' + fixed replay scenarios.
• getPathFromEvents() › it.skip 'should throw when an invalid event sequence is provided' → uncovered: skipped upstream; there is no "invalid" event for the generated candidate set.
• getPathFromEvents() › should return a path from a specified from-state → fixed "Replaying from a specified from-state begins at that state" (one TIMER from yellow lands on red).
• getPathFromEvents() › does not treat custom logic with a getStateNodeById property as a machine → fixed "A custom logic carrying getStateNodeById is traversed as plain logic" (one INC reaches context 1).
• it.each 'from-state can be specified' → outline ("Every machine, sequence and query the model draws from seed agrees with the published graph API"), fromSecond class (shortest, simple and replay queries start from machine.resolveState of the second state; the ledger requires it on every seed).
• toDirectedGraph › should represent a statechart as a directed graph → fixed "toDirectedGraph renders a machine, its root state node and an identity-independent proxy alike" (hand-written node ids, children and edge source/target/label of a light statechart).
• toDirectedGraph › does not rely on StateMachine constructor identity → the same fixed scenario: a null-prototype Proxy of the machine renders the same graph.
• simple paths for transition functions → outline ("Every machine, sequence and query the model draws from seed agrees with the published graph API"), plainLogic class: a non-machine logic built with createLogic through getSimplePaths, data-first and data-last (plainForms ledger, required on every seed).
• shortest paths for transition functions → the same plainLogic class through getShortestPaths, both forms.
• filtering › should not traverse past filtered states → outline ("Every machine, sequence and query the model draws from seed agrees with the published graph API"), stop class on counted (context-carrying) machines: stopWhen ends traversal at the predicate's state.
• should provide previous state for serializeState() → fixed "The serializer receives each state with its entering event and its previous state" (keys a|init|none, b|toB|a, c|toC|b, a|toA|c).
• joinPaths() › should join two paths → outline ("Every machine, sequence and query the model draws from seed agrees with the published graph API"), join outcome joined.
• joinPaths() › should not join two paths with mismatched source/target states → outline ("Every machine, sequence and query the model draws from seed agrees with the published graph API"), join outcome refused-mismatch (model message Paths cannot be joined).

src/graph/test/index.test.ts

• events › should allow for dynamic generation of cases based on state → outline: default events are derived per snapshot from the active node's transitions; customEvents additionally pins the array/function override forms.
• state limiting › should limit states with stopWhen option → outline: stop.
• prevents infinite recursion based on a provided limit → outline: limit + fixed "Replaying a finite sequence on plain logic uses the input and the default serializer" (limit 1).
• should traverse with input → outline: input (zero/one) on input-seeded machines.

src/graph/test/paths.test.ts

• getSimplePaths › returns one path per reachable state → outline: simple.
• getSimplePaths › should support filtering disabled events → outline: filter.
• transition coverage › shortest paths reach every state → outline: shortest.
• transition coverage › transition coverage should consider multiple transitions with the same target → fixed "Two transitions out of one state are both drawn as distinct simple paths" (exact hand-written list of simple-path event sequences); the outline's shortest/simple dedup by (state,event) also applies.
• toState › Should find a path to a non-initial target state → outline: target.
• toState › Should find a path to an initial target state → outline: target (fromSecond also exercised).
• paths from paths › should join shortest paths from the end of other paths → outline: join queries (joined outcome; the model concatenates head steps with the tail's steps after its first, sums the weights, ends at the tail's state).

src/graph/test/shortestPaths.test.ts

• finds the shortest paths to a state without continuing traversal from that state → outline: shortest + stop/target.
• finds the shortest paths from a state to another state → outline: shortest + fromSecond.
• handles event cases → outline: default events per snapshot (NEXT/JUMP/BACK).
• should work for machines with delays → fixed "A machine with a delayed transition reaches its next state on the after event".

src/graph/test/traversal-regressions.test.ts

• replays a finite sequence on unbounded logic → fixed "Replaying a finite sequence on plain logic uses the input and the default serializer"; outline: Replay on plain logic.
• uses input when replaying machine events → fixed "Replaying a finite sequence…"; outline: input.
• honors replay filters, stopping and target predicates → outline: Replay filter/stop/target.
• replays the last permitted override candidate matching a serialized event → outline: Replay candidate: 'last' + fixed "A replay that takes the first matching override candidate is caught as a model divergence".
• it.each 'initializes custom logic once in a path generator' → fixed "A custom logic initializes exactly once per traversal call, with and without an explicit from-state" (the logic's own context factory counts its calls: 1 per getShortestPaths/getSimplePaths call).
• it.each 'initializes a machine once with explicit undefined fromState: %s' → fixed "A machine initializes exactly once per traversal call with an explicit undefined from-state" (a machine whose context factory counts its calls; shortest, simple and replay with { fromState: undefined, events: [] } each give 1 path and 1 call; the same row also passes against main's src/graph).
• it.each 'accepts arbitrary serialized state/event keys: %s' → fixed "Serialized state and event keys that collide with Object.prototype members address real entries" (__proto__, constructor, toString, hasOwnProperty, '' through getAdjacencyMap, getShortestPaths and getSimplePaths).

Additional fixed scenarios not tied to a deleted it

• "The published serializeSnapshot omits an empty context and keeps a non-empty one" → pins the serializeSnapshot entrypoint.
• (removed in 959e3f7) "Joining two paths whose source and target states differ is refused" → now outline: join queries (refused-mismatch and refused-empty outcomes, model message Paths cannot be joined).
• "The published graph entrypoint exposes only the graph API" → pins the nine exported names.

Spec 13 -> 11 cases: the two join scenarios moved into the outline

959e3f7 ("judge every published call form against the model") deleted two fixed scenarios and generated join queries from the seeded model instead, so the data-first and data-last joinPaths forms are both judged:

• "Joining two paths that meet head to tail yields the concatenated path" (it pinned ['@xstate.init','NEXT','TO_C'] for a path to b joined with a path from b to c).
• "Joining two paths whose source and target states differ is refused" (it pinned the message Paths cannot be joined).

Both are now covered by the outline "Every machine, sequence and query the model draws from seed agrees with the published graph API" (seeds 1-3). The fixture model (tests/__fixtures__/graph.model.ts, the join response) predicts joined with the concatenated steps, summed weight and tail state, or failed with Paths cannot be joined when the tail is empty or starts elsewhere. The outline's liveness row ("every operation, call form, join outcome ... occurred") requires joined, refused-mismatch and refused-empty to occur on every seed. No other case was removed.

Cycle 207 then added 9 fixed scenarios for the deleted groups the map had left out (rows above), so the spec now has 20 cases.

API report

git diff origin/main...HEAD -- packages/xstate/etc/xstate-graph.api.md: 42 insertions, 18 deletions, all in xstate-graph.api.md. No other etc/*.api.md file changes. Every change, grouped by kind:

New overloads (data-last forms; declared in the changeset). Each is added under // @public (undocumented) next to the existing data-first signature:

export function getAdjacencyMap<…>(options: TraversalOptions<TSnapshot, TEvent, TInput>): (logic: ActorLogic<TSnapshot, TEvent, TInput, TSystem>) => AdjacencyMap<TSnapshot, TEvent>;
export function getPathsFromEvents<…>(events: TEvent[], options?: TraversalOptions<TSnapshot, TEvent, TInput>): (logic: ActorLogic<TSnapshot, TEvent, TInput, TSystem>) => Array<StatePath<TSnapshot, TEvent>>;
export function getShortestPaths<TLogic extends AnyActorLogic>(options?: TraversalOptions<…>): (logic: TLogic) => Array<StatePath<SnapshotFrom<TLogic>, EventFromLogic<TLogic>>>;
export function getSimplePaths<TLogic extends AnyActorLogic>(options?: TraversalOptions<…>): (logic: TLogic) => Array<StatePath<SnapshotFrom<TLogic>, EventFromLogic<TLogic>>>;
export function joinPaths<TSnapshot extends AnySnapshot, TEvent extends EventObject>(tailPath: StatePath<TSnapshot, TEvent>): (headPath: StatePath<TSnapshot, TEvent>) => StatePath<TSnapshot, TEvent>;

On main, getAdjacencyMap and joinPaths had their data-first overload listed first. The report now lists the data-last overload first for these two, so the order of overloads in the declarations changed as well.

New export (declared in the changeset). export type AnySnapshot<TOutput = unknown> = Snapshot<TOutput>.

Narrowed parameter (declared in the changeset). serializeSnapshot(snapshot: Snapshot<any>) became serializeSnapshot(snapshot: AnySnapshot & { value?: StateValue; context?: MachineContext }). A type probe on a scratch copy shows the narrowing: serializeSnapshot on a value typed Snapshot<undefined> & { context: number }, or & { value: number[] }, compiles on main and fails on this head (TS2345). Machine snapshots still compile. The report also gains forgotten-export warnings for StateValue and MachineContext, and the dist/graph.d.ts line numbers in the warning footer moved.

Bound and alias spellings with the same meaning (no consumer-visible change).

• TSnapshot extends Snapshot<unknown> became TSnapshot extends AnySnapshot (= Snapshot<unknown>). This applies to getAdjacencyMap, getPathsFromEvents, joinPaths, PathGenerator, SerializationConfig, StatePath, StatePlanMap, Step, Steps, TraversalConfig and TraversalOptions.
• TSystem extends ActorSystem<any> = ActorSystem<any> became TSystem extends AnyActorSystem = AnyActorSystem (= ActorSystem<any>, src/system.ts). This applies to getAdjacencyMap and getPathsFromEvents.
• DirectedGraphEdge.transition: TransitionDefinition<any, any> became AnyTransitionDefinition (= TransitionDefinition<any, any>, src/types.ts).
• AnyStateNode: StateNode<any, any> became StateNode. The bare form means StateNode<MachineContext, EventObject>, so this is the one rewrite that is not alias-identical. The same type probe assigns a typed machine's root and a child node (context { count: number }, two typed events) to AnyStateNode and passes the machine, its root and a child to toDirectedGraph. That compiles on this head and against main's graph/types.ts, so no consumer-visible difference was found. It is not in the changeset.

Behaviours beyond the deleted tests (added coverage)

• options.events (array and function forms) — the outline's customEvents bracket calls each Traverse/adjacency query with a hand-picked event list and with a per-state function, for both counted and plain machines; the model traverses exactly those events. Fixed class customEvents in the fixture ledger.

• Parallel machines — the outline's Parallel bracket builds a fixed two-region machine (left/right, each region a 2-node machine) and compares adjacency (canonicalised row order), shortest/simple state sequences (canonicalised order) and getDescendantStateNodes. Fixed class parallel.

• adjacencyMapToArray order — the adjacencyArray class pins the row order ((state,event,nextState) insertion order over Object.values), projecting each entry through the caller's serializeState/serializeEvent.

• Machine classification (restored). cbd321867 restores main's structural machine check in graph.ts: a machine needs a root with a string id, a states object and a transitions.values function, plus getStateNodeById, resolveState and getTransitionData. The lint enrolment had loosened it to 'root' in logic. Fixed scenario "A logic carrying a non-machine root member is traversed as plain logic, not as a machine" pins it: a createLogic logic carrying root: { id: 'x' } gives the single plain adjacency key s0. Run against ea37f3278's graph.ts (the loose check) in a scratch copy, that row is the only failure (1 failed | 19 passed (20), a TypeError in the machine-events path). It passes on this head on seeds 1-3.

Uncovered behaviour and why

• No behaviour change in the events override. On main, resolveTraversalOptions spreads ...traversalOptions after the machine defaults, so a caller's events already replaced the defaults' per-snapshot merge function outright. That merge ran only when no events was given, and then returned the machine's own events unchanged. This branch deletes that unreachable merge (createDefaultMachineOptions now returns getAllOwnEvents directly), and the model traverses exactly the caller's events (customEvents) or the machine's own events otherwise, as main does.
• Two it.skip cases in graph.test.ts and one in getPathFromEvents — skipped upstream; carried as skipped and deliberately not asserted.
• index.test.ts's dynamic-generation it is covered only as the width-1 case — the outline's shuffle forces width 1 at seed 1 and exercises the width-2/3 branches at seeds 2–3; the inline snapshot's exact case list is not reproduced.

Mutated set

packages/xstate/stryker.config.ts adds the seven src/graph files with runtime logic: actorScope.ts, adjacency.ts, alterPath.ts, graph.ts, pathFromEvents.ts, shortestPaths.ts, simplePaths.ts. types.ts (types only) and index.ts (re-exports) are not mutated. The set after this PR: assert.ts, stateMatching.ts, mapState.ts, fsm.ts and those seven files.

Ledger and lint enrolment (XS1)

• xstate has no debt-ledger entry; capability 1 removed it, so the ledger is unchanged here.
• XS1's enrolled list in packages/AGENTS.md adds src/graph/, which the lint script and tsconfig.tsgo.json name as a whole folder.
• The recommended lint and lint:tsgo now cover src/graph, the spec and its fixtures. Every finding is fixed without disable comments.
• missing-pipeable-signature is fixed by the data-last overloads below, not by a lint patch.
• lint:tsgo checks 13/13 enrolled src files with 0 diagnostics.

Data-last forms and changeset

.changeset/graph-data-last-forms.md (minor). One implementation per function branches on an exact runtime shape check: argument count, 'transition' in for actor logic (actor logic always has a transition member and TraversalOptions has none), and Array.isArray for the replay events of getPathsFromEvents. getShortestPaths and getSimplePaths share one logicFirstOrLast dispatch in graph.ts. The spec's typeLevelContract checks that each data-last return type equals its data-first counterpart, and @ts-expect-error rows check the refusals. The outline calls every function in both forms on every seed, and the liveness row requires each form to occur.

Gates on 3b427c1 (main d6cc27e merged)

• dprint, tsc -b, tsc -p tsconfig.test.json --noEmit, pnpm lint and pnpm lint:tsgo (13/13 enrolled files, 0 diagnostics) all exit 0.
• Spec on --sequence.shuffle seeds 1-3: 20 passed (20) each, with the same case names on every seed.
• Full xstate suite on seeds 1-3: 138 files, 2348 passed, 26 skipped, 3 todo, the same on every seed. That is main's 2419, minus the 91 deleted cases, plus the spec's 20.
• No src edit was used as proof, and no mutation of any kind was run locally (ruling 204).

Remaining unguarded

packages/unguarded-tests.json: 174 files (182 on main), 126 of them in xstate (134 on main). xstate's vitest.config.ts unguarded list: 126 (134 on main).

No local mutation run.

[kiro-systemf]

Fresh review PASS 8/8 on 3b427c1; 7/7; 0 threads; every deleted test mapped; main's machine check restored; hunt clean; no effect in src.