@abloatai/transaction 0.56.0 → 0.57.0

package/src/source/adapters/kysely.ts

@@ -46,6 +46,13 @@ import {
   idempotencyLedgerMigrations,
 } from '../migrations.js';
 import { ABLO_POSTGRES_COMMIT_ECHO_PREFIX } from '../types.js';
+import {
+  authorizeSourceChange,
+  authorizeSourceRead,
+  lockSourceSubjectCreates,
+  rethrowStrictCreateConflict,
+  sourceSyncGroups,
+} from '../subjectAuthorization.js';
 import {
   createKyselyMutationCore,
   kyselyOperationRowId,
@@ -259,6 +266,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 +296,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 +336,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 +368,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 +391,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 +403,9 @@ export function createKyselyMutationAdapter(
                 entity_id: entityId,
                 type: operation.type,
                 data: operation.type === 'DELETE' ? null : JSON.stringify(row),
+                sync_groups: options.schema
+                  ? sourceSyncGroups(options.schema, operation.model, row)
+                  : [],
                 correlation_id: request.correlationId,
                 transaction_id: operation.transactionId ?? null,
                 occurred_at: Date.now(),
@@ -402,6 +442,7 @@ export function kyselyDataSource<S extends SchemaRecord>(
     db,
     createKyselyMutationCore(db, schema),
     'endpoint',
+    { schema },
   );
 
   return defineDatabaseAdapter({
@@ -423,6 +464,7 @@ export function kyselyDataSource<S extends SchemaRecord>(
           entityId: row.entity_id,
           type: row.type,
           data: typeof row.data === 'string' ? JSON.parse(row.data) : row.data ?? null,
+          syncGroups: row.sync_groups ?? [],
           organizationId: row.organization_id ?? null,
           clientTxId: row.client_tx_id ?? null,
           correlationId: row.correlation_id ?? null,
@@ -458,6 +500,7 @@ export function kyselyDirectMutation<S extends SchemaRecord>(
         markerModels.get(operationModel) ??
         markerModels.get(operationModel.toLowerCase()) ??
         operationModel,
+      schema,
     },
   );
 }

package/src/source/adapters/kyselyMutationCore.ts

@@ -15,6 +15,7 @@ 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 { 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

@@ -141,6 +141,7 @@ export function memoryDataSource(): DataSourceAdapter {
           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),

package/src/source/adapters/prisma.ts

@@ -33,11 +33,22 @@ import {
   sourceChangeIntentHash,
 } 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';
 
 /** A Prisma model delegate — the subset of its methods the adapter calls. */
 export interface PrismaDelegate {
@@ -146,7 +157,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 +211,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] : []);
       }
-      return delegate.findMany(findManyArgs(req.query));
+      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 authorizeSourceRead(schema, req, await delegate.findMany(args));
     },
 
     async commit(change: ChangeSet): Promise<AdapterCommitResult> {
@@ -211,22 +243,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, 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, $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(),
@@ -260,7 +322,7 @@ export function prismaDataSource<S extends SchemaRecord>(
     async events(cursor: string | null, limit: number): Promise<EventsPage> {
       const after = cursor ? 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, 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,
@@ -273,6 +335,7 @@ export function prismaDataSource<S extends SchemaRecord>(
           entityId: r.entity_id,
           type: r.type,
           data: r.data ?? null,
+          syncGroups: r.sync_groups ?? [],
           organizationId: r.organization_id ?? null,
           clientTxId: r.client_tx_id ?? null,
           correlationId: r.correlation_id ?? null,

package/src/source/contract.ts

@@ -29,6 +29,7 @@ import {
   type SourceCommitEchoMarker,
   type SourceOperation,
 } from './types.js';
+import type { SourceRequestContext } from './types.js';
 
 const jsonObject = z.record(z.string(), z.unknown());
 
@@ -149,6 +150,14 @@ export const changeSetSchema = z.object({
   correlationId: correlationIdSchema,
   intentHash: z.string().regex(/^[a-f0-9]{64}$/).optional(),
   echo: sourceCommitEchoSchema.optional(),
+  scope: z.object({
+    participantId: z.string().optional(),
+    participantKind: z.enum(['user', 'agent', 'system']).optional(),
+    organizationId: z.string().optional(),
+    branchId: z.string().optional(),
+    projectId: z.string().optional(),
+    syncGroups: z.array(z.string()).optional(),
+  }).optional() satisfies z.ZodType<SourceRequestContext | undefined>,
 });
 export type ChangeSet = z.infer<typeof changeSetSchema>;
 
@@ -168,6 +177,8 @@ export const outboxEventSchema = z.object({
   /** The changed row, in the key shape `SourceEvent.data` defines: the model's
    *  declared schema fields, never the table's physical column names. */
   data: jsonObject.nullish(),
+  /** Exact record routes captured in the same transaction as the row change. */
+  syncGroups: z.array(z.string().min(1)).readonly(),
   organizationId: z.string().nullish(),
   /** Legacy source transaction id. Never use this field to settle a queued commit. */
   clientTxId: z.string().nullish(),

package/src/source/factory.ts

@@ -12,7 +12,16 @@ import type {
   InferCreate,
 } from '../schema/schema.js';
 import type { DataSourceAdapter } from './adapter.js';
+import type { AdapterReadRequest, Row } from './adapter.js';
 import { changeSetSchema } from './contract.js';
+import { AbloError, AbloPermissionError } from '../errors.js';
+import {
+  authorizeSourceChange,
+  authorizeSourceRead,
+  lockSourceSubjectCreates,
+  sourceSubjectRule,
+  sourceSubjectValues,
+} from './subjectAuthorization.js';
 import {
   SourceSignatureError,
   verifyAbloSourceRequest,
@@ -31,6 +40,7 @@ import type {
   SourceRequest,
   SourceRequestContext,
   SourceScope,
+  SourceSubjectTransactionHandler,
 } from './types.js';
 
 type SourceModels<S extends SchemaRecord, TAuth> = Partial<{
@@ -86,6 +96,12 @@ export type DataSourceOptions<S extends SchemaRecord, TAuth = unknown> = {
    * run inside one transaction you control.
    */
   readonly commit?: SourceCommitHandler<TAuth>;
+  /**
+   * Required for a hand-written commit touching any subject-scoped model.
+   * The hook owns one customer-database transaction and calls `run` with a
+   * locking row loader and the batch commit bound to that same transaction.
+   */
+  readonly subjectTransaction?: SourceSubjectTransactionHandler<TAuth>;
   /**
    * Reports changes that happened outside the SDK — cron jobs, dashboard edits,
    * batch imports — which Ablo polls for. Each event you return becomes a delta and
@@ -165,6 +181,7 @@ async function handleViaAdapter(
       correlationId,
       intentHash: body.intentHash,
       echo: body.echo,
+      scope,
     });
     if (!parsed.success) {
       return json({ error: 'source_commit_invalid', message: parsed.error.message }, 400);
@@ -195,6 +212,7 @@ async function handleViaAdapter(
         entityId: event.entityId,
         type: event.type,
         ...(event.data !== undefined && event.data !== null ? { data: event.data } : {}),
+        syncGroups: event.syncGroups,
         ...(event.organizationId ? { organizationId: event.organizationId } : {}),
         ...(event.clientTxId ? { clientTxId: event.clientTxId } : {}),
         ...(event.correlationId ? { correlationId: event.correlationId } : {}),
@@ -277,6 +295,34 @@ function sameModel(operations: readonly SourceOperation[]): string | null {
   return operations.every((op) => op.model === first) ? first : null;
 }
 
+function subjectDenial(error: unknown): Response | null {
+  return error instanceof AbloPermissionError && error.code === 'capability_scope_denied'
+    ? json({ error: error.code, message: error.message }, error.httpStatus ?? 403)
+    : null;
+}
+
+function typedSourceError(error: unknown): Response | null {
+  const denial = subjectDenial(error);
+  if (denial) return denial;
+  return error instanceof AbloError && error.code && error.httpStatus
+    ? json({ error: error.code, message: error.message }, error.httpStatus)
+    : null;
+}
+
+function parseHandWrittenChange<TAuth>(
+  body: Extract<SourceRequest, { type: 'commit' }>,
+  context: SourceHandlerContext<TAuth>,
+) {
+  const correlationId = body.correlationId ?? body.clientTxId;
+  return changeSetSchema.safeParse({
+    operations: body.operations,
+    correlationId,
+    intentHash: body.intentHash,
+    echo: body.echo,
+    scope: context.scope,
+  });
+}
+
 /**
  * Creates a Data Source endpoint you host in front of your own database.
  *
@@ -368,7 +414,13 @@ export function dataSource<const S extends SchemaRecord, TAuth = unknown>(
     // generic layer where rows are plain JSON, so there is no per-model handler
     // lookup on this path.
     if (options.adapter) {
-      return handleViaAdapter(options.adapter, body, context.scope);
+      try {
+        return await handleViaAdapter(options.adapter, body, context.scope);
+      } catch (error) {
+        const typed = typedSourceError(error);
+        if (typed) return typed;
+        throw error;
+      }
     }
 
     if (body.type === 'load') {
@@ -377,20 +429,104 @@ export function dataSource<const S extends SchemaRecord, TAuth = unknown>(
         return json({ error: 'source_load_not_configured', model: body.model }, 404);
       }
       const row = await handlers.load({ id: body.id, context });
-      return json({ row });
+      try {
+        const authorized = authorizeSourceRead(
+          options.schema,
+          { kind: 'load', model: body.model, id: body.id, ...(context.scope ? { scope: context.scope } : {}) },
+          row ? [row as Row] : [],
+        );
+        return json({ row: authorized[0] ?? null });
+      } catch (error) {
+        const typed = typedSourceError(error);
+        if (typed) return typed;
+        throw error;
+      }
     }
 
     if (body.type === 'list') {
       const handlers = getModelHandlers(options, body.model);
-      if (!handlers?.list) {
+      const rule = sourceSubjectRule(options.schema, body.model);
+      if (rule && !handlers?.subjectList) {
+        return json({
+          error: 'source_subject_list_not_configured',
+          message: `Subject-scoped model "${body.model}" requires subjectList() so filtering occurs before pagination.`,
+        }, 403);
+      }
+      if (!rule && !handlers?.list) {
         return json({ error: 'source_list_not_configured', model: body.model }, 404);
       }
-      const result = await handlers.list({ query: body.query ?? {}, context });
+      const result = rule
+        ? await handlers!.subjectList!({
+            query: body.query ?? {},
+            subject: {
+              field: rule.field,
+              values: sourceSubjectValues(rule, context.scope?.syncGroups) ?? [],
+            },
+            context,
+          })
+        : await handlers!.list!({ query: body.query ?? {}, context });
       const normalized = normalizeListResult(result);
-      return json(normalized);
+      const request: AdapterReadRequest = {
+        kind: 'list',
+        model: body.model,
+        ...(body.query ? { query: body.query } : {}),
+        ...(context.scope ? { scope: context.scope } : {}),
+      };
+      return json({
+        ...normalized,
+        rows: authorizeSourceRead(options.schema, request, normalized.rows as readonly Row[]),
+      });
     }
 
     if (body.type === 'commit') {
+      const hasSubject = body.operations.some((operation) =>
+        sourceSubjectRule(options.schema, operation.model));
+      if (hasSubject) {
+        if (!options.subjectTransaction) {
+          return json({
+            error: 'source_subject_transaction_required',
+            message: 'Subject-scoped custom commits require subjectTransaction() so authorization and mutation share one transaction.',
+          }, 403);
+        }
+        const parsed = parseHandWrittenChange(body, context);
+        if (!parsed.success) {
+          return json({ error: 'source_commit_invalid', message: parsed.error.message }, 400);
+        }
+        try {
+          let ranBoundary = false;
+          const result = await options.subjectTransaction(
+            {
+              operations: body.operations,
+              correlationId: body.correlationId ?? body.clientTxId,
+              clientTxId: body.clientTxId,
+              intentHash: body.intentHash,
+              echo: body.echo,
+              context,
+            },
+            async ({ lockCreate, load, commit }) => {
+              if (ranBoundary) {
+                throw new Error('subjectTransaction run() may be called only once');
+              }
+              ranBoundary = true;
+              await lockSourceSubjectCreates(
+                options.schema,
+                parsed.data,
+                (operation) => lockCreate(operation),
+              );
+              await authorizeSourceChange(options.schema, parsed.data, load);
+              return commit();
+            },
+          );
+          if (!ranBoundary) {
+            throw new Error('subjectTransaction must call run() inside its database transaction');
+          }
+          return json(result);
+        } catch (error) {
+          const typed = typedSourceError(error);
+          if (typed) return typed;
+          throw error;
+        }
+      }
       if (options.commit) {
         const result = await options.commit({
           operations: body.operations,

package/src/source/index.ts

@@ -37,6 +37,8 @@ export {
   type SourceHandlerContext,
   type SourceModelHandlers,
   type SourceCommitHandler,
+  type SourceSubjectTransactionBoundary,
+  type SourceSubjectTransactionHandler,
   type SourceApiKey,
   type SourceLoadRequest,
   type SourceListRequest,
@@ -61,6 +63,10 @@ export {
   type DataSourceOptions,
 } from './factory.js';
 
+export {
+  sourceSubjectCreateLockKey,
+} from './subjectAuthorization.js';
+
 export {
   createPushQueue,
   InMemoryPushQueueStorage,

package/src/source/migrations.ts

@@ -99,6 +99,7 @@ export function endpointOutboxMigrations(): readonly Migration[] {
   entity_id       TEXT NOT NULL,
   type            TEXT NOT NULL,
   data            JSONB,
+  sync_groups      TEXT[] NOT NULL,
   organization_id TEXT,
   client_tx_id    TEXT,
   correlation_id  TEXT,
@@ -114,6 +115,26 @@ export function endpointOutboxMigrations(): readonly Migration[] {
 ALTER TABLE ablo_outbox
   ADD COLUMN IF NOT EXISTS transaction_id TEXT;`,
     },
+    {
+      name: 'ablo_outbox_sync_groups',
+      up: `DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM information_schema.columns
+     WHERE table_schema = current_schema()
+       AND table_name = 'ablo_outbox'
+       AND column_name = 'sync_groups'
+  ) AND EXISTS (SELECT 1 FROM ablo_outbox) THEN
+    RAISE EXCEPTION USING
+      ERRCODE = '55000',
+      MESSAGE = 'ablo_outbox contains legacy events; verify the previous release consumed them, then purge those rows before adding sync_groups';
+  END IF;
+END $$;
+ALTER TABLE ablo_outbox
+  ADD COLUMN IF NOT EXISTS sync_groups TEXT[];
+ALTER TABLE ablo_outbox
+  ALTER COLUMN sync_groups SET NOT NULL;`,
+    },
   ];
 }