Traverse

Define once. Run anywhere.

Traverse is a contract-driven WebAssembly runtime for portable business capabilities. What you get: discover a governed capability → execute known behavior → produce a verifiable trace. You define 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.

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

Why this matters

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.

Reuse instead of regenerate

The public registry is the catalog to search before you invent a rule — pricing, authorization, escalation, deadline pressure, scoring, classification, summarization, and more. Every record is contract-defined, semver'd, and signed before it merges. Live counts belong on the registry site; they are not the product pitch.

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.

Quick Start

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

Install

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

Install the CLI

The Traverse CLI is published as traverse-cli-rs (binary name traverse-cli). It needs rustc ≥ 1.94.

rustup toolchain install 1.94.0
cargo +1.94.0 install traverse-cli-rs --version =0.15.0 --locked

Name clash: crates.io traverse-cli is an unrelated Solidity tooling project. cargo install traverse-cli installs the wrong binary with the same name — always install traverse-cli-rs.

ONNX packaging (traverse-cli model package-onnx) also needs the audited runner guest from the onnx-runner-v* artifact release (not the product Traverse v* notes-only release). See docs/model-packaging-guide.md.

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

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

Swift, Maven, and NuGet packages are published as of v0.15.0 (see the platform table below). The GitHub Release is Traverse v0.15.0; binary artifacts (like the Swift xcframework) ship on their own swift-host-v* artifact releases, never marked Latest. See docs/releases/v0.15.0.md and the v0.15.0 upgrade guide (breaking Spec 138 model-rights changes).

Where it runs

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. No host is Certified under spec 529-production-platform-certification yet. Signed exact-ref model execution (ExactModelHost) ships in every embedder as of 0.15.0. On Apple hosts it can also run a package's signed Core ML variant (on-device iPhone evidence: #1630).

Edge placement is planned, not shipped. Cloud placement is an explicit non-goal for v0.1.

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.

Project state

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

Toward v1.0.0

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).

How it works

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.

For Agents

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.

Governance

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.

Contributing

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.

Built on UMA

Read the UMA book and the UMA code examples.

Authoring

• docs/capability-contract-authoring-guide.md — capability contracts
• docs/event-contract-authoring-guide.md — event contracts
• docs/wasm-agent-authoring-guide.md — WASM capability authoring
• docs/wasm-microservice-authoring-guide.md — WASM microservice authoring
• docs/workflow-composition-guide.md — composing workflows
• docs/workflow-authoring-guide.md — plan-then-seal default vs adaptive opt-in
• docs/capability-publish.md — publishing to the registry
• docs/expedition-example-authoring.md — worked example

Releases

• docs/releases/v0.15.0.md — current release notes
• docs/releases/v0.14.0.md — prior release notes
• docs/releases/v0.13.0.md — prior release notes
• docs/releases/v0.12.0.md — prior release notes
• docs/releases/v0.11.0.md — prior release notes
• docs/releases/v0.10.2.md — prior release notes
• docs/releases/v0.10.1.md — prior release notes
• docs/releases/v0.10.0.md — prior release notes
• docs/releases/v0.8.1.md — prior release notes

Consumer and packaging paths

• 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 methodology
• docs/decision-log.md — consolidated architecture decisions

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