@abloatai/transaction 0.59.2 → 0.61.0

package/src/transport/http/transport.ts

@@ -28,6 +28,7 @@ import {
   readProcessEnv,
   resolveApiKey,
   resolveApiKeyValue,
+  resolveCredentialValue,
   resolveAuthToken,
   resolveBaseURL,
   resolveBootstrapBaseUrl,
@@ -52,7 +53,6 @@ import {
   DEFAULT_CLAIM_TTL_MS,
   type ClaimHeartbeatReply,
   type ClaimListResponse,
-  type ClaimQueuedResponse,
   type ClaimRequest,
   type ClaimState,
   type ClaimTargetBody,
@@ -68,7 +68,7 @@ import {
   resolveHeartbeatPlan,
   startClaimHeartbeatLoop,
 } from '../../claims/heartbeat.js';
-import type { HttpClientConfig } from './options.js';
+import type { HttpTransport, HttpTransportOptions } from './contract.js';
 import type {
   ClaimedOptions,
   CommitCreateOptions,
@@ -86,15 +86,10 @@ import type {
   HttpTransportList,
   HttpLogsResource,
   ModelTarget,
-  CreateSessionParams,
-  AbloSession,
-  SessionResource,
 } from '../../client/resources/httpResources.js';
-import { mintSession } from '../../auth/sessionMint.js';
-import {
-  revokeCapability,
-  rotateCapability,
-} from '../../auth/capabilityLifecycle.js';
+import type { CredentialProviderResult } from '../../auth/credentialResult.js';
+import { credentialToken } from '../../auth/credentialResult.js';
+import { createSessionAccess } from '../../sessions/index.js';
 import { parseIdentityResolveResponse } from '../../auth/schemas.js';
 import type { EffectiveAuthority } from '../../auth/capability.js';
 
@@ -103,7 +98,6 @@ import {
   heldHeartbeatReply,
   parseSuccessfulCommitResponse,
 } from './helpers.js';
-import type { SchemaRecord } from '../../schema/schema.js';
 import type {
   ClaimLookupParams,
   ClaimOptions,
@@ -113,7 +107,6 @@ import type {
   ClaimReorderParams,
   ModelCreateManyParams,
   ServerReadOptions,
-  ResolvedClaimContentionOptions,
   ClaimQueueView,
 } from '../../client/resources/modelOperations.js';
 import {
@@ -124,12 +117,6 @@ import {
 } from '../../client/resources/modelOperations.js';
 import type { Duration } from '../../utils/duration.js';
 import { claimDescription, partName } from '../../coordination/schema.js';
-import type {
-  ClaimAcquired,
-  ClaimBeginPayload,
-  ClaimGranted,
-  ClaimQueued,
-} from '../../coordination/schema.js';
 import type { BatchFence } from '../../claims/locator.js';
 import {
   subTarget,
@@ -146,7 +133,6 @@ import type {
   HeldClaim,
   HeldLease,
 } from '../../types/streams.js';
-import type { CoordinationObservability } from '../../observability.js';
 import {
   assertWriteOptions,
   assertWriteTarget,
@@ -174,95 +160,14 @@ import {
   type ExactHttpCommitRequest,
 } from '../../commit/httpRequest.js';
 import { resolveDurableWrites } from '../../commit/durableWrites.js';
-import { createHttpReadOnChange, type HttpReadOnChange } from './subscription.js';
+import { createHttpReadOnChange } from './subscription.js';
+import { awaitClaimGrantOverHttp } from './claimWait.js';
 import type { CommitFrameOperation } from '../websocket/commitFrames.js';
 
-/** @internal Private options for the schema-agnostic HTTP protocol transport. */
-export type HttpTransportOptions = Omit<HttpClientConfig, 'schema'> & {
-  readonly bootstrapBaseUrl?: string | undefined;
-  /** Schema-key to wire-typename mapping used only when minting agent sessions. */
-  readonly modelTypenames?: Readonly<Record<string, string>> | undefined;
-  /**
-   * The observability provider forwarded from `Ablo({ observability })`. The HTTP
-   * transport emits the same claim and conflict events as the WebSocket transport,
-   * so a `ClaimLog` works identically for headless server-agent evaluations.
-   */
-  readonly observability?: CoordinationObservability;
-  /**
-   * Per-request deadline in milliseconds for the stateless HTTP transport.
-   * Every request this client issues is aborted after this long and surfaces
-   * as a retryable connection error — without it a black-holed server hangs
-   * a headless agent forever (browsers never time fetch out on their own).
-   * Pass `0` to disable the deadline.
-   *
-   * @default 30_000
-   */
-  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;
-  }) => void) | undefined;
-};
-
 /** @internal Default per-request deadline for the private HTTP transport. */
 export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 const HTTP_CONFIRMATION_POLL_INTERVAL_MS = 250;
-// NOTE: end-user / agent session minting is `ablo.sessions.create(...)` (typed
-// against the schema, see Ablo.ts `CreateSessionParams`). There is no separate
-// `ephemeralKeys` resource — `sessions` is the one front door for both.
-
-/** @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;
-  /**
-   * Claim-ticket operations keyed by `claimId` — the id a queued acquire
-   * hands back on `AbloClaimedError('claim_queued')`. See
-   * {@link HttpClaimsResource}.
-   */
-  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 active bearer credential this client authenticates with — the
-   * same token its own requests carry in `Authorization`. Returns `null` when
-   * no credential is configured. Async because the API key may be supplied as
-   * an async setter. Use it to authenticate a side-band request to the same
-   * server with the credential this client already holds — no re-mint.
-   */
-  getAuthToken(): Promise<string | null>;
-  /**
-   * Mint a short-lived scoped session. Minting is a control-plane HTTP call (no
-   * socket), so it lives on this stateless client too, not only the realtime one.
-   * `{ user }` mints an `ek_`; `{ agent, can }` mints an `rk_`.
-   */
-  readonly sessions: SessionResource<SchemaRecord>;
-}
-
+const ignoreBestEffortClaimReleaseFailure = (): undefined => undefined;
 type CommitResponse = CommitReceiptWire;
 
 /** @internal Constructed only by the typed HTTP facade. */
@@ -466,6 +371,12 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     return headers;
   }
 
+  async function activeCredential(): Promise<CredentialProviderResult> {
+    return (await resolveCredentialValue(configuredApiKey)) ?? configuredAuthToken ?? null;
+  }
+
+  const access = createSessionAccess(options.session, activeCredential);
+
   function endpoint(path: string): string {
     const target = new URL(`${apiBaseUrl}${path.startsWith('/') ? path : `/${path}`}`);
     for (const [key, value] of Object.entries(options.defaultQuery ?? {})) {
@@ -1177,118 +1088,6 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     },
   };
 
-  // How the stateless client waits its turn. The queued slot is real server
-  // state, so one heartbeat per tick does both jobs: it refreshes this
-  // waiter's slot and reports the line's answer — `queued` (still waiting) or
-  // `held` (granted). The first check comes quickly because most holds are a
-  // short claim→write→release; after that the cadence relaxes, with jitter so
-  // a fleet of waiters doesn't beat in step.
-  const GRANT_POLL_FIRST_MS = 250;
-  const GRANT_POLL_INTERVAL_MS = 1_000;
-  // An abort cuts the sleep short so the wait ends within a tick of the
-  // signal, not at the next scheduled beat.
-  const sleep = (ms: number, signal?: AbortSignal): Promise<void> =>
-    new Promise((resolve) => {
-      const done = (): void => {
-        clearTimeout(timer);
-        signal?.removeEventListener('abort', done);
-        resolve();
-      };
-      const timer = setTimeout(done, ms);
-      signal?.addEventListener('abort', done, { once: true });
-    });
-
-  async function awaitGrantOverHttp(
-    targetLabel: string,
-    queued: ClaimQueuedResponse,
-    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.
-    const claimId = queued.id;
-    const { signal } = options;
-    // Leave the line before rejecting: an abandoned slot would otherwise sit
-    // in the queue until its TTL lapses, stalling every waiter behind it.
-    const rejectAndLeave = async (error: AbloClaimedError): Promise<never> => {
-      await claims.release({ claimId }).catch(() => {});
-      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(
-        new AbloClaimedError(
-          `Claim queue for ${targetLabel} is ${queued.position} deep (max ${options.maxDepth}).`,
-          { code: '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(
-          new AbloClaimedError(
-            `The wait for the claim on ${targetLabel} was aborted before the grant arrived.`,
-            { code: 'claim_wait_aborted' }
-          )
-        );
-      }
-      if (deadline !== undefined && Date.now() >= deadline) {
-        return rejectAndLeave(
-          new AbloClaimedError(
-            `Timed out after ${options.timeoutMs}ms waiting for the queue grant on ${targetLabel}.`,
-            { code: 'grant_timeout' }
-          )
-        );
-      }
-      await sleep(
-        deadline !== undefined ? Math.min(delay, Math.max(0, deadline - Date.now())) : delay,
-        signal
-      );
-      if (signal?.aborted) {
-        return rejectAndLeave(
-          new AbloClaimedError(
-            `The wait for the claim on ${targetLabel} was aborted before the grant arrived.`,
-            { code: 'claim_wait_aborted' }
-          )
-        );
-      }
-      delay = GRANT_POLL_INTERVAL_MS * (0.85 + Math.random() * 0.3);
-      // A lease that ended answers the beat with 409 `claim_lost`, which the
-      // wire error mapping raises as AbloClaimedError before this reads
-      // anything — the wait fails with the loss, as the socket wait does.
-      const beat = await claims.heartbeat({ claimId });
-      if (beat.status !== 'held') continue;
-      // Granted. The heartbeat ack does not carry the fence token — the claim
-      // state does, server-stamped at grant.
-      const state = await claims.retrieve({ claimId });
-      if (state.status !== 'active') {
-        return rejectAndLeave(
-          new AbloClaimedError(`Claim lost while queued for ${targetLabel}.`, {
-            code: 'claim_lost',
-          })
-        );
-      }
-      emitClaimStatus(options.onStatus, {
-        type: 'granted',
-        claimId,
-        waited: true,
-      });
-      return state.fenceToken !== undefined
-        ? { id: claimId, fenceToken: state.fenceToken }
-        : { id: claimId };
-    }
-  }
-
   async function applyClaimedPolicy(
     target: Partial<ModelTarget>,
     options?: ClaimedOptions,
@@ -1742,7 +1541,8 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       // the manual ticket surface.)
       if (body.status === 'queued') {
         try {
-          return await awaitGrantOverHttp(
+          return await awaitClaimGrantOverHttp(
+            claims,
             `${name}/${params.id}`,
             body,
             contention,
@@ -1775,8 +1575,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     ): Promise<void> => {
       const entityId = isClaimHandle(params) ? params.target.id : params.id;
       if (claimId && options.releaseDispatchedClaim) {
-        options.releaseDispatchedClaim({ claimId, entityType: name, entityId });
-        return Promise.resolve();
+        return options.releaseDispatchedClaim({ claimId, entityType: name, entityId });
       }
       return requestRaw(claimPath(entityId), {
         method: 'DELETE',
@@ -1904,7 +1703,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         description: claimDescription(params),
         release,
         revoke: () => {
-          void release().catch(() => {});
+          void release().catch(ignoreBestEffortClaimReleaseFailure);
         },
         heartbeat,
         [Symbol.asyncDispose]: release,
@@ -1919,7 +1718,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       // this credential until the TTL lapses, behind no handle anyone can
       // release, and every other participant is refused for the duration.
       if (data === undefined) {
-        await release().catch(() => undefined);
+        await release().catch(ignoreBestEffortClaimReleaseFailure);
         throw new AbloNotFoundError(
           `Cannot claim ${name}/${params.id}: it does not exist (or is outside this credential's scope). ` +
             `To hold a key before its row exists, claim it by id alone: claim('${params.id}') returns a lease without a snapshot.`,
@@ -2026,7 +1825,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           claim: undefined,
         });
       } finally {
-        await releaseClaim({ id }, claimId).catch(() => {});
+        await releaseClaim({ id }, claimId).catch(ignoreBestEffortClaimReleaseFailure);
       }
     };
 
@@ -2222,64 +2021,12 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     claims,
     logs,
     model,
-    sessions: {
-      async create(params: CreateSessionParams<SchemaRecord>): Promise<AbloSession> {
-        // Stateless mint: the configured key is the control-plane credential here
-        // (no startup `rk_` exchange runs on this client). It reuses the resolved
-        // base URL and fetch; the shared `mintSession` handles the two server routes.
-        const apiKey = await resolveApiKeyValue(configuredApiKey);
-        if (!apiKey) {
-          throw new AbloAuthenticationError(
-            'sessions.create requires a secret (sk_) API key — call it from your backend, not the browser.',
-            { code: 'apikey_missing' }
-          );
-        }
-        // A transport built without a schema has no way to translate `can`'s
-        // schema keys into the type names the server gates on. Minting anyway
-        // would spell every override wrong and surface as
-        // `capability_scope_denied` on the agent's first write, so refuse here
-        // instead of guessing.
-        if (!options.modelTypenames) {
-          throw new AbloValidationError(
-            'sessions.create needs the schema this client is bound to. Construct it ' +
-              "through Ablo({ schema, apiKey, transport: 'http' }) rather than the " +
-              'bare transport.',
-            { code: 'invalid_options', param: 'schema' },
-          );
-        }
-        return mintSession(params, {
-          apiKey,
-          baseUrl: apiBaseUrl,
-          modelTypenames: options.modelTypenames,
-          ...(options.fetch ? { fetch: options.fetch } : {}),
-        });
-      },
-      async revoke({ id }) {
-        const apiKey = await resolveApiKeyValue(configuredApiKey);
-        return revokeCapability({
-          apiKey: apiKey ?? '',
-          baseUrl: apiBaseUrl,
-          id,
-          ...(options.fetch ? { fetch: options.fetch } : {}),
-        });
-      },
-      async rotate({ id, graceSeconds, ttlSeconds }) {
-        const apiKey = await resolveApiKeyValue(configuredApiKey);
-        return rotateCapability({
-          apiKey: apiKey ?? '',
-          baseUrl: apiBaseUrl,
-          id,
-          ...(graceSeconds !== undefined ? { graceSeconds } : {}),
-          ...(ttlSeconds !== undefined ? { ttlSeconds } : {}),
-          ...(options.fetch ? { fetch: options.fetch } : {}),
-        });
-      },
-    },
     async getAuthToken(): Promise<string | null> {
       // Mirror `authHeaders()`: a configured API key wins, else the
       // construction-time auth token. Resolve the (possibly async) key setter.
-      return (await resolveApiKeyValue(configuredApiKey)) ?? configuredAuthToken ?? null;
+      return credentialToken(await activeCredential());
     },
+    access,
   };
 }
 

package/src/transport/websocket/commitFrames.ts

@@ -17,7 +17,6 @@ import type {
   ClaimQueued,
   ClaimLost,
   ClaimRejection,
-  ClaimExpired,
 } from '../../coordination/schema.js';
 import type { ClaimEvent, ClaimCounterparty } from '../../claims/events.js';
 import type { AssertExact } from '../../types/assertExact.js';
@@ -105,7 +104,6 @@ interface ClaimFrameByPhase {
   queued: ClaimQueued;
   lost: ClaimLost;
   rejected: ClaimRejection;
-  expired: ClaimExpired;
 }
 
 // The phases this map covers and the phases a ClaimEvent can report are the

package/src/transport/websocket/frameHandlers.ts

@@ -45,16 +45,6 @@ export interface PendingCommit {
   readonly returnReceipt?: boolean;
 }
 
-/**
- * In-flight `claim` request record, keyed by claimId. Resolved when the
- * matching `claim_ack` arrives, or rejected on timeout/disconnect.
- */
-export interface PendingClaim {
-  resolve: (value: { syncGroups: string[]; ttlSeconds?: number }) => void;
-  reject: (err: Error) => void;
-  timeout: ReturnType<typeof setTimeout>;
-}
-
 /**
  * An in-flight `update_subscription` request awaiting its
  * `subscription_ack`. The wire carries no correlation id, so requests are
@@ -109,8 +99,6 @@ export interface WsSession {
   observability: SocketObservability;
   /** In-flight commit acks keyed by clientTxId. */
   pendingMutations: Map<string, PendingCommit>;
-  /** In-flight claim acks keyed by claimId. */
-  pendingClaims: Map<string, PendingClaim>;
   /** Removes and returns the oldest in-flight `update_subscription` request. */
   shiftPendingSubscription(): PendingSubscription | undefined;
   /** Connection options subset the handlers write back (acked sync groups). */
@@ -290,84 +278,6 @@ const handleMutationResult: WsFrameHandler = (session, message) => {
   }
 };
 
-/**
- * Handles the acknowledgement of a `claim` request. The frame has the shape
- * `{ type: 'claim_ack', payload: { claimId, success, syncGroups?,
- * ttlSeconds?, error? } }`.
- */
-const handleClaimAck: WsFrameHandler = (session, message) => {
-  const p = (message.payload ?? {}) as Record<string, unknown>;
-  const { claimId, success, syncGroups, ttlSeconds, error } = p;
-  const pending =
-    typeof claimId === 'string'
-      ? session.pendingClaims.get(claimId)
-      : undefined;
-  if (!pending) return;
-  clearTimeout(pending.timeout);
-  // `pending` exists ⇒ claimId was a string key (the guard above).
-  session.pendingClaims.delete(claimId as string);
-  if (success) {
-    pending.resolve({
-      syncGroups: Array.isArray(syncGroups) ? syncGroups : [],
-      ttlSeconds: typeof ttlSeconds === 'number' ? ttlSeconds : undefined,
-    });
-  } else {
-    const err = error as
-      | {
-          code?: unknown;
-          message?: unknown;
-          request_id?: unknown;
-          event_id?: unknown;
-        }
-      | undefined;
-    const code =
-      err?.code && typeof err.code === 'string'
-        ? err.code
-        : 'claim_rejected';
-    const msg =
-      err?.message && typeof err.message === 'string'
-        ? err.message
-        : 'claim rejected by server';
-    const requestId =
-      typeof err?.request_id === 'string' ? err.request_id : undefined;
-    const eventId =
-      typeof err?.event_id === 'string' ? err.event_id : undefined;
-    const details = eventId === undefined ? undefined : { event_id: eventId };
-    // Capability denials get the typed CapabilityError so
-    // callers can read `.requiredCapability` and attenuate-
-    // and-retry the claim with a narrower token.
-    if (
-      code === 'capability_scope_denied' ||
-      code === 'capability_invalid'
-    ) {
-      const rc = (error as { requiredCapability?: unknown } | undefined)
-        ?.requiredCapability;
-      const requiredCapability =
-        rc != null &&
-        typeof rc === 'object' &&
-        typeof (rc as { scope?: unknown }).scope === 'string'
-          ? (rc as RequiredCapability)
-          : undefined;
-      pending.reject(
-        new CapabilityError(code, msg, requiredCapability, {
-          ...(requestId !== undefined ? { requestId } : {}),
-          ...(details !== undefined ? { details } : {}),
-        }),
-      );
-    } else {
-      // Route through the shared factory so a failed claim_ack is a
-      // typed AbloError (registry code → right subclass), symmetric
-      // with the commit `mutation_result` path — never a bare Error.
-      pending.reject(
-        errorFromWire(msg, {
-          code,
-          requestId,
-          details,
-        }),
-      );
-    }
-  }
-};
 
 /**
  * Handles the acknowledgement of an `update_subscription` request. The wire
@@ -448,7 +358,6 @@ export const wsFrameHandlers: Record<string, WsFrameHandler> = {
   bootstrap_response: (session, message) => { session.handleBootstrapResponse(message.payload); },
   presence_update: (session, message) => { session.handlePresenceUpdate(message); },
   mutation_result: handleMutationResult,
-  claim_ack: handleClaimAck,
   subscription_ack: handleSubscriptionAck,
   delta: handleDeltaFrame,
 };
@@ -497,17 +406,6 @@ const validatedFrameHandlers: Record<
       session.handlePresenceUpdate({ payload });
     },
   ),
-  claim_expired: validating(
-    WS_INBOUND_FRAMES.claim_expired.payload,
-    'claim_expired',
-    (session, payload) => {
-      // Server-initiated expiry. The claim is already inactive by the time
-      // this arrives, so a consumer either re-claims with a fresh credential
-      // or accepts the drop.
-      recordClaim(tracePorts(session), 'expired', payload);
-      session.emit('claim_expired', payload);
-    },
-  ),
   claim_rejected: validating(
     WS_INBOUND_FRAMES.claim_rejected.payload,
     'claim_rejected',
@@ -527,6 +425,13 @@ const validatedFrameHandlers: Record<
       session.emit('claim_acquired', payload);
     },
   ),
+  claim_abandon_ack: validating(
+    WS_INBOUND_FRAMES.claim_abandon_ack.payload,
+    'claim_abandon_ack',
+    (session, payload) => {
+      session.emit('claim_abandon_ack', payload);
+    },
+  ),
   claim_queued: validating(
     WS_INBOUND_FRAMES.claim_queued.payload,
     'claim_queued',