From afcb1711a373f5842a0f89669c1c740ab24d58f3 Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Thu, 30 Jul 2026 10:32:31 -0600 Subject: [PATCH] fix: correct fabricated contract/workflow JSON shapes on concepts page The contract.json anatomy example used a flat "wasm32-wasi"/function- name entrypoint and top-level inputs/outputs instead of the real CapabilityContract shape (nested inputs.schema/outputs.schema, an entrypoint object, top-level emits/consumes), and omitted precondi- tions/postconditions entirely despite the surrounding prose naming them as the core concept. The workflow definition excerpt was worse: a graph.capabilities + terminal_conditions shape that doesn't exist anywhere in the real runtime. The actual schema is nodes/edges/start_node/terminal_nodes, verified against workflows/examples/expedition/plan-expedition/ workflow.json in traverse-framework/traverse. This fabricated shape was traced back as the likely source of an AI agent independently inventing the same wrong schema when asked to build a Traverse workflow without more accurate reference material. Also fixes a stale placement-targets claim ("only local is fully implemented") that predates the browser embedder SDK shipping. Co-Authored-By: Claude Sonnet 5 --- src/pages/docs/concepts.astro | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/docs/concepts.astro b/src/pages/docs/concepts.astro index ba2d53c..9d9d906 100644 --- a/src/pages/docs/concepts.astro +++ b/src/pages/docs/concepts.astro @@ -3,7 +3,7 @@ import SubpageLayout from '@layouts/SubpageLayout.astro'; import DocsSidebar from '@components/DocsSidebar.astro'; const _docsBefore = "
\n \n "; -const _docsAfter = "
\n
\n
Core Concepts
\n

How Traverse works

\n

The key ideas behind contracts, registries, runtime execution, placement, traces, and workflows.

\n
\n\n \n
\n

Capability Contracts

\n

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.

\n

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.

\n
\n
contract.json: anatomy
\n
\n
{\n  // Identity\n  \"id\": \"namespace.name\",          // e.g. \"pricing.eligibility-check\"\n  \"version\": \"MAJOR.MINOR.PATCH\",\n\n  // Lifecycle: draft | active | deprecated | retired | archived\n  \"lifecycle\": \"active\",\n\n  // Execution\n  \"execution\": {\n    \"binary_format\": \"wasm32-wasi\",\n    \"entrypoint\": \"function_name\",\n    \"preferred_targets\": [\"edge\", \"cloud\"],\n    \"constraints\": {\n      \"host_api_access\": \"none\",       // none | exception_required\n      \"network_access\": \"forbidden\",   // forbidden | required\n      \"filesystem_access\": \"none\"     // none | sandbox_only\n    }\n  },\n\n  // Input/output schemas (JSON Schema)\n  \"inputs\": { /* JSON Schema */ },\n  \"outputs\": { /* JSON Schema */ },\n\n  // Events\n  \"events\": {\n    \"emits\": [\"event-id-1\"],\n    \"consumes\": [\"event-id-2\"]\n  }\n}
\n
\n
\n

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

\n
\n\n \n
\n

Registry

\n

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.

\n

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.

\n
\n
bundle structure
\n
\n
registry-bundle/
\n
manifest.json
\n
capabilities/
\n
plan-expedition/contract.json
\n
interpret-intent/contract.json
\n
events/
\n
expedition-plan-assembled/contract.json
\n
workflows/
\n
plan-expedition/definition.json
\n
\n
\n

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

\n
\n\n \n
\n

Runtime & Execution Model

\n

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.

\n
\n
idle
\n
→
\n
loading_registry
\n
→
\n
ready
\n
→
\n
discovering
\n
→
\n
evaluating_constraints
\n
→
\n
selecting
\n
→
\n
executing
\n
→
\n
emitting_events
\n
→
\n
completed
\n
/
\n
error
\n
\n

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.

\n
\n

Core crates

\n
\n
traverse-runtimeCore execution engine
\n
traverse-contractsContract parsing & validation
\n
traverse-registryCapability & event registries
\n
traverse-cliregister · list · validate · run
\n
traverse-mcpMCP stdio server
\n
\n
\n
\n\n \n
\n

Placement Targets

\n

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.

\n
\n
\n
browser
\n
Executes inside the user's browser via the local adapter. No network required.
\n
\n
\n
edge
\n
Runs at the network edge. Low latency, close to the user.
\n
\n
\n
cloud
\n
Standard cloud execution. Used as fallback when edge is unavailable.
\n
\n
\n
ai-pipeline
\n
Embedded in an AI agent workflow. Governed and contract-validated.
\n
\n
\n
local
\n
Local machine execution. The default executor on native hosts as of v0.8.1.
\n
\n
\n
device
\n
On-device execution for edge hardware scenarios.
\n
\n
\n

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

\n
\n\n \n
\n

Trace Artifacts

\n

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.

\n

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

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

Workflow Composition

\n

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.

\n

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.

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

Spec-Driven Development

\n

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.

\n

73 governing specs are approved as of v0.8.1, covering everything from the foundation, capability and event contracts, and the registries through runtime execution, placement routing, the embedder SDKs, the durable event journal, and the example domains. The first nine — foundation, capability contracts, event contracts, the spec alignment gate, the capability registry, runtime request execution, workflow registry traversal, and the expedition domain and artifacts — remain the core of the system.

\n
\n

CI gates — every PR must pass

\n
\n
Spec alignment gate — code matches approved spec
\n
100% test coverage for core logic
\n
No unsafe code (#![forbid(unsafe_code)])
\n
No unwrap / panic / TODO in production code
\n
Formatting, linting, dependency checks
\n
SBOM generation (CycloneDX)
\n
\n
\n
\n
\n
\n\n"; +const _docsAfter = "
\n
\n
Core Concepts
\n

How Traverse works

\n

The key ideas behind contracts, registries, runtime execution, placement, traces, and workflows.

\n
\n\n \n
\n

Capability Contracts

\n

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.

\n

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.

\n
\n
contract.json: anatomy
\n
\n
{\n  // Identity\n  \"id\": \"namespace.name\",          // e.g. \"pricing.eligibility-check\"\n  \"version\": \"MAJOR.MINOR.PATCH\",\n\n  // Lifecycle: draft | active | deprecated | retired | archived\n  \"lifecycle\": \"active\",\n\n  // What must be true before it runs, and what it guarantees after\n  \"preconditions\": [{ \"id\": \"...\", \"description\": \"...\" }],\n  \"postconditions\": [{ \"id\": \"...\", \"description\": \"...\" }],\n\n  // Execution\n  \"execution\": {\n    \"binary_format\": \"wasm\",\n    \"entrypoint\": { \"kind\": \"wasi-command\", \"command\": \"run\" },\n    \"preferred_targets\": [\"edge\", \"cloud\"],\n    \"constraints\": {\n      \"host_api_access\": \"none\",       // none | exception_required\n      \"network_access\": \"forbidden\",   // forbidden | required\n      \"filesystem_access\": \"none\"     // none | sandbox_only\n    }\n  },\n\n  // Input/output schemas (JSON Schema, nested under \"schema\")\n  \"inputs\": { \"schema\": { /* JSON Schema */ } },\n  \"outputs\": { \"schema\": { /* JSON Schema */ } },\n\n  // Events this capability emits or reacts to\n  \"emits\": [\"event-id-1\"],\n  \"consumes\": [\"event-id-2\"]\n}
\n
\n
\n

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

\n
\n\n \n
\n

Registry

\n

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.

\n

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.

\n
\n
bundle structure
\n
\n
registry-bundle/
\n
manifest.json
\n
capabilities/
\n
plan-expedition/contract.json
\n
interpret-intent/contract.json
\n
events/
\n
expedition-plan-assembled/contract.json
\n
workflows/
\n
plan-expedition/definition.json
\n
\n
\n

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

\n
\n\n \n
\n

Runtime & Execution Model

\n

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.

\n
\n
idle
\n
→
\n
loading_registry
\n
→
\n
ready
\n
→
\n
discovering
\n
→
\n
evaluating_constraints
\n
→
\n
selecting
\n
→
\n
executing
\n
→
\n
emitting_events
\n
→
\n
completed
\n
/
\n
error
\n
\n

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.

\n
\n

Core crates

\n
\n
traverse-runtimeCore execution engine
\n
traverse-contractsContract parsing & validation
\n
traverse-registryCapability & event registries
\n
traverse-cliregister · list · validate · run
\n
traverse-mcpMCP stdio server
\n
\n
\n
\n\n \n
\n

Placement Targets

\n

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.

\n
\n
\n
browser
\n
Executes inside the user's browser via the local adapter. No network required.
\n
\n
\n
edge
\n
Runs at the network edge. Low latency, close to the user.
\n
\n
\n
cloud
\n
Standard cloud execution. Used as fallback when edge is unavailable.
\n
\n
\n
ai-pipeline
\n
Embedded in an AI agent workflow. Governed and contract-validated.
\n
\n
\n
local
\n
Local machine execution. The default executor on native hosts as of v0.8.1.
\n
\n
\n
device
\n
On-device execution for edge hardware scenarios.
\n
\n
\n

Currently, local (native) and browser are the only targets with a real, shipped executor — see Platforms for the full, evidence-linked status. Other targets are specified in contracts and will be resolved as executor adapters ship.

\n
\n\n \n
\n

Trace Artifacts

\n

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.

\n

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

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

Workflow Composition

\n

Workflows compose multiple capabilities into a deterministic execution graph. Each node names one governed capability and how data flows to and from it; each edge names the trigger that advances traversal to the next node. The runtime traverses the graph in order. Same inputs, same path, every time.

\n

Workflow definitions declare: the nodes (each a capability, reading fields via from_workflow_input and writing them via to_workflow_state into the workflow's accumulated state — not just its original input), the edges connecting them, a start_node, and the terminal_nodes where traversal ends. The runtime validates the composition before any execution begins.

\n
\n
workflow definition (excerpt)
\n
\n
{\n  \"kind\": \"workflow_definition\",\n  \"id\": \"expedition.planning.plan-expedition\",\n  \"version\": \"1.0.0\",\n  \"nodes\": [\n    {\n      \"node_id\": \"capture_objective\",\n      \"capability_id\": \"expedition.planning.capture-expedition-objective\",\n      \"input\": { \"from_workflow_input\": [\"destination\"] },\n      \"output\": { \"to_workflow_state\": [\"objective\"] }\n    },\n    {\n      \"node_id\": \"interpret_intent\",\n      \"capability_id\": \"expedition.planning.interpret-expedition-intent\",\n      \"input\": { \"from_workflow_input\": [\"objective\"] },\n      \"output\": { \"to_workflow_state\": [\"interpreted_intent\"] }\n    }\n  ],\n  \"edges\": [\n    { \"from\": \"capture_objective\", \"to\": \"interpret_intent\", \"trigger\": \"direct\" }\n  ],\n  \"start_node\": \"capture_objective\",\n  \"terminal_nodes\": [\"assemble_plan\"]\n}
\n
\n
\n
\n\n \n
\n

Spec-Driven Development

\n

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.

\n

73 governing specs are approved as of v0.8.1, covering everything from the foundation, capability and event contracts, and the registries through runtime execution, placement routing, the embedder SDKs, the durable event journal, and the example domains. The first nine — foundation, capability contracts, event contracts, the spec alignment gate, the capability registry, runtime request execution, workflow registry traversal, and the expedition domain and artifacts — remain the core of the system.

\n
\n

CI gates — every PR must pass

\n
\n
Spec alignment gate — code matches approved spec
\n
100% test coverage for core logic
\n
No unsafe code (#![forbid(unsafe_code)])
\n
No unwrap / panic / TODO in production code
\n
Formatting, linting, dependency checks
\n
SBOM generation (CycloneDX)
\n
\n
\n
\n
\n\n\n"; ---