# AI Agent Bug Suspicions & TODOs

This file tracks potential issues, structural anomalies, and mathematical mismatches identified by AI agents during code analysis. Items here require human verification before invasive code changes are made.

---

### [2026-04-24] Potential Double Normalization in Ranging Accumulation (Gemini)
**Location:** `CuasRanging.java`, method: `refineSingleTargetDisparity()` around line 1946.

**Observation:** 
The method accumulates transform-domain (TD) correlations across multiple scenes to increase SNR for deep disparity. 
1. It calls `OpticalFlow.accumulateCorrelationsAcOnly(accum_weights, fcorr_td_acc)`. This method loops over the array and divides `fcorr_td_acc` values by `accum_weights`.
2. It then calls `image_dtt.clt_process_tl_correlations(...)`, passing *both* the normalized `fcorr_td_acc` and the `accum_weights`.

If the downstream GPU call (`gpuQuad.execCorr2D_normalize`) uses `accum_weights` to divide the values again, the integrated signal is divided by $N^2$ instead of $N$. For a sequence of 200 frames, this suppresses the signal by a factor of 40,000, effectively destroying the correlation peak.

**Action Required:**
Verify if `execCorr2D_normalize` (or the downstream CPU equivalent if GPU falls back) applies division by the passed weights. If so, remove the `accumulateCorrelationsAcOnly` call in `refineSingleTargetDisparity`.

---


### [2026-04-24] Missing Peak Fallback (Gemini)
**Location:** `CuasRanging.java`, method: `rangeSingleTarget()`

**Observation:** 
If the integrated correlation fails (e.g., peak drowned out by the potential double-normalization bug), `disp_diff` evaluates to `NaN`. Because `use_non_lma` is `false`, it doesn't fall back to Center-of-Mass (CM) disparity. The method returns `null`, abruptly aborting the refinement loop for that segment. 

This causes the outer calling function to potentially log or retain `0.0` or `NaN` for `RSLT_GDISPARITY` (Global Disparity), rather than properly recording a failed integration or utilizing the un-refined initial disparity.

**Action Required:**
Check if returning `null` on failed refinement is the intended behavior, or if the system should persist the initial (single-frame) disparity into the `RSLT_GDISPARITY` field rather than zeroing it out when integration fails.

---

### [2026-04-24] Skyline "Far" Filtering Exception (Architecture Note)
**Location:** `CuasMotion.java`, around line 7916 (`filterTargetsLMA`)

**Observation:**
Targets located near the skyline are prone to generating spurious "ghost" motion vectors due to imperfect rotational background subtraction on the sharp thermal gradient. This caused valid targets to be lost if they fell off-center in a tile, because the strict "Far" filter (`FAIL_FAR`) killed them before they could compete with neighbors.

**Current Solution:**
The "Hard" `FAIL_FAR` logic is being selectively bypassed for "challenging" tiles (e.g., skyline). A "Soft" cost (`cxy` based on a cosine window) remains active to resolve redundant overlap competitions smoothly.

**Future Roadmap (Dynamic Thresholding):**
The threshold for defining a "challenging" tile is currently being determined empirically via per-tile variation maps. 
*   In Latvia (clear sky), the threshold can be narrow.
*   In Eagle Mountain (light clouds), the threshold must account for higher global variation.
*   *Future Iteration:* This threshold should eventually be made **adaptive** (e.g., based on sequence-level sky variance) rather than hardcoded, to handle different weather automatically. *Note: Keep simple for now to avoid auto-parameter "magic" masking bugs.*
