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

package/dist/engine-wasm/index.js

@@ -16,22 +16,25 @@ export class Value {
         if (!Number.isFinite(value) || !Number.isInteger(value)) {
             throw new TypeError("Value.integer() requires a finite integer number");
         }
-        return new Value("int", value);
+        return new Value("integer", value);
     }
     static boolean(value) {
-        return new Value("bool", value);
+        return new Value("boolean", value);
     }
     static real(value) {
         if (!Number.isFinite(value)) {
             throw new TypeError("Value.real() requires a finite number");
         }
-        return new Value("float", value);
+        return new Value("real", value);
     }
     static text(value) {
+        if (!isWellFormedUtf16(value)) {
+            throw new TypeError("Value.text() requires a well-formed UTF-16 string");
+        }
         return new Value("text", value);
     }
     static json(value) {
-        return new Value("json", value);
+        return new Value("json", normalizeJsonValue(value));
     }
     static blob(value) {
         return new Value("blob", undefined, bytesToBase64(value));
@@ -43,22 +46,25 @@ export class Value {
             switch (raw.kind) {
                 case "null":
                     return Value.null();
-                case "bool":
+                case "boolean":
                     return Value.boolean(raw.value);
-                case "int":
+                case "integer":
                     return Value.integer(raw.value);
-                case "float":
+                case "real":
                     return Value.real(raw.value);
                 case "text":
                     return Value.text(raw.value);
                 case "json":
-                    return Value.json(raw.value);
+                    return Value.json(normalizeJsonValue(raw.value));
                 case "blob":
                     return new Value("blob", undefined, raw.base64);
             }
         }
-        if (raw === null || raw === undefined)
+        if (raw === null)
             return Value.null();
+        if (raw === undefined) {
+            throw new TypeError("undefined is not a valid SQL parameter");
+        }
         if (typeof raw === "number") {
             return Number.isInteger(raw) ? Value.integer(raw) : Value.real(raw);
         }
@@ -71,29 +77,30 @@ export class Value {
         if (raw instanceof ArrayBuffer)
             return Value.blob(new Uint8Array(raw));
         if (ArrayBuffer.isView(raw)) {
-            return Value.blob(new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength));
+            throw new TypeError("typed array SQL parameters must be Uint8Array; other ArrayBuffer views are ambiguous");
+        }
+        if (raw instanceof Date) {
+            throw new TypeError("Date is not a valid SQL parameter; pass date.toISOString() or date.getTime() explicitly");
+        }
+        if (raw && typeof raw === "object") {
+            return Value.json(normalizeJsonValue(raw));
         }
-        if (isJsonValue(raw))
-            return Value.json(raw);
         throw new TypeError("Value.from() requires a LixValue, JSON value, or binary value");
     }
-    kindValue() {
-        return this.kind;
-    }
     asInteger() {
-        return this.kind === "int" ? this.value : undefined;
+        return this.kind === "integer" ? this.value : undefined;
     }
     asBoolean() {
-        return this.kind === "bool" ? this.value : undefined;
+        return this.kind === "boolean" ? this.value : undefined;
     }
     asReal() {
-        return this.kind === "float" ? this.value : undefined;
+        return this.kind === "real" ? this.value : undefined;
     }
     asText() {
         return this.kind === "text" ? this.value : undefined;
     }
     asJson() {
-        return this.kind === "json" ? this.value : undefined;
+        return this.kind === "json" ? normalizeJsonValue(this.value) : undefined;
     }
     asBlob() {
         return this.kind === "blob" && this.base64 !== undefined
@@ -104,12 +111,12 @@ export class Value {
         switch (this.kind) {
             case "null":
                 return { kind: "null", value: null };
-            case "bool":
-                return { kind: "bool", value: this.asBoolean() ?? false };
-            case "int":
-                return { kind: "int", value: this.asInteger() ?? 0 };
-            case "float":
-                return { kind: "float", value: this.asReal() ?? 0 };
+            case "boolean":
+                return { kind: "boolean", value: this.asBoolean() ?? false };
+            case "integer":
+                return { kind: "integer", value: this.asInteger() ?? 0 };
+            case "real":
+                return { kind: "real", value: this.asReal() ?? 0 };
             case "text":
                 return { kind: "text", value: this.asText() ?? "" };
             case "json":
@@ -121,12 +128,12 @@ export class Value {
 }
 /**
  * Type guard: returns `true` when `err` is a Lix-produced error carrying a
- * structured `code` field (all engine codes start with `LIX_ERROR_`).
+ * structured `code` field (all engine codes start with `LIX_`).
  */
 export function isLixError(err) {
     return (err instanceof Error &&
         typeof err.code === "string" &&
-        err.code.startsWith("LIX_ERROR"));
+        err.code.startsWith("LIX_"));
 }
 function isLixValue(value) {
     if (!value || typeof value !== "object") {
@@ -136,21 +143,22 @@ function isLixValue(value) {
     if (kind === "null") {
         return value.value === null;
     }
-    if (kind === "bool") {
+    if (kind === "boolean") {
         return typeof value.value === "boolean";
     }
-    if (kind === "int" || kind === "float") {
+    if (kind === "integer" || kind === "real") {
         const raw = value.value;
         if (typeof raw !== "number" || !Number.isFinite(raw)) {
             return false;
         }
-        if (kind === "int" && !Number.isInteger(raw)) {
+        if (kind === "integer" && !Number.isInteger(raw)) {
             return false;
         }
         return true;
     }
     if (kind === "text") {
-        return typeof value.value === "string";
+        const raw = value.value;
+        return typeof raw === "string" && isWellFormedUtf16(raw);
     }
     if (kind === "json") {
         return isJsonValue(value.value);
@@ -161,21 +169,80 @@ function isLixValue(value) {
     return false;
 }
 function isJsonValue(value) {
-    if (value === null ||
-        typeof value === "boolean" ||
-        typeof value === "string") {
+    try {
+        normalizeJsonValue(value);
         return true;
     }
+    catch {
+        return false;
+    }
+}
+function normalizeJsonValue(value, seen = new WeakSet()) {
+    if (value === null ||
+        typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "string") {
+        if (!isWellFormedUtf16(value)) {
+            throw new TypeError("JSON strings must be well-formed UTF-16");
+        }
+        return value;
+    }
     if (typeof value === "number") {
-        return Number.isFinite(value);
+        if (!Number.isFinite(value)) {
+            throw new TypeError("JSON numbers must be finite");
+        }
+        return value;
     }
     if (Array.isArray(value)) {
-        return value.every((item) => isJsonValue(item));
+        if (seen.has(value)) {
+            throw new TypeError("JSON values must not contain circular references");
+        }
+        seen.add(value);
+        const normalized = value.map((item) => normalizeJsonValue(item, seen));
+        seen.delete(value);
+        return normalized;
     }
     if (!value || typeof value !== "object") {
-        return false;
+        throw new TypeError("expected a JSON-compatible value");
+    }
+    if (value instanceof Date) {
+        throw new TypeError("Date is not a JSON value");
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new TypeError("JSON objects must be plain objects");
+    }
+    if (seen.has(value)) {
+        throw new TypeError("JSON values must not contain circular references");
+    }
+    seen.add(value);
+    const normalized = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (!isWellFormedUtf16(key)) {
+            throw new TypeError("JSON object keys must be well-formed UTF-16");
+        }
+        normalized[key] = normalizeJsonValue(entry, seen);
+    }
+    seen.delete(value);
+    return normalized;
+}
+function isWellFormedUtf16(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (next < 0xdc00 || next > 0xdfff) {
+                return false;
+            }
+            index += 1;
+            continue;
+        }
+        if (code >= 0xdc00 && code <= 0xdfff) {
+            return false;
+        }
     }
-    return Object.values(value).every((entry) => isJsonValue(entry));
+    return true;
 }
 function bytesToBase64(bytes) {
     const maybeBuffer = globalThis.Buffer;

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

@@ -22,16 +22,28 @@ export class Lix {
      */
     createVersion(args: any): Promise<any>;
     /**
-     * @param {string} sql
+     * Executes one DataFusion SQL statement against this Lix session.
+     *
+     * The SQL dialect is DataFusion SQL, not SQLite SQL. Positional
+     * placeholders use `$1`, `$2`, and so on. SQLite-specific catalog
+     * tables and transaction statements such as `sqlite_master`, `BEGIN`,
+     * and `COMMIT` are not part of this contract; use
+     * `information_schema` for catalog inspection.
+     * @param {any} sql
      * @param {any} params
      * @returns {Promise<any>}
      */
-    execute(sql: string, params: any): Promise<any>;
+    execute(sql: any, params: any): Promise<any>;
     /**
      * @param {any} args
      * @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

@@ -40,14 +40,19 @@ export class Lix {
         return ret;
     }
     /**
-     * @param {string} sql
+     * Executes one DataFusion SQL statement against this Lix session.
+     *
+     * The SQL dialect is DataFusion SQL, not SQLite SQL. Positional
+     * placeholders use `$1`, `$2`, and so on. SQLite-specific catalog
+     * tables and transaction statements such as `sqlite_master`, `BEGIN`,
+     * and `COMMIT` are not part of this contract; use
+     * `information_schema` for catalog inspection.
+     * @param {any} sql
      * @param {any} params
      * @returns {Promise<any>}
      */
     execute(sql, params) {
-        const ptr0 = passStringToWasm0(sql, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-        const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.lix_execute(this.__wbg_ptr, ptr0, len0, params);
+        const ret = wasm.lix_execute(this.__wbg_ptr, sql, params);
         return ret;
     }
     /**
@@ -58,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>}
@@ -178,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;
@@ -429,7 +430,7 @@ function __wbg_get_imports() {
             return ret;
         },
         __wbindgen_cast_0000000000000001: function (arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 2720, function: Function { arguments: [Externref], shim_idx: 2721, 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

@@ -5,8 +5,9 @@ export const __wbg_lix_free: (a: number, b: number) => void;
 export const lix_activeVersionId: (a: number) => any;
 export const lix_close: (a: number) => any;
 export const lix_createVersion: (a: number, b: any) => any;
-export const lix_execute: (a: number, b: number, c: number, d: 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/generated/builtin-schemas.d.ts

@@ -35,25 +35,6 @@ export declare const LixActiveAccountSchema: {
     readonly required: readonly ["account_id"];
     readonly additionalProperties: false;
 };
-export declare const LixActiveVersionSchema: {
-    readonly "x-lix-key": "lix_active_version";
-    readonly "x-lix-version": "1";
-    readonly description: "Singleton tracking which version is currently checked out in the local runtime. Exactly one row exists at all times; writing to this surface is how clients switch versions.";
-    readonly "x-lix-primary-key": readonly ["/id"];
-    readonly type: "object";
-    readonly properties: {
-        readonly id: {
-            readonly type: "string";
-            readonly description: "Fixed singleton key (constant, not a UUID); the primary-key column exists to satisfy entity-model requirements and enforces the one-row invariant.";
-        };
-        readonly version_id: {
-            readonly type: "string";
-            readonly description: "The currently active version; references `lix_version_descriptor.id` and drives the default scope for reads and writes in the session.";
-        };
-    };
-    readonly required: readonly ["id", "version_id"];
-    readonly additionalProperties: false;
-};
 export declare const LixBinaryBlobRefSchema: {
     readonly "x-lix-key": "lix_binary_blob_ref";
     readonly "x-lix-version": "1";
@@ -81,7 +62,7 @@ export declare const LixBinaryBlobRefSchema: {
 export declare const LixChangeSchema: {
     readonly "x-lix-key": "lix_change";
     readonly "x-lix-version": "1";
-    readonly description: "Canonical immutable change fact. This surface represents the authoritative stream of journaled change facts. Commit lineage and non-commit scope are modeled separately around these facts. The public `untracked` field is retained as convenience metadata and should not be treated as proof that trackedness is intrinsic to the canonical fact row itself.";
+    readonly description: "Canonical immutable change fact. This surface represents the authoritative stream of journaled change facts. Commit lineage and non-commit scope are modeled separately around these facts.";
     readonly "x-lix-primary-key": readonly ["/id"];
     readonly type: "object";
     readonly properties: {
@@ -106,10 +87,6 @@ export declare const LixChangeSchema: {
             readonly type: readonly ["string", "null"];
             readonly description: "Filesystem-scoped file identifier when the change belongs to a file; NULL for engine-internal entities (commits, versions, settings).";
         };
-        readonly plugin_key: {
-            readonly type: readonly ["string", "null"];
-            readonly description: "Plugin that authored the change; NULL for engine-internal changes.";
-        };
         readonly metadata: {
             readonly type: readonly ["object", "null"];
             readonly description: "Optional user-provided JSON metadata attached to the change; NULL when nothing was supplied.";
@@ -118,16 +95,12 @@ export declare const LixChangeSchema: {
             readonly type: "string";
             readonly description: "ISO-8601 timestamp at which the change was recorded (set via `lix_timestamp()` at write time).";
         };
-        readonly untracked: {
-            readonly type: "boolean";
-            readonly description: "Public convenience field indicating that the change currently participates in non-commit visibility rather than commit lineage. This is intended to become derived metadata rather than intrinsic canonical storage truth.";
-        };
         readonly snapshot_content: {
             readonly type: readonly ["object", "null"];
             readonly description: "Entity JSON body at this change; NULL represents a tombstone (deletion).";
         };
     };
-    readonly required: readonly ["id", "entity_id", "schema_key", "schema_version", "file_id", "plugin_key", "created_at", "untracked"];
+    readonly required: readonly ["id", "entity_id", "schema_key", "schema_version", "file_id", "created_at"];
     readonly additionalProperties: false;
 };
 export declare const LixChangeAuthorSchema: {
@@ -176,7 +149,7 @@ export declare const LixChangeSetSchema: {
 export declare const LixChangeSetElementSchema: {
     readonly "x-lix-key": "lix_change_set_element";
     readonly "x-lix-version": "1";
-    readonly description: "Derived relational index mapping a change_set to the canonical changes it contains. Rebuildable from `lix_commit.change_ids` plus the referenced `lix_change` rows; the unique constraint enforces at most one change per (entity, schema, file) tuple within a single change_set.";
+    readonly description: "Derived relational index mapping a change_set to the canonical changes introduced by its commit relative to the commit's first parent. Rebuildable from `lix_commit.change_ids` plus the referenced `lix_change` rows; the unique constraint enforces at most one change per (entity, schema, file) tuple within a single change_set.";
     readonly "x-lix-primary-key": readonly ["/change_set_id", "/change_id"];
     readonly "x-lix-unique": readonly [readonly ["/change_set_id", "/entity_id", "/schema_key", "/file_id"]];
     readonly "x-lix-foreign-keys": readonly [{
@@ -200,7 +173,7 @@ export declare const LixChangeSetElementSchema: {
         };
         readonly change_id: {
             readonly type: "string";
-            readonly description: "The canonical change included in the change_set (references `lix_change.id`).";
+            readonly description: "The canonical change introduced/adopted by the change_set's commit (references `lix_change.id`).";
         };
         readonly entity_id: {
             readonly type: "string";
@@ -221,7 +194,7 @@ export declare const LixChangeSetElementSchema: {
 export declare const LixCommitSchema: {
     readonly "x-lix-key": "lix_commit";
     readonly "x-lix-version": "1";
-    readonly description: "Commit header change. Canonical commit membership is stored in change_ids as the ordered list of non-header member changes for this commit. Derived projections such as lix_change_set_element must be rebuildable from this header plus the referenced change rows. Version head pointers such as lix_version_ref are maintained separately and are not commit members.";
+    readonly description: "Commit header change. Canonical commit membership is stored in change_ids as the ordered list of canonical changes whose effects this commit introduces relative to its first parent. A merge commit may reference canonical changes originally authored in another parent instead of copying them. Derived projections such as lix_change_set_element must be rebuildable from this header plus the referenced change rows. Version head pointers such as lix_version_ref are maintained separately and are not commit members.";
     readonly "x-lix-primary-key": readonly ["/id"];
     readonly "x-lix-foreign-keys": readonly [{
         readonly properties: readonly ["/change_set_id"];
@@ -247,7 +220,7 @@ export declare const LixCommitSchema: {
             readonly items: {
                 readonly type: "string";
             };
-            readonly description: "Canonical ordered membership list of non-header change IDs that belong to this commit. Derived indexes such as lix_change_set_element must be rebuildable from this list. This does not include lix_version_ref pointer rows.";
+            readonly description: "Canonical ordered membership list of non-header change IDs whose effects this commit introduces relative to its first parent. Merge commits may reference existing changes from another parent instead of minting equivalent copies. Derived indexes such as lix_change_set_element must be rebuildable from this list. This does not include lix_version_ref pointer rows.";
         };
         readonly author_account_ids: {
             readonly type: "array";
@@ -303,6 +276,13 @@ export declare const LixDirectoryDescriptorSchema: {
     readonly "x-lix-version": "1";
     readonly "x-lix-primary-key": readonly ["/id"];
     readonly "x-lix-unique": readonly [readonly ["/parent_id", "/name"]];
+    readonly "x-lix-foreign-keys": readonly [{
+        readonly properties: readonly ["/parent_id"];
+        readonly references: {
+            readonly schemaKey: "lix_directory_descriptor";
+            readonly properties: readonly ["/id"];
+        };
+    }];
     readonly type: "object";
     readonly properties: {
         readonly id: {
@@ -363,7 +343,14 @@ export declare const LixFileDescriptorSchema: {
     readonly "x-lix-key": "lix_file_descriptor";
     readonly "x-lix-version": "1";
     readonly "x-lix-primary-key": readonly ["/id"];
-    readonly "x-lix-unique": readonly [readonly ["/directory_id", "/name", "/extension"]];
+    readonly "x-lix-unique": readonly [readonly ["/directory_id", "/name"]];
+    readonly "x-lix-foreign-keys": readonly [{
+        readonly properties: readonly ["/directory_id"];
+        readonly references: {
+            readonly schemaKey: "lix_directory_descriptor";
+            readonly properties: readonly ["/id"];
+        };
+    }];
     readonly type: "object";
     readonly properties: {
         readonly id: {
@@ -375,18 +362,14 @@ export declare const LixFileDescriptorSchema: {
         };
         readonly name: {
             readonly type: "string";
-            readonly pattern: "^[^/\\\\]+$";
-        };
-        readonly extension: {
-            readonly type: readonly ["string", "null"];
-            readonly pattern: "^[^./\\\\]+$";
+            readonly pattern: "^(?!\\.{1,2}$)[^/\\\\]+$";
         };
         readonly hidden: {
             readonly type: "boolean";
             readonly "x-lix-default": "false";
         };
     };
-    readonly required: readonly ["id", "directory_id", "name", "extension"];
+    readonly required: readonly ["id", "directory_id", "name"];
     readonly additionalProperties: false;
 };
 export declare const LixKeyValueSchema: {
@@ -463,12 +446,13 @@ export declare const LixVersionDescriptorSchema: {
     readonly "x-lix-version": "1";
     readonly description: "User-facing version metadata (name and visibility) for a branch-like version. The stable identity of a version; the matching `lix_version_ref` carries the moving head pointer. The catalog's `lix_version` surface joins this descriptor with its ref to present a single user-visible version row.";
     readonly "x-lix-primary-key": readonly ["/id"];
+    readonly "x-lix-unique": readonly [readonly ["/name"]];
     readonly type: "object";
     readonly properties: {
         readonly id: {
             readonly type: "string";
             readonly "x-lix-default": "lix_uuid_v7()";
-            readonly description: "Stable version identifier (UUIDv7). Referenced by `lix_version_ref.id` and `lix_active_version.version_id`.";
+            readonly description: "Stable version identifier (UUIDv7). Referenced by `lix_version_ref.id`.";
         };
         readonly name: {
             readonly type: "string";
@@ -489,6 +473,12 @@ export declare const LixVersionRefSchema: {
     readonly description: "Version head pointer. Records which commit a version should currently resolve to in the local runtime. Intentionally not part of canonical commit membership: refs may be reset client-side after sync without introducing content conflicts. Each `lix_version_descriptor.id` has exactly one `lix_version_ref` row.";
     readonly "x-lix-primary-key": readonly ["/id"];
     readonly "x-lix-foreign-keys": readonly [{
+        readonly properties: readonly ["/id"];
+        readonly references: {
+            readonly schemaKey: "lix_version_descriptor";
+            readonly properties: readonly ["/id"];
+        };
+    }, {
         readonly properties: readonly ["/commit_id"];
         readonly references: {
             readonly schemaKey: "lix_commit";