sec_id 5.2.0 → 6.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc458a32d8a5cb8fc4db2b1ab4c635a6c88e4160d38948e4ce779e90b039bd3c
-  data.tar.gz: 298298a51ca424aef20c814ed620e35d32bbfe9bf285fe1f6ee6f44bac163980
+  metadata.gz: 2c705053b66b513f6cbac21702cd4548f5f446669f9251db569d62693698ff64
+  data.tar.gz: b792e03a67c57ead4064c392925771033c35b68fd984ad93aa5d932e37d1ea21
 SHA512:
-  metadata.gz: 78650675337ce8a03970e4b1227713aaa0adafb8c18da35466099add8fc39389c8b02583602c18f9aeb59a340ee6b9db9f42ef7662d96284dd0ed93336a50a6a
-  data.tar.gz: 27d54f707d2ec471218a15e6f9dadc2d78d3f46985084f1e18be921b83691f4fe5cd4d82d793ae9cbb34c3e55df30e2966aa834b5942606dfa81d5e3d38e4799
+  metadata.gz: 51880f7c27744b9700e01bca80a6f3a9a436d76a843921fdc97a401e12ef0acb2011c4f67a19034c30ea90e59638de0b66cb8a949b32d2d896e28a4f7957c4ba
+  data.tar.gz: 780d1cd07415046d2c5dfda3b6f548785ae0e244bdb294876440521f90475562000beaf493c88109d609e9c65fa83b94ad67c8509084174a84e52e6be9268543

data/.yardopts

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

data/CHANGELOG.md

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

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)
 
-> A Ruby toolkit for securities identifiers — validate, parse, normalize, detect, and convert.
+> A Ruby toolkit for securities identifiers — validate, parse, normalize, detect, convert, generate, and classify.
 
 ## Table of Contents
 
@@ -11,6 +11,8 @@
   - [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
   - [CEI](#cei) - CUSIP Entity Identifier
@@ -24,7 +26,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)
@@ -40,7 +46,7 @@ Ruby 3.2+ is required.
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'sec_id', '~> 5.2'
+gem 'sec_id', '~> 6.0'
 ```
 
 And then execute:
@@ -70,6 +76,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.)
+- `#deconstruct_keys` - exposes `:components` for [pattern matching](#pattern-matching) with `case/in`
 
 ```ruby
 SecID::ISIN.new('US5949181045').to_h
@@ -95,7 +102,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
@@ -114,6 +121,7 @@ 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
@@ -122,7 +130,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
@@ -179,8 +187,9 @@ match.raw                    # => "US-5949-1810-45"
 match.identifier.normalized  # => "US5949181045"
 ```
 
-> **Known limitations:** Format-only types (CIK, Valoren, WKN, CFI) can false-positive on
-> common numbers and short words in prose — use the `types:` filter to restrict scanning when
+> **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.
@@ -224,12 +233,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!`
 
@@ -253,6 +264,69 @@ 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:
+
+```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.
@@ -554,12 +628,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'
@@ -570,15 +644,28 @@ 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
@@ -606,6 +693,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`):
@@ -619,6 +821,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.