quarb 0.64.0

//! The Quarb query engine.
//!
//! Quarb is a query language for *arbors* — tree-spanned graphs. This
//! crate is the engine: it lexes and parses a query, then evaluates
//! it against an [`AstAdapter`] that maps some data source onto the
//! arbor model.
//!
//! It currently implements tree navigation in full (child, descendant,
//! parent, ancestor, and sibling hops; proximal/distal reach; root and
//! leaf anchors; literal, glob, and `~(...)` regex name matching;
//! `<trait>` filters), scalar projection (`::` properties, `:` core
//! metadata, `:::` adapter metadata), `[...]` predicates (comparisons,
//! `and`/`or`/`not`/`!`, structural conditions, index selection),
//! `||` union, `->` / `<-` crosslink navigation, `~` / `~~` the navop
//! star over every edge touching a node, path patterns
//! (`(...)` groups with subpath alternation and `+`/`*`/`{m,n}`
//! quantifiers — expansion under the adapter's
//! [quantifier bound](AstAdapter::quantifier_bound) and
//! [frontier bound](AstAdapter::frontier_bound)), and the register
//! system: per-capsa `| f` transforms, `@| f` whole-context
//! aggregation, `| .` push and `| $.` recall of breadcrumbs, and
//! `| .(expr)` subcontexts for grouped aggregation. It also does
//! correlation: `E1 <=> E2[…$$0…]` joins two contexts, a predicate
//! referencing the driver as `$$0` and a prior expression's bound
//! node as `$$N`. It also
//! resolves cross-references: `::prop-->` maps a reference to its
//! target node (a JSON adapter follows a `$ref` JSON Pointer), the
//! reverse resolution `<--` (who refers here) and the value match
//! `=>`. See `doc/impl.tex`.
//!
//! ```
//! # use quarb::{AstAdapter, NodeId, QueryResult, run};
//! # struct Empty;
//! # impl AstAdapter for Empty {
//! #     fn root(&self) -> NodeId { NodeId(0) }
//! #     fn children(&self, _: NodeId) -> Vec<NodeId> { vec![] }
//! #     fn name(&self, _: NodeId) -> Option<String> { None }
//! # }
//! let hits = run("//*.rs", &Empty).unwrap();
//! assert!(matches!(hits, QueryResult::Nodes(ns) if ns.is_empty()));
//! ```

pub mod diagnostic;
pub mod error;
mod graph;
mod pipeline;
pub mod rich;
mod stdlib;
mod syntax;
pub use graph::reflect::QueryArbor;
pub use syntax::expand::Form;
pub use value::QUARQ_TEXT_FIELD;
mod thread;
mod value;
// The public module paths, as they were before the layering.
pub use graph::complete;
pub use graph::edges::GraphDeclaration;
pub use graph::host::{QueryResult, Traced, resolved_provenance};
pub use graph::identity::{canonical_identity, canonical_identity_at_open, is_url, name_path};
pub use graph::run::{Run, inherited};
pub use graph::tabula::{Scientific, table_node_records, table_rows_of};
pub use graph::{
    adapter, autounits, conformance, koine, names, plan, reflect, rooted, source, target, trace,
};
#[cfg(feature = "kaiv")]
pub use pipeline::kaiv_out;
pub use pipeline::{PrettyMode, SessionMemory, SessionStore, session_memory};
pub use pipeline::{env, library};
pub use quarb_time::{calendar, calnames, datenames, durnames, regional};
/// The temporal fragment (the `quarb-time` crate, at its old paths).
pub use quarb_time::{period, temporal, timex};
pub use stdlib::pretty_value;
pub use stdlib::{pretty_precision, tabulate, tabulate_in, tabulate_pretty, tabulate_with};
use syntax::{ast, lexer, parser, unparse};
pub use syntax::{highlight, man, registry};
pub use thread::prov::{ORIGIN_CAP, Origin, Origins, Prov};
pub use value::encoding::{base64, base64_decode, sha256, sha256_hex};
pub use value::pretty_float;
pub use value::split_seconds_pub;
pub use value::table::{TABLE_CSS, table_cells, table_columns, table_html, table_html_plain};
pub use value::{bibref, encoding, locale, number, quantity, table, translit};

pub use diagnostic::{Diagnostic, Severity};
pub use error::{Kind as ErrorKind, QuarbError, Result};
pub use graph::adapter::{
    Ask, AstAdapter, Cap, Catalog, CatalogLookup, Cmp, Confidence, Conjunct, Estimate, ExternalRef,
    InstantFrom, Latency, LinkDir, NodeId, PlanAxis, Provenance, ProvenanceList, Selection,
    StepPlan, Surface, Unopened, item_index, item_name,
};

pub use pipeline::env::{EnvKind, Environment};
pub use pipeline::library::CommandLibrary;
pub use syntax::parser::{Defs, parse_scope_path, parse_value_expr};
/// The invocation instant, pinned once by the tool layer (`qua
/// --now`, or the clock read once at startup) and read by
/// adapters that would otherwise consult the wall clock when
/// resolving a relative window (`since=30m`). A pinned run
/// replays: evaluation never reads a clock, and neither does a
/// mount. `None` before the tool sets it — a library embedder
/// that never pins gets the old wall-clock behavior.
pub use value::ambient::{
    SentenceBonds, fetched, fetched_opt, invocation_instant, now_secs, raise_at_mount,
    record_refusal, record_warning, retract_diagnostics, sentence_bonds, set_invocation_instant,
    set_sentence_bonds, take_at_mount, take_refusal_diagnostic,
};
pub use value::{
    ColumnType, Foreign, ForeignValue, NodeRef, Table, TableBuilder, Typing, Value,
    offset_spelling, offset_word,
};

/// The universal search over a step body: `*//BODY`, with the
/// wildcard supplied when the body opens with a trait expression or
/// a predicate (`trait <long-text>: [:: | cc > 300];` means every
/// node that passes).
pub fn step_body_query(body: &str) -> String {
    let body = body.trim();
    if body.starts_with(['<', '[']) {
        format!("*//*{body}")
    } else {
        format!("*//{body}")
    }
}

/// One path step's body, parsed — a name, a pattern, an
/// alternation, a trait expression, predicates, in any combination,
/// without the navigation operator — as a model's `trait <name>:
/// BODY;` declaration takes it. Test a node against it with
/// [`node_matches_step_body`]: decided at the node, no walk.
pub struct StepBody(ast::PathElem);

/// Parse `body` as one step's body; refuses anything beyond that
/// single step, and positional predicates (`[1]`, `[2..3]`), which
/// have no meaning at a single node.
pub fn parse_step_body(body: &str) -> Result<StepBody> {
    let q = parser::parse(&lexer::lex(&step_body_query(body))?)?;
    let refuse = |what: &str| {
        Err(QuarbError::parse(format!(
            "a trait declaration takes one step's body (a name, a pattern, \
             a trait expression, predicates), not {what}: '{body}'"
        )))
    };
    if !q.correlations.is_empty() || !q.pipeline.is_empty() {
        return refuse("a pipeline");
    }
    if q.branches.len() != 1 || q.branches[0].projection.is_some() {
        return refuse("a projection or a union");
    }
    if q.branches[0].steps.len() != 1 {
        return refuse("a path");
    }
    let elem = q
        .branches
        .into_iter()
        .next()
        .unwrap()
        .steps
        .into_iter()
        .next()
        .unwrap();
    let preds = match &elem {
        ast::PathElem::Step(s) => &s.predicates,
        ast::PathElem::Group(g) => &g.predicates,
        _ => return refuse("that"),
    };
    if preds.iter().any(|p| {
        matches!(
            p,
            ast::Predicate::Index(_)
                | ast::Predicate::Range(_, _)
                | ast::Predicate::Positions(_)
                | ast::Predicate::Computed(_)
        )
    }) {
        return refuse("a positional predicate");
    }
    Ok(StepBody(elem))
}

/// Check that `body` parses as one step's body (see
/// [`parse_step_body`]).
pub fn validate_step_body(body: &str) -> Result<()> {
    parse_step_body(body).map(|_| ())
}

/// Whether `node` would match the step body as a step of a path:
/// decided at the node, the predicates evaluated there, no hop.
pub fn node_matches_step_body(adapter: &impl AstAdapter, node: NodeId, body: &StepBody) -> bool {
    graph::steps::node_matches_elem(adapter, node, &body.0)
}

/// Convert a refusal recorded during evaluation into an error. The
/// eval layer below the entry points has no error channel; a walk
/// that would return a silently incomplete answer (e.g. a
/// quantifier cut off at the bound) records a refusal instead, and
/// the entry points surface it here.
/// A value expression parsed once, evaluated at nodes
/// ([`node_value`]): what a model's `property` statement holds.
#[derive(Debug, Clone)]
pub struct ValueExpr(ast::Operand);

impl ValueExpr {
    /// Parse the text right of `=` (see [`parse_value_expr`]).
    pub fn parse(text: &str) -> Result<ValueExpr> {
        parse_value_expr(text).map(ValueExpr)
    }
}

/// The values of `expr` at `node` — the thread standing on the node,
/// `::prop` its properties, no register, no topic — as a predicate's
/// operands are evaluated at a candidate (ruling 2026-11-08, the
/// property statement; the sibling of [`node_matches_step_body`]).
/// Several values for an operand that yields several; none for a
/// null one.
pub fn node_value(adapter: &impl AstAdapter, node: NodeId, expr: &ValueExpr) -> Vec<Value> {
    let ext = graph::navigate::GraphExt::at(node);
    let trace = graph::correlate::Correlation::default();
    let scope = pipeline::Scope::at(&ext);
    pipeline::operand::eval_operand(adapter, &ext, &expr.0, &trace, scope)
}

/// A scope of child steps, as a model's `property` statement names
/// the nodes a declaration covers: `/legs/*`, `/flights/*[::carrier
/// = "JP"]`. Each step is matched against the node's ancestor chain
/// ([`node_in_scope`]); a descendant axis, a group or any other
/// element is refused, since membership is read per node, never by
/// a walk.
#[derive(Debug, Clone)]
pub struct ScopeSteps(Vec<ast::PathElem>);

impl ScopeSteps {
    pub fn parse(text: &str) -> Result<ScopeSteps> {
        let path = parse_scope_path(text)?;
        for elem in &path.0 {
            match elem {
                ast::PathElem::Step(s) if matches!(s.axis, ast::Axis::Child) => {}
                ast::PathElem::Step(_) => {
                    return Err(QuarbError::parse(format!(
                        "a property's scope is a path of child steps ('/legs/*', \
                         '/flights/*[::carrier = \"JP\"]'); a descendant axis walks, and \
                         membership is read at the node: '{text}'"
                    )));
                }
                _ => {
                    return Err(QuarbError::parse(format!(
                        "a property's scope is a path of child steps, not a group or a \
                         pattern: '{text}'"
                    )));
                }
            }
        }
        Ok(ScopeSteps(path.0))
    }

    /// How deep the scope's nodes stand under the root.
    pub fn depth(&self) -> usize {
        self.0.len()
    }

    /// Whether every step is a bare name or a star — membership then
    /// costs a name test per ancestor and needs no memo.
    pub fn plain(&self) -> bool {
        self.0.iter().all(|e| match e {
            ast::PathElem::Step(s) => {
                s.predicates.is_empty() && s.traits.is_empty() && s.labels.is_empty()
            }
            _ => false,
        })
    }

    /// The scope as query text.
    pub fn text(&self) -> String {
        self.0.iter().map(unparse::elem).collect()
    }
}

/// Whether `node` stands in the scope: its ancestors from the root
/// down match the scope's steps one for one, the node the last.
pub fn node_in_scope(adapter: &impl AstAdapter, node: NodeId, scope: &ScopeSteps) -> bool {
    let root = adapter.root();
    let mut chain = Vec::with_capacity(scope.0.len() + 1);
    let mut cur = Some(node);
    while let Some(n) = cur {
        if n == root {
            break;
        }
        chain.push(n);
        if chain.len() > scope.0.len() {
            return false;
        }
        cur = adapter.parent(n);
    }
    if cur.is_none() || chain.len() != scope.0.len() {
        return false;
    }
    chain.reverse();
    chain
        .iter()
        .zip(scope.0.iter())
        .all(|(n, elem)| graph::steps::node_matches_elem(adapter, *n, elem))
}

/// A value cast to a column type as a declared column casts its
/// cells (`<int>`, `<_km>`, `<instant>`): `None` where it does not
/// cast.
pub fn cast_value(v: &Value, t: &ColumnType) -> Option<Value> {
    value::cast_cell(v, t)
}

fn checked<T>(result: T) -> Result<T> {
    match value::ambient::take_refusal_diagnostic() {
        Some(d) => Err(QuarbError::refused(d.message)
            .with_code(d.code)
            .with_site(d.site)),
        None => Ok(result),
    }
}

/// The options a [`run`]-family entry runs under: the enclosing
/// run's when one is in progress (an adapter answering through the
/// engine mid-evaluation keeps its caller's instant, bound, gate
/// and targets), the ambient ones at the top.

/// A query's closing serialization for people — `@| csv` or
/// `@| pretty` as the last command — taken off for the tool to render.
#[derive(Debug, Clone)]
pub struct ClosingTable {
    pub csv: bool,
    /// The named columns, in order; empty for every field.
    pub columns: Vec<String>,
    /// The delimiter `csv(";")` names, when it names one.
    pub delimiter: Option<u8>,
    /// `@| pretty`: the digits after the point a float is drawn with
    /// (spec: Output Commands, draft 166), `-p=n`; `None` under
    /// `table` and `csv`, which keep every digit.
    pub pretty: Option<usize>,
}

/// What a run leaves for its caller.
#[derive(Debug, Clone)]
pub struct Outcome {
    /// A node set, or scalar values if the query ends in a
    /// projection.
    pub result: QueryResult,
    /// The closing `@| csv` / `@| pretty` taken off for rendering
    /// ([`Query::for_rendering`]), with the rows standing in
    /// `result` as they were before it.
    pub closing: Option<ClosingTable>,
    /// The unresolved external references: the identifiers of
    /// documents the query referenced but could not reach (not
    /// mounted, no tree declared for them).
    pub refs: Vec<String>,
    /// The static plan the run was made under, when the run asked
    /// for it (`Run::plan`) or held it to a budget.
    pub plan: Option<plan::Plan>,
    /// The HTML form of the drawing the query closed in (`@| tree`,
    /// `@| histogram`), beside the text in `result`: a browser host
    /// renders it where the terminal prints the text
    /// ([`closes_with_drawing`]); dressed with [`TABLE_CSS`].
    pub html: Option<String>,
    /// The warnings and infos the run raised, in raising order
    /// (spec: Diagnostics): they accompany the answer, where an
    /// error withholds it ([`QuarbError::diagnostic`]). A host shows
    /// them down to its level and never merges them with another
    /// query's.
    pub diagnostics: Vec<Diagnostic>,
}

/// A parsed query, ready to run against an adapter under a
/// [`Run`]: parse once, run many.
#[derive(Debug, Clone)]
pub struct Query {
    ast: ast::Query,
    closing: Option<ClosingTable>,
}

/// Whether `text` is a query whose closing command is `@| pretty` —
/// the browser hosts' rule: such a result renders as the HTML grid
/// ([`table_html`]), everything else stays text. A query that does
/// not parse closes with nothing.
pub fn closes_with_table(text: &str) -> bool {
    lexer::lex(text)
        .and_then(|tokens| parser::parse(&tokens))
        .ok()
        .and_then(|q| match q.pipeline.last() {
            Some(ast::Command::Agg(call)) => Some(matches!(call.name.as_str(), "table" | "pretty")),
            _ => None,
        })
        .unwrap_or(false)
}

/// Whether `text` is a query whose closing command is a drawing —
/// `@| tree` or `@| histogram` — whose run leaves an HTML form in
/// [`Outcome::html`] beside the text: the browser hosts render
/// that form, as they render the grid of a query closing in
/// `@| pretty`. A query that does not parse closes with nothing.
pub fn closes_with_drawing(text: &str) -> bool {
    lexer::lex(text)
        .and_then(|tokens| parser::parse(&tokens))
        .ok()
        .and_then(|q| match q.pipeline.last() {
            Some(ast::Command::Agg(call)) => {
                Some(matches!(call.name.as_str(), "tree" | "histogram"))
            }
            _ => None,
        })
        .unwrap_or(false)
}

/// One previous-line form found in a line: where its designator
/// stands (the `_` or the `-N` after the sigil, the part a label
/// replaces), how many labelled lines back it names, and the form
/// as written, for a refusal.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PreviousLine {
    /// Character offset of the designator.
    pub start: usize,
    /// Character offset past the designator.
    pub end: usize,
    /// 1 for `&_` and `&-1`, N for `&-N`.
    pub back: usize,
    /// The form as written: `&_`, `&-2`, `(=_)`, `(=-2)`.
    pub written: String,
}

/// The previous-line forms of a line, in order (ruling 2026-11-11):
/// `&_`, the line before this one, and `&-N`, the line N back, with
/// their rounded twins `(=_)` and `(=-N)`. They are the interactive
/// hosts' forms, as `&N` is: a host resolves them to a label before
/// the engine parses anything ([`resolve_previous_line`]), and a
/// `.quai` file does not carry them. Only `&_` and `&-N` followed
/// by something that cannot continue a name are the forms (`&_x`,
/// `&-2x` stay what they were), and only where the sigil is the
/// query's own token, never inside a text or a comment. A line
/// that does not lex holds none: the engine says why.
pub fn previous_line_forms(line: &str) -> Vec<PreviousLine> {
    let Ok((tokens, spans)) = lexer::lex_spanned(line) else {
        return Vec::new();
    };
    let chars: Vec<char> = line.chars().collect();
    let at = |j: usize| chars.get(j).copied();
    // the designator at `from`: its end and how far back it names
    let designator = |from: usize| -> Option<(usize, usize)> {
        match at(from)? {
            '_' => Some((from + 1, 1)),
            '-' => {
                let mut end = from + 1;
                while at(end).is_some_and(|c| c.is_ascii_digit()) {
                    end += 1;
                }
                let digits: String = chars[from + 1..end].iter().collect();
                digits.parse::<usize>().ok().map(|back| (end, back))
            }
            _ => None,
        }
    };
    let mut out = Vec::new();
    for (token, &(start, _)) in tokens.iter().zip(&spans) {
        if !matches!(token, lexer::Token::Amp) {
            continue;
        }
        // the sigil, or the rounded spelling `(=…)` it lexes from
        let (from, rounded) = match (at(start), at(start + 1)) {
            (Some('&'), _) => (start + 1, false),
            (Some('('), Some('=')) => (start + 2, true),
            _ => continue,
        };
        let Some((end, back)) = designator(from) else {
            continue;
        };
        let (closes, last) = if rounded {
            // `(=_)`, and `(=_!)` with the live marker
            let close = if at(end) == Some('!') { end + 1 } else { end };
            (at(close) == Some(')'), close + 1)
        } else {
            (
                !at(end).is_some_and(|c| lexer::is_name_char(c) || c == '('),
                end,
            )
        };
        if closes {
            out.push(PreviousLine {
                start: from,
                end,
                back,
                written: chars[start..last.min(chars.len())].iter().collect(),
            });
        }
    }
    out
}

/// `line` with its previous-line forms rewritten to the labels they
/// name. `label` answers the label of the line `back` lines back
/// among the session's labelled lines (1 the latest), `None` where
/// there is none; `count` is how many labelled lines there are. A
/// suffix (`&_#`, `&_!`) and a pipe tail stay as written, so the
/// resolved line is read as the `&N` line it now is. `Ok(None)`
/// when the line holds no such form; `Err` when one reaches before
/// the first line.
pub fn resolve_previous_line_with(
    line: &str,
    count: usize,
    label: impl Fn(usize) -> Option<usize>,
) -> std::result::Result<Option<String>, String> {
    let forms = previous_line_forms(line);
    if forms.is_empty() {
        return Ok(None);
    }
    let chars: Vec<char> = line.chars().collect();
    let mut out = String::new();
    let mut at = 0;
    for form in &forms {
        let written = &form.written;
        if form.back == 0 {
            return Err(format!(
                "'{written}' names this line itself: the line before this one is '&_' (or '&-1')"
            ));
        }
        if count == 0 {
            return Err(format!("'{written}': no line before this one"));
        }
        let Some(label) = label(form.back) else {
            return Err(format!(
                "'{written}': no line {} back ({count} ran before this one)",
                form.back
            ));
        };
        out.extend(&chars[at..form.start]);
        out.push_str(&label.to_string());
        at = form.end;
    }
    out.extend(&chars[at..]);
    Ok(Some(out))
}

/// [`resolve_previous_line_with`] for a session whose labels are
/// the numbers 1 to `last` (quai, the wasm session): `&_` is
/// `&{last}`, `&-2` the one before it.
pub fn resolve_previous_line(
    line: &str,
    last: usize,
) -> std::result::Result<Option<String>, String> {
    resolve_previous_line_with(line, last, |back| (back <= last).then(|| last + 1 - back))
}

/// What a notebook file or cell answers a previous-line form with:
/// "the previous cell" breaks in silence when cells are reordered,
/// so a file names its cell.
pub fn previous_line_in_a_file(line: &str) -> Option<String> {
    let form = previous_line_forms(line).into_iter().next()?;
    Some(format!(
        "'{}' is the interactive form of a session: a notebook names its cell ('&N')",
        form.written
    ))
}

impl Query {
    /// Lex and parse `text` with the dataset at hand (data-aware
    /// macros read it at expansion time), under the ambient options.
    pub fn parse(text: &str, adapter: &impl AstAdapter) -> Result<Query> {
        Query::parse_with(text, &Defs::default(), adapter, &inherited())
    }

    /// [`Query::parse`] with a pre-seeded fragment table and the
    /// options a macro body expands under (its shell gate, its
    /// instant).
    pub fn parse_with(
        text: &str,
        defs: &Defs,
        adapter: &impl AstAdapter,
        run: &Run,
    ) -> Result<Query> {
        let _scope = graph::run::enter(Some(run.clone()));
        let (tokens, spans) = lexer::lex_spanned(text)?;
        let ast = parser::with_head_topic(run.topic.is_some(), || {
            parser::parse_with_data_spanned(
                &tokens,
                Some(&spans),
                defs.clone(),
                &graph::reflect::Reflector::new(Some(adapter)),
            )
        })?;
        Ok(Query { ast, closing: None })
    }

    /// For a tool that renders under an output locale: when the
    /// query closes with `@| csv` or `@| pretty`, the run returns the
    /// rows as they stand before that command, with its shape in
    /// [`Outcome::closing`], and the tool tabulates them itself
    /// (`tabulate_in` with its locale's cells and delimiter). The
    /// command anywhere else, and every other command, yields the same
    /// values as under a plain run — a value never depends on a
    /// locale.
    pub fn for_rendering(mut self) -> Query {
        if let Some(ast::Command::Agg(call)) = self.ast.pipeline.last_mut()
            && matches!(call.name.as_str(), "csv" | "table" | "pretty")
        {
            let (delimiter, columns) = stdlib::split_csv_delimiter(call);
            self.closing = Some(ClosingTable {
                csv: call.name == "csv",
                columns: columns
                    .iter()
                    .filter_map(|a| match a {
                        ast::Arg::Lit(Value::Str(s)) => Some(s.clone()),
                        _ => None,
                    })
                    .collect(),
                delimiter,
                pretty: (call.name == "pretty").then(|| stdlib::pretty_precision(call)),
            });
            // The rows, with a node standing for the record of the
            // columns asked of it, exactly as the command would read
            // them.
            let columns: Vec<ast::Arg> = columns.to_vec();
            call.name = stdlib::ROWS_FOR_RENDERING.to_string();
            call.args = columns;
        }
        self
    }

    /// For a host that draws the table itself (the HTML grid of the
    /// browser hosts): when the query closes with `@| pretty`, the
    /// closing command is taken off entirely, its shape kept in
    /// [`Outcome::closing`], and the run yields what stands before
    /// it — a node set when the query selected nodes (a document's
    /// own table, say), values when it projected them. Unlike
    /// [`for_rendering`](Self::for_rendering), no stand-in command
    /// turns the nodes into their names; [`table_rows_of`] reads
    /// them into rows. A query closing with `@| csv`, or with any
    /// other command, runs as it stands.
    pub fn without_closing(mut self) -> Query {
        if let Some(ast::Command::Agg(call)) = self.ast.pipeline.last()
            && matches!(call.name.as_str(), "table" | "pretty")
        {
            let (delimiter, columns) = stdlib::split_csv_delimiter(call);
            self.closing = Some(ClosingTable {
                csv: false,
                columns: columns
                    .iter()
                    .filter_map(|a| match a {
                        ast::Arg::Lit(Value::Str(s)) => Some(s.clone()),
                        _ => None,
                    })
                    .collect(),
                delimiter,
                pretty: (call.name == "pretty").then(|| stdlib::pretty_precision(call)),
            });
            self.ast.pipeline.pop();
        }
        self
    }

    /// Evaluate against `adapter` under `run`.
    ///
    /// Errors: a refusal (a feature the engine does not implement, a
    /// shell command with the gate closed, an argument of the wrong
    /// kind); a malformed query is refused at [`Query::parse`].
    pub fn run(&self, adapter: &impl AstAdapter, run: &Run) -> Result<Outcome> {
        pipeline::gate(&self.ast, &run.options())?;
        let plan = self.planned(adapter, run)?;
        let result = checked(graph::host::eval_with(
            &self.ast,
            adapter,
            Some(run.clone()),
        ))?;
        // the source dropped whole nodes for the caller: the omission
        // warning, once (spec: omitted data)
        if adapter.nodes_withheld() {
            value::ambient::record_omitted_nodes();
        }
        Ok(Outcome {
            result,
            closing: self.closing.clone(),
            refs: pipeline::take_refs(),
            plan,
            html: pipeline::take_drawing_html(),
            diagnostics: value::ambient::take_diagnostics(),
        })
    }

    /// The static plan when the run asks for it, held to the run's
    /// budget: a query the estimate puts beyond the budget is
    /// refused here, before anything runs.
    /// Run at the calculator: no arbor, the run's topic on the head,
    /// every thread standing nowhere. The result is always values.
    pub fn run_calc(&self, run: &Run) -> Result<Outcome> {
        pipeline::gate(&self.ast, &run.options())?;
        let values = checked(graph::host::eval_calc(&self.ast, Some(run.clone())))?;
        Ok(Outcome {
            result: QueryResult::Values(values),
            closing: self.closing.clone(),
            refs: pipeline::take_refs(),
            plan: None,
            html: pipeline::take_drawing_html(),
            diagnostics: value::ambient::take_diagnostics(),
        })
    }

    /// The calculator's traced run: every value with its provenance.
    pub fn run_traced_prov_calc(&self, run: &Run) -> Result<Vec<Traced>> {
        pipeline::gate(&self.ast, &run.options())?;
        checked(graph::host::eval_calc_traced(&self.ast, Some(run.clone())))
    }

    fn planned(&self, adapter: &impl AstAdapter, run: &Run) -> Result<Option<plan::Plan>> {
        if !run.plan && run.budget.is_none() {
            return Ok(None);
        }
        let plan = match &run.budget {
            Some(budget) => plan::of_within(&self.ast, adapter, budget.cap()),
            None => plan::of(&self.ast, adapter),
        };
        if let Some(budget) = &run.budget
            && let Some(why) = budget.exceeded_by(&plan)
        {
            return Err(QuarbError::refused(why));
        }
        Ok(Some(plan))
    }

    /// Like [`Query::run`], returning the final capsae as `(node,
    /// topic)` pairs, so each result value still knows which node
    /// produced it — the provenance-bearing form used by typed
    /// emission (`qua --daiv`). A `None` topic is a node result.
    pub fn run_traced(
        &self,
        adapter: &impl AstAdapter,
        run: &Run,
    ) -> Result<Vec<(NodeId, Option<Value>)>> {
        Ok(self
            .run_traced_prov(adapter, run)?
            .into_iter()
            .map(|t| (t.node, t.topic))
            .collect())
    }

    /// Like [`Query::run_traced`], with each value's provenance: the
    /// origins of its topic, per field for a record
    /// ([`graph::host::Traced`]).
    pub fn run_traced_prov(&self, adapter: &impl AstAdapter, run: &Run) -> Result<Vec<Traced>> {
        pipeline::gate(&self.ast, &run.options())?;
        checked(graph::host::eval_traced_prov_with(
            &self.ast,
            adapter,
            Some(run.clone()),
        ))
    }

    /// The static plan: what the query will touch, step by step,
    /// with what `adapter` says it would apply from its catalog —
    /// no node is read ([`plan::of`]).
    pub fn plan(&self, adapter: &dyn AstAdapter) -> plan::Plan {
        plan::of(&self.ast, adapter)
    }

    /// The static plan priced under `budget`: every estimator may
    /// stop at the first entry past it ([`Cap`]), so a listing of
    /// a hundred thousand files costs a thousand reads under
    /// `rows=1000`.
    pub fn plan_within(&self, adapter: &dyn AstAdapter, budget: &plan::Budget) -> plan::Plan {
        plan::of_within(&self.ast, adapter, budget.cap())
    }

    /// The query rendered back to canonical text (defs expanded).
    pub fn canonical(&self) -> String {
        unparse::unparse(&self.ast)
    }

    /// The syntax tree.
    pub fn ast(&self) -> &ast::Query {
        &self.ast
    }
}

/// Lex, parse, and evaluate `query` against `adapter` under the
/// ambient options ([`Run::ambient`]; inside a run, that run's).
///
/// Returns the [`QueryResult`] — a node set, or scalar values if the
/// query ends in a projection — or an error if the query is malformed
/// or uses a feature the engine does not implement yet. A tool
/// choosing its options runs a [`Query`] under a [`Run`].
pub fn run(query: &str, adapter: &impl AstAdapter) -> Result<QueryResult> {
    run_with_defs(query, &Defs::default(), adapter)
}

/// Like [`run`], for a tool that renders under an output locale
/// ([`Query::for_rendering`]).
pub fn run_for_rendering(
    query: &str,
    adapter: &impl AstAdapter,
) -> Result<(QueryResult, Option<ClosingTable>)> {
    let r = inherited();
    let out = Query::parse_with(query, &Defs::default(), adapter, &r)?
        .for_rendering()
        .run(adapter, &r)?;
    Ok((out.result, out.closing))
}

/// Like [`run`], returning `(node, topic)` pairs
/// ([`Query::run_traced`]).
pub fn run_traced(query: &str, adapter: &impl AstAdapter) -> Result<Vec<(NodeId, Option<Value>)>> {
    run_traced_with_defs(query, &Defs::default(), adapter)
}

/// Like [`run_traced`], with each value's provenance
/// ([`Query::run_traced_prov`]).
pub fn run_traced_prov(query: &str, adapter: &impl AstAdapter) -> Result<Vec<graph::host::Traced>> {
    run_traced_prov_with_defs(query, &Defs::default(), adapter)
}

/// Parse a definitions file — `def &name(params): body;` statements
/// only — into a fragment table for [`run_with_defs`]. Lines whose
/// first non-blank character is `#` are comments: a defs file is a
/// library, and a library wants a header. The block comment
/// `(!! … )` stands anywhere in it as in query text (ruling
/// 2026-11-06); the lexer reads it as whitespace.
pub fn parse_defs(text: &str) -> Result<Defs> {
    let tokens = lexer::lex(&strip_defs_comments(text))?;
    parser::parse_defs(&tokens)
}

/// Whether `text` is definitions and nothing else (`#` comments
/// allowed): `Ok(false)` when a query follows the definitions, an
/// error when a definition itself is malformed.
pub fn defs_only(text: &str) -> Result<bool> {
    let tokens = lexer::lex(&strip_defs_comments(text))?;
    parser::defs_only(&tokens)
}

/// Blank out the `#` comment lines of a defs file, preserving line
/// structure. Session layers that *prepend defs text to query text*
/// (quai, the notebook kernels) must store the stripped form — the
/// query lexer itself has no comment syntax.
pub fn strip_defs_comments(text: &str) -> String {
    text.lines()
        .map(|l| {
            if l.trim_start().starts_with('#') {
                ""
            } else {
                l
            }
        })
        .collect::<Vec<_>>()
        .join("\n")
}

/// Like [`run`], with a pre-seeded fragment table (a `--defs` file);
/// inline `def` statements extend it.
pub fn run_with_defs(query: &str, defs: &Defs, adapter: &impl AstAdapter) -> Result<QueryResult> {
    let r = inherited();
    Ok(Query::parse_with(query, defs, adapter, &r)?
        .run(adapter, &r)?
        .result)
}

/// Like [`run_traced`], with a pre-seeded fragment table.
pub fn run_traced_with_defs(
    query: &str,
    defs: &Defs,
    adapter: &impl AstAdapter,
) -> Result<Vec<(NodeId, Option<Value>)>> {
    let r = inherited();
    Query::parse_with(query, defs, adapter, &r)?.run_traced(adapter, &r)
}

/// Like [`run_traced_prov`], with a pre-seeded fragment table.
pub fn run_traced_prov_with_defs(
    query: &str,
    defs: &Defs,
    adapter: &impl AstAdapter,
) -> Result<Vec<graph::host::Traced>> {
    let r = inherited();
    Query::parse_with(query, defs, adapter, &r)?.run_traced_prov(adapter, &r)
}

/// True if `query` (inline defs allowed) opens with an expression
/// head or a lone root anchor and never navigates a document: every
/// branch is a step-less, projection-less root anchor and there are
/// no correlations. Such a query can run against a bare root with
/// no mounted target — the calculator invocation (spec: The
/// Expression Head). Unparseable text answers `false`; the caller's
/// normal run path owns the error message.
/// The first operand of a calculator query that reads a document —
/// a path from the root or a mark (`= (/rows/*::x)`), which a bare
/// root answers with nothing — in its written form, or `None` when
/// the query computes from its literals alone. The calculator
/// command `qc` refuses such a query by name, pointing at `qua`.
pub fn calculator_reads(query: &str) -> Option<String> {
    let tokens = lexer::lex(query).ok()?;
    let ast = parser::parse_with_defs(&tokens, Defs::default()).ok()?;
    struct Reads(Option<String>);
    impl ast::visit::Visitor for Reads {
        fn operand(&mut self, o: &ast::Operand) {
            if self.0.is_none()
                && let ast::Operand::Rel { steps, .. } = o
                && !steps.is_empty()
            {
                self.0 = Some(unparse::operand(o));
            }
            ast::visit::walk_operand(self, o);
        }
    }
    let mut v = Reads(None);
    ast::visit::walk_query(&mut v, &ast);
    v.0
}

pub fn is_calculator(query: &str) -> bool {
    let Ok(tokens) = lexer::lex(query) else {
        return false;
    };
    let Ok(ast) = parser::parse_with_defs(&tokens, Defs::default()) else {
        return false;
    };
    ast.correlations.is_empty()
        && !ast.branches.is_empty()
        && ast.branches.iter().all(|b| {
            matches!(b.anchor, ast::Anchor::Root) && b.steps.is_empty() && b.projection.is_none()
        })
}

/// Parse `query` (expanding defs) and render it back to canonical
/// query text — the expansion lens (`qua --expand`). Pure fragments
/// only: a data-aware macro (`&name!`) needs [`expand_with`].
pub fn expand(query: &str, defs: &Defs) -> Result<String> {
    let tokens = lexer::lex(query)?;
    let ast = parser::parse_with_defs(&tokens, defs.clone())?;
    Ok(unparse::unparse(&ast))
}

/// The `macroexpand-1` lens (`qua --expand-1`): parse fully, but
/// return each directly-invoked macro's generated text before its
/// re-expansion — one entry per direct invocation, in source
/// order. Run the printed text again to take the next step;
/// [`expand`] is the fixed point.
pub fn expand_first(query: &str, defs: &Defs) -> Result<Vec<String>> {
    let tokens = lexer::lex(query)?;
    parser::parse_first_steps(&tokens, defs.clone(), &graph::reflect::Reflector::new(None))
}

/// Like [`expand_first`], with the dataset at hand, so data-aware
/// macros (`&name!`) can read it at expansion time, under `run`
/// (their shell gate, their instant).
pub fn expand_first_with(
    query: &str,
    defs: &Defs,
    adapter: &impl AstAdapter,
    run: &Run,
) -> Result<Vec<String>> {
    let _scope = graph::run::enter(Some(run.clone()));
    let tokens = lexer::lex(query)?;
    parser::parse_first_steps(
        &tokens,
        defs.clone(),
        &graph::reflect::Reflector::new(Some(adapter)),
    )
}

/// Like [`expand`], with the dataset at hand, so data-aware macros
/// (`&name!`) can read it at expansion time, under `run`.
pub fn expand_with(
    query: &str,
    defs: &Defs,
    adapter: &impl AstAdapter,
    run: &Run,
) -> Result<String> {
    Ok(Query::parse_with(query, defs, adapter, run)?.canonical())
}

/// Take `| copy` or `@| copy` off the end of a query text (spec:
/// Output Commands, "The clipboard"): the output boundary is the
/// tool's, so the host that prints applies it; the pipe carries no
/// information for it, the output being one thing however many
/// threads stand before it. Answers the query without it and the
/// name of the rendering the copied text is in — the closing
/// renderer's (`JSON`, `CSV`, `kaiv`, …) or `text` for the default
/// rendering — or `None` when the query does not end in `copy`
/// (a `copy` anywhere else reaches the executor and refuses).
pub fn take_copy(query: &str) -> Option<(String, &'static str)> {
    let trimmed = query.trim_end();
    let head = trimmed.strip_suffix("copy")?;
    let head = head.trim_end();
    let rest = head.strip_suffix('|')?;
    if rest.ends_with('$') {
        return None;
    }
    let rest = rest.strip_suffix('@').unwrap_or(rest);
    let rest = rest.trim_end();
    if rest.is_empty() {
        return None;
    }
    let last = rest.rsplit(['|']).next().unwrap_or("").trim();
    let name: String = last
        .chars()
        .take_while(|c| c.is_alphanumeric() || *c == '_' || *c == '-')
        .collect();
    let rendering = match name.as_str() {
        "json" => "JSON",
        "jsonl" => "JSON Lines",
        "yaml" => "YAML",
        "toml" => "TOML",
        "xml" => "XML",
        "csv" => "CSV",
        "table" | "pretty" => "a table",
        "kaiv" => "kaiv",
        "markdown" => "Markdown",
        "html" => "HTML",
        "atrep" => "atrep",
        _ => "text",
    };
    Some((rest.to_string(), rendering))
}