# M00-QAR-VISUAL-DIFF-001 — Renderer checkpoint visual diff

<!-- OPENWC_CLAIM:M00-QAR-VISUAL-DIFF-001:sindo-main-codex:2026-07-13 -->
<!-- OPENWC_INTEGRATION:ACCEPTED:M00-QAR-VISUAL-DIFF-001:19df5b7 -->

## Ownership

- Target: M00
- Program: QAR
- Owner/Agent ID: sindo-main-codex
- Branch: `work/sindo-main-codex/m00-checkpoint-diff`
- Lease expires UTC: 2026-07-13
- Integrator: milestone integrator

## Outcome

Provide a deterministic, headless perceptual comparison for paired renderer checkpoint PNGs, with machine-readable results and synthetic regression coverage.

## Non-goals

- Supplying or committing original-client screenshots.
- Claiming visual parity or replacing human approval.
- Image registration, camera correction, or temporal animation matching.

## Paths

- Exclusive: `src/tools/compare_render_checkpoints.gd`
- Shared/hotspots: `src/tools/render_baseline_manifest.json`, `tools/run_render_baseline.ps1`, `docs/RENDER_BASELINE.md`, `docs/modules/world-renderer.md`, `RENDER.md`
- Generated/ignored: comparison reports, diff PNGs, original-client captures

## Contracts and data

- Public API/events: headless CLI arguments and JSON report documented in renderer baseline docs
- Schema/format version: comparison report schema 1; baseline manifest schema remains 1
- Migration/compatibility: additive manifest budget fields
- Consumers: developers and CI

## Dependencies

- Requires: Godot `Image` API and M00 checkpoint naming contract
- Blocks: automated portion of original-client paired comparison
- External state: approved build 12340 screenshots remain unavailable

## Verification

- Commands: headless self-test; manifest verification; documentation and coordination gates
- Fixtures: tool-generated identical and changed 2x2 PNGs
- Fidelity evidence: algorithm is deterministic; real-client evidence remains a manual/external input
- Performance budget: offline checkpoint operation, linear in pixel count

## Documentation deliverables

- Inline public API docs: CLI usage in script header
- Module specification: update renderer verification and source map
- Data-flow diagram: update baseline documentation
- Sequence/state/dependency diagrams: not stateful or asynchronous; not applicable
- Source map/status updates: renderer module and RENDER notes

## Simplicity and naming

- Important names introduced: `mean_perceptual_error`, `changed_pixel_ratio`
- Simplest considered solution: direct Godot Image iteration with no dependency
- Rejected complexity/abstractions: external image library, SSIM window pipeline, image registration
- Unavoidable complexity and justification: sRGB linearization avoids comparing encoded channel values directly
- Measured optimization evidence: not required for offline seven-checkpoint comparison

## Status

- State: ready
- Done: comparator, runner integration, manifest tolerance contract, synthetic regression, five local build 12340 references, three viewpoint calibrations, corrected visual capture and first paired report
- Next: integrator review; coordinate/placement gap should be resolved before tolerance calibration
- Blocked by: real paired screenshots only for final human fidelity approval

## Handoff

- Commit: branch HEAD
- Results: ten pairs compared with no missing candidates; mean error 0.0707..0.1746 and changed ratio 0.5504..0.8187; human review identified under-terrain/inside-geometry camera mismatches
- Remaining risks: coordinate/placement mismatch blocks meaningful tolerance calibration; synthetic animation, dusk and full human approval remain incomplete
- Documentation updated: `docs/RENDER_BASELINE.md`, `docs/modules/world-renderer.md`, `RENDER.md`
