ucode 0.3.3 → 0.5.0

data/lib/ucode/glyphs/embedded_fonts/pdf_indexer.rb

@@ -1,23 +1,23 @@
 # frozen_string_literal: true
 
-require "open3"
 require "pathname"
 
+require "ucode/glyphs/embedded_fonts/mutool"
+
 module Ucode
   module Glyphs
     module EmbeddedFonts
-      # Walks the Code Charts PDF once via `mutool info` + `mutool show`
-      # and builds an Array of {RawFontDescriptor} — one per Type0 font
-      # that has the required descendant CIDFont, FontDescriptor, and
-      # FontFile2/3 + Identity CIDToGIDMap.
-      #
-      # Pure subprocess + parsing concern. Does NOT resolve codepoint →
-      # GID (that's {CodepointMapper}'s job). The descriptor carries
-      # every ref the mapper needs to do its work.
       class PdfIndexer
-        # @param source [PdfLocation]
-        def initialize(source:)
+        Type0Entry = Struct.new(:font_obj_id, :base_font, keyword_init: true)
+
+        # @param source [PdfSource]
+        # @param mutool_info [Mutool::Info] injectable for tests
+        # @param mutool_show [Mutool::Show] injectable for tests
+        def initialize(source:, mutool_info: Mutool::Info.new,
+                       mutool_show: Mutool::Show.new)
           @source = source
+          @mutool_info = mutool_info
+          @mutool_show = mutool_show
         end
 
         # @return [Array<RawFontDescriptor>]
@@ -68,11 +68,45 @@ module Ucode
         # @param base_font [String] e.g. "GPJAHB+WolofGaraySansSerif"
         # @return [Boolean] true if this font appears on any page
         def font_appears?(base_font)
-          font_entries_cache.key?(base_font)
+          type0_base_fonts.include?(base_font)
         end
 
         private
 
+        # Single source of truth for the Type0 font list. Both
+        # `discover_type0_fonts` (keyed by obj_id) and
+        # `font_appears?` (membership check by name) derive their
+        # answer from this parse, so changes to `mutool info`'s output
+        # format break in exactly one place.
+        #
+        # @return [Array<Type0Entry>]
+        def type0_entries
+          @type0_entries ||= parse_type0_entries
+        end
+
+        # @return [Set<String>] every Type0 BaseFont name seen
+        def type0_base_fonts
+          @type0_base_fonts ||= type0_entries.each_with_object(Set.new) do |e, s|
+            s << e.base_font
+          end
+        end
+
+        def parse_type0_entries
+          seen = Set.new
+          mutool_info_text.each_line.filter_map do |line|
+            next unless line.include?("Type0")
+
+            m = line.match(/Type0\s+'([^']+)'\s+\S+\s+\((\d+)\s+0\s+R\)/)
+            next unless m
+
+            font_obj_id = m[2].to_i
+            next if seen.include?(font_obj_id)
+
+            seen << font_obj_id
+            Type0Entry.new(font_obj_id: font_obj_id, base_font: m[1])
+          end
+        end
+
         def build_descriptors(type0_refs, type0_dicts, descendant_dicts, fontdesc_dicts)
           type0_refs.filter_map do |font_obj_id, base_font|
             build_descriptor(
@@ -133,35 +167,15 @@ module Ucode
         # ---- mutool subprocess + dict parsing ----------------------------
 
         def discover_type0_fonts
-          text = mutool_info_text
-          result = {}
-          seen = Set.new
-          text.each_line do |line|
-            next unless line.include?("Type0")
-
-            m = line.match(/Type0\s+'([^']+)'\s+\S+\s+\((\d+)\s+0\s+R\)/)
-            next unless m
-
-            font_obj_id = m[2].to_i
-            next if seen.include?(font_obj_id)
-
-            seen << font_obj_id
-            result[font_obj_id] = m[1]
+          type0_entries.to_h do |e|
+            [e.font_obj_id, e.base_font]
           end
-          result
         end
 
         def fetch_objects(obj_ids)
           return {} if obj_ids.empty?
 
-          args = ["mutool", "show", "-g",
-                  @source.pdf_to_s].concat(obj_ids.map(&:to_s))
-          out, err, status = Open3.capture3(*args)
-          unless status.success?
-            raise Ucode::EmbeddedFontsMissingError,
-                  "mutool show failed: #{err.strip}"
-          end
-
+          out = @mutool_show.grep(@source.pdf_to_s, *obj_ids)
           parse_grep_output(out)
         end
 
@@ -208,27 +222,7 @@ module Ucode
         end
 
         def mutool_info_text
-          @mutool_info_text ||= run_mutool_info
-        end
-
-        def run_mutool_info
-          out, err, status = Open3.capture3("mutool", "info", @source.pdf_to_s)
-          status.success? ? out + err : ""
-        end
-
-        def font_entries_cache
-          @font_entries_cache ||= begin
-            result = {}
-            mutool_info_text.each_line do |line|
-              next unless line.include?("Type0")
-
-              font_match = line.match(/Type0\s+'([^']+)'/)
-              next unless font_match
-
-              result[font_match[1]] = true
-            end
-            result
-          end
+          @mutool_info_text ||= @mutool_info.call(@source.pdf_to_s)
         end
       end
     end

data/lib/ucode/glyphs/embedded_fonts/{pdf_location.rb → pdf_source.rb}

@@ -27,7 +27,7 @@ module Ucode
       # the BaseFont (e.g. `CIAIIP+Uni2000Generalpunctuation.ttf`).
       # Re-runs skip extraction when the cached file is newer than the
       # PDF.
-      class PdfLocation
+      class PdfSource
         attr_reader :pdf_path, :cache_dir
 
         # @param pdf [String, Pathname, nil] path to a Code Charts PDF

data/lib/ucode/glyphs/embedded_fonts/renderer.rb

@@ -12,7 +12,16 @@ module Ucode
       # renderer.
       class Renderer
         # Result of rendering one codepoint.
-        Result = Struct.new(:codepoint, :base_font, :gid, :svg, keyword_init: true) do
+        #
+        # `source_page` + `source_cell` come from the Catalog's
+        # location index when available. Nil when the catalog hasn't
+        # traced the PDF (ToUnicode-only path) — downstream concerns
+        # treat that as "no positional data; skip cell-based diff".
+        Result = Struct.new(
+          :codepoint, :base_font, :gid, :svg,
+          :source_page, :source_cell,
+          keyword_init: true,
+        ) do
           def ok?
             !svg.nil?
           end
@@ -37,7 +46,15 @@ module Ucode
           return nil if outline.nil? || outline.empty?
 
           svg = Svg.new(outline, codepoint: codepoint, base_font: entry.base_font).to_s
-          Result.new(codepoint: codepoint, base_font: entry.base_font, gid: gid, svg: svg)
+          location = @catalog.location_for(codepoint)
+          Result.new(
+            codepoint: codepoint,
+            base_font: entry.base_font,
+            gid: gid,
+            svg: svg,
+            source_page: location&.fetch(:page),
+            source_cell: location && { x: location[:x], y: location[:y] },
+          )
         end
       end
     end

data/lib/ucode/glyphs/embedded_fonts/trace_runner.rb

@@ -1,51 +1,35 @@
 # frozen_string_literal: true
 
-require "open3"
 require "pathname"
 
-require "ucode/error"
+require "ucode/glyphs/embedded_fonts/mutool"
+require "ucode/glyphs/embedded_fonts/trace_parser"
 
 module Ucode
   module Glyphs
     module EmbeddedFonts
       # Thin I/O wrapper around `mutool trace <pdf> <page>`.
       #
-      # Runs mutool on the given pages, captures the XML output,
-      # delegates parsing to {TraceParser}, and returns a flat
-      # `Array<TraceGlyph>` across all pages.
-      #
-      # The only class in the trace pipeline that touches the
-      # filesystem / spawns subprocesses. Everything upstream
-      # (parser, correlator) is pure.
+      # Delegates the actual subprocess to {Mutool::Trace} and the
+      # XML parsing to {TraceParser}. Kept for backward compatibility
+      # with callers that pre-date the Mutool seam.
       class TraceRunner
         # @param pdf_path [Pathname, String]
-        def initialize(pdf_path)
+        # @param mutool [Mutool::Trace] injectable for tests
+        def initialize(pdf_path, mutool: Mutool::Trace.new)
           @pdf_path = Pathname.new(pdf_path)
+          @mutool = mutool
         end
 
         # @param page_numbers [Array<Integer>] 1-based PDF page numbers
         # @return [Array<TraceGlyph>]
         def trace(page_numbers)
-          page_numbers.flat_map { |page| trace_page(page) }
-        end
-
-        private
+          return [] if page_numbers.empty?
 
-        def trace_page(page)
-          xml = run_mutool(page)
-          TraceParser.parse(xml)
-        end
-
-        def run_mutool(page)
-          out, err, status = Open3.capture3(
-            "mutool", "trace", @pdf_path.to_s, page.to_s,
-          )
-          unless status.success?
-            raise Ucode::EmbeddedFontsMissingError,
-                  "mutool trace failed: #{(out + err).strip}"
+          page_numbers.flat_map do |page|
+            xml = @mutool.call(@pdf_path, page)
+            TraceParser.parse(xml)
           end
-
-          out + err
         end
       end
     end

data/lib/ucode/glyphs/embedded_fonts.rb

@@ -36,7 +36,7 @@ module Ucode
     # `mutool info` (font enumeration) and `mutool show -b -o` (raw
     # stream extraction).
     module EmbeddedFonts
-      autoload :PdfLocation, "ucode/glyphs/embedded_fonts/pdf_location"
+      autoload :PdfSource, "ucode/glyphs/embedded_fonts/pdf_source"
       autoload :ToUnicode, "ucode/glyphs/embedded_fonts/tounicode"
       autoload :FontEntry, "ucode/glyphs/embedded_fonts/font_entry"
       autoload :RawFontDescriptor, "ucode/glyphs/embedded_fonts/raw_font_descriptor"
@@ -50,6 +50,8 @@ module Ucode
       autoload :TraceParser, "ucode/glyphs/embedded_fonts/trace_parser"
       autoload :TraceCorrelator, "ucode/glyphs/embedded_fonts/trace_correlator"
       autoload :TraceRunner, "ucode/glyphs/embedded_fonts/trace_runner"
+      autoload :Mutool, "ucode/glyphs/embedded_fonts/mutool"
+      autoload :PageTraceCache, "ucode/glyphs/embedded_fonts/page_trace_cache"
       autoload :Svg, "ucode/glyphs/embedded_fonts/svg"
       autoload :Renderer, "ucode/glyphs/embedded_fonts/renderer"
       autoload :Writer, "ucode/glyphs/embedded_fonts/writer"

data/lib/ucode/glyphs/real_fonts/coverage_auditor.rb

@@ -5,10 +5,6 @@ require "time"
 
 require "fontisan"
 
-require_relative "block_coverage"
-require_relative "font_coverage_report"
-require_relative "unicode_17_blocks"
-
 module Ucode
   module Glyphs
     module RealFonts

data/lib/ucode/glyphs/real_fonts/font_coverage_report.rb

@@ -2,8 +2,6 @@
 
 require "lutaml/model"
 
-require_relative "block_coverage"
-
 module Ucode
   module Glyphs
     module RealFonts

data/lib/ucode/glyphs/real_fonts/writer.rb

@@ -3,8 +3,6 @@
 require "fileutils"
 require "pathname"
 
-require_relative "font_coverage_report"
-
 module Ucode
   module Glyphs
     module RealFonts

data/lib/ucode/glyphs/source.rb

@@ -25,7 +25,17 @@ module Ucode
       # One resolved glyph. Carries the SVG payload and enough
       # provenance to debug "where did this glyph come from?" without
       # holding a reference back to the source.
-      Result = Struct.new(:tier, :codepoint, :svg, :provenance, keyword_init: true)
+      #
+      # The optional `base_font`, `gid`, `source_page`, `source_cell`
+      # fields carry the renderer's localization data so downstream
+      # concerns (Verifier pixel-diff against the source PDF cell,
+      # Provenance audit trail) don't need to re-derive it. Sources
+      # that don't know this data (e.g. LastResort) leave them nil.
+      Result = Struct.new(
+        :tier, :codepoint, :svg, :provenance,
+        :base_font, :gid, :source_page, :source_cell,
+        keyword_init: true,
+      )
 
       # @return [Symbol] one of :tier1, :pillar1, :pillar2, :pillar3
       def tier

data/lib/ucode/glyphs/sources/pillar1_embedded_tounicode.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require "ucode/glyphs/source"
-require "ucode/glyphs/embedded_fonts/renderer"
-
 module Ucode
   module Glyphs
     module Sources
@@ -31,7 +28,7 @@ module Ucode
         # @param renderer [EmbeddedFonts::Renderer] the renderer to
         #   delegate to. Callers typically construct it with the
         #   {EmbeddedFonts::Catalog} built from the resolved Code
-        #   Charts {EmbeddedFonts::PdfLocation}. To enable pillar-2
+        #   Charts {EmbeddedFonts::PdfSource}. To enable pillar-2
         #   fallback, that Catalog must be constructed with
         #   +correlator_configs:+.
         def initialize(renderer:)
@@ -54,8 +51,16 @@ module Ucode
           result = @renderer.render(codepoint)
           return nil unless result
 
-          Result.new(tier: tier, codepoint: codepoint,
-                     svg: result.svg, provenance: provenance)
+          Result.new(
+            tier: tier,
+            codepoint: codepoint,
+            svg: result.svg,
+            provenance: provenance,
+            base_font: result.base_font,
+            gid: result.gid,
+            source_page: result.source_page,
+            source_cell: result.source_cell,
+          )
         end
       end
     end

data/lib/ucode/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ucode
-  VERSION = "0.3.3"
+  VERSION = "0.5.0"
 end

data/lib/ucode.rb

@@ -34,7 +34,9 @@ module Ucode
   autoload :GlyphError, "ucode/error"
   autoload :LastResortMissingError, "ucode/error"
   autoload :EmbeddedFontsMissingError, "ucode/error"
+  autoload :CodeChartError, "ucode/error"
   autoload :CodeChartNotFoundError, "ucode/error"
+  autoload :CodeChartChecksumError, "ucode/error"
   autoload :UnknownUnicodeVersionError, "ucode/error"
 
   # Infrastructure

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ucode
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.5.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-03 00:00:00.000000000 Z
+date: 2026-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -162,77 +162,6 @@ files:
 - Gemfile
 - README.md
 - Rakefile
-- TODO.extract-code-chart/01-pdf-fetch-validation.md
-- TODO.extract-code-chart/02-block-name-resolver.md
-- TODO.extract-code-chart/03-codechart-namespace.md
-- TODO.extract-code-chart/04-codechart-extractor.md
-- TODO.extract-code-chart/05-provenance-and-sidecar.md
-- TODO.extract-code-chart/06-codechart-writer.md
-- TODO.extract-code-chart/07-codechart-cli.md
-- TODO.extract-code-chart/08-specs.md
-- TODO.full/00-README.md
-- TODO.full/01-panglyph-vision.md
-- TODO.full/02-panglyph-repo-bootstrap.md
-- TODO.full/03-panglyph-font-builder.md
-- TODO.full/04-panglyph-publish-pipeline.md
-- TODO.full/05-ucode-0-1-1-release.md
-- TODO.full/06-fontisan-remove-audit.md
-- TODO.full/07-fontisan-remove-ucd.md
-- TODO.full/08-archive-private-bin-build.md
-- TODO.full/09-archive-public-structure.md
-- TODO.full/10-fontist-org-woff-glyphs.md
-- TODO.full/11-fontist-org-audit-coverage.md
-- TODO.full/12-implementation-order.md
-- TODO.full/13-fontisan-font-writer-api.md
-- TODO.full/14-fontisan-table-writers.md
-- TODO.full/15-panglyph-builder-real.md
-- TODO.full/16-archive-public-sync-workflows.md
-- TODO.full/17-fontist-org-font-picker.md
-- TODO.full/18-comprehensive-spec-coverage.md
-- TODO.full/19-ucode-0-1-2-patch.md
-- TODO.full/20-fontisan-0-2-23-release.md
-- TODO.new/00-README.md
-- TODO.new/01-pillar-terminology-alignment.md
-- TODO.new/02-audit-schema-design.md
-- TODO.new/03-directory-output-spec.md
-- TODO.new/04-fontist-org-contract.md
-- TODO.new/05-baseline-unicode17-coverage-audit.md
-- TODO.new/06-audit-namespace-skeleton.md
-- TODO.new/07-audit-models-port.md
-- TODO.new/08-extractors-cheap-port.md
-- TODO.new/09-extractors-expensive-port.md
-- TODO.new/10-aggregations-ucd-rewrite.md
-- TODO.new/11-differ-and-library-auditor-port.md
-- TODO.new/12-formatters-port.md
-- TODO.new/13-directory-emitter.md
-- TODO.new/14-html-face-browser.md
-- TODO.new/15-html-library-browser.md
-- TODO.new/16-cli-audit-subcommands.md
-- TODO.new/17-fontisan-cleanup-audit.md
-- TODO.new/18-fontisan-cleanup-ucd.md
-- TODO.new/19-fontisan-docs-update.md
-- TODO.new/20-canonical-resolver-4-tier.md
-- TODO.new/21-canonical-unicode17-build.md
-- TODO.new/22-implementation-order.md
-- TODO.new/23-universal-glyph-set-source-map.md
-- TODO.new/24-universal-glyph-set-build.md
-- TODO.new/25-font-audit-against-universal-set.md
-- TODO.new/26-missing-glyph-reporter.md
-- TODO.new/27-fontist-org-consumer-integration.md
-- TODO.new/28-implementation-order-update.md
-- TODO.new/29-universal-set-curation-uc17.md
-- TODO.new/30-tier1-font-acquisition.md
-- TODO.new/31-universal-set-production-build.md
-- TODO.new/32-uc17-coverage-matrix.md
-- TODO.new/33-specialist-font-acquisition-refresh.md
-- TODO.new/34-pillar2-content-stream-correlator.md
-- TODO.new/35-universal-set-production-run.md
-- TODO.new/36-per-font-coverage-audit.md
-- TODO.new/37-coverage-highlight-reporter.md
-- TODO.new/38-fontist-org-glyph-consumer.md
-- TODO.new/39-implementation-order-update-32-38.md
-- TODO.new/40-archive-private-uses-ucode-audit.md
-- TODO.new/41-ucode-unicode-archive-bridge.md
 - UCODE_CHANGELOG.md
 - config/specialist_fonts.yml
 - config/unicode17_tier1_fonts.yml
@@ -310,9 +239,24 @@ files:
 - lib/ucode/cache.rb
 - lib/ucode/cli.rb
 - lib/ucode/code_chart.rb
+- lib/ucode/code_chart/batch_runner.rb
+- lib/ucode/code_chart/block_index.rb
+- lib/ucode/code_chart/coverage_gap_index.rb
 - lib/ucode/code_chart/extractor.rb
+- lib/ucode/code_chart/fetcher.rb
+- lib/ucode/code_chart/gap_analyzer.rb
+- lib/ucode/code_chart/gap_analyzer/block_gap.rb
+- lib/ucode/code_chart/gap_analyzer/essenfont_manifest.rb
+- lib/ucode/code_chart/gap_analyzer/manifest.rb
 - lib/ucode/code_chart/provenance.rb
 - lib/ucode/code_chart/sidecar.rb
+- lib/ucode/code_chart/verifier.rb
+- lib/ucode/code_chart/verifier/builder.rb
+- lib/ucode/code_chart/verifier/mutool_strategy.rb
+- lib/ucode/code_chart/verifier/page_render_cache.rb
+- lib/ucode/code_chart/verifier/result.rb
+- lib/ucode/code_chart/verifier/resvg_strategy.rb
+- lib/ucode/code_chart/verifier/strategy.rb
 - lib/ucode/code_chart/writer.rb
 - lib/ucode/commands.rb
 - lib/ucode/commands/audit.rb
@@ -363,10 +307,20 @@ files:
 - lib/ucode/glyphs/embedded_fonts.rb
 - lib/ucode/glyphs/embedded_fonts/catalog.rb
 - lib/ucode/glyphs/embedded_fonts/codepoint_mapper.rb
+- lib/ucode/glyphs/embedded_fonts/codepoint_mapper/correlator_strategy.rb
+- lib/ucode/glyphs/embedded_fonts/codepoint_mapper/strategy.rb
+- lib/ucode/glyphs/embedded_fonts/codepoint_mapper/tounicode_strategy.rb
+- lib/ucode/glyphs/embedded_fonts/codepoint_mapper/trace_strategy.rb
 - lib/ucode/glyphs/embedded_fonts/content_stream_correlator.rb
 - lib/ucode/glyphs/embedded_fonts/font_entry.rb
+- lib/ucode/glyphs/embedded_fonts/mutool.rb
+- lib/ucode/glyphs/embedded_fonts/mutool/draw.rb
+- lib/ucode/glyphs/embedded_fonts/mutool/info.rb
+- lib/ucode/glyphs/embedded_fonts/mutool/show.rb
+- lib/ucode/glyphs/embedded_fonts/mutool/trace.rb
+- lib/ucode/glyphs/embedded_fonts/page_trace_cache.rb
 - lib/ucode/glyphs/embedded_fonts/pdf_indexer.rb
-- lib/ucode/glyphs/embedded_fonts/pdf_location.rb
+- lib/ucode/glyphs/embedded_fonts/pdf_source.rb
 - lib/ucode/glyphs/embedded_fonts/positional_matcher.rb
 - lib/ucode/glyphs/embedded_fonts/raw_font_descriptor.rb
 - lib/ucode/glyphs/embedded_fonts/renderer.rb

data/TODO.extract-code-chart/01-pdf-fetch-validation.md

@@ -1,80 +0,0 @@
-# TODO 01 — PDF fetch validation
-
-## Status
-
-Pending.
-
-## Goal
-
-Raise a typed `Ucode::CodeChartNotFoundError` when a Unicode Code
-Charts PDF cannot be downloaded or fails content validation. The REQ
-(R1) requires:
-
-- HTTP 4xx / 5xx → `CodeChartNotFoundError`
-- `Content-Type: application/pdf`
-- First 4 bytes are `%PDF`
-
-## Files
-
-- `lib/ucode/error.rb` — add `Ucode::CodeChartNotFoundError` under the
-  `GlyphError` subtree.
-- `lib/ucode.rb` — add an `autoload` for the new class so any rescue
-  clause triggers one load of `error.rb`.
-- `lib/ucode/fetch/http.rb` — extend `Http.get` with an optional
-  `validate:` keyword. When `validate: :pdf`, after a successful
-  download, verify the `Content-Type` response header starts with
-  `application/pdf` and the first 4 bytes of the body are `%PDF`.
-- `lib/ucode/fetch/code_charts.rb` — pass `validate: :pdf` to `Http.get`
-  for every chart PDF download.
-- `spec/ucode/fetch/code_charts_spec.rb` (new) — cover the happy path
-  and the validation failure modes.
-
-## Design
-
-### Why a new error class
-
-`FetchError` already covers transport failures, but it doesn't carry
-"this URL produced an HTML error page / 404 / non-PDF body" semantics.
-Splitting the type keeps existing `rescue Ucode::FetchError` callers
-from accidentally swallowing the typed signal that "we expected a PDF
-and didn't get one" — which is a different problem class from "the
-network was down."
-
-`CodeChartNotFoundError < Ucode::Error` (under `GlyphError`) reflects
-the REQ's framing: the chart for the requested block is not
-obtainable.
-
-### Why `validate:` is optional on `Http.get`
-
-`Http` is the single network boundary (per the comment at the top of
-`http.rb`). All callers funnel through it. Adding an optional
-keyword keeps the MECE pattern intact: non-PDF callers (UCD zip,
-Unihan zip, font zip) pass nothing; the single PDF caller passes
-`validate: :pdf`. No second network boundary is needed.
-
-### Why no separate "magic bytes" check class
-
-Magic-byte verification is 4 lines of code; extracting it into a
-class would be ceremony. Inline check after `write_body`, raising
-the typed error with the offending content-type or magic bytes in
-the context payload.
-
-## Acceptance
-
-- `Http.get(url, dest:, validate: :pdf)` raises
-  `CodeChartNotFoundError` (a) when the response Content-Type is not
-  `application/pdf`, (b) when the first 4 bytes are not `%PDF`.
-- `Fetch::CodeCharts.call(version, block_first_cps: [...])` raises
-  `CodeChartNotFoundError` when the unicode.org endpoint returns
-  4xx/5xx or non-PDF content.
-- Existing callers of `Http.get` that don't pass `validate:` are
-  unchanged.
-- Spec coverage: happy path, HTTP 404, wrong content-type, truncated
-  body missing the `%PDF` magic.
-
-## Out of scope
-
-- SHA-256 verification of the PDF — that's a downstream concern (the
-  Code Charts are not versioned by hash on unicode.org).
-- Resumable / partial downloads — the existing `Http` writes a
-  `.part` then renames; that's sufficient.

data/TODO.extract-code-chart/02-block-name-resolver.md

@@ -1,68 +0,0 @@
-# TODO 02 — Block name resolver
-
-## Status
-
-Pending. Depends on nothing.
-
-## Goal
-
-Add a class method `Ucode::Parsers::Blocks.find_by_name(name)` that
-resolves a Unicode block identifier (e.g. `"Sidetic"`,
-`"Egyptian_Hieroglyphs_Extended-B"`) to the `Ucode::Models::Block`
-instance in a given version's cached `Blocks.txt`.
-
-This is the CLI ergonomics glue: the REQ's `ucode code-chart extract
---block Sidetic` flow takes a human-readable name and needs to know
-the block's range to know which `U+XXXX` codepoints to iterate.
-
-## Files
-
-- `lib/ucode/parsers/blocks.rb` — add `Blocks.find_by_name(path, name)`.
-- `spec/ucode/parsers/blocks_spec.rb` — cover name lookup, missing-name,
-  case-sensitivity.
-
-## Design
-
-### Method shape
-
-```ruby
-# @param path [Pathname, String] path to a Blocks.txt
-# @param name [String] block identifier (matches Models::Block#id)
-# @return [Models::Block, nil] nil when no block matches
-def find_by_name(path, name)
-```
-
-Returns nil for "not found" — callers (CLI, Extractor) decide whether
-to raise. This matches `Models::Block` consumers that already expect
-nilable lookups.
-
-### Name matching rule
-
-`Blocks.txt` uses `name` with whitespace collapsed to underscores
-into `id`. `find_by_name` matches against `id` (the underscored
-form). The REQ's example `--block Sidetic` shows that the caller
-provides the underscored form already. This is consistent with the
-existing `Parsers::Blocks` build logic (`name.gsub(/\s+/, "_")`).
-
-### Why a separate method
-
-`each_record` streams every block — the caller doesn't want to walk
-~340 blocks for every name lookup. `find_by_name` short-circuits on
-first match.
-
-## Acceptance
-
-- `find_by_name(path, "Basic_Latin")` returns the Basic Latin block.
-- `find_by_name(path, "Nonexistent")` returns nil.
-- Streaming still works for callers that need every block.
-
-## Out of scope
-
-- Fuzzy matching — exact match only. Callers validate the user's
-  input against `Parsers::Blocks.each_record(path).map(&:id)` to
-  surface "did you mean …?" suggestions if we ever want that; for
-  now, a clean `UnknownBlockError` at the call site is enough.
-- Database-backed lookup — `Ucode::Database#block_ranges_by_name` is
-  a different concern (full UCD index). `find_by_name` operates on
-  the cached `Blocks.txt` directly because the CodeChart extractor
-  is meant to be runnable without a built database.