Various final cleanup

Sushisource · Sushisource · commit 6279bedeee95 · 2026-04-28T16:34:28.000-07:00
diff --git a/crates/sdk-core/tests/integ_tests/wasm_workflow_tests.rs b/crates/sdk-core/tests/integ_tests/wasm_workflow_tests.rs
@@ -14,12 +14,29 @@ const WASM_WORKFLOW_TYPE: &str = "HelloWorkflow";
 #[tokio::test]
 async fn wasm_workflow_component_executes() {
     let component_path = build_wasm_hello_component().await;
-    let mut starter = CoreWfStarter::new("wasm_workflow_component_executes");
+    let component = WasmWorkflowComponent::from_file(WASM_COMPONENT_ID, component_path)
+        .expect("sample WASM component should be loadable");
+    run_hello_workflow("wasm_workflow_component_executes", component).await;
+}
+
+// Mirrors `wasm_workflow_component_executes` but loads the component bytes into memory and
+// registers via `from_bytes`, exercising the dynamic-blob loading path that callers will use
+// for runtime-supplied components (e.g. fetched over the network rather than read from disk).
+#[tokio::test]
+async fn wasm_workflow_component_executes_from_bytes() {
+    let component_path = build_wasm_hello_component().await;
+    let bytes = tokio::fs::read(&component_path)
+        .await
+        .expect("WASM component file should be readable");
+    let component = WasmWorkflowComponent::from_bytes(WASM_COMPONENT_ID, bytes)
+        .expect("WASM component bytes should be loadable");
+    run_hello_workflow("wasm_workflow_component_executes_from_bytes", component).await;
+}
+
+async fn run_hello_workflow(test_name: &'static str, component: WasmWorkflowComponent) {
+    let mut starter = CoreWfStarter::new(test_name);
     starter.sdk_config.task_types = WorkerTaskTypes::workflow_only();
-    starter.sdk_config.register_wasm_workflow(
-        WasmWorkflowComponent::from_file(WASM_COMPONENT_ID, component_path)
-            .expect("sample WASM component should be loadable"),
-    );
+    starter.sdk_config.register_wasm_workflow(component);
 
     let mut worker = starter.worker().await;
     let client = starter.get_client().await;
diff --git a/crates/sdk/src/workflow_registry.rs b/crates/sdk/src/workflow_registry.rs
@@ -10,13 +10,15 @@ use temporalio_common::{
         coresdk::workflow_activation::InitializeWorkflow, temporal::api::common::v1::Payload,
     },
 };
-use temporalio_workflow::runtime::{
+use temporalio_workflow::{
     BaseWorkflowContext,
-    entry::WorkflowImplementation,
-    guest::WorkflowInstance,
-    host::WorkflowHost,
-    instance::{GuestWorkflowInstance, instantiate_workflow},
-    types::WorkflowDefinitionDescriptor,
+    runtime::{
+        entry::WorkflowImplementation,
+        guest::WorkflowInstance,
+        host::WorkflowHost,
+        instance::{GuestWorkflowInstance, instantiate_workflow},
+        types::WorkflowDefinitionDescriptor,
+    },
 };
 
 /// Host-owned execution inputs used to instantiate a single workflow run.
diff --git a/crates/workflow/src/component.rs b/crates/workflow/src/component.rs
@@ -1,7 +1,6 @@
 //! Component-model guest export support for workflow crates.
-
-#![allow(missing_docs)]
-
+//!
+//! Everything in this module is internal SDK/component glue.
 use crate::{
     BaseWorkflowContext,
     runtime::{
@@ -74,8 +73,8 @@ impl<T: StaticWorkflowComponent> wit_guest::Guest for ExportedComponent<T> {
             initialize_workflow: decode_proto(init.initialize_workflow),
         };
         let workflow_type = init.initialize_workflow.workflow_type.clone();
-        let instance = T::instantiate_workflow(&workflow_type, init, host)
-            .map_err(convert_failure_to_wit_box)?;
+        let instance =
+            T::instantiate_workflow(&workflow_type, init, host).map_err(|e| e.encode_to_vec())?;
         Ok(wit_guest::WorkflowInstance::new(ExportedWorkflowInstance(
             RefCell::new(instance),
         )))
@@ -106,20 +105,18 @@ impl wit_guest::GuestWorkflowInstance for ExportedWorkflowInstance {
                                 wit_types::QueryResponse {
                                     response: response
                                         .result
-                                        .map(encode_proto)
-                                        .map_err(encode_proto),
+                                        .map(|e| e.encode_to_vec())
+                                        .map_err(|e| e.encode_to_vec()),
                                 },
                             )
                         }
                         ActivationJobResult::UpdateRejected(failure) => {
-                            wit_types::ActivationJobResult::UpdateRejected(
-                                convert_failure_to_wit_box(failure),
-                            )
+                            wit_types::ActivationJobResult::UpdateRejected(failure.encode_to_vec())
                         }
                     })
                     .collect(),
             })
-            .map_err(convert_failure_to_wit_box)
+            .map_err(|e| e.encode_to_vec())
     }
 
     fn poll_routine(
@@ -140,28 +137,28 @@ impl wit_guest::GuestWorkflowInstance for ExportedWorkflowInstance {
                             MainRoutineCompletion::TaskFailed(task_failure) => {
                                 wit_types::MainRoutineCompletion::TaskFailed(
                                     wit_types::TaskFailure {
-                                        failure: convert_failure_to_wit_box(task_failure.failure),
+                                        failure: task_failure.failure.encode_to_vec(),
                                         force_cause: task_failure.force_cause,
                                     },
                                 )
                             }
                             MainRoutineCompletion::Terminal(outcome) => {
                                 wit_types::MainRoutineCompletion::Terminal(match *outcome {
                                     TerminalOutcome::Completed(payload) => {
-                                        wit_types::TerminalOutcome::Completed(encode_proto(payload))
+                                        wit_types::TerminalOutcome::Completed(
+                                            payload.encode_to_vec(),
+                                        )
                                     }
                                     TerminalOutcome::Failed(failure) => {
-                                        wit_types::TerminalOutcome::Failed(
-                                            convert_failure_to_wit_box(failure),
-                                        )
+                                        wit_types::TerminalOutcome::Failed(failure.encode_to_vec())
                                     }
                                     TerminalOutcome::Cancelled => {
                                         wit_types::TerminalOutcome::Cancelled
                                     }
                                     TerminalOutcome::ContinueAsNew(req) => {
-                                        wit_types::TerminalOutcome::ContinueAsNew(encode_proto(
-                                            *req,
-                                        ))
+                                        wit_types::TerminalOutcome::ContinueAsNew(
+                                            req.encode_to_vec(),
+                                        )
                                     }
                                 })
                             }
@@ -170,9 +167,9 @@ impl wit_guest::GuestWorkflowInstance for ExportedWorkflowInstance {
                     RoutineCompletion::Signal(result) => {
                         wit_types::RoutineCompletion::Signal(match result {
                             Ok(()) => wit_types::SignalRoutineCompletion::Succeeded,
-                            Err(failure) => wit_types::SignalRoutineCompletion::Failed(
-                                convert_failure_to_wit_box(failure),
-                            ),
+                            Err(failure) => {
+                                wit_types::SignalRoutineCompletion::Failed(failure.encode_to_vec())
+                            }
                         })
                     }
                     RoutineCompletion::Update(completion) => {
@@ -183,7 +180,7 @@ impl wit_guest::GuestWorkflowInstance for ExportedWorkflowInstance {
                             } => wit_types::UpdateRoutineCompletion::Completed(
                                 wit_types::UpdateRoutineSuccess {
                                     protocol_instance_id,
-                                    value: encode_proto(result),
+                                    value: result.encode_to_vec(),
                                 },
                             ),
                             UpdateRoutineCompletion::Rejected {
@@ -192,15 +189,15 @@ impl wit_guest::GuestWorkflowInstance for ExportedWorkflowInstance {
                             } => wit_types::UpdateRoutineCompletion::Rejected(
                                 wit_types::UpdateRoutineRejection {
                                     protocol_instance_id,
-                                    failure: convert_failure_to_wit_box(failure),
+                                    failure: failure.encode_to_vec(),
                                 },
                             ),
                         })
                     }
                 }),
                 made_progress: result.made_progress,
             })
-            .map_err(convert_failure_to_wit_box)
+            .map_err(|e| e.encode_to_vec())
     }
 }
 
@@ -237,18 +234,10 @@ impl WorkflowHost for ImportedWorkflowHost {
     }
 
     fn push_command(&self, command: WorkflowCommand) {
-        wit_host::push_command(&encode_proto(command));
+        wit_host::push_command(&command.encode_to_vec());
     }
 }
 
-fn convert_failure_to_wit_box(failure: WorkflowFailure) -> wit_types::Failure {
-    encode_proto(*failure)
-}
-
-fn encode_proto<M: Message>(message: M) -> Vec<u8> {
-    message.encode_to_vec()
-}
-
 fn decode_proto<M: Message + prost::Name + Default>(bytes: Vec<u8>) -> M {
     M::decode(bytes.as_slice()).unwrap_or_else(|err| {
         let n = M::NAME;
diff --git a/crates/workflow/src/lib.rs b/crates/workflow/src/lib.rs
@@ -13,10 +13,26 @@ pub mod __private {
 
 #[doc(hidden)]
 pub mod component;
+#[doc(hidden)]
 pub mod runtime;
 mod workflow_context;
 pub mod workflows;
 
+#[doc(hidden)]
+pub use runtime::model::{CancellableID, UnblockEvent};
+pub use runtime::model::{TimerResult, WorkflowResult, WorkflowTermination};
+#[doc(hidden)]
+pub use runtime::{SdkWakeGuard, is_sdk_wake};
+pub use workflow_context::{
+    ActivityCloseTimeouts, ActivityExecutionError, ActivityOptions, BaseWorkflowContext,
+    CancellableFuture, ChildWorkflowExecutionError, ChildWorkflowOptions, ChildWorkflowSignalError,
+    ContinueAsNewOptions, ExternalWorkflowHandle, LocalActivityOptions, NexusOperationOptions,
+    ParentWorkflowInfo, RootWorkflowInfo, Signal, SignalData,
+    StartChildWorkflowExecutionFailedCause, StartedChildWorkflow, SyncWorkflowContext,
+    TimerOptions, WorkflowContext, WorkflowContextView,
+};
+pub use workflows::{join, join_all, select};
+
 #[macro_export]
 #[doc(hidden)]
 macro_rules! __temporal_select {
@@ -92,17 +108,3 @@ macro_rules! export_workflow_module {
         };
     };
 }
-
-#[doc(hidden)]
-pub use runtime::model::{CancellableID, UnblockEvent};
-pub use runtime::model::{TimerResult, WorkflowResult, WorkflowTermination};
-#[doc(hidden)]
-pub use runtime::{SdkWakeGuard, is_sdk_wake};
-pub use workflow_context::{
-    ActivityCloseTimeouts, ActivityExecutionError, ActivityOptions, BaseWorkflowContext,
-    CancellableFuture, ChildWorkflowExecutionError, ChildWorkflowOptions, ChildWorkflowSignalError,
-    ContinueAsNewOptions, ExternalWorkflowHandle, LocalActivityOptions, NexusOperationOptions,
-    ParentWorkflowInfo, RootWorkflowInfo, Signal, SignalData,
-    StartChildWorkflowExecutionFailedCause, StartedChildWorkflow, SyncWorkflowContext,
-    TimerOptions, WorkflowContext, WorkflowContextView,
-};
diff --git a/crates/workflow/src/runtime/entry.rs b/crates/workflow/src/runtime/entry.rs
@@ -277,7 +277,7 @@ pub trait ExecutableAsyncUpdate<U: UpdateDefinition>: WorkflowImplementation {
 }
 
 /// Deserialize handler input from payloads.
-pub fn deserialize_input<I: TemporalDeserializable + 'static>(
+pub(crate) fn deserialize_input<I: TemporalDeserializable + 'static>(
     payloads: Vec<Payload>,
     converter: &PayloadConverter,
 ) -> Result<I, WorkflowError> {
@@ -289,7 +289,7 @@ pub fn deserialize_input<I: TemporalDeserializable + 'static>(
 }
 
 /// Serialize handler output to a payload.
-pub fn serialize_output<O: TemporalSerializable + 'static>(
+pub(crate) fn serialize_output<O: TemporalSerializable + 'static>(
     output: &O,
     converter: &PayloadConverter,
 ) -> Result<Payload, WorkflowError> {
@@ -301,7 +301,7 @@ pub fn serialize_output<O: TemporalSerializable + 'static>(
 }
 
 /// Wrap a handler error into WorkflowError.
-pub fn wrap_handler_error(e: Box<dyn std::error::Error + Send + Sync>) -> WorkflowError {
+pub(crate) fn wrap_handler_error(e: Box<dyn std::error::Error + Send + Sync>) -> WorkflowError {
     WorkflowError::Execution(anyhow::anyhow!(e))
 }
 
diff --git a/crates/workflow/src/runtime/guest.rs b/crates/workflow/src/runtime/guest.rs
@@ -1,7 +1,5 @@
 //! High-level guest-side runtime traits mirroring the checked-in WIT interface.
 
-#![allow(missing_docs)]
-
 use crate::runtime::types::{
     ActivationResult, RoutineId, RoutinePollResult, WorkflowActivation, WorkflowFailure,
 };
diff --git a/crates/workflow/src/runtime/instance.rs b/crates/workflow/src/runtime/instance.rs
@@ -1,11 +1,8 @@
 //! Guest-side workflow execution implementation used by native and future WASM hosts.
 
-#![allow(missing_docs)]
-
 use crate::{
-    WorkflowContext,
+    BaseWorkflowContext, WorkflowContext,
     runtime::{
-        BaseWorkflowContext,
         entry::{WorkflowError, WorkflowImplementation},
         guest::WorkflowInstance,
         model::{TimerResult, UnblockEvent, WorkflowResult, WorkflowTermination},
diff --git a/crates/workflow/src/runtime/mod.rs b/crates/workflow/src/runtime/mod.rs
@@ -1,8 +1,7 @@
 //! Unstable runtime-facing APIs for workflow hosts and future WASM integrations.
 //!
 //! These modules collect the parts of the workflow crate that are intended for SDK/runtime glue
-//! rather than normal workflow authors. The long-term target for this namespace is the WIT surface
-//! checked in under `crates/workflow/wit/`.
+//! rather than normal workflow authors.
 
 use std::{
     cell::Cell,
@@ -18,8 +17,6 @@ pub mod instance;
 pub mod model;
 pub mod types;
 
-pub use crate::workflow_context::{BaseWorkflowContext, WorkflowContextView};
-
 thread_local! {
     static SDK_WAKE_DEPTH: Cell<u32> = const { Cell::new(0) };
 }
diff --git a/crates/workflow/src/runtime/model.rs b/crates/workflow/src/runtime/model.rs
@@ -1,7 +1,5 @@
 //! Runtime protocol and execution model types shared by workflow code and native hosts.
 
-#![allow(missing_docs)]
-
 use crate::{
     runtime::types::ContinueAsNewRequest,
     workflow_context::{
diff --git a/crates/workflow/src/runtime/types.rs b/crates/workflow/src/runtime/types.rs
@@ -1,6 +1,6 @@
 //! Shared runtime model types mirroring the checked-in WIT interface.
-
-#![allow(missing_docs)]
+//!
+//! All items here are SDK/runtime glue.
 
 use temporalio_common_wasm::protos::{
     coresdk::{
diff --git a/crates/workflow/src/workflows.rs b/crates/workflow/src/workflows.rs
@@ -94,8 +94,7 @@ use futures_util::FutureExt;
 
 pub use crate::runtime::entry::{
     ExecutableAsyncSignal, ExecutableAsyncUpdate, ExecutableQuery, ExecutableSyncSignal,
-    ExecutableSyncUpdate, WorkflowError, WorkflowImplementation, deserialize_input,
-    serialize_output, serialize_result, wrap_handler_error,
+    ExecutableSyncUpdate, WorkflowError, WorkflowImplementation, serialize_result,
 };
 
 /// Deterministic `join_all` for use in Temporal workflows.
diff --git a/crates/workflow/wit/README.md b/crates/workflow/wit/README.md
@@ -41,3 +41,37 @@ The runtime should support two backends behind the same worker translation logic
 - a WASM backend that invokes a component implementing `workflow-module`
 
 The goal is one logical execution model with two transport backends, not two independent workers.
+
+## Stability
+
+The package is published as `temporal:workflow-runtime@0.1.0` and is **not yet stable**. Until
+this is bumped to `1.0.0` any release may bump the minor version with breaking changes. Once
+external SDKs (Python, TypeScript, Go, etc.) begin compiling guest workflows against this WIT,
+breaking changes need to follow normal SemVer discipline: bump the package version, dual-export
+the old and new world from the host for a deprecation window, and document the migration path.
+
+Changes that force a major bump include:
+
+- Renaming or removing any record field, variant case, function, interface, or world.
+- Changing a field/case/parameter type (including widening `u32` to `u64` etc.).
+- Reordering variant cases (the discriminant order is part of the ABI).
+- Changing the proto messages encoded into `list<u8>`-typed fields (`failure`, `payload`,
+  `workflow-command`, `workflow-activation`, `continue-as-new-request`).
+
+## Synchronous ABI and the WASIp3 future
+
+The current guest interface is intentionally synchronous: `activate` and `poll-routine` both
+return ordinary results, and the guest is expected to suspend by returning
+`routine-poll-result.made-progress = false`. The host then re-enters `poll-routine` after the
+relevant activation lands.
+
+This shape is what stable Wasmtime + `wit-bindgen` support today. When component-model async
+(WASIp3 / Preview 3) lands as stable in Wasmtime, the natural evolution is:
+
+- `activate` and `poll-routine` become `async func`.
+- `routine-poll-result.made-progress` and the explicit `routine-id`-keyed polling protocol
+  likely go away — the host can just `await` each routine directly.
+
+That is a breaking ABI change, so it will require a major-version WIT bump. Any other-language
+SDK that ships a guest implementation should expect to regenerate bindings against the new
+world at that point.

Original file line number	Diff line number	Diff line change
`@@ -277,7 +277,7 @@ pub trait ExecutableAsyncUpdate<U: UpdateDefinition>: WorkflowImplementation {`
`277`	`277`	`}`
`278`	`278`
`279`	`279`	`/// Deserialize handler input from payloads.`
`280`		`-pub fn deserialize_input<I: TemporalDeserializable + 'static>(`
	`280`	`+pub(crate) fn deserialize_input<I: TemporalDeserializable + 'static>(`
`281`	`281`	`payloads: Vec<Payload>,`
`282`	`282`	`converter: &PayloadConverter,`
`283`	`283`	`) -> Result<I, WorkflowError> {`
`@@ -289,7 +289,7 @@ pub fn deserialize_input<I: TemporalDeserializable + 'static>(`
`289`	`289`	`}`
`290`	`290`
`291`	`291`	`/// Serialize handler output to a payload.`
`292`		`-pub fn serialize_output<O: TemporalSerializable + 'static>(`
	`292`	`+pub(crate) fn serialize_output<O: TemporalSerializable + 'static>(`
`293`	`293`	`output: &O,`
`294`	`294`	`converter: &PayloadConverter,`
`295`	`295`	`) -> Result<Payload, WorkflowError> {`
`@@ -301,7 +301,7 @@ pub fn serialize_output<O: TemporalSerializable + 'static>(`
`301`	`301`	`}`
`302`	`302`
`303`	`303`	`/// Wrap a handler error into WorkflowError.`
`304`		`-pub fn wrap_handler_error(e: Box<dyn std::error::Error + Send + Sync>) -> WorkflowError {`
	`304`	`+pub(crate) fn wrap_handler_error(e: Box<dyn std::error::Error + Send + Sync>) -> WorkflowError {`
`305`	`305`	`WorkflowError::Execution(anyhow::anyhow!(e))`
`306`	`306`	`}`
`307`	`307`