@abloatai/transaction 0.57.0 → 0.59.0

package/src/source/index.ts

@@ -56,16 +56,16 @@ export {
   type SourceSignatureOptions,
   type SourceSignatureVerificationOptions,
   type SourceSignatureVerificationResult,
-} from './signing.js';
+} from './endpoint/signing.js';
 
 export {
   dataSource,
   type DataSourceOptions,
-} from './factory.js';
+} from './endpoint/factory.js';
 
 export {
   sourceSubjectCreateLockKey,
-} from './subjectAuthorization.js';
+} from './adapters/subjectAuthorization.js';
 
 export {
   createPushQueue,
@@ -75,7 +75,7 @@ export {
   type PushQueueItem,
   type PushQueueOptions,
   type PushQueueStorage,
-} from './pushQueue.js';
+} from './delivery/pushQueue.js';
 
 // The reverse-channel connector — an outbound transport for the load, list, and
 // commit leg, and the dial-out counterpart to `createPushQueue`. It lets you serve
@@ -84,14 +84,16 @@ export {
 export {
   createSourceConnector,
   DEFAULT_RECONNECT_SCHEDULE,
+  SourceConnectorSupersededError,
   type SourceConnector,
   type SourceConnectorOptions,
   type ConnectorWebSocket,
   type ConnectorWebSocketFactory,
   type ConnectorStatus,
-} from './connector.js';
+} from './connector/client.js';
 export {
   SOURCE_CONNECTOR_PROTOCOL_VERSION,
+  SOURCE_CONNECTOR_SUPERSEDED_CLOSE_CODE,
   SOURCE_CONNECTOR_WS_PATH,
   WS_SOURCE_SUBPROTOCOL,
   sourceConnectorSubprotocols,
@@ -105,7 +107,7 @@ export {
   type RequestFrame,
   type ResponseFrame,
   type ErrorFrame,
-} from './connectorProtocol.js';
+} from './connector/protocol.js';
 
 // The Data Source adapter interface and its Zod contract, with per-ORM implementations.
 export {
@@ -114,7 +116,7 @@ export {
   type AdapterReadRequest,
   type AdapterCommitResult,
   type Row as AdapterRow,
-} from './adapter.js';
+} from './adapters/adapter.js';
 export {
   adapterBindingSchema,
   databaseAdapterProfileSchema,
@@ -127,8 +129,8 @@ export {
   type DatabaseKind,
   type ObservationProfile,
   type PostgresBinding,
-} from './adapterProfile.js';
-export { defineDatabaseAdapter } from './adapterFactory.js';
+} from './adapters/adapterProfile.js';
+export { defineDatabaseAdapter } from './adapters/adapterFactory.js';
 export {
   operationSchema,
   operationTypeSchema,
@@ -137,25 +139,26 @@ export {
   sourceCommitEchoMarkerSchema,
   sourceCommitEchoIntentSchema,
   changeSetSchema,
-  outboxEventSchema,
-  eventsPageSchema,
-  migrationSchema,
   adapterCapabilitiesSchema,
   type Operation,
   type ChangeSet,
-  type OutboxEvent,
-  type EventsPage,
-  type Migration,
   type AdapterCapabilities,
   type SourceCommitEchoMarkerWire,
   type SourceCommitEchoIntent,
-} from './contract.js';
+} from './adapters/contract.js';
+export { migrationSchema, type Migration } from './adapters/migration.js';
+export {
+  endpointOutboxMigrations,
+  eventsPageSchema,
+  outboxEventSchema,
+  type EventsPage,
+  type OutboxEvent,
+} from './outbox/index.js';
 export { prismaDataSource, type PrismaLike, type PrismaDataSourceOptions } from './adapters/prisma.js';
 export {
   adapterTableMigrations,
-  endpointOutboxMigrations,
   idempotencyLedgerMigrations,
-} from './migrations.js';
+} from './adapters/migrations.js';
 export {
   createKyselyMutationAdapter,
   createKyselyMutationCore,
@@ -183,7 +186,7 @@ export {
   encodeSourceEchoTransactionId,
   decodeSourceEchoTransactionId,
   type SourceEchoTransactionId,
-} from './idempotency.js';
+} from './adapters/idempotency.js';
 // What Ablo leaves inside a customer's database, declared once — read by the
 // setup SQL, the replication runtime, and the audit that reports it back.
 export {

package/src/source/outbox/contract.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { commitOperationTypeSchema } from '../../coordination/schema.js';
+import { correlationIdSchema } from '../../commit/contract.js';
+import { ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH } from '../types.js';
+
+const jsonObject = z.record(z.string(), z.unknown());
+
+/** The immutable, versioned event envelope stored in `ablo_outbox`. */
+export const outboxEventSchema = z.object({
+  /** Version 1 predates durable routes; version 2 captures them atomically. */
+  version: z.union([z.literal(1), z.literal(2)]),
+  /** Stable, globally unique replay-protection identity. */
+  id: z.string().min(1),
+  model: z.string().min(1),
+  entityId: z.string().min(1),
+  type: commitOperationTypeSchema,
+  /** Declared schema-field names, never physical database column names. */
+  data: jsonObject.nullish(),
+  /** Exact routes captured in the writing transaction; version 2 requires them. */
+  syncGroups: z.array(z.string().min(1)).readonly().optional(),
+  organizationId: z.string().nullish(),
+  clientTxId: z.string().nullish(),
+  correlationId: correlationIdSchema.nullish(),
+  transactionId: z
+    .string()
+    .min(1)
+    .max(ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH)
+    .nullish(),
+  occurredAt: z.number().nullish(),
+  /** Monotonic database position, represented as a string to preserve bigint. */
+  cursor: z.string().min(1),
+}).superRefine((event, ctx) => {
+  if (event.version === 1 && event.syncGroups !== undefined) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['syncGroups'],
+      message: 'Outbox event version 1 cannot carry syncGroups',
+    });
+  }
+  if (event.version === 2 && event.syncGroups === undefined) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['syncGroups'],
+      message: 'Outbox event version 2 requires durable syncGroups',
+    });
+  }
+});
+
+export type OutboxEvent = z.infer<typeof outboxEventSchema>;
+
+export const eventsPageSchema = z.object({
+  events: z.array(outboxEventSchema),
+  nextCursor: z.string().nullable(),
+});
+
+export type EventsPage = z.infer<typeof eventsPageSchema>;

package/src/source/outbox/envelope.ts

@@ -0,0 +1,47 @@
+import { AbloValidationError } from '../../errors.js';
+import { outboxEventSchema, type OutboxEvent } from './contract.js';
+
+/** Decode the versioned routing envelope without turning absence into `[]`. */
+export function decodeOutboxEventEnvelope(
+  eventVersion: unknown,
+  syncGroups: unknown,
+  cursor: unknown,
+): { readonly version: 1 | 2; readonly syncGroups?: readonly string[] } {
+  const version = eventVersion == null
+    ? (Array.isArray(syncGroups) ? 2 : 1)
+    : Number(eventVersion);
+  if (version !== 1 && version !== 2) {
+    throw new AbloValidationError(
+      `Endpoint outbox event at cursor ${String(cursor)} has unsupported event version ${String(eventVersion)}.`,
+      { code: 'source_event_invalid' },
+    );
+  }
+  if (version === 2 && !Array.isArray(syncGroups)) {
+    throw new AbloValidationError(
+      `Endpoint outbox event at cursor ${String(cursor)} is version 2 but has no durable sync_groups.`,
+      { code: 'source_event_invalid' },
+    );
+  }
+  return version === 2
+    ? { version, syncGroups: syncGroups as readonly string[] }
+    : { version };
+}
+
+/** Canonical snake_case database row → versioned source event decoder. */
+export function decodeDatabaseOutboxEvent(row: Readonly<Record<string, unknown>>): OutboxEvent {
+  const envelope = decodeOutboxEventEnvelope(row.event_version, row.sync_groups, row.cursor);
+  return outboxEventSchema.parse({
+    ...envelope,
+    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),
+  });
+}

package/src/source/outbox/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Endpoint transactional-outbox subsystem.
+ *
+ * Start here, then descend into contract, envelope, migrations, or retention.
+ * ORM adapters depend on this boundary; the subsystem never depends on them.
+ */
+export {
+  outboxEventSchema,
+  eventsPageSchema,
+  type OutboxEvent,
+  type EventsPage,
+} from './contract.js';
+export { decodeDatabaseOutboxEvent, decodeOutboxEventEnvelope } from './envelope.js';
+export { endpointOutboxMigrations } from './migrations.js';
+export { ENDPOINT_OUTBOX_PRUNE_BATCH_SIZE } from './retention.js';

package/src/source/outbox/migrations.ts

@@ -0,0 +1,71 @@
+import type { Migration } from '../adapters/migration.js';
+
+function quoteIdent(value: string): string {
+  return `"${value.replace(/"/g, '""')}"`;
+}
+
+function quoteLiteral(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+
+function qualified(schema: string, relation: string): string {
+  return `${quoteIdent(schema)}.${quoteIdent(relation)}`;
+}
+
+/** Schema for the endpoint-only, versioned transactional outbox. */
+export function endpointOutboxMigrations(schema = 'public'): readonly Migration[] {
+  const outbox = qualified(schema, 'ablo_outbox');
+  return [
+    {
+      name: 'ablo_outbox',
+      up: `CREATE TABLE IF NOT EXISTS ${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,
+  event_version    SMALLINT NOT NULL DEFAULT 1,
+  sync_groups      TEXT[],
+  organization_id TEXT,
+  client_tx_id    TEXT,
+  correlation_id  TEXT,
+  transaction_id  TEXT,
+  occurred_at     BIGINT,
+  created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT ablo_outbox_event_envelope_valid CHECK (
+    (event_version = 1 AND sync_groups IS NULL) OR
+    (event_version = 2 AND sync_groups IS NOT NULL)
+  )
+);`,
+    },
+    {
+      name: 'ablo_outbox_add_correlation',
+      up: `ALTER TABLE ${outbox}
+  ADD COLUMN IF NOT EXISTS correlation_id TEXT;
+ALTER TABLE ${outbox}
+  ADD COLUMN IF NOT EXISTS transaction_id TEXT;`,
+    },
+    {
+      name: 'ablo_outbox_add_event_version_and_sync_groups',
+      up: `ALTER TABLE ${outbox}
+  ADD COLUMN IF NOT EXISTS event_version SMALLINT NOT NULL DEFAULT 1;
+ALTER TABLE ${outbox}
+  ADD COLUMN IF NOT EXISTS sync_groups TEXT[];
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+     WHERE conrelid = to_regclass(${quoteLiteral(outbox)})
+       AND conname = 'ablo_outbox_event_envelope_valid'
+  ) THEN
+    ALTER TABLE ${outbox}
+      ADD CONSTRAINT ablo_outbox_event_envelope_valid CHECK (
+        (event_version = 1 AND sync_groups IS NULL) OR
+        (event_version = 2 AND sync_groups IS NOT NULL)
+      ) NOT VALID;
+  END IF;
+END $$;`,
+    },
+  ];
+}

package/src/source/outbox/retention.ts

@@ -0,0 +1,2 @@
+/** Bounds acknowledgement cleanup when an installation retained a large history. */
+export const ENDPOINT_OUTBOX_PRUNE_BATCH_SIZE = 1_000;

package/src/source/types.ts

@@ -11,7 +11,7 @@
  */
 
 import { AbloValidationError } from '../errors.js';
-import type { CommitOperationType, OnStaleMode } from '../coordination/schema.js';
+import type { CommitOperationType } from '../coordination/schema.js';
 import type { ParticipantKind } from '../types/participant.js';
 
 /** A scalar value that can appear in a source filter. */
@@ -93,21 +93,13 @@ export interface SourceRequestContext {
   /** Trusted project selected by the authenticating credential. */
   readonly projectId?: string;
   readonly syncGroups?: readonly string[];
-  /**
-   * @deprecated Renamed to {@link SourceRequestContext.syncGroups}. Removed in
-   * 0.58.0. Ablo populates both spellings with the same value for this release,
-   * so an adapter still reading this one gets the groups rather than
-   * `undefined`, which on a routing field would read as "no groups" rather than
-   * as a missing field.
-   */
-  readonly requiredSyncGroups?: readonly string[];
 }
 
 /**
  * A single change Ablo asks your source to apply — a create, update, delete,
  * archive, or unarchive of one row of `model`. Operations arrive in your
- * `commit` handler through {@link SourceCommitParams}. `onStale` says what to
- * do when the row changed since it was read at `readAt`.
+ * `commit` handler through {@link SourceCommitParams}. A `readAt` makes the
+ * operation conditional and a stale value rejects it.
  */
 export interface SourceOperation {
   readonly type: CommitOperationType;
@@ -117,7 +109,6 @@ export interface SourceOperation {
   readonly where?: Record<string, unknown> | null;
   readonly transactionId?: string | null;
   readonly readAt?: number | null;
-  readonly onStale?: OnStaleMode | null;
 }
 
 /**
@@ -148,6 +139,8 @@ export interface SourceDelta {
  * the event is durably appended. External writes omit them.
  */
 export interface SourceEvent {
+  /** Event envelope version. When omitted, syncGroups implies v2; their absence implies v1. */
+  readonly version?: 1 | 2;
   /**
    * A globally unique event id from your outbox. Ablo uses it for replay
    * protection, so re-delivering the same id is a no-op.
@@ -173,8 +166,8 @@ export interface SourceEvent {
    * a tenant boundary.
    */
   readonly data?: Record<string, unknown> | null;
-  /** Exact record routes captured while the changed row was transactionally visible. */
-  readonly syncGroups: readonly string[];
+  /** Exact record routes captured while the changed row was transactionally visible. Required in version 2. */
+  readonly syncGroups?: readonly string[];
   /**
    * The tenant this event belongs to. Populate it from the row's organization
    * column for multi-tenant data; a single-tenant source may omit it and let
@@ -253,6 +246,7 @@ export function sourceEventForOperation(
   const occurredAt = normalizeEventOccurredAt(options.occurredAt);
   const transactionId = options.transactionId ?? options.operation.transactionId ?? undefined;
   return {
+    version: 2,
     id: options.eventId,
     model: options.operation.model,
     entityId,
@@ -381,11 +375,14 @@ export interface SourceEventsResult {
  */
 export type SourceEventsHandler<TAuth = unknown> = (params: {
   /**
-   * The cursor from a previous `events` call, or undefined on the first poll of
-   * a newly connected source. You decide what it encodes — a last event id, a
-   * timestamp, a log sequence number.
+   * The consumer position Ablo has durably committed, or undefined on the first
+   * poll of a newly connected source. It acknowledges every event through that
+   * position, so a handler may prune them before returning the next page. You
+   * decide what it encodes — a last event id, timestamp, or log sequence number.
    */
   readonly cursor?: string;
+  /** Explicit durable acknowledgement. Safe to use for bounded retention cleanup. */
+  readonly acknowledgedThrough?: string;
   /**
    * A suggested upper bound on how many events to return. You may return fewer;
    * returning many more risks tripping Ablo's per-poll cap.
@@ -539,7 +536,10 @@ export interface SourceCommitRequest {
 
 export interface SourceEventsRequest {
   readonly type: 'events';
+  /** Exclusive read position. */
   readonly cursor?: string;
+  /** Durable consumer acknowledgement, independent of the read position. */
+  readonly acknowledgedThrough?: string;
   readonly limit?: number;
   readonly scope?: SourceRequestContext;
 }

package/src/syncLog/contract.ts

@@ -15,8 +15,10 @@
  * | `current_settled_sync_id()`        | nothing at or below is still in flight    |
  * | `getCommittedSyncId`               | committed, without waiting for the barrier|
  * | `sync_broadcast_cursors.published_through` | the fan-out published through     |
- * | `Client.lastSentSyncId`            | this recipient was offered through        |
- * | `Client.lastAckedSyncId`           | this recipient confirmed through          |
+ * | `log_subscriptions.position`       | this participant was served through, in
+ *                                        the area the same row names            |
+ * | `Client.lastSentSyncId`            | this socket was offered through           |
+ * | `Client.lastAckedSyncId`           | this socket confirmed through             |
  * | `LogPosition.applied`              | the client processed on arrival through   |
  * | `LogPosition.persisted`            | the client durably holds through, in
  *                                        DELIVERED order, not numeric order       |
@@ -36,6 +38,21 @@
  * own head, re-taking the plane lock on every catch-up poll
  * (docs/plans/delivery-verify-at-read.md). Before comparing two positions, say
  * out loud which owner each belongs to.
+ *
+ * ## The owner is a relation, not just a name
+ *
+ * This doc did its job on the NUMBER and could not do it for the relation that
+ * holds one. `log_subscriptions.position` is the durable answer to "where is
+ * this participant, in this area" (ADR 0036) — one record per
+ * `(participant, area)`, with no connection axis, from which delivery and
+ * liveness are projected. The two `Client` fields above are deliberately NOT
+ * folded into it: they are an in-flight socket's frame accounting, which is why
+ * they name a socket rather than a participant.
+ *
+ * The rest of the table is ENGINE-owned and stays separate on purpose. The
+ * fan-out's progress, the compaction checkpoint and the settled head answer a
+ * different question from "where is this participant", and collapsing them
+ * would recreate the exact comparison this doc warns about.
  */
 
 import { z } from 'zod';

package/src/transport/{credentialLifecycle.ts → connection/credentialLifecycle.ts}

@@ -7,14 +7,14 @@
  * so the two can reference each other without an import cycle.
  */
 
-import type { RecoveryClass } from '../errorCodes.js';
-import { noopLogger, type Logger } from '../logger.js';
+import type { RecoveryClass } from '../../errorCodes.js';
+import { noopLogger, type Logger } from '../../logger.js';
 import {
   credentialExpiry,
   credentialToken,
   type CredentialProvider,
   type CredentialProviderResult,
-} from '../auth/credentialResult.js';
+} from '../../auth/credentialResult.js';
 
 /**
  * Tri-state outcome of a credential re-mint, mirroring the `getToken`

package/src/transport/connection/index.ts

@@ -0,0 +1,4 @@
+/** Shared connection lifecycle boundary. */
+export * from './manager.js';
+export * from './credentialLifecycle.js';
+export * from './networkProbe.js';

package/src/transport/{connectionManager.ts → connection/manager.ts}

@@ -41,13 +41,13 @@
  */
 
 import { probeNetwork, type ProbeResult } from './networkProbe.js';
-import type { AuthTokenGetter } from '../auth/credentialSource.js';
+import type { AuthTokenGetter } from '../../auth/credentialSource.js';
 import type { CredentialRefreshOutcome } from './credentialLifecycle.js';
-import { noopLogger, type Logger } from '../logger.js';
+import { noopLogger, type Logger } from '../../logger.js';
 import {
   noopSocketObservability,
   type TransportObservability,
-} from '../observability.js';
+} from '../../observability.js';
 
 // ─── State ────────────────────────────────────────────────────────────────
 
@@ -134,6 +134,13 @@ export interface ConnectionManagerOptions {
   getAuthToken?: AuthTokenGetter;
   /** Override retry ceilings / jitter. Production should leave defaults. */
   backoff?: Partial<typeof DEFAULT_BACKOFF>;
+  /**
+   * Connectivity probe. Defaults to {@link probeNetwork}. Declared so a caller
+   * can drive recovery from a deterministic outcome: `probeNetwork` is a
+   * sibling inside this module, so a test cannot reach it through the
+   * package's `transport/connection` boundary to substitute one.
+   */
+  probe?: typeof probeNetwork;
   /** Where transitions are logged. Defaults to silent. */
   logger?: Logger;
   /** Where dead-end states are reported. Defaults to silent. */
@@ -179,6 +186,7 @@ export class ConnectionManager {
   private readonly baseUrl?: string;
   private readonly getAuthToken?: AuthTokenGetter;
   private readonly backoff: typeof DEFAULT_BACKOFF;
+  private readonly probe: typeof probeNetwork;
   private readonly logger: Logger;
   private readonly observability: TransportObservability;
 
@@ -190,6 +198,7 @@ export class ConnectionManager {
     this.baseUrl = options.baseUrl;
     this.getAuthToken = options.getAuthToken;
     this.backoff = { ...DEFAULT_BACKOFF, ...(options.backoff ?? {}) };
+    this.probe = options.probe ?? probeNetwork;
     this.logger = options.logger ?? noopLogger;
     this.observability = options.observability ?? noopSocketObservability;
   }
@@ -539,7 +548,7 @@ export class ConnectionManager {
 
   private async runProbe(): Promise<void> {
     try {
-      const result = await probeNetwork({
+      const result = await this.probe({
         baseUrl: this.baseUrl,
         getAuthToken: this.getAuthToken,
         logger: this.logger,

package/src/transport/{networkProbe.ts → connection/networkProbe.ts}

@@ -23,10 +23,10 @@
  */
 
 import { z } from 'zod';
-import { classifyRecovery } from '../errors.js';
-import { withAuthHeaders, type AuthTokenGetter } from '../auth/credentialSource.js';
-import { ABLO_DEFAULT_BASE_URL } from '../auth/hostedEndpoints.js';
-import { noopLogger, type Logger } from '../logger.js';
+import { classifyRecovery } from '../../errors.js';
+import { withAuthHeaders, type AuthTokenGetter } from '../../auth/credentialSource.js';
+import { ABLO_DEFAULT_BASE_URL } from '../../auth/hostedEndpoints.js';
+import { noopLogger, type Logger } from '../../logger.js';
 
 /**
  * The complete set of probe outcomes. Each value carries both reachability and