@abloatai/transaction 0.37.0

package/src/source/index.ts

@@ -0,0 +1,182 @@
+/**
+ * The entry point for the Data Source API, re-exporting the pieces you need from
+ * their individual modules:
+ *
+ *   - `types.ts`   — the shared wire and handler types, plus `sourceEventForOperation`
+ *   - `signing.ts` — request signing and verification
+ *   - `factory.ts` — the `dataSource()` endpoint factory
+ *
+ * Import from here; the sibling modules import one another directly.
+ */
+
+export {
+  sourceEventForOperation,
+  ABLO_POSTGRES_COMMIT_ECHO_PREFIX,
+  ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH,
+  ABLO_SOURCE_ECHO_MAX_OPERATIONS,
+  ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES,
+  type SourcePrimitive,
+  type SourceWhere,
+  type SourceListQuery,
+  type SourceListPage,
+  type SourceListResult,
+  type SourceRequestContext,
+  type SourceOperation,
+  type SourceDelta,
+  type SourceEvent,
+  type SourceEventForOperationOptions,
+  type SourceCommitResult,
+  type SourceCommitEcho,
+  type SourceCommitEchoOperation,
+  type SourceCommitEchoMarker,
+  type SourceCommitParams,
+  type SourceScope,
+  type SourceEventsResult,
+  type SourceEventsHandler,
+  type SourceAuthorizeContext,
+  type SourceHandlerContext,
+  type SourceModelHandlers,
+  type SourceCommitHandler,
+  type SourceApiKey,
+  type SourceLoadRequest,
+  type SourceListRequest,
+  type SourceCommitRequest,
+  type SourceEventsRequest,
+  type SourceRequest,
+  type SourceResponse,
+} from './types.js';
+
+export {
+  ABLO_SOURCE_HEADERS,
+  SourceSignatureError,
+  signAbloSourceRequest,
+  verifyAbloSourceRequest,
+  type SourceSignatureOptions,
+  type SourceSignatureVerificationOptions,
+  type SourceSignatureVerificationResult,
+} from './signing.js';
+
+export {
+  dataSource,
+  type DataSourceOptions,
+} from './factory.js';
+
+export {
+  createPushQueue,
+  InMemoryPushQueueStorage,
+  STANDARD_WEBHOOKS_RETRY_SCHEDULE,
+  type PushQueue,
+  type PushQueueItem,
+  type PushQueueOptions,
+  type PushQueueStorage,
+} from './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
+// a Data Source from localhost or a private network that has no public inbound
+// URL. See `connectorProtocol.ts` for the frames it exchanges.
+export {
+  createSourceConnector,
+  DEFAULT_RECONNECT_SCHEDULE,
+  type SourceConnector,
+  type SourceConnectorOptions,
+  type ConnectorWebSocket,
+  type ConnectorWebSocketFactory,
+  type ConnectorStatus,
+} from './connector.js';
+export {
+  SOURCE_CONNECTOR_PROTOCOL_VERSION,
+  SOURCE_CONNECTOR_WS_PATH,
+  WS_SOURCE_SUBPROTOCOL,
+  sourceConnectorSubprotocols,
+  encodeFrame,
+  decodeFrame,
+  ConnectorProtocolError,
+  connectorFrameSchema,
+  type ConnectorFrame,
+  type RegisterFrame,
+  type ReadyFrame,
+  type RequestFrame,
+  type ResponseFrame,
+  type ErrorFrame,
+} from './connectorProtocol.js';
+
+// The Data Source adapter interface and its Zod contract, with per-ORM implementations.
+export {
+  type DataSourceAdapter,
+  type MutationAdapter,
+  type AdapterReadRequest,
+  type AdapterCommitResult,
+  type Row as AdapterRow,
+} from './adapter.js';
+export {
+  operationSchema,
+  operationTypeSchema,
+  sourceCommitEchoSchema,
+  sourceCommitEchoOperationSchema,
+  sourceCommitEchoMarkerSchema,
+  changeSetSchema,
+  outboxEventSchema,
+  eventsPageSchema,
+  migrationSchema,
+  adapterCapabilitiesSchema,
+  type Operation,
+  type ChangeSet,
+  type OutboxEvent,
+  type EventsPage,
+  type Migration,
+  type AdapterCapabilities,
+  type SourceCommitEchoMarkerWire,
+} from './contract.js';
+export { prismaDataSource, type PrismaLike, type PrismaDataSourceOptions } from './adapters/prisma.js';
+export {
+  adapterTableMigrations,
+  endpointOutboxMigrations,
+  idempotencyLedgerMigrations,
+} from './migrations.js';
+export {
+  createKyselyMutationAdapter,
+  createKyselyMutationCore,
+  kyselyDataSource,
+  kyselyDirectMutation,
+  kyselyOperationRowId,
+  type KyselyCompiledQuery,
+  type KyselyDeleteBuilder,
+  type KyselyInsertBuilder,
+  type KyselyInsertValuesBuilder,
+  type KyselyLike,
+  type KyselyMutationCore,
+  type KyselyReturningExecutable,
+  type KyselySelectBuilder,
+  type KyselyTransactionBuilder,
+  type KyselyUpdateBuilder,
+  type KyselyUpdateSetBuilder,
+} from './adapters/kysely.js';
+export {
+  sourceOperationsIntentHash,
+  sourceChangeIntentHash,
+  assertSourceIdempotencyIntent,
+  assertSourceIdempotencyRetention,
+  sourceEchoTransactionIdSchema,
+  encodeSourceEchoTransactionId,
+  decodeSourceEchoTransactionId,
+  type SourceEchoTransactionId,
+} from './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 {
+  ABLO_FOOTPRINT,
+  ABLO_PUBLICATION,
+  ABLO_REPLICATION_SLOT,
+  ABLO_REPLICATION_ROLE,
+  ABLO_WRITE_ROLE,
+  ABLO_IDEMPOTENCY_TABLE,
+  ABLO_OUTBOX_TABLE,
+  REPLICATION_SLOT_NAME,
+  isValidReplicationSlotName,
+  footprintNamesFor,
+  type FootprintArtifact,
+  type FootprintKind,
+  type FootprintNames,
+  type FootprintPlane,
+} from '../footprint.js';

package/src/source/kysely.ts

@@ -0,0 +1,2 @@
+/** Public compatibility facade for the Kysely source and direct-write adapters. */
+export * from './adapters/kysely.js';

package/src/source/migrations.ts

@@ -0,0 +1,109 @@
+/**
+ * The canonical table-creation SQL every ORM adapter ships for its own infrastructure
+ * tables: `ablo_idempotency`, whose legacy-named `client_tx_id` column stores the
+ * scoped server correlation, and (for endpoint wrappers only) `ablo_outbox`, the
+ * transactional outbox the `events()` feed reads. Direct wrappers install only
+ * the ledger migration because WAL is their authoritative feed.
+ *
+ * These are infrastructure tables, not model tables, and they exist only on your
+ * own database when you run a Data Source. Ablo's hosted storage does not use them;
+ * it records changes in its own `sync_deltas` log instead.
+ */
+
+import type { Migration } from './contract.js';
+
+/**
+ * Add a column to `ablo_idempotency` only when it is genuinely missing.
+ *
+ * `ADD COLUMN IF NOT EXISTS` performs its ownership check before the existence
+ * short-circuit, so on a ledger owned by another role the no-op re-run still
+ * errors "must be owner of table ablo_idempotency" — the setup's re-run promise
+ * breaks. `pg_attribute` is readable regardless of table ownership, so this DO
+ * block resolves the ledger through the search path and runs the `ALTER` only
+ * when the column is absent — a true no-op on a table that already has it.
+ */
+function addColumnIfAbsent(column: string, definition: string): string {
+  return `DO $$
+DECLARE ledger regclass := to_regclass('ablo_idempotency');
+BEGIN
+  IF ledger IS NOT NULL AND NOT EXISTS (
+    SELECT 1 FROM pg_attribute
+    WHERE attrelid = ledger AND attname = '${column}' AND attnum > 0 AND NOT attisdropped
+  ) THEN
+    ALTER TABLE ablo_idempotency ADD COLUMN ${column} ${definition};
+  END IF;
+END $$;`;
+}
+
+/** The idempotency ledger shared by direct and endpoint mutation wrappers. New
+ *  rows carry a bounded `expires_at` (set by the adapter at write time) so the
+ *  customer can prune them; the `infinity` column default is only a fallback for
+ *  a row inserted without one. */
+export function idempotencyLedgerMigrations(): readonly Migration[] {
+  return [
+    {
+      name: 'ablo_idempotency',
+      up: `CREATE TABLE IF NOT EXISTS ablo_idempotency (
+  client_tx_id TEXT PRIMARY KEY,
+  response     JSONB NOT NULL,
+  request_hash TEXT,
+  expires_at   TIMESTAMPTZ NOT NULL DEFAULT 'infinity',
+  created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);`,
+    },
+    {
+      name: 'ablo_idempotency_request_hash',
+      // Nullable only for rows created by older adapter versions. New writes
+      // always populate it; replaying a legacy NULL row fails closed because
+      // the adapter cannot prove that the intent matches.
+      //
+      // The column already exists on any current table (the CREATE above
+      // includes it), so this only matters when upgrading a pre-existing
+      // ledger. `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` checks ownership
+      // BEFORE it evaluates IF NOT EXISTS, so on a ledger that predates the
+      // setup — owned by another role — the no-op still errors "must be owner".
+      // Guard on the catalog (readable regardless of ownership) so the ALTER
+      // runs only when the column is genuinely absent, keeping re-runs safe.
+      up: addColumnIfAbsent('request_hash', 'TEXT'),
+    },
+    {
+      name: 'ablo_idempotency_permanent_retention',
+      up: addColumnIfAbsent('expires_at', `TIMESTAMPTZ NOT NULL DEFAULT 'infinity'`),
+    },
+  ];
+}
+
+/** 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,
+  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;`,
+    },
+  ];
+}
+
+/** Full endpoint adapter migrations (ledger + outbox). */
+export function adapterTableMigrations(): readonly Migration[] {
+  return [...idempotencyLedgerMigrations(), ...endpointOutboxMigrations()];
+}

package/src/source/next.ts

@@ -0,0 +1,38 @@
+/**
+ * A thin Next.js App Router wrapper for a Data Source. The core `dataSource()`
+ * already returns a standard `(Request) => Promise<Response>`, which the App Router
+ * accepts directly, so this helper adds only convenience: it names the handler
+ * `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 { prismaDataSource } from '@abloatai/transaction/source';
+ *   import { schema } from '@/ablo/schema';
+ *   import { prisma } from '@/lib/prisma';
+ *
+ *   export const { POST } = dataSourceNext({
+ *     schema,
+ *     apiKey: process.env.ABLO_API_KEY!,
+ *     adapter: prismaDataSource(prisma, schema),
+ *   });
+ *
+ * For hand-written handlers, or another framework, call the core `dataSource()`
+ * directly and export its result however that framework expects.
+ */
+
+import type { SchemaRecord } from '../schema/schema.js';
+import { dataSource, type DataSourceOptions } from './factory.js';
+
+/**
+ * The options for `dataSourceNext`, which are exactly the core
+ * `DataSourceOptions`. Pass `{ schema, apiKey, adapter }`, the same shape
+ * `dataSource()` takes.
+ */
+export type DataSourceNextOptions<S extends SchemaRecord, TAuth = unknown> =
+  DataSourceOptions<S, TAuth>;
+
+export function dataSourceNext<const S extends SchemaRecord, TAuth = unknown>(
+  options: DataSourceNextOptions<S, TAuth>,
+): { readonly POST: (request: Request) => Promise<Response> } {
+  return { POST: dataSource(options) };
+}

package/src/source/pushQueue.ts

@@ -0,0 +1,368 @@
+/**
+ * The durable retry queue for delivering source events to the server.
+ *
+ * When your application changes a row, it can push the resulting event to
+ * the server, which acknowledges delivery synchronously. If your process
+ * crashes mid-call, the network drops, or the server returns a 5xx, that
+ * event would be lost without a safety net. This queue is the safety net:
+ * it persists each event first, then delivers it from a background worker
+ * with automatic retries. (Polling the change feed is the slower fallback
+ * for anything the queue never manages to deliver.)
+ *
+ * The queue follows a familiar enqueue-and-worker shape:
+ *
+ *   - `enqueue(events)` returns as soon as the events are persisted.
+ *   - A background worker delivers them and retries on failure, following
+ *     the Standard Webhooks schedule (0, 5s, 5m, 30m, 2h, 5h, 10h, 14h,
+ *     20h, 24h — roughly three days in total).
+ *   - Items that exhaust every retry move to a dead-letter queue you can
+ *     monitor.
+ *
+ * Persistence is pluggable through {@link PushQueueStorage}. Use
+ * {@link InMemoryPushQueueStorage} for a single process, or implement that
+ * interface against your own outbox table for production durability.
+ */
+
+import { ABLO_SOURCE_HEADERS, signAbloSourceRequest } from './signing.js';
+import type { SourceEvent } from './types.js';
+
+/** One queued delivery: a batch of source events plus its retry bookkeeping. */
+export interface PushQueueItem {
+  readonly id: string;
+  readonly events: readonly SourceEvent[];
+  readonly attempts: number;
+  /** When the next attempt is due, in epoch milliseconds. The worker skips items due later. */
+  readonly nextAttemptAt: number;
+  /** The most recent error message, set once an attempt has failed. */
+  readonly lastError?: string;
+  /** `pending` while awaiting delivery, `delivered` on success, `dlq` once retries are exhausted. */
+  readonly status: 'pending' | 'delivered' | 'dlq';
+}
+
+/**
+ * The persistence behind a {@link PushQueue}. Implement it against your own
+ * durable table (or use {@link InMemoryPushQueueStorage}) so queued events
+ * survive a process restart. The queue calls these methods; you decide where
+ * the rows actually live.
+ */
+export interface PushQueueStorage {
+  /**
+   * Append a new item and return the persisted record. Generate a stable id
+   * — it doubles as the `webhook-id` on the delivered request — and set
+   * `nextAttemptAt` to the current time so the item is due immediately.
+   */
+  enqueue(events: readonly SourceEvent[]): Promise<PushQueueItem>;
+  /** Return pending items whose `nextAttemptAt` is at or before `now`, up to `limit`. */
+  due(now: number, limit: number): Promise<readonly PushQueueItem[]>;
+  /** Increase the attempt count and set the next attempt time after a failed delivery. */
+  reschedule(
+    id: string,
+    nextAttemptAt: number,
+    lastError: string,
+  ): Promise<void>;
+  /** Mark the item delivered so no further attempts are made. */
+  markDelivered(id: string): Promise<void>;
+  /** Move the item to the dead-letter queue after its retries are exhausted. */
+  markDlq(id: string, lastError: string): Promise<void>;
+  /** Read the dead-letter queue. Your monitoring reads this to surface deliveries that never succeeded. */
+  listDlq(): Promise<readonly PushQueueItem[]>;
+}
+
+/**
+ * The default retry schedule, taken from the Standard Webhooks
+ * specification. The index is the attempt number and the value is the delay
+ * in milliseconds after the previous attempt failed. Once an item runs off
+ * the end of this array, it moves to the dead-letter queue.
+ *
+ * See https://www.standardwebhooks.com/.
+ */
+export const STANDARD_WEBHOOKS_RETRY_SCHEDULE: readonly number[] = [
+  0, // immediate
+  5_000, // 5s
+  5 * 60_000, // 5m
+  30 * 60_000, // 30m
+  2 * 60 * 60_000, // 2h
+  5 * 60 * 60_000, // 5h
+  10 * 60 * 60_000, // 10h
+  14 * 60 * 60_000, // 14h
+  20 * 60 * 60_000, // 20h
+  24 * 60 * 60_000, // 24h
+];
+
+/** Configuration for {@link createPushQueue}. */
+export interface PushQueueOptions {
+  /** The URL the worker delivers events to. */
+  readonly endpoint: string;
+  /** The API key used to sign each delivery. */
+  readonly apiKey: string;
+  /** Where queued items are persisted. */
+  readonly storage: PushQueueStorage;
+  /**
+   * Override the retry delays. Defaults to {@link STANDARD_WEBHOOKS_RETRY_SCHEDULE}.
+   * The number of attempts equals the array length, and the i-th entry is the
+   * delay after attempt `i` failed.
+   */
+  readonly retrySchedule?: readonly number[];
+  /** How often the worker checks for due items, in milliseconds. Defaults to 1000. */
+  readonly tickIntervalMs?: number;
+  /** The most items the worker delivers per tick. Defaults to 50. */
+  readonly batchSize?: number;
+  /** A custom fetch implementation, for tests or runtimes without a global `fetch`. */
+  readonly fetch?: typeof fetch;
+  /** A custom clock source, mainly for tests. Defaults to `Date.now`. */
+  readonly now?: () => number;
+  /** Random jitter applied to each retry delay, as a fraction. Defaults to ±10%; set 0 to disable. */
+  readonly jitter?: number;
+  /** Called when an item is dead-lettered or the worker loop hits an error. */
+  readonly onError?: (item: PushQueueItem, err: unknown) => void;
+}
+
+/** A running push queue: persist events, deliver them, and recover dead-lettered ones. */
+export interface PushQueue {
+  /** Persist a batch of events for delivery and return the queued item. */
+  enqueue(events: readonly SourceEvent[]): Promise<PushQueueItem>;
+  /** Run the delivery worker until `signal` aborts. */
+  run(signal: AbortSignal): Promise<void>;
+  /**
+   * Re-enqueue every dead-lettered item for another round of delivery. Call
+   * this yourself once you have fixed whatever caused the failures. Returns
+   * the number of items re-enqueued.
+   */
+  redriveDlq(): Promise<number>;
+}
+
+/** Create a {@link PushQueue} from the given {@link PushQueueOptions}. */
+export function createPushQueue(options: PushQueueOptions): PushQueue {
+  const tickIntervalMs = options.tickIntervalMs ?? 1000;
+  const batchSize = options.batchSize ?? 50;
+  const fetchImpl = options.fetch ?? fetch;
+  const now = options.now ?? Date.now;
+  const schedule = options.retrySchedule ?? STANDARD_WEBHOOKS_RETRY_SCHEDULE;
+  const jitter = options.jitter ?? 0.1;
+
+  return {
+    async enqueue(events) {
+      return options.storage.enqueue(events);
+    },
+
+    async run(signal) {
+      while (!signal.aborted) {
+        try {
+          const due = await options.storage.due(now(), batchSize);
+          for (const item of due) {
+            if (signal.aborted) return;
+            await deliver(item);
+          }
+        } catch (err) {
+          // Storage failures shouldn't kill the loop; surface and
+          // back off the tick interval.
+          options.onError?.(
+            { id: 'storage', events: [], attempts: 0, nextAttemptAt: 0, status: 'pending' },
+            err,
+          );
+        }
+        await sleep(tickIntervalMs, signal);
+      }
+    },
+
+    async redriveDlq() {
+      const items = await options.storage.listDlq();
+      let redriven = 0;
+      for (const item of items) {
+        await options.storage.enqueue(item.events);
+        redriven++;
+      }
+      return redriven;
+    },
+  };
+
+  async function deliver(item: PushQueueItem): Promise<void> {
+    const rawBody = JSON.stringify({ events: item.events });
+    let signed: Awaited<ReturnType<typeof signAbloSourceRequest>>;
+    try {
+      signed = await signAbloSourceRequest({
+        apiKey: options.apiKey,
+        body: rawBody,
+        timestamp: Math.floor(now() / 1000),
+        // Reuse the queue id as the webhook-id across all retry
+        // attempts so the receiver can dedupe replays per spec.
+        messageId: item.id,
+      });
+    } catch (err) {
+      // Signing should not fail in practice (no network, just HMAC).
+      // If it does, treat as a permanent failure.
+      await options.storage.markDlq(item.id, formatError(err));
+      options.onError?.(item, err);
+      return;
+    }
+
+    let response: Response;
+    try {
+      response = await fetchImpl(options.endpoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...signed.headers,
+          [ABLO_SOURCE_HEADERS.idempotencyKey]: item.id,
+        },
+        body: rawBody,
+      });
+    } catch (err) {
+      await reschedule(item, formatError(err));
+      return;
+    }
+
+    if (response.ok) {
+      await options.storage.markDelivered(item.id);
+      return;
+    }
+
+    // 4xx other than 408/429 are unrecoverable — don't retry. Move
+    // straight to DLQ so the customer's monitoring catches the bad
+    // request shape early instead of waiting 3 days for retries.
+    if (
+      response.status >= 400 &&
+      response.status < 500 &&
+      response.status !== 408 &&
+      response.status !== 429
+    ) {
+      await options.storage.markDlq(
+        item.id,
+        `HTTP ${response.status}`,
+      );
+      return;
+    }
+
+    await reschedule(item, `HTTP ${response.status}`);
+  }
+
+  async function reschedule(
+    item: PushQueueItem,
+    error: string,
+  ): Promise<void> {
+    const nextAttempt = item.attempts + 1;
+    // Past the end of the backoff schedule: no attempts left, so dead-letter
+    // the item.
+    const backoff = schedule[nextAttempt];
+    if (backoff === undefined) {
+      await options.storage.markDlq(item.id, error);
+      options.onError?.(item, new Error(error));
+      return;
+    }
+    const delay = applyJitter(backoff, jitter);
+    await options.storage.reschedule(item.id, now() + delay, error);
+  }
+}
+
+/**
+ * A {@link PushQueueStorage} that keeps items in memory. It is not durable —
+ * items are lost when the process restarts — so it suits development and
+ * low-volume use. For production, implement {@link PushQueueStorage} against
+ * your own table.
+ */
+export class InMemoryPushQueueStorage implements PushQueueStorage {
+  private items = new Map<string, PushQueueItem>();
+  private nextId = 0;
+  private readonly now: () => number;
+
+  constructor(options: { now?: () => number } = {}) {
+    this.now = options.now ?? Date.now;
+  }
+
+  async enqueue(events: readonly SourceEvent[]): Promise<PushQueueItem> {
+    const id = `q_${(++this.nextId).toString(36)}_${Math.random()
+      .toString(36)
+      .slice(2, 8)}`;
+    const item: PushQueueItem = {
+      id,
+      events,
+      attempts: 0,
+      nextAttemptAt: this.now(),
+      status: 'pending',
+    };
+    this.items.set(id, item);
+    return item;
+  }
+
+  async due(now: number, limit: number): Promise<readonly PushQueueItem[]> {
+    const out: PushQueueItem[] = [];
+    for (const item of this.items.values()) {
+      if (out.length >= limit) break;
+      if (item.status !== 'pending') continue;
+      if (item.nextAttemptAt > now) continue;
+      out.push(item);
+    }
+    return out;
+  }
+
+  async reschedule(
+    id: string,
+    nextAttemptAt: number,
+    lastError: string,
+  ): Promise<void> {
+    const item = this.items.get(id);
+    if (!item) return;
+    this.items.set(id, {
+      ...item,
+      attempts: item.attempts + 1,
+      nextAttemptAt,
+      lastError,
+    });
+  }
+
+  async markDelivered(id: string): Promise<void> {
+    const item = this.items.get(id);
+    if (!item) return;
+    this.items.set(id, { ...item, status: 'delivered' });
+  }
+
+  async markDlq(id: string, lastError: string): Promise<void> {
+    const item = this.items.get(id);
+    if (!item) return;
+    this.items.set(id, {
+      ...item,
+      attempts: item.attempts + 1,
+      status: 'dlq',
+      lastError,
+    });
+  }
+
+  async listDlq(): Promise<readonly PushQueueItem[]> {
+    return Array.from(this.items.values()).filter((i) => i.status === 'dlq');
+  }
+
+  /** Test helper — read all items regardless of status. */
+  snapshot(): readonly PushQueueItem[] {
+    return Array.from(this.items.values());
+  }
+}
+
+function applyJitter(delayMs: number, factor: number): number {
+  if (factor <= 0 || delayMs === 0) return delayMs;
+  const swing = delayMs * factor;
+  return Math.max(0, delayMs + (Math.random() * 2 - 1) * swing);
+}
+
+function formatError(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve) => {
+    if (signal.aborted) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      signal.removeEventListener('abort', onAbort);
+      resolve();
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+}