tilo_app/framework/

dispatch.rs

//! Submitting edits: every change a view makes is an action the host checks
//! against permissions, applies, records for undo and history, and
//! replicates.

#[cfg(test)]
#[path = "dispatch_tests.rs"]
mod tests;

use std::cell::{Cell, RefCell};
use std::collections::VecDeque;
use std::rc::Rc;

use tilo_actions::{
    ActionAddress, ActionBinding, ActionContext, ActionError, ActionInvoker, ActionNeed,
    ControlInvocation,
};

use super::controls::Actions;
use tilo_resource::{Edit, Effect, Invoke, Resource};
use ui_core::LocalState;
use ui_core::automerge::ChangeHash;
use ui_core::permissions::{ActionKind, LivePermissions, PermissionScope, TreePath, policy};

/// What a view asks whether its participant may do.
#[derive(Clone, Debug, PartialEq, Eq)]
enum Asked {
    Need(ActionNeed),
    Govern,
    /// Whether what the workspace holds has arrived, so a choice made from the
    /// record (a free seat) is made from what everyone sees.
    Arrived,
}
use ui_core::widget::Edits;
use ui_core::widget::controls::{AttributedControlInvocation, Origin};

/// What reacting needs: an undoable change below the reactions field,
/// wherever it is.
fn reaction_need() -> ActionNeed {
    ActionNeed::reactions()
}

/// Whether the field edit in `arguments` reacts or takes a reaction back.
fn reacts(arguments: &serde_json::Map<String, serde_json::Value>) -> bool {
    arguments
        .get(tilo_resource::EDIT_PARAM)
        .and_then(|edit| edit.get("op"))
        .and_then(serde_json::Value::as_str)
        .is_some_and(|op| op == "react" || op == "unreact")
}

/// A queued invocation and who asked for it.
type Queued = (AttributedControlInvocation, Origin);

/// Something a dispatcher submits and a button is bound to: a field edit
/// made at a path (`p.favorite.set(true)`), a verb with its arguments, or an
/// invocation built some other way. No app writes an action id or an
/// argument map.
pub trait Submit<R: Resource>: Sized {
    /// The public id of the action this submits.
    fn action_id(&self) -> &'static str;

    /// The invocation of the host door this submits.
    fn into_invoke(self) -> Result<Invoke<R>, String>;

    /// The binding of a button that submits this when pressed, or `None`
    /// (and a failure in tests) when the resource does not publish it.
    fn control_binding(self, actions: &Actions<R>) -> Option<ActionBinding<()>> {
        let id = self.action_id();
        match self.into_invoke() {
            Ok(invoke) => actions.control_invocation(invoke),
            Err(error) => {
                super::controls::unbound::<R>(&format!("`{id}`"), &error);
                None
            }
        }
    }
}

impl<R: Resource> Submit<R> for Invoke<R> {
    fn action_id(&self) -> &'static str {
        self.id
    }

    fn into_invoke(self) -> Result<Invoke<R>, String> {
        match self.refusal() {
            Some(refusal) => Err(refusal.to_owned()),
            None => Ok(self),
        }
    }
}

impl<R: Resource> Submit<R> for Edit<R> {
    fn action_id(&self) -> &'static str {
        tilo_resource::FIELD_EDIT
    }

    fn into_invoke(self) -> Result<Invoke<R>, String> {
        Invoke::edit(&self).map_err(|error| error.to_string())
    }
}

/// Submits a view's edits. Cloneable; clones share one queue.
///
/// Two doors, one path. [`submit`](Self::submit) and [`apply`](Self::apply)
/// queue an invocation the host resolves after the event, exactly as a
/// control bound to an action would. [`apply_now`](Self::apply_now) applies
/// one typed action immediately, inside the event or the settle pass
/// ([`Widget::settle`](ui_core::widget::Widget::settle)), for an editor that must
/// see the result of its own edit before the next keystroke (the paragraph a
/// split created, the cell a table insert made). Both check the
/// participant's permission, apply through the replayable executor with
/// attribution, and are undone per author.
///
/// # A drag as one undo step
///
/// A slider or a drag handle a surface draws itself applies each value it
/// passes through with [`apply_now`](Self::apply_now), so the document — and
/// every collaborator — follows the drag live. The resource declares that
/// one value continues the one before it ([`Resource::coalesces`]: the same
/// field of the same item), which makes the whole drag one step, and the
/// surface calls [`settle`](Self::settle) when the pointer is let go, so the
/// next drag is a step of its own:
///
/// ```ignore
/// fn coalesces(previous: &Action, next: &Action) -> bool {
///     matches!((previous, next), (Action::SetLevel(..), Action::SetLevel(..)))
/// }
///
/// // In the surface's `handle_event`:
/// WindowEvent::CursorMoved { .. } if self.dragging => {
///     let _ = self.dispatch.apply_now(&mut ctx.edits(), &Action::SetLevel(level));
/// }
/// WindowEvent::MouseInput { state: ElementState::Released, .. } => {
///     self.dragging = false;
///     self.dispatch.settle();
/// }
/// ```
///
/// A toolkit slider bound with `ViewCx::control` instead invokes its action
/// once per drag when built with `Slider::commits_on_release`.
pub struct Dispatcher<R: Resource> {
    /// Everything that does not name the resource's action type, compiled
    /// once for every resource.
    core: DispatchCore,
    /// The invocations of the open group, and how many groups are open.
    group: Rc<RefCell<(usize, Vec<Invoke<R>>)>>,
    /// What applying an action needs: the resource's own
    /// [`Resource::permission`], or for a child its parent's action's.
    permission_of: PermissionOf<R>,
    /// Applies one immediate action: the resource's own, or for a child
    /// resource its parent's action carrying it.
    submit_now: SubmitNow<R>,
    /// Applies a group of the resource's own actions now as one action;
    /// `None` for a dispatcher of a nested or other record.
    group_now: Option<GroupNow<R>>,
    /// The last immediate action and its serial, to tell whether the next
    /// continues it.
    last: Rc<RefCell<Option<Serialed<R>>>>,
}

/// What a dispatcher keeps that does not name the resource's action type
/// ([`DispatchState`]), dropped out of line: a dispatcher is dropped in code
/// generic over its resource, and dropping each of these fields there would
/// compile it into every app.
pub(crate) struct DispatchCore(std::mem::ManuallyDrop<DispatchState>);

impl Drop for DispatchCore {
    #[inline(never)]
    fn drop(&mut self) {
        // SAFETY: the state is dropped here once, as its owner goes, and
        // nothing reads it after.
        unsafe { std::mem::ManuallyDrop::drop(&mut self.0) }
    }
}

impl DispatchCore {
    fn of(state: DispatchState) -> Self {
        Self(std::mem::ManuallyDrop::new(state))
    }
}

impl std::ops::Deref for DispatchCore {
    type Target = DispatchState;

    fn deref(&self) -> &DispatchState {
        &self.0
    }
}

impl std::ops::DerefMut for DispatchCore {
    fn deref_mut(&mut self) -> &mut DispatchState {
        &mut self.0
    }
}

/// What a dispatcher keeps that does not name the resource's action type:
/// who edits, the door's queue, permissions, refusals and the undo-step
/// bookkeeping.
pub(crate) struct DispatchState {
    app_id: &'static str,
    resource_id: Rc<str>,
    /// The route of the record the resource is, as the workspace names its node
    /// (empty for the app's own record of the workspace): an action on an item
    /// of it is decided at that item's node.
    record: Rc<str>,
    /// [`Resource::KIND`] and [`Resource::LABEL`] of the resource.
    kind: &'static str,
    label: &'static str,
    /// For a resource nested in another ([`Dispatcher::child`]), the kind and
    /// label of the record that holds it. Its edits apply as that record's
    /// field edits, so history and the change's claim name that record's
    /// kind: the app's surface describes no other, and every receiver holds
    /// (and the signer refuses) a change claiming the nested kind.
    applied_as: Option<(&'static str, &'static str)>,
    /// The readable name published by the resource host, shared with surfaces.
    resource_label: LocalState<String>,
    /// Who edits through this dispatcher; `None` in a view of a past version.
    me: Option<Rc<str>>,
    /// A dispatcher lent to an admitted effect keeps its original custody.
    /// Clones cannot turn later work into the host participant's invocation.
    /// Share the immutable scope rather than embedding its owner/lease in every
    /// view dispatcher: copying the full scope also inflates construction stacks.
    custody: Option<Rc<ui_core::invocation_scope::ResourceInvocationScope>>,
    /// Each queued invocation with the effect invocation it continues,
    /// when an effect's handler or completion queued it.
    queue: Rc<RefCell<VecDeque<Queued>>>,
    /// Who asks for what is queued now: the person, unless the app submits
    /// it on its own ([`Dispatcher::submit_on_its_own`]).
    asking: Rc<Cell<Origin>>,
    /// The references the views opened ([`Dispatcher::open_reference`]),
    /// on their way through the session's action door.
    pub(crate) opener: super::reference::Opener,
    read_only: LocalState<bool>,
    /// The participant's permissions as the host keeps them, for an action
    /// that needs less than writing (a reply a commenter may add) or more.
    /// Absent outside a host: a past version, which nobody edits, or a
    /// test's detached dispatcher, which may do what writing allows.
    permissions: Rc<RefCell<Option<LivePermissions>>>,
    permission_states: PermissionStates,
    pub(crate) refused: LocalState<Option<Refused>>,
    /// An edit applied now was refused: the views that may have previewed
    /// it are presented the stored state again, as after a refusal at the
    /// door.
    represent: Rc<Cell<bool>>,
    /// The last submission of this view the door applied.
    landed: LocalState<Option<Landed>>,
    /// What the views said they did ([`Dispatcher::say_when_kept`]), not yet
    /// handed to the record to hold for the workspace.
    notices: Rc<RefCell<Vec<String>>>,
    /// The last of them the workspace kept, to say now ([`Dispatcher::said`]).
    pub(crate) said: LocalState<Option<String>>,
    /// What the effects that queued submissions here wait on: how many are
    /// still to land, per effect invocation.
    waits: Rc<RefCell<Waits>>,
    /// Why the record does not read as the resource, while it does not:
    /// nothing is submitted against a state nobody can see.
    unreadable: Rc<RefCell<Option<String>>>,
    host: Rc<RefCell<ui_core::local_dispatch::LocalDispatch>>,
    /// Counts the immediate actions of the resource and its children, so a
    /// dispatcher can tell that nothing came between its last action and
    /// its next.
    serial: Rc<Cell<u64>>,
    /// Every immediate action since the last undo boundary continued the one
    /// before it ([`Resource::coalesces`]): one step, still open.
    continuing: Rc<Cell<bool>>,
    /// An immediate action was applied since the last boundary was taken.
    applied: Rc<Cell<bool>>,
    /// The boundary last taken opened a step that stays open.
    opened: Rc<Cell<bool>>,
    /// The view shows a past version in History, not the live resource.
    past: bool,
    /// The last immediate action may be continued by a later one
    /// ([`Resource::continuable`]).
    continuable: Rc<Cell<bool>>,
    /// The step the open undo step's changes record, decided before each
    /// change commits, so a coalesced step stays one step after a restart.
    gesture: Rc<Cell<Option<tilo_actions::ActionId>>>,
    /// Where the resource's state comes from and where its actions go: the
    /// document the host lends the pass, or the session over the app's one
    /// connection ([`super::Source`]).
    source: super::Source,
}

impl Clone for DispatchCore {
    /// Out of line: a derived clone is inlined into every dispatcher's clone, which each app
    /// compiles for its resource.
    #[inline(never)]
    fn clone(&self) -> Self {
        Self(std::mem::ManuallyDrop::new(DispatchState {
            app_id: self.app_id,
            resource_id: self.resource_id.clone(),
            record: self.record.clone(),
            kind: self.kind,
            label: self.label,
            applied_as: self.applied_as,
            resource_label: self.resource_label.clone(),
            me: self.me.clone(),
            custody: self.custody.clone(),
            queue: self.queue.clone(),
            asking: self.asking.clone(),
            opener: self.opener.clone(),
            read_only: self.read_only.clone(),
            permissions: self.permissions.clone(),
            permission_states: self.permission_states.clone(),
            refused: self.refused.clone(),
            represent: self.represent.clone(),
            landed: self.landed.clone(),
            notices: self.notices.clone(),
            said: self.said.clone(),
            waits: self.waits.clone(),
            unreadable: self.unreadable.clone(),
            host: self.host.clone(),
            serial: self.serial.clone(),
            continuing: self.continuing.clone(),
            applied: self.applied.clone(),
            opened: self.opened.clone(),
            past: self.past,
            continuable: self.continuable.clone(),
            gesture: self.gesture.clone(),
            source: self.source.clone(),
        }))
    }
}

/// What applying one action needs.
type PermissionOf<R> = Rc<dyn Fn(&<R as Resource>::Action) -> ActionNeed>;

/// One observable per requested permission, shared by this resource's views.
type PermissionStates = Rc<RefCell<Vec<(Asked, LocalState<bool>)>>>;

/// An immediate action and the serial it was applied at.
type Serialed<R> = (u64, <R as Resource>::Action);

/// Applies a group of the resource's actions now, as one action.
type GroupNow<R> = Rc<
    dyn Fn(
        &mut ui_core::local_dispatch::LocalDispatch,
        &mut Edits<'_>,
        &tilo_resource::ActionGroup<<R as Resource>::Action>,
        ActionContext,
    ) -> Result<(), ActionError>,
>;

/// Applies one typed action to the document a pass may change, through
/// the host.
type SubmitNow<R> = Rc<
    dyn Fn(
        &mut ui_core::local_dispatch::LocalDispatch,
        &mut Edits<'_>,
        &<R as Resource>::Action,
        ActionContext,
    ) -> Result<(), ActionError>,
>;

impl<R: Resource> Clone for Dispatcher<R> {
    fn clone(&self) -> Self {
        Self {
            core: self.core.clone(),
            group: Rc::clone(&self.group),
            permission_of: Rc::clone(&self.permission_of),
            submit_now: Rc::clone(&self.submit_now),
            group_now: self.group_now.clone(),
            last: Rc::clone(&self.last),
        }
    }
}

impl DispatchCore {
    fn new(
        app_id: &'static str,
        resource_id: &str,
        (kind, label): (&'static str, &'static str),
        read_only: bool,
        me: Option<&str>,
    ) -> Self {
        Self(std::mem::ManuallyDrop::new(DispatchState {
            app_id,
            resource_id: Rc::from(resource_id),
            record: Rc::from(""),
            kind,
            label,
            resource_label: LocalState::new(label.to_owned()),
            me: me.map(Rc::from),
            custody: None,
            queue: Rc::default(),
            asking: Rc::default(),
            opener: super::reference::Opener::default(),
            read_only: LocalState::new(read_only),
            permissions: Rc::default(),
            permission_states: Rc::default(),
            refused: LocalState::new(None),
            represent: Rc::default(),
            landed: LocalState::new(None),
            notices: Rc::default(),
            said: LocalState::new(None),
            waits: Rc::default(),
            unreadable: Rc::default(),
            host: Rc::default(),
            serial: Rc::default(),
            continuing: Rc::default(),
            applied: Rc::default(),
            opened: Rc::default(),
            past: false,
            continuable: Rc::default(),
            gesture: Rc::default(),
            source: super::Source::Document,
            applied_as: None,
        }))
    }

    /// The core of the dispatcher of another record than this resource's,
    /// published at `id` ([`Dispatcher::for_record`]).
    fn for_record(
        &self,
        id: &str,
        (kind, label): (&'static str, &'static str),
        read_only: bool,
    ) -> Self {
        Self::of(DispatchState {
            app_id: self.app_id,
            me: self.me.clone(),
            custody: self.custody.clone(),
            resource_id: Rc::from(id),
            record: Rc::from(""),
            kind,
            label,
            resource_label: LocalState::new(label.to_owned()),
            queue: Rc::clone(&self.queue),
            asking: Rc::clone(&self.asking),
            opener: self.opener.clone(),
            read_only: LocalState::new(read_only || self.past),
            permissions: Rc::default(),
            permission_states: Rc::default(),
            refused: self.refused.clone(),
            represent: self.represent.clone(),
            landed: self.landed.clone(),
            notices: Rc::clone(&self.notices),
            said: self.said.clone(),
            waits: Rc::clone(&self.waits),
            unreadable: Rc::default(),
            host: Rc::clone(&self.host),
            serial: Rc::default(),
            continuing: Rc::default(),
            applied: Rc::default(),
            opened: Rc::default(),
            past: self.past,
            continuable: Rc::default(),
            gesture: Rc::default(),
            // Another record of an app in this process is the app's own,
            // kept here: only the source of this one may be the session's.
            source: super::Source::Document,
            applied_as: None,
        })
    }

    /// The core of the dispatcher of a resource nested in this one at `id`
    /// ([`Dispatcher::child`]): it shares this one's permissions and undo
    /// steps.
    fn child(&self, id: &str, (kind, label): (&'static str, &'static str)) -> Self {
        let mut child = self.clone();
        child.resource_id = Rc::from(id);
        child.kind = kind;
        child.label = label;
        child.applied_as = self.applied_as.or(Some((self.kind, self.label)));
        child.resource_label = LocalState::new(label.to_owned());
        child
    }

    fn queue_invocation(
        &self,
        address: ActionAddress,
        arguments: serde_json::Map<String, serde_json::Value>,
    ) {
        let on_behalf_of = match &self.custody {
            Some(custody) => {
                if let Err(error) = custody.check() {
                    self.refuse(&address.action, error);
                    return;
                }
                Some(custody.invocation())
            }
            None => super::effect::acting_for(),
        };
        if let Some(invocation) = on_behalf_of {
            self.waits.borrow_mut().submitted(invocation);
        }
        self.queue.borrow_mut().push_back((
            (ControlInvocation { address, arguments }, on_behalf_of),
            self.asking.get(),
        ));
    }

    /// Whether the session keeps this resource's record, so submissions go
    /// over the app's connection rather than into a document the host lent
    /// ([`super::Source::Connection`]).
    fn submits_over_connection(&self) -> bool {
        self.source.is_connection()
    }

    /// Submit a control the app's view pressed, over the connection that
    /// keeps the record, as the person's gesture (`one-app-model.md` §4).
    pub(crate) fn submit_view_control(
        &self,
        address: &ActionAddress,
        arguments: serde_json::Map<String, serde_json::Value>,
    ) {
        self.submit_remote(address, arguments, true);
    }

    /// Submit `address` with `arguments` over the connection, as the person's
    /// gesture when `in_person`; the refusal is told in
    /// [`Self::refuse`] as an edit applied now is.
    fn submit_remote(
        &self,
        address: &ActionAddress,
        arguments: serde_json::Map<String, serde_json::Value>,
        in_person: bool,
    ) {
        let ask = super::Ask::new(
            address.resource.clone(),
            address.action.clone(),
            arguments,
            in_person,
        );
        match self
            .source
            .submit(&ask)
            .unwrap_or_else(|| Err("this resource is kept here; it has no connection".to_owned()))
        {
            Ok(()) => {}
            Err(reason) => self.refuse(&address.action, reason),
        }
    }

    pub(crate) fn note_continuation(
        &self,
        invocation: tilo_actions::InvocationId,
        action: &str,
        result: &Result<ui_core::host_operation::ResourceOperationStart, tilo_actions::DoorError>,
    ) {
        let landed = match result {
            Ok(ui_core::host_operation::ResourceOperationStart::Completed(output)) => {
                Ok(Landed::of(action, output))
            }
            // Handed on to the broker: it applies there, answering nothing here.
            Ok(ui_core::host_operation::ResourceOperationStart::Accepted) => Ok(Landed {
                action: action.to_owned(),
                answer: None,
                created: Vec::new(),
            }),
            Err(error) => Err(error.to_string()),
        };
        self.waits.borrow_mut().landed(invocation, landed);
    }

    /// This core, lent to an admitted effect under `custody`.
    #[inline(never)]
    fn for_custody(&self, custody: ui_core::invocation_scope::ResourceInvocationScope) -> Self {
        let mut core = self.clone();
        core.custody = Some(Rc::new(custody));
        core
    }

    fn past(&mut self) {
        self.past = true;
        self.read_only.set(true);
        self.permission_states = Rc::default();
    }

    pub(crate) fn follow(&self, permissions: LivePermissions) {
        *self.permissions.borrow_mut() = Some(permissions);
        self.refresh_permission_states();
    }

    fn asked_state(&self, asked: Asked) -> LocalState<bool> {
        let mut states = self.permission_states.borrow_mut();
        if let Some((_, state)) = states.iter().find(|(held, _)| *held == asked) {
            return state.clone();
        }
        let state = LocalState::new(self.may_asked(&asked));
        states.push((asked, state.clone()));
        state
    }

    pub(crate) fn refresh_permission_states(&self) {
        for (asked, state) in self.permission_states.borrow().iter() {
            let allowed = self.may_asked(asked);
            if state.get() != allowed {
                state.set(allowed);
            }
        }
    }

    fn may_asked(&self, asked: &Asked) -> bool {
        match asked {
            Asked::Need(need) => self.may(need),
            Asked::Govern => self.may_govern(),
            Asked::Arrived => !ui_core::workspace_sync::before_first_sync(),
        }
    }

    fn may(&self, need: &ActionNeed) -> bool {
        let mut node = self.node();
        if let Some(field) = &need.field {
            node = node.field(field);
        }
        self.may_scope(&PermissionScope::Action {
            node,
            kind: need.kind,
        })
    }

    /// The node below the workspace where the workspace decides this resource's
    /// changes, as far as a decision here can name it: an item of the
    /// record for a resource nested in one at `<kind>/<field>/<item>` (a
    /// note's body), so what the workspace grants on that item alone (an item
    /// shared to edit) lets it be changed here too; else the app's.
    fn node(&self) -> TreePath {
        let app = TreePath::root().app(self.app_id);
        if self.applied_as.is_none() {
            return app;
        }
        match self
            .resource_id
            .rsplit_once('/')
            .and_then(|(collection, item)| Some((collection.split_once('/')?, item)))
        {
            Some(((kind, field), item))
                if !kind.is_empty()
                    && !field.is_empty()
                    && !field.contains('/')
                    && !item.is_empty() =>
            {
                app.kind(kind).resource(&*self.record).item(item)
            }
            _ => app,
        }
    }

    /// Whether the participant may react here: never in a past version,
    /// else as the workspace grants reactions, which the Commenter role does as
    /// it grants comments.
    pub(crate) fn may_react(&self) -> bool {
        !self.past && self.may(&reaction_need())
    }

    /// Whether the participant may read what this window holds: one who may
    /// not is found nothing of it.
    pub(crate) fn may_read(&self) -> bool {
        self.may(&ActionNeed::of(ActionKind::Read))
    }

    /// Whether the workspace this record is in has anyone besides this window's
    /// participant, its owner or a member, here now or not: what it holds is
    /// shared with them.
    pub(crate) fn workspace_has_others(&self) -> bool {
        self.permissions
            .borrow()
            .as_ref()
            .is_some_and(ui_core::permissions::LivePermissions::workspace_has_others)
    }

    /// React (or take a reaction back) at `path`, a [`Reactions`](tilo_resource::Reactions)
    /// field of the resource, as the person this window is for: the field
    /// edit `op` through the door, as [`Dispatcher::submit`] submits one,
    /// for code that does not know the resource's type (the window's bar).
    pub(crate) fn submit_reaction(
        &self,
        path: Vec<tilo_resource::Segment>,
        op: tilo_resource::EditOp,
    ) {
        let id = tilo_resource::FIELD_EDIT;
        if self.refusal(id, false) {
            return;
        }
        if !self.may_react() {
            self.refuse(id, self.not_allowed(&reaction_need()));
            return;
        }
        let edit = Edit::<()>::new(path, op);
        match tilo_resource::__private::json_via_bytes(&edit) {
            Ok(edit) => self.queue_invocation(
                ActionAddress::new(self.resource_id.as_ref(), id),
                serde_json::Map::from_iter([(tilo_resource::EDIT_PARAM.to_owned(), edit)]),
            ),
            Err(error) => self.refuse(id, error.to_string()),
        }
    }

    fn may_govern(&self) -> bool {
        self.may_scope(&PermissionScope::governance(
            policy::roles::governance::SETTINGS,
        ))
    }

    /// Whether the participant may invite people to the workspace.
    pub(crate) fn may_invite(&self) -> bool {
        self.may_scope(&PermissionScope::governance(
            policy::roles::governance::INVITE,
        ))
    }

    fn may_scope(&self, scope: &PermissionScope) -> bool {
        match self.permissions.borrow().as_ref() {
            Some(permissions) => permissions.check(scope),
            // A detached dispatcher may what writing allows; a past version
            // nothing.
            None => !self.read_only.get(),
        }
    }

    #[cfg(any(test, feature = "test-support"))]
    fn refresh_read_only(&self) -> bool {
        let writes = self.permissions.borrow().as_ref().map(|permissions| {
            permissions.check(&PermissionScope::app(self.app_id, ActionKind::Undoable))
        });
        match writes {
            Some(writes) => self.set_read_only(!writes),
            None => false,
        }
    }

    pub(crate) fn set_read_only(&self, read_only: bool) -> bool {
        if self.read_only.get() == read_only {
            return false;
        }
        self.read_only.set(read_only);
        true
    }

    fn view_only(&self) -> String {
        format!("this {} is open to view only", self.label.to_lowercase())
    }

    /// Why an edit that is `need` was refused.
    fn not_allowed(&self, need: &ActionNeed) -> String {
        match (&need.field, need.kind) {
            (Some(field), _) if field == policy::roles::COMMENTS_FIELD => {
                format!("you may not comment on this {}", self.label.to_lowercase())
            }
            (Some(field), _) if field == policy::roles::REACTIONS_FIELD => {
                format!("you may not react to this {}", self.label.to_lowercase())
            }
            (None, ActionKind::Undoable) => self.view_only(),
            _ => format!("you may not do this to this {}", self.label.to_lowercase()),
        }
    }

    /// Why nothing can be submitted now, when the record is unreadable.
    fn unreadable(&self) -> Option<String> {
        self.unreadable.borrow().clone()
    }

    pub(crate) fn refuse(&self, action: &str, reason: String) {
        self.refused.set(Some(Refused {
            action: action.to_owned(),
            item: None,
            reason,
            by_workspace: false,
        }));
    }

    /// What the views said they did since last asked, for the record to
    /// hold until the workspace keeps it.
    pub(crate) fn take_notices(&self) -> Vec<String> {
        std::mem::take(&mut *self.notices.borrow_mut())
    }

    /// The workspace kept what `text` says was done.
    pub(crate) fn kept(&self, text: &str) {
        self.said.set(Some(text.to_owned()));
    }

    /// The workspace refused what `refusal` names after this device applied it;
    /// the record withdrew it.
    pub(crate) fn refuse_by_workspace(&self, refusal: &ui_core::record::RecordRefusal) {
        self.refused.set(Some(Refused {
            action: refusal.action.clone(),
            item: refusal.item.clone(),
            reason: refusal.reason.clone(),
            by_workspace: true,
        }));
    }

    /// Why an invocation `id` submitted now is refused before its
    /// permission is asked: the record is unreadable (unless it is an
    /// effect) or the effect lending this dispatcher lost its custody.
    fn refusal(&self, id: &str, effect: bool) -> bool {
        if let Some(reason) = self.unreadable()
            && !effect
        {
            self.refuse(id, reason);
            return true;
        }
        if let Some(custody) = &self.custody
            && let Err(error) = custody.check()
        {
            self.refuse(id, error);
            return true;
        }
        false
    }

    /// Why nothing is applied now: an effect's dispatcher submits through
    /// the queue, and an unreadable record takes nothing.
    fn applies_now(&self) -> Result<(), ActionError> {
        if self.custody.is_some() {
            return Err(ActionError::Refused(
                "caller-scoped effects submit document changes through queued actions".into(),
            ));
        }
        if let Some(reason) = self.unreadable() {
            return Err(ActionError::Refused(reason));
        }
        Ok(())
    }

    /// The context of an action of this resource, attributed to whoever the
    /// edit is applied for, and owned by this dispatcher's app. Without the
    /// app, the executor guessed one from the action type (`org.tilo.Chat` of
    /// `chat.workspace`), and every receiver checking the change against the
    /// record's app refused it as a verb that app does not publish.
    fn context(&self) -> ActionContext {
        let context = self.resource_context();
        if self.app_id.is_empty() {
            context
        } else {
            context.with_app(self.app_id, self.label)
        }
    }

    fn resource_context(&self) -> ActionContext {
        match self.applied_as {
            // As `ActionSpec::history_context` names an action a nested
            // resource re-encodes: the enclosing kind, the nested resource
            // kept as a facet.
            Some((kind, label)) => {
                let mut context =
                    ActionContext::for_resource(self.resource_id.as_ref(), kind, label);
                context.facets.push(tilo_actions::ActionFacet::new(
                    tilo_actions::NESTED_RESOURCE_FACET,
                    self.resource_label.get(),
                ));
                context
            }
            None => ActionContext::for_resource(
                self.resource_id.as_ref(),
                self.kind,
                self.resource_label.get(),
            ),
        }
    }

    /// `context` named for this resource and its editor, in the step it
    /// opens or `continues` when it is a `step`.
    fn step_context(&self, context: ActionContext, step: bool, continues: bool) -> ActionContext {
        // History names the resource and who edited it even when the
        // surface's context does not: whoever the edit is applied for (an
        // agent at its own caret, a collaborator a scenario stages), else
        // this window's person.
        let mut named = self.context();
        if let Some(invoker) = ui_core::invocation_scope::current_invoker()
            .or_else(|| self.me.as_ref().map(|me| ActionInvoker::actor(me.as_ref())))
        {
            named = named.with_invoker(invoker);
        }
        let mut context = context.enriched_by(&named);
        // An action that continues the open step joins it; any other opens
        // its own.
        if step {
            let gesture = self.gesture.get().filter(|_| continues).unwrap_or_default();
            self.gesture.set(Some(gesture));
            context = context.in_gesture(Some(gesture));
        }
        context
    }

    /// Note an immediate action that is a step and was applied: whether it
    /// `continues` the open one and is `continuable` itself. Its serial.
    fn stepped(&self, continues: bool, continuable: bool) -> u64 {
        let serial = self.serial.get().wrapping_add(1);
        self.serial.set(serial);
        self.continuable.set(continuable);
        // The event continues the open step only if every action it applied
        // did.
        let first_of_event = !self.applied.replace(true);
        self.continuing
            .set(continues && (first_of_event || self.continuing.get()));
        serial
    }

    /// Note a group applied now: a step of its own, which nothing
    /// continues.
    fn grouped(&self) {
        self.serial.set(self.serial.get().wrapping_add(1));
        self.applied.set(true);
        self.continuing.set(false);
    }

    pub(crate) fn take_committed(&self) -> Option<Vec<ChangeHash>> {
        let bracket = self.host.borrow_mut().take_committed();
        let continuing = self.continuing.replace(false);
        self.opened
            .set(bracket.is_some() && !continuing && self.continuable.get());
        self.applied.set(false);
        if continuing { None } else { bracket }
    }
}

/// What a root reads and drives of its dispatcher, without its type.
impl DispatchCore {
    /// Who edits through this dispatcher; `None` in a view of a past version.
    pub(crate) fn me(&self) -> Option<&str> {
        self.me.as_deref()
    }

    /// Whether it is a view of a past version.
    pub(crate) fn is_past(&self) -> bool {
        self.past
    }

    pub(crate) fn note_landed(&self, action: &str, output: &tilo_actions::ActionOutput) {
        self.landed.set(Some(Landed::of(action, output)));
    }

    /// Say why the record does not read as the resource (`None` once it
    /// does again); until then every submission is refused with it.
    pub(crate) fn set_unreadable(&self, reason: Option<String>) {
        *self.unreadable.borrow_mut() = reason;
    }

    /// The next queued invocation, with the effect invocation it continues.
    /// The host draining it hears who asked for it.
    pub(crate) fn take_attributed(&self) -> Option<AttributedControlInvocation> {
        let (taken, origin) = self.queue.borrow_mut().pop_front()?;
        ui_core::widget::controls::note_drained_origin(origin);
        Some(taken)
    }

    pub(crate) fn has_pending(&self) -> bool {
        !self.queue.borrow().is_empty()
    }

    /// Whether an edit applied now was refused since the last call, so the
    /// views are to be presented the stored state again.
    pub(crate) fn take_represent(&self) -> bool {
        self.represent.replace(false)
    }

    /// The step the last boundary opened stays open for the actions that
    /// continue it ([`Resource::coalesces`]).
    pub(crate) fn keeps_step_open(&self) -> bool {
        self.opened.get()
    }

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

    pub(crate) fn app_id(&self) -> &'static str {
        self.app_id
    }

    /// Where this dispatcher's resource's state comes from and where its
    /// edits go ([`super::Source`]).
    pub(crate) fn source(&self) -> &super::Source {
        &self.source
    }
}

impl<R: Resource> Dispatcher<R> {
    /// What does not name the resource type.
    pub(crate) fn core(&self) -> &DispatchCore {
        &self.core
    }

    pub(crate) fn for_custody(
        &self,
        custody: ui_core::invocation_scope::ResourceInvocationScope,
    ) -> Self {
        Self {
            core: self.core.for_custody(custody),
            // An effect's group cannot absorb the person's unrelated input.
            group: Rc::default(),
            permission_of: Rc::clone(&self.permission_of),
            submit_now: Rc::clone(&self.submit_now),
            group_now: self.group_now.clone(),
            last: Rc::clone(&self.last),
        }
    }

    /// What the effect `invocation` submitted here, once it all landed: the
    /// last submission's [`Landed`], or why one was refused. Nothing arrives
    /// when it submitted nothing.
    pub(crate) fn wait_landed(
        &self,
        invocation: tilo_actions::InvocationId,
    ) -> Option<std::sync::mpsc::Receiver<Result<Landed, String>>> {
        self.core.waits.borrow_mut().wait(invocation)
    }

    pub(crate) fn new(
        app_id: &'static str,
        resource_id: &str,
        read_only: bool,
        me: Option<&str>,
    ) -> Self {
        Self {
            core: DispatchCore::new(app_id, resource_id, (R::KIND, R::LABEL), read_only, me),
            group: Rc::default(),
            permission_of: Rc::new(tilo_resource::need_of::<R>),
            submit_now: Rc::new(|host, edits, action, context| {
                edits.apply(host, R::ACTION_TYPE, action, context)
            }),
            group_now: Some(Rc::new(|host, edits, group, context| {
                edits.apply(
                    host,
                    &tilo_resource::group::group_type::<R>(),
                    group,
                    context,
                )
            })),
            last: Rc::default(),
        }
    }

    /// A dispatcher for a surface a test builds outside any host, editing as
    /// `me`: what the surface applies now ([`Self::apply_now`]) goes into the
    /// document the test hands it, as under a host. Queued edits
    /// ([`Self::apply`], [`Self::submit`]) wait for a host that never takes
    /// them; a test that needs those runs the app
    /// ([`TestApp`](super::testing::HeadlessApp)).
    #[cfg(any(test, feature = "test-support"))]
    #[must_use]
    pub fn detached(app_id: &'static str, me: &str) -> Self {
        Self::new(app_id, R::KIND, false, Some(me))
    }

    /// What a [`detached`](Self::detached) dispatcher handed to the door
    /// and nothing took yet — a destructive verb or a removal waiting for
    /// the person's confirmation — as the actions the door would apply once
    /// they agreed. Taking them empties the queue.
    #[cfg(any(test, feature = "test-support"))]
    pub fn take_asked(&self) -> Result<Vec<R::Action>, String> {
        self.core
            .queue
            .borrow_mut()
            .drain(..)
            .map(|((invocation, _), _)| {
                tilo_resource::build_action::<R>(
                    &invocation.address.action,
                    &invocation.arguments,
                    tilo_resource::origin_now_ms(),
                )
            })
            .collect()
    }

    /// Who edits through this dispatcher: the participant this view is
    /// for, the same id an action they invoke reads as its author
    /// ([`ActionCx::author`](tilo_resource::ActionCx::author)). `None` in a
    /// view of a past version, which nobody edits.
    pub fn me(&self) -> Option<&str> {
        self.core.me.as_deref()
    }

    /// A dispatcher for a past version in History: nothing it is given is
    /// ever applied.
    pub(crate) fn past(mut self) -> Self {
        self.core.past();
        self
    }

    /// The dispatcher of the record the workspace names by `route` (empty for
    /// the app's own record of the workspace).
    pub(crate) fn on_record(mut self, route: &str) -> Self {
        self.core.record = Rc::from(route);
        self
    }

    /// Submissions go over `source`, the session's document host, rather
    /// than into the document a host lends the pass
    /// ([`super::Source::Connection`]).
    pub(crate) fn over_source(mut self, source: super::Source) -> Self {
        self.core.source = source;
        self
    }

    /// Whether the view shows a past version in History mode, drawn from a
    /// frozen document. Such a view must start no work: no worker, no
    /// network, no files. A surface that would fetch or watch something
    /// presents what the document holds instead.
    pub fn is_past(&self) -> bool {
        self.core.past
    }

    /// Whether edits from this participant will be refused, as of now: it
    /// follows role changes while the app runs. Surfaces use it to present
    /// themselves read-only instead of letting an edit bounce.
    pub fn read_only(&self) -> bool {
        self.core.read_only.get()
    }

    /// [`Self::read_only`] as observable state, for a widget that shows or
    /// disables something while the participant may only view.
    pub fn read_only_state(&self) -> LocalState<bool> {
        self.core.read_only.clone()
    }

    /// Whether the host currently allows what `need` is, as observable view
    /// state. It follows changes even when writing remains allowed and the
    /// resource document does not change. Bind it to a conditional pane or
    /// label; action invocation still checks the host's current authority.
    pub fn permission_state(&self, need: ActionNeed) -> LocalState<bool> {
        self.core.asked_state(Asked::Need(need))
    }

    /// The participant's standing in the workspace as the host keeps it when
    /// called: who they are, the workspace's policy and what bounds them. For a
    /// runtime that decides its own invocations (a tilolang program's) by
    /// the policy the door decides by. `None` outside a host.
    pub fn standing_source(&self) -> impl Fn() -> Option<policy::Standing> + 'static {
        let permissions = Rc::clone(&self.core.permissions);
        move || {
            permissions
                .borrow()
                .as_ref()
                .map(|live| live.current().standing().clone())
        }
    }

    /// Whether the participant may govern the workspace (invite, grant, change
    /// its settings), as observable view state: for an owner's pane.
    pub fn govern_state(&self) -> LocalState<bool> {
        self.core.asked_state(Asked::Govern)
    }

    /// Whether what the workspace holds has arrived, as observable view state:
    /// false while the window's workspace has not finished its first sync with
    /// its host ([`ui_core::workspace_sync`]), when a record joined from it may
    /// still be missing the content its creator wrote. True outside a workspace
    /// that syncs with a host, and for a host's own view of a record, which
    /// holds what the workspace holds.
    pub fn arrived_state(&self) -> LocalState<bool> {
        self.core.asked_state(Asked::Arrived)
    }

    /// The same dispatcher deciding by `permissions`, for a test of a
    /// surface whose participant may only comment, or only view.
    #[cfg(any(test, feature = "test-support"))]
    #[must_use]
    pub fn with_permissions(self, permissions: LivePermissions) -> Self {
        self.core.follow(permissions);
        self.core.refresh_read_only();
        self
    }

    /// Whether the participant may, as of now, do what `need` is: an
    /// undoable change for most edits, one of the comments for a reply.
    pub fn may(&self, need: &ActionNeed) -> bool {
        self.core.may(need)
    }

    /// Whether the participant may, as of now, change the workspace's settings.
    pub fn may_govern(&self) -> bool {
        self.core.may_govern()
    }

    /// Whether the record is shared: someone else belongs to its workspace, or
    /// is in it with `people` now. Where it is, reactions are offered.
    pub fn is_shared(&self, people: &super::People) -> bool {
        self.core.workspace_has_others() || people.others_here()
    }

    /// Whether the participant may apply `action`
    /// ([`tilo_resource::need_of`]).
    pub fn may_apply(&self, action: &R::Action) -> bool {
        self.core.may(&(self.permission_of)(action))
    }

    /// The last edit or effect submitted here that was refused — denied
    /// permission, unavailable, failed — and why, for a view to show. An
    /// edit waiting for the user's confirmation is not refused.
    pub fn refused(&self) -> LocalState<Option<Refused>> {
        self.core.refused.clone()
    }

    /// The last submission of this view the door applied, with what it
    /// answered: the ids a "new" verb minted ([`Landed::minted`]), for a
    /// surface that opens what it just created.
    pub fn landed(&self) -> LocalState<Option<Landed>> {
        self.core.landed.clone()
    }

    /// Say `text` of what was just submitted here ("Added Buy milk") once
    /// it is kept: at once in a record nobody else decides, once the workspace
    /// accepts the change in a shared one, and never when the workspace refuses
    /// it ([`Self::refused`] says why instead). The text shows through
    /// [`Self::said`].
    pub fn say_when_kept(&self, text: impl Into<String>) {
        self.core.notices.borrow_mut().push(text.into());
    }

    /// What [`Self::say_when_kept`] said that was kept, for the view to
    /// show and then clear.
    pub fn said(&self) -> LocalState<Option<String>> {
        self.core.said.clone()
    }

    /// Why `action` may not be applied by this participant.
    fn not_allowed(&self, action: &R::Action) -> ActionError {
        ActionError::Refused(self.core.not_allowed(&(self.permission_of)(action)))
    }

    /// Invoke one of the app's effects (`dispatcher.effect(&Backups::BackUp)`)
    /// through the same door as a button bound to it: permission, the
    /// effect's availability and a destructive effect's confirmation are
    /// checked, then its handler runs. A participant who may only view still
    /// invokes the effects declared `kind = "read"`.
    pub fn effect<E: Effect>(&self, effect: &E) {
        self.core.queue_invocation(
            ActionAddress::new(self.core.resource_id.as_ref(), effect.id()),
            effect.arguments(),
        );
    }

    /// Whether the person at this device may do `effect` at once, as their
    /// own gesture on the surface: a shortcut, a pointer gesture, a row of
    /// the surface's own menu, whose arguments the gesture itself supplied
    /// (the clipboard they paste). Like a keystroke, such a gesture is its
    /// own confirmation, so a surface told `true` performs the effect
    /// itself. The confirmation a destructive declaration asks for stays
    /// with the callers who supply its arguments — the palette, a script,
    /// an agent — because automation is the same door: under any
    /// invocation (an invoked action, an effect's handler or completion, a
    /// dispatcher lent to one) this is `false`, and the surface submits
    /// the effect ([`Self::effect`]) for the host to check and confirm as
    /// for any caller. So it is in a past version, and when the
    /// participant's role does not grant what the declaration needs.
    pub fn is_own_gesture<E: Effect>(&self, effect: &E) -> bool {
        if !self.gesture_is_own() {
            return false;
        }
        let id = effect.id();
        E::declarations()
            .iter()
            .find(|decl| decl.id == id)
            .is_some_and(|decl| {
                self.may(&ActionNeed {
                    kind: decl.action_kind,
                    field: None,
                    privileged: false,
                })
            })
    }

    /// Whether what runs now is the person's own gesture at this device,
    /// not automation: no invocation, effect, custody or past version is
    /// acting.
    fn gesture_is_own(&self) -> bool {
        !(self.core.past
            || self.core.custody.is_some()
            || super::effect::acting_for().is_some()
            || ui_core::invocation_scope::current_invoker().is_some())
    }

    /// Invoke `effect` as the live row `row` offers it
    /// ([`LiveRow::effect`](super::LiveRow::effect)): under the row's
    /// contract, so a confirmation the row asks for (typing the name of the
    /// device it erases) is asked here too.
    pub fn effect_on<E: Effect>(&self, row: &str, effect: &E) {
        self.core
            .queue_invocation(ActionAddress::new(row, effect.id()), serde_json::Map::new());
    }

    /// Submit a field edit (`dispatcher.submit(p.favorite.set(true))`) or a
    /// verb (`dispatcher.submit(Snippets::DELETE.with(id))`) through the
    /// door, after the event, as a control bound to it would.
    ///
    /// An effect's invocation ([`Invoke::effect`]) reaches its handler as
    /// [`Self::effect`] does.
    pub fn submit(&self, submit: impl Submit<R>) {
        let id = submit.action_id();
        match submit.into_invoke() {
            Ok(invoke) => self.submit_invoke(invoke),
            Err(error) => {
                super::controls::unbound::<R>(&format!("`{id}`"), &error);
                self.core.refuse(id, error);
            }
        }
    }

    /// [`submit`](Self::submit) what the app does on its own, for nobody's
    /// gesture: a read receipt, keeping a record in step with what is shown.
    /// It goes through the same door and permissions; a refusal is told in
    /// [`Self::refused`] and logged, but never said over the window as if
    /// the person had pressed something and been refused.
    pub fn submit_on_its_own(&self, submit: impl Submit<R>) {
        let before = self.core.asking.replace(Origin::App);
        self.submit(submit);
        self.core.asking.set(before);
    }

    fn submit_invoke(&self, invoke: Invoke<R>) {
        if self.core.refusal(invoke.id, invoke.is_effect()) {
            return;
        }
        if invoke.is_effect() {
            self.queue(invoke);
            return;
        }
        if !self.may_invoke(&invoke) {
            self.core.refuse(invoke.id, self.core.view_only());
            return;
        }
        {
            let mut group = self.group.borrow_mut();
            if group.0 > 0 {
                group.1.push(invoke);
                return;
            }
        }
        self.queue(invoke);
    }

    fn queue(&self, invoke: Invoke<R>) {
        if self.core.submits_over_connection() {
            // The session keeps the record: the action is the person's
            // gesture at this view, admitted and committed by its door
            // (`one-app-model.md` §4).
            self.core.submit_remote(
                &ActionAddress::new(self.core.resource_id.as_ref(), invoke.id),
                invoke.arguments,
                true,
            );
            return;
        }
        self.core.queue_invocation(
            ActionAddress::new(self.core.resource_id.as_ref(), invoke.id),
            invoke.arguments,
        );
    }

    /// Whether the participant may take `invoke`: what its declaration, or
    /// the typed value it applies, needs. One this resource does not declare
    /// (an edit bound to a surface's view state) is left to the host, which
    /// checks what its published action needs. A surface asks before work
    /// that only feeds a write (an index it would keep with a row), so a
    /// participant who may not make the write is not sent it.
    pub fn may_invoke(&self, invoke: &Invoke<R>) -> bool {
        // A reaction is decided where the workspace places it, below the
        // reactions field, as the door decides it: someone who may only
        // comment may react too.
        if invoke.id == tilo_resource::FIELD_EDIT && reacts(&invoke.arguments) {
            return self.core.may_react();
        }
        if invoke.id == tilo_resource::APPLY || invoke.id == tilo_resource::FIELD_EDIT {
            return match invoke.build(0) {
                Ok(action) => self.may_apply(&action),
                Err(error) => {
                    // What the invocation applies cannot be read here, so the
                    // door decides what its published action needs.
                    tracing::warn!(%error, action = %invoke.id, "an invocation's typed value could not be built; the door decides");
                    !self.read_only()
                }
            };
        }
        may_declared(
            &self.core,
            &tilo_resource::vocabulary::<R>().declarations(),
            invoke.id,
            invoke.is_group(),
        )
    }

    /// Open the platform search with `request`, narrowed to this app or one
    /// part of it (`SearchRequest::within`). Searching is a view, so a
    /// participant who may only view can search too.
    pub fn open_search(&self, request: &ui_core::search::SearchRequest) {
        self.core.queue.borrow_mut().push_back((
            (
                ui_core::search::open_search_invocation(request),
                super::effect::acting_for(),
            ),
            Origin::Person,
        ));
    }

    /// Ask for the link to `resource` (this resource or one nested in it,
    /// such as an item) as a control bound to its `share-link` would: the
    /// framework copies it to the clipboard and reports it in
    /// [`Self::landed`], or why there is none in [`Self::refused`]. A link
    /// grants nothing, so a participant who may only view asks too.
    pub fn share_link(&self, resource: &str) {
        self.core.queue_invocation(
            ActionAddress::new(resource, tilo_resource::share::SHARE_LINK),
            serde_json::Map::new(),
        );
    }

    /// The client of the session's action door the views' opens and
    /// reads go through.
    pub(crate) fn opener(&self) -> &super::reference::Opener {
        &self.core.opener
    }

    /// Open what `href`, a `tilo://open#…` address a link in this view's
    /// text carries, names: the app that keeps that resource shows it,
    /// started first when no window does.
    pub fn open_link(&self, href: &str) -> Result<(), String> {
        super::reference::open_link(&self.core.opener, href)
    }

    /// Open `reference`, which `app` keeps in its `record` (`None`: the
    /// app's own record of the workspace), where it lives: its app opens at
    /// it, launched first when no window shows it. The open is an action
    /// like any other, admitted as the person under their grants; a refusal
    /// is told in [`Self::refused`] as `open`.
    pub fn open_reference(
        &self,
        app: &str,
        record: Option<&str>,
        reference: &tilo_reference::ResourceRef,
    ) {
        if let Err(reason) = self.core.opener.open(app, record, reference) {
            self.core.refuse(super::reference::OPEN, reason);
        }
    }

    /// Send `invoke`, an action of this resource, to the session's host
    /// instead of applying it here. The host decides it as the person's, as
    /// it decides any caller's, may first put it to the person on its own
    /// sheet (what a run asks is answered there, never by the app), and then
    /// directs it back to be applied. A refusal is told in
    /// [`Self::refused`].
    pub fn through_host(&self, invoke: &Invoke<R>) {
        if let Some(refusal) = invoke.refusal() {
            self.core.refuse(invoke.id, refusal.to_owned());
            return;
        }
        self.core.opener.invoke_own(
            ActionAddress::new(self.core.resource_id(), invoke.id),
            invoke.arguments.clone(),
        );
    }

    /// Send `call`, another resource's published action, to the session's
    /// host, continuing `parent`, the invocation the host delivered here for
    /// someone: the host decides it as theirs. A past version calls nothing.
    pub(crate) fn call_published(
        &self,
        parent: Option<tilo_actions::InvocationId>,
        call: &super::Call,
    ) -> Result<ui_core::InvocationCall, String> {
        if self.core.past {
            return Err("a past version calls nothing".into());
        }
        if let Some(custody) = &self.core.custody {
            custody.check()?;
        }
        let (target, argument) = call.request()?;
        Ok(self.core.opener.call(parent, target, argument))
    }

    /// Invoke an action published on a nested resource, such as one item of
    /// a collection.
    pub(crate) fn invoke_at(
        &self,
        address: ActionAddress,
        arguments: serde_json::Map<String, serde_json::Value>,
    ) {
        if self.read_only() {
            return;
        }
        if self.core.submits_over_connection() {
            self.core.submit_remote(&address, arguments, true);
            return;
        }
        self.core.queue_invocation(address, arguments);
    }

    /// Run `invoke`, one of the actions `actions` publishes (another
    /// record's, such as a settings section), through the host as a control
    /// bound to it runs it: where another provider keeps the record, it runs
    /// there. From an effect's handler or completion it continues that
    /// effect, as its caller's. A refusal is told in [`Self::refused`].
    pub fn invoke_on<T: Resource>(&self, actions: &super::Actions<T>, invoke: Invoke<T>) {
        if let Some(refusal) = invoke.refusal() {
            self.core.refuse(invoke.id, refusal.to_owned());
            return;
        }
        self.invoke_at(
            ActionAddress::new(actions.resource_id(), invoke.id),
            invoke.arguments,
        );
    }

    /// Submit one typed action value — an edit with no named declaration,
    /// such as a drag's final geometry. The door applies it after the
    /// event; if it refuses it, [`Self::refused`] says why.
    pub fn apply(&self, action: &R::Action) {
        match Invoke::<R>::apply(action) {
            Ok(invoke) => self.submit_invoke(invoke),
            Err(error) => self.core.refuse(tilo_resource::APPLY, error.to_string()),
        }
    }

    /// Submit every edit `edits` makes through this dispatcher (or a clone
    /// of it) as one action: one change, one version in history, one undo
    /// step. For a gesture that is several edits — split a linked clip pair,
    /// delete a selection — which the user takes back with one Ctrl+Z.
    ///
    /// One action is one undo step by default; a group is the explicit
    /// exception. Groups nest: the outermost one submits. A group of one
    /// edit submits that edit unchanged.
    pub fn group<T>(&self, edits: impl FnOnce() -> T) -> T {
        let _group = self.begin_group();
        edits()
    }

    /// Open a group that submits when the returned guard drops: the
    /// [`group`](Self::group) for code whose edits are spread over a scope,
    /// such as one input event of a custom surface.
    #[must_use = "the group submits when this guard drops"]
    pub fn begin_group(&self) -> DispatchGroup<R> {
        let mut group = self.group.borrow_mut();
        group.0 = group.0.saturating_add(1);
        drop(group);
        DispatchGroup {
            dispatcher: self.clone(),
        }
    }

    fn end_group(&self) {
        let members = {
            let mut group = self.group.borrow_mut();
            group.0 = group.0.saturating_sub(1);
            if group.0 > 0 {
                return;
            }
            std::mem::take(&mut group.1)
        };
        let mut members = members.into_iter();
        match (members.next(), members.next()) {
            (None, _) => {}
            (Some(only), None) => self.queue(only),
            (Some(first), Some(second)) => {
                self.queue(Invoke::group([first, second].into_iter().chain(members)));
            }
        }
    }

    /// Apply a field edit (`p.title.splice(..)`) or a verb to the document
    /// `edits` lends, now, as [`Self::apply_now`] applies a typed action: for
    /// an editor that must see its own edit before the next keystroke.
    ///
    /// One that needs confirming (a destructive verb, a removal) is not
    /// applied now: it goes to the host's door, which asks first, and
    /// applies once the person agreed, as [`Self::submit`] does.
    ///
    /// # Errors
    /// Returns why the submission does not build, or as [`Self::apply_now`].
    pub fn submit_now(
        &self,
        edits: &mut Edits<'_>,
        submit: impl Submit<R>,
    ) -> Result<(), ActionError> {
        let invoke = submit.into_invoke().map_err(ActionError::Refused)?;
        if invoke.is_group() {
            return self.group_now(edits, &invoke);
        }
        let _capture = self.capture_invocation(&invoke);
        let action = invoke
            .build(tilo_resource::origin_now_ms())
            .map_err(ActionError::Refused)?;
        if asks(&action) {
            return self.ask_first(invoke, &action);
        }
        self.apply_now(edits, &action)
    }

    /// [`Self::submit_now`] of the person's own gesture on the surface: the
    /// button they pressed, the shortcut they typed, with arguments the
    /// gesture itself supplied. Like a keystroke, such a gesture is its own
    /// confirmation, so a destructive verb the surface offers with its own
    /// way back (a message held so Undo takes it back unsent) applies now.
    /// What has no way back (`#[action(irreversible)]`) is still asked first.
    /// The confirmation stays with the callers who supply the arguments
    /// themselves (the palette, a script, an agent): under any invocation,
    /// an effect's handler, custody or a past version this is
    /// [`Self::submit_now`], and the host asks as for any caller.
    ///
    /// # Errors
    /// As [`Self::submit_now`].
    pub fn submit_gesture(
        &self,
        edits: &mut Edits<'_>,
        submit: impl Submit<R>,
    ) -> Result<(), ActionError> {
        if !self.gesture_is_own() {
            return self.submit_now(edits, submit);
        }
        let invoke = submit.into_invoke().map_err(ActionError::Refused)?;
        if invoke.is_group() {
            return self.group_now(edits, &invoke);
        }
        let action = invoke
            .build(tilo_resource::origin_now_ms())
            .map_err(ActionError::Refused)?;
        // The gesture confirms only what has a way back: a verb that loses
        // something Undo cannot bring back is asked first, as at every door.
        if tilo_actions::Action::irreversible(&action) && asks(&action) {
            return self.ask_first(invoke, &action);
        }
        let applied = self.apply_now_as(edits, &action, self.core.context(), true);
        // A view that showed the edit before it was refused (a row already
        // gone) shows the stored state again.
        if applied.is_err() {
            self.core.represent.set(true);
        }
        applied
    }

    /// [`Self::submit_gesture`] of a choice the person picked that is
    /// confirmed before it goes ahead, though Undo would take it back:
    /// Delete in a message's context menu. The host asks with the same
    /// question it asks for any confirmation; holding Shift skips it, and
    /// the choice applies at once as the person's gesture, if and only if
    /// Undo takes it back ([`ui_core::widget::shift_skips_confirmation`]).
    /// What Undo cannot take back is asked, Shift or not.
    ///
    /// A control the person presses is its own confirmation
    /// ([`Self::submit_gesture`]); this is for a choice made from a list of
    /// them, where a slip of the pointer picks the neighbour.
    ///
    /// # Errors
    /// As [`Self::submit_gesture`].
    pub fn submit_confirming(
        &self,
        edits: &mut Edits<'_>,
        submit: impl Submit<R>,
    ) -> Result<(), ActionError> {
        if !self.gesture_is_own() {
            return self.submit_now(edits, submit);
        }
        let invoke = submit.into_invoke().map_err(ActionError::Refused)?;
        if invoke.is_group() {
            return self.group_now(edits, &invoke);
        }
        let action = invoke
            .build(tilo_resource::origin_now_ms())
            .map_err(ActionError::Refused)?;
        if asks(&action) {
            // The contract asks already: the door's question, which Shift
            // skips there for what Undo takes back.
            return self.ask_first(invoke, &action);
        }
        let undoable = tilo_actions::undo_takes_back(
            tilo_actions::Action::action_kind(&action),
            tilo_actions::Action::change_kind(&action),
            tilo_actions::Action::irreversible(&action),
        );
        if ui_core::widget::shift_skips_confirmation(undoable) {
            return self.submit_gesture(edits, invoke);
        }
        if let Some(reason) = self.core.unreadable() {
            return Err(ActionError::Refused(reason));
        }
        if !self.may_apply(&action) {
            return Err(self.not_allowed(&action));
        }
        let before = self.core.asking.replace(Origin::PersonConfirming);
        self.submit_invoke(invoke);
        self.core.asking.set(before);
        Ok(())
    }

    fn ask_first(&self, invoke: Invoke<R>, action: &R::Action) -> Result<(), ActionError> {
        if let Some(reason) = self.core.unreadable() {
            return Err(ActionError::Refused(reason));
        }
        if !self.may_apply(action) {
            return Err(self.not_allowed(action));
        }
        self.submit_invoke(invoke);
        Ok(())
    }

    /// [`Self::submit_now`] of a group (`Invoke::group(edits)`): its members
    /// applied as one action, one change and one entry in history, all or
    /// nothing.
    fn group_now(&self, edits: &mut Edits<'_>, invoke: &Invoke<R>) -> Result<(), ActionError> {
        let _nonlocal = self.capture_nonlocal();
        let _capture = self.capture_invocation(invoke);
        let Some(group_now) = &self.group_now else {
            return Err(ActionError::Refused(
                "this record's edits are applied one at a time".into(),
            ));
        };
        self.core.applies_now()?;
        let group = tilo_resource::group::build_group::<R>(
            &invoke.arguments,
            tilo_resource::origin_now_ms(),
        )
        .map_err(ActionError::Refused)?;
        if let Some(refused) = group.actions.iter().find(|action| !self.may_apply(action)) {
            return Err(self.not_allowed(refused));
        }
        // A group holding a removal asks first, as the queued door does.
        if group.actions.iter().any(asks) {
            self.submit_invoke(invoke.clone());
            return Ok(());
        }
        let mut context = self.core.context();
        if let Some(me) = &self.core.me {
            context = context.with_invoker(ActionInvoker::actor(me.as_ref()));
        }
        group_now(&mut self.core.host.borrow_mut(), edits, &group, context)?;
        // A group is a step of its own: nothing continues it.
        *self.last.borrow_mut() = None;
        self.core.grouped();
        Ok(())
    }

    /// Apply one typed action to the document `edits` lends — an event's,
    /// or a settle pass's — now, attributed to the participant, with history
    /// recording what the action did.
    /// One event's actions are one undo step, and an action that continues
    /// the previous one ([`Resource::coalesces`], the next letter of a word)
    /// joins its step. An action that needs confirming (a destructive verb,
    /// a removal) is not applied now: it is submitted to the host's door,
    /// which asks the person first ([`Self::apply`]).
    ///
    /// # Errors
    /// Returns [`ActionError::Refused`] for a participant who may only view,
    /// and the action's own refusal; nothing is written either way.
    pub fn apply_now(&self, edits: &mut Edits<'_>, action: &R::Action) -> Result<(), ActionError> {
        self.apply_now_as(edits, action, self.core.context(), false)
    }

    /// [`Self::apply_now`] of an action the person already confirmed, as
    /// the host applies it once they agreed: what a test resolving the
    /// queue as confirmed applies.
    ///
    /// # Errors
    /// As [`apply_now`](Self::apply_now).
    pub fn apply_confirmed(
        &self,
        edits: &mut Edits<'_>,
        action: &R::Action,
    ) -> Result<(), ActionError> {
        self.apply_now_as(edits, action, self.core.context(), true)
    }

    /// Apply `action` now to the document `edits` lends, for `invoker`: a
    /// step a door carries out for whoever invoked it that writes this
    /// record too (a container listing a new child), attributed to them.
    ///
    /// # Errors
    /// As [`apply_now`](Self::apply_now).
    pub(crate) fn apply_now_for(
        &self,
        edits: &mut Edits<'_>,
        action: &R::Action,
        invoker: &tilo_actions::ActionInvoker,
    ) -> Result<(), ActionError> {
        let context = self.core.context().with_invoker(invoker.clone());
        self.apply_now_as(edits, action, context, true)
    }

    fn apply_now_as(
        &self,
        edits: &mut Edits<'_>,
        action: &R::Action,
        context: ActionContext,
        confirmed: bool,
    ) -> Result<(), ActionError> {
        let _nonlocal = self.capture_nonlocal();
        self.core.applies_now()?;
        if !self.may_apply(action) {
            return Err(self.not_allowed(action));
        }
        if self.core.submits_over_connection() {
            // Nothing to apply to here: the session keeps the record, so the
            // edit is the same typed action submitted over the connection
            // (`one-app-model.md` §4). The view shows its own result until
            // the session's reading follows it.
            let invoke = Invoke::<R>::apply(action).map_err(ActionError::Encode)?;
            self.core.submit_remote(
                &ActionAddress::new(self.core.resource_id.as_ref(), invoke.id),
                invoke.arguments,
                true,
            );
            return Ok(());
        }
        // Applying now never skips the person's consent: an action that
        // needs confirming goes to the door, which asks first.
        if asks(action) && !confirmed {
            self.apply(action);
            return Ok(());
        }
        // Content from outside is nobody's step: it neither continues the
        // open one nor ends it.
        let step = tilo_actions::Action::change_kind(action).is_step();
        // Only an action right after this dispatcher's last one, with nothing
        // in between, can continue it.
        let serial = self.core.serial.get();
        let continues = step
            && self
                .last
                .borrow()
                .as_ref()
                .is_some_and(|(at, previous)| *at == serial && R::coalesces(previous, action));
        let context = self.core.step_context(context, step, continues);
        let fallback = if !ui_core::local_document_action::input_is_active()
            || ui_core::local_document_action::has_invocation()
        {
            None
        } else {
            Some(Invoke::<R>::apply(action).map_err(ActionError::Encode)?)
        };
        let _capture = fallback
            .as_ref()
            .and_then(|invoke| self.capture_invocation(invoke));
        (self.submit_now)(&mut self.core.host.borrow_mut(), edits, action, context)?;
        if !step {
            return Ok(());
        }
        let serial = self.core.stepped(continues, R::continuable(action));
        *self.last.borrow_mut() = Some((serial, action.clone()));
        Ok(())
    }

    /// The dispatcher of another record than this resource's — the
    /// person's own record, a settings section — published at `id`: its
    /// queued invocations go through the same door as this resource's, and
    /// what it applies now `apply` applies to that record. The workspace's roles
    /// do not reach it; only its person changes it.
    pub(crate) fn for_record<C: Resource>(
        &self,
        id: &str,
        read_only: bool,
        apply: impl Fn(&C::Action) -> Result<(), ActionError> + 'static,
    ) -> Dispatcher<C> {
        Dispatcher {
            core: self.core.for_record(id, (C::KIND, C::LABEL), read_only),
            group: Rc::default(),
            permission_of: Rc::new(|_: &C::Action| ActionNeed::of(tilo_actions::ActionKind::Read)),
            submit_now: Rc::new(move |_, _, action: &C::Action, _| apply(action)),
            group_now: None,
            last: Rc::default(),
        }
    }

    /// The dispatcher of a record the app keeps beside its own in the workspace,
    /// published at `id` (the parts of a chain): its queued invocations are
    /// addressed to `id`, `apply` applies one now, and what an action needs
    /// is its own declared need, checked against the participant's roles in
    /// the workspace as this resource's actions are.
    pub(crate) fn for_workspace_record<C: Resource>(
        &self,
        id: &str,
        read_only: bool,
        apply: impl Fn(&C::Action) -> Result<(), ActionError> + 'static,
    ) -> Dispatcher<C> {
        let mut core = self.core.for_record(id, (C::KIND, C::LABEL), read_only);
        core.permissions = Rc::clone(&self.core.permissions);
        Dispatcher {
            core,
            group: Rc::default(),
            permission_of: Rc::new(tilo_resource::need_of::<C>),
            submit_now: Rc::new(move |_, _, action: &C::Action, _| apply(action)),
            group_now: None,
            last: Rc::default(),
        }
    }

    /// The dispatcher of a resource nested in this one at `id` — a note's
    /// rich-text body, a draft's SQL — whose every edit is this resource's
    /// action `wrap(edit)`.
    ///
    /// The child is edited like a root: its named actions,
    /// [`apply`](Self::apply), [`group`](Self::group) and
    /// [`apply_now`](Self::apply_now) take `C`'s own actions, coalesce into
    /// undo steps by `C`'s [`Resource::coalesces`], and history names them
    /// after `C`'s labels. Underneath, each applies as this resource's
    /// action: the same permission check, history, undo and replay. Queued
    /// invocations are addressed to the child resource `id`, so this
    /// resource publishes the child at the same id with the same `wrap`
    /// ([`tilo_resource::publish_child`] in [`Resource::children`]), which
    /// is also what lets the palette, agents and scripts reach it.
    #[must_use]
    pub fn child<C: Resource>(
        &self,
        id: &str,
        wrap: impl Fn(C::Action) -> R::Action + 'static,
    ) -> Dispatcher<C> {
        let parent = Rc::clone(&self.submit_now);
        let parent_permission = Rc::clone(&self.permission_of);
        let wrap = Rc::new(wrap);
        let wrap_for_permission = Rc::clone(&wrap);
        Dispatcher {
            core: self.core.child(id, (C::KIND, C::LABEL)),
            group: Rc::default(),
            permission_of: Rc::new(move |action: &C::Action| {
                parent_permission(&wrap_for_permission(action.clone()))
            }),
            // History names the child and its edit; what applies is the
            // parent's action carrying it.
            group_now: None,
            submit_now: Rc::new(move |host, edits, action: &C::Action, context| {
                parent(host, edits, &wrap(action.clone()), context)
            }),
            last: Rc::default(),
        }
    }

    fn capture_nonlocal(&self) -> Option<ui_core::local_document_action::Scope> {
        (self.core.custody.is_some() || super::effect::acting_for().is_some())
            .then(ui_core::local_document_action::suspend)
    }

    fn capture_invocation(
        &self,
        invoke: &Invoke<R>,
    ) -> Option<ui_core::local_document_action::InvocationScope> {
        if !ui_core::local_document_action::input_is_active()
            || self.core.custody.is_some()
            || super::effect::acting_for().is_some()
            || ui_core::local_document_action::has_invocation()
        {
            return None;
        }
        Some(ui_core::local_document_action::with_invocation(
            ui_core::local_document_action::PublishedInvocation {
                resource: self.core.resource_id.to_string(),
                action: invoke.id.to_owned(),
                arguments: invoke.arguments.clone(),
            },
        ))
    }

    /// End the gesture the last immediate actions belonged to: the pointer
    /// was let go of a slider or a drag handle. The next action starts a
    /// step of its own even when it would continue the last one
    /// ([`Resource::coalesces`]), so two drags of one slider are two undo
    /// steps while every value one drag passes through is one.
    pub fn settle(&self) {
        self.last.borrow_mut().take();
    }

    pub(crate) fn name_resource(&self, label: &str) {
        self.core.resource_label.set(label.to_owned());
    }

    /// The id of the app whose resource this is, which presence keys name
    /// ([`ResourceSelection::presence`](super::ResourceSelection::presence)).
    pub fn app_id(&self) -> &'static str {
        self.core.app_id
    }
}

/// Whether the participant `core` edits for may take the action `id` the
/// resource's `declarations` may declare: what its declaration needs; a
/// group of edits what writing does; anything else what reading does.
fn may_declared(
    core: &DispatchCore,
    declarations: &[tilo_resource::Declaration],
    id: &str,
    group: bool,
) -> bool {
    match declarations.iter().find(|decl| decl.id == id) {
        Some(decl) => core.may(&ActionNeed {
            kind: decl.kind,
            field: decl.field.map(str::to_owned),
            privileged: false,
        }),
        None if group => !core.read_only.get(),
        None => core.may(&ActionNeed::of(ActionKind::Read)),
    }
}

/// An edit or effect the door refused ([`Dispatcher::refused`]), or one the
/// workspace refused after this device applied it.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Refused {
    /// The id of the refused action or effect: for one the workspace refused,
    /// the verb's key or the edited field's path.
    pub action: String,
    /// The item it acted on, when the workspace refused it and it named one.
    pub item: Option<String>,
    /// Why, for a person.
    pub reason: String,
    /// The workspace refused it: it was applied here, never reached anyone
    /// else, and was withdrawn again. Submitting it again is a new action.
    pub by_workspace: bool,
}

/// A submission the door applied ([`Dispatcher::landed`]).
#[derive(Clone, Debug, PartialEq)]
pub struct Landed {
    /// The id of the applied action.
    pub action: String,
    /// What it answered, if anything.
    pub answer: Option<serde_json::Value>,
    /// The resources it created (`<kind>/<field>/<id>` for an item).
    pub created: Vec<String>,
}

impl Landed {
    fn of(action: &str, output: &tilo_actions::ActionOutput) -> Self {
        Self {
            action: action.to_owned(),
            answer: output.value.clone(),
            created: output.resources.clone(),
        }
    }

    /// The ids the action minted, in the order it minted them: the item a
    /// "new" verb created first.
    #[must_use]
    pub fn minted(&self) -> Vec<tilo_resource::Id> {
        self.created
            .iter()
            .filter_map(|resource| resource.rsplit('/').next())
            .map(tilo_resource::Id::from_raw)
            .collect()
    }
}

/// Whether `action` needs the person's confirmation before it applies, by
/// the one rule every door asks (`tilo_actions::asks_first`): its risk asks
/// for it and Undo cannot take it back. A removal that only changes the
/// document runs at once; Undo is how the person takes it back. One that
/// loses something outside the document (`irreversible`) still asks.
fn asks<A: tilo_actions::Action>(action: &A) -> bool {
    tilo_actions::asks_first(
        tilo_actions::Action::risk(action),
        tilo_actions::Action::action_kind(action),
        tilo_actions::Action::change_kind(action),
        tilo_actions::Action::irreversible(action),
    )
}

/// The submissions each effect queued that have not landed yet, and the
/// effects waiting for theirs.
#[derive(Default)]
struct Waits(std::collections::HashMap<tilo_actions::InvocationId, Wait>);

#[derive(Default)]
struct Wait {
    /// Queued, not yet answered by the door.
    outstanding: usize,
    /// The last that landed, or the first refusal.
    result: Option<Result<Landed, String>>,
    waiter: Option<std::sync::mpsc::Sender<Result<Landed, String>>>,
}

impl Waits {
    fn submitted(&mut self, invocation: tilo_actions::InvocationId) {
        let wait = self.0.entry(invocation).or_default();
        wait.outstanding = wait.outstanding.saturating_add(1);
    }

    fn landed(&mut self, invocation: tilo_actions::InvocationId, landed: Result<Landed, String>) {
        let Some(wait) = self.0.get_mut(&invocation) else {
            return;
        };
        wait.outstanding = wait.outstanding.saturating_sub(1);
        // The first refusal stands: the effect failed with it.
        if !matches!(wait.result, Some(Err(_))) {
            wait.result = Some(landed);
        }
        self.settle(invocation);
    }

    fn wait(
        &mut self,
        invocation: tilo_actions::InvocationId,
    ) -> Option<std::sync::mpsc::Receiver<Result<Landed, String>>> {
        let wait = self.0.get_mut(&invocation)?;
        let (sender, receiver) = std::sync::mpsc::channel();
        wait.waiter = Some(sender);
        self.settle(invocation);
        Some(receiver)
    }

    /// Answer the waiting effect once nothing it submitted is outstanding;
    /// forget an effect nobody waits on then.
    fn settle(&mut self, invocation: tilo_actions::InvocationId) {
        let Some(wait) = self.0.get_mut(&invocation) else {
            return;
        };
        if wait.outstanding > 0 {
            return;
        }
        if let Some(waiter) = wait.waiter.take()
            && let Some(result) = wait.result.take()
        {
            let _ = waiter.send(result);
        }
        self.0.remove(&invocation);
    }
}

/// An open [`Dispatcher::begin_group`]: every edit submitted until it drops
/// becomes one action.
pub struct DispatchGroup<R: Resource> {
    dispatcher: Dispatcher<R>,
}

impl<R: Resource> Drop for DispatchGroup<R> {
    fn drop(&mut self) {
        self.dispatcher.end_group();
    }
}