@abloatai/transaction 0.56.0 → 0.57.0

package/src/schema/openapi.ts

@@ -53,6 +53,20 @@ import {
   claimReleaseReplySchema,
 } from '../wire/claims.js';
 import { errorEnvelopeSchema } from '../wire/errorEnvelope.js';
+// The lifecycle promise and the rate-limit fields are contract, not prose about
+// contract: the document renders the same constants the server emits, so the
+// published policy cannot describe a signal the runtime does not send.
+import {
+  API_DEPRECATION_HEADER,
+  API_LIFECYCLE,
+  API_SUNSET_HEADER,
+  API_VERSION_HEADER,
+} from '../wire/apiLifecycle.js';
+import {
+  RATE_LIMIT_HEADER,
+  RATE_LIMIT_POLICY_HEADER,
+  RETRY_AFTER_HEADER,
+} from '../wire/rateLimit.js';
 import { modelReadResponseSchema, modelListResponseSchema } from '../wire/modelResponses.js';
 import { modelMutationRequestSchema } from '../wire/modelMutations.js';
 import { logListResponseSchema, logQuerySchema } from '../wire/feedEvent.js';
@@ -400,6 +414,106 @@ const claimIdParam = (): Json => ({
  */
 const commitBody = (): Json => jsonBody(derive(commitRequestSchema, 'input'));
 
+/**
+ * The response headers every operation carries, declared once under
+ * `components/headers` and referenced from each response.
+ *
+ * A header a caller is expected to act on has to be IN the document to be
+ * actionable: a generated client surfaces what the spec declares and drops what
+ * it does not, so an undeclared `RateLimit` is a header the caller never sees
+ * and therefore never paces against. Declaring them here rather than at each
+ * response is what keeps one description of each — the reason the names are
+ * imported rather than typed out.
+ */
+const RESPONSE_HEADER_COMPONENTS: Readonly<Record<string, Json>> = {
+  AbloVersion: {
+    description:
+      'The date-stamped contract version this response was served under. Record ' +
+      'the value your integration was built against; a change means something ' +
+      'observable was added.',
+    schema: { type: 'string', examples: ['2026-08-15'] },
+  },
+  RateLimitPolicy: {
+    description:
+      'The standing allowance for this credential kind, as a Structured Fields ' +
+      'List: `"secret";q=600;w=12`. It does not move between responses, so read ' +
+      'it once and pace against it.',
+    schema: { type: 'string', examples: ['"secret";q=600;w=12'] },
+  },
+  RateLimit: {
+    description:
+      'This caller\u2019s live position in the allowance: `r` units left, `t` ' +
+      'seconds until they refill. Present once the request is attributed to a ' +
+      'credential.',
+    schema: { type: 'string', examples: ['"secret";r=412;t=8'] },
+  },
+  RetryAfter: {
+    description: 'Whole seconds to wait before retrying. Sent with 429 and 503.',
+    schema: { type: 'integer', minimum: 1, examples: [8] },
+  },
+  RequestId: {
+    description:
+      'Correlation id for this request, repeated in the error envelope\u2019s ' +
+      '`request_id`. Quote it in a support request.',
+    schema: { type: 'string', examples: ['req_52bb7f46-17bc-4f2d-9988-89d1398d2990'] },
+  },
+  Deprecation: {
+    description:
+      'Present only on a route being withdrawn: an sf-Date of when the ' +
+      'deprecation took effect (RFC 9745). The route still answers normally.',
+    schema: { type: 'string', examples: ['@1774483200'] },
+  },
+  Sunset: {
+    description:
+      'Present only on a route being withdrawn: the HTTP-date it stops ' +
+      'answering (RFC 8594). Never less than the published notice window after ' +
+      `\`${API_DEPRECATION_HEADER}\`.`,
+    schema: { type: 'string', examples: ['Tue, 08 Sep 2026 00:00:00 GMT'] },
+  },
+};
+
+const headerRef = (name: string): Json => ({ $ref: `#/components/headers/${name}` });
+
+/** Carried by every response, whatever its status. */
+const UNIVERSAL_RESPONSE_HEADERS: Readonly<Record<string, Json>> = {
+  [API_VERSION_HEADER]: headerRef('AbloVersion'),
+  'X-Request-Id': headerRef('RequestId'),
+  [RATE_LIMIT_POLICY_HEADER]: headerRef('RateLimitPolicy'),
+  [RATE_LIMIT_HEADER]: headerRef('RateLimit'),
+  [API_DEPRECATION_HEADER]: headerRef('Deprecation'),
+  [API_SUNSET_HEADER]: headerRef('Sunset'),
+};
+
+/** Statuses where a wait is what resolves the failure, so `Retry-After` is sent. */
+const RETRY_AFTER_STATUSES = new Set(['429', '503']);
+
+/**
+ * Stamp the documented headers onto every response of every operation.
+ *
+ * Runs after the responses are built — including the canonical error ones — so
+ * a response added later cannot quietly ship without them.
+ */
+function attachResponseHeaders(paths: Json): void {
+  for (const rawPathItem of Object.values(paths)) {
+    const pathItem = rawPathItem as Json;
+    for (const [method, rawOperation] of Object.entries(pathItem)) {
+      if (!HTTP_METHODS.has(method)) continue;
+      const operation = rawOperation as Json;
+      const responses = (operation.responses ?? {}) as Json;
+      for (const [status, rawResponse] of Object.entries(responses)) {
+        const response = rawResponse as Json;
+        response.headers = {
+          ...UNIVERSAL_RESPONSE_HEADERS,
+          ...(RETRY_AFTER_STATUSES.has(status)
+            ? { [RETRY_AFTER_HEADER]: headerRef('RetryAfter') }
+            : {}),
+          ...((response.headers as Json | undefined) ?? {}),
+        };
+      }
+    }
+  }
+}
+
 /** The envelope shared by both specs — same server, same auth, same version. */
 function envelope(options: SchemaToOpenApiOptions, description: string, paths: Json, schemas: Record<string, Json>): Json {
   return {
@@ -407,7 +521,11 @@ function envelope(options: SchemaToOpenApiOptions, description: string, paths: J
     info: {
       title: options.title ?? 'Ablo API',
       version: options.version ?? 'development',
-      description,
+      // The lifecycle policy travels WITH the routes it governs. An agent
+      // deciding whether to integrate needs to know the surface will not move
+      // under it, and a policy published somewhere else is one it has to go
+      // find — so the document that describes the calls describes the promise.
+      description: `${description}\n\n${API_LIFECYCLE}`,
       license: {
         name: 'Apache License 2.0',
         identifier: 'Apache-2.0',
@@ -417,8 +535,9 @@ function envelope(options: SchemaToOpenApiOptions, description: string, paths: J
     security: [{ bearerAuth: [] }],
     components: {
       securitySchemes: {
-        bearerAuth: { type: 'http', scheme: 'bearer', description: 'Your Ablo API key (sk_… / rk_…).' },
+        bearerAuth: { type: 'http', scheme: 'bearer', description: 'Your Ablo API key (sk_\u2026 / rk_\u2026).' },
       },
+      headers: { ...RESPONSE_HEADER_COMPONENTS },
       schemas,
     },
     paths,
@@ -950,6 +1069,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
 
   applyOperationIds(paths, ABLO_OPERATION_IDS);
   attachCanonicalErrors(paths);
+  attachResponseHeaders(paths);
 
   return envelope(
     options,
@@ -1078,6 +1198,7 @@ export function schemaToOpenApi<S extends SchemaRecord>(
   operationIds['GET /v1/commits/{id}'] = 'getCommit';
   applyOperationIds(paths, operationIds);
   attachCanonicalErrors(paths);
+  attachResponseHeaders(paths);
 
   Object.assign(schemas, abloComponentSchemas());
 

package/src/schema/roles.ts

@@ -219,6 +219,8 @@ export const groupsInputSchema = z.object({
   root: scopeSchema.optional(),
   grants: grantsRefSchema.optional(),
   roles: z.union([entityRoleSchema, z.array(entityRoleSchema)]).optional(),
+  /** Acknowledge that these groups are delivery routing, not row access. */
+  routingOnly: z.literal(true).optional(),
 });
 export type GroupsInput = z.infer<typeof groupsInputSchema>;
 
@@ -314,6 +316,57 @@ export function composeEntitySyncGroups(
   return Array.from(out);
 }
 
+/** The row fields needed to derive its durable delivery groups. */
+export interface RecordSyncGroupSpec {
+  readonly subject?: { readonly kind: string; readonly field: string };
+  readonly selfKind?: string;
+  readonly parents: readonly { readonly kind: string; readonly field: string }[];
+}
+
+/** A subject-scoped row cannot be routed safely without its declared subject. */
+export class InvalidRecordSubjectError extends Error {
+  readonly field: string;
+
+  constructor(field: string) {
+    super(`Record lacks non-empty subject field "${field}".`);
+    this.name = 'InvalidRecordSubjectError';
+    this.field = field;
+  }
+}
+
+/**
+ * Derive the exact durable delivery groups for a row.
+ *
+ * Delivery matching is OR-based, so a declared subject is an exclusive
+ * authorization route: self, parent, entity-role, writer, and transitive groups
+ * must not become alternate ways to receive the row. Additional groups are
+ * accepted here so every producer applies that rule in this one place.
+ */
+export function syncGroupsForRow(
+  spec: RecordSyncGroupSpec | undefined,
+  record: Readonly<Record<string, unknown>>,
+  additionalGroups: readonly string[] = [],
+): string[] {
+  if (spec?.subject) {
+    const value = record[spec.subject.field];
+    if (typeof value !== 'string' || value.length === 0) {
+      throw new InvalidRecordSubjectError(spec.subject.field);
+    }
+    return [syncGroup(spec.subject.kind, value)];
+  }
+
+  const groups = new Set<string>(additionalGroups);
+  if (!spec) return [...groups];
+  if (spec.selfKind && typeof record.id === 'string' && record.id.length > 0) {
+    groups.add(syncGroup(spec.selfKind, record.id));
+  }
+  for (const parent of spec.parents) {
+    const value = record[parent.field];
+    if (value) groups.add(syncGroup(parent.kind, String(value)));
+  }
+  return [...groups];
+}
+
 /**
  * Narrow a client's requested sync-group set to the groups it is actually
  * allowed to subscribe to. This helper is fully generic — it never inspects the

package/src/schema/schema.ts

@@ -27,6 +27,7 @@ import { AbloValidationError } from '../errors.js';
 import type { IdentityRole } from './roles.js';
 import { fieldRef, type FieldRef } from './fieldRef.js';
 import { scopeSchema, grantsRefSchema } from './roles.js';
+import { subjectRuleSchema } from './subject.js';
 
 // Sync-group roles (identity and entity) are defined in `./roles.js` and
 // re-exported here so they can also be imported from this module. See
@@ -49,6 +50,9 @@ export {
   extractEntityIds,
   composeIdentitySyncGroups,
   composeEntitySyncGroups,
+  syncGroupsForRow,
+  InvalidRecordSubjectError,
+  type RecordSyncGroupSpec,
   intersectRequestedWithAllowed,
   syncGroup,
   identityAnchor,
@@ -150,6 +154,7 @@ export const RESERVED_SESSION_SETTINGS: readonly string[] = [
   'app.current_participant_id',
   'app.current_participant_kind',
   'app.current_user_id',
+  'app.current_subject_groups',
 ];
 
 export interface DefineSchemaOptions {
@@ -523,14 +528,34 @@ export type InsertValue<S extends Schema, ModelName extends keyof S['models']> =
 export type UpsertValue<S extends Schema, ModelName extends keyof S['models']> =
   InsertValue<S, ModelName>;
 
+/**
+ * A patch over a row's fields: send a field to change it, omit it to leave it,
+ * send `null` to CLEAR it.
+ *
+ * The third of those is why this is a mapped type rather than `Partial`.
+ * Omitting a field and clearing a field are different intentions that
+ * `Partial` spells the same way, because `undefined` is what an absent key
+ * already means: it is dropped from the payload, so a caller who wrote
+ * `{ assigneeId: undefined }` to unassign kept the old assignee, and the
+ * unassign, the un-project and the cleared due date all did nothing without
+ * erroring. `null` is the value that clears, so `null` is what the type has to
+ * accept — otherwise the only way to write a working clear is to cast the
+ * payload, and a cast is what people reached for.
+ *
+ * Only a field the schema lets be absent is clearable. A required field cannot
+ * be nulled, which is the same rule the column has.
+ */
+export type Clearable<T> = {
+  [K in keyof T]?: undefined extends T[K] ? T[K] | null : T[K];
+};
+
 /**
  * The value type for updating an existing row. `id` is required (identifies
- * the row to update); all other fields are optional (only provided fields
- * are changed).
+ * the row to update); every other field is a {@link Clearable} patch.
  */
 export type UpdateValue<S extends Schema, ModelName extends keyof S['models']> =
   S['models'][ModelName] extends ModelDef<infer Shape>
-    ? { id: string } & Partial<z.input<z.ZodObject<Shape>>>
+    ? { id: string } & Clearable<z.input<z.ZodObject<Shape>>>
     : never;
 
 /**
@@ -708,6 +733,7 @@ export function defineSchema<const S extends SchemaRecord>(
   }
 
   validateSyncGroupSchema(resolvedModels);
+  validateSubjectSchema(resolvedModels);
   validateSessionSettings(options?.sessionSettings ?? {});
 
   return {
@@ -721,6 +747,45 @@ export function defineSchema<const S extends SchemaRecord>(
   };
 }
 
+function validateSubjectSchema(models: Record<string, ModelDef>): void {
+  for (const [name, def] of Object.entries(models)) {
+    if (!def.subject) continue;
+    const parsed = subjectRuleSchema.safeParse(def.subject);
+    if (!parsed.success) {
+      throw new AbloValidationError(
+        `Model "${name}": subject must be { field, group } with valid identifiers.`,
+        { code: 'schema_definition_invalid', param: `${name}.subject` },
+      );
+    }
+    if (!(def.subject.field in def.fields)) {
+      throw new AbloValidationError(
+        `Model "${name}": subject.field "${def.subject.field}" is not a declared field on this model.`,
+        { code: 'schema_definition_invalid', param: `${name}.subject.field` },
+      );
+    }
+    const field = def.shape[def.subject.field];
+    const meta = def.fields[def.subject.field];
+    if (!field || !meta) {
+      throw new AbloValidationError(
+        `Model "${name}": subject.field "${def.subject.field}" is not a declared field on this model.`,
+        { code: 'schema_definition_invalid', param: `${name}.subject.field` },
+      );
+    }
+    const subjectField = field as z.ZodType;
+    const acceptsInvalidValue =
+      subjectField.safeParse('').success ||
+      subjectField.safeParse(null).success ||
+      subjectField.safeParse(undefined).success ||
+      subjectField.safeParse(1).success;
+    if (!['string', 'enum'].includes(meta.type) || meta.isOptional || acceptsInvalidValue) {
+      throw new AbloValidationError(
+        `Model "${name}": subject.field "${def.subject.field}" must be a required, non-empty string field.`,
+        { code: 'schema_definition_invalid', param: `${name}.subject.field` },
+      );
+    }
+  }
+}
+
 /**
  * Reject session-setting mappings that couldn't do what the author intends —
  * caught here at definition time rather than silently dropped on the write path.

package/src/schema/serialize.ts

@@ -13,7 +13,7 @@
  * What round-trips:
  *   - all model routing and scoping metadata: typename, tableName, load,
  *     mutable, the `tenancy` descriptor, bootstrap hints, scope, grants,
- *     entityRoles, the `conflict` disposition map, persist, autoFill,
+ *     entityRoles, the routing-only acknowledgement, the `conflict` disposition map, persist, autoFill,
  *     requiredFields, and lazyObservable. The authoring shorthands (`policy`
  *     and `groups`) are normalized into these canonical fields when the model
  *     is built, so only the canonical fields cross here.
@@ -33,6 +33,7 @@ import type { FieldMeta } from './field.js';
 import { buildFieldRefs } from './schema.js';
 import type { Tenancy } from './tenancy.js';
 import type { ModelResidency } from './residency.js';
+import type { SubjectRule } from './subject.js';
 import type {
   ModelDef,
   RelationRecord,
@@ -80,6 +81,7 @@ export interface ModelJSON {
   readonly typename: string;
   readonly tableName?: string;
   readonly tenancy: Tenancy;
+  readonly subject?: SubjectRule;
   /** The database plane the model's rows live in. Optional for backward
    *  compatibility: when absent (an artifact written before this field existed)
    *  it reads as `tenant`, the default. See {@link ModelResidency}. */
@@ -87,6 +89,7 @@ export interface ModelJSON {
   readonly scope?: boolean | string;
   readonly grants?: GrantsRef;
   readonly entityRoles?: readonly EntityRole[];
+  readonly routingOnly?: true;
   /** The declared write-conflict disposition per committer kind. When absent,
    *  the engine falls back to its default. */
   readonly conflict?: ConflictAxis;
@@ -136,10 +139,12 @@ function modelToJSON(def: ModelDef): ModelJSON {
     typename: def.typename ?? '',
     tableName: def.tableName,
     tenancy: def.tenancy,
+    subject: def.subject,
     plane: def.plane,
     scope: def.scope,
     grants: def.grants,
     entityRoles: def.entityRoles,
+    routingOnly: def.routingOnly,
     conflict: def.conflict,
     bootstrapLimit: def.bootstrapLimit,
     bootstrapOrderBy: def.bootstrapOrderBy,
@@ -272,12 +277,14 @@ function modelFromJSON(json: ModelJSON): ModelDef {
     persist: json.persist,
     tableName: json.tableName,
     tenancy: json.tenancy,
+    subject: json.subject,
     // Absent in older artifacts → default `tenant`, matching the model builder
     // and provisioning defaults so the round-trip stays stable.
     plane: json.plane ?? 'tenant',
     scope: json.scope,
     grants: json.grants,
     entityRoles: json.entityRoles,
+    routingOnly: json.routingOnly,
     // Absent in older artifacts → undefined, so the commit path falls through to
     // the function registry or the engine default.
     conflict: json.conflict,

package/src/schema/subject.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+
+/**
+ * Row/subject authorization for one model.
+ *
+ * A row is authorized exactly when the authenticated request carries the sync
+ * group `${group}:${row[field]}`. Both values are plain schema data so the rule
+ * survives serialization and can be compiled by every storage plane.
+ */
+export const subjectRuleSchema = z.strictObject({
+  field: z.string().regex(
+    /^[a-zA-Z_][a-zA-Z0-9_]*$/,
+    'subject.field must name a model field',
+  ),
+  group: z.string().regex(
+    /^[a-z][a-z0-9_]*$/,
+    'subject.group must be a lowercase identifier, e.g. "workspace"',
+  ),
+});
+
+export type SubjectRule = z.infer<typeof subjectRuleSchema>;
+
+/** The exact trusted group a row must match, or null for a malformed row. */
+export function subjectGroupForRow(
+  rule: SubjectRule,
+  row: Readonly<Record<string, unknown>>,
+): string | null {
+  const value = row[rule.field];
+  return typeof value === 'string' && value.length > 0
+    ? `${rule.group}:${value}`
+    : null;
+}
+
+/** Fail-closed row check shared by endpoint adapters and in-memory log folds. */
+export function subjectAuthorized(
+  rule: SubjectRule | undefined,
+  row: Readonly<Record<string, unknown>>,
+  groups: readonly string[] | null | undefined,
+): boolean {
+  if (!rule) return true;
+  const required = subjectGroupForRow(rule, row);
+  return required !== null && (groups ?? []).includes(required);
+}

package/src/server/adapter.ts

@@ -25,6 +25,7 @@ import type { ServerSyncDelta } from '../wire/delta.js';
 import type { BootstrapModel } from './readConfig.js';
 import type { CommitContext, CommitExecutionResult } from './commit.js';
 import type { StorageMode } from './storageMode.js';
+import type { SubjectRule } from '../schema/subject.js';
 
 /**
  * A canonical database row: one record, keyed by column name. The value type is
@@ -141,6 +142,7 @@ export type ReadRequest =
       readonly sourceModel?: string;
       /** `__typename` stamped on each returned row. */
       readonly typename: string;
+      readonly subject?: SubjectRule;
       readonly query: SourceListQuery;
       readonly scope?: SourceRequestContext;
       /** Runs the query against a hosted database: compile, take the tenant pool, apply row-level security, unpack the rows. */

package/src/server/readConfig.ts

@@ -19,6 +19,8 @@
  * Plain data, no database driver — it feeds the read side of the data adapter
  * contract, and your query builder reads it to load a model's initial rows.
  */
+import type { SubjectRule } from '../schema/subject.js';
+
 
 /** A mapping from a declared field to a physical column, with the alias to apply after a `SELECT *`. */
 export interface ColumnOverride {
@@ -88,6 +90,8 @@ export interface ReadModelShape {
   readonly orgColumn?: string;
   /** Parent-table scoping for rows with no tenancy column of their own. */
   readonly scopedVia?: ParentScope;
+  /** Credential-bound row authorization compiled by every read plane. */
+  readonly subject?: SubjectRule;
   /** Client-facing field name → physical DB column for declared fields. */
   readonly fieldColumns?: Readonly<Record<string, string>>;
   /** Physical-column aliases needed after SELECT * for `.from(...)` fields. */

package/src/source/adapters/drizzle.ts

@@ -58,6 +58,15 @@ import { toSchemaJSON } from '../../schema/serialize.js';
 import { camelToSnake, snakeToCamel } from '../../schema/ddl.js';
 import { tenancyColumn } from '../../schema/tenancy.js';
 import { ABLO_POSTGRES_COMMIT_ECHO_PREFIX } from '../types.js';
+import {
+  authorizeSourceChange,
+  authorizeSourceRead,
+  lockSourceSubjectCreates,
+  rethrowStrictCreateConflict,
+  sourceSyncGroups,
+  sourceSubjectRule,
+  sourceSubjectValues,
+} from '../subjectAuthorization.js';
 
 /** The subset of a Drizzle database/transaction handle the adapter calls. */
 export interface DrizzleLike {
@@ -214,11 +223,18 @@ export function drizzleDataSource<S extends SchemaRecord>(
       const table = sql.identifier(mc.table);
       if (req.kind === 'load') {
         const rows = rowsOf(await db.execute(sql`SELECT * FROM ${table} WHERE id = ${req.id} LIMIT 1`));
-        return rows.map((r) => toFields(mc, r));
+        return authorizeSourceRead(schema, req, rows.map((r) => toFields(mc, r)));
       }
       const limit = req.query?.limit ?? 1000;
-      const rows = rowsOf(await db.execute(sql`SELECT * FROM ${table} LIMIT ${limit}`));
-      return rows.map((r) => toFields(mc, r));
+      const rule = sourceSubjectRule(schema, req.model);
+      const subjects = sourceSubjectValues(rule, req.scope?.syncGroups);
+      if (subjects?.length === 0) return [];
+      const rows = rowsOf(await db.execute(subjects
+        ? sql`SELECT * FROM ${table}
+              WHERE ${sql.identifier(columnFor(mc, rule!.field))} = ANY(${subjects})
+              LIMIT ${limit}`
+        : sql`SELECT * FROM ${table} LIMIT ${limit}`));
+      return authorizeSourceRead(schema, req, rows.map((r) => toFields(mc, r)));
     },
 
     async commit(change: ChangeSet): Promise<AdapterCommitResult> {
@@ -238,19 +254,46 @@ export function drizzleDataSource<S extends SchemaRecord>(
           return { rows: cachedRow.response as Row[] };
         }
 
+        await lockSourceSubjectCreates(schema, change, async (_operation, key) => {
+          await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtextextended(${key}, 0))`);
+        });
+
+        await authorizeSourceChange(schema, change, async (operation) => {
+          if (!operation.id) return null;
+          const mc = modelColumns(operation.model);
+          const found = rowsOf(
+            await tx.execute(
+              sql`SELECT * FROM ${sql.identifier(mc.table)} WHERE id = ${operation.id} LIMIT 1 FOR UPDATE`,
+            ),
+          )[0];
+          return found ? toFields(mc, found) : 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));
+          const syncGroups = sourceSyncGroups(schema, op.model, row);
+          const syncGroupsSql = sql`ARRAY[${sql.join(
+            syncGroups.map((group) => sql`${group}`),
+            sql`, `,
+          )}]::text[]`;
           await tx.execute(sql`
             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 (
               ${`${change.correlationId}:${index}`}, ${op.model}, ${entityId}, ${op.type},
               ${op.type === 'DELETE' ? null : JSON.stringify(row)}::jsonb,
+              ${syncGroupsSql},
               ${change.correlationId}, ${op.transactionId ?? null}, ${Date.now()}
             )`);
         }
@@ -274,7 +317,7 @@ export function drizzleDataSource<S extends SchemaRecord>(
       const after = cursor ?? '0';
       const rows = rowsOf(
         await db.execute(sql`
-          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 > ${after} ORDER BY cursor ASC LIMIT ${limit}`),
       );
@@ -285,6 +328,7 @@ export function drizzleDataSource<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,