@fragno-dev/db 0.2.2 → 0.3.0

package/src/query/serialize/dialect/mysql-serializer.ts

@@ -19,7 +19,8 @@ export class MySQLSerializer extends SQLSerializer {
     super(driverConfig);
   }
 
-  protected serializeDate(value: Date): Date {
+  protected serializeDate(value: Date, _col: AnyColumn): Date {
+    void _col;
     // MySQL handles Date objects natively
     return value;
   }
@@ -34,7 +35,8 @@ export class MySQLSerializer extends SQLSerializer {
     return value;
   }
 
-  protected deserializeDate(value: unknown): Date {
+  protected deserializeDate(value: unknown, _col: AnyColumn): Date {
+    void _col;
     if (value instanceof Date) {
       return value;
     }
@@ -96,12 +98,15 @@ export class MySQLSerializer extends SQLSerializer {
 
   protected deserializeInteger(value: unknown): number {
     if (typeof value === "number") {
+      if (Number.isNaN(value) || !Number.isFinite(value)) {
+        throw new Error(`Cannot deserialize integer from invalid number: ${value}`);
+      }
       return value;
     }
     // MySQL may return integers as strings
     if (typeof value === "string") {
       const num = Number(value);
-      if (isNaN(num)) {
+      if (Number.isNaN(num) || !Number.isFinite(num)) {
         throw new Error(`Cannot deserialize integer from invalid string: ${value}`);
       }
       return num;
@@ -121,11 +126,14 @@ export class MySQLSerializer extends SQLSerializer {
   protected deserializeDecimal(value: unknown): number {
     // MySQL can return decimals as numbers or strings
     if (typeof value === "number") {
+      if (Number.isNaN(value) || !Number.isFinite(value)) {
+        throw new Error(`Cannot deserialize decimal from invalid number: ${value}`);
+      }
       return value;
     }
     if (typeof value === "string") {
       const num = parseFloat(value);
-      if (isNaN(num)) {
+      if (Number.isNaN(num) || !Number.isFinite(num)) {
         throw new Error(`Cannot deserialize decimal from invalid string: ${value}`);
       }
       return num;

package/src/query/serialize/dialect/postgres-serializer.ts

@@ -18,7 +18,8 @@ export class PostgreSQLSerializer extends SQLSerializer {
     super(driverConfig);
   }
 
-  protected serializeDate(value: Date): Date {
+  protected serializeDate(value: Date, _col: AnyColumn): Date {
+    void _col;
     // PostgreSQL handles Date objects natively
     return value;
   }
@@ -33,13 +34,18 @@ export class PostgreSQLSerializer extends SQLSerializer {
     return value;
   }
 
-  protected deserializeDate(value: unknown): Date {
+  protected deserializeDate(value: unknown, _col: AnyColumn): Date {
+    void _col;
     if (value instanceof Date) {
+      if (this.driverConfig.driverType === "pglite") {
+        return new Date(value.getTime() - value.getTimezoneOffset() * 60_000);
+      }
       return value;
     }
     // PostgreSQL returns timestamps/dates as strings
     if (typeof value === "string") {
-      return new Date(value);
+      // Normalize timezone-less timestamps to UTC to avoid local offset drift.
+      return new Date(normalizeTimestampString(value));
     }
     throw new Error(`Cannot deserialize date from value: ${value}`);
   }
@@ -91,6 +97,9 @@ export class PostgreSQLSerializer extends SQLSerializer {
 
   protected deserializeInteger(value: unknown): number {
     if (typeof value === "number") {
+      if (Number.isNaN(value) || !Number.isFinite(value)) {
+        throw new Error(`Cannot deserialize integer from invalid number: ${value}`);
+      }
       return value;
     }
     // PostgreSQL may return bigint for large integers
@@ -108,11 +117,14 @@ export class PostgreSQLSerializer extends SQLSerializer {
   protected deserializeDecimal(value: unknown): number {
     // PostgreSQL can return decimals as numbers or strings depending on precision
     if (typeof value === "number") {
+      if (Number.isNaN(value) || !Number.isFinite(value)) {
+        throw new Error(`Cannot deserialize decimal from invalid number: ${value}`);
+      }
       return value;
     }
     if (typeof value === "string") {
       const num = parseFloat(value);
-      if (isNaN(num)) {
+      if (Number.isNaN(num) || !Number.isFinite(num)) {
         throw new Error(`Cannot deserialize decimal from invalid string: ${value}`);
       }
       return num;
@@ -127,3 +139,21 @@ export class PostgreSQLSerializer extends SQLSerializer {
     throw new Error(`Cannot deserialize string from value: ${typeof value}`);
   }
 }
+
+const normalizeTimestampString = (value: string) => {
+  if (!hasTimeComponent(value) || !isTimestampWithoutTimezone(value)) {
+    return value;
+  }
+  const withTimeSeparator = value.includes(" ") ? value.replace(" ", "T") : value;
+  return `${withTimeSeparator}Z`;
+};
+
+const hasTimeComponent = (value: string) => /\d{2}:\d{2}:\d{2}/.test(value);
+
+const isTimestampWithoutTimezone = (value: string) => {
+  // Detect RFC3339-like timezone indicators: Z or +/-HH(:MM)?
+  if (value.endsWith("Z")) {
+    return false;
+  }
+  return !/[+-]\d{2}(:?\d{2})?$/.test(value);
+};

package/src/query/serialize/dialect/sqlite-serializer.test.ts

@@ -2,10 +2,18 @@ import { describe, it, expect } from "vitest";
 import { SQLiteSerializer } from "./sqlite-serializer";
 import type { AnyColumn } from "../../../schema/create";
 import { BetterSQLite3DriverConfig } from "../../../adapters/generic-sql/driver-config";
+import { sqliteStoragePrisma } from "../../../adapters/generic-sql/sqlite-storage";
 
 describe("SQLiteSerializer", () => {
   const mockDriverConfig = new BetterSQLite3DriverConfig();
   const serializer = new SQLiteSerializer(mockDriverConfig);
+  const prismaSerializer = new SQLiteSerializer(mockDriverConfig, sqliteStoragePrisma);
+  const timestampColumn: AnyColumn = {
+    name: "createdAt",
+    type: "timestamp",
+    role: "regular",
+    isNullable: false,
+  } as AnyColumn;
 
   describe("serializeBigInt", () => {
     describe("for internal-id and reference columns", () => {
@@ -110,6 +118,19 @@ describe("SQLiteSerializer", () => {
         expect((result as Buffer).length).toBe(8);
       });
 
+      it("should keep bigint for regular column in prisma storage", () => {
+        const col: AnyColumn = {
+          name: "largeNumber",
+          type: "bigint",
+          role: "regular",
+          isNullable: false,
+        } as AnyColumn;
+
+        const result = prismaSerializer["serializeBigInt"](BigInt(789), col);
+        expect(result).toBe(BigInt(789));
+        expect(typeof result).toBe("bigint");
+      });
+
       it("should handle large values outside safe integer range as Buffer", () => {
         const col: AnyColumn = {
           name: "largeNumber",
@@ -132,11 +153,18 @@ describe("SQLiteSerializer", () => {
   describe("other serialization methods", () => {
     it("should serialize Date to timestamp number", () => {
       const date = new Date("2024-01-01T00:00:00Z");
-      const result = serializer["serializeDate"](date);
+      const result = serializer["serializeDate"](date, timestampColumn);
       expect(result).toBe(date.getTime());
       expect(typeof result).toBe("number");
     });
 
+    it("should serialize Date to ISO string for prisma storage", () => {
+      const date = new Date("2024-01-01T00:00:00Z");
+      const result = prismaSerializer["serializeDate"](date, timestampColumn);
+      expect(result).toBe(date.toISOString());
+      expect(typeof result).toBe("string");
+    });
+
     it("should serialize boolean to 0/1", () => {
       expect(serializer["serializeBoolean"](true)).toBe(1);
       expect(serializer["serializeBoolean"](false)).toBe(0);
@@ -181,6 +209,18 @@ describe("SQLiteSerializer", () => {
     });
   });
 
+  describe("deserializeDate", () => {
+    it("should parse CURRENT_TIMESTAMP format as UTC", () => {
+      const date = prismaSerializer["deserializeDate"]("2024-03-10 12:34:56", timestampColumn);
+      expect(date.toISOString()).toBe("2024-03-10T12:34:56.000Z");
+    });
+
+    it("should parse CURRENT_TIMESTAMP format with milliseconds as UTC", () => {
+      const date = prismaSerializer["deserializeDate"]("2024-03-10 12:34:56.789", timestampColumn);
+      expect(date.toISOString()).toBe("2024-03-10T12:34:56.789Z");
+    });
+  });
+
   describe("deserializeInteger", () => {
     it("should deserialize number directly", () => {
       expect(serializer["deserializeInteger"](42)).toBe(42);
@@ -248,4 +288,14 @@ describe("SQLiteSerializer", () => {
       );
     });
   });
+
+  describe("deserializeBigInt", () => {
+    it("should throw when prisma storage receives unsafe bigint number", () => {
+      const unsafeNumber = Number.MAX_SAFE_INTEGER + 10;
+      expect(() => prismaSerializer["deserializeBigInt"](unsafeNumber)).toThrow(RangeError);
+      expect(() => prismaSerializer["deserializeBigInt"](unsafeNumber)).toThrow(
+        /exceeds Number\.MAX_SAFE_INTEGER/,
+      );
+    });
+  });
 });

package/src/query/serialize/dialect/sqlite-serializer.ts

@@ -1,23 +1,59 @@
 import type { AnyColumn } from "../../../schema/create";
 import { SQLSerializer } from "../sql-serializer";
 import type { DriverConfig } from "../../../adapters/generic-sql/driver-config";
+import type { SQLiteStorageMode } from "../../../adapters/generic-sql/sqlite-storage";
+import { sqliteStorageDefault } from "../../../adapters/generic-sql/sqlite-storage";
+
+const SQLITE_UTC_TIMESTAMP_REGEX =
+  /^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?$/;
+
+function parseSQLiteUtcTimestamp(value: string): Date | null {
+  const match = SQLITE_UTC_TIMESTAMP_REGEX.exec(value);
+  if (!match) {
+    return null;
+  }
+
+  const [, year, month, day, hour, minute, second, millis] = match;
+  const milliseconds = millis ? Number(millis.padEnd(3, "0")) : 0;
+  return new Date(
+    Date.UTC(
+      Number(year),
+      Number(month) - 1,
+      Number(day),
+      Number(hour),
+      Number(minute),
+      Number(second),
+      milliseconds,
+    ),
+  );
+}
 
 /**
  * SQLite-specific serializer.
  *
  * SQLite has limited native type support and requires conversions:
  * - JSON → strings (no native JSON support)
- * - Dates → numbers (timestamps)
+ * - Dates → numbers or ISO strings (storage-mode dependent)
  * - Booleans → 0/1
- * - BigInts → Buffer (except for internal-id and reference columns → number)
+ * - BigInts → Buffer or integer (storage-mode dependent; internal-id/reference stay integer)
  * - Numbers/strings → Date for timestamps/dates
  */
 export class SQLiteSerializer extends SQLSerializer {
-  constructor(driverConfig: DriverConfig) {
+  private readonly sqliteStorageMode: SQLiteStorageMode;
+
+  constructor(driverConfig: DriverConfig, sqliteStorageMode?: SQLiteStorageMode) {
     super(driverConfig);
+    this.sqliteStorageMode = sqliteStorageMode ?? sqliteStorageDefault;
   }
 
-  protected serializeDate(value: Date): number {
+  protected serializeDate(value: Date, col: AnyColumn): number | string {
+    const storage =
+      col.type === "date"
+        ? this.sqliteStorageMode.dateStorage
+        : this.sqliteStorageMode.timestampStorage;
+    if (storage === "iso-text") {
+      return value.toISOString();
+    }
     return value.getTime();
   }
 
@@ -25,7 +61,7 @@ export class SQLiteSerializer extends SQLSerializer {
     return value ? 1 : 0;
   }
 
-  protected serializeBigInt(value: bigint, col: AnyColumn): number | Buffer {
+  protected serializeBigInt(value: bigint, col: AnyColumn): bigint | number | Buffer {
     // SQLite special case: internal-id and reference columns use integer, not blob
     // These should be converted to numbers for SQLite
     if (col.role === "reference" || col.role === "internal-id") {
@@ -40,18 +76,52 @@ export class SQLiteSerializer extends SQLSerializer {
       }
       return Number(value);
     }
+    if (this.sqliteStorageMode.bigintStorage === "integer") {
+      return value;
+    }
     const buf = Buffer.alloc(8);
     buf.writeBigInt64BE(value);
     return buf;
   }
 
-  protected deserializeDate(value: unknown): Date {
+  protected deserializeDate(value: unknown, col: AnyColumn): Date {
     if (value instanceof Date) {
       return value;
     }
-    if (typeof value === "number" || typeof value === "string") {
+    if (typeof value === "string") {
+      if (/^\d+$/.test(value)) {
+        const numericDate = new Date(Number(value));
+        if (Number.isNaN(numericDate.getTime())) {
+          throw new Error(`Cannot deserialize date from value: ${value}`);
+        }
+        return numericDate;
+      }
+      const parsed = parseSQLiteUtcTimestamp(value);
+      const date = parsed ?? new Date(value);
+      if (Number.isNaN(date.getTime())) {
+        throw new Error(`Cannot deserialize date from value: ${value}`);
+      }
+      return date;
+    }
+    if (typeof value === "number") {
+      if (Number.isNaN(value)) {
+        throw new Error(`Cannot deserialize date from value: ${value}`);
+      }
       return new Date(value);
     }
+    if (typeof value === "bigint") {
+      const storage =
+        col.type === "date"
+          ? this.sqliteStorageMode.dateStorage
+          : this.sqliteStorageMode.timestampStorage;
+      if (storage === "epoch-ms") {
+        const date = new Date(Number(value));
+        if (Number.isNaN(date.getTime())) {
+          throw new Error(`Cannot deserialize date from value: ${value}`);
+        }
+        return date;
+      }
+    }
     throw new Error(`Cannot deserialize date from value: ${value}`);
   }
 
@@ -76,6 +146,13 @@ export class SQLiteSerializer extends SQLSerializer {
       return BigInt(value);
     }
     if (typeof value === "number") {
+      if (this.sqliteStorageMode.bigintStorage === "integer") {
+        if (Math.abs(value) > Number.MAX_SAFE_INTEGER) {
+          throw new RangeError(
+            `Cannot deserialize bigint value ${value}: exceeds Number.MAX_SAFE_INTEGER`,
+          );
+        }
+      }
       return BigInt(value);
     }
     throw new Error(`Cannot deserialize bigint from value: ${value}`);
@@ -110,12 +187,15 @@ export class SQLiteSerializer extends SQLSerializer {
 
   protected deserializeInteger(value: unknown): number {
     if (typeof value === "number") {
+      if (Number.isNaN(value) || !Number.isFinite(value)) {
+        throw new Error(`Cannot deserialize integer from invalid number: ${value}`);
+      }
       return value;
     }
     // SQLite may return integers as strings for large values
     if (typeof value === "string") {
       const num = Number(value);
-      if (isNaN(num)) {
+      if (Number.isNaN(num) || !Number.isFinite(num)) {
         throw new Error(`Cannot deserialize integer from invalid string: ${value}`);
       }
       return num;
@@ -135,11 +215,14 @@ export class SQLiteSerializer extends SQLSerializer {
   protected deserializeDecimal(value: unknown): number {
     // SQLite stores decimals as REAL (floating point) or TEXT
     if (typeof value === "number") {
+      if (Number.isNaN(value) || !Number.isFinite(value)) {
+        throw new Error(`Cannot deserialize decimal from invalid number: ${value}`);
+      }
       return value;
     }
     if (typeof value === "string") {
       const num = parseFloat(value);
-      if (isNaN(num)) {
+      if (Number.isNaN(num) || !Number.isFinite(num)) {
         throw new Error(`Cannot deserialize decimal from invalid string: ${value}`);
       }
       return num;

package/src/query/serialize/sql-serializer.ts

@@ -40,7 +40,7 @@ export abstract class SQLSerializer {
 
     // Handle date/timestamp deserialization
     if (col.type === "timestamp" || col.type === "date") {
-      return this.deserializeDate(value);
+      return this.deserializeDate(value, col);
     }
 
     // Handle boolean deserialization
@@ -103,7 +103,7 @@ export abstract class SQLSerializer {
     if (!skipDriverConversions) {
       // Handle date/timestamp serialization
       if (value instanceof Date) {
-        return this.serializeDate(value);
+        return this.serializeDate(value, col);
       }
 
       // Handle boolean serialization
@@ -126,13 +126,13 @@ export abstract class SQLSerializer {
   }
 
   // Abstract methods for dialect-specific serialization
-  protected abstract serializeDate(value: Date): Date | number;
+  protected abstract serializeDate(value: Date, col: AnyColumn): Date | number | string;
   protected abstract serializeBoolean(value: boolean): boolean | number;
   protected abstract serializeBigInt(value: bigint, col: AnyColumn): bigint | number | Buffer;
   protected abstract serializeJson(value: unknown): unknown;
 
   // Abstract methods for dialect-specific deserialization
-  protected abstract deserializeDate(value: unknown): Date;
+  protected abstract deserializeDate(value: unknown, col: AnyColumn): Date;
   protected abstract deserializeBoolean(value: unknown): boolean;
   protected abstract deserializeBigInt(value: unknown): bigint;
   protected abstract deserializeJson(value: unknown): unknown;

package/src/query/simple-query-interface.ts

@@ -133,6 +133,11 @@ export type FindManyOptions<
   : {});
 
 export interface SimpleQueryInterface<TSchema extends AnySchema, TUOWConfig = void> {
+  /**
+   * Fetch the current database timestamp.
+   * Optional for adapters that cannot provide DB time.
+   */
+  now?: () => Promise<Date>;
   /**
    * Find multiple records using a builder pattern
    */

package/src/query/unit-of-work/execute-unit-of-work.test.ts

@@ -20,7 +20,7 @@ import {
 } from "./retry-policy";
 import type { AwaitedPromisesInObject, TxResult } from "./execute-unit-of-work";
 
-const testSchema = schema((s) =>
+const testSchema = schema("test", (s) =>
   s.addTable("users", (t) =>
     t
       .addColumn("id", idColumn())
@@ -414,6 +414,26 @@ describe("Unified Tx API", () => {
       expect(result.userId).toBeInstanceOf(FragnoId);
     });
 
+    it("should throw when retry policy is provided without retrieve operations", async () => {
+      const compiler = createMockCompiler();
+      const executor: UOWExecutor<unknown, unknown> = {
+        executeRetrievalPhase: async () => [],
+        executeMutationPhase: async () => ({ success: false }),
+      };
+      const decoder = createMockDecoder();
+
+      await expect(
+        createHandlerTxBuilder({
+          createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
+          retryPolicy: new NoRetryPolicy(),
+        })
+          .mutate(() => ({ done: true }))
+          .execute(),
+      ).rejects.toThrow(
+        "Retry policy is only supported when the transaction includes retrieve operations.",
+      );
+    });
+
     it("should execute a transaction with serviceCalls as retrieve source", async () => {
       const compiler = createMockCompiler();
       const mockUser = {
@@ -772,6 +792,7 @@ describe("Unified Tx API", () => {
         createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
         retryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 5, initialDelayMs: 1 }),
       })
+        .retrieve(({ forSchema }) => forSchema(testSchema).find("users"))
         .mutate(({ forSchema }) => {
           forSchema(testSchema).create("users", {
             email: "test@example.com",
@@ -801,6 +822,7 @@ describe("Unified Tx API", () => {
           createUnitOfWork: () => createUnitOfWork(compiler, executor, decoder),
           retryPolicy: new NoRetryPolicy(),
         })
+          .retrieve(({ forSchema }) => forSchema(testSchema).find("users"))
           .mutate(() => ({ done: true }))
           .execute(),
       ).rejects.toThrow(ConcurrencyConflictError);
@@ -850,6 +872,7 @@ describe("Unified Tx API", () => {
         },
         retryPolicy: new LinearBackoffRetryPolicy({ maxRetries: 3, delayMs: 1 }),
       })
+        .retrieve(({ forSchema }) => forSchema(testSchema).find("users"))
         .mutate(({ forSchema }) => {
           forSchema(testSchema).create("users", {
             email: "test@example.com",
@@ -882,6 +905,7 @@ describe("Unified Tx API", () => {
           retryPolicy: new LinearBackoffRetryPolicy({ maxRetries: 5, delayMs: 100 }),
           signal: controller.signal,
         })
+          .retrieve(({ forSchema }) => forSchema(testSchema).find("users"))
           .mutate(() => ({ done: true }))
           .execute(),
       ).rejects.toThrow("Transaction execution aborted");

package/src/query/unit-of-work/execute-unit-of-work.ts

@@ -1,7 +1,7 @@
 import type { AnySchema } from "../../schema/create";
 import type { TypedUnitOfWork, IUnitOfWork } from "./unit-of-work";
 import type { HooksMap } from "../../hooks/hooks";
-import { ExponentialBackoffRetryPolicy, type RetryPolicy } from "./retry-policy";
+import { ExponentialBackoffRetryPolicy, NoRetryPolicy, type RetryPolicy } from "./retry-policy";
 
 /**
  * Symbol to identify TxResult objects
@@ -724,13 +724,6 @@ async function executeTx(
   type TServiceCalls = readonly (TxResult<any, any> | undefined)[];
   type TMutateResult = unknown;
   type THooks = HooksMap;
-  const retryPolicy =
-    options.retryPolicy ??
-    new ExponentialBackoffRetryPolicy({
-      maxRetries: 5,
-      initialDelayMs: 10,
-      maxDelayMs: 100,
-    });
   const signal = options.signal;
   let attempt = 0;
 
@@ -740,6 +733,8 @@ async function executeTx(
       throw new Error("Transaction execution aborted");
     }
 
+    let retryPolicy: RetryPolicy | undefined;
+
     try {
       // Create a fresh UOW for this attempt
       const baseUow = options.createUnitOfWork();
@@ -764,6 +759,24 @@ async function executeTx(
 
       const allServiceCallTxResults = serviceCalls ? collectAllTxResults([...serviceCalls]) : [];
 
+      const hasRetrieveOps = baseUow.getRetrievalOperations().length > 0;
+      if (!hasRetrieveOps) {
+        if (options.retryPolicy) {
+          throw new Error(
+            "Retry policy is only supported when the transaction includes retrieve operations.",
+          );
+        }
+        retryPolicy = new NoRetryPolicy();
+      } else {
+        retryPolicy =
+          options.retryPolicy ??
+          new ExponentialBackoffRetryPolicy({
+            maxRetries: 5,
+            initialDelayMs: 10,
+            maxDelayMs: 100,
+          });
+      }
+
       await baseUow.executeRetrieve();
 
       // Get retrieve results from TypedUnitOfWork's retrievalPhase or default to empty array
@@ -885,6 +898,10 @@ async function executeTx(
         throw error;
       }
 
+      if (!retryPolicy) {
+        throw error;
+      }
+
       if (!retryPolicy.shouldRetry(attempt, error, signal)) {
         if (signal?.aborted) {
           throw new Error("Transaction execution aborted");

package/src/query/unit-of-work/unit-of-work-coordinator.test.ts

@@ -59,7 +59,7 @@ function createMockDecoder(): UOWDecoder {
 
 describe("UOW Coordinator - Parent-Child Execution", () => {
   it("should allow child UOWs to add operations and parent to execute them", async () => {
-    const testSchema = schema((s) =>
+    const testSchema = schema("test", (s) =>
       s.addTable("users", (t) =>
         t.addColumn("id", idColumn()).addColumn("name", "string").addColumn("email", "string"),
       ),
@@ -102,7 +102,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
   });
 
   it("should handle nested service calls that await phase promises without deadlock", async () => {
-    const testSchema = schema((s) =>
+    const testSchema = schema("test", (s) =>
       s
         .addTable("users", (t) =>
           t.addColumn("id", idColumn()).addColumn("name", "string").addColumn("email", "string"),
@@ -176,7 +176,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
   });
 
   it("should handle retrieval-to-mutation flow with service composition", async () => {
-    const testSchema = schema((s) =>
+    const testSchema = schema("test", (s) =>
       s
         .addTable("users", (t) =>
           t
@@ -303,7 +303,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
   });
 
   it("should handle deeply nested child UOWs (3+ levels)", async () => {
-    const testSchema = schema((s) =>
+    const testSchema = schema("test", (s) =>
       s
         .addTable("users", (t) =>
           t.addColumn("id", idColumn()).addColumn("name", "string").addColumn("email", "string"),
@@ -416,7 +416,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
   });
 
   it("should handle sibling child UOWs at same nesting level", async () => {
-    const testSchema = schema((s) =>
+    const testSchema = schema("test", (s) =>
       s
         .addTable("users", (t) =>
           t
@@ -526,7 +526,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
   });
 
   it("should support transaction rollback pattern", async () => {
-    const testSchema = schema((s) =>
+    const testSchema = schema("test", (s) =>
       s
         .addTable("accounts", (t) =>
           t
@@ -633,7 +633,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
   });
 
   it("should handle errors thrown by service methods without unhandled rejections", async () => {
-    const testSchema = schema((s) =>
+    const testSchema = schema("test", (s) =>
       s
         .addTable("users", (t) =>
           t
@@ -770,7 +770,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
   });
 
   it("should not cause unhandled rejection when service method awaits retrievalPhase and executeRetrieve fails", async () => {
-    const testSchema = schema((s) =>
+    const testSchema = schema("test", (s) =>
       s.addTable("settings", (t) =>
         t
           .addColumn("id", idColumn())
@@ -830,7 +830,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
   });
 
   it("should allow child UOW to call getCreatedIds() after parent executes mutations", async () => {
-    const testSchema = schema((s) =>
+    const testSchema = schema("test", (s) =>
       s.addTable("products", (t) =>
         t.addColumn("id", idColumn()).addColumn("name", "string").addColumn("price", "integer"),
       ),
@@ -862,7 +862,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
   });
 
   it("should preserve internal IDs in child UOW when using two-phase pattern with mutationPhase await", async () => {
-    const testSchema = schema((s) =>
+    const testSchema = schema("test", (s) =>
       s.addTable("orders", (t) =>
         t
           .addColumn("id", idColumn())
@@ -916,7 +916,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
   });
 
   it("should fail when handler executes mutations before service finishes scheduling them (anti-pattern)", async () => {
-    const testSchema = schema((s) =>
+    const testSchema = schema("test", (s) =>
       s.addTable("totp_secret", (t) =>
         t
           .addColumn("id", idColumn())
@@ -997,7 +997,7 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
   });
 
   it("should succeed when handler awaits service promise between phases (correct pattern)", async () => {
-    const testSchema = schema((s) =>
+    const testSchema = schema("test", (s) =>
       s.addTable("totp_secret", (t) =>
         t
           .addColumn("id", idColumn())