Media capabilities and optimizer strategy

The README capability matrix separates inventory, probing, review evidence, byte validation, production, and apply. This page records the evidence behind those cells and the existing optimizer direction; it adds no runtime capability or execution authority.

Evidence snapshot

Reviewed on 2026-09-17 against OptiFlow 5be461c413fc34515cd70f41d4178eb8243525d9, after PR #82 merged. The matrix describes merged source, not the installed-release surface. The v0.1.0 tag predates the media-profile and PNG candidate modules, while current Cargo.toml still declares 0.1.0. A version string alone does not prove these later capabilities are present in a binary; consult its release/source provenance.

✓ means implemented at this source pin, ~ means conditional or a limited subset, P means roadmap-only, and — means no implementation or selected format-specific profile. Planned evaluation does not promise support.

Inventory and exact duplicates

Any readable regular file can participate, including unknown formats and files with missing or misleading extensions. Discovery policy, readability and stable observation still apply; a failed observation is not accepted evidence. Format recognition is unnecessary for inventory and exact grouping.

Current exact groups require equal logical byte length and equal complete BLAKE3-256 hashes. This is review evidence, not a byte-by-byte comparison made at deletion time. A future destructive action must revalidate identity/content and directly compare bytes. Hard links, independent copies, logical bytes, allocated bytes and uncertain reclaimability remain distinct.

Pinned implementation: discovery, handle observations, inventory, duplicate analysis, and review planning. The safety model describes the future apply gate.

Classification and optional probing

The scanner classifies an up-to-8192-byte prefix with the locked infer dependency. MIME classification must be image, audio or video before the built-in ffprobe path is considered. Probing must also be enabled, the provider must be available, and its bounded invocation/result must succeed. Unknown/other classifications remain inventory candidates but are not probed. Changing a filename extension does not bypass this gate. See the pinned classification and dispatch, lockfile, and ffprobe adapter.

The locked infer 0.22.0 implementation includes recognizers for PNG, JPEG, GIF, WebP, JPEG XL, AVIF, HEIF and TIFF, plus some RAW signatures such as Canon CR2. This is eligibility evidence, not a stable format-support registry:

• SVG has no built-in image recognizer, so its README row is inventory-only.
• RAW is a family, not one supported codec; recognizing CR2 or a TIFF-like container does not establish general RAW support.
• AVIF/HEIF recognition depends on container brands and available prefix bytes; the suffix is insufficient.
• Audio/video labels cover recognized containers, not every possible codec or stream combination.
• Even recognized files may be unsupported or invalid for the installed ffprobe build. A successful metadata probe is not a complete decode, candidate validation, or optimization guarantee.

The recognizer evidence is the versioned matcher table and image matchers. Do not turn that dependency's extension list into an OptiFlow support promise.

Current boundaries

Only PNG has a built-in versioned optimization-review profile. Its selection rules require current, provider-bound observations, png_pipe, one PNG video stream with positive dimensions and no audio facts. That profile does not enforce the later byte validator's RGB/RGBA/noninterlaced subset. An opportunity means that recompression may be evaluated later, with no estimated savings or output. See profile implementation and fixtures.

The candidate contract checks consistency of supplied declarations; it does not authenticate those declarations. Separately, png_validation::validate_png_pair compares actual immutable source/candidate slices. Its supported subset is static noninterlaced 8-bit RGB/RGBA with explicitly supported metadata. It checks complete streams, exact samples (including invisible RGB), ordered non-IDAT bytes and placement, and strictly smaller encoded length. Real synthetic fixtures exercise success and refusal. Its byte limits and best-effort decoder allocation accounting are not process-memory or wall-clock enforcement.

This is a library-only validator. The CLI command definitions and application dispatch do not invoke it, generate candidates, optimize, apply, replace, delete or quarantine source media. No format currently has a candidate producer or transaction engine. Other formats have no built-in optimization-review profile or candidate byte validator; ordinary inventory, probe metadata and extension roles are not substitutes for these capabilities.

Format plans

The existing image roadmap begins with conservative lossless PNG and OxiPNG capability discovery. OxiPNG remains the first planned candidate producer after #80; no executable version, invocation or working adapter is selected by this documentation checkpoint. A later bounded issue must prove its configuration fits the validator's exact preservation subset, or explicitly refuse unsupported inputs. The wrapper's default behavior or an encoder's “lossless” label cannot establish profile conformance.

The later image transformation roadmap includes JPEG optimization/encoding and compatibility-tested modern delivery formats. WebP, AVIF and JPEG XL are evaluation candidates under that roadmap, not promised adapters. In the combined AVIF/HEIF row, the production plan refers to AVIF evaluation, not a commitment to encode every HEIF codec. GIF, SVG, TIFF and RAW have no separately selected producers here; animation and RAW preservation requirements do not imply optimization support for them.

Audio/video work belongs to the later FFmpeg adapter/profile and validation phase. Perceptual checks, configured ExifTool metadata passes, and bounded batch/temporary-space handling remain planned. Metadata stripping is a separate explicit policy, not an optimization default.

The P apply/replace column names the shared transactional exact-duplicate milestone. It is format-independent duplicate resolution, not a promise to optimize every format. Optimized-media replacement additionally depends on its own validated profile and the later commit/recovery gates. Candidate generation, candidate publication and replacement are distinct checkpoints; #80 delivered none of those operations. Resolve the architecture/release boundary before adding execution to the CLI, preserving OFD-001 and OFD-005.

Rust core and mature providers

OptiFlow owns capability discovery, typed requests/results, policy, evidence, validation coordination, reporting and CLI contracts. Its roadmap also assigns scheduling, staging, transactions and recovery to that core; those future parts are not implemented merely because they are owned here. Flow owns cross-tool orchestration through released contracts.

Codec, encoder, decoder and quality-metric implementations should remain mature tools or libraries behind bounded adapters. OptiFlow's existing PNG validator already uses a pinned decoder with independent structural and preservation checks; it is not a new PNG codec. Prefer direct typed adapters for OxiPNG and later format-specific tools. Rust is the control layer, not a reason to rewrite established compression algorithms.

This follows the existing adapter roadmap, architecture, extension trust boundary, and candidate contract. It introduces no new provider role, dependency, mutation model or format policy.

What image_optim contributes

Source review pin: toy/image_optim@574276eb8e2f9ccfb468b74b18e3e5883e8445a1. The latest version tag observed was v0.32.0 at b1029755959d2105f775eb70d121122696d5d0c0. This was source inspection, not an executed optimizer benchmark.

Its Ruby gem declaration and worker registry show an orchestration layer over external JPEG, PNG, GIF and SVG utilities. The inspected built-in worker set has no WebP, AVIF, JPEG XL, audio or video producer. It is useful prior art for provider inventory and behavior, not a foundation that defines OptiFlow's format coverage.

Do not port image_optim line-for-line or add its Ruby gem as a foundational runtime dependency. A future optional compatibility provider could be considered only through the same untrusted-candidate boundary as other providers: exact version and executable-byte provenance, typed invocation, resource limits, explicit metadata policy, independent byte validation and a tool/license inventory. Its nested utilities must also be identified; pinning the wrapper alone would not bind their behavior. No such provider is implemented here.

The wrapper's MIT license does not establish the licensing or redistribution terms of all invoked tools or binary packs. Provider admission must inventory those separately under OptiFlow's dependency policy. This note makes no redistribution approval or tool-bundling decision.

Maintaining the matrix

The README is a human-readable projection, not a second capability registry. Update it with the implementing PR and evidence, preserving the distinction between source availability, a released binary, and observed provider behavior.

Every README status links to these explanations or a precise roadmap section. The snapshot is intentionally dated and pinned. A future canonical provider- capability registry should generate or validate this projection; this issue does not invent that registry or install a second discovery mechanism.

Decision impact: Reference / ADR not required. This records existing implementation and roadmap boundaries without accepting a new durable decision or changing the gated ADR migration.