gov_codes 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bde662fd124b6754ac6c830f95e58cbcf63d8cce2168f04a410b5fe0df1c80d9
-  data.tar.gz: 77894785fb4edf1bcb2fe575fe6ed55932a7f0eadbd056988bd666742e7c2b06
+  metadata.gz: 11433a91ce2be5af9141fa58c9110a9d0f383b9769550f2fc95843b27d32da6b
+  data.tar.gz: 49d09edca49ae863444781be3da6eff64cffa2f499b8442d002736e7dc8624be
 SHA512:
-  metadata.gz: 0c8d2bcb57eb86164c8484b9db9b2c00bf9853a0fa0ef33178a8f02267d4558a88d3ca1834458de46c120a0bf68a0f3f566f65c65c865dda0c51c4ab7352ca05
-  data.tar.gz: 335e26092052f94f0b949cf28cc6c1d3d4194621f641dfa78b9098b05b71ddc6fb71c8a3e1c911d029064ff891b4114ea719a2faee4ab7d3c3d99a57959ed7ca
+  metadata.gz: 8dc82c96d74319e22b9d24d8ecc2f9c827eec171921f28158118fde4dc3586dcaa1ca5c06bd0827b954e5e659e5471eed404e7b704ad1d60f8231d9df6857e17
+  data.tar.gz: 4091a9fe8b0e0922817a01aeaaf0c48faf88339fb80431b7556975fa41c0e0c4445cc422dbcae782b91a1a8a1a4414d8ca3de8894b33af5a0742050bb73e4e3a

data/.simplecov

@@ -1,3 +1,6 @@
+# Set command name before starting to ensure consistent tracking
+SimpleCov.command_name "Unit Tests"
+
 SimpleCov.start do
   # enable_coverage :branch
 
@@ -12,6 +15,15 @@ SimpleCov.start do
   track_files "lib/**/*.rb"
 
   # Group files by module
-
   add_group "AFSC", "lib/gov_codes/afsc"
+
+  # Add JSON formatter for easier parsing
+  require "simplecov_json_formatter"
+  formatter SimpleCov::Formatter::MultiFormatter.new([
+    SimpleCov::Formatter::HTMLFormatter,
+    SimpleCov::Formatter::JSONFormatter
+  ])
+
+  # Enable result merging
+  enable_coverage_for_eval
 end

data/.tool-versions

@@ -1 +1 @@
-ruby 3.4.3
+ruby 4.0.5

data/CHANGELOG.md

@@ -5,16 +5,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
-## [0.1.1] - 2025-11-17
+## [0.1.2] - 2026-07-16
+
+### Added
+
+- 6C0X1 Contracting (4a6c87e)
+- 6F0X1 Financial Management and Comptroller (4a6c87e)
+- 7S0X1 Special Investigations (4a6c87e)
+- 5Z700/5Z800/5Z900 Chief Enlisted Manager codes (4a6c87e)
+- Concrete skill-level AFSC code lookup (e.g. 1A172Y) (1cea6af)
+- Version-aware lookup via find(code, as_of:) with effective_date (1cea6af)
+- Officer AFSC lookups versioned by DAFOCD release with as_of (1a43a2d)
+- Officer qualification-level titles and specialty/shredout acronyms (e.g. TACPO) (1a43a2d)
+- Officer specialties 17DX, 44BX, 45AX, 47BX, 47PX, 48GX from the DAFOCD (b28f308)
+- RI/SDI extraction pipeline (parser, index builder, CLI) for DAFECD and DAFOCD (5d068dd)
+- versioned RI/SDI release data at releases/{dafecd,dafocd}/2025-10-31/ri.yml (de03f09)
+- RI.find_by_acronym as a real reverse lookup; as_of threading through RI.find and RI.search (712f624)
 
 ### Changed
 
-- Test against Ruby 3.3.8 and 3.4.3
-- Officer YAML structure to match Wikipedia (11BX, 11MX, etc.) (4ca6aef)
-- Officer parser to accept letter qualification levels (X, Y, Z) (4ca6aef)
-- Officer lookup to include qualification level in key (4ca6aef)
-- Enlisted/Officer lookups to handle String leaf values (4ca6aef)
-- Use git trailers to track changelog changes. (c83929a)
+- Set dependabot cooldown to 14 days (fde4b9a)
+- Test against Ruby 4.0.5 (61983ce)
+- Source enlisted AFSC data from the official DAFECD instead of Wikipedia (1cea6af)
+- Source officer AFSC data from the official DAFOCD instead of Wikipedia (1a43a2d)
+- as_of defaults to today, not the newest release regardless of date (ff86c00)
+- RI resolves from the versioned DAFECD/DAFOCD release indexes instead of Wikipedia-sourced data (712f624)
+
+### Fixed
+
+- SimpleCov reporting inaccurate coverage due to at_exit ordering (de7063c)
+- glued shredout names in the enlisted release data (be773cf)
+- required_ruby_version understated the actual floor (b8d64b8)
+- officer ladder missed no-comma, glued-shred, and glyph-prefixed cards (b28f308)
+
+## [0.1.1] - 2025-11-17
 
 ### Added
 
@@ -25,16 +49,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Reporting identifiers with GovCodes::AFSC::RI (6102656)
 - AFSC.search to return an array of matching codes for the given prefix. (5c5bdf1)
 
-### Removed
-
-- 824 hallucinated codes not found in Wikipedia (4ca6aef)
-
-### Fixed
-
-- Tests updated to use real Wikipedia codes (4ca6aef)
-
-## [0.1.1] - 2025-11-17
-
 ### Changed
 
 - Test against Ruby 3.3.8 and 3.4.3
@@ -44,15 +58,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Enlisted/Officer lookups to handle String leaf values (4ca6aef)
 - Use git trailers to track changelog changes. (c83929a)
 
-### Added
-
-- AFSC Officer support (bb96aaa)
-- Data extractor script for Wikipedia (c8ec55b)
-- 1Z Special Warfare career field (Pararescue, Combat Control, TACP) (4ca6aef)
-- Nokogiri gem for HTML parsing (4ca6aef)
-- Reporting identifiers with GovCodes::AFSC::RI (6102656)
-- AFSC.search to return an array of matching codes for the given prefix. (5c5bdf1)
-
 ### Removed
 
 - 824 hallucinated codes not found in Wikipedia (4ca6aef)

data/README.md

@@ -31,28 +31,79 @@ require 'gov_codes/afsc'
 
 # Find an enlisted AFSC code
 code = GovCodes::AFSC.find("1A1X2")
-puts code.name # => "Mobility force aviator"
+puts code.name # => "Mobility Force Aviator"
 puts code.career_field # => "1A"
 puts code.career_field_subdivision # => "1A1"
 puts code.skill_level # => "X"
 puts code.specific_afsc # => "1A1X2"
 puts code.shredout # => nil
-
-# Find an officer AFSC code
+puts code.effective_date # => #<Date: 2025-10-31>
+
+# Look up the concrete code an HR system actually stores
+# (the "7" is the airman's skill level: Craftsman)
+code = GovCodes::AFSC.find("1A172Y")
+code.specialty_name     # => "Mobility Force Aviator"
+code.skill_level_number # => 7
+code.skill_level_name   # => "Craftsman" (title comes from the directory)
+code.specialty          # => :"1A1X2"
+
+# shredout_name resolves the shredout's meaning when that shredout
+# exists in the data (nil otherwise)
+code = GovCodes::AFSC.find("1A172A")
+code.shredout_name      # => "C-5 Flight Engineer"
+
+# Enlisted lookups are versioned by DAFECD release (published each 30 Apr and
+# 31 Oct). `find`/`search` default to today's date; pass `as_of:` (a Date or
+# "YYYY-MM-DD" string) to resolve the release in effect on a different date. A
+# release only takes effect on its own effective_date, even if it's the most
+# recently added one (e.g. one you pre-load ahead of its official date).
+code = GovCodes::AFSC.find("1A172Y", as_of: "2025-11-01")
+code.effective_date     # => #<Date: 2025-10-31>
+# A date before the earliest shipped release has no data and returns nil.
+GovCodes::AFSC.find("1A172Y", as_of: "2000-01-01") # => nil
+
+# Find an officer AFSC code. Officer lookups are versioned by DAFOCD release
+# (like enlisted); `find`/`search` default to today's date and accept the
+# same `as_of:`.
 code = GovCodes::AFSC.find("11MX")
-puts code.name # => "Mobility pilot"
+puts code.name # => "Mobility Pilot"
 puts code.career_group # => "11"
 puts code.functional_area # => "M"
 puts code.qualification_level # => "X"
 puts code.shredout # => nil
+puts code.effective_date # => #<Date: 2025-10-31>
+
+# A concrete qualification level derives the X-form specialty and its title
+code = GovCodes::AFSC.find("11B3")
+code.specialty                 # => :"11BX"
+code.specialty_name            # => "Bomber Pilot"
+code.qualification_level_number # => 3
+code.qualification_level_name  # => "Aircraft Commander" (title from the directory)
+
+# Some officer specialties are keyed by a literal bare code (a single command/
+# materiel-leader position, not a qualification ladder): 10C0, 62S0, 63G0, 63S0.
+# These resolve ONLY via their literal code -- there is no X-form for them, so
+# find("10CX") / find("62SX") return nil by design.
+GovCodes::AFSC.find("10C0").name # => "Operations Commander"
+GovCodes::AFSC.find("10CX")       # => nil (bare-code specialty; no X-form)
+
+# An officer code carries its acronym; a shredout acronym wins for a shredded code
+GovCodes::AFSC.find("16F3").acronym  # => "FAO"
+GovCodes::AFSC.find("19ZXB").acronym # => "TACPO"
 
 # Find a Reporting Identifier (RI) or Special Duty Identifier (SDI)
 code = GovCodes::AFSC.find("8A400")
-puts code.name # => "Talent management consultant"
+puts code.name # => "Talent Management Consultant"
 puts code.career_field # => "8A"
 puts code.identifier # => "400"
 puts code.suffix # => nil
 
+# An RI/SDI code carries its source-verified acronym, and reverse lookup is
+# case-insensitive and as_of-aware, just like enlisted/officer AFSCs:
+GovCodes::AFSC.find("9M200").acronym # => "IHS"
+GovCodes::AFSC.find_by_acronym("IHS", as_of: "2025-11-01").name
+# => "International Health Specialists (IHS)"
+
 # Find a code with a shredout/suffix
 code = GovCodes::AFSC.find("11BXA")
 puts code.name # => "B-1"
@@ -72,9 +123,9 @@ results.each do |code|
 end
 # Output:
 # 1Z1X1: Pararescue
-# 1Z2X1: Combat control
-# 1Z3X1: Tactical air control party (TACP)
-# 1Z4X1: Special reconnaissance
+# 1Z2X1: Combat Control
+# 1Z3X1: Tactical Air Control Party (TACP)
+# 1Z4X1: Special Reconnaissance
 
 # Search for Bomber Pilot shredouts
 results = GovCodes::AFSC.search("11BX")
@@ -95,36 +146,140 @@ GovCodes::AFSC.search("1z1") # Same as search("1Z1")
 
 ### Extending with Custom AFSC Codes
 
-You can extend the default AFSC codes with your own custom codes by placing a YAML file in your application's load path:
+Enlisted codes are stored as a specialty-keyed index per DAFECD release. You can
+extend or override a release by dropping an index file for that release's
+effective date onto your application's load path:
+
+```yaml
+# In your application's lib/gov_codes/afsc/releases/dafecd/2025-10-31/enlisted.yml
+:"9Z9X9":
+  :name: Custom Specialty
+  :career_field: :"9Z"
+  :skill_levels:
+    7:
+      :code: 9Z979
+      :title: Craftsman
+  :shredouts:
+    :A: Custom Shredout
+```
+
+The gem merges your index over the shipped index for the matching release,
+adding new specialties and overriding existing ones.
+
+You can also add a whole new release (e.g. a newer directory the gem has not
+shipped yet) by listing it in a `releases.yml` on your load path. Release lists
+are unioned by effective date, so adding a release never hides the shipped ones;
+a same-date entry from your file overrides the shipped manifest entry:
+
+```yaml
+# In your application's lib/gov_codes/afsc/releases.yml
+:dafecd:
+- :effective_date: '2026-04-30'
+  :version_label: v3.6
+  :source: DAFECD-30-April-26.pdf
+  :name: Department of the Air Force Enlisted Classification Directory
+```
+
+Pair it with a matching `releases/dafecd/2026-04-30/enlisted.yml` index, and
+`find(code, as_of: "2026-04-30")` will resolve against it.
+
+## Data source & provenance
+
+AFSC data is extracted from the official **Department of the Air Force classification directories** — the DAFECD (enlisted) and DAFOCD (officer) — not third-party sources. Extraction is deterministic, and every code is verified to appear verbatim in the source directory: no predicted or hallucinated codes.
+
+The data is **versioned by each directory's effective date** (the directories are republished roughly semi-annually, on 30 April and 31 October). Look a code up as it stands today, or as it stood for a given release:
+
+```ruby
+GovCodes::AFSC.find("1A172Y")                        # the release in effect today
+GovCodes::AFSC.find("1A172Y", as_of: "2025-11-01")   # the release in effect on that date
+GovCodes::AFSC.find("1A172Y").effective_date         # => the release the result came from
+```
+
+`as_of: nil` (the default) is today's date, not "whatever's newest" — a release only takes effect on its own effective_date. This only differs from "the latest shipped release" if a release dated in the future has been added to the load path (see "Extending with Custom AFSC Codes" above); until that date arrives, lookups keep resolving against the current release.
+
+**Currently shipped:** enlisted AFSCs from the DAFECD and officer AFSCs from the DAFOCD, plus the reporting/special-duty identifiers (RI/SDI) from both directories (enlisted 5-char from the DAFECD, officer 4-char from the DAFOCD) — all effective 31 October 2025. SEIs, prefixes, and the full Space Force Specialty Codes (SFSC) are planned.
+
+### Specialty acronyms
+
+A resolved code carries an `acronym` field:
 
 ```ruby
-# In your application's lib/gov_codes/afsc/enlisted.yml
-9Z:
-  name: Custom AFSC
-  subcategories:
-    0X1:
-      name: Custom Subcategory
-      subcategories:
-        A:
-          name: Custom Shredout
+GovCodes::AFSC.find("1C8X3").acronym   # => "RAWS"
+GovCodes::AFSC.find("1Z3X1").acronym   # => "TACP"
+GovCodes::AFSC.find("1A1X2").acronym   # => nil (no acronym)
+
+# Reverse lookup by acronym (case-insensitive, and `as_of`-aware — it searches
+# the acronyms of the release in effect on that date, so overlays never leak
+# across document dates):
+GovCodes::AFSC.find_by_acronym("RAWS")                     # => the 1C8X3 Code
+GovCodes::AFSC.find_by_acronym("raws")                     # => same (case-insensitive)
+GovCodes::AFSC.find_by_acronym("PJ", as_of: "2025-11-01")  # => resolves that release's overlay
+GovCodes::AFSC.find_by_acronym("nope")                     # => nil
+
+# Officer acronyms resolve too — including shredout acronyms, which return the
+# concrete shredded code:
+GovCodes::AFSC.find_by_acronym("TACPO")  # => the 19ZXB Code (Special Warfare, TACP Officer)
+GovCodes::AFSC.find_by_acronym("FAO")    # => the 16FX Code (Foreign Area Officer)
 ```
 
-The gem will automatically merge your custom codes with the default codes, overriding any existing codes.
+Shipped acronyms are **source-verified**: they are captured only from a trailing parenthetical in the directory title (e.g. `Radar, Airfield & Weather Systems (RAWS)`) and the build gate rejects any acronym that does not appear verbatim in the source title. Five enlisted specialties ship an acronym this way (`1A8X1`, `1C8X3`, `1N1X1`, `1Z3X1`, `4B0X1`); nothing else is invented.
+
+Everything else — colloquial acronyms not printed in the directory (e.g. `PJ` for Pararescue) — is **consumer-curated** via an optional overlay you drop on your load path. Overlays are flat `SPECIALTY => ACRONYM` (or `CODE => ACRONYM`) maps:
+
+```yaml
+# Enlisted, per DAFECD release date:
+# lib/gov_codes/afsc/releases/dafecd/2025-10-31/acronyms.yml
+:"1Z1X1": PJ      # augments the Pararescue entry; name/skill_levels/shredouts untouched
+:"1Z3X1": JTAC    # overrides the shipped TACP acronym
+
+# Officer, per DAFOCD release date:
+# lib/gov_codes/afsc/releases/dafocd/2025-10-31/acronyms.yml
+:"11MX": MOBPLT   # augments the Mobility Pilot entry (ships no acronym)
+:"16FX": FAREA    # overrides the shipped FAO acronym
+
+# RI/SDI acronyms live in the SAME per-release acronyms.yml, keyed by RI code:
+# 5-char enlisted RI in the DAFECD file, 4-char officer RI in the DAFOCD file.
+:"8A400": TMC     # enlisted RI/SDI -> dafecd/<date>/acronyms.yml
+:"90G0": GENOFF   # officer RI/SDI  -> dafocd/<date>/acronyms.yml
+```
+
+Key points:
+
+- **Enlisted, officer, and RI/SDI overlays are all per-release-date**, scoped by the directory's effective date, so `find(code, as_of: "2025-11-01")` applies that release's overlay — and each publication resolves independently, so an officer overlay never affects an enlisted lookup or vice versa. RI/SDI reuses the same per-release, per-publication `acronyms.yml` tier (enlisted RI from the DAFECD file, officer RI from the DAFOCD file), so an RI overlay never crosses into an enlisted/officer lookup either.
+- The overlay is a **separate tier** — it only sets `:acronym` on entries that already exist and never replaces an entry, so `name`, `qual_levels`/`skill_levels`, and `shredouts` stay intact.
+- **Precedence:** the consumer overlay wins over the shipped, source-verified acronym. For officer codes a documented shredout acronym still wins for a shredded code. The gem ships no overlay file, so absent one the shipped index is used as-is.
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`.
+### Regenerating the data
 
-This project is managed with [Reissue](https://github.com/SOFware/reissue).
+Enlisted (DAFECD) and officer (DAFOCD) indexes are regenerated deterministically
+from the official classification-directory PDFs by `bin/extract_afsc_from_pdf.rb`
+(offline dev tooling; never loaded by the gem runtime). It writes the versioned
+release artifact under `lib/gov_codes/afsc/releases/<publication>/<date>/`, updates
+the manifest, and fails loudly before writing if any code, title, acronym, or
+shredout override is not grounded in the source:
+
+```bash
+mise exec -- ruby bin/extract_afsc_from_pdf.rb "DAFECD -31 October 25 v3.5 FINAL.pdf"
+mise exec -- ruby bin/extract_afsc_from_pdf.rb "DAFOCD 31 Oct 25 v3.pdf"
+```
 
-To release a new version, make your changes and be sure to update the CHANGELOG.md.
+The retired `bin/extract_afsc_from_wikipedia.rb` (which generated the old flat
+enlisted/officer YAML) has been removed in favor of the PDF extractor. RI/SDI
+data is now sourced from the same DAFECD (enlisted, 5-char) and DAFOCD (officer,
+4-char) directories, under the same anti-hallucination gate — every RI code,
+title, and acronym must appear verbatim in the source — and ships as versioned
+artifacts (`releases/<publication>/<date>/ri.yml`) alongside the enlisted and
+officer indexes.
 
-To release a new version:
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+This project is managed with [Reissue](https://github.com/SOFware/reissue).
 
-1. `bundle exec rake build:checksum`
-2. `bundle exec rake release`
+Releases are automated via the [shared release workflow](https://github.com/SOFware/reissue/blob/main/.github/workflows/SHARED_WORKFLOW_README.md). Trigger a release by running the "Release gem to RubyGems.org" workflow from the Actions tab.
 
 ## Contributing
 

data/Rakefile

@@ -3,7 +3,11 @@
 require "bundler/gem_tasks"
 require "minitest/test_task"
 
-Minitest::TestTask.create
+Minitest::TestTask.create do |t|
+  # Load test_helper before minitest/autorun to ensure SimpleCov's at_exit
+  # handler runs AFTER tests complete (at_exit runs in LIFO order)
+  t.test_prelude = 'require "test_helper"'
+end
 
 require "standard/rake"
 
@@ -13,5 +17,6 @@ require "reissue/gem"
 
 Reissue::Task.create :reissue do |task|
   task.version_file = "lib/gov_codes/version.rb"
-  task.fragment = :git # Enable git trailer extraction for changelog
+  task.fragment = :git
+  task.push_finalize = :branch
 end

data/checksums/gov_codes-0.1.1.gem.sha512

@@ -0,0 +1 @@
+1a8f6a45b4e04a3a4502853a10d91f9684a7adeebad467b8b97f1904161bf4629a6ebf86ad177d73be605a484a521d9f4f36e289b301500d841bdc9887c31f6a

data/lib/gov_codes/afsc/enlisted.rb

@@ -1,10 +1,17 @@
 require "strscan"
-require "yaml"
-require_relative "../data_loader"
+require_relative "releases"
 
 module GovCodes
   module AFSC
     module Enlisted
+      SKILL_LEVELS = {
+        1 => "Helper",
+        3 => "Apprentice",
+        5 => "Journeyman",
+        7 => "Craftsman",
+        9 => "Senior Enlisted Leader"
+      }.freeze
+
       class Parser
         def initialize(code)
           @code = code
@@ -18,6 +25,10 @@ module GovCodes
             career_field: nil,
             career_field_subdivision: nil,
             skill_level: nil,
+            skill_level_number: nil,
+            skill_level_name: nil,
+            specialty: nil,
+            specialty_name: nil,
             specific_afsc: nil,
             subcategory: nil,
             shredout: nil
@@ -41,20 +52,29 @@ module GovCodes
           return result unless subdivision_digit
           result[:career_field_subdivision] = :"#{result[:career_field]}#{subdivision_digit}"
 
-          # Scan for skill level letter (usually X)
-          skill_level_letter = scanner.scan(/[A-Z]/)
-          return result unless skill_level_letter
-          result[:skill_level] = skill_level_letter.to_sym
+          # Scan for skill level: an X placeholder OR a concrete digit.
+          # NOTE: any digit is accepted here for now; validating that it is a
+          # real skill level (1/3/5/7/9) is deferred to Phase C.
+          skill_char = scanner.scan(/[A-Z0-9]/)
+          return result unless skill_char
+          result[:skill_level] = skill_char.to_sym
+
+          # Concrete skill level -> numeric level + standard title
+          if skill_char.match?(/\d/)
+            result[:skill_level_number] = Integer(skill_char)
+            result[:skill_level_name] = SKILL_LEVELS[result[:skill_level_number]]
+          end
 
-          # Scan for skill level digit
-          skill_level_digit = scanner.scan(/\d/)
-          return result unless skill_level_digit
+          # Scan for the specific AFSC digit
+          specific_digit = scanner.scan(/\d/)
+          return result unless specific_digit
 
-          # Subcategory is subdivision digit + letter + digit (e.g. '1X2')
-          result[:subcategory] = :"#{subdivision_digit}#{skill_level_letter}#{skill_level_digit}"
+          # Normalize to the X-form specialty key regardless of concrete skill level
+          result[:subcategory] = :"#{subdivision_digit}X#{specific_digit}"
+          result[:specialty] = :"#{result[:career_field_subdivision]}X#{specific_digit}"
 
-          # Build specific AFSC
-          result[:specific_afsc] = :"#{result[:career_field_subdivision]}#{skill_level_letter}#{skill_level_digit}"
+          # specific_afsc preserves the code exactly as entered (concrete or generic)
+          result[:specific_afsc] = :"#{result[:career_field_subdivision]}#{skill_char}#{specific_digit}"
 
           # Scan for shredout (optional)
           result[:shredout] = scanner.scan(/[A-Z]/)&.to_sym
@@ -66,9 +86,8 @@ module GovCodes
         end
       end
 
-      extend GovCodes::DataLoader
-
-      DATA = data
+      CODES = {}
+      private_constant :CODES
 
       Code = Data.define(
         :prefix,
@@ -76,15 +95,30 @@ module GovCodes
         :career_field,
         :career_field_subdivision,
         :skill_level,
+        :skill_level_number,
+        :skill_level_name,
+        :specialty,
+        :specialty_name,
         :specific_afsc,
         :subcategory,
         :shredout,
-        :name
+        :shredout_name,
+        :name,
+        :acronym,
+        :effective_date
       )
 
-      def self.find(code)
+      # Resolve an enlisted AFSC against the DAFECD release in effect on +as_of+
+      # (default: today). Returns nil when the code does not parse, when the
+      # specialty is absent from the resolved release, or when +as_of+ precedes
+      # the earliest shipped release (or no release has taken effect yet).
+      def self.find(code, as_of: nil)
         code = code.to_s
-        CODES[code] ||= begin
+        # Key the memo on the RESOLVED release date so equivalent as_of values
+        # (nil, the Date, its string form, any date in the same release window)
+        # share one slot instead of growing unbounded for time-series callers.
+        effective_date = Releases.effective_date_for(as_of: as_of)
+        CODES[[code, effective_date]] ||= begin
           parser = Parser.new(code)
           result = parser.parse
 
@@ -101,81 +135,78 @@ module GovCodes
           return nil if code.length > 7 ||
             code.match?(/[^A-Z0-9]/)
 
-          # Find the name by recursively searching the codes hash
-          name = find_name_recursive(result)
+          # Resolve the specialty entry from the versioned, specialty-keyed index
+          index = Releases.enlisted_index(as_of: as_of)
+          entry = index[result[:specialty]]
+          return nil unless entry
+
+          specialty_name = entry[:name]
 
-          # Return nil if name is 'Unknown'
-          return nil if name == "Unknown"
+          # Skill-level title: prefer the directory's title for this specialty,
+          # falling back to the universal enlisted skill-level map.
+          if (number = result[:skill_level_number])
+            result[:skill_level_name] = entry.dig(:skill_levels, number, :title) ||
+              SKILL_LEVELS[number]
+          end
+
+          # Shredout meaning, only when the directory documents this shredout.
+          shredout_name = result[:shredout] && entry.dig(:shredouts, result[:shredout])
 
-          # Add the name to the result
+          name = shredout_name || specialty_name
+          return nil if name.nil?
+
+          result[:shredout_name] = shredout_name
+          result[:specialty_name] = specialty_name
           result[:name] = name
+          # Specialty acronym from the resolved index entry (nil when absent).
+          result[:acronym] = entry[:acronym]
+          result[:effective_date] = effective_date
 
-          # Create a new Code object with the result
           Code.new(**result)
         end
       end
 
-      def self.find_name_recursive(result)
-        data = DATA
-
-        # Career field (e.g., "9Z")
-        cf = result[:career_field]&.to_sym
-        return "Unknown" unless cf && data[cf]
-        name = data[cf][:name]
-        data = data[cf][:subcategories]
-
-        # Subcategory (e.g., "0X1" from "9Z0X1")
-        if data && result[:subcategory]
-          sub = result[:subcategory].to_sym
-          lookup_value = data[sub]
-          if lookup_value
-            if lookup_value.is_a?(Hash)
-              name = lookup_value[:name] || name
-              data = lookup_value[:subcategories]
-            else
-              # String value (leaf node)
-              name = lookup_value
-              data = nil
-            end
-          end
-        end
-
-        # Shredout (optional, e.g., :A)
-        if data && result[:shredout]
-          lookup_value = data[result[:shredout]]
-          if lookup_value
-            name = lookup_value.is_a?(Hash) ? (lookup_value[:name] || name) : (lookup_value || name)
-          end
-        end
-
-        name || "Unknown"
+      # Resolve the enlisted specialty whose acronym matches +acronym+
+      # (case-insensitive) in the release in effect on +as_of+. Returns the
+      # generic (X-form) Code for that specialty, or nil when no specialty in the
+      # resolved release carries the acronym. Acronyms come from the shipped,
+      # source-verified data and any consumer overlay for that release, so the
+      # match is scoped to that release (no leakage across document dates).
+      def self.find_by_acronym(acronym, as_of: nil)
+        acronym = acronym.to_s.upcase
+        return nil if acronym.empty?
+
+        index = Releases.enlisted_index(as_of: as_of)
+        match = index.find { |_specialty, entry| entry[:acronym].to_s.upcase == acronym }
+        return nil unless match
+
+        find(match.first.to_s, as_of: as_of)
       end
 
-      def self.search(prefix)
-        results = []
-        prefix = prefix.to_s.upcase
-        collect_codes_recursive(DATA, "", prefix, results)
-        results.map { |code| find(code) }.compact
+      # Clears the memoized lookups and resets the versioned release loader.
+      # The +lookup+ keyword is accepted for interface parity with Officer/RI;
+      # the versioned index is resolved from the load path at lookup time.
+      def self.reset_data(lookup: $LOAD_PATH)
+        Releases.reset!
+        CODES.clear
       end
 
-      def self.collect_codes_recursive(data, current_code, prefix, results)
-        return unless data.is_a?(Hash)
-
-        data.each do |key, value|
-          code = "#{current_code}#{key}"
-
-          if value.is_a?(Hash) && value[:name]
-            # This is a node with a name and possibly subcategories
-            results << code if code.start_with?(prefix)
-            collect_codes_recursive(value[:subcategories], code, prefix, results) if value[:subcategories]
-          elsif value.is_a?(String)
-            # This is a leaf node (simple string value)
-            results << code if code.start_with?(prefix)
-          elsif value.is_a?(Hash)
-            # Nested subcategories without a name at this level
-            collect_codes_recursive(value, current_code, prefix, results)
+      def self.search(prefix, as_of: nil)
+        prefix = prefix.to_s.upcase
+        index = Releases.enlisted_index(as_of: as_of)
+
+        codes = []
+        index.each do |specialty, entry|
+          specialty_code = specialty.to_s
+          codes << specialty_code
+          (entry[:shredouts] || {}).each_key do |shredout|
+            codes << "#{specialty_code}#{shredout}"
           end
         end
+
+        codes.select { |code| code.start_with?(prefix) }
+          .map { |code| find(code, as_of: as_of) }
+          .compact
       end
     end
   end