@lix-js/sdk 0.16.0 → 0.16.1

package/README.md

@@ -31,7 +31,7 @@ await lix.close();
 | 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 |
+| `storage` and `server` | Local reads and writes with background synchronization |
 
 Creation and deletion are explicit server operations:
 
@@ -64,8 +64,8 @@ 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
+Combine storage with a server to keep a synchronized local replica. Reads and
+writes execute locally; background synchronization exchanges changes with the
 server:
 
 ```ts
@@ -83,12 +83,59 @@ 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. Cached reads and local
+writes work offline; older history and binary content load when needed.
 See [Collaboration and Sync](https://lix.dev/docs/collaboration-and-sync).
 
+### Upgrading a local replica
+
+Keep the same storage name across SDK upgrades. For a supported older synchronized
+replica, Lix preserves its existing storage generation and bootstraps a separate
+generation from the same authoritative repository and account. The replacement
+becomes active only after bootstrap and validation succeed. Pending work and
+local-only rows remain in the preserved generation; they do not block opening the
+current server state. An upgrade requires a server connection and enough local
+storage for both generations.
+
+Recovery is explicit and separate from opening:
+
+```ts
+const sources = await lix.replicaRecoverySources();
+for (const source of sources.filter((source) => source.recoveryRequired)) {
+  const exported = await lix.exportReplicaRecovery(source.id);
+  // Save exported as JSON when the user requests a portable recovery copy.
+  console.log(exported.unresolved);
+
+  const receipt = await lix.recoverReplica(source.id);
+  // Present these separate branches for review; the active branch is unchanged.
+  console.log(receipt.branchIds, receipt.restoredRows, receipt.unresolved);
+}
+```
+
+`exportReplicaRecovery()` captures available logical rows, blob contents, and
+original branch/checkpoint coordinates. `recoverReplica()` restores supported
+tracked rows into separate recovery branches. It does not automatically publish
+local-only rows or merge recovered work into the active branch. Inspect
+`unresolved`: original history and any unavailable content remain in the retained
+source. A recovery receipt describes local restoration, not a server durability
+acknowledgement. Neither operation deletes the retained generation, and retries
+reuse recovery branch receipts rather than overwriting previously recovered work.
+
+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:

package/dist/binding-types.d.ts

@@ -1,4 +1,4 @@
-import type { CreateBranchOptions, CreateBranchReceipt, UndoReceipt, RedoReceipt, ExecuteOptions, LixBatchOptions, MergeBranchOptions, MergeBranchPreview, MergeBranchReceipt, SwitchBranchOptions, SwitchBranchReceipt, LixTelemetrySpan, LixTelemetryParentContext, LixOpenProgress, LixOpenReport, OpenAnotherSessionOptions, ResultColumn } from "./types.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 = {
@@ -18,6 +18,7 @@ export type BindingExecuteResult = {
         message: string;
         hint?: string;
     }>;
+    commit?: CommitSpan;
 };
 export type BindingObserveEvent = {
     sequence: number;
@@ -49,6 +50,9 @@ export type LixBinding = {
     executeBatch(statements: BindingBatchStatement[], options?: LixBatchOptions): Promise<BindingExecuteResult[]>;
     observe(sql: string, params: BindingParam[]): Promise<ObserveEventsBinding>;
     beginTransaction(): Promise<LixTransactionBinding>;
+    replicaRecoverySources(): Promise<ReplicaRecoverySource[]>;
+    exportReplicaRecovery(id: string): Promise<ReplicaRecoveryExport>;
+    recoverReplica(id: string): Promise<ReplicaRecoveryReceipt>;
     activeBranchId(): Promise<string>;
     activeAccountId(): Promise<string>;
     createBranch(options: CreateBranchOptions): Promise<CreateBranchReceipt>;

package/dist/index.d.ts

@@ -3,5 +3,5 @@ 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, 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, RemoteLixFetch, LixServerOptions, HostedLix, CreateLixOptions, DeleteLixOptions, UndoReceipt, SqlParam, SwitchBranchOptions, SwitchBranchReceipt, } from "./types.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 { createLix, deleteLix } from "./hosted-lix.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, SqlParam, ResultArrayRow, ResultObjectRow, ResultRow, SwitchBranchOptions, SwitchBranchReceipt, UndoReceipt } from "./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";
 /** @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 {
@@ -26,6 +26,12 @@ export declare class Lix {
     executeBatch(statements: readonly LixBatchStatement[], options?: LixBatchOptions): Promise<readonly ExecuteBatchResult<ResultRow>[]>;
     observe(sql: string, params?: SqlParam[]): ObserveEvents;
     beginTransaction(): Promise<LixTransaction>;
+    /** Lists preserved generations belonging to this local repository. */
+    replicaRecoverySources(): Promise<ReplicaRecoverySource[]>;
+    /** Exports retained work without deleting or changing its source. */
+    exportReplicaRecovery(id: string): Promise<ReplicaRecoveryExport>;
+    /** Restores supported rows onto separate recovery branches; preserves the source. */
+    recoverReplica(id: string): Promise<ReplicaRecoveryReceipt>;
     activeBranchId(): Promise<string>;
     activeAccountId(): Promise<string>;
     /** Subscribes to successful branch switches made through this Lix handle. */
@@ -52,7 +58,6 @@ export declare class ObserveEvents {
 export declare class LixTransaction {
     private readonly binding;
     private readonly onFinish;
-    private finishPromise;
     private finished;
     constructor(binding: LixTransactionBinding, onFinish?: () => void);
     execute(sql: string, params: SqlParam[] | undefined, options: ExecuteOptions & {

package/dist/lix.js

@@ -95,6 +95,18 @@ export class Lix {
             }
         });
     }
+    /** Lists preserved generations belonging to this local repository. */
+    async replicaRecoverySources() {
+        return this.#runOperation(() => this.binding.replicaRecoverySources());
+    }
+    /** Exports retained work without deleting or changing its source. */
+    async exportReplicaRecovery(id) {
+        return this.#runOperation(() => this.binding.exportReplicaRecovery(id));
+    }
+    /** Restores supported rows onto separate recovery branches; preserves the source. */
+    async recoverReplica(id) {
+        return this.#runOperation(() => this.binding.recoverReplica(id));
+    }
     async activeBranchId() {
         return this.#runOperation(() => this.binding.activeBranchId());
     }
@@ -330,7 +342,6 @@ export class ObserveEvents {
 export class LixTransaction {
     binding;
     onFinish;
-    finishPromise;
     finished = false;
     constructor(binding, onFinish = () => undefined) {
         this.binding = binding;
@@ -338,6 +349,8 @@ export class LixTransaction {
         transactionFinalizer.register(this, { transaction: binding, onFinish: this.onFinish }, this);
     }
     async execute(sql, params = [], options) {
+        if (this.finished)
+            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);
@@ -351,24 +364,21 @@ export class LixTransaction {
     async finish(kind) {
         if (this.finished)
             throw transactionClosedError();
-        if (!this.finishPromise) {
-            this.finishPromise = (async () => {
-                try {
-                    if (kind === "transaction.commit")
-                        await this.binding.commit();
-                    else
-                        await this.binding.rollback();
-                }
-                finally {
-                    // A terminal binding call consumes the underlying transaction even
-                    // when its durable commit or rollback reports an error.
-                    this.finished = true;
-                    transactionFinalizer.unregister(this);
-                    this.onFinish();
-                }
-            })();
+        // The first terminal call owns the handle immediately. In particular,
+        // 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();
+        }
+        finally {
+            // Keep the parent transaction lease until the binding settles. A
+            // terminal call consumes the handle even when it reports an error.
+            transactionFinalizer.unregister(this);
+            this.onFinish();
         }
-        await this.finishPromise;
     }
 }
 function transactionClosedError() {

package/dist/storage-adapter.d.ts

@@ -98,10 +98,6 @@ export type LixStoragePrecondition = {
     kind: "rangeEmpty";
     space: LixStorageSpace;
     range: LixStorageKeyRange;
-} | {
-    kind: "branchEquals";
-    refKey: Uint8Array;
-    expected: Uint8Array;
 };
 export type LixStorageGetManyRequest = {
     space: LixStorageSpace;

package/dist/types.d.ts

@@ -75,6 +75,61 @@ export type LixOpenReport = {
     initialized: boolean;
     migration?: LixOpenMigrationReport;
 };
+/** A retained local generation. Presence does not mean recovery is complete. */
+export type ReplicaRecoverySource = {
+    id: string;
+    sourceFormat: number;
+    repositoryId: string;
+    accountId: string;
+    recoveryRequired: boolean;
+};
+export type ReplicaRecoveryRow = {
+    rowPk: JsonValue;
+    schemaKey: string;
+    fileId: string | null;
+    snapshot: JsonValue;
+    metadata: JsonValue;
+    deleted: boolean;
+    untracked: boolean;
+    global: boolean;
+    changeId: string | null;
+    commitId: string | null;
+};
+export type ReplicaRecoveryBranch = {
+    branchId: string;
+    headCommitId: string;
+    checkpointCommitId: string | null;
+    rows: ReplicaRecoveryRow[];
+};
+export type ReplicaRecoveryBlob = {
+    id: string;
+    contentBase64: string;
+};
+export type ReplicaRecoveryFile = {
+    branchId: string;
+    id: string;
+    path: string;
+    untracked: boolean;
+    blobId: string | null;
+};
+/** Portable recovery data; unresolved entries identify data not reconstructed. */
+export type ReplicaRecoveryExport = {
+    version: number;
+    source: ReplicaRecoverySource;
+    branches: ReplicaRecoveryBranch[];
+    commits: JsonValue[];
+    uploads: JsonValue[];
+    blobs: ReplicaRecoveryBlob[];
+    files: ReplicaRecoveryFile[];
+    unresolved: string[];
+};
+/** Local recovery result. This does not acknowledge durable server storage. */
+export type ReplicaRecoveryReceipt = {
+    branchIds: string[];
+    restoredFiles: number;
+    restoredRows: number;
+    unresolved: string[];
+};
 export type LixOpenProgressOptions = {
     /** Observes local inspection, automatic migration, and opening. */
     onProgress?(progress: LixOpenProgress): void;
@@ -164,6 +219,18 @@ export type ResultColumn = {
 export type ResultObjectRow = Record<string, unknown>;
 export type ResultArrayRow = unknown[];
 export type ResultRow = ResultObjectRow | ResultArrayRow;
+/**
+ * The active-branch commits a write moved between.
+ *
+ * `before` is the active branch's head before the write and `after` the head
+ * it published, so `lix_diff('lix_file', before, after)` is exactly what the
+ * write changed. A write that published no commit on the active branch
+ * reports both ids equal; a restore reports the commit it moved the head to.
+ */
+export type CommitSpan = {
+    before: string;
+    after: string;
+};
 export type ExecuteResult<TRow extends object = ResultObjectRow> = {
     statementIndex?: number;
     label?: string;
@@ -175,6 +242,15 @@ export type ExecuteResult<TRow extends object = ResultObjectRow> = {
         message: string;
         hint?: string;
     }>;
+    /**
+     * Present on every auto-committed write statement, including `RETURNING`
+     * writes, and on every statement of a written batch (all carry the
+     * batch's one span, read statements included). Absent for read
+     * statements outside a written batch, read-only batches, statements
+     * inside an explicit transaction (whose commit is the write), and the
+     * first commit on a branch that had no head yet.
+     */
+    commit?: CommitSpan;
 };
 export type ExecuteBatchResult<TRow extends object = ResultObjectRow> = ExecuteResult<TRow> & {
     statementIndex: number;

package/dist/wasm/lix_js_sdk.d.ts

@@ -13,6 +13,7 @@ export class WasmLix {
     createHosted(server: any): Promise<any>;
     execute(sql: string, params: any, options?: any | null): Promise<any>;
     executeBatch(statements: any, options?: any | null): Promise<any>;
+    exportReplicaRecovery(id: string): Promise<any>;
     exportSnapshot(): WasmSnapshotExport;
     importFilesystemPaths(_paths: any): Promise<void>;
     mergeBranch(options: any): Promise<any>;
@@ -20,7 +21,9 @@ export class WasmLix {
     observe(sql: string, params: any): Promise<WasmObserveEvents>;
     openAnotherSession(options: any): Promise<WasmLix>;
     openReport(): any;
+    recoverReplica(id: string): Promise<any>;
     redo(): Promise<any>;
+    replicaRecoverySources(): Promise<any>;
     setTelemetryParent(parent?: any | null): void;
     switchBranch(options: any): Promise<any>;
     syncDiskToLix(): Promise<void>;
@@ -56,13 +59,16 @@ export class WasmRemoteLix {
     createBranch(options: any): Promise<any>;
     execute(sql: string, params: any, options?: any | null): Promise<any>;
     executeBatch(statements: any, options?: any | null): Promise<any>;
+    exportReplicaRecovery(_id: string): Promise<any>;
     exportSnapshot(): WasmSnapshotExport;
     importFilesystemPaths(_paths: any): Promise<void>;
     mergeBranch(options: any): Promise<any>;
     mergeBranchPreview(options: any): Promise<any>;
     observe(sql: string, params: any): Promise<WasmRemoteObserveEvents>;
     openAnotherSession(options: any): Promise<WasmRemoteLix>;
+    recoverReplica(_id: string): Promise<any>;
     redo(): Promise<any>;
+    replicaRecoverySources(): Promise<any>;
     setTelemetryParent(_parent?: any | null): void;
     switchBranch(options: any): Promise<any>;
     syncDiskToLix(): Promise<void>;
@@ -146,6 +152,7 @@ export interface InitOutput {
     readonly wasmlix_createHosted: (a: number, b: number) => number;
     readonly wasmlix_execute: (a: number, b: number, c: number, d: number, e: number) => number;
     readonly wasmlix_executeBatch: (a: number, b: number, c: number) => number;
+    readonly wasmlix_exportReplicaRecovery: (a: number, b: number, c: number) => number;
     readonly wasmlix_exportSnapshot: (a: number) => number;
     readonly wasmlix_importFilesystemPaths: (a: number, b: number) => number;
     readonly wasmlix_mergeBranch: (a: number, b: number) => number;
@@ -153,7 +160,9 @@ export interface InitOutput {
     readonly wasmlix_observe: (a: number, b: number, c: number, d: number) => number;
     readonly wasmlix_openAnotherSession: (a: number, b: number) => number;
     readonly wasmlix_openReport: (a: number, b: number) => void;
+    readonly wasmlix_recoverReplica: (a: number, b: number, c: number) => number;
     readonly wasmlix_redo: (a: number) => number;
+    readonly wasmlix_replicaRecoverySources: (a: number) => number;
     readonly wasmlix_setTelemetryParent: (a: number, b: number, c: number) => void;
     readonly wasmlix_switchBranch: (a: number, b: number) => number;
     readonly wasmlix_syncDiskToLix: (a: number) => number;
@@ -171,13 +180,16 @@ export interface InitOutput {
     readonly wasmremotelix_createBranch: (a: number, b: number) => number;
     readonly wasmremotelix_execute: (a: number, b: number, c: number, d: number, e: number) => number;
     readonly wasmremotelix_executeBatch: (a: number, b: number, c: number) => number;
+    readonly wasmremotelix_exportReplicaRecovery: (a: number, b: number, c: number) => number;
     readonly wasmremotelix_exportSnapshot: (a: number) => number;
     readonly wasmremotelix_importFilesystemPaths: (a: number, b: number) => number;
     readonly wasmremotelix_mergeBranch: (a: number, b: number) => number;
     readonly wasmremotelix_mergeBranchPreview: (a: number, b: number) => number;
     readonly wasmremotelix_observe: (a: number, b: number, c: number, d: number) => number;
     readonly wasmremotelix_openAnotherSession: (a: number, b: number) => number;
+    readonly wasmremotelix_recoverReplica: (a: number, b: number, c: number) => number;
     readonly wasmremotelix_redo: (a: number) => number;
+    readonly wasmremotelix_replicaRecoverySources: (a: number) => number;
     readonly wasmremotelix_setTelemetryParent: (a: number, b: number) => void;
     readonly wasmremotelix_switchBranch: (a: number, b: number) => number;
     readonly wasmremotelix_syncDiskToLix: (a: number) => number;
@@ -194,10 +206,10 @@ export interface InitOutput {
     readonly wasmsnapshotrestore_finish: (a: number) => number;
     readonly wasmsnapshotrestore_isComplete: (a: number) => number;
     readonly wasmsnapshotrestore_write: (a: number, b: number, c: number) => number;
-    readonly __wasm_bindgen_func_elem_95597: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_95599: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_17533: (a: number, b: number, c: number) => number;
-    readonly __wasm_bindgen_func_elem_17532: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_95812: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_95814: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_17860: (a: number, b: number, c: number) => number;
+    readonly __wasm_bindgen_func_elem_17859: (a: number, b: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_export3: (a: number) => void;