@lix-js/sdk 0.6.0-preview.1 → 0.6.0-preview.2

package/dist/engine-wasm/wasm/lix_engine.d.ts

@@ -39,6 +39,11 @@ export class Lix {
      * @returns {Promise<any>}
      */
     mergeVersion(args: any): Promise<any>;
+    /**
+     * @param {any} args
+     * @returns {Promise<any>}
+     */
+    mergeVersionPreview(args: any): Promise<any>;
     /**
      * @param {any} args
      * @returns {Promise<any>}

package/dist/engine-wasm/wasm/lix_engine.js

@@ -63,6 +63,14 @@ export class Lix {
         const ret = wasm.lix_mergeVersion(this.__wbg_ptr, args);
         return ret;
     }
+    /**
+     * @param {any} args
+     * @returns {Promise<any>}
+     */
+    mergeVersionPreview(args) {
+        const ret = wasm.lix_mergeVersionPreview(this.__wbg_ptr, args);
+        return ret;
+    }
     /**
      * @param {any} args
      * @returns {Promise<any>}
@@ -183,18 +191,6 @@ function __wbg_get_imports() {
                 return ret;
             }, arguments);
         },
-        __wbg_call_812d25f1510c13c8: function () {
-            return handleError(function (arg0, arg1, arg2, arg3) {
-                const ret = arg0.call(arg1, arg2, arg3);
-                return ret;
-            }, arguments);
-        },
-        __wbg_call_e8c868596c950cf6: function () {
-            return handleError(function (arg0, arg1, arg2, arg3, arg4) {
-                const ret = arg0.call(arg1, arg2, arg3, arg4);
-                return ret;
-            }, arguments);
-        },
         __wbg_done_57b39ecd9addfe81: function (arg0) {
             const ret = arg0.done;
             return ret;
@@ -434,7 +430,7 @@ function __wbg_get_imports() {
             return ret;
         },
         __wbindgen_cast_0000000000000001: function (arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 3048, function: Function { arguments: [Externref], shim_idx: 3049, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 3067, function: Function { arguments: [Externref], shim_idx: 3068, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__h259bf120b5b35fc5, wasm_bindgen__convert__closures_____invoke__ha15a27e9815e3c81);
             return ret;
         },

package/dist/engine-wasm/wasm/lix_engine.wasm.d.ts

@@ -7,6 +7,7 @@ export const lix_close: (a: number) => any;
 export const lix_createVersion: (a: number, b: any) => any;
 export const lix_execute: (a: number, b: any, c: any) => any;
 export const lix_mergeVersion: (a: number, b: any) => any;
+export const lix_mergeVersionPreview: (a: number, b: any) => any;
 export const lix_switchVersion: (a: number, b: any) => any;
 export const openLix: (a: number) => any;
 export const wasm_bindgen__closure__destroy__h259bf120b5b35fc5: (a: number, b: number) => void;

package/dist/open-lix.d.ts

@@ -30,8 +30,7 @@ export declare class Row {
     toValueMap(): Record<string, Value>;
     private availableColumns;
 }
-export type TransactionBeginMode = "read" | "write" | "deferred";
-export type KvScanRange = {
+export type BackendKvScanRange = {
     kind: "prefix";
     prefix: Uint8Array;
 } | {
@@ -39,22 +38,78 @@ export type KvScanRange = {
     start: Uint8Array;
     end: Uint8Array;
 };
-export type KvPair = {
+export type BackendKvGetRequest = {
+    groups: BackendKvGetGroup[];
+};
+export type BackendKvGetGroup = {
+    namespace: string;
+    keys: Uint8Array[];
+};
+export type BackendKvValueBatch = {
+    groups: BackendKvValueGroup[];
+};
+export type BackendKvValueGroup = {
+    namespace: string;
+    values: Array<Uint8Array | null>;
+};
+export type BackendKvExistsBatch = {
+    groups: BackendKvExistsGroup[];
+};
+export type BackendKvExistsGroup = {
+    namespace: string;
+    exists: boolean[];
+};
+export type BackendKvScanRequest = {
+    namespace: string;
+    range: BackendKvScanRange;
+    after?: Uint8Array | null;
+    limit: number;
+};
+export type BackendKvKeyPage = {
+    keys: Uint8Array[];
+    resumeAfter?: Uint8Array | null;
+};
+export type BackendKvValuePage = {
+    values: Uint8Array[];
+    resumeAfter?: Uint8Array | null;
+};
+export type BackendKvEntryPage = {
+    keys: Uint8Array[];
+    values: Uint8Array[];
+    resumeAfter?: Uint8Array | null;
+};
+export type BackendKvPut = {
     key: Uint8Array;
     value: Uint8Array;
 };
-export type LixBackendTransaction = {
-    kvGet(namespace: string, key: Uint8Array): Uint8Array | null | undefined;
-    kvScan(namespace: string, range: KvScanRange, limit?: number | null): KvPair[];
-    kvPut(namespace: string, key: Uint8Array, value: Uint8Array): void;
-    kvDelete(namespace: string, key: Uint8Array): void;
-    commit(): void;
+export type BackendKvWriteBatch = {
+    groups: BackendKvWriteGroup[];
+};
+export type BackendKvWriteGroup = {
+    namespace: string;
+    puts: BackendKvPut[];
+    deletes: Uint8Array[];
+};
+export type BackendKvWriteStats = {
+    puts: number;
+    deletes: number;
+    bytesWritten: number;
+};
+export type LixBackendReadTransaction = {
+    getValues(request: BackendKvGetRequest): BackendKvValueBatch;
+    existsMany(request: BackendKvGetRequest): BackendKvExistsBatch;
+    scanKeys(request: BackendKvScanRequest): BackendKvKeyPage;
+    scanValues(request: BackendKvScanRequest): BackendKvValuePage;
+    scanEntries(request: BackendKvScanRequest): BackendKvEntryPage;
     rollback(): void;
 };
+export type LixBackendWriteTransaction = LixBackendReadTransaction & {
+    writeKvBatch(batch: BackendKvWriteBatch): BackendKvWriteStats;
+    commit(): void;
+};
 export type LixBackend = {
-    beginTransaction(mode: TransactionBeginMode): LixBackendTransaction;
-    kvGet?(namespace: string, key: Uint8Array): Uint8Array | null | undefined;
-    kvScan?(namespace: string, range: KvScanRange, limit?: number | null): KvPair[];
+    beginReadTransaction(): LixBackendReadTransaction;
+    beginWriteTransaction(): LixBackendWriteTransaction;
     close?(): void;
 };
 export type OpenLixOptions = {
@@ -82,15 +137,48 @@ export type MergeVersionOptions = {
 };
 export type MergeVersionOutcome = "alreadyUpToDate" | "fastForward" | "mergeCommitted";
 export type MergeVersionResult = {
+    /**
+     * How the merge was applied. `fastForward` advances the target ref without
+     * creating a merge commit, but can still make source changes visible.
+     */
     outcome: MergeVersionOutcome;
     targetVersionId: string;
     sourceVersionId: string;
-    mergeBaseCommitId: string | null;
+    baseCommitId: string;
     targetHeadBeforeCommitId: string;
     sourceHeadBeforeCommitId: string;
     targetHeadAfterCommitId: string;
     createdMergeCommitId: string | null;
-    appliedChangeCount: number;
+    changeStats: MergeChangeStats;
+};
+export type MergeVersionPreviewResult = {
+    outcome: MergeVersionOutcome;
+    targetVersionId: string;
+    sourceVersionId: string;
+    baseCommitId: string;
+    targetHeadCommitId: string;
+    sourceHeadCommitId: string;
+    changeStats: MergeChangeStats;
+    conflicts: MergeConflict[];
+};
+export type MergeChangeStats = {
+    total: number;
+    added: number;
+    modified: number;
+    removed: number;
+};
+export type MergeConflict = {
+    kind: "sameEntityChanged";
+    schemaKey: string;
+    entityId: string;
+    fileId: string | null;
+    target: MergeConflictSide;
+    source: MergeConflictSide;
+};
+export type MergeConflictSide = {
+    kind: "added" | "modified" | "removed";
+    beforeChangeId: string | null;
+    afterChangeId: string | null;
 };
 export type Lix = {
     /**
@@ -105,6 +193,7 @@ export type Lix = {
     activeVersionId(): Promise<string>;
     createVersion(options: CreateVersionOptions): Promise<CreateVersionResult>;
     switchVersion(options: SwitchVersionOptions): Promise<SwitchVersionResult>;
+    mergeVersionPreview(options: MergeVersionOptions): Promise<MergeVersionPreviewResult>;
     mergeVersion(options: MergeVersionOptions): Promise<MergeVersionResult>;
     close(): Promise<void>;
 };

package/dist/open-lix.js

@@ -134,6 +134,9 @@ function createLixHandle(wasmLix) {
         async switchVersion(options) {
             return await runQueued(() => wasmLix.switchVersion(options));
         },
+        async mergeVersionPreview(options) {
+            return await runQueued(() => wasmLix.mergeVersionPreview(options));
+        },
         async mergeVersion(options) {
             return await runQueued(() => wasmLix.mergeVersion(options));
         },

package/dist/sqlite/index.js

@@ -51,21 +51,21 @@ class BetterSqlite3Backend {
         this.#db = db;
         this.#registryKey = registryKey;
     }
-    beginTransaction(mode) {
+    beginReadTransaction() {
         this.#ensureOpen();
         if (this.#db.inTransaction) {
             throw new Error("cannot open nested Lix backend transaction");
         }
-        this.#db.exec(mode === "write" ? "BEGIN IMMEDIATE" : "BEGIN DEFERRED");
+        this.#db.exec("BEGIN DEFERRED");
         return new BetterSqlite3Transaction(this.#db);
     }
-    kvGet(namespace, key) {
+    beginWriteTransaction() {
         this.#ensureOpen();
-        return kvGet(this.#db, namespace, key);
-    }
-    kvScan(namespace, range, limit) {
-        this.#ensureOpen();
-        return kvScan(this.#db, namespace, range, limit);
+        if (this.#db.inTransaction) {
+            throw new Error("cannot open nested Lix backend transaction");
+        }
+        this.#db.exec("BEGIN IMMEDIATE");
+        return new BetterSqlite3Transaction(this.#db);
     }
     close() {
         if (this.#closed)
@@ -92,27 +92,59 @@ class BetterSqlite3Transaction {
     constructor(db) {
         this.#db = db;
     }
-    kvGet(namespace, key) {
+    getValues(request) {
+        this.#ensureOpen();
+        return getValues(this.#db, request);
+    }
+    existsMany(request) {
         this.#ensureOpen();
-        return kvGet(this.#db, namespace, key);
+        return existsMany(this.#db, request);
     }
-    kvScan(namespace, range, limit) {
+    scanKeys(request) {
         this.#ensureOpen();
-        return kvScan(this.#db, namespace, range, limit);
+        const { pairs, resumeAfter } = scanPage(this.#db, request);
+        return {
+            keys: pairs.map(({ key }) => key),
+            resumeAfter,
+        };
     }
-    kvPut(namespace, key, value) {
+    scanValues(request) {
         this.#ensureOpen();
-        this.#db
-            .prepare(`INSERT INTO lix_kv (namespace, key, value)
-				 VALUES (?, ?, ?)
-				 ON CONFLICT(namespace, key) DO UPDATE SET value = excluded.value`)
-            .run(namespace, sqliteBytes(key), sqliteBytes(value));
+        const { pairs, resumeAfter } = scanPage(this.#db, request);
+        return {
+            values: pairs.map(({ value }) => value),
+            resumeAfter,
+        };
     }
-    kvDelete(namespace, key) {
+    scanEntries(request) {
         this.#ensureOpen();
-        this.#db
-            .prepare("DELETE FROM lix_kv WHERE namespace = ? AND key = ?")
-            .run(namespace, sqliteBytes(key));
+        const { pairs, resumeAfter } = scanPage(this.#db, request);
+        return {
+            keys: pairs.map(({ key }) => key),
+            values: pairs.map(({ value }) => value),
+            resumeAfter,
+        };
+    }
+    writeKvBatch(batch) {
+        this.#ensureOpen();
+        const stats = {
+            puts: 0,
+            deletes: 0,
+            bytesWritten: 0,
+        };
+        for (const group of batch.groups) {
+            for (const put of group.puts) {
+                stats.puts += 1;
+                stats.bytesWritten += put.key.length + put.value.length;
+                kvPut(this.#db, group.namespace, put.key, put.value);
+            }
+            for (const key of group.deletes) {
+                stats.deletes += 1;
+                stats.bytesWritten += key.length;
+                kvDelete(this.#db, group.namespace, key);
+            }
+        }
+        return stats;
     }
     commit() {
         this.#ensureOpen();
@@ -130,6 +162,34 @@ class BetterSqlite3Transaction {
         }
     }
 }
+function getValues(db, request) {
+    return {
+        groups: request.groups.map((group) => ({
+            namespace: group.namespace,
+            values: group.keys.map((key) => kvGet(db, group.namespace, key)),
+        })),
+    };
+}
+function existsMany(db, request) {
+    return {
+        groups: request.groups.map((group) => ({
+            namespace: group.namespace,
+            exists: group.keys.map((key) => kvGet(db, group.namespace, key) !== null),
+        })),
+    };
+}
+function scanPage(db, request) {
+    const scanLimit = request.limit + 1 + (request.after ? 1 : 0);
+    const pairs = kvScan(db, request.namespace, request.range, scanLimit).filter((pair) => !request.after || compareBytes(pair.key, request.after) > 0);
+    const hasMore = pairs.length > request.limit;
+    const pagePairs = pairs.slice(0, request.limit);
+    return {
+        pairs: pagePairs,
+        resumeAfter: hasMore
+            ? (pagePairs.at(-1)?.key ?? null)
+            : null,
+    };
+}
 function kvGet(db, namespace, key) {
     const row = db
         .prepare("SELECT value FROM lix_kv WHERE namespace = ? AND key = ?")
@@ -139,6 +199,14 @@ function kvGet(db, namespace, key) {
     }
     return bytesFromUnknown(row.value, "lix_kv.value");
 }
+function kvPut(db, namespace, key, value) {
+    db.prepare(`INSERT INTO lix_kv (namespace, key, value)
+		 VALUES (?, ?, ?)
+		 ON CONFLICT(namespace, key) DO UPDATE SET value = excluded.value`).run(namespace, sqliteBytes(key), sqliteBytes(value));
+}
+function kvDelete(db, namespace, key) {
+    db.prepare("DELETE FROM lix_kv WHERE namespace = ? AND key = ?").run(namespace, sqliteBytes(key));
+}
 function kvScan(db, namespace, range, limit) {
     const { sql, params } = scanQuery(namespace, range, limit);
     return db.prepare(sql).all(...params).map((row) => {
@@ -174,6 +242,15 @@ function scanQuery(namespace, range, limit) {
     }
     return { sql, params };
 }
+function compareBytes(left, right) {
+    const length = Math.min(left.length, right.length);
+    for (let index = 0; index < length; index++) {
+        const delta = left[index] - right[index];
+        if (delta !== 0)
+            return delta;
+    }
+    return left.length - right.length;
+}
 function prefixUpperBound(prefix) {
     const end = new Uint8Array(prefix);
     for (let index = end.length - 1; index >= 0; index--) {

package/dist-engine-src/README.md

@@ -0,0 +1,18 @@
+# Bundled Lix Engine Source
+
+This directory is a generated snapshot of the Rust engine source that backs this @lix-js/sdk release.
+
+Source in the Lix monorepo: `packages/engine/src`
+
+Agents should inspect these files when SDK behavior is unclear instead of relying only on SKILL.md prose.
+
+Useful entry points:
+
+- `src/sql2/entity_provider.rs` - registered schema SQL surfaces
+- `src/sql2/change_provider.rs` - `lix_change` projection
+- `src/sql2/version_provider.rs` - writable `lix_version` surface
+- `src/transaction/validation.rs` - primary-key, unique, foreign-key, and shape validation
+- `src/schema/definition.json` - Lix schema-definition meta-schema
+- `src/schema/builtin/` - built-in schema definitions
+
+Regenerate with `pnpm --filter @lix-js/sdk sync:engine-src` from the repo root.