Crate traverse_embedder 

Public Traverse platform embedder SDK for Rust hosts.

This crate is the Linux GTK / CLI delivery of spec 068-public-platform-embedder-packages: a versioned public package that implements every embedder-api/1.0.0 operation (spec 057-embeddable-runtime-host) against an application-owned bundle, without any production dependency on traverse-cli serve or .traverse/server.json discovery.

Bundle input shape

BundleEmbedder::init consumes the application bundle manifest defined by spec 044-application-bundle-manifest: an app.manifest.json whose directory contains the referenced component manifests, capability contracts, WASM artifacts, and workflow definitions. The bundle is digest-verified at load; an invalid or incompatible bundle is rejected deterministically with a stable error code and never falls back to a network sidecar (spec 068 NFR-001).

Operation mapping

embedder-api/1.0.0 operation	Rust surface
runtime.init	BundleEmbedder::init (Result replaces status: ready | error)
runtime.shutdown	TraverseEmbedderApi::shutdown
runtime.submit	TraverseEmbedderApi::submit
runtime.subscribe	TraverseEmbedderApi::subscribe
compatible.start	TraverseEmbedderApi::start_compatible
compatible.stop	TraverseEmbedderApi::stop_compatible
compatible.kill	TraverseEmbedderApi::kill_compatible

Event and error mapping

Events are delivered synchronously, in emission order, as JSON values with a stable envelope (kind: "embedder_event", schema_version, event_id, sequence, event_type, workspace_id, app_id, session_id, data). Event types are exactly the embedder-api/1.0.0 set the runtime produces here: state_changed, capability_invoked, capability_result, and error. Runtime execution errors surface inside error events with the runtime’s stable snake_case error codes; embedder-boundary failures use EmbedderErrorCode codes. Identifiers (sess-*, req-*, evt-*, inst-*) are deterministic counters so the same bundled input produces identical event JSON on a fresh embedder.

Shutdown and cancellation behavior

TraverseEmbedderApi::shutdown force-terminates every running compatible capability instance (emitting a state_changed event per instance, state killed), then stops accepting work: every later submit, start_compatible, stop_compatible, or kill_compatible call is rejected with runtime_stopped. Shutdown is idempotent.

Compatibility and upgrade policy

• Embedder API: 1.0.0 (https://traverse.dev/embedder-api/1.0.0). A new IDL version requires a new conformance suite revision and a minor (pre-1.0: patch-compatible) crate release that states the new version in its release evidence.
• Bundle schema: SUPPORTED_BUNDLE_SCHEMA_VERSIONS. Bundles declaring any other schema_version are rejected at init with unsupported_bundle_schema and the mismatch is spelled out in the error message.
• Runtime: the Traverse runtime is linked natively into this crate at the same workspace version; there is no separately shipped runtime-WASM artifact for the Rust package. Release evidence (TraverseEmbedderApi::release_evidence) records the package version, the linked runtime version, the embedder API and conformance versions, and the digest of every bundled WASM component so a downstream binary can be connected to its inputs (spec 068 NFR-002).
• Semantic versioning: breaking public-API changes require a major version bump once the crate reaches 1.0.0; until then the whole workspace versions in lockstep.

Security posture

SecurityPosture::Production (the default) rejects unsigned bundle artifacts per spec 030-security-identity-model FR-013. SecurityPosture::Development permits locally built unsigned bundles for development and conformance fixtures, exactly like the dev sidecar’s loopback modes. Secrets never appear in events, errors, or release evidence: the embedder emits only runtime-owned outputs and stable error metadata (spec 068 NFR-004).

Structs

BundleEmbedder

Production embedder: loads an application-owned bundle and executes it through the natively linked Traverse runtime.

CompatibleLifecycleOutcome

compatible.stop / compatible.kill output.

CompatibleStartOutcome

compatible.start output.

EmbedderConfig

Configuration for BundleEmbedder::init (runtime.init input).

EmbedderError

A structured embedder-boundary error.

EmbedderTestDouble

Deterministic test double implementing TraverseEmbedderApi.

ShutdownOutcome

runtime.shutdown output (always stopped).

SubmitOutcome

runtime.submit output.

Enums

CompatibleLifecycleStatus

Compatible-capability lifecycle statuses.

EmbedderErrorCode

Stable embedder-boundary error codes.

SecurityPosture

Runtime artifact verification posture for the embedded runtime.

SubmitStatus

runtime.submit acceptance status.

Constants

EMBEDDER_API_VERSION

Implemented embedder API version (spec 057 IDL $id suffix).

EMBEDDER_CONFORMANCE_VERSION

Conformance suite revision this package certifies against (spec 057).

SUPPORTED_BUNDLE_SCHEMA_VERSIONS

Application bundle manifest schema_version values this package accepts.

Traits

TraverseEmbedderApi

The uniform embedder-api/1.0.0 operation surface (spec 057 FR-003).

Type Aliases

EventCallback

Ordered, synchronous event subscriber.