ducjs 3.0.4 → 3.0.5

package/dist/ducjs_wasm.d.ts

@@ -1,28 +1,30 @@
 /* tslint:disable */
 /* eslint-disable */
 /**
- * Parse a `.duc` file (Uint8Array) into a JS object (ExportedDataState).
+ * Fetch a single external file from a `.duc` buffer by file ID.
+ *
+ * Returns the file entry as a JS object, or `undefined` if not found.
  */
-export function parseDuc(buf: Uint8Array): any;
+export function getExternalFile(buf: Uint8Array, file_id: string): any;
 /**
- * Read the full VersionGraph from a `.duc` file buffer.
+ * Restore a specific checkpoint by its ID from a `.duc` file buffer.
  *
- * Returns a JS object matching the `VersionGraph` TypeScript interface,
- * or `undefined` if no version graph exists.
+ * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
  */
-export function readVersionGraph(duc_buf: Uint8Array): any;
+export function restoreCheckpoint(duc_buf: Uint8Array, checkpoint_id: string): any;
 /**
- * Fetch a single external file from a `.duc` buffer by file ID.
+ * List all versions (checkpoints + deltas) from a `.duc` file buffer.
  *
- * Returns the file entry as a JS object, or `undefined` if not found.
+ * Returns a JS array of `VersionEntry` objects (no heavy data blobs).
  */
-export function getExternalFile(buf: Uint8Array, file_id: string): any;
+export function listVersions(duc_buf: Uint8Array): any;
 /**
- * Revert the document to a specific version, removing all newer versions.
+ * Read the full VersionGraph from a `.duc` file buffer.
  *
- * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
+ * Returns a JS object matching the `VersionGraph` TypeScript interface,
+ * or `undefined` if no version graph exists.
  */
-export function revertToVersion(duc_buf: Uint8Array, target_version: number): any;
+export function readVersionGraph(duc_buf: Uint8Array): any;
 /**
  * Returns the current version-control schema version defined in Rust.
  *
@@ -32,12 +34,6 @@ export function revertToVersion(duc_buf: Uint8Array, target_version: number): an
  * recording migrations) the next time a checkpoint or delta is created.
  */
 export function getCurrentSchemaVersion(): number;
-/**
- * List all versions (checkpoints + deltas) from a `.duc` file buffer.
- *
- * Returns a JS array of `VersionEntry` objects (no heavy data blobs).
- */
-export function listVersions(duc_buf: Uint8Array): any;
 /**
  * Restore the document state at `version_number` from a `.duc` file buffer.
  *
@@ -47,31 +43,58 @@ export function listVersions(duc_buf: Uint8Array): any;
  * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
  */
 export function restoreVersion(duc_buf: Uint8Array, version_number: number): any;
+/**
+ * Revert the document to a specific version, removing all newer versions.
+ *
+ * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
+ */
+export function revertToVersion(duc_buf: Uint8Array, target_version: number): any;
+/**
+ * Apply a changeset to reconstruct document state.
+ *
+ * `base_state` must be the exact checkpoint data used when the changeset
+ * was created. Returns the full document state as `Uint8Array`.
+ *
+ * Handles all changeset formats transparently:
+ *   - v3 (bsdiff), v2 (XOR diff), v1 (zlib full snapshot)
+ */
+export function applyDeltaChangeset(base_state: Uint8Array, changeset: Uint8Array): Uint8Array;
+/**
+ * List metadata for all external files (without loading the heavy data blobs).
+ */
+export function listExternalFiles(buf: Uint8Array): any;
 /**
  * Serialize a JS object (ExportedDataState) into `.duc` bytes (Uint8Array).
  */
 export function serializeDuc(data: any): Uint8Array;
 /**
- * Restore a specific checkpoint by its ID from a `.duc` file buffer.
+ * Compute a checkpoint-relative binary diff changeset using bsdiff.
  *
- * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
+ * `base_state` is the checkpoint's full data blob.
+ * `current_state` is the full document state at the new version.
+ *
+ * Returns an encoded changeset (`Uint8Array`) ready for storage in a
+ * `Delta.payload`. bsdiff finds matching blocks even when they shift
+ * offsets, which is critical for SQLite databases.
  */
-export function restoreCheckpoint(duc_buf: Uint8Array, checkpoint_id: string): any;
+export function createDeltaChangeset(base_state: Uint8Array, current_state: Uint8Array): Uint8Array;
+/**
+ * Parse a `.duc` file (Uint8Array) into a JS object (ExportedDataState).
+ */
+export function parseDuc(buf: Uint8Array): any;
 /**
  * Parse a `.duc` file lazily — returns everything EXCEPT external file data blobs.
  *
  * Use `getExternalFile()` or `listExternalFiles()` for on-demand access.
  */
 export function parseDucLazy(buf: Uint8Array): any;
-/**
- * List metadata for all external files (without loading the heavy data blobs).
- */
-export function listExternalFiles(buf: Uint8Array): any;
 
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
   readonly memory: WebAssembly.Memory;
+  readonly applyDeltaChangeset: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+  readonly createDeltaChangeset: (a: number, b: number, c: number, d: number) => [number, number, number, number];
   readonly getCurrentSchemaVersion: () => number;
   readonly getExternalFile: (a: number, b: number, c: number, d: number) => [number, number, number];
   readonly listExternalFiles: (a: number, b: number) => [number, number, number];

package/dist/ducjs_wasm.js

@@ -195,14 +195,19 @@ function takeFromExternrefTable0(idx) {
     return value;
 }
 /**
- * Parse a `.duc` file (Uint8Array) into a JS object (ExportedDataState).
+ * Fetch a single external file from a `.duc` buffer by file ID.
+ *
+ * Returns the file entry as a JS object, or `undefined` if not found.
  * @param {Uint8Array} buf
+ * @param {string} file_id
  * @returns {any}
  */
-export function parseDuc(buf) {
+export function getExternalFile(buf, file_id) {
     const ptr0 = passArray8ToWasm0(buf, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.parseDuc(ptr0, len0);
+    const ptr1 = passStringToWasm0(file_id, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.getExternalFile(ptr0, len0, ptr1, len1);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -210,17 +215,19 @@ export function parseDuc(buf) {
 }
 
 /**
- * Read the full VersionGraph from a `.duc` file buffer.
+ * Restore a specific checkpoint by its ID from a `.duc` file buffer.
  *
- * Returns a JS object matching the `VersionGraph` TypeScript interface,
- * or `undefined` if no version graph exists.
+ * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
  * @param {Uint8Array} duc_buf
+ * @param {string} checkpoint_id
  * @returns {any}
  */
-export function readVersionGraph(duc_buf) {
+export function restoreCheckpoint(duc_buf, checkpoint_id) {
     const ptr0 = passArray8ToWasm0(duc_buf, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.readVersionGraph(ptr0, len0);
+    const ptr1 = passStringToWasm0(checkpoint_id, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.restoreCheckpoint(ptr0, len0, ptr1, len1);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -228,19 +235,16 @@ export function readVersionGraph(duc_buf) {
 }
 
 /**
- * Fetch a single external file from a `.duc` buffer by file ID.
+ * List all versions (checkpoints + deltas) from a `.duc` file buffer.
  *
- * Returns the file entry as a JS object, or `undefined` if not found.
- * @param {Uint8Array} buf
- * @param {string} file_id
+ * Returns a JS array of `VersionEntry` objects (no heavy data blobs).
+ * @param {Uint8Array} duc_buf
  * @returns {any}
  */
-export function getExternalFile(buf, file_id) {
-    const ptr0 = passArray8ToWasm0(buf, wasm.__wbindgen_malloc);
+export function listVersions(duc_buf) {
+    const ptr0 = passArray8ToWasm0(duc_buf, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ptr1 = passStringToWasm0(file_id, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len1 = WASM_VECTOR_LEN;
-    const ret = wasm.getExternalFile(ptr0, len0, ptr1, len1);
+    const ret = wasm.listVersions(ptr0, len0);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -248,17 +252,17 @@ export function getExternalFile(buf, file_id) {
 }
 
 /**
- * Revert the document to a specific version, removing all newer versions.
+ * Read the full VersionGraph from a `.duc` file buffer.
  *
- * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
+ * Returns a JS object matching the `VersionGraph` TypeScript interface,
+ * or `undefined` if no version graph exists.
  * @param {Uint8Array} duc_buf
- * @param {number} target_version
  * @returns {any}
  */
-export function revertToVersion(duc_buf, target_version) {
+export function readVersionGraph(duc_buf) {
     const ptr0 = passArray8ToWasm0(duc_buf, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.revertToVersion(ptr0, len0, target_version);
+    const ret = wasm.readVersionGraph(ptr0, len0);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -279,16 +283,20 @@ export function getCurrentSchemaVersion() {
 }
 
 /**
- * List all versions (checkpoints + deltas) from a `.duc` file buffer.
+ * Restore the document state at `version_number` from a `.duc` file buffer.
  *
- * Returns a JS array of `VersionEntry` objects (no heavy data blobs).
+ * The `.duc` file is a SQLite database — this function opens it and queries
+ * the `checkpoints` / `deltas` tables directly for version restoration.
+ *
+ * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
  * @param {Uint8Array} duc_buf
+ * @param {number} version_number
  * @returns {any}
  */
-export function listVersions(duc_buf) {
+export function restoreVersion(duc_buf, version_number) {
     const ptr0 = passArray8ToWasm0(duc_buf, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.listVersions(ptr0, len0);
+    const ret = wasm.restoreVersion(ptr0, len0, version_number);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -296,20 +304,58 @@ export function listVersions(duc_buf) {
 }
 
 /**
- * Restore the document state at `version_number` from a `.duc` file buffer.
- *
- * The `.duc` file is a SQLite database — this function opens it and queries
- * the `checkpoints` / `deltas` tables directly for version restoration.
+ * Revert the document to a specific version, removing all newer versions.
  *
  * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
  * @param {Uint8Array} duc_buf
- * @param {number} version_number
+ * @param {number} target_version
  * @returns {any}
  */
-export function restoreVersion(duc_buf, version_number) {
+export function revertToVersion(duc_buf, target_version) {
     const ptr0 = passArray8ToWasm0(duc_buf, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.restoreVersion(ptr0, len0, version_number);
+    const ret = wasm.revertToVersion(ptr0, len0, target_version);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
+/**
+ * Apply a changeset to reconstruct document state.
+ *
+ * `base_state` must be the exact checkpoint data used when the changeset
+ * was created. Returns the full document state as `Uint8Array`.
+ *
+ * Handles all changeset formats transparently:
+ *   - v3 (bsdiff), v2 (XOR diff), v1 (zlib full snapshot)
+ * @param {Uint8Array} base_state
+ * @param {Uint8Array} changeset
+ * @returns {Uint8Array}
+ */
+export function applyDeltaChangeset(base_state, changeset) {
+    const ptr0 = passArray8ToWasm0(base_state, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passArray8ToWasm0(changeset, wasm.__wbindgen_malloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.applyDeltaChangeset(ptr0, len0, ptr1, len1);
+    if (ret[3]) {
+        throw takeFromExternrefTable0(ret[2]);
+    }
+    var v3 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+    return v3;
+}
+
+/**
+ * List metadata for all external files (without loading the heavy data blobs).
+ * @param {Uint8Array} buf
+ * @returns {any}
+ */
+export function listExternalFiles(buf) {
+    const ptr0 = passArray8ToWasm0(buf, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.listExternalFiles(ptr0, len0);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -332,36 +378,41 @@ export function serializeDuc(data) {
 }
 
 /**
- * Restore a specific checkpoint by its ID from a `.duc` file buffer.
+ * Compute a checkpoint-relative binary diff changeset using bsdiff.
  *
- * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
- * @param {Uint8Array} duc_buf
- * @param {string} checkpoint_id
- * @returns {any}
+ * `base_state` is the checkpoint's full data blob.
+ * `current_state` is the full document state at the new version.
+ *
+ * Returns an encoded changeset (`Uint8Array`) ready for storage in a
+ * `Delta.payload`. bsdiff finds matching blocks even when they shift
+ * offsets, which is critical for SQLite databases.
+ * @param {Uint8Array} base_state
+ * @param {Uint8Array} current_state
+ * @returns {Uint8Array}
  */
-export function restoreCheckpoint(duc_buf, checkpoint_id) {
-    const ptr0 = passArray8ToWasm0(duc_buf, wasm.__wbindgen_malloc);
+export function createDeltaChangeset(base_state, current_state) {
+    const ptr0 = passArray8ToWasm0(base_state, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ptr1 = passStringToWasm0(checkpoint_id, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const ptr1 = passArray8ToWasm0(current_state, wasm.__wbindgen_malloc);
     const len1 = WASM_VECTOR_LEN;
-    const ret = wasm.restoreCheckpoint(ptr0, len0, ptr1, len1);
-    if (ret[2]) {
-        throw takeFromExternrefTable0(ret[1]);
+    const ret = wasm.createDeltaChangeset(ptr0, len0, ptr1, len1);
+    if (ret[3]) {
+        throw takeFromExternrefTable0(ret[2]);
     }
-    return takeFromExternrefTable0(ret[0]);
+    var v3 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+    return v3;
 }
 
 /**
- * Parse a `.duc` file lazily — returns everything EXCEPT external file data blobs.
- *
- * Use `getExternalFile()` or `listExternalFiles()` for on-demand access.
+ * Parse a `.duc` file (Uint8Array) into a JS object (ExportedDataState).
  * @param {Uint8Array} buf
  * @returns {any}
  */
-export function parseDucLazy(buf) {
+export function parseDuc(buf) {
     const ptr0 = passArray8ToWasm0(buf, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.parseDucLazy(ptr0, len0);
+    const ret = wasm.parseDuc(ptr0, len0);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -369,14 +420,16 @@ export function parseDucLazy(buf) {
 }
 
 /**
- * List metadata for all external files (without loading the heavy data blobs).
+ * Parse a `.duc` file lazily — returns everything EXCEPT external file data blobs.
+ *
+ * Use `getExternalFile()` or `listExternalFiles()` for on-demand access.
  * @param {Uint8Array} buf
  * @returns {any}
  */
-export function listExternalFiles(buf) {
+export function parseDucLazy(buf) {
     const ptr0 = passArray8ToWasm0(buf, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.listExternalFiles(ptr0, len0);
+    const ret = wasm.parseDucLazy(ptr0, len0);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }

package/dist/ducjs_wasm_bg.wasm.d.ts

@@ -1,6 +1,8 @@
 /* tslint:disable */
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
+export const applyDeltaChangeset: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+export const createDeltaChangeset: (a: number, b: number, c: number, d: number) => [number, number, number, number];
 export const getCurrentSchemaVersion: () => number;
 export const getExternalFile: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const listExternalFiles: (a: number, b: number) => [number, number, number];

package/dist/parse.js

@@ -40,7 +40,18 @@ export function parseDuc(blob, _fileHandle, elementsConfig, restoreConfig) {
             throw new Error(`[parseDuc] wasm parse failed (size=${buffer.byteLength}, header="${header}", prefix=${prefixHex}): ${error instanceof Error ? error.message : String(error)}`);
         }
         const data = transformFromRust(raw);
-        return restore(data, elementsConfig !== null && elementsConfig !== void 0 ? elementsConfig : { syncInvalidIndices: (els) => els }, restoreConfig);
+        // Preserve the original version graph from Rust before restore() can
+        // filter out entries through restoreCheckpoint/restoreDelta validation.
+        // The VG data is already validated by the Rust parser.
+        const originalVG = data.versionGraph;
+        const restored = restore(Object.assign(Object.assign({}, data), { 
+            // Preserve versionGraph from Rust separately; do not run it through restore()
+            versionGraph: undefined }), elementsConfig !== null && elementsConfig !== void 0 ? elementsConfig : { syncInvalidIndices: (els) => els }, restoreConfig);
+        // Use the original version graph from Rust, bypassing restore's lossy filtering
+        if (originalVG) {
+            restored.versionGraph = originalVG;
+        }
+        return restored;
     });
 }
 /**
@@ -65,10 +76,18 @@ export function parseDucLazy(buffer, elementsConfig, restoreConfig) {
             throw new Error(`[parseDucLazy] wasm parse failed (size=${buffer.byteLength}, header="${header}", prefix=${prefixHex}): ${error instanceof Error ? error.message : String(error)}`);
         }
         const data = transformFromRust(raw);
+        // Preserve the original version graph from Rust before restore() filters
+        const originalVG = data.versionGraph;
         const lazyFileStore = new LazyExternalFileStore(buffer);
         const files = {};
-        const restored = restore(Object.assign(Object.assign({}, data), { files }), elementsConfig !== null && elementsConfig !== void 0 ? elementsConfig : { syncInvalidIndices: (els) => els }, restoreConfig);
+        const restored = restore(Object.assign(Object.assign({}, data), { files, 
+            // Preserve versionGraph from Rust separately; do not run it through restore()
+            versionGraph: undefined }), elementsConfig !== null && elementsConfig !== void 0 ? elementsConfig : { syncInvalidIndices: (els) => els }, restoreConfig);
         restored.lazyFileStore = lazyFileStore;
+        // Use the original version graph from Rust, bypassing restore's lossy filtering
+        if (originalVG) {
+            restored.versionGraph = originalVG;
+        }
         return restored;
     });
 }

package/dist/restore/restoreDataState.js

@@ -367,11 +367,6 @@ export const restoreVersionGraph = (importedGraph) => {
     if (!importedGraph || typeof importedGraph !== "object") {
         return undefined;
     }
-    const userCheckpointVersionId = isValidString(importedGraph.userCheckpointVersionId);
-    const latestVersionId = isValidString(importedGraph.latestVersionId);
-    if (!userCheckpointVersionId || !latestVersionId) {
-        return undefined;
-    }
     const checkpoints = Array.isArray(importedGraph.checkpoints)
         ? importedGraph.checkpoints
             .map((checkpoint) => restoreCheckpoint(checkpoint))
@@ -382,6 +377,17 @@ export const restoreVersionGraph = (importedGraph) => {
             .map((delta) => restoreDelta(delta))
             .filter((delta) => Boolean(delta))
         : [];
+    if (checkpoints.length === 0 && deltas.length === 0) {
+        return undefined;
+    }
+    // Head IDs can legitimately be empty strings (e.g. after Rust roundtrip
+    // where the DB stores NULL → unwrap_or_default → ""). Accept any string.
+    const userCheckpointVersionId = typeof importedGraph.userCheckpointVersionId === "string"
+        ? importedGraph.userCheckpointVersionId
+        : "";
+    const latestVersionId = typeof importedGraph.latestVersionId === "string"
+        ? importedGraph.latestVersionId
+        : "";
     const importedMetadata = importedGraph.metadata;
     const metadata = {
         currentVersion: isFiniteNumber(importedMetadata === null || importedMetadata === void 0 ? void 0 : importedMetadata.currentVersion) && importedMetadata.currentVersion >= 0
@@ -411,6 +417,7 @@ export const restoreVersionGraph = (importedGraph) => {
     };
 };
 export const restoreCheckpoint = (importedCheckpoint) => {
+    var _a, _b, _c;
     if (!importedCheckpoint || typeof importedCheckpoint !== "object") {
         return undefined;
     }
@@ -419,10 +426,11 @@ export const restoreCheckpoint = (importedCheckpoint) => {
         return undefined;
     }
     const id = isValidString(checkpoint.id);
-    const data = isValidUint8Array(checkpoint.data);
-    if (!id || !data) {
+    if (!id) {
         return undefined;
     }
+    // Accept empty Uint8Array — shell/remote entries have byteLength === 0
+    const data = (_c = (_b = (_a = isValidUint8Array(checkpoint.data)) !== null && _a !== void 0 ? _a : (checkpoint.data instanceof Uint8Array ? checkpoint.data : undefined)) !== null && _b !== void 0 ? _b : (checkpoint.data instanceof ArrayBuffer ? new Uint8Array(checkpoint.data) : undefined)) !== null && _c !== void 0 ? _c : new Uint8Array(0);
     return {
         type: "checkpoint",
         id,
@@ -443,6 +451,7 @@ export const restoreCheckpoint = (importedCheckpoint) => {
     };
 };
 export const restoreDelta = (importedDelta) => {
+    var _a, _b, _c;
     if (!importedDelta || typeof importedDelta !== "object") {
         return undefined;
     }
@@ -451,11 +460,13 @@ export const restoreDelta = (importedDelta) => {
         return undefined;
     }
     const id = isValidString(delta.id);
-    const payload = isValidUint8Array(delta.payload);
-    const baseCheckpointId = isValidString(delta.baseCheckpointId);
-    if (!id || !payload || !baseCheckpointId) {
+    if (!id) {
         return undefined;
     }
+    // Accept empty Uint8Array — shell/remote entries have byteLength === 0
+    const payload = (_c = (_b = (_a = isValidUint8Array(delta.payload)) !== null && _a !== void 0 ? _a : (delta.payload instanceof Uint8Array ? delta.payload : undefined)) !== null && _b !== void 0 ? _b : (delta.payload instanceof ArrayBuffer ? new Uint8Array(delta.payload) : undefined)) !== null && _c !== void 0 ? _c : new Uint8Array(0);
+    // baseCheckpointId can be empty for shell entries or first-in-chain deltas
+    const baseCheckpointId = typeof delta.baseCheckpointId === "string" ? delta.baseCheckpointId : "";
     return {
         type: "delta",
         id,

package/dist/serialize.js

@@ -33,15 +33,111 @@ export function serializeDuc(data, elementsConfig, restoreConfig) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, _b, _c, _d;
         yield ensureWasm();
-        const restored = restore(data, elementsConfig !== null && elementsConfig !== void 0 ? elementsConfig : { syncInvalidIndices: (els) => els }, restoreConfig);
-        const shouldDropLegacyVersionGraph = hasLegacyVersionGraphShape(data === null || data === void 0 ? void 0 : data.versionGraph);
-        const payloadForRust = Object.assign(Object.assign({ type: (_a = data.type) !== null && _a !== void 0 ? _a : "duc", version: (_c = (_b = data.version) !== null && _b !== void 0 ? _b : DUC_SCHEMA_VERSION) !== null && _c !== void 0 ? _c : decodeUserVersionToSemver(wasmGetCurrentSchemaVersion()), source: (_d = data.source) !== null && _d !== void 0 ? _d : "ducjs" }, restored), { versionGraph: shouldDropLegacyVersionGraph
-                ? undefined
-                : restored.versionGraph });
+        const inputVG = data === null || data === void 0 ? void 0 : data.versionGraph;
+        const restored = restore(Object.assign(Object.assign({}, data), { 
+            // Version graph is preserved separately — bypass restore()'s VG processing.
+            versionGraph: undefined }), elementsConfig !== null && elementsConfig !== void 0 ? elementsConfig : { syncInvalidIndices: (els) => els }, restoreConfig);
+        const shouldDropLegacyVersionGraph = hasLegacyVersionGraphShape(inputVG);
+        // Use the ORIGINAL version graph data instead of the restored one.
+        // The restore pipeline (restoreCheckpoint/restoreDelta) filters checkpoints
+        // and deltas through isValidUint8Array which can reject valid in-memory 
+        // Uint8Array data (e.g. empty remote placeholders or detached buffers),
+        // silently dropping version history.
+        // hasLegacyVersionGraphShape already validates structural integrity.
+        const versionGraphForPayload = shouldDropLegacyVersionGraph
+            ? undefined
+            : prepareVersionGraphForSerialization(inputVG);
+        const normalizedVersionGraphForPayload = versionGraphForPayload
+            ? normalizeVersionGraphVersionNumbers(versionGraphForPayload)
+            : undefined;
+        const payloadForRust = Object.assign(Object.assign({ type: (_a = data.type) !== null && _a !== void 0 ? _a : "duc", version: (_c = (_b = data.version) !== null && _b !== void 0 ? _b : DUC_SCHEMA_VERSION) !== null && _c !== void 0 ? _c : decodeUserVersionToSemver(wasmGetCurrentSchemaVersion()), source: (_d = data.source) !== null && _d !== void 0 ? _d : "ducjs" }, restored), { versionGraph: normalizedVersionGraphForPayload });
         const prepared = transformToRust(payloadForRust);
-        return wasmSerializeDuc(prepared);
+        const serialized = wasmSerializeDuc(prepared);
+        return serialized;
     });
 }
+/**
+ * Ensure version numbers are unique before persistence.
+ * SQLite schema enforces UNIQUE(version_number) on both checkpoints and deltas.
+ * Collisions would otherwise cause INSERT OR REPLACE to drop historical entries.
+ */
+function normalizeVersionGraphVersionNumbers(vg) {
+    var _a;
+    const normalizeList = (items) => {
+        if (!Array.isArray(items) || items.length === 0) {
+            return [];
+        }
+        const sorted = [...items].sort((a, b) => {
+            const aNum = Number.isFinite(a === null || a === void 0 ? void 0 : a.versionNumber) ? Number(a.versionNumber) : Number.MAX_SAFE_INTEGER;
+            const bNum = Number.isFinite(b === null || b === void 0 ? void 0 : b.versionNumber) ? Number(b.versionNumber) : Number.MAX_SAFE_INTEGER;
+            if (aNum !== bNum)
+                return aNum - bNum;
+            const aTs = Number.isFinite(a === null || a === void 0 ? void 0 : a.timestamp) ? Number(a.timestamp) : 0;
+            const bTs = Number.isFinite(b === null || b === void 0 ? void 0 : b.timestamp) ? Number(b.timestamp) : 0;
+            if (aTs !== bTs)
+                return aTs - bTs;
+            const aId = typeof (a === null || a === void 0 ? void 0 : a.id) === "string" ? a.id : "";
+            const bId = typeof (b === null || b === void 0 ? void 0 : b.id) === "string" ? b.id : "";
+            return aId.localeCompare(bId);
+        });
+        let nextVersion = 0;
+        return sorted.map((item) => {
+            const candidate = Number.isFinite(item === null || item === void 0 ? void 0 : item.versionNumber) ? Number(item.versionNumber) : nextVersion;
+            const assigned = Math.max(candidate, nextVersion);
+            nextVersion = assigned + 1;
+            return Object.assign(Object.assign({}, item), { versionNumber: assigned });
+        });
+    };
+    const checkpoints = normalizeList(Array.isArray(vg === null || vg === void 0 ? void 0 : vg.checkpoints) ? vg.checkpoints : []);
+    const deltas = normalizeList(Array.isArray(vg === null || vg === void 0 ? void 0 : vg.deltas) ? vg.deltas : []);
+    const maxCheckpointVersion = checkpoints.length
+        ? Math.max(...checkpoints.map((cp) => Number(cp.versionNumber) || 0))
+        : 0;
+    const maxDeltaVersion = deltas.length
+        ? Math.max(...deltas.map((d) => Number(d.versionNumber) || 0))
+        : 0;
+    const maxVersion = Math.max(maxCheckpointVersion, maxDeltaVersion, 0);
+    return Object.assign(Object.assign({}, vg), { checkpoints,
+        deltas, metadata: Object.assign(Object.assign({}, vg.metadata), { currentVersion: Number.isFinite((_a = vg === null || vg === void 0 ? void 0 : vg.metadata) === null || _a === void 0 ? void 0 : _a.currentVersion)
+                ? Math.max(Number(vg.metadata.currentVersion), maxVersion)
+                : maxVersion }) });
+}
+/**
+ * Prepares version graph for serialization by filtering out shell entries
+ * (remote placeholders with empty data/payload) while preserving all entries
+ * with actual binary data intact.
+ */
+function prepareVersionGraphForSerialization(vg) {
+    if (!vg || typeof vg !== "object")
+        return undefined;
+    const checkpoints = Array.isArray(vg.checkpoints)
+        ? vg.checkpoints.filter((cp) => {
+            const data = cp === null || cp === void 0 ? void 0 : cp.data;
+            if (data instanceof Uint8Array)
+                return data.byteLength > 0;
+            if (data instanceof ArrayBuffer)
+                return data.byteLength > 0;
+            // Accept base64 strings (from JSON imports)
+            if (typeof data === "string" && data.length > 0)
+                return true;
+            return false;
+        })
+        : [];
+    const deltas = Array.isArray(vg.deltas)
+        ? vg.deltas.filter((d) => {
+            const payload = d === null || d === void 0 ? void 0 : d.payload;
+            if (payload instanceof Uint8Array)
+                return payload.byteLength > 0;
+            if (payload instanceof ArrayBuffer)
+                return payload.byteLength > 0;
+            if (typeof payload === "string" && payload.length > 0)
+                return true;
+            return false;
+        })
+        : [];
+    return Object.assign(Object.assign({}, vg), { checkpoints,
+        deltas });
+}
 function hasLegacyVersionGraphShape(versionGraph) {
     if (!versionGraph || typeof versionGraph !== "object") {
         return false;

package/dist/version-control.d.ts

@@ -59,3 +59,29 @@ export declare const revertToVersion: (ducBuffer: Uint8Array, targetVersion: num
  * on the next checkpoint or delta creation.
  */
 export declare const getCurrentSchemaVersion: () => Promise<number>;
+/**
+ * Compute a checkpoint-relative binary diff changeset using bsdiff.
+ *
+ * `baseState` is the checkpoint's full data blob (the snapshot at the
+ * base checkpoint version). `currentState` is the full document state
+ * at the new version being saved as a delta.
+ *
+ * Returns an encoded changeset (`Uint8Array`) suitable for use as
+ * `Delta.payload`. bsdiff finds matching blocks even when they shift
+ * offsets, which is critical for SQLite databases where internal page
+ * reordering makes simple byte-level diffs ineffective.
+ *
+ * Use this when constructing `Delta` objects for the `VersionGraph`
+ * before calling `serializeDuc()`.
+ */
+export declare const createDeltaChangeset: (baseState: Uint8Array, currentState: Uint8Array) => Promise<Uint8Array>;
+/**
+ * Apply a changeset to reconstruct document state.
+ *
+ * `baseState` must be the exact checkpoint data used when the changeset
+ * was created. Returns the full document state as `Uint8Array`.
+ *
+ * Handles all changeset formats transparently:
+ *   - v3 (bsdiff), v2 (XOR diff), v1 (zlib full snapshot)
+ */
+export declare const applyDeltaChangeset: (baseState: Uint8Array, changeset: Uint8Array) => Promise<Uint8Array>;

package/dist/version-control.js

@@ -7,7 +7,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { ensureWasm, wasmGetCurrentSchemaVersion, wasmListVersions, wasmReadVersionGraph, wasmRestoreCheckpoint, wasmRestoreVersion, wasmRevertToVersion, } from "./wasm";
+import { ensureWasm, wasmApplyDeltaChangeset, wasmCreateDeltaChangeset, wasmGetCurrentSchemaVersion, wasmListVersions, wasmReadVersionGraph, wasmRestoreCheckpoint, wasmRestoreVersion, wasmRevertToVersion, } from "./wasm";
 /**
  * Restore the full document state at a specific version number.
  *
@@ -82,3 +82,35 @@ export const getCurrentSchemaVersion = () => __awaiter(void 0, void 0, void 0, f
     yield ensureWasm();
     return wasmGetCurrentSchemaVersion();
 });
+/**
+ * Compute a checkpoint-relative binary diff changeset using bsdiff.
+ *
+ * `baseState` is the checkpoint's full data blob (the snapshot at the
+ * base checkpoint version). `currentState` is the full document state
+ * at the new version being saved as a delta.
+ *
+ * Returns an encoded changeset (`Uint8Array`) suitable for use as
+ * `Delta.payload`. bsdiff finds matching blocks even when they shift
+ * offsets, which is critical for SQLite databases where internal page
+ * reordering makes simple byte-level diffs ineffective.
+ *
+ * Use this when constructing `Delta` objects for the `VersionGraph`
+ * before calling `serializeDuc()`.
+ */
+export const createDeltaChangeset = (baseState, currentState) => __awaiter(void 0, void 0, void 0, function* () {
+    yield ensureWasm();
+    return wasmCreateDeltaChangeset(baseState, currentState);
+});
+/**
+ * Apply a changeset to reconstruct document state.
+ *
+ * `baseState` must be the exact checkpoint data used when the changeset
+ * was created. Returns the full document state as `Uint8Array`.
+ *
+ * Handles all changeset formats transparently:
+ *   - v3 (bsdiff), v2 (XOR diff), v1 (zlib full snapshot)
+ */
+export const applyDeltaChangeset = (baseState, changeset) => __awaiter(void 0, void 0, void 0, function* () {
+    yield ensureWasm();
+    return wasmApplyDeltaChangeset(baseState, changeset);
+});

package/dist/wasm.d.ts

@@ -1,4 +1,4 @@
-import { getCurrentSchemaVersion as _getCurrentSchemaVersion, getExternalFile as _getExternalFile, listExternalFiles as _listExternalFiles, listVersions as _listVersions, parseDuc as _parseDuc, parseDucLazy as _parseDucLazy, readVersionGraph as _readVersionGraph, restoreCheckpoint as _restoreCheckpoint, restoreVersion as _restoreVersion, revertToVersion as _revertToVersion, serializeDuc as _serializeDuc } from "../dist/ducjs_wasm";
+import { applyDeltaChangeset as _applyDeltaChangeset, createDeltaChangeset as _createDeltaChangeset, getCurrentSchemaVersion as _getCurrentSchemaVersion, getExternalFile as _getExternalFile, listExternalFiles as _listExternalFiles, listVersions as _listVersions, parseDuc as _parseDuc, parseDucLazy as _parseDucLazy, readVersionGraph as _readVersionGraph, restoreCheckpoint as _restoreCheckpoint, restoreVersion as _restoreVersion, revertToVersion as _revertToVersion, serializeDuc as _serializeDuc } from "../dist/ducjs_wasm";
 export declare function ensureWasm(wasmUrl?: string | URL | BufferSource): Promise<void>;
 /**
  * Fetch the raw WASM binary as an ArrayBuffer.
@@ -18,3 +18,5 @@ export declare const wasmListVersions: typeof _listVersions;
 export declare const wasmReadVersionGraph: typeof _readVersionGraph;
 export declare const wasmRevertToVersion: typeof _revertToVersion;
 export declare const wasmGetCurrentSchemaVersion: typeof _getCurrentSchemaVersion;
+export declare const wasmCreateDeltaChangeset: typeof _createDeltaChangeset;
+export declare const wasmApplyDeltaChangeset: typeof _applyDeltaChangeset;

package/dist/wasm.js

@@ -7,7 +7,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import init, { getCurrentSchemaVersion as _getCurrentSchemaVersion, getExternalFile as _getExternalFile, listExternalFiles as _listExternalFiles, listVersions as _listVersions, parseDuc as _parseDuc, parseDucLazy as _parseDucLazy, readVersionGraph as _readVersionGraph, restoreCheckpoint as _restoreCheckpoint, restoreVersion as _restoreVersion, revertToVersion as _revertToVersion, serializeDuc as _serializeDuc, } from "../dist/ducjs_wasm";
+import init, { applyDeltaChangeset as _applyDeltaChangeset, createDeltaChangeset as _createDeltaChangeset, getCurrentSchemaVersion as _getCurrentSchemaVersion, getExternalFile as _getExternalFile, listExternalFiles as _listExternalFiles, listVersions as _listVersions, parseDuc as _parseDuc, parseDucLazy as _parseDucLazy, readVersionGraph as _readVersionGraph, restoreCheckpoint as _restoreCheckpoint, restoreVersion as _restoreVersion, revertToVersion as _revertToVersion, serializeDuc as _serializeDuc, } from "../dist/ducjs_wasm";
 let initialized = false;
 let initPromise = null;
 export function ensureWasm(wasmUrl) {
@@ -50,3 +50,5 @@ export const wasmListVersions = _listVersions;
 export const wasmReadVersionGraph = _readVersionGraph;
 export const wasmRevertToVersion = _revertToVersion;
 export const wasmGetCurrentSchemaVersion = _getCurrentSchemaVersion;
+export const wasmCreateDeltaChangeset = _createDeltaChangeset;
+export const wasmApplyDeltaChangeset = _applyDeltaChangeset;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ducjs",
-  "version": "3.0.4",
+  "version": "3.0.5",
   "description": "The duc 2D CAD file format is a cornerstone of our advanced design system, conceived to cater to professionals seeking precision and efficiency in their design work.",
   "type": "module",
   "main": "dist/index.js",