Merge pull request 'test(M00): refine Goldshire camera framing' (#11) from work/sindo-main-codex/m00-camera-framing-refinement into master

Reviewed-on: #11

coordination/claims/M00-QAR-CAMERA-FRAMING-REFINEMENT-001.md

@@ -0,0 +1,78 @@
+# M00-QAR-CAMERA-FRAMING-REFINEMENT-001 — Goldshire pitch/FOV refinement
+
+<!-- OPENWC_CLAIM:M00-QAR-CAMERA-FRAMING-REFINEMENT-001:sindo-main-codex:2026-07-14 -->
+
+## Ownership
+
+- Target: M00
+- Program: QAR
+- Owner/Agent ID: sindo-main-codex
+- Branch: `work/sindo-main-codex/m00-camera-framing-refinement`
+- Lease expires UTC: 2026-07-14
+- Integrator: milestone integrator
+
+## Outcome
+
+Jointly refine Goldshire checkpoint pitch and FOV against a WMO-ready build 12340 reference.
+
+## Non-goals
+
+- Changing runtime player camera defaults.
+- Changing manifest values without an interior optimum and human approval.
+- Optimizing yaw beyond the ready-scene coarse result.
+
+## Paths
+
+- Exclusive: joint FOV option in camera-pose sweep and framing evidence
+- Shared/hotspots: camera-pose operational documentation and renderer module findings
+- Generated/ignored: candidate PNGs and ranking JSON under `user://`
+
+## Contracts and data
+
+- Public API/events: additive `-CameraFovValues`; scalar `-CameraFov` remains compatible
+- Schema/format version: ranking schema remains version 1 with existing per-candidate FOV field
+- Migration/compatibility: scalar sweeps retain existing candidate paths
+- Consumers: M00 fidelity workflow
+
+## Dependencies
+
+- Requires: WMO-ready 8-second capture contract
+- Blocks: Goldshire manifest framing decision
+- External state: private build 12340 reference remains outside Git
+
+## Verification
+
+- Commands: joint-grid plan regression, real ready-scene sweep, comparator self-test, repository gates
+- Fixtures: private Goldshire Inn reference
+- Fidelity evidence: joint pitch/FOV ranking and human inspection
+- Performance budget: offline diagnostic
+
+## Documentation deliverables
+
+- Inline public API docs: PowerShell parameter
+- Module specification: framing finding
+- Data-flow diagram: FOV joins pose grid
+- Sequence/state/dependency diagrams: unchanged
+- Source map/status updates: operational guide
+
+## Simplicity and naming
+
+- Important names introduced: `CameraFovValues`, `effectiveCameraFovValues`
+- Simplest considered solution: one additional loop around the existing grid
+- Rejected complexity/abstractions: generic optimizer
+- Unavoidable complexity and justification: projection and pitch jointly affect framing
+- Measured optimization evidence: bounded 1x5x3 grid
+
+## Status
+
+- State: ready-for-review
+- Done: additive joint FOV grid, compatibility-preserving paths, plan regression, ready-scene 15-candidate ranking and human inspection
+- Next: add approved landmark/region scoring before any manifest camera calibration
+- Blocked by:
+
+## Handoff
+
+- Commit: this work-package commit
+- Results: numeric best FOV 62/yaw 10/pitch -25 at mean 0.078843 and ratio 0.667721 was visually rejected as grass-dominated; FOV 38/yaw 10/pitch -10 better matched building scale at mean 0.084220
+- Remaining risks: full-frame metric does not preserve landmark framing; no manifest values were changed
+- Documentation updated: `docs/CAMERA_POSE_SWEEP.md`, `docs/modules/world-renderer.md`

coordination/claims/M00-QAR-CAMERA-POSE-EVIDENCE-001.md

@@ -0,0 +1,78 @@
+# M00-QAR-CAMERA-POSE-EVIDENCE-001 — Goldshire camera pose evidence
+
+<!-- OPENWC_CLAIM:M00-QAR-CAMERA-POSE-EVIDENCE-001:sindo-main-codex:2026-07-14 -->
+
+## Ownership
+
+- Target: M00
+- Program: QAR
+- Owner/Agent ID: sindo-main-codex
+- Branch: `work/sindo-main-codex/m00-camera-pose-evidence`
+- Lease expires UTC: 2026-07-14
+- Integrator: milestone integrator
+
+## Outcome
+
+Produce coarse-to-fine yaw/pitch evidence for the build 12340 Goldshire Inn reference and classify whether framing dominates the paired-image gap.
+
+## Non-goals
+
+- Changing manifest camera defaults before human approval.
+- Treating minimum perceptual error as proof of exact camera parity.
+- Committing proprietary reference images or generated candidates.
+
+## Paths
+
+- Exclusive: camera-pose evidence record
+- Shared/hotspots: renderer baseline and module fidelity findings
+- Generated/ignored: all sweep PNGs and JSON under `user://`
+
+## Contracts and data
+
+- Public API/events: none
+- Schema/format version: unchanged
+- Migration/compatibility: none
+- Consumers: M00 fidelity review
+
+## Dependencies
+
+- Requires: merged camera-pose sweep and local build 12340 reference
+- Blocks: classification of the Goldshire WMO paired gap
+- External state: `sources/OpenWCReferenceCheckpoints/goldshire_inn_large_wmo.jpg`
+
+## Verification
+
+- Commands: coarse and fine real sweeps, ranking inspection, repository gates
+- Fixtures: private Goldshire Inn build 12340 screenshot
+- Fidelity evidence: ranked mean perceptual error and changed-pixel ratio
+- Performance budget: offline diagnostic only
+
+## Documentation deliverables
+
+- Inline public API docs: unchanged
+- Module specification: fidelity finding and remaining risk
+- Data-flow diagram: unchanged
+- Sequence/state/dependency diagrams: unchanged
+- Source map/status updates: baseline evidence
+
+## Simplicity and naming
+
+- Important names introduced: none
+- Simplest considered solution: use the merged bounded grid runner
+- Rejected complexity/abstractions: optimizer or renderer changes
+- Unavoidable complexity and justification: real images must be rendered for each candidate
+- Measured optimization evidence: single pass per candidate
+
+## Status
+
+- State: ready-for-review
+- Done: private reference dimensions verified; coarse, extended and limit sweeps completed; representative candidates inspected; runner failure handling hardened
+- Next: investigate Goldshire Inn spatial/placement composition separately; do not change manifest yaw/pitch from this metric
+- Blocked by:
+
+## Handoff
+
+- Commit: this work-package commit
+- Results: zero offset mean error 0.099632; coarse best (-10,-20) 0.077575; metric decreased monotonically to (0,-60) 0.063574/changed ratio 0.549556, while visual inspection showed only grass and no inn
+- Remaining risks: full-frame color error cannot register a missing landmark; WMO placement/streaming at this checkpoint remains unresolved
+- Documentation updated: `docs/CAMERA_POSE_SWEEP.md`, `docs/modules/world-renderer.md`

coordination/claims/M00-QAR-WMO-READINESS-001.md

@@ -0,0 +1,78 @@
+# M00-QAR-WMO-READINESS-001 — Goldshire WMO readiness
+
+<!-- OPENWC_CLAIM:M00-QAR-WMO-READINESS-001:sindo-main-codex:2026-07-14 -->
+
+## Ownership
+
+- Target: M00
+- Program: QAR
+- Owner/Agent ID: sindo-main-codex
+- Branch: `work/sindo-main-codex/m00-wmo-readiness`
+- Lease expires UTC: 2026-07-14
+- Integrator: milestone integrator
+
+## Outcome
+
+Prevent pose calibration against an under-loaded WMO scene and replace invalid Goldshire evidence with a baseline-ready comparison.
+
+## Non-goals
+
+- Changing runtime streaming budgets.
+- Claiming all WMO queues must globally drain before a checkpoint.
+- Changing manifest camera pose without valid paired evidence.
+
+## Paths
+
+- Exclusive: pose-sweep readiness default and Goldshire timing evidence
+- Shared/hotspots: renderer baseline/module fidelity findings
+- Generated/ignored: timing and sweep images under `user://`
+
+## Contracts and data
+
+- Public API/events: pose sweep default wait becomes 8 seconds, matching the M00 manifest
+- Schema/format version: unchanged
+- Migration/compatibility: explicit `-WaitSeconds` remains supported
+- Consumers: M00 paired-fidelity workflow
+
+## Dependencies
+
+- Requires: Goldshire pose evidence and private build 12340 reference
+- Blocks: valid Goldshire camera-pose ranking
+- External state: private reference and generated captures remain outside Git
+
+## Verification
+
+- Commands: 2/8/15 second timing audit, ready-scene 3x3 pose sweep, baseline dry-run, repository gates
+- Fixtures: private Goldshire Inn screenshot
+- Fidelity evidence: visual WMO presence plus streaming snapshot and paired metrics
+- Performance budget: offline diagnostic
+
+## Documentation deliverables
+
+- Inline public API docs: PowerShell default
+- Module specification: corrected readiness/fidelity finding
+- Data-flow diagram: readiness precondition
+- Sequence/state/dependency diagrams: unchanged
+- Source map/status updates: camera-pose operational guide
+
+## Simplicity and naming
+
+- Important names introduced: none
+- Simplest considered solution: reuse the manifest's measured 8-second stabilization default
+- Rejected complexity/abstractions: global queue barrier that would include unrelated distant work
+- Unavoidable complexity and justification: WMO publication is asynchronous
+- Measured optimization evidence: 2/8/15 second snapshots
+
+## Status
+
+- State: ready-for-review
+- Done: timing audit invalidated the 2-second evidence; sweep default now matches the 8-second manifest; ready-scene 3x3 grid and human inspection completed
+- Next: jointly refine negative pitch and FOV around the ready-scene Goldshire candidate
+- Blocked by:
+
+## Handoff
+
+- Commit: this work-package commit
+- Results: WMO instances 9/113/328 at 2/8/15 seconds; inn absent at 2 and visible at 8/15; ready grid improved mean error from 0.101402 at (0,0) to 0.087952 at (10,-10)
+- Remaining risks: global WMO queues still contain unrelated work; best pitch is at the tested boundary and building scale indicates unresolved FOV/framing
+- Documentation updated: `docs/CAMERA_POSE_SWEEP.md`, `docs/modules/world-renderer.md`

docs/CAMERA_POSE_SWEEP.md

@@ -14,10 +14,12 @@ This offline M00 diagnostic recovers reproducible checkpoint framing when an ori
   -Checkpoint elwynn_adt_boundary `
   -YawOffsets -15,-10,-5,0,5,10,15 `
   -PitchOffsets -10,-5,0,5,10 `
-  -WaitSeconds 2
+  -CameraFovValues 38,50,62 `
+  -ViewportWidth 1280 -ViewportHeight 960 `
+  -WaitSeconds 8
 ```
 
-Each candidate receives its own output directory and comparison report. `ranking.json` sorts candidates by mean perceptual error and then changed-pixel ratio. Use `-PlanOnly` to validate the Cartesian grid and output paths without rendering. Run a coarse grid first, then a finer grid around the best candidate.
+Each candidate receives its own output directory and comparison report. `-CameraFovValues` adds FOV as another bounded grid dimension; omit it to retain the scalar `-CameraFov` workflow and legacy candidate paths. The viewport must exactly match the reference image dimensions; the runner fails on `size_mismatch` instead of inventing a score. The default 8-second wait matches the M00 manifest and is a readiness precondition: lowering it requires evidence that the checkpoint's WMO/M2 content has already appeared. `ranking.json` sorts candidates by mean perceptual error and then changed-pixel ratio. Use `-PlanOnly` to validate the Cartesian grid and output paths without rendering. Run a coarse grid first, then a finer grid around the best candidate.
 
 ```mermaid
 flowchart LR
@@ -37,3 +39,19 @@ The smallest error is a candidate, not automatic fidelity approval. Geometry, ma
 ## Verification
 
 The headless capture dry-run must report requested yaw and pitch offsets. Comparator `--self-test` covers paired metrics. Sweep `-PlanOnly` covers deterministic grid expansion and output naming without requiring a display. A real ranked sweep requires a display and a private build 12340 reference image.
+
+## Goldshire Inn evidence — 2026-07-12
+
+The private `2560x1440` build 12340 `goldshire_inn_large_wmo` reference was evaluated at FOV 62 degrees. A coarse 5x5 grid over yaw/pitch `[-20, -10, 0, 10, 20]` reduced mean error from `0.099632` at `(0, 0)` to `0.077575` at `(-10, -20)`. Extending pitch produced `0.070901` at `(0, -40)` and `0.063574` at `(0, -60)` with changed-pixel ratio `0.549556`.
+
+These values are invalid camera-pose evidence because the sweep used a 2-second wait. A subsequent readiness audit showed 9 WMO instances and no inn after 2 seconds, 113 instances with the inn visible after 8 seconds, and 328 instances after 15 seconds. The apparent monotonic improvement rewarded grass while the landmark was still absent; it does not demonstrate a spatial/placement defect. The manifest pose remains unchanged pending a ready-scene rerun.
+
+The ready-scene 3x3 rerun at FOV 62 degrees ranked `(yaw=10, pitch=-10)` first with mean error `0.087952` and changed-pixel ratio `0.665527`, compared with `0.101402`/`0.702489` at zero offsets. Human inspection confirms that the inn is present and the direction is plausible. Pitch remains on the tested boundary and the building scale differs from the reference, so these offsets are coarse evidence only; a joint pitch/FOV refinement is required before changing manifest camera values.
+
+## Goldshire joint pitch/FOV refinement — 2026-07-12
+
+A WMO-ready joint grid fixed yaw at 10 degrees and evaluated pitch `[-25, -20, -15, -10, -5]` across FOV `[38, 50, 62]`. Full-frame error ranked FOV 62/pitch -25 first at `0.078843` with changed-pixel ratio `0.667721`. Human inspection rejects it as a manifest calibration: the view is dominated by grass and crops the inn. FOV 38/pitch -10 is closer to the reference building scale but ranks only `0.084220`, and horizontal landmark alignment remains different.
+
+The grid therefore has no approved joint optimum. Full-frame color error continues to trade landmark framing against large terrain regions. The manifest remains unchanged. The next registration method must score an approved inn/road/tree landmark region or explicit landmark coordinates rather than the entire image.
+
+During this run the sweep orchestration was hardened in two ways: expected comparator exit code `1` is now collected through an explicit child process, and viewport dimensions are explicit. A reference/candidate `size_mismatch` now fails before ranking instead of producing an empty metric.

docs/modules/world-renderer.md

@@ -230,6 +230,9 @@ Exact exported settings and cache versions remain documented in [`../../RENDER.m
 - Camera-occluder probe не нашёл camera containment в пяти точках; paired mismatch локализован прежде всего в manual look direction/target/FOV calibration, с явным ограничением по RID-only geometry.
 - Empirical FOV sweep выявил, что checkpoint camera должна явно вызывать `make_current()`; после исправления projection ranking остаётся inconclusive из-за неизвестного manual yaw/pitch/framing reference.
 - Camera-pose sweep can now rank bounded yaw/pitch grids without changing manifest defaults; perceptual ranking remains diagnostic and requires human framing approval.
+- The first Goldshire pose grid was invalidated by WMO readiness: the inn is absent after 2 seconds but visible after the manifest-standard 8-second wait. Pose comparisons must stabilize asynchronous checkpoint content first.
+- A ready-scene Goldshire 3x3 grid improved mean error from `0.101402` at zero offsets to `0.087952` at yaw `10`/pitch `-10`; pitch/FOV refinement remains required before manifest calibration.
+- Joint Goldshire pitch/FOV refinement had no human-approved optimum: full-frame error preferred grass-heavy FOV 62/pitch -25, while FOV 38/pitch -10 better matched building scale. Landmark/region scoring is required before calibration.
 - D3D12 descriptor issues remain; the capture-path anonymous `RefCounted` shutdown leak is regression-covered by a clean verbose dry-run, while other RID/resource diagnostics still require independent evidence.
 - M2/WMO/material/particle/ribbon/portal parity incomplete.
 - Public API is mostly exported configuration rather than stable contracts.

tools/sweep_render_checkpoint_camera_pose.ps1

@@ -9,7 +9,10 @@ param(
     [double[]]$YawOffsets = @(-10.0, 0.0, 10.0),
     [double[]]$PitchOffsets = @(-10.0, 0.0, 10.0),
     [double]$CameraFov = 62.0,
-    [double]$WaitSeconds = 2.0,
+    [double[]]$CameraFovValues = @(),
+    [int]$ViewportWidth = 1280,
+    [int]$ViewportHeight = 900,
+    [double]$WaitSeconds = 8.0,
     [double]$MeasureSeconds = 0.1,
     [switch]$PlanOnly
 )
@@ -32,7 +35,8 @@ if (-not (Test-Path -LiteralPath $ReferenceDirectory)) {
 }
 
 $invariantCulture = [Globalization.CultureInfo]::InvariantCulture
-$cameraFovText = $CameraFov.ToString($invariantCulture)
+$isJointFovSweep = $CameraFovValues.Count -gt 0
+$effectiveCameraFovValues = if ($isJointFovSweep) { $CameraFovValues } else { @($CameraFov) }
 $waitSecondsText = $WaitSeconds.ToString($invariantCulture)
 $measureSecondsText = $MeasureSeconds.ToString($invariantCulture)
 $absoluteOutput = if ($Output.StartsWith("user://")) {
@@ -44,11 +48,16 @@ $ranking = [Collections.Generic.List[object]]::new()
 
 Push-Location $repoRoot
 try {
+    foreach ($cameraFovValue in $effectiveCameraFovValues) {
         foreach ($yawOffset in $YawOffsets) {
             foreach ($pitchOffset in $PitchOffsets) {
+            $cameraFovText = $cameraFovValue.ToString("0.###", $invariantCulture)
             $yawText = $yawOffset.ToString("0.###", $invariantCulture)
             $pitchText = $pitchOffset.ToString("0.###", $invariantCulture)
             $candidateName = "yaw_$($yawText.Replace('-', 'n').Replace('.', '_'))__pitch_$($pitchText.Replace('-', 'n').Replace('.', '_'))"
+            if ($isJointFovSweep) {
+                $candidateName = "fov_$($cameraFovText.Replace('.', '_'))__$candidateName"
+            }
             $candidateOutput = "$Output/$candidateName"
             $comparisonReport = Join-Path $absoluteOutput "$candidateName.json"
 
@@ -56,25 +65,32 @@ try {
                 $ranking.Add([pscustomobject]@{
                     yaw_offset_degrees = $yawOffset
                     pitch_offset_degrees = $pitchOffset
-                    camera_fov_degrees = $CameraFov
+                    camera_fov_degrees = $cameraFovValue
                     candidate_directory = $candidateOutput
                 })
                 continue
             }
 
-            & $GodotPath --path . --script res://src/tools/capture_render_checkpoints.gd -- `
-                --output $candidateOutput --only $Checkpoint --single-pass `
-                --camera-fov $cameraFovText `
-                --camera-yaw-offset $yawText --camera-pitch-offset $pitchText `
-                --wait $waitSecondsText --measure $measureSecondsText
-            if ($LASTEXITCODE -ne 0) {
+            $captureArguments = @(
+                "--path", ".", "--script", "res://src/tools/capture_render_checkpoints.gd", "--",
+                "--output", $candidateOutput, "--only", $Checkpoint, "--single-pass",
+                "--camera-fov", $cameraFovText,
+                "--camera-yaw-offset", $yawText, "--camera-pitch-offset", $pitchText,
+                "--viewport-width", $ViewportWidth, "--viewport-height", $ViewportHeight,
+                "--wait", $waitSecondsText, "--measure", $measureSecondsText
+            )
+            $captureProcess = Start-Process -FilePath $GodotPath -ArgumentList $captureArguments -Wait -PassThru
+            if ($captureProcess.ExitCode -ne 0) {
                 throw "Capture failed for yaw=$yawText pitch=$pitchText"
             }
 
-            & $GodotPath --headless --path . --script res://src/tools/compare_render_checkpoints.gd -- `
-                --reference $ReferenceDirectory --candidate $candidateOutput `
-                --only $Checkpoint --output $comparisonReport
-            if ($LASTEXITCODE -notin @(0, 1)) {
+            $comparisonArguments = @(
+                "--headless", "--path", ".", "--script", "res://src/tools/compare_render_checkpoints.gd", "--",
+                "--reference", $ReferenceDirectory, "--candidate", $candidateOutput,
+                "--only", $Checkpoint, "--output", $comparisonReport
+            )
+            $comparisonProcess = Start-Process -FilePath $GodotPath -ArgumentList $comparisonArguments -Wait -PassThru -NoNewWindow
+            if ($comparisonProcess.ExitCode -notin @(0, 1)) {
                 throw "Comparison failed for yaw=$yawText pitch=$pitchText"
             }
 
@@ -82,12 +98,17 @@ try {
             if ($comparison.compared_count -lt 1) {
                 throw "No paired image was compared for yaw=$yawText pitch=$pitchText"
             }
-            $meanError = ($comparison.results | Measure-Object -Property mean_perceptual_error -Average).Average
-            $changedRatio = ($comparison.results | Measure-Object -Property changed_pixel_ratio -Average).Average
+            $metricResults = @($comparison.results | Where-Object { $null -ne $_.mean_perceptual_error })
+            if ($metricResults.Count -ne $comparison.compared_count) {
+                $statuses = ($comparison.results.status | Sort-Object -Unique) -join ","
+                throw "Comparison produced no numeric metric for yaw=$yawText pitch=$pitchText statuses=$statuses"
+            }
+            $meanError = ($metricResults | Measure-Object -Property mean_perceptual_error -Average).Average
+            $changedRatio = ($metricResults | Measure-Object -Property changed_pixel_ratio -Average).Average
             $ranking.Add([pscustomobject]@{
                 yaw_offset_degrees = $yawOffset
                 pitch_offset_degrees = $pitchOffset
-                camera_fov_degrees = $CameraFov
+                camera_fov_degrees = $cameraFovValue
                 mean_perceptual_error = $meanError
                 changed_pixel_ratio = $changedRatio
                 candidate_directory = $candidateOutput
@@ -95,6 +116,7 @@ try {
             })
             }
         }
+    }
 
     $rankedCandidates = if ($PlanOnly) {
         @($ranking)
@@ -106,11 +128,14 @@ try {
         schema_version = 1
         checkpoint = $Checkpoint
         reference_directory = [IO.Path]::GetFullPath($ReferenceDirectory)
+        viewport = @($ViewportWidth, $ViewportHeight)
+        wait_seconds = $WaitSeconds
+        measure_seconds = $MeasureSeconds
         candidates = $rankedCandidates
     }
     New-Item -ItemType Directory -Force -Path $absoluteOutput | Out-Null
     $rankingDocument | ConvertTo-Json -Depth 6 | Set-Content -Encoding UTF8 -LiteralPath $rankingPath
-    $rankedCandidates | Format-Table yaw_offset_degrees, pitch_offset_degrees, mean_perceptual_error, changed_pixel_ratio
+    $rankedCandidates | Format-Table camera_fov_degrees, yaw_offset_degrees, pitch_offset_degrees, mean_perceptual_error, changed_pixel_ratio
     $completionKind = if ($PlanOnly) { "plan" } else { "ranking" }
     Write-Output "Camera pose sweep $completionKind completed: $rankingPath"
 } finally {