Design documents
These documents explain the implementation and its contracts for contributors and reviewers. They describe current behavior; earlier proposals and review rounds are in the Git history. To use marsh, read the manual.
Read in order:
- Local product contract: the user-visible contract
- Architecture: crates, data flow, trust boundaries
- TLA+ model: cross-component state, invariants, and where each action lives in the code
- Acceptance contract: black-box observations a release must pass
By topic:
| Document | Subject |
|---|---|
| processes.md | Nested jobs: lineage, admission, the job capability socket (acceptance) |
| workspaces.md | Daemon-owned splits and forks (acceptance) |
| stock-sbx-adapter.md | The only boundary to sbx: ownership map, mounts, workers |
| shell-attachments.md | Attaching a shell, interruption, cleanup evidence |
| command-registry.md | Command-to-Kit mappings and their rules |
| results.md | Job records behind marsh results, and scope configuration |
| bash-compatibility.md | Known Bash differences and the differential tests |
| mcp.md | The host MCP server and published-command export (test contract) |
| ACP acceptance | ACP sessions and their publication |
| kit-publication.md | Building and publishing Kits |
| supply-chain.md | Build inputs, published images, notices |
| self-development.md | marsh --dev and the dev broker |
| Brush patch record | The upstream Brush revision and marsh's patch queue |
Plans: bring your own agent Kit.