From a82c251c0323eefdd5a3fd9a216db3a345223cbd Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Thu, 29 Oct 2026 10:16:01 +0530 Subject: [PATCH] docs: correct v2 aggregate support and retire redundant tracker --- CHANGELOG.md | 5 +++++ CLAUDE.md | 4 +++- PHILOSOPHY.md | 2 +- README.md | 4 +++- ROADMAP.md | 6 +++--- docs/ERROR_REFERENCE.md | 15 ++++++++------- docs/TEST_COVERAGE.md | 2 ++ 7 files changed, 25 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ff22972dab..f6ea0f102c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Documentation + +- Correct ordinary aggregate examples and lists (#777): v2 supports `count`, `count-distinct`, `sum`, `sum-distinct`, `min` and `max`; `avg` requires `:over`. Query behavior is unchanged. +- Retire production-readiness tracker #383 in favor of the v3.0.0 milestone, preserving its release gates there. + ## v2.0.11 — 2026-10-26 Patch release on the v2.x line under the [support policy](PHILOSOPHY.md#support-policy): two query data-integrity fixes, for expressions that compared a keyword and a ref to its entity differently from joins (#744), and float-literal rule calls whose `-0.0` rows varied between runs (#750), plus `checkpoint()` deadlocking inside a `WriteTransaction` (#734). File format is unchanged (v7). No API changes. Upgrading is recommended for every v2.x user who compares entity refs in expressions, passes float constants to rules, or uses `WriteTransaction`. diff --git a/CLAUDE.md b/CLAUDE.md index afb1680633..eb0c8f65f6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -184,13 +184,15 @@ See `docs/TEST_COVERAGE.md` for the full per-file breakdown. **Testing conventions** — see the Testing Conventions section below before writing any tests. +Ordinary aggregates on v2 are `count`, `count-distinct`, `sum`, `sum-distinct`, `min` and `max`; `avg` requires `:over` (#777). + ## Current Maintainer Context **v2.0.11 released** (2026-10-26) — expression `=` / `!=` equates a keyword with a ref to its entity (#744), float-literal rule calls return `-0.0` rows in every run (#750), and `checkpoint` inside a `WriteTransaction` returns `INT-001` instead of deadlocking (#734). **v2.0.10 released** (2026-10-23) — WAL entries of more than 1,000,000 facts replay (#686), float constants match equal floats only (#706), prepared queries use the database's rule limits (#679); Kani proofs of `encode_value` backported (#627). **v2.0.9** (2026-10-21) — a pseudo-attribute in a rule body reads the stored fact (#661), a fact of more than four elements is rejected with PRS-108 (#649), `BrowserDb` rejections carry their error code (#673); every binding package is consumer-tested before and after publishing. **v2.0.8** (2026-10-20) — query data-integrity patch: `:db/valid-at` in `not-join` bodies and rule definitions (#615, #617), `or` branches with outer-variable expressions, `or`-bound expression variables and keyword/entity joins (#620, #625, #637), rules calling or recursing through a `not`/`or` rule (#628, #633). **v2.0.7** (2026-10-16) — prepared queries keep a literal `:as-of`/`:valid-at` (#603), rule calls with a literal argument return every row (#608), an `or` sharing no variable returns its cross product (#610). **v2.0.6** (2026-10-14) — concurrent-query data-integrity patch: queries see whole transactions (#554), one state per query (#555), no half-written checkpoint reads (#558). **v2.0.5** (2026-10-11) — short-file open refused with STG-045 (#506), commit after a torn WAL entry no longer lost, WAL-007 (#513); backported rule-query `max_results` (#528), all-checkpointed WAL removal (#457) and `usize::MAX` close-time save (#476); weekly soak test (#392), real coverage gates (#396). **v2.0.4** (2026-10-08) — `BrowserDb` IndexedDB flush returns an error for an unreadable dirty page (#470); golden-file v7 corpus (#391) and SIGKILL committed-data crash test (#384). **v2.0.3** (2026-10-06) — data-integrity patch under the support policy: indexed queries with >65,535 uncheckpointed facts (#445), tx counter rewound on reopen next to an already-checkpointed WAL (#447). **v2.0.2** (2026-09-27) — last planned v2.x feature/fix release: query fixes (#297, #405, #407, #410), directory fsync (#389), point-query/attribute-scan/checkpoint perf mitigations (#323, #381, #315), CI policy checks (#395), support policy and tiers (#397, #399, #400). **v2.0.1** (2026-09-25) fixed index rebuild on open (#370). **v2.0.0** introduced kernel file locking (#317, #304), structured runtime error codes (#277), `OpenOptions` `#[non_exhaustive]`, and an MSRV of Rust 1.89. See `CHANGELOG.md` for the full rationale and release history. Current plan (see `ROADMAP.md` and the milestones): - **v2.x** (`main`, format v7) now gets only data-integrity and security fixes as patch releases (v2.0.3 is the first); v2.0.2 was the last planned v2.x release. -- **v3.0.0** (format v8 and data integrity, plus `:limit` #306, query profiler #185, set membership predicates #316 and UniFFI `PreparedQuery`/UDF registration #181/#180; tracker #383) is developed on the long-lived `v3` branch. Do not merge `main` into `v3` routinely: `main` only gets backports of fixes already on `v3`. Shared CI and workflow changes land on both branches as separate PRs. Just before the v3.0.0 cut, merge `main` into `v3` once (merge commit; source conflicts resolved to `v3`, `main`'s v2.0.x CHANGELOG sections brought over) so the cut is a fast-forward. +- **v3.0.0** (format v8 and data integrity, plus `:limit` #306, query profiler #185, set membership predicates #316 and UniFFI `PreparedQuery`/UDF registration #181/#180; [v3.0.0 milestone](https://github.com/project-minigraf/minigraf/milestone/1)) is developed on the long-lived `v3` branch. Do not merge `main` into `v3` routinely: `main` only gets backports of fixes already on `v3`. Shared CI and workflow changes land on both branches as separate PRs. Just before the v3.0.0 cut, merge `main` into `v3` once (merge commit; source conflicts resolved to `v3`, `main`'s v2.0.x CHANGELOG sections brought over) so the cut is a fast-forward. - **v3.next** (the release after v3.0.0) holds new features (lag/lead #182, sliding row frames #183, rule persistence #241). - Known v2.x data issue: same-transaction multi-valued facts (#371). Fix ships in v3.0.0. All v2.x known issues are listed in pinned issue #421 (`known-issue` label); `data-integrity`/`corruption`/`durability` issues stay open until the fix is in a published release (CONTRIBUTING.md). - Support policy and tiers: PHILOSOPHY.md §7 and §10. v2.x gets data-integrity and security fixes for 12 months after v3.0.0. Tier 1 = Rust + Python; other bindings are Tier 2. diff --git a/PHILOSOPHY.md b/PHILOSOPHY.md index afd7ac3ee6..03cf26f157 100644 --- a/PHILOSOPHY.md +++ b/PHILOSOPHY.md @@ -396,7 +396,7 @@ When evaluating a feature or design choice, ask: These are goals, not a description of today. You'll know Minigraf has succeeded when: 1. **Ubiquity**: Developers say "just use Minigraf" for embedded graph storage -2. **Trust**: Known for never losing data, crash-safe, reliable. Not yet met: v2.x has a known data-integrity bug (#371), and the work to meet this goal is tracked in #383. See the [known issues](https://github.com/project-minigraf/minigraf/issues?q=is%3Aissue+is%3Aopen+label%3Aknown-issue). +2. **Trust**: Known for never losing data, crash-safe, reliable. Not yet met: v2.x has a known data-integrity bug (#371), and the work to meet this goal is tracked in the [v3.0.0 milestone](https://github.com/project-minigraf/minigraf/milestone/1). See the [known issues](https://github.com/project-minigraf/minigraf/issues?q=is%3Aissue+is%3Aopen+label%3Aknown-issue). 3. **Simplicity**: New users are productive in under 5 minutes 4. **Size**: Core binary within its ~1.2MB budget, minimal dependencies 5. **Portability**: Runs everywhere from Raspberry Pi to browsers diff --git a/README.md b/README.md index 1a5716fea9..2a948b1c49 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,8 @@ Minigraf is a **single-file embedded graph database** that lets you: **Status**: See [ROADMAP.md](ROADMAP.md) for planned work and current direction. +In v2, the ordinary aggregates are `count`, `count-distinct`, `sum`, `sum-distinct`, `min` and `max`. Average is available only as a window function, for example `(avg ?score :over (:order-by ?score))` (#777). + ## Why Datalog? **Datalog is fundamentally better for graphs than SQL-like languages:** @@ -105,7 +107,7 @@ let r2 = pq.execute(&[("tx", BindValue::TxCount(2)), ("entity", BindValue::Entit ```bash cargo run # interactive Datalog REPL -cargo test # run 1321 tests +cargo test # 1335 tests (1326 passing, 9 ignored) cargo run < demos/demo_recursive.txt # recursive rules demo ``` diff --git a/ROADMAP.md b/ROADMAP.md index 11b3017d30..7213515db3 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,6 +1,6 @@ # Minigraf Roadmap -> Planned work for Minigraf, a bi-temporal Datalog database. v2.x has known data-integrity issues ([pinned list](https://github.com/project-minigraf/minigraf/issues/421)); v3.0.0 fixes them (tracker #383). +> Planned work for Minigraf, a bi-temporal Datalog database. v2.x has known data-integrity issues ([pinned list](https://github.com/project-minigraf/minigraf/issues/421)); v3.0.0 fixes them ([v3.0.0 milestone](https://github.com/project-minigraf/minigraf/milestone/1)). **Philosophy**: Embedded graph memory for agents, mobile, and the browser — built on the SQLite approach: be boring, be reliable, be embeddable. @@ -123,7 +123,7 @@ Further v2.x releases are data-integrity and security patches only. ## v2.0.2 — Final Planned v2.x Release (released 2026-09-27) -**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. Details are in the [CHANGELOG](CHANGELOG.md). +**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. Work list: [v3.0.0 milestone](https://github.com/project-minigraf/minigraf/milestone/1). Details are in the [CHANGELOG](CHANGELOG.md). Shipped: @@ -276,7 +276,7 @@ When evaluating features, ask: - v2.x maintenance on `main`: data-integrity and security fixes only - v3.0.0 (format v8 and data integrity) on the `v3` branch, then v3.next features -- Production readiness for high-stakes deployments, tracked in #383 +- Production readiness for high-stakes deployments, tracked in the [v3.0.0 milestone](https://github.com/project-minigraf/minigraf/milestone/1) - Ecosystem work tracked in [`minigraf-examples`](https://github.com/project-minigraf/minigraf-examples) - Developer tools tracked in `minigraf-inspector` and `minigraf-visualizer` diff --git a/docs/ERROR_REFERENCE.md b/docs/ERROR_REFERENCE.md index 70fe483b29..d0f5e36395 100644 --- a/docs/ERROR_REFERENCE.md +++ b/docs/ERROR_REFERENCE.md @@ -545,7 +545,7 @@ See the [Datalog Reference](https://project-minigraf.github.io/minigraf-docs/lat **Error text**: `':with' clause requires at least one aggregate in :find` -**Cause**: `:with` is used to group result rows before aggregation, so it requires at least one aggregate function (`count`, `sum`, `avg`, etc.) in `:find`. +**Cause**: `:with` is used to group result rows before aggregation, so it requires at least one aggregate function (`count`, `count-distinct`, `sum`, `sum-distinct`, `min`, `max`) in `:find`. **Resolution**: - Add an aggregate to `:find`, or remove `:with` if no aggregation is needed. @@ -601,7 +601,7 @@ See the [Datalog Reference](https://project-minigraf.github.io/minigraf-docs/lat **Cause**: An aggregate expression in `:find` must be `(function ?variable)` — exactly two elements. **Resolution**: -- Use `(count ?e)`, `(sum ?amount)`, `(avg ?score)` — one function name, one variable. +- Use `(count ?e)`, `(sum ?amount)`, `(max ?score)` — one function name, one variable. - See the [Datalog Reference — Aggregates](https://project-minigraf.github.io/minigraf-docs/latest/datalog-reference/#aggregation). **Example**: @@ -649,16 +649,17 @@ See the [Datalog Reference](https://project-minigraf.github.io/minigraf-docs/lat **Error text**: `'{}' is a window function and requires an ':over (...)' clause` -**Cause**: Window functions (`rank`, `row-number`, `dense-rank`, `ntile`, `percent-rank`, `cume-dist`) must be accompanied by an `:over` clause specifying ordering and/or partitioning. +**Cause**: In v2, `avg`, `rank` and `row-number` must be accompanied by an `:over` clause specifying ordering and/or partitioning. **Resolution**: -- Add an `:over` clause: `(rank :over (:order-by ?score))`. +- Add an `:over` clause: `(rank :over (:order-by ?score))` or `(avg ?score :over (:order-by ?score))`. +- Ordinary `(avg ?score)` is unavailable in v2; it requires `:over`. - See the [Datalog Reference — Window Functions](https://project-minigraf.github.io/minigraf-docs/latest/datalog-reference/#window-functions). **Example**: ```datalog -(query {:find [?e (rank)] - :where [[?e :score ?score]]}) +(query [:find ?e (rank ?score) + :where [?e :score ?score]]) ``` *Missing `:over`; use `(rank :over (:order-by ?score))`* @@ -2679,7 +2680,7 @@ these two arities. **Error text**: `unknown aggregate function: '{}'` **Cause**: A `:find` or `:with` clause referenced an aggregate function -name that is neither a built-in (`count`, `sum`, `avg`, `min`, `max`, etc.) +name that is neither a built-in (`count`, `count-distinct`, `sum`, `sum-distinct`, `min`, `max`) nor a user-defined function registered via `db.register_aggregate()`. **Resolution**: diff --git a/docs/TEST_COVERAGE.md b/docs/TEST_COVERAGE.md index 2ea2618017..6a9a04a60e 100644 --- a/docs/TEST_COVERAGE.md +++ b/docs/TEST_COVERAGE.md @@ -1,5 +1,7 @@ # Minigraf Test Coverage +#777 corrects documentation only on v2; query behavior and test counts are unchanged. Ordinary `avg` still raises PRS-027 without `:over`. + ## v2.0.11 Coverage Summary | | |