@abloatai/transaction 0.43.0 → 0.45.0

package/src/coordination/awaitClaimGrant.ts

@@ -15,6 +15,7 @@
 
 import {
   AbloClaimedError,
+  AbloError,
   AbloValidationError,
   CapabilityError,
   formatClaimedErrorMessage,
@@ -88,6 +89,10 @@ export function awaitClaimGrant(
     signal?: AbortSignal;
     /** Where grant transitions are logged. Defaults to silent. */
     logger?: Logger;
+    /** Request-scoped lifecycle hooks; observer failures never alter admission. */
+    onQueued?: (info: { claimId: string; position: number }) => void;
+    onGranted?: (info: ClaimGrantInfo & { claimId: string }) => void;
+    onFailed?: (error: AbloError) => void;
   },
 ): Promise<ClaimGrantInfo> {
   const logger = options?.logger ?? noopLogger;
@@ -99,6 +104,19 @@ export function awaitClaimGrant(
       for (const u of unsubs) u();
       fn();
     };
+    const observe = (fn: (() => void) | undefined): void => {
+      try {
+        fn?.();
+      } catch {
+        // Admission is authoritative; telemetry/UI callbacks are not.
+      }
+    };
+    const fail = (error: AbloError): void => {
+      settle(() => {
+        observe(() => options?.onFailed?.(error));
+        reject(error);
+      });
+    };
 
     // The target was free → `claim_acquired` (immediate); it was contended,
     // we waited in line, and reached the head → `claim_granted`. Either frame
@@ -110,11 +128,13 @@ export function awaitClaimGrant(
           const fenceToken = readFenceToken(p);
           const readAt = readWatermark(p);
           settle(() => {
-            resolve({
+            const info: ClaimGrantInfo = {
               waited: false,
               ...(fenceToken !== undefined ? { fenceToken } : {}),
               ...(readAt !== undefined ? { readAt } : {}),
-            });
+            };
+            observe(() => options?.onGranted?.({ claimId, ...info }));
+            resolve(info);
           });
         }
       }),
@@ -128,34 +148,33 @@ export function awaitClaimGrant(
           const fenceToken = readFenceToken(p);
           const readAt = readWatermark(p);
           settle(() => {
-            resolve({
+            const info: ClaimGrantInfo = {
               waited: true,
               ...(fenceToken !== undefined ? { fenceToken } : {}),
               ...(readAt !== undefined ? { readAt } : {}),
-            });
+            };
+            observe(() => options?.onGranted?.({ claimId, ...info }));
+            resolve(info);
           });
         }
       }),
     );
-    if (options?.maxQueueDepth !== undefined) {
-      const max = options.maxQueueDepth;
-      unsubs.push(
-        transport.subscribe('claim_queued', (p) => {
-          if (p?.claimId !== claimId) return;
-          const position = typeof p.position === 'number' ? p.position : 0;
-          if (position >= max) {
-            settle(() =>
-              { reject(
-                new AbloClaimedError(
-                  `Claim queue for ${claimId} is ${position} deep (max ${max}).`,
-                  { code: 'queue_too_deep' },
-                ),
-              ); },
-            );
-          }
-        }),
-      );
-    }
+    unsubs.push(
+      transport.subscribe('claim_queued', (p) => {
+        if (p?.claimId !== claimId) return;
+        const position = typeof p.position === 'number' ? p.position : 0;
+        observe(() => options?.onQueued?.({ claimId, position }));
+        const max = options?.maxQueueDepth;
+        if (max !== undefined && position >= max) {
+          fail(
+            new AbloClaimedError(
+              `Claim queue for ${claimId} is ${position} deep (max ${max}).`,
+              { code: 'queue_too_deep' },
+            ),
+          );
+        }
+      }),
+    );
     unsubs.push(
       transport.subscribe('claim_rejected', (p) => {
         const rejection = p as ClaimRejection;
@@ -168,57 +187,53 @@ export function awaitClaimGrant(
           : claimId;
         if (rejection.reason === 'capability_denied') {
           settle(() => {
-            reject(
-              new CapabilityError(
-                'capability_scope_denied',
-                rejection.policyReason ??
-                  `This credential may not claim ${target}.`,
-              ),
+            const error = new CapabilityError(
+              'capability_scope_denied',
+              rejection.policyReason ??
+                `This credential may not claim ${target}.`,
             );
+            observe(() => options?.onFailed?.(error));
+            reject(error);
           });
           return;
         }
         if (rejection.reason === 'invalid_target') {
           settle(() => {
-            reject(
-              new AbloValidationError(
-                rejection.policyReason ?? `Invalid claim target ${target}.`,
-                { code: 'invalid_body' },
-              ),
+            const error = new AbloValidationError(
+              rejection.policyReason ?? `Invalid claim target ${target}.`,
+              { code: 'invalid_body' },
             );
+            observe(() => options?.onFailed?.(error));
+            reject(error);
           });
           return;
         }
-        settle(() =>
-          { reject(
-            new AbloClaimedError(
-              formatClaimedErrorMessage({
-                targetLabel: target,
-                heldBy: rejection.heldBy,
-                claim: rejection.heldByClaim,
-                policyReason: rejection.policyReason,
-                fallback: `Claim rejected for ${target}.`,
-              }),
-              {
-                code: rejection.reason === 'conflict'
-                  ? 'claim_conflict'
-                  : 'claim_lease_unavailable',
-                claims: rejection.heldByClaim ? [rejection.heldByClaim] : undefined,
-              },
-            ),
-          ); },
+        fail(
+          new AbloClaimedError(
+            formatClaimedErrorMessage({
+              targetLabel: target,
+              heldBy: rejection.heldBy,
+              claim: rejection.heldByClaim,
+              policyReason: rejection.policyReason,
+              fallback: `Claim rejected for ${target}.`,
+            }),
+            {
+              code: rejection.reason === 'conflict'
+                ? 'claim_conflict'
+                : 'claim_lease_unavailable',
+              claims: rejection.heldByClaim ? [rejection.heldByClaim] : undefined,
+            },
+          ),
         );
       }),
     );
     unsubs.push(
       transport.subscribe('claim_lost', (p) => {
         if (p?.claimId === claimId) {
-          settle(() =>
-            { reject(
-              new AbloClaimedError(`Claim lost while queued for ${claimId}.`, {
-                code: 'claim_lost',
-              }),
-            ); },
+          fail(
+            new AbloClaimedError(`Claim lost while queued for ${claimId}.`, {
+              code: 'claim_lost',
+            }),
           );
         }
       }),
@@ -226,15 +241,14 @@ export function awaitClaimGrant(
 
     if (options?.signal) {
       const signal = options.signal;
-      const abort = (): void =>
-        settle(() => {
-          reject(
-            new AbloClaimedError(
-              `The wait for claim ${claimId} was aborted before the grant arrived.`,
-              { code: 'claim_wait_aborted' },
-            ),
-          );
-        });
+      const abort = (): void => {
+        fail(
+          new AbloClaimedError(
+            `The wait for claim ${claimId} was aborted before the grant arrived.`,
+            { code: 'claim_wait_aborted' },
+          ),
+        );
+      };
       if (signal.aborted) {
         abort();
         return;
@@ -245,13 +259,11 @@ export function awaitClaimGrant(
 
     if (options?.timeoutMs && options.timeoutMs > 0) {
       timer = setTimeout(() => {
-        settle(() =>
-          { reject(
-            new AbloClaimedError(
-              `Timed out waiting for the queue grant on claim ${claimId}.`,
-              { code: 'grant_timeout' },
-            ),
-          ); },
+        fail(
+          new AbloClaimedError(
+            `Timed out waiting for the queue grant on claim ${claimId}.`,
+            { code: 'grant_timeout' },
+          ),
         );
       }, options.timeoutMs);
     }

package/src/errors.ts

@@ -60,9 +60,9 @@ export class AbloError extends Error {
   readonly code?: string;
   /** HTTP status code, when the error originated from an HTTP response. */
   readonly httpStatus?: number;
-  /** A correlation id for tracing a request through the server, present when the
-   *  server returned one on the `x-request-id` header. Include it in support
-   *  requests. */
+  /** A correlation id for tracing work through the server, returned in an HTTP
+   *  `x-request-id` header or a live commit's rejection frame. Include it in
+   *  support requests. */
   readonly requestId?: string;
   /** The specific input that caused the error, as a model or field path such as
    *  `'dataroomMember.grants.subject'`, so tooling can point at the exact
@@ -502,8 +502,17 @@ export class CapabilityError extends AbloPermissionError {
     code: 'capability_scope_denied' | 'capability_invalid',
     message: string,
     requiredCapability?: RequiredCapability,
+    options?: {
+      requestId?: string;
+      details?: Readonly<Record<string, unknown>>;
+    },
   ) {
-    super(`${code}: ${message}`, { code });
+    super(`${code}: ${message}`, {
+      code,
+      httpStatus: 403,
+      ...(options?.requestId !== undefined ? { requestId: options.requestId } : {}),
+      ...(options?.details !== undefined ? { details: options.details } : {}),
+    });
     this.name = 'CapabilityError';
     if (requiredCapability !== undefined) {
       this.requiredCapability = requiredCapability;
@@ -751,7 +760,10 @@ export function errorFromWire(
   // A scoped credential was denied — route through CapabilityError so callers
   // can read `.requiredCapability` to attenuate-and-retry.
   if (code === 'capability_scope_denied' || code === 'capability_invalid') {
-    return new CapabilityError(code, message, requiredCapability);
+    return new CapabilityError(code, message, requiredCapability, {
+      ...(requestId !== undefined ? { requestId } : {}),
+      ...(details !== undefined ? { details } : {}),
+    });
   }
   // Claim enforcement (rides 409): the target entity is held by another
   // participant, or a lease this participant held is gone (`claim_lost` —

package/src/resources/httpResources.ts

@@ -51,7 +51,9 @@ import type {
 import type { ModelUpdater, ContentionOptions } from './functionalUpdate.js';
 import type {
   ClaimOptions,
+  ClaimAttemptEvent,
   ClaimParams,
+  ClaimSkipParams,
   ClaimReadApi,
   AwaitedClaimMethod,
   ModelTrackParams,
@@ -147,6 +149,8 @@ export interface ClaimCreateOptions {
    * waiting if the queue is already `>= maxQueueDepth` when we join.
    */
   readonly maxQueueDepth?: number;
+  /** Request-scoped queued / granted / skipped / failed status events. */
+  readonly onStatus?: (event: ClaimAttemptEvent) => void;
 }
 
 export interface CommitOperationInput {
@@ -301,7 +305,7 @@ export type HttpClaimApi<
   // The try-claim first: `queue: false` resolves `null` on a held target —
   // an expected outcome, not an error — while the queued default always
   // resolves a held claim or rejects with a queue error.
-  ((params: ClaimParams<Fields> & { queue: false }) => Promise<HeldClaim<T> | null>) &
+  ((params: ClaimSkipParams<Fields>) => Promise<HeldClaim<T> | null>) &
   ((params: ClaimParams<Fields>) => Promise<HeldClaim<T>>) & {
     [K in keyof ClaimReadApi<T>]: AwaitedClaimMethod<ClaimReadApi<T>[K]>;
   };

package/src/resources/modelOperations.ts

@@ -12,7 +12,7 @@
 
 import type { ModelScope } from '../types/index.js';
 import type { ResolveClaimMeta } from '../types/global.js';
-import type { AbloClaimedError } from '../errors.js';
+import type { AbloError } from '../errors.js';
 import type { StaleNotification, TrackDependency } from '../coordination/schema.js';
 import type { FieldRef, FieldSelector } from '../schema/fieldRef.js';
 import type { BaseModelFields } from '../schema/schema.js';
@@ -29,6 +29,112 @@ import type {
 import type { MutationOptions } from './mutationOptions.js';
 import type { LoadWhere } from './where.js';
 
+/**
+ * One authoritative status transition for a claim attempt. This is scoped
+ * to the request that supplied the callback, unlike `claim.state` / `queue`,
+ * which are reactive snapshots of everyone on the row.
+ */
+export type ClaimAttemptEvent =
+  | {
+      readonly type: 'queued';
+      readonly claimId: string;
+      /** Zero-based place in line (`0` means next behind the holder). */
+      readonly position: number;
+      /** Human-readable count of waiters ahead, including the current holder. */
+      readonly ahead: number;
+    }
+  | {
+      readonly type: 'granted';
+      readonly claimId: string;
+      /** True when this request waited in line before it was granted. */
+      readonly waited: boolean;
+    }
+  | {
+      readonly type: 'skipped';
+      /** The typed contention error behind the expected `null` result. */
+      readonly error: AbloError;
+    }
+  | {
+      readonly type: 'failed';
+      /** The same typed Ablo error the claim promise rejects with. */
+      readonly error: AbloError;
+    };
+
+export interface ClaimContentionOptions {
+  /**
+   * `wait` (default) joins the FIFO line. `skip` resolves the model try-claim
+   * as `null` when another participant holds the target.
+   */
+  readonly mode?: 'wait' | 'skip';
+  /** Fail instead of joining at or beyond this zero-based queue depth. */
+  readonly maxDepth?: number;
+  /** Maximum queue wait in milliseconds. */
+  readonly timeoutMs?: number;
+  /** Abort the pending wait. Ignored after the grant. */
+  readonly signal?: AbortSignal;
+  /**
+   * Request-scoped attempt statuses. The callback is observational:
+   * throwing from it never changes whether the claim is granted or skipped.
+   */
+  readonly onStatus?: (event: ClaimAttemptEvent) => void;
+}
+
+export interface ResolvedClaimContentionOptions {
+  readonly wait: boolean;
+  readonly maxDepth?: number;
+  readonly timeoutMs?: number;
+  readonly signal?: AbortSignal;
+  readonly onStatus?: (event: ClaimAttemptEvent) => void;
+}
+
+/** One compatibility boundary for structured contention and legacy queue options. */
+export function resolveClaimContentionOptions(options: {
+  readonly queue?: boolean;
+  readonly contention?: ClaimContentionOptions;
+  readonly maxQueueDepth?: number;
+  readonly waitTimeoutMs?: number;
+  readonly signal?: AbortSignal;
+}): ResolvedClaimContentionOptions {
+  const structured = options.contention;
+  const maxDepth = structured?.maxDepth ?? options.maxQueueDepth;
+  const timeoutMs = structured?.timeoutMs ?? options.waitTimeoutMs;
+  const signal = structured?.signal ?? options.signal;
+  return {
+    wait: structured
+      ? structured.mode !== 'skip'
+      : options.queue !== false,
+    ...(maxDepth !== undefined ? { maxDepth } : {}),
+    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    ...(signal !== undefined ? { signal } : {}),
+    ...(structured?.onStatus !== undefined
+      ? { onStatus: structured.onStatus }
+      : {}),
+  };
+}
+
+/** Emit a status without letting an observer alter the claim attempt. */
+export function emitClaimStatus(
+  listener: ((event: ClaimAttemptEvent) => void) | undefined,
+  event: ClaimAttemptEvent,
+): void {
+  try {
+    listener?.(event);
+  } catch {
+    // The claim attempt is authoritative; telemetry/UI callbacks are not.
+  }
+}
+
+/** Separate expected skipped work from an actual failed claim attempt. */
+export function claimAttemptFailure(
+  wait: boolean,
+  error: AbloError,
+): ClaimAttemptEvent {
+  const code = error.code;
+  return !wait && (code === 'claim_conflict' || code === 'entity_claimed')
+    ? { type: 'skipped', error }
+    : { type: 'failed', error };
+}
+
 /**
  * A lifecycle filter, accepted either as the enum or as its bare string. The
  * string arm is a template projection of the enum rather than a second list, so
@@ -142,8 +248,7 @@ export type ClaimField<T> = FieldRef<
  * - **what you claim** — `fields`, selected from the model's Zod shape;
  *   narrowed below the row;
  * - **what others see** — `description` / `meta`, the presence half;
- * - **how you wait** — `queue` / `maxQueueDepth` / `waitTimeoutMs` /
- *   `signal`, admission to the line;
+ * - **how you wait** — structured `queue`, admission to the line;
  * - **how long you hold** — `ttl` / `heartbeat`, the lease.
  */
 export interface ClaimTargetOptions<T = Record<string, unknown>> {
@@ -175,18 +280,20 @@ export interface ClaimTargetOptions<T = Record<string, unknown>> {
    */
   meta?: ResolveClaimMeta;
 
-  // ── How you wait — admission to the line ───────────────────────────────
+  // ── How you handle contention ──────────────────────────────────────────
 
   /**
-   * Behavior under contention. `true` (the default) queues behind the current
-   * holder and resolves once the row is yours. `false` is fail-fast: if another
-   * participant already holds the row, it rejects immediately with
-   * {@link AbloClaimedError} instead of waiting. Use `false` to deduplicate
-   * distributed work ("if someone else has this job, skip it"), where waiting
-   * would mean double-processing.
+   * Behavior under contention. Prefer the structured form so the decision,
+   * bounds, cancellation, and request-scoped notifications stay together:
+   * `contention: { mode: 'wait', maxDepth, timeoutMs, signal, onStatus }`.
+   * `{ mode: 'skip' }` is claim-or-skip dedup.
    */
+  contention?: ClaimContentionOptions;
+  /** Concise compatibility shorthand: `true` waits and `false` skips. */
   queue?: boolean;
   /**
+   * @deprecated Prefer `contention: { maxDepth }`.
+   *
    * Backpressure: queue, but not behind too many others. If the server reports a
    * position at or beyond `maxQueueDepth` when the client joins the line, it
    * rejects with {@link AbloClaimedError} (`queue_too_deep`) instead of waiting.
@@ -194,6 +301,8 @@ export interface ClaimTargetOptions<T = Record<string, unknown>> {
    */
   maxQueueDepth?: number;
   /**
+   * @deprecated Prefer `contention: { timeoutMs }`.
+   *
    * Cap on how long a queued claim waits for its grant before rejecting with
    * {@link AbloClaimedError} (`grant_timeout`). Omit to wait as long as the
    * line takes. Same meaning on both transports; on the stateless HTTP client
@@ -201,6 +310,8 @@ export interface ClaimTargetOptions<T = Record<string, unknown>> {
    */
   waitTimeoutMs?: number;
   /**
+   * @deprecated Prefer `contention: { signal }`.
+   *
    * Abort a pending wait from outside — the same signal that cancels
    * everything else in the program, so a cancelled agent task or an unmounted
    * component takes its queued claim with it. Rejects with
@@ -234,6 +345,14 @@ export interface ClaimParams<T = Record<string, unknown>>
   readonly id: string;
 }
 
+/** The two fail-fast spellings, kept as one overload discriminator. */
+export type ClaimSkipParams<T = Record<string, unknown>> =
+  ClaimParams<T> & {
+    readonly queue: false;
+  } | ClaimParams<T> & {
+    readonly contention: ClaimContentionOptions & { readonly mode: 'skip' };
+  };
+
 export interface ClaimLookupParams<T = Record<string, unknown>> {
   readonly id: string;
 }
@@ -243,6 +362,32 @@ export interface ClaimReorderParams<T = Record<string, unknown>>
   readonly order: readonly Claim[];
 }
 
+/**
+ * One wait-line snapshot. `data` preserves the standard list-envelope shape;
+ * the named aliases make coordination code read without unpacking conventions.
+ */
+export interface ClaimQueueView<M = ResolveClaimMeta> {
+  readonly object: 'list';
+  readonly data: readonly Claim<Record<string, unknown>, M>[];
+  /** The same ordered array as `data`, named for what it contains. */
+  readonly waiting: readonly Claim<Record<string, unknown>, M>[];
+  readonly size: number;
+  /** The next participant to receive the lease, or `null` when the line is empty. */
+  readonly next: Claim<Record<string, unknown>, M> | null;
+}
+
+export function claimQueueView<M = ResolveClaimMeta>(
+  waiting: readonly Claim<Record<string, unknown>, M>[],
+): ClaimQueueView<M> {
+  return {
+    object: 'list',
+    data: waiting,
+    waiting,
+    size: waiting.length,
+    next: waiting[0] ?? null,
+  };
+}
+
 /**
  * A claim handle: the held entity data plus an explicit release hook.
  *
@@ -272,6 +417,13 @@ export type { Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease
 
 export type ClaimOptions<T = Record<string, unknown>> = ClaimTargetOptions<T>;
 
+export type ClaimSkipOptions<T = Record<string, unknown>> =
+  ClaimOptions<T> & {
+    readonly queue: false;
+  } | ClaimOptions<T> & {
+    readonly contention: ClaimContentionOptions & { readonly mode: 'skip' };
+  };
+
 /**
  * The coordination surface for a model, exposed as a callable namespace.
  *
@@ -346,10 +498,7 @@ export interface ClaimReadApi<T = Record<string, unknown>> {
    */
   queue<M = ResolveClaimMeta>(
     params: ClaimLookupParams<T>,
-  ): {
-    readonly object: 'list';
-    readonly data: readonly Claim<Record<string, unknown>, M>[];
-  };
+  ): ClaimQueueView<M>;
 
   /**
    * Re-rank the wait line. Advanced and permission-gated.
@@ -376,14 +525,15 @@ export interface ClaimApi<
   Fields = T,
 > extends ClaimReadApi<T> {
   /**
-   * The try-claim: `queue: false` treats a held target as an expected outcome,
-   * not an error — it resolves `null`, so claim-or-skip dedup reads
+   * The try-claim: `contention: { mode: 'skip' }` (or `queue: false`)
+   * treats a held target as an expected outcome, not an error — it resolves
+   * `null`, so claim-or-skip dedup reads
    * `if (!claim) return` with no try/catch. Who holds it, and why, stays
    * readable through `claim.state({ id })`. (A write to a row someone else
    * holds still rejects with `entity_claimed` — a failed write is an error;
-   * a declined try is not.)
+   * a skipped try is not.)
    */
-  (params: ClaimParams<Fields> & { queue: false }): Promise<HeldClaim<T> | null>;
+  (params: ClaimSkipParams<Fields>): Promise<HeldClaim<T> | null>;
   /**
    * Takes a claim and returns an explicit held-work handle — a {@link HeldClaim}.
    * `data`, `release`, `revoke`, and the async disposer are always present (this
@@ -392,7 +542,7 @@ export interface ClaimApi<
    */
   (params: ClaimParams<Fields>): Promise<HeldClaim<T>>;
   /** The row-free try-claim — `null` when the key is already held. */
-  (id: string, opts: ClaimOptions<Fields> & { queue: false }): Promise<HeldLease | null>;
+  (id: string, opts: ClaimSkipOptions<Fields>): Promise<HeldLease | null>;
   /**
    * Takes a claim by id alone, for a row that lives only in the customer's own
    * database — Ablo has never seen it, so there is nothing to re-read. Returns a