blockworx_doc/

document.rs

//! The document root and the index derived from it.
//! Rationale: `docs/doc-ng-design-notes.md`.

use std::sync::Arc;

use crate::{
    block_model::{Area, Asset, Block, Image, Pin, Route, RouteLabel, Text},
    commit::Commit,
    entity::{Entity, entity},
    hash::{AssetHash, AssetKind, HashedMap},
    id::{
        Allocator, AreaId, BlockId, EntityRef, Id, IdKind, ImageId, PinId, RouteId, RouteLabelId,
        TextId,
    },
    opcode::{Crud, OpCodes},
    rev::{DocStamp, Rev},
};
use ahash::{HashMap, HashSet};
use serde::{Deserialize, Serialize, Serializer};
use std::collections::{BTreeMap, BTreeSet};

entity! {
    /// The document's own registers — a mechanical drawing's title
    /// block, expected to grow fields (author, revision notes, …). The
    /// singleton exception: never created by an op, no id, no
    /// lifecycle — `OpCodes::Document` is update-only.
    pub struct TitleBlock(update TitleBlockUpdate, id ()) {
        registers {
            Name => name: String,
            /// The designated root of the single-canvas view; `NULL` = no
            /// top yet (an empty document). A register, not a convention,
            /// so two concurrent Wrap Tops converge on the later one's
            /// root instead of leaving two.
            Top => top: BlockId,
        }
        namespaces {}
        constants {}
    }
}

/// The format version this build writes, and the guard against reading a
/// file from a newer one. Bumped whenever a change would make an older
/// reader *misinterpret* a file rather than fail on it.
///
/// 1. The original format: a nested tree, blocks in a list, `loc: "w1"`.
/// 2. Asset ids became content-derived.
/// 3. Flat and id-keyed: the [`Document`] is the file (`docs/json-format.md`).
pub const CURRENT_VERSION: u32 = 3;

#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[error("document format version {0} is newer than this build reads (up to {CURRENT_VERSION})")]
pub struct UnsupportedVersion(u32);

/// The version a file declares. A version from the future is refused at
/// the decode boundary rather than guessed at — the field exists precisely
/// because a newer writer may have used syntax this build would otherwise
/// misread as something else.
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
#[serde(try_from = "u32")]
pub struct FormatVersion(u32);

impl Default for FormatVersion {
    fn default() -> Self {
        FormatVersion(CURRENT_VERSION)
    }
}

impl TryFrom<u32> for FormatVersion {
    type Error = UnsupportedVersion;
    fn try_from(version: u32) -> Result<Self, Self::Error> {
        if version > CURRENT_VERSION {
            return Err(UnsupportedVersion(version));
        }
        Ok(FormatVersion(version))
    }
}

/// Everything the document *is*, and exactly what a file holds: the entity
/// tables keyed by id, the title block flattened over them, and the artwork
/// payloads. `BTreeMap` rather than a hash map so the file is written in id
/// order without a sorting pass to forget.
///
/// Split from the session state beside it in [`Document`] — the log
/// position, the value stamp, the allocator's marks — because those are
/// facts about this process's copy rather than about the drawing.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct Content {
    version: FormatVersion,
    #[serde(flatten)]
    title_block: TitleBlock,
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    blocks: BTreeMap<BlockId, Arc<Block>>,
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pins: BTreeMap<PinId, Arc<Pin>>,
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    routes: BTreeMap<RouteId, Arc<Route>>,
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    route_labels: BTreeMap<RouteLabelId, Arc<RouteLabel>>,
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    texts: BTreeMap<TextId, Arc<Text>>,
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    areas: BTreeMap<AreaId, Arc<Area>>,
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    images: BTreeMap<ImageId, Arc<Image>>,
    /// Artwork bytes, addressed by content. Not entities: no liveness and
    /// no lifecycle — a hash names one byte string forever, so the only
    /// question the table can answer is whether it is held.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    assets: HashedMap<AssetKind, Asset>,
}

/// Authored state only — the derived index is built beside it
/// ([`DocIndex`]). The document is the implicit root of the
/// containment tree: not an element, cannot be deleted, moved, or raced.
/// Blocks whose parent is `Id::NULL` live at document level.
///
/// Serializing a document writes its [`Content`] and nothing else, and
/// parsing one goes through [`From<Content>`](Document::from), which is
/// what keeps a document read off a file stamped and marked like one that
/// was folded.
#[derive(Clone, Debug, Deserialize)]
#[serde(from = "Content")]
pub struct Document {
    /// The head position in the log: the rev of the last commit folded in.
    /// Minted only by a successful [`Document::try_apply`], so a refused
    /// commit consumes no rev and the log cannot gap.
    rev: Rev,
    /// Names this value, not this position: two documents at one rev in
    /// two processes are unrelated. Minted wherever a distinct value is
    /// born — a successful fold, an empty document, a parsed file — and
    /// carried by `Clone`.
    stamp: DocStamp,
    /// Where the next id of each kind comes from. Derived, never stored:
    /// [`Self::try_apply`] raises a mark for every entity a commit names,
    /// deleted ones included, so folding a log leaves the marks past
    /// everything the document has ever held — which is why undoing a
    /// delete can re-create the entity under its own id and why a deleted
    /// id cannot come back on a different one. A document read off a file
    /// has no such history, so its marks come from what it holds.
    ids: Allocator,
    content: Content,
}

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

/// Value equality is over the content alone: `rev` is a position, and a
/// `DocStamp` is minted fresh for every distinct value, so comparing
/// either would make two readings of one file unequal.
impl PartialEq for Document {
    fn eq(&self, other: &Self) -> bool {
        self.content == other.content
    }
}

impl From<Content> for Document {
    fn from(content: Content) -> Self {
        let mut document = Document {
            rev: Rev::default(),
            stamp: DocStamp::next(),
            ids: Allocator::default(),
            content,
        };
        document.observe_own_ids();
        document
    }
}

impl Default for Document {
    fn default() -> Self {
        Content::default().into()
    }
}

impl Document {
    /// The log position this document holds: the rev of the last commit
    /// the [`Repo`](crate::repo::Repo) folded into it.
    pub fn rev(&self) -> Rev {
        self.rev
    }

    /// Names this value: the gate every derived cache beside the document
    /// re-checks before rebuilding, [`DocIndex`] included.
    pub fn stamp(&self) -> DocStamp {
        self.stamp
    }
    /// The document's own marks, as a value a client mints from.
    pub fn ids(&self) -> Allocator {
        self.ids
    }
    /// Take this value as the document at `rev`, in a session that has
    /// already got as far as `reached`: the position it is being adopted
    /// at, a stamp of its own since it is a distinct value in this
    /// process, and the one thing a session accumulates rather than holds
    /// — the allocator's marks — carried over from where it had got to.
    ///
    /// A mark never falls, here or in the fold: an id a taken-back edit
    /// minted is never minted again, which is what stops a restored
    /// entity's id being handed out a second time.
    ///
    /// Payloads are *not* carried. They live in the store, addressed by
    /// content and never deleted, so a rev that references one gets it
    /// back when it is read — and a rev that references none holds none,
    /// live or reopened.
    ///
    /// The door a history step comes through (`docs/log-vs-snapshot.md`),
    /// and the only way a rev moves without a fold.
    pub(crate) fn restored_at(&mut self, rev: Rev, reached: &Document) {
        self.rev = rev;
        self.stamp = DocStamp::next();
        self.ids.raise_to(&reached.ids);
    }

    /// Take this value as the document at `rev` — a rev file names its
    /// position in its own name, never inside itself, so the reader is what
    /// puts the two together.
    pub fn positioned_at(&mut self, rev: Rev) {
        self.rev = rev;
    }

    /// A fresh id of this document's own, for a caller with no gesture to
    /// mint through — the fold's own high-water mark advanced by one.
    pub fn mint<K: IdKind>(&mut self) -> Id<K> {
        self.ids.mint()
    }
    pub fn title_block(&self) -> &TitleBlock {
        &self.content.title_block
    }
    pub fn block(&self, id: &BlockId) -> Option<&Block> {
        self.content.blocks.get(id).map(Arc::as_ref)
    }
    pub fn blocks(&self) -> impl Iterator<Item = (BlockId, &Block)> {
        self.content
            .blocks
            .iter()
            .map(|(id, block)| (*id, block.as_ref()))
    }
    pub fn pin(&self, id: &PinId) -> Option<&Pin> {
        self.content.pins.get(id).map(Arc::as_ref)
    }
    pub fn pins(&self) -> impl Iterator<Item = (PinId, &Pin)> {
        self.content
            .pins
            .iter()
            .map(|(id, pin)| (*id, pin.as_ref()))
    }
    pub fn route(&self, id: &RouteId) -> Option<&Route> {
        self.content.routes.get(id).map(Arc::as_ref)
    }
    pub fn routes(&self) -> impl Iterator<Item = (RouteId, &Route)> {
        self.content
            .routes
            .iter()
            .map(|(id, route)| (*id, route.as_ref()))
    }
    pub fn route_label(&self, id: &RouteLabelId) -> Option<&RouteLabel> {
        self.content.route_labels.get(id).map(Arc::as_ref)
    }
    pub fn route_labels(&self) -> impl Iterator<Item = (RouteLabelId, &RouteLabel)> {
        self.content
            .route_labels
            .iter()
            .map(|(id, label)| (*id, label.as_ref()))
    }
    pub fn text(&self, id: &TextId) -> Option<&Text> {
        self.content.texts.get(id).map(Arc::as_ref)
    }
    pub fn texts(&self) -> impl Iterator<Item = (TextId, &Text)> {
        self.content
            .texts
            .iter()
            .map(|(id, text)| (*id, text.as_ref()))
    }
    pub fn area(&self, id: &AreaId) -> Option<&Area> {
        self.content.areas.get(id).map(Arc::as_ref)
    }
    pub fn areas(&self) -> impl Iterator<Item = (AreaId, &Area)> {
        self.content
            .areas
            .iter()
            .map(|(id, area)| (*id, area.as_ref()))
    }
    pub fn image(&self, id: &ImageId) -> Option<&Image> {
        self.content.images.get(id).map(Arc::as_ref)
    }
    pub fn images(&self) -> impl Iterator<Item = (ImageId, &Image)> {
        self.content
            .images
            .iter()
            .map(|(id, image)| (*id, image.as_ref()))
    }
    /// The payload behind an [`Image`]'s or [`Icon`](crate::block_model::Icon)'s
    /// hash. `None` while the reference is held but its payload op has not
    /// arrived — a legal, transient state that renders as nothing.
    pub fn asset(&self, hash: &AssetHash) -> Option<&Asset> {
        self.content.assets.get(hash)
    }
    /// Every payload the document holds, in hash order. Assets are
    /// create-only, so this is simply what is there.
    pub fn assets(&self) -> impl Iterator<Item = (AssetHash, &Asset)> {
        self.content
            .assets
            .iter()
            .map(|(hash, asset)| (*hash, asset))
    }
    pub fn try_apply(&self, commit: &Commit) -> Result<Document, FoldError> {
        let mut new_doc = self.clone();
        new_doc.rev = self.rev.next();
        new_doc.stamp = DocStamp::next();
        apply(&mut new_doc, commit)?;
        validate(&new_doc, commit)?;
        Ok(new_doc)
    }
    fn no_block_cycles(&self, id: BlockId) -> bool {
        let mut current = id;
        let mut seen = HashSet::default();
        while let Some(block) = self.block(&current) {
            if !seen.insert(current) {
                return false; // cycle detected
            }
            if block.parent == BlockId::NULL {
                break;
            }
            current = block.parent;
        }
        true
    }
    /// A commit that removed its target leaves nothing to check here:
    /// [`apply`] refuses an op whose target was absent to begin with, so
    /// a missing entity at this point is one this very commit deleted.
    fn validate_block_owner(&self, id: BlockId) -> Result<(), FoldError> {
        let Some(block) = self.block(&id) else {
            return Ok(());
        };
        if block.parent != BlockId::NULL && !self.content.blocks.contains_key(&block.parent) {
            return Err(FoldError::InvalidBlockParent(id, block.parent));
        }
        if !self.no_block_cycles(id) {
            return Err(FoldError::BlockCycle(id));
        }
        Ok(())
    }
    /// The document root is a scope like any other: `Id::NULL` names it,
    /// holds scoped entities, and is not a block — so it is never in the
    /// map and never needs to be.
    fn holds_scope(&self, scope: BlockId) -> bool {
        scope == BlockId::NULL || self.content.blocks.contains_key(&scope)
    }
    fn validate_pin_owner(&self, id: PinId) -> Result<(), FoldError> {
        let Some(pin) = self.pin(&id) else {
            return Ok(());
        };
        if !self.holds_scope(pin.owner) {
            return Err(FoldError::InvalidPinOwner(id, pin.owner));
        }
        Ok(())
    }
    fn validate_route_owner_and_endpoints(&self, id: RouteId) -> Result<(), FoldError> {
        let Some(route) = self.route(&id) else {
            return Ok(());
        };
        if !self.holds_scope(route.owner) {
            return Err(FoldError::InvalidRouteOwner(id, route.owner));
        }
        if !self.content.pins.contains_key(&route.from) {
            return Err(FoldError::InvalidRouteFrom(id, route.from));
        }
        if !self.content.pins.contains_key(&route.to) {
            return Err(FoldError::InvalidRouteTo(id, route.to));
        }
        Ok(())
    }
    fn validate_route_label_owner(&self, id: RouteLabelId) -> Result<(), FoldError> {
        let Some(label) = self.route_label(&id) else {
            return Ok(());
        };
        if !self.content.routes.contains_key(&label.owner) {
            return Err(FoldError::InvalidRouteLabelOwner(id, label.owner));
        }
        Ok(())
    }
    fn validate_text_owner(&self, id: TextId) -> Result<(), FoldError> {
        let Some(text) = self.text(&id) else {
            return Ok(());
        };
        if !self.holds_scope(text.owner) {
            return Err(FoldError::InvalidTextOwner(id, text.owner));
        }
        Ok(())
    }
    fn validate_area_owner(&self, id: AreaId) -> Result<(), FoldError> {
        let Some(area) = self.area(&id) else {
            return Ok(());
        };
        if !self.holds_scope(area.owner) {
            return Err(FoldError::InvalidAreaOwner(id, area.owner));
        }
        Ok(())
    }
    fn validate_image_owner(&self, id: ImageId) -> Result<(), FoldError> {
        let Some(image) = self.image(&id) else {
            return Ok(());
        };
        if !self.holds_scope(image.owner) {
            return Err(FoldError::InvalidImageOwner(id, image.owner));
        }
        Ok(())
    }

    /// Every mark this document's own content implies. A fold raises the
    /// marks as it goes; a document read off a file has only what it
    /// holds, which is why a parse goes through here.
    fn observe_own_ids(&mut self) {
        for id in self.content.blocks.keys() {
            self.ids.observe(EntityRef::Block(*id));
        }
        for id in self.content.pins.keys() {
            self.ids.observe(EntityRef::Pin(*id));
        }
        for id in self.content.routes.keys() {
            self.ids.observe(EntityRef::Route(*id));
        }
        for id in self.content.route_labels.keys() {
            self.ids.observe(EntityRef::RouteLabel(*id));
        }
        for id in self.content.texts.keys() {
            self.ids.observe(EntityRef::Text(*id));
        }
        for id in self.content.areas.keys() {
            self.ids.observe(EntityRef::Area(*id));
        }
        for id in self.content.images.keys() {
            self.ids.observe(EntityRef::Image(*id));
        }
    }

    /// The whole document as one labeled commit of creates, in dependency
    /// order — the one bridge from a parsed file to the log that builds
    /// it. Id-preserving: the ids in the file are the ids, and re-minting
    /// on paste into a populated document is
    /// [`edit::clipboard`](../../blockworx/edit/clipboard/index.html)'s
    /// job, not a loader's. `None` for a document with nothing in it.
    pub fn creating_commit(&self, label: &str) -> Option<Commit> {
        fn creates<'a, K, E>(
            table: &'a BTreeMap<Id<K>, Arc<E>>,
            op: impl Fn(Id<K>, Crud<E, E::Update>) -> OpCodes + 'a,
        ) -> impl Iterator<Item = OpCodes> + 'a
        where
            K: IdKind,
            E: Entity + Clone + 'a,
        {
            table
                .iter()
                .map(move |(id, entity)| op(*id, Crud::Create(E::clone(entity))))
        }
        let mut builder = crate::commit::CommitBuilder::new(label);
        builder.extend(
            self.content
                .assets
                .iter()
                .map(|(hash, asset)| OpCodes::Asset(*hash, asset.clone())),
        );
        builder.extend(creates(&self.content.blocks, OpCodes::Block));
        builder.extend(creates(&self.content.pins, OpCodes::Pin));
        builder.extend(creates(&self.content.routes, OpCodes::Route));
        builder.extend(creates(&self.content.route_labels, OpCodes::RouteLabel));
        builder.extend(creates(&self.content.texts, OpCodes::Text));
        builder.extend(creates(&self.content.areas, OpCodes::Area));
        builder.extend(creates(&self.content.images, OpCodes::Image));
        let title = &self.content.title_block;
        if !title.name.is_empty() {
            builder.push(OpCodes::Document(TitleBlockUpdate::Name(
                title.name.clone(),
            )));
        }
        if title.top != BlockId::NULL {
            builder.push(OpCodes::Document(TitleBlockUpdate::Top(title.top)));
        }
        builder.seal()
    }

    /// Every payload this document *references*: the artwork behind its
    /// icons and its images. Never the table's own keys — a payload
    /// outlives the reference that brought it in, so the table can hold
    /// bytes nothing points at.
    pub fn referenced_assets(&self) -> BTreeSet<AssetHash> {
        let icons = self
            .content
            .blocks
            .values()
            .map(|block| block.icon.asset)
            .filter(|hash| *hash != AssetHash::default());
        let images = self.content.images.values().map(|image| image.asset);
        icons.chain(images).collect()
    }

    /// This value with its payloads left behind — what a rev file is
    /// written from (`docs/log-vs-snapshot.md` §10). `assets/` is the one
    /// home for bytes, so a rev carries the references and the
    /// content-addressed store carries what they name; the entity tables
    /// are `Arc`s, so the clone is pointers.
    #[must_use]
    pub fn without_assets(&self) -> Document {
        let mut stripped = self.clone();
        stripped.content.assets.clear();
        stripped
    }

    /// Put back every payload this document references, asking `payload`
    /// for the bytes behind each hash — [`Self::without_assets`]'s other
    /// half.
    ///
    /// # Errors
    /// Whatever the source says about the first payload it will not hand
    /// back.
    pub fn attach_assets<E>(
        &mut self,
        mut payload: impl FnMut(AssetHash) -> Result<Asset, E>,
    ) -> Result<(), E> {
        for hash in self.referenced_assets() {
            if self.content.assets.contains_key(&hash) {
                continue;
            }
            self.content.assets.insert(hash, payload(hash)?);
        }
        Ok(())
    }
}

/// A document and the index over it, bundled so they cannot be mismatched.
///
/// The pairing is the guarantee. [`DocIndex::view`] is the only
/// constructor: it brings the index up to date against the very document
/// it then bundles, so consulting an index built from a *different*
/// document — the one hazard a derived index has, and the same mistake
/// class as reading the wrong document directly — is unrepresentable
/// rather than merely discouraged. Coherence beyond that is structural:
/// documents are immutable values, so a matched index cannot drift.
///
/// The refresh is gated on the document's stamp, so re-viewing a document
/// nothing has folded into costs one comparison; a rebuild happens only
/// where a new document value does.
///
/// A pair of shared references, so the view copies freely — the pairing
/// constructor is still the only way to *make* one.
#[non_exhaustive]
#[derive(Clone, Copy)]
pub struct IndexedDocument<'a> {
    pub doc: &'a Document,
    pub index: &'a DocIndex,
}

/// The derived index over the whole document — never authoritative. A
/// child whose owner has been deleted is indexed nowhere (its owner has
/// no entry).
///
/// Owned, and stamp-gated through [`Self::view`]: the third instance of
/// the pattern the app already runs for its spatial tree (`CachedIndex`)
/// and its route-accent propagation (`PinAccents`) — kept across frames,
/// rebuilt from the document value alone, so no mutation site has to
/// remember to invalidate it.
#[derive(Default)]
pub struct DocIndex {
    /// `None` until the first build; the empty index describes no
    /// document, not the empty one.
    built_from: Option<DocStamp>,
    /// Every block's scope, plus the document root under `Id::NULL` —
    /// whose `children` are the top-level blocks and whose other sets hold
    /// the entities owned by the root directly. A row here is a *scope*,
    /// which the root is and a block also is; [`Self::holds_block`] is the
    /// other question.
    pub blocks: HashMap<BlockId, BlockIndex>,
    pub routes: HashMap<RouteId, RouteIndex>,
    /// Every route, keyed by both endpoint pins — the adjacency the
    /// delete cascade and pin drags ask for.
    pub routes_by_endpoint: HashMap<PinId, HashSet<RouteId>>,
}

impl DocIndex {
    /// One linear pass over every kind. The ad-hoc path, for a caller
    /// with nowhere to keep an index between document values; a caller
    /// that has somewhere keeps one and calls [`Self::view`].
    pub fn of(doc: &Document) -> Self {
        let mut index = Self {
            built_from: Some(doc.stamp),
            blocks: doc
                .blocks()
                .map(|(id, _)| (id, BlockIndex::default()))
                .chain(std::iter::once((BlockId::NULL, BlockIndex::default())))
                .collect(),
            routes: doc
                .routes()
                .map(|(id, _)| (id, RouteIndex::default()))
                .collect(),
            routes_by_endpoint: HashMap::default(),
        };
        for (id, block) in doc.blocks() {
            if let Some(entry) = index.blocks.get_mut(&block.parent) {
                entry.children.insert(id);
            }
        }
        for (id, pin) in doc.pins() {
            if let Some(entry) = index.blocks.get_mut(&pin.owner) {
                entry.pins.insert(id);
            }
        }
        for (id, route) in doc.routes() {
            if let Some(entry) = index.blocks.get_mut(&route.owner) {
                entry.routes.insert(id);
            }
            for endpoint in [route.from, route.to] {
                index
                    .routes_by_endpoint
                    .entry(endpoint)
                    .or_default()
                    .insert(id);
            }
        }
        for (id, label) in doc.route_labels() {
            if let Some(entry) = index.routes.get_mut(&label.owner) {
                entry.labels.insert(id);
            }
        }
        for (id, text) in doc.texts() {
            if let Some(entry) = index.blocks.get_mut(&text.owner) {
                entry.texts.insert(id);
            }
        }
        for (id, area) in doc.areas() {
            if let Some(entry) = index.blocks.get_mut(&area.owner) {
                entry.areas.insert(id);
            }
        }
        for (id, image) in doc.images() {
            if let Some(entry) = index.blocks.get_mut(&image.owner) {
                entry.images.insert(id);
            }
        }
        index
    }

    /// The contents of `scope`: a block's interior, or the document root
    /// (`Id::NULL`). Every block has a row and so does the root, so a
    /// `None` here means the scope is gone, never that it is the root.
    pub fn scope(&self, id: BlockId) -> Option<&BlockIndex> {
        self.blocks.get(&id)
    }

    /// Whether `id` names a block the document holds. The root's row is a
    /// scope without an entity behind it — nothing can delete, move, or
    /// rename it — so it answers `false` here while still answering
    /// [`Self::scope`].
    pub fn holds_block(&self, id: BlockId) -> bool {
        id != BlockId::NULL && self.blocks.contains_key(&id)
    }

    /// `doc` bundled with this index, rebuilt first unless it was already
    /// built from that very document value.
    pub fn view<'a>(&'a mut self, doc: &'a Document) -> IndexedDocument<'a> {
        if self.built_from != Some(doc.stamp) {
            *self = Self::of(doc);
        }
        IndexedDocument { doc, index: self }
    }

    /// The view over the document value this index was built from, and
    /// `None` for any other — the read-only door, for a caller holding a
    /// document and an index it built together and with no `&mut` to
    /// rebuild through. Refusing the mismatched pair is the whole point:
    /// it is the same check [`Self::view`] makes, minus the repair.
    pub fn view_of<'a>(&'a self, doc: &'a Document) -> Option<IndexedDocument<'a>> {
        (self.built_from == Some(doc.stamp)).then_some(IndexedDocument { doc, index: self })
    }
}

#[derive(Debug, Default, PartialEq, Eq)]
pub struct BlockIndex {
    pub pins: HashSet<PinId>,
    pub routes: HashSet<RouteId>,
    pub texts: HashSet<TextId>,
    pub areas: HashSet<AreaId>,
    pub images: HashSet<ImageId>,
    pub children: HashSet<BlockId>,
}

#[derive(Debug, Default, PartialEq, Eq)]
pub struct RouteIndex {
    pub labels: HashSet<RouteLabelId>,
}

/// One order, every consumer (`docs/doc-ng-design-notes.md`, "Draw order
/// is a derived policy"): ascending id — which is creation order, ids
/// being monotonic counters — so painting in this order puts the newest
/// entity on top. Hit-testing walks it back-to-front and the router
/// places first-come-first-served, so the three cannot disagree.
pub fn chronological<'a, K, T>(entries: impl Iterator<Item = (Id<K>, &'a T)>) -> Vec<Id<K>>
where
    K: crate::id::IdKind,
    T: 'a,
{
    let mut ids: Vec<Id<K>> = entries.map(|(id, _)| id).collect();
    ids.sort();
    ids
}

#[derive(Clone, PartialEq, Eq, Debug, thiserror::Error)]
pub enum FoldError {
    #[error("invalid block id {0}")]
    InvalidBlockId(BlockId),
    #[error("invalid pin id {0}")]
    InvalidPinId(PinId),
    #[error("invalid route id {0}")]
    InvalidRouteId(RouteId),
    #[error("invalid route label id {0}")]
    InvalidRouteLabelId(RouteLabelId),
    #[error("invalid text id {0}")]
    InvalidTextId(TextId),
    #[error("invalid area id {0}")]
    InvalidAreaId(AreaId),
    #[error("invalid image id {0}")]
    InvalidImageId(ImageId),
    #[error("Block {0} parent {1} is not a block in the document")]
    InvalidBlockParent(BlockId, BlockId),
    #[error("Pin {0} owner {1} is not a block in the document")]
    InvalidPinOwner(PinId, BlockId),
    #[error("Route {0} owner {1} is not a block in the document")]
    InvalidRouteOwner(RouteId, BlockId),
    #[error("Route {0} from pin {1} is not a pin in the document")]
    InvalidRouteFrom(RouteId, PinId),
    #[error("Route {0} to pin {1} is not a pin in the document")]
    InvalidRouteTo(RouteId, PinId),
    #[error("RouteLabel {0} owner {1} is not a route in the document")]
    InvalidRouteLabelOwner(RouteLabelId, RouteId),
    #[error("Text {0} owner {1} is not a block in the document")]
    InvalidTextOwner(TextId, BlockId),
    #[error("Area {0} owner {1} is not a block in the document")]
    InvalidAreaOwner(AreaId, BlockId),
    #[error("top {0} is not a block in the document")]
    InvalidTop(BlockId),
    #[error("Image {0} owner {1} is not a block in the document")]
    InvalidImageOwner(ImageId, BlockId),
    #[error("Block {0} is in a cycle of parent links")]
    BlockCycle(BlockId),
    #[error("the payload filed under asset {0} does not hash to it")]
    AssetHashMismatch(AssetHash),
    #[error("asset {0} is {1} bytes, over the {limit}-byte limit", limit = crate::block_model::ASSET_LIMIT)]
    AssetTooLarge(AssetHash, usize),
}

fn apply(doc: &mut Document, commit: &Commit) -> Result<(), FoldError> {
    for op in commit.ops() {
        doc.ids.observe(op.target());
        match op {
            OpCodes::Document(update) => {
                doc.content.title_block.apply(update);
            }
            OpCodes::Block(id, crud) => {
                apply_crud_to_entity(&mut doc.content.blocks, *id, crud)
                    .ok_or(FoldError::InvalidBlockId(*id))?;
            }
            OpCodes::Pin(id, crud) => {
                apply_crud_to_entity(&mut doc.content.pins, *id, crud)
                    .ok_or(FoldError::InvalidPinId(*id))?;
            }
            OpCodes::Route(id, crud) => {
                apply_crud_to_entity(&mut doc.content.routes, *id, crud)
                    .ok_or(FoldError::InvalidRouteId(*id))?;
            }
            OpCodes::RouteLabel(id, crud) => {
                apply_crud_to_entity(&mut doc.content.route_labels, *id, crud)
                    .ok_or(FoldError::InvalidRouteLabelId(*id))?;
            }
            OpCodes::Text(id, crud) => {
                apply_crud_to_entity(&mut doc.content.texts, *id, crud)
                    .ok_or(FoldError::InvalidTextId(*id))?;
            }
            OpCodes::Area(id, crud) => {
                apply_crud_to_entity(&mut doc.content.areas, *id, crud)
                    .ok_or(FoldError::InvalidAreaId(*id))?;
            }
            OpCodes::Image(id, crud) => {
                apply_crud_to_entity(&mut doc.content.images, *id, crud)
                    .ok_or(FoldError::InvalidImageId(*id))?;
            }
            OpCodes::Asset(hash, asset) => {
                doc.content
                    .assets
                    .entry(*hash)
                    .or_insert_with(|| asset.clone());
            }
        }
    }
    Ok(())
}

/// Run against the *folded* document, so an op's position within the
/// commit never matters: a cascade may delete a pin before or after the
/// route hanging off it and be judged the same either way.
fn validate(doc: &Document, commit: &Commit) -> Result<(), FoldError> {
    dangling_endpoints(doc, commit)?;
    for op in commit.ops() {
        match op {
            OpCodes::Block(id, _) => {
                doc.validate_block_owner(*id)?;
            }
            OpCodes::Pin(id, _) => {
                doc.validate_pin_owner(*id)?;
            }
            OpCodes::Route(id, _) => {
                doc.validate_route_owner_and_endpoints(*id)?;
            }
            OpCodes::RouteLabel(id, _) => {
                doc.validate_route_label_owner(*id)?;
            }
            OpCodes::Text(id, _) => {
                doc.validate_text_owner(*id)?;
            }
            OpCodes::Area(id, _) => {
                doc.validate_area_owner(*id)?;
            }
            OpCodes::Image(id, _) => {
                doc.validate_image_owner(*id)?;
            }
            OpCodes::Asset(hash, asset) => {
                // Content addressing is only an invariant if someone checks
                // it: a payload filed under a hash it does not have would
                // make one key name two byte strings, and every replica's
                // "same hash ⇒ same bytes" reasoning with it.
                if asset.hash() != *hash {
                    return Err(FoldError::AssetHashMismatch(*hash));
                }
                // Unbounded here is unbounded forever: the log is replayed
                // in full on every open, so a payload nobody bounded is one
                // the document carries for its whole life.
                if !asset.within_limit() {
                    return Err(FoldError::AssetTooLarge(*hash, asset.bytes().len()));
                }
            }
            OpCodes::Document(_) => {
                // Existence-only, like route endpoints: anything stricter
                // ("top's parent must be NULL") is breakable by a
                // concurrent reparent, and a well-behaved client is never
                // rejected by a race it could not see.
                let top = doc.title_block().top;
                if top != BlockId::NULL && !doc.content.blocks.contains_key(&top) {
                    return Err(FoldError::InvalidTop(top));
                }
            }
        }
    }
    Ok(())
}

/// A route's endpoints are the one reference the index cannot quietly
/// drop: an orphaned route is still indexed and still drawn, whereas a
/// child whose owner is gone leaves the index with its scope. So a pin
/// may not leave under a route — the delete cascade emits the dependent
/// route deletes itself, which is what keeps this refusal unreachable
/// from the editor.
fn dangling_endpoints(doc: &Document, commit: &Commit) -> Result<(), FoldError> {
    let removed: HashSet<PinId> = commit
        .ops()
        .iter()
        .filter_map(|op| match op {
            OpCodes::Pin(id, Crud::Delete) => Some(*id),
            _ => None,
        })
        .collect();
    if removed.is_empty() {
        return Ok(());
    }
    let mut dangling: Vec<(RouteId, &Route)> = doc
        .routes()
        .filter(|(_, route)| removed.contains(&route.from) || removed.contains(&route.to))
        .collect();
    dangling.sort_by_key(|(id, _)| *id);
    match dangling.first() {
        None => Ok(()),
        Some((id, route)) if removed.contains(&route.from) => {
            Err(FoldError::InvalidRouteFrom(*id, route.from))
        }
        Some((id, route)) => Err(FoldError::InvalidRouteTo(*id, route.to)),
    }
}

/// `None` means the id is invalid for the op: unknown for
/// `Update`/`Delete`, already taken for `Create` — the allocator never
/// re-mints a number the document has held, so a duplicate create is a
/// replay or a bug, never a merge.
fn apply_crud_to_entity<E: Entity + Clone>(
    map: &mut BTreeMap<E::Id, Arc<E>>,
    id: E::Id,
    crud: &Crud<E, E::Update>,
) -> Option<()> {
    match crud {
        Crud::Create(entity) => {
            if map.contains_key(&id) {
                return None;
            }
            map.insert(id, Arc::new(entity.clone()));
            Some(())
        }
        Crud::Update(update) => {
            Arc::make_mut(map.get_mut(&id)?).apply(update);
            Some(())
        }
        Crud::Delete => map.remove(&id).map(|_| ()),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::fixtures::{area_id, block_id, image_id, pin_id, route_id, route_label_id, text_id};
    use crate::{
        block_model::{
            Area, Block, BlockUpdate, Icon, Image, Label, Pin, PinUpdate, Route, RouteLabel, Text,
        },
        geometry::{FracVal, GridPoint, GridRect, GridSize, PinSlot, ScreenRect},
        values::{LabelSide, PinDir, PinSide, Role},
    };

    fn rename(name: &str) -> Commit {
        Commit::new(
            "Renamed the document".into(),
            vec![OpCodes::Document(TitleBlockUpdate::Name(name.into()))],
        )
    }

    fn label_init(name: String) -> Label {
        Label {
            name,
            side: LabelSide::default(),
            offset: FracVal::default(),
            hidden: false,
        }
    }

    fn block_create(n: u32) -> OpCodes {
        OpCodes::Block(
            block_id(n),
            Crud::Create(Block {
                parent: BlockId::NULL,
                rect: GridRect::default(),
                locked: false,
                role: Role::default(),
                title: label_init(format!("b{n}")),
                type_label: label_init(String::new()),
                icon: Icon::default(),
            }),
        )
    }

    fn route_create(n: u32, owner: u32, from: u32, to: u32) -> OpCodes {
        OpCodes::Route(
            route_id(n),
            Crud::Create(Route {
                owner: block_id(owner),
                name: format!("r{n}"),
                from: pin_id(from),
                to: pin_id(to),
                role: Role::default(),
                waypoints: Vec::new(),
            }),
        )
    }

    /// Block 1 top-level with block 2 nested under it; pins 3 and 4 on
    /// block 1; route 5 between them owned by block 1; route label 6 on
    /// the route; text 7, area 8, image 9 on block 1.
    fn wired_document() -> Document {
        Document::default()
            .try_apply(&Commit::new(
                "Wired a document".into(),
                vec![
                    block_create(1),
                    block_create(2),
                    reparent(2, 1),
                    pin_create(3, block_id(1)),
                    pin_create(4, block_id(1)),
                    route_create(5, 1, 3, 4),
                    OpCodes::RouteLabel(
                        route_label_id(6),
                        Crud::Create(RouteLabel {
                            owner: route_id(5),
                            pos: FracVal::default(),
                        }),
                    ),
                    OpCodes::Text(
                        text_id(7),
                        Crud::Create(Text {
                            owner: block_id(1),
                            text: "note".into(),
                            pos: GridPoint::default(),
                            role: Role::default(),
                            width: None,
                        }),
                    ),
                    OpCodes::Area(
                        area_id(8),
                        Crud::Create(Area {
                            owner: block_id(1),
                            rect: GridRect::default(),
                            role: Role::default(),
                            title: label_init("c8".into()),
                        }),
                    ),
                    OpCodes::Image(
                        image_id(9),
                        Crud::Create(Image {
                            owner: block_id(1),
                            asset: AssetHash::default(),
                            rect: ScreenRect::default(),
                        }),
                    ),
                ],
            ))
            .expect("the fold succeeds")
    }

    fn reparent(child: u32, parent: u32) -> OpCodes {
        OpCodes::Block(
            block_id(child),
            Crud::Update(BlockUpdate::Parent(block_id(parent))),
        )
    }

    fn rect(x: i32, y: i32) -> GridRect {
        GridRect {
            top_left: GridPoint { x, y },
            size: GridSize { w: 4, h: 4 },
        }
    }

    fn resize(block: u32, to: GridRect) -> OpCodes {
        OpCodes::Block(block_id(block), Crud::Update(BlockUpdate::Rect(to)))
    }

    fn rename_pin(n: u32, name: &str) -> OpCodes {
        OpCodes::Pin(pin_id(n), Crud::Update(PinUpdate::Name(name.into())))
    }

    fn pin_delete(n: u32) -> OpCodes {
        OpCodes::Pin(pin_id(n), Crud::Delete)
    }

    fn block_with_pin() -> Document {
        Document::default()
            .try_apply(&Commit::new(
                "Added a block with a pin".into(),
                vec![block_create(1), pin_create(2, block_id(1))],
            ))
            .expect("the fold succeeds")
    }

    fn pin_create(n: u32, owner: BlockId) -> OpCodes {
        OpCodes::Pin(
            pin_id(n),
            Crud::Create(Pin {
                owner,
                name: format!("p{n}"),
                type_name: String::new(),
                tag: String::new(),
                tag_hidden: false,
                rect: GridRect::default(),
                slot: PinSlot::default(),
                dir: PinDir::default(),
                port_accent: Role::default(),
                flip_lr: false,
            }),
        )
    }

    #[test]
    fn a_name_update_folds_into_a_new_document_and_the_source_stays_frozen() {
        let doc = Document::default();

        let next = doc
            .try_apply(&rename("drawing"))
            .expect("the fold succeeds");
        assert_eq!(next.rev(), Rev::new(1), "the fold mints the successor rev");
        assert_eq!(next.title_block().name.as_str(), "drawing");
        assert_eq!(doc.rev(), Rev::ZERO, "the source document is frozen");
        assert_eq!(
            doc.title_block().name.as_str(),
            "",
            "the source document is frozen"
        );
    }

    /// A block's accent is authored state, so two writes to it resolve in
    /// fold order.
    #[test]
    fn a_block_role_folds_and_the_later_write_wins() {
        let doc = Document::default()
            .try_apply(&Commit::new("Added b1".into(), vec![block_create(1)]))
            .expect("the create folds");

        let recolor = |role| {
            Commit::new(
                "Recolored".into(),
                vec![OpCodes::Block(
                    block_id(1),
                    Crud::Update(BlockUpdate::Role(role)),
                )],
            )
        };
        let next = doc
            .try_apply(&recolor(Role::Accent3))
            .expect("the first recolor folds")
            .try_apply(&recolor(Role::Accent5))
            .expect("the second recolor folds");

        let block = next.block(&block_id(1)).expect("the block is held");
        assert_eq!(block.role, Role::Accent5);
    }

    /// Wrap Top's exact commit shape — create the new root, reparent the
    /// old, point `top` at it — folds as one commit, and a later `top`
    /// write displaces an earlier one whole (LWW, like any register).
    #[test]
    fn wrap_top_folds_and_the_later_top_wins() {
        let set_top = |n| OpCodes::Document(TitleBlockUpdate::Top(block_id(n)));
        let doc = Document::default()
            .try_apply(&Commit::new(
                "Added b1".into(),
                vec![block_create(1), set_top(1)],
            ))
            .expect("the create folds")
            .try_apply(&Commit::new(
                "Wrapped the top".into(),
                vec![block_create(2), reparent(1, 2), set_top(2)],
            ))
            .expect("the wrap folds");

        assert_eq!(doc.title_block().top, block_id(2));
        assert_eq!(
            doc.block(&block_id(1)).expect("the old top is held").parent,
            block_id(2),
        );
    }

    /// Existence-only, but existence is checked: a top naming a block the
    /// document does not hold is refused, and `NULL` stays legal ("no top
    /// yet").
    #[test]
    fn a_top_naming_an_unknown_block_is_refused() {
        let doc = Document::default();
        let unknown = block_id(7);

        let refused = doc.try_apply(&Commit::new(
            "Pointed top nowhere".into(),
            vec![OpCodes::Document(TitleBlockUpdate::Top(unknown))],
        ));
        assert_eq!(refused.err(), Some(FoldError::InvalidTop(unknown)));

        doc.try_apply(&Commit::new(
            "Cleared the top".into(),
            vec![OpCodes::Document(TitleBlockUpdate::Top(BlockId::NULL))],
        ))
        .expect("NULL is the meaningful zero, not a reference");
    }

    /// The slot is one register by design: concurrent writers race whole
    /// `(side, offset)` pairs, so a merge can never land one write's edge
    /// under another's offset.
    #[test]
    fn concurrent_slot_writes_race_as_whole_pairs() {
        let doc = block_with_pin();

        let move_to = |slot| {
            Commit::new(
                "Moved a pin".into(),
                vec![OpCodes::Pin(pin_id(2), Crud::Update(PinUpdate::Slot(slot)))],
            )
        };
        let east_3 = PinSlot {
            side: PinSide::East,
            offset: 3,
        };
        let west_9 = PinSlot {
            side: PinSide::West,
            offset: 9,
        };
        let next = doc
            .try_apply(&move_to(east_3))
            .expect("the first move folds")
            .try_apply(&move_to(west_9))
            .expect("the second move folds");

        let pin = next.pin(&pin_id(2)).expect("the pin is held");
        assert_eq!(pin.slot, west_9, "the later pair wins whole");
    }

    /// The atomicity contract: an op that cannot resolve refuses the whole
    /// commit — no successor document exists, so a partial application is
    /// unrepresentable.
    #[test]
    fn a_bad_op_refuses_the_whole_commit() {
        let doc = Document::default();
        let unknown = block_id(7);
        let commit = Commit::new(
            "Deleted a block".into(),
            vec![
                OpCodes::Document(TitleBlockUpdate::Name("drawing".into())),
                OpCodes::Block(unknown, Crud::Delete),
            ],
        );

        let Err(error) = doc.try_apply(&commit) else {
            panic!("a delete of an unknown id must refuse the commit");
        };
        assert_eq!(error, FoldError::InvalidBlockId(unknown));
    }

    /// Refusal is rev-neutral: the next accepted commit lands on the rev
    /// the refused one would have taken, so the log cannot gap.
    #[test]
    fn a_refused_commit_mints_no_rev() {
        let doc = Document::default()
            .try_apply(&rename("drawing"))
            .expect("the fold succeeds");
        assert_eq!(doc.rev(), Rev::new(1));

        let unknown = block_id(7);
        let bad = Commit::new(
            "Deleted a block".into(),
            vec![OpCodes::Block(unknown, Crud::Delete)],
        );
        assert!(doc.try_apply(&bad).is_err());

        let next = doc
            .try_apply(&rename("schematic"))
            .expect("the fold succeeds");
        assert_eq!(next.rev(), Rev::new(2));
    }

    /// The tables iterate in id order whatever order they were written in —
    /// the one property the file's diffs and the content hash both rest on,
    /// and now the table type's own rather than a sorting pass someone has to
    /// remember.
    #[test]
    fn the_tables_iterate_in_id_order_whatever_order_they_were_written_in() {
        let written: Vec<u32> = vec![12, 3, 7, 1, 9];
        let doc = Document::default()
            .try_apply(&Commit::new(
                "Created five blocks".into(),
                written.iter().copied().map(block_create).collect(),
            ))
            .expect("the fold succeeds");
        assert_ne!(
            written,
            {
                let mut sorted = written.clone();
                sorted.sort_unstable();
                sorted
            },
            "the fixture must write out of order or the ordering is untested"
        );
        assert_eq!(
            doc.blocks().map(|(id, _)| id).collect::<Vec<_>>(),
            [1, 3, 7, 9, 12].map(block_id),
        );
    }

    /// A rev file is written from a document with its payloads left
    /// behind, and read back with the ones it references put in — so the
    /// pair must be a round trip, and must reach into `assets/` for
    /// exactly what the document points at.
    #[test]
    fn stripping_and_re_attaching_payloads_is_a_round_trip() {
        let held = png(b"artwork");
        let orphan = png(b"nobody points at this");
        let document = Document::default()
            .try_apply(&Commit::new(
                "Placed it".into(),
                vec![payload(&held), payload(&orphan), image_create(1, 0, &held)],
            ))
            .expect("the fold succeeds");
        assert_eq!(
            document.assets().count(),
            2,
            "precondition: the table holds a payload nothing references",
        );
        assert_eq!(
            document.referenced_assets(),
            std::collections::BTreeSet::from([held.hash()]),
        );

        let stripped = document.without_assets();
        assert_eq!(stripped.assets().count(), 0, "the rev file carries bytes");
        assert_ne!(stripped, document);

        let mut attached = stripped;
        let store = [(held.hash(), held.clone()), (orphan.hash(), orphan)];
        attached
            .attach_assets(|hash| {
                store
                    .iter()
                    .find(|(named, _)| *named == hash)
                    .map(|(_, asset)| asset.clone())
                    .ok_or(hash)
            })
            .expect("the store holds what the document references");
        assert_eq!(attached.asset(&held.hash()), Some(&held));
        assert_eq!(
            attached.assets().count(),
            1,
            "the unreferenced payload is not read back: nothing names it",
        );
    }

    /// A reference the store cannot honour is the reader's fault to
    /// report, not something to leave silently missing.
    #[test]
    fn attaching_reports_the_payload_the_store_will_not_hand_back() {
        let held = png(b"artwork");
        let mut document = Document::default()
            .try_apply(&Commit::new(
                "Placed it".into(),
                vec![payload(&held), image_create(1, 0, &held)],
            ))
            .expect("the fold succeeds")
            .without_assets();
        assert_eq!(document.attach_assets(Err::<Asset, _>), Err(held.hash()),);
    }

    /// Payload references validate against the commit's *final* view, so
    /// op order inside a commit is free: a pin may precede its owner's
    /// create. An owner the document never sees refuses the whole commit.
    #[test]
    fn a_pin_needs_its_owner_block() {
        let owner = block_id(1);
        let good = Commit::new(
            "Added a block with a pin".into(),
            vec![pin_create(2, owner), block_create(1)],
        );
        let doc = Document::default()
            .try_apply(&good)
            .expect("an owner created anywhere in the commit resolves");
        assert!(doc.pin(&pin_id(2)).is_some());

        let stranger = block_id(9);
        let bad = Commit::new("Added an orphan pin".into(), vec![pin_create(3, stranger)]);
        let Err(error) = doc.try_apply(&bad) else {
            panic!("a pin with an unknown owner must refuse the commit");
        };
        assert_eq!(error, FoldError::InvalidPinOwner(pin_id(3), stranger));
        assert!(
            doc.pin(&pin_id(3)).is_none(),
            "the refused create must leave no trace"
        );
    }

    /// The update path revalidates too: re-owning a pin to an unknown
    /// block is refused even though the write itself applied cleanly —
    /// the trial fold discards the whole successor.
    #[test]
    fn an_owner_update_to_an_unknown_block_is_refused() {
        let owner = block_id(1);
        let doc = Document::default()
            .try_apply(&Commit::new(
                "Added a block with a pin".into(),
                vec![block_create(1), pin_create(2, owner)],
            ))
            .expect("the fold succeeds");

        let stranger = block_id(9);
        let reown = Commit::new(
            "Re-owned the pin".into(),
            vec![OpCodes::Pin(
                pin_id(2),
                Crud::Update(PinUpdate::Owner(stranger)),
            )],
        );
        let Err(error) = doc.try_apply(&reown) else {
            panic!("re-owning to an unknown block must refuse the commit");
        };
        assert_eq!(error, FoldError::InvalidPinOwner(pin_id(2), stranger));
        assert_eq!(
            doc.pin(&pin_id(2)).map(|pin| pin.owner),
            Some(owner),
            "the source document still holds the valid owner"
        );
    }

    /// The one global check: parent writes that close a loop are refused —
    /// across commits, within one commit, and the self-parent degenerate.
    #[test]
    fn a_parent_cycle_is_refused() {
        let doc = Document::default()
            .try_apply(&Commit::new(
                "Added two blocks".into(),
                vec![block_create(1), block_create(2)],
            ))
            .expect("the fold succeeds");

        let nested = doc
            .try_apply(&Commit::new(
                "Nested 1 under 2".into(),
                vec![reparent(1, 2)],
            ))
            .expect("a loop-free reparent lands");
        assert_eq!(
            nested.block(&block_id(1)).map(|block| block.parent),
            Some(block_id(2)),
            "the fixture must nest or the loop below tests nothing"
        );

        let Err(error) =
            nested.try_apply(&Commit::new("Closed the loop".into(), vec![reparent(2, 1)]))
        else {
            panic!("closing a parent loop must refuse the commit");
        };
        assert_eq!(error, FoldError::BlockCycle(block_id(2)));

        let Err(error) = doc.try_apply(&Commit::new(
            "Swapped parents".into(),
            vec![reparent(1, 2), reparent(2, 1)],
        )) else {
            panic!("a loop closed within one commit must refuse it");
        };
        assert_eq!(error, FoldError::BlockCycle(block_id(1)));

        let Err(error) = doc.try_apply(&Commit::new("Self parent".into(), vec![reparent(1, 1)]))
        else {
            panic!("a self-parent must refuse the commit");
        };
        assert_eq!(error, FoldError::BlockCycle(block_id(1)));
    }

    /// Donor: `a_batch_writing_one_register_twice_ends_on_its_last_write`.
    /// One commit's writes land in push order, end to end: the last one
    /// stands.
    #[test]
    fn a_commit_writing_one_register_twice_ends_on_its_last_write() {
        let commit = Commit::new(
            "Created and nudged a block".into(),
            vec![
                block_create(1),
                resize(1, rect(1, 1)),
                resize(1, rect(2, 2)),
            ],
        );
        let doc = Document::default()
            .try_apply(&commit)
            .expect("the fold succeeds");

        let block = doc.block(&block_id(1)).expect("created");
        assert_eq!(block.rect, rect(2, 2));
    }

    /// Donor: `concurrent_writes_converge_whichever_order_they_arrive`,
    /// re-based for minted revs — apply order *is* rev order now, so what
    /// remains provable end to end is that a later commit's write
    /// displaces an earlier one's while untouched fields stand.
    #[test]
    fn a_later_commits_write_displaces_an_earlier_ones() {
        let doc = Document::default()
            .try_apply(&Commit::new("Added a block".into(), vec![block_create(1)]))
            .expect("the fold succeeds")
            .try_apply(&Commit::new("Moved it".into(), vec![resize(1, rect(1, 1))]))
            .expect("the fold succeeds")
            .try_apply(&Commit::new(
                "Moved it again".into(),
                vec![resize(1, rect(2, 2))],
            ))
            .expect("the fold succeeds");

        let block = doc.block(&block_id(1)).expect("created");
        assert_eq!(block.rect, rect(2, 2));
        assert!(!block.locked, "untouched fields keep their created value");
    }

    /// Donor: `deleting_hides_an_element_but_keeps_it_restorable`. A
    /// delete is a removal, so the identity leaves the document with the
    /// value — and a second delete has nothing to remove.
    #[test]
    fn deleting_removes_an_entity_and_a_second_delete_refuses() {
        let deleted = block_with_pin()
            .try_apply(&Commit::new("Deleted the pin".into(), vec![pin_delete(2)]))
            .expect("the fold succeeds");
        assert!(deleted.pin(&pin_id(2)).is_none());

        let Err(error) = deleted.try_apply(&Commit::new(
            "Deleted the pin again".into(),
            vec![pin_delete(2)],
        )) else {
            panic!("a delete at an absent target must refuse");
        };
        assert_eq!(error, FoldError::InvalidPinId(pin_id(2)));
    }

    /// Nothing retains an inner to absorb an edit at a removed target, so
    /// the update refuses the whole commit — which is what makes the
    /// emitters' "push nothing at an absent target" a checked rule
    /// rather than a convention.
    #[test]
    fn an_edit_after_a_delete_refuses_the_commit() {
        let deleted = block_with_pin()
            .try_apply(&Commit::new("Deleted the pin".into(), vec![pin_delete(2)]))
            .expect("the fold succeeds");
        let Err(error) = deleted.try_apply(&Commit::new(
            "Renamed the pin".into(),
            vec![rename_pin(2, "clk")],
        )) else {
            panic!("an update at an absent target must refuse");
        };
        assert_eq!(error, FoldError::InvalidPinId(pin_id(2)));
    }

    /// A delete frees nothing: the fold observes every id the log names,
    /// so the marks stay past a departed entity and a create can put the
    /// id back — which is how the journal undoes a delete.
    #[test]
    fn a_deleted_id_is_never_reissued_but_can_be_re_created() {
        let mut deleted = block_with_pin()
            .try_apply(&Commit::new("Deleted the pin".into(), vec![pin_delete(2)]))
            .expect("the fold succeeds");
        assert_ne!(deleted.mint::<crate::id::PinKind>(), pin_id(2));

        let back = deleted
            .try_apply(&Commit::new(
                "Put the pin back".into(),
                vec![pin_create(2, block_id(1))],
            ))
            .expect("a create under a departed id folds");
        assert!(back.pin(&pin_id(2)).is_some());
    }

    /// Donor: `replay_is_a_function_of_the_log_alone` +
    /// `replicas_agree_byte_for_byte_not_just_structurally` — the hash is
    /// the pivot's `state_to_bytes`. Covers the lifecycle ops too.
    #[test]
    fn replay_is_a_function_of_the_log_alone() {
        let log = [
            Commit::new(
                "Added a block with a pin".into(),
                vec![block_create(1), pin_create(2, block_id(1))],
            ),
            Commit::new("Renamed the pin".into(), vec![rename_pin(2, "clk")]),
            Commit::new("Deleted the pin".into(), vec![pin_delete(2)]),
        ];
        let replay = || {
            log.iter()
                .try_fold(Document::default(), |doc, commit| doc.try_apply(commit))
        };

        let one = replay().expect("the fold succeeds");
        let other = replay().expect("the fold succeeds");
        assert_eq!(
            one.rev(),
            Rev::new(3),
            "the fixture must fold the whole log"
        );
        assert_eq!(one, other);
    }

    #[test]
    fn the_index_covers_every_kind_and_the_containment_tree() {
        let doc = wired_document();
        let index = DocIndex::of(&doc);

        assert_eq!(
            index.blocks[&BlockId::NULL].children,
            [block_id(1)].into_iter().collect()
        );
        let entry = &index.blocks[&block_id(1)];
        assert_eq!(entry.children, [block_id(2)].into_iter().collect());
        assert_eq!(entry.pins, [pin_id(3), pin_id(4)].into_iter().collect());
        assert_eq!(entry.routes, [route_id(5)].into_iter().collect());
        assert_eq!(entry.texts, [text_id(7)].into_iter().collect());
        assert_eq!(entry.areas, [area_id(8)].into_iter().collect());
        assert_eq!(entry.images, [image_id(9)].into_iter().collect());
        assert_eq!(
            index.blocks[&block_id(2)],
            BlockIndex::default(),
            "the nested block owns nothing"
        );
        assert_eq!(
            index.routes[&route_id(5)].labels,
            [route_label_id(6)].into_iter().collect()
        );
    }

    /// Every way a distinct document value is born mints, and only
    /// `Clone` — which produces no new value — carries.
    #[test]
    fn a_born_document_value_mints_a_stamp_and_a_clone_carries_it() {
        let empty = Document::default();
        assert_ne!(
            empty.stamp,
            Document::default().stamp,
            "two empty documents are two values"
        );
        assert_eq!(empty.stamp, empty.clone().stamp);

        let folded = empty
            .try_apply(&rename("drawing"))
            .expect("the fold succeeds");
        assert_ne!(empty.stamp, folded.stamp, "a fold mints");
    }

    /// The stamp exists to stop `view` from walking a document it has
    /// already indexed. Doctoring the index is the probe: a rebuild is
    /// precisely what erases the sentinel.
    #[test]
    fn view_rebuilds_for_a_new_document_value_and_not_otherwise() {
        let doc = wired_document();
        let mut index = DocIndex::of(&doc);
        let sentinel = block_id(200);
        let root = |index: &DocIndex| index.blocks[&BlockId::NULL].children.clone();
        assert!(
            !root(&index).contains(&sentinel),
            "the sentinel must not be a real entry or the probe proves nothing"
        );
        let plant = |index: &mut DocIndex| {
            index
                .blocks
                .entry(BlockId::NULL)
                .or_default()
                .children
                .insert(sentinel);
        };
        plant(&mut index);

        assert!(
            root(index.view(&doc).index).contains(&sentinel),
            "one document value is indexed once"
        );
        assert!(
            root(index.view(&doc.clone()).index).contains(&sentinel),
            "a clone is the same value"
        );

        plant(&mut index);
        let folded = doc
            .try_apply(&Commit::new("Added b20".into(), vec![block_create(20)]))
            .expect("the fold succeeds");
        let view = index.view(&folded);
        assert!(
            !root(view.index).contains(&sentinel),
            "a folded document is a new value"
        );
        assert!(root(view.index).contains(&block_id(20)));
    }

    /// The root is a scope like any other. Its row carries the top-level
    /// blocks as children and every entity owned by the root directly, so a
    /// scope read never needs a root special case — and it is still not a
    /// *block*, which is the question deletes and moves ask.
    #[test]
    fn the_root_is_a_scope_row_but_not_a_block() {
        let doc = Document::default()
            .try_apply(&Commit::new(
                "Authored at the root".into(),
                vec![
                    block_create(1),
                    pin_create(3, BlockId::NULL),
                    pin_create(4, BlockId::NULL),
                    OpCodes::Route(
                        route_id(5),
                        Crud::Create(Route {
                            owner: BlockId::NULL,
                            name: "r5".into(),
                            from: pin_id(3),
                            to: pin_id(4),
                            role: Role::default(),
                            waypoints: Vec::new(),
                        }),
                    ),
                    OpCodes::Text(
                        text_id(7),
                        Crud::Create(Text {
                            owner: BlockId::NULL,
                            text: "note".into(),
                            pos: GridPoint::default(),
                            role: Role::default(),
                            width: None,
                        }),
                    ),
                    OpCodes::Area(
                        area_id(8),
                        Crud::Create(Area {
                            owner: BlockId::NULL,
                            rect: GridRect::default(),
                            role: Role::default(),
                            title: label_init("c8".into()),
                        }),
                    ),
                    OpCodes::Image(
                        image_id(9),
                        Crud::Create(Image {
                            owner: BlockId::NULL,
                            asset: AssetHash::default(),
                            rect: ScreenRect::default(),
                        }),
                    ),
                ],
            ))
            .expect("the root accepts scoped entities");
        let index = DocIndex::of(&doc);

        let root = index.scope(BlockId::NULL).expect("the root is a scope");
        assert_eq!(root.children, [block_id(1)].into_iter().collect());
        assert_eq!(root.pins, [pin_id(3), pin_id(4)].into_iter().collect());
        assert_eq!(root.routes, [route_id(5)].into_iter().collect());
        assert_eq!(root.texts, [text_id(7)].into_iter().collect());
        assert_eq!(root.areas, [area_id(8)].into_iter().collect());
        assert_eq!(root.images, [image_id(9)].into_iter().collect());

        assert!(index.holds_block(block_id(1)));
        assert!(
            !index.holds_block(BlockId::NULL),
            "the root has no entity to hold"
        );
        assert_eq!(
            index.scope(block_id(1)),
            Some(&BlockIndex::default()),
            "the block owns nothing — the root does"
        );
    }

    /// The other half of the root being a scope: the fold accepts `NULL` as
    /// an owner wherever it accepts a block, and still refuses an owner that
    /// is neither.
    #[test]
    fn the_fold_accepts_the_root_as_an_owner_and_refuses_a_stranger() {
        let stranger = block_id(9);
        let doc = Document::default();

        doc.try_apply(&Commit::new(
            "Pinned the root".into(),
            vec![pin_create(3, BlockId::NULL)],
        ))
        .expect("the root owns pins");

        let Err(error) = doc.try_apply(&Commit::new(
            "Pinned a stranger".into(),
            vec![pin_create(3, stranger)],
        )) else {
            panic!("an owner that is neither a block nor the root must refuse");
        };
        assert_eq!(error, FoldError::InvalidPinOwner(pin_id(3), stranger));
    }

    /// Donor: `state.rs` live-children-only — a deleted child leaves its
    /// parent's sets, and a deleted element has no index entry.
    #[test]
    fn a_deleted_child_leaves_its_parents_sets() {
        let doc = wired_document()
            .try_apply(&Commit::new(
                "Deleted a pin and the nested block".into(),
                vec![
                    OpCodes::Route(route_id(5), Crud::Delete),
                    OpCodes::RouteLabel(route_label_id(6), Crud::Delete),
                    pin_delete(4),
                    OpCodes::Block(block_id(2), Crud::Delete),
                ],
            ))
            .expect("the fold succeeds");
        let index = DocIndex::of(&doc);

        let entry = &index.blocks[&block_id(1)];
        assert_eq!(
            entry.pins,
            [pin_id(3)].into_iter().collect(),
            "a deleted pin leaves the owner's set"
        );
        assert!(
            entry.children.is_empty(),
            "a deleted child leaves the parent's list"
        );
        assert!(
            !index.blocks.contains_key(&block_id(2)),
            "no entries for deleted elements"
        );
    }

    /// Endpoint integrity is structural now that a delete removes: a
    /// commit that takes a pin out from under a route leaves a dangling
    /// endpoint, and the fold refuses the whole commit rather than
    /// suppressing the route. The delete cascade emits every dependent
    /// delete itself, which is what keeps this refusal unreachable in
    /// practice.
    #[test]
    fn deleting_an_endpoint_without_its_route_refuses_the_commit() {
        let doc = wired_document();
        assert!(
            doc.route(&route_id(5)).is_some_and(|r| r.from == pin_id(3)),
            "precondition: the fixture's route hangs off the pin being deleted"
        );

        let Err(error) = doc.try_apply(&Commit::new(
            "Deleted an endpoint".into(),
            vec![pin_delete(3)],
        )) else {
            panic!("a dangling endpoint must refuse the commit");
        };
        assert_eq!(error, FoldError::InvalidRouteFrom(route_id(5), pin_id(3)));

        doc.try_apply(&Commit::new(
            "Deleted an endpoint and its route".into(),
            vec![
                OpCodes::RouteLabel(route_label_id(6), Crud::Delete),
                OpCodes::Route(route_id(5), Crud::Delete),
                pin_delete(3),
            ],
        ))
        .expect("the cascade folds");
    }

    /// The oracle is a brute-force scan, so the index cannot inherit a
    /// bug from the code it checks. Covers the subtle row: a deleted
    /// route leaves the index entirely.
    #[test]
    fn routes_by_endpoint_agrees_with_a_brute_force_scan() {
        let doc = wired_document()
            .try_apply(&Commit::new(
                "Added a second route and killed the first".into(),
                vec![
                    route_create(10, 1, 3, 4),
                    OpCodes::RouteLabel(route_label_id(6), Crud::Delete),
                    OpCodes::Route(route_id(5), Crud::Delete),
                ],
            ))
            .expect("the fold succeeds");
        let index = DocIndex::of(&doc);

        let mut oracle: HashMap<PinId, HashSet<RouteId>> = HashMap::default();
        for (id, route) in doc.routes() {
            for endpoint in [route.from, route.to] {
                oracle.entry(endpoint).or_default().insert(id);
            }
        }
        assert_eq!(index.routes_by_endpoint, oracle);

        assert!(
            index.routes_by_endpoint[&pin_id(3)].contains(&route_id(10)),
            "a route is indexed under both its endpoints"
        );
        assert!(
            !index
                .routes_by_endpoint
                .values()
                .any(|routes| routes.contains(&route_id(5))),
            "a deleted route leaves the index"
        );
    }

    /// The one order every consumer shares: ascending id, which is
    /// creation order because ids are monotonic. Touching a block does not
    /// move it, so the fixture edits the oldest and it stays beneath its
    /// neighbours.
    #[test]
    fn chronological_orders_by_id_and_a_touch_does_not_move_it() {
        let mut doc = Document::default();
        for n in [1, 2, 3] {
            doc = doc
                .try_apply(&Commit::new(format!("Added b{n}"), vec![block_create(n)]))
                .expect("the create folds");
        }
        doc = doc
            .try_apply(&Commit::new("Moved b1".into(), vec![resize(1, rect(9, 9))]))
            .expect("the move folds");
        assert_eq!(
            chronological(doc.blocks()),
            vec![block_id(1), block_id(2), block_id(3)],
            "the touched block stays where its id puts it"
        );
    }

    fn png(bytes: &[u8]) -> Asset {
        Asset::Png(bytes.into())
    }

    fn payload(asset: &Asset) -> OpCodes {
        OpCodes::Asset(asset.hash(), asset.clone())
    }

    fn image_create(n: u32, owner: u32, asset: &Asset) -> OpCodes {
        OpCodes::Image(
            image_id(n),
            Crud::Create(Image {
                owner: block_id(owner),
                asset: asset.hash(),
                rect: ScreenRect::default(),
            }),
        )
    }

    /// The payload arrives keyed by its own hash, and the bytes come back
    /// out under it. No liveness, no order — just held or not held.
    #[test]
    fn an_asset_payload_folds_into_the_table_under_its_hash() {
        let asset = png(b"artwork");
        let doc = Document::default()
            .try_apply(&Commit::new(
                "Placed an image".into(),
                vec![payload(&asset), block_create(1), image_create(9, 1, &asset)],
            ))
            .expect("the fold succeeds");

        assert_eq!(doc.asset(&asset.hash()), Some(&asset));
        assert_eq!(
            doc.asset(&png(b"other artwork").hash()),
            None,
            "an unheld hash reads as absent, not as some other payload"
        );
        assert_eq!(
            doc.image(&image_id(9)).expect("the image is held").asset,
            asset.hash(),
            "the entity carries the reference, the table carries the bytes"
        );
    }

    /// Idempotence is structural rather than checked: one hash can only
    /// name one byte string, so a duplicate delivery — a replay, a second
    /// placement of the same file — has nothing to conflict with.
    #[test]
    fn a_duplicate_payload_is_a_no_op_not_a_refusal() {
        let asset = png(b"artwork");
        let once = Document::default()
            .try_apply(&Commit::new("Placed it".into(), vec![payload(&asset)]))
            .expect("the fold succeeds");
        let twice = once
            .try_apply(&Commit::new(
                "Placed it again".into(),
                vec![payload(&asset)],
            ))
            .expect("a duplicate payload folds rather than refusing");

        assert_eq!(twice.asset(&asset.hash()), Some(&asset));
        assert_eq!(
            twice.assets().count(),
            1,
            "the table holds one entry per hash, however often it arrives"
        );
    }

    /// The trust boundary: the payload and its key must agree, or one hash
    /// names two byte strings and every replica's content addressing is a
    /// lie. Refused, never re-keyed to the hash the bytes actually have.
    #[test]
    fn a_payload_that_does_not_hash_to_its_key_is_refused() {
        let asset = png(b"artwork");
        let forged = png(b"different artwork").hash();
        assert_ne!(
            forged,
            asset.hash(),
            "precondition: the key must name other bytes or nothing is tested"
        );

        let doc = Document::default();
        let Err(error) = doc.try_apply(&Commit::new(
            "Forged a payload".into(),
            vec![OpCodes::Asset(forged, asset)],
        )) else {
            panic!("a payload that does not hash to its key must refuse the commit");
        };
        assert_eq!(error, FoldError::AssetHashMismatch(forged));
    }

    /// The log is replayed in full on every open, so an unbounded payload
    /// is one the document carries forever.
    /// The format is the model: a document survives the trip through its own
    /// JSON, and a parsed one comes back stamped and marked as a folded one
    /// is — the file carries neither.
    #[test]
    fn a_document_round_trips_through_json_and_the_marks_come_back() {
        let doc = wired_document();
        let text = serde_json::to_string(&doc).expect("a document serializes");
        let read: Document = serde_json::from_str(&text).expect("and parses back");

        assert_eq!(read, doc);
        assert_ne!(read.stamp(), doc.stamp(), "a parsed value is its own");
        assert_eq!(read.rev(), Rev::ZERO, "a file names no log position");
        assert_eq!(
            read.ids().mint::<crate::id::BlockKind>(),
            doc.clone().ids().mint::<crate::id::BlockKind>(),
            "the marks are derived from what the file holds",
        );
    }

    /// The newer-build guard survives the schema's deletion: a file from the
    /// future is refused rather than half-read.
    #[test]
    fn a_version_from_the_future_is_refused() {
        let text = serde_json::to_string(&Document::default()).expect("it serializes");
        assert!(text.contains(&format!(r#""version":{CURRENT_VERSION}"#)));
        let ahead = text.replace(
            &format!(r#""version":{CURRENT_VERSION}"#),
            &format!(r#""version":{}"#, CURRENT_VERSION + 1),
        );
        let refusal = serde_json::from_str::<Document>(&ahead).expect_err("it is refused");
        assert!(
            refusal.to_string().contains("newer than this build reads"),
            "{refusal}"
        );
    }

    #[test]
    fn a_payload_over_the_limit_is_refused() {
        let oversized = png(&vec![0u8; crate::block_model::ASSET_LIMIT + 1]);
        let hash = oversized.hash();
        let doc = Document::default();

        let Err(error) = doc.try_apply(&Commit::new(
            "Committed a photograph".into(),
            vec![OpCodes::Asset(hash, oversized)],
        )) else {
            panic!("a payload over the limit must refuse the commit");
        };
        assert_eq!(
            error,
            FoldError::AssetTooLarge(hash, crate::block_model::ASSET_LIMIT + 1)
        );

        // The bound is inclusive: a payload exactly at the limit is fine, so
        // the check cannot be an off-by-one that refuses what it advertises.
        let exact = png(&vec![0u8; crate::block_model::ASSET_LIMIT]);
        assert!(
            doc.try_apply(&Commit::new(
                "Committed the largest allowed artwork".into(),
                vec![OpCodes::Asset(exact.hash(), exact)],
            ))
            .is_ok(),
            "a payload exactly at the limit must fold",
        );
    }

    /// The stamp a folded payload canonically encodes to. It is a ciborium
    /// encoding and `Asset`'s serde impl is format-aware, so a change to the
    /// *text* spelling of a payload must leave this untouched — which is
    /// Loading is folding, so the marks a load leaves are the marks the
    /// fold raised: the next id of a kind is one past the highest the
    /// document has ever held.
    #[test]
    fn the_next_id_is_one_past_the_highest_the_fold_saw() {
        let mut document = wired_document();
        assert!(
            document.block(&block_id(2)).is_some() && document.block(&block_id(3)).is_none(),
            "precondition: the fixture's blocks run out at b2",
        );
        assert_eq!(document.mint::<crate::id::BlockKind>(), block_id(3));
        assert_eq!(document.mint::<crate::id::PinKind>(), pin_id(5));
        assert_eq!(
            document.mint::<crate::id::TextKind>(),
            text_id(8),
            "each kind counts in its own space",
        );
    }

    /// The fold observes every id a commit names, so a delete cannot hand
    /// the departed id to something else.
    #[test]
    fn a_deleted_entity_does_not_free_its_id() {
        let document = wired_document()
            .try_apply(&Commit::new(
                "Deleted a block".into(),
                vec![OpCodes::Block(block_id(2), Crud::Delete)],
            ))
            .expect("the delete folds");
        assert!(
            document.block(&block_id(2)).is_none(),
            "precondition: b2 is gone from the document",
        );
        let mut ids = document.ids();
        assert_eq!(ids.mint::<crate::id::BlockKind>(), block_id(3));
    }

    /// A replica holding every reference but not the bytes has not folded
    /// the same log, and the hash that proves fold agreement must say so.
    #[test]
    fn a_document_is_its_asset_table_too() {
        let fold_payload = |asset: &Asset| {
            Document::default()
                .try_apply(&Commit::new("Placed it".into(), vec![payload(asset)]))
                .expect("the fold succeeds")
        };
        let one = fold_payload(&png(b"artwork"));
        let other = fold_payload(&png(b"other artwork"));

        assert_eq!(one.rev(), other.rev(), "precondition: same log position");
        assert_ne!(one, other);
    }

    /// Z-order is id order: two entities whose values are identical still
    /// order by the ids they were minted under, and nothing about how
    /// recently either was touched enters into it.
    #[test]
    fn chronological_orders_by_id_alone() {
        let block = Block {
            title: label_init("tied".into()),
            ..Block::default()
        };
        let touched = Block {
            rect: rect(9, 9),
            ..block.clone()
        };
        assert_eq!(
            chronological([(block_id(2), &block), (block_id(1), &touched)].into_iter()),
            vec![block_id(1), block_id(2)],
        );
    }
}