sec_id 7.0.0 → 7.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b89119bace7665d5cbf511fc3ddf23083e375f7b8eff25dea56b00b584868e20
-  data.tar.gz: a9bb04a1ae20c48c150b2775f55d8f262707b7c6a8510283d6896b8b78dc1876
+  metadata.gz: be4a59e18a04226f78492df3eb2ec1318af8e7c99044005bda0f7b9652ac7a33
+  data.tar.gz: 6edd9226b4cc7b293a7fe1950f32aa0673ea0b44507b36ecc253da98f372d3c2
 SHA512:
-  metadata.gz: 3f12de747aefe8f567c429c79c05717eb6a7425ffa644325b82b7255df822a5f09158afb8ac34565bfb642a9d5f6fd01effca91d7f0274e0abe5eb2fed0dd28e
-  data.tar.gz: 6d82e962ddb3219c6d5dbb28dcbfc188f56773b9210b83c6db9625bef83e6a50852a8d316166f3fe801d3c201b6654fd8d0f252da46593823edb1369e2bda8a3
+  metadata.gz: b4b95d04179e0aee0ff4c45dbc2e169a024d3933a2c8234de2319422d19773d34247d83b8f457317af93d536ac431406fca9455a454cc7159ae2a9bad8982955
+  data.tar.gz: f479c160b3229763197b1ac1fe3b7d67f8a6fc3281d3607adf59fece50e89cc8dd2160eb2d4f94d32954d136bc2e8c8998b19bfcdf1e24f4e32a2a035f9e972a

data/CHANGELOG.md

@@ -8,58 +8,76 @@ and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
 ## [Unreleased]
 
+## [7.1.1] - 2026-07-31
+
+Documentation and packaging only. No identifier, checksum, or public method changed.
+
+This is the first release published from CI through RubyGems trusted publishing, signed with sigstore and pushed with a build provenance attestation.
+
+### Changed
+
+- README declares the public API that Semantic Versioning covers, names the `@api private` internals excluded from it, and links where to ask a question and where to report a defect
+- CHANGELOG version headings resolve to comparison links, and 2.0.1 has the entry it never had
+- Gem summary punctuation matches the README tagline
+
+## [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 such as `O`↔`0`, `I`↔`1`, `5`↔`S`, `8`↔`B`, plus adjacent transpositions), keep only those that re-validate (`valid?` is the oracle, so no checksum-invalid candidate ever escapes, though a valid candidate is not necessarily the intended correction), 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
 
-- UPI (ISO 4914, Unique Product Identifier) support via `SecID::UPI` — the gem's 16th identifier type, and the first offline UPI validator in any language. Validates the 12-character code (fixed `QZ` prefix, 9-character body, 1 check character) issued by the ANNA Derivatives Service Bureau for OTC-derivatives reporting (CFTC, EMIR, and other global mandates). The check character is computed fully offline via ISO 7064 hybrid MOD 31,30 over the same 30-symbol alphabet as DTI (digits plus consonants; vowels and `Y` never appear), pinned empirically against DSB-issued vectors — no DSB registry lookup or paywalled ISO 4914 spec required. Like DTI, `checksum`/`calculate_checksum` return a `String` rather than an `Integer`, since UPI check characters can be letters. A UPI shares the 12-character length bucket with ISIN and can double-detect (ISIN ranked first) when its digit check character also satisfies ISIN's Luhn checksum.
+- UPI (ISO 4914, Unique Product Identifier) support via `SecID::UPI`: the gem's 16th identifier type, and the first offline UPI validator in any language. Validates the 12-character code (fixed `QZ` prefix, 9-character body, 1 check character) issued by the ANNA Derivatives Service Bureau for OTC-derivatives reporting (CFTC, EMIR, and other global mandates). The check character is computed fully offline via ISO 7064 hybrid MOD 31,30 over the same 30-symbol alphabet as DTI (digits plus consonants; vowels and `Y` never appear), pinned empirically against DSB-issued vectors, with no DSB registry lookup or paywalled ISO 4914 spec required. Like DTI, `checksum`/`calculate_checksum` return a `String` rather than an `Integer`, since UPI check characters can be letters. A UPI shares the 12-character length bucket with ISIN and can double-detect (ISIN ranked first) when its digit check character also satisfies ISIN's Luhn checksum.
 
 ### Changed
 
-- BREAKING: Renamed the check-digit concept to **checksum** across the entire public API, because the old name was wrong on two axes — DTI's and UPI's check value is a `String` (it can be a letter, not a digit), and LEI and IBAN carry a two-character check value. The instance and class methods `check_digit` → `checksum`, `calculate_check_digit` → `calculate_checksum`, and `has_check_digit?` → `has_checksum?`; the error class `SecID::InvalidCheckDigitError` → `SecID::InvalidChecksumError`; the error code `:invalid_check_digit` → `:invalid_checksum` (a **hard flip with no dual emission** — dual would duplicate `errors.details` entries, so update any `errors.details`/`explain`/ActiveModel `details: true` matcher immediately); and the `:check_digit` components key → `:checksum` in `to_h`/`deconstruct_keys` across all nine checkable types. `restore`/`restore!` and the `Checkable` concern name are unchanged. No validation or checksum-arithmetic behavior changed: every identifier that was valid stays valid and every computed value is byte-identical. The old method names, the `InvalidCheckDigitError` constant, and the `:check_digit` components key remain as deprecated bridges through v7 (removed in v8); the error code is the only surface with no bridge. See MIGRATION.md for the full upgrade guide
+- BREAKING: Renamed the check-digit concept to **checksum** across the entire public API, because the old name was wrong on two axes. DTI's and UPI's check value is a `String` (it can be a letter, not a digit), and LEI and IBAN carry a two-character check value. The instance and class methods `check_digit` → `checksum`, `calculate_check_digit` → `calculate_checksum`, and `has_check_digit?` → `has_checksum?`; the error class `SecID::InvalidCheckDigitError` → `SecID::InvalidChecksumError`; the error code `:invalid_check_digit` → `:invalid_checksum` (a **hard flip with no dual emission**: dual would duplicate `errors.details` entries, so update any `errors.details`/`explain`/ActiveModel `details: true` matcher immediately); and the `:check_digit` components key → `:checksum` in `to_h`/`deconstruct_keys` across all nine checkable types. `restore`/`restore!` and the `Checkable` concern name are unchanged. No validation or checksum-arithmetic behavior changed: every identifier that was valid stays valid and every computed value is byte-identical. The old method names, the `InvalidCheckDigitError` constant, and the `:check_digit` components key remain as deprecated bridges through v7 (removed in v8); the error code is the only surface with no bridge. See MIGRATION.md for the full upgrade guide
 
 ### Deprecated
 
-- The pre-rename check-digit names, kept as v7 bridges and removed in v8: the `check_digit` / `calculate_check_digit` / `has_check_digit?` methods (instance and class level) — each warns via `Kernel#warn` on every call, visible at Ruby's default verbosity and silenceable with `-W0` / `$VERBOSE = nil` or an app-level `Warning` override; the `SecID::InvalidCheckDigitError` constant, a same-object alias of `InvalidChecksumError` so `rescue` under either name keeps working; and the `:check_digit` key, still present alongside `:checksum` in `components` / `to_h` / `deconstruct_keys`
+- The pre-rename check-digit names, kept as v7 bridges and removed in v8: the `check_digit` / `calculate_check_digit` / `has_check_digit?` methods (instance and class level). Each warns via `Kernel#warn` on every call, visible at Ruby's default verbosity and silenceable with `-W0` / `$VERBOSE = nil` or an app-level `Warning` override; the `SecID::InvalidCheckDigitError` constant, a same-object alias of `InvalidChecksumError` so `rescue` under either name keeps working; and the `:check_digit` key, still present alongside `:checksum` in `components` / `to_h` / `deconstruct_keys`
 
 ## [6.1.0] - 2026-07-10
 
 ### Added
 
-- `SecID::Base#deconstruct_keys` — every identifier now destructures in `case/in` patterns, exposing the same parsed fields `#to_h` reports under `:components`. The `keys` argument is ignored, no new keys are introduced, and validity is not part of the protocol: `SecID.parse` returning `nil` remains the validity guard, and an instance built from unparseable input binds `nil` for each component. No `deconstruct` (array-pattern) method is defined
-- `SecID::Base.type_key` — the memoized class-level registry symbol for an identifier type, joining the existing `short_name` / `full_name` / `id_length` metadata surface. It round-trips through the registry: `SecID[SecID::ISIN.type_key] == SecID::ISIN`. It is now the single authority for that symbol; the registry, `#to_h`, `SecID.explain`, the ActiveModel validator, the detector, and the scanner all read it instead of each deriving it from the class name
+- `SecID::Base#deconstruct_keys`: every identifier now destructures in `case/in` patterns, exposing the same parsed fields `#to_h` reports under `:components`. The `keys` argument is ignored, no new keys are introduced, and validity is not part of the protocol: `SecID.parse` returning `nil` remains the validity guard, and an instance built from unparseable input binds `nil` for each component. No `deconstruct` (array-pattern) method is defined
+- `SecID::Base.type_key`: the memoized class-level registry symbol for an identifier type, joining the existing `short_name` / `full_name` / `id_length` metadata surface. It round-trips through the registry: `SecID[SecID::ISIN.type_key] == SecID::ISIN`. It is now the single authority for that symbol; the registry, `#to_h`, `SecID.explain`, the ActiveModel validator, the detector, and the scanner all read it instead of each deriving it from the class name
 
 ## [6.0.0] - 2026-07-08
 
 ### Added
 
-- Hand-written RBS type signatures under `sig/`, shipped in the gem, so consumers running Steep or an RBS-aware editor resolve sec_id's types on install. The core library is checked by Steep in strict mode with zero errors and verified at runtime against the specs via RBS::Test. New dev/test tooling (`rbs` and `steep`, `require: false` — the gem stays zero-runtime-dependency) and rake tasks: `rake steep` (strict type check), `rake steep:coverage` (untyped-call gate), `rake rbs:test` (runtime signature verification), `rake rbs` (validate signatures, in the default task), and `rake sig:cfi` (regenerate the CFI dynamic-method signatures from `SecID::CFI::Tables`, guarded by a drift spec). CI gains a `types` job on Ruby 4.0. The optional ActiveModel adapter and Railtie are excluded from the typed scope
-- `SecID::CFI#decode` returns a frozen `SecID::CFI::Classification` value object for any valid CFI (`nil` for invalid). Its category, group, and each attribute are `Field` objects carrying the CFI letter (`#code`), semantic symbol (`#name`), and authoritative ISO 10962 label (`#label`), plus `<name>?` predicates scoped to the field's own domain — so `decode.category.equity?` and `decode.attributes.voting_right.voting?` answer, while an out-of-domain predicate (e.g. `category.voting?`) raises `NoMethodError`. `#attributes` is an `Enumerable` of the attribute fields keyed by each position's group meaning (`attributes.voting_right`, nil-safe `attributes[:form]`). Ships a human-readable `#to_s` and `#to_h`/`#as_json` for serialization. `X` decodes to `:not_applicable`; pure-N/A positions are omitted
-- `SecID::CFI` now validates the full ISO 10962:2021 attribute matrix — positions 3–6 are checked per-group, `Strategies` (`K`) codes require `XXXX`, pure-N/A positions accept only `X`, and the `ED` (depositary receipts on equities) cross-position rule is enforced. A new `:invalid_attribute` error code (mapped to `InvalidStructureError`) names the offending positions and group
-- Opt-in ActiveModel / Rails validator (`require 'sec_id/active_model'`), registered as `sec_id`, for declarative validation: `validates :isin, sec_id: { type: :isin }`. Validates a single type (`type:`), an allowlist (`types:`), or any supported type (`sec_id: true`); a bad type raises `ArgumentError` at class-load. Opt-in `normalize: true` accepts separatored input and rewrites the attribute to canonical form on success; opt-in `details: true` surfaces the specific failure reason. Auto-activates in Rails via a Railtie (no `require:`/initializer needed) and adds **no runtime dependency** — nothing on the default `require 'sec_id'` path loads Rails or ActiveModel. Tested across Rails 7.2, 8.0, 8.1, and main
-- BIC / SWIFT code (ISO 9362) support via `SecID::BIC` — validate, normalize, parse, detect, extract, and generate 8- or 11-character Business Identifier Codes. Exposes `bank_code`, `country_code`, `location_code`, and `branch_code` (`nil` for a BIC8) components. Validates the embedded country code against a frozen ISO 3166-1 / SWIFT-recognized set (`SecID::BIC.countries`), raising `InvalidStructureError` (`:invalid_country`) for unrecognized codes. Validation confirms structure and a real country code only — it does not verify registration in the licensed SWIFT registry
-- DTI (ISO 24165, Digital Token Identifier) support via `SecID::DTI` — the gem's 15th identifier type, and the first offline DTI validator in any language. Validates the ISO 7064 hybrid MOD 31,30 check character over the 30-symbol DTI alphabet (digits plus consonants; vowels and `Y` never appear), identified empirically from public registry data (1,595 of 1,596 snapshot codes plus 2 post-snapshot registrations). Bitcoin's hand-assigned code (`4H95J0R2X`, which fails the algorithm) is honored via a frozen exception map consulted by `valid?`, `restore`, and `check_digit` alike. Unlike every other check-digit type in the gem, `check_digit`/`calculate_check_digit` return a `String` rather than an `Integer`, since DTI check characters can be letters
-- `.generate` on all 15 identifier types plus a central `SecID.generate(:type)` dispatcher for producing syntactically valid identifiers (with correct check digits where applicable) as test fixtures — accepts an optional `random:` keyword (a Ruby `Random`) for reproducible output. Generated values are valid in format only and are not real, registered securities
-- 100% YARD documentation coverage of the public API, enforced in CI via `rake yard:stats`. The gem now ships a `.yardopts` so `rubydoc.info` renders the public API cleanly (private internals hidden, README/CHANGELOG/LICENSE as pages) and exposes `documentation_uri` metadata (a Documentation link on the RubyGems page). Adds a `yard` dev/test dependency (`require: false` — the gem stays zero-runtime-dependency) and a `rake yard` task for local HTML docs
+- Hand-written RBS type signatures under `sig/`, shipped in the gem, so consumers running Steep or an RBS-aware editor resolve sec_id's types on install. The core library is checked by Steep in strict mode with zero errors and verified at runtime against the specs via RBS::Test. New dev/test tooling (`rbs` and `steep`, `require: false`; the gem stays zero-runtime-dependency) and rake tasks: `rake steep` (strict type check), `rake steep:coverage` (untyped-call gate), `rake rbs:test` (runtime signature verification), `rake rbs` (validate signatures, in the default task), and `rake sig:cfi` (regenerate the CFI dynamic-method signatures from `SecID::CFI::Tables`, guarded by a drift spec). CI gains a `types` job on Ruby 4.0. The optional ActiveModel adapter and Railtie are excluded from the typed scope
+- `SecID::CFI#decode` returns a frozen `SecID::CFI::Classification` value object for any valid CFI (`nil` for invalid). Its category, group, and each attribute are `Field` objects carrying the CFI letter (`#code`), semantic symbol (`#name`), and authoritative ISO 10962 label (`#label`), plus `<name>?` predicates scoped to the field's own domain, so `decode.category.equity?` and `decode.attributes.voting_right.voting?` answer, while an out-of-domain predicate (e.g. `category.voting?`) raises `NoMethodError`. `#attributes` is an `Enumerable` of the attribute fields keyed by each position's group meaning (`attributes.voting_right`, nil-safe `attributes[:form]`). Ships a human-readable `#to_s` and `#to_h`/`#as_json` for serialization. `X` decodes to `:not_applicable`; pure-N/A positions are omitted
+- `SecID::CFI` now validates the full ISO 10962:2021 attribute matrix: positions 3 to 6 are checked per-group, `Strategies` (`K`) codes require `XXXX`, pure-N/A positions accept only `X`, and the `ED` (depositary receipts on equities) cross-position rule is enforced. A new `:invalid_attribute` error code (mapped to `InvalidStructureError`) names the offending positions and group
+- Opt-in ActiveModel / Rails validator (`require 'sec_id/active_model'`), registered as `sec_id`, for declarative validation: `validates :isin, sec_id: { type: :isin }`. Validates a single type (`type:`), an allowlist (`types:`), or any supported type (`sec_id: true`); a bad type raises `ArgumentError` at class-load. Opt-in `normalize: true` accepts separatored input and rewrites the attribute to canonical form on success; opt-in `details: true` surfaces the specific failure reason. Auto-activates in Rails via a Railtie (no `require:`/initializer needed) and adds **no runtime dependency**: nothing on the default `require 'sec_id'` path loads Rails or ActiveModel. Tested across Rails 7.2, 8.0, 8.1, and main
+- BIC / SWIFT code (ISO 9362) support via `SecID::BIC`: validate, normalize, parse, detect, extract, and generate 8- or 11-character Business Identifier Codes. Exposes `bank_code`, `country_code`, `location_code`, and `branch_code` (`nil` for a BIC8) components. Validates the embedded country code against a frozen ISO 3166-1 / SWIFT-recognized set (`SecID::BIC.countries`), raising `InvalidStructureError` (`:invalid_country`) for unrecognized codes. Validation confirms structure and a real country code only. It does not verify registration in the licensed SWIFT registry
+- DTI (ISO 24165, Digital Token Identifier) support via `SecID::DTI`: the gem's 15th identifier type, and the first offline DTI validator in any language. Validates the ISO 7064 hybrid MOD 31,30 check character over the 30-symbol DTI alphabet (digits plus consonants; vowels and `Y` never appear), identified empirically from public registry data (1,595 of 1,596 snapshot codes plus 2 post-snapshot registrations). Bitcoin's hand-assigned code (`4H95J0R2X`, which fails the algorithm) is honored via a frozen exception map consulted by `valid?`, `restore`, and `check_digit` alike. Unlike every other check-digit type in the gem, `check_digit`/`calculate_check_digit` return a `String` rather than an `Integer`, since DTI check characters can be letters
+- `.generate` on all 15 identifier types plus a central `SecID.generate(:type)` dispatcher for producing syntactically valid identifiers (with correct check digits where applicable) as test fixtures. Accepts an optional `random:` keyword (a Ruby `Random`) for reproducible output. Generated values are valid in format only and are not real, registered securities
+- 100% YARD documentation coverage of the public API, enforced in CI via `rake yard:stats`. The gem now ships a `.yardopts` so `rubydoc.info` renders the public API cleanly (private internals hidden, README/CHANGELOG/LICENSE as pages) and exposes `documentation_uri` metadata (a Documentation link on the RubyGems page). Adds a `yard` dev/test dependency (`require: false`; the gem stays zero-runtime-dependency) and a `rake yard` task for local HTML docs
 
 ### Changed
 
 - Internal `@api private` IBAN country-data module dissolved into the `SecID::IBAN` class, so constant names match their file paths per Ruby convention: `SecID::IBANCountryRules::COUNTRY_RULES` / `LENGTH_ONLY_COUNTRIES` are now `SecID::IBAN::COUNTRY_RULES` / `SecID::IBAN::LENGTH_ONLY_COUNTRIES`
-- `SecID.valid?` and `SecID.parse` are faster and allocate less — `SecID.valid?` short-circuits on the first matching type instead of running a full detect-and-sort, and `SecID.parse` reuses the instance built during detection instead of instantiating the matched type a second time
-- **BREAKING:** `SecID::CFI.valid?` is now strict at the attribute level for all 14 categories (including the derivative categories `S`, `H`, `J`) — codes with attribute letters outside the ISO 10962:2021 tables, previously accepted, are now invalid (e.g. `CFI.valid?('ESZZZZ')` returns `false`). There is no leniency option, matching every other identifier type in the gem. The ActiveModel validator inherits this strictness automatically
-- **BREAKING:** `SecID::CFI` group tables corrected to ISO 10962:2021 — six categories carried wrong group letters. Non-listed options (`H`) are now classified by underlying (`HR` Rates, `HT` Commodities, `HE` Equity, `HC` Credit, `HF` FX, `HM` Others) instead of the copied listed-option call/put shape; `D` gains `DE` (structured products without capital protection) and corrects `DG`/`DA`/`DN` (dropping the invented `municipal_notes`); `L` becomes `LL`/`LR`/`LS`, `T` becomes `TC`/`TT`/`TR`/`TI`/…, and the phantom `FM`/`IM`/`JM`/`LM` groups are removed. Group symbols renamed accordingly (e.g. `LS` → `:securities_lending`, `TI` → `:indices`, `MM` → `:other_assets`). Real `H`-category codes that were rejected now validate; codes relying on the old wrong letters no longer do
+- `SecID.valid?` and `SecID.parse` are faster and allocate less. `SecID.valid?` short-circuits on the first matching type instead of running a full detect-and-sort, and `SecID.parse` reuses the instance built during detection instead of instantiating the matched type a second time
+- **BREAKING:** `SecID::CFI.valid?` is now strict at the attribute level for all 14 categories (including the derivative categories `S`, `H`, `J`). Codes with attribute letters outside the ISO 10962:2021 tables, previously accepted, are now invalid (e.g. `CFI.valid?('ESZZZZ')` returns `false`). There is no leniency option, matching every other identifier type in the gem. The ActiveModel validator inherits this strictness automatically
+- **BREAKING:** `SecID::CFI` group tables corrected to ISO 10962:2021: six categories carried wrong group letters. Non-listed options (`H`) are now classified by underlying (`HR` Rates, `HT` Commodities, `HE` Equity, `HC` Credit, `HF` FX, `HM` Others) instead of the copied listed-option call/put shape; `D` gains `DE` (structured products without capital protection) and corrects `DG`/`DA`/`DN` (dropping the invented `municipal_notes`); `L` becomes `LL`/`LR`/`LS`, `T` becomes `TC`/`TT`/`TR`/`TI`/…, and the phantom `FM`/`IM`/`JM`/`LM` groups are removed. Group symbols renamed accordingly (e.g. `LS` → `:securities_lending`, `TI` → `:indices`, `MM` → `:other_assets`). Real `H`-category codes that were rejected now validate; codes relying on the old wrong letters no longer do
 
 ### Removed
 
-- **BREAKING:** the 12 hardcoded equity predicate helpers on `SecID::CFI` (`equity?`, `voting?`, `non_voting?`, `restricted_voting?`, `enhanced_voting?`, `restrictions?`, `no_restrictions?`, `fully_paid?`, `nil_paid?`, `partly_paid?`, `bearer?`, `registered?`). They were category-wide and semantically wrong for non-equity groups. Migration: use `cfi.decode` and its scoped field predicates — `cfi.voting?` → `cfi.decode.attributes.voting_right.voting?` — which answer only on the field whose ISO domain defines the concept. Two names do not carry over name-for-name: migrate `cfi.equity?` to `cfi.decode.category.equity?` (or `cfi.category == :equity`, unchanged), and `cfi.no_restrictions?` to `cfi.decode.attributes.ownership_restrictions.free_of_restrictions?` (the ISO value name)
+- **BREAKING:** the 12 hardcoded equity predicate helpers on `SecID::CFI` (`equity?`, `voting?`, `non_voting?`, `restricted_voting?`, `enhanced_voting?`, `restrictions?`, `no_restrictions?`, `fully_paid?`, `nil_paid?`, `partly_paid?`, `bearer?`, `registered?`). They were category-wide and semantically wrong for non-equity groups. Migration: use `cfi.decode` and its scoped field predicates, so `cfi.voting?` becomes `cfi.decode.attributes.voting_right.voting?`, which answers only on the field whose ISO domain defines the concept. Two names do not carry over name-for-name: migrate `cfi.equity?` to `cfi.decode.category.equity?` (or `cfi.category == :equity`, unchanged), and `cfi.no_restrictions?` to `cfi.decode.attributes.ownership_restrictions.free_of_restrictions?` (the ISO value name)
 
 ## [5.2.0] - 2026-02-24
 
 ### Added
 
-- `SecID.scan` and `SecID.extract` methods for finding identifiers in freeform text — returns `Scanner::Match` objects (`Data.define(:type, :raw, :range, :identifier)`) with the validated identifier instance; supports `types:` filtering, hyphenated identifiers, and compound patterns (OCC with spaces, FISN with slashes)
-- `SecID.explain` method for debugging identifier detection — returns per-type validation results showing exactly why each type matched or rejected the input
-- `on_ambiguous:` option for `SecID.parse` and `SecID.parse!` — `:first` (default, existing behavior), `:raise` (raises `AmbiguousMatchError`), `:all` (returns array of all matching instances)
+- `SecID.scan` and `SecID.extract` methods for finding identifiers in freeform text. Returns `Scanner::Match` objects (`Data.define(:type, :raw, :range, :identifier)`) with the validated identifier instance; supports `types:` filtering, hyphenated identifiers, and compound patterns (OCC with spaces, FISN with slashes)
+- `SecID.explain` method for debugging identifier detection. Returns per-type validation results showing exactly why each type matched or rejected the input
+- `on_ambiguous:` option for `SecID.parse` and `SecID.parse!`: `:first` (default, existing behavior), `:raise` (raises `AmbiguousMatchError`), `:all` (returns array of all matching instances)
 - `SecID::AmbiguousMatchError` exception class for ambiguous identifier detection
 - `#as_json` method on all identifier types (delegates to `#to_h`) and on `Errors` (delegates to `#details`) for JSON serialization compatibility
 - `SecID::IBAN.supported_countries` class method returning sorted array of all supported country codes
@@ -71,9 +89,9 @@ and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
 ### Added
 
-- `#==`, `#eql?`, and `#hash` methods on all identifier types — two instances of the same type with the same normalized form are equal and usable as Hash keys / in Sets
-- `#to_h` method on all identifier types for consistent hash serialization — returns `{ type:, full_id:, normalized:, valid:, components: }` with type-specific component hashes (e.g. ISIN: `country_code`, `nsin`, `check_digit`)
-- `#to_pretty_s` and `.to_pretty_s` display formatting methods on all identifier types, returning a human-readable string or `nil` for invalid input — with type-specific formats for IBAN (4-char groups), LEI (4-char groups), ISIN (CC + NSIN + CD), CUSIP (cusip6 + issue + CD), FIGI (prefix+G + random + CD), OCC (space-separated components), and Valoren (thousands grouping)
+- `#==`, `#eql?`, and `#hash` methods on all identifier types. Two instances of the same type with the same normalized form are equal and usable as Hash keys / in Sets
+- `#to_h` method on all identifier types for consistent hash serialization. Returns `{ type:, full_id:, normalized:, valid:, components: }` with type-specific component hashes (e.g. ISIN: `country_code`, `nsin`, `check_digit`)
+- `#to_pretty_s` and `.to_pretty_s` display formatting methods on all identifier types, returning a human-readable string or `nil` for invalid input, with type-specific formats for IBAN (4-char groups), LEI (4-char groups), ISIN (CC + NSIN + CD), CUSIP (cusip6 + issue + CD), FIGI (prefix+G + random + CD), OCC (space-separated components), and Valoren (thousands grouping)
 - Lookup service integration guides and runnable examples for OpenFIGI, SEC EDGAR, GLEIF, and Eurex APIs (`docs/guides/`, `examples/`)
 - GitHub community standards files: Code of Conduct, Contributing guide, Security policy, issue templates, and PR template
 
@@ -111,15 +129,15 @@ and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
 ### Removed
 
-- Class-level `.normalize!` on CIK, OCC, and Valoren — replaced by `.normalize`
+- Class-level `.normalize!` on CIK, OCC, and Valoren, replaced by `.normalize`
 - `upcase` keyword parameter from `Base#parse`
 - `#valid_format?` instance method (now private) and `.valid_format?` class method
-- `OCC#full_symbol` method — use `#full_id` instead
+- `OCC#full_symbol` method. Use `#full_id` instead
 
 ### Fixed
 
-- `to_str` now always returns the same value as `to_s` across all identifier types — previously LEI, IBAN, and Checkable identifiers could return divergent strings due to Ruby `alias` resolving to the parent class method
-- OCC `#date` memoization for invalid dates — previously re-attempted parsing on every call instead of caching `nil`
+- `to_str` now always returns the same value as `to_s` across all identifier types. Previously LEI, IBAN, and Checkable identifiers could return divergent strings due to Ruby `alias` resolving to the parent class method
+- OCC `#date` memoization for invalid dates. Previously it re-attempted parsing on every call instead of caching `nil`
 - LEI `restore` and `to_s` now correctly pad single-digit check digits to 2 characters
 - `Valoren#to_isin` no longer mutates the source instance
 
@@ -153,7 +171,7 @@ and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 ### Fixed
 
 - Allow Crown Dependencies (GG, IM, JE) and Overseas Territories (FK) in SEDOL/ISIN conversions ([@wtn](https://github.com/wtn), [#117](https://github.com/svyatov/sec_id/pull/117))
-- Removed BR (Brazil) from CGS country codes — Brazil never used CINS numbers and Brazilian ISINs cannot be converted to CUSIP ([@wtn](https://github.com/wtn), [#110](https://github.com/svyatov/sec_id/pull/110))
+- Removed BR (Brazil) from CGS country codes. Brazil never used CINS numbers and Brazilian ISINs cannot be converted to CUSIP ([@wtn](https://github.com/wtn), [#110](https://github.com/svyatov/sec_id/pull/110))
 
 ## [4.3.0] - 2025-01-13
 
@@ -168,7 +186,7 @@ and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 - Refactored CIK and OCC to inherit from Base class with `has_check_digit?` hook for cleaner architecture
 - Added `Normalizable` module for consistent `normalize!` class method across identifiers
 - Added `validate_format_for_calculation!` helper method to Base class to reduce code duplication
-- Added comprehensive YARD documentation to all classes (public and private methods)
+- Added YARD documentation to all classes (public and private methods)
 - Applied Stepdown Rule to method ordering throughout codebase
 - Created shared RSpec examples for edge cases (nil, empty, whitespace inputs)
 - Created shared RSpec examples for check-digit and normalization identifiers
@@ -226,6 +244,10 @@ and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 - TravisCI config updated: dropped Ruby 2.3 and 2.4, added Ruby 2.7
 - Rubocop's Ruby target version changed to 2.5
 
+## [2.0.1] - 2019-02-04
+
+Gem metadata only: corrected the gemspec description and README wording. No library change.
+
 ## [2.0.0] - 2019-02-03
 
 ### Added
@@ -262,3 +284,24 @@ and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 ### Added
 
 - ISIN numbers support: `SecID::ISIN`
+
+[Unreleased]: https://github.com/svyatov/sec_id/compare/v7.1.1...HEAD
+[7.1.1]: https://github.com/svyatov/sec_id/compare/v7.1.0...v7.1.1
+[7.1.0]: https://github.com/svyatov/sec_id/compare/v7.0.0...v7.1.0
+[7.0.0]: https://github.com/svyatov/sec_id/compare/v6.1.0...v7.0.0
+[6.1.0]: https://github.com/svyatov/sec_id/compare/v6.0.0...v6.1.0
+[6.0.0]: https://github.com/svyatov/sec_id/compare/v5.2.0...v6.0.0
+[5.2.0]: https://github.com/svyatov/sec_id/compare/v5.1.0...v5.2.0
+[5.1.0]: https://github.com/svyatov/sec_id/compare/v5.0.0...v5.1.0
+[5.0.0]: https://github.com/svyatov/sec_id/compare/v4.4.1...v5.0.0
+[4.4.1]: https://github.com/svyatov/sec_id/compare/v4.4.0...v4.4.1
+[4.4.0]: https://github.com/svyatov/sec_id/compare/v4.3.0...v4.4.0
+[4.3.0]: https://github.com/svyatov/sec_id/compare/v4.2.0...v4.3.0
+[4.2.0]: https://github.com/svyatov/sec_id/compare/v4.1.0...v4.2.0
+[4.1.0]: https://github.com/svyatov/sec_id/compare/v4.0.0...v4.1.0
+[4.0.0]: https://github.com/svyatov/sec_id/compare/v3.0.0...v4.0.0
+[3.0.0]: https://github.com/svyatov/sec_id/compare/v2.0.1...v3.0.0
+[2.0.1]: https://github.com/svyatov/sec_id/compare/v2.0.0...v2.0.1
+[2.0.0]: https://github.com/svyatov/sec_id/compare/v1.1.0...v2.0.0
+[1.1.0]: https://github.com/svyatov/sec_id/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/svyatov/sec_id/releases/tag/v1.0.0

data/README.md

@@ -1,18 +1,27 @@
-# 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)
+# SecID
 
-> 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
+[![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)
 
-- [Supported Ruby Versions](#supported-ruby-versions)
+- **Nothing to call, nothing to sign up for.** SecID validates all 16 identifier standards offline. No registry lookup, no API key, no network call anywhere in [`lib/`](lib/).
+- **9 of the 16 carry a checksum.** SecID validates it, restores a missing one, and repairs a wrong one.
+- **Zero runtime dependencies.** Runs on Ruby 3.2 or newer.
+- **Rails, if you want it.** An opt-in ActiveModel validator adds `validates :isin, sec_id: true`. It stays off the default require path, so the dependency count stays at zero.
+- **Typed.** Ships RBS signatures for the whole public API, checked by Steep in strict mode.
+
+## Table of contents
+
+- [Supported Ruby versions](#supported-ruby-versions)
 - [Installation](#installation)
-- [Supported Standards and Usage](#supported-standards-and-usage)
-  - [Metadata Registry](#metadata-registry) - enumerate, filter, look up, and detect identifier types
-  - [Text Scanning](#text-scanning) - find identifiers in freeform text
-  - [Debugging Detection](#debugging-detection) - understand why strings match or don't
-  - [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
+- [Supported standards and usage](#supported-standards-and-usage)
+  - [Metadata registry](#metadata-registry) - enumerate, filter, look up, and detect identifier types
+  - [Text scanning](#text-scanning) - find identifiers in freeform text
+  - [Debugging detection](#debugging-detection) - understand why strings match or don't
+  - [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
@@ -29,16 +38,17 @@
   - [BIC](#bic) - Business Identifier Code / SWIFT code
   - [DTI](#dti) - Digital Token Identifier
   - [UPI](#upi) - Unique Product Identifier
-- [ActiveModel / Rails Validator](#activemodel--rails-validator) - declarative `validates :isin, sec_id: {...}`
-- [Lookup Service Integration](#lookup-service-integration)
-- [Type Signatures (RBS)](#type-signatures-rbs)
+- [ActiveModel / Rails validator](#activemodel--rails-validator) - declarative `validates :isin, sec_id: {...}`
+- [Lookup service integration](#lookup-service-integration)
+- [Type signatures (RBS)](#type-signatures-rbs)
 - [Development](#development)
+- [Support and status](#support-and-status)
 - [Contributing](#contributing)
 - [Changelog](#changelog)
 - [Versioning](#versioning)
 - [License](#license)
 
-## Supported Ruby Versions
+## Supported Ruby versions
 
 Ruby 3.2+ is required.
 
@@ -47,7 +57,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:
@@ -64,7 +74,7 @@ gem install sec_id
 
 **Upgrading from v4?** See [MIGRATION.md](MIGRATION.md) for a step-by-step guide.
 
-## Supported Standards and Usage
+## Supported standards and usage
 
 All identifier classes provide `valid?`, `errors`, `validate`, `validate!` methods at both class and instance levels.
 
@@ -89,7 +99,7 @@ SecID::ISIN.new('INVALID').to_h
 #      valid: false, components: { country_code: nil, nsin: nil, checksum: nil } }
 ```
 
-**All identifiers** support value equality — two instances of the same type with the same normalized form are equal:
+**All identifiers** support value equality. Two instances of the same type with the same normalized form are equal:
 
 ```ruby
 a = SecID::ISIN.new('US5949181045')
@@ -108,7 +118,7 @@ Set.new([a, b]).size         # => 1
 - `restore!` / `.restore!` - restores checksum in place and returns `self` / instance
 - `checksum` / `calculate_checksum` - calculates and returns the checksum
 
-### Metadata Registry
+### Metadata registry
 
 All identifier classes are registered automatically and can be enumerated, filtered, and looked up by symbol key:
 
@@ -164,7 +174,7 @@ SecID.parse('514000', on_ambiguous: :all)          # => [#<SecID::WKN>, #<SecID:
 SecID.parse('US5949181045', on_ambiguous: :raise)  # => #<SecID::ISIN> (unambiguous, no error)
 ```
 
-### Text Scanning
+### Text scanning
 
 Find identifiers embedded in freeform text:
 
@@ -190,12 +200,12 @@ match.identifier.normalized  # => "US5949181045"
 
 > **Known limitations:** Format-only types (CIK, Valoren, WKN, BIC) can false-positive on
 > common numbers and short words in prose (a BIC8 is 8 letters with a valid country code in the
-> middle) — use the `types:` filter to restrict scanning when
+> middle). Use the `types:` filter to restrict scanning when
 > this is a concern. Identifiers prefixed with special characters (e.g. `#US5949181045`) may be
 > consumed as a single token by CUSIP's `*@#` character class and fail validation, preventing
 > the embedded identifier from being found.
 
-### Debugging Detection
+### Debugging detection
 
 Understand why a string matches or doesn't match specific identifier types:
 
@@ -209,7 +219,7 @@ isin[:errors].first[:error]       # => :invalid_checksum
 SecID.explain('US5949181045', types: %i[isin cusip])
 ```
 
-### Structured Validation
+### Structured validation
 
 All identifier classes provide a Rails-like `#errors` API for detailed error reporting:
 
@@ -265,7 +275,7 @@ SecID::FIGI.new('BSG000BLNNH6').validate!
 isin = SecID::ISIN.validate!('US5949181045')  # => #<SecID::ISIN>
 ```
 
-### Pattern Matching
+### Pattern matching
 
 Every identifier destructures in `case/in` via its parsed components. Since `SecID.parse` returns `nil` for
 anything invalid, an `in nil` branch is a complete validity guard:
@@ -305,11 +315,11 @@ CIK, WKN, and Valoren have no sub-fields: they match a bare `in SecID::CIK` but
 
 Watch the `:type` key: on a `SecID::Match` it is the registry symbol (`:occ`), while on an `OCC` instance it is the
 OSI option type (`'C'` or `'P'`), so `in SecID::OCC[type: :occ]` never matches. Other types have no `:type` component
-at all — `#to_h`'s envelope keys (`:type`, `:full_id`, `:normalized`, `:valid`) are not part of the pattern surface.
+at all. `#to_h`'s envelope keys (`:type`, `:full_id`, `:normalized`, `:valid`) are not part of the pattern surface.
 
-### Generating Test Fixtures
+### Generating test fixtures
 
-Generate syntactically valid identifiers — with correct checksum where applicable — for use as test fixtures. Available per class and via the central dispatcher:
+Generate syntactically valid identifiers, with correct checksum where applicable, for use as test fixtures. Available per class and via the central dispatcher:
 
 ```ruby
 SecID::ISIN.generate          # => #<SecID::ISIN ...>
@@ -323,11 +333,47 @@ SecID.generate(:nope)         # => raises ArgumentError: Unknown identifier type
 SecID::LEI.generate(random: Random.new(42)) == SecID::LEI.generate(random: Random.new(42))  # => true
 ```
 
-> **Generated identifiers are valid in format only — they are not real, registered securities.**
+> **Generated identifiers are valid in format only. They are not real, registered securities.**
 > Country codes, FIGI prefixes, OCC expiry dates, and CFI category/group/attribute choices are
 > 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 such as `O`↔`0`, `I`↔`1`, `5`↔`S`, `8`↔`B`, plus 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 checksum-invalid candidate escapes,
+> but a valid candidate is not necessarily *the* correction, so 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), or an already-valid identifier (nothing to repair), 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.
@@ -666,7 +712,7 @@ SecID::CFI.new('QQXXXX').decode     # => nil (decode returns nil for an invalid
 
 CFI is validated strictly against the ISO 10962:2021 code tables for all 14 categories: the category (position 1), the group (position 2), and every attribute (positions 3-6) must be a value the standard defines for that group. `X` means "not applicable" and is accepted in every position; `Strategies` (`K`) codes carry no attributes and require `XXXX`. An impermissible attribute letter raises `InvalidStructureError` (`:invalid_attribute`).
 
-> **Migration from &lt; 6.0:** the old category-wide equity predicates (`cfi.voting?`, `cfi.fully_paid?`, …) are removed. Use `cfi.decode` and its scoped fields instead — a predicate now lives on the field whose domain defines it: `cfi.voting?` → `cfi.decode.attributes.voting_right.voting?`. Two do not map name-for-name: `cfi.equity?` → `cfi.decode.category.equity?` (or `cfi.category == :equity`), and `cfi.no_restrictions?` → `cfi.decode.attributes.ownership_restrictions.free_of_restrictions?`. Several group letters and symbols also changed to match ISO 10962:2021 (e.g. non-listed options `H` are now classified by underlying, and `LS` → `:securities_lending`, `TI` → `:indices`).
+> **Migration from &lt; 6.0:** the old category-wide equity predicates (`cfi.voting?`, `cfi.fully_paid?`, …) are removed. Use `cfi.decode` and its scoped fields instead. A predicate now lives on the field whose domain defines it: `cfi.voting?` → `cfi.decode.attributes.voting_right.voting?`. Two do not map name-for-name: `cfi.equity?` → `cfi.decode.category.equity?` (or `cfi.category == :equity`), and `cfi.no_restrictions?` → `cfi.decode.attributes.ownership_restrictions.free_of_restrictions?`. Several group letters and symbols also changed to match ISO 10962:2021 (e.g. non-listed options `H` are now classified by underlying, and `LS` → `:securities_lending`, `TI` → `:indices`).
 
 ```ruby
 # Introspect valid codes
@@ -721,7 +767,7 @@ SecID::BIC.valid?('DEUTZZFF')       # => false ('ZZ' is not a recognized country
 SecID::BIC.countries                # => ['AD', 'AE', 'AF', ...] (sorted, includes 'XK')
 ```
 
-BIC validation confirms structure and a real country code only. It does **not** verify that the institution, location, or branch corresponds to a registered SWIFT participant — that requires the licensed SWIFT registry.
+BIC validation confirms structure and a real country code only. It does **not** verify that the institution, location, or branch corresponds to a registered SWIFT participant. That requires the licensed SWIFT registry.
 
 ### DTI
 
@@ -745,7 +791,7 @@ dti.restore!                # => #<SecID::DTI> (mutates instance)
 dti.calculate_checksum  # => 'S'
 ```
 
-DTI accepts exactly 9 characters: an 8-character base (first character never `0`) plus 1 check character, both drawn from a 30-symbol alphabet — digits `0`-`9` and consonants (vowels and `Y` never appear). Unlike most checksum types in this gem, `checksum` and `calculate_checksum` return a `String`, not an `Integer` (as does UPI). The check character is computed fully offline via ISO 7064 hybrid MOD 31,30 — no registry lookup or paywalled ISO 24165-1 spec required.
+DTI accepts exactly 9 characters: an 8-character base (first character never `0`) plus 1 check character, both drawn from a 30-symbol alphabet: digits `0`-`9` and consonants (vowels and `Y` never appear). Unlike most checksum types in this gem, `checksum` and `calculate_checksum` return a `String`, not an `Integer` (as does UPI). The check character is computed fully offline via ISO 7064 hybrid MOD 31,30, with no registry lookup or paywalled ISO 24165-1 spec required.
 
 > **Grandfathered code:** Bitcoin's registered code (`4H95J0R2X`) predates the algorithm and fails the MOD 31,30 computation (which yields `4H95J0R2T`). A frozen exception map honors the registry's assignment across `valid?`, `restore`, and `checksum` alike:
 >
@@ -776,15 +822,15 @@ upi.restore!               # => #<SecID::UPI> (mutates instance)
 upi.calculate_checksum  # => '2'
 ```
 
-UPI accepts exactly 12 characters: a fixed `QZ` prefix, a 9-character body, and 1 check character, all drawn from the same 30-symbol alphabet as DTI — digits `0`-`9` and consonants (vowels and `Y` never appear). Like DTI, `checksum` and `calculate_checksum` return a `String`, not an `Integer`. The check character is computed fully offline via ISO 7064 hybrid MOD 31,30 over the 11 preceding characters — no DSB registry lookup or paywalled ISO 4914 spec required.
+UPI accepts exactly 12 characters: a fixed `QZ` prefix, a 9-character body, and 1 check character, all drawn from the same 30-symbol alphabet as DTI: digits `0`-`9` and consonants (vowels and `Y` never appear). Like DTI, `checksum` and `calculate_checksum` return a `String`, not an `Integer`. The check character is computed fully offline via ISO 7064 hybrid MOD 31,30 over the 11 preceding characters, with no DSB registry lookup or paywalled ISO 4914 spec required.
 
-> **Coexistence with ISIN:** a UPI shares the 12-character length bucket with ISIN. A UPI whose digit check character also satisfies ISIN's Luhn detects as both (`SecID.detect('QZXKR05S3DL1') # => [:isin, :upi]`), with ISIN ranked first; `SecID.parse(..., on_ambiguous: :raise)` surfaces the collision. UPI validation itself is fully offline and existence is **not** verified — that requires the licensed DSB registry.
+> **Coexistence with ISIN:** a UPI shares the 12-character length bucket with ISIN. A UPI whose digit check character also satisfies ISIN's Luhn detects as both (`SecID.detect('QZXKR05S3DL1') # => [:isin, :upi]`), with ISIN ranked first; `SecID.parse(..., on_ambiguous: :raise)` surfaces the collision. UPI validation itself is fully offline and existence is **not** verified. That requires the licensed DSB registry.
 
-## ActiveModel / Rails Validator
+## ActiveModel / Rails validator
 
-SecID ships an opt-in [ActiveModel](https://api.rubyonrails.org/classes/ActiveModel/Validations.html) validator, registered as `sec_id`, for declarative validation of any supported identifier type. It adds **no runtime dependency** — `require 'sec_id'` loads none of it, and ActiveModel is a development/test dependency only.
+SecID ships an opt-in [ActiveModel](https://api.rubyonrails.org/classes/ActiveModel/Validations.html) validator, registered as `sec_id`, for declarative validation of any supported identifier type. It adds **no runtime dependency**: `require 'sec_id'` loads none of it, and ActiveModel is a development/test dependency only.
 
-**In Rails it just works.** A Railtie loads the validator automatically after the framework boots, so `gem 'sec_id'` in your `Gemfile` is enough — no `require:` option and no initializer:
+**In Rails it just works.** A Railtie loads the validator automatically after the framework boots, so `gem 'sec_id'` in your `Gemfile` is enough, with no `require:` option and no initializer:
 
 ```ruby
 class Security < ApplicationRecord
@@ -801,13 +847,13 @@ require 'sec_id/active_model'
 ### Validation modes
 
 ```ruby
-# Single type — the value must be a valid ISIN
+# Single type: the value must be a valid ISIN
 validates :isin, sec_id: { type: :isin }
 
-# Allowlist — valid as at least one of the listed types
+# Allowlist: valid as at least one of the listed types
 validates :ref, sec_id: { types: %i[isin cusip] }
 
-# Type-agnostic — valid as any supported type
+# Type-agnostic: valid as any supported type
 validates :ref, sec_id: true
 ```
 
@@ -826,16 +872,16 @@ With `normalize: true` in allowlist or agnostic mode, a value valid as more than
 
 ### Error messages and `details:`
 
-On failure the validator adds one error under the `:sec_id` key with a type-aware default ("is not a valid ISIN" for a single type, "is not a valid securities identifier" for an allowlist/agnostic). Override the message in either of two ways: pass the standard `message:` option (the simplest, per-validation override), or define the attribute-scoped i18n key `activemodel.errors.models.<model>.attributes.<attribute>.sec_id` in your locale files. (The generic `activemodel.errors.messages.sec_id` key is not consulted, because the built-in default is supplied as ActiveModel's `message:` fallback.) Pass `details: true` (with a single `type:` — it is ignored for an allowlist/agnostic) to surface sec_id's specific reason instead of the generic text:
+On failure the validator adds one error under the `:sec_id` key with a type-aware default ("is not a valid ISIN" for a single type, "is not a valid securities identifier" for an allowlist/agnostic). Override the message in either of two ways: pass the standard `message:` option (the simplest, per-validation override), or define the attribute-scoped i18n key `activemodel.errors.models.<model>.attributes.<attribute>.sec_id` in your locale files. (The generic `activemodel.errors.messages.sec_id` key is not consulted, because the built-in default is supplied as ActiveModel's `message:` fallback.) Pass `details: true` (with a single `type:`; it is ignored for an allowlist/agnostic) to surface sec_id's specific reason instead of the generic text:
 
 ```ruby
 validates :isin, sec_id: { type: :isin, details: true }
 # a bad checksum reports e.g. "Checksum '4' is invalid, expected '5'"
 ```
 
-Standard `EachValidator` options — `allow_nil`, `allow_blank`, `if`, `unless`, `on` — work as usual. Tested against Rails 7.2, 8.0, and 8.1.
+Standard `EachValidator` options (`allow_nil`, `allow_blank`, `if`, `unless`, `on`) work as usual. Tested against Rails 7.2, 8.0, and 8.1.
 
-## Lookup Service Integration
+## Lookup service integration
 
 SecID validates identifiers but does not include HTTP clients. The [`docs/guides/`](docs/guides/) directory provides integration patterns for external lookup services using only stdlib (`net/http`, `json`):
 
@@ -848,10 +894,10 @@ SecID validates identifiers but does not include HTTP clients. The [`docs/guides
 
 Each guide includes a complete adapter class and a [runnable example](examples/).
 
-## Type Signatures (RBS)
+## Type signatures (RBS)
 
 sec_id ships hand-written [RBS](https://github.com/ruby/rbs) signatures under `sig/`,
-packaged in the gem — so if you use [Steep](https://github.com/soutaro/steep) or an
+packaged in the gem, so if you use [Steep](https://github.com/soutaro/steep) or an
 RBS-aware editor, sec_id's types resolve automatically on install, no `rbs collection`
 entry required. The only standard-library signature referenced is `date`, declared in
 `sig/manifest.yaml`.
@@ -877,10 +923,19 @@ committed signatures fall out of sync with the tables.
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies.
-Then, run `bundle exec rake` to run the tests. You can also run `bin/console`
-for an interactive prompt that will allow you to experiment.
+Then run `bundle exec rake` to run RuboCop, validate the RBS signatures, and run the specs.
+`bin/console` gives you an interactive prompt to experiment in.
+
+To use your working copy from another project, point its Gemfile at the checkout:
+`gem 'sec_id', path: '/path/to/sec_id'`.
+
+Releases are published from CI by pushing a tag, so there is no local publish task.
+
+## Support and status
+
+Ask questions in [Discussions](https://github.com/svyatov/sec_id/discussions). Report bugs in the [issue tracker](https://github.com/svyatov/sec_id/issues). Both are public and searchable, so the next reader with your question finds the answer.
 
-To install this gem onto your local machine, run `bundle exec rake install`.
+One person actively maintains SecID. They read bug reports and pull requests, and they track each identifier standard against its published specification. No response time is promised. See [Governance](CONTRIBUTING.md#governance) for who decides and what happens if they stop.
 
 ## Contributing
 
@@ -894,7 +949,21 @@ See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes, following [K
 
 ## Versioning
 
-This project follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html)
+This project follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
+
+The public API that version promise covers is everything documented in this README and in the [API docs](https://rubydoc.info/gems/sec_id), except anything marked `@api private` in YARD. Concretely, it covers:
+
+- the `SecID` module methods: `[]`, `identifiers`, `valid?`, `detect`, `parse`, `parse!`, `extract`, `scan`, `explain`, `generate`, and `suggest`
+- every identifier class and its documented instance and class methods
+- the `SecID::Errors`, `SecID::Suggestion`, `SecID::Scanner::Match`, and `SecID::CFI::Classification` value objects, and the exception hierarchy under `SecID::Error`
+- the `sec_id` ActiveModel validator and its options
+- the RBS signatures under `sig/`
+
+Marked `@api private` and outside the promise: `SecID::Detector`, `SecID::Scanner` itself, `SecID::CFI::Tables`, `SecID::IBAN::CountryRules`, `SecID::BIC::CountryCodes`, `Base.detection_priority`, and the internals of the four concerns. These can change in any release.
+
+Raising the minimum Ruby version is a breaking change and ships in a MAJOR release.
+
+Removals follow a deprecation window; see [Deprecation policy](CONTRIBUTING.md#deprecation-policy).
 
 ## License
 

data/lib/sec_id/active_model.rb

@@ -5,11 +5,11 @@ require 'sec_id'
 begin
   require 'active_model'
 rescue LoadError => e
-  # :nocov: ActiveModel is always loadable in the test suite
+  # simplecov:disable ActiveModel is always loadable in the test suite
   raise LoadError, 'sec_id/active_model requires ActiveModel, which could not be loaded. Add ' \
                    '`gem "activemodel"` to your Gemfile (or use this inside a Rails app) before ' \
                    "requiring 'sec_id/active_model'. (#{e.message})"
-  # :nocov:
+  # simplecov:enable
 end
 
 # ActiveModel validator for securities identifiers, registered under the `sec_id` key.
@@ -115,9 +115,10 @@ class SecIdValidator < ActiveModel::EachValidator
   # @return [String, nil] the message of the SecID::Error raised when normalizing `value` as `type`
   def capture_reason(type, value)
     SecID[type].normalize(value)
-    # :nocov: unreachable — only called after normalize already raised in valid_value?, kept as a safe fallback
+    # simplecov:disable unreachable — only called after normalize already raised in valid_value?,
+    # kept as a safe fallback
     nil
-    # :nocov:
+    # simplecov:enable
   rescue SecID::Error => e
     e.message
   end

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/checkable.rb

@@ -56,6 +56,10 @@ module SecID
       '*' => 36, '@' => 37, '#' => 38
     }.freeze
 
+    # Extends the including identifier class with the concern's class methods and checksum reader.
+    #
+    # @param base [Class] the identifier class including this concern
+    # @return [void]
     # @api private
     def self.included(base)
       base.attr_reader :checksum

data/lib/sec_id/concerns/generatable.rb

@@ -28,6 +28,10 @@ module SecID
     # Alphanumeric characters (digits then uppercase letters).
     ALPHANUMERIC = (DIGITS + ALPHA).freeze
 
+    # Extends the including identifier class with the concern's class methods.
+    #
+    # @param base [Class] the identifier class including this concern
+    # @return [void]
     # @api private
     def self.included(base)
       base.extend(ClassMethods)

data/lib/sec_id/concerns/normalizable.rb

@@ -8,6 +8,10 @@ module SecID
     # Characters stripped during normalization (whitespace and hyphens); classes may override.
     SEPARATORS = /[\s-]/
 
+    # Extends the including identifier class with the concern's class methods.
+    #
+    # @param base [Class] the identifier class including this concern
+    # @return [void]
     # @api private
     def self.included(base)
       base.extend(ClassMethods)

data/lib/sec_id/concerns/suggestable.rb

@@ -0,0 +1,173 @@
+# 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 checksum-invalid candidate ever escapes (a valid candidate is not
+  # necessarily the intended correction); 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
+
+    # Extends the including identifier class with the concern's class methods.
+    #
+    # @param base [Class] the identifier class including this concern
+    # @return [void]
+    # @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/concerns/validatable.rb

@@ -18,6 +18,10 @@ module SecID
       invalid_country: InvalidStructureError
     }.freeze
 
+    # Extends the including identifier class with the concern's class methods.
+    #
+    # @param base [Class] the identifier class including this concern
+    # @return [void]
     # @api private
     def self.included(base)
       base.extend(ClassMethods)

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,63 @@
+# 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
+
+    # Returns a JSON-compatible hash representation of the suggestion.
+    #
+    # @return [Hash] the symbol-keyed field hash (JSON-compatible)
+    def as_json(*)
+      to_h
+    end
+
+    # Returns the corrected identifier as a string.
+    #
+    # @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.1'
 end

data/lib/sec_id.rb

@@ -143,8 +143,42 @@ 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 do |suggestion|
+          [Suggestable::RANK.fetch(suggestion.edit), self[suggestion.type].detection_priority.last]
+        end
+    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 +240,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

@@ -10,10 +10,11 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Leonid Svyatov']
   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 ' \
+  spec.summary       = 'A Ruby toolkit for securities identifiers: validate, parse, normalize, detect, convert, ' \
+                       '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.1
 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
@@ -121,8 +126,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.12
+rubygems_version: 4.0.16
 specification_version: 4
-summary: A Ruby toolkit for securities identifiers — validate, parse, normalize, detect,
-  convert, generate, and classify.
+summary: 'A Ruby toolkit for securities identifiers: validate, parse, normalize, detect,
+  convert, generate, classify, and repair.'
 test_files: []