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

Correct. Every behavior has a test.
Simple and short. Prefer the obvious code. No abstraction for one caller. No configuration that nobody asked for.
Readable. A new reader must understand a file without the others. Each module starts with a doc comment that says what it owns.
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

Host integration tests share one executable:

cargo test -p sausage --test it
cargo test -p sausage --test it -- chain::

Use the required Nix environment and build slot wrapper for these commands. Add test modules under host/tests/it/ and declare them in it/main.rs. Use fully qualified child test filters with --exact. See host/tests/README.md for fixture and isolation details.

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.

3.6 KiB Raw Blame History