@fragno-dev/db 0.2.1 → 0.3.0

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

@@ -1,29 +1,26 @@
-import { describe, it, expect, vi, assert, expectTypeOf } from "vitest";
+import { describe, it, expect, expectTypeOf } from "vitest";
 import { schema, idColumn, FragnoId } from "../../schema/create";
 import {
   createUnitOfWork,
-  type TypedUnitOfWork,
   type IUnitOfWork,
   type UOWCompiler,
   type UOWDecoder,
   type UOWExecutor,
 } from "./unit-of-work";
 import {
-  executeUnitOfWork,
-  executeRestrictedUnitOfWork,
-  executeTxArray,
-  executeTxCallbacks,
-  executeServiceTx,
+  createServiceTxBuilder,
+  createHandlerTxBuilder,
+  isTxResult,
+  ConcurrencyConflictError,
 } from "./execute-unit-of-work";
 import {
   ExponentialBackoffRetryPolicy,
   LinearBackoffRetryPolicy,
   NoRetryPolicy,
 } from "./retry-policy";
-import type { AwaitedPromisesInObject } from "./execute-unit-of-work";
+import type { AwaitedPromisesInObject, TxResult } from "./execute-unit-of-work";
 
-// Create test schema
-const testSchema = schema((s) =>
+const testSchema = schema("test", (s) =>
   s.addTable("users", (t) =>
     t
       .addColumn("id", idColumn())
@@ -34,7 +31,6 @@ const testSchema = schema((s) =>
   ),
 );
 
-// Type tests for AwaitedPromisesInObject
 describe("AwaitedPromisesInObject type tests", () => {
   it("should unwrap promises in objects", () => {
     type Input = { a: Promise<string>; b: number };
@@ -132,1329 +128,1155 @@ function createMockDecoder(): UOWDecoder {
   };
 }
 
-// Helper to create a UOW factory that tracks how many times it's called
-function createMockUOWFactory(mutationResults: Array<{ success: boolean }>) {
-  const callCount = { value: 0 };
-  // Share callIndex across all UOW instances
-  let callIndex = 0;
+describe("Unified Tx API", () => {
+  describe("isTxResult", () => {
+    it("should return true for TxResult objects", () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+      };
+      const decoder = createMockDecoder();
+      const baseUow = createUnitOfWork(compiler, executor, decoder);
 
-  const factory = () => {
-    callCount.value++;
+      const txResult = createServiceTxBuilder(testSchema, baseUow)
+        .retrieve((uow) => uow.find("users", (b) => b.whereIndex("idx_email")))
+        .build();
 
-    // Create executor that uses shared callIndex
-    const executor: UOWExecutor<unknown, unknown> = {
-      executeRetrievalPhase: async () => {
-        return [
+      expect(isTxResult(txResult)).toBe(true);
+    });
+
+    it("should return false for non-TxResult objects", () => {
+      expect(isTxResult(null)).toBe(false);
+      expect(isTxResult(undefined)).toBe(false);
+      expect(isTxResult({})).toBe(false);
+      expect(isTxResult({ _internal: {} })).toBe(false);
+      expect(isTxResult(Promise.resolve())).toBe(false);
+    });
+  });
+
+  describe("createServiceTx", () => {
+    it("should create a TxResult with retrieve callback", () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [
           [
             {
-              id: FragnoId.fromExternal("user-1", 1),
+              id: FragnoId.fromExternal("1", 1),
               email: "test@example.com",
-              name: "Test User",
+              name: "Test",
               balance: 100,
             },
           ],
-        ];
-      },
-      executeMutationPhase: async () => {
-        const result = mutationResults[callIndex] || { success: false };
-        callIndex++;
-        return { ...result, createdInternalIds: [] };
-      },
-    };
-
-    return createUnitOfWork(createMockCompiler(), executor, createMockDecoder()).forSchema(
-      testSchema,
-    );
-  };
-  return { factory, callCount };
-}
-
-describe("executeUnitOfWork", () => {
-  describe("validation", () => {
-    it("should throw error when neither retrieve nor mutate is provided", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-
-      await expect(executeUnitOfWork({}, { createUnitOfWork: factory })).rejects.toThrow(
-        "At least one of 'retrieve' or 'mutate' callbacks must be provided",
-      );
-    });
-  });
-
-  describe("success scenarios", () => {
-    it("should succeed on first attempt without retries", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-      const onSuccess = vi.fn();
-
-      const result = await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: (uow, [users]) => {
-            const newBalance = users[0].balance + 100;
-            uow.update("users", users[0].id, (b) => b.set({ balance: newBalance }).check());
-            return { newBalance };
-          },
-          onSuccess,
-        },
-        { createUnitOfWork: factory },
-      );
-
-      assert(result.success);
-      expect(result.mutationResult).toEqual({ newBalance: 200 });
-      expect(onSuccess).toHaveBeenCalledExactlyOnceWith({
-        results: expect.any(Array),
-        mutationResult: { newBalance: 200 },
-        createdIds: [],
-        nonce: expect.any(String),
-      });
-    });
-  });
-
-  describe("retry scenarios", () => {
-    it("should retry on conflict with eventual success", async () => {
-      const { factory, callCount } = createMockUOWFactory([
-        { success: false },
-        { success: false },
-        { success: true },
-      ]);
-
-      const result = await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async (uow, [users]) => {
-            uow.update("users", users[0].id, (b) => b.set({ balance: 200 }).check());
-          },
-        },
-        {
-          createUnitOfWork: factory,
-          retryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 3, initialDelayMs: 1 }),
-        },
-      );
-
-      expect(result.success).toBe(true);
-      expect(callCount.value).toBe(3); // Initial + 2 retries
-    });
-
-    it("should fail when max retries exceeded", async () => {
-      const { factory, callCount } = createMockUOWFactory([
-        { success: false },
-        { success: false },
-        { success: false },
-        { success: false },
-      ]);
-
-      const result = await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async (uow, [users]) => {
-            uow.update("users", users[0].id, (b) => b.set({ balance: 200 }));
-          },
-        },
-        {
-          createUnitOfWork: factory,
-          retryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 2, initialDelayMs: 1 }),
-        },
-      );
-
-      assert(!result.success);
-      expect(result.reason).toBe("conflict");
-      expect(callCount.value).toBe(3); // Initial + 2 retries
-    });
-
-    it("should create fresh UOW on each retry attempt", async () => {
-      const { factory, callCount } = createMockUOWFactory([
-        { success: false },
-        { success: false },
-        { success: true },
-      ]);
-
-      await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async (uow, [users]) => {
-            uow.update("users", users[0].id, (b) => b.set({ balance: 200 }));
-          },
-        },
-        {
-          createUnitOfWork: factory,
-          retryPolicy: new LinearBackoffRetryPolicy({ maxRetries: 3, delayMs: 1 }),
-        },
-      );
-
-      expect(callCount.value).toBe(3); // Each attempt creates a new UOW
-    });
-  });
-
-  describe("AbortSignal handling", () => {
-    it("should abort when signal is aborted before execution", async () => {
-      const { factory } = createMockUOWFactory([{ success: false }]);
-      const controller = new AbortController();
-      controller.abort();
-
-      const result = await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async (uow, [users]) => {
-            uow.update("users", users[0].id, (b) => b.set({ balance: 200 }));
-          },
-        },
-        {
-          createUnitOfWork: factory,
-          retryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 5, initialDelayMs: 1 }),
-          signal: controller.signal,
-        },
-      );
-
-      assert(!result.success);
-      expect(result.reason).toBe("aborted");
-    });
-
-    it("should abort when signal is aborted during retry", async () => {
-      const { factory } = createMockUOWFactory([{ success: false }, { success: false }]);
-      const controller = new AbortController();
-
-      // Abort after first attempt
-      setTimeout(() => controller.abort(), 50);
-
-      const result = await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async (uow, [users]) => {
-            uow.update("users", users[0].id, (b) => b.set({ balance: 200 }));
-          },
-        },
-        {
-          createUnitOfWork: factory,
-          retryPolicy: new LinearBackoffRetryPolicy({ maxRetries: 5, delayMs: 100 }),
-          signal: controller.signal,
-        },
-      );
-
-      assert(!result.success);
-      expect(result.reason).toBe("aborted");
-    });
-  });
-
-  describe("onSuccess callback", () => {
-    it("should pass mutation result to onSuccess callback", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-      const onSuccess = vi.fn();
-
-      await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async () => {
-            return { updatedCount: 5 };
-          },
-          onSuccess,
-        },
-        { createUnitOfWork: factory },
-      );
-
-      expect(onSuccess).toHaveBeenCalledTimes(1);
-      expect(onSuccess).toHaveBeenCalledWith({
-        results: expect.any(Array),
-        mutationResult: { updatedCount: 5 },
-        createdIds: [],
-        nonce: expect.any(String),
-      });
-    });
-
-    it("should only execute onSuccess callback on success", async () => {
-      const { factory } = createMockUOWFactory([{ success: false }]);
-      const onSuccess = vi.fn();
-
-      const result = await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async (uow, [users]) => {
-            uow.update("users", users[0].id, (b) => b.set({ balance: 200 }));
-          },
-          onSuccess,
-        },
-        {
-          createUnitOfWork: factory,
-          retryPolicy: new NoRetryPolicy(),
-        },
-      );
-
-      assert(!result.success);
-      expect(result.reason).toBe("conflict");
-      expect(onSuccess).not.toHaveBeenCalled();
-    });
-
-    it("should execute onSuccess only once even after retries", async () => {
-      const { factory } = createMockUOWFactory([
-        { success: false },
-        { success: false },
-        { success: true },
-      ]);
-      const onSuccess = vi.fn();
-
-      await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async (uow, [users]) => {
-            uow.update("users", users[0].id, (b) => b.set({ balance: 200 }));
-          },
-          onSuccess,
-        },
-        {
-          createUnitOfWork: factory,
-          retryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 3, initialDelayMs: 1 }),
-        },
-      );
-
-      expect(onSuccess).toHaveBeenCalledTimes(1);
-    });
-
-    it("should handle async onSuccess callback", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-      const onSuccess = vi.fn(async () => {
-        await new Promise((resolve) => setTimeout(resolve, 10));
-      });
-
-      await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async (uow, [users]) => {
-            uow.update("users", users[0].id, (b) => b.set({ balance: 200 }));
-          },
-          onSuccess,
-        },
-        { createUnitOfWork: factory },
-      );
-
-      expect(onSuccess).toHaveBeenCalledTimes(1);
-    });
-  });
+        ],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+      };
+      const decoder = createMockDecoder();
+      const baseUow = createUnitOfWork(compiler, executor, decoder);
 
-  describe("error handling", () => {
-    it("should return error result when retrieve callback throws", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-      const testError = new Error("Retrieve failed");
+      const txResult = createServiceTxBuilder(testSchema, baseUow)
+        .retrieve((uow) => uow.find("users", (b) => b.whereIndex("idx_email")))
+        .build();
 
-      const result = await executeUnitOfWork(
-        {
-          retrieve: () => {
-            throw testError;
-          },
-          mutate: async () => {},
-        },
-        { createUnitOfWork: factory },
-      );
-
-      assert(!result.success);
-      assert(result.reason === "error");
-      expect(result.error).toBe(testError);
+      expect(isTxResult(txResult)).toBe(true);
+      expect(txResult._internal.schema).toBe(testSchema);
+      expect(txResult._internal.callbacks.retrieve).toBeDefined();
     });
 
-    it("should return error result when mutate callback throws", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-      const testError = new Error("Mutate failed");
+    it("should create a TxResult with transformRetrieve callback", () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [
+          [
+            {
+              id: FragnoId.fromExternal("1", 1),
+              email: "test@example.com",
+              name: "Test",
+              balance: 100,
+            },
+          ],
+        ],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+      };
+      const decoder = createMockDecoder();
+      const baseUow = createUnitOfWork(compiler, executor, decoder);
 
-      const result = await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async () => {
-            throw testError;
-          },
-        },
-        { createUnitOfWork: factory },
-      );
+      const txResult = createServiceTxBuilder(testSchema, baseUow)
+        .retrieve((uow) => uow.find("users", (b) => b.whereIndex("idx_email")))
+        .transformRetrieve(([users]) => users[0] ?? null)
+        .build();
 
-      assert(!result.success);
-      assert(result.reason === "error");
-      expect(result.error).toBe(testError);
+      expect(isTxResult(txResult)).toBe(true);
+      expect(txResult._internal.callbacks.retrieveSuccess).toBeDefined();
     });
 
-    it("should return error result when onSuccess callback throws", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-      const testError = new Error("onSuccess failed");
+    it("should create a TxResult with serviceCalls", () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [
+          [
+            {
+              id: FragnoId.fromExternal("1", 1),
+              email: "test@example.com",
+              name: "Test",
+              balance: 100,
+            },
+          ],
+        ],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+      };
+      const decoder = createMockDecoder();
+      const baseUow = createUnitOfWork(compiler, executor, decoder);
 
-      const result = await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async () => {},
-          onSuccess: async () => {
-            throw testError;
-          },
-        },
-        { createUnitOfWork: factory },
-      );
+      // Create a dependency TxResult
+      const depTxResult = createServiceTxBuilder(testSchema, baseUow)
+        .retrieve((uow) => uow.find("users", (b) => b.whereIndex("idx_email")))
+        .transformRetrieve(([users]) => users[0] ?? null)
+        .build();
+
+      // Create a TxResult that depends on it
+      const txResult = createServiceTxBuilder(testSchema, baseUow)
+        .withServiceCalls(() => [depTxResult])
+        .mutate(({ uow, serviceIntermediateResult: [user] }) => {
+          if (!user) {
+            throw new Error("User not found");
+          }
+          return uow.create("users", { email: "new@example.com", name: "New", balance: 0 });
+        })
+        .build();
 
-      assert(!result.success);
-      assert(result.reason === "error");
-      expect(result.error).toBe(testError);
+      expect(isTxResult(txResult)).toBe(true);
+      expect(txResult._internal.serviceCalls).toHaveLength(1);
     });
 
-    it("should capture non-Error thrown values", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-
-      const result = await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async () => {
-            throw "string error";
-          },
-        },
-        { createUnitOfWork: factory },
-      );
+    it("should type mutateResult as non-undefined when success AND mutate are provided", () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+      };
+      const decoder = createMockDecoder();
+      const baseUow = createUnitOfWork(compiler, executor, decoder);
 
-      assert(!result.success);
-      assert(result.reason === "error");
-      expect(result.error).toBe("string error");
+      // When BOTH mutate AND success are provided, mutateResult should NOT be undefined
+      createServiceTxBuilder(testSchema, baseUow)
+        .mutate(({ uow }) => {
+          uow.create("users", { email: "test@example.com", name: "Test", balance: 0 });
+          return { created: true as const, code: "ABC123" };
+        })
+        .transform(({ mutateResult }) => {
+          // Key type assertion: mutateResult is NOT undefined when mutate callback IS provided
+          expectTypeOf(mutateResult).toEqualTypeOf<{ created: true; code: string }>();
+          // Should be able to access properties without null check
+          return { success: true, code: mutateResult.code };
+        })
+        .build();
     });
-  });
-
-  describe("retrieval results", () => {
-    it("should pass retrieval results to mutation phase", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-      const mutationPhase = vi.fn(async (_uow: unknown, _results: unknown) => {});
 
-      await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: mutationPhase,
-        },
-        { createUnitOfWork: factory },
-      );
+    it("should type mutateResult as undefined when success is provided but mutate is NOT", () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [
+          [
+            {
+              id: FragnoId.fromExternal("1", 1),
+              email: "test@example.com",
+              name: "Test",
+              balance: 100,
+            },
+          ],
+        ],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+      };
+      const decoder = createMockDecoder();
+      const baseUow = createUnitOfWork(compiler, executor, decoder);
 
-      expect(mutationPhase).toHaveBeenCalledTimes(1);
-      const call = mutationPhase.mock.calls[0];
-      assert(call);
-      const [_uow, results] = call;
-      expect(results).toBeInstanceOf(Array);
-      expect(results as unknown[]).toHaveLength(1);
-      expect((results as unknown[])[0]).toBeInstanceOf(Array);
+      // When success is provided but mutate is NOT, mutateResult should be undefined
+      createServiceTxBuilder(testSchema, baseUow)
+        .retrieve((uow) => uow.find("users", (b) => b.whereIndex("idx_email")))
+        .transformRetrieve(([users]) => users[0] ?? null)
+        // NO mutate callback
+        .transform(({ mutateResult, retrieveResult }) => {
+          // Key type assertion: mutateResult IS undefined when no mutate callback
+          expectTypeOf(mutateResult).toEqualTypeOf<undefined>();
+          // retrieveResult should still be properly typed (can be null from ?? null)
+          if (retrieveResult !== null) {
+            expectTypeOf(retrieveResult.email).toEqualTypeOf<string>();
+          }
+          return { user: retrieveResult };
+        })
+        .build();
     });
 
-    it("should return retrieval results in the result object", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-
-      const result = await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async () => {},
-        },
-        { createUnitOfWork: factory },
-      );
+    it("should type retrieveResult as TRetrieveResults when retrieve is provided but retrieveSuccess is NOT", () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [
+          [
+            {
+              id: FragnoId.fromExternal("1", 1),
+              email: "test@example.com",
+              name: "Test",
+              balance: 100,
+            },
+          ],
+        ],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+      };
+      const decoder = createMockDecoder();
+      const baseUow = createUnitOfWork(compiler, executor, decoder);
 
-      assert(result.success);
-      expect(result.results).toBeInstanceOf(Array);
-      expect(result.results).toHaveLength(1);
+      // When retrieve IS provided but retrieveSuccess is NOT, retrieveResult should be TRetrieveResults
+      // (the raw array from the retrieve callback), NOT unknown
+      createServiceTxBuilder(testSchema, baseUow)
+        .retrieve((uow) => uow.find("users", (b) => b.whereIndex("idx_email")))
+        // NO transformRetrieve callback - this is the key scenario
+        .mutate(({ uow, retrieveResult }) => {
+          // Key type assertion: retrieveResult should be the raw array type, NOT unknown
+          // The retrieve callback returns TypedUnitOfWork with [users[]] as the results type
+          expectTypeOf(retrieveResult).toEqualTypeOf<
+            [{ id: FragnoId; email: string; name: string; balance: number }[]]
+          >();
+
+          // Should be able to access the array without type errors
+          const users = retrieveResult[0];
+          expectTypeOf(users).toEqualTypeOf<
+            { id: FragnoId; email: string; name: string; balance: number }[]
+          >();
+
+          if (users.length > 0) {
+            const user = users[0];
+            uow.update("users", user.id, (b) => b.set({ balance: user.balance + 100 }));
+          }
+          return { processed: true };
+        })
+        .build();
     });
   });
 
-  describe("promise awaiting in mutation result", () => {
-    it("should await promises in mutation result object (1 level deep)", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-
-      const result = await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async () => {
-            return {
-              userId: Promise.resolve("user-123"),
-              count: Promise.resolve(42),
-              data: "plain-value",
-            };
-          },
-        },
-        { createUnitOfWork: factory },
-      );
-
-      assert(result.success);
-      expect(result.mutationResult).toEqual({
-        userId: "user-123",
-        count: 42,
-        data: "plain-value",
-      });
-    });
-
-    it("should await promises in mutation result array", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-
-      const result = await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async () => {
-            return [Promise.resolve("a"), Promise.resolve("b"), "c"];
-          },
-        },
-        { createUnitOfWork: factory },
-      );
-
-      assert(result.success);
-      expect(result.mutationResult).toEqual(["a", "b", "c"]);
-    });
-
-    it("should await direct promise mutation result", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-
-      const result = await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async () => {
-            return Promise.resolve({ value: "resolved" });
-          },
-        },
-        { createUnitOfWork: factory },
-      );
-
-      assert(result.success);
-      expect(result.mutationResult).toEqual({ value: "resolved" });
-    });
-
-    it("should NOT await nested promises (only 1 level deep)", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-
-      const result = await executeUnitOfWork(
+  describe("executeTx", () => {
+    it("should execute a simple retrieve-only transaction", async () => {
+      const compiler = createMockCompiler();
+      const mockUsers = [
         {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async () => {
-            return {
-              nested: { promise: Promise.resolve("still-a-promise") },
-            };
-          },
+          id: FragnoId.fromExternal("1", 1),
+          email: "alice@example.com",
+          name: "Alice",
+          balance: 100,
         },
-        { createUnitOfWork: factory },
-      );
-
-      assert(result.success);
-      // The nested promise should still be a promise
-      expect(result.mutationResult.nested.promise).toBeInstanceOf(Promise);
-    });
-
-    it("should handle mixed types in mutation result", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-
-      const result = await executeUnitOfWork(
         {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async () => {
-            return {
-              promise: Promise.resolve(100),
-              number: 42,
-              string: "test",
-              null: null,
-              undefined: undefined,
-              nested: { value: "nested" },
-            };
-          },
-        },
-        { createUnitOfWork: factory },
-      );
-
-      assert(result.success);
-      expect(result.mutationResult).toEqual({
-        promise: 100,
-        number: 42,
-        string: "test",
-        null: null,
-        undefined: undefined,
-        nested: { value: "nested" },
-      });
-    });
-
-    it("should pass awaited mutation result to onSuccess callback", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-      const onSuccess = vi.fn();
-
-      await executeUnitOfWork(
-        {
-          retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-          mutate: async () => {
-            return {
-              userId: Promise.resolve("user-456"),
-              status: Promise.resolve("active"),
-            };
-          },
-          onSuccess,
-        },
-        { createUnitOfWork: factory },
-      );
-
-      expect(onSuccess).toHaveBeenCalledExactlyOnceWith({
-        results: expect.any(Array),
-        mutationResult: {
-          userId: "user-456",
-          status: "active",
-        },
-        createdIds: [],
-        nonce: expect.any(String),
-      });
-    });
-  });
-});
-
-describe("executeRestrictedUnitOfWork", () => {
-  describe("basic success cases", () => {
-    it("should execute a simple mutation-only workflow", async () => {
-      const { factory, callCount } = createMockUOWFactory([{ success: true }]);
-
-      const result = await executeRestrictedUnitOfWork(
-        async ({ forSchema, executeMutate }) => {
-          const uow = forSchema(testSchema);
-          const userId = uow.create("users", {
-            id: "user-1",
-            email: "test@example.com",
-            name: "Test User",
-            balance: 100,
-          });
-
-          await executeMutate();
-
-          return { userId: userId.externalId };
-        },
-        { createUnitOfWork: factory },
-      );
-
-      expect(result).toEqual({ userId: "user-1" });
-      expect(callCount.value).toBe(1);
-    });
-
-    it("should execute retrieval and mutation phases", async () => {
-      const { factory, callCount } = createMockUOWFactory([{ success: true }]);
-
-      const result = await executeRestrictedUnitOfWork(
-        async ({ forSchema, executeRetrieve, executeMutate }) => {
-          const uow = forSchema(testSchema).find("users", (b) => b.whereIndex("primary"));
-          await executeRetrieve();
-          const [[user]] = await uow.retrievalPhase;
-
-          uow.update("users", user.id, (b) => b.set({ balance: user.balance + 50 }).check());
-          await executeMutate();
-
-          return { newBalance: user.balance + 50 };
-        },
-        { createUnitOfWork: factory },
-      );
-
-      expect(result).toEqual({ newBalance: 150 });
-      expect(callCount.value).toBe(1);
-    });
-
-    it("should return callback result directly", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-
-      const result = await executeRestrictedUnitOfWork(
-        async () => {
-          return { data: "test", count: 42, nested: { value: true } };
+          id: FragnoId.fromExternal("2", 1),
+          email: "bob@example.com",
+          name: "Bob",
+          balance: 200,
         },
-        { createUnitOfWork: factory },
-      );
+      ];
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [mockUsers],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+      };
+      const decoder = createMockDecoder();
 
-      expect(result).toEqual({ data: "test", count: 42, nested: { value: true } });
+      const [users] = await createHandlerTxBuilder({
+        createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
+      })
+        .retrieve(({ forSchema }) =>
+          forSchema(testSchema).find("users", (b) => b.whereIndex("idx_email")),
+        )
+        .execute();
+
+      expect(users).toHaveLength(2);
+      expect(users[0].email).toBe("alice@example.com");
+      expect(users[1].name).toBe("Bob");
     });
-  });
-
-  describe("retry behavior", () => {
-    it("should retry on conflict and eventually succeed", async () => {
-      const { factory, callCount } = createMockUOWFactory([
-        { success: false }, // First attempt fails
-        { success: false }, // Second attempt fails
-        { success: true }, // Third attempt succeeds
-      ]);
 
-      const callbackExecutions = { count: 0 };
-
-      const result = await executeRestrictedUnitOfWork(
-        async ({ forSchema, executeMutate }) => {
-          callbackExecutions.count++;
-          const uow = forSchema(testSchema);
+    it("should execute a simple mutate-only transaction", async () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [BigInt(1)] }),
+      };
+      const decoder = createMockDecoder();
 
-          uow.create("users", {
-            id: "user-1",
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
+      })
+        .mutate(({ forSchema }) => {
+          const userId = forSchema(testSchema).create("users", {
             email: "test@example.com",
-            name: "Test User",
+            name: "Test",
             balance: 100,
           });
+          return { userId };
+        })
+        .execute();
 
-          await executeMutate();
-
-          return { attempt: callbackExecutions.count };
-        },
-        { createUnitOfWork: factory },
-      );
-
-      expect(result.attempt).toBe(3);
-      expect(callCount.value).toBe(3);
-      expect(callbackExecutions.count).toBe(3);
+      expect(result.userId).toBeInstanceOf(FragnoId);
     });
 
-    it("should throw error when retries are exhausted", async () => {
-      const { factory, callCount } = createMockUOWFactory([
-        { success: false }, // First attempt fails
-        { success: false }, // Second attempt fails
-        { success: false }, // Third attempt fails
-        { success: false }, // Fourth attempt fails (exceeds default maxRetries: 3)
-      ]);
+    it("should throw when retry policy is provided without retrieve operations", async () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [],
+        executeMutationPhase: async () => ({ success: false }),
+      };
+      const decoder = createMockDecoder();
 
       await expect(
-        executeRestrictedUnitOfWork(
-          async ({ executeMutate }) => {
-            await executeMutate();
-            return { hello: "world" };
-          },
-          { createUnitOfWork: factory },
-        ),
-      ).rejects.toThrow("Unit of Work execution failed: optimistic concurrency conflict");
-
-      // Default policy has maxRetries: 5, so we make 6 attempts (initial + 5 retries)
-      expect(callCount.value).toBe(6);
-    });
-
-    it("should respect custom retry policy", async () => {
-      const { factory, callCount } = createMockUOWFactory([
-        { success: false },
-        { success: false },
-        { success: false },
-        { success: false },
-        { success: false },
-        { success: true },
-      ]);
-
-      const result = await executeRestrictedUnitOfWork(
-        async ({ executeMutate }) => {
-          await executeMutate();
-          return { done: true };
-        },
-        {
-          createUnitOfWork: factory,
-          retryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 5, initialDelayMs: 1 }),
-        },
-      );
-
-      expect(result).toEqual({ done: true });
-      expect(callCount.value).toBe(6); // Initial + 5 retries
-    });
-
-    it("should use default ExponentialBackoffRetryPolicy with small delays", async () => {
-      const { factory } = createMockUOWFactory([{ success: false }, { success: true }]);
-
-      const startTime = Date.now();
-      await executeRestrictedUnitOfWork(
-        async ({ executeMutate }) => {
-          await executeMutate();
-          return {};
-        },
-        { createUnitOfWork: factory },
+        createHandlerTxBuilder({
+          createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
+          retryPolicy: new NoRetryPolicy(),
+        })
+          .mutate(() => ({ done: true }))
+          .execute(),
+      ).rejects.toThrow(
+        "Retry policy is only supported when the transaction includes retrieve operations.",
       );
-      const elapsed = Date.now() - startTime;
-
-      // Default policy has initialDelayMs: 10, maxDelayMs: 100
-      // First retry delay should be around 10ms
-      expect(elapsed).toBeLessThan(200); // Allow some margin
-    });
-  });
-
-  describe("error handling", () => {
-    it("should throw error from callback immediately without retry", async () => {
-      const { factory, callCount } = createMockUOWFactory([{ success: true }]);
-
-      await expect(
-        executeRestrictedUnitOfWork(
-          async () => {
-            throw new Error("Callback error");
-          },
-          { createUnitOfWork: factory },
-        ),
-      ).rejects.toThrow("Callback error");
-
-      // Should NOT retry non-conflict errors
-      expect(callCount.value).toBe(1); // Only initial attempt
     });
 
-    it("should throw callback error directly", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-      const originalError = new Error("Original error");
-
-      try {
-        await executeRestrictedUnitOfWork(
-          async () => {
-            throw originalError;
-          },
-          {
-            createUnitOfWork: factory,
-            retryPolicy: new NoRetryPolicy(), // Don't retry
-          },
-        );
-        expect.fail("Should have thrown");
-      } catch (error) {
-        // Error should be thrown directly, not wrapped
-        expect(error).toBe(originalError);
-      }
-    });
-  });
-
-  describe("abort signal", () => {
-    it("should throw when aborted before execution", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-      const controller = new AbortController();
-      controller.abort();
+    it("should execute a transaction with serviceCalls as retrieve source", async () => {
+      const compiler = createMockCompiler();
+      const mockUser = {
+        id: FragnoId.fromExternal("1", 1),
+        email: "test@example.com",
+        name: "Test",
+        balance: 100,
+      };
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [[mockUser]],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+      };
+      const decoder = createMockDecoder();
 
-      await expect(
-        executeRestrictedUnitOfWork(
-          async () => {
-            return {};
-          },
-          { createUnitOfWork: factory, signal: controller.signal },
-        ),
-      ).rejects.toThrow("Unit of Work execution aborted");
-    });
+      let currentUow: IUnitOfWork | null = null;
 
-    it("should stop retrying when aborted during retry", async () => {
-      const { factory, callCount } = createMockUOWFactory([
-        { success: false },
-        { success: false },
-        { success: true },
-      ]);
-      const controller = new AbortController();
+      // Service that retrieves
+      const getUserById = () => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .retrieve((uow) => uow.find("users", (b) => b.whereIndex("idx_email")))
+          .transformRetrieve(([users]) => users[0] ?? null)
+          .build();
+      };
 
-      const promise = executeRestrictedUnitOfWork(
-        async ({ executeMutate }) => {
-          if (callCount.value === 2) {
-            controller.abort();
-          }
-          await executeMutate();
-          return {};
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
         },
-        { createUnitOfWork: factory, signal: controller.signal },
-      );
+      })
+        .withServiceCalls(() => [getUserById()])
+        .transform(({ serviceResult: [user] }) => user)
+        .execute();
 
-      await expect(promise).rejects.toThrow("Unit of Work execution aborted");
-      expect(callCount.value).toBeLessThanOrEqual(2);
+      expect(result).toEqual(mockUser);
     });
-  });
-
-  describe("restricted UOW interface", () => {
-    it("should provide access to forSchema", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
 
-      await executeRestrictedUnitOfWork(
-        async ({ forSchema }) => {
-          const uow = forSchema(testSchema);
-          expect(uow).toBeDefined();
-          expect(uow.schema).toBe(testSchema);
-          return {};
-        },
-        { createUnitOfWork: factory },
-      );
-    });
+    it("should execute a transaction with mutate callback using serviceCalls", async () => {
+      const compiler = createMockCompiler();
+      const mockUser = {
+        id: FragnoId.fromExternal("1", 1),
+        email: "test@example.com",
+        name: "Test",
+        balance: 100,
+      };
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [[mockUser]],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [BigInt(2)] }),
+      };
+      const decoder = createMockDecoder();
 
-    it("should allow creating entities via forSchema", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
+      let currentUow: IUnitOfWork | null = null;
 
-      const result = await executeRestrictedUnitOfWork(
-        async ({ forSchema, executeRetrieve, executeMutate }) => {
-          const uow = forSchema(testSchema);
-          await executeRetrieve();
+      // Service that retrieves
+      const getUserById = () => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .retrieve((uow) => uow.find("users", (b) => b.whereIndex("idx_email")))
+          .transformRetrieve(([users]) => users[0] ?? null)
+          .build();
+      };
 
-          const userId = uow.create("users", {
-            id: "user-123",
-            email: "test@example.com",
-            name: "Test",
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
+        },
+      })
+        .withServiceCalls(() => [getUserById()])
+        .mutate(({ forSchema, serviceIntermediateResult: [user] }) => {
+          if (!user) {
+            return { ok: false as const };
+          }
+          const newUserId = forSchema(testSchema).create("users", {
+            email: "new@example.com",
+            name: "New User",
             balance: 0,
           });
+          return { ok: true as const, newUserId };
+        })
+        .execute();
 
-          await executeMutate();
+      expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.newUserId).toBeInstanceOf(FragnoId);
+      }
+    });
 
-          return { userId };
-        },
-        { createUnitOfWork: factory },
-      );
+    it("should execute a transaction with transform callback", async () => {
+      const compiler = createMockCompiler();
+      const mockUser = {
+        id: FragnoId.fromExternal("1", 1),
+        email: "test@example.com",
+        name: "Test",
+        balance: 100,
+      };
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [[mockUser]],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [BigInt(2)] }),
+      };
+      const decoder = createMockDecoder();
 
-      expect(result.userId).toBeInstanceOf(FragnoId);
-      expect(result.userId.externalId).toBe("user-123");
-    });
-  });
+      let currentUow: IUnitOfWork | null = null;
 
-  describe("promise awaiting in callback result", () => {
-    it("should await promises in result object (1 level deep)", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
+      // Service that retrieves
+      const getUserById = () => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .retrieve((uow) => uow.find("users", (b) => b.whereIndex("idx_email")))
+          .transformRetrieve(([users]) => users[0] ?? null)
+          .build();
+      };
 
-      const result = await executeRestrictedUnitOfWork(
-        async ({ executeMutate }) => {
-          await executeMutate();
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
+        },
+      })
+        .withServiceCalls(() => [getUserById()])
+        .mutate(({ forSchema, serviceIntermediateResult: [user] }) => {
+          if (!user) {
+            return { created: false as const };
+          }
+          const newUserId = forSchema(testSchema).create("users", {
+            email: "new@example.com",
+            name: "New User",
+            balance: 0,
+          });
+          return { created: true as const, newUserId };
+        })
+        .transform(({ serviceResult: [user], mutateResult }) => {
           return {
-            userId: Promise.resolve("user-123"),
-            profileId: Promise.resolve("profile-456"),
-            status: "completed",
+            originalUser: user,
+            mutationResult: mutateResult,
+            summary: "Transaction completed",
           };
-        },
-        { createUnitOfWork: factory },
-      );
+        })
+        .execute();
 
-      expect(result).toEqual({
-        userId: "user-123",
-        profileId: "profile-456",
-        status: "completed",
-      });
+      expect(result.summary).toBe("Transaction completed");
+      expect(result.originalUser).toEqual(mockUser);
+      expect(result.mutationResult?.created).toBe(true);
     });
 
-    it("should await promises in result array", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-
-      const result = await executeRestrictedUnitOfWork(
-        async ({ executeMutate }) => {
-          await executeMutate();
-          return [Promise.resolve(1), Promise.resolve(2), 3];
-        },
-        { createUnitOfWork: factory },
-      );
+    it("should execute a transaction with serviceCalls (service composition)", async () => {
+      const compiler = createMockCompiler();
+      const mockUser = {
+        id: FragnoId.fromExternal("1", 1),
+        email: "test@example.com",
+        name: "Test",
+        balance: 100,
+      };
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [[mockUser]],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [BigInt(2)] }),
+      };
+      const decoder = createMockDecoder();
 
-      expect(result).toEqual([1, 2, 3]);
-    });
+      let currentUow: IUnitOfWork | null = null;
 
-    it("should await direct promise result", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
+      // Simulate a service method that returns a TxResult
+      const getUserById = (userId: string) => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .retrieve((uow) =>
+            uow.find("users", (b) => b.whereIndex("primary", (eb) => eb("id", "=", userId))),
+          )
+          .transformRetrieve(([users]) => users[0] ?? null)
+          .build();
+      };
 
-      const result = await executeRestrictedUnitOfWork(
-        async ({ executeMutate }) => {
-          await executeMutate();
-          return Promise.resolve({ data: "test" });
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
         },
-        { createUnitOfWork: factory },
-      );
-
-      expect(result).toEqual({ data: "test" });
+      })
+        .withServiceCalls(() => [getUserById("1")])
+        .mutate(({ forSchema, serviceIntermediateResult: [user] }) => {
+          if (!user) {
+            return { ok: false as const };
+          }
+          const orderId = forSchema(testSchema).create("users", {
+            email: "order@example.com",
+            name: "Order",
+            balance: 0,
+          });
+          return { ok: true as const, orderId, forUser: user.email };
+        })
+        .execute();
+
+      expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.forUser).toBe("test@example.com");
+        expect(result.orderId).toBeInstanceOf(FragnoId);
+      }
     });
 
-    it("should NOT await nested promises (only 1 level deep)", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
+    it("should type check serviceCalls with undefined (optional service pattern)", async () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [BigInt(1)] }),
+      };
+      const decoder = createMockDecoder();
 
-      const result = await executeRestrictedUnitOfWork(
-        async ({ executeMutate }) => {
-          await executeMutate();
-          return {
-            nested: {
-              promise: Promise.resolve("still-a-promise"),
-            },
-          };
-        },
-        { createUnitOfWork: factory },
-      );
+      // Simulate optional service pattern: optionalService?.method()
+      // When optionalService is undefined, this evaluates to undefined
+      // Use type assertion to prevent TypeScript from narrowing to literal undefined
+      const optionalService = undefined as
+        | { getUser: () => TxResult<{ name: string }, { name: string }> }
+        | undefined;
 
-      // The nested promise should still be a promise
-      expect(result.nested.promise).toBeInstanceOf(Promise);
+      // This test demonstrates that serviceCalls can contain TxResult | undefined
+      // This is useful for optional service patterns like: optionalService?.method()
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
+      })
+        .withServiceCalls(() => [optionalService?.getUser()])
+        .mutate(({ forSchema, serviceIntermediateResult: [maybeUser] }) => {
+          // maybeUser is typed as { name: string } | undefined
+          // This demonstrates the optional chaining pattern works correctly
+          expectTypeOf(maybeUser).toEqualTypeOf<{ name: string } | undefined>();
+          if (!maybeUser) {
+            const userId = forSchema(testSchema).create("users", {
+              email: "fallback@example.com",
+              name: "Fallback User",
+              balance: 0,
+            });
+            return { hadUser: false as const, userId };
+          }
+          return { hadUser: true as const, userName: maybeUser.name };
+        })
+        .execute();
+
+      // Since optionalService was undefined, maybeUser was undefined, so we hit the fallback path
+      expect(result.hadUser).toBe(false);
+      if (!result.hadUser) {
+        expect(result.userId).toBeInstanceOf(FragnoId);
+      }
     });
 
-    it("should handle mixed types in result", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
+    it("should handle serviceCalls with mix of TxResult and undefined", async () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [BigInt(1)] }),
+      };
+      const decoder = createMockDecoder();
 
-      const result = await executeRestrictedUnitOfWork(
-        async ({ executeMutate }) => {
-          await executeMutate();
-          return {
-            promise: Promise.resolve("resolved"),
-            number: 42,
-            string: "test",
-            boolean: true,
-            null: null,
-            undefined: undefined,
-            object: { nested: "value" },
-          };
-        },
-        { createUnitOfWork: factory },
-      );
+      let currentUow: IUnitOfWork | null = null;
 
-      expect(result).toEqual({
-        promise: "resolved",
-        number: 42,
-        string: "test",
-        boolean: true,
-        null: null,
-        undefined: undefined,
-        object: { nested: "value" },
-      });
-    });
+      // Type for the created data returned by the defined service
+      type CreatedData = { userId: FragnoId; generatedCode: string };
+      // Type for the extra data that would be returned by the optional service
+      type ExtraData = { extraCode: string; timestamp: number };
+
+      // One defined service with mutation that returns data
+      const definedService = {
+        createUserAndReturnCode: (): TxResult<CreatedData, CreatedData> =>
+          createServiceTxBuilder(testSchema, currentUow!)
+            .mutate(({ uow }): CreatedData => {
+              const userId = uow.create("users", {
+                email: "created@example.com",
+                name: "Created User",
+                balance: 0,
+              });
+              // Return arbitrary data from the mutation
+              return { userId, generatedCode: "ABC123" };
+            })
+            .build(),
+      };
 
-    it("should await promises even after retries", async () => {
-      const { factory, callCount } = createMockUOWFactory([{ success: false }, { success: true }]);
+      // Optional service that would also return mutation data
+      const optionalService = undefined as
+        | {
+            generateExtra: () => TxResult<ExtraData, ExtraData>;
+          }
+        | undefined;
+
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
+        },
+      })
+        .withServiceCalls(
+          () =>
+            [definedService.createUserAndReturnCode(), optionalService?.generateExtra()] as const,
+        )
+        .mutate(({ forSchema, serviceIntermediateResult }) => {
+          // serviceIntermediateResult contains the mutation results from service calls
+          // (since service calls have no retrieveSuccess, the mutate result becomes the retrieve result for dependents)
+          const [createdData, maybeExtra] = serviceIntermediateResult;
+
+          // Type checks: createdData should have userId and generatedCode
+          // maybeExtra should be ExtraData | undefined
+          expectTypeOf(createdData).toEqualTypeOf<CreatedData>();
+          expectTypeOf(maybeExtra).toEqualTypeOf<ExtraData | undefined>();
+
+          forSchema(testSchema).create("users", {
+            email: "handler@example.com",
+            name: "Handler User",
+            balance: 0,
+          });
 
-      const result = await executeRestrictedUnitOfWork(
-        async ({ executeMutate }) => {
-          await executeMutate();
           return {
-            attempt: callCount.value,
-            data: Promise.resolve("final-result"),
+            depCode: createdData.generatedCode,
+            hadExtra: maybeExtra !== undefined,
           };
-        },
-        { createUnitOfWork: factory },
-      );
+        })
+        .transform(({ serviceResult, serviceIntermediateResult, mutateResult }) => {
+          // Verify serviceResult types - these are the FINAL results from serviceCalls
+          const [finalCreatedData, maybeFinalExtra] = serviceResult;
 
-      expect(result).toEqual({
-        attempt: 2,
-        data: "final-result",
-      });
-    });
+          // Type check: serviceResult should have same structure
+          // The final result is CreatedData (since there's no transform callback on the dep)
+          expectTypeOf(finalCreatedData).toEqualTypeOf<CreatedData>();
+          expectTypeOf(maybeFinalExtra).toEqualTypeOf<ExtraData | undefined>();
 
-    it("should handle complex objects with multiple promises at top level", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
+          // serviceIntermediateResult should still be accessible in transform
+          const [_retrieveData, maybeRetrieveExtra] = serviceIntermediateResult;
+          expectTypeOf(maybeRetrieveExtra).toEqualTypeOf<ExtraData | undefined>();
 
-      const result = await executeRestrictedUnitOfWork(
-        async ({ executeMutate }) => {
-          await executeMutate();
           return {
-            userId: Promise.resolve("user-1"),
-            email: Promise.resolve("test@example.com"),
-            count: Promise.resolve(100),
-            active: Promise.resolve(true),
-            metadata: {
-              timestamp: Date.now(),
-              version: 1,
-            },
+            ...mutateResult,
+            finalDepUserId: finalCreatedData.userId,
+            finalDepCode: finalCreatedData.generatedCode,
+            extraWasUndefined: maybeFinalExtra === undefined,
           };
-        },
-        { createUnitOfWork: factory },
-      );
-
-      expect(typeof result.userId).toBe("string");
-      expect(result.userId).toBe("user-1");
-      expect(typeof result.email).toBe("string");
-      expect(result.email).toBe("test@example.com");
-      expect(typeof result.count).toBe("number");
-      expect(result.count).toBe(100);
-      expect(typeof result.active).toBe("boolean");
-      expect(result.active).toBe(true);
-      expect(typeof result.metadata.timestamp).toBe("number");
-      expect(result.metadata.version).toBe(1);
+        })
+        .execute();
+
+      // Verify runtime behavior
+      expect(result.depCode).toBe("ABC123");
+      expect(result.hadExtra).toBe(false);
+      expect(result.finalDepCode).toBe("ABC123");
+      expect(result.extraWasUndefined).toBe(true);
+      expect(result.finalDepUserId).toBeInstanceOf(FragnoId);
     });
 
-    it("should handle empty object result", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-
-      const result = await executeRestrictedUnitOfWork(
-        async ({ executeMutate }) => {
-          await executeMutate();
-          return {};
+    it("should retry on concurrency conflict", async () => {
+      const compiler = createMockCompiler();
+      let mutationAttempts = 0;
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [],
+        executeMutationPhase: async () => {
+          mutationAttempts++;
+          if (mutationAttempts < 3) {
+            return { success: false };
+          }
+          return { success: true, createdInternalIds: [] };
         },
-        { createUnitOfWork: factory },
-      );
+      };
+      const decoder = createMockDecoder();
 
-      expect(result).toEqual({});
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
+        retryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 5, initialDelayMs: 1 }),
+      })
+        .retrieve(({ forSchema }) => forSchema(testSchema).find("users"))
+        .mutate(({ forSchema }) => {
+          forSchema(testSchema).create("users", {
+            email: "test@example.com",
+            name: "Test",
+            balance: 0,
+          });
+          return { createdAt: Date.now() };
+        })
+        .execute();
+
+      // Verify we retried the correct number of times
+      expect(mutationAttempts).toBe(3);
+      // Verify we got a result
+      expect(result.createdAt).toBeGreaterThan(0);
     });
 
-    it("should handle primitive result types", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
+    it("should throw ConcurrencyConflictError when retries are exhausted", async () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [],
+        executeMutationPhase: async () => ({ success: false }),
+      };
+      const decoder = createMockDecoder();
 
-      const stringResult = await executeRestrictedUnitOfWork(
-        async ({ executeMutate }) => {
-          await executeMutate();
-          return "test-string";
-        },
-        { createUnitOfWork: factory },
-      );
+      await expect(
+        createHandlerTxBuilder({
+          createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
+          retryPolicy: new NoRetryPolicy(),
+        })
+          .retrieve(({ forSchema }) => forSchema(testSchema).find("users"))
+          .mutate(() => ({ done: true }))
+          .execute(),
+      ).rejects.toThrow(ConcurrencyConflictError);
+    });
 
-      expect(stringResult).toBe("test-string");
+    it("should abort when signal is aborted", async () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+      };
+      const decoder = createMockDecoder();
 
-      const { factory: factory2 } = createMockUOWFactory([{ success: true }]);
-      const numberResult = await executeRestrictedUnitOfWork(
-        async ({ executeMutate }) => {
-          await executeMutate();
-          return 42;
-        },
-        { createUnitOfWork: factory2 },
-      );
+      const controller = new AbortController();
+      controller.abort();
 
-      expect(numberResult).toBe(42);
+      await expect(
+        createHandlerTxBuilder({
+          createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
+          signal: controller.signal,
+        })
+          .mutate(() => ({ done: true }))
+          .execute(),
+      ).rejects.toThrow("Transaction execution aborted");
     });
-  });
 
-  describe("tuple return types", () => {
-    it("should await promises in tuple and preserve tuple structure", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
+    it("should create fresh UOW on each retry attempt", async () => {
+      const compiler = createMockCompiler();
+      let callCount = 0;
+      let mutationAttempts = 0;
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [],
+        executeMutationPhase: async () => {
+          mutationAttempts++;
+          if (mutationAttempts < 3) {
+            return { success: false };
+          }
+          return { success: true, createdInternalIds: [] };
+        },
+      };
+      const decoder = createMockDecoder();
 
-      const result = await executeRestrictedUnitOfWork(
-        async ({ executeMutate }) => {
-          await executeMutate();
-          // Return a tuple with promises
-          return [Promise.resolve("user-123"), Promise.resolve(42)] as const;
+      await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          callCount++;
+          return createUnitOfWork(compiler, executor, decoder);
         },
-        { createUnitOfWork: factory },
-      );
+        retryPolicy: new LinearBackoffRetryPolicy({ maxRetries: 3, delayMs: 1 }),
+      })
+        .retrieve(({ forSchema }) => forSchema(testSchema).find("users"))
+        .mutate(({ forSchema }) => {
+          forSchema(testSchema).create("users", {
+            email: "test@example.com",
+            name: "Test",
+            balance: 0,
+          });
+        })
+        .execute();
 
-      // Runtime behavior: promises should be awaited
-      expect(result).toEqual(["user-123", 42]);
-      expect(result[0]).toBe("user-123");
-      expect(result[1]).toBe(42);
+      // Verify factory was called for each attempt (initial + 2 retries)
+      expect(callCount).toBe(3);
     });
 
-    it("should handle tuple with mixed promise and non-promise values", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
+    it("should abort when signal is aborted during retry delay", async () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [],
+        executeMutationPhase: async () => ({ success: false }),
+      };
+      const decoder = createMockDecoder();
+
+      const controller = new AbortController();
 
-      const result = await executeRestrictedUnitOfWork(
-        async ({ executeMutate }) => {
-          await executeMutate();
-          // Tuple with mixed types
-          return [Promise.resolve("first"), "second", Promise.resolve(3)] as const;
-        },
-        { createUnitOfWork: factory },
-      );
+      // Abort after first attempt during retry delay
+      setTimeout(() => controller.abort(), 50);
 
-      expect(result).toEqual(["first", "second", 3]);
-      expect(result[0]).toBe("first");
-      expect(result[1]).toBe("second");
-      expect(result[2]).toBe(3);
+      await expect(
+        createHandlerTxBuilder({
+          createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
+          retryPolicy: new LinearBackoffRetryPolicy({ maxRetries: 5, delayMs: 100 }),
+          signal: controller.signal,
+        })
+          .retrieve(({ forSchema }) => forSchema(testSchema).find("users"))
+          .mutate(() => ({ done: true }))
+          .execute(),
+      ).rejects.toThrow("Transaction execution aborted");
     });
 
-    it("should handle Promise.all pattern with tuple", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
-
-      const result = await executeRestrictedUnitOfWork(
-        async ({ executeMutate }) => {
-          await executeMutate();
-          // Simulate the pattern from db-fragment-integration.test.ts
-          const userPromise = Promise.resolve({ id: "user-1", name: "John" });
-          const ordersPromise = Promise.resolve([
-            { id: "order-1", total: 100 },
-            { id: "order-2", total: 200 },
-          ]);
-          return await Promise.all([userPromise, ordersPromise]);
-        },
-        { createUnitOfWork: factory },
-      );
+    it("should pass serviceResult to transform callback with final results", async () => {
+      const compiler = createMockCompiler();
+      const mockUser = {
+        id: FragnoId.fromExternal("1", 1),
+        email: "test@example.com",
+        name: "Test",
+        balance: 100,
+      };
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [[mockUser]],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [BigInt(2)] }),
+      };
+      const decoder = createMockDecoder();
 
-      // Runtime behavior
-      expect(result).toHaveLength(2);
-      expect(result[0]).toEqual({ id: "user-1", name: "John" });
-      expect(result[1]).toEqual([
-        { id: "order-1", total: 100 },
-        { id: "order-2", total: 200 },
-      ]);
-
-      // Type check: result should be [{ id: string; name: string }, { id: string; total: number }[]]
-      // But with current implementation, it's incorrectly typed as an array union
-      const [user, orders] = result;
-      expect(user).toBeDefined();
-      expect(orders).toBeDefined();
-    });
+      let currentUow: IUnitOfWork | null = null;
 
-    it("should handle array (not tuple) with promises", async () => {
-      const { factory } = createMockUOWFactory([{ success: true }]);
+      // Service that retrieves and mutates
+      const getUserAndUpdateBalance = (userId: string) => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .retrieve((uow) =>
+            uow.find("users", (b) => b.whereIndex("primary", (eb) => eb("id", "=", userId))),
+          )
+          .transformRetrieve(([users]) => users[0] ?? null)
+          .mutate(({ uow, retrieveResult: user }) => {
+            expect(user).toEqual(mockUser);
+            expectTypeOf(user).toEqualTypeOf<typeof mockUser>();
+            if (!user) {
+              return { updated: false as const };
+            }
+            uow.update("users", user.id, (b) => b.set({ balance: user.balance + 100 }).check());
+            return { updated: true as const, newBalance: user.balance + 100 };
+          })
+          .build();
+      };
 
-      const result = await executeRestrictedUnitOfWork(
-        async ({ executeMutate }) => {
-          await executeMutate();
-          // Regular array (not a tuple)
-          const items = [Promise.resolve(1), Promise.resolve(2), Promise.resolve(3)];
-          return items;
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
         },
-        { createUnitOfWork: factory },
-      );
+      })
+        .withServiceCalls(() => [getUserAndUpdateBalance("1")])
+        .transform(
+          ({ serviceResult: [depResult], serviceIntermediateResult: [depRetrieveResult] }) => {
+            expect(depResult).toEqual({
+              updated: true,
+              newBalance: 200,
+            });
+
+            expect(depRetrieveResult).toEqual(mockUser);
+
+            const dep = depResult;
+            return {
+              depUpdated: dep.updated,
+              depNewBalance: dep.updated ? dep.newBalance : null,
+            };
+          },
+        )
+        .execute();
 
-      expect(result).toEqual([1, 2, 3]);
-      expect(result).toHaveLength(3);
+      expect(result.depUpdated).toBe(true);
+      expect(result.depNewBalance).toBe(200);
     });
   });
 
-  describe("unhandled rejection handling", () => {
-    it("should not cause unhandled rejection when service method awaits retrievalPhase and executeRetrieve fails", async () => {
-      const settingsSchema = schema((s) =>
-        s.addTable("settings", (t) =>
-          t
-            .addColumn("id", idColumn())
-            .addColumn("key", "string")
-            .addColumn("value", "string")
-            .createIndex("unique_key", ["key"], { unique: true }),
-        ),
-      );
-
-      // Create executor that throws "table does not exist" error
-      const failingExecutor: UOWExecutor<unknown, unknown> = {
-        executeRetrievalPhase: async () => {
-          throw new Error('relation "settings" does not exist');
-        },
+  describe("return type priority", () => {
+    it("should return transform result when transform callback is provided", async () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [],
         executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
       };
+      const decoder = createMockDecoder();
 
-      const factory = () =>
-        createUnitOfWork(createMockCompiler(), failingExecutor, createMockDecoder());
-
-      const deferred = Promise.withResolvers<string>();
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
+      })
+        .retrieve(() => {
+          // Empty retrieve - defaults to empty array
+        })
+        .transformRetrieve((ctx) => {
+          expectTypeOf(ctx).toEqualTypeOf<unknown[]>();
+
+          return "retrieveSuccess result" as const;
+        })
+        .mutate((ctx) => {
+          expectTypeOf(ctx.retrieveResult).toEqualTypeOf<"retrieveSuccess result">();
+
+          return "mutate result" as const;
+        })
+        .transform((ctx) => {
+          expectTypeOf(ctx.retrieveResult).toEqualTypeOf<"retrieveSuccess result">();
+          // mutateResult is NOT | undefined because mutate callback IS provided
+          expectTypeOf(ctx.mutateResult).toEqualTypeOf<"mutate result">();
+          // serviceResult and serviceIntermediateResult are empty tuples since no service calls callback
+          expectTypeOf(ctx.serviceResult).toEqualTypeOf<readonly []>();
+          expectTypeOf(ctx.serviceIntermediateResult).toEqualTypeOf<readonly []>();
+
+          return "success result" as const;
+        })
+        .execute();
+
+      expect(result).toBe("success result");
+    });
 
-      // Service method that awaits retrievalPhase (simulating settingsService.get())
-      const getSettingValue = async (typedUow: TypedUnitOfWork<typeof settingsSchema>) => {
-        const uow = typedUow.find("settings", (b) =>
-          b.whereIndex("unique_key", (eb) => eb("key", "=", "version")),
-        );
-        const [results] = await uow.retrievalPhase;
-        return results?.[0];
+    it("should return mutate result when no transform callback", async () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
       };
+      const decoder = createMockDecoder();
 
-      // Execute with executeRestrictedUnitOfWork
-      try {
-        await executeRestrictedUnitOfWork(
-          async ({ forSchema, executeRetrieve }) => {
-            const uow = forSchema(settingsSchema);
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
+      })
+        .transformRetrieve(() => "retrieveSuccess result")
+        .mutate(() => "mutate result")
+        .execute();
 
-            const settingPromise = getSettingValue(uow);
+      expect(result).toBe("mutate result");
+    });
 
-            // Execute retrieval - this will fail
-            await executeRetrieve();
+    it("should return transformRetrieve result when no mutate or transform", async () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+      };
+      const decoder = createMockDecoder();
 
-            // Won't reach here
-            return await settingPromise;
-          },
-          {
-            createUnitOfWork: factory,
-            retryPolicy: new NoRetryPolicy(),
-          },
-        );
-        expect.fail("Should have thrown an error");
-      } catch (error) {
-        // The error should be thrown directly (not wrapped) since it's not a concurrency conflict
-        expect(error).toBeInstanceOf(Error);
-        expect((error as Error).message).toContain('relation "settings" does not exist');
-        deferred.resolve((error as Error).message);
-      }
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
+      })
+        .transformRetrieve(() => "retrieveSuccess result")
+        .execute();
 
-      // Verify no unhandled rejection occurred
-      // If the test completes without throwing, the promise rejection was properly handled
-      expect(await deferred.promise).toContain('relation "settings" does not exist');
+      expect(result).toBe("retrieveSuccess result");
     });
-  });
 
-  describe("executeTxArray", () => {
-    it("should execute multiple service promises and await them before mutations", async () => {
+    it("should return serviceCalls final results when no local callbacks", async () => {
       const compiler = createMockCompiler();
+      const mockUser = {
+        id: FragnoId.fromExternal("1", 1),
+        email: "test@example.com",
+        name: "Test",
+        balance: 100,
+      };
       const executor: UOWExecutor<unknown, unknown> = {
-        executeRetrievalPhase: async () => [],
-        executeMutationPhase: async () => ({
-          success: true,
-          createdInternalIds: [],
-        }),
+        executeRetrievalPhase: async () => [[mockUser]],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
       };
       const decoder = createMockDecoder();
 
-      let retrievalExecuted = false;
-      let servicesResolved = false;
-
-      const result = await executeTxArray(
-        () => [
-          Promise.resolve().then(async () => {
-            await new Promise((resolve) => setTimeout(resolve, 10));
-            servicesResolved = true;
-            return { result1: "value1" };
-          }),
-          Promise.resolve().then(async () => {
-            await new Promise((resolve) => setTimeout(resolve, 10));
-            return { result2: "value2" };
-          }),
-        ],
-        {
-          createUnitOfWork: () => {
-            const uow = createUnitOfWork(compiler, executor, decoder);
-            const originalExecuteRetrieve = uow.executeRetrieve.bind(uow);
-            uow.executeRetrieve = async () => {
-              retrievalExecuted = true;
-              return originalExecuteRetrieve();
-            };
-            return uow;
-          },
+      let currentUow: IUnitOfWork | null = null;
+
+      // Service that just retrieves
+      const getUser = () => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .retrieve((uow) => uow.find("users", (b) => b.whereIndex("idx_email")))
+          .transformRetrieve(([users]) => users[0] ?? null)
+          .build();
+      };
+
+      // executeTx with only serviceCalls - should return serviceCalls' final results
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
         },
-      );
+      })
+        .withServiceCalls(() => [getUser()])
+        .execute();
 
-      expect(retrievalExecuted).toBe(true);
-      expect(servicesResolved).toBe(true);
-      expect(result).toEqual([{ result1: "value1" }, { result2: "value2" }]);
+      expect(result).toEqual([mockUser]);
     });
+  });
 
-    it("should retry on concurrency conflict", async () => {
+  describe("serviceResult vs serviceIntermediateResult", () => {
+    it("serviceIntermediateResult in mutate should contain transformRetrieve results", async () => {
       const compiler = createMockCompiler();
-      let attemptCount = 0;
+      const mockUser = {
+        id: FragnoId.fromExternal("1", 1),
+        email: "test@example.com",
+        name: "Test",
+        balance: 100,
+      };
       const executor: UOWExecutor<unknown, unknown> = {
-        executeRetrievalPhase: async () => [],
-        executeMutationPhase: async () => {
-          attemptCount++;
-          if (attemptCount < 2) {
-            return { success: false };
-          }
-          return {
-            success: true,
-            createdInternalIds: [],
-          };
-        },
+        executeRetrievalPhase: async () => [[mockUser]],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
       };
       const decoder = createMockDecoder();
 
-      const result = await executeTxArray(() => [Promise.resolve({ result: "value" })], {
-        createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
-        retryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 3, initialDelayMs: 1 }),
-      });
+      let currentUow: IUnitOfWork | null = null;
+      let capturedServiceIntermediateResult: unknown[] = [];
+
+      const getUserById = () => {
+        return (
+          createServiceTxBuilder(testSchema, currentUow!)
+            .retrieve((uow) => uow.find("users", (b) => b.whereIndex("idx_email")))
+            // This transformRetrieve transforms the result
+            .transformRetrieve(([users]) => ({ transformed: true, user: users[0] }))
+            .build()
+        );
+      };
+
+      await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
+        },
+      })
+        .withServiceCalls(() => [getUserById()])
+        .mutate(({ serviceIntermediateResult }) => {
+          // Should receive the transformed (transformRetrieve) result
+          capturedServiceIntermediateResult = [...serviceIntermediateResult];
+          return { done: true };
+        })
+        .execute();
 
-      expect(attemptCount).toBe(2);
-      expect(result).toEqual([{ result: "value" }]);
+      expect(capturedServiceIntermediateResult[0]).toEqual({ transformed: true, user: mockUser });
     });
 
-    it("should throw if retries exhausted", async () => {
+    it("serviceResult in transform should contain final (mutate) results", async () => {
       const compiler = createMockCompiler();
+      const mockUser = {
+        id: FragnoId.fromExternal("1", 1),
+        email: "test@example.com",
+        name: "Test",
+        balance: 100,
+      };
       const executor: UOWExecutor<unknown, unknown> = {
-        executeRetrievalPhase: async () => [],
-        executeMutationPhase: async () => ({ success: false }),
+        executeRetrievalPhase: async () => [[mockUser]],
+        executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
       };
       const decoder = createMockDecoder();
 
-      await expect(
-        executeTxArray(() => [Promise.resolve({ result: "value" })], {
-          createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
-          retryPolicy: new NoRetryPolicy(),
-        }),
-      ).rejects.toThrow("optimistic concurrency conflict");
+      let currentUow: IUnitOfWork | null = null;
+      let capturedServiceResult: unknown[] = [];
+
+      const getUserById = () => {
+        return (
+          createServiceTxBuilder(testSchema, currentUow!)
+            .retrieve((uow) => uow.find("users", (b) => b.whereIndex("idx_email")))
+            .transformRetrieve(([users]) => users[0])
+            // This mutate returns a different result
+            .mutate(({ retrieveResult: user }) => ({ mutated: true, userId: user?.id }))
+            .build()
+        );
+      };
+
+      await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
+        },
+      })
+        .withServiceCalls(() => [getUserById()])
+        .transform(({ serviceResult }) => {
+          // Should receive the mutate result (final), not transformRetrieve result
+          capturedServiceResult = [...serviceResult];
+          return { done: true };
+        })
+        .execute();
+
+      expect(capturedServiceResult[0]).toEqual({ mutated: true, userId: mockUser.id });
     });
-  });
 
-  describe("executeTxCallbacks", () => {
-    it("should execute retrieve and mutate callbacks in order", async () => {
+    it("serviceResult in transform should contain mutateResult for mutate-only serviceCalls (via processTxResultAfterMutate)", async () => {
+      // This test exercises the buggy code path in processTxResultAfterMutate:
+      // When a nested TxResult has a transform callback and its serviceCall is mutate-only,
+      // the transform callback should receive the mutateResult in
+      // serviceResult, NOT the empty array.
+      //
+      // The key is that the nested service itself (wrapperService) has a transform callback,
+      // so processTxResultAfterMutate is called for it.
       const compiler = createMockCompiler();
       const executor: UOWExecutor<unknown, unknown> = {
         executeRetrievalPhase: async () => [],
         executeMutationPhase: async () => ({
           success: true,
-          createdInternalIds: [],
+          createdInternalIds: [BigInt(1)],
         }),
       };
       const decoder = createMockDecoder();
 
-      const executionOrder: string[] = [];
+      let currentUow: IUnitOfWork | null = null;
+      let capturedServiceIntermediateResultInNestedTransform: unknown[] = [];
+
+      // Mutate-only service - no retrieve or transformRetrieve callbacks
+      const createItem = () => {
+        return (
+          createServiceTxBuilder(testSchema, currentUow!)
+            // NO retrieve or transformRetrieve - this is a mutate-only dep
+            .mutate(({ uow }) => {
+              const itemId = uow.create("users", {
+                email: "new-item@example.com",
+                name: "New Item",
+                balance: 0,
+              });
+              return { created: true, itemId };
+            })
+            .build()
+        );
+      };
 
-      const result = await executeTxCallbacks(
-        {
-          retrieve: ({ forSchema }) => {
-            executionOrder.push("retrieve");
-            const uow = forSchema(testSchema);
-            uow.find("users", (b) => b.whereIndex("idx_email"));
-            return { servicePromise: Promise.resolve({ value: "result" }) };
-          },
-          mutate: ({ forSchema }, { servicePromise }) => {
-            executionOrder.push("mutate");
-            const uow = forSchema(testSchema);
-            uow.create("users", { email: "test@example.com", name: "Test", balance: 0 });
-            return servicePromise;
-          },
-        },
-        {
-          createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
+      // Wrapper service that has a transform callback and uses createItem as a dep
+      // This forces processTxResultAfterMutate to be called for this TxResult
+      const wrapperService = () => {
+        return (
+          createServiceTxBuilder(testSchema, currentUow!)
+            .withServiceCalls(() => [createItem()] as const)
+            // NO mutate callback - just pass through
+            // The transform callback is the key: it makes processTxResultAfterMutate get called
+            .transform(({ serviceResult, serviceIntermediateResult }) => {
+              capturedServiceIntermediateResultInNestedTransform = [...serviceIntermediateResult];
+              // serviceResult should equal serviceIntermediateResult since dep has no transform callback
+              expect(serviceResult[0]).toEqual(serviceIntermediateResult[0]);
+              return { wrapped: true, innerResult: serviceIntermediateResult[0] };
+            })
+            .build()
+        );
+      };
+
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
         },
-      );
+      })
+        .withServiceCalls(() => [wrapperService()] as const)
+        .transform(({ serviceResult: [wrapperResult] }) => wrapperResult)
+        .execute();
+
+      // The wrapper service's transform callback should have received the mutateResult, NOT empty array
+      expect(capturedServiceIntermediateResultInNestedTransform[0]).toEqual({
+        created: true,
+        itemId: expect.any(FragnoId),
+      });
+      // Verify it's not the empty array sentinel
+      expect(capturedServiceIntermediateResultInNestedTransform[0]).not.toEqual([]);
 
-      expect(executionOrder).toEqual(["retrieve", "mutate"]);
-      expect(result).toEqual({ value: "result" });
+      // And the handler should get the wrapped result
+      expect(result).toEqual({
+        wrapped: true,
+        innerResult: { created: true, itemId: expect.any(FragnoId) },
+      });
     });
+  });
 
-    it("should handle retrieve-only transactions", async () => {
+  describe("nested TxResult serviceCalls (service composition)", () => {
+    it("should collect nested serviceCalls in dependency order", async () => {
+      // Simpler test to verify collectAllTxResults works correctly
       const compiler = createMockCompiler();
+      const mockUser = {
+        id: FragnoId.fromExternal("user-1", 1),
+        email: "test@example.com",
+        name: "Test User",
+        balance: 100,
+      };
+      let retrievePhaseExecuted = false;
       const executor: UOWExecutor<unknown, unknown> = {
-        executeRetrievalPhase: async () => [
-          [
-            {
-              id: FragnoId.fromExternal("1", 1),
-              email: "test@example.com",
-              name: "Test",
-              balance: 0,
-            },
-          ],
-        ],
+        executeRetrievalPhase: async () => {
+          retrievePhaseExecuted = true;
+          return [[mockUser]];
+        },
         executeMutationPhase: async () => ({
           success: true,
           createdInternalIds: [],
@@ -1462,26 +1284,80 @@ describe("executeRestrictedUnitOfWork", () => {
       };
       const decoder = createMockDecoder();
 
-      const result = await executeTxCallbacks(
-        {
-          retrieve: ({ forSchema }) => {
-            const uow = forSchema(testSchema);
-            uow.find("users", (b) => b.whereIndex("idx_email"));
-            return { users: [] };
-          },
-        },
-        {
-          createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
-        },
-      );
+      let currentUow: IUnitOfWork | null = null;
+      let getUserByIdCalled = false;
+      let validateUserCalled = false;
+
+      // Simple service that retrieves - no nested serviceCalls
+      const getUserById = (userId: string) => {
+        getUserByIdCalled = true;
+        if (!currentUow) {
+          throw new Error("currentUow is null in getUserById!");
+        }
+        return createServiceTxBuilder(testSchema, currentUow)
+          .retrieve((uow) =>
+            uow.find("users", (b) => b.whereIndex("primary", (eb) => eb("id", "=", userId))),
+          )
+          .transformRetrieve(([users]) => users[0] ?? null)
+          .build();
+      };
 
-      expect(result).toEqual({ users: [] });
-    });
+      // Service with serviceCalls - depends on getUserById
+      const validateUser = (userId: string) => {
+        validateUserCalled = true;
+        if (!currentUow) {
+          throw new Error("currentUow is null in validateUser!");
+        }
+        return (
+          createServiceTxBuilder(testSchema, currentUow)
+            .withServiceCalls(() => [getUserById(userId)] as const)
+            // mutate callback receives serviceIntermediateResult
+            .mutate(({ serviceIntermediateResult: [user] }) => {
+              return { valid: user !== null, user };
+            })
+            .build()
+        );
+      };
+
+      // Handler calls executeTx with serviceCalls containing validateUser
+      // This tests 2-level nesting: handler -> validateUser -> getUserById
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
+        },
+      })
+        .withServiceCalls(() => [validateUser("user-1")] as const)
+        .transform(({ serviceResult: [validationResult] }) => {
+          return {
+            isValid: validationResult.valid,
+            userName: validationResult.user?.name,
+          };
+        })
+        .execute();
+
+      // Verify services were called
+      expect(getUserByIdCalled).toBe(true);
+      expect(validateUserCalled).toBe(true);
+      expect(retrievePhaseExecuted).toBe(true);
+      expect(result.isValid).toBe(true);
+      expect(result.userName).toBe("Test User");
+    }, 500);
+
+    it("should handle a TxResult with serviceCalls that returns another TxResult", async () => {
+      // This test reproduces the integration test scenario where:
+      // - orderService.createOrderWithValidation has serviceCalls: () => [userService.getUserById(...)]
+      // - handler has serviceCalls: () => [orderService.createOrderWithValidation(...)]
 
-    it("should handle mutate-only transactions", async () => {
       const compiler = createMockCompiler();
+      const mockUser = {
+        id: FragnoId.fromExternal("user-1", 1),
+        email: "test@example.com",
+        name: "Test User",
+        balance: 100,
+      };
       const executor: UOWExecutor<unknown, unknown> = {
-        executeRetrievalPhase: async () => [],
+        executeRetrievalPhase: async () => [[mockUser]],
         executeMutationPhase: async () => ({
           success: true,
           createdInternalIds: [BigInt(1)],
@@ -1489,94 +1365,146 @@ describe("executeRestrictedUnitOfWork", () => {
       };
       const decoder = createMockDecoder();
 
-      const result = await executeTxCallbacks(
-        {
-          mutate: ({ forSchema }) => {
-            const uow = forSchema(testSchema);
-            uow.create("users", { email: "test@example.com", name: "Test", balance: 0 });
-            return { created: true };
-          },
-        },
-        {
-          createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
+      let currentUow: IUnitOfWork | null = null;
+
+      // Simulates userService.getUserById - returns a TxResult that retrieves a user
+      const getUserById = (userId: string) => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .retrieve((uow) =>
+            uow.find("users", (b) => b.whereIndex("primary", (eb) => eb("id", "=", userId))),
+          )
+          .transformRetrieve(([users]) => users[0] ?? null)
+          .build();
+      };
+
+      // Simulates orderService.createOrderWithValidation - has serviceCalls on getUserById
+      const createOrderWithValidation = (userId: string, productName: string) => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .withServiceCalls(() => [getUserById(userId)] as const)
+          .mutate(({ uow, serviceIntermediateResult: [user] }) => {
+            if (!user) {
+              throw new Error("User not found");
+            }
+            // Create an order (simulated by creating a user for simplicity)
+            const orderId = uow.create("users", {
+              email: `order-${productName}@example.com`,
+              name: productName,
+              balance: 0,
+            });
+            return { orderId, forUser: user.email };
+          })
+          .build();
+      };
+
+      // Handler calls executeTx with serviceCalls containing the order service
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
         },
-      );
+      })
+        .withServiceCalls(() => [createOrderWithValidation("user-1", "TypeScript Book")] as const)
+        .transform(({ serviceResult: [orderResult] }) => {
+          return {
+            orderId: orderResult.orderId,
+            forUser: orderResult.forUser,
+            completed: true,
+          };
+        })
+        .execute();
 
-      expect(result).toEqual({ created: true });
-    });
+      expect(result.completed).toBe(true);
+      expect(result.forUser).toBe("test@example.com");
+      expect(result.orderId).toBeInstanceOf(FragnoId);
+    }, 500); // Set 500ms timeout to catch deadlock
 
-    it("should await promises returned from mutate callback", async () => {
+    it("should handle deeply nested TxResult serviceCalls (3 levels)", async () => {
       const compiler = createMockCompiler();
+      const mockUser = {
+        id: FragnoId.fromExternal("user-1", 1),
+        email: "test@example.com",
+        name: "Test User",
+        balance: 100,
+      };
       const executor: UOWExecutor<unknown, unknown> = {
-        executeRetrievalPhase: async () => [],
+        executeRetrievalPhase: async () => [[mockUser]],
         executeMutationPhase: async () => ({
           success: true,
-          createdInternalIds: [],
+          createdInternalIds: [BigInt(1)],
         }),
       };
       const decoder = createMockDecoder();
 
-      const result = await executeTxCallbacks(
-        {
-          mutate: () => {
-            return Promise.resolve({ value: "async result" });
-          },
-        },
-        {
-          createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
-        },
-      );
+      let currentUow: IUnitOfWork | null = null;
 
-      expect(result).toEqual({ value: "async result" });
-    });
+      // Level 3: Basic user retrieval
+      const getUserById = (userId: string) => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .retrieve((uow) =>
+            uow.find("users", (b) => b.whereIndex("primary", (eb) => eb("id", "=", userId))),
+          )
+          .transformRetrieve(([users]) => users[0] ?? null)
+          .build();
+      };
 
-    it("should retry on concurrency conflict", async () => {
-      const compiler = createMockCompiler();
-      let attemptCount = 0;
-      const executor: UOWExecutor<unknown, unknown> = {
-        executeRetrievalPhase: async () => [],
-        executeMutationPhase: async () => {
-          attemptCount++;
-          if (attemptCount < 2) {
-            return { success: false };
-          }
-          return {
-            success: true,
-            createdInternalIds: [],
-          };
-        },
+      // Level 2: Depends on getUserById
+      const validateUser = (userId: string) => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .withServiceCalls(() => [getUserById(userId)] as const)
+          .mutate(({ serviceIntermediateResult: [user] }) => {
+            if (!user) {
+              return { valid: false as const, reason: "User not found" };
+            }
+            return { valid: true as const, user };
+          })
+          .build();
       };
-      const decoder = createMockDecoder();
 
-      const result = await executeTxCallbacks(
-        {
-          mutate: () => ({ value: "result" }),
-        },
-        {
-          createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
-          retryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 3, initialDelayMs: 1 }),
-        },
-      );
+      // Level 1: Depends on validateUser
+      const createOrder = (userId: string, productName: string) => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .withServiceCalls(() => [validateUser(userId)] as const)
+          .mutate(({ uow, serviceIntermediateResult: [validation] }) => {
+            if (!validation.valid) {
+              throw new Error(validation.reason);
+            }
+            const orderId = uow.create("users", {
+              email: `order-${productName}@example.com`,
+              name: productName,
+              balance: 0,
+            });
+            return { orderId, forUser: validation.user.email };
+          })
+          .build();
+      };
 
-      expect(attemptCount).toBe(2);
-      expect(result).toEqual({ value: "result" });
-    });
+      // Handler: Depends on createOrder (3 levels deep)
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
+        },
+      })
+        .withServiceCalls(() => [createOrder("user-1", "Advanced TypeScript")] as const)
+        .transform(({ serviceResult: [orderResult] }) => ({
+          orderId: orderResult.orderId,
+          forUser: orderResult.forUser,
+          completed: true,
+        }))
+        .execute();
+
+      expect(result.completed).toBe(true);
+      expect(result.forUser).toBe("test@example.com");
+      expect(result.orderId).toBeInstanceOf(FragnoId);
+    }, 500); // Set 500ms timeout to catch deadlock
   });
 
-  describe("executeServiceTx", () => {
-    it("should execute service transaction with retrieve and mutate", async () => {
+  describe("triggerHook in serviceTx", () => {
+    it("should record triggered hooks on the base UOW when using createServiceTx with retrieve and mutate", async () => {
       const compiler = createMockCompiler();
+      // Return empty array to simulate no existing user, so the hook will be triggered
       const executor: UOWExecutor<unknown, unknown> = {
-        executeRetrievalPhase: async () => [
-          [
-            {
-              id: FragnoId.fromExternal("1", 1),
-              email: "test@example.com",
-              name: "Test",
-              balance: 100,
-            },
-          ],
-        ],
+        executeRetrievalPhase: async () => [[]],
         executeMutationPhase: async () => ({
           success: true,
           createdInternalIds: [],
@@ -1584,167 +1512,179 @@ describe("executeRestrictedUnitOfWork", () => {
       };
       const decoder = createMockDecoder();
 
-      const baseUow = createUnitOfWork(compiler, executor, decoder);
-      const restrictedUow = baseUow.restrict();
-
-      // Start service tx
-      const servicePromise = executeServiceTx(
-        testSchema,
-        {
-          retrieve: (uow) => {
-            return uow.findFirst("users", (b) => b.whereIndex("idx_email"));
-          },
-          mutate: async (uow, [user]) => {
-            if (!user) {
-              return { ok: false };
-            }
-            await new Promise((resolve) => setTimeout(resolve, 10)); // Async work
-            uow.update("users", user.id, (b) => b.set({ balance: user.balance - 10 }));
-            return { ok: true, newBalance: user.balance - 10 };
-          },
-        },
-        restrictedUow,
-      );
-
-      // Simulate handler executing phases concurrently with service
-      // Yield to let service start awaiting retrievalPhase
-      await new Promise((resolve) => setImmediate(resolve));
+      let currentUow: IUnitOfWork | null = null;
 
-      // Execute retrieve phase
-      await baseUow.executeRetrieve();
+      // Define hooks type for this test
+      type TestHooks = {
+        onSubscribe: (payload: { email: string }) => void;
+      };
 
-      // Wait for service mutate callback to schedule mutations
-      await new Promise((resolve) => setTimeout(resolve, 20));
+      const hooks: TestHooks = {
+        onSubscribe: (payload: { email: string }) => {
+          console.log(`onSubscribe: ${payload.email}`);
+        },
+      };
 
-      // Execute mutation phase
-      await baseUow.executeMutations();
+      // Service that retrieves a user and triggers a hook in mutate
+      const subscribeUser = (email: string) => {
+        return createServiceTxBuilder(testSchema, currentUow!, hooks)
+          .retrieve((uow) =>
+            uow.find("users", (b) => b.whereIndex("idx_email", (eb) => eb("email", "=", email))),
+          )
+          .transformRetrieve(([users]) => users[0] ?? null)
+          .mutate(({ uow, retrieveResult: existingUser }) => {
+            if (existingUser) {
+              return { subscribed: false, email };
+            }
+            // Trigger hook when subscribing a new user
+            uow.triggerHook("onSubscribe", { email });
+            return { subscribed: true, email };
+          })
+          .build();
+      };
 
-      // Wait for service to complete
-      const serviceResult = await servicePromise;
-      expect(serviceResult).toEqual({ ok: true, newBalance: 90 });
+      // Execute the transaction
+      await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
+        },
+      })
+        .withServiceCalls(() => [subscribeUser("new@example.com")] as const)
+        .transform(({ serviceResult: [result] }) => result)
+        .execute();
+
+      // Verify that the hook was triggered and recorded on the base UOW
+      const triggeredHooks = currentUow!.getTriggeredHooks();
+      expect(triggeredHooks).toHaveLength(1);
+      expect(triggeredHooks[0]).toMatchObject({
+        hookName: "onSubscribe",
+        payload: { email: "new@example.com" },
+      });
     });
 
-    it("should handle async mutate callback", async () => {
+    it("should record triggered hooks when service has only retrieve (no retrieveSuccess) and mutate", async () => {
       const compiler = createMockCompiler();
+      const mockUser = {
+        id: FragnoId.fromExternal("user-1", 1),
+        email: "test@example.com",
+        name: "Test User",
+        balance: 100,
+      };
       const executor: UOWExecutor<unknown, unknown> = {
-        executeRetrievalPhase: async () => [[]],
+        executeRetrievalPhase: async () => [[mockUser]],
         executeMutationPhase: async () => ({
           success: true,
-          createdInternalIds: [BigInt(1)],
+          createdInternalIds: [],
         }),
       };
       const decoder = createMockDecoder();
 
-      const baseUow = createUnitOfWork(compiler, executor, decoder);
-      const restrictedUow = baseUow.restrict();
-
-      // Simulate handler executing phases concurrently with service
-      const handlerSimulation = (async () => {
-        // Yield to let service start
-        await Promise.resolve();
-        // Execute retrieve phase
-        await baseUow.executeRetrieve();
-        // Wait for service mutate callback to schedule mutations
-        await new Promise((resolve) => setTimeout(resolve, 20));
-        // Execute mutation phase
-        await baseUow.executeMutations();
-      })();
-
-      // Start service tx
-      const servicePromise = executeServiceTx(
-        testSchema,
-        {
-          retrieve: (uow) => {
-            return uow.find("users", (b) => b.whereIndex("idx_email"));
-          },
-          mutate: async (uow) => {
-            await new Promise((resolve) => setTimeout(resolve, 10));
-            uow.create("users", { email: "new@example.com", name: "New", balance: 0 });
-            return { created: true };
-          },
+      let currentUow: IUnitOfWork | null = null;
+
+      // Define hooks type for this test
+      type TestHooks = {
+        onUserUpdated: (payload: { userId: string }) => void;
+      };
+
+      const hooks: TestHooks = {
+        onUserUpdated: (payload: { userId: string }) => {
+          console.log(`onUserUpdated: ${payload.userId}`);
         },
-        restrictedUow,
-      );
+      };
 
-      // Wait for both handler and service to complete
-      await Promise.all([handlerSimulation, servicePromise]);
+      // Service that uses raw retrieve results (no transformRetrieve) and triggers hook
+      const updateUser = (userId: string) => {
+        return (
+          createServiceTxBuilder(testSchema, currentUow!, hooks)
+            .retrieve((uow) =>
+              uow.find("users", (b) => b.whereIndex("primary", (eb) => eb("id", "=", userId))),
+            )
+            // NO transformRetrieve - mutate receives raw [users[]] array
+            .mutate(({ uow, retrieveResult: [users] }) => {
+              const user = users[0];
+              if (!user) {
+                return { updated: false };
+              }
+              uow.triggerHook("onUserUpdated", { userId: user.id.toString() });
+              return { updated: true };
+            })
+            .build()
+        );
+      };
 
-      const serviceResult = await servicePromise;
-      expect(serviceResult).toEqual({ created: true });
+      await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
+        },
+      })
+        .withServiceCalls(() => [updateUser("user-1")] as const)
+        .transform(({ serviceResult: [result] }) => result)
+        .execute();
+
+      // Verify hook was triggered
+      const triggeredHooks = currentUow!.getTriggeredHooks();
+      expect(triggeredHooks).toHaveLength(1);
+      expect(triggeredHooks[0]).toMatchObject({
+        hookName: "onUserUpdated",
+        payload: { userId: expect.any(String) },
+      });
     });
+  });
+
+  describe("error handling in createServiceTx", () => {
+    it("should not cause unhandled rejection when retrieve callback throws synchronously in serviceCalls", async () => {
+      // This test verifies that when a service's retrieve callback throws synchronously,
+      // the error is properly propagated without causing an unhandled rejection warning.
+      // Without the fix (adding retrievePhase.catch(() => {}) before rejecting and throwing),
+      // this test would cause an "Unhandled Rejection" warning from Vitest.
 
-    it("should prevent anti-pattern: service async work completes before mutations execute", async () => {
       const compiler = createMockCompiler();
       const executor: UOWExecutor<unknown, unknown> = {
-        executeRetrievalPhase: async () => [[]],
+        executeRetrievalPhase: async () => [],
         executeMutationPhase: async () => ({
           success: true,
-          createdInternalIds: [BigInt(1)],
+          createdInternalIds: [],
         }),
       };
       const decoder = createMockDecoder();
 
-      const baseUow = createUnitOfWork(compiler, executor, decoder);
-      const restrictedUow = baseUow.restrict();
-
-      let asyncWorkCompleted = false;
-      let mutationScheduled = false;
-
-      // Simulate handler executing phases concurrently with service
-      const handlerSimulation = (async () => {
-        // Yield to let service start
-        await Promise.resolve();
-        // Execute retrieve phase
-        await baseUow.executeRetrieve();
-        // Wait for service mutate callback to schedule mutations (including async work)
-        await new Promise((resolve) => setTimeout(resolve, 30));
-        // Execute mutation phase
-        await baseUow.executeMutations();
-      })();
-
-      // Start service tx
-      const servicePromise = executeServiceTx(
-        testSchema,
-        {
-          retrieve: (uow) => {
-            return uow.find("users", (b) => b.whereIndex("idx_email"));
-          },
-          mutate: async (uow) => {
-            // Simulate async work (like hashing backup codes)
-            await new Promise((resolve) => setTimeout(resolve, 20));
-            asyncWorkCompleted = true;
-
-            // Schedule mutation
-            uow.create("users", { email: "test@example.com", name: "Test", balance: 0 });
-            mutationScheduled = true;
-            return { success: true };
-          },
-        },
-        restrictedUow,
-      );
+      let currentUow: IUnitOfWork | null = null;
 
-      // Wait for both handler and service to complete
-      await Promise.all([handlerSimulation, servicePromise]);
+      const syncError = new Error("Retrieve callback threw synchronously");
+
+      // Service that throws synchronously in retrieve callback
+      const failingService = () => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .retrieve(() => {
+            throw syncError;
+          })
+          .build();
+      };
 
-      expect(asyncWorkCompleted).toBe(true);
-      expect(mutationScheduled).toBe(true);
+      // Execute with serviceCalls that contain the failing service
+      // The error should be properly caught and re-thrown without unhandled rejection
+      await expect(
+        createHandlerTxBuilder({
+          createUnitOfWork: () => {
+            currentUow = createUnitOfWork(compiler, executor, decoder);
+            return currentUow;
+          },
+        })
+          .withServiceCalls(() => [failingService()] as const)
+          .transform(({ serviceResult: [result] }) => result)
+          .execute(),
+      ).rejects.toThrow("Retrieve callback threw synchronously");
     });
-  });
 
-  describe("executeTxArray with executeServiceTx", () => {
-    it("should execute a single service promise created with executeServiceTx", async () => {
+    it("should not cause unhandled rejection when serviceCalls callback throws synchronously", async () => {
+      // This test verifies that when a service's serviceCalls callback throws synchronously,
+      // the error is properly propagated without causing an unhandled rejection warning.
+
       const compiler = createMockCompiler();
       const executor: UOWExecutor<unknown, unknown> = {
-        executeRetrievalPhase: async () => [
-          [
-            {
-              id: FragnoId.fromExternal("1", 1),
-              email: "user1@example.com",
-              name: "User 1",
-              balance: 100,
-            },
-          ],
-        ],
+        executeRetrievalPhase: async () => [],
         executeMutationPhase: async () => ({
           success: true,
           createdInternalIds: [],
@@ -1754,63 +1694,52 @@ describe("executeRestrictedUnitOfWork", () => {
 
       let currentUow: IUnitOfWork | null = null;
 
-      // Execute the service promise using executeTxArray
-      const result = await executeTxArray(
-        () => [
-          executeServiceTx(
-            testSchema,
-            {
-              retrieve: (uow) => {
-                return uow.findFirst("users", (b) => b.whereIndex("idx_email"));
-              },
-              mutate: async (uow, [user]) => {
-                if (!user) {
-                  return { ok: false };
-                }
-                // simulate async work
-                await new Promise((resolve) => setTimeout(resolve, 10));
-
-                uow.update("users", user.id, (b) => b.set({ balance: user.balance + 50 }));
-                return { ok: true, newBalance: user.balance + 50 };
-              },
-            },
-            currentUow!,
-          ),
-        ],
-        {
+      const syncError = new Error("Deps callback threw synchronously");
+
+      // Service that throws synchronously in serviceCalls callback
+      const failingService = () => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .withServiceCalls(() => {
+            throw syncError;
+          })
+          .mutate(() => ({ done: true }))
+          .build();
+      };
+
+      // Execute with serviceCalls that contain the failing service
+      await expect(
+        createHandlerTxBuilder({
           createUnitOfWork: () => {
             currentUow = createUnitOfWork(compiler, executor, decoder);
             return currentUow;
           },
-        },
-      );
-
-      expect(result).toHaveLength(1);
-      expect(result[0]).toEqual({ ok: true, newBalance: 150 });
+        })
+          .withServiceCalls(() => [failingService()] as const)
+          .transform(({ serviceResult: [result] }) => result)
+          .execute(),
+      ).rejects.toThrow("Deps callback threw synchronously");
     });
+  });
 
-    it("should retry and eventually succeed when mutations fail on first attempts", async () => {
-      const compiler = createMockCompiler();
-      let executionAttemptCount = 0;
-      let factoryCallCount = 0;
+  describe("mutate-only service type inference", () => {
+    it("should correctly type serviceIntermediateResult when dependent service only has mutate (no retrieve)", async () => {
+      // This test verifies that when a service has ONLY a mutate callback (no retrieve),
+      // the mutate result is correctly typed as the serviceIntermediateResult for dependent services.
+      //
+      // Execution order:
+      // 1. generateOTP's retrieve phase runs (empty - no retrieve callback)
+      // 2. generateOTP's mutate runs → returns { otpId, code }
+      // 3. sendOTPEmail's mutate runs → serviceIntermediateResult[0] is { otpId, code, userId }
+      //
+      // Without the InferBuilderRetrieveSuccessResult fix, serviceIntermediateResult[0] would be
+      // typed as `[]` (empty tuple) even though at runtime it's the mutate result.
 
+      const compiler = createMockCompiler();
       const executor: UOWExecutor<unknown, unknown> = {
-        executeRetrievalPhase: async () => [
-          [
-            {
-              id: FragnoId.fromExternal("1", 1),
-              email: "user1@example.com",
-              name: "User 1",
-              balance: 100,
-            },
-          ],
-        ],
+        executeRetrievalPhase: async () => {
+          return [];
+        },
         executeMutationPhase: async () => {
-          executionAttemptCount++;
-          // Fail on first 2 attempts, succeed on 3rd
-          if (executionAttemptCount < 3) {
-            return { success: false };
-          }
           return {
             success: true,
             createdInternalIds: [],
@@ -1821,44 +1750,169 @@ describe("executeRestrictedUnitOfWork", () => {
 
       let currentUow: IUnitOfWork | null = null;
 
-      const result = await executeTxArray(
-        () => {
-          factoryCallCount++;
-          return [
-            executeServiceTx(
-              testSchema,
-              {
-                retrieve: (uow) => {
-                  return uow.findFirst("users", (b) => b.whereIndex("idx_email"));
-                },
-                mutate: async (uow, [user]) => {
-                  if (!user) {
-                    return { ok: false };
-                  }
-                  // simulate async work
-                  await new Promise((resolve) => setTimeout(resolve, 10));
-
-                  uow.update("users", user.id, (b) => b.set({ balance: user.balance + 50 }));
-                  return { ok: true, newBalance: user.balance + 50, attempt: factoryCallCount };
-                },
-              },
-              currentUow!,
-            ),
-          ];
-        },
-        {
-          createUnitOfWork: () => {
-            currentUow = createUnitOfWork(compiler, executor, decoder);
-            return currentUow;
-          },
-          retryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 3, initialDelayMs: 1 }),
-        },
-      );
+      // Capture the runtime value of serviceResult to verify it contains the mutate result
+      let capturedOtpResult: unknown = null;
+
+      // Mutate-only service - simulates OTP generation
+      // No .retrieve() - this service doesn't need to read anything first
+      const generateOTP = (userId: string) => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .mutate(({ uow }) => {
+            const otpId = uow.create("users", {
+              email: `otp-${userId}@example.com`,
+              name: "OTP Record",
+              balance: 0,
+            });
+            // Return data that dependents need - this becomes serviceResult for them
+            return { otpId, code: "ABC123", userId };
+          })
+          .build();
+      };
 
-      expect(result).toHaveLength(1);
-      expect(result[0]).toEqual({ ok: true, newBalance: 150, attempt: 3 });
-      expect(factoryCallCount).toBe(3); // Factory called 3 times (once per attempt)
-      expect(executionAttemptCount).toBe(3); // 3 execution attempts total
+      // Service that depends on generateOTP
+      // The key test: serviceIntermediateResult[0] should be typed as { otpId, code, userId }
+      const sendOTPEmail = (userId: string, email: string) => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .withServiceCalls(() => [generateOTP(userId)] as const)
+          .mutate(({ uow, serviceIntermediateResult: [otpResult] }) => {
+            // RUNTIME CAPTURE: Store the actual runtime value for verification
+            capturedOtpResult = otpResult;
+
+            // TYPE TEST: Without the fix, this would require a manual cast.
+            // With the fix, TypeScript knows otpResult is { otpId: FragnoId, code: string, userId: string }
+            expectTypeOf(otpResult).toEqualTypeOf<{
+              otpId: FragnoId;
+              code: string;
+              userId: string;
+            }>();
+
+            // Access properties without type errors - proves the type inference works
+            const message = `Your OTP code is: ${otpResult.code}`;
+
+            uow.create("users", {
+              email,
+              name: message,
+              balance: 0,
+            });
+
+            return { sent: true, forUser: otpResult.userId };
+          })
+          .build();
+      };
+
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
+        },
+      })
+        .withServiceCalls(() => [sendOTPEmail("user-1", "test@example.com")] as const)
+        .transform(({ serviceResult: [emailResult] }) => emailResult)
+        .execute();
+
+      expect(result.sent).toBe(true);
+      expect(result.forUser).toBe("user-1");
+
+      // RUNTIME VERIFICATION: Verify the actual runtime value of serviceIntermediateResult
+      // This proves generateOTP's mutate result is actually passed as serviceIntermediateResult
+      expect(capturedOtpResult).not.toBeNull();
+      expect(capturedOtpResult).toMatchObject({
+        code: "ABC123",
+        userId: "user-1",
+      });
+      expect((capturedOtpResult as { otpId: FragnoId }).otpId).toBeInstanceOf(FragnoId);
+    });
+
+    it("should correctly type serviceIntermediateResult with multiple mutate-only service calls", async () => {
+      // Test with multiple mutate-only dependencies to verify tuple typing works
+
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [],
+        executeMutationPhase: async () => ({
+          success: true,
+          createdInternalIds: [],
+        }),
+      };
+      const decoder = createMockDecoder();
+
+      let currentUow: IUnitOfWork | null = null;
+
+      // Capture runtime values for verification
+      let capturedAuditResult: unknown = null;
+      let capturedCounterResult: unknown = null;
+
+      // First mutate-only service
+      const createAuditLog = (action: string) => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .mutate(({ uow }) => {
+            const logId = uow.create("users", {
+              email: `audit-${action}@example.com`,
+              name: action,
+              balance: 0,
+            });
+            return { logId, action, timestamp: 1234567890 };
+          })
+          .build();
+      };
+
+      // Second mutate-only service
+      const incrementCounter = (name: string) => {
+        return createServiceTxBuilder(testSchema, currentUow!)
+          .mutate(() => {
+            // Simulates incrementing a counter - returns the new value
+            return { counterName: name, newValue: 42 };
+          })
+          .build();
+      };
+
+      const result = await createHandlerTxBuilder({
+        createUnitOfWork: () => {
+          currentUow = createUnitOfWork(compiler, executor, decoder);
+          return currentUow;
+        },
+      })
+        .withServiceCalls(
+          () => [createAuditLog("user_login"), incrementCounter("login_count")] as const,
+        )
+        .mutate(({ serviceIntermediateResult: [auditResult, counterResult] }) => {
+          // RUNTIME CAPTURE: Store the actual runtime values
+          capturedAuditResult = auditResult;
+          capturedCounterResult = counterResult;
+
+          // TYPE TESTS: Both should be correctly typed from their mutate results
+          expectTypeOf(auditResult).toEqualTypeOf<{
+            logId: FragnoId;
+            action: string;
+            timestamp: number;
+          }>();
+          expectTypeOf(counterResult).toEqualTypeOf<{
+            counterName: string;
+            newValue: number;
+          }>();
+
+          // Access properties - proves type inference works
+          return {
+            auditAction: auditResult.action,
+            loginCount: counterResult.newValue,
+          };
+        })
+        .execute();
+
+      expect(result.auditAction).toBe("user_login");
+      expect(result.loginCount).toBe(42);
+
+      // RUNTIME VERIFICATION: Verify the actual runtime values
+      expect(capturedAuditResult).toMatchObject({
+        action: "user_login",
+        timestamp: 1234567890,
+      });
+      expect((capturedAuditResult as { logId: FragnoId }).logId).toBeInstanceOf(FragnoId);
+
+      expect(capturedCounterResult).toEqual({
+        counterName: "login_count",
+        newValue: 42,
+      });
     });
   });
 });