@fragno-dev/db 0.2.2 → 0.4.1

package/dist/db-fragment-definition-builder.js

@@ -1,54 +1,230 @@
-import { createHandlerTxBuilder, createServiceTxBuilder } from "./query/unit-of-work/execute-unit-of-work.js";
-import { prepareHookMutations, processHooks } from "./hooks/hooks.js";
+import { DurableHooksLogger } from "./hooks/durable-hooks-logger.js";
+import { getDurableHooksRuntimeByConfig, getDurableHooksRuntimeByNamespace, registerDurableHooksRuntime } from "./hooks/durable-hooks-runtime.js";
+import { createDurableHooksRunner, prepareHookMutations } from "./hooks/hooks.js";
+import { sanitizeNamespace } from "./naming/sql-naming.js";
+import { HandlerTxBuilder, createHandlerTxBuilder, createServiceTxBuilder } from "./query/unit-of-work/execute-unit-of-work.js";
+import { resolveDatabaseAdapter } from "./util/default-database-adapter.js";
+import { FragmentDefinitionBuilder } from "@fragno-dev/core";
+import { FragnoApiError } from "@fragno-dev/core/api";
 
 //#region src/db-fragment-definition-builder.ts
 /**
 * Create database context from options.
 * This extracts the database adapter and creates the ORM instance.
 */
-function createDatabaseContext(options, schema, namespace) {
-	const databaseAdapter = options.databaseAdapter;
-	if (!databaseAdapter) throw new Error("Database fragment requires a database adapter to be provided in options.databaseAdapter");
+function createDatabaseContext(options, schema) {
+	const databaseAdapter = resolveDatabaseAdapter(options, schema);
+	const namespace = resolveDatabaseNamespace(options, schema);
 	return {
 		databaseAdapter,
 		db: databaseAdapter.createQueryEngine(schema, namespace)
 	};
 }
+function resolveDatabaseNamespace(options, schema) {
+	return options.databaseNamespace !== void 0 ? options.databaseNamespace ?? null : sanitizeNamespace(schema.name);
+}
+function resolveMountRoute(name, mountRoute) {
+	const resolved = mountRoute ?? `/api/${name}`;
+	return resolved.endsWith("/") ? resolved.slice(0, -1) : resolved;
+}
+const dbRoundtripGuardStateSymbol = Symbol("fragno-db-roundtrip-guard");
+const requestSourceSymbol = Symbol.for("fragno-request-source");
+const requestRouteSymbol = Symbol.for("fragno-request-route");
+const requestWaitUntilSymbol = Symbol.for("fragno-request-wait-until");
+const roundtripGuardDocsUrl = "https://fragno.dev/docs/fragno/for-library-authors/rules-of-fragno";
+function wrapHandlerTxBuilderWithRoundtripGuard(builder, onExecute) {
+	const wrappedBuilders = /* @__PURE__ */ new WeakSet();
+	const applyExecuteGuard = (target) => {
+		if (wrappedBuilders.has(target)) return target;
+		wrappedBuilders.add(target);
+		const execute = target.execute.bind(target);
+		target.execute = () => {
+			onExecute();
+			return execute();
+		};
+		return target;
+	};
+	const wrap = (target) => {
+		const guarded = applyExecuteGuard(target);
+		return new Proxy(guarded, { get(obj, prop, receiver) {
+			const value = Reflect.get(obj, prop, receiver);
+			if (typeof value !== "function") return value;
+			if (prop === "execute") return value;
+			return (...args) => {
+				const result = value.apply(obj, args);
+				if (result instanceof HandlerTxBuilder) return wrap(result);
+				return result;
+			};
+		} });
+	};
+	return wrap(builder);
+}
+function buildDurableHooksLogContext(context) {
+	const logContext = {};
+	if (context?.route !== void 0) logContext["route"] = context.route;
+	if (context?.source !== void 0) logContext["source"] = context.source;
+	return logContext;
+}
+function notifyDurableHooks(notifier, namespace, notifyContext, logContextFields, options) {
+	const suffix = options?.crossNamespace ?? false ? " (cross-namespace)" : "";
+	const notifyStart = Date.now();
+	DurableHooksLogger.debug(`Durable hooks notify requested${suffix}`, {
+		namespace,
+		fields: logContextFields
+	});
+	const notifyPromise = Promise.resolve().then(() => notifier.notify(notifyContext)).then((processed) => {
+		DurableHooksLogger.debug(`Durable hooks notify completed${suffix}`, {
+			namespace,
+			fields: {
+				result: processed === void 0 ? null : processed,
+				ms: Date.now() - notifyStart,
+				...logContextFields
+			}
+		});
+	}).catch((error) => {
+		DurableHooksLogger.error(`Durable hooks notify failed${suffix}`, {
+			namespace,
+			fields: {
+				error: DurableHooksLogger.toErrorMessage(error),
+				...logContextFields
+			}
+		});
+	});
+	if (notifyContext.waitUntil) {
+		notifyContext.waitUntil(notifyPromise);
+		return;
+	}
+}
+function notifyDurableHooksAfterMutate({ uow, hooksConfig, internalFragment, autoSchedule, planMode, logContext }) {
+	if (planMode) return;
+	const notifyContext = {
+		source: logContext?.source ?? "request",
+		route: logContext?.route,
+		waitUntil: logContext?.waitUntil
+	};
+	const logContextFields = buildDurableHooksLogContext(logContext);
+	const triggeredHooks = uow.getTriggeredHooks();
+	const ownNamespaceTriggeredCount = hooksConfig ? triggeredHooks.filter((hook) => hook.namespace === hooksConfig.namespace).length : 0;
+	if (hooksConfig?.notifier && autoSchedule && ownNamespaceTriggeredCount > 0) notifyDurableHooks(hooksConfig.notifier, hooksConfig.namespace, notifyContext, logContextFields);
+	else if (hooksConfig && !autoSchedule && ownNamespaceTriggeredCount > 0) DurableHooksLogger.debug("Durable hooks notify skipped (autoSchedule=false)", {
+		namespace: hooksConfig.namespace,
+		fields: {
+			queued: ownNamespaceTriggeredCount,
+			...logContextFields
+		}
+	});
+	else if (hooksConfig && !hooksConfig.notifier && ownNamespaceTriggeredCount > 0) DurableHooksLogger.debug("Durable hooks notify skipped (notifier missing)", {
+		namespace: hooksConfig.namespace,
+		fields: {
+			queued: ownNamespaceTriggeredCount,
+			...logContextFields
+		}
+	});
+	if (triggeredHooks.length === 0) return;
+	const namespaces = /* @__PURE__ */ new Set();
+	const triggeredCountByNamespace = /* @__PURE__ */ new Map();
+	for (const hook of triggeredHooks) {
+		namespaces.add(hook.namespace);
+		triggeredCountByNamespace.set(hook.namespace, (triggeredCountByNamespace.get(hook.namespace) ?? 0) + 1);
+	}
+	if (hooksConfig) namespaces.delete(hooksConfig.namespace);
+	for (const namespace of namespaces) {
+		if (!internalFragment) {
+			DurableHooksLogger.debug("Durable hooks notifier missing scope for namespace", {
+				namespace,
+				fields: logContextFields
+			});
+			continue;
+		}
+		const runtime = getDurableHooksRuntimeByNamespace(namespace, internalFragment);
+		if (!runtime) {
+			DurableHooksLogger.debug("Durable hooks notifier missing for namespace", {
+				namespace,
+				fields: logContextFields
+			});
+			continue;
+		}
+		if (runtime.config.autoSchedule === false) {
+			DurableHooksLogger.debug("Durable hooks notify skipped (autoSchedule=false)", {
+				namespace,
+				fields: {
+					queued: triggeredCountByNamespace.get(namespace) ?? 0,
+					...logContextFields
+				}
+			});
+			continue;
+		}
+		const notifier = runtime.config.notifier;
+		if (!notifier) {
+			DurableHooksLogger.debug("Durable hooks notifier missing for namespace", {
+				namespace,
+				fields: logContextFields
+			});
+			continue;
+		}
+		notifyDurableHooks(notifier, namespace, notifyContext, logContextFields, { crossNamespace: true });
+	}
+}
+function resolveDbRoundtripGuard(options) {
+	const guard = options.dbRoundtripGuard;
+	if (!guard) return null;
+	if (guard === true) return {
+		retrieveCount: 0,
+		mutateCount: 0,
+		maxRoundtrips: 1
+	};
+	return {
+		retrieveCount: 0,
+		mutateCount: 0,
+		maxRoundtrips: guard.maxRoundtrips ?? 1
+	};
+}
+function getDbRoundtripGuardState(storage, guard) {
+	const storageWithGuard = storage;
+	if (!storageWithGuard[dbRoundtripGuardStateSymbol]) storageWithGuard[dbRoundtripGuardStateSymbol] = { ...guard };
+	else storageWithGuard[dbRoundtripGuardStateSymbol].maxRoundtrips = guard.maxRoundtrips;
+	return storageWithGuard[dbRoundtripGuardStateSymbol];
+}
+function isRouteRequest(storage) {
+	return storage[requestSourceSymbol] === "route";
+}
 /**
 * 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.
 */
 var DatabaseFragmentDefinitionBuilder = class DatabaseFragmentDefinitionBuilder {
 	#baseBuilder;
 	#schema;
-	#namespace;
 	#hooksFactory;
-	constructor(baseBuilder, schema, namespace, hooksFactory) {
+	#syncRegistry;
+	#registryResolver;
+	constructor(baseBuilder, schema, hooksFactory, syncRegistry, registryResolver) {
 		this.#baseBuilder = baseBuilder;
 		this.#schema = schema;
-		this.#namespace = namespace ?? baseBuilder.name;
 		this.#hooksFactory = hooksFactory;
+		this.#syncRegistry = syncRegistry;
+		this.#registryResolver = registryResolver;
 	}
 	/**
 	* Define dependencies for this database fragment.
-	* The context includes database adapter and ORM instance.
+	* The context includes the database adapter.
 	*/
 	withDependencies(fn) {
 		const wrappedFn = (context) => {
-			const dbContext = createDatabaseContext(context.options, this.#schema, this.#namespace);
+			const dbContext = createDatabaseContext(context.options, this.#schema);
+			const namespace = resolveDatabaseNamespace(context.options, this.#schema);
 			const userDeps = fn({
 				config: context.config,
 				options: context.options,
-				db: dbContext.db,
 				databaseAdapter: dbContext.databaseAdapter
 			});
 			const createUow = () => dbContext.db.createUnitOfWork();
 			const implicitDeps = {
-				db: dbContext.db,
+				databaseAdapter: dbContext.databaseAdapter,
 				schema: this.#schema,
-				namespace: this.#namespace,
+				namespace,
 				createUnitOfWork: createUow
 			};
 			return {
@@ -56,13 +232,13 @@ var DatabaseFragmentDefinitionBuilder = class DatabaseFragmentDefinitionBuilder
 				...implicitDeps
 			};
 		};
-		return new DatabaseFragmentDefinitionBuilder(this.#baseBuilder.withDependencies(wrappedFn), this.#schema, this.#namespace, this.#hooksFactory);
+		return new DatabaseFragmentDefinitionBuilder(this.#baseBuilder.withDependencies(wrappedFn), this.#schema, this.#hooksFactory, this.#syncRegistry, this.#registryResolver);
 	}
 	providesBaseService(fn) {
-		return new DatabaseFragmentDefinitionBuilder(this.#baseBuilder.providesBaseService(fn), this.#schema, this.#namespace, this.#hooksFactory);
+		return new DatabaseFragmentDefinitionBuilder(this.#baseBuilder.providesBaseService(fn), this.#schema, this.#hooksFactory, this.#syncRegistry, this.#registryResolver);
 	}
 	providesService(serviceName, fn) {
-		return new DatabaseFragmentDefinitionBuilder(this.#baseBuilder.providesService(serviceName, fn), this.#schema, this.#namespace, this.#hooksFactory);
+		return new DatabaseFragmentDefinitionBuilder(this.#baseBuilder.providesService(serviceName, fn), this.#schema, this.#hooksFactory, this.#syncRegistry, this.#registryResolver);
 	}
 	/**
 	* Provide a private service that is only accessible to the fragment author.
@@ -72,7 +248,7 @@ var DatabaseFragmentDefinitionBuilder = class DatabaseFragmentDefinitionBuilder
 	* to later ones.
 	*/
 	providesPrivateService(serviceName, fn) {
-		return new DatabaseFragmentDefinitionBuilder(this.#baseBuilder.providesPrivateService(serviceName, fn), this.#schema, this.#namespace, this.#hooksFactory);
+		return new DatabaseFragmentDefinitionBuilder(this.#baseBuilder.providesPrivateService(serviceName, fn), this.#schema, this.#hooksFactory, this.#syncRegistry, this.#registryResolver);
 	}
 	/**
 	* Define durable hooks for this fragment.
@@ -99,26 +275,36 @@ var DatabaseFragmentDefinitionBuilder = class DatabaseFragmentDefinitionBuilder
 			return fn({
 				config: context.config,
 				options: context.options,
+				deps: context.deps,
+				services: context.services,
+				serviceDeps: context.serviceDeps,
 				defineHook
 			});
 		};
-		const newBuilder = new DatabaseFragmentDefinitionBuilder(this.#baseBuilder, this.#schema, this.#namespace);
+		const newBuilder = new DatabaseFragmentDefinitionBuilder(this.#baseBuilder, this.#schema, this.#hooksFactory, this.#syncRegistry, this.#registryResolver);
 		newBuilder.#hooksFactory = hooksFactory;
 		return newBuilder;
 	}
 	/**
+	* Register sync command definitions for this fragment.
+	*/
+	withSyncCommands(registry) {
+		if (registry.schemaName !== this.#schema.name) throw new Error(`Sync command registry schema name "${registry.schemaName}" does not match fragment schema "${this.#schema.name}".`);
+		return new DatabaseFragmentDefinitionBuilder(this.#baseBuilder, this.#schema, this.#hooksFactory, registry, this.#registryResolver);
+	}
+	/**
 	* Declare that this fragment uses a required service provided by the runtime.
 	* Delegates to the base builder.
 	*/
 	usesService(serviceName) {
-		return new DatabaseFragmentDefinitionBuilder(this.#baseBuilder.usesService(serviceName), this.#schema, this.#namespace, this.#hooksFactory);
+		return new DatabaseFragmentDefinitionBuilder(this.#baseBuilder.usesService(serviceName), this.#schema, this.#hooksFactory, this.#syncRegistry, this.#registryResolver);
 	}
 	/**
 	* Declare that this fragment uses an optional service provided by the runtime.
 	* Delegates to the base builder.
 	*/
 	usesOptionalService(serviceName) {
-		return new DatabaseFragmentDefinitionBuilder(this.#baseBuilder.usesOptionalService(serviceName), this.#schema, this.#namespace, this.#hooksFactory);
+		return new DatabaseFragmentDefinitionBuilder(this.#baseBuilder.usesOptionalService(serviceName), this.#schema, this.#hooksFactory, this.#syncRegistry, this.#registryResolver);
 	}
 	/**
 	* Build the final database fragment definition.
@@ -137,11 +323,34 @@ var DatabaseFragmentDefinitionBuilder = class DatabaseFragmentDefinitionBuilder
 					userDeps = {};
 				} else throw error;
 			}
-			const { db } = createDatabaseContext(context.options, this.#schema, this.#namespace);
+			const dbContext = createDatabaseContext(context.options, this.#schema);
+			const { db } = dbContext;
+			const namespace = resolveDatabaseNamespace(context.options, this.#schema);
+			const dryRun = process.env["FRAGNO_INIT_DRY_RUN"] === "true";
+			const isInternalFragment$1 = baseDef.name === "$fragno-internal-fragment";
+			if (!dryRun && !isInternalFragment$1 && this.#registryResolver) {
+				const registry = this.#registryResolver.getRegistryForAdapterSync(dbContext.databaseAdapter);
+				const outboxEnabled = context.options.outbox?.enabled ?? false;
+				registry.registerSchema({
+					name: this.#schema.name,
+					namespace,
+					version: this.#schema.version,
+					tables: Object.keys(this.#schema.tables).sort()
+				}, {
+					name: baseDef.name,
+					mountRoute: resolveMountRoute(baseDef.name, context.options.mountRoute)
+				}, { outboxEnabled });
+				if (this.#syncRegistry) registry.registerSyncCommands({
+					fragmentName: baseDef.name,
+					schemaName: this.#syncRegistry.schemaName,
+					namespace,
+					commands: this.#syncRegistry.commands
+				});
+			}
 			const implicitDeps = {
-				db,
+				databaseAdapter: dbContext.databaseAdapter,
 				schema: this.#schema,
-				namespace: this.#namespace,
+				namespace,
 				createUnitOfWork: () => db.createUnitOfWork()
 			};
 			return {
@@ -150,57 +359,238 @@ var DatabaseFragmentDefinitionBuilder = class DatabaseFragmentDefinitionBuilder
 			};
 		};
 		const builderWithStorage = this.#baseBuilder.withExternalRequestStorage(({ options }) => {
-			return createDatabaseContext(options, this.#schema, this.#namespace).databaseAdapter.contextStorage;
+			return createDatabaseContext(options, this.#schema).databaseAdapter.contextStorage;
 		}).withRequestStorage(({ options }) => {
-			return { uow: createDatabaseContext(options, this.#schema, this.#namespace).db.createUnitOfWork() };
+			return { uow: createDatabaseContext(options, this.#schema).db.createBaseUnitOfWork() };
 		});
-		const internalFragmentFactory = baseDef.linkedFragments?.["_fragno_internal"];
-		return {
-			...builderWithStorage.withThisContext(({ storage, config, options }) => {
-				const hooksConfig = this.#hooksFactory ? {
-					hooks: this.#hooksFactory({
-						config,
-						options
-					}),
-					namespace: this.#namespace,
-					internalFragment: internalFragmentFactory({
-						config,
-						options
-					})
-				} : void 0;
-				function serviceTx(schema) {
-					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 createServiceTxBuilder(schema, uow, hooksConfig?.hooks);
-				}
-				const serviceContext = { serviceTx };
-				function handlerTx(execOptions) {
-					const currentStorage = storage.getStore();
-					if (!currentStorage) throw new Error("No storage in context. Handler must be called within a request context.");
+		const hooksConfigCache = /* @__PURE__ */ new WeakMap();
+		const createHooksConfig = (context) => {
+			if (!this.#hooksFactory) return;
+			const depsKey = typeof context.deps === "object" && context.deps !== null ? context.deps : void 0;
+			const namespaceKey = resolveDatabaseNamespace(context.options, this.#schema) ?? this.#schema.name;
+			const durableHooksOptions = context.options.durableHooks;
+			DurableHooksLogger.configure(durableHooksOptions?.logging, namespaceKey);
+			const cachedHooksConfig = depsKey ? hooksConfigCache.get(depsKey) : void 0;
+			if (cachedHooksConfig) {
+				if (!cachedHooksConfig.hooks && context.services) cachedHooksConfig.hooks = this.#hooksFactory({
+					config: context.config,
+					options: context.options,
+					deps: context.deps,
+					services: context.services,
+					serviceDeps: context.serviceDeps ?? {}
+				});
+				return cachedHooksConfig;
+			}
+			const autoSchedule = durableHooksOptions?.autoSchedule !== false;
+			const baseAdapter = resolveDatabaseAdapter(context.options, this.#schema);
+			const hookAdapter = baseAdapter.getHookProcessingAdapter?.() ?? baseAdapter;
+			const hookOptions = hookAdapter === baseAdapter ? context.options : {
+				...context.options,
+				databaseAdapter: hookAdapter
+			};
+			const registryResolver = this.#registryResolver;
+			if (!registryResolver) throw new Error("Adapter registry resolver is missing for durable hooks.");
+			const dbContextForHooks = createDatabaseContext(hookOptions, this.#schema);
+			const hookContextStorage = dbContextForHooks.databaseAdapter.contextStorage;
+			const hooksConfig = {
+				hooks: context.services ? this.#hooksFactory({
+					config: context.config,
+					options: context.options,
+					deps: context.deps,
+					services: context.services,
+					serviceDeps: context.serviceDeps ?? {}
+				}) : void 0,
+				namespace: namespaceKey,
+				internalFragment: registryResolver.getInternalFragment(hookAdapter),
+				autoSchedule,
+				handlerTx: (execOptions) => {
 					const userOnBeforeMutate = execOptions?.onBeforeMutate;
 					const userOnAfterMutate = execOptions?.onAfterMutate;
+					const planMode = execOptions?.planMode ?? false;
+					let storageRef = null;
+					const getHookWaitUntil = () => {
+						if (!hookContextStorage.hasStore()) return;
+						return hookContextStorage.getStore()[requestWaitUntilSymbol];
+					};
 					return createHandlerTxBuilder({
 						...execOptions,
 						createUnitOfWork: () => {
-							currentStorage.uow.reset();
-							if (hooksConfig) currentStorage.uow.registerSchema(hooksConfig.internalFragment.$internal.deps.schema, hooksConfig.internalFragment.$internal.deps.namespace);
-							return currentStorage.uow;
+							const baseUow = dbContextForHooks.db.createBaseUnitOfWork();
+							baseUow.registerSchema(hooksConfig.internalFragment.$internal.deps.schema, hooksConfig.internalFragment.$internal.deps.namespace);
+							if (storageRef) storageRef.uow = baseUow;
+							return baseUow;
 						},
 						onBeforeMutate: (uow) => {
-							if (hooksConfig) prepareHookMutations(uow, hooksConfig);
+							if (!planMode) prepareHookMutations(uow, hooksConfig.internalFragment, hooksConfig.defaultRetryPolicy);
 							if (userOnBeforeMutate) userOnBeforeMutate(uow);
 						},
 						onAfterMutate: async (uow) => {
-							if (hooksConfig) await processHooks(hooksConfig);
+							notifyDurableHooksAfterMutate({
+								uow,
+								hooksConfig,
+								internalFragment: hooksConfig.internalFragment,
+								autoSchedule,
+								planMode,
+								logContext: {
+									source: "hook",
+									waitUntil: getHookWaitUntil()
+								}
+							});
 							if (userOnAfterMutate) await userOnAfterMutate(uow);
 						}
-					});
-				}
-				return {
-					serviceContext,
-					handlerContext: { handlerTx }
+					}, void 0, (run) => hookContextStorage.runWithInitializer(() => {
+						const inheritedWaitUntil = getHookWaitUntil();
+						storageRef = { uow: null };
+						if (inheritedWaitUntil) storageRef[requestWaitUntilSymbol] = inheritedWaitUntil;
+						return storageRef;
+					}, run));
+				},
+				stuckProcessingTimeoutMinutes: durableHooksOptions?.stuckProcessingTimeoutMinutes,
+				onStuckProcessingHooks: durableHooksOptions?.onStuckProcessingHooks
+			};
+			hooksConfig.runner = createDurableHooksRunner(hooksConfig);
+			registerDurableHooksRuntime(hooksConfig);
+			if (depsKey) hooksConfigCache.set(depsKey, hooksConfig);
+			return hooksConfig;
+		};
+		const isInternalFragment = baseDef.name === "$fragno-internal-fragment";
+		const finalDef = builderWithStorage.withThisContext(({ storage, config, options, deps }) => {
+			const hooksConfig = createHooksConfig({
+				config,
+				options,
+				deps
+			});
+			const autoSchedule = options.durableHooks?.autoSchedule !== false;
+			const registryResolver = this.#registryResolver;
+			const databaseAdapter = deps.databaseAdapter ?? resolveDatabaseAdapter(options, this.#schema);
+			const internalFragment = isInternalFragment ? void 0 : hooksConfig?.internalFragment ?? registryResolver?.getInternalFragment(databaseAdapter);
+			function serviceTx(schema) {
+				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 createServiceTxBuilder(schema, uow, hooksConfig?.hooks);
+			}
+			const serviceContext = { serviceTx };
+			function handlerTx(execOptions) {
+				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 userOnAfterMutate = execOptions?.onAfterMutate;
+				const userOnAfterRetrieve = execOptions?.onAfterRetrieve;
+				const planMode = execOptions?.planMode ?? false;
+				const roundtripGuard = isRouteRequest(currentStorage) ? resolveDbRoundtripGuard(options) : null;
+				const roundtripState = roundtripGuard ? getDbRoundtripGuardState(currentStorage, roundtripGuard) : null;
+				const routeInfo = currentStorage[requestRouteSymbol];
+				const routeWaitUntil = currentStorage[requestWaitUntilSymbol];
+				const routeLabel = routeInfo && routeInfo.method && routeInfo.path ? `${routeInfo.method} ${routeInfo.path}` : null;
+				const routeSuffix = routeLabel ? ` (route: ${routeLabel})` : "";
+				const buildRoundtripError = (kind) => new FragnoApiError({
+					message: `[fragno-db] Fragment "${baseDef.name}" executed more than ${roundtripState?.maxRoundtrips ?? 1} ${kind} database roundtrip(s) in a single request${routeSuffix}. Combine reads/writes into one handlerTx() or increase dbRoundtripGuard. See ${roundtripGuardDocsUrl}`,
+					code: "DB_ROUNDTRIP_LIMIT_EXCEEDED"
+				}, 500);
+				const roundtripExecutionState = roundtripState ? {
+					countedRetrieve: false,
+					countedMutate: false
+				} : null;
+				const resetRoundtripExecutionState = () => {
+					if (!roundtripExecutionState) return;
+					roundtripExecutionState.countedRetrieve = false;
+					roundtripExecutionState.countedMutate = false;
 				};
-			}).build(),
+				const guardOnAfterRetrieve = roundtripState ? async (uow, results) => {
+					if (roundtripExecutionState && !roundtripExecutionState.countedRetrieve && uow.getRetrievalOperations().length > 0) {
+						roundtripExecutionState.countedRetrieve = true;
+						roundtripState.retrieveCount += 1;
+						if (roundtripState.retrieveCount > roundtripState.maxRoundtrips) throw buildRoundtripError("retrieve");
+					}
+					if (userOnAfterRetrieve) await userOnAfterRetrieve(uow, results);
+				} : userOnAfterRetrieve;
+				const builder = createHandlerTxBuilder({
+					...execOptions,
+					createUnitOfWork: () => {
+						currentStorage.uow.reset();
+						if (internalFragment) currentStorage.uow.registerSchema(internalFragment.$internal.deps.schema, internalFragment.$internal.deps.namespace);
+						return currentStorage.uow;
+					},
+					onBeforeMutate: (uow) => {
+						if (internalFragment && !planMode) prepareHookMutations(uow, internalFragment, hooksConfig?.defaultRetryPolicy);
+						if (userOnBeforeMutate) userOnBeforeMutate(uow);
+						if (roundtripState && roundtripExecutionState && !roundtripExecutionState.countedMutate && uow.getMutationOperations().length > 0) {
+							roundtripExecutionState.countedMutate = true;
+							roundtripState.mutateCount += 1;
+							if (roundtripState.mutateCount > roundtripState.maxRoundtrips) throw buildRoundtripError("mutate");
+						}
+					},
+					onAfterRetrieve: guardOnAfterRetrieve,
+					onAfterMutate: async (uow) => {
+						notifyDurableHooksAfterMutate({
+							uow,
+							hooksConfig,
+							internalFragment,
+							autoSchedule,
+							planMode,
+							logContext: {
+								route: routeLabel,
+								source: "request",
+								waitUntil: routeWaitUntil
+							}
+						});
+						if (hooksConfig && !planMode) {
+							const runtimeState = getDurableHooksRuntimeByConfig(hooksConfig);
+							if (runtimeState && !runtimeState.dispatcherRegistered && !runtimeState.dispatcherWarningEmitted) {
+								if (uow.getTriggeredHooks().some((hook) => hook.namespace === hooksConfig.namespace)) {
+									runtimeState.dispatcherWarningEmitted = true;
+									DurableHooksLogger.warn("Durable hooks dispatcher not configured for fragment", {
+										namespace: hooksConfig.namespace,
+										fields: { guidance: "Hooks will only run during requests; scheduled/retry hooks may stall. Create a dispatcher with createDurableHooksProcessor([...]) from `@fragno-dev/db/dispatchers/node` or `@fragno-dev/db/dispatchers/cloudflare-do`." }
+									});
+								}
+							}
+						}
+						if (userOnAfterMutate) await userOnAfterMutate(uow);
+					}
+				});
+				if (roundtripState) return wrapHandlerTxBuilderWithRoundtripGuard(builder, resetRoundtripExecutionState);
+				return builder;
+			}
+			function callServices(serviceCalls) {
+				let callWasArray = false;
+				return handlerTx().withServiceCalls(() => {
+					const calls = serviceCalls();
+					callWasArray = Array.isArray(calls);
+					return callWasArray ? calls : [calls];
+				}).execute().then((result) => callWasArray ? result : result[0]);
+			}
+			return {
+				serviceContext,
+				handlerContext: {
+					handlerTx,
+					callServices
+				}
+			};
+		}).build();
+		if (this.#hooksFactory) finalDef.internalDataFactory = ({ config, options, deps, services, serviceDeps }) => {
+			const hooksConfig = createHooksConfig({
+				config,
+				options,
+				deps,
+				services,
+				serviceDeps
+			});
+			if (!hooksConfig) return {};
+			return { durableHooksToken: registerDurableHooksRuntime(hooksConfig) };
+		};
+		if (this.#registryResolver) {
+			const registryInternalRoutes = ({ deps }) => {
+				const databaseAdapter = deps.databaseAdapter;
+				if (!databaseAdapter) throw new Error("Database adapter is missing for internal routes.");
+				const internalFragment = this.#registryResolver.getInternalFragment(databaseAdapter);
+				if (!internalFragment) return [];
+				return internalFragment.routes ?? [];
+			};
+			finalDef.internalRoutes = [...finalDef.internalRoutes ?? [], registryInternalRoutes];
+		}
+		return {
+			...finalDef,
 			dependencies
 		};
 	}