refactor(onboard): make runtime the machine authority
- Dominant language
- TypeScript
- Stars
- 22.5k
- Forks
- 3.1k
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 715
Description
## Ownership
@cv owns this issue.
Do not start, assign, or submit this work unless @cv transfers ownership in this issue.
## Problem
Session step helpers can still move the persisted machine snapshot through a compatibility option.
This creates two machine authorities: `OnboardRuntime` and step mutation.
## Desired behavior
- `OnboardRuntime` owns machine transitions, revision increments, terminal state, and machine events.
- Step helpers own only step status.
- State handlers return explicit results.
- Every production transition passes through runtime validation.
- Older sessions normalize before runtime execution without restoring implicit transition ownership.
## Change boundary
Remove production use of `LEGACY_MACHINE_STEP_MUTATION_OPTIONS`.
Remove the option when no current migration consumer remains.
Do not change user-visible onboarding behavior.
## Security
Runtime context filtering and event redaction must remain the only persistence boundary for handler results.
## Validation
- Test that step updates do not change machine state or revision.
- Test that runtime application changes both exactly once.
- Test terminal idempotency and invalid-transition rejection.
- Test normalized legacy-session entry.
- Preserve journey-level transition traces.
## Completion
No production step helper can mutate the machine snapshot.
Contributor guide
Assessment
This issue has not been assessed yet.