# 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

```sh
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.