sausage/DECISIONS.md

Decisions

This file lists the design decisions of the spike. (you) marks a decision that Surma made. (spike) marks a decision that Scout made alone during the night and that needs review.

Architecture

• (you) Actors are WASI commands (wasm32-wasip2). They use stdin, stdout, files, and HTTP. No WIT interfaces, no component composition.
• (you) Actors exchange newline-delimited JSON through the host, which is the broker. No built-in request/response. A reply is a message with reply_to. Delivery is at most once.
• (you) The broker accepts only .wasm files. It knows no source language.
• (you) cargo is a built-in Rust compiler actor. (spike) It is native (host code), because cargo cannot run inside WASM.
• (you) The agent is a normal WASM actor with the fixed ID agent. It can read and upgrade its own source.
• (spike) Three native actors: broker, console, cargo.
• (you) One Cargo workspace with two crates: cli (binary sausage) and agent. (spike) Example actors are in examples/, outside the workspace.
• (you) sausage init builds the agent and asks for the API shape, the endpoint, the model, and the token. (spike) The token can also come from SAUSAGE_API_TOKEN. The source contains no endpoint and no token.

Messages

• (spike) Stdin line: {"id", "from", "reply_to"?, "body"}. Stdout line: {"to"?, "id"?, "reply_to"?, "body"}.
• (spike) The broker sets from. An actor can choose its own id. The broker then uses "<sender>/<id>", so IDs cannot collide or be faked. Without an id, the broker assigns m-<n>.
• (you) Without to, a message goes to the subscribers of the sender. (spike) subscribe / unsubscribe messages to the broker. The registry stores subscriptions, so they survive restarts and upgrades. init subscribes console to agent.
• (spike) Errors from routing come back as {"type": "undeliverable", "reason", "to"} from broker.
• (spike) Lifecycle: {"type": "shutdown"} from broker, then EOF on stdin. After 5 seconds the broker kills the instance.
• (spike) Lines on stdout that are not JSON objects with body go to the actor's stderr.log with a note.

Filesystem

• (you) /data private, /public own public files, /actor/<id>/public and /actor/<id>/source read-only for everyone.
• (spike) The broker also writes /actor/<id>/status.json and /actor/<id>/stderr.log. ls /actor is the registry.
• (you) Commit on close: a write becomes visible only when the writer closes the file. (spike) This also applies to /data. Implementation: a wrapper around the wasmtime-wasi filesystem. An open for write goes to a hidden .sausage-tmp-* file next to the target. The descriptor drop renames it into place. Details:
  • A normal exit commits every open file (process exit closes files).
  • A trap or kill discards uncommitted writes.
  • An append or an edit without truncate copies the old content first.
  • Other descriptors see the old content until the close.
  • Directory operations take effect immediately.
  • The layer hides .sausage-tmp-* names from listings, stat, open, rename, and unlink.
  • Symlinks are disabled (they would break the path tracking).
  • No fsync. A power loss can lose committed data.
• (spike) Raw sockets are not available (no network permission), but the wasi:sockets interfaces are linked, so programs that import them still start.

Broker requests

• (spike) spawn, upgrade, rollback, stop, start, remove, subscribe, unsubscribe, list.
• (you) spawn and upgrade take wasm, plus optional source and built_by metadata. (spike) The broker copies the .wasm file and the source folder into broker/versions/<id>/<n>/, with meta.json (paths, builder, requester, time).
• (spike) Path resolution: /actor/... is global, and /public/... and /data/... belong to the sender. .. is rejected. Native senders (the console) can give absolute host paths.
• (you) Anyone can upgrade anyone. No permissions.
• (spike) Actor IDs: a-z, 0-9, -, _, at most 64 characters.
• (spike) remove archives every folder of the actor to archive/. Nothing is deleted.

Upgrades, tests, rollback

• (spike) The tests are message transcripts in source/tests/*.jsonl: {"send": body} and {"expect": subset-of-body, "to"?}. Each file runs in a fresh candidate on a copy of the actor's /data and /public. The candidate has no HTTP access. An expect waits up to 10 s. Without tests, the candidate must stay up for 2 s (smoke test).
• (spike) Swap: hold the mailbox, stop the old instance gracefully, snapshot /data + /public into the old version's folder, install the new source in /actor/<id>/source, start the new instance, release the mailbox.
• (spike) Restart after a crash: backoff 0.5 s × 2ⁿ, at most 30 s. The counter resets after 60 s of uptime.
• (spike) Parked message: when an instance traps, the broker keeps the last delivered message. It delivers that message again after the next upgrade, not after a plain restart (that would loop).
• (spike) Crash loop: 3 crashes within 30 s after an upgrade → automatic rollback to the previous version, with its data snapshot. The broker informs the actor that requested the upgrade.
• (spike) rollback without version goes to the highest older version. It restores that version's snapshot, and it first snapshots the current state, so a roll-forward is possible.
• (spike) Versions are per actor, not global.

Limits

• (spike) Mailbox: 1,000 messages. When it is full, the sender gets undeliverable.
• (spike) The broker waits 30 s when it writes to an actor's stdin. Then it drops the message and logs it.
• (spike) Time slices: the epoch advances every 10 ms, and each guest yields at each epoch.
• (spike) One sausage run per world (file lock on world/.lock).
• (spike) HTTP for all running actors, with no allow-list yet.

Agent

• (you) API shapes: OpenAI Responses and Anthropic Messages, chosen by "api" in /data/config.json.
• (spike) Config fields: api, base_url, model, token, optional reasoning_effort and max_tokens (16,000). OpenAI: POST {base_url}/v1/responses with store: false and encrypted reasoning passed back. Anthropic: POST {base_url}/v1/messages with x-api-key.
• (spike) One shared conversation in /data/history.json, in a neutral format, so the API shape can change. The history is limited to 600 entries, with the cut at a user message. There is no compaction yet.
• (spike) A turn starts only for {"type": "text"} messages without reply_to. Replies never start turns, so two actors cannot keep the agent in an endless loop. Other messages are collected and shown at the next turn.
• (spike) Tools: send_message (with optional wait for the reply), wait_for_messages, read_file, list_dir, write_file, copy_dir, remove_path. At most 40 steps per turn. Tool output is cut at 30 KB.
• (spike) The final text of a turn goes to the sender, as a reply to the message that started the turn.
• (spike) A shutdown during a turn saves the turn to /data/turn.json. The next start (for example after a self-upgrade) resumes the turn and answers the original message.

Console

• (spike) @<actor> <json|text>, plain text to agent, /deploy, /list, /sleep, /await, /help, /quit. /sleep and /await exist for scripted tests.

Known risks (accepted for now)

• Build scripts and proc macros run as native code in the host environment.
• Any actor can upgrade the agent with code that reads the token.
• Any actor can message, stop, upgrade, or remove any actor.
• A full copy of /data and /public at every upgrade is slow for large data.
• Mailboxes are in memory. A host crash loses queued messages.