lattice_mode/

action_handler_registry.rs

//! Action-handler registry — mode-contributed closures
//! per `CommandId` (M.10.1).
//!
//! Per `feedback_mode_owns_its_surface` (CLAUDE.md standing
//! rules, sharpened 2026-06-02) + `mode-architecture.md` §5.3,
//! a mode owns BOTH the chord choice AND the action handler
//! body. The keymap layer is contributed by `Mode::keymap()`;
//! the handler closure is registered into this substrate from
//! `Mode::on_activate`. The host's chord-resolved-action
//! dispatcher consults this registry; the handler returns an
//! `Effect` the host applies through the existing pipeline.
//!
//! Half-migration failure mode (the M.10 audit caught this):
//! keymap layer in the mode but `Editor::do_<provider>_action`
//! body in `lattice-host::dispatch`. This substrate exists so
//! the handler body lives in the mode's owning crate, not the
//! host.
//!
//! ## Shape
//!
//! Wait-free lookup via `arc-swap`. Register / unregister
//! perform a copy-on-write via `ArcSwap::rcu` — O(N) per
//! lifecycle event but registers are rare (per mode
//! activation / deactivation, not per keystroke). Lookups
//! happen per chord-dispatch — one `Arc` load + one
//! `HashMap::get`.
//!
//! ## Lifecycle
//!
//! `register` returns an [`ActionHandlerRegistration`] RAII
//! token. The mode's `Guard` carries one token per registered
//! action; dropping the Guard drops the tokens, each of which
//! unregisters its `CommandId`. Re-activation re-registers
//! fresh closures.

use std::collections::HashMap;
use std::sync::Arc;

use arc_swap::ArcSwap;
use lattice_grammar::effect::Effect;
use lattice_grammar::{ArgValue, Args};
use lattice_protocol::ids::{BufferId, CommandId};
use lattice_protocol::position::Position;
use lattice_runtime::EventBus;

use crate::services::ServiceRegistry;

/// Read-only context handed to a mode-contributed action
/// handler closure. Carries the bare minimum the host can
/// supply on every invocation: the active buffer + cursor and
/// shared subsystem registries the handler may need.
///
/// Borrows from App-owned state for the duration of the
/// action dispatch — handlers do NOT outlive their context.
pub struct ActionContext<'a> {
    /// Active buffer at the moment the chord fired.
    pub buffer_id: BufferId,
    /// Active document cursor at the moment the chord fired.
    pub cursor: Position,
    /// The **active region** — the Visual/Select-mode selection
    /// extent, normalised so `start <= end`. `None` in Normal mode and
    /// on every non-chord firing path (prompt submit, transient item,
    /// a `Confirm` yes-action) (MG.18e).
    ///
    /// Design §5.2's "Visual mode IS the active region" applied to mode
    /// action handlers: a chord that fires with a selection up should
    /// be able to act on it, the same way `Range::Selection` is the
    /// default range argument for an ex-command. magit's region staging
    /// is the first consumer — select some lines inside a hunk, press
    /// `s`, stage only those.
    ///
    /// **Carries no visual kind.** A diff line is the unit of every
    /// consumer so far, and the row span is all they read; adding
    /// charwise/blockwise distinctions before something needs them
    /// would be inventing a contract nobody is holding.
    pub selection: Option<lattice_protocol::position::Range>,
    /// Typed service registry. Handlers look up subsystem
    /// handles they need (`MultibufferRegistryHandle`,
    /// `ProjectSearchServiceHandle`, etc.) via
    /// `ctx.services.get::<Foo>()`.
    pub services: &'a ServiceRegistry,
    /// Typed event bus. Handlers publish events that other
    /// subsystems subscribe to (e.g.
    /// `ProjectSearchRefreshed`).
    pub events: &'a EventBus,
    /// Set only when this handler fires as the submit callback of an
    /// `Effect::OpenPrompt`-opened prompt (`Editor::do_prompt_line_submit`)
    /// — the prompt buffer's typed content at the moment of submit.
    /// `None` for every other firing path (chord dispatch, transient
    /// item click, `Effect::Confirm`'s yes-action, ...).
    pub prompt_value: Option<&'a str>,
    /// Arguments the invocation carried (MG.17a).
    ///
    /// `Args::None` for a bare chord press. A transient item's flags
    /// and arguments arrive here as `Args::List`, ordered by the
    /// action's `args_schema` — the same shape the `:` line produces
    /// for an ex-command, so one handler body serves both front-ends
    /// instead of each surface growing its own accessor. Read it with
    /// [`Self::flag`] / [`Self::arg_str`] rather than matching the
    /// list positionally.
    pub args: Args,
    /// The active buffer's typed mode-owned locals, read-only, for
    /// the duration of the dispatch. `Some` on the host chord-dispatch
    /// path (where a mode handler may need to read its buffer's state —
    /// oil's dir/snapshot, a file tree's entries — to resolve the entry
    /// under the cursor); `None` on the auxiliary firing paths (prompt
    /// submit, transient item, a `Confirm` yes-action) and wherever a
    /// caller builds a context without a buffer-locals store (LM.1).
    ///
    /// Read it through [`Self::buffer_local`] rather than the field, so a
    /// handler that runs with `None` degrades to "no such local" — the
    /// same answer as an unseeded buffer — instead of a branch.
    ///
    /// Keeping the state in `buffer_locals` (rather than a separate
    /// service) is deliberate: it stays enumerable by `:describe-buffer`
    /// via `iter_descriptors`, so a mode owning per-buffer state does not
    /// trade introspection for handler-reachability.
    pub buffer_locals: Option<&'a crate::locals::BufferLocals>,
}

impl<'a> ActionContext<'a> {
    /// Read one of the active buffer's mode-owned locals, if the
    /// context carries a buffer-locals store and the local is seeded (LM.1).
    ///
    /// Total: `None` covers a context built without locals (an auxiliary
    /// firing path) and a buffer that never seeded `T`, which a handler
    /// treats the same way — there is nothing to act on.
    pub fn buffer_local<T: crate::locals::BufferLocal>(&self) -> Option<&T> {
        self.buffer_locals.and_then(|l| l.get::<T>())
    }
}

impl ActionContext<'_> {
    /// The boolean argument at `index` in the action's `args_schema`.
    ///
    /// `false` when the invocation carried no args (a bare chord), when
    /// the index is past the end, or when that slot holds a non-bool —
    /// a handler asking "was `--force` set?" wants `false` for all
    /// three, not three different error paths.
    pub fn flag(&self, index: usize) -> bool {
        match self.args.as_list().and_then(|l| l.get(index)) {
            Some(ArgValue::Bool(b)) => *b,
            _ => false,
        }
    }

    /// The project this action is acting in (PR.2).
    ///
    /// Design: `docs/dev/architecture/project-resolution.md` §5. This is
    /// a method rather than a field so that "which project" is a
    /// question every action handler can ask without the host having to
    /// answer it on every dispatch — resolution is cached and most
    /// handlers never ask.
    ///
    /// **Total**, matching `ProjectResolver::for_path`: a handler that
    /// cannot express "no project" cannot get it wrong. The degradations
    /// are both real answers, not errors:
    ///
    /// - a buffer with no path (scratch, `*messages*`, a terminal) has
    ///   no tree to walk, so the working directory stands in;
    /// - a partially-wired harness with no resolver registered falls
    ///   back to the process working directory, which is what every
    ///   consumer did before this existed.
    pub fn project(&self) -> lattice_core::Project {
        let Some(resolver) = self.services.get::<lattice_core::ProjectResolverHandle>() else {
            // Not `warn!`: a test harness that wires only the services
            // it exercises is the common caller, and this is exactly
            // the pre-PR.2 behaviour rather than a degradation.
            tracing::debug!("no project resolver registered; falling back to the process cwd");
            return lattice_core::Project {
                root: std::env::current_dir().unwrap_or_else(|_| std::path::PathBuf::from(".")),
                kind: lattice_core::ProjectKind::Pwd,
            };
        };
        // `ActionContext` carries a `lattice_protocol::BufferId`;
        // `BufferStore` speaks `lattice_core::BufferId`. Distinct types
        // over the same u32 — the `repl_mode` conversion precedent.
        let path = self
            .services
            .get::<crate::buffer_store::BufferStoreHandle>()
            .and_then(|store| store.path_for(lattice_core::BufferId(self.buffer_id.0 as u32)));
        match path {
            Some(path) => resolver.for_path(&path),
            // No path to walk from. `for_path` on a relative empty path
            // would resolve against pwd anyway, but going through the
            // resolver keeps the pwd answer consistent with `:cd`
            // rather than reading the process cwd directly.
            None => resolver.for_path(std::path::Path::new("")),
        }
    }

    /// The string argument at `index`, or `None` when absent or empty.
    /// Empty is treated as absent because a transient argument left at
    /// its default renders as an empty string.
    pub fn arg_str(&self, index: usize) -> Option<&str> {
        match self.args.as_list().and_then(|l| l.get(index)) {
            Some(ArgValue::String(s)) | Some(ArgValue::Raw(s)) if !s.is_empty() => Some(s.as_str()),
            _ => None,
        }
    }
}

/// Action handler closure shape. Returns an [`Effect`] when
/// the handler wants the host to apply state mutation
/// (open a file, change selection, etc.); `None` for
/// fire-and-forget handlers (logging, publishing an event).
///
/// Closures are `Send + Sync` so the registry can be cloned
/// freely across threads; they take a borrowed
/// [`ActionContext`] for zero-copy access to live state.
pub type ActionHandler = Arc<dyn Fn(&ActionContext<'_>) -> Option<Effect> + Send + Sync + 'static>;

/// A *global* (buffer-agnostic) action-handler
/// contribution declared by a mode via
/// [`Mode::action_handlers`](crate::Mode::action_handlers) (SN.3c.0).
///
/// Use this for handlers whose body reads the active buffer /
/// cursor / services from the [`ActionContext`] at call time and
/// closes over no per-buffer state — they are registered ONCE at
/// boot (the host walks every mode's `action_handlers()`,
/// resolves `action_name` → `CommandId`, and registers the
/// handler), and live for the app's lifetime. The owning chord's
/// per-keystroke mode gating (K.1.c) still scopes *where the
/// chord fires*; the handler itself is global.
///
/// Per-buffer handlers (tied to a live session / per-activation
/// state) must NOT use this — they register in
/// [`Mode::on_activate`](crate::Mode::on_activate) so their
/// `ActionHandlerRegistration` token drops with the mode's Guard.
/// See `feedback_effect_vocabulary_is_host_boundary`.
#[derive(Clone)]
pub struct ActionHandlerContribution {
    /// Canonical command name (e.g. `"action:snippet-expand"`).
    /// The host resolves this to a `CommandId` via the command
    /// registry at registration time.
    pub action_name: &'static str,
    /// The handler closure registered for `action_name`.
    pub handler: ActionHandler,
}

impl std::fmt::Debug for ActionHandlerContribution {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ActionHandlerContribution")
            .field("action_name", &self.action_name)
            .finish_non_exhaustive()
    }
}

/// Typed handle for `ServiceRegistry`
/// lookup. Boot registers a fresh `ActionHandlerRegistry` under
/// this alias; modes pull it from `on_activate` via
/// `ctx.service::<ActionHandlerRegistryHandle>()` (M.10.1.b, 2026-06-03).
///
/// Per `feedback_servicesregistry_arc_typeid`: register and
/// lookup MUST use the same `T` for the TypeId hash to match.
/// This alias guarantees the convention.
pub type ActionHandlerRegistryHandle = Arc<ActionHandlerRegistry>;

/// Wait-free registry of mode-contributed action handlers.
///
/// Stored behind an `Arc` and shared by reference: the host's
/// chord dispatcher reads via [`lookup`](Self::lookup);
/// modes register via [`register`](Self::register) during
/// `Mode::on_activate` and unregister via the returned
/// [`ActionHandlerRegistration`] token's `Drop` impl.
///
/// # Examples
///
/// The per-buffer path: a mode registers in `on_activate` and keeps the token
/// in its Guard, so deactivation unregisters the body.
///
/// ```
/// use std::sync::Arc;
/// use lattice_grammar::effect::{EchoLevel, Effect};
/// use lattice_mode::{ActionHandler, ActionHandlerRegistry};
/// use lattice_protocol::ids::CommandId;
///
/// let registry = Arc::new(ActionHandlerRegistry::new());
/// let refresh = CommandId::new(41); // resolved from "action:weather-refresh"
///
/// let body: ActionHandler = Arc::new(|ctx| {
///     let text = format!("refreshing buffer {}", ctx.buffer_id);
///     Some(Effect::Echo { level: EchoLevel::Info, text })
/// });
/// let token = registry.register(refresh, body); // lives in the mode's Guard
/// assert!(registry.lookup(refresh).is_some());
///
/// drop(token); // the Guard dropped: the mode deactivated
/// assert!(registry.lookup(refresh).is_none());
/// ```
pub struct ActionHandlerRegistry {
    handlers: ArcSwap<HashMap<CommandId, ActionHandler>>,
}

impl ActionHandlerRegistry {
    /// Construct an empty registry.
    pub fn new() -> Self {
        Self {
            handlers: ArcSwap::from_pointee(HashMap::new()),
        }
    }

    /// Register an action handler closure for `action_id`.
    /// Returns an RAII registration token; the token's `Drop`
    /// impl unregisters the handler. Modes accumulate tokens
    /// in their `Guard` so deactivation drops them and the
    /// chord falls through to "unhandled" naturally.
    ///
    /// If a handler is already registered for `action_id`,
    /// the new closure replaces it. (Modes shouldn't collide
    /// on `CommandId` in normal usage — IDs are per-action
    /// and modes register distinct sets — but the
    /// last-write-wins semantics keeps the substrate
    /// behavior well-defined.)
    pub fn register(
        self: &Arc<Self>,
        action_id: CommandId,
        handler: ActionHandler,
    ) -> ActionHandlerRegistration {
        self.handlers.rcu(|map| {
            let mut next = (**map).clone();
            next.insert(action_id, handler.clone());
            next
        });
        ActionHandlerRegistration {
            registry: Arc::clone(self),
            action_id,
        }
    }

    /// Wait-free lookup. Returns a cloned `Arc` of the
    /// handler closure (cheap — `Arc::clone` is one atomic
    /// increment). The host's chord dispatcher calls this
    /// once per chord resolution; calling the returned
    /// handler is a direct `Fn` invocation.
    pub fn lookup(&self, action_id: CommandId) -> Option<ActionHandler> {
        self.handlers.load().get(&action_id).cloned()
    }

    /// Direct unregister. Normally called via
    /// [`ActionHandlerRegistration::drop`]; exposed for
    /// callers that need explicit lifetime control (e.g.
    /// tests).
    fn unregister(&self, action_id: CommandId) {
        self.handlers.rcu(|map| {
            let mut next = (**map).clone();
            next.remove(&action_id);
            next
        });
    }

    /// Number of currently registered handlers. Test
    /// affordance — production code shouldn't need this.
    #[doc(hidden)]
    pub fn registered_count(&self) -> usize {
        self.handlers.load().len()
    }
}

impl Default for ActionHandlerRegistry {
    fn default() -> Self {
        Self::new()
    }
}

impl std::fmt::Debug for ActionHandlerRegistry {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ActionHandlerRegistry")
            .field("registered_count", &self.registered_count())
            .finish_non_exhaustive()
    }
}

/// RAII registration token. Dropping it unregisters the
/// handler. Modes typically aggregate these into their
/// `Mode::Guard`; when the Guard drops on deactivation, every
/// token drops, every handler unregisters.
///
/// `Send + 'static` so it fits the `Mode::Guard: Send +
/// 'static` bound.
pub struct ActionHandlerRegistration {
    registry: Arc<ActionHandlerRegistry>,
    action_id: CommandId,
}

impl ActionHandlerRegistration {
    /// The `CommandId` this registration is bound to.
    /// Test affordance.
    #[doc(hidden)]
    pub fn action_id(&self) -> CommandId {
        self.action_id
    }
}

impl Drop for ActionHandlerRegistration {
    fn drop(&mut self) {
        self.registry.unregister(self.action_id);
    }
}

impl std::fmt::Debug for ActionHandlerRegistration {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ActionHandlerRegistration")
            .field("action_id", &self.action_id)
            .finish_non_exhaustive()
    }
}

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used)]
    use super::*;

    fn cid(raw: u64) -> CommandId {
        CommandId::new(raw)
    }

    fn handler_returning_none() -> ActionHandler {
        Arc::new(|_ctx: &ActionContext<'_>| None)
    }

    #[test]
    fn register_then_lookup_returns_handler() {
        let r = Arc::new(ActionHandlerRegistry::new());
        let id = cid(1);
        let _reg = r.register(id, handler_returning_none());
        assert!(r.lookup(id).is_some());
    }

    #[test]
    fn missing_lookup_returns_none() {
        let r = Arc::new(ActionHandlerRegistry::new());
        assert!(r.lookup(cid(42)).is_none());
    }

    #[test]
    fn drop_registration_unregisters_handler() {
        let r = Arc::new(ActionHandlerRegistry::new());
        let id = cid(7);
        let reg = r.register(id, handler_returning_none());
        assert_eq!(r.registered_count(), 1);
        drop(reg);
        assert_eq!(r.registered_count(), 0);
        assert!(r.lookup(id).is_none());
    }

    #[test]
    fn multiple_handlers_coexist_and_drop_independently() {
        let r = Arc::new(ActionHandlerRegistry::new());
        let reg_a = r.register(cid(1), handler_returning_none());
        let reg_b = r.register(cid(2), handler_returning_none());
        let _reg_c = r.register(cid(3), handler_returning_none());
        assert_eq!(r.registered_count(), 3);
        drop(reg_a);
        assert_eq!(r.registered_count(), 2);
        assert!(r.lookup(cid(1)).is_none());
        assert!(r.lookup(cid(2)).is_some());
        assert!(r.lookup(cid(3)).is_some());
        drop(reg_b);
        assert_eq!(r.registered_count(), 1);
    }

    #[test]
    fn second_register_for_same_id_replaces_previous() {
        let r = Arc::new(ActionHandlerRegistry::new());
        let id = cid(10);

        // First handler always returns None; second returns
        // a sentinel Effect we can detect.
        let _reg_first = r.register(id, handler_returning_none());
        let _reg_second = r.register(id, Arc::new(|_ctx: &ActionContext<'_>| Some(Effect::None)));

        let h = r.lookup(id).unwrap();
        let services = ServiceRegistry::new();
        let events = EventBus::new();
        let ctx = ActionContext {
            buffer_id: BufferId::new(0),
            cursor: Position::ZERO,
            selection: None,
            services: &services,
            events: &events,
            prompt_value: None,
            args: lattice_grammar::Args::None,
            buffer_locals: None,
        };
        let effect = h(&ctx);
        assert!(matches!(effect, Some(Effect::None)));
    }

    /// LM.1: a mode handler reads its buffer's mode-owned local through
    /// `ctx.buffer_local::<T>()`, and the accessor degrades to `None` on a
    /// firing path that carries no locals — the mechanism the oil /
    /// file-tree navigation handlers (LM.3/LM.4) rely on to resolve the
    /// entry under the cursor.
    #[test]
    fn buffer_local_reads_the_active_buffers_local_and_degrades_to_none() {
        use crate::locals::BufferLocals;
        let services = ServiceRegistry::new();
        let events = EventBus::new();

        let mut locals = BufferLocals::default();
        locals.insert(crate::BufferScopeDir(std::path::PathBuf::from("/scope")));

        let ctx = ActionContext {
            buffer_id: BufferId::new(0),
            cursor: Position::ZERO,
            selection: None,
            services: &services,
            events: &events,
            prompt_value: None,
            args: lattice_grammar::Args::None,
            buffer_locals: Some(&locals),
        };
        assert_eq!(
            ctx.buffer_local::<crate::BufferScopeDir>()
                .map(|d| d.0.clone()),
            Some(std::path::PathBuf::from("/scope")),
            "a handler reads its buffer's mode-owned local through the context",
        );

        // An auxiliary firing path (prompt submit, transient) carries no
        // locals; the accessor answers None rather than panicking.
        let ctx_none = ActionContext {
            buffer_id: BufferId::new(0),
            cursor: Position::ZERO,
            selection: None,
            services: &services,
            events: &events,
            prompt_value: None,
            args: lattice_grammar::Args::None,
            buffer_locals: None,
        };
        assert!(ctx_none.buffer_local::<crate::BufferScopeDir>().is_none());
    }

    #[test]
    fn registration_is_send_static() {
        fn assert_send_static<T: Send + 'static>() {}
        assert_send_static::<ActionHandlerRegistration>();
    }

    #[test]
    fn registry_is_send_sync() {
        fn assert_send_sync<T: Send + Sync>() {}
        assert_send_sync::<ActionHandlerRegistry>();
        assert_send_sync::<ActionHandler>();
    }

    #[test]
    fn lookup_after_drop_chain_is_consistent() {
        // Stress: register / drop interleavings preserve
        // exact membership semantics.
        let r = Arc::new(ActionHandlerRegistry::new());
        let regs: Vec<_> = (0..16)
            .map(|i| r.register(cid(i), handler_returning_none()))
            .collect();
        assert_eq!(r.registered_count(), 16);
        // Drop every other registration.
        let (keep, drop_these): (Vec<_>, Vec<_>) =
            regs.into_iter().enumerate().partition(|(i, _)| i % 2 == 0);
        drop(drop_these);
        assert_eq!(r.registered_count(), 8);
        for (i, _) in &keep {
            assert!(r.lookup(cid(*i as u64)).is_some());
        }
        for i in (0..16).filter(|i| i % 2 != 0) {
            assert!(r.lookup(cid(i)).is_none());
        }
    }
}