sausage/DECISIONS.md

Decisions

Why Sausage is the way it is. PROTOCOL.md and the code own the details. When this file disagrees with them, they win.

The shape

• JSON-RPC, not component interfaces. Every language can read and write lines of JSON, and models know JSON-RPC from LSP and MCP. A call has a result, like an LLM tool call.
• A process per call. WASI has no threads, so processes give parallelism. A new version applies at the next call, and old processes retire after a grace period.
• Attached by default. A process does not outlive its caller by accident. A long-running process must ask for detach.
• Services in one file. Only the core starts and restarts them, so upgrades and singletons need no logic in plugins.
• Files to inspect, calls to act. This keeps the core API small, and the agent's file tools are enough to explore the world.
• The core accepts only .wasm files. It knows no source language. cargo is one way to get a .wasm file.
• The world folder is the source of truth. Copy a plugin folder into another world, and it works there.
• The agent is a normal plugin. It can read and upgrade its own source, and change how it does inference.

Interfaces

• Generated imports and interface checks, without version numbers. A model that translates a description by hand makes errors. A generator does not. The check catches the most common error in a world that changes itself: a change to one plugin breaks another one.
• A small schema subset. With Draft 7 and a fixed subset, our own check can decide every case. It never has to guess.
• Docs are part of the interface. Other agents work from them, so the SDK requires a doc comment on each method, type, and field.
• The check covers calls, not state. Old and new versions share /state. A plugin keeps its state format compatible, or migrates it in rpc.retired.

Minimal on purpose

The core does only what a plugin cannot do for itself. Everything else can be a plugin, or a change that the agent makes to itself.

• No permissions, no limits, no hiding. Any process can call, upgrade, or stop any plugin, read and write every file, and use the network. The checks protect against mistakes, not against plugins. Locks are advisory.
• Locks are in the core. A plugin cannot see that another process died, so it cannot release that process's lock. The core can.
• Our own VFS, in its own crate. It works on Linux and macOS, it makes /proc live, and plugin-served files need it later. Mounts now, overlays later.
• TCP endpoints for now. They need no host code. VFS pipes can replace them later behind the same SDK API.
• Simple scheduling for now. An epoch tick every 10 milliseconds keeps the core responsive and makes kills reliable.
• The agent is dumb. It has a short prompt, a few tools, an append-only history that it sends in full, and no compaction. When the context is too large, it stops sending the oldest turns, so it never gets stuck.

Small choices

• Restart is a clean stop supervised by #loop. core.restart requires the host startup marker SAUSAGE_LOOP=1, which the loop exports for its invocation. Without a supervisor, restarting would only stop the world. A single pending request answers first, allows 250 ms for delivery, then signals the existing shutdown path; it does not use process::exit or bypass detached-process cleanup, lock release, or journal draining. The executable returns dedicated restart code 75 after cleanup. #loop refreshes and starts again on 75 (and other nonzero exits); 0 stops it. core.exit is a compatibility alias with the same supervisor gate, response grace, and coalescing; new callers use core.restart. HARD RULE: the mediator and all agents NEVER call core.restart without the person's explicit approval each time. This approval rule also covers legacy core.exit; it must not bypass the gate.

• YAML for configuration, JSON for data. A person edits configuration, so it needs comments. init writes commented templates instead of asking questions, so there is one way to configure a world.

• Plain POSIX files. Programs like tempfile, git, and SQLite expect normal files. Atomic writes use a temporary file and rename.

• Tests run under WASI. cargo test on the host cannot find failures that occur only in WASI, for example a missing WASI function or a panic at start. The test runner uses the same Wasmtime and the same mounts as the core.

• The SDK is not published. cargo points sausage-plugin = "0.1" at its own copy, which it also shows in /plugins/cargo/sdk/.

• Compiled code is a cache, not state. It lives outside the world, in one cache folder that all worlds share: wasmtime/ (owned by Wasmtime, whose cleanup deletes unknown entries), cargo-target/, and sdk/<hash>/. A path that depends only on the content of the SDK lets cargo reuse the compiled SDK in every world. Tests run in the release profile, so that they share compiled crates with the release build.

• mold links host code where Nix provides it. On Linux, the dev shell, the Nix builds, and the packaged sausage (for the proc macros and build scripts of plugins) link with mold, much faster than GNU ld. Plugins for wasm32-wasip2 link with rust-lld. Without Nix, the default linker stays.

• No LTO. Measured: fat LTO makes the binary 28 % smaller, but compiles plugins and answers calls at most 5–8 % faster, for 4 more minutes per release build. Thin LTO brings nothing.

• Discovery has a deadline of 10 seconds. It is an internal call of the core, not a limit on plugins. Without it, one plugin that does not answer would block every activation.

• A broken plugin blocks nobody. A plugin without a document is already broken, so the check cannot protect it. The graph shows it as "unavailable", and core.revert and force always work.

• rpc.retired is best effort. It does not run if the host stops first. A persistent queue of retirements would be more core for a rare case, so a new version checks its own migration marker instead.