@abloatai/transaction 0.57.0 → 0.59.0

package/src/source/adapters/kysely.ts

@@ -24,27 +24,27 @@ 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,
@@ -52,7 +52,12 @@ import {
   lockSourceSubjectCreates,
   rethrowStrictCreateConflict,
   sourceSyncGroups,
-} from '../subjectAuthorization.js';
+} from './subjectAuthorization.js';
+import {
+  decodeDatabaseOutboxEvent,
+  ENDPOINT_OUTBOX_PRUNE_BATCH_SIZE,
+  type EventsPage,
+} from '../outbox/index.js';
 import {
   createKyselyMutationCore,
   kyselyOperationRowId,
@@ -403,6 +408,7 @@ 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)
                   : [],
@@ -449,6 +455,22 @@ export function kyselyDataSource<S extends SchemaRecord>(
     ...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')
@@ -457,22 +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,
-          syncGroups: row.sync_groups ?? [],
-          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 };
     },
   });

package/src/source/adapters/kyselyMutationCore.ts

@@ -13,9 +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 { sourceSubjectRule, sourceSubjectValues } from '../subjectAuthorization.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 {

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,6 +139,7 @@ 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)),
@@ -144,13 +148,25 @@ export function memoryDataSource(): DataSourceAdapter {
           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,58 +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,
-  sync_groups      TEXT[] NOT NULL,
-  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;`,
-    },
-    {
-      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;`,
-    },
-  ];
-}
-
 /** 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,18 +20,19 @@ 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';
@@ -48,7 +49,11 @@ import {
   sourceSyncGroups,
   sourceSubjectRule,
   sourceSubjectValues,
-} from '../subjectAuthorization.js';
+} 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 {
@@ -280,9 +285,9 @@ export function prismaDataSource<S extends SchemaRecord>(
           // Transactional outbox: one event per operation, written in this same transaction.
           await tx.$executeRawUnsafe(
             `INSERT INTO ablo_outbox (
-               id, model, entity_id, type, data, sync_groups,
+               id, model, entity_id, type, data, event_version, sync_groups,
                correlation_id, transaction_id, occurred_at
-             ) VALUES ($1, $2, $3, $4, $5::jsonb, $6::text[], $7, $8, $9)`,
+             ) VALUES ($1, $2, $3, $4, $5::jsonb, 2, $6::text[], $7, $8, $9)`,
             `${change.correlationId}:${index}`,
             op.model,
             entityId,
@@ -319,35 +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, sync_groups, 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,
-          syncGroups: r.sync_groups ?? [],
-          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 };
     },
   });
 }

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

@@ -1,4 +1,4 @@
-import { AbloPermissionError, AbloValidationError } from '../errors.js';
+import { AbloPermissionError, AbloValidationError } from '../../errors.js';
 import {
   composeEntitySyncGroups,
   syncGroupsForRow,
@@ -8,7 +8,7 @@ import {
   type Schema,
   type SchemaRecord,
   type SubjectRule,
-} from '../schema/index.js';
+} from '../../schema/index.js';
 import type { AdapterReadRequest, Row } from './adapter.js';
 import type { ChangeSet, Operation } from './contract.js';
 

package/src/source/{connector.ts → connector/client.ts}

@@ -26,6 +26,7 @@
 
 import {
   SOURCE_CONNECTOR_PROTOCOL_VERSION,
+  SOURCE_CONNECTOR_SUPERSEDED_CLOSE_CODE,
   SOURCE_CONNECTOR_WS_PATH,
   sourceConnectorSubprotocols,
   encodeFrame,
@@ -35,8 +36,8 @@ import {
   type RequestFrame,
   type ResponseFrame,
   type ReadyFrame,
-} from './connectorProtocol.js';
-import { ABLO_HOSTED_HTTP_BASE_URL } from '../auth/hostedEndpoints.js';
+} from './protocol.js';
+import { ABLO_HOSTED_HTTP_BASE_URL } from '../../auth/hostedEndpoints.js';
 
 /**
  * The default Ablo base URL the connector dials, to which it appends
@@ -130,6 +131,20 @@ export interface SourceConnector {
   run(signal: AbortSignal): Promise<void>;
 }
 
+/** The connector lost its source lease to a newer process and will not reconnect. */
+export class SourceConnectorSupersededError extends Error {
+  readonly code = 'source_connector_superseded';
+
+  constructor() {
+    super(
+      'A newer local connector took ownership of this source; this connector has stopped.',
+    );
+    this.name = 'SourceConnectorSupersededError';
+  }
+}
+
+type ConnectionOutcome = 'retry' | 'ready' | 'superseded';
+
 export function createSourceConnector(
   options: SourceConnectorOptions,
 ): SourceConnector {
@@ -148,7 +163,7 @@ export function createSourceConnector(
         if (signal.aborted) return;
 
         options.onStatus?.('connecting');
-        const becameReady = await connectOnce({
+        const outcome = await connectOnce({
           url,
           apiKey: options.apiKey,
           handler: options.handler,
@@ -158,9 +173,10 @@ export function createSourceConnector(
           onError: options.onError,
           signal,
         });
+        if (outcome === 'superseded') return;
         // A connection that reached `ready` resets the backoff so the next
         // drop reconnects immediately; one that never readied keeps escalating.
-        attempt = becameReady ? 0 : attempt + 1;
+        attempt = outcome === 'ready' ? 0 : attempt + 1;
       }
     },
   };
@@ -169,8 +185,10 @@ export function createSourceConnector(
 /**
  * Runs one connection: open the socket, register, then serve requests until the
  * socket closes or `signal` aborts. Resolves to whether the connection reached the
- * `ready` state, which the caller uses to reset the reconnect backoff. It never
- * rejects, because a dropped transport is expected and simply drives a reconnect.
+ * `ready` state, which the caller uses to reset the reconnect backoff, or the
+ * terminal `superseded` fence, which stops this process from taking ownership
+ * back from its replacement. It never rejects because ordinary transport drops
+ * are expected and simply drive a reconnect.
  */
 function connectOnce(params: {
   readonly url: string;
@@ -181,8 +199,8 @@ function connectOnce(params: {
   readonly onStatus: ((status: ConnectorStatus) => void) | undefined;
   readonly onError: ((error: unknown) => void) | undefined;
   readonly signal: AbortSignal;
-}): Promise<boolean> {
-  return new Promise<boolean>((resolve) => {
+}): Promise<ConnectionOutcome> {
+  return new Promise<ConnectionOutcome>((resolve) => {
     let ws: ConnectorWebSocket;
     try {
       ws = params.factory(
@@ -191,18 +209,18 @@ function connectOnce(params: {
       );
     } catch (err) {
       params.onError?.(err);
-      resolve(false);
+      resolve('retry');
       return;
     }
 
     let ready = false;
     let settled = false;
-    const finish = (): void => {
+    const finish = (outcome: ConnectionOutcome = ready ? 'ready' : 'retry'): void => {
       if (settled) return;
       settled = true;
       params.signal.removeEventListener('abort', onAbort);
       params.onStatus?.('disconnected');
-      resolve(ready);
+      resolve(outcome);
     };
 
     const onAbort = (): void => {
@@ -243,7 +261,12 @@ function connectOnce(params: {
       // `close` always follows `error`; finish() runs there.
     });
 
-    ws.addEventListener('close', () => {
+    ws.addEventListener('close', (event) => {
+      if (event.code === SOURCE_CONNECTOR_SUPERSEDED_CLOSE_CODE) {
+        params.onError?.(new SourceConnectorSupersededError());
+        finish('superseded');
+        return;
+      }
       finish();
     });
 

package/src/source/connector/index.ts

@@ -0,0 +1,3 @@
+/** Outbound Data Source connector boundary: client runtime and wire protocol. */
+export * from './client.js';
+export * from './protocol.js';

package/src/source/{connectorProtocol.ts → connector/protocol.ts}

@@ -22,8 +22,8 @@
 
 import { z } from 'zod';
 
-import { environmentSchema } from '../environment.js';
-import { WS_BEARER_SUBPROTOCOL_PREFIX } from '../auth/credentialSource.js';
+import { environmentSchema } from '../../environment.js';
+import { WS_BEARER_SUBPROTOCOL_PREFIX } from '../../auth/credentialSource.js';
 
 /**
  * The wire-protocol version. It increases on any breaking change to a frame's
@@ -43,6 +43,14 @@ export const SOURCE_CONNECTOR_WS_PATH = '/v1/source/listen';
  */
 export const WS_SOURCE_SUBPROTOCOL = 'ablo.source.v1';
 
+/**
+ * Private WebSocket close code used when a newer connector takes ownership of
+ * the same source. This is a fencing decision, not a transient disconnect: the
+ * superseded process must stop reconnecting or two `ablo dev --local`
+ * processes will continuously replace each other.
+ */
+export const SOURCE_CONNECTOR_SUPERSEDED_CLOSE_CODE = 4009;
+
 /**
  * Builds the `Sec-WebSocket-Protocol` list a connector offers during the
  * handshake: the source subprotocol followed by the bearer credential, encoded as

package/src/source/delivery/index.ts

@@ -0,0 +1,2 @@
+/** Data Source push-delivery boundary. */
+export * from './pushQueue.js';

package/src/source/{pushQueue.ts → delivery/pushQueue.ts}

@@ -23,8 +23,8 @@
  * interface against your own outbox table for production durability.
  */
 
-import { ABLO_SOURCE_HEADERS, signAbloSourceRequest } from './signing.js';
-import type { SourceEvent } from './types.js';
+import { ABLO_SOURCE_HEADERS, signAbloSourceRequest } from '../endpoint/signing.js';
+import type { SourceEvent } from '../types.js';
 
 /** One queued delivery: a batch of source events plus its retry bookkeeping. */
 export interface PushQueueItem {

package/src/source/{factory.ts → endpoint/factory.ts}

@@ -10,18 +10,18 @@ import type {
   Schema,
   SchemaRecord,
   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';
+} from '../../schema/schema.js';
+import type { DataSourceAdapter } from '../adapters/adapter.js';
+import type { AdapterReadRequest, Row } from '../adapters/adapter.js';
+import { changeSetSchema } from '../adapters/contract.js';
+import { AbloError, AbloPermissionError } from '../../errors.js';
 import {
   authorizeSourceChange,
   authorizeSourceRead,
   lockSourceSubjectCreates,
   sourceSubjectRule,
   sourceSubjectValues,
-} from './subjectAuthorization.js';
+} from '../adapters/subjectAuthorization.js';
 import {
   SourceSignatureError,
   verifyAbloSourceRequest,
@@ -41,7 +41,7 @@ import type {
   SourceRequestContext,
   SourceScope,
   SourceSubjectTransactionHandler,
-} from './types.js';
+} from '../types.js';
 
 type SourceModels<S extends SchemaRecord, TAuth> = Partial<{
   readonly [K in keyof S & string]: SourceModelHandlers<
@@ -204,15 +204,19 @@ async function handleViaAdapter(
   }
 
   if (body.type === 'events') {
+    if (body.acknowledgedThrough) {
+      await adapter.acknowledgeEvents(body.acknowledgedThrough);
+    }
     const page = await adapter.events(body.cursor ?? null, body.limit ?? 100);
     return json({
       events: page.events.map((event) => ({
         id: event.id,
+        version: event.version,
         model: event.model,
         entityId: event.entityId,
         type: event.type,
         ...(event.data !== undefined && event.data !== null ? { data: event.data } : {}),
-        syncGroups: event.syncGroups,
+        ...(event.syncGroups ? { syncGroups: event.syncGroups } : {}),
         ...(event.organizationId ? { organizationId: event.organizationId } : {}),
         ...(event.clientTxId ? { clientTxId: event.clientTxId } : {}),
         ...(event.correlationId ? { correlationId: event.correlationId } : {}),
@@ -564,6 +568,7 @@ export function dataSource<const S extends SchemaRecord, TAuth = unknown>(
       }
       const result = await options.events({
         cursor: body.cursor,
+        acknowledgedThrough: body.acknowledgedThrough,
         limit: body.limit,
         context,
       });

package/src/source/endpoint/index.ts

@@ -0,0 +1,4 @@
+/** Signed Data Source endpoint boundary: factory, signing, and framework adapter. */
+export * from './factory.js';
+export * from './signing.js';
+export * from './next.js';

package/src/source/{next.ts → endpoint/next.ts}

@@ -5,7 +5,7 @@
  * `POST` so your route file can export it in one line.
  *
  *   // app/api/ablo/source/route.ts
- *   import { dataSourceNext } from '@abloatai/transaction/source/next';
+ *   import { dataSourceNext } from '@abloatai/transaction/source/endpoint';
  *   import { prismaDataSource } from '@abloatai/transaction/source';
  *   import { schema } from '@/ablo/schema';
  *   import { prisma } from '@/lib/prisma';
@@ -20,7 +20,7 @@
  * directly and export its result however that framework expects.
  */
 
-import type { SchemaRecord } from '../schema/schema.js';
+import type { SchemaRecord } from '../../schema/schema.js';
 import { dataSource, type DataSourceOptions } from './factory.js';
 
 /**

package/src/source/{signing.ts → endpoint/signing.ts}

@@ -1,5 +1,5 @@
 /**
- * Canonically signs and verifies source requests using the Standard Webhooks scheme.
+ * Canonically signs and verifies source endpoint requests using the Standard Webhooks scheme.
  *
  * Every request Ablo sends to a data source is signed with that source's API
  * key, and the receiving endpoint verifies the signature before any handler