Architecture
How Traverse is structured internally. Crates, execution model, registry design, and the WASM sandbox.
Overview
Traverse is a Rust workspace. There is no single monolith. Each concern lives in its own crate with a clear boundary. The runtime does not know about the CLI. The contracts crate does not know about the registry. You can depend on any crate independently.
All crates enforce #![forbid(unsafe_code)]. CI requires 100% test coverage and checks spec alignment on every push. A software bill of materials (SBOM) is generated via CycloneDX on each release.
Crate map
Six crates. Each one owns a distinct surface area.
| Crate | Responsibility | Target |
|---|---|---|
| traverse-runtime | Core engine. Drives the state machine, coordinates registry lookups, dispatches WASM execution, emits events, and records traces. | native |
| traverse-contracts | Contract parsing and validation. Loads JSON contract files, validates schema, resolves inputs and outputs, checks preconditions. | native |
| traverse-registry | Capability and event registries. Loads bundles from disk, indexes contracts, resolves capabilities by ID, and manages event subscriptions. | native |
| traverse-cli | CLI surface. Provides bundle inspect and browser-adapter serve. Thin layer over the runtime and registry crates. |
native |
| traverse-mcp | MCP stdio server. Exposes governed capabilities as MCP tools. Accepts tools/list and tools/call over stdin/stdout. |
native |
| traverse-expedition-wasm | Example WASM capability. The expedition planner shipped as a wasm32-wasi binary. Shows how to package executable WASM under a Traverse contract. |
wasm32-wasi |
Execution flow
Every request follows the same path through the runtime. Nothing is skipped. Each step produces a record in the trace artifact.
State machine
The runtime progresses through defined states. Each transition is explicit. There is no implicit fallback.
Registry design
The registry is bundle-based. A bundle is a directory containing a manifest file and one or more WASM binaries with their contracts. The runtime loads the whole bundle at startup.
Indexing is contract-first. The registry reads each contract file, validates it, and builds an in-memory index keyed by capability ID. WASM binaries are not loaded until a capability is actually requested.
Traversal is deterministic. If multiple capabilities match a goal, the registry returns them in the order they appear in the manifest. There is no probabilistic ranking. The contract's preferred_targets list controls which placement is chosen.
WASM sandbox
Each capability declares its resource requirements in the contract. The runtime enforces them. A capability that does not declare network access cannot make outbound requests.
| Constraint field | What it controls | Default |
|---|---|---|
network_access |
Whether the WASM module can make outbound network calls through the host API. | false |
filesystem_access |
Whether the WASM module can read or write the host filesystem. | false |
host_api_access |
Whether the WASM module can invoke host-provided functions beyond the WASI standard set. | false |
Constraints are evaluated during the evaluating_constraints state, before any WASM code loads. If a constraint check fails, the runtime transitions to error immediately. The failing constraint is recorded in the trace.
Trace system
Every execution produces a trace artifact. Traces are structured records, not log strings. They are designed to be queryable.
A trace contains:
- Trace ID and request timestamp
- The goal string as received
- Discovery decisions: which capabilities were found and why
- Constraint evaluation: each constraint checked and its result
- Selected capability ID and version
- Inputs: validated payload passed to the WASM entrypoint
- Execution path: state transitions with timestamps
- Emitted events: list of event IDs published and their payloads
- Duration: total wall time in milliseconds
- Status: completed or error with reason
Traces are available immediately after execution. The browser adapter returns the trace inline with the response. The MCP server includes it in the tool call result.
Spec governance
Traverse has 9 approved governing specs. Every crate and every feature is traceable to a spec. No code ships without an approved spec backing it.
CI runs a spec-alignment gate on every push. If code references behavior not covered by an approved spec, the gate fails. This keeps the codebase and its documentation in sync.