@abloatai/humans 0.43.0 → 0.45.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

@@ -348,8 +348,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 +402,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 +410,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/failureHandling.js

@@ -53,6 +53,9 @@ export async function handleFailure(ctx, transaction, error) {
                 : '';
             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
@@ -63,7 +66,7 @@ export async function handleFailure(ctx, transaction, error) {
             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}.${revertNote}${channelNote}`;
+            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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "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.43.0",
+    "@abloatai/transaction": "^0.45.0",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",
     "zod": "^4.4.3"

package/src/Ablo.ts

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

package/src/local/client/createModelProxy.ts

@@ -78,6 +78,11 @@ export type {
   ServerRetrieveOptions,
   ClaimTargetOptions,
   ClaimParams,
+  ClaimContentionOptions,
+  ClaimAttemptEvent,
+  ClaimQueueView,
+  ClaimSkipOptions,
+  ClaimSkipParams,
   ClaimLookupParams,
   ClaimReorderParams,
   ClaimOptions,
@@ -97,6 +102,10 @@ import type {
   ClaimLookupParams,
   ClaimOptions,
   ClaimParams,
+  ClaimSkipOptions,
+  ClaimSkipParams,
+  ClaimAttemptEvent,
+  ClaimQueueView,
   ClaimReorderParams,
   JoinOptions,
   LocalCountOptions,
@@ -109,6 +118,10 @@ import type {
   ModelUpdateParams,
   ServerReadOptions,
 } from '@abloatai/transaction/resources/modelOperations';
+import {
+  claimQueueView,
+  resolveClaimContentionOptions,
+} from '@abloatai/transaction/resources/modelOperations';
 import type { HttpModelClient } from '@abloatai/transaction/transport/httpClient';
 import type { ParticipantKind } from '@abloatai/transaction/types/participant';
 
@@ -160,6 +173,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;
   /**
@@ -557,23 +572,13 @@ export function createModelProxy<T, C>(
       );
     }
     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);
@@ -599,27 +604,41 @@ export function createModelProxy<T, C>(
 
     // 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: Claim;
+    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
@@ -748,22 +767,8 @@ export function createModelProxy<T, C>(
         { 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
@@ -772,24 +777,38 @@ export function createModelProxy<T, C>(
     // 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: Claim;
+    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
@@ -881,12 +900,12 @@ export function createModelProxy<T, C>(
   const guardedTakeClaim = guard(takeClaim);
   const guardedTakeRowFreeClaim = guard(takeRowFreeClaim);
   function claim(
-    params: ClaimParams<C> & { queue: false },
+    params: ClaimSkipParams<C>,
   ): Promise<HeldClaim<T> | null>;
   function claim(params: ClaimParams<C>): Promise<HeldClaim<T>>;
   function claim(
     id: string,
-    opts: ClaimOptions<C> & { queue: false },
+    opts: ClaimSkipOptions<C>,
   ): Promise<HeldLease | null>;
   function claim(id: string, opts?: ClaimOptions<C>): Promise<HeldLease>;
   function claim(
@@ -973,11 +992,10 @@ export function createModelProxy<T, C>(
       };
     },
 
-    queue(params: ClaimLookupParams<T>): { readonly object: 'list'; readonly data: readonly Claim[] } {
-      return {
-        object: 'list',
-        data: collaboration?.queue({ model: wireModel, id: params.id }) ?? [],
-      };
+    queue(params: ClaimLookupParams<T>): ClaimQueueView {
+      return claimQueueView(
+        collaboration?.queue({ model: wireModel, id: params.id }) ?? [],
+      );
     },
 
     reorder(params: ClaimReorderParams<T>): void {
@@ -1086,6 +1104,7 @@ export function createModelProxy<T, C>(
         // 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,
@@ -1094,8 +1113,11 @@ export function createModelProxy<T, C>(
           },
           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,
         });
       }
 
@@ -1200,7 +1222,7 @@ export function createModelProxy<T, C>(
           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(

package/src/local/client/reactiveEngine.ts

@@ -62,6 +62,10 @@ import type {
   CreateAgentSessionParams,
   CreateSessionParams,
 } from './resourceTypes.js';
+import {
+  claimAttemptFailure,
+  emitClaimStatus,
+} from '@abloatai/transaction/resources/modelOperations';
 import { createModelProxy, type ModelOperations } from './createModelProxy.js';
 import { assertWriteOptions } from '@abloatai/transaction/resources/writeOptionsSchema';
 import type { AbloClient as Ablo } from '../../client.js';
@@ -409,8 +413,8 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
 	      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',
@@ -433,6 +437,38 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
 	  const publicClaims: ClaimResource = Object.assign(claimStream, {
 	    async create(claimOptions: ClaimCreateOptions): Promise<Claim> {
 	      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),
@@ -443,31 +479,17 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
 	          ttl: claimOptions.ttl,
 	          queue: claimOptions.queue,
 	        },
+	        claimId,
 	      );
-	      // 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: number | undefined;
-	      let readAt: number | undefined;
-	      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;
-	        }
-	      }
+	      // 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: unknown) => {
+	        // 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;
+	      });
 	      return wrapClaimHandle(claim, waited, fenceToken, readAt);
 	    },
 	    list(target?: Partial<ModelTarget>): readonly ModelClaim[] {

package/src/local/client/resourceTypes.ts

@@ -23,6 +23,9 @@ export type {
   ModelDeleteParams,
   ClaimOptions,
   ClaimParams,
+  ClaimContentionOptions,
+  ClaimAttemptEvent,
+  ClaimQueueView,
   ClaimLookupParams,
   ClaimReorderParams,
   Claim,

package/src/local/sync/createClaimStream.ts

@@ -88,13 +88,18 @@ const HEARTBEAT_ACK_TIMEOUT_MS = 10_000;
 
 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
@@ -523,8 +528,9 @@ export function createClaimStream(
       ttl?: ClaimLeaseOptions['ttl'];
       queue?: boolean;
     },
+    requestedClaimId?: string,
   ): Claim {
-    const claimId = crypto.randomUUID();
+    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
@@ -589,6 +595,7 @@ export function createClaimStream(
     claim(
       target: PresenceTarget,
       opts?: ClaimOptions,
+      claimId?: string,
     ): Claim {
       const resolved = resolveTarget(target);
       return mintHandle({
@@ -597,7 +604,7 @@ export function createClaimStream(
         description: claimDescription({ ...opts, meta: resolved.meta }),
         ttl: opts?.ttl,
         queue: opts?.queue,
-      });
+      }, claimId);
     },
     get others() {
       return claimsSnapshot;

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

@@ -76,6 +76,9 @@ export async function handleFailure(ctx: FailureHandlingContext, transaction: Qu
           : '';
         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
@@ -86,7 +89,7 @@ export async function handleFailure(ctx: FailureHandlingContext, transaction: Qu
         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}.${revertNote}${channelNote}`;
+        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 —