@fragno-dev/db 0.2.1 → 0.3.0

package/src/db-fragment-definition-builder.ts

@@ -2,7 +2,6 @@ import type { AnySchema } from "./schema/create";
 import type { SimpleQueryInterface } from "./query/simple-query-interface";
 import type { DatabaseAdapter } from "./adapters/adapters";
 import type { IUnitOfWork } from "./query/unit-of-work/unit-of-work";
-import { TypedUnitOfWork, UnitOfWork } from "./query/unit-of-work/unit-of-work";
 import type {
   RequestThisContext,
   FragnoPublicConfig,
@@ -14,31 +13,42 @@ import {
   type ServiceConstructorFn,
 } from "@fragno-dev/core";
 import {
-  executeRestrictedUnitOfWork,
-  executeTxArray,
-  executeTxCallbacks,
-  executeServiceTx,
-  type AwaitedPromisesInObject,
-  type ExecuteRestrictedUnitOfWorkOptions,
-  type HandlerTxCallbacks,
-  type ServiceTxCallbacks,
+  createServiceTxBuilder,
+  createHandlerTxBuilder,
+  ServiceTxBuilder,
+  HandlerTxBuilder,
+  type ExecuteTxOptions,
 } from "./query/unit-of-work/execute-unit-of-work";
 import {
   prepareHookMutations,
-  processHooks,
   type HooksMap,
   type HookFn,
   type HookContext,
+  type HookProcessorConfig,
+  type DurableHooksProcessingOptions,
+  createHookScheduler,
 } from "./hooks/hooks";
 import type { InternalFragmentInstance } from "./fragments/internal-fragment";
+import { resolveDatabaseAdapter } from "./util/default-database-adapter";
+import { sanitizeNamespace } from "./naming/sql-naming";
 
 /**
- * Extended FragnoPublicConfig that includes a database adapter.
- * Use this type when creating fragments with database support.
+ * Extended FragnoPublicConfig for database fragments.
+ * If databaseAdapter is omitted and better-sqlite3 is available, a default SQLite adapter is used.
  */
 export type FragnoPublicConfigWithDatabase = FragnoPublicConfig & {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  databaseAdapter: DatabaseAdapter<any>;
+  databaseAdapter?: DatabaseAdapter<any>;
+  /**
+   * Optional durable hooks processing configuration.
+   */
+  durableHooks?: DurableHooksProcessingOptions;
+  /**
+   * Optional override for database namespace. If provided (including null), it is used as-is
+   * without sanitization — the caller is responsible for providing a valid namespace.
+   * When omitted, defaults to a sanitized version of schema.name.
+   */
+  databaseNamespace?: string | null;
 };
 
 /**
@@ -48,6 +58,7 @@ export type FragnoPublicConfigWithDatabase = FragnoPublicConfig & {
 export type ImplicitDatabaseDependencies<TSchema extends AnySchema> = {
   /**
    * Database query engine for the fragment's schema.
+   * @deprecated Prefer handlerTx/serviceTx instead of direct db usage.
    */
   db: SimpleQueryInterface<TSchema>;
   /**
@@ -57,7 +68,7 @@ export type ImplicitDatabaseDependencies<TSchema extends AnySchema> = {
   /**
    * The database namespace for this fragment.
    */
-  namespace: string;
+  namespace: string | null;
   /**
    * Create a new Unit of Work for database operations.
    */
@@ -69,35 +80,38 @@ export type ImplicitDatabaseDependencies<TSchema extends AnySchema> = {
  */
 export type DatabaseServiceContext<THooks extends HooksMap> = RequestThisContext & {
   /**
-   * Get a typed, restricted Unit of Work for the given schema.
-   * @param schema - Schema to get a typed view for
-   * @returns TypedUnitOfWork (restricted version without execute methods)
-   */
-  uow<TSchema extends AnySchema>(schema: TSchema): TypedUnitOfWork<TSchema, [], unknown, THooks>;
-
-  /**
-   * Execute a transaction with two-phase callbacks (retrieve + mutate).
-   *
-   * @param schema - Schema to use for the transaction
-   * @param callbacks - Object containing retrieve and mutate callbacks
-   * @returns Promise resolving to the mutation result with promises awaited 1 level deep
+   * Create a service-level transaction builder using the fluent API.
+   * Returns a builder that can be chained with withServiceCalls, retrieve,
+   * transformRetrieve, mutate, transform, and build.
    *
    * @example
    * ```ts
-   * return this.tx(schema, {
-   *   retrieve: (uow) => uow.findFirst("users", ...),
-   *   mutate: async (uow, [user]) => {
-   *     await validateUser(user);
-   *     uow.update("users", user.id, ...).check();
-   *     return { ok: true };
-   *   }
-   * });
+   * return this.serviceTx(schema)
+   *   .withServiceCalls(() => [otherService.getData()])
+   *   .retrieve((uow) => uow.find("users", ...))
+   *   .transformRetrieve(([users]) => users[0])
+   *   .mutate(({ uow, retrieveResult, serviceIntermediateResult }) =>
+   *     uow.create("records", { ... })
+   *   )
+   *   .transform(({ mutateResult, serviceResult }) => ({ id: mutateResult }))
+   *   .build();
    * ```
    */
-  tx<TSchema extends AnySchema, TRetrievalResults extends unknown[], TMutationResult = void>(
+  serviceTx<TSchema extends AnySchema>(
     schema: TSchema,
-    callbacks: ServiceTxCallbacks<TSchema, TRetrievalResults, TMutationResult, THooks>,
-  ): Promise<AwaitedPromisesInObject<TMutationResult>>;
+  ): ServiceTxBuilder<
+    TSchema,
+    readonly [],
+    [],
+    [],
+    unknown,
+    unknown,
+    false,
+    false,
+    false,
+    false,
+    THooks
+  >;
 };
 
 /**
@@ -105,92 +119,24 @@ export type DatabaseServiceContext<THooks extends HooksMap> = RequestThisContext
  */
 export type DatabaseHandlerContext<THooks extends HooksMap = {}> = RequestThisContext & {
   /**
-   * Execute a Unit of Work with explicit phase control and automatic retry support.
-   * This method provides an API where users call forSchema to create a schema-specific
-   * UOW, then call executeRetrieve() and executeMutate() to execute the phases. The entire
-   * callback is re-executed on optimistic concurrency conflicts, ensuring retries work properly.
-   * Automatically provides the UOW factory from context.
-   * Promises in the returned object are awaited 1 level deep.
-   *
-   * @param callback - Async function that receives a context with forSchema, executeRetrieve, executeMutate, nonce, and currentAttempt
-   * @param options - Optional configuration for retry policy and abort signal
-   * @returns Promise resolving to the callback's return value with promises awaited 1 level deep
-   * @throws Error if retries are exhausted or callback throws an error
+   * Create a handler-level transaction builder using the fluent API.
+   * Returns a builder that can be chained with withServiceCalls, retrieve,
+   * transformRetrieve, mutate, transform, and execute.
    *
    * @example
    * ```ts
-   * const result = await this.uow(async ({ forSchema, executeRetrieve, executeMutate, nonce, currentAttempt }) => {
-   *   const uow = forSchema(schema);
-   *   const userId = uow.create("users", { name: "John" });
-   *
-   *   // Execute retrieval phase
-   *   await executeRetrieve();
-   *
-   *   const profileId = uow.create("profiles", { userId });
-   *
-   *   // Execute mutation phase
-   *   await executeMutate();
-   *
-   *   return { userId, profileId };
-   * });
-   * ```
-   */
-  uow<TResult>(
-    callback: (context: {
-      forSchema: <TSchema extends AnySchema, H extends HooksMap = THooks>(
-        schema: TSchema,
-        hooks?: H,
-      ) => TypedUnitOfWork<TSchema, [], unknown, H>;
-      executeRetrieve: () => Promise<void>;
-      executeMutate: () => Promise<void>;
-      nonce: string;
-      currentAttempt: number;
-    }) => Promise<TResult> | TResult,
-    options?: Omit<ExecuteRestrictedUnitOfWorkOptions, "createUnitOfWork">,
-  ): Promise<AwaitedPromisesInObject<TResult>>;
-
-  /**
-   * Execute a transaction with automatic retry support.
-   * Provides two overloads: array syntax (common case) and callback syntax (advanced).
-   *
-   * Array syntax - pass a factory function that returns service calls:
-   * ```ts
-   * const [transfer, notify] = await this.tx(
-   *   () => [
-   *     services.transfer({ from, to, amount }),
-   *     services.notify({ userId, message })
-   *   ]
-   * );
-   * ```
-   *
-   * Callback syntax - for handlers that need direct UOW access:
-   * ```ts
-   * const result = await this.tx({
-   *   retrieve: ({ forSchema }) => {
-   *     const uow = forSchema(schema);
-   *     uow.find("users", ...);
-   *     return services.transfer({ ... });
-   *   },
-   *   mutate: ({ forSchema }, transferPromise) => {
-   *     const uow = forSchema(schema);
-   *     uow.create("auditLog", { ... });
-   *     return transferPromise;
-   *   }
-   * });
+   * const result = await this.handlerTx()
+   *   .withServiceCalls(() => [userService.getUser(id)])
+   *   .mutate(({ forSchema, idempotencyKey, currentAttempt, serviceIntermediateResult }) => {
+   *     return forSchema(ordersSchema).create("orders", { ... });
+   *   })
+   *   .transform(({ mutateResult, serviceResult }) => ({ ... }))
+   *   .execute();
    * ```
-   *
-   * Note: Handler callbacks are synchronous only to prevent accidentally awaiting services in wrong place.
    */
-  // Overload 1: Array syntax (common case) - accepts a factory
-  tx<T extends readonly unknown[]>(
-    servicesFactory: () => readonly [...{ [K in keyof T]: Promise<T[K]> }],
-    options?: Omit<ExecuteRestrictedUnitOfWorkOptions, "createUnitOfWork">,
-  ): Promise<{ [K in keyof T]: T[K] }>;
-  // Overload 2: Callback syntax (advanced, sync callbacks only)
-  tx<TRetrieveResult, TMutationResult>(
-    callbacks: HandlerTxCallbacks<TRetrieveResult, TMutationResult, THooks>,
-    options?: Omit<ExecuteRestrictedUnitOfWorkOptions, "createUnitOfWork">,
-  ): Promise<AwaitedPromisesInObject<TMutationResult>>;
+  handlerTx(
+    options?: Omit<ExecuteTxOptions, "createUnitOfWork">,
+  ): HandlerTxBuilder<readonly [], [], [], unknown, unknown, false, false, false, false, THooks>;
 };
 
 /**
@@ -214,21 +160,23 @@ export type DatabaseFragmentContext<TSchema extends AnySchema> = {
 function createDatabaseContext<TSchema extends AnySchema>(
   options: FragnoPublicConfigWithDatabase,
   schema: TSchema,
-  namespace: string,
 ): DatabaseFragmentContext<TSchema> {
-  const databaseAdapter = options.databaseAdapter;
-
-  if (!databaseAdapter) {
-    throw new Error(
-      "Database fragment requires a database adapter to be provided in options.databaseAdapter",
-    );
-  }
+  const databaseAdapter = resolveDatabaseAdapter(options, schema);
 
+  const namespace = resolveDatabaseNamespace(options, schema);
   const db = databaseAdapter.createQueryEngine(schema, namespace);
 
   return { databaseAdapter, db };
 }
 
+function resolveDatabaseNamespace<TSchema extends AnySchema>(
+  options: FragnoPublicConfigWithDatabase,
+  schema: TSchema,
+): string | null {
+  const hasOverride = options.databaseNamespace !== undefined;
+  return hasOverride ? (options.databaseNamespace ?? null) : sanitizeNamespace(schema.name);
+}
+
 /**
  * Storage type for database fragments - stores the Unit of Work.
  */
@@ -240,7 +188,7 @@ export type DatabaseRequestStorage = {
  * Builder for database fragments that wraps the core fragment builder
  * and provides database-specific functionality.
  *
- * Database fragments always require FragnoPublicConfigWithDatabase (which includes databaseAdapter).
+ * Database fragments use FragnoPublicConfigWithDatabase and default the adapter when possible.
  */
 export class DatabaseFragmentDefinitionBuilder<
   TSchema extends AnySchema,
@@ -270,7 +218,6 @@ export class DatabaseFragmentDefinitionBuilder<
     TLinkedFragments
   >;
   #schema: TSchema;
-  #namespace: string;
   #hooksFactory?: (context: { config: TConfig; options: FragnoPublicConfigWithDatabase }) => THooks;
 
   constructor(
@@ -288,7 +235,6 @@ export class DatabaseFragmentDefinitionBuilder<
       TLinkedFragments
     >,
     schema: TSchema,
-    namespace?: string,
     hooksFactory?: (context: {
       config: TConfig;
       options: FragnoPublicConfigWithDatabase;
@@ -296,7 +242,6 @@ export class DatabaseFragmentDefinitionBuilder<
   ) {
     this.#baseBuilder = baseBuilder;
     this.#schema = schema;
-    this.#namespace = namespace ?? baseBuilder.name;
     this.#hooksFactory = hooksFactory;
   }
 
@@ -326,7 +271,8 @@ export class DatabaseFragmentDefinitionBuilder<
   > {
     // Wrap user function to inject DB context
     const wrappedFn = (context: { config: TConfig; options: FragnoPublicConfigWithDatabase }) => {
-      const dbContext = createDatabaseContext(context.options, this.#schema, this.#namespace);
+      const dbContext = createDatabaseContext(context.options, this.#schema);
+      const namespace = resolveDatabaseNamespace(context.options, this.#schema);
 
       // Call user function with enriched context
       const userDeps = fn({
@@ -341,7 +287,7 @@ export class DatabaseFragmentDefinitionBuilder<
       const implicitDeps: ImplicitDatabaseDependencies<TSchema> = {
         db: dbContext.db,
         schema: this.#schema,
-        namespace: this.#namespace,
+        namespace,
         createUnitOfWork: createUow,
       };
 
@@ -354,12 +300,7 @@ export class DatabaseFragmentDefinitionBuilder<
     // Create new base builder with wrapped function
     const newBaseBuilder = this.#baseBuilder.withDependencies(wrappedFn);
 
-    return new DatabaseFragmentDefinitionBuilder(
-      newBaseBuilder,
-      this.#schema,
-      this.#namespace,
-      this.#hooksFactory,
-    );
+    return new DatabaseFragmentDefinitionBuilder(newBaseBuilder, this.#schema, this.#hooksFactory);
   }
 
   providesBaseService<TNewService>(
@@ -387,12 +328,7 @@ export class DatabaseFragmentDefinitionBuilder<
   > {
     const newBaseBuilder = this.#baseBuilder.providesBaseService<TNewService>(fn);
 
-    return new DatabaseFragmentDefinitionBuilder(
-      newBaseBuilder,
-      this.#schema,
-      this.#namespace,
-      this.#hooksFactory,
-    );
+    return new DatabaseFragmentDefinitionBuilder(newBaseBuilder, this.#schema, this.#hooksFactory);
   }
 
   providesService<TServiceName extends string, TService>(
@@ -424,12 +360,7 @@ export class DatabaseFragmentDefinitionBuilder<
       fn,
     );
 
-    return new DatabaseFragmentDefinitionBuilder(
-      newBaseBuilder,
-      this.#schema,
-      this.#namespace,
-      this.#hooksFactory,
-    );
+    return new DatabaseFragmentDefinitionBuilder(newBaseBuilder, this.#schema, this.#hooksFactory);
   }
 
   /**
@@ -468,12 +399,7 @@ export class DatabaseFragmentDefinitionBuilder<
       fn,
     );
 
-    return new DatabaseFragmentDefinitionBuilder(
-      newBaseBuilder,
-      this.#schema,
-      this.#namespace,
-      this.#hooksFactory,
-    );
+    return new DatabaseFragmentDefinitionBuilder(newBaseBuilder, this.#schema, this.#hooksFactory);
   }
 
   /**
@@ -487,7 +413,7 @@ export class DatabaseFragmentDefinitionBuilder<
    * ```ts
    * .provideHooks(({ defineHook, config }) => ({
    *   onSubscribe: defineHook(async function (payload: { email: string }) {
-   *     // 'this' context available (HookServiceContext with nonce)
+   *     // 'this' context available (HookServiceContext with idempotencyKey)
    *     await config.onSubscribe?.(payload.email);
    *   }),
    * }))
@@ -537,7 +463,6 @@ export class DatabaseFragmentDefinitionBuilder<
     const newBuilder = new DatabaseFragmentDefinitionBuilder(
       this.#baseBuilder,
       this.#schema,
-      this.#namespace,
     ) as unknown as DatabaseFragmentDefinitionBuilder<
       TSchema,
       TConfig,
@@ -578,12 +503,7 @@ export class DatabaseFragmentDefinitionBuilder<
   > {
     const newBaseBuilder = this.#baseBuilder.usesService<TServiceName, TService>(serviceName);
 
-    return new DatabaseFragmentDefinitionBuilder(
-      newBaseBuilder,
-      this.#schema,
-      this.#namespace,
-      this.#hooksFactory,
-    );
+    return new DatabaseFragmentDefinitionBuilder(newBaseBuilder, this.#schema, this.#hooksFactory);
   }
 
   /**
@@ -609,12 +529,7 @@ export class DatabaseFragmentDefinitionBuilder<
       serviceName,
     );
 
-    return new DatabaseFragmentDefinitionBuilder(
-      newBaseBuilder,
-      this.#schema,
-      this.#namespace,
-      this.#hooksFactory,
-    );
+    return new DatabaseFragmentDefinitionBuilder(newBaseBuilder, this.#schema, this.#hooksFactory);
   }
 
   /**
@@ -663,12 +578,13 @@ export class DatabaseFragmentDefinitionBuilder<
         }
       }
 
-      const { db } = createDatabaseContext(context.options, this.#schema, this.#namespace);
+      const { db } = createDatabaseContext(context.options, this.#schema);
+      const namespace = resolveDatabaseNamespace(context.options, this.#schema);
 
       const implicitDeps: ImplicitDatabaseDependencies<TSchema> = {
         db,
         schema: this.#schema,
-        namespace: this.#namespace,
+        namespace,
         createUnitOfWork: () => db.createUnitOfWork(),
       };
 
@@ -681,7 +597,7 @@ export class DatabaseFragmentDefinitionBuilder<
     // Use the adapter's shared context storage (all fragments using the same adapter share this storage)
     const builderWithExternalStorage = this.#baseBuilder.withExternalRequestStorage(
       ({ options }) => {
-        const dbContext = createDatabaseContext(options, this.#schema, this.#namespace);
+        const dbContext = createDatabaseContext(options, this.#schema);
         return dbContext.databaseAdapter.contextStorage;
       },
     );
@@ -690,7 +606,7 @@ export class DatabaseFragmentDefinitionBuilder<
     const builderWithStorage = builderWithExternalStorage.withRequestStorage(
       ({ options }): DatabaseRequestStorage => {
         // Create database context - needed here to create the UOW
-        const dbContextForStorage = createDatabaseContext(options, this.#schema, this.#namespace);
+        const dbContextForStorage = createDatabaseContext(options, this.#schema);
 
         // Create a new Unit of Work for this request
         const uow: IUnitOfWork = dbContextForStorage.db.createUnitOfWork();
@@ -706,68 +622,109 @@ export class DatabaseFragmentDefinitionBuilder<
       options: FragnoPublicConfigWithDatabase;
     }) => InternalFragmentInstance;
 
+    // Cache per instantiated fragment (deps object is unique per instantiation).
+    const hooksConfigCache = new WeakMap<object, HookProcessorConfig<THooks>>();
+
+    const createHooksConfig = (context: {
+      config: TConfig;
+      options: FragnoPublicConfigWithDatabase;
+      deps: TDeps;
+    }) => {
+      if (!this.#hooksFactory) {
+        return undefined;
+      }
+      const depsKey =
+        typeof context.deps === "object" && context.deps !== null
+          ? (context.deps as object)
+          : undefined;
+      const cachedHooksConfig = depsKey ? hooksConfigCache.get(depsKey) : undefined;
+      if (cachedHooksConfig) {
+        return cachedHooksConfig;
+      }
+
+      const namespace = resolveDatabaseNamespace(context.options, this.#schema);
+      const namespaceKey = namespace ?? this.#schema.name;
+      const durableHooksOptions = context.options.durableHooks;
+      const baseAdapter = resolveDatabaseAdapter(context.options, this.#schema);
+      const hookAdapter = baseAdapter.getHookProcessingAdapter?.() ?? baseAdapter;
+      const hookOptions =
+        hookAdapter === baseAdapter
+          ? context.options
+          : { ...context.options, databaseAdapter: hookAdapter };
+      const dbContextForHooks = createDatabaseContext(hookOptions, this.#schema);
+      const hooksConfig: HookProcessorConfig<THooks> = {
+        hooks: this.#hooksFactory(context),
+        namespace: namespaceKey,
+        internalFragment: internalFragmentFactory({
+          config: context.config,
+          options: hookOptions,
+        }),
+        handlerTx: (execOptions?: Omit<ExecuteTxOptions, "createUnitOfWork">) => {
+          const userOnBeforeMutate = execOptions?.onBeforeMutate;
+          const userOnAfterMutate = execOptions?.onAfterMutate;
+          return createHandlerTxBuilder<THooks>({
+            ...execOptions,
+            createUnitOfWork: () => {
+              const uow = dbContextForHooks.db.createUnitOfWork();
+              uow.registerSchema(
+                hooksConfig.internalFragment.$internal.deps.schema,
+                hooksConfig.internalFragment.$internal.deps.namespace,
+              );
+              return uow;
+            },
+            onBeforeMutate: (uow) => {
+              prepareHookMutations(uow, hooksConfig);
+              if (userOnBeforeMutate) {
+                userOnBeforeMutate(uow);
+              }
+            },
+            onAfterMutate: async (uow) => {
+              void hooksConfig.scheduler?.schedule().catch((error) => {
+                console.error("Durable hooks processing failed", error);
+              });
+              if (userOnAfterMutate) {
+                await userOnAfterMutate(uow);
+              }
+            },
+          });
+        },
+        stuckProcessingTimeoutMinutes: durableHooksOptions?.stuckProcessingTimeoutMinutes,
+        onStuckProcessingHooks: durableHooksOptions?.onStuckProcessingHooks,
+      };
+      hooksConfig.scheduler = createHookScheduler(hooksConfig);
+      if (depsKey) {
+        hooksConfigCache.set(depsKey, hooksConfig);
+      }
+      return hooksConfig;
+    };
+
     const builderWithContext = builderWithStorage.withThisContext<
       DatabaseServiceContext<THooks>,
       DatabaseHandlerContext<THooks>
-    >(({ storage, config, options }) => {
+    >(({ storage, config, options, deps }) => {
       // Create hooks config if hooks factory is defined
-      const hooksConfig = this.#hooksFactory
-        ? {
-            hooks: this.#hooksFactory({ config, options }),
-            namespace: this.#namespace,
-            internalFragment: internalFragmentFactory({ config, options }),
-          }
-        : undefined;
-
-      function forSchema<TSchema extends AnySchema>(
-        schema: TSchema,
-      ): TypedUnitOfWork<TSchema, [], unknown, THooks> {
-        const uow = storage.getStore()?.uow;
-        if (!uow) {
-          throw new Error(
-            "No UnitOfWork in context. Service must be called within a route handler OR using `withUnitOfWork`.",
-          );
-        }
-
-        return uow.restrict().forSchema<TSchema, THooks>(schema);
-      }
+      const hooksConfig = createHooksConfig({ config, options, deps });
+      const internalFragment =
+        hooksConfig?.internalFragment ??
+        (internalFragmentFactory ? internalFragmentFactory({ config, options }) : undefined);
 
-      const serviceTx = async <
-        TSchema extends AnySchema,
-        TRetrievalResults extends unknown[],
-        TMutationResult = void,
-      >(
-        schema: TSchema,
-        callbacks: ServiceTxCallbacks<TSchema, TRetrievalResults, TMutationResult, THooks>,
-      ): Promise<AwaitedPromisesInObject<TMutationResult>> => {
+      // Builder API: serviceTx using createServiceTxBuilder
+      function serviceTx<TSchema extends AnySchema>(schema: TSchema) {
         const uow = storage.getStore()?.uow;
         if (!uow) {
           throw new Error(
             "No UnitOfWork in context. Service must be called within a route handler OR using `withUnitOfWork`.",
           );
         }
-
-        return executeServiceTx(schema, callbacks, uow);
-      };
+        return createServiceTxBuilder<TSchema, THooks>(schema, uow, hooksConfig?.hooks);
+      }
 
       const serviceContext: DatabaseServiceContext<THooks> = {
-        uow: forSchema,
-        tx: serviceTx,
+        serviceTx,
       };
 
-      async function uow<TResult>(
-        callback: (context: {
-          forSchema: <S extends AnySchema, H extends HooksMap = THooks>(
-            schema: S,
-            hooks?: H,
-          ) => TypedUnitOfWork<S, [], unknown, H>;
-          executeRetrieve: () => Promise<void>;
-          executeMutate: () => Promise<void>;
-          nonce: string;
-          currentAttempt: number;
-        }) => Promise<TResult> | TResult,
-        execOptions?: Omit<ExecuteRestrictedUnitOfWorkOptions, "createUnitOfWork">,
-      ): Promise<AwaitedPromisesInObject<TResult>> {
+      // Builder API: handlerTx using createHandlerTxBuilder
+      function handlerTx(execOptions?: Omit<ExecuteTxOptions, "createUnitOfWork">) {
         const currentStorage = storage.getStore();
         if (!currentStorage) {
           throw new Error(
@@ -775,34 +732,20 @@ export class DatabaseFragmentDefinitionBuilder<
           );
         }
 
-        const wrappedCallback = async (context: {
-          forSchema: <S extends AnySchema, H extends HooksMap = THooks>(
-            schema: S,
-            hooks?: H,
-          ) => TypedUnitOfWork<S, [], unknown, H>;
-          executeRetrieve: () => Promise<void>;
-          executeMutate: () => Promise<void>;
-          nonce: string;
-          currentAttempt: number;
-        }): Promise<TResult> => {
-          return callback(context);
-        };
-
         const userOnBeforeMutate = execOptions?.onBeforeMutate;
-        const userOnSuccess = execOptions?.onSuccess;
+        const userOnAfterMutate = execOptions?.onAfterMutate;
 
-        return executeRestrictedUnitOfWork(wrappedCallback, {
+        return createHandlerTxBuilder<THooks>({
           ...execOptions,
           createUnitOfWork: () => {
             currentStorage.uow.reset();
-            if (hooksConfig) {
+            if (internalFragment) {
               currentStorage.uow.registerSchema(
-                hooksConfig.internalFragment.$internal.deps.schema,
-                hooksConfig.internalFragment.$internal.deps.namespace,
+                internalFragment.$internal.deps.schema,
+                internalFragment.$internal.deps.namespace,
               );
             }
-            // Safe cast: currentStorage.uow is always a UnitOfWork instance
-            return currentStorage.uow as UnitOfWork;
+            return currentStorage.uow;
           },
           onBeforeMutate: (uow) => {
             if (hooksConfig) {
@@ -812,94 +755,21 @@ export class DatabaseFragmentDefinitionBuilder<
               userOnBeforeMutate(uow);
             }
           },
-          onSuccess: async (uow) => {
-            if (hooksConfig) {
-              await processHooks(hooksConfig);
+          onAfterMutate: async (uow) => {
+            if (hooksConfig?.scheduler) {
+              void hooksConfig.scheduler.schedule().catch((error) => {
+                console.error("Durable hooks processing failed", error);
+              });
             }
-            if (userOnSuccess) {
-              await userOnSuccess(uow);
+            if (userOnAfterMutate) {
+              await userOnAfterMutate(uow);
             }
           },
         });
       }
 
-      // Handler tx method with two overloads
-      function handlerTx<T extends readonly unknown[]>(
-        servicesFactory: () => readonly [...{ [K in keyof T]: Promise<T[K]> }],
-        execOptions?: Omit<ExecuteRestrictedUnitOfWorkOptions, "createUnitOfWork">,
-      ): Promise<{ [K in keyof T]: T[K] }>;
-      function handlerTx<TRetrieveResult, TMutationResult>(
-        callbacks: HandlerTxCallbacks<TRetrieveResult, TMutationResult, THooks>,
-        execOptions?: Omit<ExecuteRestrictedUnitOfWorkOptions, "createUnitOfWork">,
-      ): Promise<AwaitedPromisesInObject<TMutationResult>>;
-      async function handlerTx<T extends readonly unknown[], TRetrieveResult, TMutationResult>(
-        factoryOrCallbacks:
-          | (() => readonly [...{ [K in keyof T]: Promise<T[K]> }])
-          | HandlerTxCallbacks<TRetrieveResult, TMutationResult, THooks>,
-        execOptions?: Omit<ExecuteRestrictedUnitOfWorkOptions, "createUnitOfWork">,
-      ): Promise<{ [K in keyof T]: T[K] } | AwaitedPromisesInObject<TMutationResult>> {
-        const currentStorage = storage.getStore();
-        if (!currentStorage) {
-          throw new Error(
-            "No storage in context. Handler must be called within a request context.",
-          );
-        }
-
-        const userOnBeforeMutate = execOptions?.onBeforeMutate;
-        const userOnSuccess = execOptions?.onSuccess;
-
-        const createUow = () => {
-          currentStorage.uow.reset();
-
-          if (hooksConfig) {
-            currentStorage.uow.registerSchema(
-              hooksConfig.internalFragment.$internal.deps.schema,
-              hooksConfig.internalFragment.$internal.deps.namespace,
-            );
-          }
-          // Safe cast: currentStorage.uow is always a UnitOfWork instance
-          return currentStorage.uow as UnitOfWork;
-        };
-
-        const options: ExecuteRestrictedUnitOfWorkOptions = {
-          ...execOptions,
-          createUnitOfWork: createUow,
-          onBeforeMutate: (uow) => {
-            if (hooksConfig) {
-              prepareHookMutations(uow, hooksConfig);
-            }
-            if (userOnBeforeMutate) {
-              userOnBeforeMutate(uow);
-            }
-          },
-          onSuccess: async (uow) => {
-            if (hooksConfig) {
-              await processHooks(hooksConfig);
-            }
-            if (userOnSuccess) {
-              await userOnSuccess(uow);
-            }
-          },
-        };
-
-        // Check if it's a function (array syntax factory) or callbacks object (callback syntax)
-        if (typeof factoryOrCallbacks === "function") {
-          // Array syntax - factoryOrCallbacks is a factory function
-          return executeTxArray(
-            factoryOrCallbacks as () => readonly [...{ [K in keyof T]: Promise<T[K]> }],
-            options,
-          ) as Promise<{ [K in keyof T]: T[K] }>;
-        } else {
-          return executeTxCallbacks(
-            factoryOrCallbacks as HandlerTxCallbacks<TRetrieveResult, TMutationResult, THooks>,
-            options,
-          );
-        }
-      }
-
       const handlerContext: DatabaseHandlerContext<THooks> = {
-        uow,
-        tx: handlerTx,
+        handlerTx,
       };
 
       return { serviceContext, handlerContext };
@@ -907,6 +777,15 @@ export class DatabaseFragmentDefinitionBuilder<
 
     // Build the final definition
     const finalDef = builderWithContext.build();
+    if (this.#hooksFactory) {
+      finalDef.internalDataFactory = ({ config, options, deps }) => ({
+        durableHooks: createHooksConfig({
+          config: config as TConfig,
+          options: options as FragnoPublicConfigWithDatabase,
+          deps: deps as TDeps,
+        }),
+      });
+    }
 
     // Return the complete definition with proper typing and dependencies
     return {