@lix-js/sdk 0.16.0 → 0.17.0

package/README.md

@@ -22,16 +22,57 @@ console.log(result.rows[0]?.message);
 await lix.close();
 ```
 
+For compiled plugin downloads, installation, updates, and uninstalling, see
+[Installing and managing plugins](../../docs/plugins.md).
+
 ## Hosted lifecycle
 
-`openLix()` selects execution from the supplied locations:
+### Automatic upgrades and progress
+
+Opening a supported older hosted repository automatically upgrades it on the
+server. The SDK waits inside `openLix()`; applications do not implement migration
+or retry logic. Concurrent opens share the server's upgrade operation.
+
+Use `onProgress` to display status in either remote or partial-replica mode.
+Authority upgrades emit `scope: "authority"` and `phase: "migrating"`, followed
+by opening and completion. The source format and work totals may be unknown:
+show “Upgrading repository” with an indeterminate indicator instead of inventing
+a percentage. Progress callbacks are observational and cannot change the result
+of opening.
+
+### Compatibility metadata
+
+Raw HTTP integrations can obtain this SDK's protocol versions without loading
+the engine:
+
+```ts
+import { compatibility } from "@lix-js/sdk/compatibility";
+
+const headers = {
+  "Lix-Server-Protocol-Version": String(compatibility.serverProtocolVersion),
+  "Lix-Sync-Protocol-Version": String(compatibility.syncProtocolVersion),
+};
+```
+
+The object also includes `storageFormatVersion`. It is generated from the Rust
+engine constants during the SDK build. Source-checkout CI can use
+`node scripts/compatibility.mjs` before building the SDK.
+
+### Execution modes
+
+`openLix()` selects execution from storage and the explicit server mode:
 
 | Options | Behavior |
 | --- | --- |
 | Neither | Fresh in-memory repository |
 | `storage` | Local repository, initialized if empty |
-| `server` | Execute against an existing hosted repository |
-| `storage` and `server` | Synchronized local reads; mutations execute on the server |
+| `server`, mode omitted or `"remote"` | Execute SQL remotely against an existing hosted repository; no local storage |
+| `storage` and `server.mode: "partial_replica"` | Partial replica with on-demand sync; reads and writes whose dependencies are resident execute locally |
+
+`server.mode` defaults to `"remote"`. Supplying storage requires explicitly opting
+into `"partial_replica"`; remote mode rejects storage. Partial-replica mode requires
+storage. These are the only supported server modes. `"replica"` may be added later;
+the former `"sync"` mode is not an alias.
 
 Creation and deletion are explicit server operations:
 
@@ -64,9 +105,10 @@ execution do not require streaming uploads.
 
 ## Synchronized local repositories
 
-Combine storage with a server to keep a synchronized local read replica.
-Certified current-state reads can execute locally; mutations execute on the
-server:
+Provide storage and set `server.mode: "partial_replica"` to create a
+**partial replica with on-demand sync**. Opening loads bounded metadata. SQL fetches missing native inputs on
+demand and retains them locally; background synchronization updates the loaded
+working set:
 
 ```ts
 import { openLix } from "@lix-js/sdk";
@@ -75,6 +117,7 @@ import { OpfsStorage } from "@lix-js/storage-opfs";
 const lix = await openLix({
   storage: new OpfsStorage({ name: "acme" }),
   server: {
+    mode: "partial_replica",
     url: "https://example.com/lix/01936f4e-7b6c-7c3d-8f9a-123456789abc",
     headers: async () => ({
       Authorization: `Bearer ${await accessToken()}`,
@@ -83,12 +126,121 @@ const lix = await openLix({
 });
 ```
 
-A successful mutation confirms server acceptance. The local replica receives
-the resulting certified state automatically; older history and binary content
-load when needed. Connected mutations require the server, and cached reads may
-also need fresh server certification.
+A successful mutation confirms a local commit; it does not confirm server
+acceptance. Pending commits upload in the background. Covered reads and writes
+whose dependencies are resident work offline, with immediate local visibility.
+A statement requiring missing inputs needs a connection; missing data is never
+silently treated as an empty result. Current data means the coherently applied
+server state plus pending local writes.
+
+Prefetch a view on hover using the same ordinary SELECT it will display:
+
+```ts
+const sql = "SELECT content FROM lix_file WHERE path=$1";
+const params = ["/notes.txt"];
+await lix.execute(sql, params); // On hover: fetch missing read inputs.
+const result = await lix.execute(sql, params); // On open: resident reads stay local.
+```
+
+Use ordinary `execute()` for mutations. Reading a file does not promise that every
+later write's validation or commit dependencies are resident; cold operations can
+fetch additional inputs while connected.
+
 See [Collaboration and Sync](https://lix.dev/docs/collaboration-and-sync).
 
+### Upgrading a local replica
+
+Keep the same storage name across SDK upgrades. Opening an existing full replica
+with `server.mode: "partial_replica"` requires an explicit conversion; normal opening does not download a
+replacement repository. Run conversion while the storage has no open Lix handle:
+
+```ts
+import { convertReplicaToPartial, openLix } from "@lix-js/sdk";
+
+const storage = new OpfsStorage({ name: "acme" });
+const server = {
+  mode: "partial_replica" as const,
+  url: "https://example.com/lix/01936f4e-7b6c-7c3d-8f9a-123456789abc",
+  headers: async () => ({ Authorization: `Bearer ${await accessToken()}` }),
+};
+await convertReplicaToPartial({ storage, server });
+const lix = await openLix({ storage, server });
+```
+
+Conversion authenticates the repository and account, preserves the original
+storage generation, and publishes a separate partial replica only after its
+required reconciliation and validation succeed. It can require time and extra
+storage; measure it separately from ordinary opening. Unsupported pending work
+returns an error with the original source preserved. Do not clear storage to
+bypass that error.
+
+If authority cleanup is interrupted after conversion, retry it explicitly while
+storage is closed. Ordinary opening does not scan migration journals:
+
+```ts
+import { retryReplicaMigrationCleanup } from "@lix-js/sdk";
+const completed = await retryReplicaMigrationCleanup({ storage, server });
+```
+
+This returns the number of newly completed cleanup records; repeating a
+successful cleanup returns zero. It preserves the active replica and retained
+source generation.
+
+For retained pre-native sources, explicit format migration can succeed while
+partial conversion reports that recovery is required. Open the resulting local
+recovery repository without `server`, then inspect and restore retained work:
+
+```ts
+const recovery = await openLix({ storage });
+try {
+  const sources = await recovery.replicaRecoverySources();
+  for (const source of sources.filter((source) => source.recoveryRequired)) {
+    const exported = await recovery.exportReplicaRecovery(source.id);
+    console.log(exported.unresolved); // Save a portable copy when needed.
+
+    const receipt = await recovery.recoverReplicaWithServer(source.id, server);
+    console.log(receipt.branchIds, receipt.restoredRows, receipt.unresolved);
+  }
+} finally {
+  await recovery.close();
+}
+```
+
+`recoverReplicaWithServer()` authenticates the same repository and account and
+fetches missing recovery history or chunks explicitly. It does not start a
+background sync worker or upload restored branches. Dynamic headers and custom
+fetch remain scoped to this operation in the browser. The native Node binding
+supports headers and rejects custom fetch.
+
+`exportReplicaRecovery()` captures available logical rows, blob contents, and
+original branch/checkpoint coordinates. `recoverReplica()` performs local
+restoration; its server variant can hydrate missing dependencies. Both restore
+supported tracked rows into separate recovery branches without inheriting
+unrelated active-branch rows. Inspect `unresolved`: unavailable history/content
+and local-only rows remain in the retained source. Neither operation deletes
+that source, and retries reuse durable recovery receipts.
+
+A recovery receipt confirms local restoration, not server acceptance or
+eligibility for partial conversion. Conversion of every retained pending branch
+is still a release gate: restored additional branches and unresolved retained
+sources must not be silently discarded or marked acknowledged. The current
+selected-branch native reconciliation path does not establish that broader
+migration guarantee.
+
+Recovery export currently allows up to 100,000 logical rows across all branches,
+64 MiB per blob, and 128 MiB of blob content in total. Unfinished upload parts
+have a separate 128 MiB content budget. A row-limit or upload-limit error leaves
+the source intact; omitted blob content is identified in `unresolved`. Exported
+JSON can be larger than these content budgets because binary data uses base64.
+This recovery file is not a complete repository backup.
+
+These methods require a local storage-backed handle; remote-only handles reject
+with `LIX_ERROR_LOCAL_STORAGE_REQUIRED`. Do not clear browser storage to resolve
+upgrade or recovery errors. Browser storage eviction or an unsupported old format
+can still require external recovery; retaining bytes alone is not proof that all
+work has been recovered. Standalone and authoritative repositories continue to
+use history-preserving format migrations.
+
 ## Remote repositories
 
 Use the same Lix client as a thin client against a hosted repository:
@@ -116,7 +268,8 @@ files.close();
 await lix.close();
 ```
 
-Without `storage`, remote mode uses the server for all persistence and does not
+Remote mode is the default when `server.mode` is omitted. It rejects `storage`,
+uses the server for all persistence and does not
 open a local engine. Dynamic headers are resolved for every request and
 observation reconnect. An injected `fetch` can route requests through a service
 binding or another authorized server-side transport.
@@ -243,18 +396,30 @@ try {
 - The package is ESM-only.
 - The package uses conditional ESM imports internally: Node.js resolves the
   native N-API binding, while browsers and other runtimes resolve the portable
-  WebAssembly binding. Vite follows this split without consumer configuration.
+  WebAssembly binding. Vite resolves these conditional imports automatically.
+  Configure Vite to emit ES module workers because the Component compiler uses
+  top-level await:
+
+  ```js
+  // vite.config.js
+  export default { worker: { format: "es" } };
+  ```
 - If the native addon cannot load in Node.js, in-memory Lix instances fall back
-  to the bundled WebAssembly engine. Filesystem storage and Component API v1
-  plugin execution still require the native addon.
+  to the bundled WebAssembly engine. Filesystem storage still requires the native addon.
 - Every browser `openLix()` owns one dedicated worker, so database work does
   not block the page's main thread. Node.js uses the native binding's actor.
-- Node.js executes installed Component API v1 plugins with the Rust SDK's
-  Wasmtime runtime. The browser binding currently opens without a component
-  runtime: it can use ordinary Lix storage and SQL, but does not
-  execute installed plugins. A browser Component host is a separate follow-up.
+- Node.js and browsers execute installed Component API v2 plugins through the
+  same JavaScript Component host. The host adapts Component interfaces to the
+  platform's built-in WebAssembly runtime and connects them to Lix's shared Rust
+  host resources. Node.js retains its native engine and filesystem adapter;
+  the browser engine runs inside its dedicated worker.
+- Components are compiled on first use. Each file actor gets an isolated guest
+  instance. Guest functions and loops check execution deadlines, and core memory
+  declarations are capped before instantiation. Unsupported memory forms are
+  rejected rather than executed without limits.
 - A page Content Security Policy only needs to permit the package's same-origin
-  worker. WebAssembly compilation happens inside that worker, so the required
+  worker. Component bindings are generated as data URL modules and WebAssembly
+  compilation happens inside that worker, so the required
   permission can be scoped to the worker script's HTTP response instead of
   being allowed by the document:
 
@@ -263,11 +428,11 @@ try {
   Content-Security-Policy: default-src 'self'; script-src 'self'; worker-src 'self'
 
   # Lix worker response (Vite emits assets/entry.browser-<hash>.js)
-  Content-Security-Policy: default-src 'none'; script-src 'self' 'wasm-unsafe-eval'; connect-src 'self'
+  Content-Security-Policy: default-src 'none'; script-src 'self' data: 'wasm-unsafe-eval'; connect-src 'self'
   ```
 
   Hosts that apply one policy to every response can use
-  `script-src 'self' 'wasm-unsafe-eval'; worker-src 'self'` globally
+  `script-src 'self' data: 'wasm-unsafe-eval'; worker-src 'self'` globally
   instead. Worker-scoped headers keep those permissions out of the page.
 
 - SQL parameters use normal JavaScript values: `string`, finite `number`, `boolean`, `Uint8Array`, `null`, JSON-compatible arrays, and JSON-compatible plain objects.
@@ -287,7 +452,7 @@ npm run test:browser
 
 `npm run test:browser:production` additionally packs the SDK, installs the
 tarball into a minimal Vite app, makes a production build, and exercises SQL
-plus bundled-plugin archive loading in Chromium. It runs with both
+plus bundled-plugin installation and CSV row extraction in Chromium. It runs with both
 worker-scoped and global strict CSP headers.
 
 Use `npm run build:wasm:dev` while iterating on the Rust bridge when release

package/dist/binding-types.d.ts

@@ -1,11 +1,12 @@
-import type { CreateBranchOptions, CreateBranchReceipt, UndoReceipt, RedoReceipt, ExecuteOptions, LixBatchOptions, MergeBranchOptions, MergeBranchPreview, MergeBranchReceipt, SwitchBranchOptions, SwitchBranchReceipt, LixTelemetrySpan, LixTelemetryParentContext, LixOpenProgress, LixOpenReport, OpenAnotherSessionOptions, ResultColumn } from "./types.js";
+import type { HttpTransport } from "./http-transport.js";
+import type { CommitSpan, CreateBranchOptions, CreateBranchReceipt, UndoReceipt, RedoReceipt, ExecuteOptions, LixBatchOptions, MergeBranchOptions, MergeBranchPreview, MergeBranchReceipt, SwitchBranchOptions, SwitchBranchReceipt, LixTelemetrySpan, LixTelemetryParentContext, LixOpenProgress, LixOpenReport, ReplicaRecoverySource, ReplicaRecoveryExport, ReplicaRecoveryReceipt, OpenAnotherSessionOptions, ResultColumn } from "./types.js";
 import type { NativeLixValue } from "./value.js";
 import type { LixStorageProvider } from "./storage-adapter.js";
 export type SyncServerBindingOptions = {
     url: string;
     headers: [string, string][];
     headerProvider?: () => Promise<[string, string][]>;
-    fetch?: typeof fetch;
+    transport?: HttpTransport;
 };
 export type BindingExecuteResult = {
     statementIndex?: number;
@@ -18,6 +19,7 @@ export type BindingExecuteResult = {
         message: string;
         hint?: string;
     }>;
+    commit?: CommitSpan;
 };
 export type BindingObserveEvent = {
     sequence: number;
@@ -44,11 +46,19 @@ export type LixBinding = {
     createHosted?(server: HostedServerBindingOptions): Promise<import("./types.js").HostedLix>;
     openReport?(): LixOpenReport | undefined;
     setTelemetryParent(parent?: TelemetryParentContext): void;
-    openAnotherSession(options: OpenAnotherSessionOptions): Promise<LixBinding>;
+    openAnotherSession(options: OpenAnotherSessionOptions, telemetry?: TelemetryDispatch): Promise<LixBinding>;
     execute(sql: string, params: BindingParam[], options?: ExecuteOptions): Promise<BindingExecuteResult>;
-    executeBatch(statements: BindingBatchStatement[], options?: LixBatchOptions): Promise<BindingExecuteResult[]>;
+    executeBatch(statements: BindingBatchStatement[], options?: LixBatchOptions): Promise<{
+        results: BindingExecuteResult[];
+        commit?: CommitSpan | null;
+    }>;
     observe(sql: string, params: BindingParam[]): Promise<ObserveEventsBinding>;
     beginTransaction(): Promise<LixTransactionBinding>;
+    replicaRecoverySources(): Promise<ReplicaRecoverySource[]>;
+    exportReplicaRecovery(id: string): Promise<ReplicaRecoveryExport>;
+    recoverReplica(id: string): Promise<ReplicaRecoveryReceipt>;
+    recoverReplicaWithServer(id: string, server: SyncServerBindingOptions): Promise<ReplicaRecoveryReceipt>;
+    syncHealth(): Promise<import("./types.js").SyncHealth>;
     activeBranchId(): Promise<string>;
     activeAccountId(): Promise<string>;
     createBranch(options: CreateBranchOptions): Promise<CreateBranchReceipt>;
@@ -64,7 +74,9 @@ export type LixBinding = {
 };
 export type LixTransactionBinding = {
     execute(sql: string, params: BindingParam[], options?: ExecuteOptions): Promise<BindingExecuteResult>;
-    commit(): Promise<void>;
+    commit(): Promise<{
+        commit?: CommitSpan | null;
+    }>;
     rollback(): Promise<void>;
 };
 export type ObserveEventsBinding = {
@@ -79,6 +91,8 @@ export type LixStorageProviderModule = {
     createLixStorageProvider(options: unknown): Promise<LixStorageProvider>;
 };
 export type LixStorageConfig = {
+    durability?: import("./types.js").Durability;
+} & ({
     kind: "memory";
 } | {
     kind: "jsStorage";
@@ -88,7 +102,7 @@ export type LixStorageConfig = {
     kind: "filesystem";
     path: string;
     syncAllFiles: boolean;
-};
+});
 export type HostedServerBindingOptions = {
     idempotencyKey?: string;
     url: string;

package/dist/binding.browser.d.ts

@@ -2,3 +2,5 @@ import type { LixStorageConfig, LixBinding, SyncServerBindingOptions, TelemetryD
 export declare function openLixBinding(storage: LixStorageConfig, telemetry?: TelemetryDispatch, telemetryParent?: TelemetryParentContext, server?: SyncServerBindingOptions, openProgress?: OpenProgressDispatch, snapshot?: ReadableStream<Uint8Array>): Promise<LixBinding>;
 export declare function createHostedBinding(server: import("./binding-types.js").HostedServerBindingOptions): Promise<import("./types.js").HostedLix>;
 export declare function deleteHostedBinding(server: import("./binding-types.js").HostedServerBindingOptions): Promise<void>;
+export declare function convertReplicaBinding(storage: LixStorageConfig, server: SyncServerBindingOptions, branchId?: string): Promise<void>;
+export declare function retryReplicaMigrationCleanupBinding(storage: LixStorageConfig, server: SyncServerBindingOptions): Promise<number>;

package/dist/binding.browser.js

@@ -1,3 +1,4 @@
+import { createComponentDispatch } from "./component-host/dispatch.js";
 import { initializeWasm } from "./wasm-init.js";
 import { restoreSnapshot } from "./snapshot-restore.js";
 // Generated before TypeScript compilation and emitted beside this module.
@@ -7,11 +8,12 @@ import { createHosted, deleteHosted, openJsStorage, openJsStorageFromSnapshot, o
  } from "./wasm/lix_js_sdk.js";
 export async function openLixBinding(storage, telemetry, telemetryParent, server, openProgress, snapshot) {
     await initializeWasm();
+    const componentDispatch = createComponentDispatch();
     switch (storage.kind) {
         case "memory":
             return (snapshot
-                ? restoreSnapshot(snapshot, openMemoryFromSnapshot(telemetry, telemetryParent, openProgress))
-                : openMemory(telemetry, telemetryParent, server, openProgress));
+                ? restoreSnapshot(snapshot, openMemoryFromSnapshot(telemetry, telemetryParent, openProgress, componentDispatch, storage.durability))
+                : openMemory(telemetry, telemetryParent, server, openProgress, componentDispatch, storage.durability));
         case "jsStorage": {
             const module = (await import(
             /* @vite-ignore */ storage.moduleUrl));
@@ -21,8 +23,8 @@ export async function openLixBinding(storage, telemetry, telemetryParent, server
             const provider = await module.createLixStorageProvider(storage.options);
             try {
                 const binding = (await (snapshot
-                    ? restoreSnapshot(snapshot, openJsStorageFromSnapshot(provider, telemetry, telemetryParent, openProgress))
-                    : openJsStorage(provider, telemetry, telemetryParent, server, openProgress)));
+                    ? restoreSnapshot(snapshot, openJsStorageFromSnapshot(provider, telemetry, telemetryParent, openProgress, componentDispatch, storage.durability))
+                    : openJsStorage(provider, telemetry, telemetryParent, server, openProgress, componentDispatch, storage.durability)));
                 return binding;
             }
             catch (error) {
@@ -42,3 +44,11 @@ export async function deleteHostedBinding(server) {
     await initializeWasm();
     await deleteHosted(server);
 }
+export async function convertReplicaBinding(storage, server, branchId) {
+    const migration = await import("./migration-binding.browser.js");
+    return migration.convertReplicaBinding(storage, server, branchId);
+}
+export async function retryReplicaMigrationCleanupBinding(storage, server) {
+    const migration = await import("./migration-binding.browser.js");
+    return migration.retryReplicaMigrationCleanupBinding(storage, server);
+}

package/dist/binding.node-wasm.d.ts

@@ -1,2 +1,2 @@
 import type { LixBinding, TelemetryDispatch, TelemetryParentContext, OpenProgressDispatch } from "./binding-types.js";
-export declare function openMemoryWasmBinding(telemetry?: TelemetryDispatch, telemetryParent?: TelemetryParentContext, openProgress?: OpenProgressDispatch, snapshot?: ReadableStream<Uint8Array>): Promise<LixBinding>;
+export declare function openMemoryWasmBinding(telemetry?: TelemetryDispatch, telemetryParent?: TelemetryParentContext, openProgress?: OpenProgressDispatch, snapshot?: ReadableStream<Uint8Array>, durability?: import("./types.js").Durability): Promise<LixBinding>;

package/dist/binding.node-wasm.js

@@ -1,12 +1,14 @@
+import { createComponentDispatch } from "./component-host/dispatch.js";
 import { restoreSnapshot } from "./snapshot-restore.js";
 import { initializeWasm } from "./wasm-init.js";
 // Generated before TypeScript compilation and emitted beside this module.
 // @ts-ignore Generated by build:wasm and absent in source-only checks.
 import { openMemory, openMemoryFromSnapshot } from "./wasm/lix_js_sdk.js";
-export async function openMemoryWasmBinding(telemetry, telemetryParent, openProgress, snapshot) {
+export async function openMemoryWasmBinding(telemetry, telemetryParent, openProgress, snapshot, durability) {
     await initializeWasm();
+    const componentDispatch = createComponentDispatch();
     if (snapshot) {
-        return restoreSnapshot(snapshot, openMemoryFromSnapshot(telemetry, telemetryParent, openProgress));
+        return restoreSnapshot(snapshot, openMemoryFromSnapshot(telemetry, telemetryParent, openProgress, componentDispatch, durability));
     }
-    return openMemory(telemetry, telemetryParent, undefined, openProgress);
+    return openMemory(telemetry, telemetryParent, undefined, openProgress, componentDispatch, durability);
 }

package/dist/binding.node.d.ts

@@ -3,3 +3,5 @@ export declare function openLixBinding(storage: LixStorageConfig, telemetry?: Te
 export declare function openNativeLixBinding(storage: LixStorageConfig, telemetry?: TelemetryDispatch, telemetryParent?: TelemetryParentContext, server?: SyncServerBindingOptions, openProgress?: OpenProgressDispatch, snapshot?: ReadableStream<Uint8Array>): Promise<LixBinding>;
 export declare function createHostedBinding(server: import("./binding-types.js").HostedServerBindingOptions): Promise<import("./types.js").HostedLix>;
 export declare function deleteHostedBinding(server: import("./binding-types.js").HostedServerBindingOptions): Promise<void>;
+export declare function convertReplicaBinding(storage: LixStorageConfig, server: SyncServerBindingOptions, branchId?: string): Promise<void>;
+export declare function retryReplicaMigrationCleanupBinding(storage: LixStorageConfig, server: SyncServerBindingOptions): Promise<number>;

package/dist/binding.node.js

@@ -1,3 +1,4 @@
+import { createComponentDispatch } from "./component-host/dispatch.js";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
@@ -19,6 +20,14 @@ function normalizeNativeBinding(binding) {
             if (property === "setTelemetryParent") {
                 return (parent) => target.setTelemetryParent(parent === undefined ? undefined : JSON.stringify(parent));
             }
+            if (property === "recoverReplicaWithServer") {
+                return async (id, server) => {
+                    if (server.transport)
+                        throw new Error("Custom fetch is unsupported for native recovery");
+                    const headers = server.headerProvider ? await server.headerProvider() : server.headers;
+                    return target.recoverReplicaWithServer(id, server.url, headers);
+                };
+            }
             if (property === "observe") {
                 return async (sql, params) => normalizeNativeObserveEvents(await target.observe(sql, params));
             }
@@ -91,7 +100,7 @@ export async function openLixBinding(storage, telemetry, telemetryParent, server
         }
         try {
             const { openMemoryWasmBinding } = await import("./binding.node-wasm.js");
-            return await openMemoryWasmBinding(telemetry, telemetryParent, openProgress, snapshot);
+            return await openMemoryWasmBinding(telemetry, telemetryParent, openProgress, snapshot, storage.durability);
         }
         catch (wasmError) {
             throw new AggregateError([nativeError, wasmError], "Failed to open in-memory Lix with either the native or WebAssembly binding.");
@@ -99,7 +108,7 @@ export async function openLixBinding(storage, telemetry, telemetryParent, server
     }
 }
 export async function openNativeLixBinding(storage, telemetry, telemetryParent, server, openProgress, snapshot) {
-    if (server?.fetch) {
+    if (server?.transport) {
         throw new TypeError("Custom sync fetch is only supported by the browser worker");
     }
     const nativeOpenProgress = openProgress
@@ -112,6 +121,7 @@ export async function openNativeLixBinding(storage, telemetry, telemetryParent,
             }
         }
         : undefined;
+    const componentDispatch = createComponentDispatch();
     switch (storage.kind) {
         case "memory": {
             const nativeAddon = loadAddon();
@@ -119,13 +129,13 @@ export async function openNativeLixBinding(storage, telemetry, telemetryParent,
                 ? (spanJson) => telemetry(JSON.parse(spanJson))
                 : undefined;
             if (snapshot) {
-                const restore = nativeAddon.Lix.openMemoryFromSnapshot(nativeTelemetry, telemetryParent ? JSON.stringify(telemetryParent) : undefined, nativeOpenProgress);
+                const restore = nativeAddon.Lix.openMemoryFromSnapshot(nativeTelemetry, telemetryParent ? JSON.stringify(telemetryParent) : undefined, nativeOpenProgress, componentDispatch, storage.durability);
                 return normalizeNativeBinding(await restoreSnapshot(snapshot, restore));
             }
             if (nativeTelemetry) {
-                return normalizeNativeBinding(await nativeAddon.Lix.openMemory(nativeTelemetry, telemetryParent ? JSON.stringify(telemetryParent) : undefined, server?.url, server?.headers, nativeOpenProgress));
+                return normalizeNativeBinding(await nativeAddon.Lix.openMemory(nativeTelemetry, telemetryParent ? JSON.stringify(telemetryParent) : undefined, server?.url, server?.headers, nativeOpenProgress, componentDispatch, storage.durability));
             }
-            return normalizeNativeBinding(await nativeAddon.Lix.openMemory(undefined, undefined, server?.url, server?.headers, nativeOpenProgress));
+            return normalizeNativeBinding(await nativeAddon.Lix.openMemory(undefined, undefined, server?.url, server?.headers, nativeOpenProgress, componentDispatch, storage.durability));
         }
         case "jsStorage":
             throw new Error("JavaScript storage providers are only available in browsers");
@@ -135,13 +145,13 @@ export async function openNativeLixBinding(storage, telemetry, telemetryParent,
                 ? (spanJson) => telemetry(JSON.parse(spanJson))
                 : undefined;
             if (snapshot) {
-                const restore = nativeAddon.Lix.openFilesystemStorageFromSnapshot(storage.path, storage.syncAllFiles, nativeTelemetry, telemetryParent ? JSON.stringify(telemetryParent) : undefined, nativeOpenProgress);
+                const restore = nativeAddon.Lix.openFilesystemStorageFromSnapshot(storage.path, storage.syncAllFiles, nativeTelemetry, telemetryParent ? JSON.stringify(telemetryParent) : undefined, nativeOpenProgress, componentDispatch, storage.durability);
                 return normalizeNativeBinding(await restoreSnapshot(snapshot, restore));
             }
             if (nativeTelemetry) {
-                return normalizeNativeBinding(await nativeAddon.Lix.openFilesystemStorage(storage.path, storage.syncAllFiles, nativeTelemetry, telemetryParent ? JSON.stringify(telemetryParent) : undefined, server?.url, server?.headers, nativeOpenProgress));
+                return normalizeNativeBinding(await nativeAddon.Lix.openFilesystemStorage(storage.path, storage.syncAllFiles, nativeTelemetry, telemetryParent ? JSON.stringify(telemetryParent) : undefined, server?.url, server?.headers, nativeOpenProgress, componentDispatch, storage.durability));
             }
-            return normalizeNativeBinding(await nativeAddon.Lix.openFilesystemStorage(storage.path, storage.syncAllFiles, undefined, undefined, server?.url, server?.headers, nativeOpenProgress));
+            return normalizeNativeBinding(await nativeAddon.Lix.openFilesystemStorage(storage.path, storage.syncAllFiles, undefined, undefined, server?.url, server?.headers, nativeOpenProgress, componentDispatch, storage.durability));
         }
     }
 }
@@ -151,3 +161,19 @@ export async function createHostedBinding(server) {
 export async function deleteHostedBinding(server) {
     await loadAddon().deleteHosted(server.url, server.headers);
 }
+export async function convertReplicaBinding(storage, server, branchId) {
+    if (storage.kind !== "filesystem")
+        throw new TypeError("Node conversion requires FilesystemStorage");
+    if (server.transport)
+        throw new TypeError("Custom sync fetch is only supported in browsers");
+    const headers = server.headerProvider ? await server.headerProvider() : server.headers;
+    await (await import("./migration-binding.node.js")).loadMigrationAddon().convertFilesystemReplicaToPartial(storage.path, storage.syncAllFiles, server.url, headers, branchId);
+}
+export async function retryReplicaMigrationCleanupBinding(storage, server) {
+    if (storage.kind !== "filesystem")
+        throw new TypeError("Node migration cleanup requires FilesystemStorage");
+    if (server.transport)
+        throw new TypeError("Custom sync fetch is only supported in browsers");
+    const headers = server.headerProvider ? await server.headerProvider() : server.headers;
+    return (await import("./migration-binding.node.js")).loadMigrationAddon().retryFilesystemReplicaMigrationCleanup(storage.path, storage.syncAllFiles, server.url, headers);
+}

package/dist/compatibility.d.ts

@@ -0,0 +1,6 @@
+/** Compatibility versions of the engine shipped with this SDK. */
+export declare const compatibility: Readonly<{
+  serverProtocolVersion: number;
+  syncProtocolVersion: number;
+  storageFormatVersion: number;
+}>;

package/dist/compatibility.js

@@ -0,0 +1,6 @@
+// Generated from the canonical Rust engine constants. No binding is loaded.
+export const compatibility = Object.freeze({
+  "serverProtocolVersion": 11,
+  "syncProtocolVersion": 17,
+  "storageFormatVersion": 81
+});

package/dist/component-host/dispatch.d.ts

@@ -0,0 +1,12 @@
+export type ComponentRequest = {
+    operation: string;
+    data: string;
+    bytes?: Uint8Array;
+    host?: {
+        call(method: string, argumentsJson: string): string;
+        free?(): void;
+    };
+};
+export type ComponentDispatch = (request: ComponentRequest) => Promise<string>;
+/** One isolated handle registry per engine runtime, shared by Node and browsers. */
+export declare function createComponentDispatch(): (request: ComponentRequest) => Promise<string>;