tilo_app/framework/

person.rs

//! Records an app opens beside the one it shows: its own record of a kind
//! (what was watched, the words taught to the keyboard, where reading
//! stopped), kept with its other records in the workspace it is open in,
//! and the person's shared records another app keeps for all of theirs
//! (their accounts, their contacts), kept in the person's own scope.

use std::any::Any;
use std::cell::RefCell;
use std::collections::HashMap;
use std::rc::Rc;

use tilo_actions::{Action as _, ActionContext, ActionError, ActionInvoker, ChangeKind};

use super::live::Live;
use super::record::{Held, RecordDoor};
use super::section::{SectionDoor, SectionKind};
use tilo_resource::{Invoke, Resource};
use ui_core::LocalState;
use ui_core::history_mode::HistoryOwner;
use ui_core::record::RecordKind;
use ui_core::record::StoredRecord;
use ui_core::record::person::PersonRecords;

/// A record the app keeps beside the one it shows: one per resource kind
/// and app in the workspace the app is open in, the same on every device,
/// so it reaches the person's other devices with the workspace. What was
/// watched, the words taught to the keyboard, where reading stopped. Or
/// one of the person's shared records another app keeps
/// ([`tilo_resource::SharedRecord`]). The shared ones belong to the person
/// rather than to a workspace, so they are kept in the person's own scope and
/// stay on this device until their personal store carries them.
///
/// It is a resource like the app's own: its edits are its actions, applied
/// by the replayable executor, attributed to the person, written into its
/// history and undone per step ([`Self::undo`]). It is created with the
/// resource's genesis ([`Resource::initialize`]) where it does not exist
/// yet. Read it through [`Self::state`] or [`Self::with`]; an edit from
/// another window or device reaches it on the next frame.
pub struct PersonRecord<P: Resource> {
    shared: Rc<Shared<P>>,
}

impl<P: Resource> Clone for PersonRecord<P> {
    fn clone(&self) -> Self {
        Self {
            shared: Rc::clone(&self.shared),
        }
    }
}

struct Shared<P: Resource> {
    record: StoredRecord,
    /// The app that keeps the record, when this app does not change it:
    /// it is read here and its edits are refused.
    owner: Option<&'static str>,
    app_id: &'static str,
    app_title: &'static str,
    me: String,
    /// The state, followed change by change: what views of the record read.
    live: Live<P>,
    /// The same state, for controls bound to it.
    state: LocalState<Rc<P::State>>,
    /// The record as views and the door edit it.
    held: RefCell<Option<Rc<Held<P>>>>,
}

impl<P: Resource> Shared<P> {
    /// Follow the record when it moved, reading only what changed. Whether
    /// it did.
    fn refresh(&self) -> bool {
        let mut moved = match self.record.read(|doc| self.live.sync(doc)) {
            Some(Ok(moved)) => moved,
            Some(Err(error)) => {
                unreadable_person_record(P::KIND, &error);
                false
            }
            None => false,
        };
        if !moved && self.live.unreadable().is_none() {
            // The record is small and read whole, so a change it cannot
            // read is noticed here rather than by whoever publishes it. The
            // reader reads it again only when the document moved since it
            // last read it whole; what that read found is the state too.
            match self.record.read(|doc| self.live.reread(doc)) {
                Some(Ok(reread)) => moved = reread,
                Some(Err(error)) => unreadable_person_record(P::KIND, &error),
                None => {}
            }
        }
        // Views of the record follow it whole: it is small.
        let _ = self.live.take_change();
        if moved {
            self.state.set(self.live.get());
        }
        moved
    }
}

impl<P: Resource> PersonRecord<P> {
    /// The current state.
    #[must_use]
    pub fn get(&self) -> Rc<P::State> {
        self.shared.refresh();
        self.shared.state.with(Rc::clone)
    }

    /// Read the current state.
    pub fn with<T>(&self, read: impl FnOnce(&P::State) -> T) -> T {
        read(&self.get())
    }

    /// Why the record stopped reading as `P`, if it did: the state is then
    /// the last one that read, and a view shows this instead of it. Its
    /// published actions say the same.
    #[must_use]
    pub fn unreadable(&self) -> Option<String> {
        self.shared.refresh();
        self.shared.live.unreadable().map(|why| why.reason)
    }

    /// The state as view state that follows every change, for a control
    /// bound to it.
    #[must_use]
    pub fn state(&self) -> LocalState<Rc<P::State>> {
        self.shared.state.clone()
    }

    /// Increases whenever the state changes.
    #[must_use]
    pub fn revision(&self) -> u64 {
        self.shared.refresh();
        self.shared.live.revision()
    }

    /// Apply `action` now: one change of the record, attributed to the
    /// person, recorded in its history and — for content the person made —
    /// one undo step of theirs.
    pub fn apply(&self, action: &P::Action) -> Result<(), ActionError> {
        self.apply_as(action, &ActionInvoker::actor(&self.shared.me))
    }

    /// [`Self::apply`] by `invoker`: the person, or software acting for
    /// them.
    pub(crate) fn apply_as(
        &self,
        action: &P::Action,
        invoker: &ActionInvoker,
    ) -> Result<(), ActionError> {
        let shared = &self.shared;
        if let Some(owner) = shared.owner {
            return Err(ActionError::Refused(format!(
                "the person's {} are edited in {owner}",
                P::LABEL.to_lowercase()
            )));
        }
        let encoded = tilo_resource::encode::<P>(action)?;
        let change = action.change_kind();
        let context = ActionContext::for_resource(P::KIND, P::KIND, P::LABEL)
            .with_app(shared.app_id, shared.app_title)
            .with_invoker(invoker.clone())
            .with_change(change);
        shared
            .record
            .edit(change == ChangeKind::Content, |doc| {
                let writer =
                    ui_core::history_source::authors::device_actor(&shared.me, doc.get_actor());
                tilo_actions::apply_local_with_context(doc, action, encoded, Some(&writer), context)
                    .map(|_| ())
                    .map_err(|error| error.to_string())
            })
            .map_err(ActionError::Refused)?;
        shared.refresh();
        Ok(())
    }

    /// Apply the action `invoke` names, as [`Self::apply`].
    pub fn invoke(&self, invoke: &Invoke<P>) -> Result<(), ActionError> {
        let action = invoke
            .build(tilo_resource::origin_now_ms())
            .map_err(ActionError::Refused)?;
        self.apply(&action)
    }

    /// Whether this app changes the record: its own, or a shared one it is
    /// an editor of; any other is read here.
    #[must_use]
    pub fn editable(&self) -> bool {
        self.shared.owner.is_none()
    }

    /// Undo the person's last edit of the record. Whether there was one.
    pub fn undo(&self) -> bool {
        let undone = self.shared.record.undo();
        self.shared.refresh();
        undone
    }

    /// Redo the person's last undone edit of the record.
    pub fn redo(&self) -> bool {
        let redone = self.shared.record.redo();
        self.shared.refresh();
        redone
    }

    /// Whether the record reaches other devices: it has a route. One kept
    /// on this device only has none.
    #[must_use]
    pub fn syncs(&self) -> bool {
        self.shared.record.syncs()
    }

    /// Where the content this record references — a picture its state
    /// names by hash — is stored and read: with the record, carried on its
    /// route. `None` for a record kept on this device only, which keeps no
    /// content.
    #[must_use]
    pub fn content(&self) -> Option<tilo_content::ContentStore> {
        self.shared.record.content()
    }

    /// The record underneath, for a test or host that carries it between
    /// devices itself.
    #[must_use]
    pub fn record(&self) -> &StoredRecord {
        &self.shared.record
    }
}

/// An open record: the app that owns it, and its kind.
type OpenKey = (&'static str, String);

/// The person's records a root's views opened, shared by every scope of the
/// root: one [`PersonRecord`] per resource kind.
pub(crate) struct PersonState {
    /// The person's shared records ([`tilo_resource::SharedRecord`]); none
    /// for a host that keeps only the settings sections, whose history is
    /// the settings document's.
    records: Option<PersonRecords>,
    /// The app's own records of a kind, in the workspace it is open in;
    /// none for a host that keeps only the shared ones (the session's
    /// settings).
    own: Option<PersonRecords>,
    app_id: &'static str,
    app_title: &'static str,
    me: String,
    /// The ids they went by before this device had an identity, under which
    /// what they changed is still theirs.
    earlier: Vec<String>,
    /// The open records, by the app that owns them and their kind.
    opened: RefCell<HashMap<OpenKey, Rc<dyn Any>>>,
    /// The records of the person's other apps keep, held here too.
    others: RefCell<HashMap<&'static str, PersonRecords>>,
    owners: Rc<RefCell<Vec<HistoryOwner>>>,
    refreshers: RefCell<Vec<Box<dyn Fn() -> bool>>>,
    /// The open records' undo and redo, as the palette and agents reach
    /// them.
    published: RefCell<Vec<Published>>,
    /// The records that could not be opened as views asked for them, by
    /// what they are, with what they publish: their declared actions,
    /// unavailable for why. Those views are told now, and never again for
    /// the same record.
    unavailable: RefCell<HashMap<(String, &'static str), tilo_actions::ResourceSpec>>,
}

/// One open record as the root publishes it.
struct Published {
    id: String,
    label: String,
    /// Its field edits and verbs, as the door reaches them.
    door: Rc<dyn RecordDoor>,
    /// Take back (`true`) or redo (`false`) one of the person's steps, for
    /// the invoker named. Whether there was one.
    step: Step,
}

/// Take back (`true`) or redo (`false`) one step for the invoker named.
type Step = Box<dyn Fn(bool, &str) -> bool>;

/// A person record just opened as its type: its shared state, its door and
/// its undo and redo.
struct Opened {
    shared: Rc<dyn Any>,
    door: Rc<dyn RecordDoor>,
    step: Step,
}

/// The operation type of a person record's undo and redo.
pub(crate) const HISTORY_TYPE: &str = "tilo.app.person-history";

/// The most steps one undo or redo of a person record takes.
const MAX_STEPS: i64 = 50;

/// What a person record's undo or redo was asked.
#[derive(serde::Serialize, serde::Deserialize)]
struct HistoryRequest {
    record: String,
    undo: bool,
    steps: Option<i64>,
}

/// The address a person record of `kind` is published under.
#[must_use]
pub(crate) fn resource_id(kind: &str) -> String {
    format!("person:{kind}")
}

/// One of the person's own records an app keeps, declared with the app
/// ([`ResourceApp::PERSON_RECORDS`](super::ResourceApp::PERSON_RECORDS)).
///
/// It is the person's, not the workspace's: kept in their own scope, carried
/// to their other devices by their personal store, and never reaching a
/// collaborator. The app's committed surface names it whether or not a view
/// of it is showing, so the host admits the app's changes to it — and its
/// reads of it — against the surface.
#[derive(Clone, Copy)]
pub struct PersonKind {
    kind: &'static str,
    report: fn() -> tilo_resource::Surface,
    open: fn(&super::settings::ViewStorage),
}

impl PersonKind {
    /// The person's record `P`, kept by the app that owns it
    /// ([`SharedRecord`](tilo_resource::SharedRecord)).
    #[must_use]
    pub const fn shared<P: tilo_resource::SharedRecord>() -> Self {
        Self {
            kind: P::KIND,
            report: shared_surface::<P>,
            open: open_shared::<P>,
        }
    }

    /// The kind of record it is.
    #[must_use]
    pub const fn kind(&self) -> &'static str {
        self.kind
    }

    /// Its surface, as the app's surface report lists it: `P`'s, marked as
    /// the person's own.
    #[must_use]
    pub fn surface(&self) -> tilo_resource::Surface {
        (self.report)()
    }

    /// Open it with the window, so it is published before any view shows it.
    pub(crate) fn open(&self, storage: &super::settings::ViewStorage) {
        (self.open)(storage);
    }
}

fn shared_surface<P: tilo_resource::SharedRecord>() -> tilo_resource::Surface {
    tilo_resource::Surface {
        person: true,
        ..P::surface()
    }
}

fn open_shared<P: tilo_resource::SharedRecord>(storage: &super::settings::ViewStorage) {
    let _ = storage.shared_person::<P>();
}

fn history_spec(record: &str, label: &str, undo: bool) -> tilo_actions::ActionSpec {
    let mut spec = history_operation(record.to_owned(), label, undo);
    spec.type_mut().contract.result = tilo_actions::ResultSpec::Json {
        schema: serde_json::json!({
            "type": "object",
            "properties": { "steps": { "type": "integer" } },
        }),
    };
    spec
}

fn history_operation(record: String, label: &str, undo: bool) -> tilo_actions::ActionSpec {
    let (id, verb) = if undo {
        ("undo", "Undo")
    } else {
        ("redo", "Redo")
    };
    tilo_actions::ActionSpec::typed_operation(
        id,
        verb,
        verb,
        tilo_actions::OperationKind::Effect,
        HISTORY_TYPE,
        vec![
            tilo_actions::ActionParam::optional(
                "steps",
                tilo_actions::ParamType::Number,
                "How many of your steps (default 1, at most 50)",
            )
            .nullable(),
        ],
        move |args| {
            tilo_actions::EncodedAction::encode_operation(
                HISTORY_TYPE,
                &HistoryRequest {
                    record: record.clone(),
                    undo,
                    steps: args.integer("steps"),
                },
            )
            .unwrap_or_else(|_| tilo_actions::EncodedAction {
                type_id: tilo_actions::resource::INVALID_ARGUMENTS_TYPE.to_owned(),
                payload: Vec::new(),
            })
        },
    )
    .of_kind(tilo_actions::ActionKind::Read)
    .with_description(if undo {
        format!("Take back your last change to your {label}.")
    } else {
        format!("Make again the change to your {label} you last took back.")
    })
}

impl PersonState {
    pub(crate) fn new(
        records: PersonRecords,
        own: Option<PersonRecords>,
        app_id: &'static str,
        app_title: &'static str,
    ) -> Self {
        let me = records.author().0.clone();
        Self::named(Some(records), own, me, Vec::new(), app_id, app_title)
    }

    /// The person `me`, whose shared records this host does not hold: their
    /// undo and redo of the settings sections are published all the same,
    /// and read the sections' history in the settings document. `earlier`
    /// are the ids they went by before this device had an identity, whose
    /// changes are theirs too.
    pub(crate) fn without_records(
        me: String,
        earlier: Vec<String>,
        app_id: &'static str,
        app_title: &'static str,
    ) -> Self {
        Self::named(None, None, me, earlier, app_id, app_title)
    }

    fn named(
        records: Option<PersonRecords>,
        own: Option<PersonRecords>,
        me: String,
        earlier: Vec<String>,
        app_id: &'static str,
        app_title: &'static str,
    ) -> Self {
        Self {
            records,
            own,
            app_id,
            app_title,
            me,
            earlier,
            opened: RefCell::default(),
            others: RefCell::default(),
            owners: Rc::default(),
            refreshers: RefCell::default(),
            published: RefCell::default(),
            unavailable: RefCell::default(),
        }
    }

    /// The person's record of `P`, opened on first use.
    pub(crate) fn open<P: Resource>(&self) -> Option<PersonRecord<P>> {
        self.open_of::<P>(self.app_id, true, true, false)
    }

    /// The shared record `P`, opened on first use: kept by its owner, a copy
    /// of it here in every other app, changed where `P` says.
    pub(crate) fn open_shared<P: tilo_resource::SharedRecord>(&self) -> Option<PersonRecord<P>> {
        self.open_of::<P>(P::OWNER, P::edited_by(self.app_id), true, true)
    }

    /// The shared record `P`, opened on first use as [`Self::open_shared`]
    /// but never published: a host holds it for its own edits, and the app
    /// whose window shows it publishes its actions.
    pub(crate) fn hold_shared<P: tilo_resource::SharedRecord>(&self) -> Option<PersonRecord<P>> {
        self.open_of::<P>(P::OWNER, P::edited_by(self.app_id), false, true)
    }

    /// The record of `P` that the app `owner` keeps, opened on first use,
    /// whether this app changes it, whether it is published when it is
    /// this app's own, and whether it is one of the person's shared records
    /// rather than the app's own in its workspace.
    fn open_of<P: Resource>(
        &self,
        owner: &'static str,
        edits: bool,
        publish: bool,
        shared: bool,
    ) -> Option<PersonRecord<P>> {
        let open = |record: StoredRecord| -> Result<Opened, String> {
            let shared = self.shared_of::<P>(record, (!edits).then_some(owner))?;
            let held = Rc::new(held::<P>(&shared, edits));
            *shared.held.borrow_mut() = Some(Rc::clone(&held));
            let weak = Rc::downgrade(&shared);
            Ok(Opened {
                shared: shared as Rc<dyn Any>,
                door: held,
                step: Box::new(move |undo, _| {
                    weak.upgrade().is_some_and(|shared| {
                        let record = PersonRecord { shared };
                        if undo { record.undo() } else { record.redo() }
                    })
                }),
            })
        };
        let shared = self.open_kind(
            owner,
            &RecordType {
                kind: P::KIND,
                label: P::LABEL,
                unreadable: &|reason| {
                    tilo_resource::resource::unreadable_parts::<P>(
                        &resource_id(P::KIND),
                        P::LABEL,
                        reason,
                    )
                },
            },
            &|doc| P::initialize(doc).map_err(|error| error.to_string()),
            &open,
            (publish, shared),
        )?;
        shared
            .downcast::<Shared<P>>()
            .ok()
            .map(|shared| PersonRecord { shared })
    }

    /// The open record of `kind` that the app `owner` keeps, or the one
    /// `open` makes of it, created by `initialize` where it does not exist
    /// yet, kept and (for this app's own, when `publish`) published: the
    /// part of opening a record that does not depend on its type. A
    /// `shared` one is the person's ([`tilo_resource::SharedRecord`]); any
    /// other is the app's own, in the workspace it is open in.
    fn open_kind(
        &self,
        owner: &'static str,
        of: &RecordType<'_>,
        initialize: &dyn Fn(&mut ui_core::automerge::AutoCommit) -> Result<(), String>,
        open: &dyn Fn(StoredRecord) -> Result<Opened, String>,
        (publish, shared): (bool, bool),
    ) -> Option<Rc<dyn Any>> {
        let (kind, label) = (of.kind, of.label);
        let key = (owner, kind.to_owned());
        if let Some(open) = self.opened.borrow().get(&key) {
            return Some(Rc::clone(open));
        }
        let records = if shared {
            self.records_of(owner)?
        } else {
            self.own.clone()?
        };
        let record = match open_record(&records, kind.to_owned(), kind, initialize) {
            Ok(record) => record,
            Err(reason) => return self.note_unavailable(owner, of, &reason, publish),
        };
        let Opened { shared, door, step } = match open(record) {
            Ok(opened) => opened,
            Err(reason) => return self.note_unavailable(owner, of, &reason, publish),
        };
        if owner != self.app_id || !publish {
            self.opened.borrow_mut().insert(key, Rc::clone(&shared));
            return Some(shared);
        }
        self.publish(
            key,
            Rc::clone(&shared),
            Published {
                id: resource_id(kind),
                label: label.to_owned(),
                door,
                step,
            },
        );
        Some(shared)
    }

    /// `record` read as `P`, followed from now on.
    ///
    /// # Errors
    /// Why the record does not read as `P`: it could not be migrated to the
    /// storage version the app reads, or what it holds is not a `P`.
    fn shared_of<P: Resource>(
        &self,
        record: StoredRecord,
        owner: Option<&'static str>,
    ) -> Result<Rc<Shared<P>>, String> {
        // An older record is brought up to the resource's storage version
        // before it is read, as the app's record is when it opens: once, as
        // the same housekeeping change on every device, nobody's undo step.
        let older = record
            .read(tilo_resource::evolution::needs_migrate::<P>)
            .ok_or_else(|| "the record cannot be read".to_owned())?;
        if older
            && let Err(error) = record.edit(false, |doc| {
                tilo_resource::evolution::migrate::<P>(doc).map_err(|error| error.to_string())
            })
        {
            return Err(format!(
                "it could not be brought up to this app's storage version: {error}"
            ));
        }
        let reader = record
            .read(tilo_resource::Reader::<P>::read)
            .ok_or_else(|| "the record cannot be read".to_owned())?
            .map_err(|error| format!("it does not read: {error}"))?;
        let live = Live::new(reader);
        self.owners.borrow_mut().push(record.history_owner());
        let shared = Rc::new(Shared::<P> {
            record,
            owner,
            app_id: self.app_id,
            app_title: self.app_title,
            me: self.me.clone(),
            state: LocalState::new(live.get()),
            live,
            held: RefCell::new(None),
        });
        let weak = Rc::downgrade(&shared);
        self.refreshers.borrow_mut().push(Box::new(move || {
            weak.upgrade().is_some_and(|shared| shared.refresh())
        }));
        Ok(shared)
    }

    /// The settings section `kind` held as a record, opened on first use and
    /// published with the undo and redo of each invoker's steps on it.
    pub(crate) fn open_section(&self, kind: Rc<SectionKind>) -> Rc<SectionDoor> {
        let key = (self.app_id, kind.kind.to_owned());
        if let Some(door) = self
            .opened
            .borrow()
            .get(&key)
            .and_then(|open| Rc::clone(open).downcast::<SectionDoor>().ok())
        {
            return door;
        }
        let door = Rc::new(SectionDoor::new(
            kind,
            self.me.clone(),
            self.earlier.clone(),
        ));
        let stepping = Rc::downgrade(&door);
        self.publish(
            key,
            Rc::clone(&door) as Rc<dyn Any>,
            Published {
                id: door.id().to_owned(),
                label: door.label().to_owned(),
                door: Rc::clone(&door) as Rc<dyn RecordDoor>,
                step: Box::new(move |undo, by| {
                    stepping.upgrade().is_some_and(|door| door.step(undo, by))
                }),
            },
        );
        door
    }

    /// The person's records `owner` keeps: this app's own, or another app's,
    /// opened once.
    fn records_of(&self, owner: &'static str) -> Option<PersonRecords> {
        // A host that keeps the person's shared records lends this app its
        // own as well: a second writer of them here would store nowhere the
        // host stores or syncs.
        if owner == self.app_id && !self.records.as_ref()?.shared_by_host() {
            return self.records.clone();
        }
        let mut others = self.others.borrow_mut();
        if let Some(records) = others.get(owner) {
            return Some(records.clone());
        }
        let records = self
            .records
            .as_ref()?
            .of_package(owner)
            .map_err(|error| {
                tracing::warn!(owner, %error, "the person's records of another app are unavailable");
            })
            .ok()?;
        others.insert(owner, records.clone());
        Some(records)
    }

    /// Note that the record `P` that `owner` keeps could not be opened, for
    /// `reason`: the root publishes it with its declared actions
    /// unavailable for that reason, rather than the record going quietly
    /// missing from the surface.
    fn note_unavailable(
        &self,
        owner: &'static str,
        of: &RecordType<'_>,
        reason: &str,
        publish: bool,
    ) -> Option<Rc<dyn Any>> {
        unreadable_person_record(of.kind, &reason);
        // Only the record this app would have published is published for
        // the reason: one another app keeps and this one reads is that
        // app's surface, which registers the actions its own record has.
        if owner == self.app_id && publish {
            let published = (of.unreadable)(reason);
            self.unavailable
                .borrow_mut()
                .insert((owner.to_owned(), of.kind), published);
        }
        None
    }

    /// Every record a view asked for that could not be opened, as it is
    /// published: its declared actions, unavailable for why.
    pub(crate) fn unavailable(&self) -> Vec<tilo_actions::ResourceSpec> {
        self.unavailable.borrow().values().cloned().collect()
    }

    /// Keep the record opened under `key`, publishing its door and its undo
    /// and redo.
    fn publish(&self, key: OpenKey, open: Rc<dyn Any>, published: Published) {
        self.published.borrow_mut().push(published);
        self.opened.borrow_mut().insert(key, open);
    }

    /// Read every open record that moved. Whether one did.
    pub(crate) fn refresh(&self) -> bool {
        self.refreshers
            .borrow()
            .iter()
            .fold(false, |moved, refresh| refresh() | moved)
    }

    /// The open records as resources of their own: the person's undo and
    /// redo of each, which the palette and agents reach like the app's own
    /// history.
    pub(crate) fn resources(&self) -> Vec<tilo_actions::ResourceSpec> {
        self.published
            .borrow()
            .iter()
            .map(|published| {
                published
                    .door
                    .publish()
                    .with_action(history_spec(&published.id, &published.label, true))
                    .with_action(history_spec(&published.id, &published.label, false))
            })
            .collect()
    }

    /// The open records of the person's own, as the door changes them.
    pub(crate) fn doors(&self) -> Vec<Rc<dyn RecordDoor>> {
        self.published
            .borrow()
            .iter()
            .map(|published| Rc::clone(&published.door))
            .collect()
    }

    pub(crate) fn me(&self) -> &str {
        &self.me
    }

    /// Answer an undo or redo of an open record: how many steps it took.
    pub(crate) fn answer(&self, payload: &[u8]) -> Result<tilo_actions::ActionOutput, String> {
        let invoker = ui_core::invocation_scope::current_invoker()
            .unwrap_or_else(|| ActionInvoker::actor(&self.me));
        self.answer_for(payload, &invoker)
    }

    /// [`Self::answer`] for `invoker`.
    pub(crate) fn answer_for(
        &self,
        payload: &[u8],
        invoker: &ActionInvoker,
    ) -> Result<tilo_actions::ActionOutput, String> {
        let request: HistoryRequest =
            tilo_actions::decode_json(payload).map_err(|error| error.to_string())?;
        let steps = request.steps.unwrap_or(1);
        if !(1..=MAX_STEPS).contains(&steps) {
            return Err(format!("steps is 1 to {MAX_STEPS}"));
        }
        if invoker.actor != self.me && invoker.on_behalf_of.as_deref() != Some(self.me.as_str()) {
            return Err(format!(
                "`{}` is {}'s own; only they change it",
                request.record, self.me
            ));
        }
        let published = self.published.borrow();
        let record = published
            .iter()
            .find(|published| published.id == request.record)
            .ok_or_else(|| format!("no record of yours is open as {}", request.record))?;
        let mut taken = 0;
        while taken < steps && (record.step)(request.undo, &invoker.actor) {
            taken = taken.saturating_add(1);
        }
        if taken == 0 {
            return Err(if request.undo {
                "nothing of yours to undo".to_owned()
            } else {
                "nothing of yours to redo".to_owned()
            });
        }
        Ok(tilo_actions::ActionOutput {
            value: Some(serde_json::json!({ "steps": taken })),
            resources: vec![record.id.clone()],
        })
    }

    /// The routes of the open records, which the runtime syncs: a record
    /// kept on this device only has none.
    pub(crate) fn owners(&self) -> Vec<HistoryOwner> {
        self.owners.borrow().clone()
    }
}

/// The record `kind` that `records` keeps, made by `initialize` where it
/// does not exist yet.
///
/// # Errors
/// Why the record cannot be opened: the store refused it, or it cannot be
/// created.
fn open_record(
    records: &PersonRecords,
    kind: String,
    of: &str,
    initialize: &dyn Fn(&mut ui_core::automerge::AutoCommit) -> Result<(), String>,
) -> Result<StoredRecord, String> {
    records
        .open_record(RecordKind::new(kind), initialize)
        .map_err(|error| format!("{of}'s record cannot be opened: {error}"))
}

/// The record `shared` as views and the door edit it: read into a state of
/// its own that follows the record, changed as the person.
fn held<P: Resource>(shared: &Rc<Shared<P>>, edits: bool) -> Held<P> {
    let following = Rc::downgrade(shared);
    let applying = Rc::downgrade(shared);
    Held::new(
        resource_id(P::KIND),
        format!("Your {}", P::LABEL.to_lowercase()),
        edits,
        shared.live.clone(),
        move |_: &Live<P>| {
            if let Some(shared) = following.upgrade() {
                shared.refresh();
            }
        },
        move |action: &P::Action, invoker: &ActionInvoker| {
            let shared = applying
                .upgrade()
                .ok_or_else(|| ActionError::Refused("the record is closed".into()))?;
            PersonRecord { shared }.apply_as(action, invoker)
        },
    )
}

impl<P: Resource> super::record::sealed::Hold<P> for PersonRecord<P> {
    fn held(&self, _storage: super::record::sealed::Storage<'_>) -> Option<Rc<Held<P>>> {
        self.shared.held.borrow().clone()
    }

    fn door(
        &self,
        _storage: super::record::sealed::Storage<'_>,
    ) -> Option<super::record::sealed::Door> {
        self.shared
            .held
            .borrow()
            .clone()
            .map(|held| super::record::sealed::Door(held as Rc<dyn RecordDoor>))
    }
}

impl Drop for PersonState {
    /// The window closes: what the person did is stored before it goes.
    fn drop(&mut self) {
        for records in self.records.iter().chain(&self.own) {
            if let Err(error) = records.flush() {
                tracing::warn!(%error, "the records beside the app's own could not be stored");
            }
        }
    }
}

/// Log that the person's record of `kind` does not read: one event site in
/// the runtime rather than one in every app for each record type.
#[cold]
#[inline(never)]
fn unreadable_person_record(kind: &'static str, error: &dyn std::fmt::Display) {
    tracing::warn!(kind, %error, "person record unreadable");
}

/// A person record's type, as the part of opening one that does not depend
/// on it reads it: compiled once, not into every app.
struct RecordType<'a> {
    kind: &'static str,
    label: &'static str,
    /// What the record publishes when it could not be opened, for why.
    unreadable: &'a dyn Fn(&str) -> tilo_actions::ResourceSpec,
}