blockworx/store/

projection.rs

//! `document.json`: the readable projection beside the revs.
//! Rationale: `docs/single-author-playbook.md`, D11.
//!
//! `revs/{head}` is the document; this file is a *view* of it, kept for
//! diffing, searching and review (F5) — 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.zst>" },
//!   "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 import can read one back (ignoring the
//! stamp) with no second shape to support.
//!
//! The same writer serves the *export* artifact (D19): a flattened document
//! that leaves its container carries a [`Provenance`] block inside its stamp,
//! naming the document, rev, author and tag it was taken from. `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::record::Digest;

/// Which rev a projection was written from — D11's stamp. 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 (D19),
/// 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 (D19). 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 (D9).
    pub author: String,
    /// What the source called that rev (D18) — §8.1's 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, and the phrase D19 spells for it.
    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` (D19).
    #[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 D7's
    /// explicit import.
    Unrecognized,
}

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
}

/// The bytes an export writes (D19): `document` flattened under a stamp
/// that says where it came from.
///
/// The one writer every artifact leaving a container goes through — the
/// Export command, and the history row's Copy and Save — so an export at a
/// past rev is the export at head with a different fold under it, rather
/// than a second path that could drift.
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 written as an export — the shape
/// test D19's clipboard paste and its file import both read: a stamp on the
/// front is 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 the revs at `root`.
#[cfg(not(target_arch = "wasm32"))]
pub fn found_at(root: &std::path::Path) -> Found {
    match std::fs::read_to_string(root.join(super::container::PROJECTION)) {
        Ok(text) => stamp_in(&text),
        Err(_) => Found::Nothing,
    }
}

/// Write the projection beside the revs at `root`, atomically — a reader
/// looking at the file mid-save sees the old one whole, never half of each.
///
/// # Errors
/// The underlying write failure.
#[cfg(not(target_arch = "wasm32"))]
pub fn write_at(root: &std::path::Path, stamp: Stamp, document: &Document) -> std::io::Result<()> {
    crate::atomic::write_atomically(
        &root.join(super::container::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))
    }

    /// D11's read: 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"),
        ));
    }

    /// D19's boundary: 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,
        );
    }
}