Skip to content

refactor: pre-1.0 state API naming and signature polish#140

Merged
joshua-temple merged 6 commits into
mainfrom
refactor/state-api-naming
Jun 5, 2026
Merged

refactor: pre-1.0 state API naming and signature polish#140
joshua-temple merged 6 commits into
mainfrom
refactor/state-api-naming

Conversation

@joshua-temple

Copy link
Copy Markdown
Collaborator

What this change does

Pre-1.0 naming and signature polish on the state public API, from an early-adopter audit. Four focused changes (atomic commits), all pre-tag so they stay out of the frozen 1.0 surface:

  • Invoke outcomes are now options. Invoke(src, ...InvokeOption) / InvokeActor(src, ...InvokeOption) with WithInvokeOnDone(E) / WithInvokeOnError(E), mirroring the existing WithSpawnOnDone/OnError. This was the one place the project broke its own functional-options pattern; moving outcomes off the positional signature lets onCancel / fire-and-forget arrive additively instead of as a future break. Behavior is unchanged for callers that set both.
  • Reducer registration vs. assign wiring are now distinct words. Registry.Assign is renamed to Registry.Reducer (matching Builder.Reducer), and Assign is reserved for the transition-wiring verb. This mirrors the existing Guard/When and Action/Do register-noun / wire-verb split, so no single word means two things. The AssignFn type is unchanged.
  • StopChild collapsed into StopActor. Both emitted the identical StopActor effect; one verb now, aligned with Spawn/SpawnActor.
  • Driver advance verbs converge on Tick. ServiceRunner.Run and ActorSystem.Step become Tick, matching Scheduler.Tick and the already-consistent Absorb/Pending/SettleDone/SettleError set.

Plus godoc cross-references across the Fire / FireSeq / FireEach family.

Why

The audit found the surface in good shape; these are the few items genuinely worth fixing before contracts freeze, biased toward extensibility and developer experience. The Verify rename (PR #139) set the precedent: favor discoverability and additive-friendly signatures over cleverness.

Note: the Tick verb is unified across the three drivers, but their return shapes intentionally still differ (ServiceRunner.Tick settles one service and returns (FireResult, bool); the others return []FireResult). Unifying return shapes is a separate, larger call left for later.

Checklist

  • Commits are signed off (git commit -s) per the DCO
  • Conventional commit messages (type: subject)
  • state build/test/vet green; source + source/statemachine (the only consumer) green; docsgen clean
  • Public API changes documented (godoc, docs site, CHANGELOG under the staged [1.0.0])

Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
@joshua-temple joshua-temple merged commit f17cd94 into main Jun 5, 2026
121 checks passed
@joshua-temple joshua-temple deleted the refactor/state-api-naming branch June 5, 2026 01:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant