Struct QueryBudget 

pub struct QueryBudget {
    pub max_rows: u64,
    pub examined: Arc<AtomicU64>,
    pub cancel: CancellationToken,
    pub state: Arc<AtomicU8>,
    pub check_stride: u64,
}

Per-tool runtime budget. Constructed at the crate::query::executor::QueryExecutor boundary; threaded into crate::query::executor::graph_eval::GraphEvalContext so evaluate_all can sample-and-check it without re-reading env vars per call.

Clone is cheap: the inner counters are Arc-shared, so cloning across rayon workers is a refcount bump per field.

Fields

max_rows: u64

Maximum rows the executor may examine before tripping cancellation. 0 is rejected at construction sites (MCP boundary + env-var parse).

examined: Arc<AtomicU64>

How many rows have actually been examined. Shared across rayon worker threads; reset per evaluate_all call.

cancel: CancellationToken

Shared cancellation token (canonical type per 00_contracts.md §3.CC-1). Tripped when examined >= max_rows.

state: Arc<AtomicU8>

First-observer-wins source tag. Written exactly once by the first signal to cancel the shared token (either Self::tick on budget overflow or Self::mark_external_cancel).

check_stride: u64

How often (in rows) to compare examined against max_rows. Trades early-trip precision for fetch_add overhead.

Implementations

impl QueryBudget

pub fn new(max_rows: u64, cancel: CancellationToken) -> Self

Construct a fresh budget with max_rows and the documented DEFAULT_CHECK_STRIDE. The supplied token is the canonical per-request CancellationToken from Subagent A’s wrapper — tick() calls cancel() on it when the budget trips, so every clone of the token observes the cancellation through the same shared Arc<AtomicBool>.

pub fn unbounded(cancel: CancellationToken) -> Self

Construct an effectively-unbounded budget (u64::MAX rows) for back-compat callers that have not opted into per-tool budgeting yet. The cancellation token is still wired so external cancel signals propagate normally.

pub fn from_per_call_or_env( per_call_budget: Option<u64>, cancel: CancellationToken, ) -> Self

Resolve the effective budget for an MCP tool call.

Priority (per C_budget.md §2):

1. Per-call budget_rows MCP parameter (the caller can opt to a tighter or looser bound for diagnostics).
2. Environment-variable SQRY_TOOL_BUDGET_ROWS.
3. DEFAULT_BUDGET_ROWS.

0 is rejected at this boundary by mapping to the effectively-unbounded variant — a budget of zero would trip on the first row, which is never the operator intent. Negative env values are similarly mapped to the default.

pub fn exceeded(&self) -> bool

Returns true iff the budget has been exceeded. Cheap: one Relaxed load + comparison.

pub fn source(&self) -> CancellationSource

Reads the (possibly still None) cancellation source tag.

pub fn mark_external_cancel(&self) -> bool

Tag the source as External IFF it is still None. CAS, safe to call from any worker on observation. No-op if Budget already won the race. Returned bool indicates whether THIS call won the CAS (used in tests).

pub fn tick(&self) -> Result<(), BudgetExceeded>

Increment by 1. Returns Err(BudgetExceeded) the first time the post-increment count crosses max_rows. Idempotent on subsequent crosses (so multiple rayon workers racing past the threshold all see Err but the cancel-once contract holds via CancellationToken::cancel’s internal AtomicBool).

Source-tag invariant: the tag is set to Budget BEFORE cancel.cancel() is called. This ordering means any observer that subsequently reads cancel.is_cancelled() == true is guaranteed to see source() != None — the consumer side of the invariant lives in evaluate_all’s classify_cancel block.

Errors

Returns BudgetExceeded when the post-increment examined count meets or exceeds max_rows.

Trait Implementations

impl Clone for QueryBudget

fn clone(&self) -> QueryBudget

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for QueryBudget

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.