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.
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.
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.
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.
[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
// 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:
fn main() {
println(greet("Ada"));
println(sum_to(10));
}
# 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.
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.
# 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. |
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:
# 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.
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.
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
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 |
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/
├── 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.
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.
// 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:
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;
}
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:
# 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
.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.
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 |
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.
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 |
# 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, magic | yes |
build, dist | no — a native executable cannot link one |
fmt, version, lsp, package commands | no — 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? |
|---|---|
matrix | No — works in the zero-dependency build |
wasm | Yes (on by default; --no-default-features drops it) |
host | N/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.
fn main() {
try {
println(hello_env("PATH"));
} catch (e) {
// capability denied: 'hello_env' is not available to this script
println("blocked: " + e);
}
return 0;
}
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 call | 50,000,000 instructions | WASM |
| payload size | 8 MiB each direction | WASM |
| arguments per call | 255 | both |
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 |
PluginHost | manifest(), functions(), start(), stop() |
PluginFnDef | name, 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 |
|---|---|
filesystem | read_file, write_file, file_delete, … |
process | spawning and process control |
network | sockets and HTTP |
environment | environment variables, clock |
Source map
| Path | What lives there |
|---|---|
src/plugin/mod.rs | registry, lifecycle, discovery, registration rules |
src/plugin/manifest.rs | the plugin.toml parser |
src/plugin/abi.rs | the wire format |
src/plugin/wasm.rs | the wasmi host: sandbox, fuel, calls |
examples/plugins/hello-matrix | Spid3r-source (kind = "matrix") plugin sample |
examples/plugins/hello-host | host plugin sample |
examples/plugins/hello-wasm | WASM plugin sample, with its built module |
tests/plugin_api.rs | registration, lifecycle, permission gate |
tests/plugin_wasm.rs | discovery, 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:
matrixby default,wasmfor code you did not write,hostonly when the plugin must be Rust. abiis exactlyspid3r-plugin-abi-1.- Every function you offer is declared, with a matching
arity. - Every
permissionappears incapabilities. - No function name collides with a builtin or with another plugin.
- For WASM:
entryis set,plugin.wasmis committed, and the module exportsmemory,allocand 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, andstop()is safe to call twice. - You have decided what happens under
spid3r build(it will refuse — say so in your README).
docs/PLUGINS.md for the full contract, or open
examples/plugins/hello-wasm and change one function to see the whole loop.