@lix-js/sdk 0.12.2 → 0.14.0

package/dist/remote/client.js

@@ -1,1167 +1,77 @@
-import { decodeExecuteBatchResult, decodeExecuteResult, decodeHandshake, decodeObserveEvent, encodeWireValue, errorFromResponseBody, protocolError, record, SERVER_PROTOCOL_PATH, remoteError, } from "./server-protocol.js";
-import { readSseEvents } from "./sse.js";
-const OBSERVE_RETRY_BASE_MS = 100;
-const OBSERVE_RETRY_MAX_MS = 5_000;
-const REMOTE_SESSION_HEADER = "Lix-Session-Id";
-const REMOTE_TRANSACTION_HEADER = "Lix-Transaction-Id";
-const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
-const REQUEST_BLOB_DELTA_MIN_BYTES = 32 * 1024;
-const REQUEST_BLOB_DELTA_MIN_WIRE_RATIO = 0.9;
-const REQUEST_BLOB_COMPARE_WORD_BYTES = 8;
-const REQUEST_BLOB_BASE_MAX_ENTRIES = 8;
-// Match the server's per-session aggregate base budget. One 10.68 MB CSV base
-// fits; committing its successor removes the same-slot predecessor before the
-// new base is retained, so repeated large-file edits stay bounded.
-const REQUEST_BLOB_BASE_MAX_BYTES = 16 * 1024 * 1024;
-const REMOTE_BLOB_BASE_MISSING = "LIX_REMOTE_BLOB_BASE_MISSING";
-const WIRE_BLOB_JSON_ENVELOPE_BYTES = JSON.stringify({
-    kind: "blob",
-    base64: "",
-}).length;
-const MIN_COMPRESSIBLE_JSON_BYTES = 32 * 1024;
-const COMPRESSION_SAMPLE_BYTES = 32 * 1024;
-const MAX_COMPRESSION_SAMPLE_RATIO = 0.7;
-const MAX_COMPRESSED_BODY_RATIO = 0.9;
-export async function openRemoteLixBinding(options, clientOptions = {}) {
-    const client = new RemoteLixBinding(options, clientOptions);
-    await client.open();
-    return client;
-}
-class RemoteLixBinding {
-    #baseUrl;
-    #fetch;
-    #headers;
-    #initialActiveBranchId;
-    #observationHub;
-    #requestBlobBases = new Map();
-    #sessionId;
-    #activeBranchId;
-    #activeAccountId;
-    #requestBlobBaseBytes = 0;
-    #acceptingOperations = true;
-    #operationQueue = Promise.resolve();
-    #closePromise;
-    constructor(options, clientOptions) {
-        if (!options || typeof options !== "object") {
-            throw new TypeError("openLix() remote server must be an object");
-        }
-        if (options.mode !== "remote") {
-            throw new TypeError("openLix() remote server mode must be 'remote'");
-        }
-        this.#baseUrl = protocolBaseUrl(options.url);
-        const remoteFetch = options.fetch ?? globalThis.fetch?.bind(globalThis);
-        if (typeof remoteFetch !== "function") {
-            throw new TypeError("openLix() remote mode requires fetch");
-        }
-        this.#fetch = remoteFetch;
-        if (options.headers !== undefined &&
-            typeof options.headers !== "function" &&
-            !isHeadersInit(options.headers)) {
-            throw new TypeError("openLix() remote server headers must be HeadersInit or a function");
-        }
-        this.#headers = options.headers;
-        if (clientOptions.initialActiveBranchId !== undefined &&
-            clientOptions.initialActiveBranchId.length === 0) {
-            throw new TypeError("initialActiveBranchId must be a non-empty string");
-        }
-        this.#initialActiveBranchId = clientOptions.initialActiveBranchId;
-        this.#observationHub = new RemoteObservationHub({
-            openStream: (subscriptions, signal) => this.#requestObserveStream(subscriptions, signal),
-            refreshObservation: (subscription) => this.#refreshObservation(subscription),
-        });
-    }
-    async open() {
-        const query = new URLSearchParams();
-        if (this.#initialActiveBranchId !== undefined) {
-            query.set("activeBranchId", this.#initialActiveBranchId);
-        }
-        const path = query.size === 0 ? "" : `?${query}`;
-        const handshake = decodeHandshake(await this.#requestJson(path, { method: "GET" }));
-        this.#sessionId = handshake.sessionId;
-        this.#activeBranchId = handshake.activeBranchId;
-        this.#activeAccountId = handshake.activeAccountId;
-    }
-    async execute(sql, params, options) {
-        this.#assertOpen();
-        const snapshot = snapshotParams(params);
-        const idempotencyKey = idempotencyKeyFor(options?.idempotencyKey);
-        const requestOptions = remoteExecuteOptions(options);
-        return this.#enqueue(async () => {
-            const prepared = await this.#prepareParams(snapshot, (index) => requestBlobSlot("execute", sql, index));
-            const request = (params) => this.#requestJson("execute", {
-                method: "POST",
-                headers: { [IDEMPOTENCY_KEY_HEADER]: idempotencyKey },
-                body: JSON.stringify({
-                    sql,
-                    params,
-                    ...(requestOptions === undefined ? {} : { options: requestOptions }),
-                    ...(prepared.cacheBlobs ? { cacheBlobs: true } : {}),
-                }),
-            });
-            const value = await requestWithFullBlobFallback(() => request(prepared.params), prepared.hasDelta ? () => request(prepared.fullParams()) : undefined);
-            const result = decodeExecuteResult(value);
-            this.#commitRequestBlobBases(prepared.cacheUpdates);
-            return result;
-        });
-    }
-    async executeBatch(statements, options) {
-        this.#assertOpen();
-        const idempotencyKey = idempotencyKeyFor(options?.idempotencyKey);
-        const requestOptions = remoteExecuteOptions(options);
-        const snapshot = statements.map((statement) => ({
-            sql: statement.sql,
-            params: snapshotParams(statement.params),
-            ...(statement.label === undefined ? {} : { label: statement.label }),
-        }));
-        return this.#enqueue(async () => {
-            const preparedStatements = await Promise.all(snapshot.map(async (statement, statementIndex) => ({
-                sql: statement.sql,
-                label: statement.label,
-                prepared: await this.#prepareParams(statement.params, (paramIndex) => requestBlobSlot("batch", statement.sql, paramIndex, statementIndex)),
-            })));
-            const cacheBlobs = preparedStatements.some((statement) => statement.prepared.cacheBlobs);
-            const hasDelta = preparedStatements.some((statement) => statement.prepared.hasDelta);
-            const request = (full) => this.#requestJson("execute-batch", {
-                method: "POST",
-                headers: { [IDEMPOTENCY_KEY_HEADER]: idempotencyKey },
-                body: JSON.stringify({
-                    statements: preparedStatements.map((statement) => ({
-                        sql: statement.sql,
-                        ...(statement.label === undefined
-                            ? {}
-                            : { label: statement.label }),
-                        params: full
-                            ? statement.prepared.fullParams()
-                            : statement.prepared.params,
-                    })),
-                    ...(requestOptions === undefined ? {} : { options: requestOptions }),
-                    ...(cacheBlobs ? { cacheBlobs: true } : {}),
-                }),
-            });
-            const value = await requestWithFullBlobFallback(() => request(false), hasDelta ? () => request(true) : undefined);
-            if (!Array.isArray(value)) {
-                throw protocolError("execute batch response must be an array");
-            }
-            const results = value.map(decodeExecuteBatchResult);
-            this.#commitRequestBlobBases(preparedStatements.flatMap((statement) => statement.prepared.cacheUpdates));
-            return results;
-        });
-    }
-    async observe(sql, params) {
-        this.#assertOpen();
-        return this.#observationHub.observe(sql, params.map(encodeWireValue));
-    }
-    async beginTransaction() {
-        this.#assertOpen();
-        return this.#enqueue(async () => {
-            const begun = record(await this.#requestJson("transaction/begin", { method: "POST" }), "begin transaction response");
-            if (typeof begun.transactionId !== "string") {
-                throw protocolError("begin transaction response.transactionId must be a string");
-            }
-            const transactionId = begun.transactionId;
-            let active = true;
-            const assertActive = () => {
-                if (!active) {
-                    throw remoteError("LIX_INVALID_TRANSACTION_STATE", "Lix transaction is closed");
-                }
-            };
-            return {
-                execute: async (sql, params, options) => {
-                    assertActive();
-                    const snapshot = snapshotParams(params);
-                    const requestOptions = remoteExecuteOptions(options);
-                    return this.#enqueue(async () => {
-                        const value = await this.#requestJson("transaction/execute", {
-                            method: "POST",
-                            headers: { [REMOTE_TRANSACTION_HEADER]: transactionId },
-                            body: JSON.stringify({
-                                sql,
-                                params: snapshot.map(encodeWireValue),
-                                ...(requestOptions === undefined
-                                    ? {}
-                                    : { options: requestOptions }),
-                            }),
-                        });
-                        return decodeExecuteResult(value);
-                    });
-                },
-                commit: async () => {
-                    assertActive();
-                    return this.#enqueue(async () => {
-                        assertActive();
-                        await this.#requestJson("transaction/commit", {
-                            method: "POST",
-                            headers: { [REMOTE_TRANSACTION_HEADER]: transactionId },
-                        }, "empty");
-                        active = false;
-                    });
-                },
-                rollback: async () => {
-                    assertActive();
-                    return this.#enqueue(async () => {
-                        assertActive();
-                        await this.#requestJson("transaction/rollback", {
-                            method: "POST",
-                            headers: { [REMOTE_TRANSACTION_HEADER]: transactionId },
-                        }, "empty");
-                        active = false;
-                    });
-                },
-            };
-        });
-    }
-    async activeBranchId() {
-        this.#assertOpen();
-        return this.#enqueue(async () => {
-            if (this.#activeBranchId === undefined) {
-                const handshake = decodeHandshake(await this.#requestJson("", { method: "GET" }));
-                if (handshake.sessionId !== this.#sessionId) {
-                    throw protocolError("Lix Server Protocol handshake changed sessionId");
-                }
-                this.#activeBranchId = handshake.activeBranchId;
-            }
-            return this.#activeBranchId;
-        });
-    }
-    async activeAccountId() {
-        this.#assertOpen();
-        return this.#enqueue(async () => {
-            if (this.#activeAccountId === undefined) {
-                const handshake = decodeHandshake(await this.#requestJson("", { method: "GET" }));
-                if (handshake.sessionId !== this.#sessionId) {
-                    throw protocolError("Lix Server Protocol handshake changed sessionId");
-                }
-                this.#activeAccountId = handshake.activeAccountId;
-            }
-            return this.#activeAccountId;
-        });
-    }
-    async createBranch(options) {
-        this.#assertOpen();
-        return this.#enqueue(async () => {
-            const value = record(await this.#requestJson("branch/create", {
-                method: "POST",
-                body: JSON.stringify(options),
-            }), "create branch response");
-            if (typeof value.id !== "string" ||
-                typeof value.name !== "string" ||
-                typeof value.hidden !== "boolean" ||
-                typeof value.commitId !== "string") {
-                throw protocolError("create branch response is invalid");
-            }
-            return {
-                id: value.id,
-                name: value.name,
-                hidden: value.hidden,
-                commitId: value.commitId,
-            };
-        });
-    }
-    async createCheckpoint() {
-        this.#assertOpen();
-        return this.#enqueue(async () => {
-            const value = record(await this.#requestJson("checkpoint/create", { method: "POST" }), "create checkpoint response");
-            if (typeof value.commitId !== "string" ||
-                value.commitId.length === 0) {
-                throw protocolError("create checkpoint response is invalid");
-            }
-            return { commitId: value.commitId };
-        });
-    }
-    async undo() {
-        this.#assertOpen();
-        return this.#enqueue(async () => {
-            const value = record(await this.#requestJson("undo", { method: "POST" }), "undo response");
-            if (typeof value.branchId !== "string" ||
-                typeof value.targetCommitId !== "string" ||
-                typeof value.inverseCommitId !== "string") {
-                throw protocolError("undo response is invalid");
-            }
-            return {
-                branchId: value.branchId,
-                targetCommitId: value.targetCommitId,
-                inverseCommitId: value.inverseCommitId,
-            };
-        });
-    }
-    async redo() {
-        this.#assertOpen();
-        return this.#enqueue(async () => {
-            const value = record(await this.#requestJson("redo", { method: "POST" }), "redo response");
-            if (typeof value.branchId !== "string" ||
-                typeof value.targetCommitId !== "string" ||
-                typeof value.replayCommitId !== "string") {
-                throw protocolError("redo response is invalid");
-            }
-            return {
-                branchId: value.branchId,
-                targetCommitId: value.targetCommitId,
-                replayCommitId: value.replayCommitId,
-            };
-        });
-    }
-    async switchBranch(options) {
-        this.#assertOpen();
-        return this.#enqueue(async () => {
-            let requestAttempted = false;
-            try {
-                const value = record(await this.#requestJson("branch/switch", {
-                    method: "POST",
-                    body: JSON.stringify(options),
-                }, "json", () => {
-                    requestAttempted = true;
-                }), "switch branch response");
-                if (value.branchId !== options.branchId) {
-                    throw protocolError("switch branch response is invalid");
-                }
-                this.#activeBranchId = options.branchId;
-                this.#observationHub.restart();
-                return { branchId: options.branchId };
-            }
-            catch (error) {
-                if (requestAttempted && !isDefinitiveClientError(error)) {
-                    this.#activeBranchId = undefined;
-                    this.#observationHub.restart();
-                }
-                throw error;
-            }
-        });
-    }
-    async importFilesystemPaths(_paths) {
-        this.#assertOpen();
-        throw unsupportedRemoteOperation("importFilesystemPaths");
-    }
-    async mergeBranchPreview(_options) {
-        this.#assertOpen();
-        throw unsupportedRemoteOperation("mergeBranchPreview");
-    }
-    async mergeBranch(_options) {
-        this.#assertOpen();
-        throw unsupportedRemoteOperation("mergeBranch");
-    }
-    async syncDiskToLix() {
-        this.#assertOpen();
-        throw unsupportedRemoteOperation("syncDiskToLix");
-    }
-    async close() {
-        if (this.#closePromise !== undefined)
-            return this.#closePromise;
-        this.#acceptingOperations = false;
-        this.#observationHub.close();
-        this.#closePromise = this.#enqueue(async () => {
-            this.#observationHub.close();
-            await this.#requestJson("session", { method: "DELETE" }, "empty");
-        });
-        return this.#closePromise;
-    }
-    async #requestJson(path, init, responseKind = "json", onRequestAttempt) {
-        const headers = new Headers(await resolveHeaders(this.#headers));
-        new Headers(init.headers).forEach((value, name) => headers.set(name, value));
-        if (this.#sessionId === undefined)
-            headers.delete(REMOTE_SESSION_HEADER);
-        else
-            headers.set(REMOTE_SESSION_HEADER, this.#sessionId);
-        headers.set("accept", "application/json");
-        headers.delete("content-encoding");
-        let requestInit = init;
-        if (init.body !== undefined) {
-            headers.set("content-type", "application/json");
-            if (typeof init.body === "string" &&
-                init.body.length >= MIN_COMPRESSIBLE_JSON_BYTES) {
-                const prepared = await prepareJsonRequestBody(init.body);
-                requestInit = { ...init, body: prepared.body };
-                if (prepared.compressed)
-                    headers.set("content-encoding", "gzip");
-            }
-        }
-        let response;
-        const url = new URL(path, this.#baseUrl);
-        const fetchInit = {
-            ...requestInit,
-            headers,
-        };
-        // A custom fetch may transmit before throwing, so failures become
-        // ambiguous only once control is handed to it.
-        onRequestAttempt?.();
-        try {
-            response = await this.#fetch(url, fetchInit);
-        }
-        catch (cause) {
-            throw remoteError("LIX_REMOTE_UNAVAILABLE", "The remote Lix server is unavailable", { details: { cause: errorMessage(cause) } });
-        }
-        if (!response.ok)
-            throw await errorFromHttpResponse(response);
-        if (responseKind === "empty" || response.status === 204)
-            return undefined;
-        const text = await response.text();
-        try {
-            return JSON.parse(text);
-        }
-        catch {
-            throw protocolError(`remote response ${response.status} did not contain valid JSON`);
-        }
-    }
-    async #requestObserveStream(subscriptions, signal) {
-        let headers;
-        try {
-            headers = new Headers(await resolveHeaders(this.#headers));
-        }
-        catch (cause) {
-            throw remoteError("LIX_REMOTE_CONFIGURATION_ERROR", "Remote Lix observation headers could not be resolved", { details: { cause: errorMessage(cause) } });
-        }
-        signal.throwIfAborted();
-        if (this.#sessionId === undefined) {
-            throw protocolError("remote observation started without a session");
-        }
-        headers.set(REMOTE_SESSION_HEADER, this.#sessionId);
-        headers.set("accept", "text/event-stream");
-        headers.set("content-type", "application/json");
-        headers.delete("content-encoding");
-        const observeBody = JSON.stringify({ subscriptions });
-        const prepared = observeBody.length < MIN_COMPRESSIBLE_JSON_BYTES
-            ? { body: observeBody, compressed: false }
-            : await prepareJsonRequestBody(observeBody);
-        if (prepared.compressed) {
-            headers.set("content-encoding", "gzip");
-        }
-        signal.throwIfAborted();
-        try {
-            return await this.#fetch(new URL("observe/multiplex", this.#baseUrl), {
-                method: "POST",
-                headers,
-                body: prepared.body,
-                signal,
-            });
-        }
-        catch (cause) {
-            if (signal.aborted)
-                throw cause;
-            throw remoteError("LIX_REMOTE_UNAVAILABLE", "The remote Lix observation stream is unavailable", { details: { cause: errorMessage(cause) } });
-        }
-    }
-    async #refreshObservation(subscription) {
-        return this.#enqueue(async () => {
-            const value = await this.#requestJson("execute", {
-                method: "POST",
-                body: JSON.stringify({
-                    sql: subscription.sql,
-                    params: subscription.params,
-                }),
-            });
-            return decodeExecuteResult(value);
-        });
-    }
-    async #prepareParams(params, slot) {
-        const prepared = await Promise.all(params.map(async (param, index) => {
-            if (param.kind !== "blob" ||
-                param.blob.byteLength < REQUEST_BLOB_DELTA_MIN_BYTES ||
-                param.blob.byteLength > REQUEST_BLOB_BASE_MAX_BYTES) {
-                return fullRequestParam(param);
-            }
-            const resultSha256 = await sha256Hex(param.blob);
-            if (resultSha256 === undefined)
-                return fullRequestParam(param);
-            const cacheSlot = slot(index);
-            const cacheUpdate = {
-                slot: cacheSlot,
-                base: {
-                    sha256: resultSha256,
-                    bytes: param.blob,
-                },
-            };
-            const base = this.#requestBlobBases.get(cacheSlot);
-            if (base === undefined) {
-                return { ...fullRequestParam(param), cacheUpdate };
-            }
-            const delta = planBlobSplice(base, param.blob, resultSha256);
-            if (!blobSpliceIsAtLeastTenPercentSmaller(delta, param.blob)) {
-                return { ...fullRequestParam(param), cacheUpdate };
-            }
-            return {
-                value: encodeBlobSplice(delta),
-                full: () => encodeWireValue(param),
-                cacheUpdate,
-            };
-        }));
-        return {
-            params: prepared.map((param) => param.value),
-            fullParams: () => prepared.map((param) => param.full()),
-            cacheUpdates: prepared.flatMap((param) => param.cacheUpdate === undefined ? [] : [param.cacheUpdate]),
-            cacheBlobs: prepared.some((param) => param.cacheUpdate !== undefined),
-            hasDelta: prepared.some((param) => param.value.kind === "blob-splice"),
-        };
-    }
-    #commitRequestBlobBases(updates) {
-        for (const update of updates) {
-            const previous = this.#requestBlobBases.get(update.slot);
-            if (previous !== undefined) {
-                this.#requestBlobBaseBytes -= previous.bytes.byteLength;
-                this.#requestBlobBases.delete(update.slot);
-            }
-            if (update.base.bytes.byteLength > REQUEST_BLOB_BASE_MAX_BYTES)
-                continue;
-            while (this.#requestBlobBases.size >= REQUEST_BLOB_BASE_MAX_ENTRIES ||
-                this.#requestBlobBaseBytes + update.base.bytes.byteLength >
-                    REQUEST_BLOB_BASE_MAX_BYTES) {
-                const oldest = this.#requestBlobBases.entries().next().value;
-                if (oldest === undefined)
-                    break;
-                this.#requestBlobBases.delete(oldest[0]);
-                this.#requestBlobBaseBytes -= oldest[1].bytes.byteLength;
-            }
-            this.#requestBlobBases.set(update.slot, update.base);
-            this.#requestBlobBaseBytes += update.base.bytes.byteLength;
-        }
-    }
-    #assertOpen() {
-        if (!this.#acceptingOperations) {
-            throw remoteError("LIX_ERROR_CLOSED", "Lix is closed");
-        }
-    }
-    #enqueue(operation) {
-        const result = this.#operationQueue.then(operation, operation);
-        this.#operationQueue = result.then(() => undefined, () => undefined);
-        return result;
-    }
-}
-function fullRequestParam(param) {
-    const full = encodeWireValue(param);
-    return { value: full, full: () => full };
-}
-function snapshotParams(params) {
-    return params.map((param) => param.kind === "blob"
-        ? { kind: "blob", value: null, blob: new Uint8Array(param.blob) }
-        : param);
-}
-function requestBlobSlot(kind, sql, paramIndex, statementIndex) {
-    return JSON.stringify([kind, statementIndex, sql, paramIndex]);
-}
-async function sha256Hex(bytes) {
-    const subtle = globalThis.crypto?.subtle;
-    if (subtle === undefined)
-        return undefined;
-    try {
-        const input = bytes.buffer instanceof ArrayBuffer &&
-            bytes.byteOffset === 0 &&
-            bytes.byteLength === bytes.buffer.byteLength
-            ? bytes.buffer
-            : copyArrayBuffer(bytes);
-        const digest = await subtle.digest("SHA-256", input);
-        return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
-    }
-    catch {
-        return undefined;
-    }
-}
-function planBlobSplice(base, result, resultSha256) {
-    const baseView = new DataView(base.bytes.buffer, base.bytes.byteOffset, base.bytes.byteLength);
-    const resultView = new DataView(result.buffer, result.byteOffset, result.byteLength);
-    let prefixBytes = 0;
-    const prefixLimit = Math.min(base.bytes.byteLength, result.byteLength);
-    while (prefixLimit - prefixBytes >= REQUEST_BLOB_COMPARE_WORD_BYTES &&
-        baseView.getUint32(prefixBytes) === resultView.getUint32(prefixBytes) &&
-        baseView.getUint32(prefixBytes + 4) ===
-            resultView.getUint32(prefixBytes + 4)) {
-        prefixBytes += REQUEST_BLOB_COMPARE_WORD_BYTES;
-    }
-    while (prefixBytes < prefixLimit &&
-        base.bytes[prefixBytes] === result[prefixBytes]) {
-        prefixBytes += 1;
-    }
-    let suffixBytes = 0;
-    const suffixLimit = Math.min(base.bytes.byteLength - prefixBytes, result.byteLength - prefixBytes);
-    while (suffixLimit - suffixBytes >= REQUEST_BLOB_COMPARE_WORD_BYTES) {
-        const baseOffset = base.bytes.byteLength - suffixBytes - REQUEST_BLOB_COMPARE_WORD_BYTES;
-        const resultOffset = result.byteLength - suffixBytes - REQUEST_BLOB_COMPARE_WORD_BYTES;
-        if (baseView.getUint32(baseOffset) !== resultView.getUint32(resultOffset) ||
-            baseView.getUint32(baseOffset + 4) !==
-                resultView.getUint32(resultOffset + 4)) {
-            break;
-        }
-        suffixBytes += REQUEST_BLOB_COMPARE_WORD_BYTES;
-    }
-    while (suffixBytes < suffixLimit &&
-        base.bytes[base.bytes.byteLength - suffixBytes - 1] ===
-            result[result.byteLength - suffixBytes - 1]) {
-        suffixBytes += 1;
-    }
-    const insert = result.subarray(prefixBytes, result.byteLength - suffixBytes);
-    return {
-        baseSha256: base.sha256,
-        resultSha256,
-        prefixBytes,
-        suffixBytes,
-        insert,
-    };
-}
-function encodeBlobSplice(plan) {
-    const encodedInsert = encodeWireValue({
-        kind: "blob",
-        value: null,
-        blob: plan.insert,
-    });
-    if (encodedInsert.kind !== "blob") {
-        throw protocolError("request blob splice insert could not be encoded");
-    }
-    return {
-        kind: "blob-splice",
-        baseSha256: plan.baseSha256,
-        resultSha256: plan.resultSha256,
-        prefixBytes: plan.prefixBytes,
-        suffixBytes: plan.suffixBytes,
-        insertBase64: encodedInsert.base64,
-    };
-}
-function blobSpliceIsAtLeastTenPercentSmaller(delta, full) {
-    const deltaEnvelopeBytes = JSON.stringify({
-        kind: "blob-splice",
-        baseSha256: delta.baseSha256,
-        resultSha256: delta.resultSha256,
-        prefixBytes: delta.prefixBytes,
-        suffixBytes: delta.suffixBytes,
-        insertBase64: "",
-    }).length;
-    const deltaBytes = deltaEnvelopeBytes + base64EncodedLength(delta.insert.byteLength);
-    const fullBytes = WIRE_BLOB_JSON_ENVELOPE_BYTES + base64EncodedLength(full.byteLength);
-    return (deltaBytes < fullBytes * REQUEST_BLOB_DELTA_MIN_WIRE_RATIO);
-}
-function base64EncodedLength(byteLength) {
-    return 4 * Math.ceil(byteLength / 3);
-}
-function remoteExecuteOptions(options) {
-    if (options?.originKey === undefined)
-        return undefined;
-    return { originKey: options.originKey };
-}
-function idempotencyKeyFor(provided) {
-    if (provided !== undefined && typeof provided !== "string") {
-        throw new TypeError("options.idempotencyKey must be a string");
-    }
-    const key = provided ?? globalThis.crypto.randomUUID();
-    if (key.length === 0 ||
-        key.length > 255 ||
-        ![...key].every((character) => character.length === 1 &&
-            character.charCodeAt(0) >= 0x21 &&
-            character.charCodeAt(0) <= 0x7e)) {
-        throw new TypeError("options.idempotencyKey must contain 1 to 255 visible ASCII characters");
-    }
-    return key;
-}
-async function requestWithFullBlobFallback(request, fullFallback) {
-    try {
-        return await request();
-    }
-    catch (error) {
-        if (fullFallback !== undefined && errorCode(error) === REMOTE_BLOB_BASE_MISSING) {
-            return await fullFallback();
-        }
-        throw error;
-    }
-}
-function errorCode(error) {
-    return error instanceof Error && "code" in error
-        ? error.code
-        : undefined;
-}
-function copyArrayBuffer(bytes) {
-    const copy = new Uint8Array(bytes.byteLength);
-    copy.set(bytes);
-    return copy.buffer;
-}
-class RemoteObservationHub {
-    #openStream;
-    #refreshObservation;
-    #observations = new Map();
-    #nextObservationId = 0;
-    #controller;
-    #retryTimer;
-    #retryAttempt = 0;
-    #serverRetryMs;
-    #generation = 0;
-    #startQueued = false;
-    #closed = false;
-    constructor(options) {
-        this.#openStream = options.openStream;
-        this.#refreshObservation = options.refreshObservation;
-    }
-    observe(sql, params) {
-        const id = `observe-${++this.#nextObservationId}`;
-        const observation = new RemoteObservation({
-            id,
-            sql,
-            params,
-            onClose: () => {
-                this.#observations.delete(id);
-                this.#restartStream();
-            },
-        });
-        this.#observations.set(id, observation);
-        this.#restartStream();
-        return observation;
-    }
-    close() {
-        if (!this.#closed) {
-            this.#closed = true;
-            this.#stopStream();
-        }
-        for (const observation of [...this.#observations.values()]) {
-            observation.close();
-        }
-        this.#observations.clear();
-    }
-    restart() {
-        if (!this.#closed)
-            this.#restartStream();
-    }
-    #restartStream() {
-        this.#stopStream();
-        if (this.#startQueued)
-            return;
-        this.#startQueued = true;
-        queueMicrotask(() => {
-            this.#startQueued = false;
-            this.#startStream();
-        });
-    }
-    #startStream() {
-        if (this.#closed ||
-            this.#observations.size === 0 ||
-            this.#controller !== undefined ||
-            this.#retryTimer !== undefined) {
-            return;
-        }
-        const generation = this.#generation;
-        const controller = new AbortController();
-        this.#controller = controller;
-        void this.#consume(generation, controller);
-    }
-    #stopStream() {
-        this.#generation += 1;
-        this.#controller?.abort();
-        this.#controller = undefined;
-        if (this.#retryTimer !== undefined)
-            clearTimeout(this.#retryTimer);
-        this.#retryTimer = undefined;
-        this.#retryAttempt = 0;
-        this.#serverRetryMs = undefined;
-    }
-    async #consume(generation, controller) {
-        let reconnect = false;
-        let streamOpened = false;
-        const transportBases = new Map();
-        try {
-            const response = await this.#openStream([...this.#observations.values()].map((observation) => observation.request()), controller.signal);
-            if (!this.#isCurrent(generation, controller))
-                return;
-            streamOpened = true;
-            const initialSubscriptions = new Set(this.#observations.keys());
-            if (!response.ok) {
-                if (isRetryableObserveStatus(response.status)) {
-                    void response.body?.cancel();
-                    reconnect = true;
-                    return;
-                }
-                const error = await errorFromHttpResponse(response);
-                if (this.#isCurrent(generation, controller)) {
-                    this.#failStream(error, controller);
-                }
-                return;
-            }
-            if (!response.body) {
-                this.#failStream(protocolError("remote observe response has no body"), controller);
-                return;
-            }
-            const contentType = response.headers.get("content-type") ?? "";
-            if (contentType.split(";", 1)[0]?.trim().toLowerCase() !==
-                "text/event-stream") {
-                this.#failStream(protocolError("remote observe response must be text/event-stream"), controller);
-                return;
-            }
-            for await (const frame of readSseEvents(response.body)) {
-                if (!this.#isCurrent(generation, controller))
-                    return;
-                if (frame.retry !== undefined)
-                    this.#serverRetryMs = frame.retry;
-                if (frame.event === "next") {
-                    try {
-                        const payload = record(JSON.parse(frame.data), "remote multiplex observe next event");
-                        const subscriptionId = payload.subscriptionId;
-                        if (typeof subscriptionId !== "string") {
-                            throw protocolError("remote observe event requires subscriptionId");
-                        }
-                        const observation = this.#observation(subscriptionId);
-                        const transportDelta = payload.delta !== undefined;
-                        const event = decodeObserveEvent(payload, transportBases.get(subscriptionId));
-                        transportBases.set(subscriptionId, event);
-                        if (initialSubscriptions.delete(subscriptionId)) {
-                            // The first frame after opening (including a reconnect) is a
-                            // synchronization point, not an authoritative snapshot. The
-                            // remote runtime may have observed the stream before its
-                            // external-storage watcher caught up. Reconcile through the
-                            // normal execute endpoint before publishing it to consumers.
-                            const rows = await this.#refreshObservation(observation.request());
-                            observation.accept({
-                                ...event,
-                                rows,
-                            }, false);
-                        }
-                        else {
-                            observation.accept(event, transportDelta);
-                        }
-                        this.#retryAttempt = 0;
-                    }
-                    catch (error) {
-                        this.#failStream(asObserveProtocolError(error, "next"), controller);
-                        return;
-                    }
-                }
-                else if (frame.event === "error") {
-                    try {
-                        const payload = record(JSON.parse(frame.data), "remote multiplex observe error event");
-                        if (payload.retryable !== undefined &&
-                            typeof payload.retryable !== "boolean") {
-                            throw protocolError("remote observe error retryable must be a boolean");
-                        }
-                        const error = errorFromResponseBody(payload);
-                        const subscriptionId = payload.subscriptionId;
-                        if (subscriptionId !== undefined) {
-                            if (typeof subscriptionId !== "string") {
-                                throw protocolError("remote observe event requires subscriptionId");
-                            }
-                            const observation = this.#observation(subscriptionId);
-                            if (payload.retryable === true) {
-                                observation.recover(error);
-                                reconnect = true;
-                                controller.abort();
-                                return;
-                            }
-                            observation.fail(error);
-                            this.#observations.delete(subscriptionId);
-                            continue;
-                        }
-                        if (payload.retryable === true) {
-                            for (const observation of this.#observations.values()) {
-                                observation.recover(error);
-                            }
-                            reconnect = true;
-                            controller.abort();
-                        }
-                        else {
-                            this.#failStream(error, controller);
-                        }
-                    }
-                    catch (error) {
-                        this.#failStream(asObserveProtocolError(error, "error"), controller);
-                    }
-                    return;
-                }
-                else if (frame.event !== "message" || frame.data.length > 0) {
-                    this.#failStream(protocolError(`unknown remote observe event: ${frame.event}`), controller);
-                    return;
-                }
-            }
-            if (this.#isCurrent(generation, controller))
-                reconnect = true;
-        }
-        catch (error) {
-            if (!this.#isCurrent(generation, controller) ||
-                controller.signal.aborted) {
-                return;
-            }
-            if (streamOpened || isRetryableObserveError(error))
-                reconnect = true;
-            else
-                this.#failStream(error, controller);
-        }
-        finally {
-            if (this.#isCurrent(generation, controller)) {
-                this.#controller = undefined;
-                if (reconnect)
-                    this.#scheduleReconnect(generation);
-            }
-        }
-    }
-    #observation(id) {
-        if (typeof id !== "string" || id.length === 0) {
-            throw protocolError("remote observe event requires subscriptionId");
-        }
-        const observation = this.#observations.get(id);
-        if (!observation) {
-            throw protocolError(`unknown remote observe subscription: ${id}`);
-        }
-        return observation;
-    }
-    #failAll(error) {
-        for (const observation of this.#observations.values()) {
-            observation.fail(error);
-        }
-    }
-    #failStream(error, controller) {
-        this.#failAll(error);
-        controller.abort();
-    }
-    #scheduleReconnect(generation) {
-        if (this.#closed ||
-            this.#observations.size === 0 ||
-            generation !== this.#generation ||
-            this.#controller !== undefined ||
-            this.#retryTimer !== undefined) {
-            return;
-        }
-        const delay = this.#serverRetryMs === undefined
-            ? Math.min(OBSERVE_RETRY_BASE_MS * 2 ** this.#retryAttempt, OBSERVE_RETRY_MAX_MS)
-            : Math.min(Math.max(this.#serverRetryMs, OBSERVE_RETRY_BASE_MS), OBSERVE_RETRY_MAX_MS);
-        this.#retryAttempt += 1;
-        this.#retryTimer = setTimeout(() => {
-            this.#retryTimer = undefined;
-            if (generation === this.#generation)
-                this.#startStream();
-        }, delay);
-    }
-    #isCurrent(generation, controller) {
-        return (!this.#closed &&
-            generation === this.#generation &&
-            controller === this.#controller);
-    }
+import { initializeBrowserWasm } from "../browser-wasm-init.js";
+// Generated before TypeScript compilation and emitted beside the JS SDK.
+// @ts-ignore Generated by build:wasm and absent in source-only checks.
+import initWasm, { openRemote } from "../wasm/lix_js_sdk.js";
+let wasmInitialized;
+function initializeWasm() {
+    if (wasmInitialized !== undefined)
+        return wasmInitialized;
+    let initialization;
+    if (typeof process !== "undefined" && process.versions?.node) {
+        initialization = import("node:fs/promises").then(({ readFile }) => initWasm({
+            module_or_path: readFile(new URL("../wasm/lix_js_sdk_bg.wasm", import.meta.url)),
+        }), (error) => {
+            wasmInitialized = undefined;
+            throw error;
+        });
+    }
+    else {
+        initialization = initializeBrowserWasm(initWasm, new URL("../wasm/lix_js_sdk_bg.wasm", import.meta.url));
+    }
+    wasmInitialized = initialization;
+    return wasmInitialized;
 }
-class RemoteObservation {
-    #id;
-    #sql;
-    #params;
-    #onClose;
-    #outcomes = [];
-    #waiters = [];
-    #terminalError;
-    #lastRows;
-    #lastSequence = -1;
-    #closed = false;
-    constructor(options) {
-        this.#id = options.id;
-        this.#sql = options.sql;
-        this.#params = options.params;
-        this.#onClose = options.onClose;
-    }
-    request() {
-        return { id: this.#id, sql: this.#sql, params: this.#params };
-    }
-    next() {
-        const outcome = this.#outcomes.shift();
-        if (outcome?.ok)
-            return Promise.resolve(outcome.event);
-        if (outcome)
-            return Promise.reject(outcome.error);
-        if (this.#terminalError !== undefined) {
-            return Promise.reject(this.#terminalError);
-        }
-        if (this.#closed)
-            return Promise.resolve(undefined);
-        return new Promise((resolve, reject) => {
-            this.#waiters.push({ resolve, reject });
-        });
-    }
-    close() {
-        if (this.#closed)
-            return;
-        this.#closed = true;
-        this.#outcomes = [];
-        this.#terminalError = undefined;
-        for (const waiter of this.#waiters.splice(0))
-            waiter.resolve(undefined);
-        this.#onClose();
-    }
-    accept(event, transportDelta = false) {
-        if (this.#closed || this.#terminalError !== undefined)
-            return;
-        if (!transportDelta &&
-            this.#lastRows !== undefined &&
-            executeResultsEqual(this.#lastRows, event.rows)) {
-            return;
-        }
-        const normalized = {
-            sequence: this.#lastSequence + 1,
-            mutationSequence: event.mutationSequence,
-            rows: event.rows,
-        };
-        this.#lastRows = event.rows;
-        this.#lastSequence = normalized.sequence;
-        const waiter = this.#waiters.shift();
-        if (waiter)
-            waiter.resolve(normalized);
-        else {
-            this.#outcomes = this.#outcomes.filter((outcome) => !outcome.ok);
-            this.#outcomes.push({ ok: true, event: normalized });
-        }
-    }
-    recover(error) {
-        if (this.#closed || this.#terminalError !== undefined)
-            return;
-        const waiter = this.#waiters.shift();
-        if (waiter)
-            waiter.reject(error);
-        else if (!this.#outcomes.some((outcome) => !outcome.ok)) {
-            this.#outcomes.push({ ok: false, error });
-        }
-    }
-    fail(error) {
-        if (this.#closed || this.#terminalError !== undefined)
-            return;
-        this.#terminalError = error;
-        for (const waiter of this.#waiters.splice(0))
-            waiter.reject(error);
+export async function openRemoteLixBinding(options, clientOptions = {}) {
+    if (!options || typeof options !== "object") {
+        throw new TypeError("openLix() remote server must be an object");
     }
-}
-async function prepareJsonRequestBody(body) {
-    const bytes = new TextEncoder().encode(body);
-    if (bytes.byteLength < MIN_COMPRESSIBLE_JSON_BYTES) {
-        return { body, compressed: false };
+    if (options.mode !== "remote") {
+        throw new TypeError("openLix() remote server mode must be 'remote'");
     }
-    const sample = bytes.subarray(0, Math.min(bytes.byteLength, COMPRESSION_SAMPLE_BYTES));
-    const compressedSample = await gzipBytes(sample);
-    if (compressedSample.byteLength >
-        sample.byteLength * MAX_COMPRESSION_SAMPLE_RATIO) {
-        return { body, compressed: false };
+    const remoteFetch = options.fetch ?? globalThis.fetch?.bind(globalThis);
+    if (typeof remoteFetch !== "function") {
+        throw new TypeError("openLix() remote mode requires fetch");
     }
-    const compressed = await gzipBytes(bytes);
-    if (compressed.byteLength > bytes.byteLength * MAX_COMPRESSED_BODY_RATIO) {
-        return { body, compressed: false };
+    if (options.headers !== undefined &&
+        typeof options.headers !== "function" &&
+        !isHeadersInit(options.headers)) {
+        throw new TypeError("openLix() remote server headers must be HeadersInit or a function");
     }
-    const transportBody = new ArrayBuffer(compressed.byteLength);
-    new Uint8Array(transportBody).set(compressed);
-    return { body: transportBody, compressed: true };
-}
-async function gzipBytes(bytes) {
-    const CompressionStreamConstructor = globalThis.CompressionStream;
-    if (typeof CompressionStreamConstructor === "function") {
-        const stream = new CompressionStreamConstructor("gzip");
-        const output = new Response(stream.readable).arrayBuffer();
-        const writer = stream.writable.getWriter();
-        await writer.write(bytes);
-        await writer.close();
-        return new Uint8Array(await output);
+    if (clientOptions.initialActiveBranchId !== undefined &&
+        clientOptions.initialActiveBranchId.length === 0) {
+        throw new TypeError("initialActiveBranchId must be a non-empty string");
     }
-    const { gzipSync } = await import("fflate");
-    return gzipSync(bytes, { level: 1 });
+    const protocolLocator = connectionUrl(options.url).toString();
+    await initializeWasm();
+    return openRemote(protocolLocator, remoteFetch, options.headers, clientOptions.initialActiveBranchId);
 }
-async function resolveHeaders(headers) {
-    return typeof headers === "function" ? await headers() : headers;
-}
-async function errorFromHttpResponse(response) {
-    const text = await response.text();
+function connectionUrl(value) {
+    let locator;
     try {
-        return errorFromResponseBody(JSON.parse(text), response.status);
-    }
-    catch (error) {
-        if (error instanceof Error &&
-            "status" in error &&
-            error.status === response.status) {
-            return error;
-        }
-        return remoteError("LIX_REMOTE_REQUEST_FAILED", `Remote Lix request failed with status ${response.status}`, {
-            status: response.status,
-            details: text.length === 0 ? undefined : { body: text.slice(0, 1000) },
-        });
-    }
-}
-function isDefinitiveClientError(error) {
-    if (!(error instanceof Error) || !("status" in error))
-        return false;
-    const status = error.status;
-    return (typeof status === "number" &&
-        status >= 400 &&
-        status < 500 &&
-        status !== 408 &&
-        status !== 429);
-}
-function isRetryableObserveStatus(status) {
-    return status === 408 || status === 429 || status >= 500;
-}
-function isRetryableObserveError(error) {
-    return (error instanceof Error &&
-        "code" in error &&
-        error.code === "LIX_REMOTE_UNAVAILABLE");
-}
-function asObserveProtocolError(error, event) {
-    if (error instanceof Error &&
-        "code" in error &&
-        error.code === "LIX_SERVER_PROTOCOL_ERROR") {
-        return error;
-    }
-    return protocolError(`remote observe ${event} event contains invalid data: ${errorMessage(error)}`);
-}
-function executeResultsEqual(left, right) {
-    return (left.rowsAffected === right.rowsAffected &&
-        stringArraysEqual(left.columns, right.columns) &&
-        left.rows.length === right.rows.length &&
-        left.rows.every((row, rowIndex) => row.length === right.rows[rowIndex]?.length &&
-            row.every((value, valueIndex) => nativeValuesEqual(value, right.rows[rowIndex]?.[valueIndex]))) &&
-        left.notices.length === right.notices.length &&
-        left.notices.every((notice, index) => {
-            const other = right.notices[index];
-            return (notice.code === other?.code &&
-                notice.message === other.message &&
-                notice.hint === other.hint);
-        }));
-}
-function nativeValuesEqual(left, right) {
-    if (!right || left.kind !== right.kind)
-        return false;
-    switch (left.kind) {
-        case "blob":
-            return (right.kind === "blob" &&
-                left.blob.length === right.blob.length &&
-                left.blob.every((byte, index) => byte === right.blob[index]));
-        case "jsonb":
-            return right.kind === "jsonb" && jsonValuesEqual(left.value, right.value);
-        default:
-            return left.value === right.value;
-    }
-}
-function jsonValuesEqual(left, right) {
-    if (left === right)
-        return true;
-    if (Array.isArray(left) || Array.isArray(right)) {
-        return (Array.isArray(left) &&
-            Array.isArray(right) &&
-            left.length === right.length &&
-            left.every((value, index) => jsonValuesEqual(value, right[index])));
-    }
-    if (!left ||
-        !right ||
-        typeof left !== "object" ||
-        typeof right !== "object") {
-        return false;
-    }
-    const leftRecord = left;
-    const rightRecord = right;
-    const leftKeys = Object.keys(leftRecord).sort();
-    const rightKeys = Object.keys(rightRecord).sort();
-    return (stringArraysEqual(leftKeys, rightKeys) &&
-        leftKeys.every((key) => jsonValuesEqual(leftRecord[key], rightRecord[key])));
-}
-function stringArraysEqual(left, right) {
-    return (left.length === right.length &&
-        left.every((value, index) => value === right[index]));
-}
-function protocolBaseUrl(value) {
-    let repositoryUrl;
-    try {
-        repositoryUrl = new URL(value);
+        locator = new URL(value);
     }
     catch {
         throw new TypeError("openLix() remote server url must be an absolute URL");
     }
-    if (repositoryUrl.protocol !== "http:" &&
-        repositoryUrl.protocol !== "https:") {
-        throw new TypeError("openLix() remote server url must use http or https");
+    if (locator.protocol !== "https:" &&
+        !(locator.protocol === "http:" && isLoopbackHost(locator.hostname))) {
+        throw new TypeError("openLix() remote server url must use https (http is allowed only for loopback development)");
     }
-    if (repositoryUrl.search || repositoryUrl.hash) {
+    if (locator.search || locator.hash) {
         throw new TypeError("openLix() remote server url must not contain a query or fragment");
     }
-    repositoryUrl.pathname = `${repositoryUrl.pathname.replace(/\/$/, "")}${SERVER_PROTOCOL_PATH}`;
-    return repositoryUrl;
+    if (locator.username || locator.password) {
+        throw new TypeError("openLix() remote server url must not contain credentials");
+    }
+    if (!/^\/lix\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(locator.pathname)) {
+        throw new TypeError("openLix() remote server url path must be exactly /lix/{uuid}");
+    }
+    return locator;
 }
-function unsupportedRemoteOperation(operation) {
-    return remoteError("LIX_UNSUPPORTED_REMOTE_OPERATION", `${operation} is not supported in remote mode`, { details: { operation } });
+function isLoopbackHost(hostname) {
+    return (hostname === "localhost" ||
+        hostname === "[::1]" ||
+        /^127(?:\.[0-9]{1,3}){3}$/.test(hostname));
 }
 function isHeadersInit(value) {
     try {
@@ -1172,6 +82,3 @@ function isHeadersInit(value) {
         return false;
     }
 }
-function errorMessage(value) {
-    return value instanceof Error ? value.message : String(value);
-}