picovolt 1.9.0 → 2.2.0

package/README.md

@@ -2,17 +2,56 @@
 
 [![CI](https://github.com/MiniJe/picovolt/actions/workflows/ci.yml/badge.svg)](https://github.com/MiniJe/picovolt/actions/workflows/ci.yml)
 [![crates.io](https://img.shields.io/crates/v/picovolt.svg)](https://crates.io/crates/picovolt)
-[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
-![Status: stable 1.x](https://img.shields.io/badge/status-stable%201.x-brightgreen.svg)
+[![License: Proprietary](https://img.shields.io/badge/license-Proprietary-blue.svg)](LICENSE)
 [![GitHub stars](https://img.shields.io/github/stars/MiniJe/picovolt?style=social)](https://github.com/MiniJe/picovolt)
 
-PicoVolt is an embedded database engine written in Rust. Its 1.x public API and
-on-disk format are stable under Semantic Versioning. It is young software and
-has not had an external security audit, so review it and keep backups before
-trusting it with data you cannot regenerate.
+PicoVolt is an embedded SQL database with queryable history. **2.2.0** adds
+native encrypted snapshots and vaults, key/password rotation, verified encrypted
+backup/restore and hybrid full-text/vector retrieval. It builds on the snapshot
+readers, bounded writer scheduling and durable commit logs introduced in 2.0.
 
-If PicoVolt is useful to you, consider starring the repository on GitHub. It is
-the simplest way to help others discover the project.
+The source and official packages are available without a license fee under the
+[PicoVolt Public-Source License 1.1](LICENSE). This proprietary license permits
+commercial application embedding and unchanged registry/mirror distribution;
+standalone competing database products require a separate agreement. This is
+source-available, not open source. Earlier Apache grants remain unchanged.
+No account, activation, telemetry or pre-download acceptance is required.
+
+Read [encrypted storage](docs/ENCRYPTION_2_2.md), [hybrid search](docs/HYBRID_2_2.md)
+and [release evidence](docs/RELEASE_2_2.md). Native vault encryption is not offered
+in WASM. Independent security/cryptographic review and external application
+trials have not been completed; automated verification is not such an audit.
+
+Start with the [2.0 guide for every maintained interface](docs/QUICKSTART_2_0.md)
+for atomic batches, persistence choices, log diagnostics and error recovery.
+The [standalone review prompt](docs/INDEPENDENT_REVIEW_PROMPT.md) defines an
+independent assessment and external trials deferred beyond the 2.0 release.
+
+## Quick start
+
+The 2.2.0 release is free to download and use within its [license](LICENSE).
+Historical 2.0 documentation below remains useful for unchanged APIs. See the
+[transition policy](legal/TRANSITION.md) for continuing Apache rights and support.
+
+```sh
+cargo add picovolt@2.2.0
+```
+
+```rust
+use picovolt::Database;
+
+fn main() -> Result<(), picovolt::PvError> {
+    let mut db = Database::open_memory();
+    db.query("CREATE TABLE notes (id, body)")?;
+    db.query("INSERT INTO notes VALUES (1, 'Hello, PicoVolt')")?;
+    println!("{:?}", db.query("SELECT * FROM notes")?);
+    Ok(())
+}
+```
+
+For other languages, see [Install and distribution](#install-and-distribution).
+
+## Storage model
 
 The engine decouples query logic from storage representation through a
 Virtualization Layer Engine (VLE) that shifts between two on-disk shapes:
@@ -28,10 +67,10 @@ MVCC-preserving columnar layout with packed decimal encoding.
 
 ## Status
 
-The current stable release is exercised by a 240+ test Rust suite plus doctests
+The engine is exercised by Rust unit and integration suites plus doctests
 and maintained-binding integration tests. CI also enforces formatting and
 warning-free Clippy builds on Linux and Windows. Shipped changes are tracked in
-[CHANGELOG.md](CHANGELOG.md), and the remaining work toward 2.0 is tracked in
+[CHANGELOG.md](CHANGELOG.md), and future work is tracked in
 [ROADMAP.md](ROADMAP.md).
 
 ### Module map
@@ -73,8 +112,10 @@ warning-free Clippy builds on Linux and Windows. Shipped changes are tracked in
   and are rejected rather than mis-run.
 - **Page-backed engine.** Tables are append-only chains of hot row pages and
   optional packed cold pages, each header linking to the next. Inserts append to
-  a row tail and write only that page plus an O(tables) manifest, so autocommit
-  is O(1) per insert rather than a whole-table rewrite. Reads stream through a
+  a row tail. Commit cost also includes catalog/index maintenance, retained-log
+  accounting and the selected durability protocol; it is not uniformly O(1).
+  Logged 2.0 workspaces persist index definitions to reduce catalog rewrites.
+  Reads stream through a
   bounded buffer pool ([`storage/cache.rs`](src/storage/cache.rs)), so datasets
   need not fit in RAM, and opt-in ordered indexes
   ([`storage/index.rs`](src/storage/index.rs)) turn `WHERE col = value` into a
@@ -84,10 +125,12 @@ warning-free Clippy builds on Linux and Windows. Shipped changes are tracked in
   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.
+- **Concurrent transactions.** Native `SharedDatabase` exposes independent
+  snapshot readers and bounded FIFO writers. Logged workspaces sync original
+  pages before overwriting them and publish an ordered physical change stream.
+  Reopening rolls back incomplete writes. Format 6 prevents old binaries from
+  bypassing recovery. Existing 1.x images remain readable and migratable.
+  See [the concurrency contract](docs/CONCURRENCY.md) for limits and costs.
 - **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
@@ -150,21 +193,30 @@ databases.
 Durability is selectable via `Database::set_durability` (`Fast` OS-cache default,
 or crash-safe `Sync` with fsync and an atomic manifest).
 
-Measured results and the methodology are in [BENCHMARKS.md](BENCHMARKS.md). In
-short, PicoVolt is a page-backed engine with O(1) filesystem appends (autocommit
-around 33k rows/s, linear), larger-than-RAM reads through a bounded buffer pool (a
-667-page dataset serves from a 16-page pool), ordered secondary indexes (point
-lookups roughly 6,100 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, cooperative columnar compression,
-memory-mappable single-file artifacts). Current limits include full-workspace
-transaction backups rather than an incremental WAL, adaptive index access within
-a left-deep equality-join plan rather than a general SQL planner, and no
-concurrent writers.
+Native Rust applications can use the 2.0 concurrency surface through
+`SharedDatabase`. It is a cloneable, bounded worker-thread coordinator with
+explicit read and write transaction handles, FIFO admission, cooperative
+cancellation, and rollback before failed or abandoned writes release the queue.
+Explicit readers execute against independent snapshots while one writer updates
+the workspace. Logged workspaces use format 7 with commit-sequence anchoring;
+use clones of one coordinator for a shared development workspace.
+See [Shared database concurrency](docs/CONCURRENCY.md) for the contract and
+current limits.
+
+Measured results and the methodology are in [BENCHMARKS.md](BENCHMARKS.md).
+These measurements describe specific workloads and versions, rather than a
+general throughput guarantee. PicoVolt supports bounded page-cache reads,
+ordered secondary indexes, MVCC time travel and single-file publication.
+Shared filesystem transactions use an incremental page journal; the legacy
+unlogged surface retains full rollback images. Current limits include snapshot
+copy costs, a focused SQL planner and a single writer. The [2.0 benchmark
+baseline](benchmarks/COMPETITORS_2_0_RC3.md) records candidate measurements and
+their limits; see [the concurrency contract](docs/CONCURRENCY.md) for current
+resource costs.
 
 ## Maintenance and migration
 
-Cold-page maintenance is explicit in 1.x so the host retains ownership of
+Cold-page maintenance is explicit so the host retains ownership of
 scheduling and threads:
 
 ```sh
@@ -175,8 +227,8 @@ pv inspect ./data.pv --json
 `Database::compact_step(max_pages)` preserves record addresses, indexes, and
 complete MVCC history; it never compacts the mutable tail and leaves a page in
 row form when transposition would not save space. Each pass uses the
-crash-recoverable workspace transaction protocol, so allow temporary disk space
-for one complete rollback image. Baked-image migration is
+crash-recoverable transaction protocol: allow bounded journal space for logged
+workspaces, or a full rollback image for unlogged workspaces. Baked-image migration is
 out-of-place and deeply verified before publication:
 
 ```sh
@@ -194,7 +246,7 @@ See [Migration and compaction](docs/MIGRATION.md).
 | **Rust** (crates.io) | `cargo add picovolt` |
 | **JavaScript / npm** (WebAssembly, browser and Node) | `npm install picovolt` |
 | **Python** (native wheels) | `python -m pip install picovolt` |
-| **Go** (`database/sql` and direct API) | `go get github.com/MiniJe/picovolt/bindings/go@latest`, then provide the matching native C ABI library described in [`bindings/go/`](bindings/go) |
+| **Go** (`database/sql` and direct API) | `go get github.com/MiniJe/picovolt/bindings/go/v2@v2.2.0`, then provide the matching native C ABI library described in [`bindings/go/`](bindings/go) |
 | **C** | Download the matching `picovolt-capi-*` bundle from the [latest release](https://github.com/MiniJe/picovolt/releases/latest), or run `cargo build --release --features capi` |
 | **In-memory** (native, no filesystem) | `Database::open_memory()`, export with `bake_to_bytes()` |
 
@@ -263,7 +315,6 @@ 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) |
@@ -274,10 +325,11 @@ native modules built on the public API. Both are documented in
 
 ## License
 
-Licensed under the [Apache License, Version 2.0](LICENSE). Third-party
-dependencies are under MIT or Apache-2.0 licenses, and their notices apply to
-redistributions (see [`NOTICE`](NOTICE)).
+The 2.1.0 line is prepared under the [PicoVolt Proprietary Lifetime License](LICENSE).
+Earlier Apache-2.0 components retain their existing grants; the original license
+is preserved [here](legal/APACHE-2.0-LEGACY.txt). Third-party licenses and notices
+continue to apply (see [`NOTICE`](NOTICE)). No automatic public publication is enabled.
 
 The optional [`compliance`](src/engine/compliance.rs) module is not a license
 requirement. It is an opt-in helper for applications that want to enforce their
-own usage policy. Apache-2.0 places no usage restrictions on PicoVolt itself.
+own usage policy. It does not implement license activation or telemetry.

package/browser.js

@@ -1,3 +1,4 @@
+// Modified for PicoVolt 2.1.0 retrieval, 2026-09-11. See legal/COMPONENT-SCOPE-2.1.md.
 // Durable browser helper backed by the Origin Private File System (OPFS).
 import { Db } from "./picovolt.js";
 
@@ -62,6 +63,16 @@ export class PersistentDb {
     return statement;
   }
 
+  retrieve(request) {
+    this._assertOpen();
+    return JSON.parse(this.db.retrieve(JSON.stringify(request)));
+  }
+
+  executeMany(sql, rows) {
+    this._assertOpen();
+    return JSON.parse(this.db.executeMany(sql, rows)).mutated;
+  }
+
   async save() {
     this._assertOpen();
     const root = await navigator.storage.getDirectory();