Traverse

Your business logic runs in the browser, on your server, and in a cloud function. They drift. You maintain three versions of the same behavior. Traverse keeps it in one contract and runs it anywhere — with a full execution trace every time.

Traverse is the working implementation of Universal Microservices Architecture.

Quick Start

Requirements: Rust 1.94+

git clone https://github.com/traverse-framework/traverse.git
cd traverse
cargo build
cargo run -p traverse-cli-rs -- bundle inspect examples/expedition/registry-bundle/manifest.json

Expected output:

bundle_id: expedition.planning.seed-bundle
version: 1.0.0
capabilities: 6
events: 5
workflows: 1

You just inspected a live capability bundle — 6 capabilities, 5 events, 1 workflow, all defined in contracts that the runtime validates and executes.

Ready to run the full browser demo? → quickstart.md

What Can I Build?

A browser app with governed runtime behavior

Build the UI. Traverse owns execution, workflow state, and trace output. The same capability contract runs locally in development and on the edge in production — no rewrite.

→ quickstart.md · docs/app-consumable-entry-path.md

A governed MCP server

Expose capability discovery and execution over stdio. Downstream AI clients and tools discover and call governed capabilities without touching your internals.

→ docs/mcp-stdio-server.md

Portable WASM capabilities

Package executable behavior as WASM. Traverse validates, places, and runs it — browser, edge, or cloud — under the same contract.

→ docs/wasm-agent-authoring-guide.md

Workflow-backed business logic

Model multi-step business behavior as a workflow. The runtime traverses it deterministically and produces a structured trace you can inspect and audit.

→ docs/workflow-composition-guide.md · docs/getting-started.md

Your own app bundle

cargo run -p traverse-cli-rs -- app new my-app

Scaffolds a governed app bundle. Add your capability contracts, workflows, and WASM components.

→ docs/expedition-example-authoring.md

Documentation

Onboarding and tutorial path

Consumer and release surfaces

• docs/releases/v0.8.1.md — current release notes
• docs/app-consumable-consumer-bundle.md — versioned consumer bundle
• docs/app-consumable-package-release-pointer.md — package release pointer
• docs/packaged-traverse-runtime-artifact.md — packaged runtime artifact
• docs/packaged-traverse-mcp-server-artifact.md — packaged MCP server artifact
• docs/youaskm3-canonical-app-http-path.md — canonical HTTP app path
• docs/youaskm3-canonical-mcp-client-path.md — canonical MCP client path
• docs/youaskm3-integration-validation.md — youaskm3 integration validation
• docs/youaskm3-published-artifact-validation.md — published-artifact validation
• docs/youaskm3-compatibility-conformance-suite.md — compatibility conformance suite
• docs/youaskm3-real-shell-validation.md — real shell validation
• docs/mcp-real-agent-exercise.md — real AI agent exercise for the MCP surface

v0.3.0 consumer paths

• docs/v0.3.0-public-surface-compatibility.md — v0.3.0 public surface compatibility
• docs/v0.3.0-source-build-consumer-packaging.md — source-build packaging for v0.3.0 consumers
• docs/v0.3.0-downstream-validation-path.md — downstream validation path for v0.3.0
• docs/youaskm3-v0.3.0-integration-readiness.md — v0.3.0 integration readiness index

Reference

• docs/adapter-boundaries.md — adapter and portability boundaries
• docs/compatibility-policy.md — versioning and compatibility
• docs/troubleshooting.md — shortest path through common failures
• docs/what-can-i-build.md — concrete app and integration patterns
• docs/benchmarks.md — measured latency numbers
• docs/decision-log.md — consolidated architecture decisions

Architecture

Crates

Contributing

Please read before opening a PR:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• docs/quality-standards.md

All work follows the governance workflow below. Every PR must be backed by an approved spec.

GitHub Project 1 is the canonical board. All active work has an issue, a project item, and a PR.

Built on UMA

Traverse is the runtime that Universal Microservices Architecture describes — the answer in working Rust code to the question: how do you keep one business behavior portable and governed as execution moves across browser, edge, cloud, workflows, and AI?

If you want to understand the ideas: read the UMA book and explore the UMA code examples.

Governance

Traverse is spec-driven. Code must align with an approved, immutable spec or it does not merge.

Approved Specs

For Agents

This project supports AI-assisted development with Codex and Claude Code running in parallel.

Entry points

Agent workflow

1. Read your entry point file (CLAUDE.md or AGENTS.md)
2. Claim the ticket — check for agent:claude / agent:codex labels and existing branches
3. Create a feature branch: NNN-feature-name
4. Run .specify/scripts/bash/setup-plan.sh --json to initialize the spec directory
5. Write specs/<branch>/spec.md and plan.md before any code
6. Implement the smallest change that satisfies the spec and contracts
7. Open a PR with ## Governing Spec, ## Project Item, and ## Validation sections

Agent coordination

• agent:claude label = claimed by Claude Code — Codex must skip
• agent:codex label = claimed by Codex — Claude Code must skip
• Full coordination rules: docs/multi-thread-workflow.md

License

Apache-2.0 — see LICENSE and NOTICE.

Related Work

• UMA-code-examples
• Universal Microservices Architecture — Book
• Contract-Driven AI Development (C-DAD) — White Paper
• Speaking
• github.com/enricopiovesan