adityamukho · Oct 29, 2026 · Oct 29, 2026
@@ -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`.

@@ -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.

@@ -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

@@ -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
 ```
 

@@ -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`
 

@@ -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**:

@@ -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
 
 | | |