From 67f5462b6ea4a23562c178a77353b202987657cc Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Fri, 6 Nov 2026 12:24:55 +0530 Subject: [PATCH 1/3] docs: #869 implementation plan Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01H2a7QoYX6tc5G3sKVzvLjD --- .../plans/2026-11-06-869-allow-overrides.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 docs/superpowers/plans/2026-11-06-869-allow-overrides.md diff --git a/docs/superpowers/plans/2026-11-06-869-allow-overrides.md b/docs/superpowers/plans/2026-11-06-869-allow-overrides.md new file mode 100644 index 0000000000..8f84f41461 --- /dev/null +++ b/docs/superpowers/plans/2026-11-06-869-allow-overrides.md @@ -0,0 +1,87 @@ +# #869 plan: `OpenOptions::allow_overrides` gate + +Spec: `docs/superpowers/specs/2026-11-06-862-override-audit-design.md` (§1, §2, §7, §9 gate tests), merged in #868. +Branch `feat/869-allow-overrides` off `v3` at `70ed3f21`. One PR to `v3`, with `Refs #869, #862` in its body. Closing keywords do not fire on `v3`, so close #869 with `gh issue close` after the merge. + +## 1. Public API + +Add a new module `src/overrides.rs`, re-exported from `lib.rs` as `minigraf::Overridable`: + +```rust +/// A setting that query text may override (#862). +#[non_exhaustive] +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub enum Overridable { MaxDerivedFacts, MaxResults } + +impl Overridable { + /// The list a database uses when `OpenOptions::allow_overrides` is not set. + pub const DEFAULTS: &'static [Overridable] = &[Overridable::MaxDerivedFacts, Overridable::MaxResults]; + /// The query keyword this variant gates, e.g. ":max-derived-facts". + pub fn keyword(self) -> &'static str; +} +``` + +- `QueryMemoryLimit` comes in #870, and `MaxIterations` in #861, together with its entry in `DEFAULTS`. Adding a variant later is not a breaking change, because the enum is `#[non_exhaustive]`. +- `OpenOptions` gains a field `pub allow_overrides: Vec`, which `Default` sets to `DEFAULTS.to_vec()`. +- It also gains a builder, `pub fn allow_overrides(mut self, list: impl IntoIterator) -> Self`, which replaces the list. Its doc explains replace semantics and gives the `DEFAULTS` concat example. +- `OpenOptions` derives only `Debug` and `Clone`, not `Copy`, so a `Vec` field is fine. +- The `OpenOptionsWithPath` builder forwards `allow_overrides` like the other options. +- `cargo semver-checks` runs against the PR base. Adding a field to a `#[non_exhaustive]` struct and adding a new enum are both non-breaking. + +## 2. Error code API-025 + +- Add `ErrorCode::Api025` with text `query option {} is not allowed on this database; OpenOptions::allow_overrides does not list Overridable::{}` (category Api). +- Add it to the registry tables in `src/error.rs`, including the category tests that list API codes. +- Add it to `docs/ERROR_REFERENCE.md`: in the table, "Query option override not allowed", and as a section with cause, resolution and scenario. + +## 3. The check + +- `pub(crate) fn check_overrides(query: &DatalogQuery, allowed: &[Overridable]) -> Result<()>` lives in `overrides.rs`. A keyword is present when its parsed field is `Some(_)`: `max_derived_facts` and `max_results`. +- The check runs in a fixed order, `MaxDerivedFacts` then `MaxResults`, and reports the first keyword that is present but not listed. +- It reads only the top-level query. Rule bodies take no keywords, and subqueries don't exist. + +Call it right after parsing, before `reject_unbound_slots`, at every query entry point: + +| Site | List | +|---|---| +| `Minigraf::execute`, Query arm (`db.rs` ~761) | `self.inner.options.allow_overrides` | +| `Minigraf::query_inner` (~982) | same | +| `Minigraf::prepare_inner` (~1347), before `prepare_query` | same | +| `WriteTransaction::execute`, Query arm (~1770) | `self.inner.options.allow_overrides` | +| `BrowserDb` `execute`, `query`, `prepare` (`browser/mod.rs`) | `Overridable::DEFAULTS` (BrowserDb takes no options) | + +Since `DEFAULTS` allows both of today's keywords, this PR changes nothing for BrowserDb. Calling the check there now means #870's gated keyword is refused in BrowserDb without another change. + +## 4. Tests (`tests/allow_overrides_test.rs`, `#![cfg(not(target_arch = "wasm32"))]`) + +1. **Defaults.** A default handle runs a rule query with `:max-derived-facts` and one with `:max-results`. Both return their rows. +2. **Empty list.** Under `allow_overrides([])`, each keyword is refused with API-025 by `execute`, `query`, `prepare` and `WriteTransaction::execute`. Assert on `code()`, and check the message names the keyword. The same queries without a keyword run. +3. **Replace semantics.** `allow_overrides([MaxResults])` refuses `:max-derived-facts` and allows `:max-results`. +4. **Refusal happens before execution.** A refused `WriteTransaction::execute` leaves the transaction usable: a later transact and commit succeed. +5. **Refused at prepare.** A refused `prepare` returns no `PreparedQuery`. +6. **Defaults read back.** `OpenOptions::default().allow_overrides == Overridable::DEFAULTS`. `DEFAULTS` concatenated with another list works, and duplicates in the list have no effect. +7. **File databases.** The option holds on a file database (`OpenOptions::new().allow_overrides([]).path(..).open()`), and it isn't persisted: reopening with defaults allows the keyword again. +8. **Registry.** API-025 is registered, documented and in the Api category, through the existing registry/doc consistency tests (`error_codes_foundation_test.rs`). + +Plus a unit test of `check_overrides` order (both keywords present, both unlisted → `:max-derived-facts` is reported), and a doc test on `OpenOptions::allow_overrides`. + +BrowserDb: a `#[wasm_bindgen_test]` in `browser/mod.rs` confirms `:max-derived-facts` still runs. That is the only behavior there. + +## 5. Docs (same PR) + +- **`docs/CONFIGURATION.md` (new).** The spec's §1 table, trimmed to what is true after this PR. Rows not done yet are marked "planned (#870/#871/#861)". It also explains `allow_overrides` with Rust examples. Link it from `README.md`. +- **`CHANGELOG.md` `[Unreleased]`.** Under Added: `allow_overrides` / `Overridable`. Under Documentation: `CONFIGURATION.md`. API-025 is noted under Added. +- **Test counts.** Update `docs/TEST_COVERAGE.md` and the `CLAUDE.md` count. The `CLAUDE.md` module list gains `overrides.rs`, and the `db.rs` line gains `allow_overrides`. +- **`ROADMAP.md`.** Check whether #862 is listed; update it if so. +- **Docs site PR** (`../minigraf-docs`): put the table and the `allow_overrides` section in `performance-tuning.md` under ``. In `datalog-reference.md`, note under the limit keywords that the embedder can refuse them (API-025). Docs CI checks links. + +## 6. Verification before the PR + +- `cargo fmt`, then `cargo clippy --all-targets -- -D warnings`. +- `cargo test`: the full suite, on the bench machine first. +- `cargo test --doc`. +- `cargo build --target wasm32-unknown-unknown --features browser` to check the BrowserDb call sites. +- The size gate (`--profile dist`) shouldn't move much. Record the delta in the PR body. +- Review: `codex exec -m gpt-6-astra` (skip if it fails), then CI until it is green. + +After merge: #861 is unblocked (`MaxIterations`), then #870. From 90add3a74319994c6fc142a6e2135a4671dba709 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Fri, 6 Nov 2026 13:18:52 +0530 Subject: [PATCH 2/3] feat: OpenOptions::allow_overrides gate for query keywords (#869) Overridable (MaxDerivedFacts, MaxResults; DEFAULTS allows both) lists the query keywords that may override a database's settings. A query using an unlisted keyword is refused with API-025 after parsing, from execute, query, prepare and WriteTransaction::execute. BrowserDb uses DEFAULTS. Adds docs/CONFIGURATION.md. Refs #869, #862 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01H2a7QoYX6tc5G3sKVzvLjD --- CHANGELOG.md | 5 ++ CLAUDE.md | 3 +- README.md | 2 + docs/CONFIGURATION.md | 82 +++++++++++++++++++++ docs/ERROR_REFERENCE.md | 13 ++++ docs/TEST_COVERAGE.md | 5 +- src/browser/mod.rs | 31 +++++++- src/db.rs | 51 ++++++++++++- src/error.rs | 9 +++ src/lib.rs | 2 + src/overrides.rs | 111 ++++++++++++++++++++++++++++ tests/allow_overrides_test.rs | 133 ++++++++++++++++++++++++++++++++++ 12 files changed, 442 insertions(+), 5 deletions(-) create mode 100644 docs/CONFIGURATION.md create mode 100644 src/overrides.rs create mode 100644 tests/allow_overrides_test.rs diff --git a/CHANGELOG.md b/CHANGELOG.md index ed63e28d2b..7cd8ca2dce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- **`OpenOptions::allow_overrides`** (#869, part of #862): the embedder lists, as `Overridable` variants, the query keywords that may override the database's settings. The default, `Overridable::DEFAULTS` (`MaxDerivedFacts`, `MaxResults`), allows every keyword that could do so before, so no query changes. A query using a keyword the list leaves out is refused with the new **API-025** before it runs, from `execute`, `query`, `prepare` and `WriteTransaction::execute`; the list replaces the defaults rather than adding to them, and is not stored in the file. `BrowserDb` takes no options and uses the defaults. `Overridable` is `#[non_exhaustive]`. + ### Changed - **Ordinary average** (#777): `(avg ?v)` no longer raises PRS-027. Grouped and ungrouped queries use the same numeric population and arithmetic as window `avg`: skip nil and nonnumeric values, sum exactly, round the total once to Float, then divide by the numeric count. Integer totals are not saturated. Results are Float, or nil for an existing group without numbers; no matching rows yields no rows. The total can overflow before division, and division rounds separately. Existing window behavior is unchanged. Retained exact-sum allocations for ordinary `sum` and `avg` are now charged to the query memory limit. @@ -30,6 +34,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Documentation +- **Configuration reference** (#869): [docs/CONFIGURATION.md](docs/CONFIGURATION.md) lists every `OpenOptions` setting, where else it can be changed, and how `allow_overrides` gates query text. - **Heavy WAL entry replay test** (#865): a nightly acceptance test writes one WAL entry of 1,000,000 facts, reopens without a checkpoint and checks every replayed fact through entity, attribute and attribute-value lookups, then checkpoints, verifies and reopens. It passes; no production change. - **Failure-path correctness map** (#843): [X08's correctness-target map](docs/benchmarks/843-failure-correctness/README.md) ties invalid bounds, windows and binds, callback errors, exhaustion, corrupt pages, failed-handle retry, v1–v6 refusal and heavy single-entry WAL replay to 138 named tests at a pinned v3 revision, with their error and data invariants, and limits the C08 repair and C30 rollback claims to their fixtures. Gaps found: heavy WAL replay through `Minigraf::open` (#865) and the recursion round bound (#861). X08 stays excluded. No production, test, public API or nightly-route change. diff --git a/CLAUDE.md b/CLAUDE.md index 6fb54e9b46..a974f2cbea 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -182,7 +182,8 @@ cargo run < demos/demo_negation.txt 5. **`src/repl.rs`** — Interactive REPL; TTY-aware (suppresses prompts/banner for piped input) -6. **`src/db.rs`** — Public API: `Minigraf::open/execute/query/fact_log/prepare/begin_write/checkpoint/save/verify/rebuild_indexes`, `WriteTransaction`, `IntegrityReport`, `OpenOptions::page_cache_size`, `OpenOptions::read_only` (#429: shared lock, nothing written, writes are `API-014`), `OpenOptions::query_memory_limit` (#549: `QRY-012`, off by default), `OpenOptions::transaction_chunk_facts` (#550) +6. **`src/db.rs`** — Public API: `Minigraf::open/execute/query/fact_log/prepare/begin_write/checkpoint/save/verify/rebuild_indexes`, `WriteTransaction`, `IntegrityReport`, `OpenOptions::page_cache_size`, `OpenOptions::read_only` (#429: shared lock, nothing written, writes are `API-014`), `OpenOptions::query_memory_limit` (#549: `QRY-012`, off by default), `OpenOptions::transaction_chunk_facts` (#550), `OpenOptions::allow_overrides` (#869: which query keywords may override settings, `API-025`; see `docs/CONFIGURATION.md`) + - `src/overrides.rs`: `Overridable` (`DEFAULTS`, `keyword`) and `check_overrides`, called after parsing at every query entry point (`BrowserDb` uses `DEFAULTS`) - `src/cursor.rs`: `Cursor` / `Batch` — owned, `Send` cursor returned by `Minigraf::query` and `PreparedQuery::query` (#432); pulls engine queries one internal batch at a time (`close`/drop stops the work; a read error after some rows comes on the next call), other queries computed at open; holds a `Snapshot` (one state of the store, its committed generation pinned, #543) until dropped - `src/fact_log.rs`: `FactLog` / `FactFilter` / `FactRecord` / `FactOrder` — every fact version streamed by `Minigraf::fact_log` (#430): tx order (multi-pass, bounded window) or storage order, key-level filters; an open log pins the committed generation (`storage::pins`), so checkpoints run but do not reuse its pages (`API-013` deprecated, #543) - `src/log_writer.rs`: `LogWriter` — builds a new file from `FactRecord`s with their tx and valid-time kept (#431): tx-ordered appends with holes (`API-015`/`API-016`), batched copy-on-write checkpoints at tx boundaries, no WAL, built at `.partial` and renamed by `finish` (`STG-043` if the target exists) diff --git a/README.md b/README.md index 6dd52d186a..ba62f3edca 100644 --- a/README.md +++ b/README.md @@ -318,6 +318,8 @@ File-backed databases limit string values to 4,068 bytes (`WAL-003`). In-memory **Durability tuning:** every write is `fsync`'d immediately by default (`SyncMode::Full`). Bulk loaders/migrations that can safely re-run from a checkpoint watermark on failure can trade that for throughput with `OpenOptions::new().synchronous(SyncMode::Normal)` — `checkpoint()` still fsyncs unconditionally in both modes. See the [Performance Tuning](https://project-minigraf.github.io/minigraf-docs/latest/performance-tuning/#configuration-knobs) for the full tradeoff and the write-batching pattern that pairs with it. +**Configuration:** [docs/CONFIGURATION.md](docs/CONFIGURATION.md) lists every `OpenOptions` setting, which ones query text can override, and how `OpenOptions::allow_overrides` lets the embedder refuse those keywords (`API-025`, #869). + **Running Minigraf where data loss matters:** [docs/DURABILITY.md](docs/DURABILITY.md) covers what survives a process crash and a power loss, recovery on open, supported filesystems and containers, backups and restores, `verify()` and `rebuild_indexes()`, upgrading from v2.x, and which errors mean retry, reopen or restore. ## Contributing diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md new file mode 100644 index 0000000000..fb3f9c3000 --- /dev/null +++ b/docs/CONFIGURATION.md @@ -0,0 +1,82 @@ +# Configuration + +Minigraf needs no configuration: `Minigraf::open("app.graph")` uses safe +defaults. `OpenOptions` changes them for one handle. Nothing here is stored +in the `.graph` file; each open sets it. + +This page lists every `OpenOptions` setting, where else it can be changed, +and how the embedder controls which settings query text may override +(`allow_overrides`, #862). + +## Settings and where they can be changed + +"Query text" means keywords in the query vector, such as +`:max-derived-facts 1000`. Query text is gated by +[`allow_overrides`](#allow_overrides). Settings changed from application +code are not gated. + +| `OpenOptions` field | Default | Also changed by | Semantics of an override | +|---|---|---|---| +| `max_derived_facts` | 1,000,000 | query text: `:max-derived-facts N` | Replaces the database value for that query, up or down | +| `max_results` (deprecated) | no limit of its own | query text: `:max-results N` | Alone, replaces the database value; with `:max-derived-facts`, the lower applies | +| `query_memory_limit` | no limit | — (query keyword and `PreparedQuery` setter planned, #870) | — | +| round limit | 1000, fixed | — (`OpenOptions::max_iterations` and `:max-iterations` planned, #861) | — | +| `transaction_chunk_facts` | 65,536 | — (per-transaction `TxOptions` planned, #871) | — | +| `synchronous` | `SyncMode::Full` | — (per-transaction `TxOptions` planned, #871) | — | +| `wal_checkpoint_threshold` | 1000 | open only | Database-wide checkpoint policy | +| `page_cache_size` | 256 pages | open only | Shared cache | +| `allow_unlocked` | `false` | open only | Decided when the file is opened | +| `read_only` | `false` | open only | Decided when the file is opened | +| `allow_overrides` | `Overridable::DEFAULTS` | open only | Policy for query text | + +`BrowserDb` takes no options: it always runs with the defaults, including +`Overridable::DEFAULTS`. + +## `allow_overrides` + +`OpenOptions::allow_overrides` lists the query keywords that may override the +database's settings, as `Overridable` variants: + +| Variant | Keyword | In `DEFAULTS` | +|---|---|---| +| `Overridable::MaxDerivedFacts` | `:max-derived-facts` | yes | +| `Overridable::MaxResults` | `:max-results` | yes | + +The default, `Overridable::DEFAULTS`, allows every keyword that could +override a setting before the list existed, so existing queries keep +working. + +A query that uses a keyword the list leaves out is refused with +[`API-025`](ERROR_REFERENCE.md#api-025-query-option-override-not-allowed) +before it runs. The check depends only on whether the keyword is present, +never on its value, and the override is never ignored or clamped. It applies +to `Minigraf::execute`, `Minigraf::query`, `Minigraf::prepare` (a refused +query yields no `PreparedQuery`) and `WriteTransaction::execute` (a refused +query leaves the transaction usable). + +The list **replaces** the defaults; it is not merged with them. Duplicates +have no effect. + +```rust +use minigraf::{OpenOptions, Overridable}; + +// Query text may not override any limit, e.g. when it comes from users or an LLM. +let db = OpenOptions::new() + .allow_overrides([]) + .path("app.graph") + .open()?; + +// Only :max-results; :max-derived-facts is refused with API-025. +let db = OpenOptions::new() + .allow_overrides([Overridable::MaxResults]) + .open_memory()?; + +// The defaults plus another variant (for keywords added later). +let opts = OpenOptions::new().allow_overrides( + Overridable::DEFAULTS.iter().copied().chain([/* Overridable::… */]), +); +``` + +`Overridable` is `#[non_exhaustive]`: later releases add variants for new +keywords, such as `:query-memory-limit` (#870, not in `DEFAULTS`) and +`:max-iterations` (#861, in `DEFAULTS`). diff --git a/docs/ERROR_REFERENCE.md b/docs/ERROR_REFERENCE.md index f7d2f8f94b..7fefa70ff4 100644 --- a/docs/ERROR_REFERENCE.md +++ b/docs/ERROR_REFERENCE.md @@ -239,6 +239,7 @@ with no `CodedError` anywhere in its chain. | API-022 | Missing bind value for slot | Database API | | API-023 | Bind slot not permitted in attribute position | Database API | | API-024 | Bind slot type mismatch | Database API | +| API-025 | Query option override not allowed | Database API | | INT-000 | Unclassified internal error | Internal | | INT-001 | WriteTransaction already in progress on this thread | Internal | | INT-002 | Invalid entity (API layer) | Internal | @@ -3651,6 +3652,18 @@ ValueSet::new(vec![inner]) // API-021 **Scenario**: `:as-of $tx` is bound to `Val(Integer(5))` instead of `TxCount(5)`. +### API-025 Query option override not allowed + +**Error text**: `query option {} is not allowed on this database; OpenOptions::allow_overrides does not list Overridable::{}` + +**Cause**: The query used a keyword that overrides one of the database's settings, such as `:max-derived-facts` or `:max-results`, and the embedder's `OpenOptions::allow_overrides` list leaves that keyword out. The query is refused before it runs, by `execute`, `query`, `prepare` and `WriteTransaction::execute`; a refused statement in a `WriteTransaction` leaves the transaction usable. When a query uses several refused keywords, the message names the first in the order `:max-derived-facts`, `:max-results`. The list is not stored in the file: each open sets it, and the default (`Overridable::DEFAULTS`) allows both keywords. + +**Resolution**: +- Remove the keyword from the query and rely on the database's own setting. +- Or, if the embedder means to let queries override it, add the `Overridable` variant to `OpenOptions::allow_overrides`. The list replaces the defaults; chain `Overridable::DEFAULTS` to add to them. + +**Scenario**: An application opens its database with `OpenOptions::new().allow_overrides([])` so that query text from its users cannot raise `max_derived_facts`; a user query ending in `:max-derived-facts 100000000` is refused with API-025. + --- ## INT — Internal Errors diff --git a/docs/TEST_COVERAGE.md b/docs/TEST_COVERAGE.md index 788f305e75..7fb32a03fe 100644 --- a/docs/TEST_COVERAGE.md +++ b/docs/TEST_COVERAGE.md @@ -641,14 +641,15 @@ These are not `#[test]`s; run them with `cargo kani` or `.github/workflows/kani. - The forms next to them still run: an option followed by a keyword, `(- ?n 1)`, a zero-argument rule. - Thirteen new `tests/grammar/invalid/syntax/` fixtures. - **Grammar page** (`tests/grammar_doc.rs`, 10 tests; #643): `docs/GRAMMAR.md` matches the EBNF rendered from `tests/grammar/grammar.pest`. Each rendering rule is checked on a small grammar: sequence, choice and grouping, names and builtins, `SOI`/`EOI` dropped, lookaheads as comments, bounded repetition, quoting, token marks, section titles, line breaking, the whitespace note and the comment note it joins. +- **`OpenOptions::allow_overrides`** (#869; `tests/allow_overrides_test.rs`, 6 tests; `src/overrides.rs`, 2 unit tests; 1 doc test on `OpenOptions::allow_overrides`): the defaults allow `:max-derived-facts` and `:max-results`; an empty list refuses each with `API-025` from `execute`, `query`, `prepare` and `WriteTransaction::execute`, and queries without them still run; a list replaces the defaults; a refused statement leaves the write transaction usable; `DEFAULTS` read back, chained and with duplicates; the list holds on a file database and is not persisted; `:max-derived-facts` is reported first when both keywords are refused. API-025's registration and documentation are checked by the registry tests. ## Browser and WASI None of these are counted in the summary. The wasm32 targets run in CI (`.github/workflows/wasm.yml`). -- **In a browser** (`wasm-pack test --headless`, Firefox and Chrome): 61 `wasm_bindgen_test` tests. The final #641 snapshot passed in headless Firefox on the bench; Chrome remains a CI run. +- **In a browser** (`wasm-pack test --headless`, Firefox and Chrome): 62 `wasm_bindgen_test` tests. The final #641 snapshot passed in headless Firefox on the bench; Chrome remains a CI run. - Three committed-memory-backend input-order fixtures: scalar Sort omission, streaming counts with Boolean/float representatives and mixed numeric group order, and partition windows preserving float edges and numeric group classes (#641). - - Twenty-five for `BrowserDb`, including IndexedDB persistence, the cursor, and the flush returning every dirty page and failing on one it cannot read (#470). + - Twenty-six for `BrowserDb`, including IndexedDB persistence, the default `allow_overrides` list (#869), the cursor, and the flush returning every dirty page and failing on one it cannot read (#470). - Eleven for `BrowserBufferBackend` (which used `#[test]` and never ran before). - Two checking that IndexedDB page keys accept only whole numbers from 0 to 2^53. - Fifteen for `BrowserDb` user functions (#180), below. diff --git a/src/browser/mod.rs b/src/browser/mod.rs index 6fcd00a954..89237028aa 100644 --- a/src/browser/mod.rs +++ b/src/browser/mod.rs @@ -121,6 +121,11 @@ impl BrowserDb { #[wasm_bindgen(js_name = execute)] pub async fn execute(&self, datalog: String) -> Result { let cmd = parse_datalog_command(&datalog).map_err(to_js_error)?; + // BrowserDb takes no options: the default override list (#869). + if let DatalogCommand::Query(q) = &cmd { + crate::overrides::check_overrides(q, crate::Overridable::DEFAULTS) + .map_err(to_js_error)?; + } // Peek at the discriminant before consuming `cmd`. let is_read = matches!(cmd, DatalogCommand::Query(_) | DatalogCommand::Rule(_)); @@ -318,6 +323,7 @@ impl BrowserDb { DatalogCommand::Retract(_) => bail_coded!(ErrorCode::Api006), DatalogCommand::Rule(_) => bail_coded!(ErrorCode::Api007), }; + crate::overrides::check_overrides(&query, crate::Overridable::DEFAULTS)?; let inner = self.inner.borrow(); // The limits `query` runs with (`DatalogExecutor`'s defaults). crate::query::datalog::prepared::prepare_query( @@ -337,7 +343,10 @@ impl BrowserDb { let cmd = parse_datalog_command(datalog)?; match &cmd { - DatalogCommand::Query(q) => crate::query::datalog::prepared::reject_unbound_slots(q)?, + DatalogCommand::Query(q) => { + crate::overrides::check_overrides(q, crate::Overridable::DEFAULTS)?; + crate::query::datalog::prepared::reject_unbound_slots(q)? + } DatalogCommand::Transact(_) => bail_coded!(ErrorCode::Api012, "transact"), DatalogCommand::Retract(_) => bail_coded!(ErrorCode::Api012, "retract"), DatalogCommand::Rule(_) => bail_coded!(ErrorCode::Api012, "rule"), @@ -710,6 +719,26 @@ mod tests { } } + // #869: BrowserDb takes no options, so the default override list applies. + #[wasm_bindgen_test] + async fn default_override_keywords_still_run() { + let db = BrowserDb::open_in_memory().expect("open_in_memory"); + db.execute("(transact [[:a :edge :b]])".to_string()) + .await + .expect("transact"); + db.execute("(rule [(reach ?x ?y) [?x :edge ?y]])".to_string()) + .await + .expect("rule"); + for q in [ + "(query [:find ?x ?y :where (reach ?x ?y) :max-derived-facts 10])", + "(query [:find ?x ?y :where (reach ?x ?y) :max-results 10])", + ] { + let r = db.execute(q.to_string()).await.expect("query"); + let v: serde_json::Value = serde_json::from_str(&r).unwrap(); + assert_eq!(v["results"].as_array().unwrap().len(), 1); + } + } + #[wasm_bindgen_test] async fn in_memory_transact_and_query() { let db = BrowserDb::open_in_memory().expect("open_in_memory"); diff --git a/src/db.rs b/src/db.rs index e47e9c7080..9384b1a75e 100644 --- a/src/db.rs +++ b/src/db.rs @@ -20,6 +20,7 @@ use crate::error::{ErrorCode, MinigrafError, bail_coded, err_coded}; use crate::graph::FactStorage; use crate::graph::storage::Snapshot; use crate::graph::types::Value; +use crate::overrides::{Overridable, check_overrides}; use crate::query::datalog::evaluator::DEFAULT_MAX_DERIVED_FACTS; use crate::query::datalog::executor::DatalogExecutor; use crate::query::datalog::executor::QueryResult; @@ -213,6 +214,16 @@ pub struct OpenOptions { /// databases never write chunks; a statement is still read a chunk at a /// time. pub transaction_chunk_facts: usize, + /// The query keywords that may override this database's settings (#862). + /// Defaults to [`Overridable::DEFAULTS`], every keyword that could + /// override a setting before the list existed. + /// + /// A query using a keyword the list leaves out fails with `API-025` + /// before it runs, from [`Minigraf::execute`], [`Minigraf::query`], + /// [`Minigraf::prepare`] and [`WriteTransaction::execute`]. The list is + /// not stored in the file: each open sets it. See + /// [`OpenOptions::allow_overrides`](Self::allow_overrides) for setting it. + pub allow_overrides: Vec, } #[allow(deprecated)] // `max_results`, kept as an alias until it is removed @@ -228,6 +239,7 @@ impl Default for OpenOptions { read_only: false, query_memory_limit: usize::MAX, transaction_chunk_facts: statement::DEFAULT_TX_CHUNK_FACTS, + allow_overrides: Overridable::DEFAULTS.to_vec(), } } } @@ -305,6 +317,36 @@ impl OpenOptions { self.max_derived_facts.min(self.max_results) } + /// Set the query keywords that may override this database's settings. + /// See [`OpenOptions::allow_overrides`](Self::allow_overrides) (the field). + /// + /// The list **replaces** the defaults rather than adding to them: an + /// empty list refuses every override keyword with `API-025`, and listing + /// only one refuses the others. To add to the defaults, chain them: + /// + /// ``` + /// use minigraf::{OpenOptions, Overridable}; + /// + /// // Refuse every query keyword that overrides a limit. + /// let locked = OpenOptions::new().allow_overrides([]).open_memory().unwrap(); + /// locked.execute("(rule [(r ?x) [?x :a 1]])").unwrap(); + /// let err = locked + /// .execute("(query [:find ?x :where (r ?x) :max-derived-facts 10])") + /// .unwrap_err(); + /// assert_eq!(err.code(), "API-025"); + /// + /// // The defaults plus anything else (duplicates have no effect). + /// let opts = OpenOptions::new().allow_overrides( + /// Overridable::DEFAULTS.iter().copied().chain([Overridable::MaxResults]), + /// ); + /// assert!(opts.allow_overrides.contains(&Overridable::MaxDerivedFacts)); + /// ``` + #[must_use] + pub fn allow_overrides(mut self, list: impl IntoIterator) -> Self { + self.allow_overrides = list.into_iter().collect(); + self + } + /// Open even when the filesystem cannot lock files. See /// [`OpenOptions::allow_unlocked`] for when this is appropriate. #[must_use] @@ -758,6 +800,7 @@ impl Minigraf { let cmd = parse_datalog_command(input)?; match cmd { DatalogCommand::Query(ref q) => { + check_overrides(q, &self.inner.options.allow_overrides)?; reject_unbound_slots(q)?; // Read-only: no lock needed let snapshot = self.inner.fact_storage.snapshot()?; @@ -979,7 +1022,10 @@ impl Minigraf { } let cmd = parse_datalog_command(input)?; match &cmd { - DatalogCommand::Query(q) => reject_unbound_slots(q)?, + DatalogCommand::Query(q) => { + check_overrides(q, &self.inner.options.allow_overrides)?; + reject_unbound_slots(q)? + } DatalogCommand::Transact(_) => bail_coded!(ErrorCode::Api012, "transact"), DatalogCommand::Retract(_) => bail_coded!(ErrorCode::Api012, "retract"), DatalogCommand::Rule(_) => bail_coded!(ErrorCode::Api012, "rule"), @@ -1357,6 +1403,7 @@ impl Minigraf { bail_coded!(ErrorCode::Api007); } }; + check_overrides(&query, &self.inner.options.allow_overrides)?; prepare_query( query, @@ -1767,6 +1814,7 @@ impl<'a> WriteTransaction<'a> { Err(err_coded!(ErrorCode::Api002)) } DatalogCommand::Query(ref q) => { + check_overrides(q, &self.inner.options.allow_overrides)?; reject_unbound_slots(q)?; self.execute_read_command(cmd) } @@ -2686,6 +2734,7 @@ mod tests { read_only: false, query_memory_limit: usize::MAX, transaction_chunk_facts: 65_536, + allow_overrides: Overridable::DEFAULTS.to_vec(), }; let db = Minigraf::open_with_options(&path, opts).unwrap(); assert_eq!(db.inner.options.wal_checkpoint_threshold, 5); diff --git a/src/error.rs b/src/error.rs index 3760971bde..8cfa974892 100644 --- a/src/error.rs +++ b/src/error.rs @@ -278,6 +278,7 @@ pub(crate) enum ErrorCode { Api022, Api023, Api024, + Api025, Int001, Int002, Int003, @@ -1661,6 +1662,12 @@ pub(crate) const REGISTRY: &[(ErrorCode, &str, &str, ErrorCategory)] = &[ "slot '${}' in {} position requires {}, got {}", ErrorCategory::Api, ), + ( + ErrorCode::Api025, + "API-025", + "query option {} is not allowed on this database; OpenOptions::allow_overrides does not list Overridable::{}", + ErrorCategory::Api, + ), ( ErrorCode::Int001, "INT-001", @@ -2502,6 +2509,7 @@ mod tests { | ErrorCode::Api022 | ErrorCode::Api023 | ErrorCode::Api024 + | ErrorCode::Api025 | ErrorCode::Int001 | ErrorCode::Int002 | ErrorCode::Int003 @@ -2781,6 +2789,7 @@ mod tests { ErrorCode::Api022, ErrorCode::Api023, ErrorCode::Api024, + ErrorCode::Api025, ErrorCode::Int001, ErrorCode::Int002, ErrorCode::Int003, diff --git a/src/lib.rs b/src/lib.rs index ae678daa68..dde2eb59d2 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -90,6 +90,7 @@ pub(crate) mod graph; /// Build a new database from explicit fact records: [`LogWriter`]. #[cfg(not(target_arch = "wasm32"))] pub mod log_writer; +mod overrides; pub(crate) mod query; /// Interactive REPL for exploring a [`Minigraf`] database from the command line. pub mod repl; @@ -107,6 +108,7 @@ pub mod browser; pub use db::OpenOptionsWithPath; pub use db::{IntegrityReport, Minigraf, OpenOptions, SyncMode, WriteTransaction}; pub use error::{ErrorCategory, MinigrafError}; +pub use overrides::Overridable; pub use query::datalog::functions::UdfError; pub use repl::Repl; diff --git a/src/overrides.rs b/src/overrides.rs new file mode 100644 index 0000000000..6ac4258cef --- /dev/null +++ b/src/overrides.rs @@ -0,0 +1,111 @@ +//! Which query keywords may override the database's settings (#862, #869). +//! +//! The embedder lists them in [`OpenOptions::allow_overrides`]; a query that +//! uses a keyword the list leaves out is refused with `API-025` before it runs. +//! +//! [`OpenOptions::allow_overrides`]: crate::OpenOptions::allow_overrides + +use anyhow::Result; + +use crate::error::{ErrorCode, bail_coded}; +use crate::query::datalog::types::DatalogQuery; + +/// A setting that query text may override (#862). +/// +/// `#[non_exhaustive]`: later releases add variants for new query keywords. +#[non_exhaustive] +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub enum Overridable { + /// `:max-derived-facts N`, which overrides + /// [`OpenOptions::max_derived_facts`](crate::OpenOptions::max_derived_facts). + MaxDerivedFacts, + /// `:max-results N`, the deprecated alias of `:max-derived-facts`. + MaxResults, +} + +impl Overridable { + /// The list a database uses when + /// [`OpenOptions::allow_overrides`](crate::OpenOptions::allow_overrides) + /// is not set: every keyword that could override a setting before #862. + pub const DEFAULTS: &'static [Overridable] = + &[Overridable::MaxDerivedFacts, Overridable::MaxResults]; + + /// The query keyword this variant gates, e.g. `":max-derived-facts"`. + pub fn keyword(self) -> &'static str { + match self { + Overridable::MaxDerivedFacts => ":max-derived-facts", + Overridable::MaxResults => ":max-results", + } + } + + fn name(self) -> &'static str { + match self { + Overridable::MaxDerivedFacts => "MaxDerivedFacts", + Overridable::MaxResults => "MaxResults", + } + } +} + +/// Refuse a query that uses a keyword `allowed` does not list (`API-025`). +/// +/// Checks the keywords in a fixed order and reports the first one refused. +/// Only the top-level query takes keywords; rule bodies take none. +pub(crate) fn check_overrides(query: &DatalogQuery, allowed: &[Overridable]) -> Result<()> { + let present = [ + ( + Overridable::MaxDerivedFacts, + query.max_derived_facts.is_some(), + ), + (Overridable::MaxResults, query.max_results.is_some()), + ]; + for (setting, used) in present { + if used && !allowed.contains(&setting) { + bail_coded!(ErrorCode::Api025, setting.keyword(), setting.name()); + } + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::query::datalog::parser::parse_datalog_command; + use crate::query::datalog::types::DatalogCommand; + + fn query(text: &str) -> DatalogQuery { + match parse_datalog_command(text).expect("parse") { + DatalogCommand::Query(q) => q, + _ => panic!("expected a query"), + } + } + + fn code(r: Result<()>) -> String { + crate::MinigrafError::from(r.expect_err("refused")) + .code() + .to_string() + } + + #[test] + fn reports_max_derived_facts_first() { + let q = query("(query [:find ?e :where [?e :a ?v] :max-derived-facts 5 :max-results 5])"); + let err = crate::MinigrafError::from(check_overrides(&q, &[]).expect_err("refused")); + assert_eq!(err.code(), "API-025"); + assert!(err.to_string().contains(":max-derived-facts")); + assert!(err.to_string().contains("Overridable::MaxDerivedFacts")); + assert!(!err.to_string().contains(":max-results")); + } + + #[test] + fn listed_and_absent_keywords_pass() { + let both = + query("(query [:find ?e :where [?e :a ?v] :max-derived-facts 5 :max-results 5])"); + check_overrides(&both, Overridable::DEFAULTS).expect("defaults allow both"); + let plain = query("(query [:find ?e :where [?e :a ?v]])"); + check_overrides(&plain, &[]).expect("no keyword"); + let results = query("(query [:find ?e :where [?e :a ?v] :max-results 5])"); + assert_eq!( + code(check_overrides(&results, &[Overridable::MaxDerivedFacts])), + "API-025" + ); + } +} diff --git a/tests/allow_overrides_test.rs b/tests/allow_overrides_test.rs new file mode 100644 index 0000000000..e46521bbe8 --- /dev/null +++ b/tests/allow_overrides_test.rs @@ -0,0 +1,133 @@ +#![cfg(not(target_arch = "wasm32"))] +//! `OpenOptions::allow_overrides` (#869, spec #862 §1–§2): the embedder +//! decides which query keywords may override its limits; a keyword the list +//! leaves out is refused with `API-025` before the query runs. + +use minigraf::{Minigraf, OpenOptions, Overridable, QueryResult}; + +const RULE: &str = "(rule [(reach ?x ?y) [?x :edge ?y]])"; +const DERIVED: &str = "(query [:find ?x ?y :where (reach ?x ?y) :max-derived-facts 100])"; +const RESULTS: &str = "(query [:find ?x ?y :where (reach ?x ?y) :max-results 100])"; +const PLAIN: &str = "(query [:find ?x ?y :where (reach ?x ?y)])"; + +fn setup(opts: OpenOptions) -> Minigraf { + let db = opts.open_memory().expect("open"); + db.execute("(transact [[:a :edge :b] [:b :edge :c]])") + .expect("transact"); + db.execute(RULE).expect("rule"); + db +} + +fn rows(r: QueryResult) -> usize { + match r { + QueryResult::QueryResults { results, .. } => results.len(), + _ => panic!("expected query results"), + } +} + +fn refused(err: minigraf::MinigrafError, keyword: &str) { + assert_eq!(err.code(), "API-025", "expected API-025"); + assert!( + err.to_string().contains(keyword), + "message names the keyword" + ); +} + +#[test] +fn defaults_allow_both_keywords() { + let db = setup(OpenOptions::new()); + assert_eq!(rows(db.execute(DERIVED).expect("derived")), 2); + assert_eq!(rows(db.execute(RESULTS).expect("results")), 2); +} + +#[test] +fn empty_list_refuses_every_entry_point() { + let db = setup(OpenOptions::new().allow_overrides([])); + for (q, kw) in [(DERIVED, ":max-derived-facts"), (RESULTS, ":max-results")] { + refused(db.execute(q).err().expect("execute refused"), kw); + refused(db.query(q).err().expect("query refused"), kw); + refused(db.prepare(q).err().expect("prepare refused"), kw); + let mut tx = db.begin_write().expect("begin"); + refused(tx.execute(q).err().expect("tx refused"), kw); + tx.rollback(); + } + assert_eq!(rows(db.execute(PLAIN).expect("plain")), 2); + assert_eq!(db.query(PLAIN).expect("cursor").count(), 2); + assert_eq!( + rows( + db.prepare(PLAIN) + .expect("prepare") + .execute(&[]) + .expect("run") + ), + 2 + ); +} + +#[test] +fn list_replaces_defaults() { + let db = setup(OpenOptions::new().allow_overrides([Overridable::MaxResults])); + refused( + db.execute(DERIVED).err().expect("refused"), + ":max-derived-facts", + ); + assert_eq!(rows(db.execute(RESULTS).expect("allowed")), 2); +} + +#[test] +fn refused_tx_execute_leaves_transaction_usable() { + let db = setup(OpenOptions::new().allow_overrides([])); + let mut tx = db.begin_write().expect("begin"); + refused( + tx.execute(DERIVED).err().expect("refused"), + ":max-derived-facts", + ); + tx.execute("(transact [[:c :edge :d]])").expect("transact"); + tx.commit().expect("commit"); + assert_eq!(rows(db.execute(PLAIN).expect("plain")), 3); +} + +#[test] +fn defaults_read_back_and_compose() { + assert_eq!( + OpenOptions::default().allow_overrides, + Overridable::DEFAULTS.to_vec() + ); + assert_eq!( + Overridable::DEFAULTS, + &[Overridable::MaxDerivedFacts, Overridable::MaxResults] + ); + assert_eq!(Overridable::MaxDerivedFacts.keyword(), ":max-derived-facts"); + assert_eq!(Overridable::MaxResults.keyword(), ":max-results"); + + let list: Vec = Overridable::DEFAULTS + .iter() + .copied() + .chain([Overridable::MaxResults, Overridable::MaxResults]) + .collect(); + let db = setup(OpenOptions::new().allow_overrides(list)); + assert_eq!(rows(db.execute(DERIVED).expect("derived")), 2); + assert_eq!(rows(db.execute(RESULTS).expect("results")), 2); +} + +#[test] +fn file_database_option_not_persisted() { + let dir = tempfile::tempdir().expect("tempdir"); + let path = dir.path().join("o.graph"); + { + let db = OpenOptions::new() + .allow_overrides([]) + .path(&path) + .open() + .expect("open"); + db.execute("(transact [[:a :edge :b]])").expect("transact"); + db.execute(RULE).expect("rule"); + refused( + db.execute(DERIVED).err().expect("refused"), + ":max-derived-facts", + ); + } + let db = Minigraf::open(&path).expect("reopen"); + db.execute(RULE).expect("rule"); + assert_eq!(rows(db.execute(DERIVED).expect("allowed")), 1); +} From 4b318d2882c6706aa0e4535c3a19d76654b95680 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Fri, 6 Nov 2026 13:36:06 +0530 Subject: [PATCH 3/3] docs: #869 test counts Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01H2a7QoYX6tc5G3sKVzvLjD --- CLAUDE.md | 2 +- docs/TEST_COVERAGE.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a974f2cbea..41e9810686 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -245,7 +245,7 @@ Auto-migrates v7 → v8 on open (spec §9, with a backup meta page). v1–v6 are ## Test Coverage -**2062 tests** (2041 active, 21 ignored; unit + integration + doc). Engine answers once checked by the executor are frozen in `tests/answers/` (#551). +**2071 tests** (2050 active, 21 ignored; unit + integration + doc). Engine answers once checked by the executor are frozen in `tests/answers/` (#551). See `docs/TEST_COVERAGE.md` for the full per-file breakdown. The #760 deterministic storage suite adds three native unit tests in a separate `--cfg minigraf_shuttle` build, outside the default count. Run only `graph::storage::deterministic::` with that cfg; ordinary unit tests do not enter its scheduler. `deterministic-schedules.yml` runs relevant v3 PRs on Linux/macOS/Windows plus Linux MSRV, and larger nightly/manual searches with replay artifacts. The identical main workflow activates the v3 schedule after both PRs merge. See `docs/testing/deterministic-schedules.md` for scope, controls and findings. diff --git a/docs/TEST_COVERAGE.md b/docs/TEST_COVERAGE.md index 7fb32a03fe..ab082c56e6 100644 --- a/docs/TEST_COVERAGE.md +++ b/docs/TEST_COVERAGE.md @@ -4,12 +4,12 @@ | | Default features | With `--features test-hooks` | |---|---|---| -| **Active** | 2,041 | 2,076 | +| **Active** | 2,050 | 2,085 | | **Ignored** | 21 | 24 | -| **Total** | 2,062 | 2,100 | +| **Total** | 2,071 | 2,109 | Counts above are the current Cargo test inventory (active versus ignored), -including #777, #789, #781, #794, #795, #837 and #865 (Linux). Verification results below identify which suites ran. +including #777, #789, #781, #794, #795, #837, #865 and #869 (Linux). Verification results below identify which suites ran. **#838 manual migration verification**: the [manual sweep](benchmarks/838-migration/README.md) checks every fixture value and cursor snapshot before accepting timings, including