@abloatai/transaction 0.57.0 → 0.58.0

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