sec_id 6.0.0 → 7.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c629207aa12be217cf0de6bcb9f7429731da6f33e28b4829c21e789c01246d70
-  data.tar.gz: 18c299442df23cba47816bf3f6ebc7d274299f4e87cb82430018fd3e1ce11f8b
+  metadata.gz: b89119bace7665d5cbf511fc3ddf23083e375f7b8eff25dea56b00b584868e20
+  data.tar.gz: a9bb04a1ae20c48c150b2775f55d8f262707b7c6a8510283d6896b8b78dc1876
 SHA512:
-  metadata.gz: 7210e01bab67effdb53376fcd6d4de7ecdf17c61ef505db439a8a08c5ab5e29960b48e0ef57000bbc68c9bd0feb8f123ad1fb397df25104414205a5720f21ef9
-  data.tar.gz: 8325b5b97cd4e1edc9d4e2eae1537e1aa7f02d48d73ad8cda502df4075efe33ffa86ba1ed625c4e45b7cdd748606ac5ed32e509c54be128f310fc8d7b4ca978f
+  metadata.gz: 3f12de747aefe8f567c429c79c05717eb6a7425ffa644325b82b7255df822a5f09158afb8ac34565bfb642a9d5f6fd01effca91d7f0274e0abe5eb2fed0dd28e
+  data.tar.gz: 6d82e962ddb3219c6d5dbb28dcbfc188f56773b9210b83c6db9625bef83e6a50852a8d316166f3fe801d3c201b6654fd8d0f252da46593823edb1369e2bda8a3

data/CHANGELOG.md

@@ -8,6 +8,27 @@ and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
 ## [Unreleased]
 
+## [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
+
+- `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

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

@@ -11,6 +11,7 @@
   - [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
   - [ISIN](#isin) - International Securities Identification Number
   - [CUSIP](#cusip) - Committee on Uniform Securities Identification Procedures
@@ -27,6 +28,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)
@@ -45,7 +47,7 @@ Ruby 3.2+ is required.
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'sec_id', '~> 6.0'
+gem 'sec_id', '~> 7.0'
 ```
 
 And then execute:
@@ -75,15 +77,16 @@ All identifier classes provide `valid?`, `errors`, `validate`, `validate!` metho
 **All identifiers** support hash serialization:
 - `#to_h` - returns a hash with `:type`, `:full_id`, `:normalized`, `:valid`, and `:components` keys
 - `#as_json` - same as `#to_h`, for JSON serialization compatibility (Rails, `JSON.generate`, etc.)
+- `#deconstruct_keys` - exposes `:components` for [pattern matching](#pattern-matching) with `case/in`
 
 ```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:
@@ -100,10 +103,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
 
@@ -119,18 +122,19 @@ SecID.identifiers                         # => [SecID::ISIN, SecID::CUSIP, ...]
 SecID.identifiers.map(&:short_name)       # => ["ISIN", "CUSIP", "SEDOL", ...]
 
 # Query metadata
+SecID::ISIN.type_key                      # => :isin  (SecID[SecID::ISIN.type_key] == SecID::ISIN)
 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]
@@ -199,7 +203,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])
@@ -212,8 +216,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
@@ -230,7 +234,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)
@@ -252,7 +256,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
@@ -261,9 +265,51 @@ SecID::FIGI.new('BSG000BLNNH6').validate!
 isin = SecID::ISIN.validate!('US5949181045')  # => #<SecID::ISIN>
 ```
 
+### 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:
+
+```ruby
+case SecID.parse(input)
+in SecID::ISIN[country_code: 'US', nsin:]  then "US security #{nsin}"
+in SecID::ISIN[country_code:]              then "foreign security from #{country_code}"
+in SecID::OCC[underlying:, type:, strike_mills:] then "#{type} option on #{underlying}"
+in nil                                     then 'not a valid identifier'
+end
+```
+
+`SecID::Match` is a `Data`, so scan results destructure one layer up and nest into the identifier they wrap:
+
+```ruby
+SecID.extract('AAPL ISIN US0378331005').each do |match|
+  case match
+  in { type: :isin, identifier: SecID::ISIN[country_code: 'US'] } then puts 'US ISIN found'
+  else next
+  end
+end
+```
+
+The keys are exactly the `:components` of `#to_h`, and destructuring never consults
+`valid?`. An instance built directly from unparseable input therefore binds `nil` for every component, the same shape
+`to_h` reports:
+
+```ruby
+SecID::ISIN.new('GARBAGE') => { country_code:, nsin: }
+country_code # => nil
+nsin         # => nil
+```
+
+CIK, WKN, and Valoren have no sub-fields: they match a bare `in SecID::CIK` but no keyed pattern. Array patterns
+(`deconstruct`) are not supported.
+
+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.
+
 ### 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 ...>
@@ -291,18 +337,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
@@ -336,18 +382,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
@@ -362,7 +408,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')
@@ -370,11 +416,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
@@ -386,16 +432,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)
 ```
@@ -409,18 +455,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'
 ```
 
@@ -433,7 +479,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')
@@ -441,11 +487,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'
 ```
 
@@ -458,7 +504,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')
@@ -467,11 +513,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'
 ```
@@ -686,28 +732,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.
@@ -758,7 +830,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.

data/lib/sec_id/active_model.rb

@@ -93,7 +93,7 @@ class SecIdValidator < ActiveModel::EachValidator
   #
   # @return [Array<Symbol>]
   def candidate_types
-    configured_types || SecID.identifiers.map { |klass| klass.short_name.downcase.to_sym }
+    configured_types || SecID.identifiers.map(&:type_key)
   end
 
   # sec_id's specific failure reason, only when `details: true` and a single `type:` is set;