@abloatai/humans 0.44.0 → 0.46.0

package/dist/Ablo.d.ts

@@ -171,6 +171,9 @@ export declare namespace Ablo {
         type Held<T = Record<string, unknown>> = import('@abloatai/transaction/types/streams').HeldClaim<T>;
         type CreateOptions = import('./local/client/resourceTypes.js').ClaimCreateOptions;
         type WaitOptions = import('./local/client/resourceTypes.js').ClaimWaitOptions;
+        type ContentionOptions = import('@abloatai/transaction/resources/modelOperations').ClaimContentionOptions;
+        type AttemptEvent = import('@abloatai/transaction/resources/modelOperations').ClaimAttemptEvent;
+        type QueueView = import('@abloatai/transaction/resources/modelOperations').ClaimQueueView;
         type Client = import('./local/client/resourceTypes.js').ClaimResource;
     }
     namespace Model {

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

@@ -17,9 +17,9 @@ import type { SyncClient } from '../SyncClient.js';
 import type { OnDemandLoader } from '../sync/OnDemandLoader.js';
 import type { JoinedParticipant } from '../sync/participants.js';
 import type { Duration, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease, ClaimWaitOptions, Snapshot } from '@abloatai/transaction/types/streams';
-export type { ModelListScope, ModelTrackParams, ModelTrackResult, LocalReadOptions, LocalCountOptions, ServerReadOptions, ServerGetOptions, ServerRetrieveOptions, ClaimTargetOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimOptions, ClaimReadApi, AwaitedClaimMethod, ClaimApi, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, JoinOptions, } from '@abloatai/transaction/resources/modelOperations';
+export type { ModelListScope, ModelTrackParams, ModelTrackResult, LocalReadOptions, LocalCountOptions, ServerReadOptions, ServerGetOptions, ServerRetrieveOptions, ClaimTargetOptions, ClaimParams, ClaimContentionOptions, ClaimAttemptEvent, ClaimQueueView, ClaimSkipOptions, ClaimSkipParams, ClaimLookupParams, ClaimReorderParams, ClaimOptions, ClaimReadApi, AwaitedClaimMethod, ClaimApi, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, JoinOptions, } from '@abloatai/transaction/resources/modelOperations';
 export type { Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease };
-import type { ClaimApi, JoinOptions, LocalCountOptions, LocalReadOptions } from '@abloatai/transaction/resources/modelOperations';
+import type { ClaimApi, ClaimAttemptEvent, JoinOptions, LocalCountOptions, LocalReadOptions } from '@abloatai/transaction/resources/modelOperations';
 import type { HttpModelClient } from '@abloatai/transaction/transport/httpClient';
 import type { ParticipantKind } from '@abloatai/transaction/types/participant';
 export interface ModelClientMeta {
@@ -56,6 +56,8 @@ export interface ModelCollaboration {
         waitTimeoutMs?: number;
         /** Abort the queued wait — rejects with `claim_wait_aborted`. */
         signal?: AbortSignal;
+        /** Request-scoped queued / granted / skipped / failed status events. */
+        onStatus?: (event: ClaimAttemptEvent) => void;
     }): Promise<Claim>;
     createSnapshot(modelKey: string, id: string): Snapshot;
     /**

package/dist/local/client/createModelProxy.js

@@ -26,6 +26,7 @@ import { subTarget } from '@abloatai/transaction/coordination';
 // here like the other enumerated crossings.
 import { declaredMeta } from '@abloatai/transaction/coordination/claimMeta';
 import { ModelScope } from '@abloatai/transaction/types';
+import { claimQueueView, resolveClaimContentionOptions, } from '@abloatai/transaction/resources/modelOperations';
 const modelClientMeta = new WeakMap();
 export function getModelClientMeta(modelClient) {
     if (typeof modelClient !== 'object' || modelClient === null)
@@ -172,22 +173,13 @@ defaultWait) {
             throw new AbloValidationError(`Model "${schemaKey}" was built without the collaboration runtime, so claim() is unavailable here. Claiming needs no per-model config — use the standard Ablo({ schema, apiKey }) client and every model is claimable.`, { code: 'model_claim_not_configured' });
         }
         const { id, ...options } = params;
-        // Is someone else already on this target? Read the local coordination
-        // snapshot up front — it decides whether a re-read is needed after the
-        // claim (a free or already-held target cannot have changed underneath us).
+        // Read the local snapshot only to decide whether a post-grant re-read may
+        // be needed. Admission itself always goes to the server: a local presence
+        // snapshot may be stale or incomplete across instances.
         const held = collaboration.state({ model: wireModel, id });
         const contended = !!held && held.heldBy !== collaboration.selfParticipantId;
-        const failFast = options.queue === false;
-        // The try-claim (`queue: false`): a held target is an expected outcome,
-        // not an error, so it resolves `null` — the caller reads `if (!claim)`
-        // and moves on; who holds it stays readable via `claim.state`. Best-effort
-        // at the client (a racing claim not yet synced into our snapshot slips
-        // through here) — the commit-time claim guard is the authoritative
-        // backstop that rejects the loser's first write. For work-distribution
-        // dedup that's exactly right: don't wait (that would double-process), skip.
-        if (failFast && contended) {
-            return null;
-        }
+        const contention = resolveClaimContentionOptions(options);
+        const failFast = !contention.wait;
         // Ensure the row exists locally before claiming.
         let model = ownRowOrThrow(id);
         if (!model) {
@@ -207,27 +199,40 @@ defaultWait) {
         await collaboration.pinScope?.({ [schemaKey]: id });
         // Acquire the lease. By default (`queue` is not false) this goes through the
         // server's fair FIFO queue: `queue: true` resolves only once the lease is
-        // genuinely ours, blocking behind any current holder, with no check-then-act
-        // gap because the server orders contenders. Fail-fast skips the queue: an
-        // observed conflict was already rejected above, so this just records the lease.
-        const lease = await collaboration.createClaim({
-            target: {
-                model: wireModel,
-                id,
-                // The whole sub-entity locator in one move — listing its members here
-                // is what let `fields` die between the caller and the lease, so the
-                // claim covered the whole row while the caller believed it named parts.
-                ...subTarget(options, schemaKey),
-            },
-            description: claimDescription(options),
-            ttl: options.ttl,
-            queue: !failFast,
-            maxQueueDepth: options.maxQueueDepth,
-            // The one wait cap, declared once on ClaimTargetOptions — the socket
-            // wait and the HTTP poll-wait both honor it as `grant_timeout`.
-            waitTimeoutMs: options.waitTimeoutMs,
-            signal: options.signal,
-        });
+        // genuinely ours, blocking behind any current holder. Fail-fast skips the
+        // queue but still awaits the server: a conflict invisible in the local
+        // snapshot resolves `null`, never a speculative handle.
+        let lease;
+        try {
+            lease = await collaboration.createClaim({
+                target: {
+                    model: wireModel,
+                    id,
+                    // The whole sub-entity locator in one move — listing its members here
+                    // is what let `fields` die between the caller and the lease, so the
+                    // claim covered the whole row while the caller believed it named parts.
+                    ...subTarget(options, schemaKey),
+                },
+                description: claimDescription(options),
+                ttl: options.ttl,
+                queue: contention.wait,
+                maxQueueDepth: contention.maxDepth,
+                // The one wait cap, declared once on ClaimTargetOptions — the socket
+                // wait and the HTTP poll-wait both honor it as `grant_timeout`.
+                waitTimeoutMs: contention.timeoutMs,
+                signal: contention.signal,
+                onStatus: contention.onStatus,
+            });
+        }
+        catch (err) {
+            const normalized = toAbloError(err);
+            if (failFast &&
+                normalized instanceof AbloClaimedError &&
+                normalized.code === 'claim_conflict') {
+                return null;
+            }
+            throw normalized;
+        }
         // Only when the claim actually waited behind another holder can the row have
         // changed underneath us — re-read so the claimed snapshot reflects what that
         // holder committed before releasing. Either of two signals suffices:
@@ -340,45 +345,45 @@ defaultWait) {
         if (!collaboration) {
             throw new AbloValidationError(`Model "${schemaKey}" was built without the collaboration runtime, so claim() is unavailable here. Claiming needs no per-model config — use the standard Ablo({ schema, apiKey }) client and every model is claimable.`, { code: 'model_claim_not_configured' });
         }
-        // Is someone else already on this target? Read the local coordination
-        // snapshot up front so a `queue: false` caller can reject before announcing
-        // a claim the server would refuse.
-        const held = collaboration.state({ model: wireModel, id });
-        const contended = !!held && held.heldBy !== collaboration.selfParticipantId;
-        const failFast = options.queue === false;
-        // The try-claim (`queue: false`): resolve `null` if a holder is already
-        // visible — an expected outcome, not an error. Best-effort at the client —
-        // a row this participant never synced usually carries no local claim state
-        // either, so a peer gets the deterministic `null` only once it has
-        // observed the holder (entered the row's entity scope). The server's
-        // queue is the backstop for the queuing path.
-        if (failFast && contended) {
-            return null;
-        }
+        const contention = resolveClaimContentionOptions(options);
+        const failFast = !contention.wait;
         // Enter the entity scope before acquiring the lease so the holder's claim
         // presence broadcasts to everyone in this entity group — the same ordering
         // the row-bearing path relies on. No pool `load` and no `entity_not_found`
         // throw: the row lives only in the customer's database, so there is nothing
         // to hydrate here and nothing to re-read after the grant.
         await collaboration.pinScope?.({ [schemaKey]: id });
-        const lease = await collaboration.createClaim({
-            target: {
-                model: wireModel,
-                id,
-                // The whole sub-entity locator in one move — listing its members here
-                // is what let `fields` die between the caller and the lease, so the
-                // claim covered the whole row while the caller believed it named parts.
-                ...subTarget(options, schemaKey),
-            },
-            description: claimDescription(options),
-            ttl: options.ttl,
-            queue: !failFast,
-            maxQueueDepth: options.maxQueueDepth,
-            // The one wait cap, declared once on ClaimTargetOptions — the socket
-            // wait and the HTTP poll-wait both honor it as `grant_timeout`.
-            waitTimeoutMs: options.waitTimeoutMs,
-            signal: options.signal,
-        });
+        let lease;
+        try {
+            lease = await collaboration.createClaim({
+                target: {
+                    model: wireModel,
+                    id,
+                    // The whole sub-entity locator in one move — listing its members here
+                    // is what let `fields` die between the caller and the lease, so the
+                    // claim covered the whole row while the caller believed it named parts.
+                    ...subTarget(options, schemaKey),
+                },
+                description: claimDescription(options),
+                ttl: options.ttl,
+                queue: contention.wait,
+                maxQueueDepth: contention.maxDepth,
+                // The one wait cap, declared once on ClaimTargetOptions — the socket
+                // wait and the HTTP poll-wait both honor it as `grant_timeout`.
+                waitTimeoutMs: contention.timeoutMs,
+                signal: contention.signal,
+                onStatus: contention.onStatus,
+            });
+        }
+        catch (err) {
+            const normalized = toAbloError(err);
+            if (failFast &&
+                normalized instanceof AbloClaimedError &&
+                normalized.code === 'claim_conflict') {
+                return null;
+            }
+            throw normalized;
+        }
         // A watermark-only snapshot: `createSnapshot` still reads the engine's
         // current `lastSyncId` even though the pool holds no row (the bucket is
         // empty). It costs nothing extra and gives a write taken under this lease a
@@ -537,10 +542,7 @@ defaultWait) {
             };
         },
         queue(params) {
-            return {
-                object: 'list',
-                data: collaboration?.queue({ model: wireModel, id: params.id }) ?? [],
-            };
+            return claimQueueView(collaboration?.queue({ model: wireModel, id: params.id }) ?? []);
         },
         reorder(params) {
             collaboration?.reorder({ model: wireModel, id: params.id }, params.order);
@@ -627,6 +629,7 @@ defaultWait) {
                 // race — see `takeClaim`). Released with the lease in the `finally`
                 // below. Awaited for broadcast ordering; still best-effort.
                 await collaboration.pinScope?.({ [schemaKey]: id });
+                const contention = resolveClaimContentionOptions(claim);
                 autoLease = await collaboration.createClaim({
                     target: {
                         model: wireModel,
@@ -635,8 +638,11 @@ defaultWait) {
                     },
                     description: claimDescription(claim, 'creating'),
                     ttl: claim.ttl,
-                    queue: claim.queue !== false,
-                    maxQueueDepth: claim.maxQueueDepth,
+                    queue: contention.wait,
+                    maxQueueDepth: contention.maxDepth,
+                    waitTimeoutMs: contention.timeoutMs,
+                    signal: contention.signal,
+                    onStatus: contention.onStatus,
                 });
             }
             // Default `organizationId` from the client's identity, matching the other
@@ -724,7 +730,7 @@ defaultWait) {
                 const autoClaim = params.claim && !isClaimHandle(params.claim) ? params.claim : null;
                 if (autoClaim) {
                     const handle = await takeClaim({ ...autoClaim, id: params.id });
-                    // A declined try-claim is `null` only on the standalone verb; a
+                    // A skipped try-claim is `null` only on the standalone verb; a
                     // write that could not take its claim is a failed write.
                     if (!handle) {
                         throw new AbloClaimedError(`${registeredModelName}/${params.id} is held by another participant, so this update's claim could not be taken.`, { code: 'entity_claimed' });

package/dist/local/client/reactiveEngine.js

@@ -25,6 +25,7 @@ import { awaitClaimGrant } from '@abloatai/transaction/coordination/awaitClaimGr
 import { createSnapshot } from '../sync/createSnapshot.js';
 import { createParticipantManager } from '../sync/participants.js';
 import { resolveApiKeyValue, resolveBootstrapBaseUrl } from '@abloatai/transaction/auth/apiKey';
+import { claimAttemptFailure, emitClaimStatus, } from '@abloatai/transaction/resources/modelOperations';
 import { createModelProxy } from './createModelProxy.js';
 import { assertWriteOptions } from '@abloatai/transaction/resources/writeOptionsSchema';
 export function buildReactiveEngine(inputs) {
@@ -257,8 +258,8 @@ export function buildReactiveEngine(inputs) {
             return Promise.resolve();
         };
         // The token is server-stamped and arrives on the grant frame, so prefer
-        // the one `awaitClaimGrant` read there; fall back to any the local handle
-        // already carried (immediate, non-queued grants).
+        // the one `awaitClaimGrant` read there; retain the handle fallback for
+        // wire-compatible transports that already stamped it locally.
         const resolvedFenceToken = fenceToken ?? claim.fenceToken;
         return {
             object: 'claim',
@@ -280,6 +281,35 @@ export function buildReactiveEngine(inputs) {
     const publicClaims = Object.assign(claimStream, {
         async create(claimOptions) {
             await ready();
+            // Subscribe before announcing the claim. A fast rejection can arrive
+            // in the same turn as `send` in tests and on a low-latency socket; if
+            // the listener is installed afterwards, that authoritative answer is
+            // lost and the locally minted handle looks like a grant.
+            const claimId = crypto.randomUUID();
+            const grant = awaitClaimGrant(transport, claimId, {
+                timeoutMs: claimOptions.waitTimeoutMs,
+                maxQueueDepth: claimOptions.maxQueueDepth,
+                signal: claimOptions.signal,
+                logger,
+                onQueued: ({ position }) => {
+                    emitClaimStatus(claimOptions.onStatus, {
+                        type: 'queued',
+                        claimId,
+                        position,
+                        ahead: position + 1,
+                    });
+                },
+                onGranted: ({ waited }) => {
+                    emitClaimStatus(claimOptions.onStatus, {
+                        type: 'granted',
+                        claimId,
+                        waited,
+                    });
+                },
+                onFailed: (error) => {
+                    emitClaimStatus(claimOptions.onStatus, claimAttemptFailure(claimOptions.queue !== false, error));
+                },
+            });
             const claim = claimStream.claim({
                 ...streamTarget(claimOptions.target),
                 ...subTarget(claimOptions.target),
@@ -287,32 +317,16 @@ export function buildReactiveEngine(inputs) {
                 description: claimOptions.description,
                 ttl: claimOptions.ttl,
                 queue: claimOptions.queue,
+            }, claimId);
+            // A claim is ours only after the server says so. This applies equally
+            // to queued claims and try-claims (`queue: false`): the latter must
+            // observe `claim_rejected` instead of returning a phantom handle.
+            const { waited, fenceToken, readAt } = await grant.catch((err) => {
+                // Give up the local/reconnect record after any rejection, timeout,
+                // abort, or lost lease. For queued claims this also leaves the line.
+                claim.revoke?.();
+                throw err;
             });
-            // With `queue`, the claim is only really *ours* once the server says
-            // so (`claim_acquired` if the target was free, `claim_granted` once
-            // we reach the head of the FIFO line). Block here on that grant so
-            // callers — chiefly `ablo.<model>.claim` — get a handle that already
-            // holds the lease, never a half-claimed one racing the queue.
-            let waited = false;
-            let fenceToken;
-            let readAt;
-            if (claimOptions.queue) {
-                try {
-                    ({ waited, fenceToken, readAt } = await awaitClaimGrant(transport, claim.id, {
-                        timeoutMs: claimOptions.waitTimeoutMs,
-                        maxQueueDepth: claimOptions.maxQueueDepth,
-                        signal: claimOptions.signal,
-                        logger,
-                    }));
-                }
-                catch (err) {
-                    // Gave up waiting (queue too deep, timed out, or lost) — abandon
-                    // the queued claim so we don't leave a phantom entry in the
-                    // line that would block or mislead other claimers.
-                    claim.revoke?.();
-                    throw err;
-                }
-            }
             return wrapClaimHandle(claim, waited, fenceToken, readAt);
         },
         list(target) {

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, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease, } from '@abloatai/transaction/resources/modelOperations';
+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 { ModelOperations } from './createModelProxy.js';

package/dist/local/sync/createClaimStream.d.ts

@@ -41,13 +41,18 @@ export interface ClaimStreamConfig {
 }
 export interface AttachableClaimStream extends ClaimStream {
     /**
-     * Mints a lease directly: sends the `claim_begin` frame and returns a held
-     * {@link Claim} that carries no row `data` (the resource layer reads the row
-     * and stamps it). This is an internal entry point, not part of the public
+     * Mints the local handle and sends its `claim_begin` frame. The handle is a
+     * request until the resource layer observes the server's grant; it must never
+     * be returned to application code before that acknowledgement. This is an
+     * internal entry point, not part of the public
      * {@link ClaimStream}; application code takes a claim through
      * `ablo.<model>.claim({ id })`, which is built on this.
+     *
+     * `claimId` lets that resource layer subscribe for the acknowledgement before
+     * this method sends. Omitting it preserves the direct stream API's generated
+     * id for internal callers that do not await the grant.
      */
-    claim(target: PresenceTarget, opts?: ClaimOptions): Claim;
+    claim(target: PresenceTarget, opts?: ClaimOptions, claimId?: string): Claim;
     attach(transport: ClaimTransport): void;
     /**
      * Seeds the participant identity once the host resolves it. The stream can

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);
@@ -348,8 +357,8 @@ export function createClaimStream(config, transport = null) {
     // The locator half derives from `OwnClaim` rather than being restated: a
     // member spelled out here is a member that dies before `sendBegin`, which is
     // how `fields` used to be lost between `claim()` and the socket.
-    function mintHandle(args) {
-        const claimId = crypto.randomUUID();
+    function mintHandle(args, requestedClaimId) {
+        const claimId = requestedClaimId ?? crypto.randomUUID();
         const estimatedMs = args.ttl !== undefined ? toMs(args.ttl) : undefined;
         // The handle the caller reads back is a public claim, so its `meta` is the
         // declared shape; the `OwnClaim` below stays wire-typed, because that is
@@ -402,7 +411,7 @@ export function createClaimStream(config, transport = null) {
         return target;
     }
     return {
-        claim(target, opts) {
+        claim(target, opts, claimId) {
             const resolved = resolveTarget(target);
             return mintHandle({
                 ...wireTarget(resolved),
@@ -410,7 +419,7 @@ export function createClaimStream(config, transport = null) {
                 description: claimDescription({ ...opts, meta: resolved.meta }),
                 ttl: opts?.ttl,
                 queue: opts?.queue,
-            });
+            }, claimId);
         },
         get others() {
             return claimsSnapshot;

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. */
@@ -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',
         },
@@ -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';