8000 docs(roadmap): final v2.x is v2.0.2; split v3.0.0 (integrity) and v3.1.0 (features) by adityamukho · Pull Request #403 · project-minigraf/minigraf · GitHub
[go: up one dir, main page]
Skip to content

docs(roadmap): final v2.x is v2.0.2; split v3.0.0 (integrity) and v3.1.0 (features) #403

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
adityamukho merged 1 commit into from
Sep 26, 2026
Merged

docs(roadmap): final v2.x is v2.0.2; split v3.0.0 (integrity) and v3.1.0 (features) #403

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 57 additions & 9 deletions ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,62 @@ Completed releases and their implementation details live in the [CHANGELOG](CHAN

---

## v3.0.0 — File Format Policy
## v2.0.2 — Final Planned v2.x Release

**v3.0.0 supports file format v8 only.** Fixing #287's `EavtKey`/`AevtKey` missing-value-bytes data-loss bug bumps the format from v7 to v8. Support for v1–v6 is dropped at the same time. The v1–v6 → v7 auto-migration code in `persistent_facts.rs` can be removed when cutting this release; a v7→v8 migration replaces it. Any database opened at least once under a v1.x release will already be on v7; there are no known users on older formats.

This was the GitHub milestone named “2.0” before v2.0.0 used that version number for the kernel-locking and structured-error-code breaking changes; it was consequently renumbered to v3.0.0.
**The v2.x line (`main`) ends with a patch.** File format stays v7 and the public API does not change. All new feature work has moved to v3.x. Tracker: #383.

Scope:

- `EavtKey`/`AevtKey` missing-value-bytes fix and file-format v7→v8 migration (#287)
- Already merged: bound-entity point queries narrowed to the queried attribute (#323 mitigation), exact attribute-scan bounds (#381), and checkpoints that copy untouched index leaves (#315 mitigation)
- fsync the parent directory after creating the `.graph`/WAL file and after deleting the WAL (#389)
- Benchmark regression alerting that is not silently muted (#393)
- CI: MSRV build, public-API semver check, dependency policy (#395)
- Stability and support policy, including how long v2.x gets data-integrity fixes after v3.0.0 (#397)
- Known-issues process: data-integrity issues stay open until the fix is in a published release (#399)
- Support tiers for language bindings and platforms (#400)

**Known issue on all v2.x releases:** same-transaction multi-valued facts read back as one value (#371, #287). The fix needs format v8 and ships in v3.0.0. Workaround: write or retract each value of a multi-valued attribute in its own `transact`/`retract` call.

---

## v3.0.0 — File Format v8 and Data Integrity

**v3.0.0 supports file format v8 only.** Fixing #287/#371 (`EavtKey`/`AevtKey` carry no value bytes, so same-transaction multi-values collapse) bumps the format from v7 to v8. Support for v1–v6 is dropped at the same time. The v1–v6 → v7 auto-migration code in `persistent_facts.rs` can be removed when cutting this release; a v7→v8 migration replaces it. Any database opened at least once under a v1.x release will already be on v7; there are no known users on older formats. Every other layout change this release needs goes into v8 too, so there is no separate v9.

This was the GitHub milestone named “2.0” before v2.0.0 used that version number for the kernel-locking and structured-error-code breaking changes; it was consequently renumbered to v3.0.0. It is developed on the long-lived `v3` branch and merges into `main` at the cut.

Scope — format and storage integrity:

- v8 index keys with value bytes and v7→v8 migration (#371, #287; done on `v3`)
- Per-page CRC32 checksums on fact pages and B+tree pages (#388)
- Crash-atomic `save()`, with checkpoints proportional to the change (#374)
- Index `verify` and public `rebuild_indexes()` (#373)
- Net-assert on v8 keys before resolving facts, for O(live) point queries (#379)
- `btree_page` fuzz target that reaches node decoding (#375)

Scope — release-gate testing and documentation:

- Golden-file compatibility corpus for every format version, frozen before v8 work goes further (#391)
- SIGKILL crash test that checks committed data through EAVT, AEVT and full scan (#384)
- Model-based test of transact/retract/checkpoint/reopen (#385)
- Wider property tests: file-backed, batched, retracts, temporal, joins (#386)
- Persistent fuzz corpus and an operation-sequence target (#387)
- Fault injection across save/WAL/recovery (#390)
- Long-running soak test at scale (#392)
- Benchmarks at 100K–10M facts and a published performance envelope (#394)
- Higher storage/WAL coverage gates and branch-coverage gates (#396)
- Durability, recovery and operations guide (#398)

---

## v3.1.0 — Features

Additive features, kept out of v3.0.0 so the #371 fix is not held up by them:

- Rule persistence — design first (#241)
- Query profiler (#185)
- Native `:limit N` / `:offset` for plain `:find` queries (#306, #310)
- Set membership predicates (#316)
- `lag`/`lead` window functions (#182)
- Sliding row frames — `:rows N preceding` (#183; builds on #182)
- `PreparedQuery` over UniFFI (#181)
Expand All @@ -33,7 +80,7 @@ Scope:
### Developer Tools

- 🎯 Database inspector/debugger (separate repository: [minigraf-inspector](https://github.com/project-minigraf/minigraf-inspector))
- 🎯 Query profiler
- 🎯 Query profiler (#185, v3.1.0)
- 🎯 Time-travel visualizer (separate repository: [minigraf-visualizer](https://github.com/project-minigraf/minigraf-visualizer))

### Integration Examples
Expand Down Expand Up @@ -105,13 +152,14 @@ When evaluating features, ask:

## Current Focus

- v2.x minor releases (v2.1.0–v2.3.0) on `main`
- The v3.0.0 file-format policy and its scoped work above, on the `v3` branch
- v2.0.2, the final planned v2.x release, on `main`
- v3.0.0 (format v8 and data integrity) on the `v3` branch, then v3.1.0 features
- Production readiness for high-stakes deployments, tracked in #383
- Ecosystem work tracked in [`minigraf-examples`](https://github.com/project-minigraf/minigraf-examples)
- Developer tools tracked in `minigraf-inspector` and `minigraf-visualizer`

See [GitHub Issues](https://github.com/project-minigraf/minigraf/issues) for specific tasks, and the [CHANGELOG](CHANGELOG.md) for completed releases.

---

**Last updated**: September 2026 — v2.0.1 is the current release. v2.x minor releases (v2.1.0–v2.3.0) ship from `main` first; v3.0.0 work, including the file-format v8 fix for #287/#371, is developed on the long-lived `v3` branch and merges into `main` at the v3.0.0 cut.
**Last updated**: September 2026 — v2.0.1 is the current release. v2.0.2 is the final planned v2.x release and ships from `main` first; v3.0.0 work, including the file-format v8 fix for #287/#371, is developed on the long-lived `v3` branch and merges into `main` at the v3.0.0 cut.
Loading
0