refactor(onboard): introduce explicit state result types

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

@@ -0,0 +1,62 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, it } from "vitest";
+
+import {
+  advanceTo,
+  branchTo,
+  completeOnboardMachine,
+  failOnboardMachine,
+  retryTo,
+  transitionTo,
+} from "./result";
+
+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("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("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,89 @@
+// 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 } from "./types";
+import type { OnboardMachineState } from "./types";
+
+export interface OnboardStateTransitionResult {
+  type: "transition";
+  next: OnboardMachineState;
+  transitionKind?: OnboardMachineTransitionKind;
+  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: OnboardMachineState,
+  options: {
+    transitionKind?: OnboardMachineTransitionKind;
+    updates?: SessionUpdates;
+    metadata?: Record<string, unknown> | null;
+  } = {},
+): OnboardStateTransitionResult {
+  return {
+    type: "transition",
+    next,
+    transitionKind: options.transitionKind,
+    updates: options.updates,
+    metadata: options.metadata,
+  };
+}
+
+export function advanceTo(
+  next: OnboardMachineState,
+  options: Omit<Parameters<typeof transitionTo>[1], "transitionKind"> = {},
+): OnboardStateTransitionResult {
+  return transitionTo(next, { ...options, transitionKind: "advance" });
+}
+
+export function retryTo(
+  next: OnboardMachineState,
+  options: Omit<Parameters<typeof transitionTo>[1], "transitionKind"> = {},
+): OnboardStateTransitionResult {
+  return transitionTo(next, { ...options, transitionKind: "retry" });
+}
+
+export function branchTo(
+  next: OnboardMachineState,
+  options: Omit<Parameters<typeof transitionTo>[1], "transitionKind"> = {},
+): 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,
+  };
+}