Traverse

Run one governed business capability across browser, edge, and cloud without rewriting it.

Traverse is a contract-driven runtime for discovering, validating, and composing portable business capabilities through events, policies, constraints, and graph-based workflows.

Why Should I Care?

Most systems are portable at the container boundary, but not at the business behavior boundary. The moment you need the same governed behavior to run in multiple hosts (browser, edge, cloud, device), you typically end up with duplicated implementations and behavior drift.

Traverse is built to make the capability contract the source of truth, and make execution traceable and governed regardless of where it runs.

Killer use case (first target): a portable knowledge workflow that runs offline in the browser and can also run in cloud/edge contexts, without splitting the business behavior into separate implementations. See: docs/killer-use-case-portable-knowledge-app.md.

What’s Proven Today

• A spec-governed runtime with deterministic CI gates and versioned governing specs
• “App-consumable” release surfaces with downstream validation (see: docs/app-consumable-entry-path.md and docs/youaskm3-integration-validation.md)

Who It’s For (and Not For)

Traverse is for teams that must run the same governed behavior across multiple host environments and want contract-first portability, traceability, and governance.

Traverse is not a replacement for Docker-orchestrated services when “portable enough” means “runs in a container in one environment”, and you do not need host-level portability or capability-level governance.

This is personal research and development by Enrico Piovesan, built to prove in code the ideas behind Universal Microservices Architecture (UMA).

Built on UMA

Traverse is the runtime that Universal Microservices Architecture describes.

UMA answers the question: how do you keep one business behavior portable and governed as execution moves across browser, edge, cloud, workflows, and AI? Traverse is the answer in working Rust code — contracts, registries, a governed runtime, and structured traces.

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

If you want to run them: you're in the right place.

For Humans

Quick Start

git clone https://github.com/enricopiovesan/Traverse.git
cd Traverse

cargo build                   # build all crates
cargo test                    # run the full test suite
cargo run -p traverse-cli     # run the CLI

Requirements: Rust 1.94+

New to Traverse? Start with docs/tutorial-index.md. That page describes three paths and tells you which one fits your goal.

Documentation Map

Use this as the human and agent navigation hub for the supported docs:

What it does

• Define a capability contract — one meaningful business action with explicit inputs, outputs, and side effects
• Register it in the capability registry
• Validate it against its governing spec
• Execute it locally through the runtime with structured trace output

Vision

Traverse treats business capabilities as the primary unit of software:

• portable across browser, edge, cloud, and device
• governed through versioned, immutable contracts and specs
• composable through events and graph-based workflows
• explainable through structured runtime traces
• safe for humans, runtimes, and AI systems to consume

Contributing

Please read before opening a PR:

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

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

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

Approved specs

Architecture

Crates

Governance

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

Key docs

Onboarding and tutorial path

• docs/tutorial-index.md — ordered onboarding path for developers and agents
• docs/getting-started.md — first capability path for new developers
• quickstart.md — first runnable app-consumable flow
• docs/app-consumable-entry-path.md — browser-hosted consumer path

Build and authoring guides

• docs/expedition-example-authoring.md — canonical example authoring flow
• docs/workflow-composition-guide.md — beginner guide to chaining two capabilities into a workflow
• docs/tutorial-index.md — ordered onboarding path for new developers and agents
• quickstart.md — start here for the first runnable flow
• docs/app-consumable-entry-path.md — first app-consumable flow
• docs/app-consumable-consumer-bundle.md — versioned consumer bundle
• docs/app-consumable-package-release-pointer.md — package release pointer
• docs/adapter-boundaries.md — adapter and portability boundaries
• docs/youaskm3-canonical-mcp-client-path.md — canonical v0.3.0 MCP client path for youaskm3
• docs/mcp-stdio-server.md — supported MCP server bootstrap path and command surface
• docs/wasm-agent-authoring-guide.md — how to create new WASM agents
• docs/wasm-agent-team-readiness-example.md — second governed WASM AI agent example
• docs/wasm-microservice-authoring-guide.md — how to create new WASM microservices
• docs/mcp-real-agent-exercise.md — real AI agent exercise for the Traverse MCP surface

Consumer and release surfaces

• docs/app-consumable-consumer-bundle.md — versioned consumer bundle
• docs/app-consumable-package-release-pointer.md — package release pointer
• docs/event-publishing-tutorial.md — how to emit and receive governed events from a capability
• docs/youaskm3-canonical-mcp-client-path.md — release-facing MCP client path for youaskm3
• docs/packaged-traverse-runtime-artifact.md — packaged runtime artifact
• docs/packaged-traverse-mcp-server-artifact.md — packaged MCP server artifact
• docs/youaskm3-integration-validation.md — youaskm3 integration validation
• docs/youaskm3-published-artifact-validation.md — published-artifact validation for youaskm3
• docs/youaskm3-compatibility-conformance-suite.md — youaskm3 compatibility conformance suite
• docs/youaskm3-real-shell-validation.md — youaskm3 real shell validation

Reference and governance

• docs/adapter-boundaries.md — adapter and portability boundaries
• docs/quality-standards.md — non-negotiable quality rules
• docs/compatibility-policy.md — versioning and compatibility
• docs/troubleshooting.md — shortest path through common local and CI failures
• docs/what-can-i-build.md — concrete app and integration patterns supported today
• docs/why-not-docker.md — when to use Traverse vs Docker (decision matrix)
• docs/benchmarks.md — measured latency numbers and Docker comparison
• docs/decision-log.md — consolidated roadmap and architecture decisions
• docs/spec-numbering.md — how spec ids, paths, and versions relate
• docs/multi-thread-workflow.md — parallel agent workflow
• docs/project-management.md — issue and board rules
• docs/spec-reviewer-guide.md — reviewer template for governing specs
• docs/adr/README.md — architecture decision records

Task board

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

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