gov_codes 0.1.0 → 0.1.2

data/lib/gov_codes/afsc/releases/dafocd/2025-10-31/ri.yml

@@ -0,0 +1,193 @@
+# DAFOCD Reporting Identifiers (RI) + Special Duty Identifiers (SDI)
+# Source: DAFOCD 31 Oct 25 v3.pdf
+# Directory: Department of the Air Force Officer Classification Directory
+# Effective date: 2025-10-31  (v3)
+# Generated deterministically by bin/extract_afsc_from_pdf.rb.
+# Do not edit by hand; re-run the extractor against the source PDF.
+# Titles are de-glued via human-verified overrides (spacing/case only, gated
+# against the verbatim source); a title without an override is kept verbatim.
+---
+:80C0:
+  :name: Commander, Cadet Squadron, USAF Academy
+  :changed_date: '2022-10-31'
+:81C0:
+  :name: Instructor, Officer Training School
+  :changed_date: '2019-04-30'
+:81D0:
+  :name: Air Force Reserve Officer Training Corps Detachment Commander and Professor
+    of Aerospace Studies
+  :changed_date: '2020-04-30'
+:81L0:
+  :name: Education and Training Leader
+  :changed_date: '2020-04-30'
+:81T0:
+  :name: Instructor
+:82A0:
+  :name: Academic Program Manager
+:83R0:
+  :name: Recruiting Service
+:84H0:
+  :name: Historian
+  :changed_date: '2024-10-31'
+:85G0:
+  :name: Honor Guard
+  :changed_date: '2025-10-31'
+:86M0:
+  :name: Operations Management
+:86P0:
+  :name: Command and Control
+:87G0:
+  :name: Wing Inspector General
+  :changed_date: '2018-04-30'
+:87I0:
+  :name: Director, Wing Inspections
+  :changed_date: '2012-10-31'
+:87Q0:
+  :name: Director, Complaints Resolution
+  :changed_date: '2012-10-31'
+:88A0:
+  :name: Aide-de-camp
+:88B0:
+  :name: Protocol Officer
+  :changed_date: '2019-10-31'
+:88C0:
+  :name: Sexual Assault Response Coordinator (SARC)
+  :acronym: SARC
+  :changed_date: '2020-04-30'
+:88I0:
+  :name: Innovation Officer
+  :changed_date: '2022-10-31'
+:88M0:
+  :name: United States Air Force Medical Pinnacle Position
+  :changed_date: '2024-04-30'
+:88X0:
+  :name: Operational STEM Officer
+  :changed_date: '2024-10-31'
+:88Y0:
+  :name: Pathfinder Officer
+  :changed_date: '2023-10-31'
+:89A0:
+  :name: Air Advisor (Basic)
+  :changed_date: '2022-10-31'
+:89B0:
+  :name: Air Advisor (Basic) Team Leader
+  :changed_date: '2022-10-31'
+:89C0:
+  :name: Air Advisor (Basic) Mission Commander
+  :changed_date: '2022-10-31'
+:89D0:
+  :name: Air Advisor (Advanced)
+  :changed_date: '2022-10-31'
+:89E0:
+  :name: Air Advisor (Advanced) Team Leader
+  :changed_date: '2022-10-31'
+:89F0:
+  :name: Air Advisor (Advanced) Mission Commander
+  :changed_date: '2022-10-31'
+:89G0:
+  :name: Combat Aviation Advisor
+  :changed_date: '2025-04-30'
+:89H0:
+  :name: Combat Aviation Advisor Team Leader
+  :changed_date: '2025-04-30'
+:89I0:
+  :name: Combat Aviation Advisor Mission Commander
+  :changed_date: '2025-04-30'
+:89W0:
+  :name: Weapons of Mass Destruction Civil Support Team (WMD-CST)
+  :changed_date: '2020-10-31'
+:90G0:
+  :name: General Officer
+:91C0:
+  :name: Commander
+:91E0:
+  :name: Wing Commander Equivalent
+:91W0:
+  :name: Wing Commander
+:92F0:
+  :name: Foreign Area Officer (FAO) Trainee
+:92J0:
+  :name: Non-designated Lawyer
+:92J1:
+  :name: AFROTC Educational Delay Law Student
+:92J2:
+  :name: Funded Legal Education Program Law Student
+:92J3:
+  :name: Excess Leave Law Student
+:92M0:
+  :name: Health Professions Scholarship Program (HPSP) Medical Student
+:92M1:
+  :name: Uniformed Services University of Health Sciences (USUHS) Student
+:92M2:
+  :name: HPSP Biomedical Science Student
+:92P0:
+  :name: Physician Assistant Student
+  :changed_date: '2017-10-31'
+:92R0:
+  :name: Chaplain Candidate
+:92S0:
+  :name: Student Officer Authorization
+:92T0:
+  :name: Pilot Trainee
+:92T1:
+  :name: Combat Systems Officer Trainee
+:92T2:
+  :name: Air Battle Manager Trainee
+:92T3:
+  :name: Remotely Piloted Aircraft Pilot Trainee
+:92W0:
+  :name: Combat Wounded Warrior
+  :changed_date: '2015-05-11'
+:92W1:
+  :name: Reserved for Future Use
+  :changed_date: '2015-05-11'
+:92W2:
+  :name: Combat Wounded Warrior with Exemptions
+  :changed_date: '2015-05-11'
+:92W3:
+  :name: Non-Combat Wounded Warrior
+  :changed_date: '2015-05-11'
+:92W4:
+  :name: Wounded Warrior - Limited Assignment Status (LAS)
+  :acronym: LAS
+  :changed_date: '2015-05-11'
+:92W5:
+  :name: Wounded Warrior - Retired/Discharged
+  :changed_date: '2015-05-11'
+:92W6:
+  :name: Reserved for Future Use
+  :changed_date: '2015-05-11'
+:92W7:
+  :name: Reserved for Future Use
+  :changed_date: '2015-05-11'
+:92W8:
+  :name: Wounded Warrior - Ambassador
+  :changed_date: '2019-10-31'
+:92W9:
+  :name: Wounded Warrior - Project Planner/Officer
+  :changed_date: '2019-10-31'
+:93P0:
+  :name: Patient
+:94N0:
+  :name: Nuclear Weapons Custodian
+:95A0:
+  :name: Non-EAD USAFR Academy Liaison Officer (ALO) or Civil Air Patrol Reserve Assistance
+    Program (CAPRAP) Officer
+:96A0:
+  :name: Disqualified Officer, Reasons Beyond Their Control
+:96B0:
+  :name: Disqualified Officer, Reasons Within Their Control
+:96D0:
+  :name: Officer Not Available for Use in Awarded AFSC for Cause
+:96U0:
+  :name: Unclassified Officer
+:96V0:
+  :name: Un-allotted
+:97E0:
+  :name: Executive Officer
+:99A0:
+  :name: Unspecified AFSC
+  :changed_date: '2015-04-20'
+:99G0:
+  :name: Gold Bar Recruiter
+  :changed_date: '2013-06-05'

data/lib/gov_codes/afsc/releases.rb

@@ -0,0 +1,219 @@
+require "date"
+require "yaml"
+
+module GovCodes
+  module AFSC
+    # Loads the versioned release manifest and per-release specialty index for a
+    # publication (DAFECD enlisted, DAFOCD officer), and resolves the release in
+    # effect on a given date. Both publications share this resolve/merge/cache
+    # machinery and are resolved independently (their release dates may diverge).
+    #
+    # See docs/plans/2026-07-08-afsc-pdf-representation-design.md
+    # "Versioning by document release".
+    #
+    # Storage layout (per release):
+    #   lib/gov_codes/afsc/releases.yml                          # manifest
+    #   lib/gov_codes/afsc/releases/dafecd/<date>/enlisted.yml   # enlisted index
+    #   lib/gov_codes/afsc/releases/dafocd/<date>/officer.yml    # officer index
+    #
+    # Resolution: releases are sorted ascending by effective_date. A given
+    # `as_of` resolves to the release with the greatest effective_date <= as_of;
+    # `as_of: nil` resolves it as of today. A release only takes effect on its
+    # own effective_date -- a release dated in the future (e.g. one a consumer
+    # pre-loads ahead of its official date, see DEC-004 below) is not resolved
+    # until that date arrives, even though it is the most recently added one. A
+    # date before the earliest shipped release resolves to no release (an empty
+    # index / nil date).
+    #
+    # Extensibility (DEC-004): both tiers merge across the load path (gem lib dir
+    # first, then the load path). The manifest's per-publication release list is
+    # unioned by effective_date -- a consumer releases.yml ADDS releases without
+    # hiding the shipped ones, and a same-date entry from the load path wins. For
+    # the resolved release, the release index found at each lookup path is merged,
+    # so a consumer may drop gov_codes/afsc/releases/dafecd/<date>/enlisted.yml to
+    # extend or override the shipped index.
+    module Releases
+      # Publication key for the enlisted directory (DAFECD).
+      ENLISTED_PUBLICATION = "dafecd"
+      # Publication key for the officer directory (DAFOCD).
+      OFFICER_PUBLICATION = "dafocd"
+
+      class << self
+        def manifest(lookup: $LOAD_PATH)
+          manifest_cache[cache_key(lookup)] ||= load_manifest(lookup)
+        end
+
+        def enlisted_index(as_of: nil, lookup: $LOAD_PATH)
+          release_index(ENLISTED_PUBLICATION, "enlisted.yml", as_of: as_of, lookup: lookup)
+        end
+
+        def officer_index(as_of: nil, lookup: $LOAD_PATH)
+          release_index(OFFICER_PUBLICATION, "officer.yml", as_of: as_of, lookup: lookup)
+        end
+
+        # Resolve the RI/SDI index for +publication+ (enlisted DAFECD or officer
+        # DAFOCD). RI/SDI codes live in both directories with different code
+        # grammars (5-char enlisted, 4-char officer), so this wrapper is
+        # parameterized by publication; it otherwise reuses the same resolve/
+        # merge/cache and acronym-overlay machinery as enlisted_index/
+        # officer_index.
+        def ri_index(as_of: nil, lookup: $LOAD_PATH, publication: ENLISTED_PUBLICATION)
+          release_index(publication, "ri.yml", as_of: as_of, lookup: lookup)
+        end
+
+        # Resolve the effective date for +publication+ (defaults to enlisted).
+        # Publications are resolved independently: an officer release date never
+        # moves the enlisted latest date and vice versa.
+        def effective_date_for(as_of: nil, lookup: $LOAD_PATH, publication: ENLISTED_PUBLICATION)
+          release = resolve_release(publication, as_of: as_of, lookup: lookup)
+          release && release[:date]
+        end
+
+        def reset!
+          @manifest_cache = {}
+          @index_cache = {}
+        end
+
+        private
+
+        def manifest_cache
+          @manifest_cache ||= {}
+        end
+
+        def index_cache
+          @index_cache ||= {}
+        end
+
+        def cache_key(lookup)
+          Array(lookup).dup
+        end
+
+        def to_date(as_of)
+          return nil if as_of.nil?
+          return as_of if as_of.is_a?(Date)
+          Date.parse(as_of.to_s)
+        rescue Date::Error
+          raise ArgumentError,
+            "invalid as_of #{as_of.inspect}: expected a Date or a parseable date string (e.g. \"2025-10-31\")"
+        end
+
+        # Ordered list of directories to search: the gem lib dir first, then the
+        # provided lookup path. Deduplicated to avoid loading the same file twice.
+        def lookup_paths(lookup)
+          gem_lib_dir = File.expand_path("../..", __dir__)
+          ([gem_lib_dir] + Array(lookup)).uniq
+        end
+
+        # Resolve, merge, and cache the release index for +publication+. Always
+        # resolves the release first (cheap: the manifest itself is cached) and
+        # keys the expensive part -- loading and merging the index file -- on
+        # the RESOLVED release's date, not the raw +as_of+. With `as_of: nil`
+        # meaning "today," keying on the raw input would freeze the cache to
+        # whichever release happened to be current at the first call and never
+        # notice a later release's effective_date arrive.
+        def release_index(publication, index_file, as_of:, lookup:)
+          release = resolve_release(publication, as_of: as_of, lookup: lookup)
+          return {} unless release
+
+          key = [publication, index_file, release[:date], cache_key(lookup)]
+          index_cache[key] ||= load_release_index(release, publication, index_file, lookup)
+        end
+
+        def resolve_release(publication, as_of:, lookup:)
+          releases = release_list(lookup, publication)
+          return nil if releases.empty?
+
+          target = to_date(as_of) || Date.today
+          releases.reverse.find { |r| r[:date] <= target }
+        end
+
+        # Releases for +publication+ from the manifest, each annotated with a
+        # parsed :date and the :dir name used to locate its index, sorted
+        # ascending by date.
+        def release_list(lookup, publication)
+          entries = manifest(lookup: lookup)[publication.to_sym] || []
+          entries.filter_map do |entry|
+            raw = entry[:effective_date]
+            next unless raw
+
+            date = raw.is_a?(Date) ? raw : Date.parse(raw.to_s)
+            dir = raw.is_a?(Date) ? raw.strftime("%Y-%m-%d") : raw.to_s
+            entry.merge(date: date, dir: dir)
+          end.sort_by { |r| r[:date] }
+        end
+
+        def load_manifest(lookup)
+          merged = {}
+          each_yaml(lookup, ["gov_codes", "afsc", "releases.yml"]) do |data|
+            merge_manifest!(merged, data)
+          end
+          merged
+        end
+
+        def load_release_index(release, publication, index_file, lookup)
+          merged = {}
+          parts = ["gov_codes", "afsc", "releases", publication, release[:dir], index_file]
+          each_yaml(lookup, parts) { |data| merged.merge!(data) }
+          apply_acronym_overlay(merged, publication, release, lookup)
+          merged
+        end
+
+        # Apply the consumer acronym overlay (Task 3, "dedicated tier"): a flat
+        # SPECIALTY => ACRONYM map at releases/<pub>/<dir>/acronyms.yml, resolved
+        # for the SAME release as the index and merged across the load path
+        # (consumer-loaded-last wins). Applied ONLY to specialties already in the
+        # index, so it sets an entry's :acronym without ever replacing the entry
+        # (the index merge above is shallow — overlaying whole entries here would
+        # drop name/skill_levels/shredouts). The consumer overlay wins over the
+        # source-extracted acronym shipped in the index. The gem ships no
+        # acronyms.yml; an absent overlay leaves the index unchanged. Resolved per
+        # release, so overlays never leak across document dates or publications.
+        def apply_acronym_overlay(merged, publication, release, lookup)
+          overlay = {}
+          parts = ["gov_codes", "afsc", "releases", publication, release[:dir], "acronyms.yml"]
+          each_yaml(lookup, parts) { |data| overlay.merge!(data) }
+          overlay.each do |specialty, acronym|
+            entry = merged[specialty]
+            entry[:acronym] = acronym if entry
+          end
+        end
+
+        # Merge a manifest hash into +acc+. Per-publication release lists are
+        # unioned by effective_date (a same-date entry from a later-loaded file
+        # wins); non-list values fall back to a plain overwrite.
+        def merge_manifest!(acc, incoming)
+          incoming.each do |publication, releases|
+            acc[publication] = if acc[publication].is_a?(Array) && releases.is_a?(Array)
+              union_releases(acc[publication], releases)
+            else
+              releases
+            end
+          end
+          acc
+        end
+
+        def union_releases(base, overrides)
+          by_date = {}
+          (base + overrides).each do |entry|
+            by_date[entry[:effective_date]] = entry if entry.is_a?(Hash)
+          end
+          by_date.values
+        end
+
+        # Yield each parsed YAML hash found at +parts+ across the lookup paths,
+        # skipping missing files and malformed YAML (graceful degradation).
+        def each_yaml(lookup, parts)
+          lookup_paths(lookup).each do |dir|
+            path = File.join(dir, *parts)
+            next unless File.exist?(path)
+
+            data = YAML.load_file(path, symbolize_names: true)
+            yield data if data.is_a?(Hash)
+          rescue Psych::SyntaxError, TypeError
+            next
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gov_codes/afsc/releases.yml

@@ -0,0 +1,11 @@
+---
+:dafecd:
+- :effective_date: '2025-10-31'
+  :version_label: v3.5
+  :source: DAFECD -31 October 25 v3.5 FINAL.pdf
+  :name: Department of the Air Force Enlisted Classification Directory
+:dafocd:
+- :effective_date: '2025-10-31'
+  :version_label: v3
+  :source: DAFOCD 31 Oct 25 v3.pdf
+  :name: Department of the Air Force Officer Classification Directory

data/lib/gov_codes/afsc/ri.rb

@@ -0,0 +1,207 @@
+require "strscan"
+require_relative "releases"
+
+module GovCodes
+  module AFSC
+    # Reporting Identifiers (RI) and Special Duty Identifiers (SDI), resolved
+    # against the versioned classification-directory release indexes. RI/SDI
+    # codes live in BOTH directories under two different code grammars:
+    #
+    #   Enlisted (DAFECD), 5-char:  \d[A-Z]\d{3}[A-Z]?   e.g. 9Z200, 8R300A
+    #   Officer  (DAFOCD), 4-char:  \d{2}[A-Z]\d[A-Z]?   e.g. 90G0,  92T1
+    #
+    # A single +find+ entry point dispatches by shape to the matching
+    # publication's ri.yml index (Releases.ri_index). Entries share the shape of
+    # enlisted/officer specialty records (:name, :acronym, :shredouts,
+    # :shredout_acronyms), so shredout suffixes and acronyms resolve exactly as
+    # they do for Enlisted/Officer.
+    module RI
+      class Parser
+        def initialize(code)
+          @code = code.to_s
+        end
+
+        # Try the 5-char enlisted shape first, then the 4-char officer shape.
+        # Both shapes are mutually exclusive (an enlisted code's 2nd char is a
+        # letter; an officer code's 2nd char is a digit), so at most one matches.
+        # The result carries the decomposed fields plus the :publication whose
+        # index should resolve the name; all nil when neither shape parses.
+        def parse
+          parse_enlisted || parse_officer || empty_result
+        end
+
+        private
+
+        def empty_result
+          {
+            career_group: nil,
+            career_field: nil,
+            identifier: nil,
+            suffix: nil,
+            specific_ri: nil,
+            publication: nil
+          }
+        end
+
+        # Enlisted shape: career_group (1 digit), career_field (digit+letter,
+        # e.g. "9Z"), identifier (3 digits), optional 1-letter suffix.
+        def parse_enlisted
+          scanner = StringScanner.new(@code)
+          career_group = scanner.scan(/\d/) or return nil
+          field_letter = scanner.scan(/[A-Z]/) or return nil
+          identifier = scanner.scan(/\d{3}/) or return nil
+          suffix = scanner.scan(/[A-Z]/)
+          return nil unless scanner.eos?
+
+          career_field = :"#{career_group}#{field_letter}"
+          {
+            career_group: career_group.to_sym,
+            career_field: career_field,
+            identifier: identifier.to_sym,
+            suffix: suffix&.to_sym,
+            specific_ri: :"#{career_field}#{identifier}",
+            publication: Releases::ENLISTED_PUBLICATION
+          }
+        end
+
+        # Officer shape: same grammar as an officer AFSC (2-digit career group +
+        # functional-area letter + 1-digit qualification level). There is no
+        # natural 3-digit identifier here, so these codes are mapped onto the
+        # SAME Code struct with the closest-matching semantics:
+        #   career_group  the 2-digit prefix   (e.g. :"90")
+        #   career_field  2-digit + letter     (e.g. :"90G")
+        #   identifier    the trailing digit   (e.g. :"0")  <- 1 digit, not 3;
+        #                                                       intentional, not a bug
+        #   specific_ri   the full 4-char code (e.g. :"90G0")
+        def parse_officer
+          scanner = StringScanner.new(@code)
+          career_group = scanner.scan(/\d{2}/) or return nil
+          field_letter = scanner.scan(/[A-Z]/) or return nil
+          identifier = scanner.scan(/\d/) or return nil
+          suffix = scanner.scan(/[A-Z]/)
+          return nil unless scanner.eos?
+
+          career_field = :"#{career_group}#{field_letter}"
+          {
+            career_group: career_group.to_sym,
+            career_field: career_field,
+            identifier: identifier.to_sym,
+            suffix: suffix&.to_sym,
+            specific_ri: :"#{career_field}#{identifier}",
+            publication: Releases::OFFICER_PUBLICATION
+          }
+        end
+      end
+
+      CODES = {}
+      private_constant :CODES
+
+      Code = Data.define(
+        :career_group,
+        :career_field,
+        :identifier,
+        :suffix,
+        :specific_ri,
+        :name,
+        :acronym,
+        :effective_date
+      )
+
+      # Resolve an RI/SDI code against the release in effect on +as_of+ (default:
+      # today). Dispatches by code shape to the enlisted (DAFECD) or officer
+      # (DAFOCD) ri.yml index. Returns nil when the code parses as neither shape,
+      # when the resolved index lacks the code, or when +as_of+ precedes the
+      # earliest shipped release for the relevant publication.
+      def self.find(code, as_of: nil)
+        code = code.to_s
+        parsed = Parser.new(code).parse
+        publication = parsed[:publication]
+        return nil unless publication
+
+        # Key the memo on the RESOLVED release date so equivalent as_of values
+        # (nil, the Date, its string form) share one slot.
+        effective_date = Releases.effective_date_for(as_of: as_of, publication: publication)
+        CODES[[code, effective_date]] ||= begin
+          index = Releases.ri_index(as_of: as_of, publication: publication)
+          entry = index[parsed[:specific_ri]]
+          return nil unless entry
+
+          suffix = parsed[:suffix]
+          # Shredout suffix meaning, only when the directory documents it.
+          shredout_name = suffix && entry.dig(:shredouts, suffix)
+          name = shredout_name || entry[:name]
+          return nil if name.nil?
+
+          # A documented shredout acronym wins for a shredded code; otherwise the
+          # entry's own acronym (which a consumer overlay may set).
+          shredout_acronym = suffix && entry.dig(:shredout_acronyms, suffix)
+
+          Code.new(
+            career_group: parsed[:career_group],
+            career_field: parsed[:career_field],
+            identifier: parsed[:identifier],
+            suffix: suffix,
+            specific_ri: parsed[:specific_ri],
+            name: name,
+            acronym: shredout_acronym || entry[:acronym],
+            effective_date: effective_date
+          )
+        end
+      end
+
+      # Resolve the RI/SDI code whose acronym matches +acronym+ (case-insensitive)
+      # in the release in effect on +as_of+. Scans the enlisted index first, then
+      # the officer index; within an entry the entry's own acronym is tried before
+      # its shredout acronyms (a shredout match returns the concrete shredded
+      # code). First match wins. Returns nil when no acronym in the resolved
+      # release(s) matches (no leakage across document dates).
+      def self.find_by_acronym(acronym, as_of: nil)
+        acronym = acronym.to_s.upcase
+        return nil if acronym.empty?
+
+        [Releases::ENLISTED_PUBLICATION, Releases::OFFICER_PUBLICATION].each do |publication|
+          index = Releases.ri_index(as_of: as_of, publication: publication)
+          index.each do |code, entry|
+            return find(code.to_s, as_of: as_of) if entry[:acronym].to_s.upcase == acronym
+
+            (entry[:shredout_acronyms] || {}).each do |suffix, acr|
+              return find("#{code}#{suffix}", as_of: as_of) if acr.to_s.upcase == acronym
+            end
+          end
+        end
+        nil
+      end
+
+      # Walk both publications' RI/SDI indexes for the release in effect on
+      # +as_of+, emitting each base code and its shredout-suffixed combinations,
+      # and return the Codes whose code starts with +prefix+.
+      def self.search(prefix, as_of: nil)
+        prefix = prefix.to_s.upcase
+
+        codes = []
+        [Releases::ENLISTED_PUBLICATION, Releases::OFFICER_PUBLICATION].each do |publication|
+          index = Releases.ri_index(as_of: as_of, publication: publication)
+          index.each do |code, entry|
+            code_str = code.to_s
+            codes << code_str
+            (entry[:shredouts] || {}).each_key do |suffix|
+              codes << "#{code_str}#{suffix}"
+            end
+          end
+        end
+
+        codes.select { |code| code.start_with?(prefix) }
+          .map { |code| find(code, as_of: as_of) }
+          .compact
+      end
+
+      # Clears the memoized lookups and resets the versioned release loader. The
+      # +lookup+ keyword is accepted for interface parity with Enlisted/Officer;
+      # the versioned index is resolved from the load path at lookup time.
+      def self.reset_data(lookup: $LOAD_PATH)
+        Releases.reset!
+        CODES.clear
+      end
+    end
+  end
+end

data/lib/gov_codes/afsc.rb

@@ -1,16 +1,48 @@
 require_relative "afsc/enlisted"
 require_relative "afsc/officer"
+require_relative "afsc/ri"
 
 module GovCodes
   module AFSC
-    def self.find(code)
-      AFSC::Enlisted.find(code) ||
-        AFSC::Officer.find(code)
+    # Resolve a code as of the classification-directory release in effect on
+    # +as_of+ (default: today). +as_of+ applies to every tier: the versioned
+    # enlisted (DAFECD) and officer (DAFOCD) AFSC lookups and the versioned
+    # RI/SDI lookup (which itself dispatches by code shape to the DAFECD or
+    # DAFOCD RI index), each resolved against its own publication.
+    def self.find(code, as_of: nil)
+      AFSC::Enlisted.find(code, as_of: as_of) ||
+        AFSC::Officer.find(code, as_of: as_of) ||
+        AFSC::RI.find(code, as_of: as_of)
+    end
+
+    # Resolve a code by its acronym (case-insensitive) as of the release in
+    # effect on +as_of+ (default: today). Searches the enlisted tier
+    # (source-verified acronyms + that release's overlay), then the officer
+    # tier (specialty and shredout acronyms + that release's overlay), then the
+    # versioned RI/SDI tier (enlisted then officer RI index for that release).
+    # Returns a single Code or nil.
+    #
+    # Acronyms are expected to be unique. If two codes carry the same acronym,
+    # the first match wins in a defined order: enlisted before officer before RI,
+    # and within a tier by the data's key order.
+    def self.find_by_acronym(acronym, as_of: nil)
+      AFSC::Enlisted.find_by_acronym(acronym, as_of: as_of) ||
+        AFSC::Officer.find_by_acronym(acronym, as_of: as_of) ||
+        AFSC::RI.find_by_acronym(acronym, as_of: as_of)
+    end
+
+    def self.search(prefix, as_of: nil)
+      results = []
+      results.concat(Enlisted.search(prefix, as_of: as_of))
+      results.concat(Officer.search(prefix, as_of: as_of))
+      results.concat(RI.search(prefix, as_of: as_of))
+      results
     end
 
     def self.reset_data(lookup: $LOAD_PATH)
       Enlisted.reset_data(lookup:)
       Officer.reset_data(lookup:)
+      RI.reset_data(lookup:)
     end
   end
 end