@abloatai/transaction 0.56.0 → 0.58.0

package/src/source/adapters/kysely.ts

@@ -24,28 +24,40 @@ import type {
   DataSourceAdapter,
   MutationAdapter,
   Row,
-} from '../adapter.js';
-import { defineDatabaseAdapter } from '../adapterFactory.js';
-import { postgresAdapterProfile } from '../adapterProfile.js';
-import type { ChangeSet, EventsPage, Migration } from '../contract.js';
+} from './adapter.js';
+import { defineDatabaseAdapter } from './adapterFactory.js';
+import { postgresAdapterProfile } from './adapterProfile.js';
+import type { ChangeSet } from './contract.js';
+import type { Migration } from './migration.js';
 import {
   changeSetSchema,
-  outboxEventSchema,
   sourceCommitEchoMarkerSchema,
   sourceCommitEchoIntentSchema,
   type SourceCommitEchoIntent,
-} from '../contract.js';
+} from './contract.js';
 import {
   assertSourceIdempotencyIntent,
   assertSourceIdempotencyRetention,
   sourceChangeIntentHash,
   SOURCE_IDEMPOTENCY_RETENTION,
-} from '../idempotency.js';
+} from './idempotency.js';
 import {
   adapterTableMigrations,
   idempotencyLedgerMigrations,
-} from '../migrations.js';
+} from './migrations.js';
 import { ABLO_POSTGRES_COMMIT_ECHO_PREFIX } from '../types.js';
+import {
+  authorizeSourceChange,
+  authorizeSourceRead,
+  lockSourceSubjectCreates,
+  rethrowStrictCreateConflict,
+  sourceSyncGroups,
+} from './subjectAuthorization.js';
+import {
+  decodeDatabaseOutboxEvent,
+  ENDPOINT_OUTBOX_PRUNE_BATCH_SIZE,
+  type EventsPage,
+} from '../outbox/index.js';
 import {
   createKyselyMutationCore,
   kyselyOperationRowId,
@@ -259,6 +271,8 @@ export interface KyselyMutationAdapterOptions {
    * typenames equal its keys.
    */
   readonly markerModelFor?: (operationModel: string) => string;
+  /** Schema required to enforce row/subject authorization in this adapter. */
+  readonly schema?: Schema;
 }
 
 export function createKyselyMutationAdapter(
@@ -287,8 +301,9 @@ export function createKyselyMutationAdapter(
         : idempotencyLedgerMigrations();
     },
 
-    read(request) {
-      return core.read(request);
+    async read(request) {
+      const rows = await core.read(request);
+      return options.schema ? authorizeSourceRead(options.schema, request, rows) : rows;
     },
 
     async commit(change: ChangeSet): Promise<AdapterCommitResult> {
@@ -326,6 +341,25 @@ export function createKyselyMutationAdapter(
           return { rows: parseCachedRows(cachedRow.response) };
         }
 
+        if (options.schema) {
+          await lockSourceSubjectCreates(options.schema, request, async (_operation, key) => {
+            await transaction.executeQuery(rawQuery(
+              'subject-create-lock',
+              'SELECT pg_advisory_xact_lock(hashtextextended($1, 0))',
+              [key],
+            ));
+          });
+          await authorizeSourceChange(options.schema, request, async (operation) => {
+            if (!operation.id) return null;
+            const rows = await core.read(
+              { kind: 'load', model: operation.model, id: operation.id },
+              transaction,
+              { forUpdate: true },
+            );
+            return rows[0] ?? null;
+          });
+        }
+
         // Direct mode dispatches every operation before awaiting any of them, so
         // the driver pipelines them into one trip instead of paying a full
         // round trip per row. Postgres still executes them IN ORDER on the
@@ -339,9 +373,17 @@ export function createKyselyMutationAdapter(
         // returned row, so operation i+1's write cannot be dispatched before
         // operation i has answered.
         const rows: Row[] = [];
+        const applyStrict = async (operation: ChangeSet['operations'][number]): Promise<Row> => {
+          try {
+            return await core.applyOperation(transaction, operation);
+          } catch (error) {
+            if (operation.type === 'CREATE') rethrowStrictCreateConflict(error, operation);
+            throw error;
+          }
+        };
         if (mode === 'direct') {
           const dispatched = request.operations.map((operation) =>
-            core.applyOperation(transaction, operation),
+            applyStrict(operation),
           );
           // Settle every dispatch before inspecting, so a later rejection is
           // never an unhandled rejection, then surface the FIRST failure in
@@ -354,7 +396,7 @@ export function createKyselyMutationAdapter(
           }
         } else {
           for (const [index, operation] of request.operations.entries()) {
-            const row = await core.applyOperation(transaction, operation);
+            const row = await applyStrict(operation);
             rows.push(row);
 
             const entityId = String(row.id ?? kyselyOperationRowId(operation));
@@ -366,6 +408,10 @@ export function createKyselyMutationAdapter(
                 entity_id: entityId,
                 type: operation.type,
                 data: operation.type === 'DELETE' ? null : JSON.stringify(row),
+                event_version: 2,
+                sync_groups: options.schema
+                  ? sourceSyncGroups(options.schema, operation.model, row)
+                  : [],
                 correlation_id: request.correlationId,
                 transaction_id: operation.transactionId ?? null,
                 occurred_at: Date.now(),
@@ -402,12 +448,29 @@ export function kyselyDataSource<S extends SchemaRecord>(
     db,
     createKyselyMutationCore(db, schema),
     'endpoint',
+    { schema },
   );
 
   return defineDatabaseAdapter({
     ...mutation,
     capabilities: { ...mutation.capabilities, outboxEvents: true },
 
+    async acknowledgeEvents(acknowledgedThrough: string): Promise<void> {
+      await db.transaction().execute(async (transaction) => {
+        await transaction.executeQuery(
+          rawQuery(
+            'ablo-outbox-prune-acknowledged',
+            `DELETE FROM ablo_outbox
+              WHERE cursor IN (
+                SELECT cursor FROM ablo_outbox
+                 WHERE cursor <= $1 ORDER BY cursor ASC LIMIT $2
+            )`,
+            [acknowledgedThrough, ENDPOINT_OUTBOX_PRUNE_BATCH_SIZE],
+          ),
+        );
+      });
+    },
+
     async events(cursor: string | null, limit: number): Promise<EventsPage> {
       const rows = await db
         .selectFrom('ablo_outbox')
@@ -416,21 +479,7 @@ export function kyselyDataSource<S extends SchemaRecord>(
         .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),
-        }),
-      );
+      const events = rows.map(decodeDatabaseOutboxEvent);
       return { events, nextCursor: events.at(-1)?.cursor ?? null };
     },
   });
@@ -458,6 +507,7 @@ export function kyselyDirectMutation<S extends SchemaRecord>(
         markerModels.get(operationModel) ??
         markerModels.get(operationModel.toLowerCase()) ??
         operationModel,
+      schema,
     },
   );
 }

package/src/source/adapters/kyselyMutationCore.ts

@@ -13,8 +13,9 @@ 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';
+import type { AdapterReadRequest, Row } from './adapter.js';
+import type { Operation } from './contract.js';
+import { sourceSubjectRule, sourceSubjectValues } from './subjectAuthorization.js';
 
 /** The subset of a Kysely instance, or transaction handle, used by the core. */
 export interface KyselyLike {
@@ -48,6 +49,7 @@ export interface KyselySelectBuilder {
   where(column: string, operator: string, value: unknown): KyselySelectBuilder;
   orderBy(column: string, direction: 'asc' | 'desc'): KyselySelectBuilder;
   limit(limit: number): KyselySelectBuilder;
+  forUpdate(): KyselySelectBuilder;
   execute(): Promise<readonly Row[]>;
 }
 
@@ -140,7 +142,11 @@ function suppliedOperationRowId(operation: Operation): string | undefined {
 
 /** The transport-independent Kysely field/column mutation boundary. */
 export interface KyselyMutationCore {
-  read(request: AdapterReadRequest): Promise<readonly Row[]>;
+  read(
+    request: AdapterReadRequest,
+    database?: KyselyLike,
+    options?: { readonly forUpdate?: boolean },
+  ): Promise<readonly Row[]>;
   applyOperation(transaction: KyselyLike, operation: Operation): Promise<Row>;
 }
 
@@ -185,22 +191,28 @@ export function createKyselyMutationCore<S extends SchemaRecord>(
   };
 
   return {
-    async read(request): Promise<readonly Row[]> {
+    async read(request, database = db, options): Promise<readonly Row[]> {
       const columns = modelColumns(request.model);
       if (request.kind === 'load') {
-        const rows = await db
+        let query = database
           .selectFrom(columns.table)
           .selectAll()
           .where(columnFor(columns, 'id'), '=', request.id)
-          .limit(1)
-          .execute();
+          .limit(1);
+        if (options?.forUpdate) query = query.forUpdate();
+        const rows = await query.execute();
         return rows.map((row) => toFields(columns, row));
       }
-      const rows = await db
+      let query = database
         .selectFrom(columns.table)
-        .selectAll()
-        .limit(request.query?.limit ?? 1000)
-        .execute();
+        .selectAll();
+      const rule = sourceSubjectRule(schema, request.model);
+      const subjects = sourceSubjectValues(rule, request.scope?.syncGroups);
+      if (subjects) {
+        if (subjects.length === 0) return [];
+        query = query.where(columnFor(columns, rule!.field), 'in', subjects);
+      }
+      const rows = await query.limit(request.query?.limit ?? 1000).execute();
       return rows.map((row) => toFields(columns, row));
     },
 

package/src/source/adapters/memory.ts

@@ -6,8 +6,8 @@
  * mapper is complete when it passes the same suite this one passes.
  *
  * It models the semantics minimally but faithfully: one row store per model, an
- * idempotency ledger keyed by scoped correlation, and an append-only outbox with a
- * monotonic cursor.
+ * idempotency ledger keyed by scoped correlation, and an acknowledgement-pruned
+ * outbox with a monotonic cursor.
  */
 
 import { AbloValidationError } from '../../errors.js';
@@ -16,14 +16,16 @@ import type {
   AdapterReadRequest,
   DataSourceAdapter,
   Row,
-} from '../adapter.js';
-import { defineDatabaseAdapter } from '../adapterFactory.js';
-import { memoryAdapterProfile } from '../adapterProfile.js';
-import type { ChangeSet, EventsPage, Migration, Operation, OutboxEvent } from '../contract.js';
+} from './adapter.js';
+import { defineDatabaseAdapter } from './adapterFactory.js';
+import { memoryAdapterProfile } from './adapterProfile.js';
+import type { ChangeSet, Operation } from './contract.js';
+import type { Migration } from './migration.js';
+import type { EventsPage, OutboxEvent } from '../outbox/index.js';
 import {
   assertSourceIdempotencyIntent,
   sourceChangeIntentHash,
-} from '../idempotency.js';
+} from './idempotency.js';
 
 function rowId(op: Operation): string {
   const id = op.id ?? (op.input?.id as string | undefined);
@@ -41,8 +43,9 @@ export function memoryDataSource(): DataSourceAdapter {
     string,
     { readonly requestHash: string; readonly rows: Row[] }
   >();
-  /** Append-only outbox; `cursor` is the 1-based index as a string. */
+  /** Acknowledgement-pruned outbox with a monotonic cursor. */
   const outbox: OutboxEvent[] = [];
+  let nextOutboxCursor = 1;
 
   const modelStore = (model: string): Map<string, Row> => {
     let m = store.get(model);
@@ -136,20 +139,34 @@ export function memoryDataSource(): DataSourceAdapter {
         rows.push(row);
         // Transactional outbox: one event per op, monotonic cursor.
         outbox.push({
+          version: 2,
           id: `${change.correlationId}:${index}`,
           model: op.model,
           entityId: String(row.id ?? rowId(op)),
           type: op.type,
           data: op.type === 'DELETE' ? null : row,
+          syncGroups: [],
           correlationId: change.correlationId,
           ...(op.transactionId ? { transactionId: op.transactionId } : {}),
-          cursor: String(outbox.length + 1),
+          cursor: String(nextOutboxCursor++),
         });
       }
       idempotency.set(change.correlationId, { requestHash, rows });
       return { rows };
     },
 
+    async acknowledgeEvents(acknowledgedThrough: string): Promise<void> {
+      const after = Number(acknowledgedThrough);
+      let acknowledgedCount = 0;
+      while (
+        acknowledgedCount < outbox.length &&
+        Number(outbox[acknowledgedCount]?.cursor) <= after
+      ) {
+        acknowledgedCount += 1;
+      }
+      if (acknowledgedCount > 0) outbox.splice(0, acknowledgedCount);
+    },
+
     async events(cursor: string | null, limit: number): Promise<EventsPage> {
       const after = cursor ? Number(cursor) : 0;
       const page = outbox.filter((e) => Number(e.cursor) > after).slice(0, limit);

package/src/source/adapters/migration.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+
+/** One forward-only infrastructure migration shipped by an adapter. */
+export const migrationSchema = z.object({
+  /** Stable name, used as the migration filename + applied-ledger key. */
+  name: z.string().min(1),
+  /** The forward SQL. */
+  up: z.string().min(1),
+});
+
+export type Migration = z.infer<typeof migrationSchema>;

package/src/source/{migrations.ts → adapters/migrations.ts}

@@ -10,7 +10,10 @@
  * it records changes in its own `sync_deltas` log instead.
  */
 
-import type { Migration } from './contract.js';
+import type { Migration } from './migration.js';
+import { endpointOutboxMigrations } from '../outbox/index.js';
+
+export { endpointOutboxMigrations } from '../outbox/index.js';
 
 /**
  * Add a column to `ablo_idempotency` only when it is genuinely missing.
@@ -87,37 +90,7 @@ export function idempotencyLedgerMigrations(schema = 'public'): readonly Migrati
   ];
 }
 
-/** Endpoint-only transactional outbox and its correlation columns. */
-export function endpointOutboxMigrations(): readonly Migration[] {
-  return [
-    {
-      name: 'ablo_outbox',
-      up: `CREATE TABLE IF NOT EXISTS ablo_outbox (
-  cursor          BIGSERIAL PRIMARY KEY,
-  id              TEXT NOT NULL UNIQUE,
-  model           TEXT NOT NULL,
-  entity_id       TEXT NOT NULL,
-  type            TEXT NOT NULL,
-  data            JSONB,
-  organization_id TEXT,
-  client_tx_id    TEXT,
-  correlation_id  TEXT,
-  transaction_id  TEXT,
-  occurred_at     BIGINT,
-  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
-);`,
-    },
-    {
-      name: 'ablo_outbox_correlation',
-      up: `ALTER TABLE ablo_outbox
-  ADD COLUMN IF NOT EXISTS correlation_id TEXT;
-ALTER TABLE ablo_outbox
-  ADD COLUMN IF NOT EXISTS transaction_id TEXT;`,
-    },
-  ];
-}
-
 /** Full endpoint adapter migrations (ledger + outbox). */
-export function adapterTableMigrations(): readonly Migration[] {
-  return [...idempotencyLedgerMigrations(), ...endpointOutboxMigrations()];
+export function adapterTableMigrations(schema = 'public'): readonly Migration[] {
+  return [...idempotencyLedgerMigrations(schema), ...endpointOutboxMigrations(schema)];
 }

package/src/source/adapters/prisma.ts

@@ -20,24 +20,40 @@ import type {
   AdapterReadRequest,
   DataSourceAdapter,
   Row,
-} from '../adapter.js';
-import { defineDatabaseAdapter } from '../adapterFactory.js';
-import { postgresAdapterProfile } from '../adapterProfile.js';
-import type { ChangeSet, EventsPage, Migration, Operation, OutboxEvent } from '../contract.js';
-import { outboxEventSchema } from '../contract.js';
-import { adapterTableMigrations } from '../migrations.js';
+} from './adapter.js';
+import { defineDatabaseAdapter } from './adapterFactory.js';
+import { postgresAdapterProfile } from './adapterProfile.js';
+import type { ChangeSet, Operation } from './contract.js';
+import type { Migration } from './migration.js';
+import type { EventsPage, OutboxEvent } from '../outbox/index.js';
+import { adapterTableMigrations } from './migrations.js';
 import {
   assertSourceIdempotencyIntent,
   assertSourceIdempotencyRetention,
   SOURCE_IDEMPOTENCY_RETENTION,
   sourceChangeIntentHash,
-} from '../idempotency.js';
+} from './idempotency.js';
 import type { SchemaRecord, Schema } from '../../schema/schema.js';
+import { toSchemaJSON } from '../../schema/serialize.js';
+import { camelToSnake } from '../../schema/ddl.js';
 import {
   ABLO_POSTGRES_COMMIT_ECHO_PREFIX,
   type SourceListQuery,
   type SourceWhere,
 } from '../types.js';
+import {
+  authorizeSourceChange,
+  authorizeSourceRead,
+  lockSourceSubjectCreates,
+  rethrowStrictCreateConflict,
+  sourceSyncGroups,
+  sourceSubjectRule,
+  sourceSubjectValues,
+} from './subjectAuthorization.js';
+import {
+  decodeDatabaseOutboxEvent,
+  ENDPOINT_OUTBOX_PRUNE_BATCH_SIZE,
+} from '../outbox/index.js';
 
 /** A Prisma model delegate — the subset of its methods the adapter calls. */
 export interface PrismaDelegate {
@@ -146,7 +162,19 @@ export function prismaDataSource<S extends SchemaRecord>(
   options: PrismaDataSourceOptions = {},
 ): DataSourceAdapter {
   const delegateName = options.delegateName ?? lowerFirst;
-  void schema; // held for typed reads and model validation
+  const lockTargets = new Map<string, { table: string; subjectColumn: string }>();
+  for (const [key, definition] of Object.entries(toSchemaJSON(schema).models)) {
+    if (!definition.subject) continue;
+    const target = {
+      table: definition.tableName ?? key,
+      subjectColumn:
+        definition.fields[definition.subject.field]?.column ??
+        camelToSnake(definition.subject.field),
+    };
+    lockTargets.set(key.toLowerCase(), target);
+    if (definition.typename) lockTargets.set(definition.typename.toLowerCase(), target);
+  }
+  const quoted = (identifier: string): string => `"${identifier.replaceAll('"', '""')}"`;
 
   const applyOperation = async (tx: PrismaRaw, op: Operation): Promise<Row> => {
     if (op.where) {
@@ -188,9 +216,18 @@ export function prismaDataSource<S extends SchemaRecord>(
       const delegate = delegateFor(prisma, delegateName(req.model));
       if (req.kind === 'load') {
         const row = await delegate.findUnique({ where: { id: req.id } });
-        return row ? [row] : [];
+        return authorizeSourceRead(schema, req, row ? [row] : []);
+      }
+      const args = findManyArgs(req.query);
+      const rule = sourceSubjectRule(schema, req.model);
+      const subjects = sourceSubjectValues(rule, req.scope?.syncGroups);
+      if (subjects?.length === 0) return [];
+      if (subjects) {
+        args.where = {
+          AND: [args.where ?? {}, { [rule!.field]: { in: subjects } }],
+        };
       }
-      return delegate.findMany(findManyArgs(req.query));
+      return authorizeSourceRead(schema, req, await delegate.findMany(args));
     },
 
     async commit(change: ChangeSet): Promise<AdapterCommitResult> {
@@ -211,22 +248,52 @@ export function prismaDataSource<S extends SchemaRecord>(
           return { rows: cachedRow.response };
         }
 
+        await lockSourceSubjectCreates(schema, change, async (_operation, key) => {
+          await tx.$queryRawUnsafe(
+            `SELECT pg_advisory_xact_lock(hashtextextended($1, 0))`,
+            key,
+          );
+        });
+
+        await authorizeSourceChange(schema, change, async (operation) => {
+          if (!operation.id) return null;
+          const rule = sourceSubjectRule(schema, operation.model);
+          const target = lockTargets.get(operation.model.toLowerCase());
+          if (!rule || !target) return null;
+          const rows = await tx.$queryRawUnsafe<Row[]>(
+            `SELECT id, ${quoted(target.subjectColumn)} AS ${quoted(rule.field)}
+               FROM ${quoted(target.table)}
+              WHERE id = $1
+              LIMIT 1
+              FOR UPDATE`,
+            operation.id,
+          );
+          return rows[0] ?? null;
+        });
+
         const rows: Row[] = [];
         for (const [index, op] of change.operations.entries()) {
-          const row = await applyOperation(tx, op);
+          let row: Row;
+          try {
+            row = await applyOperation(tx, op);
+          } catch (error) {
+            if (op.type === 'CREATE') rethrowStrictCreateConflict(error, op);
+            throw error;
+          }
           rows.push(row);
           const entityId = String(row.id ?? rowId(op));
           // Transactional outbox: one event per operation, written in this same transaction.
           await tx.$executeRawUnsafe(
             `INSERT INTO ablo_outbox (
-               id, model, entity_id, type, data,
+               id, model, entity_id, type, data, event_version, sync_groups,
                correlation_id, transaction_id, occurred_at
-             ) VALUES ($1, $2, $3, $4, $5::jsonb, $6, $7, $8)`,
+             ) VALUES ($1, $2, $3, $4, $5::jsonb, 2, $6::text[], $7, $8, $9)`,
             `${change.correlationId}:${index}`,
             op.model,
             entityId,
             op.type,
             JSON.stringify(op.type === 'DELETE' ? null : row),
+            sourceSyncGroups(schema, op.model, row),
             change.correlationId,
             op.transactionId ?? null,
             Date.now(),
@@ -257,34 +324,31 @@ export function prismaDataSource<S extends SchemaRecord>(
       });
     },
 
+    async acknowledgeEvents(acknowledgedThrough: string): Promise<void> {
+      await prisma.$transaction(async (tx) => {
+        await tx.$executeRawUnsafe(
+          `DELETE FROM ablo_outbox
+            WHERE cursor IN (
+              SELECT cursor FROM ablo_outbox
+               WHERE cursor <= $1 ORDER BY cursor ASC LIMIT $2
+            )`,
+          acknowledgedThrough,
+          ENDPOINT_OUTBOX_PRUNE_BATCH_SIZE,
+        );
+      });
+    },
+
     async events(cursor: string | null, limit: number): Promise<EventsPage> {
-      const after = cursor ? cursor : '0';
+      const after = cursor ?? '0';
       const rows = await prisma.$queryRawUnsafe<Record<string, unknown>[]>(
-        `SELECT cursor, id, model, entity_id, type, data, organization_id,
+        `SELECT cursor, id, model, entity_id, type, data, event_version, sync_groups, organization_id,
                 client_tx_id, correlation_id, transaction_id, occurred_at
          FROM ablo_outbox WHERE cursor > $1 ORDER BY cursor ASC LIMIT $2`,
         after,
         limit,
       );
-      const events: OutboxEvent[] = rows.map((r) =>
-        outboxEventSchema.parse({
-          id: r.id,
-          model: r.model,
-          entityId: r.entity_id,
-          type: r.type,
-          data: r.data ?? null,
-          organizationId: r.organization_id ?? null,
-          clientTxId: r.client_tx_id ?? null,
-          correlationId: r.correlation_id ?? null,
-          transactionId: r.transaction_id ?? null,
-          occurredAt: r.occurred_at != null ? Number(r.occurred_at) : null,
-          cursor: String(r.cursor),
-        }),
-      );
-      return {
-        events,
-        nextCursor: events.at(-1)?.cursor ?? null,
-      };
+      const events: OutboxEvent[] = rows.map(decodeDatabaseOutboxEvent);
+      return { events, nextCursor: events.at(-1)?.cursor ?? null };
     },
   });
 }