fontisan 0.4.47 → 0.4.48

data/benchmark/corpus/run.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+# Runs every benchmark op once-per-process-style and prints JSON:
+#   {"ops": {"name": seconds_per_call | null}, "scan_peak_rss_kb": n | null, ...}
+#
+# Usage: ruby -I<fontisan>/lib benchmark/corpus/run.rb --corpus DIR [--side head|base]
+#
+# The harness lives in the checkout that invokes it; the fontisan under test
+# is whatever `require "fontisan"` resolves to (-I or BUNDLE_GEMFILE).
+#
+# FONTISAN_BENCH_SLOWDOWN=2 makes the `head` side run each op N times slower
+# (it sleeps (N-1) x the op's own time), to prove the gate goes red.
+
+require "json"
+require "optparse"
+require "rbconfig"
+require "benchmark"
+require_relative "ops"
+
+module FontisanBench
+  # Times ops and measures the peak RSS of the directory scan.
+  class Runner
+    MIN_SECONDS = 0.25
+    MIN_REPS = 3
+    SLOW_SECONDS = 2.0
+    MAX_REPS = 200
+
+    def initialize(corpus:, side:, only: nil)
+      @ops = Ops.new(corpus)
+      @side = side
+      @only = only
+      @slowdown = slowdown_for(side)
+    end
+
+    def call
+      ops = {}
+      @ops.all.each do |op|
+        next if @only && !@only.include?(op.name)
+
+        ops[op.name] = runnable?(op) ? time(op) : nil
+      end
+      { "ops" => ops, "scan_peak_rss_kb" => scan_rss, "ruby" => RUBY_VERSION,
+        "fontisan_version" => (defined?(Fontisan::VERSION) ? Fontisan::VERSION : nil) }
+    end
+
+    private
+
+    # FONTISAN_BENCH_SLOWDOWN_TIER=native limits the forced slowdown to the
+    # run whose FONTISAN_ENGINE is that tier (the tiers gate self-test).
+    def slowdown_for(side)
+      return 1.0 unless side == "head"
+
+      tier = ENV.fetch("FONTISAN_BENCH_SLOWDOWN_TIER", "")
+      return 1.0 unless tier.empty? || tier == ENV.fetch("FONTISAN_ENGINE", "")
+
+      ENV.fetch("FONTISAN_BENCH_SLOWDOWN", "1").to_f
+    end
+
+    def runnable?(bench)
+      bench.requires.all? { |const| Object.const_defined?(const) }
+    end
+
+    # Fastest call in seconds after one untimed warm-up call. Calls repeat
+    # until MIN_SECONDS of measured time and at least MIN_REPS calls (unless
+    # the op is already slow), and the minimum is reported: it is the figure
+    # least disturbed by other load on a shared runner.
+    def time(bench)
+      bench.body.call
+      times = []
+      while times.size < MAX_REPS && keep_timing?(times)
+        one = Benchmark.realtime { bench.body.call }
+        # forced slowdown: sleep (N-1) x the call's own time, counted as run time
+        times << one + (@slowdown > 1 ? slow_sleep(one) : 0)
+      end
+      times.min
+    end
+
+    def keep_timing?(times)
+      total = times.sum
+      times.empty? || total < MIN_SECONDS || (times.size < MIN_REPS && total < SLOW_SECONDS)
+    end
+
+    def slow_sleep(one)
+      extra = one * (@slowdown - 1)
+      sleep(extra)
+      extra
+    end
+
+    def scan_rss
+      return nil unless Object.const_defined?("Fontisan::Reference")
+      return nil if @only && !@only.include?("scan_dir")
+
+      lib = File.dirname($LOADED_FEATURES.grep(%r{/fontisan\.rb\z}).first.to_s)
+      Rss.peak_kb(
+        [RbConfig.ruby, "-I", lib, File.join(__dir__, "scan_child.rb"), @ops.corpus],
+        env: ENV.to_h,
+      )
+    end
+  end
+
+  # Peak resident set size of a child process: time(1) on macOS and Linux,
+  # a PowerShell sampler of PeakWorkingSet64 on Windows. nil when the
+  # platform cannot measure it; the tiers gate then skips only the RSS check.
+  module Rss
+    WINDOWS = /mswin|mingw|cygwin/
+    # Polls the child's peak working set until it exits (the value is gone
+    # once the process object is released, so it is sampled, never read late).
+    POWERSHELL = <<~PS
+      $psi = New-Object System.Diagnostics.ProcessStartInfo
+      $psi.FileName = $env:FONTISAN_RSS_EXE
+      $psi.Arguments = $env:FONTISAN_RSS_ARGS
+      $psi.UseShellExecute = $false
+      $p = [System.Diagnostics.Process]::Start($psi)
+      $peak = 0
+      while (-not $p.HasExited) {
+        try { $p.Refresh(); if ($p.PeakWorkingSet64 -gt $peak) { $peak = $p.PeakWorkingSet64 } } catch {}
+        Start-Sleep -Milliseconds 5
+      }
+      $p.WaitForExit()
+      if ($p.ExitCode -ne 0) { exit 1 }
+      Write-Output ("PEAK_BYTES=" + $peak)
+    PS
+
+    module_function
+
+    def supported?
+      windows? || (File.executable?("/usr/bin/time") && !RbConfig::CONFIG["host_os"].match?(WINDOWS))
+    end
+
+    def windows?
+      RbConfig::CONFIG["host_os"].match?(WINDOWS)
+    end
+
+    def peak_kb(cmd, env: {})
+      require "open3"
+      return windows_peak_kb(cmd, env) if windows?
+
+      flag = RbConfig::CONFIG["host_os"].include?("darwin") ? "-l" : "-v"
+      return nil unless File.executable?("/usr/bin/time")
+
+      _out, err, status = Open3.capture3(env, "/usr/bin/time", flag, *cmd)
+      return nil unless status.success?
+
+      parse(err, flag)
+    end
+
+    def windows_peak_kb(cmd, env)
+      args = cmd.drop(1).map { |a| %("#{a}") }.join(" ")
+      out, _err, status = Open3.capture3(env.merge("FONTISAN_RSS_EXE" => cmd.first, "FONTISAN_RSS_ARGS" => args),
+                                         "powershell", "-NoProfile", "-NonInteractive", "-Command", POWERSHELL)
+      return nil unless status.success?
+
+      m = out.match(/PEAK_BYTES=(\d+)/)
+      m && m[1].to_i.positive? ? m[1].to_i / 1024 : nil
+    rescue SystemCallError
+      nil
+    end
+
+    def parse(text, flag)
+      if flag == "-l" # macOS: bytes
+        m = text.match(/^\s*(\d+)\s+maximum resident set size/)
+        m && (m[1].to_i / 1024)
+      else # Linux: kbytes
+        m = text.match(/Maximum resident set size \(kbytes\): (\d+)/)
+        m && m[1].to_i
+      end
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  opts = { side: "head", corpus: nil, only: nil }
+  OptionParser.new do |o|
+    o.on("--corpus DIR") { |v| opts[:corpus] = v }
+    o.on("--side SIDE") { |v| opts[:side] = v }
+    o.on("--only LIST") { |v| opts[:only] = v.split(",") }
+  end.parse!
+  abort "--corpus DIR is required" unless opts[:corpus]
+
+  require "fontisan"
+  puts JSON.generate(FontisanBench::Runner.new(**opts).call)
+end

data/benchmark/corpus/scan_child.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Child process for the scan peak-RSS measurement: scans every file of the
+# corpus fonts directory once. Usage: ruby -I<lib> scan_child.rb CORPUS_DIR
+require "fontisan"
+
+paths = Dir.glob(File.join(ARGV.fetch(0), "fonts", "**", "*")).select { |f| File.file?(f) }.sort
+Fontisan::Reference.scan(paths)

data/benchmark/corpus/tiers.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require_relative "harness"
+
+module FontisanBench
+  # The ruby, native and ffi tiers measured in one job: the same checkout,
+  # one engine per run (FONTISAN_ENGINE, strict), interleaved rounds.
+  module Tiers
+    TIERS = %w[ruby native ffi].freeze
+    # Ops served by the engine tiers (they go through Fontisan::Reference).
+    OPS = %w[audit_file audit_dir scan_dir].freeze
+    # The hard floor (#160): native must be faster than Ruby on these. The ffi
+    # tier is held to the same floor when it ran (it is optional: no cdylib, no
+    # ffi row). Both are floors only; the baseline regression gate is native-only
+    # because no ffi baselines exist.
+    GATED_OPS = %w[audit_file audit_dir scan_dir].freeze
+    # Native peak RSS may exceed ruby's by this much before the gate fails.
+    # #160 says "must not exceed the Ruby baseline's"; the scan's peak RSS is
+    # sampled from a child process (page granularity, allocator noise), and
+    # healthy native/ruby ratios measured 0.84x-0.99x, so a literal 1.00x
+    # decides on noise (0.3 MB of 58 MB flipped a verdict). 3% is about 1.7 MB:
+    # above the noise, far below a real regression (a 1 MB/call leak read 1.35x).
+    RSS_TOLERANCE = 0.03
+    # Committed expected native factors per platform (see benchmark/tier_baseline.json).
+    BASELINE_FILE = File.expand_path("../tier_baseline.json", __dir__)
+
+    # One tier of the working tree. Runs as the `head` side of run.rb.
+    class TierSide < Side
+      attr_reader :tier
+
+      def initialize(tier, dir)
+        super(tier, dir, ref: tier)
+        @tier = tier
+      end
+
+      def env
+        super.merge("FONTISAN_ENGINE" => tier, "FONTISAN_ENGINE_STRICT" => "1")
+      end
+
+      def run_once(harness_dir, corpus, only: nil)
+        cmd = ["bundle", "exec", RbConfig.ruby, File.join(harness_dir, "run.rb"),
+               "--corpus", corpus, "--side", "head"]
+        cmd += ["--only", only.join(",")] if only
+        out, err, st = Open3.capture3(env, *cmd, chdir: dir)
+        raise Error, "tier #{tier} bench run failed:\n#{err}" unless st.success?
+
+        JSON.parse(out.lines.reverse_each.find { |l| l.start_with?("{") })
+      end
+    end
+
+    Row = Struct.new(:metric, :times, :factors, :status, :note, keyword_init: true)
+
+    module_function
+
+    # The expected native factors of +platform+, or nil when none are committed.
+    def baseline(platform, file: BASELINE_FILE)
+      data = JSON.parse(File.read(file))
+      entry = data.dig("platforms", platform)
+      return nil unless entry
+
+      { "tolerance" => data.fetch("tolerance"), "factors" => entry }
+    end
+
+    # Tiers that run at all. ruby and native are required; ffi (needs the
+    # cdylib) is reported when it can run and "unavailable" when it cannot.
+    def sides(dir)
+      TIERS.map { |t| TierSide.new(t, dir) }
+    end
+
+    def measure(sides, rounds:, harness_dir:, corpus:, only: OPS, into: nil, log: $stderr)
+      m = into || Measurement.new
+      rounds.times do |i|
+        (i.even? ? sides : sides.reverse).each do |side|
+          log.puts "round #{i + 1}/#{rounds}: #{side.name}"
+          record(m, side, harness_dir, corpus, only, log)
+        end
+      end
+      m
+    end
+
+    def record(measurement, side, harness_dir, corpus, only, log)
+      measurement.record(side.name, side.run_once(harness_dir, corpus, only: only))
+    rescue Error => e
+      raise if side.tier != "ffi"
+
+      log.puts "ffi tier unavailable: #{e.message.lines.first(3).join.strip}"
+    end
+
+    # Rows: per op the median per tier and the factor ruby / tier (above 1.0
+    # is faster than Ruby), then the scan peak RSS per tier.
+    def rows(measure, baseline: nil)
+      ops = measure.op_names.map { |op| op_row(op, TIERS.to_h { |t| [t, measure.median_op(t, op)] }, baseline) }
+      ops << rss_row(TIERS.to_h { |t| [t, measure.median_rss(t)] })
+    end
+
+    def op_row(name, times, baseline = nil)
+      ruby = times["ruby"]
+      factors = times.transform_values { |v| ruby && v ? ruby / v : nil }
+      status = "ok"
+      note = nil
+      if GATED_OPS.include?(name)
+        status, note = floor(times, factors)
+        status, note = against_baseline(name, factors, baseline) if status == "ok"
+      end
+      Row.new(metric: name, times: times, factors: factors, status: status, note: note)
+    end
+
+    def floor(times, factors)
+      return ["FAIL", "no ruby or native measurement"] unless times["ruby"] && times["native"]
+      return ["FAIL", "native is slower than ruby"] if factors["native"] < 1.0
+      return ["FAIL", "ffi is slower than ruby"] if factors["ffi"] && factors["ffi"] < 1.0
+
+      %w[ok gated]
+    end
+
+    # Regression gate: native may lose at most the tolerance against the
+    # platform's committed factor. Both tiers run in the same job, so the
+    # factor cancels the runner's speed. Without a baseline only the floor holds.
+    def against_baseline(name, factors, baseline)
+      return ["ok", "floor only, no baseline for this platform"] unless baseline
+
+      expected = baseline["factors"][name]
+      return ["ok", "gated"] unless expected
+
+      least = expected * (1 - baseline["tolerance"])
+      return ["ok", "gated, at least #{format('%.2fx', least)}"] if factors["native"] >= least
+
+      ["FAIL", format("native factor %<got>.2fx is more than %<pct>d%% below the expected %<want>.2fx",
+                      got: factors["native"], pct: (baseline["tolerance"] * 100).round, want: expected)]
+    end
+
+    # Both engine tiers share the RSS rule. ffi's cdylib is loaded into the Ruby
+    # process, so its peak RSS is directly comparable to ruby's (local 0.98x).
+    def rss_row(rss)
+      status = "ok"
+      note = nil
+      if rss["ruby"].nil? || rss["native"].nil?
+        note = "peak RSS unsupported on this platform; RSS check skipped"
+        status = "skipped"
+      elsif (over = %w[native ffi].find { |t| rss[t] && rss[t] > rss["ruby"] * (1 + RSS_TOLERANCE) })
+        status = "FAIL"
+        note = "#{over} peak RSS exceeds ruby's by more than #{(RSS_TOLERANCE * 100).round}%"
+      else
+        note = "gated"
+      end
+      Row.new(metric: "scan_peak_rss_kb", times: rss, factors: rss.transform_values { |v| v && rss["ruby"] ? v.to_f / rss["ruby"] : nil },
+              status: status, note: note)
+    end
+
+    def failed?(rows)
+      rows.any? { |r| r.status == "FAIL" }
+    end
+
+    def markdown(rows, title:, rounds:)
+      out = ["## #{title}", "",
+             "Median of #{rounds}+ interleaved rounds, one engine per run (`FONTISAN_ENGINE`, strict). " \
+             "Factor = ruby time / tier time (above 1.00x is faster than Ruby; RSS rows show tier / ruby). " \
+             "Hard floor: native and ffi factors on #{GATED_OPS.join(', ')} must be at least 1.00x and their peak RSS " \
+             "must not exceed ruby's by more than #{(RSS_TOLERANCE * 100).round}%. With a committed baseline for the " \
+             "platform, the native factor must also stay within its tolerance of the expected factor. " \
+             "Other columns are reported, not gated.", "",
+             "| metric | ruby | native | ffi | native factor | ffi factor | status |", "|---|---|---|---|---|---|---|"]
+      rows.each { |r| out << table_line(r) }
+      out << ""
+      out << (failed?(rows) ? "**RESULT: FAIL**" : "**RESULT: PASS**")
+      out.join("\n")
+    end
+
+    def table_line(row)
+      cells = TIERS.map { |t| Compare.fmt(row.metric, row.times[t]) }
+      f = %w[native ffi].map { |t| row.factors[t] ? format("%.2fx", row.factors[t]) : "-" }
+      status = [row.status, row.note].compact.join(": ")
+      "| #{row.metric} | #{cells.join(' | ')} | #{f.join(' | ')} | #{status} |"
+    end
+  end
+end

data/benchmark/tier_baseline.json

@@ -0,0 +1,12 @@
+{
+  "schema": 1,
+  "tolerance": 0.25,
+  "note": "Expected native factor (ruby time / native time) per platform and op, from the perf-gate.yml tiers jobs (run 42233249352 on 2b648ed, BENCHMARKS.md). audit_dir re-measured in run 42789182973 on 91beb5b: the Ruby tier got about 26% faster at audit_dir (one budgeted layout parse, 8e55ebd) while native time stayed flat, so the ratio fell. The tiers gate fails when a measured factor is more than `tolerance` below it. Both tiers run in the same job, so the factor cancels runner speed. A platform without an entry is held to the 1.00x floor only: arm64-darwin has no CI measurement yet. Raise a value only deliberately, from a green CI run.",
+  "platforms": {
+    "x86_64-linux": { "audit_file": 43.14, "audit_dir": 19.93, "scan_dir": 13.58 },
+    "x86_64-linux-musl": { "audit_file": 21.07, "audit_dir": 14.96, "scan_dir": 10.76 },
+    "aarch64-linux": { "audit_file": 45.51, "audit_dir": 11.15, "scan_dir": 7.86 },
+    "x86_64-darwin": { "audit_file": 36.89, "audit_dir": 11.90, "scan_dir": 7.78 },
+    "x64-mingw-ucrt": { "audit_file": 29.71, "audit_dir": 17.69, "scan_dir": 10.57 }
+  }
+}

data/docs/.vitepress/config.ts

@@ -245,6 +245,7 @@ export default defineConfig({
           text: "Advanced Topics",
           collapsed: true,
           items: [
+            { text: "Engines", link: "/guide/engines" },
             { text: "Universal Outline Model", link: "/guide/universal-outline" },
           ],
         },
@@ -360,7 +361,7 @@ export default defineConfig({
     ],
 
     footer: {
-      message: 'Fontisan is a [Ribose](https://open.ribose.com/) project',
+      message: 'Fontisan is a [Ribose](https://www.ribose.com/) project',
       copyright: `Copyright © 2026 Ribose Group Inc. All rights reserved.`,
     },
 

data/docs/guide/engines.md

@@ -0,0 +1,117 @@
+---
+title: Engines
+---
+
+# Engines
+
+The path-based operations of `Fontisan::Reference` (`read`, `outline_hashes`, `audit`, `audit_dir`, `scan`, `convert`, `extract`, `instance`, `glyph_ids`, `subset`) can run on one of three engine tiers. All tiers return the same results; they differ in speed.
+
+| Tier | What it is |
+|---|---|
+| `ruby` | The pure Ruby implementation. Always available. |
+| `native` | A compiled Rust extension (`Fontisan::Native`) loaded into the Ruby process. |
+| `ffi` | A bundled Rust shared library (`Fontisan::Ffi`) called through the `ffi` gem, which is not a runtime dependency of fontisan. |
+
+Reference timings on macOS arm64 (see `BENCHMARKS.md`, local run, not CI), native versus Ruby:
+
+| Operation | Speedup |
+|---|---|
+| `audit` (one file) | 30x |
+| `audit_dir` | 8.2x |
+| `scan` (directory) | 3.9x |
+
+Peak memory of a directory scan is about 4% lower on the native tier.
+
+## Selecting an engine
+
+Set `FONTISAN_ENGINE` before the process starts. Unset or empty means `auto`:
+
+| Value | Behaviour |
+|---|---|
+| `ruby` | Use the Ruby tier only. |
+| `native` | Use the native tier. |
+| `ffi` | Use the ffi tier. |
+| `auto` | The default. Use the first tier that is available and supports the operation, in the order native, ffi, ruby. |
+
+```sh
+FONTISAN_ENGINE=native FONTISAN_ENGINE_STRICT=1 fontisan convert MyFont.ttf --to woff2 --output out.woff2
+ruby -e 'require "fontisan"; p Fontisan::Reference.audit("MyFont.ttf").keys'
+```
+
+Any other value raises `Fontisan::Engine::ConfigError`.
+
+### Command line
+
+The same variables apply to the CLI, but only for the commands that go through the engine: `convert`, `unpack`, `subset` and `instance`. Each routes only its plain cases: `convert` a single-target conversion (several targets, instance coordinates, conversion options, hinting, a collection target format, compression options or a font index run on Ruby); `subset` by `--text` or `--unicode` with the `pdf`, `web` or `minimal` profile; `instance` of a TrueType variable font by axis coordinates to the same format (`--to`, `--named-instance` and `--list-instances` run on Ruby). Every other command (`info`, `validate`, `export`, `pack`, and so on) runs on Ruby.
+
+## Strict mode
+
+If a forced tier (`native` or `ffi`) is not available, fontisan falls back to Ruby silently. Set `FONTISAN_ENGINE_STRICT=1` (also `true`, `yes`, `on`; `0`, `false`, `no`, `off` leave it off, anything else raises `Fontisan::Engine::ConfigError`) to raise `Fontisan::Engine::TierUnavailable` instead:
+
+```sh
+FONTISAN_ENGINE=native FONTISAN_ENGINE_STRICT=1 ruby -rfontisan -e 'Fontisan::Reference.audit("MyFont.ttf")'
+```
+
+Strict mode does not apply to operations a tier cannot serve (see below); those always go to Ruby.
+
+## Which tier served a call
+
+`Fontisan::Engine.served_by(operation)` returns the tier (a Symbol) that served the last call of that operation in the current process, or `nil` if there was none.
+
+```ruby
+ENV["FONTISAN_ENGINE"] = "auto"
+Fontisan::Reference.audit("MyFont.ttf")
+Fontisan::Engine.served_by(:audit)   # => :native
+```
+
+`Fontisan::Engine.scan(paths)` and `Fontisan::Engine.audit_dir(dir)` return the same rows as the `Reference` methods with an added `"served_by"` key per row or entry. Results of the `Reference` methods themselves do not change with the tier.
+
+## What stays on Ruby
+
+These always run on the Ruby tier, whichever engine is selected, and strict mode does not raise for them:
+
+- The object-based API: `Fontisan::Subset::Builder.new(font, ...)` and `Fontisan::Variable::Instancer`. Only the path-based `Reference.subset` and `Reference.instance` can use another tier.
+- Apple dfont files.
+- CLI commands other than `convert`, `unpack` and `subset`, and the non-plain `convert` cases listed above.
+- Type 1 fonts (PFB/PFA).
+
+## Platforms
+
+Platform gems with the native extension and the bundled shared library are published for:
+
+- `x86_64-linux`
+- `x86_64-linux-musl`
+- `arm64-darwin`
+- `x86_64-darwin`
+- `x64-mingw-ucrt` (Ruby 3.2 to 4.0)
+
+The `java` gem (JRuby) carries the shared library only (bundled for linux-x86_64, darwin-arm64, darwin-x86_64 and windows-x86_64; no musl or linux-arm64), so it serves the `ffi` tier. It depends on neither `brotli` nor `rb_sys`; a WOFF2 operation that falls to the Ruby tier on this gem raises `Fontisan::Engine::Woff2Unavailable`.
+
+The plain source gem builds the native extension at install time when a Rust toolchain (`cargo`) and the `rb_sys` gem are present. Without them the install still succeeds and fontisan runs on the Ruby tier.
+
+## Troubleshooting
+
+### "native tier not available"
+
+With `FONTISAN_ENGINE=native` and `FONTISAN_ENGINE_STRICT=1` you get `TierUnavailable`: the native extension did not load. Check:
+
+```sh
+ruby -rfontisan -e 'p Fontisan::Native.available?, Fontisan::Ffi.available?'
+```
+
+- `false` on an installed platform gem: the gem was installed on a Ruby version or platform it does not cover. Run `gem list fontisan` and check the platform suffix; install the matching one.
+- `false` on a source install: the extension was skipped because `cargo` or `rb_sys` was missing. See below.
+- Without strict mode, the same condition silently serves from Ruby; use `Fontisan::Engine.served_by` to confirm which tier ran.
+
+For the ffi tier, `FONTISAN_CDYLIB` can point at a specific shared library file.
+
+### Building from source
+
+Install a Rust toolchain ([rustup](https://rustup.rs)), then reinstall so the extension is compiled:
+
+```sh
+gem install rb_sys
+gem install fontisan --platform ruby
+```
+
+With Bundler, add `gem "fontisan", force_ruby_platform: true` to build from the source gem. Set `FONTISAN_NATIVE_REQUIRED=1` during the install to make a missing toolchain or a failed build an error instead of a silent skip. `FONTISAN_SKIP_CDYLIB=1` skips building the shared library for the ffi tier.

data/docs/reference-facade.md

@@ -0,0 +1,130 @@
+# Reference facade (`Fontisan::Reference`)
+
+Every golden is generated through this module; every engine tier serves the
+same operations. Operations take a file path, never a loaded font. Read-type
+results are JSON-ready: Hash with String keys sorted bytewise, Array, String,
+Integer, true, false, nil. No Float (Fixed 16.16 values are raw integers) and
+no clock value. `Reference.canonical_json(data)` = `JSON.pretty_generate` of the
+normalised data plus a trailing newline.
+
+Errors: the wrapped class's exception propagates unchanged (`Errno::ENOENT`,
+`Fontisan::InvalidFontError`, `Fontisan::Error` "Conversion failed: ...",
+`ArgumentError`). `scan` and `audit_dir` never raise for a bad font; the failure
+is recorded in the row/entry. A non-path argument raises `TypeError`.
+
+## Operations
+
+| Op | Returns |
+|---|---|
+| `read(path, mode: :metadata, lazy: true)` | Array of faces (below) |
+| `outline_hashes(path, index: 0)` | `{"kind"=>"glyf"/"cff"/nil, "hashes"=>[hex...]}` |
+| `audit(path, validate: false)` | Array of canonical audit reports, one per face |
+| `audit_dir(dir, validate: false)` | Array of `{"path"=>rel, "faces"=>[...]}` or `{"path","error"=>{"class","message"}}`, sorted by relative path; files with ttf otf ttc otc woff woff2 dfont pfa pfb extensions |
+| `scan(paths)` | Array of scan rows (below); `Fontisan.scan` delegates here |
+| `convert(path, to:, output:, timestamp: nil)` | the `ConvertCommand` result Hash; runs quietly; `timestamp` is passed only when `to` is `woff2` |
+| `extract(path, index:, output_dir:)` | path of the extracted file (`UnpackCommand`) |
+| `instance(path, coords:, timestamp: nil)` | binary String (`Instancer#instance`); `timestamp` ignored |
+| `glyph_ids(path, unicodes:, text:)` | sorted unique gids; raises `Fontisan::Error` "None of the requested characters exist in <basename>" |
+| `subset(path, unicodes:, text:, profile: "web", timestamp: nil)` | binary String; gids then `Subset::Builder`; `timestamp` ignored |
+
+Three additions to existing behaviour, nothing else: optional `timestamp:`
+(Unix seconds or Time) fixing `head.modified` in WOFF2 encode and
+`StaticFontBuilder` (nil = today's clock behaviour); fontist's `glyph_ids` step
+in `subset`; quiet `convert`.
+
+## `read` face
+
+`index, format, mode, lazy, file_sha256`, `tables` (`tag, length, sha256, error`
+per table; sha256 nil when the loading mode gates the table out, `error` is the
+exception class when loading/parsing failed), `names` (`platform_id, encoding_id,
+language_id, name_id, string` decoded as fontist's `decode_name_record_manually`),
+`header_fields` (`head`, `hhea`, `maxp`, `OS/2`: every field of the parsed record
+with Ruby's field names; Strings that are printable ASCII stay text, others are
+`"0x"+hex`), `cmap` (`count`, `sha256`, `subtable_formats`; sha256 is SHA-256 over
+the sorted codepoints as big-endian uint32), `fvar` (`axes` with `*_raw` Fixed
+integers, `instances` with `coordinates_raw`), `outlines` (`kind`, `count`,
+`digest` = SHA-256 over the concatenated 32-byte per-glyph hashes).
+
+Per-glyph outline hash: glyf fonts hash the glyph's byte range of `glyf`, located
+via the parsed `loca` (empty glyph = hash of the empty string); CFF fonts hash the
+CharString bytes of the CharStrings INDEX entry; CFF2 fonts (`kind` "cff2")
+hash the CharStrings INDEX entries located through Top DICT operator 17 (the
+INDEX count is a uint32).
+
+Further `read` face fields (all nil when the table is absent or gated out):
+
+- `post`: `version_raw, italic_angle_raw, underline_position,
+  underline_thickness, is_fixed_pitch, min_mem_type42, max_mem_type42,
+  min_mem_type1, max_mem_type1`, `glyph_name_count` and `glyph_names_sha256`
+  (SHA-256 of the glyph names joined with "\n"), or `glyph_names_error`.
+- `hmtx_metrics`: `count` (glyphs) and `sha256` over the decoded `Hmtx#metric_for`
+  result of every glyph (advance as uint32 BE, lsb as int32 BE, concatenated), or
+  `{error}`. A decoded-value digest: the `tables` digests are raw bytes and no
+  convert golden reads hmtx. (Parsed glyf coordinates are covered by the convert
+  goldens, whose ttf -> otf rebuild decodes every simple glyph; measured red under
+  a coordinate-delta mutation.)
+- `layout`: `GSUB` / `GPOS` => `{scripts, features}` where `features` maps each
+  script tag to its feature tags, exactly as the table classes report them
+  (they answer `[]` when parsing fails; that is the reference behaviour).
+- `variation`: `gvar`, `HVAR`, `VVAR`, `MVAR`, `STAT` parsed digests, below;
+  `{"error"=>class}` when the table cannot be read.
+
+## Parsed table digests (`variation`)
+
+Computed from the raw table bytes by `Fontisan::Reference::TableDigests`. A
+"parts digest" is SHA-256 over the concatenated 32-byte SHA-256 of each part.
+
+- `gvar`: `version, axis_count, flags, glyph_count, glyphs_with_data,
+  shared_tuple_count, shared_tuples_sha256` (the `shared_tuple_count x
+  axis_count x 2` bytes at `sharedTuplesOffset`), `glyphs_digest` = parts
+  digest over each glyph's GlyphVariationData byte range (offset array
+  `u16*2` or `u32` by flag bit 0, relative to `glyphVariationDataArrayOffset`).
+- `item_variation_store` (HVAR, VVAR, MVAR): `region_count, item_data_count,
+  regions_sha256` (4 + regionCount x axisCount x 6 bytes), `data_sha256` (one
+  per ItemVariationData: 6 + 2 x regionIndexCount + itemCount x row bytes; row
+  = wordCount + regionIndexCount, or 4 x wordCount + 2 x (regionIndexCount -
+  wordCount) with the long-words flag), `data_digest` = parts digest of those.
+- `HVAR`/`VVAR`: `version`, `item_variation_store`, and `advance_mapping`,
+  `lsb_mapping`, `rsb_mapping` (nil when the offset is 0) each
+  `{format, entry_format, map_count, sha256}` over the whole DeltaSetIndexMap
+  (4 or 6 byte header + mapCount x entrySize).
+- `MVAR`: `version`, `value_records` (`tag, outer, inner`), `item_variation_store`
+  (Offset16 from the table start, per the OpenType spec).
+- `STAT`: `version, elided_fallback_name_id` (nil before 1.1), `axes` (`tag,
+  name_id, ordering`), `axis_values` in table order: formats 1-3 as
+  `format, axis_index, flags, value_name_id` plus `value_raw` /
+  `nominal_raw, range_min_raw, range_max_raw` / `value_raw, linked_value_raw`
+  (Fixed 16.16 integers); format 4 with `axis_values` (`axis_index, value`).
+
+## Audit canonical form
+
+`AuditCommand` with `include_codepoints: false`; `generated_at` and
+`fontisan_version` dropped; Float fields become raw Fixed integers:
+`font_revision` -> `font_revision_raw`, axis `min_value/default_value/max_value`
+-> `*_raw` (value x 65536, rounded).
+
+Object addresses in messages (`#<Class:0x000...>`, from checks that crash) become
+`#<Class>`, so the text is stable between runs.
+
+## Scan row (one per face)
+
+`path, collection_index (nil for non-collections), sha256, format, is_collection,
+num_faces, has_fvar`, `names` and `english_names` (`family_name, full_name,
+subfamily_name, preferred_family, preferred_subfamily, postscript_name`;
+`names` uses fontist's any-platform fallback as `FontFile`, `english_names` is
+`english_name` only as `CollectionFile`; `english_names` is nil for
+non-collections), `variable_instances` (`family, style, full_name`, fontist's
+RIBBI rule, from a second full-mode load), `validation` (`profile, valid,
+status, issues[severity, category, message, location], error_summary` = fontist's
+`"category: message; ..."`), and `errors`:
+
+- `font_file`: what `FontFile.extract_font_info_from_path` would raise (only
+  rows of the face it reads: non-collection or index 0), as `{class, message,
+  cause}`; message `"Font file could not be parsed: #&lt;Class: msg&gt;."`.
+- `collection_file`: what `CollectionFile.from_path` would raise for the file
+  (same on every row of the file): "Font collection could not be loaded: ..."
+  (for a non-collection the text is "...: File is not a recognized font collection
+  (TTC/OTC/dfont)", because `CollectionFile` wraps its own raise; a collection with
+  no faces gets one row of its own, `num_faces` 0, to carry the error) or "Font collection failed indexability validation (first font): ...".
+- `collection_member`: error of the lazy:false metadata load that
+  `CollectionFile#[]` performs for this face, `{class, message}`.