blockworx_store/

stamp.rs

//! The stamp a document carries when it leaves home.
//!
//! An export — a `.json` written out, the metadata on a PDF — says which rev
//! of which document it is a copy of, so a file that has travelled can be
//! read back to where it came from:
//!
//! ```text
//! {
//!   "stamp": { "rev": 12, "state": "<blake3 of revs/000012.json.gz>",
//!              "provenance": { "document": "motor-controller", … } },
//!   "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.
//!
//! [`Provenance`] is advisory throughout — it is never folded and never
//! written into the importing document's log. A container's revs carry no
//! stamp: inside a container the manifest says where every rev came from.

use serde::{Deserialize, Serialize};

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

use super::record::Digest;

/// 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
        }
    }
}

/// 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 read its stamp. Deserializing this builds a stamp
/// and nothing else — serde skips every other field rather than modelling
/// it, so asking where a file came from never parses the drawing in it.
#[derive(Deserialize)]
struct Header {
    stamp: Stamp,
}

/// `document` flattened under a stamp saying where it came from.
// `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 export_text(document: &Document, stamp: Stamp, source: Source) -> String {
    let stamped = Stamped {
        stamp: stamp.from(source),
        document,
    };
    let mut text =
        serde_json::to_string_pretty(&stamped).expect("the document serializes infallibly");
    text.push('\n');
    text
}

/// 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> {
    serde_json::from_str::<Header>(text)
        .ok()
        .map(|header| header.stamp)
}

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

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

    fn exported(document: &Document) -> String {
        export_text(
            document,
            stamp(0, b"empty"),
            Source {
                document: "motor-controller".to_owned(),
                author: "ada".to_owned(),
                tags: vec!["Initial Draft".to_owned()],
            },
        )
    }

    /// 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 written = exported(&Document::default());
        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, "export.json").is_err(),
            "precondition: this body does not deserialize as a document",
        );
        assert!(
            exported_stamp_in(&mutilated).is_some(),
            "the stamp is read off a body this build cannot parse",
        );
    }

    /// What an export says about where it came from.
    #[test]
    fn an_export_carries_the_document_rev_author_and_tags_it_was_taken_at() {
        let stamp = exported_stamp_in(&exported(&Document::default())).expect("it 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 document written by hand, or one a container wrote, carries none —
    /// which is how an importer tells an excerpt from a document.
    #[test]
    fn a_document_that_never_left_home_is_unstamped() {
        let plain = crate::document_file::to_json(&Document::default());
        assert!(exported_stamp_in(&plain).is_none());
    }

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