NVIDIA / NVIDIA/NemoClaw

refactor(onboard): make runtime the machine authority

Open
#7,703 0 comments 0 reactions 1 assignee Claimed by @cv View on GitHub
area: architecture area: onboarding refactor
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.