sec_id 6.1.0 → 7.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c705053b66b513f6cbac21702cd4548f5f446669f9251db569d62693698ff64
-  data.tar.gz: b792e03a67c57ead4064c392925771033c35b68fd984ad93aa5d932e37d1ea21
+  metadata.gz: b89119bace7665d5cbf511fc3ddf23083e375f7b8eff25dea56b00b584868e20
+  data.tar.gz: a9bb04a1ae20c48c150b2775f55d8f262707b7c6a8510283d6896b8b78dc1876
 SHA512:
-  metadata.gz: 51880f7c27744b9700e01bca80a6f3a9a436d76a843921fdc97a401e12ef0acb2011c4f67a19034c30ea90e59638de0b66cb8a949b32d2d896e28a4f7957c4ba
-  data.tar.gz: 780d1cd07415046d2c5dfda3b6f548785ae0e244bdb294876440521f90475562000beaf493c88109d609e9c65fa83b94ad67c8509084174a84e52e6be9268543
+  metadata.gz: 3f12de747aefe8f567c429c79c05717eb6a7425ffa644325b82b7255df822a5f09158afb8ac34565bfb642a9d5f6fd01effca91d7f0274e0abe5eb2fed0dd28e
+  data.tar.gz: 6d82e962ddb3219c6d5dbb28dcbfc188f56773b9210b83c6db9625bef83e6a50852a8d316166f3fe801d3c201b6654fd8d0f252da46593823edb1369e2bda8a3

data/CHANGELOG.md

@@ -8,6 +8,20 @@ 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

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

@@ -28,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)
@@ -46,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:
@@ -81,11 +82,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 +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
 
@@ -126,14 +127,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 +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])
@@ -215,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
@@ -233,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)
@@ -255,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
@@ -308,7 +309,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 ...>
@@ -336,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
@@ -381,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
@@ -407,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')
@@ -415,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
@@ -431,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)
 ```
@@ -454,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'
 ```
 
@@ -478,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')
@@ -486,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'
 ```
 
@@ -503,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')
@@ -512,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'
 ```
@@ -731,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.
@@ -803,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/base.rb

@@ -8,28 +8,28 @@ module SecID
   # - ID_REGEX constant with named capture groups for parsing
   # - initialize method that calls parse and extracts components
   #
-  # Subclasses with check digits should also include the Checkable concern,
-  # which provides check-digit validation, calculation, and restoration.
+  # Subclasses with checksum should also include the Checkable concern,
+  # which provides checksum validation, calculation, and restoration.
   #
-  # @example Implementing a check-digit identifier
+  # @example Implementing a checksum identifier
   #   class MyIdentifier < Base
   #     include Checkable
   #
-  #     ID_REGEX = /\A(?<identifier>[A-Z]{6})(?<check_digit>\d)?\z/x
+  #     ID_REGEX = /\A(?<identifier>[A-Z]{6})(?<checksum>\d)?\z/x
   #
   #     def initialize(id)
   #       parts = parse(id)
   #       @identifier = parts[:identifier]
-  #       @check_digit = parts[:check_digit]&.to_i
+  #       @checksum = parts[:checksum]&.to_i
   #     end
   #
-  #     def calculate_check_digit
+  #     def calculate_checksum
   #       validate_format_for_calculation!
   #       mod10(some_algorithm)
   #     end
   #   end
   #
-  # @example Implementing a non-check-digit identifier
+  # @example Implementing a non-checksum identifier
   #   class SimpleId < Base
   #     ID_REGEX = /\A(?<identifier>[A-Z]{6})\z/x
   #
@@ -46,7 +46,7 @@ module SecID
     # @return [String] the original input after normalization (stripped and uppercased)
     attr_reader :full_id
 
-    # @return [String, nil] the main identifier portion (without check digit)
+    # @return [String, nil] the main identifier portion (without checksum)
     attr_reader :identifier
 
     class << self
@@ -55,15 +55,15 @@ module SecID
       # @return [Symbol] the registry key (e.g. :isin, :cusip)
       def type_key = @type_key ||= short_name.downcase.to_sym
 
-      # Composite sort key ranking detection specificity: check-digit types first,
+      # Composite sort key ranking detection specificity: checksum types first,
       # then narrower length range, then registration order. A class the registry
       # never saw sorts last.
       #
       # @api private
-      # @return [Array] frozen [check-digit rank, length specificity, registration order]
+      # @return [Array] frozen [checksum rank, length specificity, registration order]
       def detection_priority
         @detection_priority ||=
-          [has_check_digit? ? 0 : 1, length_specificity, SecID.identifiers.index(self) || Float::INFINITY].freeze
+          [has_checksum? ? 0 : 1, length_specificity, SecID.identifiers.index(self) || Float::INFINITY].freeze
       end
 
       # @return [String] the unqualified class name (e.g. "ISIN", "CUSIP")
@@ -89,11 +89,19 @@ module SecID
       # @return [String] a representative valid identifier string
       def example = self::EXAMPLE
 
-      # @return [Boolean] true if this identifier type uses a check digit
-      def has_check_digit?
-        return @has_check_digit if defined?(@has_check_digit)
+      # @return [Boolean] true if this identifier type uses a checksum
+      def has_checksum?
+        return @has_checksum if defined?(@has_checksum)
+
+        @has_checksum = ancestors.include?(SecID::Checkable)
+      end
 
-        @has_check_digit = ancestors.include?(SecID::Checkable)
+      # @deprecated Use {.has_checksum?}. Kept as a v7 bridge; removed in v8.
+      #
+      # @return [Boolean]
+      def has_check_digit?
+        SecID::Deprecation.warn(old: 'has_check_digit?', new: 'has_checksum?')
+        has_checksum?
       end
     end
 
@@ -134,7 +142,7 @@ module SecID
         full_id: full_id,
         normalized: valid? ? normalized : nil,
         valid: valid?,
-        components: components
+        components: components_with_deprecation_bridge
       }
     end
 
@@ -157,7 +165,7 @@ module SecID
     #   in SecID::ISIN[country_code:, nsin:] then [country_code, nsin]
     #   in nil then :invalid
     #   end #=> ['US', '594918104']
-    def deconstruct_keys(_keys) = components
+    def deconstruct_keys(_keys) = components_with_deprecation_bridge
 
     protected
 
@@ -168,6 +176,17 @@ module SecID
 
     private
 
+    # Mirrors the canonical `:checksum` components key onto the deprecated `:check_digit`
+    # key for the v7 bridge, when a checksum is present. The mirror reads `:checksum`, so the
+    # deprecated `check_digit` reader never fires internally. Removed in v8 (revert `to_h` and
+    # `deconstruct_keys` to call `components` directly).
+    #
+    # @return [Hash] the parsed components, with `:check_digit` added when `:checksum` is present
+    def components_with_deprecation_bridge
+      parsed = components
+      parsed.key?(:checksum) ? parsed.merge(check_digit: parsed[:checksum]) : parsed
+    end
+
     # @return [Hash]
     def components
       {}