sec_id 7.0.0 → 7.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b89119bace7665d5cbf511fc3ddf23083e375f7b8eff25dea56b00b584868e20
-  data.tar.gz: a9bb04a1ae20c48c150b2775f55d8f262707b7c6a8510283d6896b8b78dc1876
+  metadata.gz: 2ce3f9d548d4530dae973ee4ee4a7cf8e18898aaa36396423efe5ece7dd091f4
+  data.tar.gz: 5b7950a09cfc4afd59358b230fd659a9f26a1e58e50577ed16267f4763142a7f
 SHA512:
-  metadata.gz: 3f12de747aefe8f567c429c79c05717eb6a7425ffa644325b82b7255df822a5f09158afb8ac34565bfb642a9d5f6fd01effca91d7f0274e0abe5eb2fed0dd28e
-  data.tar.gz: 6d82e962ddb3219c6d5dbb28dcbfc188f56773b9210b83c6db9625bef83e6a50852a8d316166f3fe801d3c201b6654fd8d0f252da46593823edb1369e2bda8a3
+  metadata.gz: 34447319dc249c2fb3b7150cc45cc4a2aa8eed8e11ab16b726d9ee73d7aa2ad01daa2eed846f0cc788fb9f955488b161a91112ea6ec683268af7fa3fdf5267e0
+  data.tar.gz: 155fd8fe486ea96af91949ddd1adacb04310f50c820a2a5c1d98f1f55075545886c3935adfa5dacf2eedc9975ca7f1879c0e1140a8165dcd60736f24a0bcea94

data/CHANGELOG.md

@@ -8,6 +8,12 @@ and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
 ## [Unreleased]
 
+## [7.1.0] - 2026-07-15
+
+### Added
+
+- `suggest` — a checksum-anchored diagnostic-repair verb that turns the checksum from a gatekeeper into a repair engine. For a structurally-valid but checksum-**failing** identifier, `SecID::<Type>.suggest(str)` and `SecID.suggest(str, types:)` enumerate the plausible single-character human errors — visual/OCR homoglyph substitutions (`O`↔`0`, `I`↔`1`, `5`↔`S`, `8`↔`B`, …) and adjacent transpositions — keep only those that re-validate (`valid?` is the oracle, so no false candidate ever escapes), and return them as confidence-ranked `SecID::Suggestion` value objects reporting *what changed* (edit kind, position, from/to characters, confidence tier). Available for all 9 checksum types (ISIN, CUSIP, SEDOL, FIGI, LEI, IBAN, CEI, DTI, UPI) through one shared `Suggestable` concern. Candidates rank `:high` (homoglyph) then `:medium` (transposition) then a `:checksum` recompute fallback last; there is no `:low` tier (coincidental substitutions are never generated), keeping results small and high-precision. `suggest` never mutates its input and never presents a candidate as an authoritative correction. Non-checksum types (CIK, OCC, WKN, Valoren, CFI, FISN, BIC) have no checksum oracle and are unsupported; `SecID.suggest` silently skips them. Known limitations: the mistyped character must be in the type's charset to be reachable (the vowel-free SEDOL/FIGI/DTI/UPI can't repair an `O`-for-`0`/`I`-for-`1` typo), only a single body error is in scope, and wrong-length input returns `[]`. In a seeded simulation (`benchmark/suggest_precision.rb`), every reachable single-error homoglyph or transposition that yields a checksum-failing identifier is recovered (the correct identifier is always among the returned candidates), the top-ranked body candidate ~89% of the time for homoglyph errors
+
 ## [7.0.0] - 2026-07-14
 
 ### Added

data/README.md

@@ -1,6 +1,6 @@
 # SecID [![Gem Version](https://badge.fury.io/rb/sec_id.svg)](https://rubygems.org/gems/sec_id) [![CI](https://github.com/svyatov/sec_id/actions/workflows/main.yml/badge.svg)](https://github.com/svyatov/sec_id/actions/workflows/main.yml) [![codecov](https://codecov.io/gh/svyatov/sec_id/graph/badge.svg?token=VV49EMQIIC)](https://codecov.io/gh/svyatov/sec_id) [![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://rubydoc.info/gems/sec_id) [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-CC342D.svg)](https://www.ruby-lang.org) [![Types: RBS](https://img.shields.io/badge/types-RBS-8A2BE2.svg)](https://github.com/svyatov/sec_id/tree/main/sig)
 
-> A Ruby toolkit for securities identifiers — validate, parse, normalize, detect, convert, generate, and classify.
+> A Ruby toolkit for securities identifiers — validate, parse, normalize, detect, convert, generate, classify, and repair.
 
 ## Table of Contents
 
@@ -13,6 +13,7 @@
   - [Structured Validation](#structured-validation) - detailed error codes and messages
   - [Pattern Matching](#pattern-matching) - destructure identifiers with `case/in`
   - [Generating Test Fixtures](#generating-test-fixtures) - produce valid identifiers for tests
+  - [Repairing Typos](#repairing-typos) - suggest corrections for checksum-failing identifiers
   - [ISIN](#isin) - International Securities Identification Number
   - [CUSIP](#cusip) - Committee on Uniform Securities Identification Procedures
   - [CEI](#cei) - CUSIP Entity Identifier
@@ -47,7 +48,7 @@ Ruby 3.2+ is required.
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'sec_id', '~> 7.0'
+gem 'sec_id', '~> 7.1'
 ```
 
 And then execute:
@@ -328,6 +329,41 @@ SecID::LEI.generate(random: Random.new(42)) == SecID::LEI.generate(random: Rando
 > randomly selected (from the values each standard permits) and do not map to real-world
 > instruments. Use them as test fixtures, not as references to actual securities.
 
+### Repairing Typos
+
+Turn the checksum from a gatekeeper into a repair engine. For a checksum-**failing** identifier, `suggest` enumerates the plausible single-character human errors — visual/OCR homoglyph substitutions (`O`↔`0`, `I`↔`1`, `5`↔`S`, `8`↔`B`, …) and adjacent transpositions — keeps only the edits that re-validate, and returns them as confidence-ranked `SecID::Suggestion` candidates that report *what changed*. Available for all 9 checksum types (ISIN, CUSIP, SEDOL, FIGI, LEI, IBAN, CEI, DTI, UPI) per class and via the central dispatcher:
+
+```ruby
+# A letter O typed where a 0 belongs — 'US5949181O45' should be 'US5949181045'
+top = SecID::ISIN.suggest('US5949181O45').first
+top.to_s          # => 'US5949181045'  (the corrected identifier)
+top.edit          # => :substitution
+top.position      # => 9
+top.from          # => 'O'
+top.to            # => '0'
+top.confidence    # => :high
+top.identifier    # => #<SecID::ISIN ...>  (parsed and valid — call .country_code, .to_h, etc.)
+
+# Module-level: infers every format-compatible checksum type (like parse / detect)
+SecID.suggest('US5949181O45')                   # => [#<SecID::Suggestion type=:isin ...>, ...]
+SecID.suggest('US5949181O45', types: [:isin])   # => restrict to specific types
+```
+
+Each candidate carries the corrected `identifier` (a parsed, valid instance), the `edit` kind, its `position`, the `from`/`to` characters, and a `confidence` tier. Candidates are ranked by confidence: `:high` homoglyph substitutions first, then `:medium` adjacent transpositions, then the `:checksum` recompute (body assumed correct, wrong check character) last as a fallback hypothesis. **There is no `:low` tier** — coincidental substitutions that merely satisfy the checksum are never generated, keeping the result small and high-precision.
+
+> **`suggest` returns candidates, never authoritative corrections, and never mutates its input.**
+> Every returned candidate fully re-validates (`valid?` is the oracle), so no false candidate escapes —
+> but the `confidence` tier is how *you* decide what to trust. This matters for financial identifiers.
+
+Notes and limitations:
+
+- **Never empty for structurally-valid input** — a parseable but checksum-failing identifier always yields at least the `:checksum` fallback. Only wrong-length or illegal-charset input (which fails the format gate) returns `[]`.
+- **Vowel-free reachability** — SEDOL, FIGI, DTI, and UPI exclude vowels from their charset, so an `O`-for-`0` or `I`-for-`1` typo is unparseable and therefore unrepairable (it fails the format gate before enumeration). The mistyped character must be *in* the type's charset to be reachable.
+- **Single body error only** — two or more wrong body characters, or a dropped/doubled character (insertion/deletion), are out of scope; such input returns only the `:checksum` fallback, never additional body candidates.
+- **Non-checksum types are unsupported** — CIK, OCC, WKN, Valoren, CFI, FISN, and BIC have no checksum oracle, so they have no `suggest`; `SecID.suggest` silently skips them.
+
+**Precision** (simulated over 1,000 seeded samples per checksum type — see [`benchmark/suggest_precision.rb`](benchmark/suggest_precision.rb)): every reachable, single-error homoglyph or transposition that yields a checksum-failing identifier is recovered — the correct identifier is **always** among the returned candidates (100%), and is the top-ranked body candidate ~89% of the time for homoglyph errors. In-charset homoglyph reachability averages ~96% (100% for the letter-permitting types, lower for the four vowel-free ones).
+
 ### ISIN
 
 > [International Securities Identification Number](https://en.wikipedia.org/wiki/International_Securities_Identification_Number) - a 12-character alphanumeric code that uniquely identifies a security.

data/lib/sec_id/cei.rb

@@ -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'

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

data/lib/sec_id/cusip.rb

@@ -16,6 +16,7 @@ module SecID
   #   cusip.to_isin('US')  #=> #<SecID::ISIN>
   class CUSIP < Base
     include Checkable
+    include Suggestable
 
     # Human-readable name of the standard.
     FULL_NAME = 'Committee on Uniform Securities Identification Procedures'

data/lib/sec_id/dti.rb

@@ -17,6 +17,7 @@ module SecID
   #   SecID::DTI.restore('X9J9K872')  #=> 'X9J9K872S'
   class DTI < Base
     include Checkable
+    include Suggestable
 
     # Human-readable name of the standard.
     FULL_NAME = 'Digital Token Identifier'

data/lib/sec_id/figi.rb

@@ -16,6 +16,7 @@ module SecID
   #   SecID::FIGI.restore!('BBG000BLNQ1')  #=> #<SecID::FIGI>
   class FIGI < Base
     include Checkable
+    include Suggestable
 
     # Human-readable name of the standard.
     FULL_NAME = 'Financial Instrument Global Identifier'

data/lib/sec_id/iban.rb

@@ -19,6 +19,7 @@ module SecID
   #   SecID::IBAN.restore!('DE00370400440532013000')  #=> #<SecID::IBAN>
   class IBAN < Base
     include Checkable
+    include Suggestable
 
     # Human-readable name of the standard.
     FULL_NAME = 'International Bank Account Number'

data/lib/sec_id/isin.rb

@@ -15,6 +15,7 @@ module SecID
   #   SecID::ISIN.restore!('US594918104')  #=> #<SecID::ISIN>
   class ISIN < Base
     include Checkable
+    include Suggestable
 
     # Human-readable name of the standard.
     FULL_NAME = 'International Securities Identification Number'

data/lib/sec_id/lei.rb

@@ -16,6 +16,7 @@ module SecID
   #   SecID::LEI.checksum('529900T8BM49AURSDO')  #=> 55
   class LEI < Base
     include Checkable
+    include Suggestable
 
     # Human-readable name of the standard.
     FULL_NAME = 'Legal Entity Identifier'

data/lib/sec_id/sedol.rb

@@ -16,6 +16,7 @@ module SecID
   #   SecID::SEDOL.checksum('B19GKT')  #=> 4
   class SEDOL < Base
     include Checkable
+    include Suggestable
 
     # Human-readable name of the standard.
     FULL_NAME = 'Stock Exchange Daily Official List'

data/lib/sec_id/suggestion.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module SecID
+  # Immutable value object representing one repair candidate returned by `suggest`.
+  #
+  # Carries the corrected, re-validated identifier plus the what-changed diff (edit
+  # kind, position, from/to characters) and a confidence tier — the honest surface
+  # that keeps a candidate from reading as an authoritative correction.
+  #
+  # Coordinate system by edit kind:
+  # - `:substitution` — `position` is the 0-based index of the changed character;
+  #   `from`/`to` are the single characters before/after.
+  # - `:transposition` — `position` is the left index of the swapped pair;
+  #   `from`/`to` are the two-character adjacent substring before/after the swap.
+  # - `:checksum` — `position` is `nil`; `from`/`to` are the old/new check-character
+  #   string. `confidence` is `nil` (it is the fallback hypothesis, ranked last).
+  #
+  # @!attribute [r] type
+  #   @return [Symbol] the identifier type key (e.g. :isin)
+  # @!attribute [r] identifier
+  #   @return [SecID::Base] the valid, parsed corrected identifier
+  # @!attribute [r] edit
+  #   @return [Symbol] :substitution, :transposition, or :checksum
+  # @!attribute [r] position
+  #   @return [Integer, nil] the edit position (nil for :checksum)
+  # @!attribute [r] from
+  #   @return [String] the original character(s)
+  # @!attribute [r] to
+  #   @return [String] the replacement character(s)
+  # @!attribute [r] confidence
+  #   @return [Symbol, nil] :high (homoglyph), :medium (transposition), or nil (:checksum)
+  #
+  # @example
+  #   suggestion = SecID::ISIN.suggest('US5949181O45').first
+  #   suggestion.to_s          #=> 'US5949181045'
+  #   suggestion.edit          #=> :substitution
+  #   suggestion.confidence    #=> :high
+  Suggestion = Data.define(:type, :identifier, :edit, :position, :from, :to, :confidence)
+
+  # Reopened to add the domain enumerations and serialization helpers per the repo
+  # convention (see {Base#as_json}).
+  class Suggestion
+    # The edit kinds `edit` can take, in rank order (see {Suggestable::RANK}).
+    EDIT_KINDS = %i[substitution transposition checksum].freeze
+
+    # The non-nil confidence tiers `confidence` can take; `:checksum` candidates carry `nil`.
+    CONFIDENCE_LEVELS = %i[high medium].freeze
+
+    # @return [Hash] the symbol-keyed field hash (JSON-compatible)
+    def as_json(*)
+      to_h
+    end
+
+    # @return [String] the corrected identifier string
+    def to_s
+      identifier.to_s
+    end
+  end
+end

data/lib/sec_id/upi.rb

@@ -18,6 +18,7 @@ module SecID
   #   SecID::UPI.restore('QZRBG6ZTKS4')  #=> 'QZRBG6ZTKS42'
   class UPI < Base
     include Checkable
+    include Suggestable
 
     # Human-readable name of the standard.
     FULL_NAME = 'Unique Product Identifier'

data/lib/sec_id/version.rb

@@ -2,5 +2,5 @@
 
 module SecID
   # Current gem version.
-  VERSION = '7.0.0'
+  VERSION = '7.1.0'
 end

data/lib/sec_id.rb

@@ -143,8 +143,40 @@ module SecID
       self[key].generate(random: random)
     end
 
+    # Returns confidence-ranked repair candidates for a checksum-failing identifier,
+    # inferred across all format-compatible checksum types (or the given `types:`).
+    #
+    # @note Repair is only defined for checksum types; non-checksum types have no
+    #   oracle and are silently skipped.
+    #
+    # @param str [String, nil] the identifier string to repair
+    # @param types [Array<Symbol>, nil] restrict to specific types (non-checksum types are ignored)
+    # @return [Array<Suggestion>] cross-type ranked candidates, each carrying its `type`;
+    #   empty when no format-compatible checksum type matches
+    # @raise [ArgumentError] if any key in types is unknown
+    def suggest(str, types: nil)
+      input = str.to_s.strip.upcase
+      suggestable_types(input, types)
+        .flat_map { |klass| klass.suggest(input) }
+        .sort_by { |suggestion| [Suggestable::RANK.fetch(suggestion.edit), self[suggestion.type].detection_priority.last] }
+    end
+
     private
 
+    # Resolves the checksum types eligible to repair `input` (KTD4): the given `types:`
+    # narrowed to checksum types, or every checksum type whose length and charset admit it.
+    #
+    # @param input [String] the normalized (stripped, upcased) input
+    # @param types [Array<Symbol>, nil]
+    # @return [Array<Class>]
+    def suggestable_types(input, types)
+      return types.map { |key| self[key] }.select(&:has_checksum?) if types
+
+      identifier_list.select do |klass|
+        klass.has_checksum? && klass.length_values.include?(input.length) && input.match?(klass::VALID_CHARS_REGEX)
+      end
+    end
+
     # @return [void]
     def register_identifier(klass)
       identifier_map[klass.type_key] = klass
@@ -206,7 +238,9 @@ require 'sec_id/concerns/normalizable'
 require 'sec_id/concerns/validatable'
 require 'sec_id/concerns/checkable'
 require 'sec_id/concerns/generatable'
+require 'sec_id/concerns/suggestable'
 require 'sec_id/base'
+require 'sec_id/suggestion'
 require 'sec_id/detector'
 require 'sec_id/scanner'
 require 'sec_id/isin'

data/sec_id.gemspec

@@ -11,9 +11,10 @@ Gem::Specification.new do |spec|
   spec.email         = ['leonid@svyatov.ru']
 
   spec.summary       = 'A Ruby toolkit for securities identifiers — validate, parse, normalize, detect, convert, ' \
-                       'generate, and classify.'
-  spec.description   = 'Validate, normalize, parse, convert, generate, and classify securities identifiers. ' \
-                       'Auto-detect identifier type from any string. Calculate and restore checksums. Generate ' \
+                       'generate, classify, and repair.'
+  spec.description   = 'Validate, normalize, parse, convert, generate, classify, and repair securities identifiers. ' \
+                       'Auto-detect identifier type from any string. Calculate and restore checksums. Suggest ' \
+                       'confidence-ranked corrections for fat-fingered or OCR-mangled identifiers. Generate ' \
                        'format-valid identifiers as test fixtures. Decode CFI codes to full ISO 10962:2021 ' \
                        'classifications. Includes an opt-in ActiveModel/Rails validator that adds no runtime ' \
                        'dependency. Supports ISIN, CUSIP, CEI, SEDOL, FIGI, LEI, IBAN, CIK, OCC, WKN, Valoren, ' \

data/sig/sec_id/base.rbs

@@ -43,6 +43,9 @@ module SecID
     def self.length_specificity: () -> (Integer | Float | nil)
     def self.example: () -> String
     def self.has_checksum?: () -> bool
+    # Only Suggestable (checksum) types implement `.suggest`; declared here so the
+    # module-level `SecID.suggest` can call it on any registered class object.
+    def self.suggest: (SecID::input str) -> Array[Suggestion]
 
     # @deprecated v7 bridge alias for `has_checksum?`; removed in v8.
     def self.has_check_digit?: () -> bool
@@ -58,12 +61,15 @@ module SecID
     def as_json: (*untyped) -> Hash[Symbol, untyped]
     def deconstruct_keys: (::Array[Symbol]? _keys) -> Hash[Symbol, untyped]
 
-    # Checksum surface. Only the types that `include Checkable` implement these
-    # (they raise/NoMethodError otherwise); declared on Base so `Generatable#generate`
-    # and `Checkable::ClassMethods` type-check without narrowing on `has_checksum?`.
+    # Checksum / repair surface. Only the types that `include Checkable` /
+    # `include Suggestable` implement these (they raise/NoMethodError otherwise);
+    # declared on Base so `Generatable#generate`, `Checkable::ClassMethods`, and the
+    # Base-self-typed `Suggestable` body type-check without narrowing on `has_checksum?`.
     def restore: () -> String
     def restore!: () -> self
     def calculate_checksum: () -> (Integer | String)
+    attr_reader checksum: (Integer | String)?
+    def suggest: () -> Array[Suggestion]
 
     def comparison_id: () -> String
 

data/sig/sec_id/concerns/checkable.rbs

@@ -6,7 +6,8 @@ module SecID
 
     def self.included: (Module base) -> void
 
-    attr_reader checksum: (Integer | String)?
+    # `attr_reader checksum` is declared on Base (the repair surface) to keep the
+    # Base-self-typed Suggestable body type-checking; not redeclared here.
 
     # Class methods added when Checkable is included.
     module ClassMethods : SecID::_IdentifierClass

data/sig/sec_id/concerns/suggestable.rbs

@@ -0,0 +1,32 @@
+module SecID
+  # Repair engine for checksum-failing identifiers: enumerates plausible edits and
+  # returns the re-validating ones as confidence-ranked Suggestion objects.
+  module Suggestable : SecID::Base
+    HOMOGLYPHS: Hash[String, Array[String]]
+    RANK: Hash[Symbol, Integer]
+
+    def self.included: (Module base) -> void
+
+    # Class methods added when Suggestable is included.
+    module ClassMethods : SecID::_IdentifierClass
+      def suggest: (SecID::input str) -> Array[Suggestion]
+    end
+
+    def suggest: () -> Array[Suggestion]
+
+    private
+
+    def candidate_strings: () -> Array[String]
+    def homoglyph_candidates: () -> Array[String]
+    def transposition_candidates: () -> Array[String]
+    def replace_at: (String str, Integer index, String char) -> String
+    def swap_at: (String str, Integer index) -> String
+    def classify: (Base candidate) -> Suggestion?
+    def changed_indices: (Base candidate) -> Array[Integer]
+    def substitution_suggestion: (Base candidate, Integer index) -> Suggestion
+    def transposition_suggestion: (Base candidate, Array[Integer] indices) -> Suggestion?
+    def swap?: (Base candidate, Integer left, Integer right) -> bool
+    def checksum_suggestion: (Base candidate) -> Suggestion
+    def rendered_checksum: ((Integer | String)? value) -> String
+  end
+end

data/sig/sec_id/suggestion.rbs

@@ -0,0 +1,23 @@
+module SecID
+  # Immutable value object representing one repair candidate returned by `suggest`.
+  class Suggestion < Data
+    EDIT_KINDS: Array[Symbol]
+    CONFIDENCE_LEVELS: Array[Symbol]
+
+    attr_reader type: Symbol
+    attr_reader identifier: Base
+    attr_reader edit: Symbol
+    attr_reader position: Integer?
+    attr_reader from: String
+    attr_reader to: String
+    attr_reader confidence: Symbol?
+
+    def self.new: (type: Symbol, identifier: Base, edit: Symbol, position: Integer?, from: String, to: String, confidence: Symbol?) -> instance
+                | (Symbol type, Base identifier, Symbol edit, Integer? position, String from, String to, Symbol? confidence) -> instance
+    def self.[]: (type: Symbol, identifier: Base, edit: Symbol, position: Integer?, from: String, to: String, confidence: Symbol?) -> instance
+               | (Symbol type, Base identifier, Symbol edit, Integer? position, String from, String to, Symbol? confidence) -> instance
+
+    def as_json: (*untyped) -> Hash[Symbol, untyped]
+    def to_s: () -> String
+  end
+end

data/sig/sec_id.rbs

@@ -38,9 +38,11 @@ module SecID
   # against the `:first`/`:raise` arm's `Base?` and fail. Widening here keeps `result` untyped.
   def self.parse!: (SecID::input str, ?types: Array[Symbol]?, ?on_ambiguous: Symbol) -> (Base | Array[Base])
   def self.generate: (Symbol key, ?random: Random) -> Base
+  def self.suggest: (SecID::input str, ?types: Array[Symbol]?) -> Array[Suggestion]
 
   # Singleton-method privacy must be declared inline (`private def self.…`); a bare
   # `private` section only affects instance methods, leaving these public.
+  private def self.suggestable_types: (String input, Array[Symbol]? types) -> Array[singleton(Base)]
   private def self.register_identifier: (singleton(Base) klass) -> void
   private def self.parse_any: (SecID::input str) -> Base?
   private def self.parse_from: (SecID::input str, Array[Symbol] types) -> Base?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sec_id
 version: !ruby/object:Gem::Version
-  version: 7.0.0
+  version: 7.1.0
 platform: ruby
 authors:
 - Leonid Svyatov
@@ -9,9 +9,10 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Validate, normalize, parse, convert, generate, and classify securities
+description: Validate, normalize, parse, convert, generate, classify, and repair securities
   identifiers. Auto-detect identifier type from any string. Calculate and restore
-  checksums. Generate format-valid identifiers as test fixtures. Decode CFI codes
+  checksums. Suggest confidence-ranked corrections for fat-fingered or OCR-mangled
+  identifiers. Generate format-valid identifiers as test fixtures. Decode CFI codes
   to full ISO 10962:2021 classifications. Includes an opt-in ActiveModel/Rails validator
   that adds no runtime dependency. Supports ISIN, CUSIP, CEI, SEDOL, FIGI, LEI, IBAN,
   CIK, OCC, WKN, Valoren, CFI, FISN, BIC, DTI, and UPI.
@@ -41,6 +42,7 @@ files:
 - lib/sec_id/concerns/checkable.rb
 - lib/sec_id/concerns/generatable.rb
 - lib/sec_id/concerns/normalizable.rb
+- lib/sec_id/concerns/suggestable.rb
 - lib/sec_id/concerns/validatable.rb
 - lib/sec_id/cusip.rb
 - lib/sec_id/deep_freeze.rb
@@ -58,6 +60,7 @@ files:
 - lib/sec_id/railtie.rb
 - lib/sec_id/scanner.rb
 - lib/sec_id/sedol.rb
+- lib/sec_id/suggestion.rb
 - lib/sec_id/upi.rb
 - lib/sec_id/valoren.rb
 - lib/sec_id/version.rb
@@ -78,6 +81,7 @@ files:
 - sig/sec_id/concerns/checkable.rbs
 - sig/sec_id/concerns/generatable.rbs
 - sig/sec_id/concerns/normalizable.rbs
+- sig/sec_id/concerns/suggestable.rbs
 - sig/sec_id/concerns/validatable.rbs
 - sig/sec_id/cusip.rbs
 - sig/sec_id/deep_freeze.rbs
@@ -94,6 +98,7 @@ files:
 - sig/sec_id/occ.rbs
 - sig/sec_id/scanner.rbs
 - sig/sec_id/sedol.rbs
+- sig/sec_id/suggestion.rbs
 - sig/sec_id/upi.rbs
 - sig/sec_id/valoren.rbs
 - sig/sec_id/version.rbs
@@ -124,5 +129,5 @@ requirements: []
 rubygems_version: 4.0.12
 specification_version: 4
 summary: A Ruby toolkit for securities identifiers — validate, parse, normalize, detect,
-  convert, generate, and classify.
+  convert, generate, classify, and repair.
 test_files: []