Crate traverse_embedder

Expand description

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.
EmbeddedDataStoreError: Safe public projection of a DataStore failure.
EmbeddedTraceApiError: A public Trace API failure with a stable code and deliberately generic text.
EmbeddedTraceDetail: Safe public diagnostic detail for one retained local trace.
EmbeddedTracePage: A bounded, cursor-paged public Trace API response.
EmbeddedTracePhase: One public phase code in a safe trace projection.
EmbeddedTracePlacement: Safe placement evidence for a public trace detail.
EmbeddedTraceSelectedTarget: Safe selected-target evidence for a public trace detail.
EmbeddedTraceSummary: Safe list-oriented record for one completed local execution.
EmbedderConfig: Configuration for BundleEmbedder::init (runtime.init input).
EmbedderError: A structured embedder-boundary error.
EmbedderTestDouble: Deterministic test double implementing TraverseEmbedderApi.
HostDataStore: An explicitly host-owned local store that may be injected into a BundleEmbedder. The host selects its root and lifecycle before constructing this wrapper; Traverse never receives a root path.
HostRegistryCache: Host-chosen content-addressed registry cache root.
RegistryCacheError: Secret-free registry-cache failure.
RegistryPrepareEvidence: FR-008 resolution evidence retained after a successful prepare.
ShutdownOutcome: runtime.shutdown output (always stopped).
SubmitOutcome: runtime.submit output.
VerifiedRegistryDependency: Offline lookup of a previously prepared registry_ref.

Enums§

CompatibleLifecycleStatus: Compatible-capability lifecycle statuses.
EmbeddedTraceApiErrorCode: Stable machine-readable public Trace API failure codes (spec 517 FR-010).
EmbeddedTraceOutcome: The safe terminal outcome exposed by the public embedded Trace API.
EmbedderErrorCode: Stable embedder-boundary error codes.
RegistryCacheErrorCode: Stable, secret-free registry-cache failure codes (Spec 080 FR-007).
SecurityPosture: Runtime artifact verification posture for the embedded runtime.
SubmitStatus: runtime.submit acceptance status.

Constants§

EMBEDDED_TRACE_API_VERSION: Implemented companion Trace API version (spec 517).
EMBEDDED_TRACE_MAX_PAGE_SIZE: Largest page the public embedded Trace API returns in one call.
EMBEDDED_TRACE_RETENTION_LIMIT: Maximum number of public trace records retained by one embedded session.
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§

EmbeddedTraceApi: The additive embedded-trace-api/1.0.0 companion surface (spec 517).
RegistryArtifactFetcher: Host-supplied network fetch used only by prepare.
TraverseEmbedderApi: The uniform embedder-api/1.0.0 operation surface (spec 057 FR-003).

Functions§

prepare_registry_dependency: Prepare one registry_ref into a host-owned verified cache.
resolve_registry_component: Resolve a registry_ref into a registry component materialization.
resolve_registry_dependency_offline: Resolve a registry_ref from verified local cache entries only.

Type Aliases§

EventCallback: Ordered, synchronous event subscriber.