@abloatai/humans 0.45.0 → 0.47.0

package/dist/local/BaseSyncedStore.d.ts

@@ -32,6 +32,7 @@ import type { EnrichmentPlanEntry, ForeignKeyIndexSpec } from './sync/syncPlan.j
 import { type CredentialRefresher } from './sync/credentialLifecycle.js';
 import type { RehydrationStats } from './sync/bootstrapApply.js';
 import type { ParticipantKind } from '@abloatai/transaction/types/participant';
+import type { DeliveryPartitionRoute } from '@abloatai/transaction/auth/deliveryPartition';
 import type { QueuedMutation } from './transactions/mutations/MutationQueue.js';
 import type { CommitLatencySample } from './transactions/mutations/commitLatency.js';
 /** Constructor type for Model subclasses (accepts abstract classes) */
@@ -90,6 +91,8 @@ export interface UserContext {
     branchId: string;
     /** True only when branchId is the project's production root. */
     branchRoot?: boolean;
+    /** Server-resolved WebSocket gateway route; never an authorization claim. */
+    deliveryPartition?: DeliveryPartitionRoute | null;
     role?: string;
     teamIds?: string[];
     /** Participant kind on the wire. Default 'user' for browser

package/dist/local/BaseSyncedStore.js

@@ -1067,6 +1067,7 @@ export class BaseSyncedStore {
         }
         const syncGroups = this.resolveSyncGroups(context);
         this.syncWebSocket.setSyncGroups(syncGroups);
+        this.syncWebSocket.setDeliveryPartition(context.deliveryPartition ?? null);
         this.syncWebSocket.setLastSyncId(lastSyncId || 0);
         // The permanent base scopes for read interest — same set the connection
         // subscribes to at upgrade, so the two can never disagree.

package/dist/local/client/clientPrelude.js

@@ -22,8 +22,12 @@ import { createConsoleLogger, resolveLogLevel } from './consoleLogger.js';
  * different project than the one being addressed (a warning, not a throw).
  */
 export function resolveClientPrelude(options) {
-    const internalOptions = options;
     const env = readProcessEnv();
+    const internalOptions = {
+        ...options,
+        projectId: options.projectId ?? env.ABLO_PROJECT_ID,
+        branchId: options.branchId ?? env.ABLO_BRANCH_ID,
+    };
     const authInput = { options, env };
     const configuredApiKey = resolveApiKey(authInput);
     const configuredAuthToken = resolveAuthToken(authInput);

package/dist/local/client/createModelProxy.d.ts

@@ -245,6 +245,4 @@ export declare function createModelProxy<T, C>(schemaKey: string, registeredMode
  * collaborator, a test most of all, is pushed into a cast through `unknown`
  * to supply the one method that is actually read.
  */
-hydration: Pick<OnDemandLoader, 'fetch'>, collaboration?: ModelCollaboration, 
-/** The client-wide `wait` default; a per-call `wait` still wins over it. */
-defaultWait?: 'queued' | 'confirmed'): ModelOperations<T, C>;
+hydration: Pick<OnDemandLoader, 'fetch'>, collaboration?: ModelCollaboration): ModelOperations<T, C>;

package/dist/local/client/createModelProxy.js

@@ -43,9 +43,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
  * collaborator, a test most of all, is pushed into a cast through `unknown`
  * to supply the one method that is actually read.
  */
-hydration, collaboration, 
-/** The client-wide `wait` default; a per-call `wait` still wins over it. */
-defaultWait) {
+hydration, collaboration) {
     /**
      * Resolve a row **this** resource owns.
      *
@@ -100,17 +98,30 @@ defaultWait) {
             }
         };
     };
+    const guardWrite = (fn) => {
+        const guarded = guard(fn);
+        return (...args) => {
+            const confirmation = guarded(...args);
+            // Optimistic writes are intentionally useful without awaiting them. The
+            // transaction pipeline already reports a later refusal through
+            // `onMutationFailure`; attach an observer here as well so choosing not to
+            // await does not create an unhandled-rejection process error. Returning
+            // the original promise preserves normal rejection for callers that do
+            // await or attach their own catch handler.
+            void confirmation.catch(() => undefined);
+            return confirmation;
+        };
+    };
     const load = async (options) => {
         const rows = await hydration.fetch(schemaKey, options);
         return rows.map((row) => modelAsRow(row));
     };
-    const waitForMutation = async (model, options) => {
-        // A per-call `wait` wins; otherwise the client-wide default decides. This
-        // is the single point that turns "confirmed" into actually waiting, so a
-        // client configured that way rejects on a refused write everywhere rather
-        // than in the one place a caller remembered to ask.
-        if ((options?.wait ?? defaultWait) !== 'confirmed')
-            return;
+    const waitForMutation = async (model) => {
+        // Model writes are optimistic locally, but their promise has one stable
+        // meaning: authoritative confirmation. Callers that do not need the
+        // barrier can keep using the row immediately and leave the promise to the
+        // global mutation-failure handler; awaiting the promise never means merely
+        // "placed in the local queue".
         // Let sibling writes from the same synchronous burst enter the mutation
         // queue before forcing a drain. Without this yield, every confirmed
         // create/update calls syncNow() alone, defeating the queue's microtask
@@ -147,7 +158,6 @@ defaultWait) {
                 ? { idempotencyKey: params.idempotencyKey }
                 : {}),
             ...(params.label !== undefined ? { label: params.label } : {}),
-            ...(params.wait !== undefined ? { wait: params.wait } : {}),
             ...(params.readAt !== undefined ? { readAt: params.readAt } : {}),
             ...(params.onStale !== undefined ? { onStale: params.onStale } : {}),
             ...(params.fenceToken !== undefined ? { fenceToken: params.fenceToken } : {}),
@@ -614,7 +624,7 @@ defaultWait) {
         // No automatic scope enrolment on bulk `list`: that would subscribe to an
         // unbounded set of rows' entity groups.
         list: guard(load),
-        create: guard(async (params) => {
+        create: guardWrite(async (params) => {
             const id = params.id ?? Model.generateId();
             const opts = mutationOptions(params);
             const claim = params.claim;
@@ -665,7 +675,7 @@ defaultWait) {
             };
             try {
                 syncClient.add(model, effective);
-                await waitForMutation(model, effective);
+                await waitForMutation(model);
                 return modelAsRow(model);
             }
             finally {
@@ -677,7 +687,7 @@ defaultWait) {
         // wrapping while exposing the two public signatures (a plain `guard(...)`
         // would collapse them to one).
         update: (() => {
-            const updateImpl = guard(async (arg, updater, contention) => {
+            const updateImpl = guardWrite(async (arg, updater, contention) => {
                 // Functional form: update(id, current => next). Same guarantee as the
                 // HTTP client (shared reconcile loop), implemented with this transport's
                 // own read-fresh + confirmed compare-and-swap. A forced server round-trip
@@ -715,13 +725,12 @@ defaultWait) {
                                 throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
                             }
                             const effective = {
-                                wait: 'confirmed',
                                 readAt,
                                 onStale: 'reject',
                             };
                             model.applyChanges(patch);
                             syncClient.update(model, effective);
-                            await waitForMutation(model, effective);
+                            await waitForMutation(model);
                             return modelAsRow(model);
                         },
                     });
@@ -753,7 +762,6 @@ defaultWait) {
                 const handle = isClaimHandle(params.claim) ? params.claim : undefined;
                 const effective = claimed
                     ? {
-                        wait: 'confirmed',
                         readAt: claimed.lease.readAt ?? claimed.snapshot.stamp,
                         onStale: 'reject',
                         claimRef: { id: claimed.lease.id },
@@ -765,7 +773,6 @@ defaultWait) {
                         // works across clients (HTTP-minted handles included).
                         ...(handle?.readAt !== undefined
                             ? {
-                                wait: 'confirmed',
                                 readAt: handle.readAt,
                                 onStale: 'reject',
                                 ...(handle.fenceToken !== undefined
@@ -782,7 +789,7 @@ defaultWait) {
                 // the tracking, producing an empty `input: {}` no-op mutation.)
                 model.applyChanges(params.data);
                 syncClient.update(model, effective);
-                await waitForMutation(model, effective);
+                await waitForMutation(model);
                 return modelAsRow(model);
             });
             function update(arg, updater, contention) {
@@ -790,7 +797,7 @@ defaultWait) {
             }
             return update;
         })(),
-        delete: guard(async (params) => {
+        delete: guardWrite(async (params) => {
             const autoClaim = params.claim && !isClaimHandle(params.claim) ? params.claim : null;
             if (autoClaim) {
                 const handle = await takeClaim({ ...autoClaim, id: params.id });
@@ -823,7 +830,6 @@ defaultWait) {
             const handle = isClaimHandle(params.claim) ? params.claim : undefined;
             const effective = claimed
                 ? {
-                    wait: 'confirmed',
                     readAt: claimed.lease.readAt ?? claimed.snapshot.stamp,
                     onStale: 'reject',
                     claimRef: { id: claimed.lease.id },
@@ -835,7 +841,6 @@ defaultWait) {
                 : {
                     ...(handle?.readAt !== undefined
                         ? {
-                            wait: 'confirmed',
                             readAt: handle.readAt,
                             onStale: 'reject',
                         }
@@ -844,7 +849,7 @@ defaultWait) {
                     ...(handle ? { claim: { id: handle.id } } : {}),
                 };
             syncClient.delete(model, effective);
-            await waitForMutation(model, effective);
+            await waitForMutation(model);
         }),
         // `claim` is a callable namespace (take a claim) carrying the coordination
         // readers (`claim.state` / `claim.queue` / `claim.release` / `claim.reorder`).

package/dist/local/client/options.d.ts

@@ -68,6 +68,19 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * this for you: only a structured `401 session_expired` means signed out.
      */
     apiKey?: string | CredentialProvider | null | undefined;
+    /**
+     * Pins this client to one Ablo project. During `ready()` the server resolves
+     * the API key's actual project and the client refuses to start when it differs.
+     * Defaults to `ABLO_PROJECT_ID`; `ablo dev` writes that value beside the key.
+     * This is an assertion, never a routing selector — the key remains authoritative.
+     */
+    projectId?: string | null | undefined;
+    /**
+     * Pins this client to one immutable Ablo branch. Defaults to
+     * `ABLO_BRANCH_ID`; `ablo dev` writes it beside the branch key. Like
+     * `projectId`, this is a startup assertion and never selects a branch.
+     */
+    branchId?: string | null | undefined;
     /**
      * The session-mint endpoint — the browser-side auth field, and the named
      * endpoint for the route that mints the signed-in user's short-lived token:
@@ -192,33 +205,6 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * session token (`ek_`/`rk_`) or you route through a controlled server proxy.
      */
     dangerouslyAllowBrowser?: boolean | undefined;
-    /**
-     * How far a write goes before its promise settles, for every model write on
-     * this client. The same word each write already takes per call
-     * (`create({ …, wait: 'confirmed' })`); setting it here makes it the default
-     * instead of repeating it.
-     *
-     * A write resolves as soon as it is applied locally and queued. That is what
-     * makes the UI immediate, and it is right for most writes — but it means a
-     * write the server later REFUSES has no caller left to tell. The rejection
-     * reverts the local row and reaches `ablo.onMutationFailure(…)`, and an
-     * application that subscribes to neither shows the change, then loses it,
-     * with nothing thrown anywhere.
-     *
-     * ```ts
-     * const ablo = new Ablo({ schema, apiKey, wait: 'confirmed' });
-     * try {
-     *   await ablo.documents.update({ id, data });   // throws if refused
-     * } catch (err) {
-     *   if (err instanceof AbloError) show(err.message);
-     * }
-     * ```
-     *
-     * The cost is real: each write now waits for the server's answer, so it is a
-     * choice between immediacy and certainty rather than a strict improvement.
-     * A per-call `wait` still wins over this.
-     */
-    wait?: 'queued' | 'confirmed' | undefined;
 }
 export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
     /**
@@ -233,6 +219,8 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * the original available as `cause`.
      */
     apiKey?: string | CredentialProvider | null | undefined;
+    /** Expected project assertion; see {@link AbloOptions.projectId}. */
+    projectId?: string | null | undefined;
     /**
      * Session-mint endpoint (string or async resolver) — see
      * {@link AbloOptions.authEndpoint}. Mutually exclusive with `apiKey`.
@@ -435,13 +423,10 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     organizationId?: string;
     /**
-     * Immutable branch selected by a self-hosted credential. Hosted clients
-     * receive this from the credential exchange.
+     * Expected immutable branch. Hosted clients compare it with the credential
+     * exchange; self-hosted clients use it as their locally selected branch.
      */
     branchId?: string;
     /** Whether the selected self-hosted branch is the project's root branch. */
     branchRoot?: boolean;
-    /** The client-wide write default — see {@link AbloOptions.wait}. Projected
-     *  from the public option rather than restated, so the two cannot diverge. */
-    wait?: AbloOptions['wait'];
 }

package/dist/local/client/reactiveEngine.js

@@ -429,9 +429,7 @@ export function buildReactiveEngine(inputs) {
                 scope: { [modelKey]: ids },
                 ...(options?.ttl !== undefined ? { ttl: options.ttl } : {}),
             }),
-        }, 
-        // The client-wide `wait` default; a per-call `wait` still wins.
-        internalOptions.wait);
+        });
     }
     const commits = {
         async create(commitOptions) {

package/dist/local/client/resourceTypes.d.ts

@@ -8,5 +8,5 @@
  * live participant handle.
  */
 export * from '@abloatai/transaction/resources/httpResources';
-export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimContentionOptions, ClaimAttemptEvent, ClaimQueueView, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease, } from '@abloatai/transaction/resources/modelOperations';
+export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelWriteOptions, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimContentionOptions, ClaimAttemptEvent, ClaimQueueView, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease, } from '@abloatai/transaction/resources/modelOperations';
 export type { ModelOperations } from './createModelProxy.js';

package/dist/local/client/storeLifecycle.d.ts

@@ -51,6 +51,10 @@ export interface StoreLifecycleDeps<S extends SchemaRecord> {
     /** Seeds resolved identity into the engine's own state: the self locals and the streams. */
     readonly onIdentityResolved: (seed: IdentitySeed) => void;
 }
+/** Refuse a credential for another project before the store opens its socket. */
+export declare function assertExpectedProject(expectedProjectId: string | null | undefined, actualProjectId: string | null): void;
+/** Refuse a credential for another branch before the store opens its socket. */
+export declare function assertExpectedBranch(expectedBranchId: string | null | undefined, actualBranchId: string | null): void;
 /**
  * Wires the credential machinery onto the cluster and returns the `ready`
  * the client exposes. Wiring happens now — the refresh lifecycle, the

package/dist/local/client/storeLifecycle.js

@@ -10,6 +10,32 @@
  */
 import { resolveParticipantIdentity } from '@abloatai/transaction/auth/identity';
 import { AbloAuthenticationError, AbloConnectionError, toAbloError, } from '@abloatai/transaction/errors';
+/** Refuse a credential for another project before the store opens its socket. */
+export function assertExpectedProject(expectedProjectId, actualProjectId) {
+    const expected = expectedProjectId?.trim();
+    if (!expected || actualProjectId === expected)
+        return;
+    throw new AbloAuthenticationError(`ABLO_API_KEY belongs to project ${actualProjectId ?? '(none)'}, but this app is pinned to ${expected} by projectId/ABLO_PROJECT_ID.`, {
+        code: 'project_scope_denied',
+        details: {
+            expectedProjectId: expected,
+            actualProjectId,
+        },
+    });
+}
+/** Refuse a credential for another branch before the store opens its socket. */
+export function assertExpectedBranch(expectedBranchId, actualBranchId) {
+    const expected = expectedBranchId?.trim();
+    if (!expected || actualBranchId === expected)
+        return;
+    throw new AbloAuthenticationError(`ABLO_API_KEY belongs to branch ${actualBranchId ?? '(none)'}, but this app is pinned to ${expected} by branchId/ABLO_BRANCH_ID.`, {
+        code: 'branch_scope_denied',
+        details: {
+            expectedBranchId: expected,
+            actualBranchId,
+        },
+    });
+}
 /**
  * Wires the credential machinery onto the cluster and returns the `ready`
  * the client exposes. Wiring happens now — the refresh lifecycle, the
@@ -107,7 +133,9 @@ export function startStoreLifecycle(deps) {
                     auth: authCredentials,
                     logger,
                 });
-                const { userId, accountScope, projectId, branchId, branchRoot, teamIds, capabilityToken, syncGroups, participantKind, } = resolved;
+                const { userId, accountScope, projectId, branchId, branchRoot, teamIds, capabilityToken, syncGroups, participantKind, deliveryPartition, } = resolved;
+                assertExpectedProject(internalOptions.projectId, projectId);
+                assertExpectedBranch(internalOptions.branchId, branchId);
                 // Fail-loud guard: detect the degenerate "no real sync groups
                 // resolved" state before opening the socket. It is the same class of bug as
                 // a sensible-looking default that's functionally broken: the
@@ -168,6 +196,7 @@ export function startStoreLifecycle(deps) {
                     kind: participantKind,
                     capabilityToken,
                     syncGroups,
+                    deliveryPartition,
                     bootstrapMode: resolvedBootstrapMode,
                 });
                 let current = gen.next();

package/dist/local/sync/createClaimStream.js

@@ -83,6 +83,28 @@ export function createClaimStream(config, transport = null) {
             }
         }
     };
+    const observeForeignClaim = (heldBy, claim, participantKind, isAgent) => {
+        const description = claim.description ??
+            descriptionFromMeta(claim.meta) ??
+            'editing';
+        const { meta, ...details } = subTarget(claim);
+        activeByClaimId.set(claim.claimId, {
+            object: 'claim',
+            id: claim.claimId,
+            status: 'active',
+            heldBy,
+            participantKind: participantKindFromWire(participantKind, isAgent),
+            target: {
+                ...streamTarget(claim),
+                ...details,
+                ...(meta !== undefined ? { meta: declaredMeta(meta) } : {}),
+            },
+            description,
+            ttlSeconds: Math.max(0, Math.floor((claim.expiresAt - Date.now()) / 1000)),
+            createdAt: claim.declaredAt,
+            expiresAt: claim.expiresAt,
+        });
+    };
     // ── Wire wiring ──────────────────────────────────────────────────
     let attached = null;
     const unsubs = [];
@@ -125,30 +147,7 @@ export function createClaimStream(config, transport = null) {
                 // `settled()`. Absent status means active (wire back-compat).
                 if (claim.status && claim.status !== 'active')
                     continue;
-                // Resolve the always-present public field, tolerating a frame that
-                // carries the value in `meta` rather than as an explicit description.
-                const description = claim.description ??
-                    descriptionFromMeta(claim.meta) ??
-                    'editing';
-                // The frame is parsed permissively, on purpose; `declaredMeta` is where
-                // that wire value becomes the shape the program declared.
-                const { meta, ...details } = subTarget(claim);
-                activeByClaimId.set(claim.claimId, {
-                    object: 'claim',
-                    id: claim.claimId,
-                    status: 'active',
-                    heldBy: event.userId,
-                    participantKind: participantKindFromWire(event.participantKind, event.isAgent),
-                    target: {
-                        ...streamTarget(claim),
-                        ...details,
-                        ...(meta !== undefined ? { meta: declaredMeta(meta) } : {}),
-                    },
-                    description,
-                    ttlSeconds: Math.max(0, Math.floor((claim.expiresAt - Date.now()) / 1000)),
-                    createdAt: claim.declaredAt,
-                    expiresAt: claim.expiresAt,
-                });
+                observeForeignClaim(event.userId, claim, event.participantKind, event.isAgent);
                 mutated = true;
             }
             if (mutated)
@@ -168,6 +167,16 @@ export function createClaimStream(config, transport = null) {
             // a claim the server already rejected (would just spam both
             // sides with conflicts).
             ownClaims.delete(rejection.claimId);
+            // A holder on another server may have claimed before this client joined
+            // the row group, so its one-shot presence frame was missed. A conflict
+            // reply carries the authoritative holder summary; seed the same local
+            // state immediately instead of continuing to report the row as free.
+            if (rejection.reason === 'conflict' &&
+                rejection.heldBy &&
+                rejection.heldByClaim) {
+                observeForeignClaim(rejection.heldBy, rejection.heldByClaim, rejection.heldByKind);
+                notifyListeners();
+            }
             for (const l of rejectionListeners) {
                 try {
                     l(rejection);

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

@@ -45,6 +45,15 @@ export interface MutationQueueConfig {
     maxBatchSize: number;
     batchDelay: number;
     maxRetries: number;
+    /**
+     * Minimum wall-clock window for retrying transient write failures with the
+     * same durable envelope and idempotency key. This absorbs managed-database
+     * promotion and brief regional network incidents without double-applying a
+     * write. Defaults to 120 seconds: the Aurora promotion drill recovered
+     * writes just beyond 60 seconds, so a one-minute boundary discarded exact
+     * envelopes at the instant the new writer became usable.
+     */
+    availabilityRetryWindowMs: number;
     conflictResolution: ConflictResolution;
     enablePersistence: boolean;
     enableOptimistic: boolean;
@@ -127,6 +136,7 @@ export declare class MutationQueue extends EventEmitter {
     private replicationLagTimeouts;
     private replicationLagErrors;
     private commitProcessing;
+    private commitRetryTimer;
     private lastCommitSequence;
     private durableReplayBlock;
     /** Browser-backed strict outbox; absent for standalone/in-memory consumers. */
@@ -220,7 +230,7 @@ export declare class MutationQueue extends EventEmitter {
     private dispatchCommitBounded;
     private clearReplicationLagState;
     /**
-     * Bounds the public `wait: 'confirmed'` promise without changing the
+     * Bounds the public model-write confirmation promise without changing the
      * accepted write's lifecycle. A lag timeout is not a rejection from the
      * source database, so it must never emit `transaction:failed`, roll back
      * optimistic state, or remove the durable replay envelope.
@@ -418,6 +428,15 @@ export declare class MutationQueue extends EventEmitter {
             maxBatchSize: number;
             batchDelay: number;
             maxRetries: number;
+            /**
+             * Minimum wall-clock window for retrying transient write failures with the
+             * same durable envelope and idempotency key. This absorbs managed-database
+             * promotion and brief regional network incidents without double-applying a
+             * write. Defaults to 120 seconds: the Aurora promotion drill recovered
+             * writes just beyond 60 seconds, so a one-minute boundary discarded exact
+             * envelopes at the instant the new writer became usable.
+             */
+            availabilityRetryWindowMs: number;
             conflictResolution: ConflictResolution;
             enablePersistence: boolean;
             enableOptimistic: boolean;

package/dist/local/transactions/mutations/MutationQueue.js

@@ -104,6 +104,7 @@ export class MutationQueue extends EventEmitter {
     replicationLagTimeouts = new Map();
     replicationLagErrors = new Map();
     commitProcessing = false;
+    commitRetryTimer = null;
     lastCommitSequence = 0;
     durableReplayBlock = null;
     /** Browser-backed strict outbox; absent for standalone/in-memory consumers. */
@@ -125,7 +126,11 @@ export class MutationQueue extends EventEmitter {
     get commitLaneContext() {
         return {
             runtime: this.runtime,
-            config: { maxRetries: this.config.maxRetries },
+            config: {
+                maxRetries: this.config.maxRetries,
+                availabilityRetryWindowMs: this.config.availabilityRetryWindowMs,
+                retryBackoff: this.config.retryBackoff,
+            },
             commitLane: this.commitLane,
             commitNotifications: this.commitNotifications,
             commitMissingIds: this.commitMissingIds,
@@ -147,6 +152,14 @@ export class MutationQueue extends EventEmitter {
             noteAck: (syncId) => this.noteAck(syncId),
             isDefinitiveRejection: (error) => this.isDefinitiveRejection(error),
             isPermanentError: (error) => this.isPermanentError(error),
+            scheduleRetry: (delayMs) => {
+                if (this.commitRetryTimer !== null)
+                    clearTimeout(this.commitRetryTimer);
+                this.commitRetryTimer = setTimeout(() => {
+                    this.commitRetryTimer = null;
+                    void this.processCommitLane();
+                }, delayMs);
+            },
             emitCommitLifecycle: (event, payload) => this.emitCommitLifecycle(event, payload),
         };
     }
@@ -516,6 +529,7 @@ export class MutationQueue extends EventEmitter {
         maxBatchSize: 50, // send up to this many operations per commit
         batchDelay: 150, // milliseconds to wait for more operations before sending
         maxRetries: 3,
+        availabilityRetryWindowMs: 120_000,
         conflictResolution: {
             strategy: 'last-write-wins',
         },
@@ -726,7 +740,7 @@ export class MutationQueue extends EventEmitter {
         this.replicationLagErrors.delete(transactionId);
     }
     /**
-     * Bounds the public `wait: 'confirmed'` promise without changing the
+     * Bounds the public model-write confirmation promise without changing the
      * accepted write's lifecycle. A lag timeout is not a rejection from the
      * source database, so it must never emit `transaction:failed`, roll back
      * optimistic state, or remove the durable replay envelope.
@@ -1506,6 +1520,10 @@ export class MutationQueue extends EventEmitter {
             clearTimeout(this.commitOfflineGraceTimer);
             this.commitOfflineGraceTimer = null;
         }
+        if (this.commitRetryTimer !== null) {
+            clearTimeout(this.commitRetryTimer);
+            this.commitRetryTimer = null;
+        }
         // Clear store
         this.store.clear();
         this.localMutationPort.updates.clear();

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

@@ -21,6 +21,7 @@ export interface CommitTransaction {
     createdAt: number;
     attempts: number;
     transientAttempts?: number;
+    firstTransientFailureAt?: number;
     lastSyncId?: number;
     correlationId?: string;
     error?: Error;
@@ -34,6 +35,11 @@ export interface CommitLaneContext {
     readonly runtime: RuntimeContext;
     readonly config: {
         maxRetries: number;
+        availabilityRetryWindowMs: number;
+        retryBackoff: {
+            baseMs: number;
+            capMs: number;
+        };
     };
     readonly commitLane: CommitTransaction[];
     readonly commitNotifications: Map<string, StaleNotification[]>;
@@ -52,6 +58,7 @@ export interface CommitLaneContext {
     readonly noteAck: (syncId: number | undefined) => void;
     readonly isDefinitiveRejection: (error: Error) => boolean;
     readonly isPermanentError: (error: Error) => boolean;
+    readonly scheduleRetry: (delayMs: number) => void;
     readonly emitCommitLifecycle: (event: string, payload: object) => void;
 }
 export interface CommitReceiptContext {

package/dist/local/transactions/mutations/commitLane.js

@@ -1,4 +1,4 @@
-import { AbloConnectionError } from '@abloatai/transaction/errors';
+import { transientRetryDelayMs } from './failureHandling.js';
 export function waitForCommitReceipt(ctx, clientTxId) {
     const drainNotifications = () => {
         const notifications = ctx.commitNotifications.get(clientTxId);
@@ -112,15 +112,18 @@ export async function processCommitLane(ctx) {
                 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;
+                tx.transientAttempts = (tx.transientAttempts ?? 0) + 1;
+                tx.firstTransientFailureAt ??= Date.now();
+                const outsideAvailabilityWindow = Date.now() - tx.firstTransientFailureAt >= ctx.config.availabilityRetryWindowMs;
+                const exhausted = tx.transientAttempts > ctx.config.maxRetries && outsideAvailabilityWindow;
                 if (!ctx.isPermanentError(error) && !exhausted) {
                     tx.status = 'pending';
+                    const delayMs = transientRetryDelayMs(error, tx.transientAttempts, ctx.config.retryBackoff);
                     ctx.runtime.logger.debug('[MutationQueue] commit lane transient', {
                         txId: tx.id.slice(0, 12), attempts: tx.attempts,
-                        transientAttempts: tx.transientAttempts ?? 0, message: error.message,
+                        transientAttempts: tx.transientAttempts, delayMs, message: error.message,
                     });
+                    ctx.scheduleRetry(delayMs);
                     break;
                 }
                 tx.status = 'failed';

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

@@ -54,6 +54,8 @@ export interface QueuedMutation {
     status: 'pending' | 'executing' | 'awaiting_delta' | 'completed' | 'failed' | 'rolled_back';
     createdAt: number;
     attempts: number;
+    /** First transient dispatch failure in the current availability incident. */
+    firstTransientFailureAt?: number;
     priority: 'normal' | 'high';
     priorityScore: number;
     writeOptions?: WriteOptions;

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

@@ -4,7 +4,7 @@ import type { QueuedMutation } from './commitPayload.js';
 import type { MutationStore } from './MutationStore.js';
 export interface FailureHandlingContext {
     readonly runtime: RuntimeContext;
-    readonly config: Pick<MutationQueueConfig, 'enableOptimistic' | 'maxRetries' | 'retryBackoff'>;
+    readonly config: Pick<MutationQueueConfig, 'enableOptimistic' | 'maxRetries' | 'retryBackoff' | 'availabilityRetryWindowMs'>;
     readonly store: MutationStore;
     readonly isPermanentError: (error: Error) => boolean;
     readonly rollbackOptimistic: (transaction: QueuedMutation, reason: string, error?: Error) => Promise<void>;
@@ -13,4 +13,5 @@ export interface FailureHandlingContext {
     readonly setLastPermanentErrorSignature: (signature: string) => void;
     readonly emit: (event: string, payload: object) => boolean;
 }
+export declare function transientRetryDelayMs(error: Error, attempt: number, retryBackoff: MutationQueueConfig['retryBackoff']): number;
 export declare function handleFailure(ctx: FailureHandlingContext, transaction: QueuedMutation, error: Error): Promise<void>;