@temporalio/core-bridge 1.15.0 → 1.16.1

package/sdk-core/crates/client/src/lib.rs

@@ -7,12 +7,15 @@
 #[macro_use]
 extern crate tracing;
 
+mod async_activity_handle;
 pub mod callback_based;
+pub mod errors;
+pub mod grpc;
 mod metrics;
+mod options_structs;
 /// Visible only for tests
 #[doc(hidden)]
 pub mod proxy;
-mod raw;
 mod replaceable;
 pub mod request_extensions;
 mod retry;
@@ -21,60 +24,68 @@ mod workflow_handle;
 
 pub use crate::{
     proxy::HttpConnectProxyOptions,
-    retry::{CallType, RETRYABLE_ERROR_CODES, RetryClient},
+    retry::{CallType, RETRYABLE_ERROR_CODES},
 };
+pub use async_activity_handle::{
+    ActivityHeartbeatResponse, ActivityIdentifier, AsyncActivityHandle,
+};
+
 pub use metrics::{LONG_REQUEST_LATENCY_HISTOGRAM_NAME, REQUEST_LATENCY_HISTOGRAM_NAME};
-pub use raw::{CloudService, HealthService, OperatorService, TestService, WorkflowService};
+pub use options_structs::*;
 pub use replaceable::SharedReplaceableClient;
+pub use retry::RetryOptions;
 pub use tonic;
 pub use workflow_handle::{
-    GetWorkflowResultOptions, WorkflowExecutionInfo, WorkflowExecutionResult, WorkflowHandle,
+    UntypedQuery, UntypedSignal, UntypedUpdate, UntypedWorkflow, UntypedWorkflowHandle,
+    WorkflowExecutionDescription, WorkflowExecutionInfo, WorkflowExecutionResult, WorkflowHandle,
+    WorkflowHistory, WorkflowUpdateHandle,
 };
 
 use crate::{
+    grpc::{
+        AttachMetricLabels, CloudService, HealthService, OperatorService, TestService,
+        WorkflowService,
+    },
     metrics::{ChannelOrGrpcOverride, GrpcMetricSvc, MetricsContext},
-    raw::AttachMetricLabels,
     request_extensions::RequestExt,
-    sealed::WfHandleClient,
     worker::ClientWorkerSet,
-    workflow_handle::UntypedWorkflowHandle,
 };
-use backoff::{ExponentialBackoff, SystemClock, exponential};
-use http::{Uri, uri::InvalidUri};
+use errors::*;
+use futures_util::{stream, stream::Stream};
+use http::Uri;
 use parking_lot::RwLock;
 use std::{
-    collections::HashMap,
-    fmt::{Debug, Formatter},
-    ops::{Deref, DerefMut},
+    collections::{HashMap, VecDeque},
+    fmt::Debug,
+    pin::Pin,
     str::FromStr,
     sync::{Arc, OnceLock},
-    time::{Duration, Instant},
+    task::{Context, Poll},
+    time::{Duration, SystemTime},
 };
 use temporalio_common::{
+    WorkflowDefinition,
+    data_converters::{DataConverter, SerializationContextData},
     protos::{
-        TaskToken,
         coresdk::IntoPayloadsExt,
         grpc::health::v1::health_client::HealthClient,
+        proto_ts_to_system_time,
         temporal::api::{
             cloud::cloudservice::v1::cloud_service_client::CloudServiceClient,
-            common::{
-                self,
-                v1::{Header, Payload, Payloads, RetryPolicy, WorkflowExecution, WorkflowType},
-            },
-            enums::v1::{
-                ArchivalState, TaskQueueKind, WorkflowIdConflictPolicy, WorkflowIdReusePolicy,
-            },
-            filter::v1::StartTimeFilter,
+            common::v1::{Memo, Payload, SearchAttributes, WorkflowType},
+            enums::v1::{TaskQueueKind, WorkflowExecutionStatus},
+            errordetails::v1::WorkflowExecutionAlreadyStartedFailure,
             operatorservice::v1::operator_service_client::OperatorServiceClient,
-            query::v1::WorkflowQuery,
-            replication::v1::ClusterReplicationConfig,
             taskqueue::v1::TaskQueue,
             testservice::v1::test_service_client::TestServiceClient,
-            update,
-            workflowservice::v1::{workflow_service_client::WorkflowServiceClient, *},
+            workflow::v1 as workflow,
+            workflowservice::v1::{
+                count_workflow_executions_response, workflow_service_client::WorkflowServiceClient,
+                *,
+            },
         },
+        utilities::decode_status_detail,
     },
-    telemetry::metrics::TemporalMeter,
 };
 use tonic::{
     Code, IntoRequest,
@@ -89,308 +100,150 @@ use tonic::{
     transport::{Certificate, Channel, Endpoint, Identity},
 };
 use tower::ServiceBuilder;
-use url::Url;
 use uuid::Uuid;
 
 static CLIENT_NAME_HEADER_KEY: &str = "client-name";
 static CLIENT_VERSION_HEADER_KEY: &str = "client-version";
 static TEMPORAL_NAMESPACE_HEADER_KEY: &str = "temporal-namespace";
 
+#[doc(hidden)]
 /// Key used to communicate when a GRPC message is too large
 pub static MESSAGE_TOO_LARGE_KEY: &str = "message-too-large";
+#[doc(hidden)]
 /// Key used to indicate a error was returned by the retryer because of the short-circuit predicate
 pub static ERROR_RETURNED_DUE_TO_SHORT_CIRCUIT: &str = "short-circuit";
 
 /// The server times out polls after 60 seconds. Set our timeout to be slightly beyond that.
 const LONG_POLL_TIMEOUT: Duration = Duration::from_secs(70);
 const OTHER_CALL_TIMEOUT: Duration = Duration::from_secs(30);
+const VERSION: &str = env!("CARGO_PKG_VERSION");
 
-type Result<T, E = tonic::Status> = std::result::Result<T, E>;
-
-/// Options for the connection to the temporal server. Construct with [ClientOptions::builder]
-#[derive(Clone, Debug, bon::Builder)]
-#[non_exhaustive]
-#[builder(on(String, into), state_mod(vis = "pub"))]
-pub struct ClientOptions {
-    /// The URL of the Temporal server to connect to
-    #[builder(into)]
-    pub target_url: Url,
-
-    /// The name of the SDK being implemented on top of core. Is set as `client-name` header in
-    /// all RPC calls
-    pub client_name: String,
-
-    /// The version of the SDK being implemented on top of core. Is set as `client-version` header
-    /// in all RPC calls. The server decides if the client is supported based on this.
-    pub client_version: String,
-
-    /// A human-readable string that can identify this process. Defaults to empty string.
-    #[builder(default)]
-    pub identity: String,
-
-    /// If specified, use TLS as configured by the [TlsOptions] struct. If this is set core will
-    /// attempt to use TLS when connecting to the Temporal server. Lang SDK is expected to pass any
-    /// certs or keys as bytes, loading them from disk itself if needed.
-    pub tls_options: Option<TlsOptions>,
-
-    /// Retry configuration for the server client. Default is [RetryOptions::default]
-    #[builder(default)]
-    pub retry_options: RetryOptions,
-
-    /// If set, override the origin used when connecting. May be useful in rare situations where tls
-    /// verification needs to use a different name from what should be set as the `:authority`
-    /// header. If [TlsOptions::domain] is set, and this is not, this will be set to
-    /// `https://<domain>`, effectively making the `:authority` header consistent with the domain
-    /// override.
-    pub override_origin: Option<Uri>,
-
-    /// If set, HTTP2 gRPC keep alive will be enabled.
-    /// To enable with default settings, use `.keep_alive(ClientKeepAliveConfig::default())`.
-    #[builder(required, default = Some(ClientKeepAliveOptions::default()))]
-    pub keep_alive: Option<ClientKeepAliveOptions>,
-
-    /// HTTP headers to include on every RPC call.
-    ///
-    /// These must be valid gRPC metadata keys, and must not be binary metadata keys (ending in
-    /// `-bin). To set binary headers, use [ClientOptions::binary_headers]. Invalid header keys or
-    /// values will cause an error to be returned when connecting.
-    pub headers: Option<HashMap<String, String>>,
-
-    /// HTTP headers to include on every RPC call as binary gRPC metadata (encoded as base64).
-    ///
-    /// These must be valid binary gRPC metadata keys (and end with a `-bin` suffix). Invalid
-    /// header keys will cause an error to be returned when connecting.
-    pub binary_headers: Option<HashMap<String, Vec<u8>>>,
-
-    /// API key which is set as the "Authorization" header with "Bearer " prepended. This will only
-    /// be applied if the headers don't already have an "Authorization" header.
-    pub api_key: Option<String>,
-
-    /// HTTP CONNECT proxy to use for this client.
-    pub http_connect_proxy: Option<HttpConnectProxyOptions>,
-
-    /// If set true, error code labels will not be included on request failure metrics.
-    #[builder(default)]
-    pub disable_error_code_metric_tags: bool,
-
-    /// If set true, get_system_info will not be called upon connection
-    #[builder(default)]
-    pub skip_get_system_info: bool,
-}
-
-/// Configuration options for TLS
-#[derive(Clone, Debug, Default)]
-pub struct TlsOptions {
-    /// Bytes representing the root CA certificate used by the server. If not set, and the server's
-    /// cert is issued by someone the operating system trusts, verification will still work (ex:
-    /// Cloud offering).
-    pub server_root_ca_cert: Option<Vec<u8>>,
-    /// Sets the domain name against which to verify the server's TLS certificate. If not provided,
-    /// the domain name will be extracted from the URL used to connect.
-    pub domain: Option<String>,
-    /// TLS info for the client. If specified, core will attempt to use mTLS.
-    pub client_tls_options: Option<ClientTlsOptions>,
-}
-
-/// If using mTLS, both the client cert and private key must be specified, this contains them.
+/// A connection to the Temporal service.
+///
+/// Cloning a connection is cheap (single Arc increment). The underlying connection is shared
+/// between clones.
 #[derive(Clone)]
-pub struct ClientTlsOptions {
-    /// The certificate for this client, encoded as PEM
-    pub client_cert: Vec<u8>,
-    /// The private key for this client, encoded as PEM
-    pub client_private_key: Vec<u8>,
-}
-
-/// Client keep alive configuration.
-#[derive(Clone, Debug)]
-pub struct ClientKeepAliveOptions {
-    /// Interval to send HTTP2 keep alive pings.
-    pub interval: Duration,
-    /// Timeout that the keep alive must be responded to within or the connection will be closed.
-    pub timeout: Duration,
-}
-
-impl Default for ClientKeepAliveOptions {
-    fn default() -> Self {
-        Self {
-            interval: Duration::from_secs(30),
-            timeout: Duration::from_secs(15),
-        }
-    }
-}
-
-/// Configuration for retrying requests to the server
-#[derive(Clone, Debug, PartialEq)]
-pub struct RetryOptions {
-    /// initial wait time before the first retry.
-    pub initial_interval: Duration,
-    /// randomization jitter that is used as a multiplier for the current retry interval
-    /// and is added or subtracted from the interval length.
-    pub randomization_factor: f64,
-    /// rate at which retry time should be increased, until it reaches max_interval.
-    pub multiplier: f64,
-    /// maximum amount of time to wait between retries.
-    pub max_interval: Duration,
-    /// maximum total amount of time requests should be retried for, if None is set then no limit
-    /// will be used.
-    pub max_elapsed_time: Option<Duration>,
-    /// maximum number of retry attempts.
-    pub max_retries: usize,
+pub struct Connection {
+    inner: Arc<ConnectionInner>,
 }
 
-impl Default for RetryOptions {
-    fn default() -> Self {
-        Self {
-            initial_interval: Duration::from_millis(100), // 100 ms wait by default.
-            randomization_factor: 0.2,                    // +-20% jitter.
-            multiplier: 1.7, // each next retry delay will increase by 70%
-            max_interval: Duration::from_secs(5), // until it reaches 5 seconds.
-            max_elapsed_time: Some(Duration::from_secs(10)), // 10 seconds total allocated time for all retries.
-            max_retries: 10,
-        }
-    }
+#[derive(Clone)]
+struct ConnectionInner {
+    service: TemporalServiceClient,
+    retry_options: RetryOptions,
+    identity: String,
+    headers: Arc<RwLock<ClientHeaders>>,
+    client_name: String,
+    client_version: String,
+    /// Capabilities as read from the `get_system_info` RPC call made on client connection
+    capabilities: Option<get_system_info_response::Capabilities>,
+    workers: Arc<ClientWorkerSet>,
 }
 
-impl RetryOptions {
-    pub(crate) const fn task_poll_retry_policy() -> Self {
-        Self {
-            initial_interval: Duration::from_millis(200),
-            randomization_factor: 0.2,
-            multiplier: 2.0,
-            max_interval: Duration::from_secs(10),
-            max_elapsed_time: None,
-            max_retries: 0,
-        }
-    }
-
-    pub(crate) const fn throttle_retry_policy() -> Self {
-        Self {
-            initial_interval: Duration::from_secs(1),
-            randomization_factor: 0.2,
-            multiplier: 2.0,
-            max_interval: Duration::from_secs(10),
-            max_elapsed_time: None,
-            max_retries: 0,
-        }
-    }
-
-    /// A retry policy that never retires
-    pub const fn no_retries() -> Self {
-        Self {
-            initial_interval: Duration::from_secs(0),
-            randomization_factor: 0.0,
-            multiplier: 1.0,
-            max_interval: Duration::from_secs(0),
-            max_elapsed_time: None,
-            max_retries: 1,
-        }
-    }
+impl Connection {
+    /// Connect to a Temporal service.
+    pub async fn connect(options: ConnectionOptions) -> Result<Self, ClientConnectError> {
+        let service = if let Some(service_override) = options.service_override {
+            GrpcMetricSvc {
+                inner: ChannelOrGrpcOverride::GrpcOverride(service_override),
+                metrics: options.metrics_meter.clone().map(MetricsContext::new),
+                disable_errcode_label: options.disable_error_code_metric_tags,
+            }
+        } else {
+            let channel = Channel::from_shared(options.target.to_string())?;
+            let channel = add_tls_to_channel(options.tls_options.as_ref(), channel).await?;
+            let channel = if let Some(keep_alive) = options.keep_alive.as_ref() {
+                channel
+                    .keep_alive_while_idle(true)
+                    .http2_keep_alive_interval(keep_alive.interval)
+                    .keep_alive_timeout(keep_alive.timeout)
+            } else {
+                channel
+            };
+            let channel = if let Some(origin) = options.override_origin.clone() {
+                channel.origin(origin)
+            } else {
+                channel
+            };
+            // If there is a proxy, we have to connect that way
+            let channel = if let Some(proxy) = options.http_connect_proxy.as_ref() {
+                proxy.connect_endpoint(&channel).await?
+            } else {
+                channel.connect().await?
+            };
+            ServiceBuilder::new()
+                .layer_fn(move |channel| GrpcMetricSvc {
+                    inner: ChannelOrGrpcOverride::Channel(channel),
+                    metrics: options.metrics_meter.clone().map(MetricsContext::new),
+                    disable_errcode_label: options.disable_error_code_metric_tags,
+                })
+                .service(channel)
+        };
 
-    pub(crate) fn into_exp_backoff<C>(self, clock: C) -> exponential::ExponentialBackoff<C> {
-        exponential::ExponentialBackoff {
-            current_interval: self.initial_interval,
-            initial_interval: self.initial_interval,
-            randomization_factor: self.randomization_factor,
-            multiplier: self.multiplier,
-            max_interval: self.max_interval,
-            max_elapsed_time: self.max_elapsed_time,
-            clock,
-            start_time: Instant::now(),
-        }
-    }
-}
+        let headers = Arc::new(RwLock::new(ClientHeaders {
+            user_headers: parse_ascii_headers(options.headers.clone().unwrap_or_default())?,
+            user_binary_headers: parse_binary_headers(
+                options.binary_headers.clone().unwrap_or_default(),
+            )?,
+            api_key: options.api_key.clone(),
+        }));
+        let interceptor = ServiceCallInterceptor {
+            client_name: options.client_name.clone(),
+            client_version: options.client_version.clone(),
+            headers: headers.clone(),
+        };
+        let svc = InterceptedService::new(service, interceptor);
+        let mut svc_client = TemporalServiceClient::new(svc);
 
-impl From<RetryOptions> for ExponentialBackoff {
-    fn from(c: RetryOptions) -> Self {
-        c.into_exp_backoff(SystemClock::default())
+        let capabilities = if !options.skip_get_system_info {
+            match svc_client
+                .get_system_info(GetSystemInfoRequest::default().into_request())
+                .await
+            {
+                Ok(sysinfo) => sysinfo.into_inner().capabilities,
+                Err(status) => match status.code() {
+                    Code::Unimplemented => None,
+                    _ => return Err(ClientConnectError::SystemInfoCallError(status)),
+                },
+            }
+        } else {
+            None
+        };
+        Ok(Self {
+            inner: Arc::new(ConnectionInner {
+                service: svc_client,
+                retry_options: options.retry_options,
+                identity: options.identity,
+                headers,
+                client_name: options.client_name,
+                client_version: options.client_version,
+                capabilities,
+                workers: Arc::new(ClientWorkerSet::new()),
+            }),
+        })
     }
-}
 
-impl Debug for ClientTlsOptions {
-    // Intentionally omit details here since they could leak a key if ever printed
-    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
-        write!(f, "ClientTlsOptions(..)")
+    /// Set API key, overwriting any previous one.
+    pub fn set_api_key(&self, api_key: Option<String>) {
+        self.inner.headers.write().api_key = api_key;
     }
-}
-
-/// Errors thrown while attempting to establish a connection to the server
-#[derive(thiserror::Error, Debug)]
-pub enum ClientInitError {
-    /// Invalid URI. Configuration error, fatal.
-    #[error("Invalid URI: {0:?}")]
-    InvalidUri(#[from] InvalidUri),
-    /// Invalid gRPC metadata headers. Configuration error.
-    #[error("Invalid headers: {0}")]
-    InvalidHeaders(#[from] InvalidHeaderError),
-    /// Server connection error. Crashing and restarting the worker is likely best.
-    #[error("Server connection error: {0:?}")]
-    TonicTransportError(#[from] tonic::transport::Error),
-    /// We couldn't successfully make the `get_system_info` call at connection time to establish
-    /// server capabilities / verify server is responding.
-    #[error("`get_system_info` call error after connection: {0:?}")]
-    SystemInfoCallError(tonic::Status),
-}
-
-/// Errors thrown when a gRPC metadata header is invalid.
-#[derive(thiserror::Error, Debug)]
-pub enum InvalidHeaderError {
-    /// A binary header key was invalid
-    #[error("Invalid binary header key '{key}': {source}")]
-    InvalidBinaryHeaderKey {
-        /// The invalid key
-        key: String,
-        /// The source error from tonic
-        source: tonic::metadata::errors::InvalidMetadataKey,
-    },
-    /// An ASCII header key was invalid
-    #[error("Invalid ASCII header key '{key}': {source}")]
-    InvalidAsciiHeaderKey {
-        /// The invalid key
-        key: String,
-        /// The source error from tonic
-        source: tonic::metadata::errors::InvalidMetadataKey,
-    },
-    /// An ASCII header value was invalid
-    #[error("Invalid ASCII header value for key '{key}': {source}")]
-    InvalidAsciiHeaderValue {
-        /// The key
-        key: String,
-        /// The invalid value
-        value: String,
-        /// The source error from tonic
-        source: tonic::metadata::errors::InvalidMetadataValue,
-    },
-}
 
-/// A client with [ClientOptions] attached, which can be passed to initialize workers,
-/// or can be used directly. Is cheap to clone.
-#[derive(Clone, Debug)]
-pub struct ConfiguredClient<C> {
-    client: C,
-    options: Arc<ClientOptions>,
-    headers: Arc<RwLock<ClientHeaders>>,
-    /// Capabilities as read from the `get_system_info` RPC call made on client connection
-    capabilities: Option<get_system_info_response::Capabilities>,
-    workers: Arc<ClientWorkerSet>,
-}
-
-impl<C> ConfiguredClient<C> {
     /// Set HTTP request headers overwriting previous headers.
     ///
-    /// This will not affect headers set via [ClientOptions::binary_headers].
+    /// This will not affect headers set via [ConnectionOptions::binary_headers].
     ///
     /// # Errors
     ///
     /// Will return an error if any of the provided keys or values are not valid gRPC metadata.
     /// If an error is returned, the previous headers will remain unchanged.
     pub fn set_headers(&self, headers: HashMap<String, String>) -> Result<(), InvalidHeaderError> {
-        self.headers.write().user_headers = parse_ascii_headers(headers)?;
+        self.inner.headers.write().user_headers = parse_ascii_headers(headers)?;
         Ok(())
     }
 
     /// Set binary HTTP request headers overwriting previous headers.
     ///
-    /// This will not affect headers set via [ClientOptions::headers].
+    /// This will not affect headers set via [ConnectionOptions::headers].
     ///
     /// # Errors
     ///
@@ -400,34 +253,80 @@ impl<C> ConfiguredClient<C> {
         &self,
         binary_headers: HashMap<String, Vec<u8>>,
     ) -> Result<(), InvalidHeaderError> {
-        self.headers.write().user_binary_headers = parse_binary_headers(binary_headers)?;
+        self.inner.headers.write().user_binary_headers = parse_binary_headers(binary_headers)?;
         Ok(())
     }
 
-    /// Set API key, overwriting previous
-    pub fn set_api_key(&self, api_key: Option<String>) {
-        self.headers.write().api_key = api_key;
+    /// Returns the value used for the `client-name` header by this connection.
+    pub fn client_name(&self) -> &str {
+        &self.inner.client_name
     }
 
-    /// Returns the options the client is configured with
-    pub fn options(&self) -> &ClientOptions {
-        &self.options
+    /// Returns the value used for the `client-version` header by this connection.
+    pub fn client_version(&self) -> &str {
+        &self.inner.client_version
     }
 
     /// Returns the server capabilities we (may have) learned about when establishing an initial
     /// connection
     pub fn capabilities(&self) -> Option<&get_system_info_response::Capabilities> {
-        self.capabilities.as_ref()
+        self.inner.capabilities.as_ref()
+    }
+
+    /// Get a mutable reference to the retry options.
+    ///
+    /// Note: If this connection has been cloned, this will copy-on-write to avoid
+    /// affecting other clones.
+    pub fn retry_options_mut(&mut self) -> &mut RetryOptions {
+        &mut Arc::make_mut(&mut self.inner).retry_options
+    }
+
+    /// Get a reference to the connection identity.
+    pub fn identity(&self) -> &str {
+        &self.inner.identity
+    }
+
+    /// Get a mutable reference to the connection identity.
+    ///
+    /// Note: If this connection has been cloned, this will copy-on-write to avoid
+    /// affecting other clones.
+    pub fn identity_mut(&mut self) -> &mut String {
+        &mut Arc::make_mut(&mut self.inner).identity
     }
 
-    /// Returns a cloned reference to a registry with workers using this client instance
+    /// Returns a reference to a registry with workers using this client instance.
     pub fn workers(&self) -> Arc<ClientWorkerSet> {
-        self.workers.clone()
+        self.inner.workers.clone()
     }
 
-    /// Returns the worker grouping key, this should be unique across each client
+    /// Returns the client-wide key.
     pub fn worker_grouping_key(&self) -> Uuid {
-        self.workers.worker_grouping_key()
+        self.inner.workers.worker_grouping_key()
+    }
+
+    /// Get the underlying workflow service client for making raw gRPC calls.
+    pub fn workflow_service(&self) -> Box<dyn WorkflowService> {
+        self.inner.service.workflow_service()
+    }
+
+    /// Get the underlying operator service client for making raw gRPC calls.
+    pub fn operator_service(&self) -> Box<dyn OperatorService> {
+        self.inner.service.operator_service()
+    }
+
+    /// Get the underlying cloud service client for making raw gRPC calls.
+    pub fn cloud_service(&self) -> Box<dyn CloudService> {
+        self.inner.service.cloud_service()
+    }
+
+    /// Get the underlying test service client for making raw gRPC calls.
+    pub fn test_service(&self) -> Box<dyn TestService> {
+        self.inner.service.test_service()
+    }
+
+    /// Get the underlying health service client for making raw gRPC calls.
+    pub fn health_service(&self) -> Box<dyn HealthService> {
+        self.inner.service.health_service()
     }
 }
 
@@ -463,166 +362,42 @@ impl ClientHeaders {
     }
 }
 
-// The configured client is effectively a "smart" (dumb) pointer
-impl<C> Deref for ConfiguredClient<C> {
-    type Target = C;
-
-    fn deref(&self) -> &Self::Target {
-        &self.client
-    }
-}
-
-impl<C> DerefMut for ConfiguredClient<C> {
-    fn deref_mut(&mut self) -> &mut Self::Target {
-        &mut self.client
-    }
-}
-
-impl ClientOptions {
-    /// Attempt to establish a connection to the Temporal server in a specific namespace. The
-    /// returned client is bound to that namespace.
-    pub async fn connect(
-        &self,
-        namespace: impl Into<String>,
-        metrics_meter: Option<TemporalMeter>,
-    ) -> Result<RetryClient<Client>, ClientInitError> {
-        let client = self.connect_no_namespace(metrics_meter).await?.into_inner();
-        let client = Client::new(client, namespace.into());
-        let retry_client = RetryClient::new(client, self.retry_options.clone());
-        Ok(retry_client)
-    }
-
-    /// Attempt to establish a connection to the Temporal server and return a gRPC client which is
-    /// intercepted with retry, default headers functionality, and metrics if provided.
-    ///
-    /// See [RetryClient] for more
-    pub async fn connect_no_namespace(
-        &self,
-        metrics_meter: Option<TemporalMeter>,
-    ) -> Result<RetryClient<ConfiguredClient<TemporalServiceClient>>, ClientInitError> {
-        self.connect_no_namespace_with_service_override(metrics_meter, None)
-            .await
-    }
-
-    /// Attempt to establish a connection to the Temporal server and return a gRPC client which is
-    /// intercepted with retry, default headers functionality, and metrics if provided. If a
-    /// service_override is present, network-specific options are ignored and the callback is
-    /// invoked for each gRPC call.
-    ///
-    /// See [RetryClient] for more
-    pub async fn connect_no_namespace_with_service_override(
-        &self,
-        metrics_meter: Option<TemporalMeter>,
-        service_override: Option<callback_based::CallbackBasedGrpcService>,
-    ) -> Result<RetryClient<ConfiguredClient<TemporalServiceClient>>, ClientInitError> {
-        let service = if let Some(service_override) = service_override {
-            GrpcMetricSvc {
-                inner: ChannelOrGrpcOverride::GrpcOverride(service_override),
-                metrics: metrics_meter.clone().map(MetricsContext::new),
-                disable_errcode_label: self.disable_error_code_metric_tags,
-            }
+/// If TLS is configured, set the appropriate options on the provided channel and return it.
+/// Passes it through if TLS options not set.
+async fn add_tls_to_channel(
+    tls_options: Option<&TlsOptions>,
+    mut channel: Endpoint,
+) -> Result<Endpoint, ClientConnectError> {
+    if let Some(tls_cfg) = tls_options {
+        let mut tls = tonic::transport::ClientTlsConfig::new();
+
+        if let Some(root_cert) = &tls_cfg.server_root_ca_cert {
+            let server_root_ca_cert = Certificate::from_pem(root_cert);
+            tls = tls.ca_certificate(server_root_ca_cert);
         } else {
-            let channel = Channel::from_shared(self.target_url.to_string())?;
-            let channel = self.add_tls_to_channel(channel).await?;
-            let channel = if let Some(keep_alive) = self.keep_alive.as_ref() {
-                channel
-                    .keep_alive_while_idle(true)
-                    .http2_keep_alive_interval(keep_alive.interval)
-                    .keep_alive_timeout(keep_alive.timeout)
-            } else {
-                channel
-            };
-            let channel = if let Some(origin) = self.override_origin.clone() {
-                channel.origin(origin)
-            } else {
-                channel
-            };
-            // If there is a proxy, we have to connect that way
-            let channel = if let Some(proxy) = self.http_connect_proxy.as_ref() {
-                proxy.connect_endpoint(&channel).await?
-            } else {
-                channel.connect().await?
-            };
-            ServiceBuilder::new()
-                .layer_fn(move |channel| GrpcMetricSvc {
-                    inner: ChannelOrGrpcOverride::Channel(channel),
-                    metrics: metrics_meter.clone().map(MetricsContext::new),
-                    disable_errcode_label: self.disable_error_code_metric_tags,
-                })
-                .service(channel)
-        };
-
-        let headers = Arc::new(RwLock::new(ClientHeaders {
-            user_headers: parse_ascii_headers(self.headers.clone().unwrap_or_default())?,
-            user_binary_headers: parse_binary_headers(
-                self.binary_headers.clone().unwrap_or_default(),
-            )?,
-            api_key: self.api_key.clone(),
-        }));
-        let interceptor = ServiceCallInterceptor {
-            opts: self.clone(),
-            headers: headers.clone(),
-        };
-        let svc = InterceptedService::new(service, interceptor);
-
-        let mut client = ConfiguredClient {
-            headers,
-            client: TemporalServiceClient::new(svc),
-            options: Arc::new(self.clone()),
-            capabilities: None,
-            workers: Arc::new(ClientWorkerSet::new()),
-        };
-        if !self.skip_get_system_info {
-            match client
-                .get_system_info(GetSystemInfoRequest::default().into_request())
-                .await
-            {
-                Ok(sysinfo) => {
-                    client.capabilities = sysinfo.into_inner().capabilities;
-                }
-                Err(status) => match status.code() {
-                    Code::Unimplemented => {}
-                    _ => return Err(ClientInitError::SystemInfoCallError(status)),
-                },
-            };
+            tls = tls.with_native_roots();
         }
-        Ok(RetryClient::new(client, self.retry_options.clone()))
-    }
 
-    /// If TLS is configured, set the appropriate options on the provided channel and return it.
-    /// Passes it through if TLS options not set.
-    async fn add_tls_to_channel(&self, mut channel: Endpoint) -> Result<Endpoint, ClientInitError> {
-        if let Some(tls_cfg) = &self.tls_options {
-            let mut tls = tonic::transport::ClientTlsConfig::new();
+        if let Some(domain) = &tls_cfg.domain {
+            tls = tls.domain_name(domain);
 
-            if let Some(root_cert) = &tls_cfg.server_root_ca_cert {
-                let server_root_ca_cert = Certificate::from_pem(root_cert);
-                tls = tls.ca_certificate(server_root_ca_cert);
-            } else {
-                tls = tls.with_native_roots();
-            }
-
-            if let Some(domain) = &tls_cfg.domain {
-                tls = tls.domain_name(domain);
-
-                // This song and dance ultimately is just to make sure the `:authority` header ends
-                // up correct on requests while we use TLS. Setting the header directly in our
-                // interceptor doesn't work since seemingly it is overridden at some point by
-                // something lower level.
-                let uri: Uri = format!("https://{domain}").parse()?;
-                channel = channel.origin(uri);
-            }
-
-            if let Some(client_opts) = &tls_cfg.client_tls_options {
-                let client_identity =
-                    Identity::from_pem(&client_opts.client_cert, &client_opts.client_private_key);
-                tls = tls.identity(client_identity);
-            }
+            // This song and dance ultimately is just to make sure the `:authority` header ends
+            // up correct on requests while we use TLS. Setting the header directly in our
+            // interceptor doesn't work since seemingly it is overridden at some point by
+            // something lower level.
+            let uri: Uri = format!("https://{domain}").parse()?;
+            channel = channel.origin(uri);
+        }
 
-            return channel.tls_config(tls).map_err(Into::into);
+        if let Some(client_opts) = &tls_cfg.client_tls_options {
+            let client_identity =
+                Identity::from_pem(&client_opts.client_cert, &client_opts.client_private_key);
+            tls = tls.identity(client_identity);
         }
-        Ok(channel)
+
+        return channel.tls_config(tls).map_err(Into::into);
     }
+    Ok(channel)
 }
 
 fn parse_ascii_headers(
@@ -679,7 +454,8 @@ fn parse_binary_headers(
 /// Interceptor which attaches common metadata (like "client-name") to every outgoing call
 #[derive(Clone)]
 pub struct ServiceCallInterceptor {
-    opts: ClientOptions,
+    client_name: String,
+    client_version: String,
     /// Only accessed as a reader
     headers: Arc<RwLock<ClientHeaders>>,
 }
@@ -695,8 +471,7 @@ impl Interceptor for ServiceCallInterceptor {
         if !metadata.contains_key(CLIENT_NAME_HEADER_KEY) {
             metadata.insert(
                 CLIENT_NAME_HEADER_KEY,
-                self.opts
-                    .client_name
+                self.client_name
                     .parse()
                     .unwrap_or_else(|_| MetadataValue::from_static("")),
             );
@@ -704,8 +479,7 @@ impl Interceptor for ServiceCallInterceptor {
         if !metadata.contains_key(CLIENT_VERSION_HEADER_KEY) {
             metadata.insert(
                 CLIENT_VERSION_HEADER_KEY,
-                self.opts
-                    .client_version
+                self.client_version
                     .parse()
                     .unwrap_or_else(|_| MetadataValue::from_static("")),
             );
@@ -794,78 +568,145 @@ impl TemporalServiceClient {
     }
 
     /// Get the underlying workflow service client
-    pub fn workflow_svc(&self) -> Box<dyn WorkflowService> {
+    pub fn workflow_service(&self) -> Box<dyn WorkflowService> {
         self.workflow_svc_client.clone()
     }
     /// Get the underlying operator service client
-    pub fn operator_svc(&self) -> Box<dyn OperatorService> {
+    pub fn operator_service(&self) -> Box<dyn OperatorService> {
         self.operator_svc_client.clone()
     }
     /// Get the underlying cloud service client
-    pub fn cloud_svc(&self) -> Box<dyn CloudService> {
+    pub fn cloud_service(&self) -> Box<dyn CloudService> {
         self.cloud_svc_client.clone()
     }
     /// Get the underlying test service client
-    pub fn test_svc(&self) -> Box<dyn TestService> {
+    pub fn test_service(&self) -> Box<dyn TestService> {
         self.test_svc_client.clone()
     }
     /// Get the underlying health service client
-    pub fn health_svc(&self) -> Box<dyn HealthService> {
+    pub fn health_service(&self) -> Box<dyn HealthService> {
         self.health_svc_client.clone()
     }
 }
 
-/// Contains an instance of a namespace-bound client for interacting with the Temporal server
+/// Contains an instance of a namespace-bound client for interacting with the Temporal server.
+/// Cheap to clone.
 #[derive(Clone)]
 pub struct Client {
-    /// Client for interacting with workflow service
-    inner: ConfiguredClient<TemporalServiceClient>,
-    /// The namespace this client interacts with
-    namespace: String,
+    connection: Connection,
+    options: Arc<ClientOptions>,
 }
 
 impl Client {
-    /// Create a new client from an existing configured lower level client and a namespace
-    pub fn new(client: ConfiguredClient<TemporalServiceClient>, namespace: String) -> Self {
-        Client {
-            inner: client,
-            namespace,
-        }
+    /// Create a new client from a connection and options.
+    ///
+    /// Currently infallible, but returns a `Result` for future extensibility
+    /// (e.g., interceptor or plugin validation).
+    pub fn new(connection: Connection, options: ClientOptions) -> Result<Self, ClientNewError> {
+        Ok(Client {
+            connection,
+            options: Arc::new(options),
+        })
     }
 
     /// Return the options this client was initialized with
     pub fn options(&self) -> &ClientOptions {
-        &self.inner.options
+        &self.options
     }
 
-    /// Return the options this client was initialized with mutably
+    /// Return this client's options mutably.
+    ///
+    /// Note: If this client has been cloned, this will copy-on-write to avoid affecting other
+    /// clones.
     pub fn options_mut(&mut self) -> &mut ClientOptions {
-        Arc::make_mut(&mut self.inner.options)
+        Arc::make_mut(&mut self.options)
     }
 
-    /// Returns a reference to the underlying client
-    pub fn inner(&self) -> &ConfiguredClient<TemporalServiceClient> {
-        &self.inner
+    /// Returns a reference to the underlying connection
+    pub fn connection(&self) -> &Connection {
+        &self.connection
     }
 
-    /// Consumes self and returns the underlying client
-    pub fn into_inner(self) -> ConfiguredClient<TemporalServiceClient> {
-        self.inner
+    /// Returns a mutable reference to the underlying connection
+    pub fn connection_mut(&mut self) -> &mut Connection {
+        &mut self.connection
     }
+}
 
-    /// Returns the client-wide key
-    pub fn worker_grouping_key(&self) -> Uuid {
-        self.inner.worker_grouping_key()
+// High-level workflow operations on Client.
+// These forward to the internal WorkflowClientTrait blanket impl which is
+// available because Client implements WorkflowService + NamespacedClient + Clone.
+impl Client {
+    /// Start a workflow execution.
+    ///
+    /// Returns a [`WorkflowHandle`] that can be used to interact with the workflow
+    /// (e.g., get its result, send signals, query, etc.).
+    pub async fn start_workflow<W>(
+        &self,
+        workflow: W,
+        input: W::Input,
+        options: WorkflowStartOptions,
+    ) -> Result<WorkflowHandle<Self, W>, WorkflowStartError>
+    where
+        W: WorkflowDefinition,
+        W::Input: Send,
+    {
+        WorkflowClientTrait::start_workflow(self, workflow, input, options).await
+    }
+
+    /// Get a handle to an existing workflow.
+    ///
+    /// For untyped access, use `get_workflow_handle::<UntypedWorkflow>(...)`.
+    pub fn get_workflow_handle<W: WorkflowDefinition>(
+        &self,
+        workflow_id: impl Into<String>,
+    ) -> WorkflowHandle<Self, W> {
+        WorkflowClientTrait::get_workflow_handle(self, workflow_id)
+    }
+
+    /// List workflows matching a query.
+    ///
+    /// Returns a stream that lazily paginates through results.
+    /// Use `limit` in options to cap the number of results returned.
+    pub fn list_workflows(
+        &self,
+        query: impl Into<String>,
+        opts: WorkflowListOptions,
+    ) -> ListWorkflowsStream {
+        WorkflowClientTrait::list_workflows(self, query, opts)
+    }
+
+    /// Count workflows matching a query.
+    pub async fn count_workflows(
+        &self,
+        query: impl Into<String>,
+        opts: WorkflowCountOptions,
+    ) -> Result<WorkflowExecutionCount, ClientError> {
+        WorkflowClientTrait::count_workflows(self, query, opts).await
+    }
+
+    /// Get a handle to complete an activity asynchronously.
+    ///
+    /// An activity returning `ActivityError::WillCompleteAsync` can be completed with this handle.
+    pub fn get_async_activity_handle(
+        &self,
+        identifier: ActivityIdentifier,
+    ) -> AsyncActivityHandle<Self> {
+        WorkflowClientTrait::get_async_activity_handle(self, identifier)
     }
 }
 
 impl NamespacedClient for Client {
     fn namespace(&self) -> String {
-        self.namespace.clone()
+        self.options.namespace.clone()
     }
 
     fn identity(&self) -> String {
-        self.inner.options.identity.clone()
+        self.connection.identity().to_owned()
+    }
+
+    fn data_converter(&self) -> &DataConverter {
+        &self.options.data_converter
     }
 }
 
@@ -889,268 +730,60 @@ impl Namespace {
     }
 }
 
-/// Default workflow execution retention for a Namespace is 3 days
-const DEFAULT_WORKFLOW_EXECUTION_RETENTION_PERIOD: Duration = Duration::from_secs(60 * 60 * 24 * 3);
-
-/// Helper struct for `register_namespace`.
-#[derive(Clone, bon::Builder)]
-#[builder(on(String, into))]
-pub struct RegisterNamespaceOptions {
-    /// Name (required)
-    pub namespace: String,
-    /// Description (required)
-    pub description: String,
-    /// Owner's email
-    #[builder(default)]
-    pub owner_email: String,
-    /// Workflow execution retention period
-    #[builder(default = DEFAULT_WORKFLOW_EXECUTION_RETENTION_PERIOD)]
-    pub workflow_execution_retention_period: Duration,
-    /// Cluster settings
-    #[builder(default)]
-    pub clusters: Vec<ClusterReplicationConfig>,
-    /// Active cluster name
-    #[builder(default)]
-    pub active_cluster_name: String,
-    /// Custom Data
-    #[builder(default)]
-    pub data: HashMap<String, String>,
-    /// Security Token
-    #[builder(default)]
-    pub security_token: String,
-    /// Global namespace
-    #[builder(default)]
-    pub is_global_namespace: bool,
-    /// History Archival setting
-    #[builder(default = ArchivalState::Unspecified)]
-    pub history_archival_state: ArchivalState,
-    /// History Archival uri
-    #[builder(default)]
-    pub history_archival_uri: String,
-    /// Visibility Archival setting
-    #[builder(default = ArchivalState::Unspecified)]
-    pub visibility_archival_state: ArchivalState,
-    /// Visibility Archival uri
-    #[builder(default)]
-    pub visibility_archival_uri: String,
-}
-
-impl From<RegisterNamespaceOptions> for RegisterNamespaceRequest {
-    fn from(val: RegisterNamespaceOptions) -> Self {
-        RegisterNamespaceRequest {
-            namespace: val.namespace,
-            description: val.description,
-            owner_email: val.owner_email,
-            workflow_execution_retention_period: val
-                .workflow_execution_retention_period
-                .try_into()
-                .ok(),
-            clusters: val.clusters,
-            active_cluster_name: val.active_cluster_name,
-            data: val.data,
-            security_token: val.security_token,
-            is_global_namespace: val.is_global_namespace,
-            history_archival_state: val.history_archival_state as i32,
-            history_archival_uri: val.history_archival_uri,
-            visibility_archival_state: val.visibility_archival_state as i32,
-            visibility_archival_uri: val.visibility_archival_uri,
-        }
-    }
-}
-
-// Note: The cluster_names custom setter from derive_builder is not supported in bon.
-// Users should manually construct the clusters vector if needed.
-
-/// Helper struct for `signal_with_start_workflow_execution`.
-#[derive(Clone, bon::Builder)]
-#[builder(on(String, into))]
-pub struct SignalWithStartOptions {
-    /// Input payload for the workflow run
-    pub input: Option<Payloads>,
-    /// Task Queue to target (required)
-    pub task_queue: String,
-    /// Workflow id for the workflow run
-    pub workflow_id: String,
-    /// Workflow type for the workflow run
-    pub workflow_type: String,
-    /// Request id for idempotency/deduplication
-    pub request_id: Option<String>,
-    /// The signal name to send (required)
-    pub signal_name: String,
-    /// Payloads for the signal
-    pub signal_input: Option<Payloads>,
-    /// Headers for the signal
-    pub signal_header: Option<Header>,
-}
-
 /// This trait provides higher-level friendlier interaction with the server.
 /// See the [WorkflowService] trait for a lower-level client.
-#[async_trait::async_trait]
-pub trait WorkflowClientTrait: NamespacedClient {
-    /// Starts workflow execution.
-    async fn start_workflow(
-        &self,
-        input: Vec<Payload>,
-        task_queue: String,
-        workflow_id: String,
-        workflow_type: String,
-        request_id: Option<String>,
-        options: WorkflowOptions,
-    ) -> Result<StartWorkflowExecutionResponse>;
-
-    /// Notifies the server that workflow tasks for a given workflow should be sent to the normal
-    /// non-sticky task queue. This normally happens when workflow has been evicted from the cache.
-    async fn reset_sticky_task_queue(
+pub(crate) trait WorkflowClientTrait: NamespacedClient {
+    /// Start a workflow execution.
+    fn start_workflow<W>(
         &self,
-        workflow_id: String,
-        run_id: String,
-    ) -> Result<ResetStickyTaskQueueResponse>;
-
-    /// Complete activity task by sending response to the server. `task_token` contains activity
-    /// identifier that would've been received from polling for an activity task. `result` is a blob
-    /// that contains activity response.
-    async fn complete_activity_task(
-        &self,
-        task_token: TaskToken,
-        result: Option<Payloads>,
-    ) -> Result<RespondActivityTaskCompletedResponse>;
-
-    /// Report activity task heartbeat by sending details to the server. `task_token` contains
-    /// activity identifier that would've been received from polling for an activity task. `result`
-    /// contains `cancel_requested` flag, which if set to true indicates that activity has been
-    /// cancelled.
-    async fn record_activity_heartbeat(
-        &self,
-        task_token: TaskToken,
-        details: Option<Payloads>,
-    ) -> Result<RecordActivityTaskHeartbeatResponse>;
-
-    /// Cancel activity task by sending response to the server. `task_token` contains activity
-    /// identifier that would've been received from polling for an activity task. `details` is a
-    /// blob that provides arbitrary user defined cancellation info.
-    async fn cancel_activity_task(
-        &self,
-        task_token: TaskToken,
-        details: Option<Payloads>,
-    ) -> Result<RespondActivityTaskCanceledResponse>;
-
-    /// Send a signal to a certain workflow instance
-    async fn signal_workflow_execution(
-        &self,
-        workflow_id: String,
-        run_id: String,
-        signal_name: String,
-        payloads: Option<Payloads>,
-        request_id: Option<String>,
-    ) -> Result<SignalWorkflowExecutionResponse>;
-
-    /// Send signal and start workflow transcationally
-    //#TODO maybe lift the Signal type from sdk::workflow_context::options
-    #[allow(clippy::too_many_arguments)]
-    async fn signal_with_start_workflow_execution(
-        &self,
-        options: SignalWithStartOptions,
-        workflow_options: WorkflowOptions,
-    ) -> Result<SignalWithStartWorkflowExecutionResponse>;
+        workflow: W,
+        input: W::Input,
+        options: WorkflowStartOptions,
+    ) -> impl Future<Output = Result<WorkflowHandle<Self, W>, WorkflowStartError>>
+    where
+        Self: Sized,
+        W: WorkflowDefinition,
+        W::Input: Send;
 
-    /// Request a query of a certain workflow instance
-    async fn query_workflow_execution(
+    /// Get a handle to an existing workflow. `run_id` may be left blank to specify the most recent
+    /// execution having the provided `workflow_id`.
+    ///
+    /// For untyped access, use `get_workflow_handle::<UntypedWorkflow>(...)`.
+    ///
+    /// See also [WorkflowHandle::new], for specifying namespace or first_execution_run_id.
+    fn get_workflow_handle<W: WorkflowDefinition>(
         &self,
-        workflow_id: String,
-        run_id: String,
-        query: WorkflowQuery,
-    ) -> Result<QueryWorkflowResponse>;
+        workflow_id: impl Into<String>,
+    ) -> WorkflowHandle<Self, W>
+    where
+        Self: Sized;
 
-    /// Get information about a workflow run
-    async fn describe_workflow_execution(
+    /// List workflows matching a query.
+    /// Returns a stream that lazily paginates through results.
+    /// Use `limit` in options to cap the number of results returned.
+    fn list_workflows(
         &self,
-        workflow_id: String,
-        run_id: Option<String>,
-    ) -> Result<DescribeWorkflowExecutionResponse>;
+        query: impl Into<String>,
+        opts: WorkflowListOptions,
+    ) -> ListWorkflowsStream;
 
-    /// Get history for a particular workflow run
-    async fn get_workflow_execution_history(
+    /// Count workflows matching a query.
+    fn count_workflows(
         &self,
-        workflow_id: String,
-        run_id: Option<String>,
-        page_token: Vec<u8>,
-    ) -> Result<GetWorkflowExecutionHistoryResponse>;
+        query: impl Into<String>,
+        opts: WorkflowCountOptions,
+    ) -> impl Future<Output = Result<WorkflowExecutionCount, ClientError>>;
 
-    /// Cancel a currently executing workflow
-    async fn cancel_workflow_execution(
-        &self,
-        workflow_id: String,
-        run_id: Option<String>,
-        reason: String,
-        request_id: Option<String>,
-    ) -> Result<RequestCancelWorkflowExecutionResponse>;
-
-    /// Terminate a currently executing workflow
-    async fn terminate_workflow_execution(
+    /// Get a handle to complete an activity asynchronously.
+    ///
+    /// An activity returning `ActivityError::WillCompleteAsync` can be completed with this handle.
+    fn get_async_activity_handle(
         &self,
-        workflow_id: String,
-        run_id: Option<String>,
-    ) -> Result<TerminateWorkflowExecutionResponse>;
-
-    /// Register a new namespace
-    async fn register_namespace(
-        &self,
-        options: RegisterNamespaceOptions,
-    ) -> Result<RegisterNamespaceResponse>;
-
-    /// Lists all available namespaces
-    async fn list_namespaces(&self) -> Result<ListNamespacesResponse>;
-
-    /// Query namespace details
-    async fn describe_namespace(&self, namespace: Namespace) -> Result<DescribeNamespaceResponse>;
-
-    /// List open workflow executions with Standard Visibility filtering
-    async fn list_open_workflow_executions(
-        &self,
-        max_page_size: i32,
-        next_page_token: Vec<u8>,
-        start_time_filter: Option<StartTimeFilter>,
-        filters: Option<list_open_workflow_executions_request::Filters>,
-    ) -> Result<ListOpenWorkflowExecutionsResponse>;
-
-    /// List closed workflow executions Standard Visibility filtering
-    async fn list_closed_workflow_executions(
-        &self,
-        max_page_size: i32,
-        next_page_token: Vec<u8>,
-        start_time_filter: Option<StartTimeFilter>,
-        filters: Option<list_closed_workflow_executions_request::Filters>,
-    ) -> Result<ListClosedWorkflowExecutionsResponse>;
-
-    /// List workflow executions with Advanced Visibility filtering
-    async fn list_workflow_executions(
-        &self,
-        page_size: i32,
-        next_page_token: Vec<u8>,
-        query: String,
-    ) -> Result<ListWorkflowExecutionsResponse>;
-
-    /// List archived workflow executions
-    async fn list_archived_workflow_executions(
-        &self,
-        page_size: i32,
-        next_page_token: Vec<u8>,
-        query: String,
-    ) -> Result<ListArchivedWorkflowExecutionsResponse>;
-
-    /// Get Cluster Search Attributes
-    async fn get_search_attributes(&self) -> Result<GetSearchAttributesResponse>;
-
-    /// Send an Update to a workflow execution
-    async fn update_workflow_execution(
-        &self,
-        workflow_id: String,
-        run_id: String,
-        name: String,
-        wait_policy: update::v1::WaitPolicy,
-        args: Option<Payloads>,
-    ) -> Result<UpdateWorkflowExecutionResponse>;
-}
+        identifier: ActivityIdentifier,
+    ) -> AsyncActivityHandle<Self>
+    where
+        Self: Sized;
+}
 
 /// A client that is bound to a namespace
 pub trait NamespacedClient {
@@ -1158,172 +791,260 @@ pub trait NamespacedClient {
     fn namespace(&self) -> String;
     /// Returns the client identity
     fn identity(&self) -> String;
+    /// Returns the data converter for serializing/deserializing payloads.
+    /// Default implementation returns a static default converter.
+    fn data_converter(&self) -> &DataConverter {
+        static DEFAULT: OnceLock<DataConverter> = OnceLock::new();
+        DEFAULT.get_or_init(DataConverter::default)
+    }
 }
 
-/// Optional fields supplied at the start of workflow execution
-#[derive(Debug, Clone, Default)]
-pub struct WorkflowOptions {
-    /// Set the policy for reusing the workflow id
-    pub id_reuse_policy: WorkflowIdReusePolicy,
+/// A workflow execution returned from list operations.
+/// This represents information about a workflow present in visibility.
+#[derive(Debug, Clone)]
+pub struct WorkflowExecution {
+    raw: workflow::WorkflowExecutionInfo,
+}
+
+impl WorkflowExecution {
+    /// Create a new WorkflowExecution from the raw proto.
+    pub fn new(raw: workflow::WorkflowExecutionInfo) -> Self {
+        Self { raw }
+    }
+
+    /// The workflow ID.
+    pub fn id(&self) -> &str {
+        self.raw
+            .execution
+            .as_ref()
+            .map(|e| e.workflow_id.as_str())
+            .unwrap_or("")
+    }
+
+    /// The run ID.
+    pub fn run_id(&self) -> &str {
+        self.raw
+            .execution
+            .as_ref()
+            .map(|e| e.run_id.as_str())
+            .unwrap_or("")
+    }
+
+    /// The workflow type name.
+    pub fn workflow_type(&self) -> &str {
+        self.raw
+            .r#type
+            .as_ref()
+            .map(|t| t.name.as_str())
+            .unwrap_or("")
+    }
+
+    /// The current status of the workflow execution.
+    pub fn status(&self) -> WorkflowExecutionStatus {
+        self.raw.status()
+    }
+
+    /// When the workflow was created.
+    pub fn start_time(&self) -> Option<SystemTime> {
+        self.raw
+            .start_time
+            .as_ref()
+            .and_then(proto_ts_to_system_time)
+    }
+
+    /// When the workflow run started or should start.
+    pub fn execution_time(&self) -> Option<SystemTime> {
+        self.raw
+            .execution_time
+            .as_ref()
+            .and_then(proto_ts_to_system_time)
+    }
+
+    /// When the workflow was closed, if closed.
+    pub fn close_time(&self) -> Option<SystemTime> {
+        self.raw
+            .close_time
+            .as_ref()
+            .and_then(proto_ts_to_system_time)
+    }
+
+    /// The task queue the workflow runs on.
+    pub fn task_queue(&self) -> &str {
+        &self.raw.task_queue
+    }
+
+    /// Number of events in history.
+    pub fn history_length(&self) -> i64 {
+        self.raw.history_length
+    }
 
-    /// Set the policy for how to resolve conflicts with running policies.
-    /// NOTE: This is ignored for child workflows.
-    pub id_conflict_policy: WorkflowIdConflictPolicy,
+    /// Workflow memo.
+    pub fn memo(&self) -> Option<&Memo> {
+        self.raw.memo.as_ref()
+    }
 
-    /// Optionally set the execution timeout for the workflow
-    /// <https://docs.temporal.io/workflows/#workflow-execution-timeout>
-    pub execution_timeout: Option<Duration>,
+    /// Parent workflow ID, if this is a child workflow.
+    pub fn parent_id(&self) -> Option<&str> {
+        self.raw
+            .parent_execution
+            .as_ref()
+            .map(|e| e.workflow_id.as_str())
+    }
 
-    /// Optionally indicates the default run timeout for a workflow run
-    pub run_timeout: Option<Duration>,
+    /// Parent run ID, if this is a child workflow.
+    pub fn parent_run_id(&self) -> Option<&str> {
+        self.raw
+            .parent_execution
+            .as_ref()
+            .map(|e| e.run_id.as_str())
+    }
 
-    /// Optionally indicates the default task timeout for a workflow run
-    pub task_timeout: Option<Duration>,
+    /// Search attributes on the workflow.
+    pub fn search_attributes(&self) -> Option<&SearchAttributes> {
+        self.raw.search_attributes.as_ref()
+    }
 
-    /// Optionally set a cron schedule for the workflow
-    pub cron_schedule: Option<String>,
+    /// Access the raw proto for additional fields not exposed via accessors.
+    pub fn raw(&self) -> &workflow::WorkflowExecutionInfo {
+        &self.raw
+    }
 
-    /// Optionally associate extra search attributes with a workflow
-    pub search_attributes: Option<HashMap<String, Payload>>,
+    /// Consume the wrapper and return the raw proto.
+    pub fn into_raw(self) -> workflow::WorkflowExecutionInfo {
+        self.raw
+    }
+}
 
-    /// Optionally enable Eager Workflow Start, a latency optimization using local workers
-    /// NOTE: Experimental
-    pub enable_eager_workflow_start: bool,
+impl From<workflow::WorkflowExecutionInfo> for WorkflowExecution {
+    fn from(raw: workflow::WorkflowExecutionInfo) -> Self {
+        Self::new(raw)
+    }
+}
 
-    /// Optionally set a retry policy for the workflow
-    pub retry_policy: Option<RetryPolicy>,
+/// A stream of workflow executions from a list query.
+/// Internally paginates through results from the server.
+pub struct ListWorkflowsStream {
+    inner: Pin<Box<dyn Stream<Item = Result<WorkflowExecution, ClientError>> + Send>>,
+}
 
-    /// Links to associate with the workflow. Ex: References to a nexus operation.
-    pub links: Vec<common::v1::Link>,
+impl ListWorkflowsStream {
+    fn new(
+        inner: Pin<Box<dyn Stream<Item = Result<WorkflowExecution, ClientError>> + Send>>,
+    ) -> Self {
+        Self { inner }
+    }
+}
 
-    /// Callbacks that will be invoked upon workflow completion. For, ex, completing nexus
-    /// operations.
-    pub completion_callbacks: Vec<common::v1::Callback>,
+impl Stream for ListWorkflowsStream {
+    type Item = Result<WorkflowExecution, ClientError>;
 
-    /// Priority for the workflow
-    pub priority: Option<Priority>,
+    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
+        self.inner.as_mut().poll_next(cx)
+    }
 }
 
-/// Priority contains metadata that controls relative ordering of task processing
-/// when tasks are backlogged in a queue. Initially, Priority will be used in
-/// activity and workflow task queues, which are typically where backlogs exist.
-/// Other queues in the server (such as transfer and timer queues) and rate
-/// limiting decisions do not use Priority, but may in the future.
+/// Result of a workflow count operation.
 ///
-/// Priority is attached to workflows and activities. Activities and child
-/// workflows inherit Priority from the workflow that created them, but may
-/// override fields when they are started or modified. For each field of a
-/// Priority on an activity/workflow, not present or equal to zero/empty string
-/// means to inherit the value from the calling workflow, or if there is no
-/// calling workflow, then use the default (documented below).
-///
-/// Despite being named "Priority", this message will also contains fields that
-/// control "fairness" mechanisms.
-///
-/// The overall semantics of Priority are:
-/// (more will be added here later)
-/// 1. First, consider "priority_key": lower number goes first.
-#[derive(Debug, Clone, Default, PartialEq)]
-pub struct Priority {
-    /// Priority key is a positive integer from 1 to n, where smaller integers
-    /// correspond to higher priorities (tasks run sooner). In general, tasks in
-    /// a queue should be processed in close to priority order, although small
-    /// deviations are possible.
-    ///
-    /// The maximum priority value (minimum priority) is determined by server
-    /// configuration, and defaults to 5.
-    ///
-    /// The default priority is (min+max)/2. With the default max of 5 and min of
-    /// 1, that comes out to 3.
-    pub priority_key: u32,
-
-    /// Fairness key is a short string that's used as a key for a fairness
-    /// balancing mechanism. It may correspond to a tenant id, or to a fixed
-    /// string like "high" or "low". The default is the empty string.
-    ///
-    /// The fairness mechanism attempts to dispatch tasks for a given key in
-    /// proportion to its weight. For example, using a thousand distinct tenant
-    /// ids, each with a weight of 1.0 (the default) will result in each tenant
-    /// getting a roughly equal share of task dispatch throughput.
-    ///
-    /// (Note: this does not imply equal share of worker capacity! Fairness
-    /// decisions are made based on queue statistics, not
-    /// current worker load.)
-    ///
-    /// As another example, using keys "high" and "low" with weight 9.0 and 1.0
-    /// respectively will prefer dispatching "high" tasks over "low" tasks at a
-    /// 9:1 ratio, while allowing either key to use all worker capacity if the
-    /// other is not present.
-    ///
-    /// All fairness mechanisms, including rate limits, are best-effort and
-    /// probabilistic. The results may not match what a "perfect" algorithm with
-    /// infinite resources would produce. The more unique keys are used, the less
-    /// accurate the results will be.
-    ///
-    /// Fairness keys are limited to 64 bytes.
-    pub fairness_key: String,
-
-    /// Fairness weight for a task can come from multiple sources for
-    /// flexibility. From highest to lowest precedence:
-    /// 1. Weights for a small set of keys can be overridden in task queue
-    ///    configuration with an API.
-    /// 2. It can be attached to the workflow/activity in this field.
-    /// 3. The default weight of 1.0 will be used.
-    ///
-    /// Weight values are clamped by the server to the range [0.001, 1000].
-    pub fairness_weight: f32,
+/// If the query includes a group-by clause, `groups` will contain the aggregated
+/// counts and `count` will be the sum of all group counts.
+#[derive(Debug, Clone)]
+pub struct WorkflowExecutionCount {
+    count: usize,
+    groups: Vec<WorkflowCountAggregationGroup>,
 }
 
-impl From<Priority> for common::v1::Priority {
-    fn from(priority: Priority) -> Self {
-        common::v1::Priority {
-            priority_key: priority.priority_key as i32,
-            fairness_key: priority.fairness_key,
-            fairness_weight: priority.fairness_weight,
+impl WorkflowExecutionCount {
+    pub(crate) fn from_response(resp: CountWorkflowExecutionsResponse) -> Self {
+        Self {
+            count: resp.count as usize,
+            groups: resp
+                .groups
+                .into_iter()
+                .map(WorkflowCountAggregationGroup::from_proto)
+                .collect(),
         }
     }
+
+    /// The approximate number of workflows matching the query.
+    /// If grouping was applied, this is the sum of all group counts.
+    pub fn count(&self) -> usize {
+        self.count
+    }
+
+    /// The groups if the query had a group-by clause, or empty if not.
+    pub fn groups(&self) -> &[WorkflowCountAggregationGroup] {
+        &self.groups
+    }
+}
+
+/// Aggregation group from a workflow count query with a group-by clause.
+#[derive(Debug, Clone)]
+pub struct WorkflowCountAggregationGroup {
+    group_values: Vec<Payload>,
+    count: usize,
 }
 
-impl From<common::v1::Priority> for Priority {
-    fn from(priority: common::v1::Priority) -> Self {
+impl WorkflowCountAggregationGroup {
+    fn from_proto(proto: count_workflow_executions_response::AggregationGroup) -> Self {
         Self {
-            priority_key: priority.priority_key as u32,
-            fairness_key: priority.fairness_key,
-            fairness_weight: priority.fairness_weight,
+            group_values: proto.group_values,
+            count: proto.count as usize,
         }
     }
+
+    /// The search attribute values for this group.
+    pub fn group_values(&self) -> &[Payload] {
+        &self.group_values
+    }
+
+    /// The approximate number of workflows matching for this group.
+    pub fn count(&self) -> usize {
+        self.count
+    }
 }
 
-#[async_trait::async_trait]
 impl<T> WorkflowClientTrait for T
 where
     T: WorkflowService + NamespacedClient + Clone + Send + Sync + 'static,
 {
-    async fn start_workflow(
+    async fn start_workflow<W>(
         &self,
-        input: Vec<Payload>,
-        task_queue: String,
-        workflow_id: String,
-        workflow_type: String,
-        request_id: Option<String>,
-        options: WorkflowOptions,
-    ) -> Result<StartWorkflowExecutionResponse> {
-        Ok(self
-            .clone()
-            .start_workflow_execution(
-                StartWorkflowExecutionRequest {
-                    namespace: self.namespace(),
-                    input: input.into_payloads(),
-                    workflow_id,
+        workflow: W,
+        input: W::Input,
+        options: WorkflowStartOptions,
+    ) -> Result<WorkflowHandle<Self, W>, WorkflowStartError>
+    where
+        W: WorkflowDefinition,
+        W::Input: Send,
+    {
+        let payloads = self
+            .data_converter()
+            .to_payloads(&SerializationContextData::Workflow, &input)
+            .await?;
+        let namespace = self.namespace();
+        let workflow_id = options.workflow_id.clone();
+        let task_queue_name = options.task_queue.clone();
+
+        let run_id = if let Some(start_signal) = options.start_signal {
+            // Use signal-with-start when a start_signal is provided
+            let res = WorkflowService::signal_with_start_workflow_execution(
+                &mut self.clone(),
+                SignalWithStartWorkflowExecutionRequest {
+                    namespace: namespace.clone(),
+                    workflow_id: workflow_id.clone(),
                     workflow_type: Some(WorkflowType {
-                        name: workflow_type,
+                        name: workflow.name().to_string(),
                     }),
                     task_queue: Some(TaskQueue {
-                        name: task_queue,
-                        kind: TaskQueueKind::Unspecified as i32,
+                        name: task_queue_name,
+                        kind: TaskQueueKind::Normal as i32,
                         normal_name: "".to_string(),
                     }),
-                    request_id: request_id.unwrap_or_else(|| Uuid::new_v4().to_string()),
+                    input: payloads.into_payloads(),
+                    signal_name: start_signal.signal_name,
+                    signal_input: start_signal.input,
+                    identity: self.identity(),
+                    request_id: Uuid::new_v4().to_string(),
                     workflow_id_reuse_policy: options.id_reuse_policy as i32,
                     workflow_id_conflict_policy: options.id_conflict_policy as i32,
                     workflow_execution_timeout: options
@@ -1333,482 +1054,203 @@ where
                     workflow_task_timeout: options.task_timeout.and_then(|d| d.try_into().ok()),
                     search_attributes: options.search_attributes.map(|d| d.into()),
                     cron_schedule: options.cron_schedule.unwrap_or_default(),
-                    request_eager_execution: options.enable_eager_workflow_start,
-                    retry_policy: options.retry_policy,
-                    links: options.links,
-                    completion_callbacks: options.completion_callbacks,
-                    priority: options.priority.map(Into::into),
+                    header: options.header.or(start_signal.header),
                     ..Default::default()
                 }
                 .into_request(),
             )
             .await?
-            .into_inner())
-    }
-
-    async fn reset_sticky_task_queue(
-        &self,
-        workflow_id: String,
-        run_id: String,
-    ) -> Result<ResetStickyTaskQueueResponse> {
-        let request = ResetStickyTaskQueueRequest {
-            namespace: self.namespace(),
-            execution: Some(WorkflowExecution {
-                workflow_id,
-                run_id,
-            }),
+            .into_inner();
+            res.run_id
+        } else {
+            // Normal start workflow
+            let res = self
+                .clone()
+                .start_workflow_execution(
+                    StartWorkflowExecutionRequest {
+                        namespace: namespace.clone(),
+                        input: payloads.into_payloads(),
+                        workflow_id: workflow_id.clone(),
+                        workflow_type: Some(WorkflowType {
+                            name: workflow.name().to_string(),
+                        }),
+                        task_queue: Some(TaskQueue {
+                            name: task_queue_name,
+                            kind: TaskQueueKind::Unspecified as i32,
+                            normal_name: "".to_string(),
+                        }),
+                        request_id: Uuid::new_v4().to_string(),
+                        workflow_id_reuse_policy: options.id_reuse_policy as i32,
+                        workflow_id_conflict_policy: options.id_conflict_policy as i32,
+                        workflow_execution_timeout: options
+                            .execution_timeout
+                            .and_then(|d| d.try_into().ok()),
+                        workflow_run_timeout: options.run_timeout.and_then(|d| d.try_into().ok()),
+                        workflow_task_timeout: options.task_timeout.and_then(|d| d.try_into().ok()),
+                        search_attributes: options.search_attributes.map(|d| d.into()),
+                        cron_schedule: options.cron_schedule.unwrap_or_default(),
+                        request_eager_execution: options.enable_eager_workflow_start,
+                        retry_policy: options.retry_policy,
+                        links: options.links,
+                        completion_callbacks: options.completion_callbacks,
+                        priority: Some(options.priority.into()),
+                        header: options.header,
+                        ..Default::default()
+                    }
+                    .into_request(),
+                )
+                .await
+                .map_err(|status| {
+                    if status.code() == Code::AlreadyExists {
+                        let run_id =
+                            decode_status_detail::<WorkflowExecutionAlreadyStartedFailure>(
+                                status.details(),
+                            )
+                            .map(|f| f.run_id);
+                        WorkflowStartError::AlreadyStarted {
+                            run_id,
+                            source: status,
+                        }
+                    } else {
+                        WorkflowStartError::Rpc(status)
+                    }
+                })?
+                .into_inner();
+            res.run_id
         };
-        Ok(
-            WorkflowService::reset_sticky_task_queue(&mut self.clone(), request.into_request())
-                .await?
-                .into_inner(),
-        )
-    }
-
-    async fn complete_activity_task(
-        &self,
-        task_token: TaskToken,
-        result: Option<Payloads>,
-    ) -> Result<RespondActivityTaskCompletedResponse> {
-        Ok(self
-            .clone()
-            .respond_activity_task_completed(
-                RespondActivityTaskCompletedRequest {
-                    task_token: task_token.0,
-                    result,
-                    identity: self.identity(),
-                    namespace: self.namespace(),
-                    ..Default::default()
-                }
-                .into_request(),
-            )
-            .await?
-            .into_inner())
-    }
-
-    async fn record_activity_heartbeat(
-        &self,
-        task_token: TaskToken,
-        details: Option<Payloads>,
-    ) -> Result<RecordActivityTaskHeartbeatResponse> {
-        Ok(self
-            .clone()
-            .record_activity_task_heartbeat(
-                RecordActivityTaskHeartbeatRequest {
-                    task_token: task_token.0,
-                    details,
-                    identity: self.identity(),
-                    namespace: self.namespace(),
-                }
-                .into_request(),
-            )
-            .await?
-            .into_inner())
-    }
-
-    async fn cancel_activity_task(
-        &self,
-        task_token: TaskToken,
-        details: Option<Payloads>,
-    ) -> Result<RespondActivityTaskCanceledResponse> {
-        Ok(self
-            .clone()
-            .respond_activity_task_canceled(
-                RespondActivityTaskCanceledRequest {
-                    task_token: task_token.0,
-                    details,
-                    identity: self.identity(),
-                    namespace: self.namespace(),
-                    ..Default::default()
-                }
-                .into_request(),
-            )
-            .await?
-            .into_inner())
-    }
-
-    async fn signal_workflow_execution(
-        &self,
-        workflow_id: String,
-        run_id: String,
-        signal_name: String,
-        payloads: Option<Payloads>,
-        request_id: Option<String>,
-    ) -> Result<SignalWorkflowExecutionResponse> {
-        Ok(WorkflowService::signal_workflow_execution(
-            &mut self.clone(),
-            SignalWorkflowExecutionRequest {
-                namespace: self.namespace(),
-                workflow_execution: Some(WorkflowExecution {
-                    workflow_id,
-                    run_id,
-                }),
-                signal_name,
-                input: payloads,
-                identity: self.identity(),
-                request_id: request_id.unwrap_or_else(|| Uuid::new_v4().to_string()),
-                ..Default::default()
-            }
-            .into_request(),
-        )
-        .await?
-        .into_inner())
-    }
 
-    async fn signal_with_start_workflow_execution(
-        &self,
-        options: SignalWithStartOptions,
-        workflow_options: WorkflowOptions,
-    ) -> Result<SignalWithStartWorkflowExecutionResponse> {
-        Ok(WorkflowService::signal_with_start_workflow_execution(
-            &mut self.clone(),
-            SignalWithStartWorkflowExecutionRequest {
-                namespace: self.namespace(),
-                workflow_id: options.workflow_id,
-                workflow_type: Some(WorkflowType {
-                    name: options.workflow_type,
-                }),
-                task_queue: Some(TaskQueue {
-                    name: options.task_queue,
-                    kind: TaskQueueKind::Normal as i32,
-                    normal_name: "".to_string(),
-                }),
-                input: options.input,
-                signal_name: options.signal_name,
-                signal_input: options.signal_input,
-                identity: self.identity(),
-                request_id: options
-                    .request_id
-                    .unwrap_or_else(|| Uuid::new_v4().to_string()),
-                workflow_id_reuse_policy: workflow_options.id_reuse_policy as i32,
-                workflow_id_conflict_policy: workflow_options.id_conflict_policy as i32,
-                workflow_execution_timeout: workflow_options
-                    .execution_timeout
-                    .and_then(|d| d.try_into().ok()),
-                workflow_run_timeout: workflow_options.run_timeout.and_then(|d| d.try_into().ok()),
-                workflow_task_timeout: workflow_options
-                    .task_timeout
-                    .and_then(|d| d.try_into().ok()),
-                search_attributes: workflow_options.search_attributes.map(|d| d.into()),
-                cron_schedule: workflow_options.cron_schedule.unwrap_or_default(),
-                header: options.signal_header,
-                ..Default::default()
-            }
-            .into_request(),
-        )
-        .await?
-        .into_inner())
-    }
-
-    async fn query_workflow_execution(
-        &self,
-        workflow_id: String,
-        run_id: String,
-        query: WorkflowQuery,
-    ) -> Result<QueryWorkflowResponse> {
-        Ok(self
-            .clone()
-            .query_workflow(
-                QueryWorkflowRequest {
-                    namespace: self.namespace(),
-                    execution: Some(WorkflowExecution {
-                        workflow_id,
-                        run_id,
-                    }),
-                    query: Some(query),
-                    query_reject_condition: 1,
-                }
-                .into_request(),
-            )
-            .await?
-            .into_inner())
-    }
-
-    async fn describe_workflow_execution(
-        &self,
-        workflow_id: String,
-        run_id: Option<String>,
-    ) -> Result<DescribeWorkflowExecutionResponse> {
-        Ok(WorkflowService::describe_workflow_execution(
-            &mut self.clone(),
-            DescribeWorkflowExecutionRequest {
-                namespace: self.namespace(),
-                execution: Some(WorkflowExecution {
-                    workflow_id,
-                    run_id: run_id.unwrap_or_default(),
-                }),
-            }
-            .into_request(),
-        )
-        .await?
-        .into_inner())
+        Ok(WorkflowHandle::new(
+            self.clone(),
+            WorkflowExecutionInfo {
+                namespace,
+                workflow_id,
+                run_id: Some(run_id.clone()),
+                first_execution_run_id: Some(run_id),
+            },
+        ))
     }
 
-    async fn get_workflow_execution_history(
+    fn get_workflow_handle<W: WorkflowDefinition>(
         &self,
-        workflow_id: String,
-        run_id: Option<String>,
-        page_token: Vec<u8>,
-    ) -> Result<GetWorkflowExecutionHistoryResponse> {
-        Ok(WorkflowService::get_workflow_execution_history(
-            &mut self.clone(),
-            GetWorkflowExecutionHistoryRequest {
+        workflow_id: impl Into<String>,
+    ) -> WorkflowHandle<Self, W>
+    where
+        Self: Sized,
+    {
+        WorkflowHandle::new(
+            self.clone(),
+            WorkflowExecutionInfo {
                 namespace: self.namespace(),
-                execution: Some(WorkflowExecution {
-                    workflow_id,
-                    run_id: run_id.unwrap_or_default(),
-                }),
-                next_page_token: page_token,
-                ..Default::default()
-            }
-            .into_request(),
+                workflow_id: workflow_id.into(),
+                run_id: None,
+                first_execution_run_id: None,
+            },
         )
-        .await?
-        .into_inner())
     }
 
-    async fn cancel_workflow_execution(
+    fn list_workflows(
         &self,
-        workflow_id: String,
-        run_id: Option<String>,
-        reason: String,
-        request_id: Option<String>,
-    ) -> Result<RequestCancelWorkflowExecutionResponse> {
-        Ok(self
-            .clone()
-            .request_cancel_workflow_execution(
-                RequestCancelWorkflowExecutionRequest {
-                    namespace: self.namespace(),
-                    workflow_execution: Some(WorkflowExecution {
-                        workflow_id,
-                        run_id: run_id.unwrap_or_default(),
-                    }),
-                    identity: self.identity(),
-                    request_id: request_id.unwrap_or_else(|| Uuid::new_v4().to_string()),
-                    first_execution_run_id: "".to_string(),
-                    reason,
-                    links: vec![],
+        query: impl Into<String>,
+        opts: WorkflowListOptions,
+    ) -> ListWorkflowsStream {
+        let client = self.clone();
+        let namespace = self.namespace();
+        let query = query.into();
+        let limit = opts.limit;
+
+        // State: (next_page_token, buffer, yielded_count, exhausted)
+        let initial_state = (Vec::new(), VecDeque::new(), 0, false);
+
+        let stream = stream::unfold(
+            initial_state,
+            move |(next_page_token, mut buffer, mut yielded, exhausted)| {
+                let mut client = client.clone();
+                let namespace = namespace.clone();
+                let query = query.clone();
+
+                async move {
+                    if let Some(l) = limit
+                        && yielded >= l
+                    {
+                        return None;
+                    }
+
+                    if let Some(exec) = buffer.pop_front() {
+                        yielded += 1;
+                        return Some((Ok(exec), (next_page_token, buffer, yielded, exhausted)));
+                    }
+
+                    if exhausted {
+                        return None;
+                    }
+
+                    let response = WorkflowService::list_workflow_executions(
+                        &mut client,
+                        ListWorkflowExecutionsRequest {
+                            namespace,
+                            page_size: 0, // Use server default
+                            next_page_token: next_page_token.clone(),
+                            query,
+                        }
+                        .into_request(),
+                    )
+                    .await;
+
+                    match response {
+                        Ok(resp) => {
+                            let resp = resp.into_inner();
+                            let new_exhausted = resp.next_page_token.is_empty();
+                            let new_token = resp.next_page_token;
+
+                            buffer = resp
+                                .executions
+                                .into_iter()
+                                .map(WorkflowExecution::from)
+                                .collect();
+
+                            if let Some(exec) = buffer.pop_front() {
+                                yielded += 1;
+                                Some((Ok(exec), (new_token, buffer, yielded, new_exhausted)))
+                            } else {
+                                None
+                            }
+                        }
+                        Err(e) => Some((Err(e.into()), (next_page_token, buffer, yielded, true))),
+                    }
                 }
-                .into_request(),
-            )
-            .await?
-            .into_inner())
-    }
-
-    async fn terminate_workflow_execution(
-        &self,
-        workflow_id: String,
-        run_id: Option<String>,
-    ) -> Result<TerminateWorkflowExecutionResponse> {
-        Ok(WorkflowService::terminate_workflow_execution(
-            &mut self.clone(),
-            TerminateWorkflowExecutionRequest {
-                namespace: self.namespace(),
-                workflow_execution: Some(WorkflowExecution {
-                    workflow_id,
-                    run_id: run_id.unwrap_or_default(),
-                }),
-                reason: "".to_string(),
-                details: None,
-                identity: self.identity(),
-                first_execution_run_id: "".to_string(),
-                links: vec![],
-            }
-            .into_request(),
-        )
-        .await?
-        .into_inner())
-    }
-
-    async fn register_namespace(
-        &self,
-        options: RegisterNamespaceOptions,
-    ) -> Result<RegisterNamespaceResponse> {
-        let req = Into::<RegisterNamespaceRequest>::into(options);
-        Ok(
-            WorkflowService::register_namespace(&mut self.clone(), req.into_request())
-                .await?
-                .into_inner(),
-        )
-    }
-
-    async fn list_namespaces(&self) -> Result<ListNamespacesResponse> {
-        Ok(WorkflowService::list_namespaces(
-            &mut self.clone(),
-            ListNamespacesRequest::default().into_request(),
-        )
-        .await?
-        .into_inner())
-    }
-
-    async fn describe_namespace(&self, namespace: Namespace) -> Result<DescribeNamespaceResponse> {
-        Ok(WorkflowService::describe_namespace(
-            &mut self.clone(),
-            namespace.into_describe_namespace_request().into_request(),
-        )
-        .await?
-        .into_inner())
-    }
-
-    async fn list_open_workflow_executions(
-        &self,
-        maximum_page_size: i32,
-        next_page_token: Vec<u8>,
-        start_time_filter: Option<StartTimeFilter>,
-        filters: Option<list_open_workflow_executions_request::Filters>,
-    ) -> Result<ListOpenWorkflowExecutionsResponse> {
-        Ok(WorkflowService::list_open_workflow_executions(
-            &mut self.clone(),
-            ListOpenWorkflowExecutionsRequest {
-                namespace: self.namespace(),
-                maximum_page_size,
-                next_page_token,
-                start_time_filter,
-                filters,
-            }
-            .into_request(),
-        )
-        .await?
-        .into_inner())
-    }
-
-    async fn list_closed_workflow_executions(
-        &self,
-        maximum_page_size: i32,
-        next_page_token: Vec<u8>,
-        start_time_filter: Option<StartTimeFilter>,
-        filters: Option<list_closed_workflow_executions_request::Filters>,
-    ) -> Result<ListClosedWorkflowExecutionsResponse> {
-        Ok(WorkflowService::list_closed_workflow_executions(
-            &mut self.clone(),
-            ListClosedWorkflowExecutionsRequest {
-                namespace: self.namespace(),
-                maximum_page_size,
-                next_page_token,
-                start_time_filter,
-                filters,
-            }
-            .into_request(),
-        )
-        .await?
-        .into_inner())
-    }
+            },
+        );
 
-    async fn list_workflow_executions(
-        &self,
-        page_size: i32,
-        next_page_token: Vec<u8>,
-        query: String,
-    ) -> Result<ListWorkflowExecutionsResponse> {
-        Ok(WorkflowService::list_workflow_executions(
-            &mut self.clone(),
-            ListWorkflowExecutionsRequest {
-                namespace: self.namespace(),
-                page_size,
-                next_page_token,
-                query,
-            }
-            .into_request(),
-        )
-        .await?
-        .into_inner())
+        ListWorkflowsStream::new(Box::pin(stream))
     }
 
-    async fn list_archived_workflow_executions(
+    async fn count_workflows(
         &self,
-        page_size: i32,
-        next_page_token: Vec<u8>,
-        query: String,
-    ) -> Result<ListArchivedWorkflowExecutionsResponse> {
-        Ok(WorkflowService::list_archived_workflow_executions(
+        query: impl Into<String>,
+        _opts: WorkflowCountOptions,
+    ) -> Result<WorkflowExecutionCount, ClientError> {
+        let resp = WorkflowService::count_workflow_executions(
             &mut self.clone(),
-            ListArchivedWorkflowExecutionsRequest {
+            CountWorkflowExecutionsRequest {
                 namespace: self.namespace(),
-                page_size,
-                next_page_token,
-                query,
+                query: query.into(),
             }
             .into_request(),
         )
         .await?
-        .into_inner())
-    }
+        .into_inner();
 
-    async fn get_search_attributes(&self) -> Result<GetSearchAttributesResponse> {
-        Ok(WorkflowService::get_search_attributes(
-            &mut self.clone(),
-            GetSearchAttributesRequest {}.into_request(),
-        )
-        .await?
-        .into_inner())
+        Ok(WorkflowExecutionCount::from_response(resp))
     }
 
-    async fn update_workflow_execution(
-        &self,
-        workflow_id: String,
-        run_id: String,
-        name: String,
-        wait_policy: update::v1::WaitPolicy,
-        args: Option<Payloads>,
-    ) -> Result<UpdateWorkflowExecutionResponse> {
-        Ok(WorkflowService::update_workflow_execution(
-            &mut self.clone(),
-            UpdateWorkflowExecutionRequest {
-                namespace: self.namespace(),
-                workflow_execution: Some(WorkflowExecution {
-                    workflow_id,
-                    run_id,
-                }),
-                wait_policy: Some(wait_policy),
-                request: Some(update::v1::Request {
-                    meta: Some(update::v1::Meta {
-                        update_id: "".into(),
-                        identity: self.identity(),
-                    }),
-                    input: Some(update::v1::Input {
-                        header: None,
-                        name,
-                        args,
-                    }),
-                }),
-                ..Default::default()
-            }
-            .into_request(),
-        )
-        .await?
-        .into_inner())
-    }
-}
-
-mod sealed {
-    use crate::{WorkflowClientTrait, WorkflowService};
-    pub trait WfHandleClient: WorkflowClientTrait + WorkflowService {}
-    impl<T> WfHandleClient for T where T: WorkflowClientTrait + WorkflowService {}
-}
-
-/// Additional methods for workflow clients
-pub trait WfClientExt: WfHandleClient + Sized + Clone {
-    /// Create an untyped handle for a workflow execution, which can be used to do things like
-    /// wait for that workflow's result. `run_id` may be left blank to target the latest run.
-    fn get_untyped_workflow_handle(
-        &self,
-        workflow_id: impl Into<String>,
-        run_id: impl Into<String>,
-    ) -> UntypedWorkflowHandle<Self> {
-        let rid = run_id.into();
-        UntypedWorkflowHandle::new(
-            self.clone(),
-            WorkflowExecutionInfo {
-                namespace: self.namespace(),
-                workflow_id: workflow_id.into(),
-                run_id: if rid.is_empty() { None } else { Some(rid) },
-            },
-        )
+    fn get_async_activity_handle(&self, identifier: ActivityIdentifier) -> AsyncActivityHandle<Self>
+    where
+        Self: Sized,
+    {
+        AsyncActivityHandle::new(self.clone(), identifier)
     }
 }
 
-impl<T> WfClientExt for T where T: WfHandleClient + Clone + Sized {}
-
 macro_rules! dbg_panic {
   ($($arg:tt)*) => {
       use tracing::error;
@@ -1822,16 +1264,10 @@ pub(crate) use dbg_panic;
 mod tests {
     use super::*;
     use tonic::metadata::Ascii;
+    use url::Url;
 
     #[test]
     fn applies_headers() {
-        let opts = ClientOptions::builder()
-            .identity("enchicat".to_string())
-            .target_url(Url::parse("https://smolkitty").unwrap())
-            .client_name("cute-kitty".to_string())
-            .client_version("0.1.0".to_string())
-            .build();
-
         // Initial header set
         let headers = Arc::new(RwLock::new(ClientHeaders {
             user_headers: HashMap::new(),
@@ -1847,7 +1283,8 @@ mod tests {
             vec![1, 2, 3].try_into().unwrap(),
         );
         let mut interceptor = ServiceCallInterceptor {
-            opts,
+            client_name: "cute-kitty".to_string(),
+            client_version: "0.1.0".to_string(),
             headers: headers.clone(),
         };
 
@@ -1959,9 +1396,8 @@ mod tests {
 
     #[test]
     fn keep_alive_defaults() {
-        let opts = ClientOptions::builder()
+        let opts = ConnectionOptions::new(Url::parse("https://smolkitty").unwrap())
             .identity("enchicat".to_string())
-            .target_url(Url::parse("https://smolkitty").unwrap())
             .client_name("cute-kitty".to_string())
             .client_version("0.1.0".to_string())
             .build();
@@ -1975,9 +1411,8 @@ mod tests {
         );
 
         // Can be explicitly set to None
-        let opts = ClientOptions::builder()
+        let opts = ConnectionOptions::new(Url::parse("https://smolkitty").unwrap())
             .identity("enchicat".to_string())
-            .target_url(Url::parse("https://smolkitty").unwrap())
             .client_name("cute-kitty".to_string())
             .client_version("0.1.0".to_string())
             .keep_alive(None)
@@ -1985,4 +1420,163 @@ mod tests {
         dbg!(&opts.keep_alive);
         assert!(opts.keep_alive.is_none());
     }
+
+    mod list_workflows_tests {
+        use super::*;
+        use futures_util::{FutureExt, StreamExt};
+        use std::sync::atomic::{AtomicUsize, Ordering};
+        use temporalio_common::protos::temporal::api::common::v1::WorkflowExecution as ProtoWorkflowExecution;
+        use tonic::{Request, Response};
+
+        #[derive(Clone)]
+        struct MockListWorkflowsClient {
+            call_count: Arc<AtomicUsize>,
+            // Returns this many workflows per page
+            page_size: usize,
+            // Total workflows available
+            total_workflows: usize,
+        }
+
+        impl NamespacedClient for MockListWorkflowsClient {
+            fn namespace(&self) -> String {
+                "test-namespace".to_string()
+            }
+            fn identity(&self) -> String {
+                "test-identity".to_string()
+            }
+        }
+
+        impl WorkflowService for MockListWorkflowsClient {
+            fn list_workflow_executions(
+                &mut self,
+                request: Request<ListWorkflowExecutionsRequest>,
+            ) -> futures_util::future::BoxFuture<
+                '_,
+                Result<Response<ListWorkflowExecutionsResponse>, tonic::Status>,
+            > {
+                self.call_count.fetch_add(1, Ordering::SeqCst);
+                let req = request.into_inner();
+
+                // Determine offset from page token
+                let offset: usize = if req.next_page_token.is_empty() {
+                    0
+                } else {
+                    String::from_utf8(req.next_page_token)
+                        .unwrap()
+                        .parse()
+                        .unwrap()
+                };
+
+                let remaining = self.total_workflows.saturating_sub(offset);
+                let count = remaining.min(self.page_size);
+                let new_offset = offset + count;
+
+                let executions: Vec<_> = (offset..offset + count)
+                    .map(|i| workflow::WorkflowExecutionInfo {
+                        execution: Some(ProtoWorkflowExecution {
+                            workflow_id: format!("wf-{i}"),
+                            run_id: format!("run-{i}"),
+                        }),
+                        r#type: Some(WorkflowType {
+                            name: "TestWorkflow".to_string(),
+                        }),
+                        task_queue: "test-queue".to_string(),
+                        ..Default::default()
+                    })
+                    .collect();
+
+                let next_page_token = if new_offset < self.total_workflows {
+                    new_offset.to_string().into_bytes()
+                } else {
+                    vec![]
+                };
+
+                async move {
+                    Ok(Response::new(ListWorkflowExecutionsResponse {
+                        executions,
+                        next_page_token,
+                    }))
+                }
+                .boxed()
+            }
+        }
+
+        #[tokio::test]
+        async fn list_workflows_paginates_through_all_results() {
+            let call_count = Arc::new(AtomicUsize::new(0));
+            let client = MockListWorkflowsClient {
+                call_count: call_count.clone(),
+                page_size: 3,
+                total_workflows: 10,
+            };
+
+            let stream = client.list_workflows("", WorkflowListOptions::default());
+            let results: Vec<_> = stream.collect().await;
+
+            assert_eq!(results.len(), 10);
+            for (i, result) in results.iter().enumerate() {
+                let wf = result.as_ref().unwrap();
+                assert_eq!(wf.id(), format!("wf-{i}"));
+                assert_eq!(wf.run_id(), format!("run-{i}"));
+            }
+            // Should have made 4 calls: pages of 3, 3, 3, 1
+            assert_eq!(call_count.load(Ordering::SeqCst), 4);
+        }
+
+        #[tokio::test]
+        async fn list_workflows_respects_limit() {
+            let call_count = Arc::new(AtomicUsize::new(0));
+            let client = MockListWorkflowsClient {
+                call_count: call_count.clone(),
+                page_size: 3,
+                total_workflows: 10,
+            };
+
+            let opts = WorkflowListOptions::builder().limit(5).build();
+            let stream = client.list_workflows("", opts);
+            let results: Vec<_> = stream.collect().await;
+
+            assert_eq!(results.len(), 5);
+            for (i, result) in results.iter().enumerate() {
+                let wf = result.as_ref().unwrap();
+                assert_eq!(wf.id(), format!("wf-{i}"));
+            }
+            // Should have made 2 calls: 1 page of 3, then 2 more from next page
+            assert_eq!(call_count.load(Ordering::SeqCst), 2);
+        }
+
+        #[tokio::test]
+        async fn list_workflows_limit_less_than_page_size() {
+            let call_count = Arc::new(AtomicUsize::new(0));
+            let client = MockListWorkflowsClient {
+                call_count: call_count.clone(),
+                page_size: 10,
+                total_workflows: 100,
+            };
+
+            let opts = WorkflowListOptions::builder().limit(3).build();
+            let stream = client.list_workflows("", opts);
+            let results: Vec<_> = stream.collect().await;
+
+            assert_eq!(results.len(), 3);
+            // Only 1 call needed since limit < page_size
+            assert_eq!(call_count.load(Ordering::SeqCst), 1);
+        }
+
+        #[tokio::test]
+        async fn list_workflows_empty_results() {
+            let call_count = Arc::new(AtomicUsize::new(0));
+            let client = MockListWorkflowsClient {
+                call_count: call_count.clone(),
+                page_size: 10,
+                total_workflows: 0,
+            };
+
+            let stream = client.list_workflows("", WorkflowListOptions::default());
+            let results: Vec<_> = stream.collect().await;
+
+            assert_eq!(results.len(), 0);
+            assert_eq!(call_count.load(Ordering::SeqCst), 1);
+        }
+    }
 }