refactor(machines): make machine-transition actually pure — allocator-in-snapshot replaces spawn-counter atom (rf2-gr8q)

[mike-thompson-day8]

Summary

Per rf2-gr8q's Shape 1 decision (2026-05-12): the module-level (defonce spawn-counter (atom {})) in re-frame.machines.transition is gone. Spawn-id allocation for declarative :invoke / :invoke-all now lives inside the parent snapshot at the reserved :rf/spawn-counter slot — a per-machine-id integer map bumped via update-in inside apply-transition-once and returned as part of the new snapshot.

Before / after

Before. machine-transition's docstring promised "Pure function. JVM- and CLJS-runnable, deterministic." but the implementation transitively called next-spawn-id, which did (swap! spawn-counter ...) on a module-level atom. The conformance corpus only produced deterministic ids because the test fixture's :machines/reset-counters! hook zeroed the atom between fixtures — the function itself was not pure.

After. (machine-transition machine snap event) is deterministic from its arguments — calling it twice with the same triple returns identical [next-snapshot effects] pairs including the spawn-id sequencing inside emitted :rf.machine/spawn fx maps. The new re-frame.machine-transition-purity-test namespace locks the property in.

Surface changes

• re-frame.machines.transition:

  • spawn-counter defonce + next-spawn-id removed; replaced with the pure allocate-spawned-id [snap machine-id] -> [snap' spawned-id] helper.
  • handle-invoke-spawn / handle-invoke-all-spawn thread the snapshot through allocation.

• re-frame.machines.parallel: parallel-machine-transition and apply-initial-entry-cascade thread :rf/spawn-counter across regions (matching how :data is threaded).

• re-frame.machines.lifecycle-fx:

  • synthesise-initial-snapshot stamps :rf/spawn-counter {} on every freshly-registered machine snapshot.
  • compute-actor-id split into pre-allocated-actor-id + allocate-actor-id-in-db (the hand-emitted-spawn fallback now bumps [:rf/spawn-counter <machine-id>] in the frame's app-db inside the same swap as the snapshot install).

• re-frame.machines façade: spawn-counter re-export gone. reset-counters! kept (with the :machines/reset-counters! late-bind hook preserved for fixture back-compat) but now only cancels in-flight :after wall-clock timers — no more counter atom to reset.

• spec/Spec-Schemas.md §:rf/machine-snapshot: optional :rf/spawn-counter slot documented as runtime-owned, user-read-only [:map-of :keyword :int].

• Six conformance fixtures asserting :expect-next-snapshot after declarative spawn updated to include the bumped :rf/spawn-counter.

• New regression test implementation/machines/test/re_frame/machine_transition_purity_test.clj asserts: identical args → identical results (including spawn-id sequencing), independent input snapshots allocate from their own counters, pre-populated counters keep their sequencing.

• implementation/core/test/re_frame/smoke_test.clj spawn-id-is-frame-scoped rewritten to read each frame's parent machine snapshot's :rf/spawn-counter slot. rf-machine-sub's expected snapshot updated for the new slot.

Test plan

• implementation/machines clojure -M:test: 116 tests / 316 assertions / 0 failures
• implementation/core clojure -M:test: 226 tests / 1024 assertions / 0 failures (the conformance corpus's 110 runnable fixtures all pass)
• npm run test:cljs: 571 tests / 1353 assertions / 0 failures
• npm run test:browser: 559 tests / 1345 assertions / 0 failures
• npm run test:elision, test:bundle-isolation, test:bundle-comparison, test:examples: all pass
• implementation/http and implementation/routing clojure -M:test: all pass