@prismatic-io/lux 0.0.1

package/src/orchestrator/run-lifecycle.ts

@@ -0,0 +1,174 @@
+import { assign, createActor, fromPromise, setup, toPromise } from "xstate";
+import { isRunTraceLimit } from "./trace-limits.js";
+
+export type RunFailurePhase = "setup" | "running" | "collection" | "grading" | "close" | "trace";
+
+/**
+ * Side effects owned by the run lifecycle. The machine decides when each
+ * effect may run; implementations hold the filesystem and plugin details.
+ */
+export type RunLifecycleEffects<Result> = {
+  prepare: () => Promise<void>;
+  start: () => Promise<void>;
+  waitForAgent: () => Promise<void>;
+  collect: () => Promise<void>;
+  grade: () => Promise<Result>;
+  recordFailure: (phase: RunFailurePhase, error: unknown) => Promise<void>;
+  close: (primaryError: unknown | null) => Promise<void>;
+};
+
+type ErasedEffects = RunLifecycleEffects<unknown>;
+type RunLifecycleContext = {
+  effects: ErasedEffects;
+  phase: RunFailurePhase;
+  result: unknown;
+  error: unknown;
+};
+type RunLifecycleInput = { effects: ErasedEffects };
+type RunLifecycleOutcome =
+  | { status: "succeeded"; result: unknown }
+  | { status: "failed"; error: unknown };
+
+const invokeEffect = (effect: (effects: ErasedEffects) => Promise<unknown>) =>
+  fromPromise<unknown, ErasedEffects>(({ input }) => effect(input));
+
+const runLifecycleMachine = setup({
+  types: {
+    context: {} as RunLifecycleContext,
+    input: {} as RunLifecycleInput,
+    output: {} as RunLifecycleOutcome,
+  },
+  actors: {
+    prepare: invokeEffect((effects) => effects.prepare()),
+    start: invokeEffect((effects) => effects.start()),
+    waitForAgent: invokeEffect((effects) => effects.waitForAgent()),
+    collect: invokeEffect((effects) => effects.collect()),
+    grade: invokeEffect((effects) => effects.grade()),
+    recordFailure: fromPromise<
+      void,
+      { effects: ErasedEffects; phase: RunFailurePhase; error: unknown }
+    >(({ input }) => input.effects.recordFailure(input.phase, input.error)),
+    closeSuccess: invokeEffect((effects) => effects.close(null)),
+    closeFailure: fromPromise<void, { effects: ErasedEffects; error: unknown }>(({ input }) =>
+      input.effects.close(input.error),
+    ),
+  },
+  actions: {
+    captureError: assign(({ context, event }) => {
+      const error = "error" in event ? event.error : new Error("run lifecycle failed");
+      return { error, phase: isRunTraceLimit(error) ? "trace" : context.phase };
+    }),
+    captureResult: assign({
+      result: ({ event }) => ("output" in event ? event.output : undefined),
+    }),
+    enterRunning: assign({ phase: "running" }),
+    enterCollection: assign({ phase: "collection" }),
+    enterGrading: assign({ phase: "grading" }),
+    enterClose: assign({ phase: "close" }),
+  },
+}).createMachine({
+  id: "lux-run",
+  context: ({ input }) => ({
+    effects: input.effects,
+    phase: "setup",
+    result: undefined,
+    error: undefined,
+  }),
+  initial: "preparing",
+  states: {
+    preparing: {
+      invoke: {
+        src: "prepare",
+        input: ({ context }) => context.effects,
+        onDone: { target: "starting" },
+        onError: { target: "recordingFailure", actions: "captureError" },
+      },
+    },
+    starting: {
+      invoke: {
+        src: "start",
+        input: ({ context }) => context.effects,
+        onDone: { target: "running" },
+        onError: { target: "recordingFailure", actions: "captureError" },
+      },
+    },
+    recordingFailure: {
+      invoke: {
+        src: "recordFailure",
+        input: ({ context }) => ({
+          effects: context.effects,
+          phase: context.phase,
+          error: context.error,
+        }),
+        onDone: { target: "closingFailure" },
+        // Keep the original phase error as the terminal reason.
+        onError: { target: "closingFailure" },
+      },
+    },
+    running: {
+      entry: "enterRunning",
+      invoke: {
+        src: "waitForAgent",
+        input: ({ context }) => context.effects,
+        onDone: { target: "collecting" },
+        onError: { target: "recordingFailure", actions: "captureError" },
+      },
+    },
+    collecting: {
+      entry: "enterCollection",
+      invoke: {
+        src: "collect",
+        input: ({ context }) => context.effects,
+        onDone: { target: "grading" },
+        onError: { target: "recordingFailure", actions: "captureError" },
+      },
+    },
+    grading: {
+      entry: "enterGrading",
+      invoke: {
+        src: "grade",
+        input: ({ context }) => context.effects,
+        onDone: { target: "closingSuccess", actions: "captureResult" },
+        onError: { target: "recordingFailure", actions: "captureError" },
+      },
+    },
+    closingSuccess: {
+      entry: "enterClose",
+      invoke: {
+        src: "closeSuccess",
+        input: ({ context }) => context.effects,
+        onDone: { target: "succeeded" },
+        onError: { target: "recordingFailure", actions: "captureError" },
+      },
+    },
+    closingFailure: {
+      invoke: {
+        src: "closeFailure",
+        input: ({ context }) => ({ effects: context.effects, error: context.error }),
+        onDone: { target: "failed" },
+        onError: { target: "failed" },
+      },
+    },
+    succeeded: { type: "final" },
+    failed: { type: "final" },
+  },
+  output: ({ context }) => {
+    if (context.error !== undefined) {
+      return { status: "failed", error: context.error };
+    }
+    return { status: "succeeded", result: context.result };
+  },
+});
+
+export const executeRunLifecycle = async <Result>(
+  effects: RunLifecycleEffects<Result>,
+): Promise<Result> => {
+  const actor = createActor(runLifecycleMachine, { input: { effects } });
+  actor.start();
+  const outcome = await toPromise(actor);
+  if (outcome.status === "failed") throw outcome.error;
+  return outcome.result as Result;
+};
+
+// Internal export for transition-level tests.
+export { runLifecycleMachine };

package/src/orchestrator/suite-compare.ts

@@ -0,0 +1,195 @@
+import { z } from "zod";
+import {
+  loadSuiteSummary,
+  type MetricSummary,
+  MetricSummarySchema,
+  type SuiteSample,
+  type SuiteSummary,
+  summarizeNumbers,
+} from "./suite-summary.js";
+
+const ComparedOutcomeSchema = z
+  .object({
+    attempts: z.number().int().nonnegative(),
+    passRate: z.number().min(0).max(1),
+  })
+  .strict();
+
+export const SuiteCaseComparisonSchema = z
+  .object({
+    canonicalCaseId: z.string(),
+    before: ComparedOutcomeSchema.nullable(),
+    after: ComparedOutcomeSchema.nullable(),
+    passRateDelta: z.number().nullable(),
+    regressed: z.boolean(),
+    pairedMetricDeltas: z.record(z.string(), MetricSummarySchema),
+  })
+  .strict();
+export type SuiteCaseComparison = z.infer<typeof SuiteCaseComparisonSchema>;
+
+export const SuiteComparisonSchema = z
+  .object({
+    pathA: z.string(),
+    pathB: z.string(),
+    passRateTolerance: z.number().nonnegative(),
+    before: ComparedOutcomeSchema,
+    after: ComparedOutcomeSchema,
+    passRateDelta: z.number(),
+    cases: z.array(SuiteCaseComparisonSchema),
+    identityMismatches: z.array(
+      z
+        .object({
+          canonicalCaseId: z.string(),
+          repetition: z.number().int().positive(),
+          before: z.string().nullable(),
+          after: z.string().nullable(),
+        })
+        .strict(),
+    ),
+    regressions: z.number().int().nonnegative(),
+  })
+  .strict();
+export type SuiteComparison = z.infer<typeof SuiteComparisonSchema>;
+
+const samplesByCase = (summary: SuiteSummary): Map<string, SuiteSample[]> => {
+  const out = new Map<string, SuiteSample[]>();
+  for (const sample of summary.samples) {
+    const entries = out.get(sample.canonicalCaseId) ?? [];
+    entries.push(sample);
+    out.set(sample.canonicalCaseId, entries);
+  }
+  return out;
+};
+
+const pairedMetricDeltas = (
+  before: readonly SuiteSample[],
+  after: readonly SuiteSample[],
+): Record<string, MetricSummary> => {
+  const deltas = new Map<string, number[]>();
+  for (let index = 0; index < Math.min(before.length, after.length); index++) {
+    const a = before[index];
+    const b = after[index];
+    if (!a || !b) continue;
+    const names = new Set([...Object.keys(a.metrics), ...Object.keys(b.metrics)]);
+    for (const name of names) {
+      const av = a.metrics[name];
+      const bv = b.metrics[name];
+      if (av === undefined || bv === undefined) continue;
+      const values = deltas.get(name) ?? [];
+      values.push(bv - av);
+      deltas.set(name, values);
+    }
+  }
+  return Object.fromEntries(
+    [...deltas.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([name, values]) => [name, summarizeNumbers(values)]),
+  );
+};
+
+export const compareSuiteSummaries = (
+  pathA: string,
+  a: SuiteSummary,
+  pathB: string,
+  b: SuiteSummary,
+  options: { passRateTolerance?: number } = {},
+): SuiteComparison => {
+  const passRateTolerance = options.passRateTolerance ?? 0;
+  const aCases = new Map(a.cases.map((entry) => [entry.canonicalCaseId, entry]));
+  const bCases = new Map(b.cases.map((entry) => [entry.canonicalCaseId, entry]));
+  const aSamples = samplesByCase(a);
+  const bSamples = samplesByCase(b);
+  const ids = new Set([...aCases.keys(), ...bCases.keys()]);
+  const identityMismatches = [...ids].sort().flatMap((canonicalCaseId) => {
+    const before = aSamples.get(canonicalCaseId) ?? [];
+    const after = bSamples.get(canonicalCaseId) ?? [];
+    return Array.from({ length: Math.max(before.length, after.length) }, (_, index) => {
+      const beforeHash = before[index]?.identityHash ?? null;
+      const afterHash = after[index]?.identityHash ?? null;
+      return beforeHash === afterHash && beforeHash !== null
+        ? []
+        : [
+            {
+              canonicalCaseId,
+              repetition: index + 1,
+              before: beforeHash,
+              after: afterHash,
+            },
+          ];
+    }).flat();
+  });
+  const cases = [...ids].sort().map((canonicalCaseId) => {
+    const before = aCases.get(canonicalCaseId);
+    const after = bCases.get(canonicalCaseId);
+    let passRateDelta: number | null = null;
+    if (before && after) {
+      passRateDelta = after.passRate - before.passRate;
+    } else if (before) {
+      passRateDelta = -before.passRate;
+    }
+    return {
+      canonicalCaseId,
+      before: before ? { attempts: before.attempts, passRate: before.passRate } : null,
+      after: after ? { attempts: after.attempts, passRate: after.passRate } : null,
+      passRateDelta,
+      regressed:
+        Boolean(before) && (!after || after.passRate + passRateTolerance < (before?.passRate ?? 0)),
+      pairedMetricDeltas: pairedMetricDeltas(
+        aSamples.get(canonicalCaseId) ?? [],
+        bSamples.get(canonicalCaseId) ?? [],
+      ),
+    };
+  });
+  return SuiteComparisonSchema.parse({
+    pathA,
+    pathB,
+    passRateTolerance,
+    before: { attempts: a.totals.attempts, passRate: a.totals.passRate },
+    after: { attempts: b.totals.attempts, passRate: b.totals.passRate },
+    passRateDelta: b.totals.passRate - a.totals.passRate,
+    cases,
+    identityMismatches,
+    regressions: cases.filter((entry) => entry.regressed).length,
+  });
+};
+
+export const compareSuiteRuns = async (
+  pathA: string,
+  pathB: string,
+  options: { passRateTolerance?: number } = {},
+): Promise<SuiteComparison> => {
+  const [a, b] = await Promise.all([loadSuiteSummary(pathA), loadSuiteSummary(pathB)]);
+  if (!a) throw new Error(`suite summary not found at ${pathA}`);
+  if (!b) throw new Error(`suite summary not found at ${pathB}`);
+  return compareSuiteSummaries(pathA, a, pathB, b, options);
+};
+
+export const hasSuiteRegression = (comparison: SuiteComparison): boolean =>
+  comparison.regressions > 0 || comparison.identityMismatches.length > 0;
+
+const percent = (value: number): string => `${(value * 100).toFixed(1)}%`;
+
+export const formatSuiteComparisonText = (comparison: SuiteComparison): string => {
+  const lines = [
+    `A: ${comparison.pathA}`,
+    `B: ${comparison.pathB}`,
+    "",
+    "Suite:",
+    `  pass rate: ${percent(comparison.before.passRate)} → ${percent(comparison.after.passRate)} (${comparison.passRateDelta >= 0 ? "+" : ""}${percent(comparison.passRateDelta)})`,
+    `  attempts:  ${comparison.before.attempts} → ${comparison.after.attempts}`,
+    `  regressions: ${comparison.regressions}`,
+  ];
+  if (comparison.identityMismatches.length > 0) {
+    lines.push(`  identity mismatches: ${comparison.identityMismatches.length}`);
+    for (const mismatch of comparison.identityMismatches) {
+      lines.push(`    ! ${mismatch.canonicalCaseId} repetition ${mismatch.repetition}`);
+    }
+  }
+  for (const entry of comparison.cases) {
+    if (!entry.regressed) continue;
+    lines.push(
+      `    ↓ ${entry.canonicalCaseId}: ${entry.before ? percent(entry.before.passRate) : "—"} → ${entry.after ? percent(entry.after.passRate) : "missing"}`,
+    );
+  }
+  return lines.join("\n");
+};

package/src/orchestrator/suite-lifecycle.ts

@@ -0,0 +1,335 @@
+import { assign, createActor, fromCallback, fromPromise, sendTo, setup, toPromise } from "xstate";
+
+type SuiteLifecycleStatus = "succeeded" | "failed" | "aborted";
+type SuiteItemLifecycleStatus = "pending" | "running" | "completed";
+
+type SuiteLifecycleItem<Result> = {
+  status: SuiteItemLifecycleStatus;
+  result: Result | null;
+};
+
+export type SuiteLifecycleFinalization<Result> = {
+  status: SuiteLifecycleStatus;
+  items: readonly SuiteLifecycleItem<Result>[];
+  results: readonly Result[];
+  error: unknown | null;
+};
+
+export type SuiteLifecycleEffects<Result> = {
+  itemStarted: (index: number) => Promise<void>;
+  runItem: (index: number) => Promise<Result>;
+  itemCompleted: (index: number, result: Result) => Promise<void>;
+  resultFailed: (result: Result) => boolean;
+  finalize: (finalization: SuiteLifecycleFinalization<Result>) => Promise<void>;
+  recordFinalizationFailure: (finalization: SuiteLifecycleFinalization<Result>) => Promise<void>;
+};
+
+type ErasedEffects = SuiteLifecycleEffects<unknown>;
+type SuiteLifecycleInput = {
+  itemCount: number;
+  concurrency: number;
+  abortSignal?: AbortSignal;
+  effects: ErasedEffects;
+};
+type SuiteLifecycleContext = {
+  itemCount: number;
+  concurrency: number;
+  abortSignal?: AbortSignal;
+  effects: ErasedEffects;
+  items: SuiteLifecycleItem<unknown>[];
+  nextIndex: number;
+  runningCount: number;
+  aborted: boolean;
+  status: SuiteLifecycleStatus | null;
+  error: unknown | null;
+};
+type WorkerPoolInput = {
+  concurrency: number;
+  abortSignal?: AbortSignal;
+  effects: ErasedEffects;
+};
+type WorkerPoolCommand =
+  | { type: "startItem"; workerId: number; index: number }
+  | { type: "completeItem"; workerId: number; index: number; result: unknown };
+type SuiteLifecycleEvent =
+  | { type: "workerReady"; workerId: number }
+  | { type: "itemFinished"; workerId: number; index: number; result: unknown }
+  | { type: "workerFailed"; index: number; error: unknown }
+  | { type: "abort" };
+
+const workerPool = fromCallback<WorkerPoolCommand, WorkerPoolInput>(
+  ({ input, receive, sendBack }) => {
+    const executeCommand = async (event: WorkerPoolCommand): Promise<void> => {
+      try {
+        if (event.type === "startItem") {
+          await input.effects.itemStarted(event.index);
+          const result = await input.effects.runItem(event.index);
+          sendBack({
+            type: "itemFinished",
+            workerId: event.workerId,
+            index: event.index,
+            result,
+          });
+          return;
+        }
+        await input.effects.itemCompleted(event.index, event.result);
+        sendBack({ type: "workerReady", workerId: event.workerId });
+      } catch (error) {
+        sendBack({ type: "workerFailed", index: event.index, error });
+      }
+    };
+    receive((event) => void executeCommand(event));
+
+    for (let workerId = 0; workerId < input.concurrency; workerId++) {
+      sendBack({ type: "workerReady", workerId });
+    }
+
+    const abort = (): void => sendBack({ type: "abort" });
+    if (input.abortSignal?.aborted) abort();
+    else input.abortSignal?.addEventListener("abort", abort, { once: true });
+    return () => input.abortSignal?.removeEventListener("abort", abort);
+  },
+);
+
+const finalizationOf = (context: SuiteLifecycleContext): SuiteLifecycleFinalization<unknown> => ({
+  status: context.status ?? "failed",
+  items: context.items,
+  results: context.items.flatMap((item) =>
+    item.status === "completed" && item.result !== null ? [item.result] : [],
+  ),
+  error: context.error,
+});
+
+const selectedFinalStatus = (context: SuiteLifecycleContext): SuiteLifecycleStatus => {
+  if (context.error !== null) return "failed";
+  if (context.aborted || context.abortSignal?.aborted) return "aborted";
+  const resultFailed = context.items.some(
+    (item) =>
+      item.status === "completed" &&
+      item.result !== null &&
+      context.effects.resultFailed(item.result),
+  );
+  return resultFailed ? "failed" : "succeeded";
+};
+
+const suiteLifecycleMachine = setup({
+  types: {
+    context: {} as SuiteLifecycleContext,
+    input: {} as SuiteLifecycleInput,
+    events: {} as SuiteLifecycleEvent,
+    output: {} as SuiteLifecycleFinalization<unknown>,
+  },
+  actors: {
+    workerPool,
+    finalize: fromPromise<
+      void,
+      { effects: ErasedEffects; finalization: SuiteLifecycleFinalization<unknown> }
+    >(({ input }) => input.effects.finalize(input.finalization)),
+    recordFinalizationFailure: fromPromise<
+      void,
+      { effects: ErasedEffects; finalization: SuiteLifecycleFinalization<unknown> }
+    >(({ input }) => input.effects.recordFinalizationFailure(input.finalization)),
+  },
+  guards: {
+    canStartItem: ({ context }) =>
+      context.error === null &&
+      !context.aborted &&
+      !context.abortSignal?.aborted &&
+      context.nextIndex < context.itemCount,
+    readyToFinalize: ({ context }) =>
+      context.runningCount === 0 &&
+      (context.error !== null ||
+        context.aborted ||
+        context.abortSignal?.aborted ||
+        context.nextIndex >= context.itemCount),
+    failureLeavesNoRunningItems: ({ context, event }) =>
+      event.type === "workerFailed" &&
+      context.runningCount === (context.items[event.index]?.status === "running" ? 1 : 0),
+    abortLeavesNoRunningItems: ({ context }) => context.runningCount === 0,
+    finalizedAsAborted: ({ context }) => context.status === "aborted",
+    finalizedAsFailed: ({ context }) => context.status === "failed",
+  },
+  actions: {
+    dispatchNextItem: sendTo("workers", ({ context, event }) => {
+      if (event.type !== "workerReady") {
+        throw new Error("suite worker dispatch requires an available worker");
+      }
+      return {
+        type: "startItem",
+        workerId: event.workerId,
+        index: context.nextIndex,
+      };
+    }),
+    markNextItemRunning: assign(({ context }) => ({
+      items: context.items.map((item, index) =>
+        index === context.nextIndex ? { ...item, status: "running" as const } : item,
+      ),
+      nextIndex: context.nextIndex + 1,
+      runningCount: context.runningCount + 1,
+    })),
+    markItemCompleted: assign(({ context, event }) => {
+      if (event.type !== "itemFinished") return {};
+      return {
+        items: context.items.map((item, index) =>
+          index === event.index ? { status: "completed" as const, result: event.result } : item,
+        ),
+        runningCount: context.runningCount - 1,
+      };
+    }),
+    persistCompletedItem: sendTo("workers", ({ event }) => {
+      if (event.type !== "itemFinished") {
+        throw new Error("suite item completion requires a finished item");
+      }
+      return {
+        type: "completeItem",
+        workerId: event.workerId,
+        index: event.index,
+        result: event.result,
+      };
+    }),
+    rememberAbort: assign({ aborted: true }),
+    selectFinalStatus: assign(({ context }) => ({
+      aborted: context.aborted || Boolean(context.abortSignal?.aborted),
+      status: selectedFinalStatus(context),
+    })),
+    rememberFailure: assign(({ context, event }) => {
+      if (event.type !== "workerFailed") return {};
+      const wasRunning = context.items[event.index]?.status === "running";
+      return {
+        error: context.error ?? event.error,
+        runningCount: wasRunning ? context.runningCount - 1 : context.runningCount,
+      };
+    }),
+    rememberFinalizationFailure: assign(({ event }) => ({
+      error: "error" in event ? event.error : new Error("suite finalization failed"),
+      status: "failed" as const,
+    })),
+  },
+}).createMachine({
+  id: "lux-suite",
+  context: ({ input }) => ({
+    itemCount: input.itemCount,
+    concurrency: input.concurrency,
+    ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),
+    effects: input.effects,
+    items: Array.from({ length: input.itemCount }, () => ({
+      status: "pending" as const,
+      result: null,
+    })),
+    nextIndex: 0,
+    runningCount: 0,
+    aborted: input.abortSignal?.aborted ?? false,
+    status: null,
+    error: null,
+  }),
+  initial: "running",
+  states: {
+    running: {
+      invoke: {
+        id: "workers",
+        src: "workerPool",
+        input: ({ context }) => ({
+          concurrency: context.concurrency,
+          ...(context.abortSignal ? { abortSignal: context.abortSignal } : {}),
+          effects: context.effects,
+        }),
+      },
+      on: {
+        workerReady: [
+          {
+            guard: "readyToFinalize",
+            target: "finalizing",
+            actions: "selectFinalStatus",
+          },
+          {
+            guard: "canStartItem",
+            actions: ["dispatchNextItem", "markNextItemRunning"],
+          },
+        ],
+        itemFinished: {
+          actions: ["markItemCompleted", "persistCompletedItem"],
+        },
+        workerFailed: [
+          {
+            guard: "failureLeavesNoRunningItems",
+            target: "finalizing",
+            actions: ["rememberFailure", "selectFinalStatus"],
+          },
+          { actions: "rememberFailure" },
+        ],
+        abort: [
+          {
+            guard: "abortLeavesNoRunningItems",
+            target: "finalizing",
+            actions: ["rememberAbort", "selectFinalStatus"],
+          },
+          { actions: "rememberAbort" },
+        ],
+      },
+    },
+    finalizing: {
+      invoke: {
+        src: "finalize",
+        input: ({ context }) => ({
+          effects: context.effects,
+          finalization: finalizationOf(context),
+        }),
+        onDone: [
+          { guard: "finalizedAsAborted", target: "aborted" },
+          { guard: "finalizedAsFailed", target: "failed" },
+          { target: "succeeded" },
+        ],
+        onError: {
+          target: "recordingFinalizationFailure",
+          actions: "rememberFinalizationFailure",
+        },
+      },
+    },
+    recordingFinalizationFailure: {
+      invoke: {
+        src: "recordFinalizationFailure",
+        input: ({ context }) => ({
+          effects: context.effects,
+          finalization: finalizationOf(context),
+        }),
+        onDone: { target: "failed" },
+        onError: { target: "failed" },
+      },
+    },
+    succeeded: { type: "final" },
+    failed: { type: "final" },
+    aborted: { type: "final" },
+  },
+  output: ({ context }) => finalizationOf(context),
+});
+
+export const validateSuiteConcurrency = (concurrency: number | undefined): number => {
+  const value = concurrency ?? 1;
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+    throw new Error("suite concurrency must be a positive finite integer");
+  }
+  return value;
+};
+
+export const executeSuiteLifecycle = async <Result>(options: {
+  itemCount: number;
+  concurrency: number;
+  abortSignal?: AbortSignal;
+  effects: SuiteLifecycleEffects<Result>;
+}): Promise<SuiteLifecycleFinalization<Result>> => {
+  const actor = createActor(suiteLifecycleMachine, {
+    input: {
+      itemCount: options.itemCount,
+      concurrency: options.concurrency,
+      ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
+      effects: options.effects as ErasedEffects,
+    },
+  });
+  actor.start();
+  const outcome = await toPromise(actor);
+  if (outcome.error !== null) throw outcome.error;
+  return outcome as SuiteLifecycleFinalization<Result>;
+};
+
+// Internal export for transition-level tests.
+export { suiteLifecycleMachine };