refactor(onboard): allow step recording without machine transitions

src/lib/onboard/machine/runner.test.ts

@@ -51,13 +51,19 @@ function createRuntime(initialSession: Session = createSession()) {
         Object.assign(current, filterSafeUpdates(updates));
         return current;
       }),
+    markStepCompleteRecordOnly: (_stepName, updates: SessionUpdates = {}) =>
+      updateSession((current) => {
+        Object.assign(current, filterSafeUpdates(updates));
+        return current;
+      }),
     markStepSkipped: () => cloneSession(session),
     markStepFailed: (_stepName, message) =>
       updateSession((current) => {
         current.status = "failed";
         current.failure = sanitizeFailure({ step: _stepName, message, recordedAt: "now" });
         return current;
       }),
+    markStepFailedRecordOnly: () => cloneSession(session),
     completeSession: (updates: SessionUpdates = {}) =>
       updateSession((current) => {
         Object.assign(current, filterSafeUpdates(updates));

src/lib/onboard/machine/runtime.test.ts

@@ -7,9 +7,9 @@ import {
   createSession,
   filterSafeUpdates,
   normalizeSession,
-  sanitizeFailure,
   type Session,
   type SessionUpdates,
+  sanitizeFailure,
 } from "../../state/onboard-session";
 import type { OnboardMachineEvent } from "./events";
 import {
@@ -62,6 +62,15 @@ function createHarness(initialSession: Session | null = createSession()) {
         Object.assign(current, filterSafeUpdates(updates));
         return current;
       }),
+    markStepCompleteRecordOnly: (stepName, updates: SessionUpdates = {}) =>
+      updateSession((current) => {
+        const step = current.steps[stepName];
+        if (!step) return current;
+        step.status = "complete";
+        current.lastCompletedStep = stepName;
+        Object.assign(current, filterSafeUpdates(updates));
+        return current;
+      }),
     markStepSkipped: (stepName) =>
       updateSession((current) => {
         const step = current.steps[stepName];
@@ -78,6 +87,14 @@ function createHarness(initialSession: Session | null = createSession()) {
         current.failure = sanitizeFailure({ step: stepName, message, recordedAt: "now" });
         return current;
       }),
+    markStepFailedRecordOnly: (stepName, message) =>
+      updateSession((current) => {
+        const step = current.steps[stepName];
+        if (!step) return current;
+        step.status = "failed";
+        step.error = message ?? null;
+        return current;
+      }),
     completeSession: (updates: SessionUpdates = {}) =>
       updateSession((current) => {
         Object.assign(current, filterSafeUpdates(updates));

src/lib/onboard/machine/runtime.ts

@@ -2,8 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import type { JsonObject } from "../../core/json-types";
-import * as onboardSession from "../../state/onboard-session";
 import type { Session, SessionUpdates } from "../../state/onboard-session";
+import * as onboardSession from "../../state/onboard-session";
 import type { ResumeConfigConflict } from "../resume-config";
 import {
   createOnboardMachineEvent,
@@ -25,8 +25,10 @@ export interface OnboardRuntimeDeps {
   updateSession(mutator: (session: Session) => Session | void): Session;
   markStepStarted(stepName: string): Session;
   markStepComplete(stepName: string, updates?: SessionUpdates): Session;
+  markStepCompleteRecordOnly(stepName: string, updates?: SessionUpdates): Session;
   markStepSkipped(stepName: string): Session;
   markStepFailed(stepName: string, message?: string | null): Session;
+  markStepFailedRecordOnly(stepName: string, message?: string | null): Session;
   completeSession(updates?: SessionUpdates): Session;
   filterSafeUpdates(updates: SessionUpdates): Partial<Session>;
   emitEvent(event: OnboardMachineEvent): void;
@@ -64,8 +66,10 @@ function defaultDeps(): OnboardRuntimeDeps {
     updateSession: onboardSession.updateSession,
     markStepStarted: onboardSession.markStepStarted,
     markStepComplete: onboardSession.markStepComplete,
+    markStepCompleteRecordOnly: onboardSession.markStepCompleteRecordOnly,
     markStepSkipped: onboardSession.markStepSkipped,
     markStepFailed: onboardSession.markStepFailed,
+    markStepFailedRecordOnly: onboardSession.markStepFailedRecordOnly,
     completeSession: onboardSession.completeSession,
     filterSafeUpdates: onboardSession.filterSafeUpdates,
     emitEvent: emitOnboardMachineEvent,
@@ -120,6 +124,10 @@ export class OnboardRuntime {
     return this.deps.markStepComplete(stepName, updates);
   }
 
+  async markStepCompleteRecordOnly(stepName: string, updates: SessionUpdates = {}): Promise<Session> {
+    return this.deps.markStepCompleteRecordOnly(stepName, updates);
+  }
+
   async markStepSkipped(stepName: string): Promise<Session> {
     return this.deps.markStepSkipped(stepName);
   }
@@ -128,6 +136,10 @@ export class OnboardRuntime {
     return this.deps.markStepFailed(stepName, message);
   }
 
+  async markStepFailedRecordOnly(stepName: string, message: string | null = null): Promise<Session> {
+    return this.deps.markStepFailedRecordOnly(stepName, message);
+  }
+
   async completeSession(updates: SessionUpdates = {}): Promise<Session> {
     return this.deps.completeSession(updates);
   }

src/lib/onboard/runtime-boundary-record-only.test.ts

@@ -0,0 +1,155 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, it } from "vitest";
+
+import {
+  createSession,
+  filterSafeUpdates,
+  normalizeSession,
+  type Session,
+  type SessionUpdates,
+} from "../state/onboard-session";
+import type { OnboardMachineEvent } from "./machine/events";
+import { advanceTo, failOnboardMachine } from "./machine/result";
+import { OnboardRuntime, type OnboardRuntimeDeps } from "./machine/runtime";
+import { OnboardRuntimeBoundary } from "./runtime-boundary";
+
+function cloneSession(session: Session): Session {
+  return normalizeSession(JSON.parse(JSON.stringify(session))) ?? session;
+}
+
+function createRuntimeHarness() {
+  let session: Session = createSession();
+  const events: OnboardMachineEvent[] = [];
+  const updateSession = (mutator: (value: Session) => Session | void): Session => {
+    session = cloneSession(mutator(cloneSession(session)) ?? session);
+    return cloneSession(session);
+  };
+  const deps: OnboardRuntimeDeps = {
+    loadSession: () => cloneSession(session),
+    createSession,
+    saveSession: (next) => {
+      session = cloneSession(next);
+      return cloneSession(session);
+    },
+    updateSession,
+    markStepStarted: (stepName) =>
+      updateSession((current) => {
+        current.steps[stepName].status = "in_progress";
+        return current;
+      }),
+    markStepComplete: (stepName, updates: SessionUpdates = {}) =>
+      updateSession((current) => {
+        current.steps[stepName].status = "complete";
+        Object.assign(current, filterSafeUpdates(updates));
+        return current;
+      }),
+    markStepCompleteRecordOnly: (stepName, updates: SessionUpdates = {}) =>
+      updateSession((current) => {
+        current.steps[stepName].status = "complete";
+        Object.assign(current, filterSafeUpdates(updates));
+        return current;
+      }),
+    markStepSkipped: (stepName) =>
+      updateSession((current) => {
+        current.steps[stepName].status = "skipped";
+        return current;
+      }),
+    markStepFailed: (stepName, message) =>
+      updateSession((current) => {
+        current.steps[stepName].status = "failed";
+        current.steps[stepName].error = message ?? null;
+        current.status = "failed";
+        current.failure = { step: stepName, message: message ?? null, recordedAt: "now" };
+        return current;
+      }),
+    markStepFailedRecordOnly: (stepName, message) =>
+      updateSession((current) => {
+        current.steps[stepName].status = "failed";
+        current.steps[stepName].error = message ?? null;
+        return current;
+      }),
+    completeSession: (updates: SessionUpdates = {}) =>
+      updateSession((current) => {
+        Object.assign(current, filterSafeUpdates(updates));
+        current.status = "complete";
+        return current;
+      }),
+    filterSafeUpdates,
+    emitEvent: (event) => events.push(event),
+    now: () => "2026-05-27T00:00:00.000Z",
+  };
+  return {
+    boundary: new OnboardRuntimeBoundary({
+      toSessionUpdates: (updates) => filterSafeUpdates(updates as SessionUpdates) as SessionUpdates,
+      maybeForceE2eStepFailure: () => undefined,
+      createRuntime: () => new OnboardRuntime(deps),
+    }),
+    events,
+    getSession: () => cloneSession(session),
+  };
+}
+
+describe("OnboardRuntimeBoundary record-only step/result pairing", () => {
+  it("pairs record-only step completion with an explicit state result", async () => {
+    const { boundary, events } = createRuntimeHarness();
+
+    await boundary.recordStateResult(advanceTo("preflight"));
+    const completed = await boundary.recordStepCompleteWithStateResult(
+      "preflight",
+      { sandboxName: "record-only-sb" },
+      advanceTo("gateway", { metadata: { state: "preflight" } }),
+    );
+
+    expect(completed).toMatchObject({
+      sandboxName: "record-only-sb",
+      machine: { state: "gateway", revision: 2 },
+      steps: { preflight: { status: "complete" } },
+    });
+    expect(events.map((event) => event.type)).toEqual([
+      "state.exited",
+      "state.entered",
+      "state.exited",
+      "state.entered",
+    ]);
+  });
+
+  it("pairs record-only step failure with an explicit failure result", async () => {
+    const { boundary, events } = createRuntimeHarness();
+
+    await boundary.recordStateResult(advanceTo("preflight"));
+    const failed = await boundary.recordStepFailedWithStateResult(
+      "preflight",
+      "Preflight failed",
+      failOnboardMachine("Preflight failed", { step: "preflight" }),
+    );
+
+    expect(failed).toMatchObject({
+      status: "failed",
+      failure: { step: "preflight", message: "Preflight failed" },
+      machine: { state: "failed", revision: 2 },
+      steps: { preflight: { status: "failed", error: "Preflight failed" } },
+    });
+    expect(events.map((event) => event.type)).toEqual([
+      "state.exited",
+      "state.entered",
+      "state.failed",
+      "onboard.failed",
+    ]);
+  });
+
+  it("rejects invalid explicit results before persisting record-only step completion", async () => {
+    const { boundary, getSession } = createRuntimeHarness();
+
+    await boundary.recordStateResult(advanceTo("preflight"));
+    await expect(
+      boundary.recordStepCompleteWithStateResult("preflight", {}, advanceTo("sandbox")),
+    ).rejects.toThrow("Invalid onboarding machine transition: preflight -> sandbox");
+
+    expect(getSession()).toMatchObject({
+      machine: { state: "preflight", revision: 1 },
+      steps: { preflight: { status: "pending" } },
+    });
+  });
+});

src/lib/onboard/runtime-boundary.test.ts

@@ -110,6 +110,7 @@ function createRuntimeHarness(overrides: Partial<Session> = {}) {
         if (nextState) transitionMachine(current, nextState);
         return current;
       }),
+    markStepCompleteRecordOnly: () => cloneSession(session ?? createSession()),
     markStepSkipped: (stepName) =>
       updateSession((current) => {
         current.steps[stepName].status = "skipped";
@@ -121,6 +122,7 @@ function createRuntimeHarness(overrides: Partial<Session> = {}) {
         current.failure = { step: stepName, message: message ?? null, recordedAt: "now" };
         return current;
       }),
+    markStepFailedRecordOnly: () => cloneSession(session ?? createSession()),
     completeSession: (updates: SessionUpdates = {}) =>
       updateSession((current) => {
         Object.assign(current, filterSafeUpdates(updates));

src/lib/onboard/runtime-boundary.ts

@@ -2,8 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import type { Session, SessionUpdates } from "../state/onboard-session";
-import type { OnboardStateResult } from "./machine/result";
+import type { OnboardStateFailedResult, OnboardStateResult } from "./machine/result";
 import { OnboardRuntime } from "./machine/runtime";
+import { assertValidOnboardMachineTransition } from "./machine/transitions";
 import type { OnboardMachineEventType, OnboardMachineState } from "./machine/types";
 import type { ResumeConfigConflict } from "./resume-config";
 
@@ -51,6 +52,8 @@ export class OnboardRuntimeBoundary {
       recordRepairEvent: this.recordRepairEvent.bind(this),
       recordResumeConflict: this.recordResumeConflict.bind(this),
       recordStateResult: this.recordStateResult.bind(this),
+      recordStepCompleteWithStateResult: this.recordStepCompleteWithStateResult.bind(this),
+      recordStepFailedWithStateResult: this.recordStepFailedWithStateResult.bind(this),
       recordStateResultWithStepCompatibility: this.recordStateResultWithStepCompatibility.bind(this),
       recordStepFailed: this.recordStepFailed.bind(this),
       recordPostVerifyStarted: this.recordPostVerifyStarted.bind(this),
@@ -102,6 +105,55 @@ export class OnboardRuntimeBoundary {
     return this.getRuntime().applyResult(result);
   }
 
+  private async assertStateResultWillApply(result: OnboardStateResult): Promise<void> {
+    const current = await this.getRuntime().session();
+    if (result.type === "failed") {
+      assertValidOnboardMachineTransition(current.machine.state, "failed");
+      return;
+    }
+    if (result.type === "complete") {
+      assertValidOnboardMachineTransition(current.machine.state, "complete");
+      return;
+    }
+
+    const sourceState =
+      result.metadata && typeof result.metadata.state === "string" ? result.metadata.state : null;
+    if (current.machine.state === result.next) {
+      throw new Error(`Record-only step result already reached target state: ${result.next}`);
+    }
+    if (sourceState && current.machine.state !== sourceState) {
+      throw new Error(
+        `Record-only step result source mismatch: ${sourceState} != ${current.machine.state}`,
+      );
+    }
+    const transition = assertValidOnboardMachineTransition(current.machine.state, result.next);
+    if (result.transitionKind && transition.kind !== result.transitionKind) {
+      throw new Error(
+        `Invalid onboarding machine transition kind: ${current.machine.state} -> ${result.next} expected ${result.transitionKind}, got ${transition.kind}`,
+      );
+    }
+  }
+
+  async recordStepCompleteWithStateResult(
+    stepName: string,
+    updates: SessionUpdates,
+    result: OnboardStateResult,
+  ): Promise<Session> {
+    await this.assertStateResultWillApply(result);
+    await this.getRuntime().markStepCompleteRecordOnly(stepName, updates);
+    return this.recordStateResultWithStepCompatibility(result);
+  }
+
+  async recordStepFailedWithStateResult(
+    stepName: string,
+    message: string | null,
+    result: OnboardStateFailedResult,
+  ): Promise<Session> {
+    await this.assertStateResultWillApply(result);
+    await this.getRuntime().markStepFailedRecordOnly(stepName, message);
+    return this.recordStateResult(result);
+  }
+
   /**
    * Compatibility bridge for the live onboarding host glue while legacy step helpers remain a
    * second machine snapshot writer. `markStepStarted()` and `markStepComplete()` still mutate

src/lib/state/onboard-session.test.ts

@@ -1,11 +1,11 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import fs from "node:fs";
+import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
-import { createRequire } from "node:module";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 const require = createRequire(import.meta.url);
 const distPath = require.resolve("../../../dist/lib/state/onboard-session");