PROPOSAL.md: results of the review, no mention of the old model

Upgrades retire old processes after a grace period, then call rpc.retired. Services live in boot.json. One preopen / with a mount table in the sausage-vfs crate, with guards for in-flight file operations. Draft 7 and our own compatibility check on a fixed subset. Imports register with inventory. Rules for liveness, stop states, routing, locks, activation, endpoints (rpc.endpoint handshake), boot, builds, and a 10 ms scheduling tick.
PROPOSAL.md: plugins, processes, and JSON-RPC
2026-10-22 23:27:08 +01:00 · 2026-10-22 20:58:30 +01:00 · 2026-10-22 20:16:38 +01:00 · 2026-10-22 13:35:13 +00:00 · 2026-10-22 13:29:38 +00:00 · 2026-10-22 10:50:15 +01:00
18 changed files with 1309 additions and 71 deletions
@@ -0,0 +1,915 @@
+# Proposal: plugins, processes, and JSON-RPC
+
+Status: a proposal on the branch `plugins`. When we accept it, its content
+goes into `PROTOCOL.md` (the contract) and `DECISIONS.md` (the reasons).
+Then this file goes away.
+
+## 1. The idea
+
+Sausage is a world of small WASI programs that an agent grows by talking to
+it. The design uses three ideas that models already know:
+
+1. **JSON-RPC calls.** A call has a result, like an LLM tool call. LSP and
+   MCP use the same protocol.
+2. **Processes.** Each call to a plugin starts a new WASI process. WASI has no
+   threads, so processes are the unit of parallelism. Calls are asynchronous,
+   so one process can make many calls at the same time.
+3. **Files to inspect, calls to act.** The core shows its state as virtual
+   files in `/proc`, like Plan 9 and Linux. Each change of state is a call.
+
+## 2. Terms
+
+| Term | Meaning |
+| --- | --- |
+| world | The folder that a `sausage` host runs. It is `/` for every process. |
+| core | The host. It runs processes, routes calls, serves the virtual files, and keeps the journal. |
+| plugin | A folder `/plugins/<name>/` with a `plugin.wasm`. A plugin does not run by itself. |
+| process | One run of a plugin version. Its ID is `<plugin>-<uuidv7>`, for example `notes-0197f3a2-7c1e-7d2b-9a41-5f0c2e8b1d34`. |
+| call | A JSON-RPC request. `notes.add` calls the method `add` of the plugin `notes`. |
+| interface | A set of methods. A plugin has one main interface. It can also declare endpoint interfaces. |
+| endpoint | An interface that a running process serves on a TCP port. An endpoint file tells others where it is. |
+| service | A call in `/config/boot.json`. The core starts it at boot and again after an upgrade of its plugin. |
+| import | An interface of another plugin that a plugin uses. The SDK generates it from that plugin's description. |
+| provider, consumer | The plugin that has an interface, and a plugin that imports it. |
+| journal | The central log of the world. |
+
+## 3. The world folder
+
+```text
+<world>/
+  plugins/<name>/
+    plugin.wasm               the current version
+    plugin.prev.wasm          the version before, for `core.revert`
+    source/                   the source. `cargo.build` builds it from here.
+      imports/<plugin>.json   descriptions of the imported plugins
+  state/<plugin>/             persistent state of a plugin, by convention
+  state/core/journal.sqlite   the journal
+  config/                     global configuration
+    boot.json                 the services
+    agent.json                API, base URL, model, and token of the agent
+```
+
+- Every process can read and write all of it. There are no permissions.
+- The world folder must not contain `proc`, `run`, or `self`. These names are
+  mount points (section 5). The host does not start a world that has them.
+
+## 4. Calls and processes
+
+### 4.1 The protocol
+
+- JSON-RPC 2.0 on stdin and stdout, one message per line, as in MCP's stdio
+  transport.
+- A line is a message only if it is a JSON object with `"jsonrpc": "2.0"`.
+- The core discards every other line on stdout. For the first discarded line
+  of a process, it writes one warning to the journal, without the content of
+  the line. Logs go to stderr.
+- Each line on stderr goes to the journal.
+- `params` is always an object. Batches are not supported.
+- The SDK writes each message with one blocking write through std's stdout,
+  and it writes a newline before each message. So a `print!` without a
+  newline cannot damage a message.
+
+### 4.2 Method names
+
+- A method name has the form `<target>.<method>`. The core splits it at the
+  first `.`.
+- Plugin names use `a-z`, `0-9`, `-`, and `_`. The name `core` is reserved.
+- `notes.add` starts a new process of `notes` and sends it the request `add`.
+  `notes.rpc.discover` sends it `rpc.discover`.
+- `core.<method>` is a method of the core (section 10).
+- Method names that start with `rpc.` are reserved: `rpc.discover`,
+  `rpc.retired`, and `rpc.endpoint`.
+
+### 4.3 What a call does
+
+1. The core gives the call a UUIDv7 and starts the process `<plugin>-<uuid>`
+   with the current version of the plugin.
+2. The core writes the request to the stdin of the process. The request ID is
+   the process ID.
+3. The process writes the response to stdout. The core sends the response to
+   the caller, with the caller's request ID.
+4. If the process ends before it answers, the caller gets the error -32002.
+   Its `data` has the exit status and the last journal lines of the process.
+   Before the core decides this, it reads the stdout of the process to the
+   end.
+
+- A process can write calls to stdout at any time, to the core and to
+  plugins. The responses come on stdin. A process can have many calls in
+  flight.
+- The core keys each pending request by the process and the exact JSON ID.
+  The core drops a response with an unknown or late ID. The SDK writes a note
+  about such a response to stderr.
+- A notification to `plugin.method` (without an ID) starts an attached
+  process. That process gets the notification without an ID, and nobody gets
+  a result.
+
+### 4.4 Detached calls
+
+`core.call {"method": "www.start", "params": {...}, "detach": true}` makes the
+call and returns its result to the caller. The new process has no parent, so
+it does not end with its caller.
+
+Sent as a notification (without an ID), the same `core.call` starts the
+process and forgets it.
+
+### 4.5 Notifications to the caller
+
+A process can tell its caller about progress. It sends the notification
+`core.notify {"name": "text", "params": {...}}`. The core gives it to the
+caller as `core.notify {"call": <ID of the caller's request>, "name": "text",
+"params": {...}}`. After the call has ended, the core drops such
+notifications.
+
+So a process never needs to know who called it. Endpoint calls send their
+notifications over the endpoint connection (section 6).
+
+### 4.6 Lifetime
+
+A process lives while one of these runs:
+
+- a handler of a call,
+- a background task,
+- an endpoint that listens.
+
+The SDK's own reader of stdin does not count. When nothing of this runs, the
+SDK returns from `main`, and the process ends.
+
+A process has three states:
+
+1. **running**
+2. **stopping**: the core has closed stdin. EOF on stdin means "stop now".
+   - New calls of the process fail at once, and its pending calls fail.
+   - A stop hook can still write files and send notifications. It cannot
+     make calls, because no response can arrive.
+   - After 5 seconds, the core kills the process.
+3. **ended**: the core releases the locks of the process (section 7) and
+   removes its folder in `/proc`.
+
+Rules:
+
+- `core.stop {pid}` starts the stopping state. `core.kill {pid}` kills the
+  process at once.
+- When a process ends, the core stops each of its attached children. All
+  children stop in parallel, so a whole tree takes 5 seconds at most.
+- A detached process has no parent. Only `core.stop`, `core.kill`, an
+  upgrade (section 4.7), and the end of the host stop it.
+- At host shutdown, the core stops every process in parallel.
+
+Note: on Unix, children outlive their parent. Here, an attached child ends
+with its parent. Only `detach` makes a process independent.
+
+### 4.7 Upgrades
+
+A process is an instance of one plugin version. When a new version becomes
+active (section 11.3):
+
+1. New calls get the new version at once.
+2. Each process of an older version gets a grace period to finish its work.
+   The default is 60 seconds. A plugin can declare its own value in
+   `rpc.discover` (`x-sausage-grace`). Then the core stops the process.
+3. When the old process of a service has ended, the core starts the service
+   again with the new version.
+4. When the last process of an older version has ended, the core starts a
+   process of the new version and calls `rpc.retired {"previous":
+   "<sha256 of the older file>"}`. A plugin can use this hook to migrate its
+   state, or to write a marker that its other new processes wait for. The
+   result goes to the journal.
+
+During the grace period, an old process can call a method that a new
+provider no longer has. The time is limited, so this risk is acceptable.
+
+### 4.8 Environment and network
+
+- `SAUSAGE_PID`: the process ID.
+- `SAUSAGE_PLUGIN`: the plugin name.
+- `SAUSAGE_PARENT`: the parent: `console`, `core`, or a process ID.
+
+Every process gets the network: outgoing HTTP and HTTPS through `wasi:http`,
+and TCP, UDP, and DNS through `wasi:sockets`.
+
+### 4.9 Scheduling
+
+- Each process is a task on the core's multi-thread tokio runtime, with work
+  stealing.
+- A scheduler thread advances Wasmtime's epoch every 10 milliseconds. At
+  each tick, a process that computes yields to the runtime. So a busy process
+  cannot block the core or the other processes.
+- `core.kill` aborts the task. It takes effect at the next tick at the latest.
+- Most processes wait for IO most of the time. A better scheduler can come
+  later.
+
+### 4.10 Errors
+
+The standard JSON-RPC codes apply. The core adds these codes:
+
+| Code | Meaning |
+| --- | --- |
+| -32001 | There is no such plugin. |
+| -32002 | The process ended without an answer. `data` has the exit status and the last journal lines. |
+| -32003 | The activation was rejected. `data` has the reasons. |
+
+## 5. The filesystem
+
+Each process gets one preopen, `/`. The VFS resolves each path through a
+mount table:
+
+| Path | Layer | Access |
+| --- | --- | --- |
+| `/` | host: the world folder | read-write |
+| `/proc` | generated by the core | read-only |
+| `/self` | memory: the folder `/proc/<own pid>/` | read-write |
+| `/run` | memory, shared, empty at each host start | read-write |
+
+A listing of `/` shows `proc`, `run`, and `self`. A path from any folder
+descriptor goes through the same mount table.
+
+```text
+/proc/
+  core/
+    PROTOCOL.md          the contract
+    graph.json           plugins, imports, and the result of each check
+    graph.dot            the same graph for Graphviz
+    locks.json           held locks and waiting processes
+    plugins/<name>/
+      discover.json      the rpc.discover document of the current plugin.wasm
+      client.rs          the Rust code that import!("<name>") generates
+  <pid>/
+    info.json            plugin, version, method, params, parent, detached, start time, state
+    log                  the journal lines of this process
+    <files>              the files that the process writes to /self
+```
+
+Rules:
+
+- A process writes its own folder only through `/self`. Writes through
+  `/proc` always fail.
+- In a process folder, the names `info.json`, `log`, and `fs` belong to the
+  core. A write to `/self/info.json` fails.
+- A read of a generated file returns a snapshot that ends. For example,
+  `/proc/<pid>/log` returns the lines up to the time of the open.
+- The folder of a process goes away when the process ends. Its files are in
+  memory. Large or persistent data belongs in `/state`.
+- Do not send a `/self` path to another process. There it means a different
+  folder, like `localhost` on another machine.
+
+Principle: **inspect through files, act through calls.** A file read is
+cheaper than a call, and every language and tool can read a file.
+
+### 5.1 The VFS crate
+
+The VFS is a crate of its own, `sausage-vfs`, so that it can become public
+later. It knows nothing about Sausage.
+
+- One trait with the operations of a filesystem: stat, list, open, read and
+  write at an offset, set size, create a folder, remove, and rename.
+- The layers:
+  - **host:** a real folder, sandboxed with `cap-std`. Each file operation
+    runs in a blocking task. That task holds a guard of its process until
+    the system call has returned, even if the process was killed.
+  - **memory:** files and folders in memory.
+  - **generated:** files that a function makes at each open.
+  - **mounts:** sends each path to the right layer. Each process has its own
+    mount table, which shares most layers with the other processes.
+- An adapter implements `wasi:filesystem` for Wasmtime on top of the trait.
+  It replaces the filesystem of `wasmtime-wasi` completely.
+- Not now: overlays (a union of two layers). Deletes and renames across
+  layers need whiteouts and copy-up. The trait leaves room for overlays.
+- Tests:
+  1. Unit tests for each layer.
+  2. Differential tests: `proptest` generates sequences of operations. They
+     run on the host layer and on `std::fs` in a temporary folder, and the
+     results must be equal.
+  3. A model test for the memory layer.
+  4. WASI tests: Rust guests use `std::fs` through the adapter. `rusqlite`
+     and `tempfile` must work.
+
+## 6. Endpoints
+
+- `listen(path, interface)` binds a free port on 127.0.0.1. When the listener
+  is ready, it writes an endpoint file at `path`, in one atomic step. The
+  file has one line: the address, the owner, and the interface. Example:
+  `tcp:127.0.0.1:41234 www-0197… control`.
+- Usually the path is in `/self`. A service that others must find uses a
+  fixed path in `/run`, for example `/run/secrets`.
+- `connect(path)` reads the file and connects. Its first request is the
+  built-in `rpc.endpoint`, which returns the owner, the plugin, and the
+  interface. If they do not match the file, `connect` fails. So a stale file
+  or a reused port cannot connect a client to the wrong process.
+- If the file does not exist yet, `connect` waits a short time, for example
+  while the services start.
+- JSON-RPC runs on the connection, one message per line. In an endpoint
+  handler, `ctx.notify` sends the notification over the connection.
+- `listen` accepts only interfaces that the plugin declares (section 11.1).
+
+## 7. Locks
+
+- `core.lock {"path": "/state/notes/notes.json"}` returns when the caller
+  holds the lock.
+- Each acquisition gets its own place in a FIFO queue. The same process
+  cannot take one lock twice: its second acquisition waits behind its first.
+- With `"wait": false`, the call returns at once with `{"held": true}` or
+  `{"held": false}`.
+- `core.unlock {path}` releases the lock. The SDK sends it as a notification
+  when a guard drops. If the future of an acquisition was dropped, the SDK
+  releases the lock when the grant arrives.
+- When a process ends, the core releases all of its locks, also after a
+  crash or a kill. It waits until the last file operation of the process has
+  returned (section 5.1). So a write of a killed process cannot land after
+  the next process got the lock.
+- Locks are advisory. The core does not block writes to the file: the path
+  is only a name.
+- SQLite has no file locks in WASI. Hold the lock while the database is open.
+
+## 8. The journal
+
+- An SQLite file at `/state/core/journal.sqlite`. Only the core writes it.
+- Each entry has a UUIDv7 (it sorts by time), the process ID, the plugin, the
+  stream (`stderr` or `core`), and the line.
+- The core writes its own events too: start (with method and params), exit
+  status, stop, kill, upgrades, and the warning about discarded stdout.
+- `core.log {plugin?, pid?, since?, until?, grep?, limit?}` queries the
+  journal. `/proc/<pid>/log` shows the lines of one running process.
+- Later: structured logging, like `tracing`.
+
+## 9. Boot and services
+
+At start, the core starts each service in `/config/boot.json`, in order:
+
+```json
+[
+  {"method": "secrets.serve", "params": {}},
+  {"method": "www.start", "params": {"port": 8080}}
+]
+```
+
+- A service is a detached call. The core waits for its result before it
+  starts the next one. The result shows that the service is ready.
+- If a service fails, the core writes the error to the journal and continues.
+- After an upgrade of the plugin of a service, the core starts the service
+  again with the new version (section 4.7).
+- The core does not restart other detached processes.
+- A singleton is a service with a fixed endpoint in `/run`. Only the core
+  starts it, so two instances cannot start at the same time.
+
+## 10. The core API
+
+| Method | Params | Result |
+| --- | --- | --- |
+| `core.call` | `method`, `params`, `detach`? | the result of the method |
+| `core.notify` | `name`, `params` | none (a notification) |
+| `core.stop` | `pid` | `{}` when the process has ended |
+| `core.kill` | `pid` | `{}` |
+| `core.lock` | `path`, `wait`? | `{"held": bool}` |
+| `core.unlock` | `path` | none (a notification) |
+| `core.activate` | `plugin` and `wasm`, or `plugins: [{plugin, wasm}]`. `force`? | the new `rpc.discover` documents |
+| `core.revert` | `plugin`, `force`? | like `core.activate` |
+| `core.log` | filters (section 8) | journal entries |
+| `core.exit` | none | `{}`. Then the host stops with exit code 75. |
+
+Everything else is a file.
+
+## 11. Interfaces
+
+### 11.1 `rpc.discover`
+
+Each plugin answers `rpc.discover` with an OpenRPC document. The SDK
+generates it from the code, with all doc comments. The schemas are JSON
+Schema Draft 7, as OpenRPC requires. The document has these extension
+fields:
+
+- `x-sausage-params` for each method: a `$ref` to the schema of the params
+  struct. So the name and the docs of the struct are not lost.
+- `x-sausage-endpoints`: the endpoint interfaces by name, each with its
+  methods.
+- `x-sausage-imports`: the methods that the plugin uses from each provider,
+  with their schemas.
+- `x-sausage-grace`: the grace period in seconds, if the plugin declares one.
+
+The schema of params describes what the provider can deserialize. The schema
+of a result describes what the provider serializes. (Schemars generates both
+kinds. They differ, for example for fields with `#[serde(default)]`.)
+
+```json
+{
+  "openrpc": "1.2.6",
+  "info": {"title": "www", "version": "0.1.0"},
+  "methods": [{
+    "name": "start",
+    "summary": "Start the web server and return the ID of its process.",
+    "paramStructure": "by-name",
+    "params": [{"name": "port", "required": true,
+                "description": "The TCP port to listen on, on all interfaces.",
+                "schema": {"type": "integer", "minimum": 0, "maximum": 65535}}],
+    "result": {"name": "pid", "schema": {"type": "string"}},
+    "x-sausage-params": {"$ref": "#/components/schemas/StartParams"}
+  }],
+  "components": {"schemas": {"StartParams": {"…": "…"}}},
+  "x-sausage-endpoints": {"control": {"methods": [{"name": "stats", "…": "…"}]}},
+  "x-sausage-imports": {"notes": {"methods": [{"name": "add", "…": "…"}]}}
+}
+```
+
+### 11.2 Compatibility
+
+A provider can add methods, optional params, and result fields. For each
+imported method:
+
+1. The provider has the method.
+2. Each params value that the consumer can send is valid for the provider.
+3. Each result that the provider can return is valid for the consumer.
+
+- The same rules apply to endpoint interfaces.
+- There are no version numbers. This check replaces them.
+- The check is our own. It covers a fixed subset of JSON Schema: objects with
+  `properties` and `required`, the primitive types, arrays, optional and
+  nullable values, string enums, and `$ref`. `#[schema]` gives a compile
+  error for a type outside this subset. So the check can decide every case.
+- The check covers calls, not state. Old and new processes share the files in
+  `/state`, and `core.revert` restores only code. A plugin must keep its
+  state format compatible, or migrate it in `rpc.retired`.
+
+### 11.3 Activation
+
+`core.activate {"plugin": "notes", "wasm": "/state/cargo/builds/7/notes.wasm"}`:
+
+1. The core copies the file. All further steps use this copy, even if the
+   file changes.
+2. It starts the copy and calls `rpc.discover`.
+3. It waits until it has the documents of all plugins (section 11.4). A
+   missing document never counts as "no consumers".
+4. It checks the imports of the new version against the current providers.
+5. It checks each current consumer of the plugin against the new version.
+6. If all checks pass, `plugin.wasm` becomes `plugin.prev.wasm`, and the copy
+   becomes `plugin.wasm`. Then the upgrade starts (section 4.7).
+
+If a check fails, nothing changes. The error lists each problem, with a
+counterexample where possible:
+
+```text
+notes was not activated: 1 consumer breaks.
+- agent imports notes.add(text: string) -> Added.
+  The new notes.add has no param "text". It requires "body": string.
+  Counterexample: {"text": "milk"} is not valid for the new params.
+Update agent first, or activate both together.
+```
+
+- The core runs one activation at a time.
+- `plugins: [...]` activates several plugins together. The checks then use
+  the new set. The core writes all files under temporary names first, and
+  then renames them.
+- `force: true` skips steps 4 and 5.
+- `core.revert {plugin}` activates `plugin.prev.wasm` in the same way, and
+  the current version becomes `plugin.prev.wasm`.
+- A person can also copy a file to `plugin.wasm` by hand. That skips the
+  checks (section 11.4).
+
+### 11.4 The graph
+
+- The core keeps the `rpc.discover` documents of all plugins in memory, by
+  file hash. At start, it gets them in the background.
+- A file watcher on `/plugins/*/plugin.wasm` updates them, for example after
+  a copy by hand. Such a copy skips the checks. `graph.json` then shows each
+  broken import, and the journal records it.
+- An import of a plugin that does not exist is "missing".
+- Untyped calls (`call("x.y", ...)`) are not in the graph.
+
+## 12. Building and tests
+
+`cargo.build {"plugin": "notes"}` is a native method of the host. A call
+still gets a process ID, a folder in `/proc`, and journal entries, like other
+calls. The method does these steps:
+
+1. It copies `/plugins/notes/source/` once. The tests and the build both use
+   this copy.
+2. It runs the tests under WASI.
+3. It builds the release `.wasm` for `wasm32-wasip2`.
+4. It returns `{"wasm": "/state/cargo/builds/<n>/notes.wasm", "tests":
+   {"passed", "failed", "output"}, "warnings"}`. If a step fails, it returns
+   an error with the compiler or test output.
+
+- The dependency `sausage-plugin = "0.1"` points to the SDK copy at
+  `/plugins/cargo/sdk/`.
+- Build scripts can compile C: `CC_wasm32_wasip2` and `AR_wasm32_wasip2`
+  point to a WASI clang.
+- The warnings include unused imported methods. Remove them from
+  `imports/<plugin>.json`, so that fewer changes of the provider break the
+  plugin.
+- A kill of the call stops the whole process group of cargo, with rustc, the
+  build scripts, and the tests.
+
+Tests:
+
+- `sausage` is the test runner (`CARGO_TARGET_WASM32_WASIP2_RUNNER`). It runs
+  each test in its own instance, in parallel. A panic ends only its own test.
+  Without this, the first panic would end the whole test run, because WASI
+  has `panic=abort`.
+- The normal Rust test setup works: `#[test]`, `tests/*.rs`, name filters,
+  and `--ignored`. Async tests use `#[sausage_plugin::test]`, like
+  `#[tokio::test]`. `#[should_panic]` cannot work, because WASI cannot catch
+  a panic.
+- Each test gets its own mount table: an empty temporary world as `/`, the
+  package folder (so that fixture files work), the variables that cargo sets,
+  and its own `/proc`, `/self`, and `/run`.
+- The runner answers `core.lock`, `core.unlock`, `core.notify`, and
+  `core.log`. A call to a plugin fails with a clear error: a test has no
+  other plugins.
+
+## 13. The SDK
+
+Two crates: `sausage-plugin`, and `sausage-plugin-macros`, which
+`sausage-plugin` re-exports. A plugin depends only on `sausage-plugin`. The
+SDK also re-exports `serde` and `schemars` for the macros.
+
+| Item | Purpose |
+| --- | --- |
+| `#[rpc]` | Makes an `impl` an interface. On the main interface: `#[rpc(endpoints(name = Type), grace_seconds = N)]`. |
+| `#[on_retired]` | Marks the method that answers `rpc.retired`. |
+| `#[schema]` | For each type that a method takes or returns: adds the serde and schemars derives, and checks the subset of section 11.2. |
+| `run(T)` | In `main`: serves the main interface on stdin and stdout. |
+| `call(method, params)` | An untyped call. Returns a JSON value. |
+| `.detach()`, `.on_notify(f)` | Options of a call. |
+| `Ctx` | An optional second argument of a method: `ctx.notify(name, params)`, `ctx.exit_after_response()`. |
+| `lock(path)` | A lock guard. `.try_now()` does not wait. `.keep()` holds the lock until the process ends. |
+| `listen(path, value)`, `connect(path)` | Endpoints. |
+| `background(future)` | Runs a task in this process. The process lives while a task runs. |
+| `import!("name")` | Generates `mod name` from `imports/name.json`. |
+| `state_dir()`, `write_atomic(path, bytes)`, `pid()` | Helpers. |
+| `#[sausage_plugin::test]` | An async test. A plain `#[test]` also works. |
+
+Rules that the compiler enforces:
+
+- A method takes `&self`, an optional `ctx: &Ctx`, and at most one params
+  argument.
+- The params argument is a `#[schema]` struct with named fields. Its fields
+  are the params of the method.
+- Each method, each `#[schema]` type, and each field has a doc comment.
+  Other agents read these docs to use the interface. Write them like good
+  Rust documentation.
+
+Other rules:
+
+- Method docs become `summary` (the first paragraph) and `description` in
+  OpenRPC. Type and field docs become `description` in the JSON Schema. The
+  generated imports contain them again as doc comments.
+- Each `import!` registers its document in a static list with the
+  `inventory` crate. `run` reads the list for `rpc.discover`. `import!` uses
+  `include_str!`, so cargo rebuilds the plugin when the file changes.
+- The value that `run` receives must be cheap to create, because the core
+  also starts a plugin only for `rpc.discover`. Open files and databases in
+  the methods.
+- Log with `eprintln!`. stdout belongs to the protocol.
+
+### 13.1 A plugin
+
+```toml
+[package]
+name = "notes"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+sausage-plugin = "0.1"
+serde_json = "1"
+```
+
+```rust
+//! Notes: a list of short texts, stored in `/state/notes/notes.json`.
+//!
+//! Each call runs in its own process, so two calls can run at the same time.
+//! `add` takes a lock on the file, so that no note gets lost.
+
+use std::path::PathBuf;
+
+use sausage_plugin::{Result, lock, rpc, schema, state_dir, write_atomic};
+
+/// The notes plugin. It keeps no state in memory: each call reads the file.
+struct Notes;
+
+/// The params of `add`.
+#[schema]
+struct AddParams {
+    /// The text of the new note. It can contain newlines.
+    text: String,
+}
+
+/// The result of `add`.
+#[schema]
+struct Added {
+    /// The number of notes after the call, with the new note.
+    count: usize,
+}
+
+#[rpc]
+impl Notes {
+    /// Add a note at the end of the list.
+    ///
+    /// Returns the number of notes after the call.
+    async fn add(&self, AddParams { text }: AddParams) -> Result<Added> {
+        let _lock = lock(file()).await?; // released on drop, or when the process ends
+        let mut notes = load()?;
+        notes.push(text);
+        write_atomic(file(), serde_json::to_vec(&notes)?)?;
+        Ok(Added { count: notes.len() })
+    }
+
+    /// List all notes, the oldest first.
+    fn list(&self) -> Result<Vec<String>> {
+        load() // no lock: write_atomic replaces the file in one step
+    }
+}
+
+/// The file with the notes: a JSON list of strings.
+fn file() -> PathBuf {
+    state_dir().join("notes.json")
+}
+
+/// Read all notes. A missing file means no notes.
+fn load() -> Result<Vec<String>> {
+    match std::fs::read(file()) {
+        Ok(bytes) => Ok(serde_json::from_slice(&bytes)?),
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(vec![]),
+        Err(e) => Err(e.into()),
+    }
+}
+
+fn main() {
+    sausage_plugin::run(Notes);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[sausage_plugin::test]
+    async fn add_appends_and_counts() {
+        assert_eq!(Notes.add(AddParams { text: "milk".into() }).await.unwrap().count, 1);
+        assert_eq!(Notes.add(AddParams { text: "eggs".into() }).await.unwrap().count, 2);
+        assert_eq!(Notes.list().unwrap(), ["milk", "eggs"]);
+    }
+
+    #[test]
+    fn list_is_empty_without_a_file() {
+        assert!(Notes.list().unwrap().is_empty());
+    }
+}
+```
+
+### 13.2 A server with an endpoint
+
+```rust
+//! A web server for the files in `/state/www/`.
+//!
+//! `start` starts the server in its own process and returns at once. Run it
+//! as a service, or call it detached, or the server ends with its caller.
+//! The running server serves the endpoint `control` at
+//! `/proc/<pid>/control`.
+
+use std::{cell::Cell, rc::Rc};
+
+use sausage_plugin::{Ctx, Result, background, listen, pid, rpc, schema};
+use wstd::net::TcpListener;
+
+/// The www plugin.
+struct Www;
+
+/// The params of `start`.
+#[schema]
+struct StartParams {
+    /// The TCP port to listen on, on all interfaces.
+    port: u16,
+}
+
+#[rpc(endpoints(control = Control), grace_seconds = 5)]
+impl Www {
+    /// Start the web server and return the ID of its process.
+    ///
+    /// The server runs until it gets `stop` on its endpoint, until
+    /// `core.stop`, or until its caller ends. Fails if the port is in use.
+    async fn start(&self, StartParams { port }: StartParams) -> Result<String> {
+        let tcp = TcpListener::bind(&format!("0.0.0.0:{port}")).await?;
+        let control = Rc::new(Control { hits: Cell::new(0) });
+        listen("/self/control", control.clone()).await?;
+        background(serve(tcp, control)); // the process lives while this task runs
+        Ok(pid())
+    }
+}
+
+/// The control endpoint of a running server.
+struct Control {
+    /// The number of HTTP requests that the server answered.
+    hits: Cell<u64>,
+}
+
+#[rpc]
+impl Control {
+    /// The number of HTTP requests that the server answered since its start.
+    fn stats(&self) -> Result<u64> {
+        Ok(self.hits.get())
+    }
+
+    /// Stop the server. The process ends after this response.
+    fn stop(&self, ctx: &Ctx) -> Result<()> {
+        ctx.exit_after_response();
+        Ok(())
+    }
+}
+
+/// Accept HTTP connections, and answer each request from `/state/www/`.
+async fn serve(tcp: TcpListener, control: Rc<Control>) {
+    // …
+}
+
+fn main() {
+    sausage_plugin::run(Www);
+}
+```
+
+The same type can serve stdin and an endpoint. The example uses two types
+for a reason: `www.stats` through the core would start a fresh process, and
+that process would answer 0.
+
+### 13.3 A service with a fixed endpoint
+
+```rust
+//! Secrets: keeps secrets in memory, for other plugins.
+//!
+//! Run it as a service: `{"method": "secrets.serve", "params": {}}` in
+//! `/config/boot.json`. Clients connect to the endpoint `vault` at
+//! `/run/secrets`.
+
+use std::rc::Rc;
+
+use sausage_plugin::{Result, listen, rpc};
+
+/// The secrets plugin.
+struct Secrets;
+
+#[rpc(endpoints(vault = Vault))]
+impl Secrets {
+    /// Open the vault and serve it at `/run/secrets`.
+    ///
+    /// Returns when the endpoint is ready. The process then lives while the
+    /// endpoint listens.
+    async fn serve(&self) -> Result<()> {
+        listen("/run/secrets", Rc::new(Vault::open()?)).await
+    }
+}
+```
+
+A client imports `secrets` and calls
+`secrets::vault::connect("/run/secrets").await?`.
+
+### 13.4 Imports
+
+To use another plugin, an agent does these steps:
+
+1. Copy `/proc/core/plugins/notes/discover.json` to
+   `source/imports/notes.json`.
+2. Read `/proc/core/plugins/notes/client.rs`: the exact code that the import
+   generates.
+3. Write `import!("notes")` and the code that uses it.
+4. Call `cargo.build`, and remove the imported methods that the warnings call
+   unused.
+5. Call `core.activate`.
+
+```rust
+sausage_plugin::import!("notes"); // imports/notes.json
+sausage_plugin::import!("www"); // imports/www.json, with its endpoint "control"
+
+/// Add a note, then start a web server and return its number of answered requests.
+async fn example() -> Result<u64> {
+    let added = notes::add(notes::AddParams { text: "milk".into() }).await?;
+    eprintln!("{} notes", added.count); // stderr goes to the journal
+    let pid = www::start(www::StartParams { port: 8080 }).detach().await?;
+    let control = www::control::connect(&format!("/proc/{pid}/control")).await?;
+    control.stats().await
+}
+```
+
+- The params of each method are one struct. The fields have the same names as
+  the JSON params.
+- Types take their names from the schemas. When the provider uses
+  `#[schema]`, those are the names of its Rust types: `AddParams` stays
+  `AddParams`.
+- The generated items are private to the crate, so rustc warns about each
+  unused method.
+
+## 14. The agent
+
+- `agent.chat {"text": "..."}` answers a message from a person. The result is
+  the final text. The interim texts come as `core.notify` with the name
+  `text`.
+- The agent takes a lock on `/state/agent/history.jsonl`. So a second message
+  waits until the first turn has ended.
+- The agent declares a long grace period (for example 10 minutes), so that a
+  turn can finish after an upgrade. A new version applies at the next
+  `chat`.
+- The tools: `call` (method, params, detach), `read_file`, `write_file`,
+  `list_dir`, and `copy_dir`.
+- The configuration is in `/config/agent.json`.
+- The prompt stays short. It says:
+  - where the contract is (`/proc/core/PROTOCOL.md`),
+  - where the SDK is (`/plugins/cargo/sdk/`),
+  - how to build and activate a plugin,
+  - where the agent's own source is (`/plugins/agent/source/`),
+  - that logs go to stderr,
+  - that the interface check does not cover state.
+
+## 15. The console
+
+- `rustyline` gives line editing and history. Notifications appear while you
+  type.
+- A short prompt. Results are indented. Agent notifications are dimmed.
+
+| Input | Effect |
+| --- | --- |
+| text | `agent.chat` |
+| `<plugin>.<method> {json}` | a call. The console prints the result. |
+| `ls [path]`, `cat <path>` | the filesystem as a process sees it, with `/proc` and `/run` |
+| `methods <plugin>` | the methods from `rpc.discover`, with params and docs |
+| `ps` | the running processes |
+| `log [plugin or pid] [-n N]` | the journal |
+| `activate <plugin> <wasm>`, `revert <plugin>` | `core.activate`, `core.revert` |
+| `stop <pid>`, `kill <pid>` | `core.stop`, `core.kill` |
+| `help`, `quit` | |
+
+`--headless` stays: no console input, and the host runs until SIGTERM or
+`core.exit`.
+
+## 16. Caches
+
+- Wasmtime's own compile cache stores the compiled code of each `.wasm` file.
+  It supports components.
+- The folder is `$XDG_CACHE_HOME/sausage/`, or `~/.cache/sausage/` without
+  that variable. `--cache-dir` changes the folder.
+
+## 17. Decisions
+
+- **JSON-RPC, not component interfaces.** Every language can read and write
+  lines of JSON, and models know JSON-RPC from LSP and MCP.
+- **A process per call.** We get parallelism without threads in WASI. A new
+  version applies at the next call, and old processes retire after a grace
+  period.
+- **Attached by default.** A process does not outlive its caller by
+  accident.
+- **Services in one file.** Only the core starts and restarts them, so
+  upgrades and singletons need no logic in plugins.
+- **Files to inspect, calls to act.** This keeps the core API small, and the
+  agent's file tools are enough to explore the world.
+- **Generated imports and interface checks, without version numbers.** A model
+  that translates a description by hand makes errors. A generator does not.
+  The check catches the most common error in a world that changes itself: a
+  change to one plugin breaks another one.
+- **A small schema subset.** With Draft 7 and a fixed subset, our own check
+  can decide every case.
+- **Docs are part of the interface.** Other agents work from them, so the
+  compiler requires them.
+- **No permissions.** The checks protect against mistakes, not against
+  plugins. Locks are advisory.
+- **Our own VFS, in its own crate.** It works on Linux and macOS, it makes
+  `/proc` live, and plugin-served files need it later. Mounts now, overlays
+  later.
+- **TCP endpoints for now.** They need no host code. VFS pipes can replace
+  them later behind the same SDK API.
+- **Simple scheduling for now.** An epoch tick every 10 milliseconds keeps
+  the core responsive and makes kills reliable.
+
+## 18. Later
+
+- Plugin-served files at `/proc/<pid>/fs/`, for example for an FTP plugin. A
+  request gets a timeout of 10 seconds, because a process that reads its own
+  served files would wait for itself forever.
+- Overlays in the VFS.
+- VFS pipes for endpoints, instead of TCP ports.
+- Subscriptions to file changes.
+- Structured logging.
+- A secrets service.
+- Cancellation of calls.
+- A better scheduler.
+
+## 19. Plan
+
+The work happens on the branch `plugins`. Each step includes its tests.
+
+Already confirmed:
+
+- `inventory` works on `wasm32-wasip2`.
+- Wasmtime's compile cache supports components.
+- C code builds for `wasm32-wasip2`.
+
+Checks of risks first:
+
+1. An end-to-end pair: a provider and a consumer with a generated import,
+   through the real transport. This includes `typify` with Draft 7 from
+   schemars, and our compatibility check on real documents.
+2. Fixture paths in tests under the runner.
+
+Then the steps:
+
+1. `PROTOCOL.md` and `DECISIONS.md` from this proposal.
+2. `sausage-vfs`: the trait, the layers, the Wasmtime adapter, and its tests.
+3. The core: a process per call, JSON-RPC routing, the process tree, upgrades,
+   services, locks, the journal, scheduling, and the compile cache.
+4. The SDK and its macros.
+5. `cargo.build`, the test runner, activation, and the graph.
+6. The agent and the console.
@@ -59,15 +59,27 @@ it exits. After 5 seconds, it kills the instance.

 ## Filesystem

-Each instance sees three folders:
+The world folder is the foundation of every instance's filesystem:

 | Path | Access | Contents |
 | --- | --- | --- |
-| `/data` | read-write by its actor; readable by every actor | the actor's state |
-| `/public` | read-write | the files that the actor publishes |
-| `/actor` | read-only | the `actor/` folder of the world |
+| `/` | read-write by every actor | the whole world folder |
+| `/self` | read-write | alias for the actor's own folder (`public/`, `data/`, `source/`, etc.) |
+| `/data` | read-write | alias for the actor's state folder |
+| `/public` | read-write | alias for the actor's published files |
+| `/actor` | read-write by every actor | the `actor/` folder of the world |

-An actor can write only its own `/data`, but can read every actor's `/data` through `/actor/<id>/data/`. `/data` is not private: any unprotected secret file there is readable by every actor.
+Every actor can read and write every file in the world, including other actors'
+`/actor/<id>/data/` and `/actor/<id>/public/`. Nothing there is private.
+Creating a folder in the world makes it visible to running actors immediately:
+`/config`, `/docs`, `/www`, and `/skills` need no new mounts or host restart.
+New worlds include an empty `/config` for global configuration by convention;
+existing worlds can simply create it. Keep secrets out of global configuration.
+
+Candidate instances see the same writable world root. Their `/self` alias
+points to the scratch actor folder; `/public` and `/data` still point to its
+corresponding children, and network access remains off;
+absolute world paths are not isolated from the live world.

 `/actor/<id>/` holds everything about an actor: `actor.wasm`, `actor.json`
 (installed version, running, subscriptions, tapped, watches), `source/`, `public/`, `data/`,
@@ -125,16 +137,21 @@ the request: the request's `type` in past tense (`spawned`, `upgraded`,
 | `type` | Fields | Effect |
 | --- | --- | --- |
 | `spawn` | `actor`, `wasm`, `source`?, `built_by`? | test, then start a new actor |
-| `upgrade` | `actor`, `wasm`, `source`?, `built_by`? | test, then swap the version |
-| `rollback` | `actor`, `version` | go back to an older version |
+| `upgrade` | `actor`, `wasm`, `source`?, `built_by`? | test, then swap the version: a running actor is stopped (normal shutdown) and starts the new version; a stopped actor gets the new version and stays stopped, with its mailbox untouched, until `start`. The answer has `running` |
+| `rollback` | `actor`, `version` | go back to an older version; like `upgrade`, a stopped actor stays stopped. The answer has `running` |
 | `stop`, `start` | `actor` | stop or start an actor |
 | `remove` | `actor` | stop the actor (normal shutdown), then delete its whole folder `/actor/<id>/` (all versions, `data/`, `public/`, logs); answer `{"type": "removed", "actor"}`. Messages to it are then undeliverable, and the ID can be spawned again. An unknown actor or a native one (`broker`, `console`, `cargo`, `fs`) is an `error` |
 | `subscribe`, `unsubscribe` | `actor` | receive (or not) what `actor` publishes |
 | `tap`, `untap` | | receive (or not) a copy of every message the broker routes |
-| `watch`, `unwatch` | `path` | receive (or not) `fs_changed` for every change of `path` or anything under it; answer `{"type": "watching" \| "unwatched", "path"}` with the path as an `/actor/...` path |
-| `exit` | | answer `exiting`, stop every actor, and end the `sausage` process (a wrapper like `nix run .#loop` starts it again, updated) |
+| `watch`, `unwatch` | `path` | receive (or not) `fs_changed` for every change of `path` or anything under it; answer `{"type": "watching" \| "unwatched", "path"}` with the path as an absolute world path |
+| `exit` | | answer `exiting`, stop every actor, and end the `sausage` process with exit code 75 (a wrapper like `nix run .#loop` starts it again, updated) |

-Paths are `/actor/...`, or the sender's `/public/...` or `/data/...`.
+**Headless.** `sausage run --headless [dir]` (or `sausage --headless`, or `SAUSAGE_HEADLESS=1`) turns the console input off: the host does not read stdin, so end of input (`/dev/null`) does not stop the world. `nix run .#loop -- --headless <world>` passes it through the loop. It runs until SIGTERM or SIGINT (stops every actor, exit code 0) or a broker `exit` request (exit code 75, as above). Without the flag, EOF on stdin or `/quit` ends the host.
+
+Paths are absolute world paths, or the sender's `/self/...`, `/public/...` or
+`/data/...` aliases. Native senders (such as the console) can also supply
+absolute host paths; apart from `/actor` and these aliases,
+these retain their host meaning.

 **Taps.** After `tap`, the sender gets a copy of every message that the
 broker routes (direct messages, replies, and publishes, between any actors,
@@ -174,7 +191,7 @@ change of `path` or a path under it (`/actor/a` covers `/actor/a/x`, not
 - Events come from `fs`. Like tap copies, they are not routed, a full
  mailbox drops them, and they never block the writer. Never answer them.
 - If the OS drops events, every watcher gets one
-  `{"type": "fs_changed", "path": "/actor", "op": "rescan"}`: anything may
+  `{"type": "fs_changed", "path": "/", "op": "rescan"}`: anything may
  have changed.
 - A watch is saved in `actor.json` (`"watches": [...]`) and survives
  restarts and upgrades. `unwatch` with the same path ends it.
@@ -210,7 +227,8 @@ instance. A version without test files passes.

 **Swap.** The broker holds the mailbox, stops the old instance, makes the
 top-level `actor.wasm` and `source/` a copy of the new version, and starts
-it. A rollback does the same with the older version.
+it. A stopped actor is not started: it keeps its mailbox and runs the new
+version at the next `start`. A rollback does the same with the older version.

 **Crashes.** The broker restarts a crashed actor after 0.5 s, then doubles
 the delay up to 30 s. A new version that crashes 3 times within 30 seconds
@@ -247,6 +265,11 @@ The reply is `{"type": "built", "wasm": "/actor/cargo/public/builds/<n>/<name>.w
 or `{"type": "build_failed", "errors": "...", "tests": {...}}`. Pass
 `wasm`, `source`, and `built_by` on to `spawn` or `upgrade`.

+Build scripts can compile C for `wasm32-wasip2`: the host sets
+`CC_wasm32_wasip2` and `AR_wasm32_wasip2` to a WASI clang with wasi-libc, so
+the `cc` crate (for example `rusqlite` with `bundled`) works. Its headers are
+WASI 0.1: C code that needs sockets does not build.
+
 A Rust actor depends on the SDK with `sausage-actor = "0.1"`. `cargo` points
 that dependency at the SDK of the host, which it publishes at
 `/actor/cargo/public/sdk/`.
@@ -48,6 +48,18 @@ From a clone (`git clone https://gitea.surma.technology/surma/sausage`), the
 same commands are `nix run`, `nix run -- init`, `nix run -- run` and
 `nix run .#loop`.

+### Headless
+
+`--headless` (or `SAUSAGE_HEADLESS=1`) turns the console input off: the host
+never reads stdin, so end of input does not stop the world. It runs until
+SIGTERM/SIGINT (clean stop, exit code 0) or a broker `exit` request (exit
+code 75, so the loop starts the newest version). Create the world first
+(`init`), then pass the flag through the loop:
+
+```sh
+nix run git+https://gitea.surma.technology/surma/sausage#loop -- --headless my-world
+```
+
 In the console:

 ```text
@@ -255,7 +255,9 @@ impl Broker {
        }
        InstanceConfig {
            mounts: vec![
-                Mount { guest: "/actor".into(), host: self.world.actors_root(), writable: false },
+                Mount { guest: "/".into(), host: self.world.root.clone(), writable: true },
+                Mount { guest: "/actor".into(), host: self.world.actors_root(), writable: true },
+                Mount { guest: "/self".into(), host: own.clone(), writable: true },
                Mount { guest: "/public".into(), host: own.join("public"), writable: true },
                Mount { guest: "/data".into(), host: own.join("data"), writable: true },
            ],
@@ -331,12 +333,13 @@ impl Broker {
        Ok((component, tests))
    }

-    /// Make `version` the current `actor.wasm`, `source/`, and `actor.json`.
-    pub fn install(&self, id: &str, version: u64) -> Result<()> {
+    /// Make `version` the current `actor.wasm`, `source/`, and `actor.json`,
+    /// and record whether the actor runs.
+    pub fn install(&self, id: &str, version: u64, running: bool) -> Result<()> {
        self.world.install_files(id, version)?;
        self.update_meta(id, |m| {
            m.version = Some(version);
-            m.running = true;
+            m.running = running;
        })
    }

@@ -360,7 +363,7 @@ impl Broker {

    async fn create_version(self: &Arc<Self>, id: &str, meta: &VersionMeta, wasm: &Path, source: Option<&Path>) -> Result<Value> {
        let (_, tests) = self.try_version(id, meta, wasm, source).await?;
-        self.install(id, meta.version)?;
+        self.install(id, meta.version, true)?;
        self.start_supervisor(id, meta.version, true);
        Ok(json!({"type": "spawned", "actor": id, "version": meta.version, "tests": tests}))
    }
@@ -444,7 +447,7 @@ impl Broker {
        self.host_error("the file watcher dropped events; watchers get a rescan, actors a full pass");
        let watchers: Vec<String> =
            self.metas.lock().unwrap().iter().filter(|(_, m)| !m.watches.is_empty()).map(|(id, _)| id.clone()).collect();
-        self.inject(&watchers, vfs::ID, json!({"type": "fs_changed", "path": "/actor", "op": "rescan"}));
+        self.inject(&watchers, vfs::ID, json!({"type": "fs_changed", "path": "/", "op": "rescan"}));
        let report = self.scan().await;
        for change in &report {
            eprintln!("sausage: {change}");
@@ -598,9 +601,9 @@ impl Broker {
                let on = ty == "watch";
                let path_s = b["path"].as_str().ok_or_else(|| anyhow!("missing \"path\""))?;
                let global = self.world.global_path(&self.world.resolve(&env.from, path_s)?);
-                let path = global.ok_or_else(|| anyhow!("{path_s} is not under /actor"))?;
+                let path = global.ok_or_else(|| anyhow!("{path_s} is not under the world root"))?;
                let path = match path.trim_end_matches('/') {
-                    "" => "/actor".to_string(),
+                    "" => "/".to_string(),
                    p => p.to_string(),
                };
                self.update_meta(&env.from, |m| {
@@ -648,7 +651,7 @@ fn same_file(a: &Path, b: &Path) -> bool {

 /// Whether the namespace path `path` is `prefix` or inside it.
 fn under(path: &str, prefix: &str) -> bool {
-    path.strip_prefix(prefix).is_some_and(|rest| rest.is_empty() || rest.starts_with('/'))
+    prefix == "/" || path.strip_prefix(prefix).is_some_and(|rest| rest.is_empty() || rest.starts_with('/'))
 }

 pub fn truncate(s: &str, max: usize) -> String {
@@ -8,6 +8,9 @@
 //! The broker knows nothing about Rust. This actor is one way to get a
 //! `.wasm` file. Other actors can add other languages.
 //!
+//! Build scripts compile C for WASI with the clang in `CC_wasm32_wasip2`
+//! and `AR_wasm32_wasip2`. The Nix package and the dev shell set both.
+//!
 //! Actors depend on the SDK with `sausage-actor = "0.1"`. The SDK is not
 //! published: this actor copies the SDK of this host to `public/sdk/` (so
 //! that every actor can read it), and points the dependency there in the
@@ -3,7 +3,8 @@
 //! - `@<actor> <json>` sends a JSON body. `@<actor> <text>` sends
 //!   `{"type": "text", "text": ...}`.
 //! - A line without `@` goes to `agent` as text.
-//! - `/help`, `/quit`. EOF on stdin also quits.
+//! - `/help`, `/quit`. EOF on stdin also quits (not with `--headless`, which
+//!   never reads stdin).

 use std::sync::Arc;

@@ -5,6 +5,7 @@ use anyhow::{Context, Result, bail};
 use clap::{Parser, Subcommand};
 use include_dir::{Dir, include_dir};
 use serde_json::json;
+use tokio::signal::unix::Signal;

 use sausage::world::{ActorMeta, World};
 use sausage::{Host, cargo_actor, console};
@@ -17,6 +18,11 @@ static AGENT_SOURCE: Dir<'_> = include_dir!("$CARGO_MANIFEST_DIR/../agent");
 #[derive(Parser)]
 #[command(version, about)]
 struct Cli {
+    /// Do not read stdin, so end of input does not stop the world. It runs
+    /// until SIGTERM (or SIGINT), or until an actor sends
+    /// `@broker {"type":"exit"}`. Also set by SAUSAGE_HEADLESS=1.
+    #[arg(long, global = true)]
+    headless: bool,
    #[command(subcommand)]
    command: Option<Cmd>,
 }
@@ -91,13 +97,41 @@ async fn init(dir: PathBuf) -> Result<()> {
    Ok(())
 }

-async fn run(dir: PathBuf) -> Result<()> {
+/// Install the SIGTERM and SIGINT handlers now (not when first polled).
+fn termination_signals() -> Result<(Signal, Signal)> {
+    use tokio::signal::unix::{SignalKind, signal};
+    let term = signal(SignalKind::terminate()).context("install SIGTERM handler")?;
+    let int = signal(SignalKind::interrupt()).context("install SIGINT handler")?;
+    Ok((term, int))
+}
+
+/// Resolves on SIGTERM or SIGINT.
+async fn termination((mut term, mut int): (Signal, Signal)) {
+    tokio::select! {
+        _ = term.recv() => {}
+        _ = int.recv() => {}
+    }
+}
+
+async fn run(dir: PathBuf, headless: bool) -> Result<()> {
+    // Register the signal handlers before the host starts, so a signal that
+    // arrives early is never the default (kill) action.
+    let signals = if headless { Some(termination_signals()?) } else { None };
    let host = Host::start(&dir).await?;
    tokio::spawn(console::run_mailbox(host.mailbox(console::ID)));
    let broker = host.broker.clone();
-    let exit = tokio::select! {
+    let exit = match signals {
+        Some(signals) => {
+            println!("Sausage headless: running until SIGTERM or an exit request.");
+            tokio::select! {
+                _ = termination(signals) => false,
+                _ = broker.exit_requested() => true,
+            }
+        }
+        None => tokio::select! {
            _ = console::run_input(host.broker.clone()) => false,
            _ = broker.exit_requested() => true,
+        },
    };
    println!("Stopping actors …");
    host.stop().await;
@@ -113,16 +147,18 @@ async fn run(dir: PathBuf) -> Result<()> {

 #[tokio::main]
 async fn main() -> Result<()> {
-    match Cli::parse().command {
+    let cli = Cli::parse();
+    let headless = cli.headless || std::env::var("SAUSAGE_HEADLESS").is_ok_and(|v| !v.is_empty() && v != "0");
+    match cli.command {
        Some(Cmd::Init { dir }) => init(dir).await,
-        Some(Cmd::Run { dir }) => run(dir).await,
+        Some(Cmd::Run { dir }) => run(dir, headless).await,
        None => {
            let dir = PathBuf::from("world");
            if !dir.join("actor").is_dir() {
                println!("No world in ./world yet, creating it (same as `sausage init`).");
                init(dir.clone()).await?;
            }
-            run(dir).await
+            run(dir, headless).await
        }
    }
 }
@@ -220,17 +220,16 @@ impl Supervisor {

    /// Make `version` current. It is compiled first (unless `component` is
    /// given): if that fails, nothing changes. `data/` and `public/` stay as
-    /// they are.
+    /// they are. A stopped actor stays stopped.
    async fn install(&mut self, version: u64, component: Option<Component>) -> Result<()> {
        let component = match component {
            Some(c) => c,
            None => self.broker.load_version(&self.id, version)?,
        };
        self.stop().await;
-        self.broker.install(&self.id, version)?;
+        self.broker.install(&self.id, version, self.running)?;
        self.version = version;
        self.component = Some(component);
-        self.running = true;
        self.restarts = 0;
        self.restart_at = None;
        Ok(())
@@ -239,20 +238,26 @@ impl Supervisor {
    async fn upgrade(&mut self, version: u64, component: Component, requester: String) -> Result<Value> {
        let previous = self.version;
        self.install(version, Some(component)).await?;
+        if !self.running {
+            // Installed, not started: main runs and mail is read at the next `start`.
+            return Ok(json!({"type": "upgraded", "actor": self.id, "version": version, "previous": previous, "running": false}));
+        }
        self.probation = Some(Probation { previous, since: Instant::now(), crashes: 0, requester });
        if let Err(e) = self.start().await {
            self.rollback(previous).await?;
            bail!("version {version} did not start ({e:#}); rolled back to {previous}");
        }
-        Ok(json!({"type": "upgraded", "actor": self.id, "version": version, "previous": previous}))
+        Ok(json!({"type": "upgraded", "actor": self.id, "version": version, "previous": previous, "running": true}))
    }

    async fn rollback(&mut self, version: u64) -> Result<Value> {
        let from = self.version;
        self.install(version, None).await?;
        self.probation = None;
+        if self.running {
            self.start().await?;
-        Ok(json!({"type": "rolled_back", "actor": self.id, "from": from, "to": version}))
+        }
+        Ok(json!({"type": "rolled_back", "actor": self.id, "from": from, "to": version, "running": self.running}))
    }

    /// Handle a control request. Returns `true` when the supervisor ends.
@@ -390,8 +390,8 @@ impl preopens::Host for VfsView<'_> {
    fn get_directories(&mut self) -> wasmtime::Result<Vec<(Resource<types::Descriptor>, String)>> {
        let dirs = preopens::Host::get_directories(&mut self.inner)?;
        for (fd, name) in &dirs {
-            if name == "/actor" {
-                self.state.dirs.insert(fd.rep(), "/actor".to_string());
+            if name == "/actor" || name == "/" {
+                self.state.dirs.insert(fd.rep(), name.clone());
            }
        }
        Ok(dirs)
@@ -5,7 +5,7 @@
 //! Events are coalesced per path: once a path is quiet for `QUIET` (or has
 //! kept changing for `MAX_DELAY`), it becomes one change
 //! `{path, op: write | create | remove | rename, to?}` with a namespace path
-//! (`/actor/...`). Then the broker
+//! (relative to the world root, such as `/actor/...` or `/config/...`). Then the broker
 //!
 //! - sends `fs_changed` to the actors that watch the path (`watch` request),
 //! - starts or upgrades an actor whose `actor/<id>/actor.wasm` (or folder
@@ -75,7 +75,7 @@ impl Pending {
 }

 async fn run(broker: Arc<Broker>, mut events: mpsc::UnboundedReceiver<notify::Result<notify::Event>>) {
-    let root = broker.world.actors_root();
+    let root = broker.world.root.clone();
    let mut pending: HashMap<String, Pending> = HashMap::new();
    // Actor checks and full passes. Dropping the set (when the host stops) aborts them.
    let mut tasks = tokio::task::JoinSet::new();
@@ -122,11 +122,11 @@ async fn sleep_until(t: Option<Instant>) {
    }
 }

-/// The namespace path (`/actor/...`) of a host path, unless it is outside
-/// `actor/` or a temporary file of the host.
+/// The world namespace path of a host path, unless it is outside the
+/// world or a temporary file of the host.
 fn namespace(root: &Path, path: &Path) -> Option<String> {
    let rel = path.strip_prefix(root).ok()?;
-    let mut out = String::from("/actor");
+    let mut out = String::new();
    for part in rel.components() {
        let name = part.as_os_str().to_str()?;
        if name.starts_with(TMP_PREFIX) {
@@ -135,7 +135,7 @@ fn namespace(root: &Path, path: &Path) -> Option<String> {
        out.push('/');
        out.push_str(name);
    }
-    Some(out)
+    Some(if out.is_empty() { "/".to_string() } else { out })
 }

 /// One change: namespace path, op, and the new path of a rename.
@@ -219,7 +219,7 @@ mod tests {

    #[test]
    fn a_rename_is_one_change_and_temp_files_are_skipped() {
-        let root = Path::new("/w/actor");
+        let root = Path::new("/w");
        let now = Instant::now();
        let mut pending = HashMap::new();
        let ev = |kind, paths: &[&str]| {
@@ -236,7 +236,8 @@ mod tests {
            ev(name(RenameMode::Both), &["/w/actor/a/public/x", "/w/actor/a/public/y"]),
            ev(EventKind::Create(notify::event::CreateKind::File), &["/w/actor/a/.sausage-tmp-host-1-actor.json"]),
            ev(name(RenameMode::Both), &["/w/actor/a/.sausage-tmp-host-1-actor.json", "/w/actor/a/actor.json"]),
-            ev(EventKind::Create(notify::event::CreateKind::File), &["/w/.lock"]),
+            ev(EventKind::Create(notify::event::CreateKind::File), &["/outside/.lock"]),
+            ev(EventKind::Create(notify::event::CreateKind::File), &["/w/config/x"]),
        ] {
            for (path, op, to) in changes(root, &e) {
                add(&mut pending, path, op, to, now);
@@ -250,6 +251,7 @@ mod tests {
            vec![
                ("/actor/a/actor.json".to_string(), "write", None),
                ("/actor/a/public/x".to_string(), "rename", Some("/actor/a/public/y".to_string())),
+                ("/config/x".to_string(), "create", None),
            ]
        );
    }
@@ -1,15 +1,17 @@
 //! On-disk layout of a Sausage world. The folder is the source of truth:
 //! `sausage run` boots every actor that it finds in `actor/`, and then
-//! watches the folder (`watch.rs`).
+//! watches the folder (`watch.rs`). `/self` aliases the running actor's folder;
+//! `/public` and `/data` remain aliases for its `public/` and `data/`.
 //!
 //! ```text
-//! <world>/
+//! <world>/              mounted at /, readable and writable by every actor
+//!   config/             global configuration by convention (no secrets)
 //!   actor/<id>/
 //!     actor.wasm        the current version
 //!     actor.json        version, running, subscriptions, tapped, watches (broker)
 //!     source/           source of the current version
-//!     public/           written by the actor, read-only for others
-//!     data/             state, writable only by the actor
+//!     public/           published files, readable and writable by everyone
+//!     data/             state, readable and writable by everyone
 //!     stderr.log        stderr of the actor and notes of the broker
 //!     versions/<n>/     every version that was installed: actor.wasm, source/, meta.json
 //! ```
@@ -131,6 +133,7 @@ impl World {
        for id in NATIVE {
            world.ensure_actor_dirs(id)?;
        }
+        std::fs::create_dir_all(world.root.join("config"))?;
        Ok(world)
    }

@@ -191,8 +194,9 @@ impl World {

    /// Map a path in an actor's namespace to a host path.
    ///
-    /// - `/actor/<id>/...` is the global filesystem.
-    /// - `/public/...` and `/data/...` belong to `sender`.
+    /// - Absolute paths are relative to the world root.
+    /// - `/self/...` aliases `sender`'s folder; `/public/...` and `/data/...`
+    ///   alias its corresponding children.
    /// - Native senders (the console) can also give absolute host paths.
    pub fn resolve(&self, sender: &str, path: &str) -> Result<PathBuf> {
        let under = |base: PathBuf, rest: &str| -> Result<PathBuf> {
@@ -212,6 +216,9 @@ impl World {
        if let Some(rest) = prefixed("/actor") {
            return under(self.actors_root(), rest);
        }
+        if let Some(rest) = prefixed("/self") {
+            return under(self.actor_dir(sender), rest);
+        }
        if let Some(rest) = prefixed("/public") {
            return under(self.public_dir(sender), rest);
        }
@@ -221,13 +228,16 @@ impl World {
        if NATIVE.contains(&sender) && Path::new(path).is_absolute() {
            return Ok(PathBuf::from(path));
        }
-        bail!("cannot resolve path {path} for {sender}: use /actor/<id>/..., /public/... or /data/...")
+        if Path::new(path).is_absolute() {
+            return under(self.root.clone(), path);
+        }
+        bail!("cannot resolve path {path} for {sender}: use an absolute world path")
    }

    /// The path of a host file in the global filesystem, if it has one.
    pub fn global_path(&self, host: &Path) -> Option<String> {
-        let rel = host.strip_prefix(self.actors_root()).ok()?;
-        Some(format!("/actor/{}", rel.display()))
+        let rel = host.strip_prefix(&self.root).ok()?;
+        Some(format!("/{}", rel.display()))
    }
 }

@@ -39,3 +39,47 @@ fn bare_command_without_a_world_starts_init() {
    // It asks before it creates anything.
    assert!(!dir.join("world").exists());
 }
+
+/// Start a headless host on a fresh world with stdin at EOF; returns once it
+/// printed its ready line (printed after the signal handlers are installed).
+fn start_headless(label: &str) -> (std::process::Child, std::io::Lines<std::io::BufReader<std::process::ChildStdout>>) {
+    use std::io::{BufRead, BufReader};
+    let dir = empty_dir(label);
+    let world = dir.join("world");
+    sausage::World::create(&world).unwrap();
+    let mut child = Command::new(env!("CARGO_BIN_EXE_sausage"))
+        .args(["run", "--headless"])
+        .arg(&world)
+        .stdin(Stdio::null())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::null())
+        .spawn()
+        .unwrap();
+    let mut lines = BufReader::new(child.stdout.take().unwrap()).lines();
+    let line = lines.next().expect("host exited before it started").unwrap();
+    assert!(line.contains("headless"), "unexpected first line: {line}");
+    (child, lines)
+}
+
+/// With stdin at EOF (as soon as the host starts), a headless host stays up.
+#[test]
+fn headless_ignores_stdin_eof() {
+    let (mut child, _lines) = start_headless("headless-eof");
+    std::thread::sleep(std::time::Duration::from_millis(500));
+    let alive = child.try_wait().unwrap().is_none();
+    let _ = child.kill();
+    let _ = child.wait();
+    assert!(alive, "headless host exited on stdin EOF");
+}
+
+/// SIGTERM right after the ready line stops the actors and exits with 0.
+#[test]
+fn headless_stops_cleanly_on_sigterm_right_after_ready() {
+    let (mut child, lines) = start_headless("headless-term");
+    let pid = child.id().to_string();
+    assert!(Command::new("kill").args(["-TERM", &pid]).status().unwrap().success());
+    let rest: Vec<String> = lines.map(|l| l.unwrap()).collect();
+    let status = child.wait().unwrap();
+    assert!(status.success(), "exit status {status:?}, output {rest:?}");
+    assert!(rest.iter().any(|l| l.contains("Stopping actors")), "output {rest:?}");
+}
@@ -0,0 +1,12 @@
+[package]
+name = "cargo-c"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+sausage-actor = "0.1"
+
+[build-dependencies]
+cc = "1"
+
+[workspace]
@@ -0,0 +1,5 @@
+// Compile C with the `cc` crate: natively for the unit test, and with the
+// WASI clang (`CC_wasm32_wasip2`) for the actor.
+fn main() {
+    cc::Build::new().file("src/add.c").compile("add");
+}
@@ -0,0 +1 @@
+int c_add(int a, int b) { return a + b; }
@@ -0,0 +1,25 @@
+//! Adds two numbers with a C function: `{"type": "add", "a", "b"}` -> `{"type": "sum", "value"}`.
+use sausage_actor::{json, messages, reply};
+
+unsafe extern "C" {
+    fn c_add(a: i32, b: i32) -> i32;
+}
+
+fn add(a: i32, b: i32) -> i32 {
+    unsafe { c_add(a, b) }
+}
+
+fn main() {
+    for message in messages() {
+        let (a, b) = (message.body["a"].as_i64().unwrap_or(0), message.body["b"].as_i64().unwrap_or(0));
+        let _ = reply(&message, json!({"type": "sum", "value": add(a as i32, b as i32)}));
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn c_code_runs_on_the_host_target() {
+        assert_eq!(super::add(2, 3), 5);
+    }
+}
@@ -140,20 +140,20 @@ async fn exit_request_is_answered_and_signals_the_host() {
 }

 #[tokio::test]
-async fn filesystem_permissions_and_public_sharing() {
+async fn filesystem_is_writable_and_public_aliases_share_files() {
    let (_, host, mut mailbox) = filesystem_world("filesystem-permissions").await;
    for path in [
-        "/actor/reader/public/denied.txt",
-        "/actor/writer/public/denied.txt",
+        "/actor/reader/public/shared.txt",
+        "/actor/writer/public/shared.txt",
    ] {
-        let denied = ask(
+        let written = ask(
            &host,
            &mut mailbox,
            "writer",
-            json!({"type": "write", "path": path, "text": "denied"}),
+            json!({"type": "write", "path": path, "text": "shared"}),
        )
        .await;
-        assert_eq!(denied.body["type"], "error", "write to {path} succeeded");
+        assert_eq!(written.body["type"], "ok", "write to {path} failed");
    }

    let written = ask(
@@ -176,7 +176,7 @@ async fn filesystem_permissions_and_public_sharing() {
 }

 #[tokio::test]
-async fn actors_can_read_but_not_write_other_actor_data() {
+async fn actors_can_read_and_write_other_actor_data() {
    let (_, host, mut mailbox) = filesystem_world("actor-data-sharing").await;
    ask_type(
        &host,
@@ -201,10 +201,10 @@ async fn actors_can_read_but_not_write_other_actor_data() {
        &mut mailbox,
        "reader",
        json!({"type": "write", "path": "/actor/writer/data/x", "text": "changed"}),
-        "error",
+        "ok",
    )
    .await;
-    let unchanged = ask_type(
+    let changed = ask_type(
        &host,
        &mut mailbox,
        "writer",
@@ -212,7 +212,49 @@ async fn actors_can_read_but_not_write_other_actor_data() {
        "content",
    )
    .await;
-    assert_eq!(unchanged.body["text"], "shared");
+    assert_eq!(changed.body["text"], "changed");
+    host.stop().await;
+}
+
+#[tokio::test]
+async fn world_root_is_shared_writable_and_survives_restart() {
+    let (world, host, mut mailbox) = filesystem_world("world-root").await;
+    assert!(world.root.join("config").is_dir());
+    ask_type(&host, &mut mailbox, "writer", json!({"type": "write", "path": "/self/data/x", "text": "self-alias"}), "ok").await;
+    assert_eq!(ask_type(&host, &mut mailbox, "writer", json!({"type": "read", "path": "/data/x"}), "content").await.body["text"], "self-alias");
+    let file = "/config/x";
+    ask_type(&host, &mut mailbox, "writer", json!({"type": "write", "path": file, "text": "first"}), "ok").await;
+    let read = json!({"type": "read", "path": file});
+    assert_eq!(ask_type(&host, &mut mailbox, "reader", read.clone(), "content").await.body["text"], "first");
+    ask_type(&host, &mut mailbox, "reader", json!({"type": "write", "path": file, "text": "second"}), "ok").await;
+    assert_eq!(std::fs::read_to_string(world.root.join("config/x")).unwrap(), "second");
+    for actor in ["writer", "reader"] {
+        assert_eq!(world.resolve(actor, file).unwrap(), world.root.join("config/x"));
+    }
+    assert_eq!(world.global_path(&world.root.join("config/x")).as_deref(), Some(file));
+
+    // Watches use the same world namespace, not only /actor paths.
+    let watching = request(&host, &mut mailbox, json!({"type": "watch", "path": world.root.join("config").display().to_string()})).await;
+    assert_eq!(watching.body, json!({"type": "watching", "path": "/config"}));
+    drain(&mut mailbox, Duration::from_millis(300)).await;
+    std::fs::write(world.root.join("config/event"), "watched").unwrap();
+    assert_eq!(fs_events(drain(&mut mailbox, Duration::from_millis(600)).await),
+        vec![json!({"type": "fs_changed", "path": "/config/event", "op": "create"})]);
+    request(&host, &mut mailbox, json!({"type": "unwatch", "path": world.root.join("config").display().to_string()})).await;
+
+    // A new top-level folder appears in already running instances, without a mount change.
+    std::fs::create_dir(world.root.join("docs")).unwrap();
+    std::fs::write(world.root.join("docs/new"), "host-created").unwrap();
+    let docs = json!({"type": "read", "path": "/docs/new"});
+    assert_eq!(ask_type(&host, &mut mailbox, "reader", docs, "content").await.body["text"], "host-created");
+    ask_type(&host, &mut mailbox, "reader", json!({"type": "write", "path": "/docs/new", "text": "actor-updated"}), "ok").await;
+    assert_eq!(std::fs::read_to_string(world.root.join("docs/new")).unwrap(), "actor-updated");
+    host.stop().await;
+
+    let (host, mut mailbox) = start(&world).await;
+    for actor in ["writer", "reader"] {
+        assert_eq!(ask_type(&host, &mut mailbox, actor, read.clone(), "content").await.body["text"], "second");
+    }
    host.stop().await;
 }

@@ -506,6 +548,50 @@ async fn rolls_back_a_crash_loop_to_the_previous_version_without_restoring_data(
    host.stop().await;
 }

+#[tokio::test]
+async fn upgrade_and_rollback_keep_a_stopped_actor_stopped() {
+    let world = create_world("upgrade-stopped");
+    let wasm = toolbox_wasm().clone();
+    let (host, mut mailbox) = start(&world).await;
+    let source = passing_source(&world, "source");
+    spawn_type(&host, &mut mailbox, "sleeper", &wasm, &source).await;
+    let stopped = request(&host, &mut mailbox, json!({"type": "stop", "actor": "sleeper"})).await;
+    assert_eq!(stopped.body["type"], "stopped");
+
+    let upgraded = upgrade_actor(&host, &mut mailbox, "sleeper", &wasm, &source).await;
+    assert_eq!(upgraded.body["type"], "upgraded", "{upgraded:?}");
+    assert_eq!(upgraded.body["version"], 2);
+    assert_eq!(upgraded.body["running"], false);
+    let meta = world.read_meta("sleeper");
+    assert_eq!((meta.version, meta.running), (Some(2), false));
+
+    // Mail waits in the mailbox: the stopped actor reads nothing.
+    let waiting = host.broker.send("console", Some("sleeper"), None, None, json!({"type": "version"}));
+    assert!(
+        tokio::time::timeout(Duration::from_millis(500), receive_reply(&mut mailbox, &waiting, Duration::from_secs(10)))
+            .await
+            .is_err(),
+        "a stopped actor must not answer"
+    );
+
+    let rolled_back = request(&host, &mut mailbox, json!({"type": "rollback", "actor": "sleeper", "version": 1})).await;
+    assert_eq!(rolled_back.body["type"], "rolled_back", "{rolled_back:?}");
+    assert_eq!(rolled_back.body["running"], false);
+    assert!(!world.read_meta("sleeper").running);
+
+    // `start` runs the installed version and delivers the waiting message.
+    let started = request(&host, &mut mailbox, json!({"type": "start", "actor": "sleeper"})).await;
+    assert_eq!(started.body["type"], "started");
+    let answer = receive_reply(&mut mailbox, &waiting, Duration::from_secs(10)).await;
+    assert_eq!(answer.body["version"], "1");
+
+    // A running actor still restarts on the new version.
+    let running = upgrade_actor(&host, &mut mailbox, "sleeper", &wasm, &source).await;
+    assert_eq!(running.body["running"], true);
+    assert_eq!(ask(&host, &mut mailbox, "sleeper", json!({"type": "version"})).await.body["version"], "3");
+    host.stop().await;
+}
+
 #[tokio::test]
 async fn explicit_rollback_keeps_current_data() {
    let world = create_world("explicit-rollback");
@@ -683,6 +769,22 @@ async fn cargo_actor_runs_unit_tests_by_default_and_can_skip_them() {
    host.stop().await;
 }

+#[tokio::test]
+async fn cargo_actor_compiles_c_code_for_wasi() {
+    let world = create_world("cargo-c");
+    let (host, mut mailbox) = start(&world).await;
+    let source = cargo_source("cargo-c");
+    let id = host.broker.send("console", Some("cargo"), None, None, json!({"type": "build", "source": source.display().to_string()}));
+    let built = receive_reply(&mut mailbox, &id, Duration::from_secs(300)).await;
+    assert_eq!(built.body["type"], "built", "{built:?}");
+    assert_eq!(built.body["tests"]["passed"], 1, "{built:?}");
+    let wasm = host.world.resolve("console", built.body["wasm"].as_str().unwrap()).unwrap();
+    spawn_type(&host, &mut mailbox, "c-add", &wasm, &source).await;
+    let sum = ask_type(&host, &mut mailbox, "c-add", json!({"type": "add", "a": 2, "b": 3}), "sum").await;
+    assert_eq!(sum.body["value"], 5);
+    host.stop().await;
+}
+
 #[tokio::test]
 async fn rejects_invalid_actor_ids() {
    let world = create_world("invalid-id");
@@ -1143,7 +1245,7 @@ async fn a_watcher_overflow_sends_one_rescan_and_runs_a_full_pass() {
    let report = host.broker.clone().overflowed().await;
    assert!(report.iter().any(|r| r["type"] == "spawned" && r["actor"] == "planted"), "{report:?}");

-    let rescan = json!({"type": "fs_changed", "path": "/actor", "op": "rescan"});
+    let rescan = json!({"type": "fs_changed", "path": "/", "op": "rescan"});
    assert_eq!(fs_events(drain(&mut mailbox, Duration::from_millis(600)).await), vec![rescan]);
    assert!(bystander.try_recv().is_err(), "an actor without watches got the rescan");
    host.stop().await;
@@ -26,6 +26,14 @@
        # PATH. Keep this same runtime path in the packaged host and exercise
        # the installed binary below with PATH deliberately empty.
        runtimePath = pkgs.lib.makeBinPath [ rust pkgs.stdenv.cc ];
+        # A WASI clang with wasi-libc, so that build scripts (the `cc` crate)
+        # can compile C for wasm32-wasip2. Its headers are WASI 0.1: C code
+        # that needs sockets does not build.
+        wasiCc = pkgs.pkgsCross.wasi32.stdenv.cc;
+        wasiCcEnv = {
+          CC_wasm32_wasip2 = "${wasiCc}/bin/${wasiCc.targetPrefix}cc";
+          AR_wasm32_wasip2 = "${wasiCc}/bin/${wasiCc.targetPrefix}ar";
+        };
        craneLib = (crane.mkLib pkgs).overrideToolchain rust;
        common = {
          pname = "sausage";
@@ -48,9 +56,12 @@
          cargoExtraArgs = "--locked -p sausage";
          doCheck = false;
          nativeBuildInputs = [ pkgs.makeWrapper ];
-          # The `cargo` actor runs cargo at runtime. Build scripts need a C linker.
+          # The `cargo` actor runs cargo at runtime. Build scripts need a C linker,
+          # and C code for WASI needs the WASI clang.
          postInstall = ''
-            wrapProgram $out/bin/sausage --prefix PATH : ${runtimePath}
+            wrapProgram $out/bin/sausage --prefix PATH : ${runtimePath} \
+              --set-default CC_wasm32_wasip2 ${wasiCcEnv.CC_wasm32_wasip2} \
+              --set-default AR_wasm32_wasip2 ${wasiCcEnv.AR_wasm32_wasip2}
          '';
          meta.mainProgram = "sausage";
        });
@@ -84,7 +95,7 @@
        # The binary the host loop runs (`nix run`), built from the same
        # cached dependencies as the tests.
        checks.package = sausage;
-        checks.tests = craneLib.cargoTest (common // {
+        checks.tests = craneLib.cargoTest (common // wasiCcEnv // {
          inherit cargoArtifacts;
          cargoExtraArgs = "--locked ${testPackages}";
          # Nothing builds on the test run's target folder: don't store it.
@@ -114,7 +125,35 @@
          version = "0.1.0"
          edition = "2024"
          TOML
-          printf 'fn main() {}\n' > "$source/src/main.rs"
+          # C code for WASI, compiled with the packaged WASI clang. The native
+          # test build has no C, so it needs no C compiler for the host.
+          printf 'int probe_add(int a, int b) { return a + b; }\n' > "$source/src/add.c"
+          cat > "$source/build.rs" <<'RUST'
+          use std::process::Command;
+          fn main() {
+              if std::env::var("TARGET").unwrap() != "wasm32-wasip2" {
+                  return;
+              }
+              let out = std::env::var("OUT_DIR").unwrap();
+              let cc = std::env::var("CC_wasm32_wasip2").expect("CC_wasm32_wasip2");
+              let ar = std::env::var("AR_wasm32_wasip2").expect("AR_wasm32_wasip2");
+              let object = format!("{out}/add.o");
+              assert!(Command::new(cc).args(["-c", "src/add.c", "-o", &object]).status().unwrap().success());
+              assert!(Command::new(ar).args(["crs", &format!("{out}/libadd.a"), &object]).status().unwrap().success());
+              println!("cargo:rustc-link-search=native={out}");
+              println!("cargo:rustc-link-lib=static=add");
+          }
+          RUST
+          cat > "$source/src/main.rs" <<'RUST'
+          #[cfg(target_os = "wasi")]
+          unsafe extern "C" {
+              fn probe_add(a: i32, b: i32) -> i32;
+          }
+          fn main() {
+              #[cfg(target_os = "wasi")]
+              assert_eq!(unsafe { probe_add(2, 3) }, 5);
+          }
+          RUST
          cat > "$source/tests/probe.rs" <<'RUST'
          #[test]
          fn native_test_harness_runs() {
@@ -161,11 +200,11 @@
        apps.default = { type = "app"; program = "${sausage}/bin/sausage"; };
        apps.loop = { type = "app"; program = "${loop}/bin/sausage-loop"; };

-        devShells.default = pkgs.mkShell {
+        devShells.default = pkgs.mkShell (wasiCcEnv // {
          packages = [ rust pkgs.wasmtime pkgs.wasm-tools ];
          shellHook = ''
            export CARGO_HOME="$PWD/.cargo-home"
          '';
-        };
+        });
      });
 }
Author	SHA1	Message	Date
surma	a7eb96bbbb	PROPOSAL.md: results of the review, no mention of the old model ci / check (push) Successful in 2m33s Details Upgrades retire old processes after a grace period, then call rpc.retired. Services live in boot.json. One preopen / with a mount table in the sausage-vfs crate, with guards for in-flight file operations. Draft 7 and our own compatibility check on a fixed subset. Imports register with inventory. Rules for liveness, stop states, routing, locks, activation, endpoints (rpc.endpoint handshake), boot, builds, and a 10 ms scheduling tick.	2026-10-22 23:27:08 +01:00
surma	2415bb361f	PROPOSAL.md: plugins, processes, and JSON-RPC ci / check (push) Successful in 2m17s Details The design from the redesign discussion: a process per call, JSON-RPC on stdin and stdout, a virtual /proc, /self, and /run, TCP endpoints, locks, a central journal, generated imports with interface checks at activation, and the SDK with examples.	2026-10-22 20:58:30 +01:00
surma	a536d873e6	cargo: compile C for wasm32-wasip2 with a WASI clang ci / check (push) Successful in 18s Details The Nix package, the dev shell, and the test check set CC_wasm32_wasip2 and AR_wasm32_wasip2 to the clang of pkgsCross.wasi32 (wasi-libc), so build scripts with the cc crate work, for example rusqlite with bundled SQLite. The runtime-toolchain check links C into a probe with the packaged host and an empty PATH.	2026-10-22 20:16:38 +01:00
Sausage Agent	34e2f35272	Add writable /self alias alongside /public and /data ci / check (push) Successful in 15s Details	2026-10-22 13:35:13 +00:00
Sausage Agent	f932ab9719	Mount the writable world root for every actor ci / check (push) Successful in 3m9s Details	2026-10-22 13:29:38 +00:00
surma	3d3f6f35fb	Merge pull request 'broker: upgrade and rollback keep a stopped actor stopped' (#3 ) from upgrade-keeps-stopped into main ci / check (push) Successful in 13s Details Reviewed-on: #3	2026-10-22 10:50:15 +01:00
surma	f1af07506f	broker: upgrade and rollback keep a stopped actor stopped ci / check (push) Successful in 8m42s Details ci / check (pull_request) Successful in 4m38s Details A stopped actor gets the new version installed, keeps its mailbox and does not run main until the next start. Running actors still restart on the new version. The upgraded and rolled_back answers say whether the actor runs.	2026-10-22 10:11:36 +01:00
Sausage Agent	a72e42a8c9	headless: register signal handlers synchronously, split tests, drop deployment examples and wording ci / check (pull_request) Successful in 1m36s Details ci / check (push) Successful in 11s Details	2026-10-18 15:31:41 +00:00
Sausage Agent	01a821ab72	Add --headless mode (no stdin read, runs until SIGTERM/exit) + systemd/NixOS examples ci / check (push) Successful in 2m44s Details	2026-10-18 15:24:20 +00:00