@abloatai/humans 0.37.0

package/src/local/transactions/mutations/coalesceRules.ts

@@ -0,0 +1,192 @@
+/**
+ * The queue's rules for coalescing operations that touch the same row, so their
+ * causal order is preserved. {@link MutationQueue} calls into these through a
+ * small store-shaped interface:
+ *
+ *   - Create-then-delete cancellation ({@link takeUnsentCreateForModel}):
+ *     deleting a row whose create never left the client cancels both locally.
+ *   - The create barrier ({@link findCreateBarrierForDelete}) and deferred-delete
+ *     parking ({@link deferDeleteUntilCreateSettles} /
+ *     {@link releaseDeferredDeletesForCreate}): once a create has been sent, a
+ *     delete must wait for it to settle, or the server could receive the delete
+ *     before the create.
+ *   - Update-payload merging ({@link mergeUpdateData}): collapses rapid updates
+ *     to the same row into one wire operation.
+ *
+ * The queue keeps the `enqueue` and `delete` methods that orchestrate optimistic
+ * state and events; these functions hold only the coalescing rules.
+ */
+
+import type { MutationInput, QueuedMutation } from './commitPayload.js';
+
+/** The subset of {@link MutationStore} that the coalescing rules read. */
+export interface MutationStoreLike {
+  get(id: string): QueuedMutation | undefined;
+  getByStatus(status: QueuedMutation['status']): QueuedMutation[];
+}
+
+export const entityKey = (modelName: string, modelId: string): string =>
+  `${modelName}:${modelId}`;
+
+const isTransactionForModel = (
+  transaction: QueuedMutation,
+  modelName: string,
+  modelId: string,
+): boolean => transaction.modelName === modelName && transaction.modelId === modelId;
+
+/**
+ * Finds and removes a create for the given model and id that has never been
+ * sent, searching the staging area, the execution queue, and the store's
+ * pending bucket in that order. It splices the match out of whichever queue
+ * held it, so the caller can cancel it rather than send a create followed by a
+ * delete.
+ */
+export function takeUnsentCreateForModel(
+  staged: QueuedMutation[],
+  queued: QueuedMutation[],
+  store: Pick<MutationStoreLike, 'getByStatus'>,
+  modelName: string,
+  modelId: string,
+): QueuedMutation | undefined {
+  const isUnsentCreate = (tx: QueuedMutation): boolean =>
+    tx.type === 'create' &&
+    tx.status === 'pending' &&
+    tx.attempts === 0 &&
+    isTransactionForModel(tx, modelName, modelId);
+
+  const stagedIndex = staged.findIndex(isUnsentCreate);
+  if (stagedIndex >= 0) {
+    return staged.splice(stagedIndex, 1)[0];
+  }
+
+  const queuedIndex = queued.findIndex(isUnsentCreate);
+  if (queuedIndex >= 0) {
+    return queued.splice(queuedIndex, 1)[0];
+  }
+
+  return store.getByStatus('pending').find(isUnsentCreate);
+}
+
+/**
+ * Returns the most recent in-flight create for the given model and id that a
+ * delete must wait behind, or undefined if there is none. A pending create that
+ * has never been attempted is not a barrier, because it can be cancelled
+ * instead; once a create has been sent, even a retry-pending one is a barrier.
+ */
+export function findCreateBarrierForDelete(
+  store: Pick<MutationStoreLike, 'getByStatus'>,
+  modelName: string,
+  modelId: string,
+): QueuedMutation | undefined {
+  const liveCreates = [
+    ...store.getByStatus('pending'),
+    ...store.getByStatus('executing'),
+    ...store.getByStatus('awaiting_delta'),
+  ].filter((tx) =>
+    tx.type === 'create' &&
+    isTransactionForModel(tx, modelName, modelId) &&
+    // A never-attempted pending create can be cancelled instead. Once the
+    // create has been sent, even a retry-pending state is a causal barrier:
+    // the server may already have applied it and only the response was lost.
+    (tx.status !== 'pending' || tx.attempts > 0)
+  );
+
+  return liveCreates.sort((a, b) => b.createdAt - a.createdAt)[0];
+}
+
+/**
+ * Parks a delete until the create for the same row settles, keyed by the
+ * create's model and id. {@link releaseDeferredDeletesForCreate} re-enqueues
+ * the parked deletes once that create completes.
+ */
+export function deferDeleteUntilCreateSettles(
+  deferredDeletesByCreate: Map<string, QueuedMutation[]>,
+  createTransaction: QueuedMutation,
+  deleteTransaction: QueuedMutation,
+): void {
+  const key = entityKey(createTransaction.modelName, createTransaction.modelId);
+  const deferred = deferredDeletesByCreate.get(key) ?? [];
+  deferred.push(deleteTransaction);
+  deferredDeletesByCreate.set(key, deferred);
+}
+
+/**
+ * Re-enqueues the deletes parked behind a create once that create settles,
+ * skipping any whose status is no longer pending.
+ */
+export function releaseDeferredDeletesForCreate(
+  deferredDeletesByCreate: Map<string, QueuedMutation[]>,
+  store: Pick<MutationStoreLike, 'get'>,
+  enqueue: (transaction: QueuedMutation) => void,
+  createTransaction: QueuedMutation,
+): void {
+  const key = entityKey(createTransaction.modelName, createTransaction.modelId);
+  const deferred = deferredDeletesByCreate.get(key);
+  if (!deferred || deferred.length === 0) return;
+
+  deferredDeletesByCreate.delete(key);
+
+  for (const deleteTransaction of deferred) {
+    if (store.get(deleteTransaction.id)?.status !== 'pending') continue;
+    enqueue(deleteTransaction);
+  }
+}
+
+/**
+ * Merges two update payloads for the same row into one. Later values win, with
+ * one exception: a `metadata` field is deep-merged as an object — parsing it
+ * first when it arrives as a JSON string — rather than replaced, so partial
+ * metadata updates accumulate instead of overwriting each other.
+ */
+export function mergeUpdateData(
+  left: MutationInput | undefined,
+  right: MutationInput | undefined,
+  _modelName?: string
+): MutationInput {
+  const out: MutationInput = { ...(left || {}) };
+  const src = right || {};
+
+  for (const key of Object.keys(src)) {
+    // Special case: metadata payloads may be JSON strings; merge objects instead of clobbering
+    if (key === 'metadata') {
+      const l = out.metadata;
+      const r = src.metadata;
+
+      // If both sides undefined/null, continue
+      if (l == null && r == null) {
+        continue;
+      }
+
+      // Normalize to objects
+      const toObj = (v: unknown): Record<string, unknown> => {
+        if (v == null) return {};
+        if (typeof v === 'string') {
+          try {
+            return JSON.parse(v);
+          } catch {
+            return {};
+          }
+        }
+        if (typeof v === 'object') return v as Record<string, unknown>;
+        return {};
+      };
+
+      const lobj = toObj(l);
+      const robj = toObj(r);
+      const merged = { ...lobj, ...robj };
+      // Re-stringify to match schema input type
+      try {
+        out.metadata = JSON.stringify(merged);
+      } catch {
+        // Fallback to right-hand side if stringify fails
+        out.metadata = typeof r === 'string' ? r : JSON.stringify(robj || {});
+      }
+      continue;
+    }
+
+    // Default: shallow overwrite with right-hand value
+    out[key] = src[key];
+  }
+
+  return out;
+}

package/src/local/transactions/mutations/commitApi.ts

@@ -0,0 +1,97 @@
+import { AbloIdempotencyError } from '@abloatai/transaction/errors';
+import type { ReadDependency, TrackDependency } from '@abloatai/transaction/coordination/schema';
+import { stableStringify } from '@abloatai/transaction/utils/json';
+import type { DurableCommitEnvelope } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import type { CommitTransaction } from './commitLane.js';
+import type { SealDurableCommitInput } from './commitTransport.js';
+
+export interface CommitApiContext {
+  readonly assertDurableReplayOpen: () => void;
+  readonly commitStore: Map<string, CommitTransaction>;
+  readonly commitLane: CommitTransaction[];
+  readonly replicationLagErrors: Map<string, Error>;
+  readonly clearReplicationLagState: (transactionId: string) => void;
+  readonly nextCommitSequence: () => number;
+  readonly sealDurableCommit: (input: SealDurableCommitInput) => Promise<DurableCommitEnvelope>;
+  readonly processCommitLane: () => Promise<void>;
+  readonly emitCommitLifecycle: (event: string, payload: object) => void;
+}
+
+export async function enqueueCommit(
+  ctx: CommitApiContext,
+  clientTxId: string,
+  operations: CommitTransaction['operations'],
+  options: { reads?: ReadDependency[] | null; track?: TrackDependency[] | null } = {},
+): Promise<void> {
+  ctx.assertDurableReplayOpen();
+  const existing = ctx.commitStore.get(clientTxId);
+  if (existing) {
+    await existing.sealPromise;
+    const existingIntent = stableStringify({
+      operations: existing.operations,
+      reads: existing.reads ?? null,
+      track: existing.track ?? null,
+    });
+    const incomingIntent = stableStringify({
+      operations,
+      reads: options.reads ?? null,
+      track: options.track ?? null,
+    });
+    if (existingIntent !== incomingIntent) {
+      throw new AbloIdempotencyError(
+        'Idempotency key reused with a different atomic commit request',
+        { code: 'idempotency_conflict' },
+      );
+    }
+    if (existing.status === 'awaiting_delta' && ctx.replicationLagErrors.has(existing.id)) {
+      ctx.clearReplicationLagState(existing.id);
+      existing.status = 'pending';
+      ctx.commitLane.push(existing);
+    }
+    if (existing.status === 'pending') void ctx.processCommitLane();
+    return;
+  }
+
+  ctx.emitCommitLifecycle('commit:staging', { clientTxId, operations });
+  const now = Date.now();
+  const tx: CommitTransaction = {
+    id: clientTxId,
+    kind: 'commit',
+    operations: [...operations],
+    ...(options.reads ? { reads: options.reads } : {}),
+    ...(options.track ? { track: options.track } : {}),
+    status: 'pending',
+    createdAt: now,
+    attempts: 0,
+    sealedAt: now,
+    sequence: ctx.nextCommitSequence(),
+  };
+  ctx.commitStore.set(clientTxId, tx);
+  tx.sealPromise = ctx.sealDurableCommit({
+    idempotencyKey: tx.id,
+    origin: 'atomic_commit',
+    operations: tx.operations,
+    commitOptions: {
+      ...(tx.reads ? { reads: tx.reads } : {}),
+      ...(tx.track ? { track: tx.track } : {}),
+    },
+    createdAt: tx.createdAt,
+    sealedAt: tx.sealedAt,
+    sequence: tx.sequence,
+  }).then((envelope) => {
+    tx.durableEnvelope = envelope;
+    tx.operations = envelope.operations.map((operation) => ({ ...operation }));
+  });
+  try {
+    await tx.sealPromise;
+  } catch (error) {
+    ctx.commitStore.delete(clientTxId);
+    ctx.emitCommitLifecycle('commit:seal_failed', { clientTxId });
+    throw error;
+  } finally {
+    tx.sealPromise = undefined;
+  }
+  ctx.commitLane.push(tx);
+  ctx.emitCommitLifecycle('commit:created', { clientTxId, operations: tx.operations });
+  void ctx.processCommitLane();
+}

package/src/local/transactions/mutations/commitLane.ts

@@ -0,0 +1,191 @@
+import type { RuntimeContext } from '../../RuntimeContext.js';
+import type { ReadDependency, TrackDependency, OnStaleMode, StaleNotification } from '@abloatai/transaction/coordination/schema';
+import { AbloConnectionError } from '@abloatai/transaction/errors';
+import type { MutationCommitResult } from '@abloatai/transaction/wire/commit';
+import type {
+  DurableCommitEnvelope,
+  DurableCommitOperation,
+} from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import type { SealDurableCommitInput } from './commitTransport.js';
+
+export interface CommitTransaction {
+  id: string;
+  kind: 'commit';
+  operations: {
+    type: DurableCommitOperation['type'];
+    model: string;
+    id: string;
+    input?: Record<string, unknown>;
+    transactionId?: string;
+    readAt?: number | null;
+    onStale?: OnStaleMode | null;
+  }[];
+  reads?: ReadDependency[] | null;
+  track?: TrackDependency[] | null;
+  status: 'pending' | 'executing' | 'awaiting_delta' | 'completed' | 'failed';
+  createdAt: number;
+  attempts: number;
+  transientAttempts?: number;
+  lastSyncId?: number;
+  correlationId?: string;
+  error?: Error;
+  sealedAt: number;
+  sequence: number;
+  sealPromise?: Promise<void>;
+  durableEnvelope?: DurableCommitEnvelope;
+  sourceMutationIds?: string[];
+}
+
+export interface CommitLaneContext {
+  readonly runtime: RuntimeContext;
+  readonly config: { maxRetries: number };
+  readonly commitLane: CommitTransaction[];
+  readonly commitNotifications: Map<string, StaleNotification[]>;
+  readonly commitMissingIds: Map<string, string[]>;
+  readonly commitProcessing: boolean;
+  readonly setCommitProcessing: (value: boolean) => void;
+  readonly durableReplayBlock: object | null;
+  readonly sealDurableCommit: (input: SealDurableCommitInput) => Promise<DurableCommitEnvelope>;
+  readonly assertEnvelopeInsideReplayWindow: (envelope: DurableCommitEnvelope) => void;
+  readonly dispatchCommit: (envelope: DurableCommitEnvelope) => Promise<MutationCommitResult>;
+  readonly persistDurableCommitAcceptance: (envelope: DurableCommitEnvelope, result: MutationCommitResult) => Promise<DurableCommitEnvelope>;
+  readonly removeDurableCommit: (idempotencyKey: string) => Promise<void>;
+  readonly queuedCommitEchoSyncId: (transaction: CommitTransaction) => number | undefined;
+  readonly completeQueuedCommit: (transaction: CommitTransaction, syncId: number) => void;
+  readonly scheduleReplicationLagTimeout: (transactionId: string, clientTxId: string, correlationId?: string) => void;
+  readonly noteAck: (syncId: number | undefined) => void;
+  readonly isDefinitiveRejection: (error: Error) => boolean;
+  readonly isPermanentError: (error: Error) => boolean;
+  readonly emitCommitLifecycle: (event: string, payload: object) => void;
+}
+
+export interface CommitReceiptContext {
+  readonly commitStore: Map<string, CommitTransaction>;
+  readonly commitNotifications: Map<string, StaleNotification[]>;
+  readonly commitMissingIds: Map<string, string[]>;
+  readonly replicationLagErrors: Map<string, Error>;
+  readonly on: (event: string, listener: (payload: object) => void) => void;
+  readonly off: (event: string, listener: (payload: object) => void) => void;
+}
+
+export function waitForCommitReceipt(
+  ctx: CommitReceiptContext,
+  clientTxId: string,
+): Promise<{ lastSyncId: number; notifications?: StaleNotification[]; missingIds?: string[] }> {
+  const drainNotifications = (): StaleNotification[] | undefined => {
+    const notifications = ctx.commitNotifications.get(clientTxId);
+    if (!notifications) return undefined;
+    ctx.commitNotifications.delete(clientTxId);
+    return notifications.length > 0 ? notifications : undefined;
+  };
+  const drainMissingIds = (): string[] | undefined => {
+    const ids = ctx.commitMissingIds.get(clientTxId);
+    if (!ids) return undefined;
+    ctx.commitMissingIds.delete(clientTxId);
+    return ids.length > 0 ? ids : undefined;
+  };
+  const receipt = (lastSyncId: number) => {
+    const missingIds = drainMissingIds();
+    return {
+      lastSyncId,
+      notifications: drainNotifications(),
+      ...(missingIds ? { missingIds } : {}),
+    };
+  };
+  return new Promise((resolve, reject) => {
+    const existing = ctx.commitStore.get(clientTxId);
+    if (existing?.status === 'completed') { resolve(receipt(existing.lastSyncId ?? 0)); return; }
+    if (existing?.status === 'failed' && existing.error) { reject(existing.error); return; }
+    const lagError = ctx.replicationLagErrors.get(clientTxId);
+    if (lagError) { reject(lagError); return; }
+    const onCompleted = (tx: object) => { cleanup(); resolve(receipt((tx as CommitTransaction).lastSyncId ?? 0)); };
+    const onFailed = (payload: object) => { cleanup(); reject((payload as { error: Error }).error); };
+    const onLagged = (payload: object) => { cleanup(); reject((payload as { error: Error }).error); };
+    const cleanup = () => {
+      ctx.off(`transaction:completed:${clientTxId}`, onCompleted);
+      ctx.off(`transaction:failed:${clientTxId}`, onFailed);
+      ctx.off(`transaction:confirmation_lagged:${clientTxId}`, onLagged);
+    };
+    ctx.on(`transaction:completed:${clientTxId}`, onCompleted);
+    ctx.on(`transaction:failed:${clientTxId}`, onFailed);
+    ctx.on(`transaction:confirmation_lagged:${clientTxId}`, onLagged);
+  });
+}
+
+export async function processCommitLane(ctx: CommitLaneContext): Promise<void> {
+  if (ctx.commitProcessing || ctx.durableReplayBlock) return;
+  ctx.setCommitProcessing(true);
+  try {
+    while (ctx.commitLane.length > 0) {
+      const tx = ctx.commitLane[0];
+      if (!tx) break;
+      if (tx.status !== 'pending') {
+        ctx.commitLane.shift();
+        continue;
+      }
+      tx.status = 'executing';
+      tx.attempts += 1;
+      let dispatchStarted = false;
+      try {
+        const durableEnvelope = tx.durableEnvelope ?? await ctx.sealDurableCommit({
+          idempotencyKey: tx.id,
+          origin: 'atomic_commit',
+          operations: tx.operations,
+          sourceMutationIds: tx.sourceMutationIds,
+          commitOptions: {
+            ...(tx.reads ? { reads: tx.reads } : {}),
+            ...(tx.track ? { track: tx.track } : {}),
+          },
+          createdAt: tx.createdAt,
+          sealedAt: tx.sealedAt,
+          sequence: tx.sequence,
+        });
+        tx.durableEnvelope = durableEnvelope;
+        ctx.assertEnvelopeInsideReplayWindow(durableEnvelope);
+        dispatchStarted = true;
+        const result = await ctx.dispatchCommit(durableEnvelope);
+        tx.durableEnvelope = await ctx.persistDurableCommitAcceptance(durableEnvelope, result);
+        tx.lastSyncId = result.lastSyncId;
+        if (result.notifications?.length) ctx.commitNotifications.set(tx.id, result.notifications);
+        if (result.missingIds?.length) ctx.commitMissingIds.set(tx.id, result.missingIds);
+        ctx.commitLane.shift();
+        if (result.status === 'queued') {
+          tx.correlationId = result.correlationId;
+          tx.status = 'awaiting_delta';
+          const echoSyncId = ctx.queuedCommitEchoSyncId(tx);
+          if (echoSyncId !== undefined) ctx.completeQueuedCommit(tx, echoSyncId);
+          else ctx.scheduleReplicationLagTimeout(tx.id, tx.id, result.correlationId);
+        } else {
+          await ctx.removeDurableCommit(tx.id);
+          ctx.noteAck(tx.lastSyncId);
+          tx.status = 'completed';
+          ctx.emitCommitLifecycle('transaction:completed', tx);
+          ctx.emitCommitLifecycle(`transaction:completed:${tx.id}`, tx);
+        }
+      } catch (cause) {
+        const error = cause instanceof Error ? cause : new Error(String(cause));
+        if (dispatchStarted && ctx.isDefinitiveRejection(error)) await ctx.removeDurableCommit(tx.id);
+        if (!(error instanceof AbloConnectionError)) tx.transientAttempts = (tx.transientAttempts ?? 0) + 1;
+        const exhausted = (tx.transientAttempts ?? 0) > ctx.config.maxRetries;
+        if (!ctx.isPermanentError(error) && !exhausted) {
+          tx.status = 'pending';
+          ctx.runtime.logger.debug('[MutationQueue] commit lane transient', {
+            txId: tx.id.slice(0, 12), attempts: tx.attempts,
+            transientAttempts: tx.transientAttempts ?? 0, message: error.message,
+          });
+          break;
+        }
+        tx.status = 'failed';
+        tx.error = error;
+        ctx.commitLane.shift();
+        ctx.runtime.logger.debug('[MutationQueue] commit lane permanent error', {
+          txId: tx.id.slice(0, 12), attempts: tx.attempts, message: error.message,
+        });
+        ctx.emitCommitLifecycle('transaction:failed', { transaction: tx, error, permanent: true });
+        ctx.emitCommitLifecycle(`transaction:failed:${tx.id}`, { error });
+      }
+    }
+  } finally {
+    ctx.setCommitProcessing(false);
+  }
+}

package/src/local/transactions/mutations/commitLatency.ts

@@ -0,0 +1,164 @@
+/**
+ * Commit latency — how long a user's edit actually takes to land.
+ *
+ * The engine has never measured this. HUDs and dashboards reach for
+ * `window.fetch` timings, which the sync engine's WebSocket never touches, so
+ * the latency a user sees reported while editing has had nothing to do with
+ * the writes they are making. This module closes that gap without adding a
+ * single timestamp to the hot path: `MutationQueue` already emits the commit
+ * lifecycle, and the events already carry the correlation key.
+ *
+ * Three events, two intervals:
+ *
+ *   commit:staging ──sealMs──▶ commit:created ──ackMs──▶ transaction:completed
+ *
+ *  - `sealMs` is **local** — writing the durable envelope before the commit is
+ *    allowed onto the wire. Slow here means durable storage, not network.
+ *  - `ackMs` is **remote** — dispatch, round-trip, and server work. For a
+ *    commit routed at a connected source this also spans the wait for the
+ *    correlated echo that promotes `queued` to `confirmed`, so it answers
+ *    "when did my edit become real" rather than raw socket round-trip. Read a
+ *    large `ackMs` against a small `sealMs` as a network or replication cost.
+ *
+ * Correlation is by `clientTxId`: `MutationQueue` uses it as the transaction
+ * id verbatim, so the staging event and the completion event share one key.
+ */
+
+/**
+ * The slice of an event emitter this module needs. Declared structurally so a
+ * plain object can stand in under test — `MutationQueue` satisfies it by
+ * extending `EventEmitter`.
+ */
+export interface CommitEventSource {
+  on(event: string, listener: (payload: unknown) => void): unknown;
+  off(event: string, listener: (payload: unknown) => void): unknown;
+}
+
+/** One completed commit, broken into its local and remote halves. */
+export interface CommitLatencySample {
+  /** The commit's `clientTxId`, identical to its transaction id. */
+  clientTxId: string;
+  /** Milliseconds sealing the durable envelope locally. */
+  sealMs: number;
+  /** Milliseconds from sealed envelope to acknowledgement. */
+  ackMs: number;
+  /** Milliseconds from staging to acknowledgement — `sealMs + ackMs`. */
+  totalMs: number;
+}
+
+interface PendingCommitTiming {
+  stagedAt: number;
+  /** Set when the envelope seals; null while the seal is still in flight. */
+  sealedAt: number | null;
+}
+
+/**
+ * Cap on commits awaiting completion. A commit whose completion never arrives
+ * (connection dropped mid-flight, retry abandoned) would otherwise pin its
+ * entry forever, so the map is bounded rather than trusted to drain.
+ */
+const MAX_PENDING_COMMITS = 256;
+
+function nowMs(): number {
+  return typeof performance !== 'undefined' ? performance.now() : Date.now();
+}
+
+/** Read `clientTxId` off a `commit:*` payload, or null if it isn't shaped so. */
+function readClientTxId(payload: unknown): string | null {
+  if (typeof payload !== 'object' || payload === null) return null;
+  const { clientTxId } = payload as { clientTxId?: unknown };
+  return typeof clientTxId === 'string' ? clientTxId : null;
+}
+
+/** Read `id` off a transaction payload (`transaction:completed` sends the tx). */
+function readTransactionId(payload: unknown): string | null {
+  if (typeof payload !== 'object' || payload === null) return null;
+  const { id } = payload as { id?: unknown };
+  return typeof id === 'string' ? id : null;
+}
+
+/** `transaction:failed` wraps the transaction rather than sending it bare. */
+function readFailedTransactionId(payload: unknown): string | null {
+  if (typeof payload !== 'object' || payload === null) return null;
+  return readTransactionId((payload as { transaction?: unknown }).transaction);
+}
+
+/**
+ * Pair commit lifecycle events into latency samples. Returns an unsubscribe
+ * function that also drops any still-pending timings.
+ *
+ * `onSample` fires once per commit that completes, in completion order.
+ */
+export function observeCommitLatency(
+  source: CommitEventSource,
+  onSample: (sample: CommitLatencySample) => void,
+): () => void {
+  const pending = new Map<string, PendingCommitTiming>();
+
+  const handleStaging = (payload: unknown): void => {
+    const id = readClientTxId(payload);
+    if (id === null) return;
+    // Map preserves insertion order, so the first key is the stalest entry.
+    if (pending.size >= MAX_PENDING_COMMITS) {
+      const oldest = pending.keys().next();
+      if (!oldest.done) pending.delete(oldest.value);
+    }
+    pending.set(id, { stagedAt: nowMs(), sealedAt: null });
+  };
+
+  const handleCreated = (payload: unknown): void => {
+    const id = readClientTxId(payload);
+    if (id === null) return;
+    const timing = pending.get(id);
+    if (timing === undefined) return;
+    timing.sealedAt = nowMs();
+  };
+
+  const handleCompleted = (payload: unknown): void => {
+    const id = readTransactionId(payload);
+    if (id === null) return;
+    const timing = pending.get(id);
+    // `transaction:completed` also fires for local (non-commit) transactions
+    // and for mutation-log replay. Only ids we staged are commits, so an
+    // absent entry is the normal way those are filtered out.
+    if (timing === undefined) return;
+    pending.delete(id);
+
+    const completedAt = nowMs();
+    // A commit can complete without an observed seal only if the listener was
+    // attached mid-flight; attributing the whole span to `ackMs` keeps
+    // `sealMs + ackMs === totalMs` true rather than reporting a bogus seal.
+    const sealedAt = timing.sealedAt ?? timing.stagedAt;
+    onSample({
+      clientTxId: id,
+      sealMs: sealedAt - timing.stagedAt,
+      ackMs: completedAt - sealedAt,
+      totalMs: completedAt - timing.stagedAt,
+    });
+  };
+
+  const handleSealFailed = (payload: unknown): void => {
+    const id = readClientTxId(payload);
+    if (id !== null) pending.delete(id);
+  };
+
+  const handleFailed = (payload: unknown): void => {
+    const id = readFailedTransactionId(payload);
+    if (id !== null) pending.delete(id);
+  };
+
+  source.on('commit:staging', handleStaging);
+  source.on('commit:created', handleCreated);
+  source.on('commit:seal_failed', handleSealFailed);
+  source.on('transaction:completed', handleCompleted);
+  source.on('transaction:failed', handleFailed);
+
+  return () => {
+    source.off('commit:staging', handleStaging);
+    source.off('commit:created', handleCreated);
+    source.off('commit:seal_failed', handleSealFailed);
+    source.off('transaction:completed', handleCompleted);
+    source.off('transaction:failed', handleFailed);
+    pending.clear();
+  };
+}