Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- **Formats v1–v6 are no longer readable.** Opening one fails with the new `STG-028`; open it once with Minigraf v2.x to upgrade it to v7 first. `STG-003` and `STG-004` are deprecated (no longer emitted, still registered, never reused). `STG-005` and `STG-006` message text changed.
- **Empty or inverted valid-time windows are rejected** (#436). A `transact` whose effective window for any fact ends at or before it starts fails with the new `API-019`, writes nothing and takes no transaction number. The effective window is the one after defaults, so `(transact {:valid-to "2020-01-01"} ...)` is rejected too: its `:valid-from` is the transaction time. This applies to `execute`, each `WriteTransaction::execute` statement and, with the commit time, `WriteTransaction::commit`, and the browser. Before, such a fact was stored, never matched `:valid-at`, and still showed up under `:any-valid-time`. Files that already hold such facts open and read as before.
- **In a `WriteTransaction`, the last statement that writes a fact decides it** (#477). When several `execute` calls in one `WriteTransaction` write the same `(entity, attribute, value)`, in any mix of `transact` and `retract`, the commit keeps only the records from the last of them. Before, reads inside the transaction already followed statement order, but the commit stamped every record with one transaction number and a retraction always won: a fact retracted and then asserted again read as live before `commit()` and was gone after it. Two windows of one fact in separate statements, which were `API-011`, now commit the later window. `API-011` is limited to one `transact`; `tx.execute()` raises it and stages nothing, and the transaction stays usable. `LogWriter` keeps the same rules (see the log writer entry).
- **A `:find` variable that nothing binds is an error** (#406). A query whose `:find` names a variable that no `:where` clause binds now fails at parse time with the new `PRS-080`, naming the variable, from `execute()`, `query()` and `prepare()`. Before, it returned no results, so a typo in `:find` looked the same as "no matching data". The same check covers a window function's argument, `:partition-by` and `:order-by` variables. A variable counts as bound when it appears in a pattern, a rule call, an expression binding, an `or-join` join vector or every branch of an `or`; one that appears only inside `not`/`not-join`, or a `?_` wildcard, does not.
- **An unknown aggregate or window function is an error whatever the data** (#414). Aggregate and window function names in `:find` are now resolved before the query runs: an unknown aggregate fails with the new `QRY-010` and an unknown window function with the new `QRY-011`, even on an empty database or when no row matches. Before, such a query returned no results until a row matched and then failed with `INT-029`/`INT-030`, which stay registered for internal inconsistencies only.
- **One current valid-time window per fact** (#435). At any transaction time, each `(entity, attribute, value)` now has exactly one current valid-time window: the one from its latest `transact`. A later assertion of the same fact replaces the earlier window, which stays visible through `:as-of` of the earlier transaction. Before, every window ever asserted stayed live until a `retract`, so closing an open window with `(transact {:valid-from vf :valid-to D} ...)` left the open one live and `:valid-at` after `D` still found the fact. Closing, extending or reopening a window is now a plain `transact` with the new bounds; `retract` still withdraws the fact. **This changes query results for existing data:** a fact asserted in several transactions with different windows is now valid only in its latest window at the current transaction time. A fact that was true over two separate periods can no longer have both windows live at once; model each period as its own entity, or read earlier periods with `:as-of`. Asserting one fact with two different windows in one `transact` is rejected with the new `API-011`, and nothing is written. Data written before this check with two windows in one transaction keeps both.

### Added
Expand Down
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,7 @@ Auto-migrates v7 → v8 on open (spec §9, with a backup meta page). v1–v6 are

## Test Coverage

**1360 tests** (1351 passing, 9 ignored; unit + integration + doc).
**1372 tests** (1363 passing, 9 ignored; unit + integration + doc).
See `docs/TEST_COVERAGE.md` for the full per-file breakdown.

**Testing conventions** — see the Testing Conventions section below before writing any tests.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ let r2 = pq.execute(&[("tx", BindValue::TxCount(2)), ("entity", BindValue::Entit

```bash
cargo run # interactive Datalog REPL
cargo test # run 1360 tests
cargo test # run 1372 tests
cargo run < demos/demo_recursive.txt # recursive rules demo
```

Expand Down
59 changes: 59 additions & 0 deletions docs/ERROR_REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,7 @@ with no `CodedError` anywhere in its chain.
| PRS-077 | Unexpected trailing input after a complete form | Parser |
| PRS-078 | Query rejects unexpected trailing argument(s) | Parser |
| PRS-079 | Rule rejects unexpected trailing argument(s) | Parser |
| PRS-080 | :find variable not bound in :where | Parser |
| QRY-001 | Invalid entity | Query Execution |
| QRY-002 | Attribute must be a keyword | Query Execution |
| QRY-003 | Cannot transact a pseudo-attribute | Query Execution |
Expand All @@ -109,6 +110,8 @@ with no `CodedError` anywhere in its chain.
| QRY-007 | Unknown predicate | Query Execution |
| QRY-008 | Functions lock poisoned | Query Execution |
| QRY-009 | Rules lock poisoned | Query Execution |
| QRY-010 | Unknown aggregate function | Query Execution |
| QRY-011 | Unknown window function | Query Execution |
| STG-001 | Invalid header: too short | Storage |
| STG-002 | Invalid magic number: not a .graph file | Storage |
| STG-003 | Invalid v4/v5/v6 header too short (deprecated) | Storage |
Expand Down Expand Up @@ -1555,6 +1558,22 @@ $<4097-char-slot-name>
```
*Nothing may follow the rule vector; remove `:unexpected-extra`*

### PRS-080 :find variable not bound in :where

**Error text**: `:find variable {} not bound in :where`

**Cause**: A variable in `:find` — a plain variable, or the argument, `:partition-by` or `:order-by` variable of a window function — is not bound by any `:where` clause. Variables count as bound when they appear in a pattern, a rule call, an expression binding (`[(+ ?a 1) ?b]`), an `or-join` join vector, or every branch of an `or`. Variables that appear only inside `not`/`not-join`, and `?_` wildcards, are not bound. Before v3.0.0 such a query returned no results, so a typo in `:find` looked the same as "no matching data".

**Resolution**:
- Check the variable name for typos against the `:where` clauses.
- Add a clause that binds the variable, or remove it from `:find`.

**Example**:
```datalog
(query [:find ?n :where [?e :person/name ?name]])
```
*`?n` is never bound; use `?name`*

---

## QRY — Query Execution Errors
Expand Down Expand Up @@ -1695,6 +1714,38 @@ predicate evaluation, or fact transacting.

**Scenario**: `db.execute("(rule ...)")` panics; subsequent queries that reference rules return this error.

### QRY-010 Unknown aggregate function

**Error text**: `unknown aggregate function: '{}'`

**Cause**: A `:find` aggregate names a function that is neither built-in (`count`, `count-distinct`, `sum`, `sum-distinct`, `avg`, `min`, `max`) nor registered with `db.register_aggregate()`. The name is resolved before the query runs, so the error does not depend on whether any row matches. Before v3.0.0 a query with no matching rows returned an empty result instead (see INT-029).

**Resolution**:
- Check the function name for typos.
- Register a custom aggregate first: `db.register_aggregate("frob", init, step, finalise)?;`.

**Example**:
```datalog
(query [:find (frob ?b) :where [?a :x ?b]])
```
*`frob` is not built-in; register it with `register_aggregate()` before querying*

### QRY-011 Unknown window function

**Error text**: `unknown window function '{}' — register it with register_aggregate() before querying`

**Cause**: A `:find` window expression (`... :over (...)`) names a function that is neither a window built-in (`sum`, `count`, `min`, `max`, `avg`, `rank`, `row-number`) nor registered with `db.register_aggregate()`. The name is resolved before the query runs, so the error does not depend on whether any row matches. Before v3.0.0 a query with no matching rows returned an empty result instead (see INT-030).

**Resolution**:
- Check the function name for typos.
- Register the function with `db.register_aggregate()` before using it in an `:over` clause.

**Example**:
```datalog
(query [:find ?b (frob ?b :over (:order-by ?b)) :where [?a :x ?b]])
```
*`frob` is not a window built-in; register it first*

---

## STG — Storage Errors
Expand Down Expand Up @@ -3031,6 +3082,10 @@ nor a user-defined function registered via `db.register_aggregate()`.
- Check the function name for typos, or register it first with
`db.register_aggregate()`.

Since v3.0.0, `:find` aggregates are resolved before the query runs and an
unknown name is reported as QRY-010. INT-029 now only signals an internal
inconsistency (a name that passed that check but is missing at aggregation).

### INT-030 Unknown window function

**Error text**: `unknown window function '{}' — register it with register_aggregate() before querying`
Expand All @@ -3042,6 +3097,10 @@ not a recognized window-compatible built-in and has not been registered.
- Register the function with `db.register_aggregate()` before using it in
an `:over` clause.

Since v3.0.0, window functions are resolved before the query runs and an
unknown name is reported as QRY-011. INT-030 now only signals an internal
inconsistency (a name that passed that check but is missing at evaluation).

### INT-031 or-join variable not bound in incoming scope

**Error text**: `or-join variable {} is not bound in the incoming scope`
Expand Down
6 changes: 3 additions & 3 deletions docs/TEST_COVERAGE.md

Large diffs are not rendered by default.

27 changes: 27 additions & 0 deletions src/error.rs
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,7 @@ pub(crate) enum ErrorCode {
Prs077,
Prs078,
Prs079,
Prs080,
Qry001,
Qry002,
Qry003,
Expand All @@ -135,6 +136,8 @@ pub(crate) enum ErrorCode {
Qry007,
Qry008,
Qry009,
Qry010,
Qry011,
Int000,
Stg001,
Stg002,
Expand Down Expand Up @@ -747,6 +750,12 @@ pub(crate) const REGISTRY: &[(ErrorCode, &str, &str, ErrorCategory)] = &[
"rule takes (rule [...]); found {} unexpected trailing argument(s)",
ErrorCategory::Parser,
),
(
ErrorCode::Prs080,
"PRS-080",
":find variable {} not bound in :where",
ErrorCategory::Parser,
),
(
ErrorCode::Qry001,
"QRY-001",
Expand Down Expand Up @@ -801,6 +810,18 @@ pub(crate) const REGISTRY: &[(ErrorCode, &str, &str, ErrorCategory)] = &[
"rules lock poisoned",
ErrorCategory::Query,
),
(
ErrorCode::Qry010,
"QRY-010",
"unknown aggregate function: '{}'",
ErrorCategory::Query,
),
(
ErrorCode::Qry011,
"QRY-011",
"unknown window function '{}' — register it with register_aggregate() before querying",
ErrorCategory::Query,
),
(
ErrorCode::Int000,
"INT-000",
Expand Down Expand Up @@ -1923,6 +1944,7 @@ mod tests {
| ErrorCode::Prs077
| ErrorCode::Prs078
| ErrorCode::Prs079
| ErrorCode::Prs080
| ErrorCode::Qry001
| ErrorCode::Qry002
| ErrorCode::Qry003
Expand All @@ -1932,6 +1954,8 @@ mod tests {
| ErrorCode::Qry007
| ErrorCode::Qry008
| ErrorCode::Qry009
| ErrorCode::Qry010
| ErrorCode::Qry011
| ErrorCode::Stg001
| ErrorCode::Stg002
| ErrorCode::Stg003
Expand Down Expand Up @@ -2141,6 +2165,7 @@ mod tests {
ErrorCode::Prs077,
ErrorCode::Prs078,
ErrorCode::Prs079,
ErrorCode::Prs080,
ErrorCode::Qry001,
ErrorCode::Qry002,
ErrorCode::Qry003,
Expand All @@ -2150,6 +2175,8 @@ mod tests {
ErrorCode::Qry007,
ErrorCode::Qry008,
ErrorCode::Qry009,
ErrorCode::Qry010,
ErrorCode::Qry011,
ErrorCode::Stg001,
ErrorCode::Stg002,
ErrorCode::Stg003,
Expand Down
35 changes: 35 additions & 0 deletions src/query/datalog/executor.rs
Original file line number Diff line number Diff line change
Expand Up @@ -467,6 +467,16 @@ impl DatalogExecutor {

/// Execute a query: find matching facts and return specified variables
fn execute_query(&self, query: DatalogQuery) -> Result<QueryResult> {
// Resolve :find functions up front so an unknown name fails whether or
// not any row matches (#414).
{
let registry = self
.functions
.read()
.map_err(|_| err_coded!(ErrorCode::Qry008))?;
check_find_functions(&query.find, &registry)?;
}

// Check if query uses rules
if query.uses_rules() {
// Use StratifiedEvaluator for queries with rule invocations (handles negation and strata)
Expand Down Expand Up @@ -2316,6 +2326,31 @@ fn eval_binop(op: &BinOp, l: Value, r: Value) -> Result<Value, ()> {

/// Evaluate an Expr against a binding map.
///
/// Rejects aggregate and window functions in `:find` that are neither
/// built-in nor registered. Runs before execution, so the result does not
/// depend on the data (#414).
fn check_find_functions(find: &[FindSpec], registry: &FunctionRegistry) -> Result<()> {
for spec in find {
match spec {
FindSpec::Aggregate { func, .. } => {
if registry.get(func).is_none() {
bail_coded!(ErrorCode::Qry010, func);
}
}
FindSpec::Window(ws) => {
if !matches!(ws.func, WindowFunc::Rank | WindowFunc::RowNumber) {
let name = ws.func_name();
if registry.get(&name).is_none() {
bail_coded!(ErrorCode::Qry011, name);
}
}
}
FindSpec::Variable(_) => {}
}
}
Ok(())
}

/// Returns `Err(())` on: unbound variable, type mismatch, division by zero, unknown UDF predicate.
pub(crate) fn eval_expr(
expr: &Expr,
Expand Down
30 changes: 25 additions & 5 deletions src/query/datalog/parser.rs
Original file line number Diff line number Diff line change
Expand Up @@ -920,12 +920,32 @@ fn parse_query(elements: &[EdnValue]) -> Result<DatalogCommand> {
check_not_join_safety(&where_clauses, &outer_bound)?;
check_expr_safety(&where_clauses)?;

// Validate aggregate and :with vars are bound in :where
// Validate :find and :with vars are bound in :where. An unbound :find
// variable (e.g. a typo) would otherwise return an empty result (#406).
for spec in &find_specs {
if let FindSpec::Aggregate { var, .. } = spec
&& !outer_bound.contains(var)
{
bail_coded!(ErrorCode::Prs023, var);
match spec {
FindSpec::Variable(var) => {
if !outer_bound.contains(var) {
bail_coded!(ErrorCode::Prs080, var);
}
}
FindSpec::Aggregate { var, .. } => {
if !outer_bound.contains(var) {
bail_coded!(ErrorCode::Prs023, var);
}
}
FindSpec::Window(ws) => {
let window_vars = ws
.var
.iter()
.chain(ws.partition_by.iter())
.chain(std::iter::once(&ws.order_by));
for var in window_vars {
if !outer_bound.contains(var) {
bail_coded!(ErrorCode::Prs080, var);
}
}
}
}
}
for var in &with_vars {
Expand Down
2 changes: 1 addition & 1 deletion src/query/datalog/prepared.rs
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ fn bind_value_type_name(bv: &BindValue) -> &'static str {
/// let db = Minigraf::in_memory().unwrap();
/// db.execute(r#"(transact [[:alice :person/age 30] [:bob :person/age 25]])"#).unwrap();
///
/// let pq = db.prepare("(query [:find ?name :where [?e :person/age $age]])").unwrap();
/// let pq = db.prepare("(query [:find ?e :where [?e :person/age $age]])").unwrap();
///
/// // Re-use the same prepared query with different bindings
/// let young = pq.execute(&[("age", BindValue::Val(Value::Integer(25)))]).unwrap();
Expand Down
55 changes: 55 additions & 0 deletions tests/error_codes_prs_test.rs
Original file line number Diff line number Diff line change
Expand Up @@ -367,6 +367,61 @@ fn prs_codes_cover_trailing_argument_rejection() {
}
}

// ── PRS-080: a :find variable must be bound in :where (#406) ───────────────

#[test]
fn prs_080_rejects_unbound_find_variables() {
let cases: &[&str] = &[
// Plain :find variable that appears nowhere in :where (a typo).
r#"(query [:find ?n :where [?e :y ?v]])"#,
// One bound, one unbound.
r#"(query [:find ?e ?n :where [?e :y ?v]])"#,
// `?_` variables are wildcards and never bind.
r#"(query [:find ?_x :where [?_x :y 1]])"#,
// Window function argument, :partition-by and :order-by variables.
r#"(query [:find ?e (sum ?n :over (:order-by ?v)) :where [?e :y ?v]])"#,
r#"(query [:find ?e (rank :over (:partition-by ?p :order-by ?v)) :where [?e :y ?v]])"#,
r#"(query [:find ?e (row-number :over (:order-by ?o)) :where [?e :y ?v]])"#,
];
for input in cases {
assert_execute_code(input, "PRS-080");
assert_prepare_code(input, "PRS-080");
}
}

#[test]
fn prs_080_names_the_unbound_variable() {
let err = db()
.execute(r#"(query [:find ?e ?typo :where [?e :y ?v]])"#)
.expect_err("unbound :find variable must fail");
assert!(err.to_string().contains("?typo"), "message names ?typo");
}

#[test]
fn find_variables_bound_by_any_binding_clause_are_accepted() {
let db = db();
db.execute(r#"(transact [[:a :y 1] [:a :z 2]])"#).unwrap();
db.execute(r#"(rule [(r ?x ?y) [?x :y ?y]])"#).unwrap();
let cases: &[&str] = &[
r#"(query [:find ?e ?v :where [?e :y ?v]])"#,
r#"(query [:find ?e ?a :where [?e ?a 1]])"#,
r#"(query [:find ?x ?y :where (r ?x ?y)])"#,
r#"(query [:find ?e ?w :where [?e :y ?v] [(+ ?v 1) ?w]])"#,
r#"(query [:find ?e ?v :where [?e :y ?v] (or-join [?e] [?e :z 2] [?e :y 3])])"#,
r#"(query [:find ?e ?v :where (or [?e :y ?v] [?e :z ?v])])"#,
r#"(query [:find ?e ?vf :any-valid-time :where [?e :y ?v] [?e :db/valid-from ?vf]])"#,
r#"(query [:find ?e (sum ?v :over (:partition-by ?e :order-by ?v)) :where [?e :y ?v]])"#,
];
for input in cases {
db.execute(input).expect("query with bound :find variables");
}
let pq = db
.prepare(r#"(query [:find ?e :where [?e :y $v]])"#)
.expect("bind slots are values, not :find variables");
pq.execute(&[("v", minigraf::BindValue::Val(minigraf::Value::Integer(1)))])
.expect("prepared query executes");
}

// ── db.prepare() surfaces the same PRS codes as db.execute() ────────────────

fn assert_prepare_code(input: &str, expected_code: &str) {
Expand Down
Loading
Loading