@fragno-dev/db 0.3.0 → 0.4.1

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

@@ -1,7 +1,11 @@
-import { createHandlerTxBuilder, createServiceTxBuilder } from "./query/unit-of-work/execute-unit-of-work.js";
-import { createHookScheduler, prepareHookMutations } 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
 /**
@@ -19,6 +23,171 @@ function createDatabaseContext(options, schema) {
 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.
@@ -29,14 +198,18 @@ var DatabaseFragmentDefinitionBuilder = class DatabaseFragmentDefinitionBuilder
 	#baseBuilder;
 	#schema;
 	#hooksFactory;
-	constructor(baseBuilder, schema, hooksFactory) {
+	#syncRegistry;
+	#registryResolver;
+	constructor(baseBuilder, schema, hooksFactory, syncRegistry, registryResolver) {
 		this.#baseBuilder = baseBuilder;
 		this.#schema = schema;
 		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) => {
@@ -45,12 +218,11 @@ var DatabaseFragmentDefinitionBuilder = class DatabaseFragmentDefinitionBuilder
 			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,
 				createUnitOfWork: createUow
@@ -60,13 +232,13 @@ var DatabaseFragmentDefinitionBuilder = class DatabaseFragmentDefinitionBuilder
 				...implicitDeps
 			};
 		};
-		return new DatabaseFragmentDefinitionBuilder(this.#baseBuilder.withDependencies(wrappedFn), this.#schema, 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.#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.#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.
@@ -76,7 +248,7 @@ var DatabaseFragmentDefinitionBuilder = class DatabaseFragmentDefinitionBuilder
 	* to later ones.
 	*/
 	providesPrivateService(serviceName, fn) {
-		return new DatabaseFragmentDefinitionBuilder(this.#baseBuilder.providesPrivateService(serviceName, fn), this.#schema, this.#hooksFactory);
+		return new DatabaseFragmentDefinitionBuilder(this.#baseBuilder.providesPrivateService(serviceName, fn), this.#schema, this.#hooksFactory, this.#syncRegistry, this.#registryResolver);
 	}
 	/**
 	* Define durable hooks for this fragment.
@@ -103,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);
+		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.#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.#hooksFactory);
+		return new DatabaseFragmentDefinitionBuilder(this.#baseBuilder.usesOptionalService(serviceName), this.#schema, this.#hooksFactory, this.#syncRegistry, this.#registryResolver);
 	}
 	/**
 	* Build the final database fragment definition.
@@ -141,10 +323,32 @@ var DatabaseFragmentDefinitionBuilder = class DatabaseFragmentDefinitionBuilder
 					userDeps = {};
 				} else throw error;
 			}
-			const { db } = createDatabaseContext(context.options, this.#schema);
+			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,
 				createUnitOfWork: () => db.createUnitOfWork()
@@ -157,70 +361,109 @@ var DatabaseFragmentDefinitionBuilder = class DatabaseFragmentDefinitionBuilder
 		const builderWithStorage = this.#baseBuilder.withExternalRequestStorage(({ options }) => {
 			return createDatabaseContext(options, this.#schema).databaseAdapter.contextStorage;
 		}).withRequestStorage(({ options }) => {
-			return { uow: createDatabaseContext(options, this.#schema).db.createUnitOfWork() };
+			return { uow: createDatabaseContext(options, this.#schema).db.createBaseUnitOfWork() };
 		});
-		const internalFragmentFactory = baseDef.linkedFragments?.["_fragno_internal"];
 		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 cachedHooksConfig = depsKey ? hooksConfigCache.get(depsKey) : void 0;
-			if (cachedHooksConfig) return cachedHooksConfig;
 			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: this.#hooksFactory(context),
-				namespace: namespaceKey,
-				internalFragment: internalFragmentFactory({
+				hooks: context.services ? this.#hooksFactory({
 					config: context.config,
-					options: hookOptions
-				}),
+					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: () => {
-							const uow = dbContextForHooks.db.createUnitOfWork();
-							uow.registerSchema(hooksConfig.internalFragment.$internal.deps.schema, hooksConfig.internalFragment.$internal.deps.namespace);
-							return 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) => {
-							prepareHookMutations(uow, hooksConfig);
+							if (!planMode) prepareHookMutations(uow, hooksConfig.internalFragment, hooksConfig.defaultRetryPolicy);
 							if (userOnBeforeMutate) userOnBeforeMutate(uow);
 						},
 						onAfterMutate: async (uow) => {
-							hooksConfig.scheduler?.schedule().catch((error) => {
-								console.error("Durable hooks processing failed", error);
+							notifyDurableHooksAfterMutate({
+								uow,
+								hooksConfig,
+								internalFragment: hooksConfig.internalFragment,
+								autoSchedule,
+								planMode,
+								logContext: {
+									source: "hook",
+									waitUntil: getHookWaitUntil()
+								}
 							});
 							if (userOnAfterMutate) await userOnAfterMutate(uow);
 						}
-					});
+					}, 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.scheduler = createHookScheduler(hooksConfig);
+			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 internalFragment = hooksConfig?.internalFragment ?? (internalFragmentFactory ? internalFragmentFactory({
-				config,
-				options
-			}) : void 0);
+			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`.");
@@ -232,7 +475,36 @@ var DatabaseFragmentDefinitionBuilder = class DatabaseFragmentDefinitionBuilder
 				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;
-				return createHandlerTxBuilder({
+				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;
+				};
+				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();
@@ -240,27 +512,83 @@ var DatabaseFragmentDefinitionBuilder = class DatabaseFragmentDefinitionBuilder
 						return currentStorage.uow;
 					},
 					onBeforeMutate: (uow) => {
-						if (hooksConfig) prepareHookMutations(uow, hooksConfig);
+						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) => {
-						if (hooksConfig?.scheduler) hooksConfig.scheduler.schedule().catch((error) => {
-							console.error("Durable hooks processing failed", error);
+						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 }
+				handlerContext: {
+					handlerTx,
+					callServices
+				}
 			};
 		}).build();
-		if (this.#hooksFactory) finalDef.internalDataFactory = ({ config, options, deps }) => ({ durableHooks: createHooksConfig({
-			config,
-			options,
-			deps
-		}) });
+		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