gapic-common 1.4.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11f04f82fc6e98e5ca24d814d6162d68681999b6a7f2305cc32c77c597db2a88
-  data.tar.gz: a36c758ffd65878ac9809c0ecfc515e2c6e0e817f5ad679e8574e5dbeb8a03f6
+  metadata.gz: f9cc2de9bcbe93a62a1706acc73f6d37064bbde7a81a5c9fd434570ed8c6e22f
+  data.tar.gz: 3be68b0522ce0e3465bfb555820c7c73882f2e1bf36ac009fd4bb4f31c0bb3bd
 SHA512:
-  metadata.gz: 8fb7d4c578dc4b44383ac18e33159fd824465e63df13b10ed2d2fe142c4a9743876d7a3a41cd00680dc3e44cab88f6d3d6185198a8b74a85ace1ff30ee6d9e4e
-  data.tar.gz: 3d508937a578e43a1fe8022557d08a7c01be477b9141a1d055c0d6a1df8e739eca0a9e2f14d178aa90c4b121d44dd12e437d73242250009916645948238af388
+  metadata.gz: f958c2009dead1a09f0f20a9dda26f65d1698399657462b47b501297aff0e6af7496b4b0314237485bbb4f9a61d3866b9ee8e61ac26469c0ee69184c53cddd5b
+  data.tar.gz: e8fd4368fab545fbc33636d5999e73bd9f8b664006f5967929cd8e09b25cfafb22e34a17d58ce1481b94474d952d2c7add11ba7644ba77ffab23b98c2b83728a

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Release History
 
+### 1.5.0 (2026-09-29)
+
+#### Features
+
+* Resumable Media Upload functionality implementation ([#72](https://github.com/googleapis/ruby-core-libraries/issues/72)) 
+#### Documentation
+
+* remove stale preview notice and disclaimer from READMEs ([#77](https://github.com/googleapis/ruby-core-libraries/issues/77)) 
+
 ### 1.4.1 (2026-09-28)
 
 #### Bug Fixes

data/README.md

@@ -61,9 +61,6 @@ See the {file:CONTRIBUTING.md CONTRIBUTING} documentation for more information o
 
 ## Versioning
 
-This library is currently a **preview** with no guarantees of stability or support. Please get
-involved and let us know if you find it useful and we'll work towards a stable version.
+This library follows [Semantic Versioning](http://semver.org/).
 
-## Disclaimer
-
-This is not an official Google product.
+This library is considered to be stable and will not have backwards-incompatible changes introduced in subsequent minor releases.

data/lib/gapic/common/retry_policy.rb

@@ -19,6 +19,12 @@ module Gapic
     ##
     # Gapic Common retry policy base class.
     #
+    # A policy distinguishes "set to this value" from "never set". Every setting is stored as `nil`
+    # until someone supplies it, and the reader for each substitutes the corresponding `DEFAULT_`
+    # constant on the way out, so a reader can never say which of the two happened. That distinction is
+    # what lets {#apply_defaults} fill in gaps without overwriting a caller's choices, and {#overrides}
+    # report what a caller actually asked for.
+    #
     class RetryPolicy
       # @return [Numeric] Default initial delay in seconds.
       DEFAULT_INITIAL_DELAY = 1
@@ -111,6 +117,34 @@ module Gapic
         @retry_predicate
       end
 
+      ##
+      # @private
+      # The settings this policy actually carries, as keyword arguments for {RetryPolicy.initialize}.
+      #
+      # A key is present only if that setting was explicitly supplied; a key that was never set is
+      # absent rather than `nil`. This is what the readers cannot tell you — {#max_delay} returns
+      # {DEFAULT_MAX_DELAY} whether the caller chose that number or said nothing — so it is the only
+      # safe way to carry one policy's settings onto another without dragging defaults along, and
+      # without mistaking a deliberate choice that happens to equal a default for silence.
+      #
+      # An empty `retry_codes` list counts as unset. It retries nothing, which is exactly what an
+      # unset list does, so there is nothing for it to carry.
+      #
+      # @return [Hash{Symbol=>Object}] Explicitly set settings only
+      def overrides
+        # Assigns nil, and so omits the key, when the list is absent or empty.
+        retry_codes = @retry_codes unless @retry_codes.nil? || @retry_codes.empty?
+        {
+          initial_delay:   @initial_delay,
+          max_delay:       @max_delay,
+          multiplier:      @multiplier,
+          retry_codes:     retry_codes,
+          timeout:         @timeout,
+          jitter:          @jitter,
+          retry_predicate: @retry_predicate
+        }.compact
+      end
+
       ##
       # Returns a duplicate in a non-executing state, i.e. with the deadline
       # and current delay reset.

data/lib/gapic/common/version.rb

@@ -14,6 +14,6 @@
 
 module Gapic
   module Common
-    VERSION = "1.4.1".freeze
+    VERSION = "1.5.0".freeze
   end
 end

data/lib/gapic/logging_concerns.rb

@@ -67,6 +67,10 @@ module Gapic
         log(Logger::DEBUG, &)
       end
 
+      def warn(&)
+        log(Logger::WARN, &)
+      end
+
       ##
       # @private
       # Builder for a log entry, passed to {StubLogger#log}.

data/lib/gapic/rest/client_stub.rb

@@ -287,17 +287,27 @@ module Gapic
           entry.set "requestId", request_id
           entry.message = "Sending request to #{entry.service}.#{method_name} (try #{try_number})"
         end
-        body = body.to_s
+        body_str = body.to_s
         metadata = metadata.to_h rescue {}
-        return if body.empty? && metadata.empty?
+        return if body_str.empty? && metadata.empty?
         stub_logger.debug do |entry|
           entry.set "requestId", request_id
-          entry.set "request", body
+          entry.set "request", abridge_request_body(body_str)
           entry.set "headers", metadata
           entry.message = "(request payload as JSON)"
         end
       end
 
+      def abridge_request_body body_str
+        utf8_body = body_str.dup.force_encoding Encoding::UTF_8
+        if body_str.bytesize > 1024 || !utf8_body.valid_encoding?
+          prefix_hex = body_str.byteslice(0, 32).unpack1 "H*"
+          "<#{body_str.bytesize} bytes, first 32: #{prefix_hex}>"
+        else
+          utf8_body
+        end
+      end
+
       def log_response method_name, request_id, try_number, response, is_server_streaming
         return unless stub_logger&.enabled?
         stub_logger.info do |entry|

data/lib/gapic/rest/error.rb

@@ -22,6 +22,9 @@ module Gapic
   module Rest
     # Gapic REST exception class
     class Error < ::Gapic::Common::Error
+      # @private
+      REST_ERROR_PREFIX = "An error has occurred when making a REST request".freeze
+
       # @return [Integer, nil] the http status code for the error
       attr_reader :status_code
       # @return [Object, nil] the text representation of status as parsed from the response body
@@ -79,7 +82,7 @@ module Gapic
 
           if err.response_body
             msg, code, status, details = try_parse_from_body err.response_body
-            message = "An error has occurred when making a REST request: #{msg}" unless msg.nil?
+            message = "#{REST_ERROR_PREFIX}: #{msg}" unless msg.nil?
             status_code = code unless code.nil?
           end
 

data/lib/gapic/rest/resumable_upload/core.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "gapic/rest/resumable_upload/data_types"
+require "gapic/rest/resumable_upload/rules"
+
+module Gapic
+  module Rest
+    module ResumableUpload
+      ##
+      # @private
+      # State machine container holding the immutable State snapshot.
+      # Contains zero protocol branching logic and zero side-effects.
+      #
+      # The middle tier of the three-tier design: `Driver` executes side effects, {Rules} decides transitions,
+      # and Core holds the {State} between the two. See {Rules} for the protocol narrative and state graph, and
+      # `design/resumable_upload/implementation-guide.md` section 1 for the tier boundaries.
+      #
+      class Core
+        # @private
+        # @return [State] Current immutable state snapshot
+        attr_reader :state
+
+        # @private
+        # @return [Decision, nil] Decision emitted during the last dispatch
+        attr_reader :last_decision
+
+        ##
+        # @private
+        # Initializes a Core state machine container.
+        #
+        # @param config [StartUploadConfig, ResumeUploadConfig] Upload session configuration
+        #
+        def initialize config
+          @config = config
+          @last_decision = nil
+          @state = State.new(
+            status:            :initializing,
+            upload_url:        nil,
+            offset:            0,
+            chunk_size:        config.chunk_size || Rules::DEFAULT_CHUNK_SIZE,
+            chunk_granularity: nil,
+            in_flight_length:  0,
+            last_error:        nil
+          )
+        end
+
+        ##
+        # @private
+        # Dispatches event to Rules and updates internal state snapshot.
+        #
+        # @param event [Object] Input event
+        # @return [Array<Object>] Driver instructions
+        #
+        def dispatch event
+          decision = Rules.decide @state, event, @config
+          @state = decision.next_state
+          @last_decision = decision
+          decision.instructions
+        end
+      end
+    end
+  end
+end

data/lib/gapic/rest/resumable_upload/data_types.rb

@@ -0,0 +1,428 @@
+# frozen_string_literal: true
+
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# rubocop:disable Metrics/ModuleLength
+
+module Gapic
+  module Rest
+    module ResumableUpload
+      ##
+      # @private
+      # Configuration members shared by {StartUploadConfig} and {ResumeUploadConfig}, in the order both
+      # definitions splat them.
+      #
+      # The two config types are deliberately *flat*: {Core}, {Rules} and {Driver} read every member
+      # straight off `config`. Nesting the shared members inside a common object would turn every
+      # `config.upload_size` into `config.common.upload_size` at some thirty call sites for no behavioural
+      # gain, so they are spliced into each `Data.define` instead.
+      #
+      # * `stream` [IO] Binary input stream to upload. Required.
+      # * `upload_size` [Integer, nil] Total upload bytes if known upfront.
+      # * `content_type` [String, nil] MIME type of uploaded media.
+      # * `timeout` [Numeric, nil] Total upload timeout in seconds (zero or negative is treated as nil).
+      # * `control_plane_retry_policy` [Gapic::Common::RetryPolicy, Hash, nil] Retry policy for control
+      #   commands (query, cancel).
+      # * `data_plane_retry_policy` [Gapic::Common::RetryPolicy, Hash, nil] Retry policy for data commands
+      #   (upload, finalize).
+      # * `on_progress` [Proc, nil] Callback invoked as `->(progress)` with a {Progress} instance.
+      #
+      # Every retry policy member, here and in the per-run configs, follows the same convention: a
+      # {Gapic::Common::RetryPolicy} replaces the default policy outright, while a Hash overrides only the
+      # settings it names and leaves the remaining defaults — including retry codes and predicates — in place.
+      #
+      COMMON_MEMBERS = [
+        :stream,
+        :upload_size,
+        :content_type,
+        :timeout,
+        :control_plane_retry_policy,
+        :data_plane_retry_policy,
+        :on_progress
+      ].freeze
+
+      ##
+      # @private
+      # Header names a caller may not use in `initial_headers`, lowercased for comparison.
+      #
+      # These five headers are protocol machinery the driver owns: the protocol identifier, the command
+      # verb, the byte offset, and the content descriptors derived from `content_type` and `upload_size`.
+      # `x-goog-upload-offset` is included for completeness even though initiation never sets an offset:
+      # supplying an offset at initiation is meaningless and indicates a confused caller. Pass-through
+      # headers such as `X-Goog-Upload-Header-Content-Disposition` remain permitted.
+      #
+      # See `Driver#start_headers`, which builds the initiation headers this list protects.
+      #
+      # @return [Array<String>]
+      RESERVED_INITIAL_HEADERS = [
+        "x-goog-upload-protocol",
+        "x-goog-upload-command",
+        "x-goog-upload-offset",
+        "x-goog-upload-header-content-type",
+        "x-goog-upload-header-content-length"
+      ].freeze
+
+      ##
+      # @private
+      # Immutable configuration for a run that initiates a new upload session, i.e.
+      # {Gapic::ResumableUpload#start}.
+      #
+      # Carries {COMMON_MEMBERS} plus the members only an initiating run uses.
+      #
+      # @!attribute [r] initial_url
+      #   @return [String] Initial endpoint URI for session initiation
+      # @!attribute [r] initial_body
+      #   @return [String, nil] Request payload for session initiation
+      # @!attribute [r] initial_headers
+      #   @return [Hash<String, String>] Additional headers for initiation, merged over the driver's
+      #     own headers. Keys in {RESERVED_INITIAL_HEADERS} are rejected in any casing; use
+      #     `content_type` and `upload_size` to shape those.
+      # @!attribute [r] chunk_size
+      #   @return [Integer, nil] Requested chunk size in bytes, aligned to the granularity the server
+      #     reports during initiation. A resumed run takes its chunk size from {ResumeUploadConfig}.
+      # @!attribute [r] start_retry_policy
+      #   @return [Gapic::Common::RetryPolicy, Hash, nil] Retry policy for session initiation
+      #
+      StartUploadConfig = Data.define(
+        *COMMON_MEMBERS,
+        :initial_url,
+        :initial_body,
+        :initial_headers,
+        :chunk_size,
+        :start_retry_policy
+      ) do
+        ##
+        # @private
+        # Initializes a new upload configuration.
+        #
+        # @param initial_url [String] Initial endpoint URI for session initiation
+        # @param stream [IO] Binary input stream to upload
+        # @param initial_body [String, nil] Request payload for session initiation
+        # @param initial_headers [Hash<String, String>] Additional headers for initiation. Keys in
+        #   {RESERVED_INITIAL_HEADERS} are rejected in any casing; use `content_type` and `upload_size`
+        #   to shape those.
+        # @param upload_size [Integer, nil] Total upload bytes if known upfront
+        # @param chunk_size [Integer, nil] Requested chunk size in bytes
+        # @param content_type [String, nil] MIME type of uploaded media
+        # @param timeout [Numeric, nil] Total upload timeout in seconds (zero/negative values treated as nil)
+        # @param start_retry_policy [Gapic::Common::RetryPolicy, Hash, nil] Retry policy for session initiation
+        # @param control_plane_retry_policy [Gapic::Common::RetryPolicy, Hash, nil] Retry policy for control commands
+        # @param data_plane_retry_policy [Gapic::Common::RetryPolicy, Hash, nil] Retry policy for data commands
+        # @param on_progress [Proc, nil] Callback invoked as `->(progress)` with a {Progress} instance
+        # @raise [ArgumentError] If required arguments are missing or invalid
+        #
+        def initialize initial_url:,
+                       stream:,
+                       initial_body: nil,
+                       initial_headers: {},
+                       upload_size: nil,
+                       chunk_size: nil,
+                       content_type: nil,
+                       timeout: nil,
+                       start_retry_policy: nil,
+                       control_plane_retry_policy: nil,
+                       data_plane_retry_policy: nil,
+                       on_progress: nil
+          raise ArgumentError, "initial_url is required" if initial_url.nil? || initial_url.to_s.strip.empty?
+          raise ArgumentError, "stream is required" if stream.nil?
+          reserved = (initial_headers || {}).keys.find do |key|
+            RESERVED_INITIAL_HEADERS.include? key.to_s.downcase
+          end
+          if reserved
+            raise ArgumentError,
+                  "initial_headers must not set protocol header #{reserved.inspect}; " \
+                  "use content_type and upload_size instead"
+          end
+
+          super(
+            initial_url:                initial_url,
+            initial_body:               initial_body,
+            initial_headers:            initial_headers || {},
+            stream:                     stream,
+            upload_size:                upload_size,
+            chunk_size:                 chunk_size,
+            content_type:               content_type,
+            timeout:                    timeout,
+            start_retry_policy:         start_retry_policy,
+            control_plane_retry_policy: control_plane_retry_policy,
+            data_plane_retry_policy:    data_plane_retry_policy,
+            on_progress:                on_progress
+          )
+        end
+      end
+
+      ##
+      # @private
+      # Immutable configuration for a run that resumes an existing upload session, i.e.
+      # {Gapic::ResumableUpload#resume}.
+      #
+      # Carries {COMMON_MEMBERS} plus the upload URL and chunk size the earlier run established. There is
+      # no `start_retry_policy` here: a resumed run issues no initiation request, so the member would
+      # always be dead.
+      #
+      # @!attribute [r] upload_url
+      #   @return [String] Session upload URL returned by the upload backend
+      # @!attribute [r] chunk_size
+      #   @return [Integer] Explicit chunk size in bytes (must be a positive integer). Server granularity is
+      #     reported only during initiation, which a resumed run skips, so the size is carried forward from
+      #     the earlier run rather than re-negotiated.
+      #
+      ResumeUploadConfig = Data.define(
+        *COMMON_MEMBERS,
+        :upload_url,
+        :chunk_size
+      ) do
+        ##
+        # @private
+        # Initializes a new upload resume configuration.
+        #
+        # @param upload_url [String] Session upload URL
+        # @param chunk_size [Integer] Explicit chunk size in bytes (must be a positive integer)
+        # @param stream [IO] Binary input stream to upload
+        # @param upload_size [Integer, nil] Total upload bytes if known upfront
+        # @param content_type [String, nil] MIME type of uploaded media
+        # @param timeout [Numeric, nil] Total upload timeout in seconds (zero/negative values treated as nil)
+        # @param control_plane_retry_policy [Gapic::Common::RetryPolicy, Hash, nil] Retry policy for control commands
+        # @param data_plane_retry_policy [Gapic::Common::RetryPolicy, Hash, nil] Retry policy for data commands
+        # @param on_progress [Proc, nil] Callback invoked as `->(progress)` with a {Progress} instance
+        # @raise [ArgumentError] If required arguments are missing or invalid
+        #
+        def initialize upload_url:,
+                       chunk_size:,
+                       stream:,
+                       upload_size: nil,
+                       content_type: nil,
+                       timeout: nil,
+                       control_plane_retry_policy: nil,
+                       data_plane_retry_policy: nil,
+                       on_progress: nil
+          raise ArgumentError, "upload_url is required" if upload_url.nil? || upload_url.to_s.strip.empty?
+          unless chunk_size.is_a?(Integer) && chunk_size.positive?
+            raise ArgumentError, "chunk_size must be a positive integer"
+          end
+          raise ArgumentError, "stream is required" if stream.nil?
+
+          super(
+            upload_url:                 upload_url,
+            chunk_size:                 chunk_size,
+            stream:                     stream,
+            upload_size:                upload_size,
+            content_type:               content_type,
+            timeout:                    timeout,
+            control_plane_retry_policy: control_plane_retry_policy,
+            data_plane_retry_policy:    data_plane_retry_policy,
+            on_progress:                on_progress
+          )
+        end
+      end
+
+      ##
+      # Immutable progress snapshot passed to the `on_progress` callback.
+      #
+      # The `on_progress` callback runs synchronously on the same thread as the upload protocol
+      # and must not block. Any exception raised inside the callback aborts the upload session
+      # and propagates out of {Gapic::ResumableUpload#start} or {Gapic::ResumableUpload#resume}.
+      #
+      # @!attribute [r] phase
+      #   @return [Symbol] Current upload phase, one of {Progress::PHASES}
+      # @!attribute [r] bytes_uploaded
+      #   @return [Integer] Cumulative bytes acknowledged by the server. Note that this is the
+      #     server-confirmed offset and is not guaranteed to be monotonic — a server rewind during
+      #     recovery can decrease this value.
+      # @!attribute [r] total_bytes
+      #   @return [Integer, nil] Total upload size in bytes if known, or `nil`. Always set on the
+      #     `:completed` phase — the total is known once the transfer finishes, even when `upload_size`
+      #     was not supplied upfront.
+      #
+      Progress = Data.define(
+        :phase,
+        :bytes_uploaded,
+        :total_bytes
+      ) do
+        ##
+        # Initializes a new progress snapshot.
+        #
+        # @param phase [Symbol] Current upload phase, one of {Progress::PHASES}
+        # @param bytes_uploaded [Integer] Cumulative bytes acknowledged by the server
+        # @param total_bytes [Integer, nil] Total upload size in bytes if known, or nil
+        # @raise [ArgumentError] If the phase is not one of {Progress::PHASES}
+        #
+        def initialize phase:, bytes_uploaded:, total_bytes: nil
+          # Must use `self.class::` to access constants from the class scope
+          unless self.class::PHASES.include? phase
+            raise ArgumentError, "Invalid phase: #{phase.inspect}. Expected one of #{self.class::PHASES.inspect}"
+          end
+
+          super(
+            phase:          phase,
+            bytes_uploaded: bytes_uploaded,
+            total_bytes:    total_bytes
+          )
+        end
+      end
+
+      ##
+      # Allowed lifecycle phases for an upload session.
+      #
+      # A callback observes `:initiating`, `:uploading`, `:recovering`, `:finalizing` and `:completed`.
+      # `:cancelling` is reserved: cancellation is not exposed on {Gapic::ResumableUpload}, so no phase
+      # with that value is currently emitted.
+      #
+      # @return [Array<Symbol>]
+      Progress::PHASES = [:initiating, :uploading, :recovering, :finalizing, :cancelling, :completed].freeze
+
+      ##
+      # Immutable handle containing parameters necessary to resume an in-progress upload session.
+      # These parameters are provided by the server and can be persisted to resume the upload
+      # at a later time.
+      #
+      # @!attribute [r] upload_url
+      #   @return [String] Upload session URL provided by the server
+      # @!attribute [r] chunk_size
+      #   @return [Integer] Effective chunk size in bytes
+      #
+      ResumeHandle = Data.define(
+        :upload_url,
+        :chunk_size
+      ) do
+        ##
+        # Initializes a new resume handle.
+        #
+        # @param upload_url [String] Upload session URL provided by the server
+        # @param chunk_size [Integer] Effective chunk size in bytes
+        #
+        def initialize upload_url:, chunk_size:
+          super(
+            upload_url: upload_url,
+            chunk_size: chunk_size
+          )
+        end
+      end
+
+      ##
+      # @private
+      # Immutable state snapshot representing the current protocol progression.
+      #
+      # @!attribute [r] status
+      #   @return [Symbol] Protocol lifecycle status, one of {Rules::STATUSES}
+      # @!attribute [r] upload_url
+      #   @return [String, nil] Session upload URL returned by the upload backend
+      # @!attribute [r] offset
+      #   @return [Integer] Contiguous bytes acknowledged by server
+      # @!attribute [r] chunk_size
+      #   @return [Integer] Resolved effective chunk size in bytes
+      # @!attribute [r] chunk_granularity
+      #   @return [Integer, nil] Alignment modulus returned by server
+      # @!attribute [r] in_flight_length
+      #   @return [Integer] Byte length of in-flight chunk currently being transmitted
+      # @!attribute [r] last_error
+      #   @return [StandardError, nil] Terminal exception if in an error or rejected status
+      # @!attribute [r] recovery_offset
+      #   @return [Integer, nil] Server-confirmed offset when the open recovery episode began, or `nil` when no
+      #     episode is open. A recovery episode is the run of consecutive recovery attempts during which the
+      #     confirmed offset does not advance; every query in it after the first waits for the next backoff delay.
+      #     See `design/resumable_upload/implementation-guide.md` section 6.2.1.
+      #
+      State = Data.define(
+        :status,
+        :upload_url,
+        :offset,
+        :chunk_size,
+        :chunk_granularity,
+        :in_flight_length,
+        :last_error,
+        :recovery_offset
+      ) do
+        ##
+        # @private
+        # Initializes a protocol state snapshot.
+        #
+        # @param status [Symbol] Protocol lifecycle status, one of {Rules::STATUSES}
+        # @param upload_url [String, nil] Session upload URL
+        # @param offset [Integer] Contiguous bytes acknowledged by server
+        # @param chunk_size [Integer] Resolved effective chunk size in bytes
+        # @param chunk_granularity [Integer, nil] Alignment modulus returned by server
+        # @param in_flight_length [Integer] Byte length of in-flight chunk
+        # @param last_error [StandardError, nil] Terminal exception
+        # @param recovery_offset [Integer, nil] Offset the open recovery episode began at; `nil` if none is open
+        #
+        def initialize status: :initializing,
+                       upload_url: nil,
+                       offset: 0,
+                       chunk_size: Rules::DEFAULT_CHUNK_SIZE,
+                       chunk_granularity: nil,
+                       in_flight_length: 0,
+                       last_error: nil,
+                       recovery_offset: nil
+          super(
+            status:            status,
+            upload_url:        upload_url,
+            offset:            offset,
+            chunk_size:        chunk_size,
+            chunk_granularity: chunk_granularity,
+            in_flight_length:  in_flight_length,
+            last_error:        last_error,
+            recovery_offset:   recovery_offset
+          )
+        end
+      end
+
+      ##
+      # @private
+      # Immutable decision snapshot emitted by Rules.decide.
+      #
+      # @!attribute [r] from_status
+      #   @return [Symbol] The protocol status before the transition
+      # @!attribute [r] shape
+      #   @return [Symbol] The canonical event shape
+      # @!attribute [r] recipe
+      #   @return [Symbol] Selected transition recipe method name
+      # @!attribute [r] next_state
+      #   @return [State] The new protocol state snapshot after transition
+      # @!attribute [r] instructions
+      #   @return [Array<Object>] Emitted instructions for the Driver
+      #
+      Decision = Data.define(
+        :from_status,
+        :shape,
+        :recipe,
+        :next_state,
+        :instructions
+      ) do
+        ##
+        # @private
+        # Initializes a decision snapshot.
+        #
+        # @param from_status [Symbol] The protocol status before the transition
+        # @param shape [Symbol] The canonical event shape
+        # @param recipe [Symbol] Selected transition recipe method name
+        # @param next_state [State] Resulting protocol state snapshot
+        # @param instructions [Array<Object>] Emitted instructions for the Driver
+        #
+        def initialize from_status:, shape:, recipe:, next_state:, instructions: []
+          super(
+            from_status:  from_status,
+            shape:        shape,
+            recipe:       recipe,
+            next_state:   next_state,
+            instructions: instructions
+          )
+        end
+      end
+    end
+  end
+end
+
+# rubocop:enable Metrics/ModuleLength