@fragno-dev/db 0.3.0 → 0.4.1

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

@@ -1,36 +1,107 @@
-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 { FragnoApiError } from "@fragno-dev/core/api";
+
 import type {
   RequestThisContext,
   FragnoPublicConfig,
-  AnyFragnoInstantiatedFragment,
+  AnyRouteOrFactory,
+  FragnoRouteConfig,
+  BoundServices,
 } from "@fragno-dev/core";
 import {
   FragmentDefinitionBuilder,
   type FragmentDefinition,
   type ServiceConstructorFn,
 } from "@fragno-dev/core";
+
+import type { DatabaseAdapter, DatabaseContextStorage } from "./adapters/adapters";
+import type { InternalFragmentInstance } from "./fragments/internal-fragment";
+import { DurableHooksLogger } from "./hooks/durable-hooks-logger";
 import {
-  createServiceTxBuilder,
-  createHandlerTxBuilder,
-  ServiceTxBuilder,
-  HandlerTxBuilder,
-  type ExecuteTxOptions,
-} from "./query/unit-of-work/execute-unit-of-work";
+  getDurableHooksRuntimeByConfig,
+  getDurableHooksRuntimeByNamespace,
+  registerDurableHooksRuntime,
+} from "./hooks/durable-hooks-runtime";
 import {
   prepareHookMutations,
   type HooksMap,
   type HookFn,
   type HookContext,
   type HookProcessorConfig,
+  type HookNotifier,
+  type HookNotifyContext,
   type DurableHooksProcessingOptions,
-  createHookScheduler,
+  createDurableHooksRunner,
 } from "./hooks/hooks";
-import type { InternalFragmentInstance } from "./fragments/internal-fragment";
-import { resolveDatabaseAdapter } from "./util/default-database-adapter";
 import { sanitizeNamespace } from "./naming/sql-naming";
+import type { SimpleQueryInterface } from "./query/simple-query-interface";
+import {
+  createServiceTxBuilder,
+  createHandlerTxBuilder,
+  ServiceTxBuilder,
+  HandlerTxBuilder,
+  type AwaitedPromisesInObject,
+  type ExtractServiceFinalResults,
+  type ExecuteTxOptions,
+  type TxResult,
+} from "./query/unit-of-work/execute-unit-of-work";
+import type { IUnitOfWork } from "./query/unit-of-work/unit-of-work";
+import type { AnySchema } from "./schema/create";
+import type { SyncCommandRegistry, SyncCommandTargetRegistration } from "./sync/types";
+import { resolveDatabaseAdapter } from "./util/default-database-adapter";
+type RegistrySchemaInfo = {
+  name: string;
+  namespace: string | null;
+  version: number;
+  tables: string[];
+};
+
+type RegistryFragmentMeta = {
+  name: string;
+  mountRoute: string;
+};
+
+type ExtractServiceFinalResultOrSingle<T> = T extends readonly (
+  | TxResult<unknown, unknown>
+  | undefined
+)[]
+  ? AwaitedPromisesInObject<ExtractServiceFinalResults<T>>
+  : T extends undefined
+    ? undefined
+    : AwaitedPromisesInObject<ExtractServiceFinalResults<readonly [T]>>[0];
+
+type RegistryResolver = {
+  getRegistryForAdapterSync: <TUOWConfig>(adapter: DatabaseAdapter<TUOWConfig>) => {
+    registerSchema: (
+      schema: RegistrySchemaInfo,
+      fragment: RegistryFragmentMeta,
+      options?: { outboxEnabled?: boolean },
+    ) => void;
+    registerSyncCommands: (registration: SyncCommandTargetRegistration) => void;
+  };
+  getInternalFragment: <TUOWConfig>(
+    adapter: DatabaseAdapter<TUOWConfig>,
+  ) => InternalFragmentInstance;
+};
+
+type HooksFactoryContext<TConfig> = {
+  config: TConfig;
+  options: FragnoPublicConfigWithDatabase;
+  deps: unknown;
+  services: unknown;
+  serviceDeps: unknown;
+};
+
+type AnyHttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
+
+type AnyFragnoRouteConfig = FragnoRouteConfig<
+  AnyHttpMethod,
+  string,
+  undefined,
+  undefined,
+  string,
+  string,
+  RequestThisContext
+>;
 
 /**
  * Extended FragnoPublicConfig for database fragments.
@@ -39,6 +110,19 @@ import { sanitizeNamespace } from "./naming/sql-naming";
 export type FragnoPublicConfigWithDatabase = FragnoPublicConfig & {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   databaseAdapter?: DatabaseAdapter<any>;
+  /**
+   * Optional guard to limit database roundtrips per request (primarily for tests).
+   * When enabled, retrieve-only and mutate-only handlerTx().execute() calls are
+   * counted separately (one of each by default).
+   * Applied only for route handlers (not inContext).
+   */
+  dbRoundtripGuard?: boolean | DbRoundtripGuardConfig;
+  /**
+   * Optional outbox configuration for this fragment.
+   */
+  outbox?: {
+    enabled?: boolean;
+  };
   /**
    * Optional durable hooks processing configuration.
    */
@@ -51,16 +135,27 @@ export type FragnoPublicConfigWithDatabase = FragnoPublicConfig & {
   databaseNamespace?: string | null;
 };
 
+/**
+ * Configuration for limiting database roundtrips per request.
+ */
+export type DbRoundtripGuardConfig = {
+  /**
+   * Maximum allowed retrieve-only and mutate-only handlerTx().execute() calls per request.
+   * Each type is tracked separately.
+   * Defaults to 1 when the guard is enabled.
+   */
+  maxRoundtrips?: number;
+};
+
 /**
  * Implicit dependencies that database fragments get automatically.
  * These are injected without requiring explicit configuration.
  */
 export type ImplicitDatabaseDependencies<TSchema extends AnySchema> = {
   /**
-   * Database query engine for the fragment's schema.
-   * @deprecated Prefer handlerTx/serviceTx instead of direct db usage.
+   * Database adapter instance.
    */
-  db: SimpleQueryInterface<TSchema>;
+  databaseAdapter: DatabaseAdapter<any>; // eslint-disable-line @typescript-eslint/no-explicit-any
   /**
    * The schema definition for this fragment.
    */
@@ -137,19 +232,34 @@ export type DatabaseHandlerContext<THooks extends HooksMap = {}> = RequestThisCo
   handlerTx(
     options?: Omit<ExecuteTxOptions, "createUnitOfWork">,
   ): HandlerTxBuilder<readonly [], [], [], unknown, unknown, false, false, false, false, THooks>;
+
+  /**
+   * Execute multiple service calls in a handler context and return their final results.
+   */
+  callServices<
+    TServiceCalls extends
+      | TxResult<unknown, unknown>
+      | undefined
+      | readonly (TxResult<unknown, unknown> | undefined)[],
+  >(
+    /**
+     * Factory to create service calls inside the active context.
+     */
+    serviceCalls: () => TServiceCalls,
+  ): Promise<ExtractServiceFinalResultOrSingle<TServiceCalls>>;
 };
 
 /**
  * Database fragment context provided to user callbacks.
  */
-export type DatabaseFragmentContext<TSchema extends AnySchema> = {
+export type DatabaseFragmentContext = {
   /**
    * Database adapter instance.
    */
   databaseAdapter: DatabaseAdapter<any>; // eslint-disable-line @typescript-eslint/no-explicit-any
-  /**
-   * ORM query engine for the fragment's schema.
-   */
+};
+
+type DatabaseFragmentContextInternal<TSchema extends AnySchema> = DatabaseFragmentContext & {
   db: SimpleQueryInterface<TSchema>;
 };
 
@@ -160,7 +270,7 @@ export type DatabaseFragmentContext<TSchema extends AnySchema> = {
 function createDatabaseContext<TSchema extends AnySchema>(
   options: FragnoPublicConfigWithDatabase,
   schema: TSchema,
-): DatabaseFragmentContext<TSchema> {
+): DatabaseFragmentContextInternal<TSchema> {
   const databaseAdapter = resolveDatabaseAdapter(options, schema);
 
   const namespace = resolveDatabaseNamespace(options, schema);
@@ -177,6 +287,295 @@ function resolveDatabaseNamespace<TSchema extends AnySchema>(
   return hasOverride ? (options.databaseNamespace ?? null) : sanitizeNamespace(schema.name);
 }
 
+function resolveMountRoute(name: string, mountRoute?: string): string {
+  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";
+
+type DbRoundtripGuardState = {
+  retrieveCount: number;
+  mutateCount: number;
+  maxRoundtrips: number;
+};
+
+type DurableHooksLogContext = HookNotifyContext;
+
+type AnyHandlerTxBuilder = HandlerTxBuilder<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  any
+>;
+
+function wrapHandlerTxBuilderWithRoundtripGuard<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TBuilder extends HandlerTxBuilder<any, any, any, any, any, any, any, any, any, any>,
+>(builder: TBuilder, onExecute: () => void): TBuilder {
+  const wrappedBuilders = new WeakSet<AnyHandlerTxBuilder>();
+
+  const applyExecuteGuard = (target: TBuilder): TBuilder => {
+    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: TBuilder): TBuilder => {
+    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: unknown[]) => {
+          const result = value.apply(obj, args);
+          if (result instanceof HandlerTxBuilder) {
+            return wrap(result as TBuilder);
+          }
+          return result;
+        };
+      },
+    }) as TBuilder;
+  };
+
+  return wrap(builder);
+}
+
+function buildDurableHooksLogContext(context?: DurableHooksLogContext) {
+  const logContext: Record<string, unknown> = {};
+  if (context?.route !== undefined) {
+    logContext["route"] = context.route;
+  }
+  if (context?.source !== undefined) {
+    logContext["source"] = context.source;
+  }
+  return logContext;
+}
+
+function notifyDurableHooks(
+  notifier: HookNotifier,
+  namespace: string,
+  notifyContext: HookNotifyContext,
+  logContextFields: Record<string, unknown>,
+  options?: { crossNamespace?: boolean },
+) {
+  const crossNamespace = options?.crossNamespace ?? false;
+  const suffix = crossNamespace ? " (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 === undefined ? 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;
+  }
+  void notifyPromise;
+}
+
+function notifyDurableHooksAfterMutate<THooks extends HooksMap>({
+  uow,
+  hooksConfig,
+  internalFragment,
+  autoSchedule,
+  planMode,
+  logContext,
+}: {
+  uow: IUnitOfWork;
+  hooksConfig?: HookProcessorConfig<THooks>;
+  internalFragment?: InternalFragmentInstance;
+  autoSchedule: boolean;
+  planMode: boolean;
+  logContext?: DurableHooksLogContext;
+}) {
+  if (planMode) {
+    return;
+  }
+
+  const notifyContext: HookNotifyContext = {
+    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 = new Set<string>();
+  const triggeredCountByNamespace = new Map<string, number>();
+  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: FragnoPublicConfigWithDatabase,
+): DbRoundtripGuardState | null {
+  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: DatabaseContextStorage,
+  guard: DbRoundtripGuardState,
+): DbRoundtripGuardState {
+  const storageWithGuard = storage as DatabaseContextStorage & {
+    [dbRoundtripGuardStateSymbol]?: DbRoundtripGuardState;
+  };
+  if (!storageWithGuard[dbRoundtripGuardStateSymbol]) {
+    storageWithGuard[dbRoundtripGuardStateSymbol] = { ...guard };
+  } else {
+    storageWithGuard[dbRoundtripGuardStateSymbol]!.maxRoundtrips = guard.maxRoundtrips;
+  }
+  return storageWithGuard[dbRoundtripGuardStateSymbol]!;
+}
+
+function isRouteRequest(storage: DatabaseContextStorage): boolean {
+  const source = (storage as Record<symbol, unknown>)[requestSourceSymbol];
+  return source === "route";
+}
+
 /**
  * Storage type for database fragments - stores the Unit of Work.
  */
@@ -201,7 +600,7 @@ export class DatabaseFragmentDefinitionBuilder<
   THooks extends HooksMap = {},
   TServiceThisContext extends RequestThisContext = DatabaseHandlerContext,
   THandlerThisContext extends RequestThisContext = DatabaseHandlerContext,
-  TLinkedFragments extends Record<string, AnyFragnoInstantiatedFragment> = {},
+  TInternalRoutes extends readonly AnyRouteOrFactory[] = readonly [],
 > {
   // Store the base builder - we'll replace its storage and context setup when building
   #baseBuilder: FragmentDefinitionBuilder<
@@ -215,10 +614,12 @@ export class DatabaseFragmentDefinitionBuilder<
     TServiceThisContext,
     THandlerThisContext,
     DatabaseRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   >;
   #schema: TSchema;
-  #hooksFactory?: (context: { config: TConfig; options: FragnoPublicConfigWithDatabase }) => THooks;
+  #hooksFactory?: (context: HooksFactoryContext<TConfig>) => THooks;
+  #syncRegistry?: SyncCommandRegistry;
+  #registryResolver?: RegistryResolver;
 
   constructor(
     baseBuilder: FragmentDefinitionBuilder<
@@ -232,28 +633,28 @@ export class DatabaseFragmentDefinitionBuilder<
       TServiceThisContext,
       THandlerThisContext,
       DatabaseRequestStorage,
-      TLinkedFragments
+      TInternalRoutes
     >,
     schema: TSchema,
-    hooksFactory?: (context: {
-      config: TConfig;
-      options: FragnoPublicConfigWithDatabase;
-    }) => THooks,
+    hooksFactory?: (context: HooksFactoryContext<TConfig>) => THooks,
+    syncRegistry?: SyncCommandRegistry,
+    registryResolver?: 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<TNewDeps>(
     fn: (context: {
       config: TConfig;
       options: FragnoPublicConfigWithDatabase;
-      db: SimpleQueryInterface<TSchema>;
       databaseAdapter: DatabaseAdapter<any>; // eslint-disable-line @typescript-eslint/no-explicit-any
     }) => TNewDeps,
   ): DatabaseFragmentDefinitionBuilder<
@@ -267,7 +668,7 @@ export class DatabaseFragmentDefinitionBuilder<
     THooks,
     TServiceThisContext,
     THandlerThisContext,
-    TLinkedFragments
+    TInternalRoutes
   > {
     // Wrap user function to inject DB context
     const wrappedFn = (context: { config: TConfig; options: FragnoPublicConfigWithDatabase }) => {
@@ -278,14 +679,13 @@ export class DatabaseFragmentDefinitionBuilder<
       const userDeps = fn({
         config: context.config,
         options: context.options,
-        db: dbContext.db,
         databaseAdapter: dbContext.databaseAdapter,
       });
 
       // Create implicit dependencies
       const createUow = () => dbContext.db.createUnitOfWork();
       const implicitDeps: ImplicitDatabaseDependencies<TSchema> = {
-        db: dbContext.db,
+        databaseAdapter: dbContext.databaseAdapter,
         schema: this.#schema,
         namespace,
         createUnitOfWork: createUow,
@@ -300,7 +700,13 @@ export class DatabaseFragmentDefinitionBuilder<
     // Create new base builder with wrapped function
     const newBaseBuilder = this.#baseBuilder.withDependencies(wrappedFn);
 
-    return new DatabaseFragmentDefinitionBuilder(newBaseBuilder, this.#schema, this.#hooksFactory);
+    return new DatabaseFragmentDefinitionBuilder(
+      newBaseBuilder,
+      this.#schema,
+      this.#hooksFactory,
+      this.#syncRegistry,
+      this.#registryResolver,
+    );
   }
 
   providesBaseService<TNewService>(
@@ -324,11 +730,17 @@ export class DatabaseFragmentDefinitionBuilder<
     THooks,
     TServiceThisContext,
     THandlerThisContext,
-    TLinkedFragments
+    TInternalRoutes
   > {
     const newBaseBuilder = this.#baseBuilder.providesBaseService<TNewService>(fn);
 
-    return new DatabaseFragmentDefinitionBuilder(newBaseBuilder, this.#schema, this.#hooksFactory);
+    return new DatabaseFragmentDefinitionBuilder(
+      newBaseBuilder,
+      this.#schema,
+      this.#hooksFactory,
+      this.#syncRegistry,
+      this.#registryResolver,
+    );
   }
 
   providesService<TServiceName extends string, TService>(
@@ -353,14 +765,20 @@ export class DatabaseFragmentDefinitionBuilder<
     THooks,
     TServiceThisContext,
     THandlerThisContext,
-    TLinkedFragments
+    TInternalRoutes
   > {
     const newBaseBuilder = this.#baseBuilder.providesService<TServiceName, TService>(
       serviceName,
       fn,
     );
 
-    return new DatabaseFragmentDefinitionBuilder(newBaseBuilder, this.#schema, this.#hooksFactory);
+    return new DatabaseFragmentDefinitionBuilder(
+      newBaseBuilder,
+      this.#schema,
+      this.#hooksFactory,
+      this.#syncRegistry,
+      this.#registryResolver,
+    );
   }
 
   /**
@@ -392,14 +810,20 @@ export class DatabaseFragmentDefinitionBuilder<
     THooks,
     TServiceThisContext,
     THandlerThisContext,
-    TLinkedFragments
+    TInternalRoutes
   > {
     const newBaseBuilder = this.#baseBuilder.providesPrivateService<TServiceName, TService>(
       serviceName,
       fn,
     );
 
-    return new DatabaseFragmentDefinitionBuilder(newBaseBuilder, this.#schema, this.#hooksFactory);
+    return new DatabaseFragmentDefinitionBuilder(
+      newBaseBuilder,
+      this.#schema,
+      this.#hooksFactory,
+      this.#syncRegistry,
+      this.#registryResolver,
+    );
   }
 
   /**
@@ -423,6 +847,9 @@ export class DatabaseFragmentDefinitionBuilder<
     fn: (context: {
       config: TConfig;
       options: FragnoPublicConfigWithDatabase;
+      deps: TDeps;
+      services: BoundServices<TBaseServices & TServices>;
+      serviceDeps: TServiceDependencies;
       defineHook: <TPayload>(
         hook: (this: HookContext, payload: TPayload) => void | Promise<void>,
       ) => HookFn<TPayload>;
@@ -438,7 +865,7 @@ export class DatabaseFragmentDefinitionBuilder<
     TNewHooks,
     DatabaseServiceContext<TNewHooks>,
     THandlerThisContext,
-    TLinkedFragments
+    TInternalRoutes
   > {
     const defineHook = <TPayload>(
       hook: (this: HookContext, payload: TPayload) => void | Promise<void>,
@@ -447,13 +874,13 @@ export class DatabaseFragmentDefinitionBuilder<
     };
 
     // Store the hooks factory - it will be called in build() with config/options
-    const hooksFactory = (context: {
-      config: TConfig;
-      options: FragnoPublicConfigWithDatabase;
-    }) => {
+    const hooksFactory = (context: HooksFactoryContext<TConfig>) => {
       return fn({
         config: context.config,
         options: context.options,
+        deps: context.deps as TDeps,
+        services: context.services as BoundServices<TBaseServices & TServices>,
+        serviceDeps: context.serviceDeps as TServiceDependencies,
         defineHook,
       });
     };
@@ -463,6 +890,9 @@ export class DatabaseFragmentDefinitionBuilder<
     const newBuilder = new DatabaseFragmentDefinitionBuilder(
       this.#baseBuilder,
       this.#schema,
+      this.#hooksFactory,
+      this.#syncRegistry,
+      this.#registryResolver,
     ) as unknown as DatabaseFragmentDefinitionBuilder<
       TSchema,
       TConfig,
@@ -474,7 +904,7 @@ export class DatabaseFragmentDefinitionBuilder<
       TNewHooks,
       DatabaseServiceContext<TNewHooks>,
       THandlerThisContext,
-      TLinkedFragments
+      TInternalRoutes
     >;
 
     newBuilder.#hooksFactory = hooksFactory;
@@ -482,6 +912,39 @@ export class DatabaseFragmentDefinitionBuilder<
     return newBuilder;
   }
 
+  /**
+   * Register sync command definitions for this fragment.
+   */
+  withSyncCommands(
+    registry: SyncCommandRegistry,
+  ): DatabaseFragmentDefinitionBuilder<
+    TSchema,
+    TConfig,
+    TDeps,
+    TBaseServices,
+    TServices,
+    TServiceDependencies,
+    TPrivateServices,
+    THooks,
+    TServiceThisContext,
+    THandlerThisContext,
+    TInternalRoutes
+  > {
+    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.
@@ -499,11 +962,17 @@ export class DatabaseFragmentDefinitionBuilder<
     THooks,
     TServiceThisContext,
     THandlerThisContext,
-    TLinkedFragments
+    TInternalRoutes
   > {
     const newBaseBuilder = this.#baseBuilder.usesService<TServiceName, TService>(serviceName);
 
-    return new DatabaseFragmentDefinitionBuilder(newBaseBuilder, this.#schema, this.#hooksFactory);
+    return new DatabaseFragmentDefinitionBuilder(
+      newBaseBuilder,
+      this.#schema,
+      this.#hooksFactory,
+      this.#syncRegistry,
+      this.#registryResolver,
+    );
   }
 
   /**
@@ -523,13 +992,19 @@ export class DatabaseFragmentDefinitionBuilder<
     THooks,
     TServiceThisContext,
     THandlerThisContext,
-    TLinkedFragments
+    TInternalRoutes
   > {
     const newBaseBuilder = this.#baseBuilder.usesOptionalService<TServiceName, TService>(
       serviceName,
     );
 
-    return new DatabaseFragmentDefinitionBuilder(newBaseBuilder, this.#schema, this.#hooksFactory);
+    return new DatabaseFragmentDefinitionBuilder(
+      newBaseBuilder,
+      this.#schema,
+      this.#hooksFactory,
+      this.#syncRegistry,
+      this.#registryResolver,
+    );
   }
 
   /**
@@ -548,7 +1023,7 @@ export class DatabaseFragmentDefinitionBuilder<
     DatabaseServiceContext<THooks>,
     DatabaseHandlerContext<THooks>,
     DatabaseRequestStorage,
-    TLinkedFragments
+    TInternalRoutes
   > {
     const baseDef = this.#baseBuilder.build();
 
@@ -578,11 +1053,42 @@ export class DatabaseFragmentDefinitionBuilder<
         }
       }
 
-      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 = baseDef.name === "$fragno-internal-fragment";
+
+      if (!dryRun && !isInternalFragment && 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: ImplicitDatabaseDependencies<TSchema> = {
-        db,
+        databaseAdapter: dbContext.databaseAdapter,
         schema: this.#schema,
         namespace,
         createUnitOfWork: () => db.createUnitOfWork(),
@@ -608,20 +1114,12 @@ export class DatabaseFragmentDefinitionBuilder<
         // Create database context - needed here to create the UOW
         const dbContextForStorage = createDatabaseContext(options, this.#schema);
 
-        // Create a new Unit of Work for this request
-        const uow: IUnitOfWork = dbContextForStorage.db.createUnitOfWork();
+        const uow = dbContextForStorage.db.createBaseUnitOfWork();
 
         return { uow };
       },
     );
 
-    // Get the internal fragment factory from linked fragments (added by withDatabase)
-    // Cast is safe: withDatabase() guarantees this fragment exists and has the correct type
-    const internalFragmentFactory = baseDef.linkedFragments?.["_fragno_internal"] as (context: {
-      config: TConfig;
-      options: FragnoPublicConfigWithDatabase;
-    }) => InternalFragmentInstance;
-
     // Cache per instantiated fragment (deps object is unique per instantiation).
     const hooksConfigCache = new WeakMap<object, HookProcessorConfig<THooks>>();
 
@@ -629,6 +1127,8 @@ export class DatabaseFragmentDefinitionBuilder<
       config: TConfig;
       options: FragnoPublicConfigWithDatabase;
       deps: TDeps;
+      services?: BoundServices<TBaseServices & TServices>;
+      serviceDeps?: TServiceDependencies;
     }) => {
       if (!this.#hooksFactory) {
         return undefined;
@@ -637,76 +1137,148 @@ export class DatabaseFragmentDefinitionBuilder<
         typeof context.deps === "object" && context.deps !== null
           ? (context.deps as object)
           : undefined;
+      const namespace = resolveDatabaseNamespace(context.options, this.#schema);
+      const namespaceKey = namespace ?? this.#schema.name;
+      const durableHooksOptions = context.options.durableHooks;
+      DurableHooksLogger.configure(durableHooksOptions?.logging, namespaceKey);
       const cachedHooksConfig = depsKey ? hooksConfigCache.get(depsKey) : undefined;
       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 ?? ({} as TServiceDependencies),
+          });
+        }
         return cachedHooksConfig;
       }
 
-      const namespace = resolveDatabaseNamespace(context.options, this.#schema);
-      const namespaceKey = namespace ?? this.#schema.name;
-      const durableHooksOptions = context.options.durableHooks;
+      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: HookProcessorConfig<THooks> = {
-        hooks: this.#hooksFactory(context),
+        hooks: context.services
+          ? this.#hooksFactory({
+              config: context.config,
+              options: context.options,
+              deps: context.deps,
+              services: context.services,
+              serviceDeps: context.serviceDeps ?? ({} as TServiceDependencies),
+            })
+          : undefined,
         namespace: namespaceKey,
-        internalFragment: internalFragmentFactory({
-          config: context.config,
-          options: hookOptions,
-        }),
+        internalFragment: registryResolver.getInternalFragment(hookAdapter),
+        autoSchedule,
         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);
+          const planMode = execOptions?.planMode ?? false;
+          let storageRef: DatabaseContextStorage | null = null;
+          const getHookWaitUntil = () => {
+            if (!hookContextStorage.hasStore()) {
+              return undefined;
+            }
+            return (
+              hookContextStorage.getStore() as DatabaseContextStorage & {
+                [requestWaitUntilSymbol]?: (promise: Promise<unknown>) => void;
               }
+            )[requestWaitUntilSymbol];
+          };
+          return createHandlerTxBuilder<THooks>(
+            {
+              ...execOptions,
+              createUnitOfWork: () => {
+                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 (!planMode) {
+                  prepareHookMutations(
+                    uow,
+                    hooksConfig.internalFragment,
+                    hooksConfig.defaultRetryPolicy,
+                  );
+                }
+                if (userOnBeforeMutate) {
+                  userOnBeforeMutate(uow);
+                }
+              },
+              onAfterMutate: async (uow) => {
+                notifyDurableHooksAfterMutate({
+                  uow,
+                  hooksConfig,
+                  internalFragment: hooksConfig.internalFragment,
+                  autoSchedule,
+                  planMode,
+                  logContext: { source: "hook", waitUntil: getHookWaitUntil() },
+                });
+                if (userOnAfterMutate) {
+                  await userOnAfterMutate(uow);
+                }
+              },
             },
-          });
+            undefined,
+            (run) =>
+              hookContextStorage.runWithInitializer(() => {
+                const inheritedWaitUntil = getHookWaitUntil();
+                storageRef = { uow: null as unknown as DatabaseContextStorage["uow"] };
+                if (inheritedWaitUntil) {
+                  (
+                    storageRef as DatabaseContextStorage & {
+                      [requestWaitUntilSymbol]?: (promise: Promise<unknown>) => void;
+                    }
+                  )[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 builderWithContext = builderWithStorage.withThisContext<
       DatabaseServiceContext<THooks>,
       DatabaseHandlerContext<THooks>
     >(({ storage, config, options, deps }) => {
       // Create hooks config if hooks factory is defined
       const hooksConfig = createHooksConfig({ config, options, deps });
-      const internalFragment =
-        hooksConfig?.internalFragment ??
-        (internalFragmentFactory ? internalFragmentFactory({ config, options }) : undefined);
+      const autoSchedule = options.durableHooks?.autoSchedule !== false;
+      const registryResolver = this.#registryResolver;
+      const databaseAdapter =
+        (deps as ImplicitDatabaseDependencies<TSchema>).databaseAdapter ??
+        resolveDatabaseAdapter(options, this.#schema);
+      const internalFragment = isInternalFragment
+        ? undefined
+        : (hooksConfig?.internalFragment ?? registryResolver?.getInternalFragment(databaseAdapter));
 
       // Builder API: serviceTx using createServiceTxBuilder
       function serviceTx<TSchema extends AnySchema>(schema: TSchema) {
@@ -734,8 +1306,75 @@ export class DatabaseFragmentDefinitionBuilder<
 
         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 as DatabaseContextStorage & {
+            [requestRouteSymbol]?: { method?: string; path?: string };
+          }
+        )[requestRouteSymbol];
+        const routeWaitUntil = (
+          currentStorage as DatabaseContextStorage & {
+            [requestWaitUntilSymbol]?: (promise: Promise<unknown>) => void;
+          }
+        )[requestWaitUntilSymbol];
+        const routeLabel =
+          routeInfo && routeInfo.method && routeInfo.path
+            ? `${routeInfo.method} ${routeInfo.path}`
+            : null;
+        const routeSuffix = routeLabel ? ` (route: ${routeLabel})` : "";
+        const buildRoundtripError = (kind: "retrieve" | "mutate") =>
+          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;
 
-        return createHandlerTxBuilder<THooks>({
+        const resetRoundtripExecutionState = () => {
+          if (!roundtripExecutionState) {
+            return;
+          }
+          roundtripExecutionState.countedRetrieve = false;
+          roundtripExecutionState.countedMutate = false;
+        };
+
+        const guardOnAfterRetrieve = roundtripState
+          ? async (uow: IUnitOfWork, results: unknown[]) => {
+              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<THooks>({
           ...execOptions,
           createUnitOfWork: () => {
             currentStorage.uow.reset();
@@ -748,28 +1387,110 @@ export 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) {
-              void 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
+              ) {
+                const hasHooks = uow
+                  .getTriggeredHooks()
+                  .some((hook) => hook.namespace === hooksConfig.namespace);
+                if (hasHooks) {
+                  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) {
+          const guardedBuilder = wrapHandlerTxBuilderWithRoundtripGuard(
+            builder,
+            resetRoundtripExecutionState,
+          );
+          return guardedBuilder;
+        }
+
+        return builder;
+      }
+
+      function callServices<
+        TServiceCalls extends
+          | TxResult<unknown, unknown>
+          | undefined
+          | readonly (TxResult<unknown, unknown> | undefined)[],
+      >(
+        serviceCalls: () => TServiceCalls,
+      ): Promise<ExtractServiceFinalResultOrSingle<TServiceCalls>> {
+        let callWasArray = false;
+        const resultPromise = handlerTx()
+          .withServiceCalls(() => {
+            const calls = serviceCalls();
+            callWasArray = Array.isArray(calls);
+            return (callWasArray ? calls : [calls]) as readonly (
+              | TxResult<unknown, unknown>
+              | undefined
+            )[];
+          })
+          .execute();
+
+        return resultPromise.then((result) =>
+          callWasArray
+            ? (result as ExtractServiceFinalResultOrSingle<TServiceCalls>)
+            : (
+                result as AwaitedPromisesInObject<
+                  ExtractServiceFinalResults<readonly [TServiceCalls]>
+                >
+              )[0],
+        ) as Promise<ExtractServiceFinalResultOrSingle<TServiceCalls>>;
       }
 
       const handlerContext: DatabaseHandlerContext<THooks> = {
         handlerTx,
+        callServices,
       };
 
       return { serviceContext, handlerContext };
@@ -778,13 +1499,39 @@ export class DatabaseFragmentDefinitionBuilder<
     // Build the final definition
     const finalDef = builderWithContext.build();
     if (this.#hooksFactory) {
-      finalDef.internalDataFactory = ({ config, options, deps }) => ({
-        durableHooks: createHooksConfig({
+      finalDef.internalDataFactory = ({ config, options, deps, services, serviceDeps }) => {
+        const hooksConfig = createHooksConfig({
           config: config as TConfig,
           options: options as FragnoPublicConfigWithDatabase,
           deps: deps as TDeps,
-        }),
-      });
+          services: services as BoundServices<TBaseServices & TServices>,
+          serviceDeps: serviceDeps as TServiceDependencies,
+        });
+        if (!hooksConfig) {
+          return {};
+        }
+        return {
+          durableHooksToken: registerDurableHooksRuntime(hooksConfig),
+        };
+      };
+    }
+    if (this.#registryResolver) {
+      const registryInternalRoutes = ({ deps }: { deps: TDeps }) => {
+        const databaseAdapter = (deps as ImplicitDatabaseDependencies<TSchema>).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 ?? []) as readonly AnyFragnoRouteConfig[];
+      };
+      const mergedInternalRoutes = [
+        ...(finalDef.internalRoutes ?? []),
+        registryInternalRoutes,
+      ] as readonly AnyRouteOrFactory[];
+      finalDef.internalRoutes = mergedInternalRoutes as TInternalRoutes;
     }
 
     // Return the complete definition with proper typing and dependencies