Crate lattice_plugin_host

Expand description

Plugin host — the WASM Component Model extension substrate (Phase 7).

Design fragment: docs/dev/architecture/plugin-host.md. Slice plan: docs/dev/operations/slice-plans/plugin-host.md. Spec: design.md §5.5.

PH7.1a — async runtime core. The host now runs the canonical async ABI (design.md §5.5, fragment §3): the engine has async_support, so a plugin’s lifecycle exports are async and a host call suspends the WASM stack rather than pinning an OS thread. Each call runs under two hard budgets — a fuel cap (total work) and an epoch deadline (wall-clock) — and either, on exhaustion, traps cleanly: the offending call returns a typed PluginHostError::Trap, the [Store] is untouched by any other plugin, and the host stays live. A background epoch-ticker thread bumps the engine epoch so the wall-clock deadline actually fires.

The lib owns no async runtime: methods are async fn, so the caller (the editor’s multi-thread pool — never the current_thread actor) drives them. Running two plugins on two tasks runs them on two cores.

PH7.1b — module cache + lazy instantiation. The AOT (Cranelift) compile of a component is cached on disk (via wasmtime’s own cache, keyed on bytes + compiler config + target + wasmtime version), so a second launch reuses the cached module instead of recompiling. Lazy instantiation is structural here, not a new type: PluginHost::compile loads/caches a Component without instantiating it; the [Store] and instance are created only by an explicit PluginHost::instantiate call. When the contribution model lands (PH7.3+), that call is what a plugin’s first contribution invocation will trigger.

PH7.2 — capability & security model. Each plugin now instantiates under a CapabilityGrant computed from its PluginManifest and TrustTier (fragment §6). The grant is enforced, not advisory: each [Store]’s WASI view is built with exactly its granted filesystem preopens plus a private per-plugin data dir, so a plugin without an fs:write grant cannot reach a path outside its data dir at the WASI layer (WASI has no ambient authority). net:http / proc:spawn ride the grant as metadata for the capability-gated host-services seam (PH7.3+); they are deliberately not wired into the raw WASI view (see capability). The host also issues each plugin a monotonic PluginId and stamps SourceLayer::Plugin provenance from its own ground truth — a plugin cannot forge provenance (lattice_grammar::source has no public SourceLocation setter). See manifest and capability.

The end-to-end “a guest attempts a write and WASI denies it” proof lands at PH7.4 with the real wasm32-wasip2 fuzzy-finder (the guest toolchain PH7.0 deferred to that slice); PH7.2 proves the model at the host layer — grant computation, the grant→preopen mapping, provenance issuance — with the WASI-layer OS enforcement itself resting on wasmtime’s tested guarantee.

Still owned by later slices: every contribution seam (PH7.3+). The first consumer of the plugin lifecycle world is the user’s init.rs; the no-op component the tests instantiate is the degenerate init.rs.

Re-exports§

pub use crate::media_source::WasmMediaSource;
pub use crate::scanned_excerpt_source::WasmScannedExcerptSource;
pub use crate::scanned_excerpt_source::normalise_extensions;
pub use crate::effect_authorizer::EffectAuthorizer;
pub use boundary::WitBoundary;
pub use capability::CapabilityGrant;
pub use capability::FsGrant;
pub use capability::GrantOutcome;
pub use capability::PreopenSpec;
pub use capability::TrustTier;
pub use capability::build_wasi_ctx;
pub use capability::grant;
pub use completion_source::WasmCompletionSource;
pub use completion_task::CompletionActor;
pub use completion_task::CompletionClient;
pub use context_source::WasmContextSource;
pub use context_task::ContextActor;
pub use context_task::ContextClient;
pub use decoration_source::WasmDecorationSource;
pub use decoration_task::DecorationActor;
pub use decoration_task::DecorationClient;
pub use manifest::Capability;
pub use manifest::CapabilityParseError;
pub use manifest::ManifestError;
pub use manifest::PluginManifest;
pub use manifest::PluginSeam;
pub use picker_source::WasmPickerSource;
pub use picker_task::PickerActor;
pub use picker_task::PickerClient;
pub use teardown::PluginTeardown;
pub use teardown::TeardownRegistries;
pub use teardown::TeardownReport;
pub use trace::Direction;
pub use trace::HotGate;
pub use trace::PluginTracePushed;
pub use trace::PluginTraceRecord;
pub use trace::PluginTracer;
pub use trace::PluginTracerHandle;
pub use trace::TraceLevel;
pub use trace::TraceOutcome;
pub use transient_source::project_transient_context;
pub use transient_source::spec_from_wit;
pub use transient_source::transient_builder;
pub use transient_task::TransientActor;
pub use transient_task::TransientClient;
pub use wake::Sleeper;
pub use wake::SleeperHandle;

Modules§

boundary: The boundary adapter machinery (plugin-host.md §4).
boundary_app_effect: WitBoundary mirror for AppEffect (plugin-host.md §4.4, PH7.3b2).
boundary_config: TC.3 — the config schema / value boundary: arena on the wire, tree in the host.
boundary_context: The sticky-context boundary conversions (treesitter-context.md, TC.2).
boundary_decoration: The decoration/ui boundary conversions (plugin-host.md §5 decorations/ui, PH7.9a).
boundary_effect: WitBoundary mirrors for the Effect payload types (plugin-host.md §4.4).
boundary_event: The event/hook boundary conversions (plugin-host.md §5 events, PH7.8a).
boundary_grammar: The grammar-extension boundary conversions (plugin-host.md §4.1, PH7.7a).
boundary_picker: The picker-source boundary mirrors (plugin-host.md §4.2 / §5 picker-source).
buffer: The document resource backing + the buffer-snapshot projection (plugin-host.md §4.2 / §9.6, PH7.3c).
capability: Trust tiers, grant computation, and the per-plugin WASI view.
completion_host: The completion-source guest world (PH7.6).
completion_source: PH7.6 — the WasmCompletionSource adapter (the async-produce path).
completion_task: PH7.6 — the per-plugin actor bridge for completion sources.
config_host: The config guest→host option-declaration seam (PH7.10).
context_host: The context-provider guest world (TC.2).
context_source: TC.2 — the WasmContextSource adapter (the async-produce path).
context_task: TC.2 — the per-plugin actor bridge for sticky-context providers.
dashboard_host: CR.4: the dashboard guest→host section seam. The dashboard guest→host section seam (CR.4).
decoration_host: The decoration-provider guest world (PH7.9b).
decoration_source: PH7.9c — the WasmDecorationSource adapter (the async-produce path).
decoration_task: PH7.9b — the per-plugin actor bridge for decoration providers.
effect_authorizer: XF.4 — authorising a guest-returned effect’s file paths.
error_parser_host: CM.6: the host side of the plugin-contributed compilation-parser seam.
event_task: PH7.8c — the per-plugin event-delivery actor + bus wiring.
events_host: The event/hook guest world (PH7.8b).
grammar_host: The grammar-extension guest world (PH7.7b).
grammar_trampoline: The sync grammar trampoline + registry wiring (plugin-host.md §4.1, PH7.7c).
help_host: CR.3: the help guest→host topic-registration seam. The help guest→host topic-registration seam (CR.3).
host_services: The host-services guest→host seam (plugin-host.md §5) — PH7.4b.
keymap_host: The keymap guest→host binding-registration seam (PL8.D.1).
language_host: The language guest→host registration seam (LG.3c).
lattice
manifest: The plugin manifest — a plugin’s declared capability request.
media_host: IM.6b — the inline-media provider guest world.
media_source: IM.6b — the WasmMediaSource adapter.
media_task: IM.6b — the per-plugin actor bridge for inline-media providers.
mode_host: The modes guest→host mode-declaration seam (PH7.11a).
multibuffer_view_host: MV.1 — the multibuffer-view guest world.
multibuffer_view_task: MV.1 — the per-plugin actor bridge for multibuffer-view sources.
picker_host: The picker-source guest world (PH7.4c.1a).
picker_source: PH7.4c.2 — the WasmPickerSource host adapter (the create path).
picker_task: PH7.4c.1b — the per-plugin actor task + call protocol (the bridge).
plugin_manager_host: PM.7: the host side of the require seam.
plugin_store: OR.1 — durable, plugin-scoped key/value storage for guests.
scan_cache: OT.3b — agenda scan results, remembered across restarts.
scan_host: OM.A1 — the scanned-excerpt-source guest world.
scan_task: OM.A1 — the per-plugin actor bridge for scanned-excerpt-source providers.
scanned_excerpt_source: OM.A1 — the WasmScannedExcerptSource adapter.
sign_host: The signs guest→host sign-declaration seam (SG.3a).
teardown: Plugin teardown — reversing every contribution a plugin made (PH7.12b.3).
theme_host: The theme guest→host element-declaration seam (TC.4).
trace: PO.1 — the plugin boundary-trace substrate (Layer 1 of the observability stack, design fragment docs/dev/architecture/plugin-observability.md).
trampoline: The §4.1 trampoline + §4.3 result-carrier (plugin-host.md, PH7.3d).
transient_host: TR.2b — the transient-source guest world.
transient_source: TR.2b — the WasmTransientSource adapter (boundary + registry builder).
transient_task: TR.2b — the per-plugin actor bridge for transient-source providers.
tree_resource: TS.1 host backing for the tree-snapshot / node WIT resources (plugin-treesitter-seam.md §3). The host owns the parse tree; a plugin gets read-only handles and calls back for the structure it needs — the tree never crosses the boundary (the document-handle model, applied to structure).
ui_host: The ui guest→host contribution seam (OC.3 / ML.6) — a plugin-owned modeline element.
wake: OC.2 — the periodic wake seam: wake-every / cancel-wake / on-wake.

Structs§

Component: The compiled component — the return type of PluginHost::compile, re-exported so callers (the plugin loader) can name it without a direct wasmtime dependency. A compiled WebAssembly Component.
LoadedPlugin: A live plugin instance: its Store (holding the scoped WASI view), the lifecycle bindings, the per-call budget, its host-issued identity and effective grant. Dropping it tears the Store down (the reload/teardown seam PH7.12 formalises).
Plugin: Auto-generated bindings for an instance a component which implements the world plugin.
PluginBudget: Per-call resource budget. Both limits are hard: whichever is hit first traps the call cleanly.
PluginHost: The wasmtime engine, the (import-free) component linker, the on-disk module cache, and the epoch ticker. One host per editor process; construct it once (the engine owns Cranelift).
PluginId: A host-issued plugin identity. Monotonic, allocated by the PluginHost at instantiation — never supplied by the guest. It is the u32 inside SourceLayer::Plugin, so every contribution a plugin registers (PH7.3+) traces back to a provenance the guest cannot forge.
PluginIndices: Auto-generated bindings for index of the exports of plugin.
PluginPre: Auto-generated bindings for a pre-instantiated version of a component which implements the world plugin.

Enums§

PluginHostError: Typed error surface for the plugin host. No host path panics — every failure mode is a value here (the four-artefact graceful-error clause). anyhow::Error is wasmtime’s error type; each variant carries it as #[source].
TrapKind: Why a lifecycle call trapped. Fuel/epoch are the expected runaway-guard outcomes; Other is any genuine wasm trap (unreachable, OOB, a guest panic).

Functions§

data_dir_base_from: The pure resolver behind [default_data_dir_base], split out so the layout is testable without touching the process environment.
legacy_data_dir_base: The pre-2026-09-22 data-dir base, dirs::data_dir()/lattice/plugins/. Read once at boot by migrate_plugin_data; nothing else should use it.
migrate_cache_dirs: Carry the module cache under the config home, once. Returns whether anything moved. A cache that cannot be moved is simply rebuilt.
migrate_plugin_data: Move each <old>/<name>/data directory to <new>/<name>/data, returning how many moved. Idempotent, and safe to call when old does not exist.