quarb 0.56.0

//! The scalar world.
//!
//! Navigation produces nodes; a projection turns each node into a
//! [`Value`]. Quarb is value-domain agnostic, so this is a small,
//! open set of scalar shapes an adapter can return.

use super::words::is_bool_word;
use std::fmt;

/// The value of a `q(…)` literal (spec: Quarqs): the body as parsed,
/// its canonical source, and — when the body is nothing but a
/// structure of projectors (`q(::x)`, `q(%(::Name; ::Fare))`) — that
/// structure, which is what the literal then answers: a projector is
/// the simplest quarq and keeps its own type word.
#[derive(Debug, Clone)]
pub struct Quarq {
    /// The canonical spelling, `q(+ 3)`.
    pub source: String,
    /// The commands of the body, as after a pipe.
    pub body: std::sync::Arc<Vec<crate::syntax::ast::Command>>,
    /// The projector or structured projector the body spells, when
    /// it spells one and nothing else.
    pub projector: Option<Box<Value>>,
    /// The template's expansions (design paper: the quasiquote), in
    /// the order the body's holes index them; empty for a quarq
    /// without any, and for a filled one.
    pub holes: std::sync::Arc<Vec<crate::syntax::ast::Hole>>,
    /// The construct the quarq stands for exactly, when it came
    /// from a reflected node (a node overwritten, a constructor's
    /// answer): a step, a predicate, a projection — what the body's
    /// commands only approximate (design paper: the node overwrite).
    pub form: Option<Box<crate::syntax::expand::Form>>,
    /// The topic of the pushing thread at the push (spec: Quarqs,
    /// the held quarq's appliers): what `&$.x#` takes as `$_`. None
    /// until the quarq is pushed.
    pub at: Option<Box<Value>>,
}

/// The name of the quarq's own core field, the inverse of the `q(…)`
/// wrapping: the canonical text of what the quarq stands for (the line
/// `--expand` prints). The spelling is the spec's (draft 208) and
/// lives here alone.
pub const QUARQ_TEXT_FIELD: &str = "unq";

impl Quarq {
    /// Whether the body still holds expansions to fill.
    pub fn is_template(&self) -> bool {
        !self.holes.is_empty()
    }

    /// The inverse of the wrapping: the canonical spelling inside
    /// `q(…)`, as `--expand` prints it, which for a quarq written
    /// around an invocation is the expansion the invocation received.
    pub fn unq_text(&self) -> &str {
        self.source
            .strip_prefix("q(")
            .and_then(|s| s.strip_suffix(')'))
            .unwrap_or(&self.source)
    }

    /// The quarq's own core field (spec: Quarqs; Core Fields), named
    /// by `QUARQ_TEXT_FIELD`: the engine's fact about the value, its
    /// canonical text — the line `--expand` prints. None for any other
    /// key: the thread's position answers the node's core fields as
    /// for any value.
    pub fn core_field(&self, key: &str) -> Option<Value> {
        if key == QUARQ_TEXT_FIELD {
            Some(Value::Str(self.unq_text().to_string()))
        } else {
            None
        }
    }

    /// The construct the quarq grafts as: its exact form, else its
    /// commands as a pipeline.
    pub fn into_form(self) -> crate::syntax::expand::Form {
        match self.form {
            Some(f) => *f,
            None => crate::syntax::expand::Form::Pipeline((*self.body).clone()),
        }
    }
}

impl PartialEq for Quarq {
    fn eq(&self, other: &Self) -> bool {
        self.source == other.source
    }
}

/// A projected scalar value.
#[derive(Debug, Clone, PartialEq)]
pub enum Value {
    /// Absent / undefined.
    Null,
    /// A boolean (e.g. `:is-leaf`).
    Bool(bool),
    /// An integer (e.g. `:::size`, `:index`).
    Int(i64),
    /// A floating-point number.
    Float(f64),
    /// A string (e.g. `:name`, file content).
    Str(String),
    /// A list of values (produced by aggregating pipeline commands).
    /// Shared behind an `Arc`: a register read or a group's topic
    /// copies a pointer, not the elements, so a large list used as a
    /// set operand costs its construction once.
    List(std::sync::Arc<Vec<Value>>),
    /// A record: insertion-ordered fields (spec: Record). Field
    /// order is significant, matching kaiv namespaces and JSON key
    /// order. The keys are scalars, text as a rule (draft 166): the
    /// [`Record`] holds every key's text, the typed keys beside it
    /// where any is no text, and the fields' declarations.
    Record(Record),
    /// A table (spec: The Table Kind): rows of one width, with a
    /// header naming the columns (a frame) or without one (an
    /// array). The reading a list of same-shaped records admits,
    /// written `#(...)`; a hole is `null`. Shared behind an `Arc`
    /// like a list.
    Table(std::sync::Arc<Table>),
    /// A point on the UTC timeline (spec: The Temporal Fragment).
    /// `offset_min` preserves the source's UTC offset for display
    /// only — comparison is always on the timeline. Displays as
    /// ISO-8601; a midnight instant with no offset prints as a
    /// bare date.
    Instant {
        secs: i64,
        nanos: u32,
        offset_min: Option<i16>,
        /// The calendar the instant is read in (spec: Calendars):
        /// like the offset, kept for reading and display only.
        calendar: crate::calendar::Calendar,
    },
    /// A stretch of the UTC calendar named at a grain (spec: The
    /// Temporal Fragment): its first second and the grain. Displays
    /// as ISO-8601 at reduced precision (`1812`, `2025-10`,
    /// `1899-10-06T14:30`). Compares as an interval; takes no part
    /// in arithmetic.
    Period {
        start: i64,
        grain: crate::period::Grain,
        /// The calendar whose month or year the period names.
        calendar: crate::calendar::Calendar,
    },
    /// A value on a dimension (spec: The Quantital Fragment):
    /// the magnitude scaled to the dimension's SI-base expansion
    /// (`base`, e.g. `m`, `m^2*kg/s^3`), the written form kept
    /// for display only — exactly as instants keep their written
    /// offset. Minted by unit-aware adapters (kaiv); compared and
    /// combined on the base, so `42 km` orders above `5000 m`.
    Quantity {
        value: f64,
        base: String,
        /// The authored magnitude and unit, for display
        /// (`42 km`); absent for computed quantities, which
        /// display in the base.
        written: Option<(f64, String)>,
    },
    /// A library value (spec: Command Libraries, "A library
    /// value"): what a command library built and keeps in its own
    /// form — a frame, an array, an object — so that its next
    /// command takes it as it is, with no crossing into records and
    /// lists between two commands. The engine knows its kind for
    /// messages, its text (the object's own display), and its two
    /// exports, the row reading (`| @`) and the column reading
    /// (`| %`); anything else done with one is refused by kind.
    /// Two library values are equal only when they are the same
    /// object.
    Foreign(ForeignValue),
    /// A projector (spec: Projectors, draft 164):
    /// a ladder — 1 the core field `:`, 2 the property `::`, 3 the
    /// adapter metadata `:::` — and its key. It prints as the
    /// projection is written (`::title`, the key quoted where it is
    /// no identifier) and coerces to text as the bare key. A TYPED
    /// projector (draft 166) carries a declared type in the trait
    /// brackets, `:A<int>`: it declares the field it names and
    /// stands only where a field is declared (a header item, a
    /// record key, a structured projector's item, `map`'s body);
    /// `:A<*; float>` is how a header reports an undeclared column
    /// beside its inferred type, and declares nothing.
    Projection {
        ladder: u8,
        key: String,
        typing: Option<Typing>,
    },
    /// A quarq (spec: Quarqs, draft 166): a command as it stands
    /// after a pipe, read as Quarb and not run — the value of the
    /// `q(…)` literal, the sibling of `sh(…)`. It prints as its
    /// source, two are equal when their source is, `| type` reads
    /// `quarq`; nothing runs it but the glued colon and the commands
    /// that take a command (`map`, the keyed aggregates), where it
    /// is late bound: `$_`, the registers and the cursor inside it
    /// are read where it is applied.
    Quarq(Quarq),
    /// A node reference (spec: The Capsa, "Node references"): an
    /// engine-minted value naming one node of the arbor. It prints
    /// and exports as the node's locator, two references to one node
    /// are equal whatever the readings that minted them, and `-->`
    /// resolves it back to the node. `| type` reads `node`. The
    /// value layer knows the node only as a number: the graph mints
    /// the reference and reads it back.
    Node(NodeRef),
}

/// A node reference's payload: the node's coordinate in the run
/// and its locator, rendered when the reference was minted (the
/// value layer cannot reach an adapter). Equality and hashing are
/// by coordinate.
#[derive(Clone)]
pub struct NodeRef {
    pub id: u64,
    pub locator: std::sync::Arc<str>,
}

impl NodeRef {
    pub fn new(id: u64, locator: impl Into<std::sync::Arc<str>>) -> NodeRef {
        NodeRef {
            id,
            locator: locator.into(),
        }
    }
}

impl PartialEq for NodeRef {
    fn eq(&self, other: &NodeRef) -> bool {
        self.id == other.id
    }
}

impl Eq for NodeRef {}

impl std::hash::Hash for NodeRef {
    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
        self.id.hash(state)
    }
}

impl std::fmt::Debug for NodeRef {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Node({}#{})", self.locator, self.id)
    }
}

/// Fields whose names are paths of levels (`bar:A`, `bar:B`, `baz`)
/// nested into a record by level (spec: The Table, "Levels of the
/// header"): the outer names in first-met order, each holding the
/// record of what stands under it.
fn nest_by_levels(fields: Vec<(String, Value)>) -> Value {
    if !fields.iter().any(|(k, _)| k.contains(':')) {
        return Value::record(fields);
    }
    let mut out: Vec<(String, Value)> = Vec::new();
    let mut groups: Vec<(String, Vec<(String, Value)>)> = Vec::new();
    for (k, v) in fields {
        match k.split_once(':') {
            Some((outer, inner)) => match groups.iter_mut().find(|(o, _)| *o == outer) {
                Some((_, g)) => g.push((inner.to_string(), v)),
                None => {
                    out.push((outer.to_string(), Value::Null));
                    groups.push((outer.to_string(), vec![(inner.to_string(), v)]));
                }
            },
            None => out.push((k, v)),
        }
    }
    for (o, g) in groups {
        if let Some(slot) = out
            .iter_mut()
            .find(|(k, v)| *k == o && matches!(v, Value::Null))
        {
            slot.1 = nest_by_levels(g);
        }
    }
    Value::record(out)
}

/// The cells nested level by level under their labels (spec: The
/// Table, "The index"): at each level a record keyed by the distinct
/// values of that level in first-met order, the innermost level
/// holding the cell.
fn nest_levels(levels: &[Vec<Value>], cells: &[Value], depth: usize) -> Value {
    let width = levels.first().map_or(0, Vec::len);
    if depth + 1 >= width {
        return Value::Record(Record::keyed(
            levels
                .iter()
                .zip(cells)
                .map(|(l, c)| (l.get(depth).cloned().unwrap_or(Value::Null), c.clone()))
                .collect(),
        ));
    }
    let mut keys: Vec<Value> = Vec::new();
    for l in levels {
        let k = l.get(depth).cloned().unwrap_or(Value::Null);
        if !keys.contains(&k) {
            keys.push(k);
        }
    }
    Value::Record(Record::keyed(
        keys.into_iter()
            .map(|k| {
                let (sub_levels, sub_cells): (Vec<Vec<Value>>, Vec<Value>) = levels
                    .iter()
                    .zip(cells)
                    .filter(|(l, _)| l.get(depth) == Some(&k))
                    .map(|(l, c)| (l.clone(), c.clone()))
                    .unzip();
                let v = nest_levels(&sub_levels, &sub_cells, depth + 1);
                (k, v)
            })
            .collect(),
    ))
}

/// A record's fields (spec: Record, draft 166): the key's text and
/// the value per field, in order; beside them the keys as VALUES
/// where any key is no text (`%(1 = "a"; 2013-01-01 = 5)`: an
/// integer and an instant, equal as values, `1` and `"1"` two keys)
/// and the declaration per field (`%(price<float> = …)`, the field
/// then fixed to its type). A record with text keys and no
/// declaration carries nothing beside its fields, the common case.
/// It derefs to the fields, so a reader sees `Vec<(String, Value)>`
/// as ever; a text key's value is its text.
#[derive(Debug, Clone, Default)]
pub struct Record {
    fields: Vec<(String, Value)>,
    /// The keys as values, one per field, where any is no text.
    keys: Option<Vec<Value>>,
    /// The declared type per field, where any field is declared.
    declared: Option<Vec<Option<ColumnType>>>,
}

impl Record {
    /// A record of text keys.
    pub fn new(fields: Vec<(String, Value)>) -> Record {
        Record {
            fields,
            keys: None,
            declared: None,
        }
    }

    /// A record keyed by values: a text key stays text, any other
    /// scalar is held typed beside its text form.
    pub fn keyed(pairs: Vec<(Value, Value)>) -> Record {
        let typed = pairs.iter().any(|(k, _)| !matches!(k, Value::Str(_)));
        let keys = typed.then(|| pairs.iter().map(|(k, _)| k.clone()).collect());
        let fields = pairs
            .into_iter()
            .map(|(k, v)| (Record::key_text(&k), v))
            .collect();
        Record {
            fields,
            keys,
            declared: None,
        }
    }

    /// The text of a key: a text as it is, any other scalar in its
    /// display form (the text `:name` reads it by).
    pub fn key_text(k: &Value) -> String {
        match k {
            Value::Str(s) => s.clone(),
            other => other.to_string(),
        }
    }

    /// The key of field `i` as a value: the typed key, or the text.
    pub fn key(&self, i: usize) -> Value {
        match self.keys.as_ref().and_then(|k| k.get(i)) {
            Some(k) => k.clone(),
            None => Value::Str(
                self.fields
                    .get(i)
                    .map(|(k, _)| k.clone())
                    .unwrap_or_default(),
            ),
        }
    }

    /// The keys as values, in order (`| keys`).
    pub fn key_values(&self) -> Vec<Value> {
        (0..self.fields.len()).map(|i| self.key(i)).collect()
    }

    /// Whether any key is no text.
    pub fn has_typed_keys(&self) -> bool {
        self.keys.is_some()
    }

    /// The field whose key equals `k` AS A VALUE (`r[[k]]`): a text
    /// key equals its text, a typed key its value.
    pub fn find_key(&self, k: &Value) -> Option<usize> {
        // keys are equal as values (the review's Values pass,
        // 2026-11-06): 1 and 1.0 are one number, 1 and "1" two keys
        let same = |a: &Value, b: &Value| match (a, b) {
            (Value::Int(x), Value::Float(y)) | (Value::Float(y), Value::Int(x)) => *x as f64 == *y,
            _ => a == b,
        };
        (0..self.fields.len()).find(|&i| same(&self.key(i), k))
    }

    /// The field under the text key `k` (`:name`).
    pub fn get(&self, k: &str) -> Option<&Value> {
        self.fields.iter().find(|(f, _)| f == k).map(|(_, v)| v)
    }

    /// The declared type of field `i`, `Some` where it is declared.
    pub fn declaration(&self, i: usize) -> Option<ColumnType> {
        self.declared
            .as_ref()
            .and_then(|d| d.get(i))
            .cloned()
            .flatten()
    }

    /// Whether any field is declared.
    pub fn has_declarations(&self) -> bool {
        self.declared
            .as_ref()
            .is_some_and(|d| d.iter().any(Option::is_some))
    }

    /// Field `i` declared `ty` (`None` undeclares it).
    /// Field `i`'s value replaced, its key and declaration kept.
    pub fn set_value(&mut self, i: usize, v: Value) {
        if let Some(f) = self.fields.get_mut(i) {
            f.1 = v;
        }
    }

    pub fn declare(&mut self, i: usize, ty: Option<ColumnType>) {
        let d = self
            .declared
            .get_or_insert_with(|| vec![None; self.fields.len()]);
        d.resize(self.fields.len(), None);
        d[i] = ty;
        if d.iter().all(Option::is_none) {
            self.declared = None;
        }
    }

    /// A field appended under a text key (a `push((k, v))` through
    /// the deref says the same).
    pub fn push_field(&mut self, k: String, v: Value) {
        self.push_keyed(Value::Str(k), v, None);
    }

    /// A field appended under a key value, with its declaration.
    pub fn push_keyed(&mut self, k: Value, v: Value, ty: Option<ColumnType>) {
        let n = self.fields.len();
        if !matches!(k, Value::Str(_)) {
            let keys = self.keys.get_or_insert_with(|| vec![Value::Null; n]);
            keys.resize(n, Value::Null);
            // the text keys before it, held as text
            for (i, slot) in keys.iter_mut().enumerate() {
                if matches!(slot, Value::Null) {
                    *slot = Value::Str(self.fields[i].0.clone());
                }
            }
            keys.push(k.clone());
        } else if let Some(keys) = &mut self.keys {
            keys.resize(n, Value::Null);
            keys.push(k.clone());
        }
        if let Some(d) = &mut self.declared {
            d.resize(n, None);
            d.push(ty);
        } else if ty.is_some() {
            let mut d = vec![None; n];
            d.push(ty);
            self.declared = Some(d);
        }
        self.fields.push((Record::key_text(&k), v));
    }

    /// The value of field `i` replaced.
    pub fn set(&mut self, i: usize, v: Value) {
        if let Some(f) = self.fields.get_mut(i) {
            f.1 = v;
        }
    }

    /// The fields alone, the keys as text.
    pub fn into_fields(self) -> Vec<(String, Value)> {
        self.fields
    }

    /// The record with every value replaced by `f`'s, the keys and
    /// the declarations kept.
    pub fn map_values(self, mut f: impl FnMut(Value) -> Value) -> Record {
        Record {
            fields: self.fields.into_iter().map(|(k, v)| (k, f(v))).collect(),
            keys: self.keys,
            declared: self.declared,
        }
    }

    /// The record with its values replaced in order (`shift` keeps
    /// the keys and the declarations).
    pub fn with_values(&self, values: Vec<Value>) -> Record {
        Record {
            fields: self
                .fields
                .iter()
                .zip(values)
                .map(|((k, _), v)| (k.clone(), v))
                .collect(),
            keys: self.keys.clone(),
            declared: self.declared.clone(),
        }
    }

    /// The record with the fields `keep(i)` admits, the keys and
    /// declarations kept in step.
    pub fn filter_fields(self, mut keep: impl FnMut(usize, &(String, Value)) -> bool) -> Record {
        let kept: Vec<bool> = self
            .fields
            .iter()
            .enumerate()
            .map(|(i, f)| keep(i, f))
            .collect();
        let pick = |v: Vec<Value>| -> Vec<Value> {
            v.into_iter()
                .zip(&kept)
                .filter(|(_, k)| **k)
                .map(|(x, _)| x)
                .collect()
        };
        Record {
            fields: self
                .fields
                .into_iter()
                .zip(&kept)
                .filter(|(_, k)| **k)
                .map(|(f, _)| f)
                .collect(),
            keys: self.keys.map(pick),
            declared: self.declared.map(|d| {
                d.into_iter()
                    .zip(&kept)
                    .filter(|(_, k)| **k)
                    .map(|(x, _)| x)
                    .collect()
            }),
        }
    }

    /// The key of field `i` in Quarb's text: a text key bare where
    /// it is an identifier, quoted otherwise; a typed key as its
    /// literal.
    pub fn key_quarb(&self, i: usize) -> String {
        match self.keys.as_ref().and_then(|k| k.get(i)) {
            Some(Value::Str(_)) | None => quarb_key(&self.fields[i].0),
            Some(k) => k.to_quarb(),
        }
    }
}

impl PartialEq for Record {
    /// Two records are equal item by item: the keys as values and
    /// the values; a declaration is no part of the value.
    fn eq(&self, other: &Record) -> bool {
        self.fields.len() == other.fields.len()
            && self
                .fields
                .iter()
                .zip(other.fields.iter())
                .enumerate()
                .all(|(i, ((_, a), (_, b)))| a == b && self.key(i) == other.key(i))
    }
}

impl std::ops::Deref for Record {
    type Target = Vec<(String, Value)>;
    fn deref(&self) -> &Vec<(String, Value)> {
        &self.fields
    }
}

impl std::ops::DerefMut for Record {
    /// Writes through to the fields; a push through here appends a
    /// text, undeclared field (the accessors read a shorter `keys`
    /// or `declared` as text and undeclared).
    fn deref_mut(&mut self) -> &mut Vec<(String, Value)> {
        &mut self.fields
    }
}

impl From<Vec<(String, Value)>> for Record {
    fn from(fields: Vec<(String, Value)>) -> Record {
        Record::new(fields)
    }
}

impl FromIterator<(String, Value)> for Record {
    fn from_iter<I: IntoIterator<Item = (String, Value)>>(iter: I) -> Record {
        Record::new(iter.into_iter().collect())
    }
}

impl IntoIterator for Record {
    type Item = (String, Value);
    type IntoIter = std::vec::IntoIter<(String, Value)>;
    fn into_iter(self) -> Self::IntoIter {
        self.fields.into_iter()
    }
}

impl<'a> IntoIterator for &'a Record {
    type Item = &'a (String, Value);
    type IntoIter = std::slice::Iter<'a, (String, Value)>;
    fn into_iter(self) -> Self::IntoIter {
        self.fields.iter()
    }
}

/// A table: rows of one width, each cell a value, `null` the hole.
/// With a header it is a frame (the columns named, `t:age` a
/// column); without one an array (`#(%(1; 2); %(3; 4))`, the positions
/// its columns). One kind,
/// two faces: an ndarray and a DataFrame are its two boundary forms.
#[derive(Debug, Clone)]
pub struct Table {
    pub header: Option<Vec<String>>,
    /// The cells by column, each column stored by its kind (the
    /// columnar round, 2026-11-06): a value is made on read.
    columns: Vec<Column>,
    /// How many rows the table holds (its columns are that long).
    n: usize,
    /// The declared type per column (spec: The Table, "Columns",
    /// draft 166): `Some` where a typed projector declared the
    /// column, which is then fixed to it; `None` where the column
    /// is undeclared and typed by its cells. Empty when no column
    /// is declared (the common case, every file read).
    pub declared: Vec<Option<ColumnType>>,
    /// The number of leading columns that are the INDEX (spec: The
    /// Table, "The index", draft 166): 0 on a plain table, 1 where
    /// `#(-i=:col)` named a column the labels of the rows (the
    /// column stays a column, first in the header); more under a
    /// composite index. The labels are the keys of the records the
    /// table answers (`t:A`), looked up by `t[[label]]`.
    pub index: usize,
    /// The header's name (`#(--header=…; --name=word)`, draft 166),
    /// read back by `:::name`; `column` is the no-name default on
    /// both axes, so `transpose` exchanges it with the index
    /// column's name and undoes itself.
    pub name: Option<String>,
}

impl PartialEq for Table {
    /// Two tables are equal cell for cell under the same header,
    /// declarations, index and name, whatever each column's storage.
    fn eq(&self, other: &Table) -> bool {
        self.header == other.header
            && self.n == other.n
            && self.width() == other.width()
            && self.declared == other.declared
            && self.index == other.index
            && self.name == other.name
            && (0..self.width()).all(|j| (0..self.n).all(|i| self.cell(i, j) == other.cell(i, j)))
    }
}

/// Which cells of a column are null: a bitmap, empty while none is.
#[derive(Debug, Clone, PartialEq, Default)]
pub(crate) struct Nulls {
    bits: Vec<u64>,
    len: usize,
    count: usize,
}

impl Nulls {
    fn get(&self, i: usize) -> bool {
        self.bits
            .get(i / 64)
            .is_some_and(|w| (w >> (i % 64)) & 1 == 1)
    }

    fn push(&mut self, null: bool) {
        if null {
            let w = self.len / 64;
            if self.bits.len() <= w {
                self.bits.resize(w + 1, 0);
            }
            self.bits[w] |= 1 << (self.len % 64);
            self.count += 1;
        }
        self.len += 1;
    }

    fn nulls(n: usize) -> Nulls {
        let mut out = Nulls::default();
        for _ in 0..n {
            out.push(true);
        }
        out
    }
}

/// A column's cells, stored by kind: the numbers and booleans as
/// their vectors, the texts end to end in one arena, anything else
/// (an instant, a quantity, a node reference, a list cell, or a mix
/// of kinds) as values. A column's kind is its first value's; a
/// value of another kind turns it mixed. A table reads a cell by
/// making the value, so what a reader sees is the row-form table.
#[derive(Debug, Clone, PartialEq)]
pub(crate) enum Column {
    /// Nothing but nulls so far.
    Null(usize),
    Bool {
        cells: Vec<bool>,
        nulls: Nulls,
    },
    Int {
        cells: Vec<i64>,
        nulls: Nulls,
    },
    Float {
        cells: Vec<f64>,
        nulls: Nulls,
    },
    Text {
        bytes: Vec<u8>,
        ends: Vec<u32>,
        nulls: Nulls,
    },
    Mixed(Vec<Value>),
}

impl Column {
    fn len(&self) -> usize {
        match self {
            Column::Null(n) => *n,
            Column::Bool { cells, .. } => cells.len(),
            Column::Int { cells, .. } => cells.len(),
            Column::Float { cells, .. } => cells.len(),
            Column::Text { ends, .. } => ends.len(),
            Column::Mixed(cells) => cells.len(),
        }
    }

    /// Cell `i`, null past the end.
    fn get(&self, i: usize) -> Value {
        match self {
            Column::Null(_) => Value::Null,
            Column::Bool { cells, nulls } => match cells.get(i) {
                Some(b) if !nulls.get(i) => Value::Bool(*b),
                _ => Value::Null,
            },
            Column::Int { cells, nulls } => match cells.get(i) {
                Some(x) if !nulls.get(i) => Value::Int(*x),
                _ => Value::Null,
            },
            Column::Float { cells, nulls } => match cells.get(i) {
                Some(x) if !nulls.get(i) => Value::Float(*x),
                _ => Value::Null,
            },
            Column::Text { bytes, ends, nulls } => match ends.get(i) {
                Some(&end) if !nulls.get(i) => {
                    let start = if i == 0 { 0 } else { ends[i - 1] as usize };
                    Value::Str(String::from_utf8_lossy(&bytes[start..end as usize]).into_owned())
                }
                _ => Value::Null,
            },
            Column::Mixed(cells) => cells.get(i).cloned().unwrap_or(Value::Null),
        }
    }

    /// The column a first value opens, after `n` nulls.
    fn opened_by(v: &Value, n: usize) -> Column {
        let nulls = Nulls::nulls(n);
        match v {
            Value::Bool(_) => Column::Bool {
                cells: vec![false; n],
                nulls,
            },
            Value::Int(_) => Column::Int {
                cells: vec![0; n],
                nulls,
            },
            Value::Float(_) => Column::Float {
                cells: vec![0.0; n],
                nulls,
            },
            Value::Str(_) => Column::Text {
                bytes: Vec::new(),
                ends: vec![0; n],
                nulls,
            },
            _ => Column::Mixed(vec![Value::Null; n]),
        }
    }

    /// A cell appended: into the column's kind, or the column turns
    /// mixed.
    fn push(&mut self, v: Value) {
        let v = match self {
            Column::Null(n) => {
                if matches!(v, Value::Null) {
                    *n += 1;
                    return;
                }
                let n = *n;
                *self = Column::opened_by(&v, n);
                return self.push(v);
            }
            Column::Bool { cells, nulls } => match v {
                Value::Bool(b) => {
                    cells.push(b);
                    nulls.push(false);
                    return;
                }
                Value::Null => {
                    cells.push(false);
                    nulls.push(true);
                    return;
                }
                other => other,
            },
            Column::Int { cells, nulls } => match v {
                Value::Int(x) => {
                    cells.push(x);
                    nulls.push(false);
                    return;
                }
                Value::Null => {
                    cells.push(0);
                    nulls.push(true);
                    return;
                }
                other => other,
            },
            Column::Float { cells, nulls } => match v {
                Value::Float(x) => {
                    cells.push(x);
                    nulls.push(false);
                    return;
                }
                Value::Null => {
                    cells.push(0.0);
                    nulls.push(true);
                    return;
                }
                other => other,
            },
            Column::Text { bytes, ends, nulls } => match v {
                Value::Str(s) if bytes.len() + s.len() <= u32::MAX as usize => {
                    bytes.extend_from_slice(s.as_bytes());
                    ends.push(bytes.len() as u32);
                    nulls.push(false);
                    return;
                }
                Value::Null => {
                    ends.push(bytes.len() as u32);
                    nulls.push(true);
                    return;
                }
                other => other,
            },
            Column::Mixed(cells) => {
                cells.push(v);
                return;
            }
        };
        *self = Column::Mixed(self.to_values());
        self.push(v);
    }

    /// The cells at `idx`, in that order, as a column of the same
    /// kind: a gather, no value made on the way.
    fn take(&self, idx: &[usize]) -> Column {
        match self {
            Column::Null(_) => Column::Null(idx.len()),
            Column::Bool { cells, nulls } => {
                let mut taken = Nulls::default();
                let cells = idx
                    .iter()
                    .map(|&i| {
                        taken.push(nulls.get(i) || i >= cells.len());
                        cells.get(i).copied().unwrap_or(false)
                    })
                    .collect();
                Column::Bool {
                    cells,
                    nulls: taken,
                }
            }
            Column::Int { cells, nulls } => {
                let mut taken = Nulls::default();
                let cells = idx
                    .iter()
                    .map(|&i| {
                        taken.push(nulls.get(i) || i >= cells.len());
                        cells.get(i).copied().unwrap_or(0)
                    })
                    .collect();
                Column::Int {
                    cells,
                    nulls: taken,
                }
            }
            Column::Float { cells, nulls } => {
                let mut taken = Nulls::default();
                let cells = idx
                    .iter()
                    .map(|&i| {
                        taken.push(nulls.get(i) || i >= cells.len());
                        cells.get(i).copied().unwrap_or(0.0)
                    })
                    .collect();
                Column::Float {
                    cells,
                    nulls: taken,
                }
            }
            Column::Text { bytes, ends, nulls } => {
                let mut out_bytes = Vec::new();
                let mut out_ends = Vec::with_capacity(idx.len());
                let mut taken = Nulls::default();
                for &i in idx {
                    match ends.get(i) {
                        Some(&end) if !nulls.get(i) => {
                            let start = if i == 0 { 0 } else { ends[i - 1] as usize };
                            out_bytes.extend_from_slice(&bytes[start..end as usize]);
                            taken.push(false);
                        }
                        _ => taken.push(true),
                    }
                    out_ends.push(out_bytes.len() as u32);
                }
                Column::Text {
                    bytes: out_bytes,
                    ends: out_ends,
                    nulls: taken,
                }
            }
            Column::Mixed(cells) => Column::Mixed(
                idx.iter()
                    .map(|&i| cells.get(i).cloned().unwrap_or(Value::Null))
                    .collect(),
            ),
        }
    }

    fn to_values(&self) -> Vec<Value> {
        (0..self.len()).map(|i| self.get(i)).collect()
    }

    /// Cells `from..to` as a column of their own.
    fn slice(&self, from: usize, to: usize) -> Column {
        let mut out = Column::Null(0);
        for i in from..to.min(self.len()) {
            out.push(self.get(i));
        }
        out
    }

    /// Whether any cell holds what a flat table refuses (a list, a
    /// record, a table): the typed kinds never do.
    fn any_cell(&self, f: impl Fn(&Value) -> bool) -> bool {
        match self {
            Column::Mixed(cells) => cells.iter().any(f),
            _ => false,
        }
    }
}

/// The rank of text in the type order: the type every cell has.
const TEXT_RANK: usize = ColumnType::ORDER.len() - 1;

/// A column as it is built (the one-pass typed build, 2026-11-06):
/// the cells as they arrive, lossless (`raw`: the text in its arena,
/// a number as a number), and beside them the column typed as the
/// LEADER types it — the first type of the order every cell so far
/// coerces to. A cell the leader does not coerce moves the leader
/// forward: the next type of the order every cell so far coerces to
/// is found over the raw cells (text stays the last and always
/// fits), and the typed column is packed again from them — the raw
/// text is what is re-read, never a lossy parse. When the leader is
/// text and the raw column is text already the two are one, and
/// nothing is kept twice.
#[derive(Debug)]
struct ColumnBuilder {
    raw: Column,
    /// The leader's column; `None` while it is the raw column itself.
    typed: Option<Column>,
    /// The leader's rank in the order; past the end: the column
    /// stays raw (a projector cell was seen).
    leader: usize,
    /// The quantity base the leader saw first, while it is quantity.
    base: Option<String>,
    /// A declared column: every cell cast to it, or the first row
    /// that does not, held for the refusal.
    declared: Option<ColumnType>,
    failed: Option<(usize, String)>,
}

impl ColumnBuilder {
    fn new(n_before: usize, declared: Option<ColumnType>) -> ColumnBuilder {
        ColumnBuilder {
            raw: Column::Null(n_before),
            typed: Some(Column::Null(n_before)),
            leader: 0,
            base: None,
            declared,
            failed: None,
        }
    }

    fn len(&self) -> usize {
        self.raw.len()
    }

    /// A text cell: the one-pass path of a row read from its bytes.
    fn push_text(&mut self, s: &str) {
        if self.declared.is_some() || self.leader > TEXT_RANK {
            return self.push(Value::Str(s.to_string()));
        }
        if self.leader == TEXT_RANK {
            // text into a text column: nothing to coerce
            if self.typed.is_none() {
                self.raw.push(Value::Str(s.to_string()));
            } else {
                self.raw.push(Value::Str(s.to_string()));
                self.typed
                    .as_mut()
                    .expect("typed")
                    .push(Value::Str(s.to_string()));
            }
            return;
        }
        match coerce_text(s, &ColumnType::ORDER[self.leader]) {
            Some(v) if self.base_fits(&v) => {
                self.raw.push(Value::Str(s.to_string()));
                self.typed
                    .as_mut()
                    .expect("a leader below text keeps its column")
                    .push(v);
            }
            _ => {
                self.raw.push(Value::Str(s.to_string()));
                self.widen();
            }
        }
    }

    /// Any cell.
    fn push(&mut self, cell: Value) {
        if let Some(ty) = &self.declared {
            let i = self.raw.len();
            match cast_cell(&cell, ty) {
                Some(v) => self.typed.as_mut().expect("declared").push(v),
                None => {
                    if self.failed.is_none() {
                        self.failed = Some((i, held_text(&cell)));
                    }
                    self.typed.as_mut().expect("declared").push(Value::Null);
                }
            }
            self.raw.push(Value::Null);
            return;
        }
        if self.leader > TEXT_RANK {
            self.raw.push(cell);
            return;
        }
        // a column of projectors is a projector table's (held, read
        // where it is applied): its cells stay as they are
        if matches!(cell, Value::Projection { .. }) {
            self.leader = TEXT_RANK + 1;
            self.typed = None;
            self.raw.push(cell);
            return;
        }
        if self.leader == TEXT_RANK
            && self.typed.is_none()
            && !matches!(cell, Value::Str(_) | Value::Null)
        {
            // the raw column stops being the text column: the text
            // column is made from it
            self.typed = Some(
                Self::coerced_all(&self.raw, &ColumnType::Text, &mut None)
                    .expect("every cell has a text form"),
            );
        }
        let coerced = match &cell {
            Value::Null => Some(Value::Null),
            other => coerce_cell(other, &ColumnType::ORDER[self.leader]),
        };
        match coerced {
            Some(v) if self.base_fits(&v) => {
                if let Some(t) = self.typed.as_mut() {
                    t.push(v);
                }
                self.raw.push(cell);
            }
            _ => {
                self.raw.push(cell);
                self.widen();
            }
        }
    }

    /// A quantity leader holds one dimension: the first base seen.
    fn base_fits(&mut self, v: &Value) -> bool {
        if ColumnType::ORDER[self.leader] != ColumnType::Quantity {
            return true;
        }
        match (v, &self.base) {
            (Value::Quantity { base, .. }, Some(first)) => base == first,
            (Value::Quantity { base, .. }, None) => {
                self.base = Some(base.clone());
                true
            }
            _ => true,
        }
    }

    /// The next type of the order every raw cell coerces to becomes
    /// the leader, its column packed from the raw cells.
    fn widen(&mut self) {
        for rank in self.leader + 1..=TEXT_RANK {
            let t = &ColumnType::ORDER[rank];
            let mut base = None;
            if let Some(col) = Self::coerced_all(&self.raw, t, &mut base) {
                self.leader = rank;
                self.base = base;
                self.typed = if rank == TEXT_RANK
                    && matches!(self.raw, Column::Text { .. } | Column::Null(_))
                {
                    None
                } else {
                    Some(col)
                };
                return;
            }
        }
        unreachable!("text is the top: every scalar has a text form")
    }

    /// Every raw cell coerced to `t` and packed, `None` where one
    /// does not coerce or the quantity bases differ.
    fn coerced_all(raw: &Column, t: &ColumnType, base: &mut Option<String>) -> Option<Column> {
        let mut out = Column::Null(0);
        for i in 0..raw.len() {
            let v = coerce_cell(&raw.get(i), t)?;
            if *t == ColumnType::Quantity
                && let Value::Quantity { base: b, .. } = &v
            {
                match base {
                    Some(first) if first != b => return None,
                    Some(_) => {}
                    None => *base = Some(b.clone()),
                }
            }
            out.push(v);
        }
        Some(out)
    }

    fn finish(self) -> Result<Column, (usize, String)> {
        if let Some(failed) = self.failed {
            return Err(failed);
        }
        Ok(match self.typed {
            Some(t) => t,
            None => self.raw,
        })
    }
}

/// A table built a row at a time (the columnar round, 2026-11-06),
/// typed as it is built: the streamed table build's store — a
/// record per node, or a row of cells in the columns' order, pushed
/// as it is read, each column keeping its leading type as the cells
/// arrive — and every `Table::typed` call's path. No row is held in
/// row form at any point, and no second pass types the table.
#[derive(Debug)]
pub struct TableBuilder {
    header: Option<Vec<String>>,
    at: std::collections::HashMap<String, usize>,
    columns: Vec<ColumnBuilder>,
    declared: Vec<Option<ColumnType>>,
    n: usize,
}

impl Default for TableBuilder {
    fn default() -> Self {
        TableBuilder::new()
    }
}

impl TableBuilder {
    /// A builder whose header grows with the records pushed.
    pub fn new() -> TableBuilder {
        TableBuilder {
            header: Some(Vec::new()),
            at: std::collections::HashMap::new(),
            columns: Vec::new(),
            declared: Vec::new(),
            n: 0,
        }
    }

    /// A builder of a known shape: the rows pushed by position under
    /// `header` (`None`: an array, as wide as its first row), the
    /// columns declared as `declared` says (empty: none).
    pub fn shaped(header: Option<Vec<String>>, declared: Vec<Option<ColumnType>>) -> TableBuilder {
        let columns = header
            .as_ref()
            .map(|h| {
                (0..h.len())
                    .map(|j| ColumnBuilder::new(0, declared.get(j).cloned().flatten()))
                    .collect()
            })
            .unwrap_or_default();
        let at = header
            .as_ref()
            .map(|h| h.iter().cloned().enumerate().map(|(j, k)| (k, j)).collect())
            .unwrap_or_default();
        TableBuilder {
            header,
            at,
            columns,
            declared,
            n: 0,
        }
    }

    pub fn n_rows(&self) -> usize {
        self.n
    }

    fn open_width(&mut self, w: usize) {
        while self.columns.len() < w {
            let j = self.columns.len();
            self.columns.push(ColumnBuilder::new(
                self.n,
                self.declared.get(j).cloned().flatten(),
            ));
        }
    }

    /// A row by position: a cell past the width is dropped, a width
    /// the row lacks is null; an array's first row sets its width.
    pub fn push_row(&mut self, row: Vec<Value>) {
        if self.header.is_none() && self.n == 0 {
            self.open_width(row.len());
        }
        let w = self.columns.len();
        let mut cells = row.into_iter();
        for col in self.columns.iter_mut() {
            col.push(cells.next().unwrap_or(Value::Null));
        }
        debug_assert!(w == self.columns.len());
        self.n += 1;
    }

    /// A row of text cells by position (a CSV record): an empty text
    /// is a cell the row lacks, null.
    pub fn push_text_row(&mut self, row: &[&str]) {
        if self.header.is_none() && self.n == 0 {
            self.open_width(row.len());
        }
        for (j, col) in self.columns.iter_mut().enumerate() {
            match row.get(j) {
                Some(s) if !s.is_empty() => col.push_text(s),
                _ => col.push(Value::Null),
            }
        }
        self.n += 1;
    }

    /// A record's fields as the next row: a new name opens a column
    /// (null above), a name the record lacks is null here.
    pub fn push_record(&mut self, fields: impl IntoIterator<Item = (String, Value)>) {
        let mut row: Vec<Option<Value>> = vec![None; self.columns.len()];
        for (k, v) in fields {
            let j = match self.at.get(&k) {
                Some(&j) => j,
                None => {
                    let j = self.columns.len();
                    self.at.insert(k.clone(), j);
                    self.header.get_or_insert_with(Vec::new).push(k);
                    self.columns.push(ColumnBuilder::new(self.n, None));
                    row.push(None);
                    j
                }
            };
            row[j] = Some(v);
        }
        for (j, c) in row.into_iter().enumerate() {
            self.columns[j].push(c.unwrap_or(Value::Null));
        }
        self.n += 1;
    }

    /// The table: typed as every table is, or the refusal of a
    /// declared column's cell.
    pub fn finish(self) -> Result<Table, String> {
        let header = self.header;
        let name_of = |j: usize| -> String {
            match &header {
                Some(h) => h.get(j).cloned().unwrap_or_else(|| (j + 1).to_string()),
                None => (j + 1).to_string(),
            }
        };
        let mut columns = Vec::with_capacity(self.columns.len());
        for (j, col) in self.columns.into_iter().enumerate() {
            let ty = col.declared.clone();
            match col.finish() {
                Ok(c) => columns.push(c),
                Err((i, held)) => {
                    return Err(format!(
                        "column '{}' is declared {}, and row {} holds {}, which does not cast to it",
                        name_of(j),
                        ty.map(|t| t.word()).unwrap_or_default(),
                        i + 1,
                        held,
                    ));
                }
            }
        }
        let mut declared = self.declared;
        let w = columns.len();
        declared.resize(w, None);
        if declared.iter().all(Option::is_none) {
            declared.clear();
        }
        Ok(Table {
            header,
            columns,
            n: self.n,
            declared,
            index: 0,
            name: None,
        })
    }
}

/// The keys a list of two or more records share in one order, when
/// every item is such a record with at least one field: the header
/// of the record array the list prints as.
fn record_array_keys(items: &[Value]) -> Option<&[(String, Value)]> {
    if items.len() < 2 {
        return None;
    }
    let Value::Record(first) = &items[0] else {
        return None;
    };
    if first.is_empty() {
        return None;
    }
    let same = items.iter().all(|v| match v {
        Value::Record(o) => {
            o.len() == first.len() && o.iter().zip(first.iter()).all(|((a, _), (b, _))| a == b)
        }
        _ => false,
    });
    same.then_some(first.as_slice())
}

/// The type of a table column (spec: The Table): one scalar type
/// per column, every non-null cell a value of it. Decided when the
/// table is built, by [`Table::new`]: the least type every non-null
/// cell coerces to, tried in this order — the lattice boolean <
/// integer < float, then the types of their own, text the top, so
/// no column fails to type.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ColumnType {
    Boolean,
    Integer,
    Float,
    Instant,
    Duration,
    Period,
    Quantity,
    /// A column of node references (spec: The graph as a table):
    /// the `node` column of `@| nodes`, `source` and `target` of
    /// `@| edges`. The cells stay references — node operands inside
    /// the query (`:source:.l`) — and print as the node's path.
    Node,
    Text,
    /// A TUPLE column (spec: The Table, draft 166), declared only:
    /// `key<(int; text)>` holds lists of that arity and those types,
    /// compared item by item, printed in the quarb form; never
    /// inferred, it arises by declaration or as the flattened index.
    Tuple(std::sync::Arc<Vec<ColumnType>>),
    /// A UNIT column (spec: Projectors, the unit trait, ruling
    /// 2026-11-08), declared only: `t<_h>` holds quantities of the
    /// unit's dimension written in the unit — a quantity converted
    /// on the fly, its base value untouched, a bare number or
    /// numeric text minted in the unit; never inferred (a column of
    /// quantities infers `quantity`). The word is the unit with the
    /// underscore a quantity writes, `_h`.
    Unit(std::sync::Arc<str>),
}

impl ColumnType {
    /// The unit a unit column is declared in, `None` for every other
    /// type.
    pub fn unit(&self) -> Option<&str> {
        match self {
            ColumnType::Unit(u) => Some(u),
            _ => None,
        }
    }

    /// The type's word, as `| type` lists it (`(int; text)` for a
    /// tuple).
    pub fn word(&self) -> String {
        match self {
            ColumnType::Boolean => "bool".to_string(),
            ColumnType::Integer => "int".to_string(),
            ColumnType::Float => "float".to_string(),
            ColumnType::Instant => "instant".to_string(),
            ColumnType::Duration => "duration".to_string(),
            ColumnType::Period => "period".to_string(),
            ColumnType::Quantity => "quantity".to_string(),
            ColumnType::Node => "node".to_string(),
            ColumnType::Text => "text".to_string(),
            ColumnType::Unit(u) => format!("_{u}"),
            ColumnType::Tuple(items) => {
                format!(
                    "({})",
                    items
                        .iter()
                        .map(ColumnType::word)
                        .collect::<Vec<_>>()
                        .join("; ")
                )
            }
        }
    }

    /// The type named by its word, as a declared header names it
    /// (`#(--header=@(:age<int>))`); a tuple by its words in
    /// parentheses, `(int; text)`; `None` for no such word.
    pub fn from_word(word: &str) -> Option<ColumnType> {
        // `_h` — the unit trait's word (ruling 2026-11-08): the
        // underscore a quantity writes, then a unit expression; that
        // the unit is one the run knows is the parser's check
        if let Some(u) = word.strip_prefix('_') {
            return unit_shaped(u).then(|| ColumnType::Unit(u.into()));
        }
        if let Some(inner) = word.strip_prefix('(').and_then(|w| w.strip_suffix(')')) {
            let items: Option<Vec<ColumnType>> = inner
                .split([';', ','])
                .map(|w| ColumnType::from_word(w.trim()))
                .collect();
            return items
                .filter(|v| !v.is_empty())
                .map(|v| ColumnType::Tuple(std::sync::Arc::new(v)));
        }
        ColumnType::ORDER.into_iter().find(|t| t.word() == word)
    }

    /// The words, in lattice order, for a refusal to list.
    pub fn words() -> Vec<String> {
        ColumnType::ORDER.iter().map(ColumnType::word).collect()
    }

    const ORDER: [ColumnType; 9] = [
        ColumnType::Boolean,
        ColumnType::Integer,
        ColumnType::Float,
        ColumnType::Instant,
        ColumnType::Duration,
        ColumnType::Period,
        ColumnType::Quantity,
        ColumnType::Node,
        ColumnType::Text,
    ];

    /// The type a value is of, as a column would hold it; `None` on
    /// null.
    pub fn of_value(v: &Value) -> Option<ColumnType> {
        ColumnType::of(v)
    }

    /// The type a stored cell is of (null is of every type).
    fn of(v: &Value) -> Option<ColumnType> {
        Some(match v {
            Value::Null => return None,
            Value::Bool(_) => ColumnType::Boolean,
            Value::Int(_) => ColumnType::Integer,
            Value::Float(_) => ColumnType::Float,
            Value::Instant { .. } => ColumnType::Instant,
            Value::Quantity { base, .. } if base == "s" => ColumnType::Duration,
            Value::Period { .. } => ColumnType::Period,
            Value::Quantity { .. } => ColumnType::Quantity,
            Value::Node(_) => ColumnType::Node,
            _ => ColumnType::Text,
        })
    }
}

/// What a projector's trait brackets say of the field it names
/// (spec: Projectors, draft 166): `<int>` DECLARES the type, the
/// field then fixed to it, a value cast into it or refused; `<*>`
/// declares nothing, and `<*; float>` is the star beside the type a
/// header reports for an undeclared column, a report and no request
/// (ignored where the header is applied).
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Typing {
    Declared(ColumnType),
    Star(Option<ColumnType>),
}

impl Typing {
    /// The brackets' text: `<int>`, `<(int; text)>`, `<*>`, `<*; float>`.
    pub fn spelling(&self) -> String {
        match self {
            Typing::Declared(t) => format!("<{}>", t.word()),
            Typing::Star(None) => "<*>".to_string(),
            Typing::Star(Some(t)) => format!("<*; {}>", t.word()),
        }
    }

    /// The type declared, `None` under the star.
    pub fn declared(&self) -> Option<ColumnType> {
        match self {
            Typing::Declared(t) => Some(t.clone()),
            Typing::Star(_) => None,
        }
    }

    /// The unit a unit trait declares (`<_h>`), `None` under a type
    /// word or the star.
    pub fn unit(&self) -> Option<&str> {
        match self {
            Typing::Declared(ColumnType::Unit(u)) => Some(u),
            _ => None,
        }
    }
}

/// Whether `u` is shaped as a unit expression: a unit letter (or a
/// currency sign) first, then letters, digits and the operators of
/// an expression (`km/h`, `m^2`).
fn unit_shaped(u: &str) -> bool {
    use crate::value::quantity::is_name_char;
    u.chars().next().is_some_and(is_name_char)
        && u.chars()
            .all(|c| is_name_char(c) || c.is_ascii_digit() || matches!(c, '*' | '/' | '^'))
}

/// `v` under the unit trait `<_unit>` (spec: Projectors, the unit
/// trait, ruling 2026-11-08) — convert's rule and the minting of
/// bare numbers: a quantity of the unit's dimension keeps its base
/// value and is written in the unit; a bare number, or numeric text,
/// is read IN the unit; quantity text reads as the quantity it
/// spells; null is null. `None` where the value does not read — a
/// quantity of another dimension (a currency a dimension of its
/// own), text that is neither a number nor a quantity, any other
/// value — and where `unit` names no unit the run knows.
pub(crate) fn cast_unit(v: &Value, unit: &str) -> Option<Value> {
    use crate::value::quantity::{parse_unit_text, scale_by, unscale_by};
    if matches!(v, Value::Null) {
        return Some(Value::Null);
    }
    // spaced text reads no opaque unit: the unit is built in or
    // declared, resolved through the run's resolver as convert's is
    let (factor, base, _, _) = parse_unit_text(&format!("1 {unit}"))?;
    let minted = |n: f64| Value::Quantity {
        value: scale_by(n, factor),
        base: base.clone(),
        written: Some((n, unit.to_string())),
    };
    let converted = |value: f64, held: &str| {
        (held == base).then(|| Value::Quantity {
            value,
            base: base.clone(),
            written: Some((unscale_by(value, factor), unit.to_string())),
        })
    };
    match v {
        Value::Int(n) => Some(minted(*n as f64)),
        Value::Float(x) => Some(minted(*x)),
        Value::Quantity {
            value, base: held, ..
        } => converted(*value, held),
        Value::Str(s) => {
            match crate::value::number::read(s, crate::value::number::Decimal::Point) {
                Some(Value::Int(n)) => Some(minted(n as f64)),
                Some(Value::Float(x)) => Some(minted(x)),
                _ => {
                    let (value, held, _, _) = parse_unit_text(s)?;
                    converted(value, &held)
                }
            }
        }
        _ => None,
    }
}

/// A value's reading under a unit trait in value position (ruling
/// 2026-11-08): [`cast_unit`] with null where the value does not
/// read, a list item by item.
pub(crate) fn unit_reading(v: Value, unit: &str) -> Value {
    match v {
        Value::List(items) => Value::list(
            items
                .iter()
                .map(|i| unit_reading(i.clone(), unit))
                .collect(),
        ),
        other => cast_unit(&other, unit).unwrap_or(Value::Null),
    }
}

/// `v` cast to the declared column type `t`, `None` where it does
/// not cast: the coercion of [`coerce_cell`], a whole-valued float
/// under a declared integer (the cast is lossless), and under a
/// tuple a list of the arity whose items cast each.
pub(crate) fn cast_cell(v: &Value, t: &ColumnType) -> Option<Value> {
    if let ColumnType::Unit(u) = t {
        return cast_unit(v, u);
    }
    if let ColumnType::Tuple(items) = t {
        if matches!(v, Value::Null) {
            return Some(Value::Null);
        }
        let Value::List(cells) = v else { return None };
        if cells.len() != items.len() {
            return None;
        }
        let cast: Option<Vec<Value>> = cells
            .iter()
            .zip(items.iter())
            .map(|(c, ty)| cast_cell(c, ty))
            .collect();
        return cast.map(Value::list);
    }
    coerce_cell(v, t).or_else(|| match (v, t) {
        (Value::Float(f), ColumnType::Integer) if f.fract() == 0.0 && f.abs() < 9.0e15 => {
            Some(Value::Int(*f as i64))
        }
        _ => None,
    })
}

/// The cell as a refusal shows it: a text quoted, the rest in its
/// display form.
pub(crate) fn held_text(c: &Value) -> String {
    match c {
        Value::Str(s) => format!("\"{s}\""),
        other => other.display_form(),
    }
}

/// `v` coerced to the column type `t`, `None` where it has no such
/// reading. Text that reads as a type counts as that type; a
/// boolean reads as 1 and 0 among integers, an integer as a float;
/// every scalar has a text form.
/// A text cell coerced to a column type (spec: The Table): what
/// `coerce_cell` does for a text value, read off the text itself —
/// the one-pass typed build parses a cell from its bytes, no value
/// made first.
pub(crate) fn coerce_text(s: &str, t: &ColumnType) -> Option<Value> {
    use ColumnType as T;
    match t {
        T::Tuple(_) => None,
        T::Unit(u) => cast_unit(&Value::Str(s.to_string()), u),
        T::Boolean => match s {
            "true" => Some(Value::Bool(true)),
            "false" => Some(Value::Bool(false)),
            _ => None,
        },
        T::Integer => match crate::value::number::read(s, crate::value::number::Decimal::Point) {
            Some(n @ Value::Int(_)) => Some(n),
            _ => None,
        },
        T::Float => match crate::value::number::read(s, crate::value::number::Decimal::Point) {
            Some(Value::Int(n)) => Some(Value::Float(n as f64)),
            Some(f @ Value::Float(_)) => Some(f),
            _ => None,
        },
        T::Instant => {
            crate::temporal::parse_iso(s).map(|(secs, nanos, offset_min)| Value::Instant {
                secs,
                nanos,
                offset_min,
                calendar: Default::default(),
            })
        }
        T::Duration => crate::temporal::parse_span(s)
            .map(|(secs, nanos)| Value::seconds(secs, nanos))
            .or_else(|| {
                crate::value::quantity::parse_unit_text(s)
                    .filter(|(_, base, ..)| base == "s")
                    .map(|(value, base, wv, wu)| Value::Quantity {
                        value,
                        base,
                        written: Some((wv, wu)),
                    })
            }),
        T::Period => crate::period::Period::parse(s).map(Value::period),
        T::Quantity => {
            crate::value::quantity::parse_unit_text(s).map(|(value, base, mag, unit)| {
                Value::Quantity {
                    value,
                    base,
                    written: Some((mag, unit)),
                }
            })
        }
        T::Node => None,
        T::Text => Some(Value::Str(s.to_string())),
    }
}

fn coerce_cell(v: &Value, t: &ColumnType) -> Option<Value> {
    use ColumnType as T;
    if matches!(v, Value::Null) {
        return Some(Value::Null);
    }
    if let Value::Str(s) = v {
        return coerce_text(s, t);
    }
    match t {
        // a tuple is cast, never coerced: see `cast_cell`
        T::Tuple(_) => None,
        T::Unit(u) => cast_unit(v, u),
        T::Boolean => match v {
            Value::Bool(_) => Some(v.clone()),
            Value::Str(s) if s == "true" => Some(Value::Bool(true)),
            Value::Str(s) if s == "false" => Some(Value::Bool(false)),
            _ => None,
        },
        T::Integer => match v {
            Value::Bool(b) => Some(Value::Int(i64::from(*b))),
            Value::Int(_) => Some(v.clone()),
            Value::Str(_) => match v.numeric_reading() {
                Some(n @ Value::Int(_)) => Some(n),
                _ => None,
            },
            _ => None,
        },
        T::Float => match v {
            Value::Bool(b) => Some(Value::Float(if *b { 1.0 } else { 0.0 })),
            Value::Int(n) => Some(Value::Float(*n as f64)),
            Value::Float(_) => Some(v.clone()),
            Value::Str(_) => match v.numeric_reading() {
                Some(Value::Int(n)) => Some(Value::Float(n as f64)),
                Some(f @ Value::Float(_)) => Some(f),
                _ => None,
            },
            _ => None,
        },
        T::Instant => match v {
            Value::Instant { .. } => Some(v.clone()),
            Value::Str(s) => {
                crate::temporal::parse_iso(s).map(|(secs, nanos, offset_min)| Value::Instant {
                    secs,
                    nanos,
                    offset_min,
                    calendar: Default::default(),
                })
            }
            _ => None,
        },
        T::Duration => match v {
            q if q.is_duration() => Some(q.clone()),
            Value::Str(s) => crate::temporal::parse_span(s)
                .map(|(secs, nanos)| Value::seconds(secs, nanos))
                .or_else(|| {
                    crate::value::quantity::parse_unit_text(s)
                        .filter(|(_, base, ..)| base == "s")
                        .map(|(value, base, wv, wu)| Value::Quantity {
                            value,
                            base,
                            written: Some((wv, wu)),
                        })
                }),
            _ => None,
        },
        T::Period => match v {
            Value::Period { .. } => Some(v.clone()),
            Value::Str(s) => crate::period::Period::parse(s).map(Value::period),
            _ => None,
        },
        T::Quantity => match v {
            Value::Quantity { .. } => Some(v.clone()),
            Value::Str(s) => {
                crate::value::quantity::parse_unit_text(s).map(|(value, base, mag, unit)| {
                    Value::Quantity {
                        value,
                        base,
                        written: Some((mag, unit)),
                    }
                })
            }
            _ => None,
        },
        // a reference stays one; nothing else is a node
        T::Node => match v {
            Value::Node(_) => Some(v.clone()),
            _ => None,
        },
        T::Text => Some(match v {
            Value::Str(_) => v.clone(),
            other => Value::Str(other.to_string()),
        }),
    }
}

/// The column typed as `type_column` types a vector of cells — the
/// least type in order every non-null cell coerces to, the cells
/// stored coerced — read off the column as held, one cell at a time.
fn type_raw(col: &Column) -> Column {
    let n = col.len();
    'types: for t in ColumnType::ORDER {
        let mut out = Column::Null(0);
        let mut base: Option<String> = None;
        for i in 0..n {
            let Some(v) = coerce_cell(&col.get(i), &t) else {
                continue 'types;
            };
            if t == ColumnType::Quantity
                && let Value::Quantity { base: b, .. } = &v
            {
                match &base {
                    Some(first) if first != b => continue 'types,
                    Some(_) => {}
                    None => base = Some(b.clone()),
                }
            }
            out.push(v);
        }
        return out;
    }
    unreachable!("text is the top: every scalar has a text form")
}

/// One column typed: the first type of the order every non-null
/// cell coerces to, and the cells coerced. A quantity column is of
/// one dimension; cells of several fall through to text. An
/// all-null column is text.
pub(crate) fn type_column(cells: Vec<Value>) -> (ColumnType, Vec<Value>) {
    for t in ColumnType::ORDER {
        let coerced: Option<Vec<Value>> = cells.iter().map(|c| coerce_cell(c, &t)).collect();
        let Some(coerced) = coerced else { continue };
        if t == ColumnType::Quantity {
            let mut bases = coerced.iter().filter_map(|c| match c {
                Value::Quantity { base, .. } => Some(base.as_str()),
                _ => None,
            });
            if let Some(first) = bases.next()
                && bases.any(|b| b != first)
            {
                continue;
            }
        }
        return (t, coerced);
    }
    unreachable!("text is the top: every scalar has a text form")
}

/// One row of a table, read by position (the columnar round,
/// 2026-11-06): a view, its cells made on read, so a row costs
/// nothing to hand out whatever the table's storage.
#[derive(Clone, Copy)]
pub struct Row<'a> {
    table: &'a Table,
    i: usize,
}

impl<'a> Row<'a> {
    /// The cell in column `j`, null past the row's end.
    pub fn get(&self, j: usize) -> Value {
        self.table.cell(self.i, j)
    }

    /// The row's position (0-based).
    pub fn index(&self) -> usize {
        self.i
    }

    /// The cells of the row, as many as the table is wide.
    pub fn cells(&self) -> Vec<Value> {
        (0..self.table.width()).map(|j| self.get(j)).collect()
    }

    /// The row's cells in order.
    pub fn iter(&self) -> impl Iterator<Item = Value> + use<'a> {
        let (t, i) = (self.table, self.i);
        (0..t.width()).map(move |j| t.cell(i, j))
    }

    pub fn len(&self) -> usize {
        self.table.width()
    }

    pub fn is_empty(&self) -> bool {
        self.table.width() == 0
    }
}

impl Table {
    /// A table assembled from its parts as given — the cells kept
    /// as they are, no typing pass (the builders that carry a
    /// table's own cells and declarations over to a new shape).
    pub fn assemble(
        header: Option<Vec<String>>,
        rows: Vec<Vec<Value>>,
        declared: Vec<Option<ColumnType>>,
        index: usize,
        name: Option<String>,
    ) -> Table {
        let w = match &header {
            Some(h) => h.len(),
            None => rows.first().map_or(0, Vec::len),
        };
        let mut columns = vec![Column::Null(0); w];
        let mut n = 0;
        for row in rows {
            let mut cells = row.into_iter();
            for col in columns.iter_mut() {
                col.push(cells.next().unwrap_or(Value::Null));
            }
            n += 1;
        }
        Table {
            header,
            columns,
            n,
            declared,
            index,
            name,
        }
    }

    /// How many rows the table holds.
    pub fn n_rows(&self) -> usize {
        self.n
    }

    /// The cell at row `i`, column `j` (0-based), null where the
    /// table has none.
    pub fn cell(&self, i: usize, j: usize) -> Value {
        self.columns.get(j).map_or(Value::Null, |c| c.get(i))
    }

    /// The rows in order, each a view.
    pub fn rows(&self) -> impl Iterator<Item = Row<'_>> + '_ {
        (0..self.n_rows()).map(move |i| Row { table: self, i })
    }

    /// Row `i` (0-based) as a view, `None` past the end.
    pub fn row_at(&self, i: usize) -> Option<Row<'_>> {
        (i < self.n_rows()).then_some(Row { table: self, i })
    }

    /// Row `i`'s cells, owned, as many as the table is wide.
    pub fn row_cells(&self, i: usize) -> Vec<Value> {
        self.row_at(i).map(|r| r.cells()).unwrap_or_default()
    }

    /// Every row's cells, owned: the row-form copy of the table.
    pub fn rows_vec(&self) -> Vec<Vec<Value>> {
        self.rows().map(|r| r.cells()).collect()
    }

    /// The rows at `idx`, in that order, under the same header,
    /// declarations, index and name: a gather per column. A selection
    /// of rows keeps every column's type (ruling 2026-11-06): the
    /// typing pass ran when the table was built, and runs again only
    /// under `autocast`.
    pub fn take_rows(&self, idx: &[usize]) -> Table {
        Table {
            header: self.header.clone(),
            columns: self.columns.iter().map(|c| c.take(idx)).collect(),
            n: idx.len(),
            declared: self.declared.clone(),
            index: self.index,
            name: self.name.clone(),
        }
    }

    /// Rows kept from this table, in row form, under the same header,
    /// declarations, index and name, the columns' types kept (ruling
    /// 2026-11-06): the row-selecting commands' rebuild.
    pub fn keep_rows(&self, rows: Vec<Vec<Value>>) -> Table {
        Table::assemble(
            self.header.clone(),
            rows,
            self.declared.clone(),
            self.index,
            self.name.clone(),
        )
    }

    /// `-c|--cast=:col<type>` (ruling 2026-11-06): the named columns
    /// declared and their cells cast into the declaration, as
    /// `map(<type>; --to=:col)` casts them after the build; a cell
    /// that does not cast refuses naming the column and the row.
    pub fn cast_columns(&self, casts: &[(String, ColumnType)]) -> Result<Table, String> {
        let mut t = self.clone();
        for (name, ty) in casts {
            let Some(j) = (0..t.width()).find(|&j| t.column_name(j) == *name) else {
                return Err(format!(
                    "--cast names column '{name}', and the table has no such column (its columns: {})",
                    (0..t.width())
                        .map(|j| t.column_name(j))
                        .collect::<Vec<_>>()
                        .join(", ")
                ));
            };
            let mut b = ColumnBuilder::new(0, Some(ty.clone()));
            for i in 0..t.n {
                b.push(t.columns[j].get(i));
            }
            match b.finish() {
                Ok(col) => t.columns[j] = col,
                Err((i, held)) => {
                    return Err(format!(
                        "column '{name}' is declared {}, and row {} holds {held}, which does not cast to it",
                        ty.word(),
                        i + 1
                    ));
                }
            }
            if t.declared.len() < t.width() {
                t.declared.resize(t.width(), None);
            }
            t.declared[j] = Some(ty.clone());
        }
        Ok(t)
    }

    /// A column prepended to the table as it stands — `autoindex`'s
    /// labels, `-a`'s positions — the other columns untouched (an index
    /// the table had becomes a plain column, as before: the caller sets
    /// the index), the new column declared as `declared` says.
    pub fn prepend_column(
        &self,
        name: String,
        cells: Vec<Value>,
        declared: Option<ColumnType>,
    ) -> Table {
        let mut col = Column::Null(0);
        for c in cells {
            col.push(c);
        }
        let mut columns = Vec::with_capacity(self.columns.len() + 1);
        columns.push(col);
        columns.extend(self.columns.iter().cloned());
        let mut header: Vec<String> = Vec::with_capacity(columns.len());
        header.push(name);
        header.extend((0..self.width()).map(|j| self.column_name(j)));
        let mut decl: Vec<Option<ColumnType>> = Vec::with_capacity(columns.len());
        decl.push(declared);
        decl.extend((0..self.width()).map(|j| self.declaration(j)));
        if decl.iter().all(Option::is_none) {
            decl.clear();
        }
        Table {
            header: Some(header),
            columns,
            n: self.n,
            declared: decl,
            index: 0,
            name: self.name.clone(),
        }
    }

    /// `autocast` (ruling 2026-11-06): the undeclared columns typed
    /// again from the cells present, by the rule of the build — every
    /// one, or those at `only`; a declared column stays as declared,
    /// a column of projectors stays.
    pub fn autocast(&self, only: Option<&[usize]>) -> Table {
        let mut t = self.clone();
        for j in 0..t.columns.len() {
            if only.is_some_and(|o| !o.contains(&j))
                || t.declaration(j).is_some()
                || t.columns[j].any_cell(|c| matches!(c, Value::Projection { .. }))
            {
                continue;
            }
            t.columns[j] = type_raw(&t.columns[j]);
        }
        t
    }

    /// Column `j`'s cells, owned, one per row.
    pub fn column_cells(&self, j: usize) -> Vec<Value> {
        self.columns
            .get(j)
            .map_or_else(|| vec![Value::Null; self.n], Column::to_values)
    }
}

impl Table {
    /// A table built from its header and rows, the columns typed
    /// (spec: The Table): each column takes the least type every
    /// non-null cell coerces to, and its cells are stored coerced,
    /// so a column of digit strings is an integer column that
    /// prints its numbers bare. The rows are expected flat and of
    /// one width; the one routine every builder of a table calls.
    /// Every column is undeclared.
    pub fn new(header: Option<Vec<String>>, rows: Vec<Vec<Value>>) -> Table {
        Table::typed(header, rows, Vec::new())
            .unwrap_or_else(|_| unreachable!("no column is declared"))
    }

    /// A table built under a declared header (spec: The Table,
    /// `#(--header=@(:a<int>; :b))`): a column declared with a type
    /// has every cell cast to it, and a cell that does not cast
    /// refuses the build naming the column and the first offending
    /// row; a column declared without a type is typed as `new` types
    /// it. The rows are expected flat and of the header's width.
    pub fn declared(
        header: Vec<(String, Option<ColumnType>)>,
        rows: Vec<Vec<Value>>,
    ) -> Result<Table, String> {
        let names: Vec<String> = header.iter().map(|(n, _)| n.clone()).collect();
        let declared: Vec<Option<ColumnType>> = header.iter().map(|(_, t)| t.clone()).collect();
        Table::typed(Some(names), rows, declared)
    }

    /// The one builder (spec: The Table, "Columns", draft 166): the
    /// header, the rows, and the declaration per column (`declared`
    /// shorter than the width is padded with undeclared columns).
    /// A declared column has every cell cast into its type, a cell
    /// that does not cast refusing by column and row; an undeclared
    /// column takes the least type its cells coerce to. Rows
    /// shorter than the width are null-padded.
    pub fn typed(
        header: Option<Vec<String>>,
        rows: Vec<Vec<Value>>,
        mut declared: Vec<Option<ColumnType>>,
    ) -> Result<Table, String> {
        let w = match &header {
            Some(h) => h.len(),
            None => rows.first().map_or(0, Vec::len),
        };
        declared.resize(w, None);
        if declared.iter().all(Option::is_none) {
            declared.clear();
        }
        let mut b = TableBuilder::shaped(header, declared);
        for row in rows {
            b.push_row(row);
        }
        b.finish()
    }

    /// The typing pass over the columns as held (spec: The Table):
    /// a declared column casts every cell to its declaration or
    /// refuses naming the row; a column of projectors stays; any
    /// other column takes the least type every non-null cell
    /// coerces to, its cells stored coerced.
    pub(crate) fn retyped(mut self) -> Result<Table, String> {
        if self.n == 0 {
            return Ok(self);
        }
        for j in 0..self.columns.len() {
            let coerced = match self.declared.get(j).cloned().flatten() {
                Some(ty) => {
                    let mut out = Column::Null(0);
                    for i in 0..self.n {
                        let c = self.columns[j].get(i);
                        match cast_cell(&c, &ty) {
                            Some(v) => out.push(v),
                            None => {
                                return Err(format!(
                                    "column '{}' is declared {}, and row {} holds {}, which does not cast to it",
                                    self.column_name(j),
                                    ty.word(),
                                    i + 1,
                                    held_text(&c),
                                ));
                            }
                        }
                    }
                    out
                }
                // a column of projectors is a projector table's (held,
                // read where it is applied): its cells stay projectors
                None if self.columns[j].any_cell(|c| matches!(c, Value::Projection { .. })) => {
                    continue;
                }
                None => type_raw(&self.columns[j]),
            };
            self.columns[j] = coerced;
        }
        Ok(self)
    }

    /// The table with new rows under the same header and the same
    /// declarations (spec: The Table, "Columns"): what every command
    /// that keeps the columns and changes the cells rebuilds through
    /// — a declared column casts the new cells or refuses naming it,
    /// an undeclared one re-types by its cells.
    pub fn rebuild(&self, rows: Vec<Vec<Value>>) -> Result<Table, String> {
        Table::typed(self.header.clone(), rows, self.declared.clone())
            .map(|t| t.with_index(self.index).with_name(self.name.clone()))
    }

    /// The table with `n` leading columns as its index (0 none).
    pub fn with_index(mut self, n: usize) -> Table {
        self.index = n.min(self.width());
        self
    }

    /// `| #` with no option: the index role dropped.
    pub fn drop_index(self) -> Table {
        self.with_index(0)
    }

    /// The table indexed by the named column (spec: The Table, "The
    /// index"): the column moved first, declared where the projector
    /// declares it, and marked the index; a name the table lacks
    /// refuses. On the array face the name is a position.
    pub fn indexed_by(&self, name: &str, ty: Option<ColumnType>) -> Result<Table, String> {
        self.indexed_by_levels(&[(name.to_string(), ty)])
    }

    /// The table indexed by several columns, the levels of a
    /// composite index outer first (spec: The Table, "The index"):
    /// the columns moved first in that order, each declared where its
    /// projector declares it, and marked the index.
    pub fn indexed_by_levels(
        &self,
        levels: &[(String, Option<ColumnType>)],
    ) -> Result<Table, String> {
        let w = self.width();
        let mut order: Vec<usize> = Vec::with_capacity(w);
        for (name, _) in levels {
            let j = match &self.header {
                Some(h) => h.iter().position(|c| c == name),
                None => None,
            }
            .or_else(|| name.parse::<usize>().ok().filter(|j| *j >= 1 && *j <= w).map(|j| j - 1))
            .ok_or_else(|| {
                format!(
                    "--index names column '{name}', and the table has no such column (its columns: {})",
                    (0..w).map(|j| self.column_name(j)).collect::<Vec<_>>().join(", ")
                )
            })?;
            if order.contains(&j) {
                return Err(format!("--index names column '{name}' twice"));
            }
            order.push(j);
        }
        let n = order.len();
        let chosen = order.clone();
        order.extend((0..w).filter(|k| !chosen.contains(k)));
        let header = self
            .header
            .as_ref()
            .map(|h| order.iter().map(|k| h[*k].clone()).collect());
        let mut declared: Vec<Option<ColumnType>> =
            order.iter().map(|k| self.declaration(*k)).collect();
        for (i, (_, ty)) in levels.iter().enumerate() {
            if ty.is_some() {
                declared[i] = ty.clone();
            }
        }
        let rows = self
            .rows()
            .map(|r| order.iter().map(|k| r.get(*k)).collect())
            .collect();
        Ok(Table::typed(header, rows, declared)?.with_index(n))
    }

    /// The labels (`:::index`): the index column's cells, or under a
    /// composite index the record of each row's levels keyed by the
    /// level names; `None` on a table with no index.
    pub fn labels(&self) -> Option<Vec<Value>> {
        if self.index == 0 {
            return None;
        }
        if self.index == 1 {
            return Some(self.rows().map(|r| r.get(0)).collect());
        }
        let names: Vec<String> = (0..self.index).map(|j| self.column_name(j)).collect();
        Some(
            self.rows()
                .map(|r| {
                    Value::record(
                        names
                            .iter()
                            .enumerate()
                            .map(|(j, n)| (n.clone(), r.get(j)))
                            .collect(),
                    )
                })
                .collect(),
        )
    }

    /// A row's label as one name: the levels joined by `:` (a header
    /// path), one level its text.
    pub fn label_name(&self, row: &[Value]) -> String {
        row[..self.index]
            .iter()
            .map(Record::key_text)
            .collect::<Vec<_>>()
            .join(":")
    }

    /// The level names of the index, outer first.
    pub fn level_names(&self) -> Vec<String> {
        (0..self.index).map(|j| self.column_name(j)).collect()
    }

    /// The rows whose leading levels equal `levels`, each compared
    /// as a value against its column's type.
    pub fn rows_at_levels(&self, levels: &[Value]) -> Vec<usize> {
        let types = self.types();
        let wanted: Vec<Value> = levels
            .iter()
            .enumerate()
            .map(|(j, l)| match types.get(j) {
                Some(t) => cast_cell(l, t).unwrap_or_else(|| l.clone()),
                None => l.clone(),
            })
            .collect();
        self.rows()
            .enumerate()
            .filter(|(_, r)| wanted.iter().enumerate().all(|(j, w)| r.get(j) == *w))
            .map(|(i, _)| i)
            .collect()
    }

    /// The columns under the outer name `prefix` of a header with
    /// levels (spec: The Table, "Levels of the header"): `t:bar` on a
    /// header `bar:A`, `bar:B`, `baz:A` is the table of `A` and `B`
    /// under the index; `None` where no column stands under the name.
    pub fn sub_columns(&self, prefix: &str) -> Option<Table> {
        let h = self.header.as_ref()?;
        let lead = format!("{prefix}:");
        let under: Vec<usize> = (self.index..self.width())
            .filter(|&j| h[j].starts_with(&lead))
            .collect();
        if under.is_empty() {
            return None;
        }
        let order: Vec<usize> = (0..self.index).chain(under.iter().copied()).collect();
        let header: Vec<String> = order
            .iter()
            .map(|&j| {
                if j < self.index {
                    h[j].clone()
                } else {
                    h[j][lead.len()..].to_string()
                }
            })
            .collect();
        let declared: Vec<Option<ColumnType>> =
            order.iter().map(|&j| self.declaration(j)).collect();
        let rows: Vec<Vec<Value>> = self
            .rows()
            .map(|r| order.iter().map(|&j| r.get(j)).collect())
            .collect();
        Some(
            Table::typed(Some(header), rows, declared)
                .unwrap_or_else(|_| Table::new(None, Vec::new()))
                .with_index(self.index),
        )
    }

    /// Whether the header has levels: a column name with a colon.
    pub fn header_has_levels(&self) -> bool {
        self.header
            .as_ref()
            .is_some_and(|h| h[self.index..].iter().any(|n| n.contains(':')))
    }

    /// `stack` (spec: The Table, "Levels of the header"): the innermost
    /// level of the header moved into the index. A flat header makes a
    /// one-column table, `value`, indexed by the labels and the column
    /// name under `variable`; a header with levels keeps its outer
    /// levels as columns. Refused where the table has no index.
    pub fn stacked(&self) -> Result<Table, String> {
        if self.index == 0 {
            return Err("stack moves the header's innermost level into the index, and the table has no index: name one with #(-i=:col)".into());
        }
        let h = self
            .header
            .clone()
            .unwrap_or_else(|| (1..=self.width()).map(|j| j.to_string()).collect());
        let data: Vec<usize> = (self.index..self.width()).collect();
        // the innermost level of each data column's name, and what
        // stands before it
        let split = |name: &str| -> (Option<String>, String) {
            match name.rsplit_once(':') {
                Some((outer, inner)) => (Some(outer.to_string()), inner.to_string()),
                None => (None, name.to_string()),
            }
        };
        let mut inner_values: Vec<String> = Vec::new();
        let mut outers: Vec<Option<String>> = Vec::new();
        for &j in &data {
            let (outer, inner) = split(&h[j]);
            if !inner_values.contains(&inner) {
                inner_values.push(inner);
            }
            if !outers.contains(&outer) {
                outers.push(outer);
            }
        }
        let mut header: Vec<String> = h[..self.index].to_vec();
        header.push("variable".to_string());
        let new_cols: Vec<Option<String>> = outers.clone();
        header.extend(
            new_cols
                .iter()
                .map(|o| o.clone().unwrap_or_else(|| "value".to_string())),
        );
        let mut rows: Vec<Vec<Value>> = Vec::new();
        for r in self.rows() {
            for inner in &inner_values {
                let mut row: Vec<Value> = (0..self.index).map(|j| r.get(j)).collect();
                row.push(Value::Str(inner.clone()));
                for outer in &new_cols {
                    let name = match outer {
                        Some(o) => format!("{o}:{inner}"),
                        None => inner.clone(),
                    };
                    let cell = h
                        .iter()
                        .position(|n| *n == name)
                        .map(|j| r.get(j))
                        .unwrap_or(Value::Null);
                    row.push(cell);
                }
                rows.push(row);
            }
        }
        Ok(Table::new(Some(header), rows).with_index(self.index + 1))
    }

    /// `unstack`: the innermost level of the index moved into the
    /// header. With one data column the new columns are the level's
    /// values; with several, paths `column:value`. Refused where the
    /// index has no level to move.
    pub fn unstacked(&self) -> Result<Table, String> {
        if self.index == 0 {
            return Err("unstack moves the index's innermost level into the header, and the table has no index level to move".into());
        }
        let h = self
            .header
            .clone()
            .unwrap_or_else(|| (1..=self.width()).map(|j| j.to_string()).collect());
        let k = self.index - 1;
        let data: Vec<usize> = (self.index..self.width()).collect();
        let mut values: Vec<Value> = Vec::new();
        for r in self.rows() {
            let v = r.get(k);
            if !values.contains(&v) {
                values.push(v);
            }
        }
        // a label standing on several rows has no one cell to put
        // under its column: refused naming it, as a column read is
        // (ruling 2026-11-05)
        let mut seen: Vec<Vec<Value>> = Vec::with_capacity(self.n_rows());
        for r in self.rows() {
            let key: Vec<Value> = (0..self.index).map(|j| r.get(j)).collect();
            if seen.contains(&key) {
                return Err(format!(
                    "the label {} stands on several rows, so it has no one cell to put under its column: aggregate the rows first (| mean(--by=:col)), or read them with | @",
                    self.label_name(&r.cells())
                ));
            }
            seen.push(key);
        }
        let mut header: Vec<String> = h[..k].to_vec();
        for &j in &data {
            for v in &values {
                header.push(if data.len() == 1 {
                    Record::key_text(v)
                } else {
                    format!("{}:{}", h[j], Record::key_text(v))
                });
            }
        }
        // one row per distinct outer label, in first-met order
        let mut keys: Vec<Vec<Value>> = Vec::new();
        for r in self.rows() {
            let key: Vec<Value> = (0..k).map(|j| r.get(j)).collect();
            if !keys.contains(&key) {
                keys.push(key);
            }
        }
        let rows: Vec<Vec<Value>> = keys
            .iter()
            .map(|key| {
                let mut row = key.clone();
                for &j in &data {
                    for v in &values {
                        let cell = self
                            .rows()
                            .find(|r| (0..k).all(|i| r.get(i) == key[i]) && r.get(k) == *v)
                            .map(|r| r.get(j))
                            .unwrap_or(Value::Null);
                        row.push(cell);
                    }
                }
                row
            })
            .collect();
        Ok(Table::new(Some(header), rows).with_index(k))
    }

    /// The sub-table under the first `k` levels dropped: the rows
    /// given, the leading `k` columns left out, indexed by what
    /// remains.
    pub fn sub_table(&self, rows: &[usize], k: usize) -> Table {
        let header = self.header.as_ref().map(|h| h[k..].to_vec());
        let declared: Vec<Option<ColumnType>> =
            (k..self.width()).map(|j| self.declaration(j)).collect();
        let body: Vec<Vec<Value>> = rows
            .iter()
            .map(|&i| self.row_cells(i)[k..].to_vec())
            .collect();
        Table::typed(header, body, declared)
            .unwrap_or_else(|_| {
                Table::new(
                    self.header.as_ref().map(|h| h[k..].to_vec()),
                    rows.iter()
                        .map(|&i| self.row_cells(i)[k..].to_vec())
                        .collect(),
                )
            })
            .with_index(self.index.saturating_sub(k))
    }

    /// The rows carrying `label`, compared as a value against the
    /// index's type (a text label cast to it where it reads).
    pub fn rows_labelled(&self, label: &Value) -> Vec<usize> {
        let Some(labels) = self.labels() else {
            return Vec::new();
        };
        let ty = self.types().first().cloned();
        let wanted = match ty {
            Some(t) => cast_cell(label, &t).unwrap_or_else(|| label.clone()),
            None => label.clone(),
        };
        labels
            .iter()
            .enumerate()
            .filter(|(_, l)| **l == wanted)
            .map(|(i, _)| i)
            .collect()
    }

    /// A column by name as the table answers it: on an indexed table
    /// the RECORD of the column keyed by the labels (refused where a
    /// label repeats, naming it), on a plain table the list; a name
    /// no column bears is null.
    pub fn column_value(&self, name: &str) -> Result<Value, String> {
        let Some(list) = self.column(name) else {
            // `t:bar` on a header with levels: the columns under the name
            return Ok(self
                .sub_columns(name)
                .map(Value::table)
                .unwrap_or(Value::Null));
        };
        let Some(labels) = self.labels() else {
            return Ok(list);
        };
        let mut seen: Vec<&Value> = Vec::with_capacity(labels.len());
        for l in &labels {
            if seen.contains(&l) {
                return Err(format!(
                    "the label {} stands on several rows, so the column '{name}' is no record keyed by it: read the rows with | @, or look the label up with [[{}]]",
                    l.to_quarb(),
                    l.to_quarb()
                ));
            }
            seen.push(l);
        }
        let cells = list.into_items().unwrap_or_default();
        if self.index == 1 {
            return Ok(Value::Record(Record::keyed(
                labels.into_iter().zip(cells).collect(),
            )));
        }
        // a composite index nests the record level by level
        let levels: Vec<Vec<Value>> = self
            .rows()
            .map(|r| (0..self.index).map(|j| r.get(j)).collect())
            .collect();
        Ok(nest_levels(&levels, &cells, 0))
    }

    /// The table with new rows, infallible: as [`Table::rebuild`],
    /// and where a declared column refuses a cell the columns come
    /// back undeclared (the callers: a filter keeping rows, an
    /// ordering, a walk that cannot change a cell's type).
    pub fn with_rows(&self, rows: Vec<Vec<Value>>) -> Table {
        if self.declared.is_empty() {
            return Table::new(self.header.clone(), rows)
                .with_index(self.index)
                .with_name(self.name.clone());
        }
        match Table::typed(self.header.clone(), rows.clone(), self.declared.clone()) {
            Ok(t) => t.with_index(self.index).with_name(self.name.clone()),
            Err(_) => Table::new(self.header.clone(), rows)
                .with_index(self.index)
                .with_name(self.name.clone()),
        }
    }

    /// The header's name set; `column` and the empty word are none.
    pub fn with_name(mut self, name: Option<String>) -> Table {
        self.name = name.filter(|n| !n.is_empty() && n != "column");
        self
    }

    /// The column's name for a message: the header's, or the
    /// position on the array face.
    pub fn column_name(&self, j: usize) -> String {
        match &self.header {
            Some(h) => h.get(j).cloned().unwrap_or_else(|| (j + 1).to_string()),
            None => (j + 1).to_string(),
        }
    }

    /// The declaration of column `j`: `Some` where it is declared.
    pub fn declaration(&self, j: usize) -> Option<ColumnType> {
        self.declared.get(j).cloned().flatten()
    }

    /// `| header` (spec: The Table, draft 166): the columns as typed
    /// projectors, a declared column with its type (`:A<int>`), an
    /// undeclared one with the star and the type inferred
    /// (`:A<*; float>`); by position on a headerless table
    /// (`:1<int>`). The list is a structured projector: applied to
    /// another table it narrows and casts it.
    pub fn header_projectors(&self) -> Vec<Value> {
        let types = self.types();
        (0..self.width())
            .map(|j| {
                let typing = match self.declaration(j) {
                    Some(t) => Typing::Declared(t),
                    None => Typing::Star(Some(types[j].clone())),
                };
                Value::typed_projection(1, self.column_name(j), Some(typing))
            })
            .collect()
    }

    /// A matrix from rows of one width: every cell coerced TOGETHER
    /// to the least type all of them admit, by the column lattice,
    /// so the array is of one type (spec: Tables and Reshapes,
    /// transpose). The rows are expected of one width.
    pub fn matrix(rows: Vec<Vec<Value>>) -> Table {
        let w = rows.first().map_or(0, Vec::len);
        let cells: Vec<Value> = rows.into_iter().flatten().collect();
        let (_, coerced) = type_column(cells);
        let rows: Vec<Vec<Value>> = if w == 0 {
            Vec::new()
        } else {
            coerced.chunks(w).map(|c| c.to_vec()).collect()
        };
        Table::assemble(None, rows, Vec::new(), 0, None)
    }

    /// The column types, one per column: the type of the cells as
    /// stored (text for a column of nulls).
    pub fn types(&self) -> Vec<ColumnType> {
        (0..self.width())
            .map(|j| {
                // a declared column answers its declaration (a tuple
                // column's cells are lists, which no cell types)
                if let Some(ty) = self.declaration(j) {
                    return ty;
                }
                self.rows()
                    .find_map(|r| ColumnType::of(&r.get(j)))
                    .unwrap_or(ColumnType::Text)
            })
            .collect()
    }

    /// `| types`: the column types as a list of words.
    pub fn types_value(&self) -> Value {
        Value::list(
            self.types()
                .into_iter()
                .map(|t| Value::Str(t.word().to_string()))
                .collect(),
        )
    }

    /// Whether every cell holds a scalar or null — what a table
    /// promises (spec: The Table).
    pub fn is_flat(&self) -> bool {
        self.rows().flat_map(|r| r.iter()).all(|c| {
            !matches!(
                c,
                Value::List(_) | Value::Record(_) | Value::Table(_) | Value::Foreign(_)
            )
        })
    }

    /// The rows as the list of records a frame stands for (positional
    /// lists on the array face).
    pub fn into_records(self) -> Value {
        Value::list(
            (0..self.n)
                .map(|i| {
                    let r = self.row_cells(i);
                    match &self.header {
                        Some(h) => Value::Record(h.iter().cloned().zip(r).collect()),
                        None => Value::list(r),
                    }
                })
                .collect(),
        )
    }

    /// The number of columns: the header's width, else the first
    /// row's (every row is padded or refused to that width).
    pub fn width(&self) -> usize {
        match &self.header {
            Some(h) => h.len(),
            None => self.columns.len(),
        }
    }

    /// `@(rows; columns)`.
    pub fn shape(&self) -> Value {
        Value::list(vec![
            Value::Int(self.n_rows() as i64),
            Value::Int(self.width() as i64),
        ])
    }

    /// The kind, for messages: `a frame 3×2`, `an array 2×2`.
    pub fn kind(&self) -> String {
        format!(
            "{} {}×{}",
            if self.header.is_some() {
                "a frame"
            } else {
                "an array"
            },
            self.n_rows(),
            self.width()
        )
    }

    /// Whether the table is a sample: one column and no header, the
    /// reading a list of values admits, which reads back to it.
    pub fn is_sample(&self) -> bool {
        self.header.is_none() && self.width() == 1
    }

    /// The row reading: a frame's rows as records, an array's as
    /// lists, a sample's as its values.
    pub fn rows_value(&self) -> Value {
        Value::list(self.rows().map(|r| self.row_value(&r.cells())).collect())
    }

    fn row_value(&self, row: &[Value]) -> Value {
        match &self.header {
            Some(h) if self.header_has_levels() => {
                nest_by_levels(h.iter().cloned().zip(row.iter().cloned()).collect())
            }
            Some(h) => Value::Record(h.iter().cloned().zip(row.iter().cloned()).collect()),
            None if self.width() == 1 => row.first().cloned().unwrap_or(Value::Null),
            None => Value::list(row.to_vec()),
        }
    }

    /// The row at `i` (1-based), as the row reading gives it.
    pub fn row(&self, i: usize) -> Option<Value> {
        (i >= 1)
            .then(|| self.row_at(i - 1))
            .flatten()
            .map(|r| self.row_value(&r.cells()))
    }

    /// The column reading: a record of lists, keyed by the header,
    /// or by position (`1`, `2`, …) on the array face; on an indexed
    /// table a record of records, each column keyed by the labels
    /// (the index column itself left out).
    pub fn columns_value(&self) -> Value {
        if self.index > 0 || self.header_has_levels() {
            let fields: Vec<(String, Value)> = (self.index..self.width())
                .map(|j| {
                    let name = self.column_name(j);
                    let v = self
                        .column_value(&name)
                        .unwrap_or_else(|_| self.column_at(j));
                    (name, v)
                })
                .collect();
            return nest_by_levels(fields);
        }
        let cols: Vec<Value> = (0..self.width()).map(|j| self.column_at(j)).collect();
        let keys: Vec<String> = match &self.header {
            Some(h) => h.clone(),
            None => (1..=self.width()).map(|j| j.to_string()).collect(),
        };
        Value::Record(keys.into_iter().zip(cols).collect())
    }

    /// The header as a list of names; null on the array face.
    pub fn header_value(&self) -> Value {
        match &self.header {
            Some(h) => Value::list(h.iter().cloned().map(Value::Str).collect()),
            None => Value::Null,
        }
    }

    /// The rows `a..b` (1-based, inclusive, either end open) as a
    /// table under the same header.
    pub fn slice(&self, a: Option<i64>, b: Option<i64>) -> Table {
        let n = self.n as i64;
        let from = a.unwrap_or(1).clamp(1, n + 1) - 1;
        let to = b.unwrap_or(n).clamp(0, n);
        let (from, to) = if from < to {
            (from as usize, to as usize)
        } else {
            (0, 0)
        };
        Table {
            header: self.header.clone(),
            columns: self.columns.iter().map(|c| c.slice(from, to)).collect(),
            n: to - from,
            declared: self.declared.clone(),
            index: self.index,
            name: self.name.clone(),
        }
    }

    /// The output form: the literal with the header and each row on
    /// a line of its own, so it pastes back as the constructor.
    pub fn to_quarb_lines(&self) -> String {
        let mut parts: Vec<String> = Vec::with_capacity(self.n_rows() + 1);
        if let Some(h) = &self.header {
            let names: Vec<String> = h.iter().map(|k| quarb_key(k)).collect();
            parts.push(format!("@({})", names.join("; ")));
        }
        // a headerless table is the matrix: its rows print as lists
        // (spec: Table Construction, draft 166); a frame's as records
        let sigil = if self.header.is_some() { '%' } else { '@' };
        for r in self.rows() {
            let cells: Vec<String> = r.iter().map(|v| v.to_quarb()).collect();
            parts.push(format!("{sigil}({})", cells.join("; ")));
        }
        if parts.len() <= 1 {
            return format!("#({})", parts.join(""));
        }
        format!("#({})", parts.join(";\n  "))
    }

    fn column_at(&self, j: usize) -> Value {
        Value::list(self.rows().map(|r| r.get(j)).collect())
    }

    /// A column by name, as a list: the header's name on a frame, the
    /// position's text (`"2"`) on the array face, where the positions
    /// are the column names.
    pub fn column(&self, name: &str) -> Option<Value> {
        match &self.header {
            // By name first; a number that names no column is the
            // position (`#*:2`, the second column; spec: Context
            // Accessors).
            Some(h) => h
                .iter()
                .position(|c| c == name)
                .or_else(|| {
                    name.parse::<usize>()
                        .ok()
                        .filter(|&j| j >= 1 && j <= self.width())
                        .map(|j| j - 1)
                })
                .map(|j| self.column_at(j)),
            None => name
                .parse::<usize>()
                .ok()
                .filter(|j| *j >= 1 && *j <= self.width())
                .map(|j| self.column_at(j - 1)),
        }
    }

    /// The rows and columns exchanged: an array's transpose.
    pub fn transposed(&self) -> Table {
        let w = self.width();
        Table::new(
            None,
            (0..w)
                .map(|j| self.rows().map(|r| r.get(j)).collect())
                .collect(),
        )
    }

    /// The literal that reads back: `#(@(name; age); %("Braund";
    /// 22))` for a frame, `#(%(1; 2); %(3; 4))` for an array: every row a
    /// record, the header the one list.
    pub fn to_quarb(&self) -> String {
        let mut parts: Vec<String> = Vec::with_capacity(self.n_rows() + 1);
        if let Some(h) = &self.header {
            let names: Vec<String> = h.iter().map(|k| quarb_key(k)).collect();
            parts.push(format!("@({})", names.join("; ")));
        }
        let sigil = if self.header.is_some() { '%' } else { '@' };
        for r in self.rows() {
            let cells: Vec<String> = r.iter().map(|v| v.to_quarb()).collect();
            parts.push(format!("{sigil}({})", cells.join("; ")));
        }
        format!("#({})", parts.join("; "))
    }
}

/// What a command library implements for the values it keeps in
/// its own form; see [`Value::Foreign`].
pub trait Foreign: Send + Sync {
    /// The kind, for messages: `DataFrame 17×3`, `ndarray (17, 3)
    /// float64`.
    fn kind(&self) -> String;
    /// The object's own text (its display).
    fn display(&self) -> String;
    /// The row reading (`| @`): a frame as a list of records with
    /// its index as the first field, an array as nested lists, a
    /// series as a list. `Err` names why there is none.
    fn rows(&self) -> Result<Value, String>;
    /// The column reading (`| %`): a frame as a record of columns,
    /// each a record keyed by the index; a series on a named index
    /// as one record. `Err` names why there is none (an array has
    /// no names).
    fn columns(&self) -> Result<Value, String>;
    /// The object itself, for the library that made it.
    fn as_any(&self) -> &dyn std::any::Any;
}

/// A shared library value; equal to another only as the same object.
#[derive(Clone)]
pub struct ForeignValue(pub std::sync::Arc<dyn Foreign>);

impl ForeignValue {
    pub fn new(f: impl Foreign + 'static) -> ForeignValue {
        ForeignValue(std::sync::Arc::new(f))
    }

    /// The refusal for a command that has no reading of a library
    /// value, naming the kind and the two exports.
    pub fn refusal(&self, command: &str) -> String {
        format!(
            "{command}: {} is a library value; '| @' exports its rows, '| %' its columns",
            self.0.kind()
        )
    }
}

impl std::ops::Deref for ForeignValue {
    type Target = dyn Foreign;
    fn deref(&self) -> &Self::Target {
        &*self.0
    }
}

impl PartialEq for ForeignValue {
    fn eq(&self, other: &ForeignValue) -> bool {
        std::sync::Arc::ptr_eq(&self.0, &other.0)
    }
}

impl std::fmt::Debug for ForeignValue {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Foreign({})", self.0.kind())
    }
}

impl Value {
    /// A list value from its elements.
    /// A record of text keys from its fields.
    pub fn record(fields: Vec<(String, Value)>) -> Value {
        Value::Record(Record::new(fields))
    }

    /// A projector: the ladder (1 `:`, 2 `::`, 3 `:::`) and
    /// its key.
    pub fn projection(ladder: u8, key: impl Into<String>) -> Value {
        Value::Projection {
            ladder,
            key: key.into(),
            typing: None,
        }
    }

    /// A projector with its trait brackets (spec: Projectors, draft
    /// 166): `:A<int>` declares, `:A<*; float>` reports.
    pub fn typed_projection(ladder: u8, key: impl Into<String>, typing: Option<Typing>) -> Value {
        Value::Projection {
            ladder,
            key: key.into(),
            typing,
        }
    }

    /// A typed projector's declared type: `Some` under `<int>`,
    /// `None` on a bare projector, under the star, and on every
    /// other value.
    pub fn declared_type(&self) -> Option<ColumnType> {
        match self {
            Value::Projection {
                typing: Some(t), ..
            } => t.declared(),
            _ => None,
        }
    }

    /// A quarq from its body (spec: Quarqs): the source is the
    /// body's canonical spelling in `q(…)`; `projector` is the
    /// structure of projectors the body folds to, if it is one.
    pub fn quarq(body: Vec<crate::syntax::ast::Command>, projector: Option<Value>) -> Value {
        let source = crate::syntax::unparse::quarq_source(&body);
        Value::Quarq(Quarq {
            source,
            body: std::sync::Arc::new(body),
            projector: projector.map(Box::new),
            holes: std::sync::Arc::new(Vec::new()),
            form: None,
            at: None,
        })
    }

    /// A quarq standing for one construct exactly (design paper: the
    /// node overwrite, the constructors): its body the commands the
    /// construct reads as after a pipe, its form the construct.
    pub fn quarq_form(form: crate::syntax::expand::Form) -> Value {
        let body = form.as_commands();
        // a construct with no reading after a pipe (a trait block)
        // prints as itself
        let source = if body.is_empty() {
            format!("q({})", form.text())
        } else {
            crate::syntax::unparse::quarq_source(&body)
        };
        Value::Quarq(Quarq {
            source,
            body: std::sync::Arc::new(body),
            projector: None,
            holes: std::sync::Arc::new(Vec::new()),
            form: Some(Box::new(form)),
            at: None,
        })
    }

    /// A quarq template: a body with expansions still to fill.
    pub fn quarq_template(
        body: Vec<crate::syntax::ast::Command>,
        holes: Vec<crate::syntax::ast::Hole>,
    ) -> Value {
        let source = crate::syntax::unparse::quarq_source(&body);
        Value::Quarq(Quarq {
            source,
            body: std::sync::Arc::new(body),
            projector: None,
            holes: std::sync::Arc::new(holes),
            form: None,
            at: None,
        })
    }

    /// Whether a projector stands in the value, at any depth of
    /// lists, records and tables: what the glued colon and the
    /// commands that take a held projector read on their topic.
    pub fn holds_projector(&self) -> bool {
        match self {
            Value::Projection { .. } => true,
            Value::List(items) => items.iter().any(Value::holds_projector),
            Value::Record(fields) => fields.iter().any(|(_, v)| v.holds_projector()),
            Value::Table(t) => t.rows().flat_map(|r| r.iter()).any(|v| v.holds_projector()),
            _ => false,
        }
    }

    /// A projector's spelling, as the projection is written:
    /// the colons and the key, quoted where it is no identifier.
    pub fn projector_spelling(ladder: u8, key: &str, typing: Option<&Typing>) -> String {
        let mut s = Value::projection_spelling(ladder, key);
        if let Some(t) = typing {
            s.push_str(&t.spelling());
        }
        s
    }

    pub fn projection_spelling(ladder: u8, key: &str) -> String {
        // an identifier, a position (`:1`, `::0`), or a path of
        // identifiers (`:bar:A`, a header level) stands bare
        let ident = |k: &str| {
            let mut cs = k.chars();
            (matches!(cs.next(), Some(c) if c.is_alphabetic() || c == '_')
                && cs.all(|c| c.is_alphanumeric() || c == '_' || c == '-'))
                || (!k.is_empty() && k.bytes().all(|b| b.is_ascii_digit()))
        };
        let bare = ident(key) || (key.contains(':') && key.split(':').all(ident));
        let key = if bare {
            key.to_string()
        } else {
            format!("'{}'", key.replace('\\', "\\\\").replace('\'', "\\'"))
        };
        format!("{}{key}", ":".repeat(usize::from(ladder.clamp(1, 3))))
    }

    pub fn list(items: Vec<Value>) -> Value {
        Value::List(std::sync::Arc::new(items))
    }

    /// A table value (shared like a list).
    pub fn table(t: Table) -> Value {
        Value::Table(std::sync::Arc::new(t))
    }

    /// The elements of a list value, taken out of their sharing
    /// (cloned only when another holder remains).
    pub fn into_items(self) -> Option<Vec<Value>> {
        match self {
            Value::List(l) => Some(std::sync::Arc::try_unwrap(l).unwrap_or_else(|a| (*a).clone())),
            _ => None,
        }
    }

    /// A byte count as a typed quantity on the information base —
    /// the mint for every adapter's `size` fact, so `[:::size >
    /// 1GiB]`, `| convert(MB)`, and typed size totals work
    /// uniformly. (Exact up to 2^53 bytes — 8 PiB — beyond which
    /// f64 granularity coarsens; no substrate this engine mounts
    /// reports single objects there.)
    pub fn bytes(n: i64) -> Value {
        // On the information base, the bit (B = 8 b); written as
        // the byte count it is, so a size prints `65 B` and reads
        // beside `200 kB` on one scale.
        Value::Quantity {
            value: n as f64 * 8.0,
            base: "b".to_string(),
            written: Some((n as f64, "B".to_string())),
        }
    }

    /// Truthiness, for predicate coercion: `Null`, `false`, `0`, the
    /// empty string, and the empty list and record are falsy;
    /// everything else is truthy.
    pub fn is_truthy(&self) -> bool {
        match self {
            Value::Null => false,
            Value::Bool(b) => *b,
            Value::Int(n) => *n != 0,
            Value::Float(f) => *f != 0.0,
            Value::Str(s) => !s.is_empty(),
            Value::List(l) => !l.is_empty(),
            Value::Record(o) => !o.is_empty(),
            Value::Table(t) => t.n_rows() != 0,
            Value::Instant { .. } => true,
            Value::Period { .. } => true,
            Value::Quantity { value, .. } => *value != 0.0,
            // No truth value: a predicate on a library value is
            // refused by kind, and false.
            Value::Foreign(f) => {
                crate::value::ambient::record_refusal(f.refusal("a predicate"));
                false
            }
            // A reference names a node: true.
            Value::Node(_) => true,
            Value::Projection { .. } => true,
            Value::Quarq(_) => true,
        }
    }

    /// The *temporal reading* (spec: The Temporal Fragment): the UTC
    /// timeline point a value denotes, if any — an instant itself,
    /// an integer or float read as epoch seconds, or ISO-8601 text.
    /// Booleans, lists, records, durations, and non-ISO text have
    /// none.
    pub fn temporal_reading(&self) -> Option<(i64, u32)> {
        match self {
            Value::Instant { secs, nanos, .. } => Some((*secs, *nanos)),
            // A period reads as its first instant.
            Value::Period { start, .. } => Some((*start, 0)),
            Value::Int(n) => Some((*n, 0)),
            Value::Float(f) if f.is_finite() => {
                let secs = f.floor() as i64;
                let nanos = ((f - f.floor()) * 1e9) as u32;
                Some((secs, nanos))
            }
            Value::Str(s) => crate::temporal::parse_iso(s).map(|(s, n, _)| (s, n)),
            _ => None,
        }
    }

    /// The *calendar reading* (spec: The Calendar Reading): the
    /// period a value denotes, if any — a period itself, ISO-8601
    /// text at reduced precision (or a full instant's text), an
    /// integer (that year), or an instant at the grain it prints
    /// at (the day for a midnight instant with no offset, the
    /// second otherwise).
    pub fn calendar_reading(&self) -> Option<crate::period::Period> {
        use crate::period::Period;
        match self {
            Value::Period {
                start,
                grain,
                calendar,
            } => Some(Period {
                start: *start,
                grain: *grain,
                calendar: *calendar,
            }),
            // an integer is epoch seconds wherever an instant is
            // expected and leaves the calendar coercion; the year
            // is written with its trailing dash, `2025-`
            Value::Int(_) => None,
            Value::Instant {
                secs,
                nanos,
                offset_min,
                calendar,
            } => Some(Period::of_instant(*secs, *nanos, *offset_min).in_calendar(*calendar)),
            Value::Str(s) => year_word(s).or_else(|| Period::parse(s)).or_else(|| {
                crate::temporal::parse_iso(s)
                    .map(|(secs, nanos, off)| Period::of_instant(secs, nanos, off))
            }),
            _ => None,
        }
    }

    /// A period as a value.
    pub fn period(p: crate::period::Period) -> Value {
        Value::Period {
            start: p.start,
            grain: p.grain,
            calendar: p.calendar,
        }
    }

    /// The *unital reading* (spec: The Unital Reading): the
    /// dimensioned magnitude a value denotes, if any — a quantity
    /// itself, or unit text (`5km`, `0.2 kW`) scaled through the
    /// frozen built-in table. Bare numbers read as the *partner's*
    /// base at the comparison site (they carry no dimension of
    /// their own), so they are not read here.
    pub fn unital_reading(&self) -> Option<(f64, String)> {
        match self {
            Value::Quantity { value, base, .. } => Some((*value, base.clone())),
            Value::Str(s) => crate::value::quantity::parse_unit_text(s)
                .map(|(v, base, ..)| (v, base.to_string())),
            _ => None,
        }
    }

    /// The *durational reading* (spec: The Durational Reading): the
    /// span a value denotes, if any — a duration itself, a number
    /// read as seconds, or span text (an ISO-8601 duration or a
    /// systemd time-span like `5d3h5min`). Booleans, lists, records,
    /// instants, and other text have none.
    pub fn durational_reading(&self) -> Option<(i64, u32)> {
        match self {
            Value::Quantity { .. } => self.span_parts(),
            // A bare number is not seconds: time is a dimension like
            // the others (spec: the durational coercion, draft 155).
            // Unit text in a time unit first (`2h` keeps its written
            // unit), then ISO-8601 and the multi-component span text
            Value::Str(s) => crate::value::quantity::parse_unit_text(s)
                .filter(|(_, base, ..)| base == "s")
                .map(|(v, ..)| split_seconds(v))
                .or_else(|| crate::temporal::parse_span(s)),
            _ => None,
        }
    }

    /// A span of time: the quantity of dimension T on the base `s`
    /// (spec: Duration), seconds and nanoseconds in, displayed in
    /// seconds unless a written unit is set.
    pub fn seconds(secs: i64, nanos: u32) -> Value {
        Value::Quantity {
            value: secs as f64 + nanos as f64 / 1e9,
            base: "s".to_string(),
            written: None,
        }
    }

    /// Whether the value is a quantity of time.
    pub fn is_duration(&self) -> bool {
        matches!(self, Value::Quantity { base, .. } if base == "s")
    }

    /// The seconds and nanoseconds of a time quantity.
    pub fn span_parts(&self) -> Option<(i64, u32)> {
        match self {
            Value::Quantity { value, base, .. } if base == "s" && value.is_finite() => {
                Some(split_seconds(*value))
            }
            _ => None,
        }
    }

    /// The Quarb form: the value spelled as Quarb
    /// query text, so a printed result reads back as an expression.
    /// Strings quoted as literals, numbers and booleans bare,
    /// `null`, lists as `@(a; b)`, records as `%(k = v; k2 = v2)`
    /// with bare identifier keys; instants, durations, and
    /// quantities in their written form. This is what `qua` prints
    /// for a record or list result — JSON is `| json` / `--json`.
    pub fn to_quarb(&self) -> String {
        match self {
            Value::Null => "null".to_string(),
            Value::Str(s) => quarb_string(s),
            Value::List(l) => {
                // Two or more records of one shape (the same keys in
                // the same order) print as the record array, the
                // header once; records that differ in shape print
                // record by record, so no sparse grid is shown.
                if let Some(keys) = record_array_keys(l) {
                    let mut parts: Vec<String> = Vec::with_capacity(l.len() + 1);
                    let names: Vec<String> = keys.iter().map(|(k, _)| quarb_key(k)).collect();
                    parts.push(format!("@({})", names.join("; ")));
                    for item in l.iter() {
                        if let Value::Record(o) = item {
                            let cells: Vec<String> = o.iter().map(|(_, v)| v.to_quarb()).collect();
                            parts.push(format!("%({})", cells.join("; ")));
                        }
                    }
                    return format!("@%({})", parts.join("; "));
                }
                let inner: Vec<String> = l.iter().map(Value::to_quarb).collect();
                format!("@({})", inner.join("; "))
            }
            Value::Record(o) => {
                let inner: Vec<String> = o
                    .iter()
                    .enumerate()
                    .map(|(i, (_, v))| format!("{} = {}", o.key_quarb(i), v.to_quarb()))
                    .collect();
                format!("%({})", inner.join("; "))
            }
            Value::Table(t) => t.to_quarb(),
            // A library value has no Quarb form that reads back; its
            // text is the object's own display.
            Value::Projection {
                ladder,
                key,
                typing,
            } => Value::projector_spelling(*ladder, key, typing.as_ref()),
            Value::Quarq(q) => q.source.clone(),
            other => other.to_string(),
        }
    }

    /// What a result line shows: a scalar bare (text unquoted), a
    /// record or list in its Quarb form.
    /// A table a boundary would make implicitly — a library's frame
    /// or two-dimensional array, an adapter's tabular source — as the
    /// engine's value: the table when it is flat, else the list of
    /// records that keeps its shape (spec: The Table). One rule for
    /// every boundary; the explicit constructors (`#(…)`, `| #`)
    /// refuse instead, since the query asked for a table.
    /// The one rule for an implicit table (spec: The Table, the flat
    /// table): flat rows are the table, typed by `Table::new`; rows
    /// with a structured cell (a frame's object column of lists)
    /// keep their shape as a list of records. The flatness is read
    /// off the raw rows: `Table::new` would coerce the lists to text.
    pub fn table_or_records(header: Option<Vec<String>>, rows: Vec<Vec<Value>>) -> Value {
        let raw = Table::assemble(header, rows, Vec::new(), 0, None);
        if raw.is_flat() {
            Value::table(
                raw.retyped()
                    .unwrap_or_else(|_| unreachable!("no column is declared")),
            )
        } else {
            raw.into_records()
        }
    }

    pub fn display_form(&self) -> String {
        match self {
            // a bare null prints as `null` (spec: the default print,
            // draft 166): an empty line is the empty text's, and what
            // a query shows reads back as what it says
            Value::Null => "null".to_string(),
            Value::List(_) | Value::Record(_) => self.to_quarb(),
            Value::Projection {
                ladder,
                key,
                typing,
            } => Value::projector_spelling(*ladder, key, typing.as_ref()),
            Value::Quarq(q) => q.source.clone(),
            Value::Table(t) => t.to_quarb_lines(),
            other => other.to_string(),
        }
    }

    /// Strict-JSON rendering: strings quoted and escaped, numbers and
    /// booleans bare, null literal, lists as arrays, records as
    /// key-ordered JSON objects. This is the `| json` / `| jsonl`
    /// serialization and the `--json` / `--jsonl` output.
    pub fn to_json(&self) -> String {
        match self {
            Value::Null => "null".to_string(),
            Value::Bool(b) => b.to_string(),
            Value::Int(n) => n.to_string(),
            Value::Float(f) if f.is_finite() => format_float(*f),
            // JSON has no spelling for infinity or NaN.
            Value::Float(_) => "null".to_string(),
            Value::Str(s) => json_string(s),
            Value::List(l) => {
                let inner: Vec<String> = l.iter().map(Value::to_json).collect();
                format!("[{}]", inner.join(", "))
            }
            Value::Record(o) => {
                let inner: Vec<String> = o
                    .iter()
                    .map(|(k, v)| format!("{}: {}", json_string(k), v.to_json()))
                    .collect();
                format!("{{{}}}", inner.join(", "))
            }
            Value::Instant { .. } | Value::Period { .. } | Value::Quantity { .. } => {
                json_string(&self.to_string())
            }
            // The row reading, serialized.
            Value::Table(t) => t.rows_value().to_json(),
            // The row reading, serialized; its text where the object
            // has no rows.
            Value::Foreign(f) => match f.rows() {
                Ok(rows) => rows.to_json(),
                Err(_) => json_string(&f.display()),
            },
            // The locator text: no JSON form keeps nodeness.
            Value::Node(n) => json_string(&n.locator),
            Value::Projection {
                ladder,
                key,
                typing,
            } => json_string(&Value::projector_spelling(*ladder, key, typing.as_ref())),
            // The source text: no JSON form keeps a quarq.
            Value::Quarq(q) => json_string(&q.source),
        }
    }

    /// The numeric value, for numeric comparison and aggregation.
    /// `Int` and `Float` coerce, and so does a string that parses as a
    /// finite number\,---\,without which numeric work would silently
    /// fail over text adapters, where every value is a string (an HTML
    /// attribute like `rank="3"`, a CSV cell). Non-numeric strings,
    /// booleans, lists, and null do not coerce.
    /// The key under which a value may be indexed for equality
    /// (`=`, the value match `=>`): two values with keys compare
    /// equal only if their keys are equal — the numeric reading
    /// when there is one (so `1`, `1.0` and `"1"` share a key, as
    /// they compare equal), else the text, booleans and null apart.
    /// `None` for values compared under another reading (instants,
    /// durations, quantities, lists, records): a search for one, or
    /// among them, takes the scan.
    pub fn equality_key(&self) -> Option<String> {
        match self {
            Value::Int(_) | Value::Float(_) | Value::Str(_) => Some(match self.numeric_reading() {
                // An integer keys as itself (exact past 2^53); a
                // whole double keys as that integer, so `1`, `1.0`
                // and `"1"` still share a key, and -0.0 is 0.
                Some(Value::Int(n)) => format!("n:{n}"),
                Some(Value::Float(f)) if f.fract() == 0.0 && f.abs() < 9.2e18 => {
                    format!("n:{}", f as i64)
                }
                Some(Value::Float(f)) => format!("n:{f}"),
                _ => format!("s:{self}"),
            }),
            Value::Bool(b) => Some(format!("b:{b}")),
            Value::Null => Some("0:".to_string()),
            Value::Node(n) => Some(format!("node:{}", n.id)),
            // a projection coerces to text as its bare key
            Value::Projection { key, .. } => Some(format!("s:{key}")),
            Value::Quarq(q) => Some(format!("q:{}", q.source)),
            _ => None,
        }
    }

    pub fn numeric(&self) -> Option<f64> {
        match self {
            Value::Int(n) => Some(*n as f64),
            Value::Float(f) => Some(*f),
            Value::Str(s) => crate::value::number::read(s, crate::value::number::Decimal::Point)
                .and_then(|v| v.numeric()),
            // A quantity's base magnitude, so aggregates work
            // (`::power @| sum` sums watts). Arithmetic never sees
            // this: the quantital fragment intercepts first.
            Value::Quantity { value, .. } => Some(*value),
            _ => None,
        }
    }

    /// The *numeric reading* (spec: The Numeric Fragment) — like
    /// [`Value::numeric`], but type-preserving: text with integer
    /// form reads as an exact `Int`, so arithmetic over text-sourced
    /// values stays exact. At most one reading exists; booleans,
    /// lists, and null have none.
    pub fn numeric_reading(&self) -> Option<Value> {
        match self {
            Value::Int(n) => Some(Value::Int(*n)),
            Value::Float(f) => Some(Value::Float(*f)),
            // The canonical form, and under the default convention
            // grouped thousands (`1,234`, `1 234`); a source that
            // writes decimal commas declares it (`?decimal=comma`)
            // and its text arrives in canonical form.
            Value::Str(s) => crate::value::number::read(s, crate::value::number::Decimal::Point),
            _ => None,
        }
    }

    /// A total order for sorting — transitive by construction, via
    /// a per-value canonical key (see [`SortKey`]): null, then
    /// booleans, then the *magnitude lines* (numbers and instants
    /// as epoch seconds on the dimensionless line, durations as
    /// seconds on the line of `T`, quantities on their dimension's
    /// line by base magnitude, and text through its one reading —
    /// the text readings are disjoint by grammar), then readingless
    /// text, then lists and records by display form. Values meeting
    /// on one line compare by magnitude alone, so `PT1M` and `60_s`
    /// are equal, `1_km` and `1000_m` too; `60` is on another line
    /// (spec: Relations, draft 155), so `group` and `unique` keep
    /// "£30" and "30" apart.
    ///
    /// Ordering contexts with an adapter at hand should call
    /// [`Value::compare_with`] so mounted custom units read; this
    /// wrapper uses the frozen built-in table.
    pub fn compare(&self, other: &Value) -> std::cmp::Ordering {
        self.compare_with(other, &crate::value::quantity::scale_expr)
    }

    /// [`Value::compare`] with an explicit unit-expression resolver
    /// (the adapter's `unit_scale`), so custom-unit text takes its
    /// place on the magnitude line exactly as it does in criteria.
    pub fn compare_with(
        &self,
        other: &Value,
        scale: &dyn Fn(&str) -> Option<(f64, String)>,
    ) -> std::cmp::Ordering {
        sort_key(self, scale).cmp_key(&sort_key(other, scale))
    }

    /// The value's sort key under an explicit unit resolver — the
    /// hashable form of [`Value::compare_with`]'s equality, for the
    /// aggregates that partition by key.
    pub(crate) fn sort_key_with(&self, scale: &dyn Fn(&str) -> Option<(f64, String)>) -> SortKey {
        sort_key(self, scale)
    }
}

/// The canonical sort key behind [`Value::compare`]: every value
/// maps to exactly one class, so the order is total and transitive
/// where the old pairwise fragment activation was not (`10 < "1z" <
/// "9" < 10` cycled through the string fallback).
///
/// Equality and hashing agree with `cmp_key` exactly (a magnitude
/// hashes by its bit pattern, which is `total_cmp` equality), so
/// a `HashMap` keyed on sort keys partitions the same way the
/// pairwise comparison does — `group` and `unique_by` look a key
/// up in one probe instead of scanning every group formed so far.
#[derive(Debug, Clone)]
pub(crate) enum SortKey {
    Null,
    Bool(bool),
    /// The magnitude lines, one per dimension: everything with a
    /// numeric, temporal, durational, or unital reading, by its
    /// dimension (`""` for numbers and instants, `T` for durations
    /// and spans, the unit's dimension for a quantity; spec:
    /// Relations) and then by the reading's magnitude — and, where
    /// the magnitude is a whole number, the integer itself, so two
    /// 64-bit integers a double cannot tell apart still order and
    /// key exactly. Lines of different dimensions never meet: a
    /// quantity is equal, and ordered, only to one of its own
    /// dimension, and never to a bare number.
    Line(f64, i64, String),
    /// A period: by its start, the coarser first where two start
    /// together.
    Period(i64, u8),
    /// Text with no reading, by codepoint order.
    Text(String),
    /// Lists then records order after scalars, by display form.
    ListText(String),
    RecordText(String),
}

impl PartialEq for SortKey {
    fn eq(&self, other: &SortKey) -> bool {
        self.cmp_key(other) == std::cmp::Ordering::Equal
    }
}

impl Eq for SortKey {}

impl std::hash::Hash for SortKey {
    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
        self.rank().hash(state);
        match self {
            SortKey::Null => {}
            SortKey::Bool(b) => b.hash(state),
            SortKey::Line(f, i, dim) => {
                dim.hash(state);
                // -0.0 and 0.0 are one point of the line.
                (if *f == 0.0 { 0.0f64 } else { *f }).to_bits().hash(state);
                i.hash(state);
            }
            SortKey::Period(start, grain) => {
                start.hash(state);
                grain.hash(state);
            }
            SortKey::Text(s) | SortKey::ListText(s) | SortKey::RecordText(s) => s.hash(state),
        }
    }
}

impl SortKey {
    /// A point of the dimensionless line from a double: a whole
    /// number in range carries its integer, anything else zero.
    fn line(f: f64) -> SortKey {
        SortKey::line_of(f, String::new())
    }

    /// A point of the line of dimension `dim`.
    fn line_of(f: f64, dim: String) -> SortKey {
        let whole = f.fract() == 0.0 && f.abs() < 9.2e18;
        SortKey::Line(f, if whole { f as i64 } else { 0 }, dim)
    }

    fn rank(&self) -> u8 {
        match self {
            SortKey::Null => 0,
            SortKey::Bool(_) => 1,
            SortKey::Line(..) => 2,
            SortKey::Period(..) => 3,
            SortKey::Text(_) => 4,
            SortKey::ListText(_) => 5,
            SortKey::RecordText(_) => 6,
        }
    }

    pub(crate) fn cmp_key(&self, other: &SortKey) -> std::cmp::Ordering {
        use SortKey::*;
        match (self, other) {
            (Bool(a), Bool(b)) => a.cmp(b),
            // NaN (mintable by query arithmetic) orders after every
            // other number, whichever sign bit it carries (`0 div 0`
            // mints a negative NaN, which `total_cmp` alone would
            // put before -inf); two NaNs are equal.
            // The dimensionless line first, then the dimensions in
            // text order; magnitudes meet only within one line.
            (Line(a, i, da), Line(b, j, db)) => {
                da.cmp(db).then_with(|| match (a.is_nan(), b.is_nan()) {
                    (true, true) => i.cmp(j),
                    (true, false) => std::cmp::Ordering::Greater,
                    (false, true) => std::cmp::Ordering::Less,
                    (false, false) => {
                        if *a == 0.0 && *b == 0.0 {
                            i.cmp(j)
                        } else {
                            a.total_cmp(b).then(i.cmp(j))
                        }
                    }
                })
            }
            (Period(a, g), Period(b, h)) => a.cmp(b).then(g.cmp(h)),
            (Text(a), Text(b)) | (ListText(a), ListText(b)) | (RecordText(a), RecordText(b)) => {
                a.cmp(b)
            }
            _ => self.rank().cmp(&other.rank()),
        }
    }
}

fn sort_key(v: &Value, scale: &dyn Fn(&str) -> Option<(f64, String)>) -> SortKey {
    match v {
        Value::Null => SortKey::Null,
        Value::Bool(b) => SortKey::Bool(*b),
        Value::Int(n) => SortKey::Line(*n as f64, *n, String::new()),
        Value::Float(f) => SortKey::line(*f),
        Value::Instant { secs, nanos, .. } => SortKey::line(*secs as f64 + *nanos as f64 / 1e9),
        Value::Period { start, grain, .. } => SortKey::Period(*start, *grain as u8),
        Value::Quantity { value, base, .. } => {
            SortKey::line_of(*value, crate::value::quantity::dimension_of(base))
        }
        // A library value keys by identity: equal only to itself,
        // ordered after lists and records.
        Value::Foreign(x) => {
            SortKey::RecordText(format!("\u{0}foreign:{:p}", std::sync::Arc::as_ptr(&x.0)))
        }
        // A node reference keys by its locator, after lists and
        // records: references sort in locator order.
        Value::Node(n) => SortKey::RecordText(format!("\u{0}node:{}", n.locator)),
        // a projection orders and equals as its bare key's text
        Value::Projection { key, .. } => sort_key(&Value::Str(key.clone()), scale),
        // a quarq orders and equals as its source text
        Value::Quarq(q) => sort_key(&Value::Str(q.source.clone()), scale),
        // A table keys by its literal, after lists and records.
        Value::Table(t) => SortKey::RecordText(format!("\u{0}table:{}", t.to_quarb())),
        // A string has at most one reading — numeric text carries
        // no unit, unital text excludes pure time (that is span
        // territory), span text needs its span grammar, ISO text
        // is none of those — so the priority order below never
        // actually chooses between readings.
        Value::Str(s) => {
            if let Some(f) = crate::value::number::read(s, crate::value::number::Decimal::Point)
                .and_then(|v| v.numeric())
            {
                SortKey::line(f)
            } else if let Some((bv, base, ..)) =
                crate::value::quantity::parse_unit_text_with(s, scale)
            {
                SortKey::line_of(bv, crate::value::quantity::dimension_of(&base))
            } else if let Some((secs, nanos)) = crate::temporal::parse_span(s) {
                SortKey::line_of(secs as f64 + nanos as f64 / 1e9, "T".to_string())
            } else if let Some((secs, nanos, _)) = crate::temporal::parse_iso(s) {
                SortKey::line(secs as f64 + nanos as f64 / 1e9)
            } else {
                SortKey::Text(s.clone())
            }
        }
        Value::List(_) => SortKey::ListText(v.to_string()),
        Value::Record(_) => SortKey::RecordText(v.to_string()),
    }
}

impl fmt::Display for Value {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Value::Null => Ok(()),
            Value::Bool(b) => write!(f, "{b}"),
            Value::Int(n) => write!(f, "{n}"),
            Value::Float(x) => write!(f, "{}", format_float(*x)),
            Value::Str(s) => write!(f, "{s}"),
            Value::Projection { key, .. } => write!(f, "{key}"),
            Value::Quarq(q) => write!(f, "{}", q.source),
            Value::List(items) => {
                let parts: Vec<String> = items.iter().map(|v| v.to_string()).collect();
                write!(f, "{}", parts.join(", "))
            }
            // A record's text is its Quarb form.
            Value::Record(_) => write!(f, "{}", self.to_quarb()),
            Value::Instant {
                secs,
                nanos,
                offset_min,
                ..
            } => write!(
                f,
                "{}",
                crate::temporal::format_instant(*secs, *nanos, *offset_min)
            ),
            Value::Period {
                start,
                grain,
                calendar,
            } => write!(
                f,
                "{}",
                crate::period::Period {
                    start: *start,
                    grain: *grain,
                    calendar: *calendar
                }
                .format()
            ),
            // The written form when the source had one (`42 km`),
            // the base otherwise; single-factor forms re-parse
            // through the unital reading.
            Value::Quantity {
                value,
                base,
                written,
            } => match written {
                // magnitude, underscore, unit as written (spec: the
                // output form of a quantity), so it pastes back; a
                // Cyrillic designation prints as its SI symbol here,
                // the locale re-spelling it
                Some((v, u)) => write!(
                    f,
                    "{}_{}",
                    format_magnitude(*v),
                    crate::value::quantity::canonical_unit(u)
                ),
                // a span with no written unit prints in the full
                // mixed form, `1h 30min` (spec: Duration)
                None if base == "s" => {
                    write!(
                        f,
                        "{}",
                        crate::value::quantity::duration_text(*value, false)
                    )
                }
                None => write!(f, "{}_{}", format_magnitude(*value), base),
            },
            Value::Foreign(x) => write!(f, "{}", x.display()),
            Value::Table(t) => write!(f, "{}", t.to_quarb()),
            Value::Node(n) => write!(f, "{}", n.locator),
        }
    }
}

/// The base-unit magnitudes of a comparison in which at least one
/// side is a quantity (spec: The Unital Reading), under an explicit
/// unit-expression resolver — the adapter's `unit_scale`, so
/// criterion text may use the mounted document's custom units. The
/// non-quantity side coerces through its unital reading. Dimensions
/// must agree — a base mismatch is no pair, so the comparison fails
/// rather than lies — and a bare number (or numeric text) carries
/// no dimension, so it pairs only with a quantity of dimension `1`
/// (spec: Relations, draft 155: a quantity is equal, and ordered,
/// only to a quantity of its own dimension; `30_km = 30` is false,
/// as is `60_s = 60`, time a dimension like the others).
pub(crate) fn quantital_pair_with(
    a: &Value,
    b: &Value,
    scale: &dyn Fn(&str) -> Option<(f64, String)>,
) -> Option<(f64, f64)> {
    let read = |v: &Value| -> Option<(f64, String, Option<String>)> {
        match v {
            Value::Quantity {
                value,
                base,
                written,
            } => Some((
                *value,
                base.clone(),
                written.as_ref().map(|(_, u)| u.clone()),
            )),
            // unit text, else ISO-8601 or span text, a span in seconds
            Value::Str(s) => crate::value::quantity::parse_unit_text_with(s, scale)
                .map(|(bv, b, _, wu)| (bv, b, Some(wu)))
                .or_else(|| {
                    crate::temporal::parse_span(s).map(|(secs, nanos)| {
                        (secs as f64 + nanos as f64 / 1e9, "s".to_string(), None)
                    })
                }),
            _ => None,
        }
    };
    // A bare number is dimensionless: it pairs with a ratio
    // (dimension `1`) and with nothing dimensioned.
    let ratio = |base: &str| crate::value::quantity::dimension_of(base) == "1";
    match (read(a), read(b)) {
        (Some((va, ba, _)), Some((vb, bb, _))) => (ba == bb).then_some((va, vb)),
        (Some((va, ba, _)), None) if ratio(&ba) => b.numeric().map(|n| (va, n)),
        (None, Some((vb, bb, _))) if ratio(&bb) => a.numeric().map(|n| (n, vb)),
        _ => None,
    }
}

/// Seconds as a float split into whole seconds and nanoseconds.
/// Seconds as a float split into whole seconds and nanoseconds, for
/// the bindings that hand a span to a host language.
pub fn split_seconds_pub(f: f64) -> (i64, u32) {
    split_seconds(f)
}

pub(crate) fn split_seconds(f: f64) -> (i64, u32) {
    let secs = f.floor();
    let nanos = ((f - secs) * 1e9).round();
    if nanos >= 1e9 {
        (secs as i64 + 1, 0)
    } else {
        (secs as i64, nanos as u32)
    }
}

/// `2025-`, the year as a word (spec: Temporal Kinds): digits and a
/// trailing dash, the sign before them for a year before the era.
fn year_word(s: &str) -> Option<crate::period::Period> {
    let body = s.strip_suffix('-')?;
    let (neg, digits) = match body.strip_prefix('-') {
        Some(d) => (true, d),
        None => (false, body),
    };
    if digits.is_empty() || digits.len() > 6 || !digits.bytes().all(|b| b.is_ascii_digit()) {
        return None;
    }
    let y: i64 = digits.parse().ok()?;
    crate::period::Period::of(
        if neg { -y } else { y },
        1,
        1,
        0,
        0,
        0,
        crate::period::Grain::Year,
    )
}

/// Render a float the way `Display` does (no trailing `.0` for whole
/// values). Arithmetic minted no infinity or NaN (an overflow is
/// null); a source that carries one still renders here, as text.
/// A float's text (spec: The Numeric Fragment): the shortest digit
/// string that reads back to the same double, as Python, JavaScript,
/// jq and PostgreSQL print it, in exponent form when the decimal
/// exponent is below -4 or at least 16, exactly Python's repr
/// (`2.89e-82`, `1e-05`, `1.2345678901234568e+29`), positional
/// otherwise (`0.001`, `1234567890123456`); a whole double keeps
/// its point (`3.0`), as every printer does since ruling 2026-11-06,
/// release. NaN and the infinities as Rust spells them.
/// A float as `pretty` draws it (spec: Output Commands, draft 166):
/// at most `precision` digits after the point, trailing zeros
/// dropped, a whole value bare (`-25.1988`, `-1.773333`, `506`);
/// `0` prints the value whole; NaN and the infinities as they are.
/// The value itself is untouched: the output form, `csv` and `json`
/// keep every digit.
pub fn pretty_float(f: f64, precision: usize) -> String {
    if f.is_nan() || f.is_infinite() {
        return format_float(f);
    }
    let fixed = format!("{f:.precision$}");
    match fixed.split_once('.') {
        Some((whole, frac)) => {
            let frac = frac.trim_end_matches('0');
            let whole = if whole == "-0" && frac.is_empty() {
                "0"
            } else {
                whole
            };
            // a whole float keeps its point in every printer (ruling
            // 2026-11-06), the pretty one too
            if frac.is_empty() {
                format!("{whole}.0")
            } else {
                format!("{whole}.{frac}")
            }
        }
        None => fixed,
    }
}

/// A quantity's magnitude or a span's count: the float's text with
/// a whole value's point dropped (`16_km`, `3d`), the value itself
/// being no float.
pub(crate) fn format_magnitude(f: f64) -> String {
    let s = format_float(f);
    match s.strip_suffix(".0") {
        Some(whole) => whole.to_string(),
        None => s,
    }
}

pub(crate) fn format_float(f: f64) -> String {
    if f.is_nan() {
        return "nan".to_string();
    }
    if f.is_infinite() {
        return if f > 0.0 { "inf" } else { "-inf" }.to_string();
    }
    // a whole float keeps its point (ruling 2026-11-06: `2.0` prints
    // `2.0`, never `2`, so the type survives the round trip)
    let plain = |f: f64| -> String {
        if f.fract() == 0.0 {
            format!("{f:.1}")
        } else {
            f.to_string()
        }
    };
    if f == 0.0 {
        return plain(f);
    }
    let sci = format!("{f:e}");
    let (mantissa, exponent) = sci.split_once('e').expect("an exponent");
    let exponent: i32 = exponent.parse().expect("a decimal exponent");
    if (-4..16).contains(&exponent) {
        return plain(f);
    }
    format!(
        "{mantissa}e{}{:02}",
        if exponent < 0 { '-' } else { '+' },
        exponent.abs()
    )
}

/// JSON-quote a string (the escapes JSON requires; forward slash
/// left alone).
fn json_string(s: &str) -> String {
    let mut out = String::with_capacity(s.len() + 2);
    out.push('"');
    for c in s.chars() {
        match c {
            '"' => out.push_str("\\\""),
            '\\' => out.push_str("\\\\"),
            '\n' => out.push_str("\\n"),
            '\r' => out.push_str("\\r"),
            '\t' => out.push_str("\\t"),
            c if (c as u32) < 0x20 => {
                out.push_str(&format!("\\u{:04x}", c as u32));
            }
            c => out.push(c),
        }
    }
    out.push('"');
    out
}

impl From<i64> for Value {
    fn from(n: i64) -> Self {
        Value::Int(n)
    }
}
impl From<bool> for Value {
    fn from(b: bool) -> Self {
        Value::Bool(b)
    }
}
impl From<String> for Value {
    fn from(s: String) -> Self {
        Value::Str(s)
    }
}
impl From<&str> for Value {
    fn from(s: &str) -> Self {
        Value::Str(s.to_string())
    }
}

#[cfg(test)]
mod tests {
    #[test]
    fn a_key_prints_bare_when_it_reads_bare() {
        use super::quarb_key;
        for k in ["a", "a_b", "in-degree", "x-1", "a-b-c", "x_", "é", ".3"] {
            assert_eq!(quarb_key(k), k, "{k} prints bare");
        }
        for (k, want) in [
            ("e f", r#""e f""#),
            ("a-", r#""a-""#),
            ("a--b", r#""a--b""#),
            ("-a", r#""-a""#),
            ("_x", r#""_x""#),
            ("1a", r#""1a""#),
            ("a.b", r#""a.b""#),
            ("null", r#""null""#),
            ("true", r#""true""#),
            ("nan", r#""nan""#),
            (".and.", r#"".and.""#),
            ("", r#""""#),
        ] {
            assert_eq!(quarb_key(k), want, "{k} prints quoted");
        }
    }

    #[test]
    fn floats_print_as_python_prints_them() {
        for (f, want) in [
            (2.89e-82, "2.89e-82"),
            (0.00001, "1e-05"),
            (1e16, "1e+16"),
            (1.2345678901234568e29, "1.2345678901234568e+29"),
            (0.001, "0.001"),
            (0.0001, "0.0001"),
            (1234567890123456.0, "1234567890123456.0"),
            (3.0, "3.0"),
            (-5e-8, "-5e-08"),
            (0.0, "0.0"),
        ] {
            assert_eq!(format_float(f), want, "{f}");
            assert_eq!(Value::Float(f).to_string(), want);
        }
        assert_eq!(Value::Float(2.89e-82).to_json(), "2.89e-82");
    }

    use super::*;

    /// The hashable sort key partitions exactly as `compare_with`
    /// does: a numeric string, an integer and a float on the same
    /// magnitude share one key (so `group` merges them), text with
    /// no reading stays apart, and a quantity keys by its base
    /// magnitude.
    #[test]
    fn sort_key_hashes_like_it_compares() {
        use std::collections::HashSet;
        let scale = |_: &str| None;
        let keys: HashSet<SortKey> = [
            Value::Str("1".into()),
            Value::Int(1),
            Value::Float(1.0),
            Value::Str("x".into()),
            Value::Str("X".into()),
            Value::Null,
            Value::Bool(true),
        ]
        .iter()
        .map(|v| v.sort_key_with(&scale))
        .collect();
        assert_eq!(keys.len(), 5);
        assert_eq!(
            Value::Int(1).sort_key_with(&scale),
            Value::Str(" 1.0 ".into()).sort_key_with(&scale)
        );
        assert_ne!(
            Value::Str("x".into()).sort_key_with(&scale),
            Value::Str("y".into()).sort_key_with(&scale)
        );
    }

    #[test]
    fn json_rendering() {
        let obj = Value::record(vec![
            ("name".into(), Value::Str("A\"da\n".into())),
            ("age".into(), Value::Int(36)),
            ("score".into(), Value::Float(2.5)),
            ("ok".into(), Value::Bool(true)),
            ("gone".into(), Value::Null),
            (
                "tags".into(),
                Value::list(vec![Value::Str("x".into()), Value::Int(1)]),
            ),
        ]);
        assert_eq!(
            obj.to_json(),
            r#"{"name": "A\"da\n", "age": 36, "score": 2.5, "ok": true, "gone": null, "tags": ["x", 1]}"#
        );
        // Display of a record is its Quarb form; an
        // empty record is falsy
        assert_eq!(
            obj.to_quarb(),
            "%(name = \"A\\\"da\n\"; age = 36; score = 2.5; ok = true; gone = null; tags = @(\"x\"; 1))"
        );
        assert_eq!(obj.to_string(), obj.to_quarb());
        assert!(!Value::record(Vec::new()).is_truthy());
        assert_eq!(Value::list(Vec::new()).to_quarb(), "@()");
        assert_eq!(Value::record(Vec::new()).to_quarb(), "%()");
        // a hyphenated name is a bare key; a key the constructor
        // would not read bare quotes
        assert_eq!(
            Value::record(vec![("my-key".into(), Value::Int(1))]).to_quarb(),
            "%(my-key = 1)"
        );
        assert_eq!(
            Value::record(vec![("my key".into(), Value::Int(1))]).to_quarb(),
            "%(\"my key\" = 1)"
        );
        // top-level list display (string coercion) is unchanged
        // (join, not the Quarb form — that is display_form's job)
        assert_eq!(
            Value::list(vec![Value::Str("a".into()), Value::Str("b".into())]).to_string(),
            "a, b"
        );
    }
}

/// A string as a Quarb literal: double-quoted — the quote every
/// keyboard layout has — with `"`, `\`, and a `${` hole opener
/// escaped, so the result reparses exactly (a lone `$` is literal
/// in a double-quoted string). The single-quoted verbatim form
/// stays as input.
pub fn quarb_string(s: &str) -> String {
    let mut out = String::with_capacity(s.len() + 2);
    out.push('"');
    let mut chars = s.chars().peekable();
    while let Some(c) = chars.next() {
        match c {
            '"' | '\\' => {
                out.push('\\');
                out.push(c);
            }
            '$' if chars.peek() == Some(&'{') => {
                out.push('\\');
                out.push('$');
            }
            // `(,` opens the rounded hole; `\(` is the literal.
            '(' if chars.peek() == Some(&',') => {
                out.push('\\');
                out.push('(');
            }
            _ => out.push(c),
        }
    }
    out.push('"');
    out
}

/// A record key as written in `%(k = v)`: bare when the
/// constructor reads it bare as that key, quoted otherwise.
pub fn quarb_key(k: &str) -> String {
    if is_bare_key(k) {
        k.to_string()
    } else {
        quarb_string(k)
    }
}

/// Whether the constructor reads `k` unquoted as the text key `k`:
/// a name — a letter, then letters, digits, `_` and single inner
/// hyphens (`in-degree`, `x-1`) — that is no boolean word and no
/// literal (`true`, `null`, `nan` written bare are typed keys);
/// `_` opens the cursor record, so a key starting with it is
/// quoted; and `.N`, the key of an anonymous regula in `%%.`.
pub fn is_bare_key(k: &str) -> bool {
    if k.len() > 1 && k.starts_with('.') && k[1..].bytes().all(|c| c.is_ascii_digit()) {
        return true;
    }
    let mut cs = k.chars();
    matches!(cs.next(), Some(c) if c.is_alphabetic())
        && cs.all(|c| c.is_alphanumeric() || c == '_' || c == '-')
        && !k.ends_with('-')
        && !k.contains("--")
        && !is_bool_word(k)
        && !matches!(k, "true" | "false" | "null" | "nan" | "inf")
}

#[cfg(test)]
mod one_pass_typing_tests {
    //! The builder types a column as the pass over the held cells
    //! types it: the same rule, met one cell at a time.
    use super::*;

    fn s(x: &str) -> Value {
        Value::Str(x.to_string())
    }

    fn both(rows: Vec<Vec<Value>>) -> (Table, Table) {
        let header = Some((0..rows[0].len()).map(|j| format!("c{j}")).collect());
        let one = Table::typed(header.clone(), rows.clone(), Vec::new()).unwrap();
        let two = Table::assemble(header, rows, Vec::new(), 0, None)
            .retyped()
            .unwrap();
        (one, two)
    }

    #[test]
    fn the_leader_meets_the_pass() {
        let rows = vec![
            vec![
                s("1"),
                s("1.50"),
                s("1.50"),
                s("3 kg"),
                s("true"),
                Value::Null,
                s("2024-01-02"),
                s("x"),
            ],
            vec![
                s("2"),
                s("2"),
                s("x"),
                s("4 kg"),
                s("false"),
                Value::Null,
                s("2024-01-03T04:05:06Z"),
                Value::Int(1),
            ],
            vec![
                s("3"),
                Value::Null,
                s("2.5"),
                s("5 m"),
                s("1"),
                Value::Null,
                s("nope"),
                Value::Float(2.5),
            ],
        ];
        let (one, two) = both(rows);
        assert_eq!(one, two);
        assert_eq!(
            one.types(),
            vec![
                ColumnType::Integer,
                ColumnType::Float,
                ColumnType::Text,
                ColumnType::Text,
                ColumnType::Text,
                ColumnType::Text,
                ColumnType::Text,
                ColumnType::Text,
            ]
        );
        // the text that looked numeric first keeps its spelling
        assert_eq!(one.cell(0, 2), s("1.50"));
        assert_eq!(one.cell(1, 7), s("1"));
    }

    #[test]
    fn the_late_widenings() {
        // ints for a long run, then a float; then a word
        let mut rows: Vec<Vec<Value>> = (0..200)
            .map(|i| vec![s(&i.to_string()), s(&i.to_string())])
            .collect();
        rows.push(vec![s("0.5"), s("w")]);
        let (one, two) = both(rows);
        assert_eq!(one, two);
        assert_eq!(one.types(), vec![ColumnType::Float, ColumnType::Text]);
        assert_eq!(one.cell(3, 0), Value::Float(3.0));
        assert_eq!(one.cell(3, 1), s("3"));
        // quantities of one dimension, then of two
        let (one, two) = both(vec![vec![s("3 kg"), s("3 kg")], vec![s("4 kg"), s("4 m")]]);
        assert_eq!(one, two);
        assert_eq!(one.types(), vec![ColumnType::Quantity, ColumnType::Text]);
        // a projector cell keeps the column raw
        let p = Value::projection(1, "k".to_string());
        let (one, two) = both(vec![vec![p.clone(), s("1")], vec![s("2"), s("2")]]);
        assert_eq!(one, two);
        assert_eq!(one.cell(0, 0), p);
        assert_eq!(one.cell(1, 1), Value::Int(2));
    }

    #[test]
    fn a_declared_column_casts_or_refuses_as_before() {
        let header = Some(vec!["n".to_string(), "t".to_string()]);
        let declared = vec![Some(ColumnType::Integer), Some(ColumnType::Text)];
        let rows = vec![vec![s("1"), Value::Int(5)], vec![Value::Null, s("x")]];
        let one = Table::typed(header.clone(), rows.clone(), declared.clone()).unwrap();
        let two = Table::assemble(header.clone(), rows, declared.clone(), 0, None)
            .retyped()
            .unwrap();
        assert_eq!(one, two);
        assert_eq!(one.cell(0, 1), s("5"));
        let bad = vec![vec![s("1"), s("a")], vec![s("x"), s("b")]];
        let e1 = Table::typed(header.clone(), bad.clone(), declared.clone()).unwrap_err();
        let e2 = Table::assemble(header, bad, declared, 0, None)
            .retyped()
            .unwrap_err();
        assert_eq!(e1, e2);
        assert!(
            e1.contains("column 'n' is declared int, and row 2 holds \"x\""),
            "{e1}"
        );
    }

    #[test]
    fn text_rows_read_as_records_do() {
        let cols = vec!["a".to_string(), "b".to_string()];
        let mut by_text = TableBuilder::shaped(Some(cols.clone()), Vec::new());
        by_text.push_text_row(&["1", ""]);
        by_text.push_text_row(&["2", "x", "extra"]);
        by_text.push_text_row(&["3"]);
        let mut by_record = TableBuilder::shaped(Some(cols), Vec::new());
        by_record.push_record(vec![("a".to_string(), s("1"))]);
        by_record.push_record(vec![("a".to_string(), s("2")), ("b".to_string(), s("x"))]);
        by_record.push_record(vec![("a".to_string(), s("3"))]);
        assert_eq!(by_text.finish().unwrap(), by_record.finish().unwrap());
    }
}