refactor(onboard): introduce explicit state result types

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

@@ -0,0 +1,90 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, expectTypeOf, it } from "vitest";
+
+import {
+  advanceTo,
+  branchTo,
+  completeOnboardMachine,
+  failOnboardMachine,
+  type OnboardStateResultTransitionKind,
+  type OnboardStateTransitionHelperOptions,
+  retryTo,
+  transitionTo,
+} from "./result";
+import type { OnboardNonTerminalMachineState } from "./types";
+
+describe("onboard state result helpers", () => {
+  it("builds transition results with optional updates and metadata", () => {
+    expect(
+      transitionTo("gateway", {
+        updates: { sandboxName: "my-assistant" },
+        metadata: { reason: "test" },
+      }),
+    ).toEqual({
+      type: "transition",
+      next: "gateway",
+      transitionKind: undefined,
+      updates: { sandboxName: "my-assistant" },
+      metadata: { reason: "test" },
+    });
+  });
+
+  it("restricts transition results to non-terminal transition paths", () => {
+    expectTypeOf(transitionTo).parameter(0).toEqualTypeOf<OnboardNonTerminalMachineState>();
+    expectTypeOf<OnboardStateResultTransitionKind>().toEqualTypeOf<
+      "advance" | "retry" | "branch"
+    >();
+  });
+
+  it("labels advance, retry, and branch transitions", () => {
+    expect(advanceTo("preflight")).toMatchObject({
+      type: "transition",
+      next: "preflight",
+      transitionKind: "advance",
+    });
+    expect(retryTo("provider_selection")).toMatchObject({
+      type: "transition",
+      next: "provider_selection",
+      transitionKind: "retry",
+    });
+    expect(branchTo("agent_setup")).toMatchObject({
+      type: "transition",
+      next: "agent_setup",
+      transitionKind: "branch",
+    });
+  });
+
+  it("type-checks helper options without accepting transition kind overrides", () => {
+    expectTypeOf(advanceTo).parameter(1).toEqualTypeOf<
+      OnboardStateTransitionHelperOptions | undefined
+    >();
+
+    advanceTo("preflight", {
+      updates: { sandboxName: "my-assistant" },
+      metadata: { reason: "typed" },
+    });
+
+    // @ts-expect-error transitionKind is controlled by each specialized helper.
+    advanceTo("preflight", { transitionKind: "retry" });
+    // @ts-expect-error updates must match the persisted onboarding session shape.
+    retryTo("provider_selection", { updates: { unknown: "value" } });
+    // @ts-expect-error metadata must be an object or null.
+    branchTo("agent_setup", { metadata: "bad" });
+  });
+
+  it("builds terminal completion and failure results", () => {
+    expect(completeOnboardMachine({ sandboxName: "my-assistant" }, { verified: true })).toEqual({
+      type: "complete",
+      updates: { sandboxName: "my-assistant" },
+      metadata: { verified: true },
+    });
+    expect(failOnboardMachine("boom", { step: "gateway", metadata: { phase: 2 } })).toEqual({
+      type: "failed",
+      error: "boom",
+      step: "gateway",
+      metadata: { phase: 2 },
+    });
+  });
+});

src/lib/onboard/machine/result.ts

@@ -0,0 +1,97 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { SessionUpdates } from "../../state/onboard-session";
+import type { OnboardMachineTransitionKind, OnboardNonTerminalMachineState } from "./types";
+
+export type OnboardStateResultTransitionKind = Exclude<OnboardMachineTransitionKind, "failure">;
+
+export interface OnboardStateTransitionOptions {
+  transitionKind?: OnboardStateResultTransitionKind;
+  updates?: SessionUpdates;
+  metadata?: Record<string, unknown> | null;
+}
+
+export type OnboardStateTransitionHelperOptions = Omit<
+  OnboardStateTransitionOptions,
+  "transitionKind"
+>;
+
+export interface OnboardStateTransitionResult {
+  type: "transition";
+  next: OnboardNonTerminalMachineState;
+  transitionKind?: OnboardStateResultTransitionKind;
+  updates?: SessionUpdates;
+  metadata?: Record<string, unknown> | null;
+}
+
+export interface OnboardStateCompleteResult {
+  type: "complete";
+  updates?: SessionUpdates;
+  metadata?: Record<string, unknown> | null;
+}
+
+export interface OnboardStateFailedResult {
+  type: "failed";
+  error: string | null;
+  step?: string | null;
+  metadata?: Record<string, unknown> | null;
+}
+
+export type OnboardStateResult =
+  | OnboardStateTransitionResult
+  | OnboardStateCompleteResult
+  | OnboardStateFailedResult;
+
+export function transitionTo(
+  next: OnboardNonTerminalMachineState,
+  options: OnboardStateTransitionOptions = {},
+): OnboardStateTransitionResult {
+  return {
+    type: "transition",
+    next,
+    transitionKind: options.transitionKind,
+    updates: options.updates,
+    metadata: options.metadata,
+  };
+}
+
+export function advanceTo(
+  next: OnboardNonTerminalMachineState,
+  options: OnboardStateTransitionHelperOptions = {},
+): OnboardStateTransitionResult {
+  return transitionTo(next, { ...options, transitionKind: "advance" });
+}
+
+export function retryTo(
+  next: OnboardNonTerminalMachineState,
+  options: OnboardStateTransitionHelperOptions = {},
+): OnboardStateTransitionResult {
+  return transitionTo(next, { ...options, transitionKind: "retry" });
+}
+
+export function branchTo(
+  next: OnboardNonTerminalMachineState,
+  options: OnboardStateTransitionHelperOptions = {},
+): OnboardStateTransitionResult {
+  return transitionTo(next, { ...options, transitionKind: "branch" });
+}
+
+export function completeOnboardMachine(
+  updates: SessionUpdates = {},
+  metadata: Record<string, unknown> | null = null,
+): OnboardStateCompleteResult {
+  return { type: "complete", updates, metadata };
+}
+
+export function failOnboardMachine(
+  error: string | null,
+  options: { step?: string | null; metadata?: Record<string, unknown> | null } = {},
+): OnboardStateFailedResult {
+  return {
+    type: "failed",
+    error,
+    step: options.step,
+    metadata: options.metadata,
+  };
+}