@fragno-dev/db 0.3.0 → 0.4.1

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

@@ -1,19 +1,34 @@
+import { describe, it, expect, vi, expectTypeOf } from "vitest";
+
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { describe, it, expect, vi, expectTypeOf } from "vitest";
-import { defineFragment } from "@fragno-dev/core";
+
+import { RequestContextStorage } from "@fragno-dev/core/internal/request-context-storage";
+import SQLite from "better-sqlite3";
+import { SqliteDialect } from "kysely";
+
+import { defineFragment, instantiate } from "@fragno-dev/core";
+
+import type { DatabaseAdapter, DatabaseContextStorage } from "./adapters/adapters";
+import { BetterSQLite3DriverConfig } from "./adapters/generic-sql/driver-config";
+import { SqlAdapter } from "./adapters/generic-sql/generic-sql-adapter";
 import {
   DatabaseFragmentDefinitionBuilder,
   type ImplicitDatabaseDependencies,
 } from "./db-fragment-definition-builder";
-import { withDatabase } from "./with-database";
-import { schema, column, idColumn } from "./schema/create";
+import { internalSchema } from "./fragments/internal-fragment";
+import { getDurableHooksRuntimeByToken } from "./hooks/durable-hooks-runtime";
+import type { HookFn } from "./hooks/hooks";
+import * as hooks from "./hooks/hooks";
+import { getInternalFragment, getRegistryForAdapterSync } from "./internal/adapter-registry";
+import { suffixNamingStrategy, sanitizeNamespace } from "./naming/sql-naming";
 import type { SimpleQueryInterface } from "./query/simple-query-interface";
-import type { DatabaseAdapter } from "./adapters/adapters";
 import * as executeUnitOfWork from "./query/unit-of-work/execute-unit-of-work";
-import { RequestContextStorage } from "@fragno-dev/core/internal/request-context-storage";
-import { suffixNamingStrategy } from "./naming/sql-naming";
+import type { IUnitOfWork } from "./query/unit-of-work/unit-of-work";
+import { schema, column, idColumn } from "./schema/create";
+import { defineSyncCommands } from "./sync/commands";
+import { withDatabase } from "./with-database";
 
 // Create a test schema
 const testSchema = schema("test", (s) => {
@@ -29,14 +44,17 @@ type TestSchema = typeof testSchema;
 
 // Mock database adapter
 function createMockAdapter(): DatabaseAdapter {
+  const createMockUow = () => ({
+    forSchema: vi.fn(),
+    executeRetrieve: vi.fn(),
+    executeMutations: vi.fn(),
+    registerSchema: vi.fn(),
+    reset: vi.fn(),
+  });
+
   const mockdb = {
-    createUnitOfWork: vi.fn(() => ({
-      forSchema: vi.fn(),
-      executeRetrieve: vi.fn(),
-      executeMutations: vi.fn(),
-      registerSchema: vi.fn(),
-      reset: vi.fn(),
-    })),
+    createUnitOfWork: vi.fn(() => createMockUow()),
+    createBaseUnitOfWork: vi.fn(() => createMockUow()),
   } as unknown as SimpleQueryInterface<TestSchema>;
 
   return {
@@ -87,8 +105,8 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
 
       const definition = defineFragment("test-frag")
         .extend(withDatabase(testSchema))
-        .withDependencies(({ db }) => {
-          expect(db).toBeDefined();
+        .withDependencies(({ databaseAdapter }) => {
+          expect(databaseAdapter).toBeDefined();
           return {
             customDep: "value",
           };
@@ -101,7 +119,8 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
       });
 
       expect(deps.customDep).toBe("value");
-      expect(deps.db).toBeDefined();
+      expect(deps.databaseAdapter).toBeDefined();
+      expect(deps.createUnitOfWork).toBeDefined();
       expect(deps.schema).toBeDefined();
     });
 
@@ -121,7 +140,8 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
       });
 
       expect(deps.apiKey).toBe("key123");
-      expect(deps.db).toBeDefined();
+      expect(deps.databaseAdapter).toBeDefined();
+      expect(deps.createUnitOfWork).toBeDefined();
       expect(deps.schema).toBeDefined();
     });
 
@@ -131,7 +151,7 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
       const definition = defineFragment("test-frag")
         .extend(withDatabase(testSchema))
         .providesService("users", ({ deps }) => {
-          expect(deps.db).toBeDefined();
+          expect(deps.databaseAdapter).toBeDefined();
           return {
             list: () => "users list",
           };
@@ -164,7 +184,7 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
         }))
         .extend(withDatabase(testSchema))
         .providesService("users", ({ deps }) => {
-          expect(deps.db).toBeDefined();
+          expect(deps.databaseAdapter).toBeDefined();
           return {
             list: () => "users list",
           };
@@ -238,7 +258,7 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
       const definition = defineFragment("test-frag")
         .extend(withDatabase(testSchema))
         .providesBaseService(({ deps }) => {
-          expect(deps.db).toBeDefined();
+          expect(deps.databaseAdapter).toBeDefined();
           return {
             healthCheck: () => "healthy",
           };
@@ -271,7 +291,7 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
         }))
         .extend(withDatabase(testSchema))
         .providesBaseService(({ deps }) => {
-          expect(deps.db).toBeDefined();
+          expect(deps.databaseAdapter).toBeDefined();
           return {
             status: () => "ok",
           };
@@ -306,8 +326,8 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
 
       const definition = defineFragment("test-frag")
         .extend(withDatabase(testSchema))
-        .withDependencies(({ db }) => {
-          expect(db).toBeDefined();
+        .withDependencies(({ databaseAdapter }) => {
+          expect(databaseAdapter).toBeDefined();
           return {
             apiKey: "secret",
           };
@@ -322,7 +342,7 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
           },
         }))
         .providesService("data", ({ deps }) => {
-          expect(deps.db).toBeDefined();
+          expect(deps.databaseAdapter).toBeDefined();
           return {
             fetch: () => `Fetching with ${deps.apiKey}`,
           };
@@ -375,15 +395,15 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
           baseConfig: "config1",
         }))
         .extend(withDatabase(testSchema))
-        .withDependencies(({ db }) => {
-          expect(db).toBeDefined();
+        .withDependencies(({ databaseAdapter }) => {
+          expect(databaseAdapter).toBeDefined();
           // Second withDependencies replaces the first one
           return {
             enhancedConfig: "enhanced",
           };
         })
         .providesService("combined", ({ deps }) => {
-          expect(deps.db).toBeDefined();
+          expect(deps.databaseAdapter).toBeDefined();
           return {
             getConfig: () => deps.enhancedConfig,
           };
@@ -398,7 +418,7 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
       // Only the second withDependencies is used (plus implicit deps)
       expect(deps).not.toHaveProperty("baseConfig");
       expect(deps.enhancedConfig).toBe("enhanced");
-      expect(deps.db).toBeDefined();
+      expect(deps.databaseAdapter).toBeDefined();
 
       const combinedService = definition.namedServices!.combined({
         config: {},
@@ -428,9 +448,9 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
           };
         })
         .extend(withDatabase(testSchema))
-        .withDependencies(({ config, db }) => {
+        .withDependencies(({ config, databaseAdapter }) => {
           expectTypeOf(config).toExtend<MyConfig>();
-          expect(db).toBeDefined();
+          expect(databaseAdapter).toBeDefined();
           // Second withDependencies replaces the first, so combine them here
           return {
             connectionTimeout: config.timeout,
@@ -446,7 +466,7 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
 
       expect(deps.connectionTimeout).toBe(5000);
       expect(deps.dbConnectionString).toBe("postgres://localhost");
-      expect(deps.db).toBeDefined();
+      expect(deps.databaseAdapter).toBeDefined();
     });
 
     it("recommended pattern: extend first then configure", () => {
@@ -463,8 +483,8 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
       // Best practice: .extend() early, then add all your features
       const definition = defineFragment("best-practice")
         .extend(withDatabase(testSchema))
-        .withDependencies(({ db }) => {
-          expect(db).toBeDefined();
+        .withDependencies(({ databaseAdapter }) => {
+          expect(databaseAdapter).toBeDefined();
           return {
             apiKey: "secret",
             timeout: 5000,
@@ -474,7 +494,7 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
         .usesOptionalService<"auth", AuthService>("auth")
         .providesBaseService(({ deps }) => ({
           healthCheck: () => {
-            expect(deps.db).toBeDefined();
+            expect(deps.databaseAdapter).toBeDefined();
             return `OK (timeout: ${deps.timeout})`;
           },
         }))
@@ -497,7 +517,7 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
       // Verify all dependencies including implicit ones
       expect(deps.apiKey).toBe("secret");
       expect(deps.timeout).toBe(5000);
-      expect(deps.db).toBeDefined();
+      expect(deps.databaseAdapter).toBeDefined();
       expect(deps.schema).toBeDefined();
       expect(deps.createUnitOfWork).toBeDefined();
 
@@ -537,8 +557,7 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
       const mockAdapter = createMockAdapter();
 
       const definition = withDatabase(testSchema)(defineFragment("db-frag"))
-        .withDependencies(({ db, databaseAdapter }) => {
-          expect(db).toBeDefined();
+        .withDependencies(({ databaseAdapter }) => {
           expect(databaseAdapter).toBeDefined();
           return {
             customDep: "test",
@@ -555,7 +574,7 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
       });
 
       // Should have implicit deps
-      expect(deps).toHaveProperty("db");
+      expect(deps).toHaveProperty("databaseAdapter");
       expect(deps).toHaveProperty("schema");
       expect(deps).toHaveProperty("createUnitOfWork");
       expect(deps).toHaveProperty("customDep");
@@ -576,7 +595,7 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
       });
 
       // Check implicit dependencies structure
-      expect(deps.db).toBeDefined();
+      expect(deps.databaseAdapter).toBeDefined();
       expect(deps.schema).toBeDefined();
       expect(typeof deps.createUnitOfWork).toBe("function");
     });
@@ -590,7 +609,7 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
         .withDependencies(() => ({ apiKey: "key" }))
         .providesBaseService(({ deps, defineService }) => {
           expect(deps.apiKey).toBe("key");
-          expect(deps.db).toBeDefined();
+          expect(deps.databaseAdapter).toBeDefined();
           expect(defineService).toBeDefined();
 
           return defineService({
@@ -687,6 +706,43 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
     });
   });
 
+  describe("withSyncCommands", () => {
+    it("registers sync commands in adapter registry", async () => {
+      const sqlite = new SQLite(":memory:");
+      const adapter = new SqlAdapter({
+        dialect: new SqliteDialect({ database: sqlite }),
+        driverConfig: new BetterSQLite3DriverConfig(),
+      });
+
+      const registry = getRegistryForAdapterSync(adapter);
+      const syncCommands = defineSyncCommands({ schema: testSchema }).create(
+        ({ defineCommand }) => [
+          defineCommand({
+            name: "ping",
+            handler: async () => undefined,
+          }),
+        ],
+      );
+
+      const definition = defineFragment("sync-frag")
+        .extend(withDatabase(testSchema))
+        .withSyncCommands(syncCommands)
+        .build();
+
+      definition.dependencies!({
+        config: {},
+        options: { databaseAdapter: adapter },
+      });
+
+      const resolved = registry.resolveSyncCommand("sync-frag", testSchema.name, "ping");
+      expect(resolved?.command).toBe(syncCommands.commands.get("ping"));
+      expect(resolved?.namespace).toBe(sanitizeNamespace(testSchema.name));
+
+      await adapter.close();
+      sqlite.close();
+    });
+  });
+
   describe("createRequestStorage and createThisContext", () => {
     it("should create request storage with UnitOfWork", () => {
       const mockAdapter = createMockAdapter();
@@ -826,7 +882,7 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
           options: {},
         });
 
-        expect(deps.db).toBeDefined();
+        expect(deps.databaseAdapter).toBeDefined();
         expect(deps.createUnitOfWork).toBeDefined();
       } finally {
         if (previous === undefined) {
@@ -860,7 +916,7 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
       >();
 
       expect(deps.customDep).toBe("test");
-      expect(deps.db).toBeDefined();
+      expect(deps.databaseAdapter).toBeDefined();
     });
   });
 
@@ -888,21 +944,31 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
         getStore: () => ({
           uow: mockAdapter.createQueryEngine(testSchema, "test").createUnitOfWork(),
         }),
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      } as any;
+      } as unknown as RequestContextStorage<DatabaseContextStorage>;
 
       // Spy on createServiceTxBuilder
       const createServiceTxBuilderSpy = vi.spyOn(executeUnitOfWork, "createServiceTxBuilder");
 
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const deps = {} as any;
+
       // Get the contexts which includes serviceTx
       const contexts = definition.createThisContext!({
         config: {},
         options: { databaseAdapter: mockAdapter },
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        deps: {} as any,
+        deps,
         storage: mockStorage,
       });
 
+      // Initialize hooks with services so serviceTx receives the hooks map.
+      definition.internalDataFactory?.({
+        config: {},
+        options: { databaseAdapter: mockAdapter },
+        deps,
+        services: {} as Record<string, never>,
+        serviceDeps: {} as Record<string, never>,
+      });
+
       // Call serviceTx - this should pass hooks to createServiceTxBuilder
       contexts.serviceContext.serviceTx(testSchema);
 
@@ -918,4 +984,712 @@ describe("DatabaseFragmentDefinitionBuilder", () => {
       createServiceTxBuilderSpy.mockRestore();
     });
   });
+
+  describe("provideHooks services access", () => {
+    it("should provide bound services to hooks factory", () => {
+      const mockAdapter = createMockAdapter();
+      let observed: string | null = null;
+
+      type TestHooks = {
+        onPing: HookFn;
+      };
+
+      const definition = defineFragment("db-frag-hooks-services")
+        .extend(withDatabase(testSchema))
+        .providesBaseService(() => ({
+          ping: () => "pong",
+        }))
+        .provideHooks<TestHooks>(({ defineHook, services }) => {
+          observed = services.ping();
+          return {
+            onPing: defineHook(async function () {
+              // no-op
+            }),
+          };
+        })
+        .build();
+
+      const deps = definition.dependencies!({
+        config: {},
+        options: { databaseAdapter: mockAdapter },
+      });
+
+      const internalData = definition.internalDataFactory?.({
+        config: {},
+        options: { databaseAdapter: mockAdapter },
+        deps,
+        services: { ping: () => "pong" },
+        serviceDeps: {},
+      }) as { durableHooksToken?: object } | undefined;
+
+      expect(observed).toBe("pong");
+      expect(internalData?.durableHooksToken).toBeDefined();
+      const runtime = internalData?.durableHooksToken
+        ? getDurableHooksRuntimeByToken(internalData.durableHooksToken)
+        : undefined;
+      expect(runtime?.config.hooks).toBeDefined();
+      expect(runtime?.config.hooks).toHaveProperty("onPing");
+    });
+  });
+
+  describe("durable hooks waitUntil forwarding", () => {
+    it("forwards request waitUntil to notifier context", async () => {
+      const mockAdapter = createMockAdapter();
+      const requestSourceSymbol = Symbol.for("fragno-request-source");
+      const requestRouteSymbol = Symbol.for("fragno-request-route");
+      const requestWaitUntilSymbol = Symbol.for("fragno-request-wait-until");
+      const notifySpy = vi.fn().mockResolvedValue(undefined);
+      const waitUntilSpy = vi.fn();
+
+      type TestHooks = {
+        onPing: HookFn<{ value: string }>;
+      };
+
+      const definition = defineFragment("db-frag-hooks-waituntil")
+        .extend(withDatabase(testSchema))
+        .provideHooks<TestHooks>(({ defineHook }) => ({
+          onPing: defineHook(async function () {
+            // no-op
+          }),
+        }))
+        .build();
+
+      const deps = definition.dependencies!({
+        config: {},
+        options: { databaseAdapter: mockAdapter },
+      });
+
+      const internalData = definition.internalDataFactory?.({
+        config: {},
+        options: { databaseAdapter: mockAdapter },
+        deps,
+        services: {} as Record<string, never>,
+        serviceDeps: {} as Record<string, never>,
+      }) as { durableHooksToken?: object } | undefined;
+
+      const runtime = internalData?.durableHooksToken
+        ? getDurableHooksRuntimeByToken(internalData.durableHooksToken)
+        : undefined;
+      if (!runtime) {
+        throw new Error("Durable hooks runtime missing");
+      }
+      runtime.config.notifier = {
+        notify: notifySpy,
+      };
+
+      const createHandlerTxBuilderSpy = vi
+        .spyOn(executeUnitOfWork, "createHandlerTxBuilder")
+        .mockReturnValue(
+          {} as unknown as ReturnType<typeof executeUnitOfWork.createHandlerTxBuilder>,
+        );
+
+      const mockStorage = {
+        getStore: () => ({
+          uow: mockAdapter.createQueryEngine(testSchema, "test").createUnitOfWork(),
+          [requestSourceSymbol]: "route",
+          [requestRouteSymbol]: { method: "POST", path: "/users" },
+          [requestWaitUntilSymbol]: waitUntilSpy,
+        }),
+      } as unknown as RequestContextStorage<DatabaseContextStorage>;
+
+      const contexts = definition.createThisContext!({
+        config: {},
+        options: { databaseAdapter: mockAdapter },
+        deps,
+        storage: mockStorage,
+      });
+
+      contexts.handlerContext.handlerTx();
+      const callArgs = createHandlerTxBuilderSpy.mock.calls[0]?.[0];
+      const mockUow = {
+        getTriggeredHooks: () => [
+          {
+            namespace: runtime.config.namespace,
+            hookName: "onPing",
+            payload: { value: "ping" },
+          },
+        ],
+      } as unknown as IUnitOfWork;
+      await callArgs?.onAfterMutate?.(mockUow);
+
+      expect(notifySpy).toHaveBeenCalledTimes(1);
+      const notifyContext = notifySpy.mock.calls[0]?.[0] as
+        | { route?: string; source?: string; waitUntil?: unknown }
+        | undefined;
+      expect(notifyContext).toMatchObject({
+        source: "request",
+        route: "POST /users",
+      });
+      expect(notifyContext?.waitUntil).toBe(waitUntilSpy);
+      expect(waitUntilSpy).toHaveBeenCalledTimes(1);
+
+      createHandlerTxBuilderSpy.mockRestore();
+    });
+
+    it("forwards inherited request waitUntil for hook mutations", async () => {
+      const mockAdapter = createMockAdapter();
+      const requestWaitUntilSymbol = Symbol.for("fragno-request-wait-until");
+      const notifySpy = vi.fn().mockResolvedValue(undefined);
+      const waitUntilSpy = vi.fn();
+
+      type TestHooks = {
+        onPing: HookFn<{ value: string }>;
+      };
+
+      const definition = defineFragment("db-frag-hooks-hook-waituntil")
+        .extend(withDatabase(testSchema))
+        .provideHooks<TestHooks>(({ defineHook }) => ({
+          onPing: defineHook(async function () {
+            // no-op
+          }),
+        }))
+        .build();
+
+      const deps = definition.dependencies!({
+        config: {},
+        options: { databaseAdapter: mockAdapter },
+      });
+
+      const internalData = definition.internalDataFactory?.({
+        config: {},
+        options: { databaseAdapter: mockAdapter },
+        deps,
+        services: {} as Record<string, never>,
+        serviceDeps: {} as Record<string, never>,
+      }) as { durableHooksToken?: object } | undefined;
+
+      const runtime = internalData?.durableHooksToken
+        ? getDurableHooksRuntimeByToken(internalData.durableHooksToken)
+        : undefined;
+      if (!runtime) {
+        throw new Error("Durable hooks runtime missing");
+      }
+      runtime.config.notifier = {
+        notify: notifySpy,
+      };
+
+      const createHandlerTxBuilderSpy = vi
+        .spyOn(executeUnitOfWork, "createHandlerTxBuilder")
+        .mockImplementation((options) => {
+          return {
+            execute: vi.fn(async () => {
+              const mockUow = {
+                getTriggeredHooks: () => [
+                  {
+                    namespace: runtime.config.namespace,
+                    hookName: "onPing",
+                    payload: { value: "ping" },
+                  },
+                ],
+              } as unknown as IUnitOfWork;
+              await options.onAfterMutate?.(mockUow);
+            }),
+          } as unknown as ReturnType<typeof executeUnitOfWork.createHandlerTxBuilder>;
+        });
+
+      try {
+        const storage = mockAdapter.contextStorage as RequestContextStorage<DatabaseContextStorage>;
+        await storage.runWithInitializer(
+          () =>
+            ({
+              uow: mockAdapter.createQueryEngine(testSchema, "test").createUnitOfWork(),
+              [requestWaitUntilSymbol]: waitUntilSpy,
+            }) as DatabaseContextStorage,
+          async () => {
+            await runtime.config.handlerTx().execute();
+          },
+        );
+
+        expect(notifySpy).toHaveBeenCalledTimes(1);
+        const notifyContext = notifySpy.mock.calls[0]?.[0] as
+          | { source?: string; waitUntil?: unknown }
+          | undefined;
+        expect(notifyContext?.source).toBe("hook");
+        expect(notifyContext?.waitUntil).toBe(waitUntilSpy);
+        expect(waitUntilSpy).toHaveBeenCalledTimes(1);
+      } finally {
+        createHandlerTxBuilderSpy.mockRestore();
+      }
+    });
+  });
+
+  describe("durable hooks cross-namespace scheduling", () => {
+    it("should schedule hooks triggered in another namespace when mutation runs inside a hook", async () => {
+      const sqlite = new SQLite(":memory:");
+      const adapter = new SqlAdapter({
+        dialect: new SqliteDialect({ database: sqlite }),
+        driverConfig: new BetterSQLite3DriverConfig(),
+      });
+
+      const schemaA = schema("hooks_alpha", (s) =>
+        s.addTable("items", (t) =>
+          t.addColumn("id", idColumn()).addColumn("name", column("string")),
+        ),
+      );
+      const schemaB = schema("hooks_beta", (s) =>
+        s.addTable("items", (t) =>
+          t.addColumn("id", idColumn()).addColumn("name", column("string")),
+        ),
+      );
+
+      type HooksA = {
+        onAlpha: (payload: { value: string }) => void;
+      };
+      type HooksB = {
+        onBeta: (payload: { value: string }) => void;
+      };
+
+      const hooksB: HooksB = {
+        onBeta: () => {},
+      };
+
+      const namespaceA = sanitizeNamespace(schemaA.name);
+      const namespaceB = sanitizeNamespace(schemaB.name);
+
+      const fragmentADef = defineFragment("frag-hooks-a")
+        .extend(withDatabase(schemaA))
+        .provideHooks<HooksA>(({ defineHook }) => ({
+          onAlpha: defineHook(async function () {
+            await this.handlerTx({
+              onBeforeMutate: (uow) => {
+                uow.registerSchema(schemaB, namespaceB);
+              },
+            })
+              .mutate(({ forSchema }) => {
+                const other = forSchema(schemaB, hooksB);
+                other.triggerHook("onBeta", { value: "beta" });
+              })
+              .execute();
+          }),
+        }))
+        .build();
+
+      const fragmentBDef = defineFragment("frag-hooks-b")
+        .extend(withDatabase(schemaB))
+        .provideHooks<HooksB>(({ defineHook }) => ({
+          onBeta: defineHook(async function () {
+            // no-op
+          }),
+        }))
+        .build();
+
+      try {
+        const internalMigrations = adapter.prepareMigrations(internalSchema, null);
+        await internalMigrations.executeWithDriver(adapter.driver, 0);
+
+        const migrationsA = adapter.prepareMigrations(schemaA, namespaceA);
+        await migrationsA.executeWithDriver(adapter.driver, 0);
+
+        const migrationsB = adapter.prepareMigrations(schemaB, namespaceB);
+        await migrationsB.executeWithDriver(adapter.driver, 0);
+
+        const fragmentA = instantiate(fragmentADef)
+          .withConfig({})
+          .withOptions({ databaseAdapter: adapter })
+          .build();
+        const fragmentB = instantiate(fragmentBDef)
+          .withConfig({})
+          .withOptions({ databaseAdapter: adapter })
+          .build();
+
+        const tokenA = (fragmentA.$internal as { durableHooksToken?: object }).durableHooksToken;
+        const tokenB = (fragmentB.$internal as { durableHooksToken?: object }).durableHooksToken;
+
+        expect(tokenA).toBeDefined();
+        expect(tokenB).toBeDefined();
+
+        const runtimeA = tokenA ? getDurableHooksRuntimeByToken(tokenA) : undefined;
+        const runtimeB = tokenB ? getDurableHooksRuntimeByToken(tokenB) : undefined;
+
+        if (!runtimeA || !runtimeB) {
+          throw new Error("Durable hooks runtime missing");
+        }
+
+        const notifySpy = vi.fn();
+        runtimeB.config.notifier = {
+          notify: notifySpy,
+        };
+
+        const internalFragment = getInternalFragment(adapter);
+        await internalFragment.inContext(async function () {
+          await this.handlerTx()
+            .mutate(({ forSchema }) => {
+              const uow = forSchema(internalSchema);
+              uow.create("fragno_hooks", {
+                namespace: namespaceA,
+                hookName: "onAlpha",
+                payload: { value: "alpha" },
+                status: "pending",
+                attempts: 0,
+                maxAttempts: 1,
+                lastAttemptAt: null,
+                nextRetryAt: null,
+                error: null,
+                nonce: "test-nonce",
+              });
+            })
+            .execute();
+        });
+
+        const runnerA = runtimeA.config.runner ?? hooks.createDurableHooksRunner(runtimeA.config);
+        runtimeA.config.runner = runnerA;
+        await runnerA.processDue();
+
+        expect(notifySpy).toHaveBeenCalled();
+      } finally {
+        await adapter.close();
+        sqlite.close();
+      }
+    });
+
+    it("should skip cross-namespace notify when target namespace has autoSchedule=false", async () => {
+      const sqlite = new SQLite(":memory:");
+      const adapter = new SqlAdapter({
+        dialect: new SqliteDialect({ database: sqlite }),
+        driverConfig: new BetterSQLite3DriverConfig(),
+      });
+
+      const schemaA = schema("hooks_alpha_autoschedule", (s) =>
+        s.addTable("items", (t) =>
+          t.addColumn("id", idColumn()).addColumn("name", column("string")),
+        ),
+      );
+      const schemaB = schema("hooks_beta_autoschedule", (s) =>
+        s.addTable("items", (t) =>
+          t.addColumn("id", idColumn()).addColumn("name", column("string")),
+        ),
+      );
+
+      type HooksA = {
+        onAlpha: (payload: { value: string }) => void;
+      };
+      type HooksB = {
+        onBeta: (payload: { value: string }) => void;
+      };
+
+      const hooksB: HooksB = {
+        onBeta: () => {},
+      };
+
+      const namespaceA = sanitizeNamespace(schemaA.name);
+      const namespaceB = sanitizeNamespace(schemaB.name);
+
+      const fragmentADef = defineFragment("frag-hooks-autoschedule-a")
+        .extend(withDatabase(schemaA))
+        .provideHooks<HooksA>(({ defineHook }) => ({
+          onAlpha: defineHook(async function () {
+            await this.handlerTx({
+              onBeforeMutate: (uow) => {
+                uow.registerSchema(schemaB, namespaceB);
+              },
+            })
+              .mutate(({ forSchema }) => {
+                const other = forSchema(schemaB, hooksB);
+                other.triggerHook("onBeta", { value: "beta" });
+              })
+              .execute();
+          }),
+        }))
+        .build();
+
+      const fragmentBDef = defineFragment("frag-hooks-autoschedule-b")
+        .extend(withDatabase(schemaB))
+        .provideHooks<HooksB>(({ defineHook }) => ({
+          onBeta: defineHook(async function () {
+            // no-op
+          }),
+        }))
+        .build();
+
+      try {
+        const internalMigrations = adapter.prepareMigrations(internalSchema, null);
+        await internalMigrations.executeWithDriver(adapter.driver, 0);
+
+        const migrationsA = adapter.prepareMigrations(schemaA, namespaceA);
+        await migrationsA.executeWithDriver(adapter.driver, 0);
+
+        const migrationsB = adapter.prepareMigrations(schemaB, namespaceB);
+        await migrationsB.executeWithDriver(adapter.driver, 0);
+
+        const fragmentA = instantiate(fragmentADef)
+          .withConfig({})
+          .withOptions({ databaseAdapter: adapter })
+          .build();
+        const fragmentB = instantiate(fragmentBDef)
+          .withConfig({})
+          .withOptions({ databaseAdapter: adapter, durableHooks: { autoSchedule: false } })
+          .build();
+
+        const tokenA = (fragmentA.$internal as { durableHooksToken?: object }).durableHooksToken;
+        const tokenB = (fragmentB.$internal as { durableHooksToken?: object }).durableHooksToken;
+
+        expect(tokenA).toBeDefined();
+        expect(tokenB).toBeDefined();
+
+        const runtimeA = tokenA ? getDurableHooksRuntimeByToken(tokenA) : undefined;
+        const runtimeB = tokenB ? getDurableHooksRuntimeByToken(tokenB) : undefined;
+
+        if (!runtimeA || !runtimeB) {
+          throw new Error("Durable hooks runtime missing");
+        }
+
+        const notifySpy = vi.fn();
+        runtimeB.config.notifier = {
+          notify: notifySpy,
+        };
+
+        const internalFragment = getInternalFragment(adapter);
+        await internalFragment.inContext(async function () {
+          await this.handlerTx()
+            .mutate(({ forSchema }) => {
+              const uow = forSchema(internalSchema);
+              uow.create("fragno_hooks", {
+                namespace: namespaceA,
+                hookName: "onAlpha",
+                payload: { value: "alpha" },
+                status: "pending",
+                attempts: 0,
+                maxAttempts: 1,
+                lastAttemptAt: null,
+                nextRetryAt: null,
+                error: null,
+                nonce: "auto-schedule-test-nonce",
+              });
+            })
+            .execute();
+        });
+
+        const runnerA = runtimeA.config.runner ?? hooks.createDurableHooksRunner(runtimeA.config);
+        runtimeA.config.runner = runnerA;
+        await runnerA.processDue();
+
+        expect(notifySpy).not.toHaveBeenCalled();
+
+        const queuedHooks = await internalFragment.inContext(async function () {
+          return await this.handlerTx()
+            .withServiceCalls(
+              () =>
+                [internalFragment.services.hookService.getHooksByNamespace(namespaceB)] as const,
+            )
+            .transform(({ serviceResult: [result] }) => result)
+            .execute();
+        });
+
+        const pendingBetaHooks = queuedHooks.filter(
+          (hook) => hook.status === "pending" && hook.hookName === "onBeta",
+        );
+        expect(pendingBetaHooks.length).toBeGreaterThan(0);
+      } finally {
+        await adapter.close();
+        sqlite.close();
+      }
+    });
+
+    it("should notify the matching runtime instance when namespace has multiple runtimes", async () => {
+      const sqliteA = new SQLite(":memory:");
+      const sqliteB = new SQLite(":memory:");
+      const adapterA = new SqlAdapter({
+        dialect: new SqliteDialect({ database: sqliteA }),
+        driverConfig: new BetterSQLite3DriverConfig(),
+      });
+      const adapterB = new SqlAdapter({
+        dialect: new SqliteDialect({ database: sqliteB }),
+        driverConfig: new BetterSQLite3DriverConfig(),
+      });
+
+      const unique = `${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+      const schemaA = schema(`hooks_alpha_instance_${unique}`, (s) =>
+        s.addTable("items", (t) =>
+          t.addColumn("id", idColumn()).addColumn("name", column("string")),
+        ),
+      );
+      const schemaB = schema(`hooks_shared_${unique}`, (s) =>
+        s.addTable("items", (t) =>
+          t.addColumn("id", idColumn()).addColumn("name", column("string")),
+        ),
+      );
+
+      type HooksA = {
+        onAlpha: (payload: { value: string }) => void;
+      };
+      type HooksB = {
+        onBeta: (payload: { value: string }) => void;
+      };
+
+      const hooksB: HooksB = {
+        onBeta: () => {},
+      };
+
+      const namespaceA = sanitizeNamespace(schemaA.name);
+      const namespaceB = sanitizeNamespace(schemaB.name);
+
+      const fragmentADef = defineFragment("frag-hooks-instance-a")
+        .extend(withDatabase(schemaA))
+        .provideHooks<HooksA>(({ defineHook }) => ({
+          onAlpha: defineHook(async function () {
+            await this.handlerTx({
+              onBeforeMutate: (uow) => {
+                uow.registerSchema(schemaB, namespaceB);
+              },
+            })
+              .mutate(({ forSchema }) => {
+                const other = forSchema(schemaB, hooksB);
+                other.triggerHook("onBeta", { value: "beta" });
+              })
+              .execute();
+          }),
+        }))
+        .build();
+
+      const fragmentBDef = defineFragment("frag-hooks-shared")
+        .extend(withDatabase(schemaB))
+        .provideHooks<HooksB>(({ defineHook }) => ({
+          onBeta: defineHook(async function () {
+            // no-op
+          }),
+        }))
+        .build();
+
+      try {
+        const internalMigrationsA = adapterA.prepareMigrations(internalSchema, null);
+        await internalMigrationsA.executeWithDriver(adapterA.driver, 0);
+        const schemaAMigrations = adapterA.prepareMigrations(schemaA, namespaceA);
+        await schemaAMigrations.executeWithDriver(adapterA.driver, 0);
+        const schemaBMigrationsA = adapterA.prepareMigrations(schemaB, namespaceB);
+        await schemaBMigrationsA.executeWithDriver(adapterA.driver, 0);
+
+        const internalMigrationsB = adapterB.prepareMigrations(internalSchema, null);
+        await internalMigrationsB.executeWithDriver(adapterB.driver, 0);
+        const schemaBMigrationsB = adapterB.prepareMigrations(schemaB, namespaceB);
+        await schemaBMigrationsB.executeWithDriver(adapterB.driver, 0);
+
+        const fragmentA = instantiate(fragmentADef)
+          .withConfig({})
+          .withOptions({ databaseAdapter: adapterA })
+          .build();
+        const fragmentBForAdapterA = instantiate(fragmentBDef)
+          .withConfig({})
+          .withOptions({ databaseAdapter: adapterA })
+          .build();
+        const fragmentBForAdapterB = instantiate(fragmentBDef)
+          .withConfig({})
+          .withOptions({ databaseAdapter: adapterB })
+          .build();
+
+        const tokenA = (fragmentA.$internal as { durableHooksToken?: object }).durableHooksToken;
+        const tokenBForAdapterA = (fragmentBForAdapterA.$internal as { durableHooksToken?: object })
+          .durableHooksToken;
+        const tokenBForAdapterB = (fragmentBForAdapterB.$internal as { durableHooksToken?: object })
+          .durableHooksToken;
+
+        expect(tokenA).toBeDefined();
+        expect(tokenBForAdapterA).toBeDefined();
+        expect(tokenBForAdapterB).toBeDefined();
+
+        const runtimeA = tokenA ? getDurableHooksRuntimeByToken(tokenA) : undefined;
+        const runtimeBForAdapterA = tokenBForAdapterA
+          ? getDurableHooksRuntimeByToken(tokenBForAdapterA)
+          : undefined;
+        const runtimeBForAdapterB = tokenBForAdapterB
+          ? getDurableHooksRuntimeByToken(tokenBForAdapterB)
+          : undefined;
+
+        if (!runtimeA || !runtimeBForAdapterA || !runtimeBForAdapterB) {
+          throw new Error("Durable hooks runtime missing");
+        }
+
+        const notifySpyForAdapterA = vi.fn();
+        const notifySpyForAdapterB = vi.fn();
+        runtimeBForAdapterA.config.notifier = {
+          notify: notifySpyForAdapterA,
+        };
+        runtimeBForAdapterB.config.notifier = {
+          notify: notifySpyForAdapterB,
+        };
+
+        const internalFragment = getInternalFragment(adapterA);
+        await internalFragment.inContext(async function () {
+          await this.handlerTx()
+            .mutate(({ forSchema }) => {
+              const uow = forSchema(internalSchema);
+              uow.create("fragno_hooks", {
+                namespace: namespaceA,
+                hookName: "onAlpha",
+                payload: { value: "alpha" },
+                status: "pending",
+                attempts: 0,
+                maxAttempts: 1,
+                lastAttemptAt: null,
+                nextRetryAt: null,
+                error: null,
+                nonce: "instance-test-nonce",
+              });
+            })
+            .execute();
+        });
+
+        const runnerA = runtimeA.config.runner ?? hooks.createDurableHooksRunner(runtimeA.config);
+        runtimeA.config.runner = runnerA;
+        await runnerA.processDue();
+
+        expect(notifySpyForAdapterA).toHaveBeenCalled();
+        expect(notifySpyForAdapterB).not.toHaveBeenCalled();
+      } finally {
+        await adapterA.close();
+        await adapterB.close();
+        sqliteA.close();
+        sqliteB.close();
+      }
+    });
+  });
+
+  describe("handlerTx plan mode", () => {
+    it("should suppress hook mutations in plan mode", () => {
+      const mockAdapter = createMockAdapter();
+
+      type TestHooks = {
+        onUserCreated: (payload: { email: string }) => void;
+      };
+
+      const definition = withDatabase(testSchema)(defineFragment("db-frag-plan-mode"))
+        .provideHooks<TestHooks>(({ defineHook }) => ({
+          onUserCreated: defineHook(function () {
+            // no-op
+          }),
+        }))
+        .build();
+
+      const mockStorage = {
+        getStore: () => ({
+          uow: mockAdapter.createQueryEngine(testSchema, "test").createUnitOfWork(),
+        }),
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any;
+
+      const createHandlerTxBuilderSpy = vi
+        .spyOn(executeUnitOfWork, "createHandlerTxBuilder")
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        .mockReturnValue({} as any);
+
+      const prepareHookMutationsSpy = vi.spyOn(hooks, "prepareHookMutations");
+
+      const contexts = definition.createThisContext!({
+        config: {},
+        options: { databaseAdapter: mockAdapter },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        deps: {} as any,
+        storage: mockStorage,
+      });
+
+      contexts.handlerContext.handlerTx({ planMode: true });
+
+      const callArgs = createHandlerTxBuilderSpy.mock.calls[0]?.[0];
+      callArgs?.onBeforeMutate?.({} as unknown as IUnitOfWork);
+
+      expect(prepareHookMutationsSpy).not.toHaveBeenCalled();
+
+      prepareHookMutationsSpy.mockRestore();
+      createHandlerTxBuilderSpy.mockRestore();
+    });
+  });
 });