Prune the comments this branch added

Per AGENTS.md: drop the ones that restate the name below them, and the
clauses that narrate the change or defend a choice against an edit nobody
was going to make. What's left is the why a reader would otherwise get
wrong - token_time flooring so a blank token reads as expired, the sent-at
stamp being written by the caller rather than the delivering job, the
self-posting confirm form defeating link scanners.

find_b_param_for_confirmation's had grown to five lines when the deleted
service method's comment folded into it; now it leads with why it isn't
find_b_param.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: sethherr

app/components/emails/partial_register_confirmation/component.rb

@@ -15,8 +15,6 @@ def expiration_days
 
       def color_and_brand = @b_param.color_and_brand
 
-      # The confirmation token only ever exists in this email - never rendered
-      # anywhere the registrant's browser could have shown it first
       def tokenized_url
         confirm_register_url(b_param_token: @b_param.id_token,
           confirmation_token: @b_param.email_confirmation_token)

app/controllers/concerns/sessionable.rb

@@ -37,9 +37,8 @@ def sign_in_and_redirect(user, signed_up: false)
     end
   end
 
-  # Everything signing in does apart from deciding where to go next - so a flow with
-  # its own destination (the register flow's confirmation link) lands in the same
-  # session state as every other sign in
+  # Everything signing in does apart from deciding where to go next, for flows with
+  # a destination of their own
   def sign_in_user(user)
     confirm_user_from_claim_token(user)
     session[:last_seen] = Time.current

app/controllers/register_controller.rb

@@ -7,7 +7,7 @@ class RegisterController < ApplicationController
   before_action -> { find_b_param(build: true) }, only: %i[create]
   # The emailed link resumes a registration the session knows nothing about
   before_action :find_b_param_for_confirmation, only: %i[confirm confirm_email]
-  # confirm renders a form and nothing else - neither is read before it posts itself
+  # confirm renders a self-posting form and nothing else, so it reads neither
   before_action :assign_organization, except: %i[new confirm]
   before_action :find_registration_sequence, except: %i[new confirm]
   before_action :redirect_finished, only: %i[create update acknowledge]
@@ -62,8 +62,7 @@ def create
     if @b_param.errors.any?
       render Register::Step1::Component.new(b_param: @b_param, sequence: @registration_sequence, current_user:), status: :unprocessable_entity
     elsif @b_param.save
-      # Anonymous registrations need the address proven before there's a bike, and step 2
-      # says the link is on its way - so it goes out here, not at the end
+      # Step 2 says the link is on its way, so it goes out here rather than at the end
       BikeServices::Register.send_confirmation_email(@b_param)
       redirect_to step_path(2)
     else
@@ -109,8 +108,8 @@ def confirm
     render Register::Confirm::Component.new(b_param: @b_param, token: params[:confirmation_token])
   end
 
-  # The confirmation itself: the address is proven, so the registration has an account
-  # behind it - created here if this is their first registration
+  # The confirmation itself - the proven address gets an account, created here if
+  # this is their first registration
   def confirm_email
     # Single use, so a second click has nothing left to do - the first one signed them in
     return redirect_to_current_step if @b_param.email_confirmed?
@@ -151,15 +150,13 @@ def complete_registration
     BikeServices::Register.claim_creator(@b_param, current_user)
     bike = BikeServices::Register.create_bike_if_ready(@b_param,
       sequence: @registration_sequence, ip_address: forwarded_ip_address)
-    # Everything is saved on the b_param - the bike is created once the
-    # confirmation link from the registration email is clicked
+    # No bike yet - everything stays on the b_param until the emailed link is clicked
     return redirect_to_current_step if bike.blank?
 
     redirect_after_bike_creation(bike)
   end
 
-  # The account the confirmed address belongs to, created if it doesn't have one yet -
-  # passwordless, so it gets the same offer to set one as every other emailed sign in
+  # The account the confirmed address belongs to, created if it doesn't have one yet
   def sign_in_confirmed_user
     user, signed_up = UserServices::PasswordlessCreator.find_or_create(@b_param.owner_email)
     if user.blank? || user.banned?
@@ -203,11 +200,9 @@ def find_registration_sequence
     @registration_sequence = BikeServices::Register.registration_sequence(@b_param)
   end
 
-  # The emailed link carries the registration's token, so it resumes from any browser.
-  # Nothing is put in the session here - the token hasn't been checked yet, and dropping
-  # a registration already underway in this browser isn't the link's to do.
-  # No window like find_token's: the confirmation token expires on its own clock, and
-  # finding the registration is what lets an expired link say so rather than dead-end
+  # Not find_b_param: the emailed token authorizes this, not the session, and an expired
+  # link has to find its registration to say so rather than dead-end. Nothing is written
+  # to the session - the token hasn't been checked yet
   def find_b_param_for_confirmation
     token = params[:b_param_token]
     @b_param = BParam.find_by(id_token: token) if token.present?

app/jobs/email/partial_registration_job.rb

@@ -1,10 +1,9 @@
 # frozen_string_literal: true
 
 module Email
-  # The emails a registration sends before it has a bike, and so before there's an account
-  # to notify - the address itself is all that's been entered, so every one of them runs
-  # the domain check first. kind names both the notification and the mailer method, and
-  # defaults so jobs enqueued before it existed still run
+  # The emails a registration sends before it has a bike - only an address has been
+  # entered, so every one runs the domain check first. kind names both the notification
+  # and the mailer method, and defaults for jobs enqueued before it took one
   class PartialRegistrationJob < ApplicationJob
     sidekiq_options queue: "notify", retry: 3
 

app/mailers/organized_mailer.rb

@@ -13,7 +13,6 @@ def partial_registration(b_param)
     b_param_mail(b_param, Emails::PartialRegistration::Component.new(b_param:), tag: __callee__)
   end
 
-  # The register flow's confirmation link - proves the address, and signs them in
   def partial_register_confirmation(b_param)
     b_param_mail(b_param, Emails::PartialRegisterConfirmation::Component.new(b_param:), tag: __callee__)
   end
@@ -118,8 +117,7 @@ def impound_claim_approved_or_denied(impound_claim)
 
   private
 
-  # The emails a registration sends before it has a bike - addressed to whoever
-  # entered it, and subjected by the mailer method's own name
+  # Addressed to whoever entered the registration, and subjected by the caller's own name
   def b_param_mail(b_param, component, tag:)
     @organization = b_param.creation_organization
     mail(reply_to: reply_to,

app/models/b_param.rb

@@ -72,8 +72,8 @@ class BParam < ApplicationRecord
     stolen
     street
   ].freeze
-  # How long a register flow registration resumes by token - and so how long its emailed
-  # confirmation link works, since a link outliving the registration it resumes is a dead end
+  # How long a register flow registration resumes by token, and so how long its
+  # emailed confirmation link works
   TOKEN_EXPIRATION = 90.days
   mount_uploader :image, ImageUploaderBackgrounded
   process_in_background :image, CarrierWaveProcessJob # Defer version generation so large uploads don't hit the 30s Rack::Timeout
@@ -100,7 +100,6 @@ class BParam < ApplicationRecord
   scope :without_bike_values, -> { bike_params_empty.or(where(origin: "register_flow").where("(params -> 'bike' -> 'manufacturer_id') IS NULL")) }
   # Tokenized lookups resume registrations for up to a month
   scope :recent_with_token, ->(toke) { where(id_token: toke).where("created_at >= ?", Time.current - 1.month) }
-  # The register flow's own (longer) window - see TOKEN_EXPIRATION
   scope :unexpired_with_token, ->(toke) { where(id_token: toke).where("created_at >= ?", Time.current - TOKEN_EXPIRATION) }
   scope :unprocessed_image, -> { where(image_processed: false).where.not(image: nil) }
   scope :with_cycle_type, -> { bike_params.where("(params -> 'bike' -> 'cycle_type') IS NOT NULL") }
@@ -448,8 +447,7 @@ def email_unconfirmed?
     owner_email.present? && !email_confirmed?
   end
 
-  # Spends the confirmation token, so a forwarded email can't sign anyone in later.
-  # creator_id: assigned in the same write, the registration having proven who it's for
+  # Spends the confirmation token, so a forwarded email can't sign anyone in later
   def confirm_email!(creator_id: nil)
     return true if email_confirmed?
 
@@ -458,15 +456,13 @@ def confirm_email!(creator_id: nil)
         .except("email_confirmation_token", "email_confirmation_email"))
   end
 
-  # The emailed link's credential. Distinct from id_token, which is in the registrant's
-  # own URL before any email goes out - only a secret that lived solely in the email
-  # proves the address received it. Nil once owner_email is edited to a different
-  # address, since all the token proves is that the one it was mailed to received it
+  # Distinct from id_token, which is in the registrant's own URL before any email goes
+  # out - only a secret that lived solely in the email proves the address received it,
+  # and only for the address it was mailed to
   def email_confirmation_token
     params["email_confirmation_token"] if email_confirmation_email == EmailNormalizer.normalize(owner_email)
   end
 
-  # The address the token in hand was mailed to
   def email_confirmation_email
     params["email_confirmation_email"]
   end
@@ -476,8 +472,8 @@ def email_confirmation_token_expired?
     SecurityTokenizer.token_time(email_confirmation_token) < Time.current - TOKEN_EXPIRATION
   end
 
-  # Resending reuses an unexpired token, so the link already in their inbox keeps working.
-  # The stamp is what rate limits resends, so it's rewritten either way
+  # Reuses an unexpired token, so the link already in their inbox keeps working - but
+  # re-stamps either way, since the stamp is what rate limits resends
   def generate_email_confirmation_token!
     token = email_confirmation_token_expired? ? SecurityTokenizer.new_token : email_confirmation_token
     update(params: params.merge("email_confirmation_token" => token,
@@ -486,8 +482,8 @@ def generate_email_confirmation_token!
     token
   end
 
-  # When a link last went out - written by whatever asked for the send, rather than by
-  # the job that delivers it, so it rate limits even when delivery drops the email
+  # Written by whatever asked for the send rather than by the job that delivers it,
+  # so it rate limits even when delivery drops the email
   def email_confirmation_sent_at
     Binxtils::TimeParser.parse(params["email_confirmation_sent_at"])
   end
@@ -682,7 +678,6 @@ def mnfg_name
     Manufacturer.calculated_mnfg_name(manufacturer, bike["manufacturer_other"])
   end
 
-  # What the registration's emails call the bike - everything entered that names it
   def color_and_brand
     [primary_frame_color.presence, mnfg_name].compact.join(" ")
   end

app/services/bike_services/register.rb

@@ -7,7 +7,6 @@ module Register
 
     # Step "3" is the first of the e-vehicle acknowledgment pages
     ACKNOWLEDGMENT_OFFSET = 3
-    # How often a registration will email its confirmation link
     CONFIRMATION_EMAIL_INTERVAL = 5.minutes
 
     # The token's registration when step 1 was never submitted (redirecting into
@@ -134,19 +133,16 @@ def finished?(b_param, sequence:)
       ready_for_bike?(b_param, sequence:) && !creator_available?(b_param)
     end
 
-    # A link went to the address and nothing has proven it yet - what the steps tell
-    # the registrant to expect, and what makes their bike once they click it.
-    # user: whoever is looking, since being signed in as the address settles it too
+    # user: being signed in as the address settles it, without any link being clicked
     def confirmation_email_pending?(b_param, user: nil)
       return false if b_param.self_made?(user)
 
       b_param.email_unconfirmed? && !creator_available?(b_param)
     end
 
     # Anonymous registrations can't create a bike - Ownership needs a creator - so the
-    # address is emailed a link that proves it, makes an account and signs them in
-    # A resend can be asked for by anyone holding the registration's token, so the address
-    # it was entered for is only emailed this often
+    # address is emailed a link that proves it. Rate limited: anyone holding the
+    # registration's token can ask for a resend
     def send_confirmation_email(b_param)
       return false unless confirmation_email_pending?(b_param)
       return false if b_param.email_confirmation_sent_at.to_i > (Time.current - CONFIRMATION_EMAIL_INTERVAL).to_i
@@ -186,8 +182,6 @@ def claim_creator(b_param, user)
       b_param.update(creator_id: user.id)
     end
 
-    # The bike everything has been waiting on - nil until the registration is complete
-    # and has a creator, which is what the confirmation link finally supplies
     def create_bike_if_ready(b_param, sequence:, ip_address:)
       return nil if b_param.with_bike? || !creator_available?(b_param) ||
         !ready_for_bike?(b_param, sequence:)
@@ -207,7 +201,6 @@ def create_bike(b_param, ip_address:)
     # private below here
     #
 
-    # Everything's entered - all that's missing is a creator
     def ready_for_bike?(b_param, sequence:)
       details_completed?(b_param) && acknowledged?(b_param, sequence:)
     end

app/services/user_services/passwordless_creator.rb

@@ -6,7 +6,7 @@ module UserServices
   module PasswordlessCreator
     extend Functionable
 
-    # Returns the user and whether this call is what created them - confirming saves
+    # Returns whether this call created them alongside the user - confirming saves
     # again, so previously_new_record? can't answer that by the time it returns
     def find_or_create(email)
       return [nil, false] if email.blank?

db/seeds/seed_organized_emails.rb

@@ -235,9 +235,8 @@
   puts "  Created transferred bike ##{bike.id}"
 end
 
-# --- Registrations that never became bikes: the two emails a b_param sends.
-# Both are mid-flow states nothing else seeds, since every other seeded b_param
-# is only an input to BikeServices::Creator and ends up with a created bike. ---
+# --- Registrations that never became bikes: mid-flow states nothing else seeds,
+# since every other seeded b_param ends up with a created bike ---
 if BParam.partial_registrations.none?
   b_param = BParam.create!(origin: "embed_partial", params: {
     bike: {
@@ -251,10 +250,8 @@
   puts "  Created partial registration b_param ##{b_param.id}"
 end
 
-# The register flow parks an anonymous registration here until the emailed link proves
-# the address - generate_email_confirmation_token! is what mints the credential.
-# Brakebills so the preview renders its snippets, though a registration for an
-# organization with an auto_user already has a creator and never sends this
+# Brakebills so the preview renders its snippets, though an organization with an
+# auto_user already has a creator and would never send this
 if BParam.where(origin: "register_flow").where("(params -> 'email_confirmation_token') IS NOT NULL").none?
   b_param = BParam.create!(origin: "register_flow", params: {
     bike: {

spec/integration/registration/register_spec.rb

@@ -184,8 +184,7 @@ def confirmation_link
     bike = Bike.last
     expect(bike).to have_attributes(owner_email:, serial_number: "made_without_serial",
       status: "status_stolen", frame_model: "Marlin 7")
-    # Signed in as the account the link made - to anyone else this page would say the
-    # registration is the owner's to claim
+    # Signed in as the account the link made - to anyone else it reads as unclaimed
     expect(page).to have_content("keep watch")
 
     # An account nobody signed up for, so the terms are the first thing it's asked