sec_id 6.1.0 → 7.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c705053b66b513f6cbac21702cd4548f5f446669f9251db569d62693698ff64
-  data.tar.gz: b792e03a67c57ead4064c392925771033c35b68fd984ad93aa5d932e37d1ea21
+  metadata.gz: 2ce3f9d548d4530dae973ee4ee4a7cf8e18898aaa36396423efe5ece7dd091f4
+  data.tar.gz: 5b7950a09cfc4afd59358b230fd659a9f26a1e58e50577ed16267f4763142a7f
 SHA512:
-  metadata.gz: 51880f7c27744b9700e01bca80a6f3a9a436d76a843921fdc97a401e12ef0acb2011c4f67a19034c30ea90e59638de0b66cb8a949b32d2d896e28a4f7957c4ba
-  data.tar.gz: 780d1cd07415046d2c5dfda3b6f548785ae0e244bdb294876440521f90475562000beaf493c88109d609e9c65fa83b94ad67c8509084174a84e52e6be9268543
+  metadata.gz: 34447319dc249c2fb3b7150cc45cc4a2aa8eed8e11ab16b726d9ee73d7aa2ad01daa2eed846f0cc788fb9f955488b161a91112ea6ec683268af7fa3fdf5267e0
+  data.tar.gz: 155fd8fe486ea96af91949ddd1adacb04310f50c820a2a5c1d98f1f55075545886c3935adfa5dacf2eedc9975ca7f1879c0e1140a8165dcd60736f24a0bcea94

data/CHANGELOG.md

@@ -8,6 +8,26 @@ 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
+
+- 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.
+
+### 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
+
+### 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`
+
 ## [6.1.0] - 2026-07-10
 
 ### Added

data/MIGRATION.md

@@ -1,3 +1,150 @@
+# Upgrading to SecID 7.0
+
+This guide covers all breaking changes when upgrading from SecID 6.x to 7.0. They are all one
+mechanical rename: the **check-digit** concept became **checksum** across the public API —
+methods, the error class, the error code, the components key, and documentation vocabulary.
+The name was inaccurate 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. `checksum` is
+type- and count-agnostic.
+
+Nothing about validation or checksum arithmetic changed — every previously valid identifier is
+still valid and every computed value is byte-identical. Only names, one error code, and
+deprecation warnings changed.
+
+## Quick Reference
+
+| What changed | Before (6.x) | After (7.0) |
+|---|---|---|
+| Instance/class method | `isin.check_digit`, `SecID::ISIN.check_digit(id)` | `isin.checksum`, `SecID::ISIN.checksum(id)` |
+| Calculation method | `isin.calculate_check_digit` | `isin.calculate_checksum` |
+| Capability predicate | `SecID::ISIN.has_check_digit?` | `SecID::ISIN.has_checksum?` |
+| Error class | `SecID::InvalidCheckDigitError` | `SecID::InvalidChecksumError` |
+| **Error code (hard flip)** | `:invalid_check_digit` | `:invalid_checksum` |
+| Components / `to_h` / pattern-match key | `{ check_digit: … }` | `{ checksum: … }` |
+
+`restore` / `restore!` and the `Checkable` concern name are unchanged.
+
+**Bridge:** the old method names, the `InvalidCheckDigitError` constant, and the `:check_digit`
+components key all keep working through v7 (the methods warn on use); they are removed in v8.
+**The one exception is the error code** — `:invalid_check_digit` flips hard to `:invalid_checksum`
+at v7 with no bridge, so an error-code matcher must be updated immediately.
+
+## Step-by-Step
+
+### 1. Update Gemfile
+
+```ruby
+gem 'sec_id', '~> 7.0'
+```
+
+Then run `bundle update sec_id`.
+
+### 2. Rename method calls (deprecated aliases warn through v7)
+
+```ruby
+# Before (6.x)
+isin.check_digit
+isin.calculate_check_digit
+SecID::ISIN.check_digit('US594918104')
+SecID::ISIN.has_check_digit?
+
+# After (7.0)
+isin.checksum
+isin.calculate_checksum
+SecID::ISIN.checksum('US594918104')
+SecID::ISIN.has_checksum?
+```
+
+The old names still work through v7 but emit a deprecation warning on every call and are removed
+in v8. See step 6 to silence them if you cannot migrate every call site yet.
+
+### 3. Rename the rescued error class
+
+```ruby
+# Before (6.x)
+rescue SecID::InvalidCheckDigitError => e
+
+# After (7.0)
+rescue SecID::InvalidChecksumError => e
+```
+
+`SecID::InvalidCheckDigitError` remains as a constant alias of `SecID::InvalidChecksumError`
+through v7 (it is the *same class object*, so `rescue` under either name catches the same error),
+and is removed in v8.
+
+The constant alias emits **no** deprecation warning at runtime (it is a plain constant, not a
+warned method), so `-W` output won't reveal your rescue sites — find them statically:
+
+```bash
+grep -rEn 'InvalidCheckDigitError' app/ lib/ spec/
+```
+
+### 4. Update error-code matchers (hard flip — no bridge)
+
+The `:invalid_check_digit` code in `errors.details` and `explain` output is replaced by
+`:invalid_checksum` with **no dual emission** — emitting both would duplicate `errors.details`
+entries. This is the only change with no v7 bridge, so update any matcher immediately.
+
+```ruby
+# Before (6.x)
+isin.errors.details.first[:error] == :invalid_check_digit
+SecID.explain('US5949181040', types: [:isin])[:candidates].first[:errors]
+#   => [{ error: :invalid_check_digit, message: "Check digit '0' is invalid, expected '5'" }]
+
+# After (7.0)
+isin.errors.details.first[:error] == :invalid_checksum
+SecID.explain('US5949181040', types: [:isin])[:candidates].first[:errors]
+#   => [{ error: :invalid_checksum, message: "Checksum '0' is invalid, expected '5'" }]
+```
+
+If you use the opt-in ActiveModel/Rails validator with `details: true`, the surfaced reason
+follows the same flip: an invalid checksum now reports `:invalid_checksum`.
+
+### 5. Migrate pattern matches and `to_h` readers before v8
+
+`components` (and therefore `to_h` and `deconstruct_keys`) carries **both** `:checksum` and the
+deprecated `:check_digit` key through v7, so existing pattern matches keep working. The
+`:check_digit` key is removed in v8 — migrate to `:checksum` before then.
+
+```ruby
+# Both work through v7, binding the same value:
+isin => { check_digit: }   # deprecated, removed in v8
+isin => { checksum: }      # canonical
+
+isin.to_h[:components]
+#   => { country_code: 'US', nsin: '594918104', checksum: 5, check_digit: 5 }
+```
+
+Reading the `:check_digit` key also emits **no** warning (the value mirrors `:checksum`), so grep
+for the call sites rather than relying on stderr:
+
+```bash
+grep -rEn ':check_digit\b|check_digit:' app/ lib/ spec/
+```
+
+### 6. Silencing the deprecation warnings
+
+The method aliases warn via `Kernel#warn` on every call, visible at Ruby's default verbosity.
+If you cannot migrate every call site before v7, silence them one of these ways:
+
+```ruby
+# Process-wide, at the lowest verbosity (also silences other Ruby warnings):
+$VERBOSE = nil            # equivalent to running with -W0
+
+# Or filter only SecID's deprecations with an app-level Warning override:
+module SecIDDeprecationSilencer
+  def warn(message, category: nil, **)
+    super unless message.to_s.include?('SecID: `')
+  end
+end
+Warning.extend(SecIDDeprecationSilencer)
+```
+
+The warnings are intentionally on by default (not routed through `Warning[:deprecated]`, which
+Ruby leaves off) so the migration signal is visible without opting in.
+
+---
+
 # Upgrading to SecID 6.0
 
 This guide covers all breaking changes when upgrading from SecID 5.x to 6.0. Every one is

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
@@ -28,6 +29,7 @@
   - [FISN](#fisn) - Financial Instrument Short Name
   - [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)
@@ -46,7 +48,7 @@ Ruby 3.2+ is required.
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'sec_id', '~> 6.0'
+gem 'sec_id', '~> 7.1'
 ```
 
 And then execute:
@@ -81,11 +83,11 @@ All identifier classes provide `valid?`, `errors`, `validate`, `validate!` metho
 ```ruby
 SecID::ISIN.new('US5949181045').to_h
 # => { type: :isin, full_id: 'US5949181045', normalized: 'US5949181045',
-#      valid: true, components: { country_code: 'US', nsin: '594918104', check_digit: 5 } }
+#      valid: true, components: { country_code: 'US', nsin: '594918104', checksum: 5 } }
 
 SecID::ISIN.new('INVALID').to_h
 # => { type: :isin, full_id: 'INVALID', normalized: nil,
-#      valid: false, components: { country_code: nil, nsin: nil, check_digit: nil } }
+#      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:
@@ -102,10 +104,10 @@ a.eql?(b) # => true
 Set.new([a, b]).size         # => 1
 ```
 
-**Check-digit based identifiers** (ISIN, CUSIP, CEI, SEDOL, FIGI, LEI, IBAN, DTI) also provide:
-- `restore` / `.restore` - returns the full identifier string with correct check-digit (no mutation)
-- `restore!` / `.restore!` - restores check-digit in place and returns `self` / instance
-- `check_digit` / `calculate_check_digit` - calculates and returns the check-digit
+**Checksum-based identifiers** (ISIN, CUSIP, CEI, SEDOL, FIGI, LEI, IBAN, DTI, UPI) also provide:
+- `restore` / `.restore` - returns the full identifier string with correct checksum (no mutation)
+- `restore!` / `.restore!` - restores checksum in place and returns `self` / instance
+- `checksum` / `calculate_checksum` - calculates and returns the checksum
 
 ### Metadata Registry
 
@@ -126,14 +128,14 @@ SecID::ISIN.short_name                    # => "ISIN"
 SecID::ISIN.full_name                     # => "International Securities Identification Number"
 SecID::ISIN.id_length                     # => 12
 SecID::ISIN.example                       # => "US5949181045"
-SecID::ISIN.has_check_digit?              # => true
+SecID::ISIN.has_checksum?                 # => true
 
 # Filter with standard Ruby
-SecID.identifiers.select(&:has_check_digit?).map(&:short_name)
-# => ["ISIN", "CUSIP", "SEDOL", "FIGI", "LEI", "IBAN", "CEI", "DTI"]
+SecID.identifiers.select(&:has_checksum?).map(&:short_name)
+# => ["ISIN", "CUSIP", "SEDOL", "FIGI", "LEI", "IBAN", "CEI", "DTI", "UPI"]
 
 # Detect identifier type from an unknown string
-# Results are sorted by specificity: check-digit types first, then by length precision
+# Results are sorted by specificity: checksum types first, then by length precision
 SecID.detect('US5949181045')  # => [:isin]
 SecID.detect('037833100')     # => [:cusip, :valoren, :cik]
 SecID.detect('APPLE INC/SH')  # => [:fisn]
@@ -202,7 +204,7 @@ Understand why a string matches or doesn't match specific identifier types:
 result = SecID.explain('US5949181040')
 isin = result[:candidates].find { |c| c[:type] == :isin }
 isin[:valid]                      # => false
-isin[:errors].first[:error]       # => :invalid_check_digit
+isin[:errors].first[:error]       # => :invalid_checksum
 
 # Filter to specific types
 SecID.explain('US5949181045', types: %i[isin cusip])
@@ -215,8 +217,8 @@ All identifier classes provide a Rails-like `#errors` API for detailed error rep
 ```ruby
 isin = SecID::ISIN.new('US5949181040')
 isin.errors.none?     # => false
-isin.errors.messages  # => ["Check digit '0' is invalid, expected '5'"]
-isin.errors.details   # => [{ error: :invalid_check_digit, message: "Check digit '0' is invalid, expected '5'" }]
+isin.errors.messages  # => ["Checksum '0' is invalid, expected '5'"]
+isin.errors.details   # => [{ error: :invalid_checksum, message: "Checksum '0' is invalid, expected '5'" }]
 isin.errors.any?      # => true
 isin.errors.empty?    # => false
 isin.errors.size      # => 1
@@ -233,7 +235,7 @@ SecID::ISIN.validate('US5949181040').errors   # => #<SecID::Errors>
 - `:invalid_format` - correct length and characters but wrong structure
 
 **Type-specific error codes:**
-- `:invalid_check_digit` - check digit mismatch (ISIN, CUSIP, SEDOL, FIGI, LEI, IBAN, CEI, DTI)
+- `:invalid_checksum` - checksum mismatch (ISIN, CUSIP, SEDOL, FIGI, LEI, IBAN, CEI, DTI, UPI)
 - `:invalid_prefix` - restricted FIGI prefix (FIGI)
 - `:invalid_category` - unknown CFI category code (CFI)
 - `:invalid_group` - unknown CFI group code for category (CFI)
@@ -255,7 +257,7 @@ SecID::ISIN.new('INVALID').validate!
 # => SecID::InvalidFormatError: Expected 12 characters, got 7
 
 SecID::ISIN.new('US5949181040').validate!
-# => SecID::InvalidCheckDigitError: Check digit '0' is invalid, expected '5'
+# => SecID::InvalidChecksumError: Checksum '0' is invalid, expected '5'
 
 SecID::FIGI.new('BSG000BLNNH6').validate!
 # => SecID::InvalidStructureError: Prefix 'BS' is restricted
@@ -308,7 +310,7 @@ at all — `#to_h`'s envelope keys (`:type`, `:full_id`, `:normalized`, `:valid`
 
 ### Generating Test Fixtures
 
-Generate syntactically valid identifiers — with correct check digits 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 ...>
@@ -327,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.
@@ -336,18 +373,18 @@ SecID::LEI.generate(random: Random.new(42)) == SecID::LEI.generate(random: Rando
 SecID::ISIN.valid?('US5949181045')      # => true
 SecID::ISIN.restore('US594918104')      # => 'US5949181045'
 SecID::ISIN.restore!('US594918104')     # => #<SecID::ISIN>
-SecID::ISIN.check_digit('US594918104')  # => 5
+SecID::ISIN.checksum('US594918104')  # => 5
 
 # instance level
 isin = SecID::ISIN.new('US5949181045')
 isin.full_id               # => 'US5949181045'
 isin.country_code          # => 'US'
 isin.nsin                  # => '594918104'
-isin.check_digit           # => 5
+isin.checksum           # => 5
 isin.valid?                # => true
 isin.restore               # => 'US5949181045'
 isin.restore!              # => #<SecID::ISIN> (mutates instance)
-isin.calculate_check_digit # => 5
+isin.calculate_checksum # => 5
 isin.to_pretty_s           # => 'US 594918104 5'
 isin.to_cusip              # => #<SecID::CUSIP>
 isin.nsin_type             # => :cusip
@@ -381,18 +418,18 @@ SecID::ISIN.new('CH0012221716').to_valoren # => #<SecID::Valoren>
 SecID::CUSIP.valid?('594918104')      # => true
 SecID::CUSIP.restore('59491810')      # => '594918104'
 SecID::CUSIP.restore!('59491810')     # => #<SecID::CUSIP>
-SecID::CUSIP.check_digit('59491810')  # => 4
+SecID::CUSIP.checksum('59491810')  # => 4
 
 # instance level
 cusip = SecID::CUSIP.new('594918104')
 cusip.full_id               # => '594918104'
 cusip.cusip6                # => '594918'
 cusip.issue                 # => '10'
-cusip.check_digit           # => 4
+cusip.checksum           # => 4
 cusip.valid?                # => true
 cusip.restore               # => '594918104'
 cusip.restore!              # => #<SecID::CUSIP> (mutates instance)
-cusip.calculate_check_digit # => 4
+cusip.calculate_checksum # => 4
 cusip.to_pretty_s           # => '594918 10 4'
 cusip.to_isin('US')         # => #<SecID::ISIN>
 cusip.cins?                 # => false
@@ -407,7 +444,7 @@ cusip.cins?                 # => false
 SecID::CEI.valid?('A0BCDEFGH1')      # => true
 SecID::CEI.restore('A0BCDEFGH')      # => 'A0BCDEFGH1'
 SecID::CEI.restore!('A0BCDEFGH')     # => #<SecID::CEI>
-SecID::CEI.check_digit('A0BCDEFGH')  # => 1
+SecID::CEI.checksum('A0BCDEFGH')  # => 1
 
 # instance level
 cei = SecID::CEI.new('A0BCDEFGH1')
@@ -415,11 +452,11 @@ cei.full_id               # => 'A0BCDEFGH1'
 cei.prefix                # => 'A'
 cei.numeric               # => '0'
 cei.entity_id             # => 'BCDEFGH'
-cei.check_digit           # => 1
+cei.checksum           # => 1
 cei.valid?                # => true
 cei.restore               # => 'A0BCDEFGH1'
 cei.restore!              # => #<SecID::CEI> (mutates instance)
-cei.calculate_check_digit # => 1
+cei.calculate_checksum # => 1
 ```
 
 ### SEDOL
@@ -431,16 +468,16 @@ cei.calculate_check_digit # => 1
 SecID::SEDOL.valid?('B0Z52W5')      # => true
 SecID::SEDOL.restore('B0Z52W')      # => 'B0Z52W5'
 SecID::SEDOL.restore!('B0Z52W')     # => #<SecID::SEDOL>
-SecID::SEDOL.check_digit('B0Z52W')  # => 5
+SecID::SEDOL.checksum('B0Z52W')  # => 5
 
 # instance level
 sedol = SecID::SEDOL.new('B0Z52W5')
 sedol.full_id               # => 'B0Z52W5'
-sedol.check_digit           # => 5
+sedol.checksum           # => 5
 sedol.valid?                # => true
 sedol.restore               # => 'B0Z52W5'
 sedol.restore!              # => #<SecID::SEDOL> (mutates instance)
-sedol.calculate_check_digit # => 5
+sedol.calculate_checksum # => 5
 sedol.to_isin               # => #<SecID::ISIN> (GB ISIN by default)
 sedol.to_isin('IE')         # => #<SecID::ISIN> (IE ISIN)
 ```
@@ -454,18 +491,18 @@ sedol.to_isin('IE')         # => #<SecID::ISIN> (IE ISIN)
 SecID::FIGI.valid?('BBG000DMBXR2')     # => true
 SecID::FIGI.restore('BBG000DMBXR')     # => 'BBG000DMBXR2'
 SecID::FIGI.restore!('BBG000DMBXR')    # => #<SecID::FIGI>
-SecID::FIGI.check_digit('BBG000DMBXR') # => 2
+SecID::FIGI.checksum('BBG000DMBXR') # => 2
 
 # instance level
 figi = SecID::FIGI.new('BBG000DMBXR2')
 figi.full_id               # => 'BBG000DMBXR2'
 figi.prefix                # => 'BB'
 figi.random_part           # => '000DMBXR'
-figi.check_digit           # => 2
+figi.checksum           # => 2
 figi.valid?                # => true
 figi.restore               # => 'BBG000DMBXR2'
 figi.restore!              # => #<SecID::FIGI> (mutates instance)
-figi.calculate_check_digit # => 2
+figi.calculate_checksum # => 2
 figi.to_pretty_s           # => 'BBG 000DMBXR 2'
 ```
 
@@ -478,7 +515,7 @@ figi.to_pretty_s           # => 'BBG 000DMBXR 2'
 SecID::LEI.valid?('5493006MHB84DD0ZWV18')    # => true
 SecID::LEI.restore('5493006MHB84DD0ZWV')     # => '5493006MHB84DD0ZWV18'
 SecID::LEI.restore!('5493006MHB84DD0ZWV')    # => #<SecID::LEI>
-SecID::LEI.check_digit('5493006MHB84DD0ZWV') # => 18
+SecID::LEI.checksum('5493006MHB84DD0ZWV') # => 18
 
 # instance level
 lei = SecID::LEI.new('5493006MHB84DD0ZWV18')
@@ -486,11 +523,11 @@ lei.full_id               # => '5493006MHB84DD0ZWV18'
 lei.lou_id                # => '5493'
 lei.reserved              # => '00'
 lei.entity_id             # => '6MHB84DD0ZWV'
-lei.check_digit           # => 18
+lei.checksum           # => 18
 lei.valid?                # => true
 lei.restore               # => '5493006MHB84DD0ZWV18'
 lei.restore!              # => #<SecID::LEI> (mutates instance)
-lei.calculate_check_digit # => 18
+lei.calculate_checksum # => 18
 lei.to_pretty_s           # => '5493 006M HB84 DD0Z WV18'
 ```
 
@@ -503,7 +540,7 @@ lei.to_pretty_s           # => '5493 006M HB84 DD0Z WV18'
 SecID::IBAN.valid?('DE89370400440532013000')    # => true
 SecID::IBAN.restore('DE370400440532013000')     # => 'DE89370400440532013000'
 SecID::IBAN.restore!('DE370400440532013000')    # => #<SecID::IBAN>
-SecID::IBAN.check_digit('DE370400440532013000') # => 89
+SecID::IBAN.checksum('DE370400440532013000') # => 89
 
 # instance level
 iban = SecID::IBAN.new('DE89370400440532013000')
@@ -512,11 +549,11 @@ iban.country_code          # => 'DE'
 iban.bban                  # => '370400440532013000'
 iban.bank_code             # => '37040044'
 iban.account_number        # => '0532013000'
-iban.check_digit           # => 89
+iban.checksum           # => 89
 iban.valid?                # => true
 iban.restore               # => 'DE89370400440532013000'
 iban.restore!              # => #<SecID::IBAN> (mutates instance)
-iban.calculate_check_digit # => 89
+iban.calculate_checksum # => 89
 iban.known_country?        # => true
 iban.to_pretty_s           # => 'DE89 3704 0044 0532 0130 00'
 ```
@@ -731,28 +768,54 @@ BIC validation confirms structure and a real country code only. It does **not**
 SecID::DTI.valid?('X9J9K872S')      # => true
 SecID::DTI.restore('X9J9K872')      # => 'X9J9K872S'
 SecID::DTI.restore!('X9J9K872')     # => #<SecID::DTI>
-SecID::DTI.check_digit('X9J9K872')  # => 'S'
+SecID::DTI.checksum('X9J9K872')  # => 'S'
 
 # instance level
 dti = SecID::DTI.new('X9J9K872S')
 dti.full_id               # => 'X9J9K872S'
 dti.identifier             # => 'X9J9K872'
-dti.check_digit            # => 'S'
+dti.checksum            # => 'S'
 dti.valid?                 # => true
 dti.restore                # => 'X9J9K872S'
 dti.restore!                # => #<SecID::DTI> (mutates instance)
-dti.calculate_check_digit  # => 'S'
+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 every other check-digit type in this gem, `check_digit` and `calculate_check_digit` return a `String`, not an `Integer`. 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 — 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 `check_digit` alike:
+> **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:
 >
 > ```ruby
 > SecID::DTI.valid?('4H95J0R2X')  # => true  (registered code, via the exception map)
 > SecID::DTI.valid?('4H95J0R2T')  # => false (algorithmic form is not the registered one)
 > ```
 
+### UPI
+
+> [Unique Product Identifier](https://www.anna-dsb.com) - a 12-character code identifying OTC derivative products per ISO 4914, issued by the ANNA Derivatives Service Bureau and reported under CFTC, EMIR, and other global OTC-derivatives mandates.
+
+```ruby
+# class level
+SecID::UPI.valid?('QZRBG6ZTKS42')      # => true
+SecID::UPI.restore('QZRBG6ZTKS4')      # => 'QZRBG6ZTKS42'
+SecID::UPI.restore!('QZRBG6ZTKS4')     # => #<SecID::UPI>
+SecID::UPI.checksum('QZRBG6ZTKS4')  # => '2'
+
+# instance level
+upi = SecID::UPI.new('QZRBG6ZTKS42')
+upi.full_id                # => 'QZRBG6ZTKS42'
+upi.identifier             # => 'QZRBG6ZTKS4'
+upi.checksum            # => '2'
+upi.valid?                 # => true
+upi.restore                # => 'QZRBG6ZTKS42'
+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.
+
+> **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
 
 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.
@@ -803,7 +866,7 @@ On failure the validator adds one error under the `:sec_id` key with a type-awar
 
 ```ruby
 validates :isin, sec_id: { type: :isin, details: true }
-# a bad check digit reports e.g. "Check digit '4' is invalid, expected '5'"
+# 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.