Promotes Lunar Pool

_wip/Golf (JU)/copilot/OVERLAP_AUDIT.md

@@ -0,0 +1,44 @@
+# Pass 1 overlap-entry audit
+
+The 19 held-back decoded entries reduce to nine intentional overlapping-instruction
+idioms plus one non-entry byte (`$D9DA`). These are valid 6502 size/speed tricks,
+not ambiguous code/data boundaries.
+
+## General idiom
+
+`BIT absolute` consumes the following two bytes without changing A. Entering one
+byte later interprets the low/high operand bytes as a useful instruction stream.
+This permits conditional constant selection without a branch around the second
+load. Because ca65 cannot emit two overlapping instruction streams linearly,
+Pass 1 preserves each byte sequence in a localized `.incbin` span and documents
+all valid entry points.
+
+## Resolutions
+
+- `$C198`: `BIT $00A9`; alternate entry `$C199`: `LDA #$00` from branch `$C194`.
+  Both entries valid. `$C198` is fall-through constant-selection path.
+- `$D424`: `BIT $40A9`; alternate entry `$D425`: `LDA #$40` from `$D49B`.
+  Both entries valid.
+- `$D9D8`: `BIT $0838`; alternate entry `$D9D9`: `SEC` from `$FE28`.
+  `$D9DA` (`PHP`) has no caller and is only the third byte of the BIT operand;
+  it is not an independent entry point.
+- `$D9F9`: `BIT $FFA9`; alternate entry `$D9FA`: `LDA #$FF` from `$D9F4`.
+  Both entries valid.
+- `$DF3A`: `BIT $02A9`; alternate entry `$DF3B`: `LDA #$02` from `$DF36`.
+  Both entries valid.
+- `$FB24`: `BIT $B8A9`; alternate entry `$FB25`: `LDA #$B8` from `$FAE4/$FBAB`.
+  Both entries valid and implement the already traced terrain fallback selection.
+- `$FB83`: `BIT $FFA9`; alternate entry `$FB84`: `LDA #$FF` from `$FB5C`.
+  Both entries valid.
+- `$FC6B`: `BIT $18`; alternate entry `$FC6C`: `CLC` from `$FC68`.
+  Both entries valid. The BIT path preserves carry set by the preceding `SEC`;
+  the alternate path explicitly clears carry before return.
+- `$FF00`: `BIT $00A9`; alternate entry `$FF01`: `LDA #$00` from `$FEFC`.
+  Both entries valid.
+
+## Pass 1 source treatment
+
+All nine physical byte sequences remain localized `.incbin` spans in `prg.s`.
+Named entry constants may point into these spans, but the overlapping bytes must
+not be emitted twice. Pass 2 may replace each span with explicit `.byte` values
+and entry aliases while retaining the dual interpretation in comments.