Traverse

Define once. Run anywhere.

Traverse is a contract-driven WebAssembly runtime for portable business capabilities. You write a piece of business logic once — as a capability with a machine-readable contract — and the same signed WASM binary runs on Linux, macOS, and Windows, on iOS and Android, in the browser, and inside an AI agent — producing a verifiable execution trace every time.

No reimplementation per environment. No agent free-handing your pricing rules. One behavior, governed, everywhere it needs to run.

Business logic no longer lives in one place. The same eligibility check, pricing rule, or approval policy now has to run in a web client, on a server, at the edge, and — increasingly — inside an AI agent that a user is talking to. Teams answer that by reimplementing the rule in each stack. The copies drift. The behavior stops being one thing.

AI coding agents make this sharper, not softer. An agent asked to "add the discount logic" will re-derive that logic from scratch, in prose, every session — unversioned, unreviewed, and authoritative only because it ran last.

Traverse takes the other position: the agent proposes, the runtime decides. A capability is a contract (JSON Schema in, JSON Schema out), an immutable version, a signature, and a WASM artifact. The runtime validates every input against the contract, isolates execution in a WASM sandbox, enforces policy, and emits a trace you can audit. An agent's job is to find and compose the right capabilities — not to be the source of truth for what the business does.

This is the working implementation of Universal Microservices Architecture: write once, run where it makes sense, keep the decisions queryable instead of buried in a framework.

The public registry currently holds 92 capabilities across 33 domains (213 signed versions; 175 non-deprecated) — pricing, authorization, escalation, deadline pressure, completion-quality scoring, classification, summarization, and more. Every record is contract-defined, semver'd, signed, and CI-validated before it merges.

Before an agent (or a developer) writes a rule, it can check whether that rule already exists:

traverse-cli registry sync   --workspace local-default --json   # pull the index locally
traverse-cli registry search price --workspace local-default --json
traverse-cli registry search price --workspace local-default --commercial-use allowed --json
traverse-cli registry list   --workspace local-default --json

Licensing filters (--commercial-use, --redistribution) project Registry spec 025-capability-licensing-metadata fields from the synced index. Declarative only — unknown / conditional / forbidden are never treated as permission.

Find core.calculate-price@1.1.0, compose it into a workflow, done. What you don't spend tokens or review cycles on:

• re-deriving the input/output contract
• re-implementing and re-testing the logic
• re-reviewing a fresh, unverified copy of a rule the org already agreed on

The same discovery surface is exposed over MCP, so an AI client can list and call governed capabilities directly. The claude-skills skill set makes "check the registry first" the default step, so agents stop duplicating what's already published.

Author a capability (plain English): use the official Claude skill traverse-capability-author in traverse-framework/claude-skills. It interviews you one question at a time, checks the public (and any private) registry, writes the contract, produces executable WASM, and opens a human-reviewed PR. You describe the business rule — you do not have to write the Rust yourself. Under the hood the implementation is still Rust→WASM (determinism, sandboxing, portability). That is the LLM-assisted authoring on-ramp.

Build / run from this repo (manual path): 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 the runtime validates and executes. From here:

• Run it end to end and see the trace → docs/getting-started.md
• Full browser + HTTP walkthrough → quickstart.md
• Author in plain English (skill) → claude-skills / traverse-capability-author
• Author manually in Rust → docs/capability-contract-authoring-guide.md

Public packages are on crates.io and npmjs, not GitHub Packages. Current release: v0.12.0.

# Rust
cargo add traverse-runtime@0.12.0
cargo add traverse-embedder@0.12.0
# also: traverse-contracts, traverse-mcp, traverse-cli-rs,
#       traverse-expedition-wasm

# Web / TypeScript
npm install traverse-embedder-web@0.12.0

Swift, Maven, and NuGet packages are not published yet.

One capability contract and one WASM artifact, executed the same way on every target through a platform embedder that speaks embedder-api/1.0.0. Each embedder digest-verifies the runtime, rejects ambient imports, and enforces the same Host ABI — the browser is one target among several, not the default.

All five embedders run against one CI-enforced conformance suite (spec 068-public-platform-embedder-packages), so a capability that passes on one platform behaves the same on the rest. Desktop targets (Linux x86_64/aarch64, macOS x86_64/arm64, Windows x86_64) are covered by the CI matrix on every PR.

Cloud and edge placement targets are specified and on the roadmap, not yet shipped.

Scaffold your own governed bundle with traverse-cli app new <id> — docs/expedition-example-authoring.md. Guides: docs/wasm-microservice-authoring-guide.md · docs/mcp-stdio-server.md · docs/mcp-real-agent-exercise.md · quickstart.md.

Traverse is pre-1.0 (v0.12.0) and spec-driven — every capability below is real, running, tested code.

v1.0.0 is gated, not dated — governed by spec 049-v1-milestone-gate, checkable with bash scripts/ci/v1_gate_check.sh. It signals stable public API surfaces, every published crate live on crates.io, and the runtime stress-tested on every supported platform. Full conditions: docs/v1-milestone.md.

Explicitly not required for v1.0.0: a reference app in this repo (that's reference-apps), an HTTP admin API, a cloud deployment surface, or worker-isolation message passing (v2).

traverse-registry (capability and event registries with deterministic traversal) lives in traverse-framework/registry so capabilities publish and version independently of the runtime. The runtime never talks to that repo live — traverse-cli registry sync pulls a signed index artifact into local workspace state, and execution reads local state only.

Boundaries and portability rules: docs/adapter-boundaries.md · docs/compatibility-policy.md · docs/decision-log.md.

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

Workflow: read your entry-point file → claim the ticket (check agent:claude / agent:codex labels and existing branches) → branch NNN-feature-name → write specs/<branch>/spec.md before code → implement the smallest change that satisfies the spec → open a PR with ## Governing Spec, ## Project Item, and ## Validation sections. Full rules: docs/multi-thread-workflow.md.

Code must align with an approved, immutable spec or it does not merge.

Start with 001-foundation-v0-1 (core runtime, CLI, MCP surface), 004-spec-alignment-gate (the CI gate), and 049-v1-milestone-gate (what v1.0.0 requires).

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

Start with CONTRIBUTING.md — especially First contributions — then CODE_OF_CONDUCT.md and SECURITY.md. Pick a good first issue or help wanted ticket; docs/examples marked no-spec-needed do not need a new specs/ slice. Runtime and contract changes still need an approved governing spec.

Common starting points: docs/getting-started.md · docs/troubleshooting.md · docs/what-can-i-build.md · docs/quality-standards.md.

Read the UMA book and the UMA code examples.

Apache-2.0 — see LICENSE and NOTICE.

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