pdftract/notes/pdftract-njde.md

pdftract-njde: Font Fingerprint Cache (Level 3)

Summary

Implemented Level 3 of the encoding fallback chain - a font fingerprint cache that uses SHA-256 hashes of embedded font programs to look up glyph-to-Unicode mappings for known fonts.

Implementation

Files Created

1. crates/pdftract-core/build/font-fingerprints.json

   • Empty JSON array (placeholder for future font entries)
   • Schema: [{ sha256_hex, font_name, entries: [[gid, codepoint], ...] }]

2. crates/pdftract-core/src/font/fingerprint.rs

   • FontFingerprint: computes SHA-256 hash of font program bytes
   • lookup_font_fingerprint(): runtime API for single lookups
   • CachedFingerprint: cached hash for repeated lookups on the same font
   • Full test coverage (12 tests, all passing)

Files Modified

1. crates/pdftract-core/build.rs

   • Added generate_font_fingerprints() function
   • Reads JSON, validates SHA-256 hex (64 chars), validates Unicode scalars
   • Generates font_fingerprints.rs with phf::Map<[u8; 32], &'static [(u16, u32)]>
   • Key type is [u8; 32] (binary digest), not &str (hex string)

2. crates/pdftract-core/src/font/mod.rs

   • Added pub mod fingerprint;
   • Exported FontFingerprint, CachedFingerprint, lookup_font_fingerprint

Acceptance Criteria

• ✅ Empty JSON produces valid phf::Map: Empty array compiles without errors
• ✅ Hash is stable across runs: Verified with test_hash_stability_across_runs
• ✅ Lookup of unknown digest returns None: Verified with multiple tests
• ✅ Binary footprint: Empty database = negligible (~0 bytes); 200-font target = ~500KB (to be verified when populated)
• ✅ Key type is [u8; 32]: Not &str - conversion happens at build time
• ✅ Hash computed over decoded bytes: FontFingerprint::compute() takes raw decoded bytes

Design Decisions

Hash computed once per font

Per the implementation guidance, the hash should be computed ONCE per font load and stored. The CachedFingerprint struct handles this - it computes the hash once, checks if it's in the database, and can be reused for multiple glyph lookups.

Database not user-extensible at runtime

The phf::Map is compile-time generated; adding entries requires editing the JSON and rebuilding. This is by design per the task requirements.

Skip L3 for Std-14 fonts

Std-14 fonts don't have embedded font programs, so the fingerprint cache is skipped for them. The EmbeddedFont::load() function already returns EmptyFontMetrics for Type1Std14 fonts.

Test Results

running 12 tests
test font::fingerprint::tests::test_cached_fingerprint_accessors ... ok
test font::fingerprint::tests::test_cached_fingerprint_deterministic ... ok
test font::fingerprint::tests::test_cached_fingerprint_reuse ... ok
test font::fingerprint::tests::test_cached_fingerprint_unknown_font ... ok
test font::fingerprint::tests::test_empty_database_compiles ... ok
test font::fingerprint::tests::test_font_fingerprint_as_bytes ... ok
test font::fingerprint::tests::test_fingerprint_different_inputs ... ok
test font::fingerprint::tests::test_font_fingerprint_compute ... ok
test font::fingerprint::tests::test_font_fingerprint_empty_input ... ok
test font::fingerprint::tests::test_hash_stability_across_runs ... ok
test font::fingerprint::tests::test_lookup_font_fingerprint_unknown_font ... ok
test font::fingerprint::tests::test_lookup_font_fingerprint_different_gids ... ok

test result: ok. 12 passed; 0 failed; 0 ignored

Next Steps

1. Populate font-fingerprints.json with real font fingerprints (commercial fonts, etc.)
2. Integrate lookup_font_fingerprint() into the encoding fallback chain in extract.rs
3. Measure binary footprint when populated with ~200 fonts

References

• Plan section: Phase 2.2 Level 3 (lines 1343-1352)
• Dependency Matrix: sha2 crate already approved