@@ -41,8 +41,6 @@ def self.wait_until_resolved(action_attempt, client, timeout: nil, polling_inter
 
       raise Seam::ActionAttemptFailedError.new(action_attempt) if action_attempt.status == "error"
 
-      # Neither pending, success, nor error: a status added after this release.
-      # Waiting cannot conclude, so say so rather than pass it off as a success.
       unless action_attempt.status == "success"
         raise Seam::ActionAttemptUnknownStatusError.new(action_attempt, action_attempt.status)
       end
 
@@ -110,17 +110,13 @@ def self.date_accessor(*attrs)
 
       protected
 
-      # Reading a date never raises: a value the API sends in an unexpected shape
-      # reads as nil rather than taking down an otherwise usable resource.
       def parse_datetime(value)
         Time.parse(value)
       rescue ArgumentError, TypeError
         nil
       end
 
       def process_data_attributes(data)
-        # A response that is not an object at all still yields a usable resource
-        # with every attribute unset, rather than raising from #each.
         return unless data.is_a?(Hash)
 
         data.each do |key, value|
 
@@ -26,10 +26,7 @@ def initialize(action_attempt)
   end
 
   # Raised when an attempt reports a status this SDK version does not know.
-  #
-  # Waiting promises to return a succeeded attempt or raise, and an unrecognized
-  # status supports neither: reporting success would claim the action completed
-  # when the SDK cannot tell. Read #action_attempt to inspect the status.
+  # Waiting can neither return it as a success nor call it a failure.
   class ActionAttemptUnknownStatusError < ActionAttemptError
     attr_reader :status
 
 
@@ -2,18 +2,16 @@
 
 require "svix/webhook"
 require "svix/errors"
-# svix/webhook calls Svix.secure_compare but does not require the file defining
-# it, so verification raises NoMethodError unless something else loaded it first.
+# svix/webhook calls Svix.secure_compare without requiring the file defining it.
 require "svix/util"
 require_relative "base_resource"
 require_relative "resources/event"
 
 module Seam
   WebhookVerificationError = Svix::WebhookVerificationError
 
-  # Raised when a payload carries a valid signature but cannot be read as a Seam
-  # event. Distinct from WebhookVerificationError: the sender is genuinely Seam,
-  # so the payload will never become readable and retrying it cannot help.
+  # Raised when a payload is correctly signed but is not a Seam event. Unlike
+  # WebhookVerificationError, retrying it can never help.
   class InvalidWebhookPayloadError < StandardError; end
 
   class Webhook
@@ -26,17 +24,13 @@ def initialize(secret)
     #
     # @return [Seam::Resources::SeamEvent]
     # @raise [Seam::WebhookVerificationError] When the signature does not match.
-    #   Respond with an error status so the sender retries.
-    # @raise [Seam::InvalidWebhookPayloadError] When the signature matches but the
-    #   body is not a Seam event. Report it rather than letting the sender retry.
+    # @raise [Seam::InvalidWebhookPayloadError] When it does but the body is not an event.
     def verify(payload, headers)
       normalized_headers = headers.transform_keys(&:downcase)
 
       begin
         event_data = @webhook.verify(payload, normalized_headers)
       rescue JSON::ParserError => e
-        # The signature already checked out, so this came from Seam but is
-        # permanently unreadable.
         raise InvalidWebhookPayloadError, "The verified webhook payload is not valid JSON: #{e.message}"
       end
 
@@ -49,8 +43,7 @@ def verify(payload, headers)
 
     private
 
-    # Svix parses with symbolize_names, so read either key shape rather than
-    # depending on how the payload happened to be decoded.
+    # Svix parses with symbolize_names, so accept either key shape.
     def seam_event?(data)
       return false unless data.is_a?(Hash)
 
 
@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-# Seam adds event types, action types, and error codes between SDK releases, so a
-# payload this version does not recognize has to stay readable rather than cost
-# the caller the whole response. Each example pins one shape that used to raise.
+# Reading a response must not fail on the shape of the payload.
 RSpec.describe "total parsing" do
   it "does not raise when the payload is not an object" do
     resource = Seam::Resources::Device.load_from_response(42)
@@ -38,7 +36,6 @@
     expect(device.errors.first.error_code).to eq("brand_new")
   end
 
-  # Reading a date must not take down an otherwise usable resource.
   it "reads a malformed timestamp as nil" do
     device = Seam::Resources::Device.load_from_response(
       "device_id" => "device_1", "created_at" => "not a timestamp"
@@ -65,8 +62,6 @@
 end
 
 RSpec.describe Seam::ActionAttemptUnknownStatusError do
-  # Waiting promises a succeeded attempt or a raise. An unrecognized status
-  # supports neither, and returning it would claim the action completed.
   it "is raised rather than returning an unresolved attempt as a success" do
     attempt = Seam::Resources::ActionAttempt.load_from_response(
       "action_attempt_id" => "attempt_1",
 
@@ -4,8 +4,7 @@
 require "openssl"
 require "base64"
 
-# Signs a payload the way Svix does, so these specs exercise the real
-# verification path rather than stubbing it out.
+# Signs a payload the way Svix does, so these specs exercise real verification.
 def signed_headers(secret, payload, msg_id: "msg_1", timestamp: Time.now.to_i)
   key = Base64.decode64(secret.delete_prefix("whsec_"))
   signature = Base64.strict_encode64(
@@ -52,8 +51,7 @@ def verify(payload, headers: nil)
     expect(event.event_type).to eq("future.thing")
   end
 
-  # Svix parses webhook payloads with symbolize_names, so the raw payload reachable
-  # through #data carries symbol keys here, where an HTTP response carries strings.
+  # Svix symbolizes keys, so #data carries symbols here and strings over HTTP.
   it "exposes the full payload of an unknown event through data" do
     payload = JSON.generate(
       event_id: "event_1",
@@ -74,9 +72,6 @@ def verify(payload, headers: nil)
       .to raise_error(Seam::WebhookVerificationError)
   end
 
-  # A signed but unreadable body is permanently unreadable: the sender is
-  # genuinely Seam, so retrying can never help. It must not look like a
-  # verification failure, which is the signal to retry.
   describe "signed but unreadable payloads" do
     it "raises for a body that is not JSON" do
       expect { verify("{not json") }