png_conform 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f40907ca0fa307f62da38b9fecdd97fa05e6f9953315d3bc197a6c1385c1c490
-  data.tar.gz: 27891ced82861b1ff72ac09ef12fcc6801c1f28b46cb849e1a4d6100a6ad9f6c
+  metadata.gz: c3185c558227f8e781d2939e2c5ab3d938e23b2e316b7a4e6dc331e3833a808b
+  data.tar.gz: a34d66c41bed7ef373ee86fd6e492aaee2203c0655884e0f5bfffe8a644e5d3d
 SHA512:
-  metadata.gz: f58ca78ca13ca9934b677118c06cd67d362b96af38863b943dc0f60b757d0685435c450261ee1107d4eebbc5aa95e494c877cf6f55faccccb0dc89fdb0dd9bfc
-  data.tar.gz: 4479d1b4a79ee5d97fc49c297297f11818443e1f7c29e612131520d7037293951488a8fc8ec6af8772d7b49f833d45973ee21817e4bcaa34f98a4f88117818ff
+  metadata.gz: 67ffbca8b2bf76865aae2cf41596e85a3fb3a566b30ae27df8d229f66849a598c5c28bf84e1f36cee4a79d9c7a9eac6adad3ab548a7be669bcc1058709277881
+  data.tar.gz: aee8b3f744dc6f8f6e4fa7cf64077d4174e23fc0a789361f36229a2dc25ecf292eb4fe4662fce7c3b08931d0467c46786a104c91d250a66e34862e67391410f9

data/CONTRIBUTING.md

@@ -147,6 +147,28 @@ bundle exec rspec spec/path/to/spec_file.rb
 COVERAGE=true bundle exec rake spec
 ```
 
+### Diagnostics Goldens
+
+Every fixture under `spec/fixtures` has one structured diagnostics golden
+under `spec/fixtures/diagnostics/`. CI fails if a golden drifts.
+
+```bash
+# Targeted check: corpus spec only
+bundle exec rspec spec/structured_diagnostics/corpus_spec.rb
+
+# Full-corpus verification (non-mutating; also part of the default rake task)
+bundle exec rake diagnostics:check
+
+# Controlled regeneration (writes files)
+script/regenerate_diagnostic_goldens --write
+```
+
+Regenerate only when a rule, report or schema change is intended. After
+`--write`, review the complete `git diff spec/fixtures/diagnostics` and
+confirm every change is explained by your change, then rerun
+`bundle exec rake diagnostics:check` and commit the goldens in their own
+reviewable commit. Never edit a golden by hand.
+
 ### Writing Tests
 
 Follow these principles:

data/Gemfile

@@ -3,6 +3,10 @@
 source "https://rubygems.org"
 
 # Specify your gem's dependencies in png_conform.gemspec
+
+# LensCore main until v1 is released; replace with the
+# released constraint at freeze.
+gem "lens_core", github: "claricle/lens_core", branch: "main"
 gemspec
 
 gem "openssl", "~> 3.0"

data/README.adoc

@@ -328,6 +328,13 @@ $ png_conform check --format json image.png
 }
 ----
 ====
+.Structured diagnostics
+Every JSON and YAML report carries `schema_version` and a `diagnostics` array
+(identity, severity, kind, citation, location, message, context) from the shared
+`lens_core` contract. The legacy `errors` array is kept as a compatibility alias
+for one transition. See `docs/CLI_OPTIONS.adoc` (Structured diagnostics) for the
+full schema, a worked example and the migration notes.
+
 .YAML with errors
 [example]
 ====

data/Rakefile

@@ -7,4 +7,11 @@ require "rubocop/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+namespace :diagnostics do
+  desc "Verify checked-in diagnostics goldens without writing files"
+  task :check do
+    ruby "script/regenerate_diagnostic_goldens", "--check"
+  end
+end
+
+task default: %i[spec rubocop diagnostics:check]

data/TODO.structured-diagnostics/00-overview.md

@@ -0,0 +1,98 @@
+# Issue #9 — Lens-family structured diagnostics
+
+Planning baseline: `origin/main` at `653abae0d16d9533a37a5d5eca40896d3b307993`.
+
+Public requirements and related work: [`png_conform#9`](https://github.com/claricle/png_conform/issues/9), [`svg_conform#100`](https://github.com/claricle/svg_conform/issues/100), [`claricle/lens_core`](https://github.com/claricle/lens_core), and [`emf#37`](https://github.com/claricle/emf/issues/37).
+
+## Plan navigation
+
+- [01 — Adopt the shared contract behind a PNG adapter](01-shared-contract.md)
+- [02 — Catalog every rule and citation](02-requirement-catalog.md)
+- [03a — Convert PNG, APNG, and service emitters](03a-png-apng-emitters.md)
+- [03b — Convert MNG and JNG emitters](03b-mng-jng-emitters.md)
+- [03c — Make orchestration format-aware](03c-format-aware-orchestration.md)
+- [04 — Unify Ruby, JSON, YAML, and text reports](04-report-migration.md)
+- [05 — Pin corpus JSON and the release gate](05-corpus-goldens.md)
+- [Progress and handoff](90-progress.md)
+
+## Problem
+
+`png_conform` currently carries diagnostics through several incompatible representations. Validators add hashes to `ValidationContext`; `ResultBuilder#add_context_messages` then forwards only each message into `ValidationResult`; and `FileAnalysis#to_h` emits a small legacy subset. That path loses chunk offsets and error types before JSON/YAML reporting, while human reporters format the reduced model independently.
+
+Issue #9 asks for the lens-family diagnostic contract: stable identity/kind, severity, a format-native location, spec or profile citation, and machine and human renderings derived from one model. The change must cover every in-scope conformance failure and pin the resulting JSON for the fixture corpus.
+
+The shared schema is not yet a landed dependency. `svg_conform` issue #100 is responsible for defining it in the new zero-dependency `claricle/lens_core` gem (`LensCore`), while the EMF conformance work in issue #37 is on an unmerged feature branch. Existing SVG API and CLI reports also differ and lose fields in adaptation, so neither current SVG shape should be copied as the canonical contract.
+
+## Scope
+
+- Consume `LensCore` from the `claricle/lens_core` git branch published by `claricle/svg_conform#100`, then move to its released dependency when v1 freezes. Do not vendor the contract.
+- Keep a PNG adapter around the shared model so byte offset, chunk type/index, field name, expected value, and actual value can be represented without forcing SVG line/column semantics.
+- Give every active or documented direct-use conformance emitter a stable requirement ID, kind, default severity, and authoritative specification/profile citation; classify reachability before including non-registry source files.
+- Carry the same diagnostic object through validation context, result building, the Ruby API, JSON/YAML, and text reporters without dropping fields.
+- Map all 47 registered format validators—28 PNG/APNG and 19 MNG/JNG—plus shared `BaseValidator` behavior and other proven active/public emitters. Cite ISO/IEC 15948 for PNG plus the MNG 1.0 and JNG specification sections for MNG/JNG findings.
+- Make the active reader/orchestrator path format-aware: recognize PNG, MNG, and JNG signatures, apply each format's own top-level header/data/terminator rules, and prove complete valid and invalid files without cross-format false findings.
+- Pin deterministic structured JSON for all 180 existing PNG fixtures and a small, licensed MNG/JNG fixture set, with a reviewable, check-only regeneration workflow.
+- Document the public Ruby and CLI schemas, compatibility behavior, location semantics, and golden update procedure.
+
+## Exclusions
+
+- Defining, copying, or vendoring a competing family-wide contract inside this repository.
+- Implementing SVG, EMF, or PostScript conformance behavior in this repository.
+- Converting CLI invocation, missing-file, dependency, or unexpected process failures into conformance findings; those remain operational errors unless the shared contract explicitly says otherwise.
+- Changing rule semantics beyond correcting the active path's PNG-only format dispatch and top-level PNG/MNG/JNG sequence checks; auto-remediation behavior, profile policy, and pngcheck-compatible exit status otherwise remain unchanged.
+- Wiring or migrating dormant code merely because it contains emitter-like methods. Card 02 classifies `lib/png_conform/pipelines/`, `Services::ZlibValidator`, `Validators::StreamingIdatValidator`, and the legacy private emitter helpers in `ValidationService`; sources with no registry, require/call, or documented direct-use public contract stay out of the migration.
+
+## Intended end state
+
+- A single immutable diagnostic value is created at the rule boundary and survives unchanged to all report formats.
+- Its serialized shape matches the landed, versioned lens-family contract and includes stable requirement identity, kind, severity, message, structured citation, and an extensible location containing PNG-native context.
+- Human output is rendered from that value; it does not reconstruct meaning from message text.
+- Public report shapes add the canonical diagnostics while compatibility aliases preserve the legacy Ruby/JSON surface for one documented transition.
+- A catalog completeness check covers every active emitter, and corpus goldens make schema, ordering, optional-field, filename, and timestamp changes review-visible.
+
+## Cross-repository prerequisites
+
+1. **Blocking contract prerequisite — `svg_conform#100`:** a reviewed commit must publish the zero-dependency `claricle/lens_core` gem on a consumable git branch, including field names, primitive/optional value rules, deterministic ordering, human-rendering boundary, extensible location/citation representation, and schema version. The png_conform dependency remains pinned to that branch until the LensCore v1 contract freezes; a released v1 is not required to begin this issue.
+2. **Non-blocking family-parity check — `emf#37`:** recheck the EMF integration once it consumes LensCore and demonstrate the same common fields and serialization rules. EMF's current feature branch is useful evidence, but it neither defines nor supplies PNG's runtime contract.
+3. PNG implementation may inventory all format rules and citations while the LensCore branch is pending, but cards 01, 03a–03c, 04, and 05 cannot be accepted against an assumed schema.
+
+## Ordering and parallelism
+
+1. Start card 02’s complete PNG/APNG/MNG/JNG inventory immediately.
+2. Complete card 01 after `svg_conform#100` satisfies the blocking prerequisite.
+3. Cards 03a and 03b depend on cards 01 and 02, and may run in parallel by validator family.
+4. Card 03c follows the shared diagnostic APIs and both emitter conversions; it owns the reader/orchestrator format dispatch and full-file PNG/MNG/JNG integration proofs.
+5. Card 04 follows cards 03a–03c so additive compatibility assertions exercise the final cross-format objects.
+6. Card 05 may source and license the small MNG/JNG fixture set early, but golden generation follows card 04; perform its single reviewed regeneration only after the schema, format dispatch, and rendering policy are frozen.
+
+## Effort
+
+| Card | Work | Estimate |
+| --- | --- | ---: |
+| 01 | Shared contract and PNG adapter | 1–2 engineer-days |
+| 02 | Requirement catalog and citation inventory | 1–2 engineer-days |
+| 03a | PNG/APNG and service emitters | 2–3 engineer-days |
+| 03b | MNG/JNG emitters | 1.5–2.5 engineer-days |
+| 03c | Format-aware readers, orchestration, and full-file integration | 1.5–2.5 engineer-days |
+| 04 | Ruby API and report migration | 1.5–2.5 engineer-days |
+| 05 | Licensed cross-format corpus, goldens, documentation, and release gate | 1.5–3 engineer-days |
+
+The required PNG/APNG/MNG/JNG scope totals **10–17.5 engineer-days**. The total excludes the external wait for the LensCore branch and assumes authoritative specification text and suitable redistributable MNG/JNG samples are available to the implementer.
+
+## Project decisions
+
+1. `claricle/lens_core` is the sole shared-contract source. png_conform consumes its git branch until v1 freezes and never vendors a local copy.
+2. PNG, APNG, MNG, and JNG are all required. All 47 registered format validators are mapped, the active validation path dispatches their distinct signatures and top-level rules, and the golden corpus gains a small licensed MNG/JNG set alongside the 180 PNG fixtures.
+3. Public report changes are additive. Compatibility aliases preserve the legacy surface for one documented transition; this issue does not perform a breaking replacement.
+
+## Planning evidence
+
+- `lib/png_conform/validators/base_validator.rb` creates context hashes with message/severity/chunk/offset.
+- `lib/png_conform/services/result_builder.rb` drops all fields except message when building results.
+- `lib/png_conform/models/validation_error.rb` lacks canonical requirement, citation, and location values.
+- `lib/png_conform/models/file_analysis.rb` defines the current machine representation; `lib/png_conform/reporters/json_reporter.rb` serializes it directly.
+- `ChunkRegistry::VALIDATOR_PATHS` has 47 registered format validators: 28 PNG/APNG and 19 MNG/JNG. `BaseValidator` is shared infrastructure outside that count; `StreamingIdatValidator` is not registered.
+- `lib/png_conform/services/profile_manager.rb` is loaded by the public library and directly exposes profile validation. `validate_chunk_against_profile` emits unknown-profile and prohibited-chunk errors plus undefined-chunk warnings; `validate_file_against_profile` emits prohibited-present and missing-required errors. Those existing semantics must enter the canonical model while their public result keys remain available during the compatibility transition.
+- `ValidationOrchestrator` currently accepts only the PNG signature and unconditionally requires `IHDR`, `IEND`, and `IDAT`. `StreamingReader` likewise recognizes only the PNG signature and stops only at `IEND`; format-specific BinData models establish MNG's `MHDR`/`MEND` envelope and JNG's `JHDR`/`JDAT`/`IEND` envelope.
+- The source tree has 317 candidate diagnostic-emission call sites before reachability filtering, 47 validator specs plus base-validator and registry specs (49 files total), 180 PNG fixtures, no MNG/JNG fixtures, and no diagnostic JSON goldens.
+- `FileAnalysis#to_h` currently emits `severity` and `message` for each error plus optional `chunk_type`, `expected`, and `actual`; `chunk_offset` and `error_type` exist as Ruby readers but are not current JSON keys.

data/TODO.structured-diagnostics/01-shared-contract.md

@@ -0,0 +1,36 @@
+# 01 — Adopt the shared contract behind a PNG adapter
+
+## Purpose
+
+Bind `png_conform` to the zero-dependency `claricle/lens_core` gem defined by `svg_conform#100` without copying SVG-only coordinates or coupling validators to package internals. Preserve the existing `ValidationError` entry points as additive compatibility aliases while making the shared diagnostic the source of truth.
+
+## Work
+
+- Declare the `lens_core` runtime dependency in `png_conform.gemspec` and pin `claricle/lens_core` to the reviewed integration branch through `Gemfile`/`Gemfile.lock` until v1 freezes. Replace the git source with the released v1 constraint at freeze; do not publish png_conform while its installable dependency is unavailable.
+- Require LensCore directly from the dependency. Do not create a vendored or locally reimplemented shared-contract module.
+- Add `lib/png_conform/diagnostics/location.rb` for PNG-native location data: byte offset plus optional chunk type, chunk index, and field. Its shared projection must use only the extension/context mechanism defined upstream.
+- Add `lib/png_conform/diagnostics/citation.rb` only if the upstream contract delegates citation construction to consumers; otherwise wrap the upstream value without changing its keys.
+- Refactor `PngConform::Models::ValidationError` to own/delegate to the shared immutable diagnostic while retaining documented severity predicates, factories, legacy readers, and `#to_s` behavior as compatibility aliases for one documented transition.
+- Add `spec/png_conform/diagnostics/shared_contract_spec.rb` to pin schema version, primitive types, optional-field policy, location projection, stable serialization, and human rendering. Extend `spec/png_conform/models/validation_error_spec.rb` for legacy compatibility.
+
+## Dependencies
+
+- Blocking: `svg_conform#100` publishes the versioned LensCore schema and a consumable `claricle/lens_core` git branch.
+- Non-blocking parity evidence: once EMF #37 consumes LensCore, its contract tests serialize the same common fields. PNG-specific location context may differ.
+
+## Done when
+
+- The dependency points to one reviewed LensCore branch revision, and no second family schema or vendored copy is defined locally.
+- A PNG diagnostic round-trips stable requirement identity, kind, severity, message, citation, and byte/chunk location using JSON-safe primitives.
+- The same object produces machine and human representations, and changing a structured field changes both applicable representations without message parsing.
+- Existing documented `ValidationError` readers and predicates remain available as compatibility aliases for the documented transition.
+
+```bash
+bundle exec rspec spec/png_conform/diagnostics/shared_contract_spec.rb \
+  spec/png_conform/models/validation_error_spec.rb
+```
+
+## Status
+
+State: done
+PR: https://github.com/claricle/png_conform/pull/14

data/TODO.structured-diagnostics/02-requirement-catalog.md

@@ -0,0 +1,37 @@
+# 02 — Catalog every rule and citation
+
+## Purpose
+
+Replace message text as the implicit rule identity with a complete, reviewable registry across PNG, APNG, MNG, and JNG. This card can begin while the upstream schema is pending.
+
+## Work
+
+- Add `config/diagnostics.yml`, keyed by stable requirement ID, with format, kind, default severity, specification/profile name and version, and exact section/clause citation. Keep messages/templates in the catalog only if the shared contract standardizes them there.
+- Add `lib/png_conform/diagnostics/catalog.rb` to load and validate the registry, reject duplicate/unknown IDs, and return typed data for diagnostic construction.
+- Inventory the 47 validators registered in `ChunkRegistry::VALIDATOR_PATHS`—28 PNG/APNG and 19 MNG/JNG—then separately inventory shared findings from `lib/png_conform/validators/base_validator.rb`, direct findings in `lib/png_conform/services/validation_orchestrator.rb` and `chunk_processor.rb`, and the public profile findings from `ProfileManager.validate_chunk_against_profile` and `ProfileManager.validate_file_against_profile` in `lib/png_conform/services/profile_manager.rb`. Inventory any other emitter only when it is proven active or covered by a documented direct-use public contract. Include active informational diagnostics in the one-model migration even though they are not failures.
+- Trace registry membership, `require` edges, call sites, public documentation, and focused direct-use tests for non-registry sources. Record an explicit include/exclude rationale for `lib/png_conform/pipelines/`, `Services::ZlibValidator`, `Validators::StreamingIdatValidator`, and the legacy private emitter helpers in `ValidationService`. Do not wire dormant classes into production or catalog unreachable helper methods just to expand coverage; a non-registry source enters scope only when a direct-use public contract is documented and tested.
+- Assign citations from ISO/IEC 15948 (including the applicable edition), the APNG specification, and the MNG 1.0 and JNG specifications. Profile-only policy findings cite the profile ID/version rather than inventing a normative PNG clause.
+- Add `spec/png_conform/diagnostics/catalog_spec.rb` to prove schema validity, unique IDs, known severities/kinds/formats, citation presence, and complete coverage of the explicit emitter inventory. The inventory must fail when a new emitter lacks a catalog ID.
+- Document non-conformance informational messages separately; do not give success/progress messages fictitious normative citations.
+
+## Dependencies
+
+- Access to the authoritative editions used for clause-level review.
+- The final serializer keys wait on card 01, but stable IDs and source citations do not.
+
+## Done when
+
+- Every active error, warning, and conformance-information path across all 47 registered validators, shared `BaseValidator` behavior, and other proven active/public emitters has one stable catalog ID and an authoritative spec/profile citation appropriate to its format.
+- The catalog distinguishes `ProfileManager.validate_chunk_against_profile` findings for an unknown profile, a prohibited chunk, and a chunk undefined by a profile from `validate_file_against_profile` findings for a prohibited-present chunk and a missing required chunk, with the applicable profile ID/version as the policy citation.
+- Common helper findings remain distinguishable by violated requirement rather than collapsing to one generic length/range/CRC ID.
+- Duplicate IDs, missing citations, unknown metadata values, and uncataloged emitters fail a focused completeness spec.
+- The inventory records a source-backed reachability/public-contract classification for `lib/png_conform/pipelines/`, `Services::ZlibValidator`, `Validators::StreamingIdatValidator`, and the legacy `ValidationService` helper emitters so card 03a has explicit inclusion decisions and no speculative migration work.
+
+```bash
+bundle exec rspec spec/png_conform/diagnostics/catalog_spec.rb
+```
+
+## Status
+
+State: done
+PR: https://github.com/claricle/png_conform/pull/13

data/TODO.structured-diagnostics/03a-png-apng-emitters.md

@@ -0,0 +1,45 @@
+# 03a — Convert PNG, APNG, and service emitters
+
+## Purpose
+
+Create the canonical diagnostic once at each active PNG/APNG rule boundary and carry it without metadata loss through the validation pipeline.
+
+## Work
+
+- Change `ValidationContext` in `lib/png_conform/validators/base_validator.rb` to collect diagnostic values instead of ad hoc hashes. Require a catalog ID at every conformance-diagnostic boundary, explicitly including informational findings; pass dynamic message data, PNG location, and expected/actual context separately.
+- Update the 28 registered non-MNG/JNG validators under `lib/png_conform/validators/critical/`, `ancillary/`, and `apng/` to emit the cataloged requirements from card 02. Convert shared `BaseValidator` behavior separately; it is infrastructure, not a 29th registered validator.
+- Convert the direct active unknown-critical findings in `lib/png_conform/services/chunk_processor.rb`, plus any other non-registry emitter that card 02 proves has a documented, tested direct-use public contract. Card 03c exclusively owns `ValidationOrchestrator` signature, missing-chunk, and top-level ordering findings so format dispatch is changed and tested as one unit.
+- Migrate the active profile-policy emitter in `lib/png_conform/services/profile_manager.rb` without changing its split responsibilities. `validate_chunk_against_profile` must construct canonical diagnostics for an unknown profile, a prohibited chunk, and a chunk undefined by the profile; `validate_file_against_profile` must construct them for prohibited-present and missing-required chunks. Preserve the former method's existing `status`/`message` keys and the latter's `valid`/`errors`/`warnings` keys as compatibility projections for the documented transition; no profile finding may remain string-only internally.
+- Keep `Services::ZlibValidator`, `Validators::StreamingIdatValidator`, and the legacy private emitter helpers in `ValidationService` out of the migration under the current source evidence: the first two have no require/call path, the streaming validator is absent from the registry, and the helper emitters are unused. Do not make them reachable as part of this issue. If card 02 finds an existing documented direct-use contract, add that source to the explicit active inventory and add a focused spec before converting it.
+- Refactor `ResultBuilder#add_context_messages` in `lib/png_conform/services/result_builder.rb` to append each diagnostic intact. Remove severity-specific reconstruction that currently retains only `e[:message]`.
+- Follow card 02’s reachability finding for `lib/png_conform/pipelines/`: adapt an emitter only if an existing public/reachable path is proven; otherwise record the directory as outside the active issue path. Do not create a second diagnostic pipeline by making dormant code reachable.
+- Extend existing validator and profile-manager specs to assert IDs, citations, severity, and applicable absolute byte/chunk locations in addition to message text. In `spec/png_conform/services/profile_manager_spec.rb`, add structured assertions for unknown-profile, prohibited-chunk, and undefined-chunk results from `validate_chunk_against_profile`, plus prohibited-present and missing-required results from `validate_file_against_profile`; keep the existing success examples as preservation checks. Card 03c owns orchestrator and full-file integration assertions.
+- Together with card 03b, make `spec/png_conform/diagnostics/emitter_coverage_spec.rb` enumerate all 47 registered validators so the agreed inventory is explicit and regression-visible.
+
+## Dependencies
+
+- Cards 01 and 02.
+- Card 03b runs in parallel after the shared context/catalog APIs are merged; both emitter cards feed card 03c and are required before card 04.
+
+## Done when
+
+- All active PNG/APNG and shared-service errors, warnings, and conformance-information messages across the 28 registered non-MNG/JNG validators originate as canonical diagnostics with catalog IDs and citations.
+- `ValidationContext` to `ResultBuilder` preserves diagnostic identity, location, expected/actual context, and severity exactly.
+- CRC, unknown-critical, registered compressed-payload, and representative critical/ancillary/APNG failures each have focused structured assertions; card 03c separately proves signature and top-level sequence findings.
+- `ProfileManager.validate_chunk_against_profile` has structured assertions for unknown-profile and prohibited-chunk errors plus an undefined-chunk warning; `ProfileManager.validate_file_against_profile` has structured prohibited-present and missing-required-chunk assertions. Every case proves stable ID, policy citation, severity, message, and the applicable profile/chunk context while preserving current compatibility keys.
+- Dormant non-registry classes and unused `ValidationService` helper emitters are neither wired into production nor counted as migrated unless their pre-existing direct-use public contract is documented and covered by a focused spec.
+- No active PNG/APNG conformance emitter bypasses the cataloged diagnostic constructor.
+
+```bash
+bundle exec rspec spec/png_conform/diagnostics/emitter_coverage_spec.rb \
+  spec/png_conform/validators/base_validator_spec.rb \
+  spec/png_conform/validators/critical \
+  spec/png_conform/validators/ancillary \
+  spec/png_conform/validators/apng \
+  spec/png_conform/services/profile_manager_spec.rb
+```
+
+## Status
+
+State: done
+PR: https://github.com/claricle/png_conform/pull/17

data/TODO.structured-diagnostics/03b-mng-jng-emitters.md

@@ -0,0 +1,34 @@
+# 03b — Convert MNG and JNG emitters
+
+## Purpose
+
+Apply the same contract to the other file formats that `png_conform` publicly advertises, using their own normative specifications rather than mislabeling their requirements as ISO/IEC 15948 rules.
+
+## Work
+
+- Update all 19 validators under `lib/png_conform/validators/mng/` and `lib/png_conform/validators/jng/` to require the stable IDs cataloged in card 02.
+- Preserve MNG/JNG byte offsets, chunk type/index, field context, expected/actual values, severity, and format in the shared location/context projection.
+- Extend the existing MNG/JNG validator specs with structured identity and citation assertions for representative length, field, sequence, and required-chunk failures.
+- Add MNG/JNG emitter coverage to `spec/png_conform/diagnostics/emitter_coverage_spec.rb` so future rules cannot silently return to message-only errors.
+
+## Dependencies
+
+- Cards 01 and 02.
+- Card 03a shares the context/catalog APIs and emitter-coverage spec; coordinate those files while converting the two required format families. Card 03c consumes both emitter cards and owns end-to-end format dispatch.
+
+## Done when
+
+- Every active MNG/JNG conformance error, warning, and information message across all 19 validators uses a stable catalog ID and the applicable MNG 1.0 or JNG specification section.
+- Representative MNG and JNG diagnostics preserve structured format, byte/chunk location, severity, and rule identity through `ValidationResult`.
+- The emitter completeness spec covers the MNG/JNG validator directories and fails on an uncataloged finding.
+
+```bash
+bundle exec rspec spec/png_conform/diagnostics/emitter_coverage_spec.rb \
+  spec/png_conform/validators/mng \
+  spec/png_conform/validators/jng
+```
+
+## Status
+
+State: done
+PR: https://github.com/claricle/png_conform/pull/16

data/TODO.structured-diagnostics/03c-format-aware-orchestration.md

@@ -0,0 +1,38 @@
+# 03c — Make orchestration format-aware
+
+## Purpose
+
+Route complete PNG, MNG, and JNG files through their own signatures and top-level sequence requirements so valid non-PNG inputs do not receive false PNG diagnostics.
+
+## Work
+
+- Give the active reader/orchestrator path one exact signature-to-format dispatch table for PNG (`89 50 4e 47 0d 0a 1a 0a`), MNG (`8a 4d 4e 47 0d 0a 1a 0a`), and JNG (`8b 4a 4e 47 0d 0a 1a 0a`). Preserve the detected format in validation context/result construction; an unknown signature emits its own cataloged signature diagnostic and does not trigger an arbitrary format's required-chunk findings.
+- Refactor `lib/png_conform/services/validation_orchestrator.rb` to dispatch top-level rules by detected format: PNG/APNG requires first `IHDR`, last `IEND`, and at least one `IDAT`; MNG requires first `MHDR` and last `MEND`; JNG requires first `JHDR`, last `IEND`, and at least one `JDAT`. Check actual first/last positions as well as presence, and emit the card 02 catalog IDs and format-specific citations through the canonical constructor.
+- Make `lib/png_conform/readers/streaming_reader.rb` recognize all three signatures and stop at the detected format's outer terminator (`IEND` for PNG/JNG, `MEND` for MNG), rather than rejecting or truncating an otherwise valid MNG/JNG stream. Keep `FullLoadReader` behavior covered so path-based validation continues to parse all three generic chunk streams.
+- Extend `spec/png_conform/services/validation_orchestrator_spec.rb` for each recognized and unknown signature, each format's missing/misplaced header and terminator, PNG's missing `IDAT`, JNG's missing `JDAT`, and the absence of irrelevant cross-format findings.
+- Add proposed `spec/png_conform/readers/format_dispatch_spec.rb`, `spec/integration/mng_validation_spec.rb`, and `spec/integration/jng_validation_spec.rb`. Build minimal complete files with valid CRCs in the focused specs; prove the public full-file path accepts valid `MHDR`/`MEND` and `JHDR`/`JDAT`/`IEND` streams with an empty diagnostic set. Keep `spec/integration/png_validation_spec.rb` as the PNG behavior-preservation proof.
+
+## Dependencies
+
+- Cards 01, 02, 03a, and 03b. This card owns `ValidationOrchestrator` and the reader format-dispatch specs after the shared diagnostic constructor and format validators are available.
+- Card 04 consumes the detected format and canonical top-level findings; card 05 consumes the full-file MNG/JNG integration path for goldens.
+
+## Done when
+
+- Exact PNG, MNG, and JNG signatures select the correct format, while an unknown signature yields a cataloged signature diagnostic without unrelated PNG/MNG/JNG missing-chunk findings.
+- Valid minimal PNG, MNG, and JNG files pass through the public full-file validation path with no diagnostics and the correct reported format.
+- Missing or misplaced PNG `IHDR`/`IEND`/`IDAT`, MNG `MHDR`/`MEND`, and JNG `JHDR`/`IEND`/`JDAT` produce only the applicable stable IDs, citations, severities, and chunk locations.
+- Streaming validation recognizes all three signatures, reads through the applicable outer terminator, and does not stop at an embedded MNG `IEND` before `MEND`.
+
+```bash
+bundle exec rspec spec/png_conform/services/validation_orchestrator_spec.rb \
+  spec/png_conform/readers/format_dispatch_spec.rb \
+  spec/integration/png_validation_spec.rb \
+  spec/integration/mng_validation_spec.rb \
+  spec/integration/jng_validation_spec.rb
+```
+
+## Status
+
+State: done
+PR: https://github.com/claricle/png_conform/pull/18

data/TODO.structured-diagnostics/04-report-migration.md

@@ -0,0 +1,40 @@
+# 04 — Unify Ruby, JSON, YAML, and text reports
+
+## Purpose
+
+Make the canonical diagnostic the only source for public machine and human output while adding it to existing report shapes with compatibility aliases for one documented transition.
+
+## Work
+
+- Update `PngConform::Models::ValidationResult` and `FileAnalysis#to_h` to expose the shared diagnostic projection without rebuilding or discarding fields. Add the upstream schema version at the contract-defined report location.
+- Update `JsonReporter` and `YamlReporter` to serialize that projection with stable diagnostic ordering and explicit absent-field policy. Normalize or omit volatile timestamps and host-specific paths as prescribed by the shared contract.
+- Update `TextReporter`, `SummaryReporter`, `VerboseReporter`, `VeryVerboseReporter`, `QuietReporter`, and `ColorReporter` to call the diagnostic’s human renderer, with reporter-specific filtering/color outside the diagnostic model.
+- Preserve check-command exit behavior: error-severity diagnostics make a result invalid; warnings/info do not. Keep missing-file and unexpected-process failures on the operational error path.
+- Preserve the existing Ruby readers `severity`, `message`, `chunk_type`, `chunk_offset`, `error_type`, `expected`, and `actual` as compatibility aliases for one documented transition.
+- Preserve the JSON fields actually emitted by `FileAnalysis#to_h` today: `severity` and `message`, with optional `chunk_type`, `expected`, and `actual`. Add the canonical diagnostic projection without removing or repurposing those fields. Treat any flattened `chunk_offset` or `error_type` JSON fields as deliberate new additive projections—not legacy keys—and document and pin their exact placement if they are introduced in addition to the canonical location/kind fields.
+- Update `README.adoc`, `docs/CLI_OPTIONS.adoc`, and `docs/ARCHITECTURE.adoc` with the schema/version, a structured example, location/citation semantics, and migration notes.
+
+## Dependencies
+
+- Cards 01 and 03a–03c.
+
+## Done when
+
+- Ruby API, JSON, and YAML expose the same diagnostic identity, severity, kind, citation, location, message, and context with JSON-safe values.
+- Focused model/reporter specs preserve every existing Ruby reader and the current five-field legacy JSON projection, and explicitly assert any newly added flattened `chunk_offset` or `error_type` projection as additive.
+- Text-family reporters render from the same object and preserve their documented filtering/color responsibilities.
+- Error/warning validity and CLI exit status remain covered, including operational failures that are not conformance diagnostics.
+- The documented examples match executable reporter output, identify every compatibility alias, define the transition boundary, and state the schema version.
+
+```bash
+bundle exec rspec spec/png_conform/models/validation_error_spec.rb \
+  spec/png_conform/models/validation_result_spec.rb \
+  spec/png_conform/models/file_analysis_spec.rb \
+  spec/png_conform/reporters \
+  spec/png_conform/commands/check_command_spec.rb
+```
+
+## Status
+
+State: done
+PR: https://github.com/claricle/png_conform/pull/19

data/TODO.structured-diagnostics/05-corpus-goldens.md

@@ -0,0 +1,42 @@
+# 05 — Pin corpus JSON and the release gate
+
+## Purpose
+
+Make the one-time schema transition reviewable and ensure future rule/report changes cannot silently alter diagnostics across the fixture corpus.
+
+## Work
+
+- Add `script/regenerate_diagnostic_goldens` with explicit `--write` and non-mutating `--check` modes. Process fixtures in bytewise sorted repo-relative order and reject unknown options or a dirty/partial target set.
+- Mirror all 180 PNG inputs under `spec/fixtures/diagnostics/pngsuite/` as canonical pretty JSON. Normalize input names to repo-relative paths and follow LensCore's timestamp/optional-field policy so repeated generation is byte-identical.
+- Add a small redistributable fixture set under the proposed `spec/fixtures/mng/` and `spec/fixtures/jng/` paths, with source, license, and expected-validity metadata recorded beside the fixtures. Include representative valid and invalid MNG/JNG structures that exercise their format-specific citations.
+- Mirror the MNG/JNG inputs under proposed `spec/fixtures/diagnostics/mng/` and `spec/fixtures/diagnostics/jng/` paths, and add proposed `spec/structured_diagnostics/corpus_spec.rb` to assert one-to-one cross-format input/golden coverage, parseability, schema version, deterministic ordering, and exact output equality. Include valid files with empty findings and invalid/edge files, using card 03c's format-aware full-file path rather than bypassing orchestration.
+- Perform exactly one intentional `--write` regeneration after cards 01, 02, 03a–03c, and 04 have `State: done` and the shared schema, format dispatch, and rendering policy are frozen. Then review the complete artifact diff once as a dedicated transition step; subsequent CI uses `--check` and never rewrites files.
+- Add the check to the existing Rake/CI path only after its runtime and memory usage are measured. Keep a targeted representative fixture subset for fast local development if the full corpus is too slow, but do not weaken the full CI acceptance gate.
+- Document regeneration and review procedure in `CONTRIBUTING.md`; update fixture counts only through the coverage assertion, not a hand-maintained magic number.
+
+## Dependencies
+
+- Cards 01–04, including card 03c's full-file format dispatch, and a frozen shared schema/ordering policy.
+- Suitable redistributable MNG/JNG samples and recorded license/provenance; the current checked-in corpus contains 180 PNG fixtures and no MNG/JNG fixtures.
+
+## Done when
+
+- Every checked-in PNG fixture and every newly licensed MNG/JNG fixture has exactly one deterministic structured JSON golden, including valid fixtures with no findings.
+- The MNG/JNG fixture metadata records a redistribution-compatible license, source, format, and expected validity, and the set exercises both format-specific diagnostic citations.
+- `--check` detects missing, extra, stale, reordered, schema-incompatible, or host-dependent golden output without writing files.
+- The one-time transition regeneration is isolated for human review, and later CI proves no unreviewed drift.
+- Contributor documentation explains targeted checks, full-corpus verification, and the controlled regeneration command.
+
+```bash
+bundle exec rspec spec/integration/png_validation_spec.rb \
+  spec/integration/mng_validation_spec.rb \
+  spec/integration/jng_validation_spec.rb
+script/regenerate_diagnostic_goldens --check
+bundle exec rspec spec/structured_diagnostics/corpus_spec.rb
+bundle exec rubocop
+```
+
+## Status
+
+State: done
+PR: https://github.com/claricle/png_conform/pull/12

data/TODO.structured-diagnostics/90-progress.md

@@ -0,0 +1,22 @@
+# Progress and handoff
+
+## Current state
+
+- Cards 01–05 are `done`. The structured diagnostics format from claricle/png_conform#9 is adopted end to end.
+- Reports are built on the shared LensCore contract, with the requirement catalog, format-aware orchestration (PNG/MNG/JNG) and canonical report output in place.
+- The corpus has one golden per checked-in fixture under `spec/fixtures/diagnostics/{pngsuite,idot,mng,jng}/`. Each golden is `ValidationResult#to_lens_report(filename: ...).to_h`, with every emitted diagnostic kept and no timestamp.
+- `script/regenerate_diagnostic_goldens` has `--write` and `--check` modes. `bundle exec rake diagnostics:check` runs `--check` and is part of the default `rake` task (spec, rubocop, check), so CI catches drift.
+- `spec/structured_diagnostics/corpus_spec.rb` asserts one-to-one fixture/golden coverage and exact output equality.
+- `CONTRIBUTING.md` documents targeted checks, full-corpus verification and the controlled `--write` regeneration and review steps.
+
+## Next executable action
+
+None for this effort. Regenerate goldens with `--write` only for an intended rule, report or schema change, review the full golden diff, then confirm with `bundle exec rake diagnostics:check`.
+
+## Blockers
+
+None.
+
+## Remaining gaps and risks
+
+- Dormant sources (`Services::ZlibValidator`, `Validators::StreamingIdatValidator`, `lib/png_conform/pipelines/`) remain excluded from the catalog unless a public contract is documented for them.