picovolt 1.4.0 → 1.6.0

package/README.md

@@ -1,7 +1,7 @@
 # PicoVolt (PVDB)
 
 [![CI](https://github.com/MiniJe/picovolt/actions/workflows/ci.yml/badge.svg)](https://github.com/MiniJe/picovolt/actions/workflows/ci.yml)
-[![Version](https://img.shields.io/badge/version-1.4.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.6.0-blue.svg)](CHANGELOG.md)
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 ![Status: 1.0 stable](https://img.shields.io/badge/status-1.0%20stable-brightgreen.svg)
 [![GitHub stars](https://img.shields.io/github/stars/MiniJe/picovolt?style=social)](https://github.com/MiniJe/picovolt)
@@ -56,8 +56,9 @@ Linux and Windows. Changes are tracked in [CHANGELOG.md](CHANGELOG.md).
 | [`engine/mvcc.rs`](src/engine/mvcc.rs) | transaction clock and snapshot visibility |
 | [`engine/wasm.rs`](src/engine/wasm.rs) | sandboxed `wasmi` extension runtime and the `WasmExec` backend trait |
 | [`engine/interp.rs`](src/engine/interp.rs) | `pv-wasm`: a from-scratch WASM interpreter (integer subset) |
-| [`engine/query.rs`](src/engine/query.rs) | SQL front-end (CREATE/INSERT/UPDATE/DELETE/DROP, `SELECT` with projection, `AS` aliases, `DISTINCT`, aggregates, `GROUP BY`/`HAVING`, `WHERE` predicates incl. `IN`/`BETWEEN`/`IS NULL`/`LIKE`, `BEFORE`, multi-column `ORDER BY`, `LIMIT`) |
+| [`engine/query.rs`](src/engine/query.rs) | SQL front-end (CREATE/INSERT/UPDATE/DELETE/DROP, `SELECT` with projection, `AS` aliases, `DISTINCT`, aggregates, `GROUP BY`/`HAVING`, `WHERE` predicates incl. `IN`/`BETWEEN`/`IS NULL`/`LIKE`, `BEFORE`, multi-column `ORDER BY`, `LIMIT`/`OFFSET`) |
 | [`engine/compliance.rs`](src/engine/compliance.rs) | optional, app-driven usage-policy hook (not a license requirement) |
+| [`enterprise.rs`](src/enterprise.rs) | optional, host-owned audit events and honest capability discovery for fleet integrations |
 | [`db.rs`](src/db.rs) | the `Database` surface that ties it together |
 | [`ffi.rs`](src/ffi.rs) | C ABI (the `capi` feature): a panic-safe, C-callable surface wrapping the engine for Go, Python, and C bindings |
 
@@ -86,6 +87,10 @@ Linux and Windows. Changes are tracked in [CHANGELOG.md](CHANGELOG.md).
   each flush `fsync` the data and commit the manifest atomically (write to a temp
   file, `fsync`, then rename). The default `Fast` mode uses the OS cache only:
   fast and durable on a clean exit, but not power-loss-safe.
+- **Crash-recoverable transactions.** Explicit `BEGIN`, `COMMIT`, and
+  `ROLLBACK` group filesystem or in-memory writes. Filesystem transactions keep
+  a synced rollback image and recovery marker; reopening after interruption
+  restores the last committed state before loading the workspace.
 - **Hardened against untrusted input.** Opening a `.pvdb` or workspace, or running
   a WASM module, validates manifest hashes (no path traversal), bounds-checks CAS
   offsets and page chains (no out-of-bounds reads or infinite loops on a crafted
@@ -113,22 +118,24 @@ cargo run --release --example bench    # evaluation harness across modes and wor
 ```
 
 Install the first-class CLI with `cargo install picovolt`, then use `pv query`,
-`pv inspect`, `pv import`, `pv export`, and `pv bake`. Copyable Rust, Python, Go,
-and browser projects are in [`starters/`](starters/README.md); supported adapters
+`pv inspect`, `pv history`, `pv import`, `pv export`, and `pv bake`. Copyable
+Rust, Python, Go, Node, and browser projects are in [`starters/`](starters/README.md); supported adapters
 are catalogued in [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md).
 
-SQL supported: `CREATE TABLE` with `PRIMARY KEY`, `UNIQUE`, and `NOT NULL`,
-`CREATE [UNIQUE] INDEX ON t (col)`, `INSERT`,
-`UPDATE ... SET ... WHERE`, `DELETE ... WHERE`, `DROP TABLE`, and
+SQL supported: `CREATE TABLE [IF NOT EXISTS]` with `PRIMARY KEY`, `UNIQUE`, and `NOT NULL`,
+`CREATE [UNIQUE] INDEX ON t (col)`, single- and multi-row `INSERT`,
+`UPDATE ... SET ... WHERE`, `DELETE ... WHERE`, `DROP TABLE [IF EXISTS]`, and
 `SELECT [DISTINCT] {* | col [AS alias], ... | COUNT/SUM/MIN/MAX/AVG(...) [AS alias]}
 FROM t [WHERE <pred>] [GROUP BY cols] [HAVING <pred>] [BEFORE tx]
-[ORDER BY col [ASC|DESC], ...] [LIMIT n]`, where `<pred>` combines
+[ORDER BY col [ASC|DESC], ...] [LIMIT n] [OFFSET n]`, where `<pred>` combines
 `col <op> value` (`=`, `!=`, `<`, `<=`, `>`, `>=`, `LIKE`, `NOT LIKE`),
 `col [NOT] IN (...)`, `col [NOT] BETWEEN a AND b`, and `col IS [NOT] NULL` with
 `AND`, `OR`, and parentheses. Integer and decimal values compare by magnitude.
-Basic `SELECT * FROM a [INNER|LEFT] JOIN b ON a_key = b_key` equality joins are
-also supported. Rust callers can cache `Database::prepare(...)` templates and use
-atomic `Database::transaction(...)` closures with in-memory databases.
+Two-table equality `INNER`/`LEFT JOIN` queries support qualified references,
+projection, aliases, `DISTINCT`, filters, ordering, and pagination. Rust callers
+can cache `Database::prepare(...)` templates and use explicit transaction
+lifecycle methods or atomic `Database::transaction(...)` closures with both
+filesystem and in-memory databases.
 Durability is selectable via `Database::set_durability` (`Fast` OS-cache default,
 or crash-safe `Sync` with fsync and an atomic manifest).
 
@@ -139,8 +146,9 @@ around 33k rows/s, linear), larger-than-RAM reads through a bounded buffer pool
 lookups roughly 11,000 times faster than a scan, plus range predicates), MVCC
 time-travel, opt-in crash-safe durability (`Durability::Sync`), and a fast
 compile-and-publish path (CAS dedup, columnar compression, memory-mappable
-single-file artifacts). Current limits include no filesystem `BEGIN`/`COMMIT`
-transactions, only basic two-table equality joins, and no concurrent writers.
+single-file artifacts). Current limits include full-workspace transaction
+backups rather than an incremental WAL, only basic two-table equality joins,
+and no concurrent writers.
 
 ## Install and distribution
 
@@ -148,7 +156,7 @@ transactions, only basic two-table equality joins, and no concurrent writers.
 |--------|-----|
 | **Rust** (crates.io) | `cargo add picovolt` |
 | **JavaScript / npm** (WebAssembly, browser and Node) | `npm install picovolt` |
-| **Python** (native wheels) | `python -m pip install picovolt` (after the first PyPI release) |
+| **Python** (native wheels) | `python -m pip install picovolt` |
 | **C / Go** (native, via the C ABI) | `cargo build --release --features capi`, then see [`bindings/`](bindings) |
 | **In-memory** (native, no filesystem) | `Database::open_memory()`, export with `bake_to_bytes()` |
 
@@ -171,7 +179,8 @@ JavaScript API (`import Database from "picovolt/sqlite"`), a Python DB-API 2.0
 module (`import picovolt.dbapi2 as sqlite`), and the Go `database/sql` driver
 ([`bindings/go/pvsql`](bindings/go/pvsql)). Shared limits include positional `?`
 only and the intentionally compact SQL grammar; JavaScript and in-memory Rust
-also expose rollback-capable transaction wrappers.
+also expose rollback-capable transaction wrappers. Native bindings expose the
+same transaction lifecycle through the C ABI.
 
 ## Server mode
 
@@ -196,6 +205,11 @@ result rows, and response size are bounded. TLS is not built in, so network
 deployments still belong behind a TLS-terminating reverse proxy. See
 [src/bin/server.rs](src/bin/server.rs).
 
+The HTTP API is sessionless, so each request is an atomic statement and explicit
+transaction-control statements are rejected. Applications needing a
+multi-statement transaction should use an embedded language binding, where the
+transaction belongs to one database handle.
+
 Applications accepting SQL from users can also call `Database::query_with_limits`
 directly and choose their own scan, result, memory, and deadline budgets.
 
@@ -211,6 +225,9 @@ native modules built on the public API. Both are documented in
 |--|--|
 | Roadmap | [ROADMAP.md](ROADMAP.md) |
 | One-million-download plan | [docs/ROADMAP_1M_DOWNLOADS.md](docs/ROADMAP_1M_DOWNLOADS.md) |
+| Monetization thesis | [docs/MONETIZATION.md](docs/MONETIZATION.md) |
+| Enterprise integration foundation | [docs/ENTERPRISE.md](docs/ENTERPRISE.md) |
+| Platform and file support | [docs/SUPPORT.md](docs/SUPPORT.md) |
 | Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
 | Code of conduct | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) |
 | Changelog | [CHANGELOG.md](CHANGELOG.md) |

package/package.json

@@ -2,7 +2,7 @@
   "name": "picovolt",
   "type": "module",
   "description": "PicoVolt (PVDB): a polymorphic embedded database engine in Rust.",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/picovolt.d.ts

@@ -7,6 +7,14 @@
 export class Db {
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Begin an explicit multi-statement in-memory transaction.
+     */
+    beginTransaction(): void;
+    /**
+     * Commit the active transaction.
+     */
+    commitTransaction(): void;
     /**
      * The most recently committed transaction id, the upper bound for a
      * `... BEFORE tx` time-travel query.
@@ -21,6 +29,10 @@ export class Db {
      * [`export`](Db::export)). Writable, with full time-travel history intact.
      */
     static fromBytes(bytes: Uint8Array): Db;
+    /**
+     * Whether an explicit transaction is active.
+     */
+    inTransaction(): boolean;
     /**
      * Create a new, empty in-memory database.
      */
@@ -40,6 +52,10 @@ export class Db {
      * `{"done":true}` otherwise. Throws the error message (a string) on failure.
      */
     query(sql: string, params: any): string;
+    /**
+     * Roll back the active transaction.
+     */
+    rollbackTransaction(): void;
     /**
      * A JSON array of the table names in this database (for introspecting an
      * uploaded `.pvdb` whose schema is unknown).

package/picovolt_bg.js

@@ -18,6 +18,24 @@ export class Db {
         const ptr = this.__destroy_into_raw();
         wasm.__wbg_db_free(ptr, 0);
     }
+    /**
+     * Begin an explicit multi-statement in-memory transaction.
+     */
+    beginTransaction() {
+        const ret = wasm.db_beginTransaction(this.__wbg_ptr);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
+    /**
+     * Commit the active transaction.
+     */
+    commitTransaction() {
+        const ret = wasm.db_commitTransaction(this.__wbg_ptr);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
     /**
      * The most recently committed transaction id, the upper bound for a
      * `... BEFORE tx` time-travel query.
@@ -55,6 +73,14 @@ export class Db {
         }
         return Db.__wrap(ret[0]);
     }
+    /**
+     * Whether an explicit transaction is active.
+     * @returns {boolean}
+     */
+    inTransaction() {
+        const ret = wasm.db_inTransaction(this.__wbg_ptr);
+        return ret !== 0;
+    }
     /**
      * Create a new, empty in-memory database.
      */
@@ -110,6 +136,15 @@ export class Db {
             wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
         }
     }
+    /**
+     * Roll back the active transaction.
+     */
+    rollbackTransaction() {
+        const ret = wasm.db_rollbackTransaction(this.__wbg_ptr);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
     /**
      * A JSON array of the table names in this database (for introspecting an
      * uploaded `.pvdb` whose schema is unknown).

package/sqlite.js

@@ -94,19 +94,21 @@ class Database {
     throw new Error("picovolt: pragma is not supported");
   }
 
-  // Wrap a synchronous callback in an atomic unit. A compact PVDB snapshot is
-  // restored if the callback throws, matching better-sqlite3's common pattern.
+  // Wrap a synchronous callback in an engine transaction, matching
+  // better-sqlite3's common pattern.
   transaction(fn) {
     if (typeof fn !== "function") throw new TypeError("transaction expects a function");
     const db = this;
     function wrapped(...args) {
       if (db._inTransaction) return fn(...args);
-      const snapshot = db.serialize();
+      db._db.beginTransaction();
       db._inTransaction = true;
       try {
-        return fn(...args);
+        const value = fn(...args);
+        db._db.commitTransaction();
+        return value;
       } catch (error) {
-        db._db = Db.fromBytes(snapshot);
+        if (db._db.inTransaction()) db._db.rollbackTransaction();
         throw error;
       } finally {
         db._inTransaction = false;