claricle 0.1.0 → 0.2.0

data/TODO.plan/01-core.md

@@ -0,0 +1,296 @@
+# 01 — Core: models, detection, registry, CLI runner
+
+Can start: now. Everything else builds on this item; it ships with an
+empty registry, so every operation raises `UnsupportedFormat` through
+the real dispatch path until 02. The model shape is settled by D15
+(dimensions), D17 (`parse_status`) and D23 (structural pre-pass) — read
+those before writing `Handlers::Base`.
+
+## Problem
+
+The gem is a placeholder: a Thor CLI whose `validate`/`convert`/
+`compress` commands print "coming soon". Nothing exists to detect
+formats, dispatch to handlers, model results, or map errors to exit
+codes — and the README advertises the fake commands.
+
+## Design
+
+Contracts an implementer must honor (each verified against the real
+dependency where marked ⚙):
+
+- **Errors** (`lib/claricle/errors.rb`): `UnknownFormat` (bytes match no
+  signature), `UnsupportedFormat.new(format, operation = nil)` with
+  message `format :wmf is not supported for convert to :svg` style,
+  `ConversionError`, `InvocationError` (bad arguments, conflicting
+  flags, refused destination — the only thing besides `Thor::Error` and
+  `ENOENT` that maps to exit 2) — all `< Claricle::Error` (moved here
+  from `claricle.rb`).
+- **Models** (`lib/claricle/models/`): lutaml-model `Serializable`
+  classes ⚙ (construct + `to_json`/`from_json` against the installed gem
+  before trusting specs). `Location{byte_offset, byte_length, line,
+  column, chunk, node_path}` all nullable — the offset/length pair is a
+  zero-based half-open range, because issue #1 asks for a byte *range*
+  and a bare offset can't express one. `Issue{severity:
+  error|warning|info, code, message, location}` — `message` is always
+  present, never nil. `Report{source_path, format, issues, profile,
+  validator_version}` — provenance matters once conformance can mean
+  more than one thing, and `source_path` is what lets a batch result be
+  traced back to its input (nil for content-born images; never expose a
+  Tempfile path). `Report#valid` is **derived on read**, not stored, so
+  appending an issue or deserializing JSON can't leave a stale verdict;
+  it decides in D8 order error → warning → else `yes`.
+  `Inspection{format, width, height, dpi, color_space, meta,
+  parse_status, issues}` — see the inspection contract below.
+- **Invariants are enforced, not just described** ⚙: the gemspec
+  constrains lutaml-model to `~> 0.8.32`, currently resolved to 0.8.97.
+  Claricle validates and normalizes on construction AND on
+  deserialization, then deep-freezes the issue collection. Contract
+  specs cover an invalid severity, a missing message, post-build
+  mutation, and inconsistent JSON.
+- **Inspection means "did the metadata parse", nothing more.**
+  `parse_status` is `"ok"` or `"failed"` — Strings, because the model
+  declares a string enum. A Symbol is accepted on construction and reads
+  back as a String ⚙, so compare against `"ok"`, never `:ok`. It replaces
+  a `valid` field outright — `valid` would mean five different things
+  across five delegates, and vectory parses SVG in Nokogiri's default
+  RECOVER mode ⚙, so a repaired malformed SVG would read as valid.
+  Validity claims belong to `conform` alone. An **allowlisted** parse failure gives
+  `"failed"` and exits 0 — the command succeeded in reporting that the
+  file doesn't parse. A fault off the allowlist is not absorbed; it
+  propagates and exits 4. **`parse_status` comes from Claricle's own
+  structural check (D23), never from delegate silence** — measured, a
+  PNG reader yields zero chunks without raising, svg_conform's `base`
+  profile returns no errors for raw binary, and vectory raises on a
+  *valid* dimensionless SVG. "The delegate didn't complain" is not
+  evidence the file parsed.
+- **Detector** (`lib/claricle/detector.rb`): internal --
+  `Claricle::Detector` is a `private_constant`, so
+  `Claricle::Detector` raises `NameError` from
+  outside the gem. `Detector.detect(bytes)` / `Detector.detect_path(path)`
+  are reached through the public `Claricle.detect(source)` (a String or
+  an IO) and `Image.from_path` / `Image.from_content`;
+  `Claricle.detect_path` does not exist. Result: `:png :svg :emf :wmf
+  :eps :ps :pdf` or raise `UnknownFormat`. Load-bearing details, each corrected by execution on
+  2026-08-12 — do not trust the earlier wording, it was wrong:
+  - Normalize `bytes.to_s.b` first (callers hand UTF-8 strings;
+    comparisons must be binary).
+  - `%!PS` + `EPSF` in first line → `:eps` else `:ps`.
+  - **`::Emf.detect_format` raises `Emf::FormatError` on every
+    unrecognised input** ⚙ — verified against emf 0.1.0 with empty,
+    2-byte, plain-text, XML and PNG input; it never returned nil. Wrap
+    the metafile probe in `rescue Emf::FormatError` and continue to the
+    next probe. Rescue that class only, never bare. Without this, every
+    ordinary unknown file becomes exit 4 instead of `UnknownFormat`/3.
+  - **SVG detection is encoding-aware XML root detection, not a
+    regex** ⚙. A 4096-byte binary `<svg` scan rejects input vectory
+    accepts: UTF-16LE+BOM, `<s:svg xmlns:s=...>` prefixed roots, and a
+    root sitting at byte 5028 behind a long licence comment all failed
+    the regex and all parsed fine in vectory 0.12.0. Decode the BOM and
+    XML declaration, resolve the root **QName**, and require the SVG
+    namespace — local name alone would accept a non-SVG `<svg>` in
+    another namespace. Disable external entity resolution and DTD
+    expansion (XXE); a detector must never fetch a URL. Any byte limit
+    on the preamble is a deliberate product restriction, so state it —
+    it is not delegate compatibility.
+  - `:wmf` is still detected even though nothing handles it (D14), so
+    the user gets `UnsupportedFormat`/3 rather than a misleading
+    "unknown format".
+- **Registry** (`lib/claricle/registry.rb`): internal
+  (`private_constant :Registry`); reached through `Image` operations and
+  the `formats` command. It loads every file in `handlers/`, derives
+  `HANDLER_CLASSES` from `Base.subclasses`, and builds the frozen
+  `HANDLERS` map from each class's `supported_formats`;
+  `handler_for(format)` fetches or raises `UnsupportedFormat`;
+  `formats -> [Symbol]` (sorted; feeds 02's `formats` command); no runtime
+  mutation, no test-only APIs.
+- **Handler metadata carries what the registry derives.** Adding a
+  format is one handler class on main: registry discovery is automatic,
+  and `spec/claricle/one_class_per_format_spec.rb` proves that a dropped-in
+  class supplies detection, dispatch, formats output and inbound
+  conversion without another edit. A handler declares its formats, an
+  optional `detect` block, its conversion targets, the **feature-loss
+  rules** for each of those targets (per D23, lossiness is classified per
+  conversion from the source's content, so a handler declares which
+  source features a target discards, not a flat per-edge label), and its
+  canonical file extensions (needed by 04's `--to` inference from an
+  `--output` suffix). The built-in probes remain Detector's ordered,
+  load-bearing prefix/delegate/XML sequence; handler-declared probes are
+  the extension point and run afterwards through `Registry.detect`, so
+  a new format cannot change an existing format's verdict. Capabilities
+  are derived from the operations the handler overrides, not declared.
+- **Handlers::Base** (`lib/claricle/handlers/base.rb`): internal
+  (`private_constant :Handlers`) -- a handler is a
+  subclass of it, never called by name from outside the gem.
+  `formats(*syms)`
+  class macro is pure declaration; instance `inspection(image)`,
+  `conformance_report(image)`, `convert(image, to:)` all raise
+  `UnsupportedFormat` (interpolate `to` into the message — unused-arg
+  lint otherwise).
+- **Image** (`lib/claricle/image.rb`): `from_path` (detects),
+  `from_content(content, format: nil)` (detects when format omitted);
+  `#content` lazy-reads; ops dispatch through the registry;
+  `#with_path { |p| }` yields the real path or a binmode Tempfile
+  (auto-cleaned) for content-born images — `require "tempfile"` is
+  load-bearing (stdlib, NOT autoloaded ⚙).
+- **CLI + Runner** (`lib/claricle/cli.rb`): stubs deleted, `version`
+  kept, nested `Runner` module maps `run(argv)` → exit code:
+  dispatch Thor directly so `Thor::Error` and operation failures reach
+  the map. Thor's public `start` treats every `Errno::EPIPE` as success,
+  even one raised by a command's own work; only actual `help` and
+  `version` output tolerates a closed consumer. Validate argv before
+  dispatch so malformed or non-ASCII-compatible text is an invocation
+  error rather than an internal encoding failure.
+  `Thor::Error`/`Errno::ENOENT`/`InvocationError` → 2,
+  `UnknownFormat`/`UnsupportedFormat` → 3, other `StandardError` → 4,
+  **`LoadError` → 4 and `SystemStackError` → 4, both caught
+  explicitly** — neither is a `StandardError`, so a missing lazy
+  delegate or a deeply recursive PostScript file would otherwise escape
+  as process status 1, the code reserved for nonconformance. Recursive
+  PS through `Vectory::Ps#to_svg` was measured raising
+  `SystemStackError`. Catch `ScriptError` and `SystemStackError`
+  narrowly; never rescue `Exception`.
+  Never blanket-map `ArgumentError`: a delegate raising one
+  accidentally is an internal defect, not bad user input. Split into
+  `run` / `exit_code` / `error_message` to stay under
+  `Metrics/MethodLength`. `Runner.run` **returns** an integer and never
+  calls `exit`; only `exe/claricle` exits, via
+  `exit Claricle::Cli::Runner.run(ARGV)`. `run` does rescue `SystemExit`
+  and return its status, bounded to 0-255 with anything outside becoming
+  4 — that replaced the original prescription's "no `SystemExit`
+  passthrough". Nothing is thrown through the runner either way, and
+  03's nonconformant exit 1 stays a returned integer like every other
+  code. Normalize exception messages to UTF-8 before reporting them so
+  a delegate's differently encoded message cannot replace its mapped
+  status with an `Encoding::CompatibilityError`.
+- **Tooling**: gemspec floor `>= 3.3.0`, add `emf` + `lutaml-model`
+  (only what 01 uses; 02 adds the rest) with three-segment constraints
+  on the reviewed line — `~> 0.7` is not a pin, it admits every 0.x
+  (D13), and this gem commits no lockfile. `.rubocop.yml`
+  `TargetRubyVersion: 3.3` + `Metrics/BlockLength` exclude `spec/**/*`
+  (rubocop-rspec isn't wired in); CI matrix `['3.3', '3.4', '4.0']`, extended
+  to the newest stable Ruby the gemspec actually admits.
+- **Tooling outcome.** `rexml` also joined `emf` and `lutaml-model`,
+  because `detector.rb` requires it directly. No direct runtime
+  dependency forces 3.3: measured, `emf` 0.1.0 asks `>= 3.1.0`
+  and the current lutaml-model resolution, 0.8.97, asks `>= 3.0.0`,
+  while `rexml` 3.4.4 asks
+  `>= 2.5.0` and Thor 1.2.0 asks `>= 2.0.0`. The 3.3 project floor is a
+  deliberate policy, not a delegate constraint. Thor's floor is 1.2:
+  1.0 and 1.1 reference the removed `DidYouMean::SPELL_CHECKERS` and
+  fail on supported Ruby 3.4.
+- **Honesty baseline**: README.adoc and the gemspec description
+  describe reality as of 01 — the pre-01 README advertised validation,
+  conversion, compression and a fictional
+  `Claricle::Validator` API, and the gemspec advertises compression.
+  Later items extend this baseline; 04 does the final rewrite. Merged
+  source should never claim capabilities it lacks, release or no
+  release.
+- **Require order is load-bearing for one pair only.** Every file under
+  `lib/` loads standalone except `lib/claricle/cli.rb`, which names
+  `Thor` at class-definition time and raises `uninitialized constant
+  Claricle::Thor` unless `thor` was required first — so `lib/claricle.rb`
+  requiring `thor` ahead of `cli` is a real dependency, not reading
+  order. `detector`, `image`, `registry`, `errors`, `handlers/base` and
+  the models each load on their own, and `lib/claricle.rb` may require
+  them in any order. `detector` is standalone only as far as loading
+  goes: it does not require `errors`, so raising `UnknownFormat` needs
+  `errors` already loaded. That replaced the original prescription
+  (thor, emf, lutaml/model, version, errors, models, detector,
+  handlers/base, registry, image, cli), which existed because every file
+  relied on the entry point to have loaded its constants first.
+  `registry.rb` requires `handlers/base` itself, next to the
+  `HANDLER_CLASSES` entries that name those classes; `detector.rb`
+  requires `emf` and `rexml`; `models/base.rb` requires `lutaml/model`.
+
+## Do
+
+TDD each step (failing spec → implement → green → rubocop → commit,
+subjects in quotes):
+
+1. Tooling floor + gemspec deps; `bundle install` must resolve against
+   released gems (D13). "chore: raise floor, add emf and lutaml-model"
+2. Error taxonomy + spec. "feat: add error taxonomy"
+3. Models + derived tri-state spec + JSON round-trip spec + invariant
+   specs (invalid severity, nil message, post-build mutation,
+   inconsistent JSON); run the lutaml-model validation contract check in
+   `bin/console` first against the constrained line (`~> 0.8.32`, current
+   resolution 0.8.97).
+   "feat: add unified issue and report models"
+4. Detector + spec. Fixtures: smallest real `.emf`/`.wmf` from the emf
+   corpus into `spec/fixtures/detector/`; inline byte strings for the
+   rest. Must include the cases the old regex failed — UTF-16LE+BOM,
+   `<s:svg>` prefixed root, internal DTD subset, root behind a
+   5000-byte comment — plus rejection cases: an `<svg>` in a foreign
+   namespace, an `<svg` decoy inside a comment, and an entity referring
+   to an external file (must not be fetched). Assert that plain text
+   reaches `UnknownFormat` and PNG bytes detect as `:png` — neither may
+   leak `Emf::FormatError`, which both trigger on the metafile probe.
+   "feat: add format detector"
+5. Registry + Base + specs (anonymous subclasses are fine — real
+   classes, not doubles). "feat: add handler registry and base class"
+6. Image + spec (tempfile lifecycle both directions; the
+   "no handler registered" example must be replaced in 02 with an
+   explicitly-passed unregistered format). "feat: add image entry object"
+7. CLI rebuild + Runner + spec (version → 0, unknown command → 2,
+   `LoadError` → 4, `InvocationError` → 2, all three stubs gone).
+   "feat: rebuild cli with exit-code runner"
+7b. Honesty baseline: README.adoc and the gemspec description
+   describe only what exists; `sig/` is deleted rather than kept
+   honest, because RBS is not maintained here.
+   "docs: describe only shipped behaviour"
+8. Final wiring; full `bundle exec rake`; execution-diff against main —
+   `bundle exec exe/claricle version`, `bundle exec exe/claricle help`,
+   `bundle exec exe/claricle validate x.png; echo $?`, on BOTH revisions
+   (bare `exe/` can't resolve `lib/` from a checkout).
+   "chore: finalize core wiring"
+
+## Done when
+
+- [x] `bundle exec rake` green on a clean install.
+- [x] `bundle exec exe/claricle version` → 0; `bundle exec exe/claricle
+  nope; echo $?` → 2; stub commands absent from `claricle help`.
+- [x] Runner spec covers every row of the exit-code matrix including 4
+  (a raised `StandardError` that is not a `Claricle::Error`); 03
+  exercises 4 end-to-end through a deliberately faulting handler
+  raising an off-allowlist exception. A real crashing delegate is the
+  wrong probe — once the allowlists exist, a corrupt fixture is
+  nonconformance and exits 1. `spec/claricle/cli_spec.rb` covers these with
+  the missing-file and directory examples (2), unknown and unhandled
+  format examples (3), nonconformant format examples (1), and the two
+  "exits 4 when the handler raises outside its allowlist" examples
+  (conform and convert) through `spec/fixtures/faulting_handler/boom.rb`, #63.
+- [x] `Report#valid` spec covers info-only and warning-plus-info inputs,
+  proves the frozen issue collection refuses mutation rather than
+  silently accepting it, and proves the verdict is correct after a
+  deserialization round trip.
+- [x] The detector's SVG contract is stated as what it accepts, not as
+  parity with vectory — vectory is not a dependency of this item, so a
+  parity claim cannot be measured here. It accepts a root carrying the
+  SVG namespace within `SVG_PROLOG_BYTES`; a foreign namespace, a decoy
+  and a namespace-less root are all refused, and no external entity is
+  ever resolved. Both bounds are real divergences from a permissive XML
+  reader, not formalities ⚙: REXML parses a valid SVG behind a
+  comment longer than `SVG_PROLOG_BYTES` (8192; pinned on both sides by
+  `spec/claricle/detector_spec.rb`, examples "accepts a root that ends on
+  the last byte of the bound" and "rejects the same root one byte beyond
+  the bound"), and behind no comment at all with the namespace dropped,
+  that `Claricle.detect` refuses in both cases.
+- [x] (one-time check, now complete) Execution-diff vs main shows ONLY: stubs gone, version unchanged,
+  README and gemspec truthful.
+- [x] (PR-time record, superseded by CI) Every ⚙ contract check ran against the installed gem and its outcome
+  is recorded in the PR description. `Emf.detect_format` raising, the
+  SVG root cases, lutaml-model's deferred validation and `tempfile`'s
+  non-autoloading are the known ones; treat any new delegate assumption
+  the same way.
+- ~~Full Pre-Push Review Chain passed.~~ Superseded: Hassan 2026-10-09 requires TDD, only changed specs, and green GHA; no extra review chain.
+
+## Files
+
+`claricle.gemspec`, `.rubocop.yml`, `.github/workflows/main.yml`,
+`lib/claricle.rb`, `lib/claricle/errors.rb`, `lib/claricle/models/
+{base,free_form_hash,location,issue,report,inspection}.rb`,
+`lib/claricle/detector.rb`,
+`lib/claricle/registry.rb`, `lib/claricle/handlers/base.rb`,
+`lib/claricle/image.rb`, `lib/claricle/cli.rb`, `exe/claricle`,
+`README.adoc`, `spec/claricle/*_spec.rb`,
+`spec/fixtures/detector/`.

data/TODO.plan/02-inspect.md

@@ -0,0 +1,163 @@
+# 02 — Inspect: five handlers, `claricle inspect`, `claricle formats`
+
+Can start: after 01. D14 (WMF) and D18 (EMF+) settle what this item
+registers.
+
+## Problem
+
+Core dispatches to an empty registry. Nothing can read metadata from
+any format, and the CLI has no operation commands.
+
+## Design
+
+Delegate entry points (verified against the real gems 2026-08-10; the
+delegates are path- or content-oriented as noted):
+
+| Handler (formats) | Delegate call | Metadata source |
+|---|---|---|
+| `Handlers::Png` (`:png`) | A chunk **reader**, not the validator — `PngConform::Readers::StreamingReader` is the entry point actually used -- `FullLoadReader` was measured first but is `read_until: :eof`, so it reads past `IEND`, owns and leaks the file it opens, and rejects a Pathname. The streaming reader stops at `IEND` and closes its own file. The handler does not call `each_chunk`: it drives `reader.io` by hand, so it can read an 8-byte header and decide before touching a payload, which is what bounds the read. Measured — `open` raises nothing on a signature followed by 0 to 4 junk bytes, it just leaves the IO at byte 8, so "no exception" cannot mean `parse_status: "ok"` — require a readable `IHDR` before declaring success. Routing inspection through `ValidationService` would make `inspect` mean conformance for PNG and metadata for everything else | `IHDR`: width/height/bit depth/colour type; `pHYs`: dpi |
+| `Handlers::Svg` (`:svg`) | **Amended 2026-08-21: the slice shipped with no delegate at all.** `Detector.read_root(source)`, with the source handed over by `image.with_source` — the detector already owns the 8192-byte bound, the ATTLIST precedence and the reference resolution, so a second reader would have to agree with all three forever. vectory is not in the gemspec. The original row's `Vectory::Svg.from_content(image.content)` was measured, then not taken: a heavyweight dependency and the whole file in memory to reach the root's attributes. What that measurement settled still holds — dimensions are nullable, and `parse_status` comes from Claricle's own structural check (D23), here an affirmative root start event, never from a delegate staying quiet. **Scope is the root prefix**: nothing past the root start tag is parsed — the 8192-byte bound is read either way — so a document malformed only after that tag reports `ok`. Whole-document well-formedness is conformance (D16, item 03), and it would cost the bounded read — 64.0 MiB SVG, +0.8 MiB against +64.5 MiB. Values get XML's **CDATA** attribute normalization and only that: a literal tab, CR or LF becomes a space, a character reference keeps its character. The non-CDATA trim-and-collapse is deliberately skipped — the type lives in the DTD, SVG's DTD is external, and a bounded reader can neither fetch it nor should, so implementing the internal-subset half would be right for a locally declared `NMTOKENS` and wrong for the same attribute declared externally | width/height (nullable); root attributes into `meta` |
+| `Handlers::Metafile` (`:emf` only) | `::Emf.parse(image.content)` | header `bounds` and `frame`, both `Emf::Model::Geometry::Rect` with `width`/`height` helpers, **plus `device_pixels` and `device_mm`**, both `Emf::Model::Geometry::Size` (`cx`/`cy`). Measured on our fixture: bounds 100x50, frame 2645x1322, device_pixels 100x50, device_mm 26x13. **Amended twice on 2026-08-20** — an earlier amendment claimed there was no device accessor, which was my own false contract: I probed `device`/`millimeters` and concluded from the wrong names. The original row was right. Also available: `n_records`, `n_handles`, `description` (nil on our fixture). `metafile.emf_plus` was nil on our fixture, and when present it is packed binary — putting it straight into `meta` risks `JSON::GeneratorError`, so expose presence, byte size and optionally Base64, never the raw bytes ⚙ confirm against a real EMF+ file before writing the spec |
+| `Handlers::Postscript` (`:eps, :ps`) | **Amended 2026-08-20: vectory is not needed here.** `::Postscript.parse(src).header` exposes `bounding_box` directly, returning `[0.0, 0.0, 100.0, 50.0]` — the same Floats vectory gave, from a delegate already required for the DSC data. Taking vectory would add a heavyweight dependency for a number we already have, which is the reasoning the SVG slice settled. The header also carries `hires_bounding_box`, `title`, `creator`, `creation_date`, `epsf`, `language_level`, `page_count` and `custom`. D22 is untouched: a successful parse still says nothing about conformance. **Amended again 2026-08-21, after building it:** `epsf` is never populated even for a genuine EPSF header; the page fields are populated only by the two-argument `%%Pages: n m` form; and `custom` is the bucket of comments 0.2.0 could NOT read, so all three stay out of `meta`. 0.2.0 is also last-wins on repeated header comments where DSC gives the FIRST one precedence, so every published value is checked against the first declaration's own text | dims from `hires_bounding_box`, falling back to `bounding_box`; the header comments 0.2.0 populates reliably into `meta` |
+| `Handlers::Pdf` (`:pdf`) | `Pdfrb::Document.open(path)` via `image.with_path`. **Amended 2026-08-20, two corrections on pdfrb 0.7.23:** `version` holds (`"1.4"`), but there is **no `page_count` method** — `pages` returns a `Pdfrb::Document::Pages` and the count is `pages.count`, so a handler written from the original row raises `NoMethodError`. **Amended again 2026-08-21: the MediaBox claim above was wrong, and it is what pulled dimensions into this row.** `page[:MediaBox]` is a `Rectangle`, but a `Rectangle` is not evidence a rectangle was declared — pdfrb coerces every element with `to_f` and pads what is missing, so `[0 0]` reads back as a 0x0 page and `[0 0 null 100]` fabricates a coordinate. `page.media_box`, the accessor that resolves inheritance, **hangs forever** on a self-referential `/Parent`; `pages.first` walks `/Kids` with no cycle guard and resolves references by object number alone; and `pages.count` reports the DECLARED `/Count` verbatim, so one leaf page declaring `/Count 999` reports 999. **Dimensions are therefore deferred** — see `docs/plans/inspect-pdf.md` for the eleven rounds of measurements and what a future pdfrb must offer before they are revisited. It **opens a structurally broken PDF without complaint**, so a successful `open` cannot by itself yield `parse_status: "ok"`; the status comes from Claricle's structural pre-pass (D23), consistent with 01 | version; **declared** page count. **Amended 2026-08-28:** `pages.count` is unusable for it -- measured, it is sometimes the declared `/Count`, sometimes computed by walking `/Kids`, and it raises `SystemStackError` on a self-cycling `/Kids` tree whose `/Count` is absent. The handler reads `/Count` RAW off the page-tree node instead, through `.value[:Count]`, because the typed subscript coerces and mutates the node in place. Dimensions deferred |
+
+Every row above was executed against a real fixture on 2026-08-13, and
+**re-measured on 2026-08-20 against emf 0.1.0, postscript 0.2.0, pdfrb
+0.7.23 and vectory 0.12.0** — three rows had drifted and are amended
+above. See the measured-contracts section in 00. Re-run them if a
+delegate version moves; that section exists because six
+confidently-asserted contracts turned out false, and this round found
+three more.
+
+The SVG row's 2026-08-21 amendment is not one of those three. Nothing
+had drifted there: the slice was built and chose to drop the delegate,
+so the row now records what shipped.
+
+The repo had no PDF fixture, so the PDF slice builds one: a minimal
+PDF 1.4 with a catalog, a pages node and a single page -- sufficient for
+this handler's structure gate, not structurally valid in the full sense.
+**Amended 2026-08-28:** the page carries NO `/MediaBox` -- pdfrb's
+own validator reports "Page 3 has no /MediaBox" -- because this slice
+reports no dimensions, so there is nothing for a box to feed. The
+earlier "200x100 page" described a fixture that was never built.
+
+- **WMF is out (D14).** Released `emf` 0.1.0 raises `WMF parser not yet
+  implemented`, so `Handlers::Metafile` claims `:emf` alone. The
+  detector still returns `:wmf`; with no handler registered it raises
+  `UnsupportedFormat` → exit 3. That needs its own spec: a real WMF
+  fixture is recognised and refused, not reported unknown.
+
+- Handlers must reference delegates with `::` — `Claricle::Handlers::X`
+  shadows top-level constants (`Emf`, `Postscript`).
+- Heavy delegates are `require`d lazily inside each handler (D5).
+- `capabilities` is **derived** from the operations a handler overrides
+  on `Handlers::Base`, not declared by a macro. **02 yields `inspect`
+  only** — nothing else is implemented, so `formats` cannot advertise
+  it. 03 and 04 extend it by implementing the operations (see 00's
+  capabilities rule).
+- `Inspection#parse_status` is `"ok"` or `"failed"` — "did the metadata
+  parse", never a validity claim (01's inspection contract). An
+  **allowlisted** parse error becomes `"failed"` plus one
+  `Issue{severity: "error"}` and still exits 0; a fault off the
+  allowlist propagates and exits 4, so a genuine bug in a delegate is
+  never disguised as a tidy `"failed"` result. A clean parse is `"ok"`
+  with no issues. Handlers do NOT run a second validation pass here,
+  and PNG must not route inspection through the conformance validator
+  just because it has one — that would make `inspect` mean something
+  different for PNG than for everything else.
+  Codes reuse the scheme 03 formalizes, so 03 extends this mapping
+  instead of replacing it. `dpi`/`color_space` nullable where the
+  format has none. Note that a `"failed"` inspection still exits 0.
+- New deps in gemspec as item 02's handlers land: `png_conform`,
+  `postscript`, `pdfrb` — three-segment constraints on the reviewed line
+  (D13), not a floating `~> 0.x`. Locally installed and reviewed:
+  png_conform 0.1.4, postscript 0.2.0 and pdfrb 0.7.23, with PDF behavior
+  re-verified on 0.7.49, which resolves here. The earlier plan's
+  `png_conform ~> 0.7` figure was wrong and contradicted this list.
+  `svg_conform` belongs to item 03 and `vectory` to item 04; neither is
+  introduced here. Item 04's `vectory → emfsvg` chain will bring
+  `libpng` transitively, so no direct dependency is planned (D5). Verify
+  Bundler resolution.
+- CLI: `claricle inspect FILE [--json]`; human output prints format,
+  dimensions, each populated metadata field one per line, the
+  `parse_status`, and every issue — a delegate that failed to parse
+  shows up there and nowhere else, so omitting it would print a
+  blank-looking success. JSON uses lutaml-model `to_json`, and empty
+  collections must still serialize as `[]` rather than being omitted —
+  lutaml-model drops them by default unless the mapping says otherwise.
+  Dimensions follow settled D15: numeric values are normalised, and
+  cross-format dimension equality is never asserted. `claricle formats` prints the format ×
+  operation matrix (human + `--json`). `formats --json` is an array of
+  `{"format": "svg", "inspect": true, "conform": false, "convert":
+  false, "convert_to": []}` objects, sorted by format — the keys stay fixed across items, so
+  03 and 04 flip booleans and fill `convert_to` without reshaping the
+  schema. Missing file → exit 2 (runner spec example deferred from 01
+  lands here).
+- Registry: `registry.rb` loads every file in `handlers/` and derives
+  `HANDLER_CLASSES` from `Handlers::Base.subclasses`, so each of the five
+  handlers is introduced by its own file without a second registration
+  edit. A missing handler file is the silent case, and item 02 catches it
+  by asserting the exact expected format set rather than a
+  self-consistency check. Replace
+  01's "no handler registered" spec example with
+  `from_content("x", format: :unregistered)`.
+
+## Do
+
+Plumbing first, then one handler per commit. The order matters: the
+`formats` command has to exist before any handler can be truthful in
+it, and after that every handler arrives as a complete slice.
+
+1. Add deps; verify resolution.
+2. `capabilities` derivation on `Handlers::Base` + `formats` command +
+   spec against the still-empty registry (prints no formats).
+3. `inspect` command + `--json` + missing-file exit-2 spec, still
+   against the empty registry.
+4. One handler per commit, each commit carrying the whole slice: the
+   handler class (its capabilities are derived from the operations it
+   overrides, not declared — a declaration can advertise an operation
+   that is still `Base`'s raising stub), its `require` in
+   `registry.rb`, its `HANDLER_CLASSES` entry, its
+   spec against a real fixture, and the `formats` expected-output
+   update. **Amended 2026-08-28, PDF only:** its fixtures are
+   GENERATED by `spec/support/pdf_builder.rb` rather than committed. A
+   PDF's xref offsets depend on every byte before them, so a committed
+   corpus is 60-odd opaque blobs no reviewer can check, and one of them
+   would be a 120 KB file whose whole purpose is to assert a
+   `SystemStackError`. No commit ever advertises an operation it didn't ship.
+5. Replace 01's "no handler registered" spec example.
+6. README section for `inspect` and `formats` (D1) — real commands
+   only, no forward promises.
+
+## Done when
+
+- [x] `Claricle::Image.from_path(f).inspection` returns a populated
+  `Inspection` for a real PNG, SVG, EMF, EPS, PS, and PDF fixture --
+  the PDF one generated rather than committed, per the amendment above.
+  `PdfBuilder`-generated PDFs (`spec/claricle/cli_spec.rb`, example
+  `inspects a PDF through the real detector`); the two committed PDFs are
+  gone and `spec/support/inspect_fixture.rb` builds them at spec time (#67).
+- [x] A real WMF fixture is detected as `:wmf` and refused with exit 3
+  (D14; `spec/claricle/cli_spec.rb`, example
+  `exits 3 for a detected format with no handler`).
+- [x] `claricle inspect`/`claricle formats` work in human and JSON modes;
+  exit codes verified (0 / 2 missing file / 3 unknown format).
+- [x] `formats` reports each format's true operations. Originally
+  "`inspect` only"; once 03 and 04 shipped that was no longer true, and
+  `spec/claricle/cli_spec.rb`, example
+  `claims conform and convert only where a handler implements them`,
+  asserts the per-format truth (D22: eps/ps have `convert` but not
+  `conform`).
+- ~~Full Pre-Push Review Chain passed.~~ Superseded: Hassan 2026-10-09 requires TDD, only changed specs, and green GHA; no extra review chain.
+
+## Files
+
+`claricle.gemspec`,
+`lib/claricle/handlers/{png,svg,metafile,postscript,pdf}.rb`,
+`lib/claricle/handlers/base.rb` (capabilities),
+`lib/claricle/registry.rb` (handler requires + class list),
+`lib/claricle/cli.rb`,
+`README.adoc`, `spec/claricle/handlers/*_spec.rb`,
+`spec/claricle/cli_spec.rb`, `spec/fixtures/`,
+`spec/support/pdf_builder.rb` and `spec/support/pdf_objstm_builder.rb`
+(the generated PDF corpus).