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

package/SKILL.md

@@ -45,7 +45,7 @@ Do not use this skill for raw SQLite access, private engine/wasm internals, SDK
 
 1. Install `@lix-js/sdk` and `better-sqlite3`.
 2. Open with `createBetterSqlite3Backend({ path })`; do not open `.lix` with raw SQLite.
-3. Register a schema with `x-lix-key`, `x-lix-version`, `x-lix-primary-key`, and `additionalProperties: false`.
+3. Register a schema with `x-lix-key`, `x-lix-primary-key`, and `additionalProperties: false`.
 4. Write rows through the generated table named by `x-lix-key`.
 5. Use `<schema>_by_version` plus `lixcol_version_id` for side-by-side version reads/writes.
 6. Query `lix_change` for audit/history instead of hand-rolling audit tables.
@@ -57,6 +57,7 @@ Do not use this skill for raw SQLite access, private engine/wasm internals, SDK
 - Use `createBetterSqlite3Backend()` for persistent apps, demos, and tests.
 - Use numbered SQL placeholders: `$1`, `$2`, `$3`; bare `?` is rejected.
 - Use `lix_json($1)` when inserting JSON text into JSON-typed columns.
+- Use scalar SQL functions `SELECT lix_uuid_v7()` and `SELECT lix_timestamp()` when consumer code needs Lix-generated UUID v7 ids or ISO timestamps. Do not call them as table functions with `SELECT * FROM ...`.
 - Use stable, namespaced, lowercase schema keys like `acme_section`, not generic names like `task`.
 - Always include `x-lix-primary-key` and `additionalProperties: false` on app schemas.
 - Use version names from the user's vocabulary, such as `"Marketing edit"` or `"Q3 pricing draft"`.
@@ -134,7 +135,6 @@ await lix.execute(
     JSON.stringify({
       $schema: "https://json-schema.org/draft/2020-12/schema",
       "x-lix-key": "acme_note",
-      "x-lix-version": "1",
       "x-lix-primary-key": ["/id"],
       type: "object",
       required: ["id", "title", "done"],
@@ -217,7 +217,7 @@ await lix.execute(
 Schema basics:
 
 - `x-lix-key` becomes the generated SQL table name.
-- `x-lix-version` versions your schema contract.
+- Compatible schema amendments are keyed by `x-lix-key`.
 - `x-lix-primary-key` tells Lix how to derive entity identity.
 - Primary-key entries are JSON Pointers with a leading slash, such as `["/id"]` or `["/owner/email"]`.
 - Use `additionalProperties: false` so accidental fields fail fast.
@@ -229,7 +229,6 @@ Uniqueness is not inferred from ordinary JSON Schema fields. If a non-primary-ke
 ```ts
 const companyDomainSchema = {
   "x-lix-key": "crm_company_domain",
-  "x-lix-version": "1",
   "x-lix-primary-key": ["/id"],
   "x-lix-unique": [["/domain"]],
   type: "object",
@@ -389,7 +388,7 @@ Columns consumers usually need:
 
 `lix_change` is an immutable SQL table of changes across registered schemas and versions. Use it for audit logs, blame, history, activity feeds, and undo-style UI.
 
-Important columns include `id`, `entity_id`, `schema_key`, `schema_version`, `snapshot_content`, `created_at`, and `lixcol_*` metadata.
+Important columns include `id`, `entity_id`, `schema_key`, `snapshot_content`, `created_at`, and `lixcol_*` metadata.
 
 ```ts
 // Audit log for one entity, oldest to newest.

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

@@ -430,7 +430,7 @@ function __wbg_get_imports() {
             return ret;
         },
         __wbindgen_cast_0000000000000001: function (arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 3067, function: Function { arguments: [Externref], shim_idx: 3068, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 3074, function: Function { arguments: [Externref], shim_idx: 3075, 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/generated/builtin-schemas.d.ts

@@ -1,6 +1,5 @@
 export declare const LixAccountSchema: {
     readonly "x-lix-key": "lix_account";
-    readonly "x-lix-version": "1";
     readonly "x-lix-primary-key": readonly ["/id"];
     readonly type: "object";
     readonly properties: {
@@ -17,7 +16,6 @@ export declare const LixAccountSchema: {
 };
 export declare const LixActiveAccountSchema: {
     readonly "x-lix-key": "lix_active_account";
-    readonly "x-lix-version": "1";
     readonly "x-lix-primary-key": readonly ["/account_id"];
     readonly "x-lix-foreign-keys": readonly [{
         readonly properties: readonly ["/account_id"];
@@ -37,7 +35,6 @@ export declare const LixActiveAccountSchema: {
 };
 export declare const LixBinaryBlobRefSchema: {
     readonly "x-lix-key": "lix_binary_blob_ref";
-    readonly "x-lix-version": "1";
     readonly description: "Metadata pointer from a file version to its binary payload in internal CAS storage.";
     readonly "x-lix-primary-key": readonly ["/id"];
     readonly type: "object";
@@ -61,28 +58,27 @@ 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.";
+    readonly description: "A change records one edit to a Lix entity, including what changed, when it changed, and which entity was affected.";
     readonly "x-lix-primary-key": readonly ["/id"];
     readonly type: "object";
     readonly properties: {
         readonly id: {
             readonly type: "string";
             readonly "x-lix-default": "lix_uuid_v7()";
-            readonly description: "Stable change identifier (UUIDv7). Referenced from `lix_commit.change_ids` and `lix_change_set_element.change_id`.";
+            readonly description: "Stable identifier for this change.";
         };
         readonly entity_id: {
-            readonly type: "string";
-            readonly description: "The entity this change applies to, scoped by (`schema_key`, `file_id`).";
+            readonly type: "array";
+            readonly description: "Canonical JSON primary-key tuple for the entity this change applies to, scoped by (`schema_key`, `file_id`). Values are ordered according to the target schema's `x-lix-primary-key`.";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly minItems: 1;
         };
         readonly schema_key: {
             readonly type: "string";
             readonly description: "Schema identifier of the entity (e.g. `lix_file_descriptor`, `lix_commit`, or a user-registered key).";
         };
-        readonly schema_version: {
-            readonly type: "string";
-            readonly description: "Schema version the snapshot_content was written against (matches `x-lix-version` on the schema at write time).";
-        };
         readonly file_id: {
             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).";
@@ -93,6 +89,7 @@ export declare const LixChangeSchema: {
         };
         readonly created_at: {
             readonly type: "string";
+            readonly examples: readonly ["2026-05-08T17:42:31.123Z"];
             readonly description: "ISO-8601 timestamp at which the change was recorded (set via `lix_timestamp()` at write time).";
         };
         readonly snapshot_content: {
@@ -100,12 +97,11 @@ export declare const LixChangeSchema: {
             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", "created_at"];
+    readonly required: readonly ["id", "entity_id", "schema_key", "file_id", "created_at"];
     readonly additionalProperties: false;
 };
 export declare const LixChangeAuthorSchema: {
     readonly "x-lix-key": "lix_change_author";
-    readonly "x-lix-version": "1";
     readonly "x-lix-primary-key": readonly ["/change_id", "/account_id"];
     readonly "x-lix-foreign-keys": readonly [{
         readonly properties: readonly ["/change_id"];
@@ -132,120 +128,38 @@ export declare const LixChangeAuthorSchema: {
     readonly required: readonly ["change_id", "account_id"];
     readonly additionalProperties: false;
 };
-export declare const LixChangeSetSchema: {
-    readonly "x-lix-key": "lix_change_set";
-    readonly "x-lix-version": "1";
-    readonly "x-lix-primary-key": readonly ["/id"];
-    readonly type: "object";
-    readonly properties: {
-        readonly id: {
-            readonly type: "string";
-            readonly "x-lix-default": "lix_uuid_v7()";
-        };
-    };
-    readonly required: readonly ["id"];
-    readonly additionalProperties: false;
-};
-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 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 [{
-        readonly properties: readonly ["/change_set_id"];
-        readonly references: {
-            readonly schemaKey: "lix_change_set";
-            readonly properties: readonly ["/id"];
-        };
-    }, {
-        readonly properties: readonly ["/change_id"];
-        readonly references: {
-            readonly schemaKey: "lix_change";
-            readonly properties: readonly ["/id"];
-        };
-    }];
-    readonly type: "object";
-    readonly properties: {
-        readonly change_set_id: {
-            readonly type: "string";
-            readonly description: "The change_set this element belongs to (references `lix_change_set.id`).";
-        };
-        readonly change_id: {
-            readonly type: "string";
-            readonly description: "The canonical change introduced/adopted by the change_set's commit (references `lix_change.id`).";
-        };
-        readonly entity_id: {
-            readonly type: "string";
-            readonly description: "Denormalized from the referenced `lix_change` for fast entity-scoped queries and to anchor the unique constraint.";
-        };
-        readonly schema_key: {
-            readonly type: "string";
-            readonly description: "Denormalized schema identifier from the referenced `lix_change`; part of the per-change_set uniqueness tuple.";
-        };
-        readonly file_id: {
-            readonly type: readonly ["string", "null"];
-            readonly description: "Denormalized file scope from the referenced `lix_change`; NULL for engine-internal entities. Part of the per-change_set uniqueness tuple.";
-        };
-    };
-    readonly required: readonly ["change_set_id", "change_id", "entity_id", "schema_key", "file_id"];
-    readonly additionalProperties: false;
-};
 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 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"];
-        readonly references: {
-            readonly schemaKey: "lix_change_set";
-            readonly properties: readonly ["/id"];
-        };
+    readonly description: "A commit is a stable point in project history. Versions point to commits. Use lix_commit_edge to inspect parent commits.";
+    readonly examples: readonly [{
+        readonly id: "commit_01jexample";
     }];
+    readonly "x-lix-primary-key": readonly ["/id"];
     readonly type: "object";
     readonly properties: {
         readonly id: {
             readonly type: "string";
             readonly "x-lix-default": "lix_uuid_v7()";
-            readonly description: "Stable commit identifier.";
-        };
-        readonly change_set_id: {
-            readonly type: "string";
-            readonly description: "Commit-local grouping identifier used by derived relational indexes and projections such as lix_change_set_element.";
-        };
-        readonly change_ids: {
-            readonly type: "array";
-            readonly default: readonly [];
-            readonly items: {
-                readonly type: "string";
-            };
-            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";
-            readonly default: readonly [];
-            readonly items: {
-                readonly type: "string";
-            };
-            readonly description: "Ordered set of author account IDs associated with this commit.";
-        };
-        readonly parent_commit_ids: {
-            readonly type: "array";
-            readonly default: readonly [];
-            readonly items: {
-                readonly type: "string";
-            };
-            readonly description: "Parent commit IDs for commit graph topology.";
+            readonly description: "Stable identifier of this commit.";
         };
     };
-    readonly required: readonly ["id", "change_set_id"];
+    readonly required: readonly ["id"];
     readonly additionalProperties: false;
 };
 export declare const LixCommitEdgeSchema: {
     readonly "x-lix-key": "lix_commit_edge";
-    readonly "x-lix-version": "1";
-    readonly "x-lix-primary-key": readonly ["/parent_id", "/child_id"];
+    readonly description: "Direct parent relationship between two commits. Merge commits have one row per parent. The first parent is useful for showing mainline history or comparing a merge commit against the commit that was checked out before the merge.";
+    readonly examples: readonly [{
+        readonly parent_id: "commit-main";
+        readonly child_id: "commit-merge";
+        readonly parent_order: 0;
+    }, {
+        readonly parent_id: "commit-feature";
+        readonly child_id: "commit-merge";
+        readonly parent_order: 1;
+    }];
+    readonly "x-lix-primary-key": readonly ["/child_id", "/parent_order"];
+    readonly "x-lix-unique": readonly [readonly ["/parent_id", "/child_id"]];
     readonly "x-lix-foreign-keys": readonly [{
         readonly properties: readonly ["/parent_id"];
         readonly references: {
@@ -263,17 +177,24 @@ export declare const LixCommitEdgeSchema: {
     readonly properties: {
         readonly parent_id: {
             readonly type: "string";
+            readonly description: "Identifier of the parent commit.";
         };
         readonly child_id: {
             readonly type: "string";
+            readonly description: "Identifier of the child commit.";
+        };
+        readonly parent_order: {
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly examples: readonly [0, 1];
+            readonly description: "Zero-based position of this parent in the child commit's ordered parent list. The first parent has order 0; additional merge parents have order 1, 2, and so on.";
         };
     };
-    readonly required: readonly ["parent_id", "child_id"];
+    readonly required: readonly ["parent_id", "child_id", "parent_order"];
     readonly additionalProperties: false;
 };
 export declare const LixDirectoryDescriptorSchema: {
     readonly "x-lix-key": "lix_directory_descriptor";
-    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 [{
@@ -304,44 +225,8 @@ export declare const LixDirectoryDescriptorSchema: {
     readonly required: readonly ["id", "parent_id", "name"];
     readonly additionalProperties: false;
 };
-export declare const LixEntityLabelSchema: {
-    readonly "x-lix-key": "lix_entity_label";
-    readonly "x-lix-version": "1";
-    readonly "x-lix-primary-key": readonly ["/entity_id", "/schema_key", "/file_id", "/label_id"];
-    readonly "x-lix-foreign-keys": readonly [{
-        readonly properties: readonly ["/entity_id", "/schema_key", "/file_id"];
-        readonly references: {
-            readonly schemaKey: "lix_state";
-            readonly properties: readonly ["/entity_id", "/schema_key", "/file_id"];
-        };
-    }, {
-        readonly properties: readonly ["/label_id"];
-        readonly references: {
-            readonly schemaKey: "lix_label";
-            readonly properties: readonly ["/id"];
-        };
-    }];
-    readonly type: "object";
-    readonly properties: {
-        readonly entity_id: {
-            readonly type: "string";
-        };
-        readonly schema_key: {
-            readonly type: "string";
-        };
-        readonly file_id: {
-            readonly type: readonly ["string", "null"];
-        };
-        readonly label_id: {
-            readonly type: "string";
-        };
-    };
-    readonly required: readonly ["entity_id", "schema_key", "file_id", "label_id"];
-    readonly additionalProperties: false;
-};
 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"]];
     readonly "x-lix-foreign-keys": readonly [{
@@ -374,7 +259,6 @@ export declare const LixFileDescriptorSchema: {
 };
 export declare const LixKeyValueSchema: {
     readonly "x-lix-key": "lix_key_value";
-    readonly "x-lix-version": "1";
     readonly "x-lix-primary-key": readonly ["/key"];
     readonly type: "object";
     readonly properties: {
@@ -403,25 +287,71 @@ export declare const LixKeyValueSchema: {
 };
 export declare const LixLabelSchema: {
     readonly "x-lix-key": "lix_label";
-    readonly "x-lix-version": "1";
+    readonly description: "Catalog of labels that can be assigned to arbitrary live Lix rows through lix_label_assignment.";
     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 label identifier. Label assignments reference this value.";
         };
         readonly name: {
             readonly type: "string";
+            readonly description: "Human-readable label name. Unique across labels.";
         };
     };
     readonly required: readonly ["id", "name"];
     readonly additionalProperties: false;
 };
+export declare const LixLabelAssignmentSchema: {
+    readonly "x-lix-key": "lix_label_assignment";
+    readonly description: "Mapping table that assigns a label to any live Lix row addressed by (target_entity_id, target_schema_key, target_file_id). The state foreign-key tuple is ordered as [0] target_entity_id, [1] target_schema_key, [2] target_file_id.";
+    readonly "x-lix-primary-key": readonly ["/id"];
+    readonly "x-lix-unique": readonly [readonly ["/target_entity_id", "/target_schema_key", "/target_file_id", "/label_id"]];
+    readonly "x-lix-state-foreign-keys": readonly [readonly ["/target_entity_id", "/target_schema_key", "/target_file_id"]];
+    readonly "x-lix-foreign-keys": readonly [{
+        readonly properties: readonly ["/label_id"];
+        readonly references: {
+            readonly schemaKey: "lix_label";
+            readonly properties: readonly ["/id"];
+        };
+    }];
+    readonly type: "object";
+    readonly properties: {
+        readonly id: {
+            readonly type: "string";
+            readonly "x-lix-default": "lix_uuid_v7()";
+            readonly description: "Stable identifier for this label assignment row.";
+        };
+        readonly target_entity_id: {
+            readonly type: "array";
+            readonly description: "Target row entity_id. This is slot [0] in x-lix-state-foreign-keys and must be the canonical JSON array of string primary-key parts.";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly minItems: 1;
+        };
+        readonly target_schema_key: {
+            readonly type: "string";
+            readonly description: "Target row schema key. This is slot [1] in x-lix-state-foreign-keys.";
+        };
+        readonly target_file_id: {
+            readonly type: readonly ["string", "null"];
+            readonly description: "Target row file scope. This is slot [2] in x-lix-state-foreign-keys; null targets global rows.";
+        };
+        readonly label_id: {
+            readonly type: "string";
+            readonly description: "Label assigned to the target row. References lix_label.id.";
+        };
+    };
+    readonly required: readonly ["id", "target_entity_id", "target_schema_key", "target_file_id", "label_id"];
+    readonly additionalProperties: false;
+};
 export declare const LixRegisteredSchemaSchema: {
     readonly "x-lix-key": "lix_registered_schema";
-    readonly "x-lix-version": "1";
-    readonly "x-lix-primary-key": readonly ["/value/x-lix-key", "/value/x-lix-version"];
+    readonly "x-lix-primary-key": readonly ["/value/x-lix-key"];
     readonly type: "object";
     readonly properties: {
         readonly value: {
@@ -430,11 +360,8 @@ export declare const LixRegisteredSchemaSchema: {
                 readonly "x-lix-key": {
                     readonly type: "string";
                 };
-                readonly "x-lix-version": {
-                    readonly type: "string";
-                };
             };
-            readonly required: readonly ["x-lix-key", "x-lix-version"];
+            readonly required: readonly ["x-lix-key"];
             readonly additionalProperties: true;
         };
     };
@@ -443,7 +370,6 @@ export declare const LixRegisteredSchemaSchema: {
 };
 export declare const LixVersionDescriptorSchema: {
     readonly "x-lix-key": "lix_version_descriptor";
-    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"]];
@@ -469,7 +395,6 @@ export declare const LixVersionDescriptorSchema: {
 };
 export declare const LixVersionRefSchema: {
     readonly "x-lix-key": "lix_version_ref";
-    readonly "x-lix-version": "1";
     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 [{