ucode 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9d5a29a388017c0338a8d2723f97dfd4ac8985324b6ab7fc9b8921a5f4b0b82
-  data.tar.gz: f6988cf20f74efc1b94ebfedbd7b9507680de1c0880ffd28ac9a4a00851195a8
+  metadata.gz: e2e60f073662cc78885f8ee6a0333a2307a8b894ddb9789b1e206f6ae63d25e3
+  data.tar.gz: 50b3984de26589d0aab193250e9c8dd3f56fd0d10a4a77a21ffdcb236c38c737
 SHA512:
-  metadata.gz: 890fec1b40ed6016b269982d32d28b15eb2683dfa7d4e9fc32e5a6633c46fb6f8a94b0d004d1bbd4381fb5bbe629faf00984729036005c12e1558c65d70afe4f
-  data.tar.gz: 792b58d5eb3434b05008740457b1c432f5810bd45b2d0d80936bd0c539445098b835c1d242093487cf0a4a4754efba2fe725c500b2d3f1a23f4906b4a17809dc
+  metadata.gz: 88d9ef3df0f99af9b3897cd429666092d48a373d9c60d3c83a6e06a59404e0523c736a8d971fbb6d6d29c9b4b80d9610cad54a64cda439326e19a80670d67ba9
+  data.tar.gz: 8146f6984defddb5b45204fe7a8852cd3051bf1474584eddc7489e5ec9fd4900d48452ac5462a1c6c2ac9b8213823ace68cebe6c5b5176dd0c25c922f8f1d4ba

data/Gemfile

@@ -4,8 +4,13 @@ source "https://rubygems.org"
 
 gemspec
 
+# Rake must be in the default group (not :development) because the
+# GHA release workflow runs `bundle exec rake release` to publish the
+# gem. The release runner installs with `--without development`, so
+# gems in the :development group are excluded.
+gem "rake"
+
 group :development do
-  gem "rake"
   gem "rspec"
   gem "rubocop"
   gem "rubocop-performance"
@@ -19,4 +24,7 @@ end
 # local sibling checkout, set FONTISAN_PATH before running bundle.
 #   FONTISAN_PATH=../fontisan bundle install
 gem "fontisan", path: ENV["FONTISAN_PATH"] if ENV["FONTISAN_PATH"]
-gem "fontisan", "~> 0.2" unless ENV["FONTISAN_PATH"]
+# Pin fontisan to 0.2.22 — 0.2.23+ removed
+# `Fontisan::Commands::AuditCommand` and 0.4.x removed the Audit
+# subsystem entirely. See ucode.gemspec for the rationale.
+gem "fontisan", "= 0.2.22" unless ENV["FONTISAN_PATH"]

data/README.md

@@ -2,14 +2,16 @@
 
 `ucode` is a Ruby toolkit for the Unicode Character Database (UCD). It turns the
 official UCD text files into a structured, browsable dataset: one JSON document
-per assigned codepoint, plus a Vitepress site for navigation.
+per assigned codepoint, plus a Vitepress site for navigation. It also extracts
+per-codepoint SVG glyphs from the Unicode Code Charts PDFs and audits font
+coverage against the Unicode baseline.
 
-> **Status (v0.1).** The JSON dataset, lookup index, and Vitepress site are
-> production-ready. **SVG glyph extraction from the Code Charts PDFs is
-> experimental and deferred to v0.2** — see
-> [Glyph extraction (experimental)](#glyph-extraction-experimental) below.
+> **Status (v0.2.1).** The JSON dataset, lookup index, Vitepress site, and
+> 4-tier glyph extraction pipeline are production-ready. The `ucode code-chart`
+> subcommand extracts standalone SVGs + provenance sidecars from per-block
+> Code Charts PDFs. Font coverage auditing (`ucode audit`) is production-ready.
 
-## What you get (v0.1)
+## What you get (v0.2)
 
 - **Per-codepoint JSON** at `output/blocks/<BLOCK>/<U+XXXX>/index.json` with
   full UCD properties, the human-curated relationships from `NamesList.txt`
@@ -21,6 +23,14 @@ per assigned codepoint, plus a Vitepress site for navigation.
   relationships, named sequences, manifest.
 - **SQLite lookup index** for fast codepoint → block/script/char queries.
 - **Vitepress site** at `site/` for browsing Plane → Block → Character.
+- **4-tier glyph extraction** — per-codepoint `glyph.svg` sourced from real
+  fonts (Tier 1), PDF-embedded fonts (Pillars 1+2), or Last Resort UFO
+  (Pillar 3).
+- **Per-block Code Chart extraction** — `ucode code-chart extract` produces
+  standalone SVG + provenance JSON for every codepoint in a block.
+- **Font coverage audit** — `ucode audit` compares a font's cmap against the
+  Unicode baseline and reports per-block coverage, missing codepoints, and
+  optional HTML browsers.
 
 ## Install
 
@@ -31,7 +41,7 @@ gem install ucode
 Or in a Gemfile:
 
 ```ruby
-gem "ucode", "~> 0.1"
+gem "ucode", "~> 0.2"
 ```
 
 ## Quick start
@@ -107,7 +117,39 @@ Then:
 cd site && npm install && npm run dev
 ```
 
-## Glyph extraction (experimental in v0.1; concrete plan for v0.2)
+## Code Chart extraction
+
+Extract per-codepoint SVG glyphs from a Unicode Code Charts PDF, with
+provenance sidecar JSON:
+
+```sh
+# Download the Code Charts PDF for a block
+ucode code-chart fetch --block Sidetic
+
+# Extract every codepoint as SVG + provenance JSON
+ucode code-chart extract --block Sidetic --to /tmp/sidetic/
+
+# List cached Code Charts PDFs
+ucode code-chart list
+```
+
+Output layout:
+
+```
+/tmp/sidetic/Sidetic/
+  U+10920.svg      # vector glyph outline
+  U+10920.json     # provenance: source PDF, sha256, version, timestamp
+  U+10921.svg
+  U+10921.json
+  ...
+```
+
+The extractor uses the existing 4-tier glyph sourcing pipeline (Tier 1 →
+Pillar 1 → Pillar 2 → Pillar 3). No new extraction logic — the
+`ucode code-chart` subcommand is a thin CLI wrapper over `Ucode::CodeChart::Writer`,
+which orchestrates `Ucode::Glyphs::Resolver` for each codepoint.
+
+## Glyph extraction (4-tier pipeline)
 
 The `ucode glyphs` command and the `--include-glyphs` flag on `ucode build`
 are **opt-in and experimental in v0.1**. They emit per-codepoint `glyph.svg`
@@ -436,29 +478,33 @@ from the dataset.
 
 ## Architecture
 
-Five concerns, each isolated:
+Seven concerns, each isolated:
 
 1. **`Ucode::Models`** — `lutaml-model` classes for every UCD aggregate.
 2. **`Ucode::Parsers`** — one streaming parser per UCD text file.
 3. **`Ucode::Coordinator`** — single-pass enrichment that merges indices
    into each `CodePoint` as it streams.
-4. **`Ucode::Repo`** — atomic, idempotent writers for the output tree.
-5. **`Ucode::Glyphs`** — vector glyph extraction from Code Charts PDFs
-   (experimental in v0.1).
-6. **`Ucode::Site`** — Vitepress scaffold + config/page generator.
+4. **`Ucode::Repo`** — atomic, idempotent writers for the output tree
+   (per-concern writers under `Repo::Writers::*`).
+5. **`Ucode::Glyphs`** — 4-tier vector glyph extraction from Code Charts PDFs
+   (RealFonts, EmbeddedFonts, LastResort + Resolver).
+6. **`Ucode::CodeChart`** — per-block SVG extraction + provenance sidecar
+   for the "Code Chart donor" use case.
+7. **`Ucode::Site`** — Vitepress scaffold + config/page generator.
 
 CLI is thin Thor dispatch over `Ucode::Commands::*`. Each command class
-is a pure, in-process testable unit.
+is a pure, in-process testable unit. Version resolution happens once
+per CLI invocation and threads through to all sub-commands.
 
-See `CLAUDE.md` for the full architecture notes. See
-`docs/FONTISAN_MIGRATION.md` for the fontisan integration plan.
+See `docs/architecture.md` for the canonical architecture reference and
+`docs/adr/` for Architecture Decision Records.
 
 ## Authoritative source
 
-ucode parses the **UCD text files** (per UAX #44). The
-`ucd.all.flat.xml` shipped with the repo is reference-only — it omits
-the human-curated relationship data in `NamesList.txt` and has partial
-Unihan coverage. We never parse it.
+ucode parses the **UCD text files** (`UnicodeData.txt`, `NamesList.txt`,
+`Blocks.txt`, etc.) per UAX #44. Never uses the flat XML dump — the text
+files carry the human-curated relationship data that makes this project
+valuable.
 
 ## License
 

data/Rakefile

@@ -4,15 +4,26 @@ require "rubygems"
 require "rake"
 require "bundler/gem_tasks"
 
-require "rspec/core/rake_task"
-RSpec::Core::RakeTask.new(:spec)
+begin
+  require "rspec/core/rake_task"
+  RSpec::Core::RakeTask.new(:spec)
+rescue LoadError
+  # rspec is in the :development group; not available in the
+  # release runner (`bundle install --without development`).
+end
 
-require "rubocop/rake_task"
-RuboCop::RakeTask.new
+begin
+  require "rubocop/rake_task"
+  RuboCop::RakeTask.new
+rescue LoadError
+end
 
-require "yard"
-YARD::Rake::YardocTask.new do |t|
-  t.options = ["--output-dir", "docs/api"]
+begin
+  require "yard"
+  YARD::Rake::YardocTask.new do |t|
+    t.options = ["--output-dir", "docs/api"]
+  end
+rescue LoadError
 end
 
-task default: %i[spec rubocop]
+task default: %i[spec rubocop]

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

@@ -0,0 +1,80 @@
+# 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

@@ -0,0 +1,68 @@
+# 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.

data/TODO.extract-code-chart/03-codechart-namespace.md

@@ -0,0 +1,82 @@
+# TODO 03 — CodeChart namespace
+
+## Status
+
+Pending. Depends on TODO 02 (block name resolver) so the Extractor
+can consume it; depends on TODO 01 (error class) so the namespace
+can declare typed errors.
+
+## Goal
+
+Establish the `Ucode::CodeChart` namespace as the home for the
+Code Charts per-codepoint extraction feature. The REQ calls this
+namespace `Ucode::CodeChart::*`; we follow the REQ.
+
+This is the autoload-hub file plus the autoload declaration in
+`lib/ucode.rb`.
+
+## Files
+
+- `lib/ucode/code_chart.rb` — new autoload hub (defines
+  `Ucode::CodeChart` and declares child autoloads).
+- `lib/ucode.rb` — add `autoload :CodeChart, "ucode/code_chart"` in
+  the namespace-hubs block.
+
+## Design
+
+### Autoload hub shape
+
+```ruby
+# lib/ucode/code_chart.rb
+module Ucode
+  module CodeChart
+    autoload :Extractor, "ucode/code_chart/extractor"
+    autoload :Provenance, "ucode/code_chart/provenance"
+    autoload :Sidecar, "ucode/code_chart/sidecar"
+    autoload :Writer, "ucode/code_chart/writer"
+  end
+end
+```
+
+Per the global rule (`~/.claude/CLAUDE.md`): declare autoloads in the
+immediate parent namespace's file. `Ucode::CodeChart` is the immediate
+parent of `Extractor`, `Provenance`, `Sidecar`, `Writer`; this file
+is the immediate parent's file.
+
+`Ucode` is the immediate parent of `CodeChart`; the autoload
+declaration `autoload :CodeChart, "ucode/code_chart"` goes in
+`lib/ucode.rb`.
+
+### Why a new namespace (not under `Ucode::Glyphs`)
+
+`Ucode::Glyphs::*` is the existing 4-tier sourcing pipeline
+(`EmbeddedFonts`, `RealFonts`, `LastResort`, `Writer`). The REQ's
+`CodeChart::*` is a feature-facing namespace that orchestrates the
+glyphs pipeline for one specific use case (extracting from a per-block
+PDF for the essenfont donor pipeline). Keeping the feature-facing
+namespace separate from the implementation namespace:
+
+- Lets callers say `Ucode::CodeChart.extract(block: "Sidetic")`
+  without first knowing about `Glyphs::EmbeddedFonts`.
+- Makes it easy to swap the implementation later (different
+  resolution strategy, alternative PDF parser) without breaking the
+  public API.
+- Keeps `Glyphs::` focused on tier mechanics, free of feature
+  ergonomics.
+
+The REQ's namespace name is what we use.
+
+## Acceptance
+
+- `lib/ucode/code_chart.rb` exists with the autoload declarations.
+- `lib/ucode.rb` has the new `autoload :CodeChart, "ucode/code_chart"`
+  in the namespace-hubs block.
+- `Ucode::CodeChart` resolves to a module without loading any of its
+  children.
+
+## Out of scope
+
+- `Ucode::CodeChart::Command` (Thin wrapper). The CLI lives in
+  `lib/ucode/cli.rb` per the existing pattern; no separate
+  `Commands::CodeChartCommand` is introduced (single source of
+  truth for CLI dispatch).

data/TODO.extract-code-chart/04-codechart-extractor.md

@@ -0,0 +1,154 @@
+# TODO 04 — CodeChart::Extractor
+
+## Status
+
+Pending. Depends on TODO 01 (error class), TODO 02 (block name
+resolver), TODO 03 (namespace).
+
+## Goal
+
+`Ucode::CodeChart::Extractor` is the single entry point for
+"extract every assigned codepoint in block X as a standalone SVG."
+
+It orchestrates the existing 4-tier resolver (one source of truth for
+"how do I get the SVG for a given codepoint") and returns a list of
+extraction results — one per codepoint — that the downstream Writer
+serializes to disk.
+
+This is *not* a new extraction pipeline; it is the existing
+`Ucode::Glyphs::Resolver` with per-block inputs pre-configured.
+
+## Files
+
+- `lib/ucode/code_chart/extractor.rb` — `Ucode::CodeChart::Extractor`
+  class.
+- `spec/ucode/code_chart/extractor_spec.rb` — model/value-object
+  specs (constructor invariants, Resolver wiring) plus an integration
+  test against the fixture `spec/fixtures/pdfs/basic_latin.pdf`.
+
+## Design
+
+### Class shape
+
+```ruby
+class Ucode::CodeChart::Extractor
+  Result = Struct.new(:codepoint, :svg, :tier, :provenance, :base_font,
+                      :gid, keyword_init: true)
+
+  def initialize(block:, blocks_txt:, pdf_fetcher: nil,
+                 font_cache_dir: nil, last_resort_root: nil)
+    @block = block                      # Models::Block
+    @blocks_txt = blocks_txt            # Pathname
+    @pdf_fetcher = pdf_fetcher          # optional injectable
+    @font_cache_dir = font_cache_dir    # default: data/pdf-fonts/
+    @last_resort_root = last_resort_root
+  end
+
+  # Walks every assigned codepoint in @block and returns one Result
+  # per codepoint. Codepoints with no glyph from any tier are
+  # silently skipped (no Result yielded) — the REQ's "skip
+  # unassigned codepoints with a warning" is satisfied by the
+  # Resolver returning nil for them.
+  #
+  # @return [Array<Result>]
+  def extract
+  end
+end
+```
+
+### Wiring (single source of truth)
+
+The Extractor does NOT implement tier selection. It builds a
+`Ucode::Glyphs::Resolver` and calls `resolver.resolve(codepoint)` for
+each cp. The Resolver's tier order is preserved (Pillar 1 → 2 → 3
+for this feature; no Tier 1 because we're starting from the Code
+Charts PDF, not a real-font source).
+
+```ruby
+def build_resolver
+  pdf = fetch_pdf!
+  embedded_source = Glyphs::EmbeddedFonts::Source.new(
+    pdf: pdf, cache_dir: @font_cache_dir,
+  )
+  catalog = Glyphs::EmbeddedFonts::Catalog.new(embedded_source)
+  pillar1 = Glyphs::Sources::Pillar1EmbeddedTounicode.new(
+    renderer: Glyphs::EmbeddedFonts::Renderer.new(catalog),
+  )
+  pillar3 = Glyphs::Sources::Pillar3LastResort.new(
+    renderer: Glyphs::LastResort::Renderer.new(
+      Glyphs::LastResort::Source.new(root: @last_resort_root),
+    ),
+  )
+  Glyphs::Resolver.new(
+    sources: [pillar1, pillar3],
+    order: %i[pillar1 pillar3],
+  )
+end
+```
+
+The tier ordering is documented inline: we skip Pillar 2 because for
+the CodeChart use case the catalog's ToUnicode is the dominant path
+and Pillar 2 (positional correlation) is reserved for fonts where
+Pillar 1 fails. If a future use case needs Pillar 2, add it without
+changing this constructor — that's the OCP payoff of consuming the
+Resolver.
+
+### Why no Tier 1
+
+Tier 1 (real-font cmap) needs a configured `SourceConfig` mapping
+block → font. The CodeChart use case is for blocks where no real
+font exists (Sidetic, Egyptian Ext-B). Tier 1 wouldn't contribute
+anything. The Extractor accepts a Tier 1 source in the future by
+having callers pass a fully-built Resolver instead of constructing
+one internally.
+
+### Why PDF fetch is delegated to `PdfFetcher`
+
+`Ucode::Glyphs::PdfFetcher` is the existing seam for resolving a
+block to its PDF on disk (per-block cache + monolith fallback). It
+already handles `force:` and the cache directory. The Extractor
+constructs a `PdfFetcher` per call (cheap — it's just a path
+resolver) and reuses it across codepoints.
+
+### Per-codepoint loop
+
+```ruby
+def extract
+  resolver = build_resolver
+  @block.codepoint_ids.flat_map do |cp_id|
+    cp = Integer(cp_id.delete_prefix("U+"), 16)
+    resolver_result = resolver.resolve(cp)
+    next nil unless resolver_result&.svg
+
+    Result.new(
+      codepoint: cp,
+      svg: resolver_result.svg,
+      tier: resolver_result.tier,
+      provenance: resolver_result.provenance,
+    )
+  end.compact
+end
+```
+
+The Resolver returns a `Sources::Result` (tier + codepoint + svg +
+provenance). We adapt that to the Extractor's `Result` (with
+codepoint + svg + tier + provenance), stripping the resolver-specific
+shape at the boundary.
+
+## Acceptance
+
+- `Extractor.new(block: ..., blocks_txt: ...)` constructs without
+  raising when the block and PDF are present.
+- `#extract` returns one Result per codepoint that any tier
+  produced a glyph for.
+- `#extract` skips codepoints no tier could produce (returns no
+  Result, not a Result-with-nil).
+- Integration test: against the fixture PDF, at least one codepoint's
+  Result has tier `:pillar1` and provenance `"pillar-1:embedded-tounicode"`.
+
+## Out of scope
+
+- Writing files — that's `CodeChart::Writer` (TODO 06).
+- Provenance JSON — that's `CodeChart::Sidecar` (TODO 05).
+- Tier 1 (real-font) source injection — not needed for the REQ's
+  blocks. Future extension point if a real-font fallback is desired.