@abloatai/transaction 0.44.0 → 0.45.0

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

package/src/transport/httpTransport.ts

@@ -8,6 +8,7 @@
 
 import {
   AbloClaimedError,
+  AbloError,
   AbloAuthenticationError,
   AbloConnectionError,
   AbloIdempotencyError,
@@ -113,10 +114,19 @@ import type {
   ClaimLookupParams,
   ClaimOptions,
   ClaimParams,
+  ClaimSkipParams,
   ClaimReorderParams,
   ModelTrackParams,
   ModelTrackResult,
   ServerReadOptions,
+  ResolvedClaimContentionOptions,
+  ClaimQueueView,
+} from '../resources/modelOperations.js';
+import {
+  claimAttemptFailure,
+  claimQueueView,
+  emitClaimStatus,
+  resolveClaimContentionOptions,
 } from '../resources/modelOperations.js';
 import type { Duration } from '../utils/duration.js';
 import type { TrackDependency } from '../coordination/schema.js';
@@ -1148,7 +1158,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
   async function awaitGrantOverHttp(
     targetLabel: string,
     queued: ClaimQueuedResponse,
-    options: { maxQueueDepth?: number; waitTimeoutMs?: number; signal?: AbortSignal }
+    options: ResolvedClaimContentionOptions,
   ): Promise<{ id: string; fenceToken?: number }> {
     // The queued reply is a claim resource in its waiting state, so the
     // handle is its `id` — same rule as the 201 and the poll.
@@ -1161,17 +1171,24 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       throw error;
     };
 
-    if (options.maxQueueDepth !== undefined && queued.position >= options.maxQueueDepth) {
+    emitClaimStatus(options.onStatus, {
+      type: 'queued',
+      claimId,
+      position: queued.position,
+      ahead: queued.position + 1,
+    });
+
+    if (options.maxDepth !== undefined && queued.position >= options.maxDepth) {
       return rejectAndLeave(
         new AbloClaimedError(
-          `Claim queue for ${targetLabel} is ${queued.position} deep (max ${options.maxQueueDepth}).`,
+          `Claim queue for ${targetLabel} is ${queued.position} deep (max ${options.maxDepth}).`,
           { code: 'queue_too_deep' }
         )
       );
     }
 
     const deadline =
-      options.waitTimeoutMs !== undefined ? Date.now() + options.waitTimeoutMs : undefined;
+      options.timeoutMs !== undefined ? Date.now() + options.timeoutMs : undefined;
     let delay = GRANT_POLL_FIRST_MS;
     for (;;) {
       if (signal?.aborted) {
@@ -1185,7 +1202,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       if (deadline !== undefined && Date.now() >= deadline) {
         return rejectAndLeave(
           new AbloClaimedError(
-            `Timed out after ${options.waitTimeoutMs}ms waiting for the queue grant on ${targetLabel}.`,
+            `Timed out after ${options.timeoutMs}ms waiting for the queue grant on ${targetLabel}.`,
             { code: 'grant_timeout' }
           )
         );
@@ -1218,6 +1235,11 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           })
         );
       }
+      emitClaimStatus(options.onStatus, {
+        type: 'granted',
+        claimId,
+        waited: true,
+      });
       return state.fenceToken !== undefined
         ? { id: claimId, fenceToken: state.fenceToken }
         : { id: claimId };
@@ -1492,6 +1514,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     const acquireClaim = async (
       params: ClaimParams<Fields>
     ): Promise<{ id: string; fenceToken?: number }> => {
+      const contention = resolveClaimContentionOptions(params);
       // The row is named by the URL, so `target` carries only the narrowing a
       // claim adds below it. Sending it is what makes a field-scoped claim
       // actually field-scoped: the server's conflict rule reads `path`,
@@ -1512,13 +1535,25 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         ...(Object.keys(narrowing).length > 0 ? { target: narrowing } : {}),
         // `queue` (default true) → queue behind the holder; false → fail-fast
         // with AbloClaimedError (work-distribution dedup).
-        queue: params.queue ?? true,
+        queue: contention.wait,
       };
-      const body = await requestJson(
-        claimPath(params.id),
-        { method: 'POST', body: JSON.stringify(request) },
-        claimAcquireResponseSchema
-      );
+      let body: z.infer<typeof claimAcquireResponseSchema>;
+      try {
+        body = await requestJson(
+          claimPath(params.id),
+          { method: 'POST', body: JSON.stringify(request) },
+          claimAcquireResponseSchema
+        );
+      } catch (error) {
+        const normalized = error instanceof AbloError
+          ? error
+          : new AbloConnectionError(String(error));
+        emitClaimStatus(
+          contention.onStatus,
+          claimAttemptFailure(contention.wait, normalized),
+        );
+        throw error;
+      }
       // One resource, two states, discriminated by `status`. The queued arm
       // WAITS, exactly as the socket client does: `claim({ id })` means
       // "serialize me behind the holder" on every transport, and the grant
@@ -1527,8 +1562,28 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       // why it no longer surfaces as one here. The `claims` namespace remains
       // the manual ticket surface.)
       if (body.status === 'queued') {
-        return awaitGrantOverHttp(`${name}/${params.id}`, body, params);
+        try {
+          return await awaitGrantOverHttp(
+            `${name}/${params.id}`,
+            body,
+            contention,
+          );
+        } catch (error) {
+          const normalized = error instanceof AbloError
+            ? error
+            : new AbloConnectionError(String(error));
+          emitClaimStatus(
+            contention.onStatus,
+            claimAttemptFailure(contention.wait, normalized),
+          );
+          throw error;
+        }
       }
+      emitClaimStatus(contention.onStatus, {
+        type: 'granted',
+        claimId: body.id,
+        waited: false,
+      });
       // The lease's own fields are mirrored at the top level, the same place
       // the poll puts them — one reader for both answers.
       return body.fenceToken !== undefined
@@ -1566,7 +1621,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     };
 
     function claimImpl(
-      params: ClaimParams<Fields> & { queue: false }
+      params: ClaimSkipParams<Fields>
     ): Promise<HeldClaim<T> | null>;
     function claimImpl(params: ClaimParams<Fields>): Promise<HeldClaim<T>>;
     async function claimImpl(
@@ -1582,7 +1637,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         // and the write-site claim path calls `acquireClaim` directly, so a
         // write that could not claim still fails loudly.
         if (
-          params.queue === false &&
+          !resolveClaimContentionOptions(params).wait &&
           error instanceof AbloClaimedError &&
           (error.code === 'entity_claimed' || error.code === 'claim_conflict')
         ) {
@@ -1687,14 +1742,13 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       },
       queue: async (
         params: ClaimLookupParams<T>
-      ): Promise<{ readonly object: 'list'; readonly data: readonly Claim[] }> => {
+      ): Promise<ClaimQueueView> => {
         const res = await claimsForEntity(params);
-        return {
-          object: 'list',
-          data: res.data
+        return claimQueueView(
+          res.data
             .filter((row) => row.status === 'queued')
             .map(claimFromModelClaim),
-        };
+        );
       },
       reorder: async (params: ClaimReorderParams<T>): Promise<void> => {
         await requestRaw(`${claimPath(params.id)}/reorder`, {