@fragno-dev/db 0.2.1 → 0.3.0

package/src/query/unit-of-work/execute-unit-of-work.ts

@@ -1,331 +1,481 @@
 import type { AnySchema } from "../../schema/create";
 import type { TypedUnitOfWork, IUnitOfWork } from "./unit-of-work";
 import type { HooksMap } from "../../hooks/hooks";
-import { NoRetryPolicy, ExponentialBackoffRetryPolicy, type RetryPolicy } from "./retry-policy";
-import type { FragnoId } from "../../schema/create";
+import { ExponentialBackoffRetryPolicy, NoRetryPolicy, type RetryPolicy } from "./retry-policy";
 
 /**
- * Error thrown when a Unit of Work execution fails due to optimistic concurrency conflict.
- * This error triggers automatic retry behavior in executeRestrictedUnitOfWork.
+ * Symbol to identify TxResult objects
  */
-export class ConcurrencyConflictError extends Error {
-  constructor(message = "Optimistic concurrency conflict detected") {
-    super(message);
-    this.name = "ConcurrencyConflictError";
-  }
+const TX_RESULT_BRAND = Symbol("TxResult");
+
+/**
+ * Check if a value is a TxResult
+ */
+export function isTxResult(value: unknown): value is TxResult<unknown> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    TX_RESULT_BRAND in value &&
+    (value as Record<symbol, boolean>)[TX_RESULT_BRAND] === true
+  );
 }
 
 /**
- * Type utility that unwraps promises 1 level deep in objects, arrays, or direct promises
- * Handles tuples, arrays, objects, and direct promises
+ * Extract the retrieve success result type from a TxResult.
+ * If the TxResult has retrieveSuccess, returns its return type.
+ * Otherwise returns the raw retrieve results type.
+ * Handles undefined (for optional service patterns like optionalService?.method()).
  */
-export type AwaitedPromisesInObject<T> =
-  // First check if it's a Promise
-  T extends Promise<infer U>
-    ? Awaited<U>
-    : // Check for arrays with known length (tuples) - preserves tuple structure
-      T extends readonly [unknown, ...unknown[]]
-      ? { [K in keyof T]: AwaitedPromisesInObject<T[K]> }
-      : T extends [unknown, ...unknown[]]
-        ? { [K in keyof T]: AwaitedPromisesInObject<T[K]> }
-        : // Check for regular arrays (unknown length)
-          T extends (infer U)[]
-          ? Awaited<U>[]
-          : T extends readonly (infer U)[]
-            ? readonly Awaited<U>[]
-            : // Check for objects
-              T extends Record<string, unknown>
-              ? {
-                  [K in keyof T]: T[K] extends Promise<infer U> ? Awaited<U> : T[K];
-                }
-              : // Otherwise return as-is
-                T;
+export type ExtractTxRetrieveSuccessResult<T> = T extends undefined
+  ? undefined
+  : T extends TxResult<unknown, infer R>
+    ? R
+    : never;
 
 /**
- * Await promises in an object 1 level deep
+ * Extract the final result type from a TxResult.
+ * Handles undefined (for optional service patterns like optionalService?.method()).
  */
-async function awaitPromisesInObject<T>(obj: T): Promise<AwaitedPromisesInObject<T>> {
-  if (obj === null || obj === undefined) {
-    return obj as AwaitedPromisesInObject<T>;
-  }
+export type ExtractTxFinalResult<T> = T extends undefined
+  ? undefined
+  : T extends TxResult<infer R, infer _>
+    ? R
+    : Awaited<T>;
 
-  if (typeof obj !== "object") {
-    return obj as AwaitedPromisesInObject<T>;
-  }
+/**
+ * Map over service calls array to extract retrieve success results from each service call.
+ * Preserves tuple structure while extracting the retrieve success result type from each element.
+ */
+export type ExtractServiceRetrieveResults<T extends readonly unknown[]> = {
+  [K in keyof T]: ExtractTxRetrieveSuccessResult<T[K]>;
+};
 
-  // Check if it's a Promise
-  if (obj instanceof Promise) {
-    return (await obj) as AwaitedPromisesInObject<T>;
-  }
+/**
+ * Map over service calls array to extract final results from each service call.
+ * Preserves tuple structure while extracting the final result type from each element.
+ */
+export type ExtractServiceFinalResults<T extends readonly unknown[]> = {
+  [K in keyof T]: ExtractTxFinalResult<T[K]>;
+};
 
-  // Check if it's an array
-  if (Array.isArray(obj)) {
-    const awaited = await Promise.all(
-      obj.map((item) => (item instanceof Promise ? item : Promise.resolve(item))),
-    );
-    return awaited as AwaitedPromisesInObject<T>;
-  }
+/**
+ * Context passed to mutate callback for service methods
+ */
+export interface ServiceTxMutateContext<
+  TSchema extends AnySchema,
+  TRetrieveSuccessResult,
+  TServiceRetrieveResults extends readonly unknown[],
+  THooks extends HooksMap,
+> {
+  /** Unit of work for scheduling mutations */
+  uow: TypedUnitOfWork<TSchema, [], unknown, THooks>;
+  /** Result from retrieveSuccess callback (or raw retrieve results if no retrieveSuccess) */
+  retrieveResult: TRetrieveSuccessResult;
+  /** Array of retrieve success results from service calls (intermediate results, not final) */
+  serviceIntermediateResult: TServiceRetrieveResults;
+}
 
-  // It's a plain object - await promises in each property
-  const result = {} as T;
-  const entries = Object.entries(obj as Record<string, unknown>);
-  const awaitedEntries = await Promise.all(
-    entries.map(async ([key, value]) => {
-      const awaitedValue = value instanceof Promise ? await value : value;
-      return [key, awaitedValue] as const;
-    }),
-  );
+/**
+ * Context passed to handler-level callbacks
+ */
+export interface HandlerTxContext<THooks extends HooksMap> {
+  /** Get a typed Unit of Work for the given schema */
+  forSchema: <S extends AnySchema, H extends HooksMap = THooks>(
+    schema: S,
+    hooks?: H,
+  ) => TypedUnitOfWork<S, [], unknown, H>;
+  /** Unique key for this transaction attempt (for idempotency/deduplication) */
+  idempotencyKey: string;
+  /** Current attempt number (0-based) */
+  currentAttempt: number;
+}
 
-  for (const [key, value] of awaitedEntries) {
-    (result as Record<string, unknown>)[key] = value;
-  }
+/**
+ * Context passed to handler mutate callback
+ */
+export interface HandlerTxMutateContext<
+  TRetrieveSuccessResult,
+  TServiceRetrieveResults extends readonly unknown[],
+  THooks extends HooksMap,
+> extends HandlerTxContext<THooks> {
+  /** Result from retrieveSuccess callback (or raw retrieve results if no retrieveSuccess) */
+  retrieveResult: TRetrieveSuccessResult;
+  /** Array of retrieve success results from service calls (intermediate results, not final) */
+  serviceIntermediateResult: TServiceRetrieveResults;
+}
 
-  return result as AwaitedPromisesInObject<T>;
+/**
+ * Context passed to success callback when mutate IS provided
+ */
+export interface TxSuccessContextWithMutate<
+  TRetrieveSuccessResult,
+  TMutateResult,
+  TServiceFinalResults extends readonly unknown[],
+  TServiceRetrieveResults extends readonly unknown[],
+> {
+  /** Result from retrieveSuccess callback (or raw retrieve results if no retrieveSuccess) */
+  retrieveResult: TRetrieveSuccessResult;
+  /** Result from mutate callback */
+  mutateResult: TMutateResult;
+  /** Array of final results from service calls */
+  serviceResult: TServiceFinalResults;
+  /** Array of retrieve success results from service calls (same as what mutate receives) */
+  serviceIntermediateResult: TServiceRetrieveResults;
 }
 
 /**
- * Result of executing a Unit of Work with retry support
- * Promises in mutationResult are unwrapped 1 level deep
+ * Context passed to success callback when mutate is NOT provided
  */
-export type ExecuteUnitOfWorkResult<TRetrievalResults, TMutationResult> =
-  | {
-      success: true;
-      results: TRetrievalResults;
-      mutationResult: AwaitedPromisesInObject<TMutationResult>;
-      createdIds: FragnoId[];
-      nonce: string;
-    }
-  | {
-      success: false;
-      reason: "conflict";
-    }
-  | {
-      success: false;
-      reason: "aborted";
-    }
-  | {
-      success: false;
-      reason: "error";
-      error: unknown;
-    };
+export interface TxSuccessContextWithoutMutate<
+  TRetrieveSuccessResult,
+  TServiceFinalResults extends readonly unknown[],
+  TServiceRetrieveResults extends readonly unknown[],
+> {
+  /** Result from retrieveSuccess callback (or raw retrieve results if no retrieveSuccess) */
+  retrieveResult: TRetrieveSuccessResult;
+  /** No mutate callback was provided */
+  mutateResult: undefined;
+  /** Array of final results from service calls */
+  serviceResult: TServiceFinalResults;
+  /** Array of retrieve success results from service calls (same as what mutate receives) */
+  serviceIntermediateResult: TServiceRetrieveResults;
+}
+
+/**
+ * Context passed to success callback.
+ * Union of TxSuccessContextWithMutate and TxSuccessContextWithoutMutate to handle
+ * both cases in a single callback signature.
+ */
+export type TxSuccessContext<
+  TRetrieveSuccessResult,
+  TMutateResult,
+  TServiceFinalResults extends readonly unknown[],
+  TServiceRetrieveResults extends readonly unknown[] = readonly unknown[],
+> =
+  | TxSuccessContextWithMutate<
+      TRetrieveSuccessResult,
+      TMutateResult,
+      TServiceFinalResults,
+      TServiceRetrieveResults
+    >
+  | TxSuccessContextWithoutMutate<
+      TRetrieveSuccessResult,
+      TServiceFinalResults,
+      TServiceRetrieveResults
+    >;
 
 /**
- * Callbacks for executing a Unit of Work
+ * Callbacks for service-level TxResult.
+ *
+ * Return type priority:
+ * 1. If success exists: ReturnType<success>
+ * 2. Else if mutate exists: ReturnType<mutate>
+ * 3. Else if retrieveSuccess exists: ReturnType<retrieveSuccess>
+ * 4. Else if retrieve exists: TRetrieveResults
+ * 5. Else: serviceResult array type
  */
-export interface ExecuteUnitOfWorkCallbacks<
+export interface ServiceTxCallbacks<
   TSchema extends AnySchema,
-  TRetrievalResults extends unknown[],
-  TMutationResult,
-  TRawInput,
+  TRetrieveResults extends unknown[],
+  TRetrieveSuccessResult,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TServiceCalls extends readonly (TxResult<any, any> | undefined)[],
+  TMutateResult,
+  TSuccessResult,
+  THooks extends HooksMap,
 > {
   /**
-   * Retrieval phase callback - adds retrieval operations to the UOW
+   * Service calls - other TxResults to execute first.
+   */
+  serviceCalls?: () => TServiceCalls;
+
+  /**
+   * Retrieval phase callback - schedules retrieval operations.
    */
   retrieve?: (
-    uow: TypedUnitOfWork<TSchema, [], TRawInput>,
-  ) => TypedUnitOfWork<TSchema, TRetrievalResults, TRawInput>;
+    uow: TypedUnitOfWork<TSchema, [], unknown, THooks>,
+  ) => TypedUnitOfWork<TSchema, TRetrieveResults, unknown, THooks>;
 
   /**
-   * Mutation phase callback - receives UOW and retrieval results, adds mutation operations
+   * Transform retrieve results before passing to mutate.
+   */
+  retrieveSuccess?: (
+    retrieveResult: TRetrieveResults,
+    serviceResult: ExtractServiceRetrieveResults<TServiceCalls>,
+  ) => TRetrieveSuccessResult;
+
+  /**
+   * Mutation phase callback - schedules mutations based on retrieve results.
    */
   mutate?: (
-    uow: TypedUnitOfWork<TSchema, TRetrievalResults, TRawInput>,
-    results: TRetrievalResults,
-  ) => TMutationResult | Promise<TMutationResult>;
+    ctx: ServiceTxMutateContext<
+      TSchema,
+      TRetrieveSuccessResult,
+      ExtractServiceRetrieveResults<TServiceCalls>,
+      THooks
+    >,
+  ) => TMutateResult;
 
   /**
-   * Success callback - invoked after successful execution
-   * Promises in mutationResult are already unwrapped 1 level deep
+   * Success callback - final transformation after mutations complete.
    */
-  onSuccess?: (result: {
-    results: TRetrievalResults;
-    mutationResult: AwaitedPromisesInObject<TMutationResult>;
-    createdIds: FragnoId[];
-    nonce: string;
-  }) => void | Promise<void>;
+  success?: (
+    ctx: TxSuccessContext<
+      TRetrieveSuccessResult,
+      TMutateResult,
+      ExtractServiceFinalResults<TServiceCalls>,
+      ExtractServiceRetrieveResults<TServiceCalls>
+    >,
+  ) => TSuccessResult;
 }
 
 /**
- * Options for executing a Unit of Work
+ * Callbacks for handler-level executeTx.
+ * Uses context-based callbacks that provide forSchema() method.
  */
-export interface ExecuteUnitOfWorkOptions<TSchema extends AnySchema, TRawInput> {
+export interface HandlerTxCallbacks<
+  TRetrieveResults extends unknown[],
+  TRetrieveSuccessResult,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TServiceCalls extends readonly (TxResult<any, any> | undefined)[],
+  TMutateResult,
+  TSuccessResult,
+  THooks extends HooksMap,
+> {
   /**
-   * Factory function that creates or resets a UOW instance for each attempt
+   * Service calls - other TxResults to execute first.
    */
-  createUnitOfWork: () => TypedUnitOfWork<TSchema, [], TRawInput>;
+  serviceCalls?: () => TServiceCalls;
 
   /**
-   * Retry policy for handling optimistic concurrency conflicts
+   * Retrieval phase callback - schedules retrieval operations using context.forSchema().
+   * Return a TypedUnitOfWork to get typed results, or void for no retrieval.
    */
-  retryPolicy?: RetryPolicy;
+  retrieve?: (
+    context: HandlerTxContext<THooks>,
+  ) => TypedUnitOfWork<AnySchema, TRetrieveResults, unknown, HooksMap> | void;
 
   /**
-   * Abort signal to cancel execution
+   * Transform retrieve results before passing to mutate.
    */
-  signal?: AbortSignal;
+  retrieveSuccess?: (
+    retrieveResult: TRetrieveResults,
+    serviceResult: ExtractServiceRetrieveResults<TServiceCalls>,
+  ) => TRetrieveSuccessResult;
+
+  /**
+   * Mutation phase callback - schedules mutations based on retrieve results.
+   */
+  mutate?: (
+    ctx: HandlerTxMutateContext<
+      TRetrieveSuccessResult,
+      ExtractServiceRetrieveResults<TServiceCalls>,
+      THooks
+    >,
+  ) => TMutateResult;
+
+  /**
+   * Success callback - final transformation after mutations complete.
+   */
+  success?: (
+    ctx: TxSuccessContext<
+      TRetrieveSuccessResult,
+      TMutateResult,
+      ExtractServiceFinalResults<TServiceCalls>,
+      ExtractServiceRetrieveResults<TServiceCalls>
+    >,
+  ) => TSuccessResult;
 }
 
 /**
- * Create a bound version of executeUnitOfWork with a pre-configured UOW factory.
- * This is useful for handler contexts where the factory is already known.
- *
- * @param createUnitOfWork - Factory function that creates a fresh UOW instance
- * @returns A bound executeUnitOfWork function that doesn't require the factory parameter
- *
- * @example
- * ```ts
- * const boundExecute = createExecuteUnitOfWork(() => db.createUnitOfWork());
- * const result = await boundExecute({
- *   retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
- *   mutate: (uow, [users]) => {
- *     uow.update("users", users[0].id, (b) => b.set({ balance: newBalance }));
- *   }
- * });
- * ```
+ * Internal structure storing TxResult callbacks and state.
  */
-export function createExecuteUnitOfWork<TSchema extends AnySchema, TRawInput>(
-  createUnitOfWork: () => TypedUnitOfWork<TSchema, [], TRawInput>,
-) {
-  return async function <TRetrievalResults extends unknown[], TMutationResult = void>(
-    callbacks: ExecuteUnitOfWorkCallbacks<TSchema, TRetrievalResults, TMutationResult, TRawInput>,
-    options?: Omit<ExecuteUnitOfWorkOptions<TSchema, TRawInput>, "createUnitOfWork">,
-  ): Promise<ExecuteUnitOfWorkResult<TRetrievalResults, TMutationResult>> {
-    return executeUnitOfWork(callbacks, { ...options, createUnitOfWork });
-  };
+interface TxResultInternal<
+  TSchema extends AnySchema,
+  TRetrieveResults extends unknown[],
+  TRetrieveSuccessResult,
+  TServiceCalls extends readonly (TxResult<unknown> | undefined)[],
+  TMutateResult,
+  TSuccessResult,
+  THooks extends HooksMap,
+> {
+  schema: TSchema | undefined;
+  callbacks: ServiceTxCallbacks<
+    TSchema,
+    TRetrieveResults,
+    TRetrieveSuccessResult,
+    TServiceCalls,
+    TMutateResult,
+    TSuccessResult,
+    THooks
+  >;
+  /** The typed UOW created during retrieve callback */
+  typedUow: TypedUnitOfWork<TSchema, TRetrieveResults, unknown, THooks> | undefined;
+  /** The restricted UOW for signaling (used when typedUow is undefined) */
+  restrictedUow: IUnitOfWork;
+  /** Promise that resolves when retrieve phase is complete */
+  retrievePhase: Promise<TRetrieveResults>;
+  /** Resolve function for retrievePhase */
+  resolveRetrievePhase: (results: TRetrieveResults) => void;
+  /** Reject function for retrievePhase */
+  rejectRetrievePhase: (error: unknown) => void;
+  /** Computed retrieve success result (set after retrieveSuccess runs) */
+  retrieveSuccessResult: TRetrieveSuccessResult | undefined;
+  /** Computed mutate result (set after mutate runs) */
+  mutateResult: TMutateResult | undefined;
+  /** Computed final result (set after success runs or defaults) */
+  finalResult: TSuccessResult | undefined;
+  /** Service calls resolved */
+  serviceCalls: TServiceCalls | undefined;
 }
 
 /**
- * Execute a Unit of Work with automatic retry support for optimistic concurrency conflicts.
- *
- * This function orchestrates the two-phase execution (retrieval + mutation) with retry logic.
- * It creates fresh UOW instances for each attempt.
+ * TxResult represents a transaction definition (not yet executed).
+ * It describes the work to be done: retrieve operations, transformations, and mutations.
  *
- * @param callbacks - Object containing retrieve, mutate, and onSuccess callbacks
- * @param options - Configuration including UOW factory, retry policy, and abort signal
- * @returns Promise resolving to the execution result
+ * Service methods return TxResult objects, and the handler's executeTx function
+ * orchestrates their execution with retry support.
  *
- * @example
- * ```ts
- * const result = await executeUnitOfWork(
- *   {
- *     retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
- *     mutate: (uow, [users]) => {
- *       const user = users[0];
- *       uow.update("users", user.id, (b) => b.set({ balance: newBalance }));
- *     },
- *     onSuccess: async ({ results, mutationResult }) => {
- *       console.log("Update successful!");
- *     }
- *   },
- *   {
- *     createUnitOfWork: () => queryEngine.createUnitOfWork(),
- *     retryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 3 })
- *   }
- * );
- * ```
+ * @template TResult - The final result type (determined by return type priority)
+ * @template TRetrieveSuccessResult - The retrieve success result type (what serviceCalls receive).
+ *   Defaults to TResult, meaning serviceCalls receive the same type as the final result.
  */
-export async function executeUnitOfWork<
+export interface TxResult<TResult, TRetrieveSuccessResult = TResult> {
+  /** Brand to identify TxResult objects */
+  readonly [TX_RESULT_BRAND]: true;
+
+  /** Internal structure - do not access directly */
+  readonly _internal: TxResultInternal<
+    AnySchema,
+    unknown[],
+    TRetrieveSuccessResult,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    readonly TxResult<any, any>[],
+    unknown,
+    TResult,
+    HooksMap
+  >;
+}
+
+/**
+ * Create a TxResult for service context.
+ * Schedules retrieve operations on the baseUow and returns a TxResult with callbacks stored.
+ * @internal Used by ServiceTxBuilder.build()
+ */
+function createServiceTx<
   TSchema extends AnySchema,
-  TRetrievalResults extends unknown[],
-  TMutationResult = void,
-  TRawInput = unknown,
+  TRetrieveResults extends unknown[],
+  TRetrieveSuccessResult,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TServiceCalls extends readonly (TxResult<any, any> | undefined)[],
+  TMutateResult,
+  TSuccessResult,
+  THooks extends HooksMap = {},
 >(
-  callbacks: ExecuteUnitOfWorkCallbacks<TSchema, TRetrievalResults, TMutationResult, TRawInput>,
-  options: ExecuteUnitOfWorkOptions<TSchema, TRawInput>,
-): Promise<ExecuteUnitOfWorkResult<TRetrievalResults, TMutationResult>> {
-  // Validate that at least one of retrieve or mutate is provided
-  if (!callbacks.retrieve && !callbacks.mutate) {
-    throw new Error("At least one of 'retrieve' or 'mutate' callbacks must be provided");
+  schema: TSchema | undefined,
+  callbacks: ServiceTxCallbacks<
+    TSchema,
+    TRetrieveResults,
+    TRetrieveSuccessResult,
+    TServiceCalls,
+    TMutateResult,
+    TSuccessResult,
+    THooks
+  >,
+  baseUow: IUnitOfWork,
+): TxResult<unknown, unknown> {
+  // Create deferred promise for retrieve phase
+  const {
+    promise: retrievePhase,
+    resolve: resolveRetrievePhase,
+    reject: rejectRetrievePhase,
+  } = Promise.withResolvers<TRetrieveResults>();
+
+  // Get a restricted view that signals readiness
+  const restrictedUow = baseUow.restrict({ readyFor: "none" });
+
+  // Call serviceCalls factory if provided - this invokes other services which schedule their operations
+  let serviceCalls: TServiceCalls | undefined;
+  try {
+    if (callbacks.serviceCalls) {
+      serviceCalls = callbacks.serviceCalls();
+    }
+  } catch (error) {
+    restrictedUow.signalReadyForRetrieval();
+    restrictedUow.signalReadyForMutation();
+    retrievePhase.catch(() => {});
+    rejectRetrievePhase(error);
+    throw error;
   }
-
-  const retryPolicy = options.retryPolicy ?? new NoRetryPolicy();
-  const signal = options.signal;
-  let attempt = 0;
-
-  while (true) {
-    // Check if aborted before starting attempt
-    if (signal?.aborted) {
-      return { success: false, reason: "aborted" };
+  let typedUow: TypedUnitOfWork<TSchema, TRetrieveResults, unknown, THooks> | undefined;
+  try {
+    if (schema && callbacks.retrieve) {
+      const emptyUow = restrictedUow.forSchema<TSchema, THooks>(schema);
+      typedUow = callbacks.retrieve(emptyUow);
     }
+  } catch (error) {
+    restrictedUow.signalReadyForRetrieval();
+    restrictedUow.signalReadyForMutation();
+    retrievePhase.catch(() => {});
+    rejectRetrievePhase(error);
+    throw error;
+  }
+  restrictedUow.signalReadyForRetrieval();
 
-    try {
-      // Create a fresh UOW for this attempt
-      const uow = options.createUnitOfWork();
-
-      // Apply retrieval phase if provided
-      let retrievalUow: TypedUnitOfWork<TSchema, TRetrievalResults, TRawInput>;
-      if (callbacks.retrieve) {
-        retrievalUow = callbacks.retrieve(uow);
-      } else {
-        // No retrieval phase, use empty UOW with type cast
-        // This is safe because when there's no retrieve, TRetrievalResults should be []
-        retrievalUow = uow as unknown as TypedUnitOfWork<TSchema, TRetrievalResults, TRawInput>;
-      }
-
-      // Execute retrieval phase
-      const results = (await retrievalUow.executeRetrieve()) as TRetrievalResults;
-
-      // Invoke mutation phase callback if provided
-      let mutationResult: TMutationResult;
-      if (callbacks.mutate) {
-        mutationResult = await callbacks.mutate(retrievalUow, results);
-      } else {
-        mutationResult = undefined as TMutationResult;
-      }
-
-      // Execute mutation phase
-      const { success } = await retrievalUow.executeMutations();
-
-      if (success) {
-        // Success! Get created IDs and nonce, then invoke onSuccess if provided
-        const createdIds = retrievalUow.getCreatedIds();
-        const nonce = retrievalUow.nonce;
-
-        // Await promises in mutationResult (1 level deep)
-        const awaitedMutationResult = await awaitPromisesInObject(mutationResult);
-
-        if (callbacks.onSuccess) {
-          await callbacks.onSuccess({
-            results,
-            mutationResult: awaitedMutationResult,
-            createdIds,
-            nonce,
-          });
-        }
-
-        return {
-          success: true,
-          results,
-          mutationResult: awaitedMutationResult,
-          createdIds,
-          nonce,
-        };
-      }
-
-      // Failed - check if we should retry
-      // attempt represents the number of attempts completed so far
-      if (!retryPolicy.shouldRetry(attempt, undefined, signal)) {
-        // No more retries
-        return { success: false, reason: "conflict" };
-      }
+  // Set up the retrieve phase promise to resolve when the handler executes retrieve
+  if (typedUow) {
+    typedUow.retrievalPhase.then(
+      (results) => resolveRetrievePhase(results as TRetrieveResults),
+      (error) => rejectRetrievePhase(error),
+    );
+  } else if (!callbacks.retrieve) {
+    // No retrieve callback - resolve immediately with empty array
+    resolveRetrievePhase([] as unknown as TRetrieveResults);
+  }
 
-      const delayMs = retryPolicy.getDelayMs(attempt);
-      if (delayMs > 0) {
-        await new Promise((resolve) => setTimeout(resolve, delayMs));
-      }
+  const internal: TxResultInternal<
+    TSchema,
+    TRetrieveResults,
+    TRetrieveSuccessResult,
+    TServiceCalls,
+    TMutateResult,
+    TSuccessResult,
+    THooks
+  > = {
+    schema,
+    callbacks,
+    typedUow,
+    restrictedUow,
+    retrievePhase,
+    resolveRetrievePhase,
+    rejectRetrievePhase,
+    retrieveSuccessResult: undefined,
+    mutateResult: undefined,
+    finalResult: undefined,
+    serviceCalls,
+  };
 
-      attempt++;
-    } catch (error) {
-      // An error was thrown during execution
-      return { success: false, reason: "error", error };
-    }
-  }
+  return {
+    [TX_RESULT_BRAND]: true as const,
+    // Cast through unknown to avoid type incompatibility issues with generic constraints
+    _internal: internal as unknown as TxResultInternal<
+      AnySchema,
+      unknown[],
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      any,
+      readonly TxResult<unknown>[],
+      unknown,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      any,
+      HooksMap
+    >,
+  };
 }
 
 /**
- * Options for executing a Unit of Work with restricted access
+ * Options for executing transactions
  */
-export interface ExecuteRestrictedUnitOfWorkOptions {
+export interface ExecuteTxOptions {
   /**
    * Factory function that creates or resets a UOW instance for each attempt
    */
@@ -351,272 +501,396 @@ export interface ExecuteRestrictedUnitOfWorkOptions {
    * Callback invoked after successful mutation phase.
    * Use this for post-mutation processing like hook execution.
    */
-  onSuccess?: (uow: IUnitOfWork) => Promise<void>;
+  onAfterMutate?: (uow: IUnitOfWork) => Promise<void>;
 }
 
 /**
- * Context provided to handler tx callbacks
+ * Recursively collect all TxResults from a service call tree.
+ * Returns them in a flat array in dependency order (serviceCalls before their dependents).
+ * Skips undefined values (which can occur with optional service patterns like
+ * optionalService?.method()).
  */
-export interface TxPhaseContext<THooks extends HooksMap> {
-  /**
-   * Get a typed Unit of Work for the given schema
-   */
-  forSchema: <S extends AnySchema, H extends HooksMap = THooks>(
-    schema: S,
-    hooks?: H,
-  ) => TypedUnitOfWork<S, [], unknown, H>;
+function collectAllTxResults(
+  txResults: readonly (TxResult<unknown> | undefined)[],
+): TxResult<unknown>[] {
+  const collected: TxResult<unknown>[] = [];
+  const seen = new Set<TxResult<unknown>>();
+
+  function collect(txResult: TxResult<unknown> | undefined) {
+    if (txResult === undefined) {
+      return;
+    }
+
+    if (seen.has(txResult)) {
+      return;
+    }
+    seen.add(txResult);
+
+    // First collect serviceCalls (so they come before this TxResult)
+    const serviceCalls = txResult._internal.serviceCalls;
+    if (serviceCalls) {
+      for (const serviceCall of serviceCalls) {
+        collect(serviceCall);
+      }
+    }
+
+    collected.push(txResult);
+  }
+
+  for (const txResult of txResults) {
+    collect(txResult);
+  }
+
+  return collected;
 }
 
 /**
- * Handler callbacks for tx() - SYNCHRONOUS ONLY (no Promise return allowed)
- * This prevents accidentally awaiting services in the wrong place
+ * Execute a single TxResult's callbacks after retrieve phase completes.
+ * This processes retrieveSuccess, mutate, and success callbacks in order.
  */
-export interface HandlerTxCallbacks<TRetrieveResult, TMutationResult, THooks extends HooksMap> {
-  /**
-   * Retrieval phase callback - schedules retrievals and optionally calls services
-   * Must be synchronous - cannot await promises
-   */
-  retrieve?: (context: TxPhaseContext<THooks>) => TRetrieveResult;
-  /**
-   * Mutation phase callback - receives retrieve result, schedules mutations
-   * Must be synchronous - cannot await promises (but may return a promise to be awaited)
-   */
-  mutate?: (context: TxPhaseContext<THooks>, retrieveResult: TRetrieveResult) => TMutationResult;
+async function processTxResultAfterRetrieve<T>(
+  txResult: TxResult<T>,
+  baseUow: IUnitOfWork,
+): Promise<void> {
+  const internal = txResult._internal;
+  const callbacks = internal.callbacks;
+
+  // Wait for retrieve phase to complete
+  const retrieveResults = await internal.retrievePhase;
+
+  // Collect serviceCalls' retrieve success results (or mutate results if no retrieve was provided)
+  // When a serviceCall has no retrieve/retrieveSuccess but has mutate, its mutate has already run
+  // (due to service call execution order), so we use its mutate result as the "retrieve success result".
+  const serviceResults: unknown[] = [];
+  if (internal.serviceCalls) {
+    for (const serviceCall of internal.serviceCalls) {
+      if (serviceCall === undefined) {
+        serviceResults.push(undefined);
+        continue;
+      }
+
+      const serviceCallInternal = serviceCall._internal;
+      // Check if this is a mutate-only service call (empty array sentinel with mutate callback)
+      // In that case, prefer mutateResult over the empty array retrieveSuccessResult
+      if (
+        serviceCallInternal.retrieveSuccessResult !== undefined &&
+        !(
+          Array.isArray(serviceCallInternal.retrieveSuccessResult) &&
+          serviceCallInternal.retrieveSuccessResult.length === 0 &&
+          serviceCallInternal.callbacks.mutate
+        )
+      ) {
+        serviceResults.push(serviceCallInternal.retrieveSuccessResult);
+      } else if (serviceCallInternal.mutateResult !== undefined) {
+        serviceResults.push(serviceCallInternal.mutateResult);
+      } else {
+        serviceResults.push(serviceCallInternal.retrieveSuccessResult);
+      }
+    }
+  }
+
+  if (callbacks.retrieveSuccess) {
+    internal.retrieveSuccessResult = callbacks.retrieveSuccess(
+      retrieveResults,
+      serviceResults as ExtractServiceRetrieveResults<readonly TxResult<unknown>[]>,
+    );
+  } else {
+    internal.retrieveSuccessResult = retrieveResults as typeof internal.retrieveSuccessResult;
+  }
+
+  if (callbacks.mutate) {
+    const mutateCtx = {
+      uow: internal.schema
+        ? baseUow.forSchema(internal.schema)
+        : (undefined as unknown as TypedUnitOfWork<AnySchema, [], unknown, HooksMap>),
+      // At this point retrieveSuccessResult has been set (either by retrieveSuccess
+      // callback or defaulted to retrieveResults)
+      retrieveResult: internal.retrieveSuccessResult as NonNullable<
+        typeof internal.retrieveSuccessResult
+      >,
+      serviceIntermediateResult: serviceResults as ExtractServiceRetrieveResults<
+        readonly TxResult<unknown>[]
+      >,
+    };
+    internal.mutateResult = callbacks.mutate(mutateCtx);
+  }
+
+  if (internal.typedUow) {
+    internal.typedUow.signalReadyForMutation();
+  } else {
+    // For TxResults without retrieve callback, signal via the restricted UOW
+    internal.restrictedUow.signalReadyForMutation();
+  }
 }
 
-export interface ServiceTxCallbacks<
-  TSchema extends AnySchema,
-  TRetrievalResults extends unknown[],
-  TMutationResult,
-  THooks extends HooksMap,
-> {
-  /**
-   * Retrieval phase callback - schedules retrievals, returns typed UOW
-   */
-  retrieve?: (
-    uow: TypedUnitOfWork<TSchema, [], unknown, THooks>,
-  ) => TypedUnitOfWork<TSchema, TRetrievalResults, unknown, THooks>;
-  /**
-   * Mutation phase callback - receives retrieval results, schedules mutations and hooks
-   */
-  mutate?: (
-    uow: TypedUnitOfWork<TSchema, TRetrievalResults, unknown, THooks>,
-    results: TRetrievalResults,
-  ) => TMutationResult | Promise<TMutationResult>;
+/**
+ * Execute a single TxResult's success callback after mutations complete.
+ */
+async function processTxResultAfterMutate<T>(txResult: TxResult<T>): Promise<T> {
+  const internal = txResult._internal;
+  const callbacks = internal.callbacks;
+
+  const serviceIntermediateResults: unknown[] = [];
+  const serviceFinalResults: unknown[] = [];
+  if (internal.serviceCalls) {
+    for (const serviceCall of internal.serviceCalls) {
+      if (serviceCall === undefined) {
+        serviceIntermediateResults.push(undefined);
+        serviceFinalResults.push(undefined);
+        continue;
+      }
+
+      // Mirror the logic from processTxResultAfterRetrieve/executeTx:
+      // For mutate-only serviceCalls (no retrieve phase, just mutations), use mutateResult instead of retrieveSuccessResult
+      const serviceCallInternal = serviceCall._internal;
+      // Check if this is a mutate-only service call (empty array sentinel with mutate callback)
+      // In that case, prefer mutateResult over the empty array retrieveSuccessResult
+      if (
+        serviceCallInternal.retrieveSuccessResult !== undefined &&
+        !(
+          Array.isArray(serviceCallInternal.retrieveSuccessResult) &&
+          serviceCallInternal.retrieveSuccessResult.length === 0 &&
+          serviceCallInternal.callbacks.mutate
+        )
+      ) {
+        serviceIntermediateResults.push(serviceCallInternal.retrieveSuccessResult);
+      } else if (serviceCallInternal.mutateResult !== undefined) {
+        serviceIntermediateResults.push(serviceCallInternal.mutateResult);
+      } else {
+        serviceIntermediateResults.push(serviceCallInternal.retrieveSuccessResult);
+      }
+      serviceFinalResults.push(serviceCallInternal.finalResult);
+    }
+  }
+
+  if (callbacks.success) {
+    const successCtx = {
+      retrieveResult: internal.retrieveSuccessResult as NonNullable<
+        typeof internal.retrieveSuccessResult
+      >,
+      mutateResult: internal.mutateResult,
+      serviceResult: serviceFinalResults as ExtractServiceFinalResults<
+        readonly TxResult<unknown>[]
+      >,
+      serviceIntermediateResult: serviceIntermediateResults as ExtractServiceRetrieveResults<
+        readonly TxResult<unknown>[]
+      >,
+    };
+    internal.finalResult = callbacks.success(successCtx) as T;
+  } else if (callbacks.mutate) {
+    internal.finalResult = (await awaitPromisesInObject(internal.mutateResult)) as T;
+  } else if (callbacks.retrieveSuccess || callbacks.retrieve) {
+    internal.finalResult = internal.retrieveSuccessResult as T;
+  } else {
+    internal.finalResult = serviceFinalResults as T;
+  }
+
+  return internal.finalResult as T;
 }
 
 /**
- * Execute a Unit of Work with explicit phase control and automatic retry support.
+ * Execute a transaction with the unified TxResult pattern.
  *
- * This function provides an alternative API where users write a single callback that receives
- * a context object with forSchema, executeRetrieve, and executeMutate methods. The user can
- * create schema-specific UOWs via forSchema, then call executeRetrieve() and executeMutate()
- * to execute the retrieval and mutation phases. The entire callback is re-executed on optimistic
- * concurrency conflicts, ensuring retries work properly.
+ * This is the handler-level function that actually executes TxResults with retry support.
  *
- * @param callback - Async function that receives a context with forSchema, executeRetrieve, executeMutate, nonce, and currentAttempt
+ * @param callbacks - Transaction callbacks (serviceCalls, retrieve, retrieveSuccess, mutate, success)
  * @param options - Configuration including UOW factory, retry policy, and abort signal
- * @returns Promise resolving to the callback's return value
- * @throws Error if retries are exhausted or callback throws an error
+ * @returns Promise resolving to the result determined by return type priority
  *
  * @example
  * ```ts
- * const { userId, profileId } = await executeRestrictedUnitOfWork(
- *   async ({ forSchema, executeRetrieve, executeMutate, nonce, currentAttempt }) => {
- *     const uow = forSchema(schema);
- *     const userId = uow.create("users", { name: "John" });
- *
- *     // Execute retrieval phase
- *     await executeRetrieve();
- *
- *     const profileId = uow.create("profiles", { userId });
- *
- *     // Execute mutation phase
- *     await executeMutate();
- *
- *     return { userId, profileId };
- *   },
- *   {
- *     createUnitOfWork: () => db.createUnitOfWork(),
- *     retryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 5 })
- *   }
- * );
- * ```
+ * // Simple retrieve + transform
+ * const user = await executeTx({
+ *   retrieve: (ctx) => ctx.forSchema(usersSchema).find("users", ...),
+ *   retrieveSuccess: ([users]) => users[0] ?? null,
+ * }, { createUnitOfWork });
+ * @internal Used by HandlerTxBuilder.execute()
  */
-export async function executeRestrictedUnitOfWork<TResult, THooks extends HooksMap = {}>(
-  callback: (context: {
-    forSchema: <S extends AnySchema, H extends HooksMap = THooks>(
-      schema: S,
-      hooks?: H,
-    ) => TypedUnitOfWork<S, [], unknown, H>;
-    executeRetrieve: () => Promise<void>;
-    executeMutate: () => Promise<void>;
-    nonce: string;
-    currentAttempt: number;
-  }) => Promise<TResult>,
-  options: ExecuteRestrictedUnitOfWorkOptions,
-): Promise<AwaitedPromisesInObject<TResult>> {
-  // Default retry policy with small, fast retries for optimistic concurrency
-  const retryPolicy =
-    options.retryPolicy ??
-    new ExponentialBackoffRetryPolicy({
-      maxRetries: 5,
-      initialDelayMs: 10,
-      maxDelayMs: 100,
-    });
+async function executeTx(
+  callbacks: HandlerTxCallbacks<
+    unknown[],
+    unknown,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    readonly (TxResult<any, any> | undefined)[],
+    unknown,
+    unknown,
+    HooksMap
+  >,
+  options: ExecuteTxOptions,
+): Promise<unknown> {
+  type TRetrieveResults = unknown[];
+  type TRetrieveSuccessResult = unknown;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  type TServiceCalls = readonly (TxResult<any, any> | undefined)[];
+  type TMutateResult = unknown;
+  type THooks = HooksMap;
   const signal = options.signal;
   let attempt = 0;
 
   while (true) {
     // Check if aborted before starting attempt
     if (signal?.aborted) {
-      throw new Error("Unit of Work execution aborted");
+      throw new Error("Transaction execution aborted");
     }
 
+    let retryPolicy: RetryPolicy | undefined;
+
     try {
       // Create a fresh UOW for this attempt
       const baseUow = options.createUnitOfWork();
 
-      const context = {
+      // Create handler context
+      const context: HandlerTxContext<THooks> = {
         forSchema: <S extends AnySchema, H extends HooksMap = THooks>(schema: S, hooks?: H) => {
           return baseUow.forSchema(schema, hooks);
         },
-        executeRetrieve: async () => {
-          await baseUow.executeRetrieve();
-        },
-        executeMutate: async () => {
-          if (baseUow.state === "executed") {
-            return;
-          }
-
-          if (baseUow.state === "building-retrieval") {
-            await baseUow.executeRetrieve();
-          }
-
-          // Add hook mutations before executing
-          if (options.onBeforeMutate) {
-            options.onBeforeMutate(baseUow);
-          }
-
-          const result = await baseUow.executeMutations();
-          if (!result.success) {
-            throw new ConcurrencyConflictError();
-          }
-
-          if (options.onSuccess) {
-            await options.onSuccess(baseUow);
-          }
-        },
-        nonce: baseUow.nonce,
+        idempotencyKey: baseUow.idempotencyKey,
         currentAttempt: attempt,
       };
 
-      // Execute the callback which will call executeRetrieve and executeMutate
-      const result = await callback(context);
-
-      // Await promises in the result object (1 level deep)
-      const awaitedResult = await awaitPromisesInObject(result);
-
-      // Return the awaited result
-      return awaitedResult;
-    } catch (error) {
-      if (signal?.aborted) {
-        throw new Error("Unit of Work execution aborted");
+      // Call serviceCalls factory if provided - this creates TxResults that schedule operations
+      let serviceCalls: TServiceCalls | undefined;
+      if (callbacks.serviceCalls) {
+        serviceCalls = callbacks.serviceCalls();
       }
 
-      // Only retry concurrency conflicts, not other errors
-      if (!(error instanceof ConcurrencyConflictError)) {
-        // Not a concurrency conflict - throw immediately without retry
-        throw error;
-      }
+      // Call retrieve callback - it returns a TypedUnitOfWork with scheduled operations or void
+      const typedUowFromRetrieve = callbacks.retrieve?.(context);
 
-      if (!retryPolicy.shouldRetry(attempt, error, signal)) {
-        // No more retries - check again if aborted or throw conflict error
-        if (signal?.aborted) {
-          throw new Error("Unit of Work execution aborted");
+      const allServiceCallTxResults = serviceCalls ? collectAllTxResults([...serviceCalls]) : [];
+
+      const hasRetrieveOps = baseUow.getRetrievalOperations().length > 0;
+      if (!hasRetrieveOps) {
+        if (options.retryPolicy) {
+          throw new Error(
+            "Retry policy is only supported when the transaction includes retrieve operations.",
+          );
         }
-        throw new Error("Unit of Work execution failed: optimistic concurrency conflict", {
-          cause: error,
-        });
+        retryPolicy = new NoRetryPolicy();
+      } else {
+        retryPolicy =
+          options.retryPolicy ??
+          new ExponentialBackoffRetryPolicy({
+            maxRetries: 5,
+            initialDelayMs: 10,
+            maxDelayMs: 100,
+          });
       }
 
-      const delayMs = retryPolicy.getDelayMs(attempt);
-      if (delayMs > 0) {
-        await new Promise((resolve) => setTimeout(resolve, delayMs));
-      }
+      await baseUow.executeRetrieve();
 
-      attempt++;
-    }
-  }
-}
+      // Get retrieve results from TypedUnitOfWork's retrievalPhase or default to empty array
+      const retrieveResult: TRetrieveResults = typedUowFromRetrieve
+        ? await typedUowFromRetrieve.retrievalPhase
+        : ([] as unknown as TRetrieveResults);
 
-/**
- * Execute a transaction with array syntax (handler context).
- * Takes a factory function that creates an array of service promises, enabling proper retry support.
- *
- * @param servicesFactory - Function that creates an array of service promises
- * @param options - Configuration including UOW factory, retry policy, and abort signal
- * @returns Promise resolving to array of awaited service results
- *
- * @example
- * ```ts
- * const [result1, result2] = await executeTxArray(
- *   () => [
- *     executeServiceTx(schema, callbacks1, uow),
- *     executeServiceTx(schema, callbacks2, uow)
- *   ],
- *   { createUnitOfWork }
- * );
- * ```
- */
-export async function executeTxArray<T extends readonly unknown[]>(
-  servicesFactory: () => readonly [...{ [K in keyof T]: Promise<T[K]> }],
-  options: ExecuteRestrictedUnitOfWorkOptions,
-): Promise<{ [K in keyof T]: T[K] }> {
-  const retryPolicy =
-    options.retryPolicy ??
-    new ExponentialBackoffRetryPolicy({
-      maxRetries: 5,
-      initialDelayMs: 10,
-      maxDelayMs: 100,
-    });
-  const signal = options.signal;
-  let attempt = 0;
-
-  while (true) {
-    // Check if aborted before starting attempt
-    if (signal?.aborted) {
-      throw new Error("Unit of Work execution aborted");
-    }
+      for (const txResult of allServiceCallTxResults) {
+        await processTxResultAfterRetrieve(txResult, baseUow);
+      }
 
-    try {
-      // Create a fresh UOW for this attempt
-      const baseUow = options.createUnitOfWork();
+      const serviceResults: unknown[] = [];
+      if (serviceCalls) {
+        for (const serviceCall of serviceCalls) {
+          if (serviceCall === undefined) {
+            serviceResults.push(undefined);
+            continue;
+          }
+          const serviceCallInternal = serviceCall._internal;
+          // Check if this is a mutate-only service call (empty array sentinel with mutate callback)
+          // In that case, prefer mutateResult over the empty array retrieveSuccessResult
+          if (
+            serviceCallInternal.retrieveSuccessResult !== undefined &&
+            !(
+              Array.isArray(serviceCallInternal.retrieveSuccessResult) &&
+              serviceCallInternal.retrieveSuccessResult.length === 0 &&
+              serviceCallInternal.callbacks.mutate
+            )
+          ) {
+            serviceResults.push(serviceCallInternal.retrieveSuccessResult);
+          } else if (serviceCallInternal.mutateResult !== undefined) {
+            serviceResults.push(serviceCallInternal.mutateResult);
+          } else {
+            serviceResults.push(serviceCallInternal.retrieveSuccessResult);
+          }
+        }
+      }
 
-      // Call factory to create fresh service promises for this attempt
-      const services = servicesFactory();
+      // Call retrieveSuccess if provided
+      let retrieveSuccessResult: TRetrieveSuccessResult;
+      if (callbacks.retrieveSuccess) {
+        retrieveSuccessResult = callbacks.retrieveSuccess(
+          retrieveResult,
+          serviceResults as ExtractServiceRetrieveResults<TServiceCalls>,
+        );
+      } else {
+        retrieveSuccessResult = retrieveResult as unknown as TRetrieveSuccessResult;
+      }
 
-      await baseUow.executeRetrieve();
+      let mutateResult: TMutateResult | undefined;
+      if (callbacks.mutate) {
+        const mutateCtx: HandlerTxMutateContext<
+          TRetrieveSuccessResult,
+          ExtractServiceRetrieveResults<TServiceCalls>,
+          THooks
+        > = {
+          ...context,
+          retrieveResult: retrieveSuccessResult,
+          serviceIntermediateResult: serviceResults as ExtractServiceRetrieveResults<TServiceCalls>,
+        };
+        mutateResult = callbacks.mutate(mutateCtx);
+      }
 
       if (options.onBeforeMutate) {
         options.onBeforeMutate(baseUow);
       }
-
       const result = await baseUow.executeMutations();
       if (!result.success) {
         throw new ConcurrencyConflictError();
       }
 
-      if (options.onSuccess) {
-        await options.onSuccess(baseUow);
+      // Process each serviceCall TxResult's success callback
+      for (const txResult of allServiceCallTxResults) {
+        await processTxResultAfterMutate(txResult);
+      }
+
+      const serviceFinalResults: unknown[] = [];
+      if (serviceCalls) {
+        for (const serviceCall of serviceCalls) {
+          if (serviceCall === undefined) {
+            serviceFinalResults.push(undefined);
+            continue;
+          }
+          serviceFinalResults.push(serviceCall._internal.finalResult);
+        }
+      }
+
+      let finalResult: unknown;
+      if (callbacks.success) {
+        // The success context type is determined by the overload - we construct it at runtime
+        // and the type safety is guaranteed by the discriminated overloads
+        const successCtx = {
+          retrieveResult: retrieveSuccessResult,
+          mutateResult,
+          serviceResult: serviceFinalResults as ExtractServiceFinalResults<TServiceCalls>,
+          serviceIntermediateResult: serviceResults as ExtractServiceRetrieveResults<TServiceCalls>,
+        } as Parameters<NonNullable<typeof callbacks.success>>[0];
+        finalResult = callbacks.success(successCtx);
+      } else if (callbacks.mutate) {
+        finalResult = await awaitPromisesInObject(mutateResult);
+      } else if (callbacks.retrieveSuccess || callbacks.retrieve) {
+        finalResult = retrieveSuccessResult;
+      } else {
+        finalResult = serviceFinalResults;
+      }
+
+      if (options.onAfterMutate) {
+        await options.onAfterMutate(baseUow);
       }
 
-      // Now await all service promises - they should all resolve now that mutations executed
-      const results = await Promise.all(services);
-      return results as { [K in keyof T]: T[K] };
+      return await awaitPromisesInObject(finalResult);
     } catch (error) {
       if (signal?.aborted) {
-        throw new Error("Unit of Work execution aborted");
+        throw new Error("Transaction execution aborted");
       }
 
       // Only retry concurrency conflicts, not other errors
@@ -624,13 +898,15 @@ export async function executeTxArray<T extends readonly unknown[]>(
         throw error;
       }
 
+      if (!retryPolicy) {
+        throw error;
+      }
+
       if (!retryPolicy.shouldRetry(attempt, error, signal)) {
         if (signal?.aborted) {
-          throw new Error("Unit of Work execution aborted");
+          throw new Error("Transaction execution aborted");
         }
-        throw new Error("Unit of Work execution failed: optimistic concurrency conflict", {
-          cause: error,
-        });
+        throw new ConcurrencyConflictError();
       }
 
       const delayMs = retryPolicy.getDelayMs(attempt);
@@ -644,169 +920,1005 @@ export async function executeTxArray<T extends readonly unknown[]>(
 }
 
 /**
- * Execute a transaction with callback syntax (handler context).
- * Callbacks are synchronous only to prevent accidentally awaiting services in wrong place.
- *
- * @param callbacks - Object containing retrieve and mutate callbacks
- * @param options - Configuration including UOW factory, retry policy, and abort signal
- * @returns Promise resolving to the mutation result with promises awaited 1 level deep
+ * Error thrown when a Unit of Work execution fails due to optimistic concurrency conflict.
+ * This error triggers automatic retry behavior in executeTx.
  */
-export async function executeTxCallbacks<
-  TRetrieveResult,
-  TMutationResult,
-  THooks extends HooksMap = {},
->(
-  callbacks: HandlerTxCallbacks<TRetrieveResult, TMutationResult, THooks>,
-  options: ExecuteRestrictedUnitOfWorkOptions,
-): Promise<AwaitedPromisesInObject<TMutationResult>> {
-  const retryPolicy =
-    options.retryPolicy ??
-    new ExponentialBackoffRetryPolicy({
-      maxRetries: 5,
-      initialDelayMs: 10,
-      maxDelayMs: 100,
-    });
-  const signal = options.signal;
-  let attempt = 0;
+export class ConcurrencyConflictError extends Error {
+  constructor(message = "Optimistic concurrency conflict detected") {
+    super(message);
+    this.name = "ConcurrencyConflictError";
+  }
+}
 
-  while (true) {
-    // Check if aborted before starting attempt
-    if (signal?.aborted) {
-      throw new Error("Unit of Work execution aborted");
-    }
+/**
+ * Type utility that unwraps promises 1 level deep in objects, arrays, or direct promises
+ * Handles tuples, arrays, objects, and direct promises
+ */
+export type AwaitedPromisesInObject<T> =
+  // First check if it's a Promise
+  T extends Promise<infer U>
+    ? Awaited<U>
+    : // Check for arrays with known length (tuples) - preserves tuple structure
+      T extends readonly [unknown, ...unknown[]]
+      ? { [K in keyof T]: AwaitedPromisesInObject<T[K]> }
+      : T extends [unknown, ...unknown[]]
+        ? { [K in keyof T]: AwaitedPromisesInObject<T[K]> }
+        : // Check for regular arrays (unknown length)
+          T extends (infer U)[]
+          ? Awaited<U>[]
+          : T extends readonly (infer U)[]
+            ? readonly Awaited<U>[]
+            : // Check for objects
+              T extends Record<string, unknown>
+              ? {
+                  [K in keyof T]: T[K] extends Promise<infer U> ? Awaited<U> : T[K];
+                }
+              : // Otherwise return as-is
+                T;
 
-    try {
-      // Create a fresh UOW for this attempt
-      const baseUow = options.createUnitOfWork();
+/**
+ * Await promises in an object 1 level deep
+ */
+async function awaitPromisesInObject<T>(obj: T): Promise<AwaitedPromisesInObject<T>> {
+  if (obj === null || obj === undefined) {
+    return obj as AwaitedPromisesInObject<T>;
+  }
 
-      const context: TxPhaseContext<THooks> = {
-        forSchema: <S extends AnySchema, H extends HooksMap = THooks>(schema: S, hooks?: H) => {
-          return baseUow.forSchema(schema, hooks);
-        },
-      };
+  if (typeof obj !== "object") {
+    return obj as AwaitedPromisesInObject<T>;
+  }
 
-      let retrieveResult: TRetrieveResult;
-      if (callbacks.retrieve) {
-        retrieveResult = callbacks.retrieve(context);
-      } else {
-        retrieveResult = undefined as TRetrieveResult;
-      }
+  // Check if it's a Promise
+  if (obj instanceof Promise) {
+    return (await obj) as AwaitedPromisesInObject<T>;
+  }
 
-      await baseUow.executeRetrieve();
+  // Check if it's an array
+  if (Array.isArray(obj)) {
+    const awaited = await Promise.all(
+      obj.map((item) => (item instanceof Promise ? item : Promise.resolve(item))),
+    );
+    return awaited as AwaitedPromisesInObject<T>;
+  }
 
-      let mutationResult: TMutationResult;
-      if (callbacks.mutate) {
-        mutationResult = callbacks.mutate(context, retrieveResult);
-      } else {
-        mutationResult = retrieveResult as unknown as TMutationResult;
-      }
+  if (obj.constructor !== Object) {
+    return obj as AwaitedPromisesInObject<T>;
+  }
+  const result = {} as T;
+  const entries = Object.entries(obj as Record<string, unknown>);
+  const awaitedEntries = await Promise.all(
+    entries.map(async ([key, value]) => {
+      const awaitedValue = value instanceof Promise ? await value : value;
+      return [key, awaitedValue] as const;
+    }),
+  );
 
-      const awaitedMutationResult = await awaitPromisesInObject(mutationResult);
+  for (const [key, value] of awaitedEntries) {
+    (result as Record<string, unknown>)[key] = value;
+  }
 
-      if (options.onBeforeMutate) {
-        options.onBeforeMutate(baseUow);
-      }
+  return result as AwaitedPromisesInObject<T>;
+}
 
-      const result = await baseUow.executeMutations();
-      if (!result.success) {
-        throw new ConcurrencyConflictError();
-      }
+// ============================================================================
+// Builder Pattern Types and Classes
+// ============================================================================
 
-      if (options.onSuccess) {
-        await options.onSuccess(baseUow);
-      }
+/**
+ * Context passed to service-level mutate callback in builder pattern.
+ */
+export interface ServiceBuilderMutateContext<
+  TSchema extends AnySchema,
+  TRetrieveSuccessResult,
+  TServiceResult extends readonly unknown[],
+  THooks extends HooksMap,
+> {
+  /** Unit of work for scheduling mutations */
+  uow: TypedUnitOfWork<TSchema, [], unknown, THooks>;
+  /** Result from transformRetrieve callback (or raw retrieve results if no transformRetrieve) */
+  retrieveResult: TRetrieveSuccessResult;
+  /** Array of retrieve success results from service calls (intermediate results, not final: retrieve results if service has retrieve, mutate result if service only mutates) */
+  serviceIntermediateResult: TServiceResult;
+}
 
-      return awaitedMutationResult;
-    } catch (error) {
-      if (signal?.aborted) {
-        throw new Error("Unit of Work execution aborted");
-      }
+/**
+ * Context passed to handler-level mutate callback in builder pattern.
+ */
+export interface HandlerBuilderMutateContext<
+  TRetrieveSuccessResult,
+  TServiceResult extends readonly unknown[],
+  THooks extends HooksMap,
+> {
+  /** Get a typed Unit of Work for the given schema */
+  forSchema: <S extends AnySchema, H extends HooksMap = THooks>(
+    schema: S,
+    hooks?: H,
+  ) => TypedUnitOfWork<S, [], unknown, H>;
+  /** Unique key for this transaction (for idempotency/deduplication) */
+  idempotencyKey: string;
+  /** Current attempt number (0-based) */
+  currentAttempt: number;
+  /** Result from transformRetrieve callback (or raw retrieve results if no transformRetrieve) */
+  retrieveResult: TRetrieveSuccessResult;
+  /** Array of retrieve success results from service calls (intermediate results, not final: retrieve results if service has retrieve, mutate result if service only mutates) */
+  serviceIntermediateResult: TServiceResult;
+}
 
-      // Only retry concurrency conflicts, not other errors
-      if (!(error instanceof ConcurrencyConflictError)) {
-        throw error;
-      }
+/**
+ * Context passed to transform callback when mutate IS provided.
+ */
+export interface BuilderTransformContextWithMutate<
+  TRetrieveSuccessResult,
+  TMutateResult,
+  TServiceFinalResult extends readonly unknown[],
+  TServiceIntermediateResult extends readonly unknown[],
+> {
+  /** Result from transformRetrieve callback (or raw retrieve results if no transformRetrieve) */
+  retrieveResult: TRetrieveSuccessResult;
+  /** Result from mutate callback */
+  mutateResult: TMutateResult;
+  /** Array of final results from service calls (after success/transform callbacks) */
+  serviceResult: TServiceFinalResult;
+  /** Array of retrieve success results from service calls (same as what mutate receives: retrieve results if service has retrieve, mutate result if service only mutates) */
+  serviceIntermediateResult: TServiceIntermediateResult;
+}
 
-      if (!retryPolicy.shouldRetry(attempt, error, signal)) {
-        if (signal?.aborted) {
-          throw new Error("Unit of Work execution aborted");
-        }
-        throw new Error("Unit of Work execution failed: optimistic concurrency conflict", {
-          cause: error,
-        });
-      }
+/**
+ * Context passed to transform callback when mutate is NOT provided.
+ */
+export interface BuilderTransformContextWithoutMutate<
+  TRetrieveSuccessResult,
+  TServiceFinalResult extends readonly unknown[],
+  TServiceIntermediateResult extends readonly unknown[],
+> {
+  /** Result from transformRetrieve callback (or raw retrieve results if no transformRetrieve) */
+  retrieveResult: TRetrieveSuccessResult;
+  /** No mutate callback was provided */
+  mutateResult: undefined;
+  /** Array of final results from service calls (after success/transform callbacks) */
+  serviceResult: TServiceFinalResult;
+  /** Array of retrieve success results from service calls (same as what mutate receives: retrieve results if service has retrieve, mutate result if service only mutates) */
+  serviceIntermediateResult: TServiceIntermediateResult;
+}
 
-      const delayMs = retryPolicy.getDelayMs(attempt);
-      if (delayMs > 0) {
-        await new Promise((resolve) => setTimeout(resolve, delayMs));
-      }
+/**
+ * Infer the final result type from builder state:
+ * 1. transform → TTransformResult
+ * 2. mutate → AwaitedPromisesInObject<TMutateResult>
+ * 3. transformRetrieve → TRetrieveSuccessResult
+ * 4. retrieve → TRetrieveResults
+ * 5. withServiceCalls → ExtractServiceFinalResults<TServiceCalls>
+ */
+export type InferBuilderResultType<
+  TRetrieveResults extends unknown[],
+  TRetrieveSuccessResult,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TServiceCalls extends readonly (TxResult<any, any> | undefined)[],
+  TMutateResult,
+  TTransformResult,
+  HasTransform extends boolean,
+  HasMutate extends boolean,
+  HasTransformRetrieve extends boolean,
+  HasRetrieve extends boolean,
+> = HasTransform extends true
+  ? TTransformResult
+  : HasMutate extends true
+    ? AwaitedPromisesInObject<TMutateResult>
+    : HasTransformRetrieve extends true
+      ? TRetrieveSuccessResult
+      : HasRetrieve extends true
+        ? TRetrieveResults
+        : ExtractServiceFinalResults<TServiceCalls>;
 
-      attempt++;
-    }
-  }
+/**
+ * Infer the retrieve success result type for the builder:
+ * - If transformRetrieve exists: TRetrieveSuccessResult
+ * - Else if retrieve exists: TRetrieveResults (raw retrieve results)
+ * - Else if mutate exists: AwaitedPromisesInObject<TMutateResult>
+ *   (mutate result becomes retrieve result for dependents)
+ * - Else: TRetrieveResults (raw retrieve results, typically [])
+ */
+export type InferBuilderRetrieveSuccessResult<
+  TRetrieveResults extends unknown[],
+  TRetrieveSuccessResult,
+  TMutateResult,
+  HasTransformRetrieve extends boolean,
+  HasRetrieve extends boolean,
+  HasMutate extends boolean,
+> = HasTransformRetrieve extends true
+  ? TRetrieveSuccessResult
+  : HasRetrieve extends true
+    ? TRetrieveResults
+    : HasMutate extends true
+      ? AwaitedPromisesInObject<TMutateResult>
+      : TRetrieveResults;
+
+/**
+ * Internal state for ServiceTxBuilder
+ */
+interface ServiceTxBuilderState<
+  TSchema extends AnySchema,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TServiceCalls extends readonly (TxResult<any, any> | undefined)[],
+  TRetrieveResults extends unknown[],
+  TRetrieveSuccessResult,
+  TMutateResult,
+  TTransformResult,
+  THooks extends HooksMap,
+> {
+  schema: TSchema;
+  baseUow: IUnitOfWork;
+  hooks?: THooks;
+  withServiceCallsFn?: () => TServiceCalls;
+  retrieveFn?: (
+    uow: TypedUnitOfWork<TSchema, [], unknown, THooks>,
+  ) => TypedUnitOfWork<TSchema, TRetrieveResults, unknown, THooks>;
+  transformRetrieveFn?: (
+    retrieveResult: TRetrieveResults,
+    serviceRetrieveResult: ExtractServiceRetrieveResults<TServiceCalls>,
+  ) => TRetrieveSuccessResult;
+  mutateFn?: (
+    ctx: ServiceBuilderMutateContext<
+      TSchema,
+      TRetrieveSuccessResult,
+      ExtractServiceRetrieveResults<TServiceCalls>,
+      THooks
+    >,
+  ) => TMutateResult;
+  transformFn?: (
+    ctx:
+      | BuilderTransformContextWithMutate<
+          TRetrieveSuccessResult,
+          TMutateResult,
+          ExtractServiceFinalResults<TServiceCalls>,
+          ExtractServiceRetrieveResults<TServiceCalls>
+        >
+      | BuilderTransformContextWithoutMutate<
+          TRetrieveSuccessResult,
+          ExtractServiceFinalResults<TServiceCalls>,
+          ExtractServiceRetrieveResults<TServiceCalls>
+        >,
+  ) => TTransformResult;
 }
 
 /**
- * Execute a transaction for service context.
- * Service callbacks can be async for ergonomic async work.
+ * Builder for service-level transactions.
+ * Uses a fluent API to build up transaction callbacks with proper type inference.
  *
- * @param schema - Schema to use for the transaction
- * @param callbacks - Object containing retrieve and mutate callbacks
- * @param baseUow - Base Unit of Work (restricted) to use
- * @returns Promise resolving to the mutation result with promises awaited 1 level deep
+ * @example
+ * ```ts
+ * return serviceTx(schema)
+ *   .withServiceCalls(() => [otherService.getData()])
+ *   .retrieve((uow) => uow.find("users", ...))
+ *   .transformRetrieve(([users], serviceResult) => users[0])
+ *   .mutate(({ uow, retrieveResult, serviceIntermediateResult }) =>
+ *     uow.create("records", { ... })
+ *   )
+ *   .transform(({ mutateResult, serviceResult, serviceIntermediateResult }) => ({ id: mutateResult }))
+ *   .build();
+ * ```
  */
-export async function executeServiceTx<
+export class ServiceTxBuilder<
   TSchema extends AnySchema,
-  TRetrievalResults extends unknown[],
-  TMutationResult,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TServiceCalls extends readonly (TxResult<any, any> | undefined)[],
+  TRetrieveResults extends unknown[],
+  TRetrieveSuccessResult,
+  TMutateResult,
+  TTransformResult,
+  HasRetrieve extends boolean,
+  HasTransformRetrieve extends boolean,
+  HasMutate extends boolean,
+  HasTransform extends boolean,
   THooks extends HooksMap,
->(
-  schema: TSchema,
-  callbacks: ServiceTxCallbacks<TSchema, TRetrievalResults, TMutationResult, THooks>,
-  baseUow: IUnitOfWork,
-): Promise<AwaitedPromisesInObject<TMutationResult>> {
-  const typedUow = baseUow.restrict({ readyFor: "none" }).forSchema<TSchema, THooks>(schema);
+> {
+  readonly #state: ServiceTxBuilderState<
+    TSchema,
+    TServiceCalls,
+    TRetrieveResults,
+    TRetrieveSuccessResult,
+    TMutateResult,
+    TTransformResult,
+    THooks
+  >;
+
+  constructor(
+    state: ServiceTxBuilderState<
+      TSchema,
+      TServiceCalls,
+      TRetrieveResults,
+      TRetrieveSuccessResult,
+      TMutateResult,
+      TTransformResult,
+      THooks
+    >,
+  ) {
+    this.#state = state;
+  }
 
-  let retrievalUow: TypedUnitOfWork<TSchema, TRetrievalResults, unknown, THooks>;
-  try {
-    if (callbacks.retrieve) {
-      retrievalUow = callbacks.retrieve(typedUow);
-    } else {
-      // Safe cast: when there's no retrieve callback, TRetrievalResults should be []
-      retrievalUow = typedUow as unknown as TypedUnitOfWork<
+  /**
+   * Add dependencies to execute before this transaction.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  withServiceCalls<TNewDeps extends readonly (TxResult<any, any> | undefined)[]>(
+    fn: () => TNewDeps,
+  ): ServiceTxBuilder<
+    TSchema,
+    TNewDeps,
+    TRetrieveResults,
+    TRetrieveSuccessResult,
+    TMutateResult,
+    TTransformResult,
+    HasRetrieve,
+    HasTransformRetrieve,
+    HasMutate,
+    HasTransform,
+    THooks
+  > {
+    return new ServiceTxBuilder({
+      ...this.#state,
+      withServiceCallsFn: fn,
+    } as ServiceTxBuilderState<
+      TSchema,
+      TNewDeps,
+      TRetrieveResults,
+      TRetrieveSuccessResult,
+      TMutateResult,
+      TTransformResult,
+      THooks
+    >);
+  }
+
+  /**
+   * Add retrieval operations to the transaction.
+   */
+  retrieve<TNewRetrieveResults extends unknown[]>(
+    fn: (
+      uow: TypedUnitOfWork<TSchema, [], unknown, THooks>,
+    ) => TypedUnitOfWork<TSchema, TNewRetrieveResults, unknown, THooks>,
+  ): ServiceTxBuilder<
+    TSchema,
+    TServiceCalls,
+    TNewRetrieveResults,
+    TNewRetrieveResults, // Default TRetrieveSuccessResult to TNewRetrieveResults
+    TMutateResult,
+    TTransformResult,
+    true, // HasRetrieve = true
+    false, // Reset HasTransformRetrieve since retrieve results changed
+    HasMutate,
+    HasTransform,
+    THooks
+  > {
+    return new ServiceTxBuilder({
+      ...this.#state,
+      retrieveFn: fn,
+      transformRetrieveFn: undefined, // Clear any existing transformRetrieve since results shape changed
+    } as unknown as ServiceTxBuilderState<
+      TSchema,
+      TServiceCalls,
+      TNewRetrieveResults,
+      TNewRetrieveResults,
+      TMutateResult,
+      TTransformResult,
+      THooks
+    >);
+  }
+
+  /**
+   * Transform retrieve results before passing to mutate.
+   */
+  transformRetrieve<TNewRetrieveSuccessResult>(
+    fn: (
+      retrieveResult: TRetrieveResults,
+      serviceResult: ExtractServiceRetrieveResults<TServiceCalls>,
+    ) => TNewRetrieveSuccessResult,
+  ): ServiceTxBuilder<
+    TSchema,
+    TServiceCalls,
+    TRetrieveResults,
+    TNewRetrieveSuccessResult,
+    TMutateResult,
+    TTransformResult,
+    HasRetrieve,
+    true, // HasTransformRetrieve = true
+    HasMutate,
+    HasTransform,
+    THooks
+  > {
+    return new ServiceTxBuilder({
+      ...this.#state,
+      transformRetrieveFn: fn,
+    } as unknown as ServiceTxBuilderState<
+      TSchema,
+      TServiceCalls,
+      TRetrieveResults,
+      TNewRetrieveSuccessResult,
+      TMutateResult,
+      TTransformResult,
+      THooks
+    >);
+  }
+
+  /**
+   * Add mutation operations based on retrieve results.
+   */
+  mutate<TNewMutateResult>(
+    fn: (
+      ctx: ServiceBuilderMutateContext<
         TSchema,
-        TRetrievalResults,
-        unknown,
+        HasTransformRetrieve extends true ? TRetrieveSuccessResult : TRetrieveResults,
+        ExtractServiceRetrieveResults<TServiceCalls>,
         THooks
-      >;
-    }
-  } catch (error) {
-    typedUow.signalReadyForRetrieval();
-    typedUow.signalReadyForMutation();
-    throw error;
+      >,
+    ) => TNewMutateResult,
+  ): ServiceTxBuilder<
+    TSchema,
+    TServiceCalls,
+    TRetrieveResults,
+    HasTransformRetrieve extends true ? TRetrieveSuccessResult : TRetrieveResults,
+    TNewMutateResult,
+    TTransformResult,
+    HasRetrieve,
+    HasTransformRetrieve,
+    true, // HasMutate = true
+    HasTransform,
+    THooks
+  > {
+    return new ServiceTxBuilder({
+      ...this.#state,
+      mutateFn: fn,
+    } as unknown as ServiceTxBuilderState<
+      TSchema,
+      TServiceCalls,
+      TRetrieveResults,
+      HasTransformRetrieve extends true ? TRetrieveSuccessResult : TRetrieveResults,
+      TNewMutateResult,
+      TTransformResult,
+      THooks
+    >);
   }
 
-  typedUow.signalReadyForRetrieval();
+  /**
+   * Add final transformation after mutations complete.
+   */
+  transform<TNewTransformResult>(
+    fn: (
+      ctx: HasMutate extends true
+        ? BuilderTransformContextWithMutate<
+            HasTransformRetrieve extends true ? TRetrieveSuccessResult : TRetrieveResults,
+            TMutateResult,
+            ExtractServiceFinalResults<TServiceCalls>,
+            ExtractServiceRetrieveResults<TServiceCalls>
+          >
+        : BuilderTransformContextWithoutMutate<
+            HasTransformRetrieve extends true ? TRetrieveSuccessResult : TRetrieveResults,
+            ExtractServiceFinalResults<TServiceCalls>,
+            ExtractServiceRetrieveResults<TServiceCalls>
+          >,
+    ) => TNewTransformResult,
+  ): ServiceTxBuilder<
+    TSchema,
+    TServiceCalls,
+    TRetrieveResults,
+    HasTransformRetrieve extends true ? TRetrieveSuccessResult : TRetrieveResults,
+    TMutateResult,
+    TNewTransformResult,
+    HasRetrieve,
+    HasTransformRetrieve,
+    HasMutate,
+    true, // HasTransform = true
+    THooks
+  > {
+    return new ServiceTxBuilder({
+      ...this.#state,
+      transformFn: fn,
+    } as unknown as ServiceTxBuilderState<
+      TSchema,
+      TServiceCalls,
+      TRetrieveResults,
+      HasTransformRetrieve extends true ? TRetrieveSuccessResult : TRetrieveResults,
+      TMutateResult,
+      TNewTransformResult,
+      THooks
+    >);
+  }
 
-  // Safe cast: retrievalPhase returns the correct type based on the UOW's type parameters
-  const results = (await retrievalUow.retrievalPhase) as TRetrievalResults;
+  /**
+   * Build and return the TxResult.
+   */
+  build(): TxResult<
+    InferBuilderResultType<
+      TRetrieveResults,
+      TRetrieveSuccessResult,
+      TServiceCalls,
+      TMutateResult,
+      TTransformResult,
+      HasTransform,
+      HasMutate,
+      HasTransformRetrieve,
+      HasRetrieve
+    >,
+    InferBuilderRetrieveSuccessResult<
+      TRetrieveResults,
+      TRetrieveSuccessResult,
+      TMutateResult,
+      HasTransformRetrieve,
+      HasRetrieve,
+      HasMutate
+    >
+  > {
+    const state = this.#state;
+
+    // Convert builder state to legacy callbacks format
+    const callbacks: ServiceTxCallbacks<
+      TSchema,
+      TRetrieveResults,
+      TRetrieveSuccessResult,
+      TServiceCalls,
+      TMutateResult,
+      TTransformResult,
+      THooks
+    > = {
+      serviceCalls: state.withServiceCallsFn,
+      retrieve: state.retrieveFn,
+      retrieveSuccess: state.transformRetrieveFn,
+      mutate: state.mutateFn
+        ? (ctx) => {
+            return state.mutateFn!({
+              uow: ctx.uow,
+              retrieveResult: ctx.retrieveResult,
+              serviceIntermediateResult: ctx.serviceIntermediateResult,
+            });
+          }
+        : undefined,
+      success: state.transformFn
+        ? (ctx) => {
+            return state.transformFn!({
+              retrieveResult: ctx.retrieveResult,
+              mutateResult: ctx.mutateResult,
+              serviceResult: ctx.serviceResult,
+              serviceIntermediateResult: ctx.serviceIntermediateResult,
+            } as BuilderTransformContextWithMutate<
+              TRetrieveSuccessResult,
+              TMutateResult,
+              ExtractServiceFinalResults<TServiceCalls>,
+              ExtractServiceRetrieveResults<TServiceCalls>
+            >);
+          }
+        : undefined,
+    };
 
-  let mutationResult: TMutationResult;
-  try {
-    if (callbacks.mutate) {
-      mutationResult = await callbacks.mutate(retrievalUow, results);
-    } else {
-      // Safe cast: when there's no mutate callback, TMutationResult should be void
-      mutationResult = undefined as TMutationResult;
-    }
-  } catch (error) {
-    typedUow.signalReadyForMutation();
-    throw error;
+    // Use the existing createServiceTx implementation
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return createServiceTx(state.schema, callbacks as any, state.baseUow) as unknown as TxResult<
+      InferBuilderResultType<
+        TRetrieveResults,
+        TRetrieveSuccessResult,
+        TServiceCalls,
+        TMutateResult,
+        TTransformResult,
+        HasTransform,
+        HasMutate,
+        HasTransformRetrieve,
+        HasRetrieve
+      >,
+      InferBuilderRetrieveSuccessResult<
+        TRetrieveResults,
+        TRetrieveSuccessResult,
+        TMutateResult,
+        HasTransformRetrieve,
+        HasRetrieve,
+        HasMutate
+      >
+    >;
+  }
+}
+
+/**
+ * Create a new ServiceTxBuilder for the given schema.
+ */
+export function createServiceTxBuilder<TSchema extends AnySchema, THooks extends HooksMap = {}>(
+  schema: TSchema,
+  baseUow: IUnitOfWork,
+  hooks?: THooks,
+): ServiceTxBuilder<
+  TSchema,
+  readonly [],
+  [],
+  [],
+  unknown,
+  unknown,
+  false,
+  false,
+  false,
+  false,
+  THooks
+> {
+  return new ServiceTxBuilder({
+    schema,
+    baseUow,
+    hooks,
+  });
+}
+
+/**
+ * Internal state for HandlerTxBuilder
+ */
+interface HandlerTxBuilderState<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TServiceCalls extends readonly (TxResult<any, any> | undefined)[],
+  TRetrieveResults extends unknown[],
+  TRetrieveSuccessResult,
+  TMutateResult,
+  TTransformResult,
+  THooks extends HooksMap,
+> {
+  options: ExecuteTxOptions;
+  hooks?: THooks;
+  withServiceCallsFn?: () => TServiceCalls;
+  retrieveFn?: (context: {
+    forSchema: <S extends AnySchema, H extends HooksMap = THooks>(
+      schema: S,
+      hooks?: H,
+    ) => TypedUnitOfWork<S, [], unknown, H>;
+    idempotencyKey: string;
+    currentAttempt: number;
+  }) => TypedUnitOfWork<AnySchema, TRetrieveResults, unknown, HooksMap> | void;
+  transformRetrieveFn?: (
+    retrieveResult: TRetrieveResults,
+    serviceResult: ExtractServiceRetrieveResults<TServiceCalls>,
+  ) => TRetrieveSuccessResult;
+  mutateFn?: (
+    ctx: HandlerBuilderMutateContext<
+      TRetrieveSuccessResult,
+      ExtractServiceRetrieveResults<TServiceCalls>,
+      THooks
+    >,
+  ) => TMutateResult;
+  transformFn?: (
+    ctx:
+      | BuilderTransformContextWithMutate<
+          TRetrieveSuccessResult,
+          TMutateResult,
+          ExtractServiceFinalResults<TServiceCalls>,
+          ExtractServiceRetrieveResults<TServiceCalls>
+        >
+      | BuilderTransformContextWithoutMutate<
+          TRetrieveSuccessResult,
+          ExtractServiceFinalResults<TServiceCalls>,
+          ExtractServiceRetrieveResults<TServiceCalls>
+        >,
+  ) => TTransformResult;
+}
+
+/**
+ * Builder for handler-level transactions.
+ * Uses a fluent API to build up transaction callbacks with proper type inference.
+ *
+ * @example
+ * ```ts
+ * const result = await handlerTx()
+ *   .withServiceCalls(() => [userService.getUser(id)])
+ *   .mutate(({ forSchema, idempotencyKey, currentAttempt, serviceIntermediateResult }) => {
+ *     return forSchema(ordersSchema).create("orders", { ... });
+ *   })
+ *   .transform(({ mutateResult, serviceResult }) => ({ ... }))
+ *   .execute();
+ * ```
+ */
+export class HandlerTxBuilder<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TServiceCalls extends readonly (TxResult<any, any> | undefined)[],
+  TRetrieveResults extends unknown[],
+  TRetrieveSuccessResult,
+  TMutateResult,
+  TTransformResult,
+  HasRetrieve extends boolean,
+  HasTransformRetrieve extends boolean,
+  HasMutate extends boolean,
+  HasTransform extends boolean,
+  THooks extends HooksMap,
+> {
+  readonly #state: HandlerTxBuilderState<
+    TServiceCalls,
+    TRetrieveResults,
+    TRetrieveSuccessResult,
+    TMutateResult,
+    TTransformResult,
+    THooks
+  >;
+
+  constructor(
+    state: HandlerTxBuilderState<
+      TServiceCalls,
+      TRetrieveResults,
+      TRetrieveSuccessResult,
+      TMutateResult,
+      TTransformResult,
+      THooks
+    >,
+  ) {
+    this.#state = state;
   }
 
-  typedUow.signalReadyForMutation();
+  /**
+   * Add dependencies to execute before this transaction.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  withServiceCalls<TNewDeps extends readonly (TxResult<any, any> | undefined)[]>(
+    fn: () => TNewDeps,
+  ): HandlerTxBuilder<
+    TNewDeps,
+    TRetrieveResults,
+    TRetrieveSuccessResult,
+    TMutateResult,
+    TTransformResult,
+    HasRetrieve,
+    HasTransformRetrieve,
+    HasMutate,
+    HasTransform,
+    THooks
+  > {
+    return new HandlerTxBuilder({
+      ...this.#state,
+      withServiceCallsFn: fn,
+    } as HandlerTxBuilderState<
+      TNewDeps,
+      TRetrieveResults,
+      TRetrieveSuccessResult,
+      TMutateResult,
+      TTransformResult,
+      THooks
+    >);
+  }
+
+  /**
+   * Add retrieval operations to the transaction.
+   * Return a TypedUnitOfWork from forSchema().find() to get typed results.
+   */
+  retrieve<TNewRetrieveResults extends unknown[]>(
+    fn: (context: {
+      forSchema: <S extends AnySchema, H extends HooksMap = THooks>(
+        schema: S,
+        hooks?: H,
+      ) => TypedUnitOfWork<S, [], unknown, H>;
+      idempotencyKey: string;
+      currentAttempt: number;
+    }) => TypedUnitOfWork<AnySchema, TNewRetrieveResults, unknown, HooksMap> | void,
+  ): HandlerTxBuilder<
+    TServiceCalls,
+    TNewRetrieveResults,
+    TNewRetrieveResults, // Default TRetrieveSuccessResult to TNewRetrieveResults
+    TMutateResult,
+    TTransformResult,
+    true, // HasRetrieve = true
+    false, // Reset HasTransformRetrieve since retrieve results changed
+    HasMutate,
+    HasTransform,
+    THooks
+  > {
+    return new HandlerTxBuilder({
+      ...this.#state,
+      retrieveFn: fn,
+      transformRetrieveFn: undefined, // Clear any existing transformRetrieve since results shape changed
+    } as unknown as HandlerTxBuilderState<
+      TServiceCalls,
+      TNewRetrieveResults,
+      TNewRetrieveResults,
+      TMutateResult,
+      TTransformResult,
+      THooks
+    >);
+  }
 
-  await retrievalUow.mutationPhase;
+  /**
+   * Transform retrieve results before passing to mutate.
+   */
+  transformRetrieve<TNewRetrieveSuccessResult>(
+    fn: (
+      retrieveResult: TRetrieveResults,
+      serviceResult: ExtractServiceRetrieveResults<TServiceCalls>,
+    ) => TNewRetrieveSuccessResult,
+  ): HandlerTxBuilder<
+    TServiceCalls,
+    TRetrieveResults,
+    TNewRetrieveSuccessResult,
+    TMutateResult,
+    TTransformResult,
+    HasRetrieve,
+    true, // HasTransformRetrieve = true
+    HasMutate,
+    HasTransform,
+    THooks
+  > {
+    return new HandlerTxBuilder({
+      ...this.#state,
+      transformRetrieveFn: fn,
+    } as unknown as HandlerTxBuilderState<
+      TServiceCalls,
+      TRetrieveResults,
+      TNewRetrieveSuccessResult,
+      TMutateResult,
+      TTransformResult,
+      THooks
+    >);
+  }
 
-  return await awaitPromisesInObject(mutationResult);
+  /**
+   * Add mutation operations based on retrieve results.
+   */
+  mutate<TNewMutateResult>(
+    fn: (
+      ctx: HandlerBuilderMutateContext<
+        HasTransformRetrieve extends true ? TRetrieveSuccessResult : TRetrieveResults,
+        ExtractServiceRetrieveResults<TServiceCalls>,
+        THooks
+      >,
+    ) => TNewMutateResult,
+  ): HandlerTxBuilder<
+    TServiceCalls,
+    TRetrieveResults,
+    HasTransformRetrieve extends true ? TRetrieveSuccessResult : TRetrieveResults,
+    TNewMutateResult,
+    TTransformResult,
+    HasRetrieve,
+    HasTransformRetrieve,
+    true, // HasMutate = true
+    HasTransform,
+    THooks
+  > {
+    return new HandlerTxBuilder({
+      ...this.#state,
+      mutateFn: fn,
+    } as unknown as HandlerTxBuilderState<
+      TServiceCalls,
+      TRetrieveResults,
+      HasTransformRetrieve extends true ? TRetrieveSuccessResult : TRetrieveResults,
+      TNewMutateResult,
+      TTransformResult,
+      THooks
+    >);
+  }
+
+  /**
+   * Add final transformation after mutations complete.
+   */
+  transform<TNewTransformResult>(
+    fn: (
+      ctx: HasMutate extends true
+        ? BuilderTransformContextWithMutate<
+            HasTransformRetrieve extends true ? TRetrieveSuccessResult : TRetrieveResults,
+            TMutateResult,
+            ExtractServiceFinalResults<TServiceCalls>,
+            ExtractServiceRetrieveResults<TServiceCalls>
+          >
+        : BuilderTransformContextWithoutMutate<
+            HasTransformRetrieve extends true ? TRetrieveSuccessResult : TRetrieveResults,
+            ExtractServiceFinalResults<TServiceCalls>,
+            ExtractServiceRetrieveResults<TServiceCalls>
+          >,
+    ) => TNewTransformResult,
+  ): HandlerTxBuilder<
+    TServiceCalls,
+    TRetrieveResults,
+    HasTransformRetrieve extends true ? TRetrieveSuccessResult : TRetrieveResults,
+    TMutateResult,
+    TNewTransformResult,
+    HasRetrieve,
+    HasTransformRetrieve,
+    HasMutate,
+    true, // HasTransform = true
+    THooks
+  > {
+    return new HandlerTxBuilder({
+      ...this.#state,
+      transformFn: fn,
+    } as unknown as HandlerTxBuilderState<
+      TServiceCalls,
+      TRetrieveResults,
+      HasTransformRetrieve extends true ? TRetrieveSuccessResult : TRetrieveResults,
+      TMutateResult,
+      TNewTransformResult,
+      THooks
+    >);
+  }
+
+  /**
+   * Execute the transaction and return the result.
+   */
+  execute(): Promise<
+    AwaitedPromisesInObject<
+      InferBuilderResultType<
+        TRetrieveResults,
+        TRetrieveSuccessResult,
+        TServiceCalls,
+        TMutateResult,
+        TTransformResult,
+        HasTransform,
+        HasMutate,
+        HasTransformRetrieve,
+        HasRetrieve
+      >
+    >
+  > {
+    const state = this.#state;
+
+    // Convert builder state to legacy callbacks format
+    const callbacks: HandlerTxCallbacks<
+      TRetrieveResults,
+      TRetrieveSuccessResult,
+      TServiceCalls,
+      TMutateResult,
+      TTransformResult,
+      THooks
+    > = {
+      serviceCalls: state.withServiceCallsFn,
+      retrieve: state.retrieveFn
+        ? (context) => {
+            return state.retrieveFn!({
+              forSchema: context.forSchema,
+              idempotencyKey: context.idempotencyKey,
+              currentAttempt: context.currentAttempt,
+            });
+          }
+        : undefined,
+      retrieveSuccess: state.transformRetrieveFn,
+      mutate: state.mutateFn
+        ? (ctx) => {
+            return state.mutateFn!({
+              forSchema: ctx.forSchema,
+              idempotencyKey: ctx.idempotencyKey,
+              currentAttempt: ctx.currentAttempt,
+              retrieveResult: ctx.retrieveResult,
+              serviceIntermediateResult: ctx.serviceIntermediateResult,
+            });
+          }
+        : undefined,
+      success: state.transformFn
+        ? (ctx) => {
+            return state.transformFn!({
+              retrieveResult: ctx.retrieveResult,
+              mutateResult: ctx.mutateResult,
+              serviceResult: ctx.serviceResult,
+              serviceIntermediateResult: ctx.serviceIntermediateResult,
+            } as BuilderTransformContextWithMutate<
+              TRetrieveSuccessResult,
+              TMutateResult,
+              ExtractServiceFinalResults<TServiceCalls>,
+              ExtractServiceRetrieveResults<TServiceCalls>
+            >);
+          }
+        : undefined,
+    };
+
+    // Use the existing executeTx implementation
+    return executeTx(callbacks as Parameters<typeof executeTx>[0], state.options) as Promise<
+      AwaitedPromisesInObject<
+        InferBuilderResultType<
+          TRetrieveResults,
+          TRetrieveSuccessResult,
+          TServiceCalls,
+          TMutateResult,
+          TTransformResult,
+          HasTransform,
+          HasMutate,
+          HasTransformRetrieve,
+          HasRetrieve
+        >
+      >
+    >;
+  }
+}
+
+/**
+ * Create a new HandlerTxBuilder with the given options.
+ */
+export function createHandlerTxBuilder<THooks extends HooksMap = {}>(
+  options: ExecuteTxOptions,
+  hooks?: THooks,
+): HandlerTxBuilder<readonly [], [], [], unknown, unknown, false, false, false, false, THooks> {
+  return new HandlerTxBuilder({
+    options,
+    hooks,
+  });
 }