@abloatai/transaction 0.60.0 → 0.61.0

package/src/errors.ts

@@ -23,12 +23,24 @@ import { ABLO_DOCS_BASE_URL } from './auth/hostedEndpoints.js';
 import { errorCodeSpec, classifyRecovery } from './errorCodes.js';
 import {
   wireClaimSummarySchema,
+  wireParticipantKindSchema,
+  modelTargetSchema,
   descriptionFromMeta,
   type WireClaimSummary,
   type ModelClaim,
   type ModelTarget,
   type ParticipantKind,
 } from './coordination/schema.js';
+import {
+  claimConflictContextSchema,
+  normalizeClaimConflict,
+  type ClaimConflictContext,
+} from './claims/conflict.js';
+
+export type {
+  ClaimConflictContext,
+  ClaimConflictCounterparty,
+} from './claims/conflict.js';
 
 export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec, RecoveryClass } from './errorCodes.js';
 export {
@@ -368,6 +380,44 @@ export interface ClaimContext {
 
 export type ClaimErrorClaim = WireClaimSummary | ClaimContext;
 
+function conflictFromClaims(
+  claims: readonly ClaimErrorClaim[] | undefined,
+): ClaimConflictContext | undefined {
+  const claim = claims?.[0];
+  if (!claim) return undefined;
+  const summary = wireClaimSummarySchema.safeParse(claim);
+  if (summary.success) {
+    const actor = 'actor' in claim && typeof claim.actor === 'string'
+      ? claim.actor
+      : undefined;
+    return normalizeClaimConflict({
+      heldByClaim: summary.data,
+      ...(actor !== undefined ? { heldBy: actor } : {}),
+    });
+  }
+  const context = claim as ClaimContext;
+  return normalizeClaimConflict({
+    ...(context.actor !== undefined ? { heldBy: context.actor } : {}),
+    ...(context.participantKind !== undefined
+      ? { heldByKind: context.participantKind }
+      : {}),
+    ...(context.claimId !== undefined ? { heldByClaimId: context.claimId } : {}),
+    ...(context.description !== undefined ? { description: context.description } : {}),
+    ...(context.expiresAt !== undefined ? { expiresAt: context.expiresAt } : {}),
+    ...(context.target !== undefined
+      ? { target: context.target }
+      : context.entityType !== undefined || context.entityId !== undefined
+        ? {
+            target: {
+              ...(context.entityType !== undefined ? { model: context.entityType } : {}),
+              ...(context.entityId !== undefined ? { id: context.entityId } : {}),
+              ...(context.field !== undefined ? { field: context.field } : {}),
+            },
+          }
+        : {}),
+  });
+}
+
 function claimDescription(claim: ClaimErrorClaim | undefined): string | undefined {
   if (!claim) return undefined;
   if ('description' in claim && typeof claim.description === 'string') {
@@ -434,6 +484,7 @@ export function formatClaimedErrorMessage(args: {
 export class AbloClaimedError extends AbloError {
   override readonly type = 'AbloClaimedError' as const;
   readonly claims?: readonly ClaimErrorClaim[];
+  readonly conflict?: ClaimConflictContext;
 
   constructor(
     message: string,
@@ -443,10 +494,22 @@ export class AbloClaimedError extends AbloError {
       requestId?: string;
       cause?: unknown;
       claims?: readonly ClaimErrorClaim[];
+      conflict?: ClaimConflictContext;
+      details?: Readonly<Record<string, unknown>>;
     },
   ) {
-    super(message, options);
+    const conflict = options?.conflict ?? conflictFromClaims(options?.claims);
+    const details = {
+      ...(options?.details ?? {}),
+      ...(options?.claims !== undefined ? { claims: options.claims } : {}),
+      ...(conflict !== undefined ? { conflict } : {}),
+    };
+    super(message, {
+      ...options,
+      ...(Object.keys(details).length > 0 ? { details } : {}),
+    });
     if (options?.claims !== undefined) this.claims = options.claims;
+    if (conflict !== undefined) this.conflict = conflict;
   }
 }
 
@@ -681,8 +744,13 @@ const NestedErrorShapeSchema = z
     field: OptionalWireStringSchema,
     requiredCapability: requiredCapabilityWireSchema.optional().catch(undefined),
     heldBy: OptionalWireStringSchema,
+    heldByKind: wireParticipantKindSchema.optional().catch(undefined),
+    heldByClaimId: OptionalWireStringSchema,
+    heldByExpiresAt: z.number().optional().catch(undefined),
     heldByClaim: wireClaimSummarySchema.optional().catch(undefined),
     claims: z.array(wireClaimSummarySchema).optional().catch(undefined),
+    conflict: claimConflictContextSchema.optional().catch(undefined),
+    target: modelTargetSchema.unwrap().partial().optional().catch(undefined),
   })
   .loose();
 
@@ -706,8 +774,13 @@ const ErrorBodyShapeSchema = z
     message: OptionalWireStringSchema,
     requiredCapability: requiredCapabilityWireSchema.optional().catch(undefined),
     heldBy: OptionalWireStringSchema,
+    heldByKind: wireParticipantKindSchema.optional().catch(undefined),
+    heldByClaimId: OptionalWireStringSchema,
+    heldByExpiresAt: z.number().optional().catch(undefined),
     heldByClaim: wireClaimSummarySchema.optional().catch(undefined),
     claims: z.array(wireClaimSummarySchema).optional().catch(undefined),
+    conflict: claimConflictContextSchema.optional().catch(undefined),
+    target: modelTargetSchema.unwrap().partial().optional().catch(undefined),
   })
   .loose();
 
@@ -763,11 +836,12 @@ export function errorFromWire(
     requestId?: string;
     requiredCapability?: RequiredCapability;
     claims?: readonly ClaimErrorClaim[];
+    conflict?: ClaimConflictContext;
     /** Everything the producer attached beyond the envelope's own fields. */
     details?: Readonly<Record<string, unknown>>;
   } = {},
 ): AbloError {
-  const { code, requestId, requiredCapability, claims, details } = opts;
+  const { code, requestId, requiredCapability, claims, conflict, details } = opts;
   // Effective status: an explicit HTTP status wins; otherwise fall back to
   // the code's canonical status from the registry (undefined for unknown /
   // forward-compat codes, which then map to the base AbloError).
@@ -802,9 +876,16 @@ export function errorFromWire(
   if (
     code === 'claim_conflict' ||
     code === 'entity_claimed' ||
-    code === 'claim_lost'
+    code === 'claim_lost' ||
+    code === 'fence_token_stale' ||
+    code === 'model_claimed' ||
+    code === 'model_claimed_timeout' ||
+    code === 'claim_lease_unavailable' ||
+    code === 'claim_wait_aborted' ||
+    code === 'grant_timeout' ||
+    code === 'claim_queued'
   ) {
-    return new AbloClaimedError(message, { ...baseOpts, claims });
+    return new AbloClaimedError(message, { ...baseOpts, claims, conflict });
   }
   // A write whose `readAt` watermark went stale — callers re-read and retry.
   if (code === 'stale_context') {
@@ -854,6 +935,12 @@ const ENVELOPE_KEYS: ReadonlySet<string> = new Set([
   'requiredCapability',
   'claims',
   'heldByClaim',
+  'heldBy',
+  'heldByKind',
+  'heldByClaimId',
+  'heldByExpiresAt',
+  'conflict',
+  'target',
   // `reason` is deliberately NOT here: it is domain detail (a driver's words
   // beside the server's message), not an envelope field — the canonical
   // envelope schema has no such key — so it must survive into `details` for a
@@ -916,6 +1003,30 @@ export function translateHttpError(
       : nested?.heldByClaim
         ? [nested.heldByClaim]
         : undefined);
+  const conflict =
+    parsed.conflict ??
+    nested?.conflict ??
+    normalizeClaimConflict({
+      ...(parsed.heldBy ?? nested?.heldBy
+        ? { heldBy: parsed.heldBy ?? nested?.heldBy }
+        : {}),
+      ...(parsed.heldByKind ?? nested?.heldByKind
+        ? { heldByKind: parsed.heldByKind ?? nested?.heldByKind }
+        : {}),
+      ...(parsed.heldByClaimId ?? nested?.heldByClaimId
+        ? { heldByClaimId: parsed.heldByClaimId ?? nested?.heldByClaimId }
+        : {}),
+      ...(parsed.heldByExpiresAt ?? nested?.heldByExpiresAt
+        ? { heldByExpiresAt: parsed.heldByExpiresAt ?? nested?.heldByExpiresAt }
+        : {}),
+      ...(parsed.heldByClaim ?? nested?.heldByClaim
+        ? { heldByClaim: parsed.heldByClaim ?? nested?.heldByClaim }
+        : {}),
+      ...(parsed.target ?? nested?.target
+        ? { target: parsed.target ?? nested?.target }
+        : {}),
+    }) ??
+    conflictFromClaims(claims);
 
   // The envelope carries `request_id`, so a caller that has only the body still
   // gets the correlation id — without this it was dropped unless the caller
@@ -935,6 +1046,7 @@ export function translateHttpError(
     requestId: requestId ?? (typeof bodyRequestId === 'string' ? bodyRequestId : undefined),
     requiredCapability,
     claims,
+    conflict,
     details: Object.keys(details).length > 0 ? details : undefined,
   });
 }

package/src/transport/http/claimWait.ts

@@ -0,0 +1,108 @@
+import { normalizeClaimConflict } from '../../claims/conflict.js';
+import type { ClaimQueuedResponse } from '../../claims/contract.js';
+import type { HttpClaimsResource } from '../../client/resources/httpResources.js';
+import {
+  emitClaimStatus,
+  type ResolvedClaimContentionOptions,
+} from '../../client/resources/modelOperations.js';
+import { AbloClaimedError } from '../../errors.js';
+
+const GRANT_POLL_FIRST_MS = 250;
+const GRANT_POLL_INTERVAL_MS = 1_000;
+const ignoreBestEffortClaimReleaseFailure = (): undefined => undefined;
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const done = (): void => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener('abort', done, { once: true });
+  });
+}
+
+/** Wait for a queued HTTP claim while keeping its server-side slot alive. */
+export async function awaitClaimGrantOverHttp(
+  claims: HttpClaimsResource,
+  targetLabel: string,
+  queued: ClaimQueuedResponse,
+  options: ResolvedClaimContentionOptions,
+): Promise<{ id: string; fenceToken?: number }> {
+  const claimId = queued.id;
+  const { signal } = options;
+  const conflict = normalizeClaimConflict({
+    ...(queued.heldBy !== undefined ? { heldBy: queued.heldBy } : {}),
+    ...(queued.heldByKind !== undefined ? { heldByKind: queued.heldByKind } : {}),
+    ...(queued.heldByClaimId !== undefined ? { heldByClaimId: queued.heldByClaimId } : {}),
+    ...(queued.expiresAt !== undefined ? { heldByExpiresAt: queued.expiresAt } : {}),
+    ...(queued.heldByClaim !== undefined ? { heldByClaim: queued.heldByClaim } : {}),
+  });
+  const waitingError = (
+    message: string,
+    code: 'queue_too_deep' | 'claim_wait_aborted' | 'grant_timeout' | 'claim_lost',
+  ): AbloClaimedError => new AbloClaimedError(message, {
+    code,
+    claims: queued.heldByClaim ? [queued.heldByClaim] : undefined,
+    conflict,
+  });
+  const rejectAndLeave = async (error: AbloClaimedError): Promise<never> => {
+    await claims.release({ claimId }).catch(ignoreBestEffortClaimReleaseFailure);
+    throw error;
+  };
+
+  emitClaimStatus(options.onStatus, {
+    type: 'queued',
+    claimId,
+    position: queued.position,
+    ahead: queued.position + 1,
+  });
+  if (options.maxDepth !== undefined && queued.position >= options.maxDepth) {
+    return rejectAndLeave(waitingError(
+      `Claim queue for ${targetLabel} is ${queued.position} deep (max ${options.maxDepth}).`,
+      'queue_too_deep',
+    ));
+  }
+
+  const deadline = options.timeoutMs !== undefined ? Date.now() + options.timeoutMs : undefined;
+  let delay = GRANT_POLL_FIRST_MS;
+  for (;;) {
+    if (signal?.aborted) {
+      return rejectAndLeave(waitingError(
+        `The wait for the claim on ${targetLabel} was aborted before the grant arrived.`,
+        'claim_wait_aborted',
+      ));
+    }
+    if (deadline !== undefined && Date.now() >= deadline) {
+      return rejectAndLeave(waitingError(
+        `Timed out after ${options.timeoutMs}ms waiting for the queue grant on ${targetLabel}.`,
+        'grant_timeout',
+      ));
+    }
+    await sleep(
+      deadline !== undefined ? Math.min(delay, Math.max(0, deadline - Date.now())) : delay,
+      signal,
+    );
+    if (signal?.aborted) {
+      return rejectAndLeave(waitingError(
+        `The wait for the claim on ${targetLabel} was aborted before the grant arrived.`,
+        'claim_wait_aborted',
+      ));
+    }
+    delay = GRANT_POLL_INTERVAL_MS * (0.85 + Math.random() * 0.3);
+    const beat = await claims.heartbeat({ claimId });
+    if (beat.status !== 'held') continue;
+    const state = await claims.retrieve({ claimId });
+    if (state.status !== 'active') {
+      return rejectAndLeave(waitingError(
+        `Claim lost while queued for ${targetLabel}.`,
+        'claim_lost',
+      ));
+    }
+    emitClaimStatus(options.onStatus, { type: 'granted', claimId, waited: true });
+    return state.fenceToken !== undefined
+      ? { id: claimId, fenceToken: state.fenceToken }
+      : { id: claimId };
+  }
+}

package/src/transport/http/client.ts

@@ -19,8 +19,8 @@
  */
 import {
   createHttpTransport,
-  type HttpTransport,
 } from './transport.js';
+import type { HttpTransport } from './contract.js';
 import type { HttpClientConfig } from './options.js';
 import type {
   CommitResource,
@@ -272,6 +272,8 @@ const PROTOCOL_MEMBERS = new Set<string>([
   'getAuthToken',
 ]);
 
+const ignoreAlreadySurfacedSessionOpeningFailure = (): undefined => undefined;
+
 /** Narrows a bare property name to a transport key so the facade can index it typed. */
 function isProtocolMember(prop: string): prop is keyof HttpTransport {
   return PROTOCOL_MEMBERS.has(prop);
@@ -555,9 +557,8 @@ export function createAbloHttpClient<S extends SchemaRecord>(
         return receipt;
       },
       dispatchClaim: async (input) => (await webSocketSession()).claim(input),
-      releaseDispatchedClaim: (input) => {
-        void webSocketSession().then((session) => session.release(input));
-      },
+      releaseDispatchedClaim: async (input) =>
+        (await webSocketSession()).release(input),
     } : {}),
   });
   const schemaModels = new Set(Object.keys(schema.models));
@@ -614,7 +615,7 @@ export function createAbloHttpClient<S extends SchemaRecord>(
     webSocketOpen.abort();
     const opening = webSocketPromise;
     if (webSocket) await webSocket.close();
-    else await opening?.then((session) => session.close()).catch(() => undefined);
+    else await opening?.then((session) => session.close()).catch(ignoreAlreadySurfacedSessionOpeningFailure);
     await transport.dispose();
   };
 

package/src/transport/http/contract.ts

@@ -0,0 +1,71 @@
+/** Private contract owned by the stateless HTTP transport boundary. */
+
+import type { HttpClientConfig } from './options.js';
+import type { CommitReceiptWire } from '../../commit/contract.js';
+import type {
+  CommitResource,
+  HttpClaimsResource,
+  HttpLogsResource,
+  HttpTransportModel,
+} from '../../client/resources/httpResources.js';
+import type {
+  ClaimAcquired,
+  ClaimBeginPayload,
+  ClaimGranted,
+  ClaimQueued,
+} from '../../coordination/schema.js';
+import type { CoordinationObservability } from '../../observability.js';
+import type { EffectiveAuthority } from '../../auth/capability.js';
+import type { SessionAccess } from '../../sessions/index.js';
+import type { CommitFrameOperation } from '../websocket/commitFrames.js';
+import type { HttpReadOnChange } from './subscription.js';
+
+/** @internal Private options for the schema-agnostic HTTP protocol transport. */
+export type HttpTransportOptions = Omit<HttpClientConfig, 'schema'> & {
+  readonly bootstrapBaseUrl?: string | undefined;
+  /** Observability forwarded from `Ablo({ observability })`. */
+  readonly observability?: CoordinationObservability;
+  /** Per-request deadline in milliseconds. Pass `0` to disable it. */
+  readonly timeoutMs?: number;
+  /** @internal Routes writes through the selected duplex transport. */
+  readonly dispatchCommit?: ((input: {
+    readonly clientTxId: string;
+    readonly operations: readonly CommitFrameOperation[];
+    readonly reads?: readonly import('../../coordination/schema.js').ReadDependency[] | null;
+  }) => Promise<CommitReceiptWire>) | undefined;
+  /** @internal Routes held-claim acquisition through the shared socket. */
+  readonly dispatchClaim?: ((input: ClaimBeginPayload & {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly onQueued?: (event: ClaimQueued) => Error | undefined;
+  }) => Promise<ClaimAcquired | ClaimGranted>) | undefined;
+  /** @internal Releases a socket-acquired claim on that same session. */
+  readonly releaseDispatchedClaim?: ((input: {
+    readonly claimId: string;
+    readonly entityType: string;
+    readonly entityId: string;
+  }) => Promise<void>) | undefined;
+};
+
+/** @internal Private protocol surface wrapped by `AbloHttpClient`. */
+export interface HttpTransport {
+  ready(): Promise<void>;
+  waitForFlush(): Promise<void>;
+  /** Drains scheduled commits and active requests. */
+  dispose(): Promise<void>;
+  purge(): Promise<void>;
+  /** @internal Live check used only by `context().onChange`. */
+  readonly onChange: HttpReadOnChange;
+  readonly commits: CommitResource;
+  readonly claims: HttpClaimsResource;
+  readonly logs: HttpLogsResource;
+  /** Server-confirmed authority of the active bearer, populated by `ready()`. */
+  readonly identity: EffectiveAuthority | null;
+  model<T = Record<string, unknown>, Fields = T>(
+    name: string,
+  ): HttpTransportModel<T, Fields>;
+  /** Resolve the bearer credential used by this transport. */
+  getAuthToken(): Promise<string | null>;
+  /** @internal One normalized source shared by HTTP bootstrap and live transport. */
+  readonly access: SessionAccess;
+}

package/src/transport/http/index.ts

@@ -1,5 +1,6 @@
 /** Stateless HTTP transport boundary. */
 export * from './options.js';
+export * from './contract.js';
 export * from './client.js';
 export * from './transport.js';
 export * from './helpers.js';