@syncular/client 0.15.45 → 0.15.46

package/README.md

@@ -3,6 +3,17 @@
 The TypeScript client protocol core (SPEC.md §§3–8, client side) plus its
 browser platform bindings.
 
+The normal `SyncClient` also runs in a CLI or background service.
+Use `openBunDatabase(path)` or `openNodeDatabase(path)` for a persistent local
+replica. See the [server-side sync client guide](https://syncular.dev/guide-server-clients/).
+
+`SyncRemoteClient` is the database-less server client. It sends ordinary
+push-only commits through `/sync` and can call registered typed queries,
+server-authoritative commands, and live query watches through the remote
+operation transport. See [remote server operations](https://syncular.dev/guide-remote-operations/).
+Its schema and sync transport are optional for query-only or command-only
+processes.
+
 ## Client-local FTS5 projections
 
 Generated schemas may attach `ftsIndexes` to a synced table. The

package/dist/http.d.ts

@@ -5,13 +5,17 @@
  * (the loopback doctrine); the browser fixture exercises them in a real browser.
  */
 import type { BlobTransport } from './blob.js';
-import type { RealtimeConnector, SegmentDownloader, SyncTransport } from './transport.js';
+import type { RealtimeConnector, RemoteOperationTransport, RemoteOperationRealtimeConnector, SegmentDownloader, SyncTransport } from './transport.js';
 export interface HttpTransportOptions {
     readonly headers?: Readonly<Record<string, string>>;
     readonly fetch?: typeof fetch;
 }
 /** POST `<mount>/sync` with SSP2 bodies (§1.1). */
 export declare function httpSyncTransport(syncUrl: string, options?: HttpTransportOptions): SyncTransport;
+/** POST one registered authoritative operation to `<mount>/operations`. */
+export declare function httpRemoteOperationTransport(operationsUrl: string, options?: HttpTransportOptions): RemoteOperationTransport;
+/** WebSocket connector for registered query snapshots. */
+export declare function webSocketRemoteOperationConnector(realtimeUrl: string): RemoteOperationRealtimeConnector;
 /**
  * §5.5 direct endpoint with the `X-Syncular-Scopes` re-authorization
  * header, plus the §5.4 `fetchUrl` capability (advertises accept bit 3).

package/dist/http.js

@@ -35,6 +35,60 @@ export function httpSyncTransport(syncUrl, options) {
         return new Uint8Array(await response.arrayBuffer());
     };
 }
+/** POST one registered authoritative operation to `<mount>/operations`. */
+export function httpRemoteOperationTransport(operationsUrl, options) {
+    const doFetch = options?.fetch ?? fetch;
+    return async (request) => {
+        const response = await doFetch(operationsUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/vnd.syncular.operations.v1+json',
+                ...options?.headers,
+            },
+            body: request.slice().buffer,
+        });
+        if (!response.ok)
+            await throwHttpError(response);
+        return new Uint8Array(await response.arrayBuffer());
+    };
+}
+/** WebSocket connector for registered query snapshots. */
+export function webSocketRemoteOperationConnector(realtimeUrl) {
+    return (handlers) => new Promise((resolve, reject) => {
+        const socket = new WebSocket(realtimeUrl);
+        let opened = false;
+        socket.binaryType = 'arraybuffer';
+        socket.onopen = () => {
+            opened = true;
+            resolve({
+                send: (bytes) => socket.send(bytes.slice().buffer),
+                close: () => socket.close(),
+            });
+        };
+        socket.onmessage = (event) => {
+            if (event.data instanceof ArrayBuffer) {
+                handlers.onMessage(new Uint8Array(event.data));
+            }
+        };
+        socket.onerror = () => {
+            if (!opened) {
+                reject(new ClientSyncError('sync.transport_failed', 'remote operation realtime socket failed to connect', true));
+            }
+            try {
+                socket.close();
+            }
+            catch {
+                handlers.onClose?.();
+            }
+        };
+        socket.onclose = () => {
+            if (!opened) {
+                reject(new ClientSyncError('sync.transport_failed', 'remote operation realtime socket closed while connecting', true));
+            }
+            handlers.onClose?.();
+        };
+    });
+}
 /**
  * §5.5 direct endpoint with the `X-Syncular-Scopes` re-authorization
  * header, plus the §5.4 `fetchUrl` capability (advertises accept bit 3).
@@ -170,8 +224,10 @@ export function httpBlobTransport(blobsBaseUrl, options) {
 export function webSocketRealtimeConnector(realtimeUrl) {
     return (handlers) => new Promise((resolve, reject) => {
         const socket = new WebSocket(realtimeUrl);
+        let opened = false;
         socket.binaryType = 'arraybuffer';
         socket.onopen = () => {
+            opened = true;
             resolve({
                 send: (text) => socket.send(text),
                 sendBytes: (bytes) => {
@@ -187,9 +243,20 @@ export function webSocketRealtimeConnector(realtimeUrl) {
                 handlers.onBinary(new Uint8Array(event.data));
         };
         socket.onerror = () => {
-            reject(new ClientSyncError('sync.transport_failed', 'realtime socket failed to connect', true));
+            if (!opened) {
+                reject(new ClientSyncError('sync.transport_failed', 'realtime socket failed to connect', true));
+            }
+            try {
+                socket.close();
+            }
+            catch {
+                handlers.onClose?.();
+            }
         };
         socket.onclose = () => {
+            if (!opened) {
+                reject(new ClientSyncError('sync.transport_failed', 'realtime socket closed while connecting', true));
+            }
             handlers.onClose?.();
         };
     });

package/dist/index.d.ts

@@ -30,6 +30,7 @@ export * from './outbox.js';
 export * from './outcomes.js';
 export * from './query-guard.js';
 export * from './reactive-store.js';
+export * from './remote.js';
 export * from './realtime-supervisor.js';
 export * from './schema.js';
 export * from './sql-tag.js';

package/dist/index.js

@@ -30,6 +30,7 @@ export * from './outbox.js';
 export * from './outcomes.js';
 export * from './query-guard.js';
 export * from './reactive-store.js';
+export * from './remote.js';
 export * from './realtime-supervisor.js';
 export * from './schema.js';
 export * from './sql-tag.js';

package/dist/remote.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Database-less SSP2 producer (§6.10). It prepares and sends ordinary commits
+ * through the existing push path without creating a local replica or outbox.
+ */
+import { type PushOperationResult, type PushResultFrame } from '@syncular/core';
+import type { MutationInput } from './client.js';
+import type { EncryptionConfig } from './encryption.js';
+import { ClientSyncError } from './errors.js';
+import { type ClientSchema } from './schema.js';
+import type { SyncTransport } from './transport.js';
+import type { RemoteOperationRealtimeConnector, RemoteOperationTransport } from './transport.js';
+export interface SyncRemoteClientConfig {
+    /** Required only for ordinary row commits. */
+    readonly schema?: ClientSchema;
+    readonly clientId: string;
+    /** Required only for ordinary row commits. */
+    readonly transport?: SyncTransport;
+    readonly operations?: RemoteOperationTransport;
+    readonly operationRealtime?: RemoteOperationRealtimeConnector;
+    readonly encryption?: EncryptionConfig;
+}
+export interface RemoteCommitInput {
+    /** Stable caller-owned idempotency identity for this logical commit. */
+    readonly requestId: string;
+    readonly mutations: readonly MutationInput[];
+}
+/**
+ * Prepared bytes are the retry unit. Persist them when a process must retry
+ * across restart, especially when encryption uses randomized nonces.
+ */
+export interface PreparedRemoteCommit {
+    readonly requestId: string;
+    readonly bytes: Uint8Array;
+}
+export interface RemoteCommitResult {
+    readonly requestId: string;
+    readonly status: PushResultFrame['status'];
+    readonly commitSeq?: number;
+    readonly results: readonly PushOperationResult[];
+}
+export interface RemoteQueryDescriptor<Row, Params = undefined> {
+    readonly id: string;
+    readonly mapRow: (row: Readonly<Record<string, unknown>>) => Row;
+    readonly __row?: Row;
+    readonly __params?: Params;
+}
+export interface RemoteQueryResult<Row> {
+    readonly rows: readonly Row[];
+    readonly maxCommitSeq: number;
+}
+export interface RemoteQueryWatchHandlers<Row> {
+    onSnapshot(result: RemoteQueryResult<Row>): void;
+    onError?(error: ClientSyncError): void;
+}
+export interface RemoteCommandDescriptor<Input = undefined> {
+    readonly id: string;
+    readonly __input?: Input;
+}
+export declare function remoteCommand<Input = undefined>(id: string): RemoteCommandDescriptor<Input>;
+export interface RemoteCommandResult {
+    readonly requestId: string;
+    readonly status: 'applied' | 'cached' | 'rejected';
+    readonly commitSeq?: number;
+    readonly results: readonly unknown[];
+}
+export declare class SyncRemoteClient {
+    #private;
+    constructor(config: SyncRemoteClientConfig);
+    prepareCommit(input: RemoteCommitInput): Promise<PreparedRemoteCommit>;
+    sendCommit(prepared: PreparedRemoteCommit): Promise<RemoteCommitResult>;
+    commit(input: RemoteCommitInput): Promise<RemoteCommitResult>;
+    query<Row, Params = undefined>(descriptor: RemoteQueryDescriptor<Row, Params>, params?: Params): Promise<RemoteQueryResult<Row>>;
+    command<Input = undefined>(descriptor: RemoteCommandDescriptor<Input>, requestId: string, input?: Input): Promise<RemoteCommandResult>;
+    watch<Row, Params = undefined>(descriptor: RemoteQueryDescriptor<Row, Params>, params: Params, handlers: RemoteQueryWatchHandlers<Row>): Promise<() => void>;
+    close(): void;
+}

package/dist/remote.js

@@ -0,0 +1,441 @@
+/**
+ * Database-less SSP2 producer (§6.10). It prepares and sends ordinary commits
+ * through the existing push path without creating a local replica or outbox.
+ */
+import { decodeMessage, decodeRemoteOperationResponse, decodeRemoteOperationRealtimeMessage, encodeMessage, encodeRemoteOperationRequest, encodeRemoteOperationRealtimeMessage, encodeRow, PROTOCOL_WIRE_VERSION, } from '@syncular/core';
+import { encryptRowValues } from './encryption.js';
+import { ClientSyncError } from './errors.js';
+import { compileClientSchema, recordToRowValues, } from './schema.js';
+export function remoteCommand(id) {
+    if (id.length === 0)
+        throw invalid('remote command id must be non-empty');
+    return { id };
+}
+function invalid(message) {
+    return new ClientSyncError('sync.invalid_request', message);
+}
+function operationResponse(bytes) {
+    let response;
+    try {
+        response = decodeRemoteOperationResponse(bytes);
+    }
+    catch {
+        throw new ClientSyncError('client.invalid_host_response', 'remote operation response is malformed');
+    }
+    if (typeof response !== 'object' ||
+        response === null ||
+        Array.isArray(response)) {
+        throw new ClientSyncError('client.invalid_host_response', 'remote operation response is malformed');
+    }
+    if (response.revision !== 1) {
+        throw new ClientSyncError('client.invalid_host_response', 'remote operation response has an unsupported revision');
+    }
+    if (response.kind === 'error' &&
+        (typeof response.code !== 'string' ||
+            typeof response.message !== 'string' ||
+            typeof response.retryable !== 'boolean')) {
+        throw new ClientSyncError('client.invalid_host_response', 'remote operation error response is malformed');
+    }
+    if (response.kind === 'query' &&
+        (typeof response.operationId !== 'string' ||
+            !Array.isArray(response.rows) ||
+            response.rows.some((row) => typeof row !== 'object' || row === null || Array.isArray(row)) ||
+            !Number.isSafeInteger(response.maxCommitSeq) ||
+            response.maxCommitSeq < 0)) {
+        throw new ClientSyncError('client.invalid_host_response', 'remote query response is malformed');
+    }
+    if (response.kind === 'command' &&
+        (typeof response.operationId !== 'string' ||
+            typeof response.requestId !== 'string' ||
+            !['applied', 'cached', 'rejected'].includes(response.status) ||
+            !Array.isArray(response.results) ||
+            (response.commitSeq !== undefined &&
+                (!Number.isSafeInteger(response.commitSeq) || response.commitSeq < 1)))) {
+        throw new ClientSyncError('client.invalid_host_response', 'remote command response is malformed');
+    }
+    if (response.kind !== 'error' &&
+        response.kind !== 'query' &&
+        response.kind !== 'command') {
+        throw new ClientSyncError('client.invalid_host_response', 'remote operation response has an unknown kind');
+    }
+    return response;
+}
+export class SyncRemoteClient {
+    #schema;
+    #clientId;
+    #transport;
+    #operations;
+    #operationRealtime;
+    #operationSocket;
+    #operationSocketPromise;
+    #operationSocketGeneration = 0;
+    #watches = new Map();
+    #encryption;
+    constructor(config) {
+        if (config.clientId.length === 0) {
+            throw invalid('SyncRemoteClient clientId must be non-empty');
+        }
+        this.#schema =
+            config.schema === undefined
+                ? undefined
+                : compileClientSchema(config.schema);
+        this.#clientId = config.clientId;
+        this.#transport = config.transport;
+        this.#operations = config.operations;
+        this.#operationRealtime = config.operationRealtime;
+        this.#encryption = config.encryption;
+    }
+    async prepareCommit(input) {
+        const schema = this.#schema;
+        if (schema === undefined) {
+            throw new ClientSyncError('client.remote_schema_unconfigured', 'SyncRemoteClient needs a schema to prepare ordinary commits');
+        }
+        if (input.requestId.length === 0) {
+            throw invalid('remote commit requestId must be non-empty');
+        }
+        if (input.mutations.length === 0) {
+            throw new ClientSyncError('sync.empty_commit', 'a remote commit must carry at least one mutation (§6.1)');
+        }
+        const operations = [];
+        for (const mutation of input.mutations) {
+            const table = schema.tables.get(mutation.table);
+            if (table === undefined) {
+                throw invalid('remote commit targets an unknown table');
+            }
+            if (mutation.op === 'delete') {
+                if (mutation.rowId.length === 0) {
+                    throw invalid('remote delete rowId must be non-empty');
+                }
+                operations.push({
+                    table: mutation.table,
+                    rowId: mutation.rowId,
+                    op: 'delete',
+                    ...(mutation.baseVersion !== undefined
+                        ? { baseVersion: mutation.baseVersion }
+                        : {}),
+                });
+                continue;
+            }
+            let values = recordToRowValues(table, mutation.values);
+            const rowId = values[table.primaryKeyIndex];
+            if (typeof rowId !== 'string' || rowId.length === 0) {
+                throw invalid('remote upsert requires a non-empty string primary key');
+            }
+            if (this.#encryption !== undefined && table.hasEncryptedColumns) {
+                values = await encryptRowValues(this.#encryption, table, rowId, values);
+            }
+            operations.push({
+                table: mutation.table,
+                rowId,
+                op: 'upsert',
+                ...(mutation.baseVersion !== undefined
+                    ? { baseVersion: mutation.baseVersion }
+                    : {}),
+                payload: encodeRow(table.columns, values),
+            });
+        }
+        return {
+            requestId: input.requestId,
+            bytes: encodeMessage({
+                wireVersion: PROTOCOL_WIRE_VERSION,
+                msgKind: 'request',
+                frames: [
+                    {
+                        type: 'REQ_HEADER',
+                        clientId: this.#clientId,
+                        schemaVersion: schema.version,
+                    },
+                    {
+                        type: 'PUSH_COMMIT',
+                        clientCommitId: input.requestId,
+                        operations,
+                    },
+                ],
+            }),
+        };
+    }
+    async sendCommit(prepared) {
+        if (this.#transport === undefined) {
+            throw new ClientSyncError('client.remote_sync_unconfigured', 'SyncRemoteClient has no sync transport for ordinary commits');
+        }
+        const response = decodeMessage(await this.#transport(prepared.bytes));
+        if (response.msgKind !== 'response') {
+            throw new ClientSyncError('client.invalid_host_response', 'remote commit transport returned a non-response SSP2 message');
+        }
+        const error = response.frames.find((frame) => frame.type === 'ERROR');
+        if (error?.type === 'ERROR') {
+            throw new ClientSyncError(error.code, error.message, error.retryable);
+        }
+        const result = response.frames.find((frame) => frame.type === 'PUSH_RESULT' &&
+            frame.clientCommitId === prepared.requestId);
+        if (result === undefined) {
+            throw new ClientSyncError('client.invalid_host_response', 'remote commit response carried no matching PUSH_RESULT');
+        }
+        const details = response.frames.find((frame) => frame.type === 'PUSH_RESULT_DETAILS' &&
+            frame.clientCommitId === prepared.requestId);
+        const detailsByIndex = new Map(details?.entries.map((entry) => [entry.opIndex, entry.details]) ?? []);
+        return {
+            requestId: prepared.requestId,
+            status: result.status,
+            ...(result.commitSeq !== undefined
+                ? { commitSeq: result.commitSeq }
+                : {}),
+            results: result.results.map((operation) => {
+                if (operation.status !== 'error')
+                    return operation;
+                const operationDetails = detailsByIndex.get(operation.opIndex);
+                return operationDetails === undefined
+                    ? operation
+                    : { ...operation, details: operationDetails };
+            }),
+        };
+    }
+    async commit(input) {
+        return this.sendCommit(await this.prepareCommit(input));
+    }
+    async query(descriptor, params) {
+        if (this.#operations === undefined) {
+            throw new ClientSyncError('client.remote_operations_unconfigured', 'SyncRemoteClient has no remote operation transport');
+        }
+        const response = operationResponse(await this.#operations(encodeRemoteOperationRequest({
+            revision: 1,
+            kind: 'query',
+            clientId: this.#clientId,
+            operationId: descriptor.id,
+            params: params ?? null,
+        })));
+        if (response.kind === 'error') {
+            throw new ClientSyncError(response.code, response.message, response.retryable);
+        }
+        if (response.kind !== 'query' || response.operationId !== descriptor.id) {
+            throw new ClientSyncError('client.invalid_host_response', 'remote query returned a mismatched response');
+        }
+        try {
+            return {
+                rows: response.rows.map((row) => descriptor.mapRow(row)),
+                maxCommitSeq: response.maxCommitSeq,
+            };
+        }
+        catch {
+            throw new ClientSyncError('client.invalid_host_response', 'remote query row is malformed');
+        }
+    }
+    async command(descriptor, requestId, input) {
+        if (this.#operations === undefined) {
+            throw new ClientSyncError('client.remote_operations_unconfigured', 'SyncRemoteClient has no remote operation transport');
+        }
+        if (requestId.length === 0) {
+            throw invalid('remote command requestId must be non-empty');
+        }
+        const response = operationResponse(await this.#operations(encodeRemoteOperationRequest({
+            revision: 1,
+            kind: 'command',
+            clientId: this.#clientId,
+            operationId: descriptor.id,
+            requestId,
+            params: input ?? null,
+        })));
+        if (response.kind === 'error') {
+            throw new ClientSyncError(response.code, response.message, response.retryable);
+        }
+        if (response.kind !== 'command' ||
+            response.operationId !== descriptor.id ||
+            response.requestId !== requestId) {
+            throw new ClientSyncError('client.invalid_host_response', 'remote command returned a mismatched response');
+        }
+        return {
+            requestId,
+            status: response.status,
+            ...(response.commitSeq !== undefined
+                ? { commitSeq: response.commitSeq }
+                : {}),
+            results: response.results,
+        };
+    }
+    async watch(descriptor, params, handlers) {
+        if (this.#operationRealtime === undefined) {
+            throw new ClientSyncError('client.remote_realtime_unconfigured', 'SyncRemoteClient has no remote operation realtime connector');
+        }
+        const watchId = crypto.randomUUID();
+        this.#watches.set(watchId, {
+            operationId: descriptor.id,
+            mapRow: descriptor.mapRow,
+            handlers: handlers,
+        });
+        let socket;
+        try {
+            socket = await this.#operationRealtimeSocket();
+        }
+        catch (error) {
+            this.#watches.delete(watchId);
+            throw error;
+        }
+        if (!this.#watches.has(watchId)) {
+            throw new ClientSyncError('client.remote_realtime_cancelled', 'remote operation watch was cancelled before registration');
+        }
+        try {
+            socket.send(encodeRemoteOperationRealtimeMessage({
+                revision: 1,
+                kind: 'watch',
+                watchId,
+                clientId: this.#clientId,
+                operationId: descriptor.id,
+                params: params ?? null,
+            }));
+        }
+        catch {
+            const error = new ClientSyncError('client.remote_realtime_closed', 'remote operation realtime connection closed while registering a watch', true);
+            this.#disconnectOperationRealtime(this.#operationSocketGeneration, error, true);
+            throw error;
+        }
+        return () => {
+            if (!this.#watches.delete(watchId))
+                return;
+            try {
+                this.#operationSocket?.send(encodeRemoteOperationRealtimeMessage({
+                    revision: 1,
+                    kind: 'unwatch',
+                    watchId,
+                }));
+            }
+            catch {
+                this.#disconnectOperationRealtime(this.#operationSocketGeneration, new ClientSyncError('client.remote_realtime_closed', 'remote operation realtime connection closed while removing a watch', true), true);
+            }
+        };
+    }
+    async #operationRealtimeSocket() {
+        if (this.#operationSocket !== undefined)
+            return this.#operationSocket;
+        if (this.#operationSocketPromise !== undefined) {
+            return this.#operationSocketPromise;
+        }
+        const connector = this.#operationRealtime;
+        if (connector === undefined) {
+            throw new ClientSyncError('client.remote_realtime_unconfigured', 'SyncRemoteClient has no remote operation realtime connector');
+        }
+        const generation = this.#operationSocketGeneration;
+        const pending = Promise.resolve(connector({
+            onMessage: (bytes) => {
+                if (generation !== this.#operationSocketGeneration)
+                    return;
+                let message;
+                try {
+                    message = decodeRemoteOperationRealtimeMessage(bytes);
+                    if (typeof message !== 'object' ||
+                        message === null ||
+                        message.revision !== 1 ||
+                        (message.kind !== 'snapshot' && message.kind !== 'watch_error') ||
+                        typeof message.watchId !== 'string') {
+                        throw new Error('invalid remote operation realtime message');
+                    }
+                }
+                catch {
+                    this.#disconnectOperationRealtime(generation, new ClientSyncError('client.invalid_host_response', 'remote operation realtime message is malformed'), true);
+                    return;
+                }
+                const watch = this.#watches.get(message.watchId);
+                if (watch === undefined)
+                    return;
+                if (message.kind === 'watch_error') {
+                    if (typeof message.code !== 'string' ||
+                        typeof message.message !== 'string' ||
+                        typeof message.retryable !== 'boolean') {
+                        this.#disconnectOperationRealtime(generation, new ClientSyncError('client.invalid_host_response', 'remote operation watch error is malformed'), true);
+                        return;
+                    }
+                    try {
+                        watch.handlers.onError?.(new ClientSyncError(message.code, message.message, message.retryable));
+                    }
+                    catch {
+                        // An observer cannot alter the connection lifecycle.
+                    }
+                    return;
+                }
+                if (message.operationId !== watch.operationId ||
+                    !Array.isArray(message.rows) ||
+                    message.rows.some((row) => typeof row !== 'object' || row === null || Array.isArray(row)) ||
+                    !Number.isSafeInteger(message.maxCommitSeq) ||
+                    message.maxCommitSeq < 0) {
+                    this.#disconnectOperationRealtime(generation, new ClientSyncError('client.invalid_host_response', 'remote operation watch snapshot is malformed'), true);
+                    return;
+                }
+                let rows;
+                try {
+                    rows = message.rows.map(watch.mapRow);
+                }
+                catch {
+                    try {
+                        watch.handlers.onError?.(new ClientSyncError('client.invalid_host_response', 'remote operation watch row is malformed'));
+                    }
+                    catch {
+                        // An observer cannot alter the connection lifecycle.
+                    }
+                    return;
+                }
+                try {
+                    watch.handlers.onSnapshot({
+                        rows,
+                        maxCommitSeq: message.maxCommitSeq,
+                    });
+                }
+                catch {
+                    // An observer cannot alter the connection lifecycle.
+                }
+            },
+            onClose: () => {
+                this.#disconnectOperationRealtime(generation, new ClientSyncError('client.remote_realtime_closed', 'remote operation realtime connection closed', true), false);
+            },
+        }))
+            .then((socket) => {
+            if (generation !== this.#operationSocketGeneration) {
+                try {
+                    socket.close();
+                }
+                catch {
+                    // The cancelled socket cannot affect the replacement generation.
+                }
+                throw new ClientSyncError('client.remote_realtime_cancelled', 'remote operation realtime connection was cancelled');
+            }
+            this.#operationSocket = socket;
+            return socket;
+        })
+            .finally(() => {
+            if (this.#operationSocketPromise === pending) {
+                this.#operationSocketPromise = undefined;
+            }
+        });
+        this.#operationSocketPromise = pending;
+        return pending;
+    }
+    #disconnectOperationRealtime(generation, error, closeSocket) {
+        if (generation !== this.#operationSocketGeneration)
+            return;
+        this.#operationSocketGeneration += 1;
+        const socket = this.#operationSocket;
+        this.#operationSocket = undefined;
+        this.#operationSocketPromise = undefined;
+        const watches = [...this.#watches.values()];
+        this.#watches.clear();
+        if (closeSocket) {
+            try {
+                socket?.close();
+            }
+            catch {
+                // Local state is already disconnected.
+            }
+        }
+        if (error === undefined)
+            return;
+        for (const watch of watches) {
+            try {
+                watch.handlers.onError?.(error);
+            }
+            catch {
+                // An observer cannot alter the connection lifecycle.
+            }
+        }
+    }
+    close() {
+        this.#disconnectOperationRealtime(this.#operationSocketGeneration, undefined, true);
+    }
+}

package/dist/transport.d.ts

@@ -6,6 +6,17 @@
  */
 /** One combined push+pull round trip: SSP2 request bytes → response bytes. */
 export type SyncTransport = (request: Uint8Array) => Promise<Uint8Array>;
+/** One registered authoritative query or command request. */
+export type RemoteOperationTransport = (request: Uint8Array) => Promise<Uint8Array>;
+export interface RemoteOperationRealtimeHandlers {
+    onMessage(bytes: Uint8Array): void;
+    onClose?(): void;
+}
+export interface RemoteOperationRealtimeSocket {
+    send(bytes: Uint8Array): void;
+    close(): void;
+}
+export type RemoteOperationRealtimeConnector = (handlers: RemoteOperationRealtimeHandlers) => RemoteOperationRealtimeSocket | Promise<RemoteOperationRealtimeSocket>;
 export interface SegmentFetchRequest {
     readonly segmentId: string;
     readonly table: string;