@lix-js/sdk 0.6.0-preview.4 → 0.6.0-preview.5

package/dist/sqlite/index.js

@@ -46,6 +46,7 @@ function initializeDatabase(db) {
 class BetterSqlite3Backend {
     #db;
     #registryKey;
+    #transactionMode = null;
     #closed = false;
     constructor(db, registryKey) {
         this.#db = db;
@@ -53,19 +54,28 @@ class BetterSqlite3Backend {
     }
     beginReadTransaction() {
         this.#ensureOpen();
-        if (this.#db.inTransaction) {
-            throw new Error("cannot open nested Lix backend transaction");
-        }
-        this.#db.exec("BEGIN DEFERRED");
-        return new BetterSqlite3Transaction(this.#db);
+        return new BetterSqlite3Transaction(this.#db, {
+            ownsTransaction: false,
+            writable: false,
+        });
     }
     beginWriteTransaction() {
         this.#ensureOpen();
         if (this.#db.inTransaction) {
-            throw new Error("cannot open nested Lix backend transaction");
+            return new BetterSqlite3Transaction(this.#db, {
+                ownsTransaction: false,
+                writable: true,
+            });
         }
         this.#db.exec("BEGIN IMMEDIATE");
-        return new BetterSqlite3Transaction(this.#db);
+        this.#transactionMode = "write";
+        return new BetterSqlite3Transaction(this.#db, {
+            ownsTransaction: true,
+            writable: true,
+            onClose: () => {
+                this.#transactionMode = null;
+            },
+        });
     }
     close() {
         if (this.#closed)
@@ -88,9 +98,15 @@ class BetterSqlite3Backend {
 }
 class BetterSqlite3Transaction {
     #db;
+    #ownsTransaction;
+    #writable;
+    #onClose;
     #closed = false;
-    constructor(db) {
+    constructor(db, options) {
         this.#db = db;
+        this.#ownsTransaction = options.ownsTransaction;
+        this.#writable = options.writable;
+        this.#onClose = options.onClose;
     }
     getValues(request) {
         this.#ensureOpen();
@@ -127,34 +143,59 @@ class BetterSqlite3Transaction {
     }
     writeKvBatch(batch) {
         this.#ensureOpen();
+        if (!this.#writable) {
+            throw new Error("Lix backend transaction is read-only");
+        }
         const stats = {
             puts: 0,
             deletes: 0,
+            deleteRanges: 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);
+            for (const op of group.ops) {
+                if (op.kind === "put") {
+                    stats.puts += 1;
+                    stats.bytesWritten += op.key.length + op.value.length;
+                    kvPut(this.#db, group.namespace, op.key, op.value);
+                }
+                else if (op.kind === "delete") {
+                    stats.deletes += 1;
+                    stats.bytesWritten += op.key.length;
+                    kvDelete(this.#db, group.namespace, op.key);
+                }
+                else {
+                    stats.deleteRanges += 1;
+                    stats.bytesWritten += deleteRangeBytes(op.range);
+                    kvDeleteRange(this.#db, group.namespace, op.range);
+                }
             }
         }
         return stats;
     }
     commit() {
         this.#ensureOpen();
-        this.#db.exec("COMMIT");
-        this.#closed = true;
+        try {
+            if (this.#ownsTransaction) {
+                this.#db.exec("COMMIT");
+            }
+        }
+        finally {
+            this.#closed = true;
+            this.#onClose?.();
+        }
     }
     rollback() {
         this.#ensureOpen();
-        this.#db.exec("ROLLBACK");
-        this.#closed = true;
+        try {
+            if (this.#ownsTransaction) {
+                this.#db.exec("ROLLBACK");
+            }
+        }
+        finally {
+            this.#closed = true;
+            this.#onClose?.();
+        }
     }
     #ensureOpen() {
         if (this.#closed) {
@@ -185,9 +226,7 @@ function scanPage(db, request) {
     const pagePairs = pairs.slice(0, request.limit);
     return {
         pairs: pagePairs,
-        resumeAfter: hasMore
-            ? (pagePairs.at(-1)?.key ?? null)
-            : null,
+        resumeAfter: hasMore ? (pagePairs.at(-1)?.key ?? null) : null,
     };
 }
 function kvGet(db, namespace, key) {
@@ -207,9 +246,16 @@ function kvPut(db, namespace, key, value) {
 function kvDelete(db, namespace, key) {
     db.prepare("DELETE FROM lix_kv WHERE namespace = ? AND key = ?").run(namespace, sqliteBytes(key));
 }
+function kvDeleteRange(db, namespace, range) {
+    const { clauses, params } = rangeClauses(namespace, range);
+    db.prepare(`DELETE FROM lix_kv WHERE ${clauses.join(" AND ")}`).run(...params);
+}
 function kvScan(db, namespace, range, limit) {
     const { sql, params } = scanQuery(namespace, range, limit);
-    return db.prepare(sql).all(...params).map((row) => {
+    return db
+        .prepare(sql)
+        .all(...params)
+        .map((row) => {
         if (!isObject(row) || !("key" in row) || !("value" in row)) {
             throw new Error("invalid lix_kv scan row");
         }
@@ -220,6 +266,15 @@ function kvScan(db, namespace, range, limit) {
     });
 }
 function scanQuery(namespace, range, limit) {
+    const { clauses, params } = rangeClauses(namespace, range);
+    let sql = `SELECT key, value FROM lix_kv WHERE ${clauses.join(" AND ")} ORDER BY key`;
+    if (limit != null) {
+        sql += " LIMIT ?";
+        params.push(limit);
+    }
+    return { sql, params };
+}
+function rangeClauses(namespace, range) {
     const params = [namespace];
     const clauses = ["namespace = ?"];
     if (range.kind === "prefix") {
@@ -235,12 +290,13 @@ function scanQuery(namespace, range, limit) {
         clauses.push("key >= ?", "key < ?");
         params.push(sqliteBytes(range.start), sqliteBytes(range.end));
     }
-    let sql = `SELECT key, value FROM lix_kv WHERE ${clauses.join(" AND ")} ORDER BY key`;
-    if (limit != null) {
-        sql += " LIMIT ?";
-        params.push(limit);
+    return { clauses, params };
+}
+function deleteRangeBytes(range) {
+    if (range.kind === "prefix") {
+        return range.prefix.length;
     }
-    return { sql, params };
+    return range.start.length + range.end.length;
 }
 function compareBytes(left, right) {
     const length = Math.min(left.length, right.length);

package/dist-engine-src/README.md

@@ -8,9 +8,9 @@ Agents should inspect these files when SDK behavior is unclear instead of relyin
 
 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/sql2/providers/entity.rs` - registered schema SQL surfaces
+- `src/sql2/providers/change.rs` - `lix_change` projection
+- `src/sql2/providers/branch.rs` - writable `lix_branch` 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

package/dist-engine-src/src/backend/capabilities.rs

@@ -0,0 +1,67 @@
+use crate::backend::PredicateSupportLevel;
+
+#[derive(Clone, Debug)]
+pub struct BackendCapabilities {
+    pub profile: BackendProfile,
+    pub projection: ProjectionCapabilities,
+    pub scan: ScanCapabilities,
+    pub write: WriteCapabilities,
+    pub pushdown: PushdownCapabilities,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum BackendProfile {
+    /// Ordered byte keys, coherent read views, batched point reads,
+    /// chunked forward scans, and atomic write commit.
+    V0 { write_concurrency: WriteConcurrency },
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum WriteConcurrency {
+    SingleWriter,
+    ConcurrentWithConflictDetection,
+    ConcurrentWithoutConflictDetection,
+}
+
+#[derive(Clone, Debug, Default)]
+pub struct ProjectionCapabilities {
+    pub header: bool,
+    pub refs: bool,
+    pub header_and_refs: bool,
+    pub payload: bool,
+}
+
+#[derive(Clone, Debug, Default)]
+pub struct ScanCapabilities {
+    pub native_prefix_scan: bool,
+    pub reverse: bool,
+    pub limit_bytes: bool,
+    pub long_lived_cursors: bool,
+    pub parallel_partitions: bool,
+}
+
+#[derive(Clone, Debug, Default)]
+pub struct WriteCapabilities {
+    pub preconditions: bool,
+    pub idempotent_commit: bool,
+}
+
+#[derive(Clone, Debug, Default)]
+pub struct PushdownCapabilities {
+    pub key: PredicateSupportLevel,
+    pub header: PredicateSupportLevel,
+    pub refs: PredicateSupportLevel,
+    pub object_pruning: PredicateSupportLevel,
+}
+
+impl BackendCapabilities {
+    pub fn v0(write_concurrency: WriteConcurrency) -> Self {
+        Self {
+            profile: BackendProfile::V0 { write_concurrency },
+            projection: ProjectionCapabilities::default(),
+            scan: ScanCapabilities::default(),
+            write: WriteCapabilities::default(),
+            pushdown: PushdownCapabilities::default(),
+        }
+    }
+}