ucode 0.1.0

data/TODO.new/05-baseline-unicode17-coverage-audit.md

@@ -0,0 +1,144 @@
+# 05 — Unicode 17 baseline coverage audit
+
+## Goal
+
+Capture the actual per-tier coverage numbers for every Unicode 17
+addition (11 new blocks + additions to ~12 existing blocks) before
+locking the migration scope. The numbers ground every later decision:
+which blocks need pillar 2 work, which need real-font mining, which
+are already complete via tier 1.
+
+The publisher-confirmed table below is the starting point (carried from
+prior sessions). The deliverable is cmap-verified numbers, not
+publisher claims.
+
+## Why measure first
+
+Two open questions cannot be answered without running the audit:
+
+1. **Pillar coverage breakdown**: for each Unicode 17 block, how many
+   codepoints does Tier 1 cover? Pillar 1? Pillar 2? Pillar 3? The
+   migration's pillar-2 generalization work (already merged for Tai Yo)
+   needs to know which other blocks need it.
+2. **Real-font availability**: which Unicode 17 additions have a
+   public Tier 1 font vs which require pillar 2 (Sidetic, Beria Erfe)?
+   The canonical resolver config (TODO 20) needs this mapping.
+
+## Scope — Unicode 17 additions
+
+### 11 new blocks
+
+| Block | Range | Assigned | Tier 1 source (publisher-confirmed) | Confidence |
+|---|---|---:|---|---|
+| Sidetic | U+10940–1095F | 26 | Lentariso ≥1.029 + Noto Sans Sidetic | HIGH |
+| Sharada Supplement | U+11B60–11B7F | 8 | Noto Sans Sharada | HIGH |
+| Tolong Siki | U+11DB0–11DEF | 54 | Noto Sans Tolong Siki | HIGH |
+| Beria Erfe | U+16EA0–16EDF | 50 | Kedebideri 3.001 (SIL) | HIGH |
+| Tai Yo | U+1E6C0–1E6F3 | 55 | Noto Sans Tai Yo + pillar 2 (proven) | HIGH |
+| Symbols for Legacy Computing Supplement | U+1CC00–1CCFF | 9 | BabelStone Pseudographica | MEDIUM |
+| Supplemental Arrows-C | U+1CF00–1CFCF | 9 | Symbola | MEDIUM |
+| Alchemical Symbols (ext) | U+1F740–1F77F | 4 | Noto Sans Symbols + Symbola | HIGH |
+| Miscellaneous Symbols Supplement | U+1FA70–1FAFF | 34 | Noto Sans Symbols 2 | HIGH |
+| Musical Symbols Supplement (additions) | U+1D200–U+1D2FF | TBD | Noto Music | HIGH |
+| CJK Extension J | U+31350–U+323AF | 4298 | FSung + Noto Sans/Serif CJK | HIGH |
+
+### Additions to existing blocks
+
+- Tangut (+8), Tangut Supplement (+22), Tangut Components Supp. (+115) → Noto Sans Tangut + grave-app.
+- Adlam (+29) → Noto Sans Adlam.
+- Arabic Extended-B/C → Noto Naskh Arabic.
+- Telugu (+1), Kannada (+1) → existing Noto.
+- Combining Diacritical Marks Extended (+27) → likely Pillar 2 (font support spotty).
+- CJK Extension C/E additions → FSung.
+- Chess Symbols (+4), Transport (+1), Symbols & Pictographs Ext-A (+6) → Noto Symbols 2.
+- Egyptian Hieroglyphs (+28), Egyptian Hieroglyphs Format Controls (all), Egyptian Hieroglyphs Extended-A (+9), Egyptian Hieroglyphs Extended-B (~600 new) → UniHieroglyphica + Egyptian Text.
+
+## Procedure
+
+For each block:
+
+1. **Acquire Tier 1 font** (if publisher-confirmed):
+   - Lentariso: github.com/Bry10022/Lentariso (SFD source, OFL).
+   - Kedebideri 3.001: software.sil.org/kedebideri/.
+   - Noto family: notofonts.github.io or Google Fonts.
+   - FSung: `~/Downloads/全宋體/FSung-*.ttf` (already local).
+   - BabelStone Pseudographica, Symbola: BabelStone site.
+   - UniHieroglyphica: suignard.com (OFL); Egyptian Text: microsoft/font-tools.
+   - NotoSerifTaiYo: translationcommons.org.
+
+2. **Run Tier 1 cmap audit** via the existing `ucode font-coverage` CLI
+   (renamed to `ucode audit font` in TODO 16; both names valid until
+   then):
+   ```
+   ucode font-coverage <font-path> --label <font-label> \
+     --unicode-version 17.0
+   ```
+   Output: `output/font_coverage/<label>.json` (becomes
+   `output/font_audit/<label>/index.json` post-migration).
+
+3. **Capture pillar 1-2 stats** by running `ucode glyphs` against each
+   per-block PDF:
+   ```
+   ucode glyphs --block <block-first-cp> --version 17.0
+   ```
+   The `Catalog` reports `#codepoints`, `#size`, `#font_count` — log
+   these per block.
+
+4. **Cross-check**: Tier 1 cmap count + pillar 1-2 chart count should
+   equal `total_assigned` for that block. Discrepancies flag where
+   pillar 2 needs to generalize (e.g. fonts without ToUnicode) or
+   where Tier 1 fonts are missing codepoints the chart shows.
+
+5. **Sidetic + Beria Erfe specifically** — re-audit with the now-merged
+   `ContentStreamCorrelator` (commit `24e6bfd`). The Tai Yo proof
+   should generalize; verify the bucket sizes match (Sidetic/Beria
+   Erfe may have tighter grid than Tai Yo).
+
+## Deliverable
+
+A single markdown report at `docs/unicode17-coverage-baseline.md`
+containing:
+
+- One table per Unicode 17 block with: assigned count, Tier 1 covered,
+  Pillar 1 covered, Pillar 2 covered, Pillar 3 covered, gap, notes.
+- A summary table aggregating across all blocks.
+- Identified pillar 2 generalization needs (fonts the correlator must
+  handle).
+- Identified Tier 1 font gaps (codepoints the publisher-confirmed font
+  doesn't actually cover).
+
+This report becomes the input to TODO 20 (canonical resolver config:
+block → preferred Tier 1 font) and TODO 21 (Unicode 17 dataset build
+verification).
+
+## Acceptance
+
+- All 11 new blocks have cmap-verified Tier 1 numbers (not just
+  publisher claims).
+- All Unicode 17 additions to existing blocks have at least publisher
+  confirmation; cmap-verified where a font is locally available.
+- `docs/unicode17-coverage-baseline.md` exists with the above tables.
+- Sidetic and Beria Erfe show 26/26 and 50/50 respectively via the
+  merged pillar 2 path (validates the correlator generalization).
+- CJK Extension J: FSung covers the 4,298 assigned codepoints (or
+  documents which subset is missing).
+
+## Out of scope
+
+- Migrating any code (that's TODOs 06-19).
+- The canonical 4-tier resolver (TODO 20) — this audit informs it but
+  doesn't build it.
+- HTML browser (TODO 14-15) — the audit outputs JSON only.
+
+## References
+
+- Mode 1 vs Mode 2: `docs/architecture.md` §"Two output modes"
+- Tier 1 implementation: `lib/ucode/glyphs/real_fonts/`
+- Pillar 1 implementation: `lib/ucode/glyphs/embedded_fonts/catalog.rb`
+- Pillar 2 implementation:
+  `lib/ucode/glyphs/embedded_fonts/content_stream_correlator.rb`
+- Proven Tai Yo correlator: `/tmp/correlate_v4.rb` (carried forward as
+  the spec fixture basis)
+- PR #1 description: Tier-1 + Pillar-1 + Pillar-2 already validated
+  for Sidetic (26/26 via Lentariso), Beria Erfe (50/50 via
+  Kedebideri), Tai Yo (54/54 via pillar 2)

data/TODO.new/06-audit-namespace-skeleton.md

@@ -0,0 +1,105 @@
+# 06 — Audit namespace skeleton
+
+## Goal
+
+Stand up the `Ucode::Audit` namespace hub, the `Registry`, and the
+`Context`. No extractors, no models, no CLI yet — just the empty
+orchestrator scaffolding that subsequent TODOs (07-12) populate.
+
+This is the foundation; everything else in the migration slots into it.
+
+## Files to create
+
+- `lib/ucode/audit.rb` — namespace hub. Declares the autoloads (Ruby
+  autoload — see project memory `feedback_require_relative.md`).
+- `lib/ucode/audit/registry.rb` — ordered list of extractor classes,
+  iterated by `AuditCommand` for every face.
+- `lib/ucode/audit/context.rb` — value object carrying everything an
+  extractor needs to do its job (font handle, codepoint set, UCD
+  baseline, options).
+- `lib/ucode/audit/extractors.rb` — extractors namespace hub (empty;
+  filled by TODO 08 and 09).
+- `spec/ucode/audit/registry_spec.rb` — empty registry iterates zero
+  extractors without error.
+- `spec/ucode/audit/context_spec.rb` — context memoizes codepoints,
+  baseline, source_format.
+
+## Port from fontisan
+
+Direct port of:
+- `fontisan/lib/fontisan/audit.rb` (namespace hub pattern)
+- `fontisan/lib/fontisan/audit/registry.rb` (Registry module)
+- `fontisan/lib/fontisan/audit/context.rb` (Context class)
+- `fontisan/lib/fontisan/audit/extractors.rb` (extractors namespace)
+
+with namespace changes (`Fontisan::` → `Ucode::`).
+
+## Context adjustments vs fontisan
+
+The fontisan `Context` carries:
+
+- `font`, `font_path`, `font_index`, `num_fonts_in_source`, `options`
+- `codepoints` (memoized cmap keys)
+- `ucd` (memoized UCD database + version + warning)
+- `cldr` (memoized CLDR index — **drop**, see below)
+- `source_format`
+
+ucode's `Context` drops:
+
+- `cldr` and the entire `resolve_cldr` path. CLDR is out of scope
+  (decision in `TODO.new/00-README.md`).
+- `Ucd::VersionResolver` calls → replace with `Ucode::VersionResolver`
+  (ucode's own; see `lib/ucode/version_resolver.rb`).
+- `Ucd::Database.open` / `Ucd::CacheManager` calls → replace with
+  `Ucode::Database.open` and `Ucode::Cache` (ucode's own; see
+  `lib/ucode/database.rb` and `lib/ucode/cache.rb`).
+- `Ucd::Downloader` calls → replace with `Ucode::Fetch::UcdZip`.
+
+ucode's `Context` adds:
+
+- `baseline` — pre-resolved baseline struct (the assigned-codepoint
+  set for the target Unicode version). Extractors read from this
+  rather than re-resolving.
+- `renderer` — optional glyph renderer for `--with-glyphs` mode. Set
+  only when the option is on; nil otherwise. Avoids loading fontisan's
+  outline reader unless needed.
+
+## Registry adjustments
+
+The fontisan registry has two extractor lists:
+
+- `ORDERED_EXTRACTORS` — 12 extractors (full audit).
+- `BRIEF_EXTRACTORS` — 5 extractors (cheap pass).
+
+ucode's registry starts empty (no extractors ported yet). TODOs 08 and
+09 add them in order. The brief/full mode switch ports across unchanged.
+
+Drop the `Extractors::LanguageCoverage` entry from both lists — CLDR
+out of scope.
+
+## Acceptance
+
+- `Ucode::Audit` constant exists; `Ucode::Audit::Registry` and
+  `Ucode::Audit::Context` are referable.
+- `Ucode::Audit::Registry.each(mode: :full) { |e| }` iterates zero
+  extractors without error (empty list).
+- `Ucode::Audit::Registry.each(mode: :brief) { |e| }` same.
+- `Ucode::Audit::Context.new(font: ..., ...)` constructs and memoizes
+  `codepoints` on first call.
+- `Context#baseline` returns a real `Ucode::Database`-backed struct
+  (or raises a clear error if the version is uncached).
+- No `cldr` method exists on `Context` (verified by spec).
+- All specs use real model instances; no `double()`.
+- Rubocop clean.
+
+## References
+
+- Source: `fontisan/lib/fontisan/audit.rb`, `audit/registry.rb`,
+  `audit/context.rb`, `audit/extractors.rb`
+- ucode UCD infra: `lib/ucode/database.rb`, `lib/ucode/cache.rb`,
+  `lib/ucode/version_resolver.rb`, `lib/ucode/fetch/`
+- Project memory: `feedback_require_relative.md` (autoload rule),
+  `feedback_use_fontist_only.md`
+- Follow-ups: `TODO.new/07-audit-models-port.md`,
+  `TODO.new/08-extractors-cheap-port.md`,
+  `TODO.new/09-extractors-expensive-port.md`

data/TODO.new/07-audit-models-port.md

@@ -0,0 +1,132 @@
+# 07 — Models::Audit port
+
+## Goal
+
+Port the `Fontisan::Models::Audit::*` lutaml-model classes (15 files)
+to `Ucode::Models::Audit::*` with the schema adjustments from
+`TODO.new/02-audit-schema-design.md`. Pure data classes — no font
+parsing logic.
+
+## Files to create
+
+One class per file, plus the namespace hub:
+
+```
+lib/ucode/models/audit.rb
+lib/ucode/models/audit/audit_report.rb
+lib/ucode/models/audit/baseline.rb            # NEW
+lib/ucode/models/audit/block_summary.rb       # was AuditBlock
+lib/ucode/models/audit/script_summary.rb      # NEW (was string list)
+lib/ucode/models/audit/plane_summary.rb       # NEW
+lib/ucode/models/audit/discrepancy.rb         # NEW
+lib/ucode/models/audit/codepoint_detail.rb    # NEW
+lib/ucode/models/audit/codepoint_range.rb
+lib/ucode/models/audit/codepoint_set_diff.rb
+lib/ucode/models/audit/audit_axis.rb
+lib/ucode/models/audit/named_instance.rb
+lib/ucode/models/audit/licensing.rb
+lib/ucode/models/audit/metrics.rb
+lib/ucode/models/audit/hinting.rb
+lib/ucode/models/audit/color_capabilities.rb
+lib/ucode/models/audit/variation_detail.rb
+lib/ucode/models/audit/opentype_layout.rb
+lib/ucode/models/audit/fs_selection_flags.rb
+lib/ucode/models/audit/gasp_range.rb
+lib/ucode/models/audit/embedding_type.rb
+lib/ucode/models/audit/script_coverage_row.rb
+lib/ucode/models/audit/script_features.rb
+lib/ucode/models/audit/field_change.rb
+lib/ucode/models/audit/duplicate_group.rb
+lib/ucode/models/audit/library_summary.rb
+lib/ucode/models/audit/audit_diff.rb
+```
+
+Specs under `spec/ucode/models/audit/` — one spec per model, all
+testing `to_hash` / `from_hash` round-trip.
+
+## Source material
+
+Port these unchanged (just namespace swap):
+
+- `fontisan/lib/fontisan/models/audit/codepoint_range.rb`
+- `fontisan/lib/fontisan/models/audit/codepoint_set_diff.rb`
+- `fontisan/lib/fontisan/models/audit/audit_axis.rb`
+- `fontisan/lib/fontisan/models/audit/named_instance.rb`
+- `fontisan/lib/fontisan/models/audit/licensing.rb`
+- `fontisan/lib/fontisan/models/audit/metrics.rb`
+- `fontisan/lib/fontisan/models/audit/hinting.rb`
+- `fontisan/lib/fontisan/models/audit/color_capabilities.rb`
+- `fontisan/lib/fontisan/models/audit/variation_detail.rb`
+- `fontisan/lib/fontisan/models/audit/opentype_layout.rb`
+- `fontisan/lib/fontisan/models/audit/fs_selection_flags.rb`
+- `fontisan/lib/fontisan/models/audit/gasp_range.rb`
+- `fontisan/lib/fontisan/models/audit/embedding_type.rb`
+- `fontisan/lib/fontisan/models/audit/script_coverage_row.rb`
+- `fontisan/lib/fontisan/models/audit/script_features.rb`
+- `fontisan/lib/fontisan/models/audit/field_change.rb`
+- `fontisan/lib/fontisan/models/audit/duplicate_group.rb`
+- `fontisan/lib/fontisan/models/audit/library_summary.rb`
+- `fontisan/lib/fontisan/models/audit/audit_diff.rb`
+
+## Schema changes vs fontisan
+
+Per `TODO.new/02-audit-schema-design.md`:
+
+- `AuditReport`:
+  - `fontisan_version` → `ucode_version`.
+  - Drop `cldr_version` and `language_coverage`.
+  - Drop `ucd_version` string → replace with `baseline` (Baseline model).
+  - Drop `unicode_scripts: String[]` → replace with `scripts: ScriptSummary[]`.
+  - Add `plane_summaries: PlaneSummary[]`.
+  - Add `discrepancies: Discrepancy[]`.
+- `AuditBlock` → renamed `BlockSummary`. Add `missing_codepoints`,
+  `covered_codepoints` (verbose), `missing_count`, `coverage_percent`,
+  `status`, `plane`. Drop `complete` boolean (replaced by status).
+- `AuditReport` uses `key_value do map "name", to: :name end` form —
+  same as fontisan. No `mapping do` (lutaml-model API; see project
+  memory `lutaml_model_polymorphism_api.md`).
+
+## lutaml-model conventions
+
+- Parent class inherits via `< Lutaml::Model::Serializable` — never
+  `include Lutaml::Model::Serializable`. See project memory
+  `feedback_lutaml_model_inheritance.md`.
+- Boolean attributes use `Lutaml::Model::Type::Boolean` (not Ruby
+  `:boolean` — same convention as fontisan).
+- Key-value serialization uses `key_value do ... end` for JSON/YAML.
+  No custom `to_h`/`from_h`/`to_json`/`from_json`.
+- Nested models reference other `Ucode::Models::Audit::*` classes
+  directly (no string namespacing).
+
+## Spec requirements
+
+- One spec per model file under `spec/ucode/models/audit/`.
+- Each spec:
+  - Constructs an instance with realistic attribute values (no
+    `nil` where the schema says non-nil).
+  - Round-trips through `to_hash` → `from_hash` → field equality.
+  - For collections, tests both empty and populated.
+  - No `double()` — use real instances or `Struct.new`.
+- `AuditReport` spec additionally verifies every documented field
+  from `TODO.new/04-fontist-org-contract.md` is present.
+
+## Acceptance
+
+- All 27 model files exist and load via autoload chain declared in
+  `lib/ucode/models/audit.rb`.
+- All 27 spec files pass with no `double()` usage.
+- `Ucode::Models::Audit::AuditReport.new(...)` accepts all fields
+  from `02-audit-schema-design.md`.
+- `AuditReport#to_hash` produces a hash matching the
+  `04-fontist-org-contract.md` JSON shape (where overlapping).
+- Rubocop clean.
+
+## References
+
+- Schema source: `TODO.new/02-audit-schema-design.md`
+- Contract: `TODO.new/04-fontist-org-contract.md`
+- Source files: `fontisan/lib/fontisan/models/audit/`
+- lutaml-model conventions: project memory
+  `lutaml_model_polymorphism_api.md`,
+  `feedback_lutaml_model_inheritance.md`
+- Follow-ups: `TODO.new/08-extractors-cheap-port.md` (uses these models)

data/TODO.new/08-extractors-cheap-port.md

@@ -0,0 +1,113 @@
+# 08 — Cheap extractors port
+
+## Goal
+
+Port the 5 cheap extractors from fontisan to ucode. These are the
+"brief mode" extractors — fast, name-table-only path that doesn't need
+UCD or expensive table loads. Plus the Coverage extractor (cheap, but
+excluded from brief mode in fontisan because it needs cmap; in ucode we
+keep it cheap because cmap is the Tier 1 foundation).
+
+After this TODO, `Ucode::Audit::Registry.each(mode: :brief)` produces
+a minimal-but-real audit report (identity + style + coverage totals,
+no aggregations).
+
+## Files to create
+
+```
+lib/ucode/audit/extractors/
+├── base.rb               # port from fontisan
+├── provenance.rb         # port from fontisan
+├── identity.rb           # port from fontisan
+├── style.rb              # port from fontisan (the older StyleExtractor, not the registry-listed Extractors::Style)
+├── licensing.rb          # port from fontisan
+└── coverage.rb           # port from fontisan
+```
+
+Plus update `lib/ucode/audit/registry.rb` to populate `BRIEF_EXTRACTORS`
+and add these to `ORDERED_EXTRACTORS` (the latter stays incomplete
+until TODO 09).
+
+Specs: `spec/ucode/audit/extractors/<name>_spec.rb` for each.
+
+## Port from fontisan
+
+- `fontisan/lib/fontisan/audit/extractors/base.rb`
+- `fontisan/lib/fontisan/audit/extractors/provenance.rb`
+- `fontisan/lib/fontisan/audit/extractors/identity.rb`
+- `fontisan/lib/fontisan/audit/extractors/style.rb`
+- `fontisan/lib/fontisan/audit/extractors/licensing.rb`
+- `fontisan/lib/fontisan/audit/extractors/coverage.rb`
+
+## Adjustments vs fontisan
+
+Each extractor returns a hash of `AuditReport` fields. The fontisan
+versions read font tables via `Context#font.table(...)` — this stays
+the same; ucode's `Context` still wraps a fontisan font handle.
+
+### Provenance
+
+- `fontisan_version` → `ucode_version` (read from `Ucode::VERSION`).
+- Otherwise unchanged.
+
+### Identity
+
+- Unchanged. Reads `name` table via fontisan's public API.
+
+### Style
+
+- The standalone `StyleExtractor` class
+  (`fontisan/lib/fontisan/audit/style_extractor.rb`) is older
+  fontisan code. The registry-listed `Extractors::Style` is the newer
+  thin version. Port the registry-listed version; do not port the
+  standalone `StyleExtractor` class.
+- Reads OS/2 + head via fontisan's public API. Same shape.
+
+### Licensing
+
+- Unchanged.
+
+### Coverage
+
+- Output `codepoints` field uses `"U+XXXX"` string form (per
+  `02-audit-schema-design.md`).
+- Output `codepoint_ranges` uses `CodepointRange` model — port the
+  `CodepointRangeCoalescer` helper too (`fontisan/lib/fontisan/audit/codepoint_range_coalescer.rb`).
+- Does **not** emit aggregations (blocks/scripts) — that's the
+  Aggregations extractor in TODO 10. Coverage only emits the raw
+  codepoint set.
+
+## Boundary with fontisan
+
+These extractors call **only** fontisan's public font-reading API:
+
+- `fontisan_font.table("name")`
+- `fontisan_font.table("OS/2")`
+- `fontisan_font.table("head")`
+- `fontisan_font.table("cmap")`
+- `fontisan_font.sfnt_table("cmap").parse.unicode_mappings`
+
+No reaching into `Fontisan::Constants`, no `send`, no
+`instance_variable_get`. If a field needs a table fontisan doesn't
+expose, file a fontisan-side issue; do not work around it in ucode.
+
+## Acceptance
+
+- All 6 extractor files exist; each has a passing spec with real
+  fixture fonts (use `spec/fixtures/fonts/`).
+- `Ucode::Audit::Registry.each(mode: :brief)` iterates these 5:
+  `Provenance, Identity, Style, Licensing, Coverage`.
+- A "brief audit" of a fixture font produces an `AuditReport` with
+  provenance, identity, style, licensing, and coverage fields
+  populated. Aggregation fields (`baseline`, `blocks`, `scripts`,
+  `plane_summaries`) are nil.
+- No `double()` in any spec.
+- Rubocop clean.
+
+## References
+
+- Models: `TODO.new/07-audit-models-port.md`
+- Source: `fontisan/lib/fontisan/audit/extractors/{base,provenance,identity,style,licensing,coverage}.rb`
+- Coalescer helper: `fontisan/lib/fontisan/audit/codepoint_range_coalescer.rb`
+- fontisan API boundary: `docs/architecture.md` §"Dependency arrows"
+- Follow-up: `TODO.new/09-extractors-expensive-port.md`

data/TODO.new/09-extractors-expensive-port.md

@@ -0,0 +1,99 @@
+# 09 — Expensive extractors port
+
+## Goal
+
+Port the 5 expensive extractors from fontisan. These read multiple
+font tables and reconstruct sub-structures (metrics, hinting program,
+color font capabilities, variable-font axes, OpenType layout rules).
+They are excluded from brief mode.
+
+After this TODO, `Ucode::Audit::Registry.each(mode: :full)` produces
+a complete (but still no-UCD-aggregations) audit report.
+
+## Files to create
+
+```
+lib/ucode/audit/extractors/
+├── metrics.rb                # port from fontisan
+├── hinting.rb                # port from fontisan
+├── color_capabilities.rb     # port from fontisan
+├── variation_detail.rb       # port from fontisan
+└── opentype_layout.rb        # port from fontisan
+```
+
+Plus update `lib/ucode/audit/registry.rb` `ORDERED_EXTRACTORS` to
+include these in their fontisan positions.
+
+Specs: `spec/ucode/audit/extractors/<name>_spec.rb` for each.
+
+## Port from fontisan
+
+- `fontisan/lib/fontisan/audit/extractors/metrics.rb`
+- `fontisan/lib/fontisan/audit/extractors/hinting.rb`
+- `fontisan/lib/fontisan/audit/extractors/color_capabilities.rb`
+- `fontisan/lib/fontisan/audit/extractors/variation_detail.rb`
+- `fontisan/lib/fontisan/audit/extractors/opentype_layout.rb`
+
+## Adjustments vs fontisan
+
+Each extractor returns a hash with one or two keys mapping to a
+model from `TODO.new/07-audit-models-port.md`. The fontisan versions
+already return hashes in this shape — port unchanged.
+
+### Metrics
+
+- Reads `head`, `hhea`, `OS/2`, `post` via fontisan's public API.
+- Returns `{ metrics: Ucode::Models::Audit::Metrics.new(...) }`.
+- Returns `{}` (empty hash) for Type 1 fonts.
+
+### Hinting
+
+- Reads `fpgm`, `prep`, `cvt`, `gasp`, plus CFF charstrings for CFF fonts.
+- Returns `{ hinting: ... }` or `{}`.
+
+### ColorCapabilities
+
+- Reads `COLR`, `CPAL`, `SVG`, `CBDT`, `CBLC`, `sbix`.
+- Returns `{ color_capabilities: ... }` or `{}`.
+
+### VariationDetail
+
+- Reads `fvar`, `gvar`, `STAT`, `avar`, `HVAR`, `VVAR`, etc.
+- Returns `{ variation: ... }` or `{}` for non-variable faces.
+
+### OpenTypeLayout
+
+- Reads `GSUB`, `GPOS`.
+- Returns `{ opentype_layout: ... }` or `{}`.
+
+## Boundary with fontisan
+
+Same boundary as TODO 08: only public font-reading API. If a table
+isn't exposed publicly, file a fontisan-side issue.
+
+For complex table walks (e.g. GSUB script list iteration, COLR layer
+tree), prefer asking fontisan to expose a higher-level reader (e.g.
+`fontisan_font.gsub_scripts`) rather than parsing the raw table bytes
+in ucode. ucode is the audit owner, not the font parser.
+
+## Acceptance
+
+- All 5 extractor files exist; each has a passing spec with real
+  fixture fonts covering: static TrueType, CFF/OTF, variable font,
+  color font (COLR or CBDT), Type 1 (returns empty).
+- `Ucode::Audit::Registry.each(mode: :full)` iterates all 10
+  extractors ported so far (5 cheap from TODO 08 + 5 expensive here).
+  Still missing: Aggregations (TODO 10).
+- A full audit of a fixture variable font populates `variation.axes`,
+  `variation.named_instances`, and `opentype_layout` correctly.
+- A full audit of a fixture COLR font populates
+  `color_capabilities.colr_layers`, `color_capabilities.cpal_palettes`.
+- No `double()` in any spec.
+- Rubocop clean.
+
+## References
+
+- Models: `TODO.new/07-audit-models-port.md`
+- Source: `fontisan/lib/fontisan/audit/extractors/{metrics,hinting,color_capabilities,variation_detail,opentype_layout}.rb`
+- Fixtures: `spec/fixtures/fonts/` (port any missing from fontisan's spec/fixtures/)
+- Follow-up: `TODO.new/10-aggregations-ucd-rewrite.md` (last extractor)