macrame/util/limits.rs
1//! Ceilings imposed by the engine rather than chosen by this crate.
2//!
3//! The distinction matters and is the reason this module is separate from the
4//! tuning constants in [`crate::connection::chunk_rows`]. Those are *choices* —
5//! measured, revisable, and traded against latency. What is here is a limit
6//! SQLite imposes, which no amount of measurement will move.
7
8/// How many ids go into one `IN (…)` list when hydrating attributes (T3.1).
9///
10/// **Not a latency budget.** These are reads, and [`crate::CHUNK_BUDGET`] bounds
11/// how long the *writer* holds the lock. This is a bind-variable ceiling:
12/// `SQLITE_MAX_VARIABLE_NUMBER` is 999 on a stock build, and hydrating a
13/// budget-sized subgraph in one statement would otherwise fail at the driver
14/// with an error that says nothing about node count.
15///
16/// 400 leaves room for the other bound parameters a hydrate query carries
17/// (timestamps, mode discriminators) without arithmetic at every call site that
18/// would have to be re-checked whenever one of those queries gained a parameter.
19///
20/// # Why this lives in `util` (T3.1)
21///
22/// It was defined twice — in `graph::subgraph` and in `temporal::as_of` — both
23/// `400`, with the reasoning written out at one of them and the other carrying
24/// `// See as_of::HYDRATE_CHUNK`. That is a working arrangement right up until
25/// someone tunes one of them, at which point two constants that must be equal
26/// silently are not, and the symptom is a driver error on one code path and not
27/// the other. The cross-reference comment is evidence the duplication was known
28/// and was being managed by convention; conventions are what a shared constant
29/// replaces.
30pub const HYDRATE_CHUNK: usize = 400;
31
32/// The ceiling [`HYDRATE_CHUNK`] exists to stay under, on a stock SQLite build.
33pub const SQLITE_MAX_VARIABLE_NUMBER: usize = 999;
34
35/// A **compile-time** check that the chunk leaves room under the ceiling.
36///
37/// A `#[test]` was the first form and clippy was right to object: both sides are
38/// constants, so the assertion has a constant value and belongs where it cannot
39/// be skipped. A const block fails the *build* rather than a test run, which
40/// matters because the failure mode it guards is someone tuning `HYDRATE_CHUNK`
41/// upward — plausibly in a release build, plausibly without running the suite.
42///
43/// The margin is doubled rather than exact, because the reason the value is 400
44/// and not 990 is that a hydrate query carries other bound parameters too. A
45/// query that gains one should not be the thing that discovers the ceiling.
46const _: () = assert!(
47 HYDRATE_CHUNK * 2 < SQLITE_MAX_VARIABLE_NUMBER,
48 "HYDRATE_CHUNK leaves no margin under the stock bind-variable ceiling"
49);