@lix-js/sdk 0.16.1 → 0.17.0

package/dist/component-host/instrument.js

@@ -0,0 +1,260 @@
+import binaryen from "binaryen";
+export const TICK_MODULE = "lix:runtime/deadline";
+/** Fields containing child expressions for the supported, non-GC core ISA. */
+const fields = {
+    Block: ["children"],
+    If: ["condition", "ifTrue", "ifFalse"],
+    Loop: ["body"],
+    Break: ["condition", "value"],
+    Switch: ["condition", "value"],
+    Call: ["operands"],
+    CallIndirect: ["target", "operands"],
+    LocalGet: [],
+    LocalSet: ["value"],
+    GlobalGet: [],
+    GlobalSet: ["value"],
+    TableGet: ["index"],
+    TableSet: ["index", "value"],
+    TableSize: [],
+    TableGrow: ["value", "delta"],
+    Load: ["ptr"],
+    Store: ["ptr", "value"],
+    Const: [],
+    Unary: ["value"],
+    Binary: ["left", "right"],
+    Select: ["ifTrue", "ifFalse", "condition"],
+    Drop: ["value"],
+    Return: ["value"],
+    Nop: [],
+    Unreachable: [],
+    MemorySize: [],
+    MemoryGrow: ["delta"],
+    MemoryInit: ["dest", "offset", "size"],
+    DataDrop: [],
+    MemoryCopy: ["dest", "source", "size"],
+    MemoryFill: ["dest", "value", "size"],
+    RefNull: [],
+    RefFunc: [],
+    RefIs: ["value"],
+    RefAs: ["value"],
+    RefEq: ["left", "right"],
+    TupleMake: ["operands"],
+    TupleExtract: ["tuple"],
+};
+const childFields = new Map(Object.entries(fields).map(([name, keys]) => [
+    binaryen[`${name}Id`],
+    keys,
+]));
+/** Add checks on every cycle (function/loop entry) and cap memory before compilation. */
+export function instrumentCore(bytes, maxMemoryBytes) {
+    if (!Number.isSafeInteger(maxMemoryBytes) || maxMemoryBytes < 65536)
+        throw new Error("Component memory limit must be at least one Wasm page");
+    const module = binaryen.readBinary(capMemory(bytes, Math.floor(maxMemoryBytes / 65536)));
+    try {
+        module.setFeatures(binaryen.Features.All);
+        // Match the native host's table element limit as well as linear memory.
+        for (let index = 0; index < module.getNumTables(); index++) {
+            const table = module.getTableByIndex(index);
+            const info = binaryen.getTableInfo(table);
+            if (info.initial > 1_000_000)
+                throw new Error("Component table exceeds element limit");
+            binaryen._BinaryenTableSetMax(table, Math.min(info.max ?? 1_000_000, 1_000_000));
+        }
+        if (module.hasMemory() && Boolean(module.getMemoryInfo().module))
+            throw new Error("Imported component memories are unsupported");
+        if (module.getExport("__lix_runtime_memory"))
+            throw new Error("Reserved runtime memory export");
+        let serial = 0;
+        let tick = "lix_deadline";
+        while (module.getFunction(tick))
+            tick = `lix_deadline_${++serial}`;
+        module.addFunctionImport(tick, TICK_MODULE, "tick", binaryen.none, binaryen.none);
+        const check = () => module.call(tick, [], binaryen.none);
+        for (let index = 0; index < module.getNumFunctions(); index++) {
+            const func = module.getFunctionByIndex(index);
+            const body = binaryen.getFunctionInfo(func).body;
+            if (!body)
+                continue;
+            const pending = [body];
+            while (pending.length) {
+                const expression = pending.pop();
+                const expressionId = binaryen.getExpressionId(expression);
+                if (!childFields.has(expressionId))
+                    throw new Error(`Unsupported component instruction ${expressionId}`);
+                if (childFields.get(expressionId).length === 0)
+                    continue;
+                const info = binaryen.getExpressionInfo(expression);
+                const keys = childFields.get(info.id);
+                if (!keys)
+                    throw new Error(`Unsupported component instruction ${info.id}`);
+                for (const key of keys) {
+                    const value = info[key];
+                    if (Array.isArray(value))
+                        pending.push(...value.filter(Boolean));
+                    else if (value)
+                        pending.push(value);
+                }
+                if (info.id === binaryen.LoopId) {
+                    binaryen._BinaryenLoopSetBody(expression, module.block(null, [check(), info.body], binaryen.getExpressionType(info.body)));
+                }
+            }
+            binaryen._BinaryenFunctionSetBody(func, module.block(null, [check(), body], binaryen.getExpressionType(body)));
+        }
+        if (!module.validate())
+            throw new Error("Invalid instrumented component module");
+        return exposeMemory(module.emitBinary(), module.hasMemory());
+    }
+    finally {
+        module.dispose();
+    }
+}
+/** Rewrite only the core memory section; all other sections stay byte-identical. */
+function capMemory(bytes, pages) {
+    let offset = 8;
+    const read = () => {
+        let value = 0, shift = 0;
+        for (let count = 0; count < 5; count++) {
+            const byte = bytes[offset++];
+            if (byte === undefined)
+                throw new Error("Truncated Wasm integer");
+            value += (byte & 127) * 2 ** shift;
+            if (!(byte & 128))
+                return value;
+            shift += 7;
+        }
+        throw new Error("Invalid Wasm integer");
+    };
+    const leb = (value) => {
+        const result = [];
+        do {
+            const byte = value % 128;
+            value = Math.floor(value / 128);
+            result.push(byte | (value ? 128 : 0));
+        } while (value);
+        return result;
+    };
+    while (offset < bytes.length) {
+        const sectionStart = offset;
+        const id = bytes[offset++];
+        const length = read();
+        const end = offset + length;
+        if (end > bytes.length)
+            throw new Error("Truncated Wasm section");
+        if (id !== 5) {
+            offset = end;
+            continue;
+        }
+        const count = read();
+        if (count !== 1)
+            throw new Error("Multiple component memories are unsupported");
+        const flags = read();
+        if (flags !== 0 && flags !== 1)
+            throw new Error("Shared and 64-bit component memories are unsupported");
+        const minimum = read();
+        const maximum = flags === 1 ? read() : pages;
+        if (offset !== end || minimum > pages)
+            throw new Error("Component initial memory exceeds limit");
+        const memory = [1, 1, ...leb(minimum), ...leb(Math.min(maximum, pages))];
+        const section = new Uint8Array([5, ...leb(memory.length), ...memory]);
+        const result = new Uint8Array(sectionStart + section.length + bytes.length - end);
+        result.set(bytes.subarray(0, sectionStart));
+        result.set(section, sectionStart);
+        result.set(bytes.subarray(end), sectionStart + section.length);
+        return result;
+    }
+    return bytes;
+}
+/** Add an inspection-only memory export without changing any guest index. */
+function exposeMemory(bytes, hasMemory) {
+    if (!hasMemory)
+        return bytes;
+    const name = new TextEncoder().encode("__lix_runtime_memory");
+    const encode = (value) => {
+        const out = [];
+        do {
+            const byte = value % 128;
+            value = Math.floor(value / 128);
+            out.push(byte | (value ? 128 : 0));
+        } while (value);
+        return out;
+    };
+    let offset = 8;
+    const read = () => {
+        let result = 0, shift = 0;
+        for (;;) {
+            const b = bytes[offset++];
+            result += (b & 127) * 2 ** shift;
+            if (!(b & 128))
+                return result;
+            shift += 7;
+        }
+    };
+    while (offset < bytes.length) {
+        const start = offset;
+        const id = bytes[offset++];
+        const size = read();
+        const end = offset + size;
+        if (id < 7 || id === 0) {
+            offset = end;
+            continue;
+        }
+        let payload;
+        let replaceEnd = start;
+        if (id === 7) {
+            const count = read();
+            payload = new Uint8Array([
+                ...encode(count + 1),
+                ...bytes.subarray(offset, end),
+                ...encode(name.length),
+                ...name,
+                2,
+                0,
+            ]);
+            replaceEnd = end;
+        }
+        else
+            payload = new Uint8Array([1, ...encode(name.length), ...name, 2, 0]);
+        const header = new Uint8Array([7, ...encode(payload.length)]);
+        const result = new Uint8Array(start + header.length + payload.length + bytes.length - replaceEnd);
+        result.set(bytes.subarray(0, start));
+        result.set(header, start);
+        result.set(payload, start + header.length);
+        result.set(bytes.subarray(replaceEnd), start + header.length + payload.length);
+        return result;
+    }
+    const payload = new Uint8Array([1, ...encode(name.length), ...name, 2, 0]);
+    const result = new Uint8Array(bytes.length + payload.length + encode(payload.length).length + 1);
+    result.set(bytes);
+    result.set([7, ...encode(payload.length), ...payload], bytes.length);
+    return result;
+}
+/** Count defined memories to apportion the component's aggregate ceiling. */
+export function coreMemoryCount(bytes) {
+    return coreSectionCount(bytes, 5);
+}
+export function coreTableCount(bytes) {
+    return coreSectionCount(bytes, 4);
+}
+function coreSectionCount(bytes, section) {
+    let offset = 8;
+    const read = () => {
+        let value = 0;
+        for (let shift = 0; shift < 35; shift += 7) {
+            const byte = bytes[offset++];
+            if (byte === undefined)
+                throw new Error("Truncated Wasm integer");
+            value += (byte & 127) * 2 ** shift;
+            if (!(byte & 128))
+                return value;
+        }
+        throw new Error("Invalid Wasm integer");
+    };
+    while (offset < bytes.length) {
+        const id = bytes[offset++];
+        const size = read();
+        if (id === section)
+            return read();
+        offset += size;
+    }
+    return 0;
+}

package/dist/conversion-provider.d.ts

@@ -0,0 +1,4 @@
+/** The closed-storage binding owns one provider close, including setup failures. */
+export declare function withConversionProvider<T>(provider: {
+    close(): Promise<void>;
+}, convert: () => Promise<T>): Promise<T>;

package/dist/conversion-provider.js

@@ -0,0 +1,20 @@
+/** The closed-storage binding owns one provider close, including setup failures. */
+export async function withConversionProvider(provider, convert) {
+    let failed = false;
+    try {
+        return await convert();
+    }
+    catch (error) {
+        failed = true;
+        throw error;
+    }
+    finally {
+        try {
+            await provider.close();
+        }
+        catch (error) {
+            if (!failed)
+                throw error;
+        }
+    }
+}

package/dist/hosted-lix.js

@@ -6,7 +6,7 @@ async function resolveServer(server) {
     if ("fetch" in server && server.fetch !== undefined)
         throw new TypeError("hosted lifecycle does not accept a custom fetch");
     if ("mode" in server)
-        throw new TypeError("server.mode was removed");
+        throw new TypeError("hosted lifecycle does not accept server.mode; mode selects openLix execution");
     const url = new URL(server.url).toString();
     const headers = new Headers(typeof server.headers === "function"
         ? await server.headers()

package/dist/http-transport.d.ts

@@ -0,0 +1,25 @@
+/** The internal HTTP ABI shared by WASM, worker RPC, sync and admission. */
+export type HttpResponsePolicy = {
+    mode: "buffered";
+    maxBytes: number;
+} | {
+    mode: "streaming";
+};
+export type HttpRequest = {
+    url: string;
+    init: RequestInit;
+    response: HttpResponsePolicy;
+};
+export type HttpTransport = (request: HttpRequest) => Promise<Response>;
+export declare class HttpTransportError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+export declare function validateHttpRequest(request: HttpRequest): void;
+/** Invoke browser fetch with failure classification at the actual I/O boundary.
+ * Custom telemetry adapters should delegate here and preserve the typed error.
+ */
+export declare function networkFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+/** Public fetch callbacks are network adapters; they must preserve explicit credentials. */
+export declare function fetchTransport(fetcher?: typeof fetch): HttpTransport;
+export declare function boundedResponseBody(response: Response, maxBytes: number): Promise<Uint8Array<ArrayBuffer>>;

package/dist/http-transport.js

@@ -0,0 +1,162 @@
+export class HttpTransportError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "HttpTransportError";
+    }
+}
+export function validateHttpRequest(request) {
+    if (!request || typeof request.url !== "string" || !request.init ||
+        (request.response?.mode !== "streaming" &&
+            !(request.response?.mode === "buffered" && Number.isSafeInteger(request.response.maxBytes) && request.response.maxBytes > 0))) {
+        throw new HttpTransportError("LIX_TRANSPORT_CONTRACT", "HTTP request requires an explicit response policy");
+    }
+}
+/** Invoke browser fetch with failure classification at the actual I/O boundary.
+ * Custom telemetry adapters should delegate here and preserve the typed error.
+ */
+export async function networkFetch(input, init) {
+    const request = validatedRequest(input, init);
+    let response;
+    try {
+        response = await globalThis.fetch(request);
+    }
+    catch (error) {
+        throw nativeNetworkFailure(error, request.signal);
+    }
+    return classifiedResponse(response, error => nativeNetworkFailure(error, request.signal));
+}
+// Keep error classification attached to the body producer, including failures
+// after response headers. This wrapper preserves pull-driven backpressure.
+function classifiedResponse(response, classify) {
+    // Fetch instrumentation may expose an empty stream for a status whose
+    // body is forbidden by the Response constructor.
+    if (response.status === 204 || response.status === 205 || response.status === 304) {
+        void response.body?.cancel().catch(() => undefined);
+        return new Response(null, { status: response.status, statusText: response.statusText, headers: response.headers });
+    }
+    if (!response.body)
+        return response;
+    const reader = response.body.getReader();
+    let released = false;
+    const release = () => { if (!released) {
+        released = true;
+        reader.releaseLock();
+    } };
+    const body = new ReadableStream({
+        async pull(controller) {
+            try {
+                const chunk = await reader.read();
+                if (chunk.done) {
+                    release();
+                    controller.close();
+                }
+                else
+                    controller.enqueue(chunk.value);
+            }
+            catch (error) {
+                release();
+                controller.error(classify(error));
+            }
+        },
+        async cancel(reason) { try {
+            await reader.cancel(reason);
+        }
+        finally {
+            release();
+        } },
+    });
+    return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+}
+function nativeNetworkFailure(error, signal) {
+    if (signal.aborted || (error instanceof Error && error.name === "AbortError")) {
+        return new HttpTransportError("LIX_TRANSPORT_ABORTED", "HTTP request was cancelled");
+    }
+    if (error instanceof TypeError)
+        return new HttpTransportError("LIX_TRANSPORT_NETWORK", "HTTP network request failed");
+    return new HttpTransportError("LIX_TRANSPORT_CALLBACK", "HTTP adapter failed");
+}
+/** Public fetch callbacks are network adapters; they must preserve explicit credentials. */
+export function fetchTransport(fetcher) {
+    return async (request) => {
+        validateHttpRequest(request);
+        // Validate browser request arguments outside the network-failure boundary.
+        const validated = validatedRequest(request.url, request.init);
+        let response;
+        try {
+            response = await (fetcher ?? networkFetch)(validated.url, request.init);
+        }
+        catch (error) {
+            if (request.init.signal?.aborted || (error instanceof Error && error.name === "AbortError")) {
+                throw new HttpTransportError("LIX_TRANSPORT_ABORTED", "HTTP request was cancelled");
+            }
+            if (isTransportFailure(error))
+                throw error;
+            // Arbitrary user callbacks may throw TypeError for programming errors.
+            throw new HttpTransportError("LIX_TRANSPORT_CALLBACK", "HTTP adapter failed");
+        }
+        if (fetcher) {
+            response = classifiedResponse(response, error => {
+                if (isTransportFailure(error))
+                    return error;
+                if (request.init.signal?.aborted)
+                    return new HttpTransportError("LIX_TRANSPORT_ABORTED", "HTTP request was cancelled");
+                return new HttpTransportError("LIX_TRANSPORT_CALLBACK", "HTTP response adapter failed");
+            });
+        }
+        if (request.response.mode === "streaming")
+            return response;
+        const bytes = await boundedResponseBody(response, request.response.maxBytes);
+        return new Response(response.status === 204 || response.status === 205 || response.status === 304 ? null : bytes, { status: response.status, statusText: response.statusText, headers: response.headers });
+    };
+}
+export async function boundedResponseBody(response, maxBytes) {
+    const oversized = () => new HttpTransportError("LIX_TRANSPORT_RESPONSE_LIMIT", "HTTP response exceeds its declared resource budget");
+    if (Number(response.headers.get("content-length")) > maxBytes) {
+        await response.body?.cancel().catch(() => undefined);
+        throw oversized();
+    }
+    if (!response.body)
+        return new Uint8Array();
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel().catch(() => undefined);
+                throw oversized();
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+function validatedRequest(input, init) {
+    try {
+        return new Request(input, init);
+    }
+    catch {
+        throw new HttpTransportError("LIX_TRANSPORT_CONTRACT", "Invalid HTTP request arguments");
+    }
+}
+// Error codes, unlike constructor identity, survive worker RPC and duplicate
+// package realms. Only the explicit transport namespace crosses this boundary.
+function isTransportFailure(error) {
+    return error instanceof Error && typeof error.code === "string" &&
+        error.code.startsWith("LIX_TRANSPORT_");
+}

package/dist/index.d.ts

@@ -3,5 +3,6 @@ export type { LixStorage, LixStorageBound, LixStorageChangeWatch, LixStorageComm
 export { LixStorageError } from "./storage-adapter.js";
 export { bundledPluginArchives, type BundledPluginArchive, } from "./bundled-plugins.js";
 export { Value } from "./value.js";
-export type { CreateBranchOptions, CreateBranchReceipt, RedoReceipt, CommitSpan, ExecuteOptions, ExecuteResult, ExecuteBatchResult, LixBatchOptions, LixBatchStatement, JsonValue, LixValue, ResultArrayRow, ResultColumn, ResultColumnType, ResultObjectRow, ResultRow, MergeBranchOptions, MergeBranchOutcome, MergeBranchPreview, MergeBranchReceipt, MergeChangeStats, MergeConflict, MergeConflictSide, ObserveEvent, OpenLixOptions, OpenAnotherSessionOptions, LixTelemetryOptions, LixTelemetryParentContext, LixTelemetrySpan, LixTelemetrySpanLink, LixOpenMigrationReport, LixOpenPhase, LixOpenProgress, LixOpenProgressOptions, LixOpenReport, ReplicaRecoverySource, ReplicaRecoveryRow, ReplicaRecoveryBranch, ReplicaRecoveryBlob, ReplicaRecoveryFile, ReplicaRecoveryExport, ReplicaRecoveryReceipt, RemoteLixFetch, LixServerOptions, HostedLix, CreateLixOptions, DeleteLixOptions, UndoReceipt, SqlParam, SwitchBranchOptions, SwitchBranchReceipt, } from "./types.js";
+export type { CreateBranchOptions, CreateBranchReceipt, RedoReceipt, CommitSpan, ExecuteOptions, ExecuteResult, ExecuteBatchResult, ExecuteBatchStatementResult, CommitReceipt, StatementResult, LixBatchOptions, LixBatchStatement, JsonValue, LixValue, ResultArrayRow, ResultColumn, ResultColumnType, ResultObjectRow, ResultRow, MergeBranchOptions, MergeBranchOutcome, MergeBranchPreview, MergeBranchReceipt, MergeChangeStats, ObserveEvent, OpenLixOptions, Durability, OpenAnotherSessionOptions, LixTelemetryOptions, LixTelemetryParentContext, LixTelemetrySpan, LixTelemetrySpanLink, LixOpenMigrationReport, LixOpenPhase, LixOpenProgress, LixOpenProgressOptions, LixOpenReport, SyncHealth, ReplicaRecoverySource, ReplicaRecoveryRow, ReplicaRecoveryBranch, ReplicaRecoveryBlob, ReplicaRecoveryFile, ReplicaRecoveryExport, ReplicaRecoveryReceipt, RemoteLixFetch, LixServerOptions, RemoteLixServerOptions, PartialReplicaLixServerOptions, HostedLix, CreateLixOptions, DeleteLixOptions, UndoReceipt, SqlParam, SwitchBranchOptions, SwitchBranchReceipt, } from "./types.js";
 export { createLix, deleteLix } from "./hosted-lix.js";
+export { networkFetch, HttpTransportError } from "./http-transport.js";

package/dist/index.js

@@ -3,3 +3,4 @@ export { LixStorageError } from "./storage-adapter.js";
 export { bundledPluginArchives, } from "./bundled-plugins.js";
 export { Value } from "./value.js";
 export { createLix, deleteLix } from "./hosted-lix.js";
+export { networkFetch, HttpTransportError } from "./http-transport.js";

package/dist/lix.d.ts

@@ -1,5 +1,5 @@
 import type { LixBinding, LixTransactionBinding, ObserveEventsBinding } from "./binding-types.js";
-import type { CreateBranchOptions, CreateBranchReceipt, RedoReceipt, ExecuteOptions, ExecuteResult, ExecuteBatchResult, LixBatchOptions, LixBatchStatement, MergeBranchOptions, MergeBranchPreview, MergeBranchReceipt, ObserveEvent, OpenAnotherSessionOptions, LixOpenReport, ReplicaRecoverySource, ReplicaRecoveryExport, ReplicaRecoveryReceipt, SqlParam, ResultArrayRow, ResultObjectRow, ResultRow, SwitchBranchOptions, SwitchBranchReceipt, UndoReceipt } from "./types.js";
+import type { CreateBranchOptions, CreateBranchReceipt, RedoReceipt, ExecuteOptions, ExecuteResult, ExecuteBatchResult, CommitReceipt, StatementResult, LixBatchOptions, LixBatchStatement, MergeBranchOptions, MergeBranchPreview, MergeBranchReceipt, ObserveEvent, OpenAnotherSessionOptions, LixOpenReport, ReplicaRecoverySource, ReplicaRecoveryExport, ReplicaRecoveryReceipt, SqlParam, ResultArrayRow, ResultObjectRow, ResultRow, SwitchBranchOptions, SwitchBranchReceipt, UndoReceipt } from "./types.js";
 /** @internal Used by createLix without adding another method to Lix. */
 export declare function createHostedFromLix(lix: Lix, server: () => Promise<import("./binding-types.js").HostedServerBindingOptions>): Promise<import("./types.js").HostedLix>;
 export declare class Lix {
@@ -19,11 +19,11 @@ export declare class Lix {
     execute(sql: string, params: SqlParam[] | undefined, options?: ExecuteOptions): Promise<ExecuteResult<ResultRow>>;
     executeBatch(statements: readonly LixBatchStatement[], options: LixBatchOptions & {
         rowMode: "array";
-    }): Promise<readonly ExecuteBatchResult<ResultArrayRow>[]>;
+    }): Promise<ExecuteBatchResult<ResultArrayRow>>;
     executeBatch(statements: readonly LixBatchStatement[], options?: LixBatchOptions & {
         rowMode?: "object";
-    }): Promise<readonly ExecuteBatchResult<ResultObjectRow>[]>;
-    executeBatch(statements: readonly LixBatchStatement[], options?: LixBatchOptions): Promise<readonly ExecuteBatchResult<ResultRow>[]>;
+    }): Promise<ExecuteBatchResult<ResultObjectRow>>;
+    executeBatch(statements: readonly LixBatchStatement[], options?: LixBatchOptions): Promise<ExecuteBatchResult<ResultRow>>;
     observe(sql: string, params?: SqlParam[]): ObserveEvents;
     beginTransaction(): Promise<LixTransaction>;
     /** Lists preserved generations belonging to this local repository. */
@@ -32,12 +32,17 @@ export declare class Lix {
     exportReplicaRecovery(id: string): Promise<ReplicaRecoveryExport>;
     /** Restores supported rows onto separate recovery branches; preserves the source. */
     recoverReplica(id: string): Promise<ReplicaRecoveryReceipt>;
+    /** Explicitly hydrates retained-source recovery dependencies; does not start sync. */
+    recoverReplicaWithServer(id: string, server: import("./types.js").LixServerOptions): Promise<ReplicaRecoveryReceipt>;
+    /** Local worker health; independent of whether a warm SQL read succeeds. */
+    syncHealth(): Promise<import("./types.js").SyncHealth>;
     activeBranchId(): Promise<string>;
     activeAccountId(): Promise<string>;
     /** Subscribes to successful branch switches made through this Lix handle. */
     subscribeActiveBranch(listener: () => void): () => void;
     createBranch(options: CreateBranchOptions): Promise<CreateBranchReceipt>;
-    /** Streams a deterministic snapshot of the complete Lix. */
+    /** Streams this handle's state. Local partial replicas include their cached
+     * inputs and pending edits; remote handles export the complete authority. */
     exportSnapshot(): ReadableStream<Uint8Array>;
     undo(): Promise<UndoReceipt>;
     redo(): Promise<RedoReceipt>;
@@ -62,12 +67,12 @@ export declare class LixTransaction {
     constructor(binding: LixTransactionBinding, onFinish?: () => void);
     execute(sql: string, params: SqlParam[] | undefined, options: ExecuteOptions & {
         rowMode: "array";
-    }): Promise<ExecuteResult<ResultArrayRow>>;
+    }): Promise<StatementResult<ResultArrayRow>>;
     execute<TRow extends object = ResultObjectRow>(sql: string, params?: SqlParam[], options?: ExecuteOptions & {
         rowMode?: "object";
-    }): Promise<ExecuteResult<TRow>>;
-    execute(sql: string, params: SqlParam[] | undefined, options?: ExecuteOptions): Promise<ExecuteResult<ResultRow>>;
-    commit(): Promise<void>;
+    }): Promise<StatementResult<TRow>>;
+    execute(sql: string, params: SqlParam[] | undefined, options?: ExecuteOptions): Promise<StatementResult<ResultRow>>;
+    commit(): Promise<CommitReceipt>;
     rollback(): Promise<void>;
     private finish;
 }

package/dist/lix.js

@@ -1,3 +1,4 @@
+import { fetchTransport } from "./http-transport.js";
 import { invalidArgument } from "./errors.js";
 import { normalizeOptionals, wrapExecuteBatchResult, wrapExecuteResult, } from "./result.js";
 import { normalizeParam, toNativeValue } from "./value.js";
@@ -65,7 +66,10 @@ export class Lix {
         const { rowMode = "object", ...bindingOptions } = options ?? {};
         return this.#runOperation(async () => {
             const results = await this.binding.executeBatch(normalizedStatements, bindingOptions);
-            return results.map((result) => wrapExecuteBatchResult(result, rowMode));
+            return {
+                results: results.results.map((result) => wrapExecuteBatchResult(result, rowMode)),
+                commit: results.commit ?? null,
+            };
         });
     }
     observe(sql, params = []) {
@@ -107,6 +111,24 @@ export class Lix {
     async recoverReplica(id) {
         return this.#runOperation(() => this.binding.recoverReplica(id));
     }
+    /** Explicitly hydrates retained-source recovery dependencies; does not start sync. */
+    async recoverReplicaWithServer(id, server) {
+        const entries = (headers) => {
+            const result = [];
+            new Headers(headers).forEach((value, key) => result.push([key, value]));
+            return result;
+        };
+        return this.#runOperation(() => this.binding.recoverReplicaWithServer(id, {
+            url: new URL(server.url).toString(),
+            headers: typeof server.headers === "function" ? [] : entries(server.headers),
+            headerProvider: typeof server.headers === "function" ? async () => entries(await server.headers()) : undefined,
+            transport: server.fetch ? fetchTransport(server.fetch) : undefined,
+        }));
+    }
+    /** Local worker health; independent of whether a warm SQL read succeeds. */
+    async syncHealth() {
+        return this.binding.syncHealth();
+    }
     async activeBranchId() {
         return this.#runOperation(() => this.binding.activeBranchId());
     }
@@ -125,7 +147,8 @@ export class Lix {
     async createBranch(options) {
         return this.#runOperation(() => this.binding.createBranch(options));
     }
-    /** Streams a deterministic snapshot of the complete Lix. */
+    /** Streams this handle's state. Local partial replicas include their cached
+     * inputs and pending edits; remote handles export the complete authority. */
     exportSnapshot() {
         let snapshot;
         const start = () => {
@@ -353,13 +376,14 @@ export class LixTransaction {
             throw transactionClosedError();
         assertExecuteArgs("lixTransaction", sql, params, options);
         const { rowMode = "object", ...bindingOptions } = options ?? {};
-        return wrapExecuteResult(await this.binding.execute(sql, params.map((param, index) => toNativeValue(normalizeParam(param, index))), bindingOptions), rowMode);
+        const { commit: _commit, ...statement } = wrapExecuteResult(await this.binding.execute(sql, params.map((param, index) => toNativeValue(normalizeParam(param, index))), bindingOptions), rowMode);
+        return statement;
     }
     async commit() {
-        return this.finish("transaction.commit");
+        return (await this.finish("transaction.commit"));
     }
     async rollback() {
-        return this.finish("transaction.rollback");
+        await this.finish("transaction.rollback");
     }
     async finish(kind) {
         if (this.finished)
@@ -368,10 +392,11 @@ export class LixTransaction {
         // a concurrent rollback must never report a pending commit's success.
         this.finished = true;
         try {
-            if (kind === "transaction.commit")
-                await this.binding.commit();
-            else
-                await this.binding.rollback();
+            if (kind === "transaction.commit") {
+                const receipt = await this.binding.commit();
+                return { commit: receipt.commit ?? null };
+            }
+            await this.binding.rollback();
         }
         finally {
             // Keep the parent transaction lease until the binding settles. A
@@ -395,6 +420,11 @@ function assertExecuteArgs(receiver, sql, params, options) {
     if (!options || typeof options !== "object" || Array.isArray(options)) {
         throw invalidArgument("execute", "options", "object", typeof options, receiver);
     }
+    if (options.maxAutoCommitRetries !== undefined &&
+        (!Number.isInteger(options.maxAutoCommitRetries) ||
+            options.maxAutoCommitRetries < 0 || options.maxAutoCommitRetries > 0xffff_ffff)) {
+        throw invalidArgument("execute", "options.maxAutoCommitRetries", "integer between 0 and 4294967295", typeof options.maxAutoCommitRetries, receiver);
+    }
     if (options.originKey !== undefined &&
         typeof options.originKey !== "string") {
         throw invalidArgument("execute", "options.originKey", "string", typeof options.originKey, receiver);
@@ -460,6 +490,11 @@ function assertBatchOptions(options) {
     if (!options || typeof options !== "object" || Array.isArray(options)) {
         throw invalidArgument("executeBatch", "options", "object", typeof options);
     }
+    if (options.maxAutoCommitRetries !== undefined &&
+        (!Number.isInteger(options.maxAutoCommitRetries) ||
+            options.maxAutoCommitRetries < 0 || options.maxAutoCommitRetries > 0xffff_ffff)) {
+        throw invalidArgument("executeBatch", "options.maxAutoCommitRetries", "integer between 0 and 4294967295", typeof options.maxAutoCommitRetries);
+    }
     if (options.originKey !== undefined &&
         typeof options.originKey !== "string") {
         throw invalidArgument("executeBatch", "options.originKey", "string", typeof options.originKey);