ucode 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9d5a29a388017c0338a8d2723f97dfd4ac8985324b6ab7fc9b8921a5f4b0b82
-  data.tar.gz: f6988cf20f74efc1b94ebfedbd7b9507680de1c0880ffd28ac9a4a00851195a8
+  metadata.gz: 9c2f1e8cbf000eca25d51f0df33bb07c560396b5bcbb43e1347e8be31609c6e9
+  data.tar.gz: 654c8d3d9d63551faf5945c7ae4e42f51caffa81716e5a02b93d551de18aeed7
 SHA512:
-  metadata.gz: 890fec1b40ed6016b269982d32d28b15eb2683dfa7d4e9fc32e5a6633c46fb6f8a94b0d004d1bbd4381fb5bbe629faf00984729036005c12e1558c65d70afe4f
-  data.tar.gz: 792b58d5eb3434b05008740457b1c432f5810bd45b2d0d80936bd0c539445098b835c1d242093487cf0a4a4754efba2fe725c500b2d3f1a23f4906b4a17809dc
+  metadata.gz: d0100a2f733bd043a3902cb82cbc5a337ae9a1b19bee952ae9fb2ea0827c8b7ed226cf67db12c0ec997c22b942f5ac735093f6b5a7dc6461c1c2e374db41221b
+  data.tar.gz: 5e0e6dca7f3b4146aa62bdaf493e00e9ca19335c846a8af10beda76a1530dc2fd8bb8bddbcdf914fe60c9c109cfc8e8c095e412cad591e105779263399783bd6

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.

data/TODO.extract-code-chart/05-provenance-and-sidecar.md

@@ -0,0 +1,147 @@
+# TODO 05 — CodeChart::Provenance and CodeChart::Sidecar
+
+## Status
+
+Pending. Depends on TODO 03 (namespace). Depends on TODO 04 (Extractor)
+because Sidecar consumes the Extractor's Result.
+
+## Goal
+
+`Provenance` is the value object carrying the metadata the REQ (R5)
+requires for each extracted SVG's sidecar JSON. `Sidecar` is the
+writer that serializes one Provenance to disk next to its SVG.
+
+## Files
+
+- `lib/ucode/code_chart/provenance.rb` — `Ucode::CodeChart::Provenance`
+  Struct with all REQ R5 fields plus the construction helper.
+- `lib/ucode/code_chart/sidecar.rb` — `Ucode::CodeChart::Sidecar`
+  class (writes a sidecar JSON next to an SVG, idempotent via the
+  existing `Ucode::Repo::AtomicWrites`).
+- `spec/ucode/code_chart/provenance_spec.rb`
+- `spec/ucode/code_chart/sidecar_spec.rb`
+
+## Design
+
+### Provenance value object
+
+The REQ (R5) lists these fields:
+
+```json
+{
+  "codepoint": "U+10920",
+  "block": "Sidetic",
+  "source_pdf_url": "https://www.unicode.org/charts/PDF/U-10920.pdf",
+  "source_pdf_sha256": "...",
+  "ucd_version": "17.0.0",
+  "extracted_at": "2026-06-30T12:00:00Z",
+  "extractor_version": "0.1.0"
+}
+```
+
+`Struct` is the right tool — single source of truth for the schema,
+keyword-init for clarity, immutable-by-convention. Mirror the
+existing `Ucode::Repo::BuildReportAccumulator` pattern.
+
+```ruby
+Provenance = Struct.new(
+  :codepoint,           # String "U+10920"
+  :block,               # String "Sidetic"
+  :source_pdf_url,      # String
+  :source_pdf_sha256,   # String (hex digest)
+  :ucd_version,         # String "17.0.0"
+  :extracted_at,        # String ISO8601 UTC
+  :extractor_version,   # String "0.2.0"
+  keyword_init: true,
+)
+```
+
+`extractor_version` reads from `Ucode::VERSION` so it stays in sync
+with the gem — single source of truth.
+
+`extracted_at` is set at construction (not at file write) so the
+field describes the extraction event, not the serialization event.
+
+### Provenance → Hash serialization
+
+`Provenance#to_h` returns the hash form. NO hand-rolled `to_json` /
+`from_json` per the global rule — `Provenance` is a value object, but
+its schema is simple enough that `to_h` + `JSON.pretty_generate` is
+the framework-driven approach (lutaml-model is overkill for a flat
+struct).
+
+Wait — re-reading the global rule: "ALL (de)serialization goes through
+the framework. In Coradoc and any project using `lutaml-model`." So
+the rule is for projects using lutaml-model, and ucode uses lutaml-model
+for UCD models. This Provenance struct is not a UCD model — it's a
+feature-local value object. JSON via `JSON.pretty_generate(provenance.to_h)`
+is acceptable and avoids ceremony.
+
+`to_h` produces a hash with the Struct's keyword keys. No
+indirection, no lutaml-model mapping for what is effectively a
+record.
+
+### Sidecar writer
+
+```ruby
+class Sidecar
+  include Ucode::Repo::AtomicWrites
+
+  def initialize(output_root:)
+    @output_root = Pathname.new(output_root)
+  end
+
+  # Writes <output_root>/<cp_id>.json next to the corresponding SVG.
+  # Idempotent: re-writing the same content is a no-op (byte-stable).
+  #
+  # @param provenance [Ucode::CodeChart::Provenance]
+  # @return [Pathname] the written path
+  def write(provenance)
+    path = path_for(provenance)
+    payload = JSON.pretty_generate(provenance.to_h)
+    write_atomic(path, payload + "\n")
+    path
+  end
+
+  private
+
+  def path_for(provenance)
+    @output_root.join("#{provenance.codepoint}.json")
+  end
+end
+```
+
+`Repo::AtomicWrites#write_atomic` is the project's single source of
+truth for idempotent file writes — bytes-identical re-writes are
+no-ops (the temp-file rename is skipped when content matches).
+Reuse, don't reimplement.
+
+### Why a separate Sidecar class
+
+A `Provenance.to_disk(path)` method would couple the value object
+to I/O. Keeping the writer separate lets:
+- Tests assert `Provenance#to_h` without touching disk.
+- The Writer (TODO 06) compose `Extractor` + `Sidecar` with explicit
+  dependency injection (seam for testing).
+- Future formats (e.g. a different sidecar schema) replace Sidecar
+  without touching Provenance.
+
+This is MECE: Provenance is data; Sidecar is I/O; Writer is
+orchestration.
+
+## Acceptance
+
+- `Provenance.new(codepoint: "U+10920", block: "Sidetic", ...)`
+  constructs without raising.
+- `Provenance#to_h` returns a Hash with exactly the REQ's fields.
+- `Sidecar#write(provenance)` writes `<codepoint>.json` next to
+  where the SVG lives; the JSON content matches `Provenance#to_h`.
+- Re-writing the same Provenance is a no-op (file unchanged).
+- Specs cover all five REQ fields plus the idempotency guarantee.
+
+## Out of scope
+
+- License attribution text — the REQ mentions `LICENSE-SOURCES.md`
+  obligations, but that's a fontist-side concern (downstream
+  essenfont build). Ucode emits provenance; the consumer stitches
+  attribution.

data/TODO.extract-code-chart/06-codechart-writer.md

@@ -0,0 +1,134 @@
+# TODO 06 — CodeChart::Writer
+
+## Status
+
+Pending. Depends on TODO 04 (Extractor) and TODO 05 (Provenance +
+Sidecar).
+
+## Goal
+
+`Ucode::CodeChart::Writer` is the single entry point for
+"extract every codepoint in block X and write SVG + sidecar JSON
+files under output_dir." It's the orchestration layer the CLI
+calls and the only thing that touches disk.
+
+## Files
+
+- `lib/ucode/code_chart/writer.rb` — `Ucode::CodeChart::Writer` class.
+- `spec/ucode/code_chart/writer_spec.rb`
+
+## Design
+
+### Class shape
+
+```ruby
+class Ucode::CodeChart::Writer
+  Summary = Struct.new(:block, :codepoints_total, :svgs_written,
+                       :sidecars_written, :pdf_sha256, keyword_init: true)
+
+  def initialize(output_root:, pdf_path:, cache_dir: nil,
+                 last_resort_root: nil, blocks_txt: nil)
+    @output_root = Pathname.new(output_root)
+    @pdf_path = Pathname.new(pdf_path)
+    @cache_dir = cache_dir
+    @last_resort_root = last_resort_root
+    @blocks_txt = blocks_txt || Ucode::Cache.ucd_dir(Ucode::VersionResolver.resolve(nil)).join("Blocks.txt")
+    @sidecar = Sidecar.new(output_root: @output_root)
+  end
+
+  # Extracts every codepoint in @block (a Models::Block) and writes
+  # SVG + sidecar JSON under @output_root. Returns a Summary.
+  #
+  # @param block [Ucode::Models::Block]
+  # @return [Summary]
+  def write(block)
+  end
+end
+```
+
+### Per-codepoint flow (single source of truth)
+
+```ruby
+def write(block)
+  output_root_for(block).mkpath
+  pdf_sha = sha256(@pdf_path)
+
+  extractor = Extractor.new(
+    block: block,
+    blocks_txt: @blocks_txt,
+    pdf_path: @pdf_path,
+    cache_dir: @cache_dir,
+    last_resort_root: @last_resort_root,
+  )
+  results = extractor.extract
+
+  svgs = 0
+  sidecars = 0
+  results.each do |result|
+    svg_path = output_root_for(block).join("#{cp_id(result.codepoint)}.svg")
+    File.write(svg_path, result.svg) unless svg_path.exist? && File.read(svg_path) == result.svg
+    svgs += 1 if svg_path.exist?
+
+    provenance = build_provenance(block, result.codepoint, pdf_sha)
+    @sidecar.write(provenance)
+    sidecars += 1
+  end
+
+  Summary.new(
+    block: block.id,
+    codepoints_total: results.size,
+    svgs_written: svgs,
+    sidecars_written: sidecars,
+    pdf_sha256: pdf_sha,
+  )
+end
+```
+
+### Why not use `Repo::AtomicWrites` for the SVGs
+
+The Sidecar uses `Repo::AtomicWrites` because JSON has a stable
+canonical form. SVG output from `EmbeddedFonts::Svg#to_s` is also
+byte-stable, but the writer pattern is simpler with `File.write` —
+the byte-equality check above guarantees idempotency at the I/O
+layer. Both paths reach the same outcome.
+
+If future output formats gain non-stable serialization (timestamps,
+random IDs), the SVG path will need `Repo::AtomicWrites` too. Until
+then, simpler is better.
+
+### Why compute `pdf_sha256` once
+
+Every Provenance in this block carries the same `source_pdf_sha256`.
+Computing it once avoids 32+ disk reads of the PDF per block
+extraction. The Writer is the single place that knows "one block,
+one PDF, one hash" — pushing the calculation into Sidecar or
+Provenance would require either (a) repeated computation per
+Provenance or (b) a parameter-passing thread through Extractor. Both
+violate locality.
+
+### Output layout
+
+`<output_root>/<block_id>/<U+XXXX>.svg` and `<U+XXXX>.json`.
+
+One folder per block keeps the `Writer`'s output self-contained and
+discoverable — a downstream consumer (fontisan) can iterate a block's
+folder without scanning the whole tree. This mirrors the existing
+`Ucode::Repo::Writers::BlocksWriter` output convention (one folder
+per block, index.json inside).
+
+## Acceptance
+
+- `Writer#write(block)` creates `<output_root>/<block_id>/` and
+  fills it with `<U+XXXX>.svg` + `<U+XXXX>.json` for every
+  extracted codepoint.
+- Re-running `Writer#write(block)` with no changes produces
+  byte-identical files (no rewrites).
+- `Summary#svgs_written` equals the number of extracted codepoints.
+- Specs cover the full lifecycle including idempotency.
+
+## Out of scope
+
+- Per-block write isolation — concurrent `Writer#write` calls for
+  different blocks are safe (different folders), but the Writer is
+  not thread-safe within a single block. That's a parallel-extraction
+  concern, not a per-block concern.