sec_id 6.0.0 → 7.0.0

data/lib/sec_id/base.rb

@@ -8,28 +8,28 @@ module SecID
   # - ID_REGEX constant with named capture groups for parsing
   # - initialize method that calls parse and extracts components
   #
-  # Subclasses with check digits should also include the Checkable concern,
-  # which provides check-digit validation, calculation, and restoration.
+  # Subclasses with checksum should also include the Checkable concern,
+  # which provides checksum validation, calculation, and restoration.
   #
-  # @example Implementing a check-digit identifier
+  # @example Implementing a checksum identifier
   #   class MyIdentifier < Base
   #     include Checkable
   #
-  #     ID_REGEX = /\A(?<identifier>[A-Z]{6})(?<check_digit>\d)?\z/x
+  #     ID_REGEX = /\A(?<identifier>[A-Z]{6})(?<checksum>\d)?\z/x
   #
   #     def initialize(id)
   #       parts = parse(id)
   #       @identifier = parts[:identifier]
-  #       @check_digit = parts[:check_digit]&.to_i
+  #       @checksum = parts[:checksum]&.to_i
   #     end
   #
-  #     def calculate_check_digit
+  #     def calculate_checksum
   #       validate_format_for_calculation!
   #       mod10(some_algorithm)
   #     end
   #   end
   #
-  # @example Implementing a non-check-digit identifier
+  # @example Implementing a non-checksum identifier
   #   class SimpleId < Base
   #     ID_REGEX = /\A(?<identifier>[A-Z]{6})\z/x
   #
@@ -46,10 +46,26 @@ module SecID
     # @return [String] the original input after normalization (stripped and uppercased)
     attr_reader :full_id
 
-    # @return [String, nil] the main identifier portion (without check digit)
+    # @return [String, nil] the main identifier portion (without checksum)
     attr_reader :identifier
 
     class << self
+      # The type's registry symbol: `SecID[SecID::ISIN.type_key] == SecID::ISIN`.
+      #
+      # @return [Symbol] the registry key (e.g. :isin, :cusip)
+      def type_key = @type_key ||= short_name.downcase.to_sym
+
+      # Composite sort key ranking detection specificity: checksum types first,
+      # then narrower length range, then registration order. A class the registry
+      # never saw sorts last.
+      #
+      # @api private
+      # @return [Array] frozen [checksum rank, length specificity, registration order]
+      def detection_priority
+        @detection_priority ||=
+          [has_checksum? ? 0 : 1, length_specificity, SecID.identifiers.index(self) || Float::INFINITY].freeze
+      end
+
       # @return [String] the unqualified class name (e.g. "ISIN", "CUSIP")
       def short_name = @short_name ||= name.split('::').last
 
@@ -73,11 +89,19 @@ module SecID
       # @return [String] a representative valid identifier string
       def example = self::EXAMPLE
 
-      # @return [Boolean] true if this identifier type uses a check digit
-      def has_check_digit?
-        return @has_check_digit if defined?(@has_check_digit)
+      # @return [Boolean] true if this identifier type uses a checksum
+      def has_checksum?
+        return @has_checksum if defined?(@has_checksum)
+
+        @has_checksum = ancestors.include?(SecID::Checkable)
+      end
 
-        @has_check_digit = ancestors.include?(SecID::Checkable)
+      # @deprecated Use {.has_checksum?}. Kept as a v7 bridge; removed in v8.
+      #
+      # @return [Boolean]
+      def has_check_digit?
+        SecID::Deprecation.warn(old: 'has_check_digit?', new: 'has_checksum?')
+        has_checksum?
       end
     end
 
@@ -114,11 +138,11 @@ module SecID
     # @return [Hash] hash with :type, :full_id, :normalized, :valid, and :components keys
     def to_h
       {
-        type: self.class.short_name.downcase.to_sym,
+        type: self.class.type_key,
         full_id: full_id,
         normalized: valid? ? normalized : nil,
         valid: valid?,
-        components: components
+        components: components_with_deprecation_bridge
       }
     end
 
@@ -129,6 +153,20 @@ module SecID
       to_h
     end
 
+    # Exposes the parsed components for `case/in` destructuring. Validity is not part of
+    # the protocol: components of unparseable input are `nil`, and `SecID.parse` returning
+    # `nil` is the validity guard.
+    #
+    # @param _keys [Array<Symbol>, nil] the keys the pattern requests; ignored
+    # @return [Hash] the parsed components
+    #
+    # @example
+    #   case SecID.parse('US5949181045')
+    #   in SecID::ISIN[country_code:, nsin:] then [country_code, nsin]
+    #   in nil then :invalid
+    #   end #=> ['US', '594918104']
+    def deconstruct_keys(_keys) = components_with_deprecation_bridge
+
     protected
 
     # @return [String]
@@ -138,6 +176,17 @@ module SecID
 
     private
 
+    # Mirrors the canonical `:checksum` components key onto the deprecated `:check_digit`
+    # key for the v7 bridge, when a checksum is present. The mirror reads `:checksum`, so the
+    # deprecated `check_digit` reader never fires internally. Removed in v8 (revert `to_h` and
+    # `deconstruct_keys` to call `components` directly).
+    #
+    # @return [Hash] the parsed components, with `:check_digit` added when `:checksum` is present
+    def components_with_deprecation_bridge
+      parsed = components
+      parsed.key?(:checksum) ? parsed.merge(check_digit: parsed[:checksum]) : parsed
+    end
+
     # @return [Hash]
     def components
       {}

data/lib/sec_id/cei.rb

@@ -4,7 +4,7 @@ module SecID
   # CUSIP Entity Identifier (CEI) - a 10-character alphanumeric code that identifies
   # legal entities in the syndicated loan market.
   #
-  # Format: 1 alpha + 1 digit + 7 alphanumeric + 1 check digit
+  # Format: 1 alpha + 1 digit + 7 alphanumeric + 1 checksum
   #
   # @see https://www.cusip.com/identifiers.html
   #
@@ -28,7 +28,7 @@ module SecID
         (?<prefix>[A-Z])
         (?<numeric>[0-9])
         (?<entity_id>[A-Z0-9]{7}))
-      (?<check_digit>\d)?
+      (?<checksum>\d)?
     \z/x
 
     # @return [String, nil] the first character (alphabetic)
@@ -47,12 +47,12 @@ module SecID
       @prefix = cei_parts[:prefix]
       @numeric = cei_parts[:numeric]
       @entity_id = cei_parts[:entity_id]
-      @check_digit = cei_parts[:check_digit]&.to_i
+      @checksum = cei_parts[:checksum]&.to_i
     end
 
-    # @return [Integer] the calculated check digit (0-9)
+    # @return [Integer] the calculated checksum (0-9)
     # @raise [InvalidFormatError] if the CEI format is invalid
-    def calculate_check_digit
+    def calculate_checksum
       validate_format_for_calculation!
       mod10(luhn_sum_double_add_double(reversed_digits_single(identifier)))
     end
@@ -60,7 +60,7 @@ module SecID
     # Generates a random CEI body: 1 letter + 1 digit + 7 alphanumeric characters.
     #
     # @param random [Random] source of randomness
-    # @return [String] a 9-character CEI body without check digit
+    # @return [String] a 9-character CEI body without checksum
     def self.generate_body(random)
       "#{random_string(ALPHA, 1, random: random)}#{random_string(DIGITS, 1, random: random)}" \
         "#{random_string(ALPHANUMERIC, 7, random: random)}"
@@ -70,6 +70,6 @@ module SecID
     private
 
     # @return [Hash]
-    def components = { prefix:, numeric:, entity_id:, check_digit: }
+    def components = { prefix:, numeric:, entity_id:, checksum: }
   end
 end

data/lib/sec_id/cik.rb

@@ -4,7 +4,7 @@ module SecID
   # Central Index Key (CIK) - SEC identifier for entities filing with the SEC.
   # A 1-10 digit number that uniquely identifies entities in SEC systems.
   #
-  # @note CIK identifiers have no check digit and validation is based solely on format.
+  # @note CIK identifiers have no checksum and validation is based solely on format.
   #
   # @see https://en.wikipedia.org/wiki/Central_Index_Key
   #

data/lib/sec_id/concerns/checkable.rb

@@ -1,26 +1,26 @@
 # frozen_string_literal: true
 
 module SecID
-  # Provides check-digit validation and calculation for securities identifiers.
-  # Include this module in classes that have a check digit as part of their format.
+  # Provides checksum validation and calculation for securities identifiers.
+  # Include this module in classes that have a checksum as part of their format.
   #
   # Including classes must implement:
-  # - `calculate_check_digit` method that returns the calculated check digit value
+  # - `calculate_checksum` method that returns the calculated checksum value
   #
   # This module provides:
   # - Character-to-digit mapping constants
-  # - Luhn algorithm variants for check-digit calculation
-  # - `valid?` override that validates format and check digit
+  # - Luhn algorithm variants for checksum calculation
+  # - `valid?` override that validates format and checksum
   # - `restore` method returning full identifier string without mutation
-  # - `restore!` method to calculate and set the check digit, returning `self`
-  # - `check_digit` attribute
-  # - Class-level convenience methods: `restore`, `restore!`, `check_digit`
+  # - `restore!` method to calculate and set the checksum, returning `self`
+  # - `checksum` attribute
+  # - Class-level convenience methods: `restore`, `restore!`, `checksum`
   #
   # @example Including in an identifier class
   #   class MyIdentifier < Base
   #     include Checkable
   #
-  #     def calculate_check_digit
+  #     def calculate_checksum
   #       validate_format_for_calculation!
   #       mod10(luhn_sum_standard(reversed_digits_multi(identifier)))
   #     end
@@ -30,7 +30,7 @@ module SecID
   module Checkable
     # Character-to-digit mapping for Luhn algorithm variants.
     # Maps alphanumeric characters to digit arrays for multi-digit expansion.
-    # Used by ISIN for check-digit calculation.
+    # Used by ISIN for checksum calculation.
     CHAR_TO_DIGITS = {
       '0' => 0,      '1' => 1,      '2' => 2,      '3' => 3,      '4' => 4,
       '5' => 5,      '6' => 6,      '7' => 7,      '8' => 8,      '9' => 9,
@@ -44,7 +44,7 @@ module SecID
 
     # Character-to-digit mapping for single-digit conversion.
     # Maps alphanumeric characters to values 0-38 (A=10, B=11, ..., Z=35, *=36, @=37, #=38).
-    # Used by CUSIP, FIGI, SEDOL, LEI, and IBAN for check-digit calculations.
+    # Used by CUSIP, FIGI, SEDOL, LEI, and IBAN for checksum calculations.
     CHAR_TO_DIGIT = {
       '0' => 0,  '1' => 1,  '2' => 2,  '3' => 3,  '4' =>  4,
       '5' => 5,  '6' => 6,  '7' => 7,  '8' => 8,  '9' =>  9,
@@ -58,75 +58,102 @@ module SecID
 
     # @api private
     def self.included(base)
-      base.attr_reader :check_digit
+      base.attr_reader :checksum
       base.extend(ClassMethods)
     end
 
     # Class methods added when Checkable is included.
     module ClassMethods
-      # Returns the full identifier string with correct check digit.
+      # Returns the full identifier string with correct checksum.
       #
-      # @param id_without_check_digit [String] identifier without or with incorrect check digit
-      # @return [String] the full identifier with correct check digit
+      # @param id_without_checksum [String] identifier without or with incorrect checksum
+      # @return [String] the full identifier with correct checksum
       # @raise [InvalidFormatError] if the identifier format is invalid
-      def restore(id_without_check_digit)
-        new(id_without_check_digit).restore
+      def restore(id_without_checksum)
+        new(id_without_checksum).restore
       end
 
-      # Restores (calculates) the check digit and returns the instance.
+      # Restores (calculates) the checksum and returns the instance.
       #
-      # @param id_without_check_digit [String] identifier without or with incorrect check digit
-      # @return [self] the restored instance with correct check digit
+      # @param id_without_checksum [String] identifier without or with incorrect checksum
+      # @return [self] the restored instance with correct checksum
       # @raise [InvalidFormatError] if the identifier format is invalid
-      def restore!(id_without_check_digit)
-        new(id_without_check_digit).restore!
+      def restore!(id_without_checksum)
+        new(id_without_checksum).restore!
       end
 
-      # @param id [String] the identifier to calculate check digit for
-      # @return [Integer, String] the calculated check digit
+      # @param id [String] the identifier to calculate checksum for
+      # @return [Integer, String] the calculated checksum
+      # @raise [InvalidFormatError] if the identifier format is invalid
+      def checksum(id)
+        new(id).calculate_checksum
+      end
+
+      # @deprecated Use {.checksum}. Kept as a v7 bridge; removed in v8.
+      #
+      # @param id [String] the identifier to calculate the checksum for
+      # @return [Integer, String] the calculated checksum
       # @raise [InvalidFormatError] if the identifier format is invalid
       def check_digit(id)
-        new(id).calculate_check_digit
+        SecID::Deprecation.warn(old: 'check_digit', new: 'checksum')
+        checksum(id)
       end
     end
 
-    # Validates format and check digit.
+    # Validates format and checksum.
     #
     # @return [Boolean]
     def valid?
-      super && check_digit == calculate_check_digit
+      super && checksum == calculate_checksum
     end
 
-    # Returns the full identifier string with correct check digit without mutation.
+    # Returns the full identifier string with correct checksum without mutation.
     #
-    # @return [String] the full identifier with correct check digit
+    # @return [String] the full identifier with correct checksum
     # @raise [InvalidFormatError] if the identifier format is invalid
     def restore
-      "#{identifier}#{calculate_check_digit.to_s.rjust(check_digit_width, '0')}"
+      "#{identifier}#{calculate_checksum.to_s.rjust(checksum_width, '0')}"
     end
 
-    # Calculates and sets the check digit, updating full_id.
+    # Calculates and sets the checksum, updating full_id.
     #
     # @return [self]
     # @raise [InvalidFormatError] if the identifier format is invalid
     def restore!
-      @check_digit = calculate_check_digit
+      @checksum = calculate_checksum
       @full_id = to_s
       self
     end
 
-    # Subclasses must override this method to implement their check-digit algorithm.
+    # Subclasses must override this method to implement their checksum algorithm.
     #
-    # @return [Integer, String] the calculated check digit
+    # @return [Integer, String] the calculated checksum
     # @raise [NotImplementedError] if subclass doesn't implement
     # @raise [InvalidFormatError] if the identifier format is invalid
-    def calculate_check_digit
+    def calculate_checksum
       raise NotImplementedError
     end
 
     # @return [String]
     def to_s
-      "#{identifier}#{check_digit&.to_s&.rjust(check_digit_width, '0')}"
+      "#{identifier}#{checksum&.to_s&.rjust(checksum_width, '0')}"
+    end
+
+    # @deprecated Use {#checksum}. Kept as a v7 bridge; removed in v8.
+    #
+    # @return [Integer, String]
+    def check_digit
+      SecID::Deprecation.warn(old: 'check_digit', new: 'checksum')
+      checksum
+    end
+
+    # @deprecated Use {#calculate_checksum}. Kept as a v7 bridge; removed in v8.
+    #
+    # @return [Integer, String]
+    # @raise [InvalidFormatError] if the identifier format is invalid
+    def calculate_check_digit
+      SecID::Deprecation.warn(old: 'calculate_check_digit', new: 'calculate_checksum')
+      calculate_checksum
     end
 
     private
@@ -188,27 +215,27 @@ module SecID
       id.each_char.flat_map { |c| CHAR_TO_DIGITS.fetch(c) }.reverse!
     end
 
-    # Returns error codes including check digit validation.
+    # Returns error codes including checksum validation.
     #
     # @return [Array<Symbol>]
     def error_codes
       return detect_errors unless valid_format?
-      return [:invalid_check_digit] unless check_digit == calculate_check_digit
+      return [:invalid_checksum] unless checksum == calculate_checksum
 
       []
     end
 
     # @return [Integer]
-    def check_digit_width
+    def checksum_width
       1
     end
 
     # @param code [Symbol]
     # @return [String]
     def validation_message(code)
-      if code == :invalid_check_digit
-        fmt = ->(cd) { cd.to_s.rjust(check_digit_width, '0') }
-        return "Check digit '#{fmt[check_digit]}' is invalid, expected '#{fmt[calculate_check_digit]}'"
+      if code == :invalid_checksum
+        fmt = ->(cd) { cd.to_s.rjust(checksum_width, '0') }
+        return "Checksum '#{fmt[checksum]}' is invalid, expected '#{fmt[calculate_checksum]}'"
       end
 
       super
@@ -219,11 +246,11 @@ module SecID
     def validate_format_for_calculation!
       return if valid_format?
 
-      raise InvalidFormatError, "#{self.class.name} '#{full_id}' is invalid and check-digit cannot be calculated!"
+      raise InvalidFormatError, "#{self.class.name} '#{full_id}' is invalid and checksum cannot be calculated!"
     end
 
-    # @param sum [Integer] the sum to calculate check digit from
-    # @return [Integer] check digit (0-9)
+    # @param sum [Integer] the sum to calculate checksum from
+    # @return [Integer] checksum (0-9)
     def mod10(sum)
       (10 - (sum % 10)) % 10
     end
@@ -235,9 +262,26 @@ module SecID
     end
 
     # @param numeric_string [String] numeric string representation
-    # @return [Integer] check digit value (1-98)
+    # @return [Integer] checksum value (1-98)
     def mod97(numeric_string)
       98 - (numeric_string.to_i % 97)
     end
+
+    # ISO 7064 hybrid MOD 31,30 check character over a base string, parameterized
+    # by the type's 30-symbol alphabet. Shared by DTI and UPI.
+    #
+    # @param base [String] the base string (identifier without check character)
+    # @param alphabet [Array<String>] the 30-symbol alphabet ordered by check value (0-29)
+    # @param alphabet_value [Hash{String => Integer}] maps each alphabet character to its value
+    # @return [String] the single computed check character
+    def mod31_30_check_char(base, alphabet, alphabet_value)
+      perm = 30
+      base.each_char do |c|
+        s = (perm + alphabet_value.fetch(c)) % 30
+        s = 30 if s.zero?
+        perm = (s * 2) % 31
+      end
+      alphabet.fetch((31 - perm) % 30)
+    end
   end
 end

data/lib/sec_id/concerns/generatable.rb

@@ -4,9 +4,9 @@ module SecID
   # Provides generation of new, format-valid identifiers for use as test fixtures.
   #
   # Including classes define a class-level `generate_body(random)` returning a valid
-  # body (the identifier without its check digit). The default {ClassMethods#generate}
-  # builds an instance from that body and restores the check digit for check-digit types.
-  # Types whose shape is not "body (+ check digit)" compose the full identifier in
+  # body (the identifier without its checksum). The default {ClassMethods#generate}
+  # builds an instance from that body and restores the checksum for checksum types.
+  # Types whose shape is not "body (+ checksum)" compose the full identifier in
   # `generate_body` (CFI, FISN) or override `generate` entirely (OCC).
   #
   # @note Generated identifiers are valid in format only — they are not real,
@@ -44,12 +44,12 @@ module SecID
       # @return [self] a generated instance of the identifier type (e.g. {SecID::ISIN}) for which `valid?` is true
       def generate(random: Random.new)
         instance = new(generate_body(random))
-        has_check_digit? ? instance.restore! : instance
+        has_checksum? ? instance.restore! : instance
       end
 
       private
 
-      # Subclasses must implement this to return a valid body (identifier without check digit),
+      # Subclasses must implement this to return a valid body (identifier without checksum),
       # unless they override {#generate} entirely (as OCC does).
       #
       # @param _random [Random] source of randomness

data/lib/sec_id/concerns/normalizable.rb

@@ -19,7 +19,7 @@ module SecID
       #
       # @param id [String, #to_s] the identifier to normalize
       # @return [String] the normalized identifier
-      # @raise [InvalidFormatError, InvalidCheckDigitError, InvalidStructureError]
+      # @raise [InvalidFormatError, InvalidChecksumError, InvalidStructureError]
       def normalize(id)
         cleaned = id.to_s.strip.gsub(self::SEPARATORS, '')
         new(cleaned.upcase).normalized
@@ -38,7 +38,7 @@ module SecID
     # Returns the canonical normalized form of this identifier.
     #
     # @return [String]
-    # @raise [InvalidFormatError, InvalidCheckDigitError, InvalidStructureError]
+    # @raise [InvalidFormatError, InvalidChecksumError, InvalidStructureError]
     def normalized
       validate!
       to_s
@@ -46,13 +46,13 @@ module SecID
 
     # @!method normalize
     #   @return [String]
-    #   @raise [InvalidFormatError, InvalidCheckDigitError, InvalidStructureError]
+    #   @raise [InvalidFormatError, InvalidChecksumError, InvalidStructureError]
     alias normalize normalized
 
     # Normalizes this identifier in place, updating {#full_id}.
     #
     # @return [self]
-    # @raise [InvalidFormatError, InvalidCheckDigitError, InvalidStructureError]
+    # @raise [InvalidFormatError, InvalidChecksumError, InvalidStructureError]
     def normalize!
       @full_id = normalized
       self

data/lib/sec_id/concerns/validatable.rb

@@ -8,7 +8,7 @@ module SecID
   module Validatable
     # Maps error-code symbols to their exception classes; unmapped codes default to InvalidFormatError.
     ERROR_MAP = {
-      invalid_check_digit: InvalidCheckDigitError,
+      invalid_checksum: InvalidChecksumError,
       invalid_prefix: InvalidStructureError,
       invalid_category: InvalidStructureError,
       invalid_group: InvalidStructureError,
@@ -43,7 +43,7 @@ module SecID
       #
       # @param id [String] the identifier to validate
       # @return [Base] the identifier instance
-      # @raise [InvalidFormatError, InvalidCheckDigitError, InvalidStructureError]
+      # @raise [InvalidFormatError, InvalidChecksumError, InvalidStructureError]
       def validate!(id)
         new(id).validate!
       end
@@ -82,7 +82,7 @@ module SecID
     # Validates and returns self if valid, raises an exception otherwise.
     #
     # @return [self]
-    # @raise [InvalidFormatError, InvalidCheckDigitError, InvalidStructureError]
+    # @raise [InvalidFormatError, InvalidChecksumError, InvalidStructureError]
     def validate!
       return self if valid?
 
@@ -119,7 +119,7 @@ module SecID
     end
 
     # Checks length against ID_LENGTH's three shapes: Range (bounds), Array
-    # (discrete valid lengths), or Integer (allows an optional check digit).
+    # (discrete valid lengths), or Integer (allows an optional checksum).
     #
     # @return [Boolean]
     def valid_length?
@@ -130,7 +130,7 @@ module SecID
       case id_length
       when Range then id_length.cover?(len)
       when Array then id_length.include?(len)
-      else            ((id_length - check_digit_width)..id_length).cover?(len)
+      else            ((id_length - checksum_width)..id_length).cover?(len)
       end
     end
 
@@ -139,8 +139,8 @@ module SecID
       full_id.match?(self.class::VALID_CHARS_REGEX)
     end
 
-    # @return [Integer] width of the check digit (0 for non-checkable, overridden in Checkable)
-    def check_digit_width
+    # @return [Integer] width of the checksum (0 for non-checkable, overridden in Checkable)
+    def checksum_width
       0
     end
 

data/lib/sec_id/cusip.rb

@@ -4,7 +4,7 @@ module SecID
   # Committee on Uniform Securities Identification Procedures (CUSIP) - a 9-character
   # alphanumeric code that identifies North American securities.
   #
-  # Format: 6-character issuer code (CUSIP-6) + 2-character issue number + 1-digit check digit
+  # Format: 6-character issuer code (CUSIP-6) + 2-character issue number + 1-digit checksum
   #
   # @see https://en.wikipedia.org/wiki/CUSIP
   #
@@ -31,7 +31,7 @@ module SecID
       (?<identifier>
         (?<cusip6>[A-Z0-9]{5}[A-Z0-9*@#])
         (?<issue>[A-Z0-9*@#]{2}))
-      (?<check_digit>\d)?
+      (?<checksum>\d)?
     \z/x
 
     # @return [String, nil] the 6-character issuer code
@@ -46,19 +46,19 @@ module SecID
       @identifier = cusip_parts[:identifier]
       @cusip6 = cusip_parts[:cusip6]
       @issue = cusip_parts[:issue]
-      @check_digit = cusip_parts[:check_digit]&.to_i
+      @checksum = cusip_parts[:checksum]&.to_i
     end
 
     # @return [String, nil]
     def to_pretty_s
       return nil unless valid?
 
-      "#{cusip6} #{issue} #{check_digit}"
+      "#{cusip6} #{issue} #{checksum}"
     end
 
-    # @return [Integer] the calculated check digit (0-9)
+    # @return [Integer] the calculated checksum (0-9)
     # @raise [InvalidFormatError] if the CUSIP format is invalid
-    def calculate_check_digit
+    def calculate_checksum
       validate_format_for_calculation!
       mod10(luhn_sum_double_add_double(reversed_digits_single(identifier)))
     end
@@ -66,7 +66,7 @@ module SecID
     # Generates a random CUSIP body: 8 alphanumeric characters.
     #
     # @param random [Random] source of randomness
-    # @return [String] an 8-character CUSIP body without check digit
+    # @return [String] an 8-character CUSIP body without checksum
     def self.generate_body(random)
       random_string(ALPHANUMERIC, 8, random: random)
     end
@@ -91,6 +91,6 @@ module SecID
     private
 
     # @return [Hash]
-    def components = { cusip6:, issue:, check_digit: }
+    def components = { cusip6:, issue:, checksum: }
   end
 end

data/lib/sec_id/deprecation.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module SecID
+  # Emits standardized, silenceable deprecation warnings for the v7 → v8 rename
+  # bridge. Stateless: warns on every call with no per-call-site dedup, so the
+  # migration signal is never suppressed by default.
+  #
+  # The warning is written via {Kernel#warn} at Ruby's default verbosity — it is
+  # visible unless the process runs with `-W0` / `$VERBOSE = nil`. No `category:`
+  # is passed, because `Warning[:deprecated]` defaults to `false` and would hide
+  # the bridge warning the rename relies on.
+  module Deprecation
+    # Emits a standardized deprecation warning for a renamed API name.
+    #
+    # @param old [String] the deprecated name
+    # @param new [String] the canonical replacement name
+    # @param removed_in [String] the version that removes the deprecated name
+    # @return [void]
+    def self.warn(old:, new:, removed_in: 'v8')
+      Kernel.warn(
+        "SecID: `#{old}` is deprecated and will be removed in #{removed_in}; use `#{new}` instead.",
+        uplevel: 2
+      )
+    end
+  end
+end