ARCADIA-Studio/harness/experiments/text-diagnostics-20260913/reviews/final-annotation-geometry-review.md

# Final bounded annotation geometry review

Static review and read-only evidence comparison: **PASS within the stated scope; no blocking semantic discrepancy found in the projection optimization.** No build, source edit, GUI action, or native acceptance was performed here. The separate `desktop-full-1` gate was running and is not counted as passed. This is a captured working-tree candidate, not a claim that base HEAD `b4b860f` contains the new implementation.

## Exact change and semantic review

Compared both 604-member captured source ZIPs, their manifests, and the current frozen files. Every member's uncompressed length and SHA-256 matched its manifest, both archives had unique exact membership, and both receipt-pinned manifests, archives, stdout and stderr matched their raw file hashes. The only changed input is `crates/oa-desktop/src/source_annotations.rs`; all 604 optimized inputs matched current files. The corrected anchor/helper region and following module declarations are byte-identical between captures.

Reviewed `source_annotations.rs:78–187` against the prior captured projection:

- Empty-index and nonpositive-clip returns cannot omit a previously emitted band: there is no admitted part, or no positive-area final intersection.
- Early vertical rejection at line 89 uses the same underline y and 1.5px height as the final rectangle. Touching the clip without positive height was already rejected. It preserves the declared rule that text whose underline is wholly clipped is not hoverable. It introduces no horizontal relocation or new horizontal rejection.
- Exact source validation at lines 96–106 is once per encountered logical paragraph **within the current projection**, not a persistent authority cache. Pinned Cosmic `buffer.rs:119–162` emits monotonically advancing paragraph indices and gives each wrap the same `line.text()`. The immutable Buffer and source are not mutated by projection. A mismatched affected paragraph still suppresses all its bands.
- The byte envelope at lines 108–122 uses minimum start and maximum end over every glyph, rather than first/last iterator entries. Any glyph satisfying the original strict half-open intersection necessarily intersects this envelope. Bidi reorder cannot create a false negative. Zero-advance glyphs remain eligible by source range and retain the old 1px visual affordance. Empty parts bypass the envelope entirely, preserving gap/EOF logic. Empty glyph arrays cannot have contributed a nonempty-range interval before this change.

The source index/admission, exact diagnostic ranges, cluster expansion, disjoint interval merging, final rectangle clipping, and publication/hover wrapper are unchanged. There is no new state authority or geometry cache. Arithmetic is safe for the finite geometry supplied by the renderer; this is not a claim about fabricated NaN layouts.

## Actual corrected geometry evidence

Both `annotation-corrected-1` and `annotation-projection-cost-2` report exit 0, unchanged inputs, and the same 18 passing annotation tests, including all three normally ignored manual tests (`--include-ignored --test-threads=1`). Actual test runtimes are 29.90s and 21.39s, respectively; those are not isolated projection measurements.

All 52 EOF/gap witness/summary lines are exactly equal between runs. They contain eight shared-cluster EOF witnesses and 43 omitted-separator witnesses. The rejected old gap fallback disagrees nine times; five expected boundaries are horizontally inside the tested viewport. For example, width 72, byte 53 has corrected owner 3/x43.984375 while the old fallback returns no anchor. Width 96, byte 28 similarly has owner 1/x72.78906. This strengthens the earlier width-72/byte-28 witness, whose x72.78906 was outside its viewport. These are actual CPU-layout witnesses, not native screenshot observations.

The shared-cluster EOF `אבג x` followed by U+20DD is now at x662.39844, preserving the complete LTR cluster's advance in an RTL paragraph; the original coordinate was x653.60156. Interior grapheme behavior is unchanged. The conservative suppression for a cluster split across multiple visual runs remains explicit and outside these admitted endpoint witnesses.

The other tests exercise actual mixed-bidi/combining/CJK clusters, half-open ownership, separators/EOF, wraps and scroll, wrong-source suppression, underline clipping, retained editor input/Word/Line behavior, stationary-pointer publication changes, and measured tooltip clipping. Output-count equality alone is not coordinate equivalence; the coordinate assertions and static rejection proof supply the relevant support.

## Timing comparison and limits

The timing source is identical in both archives. It uses actual pre-shaped graphics Editor buffers, one excluded warmup, five samples, eight projection calls per sample, `black_box`, and excludes result destruction while including operation allocation. Index construction is timed separately. These are serial Windows gnullvm **debug** measurements, with noticeable scheduling outliers; they are not release, GPU, highlighter, complete draw, hover-tooltip, App latency, or native responsiveness acceptance.

| Dense projection case | Inputs and same output | Prior median, ms | Optimized median, ms |
| --- | --- | ---: | ---: |
| Ordinary/top | 124,000 bytes, 4,001 paragraphs, 4,000 diagnostics; 10 runs/300 glyphs/10 bands | 0.014400 | 0.019100 |
| Ordinary/deep | Same input, logical scroll line 2,000; 10/300/10 | 0.015900 | 0.021287 |
| Single/top | 138,000 bytes, one paragraph, 1,500 diagnostics; 10 runs/680 glyphs/30 bands | 18.046075 | 0.196200 |
| Single/deep, diagnostics above viewport | Same input, vertical scroll 24,000; 10/680/0 | 17.173862 | 0.151537 |

Deep single-paragraph dense samples span 14.704387–20.292250ms before and 0.131425–0.189187ms after. Single/top spans 15.363587–25.966250ms before and 0.164625–1.334837ms after. The long-paragraph improvement is clear across these distributions. Ordinary dense medians increase by roughly 5 microseconds, so an across-the-board speedup claim would be inaccurate. Empty-index medians are now 37–75ns sample averages; this proves the fast return, not a general rendering budget.

The rejected-clip control always emits zero bands. Ordinary deep scroll is actually normalized to logical line 2,000 after editor update; the single-line fixture remains logical line zero and scrolls within thousands of wraps. The original failed unsettled-scroll fixture is not reused as positive evidence.

Unmeasured: dense empty-span fallback, expensive source-index construction beyond these fixed fixtures, arbitrary span distributions, and pathological shaped clusters. Empty anchors can still scan a paragraph's cached glyphs after local rejection; no claim of complexity independent of paragraph size is warranted. Cosmic's layout-run iterator itself traverses earlier wrapped layouts in a deep single paragraph. Existing index-build medians remain noisy at tens of milliseconds and are not improved by this projection change. These limitations do not invalidate the measured bounded optimization.

## Bindings

All paths below are relative to `C:/ar-text-9e8r6t` unless noted.

| Artifact | SHA-256 |
| --- | --- |
| Corrected source `source_annotations.rs` | `6015e52a3b05871218ef75fc27ad65b2b7ee473b885e91c45e1c4e6355ccfd65` |
| Optimized current source `source_annotations.rs` (12,089 bytes) | `e8137a77dd919d2395015a0968f0d28da766e80c31e5681ff820608302b65ce5` |
| `anchor_tests.rs` | `52580dcc70dddbee9cf96e2e1ef2558183593ea7c45c155e576925d9bfcd2b5d` |
| `layout_tests.rs` | `1e62212ffbe414e21151690a7d8d1910920aa75b823dc51967fb76215bb03800` |
| `performance_tests.rs` | `7d97a449347938067e1d5d70b285f49dab01f0e29f7e2e378319a8f020216879` |
| `widget.rs` | `add379d53259108fbb919c367add47a1d6d5fe00ad34738f17b942e2b2e7951e` |
| `widget/tests.rs` | `ed2d8f25f40cb0b34943af865b2cea7c2981546c740a0839a35f2bb93ed69c8d` |

Under `.local/text-diagnostic-gates/`:

| Run/file | SHA-256 |
| --- | --- |
| `annotation-corrected-1/result.json` | `62bec044414635546298d906e47dc5b1b63cdd5b42498d43ebfb01890c1ded3a` |
| `annotation-corrected-1/inputs.json` | `f2234d9184cd7239fe0688e8e2b49cf53d8569eeded671f1dbbbddf6cac4a2f7` |
| `annotation-corrected-1/inputs.zip` | `864a300c1779f863cf9cdf5b7fda902a78cfcd592274c4c6b745c64b2bc9347a` |
| `annotation-corrected-1/stdout.log` | `4ec5d293d4aa891d0b1635efef3cac8854c39983a0e86cc8d5fce0928f34af77` |
| `annotation-corrected-1/stderr.log` | `48e6855dc0a40c24c1847cf5105013b2f972e08ca99378e525a7fac3158535c8` |
| `annotation-projection-cost-2/result.json` | `2219b6a359e78776d838f73ce7623876f3c28387b448d3888a5fd1760f3b51b8` |
| `annotation-projection-cost-2/inputs.json` | `076377a1a48c4c3a4b176073ca96e79fd1ec300b22fe1ab1abfc5dd68c46fffe` |
| `annotation-projection-cost-2/inputs.zip` | `c5a6e697e1490a0be7af39c30b926a31e09a42e5a4120b40157d807eca7e7a70` |
| `annotation-projection-cost-2/stdout.log` | `6d47b478663ba0c001ab24eb833b812aa8c03cebbbc797ce6558dd7412e3099c` |
| `annotation-projection-cost-2/stderr.log` | `9af4bb05971373f3013119142dd55bf5b4e15fbb3318514e436eee7b84a48347` |

The receipts retain actual Cargo test-artifact metadata and debug profile. This review did not reopen the mutable shared-target executable during the separate active gate and does not make a new binary readback or full input-scope completeness claim beyond the verified captured membership.