ucode 0.1.1 → 0.2.1

data/lib/ucode/commands/lookup.rb

@@ -5,42 +5,42 @@ require "pathname"
 require "ucode/cache"
 require "ucode/database"
 require "ucode/repo"
-require "ucode/version_resolver"
 
 module Ucode
   module Commands
     # `ucode lookup` — read-only lookups against the SQLite cache and
     # the output JSON tree. Three subactions: block, script, char.
+    #
+    # Takes a resolved version string; CLI callers resolve via
+    # {VersionResolver.resolve} once and thread it through. See
+    # Candidate 4 of the 2026-06-29 architecture review.
     class LookupCommand
       BlockResult = Struct.new(:codepoint, :block, keyword_init: true)
       ScriptResult = Struct.new(:codepoint, :script, keyword_init: true)
       CharResult = Struct.new(:codepoint, :block_id, :glyph_path, keyword_init: true)
       private_constant :BlockResult, :ScriptResult, :CharResult
 
-      # @param version_intent [nil, :default, :latest, String]
+      # @param version [String] resolved UCD version
       # @param codepoint [Integer]
       # @return [BlockResult]
-      def lookup_block(version_intent, codepoint:)
-        version = VersionResolver.resolve(version_intent)
+      def lookup_block(version, codepoint:)
         with_db(version) { |db| db.lookup_block(codepoint) }
           .then { |block| BlockResult.new(codepoint: codepoint, block: block) }
       end
 
-      # @param version_intent [nil, :default, :latest, String]
+      # @param version [String] resolved UCD version
       # @param codepoint [Integer]
       # @return [ScriptResult]
-      def lookup_script(version_intent, codepoint:)
-        version = VersionResolver.resolve(version_intent)
+      def lookup_script(version, codepoint:)
         with_db(version) { |db| db.lookup_script(codepoint) }
           .then { |script| ScriptResult.new(codepoint: codepoint, script: script) }
       end
 
-      # @param version_intent [nil, :default, :latest, String]
+      # @param version [String] resolved UCD version
       # @param codepoint [Integer]
       # @param output_root [String, Pathname]
       # @return [CharResult]
-      def lookup_char(version_intent, codepoint:, output_root:)
-        version = VersionResolver.resolve(version_intent)
+      def lookup_char(version, codepoint:, output_root:)
         block_id = with_db(version) { |db| db.lookup_block(codepoint) }
         glyph = block_id ? glyph_path(output_root, block_id, codepoint) : nil
         CharResult.new(codepoint: codepoint, block_id: block_id, glyph_path: glyph)
@@ -62,4 +62,4 @@ module Ucode
       end
     end
   end
-end
+end

data/lib/ucode/commands/parse.rb

@@ -6,19 +6,21 @@ require "ucode/cache"
 require "ucode/coordinator"
 require "ucode/parsers"
 require "ucode/repo"
-require "ucode/version_resolver"
 
 module Ucode
   module Commands
     # `ucode parse` — streams the Coordinator output into the on-disk
     # JSON tree at `output/`. Single pass: enrich + write per-cp JSON +
     # accumulate aggregates + final flush.
+    #
+    # Takes a resolved version string; CLI callers resolve via
+    # {VersionResolver.resolve} once and thread it through. See
+    # Candidate 4 of the 2026-06-29 architecture review.
     class ParseCommand
-      # @param version_intent [nil, :default, :latest, String]
+      # @param version [String] resolved UCD version
       # @param output_root [String, Pathname]
       # @return [Hash] { version:, codepoint_count: }
-      def call(version_intent, output_root:)
-        version = VersionResolver.resolve(version_intent)
+      def call(version, output_root:)
         root = Pathname.new(output_root)
         ucd_dir = Cache.ucd_dir(version)
         unihan_dir = Cache.unihan_dir(version)
@@ -59,4 +61,4 @@ module Ucode
       end
     end
   end
-end
+end

data/lib/ucode/commands/release.rb

@@ -7,7 +7,6 @@ require "ucode/audit"
 require "ucode/audit/library_auditor"
 require "ucode/audit/release"
 require "ucode/audit/emitter/paths"
-require "ucode/commands/audit/reference_builder"
 
 module Ucode
   module Commands

data/lib/ucode/commands/universal_set.rb

@@ -39,7 +39,7 @@ module Ucode
       # (in `lib/ucode/cli.rb`) is responsible only for argument
       # parsing and dispatch.
       class BuildCommand
-        # @param version_intent [nil, :default, :latest, String]
+        # @param version [String] resolved UCD version
         # @param output_root [String, Pathname] directory that will
         #   hold `manifest.json`, `glyphs/`, `reports/`.
         # @param source_config_path [String, Pathname, nil] override
@@ -58,10 +58,9 @@ module Ucode
         #   resolver and don't have a real source config on disk.
         # @return [Hash] { version:, manifest_path:, totals:,
         #   by_tier:, coverage:, validation: }
-        def call(version_intent, output_root:, source_config_path: nil,
+        def call(version, output_root:, source_config_path: nil,
                  resolver: nil, block_filter: nil,
                  parallel_workers: default_workers, skip_pre_check: false)
-          version = VersionResolver.resolve(version_intent)
           root = Pathname.new(output_root)
 
           config_path = source_config_path_or_default(source_config_path)
@@ -144,7 +143,7 @@ module Ucode
       # checks (config loads, fonts present, coverage assertion runs)
       # without starting the 4-hour build.
       class PreCheckCommand
-        # @param version_intent [nil, :default, :latest, String]
+        # @param version [String] resolved UCD version
         # @param source_config_path [String, Pathname, nil]
         # @param cmaps [#covers?] injectable; defaults to
         #   RealFonts::CmapCache.
@@ -153,9 +152,8 @@ module Ucode
         # @return [Ucode::Glyphs::UniversalSet::PreBuildReport]
         # @raise [Ucode::UniversalSetPreBuildError] when missing_fonts
         #   is non-empty or the config fails to load.
-        def call(version_intent, source_config_path: nil, cmaps: nil,
+        def call(version, source_config_path: nil, cmaps: nil,
                  font_locator: nil)
-          version = VersionResolver.resolve(version_intent)
           database = Database.open(version)
           config_path = source_config_path || Glyphs::SourceConfig::DEFAULT_PATH
 
@@ -171,12 +169,11 @@ module Ucode
       # shape (or regenerating reports after a model change) without
       # re-running the build.
       class ReportCommand
-        # @param version_intent [nil, :default, :latest, String]
+        # @param version [String] resolved UCD version
         # @param output_root [String, Pathname] directory holding
         #   `manifest.json`.
         # @return [Hash] the {CoverageReport#emit} payload.
-        def call(version_intent, output_root:)
-          version = VersionResolver.resolve(version_intent)
+        def call(version, output_root:)
           root = Pathname.new(output_root)
           manifest_path = root.join("manifest.json")
           raise Ucode::Error, "manifest not found at #{manifest_path}" unless manifest_path.exist?
@@ -196,12 +193,11 @@ module Ucode
       # totals_reconcile, provenance_complete).
       class ValidateCommand
         # @param output_root [String, Pathname]
-        # @param version_intent [nil, :default, :latest, String]
-        #   used only to stamp the report's unicode_version when the
-        #   manifest's recorded value is missing.
+        # @param version [String, nil] resolved UCD version, used only
+        #   to stamp the report's unicode_version when the manifest's
+        #   recorded value is missing.
         # @return [Hash] the {Validator#validate} payload.
-        def call(output_root, version_intent: nil)
-          version = version_intent && VersionResolver.resolve(version_intent)
+        def call(output_root, version: nil)
           Glyphs::UniversalSet::Validator
             .new(output_root, unicode_version: version).validate
         end

data/lib/ucode/coordinator/indices.rb

@@ -2,6 +2,22 @@
 
 module Ucode
   class Coordinator
+    # Pairs of (output-file-slug, indices-field) for every per-property
+    # relationship table the Repo writes. Each field holds a Hash whose
+    # values are Records (or Arrays of Records). The Repo iterates
+    # `Indices#each_relationship` instead of reaching into the Struct by
+    # field name (see Candidate 1 of the 2026-06-29 architecture review).
+    RELATIONSHIPS = [
+      ["special_casing",        :special_casing],
+      ["case_folding",          :case_folding],
+      ["bidi_mirroring",        :bidi_mirroring],
+      ["bidi_brackets",         :bidi_brackets],
+      ["cjk_radicals",          :cjk_radicals],
+      ["standardized_variants", :standardized_variants],
+      ["name_aliases",          :name_aliases],
+    ].freeze
+    private_constant :RELATIONSHIPS
+
     # Bag of pre-built indices consumed by the per-codepoint enrichment
     # pass. Every field is a frozen-shaped collection that is read-only
     # after `build_indices` returns: range files land in sorted Arrays
@@ -12,6 +28,10 @@ module Ucode
     # call reads as a self-documenting catalogue of every parsed file —
     # adding a new index is one keyword arg here, one builder call in
     # `Coordinator#build_indices`, and one assignment in `#enrich`.
+    #
+    # The relationship enumerator (`#each_relationship`) is the seam the
+    # Repo uses to write per-property relationship tables without knowing
+    # which Struct field carries which data.
     Indices = Struct.new(
       :blocks,
       :scripts,
@@ -40,6 +60,22 @@ module Ucode
       :emoji_properties,
       :extra_binary_properties,
       keyword_init: true,
-    )
+    ) do
+      # Yield (slug, records) for each relationship table. The seam
+      # between "what the Coordinator indexed" and "what the Repo writes"
+      # lives here — Repo never names a Struct field directly.
+      #
+      # @yieldparam slug [String] output file slug under
+      #   `output/relationships/`
+      # @yieldparam records [Hash<Integer|String, Record|Array<Record>>]
+      # @return [Enumerator] when no block is given
+      def each_relationship(&block)
+        return enum_for(:each_relationship) unless block_given?
+
+        RELATIONSHIPS.each do |slug, field|
+          yield(slug, public_send(field))
+        end
+      end
+    end
   end
-end
+end

data/lib/ucode/error.rb

@@ -97,6 +97,10 @@ module Ucode
   # Version string not in Config.known_versions.
   class UnknownVersionError < LookupError; end
 
+  # Block identifier not present in the cached Blocks.txt. Carries the
+  # offending id and the path searched in `context:`.
+  class UnknownBlockError < LookupError; end
+
   # Glyph pipeline failures.
   class GlyphError < Error; end
 
@@ -114,6 +118,13 @@ module Ucode
   # `mutool` is not installed on the PATH.
   class EmbeddedFontsMissingError < GlyphError; end
 
+  # The Code Charts PDF for a requested block cannot be obtained: the
+  # network returned 4xx/5xx, the response wasn't application/pdf, or
+  # the body didn't start with the `%PDF` magic. Distinct from
+  # {EmbeddedFontsMissingError} (which fires when the file is already
+  # on disk and we just can't open it): this fires at fetch time.
+  class CodeChartNotFoundError < GlyphError; end
+
   # Pre-build validation failed for a universal-set build. The
   # context carries the failing checks so the CLI can render a
   # useful diagnostic without re-running them. Distinct from

data/lib/ucode/fetch/code_charts.rb

@@ -29,7 +29,7 @@ module Ucode
             next if dest.exist? && !force
 
             url = "#{Ucode.configuration.charts_base_url}/#{filename}"
-            Http.get(url, dest: dest)
+            Http.get(url, dest: dest, validate: :pdf)
             downloaded += 1
           end
           downloaded

data/lib/ucode/fetch/http.rb

@@ -23,9 +23,17 @@ module Ucode
         #   directory is created if absent.
         # @param retries [Integer, nil] override Config.http_retries.
         # @param timeout [Integer, nil] override Config.http_timeout.
+        # @param validate [Symbol, nil] when `:pdf`, after a successful
+        #   download verify (a) Content-Type starts with `application/pdf`
+        #   and (b) the first 4 bytes of the body are `%PDF`. Raises
+        #   {Ucode::CodeChartNotFoundError} with the offending header
+        #   value in `context:` on failure. nil = no validation (the
+        #   default for non-PDF callers like UcdZip and UnihanZip).
         # @return [Pathname] destination path on success.
         # @raise [Ucode::NetworkError] if all retries fail.
-        def get(url, dest:, retries: nil, timeout: nil)
+        # @raise [Ucode::CodeChartNotFoundError] when `validate: :pdf`
+        #   and the response fails content validation.
+        def get(url, dest:, retries: nil, timeout: nil, validate: nil)
           uri = url.is_a?(URI) ? url : URI(url)
           destination = Pathname.new(dest)
           destination.dirname.mkpath
@@ -36,15 +44,21 @@ module Ucode
 
           last_error = nil
           (attempts + 1).times do |attempt|
-            return stream_to(uri, destination, read_timeout)
-          rescue StandardError => e
-            last_error = e
-            sleep_for = backoff_sequence[attempt] || backoff_sequence.last
-            Ucode.configuration.logger&.warn do
-              "Http GET #{uri} failed (attempt #{attempt + 1}/#{attempts + 1}): " \
-                "#{e.class}: #{e.message}; retrying in #{sleep_for}s"
+            begin
+              response = stream_to(uri, destination, read_timeout)
+              validate_response!(validate, response, destination) if validate
+              return destination
+            rescue ValidationFailure => e
+              raise e.cause
+            rescue StandardError => e
+              last_error = e
+              sleep_for = backoff_sequence[attempt] || backoff_sequence.last
+              Ucode.configuration.logger&.warn do
+                "Http GET #{uri} failed (attempt #{attempt + 1}/#{attempts + 1}): " \
+                  "#{e.class}: #{e.message}; retrying in #{sleep_for}s"
+              end
+              sleep(sleep_for)
             end
-            sleep(sleep_for)
           end
 
           raise Ucode::NetworkError.new(
@@ -55,19 +69,34 @@ module Ucode
 
         private
 
+        # Internal carrier for a validation failure inside a retry
+        # attempt. Re-raised from the loop so the response body (which
+        # is partial on retries) isn't double-validated against
+        # truncated bytes.
+        class ValidationFailure < StandardError
+          attr_reader :cause
+
+          def initialize(cause)
+            @cause = cause
+            super(cause.message)
+          end
+        end
+
         def stream_to(uri, destination, read_timeout)
+          response = nil
           Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
                                               read_timeout: read_timeout) do |http|
             request = Net::HTTP::Get.new(uri)
-            http.request(request) do |response|
-              unless response.is_a?(Net::HTTPSuccess)
-                raise "HTTP #{response.code} #{response.message}"
+            http.request(request) do |r|
+              unless r.is_a?(Net::HTTPSuccess)
+                raise "HTTP #{r.code} #{r.message}"
               end
 
-              write_body(response, destination)
+              write_body(r, destination)
+              response = r
             end
           end
-          destination
+          response or raise "no response received"
         end
 
         def write_body(response, destination)
@@ -77,6 +106,47 @@ module Ucode
           end
           File.rename(partial.to_s, destination.to_s)
         end
+
+        # Verifies Content-Type and magic bytes for a downloaded file.
+        # Raises ValidationFailure carrying a CodeChartNotFoundError so
+        # the retry loop in `get` doesn't re-attempt a download that's
+        # structurally invalid (only the transport is retriable).
+        def validate_response!(mode, response, destination)
+          case mode
+          when :pdf then validate_pdf!(response, destination)
+          else raise ArgumentError, "unknown validate mode: #{mode.inspect}"
+          end
+        end
+
+        PDF_CONTENT_TYPE_PREFIX = "application/pdf"
+        PDF_MAGIC = "%PDF"
+        private_constant :PDF_CONTENT_TYPE_PREFIX, :PDF_MAGIC
+
+        def validate_pdf!(response, destination)
+          content_type = response["Content-Type"].to_s
+          unless content_type.start_with?(PDF_CONTENT_TYPE_PREFIX)
+            raise ValidationFailure.new(
+              Ucode::CodeChartNotFoundError.new(
+                "expected Content-Type application/pdf, got #{content_type.inspect}",
+                context: { url: response.uri.to_s, content_type: content_type },
+              ),
+            )
+          end
+
+          # Re-open the destination file and peek at the first 4 bytes.
+          # The response body has already been written to disk by
+          # `stream_to`; we don't re-read from the response (which is
+          # consumed by then).
+          magic = File.open(destination, "rb") { |f| f.read(4) }
+          unless magic == PDF_MAGIC
+            raise ValidationFailure.new(
+              Ucode::CodeChartNotFoundError.new(
+                "expected %PDF magic bytes, got #{magic.inspect}",
+                context: { url: response.uri.to_s, magic: magic },
+              ),
+            )
+          end
+        end
       end
     end
   end

data/lib/ucode/glyphs/pipeline.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "set"
+
+require "ucode/cache"
+require "ucode/glyphs/pdf_fetcher"
+require "ucode/glyphs/writer"
+require "ucode/parsers"
+
+module Ucode
+  module Glyphs
+    # Assembles the per-block specs that {Glyphs::Writer#write_all} drains.
+    #
+    # Owns three pieces of orchestration that {Commands::GlyphsCommand}
+    # used to carry inline:
+    #
+    #   - block loading from {Cache.ucd_dir}/Blocks.txt (with an optional
+    #     block filter)
+    #   - PDF fetcher construction (with monolith fallback)
+    #   - the per-block page-map heuristic (per-block PDFs are page 1 =
+    #     title, page 2 = first chart page starting at the block's first
+    #     codepoint; true for most BMP blocks; multi-page blocks need a
+    #     richer resolver — mismatches yield placeholder SVGs only, never
+    #     wrong glyphs)
+    #
+    # The Command stays a thin wrapper that prints the experimental
+    # warning and wires the writer. See Candidate 3 of the 2026-06-29
+    # architecture review.
+    class Pipeline
+      # Path to the monolith fallback file when no per-block PDF is on
+      # disk yet. Overridable for tests.
+      DEFAULT_MONOLITH_PATH = "CodeCharts.pdf"
+      # Cache path for the page-map corpus. Overridable for tests.
+      DEFAULT_PAGE_MAP_CACHE = "data/codecharts_page_map.json"
+
+      Spec = Struct.new(:block, :pdf_path, :page_map, keyword_init: true)
+
+      # @param version [String] resolved UCD version (callers must
+      #   resolve via {VersionResolver.resolve} first)
+      # @param block_filter [Array<String>, nil] block ids to limit to;
+      #   nil = every block
+      # @param monolith_path [String, Pathname, nil] fallback monolith
+      # @param page_map_cache [String, Pathname] cache for the page map
+      def initialize(version:, block_filter: nil,
+                     monolith_path: DEFAULT_MONOLITH_PATH,
+                     page_map_cache: DEFAULT_PAGE_MAP_CACHE)
+        @version = version
+        @block_filter = block_filter
+        @monolith_path = monolith_path
+        @page_map_cache = page_map_cache
+      end
+
+      # Load every block from the cached Blocks.txt (filtered by
+      # `@block_filter` when set) and pair each one with a fetched PDF
+      # path and a page map. Blocks whose PDF cannot be fetched are
+      # silently dropped — the placeholder pass downstream covers them.
+      #
+      # @param force [Boolean] re-fetch PDFs even when cached
+      # @return [Array<Spec>]
+      def build_specs(force: false)
+        blocks = load_blocks
+        fetcher = build_fetcher(blocks)
+        blocks.map { |block| spec_for(block, fetcher, force) }.compact
+      end
+
+      private
+
+      def load_blocks
+        path = Cache.ucd_dir(@version).join("Blocks.txt")
+        return [] unless path.exist?
+
+        all = Parsers::Blocks.each_record(path).to_a
+        return all unless @block_filter && !@block_filter.empty?
+
+        filter_set = @block_filter.to_set
+        all.select { |block| filter_set.include?(block.id) }
+      end
+
+      def build_fetcher(blocks)
+        monolith = @monolith_path ? Pathname.new(@monolith_path) : nil
+        monolith = monolith.exist? ? monolith : nil
+        PdfFetcher.new(
+          @version,
+          monolith_path: monolith,
+          blocks: blocks,
+          page_map_cache: @page_map_cache,
+        )
+      end
+
+      def spec_for(block, fetcher, force)
+        pdf_path = fetcher.fetch(block_first_cp: block.range_first, force: force)
+        return nil unless pdf_path
+
+        Spec.new(block: block, pdf_path: pdf_path, page_map: page_map_for(block))
+      end
+
+      # Per-block PDFs are page 1 = title, page 2 = first chart page
+      # starting at the block's first codepoint. True for most BMP
+      # blocks; multi-page blocks (CJK) need a richer resolver.
+      def page_map_for(block)
+        { 2 => block.range_first }
+      end
+    end
+  end
+end

data/lib/ucode/glyphs.rb

@@ -20,6 +20,7 @@ module Ucode
     autoload :CellExtractor, "ucode/glyphs/cell_extractor"
     autoload :MonolithPageMap, "ucode/glyphs/monolith_page_map"
     autoload :Writer, "ucode/glyphs/writer"
+    autoload :Pipeline, "ucode/glyphs/pipeline"
     autoload :LastResort, "ucode/glyphs/last_resort"
     autoload :EmbeddedFonts, "ucode/glyphs/embedded_fonts"
     autoload :RealFonts, "ucode/glyphs/real_fonts"

data/lib/ucode/parsers/blocks.rb

@@ -37,6 +37,40 @@ module Ucode
           nil
         end
 
+        # Resolves a block by its identifier (the underscored form of
+        # the block name, e.g. "Basic_Latin", "Egyptian_Hieroglyphs_Extended-B").
+        # Streams `Blocks.txt` once and short-circuits on first match —
+        # callers don't need to walk the whole ~340-block file.
+        #
+        # @param path [Pathname, String] path to a Blocks.txt
+        # @param id [String] block identifier (matches `Models::Block#id`)
+        # @return [Models::Block, nil] the block, or nil when no block
+        #   has the given id
+        def find_by_id(path, id)
+          return nil if id.nil? || id.empty?
+
+          each_record(path) do |block|
+            return block if block.id == id
+          end
+          nil
+        end
+
+        # Same as {find_by_id} but raises {Ucode::UnknownBlockError} on
+        # miss. Use this in callers that can't recover from a missing
+        # block (CLI commands, extractors that need a block to proceed).
+        #
+        # @param path [Pathname, String] path to a Blocks.txt
+        # @param id [String] block identifier
+        # @return [Models::Block]
+        # @raise [Ucode::UnknownBlockError] when no block matches
+        def find_by_id!(path, id)
+          find_by_id(path, id) or
+            raise Ucode::UnknownBlockError.new(
+              "unknown Unicode block: #{id.inspect}",
+              context: { block_id: id, blocks_txt: path.to_s },
+            )
+        end
+
         private
 
         def build_block(range, name)