From fafb250bb4a460af81c35959c80cfee943e247ff Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 18 Apr 2026 18:56:44 +0530 Subject: [PATCH] chore(release): bump version to v0.20.0, doc-sync Phase 8.1 complete MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 8.1a (browser WASM) and Phase 8.1b (WASI) are both complete. Issue #150 (cross-platform .graph compatibility tests) is also resolved. - Cargo.toml: 0.19.0 → 0.20.0 - CHANGELOG.md: add v0.20.0 entry covering Phases 8.1a, 8.1b, and #150 - ROADMAP.md: mark Phase 8 in-progress, Phase 8.1 (both sub-phases) complete - README.md: update version badge and dependency snippet to 0.20 - CLAUDE.md: update test count 788 → 795 - TEST_COVERAGE.md: add Phase 8.1 completion section, update counts Co-Authored-By: Claude Sonnet 4.6 --- CHANGELOG.md | 22 ++++++++++++++ CLAUDE.md | 2 +- Cargo.toml | 2 +- README.md | 4 +-- ROADMAP.md | 79 +++++++++++++++++++++++------------------------- TEST_COVERAGE.md | 40 ++++++++++++++++++------ 6 files changed, 94 insertions(+), 55 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cee6a033fe..6dac7b40b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## v0.20.0 — Phase 8.1: WebAssembly Support (2026-04-18) + +### Added +- **Phase 8.1a** — Browser WASM (`wasm32-unknown-unknown` + `wasm-bindgen`): + - `BrowserDb` public API: `open_in_memory()`, `execute()`, `checkpoint()`, `export_graph()`, `import_graph()` + - `BrowserBufferBackend` — in-memory `StorageBackend` over a flat page buffer, identical byte layout to the native `.graph` format + - `IndexedDbBackend` — page-granular IndexedDB storage (one 4 KB entry per page); only dirty pages written on checkpoint + - `wasm-pack` build workflow (`wasm32-unknown-unknown --features browser`) generating `pkg/` with JS glue and TypeScript definitions + - `wasm-bindgen-test` browser integration tests (Chrome + Firefox via `wasm-pack test`) +- **Phase 8.1b** — Server-side WASM (`wasm32-wasip1` / WASI): + - `FileBackend` verified under WASI's capability-based filesystem (no backend changes needed) + - CI workflow (`wasm-wasi.yml`) builds, unit-tests, and smoke-tests under Wasmtime and Wasmer on every push/PR + - Thread-dependent tests gated with `#[cfg(not(target_os = "wasi"))]` +- **Cross-platform compatibility tests** (issue #150): + - `tests/cross_platform_compat_test.rs` — native round-trip (raw page byte copy) and fixture-readability tests + - `tests/fixtures/compat.graph` — committed v7 binary fixture containing `:alice :name "Alice"` and `:alice :age 30` + - `examples/generate_compat_fixture.rs` — reproducible fixture generator (native only; no-op on wasm32) + - `native_fixture_readable_by_browser_db` wasm-bindgen-test — loads native fixture via `BrowserDb::import_graph`, verifies both facts +- Release workflow: WASM artifacts (WASI binary + browser tarball) built and attached on every tag; `cargo publish` to crates.io on release + +795 tests. + ## v0.19.0 — Phase 7.9: Publish Prep (2026-04-08) ### Changed (breaking — internal visibility only) diff --git a/CLAUDE.md b/CLAUDE.md index 39d41fc8ae..cbcc5035c5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -167,7 +167,7 @@ Auto-migrates v1/v2/v3/v4/v5/v6 → v7 on open/checkpoint. ## Test Coverage -**788 tests passing** (unit + integration + doc). +**795 tests passing** (unit + integration + doc). See `TEST_COVERAGE.md` for the full per-file breakdown. **Testing conventions** — see the Testing Conventions section below before writing any tests. diff --git a/Cargo.toml b/Cargo.toml index 2b31a6cfcf..9b66666fc9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "minigraf" -version = "0.19.0" +version = "0.20.0" edition = "2024" description = "Zero-config, single-file, embedded graph database with bi-temporal Datalog queries" license = "MIT OR Apache-2.0" diff --git a/README.md b/README.md index 258c6e0582..b496efada7 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ [![Coverage](https://codecov.io/gh/adityamukho/minigraf/branch/main/graph/badge.svg)](https://codecov.io/gh/adityamukho/minigraf) [![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](https://github.com/adityamukho/minigraf#license) [![Rust Edition](https://img.shields.io/badge/rust-2024-orange.svg)](https://blog.rust-lang.org/2024/10/17/Rust-1.82.0.html) -[![Phase](https://img.shields.io/badge/phase-7.9%20complete-blue.svg)](https://github.com/adityamukho/minigraf/blob/main/ROADMAP.md) +[![Phase](https://img.shields.io/badge/phase-8.1%20complete-blue.svg)](https://github.com/adityamukho/minigraf/blob/main/ROADMAP.md) > **Embedded graph memory for AI agents, mobile apps, and the browser** — the SQLite of bi-temporal graph databases @@ -40,7 +40,7 @@ Minigraf is a **single-file embedded graph database** that lets you: ```toml [dependencies] -minigraf = "0.19" +minigraf = "0.20" ``` Or via cargo: diff --git a/ROADMAP.md b/ROADMAP.md index 13bfb4df9d..139b50671f 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1105,32 +1105,34 @@ The query optimizer uses selectivity estimates to pick join order. Different `:a --- -## Phase 8: Cross-Platform Expansion 🎯 FUTURE +## Phase 8: Cross-Platform Expansion 🔄 IN PROGRESS **Goal**: WASM, mobile, language bindings -**Status**: 🎯 Planned +**Status**: 🔄 In Progress (Phase 8.1 complete — v0.20.0) **Priority**: 🟢 Medium **Rationale**: Cross-platform expansion delivers a complete query engine (Phase 7) to more environments — not an incomplete one. Phase 7 ships first. -### 8.1 WebAssembly Support +### 8.1 WebAssembly Support ✅ COMPLETE **Goal**: Run Minigraf as a WASM module in two distinct environments: browser (JavaScript/TypeScript) and server-side WASM runtimes (WASI). +**Status**: ✅ Completed (April 2026) — v0.20.0 + There are two separate compilation targets with different requirements: -#### 8.1a Browser (`wasm32-unknown-unknown` + `wasm-bindgen`) +#### 8.1a Browser (`wasm32-unknown-unknown` + `wasm-bindgen`) ✅ **Features**: -- 🎯 `IndexedDbBackend`: stub already exists in `src/storage/backend/indexeddb.rs`; implement using `web-sys` + `wasm-bindgen` -- 🎯 Annotate public API with `#[wasm_bindgen]` to expose it to JavaScript -- 🎯 Build with `wasm-pack` — it handles compilation, JS glue code, and TypeScript `.d.ts` generation automatically -- 🎯 TypeScript definition file auto-generated by `wasm-pack` — gives IDE auto-complete and type safety to JS/TS consumers (including AI coding assistants) -- 🎯 Publish to npm via `wasm-pack publish` — makes Minigraf discoverable to web-based AI frameworks (LangChain.js, etc.) -- 🎯 Export API to reconstruct a portable `.graph` blob from IndexedDB (same binary format as native) -- 🎯 Disable `optimizer.rs` under `wasm` feature flag (already gated) +- ✅ `IndexedDbBackend`: page-granular IndexedDB storage using `web-sys` + `wasm-bindgen` +- ✅ `BrowserDb` public API annotated with `#[wasm_bindgen]` (execute, checkpoint, export_graph, import_graph) +- ✅ Built with `wasm-pack` — generates `pkg/` with JS glue and TypeScript `.d.ts` +- ✅ TypeScript definitions auto-generated by `wasm-pack` +- ✅ npm publish deferred to Phase 8.3 (bindings complete; package story not yet finalized) +- ✅ Export/import API for portable `.graph` blob (same binary format as native) +- ✅ `optimizer.rs` disabled under `wasm` feature flag **IndexedDB storage design: page-granular, not single-blob** @@ -1178,19 +1180,19 @@ wasm-pack build --target web wasm-pack publish ``` -**Deliverable**: npm package `@minigraf/core` — browser apps can `import { Minigraf } from '@minigraf/core'` and get full TypeScript types; page-granular IndexedDB backend keeps write amplification proportional to actual changes +**Deliverable**: ✅ Browser WASM with `BrowserDb` API, page-granular IndexedDB backend, and TypeScript types. Cross-platform `.graph` compatibility verified between native and browser via committed fixture and `import_graph` round-trip test. -#### 8.1b Server-side WASM (`wasm32-wasip1` / WASI) +#### 8.1b Server-side WASM (`wasm32-wasip1` / WASI) ✅ **Goal**: Run Minigraf inside server-side WASM runtimes (Wasmtime, Wasmer, Cloudflare Workers with WASI, Fastly Compute). **Why this matters**: Agent frameworks running in sandboxed server-side WASM environments (more secure than Docker containers) can embed Minigraf without any JavaScript bridge. Standard Rust code — no `wasm-bindgen`, no `#[wasm_bindgen]` annotations needed. **Features**: -- 🎯 Verify `FileBackend` works correctly under WASI's capability-based filesystem -- 🎯 Compile to `wasm32-wasip1` target (formerly `wasm32-wasi`) -- 🎯 No storage backend changes needed — WASI exposes a filesystem API, so `FileBackend` works as-is with capability grants -- 🎯 Validate with Wasmtime and Wasmer runtimes in CI +- ✅ `FileBackend` verified under WASI's capability-based filesystem +- ✅ Compiles to `wasm32-wasip1` target (formerly `wasm32-wasi`) +- ✅ No storage backend changes needed — WASI exposes a filesystem API; `FileBackend` works as-is with capability grants +- ✅ Validated with Wasmtime and Wasmer runtimes in CI (`wasm-wasi.yml`) **Build**: ```bash @@ -1199,7 +1201,7 @@ cargo build --target wasm32-wasip1 --release **Constraint**: WASI filesystem access requires the host runtime to grant explicit capability permissions (`--dir` in Wasmtime). Document this for users. -**Deliverable**: Minigraf `.wasm` binary runs under Wasmtime/Wasmer with file-backed storage; suitable for use in Cloudflare Workers (WASI) and similar edge runtimes +**Deliverable**: ✅ Minigraf `.wasm` binary runs under Wasmtime/Wasmer with file-backed storage; suitable for use in Cloudflare Workers (WASI) and similar edge runtimes ### 8.2 Mobile Bindings @@ -1534,7 +1536,7 @@ Push `Expr` predicate clauses (e.g. `[(> ?age 30)]`) down to filter bindings as - ✅ Branch coverage: `executor.rs` ~85.71% (up from ~75%), `evaluator.rs` ~89.29% (up from ~73%) - ✅ 617 tests passing (424 unit + 187 integration + 6 doc) -### v1.0.0 - 🎯 Phase 7 (Datalog Completeness) +### ✅ Phase 7 (Datalog Completeness) — shipped v0.11.0–v0.19.0 - Stratified negation (`not` / `not-join`) - Aggregation (`count`, `sum`, `min`, `max`, `distinct`, `:with`) + arithmetic filter predicates - Disjunction (`or` / `or-join`) @@ -1547,17 +1549,17 @@ Push `Expr` predicate clauses (e.g. `[(> ?age 30)]`) down to filter bindings as - ≥90% branch coverage - Stable API, stable file format, comprehensive tests, full documentation, performance validated +### v1.0.0 - 🎯 Phase 8 (Cross-platform) +- WASM support (browser + WASI) ✅ Phase 8.1 complete (v0.20.0) +- Mobile bindings (iOS + Android) +- Language bindings (Python, C, Node.js) + **Stability Promise**: After v1.0.0, we commit to: - Backwards-compatible file format (decades) - Stable public API (semantic versioning) - Migration tools for any format changes - Long-term support -### v1.1.0 - 🎯 Phase 8 (Cross-platform) -- WASM support (browser + WASI) -- Mobile bindings (iOS + Android) -- Language bindings (Python, C, Node.js) - --- ## Decision Framework @@ -1610,9 +1612,9 @@ When evaluating features, ask: - ✅ Phase 7.7b: Complete (April 2026) - User-Defined Functions (`register_aggregate`/`register_predicate`), 727 tests - ✅ Phase 7.8: Complete (April 2026) - Prepared statements (`$slot` bind tokens, temporal bind slots, plan reuse), 780 tests - ✅ Phase 7.9: Complete (April 2026) - Publish prep (crates.io API cleanup, Rustdoc sweep, `unwrap` audit, CI matrix), 788 tests -- 🎯 Phase 8: 3-4 months (Cross-platform — WASM, mobile, language bindings) +- ✅ Phase 8.1: Complete (April 2026) - Browser WASM (`BrowserDb`, IndexedDB backend) + WASI (`wasm32-wasip1` CI) + cross-platform compat tests, 795 tests +- 🔄 Phase 8: In progress (Cross-platform — WASM ✅, mobile, language bindings → **v1.0.0**) - 🎯 Phase 9: Ongoing (Ecosystem — integration examples, cookbook, GraphRAG/LangChain examples) -- 🎯 **v1.0.0: 9-12 months** **Note**: This is a hobby project. Timeline is flexible but realistic. @@ -1620,22 +1622,17 @@ When evaluating features, ask: ## Current Focus -**Right Now**: Phase 7.9 Complete — Phase 8 Next (Cross-Platform Expansion) +**Right Now**: Phase 8.1 Complete (v0.20.0) — Phase 8.2 Next (Mobile Bindings) -**Phase 7.9 Achievements**: -1. ✅ `Minigraf::repl(&self) -> Repl<'_>` factory method — `Repl` now borrows `&Minigraf` -2. ✅ All internal types narrowed to `pub(crate)`: `FactStorage`, `PersistentFactStorage`, `FileHeader`, `StorageBackend`, `DatalogExecutor`, `PatternMatcher`, `Fact`, `TxId`, `VALID_TIME_FOREVER`, `Wal`, etc. -3. ✅ Full rustdoc on all public API items with `# Examples` doctests; 8 new doctests -4. ✅ `[package.metadata.docs.rs]` in `Cargo.toml` — docs.rs builds with `all-features = true` -5. ✅ `#![warn(missing_docs)]` — enforces documentation coverage going forward -6. ✅ Bare `.unwrap()` in library code replaced with `.expect("lock poisoned")` / `.expect("WAL not initialized")` -7. ✅ `cargo clippy -- -D warnings` clean -8. ✅ macOS and Windows added to CI test matrix (`rust.yml`) -9. ✅ crates.io and docs.rs badges + Installation section in `README.md` -10. ✅ 788 tests passing; version bumped to v0.19.0 +**Phase 8.1 Achievements**: +1. ✅ `BrowserDb` API (browser WASM) with `IndexedDbBackend` page-granular storage +2. ✅ `wasm-pack` build generating `pkg/` with JS glue and TypeScript `.d.ts` +3. ✅ `wasm32-wasip1` (WASI) CI: build, unit tests, smoke tests under Wasmtime + Wasmer +4. ✅ Cross-platform `.graph` compatibility tests (native ↔ browser): committed fixture + import round-trip +5. ✅ 795 tests passing; version bumped to v0.20.0 -**Immediate Next Steps (Phase 8)**: -1. Cross-Platform Expansion — WASM, mobile, language bindings +**Immediate Next Steps (Phase 8.2)**: +1. Mobile Bindings — iOS + Android via UniFFI **Key Decisions Made**: - ✅ Datalog query language (simpler, better for temporal) @@ -1645,7 +1642,7 @@ When evaluating features, ask: - ✅ UTC-only timestamps (avoids chrono GHSA-wcg3-cvx6-7396) - ✅ Packed pages over one-per-page (philosophy: small binary, efficient storage) - ✅ Approximate LRU (read-lock on hits — avoids write-lock contention) -- ✅ Target 9-12 months to v1.0 (ahead of schedule!) +- ✅ Phase 8 = v1.0.0 (not Phase 7 — cross-platform completion is the 1.0 milestone) See [GitHub Issues](https://github.com/adityamukho/minigraf/issues) for specific tasks. diff --git a/TEST_COVERAGE.md b/TEST_COVERAGE.md index b8cc559a14..d8d71915e0 100644 --- a/TEST_COVERAGE.md +++ b/TEST_COVERAGE.md @@ -1,11 +1,11 @@ # Minigraf Test Coverage Report -**Last Updated**: Phase 7.9 COMPLETE - Publish prep, 788 tests ✅ +**Last Updated**: Phase 8.1 COMPLETE - WebAssembly (browser + WASI), 795 tests ✅ ## Test Summary -**Total Tests**: 788 ✅ (781 passing, 7 ignored) -- ✅ 524 unit tests (lib, +19 from `prepared.rs`) +**Total Tests**: 795 ✅ (788 passing, 7 ignored) +- ✅ 530 unit tests (lib, +6 from browser/mod.rs wasm-bindgen-test suite) - ✅ 24 bi-temporal tests (integration) - ✅ 10 complex query tests (integration) - ✅ 8 recursive rules tests (integration) @@ -29,7 +29,27 @@ - ✅ 17 prepared statement tests (integration, Phase 7.8 — entity/value/as-of/valid-at slots, combined temporal+entity, AnyValidTime, error paths, plan reuse) - ✅ 23 doc tests (15 prior + 8 new from Phase 7.9 rustdoc sweep on public API items) -**Status**: ✅ **All 781 tests passing** (7 ignored: confirmed or+neg-cycle stratification bug) +**Status**: ✅ **All 788 tests passing** (7 ignored: confirmed or+neg-cycle stratification bug) + +## Phase 8.1 Completion Status: ✅ COMPLETE + +**Phase 8.1a Features** (browser WASM, complete): +- ✅ `BrowserDb` public API: `open_in_memory`, `execute`, `checkpoint`, `export_graph`, `import_graph` +- ✅ `BrowserBufferBackend` — in-memory `StorageBackend` over a flat page buffer, byte-identical to native `.graph` format +- ✅ `IndexedDbBackend` — page-granular IndexedDB storage via `web-sys` + `wasm-bindgen` +- ✅ `wasm-pack` build generating `pkg/` with JS glue and TypeScript `.d.ts` +- ✅ `wasm-bindgen-test` suite: 6 browser integration tests (Chrome + Firefox in CI) + +**Phase 8.1b Features** (WASI, complete): +- ✅ `FileBackend` verified under WASI capability-based filesystem (no changes needed) +- ✅ `wasm32-wasip1` CI workflow: build, unit tests (Wasmtime runner), smoke tests (Wasmtime + Wasmer) +- ✅ Thread-dependent tests gated with `#[cfg(not(target_os = "wasi"))]` + +**Cross-platform compatibility** (issue #150, complete): +- ✅ `tests/cross_platform_compat_test.rs`: 2 native tests (raw page byte round-trip + fixture readability) +- ✅ `tests/fixtures/compat.graph`: committed v7 binary fixture with known facts +- ✅ `native_fixture_readable_by_browser_db` wasm-bindgen-test: imports native fixture, verifies both facts +- ✅ 795 tests passing (unit + integration + doc + wasm); version bumped to v0.20.0 ## Phase 7.9 Completion Status: ✅ COMPLETE @@ -700,9 +720,9 @@ cargo test -- --nocapture ## Conclusion -**Phase 7.9 Status**: ✅ **COMPLETE** +**Phase 8.1 Status**: ✅ **COMPLETE** -**Test Quality**: ✅ **Excellent** — High confidence in all Phase 3-7.9 features +**Test Quality**: ✅ **Excellent** — High confidence in all Phase 3-8.1 features **Strengths**: - WAL crash safety verified with real `mem::forget` simulation @@ -724,13 +744,13 @@ cargo test -- --nocapture - User-defined functions verified: custom aggregates, custom predicates, UDF as window function, name collision guards, runtime error handling, thread safety (Phase 7.7b) - Prepared statements verified: entity/value/as-of/valid-at slot positions, AnyValidTime, combined temporal+entity (agentic loop pattern), plan reuse, all error paths (Phase 7.8) - Public API surface verified via rustdoc doctests: `Minigraf::open`, `execute`, `prepare`, `repl`, `WriteTransaction`, `OpenOptions` (Phase 7.9) -- 788 tests covering all Phase 3-7.9 features +- 795 tests covering all Phase 3-8.1 features (including browser WASM + WASI + cross-platform compat) -**Confidence Level**: ✅ **Production-ready for Phase 7.9 scope** +**Confidence Level**: ✅ **Production-ready for Phase 8.1 scope** -**Readiness for Phase 8**: ✅ **Ready to proceed** +**Readiness for Phase 8.2**: ✅ **Ready to proceed** -The publish-ready, prepared-statement-capable, UDF-capable, window-function-capable, disjunction + aggregation + arithmetic/predicate expression capable, stratified-negation-capable, on-disk B+tree indexed, packed, cached bi-temporal Datalog engine is **solid, well-tested, documented, and benchmarked**. +The WebAssembly-capable (browser + WASI), publish-ready, prepared-statement-capable, UDF-capable, window-function-capable, disjunction + aggregation + arithmetic/predicate expression capable, stratified-negation-capable, on-disk B+tree indexed, packed, cached bi-temporal Datalog engine is **solid, well-tested, documented, and benchmarked**. ---