Struct PluginHost 

pub struct PluginHost { /* private fields */ }

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).

Implementations

impl PluginHost

pub async fn spawn_completion_source( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, bus: &Arc<EventBus>, config: Option<&Arc<ConfigRegistry>>, ) -> Result<(CompletionClient, CompletionActor), PluginHostError>

Instantiate a completion-source-plugin component under its capability grant and return the bridge: a Send + Sync CompletionClient plus the CompletionActor the caller drives. Grant / data-dir / WASI are identical to instantiate_plugin (shared build_plugin_wasi + new_store), and the actor is not spawned here (the lib owns no runtime). Mirror of spawn_picker_source.

impl PluginHost

pub async fn spawn_config_plugin( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, registry: &Arc<ConfigRegistry>, ) -> Result<(PluginId, Vec<String>), PluginHostError>

Instantiate a config-plugin component under its capability grant, run its register-options export to declare options into registry, and return the names it registered. Grant / data-dir / WASI are identical to instantiate_plugin (shared build_plugin_wasi + new_store).

The registry handle is wired onto the Store BEFORE register-options runs, so the guest’s imported register-option / get-option reach it. Options are declared synchronously (no drain / actor, unlike events); the returned names are the drain of the plugin’s config_contributions (the PH7.12 teardown seam will unregister them).

impl PluginHost

pub async fn spawn_context_source( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, bus: &Arc<EventBus>, config: Option<&Arc<ConfigRegistry>>, ) -> Result<(ContextClient, ContextActor), PluginHostError>

Instantiate a context-plugin component under its capability grant and return the bridge: a Send + Sync ContextClient plus the ContextActor the caller drives. Grant / data-dir / WASI are identical to instantiate_plugin (shared build_plugin_wasi + new_store), and the actor is not spawned here (the lib owns no runtime). Mirror of spawn_decoration_source.

impl PluginHost

pub fn spawn_dashboard_sections( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, ) -> Result<(PluginId, Vec<WasmDashboardSection>), PluginHostError>

Instantiate a dashboard-plugin component, drive its register-dashboard-sections export once, and hand back one live section per id it declared.

Each returned section owns its own instance. Sharing one store across several sections would serialise their renders behind a single mutex and let a trap in one blank all the others — a plugin’s sections should fail independently, the way two plugins’ do.

impl PluginHost

pub async fn spawn_decoration_source( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, bus: &Arc<EventBus>, ) -> Result<(DecorationClient, DecorationActor), PluginHostError>

Instantiate a decorations-plugin component under its capability grant and return the bridge: a Send + Sync DecorationClient plus the DecorationActor the caller drives. Grant / data-dir / WASI are identical to instantiate_plugin (shared build_plugin_wasi + new_store), and the actor is not spawned here (the lib owns no runtime). Mirror of spawn_completion_source.

impl PluginHost

pub async fn spawn_scan_source( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, bus: &Arc<EventBus>, config: Option<&Arc<ConfigRegistry>>, ) -> Result<(ScanClient, ScanActor), PluginHostError>

Instantiate an scanned-excerpt-source-plugin component under its capability grant and return the bridge. Grant / data-dir / WASI are identical to every other seam (shared build_plugin_wasi + new_store), and the actor is NOT spawned here — the lib owns no runtime.

impl PluginHost

pub fn error_parser_factory( self: &Arc<Self>, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, ) -> Result<(PluginId, WasmErrorParserFactory), PluginHostError>

CM.6b: allocate this plugin’s identity and hand back the factory the compilation readers mint from.

Instantiates once here and throws the result away. That costs one store at load and buys a load that fails loudly: an error-parser component that cannot instantiate is a broken plugin, and the alternative is a load that reports success and then contributes nothing to every build forever — the exact silent no-op the NotWired placeholder existed to avoid.

Takes &Arc<Self> because the factory outlives the call: a reader asks it for an instance at the start of every compilation run, long after load.

pub fn spawn_error_parser( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, ) -> Result<WasmErrorParser, PluginHostError>

CM.6: instantiate component as an error-parser and hand back a parser the compilation reader can drive.

Uses the sync linker: feed runs once per captured line and must not suspend (see the module docs).

impl PluginHost

pub async fn spawn_event_plugin( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, bus: &Arc<EventBus>, config: Option<&Arc<ConfigRegistry>>, ) -> Result<(Vec<SubscriptionId>, EventActor), PluginHostError>

Instantiate an events-plugin component under its capability grant, run its register-events export to collect subscriptions, wire each to bus, and return the (subscription ids, actor) pair. The subscriptions are live the moment this returns — but deliveries only fire once the caller drives EventActor::run (until then they queue on the channel). Grant / data-dir / WASI are identical to instantiate_plugin (shared build_plugin_wasi

• new_store); the actor is not spawned here (the lib owns no runtime).

The caller holds the returned SubscriptionIds to EventBus::unsubscribe on teardown; doing so drops the sinks, closes the channel, and ends the actor loop.

config is the live option registry, and the events seam needs it for the same reason context and transient do — see the wiring site below.

impl PluginHost

pub fn instantiate_grammar_plugin( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, bus: &Arc<EventBus>, tracer: Option<&PluginTracerHandle>, config_registry: Option<&Arc<ConfigRegistry>>, ) -> Result<GrammarContributionSet, PluginHostError>

Instantiate a grammar-plugin component, drive its register-grammar export, and return the native GrammarContributionSet (each spec’s apply a sync trampoline into the guest). Synchronous end to end (the PH7.7 fork): instantiated against the sync grammar_linker (sync WASI + the grammar register import), so there is no async host import a sync apply could reach. The caller registers the result via GrammarContributionSet::register_all.

A malformed spec (an arg-spec / latency-class / surface-form that won’t convert) fails registration loudly with PluginHostError::GrammarSpec; a runtime apply failure is graceful (a no-op, §8), handled in the trampoline. Instantiation + register-grammar run under the generous lifecycle budget; per-apply calls arm the Reflex budget (audit F1).

PO.3: pass Some(tracer) to instrument the sync grammar seam. Each guest call then reads the plugin’s published HotGate once (a relaxed atomic load); at the default Info gate that is the trampoline’s only added cost (design §4). None (tests / benches / a tracer-less loader) skips even the gate handoff. The tracer’s hot_gate(id) is seeded to the plugin’s current effective level and updated live by :set plugin.trace-level.

impl PluginHost

pub async fn spawn_help_plugin( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, ) -> Result<(PluginId, Vec<HelpTopicSpec>), PluginHostError>

Instantiate a help-plugin component under its capability grant, drive its register-help-topics export once, and return the host-issued id plus the topics it declared.

Mirror of spawn_theme_plugin. Nothing about the guest outlives this call: the bodies are already across, so the Store is dropped when the function returns and reading :help never touches wasm again.

impl PluginHost

pub async fn spawn_media_source( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, bus: &Arc<EventBus>, ) -> Result<(MediaClient, MediaActor), PluginHostError>

Instantiate a media-plugin component under its capability grant and return the bridge. Grant / data-dir / WASI are identical to every other seam (shared build_plugin_wasi + new_store), and the actor is NOT spawned here — the lib owns no runtime.

impl PluginHost

pub async fn spawn_keymap_plugin( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, keymap: &KeymapHandle, commands: &Arc<CommandRegistry>, ) -> Result<(PluginId, Vec<KeymapBindingToken>), PluginHostError>

Instantiate a keymap-plugin component under its capability grant, run its register-keymap export to bind user keybindings into keymap (KeymapLayer::User), and return the tokens for teardown. Grant / data-dir / WASI are identical to instantiate_plugin.

The keymap handle + command-registry snapshot are wired onto the Store BEFORE register-keymap runs, so the guest’s imported register-binding reaches them. Bindings land synchronously (no drain / actor); the returned tokens are what the loader’s teardown unbinds on unload.

impl PluginHost

pub async fn spawn_language_plugin( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, ) -> Result<(PluginId, Vec<LanguageSpec>), PluginHostError>

Instantiate a language-plugin component under its capability grant, drive its register-languages export once, and return the host-issued id plus the languages it declared.

Mirror of spawn_help_plugin. Nothing about the guest outlives this call: the bytes and query sources are already across, so the Store is dropped when the function returns and parsing never touches the guest again.

impl PluginHost

pub async fn spawn_mode_plugin( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, registry: &mut ModeRegistry, commands: &CommandRegistry, keymap: &KeymapHandle, config: Option<&ConfigRegistry>, ) -> Result<(PluginId, Vec<ModeId>), PluginHostError>

Instantiate a modes-plugin component under its capability grant, run its register-modes export to declare modes, register each into registry, and return the successfully-registered ModeIds. Grant / data-dir / WASI are identical to instantiate_plugin (shared build_plugin_wasi + new_store).

Registration is drained AFTER register-modes returns because ModeRegistry::register needs &mut ModeRegistry — unlike config’s live Arc<ConfigRegistry> handle. A declaration the registry rejects is logged + skipped (not in the returned ids); the teardown seam (PH7.12) will remove a plugin’s modes.

impl PluginHost

pub async fn spawn_multibuffer_view_source( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, bus: &Arc<EventBus>, config: Option<&Arc<ConfigRegistry>>, ) -> Result<(MultibufferViewClient, MultibufferViewActor), PluginHostError>

Instantiate a multibuffer-view-plugin component under its capability grant and return the bridge. Grant / data-dir / WASI are identical to instantiate_plugin; the actor is not spawned here (the lib owns no runtime). Mirror of spawn_picker_source.

impl PluginHost

pub async fn spawn_picker_source( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, bus: &Arc<EventBus>, config: Option<&Arc<ConfigRegistry>>, ) -> Result<(PickerClient, PickerActor), PluginHostError>

Instantiate a picker-source-plugin component under its capability grant and return the bridge: a Send + Sync PickerClient plus the PickerActor the caller drives (spawn PickerActor::run on a multi-thread runtime). Grant computation, the private data dir, and the scoped WASI view are identical to instantiate_plugin (via build_plugin_wasi) — a picker plugin is sandboxed exactly like a lifecycle plugin.

The actor is not spawned here (the lib owns no runtime). Until the caller drives it, calls on the client simply queue on the channel.

Denied capabilities (a tier-withheld request) are logged; surfacing them to the user rides the registration path (PH7.4c.2), which is the only consumer that needs them.

impl PluginHost

pub async fn spawn_plugin_manager_plugin( &self, component: &Component, manifest: &PluginManifest, budget: PluginBudget, trust: TrustTier, ) -> Result<(PluginId, Vec<RequiredPlugin>), PluginHostError>

Instantiate component as a plugin-manager guest, call its register-plugins export, and return the specs it declared.

Returns the host-issued id alongside the specs — the spawn_mode_plugin shape — so the loader can record the guest as loaded even when it declared nothing.

The specs are declarations, not loaded plugins: the caller runs resolve → build → load off-thread (§5).

impl PluginHost

pub async fn spawn_transient_source( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, bus: &Arc<EventBus>, config: Option<&Arc<ConfigRegistry>>, ) -> Result<(TransientClient, TransientActor), PluginHostError>

Instantiate a transient-source-plugin component under its capability grant and return the bridge: a Send + Sync TransientClient plus the TransientActor the caller drives. Grant / data-dir / WASI are identical to every other seam (shared build_plugin_wasi + new_store), and the actor is NOT spawned here — the lib owns no runtime.

impl PluginHost

pub async fn spawn_sign_plugin( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, registry: &SignRegistryHandle, ) -> Result<(PluginId, Vec<String>), PluginHostError>

Instantiate a sign-plugin component under its capability grant, drive its register-signs export once, and return the host-issued id plus the sign names it declared (the teardown tokens).

Mirror of spawn_theme_plugin: the registry is wired onto PluginState BEFORE the export runs so the guest’s imported define-sign reaches it.

impl PluginHost

pub async fn spawn_theme_plugin( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, registry: &ThemeRegistryHandle, ) -> Result<(PluginId, Vec<String>), PluginHostError>

Instantiate a theme-plugin component under its capability grant, drive its register-theme-elements export once, and return the host-issued id plus the element names it registered (the teardown tokens).

Mirror of spawn_config_plugin: the registry is wired onto PluginState BEFORE the export runs so the guest’s imported register-element reaches it.

impl PluginHost

pub fn new() -> Result<Self, PluginHostError>

Build a host with the default module-cache directory ([default_cache_dir]) and per-plugin data-dir base ([default_data_dir_base]). This is the production constructor.

pub fn with_cache_dir( cache_dir: impl Into<PathBuf>, ) -> Result<Self, PluginHostError>

Build a host caching compiled components under cache_dir, with the default per-plugin data-dir base. Kept as the narrow constructor the cache tests already use.

pub fn with_dirs( cache_dir: impl Into<PathBuf>, data_dir_base: impl Into<PathBuf>, ) -> Result<Self, PluginHostError>

Build a host with an explicit module-cache directory and per-plugin data-dir base. Capability tests point both at per-test tempdirs so the data-dir mounts and provenance are hermetic.

The AOT (Cranelift) compile of a component is cached on disk by wasmtime, keyed on the component bytes, the compiler configuration, the target, and the wasmtime version — so a second launch reuses the cached module instead of recompiling (design.md §15 Q17). wasmtime owns the keying and invalidation; the host owns only the location.

The linker is populated with the WASI (preview2) host functions once here; each plugin’s view onto them is scoped per-Store from its grant (PH7.2). Components that import no WASI (the hand-written lifecycle fixtures) instantiate fine against the populated linker.

pub fn plugin_data_dir(&self, plugin_id: &str) -> Option<PathBuf>

OT.3b: where a plugin’s private data lives — <base>/<id>/data/, the same directory build_plugin_wasi grants it.

Exposed so a seam adapter can persist across restarts beside the plugin’s own data (the agenda result cache), and so uninstalling a plugin removes what it cached. None for an id that is not a safe directory name — the same refusal build_plugin_wasi makes, rather than a second opinion about it.

pub fn plugin_store_get(&self, plugin_id: &str, key: &str) -> Option<Vec<u8>>

OR.1: read one key out of a plugin’s store, host-side.

The store is the guest’s schema and the host never interprets it — this hands back the same opaque bytes store-get would, without instantiating anything. It exists because a reader of a plugin’s index may be host-side (a multibuffer provider) and because a test that asked the writing guest what it wrote would pass against a per-instance store, which is the exact drift the store exists to prevent.

None for an unknown plugin id, an unsafe one, or a key with nothing under it — the three are indistinguishable to a caller, and all three mean “build it”.

pub fn set_tracer(&self, tracer: PluginTracerHandle)

Install the boundary tracer (PO.5) — the loader calls this once, after it builds the tracer, so every subsequent instantiate/spawn stamps the plugin’s log_ctx and the guest logging seam routes into the ring. Idempotent: a second call is ignored (the tracer is set once per host).

pub fn set_project_context( &self, resolver: ProjectResolverHandle, buffers: BufferStoreHandle, )

PR.6: hand the host what the guest project seam answers from.

Called once at boot after the resolver is registered. Idempotent — a second call is ignored, like set_tracer.

pub fn set_foreground_cancel(&self, cancel: ForegroundCancelHandle)

CG.4: hand the host the foreground-cancel registry, so a running guest call can be interrupted by <C-g>.

Idempotent — a second call is ignored, like set_tracer.

pub fn set_sleeper(&self, sleeper: SleeperHandle)

OC.2: hand the host the timer the wake-every seam sleeps on.

This crate owns no runtime, so it cannot construct one — the caller that spawns the actors is the one that has an executor to sleep on, and it supplies the Sleeper here. Unset leaves wake-every answering 0.

Idempotent — a second call is ignored, like set_tracer.

pub fn set_config_registry(&self, registry: Arc<ConfigRegistry>)

OA.14d: hand the host the option registry every store reads through.

The floor, not a replacement for the per-seam wiring: a seam that cannot function without a registry (config itself) still takes one as an argument, because “this seam requires it” and “any guest may read an option” are different claims. What this closes is the second one, which had been answered seam by seam and was therefore wrong for whichever seams nobody had thought about — theme and language among them, the two org reads its keyword set from at load.

Idempotent — a second call is ignored, like set_tracer.

pub fn set_excerpt_source_resolver(&self, resolver: ExcerptSourceResolverHandle)

OA.23: hand the host what resolves a composed line to its source file.

Idempotent — a second call is ignored, like set_tracer.

pub fn excerpt_source_wired(&self) -> bool

HB.2b: whether a resolver was ever wired.

Every store is stamped from this slot at creation, so a host that reaches its first instantiate_* unwired hands every guest a seam that answers none forever — and answering none is a legitimate reply the guest cannot tell apart from “this line is not composed”. Exposed so the boot pin can assert the wiring rather than a reading of install.

pub fn set_view_args_resolver(&self, resolver: ViewArgsResolverHandle)

OA.27: hand the host what answers “what is this provider view showing”.

Idempotent — a second call is ignored, like set_tracer.

pub fn view_args_wired(&self) -> bool

OA.27: whether a resolver was ever wired.

Exposed for excerpt_source_wired’s reason, and it bites harder here: an unwired view-args answers an empty list, a guest parses that as a fresh view, and every chord that walks the view then silently starts over from the default. There is no error anywhere on that path — which is precisely how the bug this seam replaces survived.

pub fn set_buffer_store(&self, buffers: BufferStoreHandle)

CD.6b: hand the host the buffer store clamp-position measures.

Idempotent — a second call is ignored, like set_tracer.

pub fn buffer_store_wired(&self) -> bool

CD.6b: whether a buffer store was ever wired.

Pinned at boot for view_args_wired’s reason: unwired, clamp-position answers none for every buffer, which a guest reads as “that buffer is closed”. A roam link would then never be written back, with a message blaming a buffer that is still open.

pub fn set_decoration_epoch(&self, epoch: DecorationEpochHandle)

OA.30: hand the host the counter refresh-decorations bumps.

Idempotent — a second call is ignored, like set_tracer.

pub fn decoration_epoch_wired(&self) -> bool

OA.30: whether a counter was ever wired.

Pinned at boot for view_args_wired’s reason: unwired, the seam is a silent no-op and a guest’s marks simply never repaint — no error on any path, and the symptom reads as a broken feature rather than a missing wire.

pub fn set_modeline(&self, modeline: ModelineServiceHandle, bus: Arc<EventBus>)

OC.3 / ML.6: hand the host what a plugin’s ui modeline calls act on.

Both halves at once, on the set_project_context reasoning: a registry with no bus would let a plugin register a descriptor and push content that nothing ever repaints — half-wired, and half-wired is the failure mode this seam is most likely to have (plugin-gates-hand-guests- throwaway-contexts). Unset leaves register-segment returning false.

Idempotent — a second call is ignored, like set_tracer.

pub fn cache_hits(&self) -> usize

Number of module-cache hits so far (a compiled artifact was reused from disk instead of recompiled). Exposed for tests and future observability.

pub fn cache_misses(&self) -> usize

Number of module-cache misses so far (a component was compiled and its artifact written to the cache).

pub fn compile(&self, bytes: &[u8]) -> Result<Component, PluginHostError>

Compile component bytes (AOT via Cranelift) into a reusable Component. Malformed / non-component input returns PluginHostError::Compile — no panic. Compilation is synchronous regardless of the async engine.

pub async fn instantiate( &self, component: &Component, ) -> Result<LoadedPlugin, PluginHostError>

Instantiate a compiled component into a live LoadedPlugin with the default per-call budget and no capability grant (an empty WASI view — zero filesystem access, no data dir). This is the degenerate load; a real plugin uses instantiate_plugin with a manifest.

pub async fn instantiate_with_budget( &self, component: &Component, budget: PluginBudget, ) -> Result<LoadedPlugin, PluginHostError>

Instantiate a compiled component with an explicit per-call budget and no capability grant (empty WASI view). See instantiate.

pub async fn instantiate_plugin( &self, component: &Component, manifest: &PluginManifest, tier: TrustTier, budget: PluginBudget, ) -> Result<LoadedPlugin, PluginHostError>

Instantiate a plugin under its capability grant (PH7.2, fragment §6).

The grant is computed from manifest + tier; a private data dir (<data-base>/<manifest.id>/data/) is created and mounted writable, and each granted fs:* prefix is preopened at its own path. The resulting [Store]’s WASI view reaches exactly the granted filesystem and nothing else — a plugin without an fs:write grant cannot write outside its data dir at the WASI layer. Requested capabilities the tier withheld (e.g. proc:spawn for a user-installed plugin) are surfaced on LoadedPlugin::denied_capabilities so the host can notify the user; the load still succeeds (graceful degradation).

Each instantiation gets its own Store (the isolation boundary) and a fresh host-issued PluginId. Instantiation runs with generous [INSTANTIATION_FUEL]; the tighter PluginBudget applies per call.