lattice_grammar/

registry.rs

//! The `CommandRegistry` holds every registered operator, motion, text
//! object, and ex-command. The dispatcher (`super::dispatcher::execute`)
//! looks up commands here.
//!
//! Built-in commands are registered at editor startup via `populate_builtins`
//! (see `super::builtins`). Plugins register their own through the same
//! `register_*` methods. v1 keeps these as native Rust closures; the WASM
//! plugin host (Phase 7) wraps the same shape.

use std::collections::HashMap;
use std::sync::Arc;
use std::sync::atomic::{AtomicU64, Ordering};

use serde::{Deserialize, Serialize};

use lattice_core::Buffer;
use lattice_core::BufferId;
use lattice_core::Document;
use lattice_protocol::ids::CommandId;
use lattice_protocol::position::{Position, Range as ProtoRange};

use crate::args::{ArgSpec, Args};
use crate::command::{CommandKind, CommandSpec, Count};
use crate::error::{CommandError, GrammarResult};
use crate::register::Register;
use crate::source::{SourceKind, SourceLayer, SourceLocation};

/// Strongly-typed handle to an operator command in the registry.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct OperatorId(pub CommandId);

/// Strongly-typed handle to a motion command in the registry.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct MotionId(pub CommandId);

/// Strongly-typed handle to a text-object command in the registry.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct TextObjectId(pub CommandId);

/// Strongly-typed handle to an ex-command in the registry.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct ExCommandId(pub CommandId);

/// Strongly-typed handle to a custom range source (plugin-registered) used by
/// `Range::Custom(RangeId)`.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct RangeId(pub CommandId);

/// Context passed to a motion's evaluator.
///
/// **M.2.b.0.A (2026-05-31):** `buffer_id` carries the active
/// buffer's registry identity through to motion handlers. Built-
/// in motions (purely content-based: `w` / `e` / `]p` / etc.)
/// ignore it; kind-specific motions (multibuffer `]e` / `[e` /
/// `]E` / `[E`, future file-tree / oil structural motions, future
/// plugin-defined kinds) use it to look up the active major
/// mode's typed state through a service registry their handler
/// closure captures at registration time. Adding it here keeps
/// the grammar layer free of lattice-mode / ServiceRegistry
/// coupling — the handler decides what to look up.
pub struct MotionContext<'a> {
    /// The buffer text the motion reads. Motions never edit.
    pub buffer: &'a Buffer,
    /// Registry-level identity of the active buffer this motion
    /// is firing against. Distinct from `lattice_protocol::ids::
    /// DocumentId` (per-actor stable id); `BufferId` is the
    /// registry key that mode-state lookups use.
    pub buffer_id: BufferId,
    /// Where the motion starts: the cursor, or the Visual head.
    pub from: Position,
    /// The count, `1` when none was typed; see [`Self::has_explicit_count`].
    pub count: Count,
    /// True when the invocation carried an explicit count (e.g.
    /// `5G`). False for bare invocations (`G` alone). Motions
    /// whose semantic changes with an explicit count (goto-last-
    /// line: last vs. specific line) use this to disambiguate.
    pub has_explicit_count: bool,
    /// The motion's own arguments, e.g. [`Args::Char`] for `f{char}` or a
    /// mark name for `'x`.
    pub args: Args,
    /// Cooperative cancellation handle (DESIGN.md §5.2.5). Hot
    /// loops should poll `cancel.check()?` on each iteration; on a
    /// flipped token the evaluator returns
    /// [`crate::CommandError::Cancelled`] and the dispatcher
    /// commits no effect.
    pub cancel: &'a crate::CancellationToken,
    /// N.1.4-motions: the active buffer's tree-sitter resolver for structural
    /// motions (`]f`/`[c`/…). `None` on Plain buffers with no parse — the
    /// motion then no-ops. Threaded by the host, identical to `TextObjectContext`.
    pub scope_resolver: Option<&'a dyn ScopeResolver>,
    /// OM.6b: the file the motion's buffer is backed by, so a plugin motion's
    /// `document` handle can answer `path()`. A borrow — this context is
    /// already borrowing, so carrying it costs nothing on the keystroke path
    /// (motions fire on every `j`). `None` for a buffer with no file.
    pub path: Option<&'a std::path::Path>,
    /// OT.1: the same type-erased tree-sitter snapshot [`ActionContext::syntax`]
    /// carries, so a plugin motion can resolve structurally instead of scanning
    /// text. Copied straight from [`GrammarEnv::syntax`], which the host has
    /// always threaded here — until OT.1 motions simply did not read it.
    ///
    /// **Borrowed, not cloned**, unlike the owned `ActionContext` peer: motions
    /// fire on every `j`, so a native motion (which ignores this) must pay
    /// nothing, and only a plugin motion that actually mints a `tree-snapshot`
    /// resource pays the `Arc` bump. Same reasoning as `path` above.
    ///
    /// Acquired the same instant as `buffer`, so tree and text versions agree
    /// (`plugin-treesitter-seam.md` §7). `None` when the buffer has no parse.
    pub syntax: Option<&'a Arc<dyn std::any::Any + Send + Sync>>,
    /// VM.3c: the last `f` / `F` / `t` / `T`, copied from
    /// [`GrammarEnv::last_find`]. Read by `motion:find-repeat` and its
    /// reverse; every other motion ignores it. `Copy`, so carrying it costs
    /// nothing on the keystroke path.
    pub last_find: Option<LastFind>,
    /// VM.3i: the fold edges `zj` / `zk` step between, copied from
    /// [`GrammarEnv::fold_resolver`]. Borrowed, so a motion that ignores it
    /// pays nothing.
    pub fold_resolver: Option<&'a dyn FoldResolver>,
    /// VM.3d-2: the search `n` / `N` / `*` / `#` repeat, copied from
    /// [`GrammarEnv::last_search`]. Borrowed; every other motion ignores it.
    pub last_search: Option<&'a LastSearch>,
    /// VM.3e: the marks `'x` / `` `x `` jump to, copied from
    /// [`GrammarEnv::marks`]. Borrowed; every other motion ignores it.
    pub marks: Option<&'a dyn MarkResolver>,
    /// VM.3f: the window's lines for `H` / `M` / `L`, copied from
    /// [`GrammarEnv::viewport`].
    pub viewport: Option<&'a dyn ViewportResolver>,
    /// VM.3f: vim's `nostartofline` — `H` / `M` / `L` keep the cursor's column
    /// instead of landing on the first non-blank.
    pub nostartofline: bool,
    /// VM.3g-1: the goal column, copied from [`GrammarEnv::curswant`].
    pub curswant: Option<Curswant>,
    /// VM.3g-2: the display geometry `gj` / `gk` / `g0` / `g$` read.
    pub display: Option<&'a dyn DisplayResolver>,
    /// VM.3f: see [`GrammarEnv::scrolloff`].
    pub scrolloff: u32,
    /// VM.3f: whether this motion is resolving an OPERATOR's target.
    ///
    /// `H` / `L` are adjusted for `scrolloff` "unless an operator is pending"
    /// (`:h H`), so `dH` reaches the window's real top edge while a bare `H`
    /// stops at the margin. Checked in vim 9.2.
    pub operator_pending: bool,
}

/// What a motion's evaluator returned.
#[derive(Debug, Clone, Copy, Default)]
pub struct MotionResult {
    /// Where the cursor lands.
    pub target: Position,
    /// `true` if the motion is linewise (ranges expand to whole lines on
    /// resolution).
    pub linewise: bool,
    /// VM.3c: override [`MotionSpec::exclusive`] for THIS invocation.
    /// `None` — the overwhelming default — means "use the spec's flag".
    ///
    /// ## Why the axis had to move
    ///
    /// `linewise` has always travelled with the RESULT and `exclusive` with
    /// the SPEC, and nothing needed the asymmetry resolved until a motion
    /// existed whose exclusivity is not knowable until it runs. `;` is that
    /// motion: it repeats whatever `f` / `F` / `t` / `T` came last, and vim
    /// gives it that motion's exclusivity — `f` and `t` are inclusive, `F`
    /// and `T` are not. A single flag on the `;` spec has to be wrong half
    /// the time, and it was: `d,` after an `f` deleted one character too
    /// many, because `,` acts as `F` while the spec said inclusive.
    ///
    /// Not on the WIT boundary. A plugin declares exclusivity on its
    /// `MotionSpec`, which is the right place for every motion that knows its
    /// own answer, so `from_wit` decodes this as `None` deliberately rather
    /// than for want of a field to read.
    pub exclusive: Option<bool>,
    /// VM.3d-2: a notice for the user, which the dispatcher echoes alongside
    /// the motion's effect — the search wrap. Not on the WIT boundary: a
    /// plugin motion reports none.
    pub notice: Option<MotionNotice>,
    /// VM.3g-3: override the goal column for THIS invocation, the way
    /// [`Self::exclusive`] overrides the spec's flag. `None` — the
    /// overwhelming default — means "apply the spec's [`CurswantEffect`]".
    ///
    /// ## Why a motion has to be able to say it
    ///
    /// `CurswantEffect` can express "keep the goal", "pin it to the line end"
    /// and "take it from where I landed", and for every motion in vim except
    /// two that is the whole story. `gj` / `gk` are the exception: they aim at
    /// a screen column that the reached display row may be too short to hold,
    /// and vim records **the aim, not the landing**.
    ///
    /// Measured in vim 9.2 (`vimcheck_scroll_curswant.vim`), wrap at 80 over a
    /// 240-char line then a 100-char line:
    ///
    /// ```text
    /// gj -> line 2 row 1            col=80   curswant=80
    /// gj -> line 2 row 2 (CLAMPED)  col=100  curswant=160
    /// ```
    ///
    /// 160 is the column the motion *wanted* — `next_start + goal`, before the
    /// clamp to the row's 100 characters. Recording the landing instead loses
    /// the aim permanently, so a following `j` onto a long line returns to 100
    /// where vim returns to 160.
    ///
    /// `SetFromTarget` cannot express this because the target IS the clamped
    /// landing, and `Keep` cannot because the goal genuinely changes on every
    /// `gj` (it tracks the screen column down the wrapped rows). Only the
    /// motion knows the unclamped aim, so only the motion can report it.
    ///
    /// Not on the WIT boundary, for the same reason `exclusive` is not: a
    /// plugin motion declares its effect on the spec, which is the right place
    /// for every motion that knows its own answer. `from_wit` decodes this as
    /// `None` deliberately rather than for want of a field to read.
    pub curswant: Option<Curswant>,
}

/// Implementation of a motion. Boxed because evaluator closures capture
/// configuration; cheap to call.
type MotionFn = Arc<dyn Fn(&MotionContext) -> GrammarResult<MotionResult> + Send + Sync>;

/// VM.3g-1: vim's `curswant` — the column a vertical motion aims for, which
/// survives passing through a SHORT line. `jj` from column 9 over a 2-column
/// line lands back on 9, not on 2 (vim 9.2, `vimcheck_curswant2.vim`).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Curswant {
    /// Aim for this byte column, clamped to whatever line is reached.
    Col(u32),
    /// vim's MAXCOL: `$` sticks to the END of every line it lands on, so
    /// `$jj` sits at each line's end rather than at a fixed column.
    EndOfLine,
}

/// VM.3g-1: what a motion does to the goal column. A property of the MOTION
/// (vim's `j` always keeps it, `$` always pins it), so it lives on the spec
/// rather than the result — and [`Self::SetFromTarget`] is the default, so
/// every motion that has never heard of `curswant`, plugin motions included,
/// behaves as vim's ordinary motions do.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub enum CurswantEffect {
    /// The landing column becomes the goal: every horizontal motion, and by
    /// the same rule every edit, Insert and yank the host routes through it.
    #[default]
    SetFromTarget,
    /// Aim at the existing goal and leave it untouched: `j` / `k`, and later
    /// `gj` / `gk`, which vim gives the SAME goal column.
    Keep,
    /// Pin to end-of-line: `$`, and later `g$`.
    PinToEnd,
}

/// A registered motion: its evaluator plus the vim properties the
/// dispatcher and host need without running it.
///
/// Registered through [`CommandRegistry::register_motion`] (or
/// [`CommandRegistry::register_plugin_motion`]). The dispatcher runs
/// `apply` for a bare motion (the cursor moves to the result) and for an
/// operator target (the span is cursor..result, shaped by `exclusive` and
/// the result's `linewise`).
///
/// # Examples
///
/// A motion that jumps to the end of the buffer (a simplified `G`):
///
/// ```
/// use std::sync::Arc;
/// use lattice_core::{BufferId, Document};
/// use lattice_grammar::{
///     CancellationToken, CommandInvocation, CommandRegistry, CurswantEffect, Effect, MotionSpec,
///     execute,
/// };
/// use lattice_grammar::registry::MotionResult;
/// use lattice_protocol::position::Position;
///
/// let mut registry = CommandRegistry::new();
/// let id = registry.register_motion(
///     "motion:buffer-end",
///     "Move to the start of the last line.",
///     MotionSpec {
///         jump: true,
///         exclusive: false,
///         curswant: CurswantEffect::default(),
///         args_schema: vec![],
///         apply: Arc::new(|ctx| {
///             let last = ctx.buffer.content_line_count().saturating_sub(1);
///             Ok(MotionResult { target: Position::new(last, 0), ..Default::default() })
///         }),
///     },
/// );
/// assert!(registry.motion_is_jump(id.0));
///
/// let mut doc = Document::from_text("one\ntwo\nthree");
/// let effect = execute(
///     &registry,
///     &mut doc,
///     BufferId(0),
///     Position::ZERO,
///     CommandInvocation::of(id.0),
///     &CancellationToken::never(),
/// )
/// .unwrap();
/// assert!(matches!(effect, Effect::CursorMove(p) if p == Position::new(2, 0)));
/// ```
#[derive(Clone)]
pub struct MotionSpec {
    /// A vim *jump*: the host records the origin in position history (so
    /// `<C-o>` returns) and opens folds at the destination. Read through
    /// [`CommandRegistry::motion_is_jump`].
    pub jump: bool,
    /// Whether the motion's end position is excluded from an operator's span
    /// (`w`, `b`, `0` are exclusive; `e`, `f`, `$` are inclusive). A
    /// [`MotionResult::exclusive`] overrides it per invocation.
    pub exclusive: bool,
    /// VM.3g-1: this motion's effect on the goal column. See [`CurswantEffect`].
    pub curswant: CurswantEffect,
    /// The evaluator. Pure: reads the [`MotionContext`], returns where to go.
    pub apply: MotionFn,
    /// Per-positional-argument metadata (DESIGN.md §B.1). Empty for
    /// motions without args (the common case).
    pub args_schema: Vec<ArgSpec>,
}

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

/// Context passed to an operator's evaluator.
pub struct OperatorContext<'a> {
    /// The document to edit. Native operators apply their edits here
    /// directly (as one undo unit) and report them in the returned
    /// [`Effect`](crate::Effect); plugin operators hold a read-only view and
    /// return an `ApplyEdit` effect instead.
    pub document: &'a mut Document,
    /// CM.3: the buffer the operator is running over — the `target` a plugin
    /// operator names in an `apply-edit` effect.
    ///
    /// Absent until now, and the absence was an asymmetry rather than a
    /// decision, exactly as MR.2 found for [`ExCommandContext::buffer_id`]:
    /// [`ActionContext`] and [`MotionContext`] both carry it, a native
    /// operator never needed it because it mutates `document` in place, and a
    /// PLUGIN operator cannot — it holds a read-only handle and must ask the
    /// host to apply. Without this field a plugin operator can read its range
    /// and never change it, which makes the contribution pointless.
    pub buffer_id: BufferId,
    /// The span to operate on, already resolved from the target or range and
    /// expanded to whole lines when [`Self::linewise`].
    pub range: ProtoRange,
    /// VM.3m: the start of the operated text BEFORE linewise expansion —
    /// `min(cursor, motion target)` for a motion, the object's or selection's
    /// start otherwise, the cursor for a count / current-line / ex range.
    /// vim leaves the cursor here after a yank, which is why the expanded
    /// `range` can't answer: `yk` keeps its column (`k`'s target has it) and
    /// `yy` doesn't move at all, though both expand to whole lines.
    pub origin: Position,
    /// Whether the range was produced by a linewise source (vim's
    /// `Range::CurrentLine` / `Range::Whole`, or a linewise visual
    /// selection). Yank uses this to tag the unnamed register so paste
    /// can do the right thing.
    pub linewise: bool,
    /// The register the operator reads or writes (unnamed when none typed).
    pub register: Register,
    /// The count, `1` when none was typed. Usually already folded into the
    /// span by target resolution (`3dw`), so most operators ignore it.
    pub count: Count,
    /// The operator's own arguments, e.g. the captured char for `r{char}` or
    /// surround's `ys{motion}{char}`.
    pub args: Args,
    /// Cooperative cancellation handle (DESIGN.md §5.2.5). Operators
    /// that scan large ranges (`d_whole`, `gU` over a big visual
    /// block) should poll `cancel.check()?` between rows; on a
    /// flipped token return [`crate::CommandError::Cancelled`].
    pub cancel: &'a crate::CancellationToken,
    /// IN.0: one level of indentation, resolved by the host. Only the
    /// indent operators (`>` / `<`) read it.
    pub indent: lattice_core::IndentUnit,
    /// IN.7: per-line indent depth for the `=` operator, injected by
    /// the host. `None` (the default) means `=` has no structural
    /// source and leaves lines alone -- the same graceful-degradation
    /// contract every other env field carries.
    pub indent_resolver: Option<&'a dyn IndentResolver>,
    /// RF.2: the buffer's `textwidth`, resolved by the host (including
    /// any `:setlocal`). Read by the reflow operator (`gq` / `gw`).
    ///
    /// Not an `Option`, for the same reason [`Self::indent`] is not:
    /// there is always a defensible answer, and
    /// `WrapWidth::default()` is the registered option default, so a
    /// caller that never resolved config reflows like an unconfigured
    /// buffer rather than not at all.
    pub textwidth: lattice_core::WrapWidth,
    /// RF.2: the buffer language's line-comment leader, so reflow can
    /// keep a comment block's marker. `None` for prose languages and
    /// for any language whose comment syntax is undeclared -- reflow
    /// then uses indentation alone, which is the right answer there.
    pub comment_syntax: Option<&'a CommentSyntax>,
    /// RF.5b: for each intent, whether the buffer's chain resolves to the
    /// **native** engine.
    ///
    /// The host resolves the chain — it owns the LSP client and the
    /// `PATH` probe — and hands down the one bit the operator needs:
    /// "do it yourself, or hand me the range". `true` (the default) is
    /// the shipped configuration, so the common path never delegates.
    pub native_format: NativeFormatIntents,
}

/// RF.5b: which formatting intents the buffer handles natively.
///
/// A struct rather than two loose bools so a third intent cannot be added
/// to one call site and forgotten at the other.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct NativeFormatIntents {
    /// `=` (`format.indent`) resolves to the native tree-sitter indenter.
    pub indent: bool,
    /// `gq` / `gw` (`format.reflow`) resolve to the native reflow engine.
    pub reflow: bool,
}

impl Default for NativeFormatIntents {
    /// Native for everything — the shipped chains, and the answer a
    /// hand-built env should get.
    fn default() -> Self {
        NativeFormatIntents {
            indent: true,
            reflow: true,
        }
    }
}

/// An operator's evaluator returns the full `Effect` it produced. Most
/// operators return `Effect::Edits(...)`; `change` adds a mode transition
/// via `Effect::Many(...)`; `yank` returns `Effect::Yank { ... }`. The
/// dispatcher passes the result through unchanged -- composition is
/// expressed in the Effect, not via flags on the spec.
type OperatorFn =
    Arc<dyn Fn(&mut OperatorContext) -> GrammarResult<crate::effect::Effect> + Send + Sync>;

/// A registered operator: its evaluator plus how the dispatcher should
/// feed it spans.
///
/// Registered through [`CommandRegistry::register_operator`] (or
/// [`CommandRegistry::register_plugin_operator`]). The dispatcher resolves
/// the invocation's range or target to a span, builds an
/// [`OperatorContext`], and returns whatever `apply` returns unchanged.
#[derive(Clone)]
pub struct OperatorSpec {
    /// Declared dot-repeatability. Currently informational: nothing reads it
    /// yet (`.` repeat is decided host-side).
    pub repeatable: bool,
    /// The evaluator. Runs once per span (once per row for a blockwise
    /// selection when [`Self::blockwise_per_row`]).
    pub apply: OperatorFn,
    /// Per-positional-argument metadata (DESIGN.md §B.1). Empty for
    /// operators without args (the common case).
    pub args_schema: Vec<ArgSpec>,
    /// Block-visual dispatch hint. `true` (the default for v1
    /// rectangle ops -- `d`, `y`, `c`) means a blockwise visual
    /// selection routes per-row: each row's column slice gets its
    /// own ProtoRange and `apply` runs once per row, with results
    /// merged into a single Blockwise yank + concatenated Edits.
    /// `false` (linewise-style ops -- `>`, `<`, `gU`, `gu`, `g~`)
    /// means a blockwise visual collapses to a single contiguous
    /// range covering anchor..head; `apply` runs once. This keeps
    /// the operator a single undo unit instead of N per-row units.
    pub blockwise_per_row: bool,
    /// When true (e.g. surround's `ys{motion}{char}`), the operator's
    /// keymap bindings append `ChordPattern::CharLiteral` after every
    /// motion path so a wrapping character is captured as `Args::Char`
    /// by the wildcard resolution. Default false.
    pub post_motion_char: bool,
}

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

/// IN.7: how deep should this line sit?
///
/// The `=` operator needs a per-line indent level, which only the
/// tree-sitter engine can compute — and this crate is deliberately
/// tree-sitter-agnostic (see its `Cargo.toml`). Same shape and same
/// reason as [`ScopeResolver`] above: the grammar declares the
/// question, the host injects something that can answer it, and
/// nothing tree-shaped crosses the boundary.
///
/// `None` from `levels_for_line` means "no answer for this row" — no
/// tree, no `indents.scm` for the language, a parse error, or a
/// position inside a string. The operator leaves such lines untouched
/// rather than guessing, so `=` over a range containing a broken
/// region reindents what it understands and does not mangle the rest.
pub trait IndentResolver {
    /// Indent depth in levels (not columns) for `line`.
    fn levels_for_line(&self, line: u32) -> Option<i32>;
}

/// VM.3i: where `zj` / `zk` find the next fold edge.
///
/// Folds, and which of them are visible, are host state: the fold table and
/// `foldenable` live on the editor, and "a closed fold is counted as one fold"
/// needs the host's fold index. So the grammar asks this, the way `=` asks
/// [`IndentResolver`], and the motion itself stays a pure function of the
/// answer.
///
/// `None` from `fold_edge` means there's no edge that way, and the motion
/// leaves the cursor where it is, as vim does.
pub trait FoldResolver {
    /// The nearest visible fold START after `line` (`forward`), or the
    /// nearest visible fold END before it (`!forward`).
    fn fold_edge(&self, line: u32, forward: bool) -> Option<u32>;
}

/// VM.3e: the mark table `'x` / `` `x `` read, so they can be motions. The
/// host owns the marks (`m` writes them); the grammar only asks where one is.
/// `None` means the mark isn't set, which fails the motion with E20.
pub trait MarkResolver {
    /// Where mark `name` is set, or `None` when it is not.
    fn mark(&self, name: char) -> Option<Position>;
}

/// The host's table is a plain map, so it is its own resolver: a read-only
/// buffer borrows it as is, and the actor path carries an `Arc` of a clone.
impl MarkResolver for std::collections::HashMap<char, Position> {
    fn mark(&self, name: char) -> Option<Position> {
        self.get(&name).copied()
    }
}

/// VM.3f: which line of the window `H` / `M` / `L` mean. The layout — folds,
/// row heights, window size — stays on the host; the grammar only asks.
pub trait ViewportResolver {
    /// `Top`: the `count`-th line from the top (`H`); `Bottom`: the `count`-th
    /// from the bottom (`L`); `Middle`: the middle line (`M`, count ignored).
    /// `None` when the window shows nothing.
    fn viewport_line(&self, pos: crate::app_effect::ViewportPos, count: u32) -> Option<u32>;
}

/// VM.3f: the window's lines, top to bottom, each with its height in
/// line-heights (1.0 for an ordinary row). The host builds it from the walk it
/// paints with; this type owns vim's rule for which of them `H` / `M` / `L`
/// mean, so the keyboard motion and the host's `JumpViewport` action answer
/// from one place. Checked in vim 9.2: a count past the window clamps to the
/// far edge, and `M` is top + (lines shown − 1) / 2 — half the lines SHOWN, so
/// a short buffer's middle, not the window's.
#[derive(Debug, Clone, Default)]
pub struct ShownLines(pub Vec<(u32, f32)>);

impl ViewportResolver for ShownLines {
    fn viewport_line(&self, pos: crate::app_effect::ViewportPos, count: u32) -> Option<u32> {
        use crate::app_effect::ViewportPos;
        let lines = &self.0;
        let last = lines.len().checked_sub(1)?;
        let n = (count.max(1) - 1) as usize;
        Some(match pos {
            ViewportPos::Top => lines[n.min(last)].0,
            ViewportPos::Bottom => lines[last - n.min(last)].0,
            ViewportPos::Middle => {
                // (shown − 1) / 2, spent in line-heights so a tall row pulls
                // `M` up to the line actually drawn mid-window.
                let budget = (lines.iter().map(|l| l.1).sum::<f32>() - 1.0) / 2.0;
                let mut used = 0.0;
                let mut at = lines[0].0;
                for &(line, cost) in &lines[1..] {
                    if used + cost > budget {
                        break;
                    }
                    used += cost;
                    at = line;
                }
                at
            }
        })
    }
}

/// VM.3g-2: what the DISPLAY looks like, for `gj` / `gk` / `g0` / `g$`. Soft
/// wrap is a rendering decision — the wrap width, and how many rows a line
/// takes once tabs and wide characters are measured — so the grammar asks
/// rather than computes, exactly as it does for folds and the viewport.
pub trait DisplayResolver {
    /// Soft-wrap width in columns, or `0` when `wrap` is off — which degrades
    /// `gj` to `j` and `g0` to `0`, as vim does.
    fn wrap_width(&self) -> u32;
    /// How many display rows `line` occupies. `1` when wrap is off.
    fn segments(&self, line: u32) -> u32;
}

/// Resolves a tree-sitter scope near the cursor, for the structural text
/// objects (`af` / `ac` / `aa` / …) and structural motions (`]f` / `[c` / …).
///
/// Defined here so `lattice-grammar` stays free of any tree-sitter
/// dependency: the host implements it (backed by the buffer's
/// `SyntaxSnapshot`) and threads it in through [`GrammarEnv::scope_resolver`]
/// to [`TextObjectContext`] and [`MotionContext`]. Introduced in N.1.4a.
pub trait ScopeResolver {
    /// The innermost node at `(line, col_byte)` whose capture name ends with
    /// `suffix` (e.g. `"function.outer"`), as a byte-precise half-open
    /// `[start, end)` [`ProtoRange`] — byte columns, not just rows, so
    /// intra-line objects like `aa` / `ia` are charwise-accurate. End is
    /// exclusive, matching tree-sitter node ranges and the operator slice
    /// convention. `None` when there is no parse or no match.
    fn scope_at(&self, line: u32, col_byte: u32, suffix: &str) -> Option<ProtoRange>;

    /// The `count`-th node whose capture name ends with `suffix`, in `dir`,
    /// targeting the node's `boundary`. Respects the enclosing-object rule
    /// (see treesitter-motions.md §4.1): `(Forward, Start)` / `(Backward, End)`
    /// skip the object the cursor is inside; `(Backward, Start)` / `(Forward, End)`
    /// may land on the current object's own boundary. Returns the target
    /// position, or `None` (no tree / no match / fewer than `count` candidates).
    fn scope_toward(
        &self,
        line: u32,
        col_byte: u32,
        suffix: &str,
        dir: NavDir,
        boundary: NavBoundary,
        count: u32,
    ) -> Option<Position>;
}

/// Direction of travel for a structural motion. `Forward` scans toward EOF,
/// `Backward` toward BOF.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NavDir {
    /// Toward the end of the buffer.
    Forward,
    /// Toward the start of the buffer.
    Backward,
}

/// Which boundary of the target node the motion lands on.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NavBoundary {
    /// Land on the node's first byte.
    Start,
    /// Land on the node's last byte.
    End,
}

/// N.1.6 (2026-06-10): per-buffer comment-leader descriptor for the
/// comment text objects (`aC` / `iC`). Commentstring-driven (NOT
/// tree-sitter) so it works for any language with a known leader, even
/// without a parse tree. The host populates it from the active buffer's
/// language (`Lang::comment_syntax`); `None` (or `line: None`) means the
/// comment objects resolve nothing (graceful operator no-op).
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct CommentSyntax {
    /// Line-comment leader, e.g. `"//"` (rust / js) or `"#"` (python).
    pub line: Option<String>,
    /// Block-comment delimiters, e.g. `("/*", "*/")`. Reserved for a
    /// follow-up; v1 comment objects use `line` only.
    pub block: Option<(String, String)>,
}

/// `f` / `F` / `t` / `T` — which direction, and whether the target character
/// is included.
///
/// VM.3c moved this down from `lattice_host::action` so `;` and `,` can be
/// MOTIONS. They have to be: vim composes them (`d;` repeats the last find
/// under an operator) and VM.1's derivation only mirrors motions into Visual,
/// so as actions they were unreachable from a selection and from an operator
/// both. The host re-exports this name, so no call site moved.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FindKind {
    /// `f` — forward to the next occurrence, landing ON it.
    Forward,
    /// `F` — backward to the previous occurrence, landing ON it.
    Backward,
    /// `t` — forward, landing one byte BEFORE it.
    TillForward,
    /// `T` — backward, landing one byte AFTER it.
    TillBackward,
}

impl FindKind {
    /// The kind `,` repeats — this one, reversed. `;` repeats `self`.
    ///
    /// A method rather than a `match` at the two call sites, because the
    /// pairing is a property of the enum: adding a fifth variant should break
    /// here, once, rather than silently repeat in the wrong direction.
    pub fn reversed(self) -> Self {
        match self {
            FindKind::Forward => FindKind::Backward,
            FindKind::Backward => FindKind::Forward,
            FindKind::TillForward => FindKind::TillBackward,
            FindKind::TillBackward => FindKind::TillForward,
        }
    }
}

/// The last `f` / `F` / `t` / `T` the user ran, which is all `;` and `,` need
/// to repeat it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct LastFind {
    /// Which of the four find motions it was.
    pub kind: FindKind,
    /// The character searched for.
    pub target: char,
}

/// VM.3d-2: the last completed `/` / `?` / `*` / `#` search, which is all `n`
/// and `N` need to repeat it. Moved here from the host (which re-exports the
/// name, so no call site moved) for the reason [`LastFind`] was: `n` is a
/// motion now, and the state it repeats has to reach the grammar.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LastSearch {
    /// The pattern as the user typed it (regex syntax, compiled with
    /// `fancy-regex`).
    pub pattern: String,
    /// The direction the search ran: `n` repeats it, `N` reverses it.
    pub direction: crate::modal::SearchDirection,
}

/// VM.3d-2: something a motion wants the user told, alongside where it moved.
/// `Copy`, so [`MotionResult`] stays `Copy`; the dispatcher renders the text.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MotionNotice {
    /// vim's "search hit BOTTOM, continuing at TOP".
    SearchHitBottom,
    /// vim's "search hit TOP, continuing at BOTTOM".
    SearchHitTop,
}

/// The per-dispatch environment: everything the host knows that a
/// command's `apply` may need but the grammar layer cannot derive for
/// itself. Bundled into ONE value so the dispatch seam carries a single
/// env rather than a widening parameter list (the long-term-fit choice
/// over parallel params). `Copy`; `default()` is the no-input case, and
/// commands that read nothing from the env (`iw`, `ap`, `i{`) are
/// unaffected by what it carries.
///
/// It has widened twice, and the name followed on the second:
///
/// - **N.1.6 (2026-06-10)** introduced it as a text-object-only env —
///   the tree-sitter `scope_resolver` (`af`/`ac`, N.1.4) and the
///   `comment_syntax` (`aC`/`iC`).
/// - **TS.1** added the tree-sitter `syntax` snapshot for **actions**
///   (borrowed `Arc<dyn Any>` so `execute_action` can `Arc::clone` it
///   into the owned `ActionContext::syntax` — a `&dyn Any` alone can't
///   recover the `Arc`), which already made `TextObjectEnv` a misnomer.
/// - **IN.0** renamed it to `GrammarEnv` on adding a field read by
///   **operators** (`>` / `<`), which would have made the old name
///   actively misleading rather than merely stale.
#[derive(Clone, Copy, Default)]
pub struct GrammarEnv<'a> {
    /// Tree-sitter scope lookup for structural text objects and motions.
    /// `None` on buffers with no parse.
    pub scope_resolver: Option<&'a dyn ScopeResolver>,
    /// The buffer language's comment leader, for `aC` / `iC` and reflow.
    /// `None` when the language declares none.
    pub comment_syntax: Option<&'a CommentSyntax>,
    /// TS.1: the per-dispatch tree-sitter snapshot, type-erased and borrowed so
    /// it stays `Copy`. `execute_action` clones it into `ActionContext::syntax`;
    /// motions / text-objects / operators ignore it (they read
    /// `scope_resolver`). `None` = no parse.
    pub syntax: Option<&'a Arc<dyn std::any::Any + Send + Sync>>,
    /// IN.0: one level of indentation, resolved by the host from
    /// `shiftwidth` / `expandtab` / `tabstop` (including any
    /// `:setlocal` override). Read by the `>` / `<` operators.
    ///
    /// Not an `Option`: there is always a defensible answer, and
    /// `IndentUnit::default()` is the registered option defaults, so a
    /// caller that never resolved config indents like an unconfigured
    /// buffer instead of like nothing. That keeps the ~40 test and
    /// plugin call sites that build a `default()` env working without
    /// each having to care about indentation.
    pub indent: lattice_core::IndentUnit,
    /// IN.7: per-line indent depth for the `=` operator, injected by
    /// the host. `None` (the default) means `=` has no structural
    /// source and reindents nothing -- the same graceful-degradation
    /// contract every other env field carries.
    pub indent_resolver: Option<&'a dyn IndentResolver>,
    /// RF.2: the buffer's `textwidth`, resolved by the host (including
    /// any `:setlocal`). Read by the reflow operator.
    ///
    /// `WrapWidth` rather than a bare `usize` precisely so this struct
    /// can keep its DERIVED `Default`: a `usize` would default to `0`,
    /// which is not a column anything wraps at, and all ~40 hand-built
    /// `default()` envs would silently get a reflow that does nothing.
    pub textwidth: lattice_core::WrapWidth,
    /// RF.5b: which intents this buffer handles natively. See
    /// [`NativeFormatIntents`].
    pub native_format: NativeFormatIntents,
    /// OS.2: the **active region** — the Visual/Select selection extent,
    /// normalised so `start <= end`. `None` in Normal mode and on every
    /// non-chord firing path.
    ///
    /// Injected by the host from the SAME resolver that fills
    /// `lattice_mode::ActionContext::selection` (MG.18e), rather than
    /// re-derived here from the document's selections. That is deliberate: two
    /// answers to "what is the region" is precisely the drift OS.3 spent a fix
    /// round removing from `Checkboxes`, and a plugin action seeing a different
    /// region than a native mode handler reached the same way is the same bug
    /// wearing a boundary.
    ///
    /// `None` (the default) means no region, so the ~40 call sites that build a
    /// `default()` env keep behaving exactly as they did.
    pub selection: Option<lattice_protocol::position::Range>,
    /// VM.3c: the last `f` / `F` / `t` / `T`, so `;` and `,` can be motions
    /// rather than host actions.
    ///
    /// Carried here for the reason `syntax` and `selection` had to be: `;`
    /// reaches the grammar through the ACTOR path on every real keystroke, so
    /// a field missing here is a field the motion never sees no matter how
    /// well the direct path is tested. `None` — the default, and the state
    /// before the user has pressed any `f` — makes `;` a no-op, which is what
    /// vim does.
    pub last_find: Option<LastFind>,
    /// VM.3i: the buffer's fold edges, so `zj` / `zk` can be motions.
    ///
    /// Carried here for the reason `last_find` is: `zj` reaches the grammar
    /// through the ACTOR path on every real keystroke, so a field missing
    /// here is one the motion never sees. `None` — no folds, or a caller
    /// with no fold table — leaves `zj` / `zk` where they are.
    pub fold_resolver: Option<&'a dyn FoldResolver>,
    /// VM.3d-2: the last search, so `n` / `N` / `*` / `#` can be motions.
    /// Carried for the reason `last_find` is: they reach the grammar through
    /// the ACTOR path on every real keystroke. `None` makes `n` fail with
    /// E35, as vim does before any search.
    pub last_search: Option<&'a LastSearch>,
    /// VM.3e: the mark table, so `'x` / `` `x `` can be motions. Carried for
    /// the reason `last_search` is. `None` makes every mark unset (E20).
    pub marks: Option<&'a dyn MarkResolver>,
    /// VM.3f: the lines the window shows, so `H` / `M` / `L` can be motions.
    /// `None` — no window, or an invocation that isn't one of them — makes
    /// them fail without moving.
    pub viewport: Option<&'a dyn ViewportResolver>,
    /// VM.3f: `!startofline`. Named for the vim option that turns the rule
    /// OFF so that `Default` (false) is vim's default.
    pub nostartofline: bool,
    /// VM.3g-1: the goal column `j` / `k` aim for. `None` — nothing has set one
    /// yet — means "use the cursor's own column", which is what the first `j`
    /// after any edit does in vim.
    pub curswant: Option<Curswant>,
    /// VM.3g-2: display geometry for `gj` / `gk` / `g0` / `g$`. `None` — no
    /// renderer has reported one — leaves them behaving as `j` / `k` / `0` /
    /// `$`, which is also what they do with `wrap` off.
    pub display: Option<&'a dyn DisplayResolver>,
    /// VM.3g-3: where a motion's [`MotionResult::curswant`] override is
    /// reported back to the caller. `None` — the default — discards it, which
    /// is right for every caller that does not maintain a goal column.
    ///
    /// The symmetric partner of [`Self::curswant`] above: that field carries
    /// the goal INTO the motion, this one carries the motion's answer back
    /// out. It is a slot rather than a return value because a motion's effect
    /// reaches the host as an `Effect::CursorMove`, a WIT type and the wrong
    /// place for per-dispatch host state — `exclusive` and `notice` are kept
    /// off that boundary for the same reason.
    ///
    /// A shared slot rather than `&mut` so `GrammarEnv` stays `Copy`, which
    /// the tree-sitter snapshot field above already depends on; a `Mutex`
    /// rather than a `Cell` because the owning `DispatchEnv` crosses the
    /// `Document` trait into an async `Pending<Effect>` and must stay
    /// `Send + Sync`. The lock is uncontended — one motion writes it once per
    /// dispatch, on the same thread that reads it.
    pub curswant_out: Option<&'a std::sync::Mutex<Option<Curswant>>>,
    /// VM.3f: `scrolloff`, the margin `H` / `L` keep from the window's edges.
    /// `0` — the default — leaves them on the first and last lines shown,
    /// which is vim with `scrolloff=0`.
    pub scrolloff: u32,
}

/// Context passed to a text-object's evaluator.
pub struct TextObjectContext<'a> {
    /// The buffer text the object reads.
    pub buffer: &'a Buffer,
    /// The cursor the object is evaluated around.
    pub at: Position,
    /// The count, `1` when none was typed (`2aw`, `2i(`).
    pub count: Count,
    /// The object's own arguments.
    pub args: Args,
    /// Cooperative cancellation handle (DESIGN.md §5.2.5). Most
    /// text objects are O(line); polling rarely matters. Tag /
    /// paragraph / sentence objects that walk further can poll
    /// `cancel.check()?` on their inner loops.
    pub cancel: &'a crate::CancellationToken,
    /// N.1.4a: tree-sitter scope resolver for the structural text
    /// objects (`af` / `ac` / …), injected by the host (backed by the
    /// buffer's `SyntaxSnapshot`). `None` for buffers with no syntax —
    /// the structural objects then resolve nothing; the classic
    /// objects (`iw`, `ap`, `i{`) never read it.
    pub scope_resolver: Option<&'a dyn ScopeResolver>,
    /// N.1.6: comment-leader descriptor for the comment objects
    /// (`aC` / `iC`), injected by the host from the active buffer's
    /// language. `None` (or `line: None`) ⇒ the comment objects resolve
    /// nothing. Only `aC` / `iC` read it.
    pub comment_syntax: Option<&'a CommentSyntax>,
    /// OM.6b: the file the object's buffer is backed by — the borrowed peer of
    /// [`MotionContext::path`], for the same reason.
    pub path: Option<&'a std::path::Path>,
    /// OT.1: the type-erased tree-sitter snapshot — the borrowed peer of
    /// [`MotionContext::syntax`], for the same reason, and carrying the same
    /// version-agreement guarantee.
    ///
    /// Distinct from `scope_resolver` above rather than replacing it: the
    /// resolver answers "what scope encloses this point" for the native
    /// structural objects, while this hands a plugin the whole tree to query.
    /// A plugin object resolving a subtree needs the second, not the first.
    pub syntax: Option<&'a Arc<dyn std::any::Any + Send + Sync>>,
}

type TextObjectFn = Arc<dyn Fn(&TextObjectContext) -> GrammarResult<ProtoRange> + Send + Sync>;

/// A registered text object: an evaluator that returns the span around a
/// position.
///
/// Registered through [`CommandRegistry::register_text_object`] (or
/// [`CommandRegistry::register_plugin_text_object`]). Used as an operator
/// target (`diw`) and to set a Visual selection (`viw`).
#[derive(Clone)]
pub struct TextObjectSpec {
    /// The evaluator: returns the selected span as a half-open range.
    pub apply: TextObjectFn,
    /// Per-positional-argument metadata (DESIGN.md §B.1). Empty for
    /// text objects without args (the common case).
    pub args_schema: Vec<ArgSpec>,
}

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

/// Context handed to an ex-command's evaluator. Mirrors the shape passed
/// to motion / operator / text-object specs but adds the `bang` bit and
/// drops direct document mutation: ex-commands describe their work by
/// returning an [`crate::effect::Effect`], which the host applies.
///
/// Owns a [`crate::CancellationToken`] (not a borrow) so apply
/// closures can hold it across `Box::new(move |ctx| ...)`
/// boundaries without lifetime gymnastics. The actor flips a clone
/// when cancellation arrives.
pub struct ExCommandContext {
    /// Whether the command was typed with a trailing `!` (`:q!`).
    pub bang: bool,
    /// Arguments produced by the spec's [`ExCommandSpec::parse_args`].
    pub args: Args,
    /// The line range typed before the command (`:%s`, `:1,5…`), unresolved;
    /// `None` when there was none. The command resolves it itself.
    pub range: Option<crate::range::Range>,
    /// The register named in the invocation, unnamed by default.
    pub register: Register,
    /// The count, `1` when none was given.
    pub count: Count,
    /// The buffer the `:` line was submitted from (MR.2) — the same
    /// fact [`ActionContext::buffer_id`] carries, filled from the same
    /// place in [`crate::dispatcher::execute`].
    ///
    /// It was absent, and the absence was an asymmetry rather than a
    /// decision: vim's ex-commands are buffer-scoped by definition
    /// (`:w`, `:%s`, `:bd`), the `:` line is a parser front-end onto the
    /// one dispatcher (design §5.2.1), and a command reached that way
    /// was seeing strictly less than the same command reached by a
    /// chord. `:magit-status` is what found it: it must open the
    /// repository of the buffer you are looking at, and via `:` it could
    /// not name that buffer at all.
    ///
    /// Deliberately just the id: an ex-command that needs the buffer's
    /// text, path or name resolves it through a handle it captured at
    /// boot (`SubsystemBoot::buffer_store`), which keeps this context
    /// free of services and keeps `lattice-grammar` unaware of them.
    pub buffer_id: BufferId,
    /// OC.10: where the caret sits when the `:` line is submitted — the four
    /// fields below are exactly the ones [`ActionContext`] already carries, and
    /// they are here for the reason `buffer_id` above is.
    ///
    /// MR.2 made that argument for the id: "a command reached that way was
    /// seeing strictly less than the same command reached by a chord". It is the
    /// same argument, and stopping at the id left it half-made. A *plugin*
    /// ex-command felt it hardest: `apply-ex-command` returns `list<effect>`,
    /// and `Effect::ApplyEdit` names a target buffer the guest had no way to
    /// obtain — so the seam offered an effect vocabulary a guest structurally
    /// could not use. `:org-clock-in` is what found it.
    ///
    /// Native ex-commands ignore all four; they cost an `Arc` bump each.
    pub cursor: Position,
    /// A point-in-time view of the buffer the `:` line was submitted from.
    /// O(1) rope clone (Arc-shared nodes), as on [`ActionContext::buffer`].
    pub buffer: Buffer,
    /// The file behind that buffer, so a plugin's `document` handle can answer
    /// `path()`. An `Arc` bump per dispatch, `None` for a buffer with no file.
    pub path: Option<std::sync::Arc<std::path::PathBuf>>,
    /// The per-dispatch tree snapshot, type-erased for the same layering reason
    /// [`ActionContext::syntax`] is. Cloned at the same instant as `buffer`, so
    /// tree and text agree on version (§7).
    pub syntax: Option<Arc<dyn std::any::Any + Send + Sync>>,
    /// Cooperative cancellation handle (DESIGN.md §5.2.5); owned so a
    /// closure can keep it.
    pub cancel: crate::CancellationToken,
}

/// Parser callback for an ex-command. The host hands the rest of the
/// command line (everything after the command word and the optional `!`)
/// plus the `bang` bit; the callback returns typed [`Args`].
type ExParseFn = Arc<dyn Fn(&str, bool) -> GrammarResult<Args> + Send + Sync>;

/// Evaluator callback. Returns the [`Effect`] the host should commit.
type ExApplyFn =
    Arc<dyn Fn(&ExCommandContext) -> GrammarResult<crate::effect::Effect> + Send + Sync>;

/// How the user types this command on the `:` line. The default
/// (`Keyword`) covers most commands -- `:write`, `:quit`, `:set
/// number`. `Delimiter` is for the small family of commands whose
/// arguments are interleaved with delimiters: `:s/pat/repl/`,
/// `:g/pat/body`, `:v/pat/body`. The keyword form (`:ex:substitute`,
/// `:ex:global`) for these is intentionally a hard error -- the
/// front-end parser routes them via `try_parse_substitute` /
/// `try_parse_global`. UI surfaces (completion, command palette)
/// hide `Delimiter` commands because there's no useful keyword-form
/// completion for them; the user types the delimiter directly.
// PL8.F: no longer `Copy` — the `hint` became `Cow<'static, str>` (a plugin
// delimiter command's hint crosses WIT as an owned string and must free on
// unregister). Consumers that bound it by value now bind by reference.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub enum SurfaceForm {
    /// Type the command word, optionally with `!`, then args
    /// separated by whitespace. The default for most commands.
    #[default]
    Keyword,
    /// Type a delimiter prefix followed by a body. The keyword form
    /// errors with a redirect message; the embedded `hint` is the
    /// canonical syntax shown in that error (`:s/pat/repl/`,
    /// `:g/pat/body`).
    Delimiter {
        /// The canonical syntax shown in the redirect error and in help,
        /// e.g. `:s/pat/repl/`.
        hint: std::borrow::Cow<'static, str>,
    },
}

/// A registered ex-command: how the `:` line parses it and what it
/// returns.
///
/// Registered through [`CommandRegistry::register_ex_command`] (or
/// [`CommandRegistry::register_plugin_ex_command`]). The `:` front-end (in
/// `lattice-host`) resolves the typed word to a registry name, rejects a
/// `!` the spec does not accept, calls [`Self::parse_args`] on the rest of
/// the line, and dispatches the resulting invocation. `apply` receives an
/// [`ExCommandContext`] and returns an [`Effect`](crate::Effect) — it never
/// performs I/O itself.
///
/// # Examples
///
/// ```
/// use std::sync::Arc;
/// use lattice_core::{BufferId, Document};
/// use lattice_grammar::{
///     Args, CancellationToken, CommandInvocation, CommandRegistry, EchoLevel, Effect,
///     ExCommandSpec, LatencyClass, SurfaceForm, execute,
/// };
/// use lattice_protocol::position::Position;
///
/// let mut registry = CommandRegistry::new();
/// let id = registry.register_ex_command(
///     "ex:greet",
///     "Echo a greeting (`:greet [name]`).",
///     ExCommandSpec {
///         latency_class: LatencyClass::Reflex,
///         accepts_bang: false,
///         accepts_range: false,
///         parse_args: Arc::new(|rest, _bang| {
///             Ok(match rest.trim() {
///                 "" => Args::None,
///                 name => Args::String(name.to_string()),
///             })
///         }),
///         apply: Arc::new(|ctx| {
///             let who = match &ctx.args {
///                 Args::String(s) => s.as_str(),
///                 _ => "world",
///             };
///             Ok(Effect::Echo { level: EchoLevel::Info, text: format!("hello, {who}") })
///         }),
///         args_schema: vec![],
///         surface_form: SurfaceForm::Keyword,
///     },
/// );
///
/// let spec = registry.ex_command_spec(id.0).unwrap();
/// let args = (spec.parse_args)(" lattice", false).unwrap();
/// let mut doc = Document::from_text("");
/// let effect = execute(
///     &registry,
///     &mut doc,
///     BufferId(0),
///     Position::ZERO,
///     CommandInvocation::of(id.0).with_args(args),
///     &CancellationToken::never(),
/// )
/// .unwrap();
/// assert!(matches!(effect, Effect::Echo { text, .. } if text == "hello, lattice"));
/// ```
#[derive(Clone)]
pub struct ExCommandSpec {
    /// Latency class declaration (DESIGN.md §5.2.5). Most ex-commands
    /// stay [`crate::command::LatencyClass::Reflex`] (the default) --
    /// they're cheap state mutations. File I/O (`:write`, `:edit`)
    /// and help-buffer builders (`:describe-*`, `:apropos`,
    /// `:keymap`) declare [`crate::command::LatencyClass::Display`]
    /// so future cancellation / deadline machinery treats them with
    /// the right budget.
    pub latency_class: crate::command::LatencyClass,
    /// Whether the parser should accept a trailing `!` after the command
    /// word. If `false`, `:cmd!` parses as an unknown command.
    pub accepts_bang: bool,
    /// Whether the parser should accept an ex-style line range (`1,5cmd`,
    /// `'a,'bcmd`, ...). v1 only honours `Whole` and `CurrentLine`; this
    /// flag is the migration knob for richer range parsing.
    pub accepts_range: bool,
    /// Parses everything after the command word (and `!`) into [`Args`].
    /// Receives the bang bit so `!` can change the grammar.
    pub parse_args: ExParseFn,
    /// The evaluator: packages the invocation into an [`Effect`](crate::Effect).
    pub apply: ExApplyFn,
    /// Per-positional-argument metadata (DESIGN.md §B.1). Drives palette
    /// forms, missing-arg prompts, completion, validation, and
    /// `:describe-command` output. Empty for commands taking no
    /// structured args (`:q`, `:noh`).
    pub args_schema: Vec<ArgSpec>,
    /// User-facing surface form. Drives whether completion / palette
    /// list this command. Defaults to [`SurfaceForm::Keyword`].
    pub surface_form: SurfaceForm,
}

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

/// Doc string for an auto-generated `:<mode-name>` mode-toggle ex-command —
/// shared so native and plugin modes read identically in `:describe-command`.
pub const MODE_TOGGLE_COMMAND_DOC: &str = "Toggle the mode on the active buffer (auto-generated; see `:help modes` for \
     the full mode-system overview).";

/// Build the auto-generated `:<mode-name>` mode-toggle ex-command spec. The
/// `apply` returns [`crate::effect::Effect::ToggleMode`]; the host routes that
/// to `toggle_mode_by_name`, flipping the mode on the active buffer. Shared by
/// boot (native modes, `register_mode_toggle_commands`) AND the plugin
/// modes-seam drain, so a plugin-registered mode gets an IDENTICAL `:<mode>`
/// toggle surface. The caller registers it under the right provenance: `Builtin`
/// for native modes; `SourceLayer::Plugin(id)` for plugin modes, so unload
/// reverses it. Takes no arguments.
pub fn mode_toggle_ex_command_spec(mode_name: &str) -> ExCommandSpec {
    let mode = mode_name.to_string();
    ExCommandSpec {
        latency_class: crate::command::LatencyClass::Reflex,
        accepts_bang: false,
        accepts_range: false,
        parse_args: std::sync::Arc::new(|s: &str, _bang: bool| {
            if s.trim().is_empty() {
                Ok(crate::args::Args::None)
            } else {
                Err(crate::error::CommandError::BadArgs(
                    "mode toggle takes no arguments".into(),
                ))
            }
        }),
        apply: std::sync::Arc::new(move |_ctx| {
            Ok(crate::effect::Effect::ToggleMode {
                mode_name: mode.clone(),
            })
        }),
        args_schema: Vec::new(),
        surface_form: SurfaceForm::Keyword,
    }
}

/// Context passed to a free-form action's evaluator. Mirrors
/// [`ExCommandContext`]'s shape (no document mutation; the App
/// applies the returned [`crate::effect::Effect`]) but omits the
/// `bang` bit -- chord-bound actions never carry one. The
/// `register` / `count` slots flow the count and register prefixes
/// the user typed before the chord (vim's `3"+yy`-style); most
/// actions ignore them.
pub struct ActionContext {
    /// The action's arguments; usually [`Args::None`].
    pub args: Args,
    /// The `"x` prefix typed before the chord, unnamed by default.
    pub register: Register,
    /// The count typed before the chord, `1` by default.
    pub count: Count,
    /// Where the caret sits when the action fires (AP.0.1) — the
    /// action's equivalent of `MotionContext::from`. Native actions
    /// ignore it; a plugin action pairs it with `buffer` (below) to
    /// read the text around the cursor.
    pub cursor: Position,
    /// The active buffer's id (AP.2) — the `target` a plugin action
    /// names in an `Effect::ApplyEdit`. Mirrors `MotionContext::buffer_id`.
    pub buffer_id: BufferId,
    /// A point-in-time view of the buffer the action fired in
    /// (AP.0.1). An owned `Buffer` — a `ropey::Rope` clone is O(1)
    /// (Arc-shared nodes), so carrying it costs nothing on the
    /// dispatch path and avoids a context lifetime. Native actions
    /// ignore it; the plugin-host trampoline mints a `document`
    /// resource from it so a grammar plugin can read buffer text.
    /// Layering: a `lattice-core` type, so `lattice-grammar` needs no
    /// `lattice-runtime` dependency (the snapshot is built host-side).
    pub buffer: Buffer,
    /// OS.2: the active region — the Visual/Select 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).
    ///
    /// The peer of `lattice_mode::ActionContext::selection` (MG.18e), which
    /// native mode handlers have had since magit needed to stage part of a
    /// hunk. A plugin action reached the same way saw strictly less — the
    /// position OC.10 fixed for `ex-command-context`. Carried in from
    /// [`GrammarEnv::selection`] so both contexts quote one resolver.
    ///
    /// **Carries no visual kind**, matching the field it mirrors: every
    /// consumer so far reads the row span, and inventing a charwise/blockwise
    /// contract before something holds it would be inventing a promise.
    pub selection: Option<lattice_protocol::position::Range>,
    /// TS.1: a point-in-time tree-sitter snapshot for the buffer the action
    /// fired in, **type-erased** as `Arc<dyn Any>` so `lattice-grammar` keeps
    /// its `protocol`+`core`-only dep set (the same reason `buffer` is a
    /// `lattice-core` type — a concrete `SyntaxSnapshot` would drag the whole
    /// syntax stack under the lean grammar crate). The host upcasts the
    /// buffer's `Arc<SyntaxSnapshot>` here **at the same instant** it clones
    /// `buffer` (so tree + text versions agree); native actions ignore it; the
    /// plugin-host trampoline downcasts it to mint a `tree-snapshot` resource
    /// so a grammar plugin can query structure (auto-pair's `enclosing` scope).
    /// `None` when the buffer has no parse (plain text / parse pending).
    pub syntax: Option<Arc<dyn std::any::Any + Send + Sync>>,
    /// Cooperative cancellation handle (DESIGN.md §5.2.5). Most
    /// actions are O(1) state mutations and ignore this; long-
    /// running ones (a hypothetical "rebuild fold tree" action)
    /// poll `cancel.check()?` between iterations.
    pub cancel: crate::CancellationToken,
    /// OM.6b: the file the action's buffer is backed by, so a plugin action's
    /// `document` handle can answer `path()` — the question `org-archive-subtree`
    /// asks to name `<file>_archive`.
    ///
    /// Owned, unlike the motion and text-object peers, because this context is
    /// owned; `Arc<PathBuf>` rather than `PathBuf` so it is an Arc bump per
    /// dispatch and not an allocation. `None` for a buffer with no file.
    pub path: Option<std::sync::Arc<std::path::PathBuf>>,
}

/// Evaluator callback for a free-form action. Returns the
/// [`crate::effect::Effect`] the host should apply -- typically
/// `Effect::AppAction(AppEffect::Foo)` for a chord-bound action,
/// occasionally a richer `Effect::Many([...])` if the action also
/// emits an edit / mode transition / yank.
type ActionFn = Arc<dyn Fn(&ActionContext) -> GrammarResult<crate::effect::Effect> + Send + Sync>;

/// A registered free-form action: a command with no grammar role, usually
/// bound to a chord.
///
/// Registered through [`CommandRegistry::register_action`] (or
/// [`CommandRegistry::register_plugin_action`]). Most return
/// `Effect::AppAction(..)` for the host to apply; mode-owned actions are
/// registered by their mode's crate, not the host.
#[derive(Clone)]
pub struct ActionSpec {
    /// The evaluator: returns the [`Effect`](crate::Effect) the host applies.
    pub apply: ActionFn,
    /// Per-positional-argument metadata (DESIGN.md §B.1). Empty
    /// for actions without args (the common case for chord
    /// bindings -- the args slot is reserved for future
    /// captured-char / numeric-param variants in slice 8.i.2-3).
    pub args_schema: Vec<ArgSpec>,
}

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

/// What a registered command holds in the registry, beyond its metadata.
#[derive(Clone)]
pub enum CommandRegistration {
    /// A motion; see [`MotionSpec`].
    Motion(MotionSpec),
    /// An operator; see [`OperatorSpec`].
    Operator(OperatorSpec),
    /// A text object; see [`TextObjectSpec`].
    TextObject(TextObjectSpec),
    /// An ex-command; see [`ExCommandSpec`].
    ExCommand(ExCommandSpec),
    /// Free-form App-side action. The dispatcher's
    /// `CommandKind::Action` branch invokes the spec's `apply`
    /// closure and returns its [`crate::effect::Effect`] -- almost
    /// always an [`crate::effect::Effect::AppAction`] carrying a
    /// typed [`crate::app_effect::AppEffect`]. Wired in slice 8.i.0;
    /// populated from the per-mode keymap modules during 8.i.1-3 as
    /// the legacy `Action` bridge retires. See
    /// `docs/dev/notes/8i-approach.md`.
    Action(ActionSpec),
}

impl CommandRegistration {
    /// The [`CommandKind`] this registration dispatches as.
    pub fn kind(&self) -> CommandKind {
        match self {
            CommandRegistration::Motion(_) => CommandKind::Motion,
            CommandRegistration::Operator(_) => CommandKind::Operator,
            CommandRegistration::TextObject(_) => CommandKind::TextObject,
            CommandRegistration::ExCommand(_) => CommandKind::ExCommand,
            CommandRegistration::Action(_) => CommandKind::Action,
        }
    }
}

/// The one registry of every command: motions, operators, text objects,
/// ex-commands and actions, built-in and plugin alike (DESIGN.md §5.2.1).
///
/// **Registration.** Each kind has a `register_<kind>` method taking a
/// canonical name, a doc string and a spec. It mints a fresh
/// [`CommandId`] from a process-wide counter, records the caller's file and
/// line as provenance (`#[track_caller]`; callers cannot forge it), and
/// returns a typed id ([`MotionId`], [`OperatorId`], …). Plugins go
/// through `register_plugin_<kind>`, which stamps
/// [`SourceLayer::Plugin`] instead, and are
/// removed wholesale by [`Self::unregister_plugin`].
///
/// **Names.** Names are namespaced by kind: `motion:word-forward`,
/// `operator:delete`, `text-object:inner-word`, `ex:write`, `action:…`.
/// Names are not checked for uniqueness: registering a name again mints a
/// new id and repoints the name at it, while the old id stays
/// dispatchable. Aliases (`:w`) are not registry entries; the `:`
/// front-end maps them to canonical names.
///
/// **Lookup and dispatch.** [`Self::id_by_name`] and [`Self::lookup`]
/// resolve names and ids to [`CommandSpec`] metadata;
/// [`execute`](crate::execute) takes the registry and an invocation and
/// routes by kind. At runtime the registry is shared as a
/// [`CommandRegistryHandle`](crate::CommandRegistryHandle): readers load a
/// snapshot wait-free, writers clone, mutate and store it.
///
/// # Examples
///
/// ```
/// use lattice_grammar::{CommandKind, CommandRegistry, builtins, ex_commands};
///
/// let mut registry = CommandRegistry::new();
/// assert!(registry.is_empty());
/// let b = builtins::populate(&mut registry);
/// ex_commands::populate(&mut registry);
///
/// let id = registry.id_by_name("operator:delete").unwrap();
/// assert_eq!(id, b.delete.0);
/// let spec = registry.lookup(id).unwrap();
/// assert_eq!(spec.kind, CommandKind::Operator);
/// assert_eq!(registry.lookup_by_name("ex:write").unwrap().kind, CommandKind::ExCommand);
///
/// // Aliases are the front-end's business, not the registry's.
/// assert!(registry.id_by_name("w").is_none());
/// ```
#[derive(Debug, Default, Clone)]
pub struct CommandRegistry {
    by_id: HashMap<CommandId, CommandEntry>,
    by_name: HashMap<String, CommandId>,
    /// Motions in the vim "word-forward" class (`w` / `W`). Under an
    /// operator these get the word-motion special case: `dw` / `cw` /
    /// `yw` on the last word of a line stop at the line end rather than
    /// reaching over the newline into the next line's first word
    /// (`:help word-motions`). Populated by `builtins::populate` via
    /// [`Self::tag_word_forward_motion`]; read by the operator range
    /// resolver.
    word_forward_motions: std::collections::HashSet<CommandId>,
    /// Monotonic mutation counter, bumped on every `insert` and every
    /// non-empty `unregister_plugin`. A cheap version stamp for cache
    /// invalidation: the `:`-command-name completion generator keys its cache on
    /// this (via [`Self::generation`]) so a plugin's *runtime* command
    /// registration or unload — which RCUs a fresh registry with a bumped
    /// counter — shows up in `<Tab>` completion without any manual cache flush.
    /// Clones with the registry (RCU snapshot), so the stored copy carries the
    /// post-mutation value the dispatcher + completion then read.
    generation: u64,
}

#[derive(Clone)]
pub(crate) struct CommandEntry {
    pub spec: CommandSpec,
    pub registration: CommandRegistration,
}

impl std::fmt::Debug for CommandEntry {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("CommandEntry")
            .field("spec", &self.spec)
            .field("registration", &self.registration.kind().label())
            .finish()
    }
}

impl CommandRegistry {
    /// An empty registry. Populate it with
    /// [`builtins::populate`](crate::builtins::populate) and
    /// [`ex_commands::populate`](crate::ex_commands::populate), then the
    /// host's and subsystems' own registrations.
    pub fn new() -> Self {
        Self::default()
    }

    /// Tag a motion as "word-forward class" (vim `w` / `W`) so the
    /// operator range resolver applies the word-motion line-stop special
    /// case to it. Called by `builtins::populate` right after the two
    /// word-forward motions are registered. Idempotent.
    pub fn tag_word_forward_motion(&mut self, id: MotionId) {
        self.word_forward_motions.insert(id.0);
    }

    /// Whether `id` is a word-forward-class motion (see
    /// [`Self::tag_word_forward_motion`]).
    pub fn is_word_forward_motion(&self, id: CommandId) -> bool {
        self.word_forward_motions.contains(&id)
    }

    /// Register a motion. The caller's source location is captured
    /// via `#[track_caller]` -- the caller cannot supply or override
    /// it. Trusted subsystems (config loader, plugin host bridge,
    /// runtime dispatcher) reach the `pub(crate) insert_motion`
    /// companion directly with a layer-appropriate source.
    #[track_caller]
    pub fn register_motion(&mut self, name: &str, doc: &str, spec: MotionSpec) -> MotionId {
        let source = capture_builtin_source();
        self.insert_motion(name, doc, spec, source)
    }

    /// Internal entry point: store the spec with a caller-supplied
    /// source. Visible only inside `lattice-grammar`; trusted
    /// subsystems in sibling crates reach this via a sealed-trait
    /// re-export when they exist (deferred until first cross-crate
    /// trusted subsystem lands -- see DESIGN.md §5.11).
    pub(crate) fn insert_motion(
        &mut self,
        name: &str,
        doc: &str,
        spec: MotionSpec,
        source: SourceLocation,
    ) -> MotionId {
        let id = next_command_id();
        let args_schema = spec.args_schema.clone();
        self.insert(CommandEntry {
            spec: CommandSpec {
                id,
                name: name.to_string(),
                kind: CommandKind::Motion,
                doc: doc.to_string(),
                args_schema,
                source,
                latency_class: crate::command::LatencyClass::Reflex,
            },
            registration: CommandRegistration::Motion(spec),
        });
        MotionId(id)
    }

    /// Register an operator; provenance and id minting as for
    /// [`Self::register_motion`].
    #[track_caller]
    pub fn register_operator(&mut self, name: &str, doc: &str, spec: OperatorSpec) -> OperatorId {
        let source = capture_builtin_source();
        self.insert_operator(name, doc, spec, source)
    }

    pub(crate) fn insert_operator(
        &mut self,
        name: &str,
        doc: &str,
        spec: OperatorSpec,
        source: SourceLocation,
    ) -> OperatorId {
        let id = next_command_id();
        let args_schema = spec.args_schema.clone();
        self.insert(CommandEntry {
            spec: CommandSpec {
                id,
                name: name.to_string(),
                kind: CommandKind::Operator,
                doc: doc.to_string(),
                args_schema,
                source,
                latency_class: crate::command::LatencyClass::Reflex,
            },
            registration: CommandRegistration::Operator(spec),
        });
        OperatorId(id)
    }

    /// Register a text object; provenance and id minting as for
    /// [`Self::register_motion`].
    #[track_caller]
    pub fn register_text_object(
        &mut self,
        name: &str,
        doc: &str,
        spec: TextObjectSpec,
    ) -> TextObjectId {
        let source = capture_builtin_source();
        self.insert_text_object(name, doc, spec, source)
    }

    pub(crate) fn insert_text_object(
        &mut self,
        name: &str,
        doc: &str,
        spec: TextObjectSpec,
        source: SourceLocation,
    ) -> TextObjectId {
        let id = next_command_id();
        let args_schema = spec.args_schema.clone();
        self.insert(CommandEntry {
            spec: CommandSpec {
                id,
                name: name.to_string(),
                kind: CommandKind::TextObject,
                doc: doc.to_string(),
                args_schema,
                source,
                latency_class: crate::command::LatencyClass::Reflex,
            },
            registration: CommandRegistration::TextObject(spec),
        });
        TextObjectId(id)
    }

    /// Register an ex-command; provenance and id minting as for
    /// [`Self::register_motion`]. The command's latency class comes from
    /// [`ExCommandSpec::latency_class`] (other kinds are always `Reflex`).
    #[track_caller]
    pub fn register_ex_command(
        &mut self,
        name: &str,
        doc: &str,
        spec: ExCommandSpec,
    ) -> ExCommandId {
        let source = capture_builtin_source();
        self.insert_ex_command(name, doc, spec, source)
    }

    pub(crate) fn insert_ex_command(
        &mut self,
        name: &str,
        doc: &str,
        spec: ExCommandSpec,
        source: SourceLocation,
    ) -> ExCommandId {
        let id = next_command_id();
        let args_schema = spec.args_schema.clone();
        self.insert(CommandEntry {
            spec: CommandSpec {
                id,
                name: name.to_string(),
                kind: CommandKind::ExCommand,
                doc: doc.to_string(),
                args_schema,
                source,
                latency_class: spec.latency_class,
            },
            registration: CommandRegistration::ExCommand(spec),
        });
        ExCommandId(id)
    }

    /// Register a free-form action (DESIGN.md §5.2.1; see
    /// `docs/dev/notes/8i-approach.md`). Used by chord bindings whose
    /// historical `Action` enum payload had no grammar concept
    /// attached. The spec's `apply` returns an
    /// [`crate::effect::Effect`] -- typically
    /// `Effect::AppAction(AppEffect::...)`.
    #[track_caller]
    pub fn register_action(&mut self, name: &str, doc: &str, spec: ActionSpec) -> CommandId {
        let source = capture_builtin_source();
        self.insert_action(name, doc, spec, source)
    }

    pub(crate) fn insert_action(
        &mut self,
        name: &str,
        doc: &str,
        spec: ActionSpec,
        source: SourceLocation,
    ) -> CommandId {
        let id = next_command_id();
        let args_schema = spec.args_schema.clone();
        self.insert(CommandEntry {
            spec: CommandSpec {
                id,
                name: name.to_string(),
                kind: CommandKind::Action,
                doc: doc.to_string(),
                args_schema,
                source,
                latency_class: crate::command::LatencyClass::Reflex,
            },
            registration: CommandRegistration::Action(spec),
        });
        id
    }

    // ---- Plugin-contribution registration (PH7.7c, §6) ----
    // The forgery-safe cross-crate seam for a WASM plugin's grammar
    // contributions. Each takes the **host-issued** `plugin_id` (a `u32`, never a
    // `SourceLocation`) and always stamps `SourceLayer::Plugin(plugin_id)` via
    // [`SourceLocation::plugin`] — so the "no public fn takes a `SourceLocation`"
    // forgery invariant (`source.rs`) holds, and a plugin cannot forge builtin /
    // user provenance. The `spec.apply` / `parse_args` are the plugin host's sync
    // trampoline closures into the guest (`lattice-plugin-host::grammar_trampoline`);
    // the registry, dispatcher, and every `:describe-*` view treat the entry
    // exactly like a builtin (paramount #3 — a plugin motion is first-class
    // grammar). These are the public counterpart to the `pub(crate) insert_*`
    // path builtins use through `register_*`.

    /// Register a plugin-contributed motion under `SourceLayer::Plugin(plugin_id)`.
    pub fn register_plugin_motion(
        &mut self,
        plugin_id: u32,
        name: &str,
        doc: &str,
        spec: MotionSpec,
    ) -> MotionId {
        self.insert_motion(name, doc, spec, SourceLocation::plugin(plugin_id))
    }

    /// Register a plugin-contributed operator under `SourceLayer::Plugin(plugin_id)`.
    pub fn register_plugin_operator(
        &mut self,
        plugin_id: u32,
        name: &str,
        doc: &str,
        spec: OperatorSpec,
    ) -> OperatorId {
        self.insert_operator(name, doc, spec, SourceLocation::plugin(plugin_id))
    }

    /// Register a plugin-contributed text object under `SourceLayer::Plugin(plugin_id)`.
    pub fn register_plugin_text_object(
        &mut self,
        plugin_id: u32,
        name: &str,
        doc: &str,
        spec: TextObjectSpec,
    ) -> TextObjectId {
        self.insert_text_object(name, doc, spec, SourceLocation::plugin(plugin_id))
    }

    /// Register a plugin-contributed ex-command under `SourceLayer::Plugin(plugin_id)`.
    pub fn register_plugin_ex_command(
        &mut self,
        plugin_id: u32,
        name: &str,
        doc: &str,
        spec: ExCommandSpec,
    ) -> ExCommandId {
        self.insert_ex_command(name, doc, spec, SourceLocation::plugin(plugin_id))
    }

    /// Register a plugin-contributed action under `SourceLayer::Plugin(plugin_id)`.
    pub fn register_plugin_action(
        &mut self,
        plugin_id: u32,
        name: &str,
        doc: &str,
        spec: ActionSpec,
    ) -> CommandId {
        self.insert_action(name, doc, spec, SourceLocation::plugin(plugin_id))
    }

    /// Remove every command a plugin contributed, keyed by its host-issued
    /// `plugin_id` (the `u32` inside `SourceLayer::Plugin`). The teardown seam
    /// for a plugin reload / unload (PH7.12b): the registry is otherwise
    /// append-only, so without this a reload would re-register on top of the
    /// old entries and the `by_id`/`by_name` maps would grow unbounded across
    /// reloads (audit F6). Provenance-driven — only `Plugin(plugin_id)` entries
    /// go; built-in / config / runtime commands are never touched, mirroring
    /// the forgery invariant (a caller supplies only a `u32`, never a
    /// `SourceLayer`). Returns the number of commands removed (0 if the plugin
    /// contributed none — an idempotent no-op on a second unload). Every
    /// index (`by_id`, `by_name`, the word-forward tag set) is kept consistent.
    pub fn unregister_plugin(&mut self, plugin_id: u32) -> usize {
        let doomed: Vec<CommandId> = self
            .by_id
            .iter()
            .filter(|(_, entry)| entry.spec.source.layer == SourceLayer::Plugin(plugin_id))
            .map(|(id, _)| *id)
            .collect();
        for id in &doomed {
            if let Some(entry) = self.by_id.remove(id) {
                self.by_name.remove(&entry.spec.name);
            }
            self.word_forward_motions.remove(id);
        }
        if !doomed.is_empty() {
            self.generation = self.generation.wrapping_add(1);
        }
        doomed.len()
    }

    /// Metadata for a registered id, or `None` if the id is unknown here
    /// (never registered, or removed by [`Self::unregister_plugin`]).
    pub fn lookup(&self, id: CommandId) -> Option<&CommandSpec> {
        self.by_id.get(&id).map(|e| &e.spec)
    }

    /// Metadata by canonical name (`"motion:word-forward"`). Exact match;
    /// no alias or prefix resolution.
    pub fn lookup_by_name(&self, name: &str) -> Option<&CommandSpec> {
        self.by_name.get(name).and_then(|id| self.lookup(*id))
    }

    /// The id currently bound to a canonical name. How modes and the host
    /// find a command they did not register themselves (e.g.
    /// `id_by_name("action:…")` at mode activation).
    pub fn id_by_name(&self, name: &str) -> Option<CommandId> {
        self.by_name.get(name).copied()
    }

    pub(crate) fn entry(&self, id: CommandId) -> Option<&CommandEntry> {
        self.by_id.get(&id)
    }

    /// Is `id` a motion that vim would call a **jump**?
    ///
    /// `MotionSpec::jump` has been declared since the grammar's first slice
    /// and, until VM.3a, read by nobody: the host decided what counted as a
    /// jump with a hardcoded `goto_first_line || goto_last_line` in
    /// `run_document_invocation`. So `}`, `{`, `(`, `)`, the sixteen
    /// tree-sitter structural motions and every plugin motion declared
    /// `jump: true` and silently got neither a position-history entry nor a
    /// fold-open at the destination — org's headline motions say in their own
    /// source comment that a headline jump "is somewhere you want `<C-o>` to
    /// bring you back from", and it was not.
    ///
    /// `false` for a non-motion or an unregistered id, so a caller can ask
    /// about any `CommandId` without pre-checking the kind.
    pub fn motion_is_jump(&self, id: CommandId) -> bool {
        match self.by_id.get(&id).map(|e| &e.registration) {
            Some(CommandRegistration::Motion(spec)) => spec.jump,
            _ => false,
        }
    }

    /// VM.3g-1: what this command does to the goal column. Anything that is NOT
    /// a motion — an operator, an action, an ex-command — answers
    /// `SetFromTarget`, which is what vim does after an edit, an Insert exit or
    /// a yank: the column it leaves the cursor on becomes the new goal.
    pub fn motion_curswant(&self, id: CommandId) -> CurswantEffect {
        match self.by_id.get(&id).map(|e| &e.registration) {
            Some(CommandRegistration::Motion(spec)) => spec.curswant,
            _ => CurswantEffect::SetFromTarget,
        }
    }

    /// Borrow the [`ExCommandSpec`] body for an ex-command id. Returns
    /// `None` for ids that aren't ex-commands or aren't registered.
    /// Used by the `:`-line parser front-end so it can call the
    /// command's `parse_args` callback before building the
    /// `CommandInvocation`.
    pub fn ex_command_spec(&self, id: CommandId) -> Option<&ExCommandSpec> {
        match self.by_id.get(&id)?.registration {
            CommandRegistration::ExCommand(ref spec) => Some(spec),
            _ => None,
        }
    }

    /// Number of registered commands.
    pub fn len(&self) -> usize {
        self.by_id.len()
    }

    /// Whether nothing is registered.
    pub fn is_empty(&self) -> bool {
        self.by_id.is_empty()
    }

    /// Every registered canonical name, in no particular order.
    pub fn names(&self) -> impl Iterator<Item = &str> {
        self.by_name.keys().map(String::as_str)
    }

    fn insert(&mut self, entry: CommandEntry) {
        let id = entry.spec.id;
        let name = entry.spec.name.clone();
        self.by_id.insert(id, entry);
        self.by_name.insert(name, id);
        self.generation = self.generation.wrapping_add(1);
    }

    /// Monotonic mutation counter (see the `generation` field). Read by the
    /// completion layer's command-name generator to key its cache: a change
    /// means the command set moved (a plugin loaded or unloaded), so the cached
    /// candidate list must be regenerated rather than served stale.
    pub fn generation(&self) -> u64 {
        self.generation
    }
}

fn next_command_id() -> CommandId {
    static NEXT: AtomicU64 = AtomicU64::new(1);
    CommandId::new(NEXT.fetch_add(1, Ordering::Relaxed))
}

/// Read the immediate caller's source location through the
/// `#[track_caller]` mechanism. Must be called from inside a
/// `#[track_caller]`-marked function whose caller is the
/// registration site we want to record. Marked
/// `#[track_caller]` itself so the location propagates through:
/// `register_motion` -> `capture_builtin_source` -> caller's site.
#[track_caller]
fn capture_builtin_source() -> SourceLocation {
    let loc = std::panic::Location::caller();
    SourceLocation {
        layer: SourceLayer::Builtin,
        kind: SourceKind::File {
            path: std::path::PathBuf::from(loc.file()),
            line: Some(loc.line()),
        },
    }
}

/// Helper used by the dispatcher to extract the typed body from a registry
/// entry.
pub(crate) fn require_motion(entry: &CommandEntry) -> GrammarResult<&MotionSpec> {
    match &entry.registration {
        CommandRegistration::Motion(s) => Ok(s),
        other => Err(CommandError::KindMismatch {
            expected: "motion",
            actual: other.kind().label(),
        }),
    }
}

pub(crate) fn require_operator(entry: &CommandEntry) -> GrammarResult<&OperatorSpec> {
    match &entry.registration {
        CommandRegistration::Operator(s) => Ok(s),
        other => Err(CommandError::KindMismatch {
            expected: "operator",
            actual: other.kind().label(),
        }),
    }
}

pub(crate) fn require_text_object(entry: &CommandEntry) -> GrammarResult<&TextObjectSpec> {
    match &entry.registration {
        CommandRegistration::TextObject(s) => Ok(s),
        other => Err(CommandError::KindMismatch {
            expected: "text-object",
            actual: other.kind().label(),
        }),
    }
}

pub(crate) fn require_ex_command(entry: &CommandEntry) -> GrammarResult<&ExCommandSpec> {
    match &entry.registration {
        CommandRegistration::ExCommand(s) => Ok(s),
        other => Err(CommandError::KindMismatch {
            expected: "ex-command",
            actual: other.kind().label(),
        }),
    }
}

pub(crate) fn require_action(entry: &CommandEntry) -> GrammarResult<&ActionSpec> {
    match &entry.registration {
        CommandRegistration::Action(s) => Ok(s),
        other => Err(CommandError::KindMismatch {
            expected: "action",
            actual: other.kind().label(),
        }),
    }
}

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

    fn dummy_motion() -> MotionSpec {
        MotionSpec {
            curswant: crate::registry::CurswantEffect::default(),
            jump: false,
            exclusive: false,
            apply: Arc::new(|ctx| {
                Ok(MotionResult {
                    curswant: None,
                    target: ctx.from,
                    linewise: false,
                    exclusive: None,
                    notice: None,
                })
            }),
            args_schema: vec![],
        }
    }

    #[test]
    fn empty_registry() {
        let r = CommandRegistry::new();
        assert!(r.is_empty());
        assert_eq!(r.len(), 0);
        assert!(r.lookup_by_name("nope").is_none());
    }

    #[test]
    fn register_motion_returns_id_and_finds_by_name() {
        let mut r = CommandRegistry::new();
        let id = r.register_motion("test:noop", "no-op motion", dummy_motion());
        assert_eq!(r.len(), 1);
        let spec = r.lookup_by_name("test:noop").unwrap();
        assert_eq!(spec.id, id.0);
        assert_eq!(spec.kind, CommandKind::Motion);
    }

    #[test]
    fn distinct_ids_for_distinct_registrations() {
        let mut r = CommandRegistry::new();
        let a = r.register_motion("a", "", dummy_motion());
        let b = r.register_motion("b", "", dummy_motion());
        assert_ne!(a.0, b.0);
    }

    #[test]
    fn unregister_plugin_removes_only_that_plugins_commands() {
        let mut r = CommandRegistry::new();
        // A built-in and two plugins, one of which registers a word-forward motion.
        r.register_motion("builtin:w", "builtin", dummy_motion());
        let p7 = r.register_plugin_motion(7, "p7:down", "", dummy_motion());
        r.tag_word_forward_motion(p7);
        r.register_plugin_motion(7, "p7:up", "", dummy_motion());
        r.register_plugin_motion(9, "p9:left", "", dummy_motion());
        assert_eq!(r.len(), 4);

        // Unregister plugin 7: both its commands go, the built-in and plugin 9 stay.
        let removed = r.unregister_plugin(7);
        assert_eq!(removed, 2);
        assert_eq!(r.len(), 2);
        assert!(r.lookup_by_name("p7:down").is_none());
        assert!(r.lookup_by_name("p7:up").is_none());
        assert!(r.lookup_by_name("builtin:w").is_some());
        assert!(r.lookup_by_name("p9:left").is_some());
        // The word-forward tag for the removed motion is gone too.
        assert!(!r.is_word_forward_motion(p7.0));

        // Idempotent: a second unload of the same plugin removes nothing.
        assert_eq!(r.unregister_plugin(7), 0);
    }

    #[test]
    fn generation_bumps_on_register_and_nonempty_unregister() {
        // The completion layer keys its `:`-command cache on this counter, so it
        // MUST move whenever the command set changes (a plugin drain / unload) —
        // otherwise plugin commands never appear in `<Tab>` completion.
        let mut r = CommandRegistry::new();
        let g0 = r.generation();
        r.register_motion("builtin:w", "builtin", dummy_motion());
        let g1 = r.generation();
        assert!(g1 > g0, "registering a command must bump generation");
        r.register_plugin_motion(7, "p7:down", "", dummy_motion());
        let g2 = r.generation();
        assert!(g2 > g1, "a plugin registration must bump generation");
        assert_eq!(r.unregister_plugin(7), 1);
        let g3 = r.generation();
        assert!(
            g3 > g2,
            "unregistering a plugin's commands must bump generation"
        );
        // A no-op unregister (nothing removed) must NOT bump — no cache churn.
        assert_eq!(r.unregister_plugin(7), 0);
        assert_eq!(
            r.generation(),
            g3,
            "an empty unregister must not bump generation"
        );
    }

    #[test]
    fn mode_toggle_spec_toggles_named_mode_and_rejects_args() {
        let spec = mode_toggle_ex_command_spec("auto-pair-mode");
        // No args → Ok(None); any args → BadArgs.
        assert!(matches!(
            (spec.parse_args)("", false),
            Ok(crate::args::Args::None)
        ));
        assert!((spec.parse_args)("nope", false).is_err());
        // apply → ToggleMode for the named mode (the spec ignores ctx).
        let ctx = ExCommandContext {
            bang: false,
            args: crate::args::Args::None,
            range: None,
            register: Register::default(),
            count: Count::default(),
            buffer_id: BufferId::default(),
            // OC.10: this spec ignores the buffer entirely (it toggles a mode),
            // so the four carry their empty forms.
            cursor: Position::default(),
            buffer: Buffer::default(),
            path: None,
            syntax: None,
            cancel: crate::CancellationToken::new(),
        };
        match (spec.apply)(&ctx) {
            Ok(crate::effect::Effect::ToggleMode { mode_name }) => {
                assert_eq!(mode_name, "auto-pair-mode");
            }
            other => panic!("expected ToggleMode, got {other:?}"),
        }
    }

    #[test]
    fn lookup_by_id_returns_metadata() {
        let mut r = CommandRegistry::new();
        let id = r.register_motion("test:m", "doc", dummy_motion());
        let spec = r.lookup(id.0).unwrap();
        assert_eq!(spec.name, "test:m");
        assert_eq!(spec.doc, "doc");
    }

    // ---- Source-capture determinism (DESIGN.md §5.11) ----
    //
    // `#[track_caller]` is the load-bearing piece -- it captures the
    // caller's `(file, line)` automatically so registration sites
    // never need to spell their location explicitly. These tests
    // pin its behaviour: any future refactor that breaks call-site
    // capture (e.g. wrapping `register_motion` in a `dyn Fn`
    // dispatcher, which resets the location) fails CI.

    #[test]
    fn track_caller_captures_register_motion_call_site() {
        let mut r = CommandRegistry::new();
        // Sentinel: capture the line of the next call.
        let expected_line = line!() + 1;
        let id = r.register_motion("test:sentinel", "", dummy_motion());
        let spec = r.lookup(id.0).unwrap();
        match &spec.source.kind {
            SourceKind::File {
                path,
                line: Some(line),
            } => {
                assert!(
                    path.to_string_lossy().contains("registry.rs"),
                    "expected path to contain `registry.rs`, got `{}`",
                    path.display()
                );
                assert_eq!(
                    *line, expected_line,
                    "track_caller line drift: expected {expected_line}, got {line}"
                );
            }
            other => panic!("expected Builtin/File source, got {other:?}"),
        }
        assert_eq!(spec.source.layer, SourceLayer::Builtin);
    }

    #[test]
    fn track_caller_captures_register_operator_call_site() {
        let mut r = CommandRegistry::new();
        let expected_line = line!() + 1;
        let id = r.register_operator(
            "test:sentinel-op",
            "",
            OperatorSpec {
                repeatable: false,
                apply: Arc::new(|_| Ok(crate::effect::Effect::None)),
                args_schema: vec![],
                blockwise_per_row: false,
                post_motion_char: false,
            },
        );
        let spec = r.lookup(id.0).unwrap();
        if let SourceKind::File {
            line: Some(line), ..
        } = &spec.source.kind
        {
            // The literal ends 6 lines after the `expected_line`
            // assignment because of formatting -- track_caller records
            // the line of the call expression's *first* token.
            assert_eq!(*line, expected_line);
        } else {
            panic!("expected File source, got {:?}", spec.source.kind);
        }
    }

    #[test]
    fn track_caller_captures_register_text_object_call_site() {
        let mut r = CommandRegistry::new();
        let expected_line = line!() + 1;
        let id = r.register_text_object(
            "test:sentinel-tobj",
            "",
            TextObjectSpec {
                apply: Arc::new(|_| Ok(ProtoRange::new(Position::ZERO, Position::ZERO))),
                args_schema: vec![],
            },
        );
        let spec = r.lookup(id.0).unwrap();
        if let SourceKind::File {
            line: Some(line), ..
        } = &spec.source.kind
        {
            assert_eq!(*line, expected_line);
        } else {
            panic!("expected File source");
        }
    }

    #[test]
    fn each_registration_records_its_own_line() {
        // Two adjacent registrations should record different lines,
        // proving that `#[track_caller]` distinguishes call sites
        // and not just call origins.
        let mut r = CommandRegistry::new();
        let id_a = r.register_motion("test:a", "", dummy_motion());
        let id_b = r.register_motion("test:b", "", dummy_motion());
        let line_a = line_of(&r, id_a.0).expect("id_a has File source");
        let line_b = line_of(&r, id_b.0).expect("id_b has File source");
        assert_ne!(line_a, line_b);
        assert!(
            line_b > line_a,
            "second call's line should follow the first"
        );
    }

    #[test]
    fn track_caller_propagates_through_helper_marked_track_caller() {
        // A helper that wraps `register_motion` and is itself marked
        // `#[track_caller]` should pass the caller's location through.
        // Without `#[track_caller]` on the helper, the location would
        // be that of the inner call inside the helper.
        #[track_caller]
        fn helper(r: &mut CommandRegistry, name: &str) -> MotionId {
            r.register_motion(name, "", dummy_motion())
        }
        let mut r = CommandRegistry::new();
        let expected_line = line!() + 1;
        let id = helper(&mut r, "test:via-helper");
        let line = line_of(&r, id.0).expect("File source");
        assert_eq!(
            line, expected_line,
            "helper marked #[track_caller] should propagate the OUTER caller's line"
        );
    }

    #[test]
    fn unmarked_helper_records_inner_line_not_outer() {
        // Counterexample: a helper that is NOT `#[track_caller]`
        // captures its own internal line, not the outer caller.
        // This documents the propagation contract -- any helper that
        // wraps `register_*` must opt in.
        fn unmarked_helper(r: &mut CommandRegistry, name: &str) -> (MotionId, u32) {
            let inner_line = line!() + 1;
            let id = r.register_motion(name, "", dummy_motion());
            (id, inner_line)
        }
        let mut r = CommandRegistry::new();
        let (id, inner_line) = unmarked_helper(&mut r, "test:unmarked");
        let captured = line_of(&r, id.0).expect("File source");
        assert_eq!(
            captured, inner_line,
            "unmarked helper should record the INNER call line"
        );
    }

    fn line_of(r: &CommandRegistry, id: CommandId) -> Option<u32> {
        match &r.lookup(id)?.source.kind {
            SourceKind::File { line, .. } => *line,
            _ => None,
        }
    }
}