sausage/AGENTS.md

Working on Sausage (v3)

Sausage is a world of WASI programs and durable agents. It is meant to be read and changed by agents, including its own. Keep it that way.

This branch (v3) rebuilds Sausage. The plan and its decisions (D1, D2, …) are in ~/research/sausage-v3/PLAN.md. PROTOCOL.md, DECISIONS.md and README.md still describe v2.

The boundary

• The world is the sandbox. Everything inside the world sees and changes the whole world. Do not add inner boundaries, permissions or per-agent views. The VFS is a safety net against mistakes, not a wall against attackers.
• Host calls pierce the sandbox. The only host import beyond standard WASI is the process interface (spawn, wait, kill). Do not add another one. Everything else uses standard WASI 0.2 interfaces: files through the VFS, wasi:http (the host API on its reserved host name, credential injection, signing), and wasi:sockets.
• The credentials manager in the host is the one real security boundary. Secrets never enter the world. Approvals need a passkey.
• Native code is the exception. The only native work for the world is the Rust builder, and it runs in user, mount and network namespaces.

Priorities

1. Correct. Every behavior has a test.
2. Simple and short. Prefer the obvious code. No abstraction for one caller. No configuration that nobody asked for.
3. Readable. A new reader must understand a file without the others. Each module starts with a doc comment that says what it owns.
4. Efficient on the paths that run per command and per model turn.

Layout

• host/: the host crate (package and binary sausage): the world, the process table, the harness. host/src/exec.rs is the contract between the harness and the process table.
• vfs/: sausage-vfs, the virtual filesystem for WASI guests and for host code. It knows nothing about Sausage. Host code reads and writes the world only through it.
• userland/: the default CLIs of a world, a separate workspace built for wasm32-wasip2.
• spikes/: accepted prototypes. Read them for evidence, copy from them, do not build on them.
• cli/, interface/, sdk/, agent/, examples/: v2 code, outside the workspace. Copy what v3 needs. They are deleted at the end of P1.

Programs in the world

• Agents write CLIs and servers. That they are WASI binaries is a detail, not a concept to explain.
• The platform is WASI 0.2 components. Rust programs build for wasm32-wasip2. WASI 0.1 programs run through an adapter.

Checks

nix develop -c cargo test --workspace     # host and vfs
nix develop -c cargo clippy --workspace --all-targets -- -D warnings
nix develop -c cargo build --manifest-path userland/Cargo.toml --release

nix flake check still describes v2 and is updated later in P1.

Tests must stay fast:

• Only a few tests may wait for a timing (grace periods, deadlines).
• Poll for a condition with a deadline. Do not sleep.
• Do not test unrealistic load, such as many fast cycles.
• #[ignore] only disables a test for a short time, with the reason in the attribute.
• Tests that build or compile guests use a persistent cache (for example under env!("CARGO_TARGET_TMPDIR")), so a warm run does not compile again.