max_results limits derived facts, not results: merge into max_derived_facts (v3.0.0) #553

Problem

Two options limit recursive rule evaluation, and neither name says what it limits.

Both raise INT-020. Neither caps the rows a query returns, and no version ever did. But the name max_results, the v2.0.4 doc comment ("Maximum total query results") and the INT-020 message ("Max query results (N) exceeded") all say it does. #432 and #473 repeated that reading.

The per-iteration limit adds almost nothing. One iteration's new facts are part of the total, so with equal limits the total limit is reached first, or in the same iteration.

Change (v3.0.0 only)

1. One limit, max_derived_facts, on the total facts a rule query derives (base facts not counted). The per-iteration check is removed.
2. OpenOptions::max_results and :max-results become deprecated aliases of max_derived_facts and :max-derived-facts, with #[deprecated] on the Rust builder method and field. When both are given, the lower value applies.
3. The INT-020 message names derived facts, not query results. The code and its category are unchanged.
4. DEFAULT_MAX_RESULTS is folded into DEFAULT_MAX_DERIVED_FACTS (1,000,000).
5. The 1,000-iteration limit is unchanged.

Behaviour change, noted in CHANGELOG.md: a caller who lowered max_derived_facts to cap each iteration now caps the total. A long recursion whose iterations each stayed under the limit can now fail with INT-020.

Not in scope

• No v2.x backport. main keeps both options as they are.
• No row cap. :limit (No working result-limiting/pagination mechanism for plain (non-recursive) :find queries #306) is the way to bound returned rows.

Touches

• src/db.rs (OpenOptions), src/query/datalog/evaluator.rs, executor.rs, parser.rs (:max-results, :max-derived-facts), src/error.rs (message).
• Docs: docs/ERROR_REFERENCE.md (INT-020), CHANGELOG.md, the docs site (content/datalog-reference.md, with @since v3.0.0).
• minigraf-playground/lib/system-prompt.ts mentions :max-results.
• No binding exposes either option.

The #473 streaming engine's Recursive operator (#548) enforces the merged limit. Spec: docs/superpowers/specs/2026-10-11-streaming-engine-design.md §6.2.