# Working on Sausage

Sausage is meant to be read and changed by agents, including its own agent.
Keep it that way.

## Priorities

1. **Correct.** Every behavior in `PROTOCOL.md` has a test in `cli/tests/`.
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 call.
5. **Raw and minimal.** Sausage has no permissions, sandboxing beyond WASI,
   limits, or authentication. Do not add them to the core. Add nothing to
   the host that a plugin (or the agent, by changing itself) could do.

## Layout

- `cli/`: the host (`sausage` binary and library): the core, the native
  `cargo` plugin, the WASI test runner, and the console.
- `vfs/`: `sausage-vfs`, the virtual filesystem for WASI guests. It knows
  nothing about Sausage.
- `interface/`: `sausage-interface`: OpenRPC documents, the compatibility
  check, and the generator of client code.
- `sdk/`: `sausage-plugin`, the SDK for Rust plugins, and `sdk/macros/`, its
  macros. Never published: `cargo` points `sausage-plugin = "0.1"` at its
  local copy.
- `agent/`: the agent plugin. `sausage init` embeds and builds it.
- `examples/`: small plugins. They are not workspace members.
- `PROTOCOL.md`: the contract between the core and the plugins. Change it in
  the same commit as the behavior. `DECISIONS.md` says why; when the two
  disagree, `PROTOCOL.md` and the code win.

## Checks

```sh
nix flake check -L      # everything below, plus the stress tests; CI runs this on every push
nix develop -c cargo test --workspace     # fast with a warm cache: run it during development
nix develop -c cargo build --release -p agent --target wasm32-wasip2
nix develop -c cargo clippy --workspace
```

`nix run -- init` and `nix run -- run` must keep working without other
setup.

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. `#[ignore]` is
only for stress tests: `nix flake check` runs them with `--include-ignored`.
Tests that build plugins use the persistent cache in
`env!("CARGO_TARGET_TMPDIR")`.