claricle 0.1.0 → 0.2.0

data/lib/claricle/handlers/metafile.rb

@@ -0,0 +1,1011 @@
+# frozen_string_literal: true
+
+require "emf"
+
+require_relative "base"
+require_relative "../conversion_engine"
+require_relative "../models/location"
+require_relative "../models/report"
+require_relative "../models/inspection"
+require_relative "../models/issue"
+require_relative "../models/conversion"
+require_relative "../lossiness"
+
+module Claricle
+  module Handlers
+    # Record framing: where a record starts and stops, and which one ends the
+    # stream.
+    #
+    # Beside `EmfPlus` rather than inside it: `EmfPlus` is about what an EMF+
+    # carrier holds -- which record type carries it, the signature, and how
+    # much payload to count -- while this is the vocabulary that walking the
+    # records consults. `EmfStructure` walks the same vocabulary to a
+    # different end, so a rule here changes both walks, which is why it is
+    # stated once and in neither of them.
+    module EmfRecords
+      # EMR_EOF closes the stream.
+      EOF_RECORD = 14
+      # EMR_EOF is Type, Size, nPalEntries, offPalEntries and SizeLast,
+      # so a shorter type-14 record is not an end of stream at all. The
+      # delegate records such a record as Raw and keeps going, and a
+      # carrier after it is real: measured, with nSize 8, 12 or 16 the
+      # gem still finds 12 bytes of EMF+ where stopping finds none.
+      EOF_RECORD_BYTES = 20
+      RECORD_HEADER_BYTES = 8
+      ALIGNMENT = 4
+      # EMR_COMMENT, and its own header: Type, Size and DataSize. Both walks
+      # read a comment's DataSize, so its layout lives here.
+      COMMENT_RECORD = 70
+      COMMENT_HEADER_BYTES = 12
+
+      # A record must declare a size that is aligned, at least a header
+      # long, and inside what is left. Anything else means the framing is
+      # broken and neither walk can continue: `EmfPlus` stops totalling, and
+      # the structural pre-pass reports `emf.record_framing` at this offset.
+      # The minimum also guarantees forward progress: a record declaring zero
+      # would otherwise pin the walk on one offset forever.
+      def self.record_at(content, offset)
+        return nil if content.bytesize - offset < RECORD_HEADER_BYTES
+
+        type, size = content.byteslice(offset, RECORD_HEADER_BYTES).unpack("VV")
+        return nil if size < RECORD_HEADER_BYTES || !(size % ALIGNMENT).zero?
+        return nil if size > content.bytesize - offset
+
+        [type, size]
+      end
+
+      # 20 bytes is the MINIMUM, not the size -- a writer may pad an EMR_EOF,
+      # and a bigger one still closes the stream.
+      def self.eof?(type, size)
+        type == EOF_RECORD && size >= EOF_RECORD_BYTES
+      end
+    end
+
+    # Finds EMF+ by walking the record framing, because the delegate
+    # cannot answer the question. emf 0.1.0 does not parse EMF+ at all --
+    # its EMF+ parser is unimplemented, and its full pass only recognises
+    # the marker and concatenates the bytes, which is close to what this
+    # does. It gets the question wrong three ways. It raises NoMethodError
+    # on a comment whose cbData overruns its own record, because the
+    # extraction step checks cbData >= 4 without checking four bytes are
+    # there. It fails outright on the valid 92- and 96-byte described
+    # headers, reporting no EMF+ for files that may carry it. And it
+    # counts a record's alignment padding as payload: measured, it reports
+    # 4 bytes for `padded_comment.emf`, whose cbData leaves 1.
+    #
+    # The handler stays a wrapper -- emf still owns every substantive
+    # header field. Only the marker hunt is local, and only because
+    # upstream's path for it is broken.
+    module EmfPlus
+      # EMR_COMMENT is the only record type EMF+ travels in. Its declared
+      # payload begins after the comment's twelve-byte header, and the
+      # signature occupies the first four bytes of it.
+      SIGNATURE = "EMF+".b.freeze
+
+      # A distinct marker rather than a zero advance. Overloading zero
+      # would make a malformed record declaring no size look like a clean
+      # end of stream, which retires the guard that catches it.
+      END_OF_STREAM = :end_of_stream
+
+      # Bytes of EMF+ payload, or **nil when the stream was over the byte
+      # limit and nothing was examined at all**.
+      #
+      # That is a different answer from zero and an earlier version
+      # conflated them. Zero means the walk ran to completion and found
+      # none -- including when framing broke partway, since what it read
+      # before the break is still established. Nil means the walk never
+      # ran, so it cannot say what the stream holds and must not report
+      # absence on the strength of bytes nobody read. A stream one byte
+      # over the limit can carry `EMF+` in its very first record;
+      # answering zero there would be exactly that mistake.
+      #
+      # The byte limit matches the delegate's own:
+      # `Emf::Emr::Parser::MAX_INPUT_BYTES` is the same 200 MiB and
+      # refuses on the same `>`. What it buys is that the cost stops
+      # growing past it.
+      #
+      # The iteration budget handed to `walk` is derived, not chosen. It
+      # exists only so a defect in `EmfRecords.record_at` cannot spin the
+      # walk on one offset forever: it refuses a record declaring fewer
+      # than its eight-byte header, so every step advances at least that
+      # far, and the content is at most `limit` bytes -- so
+      # `limit / EmfRecords::RECORD_HEADER_BYTES` steps always outlast the
+      # bytes and the budget can never bind first.
+      #
+      # It used to be a flat 500,000 and that WAS a ceiling a real file
+      # could hit. EMR_SETMETARGN is a valid parameterless 8-byte record
+      # and EMR_HEADER's record count is an unsigned 32-bit field, so an
+      # internally consistent stream of 500,000 of them is ordinary EMF
+      # and only 4.0 MiB long. Measured: it reported no EMF+ verdict at
+      # all, and 499,999 of them reported `emf_plus_present: false`.
+      #
+      # The byte limit is therefore the only thing bounding CPU, and what
+      # that costs is worth writing down. Measured on a stream of
+      # minimum-size records: 3.8 MiB walks in 0.58s and 20.0 MiB in
+      # 3.57s, so the 200 MiB boundary is around 36 seconds. The flat
+      # budget held that near 0.6s -- and refused ordinary files to do
+      # it. Answering a 4 MiB file correctly is worth the worst case.
+      def self.size(content, declared, limit)
+        return nil if content.bytesize > limit
+
+        walk(content, declared, limit / EmfRecords::RECORD_HEADER_BYTES)
+      end
+
+      # Broken framing stops the walk and keeps what came before it.
+      # Discarding a validated total was a false negative: measured, a
+      # stream whose final EMR_EOF declares nSize 0 still carries two
+      # intact carriers, and the delegate reports their 40 bytes while
+      # an all-or-nothing rule reported none. Every record counted here
+      # had its own framing checked before it was counted, so a later
+      # break says nothing about the ones already read.
+      #
+      # The line after the loop is the budget running out. With the budget
+      # derived from the byte limit it cannot be reached at all: offset
+      # starts at `declared`, every step adds at least
+      # `EmfRecords::RECORD_HEADER_BYTES`, and `budget` is the byte limit
+      # divided by that, so the end of the content always arrives first.
+      # It stays written for a budget that CAN bind, which is why it asks
+      # where the offset landed -- a last budgeted step that finished the
+      # stream walked it completely and keeps its total, while one that
+      # stopped short answers nil, because the remainder it never reached
+      # might carry EMF+ and a partial total would be silent about that.
+      def self.walk(content, offset, budget)
+        total = 0
+        budget.times do
+          return total if offset >= content.bytesize
+
+          advance = step_forward(content, offset, total)
+          return total unless advance
+
+          total, offset = advance
+        end
+        offset < content.bytesize ? nil : total
+      end
+
+      # A record consumed and folded into the running total, as
+      # `[total, offset]`, or nil at broken framing or EMR_EOF -- the
+      # two ways a step is not a record to keep walking past.
+      def self.step_forward(content, offset, total)
+        step = step_at(content, offset)
+        return nil if step.nil? || step == END_OF_STREAM
+
+        [total + step.first, offset + step.last]
+      end
+
+      # One record: `[payload, advance]`, `END_OF_STREAM` at EMR_EOF, or
+      # nil when the framing is broken.
+      def self.step_at(content, offset)
+        type, size = EmfRecords.record_at(content, offset)
+        return nil unless size
+        return END_OF_STREAM if EmfRecords.eof?(type, size)
+
+        [payload_of(content, offset, type, size), size]
+      end
+
+      # Only the bytes the comment declares are inspected, and only the
+      # declared count is added -- a record's padding is not payload.
+      #
+      # A comment whose `cbData` overruns its own record contributes
+      # nothing and does NOT stop the walk. MS-EMF keeps the whole-record
+      # `Size` and the inner `DataSize` separate, and the outer size was
+      # already validated as aligned and in bounds -- so it still proves
+      # where the next record begins, whatever the inner field claims.
+      # Measured: stopping there reported no EMF+ for a stream whose
+      # SECOND carrier was intact and which the delegate reads as 12
+      # bytes. That is the same mistake as discarding a validated total
+      # on a later break, one level down.
+      #
+      # The record minimum is load-bearing, not belt-and-braces: an
+      # 8-byte comment record standing LAST in the stream has no bytes
+      # after its header, so `unpack1` gives nil and the bound below
+      # raises NoMethodError.
+      #
+      # The `cbData` minimum is a CORRECTNESS guard. It was written down
+      # as a fast path and that was wrong: the signature is sliced from
+      # the RECORD, not from the declared run, so a comment declaring
+      # fewer than four bytes still gets four read out of it, matches,
+      # and the subtraction below goes NEGATIVE. Measured on a 16-byte
+      # comment declaring `cbData` 1 in front of an `EMF+` marker: with
+      # the line removed the handler reported `emf_plus_present` true
+      # and `emf_plus_bytes` -3.
+      #
+      # It also has to sit ahead of the slice, because reaching the
+      # comparison costs two strings for a record that cannot match: the
+      # four-byte slice and its `.b` copy. Measured over 20 MiB of
+      # 12-byte comments declaring `cbData` 0 -- the densest a stream can
+      # be, 1,747,626 records -- moving the check below the slice added
+      # 3,495,252 objects, exactly two per record.
+      #
+      # Only the signature is sliced, never the declared payload, and a
+      # comment may declare nearly the whole stream. `byteslice` COPIES
+      # at that size: measured, taking 180 MiB out of a 200 MiB string
+      # allocated 188,743,721 bytes and grew malloc by the same again.
+      # Four bytes costs 40. Slicing the declared run instead would
+      # therefore copy the carrier, not point into it.
+      def self.payload_of(content, offset, type, size)
+        return 0 unless type == EmfRecords::COMMENT_RECORD
+        return 0 if size < EmfRecords::COMMENT_HEADER_BYTES
+
+        declared = content.byteslice(offset + EmfRecords::RECORD_HEADER_BYTES, 4)
+                          .unpack1("V")
+        return 0 if declared > size - EmfRecords::COMMENT_HEADER_BYTES
+        return 0 if declared < SIGNATURE.bytesize
+
+        signature = content.byteslice(offset + EmfRecords::COMMENT_HEADER_BYTES, SIGNATURE.bytesize)
+        return 0 unless signature.b == SIGNATURE
+
+        declared - SIGNATURE.bytesize
+      end
+
+      private_class_method :walk, :step_at, :step_forward, :payload_of
+    end
+
+    # Structural pre-pass over the raw record stream, needing nothing from
+    # the delegate. It reports how the stream ends -- framing breaks, no
+    # EMR_EOF, bytes after it, an EMR_EOF whose SizeLast disagrees with its
+    # Size -- and any comment whose DataSize overruns its own record. Bytes
+    # are never read beyond what `EmfRecords.record_at` slices and the
+    # DWORD fields named below; the caller owns the read and its bound.
+    module EmfStructure
+      # EMR_EOF's final field, SizeLast. MS-EMF requires it to equal the
+      # record's Size.
+      SIZE_LAST_BYTES = 4
+
+      # `declared` is the caller's contract, not this method's to police: it
+      # arrives from `declared_size`, which yields an Integer, 4-aligned and
+      # at least MINIMUM_HEADER. Non-negative is the property this walk rests
+      # on, and it is worth being exact about what a negative would cost,
+      # because it does not fail one way. Measured on `valid.emf`: -1 raises
+      # NoMethodError, -16 raises Lutaml::Model::ValidationError from a
+      # negative `byte_offset`, and only -88 produces the quiet nonsense of a
+      # `byteslice` counting from the end. Two of those three escape a method
+      # whose contract is to RETURN issues. That is a reason to keep the
+      # contract, not to add a check for an input the handler cannot deliver.
+      #
+      # `declared` is NOT guaranteed to be inside the bytes on hand.
+      # `declared_size` bounds it by `available`, which is the read's own
+      # length under the scan limit but the file's stat above it -- so a stat
+      # reading high admits a declaration the content cannot hold, the
+      # residual written down at `declared_size` itself. No guard is needed
+      # for that either: the loop condition is false from the first step and
+      # the answer is `[missing_eof]`.
+      #
+      # nil means "not examined": over the byte limit nothing was read, and
+      # `[]` would be the stronger claim that the stream ends properly. The
+      # guard is deliberately the same idiom as `EmfPlus.size`'s -- same `>`,
+      # same figure, same reason.
+      #
+      # The walk's bound is the loop condition, so `record_at` is never
+      # called at `offset == content.bytesize`: a stream ending exactly on a
+      # record boundary is a missing EOF, not broken framing.
+      #
+      # No iteration budget, unlike `EmfPlus.walk`. That budget exists to stop
+      # a defect pinning the walk on one offset forever; here `EmfRecords.record_at`
+      # already refuses a record declaring fewer than its eight-byte header, so
+      # every step advances at least eight bytes and the byte bound is
+      # sufficient on its own.
+      #
+      # A comment overrun does not stop the walk. The outer Size was already
+      # checked, so it still says where the next record begins -- the same
+      # reason `EmfPlus.payload_of` carries on past one.
+      def self.issues(content, declared, limit)
+        return nil if content.bytesize > limit
+
+        walk(content, declared, [])
+      end
+
+      def self.walk(content, offset, found)
+        while offset < content.bytesize
+          type, size = EmfRecords.record_at(content, offset)
+          return found << framing(offset) if size.nil?
+          return found + ending(content, offset, size) if EmfRecords.eof?(type, size)
+
+          found << overrun(offset, size) if overrun?(content, offset, type, size)
+          offset += size
+        end
+        found << missing_eof
+      end
+
+      def self.body_record_count(content, offset)
+        count = 0
+        while offset < content.bytesize
+          type, size = EmfRecords.record_at(content, offset)
+          return nil if size.nil?
+
+          count += 1
+          return count if EmfRecords.eof?(type, size)
+
+          offset += size
+        end
+        nil
+      end
+
+      def self.ending(content, offset, size)
+        at = offset + size - SIZE_LAST_BYTES
+        last = content.byteslice(at, SIZE_LAST_BYTES).unpack1("V")
+        found = last == size ? [] : [size_last(at, last, size)]
+        found + trailing(content, offset + size)
+      end
+
+      # A comment's DataSize has to fit in what follows its three-field
+      # header. An 8-byte comment has no DataSize field at all.
+      def self.overrun?(content, offset, type, size)
+        return false unless type == EmfRecords::COMMENT_RECORD
+        return true if size < EmfRecords::COMMENT_HEADER_BYTES
+
+        content.byteslice(offset + EmfRecords::RECORD_HEADER_BYTES, 4).unpack1("V") >
+          size - EmfRecords::COMMENT_HEADER_BYTES
+      end
+
+      def self.overrun(at, size)
+        issue("emf.comment_overrun", "the EMR_COMMENT at byte #{at} declares more data than its record holds",
+              Models::Location.new(byte_offset: at, byte_length: size))
+      end
+
+      def self.size_last(at, last, size)
+        issue("emf.eof_size_mismatch", "EMR_EOF declares size #{size} but its SizeLast field says #{last}",
+              Models::Location.new(byte_offset: at, byte_length: SIZE_LAST_BYTES))
+      end
+
+      def self.trailing(content, at)
+        return [] if at >= content.bytesize
+
+        count = content.bytesize - at
+        noun = count == 1 ? "byte follows" : "bytes follow"
+        [issue("emf.trailing_bytes", "#{count} #{noun} the EMR_EOF record",
+               Models::Location.new(byte_offset: at, byte_length: count))]
+      end
+
+      # `record_at` refuses for four different reasons and returns a bare nil
+      # carrying none of them, so the message names the offset and no reason.
+      def self.framing(at)
+        issue("emf.record_framing", "EMF record framing breaks at byte #{at}",
+              Models::Location.new(byte_offset: at))
+      end
+
+      def self.missing_eof
+        issue("emf.missing_eof", "EMF record stream ends without an EMR_EOF record", nil)
+      end
+
+      def self.issue(code, message, location)
+        Models::Issue.new(severity: "error", code: code, message: message,
+                          location: location)
+      end
+
+      private_class_method :walk, :ending, :overrun?, :overrun, :size_last, :trailing, :framing,
+                           :missing_eof, :issue
+    end
+
+    private_constant :EmfRecords, :EmfPlus, :EmfStructure
+
+    # The one issue `inspection` can report. Beside the conformance codes
+    # rather than inside `Metafile`, so every code this file can emit reads
+    # in one place.
+    HEADER_ISSUE_CODE = "emf.header_unreadable"
+    HEADER_ISSUE_MESSAGE = "EMF header could not be read"
+
+    private_constant :HEADER_ISSUE_CODE, :HEADER_ISSUE_MESSAGE
+
+    # Builds the `Report` a conform operation returns. A sibling of the
+    # metadata reading below and nothing more: the two share a handler
+    # and no state.
+    class ConformanceMapper
+      # `Emf.parse` raises three families on truncation, at different cut
+      # points, all measured on this repo's own fixtures:
+      #
+      #   Emf::FormatError   truncated_44.emf, declared_100_have_99.emf
+      #   IOError            nsize_87.emf, truncated_117.emf
+      #   EOFError           described_92.emf, nsize_44.emf
+      #
+      # `EOFError < IOError`, so listing IOError covers both -- but only
+      # because this rescues by CLASS MATCHING. A guard comparing
+      # `e.class == IOError` would silently miss every EOFError.
+      #
+      # NoMethodError is the one the plan card does not mention, and it
+      # is not hypothetical: `bad_comment.emf`, already in this repo,
+      # reaches it, and a 3000-document fuzz hit it 66 times. The gem
+      # trusts a comment record's declared `cb_data` without checking the
+      # bytes it actually parsed, so `getbyte` returns nil and the shift
+      # raises. Left off the allowlist, a real malformed file exits 4 --
+      # an internal error -- instead of 1.
+      MALFORMED = [::Emf::FormatError, ::IOError, ::NoMethodError].freeze
+
+      # Its own copies, not `Metafile`'s: those are `private_constant` on a
+      # class this module sits beside, and reaching for them would couple
+      # the two in the one direction that is hard to unpick later.
+      MINIMUM_HEADER = 88
+      SCAN_LIMIT = 200 * 1024 * 1024
+      # The header's Bytes field: MS-EMF defines it as the size of the whole
+      # metafile.
+      BYTES_OFFSET = 48
+      RECORDS_OFFSET = 52
+
+      # The structural walk is the authority on whether the file is broken;
+      # the gem is a second opinion that may not arrive. A gem exception
+      # cannot tell the two apart -- `described_92.emf` is legal and raises
+      # EOFError, `truncated_117.emf` is damaged and raises IOError -- so
+      # only reading the record stream separates them:
+      #
+      #   valid              []                described_92   []
+      #   after_eof          [trailing_bytes]  truncated_117  [record_framing]
+      #   misaligned_record  [record_framing]  bad_comment    [comment_overrun]
+      def self.report(image)
+        issues = image.with_source { |source| issues_for(bounded(source)) }
+
+        Models::Report.new(
+          source_path: image.path, format: image.format.to_s,
+          validator_version: ::Emf::VERSION, issues: issues
+        )
+      end
+
+      # One byte past the limit is enough to show the stream is over it, so
+      # nothing bigger is read from a file. Content already in memory is
+      # used as it is. `IO#read` answers nil on an empty stream.
+      def self.bounded(source)
+        return source unless source.respond_to?(:read)
+
+        source.read(SCAN_LIMIT + 1) || "".b
+      end
+
+      # Structural findings first, then whatever the delegate managed. Do not
+      # trust the gem's `ok?` alone: a stream cut at a record boundary parses
+      # clean. A nil from the walk means "not examined" -- content over the
+      # limit -- which is a weaker claim than `[]` and must not read as clean.
+      def self.issues_for(content)
+        declared = header_size(content)
+        return [header_framing] unless declared
+
+        walked = EmfStructure.issues(content, declared, SCAN_LIMIT)
+        return [unexamined] if walked.nil?
+
+        structural = byte_count_issues(content) + walked
+        structural + delegate_issues(content, structural, declared)
+      end
+
+      # EMR_HEADER is a record, framed by the same rule as every other --
+      # aligned, at least a record header long, inside the stream -- and its
+      # fixed fields need 88 bytes. So a 109- or 110-byte header fails here.
+      def self.header_size(content)
+        _type, size = EmfRecords.record_at(content, 0)
+        size if size && size >= MINIMUM_HEADER
+      end
+
+      def self.header_framing
+        issue("emf.record_framing", "the EMR_HEADER record declares a size no header can have", offset: 0)
+      end
+
+      # The record walk still has to run when this agrees: `after_eof.emf`
+      # declares 392 and is 392, because the header was rewritten to cover
+      # the bytes after EMR_EOF.
+      def self.byte_count_issues(content)
+        declared = content.byteslice(BYTES_OFFSET, 4).unpack1("V")
+        return [] if declared == content.bytesize
+
+        [issue("emf.byte_count_mismatch",
+               "the header declares #{declared} bytes and the file holds #{content.bytesize}")]
+      end
+
+      # A gem failure is evidence about the VALIDATOR, not about the file.
+      # Where the walk found the stream intact, the honest answer is that
+      # this file was not fully judged -- a WARNING, so `Report#valid`
+      # derives `:suspicious` instead of claiming `:yes` or `:no`. Where the
+      # walk already found real damage, the gem's failure adds nothing and
+      # is dropped rather than restated in weaker words.
+      def self.delegate_issues(content, structural, declared)
+        metafile = parsed(content)
+        return fallback_issues(content, structural, declared, metafile) if metafile.is_a?(::Exception)
+
+        metafile.errors.map { |error| parse_issue(error) } + [count_issue(metafile)].compact
+      end
+
+      def self.parsed(content)
+        ::Emf.parse(content)
+      rescue *MALFORMED => e
+        e
+      end
+
+      def self.fallback_issues(content, structural, declared, error)
+        base = structural.empty? ? [unverified(error)] : []
+        base + [independent_count_issue(content, declared)].compact
+      end
+
+      def self.independent_count_issue(content, declared)
+        expected = content.byteslice(RECORDS_OFFSET, 4)&.unpack1("V")
+        actual = EmfStructure.body_record_count(content, declared)
+        return if expected.nil? || actual.nil? || expected == actual + 1
+
+        issue("emf.record_count_mismatch",
+              "the header declares #{expected} records and #{actual + 1} were read")
+      end
+
+      def self.unexamined
+        Models::Issue.new(
+          severity: "warning", code: "emf.not_examined",
+          message: "the file is larger than the scan limit and was not examined"
+        )
+      end
+
+      def self.unverified(error)
+        Models::Issue.new(
+          severity: "warning", code: "emf.unverified",
+          message: "the record stream is intact but the validator could not read it: #{error.class}"
+        )
+      end
+
+      def self.parse_issue(error)
+        issue("emf.parse_error", error.message.to_s, offset: error.offset)
+      end
+
+      # The count reads `records.size + 1` because the header counts
+      # ITSELF: EMR_HEADER is type 1 in the same record-type space as
+      # every body record, while `Metafile#records` holds only what
+      # follows it.
+      def self.count_issue(metafile)
+        declared = metafile.header.n_records
+        return if declared.nil? || declared == metafile.records.size + 1
+
+        issue(
+          "emf.record_count_mismatch",
+          "the header declares #{declared} records and #{metafile.records.size + 1} were read"
+        )
+      end
+
+      def self.issue(code, message, offset: nil)
+        Models::Issue.new(
+          severity: "error", code: code, message: message,
+          location: offset.nil? ? nil : Models::Location.new(byte_offset: offset)
+        )
+      end
+
+      private_class_method :bounded, :issues_for, :header_size, :header_framing,
+                           :byte_count_issues, :delegate_issues, :unexamined, :unverified,
+                           :parsed, :fallback_issues, :independent_count_issue,
+                           :parse_issue, :count_issue, :issue
+    end
+
+    private_constant :ConformanceMapper
+
+    # The conversion path's own two pieces, kept out of Metafile's body
+    # for the same reason EmfPlus is: this class already carries the
+    # whole header-parse contract, and conversion is a second, unrelated
+    # concern layered on top of it. `module_function` rather than a class
+    # with instance methods -- there is no state to hold between calls.
+    module MetafileConvert
+      # Symbol -> the vectory method it dispatches to. A lookup table
+      # rather than `public_send(:"to_#{to}")`: `to` is already checked
+      # against `convert_targets` before this runs, so nothing
+      # attacker-controlled reaches `public_send` either way, but a
+      # closed table is what a third target (a future `:png` once
+      # vectory gains one) would have to be added to, rather than
+      # trusting every future target's symbol to spell a real
+      # `Vectory::Emf` method.
+      TARGET_METHODS = { svg: :to_svg, eps: :to_eps, ps: :to_ps }.freeze
+
+      # Matches Metafile's own `SCAN_LIMIT` (below) and the underlying
+      # `emf` gem's own `Emf::Emr::Parser::MAX_INPUT_BYTES` -- kept as a
+      # separate constant, not a reference to `Metafile::SCAN_LIMIT`,
+      # because that one is `private_constant` and declared later in this
+      # file. Checked before the delegate ever sees the content: the
+      # gem's own limit runs on `bytesize` *after* the whole file is
+      # already a Ruby String, so refusing here is what actually stops
+      # the parse/render cost from growing on an oversized input --
+      # measured, a 364-byte corrupted EMF was still climbing past 1.2GB
+      # RSS with no cap at all.
+      MAX_CONVERT_BYTES = 200 * 1024 * 1024
+
+      # NOT an exhaustive list of what the delegate chain can raise --
+      # measured otherwise. Originally listed as four explicit classes,
+      # matching the house convention (`PARSE_FAILURES` below,
+      # postscript.rb's `Postscript::ParseError` rescue, png.rb's
+      # `PngConform::Error` rescue). A fuzz of the real fixture found
+      # three real, reachable exceptions outside that list: `IndexError`
+      # from `emfsvg`'s object table on a corrupted CreatePen record,
+      # `IOError`/`EOFError` from `bindata` on a truncated stream, and a
+      # `NameError` that is a genuine bug in `postsvg` 0.3.0's own
+      # autoload (`Postsvg::Model::UnknownOperator` is declared in the
+      # singular `operator.rb`, defined in the plural `operators.rb`),
+      # reachable through any EMF whose rendered SVG embeds a raster
+      # image. None of the three is a defect in THIS file, and this
+      # method's body calls nothing but the delegate chain, so there is
+      # no local bug a wider rescue would hide. Logged as a deviation
+      # from the house convention above -- see
+      # `deviations.md` under this task's entry.
+      module_function
+
+      def run(image, to:, convert_targets:)
+        raise UnsupportedFormat.new(image.format, :convert, target: to) unless convert_targets.include?(to)
+
+        content = bounded_content(image)
+        ConversionEngine.load!
+        converted = convert_content(content, to)
+        build(image, to, content, converted)
+      end
+
+      # Bounds the READ itself rather than trusting a stat taken on a
+      # separate filesystem call -- the same reasoning as `Metafile`'s own
+      # `header_prefix` below, and for the same failure mode: `#bytesize`
+      # and `#content` are two different filesystem operations for a
+      # path-born image, so checking a stat first and only THEN calling
+      # `#content` still materialises the whole, oversized file in memory
+      # before the check can refuse it. Reading MAX_CONVERT_BYTES + 1 and
+      # getting that many back is the proof the stream is over the limit
+      # whatever a stat would have said; getting fewer proves these bytes
+      # ARE the whole stream -- which, unlike inspection's own header-only
+      # prefix, is also the entire content a within-limit conversion needs.
+      def bounded_content(image)
+        content = image.with_source { |source| bounded_read(source, MAX_CONVERT_BYTES + 1) }
+        return content if content.bytesize <= MAX_CONVERT_BYTES
+
+        raise ConversionError, "emf image exceeds the #{MAX_CONVERT_BYTES}-byte convert limit"
+      end
+
+      # Duplicated from `Metafile`'s own private `#bounded_read` rather
+      # than shared across the module boundary: both are three-line pure
+      # functions with no state, and `Metafile`'s copy is a `private`
+      # instance method, reachable only through an instance this
+      # `module_function` module has no reason to hold.
+      def bounded_read(source, length)
+        return source.read(length) || "".b if source.respond_to?(:read)
+
+        source.byteslice(0, length)
+      end
+
+      # Scoped to only the delegate calls, not `build` below -- `build`'s
+      # own `Lossiness.classify`/`Models::Conversion.new` are this file's
+      # local logic, not the delegate chain `rescue StandardError` exists
+      # to cover, so a bug inside `build` surfaces as itself rather than
+      # being relabelled a conversion failure.
+      def convert_content(content, to)
+        ::Vectory::Emf.from_content(content).public_send(TARGET_METHODS.fetch(to))
+      rescue StandardError => e
+        raise ConversionError, "#{e.class}: #{e.message}"
+      end
+
+      # `output_path` is deliberately absent here -- the caller
+      # (`Claricle.convert_one`) does not know the real written path
+      # until after `Writer#write` runs, and `Models::Base` seals (and
+      # therefore freezes) every instance at construction, so it cannot
+      # be set on this instance afterward. The caller builds its own
+      # final `Models::Conversion` once the path is known, copying every
+      # field asserted here.
+      #
+      # Takes `content` rather than re-reading `image.content` -- the
+      # bytes `run` already read via `#bounded_content` are already the
+      # right ones (bounded, and the full stream for anything under the
+      # limit), and calling `image.content` here would silently re-read
+      # the whole file a second time for a path-born image, unbounded.
+      def build(image, to, content, converted)
+        Models::Conversion.new(
+          source_path: image.path,
+          source_format: image.format.to_s,
+          target_format: to.to_s,
+          lossiness: Lossiness.classify(source_format: image.format, target_format: to, source: content),
+          content: converted.content
+        )
+      end
+    end
+
+    private_constant :MetafileConvert
+
+    # Reads an EMF header. WMF is deliberately absent: the released emf
+    # parser reports "WMF parser not yet implemented" (D14), so nothing
+    # registers `:wmf` and it reaches exit 3 through the registry.
+    # The header is parsed by the delegate; the EMF+ marker is found by
+    # walking the record framing here. The delegate is not asked for the
+    # second answer because it cannot give it -- see `EmfPlus.size`.
+    #
+    # `image.bytesize` is a `File.size` stat, and it decides ONE thing:
+    # whether to bother reading past the fixed header. Every other
+    # decision is made from the bytes `header_prefix` actually returned,
+    # because the stat and the read are separate filesystem calls and
+    # the file is free to change between them. A stat reading high only
+    # makes this under-report, which is the safe direction.
+    #
+    # Conformance lives on `ConformanceMapper` above. No lazy require:
+    # `emf` is the detector's one EAGER delegate (D5).
+    class Metafile < Base
+      def conformance_report(image) = ConformanceMapper.report(image)
+
+      formats :emf
+      # png and pdf have no vectory class (04-convert.md); :emf itself is
+      # not a target -- Base's same-format guard in `Claricle.convert_one`
+      # already refuses that before any handler is reached, and
+      # `Vectory::Emf` has no `#to_emf` to route it to regardless.
+      convert_to :svg, :eps, :ps
+
+      # EMR_HEADER's declared size, a 4-byte little-endian value at a
+      # fixed offset. Below the minimum there is no header to read.
+      SIZE_OFFSET = 4
+      MINIMUM_HEADER = 88
+      ALIGNMENT = 4
+      MILLIMETRES_PER_INCH = 25.4
+
+      # Every way this delegate fails on input rather than on a defect.
+      # `Emf::Error` alone, because the delegate is only ever handed a
+      # normalised 88-byte header now: it can no longer be sent reading
+      # past the end, which is what raised `EOFError` and `IOError` when
+      # this took the declared prefix. Fuzzed over 8704 corrupted
+      # headers -- every failure was an `Emf::Error`, none reached an
+      # IO arm. An IOError raised AFTER the parse still propagates, and
+      # a spec pins that.
+      PARSE_FAILURES = [::Emf::Error].freeze
+
+      # The delegate refuses whole streams above this, so the walk does
+      # not go further than the parser it replaces would have. It bounds
+      # the READ as well: nothing beyond one byte past it is ever
+      # materialised, whatever the stat said the file was.
+      #
+      # It does not bound the HEADER. Applying it there turned a
+      # fully framed 209 MB EMF with a perfectly readable 100x50 header
+      # into `failed`, breaking the header-first contract this handler
+      # exists to keep -- the delegate itself parses that header and
+      # refuses only the full stream.
+      SCAN_LIMIT = 200 * 1024 * 1024
+
+      private_constant :SIZE_OFFSET, :MINIMUM_HEADER, :ALIGNMENT, :MILLIMETRES_PER_INCH, :PARSE_FAILURES, :SCAN_LIMIT
+
+      def inspection(image)
+        bytesize = image.bytesize
+        oversized = bytesize > SCAN_LIMIT
+        prefix = header_prefix(image, oversized)
+        declared = declared_size(prefix, oversized ? bytesize : prefix.bytesize)
+        return unreadable(image) unless declared
+
+        header = read_header(prefix)
+        return unreadable(image) unless header
+
+        readable(image, header, emf_plus_bytes(prefix, oversized, declared))
+      end
+
+      # The target guard, the delegate call and the `Models::Conversion`
+      # it builds all live in `MetafileConvert` above -- see its `build`
+      # for why `output_path` is absent from the result.
+      def convert(image, to:) = MetafileConvert.run(image, to: to, convert_targets: self.class.convert_targets)
+
+      private
+
+      # Every byte the rest of the inspection is allowed to rest on, and
+      # never more than SCAN_LIMIT + 1 of them.
+      #
+      # Over the stat's limit that is the fixed header alone: the walk is
+      # skipped anyway, so nothing past the header is worth reading.
+      # Under it, one byte more than the walk can handle. Getting that
+      # many back proves the stream is over the limit whatever the stat
+      # said; getting fewer proves these bytes ARE the whole stream. So
+      # both answers come from the read rather than from a stat taken
+      # before it, and memory is bounded either way.
+      def header_prefix(image, oversized)
+        length = oversized ? MINIMUM_HEADER : SCAN_LIMIT + 1
+        image.with_source { |source| bounded_read(source, length) }
+      end
+
+      # Takes an IO or a String, because `with_source` hands over
+      # whichever the image is made of: an open file for a path-born
+      # image, the bytes already in hand for a content-born one.
+      #
+      # Bounding a String costs nothing when there is nothing to cut.
+      # Measured on 20 MB: a `byteslice` covering the whole string SHARES
+      # it -- 40 bytes of object, no copy -- and only a partial one
+      # copies, which here is the 88-byte header alone. So the String arm
+      # needs no shortcut for the content-born image that is already
+      # inside the bound.
+      #
+      # `IO#read` answers nil at end of stream for a non-zero length --
+      # measured on an empty file -- and an empty stream still has to
+      # reach `declared_size` as a String.
+      def bounded_read(source, length)
+        return source.read(length) || "".b if source.respond_to?(:read)
+
+        source.byteslice(0, length)
+      end
+
+      # Over the scan limit `prefix` is only the fixed header, so there
+      # is no walk to ask for. Under it the question is still
+      # `EmfPlus.size`'s to refuse: a prefix that came back at
+      # SCAN_LIMIT + 1 is a stream over the limit however the stat read,
+      # and that call's own bytesize check is what catches it.
+      def emf_plus_bytes(prefix, oversized, declared)
+        oversized ? nil : EmfPlus.size(prefix, declared, SCAN_LIMIT)
+      end
+
+      # The delegate is handed the fixed 88-byte header with `nSize`
+      # normalised to 88, rather than the declared prefix. Any `nSize`
+      # above 88 makes emf 0.1.0 read the Win95 optional fields --
+      # cbPixelFormat, offPixelFormat and bOpenGL, twelve more bytes --
+      # and above 100 szlMicrometers as well, eight more. So it needs a
+      # full 100 bytes once `nSize` passes 88, and 108 once it passes
+      # 100, which leaves exactly three aligned sizes with no layout it
+      # can map onto: 92, 96 and 104 each raise EOFError. Swept 88 to
+      # 356, on a stream long enough for every one.
+      #
+      # Those three are the ones that matter. A standards-valid header
+      # carrying a short description lands on them, because MS-EMF places
+      # the description directly after the fixed 88 bytes. Measured: a
+      # 92-byte header fails on the declared prefix AND on the full
+      # stream, so re-slicing cannot rescue it.
+      #
+      # Every field reported here lives inside those 88 bytes and `nSize` is
+      # not one of them, so normalising it changes nothing that is read --
+      # verified to agree with the delegate figure-for-figure on the files
+      # it parses natively. The real `nSize` is still validated, by
+      # `declared_size`, before this runs.
+      def read_header(prefix)
+        ::Emf.parse(fixed_header(prefix)).header
+      rescue *PARSE_FAILURES
+        nil
+      end
+
+      # `header_prefix` guarantees BINARY -- an open file in "rb" mode,
+      # the image's own binary content, or `"".b` -- which matters here
+      # because `String#[]=` indexes by CHARACTER, and a UTF-16LE tag
+      # would make this raise on a file the delegate reads correctly.
+      # The caller's string is never written to. `byteslice` returns a
+      # NEW String either way -- measured, a full-cover one SHARES the
+      # buffer at 40 bytes of object while a partial one copies -- and a
+      # shared buffer unshares on the first write, so the `[]=` below
+      # lands on this copy alone. Measured: mutating a full-cover slice
+      # of `"ABCDEFGH"` left the source unchanged.
+      def fixed_header(prefix)
+        header = prefix.byteslice(0, MINIMUM_HEADER)
+        header[SIZE_OFFSET, 4] = [MINIMUM_HEADER].pack("V")
+        header
+      end
+
+      # The declared header size, or nil when the stream does not declare a
+      # usable one. EMF control-record sizes are multiples of four: without
+      # that check an nSize of 109 parses as a header -- the delegate
+      # reports ok? true and the full baseline metadata -- while the record
+      # stream is framed from an impossible offset. This is record framing,
+      # not the nBytes/nRecords/nHandles conformance that item 03 owns.
+      #
+      # `available` is how many bytes the stream is KNOWN to hold, and the
+      # caller supplies it differently on each branch. Under the scan
+      # limit it is `prefix.bytesize`, because there the prefix IS the
+      # read: either the whole stream or SCAN_LIMIT + 1 bytes of it, and
+      # both are lengths the stream really has. Over the limit the prefix
+      # is deliberately only the fixed 88 bytes while a legal header may
+      # declare 108, so `prefix.bytesize` would reject perfectly good
+      # large files; there the stat is the only figure there is. The
+      # residual is that a stat reading high over a short file can still
+      # admit a declaration the file cannot hold.
+      #
+      # Measuring against the stat on BOTH branches was the defect:
+      # measured, a stat of 200 over the 99-byte `declared_100_have_99`
+      # reported `ok` for a header declaring 100, and the walk then began
+      # at offset 100 -- past the real end -- and called that a completed
+      # scan.
+      #
+      # The length guard has to be on `prefix`, not on `available`.
+      # `byteslice(4, 4)` answers nil for a prefix under four bytes and a
+      # short String for one under eight, so an empty or 1-3 byte read
+      # raised `NoMethodError` before any nil `unpack1` could be checked
+      # for -- measured, by stubbing a stat over the limit while the file
+      # underneath is 0, 1 or 3 bytes long. At MINIMUM_HEADER and up the
+      # field is always four bytes, so `unpack1` always gives an Integer.
+      def declared_size(prefix, available)
+        return nil if prefix.bytesize < MINIMUM_HEADER
+
+        declared = prefix.byteslice(SIZE_OFFSET, 4).unpack1("V")
+        return nil if declared < MINIMUM_HEADER
+        return nil if declared > available || !(declared % ALIGNMENT).zero?
+
+        declared
+      end
+
+      def readable(image, header, emf_plus_bytes)
+        Models::Inspection.new(
+          format: image.format.to_s,
+          # `Rect` gives plain Integers, so this is `to_f` on an Integer;
+          # `Integer()` first only so a delegate that starts wrapping them
+          # fails loudly here rather than serialising as a string.
+          width: Integer(header.bounds.width).to_f,
+          height: Integer(header.bounds.height).to_f,
+          dpi: dpi(header),
+          meta: metadata(header, emf_plus_bytes),
+          parse_status: "ok"
+        )
+      end
+
+      def unreadable(image)
+        Models::Inspection.new(
+          format: image.format.to_s,
+          parse_status: "failed",
+          issues: [Models::Issue.new(severity: "error", code: HEADER_ISSUE_CODE,
+                                     message: HEADER_ISSUE_MESSAGE)]
+        )
+      end
+
+      def dpi(header)
+        pixels = size_of(header.device_pixels)
+        millimetres = size_of(header.device_mm)
+        return nil unless measurable?(pixels) && measurable?(millimetres)
+        return nil unless resolution_uniform?(pixels, millimetres)
+
+        (pixels["width"] / (millimetres["width"] / MILLIMETRES_PER_INCH)).round(2)
+      end
+
+      # Positive, not merely non-zero, and on BOTH pairs.
+      #
+      # MS-EMF's SIZEL holds signed 32-bit fields, and the delegate hands
+      # them back signed -- `Size#cx` is a `BinData::Int32le`. A negative
+      # one is not a measurement, and the arithmetic below divides it
+      # happily: measured on `valid.emf`, device_mm -26 x -13 reported
+      # -97.69 dpi, and negating the pixels as well reported a confident
+      # 97.69 out of two nonsense values cancelling.
+      #
+      # Zero is here for two different reasons. Zero millimetres divides
+      # by zero and the answer is Infinity, which `to_json` refuses
+      # outright. Zero pixels divides fine and reported a dpi of 0.0,
+      # which reads as a measured resolution rather than a missing one.
+      def measurable?(size)
+        size["width"].positive? && size["height"].positive?
+      end
+
+      # A cross product, in integers: Float equality would be fragile,
+      # and comparing the AXES rather than the ratios would be wrong.
+      # Our own baseline is 100x50 pixels over 26x13 millimetres --
+      # unequal on both axes, with both ratios at 97.69.
+      def resolution_uniform?(pixels, millimetres)
+        pixels["width"] * millimetres["height"] == pixels["height"] * millimetres["width"]
+      end
+
+      # Coerced because SOME of these are BinData wrappers, which behave
+      # like Integers and serialize as JSON strings. Measured across every
+      # fixture: `Size#cx`/`#cy`, `n_records` and `n_handles` are
+      # `BinData::Int32le`/`Uint32le`/`Uint16le` and render as `"100"`;
+      # `Rect#width`/`#height` are already plain Integers, so `Integer()`
+      # is a no-op there.
+      #
+      # It stays uniform rather than applied selectively: `size_of` serves
+      # both `Rect` and `Size`, and one of them needs it. Splitting the
+      # coercion by shape would make the two callers disagree about a
+      # value the delegate is free to change the class of.
+      def metadata(header, emf_plus_bytes)
+        {
+          "frame" => size_of(header.frame),
+          "device_pixels" => size_of(header.device_pixels),
+          "device_mm" => size_of(header.device_mm),
+          "n_records" => Integer(header.n_records),
+          "n_handles" => Integer(header.n_handles)
+        }.merge(emf_plus(emf_plus_bytes))
+      end
+
+      def size_of(value)
+        width = value.respond_to?(:width) ? value.width : value.cx
+        height = value.respond_to?(:height) ? value.height : value.cy
+        { "width" => Integer(width), "height" => Integer(height) }
+      end
+
+      # Presence and size only, because JSON has nowhere to put packed
+      # binary. It fails LOUDLY on most payloads and quietly on the rest,
+      # and the quiet one is worse. Measured on `emf_plus.emf`'s 40
+      # bytes: `to_json` raises `JSON::GeneratorError` under BINARY,
+      # UTF-8 and UTF-16LE. Measured on `padded_comment.emf`'s four,
+      # where every byte happens to be valid text: it serialises as an
+      # "X" followed by three escaped NULs, which reads like a value and
+      # is really a byte dump -- and under UTF-16LE those same four
+      # bytes come out as TWO characters, half of them silently gone.
+      # A count avoids all of it.
+      #
+      # Three outcomes, not two. A stream the walk never examined carries
+      # NO EMF+ keys at all -- silence is the only honest report for a
+      # question that was not asked, and `false` would be a claim about
+      # bytes nobody read.
+      #
+      # Presence follows the count, so a carrier declaring `cbData` 4 --
+      # the marker and nothing behind it -- reports absent rather than
+      # present-with-nothing. Deliberate: that comment is not valid EMF+,
+      # since the first carrier has to hold an EmfPlusHeader record, and
+      # the delegate offers no better answer to copy. Measured on a
+      # marker-only comment: unpadded it returns nil for `emf_plus`,
+      # which is exactly how it says absent, and padded it returns the
+      # padding -- four zero bytes that are not EMF+ at all.
+      def emf_plus(bytes)
+        return {} if bytes.nil?
+        return { "emf_plus_present" => false } if bytes.zero?
+
+        { "emf_plus_present" => true, "emf_plus_bytes" => bytes }
+      end
+    end
+  end
+end