blockworx_store/

doc.rs

//! The editor's document handle: the two places a document can live, as one
//! enum.
//!
//! [`Doc::Scratch`] is an in-process [`Repo`] — a session that dies with the
//! process. It is what an opened document file holds. [`Doc::Attached`] is
//! a `.bwx` container, wherever its bytes are kept: the same repo, with
//! every accepted commit in `revs/` and `manifest.jsonl` before the call
//! returns.
//!
//! Reads go through [`Doc::repo`]/[`Doc::document`]; writes through
//! [`Doc::submit`] and its two history neighbours, which route to the
//! container's write door when there is one. Nothing hands out a `&mut Repo`
//! for an attached document, so "folded but not logged" is unrepresentable
//! rather than merely avoided.

use blockworx_doc::{
    commit::Commit,
    document::Document,
    repo::Repo,
    rev::Rev,
    trail::{Direction, Trail},
};
use serde::{Deserialize, Serialize};

use crate::Refusal;
use crate::history::Journal;
use crate::record::{Attribution, Digest};
use crate::revs;
use crate::stamp::Stamp;
use crate::tags::Tags;
use crate::worked::Worked;

use crate::container::{Drained, ReadOnlyReason};
use crate::handle::Store;
use crate::storage::{Any, Name};

/// Whether this session may write its document. Not a bool: the read-only
/// arm always has a reason, and the reason is something the user is told.
#[derive(Clone, Copy, PartialEq, Eq, Debug, serde::Serialize, serde::Deserialize)]
pub enum Writability {
    Writable,
    ReadOnly,
}

/// Which document the canvas is showing: the log's head, or a rev out of
/// the past — the time machine.
///
/// Only the *state*: the fold a past rev is viewed through lives in the
/// editor beside it, so this stays `Copy` and can be handed to the command
/// registry and the chrome. Viewing the past is the second consumer of the
/// one read-only presentation, which is why it answers the same
/// [`Writability`] question a container does.
#[derive(Clone, Copy, PartialEq, Eq, Debug, serde::Serialize, serde::Deserialize)]
pub enum Viewing {
    Head,
    Past(Rev),
}

impl Viewing {
    /// Looking at the past is looking, never editing: every writing
    /// command is withheld, and undo/redo with them — they act on the head
    /// nobody is looking at.
    pub fn writability(self) -> Writability {
        match self {
            Viewing::Head => Writability::Writable,
            Viewing::Past(_) => Writability::ReadOnly,
        }
    }

    /// One step through a log whose newest rev is `head`. `None` where the
    /// step has nowhere to go.
    ///
    /// The policy in one place, because two surfaces read it: the cluster
    /// draws its buttons enabled or not by it, and the dispatch acts on it.
    /// Log positions are contiguous — a refused commit consumes none — so
    /// stepping is arithmetic rather than a search. Stepping forward off
    /// the end is how the past gives way to the writable present.
    pub fn stepped(self, head: Rev, step: TimeStep) -> Option<At> {
        let Viewing::Past(at) = self else {
            return None;
        };
        match step {
            TimeStep::Back => at.prev().filter(|before| *before > Rev::ZERO).map(At::Rev),
            TimeStep::Forward if at >= head => Some(At::Current),
            TimeStep::Forward => Some(At::Rev(at.next())),
        }
    }
}

/// Where a time-machine step lands: on a rev, or back in the writable
/// present.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum At {
    Rev(Rev),
    Current,
}

/// Which way a time-machine step goes.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum TimeStep {
    Back,
    Forward,
}

/// Whether "Save" has anything to write. Saving refreshes the projection
/// beside a log, so it needs a writable container — a scratch session has
/// no file to keep in step with, and a read-only one may not touch the file
/// it has.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Saving {
    Offered,
    Withheld,
}

/// Whether there is a container behind this document at all. Half of what
/// [`Saving`] asks; the surfaces that need the halves apart ask this and
/// [`Doc::writability`] rather than reading one answer as two.
#[derive(Clone, Copy, PartialEq, Eq, Debug, serde::Serialize, serde::Deserialize)]
pub enum Attachment {
    Attached,
    /// No container: the document lives and dies with the process.
    Scratch,
}

/// Whether the document can be renamed. Renaming moves the container the
/// document lives in, so it asks exactly what [`Saving`] asks — is there a
/// container, and may this session write it — and is derived from it
/// rather than forming a second opinion.
#[derive(Clone, Copy, PartialEq, Eq, Debug, serde::Serialize, serde::Deserialize)]
pub enum Renaming {
    Offered,
    Withheld,
}

impl From<Saving> for Renaming {
    fn from(saving: Saving) -> Self {
        match saving {
            Saving::Offered => Renaming::Offered,
            Saving::Withheld => Renaming::Withheld,
        }
    }
}

/// Which opened document this is, for the life of the handle holding it —
/// minted when a document is created or opened, never written to a log, a
/// projection, or anything else durable.
///
/// Its whole job is to make two documents opened in one process compare
/// unequal, and one document opened in two processes compare unequal too:
/// 64 drawn bits, so a payload that travels through the OS clipboard can
/// say which document it was cut out of and be believed.
#[derive(Clone, Copy, PartialEq, Eq, Debug, Serialize, Deserialize)]
pub struct DocumentNonce(u64);

impl DocumentNonce {
    /// A document of its own. Every [`Doc`] mints one, which is what makes
    /// "this handle's document" a thing the clipboard can name without any
    /// call site remembering to.
    ///
    /// Drawn through `RandomState` rather than `naming::entropy`, which is
    /// desktop-only: the browser build has documents and a clipboard too.
    /// The counter is what keeps two documents *in one process* apart
    /// whatever the draw does.
    pub fn mint() -> Self {
        use std::hash::{BuildHasher as _, Hasher as _, RandomState};
        use std::sync::atomic::{AtomicU64, Ordering};
        static OPENED: AtomicU64 = AtomicU64::new(0);
        let mut hasher = RandomState::new().build_hasher();
        hasher.write_u64(OPENED.fetch_add(1, Ordering::Relaxed));
        Self(hasher.finish())
    }
}

/// Which record a step moves, which way, and what that record is called —
/// the three things a step's own commit is written from.
#[derive(Clone, Copy)]
pub(crate) struct Stepping<'a> {
    pub edit: Rev,
    pub direction: Direction,
    pub label: &'a str,
}

/// One history step: adopt the document the trail's top entry restores,
/// and record it as a commit of its own so the step stays *in* the
/// history.
///
/// The whole policy, in one place, over the one thing the two session
/// arms disagree about — where the document at a rev comes from. Both
/// read a rev copy; only the shelf it sits on differs.
///
/// # Errors
/// [`Refusal::Step`] when the trail will not take the step, and whatever
/// `at` says when the document it names cannot be had.
pub(crate) fn stepped(
    repo: &mut Repo,
    trail: &mut Trail,
    step: Stepping<'_>,
    at: impl FnOnce(Rev) -> Result<Document, Refusal>,
) -> Result<Rev, Refusal> {
    let Stepping {
        edit,
        direction,
        label,
    } = step;
    let entry = trail.stepping(edit, direction)?;
    let target = at(entry.restores)?;
    Ok(repo.restore(
        trail,
        blockworx_doc::repo::Restoring {
            entry,
            direction,
            target,
            label,
        },
    ))
}

/// A session with no files, keeping the document at every rev exactly as
/// a container does — the same encoding over a map instead of a directory
/// (`docs/log-vs-snapshot.md`).
///
/// The payloads come off the revs and go into a store of their own for
/// the same reason they do on disk: a rev the session steps back through
/// is one copy of the document, not one copy of every icon in it.
#[derive(Default)]
pub struct Shelf {
    revs: revs::Memory,
    payloads: crate::assets::Held,
    /// What each rev's act named and the scope it was made in — a
    /// manifest row's two advisory fields, for a session that writes no
    /// rows. A step keeps the framing of the act it moves, so it frames
    /// what it moved.
    worked: std::collections::BTreeMap<Rev, Worked>,
}

impl Shelf {
    /// Keep the document this session has just reached as rev `at`.
    ///
    /// A write that fails is a fault in a map, so it is reported and
    /// dropped: the document is still in hand, and what a lost rev costs
    /// is a step this session can no longer take back — which the trail
    /// then refuses out loud.
    fn keep(&mut self, at: Rev, document: &Document, worked: Worked) {
        if let Err(why) = revs::write(&mut self.revs, at, document, &mut self.payloads) {
            tracing::error!("rev {} was not kept: {why}", at.get());
        }
        self.worked.insert(at, worked);
    }

    fn worked_at(&self, at: Rev) -> Option<Worked> {
        self.worked.get(&at).cloned()
    }

    /// The document at `at`, payloads and all.
    ///
    /// # Errors
    /// [`Refusal::Unreachable`] for a rev this session did not keep.
    fn at(&self, at: Rev) -> Result<Document, Refusal> {
        let unreachable = |why: &dyn std::fmt::Display| Refusal::Unreachable {
            at,
            why: why.to_string(),
        };
        let document = revs::read(&self.revs, at).map_err(|why| unreachable(&why))?;
        revs::attached(document, &self.payloads).map_err(|why| unreachable(&why))
    }

    /// The digest of the bytes rev `at` was written as, or the empty
    /// document's for one this session did not keep.
    fn stamp(&self, at: Rev) -> Digest {
        revs::stamp(&self.revs, at).unwrap_or_else(|_| Digest::of(&[]))
    }
}

/// What the commit at `at` is called — `log[i]` holds rev `i + 1` for a
/// session whose commits are all its own.
fn label_of(repo: &Repo, at: Rev) -> Option<String> {
    let ndx = usize::try_from(at.get().checked_sub(1)?).ok()?;
    repo.log().get(ndx).map(|commit| commit.label().to_owned())
}

/// Both arms are boxed, so swapping the document — which is all the editor
/// ever does with one — moves two words rather than a whole folded document
/// either way.
pub enum Doc {
    /// No file behind it: the history lives and dies with the process.
    /// The browser has only this arm. Its tags die with it too — there
    /// are no rows for them to be rebuilt from.
    Scratch {
        repo: Box<Repo>,
        /// Where this session's history stands. Beside the repo rather
        /// than in it: a step adopts a document the repo cannot reach on
        /// its own (`docs/log-vs-snapshot.md`).
        trail: Trail,
        tags: Tags,
        /// The document at every rev, in the container's own encoding
        /// over a map rather than a directory — so this arm steps exactly
        /// as an attached one does.
        revs: Box<Shelf>,
        session: DocumentNonce,
    },
    /// A `.bwx` container, open and (unless it says otherwise) writable.
    /// Which storage holds it is the container's own business, so it is a
    /// fact of the handle rather than of the target: a directory of files
    /// on a desktop, origin-private storage in a browser.
    Attached {
        store: Box<Store<Any>>,
        session: DocumentNonce,
    },
}

impl Default for Doc {
    fn default() -> Self {
        Doc::scratch(Repo::default())
    }
}

impl Doc {
    pub fn scratch(repo: Repo) -> Self {
        let mut trail = Trail::default();
        // A repo handed in has already folded its own past, and nobody may
        // take back a step they did not make.
        trail.seeded(repo.rev());
        // The past a handed-in repo arrives with is folded once here, so
        // the time machine and a step both read a copy rather than
        // re-folding a prefix per pick.
        let mut revs = Shelf::default();
        let mut folding = Repo::default();
        for commit in repo.log() {
            let worked = Worked::of(folding.document(), commit);
            match folding.fold_one(commit.clone()) {
                Ok(document) => revs.keep(document.rev(), document, worked),
                Err(why) => tracing::error!("a session's own past will not fold: {why}"),
            }
        }
        revs.keep(repo.rev(), repo.document(), Worked::nothing());
        Doc::Scratch {
            repo: Box::new(repo),
            trail,
            tags: Tags::default(),
            revs: Box::new(revs),
            session: DocumentNonce::mint(),
        }
    }

    pub fn attached(store: Store<Any>) -> Self {
        Doc::Attached {
            store: Box::new(store),
            session: DocumentNonce::mint(),
        }
    }

    /// Which document this handle is holding. Stable while it is open and
    /// unequal to every other, which is what a cut payload compares itself
    /// against when a paste asks whether it has come home.
    pub fn session(&self) -> DocumentNonce {
        match self {
            Doc::Scratch { session, .. } | Doc::Attached { session, .. } => *session,
        }
    }

    pub fn repo(&self) -> &Repo {
        match self {
            Doc::Scratch { repo, .. } => repo,
            Doc::Attached { store, .. } => store.repo(),
        }
    }

    /// Where this session's history stands: which rev's document the head
    /// holds, and what one press either way would move.
    pub fn trail(&self) -> &Trail {
        match self {
            Doc::Scratch { trail, .. } => trail,
            Doc::Attached { store, .. } => store.trail(),
        }
    }

    /// What this document's revs are called.
    pub fn tags(&self) -> &Tags {
        match self {
            Doc::Scratch { tags, .. } => tags,
            Doc::Attached { store, .. } => store.tags(),
        }
    }

    /// Where the rows a reader is shown come from: this container's
    /// manifest, or a session's own commits.
    pub fn journal(&self) -> Journal<'_> {
        match self {
            Doc::Scratch { repo, .. } => Journal::Session(repo.log()),
            Doc::Attached { store, .. } => Journal::Recorded(store.rows()),
        }
    }

    /// What the record at `at` says it worked on: the scope its author was
    /// standing in and the entities they named. `None` for a rev this
    /// history does not hold.
    ///
    /// A container reads the row; a session with no rows reads the commit
    /// it still holds, which is what keeps ops in memory.
    pub fn worked_at(&self, at: Rev) -> Option<Worked> {
        match self {
            Doc::Scratch { revs, .. } => revs.worked_at(at),
            Doc::Attached { store, .. } => store.framing(at).map(Worked::recorded),
        }
    }

    /// Where the author of the record at `at` was looking when they wrote
    /// it. `None` for a session that keeps no rows: there is nothing
    /// recorded to stand at, so the pick frames the change instead.
    pub fn camera_at(&self, at: Rev) -> Option<crate::record::Camera> {
        match self {
            Doc::Scratch { .. } => None,
            Doc::Attached { store, .. } => store.framing(at).map(|row| row.camera),
        }
    }

    /// What the record at `at` is called — how the undo and redo buttons
    /// name the step they stand over.
    pub fn label_at(&self, at: Rev) -> Option<&str> {
        match self {
            Doc::Scratch { repo, .. } => {
                let ndx = usize::try_from(at.get().checked_sub(1)?).ok()?;
                repo.log().get(ndx).map(Commit::label)
            }
            Doc::Attached { store, .. } => store.row(at).map(|row| row.label.as_str()),
        }
    }

    /// The document this session holds at `at`, payloads and all — the rev
    /// copy, never a fold.
    ///
    /// # Errors
    /// [`Refusal::Unreachable`] for a rev whose copy cannot be shown.
    pub fn document_at(&self, at: Rev) -> Result<Document, Refusal> {
        match self {
            Doc::Scratch { revs, .. } => revs.at(at),
            Doc::Attached { store, .. } => store.document_at(at),
        }
    }

    /// The rev this session heads at, and the digest of the bytes it was
    /// written as — what an export stamps itself with.
    pub fn stamp_at(&self, at: Rev) -> Stamp {
        Stamp::at(at, self.state_at(at))
    }

    fn state_at(&self, at: Rev) -> Digest {
        match self {
            Doc::Scratch { revs, .. } => revs.stamp(at),
            Doc::Attached { store, .. } => store
                .row(at)
                .map_or_else(|| Digest::of(&[]), |row| row.hash),
        }
    }

    pub fn document(&self) -> &Document {
        self.repo().document()
    }

    /// # Errors
    /// [`Refusal::Fold`] when the fold refuses the commit, and — for an
    /// attached document — [`Refusal::ReadOnly`] or [`Refusal::Append`].
    pub fn submit<'a>(
        &mut self,
        commit: Commit,
        by: impl Into<Attribution<'a>>,
    ) -> Result<Rev, Refusal> {
        match self {
            Doc::Scratch {
                repo, trail, revs, ..
            } => {
                // Read before the fold: what a commit worked on is
                // measured against the document it was written against.
                let worked = Worked::of(repo.document(), &commit);
                let rev = repo.submit(commit, trail)?;
                revs.keep(rev, repo.document(), worked);
                Ok(rev)
            }
            Doc::Attached { store, .. } => store.submit_edit(commit, by),
        }
    }

    /// Name `rev` — or, with an empty `name`, stop naming it. Never an
    /// edit: no rev is spent and the trail does not move.
    ///
    /// # Errors
    /// As [`Store::tag`]; a scratch session's tags are in memory and
    /// refuse only a rev the log does not hold.
    pub fn tag<'a>(
        &mut self,
        rev: Rev,
        name: &str,
        how: crate::tags::Tagging,
        by: impl Into<Attribution<'a>>,
    ) -> Result<(), Refusal> {
        match self {
            Doc::Scratch { repo, tags, .. } => {
                if rev == Rev::ZERO || rev > repo.rev() {
                    return Err(Refusal::NoSuchRev(rev));
                }
                tags.apply(rev, name, how);
                Ok(())
            }
            Doc::Attached { store, .. } => store.tag(rev, name, how, by),
        }
    }

    /// # Errors
    /// [`Refusal::Step`] when the trail will not take the step, and as
    /// [`Self::submit`] otherwise.
    pub fn undo<'a>(&mut self, edit: Rev, by: impl Into<Attribution<'a>>) -> Result<Rev, Refusal> {
        self.step(edit, Direction::Undo, by)
    }

    /// # Errors
    /// As [`Self::undo`].
    pub fn redo<'a>(&mut self, edit: Rev, by: impl Into<Attribution<'a>>) -> Result<Rev, Refusal> {
        self.step(edit, Direction::Redo, by)
    }

    /// One history step, whichever way and whichever arm holds the revs.
    ///
    /// # Errors
    /// As [`Self::undo`].
    fn step<'a>(
        &mut self,
        edit: Rev,
        direction: Direction,
        by: impl Into<Attribution<'a>>,
    ) -> Result<Rev, Refusal> {
        match self {
            Doc::Scratch {
                repo, trail, revs, ..
            } => {
                // As the store: the trail's own refusal comes first.
                let entry = trail.stepping(edit, direction)?;
                let label = label_of(repo, entry.rev).ok_or(Refusal::NoSuchRev(edit))?;
                let moved = revs.worked_at(entry.rev).unwrap_or_else(Worked::nothing);
                let at = stepped(
                    repo,
                    trail,
                    Stepping {
                        edit,
                        direction,
                        label: &label,
                    },
                    |restores| revs.at(restores),
                )?;
                revs.keep(at, repo.document(), moved);
                Ok(at)
            }
            Doc::Attached { store, .. } => match direction {
                Direction::Undo => store.undo(edit, by),
                Direction::Redo => store.redo(edit, by),
            },
        }
    }

    /// A scratch session is always writable: there is nothing for a lock to
    /// be held on and no history to be broken.
    pub fn writability(&self) -> Writability {
        match self {
            Doc::Scratch { .. } => Writability::Writable,
            Doc::Attached { store, .. } => match store.read_only_reason() {
                Some(_) => Writability::ReadOnly,
                None => Writability::Writable,
            },
        }
    }

    /// Why this document cannot be written, when it cannot be.
    pub fn read_only_reason(&self) -> Option<&ReadOnlyReason> {
        match self {
            Doc::Scratch { .. } => None,
            Doc::Attached { store, .. } => store.read_only_reason(),
        }
    }

    /// Whether this session can be asked to refresh its projection.
    /// Whether a container stands behind this document.
    pub fn attachment(&self) -> Attachment {
        match self {
            Doc::Scratch { .. } => Attachment::Scratch,
            Doc::Attached { .. } => Attachment::Attached,
        }
    }

    pub fn saving(&self) -> Saving {
        match self {
            Doc::Scratch { .. } => Saving::Withheld,
            Doc::Attached { store, .. } => match store.read_only_reason() {
                Some(_) => Saving::Withheld,
                None => Saving::Offered,
            },
        }
    }

    /// Whether this session can be asked to rename its document.
    pub fn renaming(&self) -> Renaming {
        self.saving().into()
    }

    /// Rename this document's container — the directory's name *is* the
    /// document's name.
    ///
    /// # Errors
    /// [`Refusal::Detached`] for a session with no container to rename, and
    /// as [`Store::rename`].
    pub fn rename(&mut self, to: &Name) -> Result<(), Refusal> {
        match self {
            Doc::Scratch { .. } => Err(Refusal::Detached),
            Doc::Attached { store, .. } => store.rename(to),
        }
    }

    /// [`Self::rename`] for a container whose storage is not written to as
    /// it is asked.
    ///
    /// # Errors
    /// As [`Self::rename`].
    pub async fn renaming_to(&mut self, to: &Name) -> Result<(), Refusal> {
        match self {
            Doc::Scratch { .. } => Err(Refusal::Detached),
            Doc::Attached { store, .. } => store.renaming_to(to).await,
        }
    }

    /// How many writes this session has made to its container's memory and
    /// not yet to its storage. Zero for a session with no container, and
    /// for one whose container is written to as it goes.
    pub fn pending(&self) -> usize {
        match self {
            Doc::Scratch { .. } => 0,
            Doc::Attached { store, .. } => store.pending(),
        }
    }

    /// Make the writes this session owes its storage, in the order it made
    /// them. See [`Store::drain`].
    ///
    /// # Errors
    /// The write that did not land.
    pub async fn drain(&mut self) -> std::io::Result<Drained> {
        match self {
            Doc::Scratch { .. } => Ok(Drained::NOTHING),
            Doc::Attached { store, .. } => store.drain().await,
        }
    }

    /// What this document's container is called, for the chrome that
    /// names it. `None` for a session with no container.
    pub fn container_name(&self) -> Option<Name> {
        match self {
            Doc::Scratch { .. } => None,
            Doc::Attached { store, .. } => Some(store.name()),
        }
    }

    /// Where this document's container sits on a filesystem. `None` where
    /// there is no container, and where the one there is does not live on
    /// one — a fact of the storage, which only a shell that can name a
    /// path has any use for.
    pub fn container_path(&self) -> Option<&std::path::Path> {
        match self {
            Doc::Scratch { .. } => None,
            Doc::Attached { store, .. } => store.path(),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::record::Identity;
    use blockworx_doc::fixtures::rev;

    fn author() -> Identity {
        Identity::new("ada")
    }

    /// The stepping policy the cluster's two buttons and the dispatch both
    /// read: bounded at the oldest rev, and off the newest into the present.
    #[test]
    fn stepping_walks_the_log_and_falls_off_its_end_into_the_present() {
        let head = rev(3);
        let step = |at: Viewing, dir| at.stepped(head, dir);

        assert_eq!(step(Viewing::Head, TimeStep::Back), None);
        assert_eq!(step(Viewing::Head, TimeStep::Forward), None);
        assert_eq!(step(Viewing::Past(rev(1)), TimeStep::Back), None);
        assert_eq!(
            step(Viewing::Past(rev(2)), TimeStep::Back),
            Some(At::Rev(rev(1))),
        );
        assert_eq!(
            step(Viewing::Past(rev(2)), TimeStep::Forward),
            Some(At::Rev(rev(3))),
        );
        assert_eq!(
            step(Viewing::Past(rev(3)), TimeStep::Forward),
            Some(At::Current),
        );
        assert_eq!(
            step(Viewing::Past(rev(3)), TimeStep::Back),
            Some(At::Rev(rev(2))),
            "the newest rev still steps back",
        );
    }

    /// A tag is not an edit: no rev is spent and nothing becomes undoable.
    #[test]
    fn tagging_a_scratch_rev_moves_neither_the_log_nor_the_trail() {
        let mut doc = Doc::default();
        let at = doc.submit(one_block(), &author()).expect("the edit lands");
        let depth = doc.trail().undo_depth();

        doc.tag(at, "Initial Draft", crate::tags::Tagging::Added, &author())
            .expect("it tags");
        assert_eq!(doc.tags().of(at), ["Initial Draft"]);
        assert_eq!(doc.repo().rev(), at, "tagging spent a rev");
        assert_eq!(doc.trail().undo_depth(), depth, "tagging moved the trail");

        doc.tag(
            at,
            "Initial Draft",
            crate::tags::Tagging::Removed,
            &author(),
        )
        .expect("and untags");
        assert!(doc.tags().is_empty());
        assert!(matches!(
            doc.tag(rev(9), "Nowhere", crate::tags::Tagging::Added, &author()),
            Err(Refusal::NoSuchRev(_)),
        ));
    }

    fn one_block() -> Commit {
        Commit::new(
            "Added a block".to_owned(),
            vec![crate::fixture::block_create(1, "Adder")],
        )
    }

    /// A scratch document takes the same three calls an attached one does,
    /// so the editor's write path has no second shape for the no-file case.
    #[test]
    fn a_scratch_document_submits_undoes_and_redoes() {
        let mut doc = Doc::default();
        assert_eq!(doc.writability(), Writability::Writable);

        let edit = doc.submit(one_block(), &author()).expect("the edit lands");
        let undone = doc.undo(edit, &author()).expect("and undoes");
        doc.redo(undone, &author()).expect("and redoes");
        assert_eq!(doc.repo().log().len(), 3, "an undo is a forward commit");
    }

    /// The scratch arm's answer to "where did I stand": the log prefix,
    /// folded. It has no rev copies, so this is the one place the two
    /// session arms differ — and they must reach the same documents.
    #[test]
    fn a_scratch_session_steps_through_its_own_prefix_folds() {
        use blockworx_doc::repo::Repo;

        let mut doc = Doc::default();
        let mut revs = Vec::new();
        for n in 1..=3 {
            revs.push(
                doc.submit(
                    Commit::new(
                        format!("Added block {n}"),
                        vec![crate::fixture::block_create(n, &format!("b{n}"))],
                    ),
                    &author(),
                )
                .expect("the edit lands"),
            );
        }
        let folded = |at: Rev| {
            Repo::folding(&doc.repo().log()[..at.get() as usize])
                .expect("the prefix folds")
                .document()
                .clone()
        };
        let at_three = folded(revs[2]);
        let at_two = folded(revs[1]);
        assert_ne!(at_two, at_three, "precondition: the last edit moved it");

        let undone = doc.undo(revs[2], &author()).expect("the undo lands");
        assert_eq!(doc.document(), &at_two, "the undo did not reach rev 2");
        assert_eq!(doc.trail().standing(), revs[1]);

        doc.undo(revs[1], &author()).expect("the second undo lands");
        assert_eq!(doc.trail().standing(), revs[0]);

        doc.redo(
            doc.trail().next_redo().expect("a step to put back"),
            &author(),
        )
        .expect("the redo lands");
        doc.redo(undone, &author()).expect("and the second redo");
        assert_eq!(
            doc.document(),
            &at_three,
            "the walk back up did not return the document it started from",
        );
        assert_eq!(doc.trail().standing(), revs[2]);
    }

    /// The refusal the editor's history walk reads to decide whether a step
    /// is spent or the repo is broken, in the spelling both arms report.
    #[test]
    fn a_step_the_trail_does_not_hold_is_refused_as_a_step() {
        let mut doc = Doc::default();
        assert!(matches!(
            doc.undo(blockworx_doc::fixtures::rev(1), &author()),
            Err(Refusal::Step(blockworx_doc::trail::UndoRefusal::Spent)),
        ));
    }

    #[test]
    fn an_attached_document_writes_through_the_container() {
        use crate::handle::Clock;

        let dir = crate::fixture::dir("doc-attached");
        let root = dir.join("doc.bwx");
        let store = Store::create(Any::new(crate::storage::Native::at(&root)), Clock::System)
            .expect("the container");
        let mut doc = Doc::attached(store);
        assert_eq!(doc.writability(), Writability::Writable);

        doc.submit(one_block(), &author()).expect("the edit lands");
        assert_eq!(
            std::fs::read_to_string(root.join(crate::container::MANIFEST.as_str()))
                .expect("the log")
                .lines()
                .count(),
            1,
            "an edit through the document handle did not reach the log",
        );
    }

    /// A container someone else holds opens read-only, and the handle says so
    /// in the one spelling the command registry and the chrome both read.
    #[test]
    fn a_locked_container_is_read_only_and_refuses_writes() {
        use crate::handle::Clock;
        use crate::storage::Native;

        let dir = crate::fixture::dir("doc-locked");
        let root = dir.join("doc.bwx");
        let _held = Store::create(Native::at(&root), Clock::System).expect("the first session");

        let mut doc = Doc::attached(
            Store::open(Any::new(Native::at(&root)), Clock::System).expect("the second"),
        );
        assert_eq!(doc.writability(), Writability::ReadOnly);
        assert!(matches!(
            doc.submit(one_block(), &author()),
            Err(Refusal::ReadOnly),
        ));
        // Renaming is a write on someone else's open document, not a read.
        assert_eq!(doc.renaming(), Renaming::Withheld);
        assert!(matches!(
            doc.rename(&Name::of_document("renamed").expect("a name")),
            Err(Refusal::ReadOnly),
        ));
        assert!(root.exists(), "the refused rename moved it anyway");
    }

    /// A session with no container has no name to change, and says so
    /// rather than inventing a file.
    #[test]
    fn a_scratch_session_has_no_container_to_rename() {
        let mut doc = Doc::default();
        assert_eq!(doc.renaming(), Renaming::Withheld);
        assert_eq!(doc.container_name(), None);
        assert!(matches!(
            doc.rename(&Name::of_document("nowhere").expect("a name")),
            Err(Refusal::Detached),
        ));
    }
}