temporalio 1.8.0 → 1.10.0

data/lib/temporalio/client/interceptor.rb

@@ -260,8 +260,6 @@ module Temporalio
       )
 
       # Input for {Outbound.start_activity}.
-      #
-      # WARNING: Standalone Activities are experimental.
       StartActivityInput = Data.define(
         :activity,
         :args,
@@ -275,7 +273,7 @@ module Temporalio
         :id_conflict_policy,
         :retry_policy,
         :search_attributes,
-        :static_summary,
+        :summary,
         :static_details,
         :headers,
         :priority,
@@ -286,8 +284,6 @@ module Temporalio
       )
 
       # Input for {Outbound.describe_activity}.
-      #
-      # WARNING: Standalone Activities are experimental.
       DescribeActivityInput = Data.define(
         :activity_id,
         :activity_run_id,
@@ -299,8 +295,6 @@ module Temporalio
       )
 
       # Input for {Outbound.cancel_activity}.
-      #
-      # WARNING: Standalone Activities are experimental.
       CancelActivityInput = Data.define(
         :activity_id,
         :activity_run_id,
@@ -309,8 +303,6 @@ module Temporalio
       )
 
       # Input for {Outbound.terminate_activity}.
-      #
-      # WARNING: Standalone Activities are experimental.
       TerminateActivityInput = Data.define(
         :activity_id,
         :activity_run_id,
@@ -352,16 +344,12 @@ module Temporalio
       )
 
       # Input for {Outbound.list_activities}.
-      #
-      # WARNING: Standalone Activities are experimental.
       ListActivitiesInput = Data.define(
         :query,
         :rpc_options
       )
 
       # Input for {Outbound.count_activities}.
-      #
-      # WARNING: Standalone Activities are experimental.
       CountActivitiesInput = Data.define(
         :query,
         :rpc_options
@@ -369,8 +357,6 @@ module Temporalio
 
       # Input for {Outbound.fetch_activity_outcome}. Used by `ActivityHandle#result` for long-polling
       # the activity outcome via `PollActivityExecution`.
-      #
-      # WARNING: Standalone Activities are experimental.
       FetchActivityOutcomeInput = Data.define(
         :activity_id,
         :activity_run_id,
@@ -588,8 +574,6 @@ module Temporalio
 
         # Called for every {Client.start_activity} and {Client.execute_activity} call.
         #
-        # WARNING: Standalone Activities are experimental.
-        #
         # @param input [StartActivityInput] Input.
         # @return [ActivityHandle] Activity handle.
         def start_activity(input)
@@ -598,8 +582,6 @@ module Temporalio
 
         # Called for every {ActivityHandle.describe} call.
         #
-        # WARNING: Standalone Activities are experimental.
-        #
         # @param input [DescribeActivityInput] Input.
         # @return [ActivityExecution::Description] Activity description.
         def describe_activity(input)
@@ -608,8 +590,6 @@ module Temporalio
 
         # Called for every {ActivityHandle.cancel} call.
         #
-        # WARNING: Standalone Activities are experimental.
-        #
         # @param input [CancelActivityInput] Input.
         def cancel_activity(input)
           next_interceptor.cancel_activity(input)
@@ -617,8 +597,6 @@ module Temporalio
 
         # Called for every {ActivityHandle.terminate} call.
         #
-        # WARNING: Standalone Activities are experimental.
-        #
         # @param input [TerminateActivityInput] Input.
         def terminate_activity(input)
           next_interceptor.terminate_activity(input)
@@ -654,8 +632,6 @@ module Temporalio
 
         # Called for every {Client.list_activities} call.
         #
-        # WARNING: Standalone Activities are experimental.
-        #
         # @param input [ListActivitiesInput] Input.
         # @return [Enumerator<ActivityExecution>] Activity executions.
         def list_activities(input)
@@ -664,8 +640,6 @@ module Temporalio
 
         # Called for every {Client.count_activities} call.
         #
-        # WARNING: Standalone Activities are experimental.
-        #
         # @param input [CountActivitiesInput] Input.
         # @return [ActivityExecutionCount] Activity count.
         def count_activities(input)
@@ -674,8 +648,6 @@ module Temporalio
 
         # Called by {ActivityHandle.result} to long-poll the activity outcome.
         #
-        # WARNING: Standalone Activities are experimental.
-        #
         # @param input [FetchActivityOutcomeInput] Input.
         # @return [Api::Activity::V1::ActivityExecutionOutcome] Activity outcome.
         def fetch_activity_outcome(input)

data/lib/temporalio/client/pending_activity_state.rb

@@ -5,8 +5,6 @@ require 'temporalio/api'
 module Temporalio
   class Client
     # More detailed breakdown of a running activity's state.
-    #
-    # WARNING: Standalone Activities are experimental.
     module PendingActivityState
       SCHEDULED = Api::Enums::V1::PendingActivityState::PENDING_ACTIVITY_STATE_SCHEDULED
       STARTED = Api::Enums::V1::PendingActivityState::PENDING_ACTIVITY_STATE_STARTED

data/lib/temporalio/client/schedule.rb

@@ -211,7 +211,7 @@ module Temporalio
         # @!attribute search_attributes
         #   @return [SearchAttributes, nil] Search attributes for the workflow.
         # @!attribute priority
-        #   @return [Priority] Priority of the workflow. This is currently experimental.
+        #   @return [Priority] Priority of the workflow.
         # @!attribute arg_hints
         #   @return [Array<Object>, nil] Converter hints for workflow arguments. This is only user-set (e.g. on create)
         #     and is not persisted and therefore will not be set when describing a workflow.
@@ -242,7 +242,7 @@ module Temporalio
             # @param retry_policy [RetryPolicy, nil] Retry policy for the workflow.
             # @param memo [Hash<String, Object>, nil] Memo for the workflow.
             # @param search_attributes [SearchAttributes, nil] Search attributes for the workflow.
-            # @param priority [Priority] Priority of the workflow. This is currently experimental.
+            # @param priority [Priority] Priority of the workflow.
             # @param headers [Hash<String, Object>, nil] Headers for the workflow.
             def new(
               workflow,
@@ -732,7 +732,8 @@ module Temporalio
       # @!attribute overlap
       #   @return [OverlapPolicy] Controls what happens when an action is started while another is still running.
       # @!attribute catchup_window
-      #   @return [Float] After a Temporal server is unavailable, amount of time in the past to execute missed actions.
+      #   @return [Float, nil] After a Temporal server is unavailable, amount of time in the past to execute missed
+      #     actions. If nil, the server-configured default applies (currently one year).
       # @!attribute pause_on_failure
       #   @return [Boolean] Whether to pause the schedule if an action fails or times out. Note: For workflows, this
       #     only applies after all retries have been exhausted.
@@ -743,7 +744,7 @@ module Temporalio
             overlap: Internal::ProtoUtils.enum_to_int(Api::Enums::V1::ScheduleOverlapPolicy,
                                                       raw_policies.overlap_policy,
                                                       zero_means_nil: true),
-            catchup_window: Internal::ProtoUtils.duration_to_seconds(raw_policies.catchup_window) || raise, # Never nil
+            catchup_window: Internal::ProtoUtils.duration_to_seconds(raw_policies.catchup_window),
             pause_on_failure: raw_policies.pause_on_failure
           )
         end
@@ -751,13 +752,13 @@ module Temporalio
         # Create a schedule policy.
         #
         # @param overlap [OverlapPolicy] Controls what happens when an action is started while another is still running.
-        # @param catchup_window [Float] After a Temporal server is unavailable, amount of time in the past to execute
-        #   missed actions.
+        # @param catchup_window [Float, nil] After a Temporal server is unavailable, amount of time in the past to
+        #   execute missed actions. If nil, the server-configured default applies. An explicit zero is sent.
         # @param pause_on_failure [Boolean] Whether to pause the schedule if an action fails or times out. Note: For
         #   workflows, this only applies after all retries have been exhausted.
         def initialize(
           overlap: OverlapPolicy::SKIP,
-          catchup_window: 365 * 24 * 60 * 60.0,
+          catchup_window: nil,
           pause_on_failure: false
         )
           super

data/lib/temporalio/client/with_start_workflow_operation.rb

@@ -43,7 +43,7 @@ module Temporalio
       # Note, for {Client.start_update_with_start_workflow} and {Client.execute_update_with_start_workflow},
       # `id_conflict_policy` is required.
       #
-      # @param priority [Priority] Priority of the workflow that may be started. This is currently experimental.
+      # @param priority [Priority] Priority of the workflow that may be started.
       def initialize(
         workflow,
         *args,

data/lib/temporalio/client.rb

@@ -308,7 +308,7 @@ module Temporalio
     # @param request_eager_start [Boolean] Potentially reduce the latency to start this workflow by encouraging the
     #   server to start it on a local worker running with this same client. This is currently experimental.
     # @param versioning_override [VersioningOverride, nil] Override the version of the workflow.
-    # @param priority [Priority] Priority of the workflow. This is currently experimental.
+    # @param priority [Priority] Priority of the workflow.
     # @param arg_hints [Array<Object>, nil] Overrides converter hints for arguments if any. If unset/nil and the
     #   workflow definition has arg hints, those are used by default.
     # @param result_hint [Object, nil] Overrides converter hint for result if any. If unset/nil and the workflow
@@ -400,7 +400,7 @@ module Temporalio
     # @param request_eager_start [Boolean] Potentially reduce the latency to start this workflow by encouraging the
     #   server to start it on a local worker running with this same client. This is currently experimental.
     # @param versioning_override [VersioningOverride, nil] Override the version of the workflow.
-    # @param priority [Priority] Priority for the workflow. This is currently experimental.
+    # @param priority [Priority] Priority for the workflow.
     # @param arg_hints [Array<Object>, nil] Overrides converter hints for arguments if any. If unset/nil and the
     #   workflow definition has arg hints, those are used by default.
     # @param result_hint [Object, nil] Overrides converter hint for result if any. If unset/nil and the workflow
@@ -485,8 +485,6 @@ module Temporalio
     # Get a handle for an existing standalone activity. Useful when the activity was started elsewhere
     # (a different process, or by another client) and you have only its ID.
     #
-    # WARNING: Standalone Activities are experimental.
-    #
     # @param activity_id [String] ID for the activity.
     # @param activity_run_id [String, nil] Run ID for the activity execution. If nil, operations target the
     #   latest run of the given activity ID.
@@ -500,8 +498,6 @@ module Temporalio
 
     # Start a standalone activity execution and return its handle.
     #
-    # WARNING: Standalone Activities are experimental.
-    #
     # @param activity [Class<Activity::Definition>, Activity::Definition, Activity::Definition::Info, Symbol, String]
     #   Activity definition, definition class or activity name.
     # @param args [Array<Object>] Arguments to the activity.
@@ -519,9 +515,9 @@ module Temporalio
     #   is currently running. Defaults to `FAIL` (reject the start attempt).
     # @param retry_policy [RetryPolicy, nil] Retry policy for the activity.
     # @param search_attributes [SearchAttributes, nil] Search attributes for the activity.
-    # @param static_summary [String, nil] Fixed single-line summary for this activity execution.
+    # @param summary [String, nil] Fixed single-line summary for this activity execution.
     # @param static_details [String, nil] Fixed details for this activity execution. May be in markdown format.
-    # @param priority [Priority] Priority for the activity. This is currently experimental.
+    # @param priority [Priority] Priority for the activity.
     # @param start_delay [Float, nil] Time (in seconds) to wait before dispatching the first activity task. This delay
     #   is not applied to retry attempts. `nil` or `0` means no delay. Negative values raise `ArgumentError`.
     #   This is currently experimental.
@@ -545,7 +541,7 @@ module Temporalio
       id_conflict_policy: ActivityIDConflictPolicy::FAIL,
       retry_policy: nil,
       search_attributes: nil,
-      static_summary: nil,
+      summary: nil,
       static_details: nil,
       priority: Priority.default,
       start_delay: nil,
@@ -568,7 +564,7 @@ module Temporalio
                              id_conflict_policy:,
                              retry_policy:,
                              search_attributes:,
-                             static_summary:,
+                             summary:,
                              static_details:,
                              headers: {},
                              priority:,
@@ -582,8 +578,6 @@ module Temporalio
     # Start a standalone activity execution and wait for its result. Shortcut for
     # {start_activity} + {ActivityHandle#result}.
     #
-    # WARNING: Standalone Activities are experimental.
-    #
     # @param activity [Class<Activity::Definition>, Activity::Definition, Activity::Definition::Info, Symbol, String]
     #   Activity definition, definition class or activity name.
     # @param args [Array<Object>] Arguments to the activity.
@@ -601,9 +595,9 @@ module Temporalio
     #   is currently running. Defaults to `FAIL` (reject the start attempt).
     # @param retry_policy [RetryPolicy, nil] Retry policy for the activity.
     # @param search_attributes [SearchAttributes, nil] Search attributes for the activity.
-    # @param static_summary [String, nil] Fixed single-line summary for this activity execution.
+    # @param summary [String, nil] Fixed single-line summary for this activity execution.
     # @param static_details [String, nil] Fixed details for this activity execution. May be in markdown format.
-    # @param priority [Priority] Priority for the activity. This is currently experimental.
+    # @param priority [Priority] Priority for the activity.
     # @param start_delay [Float, nil] Time (in seconds) to wait before dispatching the first activity task. This delay
     #   is not applied to retry attempts. `nil` or `0` means no delay. Negative values raise `ArgumentError`.
     #   This is currently experimental.
@@ -628,7 +622,7 @@ module Temporalio
       id_conflict_policy: ActivityIDConflictPolicy::FAIL,
       retry_policy: nil,
       search_attributes: nil,
-      static_summary: nil,
+      summary: nil,
       static_details: nil,
       priority: Priority.default,
       start_delay: nil,
@@ -649,7 +643,7 @@ module Temporalio
         id_conflict_policy:,
         retry_policy:,
         search_attributes:,
-        static_summary:,
+        summary:,
         static_details:,
         priority:,
         start_delay:,
@@ -661,8 +655,6 @@ module Temporalio
 
     # List standalone activities matching a visibility query.
     #
-    # WARNING: Standalone Activities are experimental.
-    #
     # @param query [String] Visibility list filter.
     # @param rpc_options [RPCOptions, nil] Advanced RPC options.
     #
@@ -674,8 +666,6 @@ module Temporalio
 
     # Count standalone activities matching a visibility query.
     #
-    # WARNING: Standalone Activities are experimental.
-    #
     # @param query [String] Visibility list filter.
     # @param rpc_options [RPCOptions, nil] Advanced RPC options.
     #

data/lib/temporalio/common_enums.rb

@@ -86,8 +86,6 @@ module Temporalio
 
   # Controls behavior when an activity with the same ID was previously run and is now closed.
   #
-  # WARNING: Standalone Activities are experimental.
-  #
   # @see https://docs.temporal.io/activities
   module ActivityIDReusePolicy
     # Always allow starting an activity using the same activity ID.
@@ -102,8 +100,6 @@ module Temporalio
 
   # Controls behavior when an activity with the same ID is currently running.
   #
-  # WARNING: Standalone Activities are experimental.
-  #
   # @see https://docs.temporal.io/activities
   module ActivityIDConflictPolicy
     # Don't start a new activity; instead fail with already-started error.

data/lib/temporalio/converters/external_storage.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'temporalio/converters/external_storage_concurrency'
+require 'temporalio/converters/storage_driver'
+
+module Temporalio
+  module Converters
+    # Configuration for offloading large payloads to an external storage system.
+    #
+    # This is validated when constructed rather than when used, so a misconfiguration surfaces at startup instead of on
+    # the first payload large enough to offload.
+    #
+    # @note WARNING: This API is experimental and may change in the future.
+    #
+    # @!visibility private
+    class ExternalStorage
+      # Shared with every other SDK, so the same payload offloads regardless of which one wrote it.
+      DEFAULT_PAYLOAD_SIZE_THRESHOLD = 256 * 1024
+
+      # @return [Array<StorageDriver>] Drivers available for storing and retrieving payloads.
+      attr_reader :drivers
+
+      # @return [Proc] Selector choosing which driver stores each payload. Called with a
+      #   {StorageDriverSelectContext} and a payload, returning a {StorageDriver} or nil to pass the payload through.
+      #   Only called for payloads that meet {#payload_size_threshold}, and must return one of {#drivers} or nil.
+      attr_reader :driver_selector
+
+      # @return [ExternalStorageConcurrency] Limits on how many storage requests may be in flight at once.
+      attr_reader :concurrency
+
+      # @return [Integer] Minimum encoded payload size, in bytes, that is offloaded. Payloads at or above this size are
+      #   offloaded; smaller ones are left inline. Zero offloads every payload.
+      attr_reader :payload_size_threshold
+
+      # Create external storage configuration.
+      #
+      # @param drivers [Array<StorageDriver>] Drivers available for storing and retrieving payloads. At least one is
+      #   required, and every driver must have a unique, non-empty name. Retrieval routes by the name recorded in
+      #   history, so a driver must remain configured for as long as any payload it stored can still be read.
+      # @param driver_selector [Proc, nil] Selector choosing which driver stores each payload. Required when more than
+      #   one driver is given; with a single driver it may be nil, in which case that driver stores every eligible
+      #   payload.
+      # @param payload_size_threshold [Integer] Minimum encoded payload size, in bytes, to offload. Must be a
+      #   non-negative Integer.
+      # @param concurrency [ExternalStorageConcurrency] Limits on how many storage requests may be in flight at once.
+      def initialize(
+        drivers:,
+        driver_selector: nil,
+        payload_size_threshold: DEFAULT_PAYLOAD_SIZE_THRESHOLD,
+        concurrency: ExternalStorageConcurrency.new
+      )
+        raise ArgumentError, 'At least one driver is required' if drivers.empty?
+
+        unless payload_size_threshold.is_a?(Integer) && payload_size_threshold >= 0
+          raise ArgumentError, 'payload_size_threshold must be a non-negative Integer'
+        end
+
+        if drivers.size > 1 && driver_selector.nil?
+          raise ArgumentError, 'driver_selector is required when more than one driver is given'
+        end
+
+        @drivers_by_name = {}
+        drivers.each do |driver|
+          name = driver.name
+          # The name is the routing key written into history and is written to a string proto field, so anything but
+          # a non-empty String cannot be resolved on read. A Symbol in particular passes a bare empty? check.
+          raise ArgumentError, 'Driver name must be a non-empty String' unless name.is_a?(String) && !name.empty?
+          raise ArgumentError, "Multiple drivers given with name '#{name}'" if @drivers_by_name.key?(name)
+
+          @drivers_by_name[name] = driver
+        end
+        @drivers_by_name.freeze
+
+        @drivers = drivers.dup.freeze
+        # Normalized so callers never have to distinguish the single-driver case.
+        @driver_selector = driver_selector || ->(_context, _payload) { @drivers.first }
+        @payload_size_threshold = payload_size_threshold
+        @concurrency = concurrency
+      end
+
+      # Get the driver registered under the given name.
+      #
+      # @param name [String] Driver name recorded in the payload reference.
+      # @return [StorageDriver, nil] The driver, or nil if none is registered under that name.
+      def driver(name)
+        @drivers_by_name[name]
+      end
+    end
+  end
+end

data/lib/temporalio/converters/external_storage_concurrency.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Temporalio
+  module Converters
+    ExternalStorageConcurrency = Data.define(
+      :max_driver_operations,
+      :max_operations_per_message
+    )
+
+    # Limits on how many external storage requests may be in flight at once. Set on
+    # {ExternalStorage#concurrency}.
+    #
+    # @note WARNING: This API is experimental and may change in the future.
+    #
+    # @!attribute [r] max_driver_operations
+    #   @return [Integer] Maximum requests in flight at once across every driver registered on the owning
+    #     {ExternalStorage}. Each worker and each client gets its own budget of this size.
+    # @!attribute [r] max_operations_per_message
+    #   @return [Integer] Maximum requests in flight at once on behalf of a single message, such as one workflow task
+    #     activation, activity task, Nexus operation, or client request. Every message gets its own budget of this
+    #     size, which stops a message carrying many large payloads from starving the rest.
+    #
+    # @!visibility private
+    class ExternalStorageConcurrency
+      # Shared with every other SDK.
+      DEFAULT_MAX_DRIVER_OPERATIONS = 64
+
+      # Shared with every other SDK.
+      DEFAULT_MAX_OPERATIONS_PER_MESSAGE = 8
+
+      # Create concurrency limits.
+      #
+      # @param max_driver_operations [Integer] Maximum requests in flight across the configuration.
+      # @param max_operations_per_message [Integer] Maximum requests in flight for one message.
+      def initialize(
+        max_driver_operations: DEFAULT_MAX_DRIVER_OPERATIONS,
+        max_operations_per_message: DEFAULT_MAX_OPERATIONS_PER_MESSAGE
+      )
+        # A budget of zero would stop every storage operation rather than disabling the limit, so it is rejected
+        # here instead of deadlocking the first offload.
+        unless max_driver_operations.is_a?(Integer) && max_driver_operations >= 1
+          raise ArgumentError, 'max_driver_operations must be an Integer of at least 1'
+        end
+        unless max_operations_per_message.is_a?(Integer) && max_operations_per_message >= 1
+          raise ArgumentError, 'max_operations_per_message must be an Integer of at least 1'
+        end
+
+        super
+      end
+    end
+  end
+end

data/lib/temporalio/converters/storage_driver.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Temporalio
+  module Converters
+    # Base class for storing and retrieving payloads in an external storage system.
+    #
+    # Payloads at or over the configured size threshold are handed to a driver and replaced on the wire by a small
+    # reference, so the payload data itself never reaches the Temporal server.
+    #
+    # Implementations are called concurrently and must be thread safe. Methods block, and may perform I/O directly.
+    # To work a batch concurrently, fan out with threads: threads overlap blocking I/O, since Ruby releases its global
+    # lock around it, and they work whether or not the worker is running under a fiber scheduler.
+    # {::Fiber.schedule} must not be used, since it raises when the worker is configured with a payload codec thread
+    # pool instead of a fiber scheduler. {Temporalio::Worker::ThreadPool} can be used to bound that fan out.
+    #
+    # @note WARNING: This API is experimental and may change in the future.
+    #
+    # @!visibility private
+    class StorageDriver
+      # Name of this driver instance, unique among the drivers registered on one {ExternalStorage}. This is written
+      # into history alongside every payload the driver stores and is used to route retrieval back to the same driver.
+      # Renaming a deployed driver makes every payload stored under the old name unretrievable.
+      #
+      # @return [String] Driver instance name.
+      def name
+        raise NotImplementedError
+      end
+
+      # Identifier for this driver implementation, for example +aws.s3driver+. Unlike {#name}, this is identical across
+      # every instance of the same implementation and across SDK languages.
+      #
+      # @return [String] Driver implementation identifier.
+      def type
+        raise NotImplementedError
+      end
+
+      # Store the given payloads.
+      #
+      # @param context [StorageDriverStoreContext] Context for this store operation.
+      # @param payloads [Enumerable<Api::Common::V1::Payload>] Payloads to store. This value should not be mutated.
+      # @return [Array<StorageDriverClaim>] One claim per payload, in the same order.
+      def store(context, payloads)
+        raise NotImplementedError
+      end
+
+      # Retrieve the payloads for the given claims.
+      #
+      # @param context [StorageDriverRetrieveContext] Context for this retrieve operation.
+      # @param claims [Enumerable<StorageDriverClaim>] Claims to retrieve. This value should not be mutated.
+      # @return [Array<Api::Common::V1::Payload>] One payload per claim, in the same order.
+      def retrieve(context, claims)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/temporalio/converters/storage_driver_activity_info.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Temporalio
+  module Converters
+    StorageDriverActivityInfo = Data.define(
+      :namespace,
+      :id,
+      :run_id,
+      :type
+    )
+
+    # Identity of a standalone activity a payload is being stored on behalf of.
+    #
+    # @note WARNING: This API is experimental and may change in the future.
+    #
+    # @!attribute [r] namespace
+    #   @return [String] Activity namespace.
+    # @!attribute [r] id
+    #   @return [String, nil] Activity ID, if known.
+    # @!attribute [r] run_id
+    #   @return [String, nil] Run ID, if known.
+    # @!attribute [r] type
+    #   @return [String, nil] Activity type name, if known.
+    #
+    # @!visibility private
+    class StorageDriverActivityInfo
+      # Create activity target information.
+      #
+      # @param namespace [String] Activity namespace.
+      # @param id [String, nil] Activity ID.
+      # @param run_id [String, nil] Run ID.
+      # @param type [String, nil] Activity type name.
+      def initialize(namespace:, id: nil, run_id: nil, type: nil)
+        super
+      end
+    end
+  end
+end

data/lib/temporalio/converters/storage_driver_claim.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Temporalio
+  module Converters
+    StorageDriverClaim = Data.define(:claim_data)
+
+    # Driver-defined reference to an externally stored payload, used to retrieve it later.
+    #
+    # @note WARNING: This API is experimental and may change in the future.
+    #
+    # @!attribute [r] claim_data
+    #   @return [Hash<String, String>] Data the driver needs to retrieve the payload. This is written into history, so
+    #     it must contain everything required for retrieval and must not contain secrets.
+    #
+    # @!visibility private
+    class StorageDriverClaim
+      # Create a claim.
+      #
+      # @param claim_data [Hash<String, String>] Data identifying the stored payload.
+      def initialize(claim_data:)
+        # Copied and frozen because a claim is compared and hashed by this data, so a later mutation would silently
+        # change its identity. The values are copied individually because freezing the Hash leaves them mutable in
+        # place and still aliased to the caller's objects.
+        # steep:ignore:start
+        super(claim_data: claim_data.transform_values { |value| value.dup.freeze }.freeze)
+        # steep:ignore:end
+      end
+    end
+  end
+end

data/lib/temporalio/converters/storage_driver_limiter.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Temporalio
+  module Converters
+    # Bounds how many external storage requests are in flight at once. The SDK supplies one on
+    # {StorageDriverStoreContext} and {StorageDriverRetrieveContext}; a driver calls it rather than
+    # implementing it.
+    #
+    # A driver is handed a whole batch and decides for itself how many requests to make of it, so the SDK cannot
+    # bound that fan out on the driver's behalf. The limit is cooperative: a driver that never calls {#permit} makes
+    # requests that no budget counts, and the SDK warns when it detects that.
+    #
+    # @note WARNING: This API is experimental and may change in the future.
+    #
+    # @!visibility private
+    class StorageDriverLimiter
+      # Hold a permit for the duration of the given block, waiting for one to be available before the block runs
+      # and releasing it when the block returns or raises.
+      #
+      # Take one permit per request, not one around a whole batch: wrapping a whole fan out in a single permit
+      # satisfies this signature while quietly defeating the limit. Taking a permit while already holding one can
+      # deadlock once the nesting reaches the configured limit, so a driver must not nest these.
+      #
+      # Waiting for a permit observes the cancellation on the context this limiter came from, so a driver that is
+      # waiting when the SDK abandons the operation stops waiting.
+      #
+      # @param item [Api::Common::V1::Payload, StorageDriverClaim] What this one request covers: a payload when
+      #   storing, a claim when retrieving.
+      # @yield The request to make while holding the permit.
+      # @return [Object] Whatever the block returned.
+      # @raise [Error::CanceledError] If cancelled while waiting for a permit.
+      def permit(item, &)
+        raise NotImplementedError
+      end
+    end
+  end
+end