lernie 0.1.64

//! **Which config commit governs this conversation** (yog's `docs/REMOTE.md`
//! §9.7, §9.12; bl-b52c).
//!
//! # The shape whose MEANING moved, which is the one drift a corpus cannot see
//!
//! At PROTOCOL 5 (REMOTE §9.12) this reply *"lost `branch` and gained
//! `follows` and `diverged_lineages`, and its `oid` changed meaning"*:
//!
//! > **`oid` was the fork commit and is the resolved one.** Before, it named
//! > the `config/*` ancestor an agent's branch forked off, a commit that never
//! > moved. Now it names the commit control actually reads at every step
//! > boundary: the followed lineage's head. A seat that painted the old value
//! > as *what this conversation runs* would keep painting, and would keep
//! > being wrong, which is why the number has to move even though the key did
//! > not.
//!
//! The bytes stayed well-formed across that bump, so nothing mechanical here
//! could have caught it — which is why the trap is written at `PROTOCOL` and
//! restated at the one reader that spends it. This decoder is the first thing
//! in this crate to read the field at all, and it reads it under the new
//! meaning.
//!
//! # One enum, two keys, and neither is redundant
//!
//! Upstream, verbatim: *"`follows` is the lineage's name and
//! `diverged_lineages` is `0`; or `follows` is `null` and the count is how
//! many distinct lineage tips reached the conversation and therefore held it
//! on its fork commit. The decoder rebuilds the enum off `follows` alone and
//! reads the count only where it can be non-zero, so the pair cannot decode to
//! a state the encoder could not have written."* [`Governance`] is that enum,
//! rebuilt off `follows` alone for exactly that reason.
//!
//! # The sentence is upstream's two wordings, not one composed here
//!
//! REMOTE §9.7 rules it directly — *"a seat renders it through
//! `GoverningConfig::label()`'s two wordings and composes no sentence of its
//! own"* — so [`Governing::label`] is that function's text, and the pane
//! paints what it answers.
//!
//! # The workflow mark rides BESIDE the commit, never instead of it
//!
//! REMOTE §9.24 (edition 19) grew `workflow_mark`: `null` on the general path
//! — the followed tip's `workflow.yaml` governs — else `{holder, oid,
//! short_oid, lineage}`, because a mark moves `workflow.yaml` alone while the
//! models, souls and manifest keep following the tip. So [`Governing::oid`]
//! still names the tip and [`Mark`] names the one file that comes from
//! elsewhere. Absent reads as `null` does — *"a reader that never heard of the
//! key reads the answer it always did"* — and a mark whose `lineage` is `null`
//! is a commit its lineage has advanced past, which is a reading, never a
//! refusal.

use serde_json::{Map, Value};

use super::fields;

/// The kind token this reading answers to.
pub(crate) const KIND: &str = "governing";

/// The config commit a conversation resolves its policy from, and the lineage
/// that settled it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Governing {
    /// The resolved commit, whole — what a `git show` outside yog takes.
    pub oid: String,
    /// The same commit clipped, which is what a label wears. Carried rather
    /// than derived: unlike a rail notch's, this one is the engine's own
    /// clipping of a commit it resolved, and both keys ride the wire.
    pub short_oid: String,
    /// Which lineage governs, and how.
    pub governance: Governance,
    /// Every path the governing commit's tree holds — the souls, the workflow,
    /// the provider table this conversation is actually running under.
    pub files: Vec<String>,
    /// **The mark that moves `workflow.yaml` off the tip**, or `None` where
    /// the tip's own governs (REMOTE §9.24).
    pub workflow_mark: Option<Mark>,
}

/// **A standing workflow mark**: where `workflow.yaml` is read from instead of
/// the followed tip.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Mark {
    /// The descent id wearing the mark — this conversation's own, or the
    /// ancestor's whose mark it inherits.
    pub holder: String,
    /// The marked commit, whole.
    pub oid: String,
    /// The same commit, as the engine clipped it.
    pub short_oid: String,
    /// The `config/*` lineage standing exactly on that commit, or `None` once
    /// the lineage has advanced past it — an older commit pinned, not an error.
    pub lineage: Option<String>,
}

impl Mark {
    /// **The one line the mark is painted as.** The two arms are the two
    /// things §9.24 says a mark can be: a lineage's head, or a commit that
    /// lineage has since left behind.
    pub fn line(&self) -> String {
        match &self.lineage {
            Some(lineage) => format!(
                "workflow.yaml marked to config/{lineage} at {}, on {}",
                self.short_oid, self.holder
            ),
            None => format!(
                "workflow.yaml pinned at {}, a commit its lineage has moved past, on {}",
                self.short_oid, self.holder
            ),
        }
    }
}

/// **How the policy is settled**: one lineage followed, or several diverged
/// over the fork commit and none may be guessed between.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Governance {
    /// Exactly one lineage reaches it, named bare.
    Follows(String),
    /// Two or more distinct tips reach it, so it is held on the fork commit.
    Held { diverged: u64 },
}

impl Governing {
    /// **The engine's own sentence about it**, in its two wordings — never a
    /// third composed here (REMOTE §9.7).
    pub fn label(&self) -> String {
        match &self.governance {
            Governance::Follows(lineage) => {
                format!("policy follows config/{lineage}, now at {}", self.short_oid)
            }
            Governance::Held { diverged } => format!(
                "policy held at {} — {diverged} diverged config lineages",
                self.short_oid
            ),
        }
    }
}

/// The whole answer, strictly ([`super`]'s rung 1). `follows` is `null` rather
/// than absent, matching the key it replaced, and [`fields::opt_text`] reads
/// both spellings alike.
pub(crate) fn governing(obj: &Map<String, Value>) -> Result<Governing, String> {
    let governance = match fields::opt_text(obj, "follows")? {
        Some(lineage) => Governance::Follows(lineage),
        None => Governance::Held {
            diverged: fields::count(obj, "diverged_lineages")?,
        },
    };
    Ok(Governing {
        oid: fields::text(obj, "oid")?,
        short_oid: fields::text(obj, "short_oid")?,
        governance,
        files: fields::list(obj, "files", path)?,
        workflow_mark: fields::nested(obj, "workflow_mark", mark)?,
    })
}

/// The mark, strictly: every key but `lineage` is always stated.
fn mark(obj: &Map<String, Value>) -> Result<Mark, String> {
    Ok(Mark {
        holder: fields::text(obj, "holder")?,
        oid: fields::text(obj, "oid")?,
        short_oid: fields::text(obj, "short_oid")?,
        lineage: fields::opt_text(obj, "lineage")?,
    })
}

/// One path out of the governing tree's listing.
fn path(value: &Value) -> Result<String, String> {
    value
        .as_str()
        .map(str::to_owned)
        .ok_or_else(|| "governing: a non-string path in \"files\"".to_owned())
}

#[cfg(test)]
mod tests;