blockworx_store/

projection.rs

//! `document.json`: the readable projection beside the revs.
//! Rationale: `docs/single-author-playbook.md`.
//!
//! `revs/{head}` is the document; this file is a *view* of it, kept for
//! diffing, searching and review — and, unlike a rev, self-contained:
//! it embeds its payloads, so a copy of it out of the container is still a
//! whole drawing. It is therefore **write-only**: load reads the head rev
//! and reads nothing here but the stamp on the front, which says which rev
//! wrote the file, so a projection that has fallen behind can be told from
//! one somebody hand-edited without the body ever being modelled.
//!
//! ```text
//! {
//!   "stamp": { "rev": 12, "state": "<blake3 of revs/000012.json.gz>" },
//!   "version": 3,
//!   …the document…
//! }
//! ```
//!
//! The stamp is the first field so a reader takes it off the front; the
//! document's own fields follow flattened beside it, so the file is a
//! document like any other and the command line can open one (ignoring the
//! stamp) with no second shape to support.
//!
//! A stamp can also carry a [`Provenance`] block naming the document, rev,
//! author and tag a document was taken from — what a PDF's metadata says, and
//! what a stamped file opened from the command line remembers. `document.json`
//! never carries one — it is the document, not an excerpt of another.

use serde::{Deserialize, Serialize};

use blockworx_doc::{document::Document, rev::Rev};

use super::container::{Container, PROJECTION};
use super::record::Digest;
use super::storage::Storage;

/// Which rev a projection was written from. Both halves matter: the rev
/// orders it against the history, and `state` — the blake3 of that rev's own
/// file, the one state digest this format has — says the document at that rev
/// was *this* one. [`Stamp::provenance`] joins them on an artifact that left
/// home, and only there.
#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, Debug)]
pub struct Stamp {
    pub rev: Rev,
    pub state: Digest,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub provenance: Option<Provenance>,
}

/// Where an export came from. Advisory throughout: it is never folded, never
/// written into the importing document's log, and a file that carries none is
/// read exactly as one that does.
#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, Debug)]
pub struct Provenance {
    /// The source document's name.
    pub document: String,
    /// The rev the export was taken at — [`Stamp::rev`], since the export
    /// *is* the projection of that fold.
    pub rev: Rev,
    /// The exporting session's identity.
    pub author: String,
    /// What the source called that rev — its tags, alphabetical, and empty
    /// where it called it nothing.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub tags: Vec<String>,
}

impl Provenance {
    /// The one line that names the artifact's origin — the title block's
    /// "From" row.
    pub fn line(&self) -> String {
        format!("Rev {} of {}", self.rev.get(), self.document)
    }

    /// What the line has no room for: who exported it, and the name the rev
    /// carried.
    pub fn detail(&self) -> String {
        let by = format!("Exported by {}", self.author);
        if self.tags.is_empty() {
            return by;
        }
        format!(
            "{by} \u{2014} \u{201c}{}\u{201d}",
            self.tags.join("\u{201d}, \u{201c}")
        )
    }
}

/// What an exporting session knows about itself. The rev is deliberately
/// absent: it is the stamp's own, so [`Stamp::from`] is the single place the
/// two are joined and they cannot disagree.
#[derive(Clone, PartialEq, Eq, Debug)]
pub struct Source {
    pub document: String,
    pub author: String,
    pub tags: Vec<String>,
}

impl Stamp {
    /// A rev and the digest of the bytes it was written as.
    pub fn at(rev: Rev, state: Digest) -> Self {
        Self {
            rev,
            state,
            provenance: None,
        }
    }

    /// Mark this stamp as an artifact taken out of `source`.
    #[must_use]
    pub fn from(self, source: Source) -> Self {
        let Source {
            document,
            author,
            tags,
        } = source;
        Self {
            provenance: Some(Provenance {
                document,
                rev: self.rev,
                author,
                tags,
            }),
            ..self
        }
    }

    /// Whether this stamp names the same rev as `other`, written the same
    /// way. Provenance is advisory and says nothing about the document, so
    /// it is not part of the answer.
    fn names_the_rev_of(&self, other: &Stamp) -> bool {
        self.rev == other.rev && self.state == other.state
    }
}

/// The file, as written: the stamp, then the document flattened beside it.
#[derive(Serialize)]
struct Stamped<'a> {
    stamp: Stamp,
    #[serde(flatten)]
    document: &'a Document,
}

/// Enough of the file to judge it. Deserializing this builds a stamp and
/// nothing else — serde skips every other field rather than modelling it,
/// which is what "load never parses the projection's body" means in code.
#[derive(Deserialize)]
struct Header {
    stamp: Stamp,
}

/// What sits where the projection goes.
#[derive(Clone, Debug)]
pub enum Found {
    /// Nothing written yet — a container nobody has saved.
    Nothing,
    Stamped(Stamp),
    /// A file whose stamp this build cannot read.
    Unstamped,
}

/// What the projection is, relative to the log's head. Not a bool: only
/// [`Freshness::Unrecognized`] is worth a warning, and only
/// [`Freshness::Fresh`] means the chrome says nothing.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Freshness {
    /// Its stamp names the rev the history heads at, as that rev was
    /// written.
    Fresh,
    /// It is behind (or missing): regenerated on the next save, silently.
    Stale,
    /// Its stamp names a rev this history never wrote — hand-edited, or
    /// written by another build. Overwritten on the next save, loudly; the
    /// one road an edited projection has back into the document is an
    /// explicit import.
    Unrecognized,
}

/// How long the log's head sits still before the projection follows it.
///
/// The commits are already durable, so a refresh can lose nothing; what the
/// wait buys is not rewriting the whole projection once per keystroke.
pub const SETTLE: core::time::Duration = core::time::Duration::from_secs(2);

/// What a host should do about a projection that has fallen behind its log.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Refresh {
    /// Nothing to write, or nothing this session may write.
    Settled,
    /// Ask again in this long: the head has not sat still yet.
    Wait(core::time::Duration),
    Write,
}

/// Whether `document.json` is owed a rewrite, `waited` after the head last
/// moved. One rule, because two shells keep one file in step.
///
/// A projection nobody recognizes stays behind an explicit save: it was
/// hand-edited or written by another build, and a timer must not quietly
/// overwrite it.
#[must_use]
pub fn refreshed(
    freshness: Option<Freshness>,
    may_write: crate::doc::Writability,
    waited: core::time::Duration,
) -> Refresh {
    if freshness != Some(Freshness::Stale) || may_write == crate::doc::Writability::ReadOnly {
        return Refresh::Settled;
    }
    match SETTLE.checked_sub(waited) {
        None | Some(core::time::Duration::ZERO) => Refresh::Write,
        Some(remaining) => Refresh::Wait(remaining),
    }
}

impl Freshness {
    pub fn of(found: &Found, head: &Stamp) -> Self {
        match found {
            Found::Nothing => Freshness::Stale,
            Found::Stamped(stamp) if stamp.names_the_rev_of(head) => Freshness::Fresh,
            Found::Stamped(stamp) if stamp.rev < head.rev => Freshness::Stale,
            Found::Unstamped | Found::Stamped(_) => Freshness::Unrecognized,
        }
    }
}

/// The file's text: `document` under `stamp`, pretty-printed.
// `serde_json` fails only on a non-string map key or a non-finite float,
// and neither the stamp nor the document model holds one.
#[expect(clippy::expect_used, clippy::missing_panics_doc)]
pub fn text(stamp: Stamp, document: &Document) -> String {
    let stamped = Stamped { stamp, document };
    let mut text =
        serde_json::to_string_pretty(&stamped).expect("the projection serializes infallibly");
    text.push('\n');
    text
}

/// `document` flattened under a stamp that says where it came from — the
/// shape a stamped file opened from the command line is read as.
pub fn export_text(document: &Document, stamp: Stamp, source: Source) -> String {
    text(stamp.from(source), document)
}

/// The stamp on the front of `text`, if it carries one this build reads.
pub fn stamp_in(text: &str) -> Found {
    match serde_json::from_str::<Header>(text) {
        Ok(header) => Found::Stamped(header.stamp),
        Err(_) => Found::Unstamped,
    }
}

/// Whether `text` is a flattened document carrying a stamp — what a document
/// that left home has and a hand-written one does not.
pub fn exported_stamp_in(text: &str) -> Option<Stamp> {
    match stamp_in(text) {
        Found::Stamped(stamp) => Some(stamp),
        Found::Nothing | Found::Unstamped => None,
    }
}

/// What is written beside `container`'s revs.
pub fn found_in<S: Storage>(container: &Container<S>) -> Found {
    match container.read(&PROJECTION) {
        Ok(Some(bytes)) => {
            String::from_utf8(bytes).map_or(Found::Unstamped, |text| stamp_in(&text))
        }
        Ok(None) | Err(_) => Found::Nothing,
    }
}

/// Write the projection beside the revs, whole or not at all — a reader
/// looking at the file mid-save sees the old one whole, never half of each.
///
/// # Errors
/// The underlying write failure.
pub fn write_in<S: Storage>(
    container: &Container<S>,
    stamp: Stamp,
    document: &Document,
) -> std::io::Result<()> {
    container.write(&PROJECTION, text(stamp, document).as_bytes())
}

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

    fn stamp(rev: u64, seed: &[u8]) -> Stamp {
        Stamp::at(blockworx_doc::fixtures::rev(rev), Digest::of(seed))
    }

    /// The stamp comes off a file whose body this build could never model,
    /// which is the proof that reading it does not model one.
    #[test]
    fn the_stamp_is_read_without_the_body_behind_it() {
        let empty = Document::default();
        let written = text(stamp(7, b"seven"), &empty);
        assert!(
            written.find("\"stamp\"") < written.find("\"version\""),
            "the stamp is not the first field of the file:\n{written}",
        );

        let mutilated = written.replace(r#""version": 3"#, r#""version": "three""#);
        assert!(
            crate::document_file::parse(&mutilated, "document.json").is_err(),
            "precondition: this body does not deserialize as a document",
        );
        assert!(matches!(
            stamp_in(&mutilated),
            Found::Stamped(found) if found == stamp(7, b"seven"),
        ));
    }

    /// The projection beside the revs is the document, so it carries no
    /// provenance; an export is an excerpt of that document taken somewhere
    /// else, so it does. The two are the same writer, and this is the one
    /// thing that separates them.
    #[test]
    fn the_projection_carries_no_provenance_and_an_export_does() {
        let empty = Document::default();
        let projection = text(stamp(0, b"empty"), &empty);
        assert!(
            !projection.contains("provenance"),
            "document.json was written as an excerpt of another document:\n{projection}",
        );
        assert!(matches!(
            stamp_in(&projection),
            Found::Stamped(stamp) if stamp.provenance.is_none(),
        ));

        let exported = export_text(
            &empty,
            stamp(0, b"empty"),
            Source {
                document: "motor-controller".to_owned(),
                author: "ada".to_owned(),
                tags: vec!["Initial Draft".to_owned()],
            },
        );
        let stamp = exported_stamp_in(&exported).expect("the export is stamped");
        let from = stamp.provenance.clone().expect("and carries provenance");
        assert_eq!(from.document, "motor-controller");
        assert_eq!(from.author, "ada");
        assert_eq!(from.tags, ["Initial Draft"]);
        assert_eq!(
            from.rev, stamp.rev,
            "the provenance names a rev the stamp does not",
        );
        assert_eq!(from.line(), "Rev 0 of motor-controller");
    }

    /// A stamp with no provenance and the same stamp with one name the same
    /// rev: what makes a projection stale is the history moving under it,
    /// never where some export said it came from.
    #[test]
    fn provenance_does_not_make_a_projection_unrecognized() {
        let head = stamp(4, b"head");
        let travelled = head.clone().from(Source {
            document: "elsewhere".to_owned(),
            author: "ada".to_owned(),
            tags: Vec::new(),
        });
        assert_eq!(
            Freshness::of(&Found::Stamped(travelled), &head),
            Freshness::Fresh,
        );
    }

    /// The projection is a document like any other on the way back in: the
    /// stamp is an extra field an importer ignores.
    #[test]
    fn a_written_projection_reads_back_as_a_plain_document() {
        let empty = Document::default();
        let written = text(stamp(0, b"empty"), &empty);
        assert_eq!(
            crate::document_file::parse(&written, "document.json").expect("it parses"),
            empty,
        );
    }

    #[test]
    fn a_projection_at_the_head_rev_is_fresh_and_an_older_one_is_stale() {
        let head = stamp(9, b"head");
        assert_eq!(
            Freshness::of(&Found::Stamped(head.clone()), &head),
            Freshness::Fresh,
        );
        assert_eq!(
            Freshness::of(&Found::Stamped(stamp(8, b"older")), &head),
            Freshness::Stale,
        );
        assert_eq!(Freshness::of(&Found::Nothing, &head), Freshness::Stale);
    }

    /// The two ways a projection stops being ours: a stamp at our rev
    /// naming bytes we did not write, and a stamp from a future this
    /// history has not reached.
    #[test]
    fn a_stamp_this_history_never_wrote_is_unrecognized() {
        let head = stamp(9, b"head");
        assert_eq!(
            Freshness::of(&Found::Stamped(stamp(9, b"other bytes")), &head),
            Freshness::Unrecognized,
        );
        assert_eq!(
            Freshness::of(&Found::Stamped(stamp(10, b"the future")), &head),
            Freshness::Unrecognized,
        );
        assert_eq!(
            Freshness::of(&Found::Unstamped, &head),
            Freshness::Unrecognized,
        );
    }

    /// The settle both shells read: a stale projection on a writable
    /// container is written once the head has sat still, and a hand-edited
    /// one never is.
    #[test]
    fn a_stale_projection_is_rewritten_once_the_head_has_sat_still() {
        use crate::doc::Writability::{ReadOnly, Writable};
        let stale = Some(Freshness::Stale);
        assert_eq!(refreshed(stale, Writable, SETTLE), Refresh::Write);
        assert_eq!(refreshed(stale, Writable, SETTLE * 2), Refresh::Write);
        assert_eq!(
            refreshed(stale, Writable, SETTLE / 2),
            Refresh::Wait(SETTLE / 2),
            "the wait answers what is left of it, not the whole of it",
        );
        assert_eq!(
            refreshed(stale, ReadOnly, SETTLE * 2),
            Refresh::Settled,
            "a session that may not write the container wrote its projection",
        );
        for settled in [None, Some(Freshness::Fresh), Some(Freshness::Unrecognized)] {
            assert_eq!(
                refreshed(settled, Writable, SETTLE * 2),
                Refresh::Settled,
                "{settled:?} was taken for a projection owed a rewrite",
            );
        }
    }
}