blockworx_store/

history.rs

//! The audit trail as text: one row per rev, for `blockworx log` and the
//! editor's history panel.
//! Rationale: `docs/single-author-playbook.md`.
//!
//! Both surfaces read the same rows, so the console dump and the panel
//! cannot disagree about what a row says. A row here is a *rendering* of
//! a [`manifest::Row`] — one derivation, whether the row was written this
//! session or read off a disk — except for a session with no files, whose
//! history is its commits and nothing else: there is no clock and no
//! author to report, and the panel says so by showing neither.

use blockworx_doc::{commit::Commit, rev::Rev};

use super::manifest::{self, RowKind};
use super::record::WallTime;
use super::tags::Tags;

/// The wall clock, in the one spelling every surface reads it in: the
/// rows' own. `web_time` is `std::time` on a desktop and the page's clock
/// in a browser, so a row written in a tab carries the time it was really
/// written at.
pub fn now() -> WallTime {
    WallTime::from_unix_millis(
        web_time::SystemTime::UNIX_EPOCH
            .elapsed()
            .unwrap_or_default()
            .as_millis() as u64,
    )
}

/// Where the rows a reader is shown come from. Not two functions: a
/// container's history is its manifest and a scratch session's is its own
/// commits, and naming the two arms is what keeps one renderer over both.
#[derive(Clone, Copy)]
pub enum Journal<'a> {
    Recorded(&'a [manifest::Row]),
    /// A session with no files, whose commits are all there is.
    Session(&'a [Commit]),
}

/// One rev as a reader sees it. Owned, so a view can carry the rows away
/// from the history they were read off.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct Row {
    pub rev: Rev,
    pub label: String,
    /// How many entities the act named — `blockworx log`'s count column.
    /// The panel shows the entities' *scope* instead, so this is the
    /// dump's alone.
    pub touched: usize,
    /// What the manifest row behind this one records beyond the commit.
    /// `None` for a scratch session.
    pub written: Option<Written>,
    /// What this rev is called, where tag rows named it — alphabetical,
    /// and empty for an untagged rev.
    pub tags: Vec<String>,
}

/// What a recorded row says that a bare commit cannot: what kind of step
/// it was, when it was written, by whom, and where they were standing.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct Written {
    pub kind: RowKind,
    pub wall_time: WallTime,
    pub author: String,
    /// The scope path as its author saw it spelled, outermost first.
    pub scope_names: Vec<String>,
}

impl Written {
    fn of(row: &manifest::Row) -> Self {
        Self {
            kind: row.kind,
            wall_time: row.wall_time,
            author: row.author.name.clone(),
            scope_names: row.scope_names.clone(),
        }
    }
}

/// What a rev did to its neighbours, without naming which one — the
/// history panel's kind facet, and the coarse half of [`Row::kind`].
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
pub enum Kind {
    Edit,
    Undo,
    Redo,
}

impl Kind {
    pub fn label(self) -> &'static str {
        match self {
            Kind::Edit => "edit",
            Kind::Undo => "undo",
            Kind::Redo => "redo",
        }
    }
}

/// The calendar day a rev was written, in this machine's own zone: the
/// history panel's day-group key and the value its date facet filters on.
/// One key for both, so a chip and a group heading cannot disagree about
/// which rows belong together.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
pub struct Day(jiff::civil::Date);

impl Day {
    fn of(when: WallTime, zone: &jiff::tz::TimeZone) -> Option<Self> {
        jiff::Timestamp::from_millisecond(when.unix_millis() as i64)
            .ok()
            .map(|instant| Day(instant.to_zoned(zone.clone()).date()))
    }

    /// How a heading or a chip prints this day: the words a reader would
    /// use for the last two, the ISO date beyond them.
    pub fn label(self, now: WallTime) -> String {
        self.label_in(now, &jiff::tz::TimeZone::system())
    }

    fn label_in(self, now: WallTime, zone: &jiff::tz::TimeZone) -> String {
        match Day::of(now, zone) {
            Some(today) if today == self => "Today".to_owned(),
            Some(today) if today.0.yesterday().ok() == Some(self.0) => "Yesterday".to_owned(),
            _ => self.to_string(),
        }
    }
}

impl std::fmt::Display for Day {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.0.strftime("%Y-%m-%d"))
    }
}

impl Row {
    fn kind_written(&self) -> Option<RowKind> {
        self.written.as_ref().map(|written| written.kind)
    }

    fn wall_time(&self) -> Option<WallTime> {
        self.written.as_ref().map(|written| written.wall_time)
    }

    /// What this rev did to its neighbours, without the rev it did it to.
    /// A session keeping no rows has only its commits, and a commit is an
    /// edit.
    pub fn kind_of(&self) -> Kind {
        match self.kind_written() {
            // Tag rows never reach `rows`: `manifest::history` folds them
            // into the vocabulary instead of keeping them as positions.
            None | Some(RowKind::Edit | RowKind::Tag | RowKind::Untag) => Kind::Edit,
            Some(RowKind::Undo { .. }) => Kind::Undo,
            Some(RowKind::Redo { .. }) => Kind::Redo,
        }
    }

    /// Whether this rev is an inverse rather than a design decision —
    /// rendered muted and italic in the panel so a reader scanning for
    /// when something changed can read past it. A session with no rows has
    /// only the label it wrote, which still says so.
    pub fn is_inverse(&self) -> bool {
        match self.written {
            Some(_) => self.kind_of() == Kind::Undo,
            None => self.label.starts_with("Undo "),
        }
    }

    /// Which rev this one took back, where the row says so — what the
    /// panel's `Undo — <original>` is titled from.
    pub fn undone(&self) -> Option<Rev> {
        match self.kind_written() {
            Some(RowKind::Undo { of }) => Some(of),
            _ => None,
        }
    }

    /// The row's kind column: [`Self::kind_of`] and the rev it names.
    pub fn kind(&self) -> String {
        match self.kind_written() {
            None | Some(RowKind::Edit | RowKind::Tag | RowKind::Untag) => {
                Kind::Edit.label().to_owned()
            }
            Some(RowKind::Undo { of }) => format!("{} of r{}", Kind::Undo.label(), of.get()),
            Some(RowKind::Redo { of }) => format!("{} of r{}", Kind::Redo.label(), of.get()),
        }
    }

    /// The scope line: the blocks the act happened inside, outermost
    /// first, as its author saw them spelled. Empty at the document root
    /// and for a session that recorded no path.
    pub fn scope_names(&self) -> &[String] {
        self.written
            .as_ref()
            .map_or(&[], |written| written.scope_names.as_slice())
    }

    /// The author's initials, for the row's avatar. Two at most, and a name
    /// with nothing in it shows nothing rather than a placeholder letter.
    pub fn initials(&self) -> String {
        self.author()
            .split_whitespace()
            .filter_map(|word| word.chars().next())
            .take(2)
            .flat_map(char::to_uppercase)
            .collect()
    }

    /// The clock time this rev was written, without its date: the day is in
    /// the group heading, so the row says only the time.
    /// Empty for a session that carried no clock.
    pub fn time(&self) -> String {
        self.time_in(&jiff::tz::TimeZone::system())
    }

    fn time_in(&self, zone: &jiff::tz::TimeZone) -> String {
        self.wall_time()
            .map_or_else(String::new, |when| written_as(when, zone, "%-I:%M %p"))
    }

    /// How long ago this was written, as a person would say it — "3 hours
    /// ago". The viewing pill's half of the clock; the history row says the
    /// time instead. Empty for a session that carried no clock, and
    /// for a row whose stamp is in `now`'s future (a clock that went
    /// backwards, or a container written on another machine).
    pub fn since(&self, now: WallTime) -> String {
        self.wall_time()
            .and_then(|when| {
                now.unix_millis()
                    .checked_sub(when.unix_millis())
                    .map(|elapsed| humanize(std::time::Duration::from_millis(elapsed)))
            })
            .unwrap_or_default()
    }

    /// The whole instant as a reader would say it — what the time hovers
    /// to and what the picked rev's card shows in full.
    pub fn full_when(&self) -> String {
        self.full_when_in(&jiff::tz::TimeZone::system())
    }

    fn full_when_in(&self, zone: &jiff::tz::TimeZone) -> String {
        self.wall_time().map_or_else(String::new, |when| {
            written_as(when, zone, "%a %-d %b %Y, %-I:%M %p")
        })
    }

    /// The day this rev was written. `None` for a session that carried no
    /// clock — there is no day to group it under.
    pub fn day(&self) -> Option<Day> {
        self.day_in(&jiff::tz::TimeZone::system())
    }

    fn day_in(&self, zone: &jiff::tz::TimeZone) -> Option<Day> {
        self.wall_time().and_then(|when| Day::of(when, zone))
    }

    pub fn author(&self) -> &str {
        self.written
            .as_ref()
            .map_or("", |written| written.author.as_str())
    }

    /// The wall time as a person reads it, in this machine's own zone.
    /// Empty for a session that never carried one.
    pub fn when(&self) -> String {
        self.when_in(&jiff::tz::TimeZone::system())
    }

    /// [`Self::when`] against a named zone — the seam a test pins so its
    /// expected text does not depend on where the machine is.
    fn when_in(&self, zone: &jiff::tz::TimeZone) -> String {
        self.wall_time()
            .map_or_else(String::new, |when| stamp(when, zone))
    }
}

/// Which of a row's columns one search term is asked of. The search box's
/// prefixes, so a reader who remembers *where* a change was made can say
/// so instead of hoping the word is rare.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum Field {
    /// No prefix: the term is asked of every column at once.
    Anywhere,
    Tag,
    Author,
    Scope,
    /// `#` — matched as a prefix of the number, so `#14` reaches r148.
    Rev,
}

impl Field {
    /// The prefixes, spelled once. Longest first is not needed: no
    /// prefix here is a prefix of another.
    const PREFIXES: [(&'static str, Field); 4] = [
        ("tag:", Field::Tag),
        ("by:", Field::Author),
        ("in:", Field::Scope),
        ("#", Field::Rev),
    ];
}

/// One word of a search, already split from its prefix.
#[derive(Clone, PartialEq, Eq, Debug)]
struct Term {
    field: Field,
    text: String,
}

impl Term {
    fn of(word: &str) -> Self {
        let lowered = word.to_lowercase();
        for (prefix, field) in Field::PREFIXES {
            if let Some(rest) = lowered.strip_prefix(prefix) {
                return Term {
                    field,
                    text: rest.to_owned(),
                };
            }
        }
        Term {
            field: Field::Anywhere,
            text: lowered,
        }
    }

    fn admits(&self, row: &Row) -> bool {
        // A prefix with nothing after it is still being typed; it narrows
        // to the column without yet narrowing within it.
        if self.text.is_empty() {
            return true;
        }
        let has = |text: &str| text.to_lowercase().contains(&self.text);
        let tagged = || row.tags.iter().any(|tag| has(tag));
        let in_scope = || row.scope_names().iter().any(|name| has(name));
        let is_rev = || row.rev.get().to_string().starts_with(&self.text);
        match self.field {
            Field::Tag => tagged(),
            Field::Author => has(row.author()),
            Field::Scope => in_scope(),
            Field::Rev => is_rev(),
            Field::Anywhere => {
                has(&row.label) || in_scope() || tagged() || has(row.author()) || is_rev()
            }
        }
    }
}

/// The search box, parsed: every word must match, and a word carrying
/// a prefix is asked only of that column.
///
/// Parsed once per frame rather than per row, so a long history does not
/// re-split the same string for every line of it.
#[derive(Clone, Default, PartialEq, Eq, Debug)]
pub struct Query {
    terms: Vec<Term>,
}

impl Query {
    pub fn parse(text: &str) -> Self {
        Query {
            terms: text.split_whitespace().map(Term::of).collect(),
        }
    }

    /// Whether a row survives. One predicate, so the box and the list
    /// cannot disagree about what "matches" means.
    pub fn admits(&self, row: &Row) -> bool {
        self.terms.iter().all(|term| term.admits(row))
    }

    /// Whether anything at all is narrowing the list — what an empty
    /// result has to blame.
    pub fn narrows(&self) -> bool {
        !self.terms.is_empty()
    }
}

/// The search text that narrows the list to one tag — what clicking a
/// chip sets the box to.
/// What a rev's row says it did. An inverse rev is titled from the rev it
/// moved rather than from the label the store composed for it, so a reader
/// scanning the log reads the act rather than its bookkeeping.
#[must_use]
pub fn said(row: &Row, rows: &[Row]) -> String {
    match undone(row, rows) {
        Some(original) => format!("Undo \u{2014} {original}"),
        None => row.label.clone(),
    }
}

/// The label of the rev an inverse rev took back, where the rows hold it.
#[must_use]
pub fn undone(row: &Row, rows: &[Row]) -> Option<String> {
    let of = row.undone()?;
    rows.iter()
        .find(|earlier| earlier.rev == of)
        .map(|earlier| earlier.label.clone())
}

pub fn tag_query(name: &str) -> String {
    format!("tag:{name}")
}

/// `elapsed` in conversation rather than in units. `timeago` is the whole
/// of this rule — thresholds, pluralization, "just now" — and reproducing
/// it is exactly the kind of drift the house rule about crates is for.
pub fn humanize(elapsed: std::time::Duration) -> String {
    timeago::Formatter::new().convert(elapsed)
}

/// `journal`'s revs with the names their tags give them, oldest first —
/// the order the file holds and the history took them in.
pub fn rows(journal: Journal<'_>, tags: &Tags) -> Vec<Row> {
    let at = |ndx: usize| Rev::ZERO.forward(ndx as u64 + 1);
    match journal {
        Journal::Recorded(written) => written
            .iter()
            .map(|row| Row {
                rev: row.rev,
                label: row.label.clone(),
                touched: row.touched.len(),
                written: Some(Written::of(row)),
                tags: tags.of(row.rev).to_vec(),
            })
            .collect(),
        Journal::Session(commits) => commits
            .iter()
            .enumerate()
            .map(|(ndx, commit)| Row {
                rev: at(ndx),
                label: commit.label().to_owned(),
                touched: commit.ops().len(),
                written: None,
                tags: tags.of(at(ndx)).to_vec(),
            })
            .collect(),
    }
}

/// The rendered dump: one line per row, columns aligned to the widest
/// value in each. A function over the rows rather than a printer, so what
/// the console shows is what a test can read.
pub fn lines(rows: &[Row]) -> Vec<String> {
    lines_in(rows, &jiff::tz::TimeZone::system())
}

/// [`lines`] with the clock's zone named, for a test that must know what
/// the time column will say.
fn lines_in(rows: &[Row], zone: &jiff::tz::TimeZone) -> Vec<String> {
    let kinds: Vec<String> = rows.iter().map(Row::kind).collect();
    let width = |values: &mut dyn Iterator<Item = usize>| values.max().unwrap_or(0);
    let rev_w = width(&mut rows.iter().map(|row| digits(row.rev)));
    let author_w = width(&mut rows.iter().map(|row| row.author().chars().count()));
    let kind_w = width(&mut kinds.iter().map(|kind| kind.chars().count()));
    let ops_w = width(&mut rows.iter().map(|row| digits_of(row.touched)));
    // A log with no tags in it grows no tag column at all.
    let tag_w = width(&mut rows.iter().map(|row| tag_cell(&row.tags).chars().count()));

    rows.iter()
        .zip(&kinds)
        .map(|(row, kind)| {
            let rev = format!("r{:<rev_w$}", row.rev.get());
            let ops = format!("{:>ops_w$} {}", row.touched, plural(row.touched));
            let tag = match tag_w {
                0 => String::new(),
                _ => format!("{:<tag_w$}  ", tag_cell(&row.tags)),
            };
            // A scratch session has no clock and no author, so those two
            // columns collapse to nothing rather than to blank padding.
            let attribution = match row.written {
                None => String::new(),
                Some(_) => format!("{}  {:<author_w$}  ", row.when_in(zone), row.author()),
            };
            format!(
                "{rev}  {attribution}{kind:<kind_w$}  {ops}  {tag}{label}",
                label = row.label
            )
        })
        .collect()
}

fn tag_cell(tags: &[String]) -> String {
    if tags.is_empty() {
        return String::new();
    }
    format!("[{}]", tags.join(" "))
}

fn plural(touched: usize) -> &'static str {
    if touched == 1 { "name " } else { "names" }
}

fn digits(rev: Rev) -> usize {
    digits_of(rev.get() as usize)
}

fn digits_of(n: usize) -> usize {
    n.checked_ilog10().unwrap_or(0) as usize + 1
}

/// `when` in `zone`, to the second. A zone the platform cannot name falls
/// back to UTC, which is jiff's own answer and the only honest one — an
/// audit line must still say *when*.
fn stamp(when: WallTime, zone: &jiff::tz::TimeZone) -> String {
    written_as(when, zone, "%Y-%m-%d %H:%M:%S")
}

/// The date a rev was written, in this machine's own zone — what a title
/// block's Date row says. The log's clock rather than the wall clock, so an
/// export of a given rev says the same thing every time it is taken.
pub fn date(when: WallTime) -> String {
    date_in(when, &jiff::tz::TimeZone::system())
}

/// The date *and time* a rev was written — the status line's title block,
/// which has one line for what a sheet gives a whole row. To the minute
/// where [`Row::when`] goes to the second: a corner of the frame the reader
/// is not looking at is no place for a ticking field.
pub fn written_at(when: WallTime) -> String {
    written_at_in(when, &jiff::tz::TimeZone::system())
}

fn written_at_in(when: WallTime, zone: &jiff::tz::TimeZone) -> String {
    written_as(when, zone, "%Y-%m-%d %H:%M")
}

/// [`date`] against a named zone — the seam a test pins so its expected text
/// does not depend on where the machine is.
fn date_in(when: WallTime, zone: &jiff::tz::TimeZone) -> String {
    written_as(when, zone, "%Y-%m-%d")
}

fn written_as(when: WallTime, zone: &jiff::tz::TimeZone, format: &str) -> String {
    let Ok(instant) = jiff::Timestamp::from_millisecond(when.unix_millis() as i64) else {
        return String::new();
    };
    instant.to_zoned(zone.clone()).strftime(format).to_string()
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::fixture;
    use crate::manifest::RowKind;
    use crate::record::{Camera, Digest, Identity, ScopePath};
    use blockworx_doc::fixtures::rev;

    fn written(n: u64, kind: RowKind, name: &str) -> manifest::Row {
        manifest::Row {
            rev: rev(n),
            kind,
            wall_time: WallTime::from_unix_millis(1_756_000_000_000 + n * 1_000),
            author: Identity::new(name),
            label: "Added a block".to_owned(),
            scope: ScopePath::default(),
            scope_names: Vec::new(),
            camera: Camera::UNSEEN,
            touched: vec![blockworx_doc::id::EntityRef::Block(
                blockworx_doc::fixtures::block_id(1),
            )],
            truncated: false,
            hash: Digest::of(b"a rev file"),
            parent: Digest::genesis(),
        }
    }

    /// A scratch session's history has commits and nothing else, so the
    /// rows carry the labels and leave the audit columns empty rather than
    /// inventing an author or an epoch timestamp.
    #[test]
    fn a_session_with_no_rows_still_lists_its_commits() {
        let commits = fixture::edits(2);
        let none = Tags::default();
        let rows = rows(Journal::Session(&commits), &none);
        assert_eq!(rows.len(), 2);
        assert_eq!(rows[1].rev, rev(2));
        assert_eq!(rows[1].label, "Added a block");
        assert_eq!(rows[1].touched, 1);
        assert_eq!(rows[0].author(), "");
        assert_eq!(rows[0].when(), "");
        assert_eq!(rows[0].kind(), "edit", "a commit with no row is an edit");
    }

    #[test]
    fn a_row_kind_names_the_rev_it_took_back() {
        let recorded = [
            written(1, RowKind::Edit, "ada"),
            written(2, RowKind::Undo { of: rev(1) }, "ada"),
        ];
        let none = Tags::default();
        let rows = rows(Journal::Recorded(&recorded), &none);
        assert_eq!(rows[0].kind(), "edit");
        assert_eq!(rows[1].kind(), "undo of r1");
        assert_eq!(rows[1].undone(), Some(rev(1)));
        assert_eq!(rows[1].author(), "ada");
    }

    /// The elapsed column is the one a reader reads; the absolute stamp
    /// stays reachable beside it. A row from the future — a clock that
    /// went backwards — says nothing rather than a negative age.
    #[test]
    fn a_row_reports_its_age_in_words_and_declines_to_report_a_future_one() {
        let recorded = [written(1, RowKind::Edit, "ada")];
        let none = Tags::default();
        let rows = rows(Journal::Recorded(&recorded), &none);
        let at = recorded[0].wall_time.unix_millis();

        let three_hours_on = WallTime::from_unix_millis(at + 3 * 60 * 60 * 1_000);
        assert_eq!(rows[0].since(three_hours_on), "3 hours ago");
        assert!(
            !rows[0].when().is_empty(),
            "the absolute stamp is still there for the tooltip",
        );
        assert_eq!(
            rows[0].since(WallTime::from_unix_millis(at - 1)),
            "",
            "a row stamped after `now` has no age to report",
        );
    }

    #[test]
    fn a_scratch_row_has_no_age_because_it_carries_no_clock() {
        let commits = fixture::edits(1);
        let none = Tags::default();
        assert_eq!(rows(Journal::Session(&commits), &none)[0].since(now()), "");
    }

    /// A tag rides its rev's row, and `blockworx log` grows a column for
    /// it only when there is one to show.
    #[test]
    fn a_tagged_rev_carries_its_name_into_the_dump() {
        let commits = fixture::edits(2);
        let mut tags = Tags::default();
        tags.add(rev(2), "Initial Draft");
        tags.add(rev(2), "vendor");
        let rows = rows(Journal::Session(&commits), &tags);
        assert_eq!(rows[1].tags, ["Initial Draft", "vendor"]);
        assert!(rows[0].tags.is_empty());

        let tagged = lines(&rows);
        assert!(
            tagged[1].contains("[Initial Draft vendor]"),
            "a rev's whole set does not reach the dump: {}",
            tagged[1],
        );
        let none = Tags::default();
        let untagged = lines(&super::rows(Journal::Session(&commits), &none));
        assert!(
            !untagged[0].contains('['),
            "a history with no tags grows no tag column: {}",
            untagged[0],
        );
    }

    /// What `blockworx log` prints, over a real container with a pinned
    /// clock: the whole dump, spelled out. It is the audit trail's user
    /// interface, so the columns are pinned the way the row format is.
    #[test]
    fn a_container_dumps_its_trail_line_by_line() {
        use crate::handle::{Clock, Store};

        let dir = fixture::dir("log-dump");
        let root = dir.join("doc.bwx");
        let author = Identity::new("ada");
        let mut store = Store::create(
            crate::storage::Native::at(&root),
            Clock::Pinned {
                at: WallTime::from_unix_millis(1_756_000_000_000),
                step: std::time::Duration::from_mins(1),
            },
        )
        .expect("the container");
        let edit = store
            .submit_edit(
                fixture::commit(
                    "Added a block",
                    vec![
                        fixture::block_create(1, "Adder"),
                        fixture::block_create(2, "Summer"),
                    ],
                ),
                &author,
            )
            .expect("the edit lands");
        store
            .undo(edit, &author)
            .expect("and is taken back, into the trail");

        let dumped = lines_in(
            &rows(Journal::Recorded(store.rows()), store.tags()),
            &jiff::tz::TimeZone::UTC,
        );
        assert_eq!(
            dumped,
            [
                "r1  2025-08-24 01:47:40  ada  edit        2 names  Added a block",
                "r2  2025-08-24 01:48:40  ada  undo of r1  2 names  Undo Added a block",
            ],
            "an undo frames what it moved: the same names its edit did",
        );
    }

    /// The title block says *when* a rev was written as a plain date — the
    /// row's own clock, so the same rev exports to the same date forever,
    /// and no wall clock creeps into a byte-identical export.
    #[test]
    fn a_revs_date_is_the_day_its_row_was_written() {
        let at = WallTime::from_unix_millis(1_756_000_060_000);
        assert_eq!(date_in(at, &jiff::tz::TimeZone::UTC), "2025-08-24");
        assert_eq!(
            date_in(at, &jiff::tz::TimeZone::UTC),
            stamp(at, &jiff::tz::TimeZone::UTC)
                .split(' ')
                .next()
                .expect("the audit stamp leads with its date"),
            "the two spellings of the same instant disagree about the day",
        );
    }

    /// The day a row groups under is the day it was written, and the last
    /// two are named rather than dated — one key for the heading and the
    /// date facet both.
    #[test]
    fn a_row_groups_under_the_day_it_was_written() {
        let utc = jiff::tz::TimeZone::UTC;
        let recorded = [
            written(1, RowKind::Edit, "ada"),
            manifest::Row {
                wall_time: WallTime::from_unix_millis(1_756_000_000_000 - 2 * 86_400_000),
                ..written(2, RowKind::Edit, "ada")
            },
        ];
        let none = Tags::default();
        let rows = rows(Journal::Recorded(&recorded), &none);
        let (recent, older) = (
            rows[0].day_in(&utc).expect("a row carries a day"),
            rows[1].day_in(&utc).expect("a row carries a day"),
        );
        assert_ne!(recent, older, "two days apart grouped together");
        assert_eq!(recent.to_string(), "2025-08-24");
        assert_eq!(older.to_string(), "2025-08-22");

        let now = WallTime::from_unix_millis(1_756_000_000_000);
        assert_eq!(recent.label_in(now, &utc), "Today");
        assert_eq!(older.label_in(now, &utc), "2025-08-22");
        let tomorrow = WallTime::from_unix_millis(1_756_000_000_000 + 86_400_000);
        assert_eq!(recent.label_in(tomorrow, &utc), "Yesterday");

        let commits = fixture::edits(1);
        assert_eq!(
            super::rows(Journal::Session(&commits), &none)[0].day_in(&utc),
            None,
            "a session with no clock has no day to group under",
        );
    }

    /// The kind facet is coarse — every undo answers `undo`, whichever rev
    /// it took back — while the row's own column still names that rev.
    #[test]
    fn the_kind_facet_is_coarse_and_marks_inverse_revs() {
        let recorded = [
            written(1, RowKind::Edit, "ada"),
            written(2, RowKind::Undo { of: rev(1) }, "ada"),
        ];
        let none = Tags::default();
        let rows = rows(Journal::Recorded(&recorded), &none);
        assert_eq!(rows[0].kind_of(), Kind::Edit);
        assert_eq!(rows[1].kind_of(), Kind::Undo);
        assert_eq!(rows[1].kind(), "undo of r1", "the column still names it");
        assert!(!rows[0].is_inverse());
        assert!(rows[1].is_inverse());

        let commits = fixture::edits(2);
        let unrecorded = super::rows(Journal::Session(&commits), &none);
        assert_eq!(
            unrecorded[1].label, "Added a block",
            "precondition: the fixture's commits are plain edits",
        );
        assert!(
            !unrecorded[1].is_inverse(),
            "a session with no rows reads its own labels",
        );
    }

    /// The prefixes each narrow to one column, so a word that would
    /// match somewhere else does not.
    #[test]
    fn a_prefix_asks_one_column_and_a_bare_word_asks_them_all() {
        let mut recorded = [written(1, RowKind::Edit, "ada")];
        recorded[0].label = "Base plate 78 to 84 mm".to_owned();
        recorded[0].scope_names = vec!["engine".to_owned(), "base plate".to_owned()];
        let mut tags = Tags::default();
        tags.add(rev(1), "vendor");
        let rows = rows(Journal::Recorded(&recorded), &tags);
        let admits = |query: &str| Query::parse(query).admits(&rows[0]);

        assert!(admits("plate"), "a bare word reaches the description");
        assert!(admits("ada"), "a bare word reaches the author");
        assert!(admits("vendor"), "a bare word reaches the tags");
        assert!(
            admits("78"),
            "§6.1's deltas are what makes numbers searchable"
        );

        assert!(admits("by:ada") && !admits("by:grace"));
        assert!(admits("tag:vendor") && !admits("tag:plate"));
        assert!(
            admits("in:engine") && !admits("in:vendor"),
            "`in:` reached outside the scope",
        );
        assert!(
            admits("#1") && !admits("#2"),
            "`#` matches a rev number as a prefix of it",
        );
        assert!(
            !admits("tag:plate"),
            "a prefixed term matched a column it did not name",
        );
    }

    /// Every word must match, which is what makes a second word narrow
    /// rather than widen.
    #[test]
    fn every_word_must_match_and_a_bare_prefix_narrows_no_further() {
        let mut recorded = [written(1, RowKind::Edit, "ada")];
        recorded[0].label = "Base plate".to_owned();
        let none = Tags::default();
        let rows = rows(Journal::Recorded(&recorded), &none);
        let admits = |query: &str| Query::parse(query).admits(&rows[0]);

        assert!(admits("base plate"));
        assert!(!admits("base rib"), "a second word widened the search");
        assert!(
            admits("by:"),
            "a prefix still being typed narrows to the column, not to nothing",
        );
        assert!(!Query::parse("   ").narrows(), "blank text narrows nothing");
    }

    /// Column widths come from the widest value, so a two-digit rev or a
    /// long author name does not push its neighbours out of line.
    #[test]
    fn columns_line_up_across_rows() {
        let recorded: Vec<manifest::Row> = (1..=10)
            .map(|n| {
                written(
                    n,
                    RowKind::Edit,
                    if n == 3 { "ada lovelace" } else { "bob" },
                )
            })
            .collect();
        let none = Tags::default();
        let lines = lines(&rows(Journal::Recorded(&recorded), &none));
        assert_eq!(lines.len(), 10);
        assert!(lines[9].starts_with("r10 "), "{}", lines[9]);
        let label_at = |line: &String| line.find("Added").expect("every line names its label");
        let first = label_at(&lines[0]);
        for line in &lines {
            assert_eq!(label_at(line), first, "a column drifted: {line}");
        }
    }
}