blockworx/store/

record.rs

//! The circumstances of a write: who, when, where they were standing, and
//! what they were looking at. Rationale:
//! `docs/single-author-playbook.md`, D9/D15 (the `author` identity), D12
//! (the hash chain), and `docs/log-vs-snapshot.md` §10.1 (the camera).
//!
//! These are the fields a [`manifest`](super::manifest) row is made of,
//! kept apart from the row itself because the editor builds them at seal
//! and the store writes them: an [`Attribution`] crosses that seam.
//!
//! Target-independent on purpose: Phase 8 reads and writes the same rows
//! in the browser, where the container is OPFS rather than a directory.

use blockworx_doc::id::BlockId;
use serde::{Deserialize, Serialize};

/// What the first row chains to. A fixed string rather than zeros, so a
/// hand-written row claiming an all-zero parent is not mistaken for a
/// genuine start of history. Changing it invalidates every existing
/// manifest, which is what the version suffix is for.
const GENESIS: &str = "blockworx.manifest.v1";

/// The stand-in name for a machine whose environment names nobody. Not a
/// person's name and not empty, so an audit trail says "we do not know"
/// rather than appearing to attribute the edit.
const UNATTRIBUTED: &str = "unattributed author";

/// When a record was written, in unix milliseconds. An instant rather than
/// a duration, so it is not a [`core::time::Duration`]; the conversion
/// from `SystemTime` goes through one, and the clock that mints these is
/// `store::handle::Clock` — native-only, so that this module stays
/// target-independent.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug, Serialize, Deserialize)]
#[serde(transparent)]
pub struct WallTime(u64);

impl WallTime {
    pub const EPOCH: Self = Self(0);

    pub const fn from_unix_millis(millis: u64) -> Self {
        Self(millis)
    }

    pub const fn unix_millis(self) -> u64 {
        self.0
    }
}

/// A blake3 digest in the manifest's durable spelling: 64 lowercase hex
/// characters. One type for both halves of D12 — the chain link and the
/// rev file's stamp — so the two cannot be spelled differently.
#[derive(Clone, Copy, PartialEq, Eq)]
pub struct Digest([u8; 32]);

impl Digest {
    /// The parent of the first record.
    pub fn genesis() -> Self {
        Self::of(GENESIS.as_bytes())
    }

    pub fn of(bytes: &[u8]) -> Self {
        Self(blake3::hash(bytes).into())
    }
}

impl std::fmt::Display for Digest {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(blake3::Hash::from(self.0).to_hex().as_str())
    }
}

impl std::fmt::Debug for Digest {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{self}")
    }
}

impl Serialize for Digest {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.collect_str(self)
    }
}

impl<'de> Deserialize<'de> for Digest {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let hex = String::deserialize(deserializer)?;
        blake3::Hash::from_hex(&hex)
            .map(|hash| Self(*hash.as_bytes()))
            .map_err(serde::de::Error::custom)
    }
}

/// Who wrote a record: D9's *attribution* identity, which must stay
/// meaningful for the life of a decades-lived document. Never a pointer
/// into an account system — the record carries the identity itself, so it
/// survives the death of whatever service verified it.
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
pub struct Identity {
    pub name: String,
    /// The stable id an account supplies once D15's authentication ships;
    /// `null` while identities are locally entered and unverified.
    #[serde(default)]
    pub id: Option<String>,
}

impl Identity {
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            id: None,
        }
    }

    /// The unverified local profile: the name the OS knows this user by.
    pub fn from_environment() -> Self {
        let name = std::env::var("USER")
            .or_else(|_| std::env::var("USERNAME"))
            .ok()
            .filter(|name| !name.is_empty())
            .unwrap_or_else(|| UNATTRIBUTED.to_owned());
        Self::new(name)
    }
}

/// Where the author was standing when a record was written: the blocks
/// descended into, outermost first, with the empty path meaning the
/// document root. Purely advisory (D18's neighbour in the punch list) —
/// replay parses it and nothing else reads it but the chrome.
#[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq, Eq)]
#[serde(transparent)]
pub struct ScopePath(Vec<BlockId>);

impl ScopePath {
    /// The document root, for a record nobody stood anywhere to write.
    pub const ROOT: Self = Self(Vec::new());

    pub fn segments(&self) -> &[BlockId] {
        &self.0
    }

    /// Whether the author was standing at the document root.
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }

    /// The block the author was inside — the innermost segment, which is
    /// the coordinate space a recorded camera is measured in.
    pub fn innermost(&self) -> Option<BlockId> {
        self.0.last().copied()
    }
}

impl FromIterator<BlockId> for ScopePath {
    fn from_iter<I: IntoIterator<Item = BlockId>>(ids: I) -> Self {
        Self(ids.into_iter().collect())
    }
}

/// Where the author was standing when a row was written: the world point
/// at the centre of their view, and how far in they were zoomed.
///
/// Centre-and-zoom rather than a rect (§10.1), so the view reproduces
/// sensibly at any window size — and recorded rather than derived,
/// because the view the author set is *evidence* of what they were
/// working on where a region computed from the change is only a guess.
/// The conversion to and from the canvas's own `Vantage` lives beside the
/// camera that has the viewport, in `canvas::view`.
#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq)]
pub struct Camera {
    pub x: f32,
    pub y: f32,
    pub zoom: f32,
}

impl Camera {
    /// A session nobody was looking through: a headless test, a seeded
    /// container, a command-line write. Recorded rather than left absent,
    /// so a row's shape never depends on whether there was a window.
    pub const UNSEEN: Self = Self {
        x: 0.0,
        y: 0.0,
        zoom: 1.0,
    };
}

/// Where the author was standing, in both spellings a row keeps: the
/// blocks the spotlight filters by, and the names §8.1's scope line
/// reads. Bundled rather than passed as two arguments, because names of a
/// different length than the ids they spell describe nowhere real.
#[derive(Clone, Copy)]
pub struct Standing<'a> {
    path: &'a ScopePath,
    names: &'a [String],
}

impl<'a> Standing<'a> {
    /// The document root — where a headless write stands.
    pub const ROOT: Standing<'static> = Standing {
        path: &ScopePath::ROOT,
        names: &[],
    };

    /// `names` spells `path`, outermost first, in the spelling the
    /// content path along the canvas bottom uses.
    pub fn new(path: &'a ScopePath, names: &'a [String]) -> Self {
        debug_assert_eq!(
            path.segments().len(),
            names.len(),
            "a scope's names must spell its own ids",
        );
        Self { path, names }
    }

    pub fn path(self) -> &'a ScopePath {
        self.path
    }

    pub fn names(self) -> &'a [String] {
        self.names
    }
}

/// Who wrote a row, where they were standing, and what they were looking
/// at. One argument rather than three, so a call site that has a path and
/// a camera can supply them without every call site that has neither
/// growing arguments: an `&Identity` converts into an unplaced
/// attribution on its own.
#[derive(Clone, Copy)]
pub struct Attribution<'a> {
    pub author: &'a Identity,
    pub standing: Standing<'a>,
    pub camera: Camera,
}

impl<'a> From<&'a Identity> for Attribution<'a> {
    fn from(author: &'a Identity) -> Self {
        Self {
            author,
            standing: Standing::ROOT,
            camera: Camera::UNSEEN,
        }
    }
}

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

    #[test]
    fn a_digest_survives_the_json_it_is_written_as() {
        let digest = Digest::of(b"a row");
        let text = serde_json::to_string(&digest).expect("a digest serializes");
        assert_eq!(text, format!("\"{digest}\""), "hex text, not a byte array");
        assert_eq!(
            serde_json::from_str::<Digest>(&text).expect("and parses back"),
            digest,
        );
    }

    #[test]
    fn a_digest_refuses_text_that_is_not_a_digest() {
        assert!(serde_json::from_str::<Digest>("\"deadbeef\"").is_err());
    }

    #[test]
    fn an_unnamed_environment_attributes_to_nobody_rather_than_to_an_empty_name() {
        assert!(!Identity::from_environment().name.is_empty());
        assert_eq!(Identity::new("ada").id, None);
    }

    /// An attribution with nothing behind it still carries a camera: a row
    /// records one whether or not anybody was looking (§10.1).
    #[test]
    fn an_unplaced_attribution_stands_at_the_origin_at_unity() {
        let author = Identity::new("ada");
        let by = Attribution::from(&author);
        assert!(by.standing.path().is_empty());
        assert!(by.standing.names().is_empty());
        assert_eq!(by.camera, Camera::UNSEEN);
    }

    #[test]
    fn a_scope_path_names_the_block_its_camera_is_measured_in() {
        let root = ScopePath::default();
        assert!(root.is_empty());
        assert_eq!(root.innermost(), None);

        let inside: ScopePath = [
            blockworx_doc::fixtures::block_id(1),
            blockworx_doc::fixtures::block_id(4),
        ]
        .into_iter()
        .collect();
        assert_eq!(
            inside.innermost(),
            Some(blockworx_doc::fixtures::block_id(4))
        );
        assert!(!inside.is_empty());
    }
}