From 0689caf791e1c8e04328ed3f8ef808d54834e0a6 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 2 May 2026 07:39:41 +0530 Subject: [PATCH 01/11] docs: add @minigraf/wasi addendum to Phase 8 implementation plan --- .../plans/2026-05-01-phase8-completion.md | 86 +++++++++++++++++++ 1 file changed, 86 insertions(+) diff --git a/docs/superpowers/plans/2026-05-01-phase8-completion.md b/docs/superpowers/plans/2026-05-01-phase8-completion.md index 4a53555bbc..5f8d8cdb9d 100644 --- a/docs/superpowers/plans/2026-05-01-phase8-completion.md +++ b/docs/superpowers/plans/2026-05-01-phase8-completion.md @@ -1891,6 +1891,92 @@ gh issue comment 133 --repo project-minigraf/minigraf \ --- +## Addendum: @minigraf/wasi (PR #222, merged 2026-05-02) + +PR #222 (closes #178) adds `minigraf-wasi/` — the `@minigraf/wasi` npm package (ESM loader + TypeScript declarations for Node.js WASI consumers) and a `publish-npm-wasi` CI job in `wasm-release.yml`. `minigraf-wasi/package.json` stays at `0.0.0`; CI stamps the tag version at publish time (same pattern as `@minigraf/browser`). A basic `minigraf-wasi/README.md` was added by the PR. + +Incorporate the following additions into the relevant tasks when executing: + +### Task 3 (CHANGELOG) — add to "Also in this release" bullets: +``` +- `@minigraf/wasi` published to npm on every tagged release (issue #178) — WASI binary packaged for Node.js WASI consumers +``` + +### Task 4 (README) — two changes: +**Step 4** — update the WASI row in the platform support table: +```markdown +| WASI | `@minigraf/wasi` on npm, `.wasm` on GitHub Releases | `npm install @minigraf/wasi` | +``` + +**Step 6** — in the "For WASM / Browser" replacement text, change the WASI sentence from: +``` +WASI build (`wasm32-wasip1`) available as a GitHub Releases artifact (Wasmtime / Wasmer). +``` +to: +``` +WASI build (`wasm32-wasip1`) available as [`@minigraf/wasi`](https://www.npmjs.com/package/@minigraf/wasi) on npm and as a GitHub Releases artifact (Wasmtime / Wasmer). +``` + +### Task 5 (ROADMAP) — one change: +**Step 4** — in the v1.0.0 entry, update the WASI line to: +``` +- WASI (`wasm32-wasip1`, Wasmtime/Wasmer CI) + `@minigraf/wasi` npm package ✅ v1.0.0 +``` + +### Task 7 (llms.txt) — three changes: +1. In the maturity paragraph, change `WASI (\`wasm32-wasip1\`)` to `WASI (\`wasm32-wasip1\`, \`@minigraf/wasi\` npm)`. +2. In the source layout section, add after the `minigraf-wasm/` entry: +``` +- `minigraf-wasi/` — `@minigraf/wasi` npm package: ESM loader, TypeScript declarations, `minigraf-wasi.wasm` +``` +3. In the Links section, add after the `@minigraf/browser on npm` line: +``` +- [@minigraf/wasi on npm](https://www.npmjs.com/package/@minigraf/wasi) — WASI / Node.js +``` + +### Task 13 (Wiki Home.md) — one change: +**Step 4** — in the Packages table, split the last row: +Replace: +```markdown +| Android, iOS, C, WASI | [GitHub Releases](https://github.com/project-minigraf/minigraf/releases) | +``` +with: +```markdown +| WASI (Node.js) | [@minigraf/wasi on npm](https://www.npmjs.com/package/@minigraf/wasi) | +| Android, iOS, C, WASI binary | [GitHub Releases](https://github.com/project-minigraf/minigraf/releases) | +``` + +### Task 14 (Wiki Use-Cases.md) — one addition: +After the existing WASI section (Wasmtime/Wasmer usage), add a subsection: + +```markdown +### Node.js + +For Node.js consumers, the `@minigraf/wasi` npm package provides an ESM loader: + +```sh +npm install @minigraf/wasi +``` + +```js +import { WASI } from "node:wasi"; +import { startMinigrafWasi } from "@minigraf/wasi"; + +const wasi = new WASI({ + version: "preview1", + args: ["minigraf"], + env: process.env, + preopens: { "/tmp": "/tmp" }, +}); + +await startMinigrafWasi(wasi); +``` + +Use `MINIGRAF_WASI_WASM_PATH` or the `wasmPath` option to point the loader at an alternate `.wasm` file. +``` + +--- + ## Self-review notes - **Task 2, Step 8**: Package.swift checksum is a placeholder — this must be updated after CI produces the `MinigrafKit-v1.0.0.xcframework.zip` artifact. This is a deliberate two-step: the PR merges with the placeholder, then a follow-up commit updates the checksum once the release tag is pushed and CI completes. From affe16cf4ec1b5021a89b0a9a4a15ee9cee02088 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 2 May 2026 07:47:36 +0530 Subject: [PATCH 02/11] chore: bump all manifests to v1.0.0 Co-Authored-By: Claude Sonnet 4.6 --- Cargo.toml | 2 +- Package.swift | 4 ++-- minigraf-c/Cargo.toml | 2 +- minigraf-ffi/Cargo.toml | 2 +- minigraf-ffi/java/build.gradle.kts | 2 +- minigraf-ffi/python/pyproject.toml | 2 +- minigraf-node/Cargo.toml | 2 +- minigraf-node/package.json | 10 +++++----- 8 files changed, 13 insertions(+), 13 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index c17c9171ea..3f75f415fd 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,7 +4,7 @@ resolver = "2" [package] name = "minigraf" -version = "0.25.0" +version = "1.0.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/Package.swift b/Package.swift index 10cb5f7566..2ba520cd9c 100644 --- a/Package.swift +++ b/Package.swift @@ -18,8 +18,8 @@ let package = Package( .binaryTarget( name: "minigrafFFI", // Updated by CI: release-upload-mobile job - url: "https://github.com/project-minigraf/minigraf/releases/download/v0.20.1/MinigrafKit-v0.20.1.xcframework.zip", - checksum: "0000000000000000000000000000000000000000000000000000000000000000" + url: "https://github.com/project-minigraf/minigraf/releases/download/v1.0.0/MinigrafKit-v1.0.0.xcframework.zip", + checksum: "PLACEHOLDER — replace with SHA256 of MinigrafKit-v1.0.0.xcframework.zip after CI produces the artifact" ), .target( name: "MinigrafKit", diff --git a/minigraf-c/Cargo.toml b/minigraf-c/Cargo.toml index 4c4442568d..8b733aa33b 100644 --- a/minigraf-c/Cargo.toml +++ b/minigraf-c/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "minigraf-c" -version = "0.24.0" +version = "1.0.0" edition = "2024" description = "C bindings for Minigraf — stable C API with cbindgen-generated header" publish = false diff --git a/minigraf-ffi/Cargo.toml b/minigraf-ffi/Cargo.toml index b339ff2212..7a3c7257a2 100644 --- a/minigraf-ffi/Cargo.toml +++ b/minigraf-ffi/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "minigraf-ffi" -version = "0.23.0" +version = "1.0.0" edition = "2024" description = "UniFFI mobile bindings for Minigraf (Android + iOS)" publish = false diff --git a/minigraf-ffi/java/build.gradle.kts b/minigraf-ffi/java/build.gradle.kts index 997d2d92fb..0e7d216bcc 100644 --- a/minigraf-ffi/java/build.gradle.kts +++ b/minigraf-ffi/java/build.gradle.kts @@ -10,7 +10,7 @@ plugins { } group = "io.github.project-minigraf" -version = System.getenv("RELEASE_VERSION") ?: "0.23.0" +version = System.getenv("RELEASE_VERSION") ?: "1.0.0" repositories { mavenCentral() diff --git a/minigraf-ffi/python/pyproject.toml b/minigraf-ffi/python/pyproject.toml index 3fbaa533b0..b8af780bf4 100644 --- a/minigraf-ffi/python/pyproject.toml +++ b/minigraf-ffi/python/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "maturin" [project] name = "minigraf" -version = "0.22.0" +version = "1.0.0" description = "Zero-config, single-file, embedded graph database with bi-temporal Datalog queries" license = { text = "MIT OR Apache-2.0" } requires-python = ">=3.9" diff --git a/minigraf-node/Cargo.toml b/minigraf-node/Cargo.toml index fd5cb5c68a..3e8b67fce3 100644 --- a/minigraf-node/Cargo.toml +++ b/minigraf-node/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "minigraf-node" -version = "0.25.0" +version = "1.0.0" edition = "2024" publish = false diff --git a/minigraf-node/package.json b/minigraf-node/package.json index 0a0f68b395..3d8be8348b 100644 --- a/minigraf-node/package.json +++ b/minigraf-node/package.json @@ -1,6 +1,6 @@ { "name": "minigraf", - "version": "0.25.0", + "version": "1.0.0", "description": "Zero-config, single-file, embedded graph database with bi-temporal Datalog queries", "main": "index.js", "types": "index.d.ts", @@ -31,9 +31,9 @@ "@napi-rs/cli": "^3" }, "optionalDependencies": { - "@minigraf/linux-x64-gnu": "0.25.0", - "@minigraf/linux-arm64-gnu": "0.25.0", - "@minigraf/darwin-universal": "0.25.0", - "@minigraf/win32-x64-msvc": "0.25.0" + "@minigraf/linux-x64-gnu": "1.0.0", + "@minigraf/linux-arm64-gnu": "1.0.0", + "@minigraf/darwin-universal": "1.0.0", + "@minigraf/win32-x64-msvc": "1.0.0" } } From b501a9e16c1ddd44084e490081d1dad78a3a82d7 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 2 May 2026 07:50:26 +0530 Subject: [PATCH 03/11] docs(changelog): add v1.0.0 Phase 8 complete entry --- CHANGELOG.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8bd9f2eab6..5a6db741e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,39 @@ 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). +## v1.0.0 — Phase 8 Complete (2026-05-01) + +### Milestone + +This is the **v1.0.0 release**. The public Rust API and the `.graph` file format are now stable +and committed to semantic versioning. File format stability is guaranteed from this release. + +### Phase 8 summary + +All Phase 8 cross-platform targets have shipped: + +- **8.1a** — Browser WASM (`BrowserDb`, `IndexedDbBackend`, `@minigraf/browser` on npm) — v0.20.0 +- **8.1b** — Server-side WASM (`wasm32-wasip1` / WASI, Wasmtime/Wasmer CI) — v0.20.0 +- **8.2** — Mobile bindings (Android `.aar` on GitHub Packages, iOS `.xcframework` via SPM, UniFFI) — v0.21.0 +- **8.3a** — Python (`minigraf` on PyPI, pre-built wheels) — v0.22.0 +- **8.3b** — Java/JVM (`io.github.adityamukho:minigraf-jvm` on Maven Central, fat JAR) — v0.23.0 +- **8.3c** — C FFI (`minigraf.h` + platform tarballs on GitHub Releases) — v0.24.0 +- **8.3d** — Node.js (`minigraf` on npm, pre-built `.node` binaries) — v0.25.0 + +### Also in this release + +- `pkg/` renamed to `minigraf-wasm/`, `swift/` renamed to `minigraf-swift/` — consistent + top-level naming across all workspace packages (issue #179) +- `@minigraf/browser` now published to npm on every tagged release (issue #179) +- `@minigraf/wasi` published to npm on every tagged release (issue #178) — WASI binary packaged for Node.js WASI consumers +- Per-platform READMEs added: `minigraf-wasm/`, `minigraf-node/`, `minigraf-ffi/python/`, + `minigraf-c/`, `minigraf-ffi/java/` + +### Tests + +795 tests passing (788 passing + 7 ignored: confirmed `or`+neg-cycle stratification bug, +deferred to post-1.0 backlog). + ## v0.25.0 — 2026-04-26 ### Added From 90185fa4a3c73b248009317f310b432dc31a2bb6 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 2 May 2026 07:51:07 +0530 Subject: [PATCH 04/11] docs(readme): v1.0.0 badge, platform support table, update platform sections --- README.md | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 87082f2130..d9df578b5a 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ [![Coverage](https://codecov.io/gh/project-minigraf/minigraf/branch/main/graph/badge.svg)](https://codecov.io/gh/project-minigraf/minigraf) [![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](https://github.com/project-minigraf/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-8.3c%20complete-blue.svg)](https://github.com/project-minigraf/minigraf/blob/main/ROADMAP.md) +[![Release](https://img.shields.io/badge/release-v1.0.0-blue.svg)](https://github.com/project-minigraf/minigraf/releases/tag/v1.0.0) > **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.21" +minigraf = "1.0" ``` Or via cargo: @@ -91,7 +91,7 @@ let r2 = pq.execute(&[("tx", BindValue::TxCount(2)), ("entity", BindValue::Entit ```bash cargo run # interactive Datalog REPL -cargo test # run 780 tests +cargo test # run 795 tests cargo run < demos/demo_recursive.txt # recursive rules demo ``` @@ -115,6 +115,20 @@ No other database offers this combination: | **Rust** | ✅ Yes | ❌ Clojure | ✅ Yes | ❌ Java | ❌ C | | **WASM Ready** | ✅ Phase 8.1a/b | ❌ No | ⚠️ Limited | ❌ No | ✅ Yes | +## Platform support + +| Platform | Package | Install | +|---|---|---| +| Rust (native) | `minigraf` on crates.io | `cargo add minigraf` | +| Browser WASM | `@minigraf/browser` on npm | `npm install @minigraf/browser` | +| WASI | `@minigraf/wasi` on npm, `.wasm` on GitHub Releases | `npm install @minigraf/wasi` | +| Node.js | `minigraf` on npm | `npm install minigraf` | +| Python | `minigraf` on PyPI | `pip install minigraf` | +| Java/JVM | `io.github.adityamukho:minigraf-jvm` on Maven Central | see [wiki](https://github.com/project-minigraf/minigraf/wiki/Use-Cases) | +| Android | `.aar` on GitHub Packages | see [wiki](https://github.com/project-minigraf/minigraf/wiki/Use-Cases) | +| iOS / macOS | `.xcframework` via Swift Package Manager | see [wiki](https://github.com/project-minigraf/minigraf/wiki/Use-Cases) | +| C / FFI | header + tarball on GitHub Releases | see [wiki](https://github.com/project-minigraf/minigraf/wiki/Use-Cases) | + **Embedded graph memory for agents, mobile, and the browser — SQLite's simplicity + Datomic's temporal model.** See the [Comparison](https://github.com/project-minigraf/minigraf/wiki/Comparison) wiki page for detailed analysis including temporal vs. time-series databases. @@ -147,16 +161,20 @@ See the [Mobile Integration](https://github.com/project-minigraf/minigraf/wiki/U ### For WASM / Browser -Phase 8.1a complete: IndexedDB backend, `wasm-pack` packaging. Phase 8.1b complete: server-side WASM via `wasm32-wasip1` / WASI (Wasmtime, Wasmer). npm release as `@minigraf/browser` planned for Phase 8.2. +Published as [`@minigraf/browser`](https://www.npmjs.com/package/@minigraf/browser) on npm (IndexedDB-backed, `wasm-pack`). WASI build (`wasm32-wasip1`) available as [`@minigraf/wasi`](https://www.npmjs.com/package/@minigraf/wasi) on npm and as a GitHub Releases artifact (Wasmtime / Wasmer). See the [Use Cases wiki](https://github.com/project-minigraf/minigraf/wiki/Use-Cases). + +### For Python / Node.js / Java / C -See the [Use Cases](https://github.com/project-minigraf/minigraf/wiki/Use-Cases) wiki page for detailed guides on all three targets. +Language bindings ship as `minigraf` on PyPI, `minigraf` on npm (Node.js native addon), `io.github.adityamukho:minigraf-jvm` on Maven Central, and a C header + prebuilt shared library on GitHub Releases. See the [Use Cases wiki](https://github.com/project-minigraf/minigraf/wiki/Use-Cases). ## Scope Minigraf runs as: - ✅ An embedded library - ✅ A standalone binary (interactive REPL) -- ✅ A WebAssembly module — browser (`wasm32-unknown-unknown`) and server-side WASI (`wasm32-wasip1`) (Phase 8.1a/b complete) +- ✅ Browser WASM — `@minigraf/browser` (IndexedDB-backed, `wasm-pack`) +- ✅ Server-side WASM — `wasm32-wasip1` / WASI (Wasmtime, Wasmer, Cloudflare Workers) +- ✅ Android, iOS, Python, Node.js, Java, C — via UniFFI / napi-rs / cbindgen Minigraf will **not** be (by design): - **Distributed** — no clustering, no sharding, no replication; each agent instance owns its own `.graph` file From 2d0b6372b775113460c7cb3f2b5efbbfca0f56fb Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 2 May 2026 07:53:11 +0530 Subject: [PATCH 05/11] docs: update CLAUDE.md next-phase pointer, TEST_COVERAGE.md Phase 8 sections, BENCHMARKS.md Phase 8 note --- BENCHMARKS.md | 6 +++++ CLAUDE.md | 7 +++++- TEST_COVERAGE.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 70 insertions(+), 2 deletions(-) diff --git a/BENCHMARKS.md b/BENCHMARKS.md index a091da5b91..f6d0028bf8 100644 --- a/BENCHMARKS.md +++ b/BENCHMARKS.md @@ -1,5 +1,11 @@ # Minigraf Benchmarks +## Phase 8 Note + +Phase 8 (v0.20.0–v1.0.0) added cross-platform targets: Browser WASM, WASI, Android, iOS, +Python, Node.js, Java, and C bindings. No changes were made to the native query or storage path. +All benchmark numbers below are unchanged from Phase 7 (v0.19.0). + **Live benchmark history**: [https://bencher.dev/perf/minigraf/plots](https://bencher.dev/perf/minigraf/plots) Benchmark results for Minigraf. Core query benchmarks were updated in v0.13.1 (Phase 7.4 — query path snapshot fix). New benchmark groups for window functions, temporal metadata, UDFs, count-distinct, and regex filter added in v0.17.0 (Phase 7.8). Negation, disjunction, aggregation, and expression benchmarks were first run on v0.13.0 and selectively re-run on v0.13.1. Throughput reporting (facts/sec, aggregate ops/sec), retraction benchmarks, prepared query benchmarks, and checkpoint@1M added in v0.20.1. diff --git a/CLAUDE.md b/CLAUDE.md index cbcc5035c5..cb559201c8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -174,7 +174,12 @@ See `TEST_COVERAGE.md` for the full per-file breakdown. ## Key Files for the Next Phase -See `ROADMAP.md` for the current next phase spec, including the relevant files and implementation details. +Phase 8 is complete — v1.0.0 released. Phase 9 (Ecosystem & Tooling) is next. + +Phase 9 relevant areas (see `ROADMAP.md` for full spec): +- `examples/` — end-to-end annotated examples (agentic memory, offline-first mobile, browser PWA) +- `.wiki/` — cookbook-style guides for each Phase 9 deliverable +- `BENCHMARKS.md` — post-1.0 performance baseline updates ## Testing Conventions diff --git a/TEST_COVERAGE.md b/TEST_COVERAGE.md index dca96a9679..8606a66429 100644 --- a/TEST_COVERAGE.md +++ b/TEST_COVERAGE.md @@ -1,6 +1,6 @@ # Minigraf Test Coverage Report -**Last Updated**: Phase 8.3c COMPLETE - C bindings (GitHub Releases tarballs), 795 tests ✅ +**Last Updated**: Phase 8 COMPLETE — v1.0.0 (May 2026), 795 tests ✅ ## Test Summary @@ -31,6 +31,63 @@ **Status**: ✅ **All 788 tests passing** (7 ignored: confirmed or+neg-cycle stratification bug) +## Phase 8 Completion Status: ✅ COMPLETE — v1.0.0 + +All Phase 8 sub-phases complete. See per-phase sections below. + +--- + +## Phase 8.3d Completion Status: ✅ COMPLETE + +**Phase 8.3d Features** (Node.js, complete — v0.25.0): +- ✅ `minigraf-node/src/lib.rs` — napi-rs bindings: `MiniGrafDb` class (open, inMemory, execute, checkpoint) +- ✅ `minigraf-node/package.json` — `minigraf` npm package; prebuilt `.node` binaries for Linux x86_64/aarch64, macOS universal2, Windows x86_64 +- ✅ `node-ci.yml` — PR test matrix on 4 platforms +- ✅ `node-release.yml` — cross-compile, assemble platform packages, publish to npm on tag + +--- + +## Phase 8.3c Completion Status: ✅ COMPLETE + +**Phase 8.3c Features** (C FFI, complete — v0.24.0): +- ✅ `minigraf-c/src/lib.rs` — `cdylib` + `staticlib`; 7 exported functions: `minigraf_open`, `minigraf_open_in_memory`, `minigraf_execute`, `minigraf_string_free`, `minigraf_checkpoint`, `minigraf_close`, `minigraf_last_error` +- ✅ `minigraf-c/include/minigraf.h` — committed stable header (cbindgen-generated); header drift check in CI +- ✅ `c-ci.yml` — PR test matrix on 4 platforms + header drift check +- ✅ `c-release.yml` — builds platform tarballs (`.tar.gz` / `.zip`), uploads to GitHub Releases + +--- + +## Phase 8.3b Completion Status: ✅ COMPLETE + +**Phase 8.3b Features** (Java/JVM, complete — v0.23.0): +- ✅ `minigraf-ffi/java/` — Gradle 8.11 project: `build.gradle.kts`, `settings.gradle.kts`, `NativeLoader.kt` (runtime native extraction from JAR resources) +- ✅ `minigraf-ffi/java/src/test/kotlin/.../BasicTest.kt` — JUnit 5 suite: in-memory, transact/query, error handling, file-backed persistence +- ✅ `java-ci.yml` — PR test matrix on 4 platforms (Linux x86_64, Linux aarch64, macOS universal2, Windows x86_64) +- ✅ `java-release.yml` — cross-compiles natives, assembles fat JAR, publishes to Maven Central via NMCP + +--- + +## Phase 8.3a Completion Status: ✅ COMPLETE + +**Phase 8.3a Features** (Python, complete — v0.22.0): +- ✅ `minigraf-ffi/python/` — maturin project: `pyproject.toml`, Python extension module via UniFFI +- ✅ Pre-built wheels for Linux x86_64/aarch64, macOS universal2, Windows x86_64; no Rust toolchain required by end users +- ✅ `python-ci.yml` — PR test matrix on 4 platforms +- ✅ `python-release.yml` — builds wheels, publishes to PyPI on tag + +--- + +## Phase 8.2 Completion Status: ✅ COMPLETE + +**Phase 8.2 Features** (Mobile, complete — v0.21.0): +- ✅ `minigraf-ffi/src/lib.rs` — UniFFI 0.31 bindings: `MiniGrafDb` (open, openInMemory, execute, checkpoint), `MiniGrafError` (Parse, Query, Storage, Other) +- ✅ Android `.aar` release artifact — published to GitHub Packages (`io.github.adityamukho:minigraf-android`) +- ✅ iOS `.xcframework` release artifact — distributed via Swift Package Manager (`Package.swift` at repo root) +- ✅ `mobile.yml` CI — cross-compiles Android targets with `cargo-ndk`, generates Kotlin/Swift UniFFI bindings, assembles AAR and xcframework, publishes both on every tag +- ✅ `docs-check` CI job added to `rust.yml` and `release.yml` — gates releases on `cargo doc --all-features` passing cleanly + +--- + ## Phase 8.1 Completion Status: ✅ COMPLETE **Phase 8.1a Features** (browser WASM, complete): From 7b858e77977d961ba64de0e20dd3ca9374a56122 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 2 May 2026 07:53:15 +0530 Subject: [PATCH 06/11] docs(readme): fix stale WASM comparison table row --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d9df578b5a..81068c67dd 100644 --- a/README.md +++ b/README.md @@ -113,7 +113,7 @@ No other database offers this combination: | **Embedded** | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes | | **Graph Native** | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No | | **Rust** | ✅ Yes | ❌ Clojure | ✅ Yes | ❌ Java | ❌ C | -| **WASM Ready** | ✅ Phase 8.1a/b | ❌ No | ⚠️ Limited | ❌ No | ✅ Yes | +| **WASM Ready** | ✅ Yes (browser + WASI + 6 targets) | ❌ No | ⚠️ Limited | ❌ No | ✅ Yes | ## Platform support From b21e96892ca256ca2f193f0722c980e7ee2e0e09 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 2 May 2026 07:53:24 +0530 Subject: [PATCH 07/11] docs(roadmap): mark Phase 8 complete, update timeline and Current Focus to v1.0.0 --- ROADMAP.md | 58 +++++++++++++++++++++++++++++------------------------- 1 file changed, 31 insertions(+), 27 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 4a2242cea1..f2922d8d19 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1105,11 +1105,11 @@ The query optimizer uses selectivity estimates to pick join order. Different `:a --- -## Phase 8: Cross-Platform Expansion 🔄 IN PROGRESS +## Phase 8: Cross-Platform Expansion ✅ COMPLETE **Goal**: WASM, mobile, language bindings -**Status**: 🔄 In Progress (Phase 8.1 complete — v0.20.0) +**Status**: ✅ Completed (May 2026) — v1.0.0 **Priority**: 🟢 Medium @@ -1203,7 +1203,9 @@ cargo build --target wasm32-wasip1 --release **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 +### 8.2 Mobile Bindings ✅ COMPLETE + +**Status**: ✅ Completed (April 2026) — v0.21.0 **Goal**: Ship Minigraf as a drop-in native library for Android (Kotlin/Java) and iOS (Swift), with pre-built artifacts so mobile developers don't need to touch Rust. @@ -1587,10 +1589,14 @@ 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) +### v1.0.0 - ✅ Phase 8 Complete (Cross-platform) +- Browser WASM (`@minigraf/browser` npm, IndexedDB backend) ✅ v0.20.0 +- WASI (`wasm32-wasip1`, Wasmtime/Wasmer CI) + `@minigraf/wasi` npm package ✅ v1.0.0 +- Android `.aar` + iOS `.xcframework` (UniFFI) ✅ v0.21.0 +- Python `minigraf` on PyPI ✅ v0.22.0 +- Java/JVM `minigraf-jvm` on Maven Central ✅ v0.23.0 +- C FFI `minigraf.h` + platform tarballs ✅ v0.24.0 +- Node.js `minigraf` on npm ✅ v0.25.0 **Stability Promise**: After v1.0.0, we commit to: - Backwards-compatible file format (decades) @@ -1651,8 +1657,12 @@ When evaluating features, ask: - ✅ 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.1: Complete (April 2026) - Browser WASM (`BrowserDb`, IndexedDB backend) + WASI (`wasm32-wasip1` CI) + cross-platform compat tests, 795 tests -- 🔄 Phase 8.2: In progress — Mobile bindings (Android `.aar` + iOS `.xcframework` via UniFFI 0.31.1), 815 tests -- 🔄 Phase 8: In progress (Cross-platform — WASM ✅, mobile, language bindings → **v1.0.0**) +- ✅ Phase 8.2: Complete (April 2026) — Mobile bindings (Android `.aar` + iOS `.xcframework` via UniFFI 0.31.1), 795 tests +- ✅ Phase 8.3a: Complete (April 2026) — Python `minigraf` on PyPI, 795 tests +- ✅ Phase 8.3b: Complete (April 2026) — Java/JVM `minigraf-jvm` on Maven Central, 795 tests +- ✅ Phase 8.3c: Complete (April 2026) — C FFI `minigraf.h` + platform tarballs, 795 tests +- ✅ Phase 8.3d: Complete (April 2026) — Node.js `minigraf` on npm, 795 tests +- ✅ Phase 8: Complete (May 2026) — v1.0.0 - 🎯 Phase 9: Ongoing (Ecosystem — integration examples, cookbook, GraphRAG/LangChain examples) **Note**: This is a hobby project. Timeline is flexible but realistic. @@ -1661,24 +1671,18 @@ When evaluating features, ask: ## Current Focus -**Right Now**: Phase 8.3 ✅ COMPLETE — Language Bindings - -**Phase 8.2 Progress** ✅ COMPLETE: -1. ✅ Workspace conversion (`minigraf-ffi` crate added) -2. ✅ `MiniGrafDb` FFI API (open, open_in_memory, execute, checkpoint) via UniFFI 0.31.1 -3. ✅ Android Gradle project (`.aar` assembly + GitHub Packages publishing) -4. ✅ Swift Package Manager manifest (`Package.swift`) -5. ✅ CI workflows: `mobile.yml` (Android/iOS), `wasm-release.yml` (WASM artifacts) -6. ✅ 815 tests passing (795 core + 20 FFI) +**Phase 8**: ✅ COMPLETE — v1.0.0 released (May 2026) -**Phase 8.3 Progress**: -- ✅ 8.3a: Python bindings via UniFFI — PyPI `minigraf` — v0.22.0 COMPLETE -- ✅ 8.3b: Desktop JVM bindings — fat JAR on Maven Central (`io.github.adityamukho:minigraf-jvm:0.23.0`) — v0.23.0 COMPLETE -- ✅ 8.3c: C bindings via `cbindgen` — GitHub Releases tarballs (`minigraf.h` + shared lib) — v0.24.0 COMPLETE -- ✅ 8.3d: Node.js bindings via `napi-rs` — npm `minigraf` — v0.25.0 COMPLETE +**All Phase 8 sub-phases complete**: +- ✅ 8.1a: Browser WASM (`@minigraf/browser` npm) — v0.20.0 +- ✅ 8.1b: WASI (`wasm32-wasip1`) + `@minigraf/wasi` npm — v1.0.0 +- ✅ 8.2: Mobile (Android `.aar` + iOS `.xcframework`) — v0.21.0 +- ✅ 8.3a: Python (PyPI) — v0.22.0 +- ✅ 8.3b: Java/JVM (Maven Central) — v0.23.0 +- ✅ 8.3c: C FFI (GitHub Releases) — v0.24.0 +- ✅ 8.3d: Node.js (npm) — v0.25.0 -**Immediate Next Steps**: -- Phase 9: Ecosystem & Tooling +**Next**: Phase 9 — Ecosystem & Tooling (post-release optimisation and benchmarking first) **Key Decisions Made**: - ✅ Datalog query language (simpler, better for temporal) @@ -1688,10 +1692,10 @@ 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) -- ✅ Phase 8 = v1.0.0 (not Phase 7 — cross-platform completion is the 1.0 milestone) +- ✅ Phase 8 = v1.0.0 (cross-platform completion is the 1.0 milestone) See [GitHub Issues](https://github.com/project-minigraf/minigraf/issues) for specific tasks. --- -**Last Updated**: Phase 8.3d Complete (April 2026) — 795 tests passing, v0.25.0 +**Last Updated**: Phase 8 Complete (May 2026) — 795 tests passing, v1.0.0 From a922e56351792b4a6a0ee4318331b65da3fba483 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 2 May 2026 07:57:00 +0530 Subject: [PATCH 08/11] docs(contributing): replace stale pre-publish checklist with release process pointer --- CONTRIBUTING.md | 44 ++++++++++---------------------------------- 1 file changed, 10 insertions(+), 34 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index edff211435..065ec664a1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,7 +16,7 @@ Thank you for your interest in contributing. Minigraf is a hobby project with a - Performance improvements with benchmarks showing the gain - Documentation improvements and example additions - Test coverage improvements (especially error-path coverage) -- Cross-platform compatibility fixes (Linux, macOS, Windows, eventually WASM/mobile) +- Cross-platform compatibility fixes (Linux, macOS, Windows, WASM, mobile, language bindings) ## What We Will Not Merge @@ -69,7 +69,7 @@ Run branch coverage and open the HTML report: cargo llvm-cov --branch --open ``` -The Phase 7.5 target is ≥90% branch coverage on `src/query/datalog/` modules. Re-run after adding tests to confirm progress. +Run branch coverage to check overall project health before submitting a PR. ## Code Standards @@ -101,40 +101,16 @@ Before submitting, ask yourself: If you answer "yes" to the last two questions, reconsider. If in doubt, open an issue and discuss first. -## Pre-Publishing Checklist (crates.io) +## Release Process -**Do not publish before Phase 7.8.** Before publishing, verify all of the following: +Releases are managed by the project maintainer. The process is documented in issue #133 and the +`docs/superpowers/specs/` design files. For each release: -### Minimum Bar -- [x] Phase 6.4 benchmarks complete (`BENCHMARKS.md`) -- [x] Phase 6.5 complete — on-disk B+tree, file format v6 -- [x] Phase 7.1 complete — stratified negation, 407 tests passing -- [ ] Checkpoint-during-crash recovery exercised (Phase 7.5) -- [ ] Error-path coverage ≥90% (currently ~82%) (Phase 7.5) -- [x] GitHub Discussions enabled - -### API Cleanup (Phase 7.8) -- [ ] Narrow `lib.rs` exports — expose only `Minigraf`, `WriteTransaction`, and query/result types; hide `PersistentFactStorage`, `FileHeader`, `PAGE_SIZE`, `Repl`, `Wal`, etc. -- [x] Remove dead `clap` dependency ✅ - -### Crate Metadata (`Cargo.toml`) -- [x] `repository`, `keywords`, `categories`, `readme`, `documentation` fields set -- [ ] Verify `description` is accurate and compelling (Phase 7.8) - -### Documentation (Phase 7.8) -- [ ] All public API items have rustdoc comments with examples -- [ ] `README.md` quick-start example compiles and runs -- [ ] `CHANGELOG.md` up to date - -### Quality Gates (Phase 7.8) -- [ ] `cargo test` passes on Linux, macOS, Windows (CI matrix) -- [ ] `cargo clippy -- -D warnings` passes -- [ ] `cargo doc --no-deps` builds without warnings -- [ ] No `unwrap()`/`expect()` in library code paths (tests and binary are fine) - -### Versioning -- [ ] Publish as `0.x` — no backwards-compat promise until v1.0.0 (Phase 7.8) -- [ ] Stable API target is v1.0.0 — after Phase 8 cross-platform work +1. All prerequisite issue PRs merged and CI green +2. Version bumped consistently across all manifests (`Cargo.toml`, `package.json`, `pyproject.toml`, `build.gradle.kts`, `Package.swift`) +3. `cargo check --workspace` passes cleanly +4. All docs synced (see `CLAUDE.md` — "Sync all docs at phase completion") +5. Tag pushed — CI publishes to crates.io, PyPI, npm, and Maven Central automatically ## Code of Conduct From dde86d2766887ea3286f4ee2db7ecff2576b66fb Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 2 May 2026 07:57:30 +0530 Subject: [PATCH 09/11] docs: rewrite minigraf-wasm/README.md as @minigraf/browser npm README Replace stale generic Minigraf README with browser-specific documentation covering IndexedDB persistence, Datalog queries, time travel, export/import, and browser-specific constraints. Includes maintainer note about wasm-pack clobbering and canonical README source location. Co-Authored-By: Claude Sonnet 4.6 --- minigraf-wasm/README.md | 213 +++++++++++----------------------------- 1 file changed, 57 insertions(+), 156 deletions(-) diff --git a/minigraf-wasm/README.md b/minigraf-wasm/README.md index a374142d0a..758f9b747f 100644 --- a/minigraf-wasm/README.md +++ b/minigraf-wasm/README.md @@ -1,186 +1,87 @@ -# Minigraf +# @minigraf/browser -[![crates.io](https://img.shields.io/crates/v/minigraf.svg)](https://crates.io/crates/minigraf) -[![docs.rs](https://docs.rs/minigraf/badge.svg)](https://docs.rs/minigraf) -[![Build Status](https://github.com/project-minigraf/minigraf/actions/workflows/rust.yml/badge.svg)](https://github.com/project-minigraf/minigraf/actions/workflows/rust.yml) -[![Clippy Status](https://github.com/project-minigraf/minigraf/actions/workflows/rust-clippy.yml/badge.svg)](https://github.com/project-minigraf/minigraf/actions/workflows/rust-clippy.yml) -[![Coverage](https://codecov.io/gh/project-minigraf/minigraf/branch/main/graph/badge.svg)](https://codecov.io/gh/project-minigraf/minigraf) +[![npm](https://img.shields.io/npm/v/@minigraf/browser.svg)](https://www.npmjs.com/package/@minigraf/browser) [![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](https://github.com/project-minigraf/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/project-minigraf/minigraf/blob/main/ROADMAP.md) -> **Embedded graph memory for AI agents, mobile apps, and the browser** — the SQLite of bi-temporal graph databases +> Embedded bi-temporal graph database for the browser — Datalog queries, time travel, IndexedDB persistence -A tiny, self-contained graph database with **Datalog queries** and **bi-temporal time travel**. Think SQLite, but for connected data with full history. +Minigraf in the browser: zero configuration, persistent graph storage backed by IndexedDB, Datalog queries with recursive rules and time travel. One API, no server required. -## Vision - -Minigraf is a **single-file embedded graph database** that lets you: -- ✅ **Query relationships with Datalog** - Recursive rules, natural graph traversal -- ✅ **Time travel through history** - Bi-temporal queries (transaction time + valid time) -- ✅ **Window functions** - `sum/count/min/max/avg/rank/row-number :over (partition-by … :order-by …)` in `:find` clauses -- ✅ **Prepared statements** - Parse + plan once with `$slot` bind tokens, execute thousands of times -- ✅ **Embed anywhere** - Native, WASM, mobile, IoT - one `.graph` file -- ✅ **Zero configuration** - Just `Minigraf::open("data.graph")` and you're done - -**Status**: See [ROADMAP.md](ROADMAP.md) for current phase and what's next. - -## Why Datalog? - -**Datalog is fundamentally better for graphs than SQL-like languages:** - -1. **Recursive by design** - Multi-hop traversals are natural, not an afterthought -2. **Simpler to implement** - Smaller spec = more reliable, faster to production -3. **Perfect for temporal** - Time is just another dimension in relations -4. **Proven at scale** - 40+ years of research, production use (Datomic, XTDB) -5. **Graph-native** - Facts (Entity-Attribute-Value) are literally edges -6. **LLM-friendly** - The small, uniform grammar (`[?e :attr ?v]` patterns, no JOIN variants, no subquery nesting) is easy for AI coding assistants to generate correctly from a few examples; the entire language fits in a system prompt - -## Installation - -```toml -[dependencies] -minigraf = "0.19" -``` - -Or via cargo: +## Install ```sh -cargo add minigraf +npm install @minigraf/browser ``` -## Quick Start +## Quick start -```rust -use minigraf::{Minigraf, OpenOptions}; +```javascript +import init, { BrowserDb } from '@minigraf/browser'; +await init(); -// Open or create a file-backed database -let db = OpenOptions::new().path("myapp.graph").open()?; +// Persistent database (survives page reloads — backed by IndexedDB) +const db = await BrowserDb.open('my-graph'); -// Add facts -db.execute(r#"(transact [[:alice :person/name "Alice"] - [:alice :person/age 30] - [:alice :friend :bob] - [:bob :person/name "Bob"]])"#)?; +// In-memory database (ephemeral / testing) +const mem = BrowserDb.openInMemory(); -// Query with Datalog -let results = db.execute(r#" - (query [:find ?friend-name - :where [:alice :friend ?friend] - [?friend :person/name ?friend-name]]) -"#)?; - -// Explicit transaction — all-or-nothing -let mut tx = db.begin_write()?; -tx.execute(r#"(transact [[:alice :person/age 31]])"#)?; -tx.commit()?; - -// Time travel — query as of past transaction counter -db.execute("(query [:find ?age :as-of 1 :where [:alice :person/age ?age]])")?; - -// Recursive rule — transitive reachability -db.execute(r#"(rule [(reachable ?a ?b) [?a :friend ?b]]) - (rule [(reachable ?a ?b) [?a :friend ?m] (reachable ?m ?b)])"#)?; - -// Prepared statement — parse + plan once, execute many times -use minigraf::BindValue; -let pq = db.prepare("(query [:find ?name :as-of $tx :where [$entity :person/name ?name]])")?; -let r1 = pq.execute(&[("tx", BindValue::TxCount(1)), ("entity", BindValue::Entity(alice_id))])?; -let r2 = pq.execute(&[("tx", BindValue::TxCount(2)), ("entity", BindValue::Entity(bob_id))])?; -``` +// Transact facts +const r = JSON.parse(await db.execute( + '(transact [[:alice :person/name "Alice"] [:alice :person/age 30]])' +)); +// { "transacted": 1 } -```bash -cargo run # interactive Datalog REPL -cargo test # run 780 tests -cargo run < demos/demo_recursive.txt # recursive rules demo +// Query with Datalog +const q = JSON.parse(await db.execute( + '(query [:find ?name ?age :where [?e :person/name ?name] [?e :person/age ?age]])' +)); +// { "variables": ["?name", "?age"], "results": [["Alice", 30]] } + +// Time travel — state as of transaction 1 +const snap = JSON.parse(await db.execute( + '(query [:find ?age :as-of 1 :where [:alice :person/age ?age]])' +)); ``` -## Demo - -See a working implementation of **temporal reasoning** with Minigraf at [github.com/adityamukho/temporal_reasoning](https://github.com/adityamukho/temporal_reasoning) — an AI agent that uses Minigraf's bi-temporal model to store, correct, and audit beliefs. - -See the [Datalog Reference](https://github.com/project-minigraf/minigraf/wiki/Datalog-Reference) wiki page for the complete syntax. - -## Why Minigraf? - -No other database offers this combination: - -| Feature | Minigraf | XTDB | Cozo | Neo4j | SQLite | -|---|---|---|---|---|---| -| **Query Language** | Datalog | Datalog | Datalog | Cypher | SQL | -| **Single File** | ✅ Yes | ❌ No | ❌ No | ❌ No | ✅ Yes | -| **Bi-temporal** | ✅ Yes | ✅ Yes | ⚠️ Time travel | ❌ No | ❌ No | -| **Embedded** | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes | -| **Graph Native** | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No | -| **Rust** | ✅ Yes | ❌ Clojure | ✅ Yes | ❌ Java | ❌ C | -| **WASM Ready** | ✅ Phase 8.1a/b | ❌ No | ⚠️ Limited | ❌ No | ✅ Yes | - -**Embedded graph memory for agents, mobile, and the browser — SQLite's simplicity + Datomic's temporal model.** +## Response shapes -See the [Comparison](https://github.com/project-minigraf/minigraf/wiki/Comparison) wiki page for detailed analysis including temporal vs. time-series databases. - -### For AI Agents - -Store what an agent believes, retract and correct without losing history, and replay past states to audit decisions. Every fact carries both transaction time (when it was recorded) and valid time (when it was true), so you can reconstruct the exact knowledge state at the moment of any past decision. - -Pairs well with vector stores (GraphRAG pattern): the vector store answers "what is similar?"; Minigraf answers "what are the relationships, who recorded them, and what did we believe at time T?" - -### For Mobile Apps - -Offline-first storage with retroactive corrections — the bi-temporal model lets you correct a mis-entered value while preserving the original record. Phase 8 will ship iOS `.xcframework` and Android `.aar` via UniFFI. - -### For WASM / Browser - -Phase 8.1a complete: IndexedDB backend, `wasm-pack` packaging. Phase 8.1b complete: server-side WASM via `wasm32-wasip1` / WASI (Wasmtime, Wasmer). npm release as `@minigraf/browser` planned for Phase 8.2. - -See the [Use Cases](https://github.com/project-minigraf/minigraf/wiki/Use-Cases) wiki page for detailed guides on all three targets. - -## Scope - -Minigraf runs as: -- ✅ An embedded library -- ✅ A standalone binary (interactive REPL) -- ✅ A WebAssembly module — browser (`wasm32-unknown-unknown`) and server-side WASI (`wasm32-wasip1`) (Phase 8.1a/b complete) +| Command | JSON | +|---|---| +| `transact` | `{"transacted": }` | +| `retract` | `{"retracted": }` | +| `query` | `{"variables": [...], "results": [[...]]}` | +| `rule` | `{"ok": true}` | -Minigraf will **not** be (by design): -- **Distributed** — no clustering, no sharding, no replication; each agent instance owns its own `.graph` file -- **Client-server** — no network protocol in core -- **Billion-node scale** — optimised for <1M nodes (like SQLite) -- **A time-series database** — Minigraf is a *temporal* database; see [Comparison](https://github.com/project-minigraf/minigraf/wiki/Comparison#influxdb--prometheus--timescaledb-time-series-databases) +## Export / import -## Roadmap +The `.graph` binary format is byte-identical between browser and native builds. Export a snapshot or load a native-generated file: -See [ROADMAP.md](ROADMAP.md) for the full phase plan, current status, and release strategy. +```javascript +// Export (Uint8Array — byte-identical to a native .graph file) +const bytes = db.exportGraph(); -## Performance +// Import a native .graph file (must be checkpointed — no pending WAL) +const file = document.querySelector('input[type=file]').files[0]; +await db.importGraph(new Uint8Array(await file.arrayBuffer())); +``` -Benchmarks on Intel Core i7-1065G7 @ 1.30GHz, 16 GB RAM, Rust 1.92.0. See [BENCHMARKS.md](BENCHMARKS.md) for full tables. +## Constraints -| Metric | Result | -|---|---| -| Insert (in-memory, single fact) | ~2.7 µs — flat across 1K–100K facts | -| Insert (file-backed, WAL) | ~3.6 µs — flat across 1K–100K facts | -| Point query at 1M facts | 4.3–4.5 s (O(N) scan; Phase 7 target: predicate pushdown) | -| Open time at 1M facts | 1.31 s (2.4× faster than v5 — indexes no longer loaded into RAM) | -| Peak heap at 1M facts | 1.05 GB (~21% less than v5 — indexes paged in on demand) | +- Requires a browser environment with IndexedDB. Not compatible with Node.js — use the [`minigraf` npm package](https://www.npmjs.com/package/minigraf) for Node.js instead. +- Single-threaded. Runs on the main thread or in a Web Worker; no shared state across workers. -File-backed databases enforce a maximum fact size of **4 080 serialised bytes** per fact. In-memory databases have no limit. +## wasm-pack clobbering note (for maintainers) -## Contributing +`wasm-pack build` may overwrite this file. If it does, `wasm-release.yml` must copy the canonical +README from a stable source (e.g. a root-level `minigraf-wasm.README.md`) into the build output +directory before `npm publish`. Verify this on first release after any `wasm-pack` version upgrade. -This is a hobby project with a long-term vision. Read [PHILOSOPHY.md](PHILOSOPHY.md) and [ROADMAP.md](ROADMAP.md) before proposing features. +## Links -See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code standards, and the PR process. +- [Full browser integration guide](https://github.com/project-minigraf/minigraf/wiki/Use-Cases#wasm--browser) +- [Repository](https://github.com/project-minigraf/minigraf) +- [Datalog Reference](https://github.com/project-minigraf/minigraf/wiki/Datalog-Reference) ## License -Licensed under either of: - -- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) -- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) - -at your option. - -### Contribution - -Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. +MIT OR Apache-2.0 From 712e7810dc63420adfcc2950f1ef0cd41d02a698 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 2 May 2026 07:57:49 +0530 Subject: [PATCH 10/11] =?UTF-8?q?docs(llms.txt):=20full=20rewrite=20for=20?= =?UTF-8?q?v1.0.0=20=E2=80=94=20version,=20platforms,=20prepared=20stateme?= =?UTF-8?q?nts,=20source=20layout,=20links?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- llms.txt | 62 ++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 47 insertions(+), 15 deletions(-) diff --git a/llms.txt b/llms.txt index d757ba4682..af58a26938 100644 --- a/llms.txt +++ b/llms.txt @@ -4,13 +4,16 @@ Minigraf is the SQLite of graph databases: zero configuration, one `.graph` file, embedded as a library. It stores facts in an Entity-Attribute-Value (EAV) model and queries them with Datalog, including recursive rules for graph traversal and stratified negation (`not` / `not-join`). Every fact carries two independent time dimensions (transaction time and valid time), enabling full bi-temporal time travel. -**Current version**: 0.14.0 (pre-1.0 — API and file format may change before v1.0) -**Maturity**: See [README](https://github.com/project-minigraf/minigraf/blob/main/README.md) for current phase and [ROADMAP](https://github.com/project-minigraf/minigraf/blob/main/ROADMAP.md) for the full plan. ACID + WAL are production-quality. Covering indexes (EAVT/AEVT/AVET/VAET), packed page storage, LRU page cache, and on-disk B+tree indexes are complete. Stratified negation, scalar aggregation, arithmetic/predicate expression clauses, and disjunction (`or`/`or-join`) are complete. Cross-feature integration tests and error-path coverage complete; ~86–89% branch coverage, 617 tests (Phase 7.5). Not recommended for production use until v1.0 (file format stability guaranteed only after Phase 8). +**Current version**: 1.0.0 +**Maturity**: ACID + WAL are production-quality. Covering indexes (EAVT/AEVT/AVET/VAET), packed page storage, LRU page cache, and on-disk B+tree indexes are complete. Stratified negation, scalar aggregation, arithmetic/predicate expression clauses, disjunction (`or`/`or-join`), window functions (`sum/count/min/max/avg/rank/row-number`), user-defined functions, and prepared statements are complete. Phase 8 complete: Browser WASM (`@minigraf/browser` npm), WASI (`wasm32-wasip1`, `@minigraf/wasi` npm), Android/iOS (UniFFI), Python (PyPI), Java/JVM (Maven Central), C FFI, and Node.js (npm) all ship at v1.0.0. File format stable from v1.0.0. 795 tests. ## Use for - **Agent memory with provenance**: Store facts an agent asserted, when it asserted them, and query any past state. Retract and correct beliefs without losing history. Rewind to the exact knowledge state at the moment of a bad decision for root cause analysis. - **Verifiable agent reasoning**: Preserve an agent's full decision-making lineage. Post-hoc audits can reconstruct what the agent believed at any transaction counter or timestamp. +- **Browser agent memory**: Run entirely client-side with `@minigraf/browser` (npm). Persists to IndexedDB; portable `.graph` files are byte-identical to native. +- **Mobile offline-first applications**: Android (Kotlin/Java) and iOS (Swift) native bindings via UniFFI. No Rust required. Same single-file `.graph` format. +- **Python/Node.js/Java scripting and server-side embedding**: Pre-built packages on PyPI, npm, and Maven Central. No build step required. - **Task planning agents**: Model sub-task DAGs as a graph. Update dependencies and status over time. Query historical task states with `:as-of`. - **Code dependency / debugging agents**: Embed call graphs or module dependency graphs; traverse with recursive Datalog rules. - **Audit-trail applications**: Compliance-grade history where both "what was recorded when" (transaction time) and "what was true when" (valid time) matter independently. @@ -52,13 +55,16 @@ Query either axis independently or together: The unit of storage is `(entity, attribute, value, valid_from, valid_to, tx_id, tx_count, asserted)`. Entities are UUIDs. Attributes are keywords (`:person/name`). Values are strings, integers, floats, booleans, entity refs, keywords, or null. **Datalog queries** -Pattern matching with variable unification. Recursive rules use semi-naive fixed-point evaluation. Transitive closure and cycle-safe graph traversal are first-class. Stratified negation (`not` / `not-join`), scalar aggregation (`count`, `sum`, `min`, `max`, `count-distinct`, `sum-distinct`), arithmetic/predicate expression clauses (`[(< ?age 30)]`, `[(+ ?a ?b) ?c]`), and disjunction (`or` / `or-join`) are all supported. +Pattern matching with variable unification. Recursive rules use semi-naive fixed-point evaluation. Transitive closure and cycle-safe graph traversal are first-class. Stratified negation (`not` / `not-join`), scalar aggregation (`count`, `sum`, `min`, `max`, `count-distinct`, `sum-distinct`), arithmetic/predicate expression clauses (`[(< ?age 30)]`, `[(+ ?a ?b) ?c]`), disjunction (`or` / `or-join`), window functions (`sum/count/min/max/avg/rank/row-number :over (:partition-by … :order-by …)`), and user-defined functions (custom aggregates + predicates via `FunctionRegistry`) are all supported. + +**Prepared statements** +Parse and plan a query once; execute thousands of times with different bind values. `$slot` tokens accepted in entity, value, `:as-of`, and `:valid-at` positions. `BindValue` variants: `Entity(Uuid)`, `Val(Value)`, `TxCount(u64)`, `Timestamp(i64)`, `AnyValidTime`. **ACID transactions** `begin_write()` → `commit()` / `rollback()`. Fact-level WAL with CRC32 protection. Crash recovery on open. **Single-file storage** -Page-based `.graph` file (4 KB pages, magic `MGRF`, format v6). Packed fact pages (~25 facts/page). On-disk B+tree indexes (EAVT/AEVT/AVET/VAET) with LRU page cache. WAL sidecar (`.wal`) deleted on clean close. Automatic migration from v1–v5. Endian-safe, cross-platform. +Page-based `.graph` file (4 KB pages, magic `MGRF`, format v7). Packed fact pages (~25 facts/page). On-disk B+tree indexes (EAVT/AEVT/AVET/VAET) with LRU page cache. WAL sidecar (`.wal`) deleted on clean close. Automatic migration from v1–v6. Endian-safe, cross-platform. File format stable from v1.0.0. ## API (Rust) @@ -102,6 +108,14 @@ db.execute("(query [:find ?status :as-of 10 :where [:agent-1 :employment/status db.execute(r#"(query [:find ?status :valid-at "2024-06-01" :where [:agent-1 :employment/status ?status]])"#)?; +// Prepared statement — parse once, execute many times with $slot bind tokens +use minigraf::BindValue; +let pq = db.prepare( + "(query [:find ?fact :as-of $tx :where [$entity :belief/fact ?fact]])" +)?; +let r1 = pq.execute(&[("tx", BindValue::TxCount(5)), ("entity", BindValue::Entity(agent_id))])?; +let r2 = pq.execute(&[("tx", BindValue::TxCount(10)), ("entity", BindValue::Entity(agent_id))])?; + // Explicit transaction let mut tx = db.begin_write()?; tx.execute(r#"(retract [[:agent-1 :belief/fact "Paris is in France"]])"#)?; @@ -124,19 +138,23 @@ tx.commit()?; (query [:find ?var ... ;; plain variable (count ?e) ;; aggregate: count, count-distinct, (sum ?salary) ;; sum, sum-distinct, min, max + (sum ?v :over (:order-by ?v)) ;; window: sum/count/min/max/avg/rank/row-number :with ?grouping-var ... ;; optional, extra grouping variables :as-of ;; optional, transaction time :valid-at <"ISO8601"|:any-valid-time> ;; optional, valid time :where [ ] ... (not [ ] ...) ;; optional, negation (not-join [?join-var ...] ...) ;; optional, existential negation - (or branch1 branch2 ...) ;; optional, disjunction (all branches bind same vars) + (or branch1 branch2 ...) ;; optional, disjunction (or-join [?v ...] b1 b2 ...) ;; optional, existential disjunction - (and clause1 clause2 ...) ;; group clauses into one branch (inside or/or-join) - [( ?a ?b)] ;; filter predicate: <, >, <=, >=, =, !=, string?, etc. + (and clause1 clause2 ...) ;; group clauses (inside or/or-join) + [( ?a ?b)] ;; filter predicate: <, >, <=, >=, =, !=, string? [( ?a ?b) ?result] ;; arithmetic binding: +, -, *, / ]) +;; Prepared statement with $slot bind tokens +(query [:find ?fact :as-of $tx :where [$entity :belief/fact ?fact]]) + ;; Recursive rule (rule [( ?arg ...) ...]) @@ -149,25 +167,32 @@ tx.commit()?; ## Source layout -- `src/db.rs` — public API: `Minigraf`, `OpenOptions`, `WriteTransaction` +- `src/db.rs` — public API: `Minigraf`, `OpenOptions`, `WriteTransaction`, `PreparedQuery`, `BindValue`; `register_aggregate` / `register_predicate` for UDFs; `prepare(query_str)` - `src/graph/types.rs` — `Fact`, `Value`, EAV types, bi-temporal fields - `src/graph/storage.rs` — in-memory fact store with temporal query methods and `net_asserted_facts` -- `src/query/datalog/` — parser, executor, matcher, evaluator, optimizer, stratification, rules, types +- `src/query/datalog/` — parser, executor, matcher, evaluator, optimizer, stratification, rules, types, functions, prepared - `src/query/datalog/stratification.rs` — `DependencyGraph`, `stratify()` — negative edges + cycle detection - `src/query/datalog/evaluator.rs` — `RecursiveEvaluator` (semi-naive), `StratifiedEvaluator`, `evaluate_not_join` -- `src/storage/mod.rs` — `StorageBackend` trait, `FileHeader` v6, `CommittedFactReader` / `CommittedIndexReader` traits -- `src/storage/backend/` — file, memory backends +- `src/query/datalog/functions.rs` — `FunctionRegistry`: aggregate/window/predicate registry; UDF registration +- `src/query/datalog/prepared.rs` — `PreparedQuery`: parse-once/execute-many; `BindValue` enum; `$slot` substitution +- `src/storage/mod.rs` — `StorageBackend` trait, `FileHeader` v7, `CommittedFactReader` / `CommittedIndexReader` traits +- `src/storage/backend/` — `file.rs` (native), `memory.rs` (tests), `indexeddb.rs` (browser WASM) - `src/storage/index.rs` — EAVT/AEVT/AVET/VAET index key types, `FactRef`, `encode_value` - `src/storage/btree_v6.rs` — on-disk B+tree (current); `btree.rs` — legacy v5 (migration only) - `src/storage/cache.rs` — LRU page cache (approximate-LRU, configurable capacity) - `src/storage/packed_pages.rs` — packed fact page format (~25 facts/4KB page), `MAX_FACT_BYTES` -- `src/storage/persistent_facts.rs` — v6 save/load, auto-migration v1–v5→v6 +- `src/storage/persistent_facts.rs` — v7 save/load, auto-migration v1–v6→v7 - `src/wal.rs` — write-ahead log, CRC32 entries, crash recovery - `src/temporal.rs` — UTC timestamp parsing (avoids chrono CVE GHSA-wcg3-cvx6-7396) +- `minigraf-ffi/src/lib.rs` — UniFFI bindings: `MiniGrafDb`, `MiniGrafError` (Android, iOS, Python, Java) +- `minigraf-c/src/lib.rs` — C FFI (`cdylib` + `staticlib`): `minigraf_open`, `minigraf_execute`, `minigraf_string_free`, `minigraf_checkpoint`, `minigraf_close`, `minigraf_last_error` +- `minigraf-node/src/lib.rs` — Node.js bindings via napi-rs: `MiniGrafDb` class +- `minigraf-wasm/` — wasm-pack output: `@minigraf/browser` npm package (IndexedDB-backed browser WASM) +- `minigraf-wasi/` — `@minigraf/wasi` npm package: ESM loader, TypeScript declarations, `minigraf-wasi.wasm` -## Performance summary (v0.13.0) +## Performance summary (v0.19.0) -See [BENCHMARKS.md](https://github.com/project-minigraf/minigraf/blob/main/BENCHMARKS.md) for full tables and methodology. +See [BENCHMARKS.md](https://github.com/project-minigraf/minigraf/blob/main/BENCHMARKS.md) for full tables and methodology. Phase 8 (v0.20.0–v1.0.0) added cross-platform targets without touching the native query or storage path — benchmark numbers are unchanged from Phase 7. - **Insert**: ~2.7 µs/fact (in-memory), ~3.6 µs/fact (file-backed WAL). Flat across 1K–100K facts. - **Query (point lookup)**: O(N) full scan — 4.3–4.5 s at 1M facts. @@ -177,6 +202,7 @@ See [BENCHMARKS.md](https://github.com/project-minigraf/minigraf/blob/main/BENCH ## Links - [Repository](https://github.com/project-minigraf/minigraf) +- [crates.io](https://crates.io/crates/minigraf) - [README](https://github.com/project-minigraf/minigraf/blob/main/README.md) — current status and quick start - [ROADMAP](https://github.com/project-minigraf/minigraf/blob/main/ROADMAP.md) — phase-by-phase plan - [BENCHMARKS](https://github.com/project-minigraf/minigraf/blob/main/BENCHMARKS.md) — Criterion results at 1K–1M facts @@ -184,5 +210,11 @@ See [BENCHMARKS.md](https://github.com/project-minigraf/minigraf/blob/main/BENCH - [Security Policy](https://github.com/project-minigraf/minigraf/security/policy) - [Wiki: Architecture](https://github.com/project-minigraf/minigraf/wiki/Architecture) — module structure, data model, file format, query pipeline - [Wiki: Datalog Reference](https://github.com/project-minigraf/minigraf/wiki/Datalog-Reference) — complete syntax reference -- [Wiki: Use Cases](https://github.com/project-minigraf/minigraf/wiki/Use-Cases) — AI agents, mobile apps, WASM/browser +- [Wiki: Use Cases](https://github.com/project-minigraf/minigraf/wiki/Use-Cases) — AI agents, mobile, browser, Python, Node.js, Java, C - [Wiki: Comparison](https://github.com/project-minigraf/minigraf/wiki/Comparison) — vs XTDB, Cozo, Datomic, Neo4j, SQLite and others +- [@minigraf/browser on npm](https://www.npmjs.com/package/@minigraf/browser) — Browser WASM +- [@minigraf/wasi on npm](https://www.npmjs.com/package/@minigraf/wasi) — WASI / Node.js +- [minigraf on npm](https://www.npmjs.com/package/minigraf) — Node.js +- [minigraf on PyPI](https://pypi.org/project/minigraf) — Python +- [minigraf-jvm on Maven Central](https://central.sonatype.com/artifact/io.github.adityamukho/minigraf-jvm) — Java/JVM +- [C header + libraries on GitHub Releases](https://github.com/project-minigraf/minigraf/releases) — C FFI, WASI `.wasm`, Android `.aar`, iOS `.xcframework` From a564892041f363da32349f79f0307d4aea07fb35 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 2 May 2026 07:59:44 +0530 Subject: [PATCH 11/11] docs: add per-platform READMEs for Node.js, Python, C FFI, and Java/JVM packages Co-Authored-By: Claude Sonnet 4.6 --- minigraf-c/README.md | 86 +++++++++++++++++++++++++++++++++++ minigraf-ffi/java/README.md | 66 +++++++++++++++++++++++++++ minigraf-ffi/python/README.md | 59 ++++++++++++++++++++++++ minigraf-node/README.md | 65 ++++++++++++++++++++++++++ 4 files changed, 276 insertions(+) create mode 100644 minigraf-c/README.md create mode 100644 minigraf-ffi/java/README.md create mode 100644 minigraf-ffi/python/README.md create mode 100644 minigraf-node/README.md diff --git a/minigraf-c/README.md b/minigraf-c/README.md new file mode 100644 index 0000000000..59ce3d1427 --- /dev/null +++ b/minigraf-c/README.md @@ -0,0 +1,86 @@ +# minigraf C bindings + +[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](https://github.com/project-minigraf/minigraf#license) + +> Embedded bi-temporal graph database — C header + prebuilt shared library + +Minigraf for C and any language with a C FFI. Distributed as platform tarballs containing `minigraf.h` and prebuilt shared and static libraries. + +## Install + +Download the platform tarball from [GitHub Releases](https://github.com/project-minigraf/minigraf/releases): + +```sh +# Linux x86_64 example +curl -L https://github.com/project-minigraf/minigraf/releases/download/v1.0.0/minigraf-c-v1.0.0-x86_64-unknown-linux-gnu.tar.gz | tar xz +``` + +Each archive contains: +- `include/minigraf.h` — stable C header (cbindgen-generated) +- `lib/libminigraf_c.so` (Linux) / `libminigraf_c.dylib` (macOS) / `minigraf_c.dll` (Windows) +- `lib/libminigraf_c.a` (Linux/macOS) / `minigraf_c.lib` (Windows) + +## Quick start + +```c +#include "minigraf.h" +#include +#include + +int main(void) { + char *err = NULL; + MiniGrafDb *db = minigraf_open("myapp.graph", &err); + if (!db) { fprintf(stderr, "open: %s\n", err); free(err); return 1; } + + char *result = minigraf_execute( + db, + "(transact [[:alice :person/name \"Alice\"] [:alice :person/age 30]])", + &err + ); + if (!result) { fprintf(stderr, "execute: %s\n", err); free(err); } + else { printf("%s\n", result); minigraf_string_free(result); } + + result = minigraf_execute( + db, + "(query [:find ?name :where [?e :person/name ?name]])", + &err + ); + if (!result) { fprintf(stderr, "execute: %s\n", err); free(err); } + else { printf("%s\n", result); minigraf_string_free(result); } + + minigraf_checkpoint(db, NULL); + minigraf_close(db); + return 0; +} +``` + +## Memory contract + +Mirrors SQLite: +- `minigraf_open` — caller owns the `MiniGrafDb*`; free with `minigraf_close` +- `minigraf_execute` — returns a heap-allocated JSON string; caller must free with `minigraf_string_free` +- Error strings (`char **err` out-param) are heap-allocated; caller frees with `free()` + +## API summary + +| Function | Description | +|---|---| +| `minigraf_open(path, err)` | Open or create a file-backed database | +| `minigraf_open_in_memory(err)` | Open an in-memory database | +| `minigraf_execute(db, datalog, err)` | Execute a Datalog command; returns JSON string | +| `minigraf_string_free(s)` | Free a string returned by `minigraf_execute` | +| `minigraf_checkpoint(db, err)` | Flush dirty pages to disk | +| `minigraf_close(db)` | Close the database | +| `minigraf_last_error()` | Get the last error message (thread-local) | + +See `include/minigraf.h` for the complete API. + +## Links + +- [Full C FFI integration guide](https://github.com/project-minigraf/minigraf/wiki/Use-Cases#c-ffi) +- [Repository](https://github.com/project-minigraf/minigraf) +- [Datalog Reference](https://github.com/project-minigraf/minigraf/wiki/Datalog-Reference) + +## License + +MIT OR Apache-2.0 diff --git a/minigraf-ffi/java/README.md b/minigraf-ffi/java/README.md new file mode 100644 index 0000000000..a9247568f4 --- /dev/null +++ b/minigraf-ffi/java/README.md @@ -0,0 +1,66 @@ +# minigraf-jvm + +[![Maven Central](https://img.shields.io/maven-central/v/io.github.adityamukho/minigraf-jvm.svg)](https://central.sonatype.com/artifact/io.github.adityamukho/minigraf-jvm) +[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](https://github.com/project-minigraf/minigraf#license) + +> Embedded bi-temporal graph database for Java/Kotlin — Datalog queries, time travel, fat JAR with embedded natives + +Minigraf for Java and Kotlin on the desktop JVM. Fat JAR with embedded native libraries for Linux x86_64/aarch64, macOS universal2, and Windows x86_64. No Rust toolchain required. + +## Install + +### Gradle (Kotlin DSL) + +```kotlin +dependencies { + implementation("io.github.adityamukho:minigraf-jvm:1.0.0") +} +``` + +### Maven + +```xml + + io.github.adityamukho + minigraf-jvm + 1.0.0 + +``` + +## Quick start + +```kotlin +import io.github.adityamukho.minigraf.MiniGrafDb +import org.json.JSONObject + +// File-backed database +val db = MiniGrafDb.open("/path/to/myapp.graph") + +// In-memory database (ephemeral / testing) +val mem = MiniGrafDb.openInMemory() + +// Transact facts +db.execute("""(transact [[:alice :person/name "Alice"] [:alice :person/age 30]])""") + +// Query with Datalog +val json = JSONObject(db.execute( + "(query [:find ?name ?age :where [?e :person/name ?name] [?e :person/age ?age]])" +)) +// json.getJSONArray("results").getJSONArray(0).getString(0) == "Alice" + +// Time travel — state as of transaction 1 +val snap = db.execute("(query [:find ?age :as-of 1 :where [:alice :person/age ?age]])") + +// Flush dirty pages to disk +db.checkpoint() +``` + +## Links + +- [Full Java/JVM integration guide](https://github.com/project-minigraf/minigraf/wiki/Use-Cases#java--jvm) +- [Repository](https://github.com/project-minigraf/minigraf) +- [Datalog Reference](https://github.com/project-minigraf/minigraf/wiki/Datalog-Reference) + +## License + +MIT OR Apache-2.0 diff --git a/minigraf-ffi/python/README.md b/minigraf-ffi/python/README.md new file mode 100644 index 0000000000..5e55c7db21 --- /dev/null +++ b/minigraf-ffi/python/README.md @@ -0,0 +1,59 @@ +# minigraf (Python) + +[![PyPI](https://img.shields.io/pypi/v/minigraf.svg)](https://pypi.org/project/minigraf) +[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](https://github.com/project-minigraf/minigraf#license) + +> Embedded bi-temporal graph database for Python — Datalog queries, time travel, pre-built wheels + +Minigraf for Python: pre-built wheels for Linux x86_64/aarch64, macOS universal2, and Windows x86_64. No Rust toolchain required. + +## Install + +```sh +pip install minigraf +``` + +## Quick start + +```python +from minigraf import MiniGrafDb + +# File-backed database +db = MiniGrafDb.open("myapp.graph") + +# In-memory database (ephemeral / testing) +mem = MiniGrafDb.open_in_memory() + +# Transact facts +r = db.execute('(transact [[:alice :person/name "Alice"] [:alice :person/age 30]])') +# '{"transacted": 1}' + +# Query with Datalog +q = db.execute('(query [:find ?name ?age :where [?e :person/name ?name] [?e :person/age ?age]])') +# '{"variables": ["?name", "?age"], "results": [["Alice", 30]]}' + +# Time travel — state as of transaction 1 +snap = db.execute('(query [:find ?age :as-of 1 :where [:alice :person/age ?age]])') + +# Flush dirty pages to disk +db.checkpoint() +``` + +## Response shapes + +| Command | JSON | +|---|---| +| `transact` | `{"transacted": }` | +| `retract` | `{"retracted": }` | +| `query` | `{"variables": [...], "results": [[...]]}` | +| `rule` | `{"ok": true}` | + +## Links + +- [Full Python integration guide](https://github.com/project-minigraf/minigraf/wiki/Use-Cases#python) +- [Repository](https://github.com/project-minigraf/minigraf) +- [Datalog Reference](https://github.com/project-minigraf/minigraf/wiki/Datalog-Reference) + +## License + +MIT OR Apache-2.0 diff --git a/minigraf-node/README.md b/minigraf-node/README.md new file mode 100644 index 0000000000..da1541d443 --- /dev/null +++ b/minigraf-node/README.md @@ -0,0 +1,65 @@ +# minigraf (Node.js) + +[![npm](https://img.shields.io/npm/v/minigraf.svg)](https://www.npmjs.com/package/minigraf) +[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](https://github.com/project-minigraf/minigraf#license) + +> Embedded bi-temporal graph database for Node.js — Datalog queries, time travel, native addon + +Minigraf for Node.js: a native addon (no WASM, full file I/O) with pre-built binaries for Linux x86_64/aarch64, macOS universal2, and Windows x86_64. No build step required. + +## Install + +```sh +npm install minigraf +``` + +## Quick start + +```typescript +import { MiniGrafDb } from 'minigraf'; + +// File-backed database +const db = new MiniGrafDb('myapp.graph'); + +// In-memory database (ephemeral / testing) +const mem = MiniGrafDb.inMemory(); + +// Transact facts +const r = JSON.parse(db.execute( + '(transact [[:alice :person/name "Alice"] [:alice :person/age 30]])' +)); +// { "transacted": 1 } + +// Query with Datalog +const q = JSON.parse(db.execute( + '(query [:find ?name ?age :where [?e :person/name ?name] [?e :person/age ?age]])' +)); +// { "variables": ["?name", "?age"], "results": [["Alice", 30]] } + +// Time travel — state as of transaction 1 +const snap = JSON.parse(db.execute( + '(query [:find ?age :as-of 1 :where [:alice :person/age ?age]])' +)); + +// Flush dirty pages to disk +db.checkpoint(); +``` + +## Response shapes + +| Command | JSON | +|---|---| +| `transact` | `{"transacted": }` | +| `retract` | `{"retracted": }` | +| `query` | `{"variables": [...], "results": [[...]]}` | +| `rule` | `{"ok": true}` | + +## Links + +- [Full Node.js integration guide](https://github.com/project-minigraf/minigraf/wiki/Use-Cases#nodejs--typescript) +- [Repository](https://github.com/project-minigraf/minigraf) +- [Datalog Reference](https://github.com/project-minigraf/minigraf/wiki/Datalog-Reference) + +## License + +MIT OR Apache-2.0