traverse

KO | EN

gitlite — search

#javascript #hacktoberfest #ai #llm #golang #go #linux #nodejs #java #awesome #awesome-list #vue #security #open-source

(★ 122)

Contract-driven runtime for portable business capabilities — spec-governed, WASM-first, composable across browser, edge, cloud, and AI.

traverse Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Traverse](https://github.com/user-attachments/assets/479aa1e5-5799-4c7d-bb8a-4b30d711c7db)](https://traverse-framework.com/)

# Traverse

[![CI](https://github.com/traverse-framework/traverse/actions/workflows/ci.yml/badge.svg)](https://github.com/traverse-framework/traverse/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/traverse-framework/traverse/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://raw.githubusercontent.com/traverse-framework/traverse/main/LICENSE)
[![Rust](https://img.shields.io/badge/rust-1.94%2B-orange)](https://www.rust-lang.org/)
[![Version](https://img.shields.io/badge/version-v0.9.1-blue)](https://github.com/traverse-framework/traverse/releases)
[![Registry](https://img.shields.io/badge/registry-live%20catalog-6f42c1)](https://registry.traverse-framework.com/)

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](https://www.universalmicroservices.com/).

---

## Current State & Roadmap

Traverse is pre-1.0 (`v0.9.1`) and evolving under spec-driven governance — every capability below is real, running code, not a plan.

- **8 crates in this repo** plus the capability registry (now its own repo, see below) — 7 of these 9 are [published on crates.io](https://crates.io/search?q=traverse-): runtime, contracts, registry, CLI, MCP server, embedder SDK, and the expedition WASM example. `traverse-native-bridge` and `traverse-swift-host` are newer, not yet published.
- **105 approved, immutable specs** govern the runtime, contracts, registry, MCP surface, WASM execution, native embedding, event delivery, and durable local storage. Full list: `jq -r '.specs[].id' specs/governance/approved-specs.json` (or see [Governance](#governance) below).
- **100% coverage enforced on core logic**, spec-alignment and supply-chain gates on every PR, 5-platform CI matrix (Linux x86_64/aarch64, macOS x86_64/arm64, Windows x86_64).
- **Capability registry** was extracted into its own repo, [`traverse-framework/registry`](https://github.com/traverse-framework/registry), so capabilities can be published, versioned, and consumed independently of the runtime. Browse what's actually published at the live catalog: **[registry.traverse-framework.com](https://registry.traverse-framework.com/)**.
- **Reference apps** for multiple platforms (web, iOS, macOS, Android, Windows, Linux, CLI) live in [`traverse-framework/reference-apps`](https://github.com/traverse-framework/reference-apps).

### Where this is going: v1.0.0

v1.0.0 is gated, not a date — governed by [`spec 049-v1-milestone-gate`](specs/049-v1-milestone-gate/spec.md) and checkable locally 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 gate conditions: [docs/v1-milestone.md](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 (planned for v2).

---

## Quick Start

**Requirements**: Rust 1.94+

```bash
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](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](quickstart.md) · [docs/app-consumable-entry-path.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](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](docs/wasm-agent-authoring-guide.md)

### An app with an AI coding agent

Building with Claude or another coding agent? [traverse-framework/claude-skills](https://github.com/traverse-framework/claude-skills) hosts Claude Skills that walk through checking the registry, authoring and composing capabilities, and validating them against the real `traverse-cli` — including this platform's current honest limitations.

### 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/workflow-composition-guide.md) · [docs/getting-started.md](docs/getting-started.md)

### Publish a reusable capability

Author, validate, and publish an executable WASM capability through the governed registry flow. Publishing validates the contract, use-case coverage, artifact digest, and referenced personas before creating the reviewable registry change.

→ [docs/capability-publish.md](docs/capability-publish.md) · [docs/capability-contract-authoring-guide.md](docs/capability-contract-authoring-guide.md)

### Your own app bundle

```bash
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](docs/expedition-example-authoring.md)

---

## Documentation

### Onboarding and tutorial path

| Goal | Start here | Continue with |
|---|---|---|
| First runnable flow | [quickstart.md](quickstart.md) | [docs/app-consumable-entry-path.md](docs/app-consumable-entry-path.md) |
| Learn the core path | [docs/getting-started.md](docs/getting-started.md) | [docs/expedition-example-authoring.md](docs/expedition-example-authoring.md) |
| Author a capability contract | [docs/capability-contract-authoring-guide.md](docs/capability-contract-authoring-guide.md) | [docs/getting-started.md](docs/getting-started.md) |
| Author an event contract | [docs/event-contract-authoring-guide.md](docs/event-contract-authoring-guide.md) | [docs/event-publishing-tutorial.md](docs/event-publishing-tutorial.md) |
| Build WASM capabilities | [docs/wasm-agent-authoring-guide.md](docs/wasm-agent-authoring-guide.md) | [docs/wasm-microservice-authoring-guide.md](docs/wasm-microservice-authoring-guide.md) |
| Integrate a downstream app | [docs/app-consumable-consumer-bundle.md](docs/app-consumable-consumer-bundle.md) | [docs/youaskm3-integration-validation.md](docs/youaskm3-integration-validation.md) |
| Troubleshoot a failure | [docs/troubleshooting.md](docs/troubleshooting.md) | [docs/quality-standards.md](docs/quality-standards.md) |

### Consumer and release surfaces

- [docs/releases/v0.9.1.md](docs/releases/v0.9.1.md) — current release notes
- [docs/releases/v0.8.1.md](docs/releases/v0.8.1.md) — prior release notes
- [docs/app-consumable-consumer-bundle.md](docs/app-consumable-consumer-bundle.md) — versioned consumer bundle
- [docs/app-consumable-package-release-pointer.md](docs/app-consumable-package-release-pointer.md) — package release pointer
- [docs/packaged-traverse-runtime-artifact.md](docs/packaged-traverse-runtime-artifact.md) — packaged runtime artifact
- [docs/packaged-traverse-mcp-server-artifact.md](docs/packaged-traverse-mcp-server-artifact.md) — packaged MCP server artifact
- [docs/youaskm3-canonical-app-http-path.md](docs/youaskm3-canonical-app-http-path.md) — canonical HTTP app path
- [docs/youaskm3-canonical-mcp-client-path.md](docs/youaskm3-canonical-mcp-client-path.md) — canonical MCP client path
- [docs/youaskm3-integration-validation.md](docs/youaskm3-integration-validation.md) — youaskm3 integration validation
- [docs/youaskm3-published-artifact-validation.md](docs/youaskm3-published-artifact-validation.md) — published-artifact validation
- [docs/youaskm3-compatibility-conformance-suite.md](docs/youaskm3-compatibility-conformance-suite.md) — compatibility conformance suite
- [docs/youaskm3-real-shell-validation.md](docs/youaskm3-real-shell-validation.md) — real shell validation
- [docs/mcp-real-agent-exercise.md](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](docs/v0.3.0-public-surface-compatibility.md) — v0.3.0 public surface compatibility
- [docs/v0.3.0-source-build-consumer-packaging.md](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](docs/v0.3.0-downstream-validation-path.md) — downstream validation path for v0.3.0
- [docs/youaskm3-v0.3.0-integration-readiness.md](docs/youaskm3-v0.3.0-integration-readiness.md) — v0.3.0 integration readiness index

### Reference

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

---

## Architecture

### Crates

In this repo:

| Crate | Role |
|---|---|
| `traverse-runtime` | Core execution engine — validates, places, and executes capabilities |
| `traverse-contracts` | Contract definitions, parsing, and validation |
| `traverse-cli-rs` | Command-line interface (binary: `traverse-cli`) — register, list, validate, run |
| `traverse-mcp` | Model Context Protocol stdio server and governed MCP-facing surface |
| `traverse-embedder` | Public Rust embedder SDK (`embedder-api/1.0.0`) for Linux GTK and CLI clients |
| `traverse-expedition-wasm` | Expedition example domain compiled to `wasm32-wasi` |
| `traverse-native-bridge` | Deterministic builder for the governed native runtime WebAssembly bridge |
| `traverse-swift-host` | Apple static-library feasibility host for the Traverse runtime bridge |

In a separate repo:

| Crate | Repo | Role |
|---|---|---|
| `traverse-registry` | [`traverse-framework/registry`](https://github.com/traverse-framework/registry) | Capability and event registries with deterministic traversal — extracted from this repo (spec 051) so capabilities can be published and versioned independently. Live catalog: [registry.traverse-framework.com](https://registry.traverse-framework.com/) |

---

## Contributing

Please read before opening a PR:

- [CONTRIBUTING.md](CONTRIBUTING.md)
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
- [SECURITY.md](SECURITY.md)
- [docs/quality-standards.md](docs/quality-standards.md)

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

[GitHub Project 1](https://github.com/orgs/traverse-framework/projects/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](https://www.universalmicroservices.com/) 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?*

| | UMA | Traverse |
|---|---|---|
| What it is | Architecture model + book | Working runtime implementation |
| Business capabilities | Defines the concept | Executes them with contracts and specs |
| Portability | Describes the pattern | Enforces it through WASM and adapters |
| Governance | Specifies the rules | Implements them as immutable specs and CI gates |
| AI safety | Describes requirements | Delivers through explainable runtime traces |

**If you want to understand the ideas:** [read the UMA book](https://www.universalmicroservices.com/) and explore the [UMA code examples](https://github.com/enricopiovesan/UMA-code-examples).

---

## Governance

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

| Artifact | Location | Role |
|---|---|---|
| Specs | [`specs/`](specs/) | Versioned, immutable, merge-gating |
| Contracts | [`contracts/`](contracts/) | Source of truth for runtime behavior |
| Constitution | [`.specify/memory/constitution.md`](.specify/memory/constitution.md) | Overrides all convenience decisions |
| CI gate | [`scripts/ci/spec_alignment_check.sh`](scripts/ci/spec_alignment_check.sh) | Deterministic, AI-agnostic |

### Approved Specs

105 approved specs currently govern this repo, spanning the runtime, contracts, registry integration, CLI, MCP surface, WASM execution, native embedding, event delivery, and durable local storage. The list changes as specs are approved — query it instead of reading a snapshot:

```bash
jq -r '.specs[].id' specs/governance/approved-specs.json
```

Foundational specs worth reading first: [001-foundation-v0-1](specs/001-foundation-v0-1/spec.md) (core runtime, CLI, MCP surface), [004-spec-alignment-gate](specs/004-spec-alignment-gate/spec.md) (this CI gate), [049-v1-milestone-gate](specs/049-v1-milestone-gate/spec.md) (what v1.0.0 requires).

---

## For Agents

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

### Entry points

| Agent | File | Purpose |
|---|---|---|
| Claude Code | [`CLAUDE.md`](CLAUDE.md) | Project context, governance rules, speckit workflow |
| Codex | [`AGENTS.md`](AGENTS.md) | Project context, coordination rules, speckit workflow |
| All agents | [`.specify/memory/constitution.md`](.specify/memory/constitution.md) | Governing constitution — mirrors [`traverse-framework/.github`](https://github.com/traverse-framework/.github) at the version in [`.governance-version`](.governance-version) |

### 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`](docs/multi-thread-workflow.md)

---

## License

Apache-2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).

## Related Work

- [UMA-code-examples](https://github.com/enricopiovesan/UMA-code-examples)
- [Universal Microservices Architecture — Book](https://www.amazon.com/dp/B0GTTTTQH4)
- [Contract-Driven AI Development (C-DAD) — White Paper](https://drive.google.com/file/d/1HC_ZWJl9aYaMeN78qiL3ZYBVY7mAGl3f/view)
- [Speaking](https://enricopiovesan.github.io/enricopiovesan/)
- [github.com/enricopiovesan](https://github.com/enricopiovesan)

traverse

traverse Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

traverse

traverse Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README