sec_id 6.1.0 → 7.1.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,7 +46,7 @@ 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
@@ -55,15 +55,15 @@ module SecID
       # @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: check-digit types first,
+      # 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 [check-digit rank, length specificity, registration order]
+      # @return [Array] frozen [checksum rank, length specificity, registration order]
       def detection_priority
         @detection_priority ||=
-          [has_check_digit? ? 0 : 1, length_specificity, SecID.identifiers.index(self) || Float::INFINITY].freeze
+          [has_checksum? ? 0 : 1, length_specificity, SecID.identifiers.index(self) || Float::INFINITY].freeze
       end
 
       # @return [String] the unqualified class name (e.g. "ISIN", "CUSIP")
@@ -89,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
 
@@ -134,7 +142,7 @@ module SecID
         full_id: full_id,
         normalized: valid? ? normalized : nil,
         valid: valid?,
-        components: components
+        components: components_with_deprecation_bridge
       }
     end
 
@@ -157,7 +165,7 @@ module SecID
     #   in SecID::ISIN[country_code:, nsin:] then [country_code, nsin]
     #   in nil then :invalid
     #   end #=> ['US', '594918104']
-    def deconstruct_keys(_keys) = components
+    def deconstruct_keys(_keys) = components_with_deprecation_bridge
 
     protected
 
@@ -168,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
   #
@@ -12,6 +12,7 @@ module SecID
   #   SecID::CEI.valid?('A0BCDEFGH1')  #=> true
   class CEI < Base
     include Checkable
+    include Suggestable
 
     # Human-readable name of the standard.
     FULL_NAME = 'CUSIP Entity Identifier'
@@ -28,7 +29,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 +48,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 +61,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 +71,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/suggestable.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module SecID
+  # Repair engine for checksum-failing identifiers: enumerates plausible single-character
+  # edits (homoglyph/OCR substitutions and adjacent transpositions), keeps only those that
+  # re-validate, and returns them as confidence-ranked {Suggestion} objects.
+  #
+  # Included by the 9 checksum types. The candidate space is the human-error net —
+  # {HOMOGLYPHS} plus adjacent transpositions — never a full coincidental net. `valid?`
+  # is the oracle, so no false candidate ever escapes; the {HOMOGLYPHS} table bounds recall.
+  #
+  # @see SecID::Suggestion
+  #
+  # @example
+  #   SecID::ISIN.suggest('US5949181O45')
+  #   #=> [#<SecID::Suggestion edit=:substitution ...>, #<SecID::Suggestion edit=:checksum ...>]
+  module Suggestable
+    # Homoglyph / OCR confusion table (KTD5 seed): each character maps to the characters
+    # it is commonly mistyped as or misread from. A bidirectional expansion of the seed
+    # pairs {0/O, 0/Q, 0/D, 1/I, 1/L, I/L, 2/Z, 5/S, 6/G, 8/B}. Membership bounds recall —
+    # widen it (see benchmark/suggest_precision.rb) to raise it.
+    HOMOGLYPHS = {
+      '0' => %w[O Q D], 'O' => %w[0], 'Q' => %w[0], 'D' => %w[0],
+      '1' => %w[I L], 'I' => %w[1 L], 'L' => %w[1 I],
+      '2' => %w[Z], 'Z' => %w[2], '5' => %w[S], 'S' => %w[5],
+      '6' => %w[G], 'G' => %w[6], '8' => %w[B], 'B' => %w[8]
+    }.freeze
+
+    # Rank weight per edit kind: body substitutions first, then adjacent transpositions,
+    # then the checksum-recompute fallback last (R6/R7).
+    RANK = { substitution: 0, transposition: 1, checksum: 2 }.freeze
+
+    # @api private
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class methods added when Suggestable is included.
+    module ClassMethods
+      # Returns confidence-ranked repair candidates for a checksum-failing identifier.
+      #
+      # @param str [String] the identifier string to repair
+      # @return [Array<Suggestion>] ranked candidates; empty when `str` is already valid
+      #   or fails the type's format (wrong length or charset)
+      def suggest(str)
+        new(str).suggest
+      end
+    end
+
+    # Enumerates plausible edits and returns the re-validating ones, confidence-ranked.
+    #
+    # @return [Array<Suggestion>] ranked candidates; empty when already valid or unparseable
+    def suggest
+      return [] if valid?
+      return [] unless valid_format?
+
+      surviving = candidate_strings.uniq.map { |candidate| self.class.new(candidate) }.select(&:valid?)
+      surviving.filter_map { |candidate| classify(candidate) }.sort_by { |suggestion| RANK.fetch(suggestion.edit) }
+    end
+
+    private
+
+    # Homoglyph substitutions + adjacent transpositions + the checksum recompute (R4, R6).
+    #
+    # @return [Array<String>] candidate identifier strings (unfiltered, may include duplicates)
+    def candidate_strings
+      homoglyph_candidates + transposition_candidates + [restore]
+    end
+
+    # @return [Array<String>]
+    def homoglyph_candidates
+      full_id.each_char.with_index.flat_map do |char, index|
+        Array(HOMOGLYPHS[char]).map { |replacement| replace_at(full_id, index, replacement) }
+      end
+    end
+
+    # @return [Array<String>]
+    def transposition_candidates
+      (0...(full_id.length - 1)).filter_map do |index|
+        swap_at(full_id, index) unless full_id[index] == full_id[index + 1]
+      end
+    end
+
+    # @param str [String]
+    # @param index [Integer]
+    # @param char [String] the replacement character
+    # @return [String]
+    def replace_at(str, index, char)
+      str.dup.tap { |copy| copy[index] = char }
+    end
+
+    # @param str [String]
+    # @param index [Integer] left index of the adjacent pair to swap
+    # @return [String]
+    def swap_at(str, index)
+      str.dup.tap { |copy| copy[index], copy[index + 1] = copy[index + 1], copy[index] }
+    end
+
+    # Tags a surviving candidate by comparing bodies then diffing the strings (KTD3):
+    # equal bodies mean only the check characters changed.
+    #
+    # @param candidate [SecID::Base] a re-validated candidate instance
+    # @return [Suggestion, nil] nil when the diff is neither a single substitution nor an adjacent swap
+    def classify(candidate)
+      return checksum_suggestion(candidate) if candidate.identifier == identifier
+
+      changed = changed_indices(candidate)
+      case changed.size
+      when 1 then substitution_suggestion(candidate, changed.first.to_i)
+      when 2 then transposition_suggestion(candidate, changed)
+      end
+    end
+
+    # @param candidate [SecID::Base]
+    # @return [Array<Integer>] indices where the candidate's string differs from the input's
+    def changed_indices(candidate)
+      other = candidate.full_id
+      (0...full_id.length).reject { |index| full_id[index] == other[index] }
+    end
+
+    # @param candidate [SecID::Base]
+    # @param index [Integer]
+    # @return [Suggestion]
+    def substitution_suggestion(candidate, index)
+      Suggestion.new(
+        type: self.class.type_key, identifier: candidate, edit: :substitution,
+        position: index, from: full_id[index].to_s, to: candidate.full_id[index].to_s, confidence: :high
+      )
+    end
+
+    # @param candidate [SecID::Base]
+    # @param indices [Array<Integer>] the two differing indices
+    # @return [Suggestion, nil] nil unless the two indices are an adjacent, mutual swap
+    def transposition_suggestion(candidate, indices)
+      left = indices.min.to_i
+      right = indices.max.to_i
+      return unless right == left + 1 && swap?(candidate, left, right)
+
+      Suggestion.new(
+        type: self.class.type_key, identifier: candidate, edit: :transposition,
+        position: left, from: full_id[left, 2].to_s, to: candidate.full_id[left, 2].to_s, confidence: :medium
+      )
+    end
+
+    # @param candidate [SecID::Base]
+    # @param left [Integer]
+    # @param right [Integer]
+    # @return [Boolean] true when the two positions are a mutual swap of the input's characters
+    def swap?(candidate, left, right)
+      full_id[left] == candidate.full_id[right] && full_id[right] == candidate.full_id[left]
+    end
+
+    # @param candidate [SecID::Base]
+    # @return [Suggestion]
+    def checksum_suggestion(candidate)
+      Suggestion.new(
+        type: self.class.type_key, identifier: candidate, edit: :checksum, position: nil,
+        from: rendered_checksum(checksum), to: rendered_checksum(candidate.checksum), confidence: nil
+      )
+    end
+
+    # @param value [Integer, String, nil] a checksum value
+    # @return [String] the check-character string, zero-padded to the checksum width ('' when absent)
+    def rendered_checksum(value)
+      value.nil? ? '' : value.to_s.rjust(checksum_width, '0')
+    end
+  end
+end