@abloatai/humans 0.59.1 → 0.59.2

package/dist/local/transactions/mutations/replayValidation.d.ts

@@ -27,11 +27,11 @@ import type { RuntimeContext } from '../../RuntimeContext.js';
 export declare const persistedTransactionSchema: z.ZodObject<{
     id: z.ZodString;
     type: z.ZodEnum<{
-        update: "update";
+        archive: "archive";
         create: "create";
         delete: "delete";
-        archive: "archive";
         unarchive: "unarchive";
+        update: "update";
     }>;
     modelName: z.ZodString;
     modelId: z.ZodString;
@@ -95,10 +95,10 @@ export declare function deserializePersistedTransaction(row: unknown, runtime?:
 export declare const persistedMutationSchema: z.ZodObject<{
     mutationId: z.ZodOptional<z.ZodString>;
     type: z.ZodEnum<{
-        update: "update";
+        archive: "archive";
         create: "create";
         delete: "delete";
-        archive: "archive";
+        update: "update";
     }>;
     modelData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     modelName: z.ZodString;
@@ -133,15 +133,14 @@ export declare const PENDING_MUTATION_RECORD_PREFIX = "pending-mutation:";
 export declare const PENDING_MUTATION_REPLAY_WINDOW_MS: number;
 /** Scope-less records written by the first aggregate-journal release. */
 export declare const legacyPendingMutationRecordSchema: z.ZodObject<{
-    storageVersion: z.ZodLiteral<1>;
     id: z.ZodString;
     type: z.ZodLiteral<"pending_mutation">;
     mutation: z.ZodObject<{
         type: z.ZodEnum<{
-            update: "update";
+            archive: "archive";
             create: "create";
             delete: "delete";
-            archive: "archive";
+            update: "update";
         }>;
         modelData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         modelName: z.ZodString;
@@ -168,22 +167,17 @@ export declare const legacyPendingMutationRecordSchema: z.ZodObject<{
         mutationId: z.ZodString;
     }, z.core.$loose>;
     timestamp: z.ZodNumber;
+    storageVersion: z.ZodLiteral<1>;
 }, z.core.$strict>;
 export declare const pendingMutationRecordSchema: z.ZodObject<{
-    storageVersion: z.ZodLiteral<2>;
-    scope: z.ZodObject<{
-        organizationId: z.ZodString;
-        participantId: z.ZodString;
-        namespace: z.ZodString;
-    }, z.core.$strict>;
     id: z.ZodString;
     type: z.ZodLiteral<"pending_mutation">;
     mutation: z.ZodObject<{
         type: z.ZodEnum<{
-            update: "update";
+            archive: "archive";
             create: "create";
             delete: "delete";
-            archive: "archive";
+            update: "update";
         }>;
         modelData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         modelName: z.ZodString;
@@ -210,6 +204,12 @@ export declare const pendingMutationRecordSchema: z.ZodObject<{
         mutationId: z.ZodString;
     }, z.core.$loose>;
     timestamp: z.ZodNumber;
+    storageVersion: z.ZodLiteral<2>;
+    scope: z.ZodObject<{
+        organizationId: z.ZodString;
+        participantId: z.ZodString;
+        namespace: z.ZodString;
+    }, z.core.$strict>;
 }, z.core.$strict>;
 export type PendingMutationRecord = z.infer<typeof pendingMutationRecordSchema>;
 export declare function pendingMutationRecordId(mutationId: string): string;

package/dist/react/AbloProvider.js

@@ -1,5 +1,5 @@
 'use client';
-import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 import { useCallback, useContext, useEffect, useMemo, useRef, useState, createContext, } from 'react';
 import { createParticipantClaimId, parseParticipantTtlSeconds, resolveParticipantSyncGroups, } from '../local/sync/participants.js';
 import { SyncContext } from './context.js';

package/dist/react/ClientSideSuspense.d.ts

@@ -33,4 +33,4 @@ export interface ClientSideSuspenseProps {
     /** What to render once the subtree is cleared to render. */
     children: ReactNode;
 }
-export declare function ClientSideSuspense({ fallback, children }: ClientSideSuspenseProps): import("react").JSX.Element;
+export declare function ClientSideSuspense({ fallback, children }: ClientSideSuspenseProps): import("react/jsx-runtime").JSX.Element;

package/dist/react/DefaultFallback.d.ts

@@ -21,4 +21,4 @@
  * pass `fallback={null}`. Consumers who want to skip the gate entirely
  * pass `fallback="passthrough"`.
  */
-export declare function DefaultFallback(): import("react").JSX.Element;
+export declare function DefaultFallback(): import("react/jsx-runtime").JSX.Element;

package/dist/react/createAbloReact.js

@@ -38,7 +38,7 @@ export function createAbloReact(schema) {
     // implementation's internal-context fallback.
     const BoundClientContext = createContext(null);
     function BoundAbloProvider(props) {
-        return createElement(BoundClientContext.Provider, { value: props.client }, createElement((AbloProvider), props));
+        return createElement(BoundClientContext.Provider, { value: props.client }, createElement(AbloProvider, props));
     }
     function useBoundAblo(modelOrSelect, id, options) {
         const bound = useContext(BoundClientContext);

package/dist/surface.d.ts

@@ -19,18 +19,18 @@
  * tuple, so it is the one list of model-verb names a generated summary can
  * describe.
  */
-export declare const PUBLIC_MODEL_VERBS: readonly ["get", "read", "list", "listAll", "local", "create", "update", "delete", "claim", "join", "onChange"];
+export declare const PUBLIC_MODEL_VERBS: readonly ['get', 'read', 'list', 'listAll', 'local', 'create', 'update', 'delete', 'claim', 'join', 'onChange'];
 /**
  * The option keys accepted by `local.list` and `onChange`, matching the
  * keys of {@link LocalReadOptions}. Note that the lifecycle filter is named
  * `state`, not `scope`.
  */
-export declare const PUBLIC_LIST_OPTION_KEYS: readonly ["where", "filter", "orderBy", "limit", "offset", "state"];
+export declare const PUBLIC_LIST_OPTION_KEYS: readonly ['where', 'filter', 'orderBy', 'limit', 'offset', 'state'];
 /**
  * The keys of the client constructor options, {@link AbloOptions}. Only
  * `schema` is required; every other key is optional.
  */
-export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "projectId", "branchId", "authEndpoint", "authTimeoutMs", "allowCrossOriginAuthEndpoint", "persistence", "durableWrites", "commitOutbox", "commitOutboxScope", "debug", "logLevel", "logger", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser", "collaborationEvents", "plugins"];
+export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ['schema', 'apiKey', 'projectId', 'branchId', 'authEndpoint', 'authTimeoutMs', 'allowCrossOriginAuthEndpoint', 'persistence', 'durableWrites', 'commitOutbox', 'commitOutboxScope', 'debug', 'logLevel', 'logger', 'authToken', 'baseURL', 'fetch', 'defaultHeaders', 'defaultQuery', 'dangerouslyAllowBrowser', 'collaborationEvents', 'plugins'];
 export type ModelVerb = (typeof PUBLIC_MODEL_VERBS)[number];
 export type ListOptionKey = (typeof PUBLIC_LIST_OPTION_KEYS)[number];
 export type AbloOptionKey = (typeof PUBLIC_ABLO_OPTION_KEYS)[number];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.59.1",
+  "version": "0.59.2",
   "description": "The optional human-facing local-state package for Ablo: presence, live queries, and React bindings.",
   "license": "Apache-2.0",
   "type": "module",
@@ -84,7 +84,7 @@
     "directory": "packages/humans"
   },
   "dependencies": {
-    "@abloatai/transaction": "^0.59.1",
+    "@abloatai/transaction": "^0.59.2",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",
     "zod": "^4.4.3"

package/src/local/BaseSyncedStore.ts

@@ -1578,7 +1578,6 @@ export class BaseSyncedStore<
       acknowledge: (syncId) => { this.syncWebSocket.acknowledge(syncId); },
       get objectPool() { return store.objectPool; },
       // Dynamic-dispatch hooks — protected override points on this class.
-      getStateFields: (modelName) => this.getStateFields(modelName),
       isCustomEntity: (modelName) => this.isCustomEntity(modelName),
       createCustomEntity: (modelName, modelId, data) =>
         this.createCustomEntity(modelName, modelId, data),
@@ -1607,14 +1606,9 @@ export class BaseSyncedStore<
     );
   }
 
-  /** Get fields that represent meaningful state for deduplication. Override for model-specific fields. */
-  protected getStateFields(_modelName: string): string[] {
-    return ['status', 'state', 'isActive'];
-  }
-
-  /** Deduplicate deltas to the same entity — keep meaningful state transitions only */
+  /** Deduplicate repeated delivery of the same positive sync id. */
   protected deduplicateDeltas(deltas: SyncDelta[]): SyncDelta[] {
-    return deltaPipeline.deduplicateDeltas(this.deltaPipelineContext, deltas);
+    return deltaPipeline.deduplicateDeltas(deltas);
   }
 
   /** Process incoming delta with smart batching */

package/src/local/Model.ts

@@ -412,7 +412,7 @@ export abstract class Model {
     opts?: { fallbackToLive?: boolean },
   ): ModelData {
     const out: ModelData = {};
-    const modified = this.modifiedProperties instanceof Map ? this.modifiedProperties : null;
+    const modified = this.modifiedProperties;
     const original = this.getOriginalSnapshot();
     for (const key of keys) {
       if (key === 'id') continue;
@@ -438,7 +438,7 @@ export abstract class Model {
    * is never consumed. With no `keys`, consumes every tracked field.
    */
   consumeModifiedFields(keys?: Iterable<string>): void {
-    if (!(this.modifiedProperties instanceof Map) || this.modifiedProperties.size === 0) {
+    if (this.modifiedProperties.size === 0) {
       return;
     }
     const only = keys ? new Set(keys) : null;

package/src/local/SyncClient.ts

@@ -13,7 +13,7 @@ import { InstanceCache, ModelScope } from './InstanceCache.js';
 import { Model } from './Model.js';
 import type { ModelData } from '@abloatai/transaction/types/modelData';
 import type { AppliedChange } from '../plugin.js';
-import { snapshotJsonValue } from '@abloatai/transaction/utils/json';
+import { deepEqual, snapshotJsonValue } from '@abloatai/transaction/utils/json';
 // ModelRegistry instance accessed via this.objectPool.registry
 import { LoadStrategy } from '@abloatai/transaction/types';
 import { globalRuntime } from './context.js';
@@ -1938,6 +1938,27 @@ export class SyncClient extends EventEmitter {
       // otherwise re-add it for the brief window before the matching delete
       // confirmation lands.
       if (this.echoTracker.consumeEcho(transactionId)) {
+        // A direct assignment can re-enter change tracking while this
+        // optimistic write is in flight. Leaving the acknowledged field dirty
+        // makes conflict resolution preserve it over the next collaborator
+        // delta, so peers appear desynchronized until refresh.
+        //
+        // Re-baseline only values this echo actually confirms. If the user has
+        // edited the same field again since the write was sent, its current
+        // dirty value differs from the echo and remains queued.
+        if (resident && result.data) {
+          const acknowledgedFields: string[] = [];
+          for (const [field, change] of resident.modifiedProperties) {
+            if (
+              Object.prototype.hasOwnProperty.call(result.data, field) &&
+              deepEqual(change.new, result.data[field])
+            ) {
+              acknowledgedFields.push(field);
+            }
+          }
+          resident.consumeModifiedFields(acknowledgedFields);
+          resident.markAsSynced();
+        }
         continue;
       }
 

package/src/local/sync/SyncWebSocket.ts

@@ -319,7 +319,7 @@ export class SyncWebSocket<
   /**
    * Public wrapper for sending ack from outside the class
    */
-  acknowledge(syncId: number): void {
+  override acknowledge(syncId: number): void {
     this.sendAck(syncId);
   }
 

package/src/local/sync/deltaPipeline.ts

@@ -102,7 +102,6 @@ export interface DeltaPipelineContext {
   };
 
   // ── Dynamic-dispatch hooks back into the store (protected override points) ──
-  getStateFields(modelName: string): string[];
   isCustomEntity(modelName: string): boolean;
   createCustomEntity(modelName: string, modelId: string, data: Record<string, unknown>): Model | null;
   deduplicateDeltas(deltas: SyncDelta[]): SyncDelta[];
@@ -159,91 +158,36 @@ export function handleGroupHandlerFailure(
   }
 }
 
-/** Builds a small signature of a delta's state fields, used to detect no-op duplicate deltas. */
-function extractStateSignature(
-  ctx: DeltaPipelineContext,
-  delta: SyncDelta,
-): Record<string, unknown> | null {
-  if (!delta.data || typeof delta.data !== 'object') return null;
-
-  const data = typeof delta.data === 'string'
-    ? (JSON.parse(delta.data) as Record<string, unknown>)
-    : (delta.data);
-
-  // Generic state fields — subclasses can override getStateFields() for model-specific fields
-  const fieldsToCheck = ctx.getStateFields(delta.modelName);
-  const signature: Record<string, unknown> = {
-    actionType: delta.actionType,
-    modelName: delta.modelName,
-  };
-
-  for (const field of fieldsToCheck) {
-    if (field in data) signature[field] = data[field];
-  }
-
-  return signature;
-}
-
-function isSameState(a: Record<string, unknown> | null, b: Record<string, unknown> | null): boolean {
-  if (!a || !b) return false;
-  const keys = Object.keys(a);
-  if (keys.length !== Object.keys(b).length) return false;
-  return keys.every((k) => a[k] === b[k]);
-}
+/**
+ * Deduplicate repeated delivery of the same log entry.
+ *
+ * A row may legitimately change several times in one receive frame. Those
+ * changes are ordered facts, even when a small subset of fields (such as
+ * `status`) happens to remain equal. Collapsing by entity or a partial state
+ * signature can therefore discard the newest row image while the cursor still
+ * advances past it. Only an identical positive sync id proves duplicate
+ * delivery; non-positive ids carry no usable log identity and stay untouched.
+ */
+export function deduplicateDeltas(deltas: SyncDelta[]): SyncDelta[] {
+  if (deltas.length < 2 || deltas.some((delta) => delta.id <= 0)) return deltas;
 
-/** Deduplicate deltas to the same entity — keep meaningful state transitions only */
-export function deduplicateDeltas(ctx: DeltaPipelineContext, deltas: SyncDelta[]): SyncDelta[] {
-  // The dominant live-publication shape is a frame of independent entity
-  // creates. When every entity key occurs once, reconciliation cannot remove
-  // or reorder anything: preserve the already commit-ordered input directly
-  // and avoid allocating a bucket array, state signature, and two sorts per
-  // delta. The first duplicate falls through to the full transition logic.
-  const uniqueEntities = new Set<string>();
-  let hasDuplicateEntity = false;
-  for (const delta of deltas) {
-    const key = `${delta.modelName}:${delta.modelId}`;
-    if (uniqueEntities.has(key)) {
-      hasDuplicateEntity = true;
+  let strictlyOrdered = true;
+  for (let index = 1; index < deltas.length; index += 1) {
+    if (deltas[index - 1]!.id >= deltas[index]!.id) {
+      strictlyOrdered = false;
       break;
     }
-    uniqueEntities.add(key);
-  }
-  if (!hasDuplicateEntity) return deltas;
-
-  const byEntity = new Map<string, SyncDelta[]>();
-  for (const d of deltas) {
-    const key = `${d.modelName}:${d.modelId}`;
-    if (!byEntity.has(key)) byEntity.set(key, []);
-    byEntity.get(key)!.push(d);
-  }
-
-  const result: SyncDelta[] = [];
-  for (const entityDeltas of byEntity.values()) {
-    const sorted = entityDeltas.sort((a, b) => a.id - b.id);
-
-    // DELETE wins — it's the final state
-    const del = sorted.find((d) => d.actionType === 'D');
-    if (del) { result.push(del); continue; }
-
-    // Keep deltas that represent different states
-    const unique: SyncDelta[] = [];
-    let prev: Record<string, unknown> | null = null;
-    for (const d of sorted) {
-      const sig = extractStateSignature(ctx, d);
-      if (!isSameState(prev, sig)) { unique.push(d); prev = sig; }
-    }
-
-    if (unique.length > 0) {
-      result.push(...unique);
-    } else {
-      // `sorted` is never empty (every byEntity bucket gets at least one
-      // delta pushed) — the guard only narrows the indexed access.
-      const last = sorted.at(-1);
-      if (last) result.push(last);
-    }
   }
-
-  return result.sort((a, b) => a.id - b.id);
+  if (strictlyOrdered) return deltas;
+
+  const seen = new Set<number>();
+  return [...deltas]
+    .sort((a, b) => a.id - b.id)
+    .filter((delta) => {
+      if (seen.has(delta.id)) return false;
+      seen.add(delta.id);
+      return true;
+    });
 }
 
 /**

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

@@ -2,8 +2,8 @@ import type { RuntimeContext } from '../../RuntimeContext.js';
 import type { MutationQueueConfig } from './MutationQueue.js';
 import type { QueuedMutation } from './commitPayload.js';
 import type { MutationStore } from './MutationStore.js';
-import { AbloError } from '@abloatai/transaction/errors';
 import { extractStatusCode } from './commitPayload.js';
+import { reportPermanentMutationFailure } from './failureReporting.js';
 
 export interface FailureHandlingContext {
   readonly runtime: RuntimeContext;
@@ -13,7 +13,11 @@ export interface FailureHandlingContext {
   >;
   readonly store: MutationStore;
   readonly isPermanentError: (error: Error) => boolean;
-  readonly rollbackOptimistic: (transaction: QueuedMutation, reason: string, error?: Error) => Promise<void>;
+  readonly rollbackOptimistic: (
+    transaction: QueuedMutation,
+    reason: string,
+    error?: Error,
+  ) => Promise<void>;
   readonly enqueue: (transaction: QueuedMutation) => void;
   readonly getLastPermanentErrorSignature: () => string | undefined;
   readonly setLastPermanentErrorSignature: (signature: string) => void;
@@ -35,138 +39,75 @@ export function transientRetryDelayMs(
   return Math.floor(Math.random() * ceiling);
 }
 
-export async function handleFailure(ctx: FailureHandlingContext, transaction: QueuedMutation, error: Error): Promise<void> {
-    transaction.attempts++;
-
-    // Check whether this is a permanent error that should not be retried.
-    if (ctx.isPermanentError(error)) {
-      // Logged at warn: a permanent error means the server rejected the write,
-      // so the developer should see the reason in the console. The typed
-      // AbloError fields (`type`, `code`, `httpStatus`) are included so the
-      // cause is visible — for example a foreign-key violation
-      // (AbloValidationError) versus expired authentication
-      // (AbloAuthenticationError).
-      try {
-        const abloErr = error instanceof AbloError ? error : undefined;
-        const details = {
-          txId: transaction.id.slice(0, 8),
-          type: transaction.type,
-          model: transaction.modelName,
-          modelId: transaction.modelId.slice(0, 12),
-          errorType: abloErr?.type ?? error?.name,
-          errorCode: abloErr?.code,
-          httpStatus: abloErr?.httpStatus,
-          requestId: abloErr?.requestId,
-          message: error?.message,
-          inputKeys: transaction.data ? Object.keys(transaction.data) : undefined,
-        };
-
-        // A `create` whose id already exists is the benign idempotency case:
-        // "this row is already there." It's the least alarming permanent
-        // error, so it doesn't warrant a `warn` — `info` keeps it visible
-        // without crying wolf. Everything else (FK violation, auth expiry,
-        // server 500) stays at `warn`.
-        const isBenignIdempotent =
-          transaction.type === 'create' &&
-          (abloErr?.code === 'unique_violation' ||
-            abloErr?.type === 'AbloIdempotencyError');
-
-        // Demote exact repeats (same write rejected for the same reason on
-        // each reconnect replay) to `debug` so the loop logs once.
-        const sig = `${details.type}:${details.model}:${details.modelId}:${details.errorCode ?? details.errorType}`;
-        const isRepeat = sig === ctx.getLastPermanentErrorSignature();
-        ctx.setLastPermanentErrorSignature(sig);
-
-        const logger = ctx.runtime.logger;
-
-        // Two registers from one call site, split by log level (the default
-        // logger is gated at `warn`, so `debug` stays hidden unless
-        // ABLO_LOG_LEVEL=debug is set to inspect the engine):
-        //   - the default-visible line speaks the application developer's
-        //     language: their verb (such as `update`), their model, the typed
-        //     error's own message, and the wire `code` for searching. It uses
-        //     no engine jargon and prints no JSON dump, which would alarm
-        //     without helping.
-        //   - the forensic `details` ride a companion `debug` line for anyone
-        //     debugging the engine internals.
-        const revertNote = ctx.config.enableOptimistic
-          ? ' The local change was reverted.'
-          : '';
-        const reason = abloErr?.message ? ` — ${abloErr.message}` : '';
-        const code = abloErr?.code ? ` (code: ${abloErr.code})` : '';
-        const requestRef = abloErr?.requestId
-          ? ` [request_id: ${abloErr.requestId}]`
-          : '';
-        // An optimistic write resolves before the server answers, so a later
-        // rejection has no caller left to return to and this log is the only
-        // place it appears. That reads to an application developer as their own
-        // save silently failing — the write showed, then vanished — and sends
-        // them into their editor instead of here. Name the subscription that
-        // hands them the same typed error, so the application can say what
-        // happened rather than only the console.
-        const channelNote = ctx.config.enableOptimistic
-          ? ' To surface this in your app, subscribe with `ablo.onMutationFailure(…)`.'
-          : '';
-        const headline = `Your ${transaction.type} to "${transaction.modelName}" was not saved${reason}${code}${requestRef}.${revertNote}${channelNote}`;
-
-        if (isRepeat) {
-          // Same write rejected for the same reason on each reconnect replay —
-          // log the forensics once, stay quiet after.
-          logger.debug('write rejected again (same reason)', details);
-        } else if (isBenignIdempotent) {
-          // Already-exists on a `create` is expected on replay, not a problem.
-          logger.info(`Your ${transaction.type} to "${transaction.modelName}" was skipped — this row already exists.`);
-          logger.debug('idempotent skip — details', details);
-        } else {
-          logger.warn(headline);
-          logger.debug('write rejection — details', details);
-        }
-      } catch {}
-
-      // Mark as failed immediately and rollback
-      ctx.store.updateStatus(transaction.id, 'failed');
-
-      if (ctx.config.enableOptimistic) {
-        await ctx.rollbackOptimistic(transaction, 'permanent_error', error);
-      }
-
-      ctx.emit('transaction:failed', { transaction, error, permanent: true });
-      // The id-suffixed event is what the awaited model-write promise listens
-      // on through `waitForConfirmation` — without it a permanently
-      // rejected write left the caller's promise hanging forever.
-      ctx.emit(`transaction:failed:${transaction.id}`, { error });
-      return;
+export async function handleFailure(
+  ctx: FailureHandlingContext,
+  transaction: QueuedMutation,
+  error: Error,
+): Promise<void> {
+  transaction.attempts++;
+
+  // Check whether this is a permanent error that should not be retried.
+  if (ctx.isPermanentError(error)) {
+    reportPermanentMutationFailure(
+      {
+        runtime: ctx.runtime,
+        enableOptimistic: ctx.config.enableOptimistic,
+        getLastPermanentErrorSignature: ctx.getLastPermanentErrorSignature,
+        setLastPermanentErrorSignature: ctx.setLastPermanentErrorSignature,
+      },
+      transaction,
+      error,
+    );
+
+    // Mark as failed immediately and rollback
+    ctx.store.updateStatus(transaction.id, 'failed');
+
+    if (ctx.config.enableOptimistic) {
+      await ctx.rollbackOptimistic(transaction, 'permanent_error', error);
     }
 
-    transaction.firstTransientFailureAt ??= Date.now();
-    const insideAvailabilityWindow =
-      Date.now() - transaction.firstTransientFailureAt < ctx.config.availabilityRetryWindowMs;
-
-    if (transaction.attempts < ctx.config.maxRetries || insideAvailabilityWindow) {
-      // Exponential backoff with full jitter on every transient retry:
-      // `sleep = random(0, min(cap, base * 2^attempt))`. Throttling responses
-      // (429/503) use a longer base than other transient errors. The re-enqueue
-      // is scheduled rather than awaited, so one backing-off transaction cannot
-      // stall unrelated commits.
-      const delay = transientRetryDelayMs(error, transaction.attempts, ctx.config.retryBackoff);
-
-      ctx.store.updateStatus(transaction.id, 'pending');
-      setTimeout(() => {
-        // The queue may have shut down or the tx may have been settled
-        // (e.g. delta-confirmed) while we backed off.
-        if (ctx.store.get(transaction.id)?.status !== 'pending') return;
-        ctx.enqueue(transaction);
-      }, delay);
-    } else {
-      // Mark as failed and rollback
-      ctx.store.updateStatus(transaction.id, 'failed');
-
-      if (ctx.config.enableOptimistic) {
-        await ctx.rollbackOptimistic(transaction, 'max_retries_exhausted', error);
-      }
+    ctx.emit('transaction:failed', { transaction, error, permanent: true });
+    // The id-suffixed event is what the awaited model-write promise listens
+    // on through `waitForConfirmation` — without it a permanently
+    // rejected write left the caller's promise hanging forever.
+    ctx.emit(`transaction:failed:${transaction.id}`, { error });
+    return;
+  }
 
-      ctx.emit('transaction:failed', { transaction, error });
-      // Settle `waitForConfirmation` waiters (see the permanent branch above).
-      ctx.emit(`transaction:failed:${transaction.id}`, { error });
+  transaction.firstTransientFailureAt ??= Date.now();
+  const insideAvailabilityWindow =
+    Date.now() - transaction.firstTransientFailureAt <
+    ctx.config.availabilityRetryWindowMs;
+
+  if (transaction.attempts < ctx.config.maxRetries || insideAvailabilityWindow) {
+    // Exponential backoff with full jitter on every transient retry:
+    // `sleep = random(0, min(cap, base * 2^attempt))`. Throttling responses
+    // (429/503) use a longer base than other transient errors. The re-enqueue
+    // is scheduled rather than awaited, so one backing-off transaction cannot
+    // stall unrelated commits.
+    const delay = transientRetryDelayMs(
+      error,
+      transaction.attempts,
+      ctx.config.retryBackoff,
+    );
+
+    ctx.store.updateStatus(transaction.id, 'pending');
+    setTimeout(() => {
+      // The queue may have shut down or the tx may have been settled
+      // (e.g. delta-confirmed) while we backed off.
+      if (ctx.store.get(transaction.id)?.status !== 'pending') return;
+      ctx.enqueue(transaction);
+    }, delay);
+  } else {
+    // Mark as failed and rollback
+    ctx.store.updateStatus(transaction.id, 'failed');
+
+    if (ctx.config.enableOptimistic) {
+      await ctx.rollbackOptimistic(transaction, 'max_retries_exhausted', error);
     }
+
+    ctx.emit('transaction:failed', { transaction, error });
+    // Settle `waitForConfirmation` waiters (see the permanent branch above).
+    ctx.emit(`transaction:failed:${transaction.id}`, { error });
   }
+}