@abloatai/transaction 0.59.1 → 0.59.2

package/src/transport/http/client.ts

@@ -56,6 +56,7 @@ import {
   type FunctionalUpdateOptions,
 } from '../../client/resources/functionalUpdate.js';
 import type { HeldClaim, HeldLease } from '../../types/streams.js';
+import type { JsonValue } from '../../types/streams.js';
 import { AbloConnectionError, AbloValidationError } from '../../errors.js';
 import type { ReadDependency } from '../../coordination/schema.js';
 import {
@@ -65,8 +66,22 @@ import {
   prepareReadSet,
   type ReadSetContext,
 } from '../../commit/readSetContext.js';
-import { recordHttpCommitReceipt } from '../../commit/recordRuntime.js';
+import {
+  recordHttpCommitReceipt,
+  recordWebSocketCommitReceipt,
+} from '../../commit/recordRuntime.js';
 import type { EffectiveAuthority } from '../../auth/capability.js';
+import {
+  createWebSocketSession,
+} from '../websocket/session.js';
+import type {
+  AbloWebSocketSession,
+  WebSocketObservedDelta,
+} from '../websocket/sessionContract.js';
+import { subscribeWebSocketReadChanges } from '../websocket/contextSubscription.js';
+import type {
+  CoreSyncEventMap,
+} from '../websocket/transport.js';
 
 export interface AbloHttpClientOptions<S extends SchemaRecord>
   extends HttpClientConfig<S> {
@@ -76,6 +91,16 @@ export interface AbloHttpClientOptions<S extends SchemaRecord>
    * @default 30_000
    */
   readonly timeoutMs?: number;
+  /** Initial area of interest for `transport: 'websocket'`. */
+  readonly syncGroups?: readonly string[];
+  /** Application frame names accepted by `subscribe` on the WebSocket transport. */
+  readonly collaborationEvents?: readonly string[];
+  /** Durable resume position for WebSocket observation. */
+  readonly cursorStore?: import('../../client/contract.js').ObserveCursorStore;
+  readonly cursorKey?: string;
+  readonly reconnectDelay?: number;
+  readonly maxReconnectDelay?: number;
+  readonly connectTimeoutMs?: number;
 }
 
 declare const capturedRowBrand: unique symbol;
@@ -219,6 +244,30 @@ export type AbloHttpClient<S extends SchemaRecord> = {
   readonly sessions: SessionResource<S>;
 };
 
+/** The same typed resource client, with server-pushed capabilities carried by WebSocket. */
+export type AbloWebSocketClient<S extends SchemaRecord> = AbloHttpClient<S> & {
+  observe(options?: { signal?: AbortSignal }): AsyncIterable<WebSocketObservedDelta>;
+  subscribe<K extends keyof CoreSyncEventMap>(
+    event: K,
+    listener: (...args: CoreSyncEventMap[K]) => void,
+  ): () => void;
+  updateSubscription(
+    syncGroups: readonly string[],
+    options?: { timeoutMs?: number },
+  ): Promise<{ syncGroups: string[] }>;
+  readonly presence: {
+    update(input?: {
+      readonly status?: 'online' | 'away' | 'offline';
+      readonly customStatus?: string;
+      readonly timezone?: string;
+      readonly activity?: Readonly<Record<string, JsonValue>>;
+    }): Promise<void>;
+  };
+  readonly collaboration: {
+    send(event: string, payload: Readonly<Record<string, JsonValue>>): Promise<void>;
+  };
+};
+
 /**
  * Private transport members that pass straight through the facade. Everything
  * else must be a declared schema model; there is no dynamic fallback namespace.
@@ -497,8 +546,9 @@ function createHttpModelClient<T, C = T>(
 /** @internal Constructed only through the public `Ablo({ transport: 'http' })` factory. */
 export function createAbloHttpClient<S extends SchemaRecord>(
   options: AbloHttpClientOptions<S>,
-): AbloHttpClient<S> {
+): AbloHttpClient<S> | AbloWebSocketClient<S> {
   const { schema, onCommitReceipt, ...rest } = options;
+  const usesWebSocket = options.transport === 'websocket';
   const readSetContext = createReadSetContext();
   const transport: HttpTransport = createHttpTransport({
     ...rest,
@@ -509,6 +559,21 @@ export function createAbloHttpClient<S extends SchemaRecord>(
       recordHttpCommitReceipt(readSetContext, observation);
       onCommitReceipt?.(observation);
     },
+    ...(usesWebSocket ? {
+      dispatchCommit: async (input) => {
+        const receipt = await (await webSocketSession()).commit(input);
+        recordWebSocketCommitReceipt(readSetContext, {
+          receipt,
+          operations: input.operations,
+          reads: input.reads,
+        });
+        return receipt;
+      },
+      dispatchClaim: async (input) => (await webSocketSession()).claim(input),
+      releaseDispatchedClaim: (input) => {
+        void webSocketSession().then((session) => session.release(input));
+      },
+    } : {}),
   });
   const schemaModels = new Set(Object.keys(schema.models));
   const clientIdentity = {};
@@ -517,6 +582,56 @@ export function createAbloHttpClient<S extends SchemaRecord>(
     string,
     HttpModelClient<Record<string, unknown>, Record<string, unknown>>
   >();
+  let webSocket: AbloWebSocketSession | null = null;
+  let webSocketPromise: Promise<AbloWebSocketSession> | null = null;
+  const webSocketOpen = new AbortController();
+  let disposed = false;
+
+  const webSocketSession = (): Promise<AbloWebSocketSession> => {
+    if (disposed) {
+      return Promise.reject(new AbloConnectionError('This Ablo client is disposed.'));
+    }
+    if (webSocket) return Promise.resolve(webSocket);
+    if (webSocketPromise) return webSocketPromise;
+    webSocketPromise = (async () => {
+      await transport.ready();
+      const session = await createWebSocketSession({
+        baseUrl: rest.baseURL ?? undefined,
+        getAuthToken: async () => (await transport.getAuthToken()) ?? undefined,
+        syncGroups: options.syncGroups,
+        collaborationEvents: options.collaborationEvents,
+        cursorStore: options.cursorStore,
+        cursorKey: options.cursorKey,
+        reconnectDelay: options.reconnectDelay,
+        maxReconnectDelay: options.maxReconnectDelay,
+        connectTimeoutMs: options.connectTimeoutMs,
+      }, webSocketOpen.signal);
+      if (disposed) {
+        await session.close();
+        throw new AbloConnectionError('This Ablo client is disposed.');
+      }
+      webSocket = session;
+      return session;
+    })().finally(() => {
+      webSocketPromise = null;
+    });
+    return webSocketPromise;
+  };
+
+  const ready = async (): Promise<void> => {
+    await transport.ready();
+    if (usesWebSocket) await webSocketSession();
+  };
+
+  const dispose = async (): Promise<void> => {
+    if (disposed) return;
+    disposed = true;
+    webSocketOpen.abort();
+    const opening = webSocketPromise;
+    if (webSocket) await webSocket.close();
+    else await opening?.then((session) => session.close()).catch(() => undefined);
+    await transport.dispose();
+  };
 
   const model = (
     name: string,
@@ -563,11 +678,50 @@ export function createAbloHttpClient<S extends SchemaRecord>(
         return {
           context: readSetContext,
           client: clientIdentity,
-          onChange: transport.onChange,
+          onChange: (reads: readonly ReadDependency[], listener: Parameters<typeof transport.onChange>[1]) =>
+            usesWebSocket
+              ? subscribeWhenConnected(webSocketSession, reads, listener)
+              : transport.onChange(reads, listener),
         };
       }
       if (typeof prop !== 'string') return undefined;
       if (prop === 'commits') return commits;
+      if (prop === 'ready') return ready;
+      if (prop === 'dispose') return dispose;
+      if (usesWebSocket && prop === 'observe') {
+        return async function* (observeOptions?: { signal?: AbortSignal }) {
+          yield* (await webSocketSession()).observe(observeOptions);
+        };
+      }
+      if (usesWebSocket && prop === 'subscribe') {
+        return <K extends keyof CoreSyncEventMap>(
+          event: K,
+          listener: (...args: CoreSyncEventMap[K]) => void,
+        ) => {
+          let stop: (() => void) | undefined;
+          let cancelled = false;
+          void webSocketSession().then((session) => {
+            if (!cancelled) stop = session.subscribe(event, listener);
+          });
+          return () => { cancelled = true; stop?.(); };
+        };
+      }
+      if (usesWebSocket && prop === 'updateSubscription') {
+        return async (groups: readonly string[], subscriptionOptions?: { timeoutMs?: number }) =>
+          (await webSocketSession()).updateSubscription(groups, subscriptionOptions);
+      }
+      if (usesWebSocket && prop === 'presence') {
+        return {
+          update: async (input?: Parameters<AbloWebSocketSession['presence']['update']>[0]) =>
+            (await webSocketSession()).presence.update(input),
+        };
+      }
+      if (usesWebSocket && prop === 'collaboration') {
+        return {
+          send: async (event: string, payload: Readonly<Record<string, JsonValue>>) =>
+            (await webSocketSession()).collaboration.send(event, payload),
+        };
+      }
       // Real protocol members pass through unchanged.
       if (isProtocolMember(prop)) {
         return transport[prop];
@@ -586,5 +740,18 @@ export function createAbloHttpClient<S extends SchemaRecord>(
   // A single boundary cast. `AbloHttpClient<S>` declares only what the model
   // accessor and the passed-through protocol members actually implement, so no
   // method on this type is missing at runtime.
-  return facade as AbloHttpClient<S>;
+  return facade as AbloHttpClient<S> | AbloWebSocketClient<S>;
+}
+
+function subscribeWhenConnected(
+  session: () => Promise<AbloWebSocketSession>,
+  reads: readonly ReadDependency[],
+  listener: Parameters<typeof subscribeWebSocketReadChanges>[2],
+): () => void {
+  let stop: (() => void) | undefined;
+  let cancelled = false;
+  void session().then((connected) => {
+    if (!cancelled) stop = subscribeWebSocketReadChanges(connected, reads, listener);
+  });
+  return () => { cancelled = true; stop?.(); };
 }

package/src/transport/http/transport.ts

@@ -124,6 +124,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,6 +175,7 @@ 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'> & {
@@ -191,6 +198,24 @@ 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. */
@@ -981,11 +1006,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 +1332,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 +1351,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 +1578,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 +1601,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 +1641,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 +1771,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 +1885,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 +2026,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           claim: undefined,
         });
       } finally {
-        await releaseClaim({ id }).catch(() => {});
+        await releaseClaim({ id }, claimId).catch(() => {});
       }
     };
 

package/src/transport/websocket/commitFrames.ts

@@ -37,9 +37,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 +66,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,

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();
+  };
+}