@abloatai/transaction 0.37.0

package/src/source/adapters/kysely.ts

@@ -0,0 +1,346 @@
+/**
+ * Kysely wrappers for Ablo's two customer-database write transports.
+ *
+ * Both wrappers compose the same exported {@link createKyselyMutationCore}:
+ *
+ * - {@link kyselyDataSource} is the endpoint adapter. Its transaction contains
+ *   row DML, the permanent idempotency ledger, and correlated outbox events. A
+ *   Postgres logical marker remains optional for compatibility.
+ * - {@link kyselyDirectMutation} is the engine-side direct wrapper. Its
+ *   transaction contains row DML, the same ledger, and a required logical
+ *   marker. It never creates, writes, or serves `ablo_outbox`.
+ *
+ * The ledger reservation happens before DML via `INSERT ... ON CONFLICT DO
+ * NOTHING`. Postgres waits on a concurrent uncommitted owner of the same key;
+ * after that owner commits, the loser reads and hash-checks its durable response.
+ * If the owner rolls back, the waiter acquires the reservation and performs the
+ * mutation. This gives same-key concurrency one database arbiter and one effect.
+ */
+
+import { AbloValidationError } from '../../errors.js';
+import type { Schema, SchemaRecord } from '../../schema/schema.js';
+import type {
+  AdapterCommitResult,
+  DataSourceAdapter,
+  MutationAdapter,
+  Row,
+} from '../adapter.js';
+import type { ChangeSet, EventsPage, Migration } from '../contract.js';
+import {
+  changeSetSchema,
+  outboxEventSchema,
+  sourceCommitEchoMarkerSchema,
+} from '../contract.js';
+import {
+  assertSourceIdempotencyIntent,
+  assertSourceIdempotencyRetention,
+  sourceChangeIntentHash,
+  SOURCE_IDEMPOTENCY_RETENTION,
+} from '../idempotency.js';
+import {
+  adapterTableMigrations,
+  idempotencyLedgerMigrations,
+} from '../migrations.js';
+import { ABLO_POSTGRES_COMMIT_ECHO_PREFIX } from '../types.js';
+import {
+  createKyselyMutationCore,
+  kyselyOperationRowId,
+  type KyselyCompiledQuery,
+  type KyselyLike,
+  type KyselyMutationCore,
+} from './kyselyMutationCore.js';
+
+export {
+  createKyselyMutationCore,
+  kyselyOperationRowId,
+  type KyselyCompiledQuery,
+  type KyselyDeleteBuilder,
+  type KyselyInsertBuilder,
+  type KyselyInsertValuesBuilder,
+  type KyselyLike,
+  type KyselyMutationCore,
+  type KyselyReturningExecutable,
+  type KyselySelectBuilder,
+  type KyselyTransactionBuilder,
+  type KyselyUpdateBuilder,
+  type KyselyUpdateSetBuilder,
+} from './kyselyMutationCore.js';
+
+type KyselyMutationMode = 'endpoint' | 'direct';
+
+function rawQuery(
+  queryId: string,
+  sql: string,
+  parameters: readonly unknown[],
+): KyselyCompiledQuery {
+  return {
+    query: { kind: 'RawNode', sqlFragments: [sql], parameters: [] },
+    queryId: { queryId },
+    sql,
+    parameters,
+  };
+}
+
+function reserveLedgerQuery(
+  correlationId: string,
+  requestHash: string,
+): KyselyCompiledQuery {
+  return rawQuery(
+    'ablo-idempotency-reserve',
+    `INSERT INTO ablo_idempotency (client_tx_id, response, request_hash, expires_at)
+     VALUES ($1, $2::jsonb, $3, now() + $4::interval)
+     ON CONFLICT (client_tx_id) DO NOTHING
+     RETURNING client_tx_id`,
+    [correlationId, '[]', requestHash, SOURCE_IDEMPOTENCY_RETENTION],
+  );
+}
+
+function completeLedgerQuery(
+  correlationId: string,
+  rows: readonly Row[],
+): KyselyCompiledQuery {
+  return rawQuery(
+    'ablo-idempotency-complete',
+    `UPDATE ablo_idempotency
+        SET response = $2::jsonb
+      WHERE client_tx_id = $1`,
+    [correlationId, JSON.stringify(rows)],
+  );
+}
+
+function postgresLogicalMarkerQuery(payload: string): KyselyCompiledQuery {
+  return rawQuery(
+    'ablo-postgres-logical-marker',
+    'SELECT pg_logical_emit_message(true, $1::text, $2::text)',
+    [ABLO_POSTGRES_COMMIT_ECHO_PREFIX, payload],
+  );
+}
+
+function parseCachedRows(response: unknown): Row[] {
+  const parsed = typeof response === 'string' ? (JSON.parse(response) as unknown) : response;
+  if (!Array.isArray(parsed)) {
+    throw new AbloValidationError(
+      'The source idempotency response is corrupt and cannot be replayed safely',
+      { code: 'idempotency_conflict' },
+    );
+  }
+  return parsed as Row[];
+}
+
+function markerAction(type: ChangeSet['operations'][number]['type']): 'I' | 'U' | 'D' {
+  if (type === 'CREATE') return 'I';
+  if (type === 'DELETE') return 'D';
+  return 'U';
+}
+
+function assertDirectLogicalMarker(
+  change: ChangeSet,
+  markerModelFor: (operationModel: string) => string,
+): void {
+  const payload = change.echo?.payload;
+  if (!payload) {
+    throw new AbloValidationError(
+      'A direct Kysely mutation requires a transactional Postgres logical marker',
+      { code: 'source_adapter_misconfigured' },
+    );
+  }
+  try {
+    const marker = sourceCommitEchoMarkerSchema.parse(JSON.parse(payload) as unknown);
+    if (marker.correlationId !== change.correlationId) {
+      throw new Error('marker correlation does not match the ledger key');
+    }
+    if (marker.operations.length !== change.operations.length) {
+      throw new Error('marker operation count does not match the mutation');
+    }
+    for (const [index, operation] of change.operations.entries()) {
+      const markerOperation = marker.operations[index];
+      // The marker speaks the canonical schema TYPENAME (the vocabulary the
+      // WAL consumer validates deltas against), while the mutation operation
+      // carries the authoring wire key. `markerModelFor` translates the wire
+      // key through the schema so the two vocabularies compare correctly.
+      if (
+        !markerOperation ||
+        markerOperation.model !== markerModelFor(operation.model) ||
+        markerOperation.id !== kyselyOperationRowId(operation) ||
+        markerOperation.action !== markerAction(operation.type) ||
+        markerOperation.transactionId !== operation.transactionId
+      ) {
+        throw new Error(`marker operation ${index} does not match the mutation`);
+      }
+    }
+  } catch (error) {
+    if (error instanceof AbloValidationError) throw error;
+    throw new AbloValidationError(
+      `The direct Postgres logical marker is invalid: ${error instanceof Error ? error.message : 'unknown marker error'}`,
+      { code: 'source_adapter_misconfigured' },
+    );
+  }
+}
+
+/**
+ * Build the shared transaction policy around one Kysely mutation core. Exported
+ * for engine integrations that need to inject a prebuilt core while retaining
+ * the exact same ledger and mapping semantics as the endpoint adapter.
+ */
+export interface KyselyMutationAdapterOptions {
+  /**
+   * Translate a mutation operation's authoring model key into the canonical
+   * marker vocabulary (the schema typename). Direct wrappers must supply the
+   * schema-backed translation; identity is only correct when a schema's
+   * typenames equal its keys.
+   */
+  readonly markerModelFor?: (operationModel: string) => string;
+}
+
+export function createKyselyMutationAdapter(
+  db: KyselyLike,
+  core: KyselyMutationCore,
+  mode: KyselyMutationMode,
+  options: KyselyMutationAdapterOptions = {},
+): MutationAdapter {
+  const markerModelFor = options.markerModelFor ?? ((model: string) => model);
+  return {
+    capabilities: {
+      transactions: true,
+      propose: false,
+      schemaIntrospection: true,
+      postgresWalEcho: true,
+      outboxEvents: mode === 'endpoint',
+    },
+
+    migrations(): readonly Migration[] {
+      return mode === 'endpoint'
+        ? adapterTableMigrations()
+        : idempotencyLedgerMigrations();
+    },
+
+    read(request) {
+      return core.read(request);
+    },
+
+    async commit(change: ChangeSet): Promise<AdapterCommitResult> {
+      const request = changeSetSchema.parse(change);
+      if (mode === 'direct') assertDirectLogicalMarker(request, markerModelFor);
+
+      const requestHash = sourceChangeIntentHash(request);
+      return db.transaction().execute(async (transaction) => {
+        const reservation = await transaction.executeQuery(
+          reserveLedgerQuery(request.correlationId, requestHash),
+        );
+
+        if (reservation.rows.length === 0) {
+          const cached = await transaction
+            .selectFrom('ablo_idempotency')
+            .selectAll()
+            .where('client_tx_id', '=', request.correlationId)
+            .limit(1)
+            .execute();
+          const cachedRow = cached[0];
+          if (!cachedRow) {
+            throw new AbloValidationError(
+              'The source idempotency reservation disappeared during replay',
+              { code: 'idempotency_conflict' },
+            );
+          }
+          assertSourceIdempotencyIntent(cachedRow.request_hash, requestHash);
+          assertSourceIdempotencyRetention(cachedRow.expires_at);
+          return { rows: parseCachedRows(cachedRow.response) };
+        }
+
+        const rows: Row[] = [];
+        for (const [index, operation] of request.operations.entries()) {
+          const row = await core.applyOperation(transaction, operation);
+          rows.push(row);
+
+          if (mode === 'endpoint') {
+            const entityId = String(row.id ?? kyselyOperationRowId(operation));
+            await transaction
+              .insertInto('ablo_outbox')
+              .values({
+                id: `${request.correlationId}:${index}`,
+                model: operation.model,
+                entity_id: entityId,
+                type: operation.type,
+                data: operation.type === 'DELETE' ? null : JSON.stringify(row),
+                correlation_id: request.correlationId,
+                transaction_id: operation.transactionId ?? null,
+                occurred_at: Date.now(),
+              })
+              .execute();
+          }
+        }
+
+        await transaction.executeQuery(
+          completeLedgerQuery(request.correlationId, rows),
+        );
+        if (request.echo?.kind === 'postgres-wal') {
+          await transaction.executeQuery(
+            postgresLogicalMarkerQuery(request.echo.payload),
+          );
+        }
+        return { rows };
+      });
+    },
+  };
+}
+
+/** Endpoint wrapper: mutation + ledger + outbox, with an optional marker. */
+export function kyselyDataSource<S extends SchemaRecord>(
+  db: KyselyLike,
+  schema: Schema<S>,
+): DataSourceAdapter {
+  const mutation = createKyselyMutationAdapter(
+    db,
+    createKyselyMutationCore(db, schema),
+    'endpoint',
+  );
+
+  return {
+    ...mutation,
+    capabilities: { ...mutation.capabilities, outboxEvents: true },
+
+    async events(cursor: string | null, limit: number): Promise<EventsPage> {
+      const rows = await db
+        .selectFrom('ablo_outbox')
+        .selectAll()
+        .where('cursor', '>', cursor ?? '0')
+        .orderBy('cursor', 'asc')
+        .limit(limit)
+        .execute();
+      const events = rows.map((row) =>
+        outboxEventSchema.parse({
+          id: row.id,
+          model: row.model,
+          entityId: row.entity_id,
+          type: row.type,
+          data: typeof row.data === 'string' ? JSON.parse(row.data) : row.data ?? null,
+          organizationId: row.organization_id ?? null,
+          clientTxId: row.client_tx_id ?? null,
+          correlationId: row.correlation_id ?? null,
+          transactionId: row.transaction_id ?? null,
+          occurredAt: row.occurred_at != null ? Number(row.occurred_at) : null,
+          cursor: String(row.cursor),
+        }),
+      );
+      return { events, nextCursor: events.at(-1)?.cursor ?? null };
+    },
+  };
+}
+
+/** Direct wrapper: mutation + ledger + required logical marker, never outbox. */
+export function kyselyDirectMutation<S extends SchemaRecord>(
+  db: KyselyLike,
+  schema: Schema<S>,
+): MutationAdapter {
+  return createKyselyMutationAdapter(
+    db,
+    createKyselyMutationCore(db, schema),
+    'direct',
+    {
+      markerModelFor: (operationModel) => {
+        const typename = schema.models[operationModel]?.typename;
+        return typename && typename.length > 0 ? typename : operationModel;
+      },
+    },
+  );
+}

package/src/source/adapters/kyselyMutationCore.ts

@@ -0,0 +1,220 @@
+/**
+ * Reusable Kysely row-mutation core.
+ *
+ * This is the single schema-field ↔ physical-column translation used by both
+ * Kysely transports. It deliberately knows nothing about outboxes, logical
+ * markers, or idempotency: wrappers compose those transaction policies around
+ * the same `applyOperation` implementation, so direct and endpoint DML cannot
+ * drift into separate hand-written mappers.
+ */
+
+import { AbloValidationError } from '../../errors.js';
+import type { Schema, SchemaRecord } from '../../schema/schema.js';
+import { toSchemaJSON } from '../../schema/serialize.js';
+import { camelToSnake, snakeToCamel } from '../../schema/ddl.js';
+import { tenancyColumn } from '../../schema/tenancy.js';
+import type { AdapterReadRequest, Row } from '../adapter.js';
+import type { Operation } from '../contract.js';
+
+/** The subset of a Kysely instance, or transaction handle, used by the core. */
+export interface KyselyLike {
+  selectFrom(table: string): KyselySelectBuilder;
+  insertInto(table: string): KyselyInsertBuilder;
+  updateTable(table: string): KyselyUpdateBuilder;
+  deleteFrom(table: string): KyselyDeleteBuilder;
+  /** Execute a precompiled raw query on this exact transaction handle. */
+  executeQuery(query: KyselyCompiledQuery): Promise<{ readonly rows: readonly Row[] }>;
+  transaction(): KyselyTransactionBuilder;
+}
+
+/** Structural slice of Kysely's public `CompiledQuery` shape. */
+export interface KyselyCompiledQuery {
+  readonly query: {
+    readonly kind: 'RawNode';
+    readonly sqlFragments: readonly string[];
+    readonly parameters: readonly [];
+  };
+  readonly queryId: { readonly queryId: string };
+  readonly sql: string;
+  readonly parameters: readonly unknown[];
+}
+
+export interface KyselyTransactionBuilder {
+  execute<T>(fn: (trx: KyselyLike) => Promise<T>): Promise<T>;
+}
+
+export interface KyselySelectBuilder {
+  selectAll(): KyselySelectBuilder;
+  where(column: string, operator: string, value: unknown): KyselySelectBuilder;
+  orderBy(column: string, direction: 'asc' | 'desc'): KyselySelectBuilder;
+  limit(limit: number): KyselySelectBuilder;
+  execute(): Promise<readonly Row[]>;
+}
+
+export interface KyselyReturningExecutable {
+  execute(): Promise<readonly Row[]>;
+}
+
+export interface KyselyInsertBuilder {
+  values(row: Row): KyselyInsertValuesBuilder;
+}
+
+export interface KyselyInsertValuesBuilder {
+  returningAll(): KyselyReturningExecutable;
+  execute(): Promise<unknown>;
+}
+
+export interface KyselyUpdateBuilder {
+  set(patch: Row): KyselyUpdateSetBuilder;
+}
+
+export interface KyselyUpdateSetBuilder {
+  where(column: string, operator: string, value: unknown): KyselyUpdateSetBuilder;
+  returningAll(): KyselyReturningExecutable;
+}
+
+export interface KyselyDeleteBuilder {
+  where(column: string, operator: string, value: unknown): KyselyDeleteBuilder;
+  returningAll(): KyselyReturningExecutable;
+}
+
+interface ModelColumns {
+  readonly table: string;
+  readonly fieldToColumn: ReadonlyMap<string, string>;
+  readonly columnToField: ReadonlyMap<string, string>;
+}
+
+function buildColumnMaps(schema: Schema): ReadonlyMap<string, ModelColumns> {
+  const json = toSchemaJSON(schema);
+  const out = new Map<string, ModelColumns>();
+  for (const [key, model] of Object.entries(json.models)) {
+    const fieldToColumn = new Map<string, string>();
+    const columnToField = new Map<string, string>();
+    const register = (field: string, column: string): void => {
+      if (column === camelToSnake(field)) return;
+      fieldToColumn.set(field, column);
+      columnToField.set(column, field);
+    };
+    for (const [field, meta] of Object.entries(model.fields)) {
+      if (meta.column) register(field, meta.column);
+    }
+    const orgColumn = tenancyColumn(model.tenancy);
+    if (orgColumn) register('organizationId', orgColumn);
+    out.set(key, {
+      table: model.tableName ?? key,
+      fieldToColumn,
+      columnToField,
+    });
+  }
+  return out;
+}
+
+/** Resolve the stable row id required by every source operation. */
+export function kyselyOperationRowId(operation: Operation): string {
+  const id = operation.id ?? (operation.input?.id as string | undefined);
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new AbloValidationError(
+      `operation on "${operation.model}" requires an id`,
+      { code: 'source_operation_id_required' },
+    );
+  }
+  return id;
+}
+
+/** The transport-independent Kysely field/column mutation boundary. */
+export interface KyselyMutationCore {
+  read(request: AdapterReadRequest): Promise<readonly Row[]>;
+  applyOperation(transaction: KyselyLike, operation: Operation): Promise<Row>;
+}
+
+export function createKyselyMutationCore<S extends SchemaRecord>(
+  db: KyselyLike,
+  schema: Schema<S>,
+): KyselyMutationCore {
+  const maps = buildColumnMaps(schema);
+  const modelColumns = (model: string): ModelColumns => {
+    const columns = maps.get(model);
+    if (!columns) {
+      throw new AbloValidationError(
+        `kysely mutation core: no model "${model}" in schema`,
+        { code: 'source_adapter_misconfigured' },
+      );
+    }
+    return columns;
+  };
+
+  const columnFor = (columns: ModelColumns, field: string): string =>
+    columns.fieldToColumn.get(field) ?? camelToSnake(field);
+  const fieldFor = (columns: ModelColumns, column: string): string =>
+    columns.columnToField.get(column) ?? snakeToCamel(column);
+
+  const toColumns = (columns: ModelColumns, row: Row): Row => {
+    const out: Row = {};
+    for (const key of Object.keys(row)) out[columnFor(columns, key)] = row[key];
+    return out;
+  };
+
+  const toFields = (columns: ModelColumns, row: Row): Row => {
+    const out: Row = {};
+    for (const key of Object.keys(row)) out[fieldFor(columns, key)] = row[key];
+    return out;
+  };
+
+  return {
+    async read(request): Promise<readonly Row[]> {
+      const columns = modelColumns(request.model);
+      if (request.kind === 'load') {
+        const rows = await db
+          .selectFrom(columns.table)
+          .selectAll()
+          .where('id', '=', request.id)
+          .limit(1)
+          .execute();
+        return rows.map((row) => toFields(columns, row));
+      }
+      const rows = await db
+        .selectFrom(columns.table)
+        .selectAll()
+        .limit(request.query?.limit ?? 1000)
+        .execute();
+      return rows.map((row) => toFields(columns, row));
+    },
+
+    async applyOperation(transaction, operation): Promise<Row> {
+      const columns = modelColumns(operation.model);
+      const id = kyselyOperationRowId(operation);
+      const input = operation.input ?? {};
+
+      if (operation.type === 'DELETE') {
+        const deleted = await transaction
+          .deleteFrom(columns.table)
+          .where('id', '=', id)
+          .returningAll()
+          .execute();
+        return deleted[0] ? toFields(columns, deleted[0]) : { id };
+      }
+
+      if (operation.type === 'CREATE') {
+        const inserted = await transaction
+          .insertInto(columns.table)
+          .values(toColumns(columns, { id, ...input }))
+          .returningAll()
+          .execute();
+        return inserted[0] ? toFields(columns, inserted[0]) : { id, ...input };
+      }
+
+      const patch = toColumns(columns, {
+        ...input,
+        ...(operation.type === 'ARCHIVE' ? { archivedAt: new Date() } : {}),
+        ...(operation.type === 'UNARCHIVE' ? { archivedAt: null } : {}),
+      });
+      const updated = await transaction
+        .updateTable(columns.table)
+        .set(patch)
+        .where('id', '=', id)
+        .returningAll()
+        .execute();
+      return updated[0] ? toFields(columns, updated[0]) : { id, ...input };
+    },
+  };
+}