Spid3r
Extension guide

Writing Spid3r plugins

A plugin adds functions to a Spid3r program. You write one in Spid3r — a .matrix file with public fns, no Rust and no build step. Two other kinds exist for the cases the language cannot cover: sandboxed WebAssembly, and native Rust for hosts that embed the toolchain.

spid3r plugin · works wasm plugin · works host plugin · works ffi · works (AOT) abi v1 · enforced

abi v1 is the contract version every plugin declares: spid3r-plugin-abi-1, matched exactly at load, so a plugin built against a different contract is rejected rather than half-working. There is no compatibility negotiation and no "probably fine" — bumping the ABI means a new string, and old plugins stop loading on purpose.
ffi is a separate contract, not part of the plugin ABI: extern fn declares a C function, the AOT backend links it with --link-lib, and the tree and VM reject it at compile time because they link nothing. Trusted code — a C library has the same authority your program does.

01 What a plugin is

Three kinds, one registry, one place they meet.

Third-party code reaches a Spid3r program through seven routes. Three of them are plugins, and they are the only ones where you decide what the function does — which is why they get their own page.

Three plugin kinds merge into one native table that three engines install from A Spid3r-source plugin loaded from disk, a WASM plugin loaded from disk and a host plugin compiled into the binary all register into the same plugin registry. The registry merges into stdlib native_defs, which the tree interpreter, the bytecode VM and the AOT backend all install from. Spid3r plugin .matrix · script trust wasm plugin from disk · sandboxed host plugin compiled in · trusted plugin registry fn ptr + closures native_defs() the single merge point tree interpreter bytecode VM AOT · no plugins a plugin function needs no per-engine code — all three read the same list
All three kinds register into one table. That is why a plugin function works on every engine that installs from it.

Spid3r plugin kind = "matrix"

A .matrix file whose public fns become callable from any program. Same language, same standard library, same debugger. Script authority — the same trust as your own source.

Host plugin kind = "host"

Rust code compiled into a binary that embeds the toolchain. Full authority, no sandbox. The right choice for a program you control that needs to expose its own internals to a script.

WASM plugin kind = "wasm"

A .wasm module the toolchain reads from disk and interprets. No imports, no ambient authority, fuel-limited. The right choice for anything you did not write.

The one-sentence difference. A Spid3r or host plugin is trusted code — it can do what your program can. A WASM plugin has nothing to be trusted with, because the host links no capabilities into it. That is why the sandbox is the only route worth running code you did not write.

02 Which kind should I write?

Pick by who wrote the code, not by what it does. If in doubt: write it in Spid3r.

If you are… Write Because
Writing a plugin, full stop Spid3r plugin it is your language: a .matrix file with public fns, loaded from disk
Distributing a plugin to people you do not know WASM plugin the only route that is sandboxed, so it is the only one to run untrusted code in
Shipping a Rust app that embeds spid3r_lang host plugin you already control the binary; registration is a single call at startup
Needing a file, a socket or a clock inside the plugin Spid3r or host a WASM guest has no imports, so it cannot reach any of them
Targeting spid3r build output neither a standalone executable cannot link a plugin — see Limits

03 Spid3r plugins

The default. Write the plugin in the language.

A Spid3r plugin is a directory with a plugin.toml and a .matrix file. Its public fns become callable from any program that loads it — no Rust, no WebAssembly, no build step. If you can write a function, you can write a plugin.

greetings/plugin.tomltoml
[plugin]
name = "greetings"
version = "0.1.0"
abi = "spid3r-plugin-abi-1"
kind = "matrix"
entry = "greetings.matrix"   # optional: defaults to <name>.matrix

[[function]]
name = "greet"
arity = 1

[[function]]
name = "sum_to"
arity = 1
greetings/greetings.matrixspid3r
// Nothing special: ordinary functions in the ordinary language.
public fn greet(name) {
    return "Hello, " + name + "!";
}

public fn sum_to(n) {
    let total = 0;
    let i = 1;
    while (i <= n) {
        total = total + i;
        i = i + 1;
    }
    return total;
}

Then any program that can see the plugin calls them like builtins:

app.matrixspid3r
fn main() {
    println(greet("Ada"));
    println(sum_to(10));
}
shellbash
# point at the directory containing greetings/ (or set [modules] plugins in spid3r.ini)
export SPID3R_PLUGINS=./plugins
spid3r plugin check ./plugins/greetings
spid3r run app.matrix
# Hello, Ada!
# 55

What the loader does

Parse and check

The .matrix file goes through the same parser and semantic checker as any program — including the lints. A plugin that does not check never loads.

Run the top level, without a fn main

A plugin is a module, not a program, so it is loaded with run_module — every top-level statement, no entry point required. The definitions are the point.

Bind each declared function

For every [[function]], the loader looks the name up in the plugin's globals, checks it is a function with the declared arity, and wraps it as a native closure. A declared name that the file does not define is a load error.

Register

The closures join the same registry as every other plugin, so the tree interpreter and the bytecode VM both see them — with no per-engine code.

Trust: this is script code. A Spid3r plugin has exactly the authority a script has — the same builtins, the same file access. It is tier T1, the same trust as your project's own source. Being a plugin does not sandbox it, and pretending otherwise would be the worst kind of documentation. Use kind = "wasm" for code you did not write.

Isolation and rules

Property Behaviour
Globals Each plugin gets its own interpreter and its own globals: it cannot read or clobber the calling program's variables.
Standard library Fully available — that is the point of writing in the language.
Imports The plugin's own directory is first on its module search path, so it can import a sibling file.
Errors A throw inside the plugin reaches the caller's catch with its message intact.
Arity Checked against the file at load: a manifest cannot describe a call the language would reject.
Build step None. The file is the plugin.
Needs plugins-wasm? No — a Spid3r plugin works in the zero-dependency build.

A complete, runnable sample: examples/plugins/hello-matrix/.

04 The manifest

plugin.toml is the contract. All three kinds use the same file.

plugin.tomltoml
# The manifest is the contract: what the plugin is, what ABI it targets,
# and every function it may expose.
[plugin]
name = "hello"                 # unique across the process
version = "0.1.0"
abi = "spid3r-plugin-abi-1"  # exact match, or registration fails
kind = "matrix"              # "matrix", "wasm", or "host"
capabilities = ["environment"] # everything the plugin may declare
# entry = "plugin.wasm"          # required for kind = "wasm"; optional for "matrix"

# One block per function. The name is what a script calls.
[[function]]
name = "hello_greet"
arity = 1                     # no permission: pure computation

[[function]]
name = "hello_env"
arity = 1
permission = "environment"   # must appear in capabilities above
Key Required Meaning
name yes Unique plugin id. Two plugins with the same name cannot coexist in one process.
version no Free-form; shown in diagnostics. Defaults to 0.0.0.
abi yes Must equal spid3r-plugin-abi-1 exactly. Checked before any plugin code runs.
kind no matrix (Spid3r source), wasm (sandboxed WebAssembly), or host (Rust, parser default when omitted).
capabilities no The full set a function may declare: filesystem, process, network, environment.
entry for wasm The .wasm file name (required for wasm) or .matrix file name (optional for matrix; defaults to <name>.matrix), relative to the manifest.
[[function]].name yes The identifier a script calls.
[[function]].arity no Checked against what the plugin actually offers; a mismatch is a registration error.
[[function]].permission no The capability a script must be allowed to call this function.
Why a wrong ABI is a hard error. A plugin built against a different contract is not "probably fine". Rejecting it before start() runs means a mismatched plugin can never half-work.

The ABI is versioned, and you can inspect it

spid3r-plugin-abi-1 is a contract with three parts — the manifest, the function surface, and (for WASM) the wire format. It is matched exactly, so the toolchain also gives you a way to read and validate it without loading anything:

shellbash
# the version string this build implements
spid3r plugin abi
# spid3r-plugin-abi-1

# what the search path would load — names, kinds, function counts
spid3r plugin list

# does this directory conform? the loader's own validation, without registering
spid3r plugin check examples/plugins/hello-wasm
# ok: … conforms to spid3r-plugin-abi-1
#   kind wasm · 2 function(s) · capabilities []
#   2 export(s) resolved · 65745 byte(s) of module

check exits 0 valid, 1 invalid, 2 usage. Because it runs the loader's own validation, a passing check and a failing load cannot disagree. A kind = "host" directory cannot be validated from disk — it is Rust compiled into a host — and the command says so rather than passing it.

ABI v1 fixes What would force a v2
The manifest keys and what each one means a new required key, or a changed meaning for an existing one
What a declared arity means a different rule for matching it
The value tags: null, int, float, bool, string, list a new tag, or a changed payload for an existing one
The guest exports: memory, alloc, dealloc, (i32, i32) -> i64 a changed signature or a new required export
Exact-match versioning — no negotiation, no compatibility range accepting a second version string at the same time (a v2 loader alongside v1)

Adding an optional manifest key an older plugin can omit does not force a bump; the parser must accept its absence. The full contract, including how a v2 would coexist with v1: docs/PLUGIN_ABI.md.

05 Host plugins

A trait, four methods, one registration call.

A host plugin is a Rust type implementing PluginHost. It is compiled into the binary that embeds the toolchain — there is no dynamic loading, because a native function is a Rust function pointer over Value, and Value has no stable representation that could cross a C ABI boundary.

Implement the trait

manifest() returns your parsed plugin.toml; functions() returns one definition per declared function.

src/lib.rsrust
use std::sync::Arc;
use spid3r_lang::plugin::{PluginFnDef, PluginHost, PluginManifest};
use spid3r_lang::value::{NativeCtx, Value};

pub struct Hello;

impl PluginHost for Hello {
    fn manifest(&self) -> &PluginManifest {
        // Embed it, so the shipped manifest and the code cannot drift.
        manifest_singleton()
    }

    fn functions(&self) -> Vec<PluginFnDef> {
        vec![PluginFnDef {
            // A fn pointer needs a 'static name: the function names are
            // compile-time constants, which is what keeps them out of the
            // marshalling problem entirely.
            name: "hello_greet",
            arity: 1,
            permission: None,
            func: greet,
        }]
    }

    // start runs before the first call; stop runs at shutdown.
    fn start(&mut self) -> Result<(), String> { Ok(()) }
    fn stop(&mut self) -> Result<(), String> { Ok(()) }
}

// The function itself: same signature as any builtin native.
fn greet(_ctx: &NativeCtx, args: Vec<Value>) -> Result<Value, String> {
    match args.first() {
        Some(Value::Str(s)) => Ok(Value::Str(Arc::from(format!("Hello, {s}!")))),
        _ => Err("hello_greet(name) expects a string".into()),
    }
}

Register it before you create an engine

Registration merges your functions into native_defs(), the list every engine installs from. Doing it after the engine exists is too late.

src/main.rsrust
use spid3r_lang::embed::Engine;

spid3r_lang::plugin::register(Box::new(Hello))?;

let engine = Engine::new();
let out = engine.run("app.matrix", &source)?;
print!("{}", out.output);

// Stop plugins in a defined order rather than at process exit.
spid3r_lang::plugin::shutdown_all();

Call it from a script

app.matrixspid3r
fn main() {
    println(hello_greet("Ada"));
    return 0;
}

Lifecycle

State When What it means
Loaded after the manifest checks pass registered, start not yet attempted
Started start() returned Ok its functions are visible to scripts
Stopped stop() ran functions are no longer offered
Failed start() returned Err recorded, never offered, host keeps running
A broken plugin cannot take the host down. start() runs with the registry lock released, so it may do real work; if it fails, the plugin is recorded as Failed and its functions are simply never offered. stop() must tolerate being called twice, and shutdown_all() returns errors instead of failing fast.

A complete, runnable sample: examples/plugins/hello-host/.

06 WASM plugins

Sandboxed plugins loaded from disk without rebuilding spid3r.

A WASM plugin is a directory: plugin.toml plus a .wasm module. The toolchain reads both from the plugin search path and interprets the module with wasmi. This is the only route that can be sandboxed, because the host links nothing into the guest.

Directory layout

my-plugin/tree · the Rust sample's layout
my-plugin/
├── plugin.toml      # kind = "wasm", entry = "plugin.wasm"
├── plugin.wasm      # the built module — the only file the host reads
├── Cargo.toml       # Rust only: crate-type = ["cdylib"]
└── src/lib.rs       # Rust only: the guest source

Only the first two lines are part of the plugin. Everything else is whatever build system produced plugin.wasm — for C that would be guest.c and a Makefile, and the directory would look the same to the host.

The guest contract

A module must export exactly these:

Export Signature Purpose
memory — The linear memory the host reads and writes. A cdylib exports it by default.
alloc (i32) -> i32 Reserve len bytes, return the pointer.
dealloc (i32, i32) -> () Optional. Release the request buffer after the call.
one per function (i32, i32) -> i64 Take (ptr, len), return (ptr << 32) | len of the response.

A function's export name is its manifest name, so there is no dispatch table inside the guest — the host resolves the export once, at load time.

One plugin call through linear memory The host encodes the arguments, calls alloc in the guest to reserve space, copies the bytes into the guest's linear memory, calls the exported function, then reads the response bytes back and decodes them. host encode(args) guest linear memory request bytes response bytes alloc(ptr) · call(ptr, len) · dealloc guest export hello_greet write invoke read (ptr, len) back · decode nothing crosses the boundary except bytes
Arguments go in as bytes, the answer comes back as bytes. The guest cannot see or touch anything else.

A complete guest, in Rust

The guest is any program that produces a wasm module. Rust is used here only because the shipped sample is a Rust crate and Rust targets wasm32-unknown-unknown with no ceremony — the contract is the exports and the bytes, not the language. A C, Zig, Go or AssemblyScript guest that exports the same five symbols is equally valid.

src/lib.rsrust
// Responses are copied into a static buffer, so the guest never hands the
// host a dangling pointer and never leaks an allocation.
const OUT_CAP: usize = 1 << 16;
static mut OUT: [u8; OUT_CAP] = [0; OUT_CAP];

/// Reserve `len` bytes; the host writes the request there.
#[no_mangle]
pub extern "C" fn alloc(len: u32) -> u32 {
    let mut buf: Vec<u8> = Vec::with_capacity(len as usize);
    buf.resize(len as usize, 0);
    let ptr = buf.as_mut_ptr() as u32;
    std::mem::forget(buf);
    ptr
}

#[no_mangle]
pub extern "C" fn dealloc(ptr: u32, len: u32) {
    unsafe { drop(Vec::from_raw_parts(ptr as *mut u8, len as usize, len as usize)); }
}

/// Copy `bytes` out and return `(ptr << 32) | len`.
fn respond(bytes: &[u8]) -> i64 {
    let n = bytes.len().min(OUT_CAP);
    unsafe {
        let out = &mut *core::ptr::addr_of_mut!(OUT);
        out[..n].copy_from_slice(&bytes[..n]);
        ((out.as_ptr() as u32) as i64) << 32 | (n as i64)
    }
}

/// hello_greet(name) -> string
#[no_mangle]
pub extern "C" fn hello_greet(ptr: u32, len: u32) -> i64 {
    // SAFETY: the host just wrote `len` bytes at `ptr` via alloc.
    let req = unsafe { std::slice::from_raw_parts(ptr as *const u8, len as usize) };
    match decode_one_string(req) {
        Ok(name) => respond(&encode_string(&format!("Hello, {name}!"))),
        Err(e) => respond(&encode_error(&e)),
    }
}

decode_one_string / encode_string / encode_error are the wire format, described next. A full working version is in examples/plugins/hello-wasm/src/lib.rs.

The same function in C, compiled with clang --target=wasm32 -nostdlib, is the proof that nothing above is Rust-specific:

guest.cc · same contract
static unsigned char OUT[65536];

// The host calls alloc(len) and writes the request there.
__attribute__((export_name("alloc")))
unsigned int alloc(unsigned int len) {
    static unsigned char buf[65536];
    (void)len;
    return (unsigned int)(unsigned long)buf;
}

__attribute__((export_name("dealloc")))
void dealloc(unsigned int ptr, unsigned int len) { (void)ptr; (void)len; }

// hello_greet(name) -> string: tag 4, u32 len, utf8.
__attribute__((export_name("hello_greet")))
long long hello_greet(unsigned int ptr, unsigned int len) {
    const unsigned char *req = (const unsigned char *)ptr;
    // req[0] = argc, req[1] = tag 4, req[2..6] = u32 len, then the bytes.
    unsigned int n = *(const unsigned int *)(req + 2);
    const char *name = (const char *)(req + 6);

    unsigned int o = 0;
    OUT[o++] = 4;                       // tag: string
    unsigned int at = o; o += 4;          // length, patched below
    const char *p = "Hello, ";
    while (*p) OUT[o++] = *p++;
    for (unsigned int i = 0; i < n; i++) OUT[o++] = name[i];
    OUT[o++] = '!';
    *(unsigned int *)(OUT + at) = o - at - 4;
    (void)len;

    return ((long long)(unsigned int)(unsigned long)OUT << 32) | o;
}
Can I write a WASM plugin in Spid3r itself? Not yet, and this page will not pretend otherwise. Spid3r compiles to WebAssembly only as its own runtime — web/spid3r.wasm is the interpreter, and bundle --target wasm wraps a program around it. There is no code generator that emits a module exporting alloc and your functions, so today a sandboxed plugin has to come from a language that does. Writing one in Spid3r is the obvious next step, not a current feature.

Build it

The only requirement is that the output is a wasm module exporting the five symbols. Rust is one toolchain:

shellbash
# Cargo.toml needs: crate-type = ["cdylib"]
rustup target add wasm32-unknown-unknown
cargo build --target wasm32-unknown-unknown --release

# the module must sit next to plugin.toml
cp target/wasm32-unknown-unknown/release/my_plugin.wasm plugin.wasm

# or, with C — same contract, no Rust involved
clang --target=wasm32 -nostdlib -Wl,--no-entry -Wl,--export-dynamic \
      -o plugin.wasm guest.c
Commit the .wasm. A plugin directory is meant to be droppable onto a machine that has no wasm toolchain. The repository's own test fails if the committed module is stale or is not a WebAssembly binary.

07 The wire format

Six types, little-endian, and nothing else crosses.

A typed binary encoding rather than JSON: a guest would otherwise have to ship a JSON parser into the sandbox, which is a large attack surface for a value set only six types wide.

grammartext
request  := u8 argc, argc × value
response := value | (0xFF, u32 byte_len, utf8 message)

value := u8 tag, payload
  0  null      (no payload)
  1  int       i64
  2  float     f64
  3  bool      u8 (0 or 1)
  4  string    u32 byte_len, utf8 bytes
  5  list      u32 count, count × value
Rule Why
A response must be fully consumed trailing bytes mean the guest and host disagree; that is an error, not slack
A claimed length is bounds-checked before allocating the guest controls the number, so an 8 MiB ceiling is enforced up front
A map, class or closure is refused by name a plugin boundary is the wrong place to guess a type
An error is a tag, not a trap Err(...) from a plugin becomes a catchable script error
Versioning. The format is part of ABI v1. Changing a tag is an ABI change, and a plugin built against a different contract is rejected at registration rather than misinterpreted.

08 How it works

From plugin.toml on disk to a call inside a running program.

Discovery

The CLI scans the plugin search path for directories containing plugin.toml, sorted so the load order is deterministic.

Validation, before any plugin code runs

The manifest is parsed and checked: ABI string, every function declared, arity agreeing, every permission announced, no duplicate names, no shadowing a builtin.

Backing

A host plugin's start() runs. A WASM plugin is compiled and instantiated against an empty linker, which is its sandbox.

Merge

Functions land in the registry as either a fn pointer or a closure. native_defs() returns builtins plus both, and every engine installs from that one list.

Call

A script call reaches the function like any builtin. For a WASM plugin the host encodes the arguments, writes them into linear memory, invokes the export, and decodes the response.

Why a WASM function is a closure, not a fn pointer

A builtin native is (&'static str, fn(&NativeCtx, Vec<Value>) -> Result<Value, String>) — a bare function pointer, which cannot capture a guest instance. So the registry holds both forms: fn pointers for host plugins, Arc<NativeClosureFn> for WASM. Both engines already knew how to call a Value::NativeClosure, so making a WASM plugin available on the bytecode path was a twelve-line change, not a new calling convention.

Why not dlopen? A native function is a Rust pointer over Value, and Value is a reference-counted enum with no stable layout. Handing it across a C ABI boundary would need a serialisation hop — which is exactly what the WASM route does, with a sandbox for free.

09 Discovery

Where the toolchain looks, in order.

# Root Use it for
1 SPID3R_PLUGINS a ;-separated list of directories that contain plugin directories — pin an exact set in CI
2 [modules] plugins in spid3r.ini a ;-separated list of plugin parent directories configured persistently in spid3r.ini (or via spid3r-control.exe)
3 ./plugins a project-local set, committed with the project
4 <exe>/plugins the installed layout, next to spid3r.exe
5 ~/.spidr/plugins a per-user set
shellbash
# a semicolon-separated list of directories that contain plugin directories
export SPID3R_PLUGINS="./plugins;/opt/spid3r/plugins"

# then any program can call the plugin's functions
spid3r run app.matrix
Command Loads plugins?
run, check, compile, exec, test, bench, debug, gui, repl, magicyes
build, distno — a native executable cannot link one
fmt, version, lsp, package commandsno — they never run a program

A plugin that fails to load is a warning, not a fatal error. One broken plugin in a shared directory must not stop the toolchain from running a program.

Kind Needs the plugins-wasm feature?
matrixNo — works in the zero-dependency build
wasmYes (on by default; --no-default-features drops it)
hostN/A — compiled in, never discovered on disk

10 Permissions & fuel

What a filter can do, and what only a sandbox can do.

The permission gate & spid3r.ini

A function may declare a permission. A host that calls Engine::deny(Capability::Environment) — or a host configured with [security] deny_environment = true (or --sandbox) — replaces every function declaring environment, builtin or plugin, with a stub that returns a catchable error. In spid3r.ini (and the Safety tab of spid3r-control.exe), modules.allow_wasm = false disables loading .wasm plugins from disk and modules.allow_host = false disables registering Rust host plugins; both keys are frozen against remote changes.

app.matrixspid3r
fn main() {
    try {
        println(hello_env("PATH"));
    } catch (e) {
        // capability denied: 'hello_env' is not available to this script
        println("blocked: " + e);
    }
    return 0;
}
This is a policy filter, not a sandbox. It stops a script from calling the function. It does not constrain the plugin: a host plugin could call std::env::var whether or not it declared anything. Only the WASM route removes the capability itself.

Fuel

Every WASM call gets a fuel budget — 50 million instructions by default, or the host's tighter limit. A loop {} traps instead of hanging the interpreter, and the trap arrives as a catchable script error. This is the one place a limit is enforceable below the language.

Limit Value Applies to
fuel per call50,000,000 instructionsWASM
payload size8 MiB each directionWASM
arguments per call255both

11 Limits

What does not work, stated up front.

Limitation Consequence
A native executable cannot link a plugin spid3r build on a program that calls a plugin function is a compile-time error with a note explaining why — not a binary that throws at run time.
The spid3r binary ships with no host plugins spid3r run loads matrix and wasm plugins from disk. A host plugin needs a Rust binary that registers it.
A WASM guest cannot import anything no filesystem, clock, randomness, network or environment — by design, not by omission
Only six value types cross a map or class instance is refused by name rather than coerced
A Spid3r plugin is not sandboxed it is script code: it can call the same builtins your program can. Being a plugin does not reduce its authority
No plugin unloading a registered plugin lives for the process; stop() ends its lifecycle but does not free it
FFI is AOT-only extern fn resolves at link time, so spid3r run rejects it with error[usage]. int, float, bool, string, ptr, and usize cross the boundary (see docs/FFI.md)

12 Reference

The API surface, in one place.

Rust

Item Signature
plugin::register(Box<dyn PluginHost>) -> Result<(), String>
plugin::register_matrix(&Path) -> Result<(), String> — load a .matrix plugin
plugin::register_wasm(&Path) -> Result<(), String> — load a .wasm plugin
plugin::load_all() -> Vec<String> — discover on the search path, return warnings
plugin::shutdown_all() -> Vec<String> — stop every started plugin
plugin::list() -> Vec<PluginInfo> — what is registered, and its state
PluginHostmanifest(), functions(), start(), stop()
PluginFnDefname, arity, permission, func
Engine::deny(Capability) -> Engine — stubs every native declaring it; plugin functions with a matching permission are blocked at call time, regardless of registration order

Capabilities

Name Covers
filesystemread_file, write_file, file_delete, …
processspawning and process control
networksockets and HTTP
environmentenvironment variables, clock

Source map

Path What lives there
src/plugin/mod.rsregistry, lifecycle, discovery, registration rules
src/plugin/manifest.rsthe plugin.toml parser
src/plugin/abi.rsthe wire format
src/plugin/wasm.rsthe wasmi host: sandbox, fuel, calls
examples/plugins/hello-matrixSpid3r-source (kind = "matrix") plugin sample
examples/plugins/hello-hosthost plugin sample
examples/plugins/hello-wasmWASM plugin sample, with its built module
tests/plugin_api.rsregistration, lifecycle, permission gate
tests/plugin_wasm.rsdiscovery, execution, fuel, AOT refusal

13 Troubleshooting

The errors you will actually hit.

Symptom Cause and fix
unknown name 'hello_greet' under spid3r run The plugin was not discovered. Check that SPID3R_PLUGINS points at the directory containing the plugin directory, not at the plugin itself.
targets ABI '…' but this build implements 'spid3r-plugin-abi-1' The manifest's abi is wrong or missing. It must match exactly.
does not export it as (i32, i32) -> i64 The module is missing the export, or it has the wrong signature. A function's export name must equal its manifest name.
cannot instantiate (it must not import host functions) The module imports WASI or anything else. The sandbox has no imports to give it.
failed: … fuel The call exhausted its budget. Raise it, or make the guest terminate.
declares 'greet' but the file does not define it A [[function]] names a function the .matrix file does not define. It must be a public fn at the top level.
takes 1 parameter(s) but plugin.toml declares 3 The arity in the manifest disagrees with the file. The manifest is the contract.
kind = "host" must be compiled into its host A host plugin was placed on the disk search path. Host plugins are Rust; only kind = "matrix" and kind = "wasm" load from disk.
disabled by configuration (modules.allow_wasm = false) WASM (or host) plugins are restricted in spid3r.ini or the Safety tab of spid3r-control.exe. Enable modules.allow_wasm = true / modules.allow_host = true on the host.
would shadow a builtin A function is named like println or write_file. Builtins cannot be intercepted.
Build fails with a plugin note Expected: a standalone executable cannot link a plugin. Use spid3r run, or ship a host binary.

14 Checklist

Before you ship a plugin.

  • You picked the kind on purpose: matrix by default, wasm for code you did not write, host only when the plugin must be Rust.
  • abi is exactly spid3r-plugin-abi-1.
  • Every function you offer is declared, with a matching arity.
  • Every permission appears in capabilities.
  • No function name collides with a builtin or with another plugin.
  • For WASM: entry is set, plugin.wasm is committed, and the module exports memory, alloc and one export per function.
  • For WASM: the guest terminates — the fuel budget is a backstop, not a design.
  • For host: start() can fail without taking the host down, and stop() is safe to call twice.
  • You have decided what happens under spid3r build (it will refuse — say so in your README).
Next: read docs/PLUGINS.md for the full contract, or open examples/plugins/hello-wasm and change one function to see the whole loop.