@fragno-dev/db 0.2.2 → 0.3.0

package/src/adapters/generic-sql/driver-config.ts

@@ -1,3 +1,9 @@
+import {
+  schemaNamingStrategy,
+  suffixNamingStrategy,
+  type SqlNamingStrategy,
+} from "../../naming/sql-naming";
+
 export const supportedDatabases = ["sqlite", "postgresql", "mysql"] as const;
 export type SupportedDatabase = (typeof supportedDatabases)[number];
 
@@ -18,6 +24,7 @@ export abstract class DriverConfig<T extends SupportedDriverType = SupportedDriv
 
   abstract readonly supportsReturning: boolean;
   abstract readonly supportsJson: boolean;
+  abstract readonly outboxVersionstampStrategy: OutboxVersionstampStrategy;
 
   /**
    * Column name for internal ID in RETURNING results.
@@ -25,10 +32,17 @@ export abstract class DriverConfig<T extends SupportedDriverType = SupportedDriv
    */
   abstract readonly internalIdColumn: string | undefined;
 
+  /**
+   * SQLite storage selection is handled by adapters, not driver config.
+   */
   get supportsRowsAffected(): boolean {
     return !!this.extractAffectedRows;
   }
 
+  get defaultNamingStrategy(): SqlNamingStrategy {
+    return defaultNamingStrategyForDatabase(this.databaseType);
+  }
+
   /**
    * Extract the number of affected rows from a query result.
    * Only implemented for drivers that support affected rows reporting.
@@ -40,12 +54,31 @@ export abstract class DriverConfig<T extends SupportedDriverType = SupportedDriv
   extractAffectedRows?(result: Record<string, unknown>): bigint;
 }
 
+export const defaultNamingStrategyForDatabase = (
+  databaseType: SupportedDatabase,
+): SqlNamingStrategy => {
+  switch (databaseType) {
+    case "postgresql":
+      return schemaNamingStrategy;
+    case "sqlite":
+    case "mysql":
+    default:
+      return suffixNamingStrategy;
+  }
+};
+
+export type OutboxVersionstampStrategy =
+  | "update-returning"
+  | "insert-on-conflict-returning"
+  | "insert-on-duplicate-last-insert-id";
+
 export class SQLocalDriverConfig extends DriverConfig<"sqlocal"> {
   override readonly driverType = "sqlocal";
   override readonly databaseType = "sqlite";
   override readonly supportsReturning = true;
   override readonly supportsJson = false;
   override readonly internalIdColumn = "_internalId";
+  override readonly outboxVersionstampStrategy = "insert-on-conflict-returning";
 }
 
 export class CloudflareDurableObjectsDriverConfig extends DriverConfig<"cloudflare_durable_objects"> {
@@ -54,6 +87,7 @@ export class CloudflareDurableObjectsDriverConfig extends DriverConfig<"cloudfla
   override readonly supportsReturning = true;
   override readonly supportsJson = false;
   override readonly internalIdColumn = "_internalId";
+  override readonly outboxVersionstampStrategy = "insert-on-conflict-returning";
 }
 
 export class BetterSQLite3DriverConfig extends DriverConfig<"better-sqlite3"> {
@@ -62,6 +96,7 @@ export class BetterSQLite3DriverConfig extends DriverConfig<"better-sqlite3"> {
   override readonly supportsReturning = true;
   override readonly supportsJson = false;
   override readonly internalIdColumn = "_internalId";
+  override readonly outboxVersionstampStrategy = "insert-on-conflict-returning";
 
   override extractAffectedRows(result: Record<string, unknown>): bigint {
     if ("numAffectedRows" in result) {
@@ -86,6 +121,7 @@ export class NodePostgresDriverConfig extends DriverConfig<"pg"> {
   override readonly supportsReturning = true;
   override readonly supportsJson = true;
   override readonly internalIdColumn = "_internalId";
+  override readonly outboxVersionstampStrategy = "insert-on-conflict-returning";
 
   override extractAffectedRows(result: Record<string, unknown>): bigint {
     if ("numAffectedRows" in result) {
@@ -118,6 +154,7 @@ export class PGLiteDriverConfig extends DriverConfig<"pglite"> {
   override readonly supportsReturning = true;
   override readonly supportsJson = true;
   override readonly internalIdColumn = "_internalId";
+  override readonly outboxVersionstampStrategy = "insert-on-conflict-returning";
 
   override extractAffectedRows(result: Record<string, unknown>): bigint {
     if ("affectedRows" in result) {
@@ -141,4 +178,5 @@ export class MySQL2DriverConfig extends DriverConfig<"mysql2"> {
   override readonly supportsReturning = false;
   override readonly supportsJson = true;
   override readonly internalIdColumn = undefined;
+  override readonly outboxVersionstampStrategy = "insert-on-duplicate-last-insert-id";
 }

package/src/adapters/generic-sql/generic-sql-adapter.test.ts

@@ -1,12 +1,12 @@
 import { SQLocalKysely } from "sqlocal/kysely";
 import { assert, describe, expect, it } from "vitest";
 import { SQLocalDriverConfig } from "./driver-config";
-import { GenericSQLAdapter } from "./generic-sql-adapter";
+import { SqlAdapter } from "./generic-sql-adapter";
 import { column, idColumn, schema } from "../../schema/create";
 import { internalSchema } from "../../fragments/internal-fragment";
 
-describe("GenericSQLAdapter", () => {
-  const testSchema = schema((s) => {
+describe("SqlAdapter", () => {
+  const testSchema = schema("test", (s) => {
     return s.addTable("products", (t) => {
       return t
         .addColumn("id", idColumn())
@@ -16,11 +16,11 @@ describe("GenericSQLAdapter", () => {
     });
   });
 
-  it("Should be able to query using GenericSQLAdapter", async () => {
+  it("Should be able to query using SqlAdapter", async () => {
     const { dialect } = new SQLocalKysely(":memory:");
     const driverConfig = new SQLocalDriverConfig();
 
-    const adapter = new GenericSQLAdapter({ dialect, driverConfig });
+    const adapter = new SqlAdapter({ dialect, driverConfig });
 
     // Create settings table first (needed for version tracking)
     const settingsMigrations = adapter.prepareMigrations(internalSchema, "");

package/src/adapters/generic-sql/generic-sql-adapter.ts

@@ -4,13 +4,13 @@ import {
   fragnoDatabaseAdapterVersionFakeSymbol,
   type DatabaseAdapter,
   type DatabaseContextStorage,
-  type TableNameMapper,
+  type DatabaseAdapterMetadata,
+  type SQLiteProfile,
 } from "../adapters";
 import type { CompiledQuery, Dialect, QueryResult } from "../../sql-driver/sql-driver";
 import { SqlDriverAdapter } from "../../sql-driver/sql-driver-adapter";
 import { sql } from "../../sql-driver/sql";
-import type { AnySchema } from "../../schema/create";
-import { createTableNameMapper } from "../shared/table-name-mapper";
+import type { AnyColumn, AnySchema } from "../../schema/create";
 import type { SimpleQueryInterface } from "../../query/simple-query-interface";
 import { createExecutor } from "./generic-sql-uow-executor";
 import { UnitOfWorkDecoder } from "./uow-decoder";
@@ -22,34 +22,87 @@ import {
   fromUnitOfWorkCompiler,
   type UnitOfWorkFactory,
 } from "../shared/from-unit-of-work-compiler";
+import type { UOWInstrumentation } from "../../query/unit-of-work/unit-of-work";
+import type { SQLiteStorageMode } from "./sqlite-storage";
+import { sqliteStorageDefault, sqliteStoragePrisma } from "./sqlite-storage";
+import type { OutboxConfig } from "../../outbox/outbox";
+import { createSQLSerializer } from "../../query/serialize/create-sql-serializer";
+import {
+  createNamingResolver,
+  type NamingResolver,
+  type SqlNamingStrategy,
+} from "../../naming/sql-naming";
 
 export interface UnitOfWorkConfig {
   onQuery?: (query: CompiledQuery) => void;
   dryRun?: boolean;
+  instrumentation?: UOWInstrumentation;
 }
 
-export interface GenericSQLOptions {
+export interface SqlAdapterOptions {
   dialect: Dialect;
   driverConfig: DriverConfig;
   uowConfig?: UnitOfWorkConfig;
+  outbox?: OutboxConfig;
+  sqliteProfile?: SQLiteProfile;
+  sqliteStorageMode?: SQLiteStorageMode;
+  namingStrategy?: SqlNamingStrategy;
 }
 
-export class GenericSQLAdapter implements DatabaseAdapter<UnitOfWorkConfig> {
+export const sqliteProfiles: Record<SQLiteProfile, SQLiteStorageMode> = {
+  default: sqliteStorageDefault,
+  prisma: sqliteStoragePrisma,
+};
+
+export class SqlAdapter implements DatabaseAdapter<UnitOfWorkConfig> {
   readonly dialect: Dialect;
   readonly driverConfig: DriverConfig;
   readonly uowConfig?: UnitOfWorkConfig;
+  readonly outbox?: OutboxConfig;
+  readonly sqliteStorageMode?: SQLiteStorageMode;
+  readonly sqliteProfile?: SQLiteProfile;
+  readonly adapterMetadata: DatabaseAdapterMetadata;
+  readonly namingStrategy: SqlNamingStrategy;
 
-  #schemaNamespaceMap = new WeakMap<AnySchema, string>();
+  #schemaNamespaceMap = new WeakMap<AnySchema, string | null>();
   #contextStorage: RequestContextStorage<DatabaseContextStorage>;
 
   #driver: SqlDriverAdapter;
 
-  constructor({ dialect, driverConfig, uowConfig }: GenericSQLOptions) {
+  constructor({
+    dialect,
+    driverConfig,
+    uowConfig,
+    outbox,
+    sqliteProfile,
+    sqliteStorageMode,
+    namingStrategy,
+  }: SqlAdapterOptions) {
     this.dialect = dialect;
     this.driverConfig = driverConfig;
     this.uowConfig = uowConfig;
+    this.outbox = outbox;
+    this.namingStrategy = namingStrategy ?? driverConfig.defaultNamingStrategy;
+    const resolvedProfile = sqliteProfile ?? "default";
+
+    if (sqliteStorageMode && sqliteProfile) {
+      throw new Error("sqliteStorageMode cannot be used together with sqliteProfile.");
+    }
+
+    this.sqliteStorageMode =
+      driverConfig.databaseType === "sqlite"
+        ? (sqliteStorageMode ?? sqliteProfiles[resolvedProfile])
+        : undefined;
+    this.sqliteProfile =
+      driverConfig.databaseType === "sqlite" && !sqliteStorageMode ? resolvedProfile : undefined;
+
+    this.adapterMetadata = {
+      databaseType: driverConfig.databaseType,
+      sqliteProfile: this.sqliteProfile,
+      sqliteStorageMode: this.sqliteStorageMode,
+    };
 
-    this.#schemaNamespaceMap = new WeakMap<AnySchema, string>();
+    this.#schemaNamespaceMap = new WeakMap<AnySchema, string | null>();
     this.#contextStorage = new RequestContextStorage();
 
     this.#driver = new SqlDriverAdapter(dialect);
@@ -60,11 +113,11 @@ export class GenericSQLAdapter implements DatabaseAdapter<UnitOfWorkConfig> {
   }
 
   get [fragnoDatabaseAdapterNameFakeSymbol](): string {
-    return "generic-sql";
+    return "sql";
   }
 
   get [fragnoDatabaseAdapterVersionFakeSymbol](): number {
-    return 0;
+    return 1;
   }
 
   get contextStorage(): RequestContextStorage<DatabaseContextStorage> {
@@ -77,23 +130,23 @@ export class GenericSQLAdapter implements DatabaseAdapter<UnitOfWorkConfig> {
 
   async isConnectionHealthy(): Promise<boolean> {
     const result = await this.#driver.executeQuery(sql`SELECT 1 as healthy`.compile(this.dialect));
-    return result.rows[0]["healthy"] === 1;
+    const healthyValue = result.rows[0]?.["healthy"];
+    return healthyValue === 1 || healthyValue === 1n || healthyValue === "1";
   }
 
-  prepareMigrations<T extends AnySchema>(schema: T, namespace: string): PreparedMigrations {
+  prepareMigrations<T extends AnySchema>(schema: T, namespace: string | null): PreparedMigrations {
+    const resolver = createNamingResolver(schema, namespace, this.namingStrategy);
     return createPreparedMigrations({
       schema,
-      namespace,
+      namespace: namespace ?? schema.name,
       database: this.driverConfig.databaseType,
-      mapper: namespace ? this.createTableNameMapper(namespace) : undefined,
+      driverConfig: this.driverConfig,
+      sqliteStorageMode: this.sqliteStorageMode,
+      resolver,
       driver: this.#driver,
     });
   }
 
-  createTableNameMapper(namespace: string): TableNameMapper {
-    return createTableNameMapper(namespace, false);
-  }
-
   async getSchemaVersion(namespace: string): Promise<string | undefined> {
     const key = `${namespace}.schema_version`;
     const query = sql`SELECT value FROM fragno_db_settings WHERE key = ${key};`.compile(
@@ -125,22 +178,55 @@ export class GenericSQLAdapter implements DatabaseAdapter<UnitOfWorkConfig> {
 
   createQueryEngine<T extends AnySchema>(
     schema: T,
-    namespace: string,
+    namespace: string | null,
   ): SimpleQueryInterface<T, UnitOfWorkConfig> {
     this.#schemaNamespaceMap.set(schema, namespace);
+    const resolver = createNamingResolver(schema, namespace, this.namingStrategy);
 
-    const operationCompiler = new GenericSQLUOWOperationCompiler(this.driverConfig, (ns) =>
-      ns ? this.createTableNameMapper(ns) : undefined,
+    const operationCompiler = new GenericSQLUOWOperationCompiler(
+      this.driverConfig,
+      this.sqliteStorageMode,
+      (schemaForResolver, namespaceForResolver): NamingResolver =>
+        createNamingResolver(schemaForResolver, namespaceForResolver, this.namingStrategy),
     );
 
     const factory: UnitOfWorkFactory = {
       compiler: createUOWCompilerFromOperationCompiler(operationCompiler),
-      executor: createExecutor(this.#driver, this.driverConfig, false),
-      decoder: new UnitOfWorkDecoder(this.driverConfig),
+      executor: createExecutor(this.#driver, this.driverConfig, {
+        dialect: this.dialect,
+        dryRun: false,
+        outbox: this.outbox,
+        namingStrategy: this.namingStrategy,
+      }),
+      decoder: new UnitOfWorkDecoder(this.driverConfig, this.sqliteStorageMode, resolver),
       uowConfig: this.uowConfig,
       schemaNamespaceMap: this.#schemaNamespaceMap,
     };
 
-    return fromUnitOfWorkCompiler(schema, factory);
+    const queryEngine = fromUnitOfWorkCompiler(schema, factory) as SimpleQueryInterface<
+      T,
+      UnitOfWorkConfig
+    >;
+
+    const serializer = createSQLSerializer(this.driverConfig, this.sqliteStorageMode);
+    const timestampColumn = { type: "timestamp" } as AnyColumn;
+
+    return {
+      ...queryEngine,
+      now: async () => {
+        const result = await this.#driver.executeQuery(
+          sql`SELECT CURRENT_TIMESTAMP as now`.compile(this.dialect),
+        );
+        const rawValue = result.rows[0]?.["now"];
+        if (rawValue === undefined || rawValue === null) {
+          throw new Error("Failed to fetch database time");
+        }
+        return serializer.deserialize(rawValue, timestampColumn) as Date;
+      },
+    };
   }
 }
+
+export type { SQLiteStorageMode } from "./sqlite-storage";
+export { sqliteStorageDefault, sqliteStoragePrisma } from "./sqlite-storage";
+export type { OutboxConfig } from "../../outbox/outbox";

package/src/adapters/generic-sql/generic-sql-uow-executor.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import type { CompiledMutation } from "../../query/unit-of-work/unit-of-work";
+import type { CompiledQuery, Dialect } from "../../sql-driver/sql-driver";
+import type { SqlDriverAdapter } from "../../sql-driver/sql-driver-adapter";
+import { NodePostgresDriverConfig } from "./driver-config";
+import { executeMutation } from "./generic-sql-uow-executor";
+
+const createError = (code: string) => {
+  const error = new Error(`DB_ERROR_${code}`);
+  (error as { code?: string }).code = code;
+  return error;
+};
+
+const createAdapterThatThrows = (error: Error) =>
+  ({
+    transaction: async (
+      callback: (trx: { executeQuery: () => Promise<unknown> }) => Promise<unknown>,
+    ) =>
+      await callback({
+        executeQuery: async () => {
+          throw error;
+        },
+      }),
+  }) as unknown as SqlDriverAdapter;
+
+describe("executeMutation", () => {
+  const dialect = {
+    createAdapter: () => ({}) as Dialect["createAdapter"] extends () => infer T ? T : never,
+    createDriver: () => ({}) as Dialect["createDriver"] extends () => infer T ? T : never,
+    createQueryCompiler: () =>
+      ({}) as Dialect["createQueryCompiler"] extends () => infer T ? T : never,
+  } satisfies Dialect;
+  const compiledQuery: CompiledQuery = {
+    sql: "SELECT 1",
+    parameters: [],
+  };
+
+  const mutationBatch: CompiledMutation<CompiledQuery>[] = [
+    {
+      op: "update",
+      query: compiledQuery,
+      expectedAffectedRows: null,
+      expectedReturnedRows: null,
+    },
+  ];
+
+  it.each(["40001", "40P01"])("returns success=false on SQLSTATE %s", async (code) => {
+    const adapter = createAdapterThatThrows(createError(code));
+    const result = await executeMutation(adapter, new NodePostgresDriverConfig(), mutationBatch, {
+      dialect,
+    });
+    expect(result.success).toBe(false);
+  });
+});

package/src/adapters/generic-sql/generic-sql-uow-executor.ts

@@ -3,10 +3,33 @@ import type {
   MutationResult,
   UOWExecutor,
 } from "../../query/unit-of-work/unit-of-work";
-import type { CompiledQuery } from "../../sql-driver/sql-driver";
+import type { CompiledQuery, Dialect } from "../../sql-driver/sql-driver";
 import type { SqlDriverAdapter } from "../../sql-driver/sql-driver-adapter";
 import type { DriverConfig } from "./driver-config";
 import { ResultInterpreter } from "./result-interpreter";
+import { sql } from "../../sql-driver/sql";
+import { createId } from "../../id";
+import superjson from "superjson";
+import { createColdKysely } from "./migration/cold-kysely";
+import { SETTINGS_NAMESPACE, internalSchema } from "../../fragments/internal-fragment.schema";
+import {
+  type OutboxConfig,
+  type OutboxRefLookup,
+  type OutboxRefMap,
+  encodeVersionstamp,
+  parseOutboxVersionValue,
+  versionstampToHex,
+} from "../../outbox/outbox";
+import { buildOutboxPlan, finalizeOutboxPayload } from "../../outbox/outbox-builder";
+import { createSQLSerializer } from "../../query/serialize/create-sql-serializer";
+import { type SqlNamingStrategy } from "../../naming/sql-naming";
+
+export interface ExecutorOptions {
+  dryRun?: boolean;
+  dialect: Dialect;
+  outbox?: OutboxConfig;
+  namingStrategy?: SqlNamingStrategy;
+}
 
 export async function executeRetrieval(
   adapter: SqlDriverAdapter,
@@ -32,6 +55,7 @@ export async function executeMutation(
   adapter: SqlDriverAdapter,
   driverConfig: DriverConfig,
   mutationBatch: CompiledMutation<CompiledQuery>[],
+  options: ExecutorOptions,
 ): Promise<MutationResult> {
   if (mutationBatch.length === 0) {
     return { success: true, createdInternalIds: [] };
@@ -39,9 +63,24 @@ export async function executeMutation(
 
   const createdInternalIds: (bigint | null)[] = [];
   const resultInterpreter = new ResultInterpreter(driverConfig);
+  const outboxEnabled = options.outbox?.enabled ?? false;
+  const namingStrategy = options.namingStrategy ?? driverConfig.defaultNamingStrategy;
+
+  const outboxOperations = outboxEnabled
+    ? mutationBatch.flatMap((mutation) => (mutation.operation ? [mutation.operation] : []))
+    : [];
+
+  const outboxPlan = outboxOperations.length > 0 ? buildOutboxPlan(outboxOperations) : null;
+  const shouldWriteOutbox = outboxEnabled && outboxPlan !== null && outboxPlan.drafts.length > 0;
 
   try {
     await adapter.transaction(async (tx) => {
+      let outboxVersion: bigint | null = null;
+
+      if (shouldWriteOutbox) {
+        outboxVersion = await reserveOutboxVersion(tx, driverConfig, options.dialect);
+      }
+
       for (const compiledMutation of mutationBatch) {
         const result = await tx.executeQuery(compiledMutation.query);
 
@@ -86,6 +125,31 @@ export async function executeMutation(
           }
         }
       }
+
+      if (shouldWriteOutbox && outboxPlan && outboxVersion !== null) {
+        const uowId = mutationBatch[0]?.uowId;
+        if (!uowId) {
+          throw new Error("Outbox mutation batch is missing uowId.");
+        }
+
+        const refMap = await resolveOutboxRefMap(
+          tx,
+          driverConfig,
+          outboxPlan.lookups,
+          namingStrategy,
+        );
+        const payload = finalizeOutboxPayload(outboxPlan, outboxVersion);
+        const payloadSerialized = superjson.serialize(payload);
+        const versionstamp = versionstampToHex(encodeVersionstamp(outboxVersion, 0));
+
+        await insertOutboxRow(tx, driverConfig, {
+          id: createId(),
+          versionstamp,
+          uowId,
+          payload: payloadSerialized,
+          refMap,
+        });
+      }
     });
 
     return { success: true, createdInternalIds };
@@ -96,6 +160,15 @@ export async function executeMutation(
       return { success: false };
     }
 
+    const errorCode =
+      typeof error === "object" && error !== null && "code" in error
+        ? (error as { code?: unknown }).code
+        : undefined;
+
+    if (errorCode === "40001" || errorCode === "40P01") {
+      return { success: false };
+    }
+
     // Other database errors should be thrown
     throw error;
   }
@@ -104,8 +177,10 @@ export async function executeMutation(
 export function createExecutor(
   adapter: SqlDriverAdapter,
   driverConfig: DriverConfig,
-  dryRun?: boolean,
+  options: ExecutorOptions,
 ): UOWExecutor<CompiledQuery, unknown> {
+  const dryRun = options.dryRun ?? false;
+
   return {
     async executeRetrievalPhase(retrievalBatch: CompiledQuery[]) {
       // In dryRun mode, skip execution and return empty results
@@ -124,7 +199,160 @@ export function createExecutor(
         };
       }
 
-      return executeMutation(adapter, driverConfig, mutationBatch);
+      return executeMutation(adapter, driverConfig, mutationBatch, options);
     },
   };
 }
+
+async function reserveOutboxVersion(
+  tx: SqlDriverAdapter,
+  driverConfig: DriverConfig,
+  dialect: Dialect,
+): Promise<bigint> {
+  const key = `${SETTINGS_NAMESPACE}.outbox_version`;
+  const id = createId();
+
+  switch (driverConfig.outboxVersionstampStrategy) {
+    case "insert-on-conflict-returning": {
+      const query =
+        driverConfig.databaseType === "postgresql"
+          ? sql`
+              insert into fragno_db_settings (id, key, value)
+              values (${id}, ${key}, '0')
+              on conflict (key) do update
+                set value = (fragno_db_settings.value::bigint + 1)::text
+              returning value;
+            `
+          : sql`
+              insert into fragno_db_settings (id, key, value)
+              values (${id}, ${key}, '0')
+              on conflict (key) do update
+                set value = cast(fragno_db_settings.value as integer) + 1
+              returning value;
+            `;
+
+      const result = await tx.executeQuery(query.compile(dialect));
+      const value = result.rows[0]?.["value"];
+      return parseOutboxVersionValue(value);
+    }
+    case "update-returning": {
+      const query =
+        driverConfig.databaseType === "postgresql"
+          ? sql`
+              update fragno_db_settings
+              set value = (fragno_db_settings.value::bigint + 1)::text
+              where key = ${key}
+              returning value;
+            `
+          : sql`
+              update fragno_db_settings
+              set value = cast(fragno_db_settings.value as integer) + 1
+              where key = ${key}
+              returning value;
+            `;
+
+      const result = await tx.executeQuery(query.compile(dialect));
+      const value = result.rows[0]?.["value"];
+      if (value === undefined) {
+        throw new Error("Outbox version row was not found for update-returning strategy.");
+      }
+      return parseOutboxVersionValue(value);
+    }
+    case "insert-on-duplicate-last-insert-id": {
+      const insertQuery = sql`
+        insert into fragno_db_settings (id, key, value)
+        values (${id}, ${key}, LAST_INSERT_ID(0))
+        on duplicate key update value = LAST_INSERT_ID(cast(value as unsigned) + 1);
+      `;
+
+      await tx.executeQuery(insertQuery.compile(dialect));
+
+      const selectQuery = sql`select LAST_INSERT_ID() as value;`;
+      const result = await tx.executeQuery(selectQuery.compile(dialect));
+      const value = result.rows[0]?.["value"];
+      return parseOutboxVersionValue(value);
+    }
+  }
+}
+
+async function resolveOutboxRefMap(
+  tx: SqlDriverAdapter,
+  driverConfig: DriverConfig,
+  lookups: OutboxRefLookup[],
+  namingStrategy: SqlNamingStrategy,
+): Promise<OutboxRefMap | undefined> {
+  if (lookups.length === 0) {
+    return undefined;
+  }
+
+  const refMap: OutboxRefMap = {};
+  const db = createColdKysely(driverConfig.databaseType);
+
+  for (const lookup of lookups) {
+    const namespace = lookup.namespace ?? null;
+    const logicalTable = lookup.table.name;
+    const schemaName =
+      namingStrategy.namespaceScope === "schema" && namespace && namespace.length > 0
+        ? namingStrategy.namespaceToSchema(namespace)
+        : null;
+    const scopedDb = schemaName ? db.withSchema(schemaName) : db;
+    const tableName = namingStrategy.tableName(logicalTable, namespace);
+    const internalColumn = namingStrategy.columnName(
+      lookup.table.getInternalIdColumn().name,
+      logicalTable,
+    );
+    const externalColumn = namingStrategy.columnName(lookup.table.getIdColumn().name, logicalTable);
+
+    const query = scopedDb
+      .selectFrom(tableName)
+      .select(externalColumn)
+      .where(internalColumn, "=", lookup.internalId)
+      .compile();
+
+    const result = await tx.executeQuery(query);
+    const row = result.rows[0] as Record<string, unknown> | undefined;
+    const externalId = row?.[externalColumn];
+
+    if (typeof externalId !== "string") {
+      throw new Error(
+        `Failed to resolve outbox reference for ${tableName}.${internalColumn}=${String(lookup.internalId)}`,
+      );
+    }
+
+    refMap[lookup.key] = externalId;
+  }
+
+  return Object.keys(refMap).length > 0 ? refMap : undefined;
+}
+
+async function insertOutboxRow(
+  tx: SqlDriverAdapter,
+  driverConfig: DriverConfig,
+  options: {
+    id: string;
+    versionstamp: string;
+    uowId: string;
+    payload: { json: unknown; meta?: Record<string, unknown> };
+    refMap?: OutboxRefMap;
+  },
+): Promise<void> {
+  const { id, versionstamp, uowId, payload, refMap } = options;
+  const refMapValue = refMap ?? null;
+  const serializer = createSQLSerializer(driverConfig);
+  const outboxTable = internalSchema.tables.fragno_db_outbox;
+  const values = { id, versionstamp, uowId, payload, refMap: refMapValue };
+  const serializedValues: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(values)) {
+    const col = outboxTable.columns[key];
+    if (!col) {
+      serializedValues[key] = value;
+      continue;
+    }
+    serializedValues[col.name] = serializer.serialize(value, col);
+  }
+  const db = createColdKysely(driverConfig.databaseType);
+
+  const query = db.insertInto("fragno_db_outbox").values(serializedValues).compile();
+
+  await tx.executeQuery(query);
+}