How Traverse works

Capability Contracts

Every capability in Traverse is governed by a machine-readable contract. The contract is the source of truth. It declares what the capability does, what inputs it requires, what outputs it guarantees, and where it can run.

Nothing executes without a verified contract. The runtime reads the contract before placement, validates inputs before execution, and checks postconditions after. The contract is not documentation. It is enforcement.

{
  // Identity
  "id": "namespace.name",          // e.g. "pricing.eligibility-check"
  "version": "MAJOR.MINOR.PATCH",

  // Lifecycle: draft | active | deprecated | retired | archived
  "lifecycle": "active",

  // Execution
  "execution": {
    "binary_format": "wasm32-wasi",
    "entrypoint": "function_name",
    "preferred_targets": ["edge", "cloud"],
    "constraints": {
      "host_api_access": "none",       // none | exception_required
      "network_access": "forbidden",   // forbidden | required
      "filesystem_access": "none"     // none | sandbox_only
    }
  },

  // Input/output schemas (JSON Schema)
  "inputs": { /* JSON Schema */ },
  "outputs": { /* JSON Schema */ },

  // Events
  "events": {
    "emits": ["event-id-1"],
    "consumes": ["event-id-2"]
  }
}

Event contracts follow the same pattern: identity, payload schema, publishers, subscribers, and compatibility policy.

Registry

The registry is the single source of truth for what the system can do. It holds capability contracts, event contracts, and workflow definitions. All of them are indexed and queryable at runtime.

Capabilities are loaded into the registry via registry bundles — manifests that group related capabilities, events, and workflows into a deployable unit. The CLI validates bundles before they are registered.

AI agents and orchestrators query the registry to discover capabilities by contract. Composition follows declared contracts — not inferred APIs or guesswork.

Runtime & Execution Model

The Traverse runtime is a state machine. Each execution follows a deterministic path from idle to completed (or error). Every state transition is recorded in the trace.

The runtime resolves the correct capability from the registry, validates inputs against the contract, executes the WASM binary, validates outputs, emits declared events, and writes the trace. Same inputs always produce the same path.

Placement Targets

Placement is a client decision, not a fixed deployment target. A capability is device-independent — the same WASM binary runs on any client without modification, and executes locally by default. The contract declares which environments a capability is allowed to run in; the client evaluates that against its own context (resource constraints, latency, connectivity) and decides, heuristically, whether to run locally or delegate a subset of the capability to the server.

Currently, only the local executor is fully implemented. Other targets are specified in contracts and will be resolved as executor adapters ship.

Trace Artifacts

Every execution produces a structured trace artifact. The trace records every decision the runtime made: which capability was discovered, why it was selected, what inputs were validated, what events were emitted, and what the final output was.

Traces are queryable and auditable. For AI pipelines they are the compliance record. Proof that every action was governed by a contract.

{
  "trace_id": "trv_8f2a1c...",
  "capability": "expedition.planning.plan-expedition",
  "version": "1.0.0",
  "status": "completed",
  "placement": "local",
  "discovery": {
    "candidates": 1,
    "selected": "plan-expedition",
    "reason": "contract match · preferred target"
  },
  "execution": {
    "steps": 5,
    "events_emitted": 5,
    "duration_ms": 142
  },
  "contract_validated": true,
  "preconditions_met": true,
  "postconditions_met": true
}

Workflow Composition

Workflows compose multiple capabilities into a deterministic execution graph. Each node is a governed capability. Each edge is a typed event. The runtime traverses the graph in order. Same inputs, same path, every time.

Workflow definitions declare: the participating capabilities, the events each emits, the input and output shapes, and the terminal conditions. The runtime validates the composition before any execution begins.

{
  "id": "expedition.planning.plan-expedition",
  "version": "1.0.0",
  "graph": {
    "capabilities": [
      "interpret-expedition-intent",
      "capture-expedition-objective",
      "assess-conditions-summary",
      "validate-team-readiness",
      "assemble-expedition-plan"
    ]
  },
  "terminal_conditions": {
    "success": "expedition-plan-assembled",
    "failure": "any-capability-error"
  }
}

Spec-Driven Development

Traverse is built spec-first. Every component has an approved, versioned specification before implementation begins. The spec is the source of truth. The code is the proof.

9 governing specs are approved as of v0.7.0, covering: foundation, capability contracts, event contracts, spec alignment gate, capability registry, runtime request execution, workflow registry traversal, expedition domain, and expedition artifacts.