vivac 0.15.7

//! The event. `ROADMAP.md` §4 keeps it in a single append-only file and the
//! tree comes from folding it: if the log is the truth, the stack is computed.
//! Two homes for the same state contradict principle 1 of `MODEL.md`.

use serde::{Deserialize, Serialize};
use std::path::Path;

/// Node types. `MODEL.md` §4.2. `Pillar` and `Rule` are `t411`: added at the
/// end, so the order of what already existed never moves.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Kind {
    Goal,
    Task,
    Decision,
    Question,
    Constraint,
    Finding,
    Assumption,
    Pillar,
    Rule,
}

impl Kind {
    /// Alias prefix. `MODEL.md` §3.6.
    pub fn prefix(self) -> char {
        match self {
            Kind::Goal => 'g',
            Kind::Task => 't',
            Kind::Decision => 'd',
            Kind::Question => 'q',
            Kind::Constraint => 'c',
            Kind::Finding => 'f',
            Kind::Assumption => 'a',
            Kind::Pillar => 'p',
            Kind::Rule => 'r',
        }
    }

    pub fn parse(s: &str) -> Option<Kind> {
        Some(match s {
            "goal" => Kind::Goal,
            "task" => Kind::Task,
            "decision" => Kind::Decision,
            "question" => Kind::Question,
            "constraint" => Kind::Constraint,
            "finding" => Kind::Finding,
            "assumption" => Kind::Assumption,
            "pillar" => Kind::Pillar,
            "rule" => Kind::Rule,
            _ => return None,
        })
    }

    /// The word this type goes by. The inverse of `parse`, and spelled the
    /// same way the log serialises it.
    pub fn word(self) -> &'static str {
        match self {
            Kind::Goal => "goal",
            Kind::Task => "task",
            Kind::Decision => "decision",
            Kind::Question => "question",
            Kind::Constraint => "constraint",
            Kind::Finding => "finding",
            Kind::Assumption => "assumption",
            Kind::Pillar => "pillar",
            Kind::Rule => "rule",
        }
    }

    pub const ALL: &'static str =
        "goal, task, decision, question, constraint, finding, assumption, pillar, rule";

    /// `word`, with the indefinite article it takes: `"a task"`, `"an
    /// assumption"`. Every message that forms "a" plus a type's word reads
    /// this instead, since `assumption` is the one of the nine that needs
    /// "an".
    pub fn with_article(self) -> String {
        let article = if self == Kind::Assumption { "an" } else { "a" };
        format!("{article} {}", self.word())
    }
}

/// Canonical states.
///
/// `MODEL.md` §4.2 gives different names per type --a `goal` is `achieved`, a
/// `decision` is `standing`-- but the state machine is the same in all five
/// cases. They are stored canonical and translated for display: if the log
/// stored the synonym, every query would have to know all seven types.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum State {
    Active,
    Done,
    Suspended,
    Abandoned,
    Superseded,
}

impl State {
    pub fn is_open(self) -> bool {
        self == State::Active
    }

    /// The word this state goes by for this type.
    pub fn word(self, kind: Kind) -> &'static str {
        match (self, kind) {
            (State::Active, Kind::Decision) => "standing",
            (State::Active, _) => "open",
            (State::Done, Kind::Goal) => "achieved",
            (State::Done, Kind::Question) => "answered",
            (State::Done, _) => "closed",
            (State::Suspended, _) => "parked",
            (State::Abandoned, _) => "abandoned",
            (State::Superseded, _) => "superseded",
        }
    }

    /// A one-letter mark. Meaning is never encoded in colour alone: this is
    /// read in black and white and over ssh.
    pub fn mark(self) -> char {
        match self {
            State::Active => ' ',
            State::Done => 'x',
            State::Suspended => '~',
            State::Abandoned => '!',
            State::Superseded => '-',
        }
    }
}

/// Flags orthogonal to state. `MODEL.md` §4.2: a `task` can be `active` and
/// `suspect` at once, and modelling them as states would give an untenable
/// cartesian product.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Flag {
    /// Something it depends on fell over. Always carries a reason.
    Suspect,
    /// Worth a look, without claiming it is wrong.
    Review,
    /// Stale: untouched while what it covers was changing.
    Stale,
}

impl Flag {
    pub fn parse(s: &str) -> Option<Flag> {
        Some(match s {
            "suspect" => Flag::Suspect,
            "review" => Flag::Review,
            "stale" | "old" => Flag::Stale,
            _ => return None,
        })
    }

    pub fn word(self) -> &'static str {
        match self {
            Flag::Suspect => "suspect",
            Flag::Review => "review",
            Flag::Stale => "stale",
        }
    }

    pub const ALL: &'static str = "suspect, review, stale";
}

/// A vivac: a safe stop partway up. `MODEL.md` §4.7 calls it a **single
/// primitive with three uses**: `push`, `pop` and session end all generate
/// vivacs, they are not different mechanisms.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum VivacKind {
    Push,
    Pop,
    Park,
    Manual,
    Auto,
}

impl VivacKind {
    pub fn word(self) -> &'static str {
        match self {
            VivacKind::Push => "push",
            VivacKind::Pop => "pop",
            VivacKind::Park => "park",
            VivacKind::Manual => "manual",
            VivacKind::Auto => "auto",
        }
    }
}

/// A rule's arm: the command or test that verifies it, and the folder it
/// runs in, relative to the one that holds `.vivac`. `d441`: the folder is
/// part of the arm's identity, not an afterthought -- the same command in
/// two folders are two different arms, since the folder decides what the
/// command actually checks.
///
/// No `#[serde(default)]` on either field: a line missing `dir` was written
/// by a format this version does not fully know, and `t411` §13 bis refuses
/// it rather than guessing which folder was meant.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct Arm {
    pub dir: String,
    pub command: String,
}

/// A decision, judged against a pillar or a rule: the node it was judged
/// against and the sentence saying how it holds. `t426` §1.1. `node` is a
/// ULID, resolved at write time the same way `parent` is; `why` is the
/// sentence, and vivac never judges it.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct Against {
    pub node: String,
    pub why: String,
}

/// One repository a lane declared. `Body::LaneDeclared` carries one per
/// repository the folder holds, so a lane spanning more than one repository
/// -- a product split across several -- says so in one event rather than one
/// per repository.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct Repo {
    /// Relative to the lane's folder, with forward slashes, and "." when
    /// the folder is the repository. **Never absolute**: the security
    /// pillar keeps paths out of the log, and a relative one survives the
    /// folder being moved besides.
    pub path: String,
    /// The repository's root commit, which is what makes two clones of one
    /// repository recognisable as the same repository without a remote URL
    /// ever being written down (`d597`).
    ///
    /// **Captured now, compared later.** `setup` is the only place on the
    /// write path allowed to ask git anything, so this is filled in there
    /// (`repos::root_commit`) and only ever read back to copy forward into
    /// the next declaration (`ops.rs`) -- nothing compares two of these
    /// against each other yet, which is `d597`'s own point and is left to
    /// `t594` §4.6. Not dead data even so: asking again later would cost
    /// the same `git rev-list` for strictly less information, since the
    /// commit that was root when a lane first declared itself may no
    /// longer be root by then.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub root: Option<String>,
}

impl Repo {
    /// A repository at `path`, recorded relative to the lane's folder at
    /// `base`, with forward slashes on every platform and "." when the
    /// folder is the repository itself.
    ///
    /// `None` when `path` is not inside `base`: the security pillar keeps
    /// absolute paths out of the log, and a path that cannot be made
    /// relative to the lane is one this lane has no business recording.
    pub fn relative(base: &Path, path: &Path, root: Option<String>) -> Option<Repo> {
        let rel = path.strip_prefix(base).ok()?;
        let path = if rel.as_os_str().is_empty() {
            ".".to_string()
        } else {
            rel.components()
                .map(|c| c.as_os_str().to_string_lossy().into_owned())
                .collect::<Vec<_>>()
                .join("/")
        };
        Some(Repo { path, root })
    }
}

/// `serde` wants a predicate over a reference, and `Not::not` takes its
/// bool by value. The smallest thing that fits, so a flag that is false
/// costs nothing on disk.
fn is_false(b: &bool) -> bool {
    !*b
}

/// Where one of a lane's repositories was when the lane wrote. A complete
/// photograph, never a delta: `where.changed` carries one per declared
/// repository, so any one of them can be read on its own.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
pub struct WhereRepo {
    /// Relative to the lane's folder, with forward slashes, and `.` when
    /// the folder is the repository -- the same spelling `Repo` uses.
    pub path: String,
    /// Absent with a detached `HEAD`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub branch: Option<String>,
    /// Absent when `HEAD` could not be read at all.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub sha: Option<String>,
    /// The branch is the one a rebase is replaying, so the sha moves once
    /// per commit and is not worth an event of its own (§2.5).
    #[serde(default, skip_serializing_if = "is_false")]
    pub rebasing: bool,
    /// The lane declared this repository and its folder is gone.
    #[serde(default, skip_serializing_if = "is_false")]
    pub missing: bool,
    /// The branch name tripped the redaction guard and was kept out. The
    /// sha stays: it is a hash, and withholding it would lose the only
    /// thing left that says where the work was (`d600`).
    #[serde(default, skip_serializing_if = "is_false")]
    pub withheld: bool,
}

/// One repository's commit at the moment of a stop.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
pub struct RepoAnchor {
    pub path: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub branch: Option<String>,
    pub sha: String,
}

/// One event from the log. `MODEL.md` §3.2.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Event {
    pub seq: u64,
    pub id: String,
    pub ts: String,
    /// Opaque identifier of whoever originated it. **Never email or name**:
    /// `MODEL.md` §3.4 proposed `git config user.email` and the security
    /// pillar vetoes it. Generated at `init` and kept in `config`.
    pub actor: String,
    pub lane: String,
    /// The body is **nested**, not flattened.
    ///
    /// `#[serde(flatten)]` forces serde through an intermediate map, and that
    /// is paid on every startup, which here means every call because there is
    /// no daemon. Besides, `MODEL.md` §3.2 already said `payload`: flattening
    /// it was a convenience of mine, not a decision of the model.
    pub payload: Body,
}

/// The event body.
///
/// The fields are English, and only English. They each carried a
/// `serde(alias)` with their Spanish name while the port was in flight, and
/// `d45` retired that layer: the log now reads one spelling.
///
/// The way out was to migrate the data, not to carry the compatibility layer
/// forever. The three real trees were rewritten **before** anything was
/// removed, the migration was checked by diffing the output byte for byte
/// against the binary that still read both spellings, and each previous log
/// stayed beside its tree as `events.pre-english`. The log is the source of
/// truth and it is append-only, so a rename that could not read what is
/// already written would not be a rename, it would be a data loss.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(tag = "type")]
pub enum Body {
    /// The `spawns` edge travels **inside** the node, not as a separate event.
    /// That way invariant 11 of `MODEL.md` §9 --at most one incoming `spawns`,
    /// provenance is a tree and not a DAG-- is held up by the schema and not
    /// by a check somebody can forget.
    #[serde(rename = "node.created")]
    NodeCreated {
        node: String,
        num: u64,
        // Not `type`: that name is taken by the enum tag above.
        kind: Kind,
        title: String,
        #[serde(default)]
        why: String,
        #[serde(default)]
        parent: Option<String>,
        #[serde(default)]
        blocks: bool,
        #[serde(default)]
        refs: Vec<String>,
        #[serde(default)]
        governs: Vec<String>,
        /// A rule's arms, given at birth. Empty for a rule with none -- which
        /// means it is judged -- and for every type that is not a rule.
        /// `d415`. Omitted when empty, so a pillar or any other kind that
        /// never carries one writes exactly what it always has.
        #[serde(default, skip_serializing_if = "Vec::is_empty")]
        arms: Vec<Arm>,
        /// A decision's declarations at birth: absent and empty mean
        /// different things (`d445`). Absent is a vivac that could not
        /// declare, or a tree with no pillar or rule open; `Some(vec![])` is
        /// one that could and declared nothing. `t426` §1.1: added last, so
        /// the order of what already exists never moves.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        against: Option<Vec<Against>>,
    },
    #[serde(rename = "state.changed")]
    StateChanged {
        node: String,
        state: State,
        #[serde(default)]
        outcome: String,
        /// A forced close is legitimate, but it has to be a decision and not
        /// an oversight: that is why it leaves a trace here. `MODEL.md` §7.
        #[serde(default)]
        forced: bool,
    },
    #[serde(rename = "node.noted")]
    NodeNoted { node: String, note: String },
    #[serde(rename = "edge.blocks")]
    BlockChanged { node: String, blocks: bool },
    #[serde(rename = "stack.pushed")]
    Pushed { node: String },
    #[serde(rename = "stack.popped")]
    Popped { node: String },
    #[serde(rename = "stack.promoted")]
    Promoted { node: String },
    /// The reason is mandatory: `BRIEF-SPEC.md` §10 tests it, because a flag
    /// with no reason informs nobody and is only noise.
    #[serde(rename = "flag.raised")]
    FlagRaised {
        node: String,
        flag: Flag,
        reason: String,
    },
    #[serde(rename = "flag.cleared")]
    FlagCleared { node: String, flag: Flag },
    /// A rule gains a command or test that verifies it. `d415`: vivac never
    /// runs it, only stores and hands it back. Shaped like `flag.raised`
    /// on purpose -- an addition, never a rewrite of what was already there.
    /// `dir` is `d441`: no `#[serde(default)]`, because a line missing it is
    /// one an older format wrote, and `t411` §13 bis has to refuse it rather
    /// than silently treat it as the tree's own folder.
    #[serde(rename = "arm.added")]
    ArmAdded {
        node: String,
        dir: String,
        command: String,
    },
    /// The mirror of `arm.added`, shaped like `flag.cleared`.
    #[serde(rename = "arm.removed")]
    ArmRemoved {
        node: String,
        dir: String,
        command: String,
    },
    /// A decision declares, after the fact, what it was judged against.
    /// `t426` §1.2: one per call to `declare`, with every declaration it
    /// carries, written whole or not at all.
    #[serde(rename = "against.added")]
    AgainstAdded { node: String, against: Vec<Against> },
    #[serde(rename = "vivac.created")]
    VivacCreated {
        vivac: String,
        num: u64,
        kind: VivacKind,
        /// Frozen stack with titles: a vivac has to stay readable even after
        /// the nodes have changed.
        stack: Vec<(String, String)>,
        /// Paths of the pitch. Not measured --that would need `post_tool`, which
        /// is not in Tier 0-- but derived from the `governs` the stack declares.
        working_set: Vec<String>,
        /// The resume payload: what you were about to do next.
        next_intent: String,
        #[serde(default)]
        anchor: crate::anchor::AnchorRef,
        /// Where every declared repository of the lane was. Written by a
        /// lane that has them; a lane without them writes `anchor` alone,
        /// exactly as before. A reader takes `anchors` when it carries
        /// something and falls back to `anchor`, so every stop written
        /// until today is read without migrating anything (`f25`).
        #[serde(default, skip_serializing_if = "Vec::is_empty")]
        anchors: Vec<RepoAnchor>,
        #[serde(default)]
        node_ref: Option<String>,
        #[serde(default)]
        label: String,
    },
    /// A session was opened and the brief was injected.
    ///
    /// Without it there is no answer to *was the brief read?*: a session
    /// boundary was only ever the gap between two writes, and a gap also
    /// happens when somebody goes to lunch.
    ///
    /// `source` is a `String` and not an enum **on purpose**. If a new kind of
    /// opening ever shows up, an enum would make the whole line unreadable and
    /// count it among the broken ones; a string lets it through and leaves the
    /// decision to whoever reads.
    ///
    /// Everything here is an opaque identifier. The payload this is built from
    /// also carries the path of the transcript, which holds the user's home
    /// directory: it is read past and never written down.
    #[serde(rename = "session.started")]
    SessionStarted {
        source: String,
        #[serde(default)]
        focus: Option<String>,
        #[serde(default)]
        vivac: Option<String>,
        #[serde(default)]
        session: Option<String>,
    },
    /// This folder is a lane of this tree, and these are its repositories.
    ///
    /// Written by `setup`, by a linked worktree the first time it writes, and
    /// again by `setup` whenever the repositories or the name change. The last
    /// one wins: this is a statement about a folder as it is now, not an
    /// event that accumulates.
    #[serde(rename = "lane.declared")]
    LaneDeclared {
        lane: String,
        name: String,
        repos: Vec<Repo>,
    },
    /// The lane named `main` belongs to this folder. Only ever written for
    /// `main`, and only by `relocate`: a tree whose folder moved leaves an
    /// implicit `main` behind it, and this is what stops the folder it left
    /// from answering as `main` too.
    #[serde(rename = "lane.claimed")]
    LaneClaimed { lane: String },
    /// Where the lane's repositories are, written only when it differs
    /// from the last one this lane wrote (§2.5). A lane with no declared
    /// repositories never writes it, which is every tree where nobody has
    /// run `setup`: that is what keeps 0.11 able to read them (§2.6).
    #[serde(rename = "where.changed")]
    WhereChanged { repos: Vec<WhereRepo> },
}

impl Body {
    /// Every event-type tag this version's `Body` can read, in enum
    /// declaration order. `t411` §13: a line whose own `type` is well-formed
    /// JSON but missing from this list came from a newer vivac, and the
    /// reader refuses before writing rather than silently dropping a rule it
    /// can no longer see. Tied to every variant by
    /// `tests::known_events_cover_every_variant`, which fails to compile the
    /// moment a variant is added here without a line in that test -- a hand
    /// kept list with nothing forcing it to move would desynchronise the
    /// first time somebody forgot.
    pub(crate) const KNOWN_EVENTS: &'static [&'static str] = &[
        "node.created",
        "state.changed",
        "node.noted",
        "edge.blocks",
        "stack.pushed",
        "stack.popped",
        "stack.promoted",
        "flag.raised",
        "flag.cleared",
        "arm.added",
        "arm.removed",
        "against.added",
        "vivac.created",
        "session.started",
        "lane.declared",
        "lane.claimed",
        "where.changed",
    ];
}

/// Why a line failed to deserialise as an `Event`, when that reason is worth
/// refusing over rather than skipping. `t411` §13.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum UnknownReason {
    /// The line's own `payload.type` names an event this version's `Body`
    /// does not carry.
    EventType(String),
    /// The line is a `node.created` whose `kind` is not one `Kind::parse`
    /// knows.
    NodeKind(String),
    /// The line is a well-formed event of a type and kind this version
    /// knows, and still does not deserialise: something added after this
    /// version, such as a new flag value. Skipping it would
    /// reopen the hole `f419` measured -- the next write reusing the number
    /// of what was skipped -- one release later.
    Shape(String),
}

/// Classifies a line that has **already** failed to deserialise as an
/// `Event`. `None` covers the ordinary accident -- broken JSON, a truncated
/// tail, anything without the shape of an event -- and that line stays
/// counted and skipped exactly as it always has. `Some` covers every line
/// that does have the shape of an event -- valid JSON, a numeric `seq`, a
/// `payload` with a `type` -- since a torn write never produces one of those,
/// and one this version cannot read was written by a newer vivac.
///
/// Only ever called on a line that already failed the ordinary parse, so a
/// healthy log pays nothing for this.
pub(crate) fn unknown_reason_for(line: &str) -> Option<UnknownReason> {
    let v: serde_json::Value = serde_json::from_str(line).ok()?;
    v.get("seq")?.as_u64()?;
    let payload = v.get("payload")?.as_object()?;
    let event_type = payload.get("type")?.as_str()?;
    if !Body::KNOWN_EVENTS.contains(&event_type) {
        return Some(UnknownReason::EventType(event_type.to_string()));
    }
    if event_type == "node.created" {
        if let Some(kind) = payload.get("kind").and_then(|k| k.as_str()) {
            if Kind::parse(kind).is_none() {
                return Some(UnknownReason::NodeKind(kind.to_string()));
            }
        }
    }
    Some(UnknownReason::Shape(event_type.to_string()))
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Exhaustive on purpose -- no wildcard arm -- so a variant added to
    /// `Body` without a line here fails to compile instead of drifting
    /// silently out of `KNOWN_EVENTS` below.
    fn tag_of(b: &Body) -> &'static str {
        match b {
            Body::NodeCreated { .. } => "node.created",
            Body::StateChanged { .. } => "state.changed",
            Body::NodeNoted { .. } => "node.noted",
            Body::BlockChanged { .. } => "edge.blocks",
            Body::Pushed { .. } => "stack.pushed",
            Body::Popped { .. } => "stack.popped",
            Body::Promoted { .. } => "stack.promoted",
            Body::FlagRaised { .. } => "flag.raised",
            Body::FlagCleared { .. } => "flag.cleared",
            Body::ArmAdded { .. } => "arm.added",
            Body::ArmRemoved { .. } => "arm.removed",
            Body::AgainstAdded { .. } => "against.added",
            Body::VivacCreated { .. } => "vivac.created",
            Body::SessionStarted { .. } => "session.started",
            Body::LaneDeclared { .. } => "lane.declared",
            Body::LaneClaimed { .. } => "lane.claimed",
            Body::WhereChanged { .. } => "where.changed",
        }
    }

    fn one_of_each() -> Vec<Body> {
        vec![
            Body::NodeCreated {
                node: "n".into(),
                num: 1,
                kind: Kind::Task,
                title: "t".into(),
                why: String::new(),
                parent: None,
                blocks: false,
                refs: vec![],
                governs: vec![],
                arms: vec![],
                against: None,
            },
            Body::StateChanged {
                node: "n".into(),
                state: State::Done,
                outcome: String::new(),
                forced: false,
            },
            Body::NodeNoted {
                node: "n".into(),
                note: "x".into(),
            },
            Body::BlockChanged {
                node: "n".into(),
                blocks: true,
            },
            Body::Pushed { node: "n".into() },
            Body::Popped { node: "n".into() },
            Body::Promoted { node: "n".into() },
            Body::FlagRaised {
                node: "n".into(),
                flag: Flag::Review,
                reason: "x".into(),
            },
            Body::FlagCleared {
                node: "n".into(),
                flag: Flag::Review,
            },
            Body::ArmAdded {
                node: "n".into(),
                dir: "vivac".into(),
                command: "x".into(),
            },
            Body::ArmRemoved {
                node: "n".into(),
                dir: "vivac".into(),
                command: "x".into(),
            },
            Body::AgainstAdded {
                node: "n".into(),
                against: vec![Against {
                    node: "r".into(),
                    why: "x".into(),
                }],
            },
            Body::VivacCreated {
                vivac: "v".into(),
                num: 1,
                kind: VivacKind::Manual,
                stack: vec![],
                working_set: vec![],
                next_intent: String::new(),
                anchor: crate::anchor::AnchorRef::default(),
                anchors: vec![],
                node_ref: None,
                label: String::new(),
            },
            Body::SessionStarted {
                source: "s".into(),
                focus: None,
                vivac: None,
                session: None,
            },
            Body::LaneDeclared {
                lane: "01M2".into(),
                name: "v2".into(),
                repos: vec![Repo {
                    path: "webapi".into(),
                    root: Some("abc123".into()),
                }],
            },
            Body::LaneClaimed {
                lane: "main".into(),
            },
            Body::WhereChanged {
                repos: vec![WhereRepo {
                    path: "webapi".into(),
                    branch: Some("develop".into()),
                    ..Default::default()
                }],
            },
        ]
    }

    #[test]
    fn known_events_cover_every_variant() {
        let samples = one_of_each();
        for s in &samples {
            let tag = tag_of(s);
            assert!(
                Body::KNOWN_EVENTS.contains(&tag),
                "missing from KNOWN_EVENTS: {tag}"
            );
            let v = serde_json::to_value(s).unwrap();
            assert_eq!(v["type"], tag, "tag_of disagrees with serde's own tag");
        }
        assert_eq!(
            samples.len(),
            Body::KNOWN_EVENTS.len(),
            "a variant or a listed tag is unmatched"
        );
    }

    #[test]
    fn an_unknown_event_type_is_flagged() {
        let line = r#"{"seq":1,"id":"x","ts":"t","actor":"a","lane":"main","payload":{"type":"node.evolved","node":"n"}}"#;
        assert_eq!(
            unknown_reason_for(line),
            Some(UnknownReason::EventType("node.evolved".to_string()))
        );
    }

    #[test]
    fn an_unknown_node_kind_is_flagged() {
        let line = r#"{"seq":1,"id":"x","ts":"t","actor":"a","lane":"main","payload":{"type":"node.created","node":"n","num":1,"kind":"epic","title":"t"}}"#;
        assert_eq!(
            unknown_reason_for(line),
            Some(UnknownReason::NodeKind("epic".to_string()))
        );
    }

    #[test]
    fn ordinary_broken_json_is_not_flagged() {
        assert_eq!(unknown_reason_for("{not json"), None);
        assert_eq!(
            unknown_reason_for(r#"{"payload":{"type":"node.created"}}"#),
            None,
            "no seq at all is an ordinary broken line, not a newer vivac"
        );
    }

    #[test]
    fn a_known_event_this_version_cannot_read_is_flagged() {
        // `node.noted` is known, and still fails the ordinary parse: a field
        // added or reshaped after this version. Skipped, it would be the
        // hole `f419` measured, one release later.
        let line = r#"{"seq":1,"id":"x","ts":"t","actor":"a","lane":"main","payload":{"type":"node.noted","node":"n"}}"#;
        assert_eq!(
            unknown_reason_for(line),
            Some(UnknownReason::Shape("node.noted".to_string()))
        );
    }

    /// A known type carrying a value this version does not know: a flag
    /// value that is not `suspect`, `review` or `stale`, which is what a
    /// newer release adding a flag would write.
    #[test]
    fn a_known_type_with_a_field_value_this_version_does_not_know_is_flagged() {
        let line = r#"{"seq":1,"id":"x","ts":"t","actor":"a","lane":"main","payload":{"type":"flag.raised","node":"n","flag":"advise","reason":"x"}}"#;
        assert_eq!(
            unknown_reason_for(line),
            Some(UnknownReason::Shape("flag.raised".to_string()))
        );
    }

    #[test]
    fn the_lane_events_are_named_as_the_spec_names_them() {
        let d = Body::LaneDeclared {
            lane: "01M2".into(),
            name: "v2".into(),
            repos: vec![Repo {
                path: "webapi".into(),
                root: Some("abc123".into()),
            }],
        };
        let text = serde_json::to_string(&d).unwrap();
        assert!(text.contains(r#""type":"lane.declared""#), "{text}");
        let c = Body::LaneClaimed {
            lane: "main".into(),
        };
        assert!(serde_json::to_string(&c)
            .unwrap()
            .contains(r#""type":"lane.claimed""#));
    }

    #[test]
    fn a_repo_without_a_root_commit_does_not_write_the_field() {
        let r = Repo {
            path: ".".into(),
            root: None,
        };
        assert_eq!(serde_json::to_string(&r).unwrap(), r#"{"path":"."}"#);
    }

    #[test]
    fn a_repo_with_a_root_commit_round_trips_both_fields_and_no_others() {
        let r = Repo {
            path: "webapi".into(),
            root: Some("abc123".into()),
        };
        let text = serde_json::to_string(&r).unwrap();
        let v: serde_json::Value = serde_json::from_str(&text).unwrap();
        let obj = v.as_object().unwrap();
        let mut keys: Vec<&str> = obj.keys().map(|k| k.as_str()).collect();
        keys.sort();
        assert_eq!(keys, ["path", "root"]);
        let back: Repo = serde_json::from_str(&text).unwrap();
        assert_eq!(back, r);
    }

    #[test]
    fn a_path_inside_the_base_comes_out_relative_with_forward_slashes() {
        let base = Path::new("lane");
        let path = base.join("nested").join("webapi");
        let r = Repo::relative(base, &path, None).unwrap();
        assert_eq!(r.path, "nested/webapi");
    }

    #[test]
    fn the_base_itself_comes_out_as_dot() {
        let base = Path::new("lane");
        let r = Repo::relative(base, base, None).unwrap();
        assert_eq!(r.path, ".");
    }

    #[test]
    fn a_path_outside_the_base_is_none() {
        let base = Path::new("lane");
        let path = Path::new("elsewhere");
        assert!(Repo::relative(base, path, None).is_none());
    }

    #[test]
    fn a_windows_absolute_path_outside_the_base_is_none() {
        let base = Path::new(r"C:\work\lane");
        let path = Path::new(r"D:\other\place");
        assert!(Repo::relative(base, path, None).is_none());
    }

    #[test]
    fn a_where_survives_the_round_trip_and_omits_what_it_does_not_know() {
        let w = Body::WhereChanged {
            repos: vec![
                WhereRepo {
                    path: "webapi".into(),
                    branch: Some("feature/net10".into()),
                    sha: Some("0123456789abcdef0123456789abcdef01234567".into()),
                    rebasing: false,
                    missing: false,
                    withheld: false,
                },
                WhereRepo {
                    path: "gone".into(),
                    missing: true,
                    ..Default::default()
                },
            ],
        };
        let s = serde_json::to_string(&w).unwrap();

        assert!(s.contains(r#""type":"where.changed""#));
        assert!(!s.contains("rebasing"), "a false flag is not written down");
        assert!(
            !s.contains(r#""branch":null"#),
            "an absent branch is absent, not null"
        );
        assert_eq!(serde_json::from_str::<Body>(&s).unwrap(), w);
    }

    #[test]
    fn this_version_knows_the_lane_events_and_does_not_refuse_them() {
        // `t411` §13: a line whose own `type` is well-formed JSON but missing
        // from `KNOWN_EVENTS` is treated as though a newer vivac wrote it,
        // and refused outright. `lane.declared` and `lane.claimed` are known
        // now, so neither must come back as an `EventType` refusal -- the
        // day either stops being listed, this is what notices.
        for tag in ["lane.declared", "lane.claimed"] {
            let line = format!(r#"{{"seq":1,"payload":{{"type":"{tag}"}}}}"#);
            assert_ne!(
                unknown_reason_for(&line),
                Some(UnknownReason::EventType(tag.to_string())),
                "{tag} was refused as an event type this version does not know"
            );
        }
    }
}