sec_id 5.1.0 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b0779f0d2735ded84be536bcc9690a4b106c729b03aab007a0458b6512020e8
-  data.tar.gz: 3b4d99c3534856e5e05ff68cec5355f3c7a2665e2854dad5415815e275a734b1
+  metadata.gz: c629207aa12be217cf0de6bcb9f7429731da6f33e28b4829c21e789c01246d70
+  data.tar.gz: 18c299442df23cba47816bf3f6ebc7d274299f4e87cb82430018fd3e1ce11f8b
 SHA512:
-  metadata.gz: ec036b3fbf2c3d7a89ec823fed2dea6c8cb92be1ede8792bae623c1474454141a3dcc3da27d14c5e3734b050dd95b25672552fc9f4c6983bc68d807a7493d392
-  data.tar.gz: 397e7c17dd46c8aad067262289307317e04cdba4fac65d890aa3e3ff1a1b9ecf175ab916d9600dab7a7a5d4629b54f7750fd40f11c79ed220d3bca339a210d0c
+  metadata.gz: 7210e01bab67effdb53376fcd6d4de7ecdf17c61ef505db439a8a08c5ab5e29960b48e0ef57000bbc68c9bd0feb8f123ad1fb397df25104414205a5720f21ef9
+  data.tar.gz: 8325b5b97cd4e1edc9d4e2eae1537e1aa7f02d48d73ad8cda502df4075efe33ffa86ba1ed625c4e45b7cdd748606ac5ed32e509c54be128f310fc8d7b4ca978f

data/.yardopts

@@ -0,0 +1,6 @@
+--no-private
+--readme README.md
+lib/**/*.rb
+-
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -8,6 +8,44 @@ and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
 ## [Unreleased]
 
+## [6.0.0] - 2026-07-08
+
+### Added
+
+- Hand-written RBS type signatures under `sig/`, shipped in the gem, so consumers running Steep or an RBS-aware editor resolve sec_id's types on install. The core library is checked by Steep in strict mode with zero errors and verified at runtime against the specs via RBS::Test. New dev/test tooling (`rbs` and `steep`, `require: false` — the gem stays zero-runtime-dependency) and rake tasks: `rake steep` (strict type check), `rake steep:coverage` (untyped-call gate), `rake rbs:test` (runtime signature verification), `rake rbs` (validate signatures, in the default task), and `rake sig:cfi` (regenerate the CFI dynamic-method signatures from `SecID::CFI::Tables`, guarded by a drift spec). CI gains a `types` job on Ruby 4.0. The optional ActiveModel adapter and Railtie are excluded from the typed scope
+- `SecID::CFI#decode` returns a frozen `SecID::CFI::Classification` value object for any valid CFI (`nil` for invalid). Its category, group, and each attribute are `Field` objects carrying the CFI letter (`#code`), semantic symbol (`#name`), and authoritative ISO 10962 label (`#label`), plus `<name>?` predicates scoped to the field's own domain — so `decode.category.equity?` and `decode.attributes.voting_right.voting?` answer, while an out-of-domain predicate (e.g. `category.voting?`) raises `NoMethodError`. `#attributes` is an `Enumerable` of the attribute fields keyed by each position's group meaning (`attributes.voting_right`, nil-safe `attributes[:form]`). Ships a human-readable `#to_s` and `#to_h`/`#as_json` for serialization. `X` decodes to `:not_applicable`; pure-N/A positions are omitted
+- `SecID::CFI` now validates the full ISO 10962:2021 attribute matrix — positions 3–6 are checked per-group, `Strategies` (`K`) codes require `XXXX`, pure-N/A positions accept only `X`, and the `ED` (depositary receipts on equities) cross-position rule is enforced. A new `:invalid_attribute` error code (mapped to `InvalidStructureError`) names the offending positions and group
+- Opt-in ActiveModel / Rails validator (`require 'sec_id/active_model'`), registered as `sec_id`, for declarative validation: `validates :isin, sec_id: { type: :isin }`. Validates a single type (`type:`), an allowlist (`types:`), or any supported type (`sec_id: true`); a bad type raises `ArgumentError` at class-load. Opt-in `normalize: true` accepts separatored input and rewrites the attribute to canonical form on success; opt-in `details: true` surfaces the specific failure reason. Auto-activates in Rails via a Railtie (no `require:`/initializer needed) and adds **no runtime dependency** — nothing on the default `require 'sec_id'` path loads Rails or ActiveModel. Tested across Rails 7.2, 8.0, 8.1, and main
+- BIC / SWIFT code (ISO 9362) support via `SecID::BIC` — validate, normalize, parse, detect, extract, and generate 8- or 11-character Business Identifier Codes. Exposes `bank_code`, `country_code`, `location_code`, and `branch_code` (`nil` for a BIC8) components. Validates the embedded country code against a frozen ISO 3166-1 / SWIFT-recognized set (`SecID::BIC.countries`), raising `InvalidStructureError` (`:invalid_country`) for unrecognized codes. Validation confirms structure and a real country code only — it does not verify registration in the licensed SWIFT registry
+- DTI (ISO 24165, Digital Token Identifier) support via `SecID::DTI` — the gem's 15th identifier type, and the first offline DTI validator in any language. Validates the ISO 7064 hybrid MOD 31,30 check character over the 30-symbol DTI alphabet (digits plus consonants; vowels and `Y` never appear), identified empirically from public registry data (1,595 of 1,596 snapshot codes plus 2 post-snapshot registrations). Bitcoin's hand-assigned code (`4H95J0R2X`, which fails the algorithm) is honored via a frozen exception map consulted by `valid?`, `restore`, and `check_digit` alike. Unlike every other check-digit type in the gem, `check_digit`/`calculate_check_digit` return a `String` rather than an `Integer`, since DTI check characters can be letters
+- `.generate` on all 15 identifier types plus a central `SecID.generate(:type)` dispatcher for producing syntactically valid identifiers (with correct check digits where applicable) as test fixtures — accepts an optional `random:` keyword (a Ruby `Random`) for reproducible output. Generated values are valid in format only and are not real, registered securities
+- 100% YARD documentation coverage of the public API, enforced in CI via `rake yard:stats`. The gem now ships a `.yardopts` so `rubydoc.info` renders the public API cleanly (private internals hidden, README/CHANGELOG/LICENSE as pages) and exposes `documentation_uri` metadata (a Documentation link on the RubyGems page). Adds a `yard` dev/test dependency (`require: false` — the gem stays zero-runtime-dependency) and a `rake yard` task for local HTML docs
+
+### Changed
+
+- Internal `@api private` IBAN country-data module dissolved into the `SecID::IBAN` class, so constant names match their file paths per Ruby convention: `SecID::IBANCountryRules::COUNTRY_RULES` / `LENGTH_ONLY_COUNTRIES` are now `SecID::IBAN::COUNTRY_RULES` / `SecID::IBAN::LENGTH_ONLY_COUNTRIES`
+- `SecID.valid?` and `SecID.parse` are faster and allocate less — `SecID.valid?` short-circuits on the first matching type instead of running a full detect-and-sort, and `SecID.parse` reuses the instance built during detection instead of instantiating the matched type a second time
+- **BREAKING:** `SecID::CFI.valid?` is now strict at the attribute level for all 14 categories (including the derivative categories `S`, `H`, `J`) — codes with attribute letters outside the ISO 10962:2021 tables, previously accepted, are now invalid (e.g. `CFI.valid?('ESZZZZ')` returns `false`). There is no leniency option, matching every other identifier type in the gem. The ActiveModel validator inherits this strictness automatically
+- **BREAKING:** `SecID::CFI` group tables corrected to ISO 10962:2021 — six categories carried wrong group letters. Non-listed options (`H`) are now classified by underlying (`HR` Rates, `HT` Commodities, `HE` Equity, `HC` Credit, `HF` FX, `HM` Others) instead of the copied listed-option call/put shape; `D` gains `DE` (structured products without capital protection) and corrects `DG`/`DA`/`DN` (dropping the invented `municipal_notes`); `L` becomes `LL`/`LR`/`LS`, `T` becomes `TC`/`TT`/`TR`/`TI`/…, and the phantom `FM`/`IM`/`JM`/`LM` groups are removed. Group symbols renamed accordingly (e.g. `LS` → `:securities_lending`, `TI` → `:indices`, `MM` → `:other_assets`). Real `H`-category codes that were rejected now validate; codes relying on the old wrong letters no longer do
+
+### Removed
+
+- **BREAKING:** the 12 hardcoded equity predicate helpers on `SecID::CFI` (`equity?`, `voting?`, `non_voting?`, `restricted_voting?`, `enhanced_voting?`, `restrictions?`, `no_restrictions?`, `fully_paid?`, `nil_paid?`, `partly_paid?`, `bearer?`, `registered?`). They were category-wide and semantically wrong for non-equity groups. Migration: use `cfi.decode` and its scoped field predicates — `cfi.voting?` → `cfi.decode.attributes.voting_right.voting?` — which answer only on the field whose ISO domain defines the concept. Two names do not carry over name-for-name: migrate `cfi.equity?` to `cfi.decode.category.equity?` (or `cfi.category == :equity`, unchanged), and `cfi.no_restrictions?` to `cfi.decode.attributes.ownership_restrictions.free_of_restrictions?` (the ISO value name)
+
+## [5.2.0] - 2026-02-24
+
+### Added
+
+- `SecID.scan` and `SecID.extract` methods for finding identifiers in freeform text — returns `Scanner::Match` objects (`Data.define(:type, :raw, :range, :identifier)`) with the validated identifier instance; supports `types:` filtering, hyphenated identifiers, and compound patterns (OCC with spaces, FISN with slashes)
+- `SecID.explain` method for debugging identifier detection — returns per-type validation results showing exactly why each type matched or rejected the input
+- `on_ambiguous:` option for `SecID.parse` and `SecID.parse!` — `:first` (default, existing behavior), `:raise` (raises `AmbiguousMatchError`), `:all` (returns array of all matching instances)
+- `SecID::AmbiguousMatchError` exception class for ambiguous identifier detection
+- `#as_json` method on all identifier types (delegates to `#to_h`) and on `Errors` (delegates to `#details`) for JSON serialization compatibility
+- `SecID::IBAN.supported_countries` class method returning sorted array of all supported country codes
+- `SecID::CFI.categories` class method returning the categories hash
+- `SecID::CFI.groups_for(category_code)` class method returning groups hash for a given category
+
+
 ## [5.1.0] - 2026-02-19
 
 ### Added

data/MIGRATION.md

@@ -1,3 +1,104 @@
+# Upgrading to SecID 6.0
+
+This guide covers all breaking changes when upgrading from SecID 5.x to 6.0. Every one is
+confined to `SecID::CFI`, which became a full ISO 10962:2021 classifier (strict attribute
+validation, corrected group tables, and a new `#decode` classification object replacing the
+old category-wide predicates).
+
+## Quick Reference
+
+| What changed | Before | After |
+|---|---|---|
+| CFI attribute validation is strict | `CFI.valid?('ESZZZZ')` was `true` | now `false` — positions 3-6 must match the ISO tables for the group |
+| CFI group letters/symbols corrected | old `H`/`D`/`L`/`T` groups; `FM`/`IM`/`JM`/`LM` | ISO 10962:2021 groups; e.g. `LS` → `:securities_lending`, `TI` → `:indices` |
+| Equity predicates removed | `cfi.voting?`, `cfi.fully_paid?`, … | `cfi.decode.attributes.voting_right.voting?`, … |
+| `equity?` (category-wide) removed | `cfi.equity?` | `cfi.decode.category.equity?` |
+| `no_restrictions?` uses ISO name | `cfi.no_restrictions?` | `cfi.decode.attributes.ownership_restrictions.free_of_restrictions?` |
+
+## Step-by-Step
+
+### 1. Update Gemfile
+
+```ruby
+gem 'sec_id', '~> 6.0'
+```
+
+Then run `bundle update sec_id`.
+
+### 2. Expect stricter CFI validation
+
+`SecID::CFI.valid?` now validates positions 3-6 against the ISO 10962:2021 attribute tables
+for every category, not just the code's shape. Codes carrying attribute letters outside the
+tables were accepted before and are now invalid. There is no leniency option, matching every
+other identifier type.
+
+```ruby
+# Before (5.x) — shape-only
+SecID::CFI.valid?('ESZZZZ')   # => true
+
+# After (6.0) — Z is not a permissible equity attribute
+SecID::CFI.valid?('ESZZZZ')   # => false
+```
+
+Conversely, real codes the old (incorrect) group tables rejected — notably non-listed options
+(`H`), now classified by underlying (`HR` Rates, `HT` Commodities, `HE` Equity, `HC` Credit,
+`HF` FX, `HM` Miscellaneous) — now validate. If you generate CFIs as test fixtures,
+`SecID::CFI.generate` now samples only table-permitted letters, so every generated code is valid.
+
+### 3. Replace removed CFI predicates with `cfi.decode`
+
+The 12 hardcoded equity predicates (`equity?`, `voting?`, `non_voting?`, `restricted_voting?`,
+`enhanced_voting?`, `restrictions?`, `no_restrictions?`, `fully_paid?`, `nil_paid?`,
+`partly_paid?`, `bearer?`, `registered?`) are removed — they were category-wide and
+semantically wrong for non-equity groups. `cfi.decode` returns a classification whose
+category, group, and attributes are each a **field** object; a predicate lives on the field
+whose ISO domain defines it, so it can only answer where the concept is meaningful.
+
+```ruby
+# Before (5.x)
+cfi = SecID::CFI.new('ESVUFR')
+cfi.voting?        # => true
+cfi.fully_paid?    # => true
+
+# After (6.0)
+d = SecID::CFI.new('ESVUFR').decode
+d.attributes.voting_right.voting?      # => true
+d.attributes.payment_status.fully_paid? # => true
+```
+
+Each field exposes `#code` (the CFI letter), `#name` (the symbol), `#label` (the ISO string),
+and `<name>?` predicates scoped to its own domain — asking a field a predicate outside its
+domain raises `NoMethodError` (e.g. `d.attributes.payment_status.voting?`), which is what
+makes the answers unambiguous. `attributes` is an `Enumerable`; look positions up by meaning
+with `d.attributes.voting_right` or the nil-safe `d.attributes[:voting_right]`.
+
+`decode` returns `nil` for an invalid CFI, so guard before chaining:
+
+```ruby
+SecID::CFI.new('QQXXXX').decode    # => nil
+```
+
+Two names do not map name-for-name:
+
+```ruby
+# `equity?` was category-wide, not an attribute value:
+cfi.equity?                        # before
+cfi.decode.category.equity?        # after (or cfi.category == :equity — CFI#category is unchanged)
+
+# `no_restrictions?` uses the ISO value name, on the ownership_restrictions field:
+cfi.no_restrictions?                               # before
+cfi.decode.attributes.ownership_restrictions.free_of_restrictions?   # after
+```
+
+### 4. Check group symbols if you branch on them
+
+Several group symbols changed to match ISO 10962:2021 (e.g. `LS` → `:securities_lending`,
+`TI` → `:indices`, `MM` → `:other_assets`) and the phantom `FM`/`IM`/`JM`/`LM` groups were
+removed. If you match on `cfi.group`, review `SecID::CFI.groups_for(category_code)` for the
+current values.
+
+---
+
 # Upgrading to SecID 5.0
 
 This guide covers all breaking changes when upgrading from SecID 4.x to 5.0.

data/README.md

@@ -1,6 +1,6 @@
-# SecID [![Gem Version](https://img.shields.io/gem/v/sec_id)](https://rubygems.org/gems/sec_id) [![Codecov](https://img.shields.io/codecov/c/github/svyatov/sec_id)](https://app.codecov.io/gh/svyatov/sec_id) [![CI](https://github.com/svyatov/sec_id/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/svyatov/sec_id/actions?query=workflow%3ACI)
+# 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)
 
-> Validate securities identification numbers with ease!
+> A Ruby toolkit for securities identifiers — validate, parse, normalize, detect, convert, generate, and classify.
 
 ## Table of Contents
 
@@ -8,7 +8,10 @@
 - [Installation](#installation)
 - [Supported Standards and Usage](#supported-standards-and-usage)
   - [Metadata Registry](#metadata-registry) - enumerate, filter, look up, and detect identifier types
+  - [Text Scanning](#text-scanning) - find identifiers in freeform text
+  - [Debugging Detection](#debugging-detection) - understand why strings match or don't
   - [Structured Validation](#structured-validation) - detailed error codes and messages
+  - [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
   - [CEI](#cei) - CUSIP Entity Identifier
@@ -22,7 +25,11 @@
   - [Valoren](#valoren) - Swiss Security Number
   - [CFI](#cfi) - Classification of Financial Instruments
   - [FISN](#fisn) - Financial Instrument Short Name
+  - [BIC](#bic) - Business Identifier Code / SWIFT code
+  - [DTI](#dti) - Digital Token Identifier
+- [ActiveModel / Rails Validator](#activemodel--rails-validator) - declarative `validates :isin, sec_id: {...}`
 - [Lookup Service Integration](#lookup-service-integration)
+- [Type Signatures (RBS)](#type-signatures-rbs)
 - [Development](#development)
 - [Contributing](#contributing)
 - [Changelog](#changelog)
@@ -38,7 +45,7 @@ Ruby 3.2+ is required.
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'sec_id', '~> 5.1'
+gem 'sec_id', '~> 6.0'
 ```
 
 And then execute:
@@ -67,6 +74,7 @@ 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.)
 
 ```ruby
 SecID::ISIN.new('US5949181045').to_h
@@ -92,7 +100,7 @@ a.eql?(b) # => true
 Set.new([a, b]).size         # => 1
 ```
 
-**Check-digit based identifiers** (ISIN, CUSIP, CEI, SEDOL, FIGI, LEI, IBAN) also provide:
+**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
@@ -119,7 +127,7 @@ SecID::ISIN.has_check_digit?              # => true
 
 # Filter with standard Ruby
 SecID.identifiers.select(&:has_check_digit?).map(&:short_name)
-# => ["ISIN", "CUSIP", "SEDOL", "FIGI", "LEI", "IBAN", "CEI"]
+# => ["ISIN", "CUSIP", "SEDOL", "FIGI", "LEI", "IBAN", "CEI", "DTI"]
 
 # Detect identifier type from an unknown string
 # Results are sorted by specificity: check-digit types first, then by length precision
@@ -144,6 +152,57 @@ SecID.parse('594918104', types: [:cusip])         # => #<SecID::CUSIP>
 # Bang version raises on failure
 SecID.parse!('US5949181045')                      # => #<SecID::ISIN>
 SecID.parse!('unknown')                           # raises SecID::InvalidFormatError
+
+# Handle ambiguous matches
+SecID.parse('514000', on_ambiguous: :first)        # => #<SecID::WKN> (default)
+SecID.parse('514000', on_ambiguous: :raise)        # raises SecID::AmbiguousMatchError
+SecID.parse('514000', on_ambiguous: :all)          # => [#<SecID::WKN>, #<SecID::Valoren>, #<SecID::CIK>]
+SecID.parse('US5949181045', on_ambiguous: :raise)  # => #<SecID::ISIN> (unambiguous, no error)
+```
+
+### Text Scanning
+
+Find identifiers embedded in freeform text:
+
+```ruby
+# Extract all identifiers from text
+matches = SecID.extract('Portfolio: US5949181045, 594918104, B0YBKJ7')
+matches.map(&:type)   # => [:isin, :cusip, :sedol]
+matches.first.raw     # => "US5949181045"
+matches.first.range   # => 11...23
+matches.first.identifier.country_code  # => "US"
+
+# Lazy scanning with Enumerator
+SecID.scan('Buy US5949181045 now').each { |m| puts m.type }
+
+# Filter by types
+SecID.extract('514000', types: [:valoren])  # => only Valoren matches
+
+# Handles hyphenated identifiers
+match = SecID.extract('ID: US-5949-1810-45').first
+match.raw                    # => "US-5949-1810-45"
+match.identifier.normalized  # => "US5949181045"
+```
+
+> **Known limitations:** Format-only types (CIK, Valoren, WKN, BIC) can false-positive on
+> common numbers and short words in prose (a BIC8 is 8 letters with a valid country code in the
+> middle) — use the `types:` filter to restrict scanning when
+> this is a concern. Identifiers prefixed with special characters (e.g. `#US5949181045`) may be
+> consumed as a single token by CUSIP's `*@#` character class and fail validation, preventing
+> the embedded identifier from being found.
+
+### Debugging Detection
+
+Understand why a string matches or doesn't match specific identifier types:
+
+```ruby
+result = SecID.explain('US5949181040')
+isin = result[:candidates].find { |c| c[:type] == :isin }
+isin[:valid]                      # => false
+isin[:errors].first[:error]       # => :invalid_check_digit
+
+# Filter to specific types
+SecID.explain('US5949181045', types: %i[isin cusip])
 ```
 
 ### Structured Validation
@@ -171,12 +230,14 @@ 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)
+- `:invalid_check_digit` - check digit mismatch (ISIN, CUSIP, SEDOL, FIGI, LEI, IBAN, CEI, DTI)
 - `:invalid_prefix` - restricted FIGI prefix (FIGI)
 - `:invalid_category` - unknown CFI category code (CFI)
 - `:invalid_group` - unknown CFI group code for category (CFI)
+- `:invalid_attribute` - impermissible attribute letter for the group, or `K` code without `XXXX` (CFI)
 - `:invalid_bban` - BBAN format invalid for country (IBAN)
 - `:invalid_date` - unparseable expiration date (OCC)
+- `:invalid_country` - unrecognized ISO 3166 / SWIFT country code (BIC)
 
 #### Fail-fast validation with `validate!`
 
@@ -200,6 +261,27 @@ SecID::FIGI.new('BSG000BLNNH6').validate!
 isin = SecID::ISIN.validate!('US5949181045')  # => #<SecID::ISIN>
 ```
 
+### 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:
+
+```ruby
+SecID::ISIN.generate          # => #<SecID::ISIN ...>
+SecID::ISIN.generate.valid?   # => true
+
+# Central dispatcher by type symbol (mirrors SecID[])
+SecID.generate(:cusip)        # => #<SecID::CUSIP ...>
+SecID.generate(:nope)         # => raises ArgumentError: Unknown identifier type: :nope
+
+# Pass a seeded Random for reproducible output
+SecID::LEI.generate(random: Random.new(42)) == SecID::LEI.generate(random: Random.new(42))  # => true
+```
+
+> **Generated identifiers are valid in format only — they are not real, registered securities.**
+> Country codes, FIGI prefixes, OCC expiry dates, and CFI category/group/attribute choices are
+> randomly selected (from the values each standard permits) and do not map to real-world
+> instruments. Use them as test fixtures, not as references to actual securities.
+
 ### ISIN
 
 > [International Securities Identification Number](https://en.wikipedia.org/wiki/International_Securities_Identification_Number) - a 12-character alphanumeric code that uniquely identifies a security.
@@ -396,6 +478,11 @@ iban.to_pretty_s           # => 'DE89 3704 0044 0532 0130 00'
 
 Full BBAN structural validation is supported for EU/EEA countries. Other countries have length-only validation.
 
+```ruby
+# List all supported countries
+SecID::IBAN.supported_countries  # => ["AD", "AE", "AT", "BE", "BG", "CH", ...]
+```
+
 ### CIK
 
 > [Central Index Key](https://en.wikipedia.org/wiki/Central_Index_Key) - a 10-digit number used by the SEC to identify corporations and individuals who have filed disclosures.
@@ -496,12 +583,12 @@ valoren.to_isin('LI') # => #<SecID::ISIN> (LI ISIN)
 
 ### CFI
 
-> [Classification of Financial Instruments](https://en.wikipedia.org/wiki/ISO_10962) - a 6-character alphabetic code that classifies financial instruments per ISO 10962.
+> [Classification of Financial Instruments](https://en.wikipedia.org/wiki/ISO_10962) - a 6-character alphabetic code that classifies financial instruments per ISO 10962:2021.
 
 ```ruby
 # class level
-SecID::CFI.valid?('ESXXXX')        # => true
 SecID::CFI.valid?('ESVUFR')        # => true
+SecID::CFI.valid?('ESZZZZ')        # => false (Z is not a permissible equity attribute)
 # instance level
 cfi = SecID::CFI.new('ESVUFR')
 cfi.full_id        # => 'ESVUFR'
@@ -512,15 +599,34 @@ cfi.category       # => :equity
 cfi.group          # => :common_shares
 cfi.valid?         # => true
 
-# Equity-specific predicates
-cfi.equity?        # => true
-cfi.voting?        # => true
-cfi.restrictions?  # => false
-cfi.fully_paid?    # => true
-cfi.registered?    # => true
+# Decode the full ISO 10962:2021 classification
+d = cfi.decode
+d.category.name                     # => :equity
+d.category.label                    # => 'Equities'
+d.category.equity?                  # => true  (scoped to the category domain)
+d.group.name                        # => :common_shares
+d.group.label                       # => 'Common/Ordinary shares'
+
+# attributes is an Enumerable of fields keyed by each position's group meaning
+d.attributes.map(&:name)            # => [:voting, :free_of_restrictions, :fully_paid, :registered]
+d.attributes.voting_right.name      # => :voting
+d.attributes.voting_right.voting?   # => true   (scoped to that position's values)
+d.attributes.payment_status.label   # => 'Fully paid'
+d.attributes[:form].code            # => 'R'    (nil-safe lookup; .form also works)
+d.to_s                              # => 'Equities / Common/Ordinary shares: Voting, Free of restrictions, Fully paid, Registered'
+
+SecID::CFI.new('QQXXXX').decode     # => nil (decode returns nil for an invalid CFI)
 ```
 
-CFI validates the category code (position 1) against 14 valid values and the group code (position 2) against valid values for that category. Attribute positions 3-6 accept any letter A-Z, with X meaning "not applicable".
+CFI is validated strictly against the ISO 10962:2021 code tables for all 14 categories: the category (position 1), the group (position 2), and every attribute (positions 3-6) must be a value the standard defines for that group. `X` means "not applicable" and is accepted in every position; `Strategies` (`K`) codes carry no attributes and require `XXXX`. An impermissible attribute letter raises `InvalidStructureError` (`:invalid_attribute`).
+
+> **Migration from &lt; 6.0:** the old category-wide equity predicates (`cfi.voting?`, `cfi.fully_paid?`, …) are removed. Use `cfi.decode` and its scoped fields instead — a predicate now lives on the field whose domain defines it: `cfi.voting?` → `cfi.decode.attributes.voting_right.voting?`. Two do not map name-for-name: `cfi.equity?` → `cfi.decode.category.equity?` (or `cfi.category == :equity`), and `cfi.no_restrictions?` → `cfi.decode.attributes.ownership_restrictions.free_of_restrictions?`. Several group letters and symbols also changed to match ISO 10962:2021 (e.g. non-listed options `H` are now classified by underlying, and `LS` → `:securities_lending`, `TI` → `:indices`).
+
+```ruby
+# Introspect valid codes
+SecID::CFI.categories            # => { "E" => :equity, "C" => :collective_investment_vehicles, ... }
+SecID::CFI.groups_for('E')       # => { "S" => :common_shares, "P" => :preferred_shares, ... }
+```
 
 ### FISN
 
@@ -542,6 +648,121 @@ fisn.to_s          # => 'APPLE INC/SH'
 
 FISN format: `Issuer Name/Abbreviated Instrument Description` with issuer (1-15 chars) and description (1-19 chars) separated by a forward slash. Character set: uppercase A-Z, digits 0-9, and space.
 
+### BIC
+
+> [Business Identifier Code](https://en.wikipedia.org/wiki/ISO_9362) - an 8- or 11-character code identifying financial and non-financial institutions per ISO 9362 (also known as a SWIFT code).
+
+```ruby
+# class level
+SecID::BIC.valid?('DEUTDEFF')       # => true  (BIC8)
+SecID::BIC.valid?('DEUTDEFF500')    # => true  (BIC11)
+
+# instance level
+bic = SecID::BIC.new('DEUTDEFF500')
+bic.full_id        # => 'DEUTDEFF500'
+bic.identifier     # => 'DEUTDEFF500'
+bic.bank_code      # => 'DEUT'
+bic.country_code   # => 'DE'
+bic.location_code  # => 'FF'
+bic.branch_code    # => '500' (nil for a BIC8)
+bic.valid?         # => true
+```
+
+BIC accepts exactly 8 or 11 characters: a 4-letter institution code, 2-letter country code, 2-alphanumeric location code, and (for BIC11) a 3-alphanumeric branch code. The country code (positions 5-6) is validated against a frozen ISO 3166-1 / SWIFT-recognized set; a well-formed BIC with an unrecognized country is an `:invalid_country` structural error.
+
+```ruby
+SecID::BIC.valid?('DEUTZZFF')       # => false ('ZZ' is not a recognized country)
+SecID::BIC.countries                # => ['AD', 'AE', 'AF', ...] (sorted, includes 'XK')
+```
+
+BIC validation confirms structure and a real country code only. It does **not** verify that the institution, location, or branch corresponds to a registered SWIFT participant — that requires the licensed SWIFT registry.
+
+### DTI
+
+> [Digital Token Identifier](https://www.dtif.org) - a 9-character code identifying digital tokens (e.g. cryptocurrencies) per ISO 24165, used in EU MiCA/ESMA regulatory reporting.
+
+```ruby
+# class level
+SecID::DTI.valid?('X9J9K872S')      # => true
+SecID::DTI.restore('X9J9K872')      # => 'X9J9K872S'
+SecID::DTI.restore!('X9J9K872')     # => #<SecID::DTI>
+SecID::DTI.check_digit('X9J9K872')  # => 'S'
+
+# instance level
+dti = SecID::DTI.new('X9J9K872S')
+dti.full_id               # => 'X9J9K872S'
+dti.identifier             # => 'X9J9K872'
+dti.check_digit            # => 'S'
+dti.valid?                 # => true
+dti.restore                # => 'X9J9K872S'
+dti.restore!                # => #<SecID::DTI> (mutates instance)
+dti.calculate_check_digit  # => '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.
+
+> **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:
+>
+> ```ruby
+> SecID::DTI.valid?('4H95J0R2X')  # => true  (registered code, via the exception map)
+> SecID::DTI.valid?('4H95J0R2T')  # => false (algorithmic form is not the registered one)
+> ```
+
+## 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.
+
+**In Rails it just works.** A Railtie loads the validator automatically after the framework boots, so `gem 'sec_id'` in your `Gemfile` is enough — no `require:` option and no initializer:
+
+```ruby
+class Security < ApplicationRecord
+  validates :isin, sec_id: { type: :isin }
+end
+```
+
+Outside Rails (e.g. Hanami, Sinatra + ActiveModel), require the adapter explicitly:
+
+```ruby
+require 'sec_id/active_model'
+```
+
+### Validation modes
+
+```ruby
+# Single type — the value must be a valid ISIN
+validates :isin, sec_id: { type: :isin }
+
+# Allowlist — valid as at least one of the listed types
+validates :ref, sec_id: { types: %i[isin cusip] }
+
+# Type-agnostic — valid as any supported type
+validates :ref, sec_id: true
+```
+
+An unknown `type:`/`types:` symbol raises `ArgumentError` when the model class loads (fail-fast on misconfiguration), not at validation time.
+
+### Strict by default; `normalize:` for lenient input
+
+Validation is strict by default, so separatored input like `"US-0378331005"` is invalid. Pass `normalize: true` to accept spaces/hyphens **and** rewrite the attribute to its canonical form on success (a failing value is left untouched):
+
+```ruby
+validates :isin, sec_id: { type: :isin, normalize: true }
+# "us-0378331005" validates, and the attribute afterward reads "US0378331005"
+```
+
+With `normalize: true` in allowlist or agnostic mode, a value valid as more than one type is written in the canonical form of the **first** matching type (allowlist order, or registration order when agnostic). Prefer a single `type:` when the input is ambiguous across types that normalize differently (e.g. a bare numeric string valid as both CIK and Valoren).
+
+### Error messages and `details:`
+
+On failure the validator adds one error under the `:sec_id` key with a type-aware default ("is not a valid ISIN" for a single type, "is not a valid securities identifier" for an allowlist/agnostic). Override the message in either of two ways: pass the standard `message:` option (the simplest, per-validation override), or define the attribute-scoped i18n key `activemodel.errors.models.<model>.attributes.<attribute>.sec_id` in your locale files. (The generic `activemodel.errors.messages.sec_id` key is not consulted, because the built-in default is supplied as ActiveModel's `message:` fallback.) Pass `details: true` (with a single `type:` — it is ignored for an allowlist/agnostic) to surface sec_id's specific reason instead of the generic text:
+
+```ruby
+validates :isin, sec_id: { type: :isin, details: true }
+# a bad check digit reports e.g. "Check digit '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.
+
 ## Lookup Service Integration
 
 SecID validates identifiers but does not include HTTP clients. The [`docs/guides/`](docs/guides/) directory provides integration patterns for external lookup services using only stdlib (`net/http`, `json`):
@@ -555,6 +776,32 @@ SecID validates identifiers but does not include HTTP clients. The [`docs/guides
 
 Each guide includes a complete adapter class and a [runnable example](examples/).
 
+## Type Signatures (RBS)
+
+sec_id ships hand-written [RBS](https://github.com/ruby/rbs) signatures under `sig/`,
+packaged in the gem — so if you use [Steep](https://github.com/soutaro/steep) or an
+RBS-aware editor, sec_id's types resolve automatically on install, no `rbs collection`
+entry required. The only standard-library signature referenced is `date`, declared in
+`sig/manifest.yaml`.
+
+The core library is checked by Steep in strict mode and verified at runtime against the
+test suite via RBS::Test. The optional ActiveModel/Rails adapter is excluded from the
+typed scope (it lives off the default require path).
+
+Contributor commands:
+
+```bash
+bundle exec rake rbs             # validate the signatures (also part of `rake`)
+bundle exec rake steep           # strict Steep type check
+bundle exec rake steep:coverage  # untyped-call coverage gate
+bundle exec rake rbs:test        # verify runtime values against the signatures
+bundle exec rake sig:cfi         # regenerate the CFI dynamic-method signatures
+```
+
+The CFI per-instance dynamic methods (`Field` predicates and `AttributeSet` readers) are
+generated from `SecID::CFI::Tables` by `rake sig:cfi`; a drift-guard spec fails if the
+committed signatures fall out of sync with the tables.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies.