tilo_app/framework/

attached.rs

//! An app's view of one record, attached and never drawn: how a host
//! without a screen — an agent host, a relay, a workspace service — performs
//! actions.
//!
//! Nothing is drawn if no one is looking, but no action is performed out of
//! sight. An [`AttachedView`] mounts the app's real component over the
//! record exactly as a window does, lays it out and never paints it; every
//! operation goes through the view's bound dispatcher, the door a person's
//! click takes, admitted for the participant as invoker and checked against
//! its permissions. Where the action landed is where the participant's
//! presence shows ([`AttachedView::landed`]), and the person's devices draw
//! the same record from synced state when someone looks.
//!
//! Sync is the caller's: [`AttachedView::take_changes`] returns this
//! participant's own changes since the last call (the whole document the
//! first time, for a record it created) and [`AttachedView::merge`] takes a
//! peer's, through the record store's replication frontier as a browser
//! page's mounts do. The parts of a chain the app keeps beside the record
//! ([`Chain`](super::Chain)) sync the same way on routes of their own
//! ([`AttachedView::take_record_changes`], [`AttachedView::merge_record`]),
//! and the app's actions reach them through the chain the view publishes.

use std::cell::RefCell;
use std::rc::Rc;

use tilo_actions::door::{ActionAddress, ActionDescriptor, DoorError};
use tilo_actions::{ActionEnvelope, ActionOutput, ActionTransport};
use ui_core::application::{
    ApplicationDefinition, ComponentRunnerInputs, HostContext, HostContextInputs, LaunchTarget,
    RestoreInput,
};
use ui_core::application_view::InstanceViewStore;
use ui_core::collaboration::DocumentMutation;
use ui_core::headless::FrameHarness;
use ui_core::permissions::{PermissionContext, SharedPermissions, UserId};
use ui_core::portable_storage::{PortableStorage, StorageKey};
use ui_core::record::{RecordCheckout, RecordOwners, RecordStore, RecordSync};

/// The component instance a view mounts.
const INSTANCE: u64 = 1;

/// Where the view lays out. Never drawn; it only gives the view a size, as
/// a window would.
const VIEWPORT: (u32, u32) = (1280, 720);

/// Device name the view's storage is kept under.
const DEVICE: &str = "attached-view";

/// The actions the view applied, as its transport replicates them.
#[derive(Clone, Default)]
struct Landed(Rc<RefCell<Vec<ActionEnvelope>>>);

impl ActionTransport for Landed {
    fn replicate(&mut self, env: &ActionEnvelope) {
        self.0.borrow_mut().push(env.clone());
    }
}

/// One record held in its app's view, attached and never drawn. See the
/// module docs.
pub struct AttachedView {
    definition: &'static ApplicationDefinition,
    checkout: RecordCheckout,
    /// The app's view of the record: mounted, laid out, never drawn.
    frame: Box<FrameHarness>,
    /// The record store the view reads and writes.
    records: RecordStore,
    permissions: SharedPermissions,
    /// Who acts through the view: the invoker its operations are admitted for.
    me: String,
    /// The invoker as admitted: its kind and the person it acts for.
    invoker: tilo_actions::ActionInvoker,
    /// The task the invoker is carrying out, recorded with what it does.
    context: Option<tilo_actions::ActionContext>,
    landed: Landed,
    /// What this participant sent of the record, and its own changes set
    /// aside for the next publication.
    sync: RecordSync,
    /// Each record the view holds beside its own (the parts of a chain), by
    /// id: what was taken or merged of it so far.
    beside: std::collections::HashMap<ui_core::record::RecordId, RecordSync>,
    /// Where the view keeps its records, and the workspace: what a record
    /// beside its own that a peer started is kept in before it opens.
    cache: PortableStorage,
    workspace: String,
}

/// An [`AttachedView`] about to open ([`AttachedView::opening`]): whom it
/// is for, what they may do, and what the host lends the view.
pub struct OpenView<'a> {
    definition: &'static ApplicationDefinition,
    workspace: &'a str,
    checkout: RecordCheckout,
    document: Vec<u8>,
    invoker: tilo_actions::ActionInvoker,
    permissions: PermissionContext,
    created: bool,
    content: Option<tilo_content::ContentStore>,
}

impl OpenView<'_> {
    /// Open it for `invoker` (by default the record's owner).
    #[must_use]
    pub fn for_invoker(mut self, invoker: &tilo_actions::ActionInvoker) -> Self {
        self.invoker = invoker.clone();
        self
    }

    /// What the invoker may do through it (by default anything).
    #[must_use]
    pub fn with_permissions(mut self, permissions: PermissionContext) -> Self {
        self.permissions = permissions;
        self
    }

    /// Whether the invoker just created the record, so the first
    /// [`AttachedView::take_changes`] sends it whole.
    #[must_use]
    pub const fn created(mut self, created: bool) -> Self {
        self.created = created;
        self
    }

    /// Lend the view the workspace's content store, as a host lends a window
    /// its: the bytes a content hash names (an image another app made).
    #[must_use]
    pub fn lending(mut self, store: tilo_content::ContentStore) -> Self {
        self.content = Some(store);
        self
    }

    /// Mount the view.
    ///
    /// # Errors
    /// As [`AttachedView::open`].
    pub fn open(self) -> Result<AttachedView, String> {
        AttachedView::open_view(self)
    }
}

impl AttachedView {
    /// Mount `definition`'s view over the record `document` holds in
    /// `workspace`, for `me` with `permissions`. `created` when `me` just created
    /// the record, so the first [`Self::take_changes`] sends it whole.
    pub fn open(
        definition: &'static ApplicationDefinition,
        workspace: &str,
        checkout: RecordCheckout,
        document: Vec<u8>,
        me: &str,
        permissions: PermissionContext,
        created: bool,
    ) -> Result<Self, String> {
        Self::open_for(
            definition,
            workspace,
            checkout,
            document,
            &tilo_actions::ActionInvoker::actor(me),
            permissions,
            created,
        )
    }

    /// [`Self::open`] for `invoker` — an agent, say, which may act for a
    /// person — rather than a person by their id alone. Its changes are
    /// written under the record writer's actor for its handle on this host.
    ///
    /// # Errors
    /// As [`Self::open`].
    pub fn open_for(
        definition: &'static ApplicationDefinition,
        workspace: &str,
        checkout: RecordCheckout,
        document: Vec<u8>,
        invoker: &tilo_actions::ActionInvoker,
        permissions: PermissionContext,
        created: bool,
    ) -> Result<Self, String> {
        Self::opening(definition, workspace, checkout, document)
            .for_invoker(invoker)
            .with_permissions(permissions)
            .created(created)
            .open()
    }

    /// The view of `definition` over the record `document` holds in `workspace`,
    /// to open once said for whom, with what and what the host lends it
    /// ([`OpenView`]).
    #[must_use]
    pub fn opening<'a>(
        definition: &'static ApplicationDefinition,
        workspace: &'a str,
        checkout: RecordCheckout,
        document: Vec<u8>,
    ) -> OpenView<'a> {
        OpenView {
            definition,
            workspace,
            checkout,
            document,
            invoker: tilo_actions::ActionInvoker::actor("owner"),
            permissions: PermissionContext::permissive(),
            created: false,
            content: None,
        }
    }

    fn open_view(view: OpenView<'_>) -> Result<Self, String> {
        let OpenView {
            definition,
            workspace,
            checkout,
            document,
            invoker,
            permissions,
            created,
            content,
        } = view;
        let invoker = &invoker;
        let me = invoker.actor.as_str();
        let joined_at = (!created).then(|| heads_of(&document)).transpose()?;
        let cache = PortableStorage::new("attached-views", DEVICE)?;
        let key = if checkout.id.is_package_primary() {
            StorageKey::Primary {
                package: definition.app_id().into(),
                workspace: workspace.to_owned(),
            }
        } else {
            StorageKey::Record {
                package: definition.app_id().into(),
                workspace: workspace.to_owned(),
                record: checkout.id.as_str().into(),
            }
        };
        // The record is written by the page that opens it, which mints its
        // own writer then; the handle writes what it does through actions.
        cache.hydrate(key, document, None)?;
        let cache_kept = cache.clone();
        let records = RecordOwners::portable(cache.clone())
            .open(definition.app_id(), workspace)
            .map_err(|error| error.to_string())?;
        let views = Rc::new(
            InstanceViewStore::portable(cache, workspace).map_err(|error| error.to_string())?,
        );
        let permissions = SharedPermissions::new(permissions);
        let target = LaunchTarget::Record {
            checkout: checkout.clone(),
            reveal: None,
        };
        let context = HostContext::prepare(
            definition,
            HostContextInputs {
                records: records.clone(),
                views,
                device_id: DEVICE.into(),
                instance_id: INSTANCE,
                permissions: permissions.clone(),
                author: UserId(me.to_owned()),
                action_context: tilo_actions::ActionContext::default()
                    .with_invoker(invoker.clone()),
            },
            &target,
        )
        .map_err(|error| error.to_string())?;
        let mut context = context;
        if let Some(store) = content {
            context.provide_content(store);
        }
        let component = definition
            .instantiate(context, target, RestoreInput::None)
            .map_err(|error| error.to_string())?;
        let mut frame = FrameHarness::from_component(
            component,
            VIEWPORT,
            ComponentRunnerInputs {
                theme: ui_core::Theme::default(),
                text_renderer: ui_core::TextRenderer::new(),
            },
        )
        .map_err(|error| error.to_string())?;
        let landed = Landed::default();
        frame.set_action_transport(Box::new(landed.clone()))?;
        if let Some(joined_at) = &joined_at {
            refuse_written_on_open(definition, &records, &checkout, joined_at)?;
        }
        // A record joined starts where it was handed over: the only write
        // its view may make on open is a storage migration, which is sent
        // with the participant's first changes, as a window's is, so the
        // workspace and its other holders take it rather than diverge.
        let started = joined_at.or_else(|| {
            records
                .with(&checkout.id, ui_core::automerge::AutoCommit::get_heads)
                .filter(|_| !created)
        });
        let sync = started.map_or_else(RecordSync::new, RecordSync::delivered);
        Ok(Self {
            definition,
            checkout,
            frame: Box::new(frame),
            records,
            permissions,
            me: me.to_owned(),
            invoker: invoker.clone(),
            context: None,
            landed,
            sync,
            beside: std::collections::HashMap::new(),
            cache: cache_kept,
            workspace: workspace.to_owned(),
        })
    }

    /// The app whose view this is.
    #[must_use]
    pub const fn definition(&self) -> &'static ApplicationDefinition {
        self.definition
    }

    #[must_use]
    pub const fn checkout(&self) -> &RecordCheckout {
        &self.checkout
    }

    /// Who acts through the view.
    #[must_use]
    pub fn me(&self) -> &str {
        &self.me
    }

    /// The participant's permissions changed: a role granted or taken away.
    pub fn set_permissions(&mut self, permissions: PermissionContext) {
        self.permissions.set(permissions);
        self.frame.relayout();
    }

    /// The tree the view publishes, as the participant may reach it.
    #[must_use]
    pub fn resources(&self) -> Vec<tilo_actions::ResourceSpec> {
        let permissions = self.permissions.borrow();
        self.frame
            .resources()
            .into_iter()
            .filter_map(|resource| {
                permissions.permitted_resource(self.definition.app_id(), resource)
            })
            .collect()
    }

    /// Every document operation the participant may perform through the
    /// view now, with its typed parameters.
    #[must_use]
    pub fn operations(&self) -> Vec<ActionDescriptor> {
        tilo_actions::door::survey(&self.resources())
            .into_iter()
            .filter(|descriptor| descriptor.kind == tilo_actions::OperationKind::Document)
            .collect()
    }

    /// Perform the operation `address` names through the view, for the
    /// participant: permission, confirmation and strict argument binding
    /// exactly as for a person's click (`confirmed` when the person it acts
    /// for confirmed it). The change it made leaves with
    /// [`Self::take_changes`].
    pub fn invoke(
        &mut self,
        address: &ActionAddress,
        arguments: &serde_json::Map<String, serde_json::Value>,
        confirmed: bool,
    ) -> Result<ActionOutput, DoorError> {
        self.invoke_appearing(address, arguments, confirmed, None)
    }

    /// [`Self::invoke`] showing `appearance`, which the door already admitted
    /// for this one invocation. `None` clears any appearance the view's
    /// context carried: only a door sets one.
    ///
    /// # Errors
    /// As [`Self::invoke`].
    pub fn invoke_appearing(
        &mut self,
        address: &ActionAddress,
        arguments: &serde_json::Map<String, serde_json::Value>,
        confirmed: bool,
        appearance: Option<tilo_actions::Appearance>,
    ) -> Result<ActionOutput, DoorError> {
        let invoker = self.invoker_appearing(appearance);
        self.invoke_as(invoker, address, arguments, confirmed)
    }

    /// Whom [`Self::invoke_appearing`] admits an operation for: the
    /// participant, or the person the task says it acts for now, showing
    /// `appearance`.
    #[must_use]
    pub fn invoker_appearing(
        &self,
        appearance: Option<tilo_actions::Appearance>,
    ) -> tilo_actions::ActionInvoker {
        self.context
            .as_ref()
            .and_then(|context| context.invoker.clone())
            .filter(|invoker| invoker.actor == self.invoker.actor)
            .unwrap_or_else(|| self.invoker.clone())
            .with_appearance(appearance)
    }

    /// [`Self::invoke`] for `invoker`, whom the host admitted for this one
    /// invocation (an agent's, delivered to the app that owns the record):
    /// the operation and every edit it makes are theirs. Any operation the
    /// view offers — a document action, or an edit at the invoker's own
    /// caret.
    ///
    /// # Errors
    /// As [`Self::invoke`].
    pub fn invoke_as(
        &mut self,
        invoker: tilo_actions::ActionInvoker,
        address: &ActionAddress,
        arguments: &serde_json::Map<String, serde_json::Value>,
        confirmed: bool,
    ) -> Result<ActionOutput, DoorError> {
        let (_, started) = self.start_as(invoker, address, arguments, confirmed)?;
        // It answers once what it caused in the app has landed: a reply the
        // app asked a worker for in turn is applied as part of it, not of
        // whatever is invoked next. A job it started answers by itself.
        self.frame.settle_owed();
        Ok(started.completed().unwrap_or_default())
    }

    /// [`Self::invoke_as`], waiting up to `within` for an operation that
    /// runs as a job (rendering a picture, exporting a file's worth) to end
    /// and answering with what it ended as, where [`Self::invoke_as`]
    /// answers a job at once with nothing: for a host that hands an
    /// effect's result back to whoever asked, an agent planning its next
    /// step on it. A job still running when `within` is up is cancelled.
    ///
    /// # Errors
    /// As [`Self::invoke_as`]; the job's failure or cancellation, or that it
    /// did not end in time.
    pub fn invoke_as_awaiting(
        &mut self,
        invoker: tilo_actions::ActionInvoker,
        address: &ActionAddress,
        arguments: &serde_json::Map<String, serde_json::Value>,
        confirmed: bool,
        within: ui_core::time::Duration,
    ) -> Result<ActionOutput, DoorError> {
        let (invocation, started) = self.start_as(invoker, address, arguments, confirmed)?;
        if let Some(output) = started.completed() {
            self.frame.settle_owed();
            return Ok(output);
        }
        let ended = |frame: &FrameHarness| {
            frame
                .job_updates(invocation)
                .iter()
                .find(|update| update.is_terminal())
                .cloned()
        };
        if self
            .frame
            .wait_until(within, |frame| ended(frame).is_some())
        {
            // What the job's end caused is applied before it answers too.
            self.frame.settle_owed();
        }
        match ended(&self.frame) {
            Some(tilo_actions::InvocationUpdate::Succeeded { output, .. }) => Ok(output),
            Some(tilo_actions::InvocationUpdate::Failed { error, .. }) => {
                Err(DoorError::Failed(error.message))
            }
            Some(_) => Err(DoorError::Failed(format!(
                "{} was cancelled",
                address.action
            ))),
            None => {
                let _ = self.frame.cancel_job(invocation);
                Err(DoorError::Failed(format!(
                    "{} did not finish within {} seconds",
                    address.action,
                    within.as_secs()
                )))
            }
        }
    }

    /// Start the operation `address` names for `invoker`, as
    /// [`Self::invoke_as`] does: its invocation, and whether it finished.
    fn start_as(
        &mut self,
        invoker: tilo_actions::ActionInvoker,
        address: &ActionAddress,
        arguments: &serde_json::Map<String, serde_json::Value>,
        confirmed: bool,
    ) -> Result<
        (
            tilo_actions::InvocationId,
            ui_core::host_operation::ResourceOperationStart,
        ),
        DoorError,
    > {
        if !tilo_actions::door::survey(&self.resources())
            .iter()
            .any(|entry| &entry.address == address)
        {
            return Err(DoorError::Unknown(address.clone()));
        }
        self.landed.0.borrow_mut().clear();
        // History names the app the view is of, as its window does, within
        // whatever task the participant carries out.
        let ambient = self.context.clone().unwrap_or_default().enriched_by(
            &tilo_actions::ActionContext::default()
                .with_app(self.definition.app_id(), self.definition.title()),
        );
        self.frame.start_bound_job_within(
            Some(invoker),
            Some(&ambient),
            &ui_core::bound_dispatch::BoundActionAddress {
                instance_id: INSTANCE,
                address: address.clone(),
            },
            arguments,
            confirmed,
        )
    }

    /// Perform `invoke`, an action of the record's resource `R` built from
    /// its typed reference (`Note::EDIT.with(..)`, `Invoke::edit(..)`),
    /// through the view as [`Self::invoke`] does.
    ///
    /// # Errors
    /// As [`Self::invoke`], and when `invoke` does not bind or the view
    /// publishes no `R`.
    pub fn invoke_typed<R: tilo_resource::Resource>(
        &mut self,
        invoke: &tilo_resource::Invoke<R>,
        confirmed: bool,
    ) -> Result<ActionOutput, DoorError> {
        if let Some(refusal) = invoke.refusal() {
            return Err(DoorError::InvalidArguments(refusal.to_owned()));
        }
        // The record this view draws is the one its actions are published
        // under: one of another app's, kept here, is reached through the
        // provider that keeps it.
        let app = self.definition.app_id();
        let resource = self
            .resources()
            .into_iter()
            .find(|resource| resource.kind == R::KIND && resource.app().is_none_or(|of| of == app))
            .ok_or_else(|| DoorError::Unknown(ActionAddress::new(R::KIND, invoke.id)))?;
        self.invoke(
            &ActionAddress::new(resource.id.as_str(), invoke.id),
            &invoke.arguments,
            confirmed,
        )
    }

    /// [`Self::invoke`] acting at `place` instead of at the participant's
    /// caret: `place` is given as the operation's place parameter
    /// (`#[param(place)]`), and the participant lands there.
    ///
    /// # Errors
    /// As [`Self::invoke`]; refused as invalid arguments when the operation
    /// takes no place.
    pub fn invoke_at(
        &mut self,
        place: &tilo_resource::Place,
        address: &ActionAddress,
        arguments: &serde_json::Map<String, serde_json::Value>,
        confirmed: bool,
    ) -> Result<ActionOutput, DoorError> {
        let resources = self.resources();
        let param = tilo_actions::door::survey(&resources)
            .into_iter()
            .find(|entry| &entry.address == address)
            .ok_or_else(|| DoorError::Unknown(address.clone()))?
            .params
            .iter()
            .find(|param| param.is_place())
            .map(|param| param.name.to_string())
            .ok_or_else(|| {
                DoorError::InvalidArguments(format!(
                    "`{}` takes no place to act at",
                    address.action
                ))
            })?;
        let mut arguments = arguments.clone();
        arguments.insert(
            param,
            serde_json::to_value(place)
                .map_err(|error| DoorError::InvalidArguments(error.to_string()))?,
        );
        self.invoke(address, &arguments, confirmed)
    }

    /// The task the participant carries out from now on (`None`: none),
    /// recorded with each thing it does.
    pub fn set_context(&mut self, context: Option<tilo_actions::ActionContext>) {
        self.context = context;
    }

    /// The task the participant carries out, when it has one.
    #[must_use]
    pub const fn context(&self) -> Option<&tilo_actions::ActionContext> {
        self.context.as_ref()
    }

    /// Record one instruction that changed several records as one run in
    /// this record's history: a marker, no content. Leaves with
    /// [`Self::take_changes`]; whether anything was recorded.
    pub fn record_run(
        &mut self,
        label: &str,
        issued_by: Option<&str>,
        decision: Option<&str>,
        steps: &[ui_core::RunStep],
    ) -> bool {
        self.records
            .with(&self.checkout.id, |doc| {
                let by = doc.get_actor().to_hex_string();
                let recorded = ui_core::record_run_with_details(
                    doc,
                    label,
                    Some(&by),
                    issued_by,
                    Some(label),
                    decision,
                    steps,
                );
                if recorded.is_some() {
                    tilo_resource::history::commit_stamped_with_message(
                        doc,
                        Some(tilo_actions::FrameworkChange::Run.change_message()),
                    );
                }
                recorded.is_some()
            })
            .unwrap_or(false)
    }

    /// The last action the view applied for the participant's latest
    /// invocation: where its presence shows.
    #[must_use]
    pub fn landed(&self) -> Option<ActionEnvelope> {
        self.landed.0.borrow().last().cloned()
    }

    /// Read the record's document.
    pub fn read<R>(&self, read: impl FnOnce(&ui_core::automerge::AutoCommit) -> R) -> Option<R> {
        self.records.read(&self.checkout.id, read)
    }

    /// The participant's changes since the last call, or `None`. The first
    /// call on a record the participant created returns it whole.
    pub fn take_changes(&mut self) -> Option<DocumentMutation> {
        let next = publish(&mut self.sync, &self.records, &self.checkout.id)?;
        Some(next)
    }

    /// Merge a peer's change into the view's record. Incremental changes
    /// that build on nothing this record holds belong to another record (or
    /// arrived ahead of what they build on) and are left alone: `Ok(false)`.
    pub fn merge(&mut self, mutation: &DocumentMutation) -> Result<bool, String> {
        if let DocumentMutation::Incremental(bytes) = mutation
            && !self
                .records
                .with(&self.checkout.id, |doc| RecordSync::builds_on(doc, bytes))
                .unwrap_or(false)
        {
            return Ok(false);
        }
        // What this participant did and has not taken stays its own.
        if self.sync.snapshotted() {
            self.sync.set_aside(&self.records, &self.checkout.id).ok();
        }
        let changed = self
            .sync
            .merge(&self.records, &self.checkout, mutation.clone())?;
        self.frame.relayout();
        Ok(changed)
    }

    /// The chains of records the app keeps beside its own
    /// ([`Chain`](super::Chain)), as the view publishes them: each chain's
    /// id and the kind of its parts.
    #[must_use]
    pub fn chains(&self) -> Vec<RecordCheckout> {
        // Published beside the app's resource, among its children.
        self.frame
            .resources()
            .iter()
            .flat_map(|resource| std::iter::once(resource).chain(&resource.children))
            .filter_map(|resource| {
                let chain = super::chain_of_resource_id(resource.id.as_str())?;
                Some(RecordCheckout::new(
                    chain,
                    ui_core::record::RecordKind::new(resource.kind.clone()),
                ))
            })
            .collect()
    }

    /// `record` as the view holds it beside its own: a part of one of the
    /// app's chains ([`Self::chains`]), of that chain's kind. `None` for
    /// any other record.
    #[must_use]
    pub fn beside(&self, record: &ui_core::record::RecordId) -> Option<RecordCheckout> {
        let (chain, _) = record.chain_part()?;
        self.chains()
            .into_iter()
            .find(|held| held.id == chain)
            .map(|held| RecordCheckout::new(record.clone(), held.kind))
    }

    /// The records the view holds beside its own: the parts of the app's
    /// chains ([`Self::chains`]) open here, as they sync on routes of their
    /// own.
    #[must_use]
    pub fn records_beside(&self) -> Vec<RecordCheckout> {
        let chains = self.chains();
        self.records
            .open_records()
            .into_iter()
            .filter(|checkout| {
                checkout
                    .id
                    .chain_part()
                    .is_some_and(|(chain, _)| chains.iter().any(|held| held.id == chain))
            })
            .collect()
    }

    pub fn read_record<R>(
        &self,
        record: &ui_core::record::RecordId,
        read: impl FnOnce(&ui_core::automerge::AutoCommit) -> R,
    ) -> Option<R> {
        self.beside(record)?;
        self.records.read(record, read)
    }

    /// The participant's changes to `record`, one the view holds beside
    /// its own ([`Self::records_beside`]), since the last call: the whole
    /// record the first time, for one the participant started.
    pub fn take_record_changes(
        &mut self,
        record: &ui_core::record::RecordId,
    ) -> Option<DocumentMutation> {
        let sync = self.beside.entry(record.clone()).or_default();
        publish(sync, &self.records, record)
    }

    /// Merge a peer's change into `record`, a part of one of the app's
    /// chains ([`Self::beside`]), opening it first when the view holds it
    /// not yet (a part another device started). Changes that build on
    /// nothing the part holds are left alone: `Ok(false)`. Whether it
    /// changed.
    pub fn merge_record(
        &mut self,
        record: &ui_core::record::RecordId,
        mutation: &DocumentMutation,
    ) -> Result<bool, String> {
        let checkout = self.beside(record).ok_or_else(|| {
            format!(
                "{} is not a part of a chain {} keeps",
                record.as_str(),
                self.definition.app_id()
            )
        })?;
        if !self.records.is_ready(record) && self.records.try_open_record(&checkout).is_err() {
            // Kept as the peer sent it, then opened as the view's own are.
            let DocumentMutation::Snapshot(bytes) = mutation else {
                return Ok(false);
            };
            self.cache.hydrate(
                StorageKey::Record {
                    package: self.definition.app_id().into(),
                    workspace: self.workspace.clone(),
                    record: record.as_str().into(),
                },
                bytes.clone(),
                None,
            )?;
            self.records
                .try_open_record(&checkout)
                .map_err(|error| error.to_string())?;
        }
        if let DocumentMutation::Incremental(bytes) = mutation
            && !self
                .records
                .with(record, |doc| RecordSync::builds_on(doc, bytes))
                .unwrap_or(false)
        {
            return Ok(false);
        }
        // What this participant did and has not taken stays its own. A part
        // first met through a peer's change is not this participant's to
        // publish whole: it starts from what the record already holds.
        let heads = self
            .records
            .with(record, ui_core::automerge::AutoCommit::get_heads)
            .unwrap_or_default();
        let sync = self
            .beside
            .entry(record.clone())
            .or_insert_with(move || RecordSync::delivered(heads));
        if sync.snapshotted() {
            sync.set_aside(&self.records, record).ok();
        }
        let changed = sync.merge(&self.records, &checkout, mutation.clone())?;
        self.frame.relayout();
        Ok(changed)
    }
}

/// What to publish next of `record` as `sync` stands: the record whole the
/// first time, then this participant's own changes set aside since.
fn publish(
    sync: &mut RecordSync,
    records: &RecordStore,
    id: &ui_core::record::RecordId,
) -> Option<DocumentMutation> {
    if !sync.snapshotted() {
        let whole = sync.take_outbound(records, id).ok()??;
        sync.advance(whole.heads);
        return Some(whole.mutation);
    }
    sync.set_aside(records, id).ok()?;
    sync.take_set_aside()
}

/// The heads of the record `document` holds: what a participant joining it
/// was given, past which anything its view writes while it opens is refused
/// ([`refuse_written_on_open`]).
fn heads_of(document: &[u8]) -> Result<Vec<ui_core::automerge::ChangeHash>, String> {
    ui_core::automerge::AutoCommit::load(document)
        .map(|mut doc| doc.get_heads())
        .map_err(|error| error.to_string())
}

/// Refuse a view that wrote to the record `checkout` names, one its
/// participant joined at `joined_at`, as it opened ([`written_on_open`]).
fn refuse_written_on_open(
    definition: &ApplicationDefinition,
    records: &RecordStore,
    checkout: &RecordCheckout,
    joined_at: &[ui_core::automerge::ChangeHash],
) -> Result<(), String> {
    match records.with(&checkout.id, |doc| written_on_open(doc, joined_at)) {
        Some(Some(wrote)) => Err(format!(
            "{} wrote to a record it joined as it opened ({wrote}): only the record's \
             creator writes its initial content, and a participant that joins adds \
             nothing on open. What the record starts with belongs in the app's seed; \
             what a participant adds belongs behind a control they use",
            definition.app_id
        )),
        _ => Ok(()),
    }
}

/// What the app's view wrote to `doc` past `joined_at` while it opened, named
/// for the message that refuses it; `None` when it wrote nothing. A storage
/// migration, or the structure and identity every member derives the same
/// way, is the framework's and none of the app's.
///
/// Refused rather than kept: the participant's own changes are sent from
/// where it joined, so the view's write would be sent as if the participant
/// had made it, which no member did. Deferring it until
/// the record's content arrives would only move that fork later.
fn written_on_open(
    doc: &mut ui_core::automerge::AutoCommit,
    joined_at: &[ui_core::automerge::ChangeHash],
) -> Option<String> {
    use tilo_actions::{ActionContext, Did, FrameworkChange, HistoryOp};
    let wrote: Vec<String> = doc
        .get_changes(joined_at)
        .into_iter()
        .filter_map(|change| {
            let message = change.message()?;
            if message.starts_with(tilo_actions::CONTINUATION_PREFIX)
                || FrameworkChange::from_change_message(message) == Some(FrameworkChange::Native)
            {
                return Some("an edit".to_owned());
            }
            Some(match ActionContext::from_change_message(message)?.what? {
                Did::Verb(verb) => format!("`{}`", verb.action.action),
                Did::Edit(edit) => format!("an edit of `{}`", edit.field),
                Did::Group(_) => "a group of edits".to_owned(),
                Did::History(step) if matches!(step.op, HistoryOp::Migrate { .. }) => return None,
                Did::History(_) => "a history step".to_owned(),
            })
        })
        .collect();
    (!wrote.is_empty()).then(|| wrote.join(", "))
}