@abloatai/transaction 0.59.1 → 0.60.0

package/src/transport/http/transport.ts

@@ -28,6 +28,7 @@ import {
   readProcessEnv,
   resolveApiKey,
   resolveApiKeyValue,
+  resolveCredentialValue,
   resolveAuthToken,
   resolveBaseURL,
   resolveBootstrapBaseUrl,
@@ -86,15 +87,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, type SessionAccess } from '../../sessions/index.js';
 import { parseIdentityResolveResponse } from '../../auth/schemas.js';
 import type { EffectiveAuthority } from '../../auth/capability.js';
 
@@ -103,7 +99,6 @@ import {
   heldHeartbeatReply,
   parseSuccessfulCommitResponse,
 } from './helpers.js';
-import type { SchemaRecord } from '../../schema/schema.js';
 import type {
   ClaimLookupParams,
   ClaimOptions,
@@ -124,6 +119,12 @@ 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,
@@ -169,12 +170,11 @@ import {
 } from '../../commit/httpRequest.js';
 import { resolveDurableWrites } from '../../commit/durableWrites.js';
 import { createHttpReadOnChange, type HttpReadOnChange } from './subscription.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,
@@ -191,14 +191,29 @@ export type HttpTransportOptions = Omit<HttpClientConfig, 'schema'> & {
    * @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 {
@@ -230,12 +245,8 @@ export interface HttpTransport {
    * 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>;
+  /** @internal One normalized source shared by HTTP bootstrap and live transport. */
+  readonly access: SessionAccess;
 }
 
 type CommitResponse = CommitReceiptWire;
@@ -441,6 +452,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 ?? {})) {
@@ -981,11 +998,22 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       path: string;
       body: unknown;
       wait: CommitWait;
+      operations: readonly CommitFrameOperation[];
+      reads?: readonly import('../../coordination/schema.js').ReadDependency[] | null;
     },
     beforeConfirmation?: (response: CommitResponse) => Promise<void>
   ): Promise<CommitResponse> {
     return runInHttpCommitLane(async () => {
       await prepare();
+      if (options.dispatchCommit) {
+        const response = await options.dispatchCommit({
+          clientTxId: input.idempotencyKey,
+          operations: input.operations,
+          ...(input.reads !== undefined ? { reads: input.reads } : {}),
+        });
+        if (response.status === 'confirmed') await beforeConfirmation?.(response);
+        return response;
+      }
       // Startup preparation covers replay. Re-draining here makes every later write wait
       // behind an ambiguous predecessor from this same process.
       const replayed = await replayHttpCommitOutbox();
@@ -1296,6 +1324,17 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         reads: commitOptions.reads,
       };
       const wait = commitOptions.wait ?? 'confirmed';
+      const frameOperations: CommitFrameOperation[] = operations.map((operation) => ({
+        type: operation.action.toUpperCase(),
+        model: operation.model,
+        id: operation.id ?? null,
+        input: operation.data ?? null,
+        where: operation.where ?? null,
+        transactionId: operation.transactionId ?? null,
+        claimId: operation.claimId ?? null,
+        readAt: operation.readAt ?? null,
+        fenceToken: operation.fenceToken ?? null,
+      }));
       let body: CommitResponse;
       try {
         body = await dispatchHttpCommit({
@@ -1304,6 +1343,8 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           idempotencyKey: clientTxId,
           body: requestBody,
           wait,
+          operations: frameOperations,
+          reads: commitOptions.reads,
         });
       } catch (error) {
         // Coordination collision over HTTP — surface it to observability on the
@@ -1529,6 +1570,17 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     if (action === 'create') requestBody.id = id;
     if (data !== undefined) requestBody.data = data;
 
+    const frameOperation: CommitFrameOperation = {
+      type: action.toUpperCase(),
+      model: modelName,
+      id: action === 'create' ? (id || null) : id,
+      input: data ?? null,
+      transactionId: null,
+      claimId: normalizeClaimId(options?.claimRef) ?? claimHandle?.id ?? null,
+      readAt: readAt ?? null,
+      fenceToken: options?.fenceToken ?? claimHandle?.fenceToken ?? null,
+    };
+
     let body: CommitResponse;
     try {
       body = await dispatchHttpCommit(
@@ -1541,6 +1593,8 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           // confirmation. Early queued receipts remain available through the
           // lower-level `commits.create` lifecycle surface.
           wait: 'confirmed',
+          operations: [frameOperation],
+          reads: options?.reads,
         },
         beforeConfirmation
       );
@@ -1579,6 +1633,59 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
       params: ClaimParams<Fields>
     ): Promise<{ id: string; fenceToken?: number }> => {
       const contention = resolveClaimContentionOptions(params);
+      if (options.dispatchClaim) {
+        const claimId = createClientTxId();
+        let waited = false;
+        try {
+          const grant = await options.dispatchClaim({
+            claimId,
+            entityType: name,
+            entityId: params.id,
+            ...subTarget(params, name),
+            description: claimDescription(params),
+            ...(params.ttl !== undefined ? { estimatedMs: toMs(params.ttl) } : {}),
+            queue: contention.wait,
+            ...(contention.timeoutMs !== undefined ? { timeoutMs: contention.timeoutMs } : {}),
+            ...(contention.signal !== undefined ? { signal: contention.signal } : {}),
+            onQueued: (event) => {
+              waited = true;
+              emitClaimStatus(contention.onStatus, {
+                type: 'queued',
+                claimId: event.claimId,
+                position: event.position,
+                ahead: event.position + 1,
+              });
+              if (
+                contention.maxDepth !== undefined
+                && event.position >= contention.maxDepth
+              ) {
+                return new AbloClaimedError(
+                  `Claim queue for ${name}/${params.id} is ${event.position} deep (max ${contention.maxDepth}).`,
+                  { code: 'queue_too_deep' },
+                );
+              }
+              return undefined;
+            },
+          });
+          emitClaimStatus(contention.onStatus, {
+            type: 'granted',
+            claimId: grant.claimId,
+            waited,
+          });
+          return grant.fenceToken !== undefined
+            ? { id: grant.claimId, fenceToken: grant.fenceToken }
+            : { id: grant.claimId };
+        } catch (error) {
+          const normalized = error instanceof AbloError
+            ? error
+            : new AbloConnectionError(String(error));
+          emitClaimStatus(
+            contention.onStatus,
+            claimAttemptFailure(contention.wait, normalized),
+          );
+          throw error;
+        }
+      }
       // 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`,
@@ -1656,10 +1763,17 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
     };
     const releaseClaim = (
       params: ClaimLookupParams<T> | ClaimParams<Fields> | Claim<T>,
-    ): Promise<void> =>
-      requestRaw(claimPath(isClaimHandle(params) ? params.target.id : params.id), {
+      claimId?: string,
+    ): 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 requestRaw(claimPath(entityId), {
         method: 'DELETE',
       }).then(() => undefined);
+    };
 
     // One beat on the held lease. A lapsed lease answers `claim_lost`
     // (409), which the wire error mapping surfaces as AbloClaimedError —
@@ -1763,7 +1877,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
 
       const release = () => {
         stopHeartbeatLoop?.();
-        return releaseClaim(params);
+        return releaseClaim(params, claimId);
       };
       // The handle handed back is a public claim, so its `meta` is the declared
       // shape — the same crossing the two decodes above make, spelled the same
@@ -1904,7 +2018,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           claim: undefined,
         });
       } finally {
-        await releaseClaim({ id }).catch(() => {});
+        await releaseClaim({ id }, claimId).catch(() => {});
       }
     };
 
@@ -2100,64 +2214,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';
@@ -37,9 +36,10 @@ export type CommitAck = CanonicalCommitAck;
 export interface CommitFrameOperation {
   readonly type: string;
   readonly model: string;
-  readonly id: string;
-  readonly input?: Record<string, unknown>;
-  readonly transactionId?: string;
+  readonly id: string | null;
+  readonly input?: Record<string, unknown> | null;
+  readonly where?: Record<string, unknown> | null;
+  readonly transactionId?: string | null;
   readonly claimId?: string | null;
   readonly readAt?: number | null;
   readonly fenceToken?: number | null;
@@ -65,6 +65,7 @@ export function buildCommitFrame(
       model: op.model,
       id: op.id,
       input: op.input,
+      where: op.where,
       transactionId: op.transactionId,
       claimId: op.claimId,
       readAt: op.readAt,
@@ -103,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/contextSubscription.ts

@@ -0,0 +1,55 @@
+import type { ReadDependency } from '../../coordination/schema.js';
+import { AbloStaleContextError } from '../../errors.js';
+import type { AbloWebSocketSession } from './sessionContract.js';
+
+/** Watch captured reads over the client's already-open WebSocket. */
+export function subscribeWebSocketReadChanges(
+  session: AbloWebSocketSession,
+  reads: readonly ReadDependency[],
+  listener: (error: AbloStaleContextError) => void,
+): () => void {
+  if (reads.length === 0) return () => undefined;
+  const watchedRows = new Map(
+    reads
+      .filter((read): read is Extract<ReadDependency, { model: string }> => 'model' in read)
+      .map((read) => [`${read.model.toLowerCase()}:${read.id}`, read.readAt]),
+  );
+  const watchedGroups = new Map<string, number>(
+    reads
+      .filter((read): read is Extract<ReadDependency, { group: string }> => 'group' in read)
+      .map((read) => [read.group, read.readAt]),
+  );
+  let stopped = false;
+  let unsubscribe = (): void => undefined;
+  unsubscribe = session.subscribe('delta', (delta) => {
+    if (stopped) return;
+    const readAt = watchedRows.get(`${delta.modelName.toLowerCase()}:${delta.modelId}`)
+      ?? delta.syncGroups.reduce<number | undefined>((latest, group) => {
+        const groupReadAt = watchedGroups.get(group);
+        return groupReadAt === undefined
+          ? latest
+          : Math.max(latest ?? groupReadAt, groupReadAt);
+      }, undefined);
+    if (readAt === undefined || delta.id <= readAt) return;
+    stopped = true;
+    unsubscribe();
+    listener(new AbloStaleContextError(
+      `Captured context changed: ${delta.modelName}/${delta.modelId}.`,
+      {
+        code: 'stale_context',
+        details: {
+          conflicts: [{
+            model: delta.modelName,
+            id: delta.modelId,
+            readAt,
+            current: delta.id,
+          }],
+        },
+      },
+    ));
+  });
+  return () => {
+    stopped = true;
+    unsubscribe();
+  };
+}

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',