Skip to content

docs(accuracysnes): record why E8.06 is not reachable from the cart #301

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
doublegate merged 1 commit into from
Aug 1, 2026
+41 −0
Merged

docs(accuracysnes): record why E8.06 is not reachable from the cart #301

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions docs/accuracysnes-plan.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -293,6 +293,47 @@ decoder that saturates instead of wrapping settles, and a settled decoder's read
sign; only a value that wraps swings both ways. So the row samples `OUTX` 64 times and asserts that
both signs appear, which needs no phase-locking at all.

### `E8.06` — authored, injected, and withdrawn: two voices cannot be compared at one sample

**Attempted 2026-08-01 and withdrawn the same day.** The row reads: *"collapse case `KON=$01` /
`KON=$02` → usually only voice 2, and if both, voice 1 is **2 samples ahead**, proving the 16 kHz
rate."* It is `E8.01`'s mechanism asked the other way round, and the setup was already built, so it
looked like the cheapest row left in Group E.
Comment on lines +296 to +301

@coderabbitai coderabbitai Bot Aug 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail
rg -n -C 4 'E8\.06|NOT CART-MEASURABLE' docs to-dos

Repository: doublegate/RustySNES

Length of output: 9101

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- required documentation context ---'
for f in docs/architecture.md docs/STATUS.md CONTRIBUTING.md; do
  if [ -f "$f" ]; then
    printf '\n### %s\n' "$f"
    sed -n '1,220p' "$f"
  fi
done

printf '%s\n' '--- E8.06 and coverage conventions ---'
rg -n -C 8 'E8\.06|NOT CART-MEASURABLE|coverage|T-06|roadmap' \
  docs/accuracysnes-plan.md docs/accuracysnes-research-dossier.md \
  docs/accuracysnes-coverage.md to-dos

printf '%s\n' '--- candidate subsystem and ADR documentation ---'
rg -l -i 'AccuracySNES|SPC|DSP|audio|E8' docs adr* 2>/dev/null | head -80

Repository: doublegate/RustySNES

Length of output: 50379

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- plan section ---'
sed -n '280,345p' docs/accuracysnes-plan.md

printf '%s\n' '--- dossier E8 section and related status conventions ---'
sed -n '1278,1310p' docs/accuracysnes-research-dossier.md
rg -n -C 3 '\[NOT CART-MEASURABLE' docs to-dos

printf '%s\n' '--- coverage generator and dossier parsing ---'
rg -n -C 5 'accuracysnes-coverage|NOT CART-MEASURABLE|research-dossier|Uncovered|uncovered' \
  tests scripts docs to-dos \
  -g '*.rs' -g '*.py' -g '*.sh' -g '*.md' -g '*.toml'

printf '%s\n' '--- E8.06 ticket references ---'
rg -n -C 5 'E8\.06|T-[A-Z0-9-]+' docs/accuracysnes-plan.md \
  docs/accuracysnes-research-dossier.md to-dos | \
  grep -E 'E8\.06|T-[A-Z0-9-]+' | head -120

Repository: doublegate/RustySNES

Length of output: 50378

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- exact roadmap E-ticket rows ---'
sed -n '448,470p' to-dos/ROADMAP.md

printf '%s\n' '--- all exact E8.06 references ---'
rg -n 'E8\.06' . \
  -g '!snesdev_wiki/**' \
  -g '!target/**'

printf '%s\n' '--- coverage parser and report implementation ---'
fd -t f . tests/roms/AccuracySNES/gen/src | sort
rg -n -C 8 'fn parse_enumeration|parse_enumeration|coverage_report|covered|uncovered' \
  tests/roms/AccuracySNES/gen/src

printf '%s\n' '--- status-marker grammar ---'
rg -n -C 4 'NOT CART-MEASURABLE|NOT.*MEASURABLE|status marker|annotation' \
  tests/roms/AccuracySNES docs to-dos \
  -g '*.rs' -g '*.md' -g '*.toml'

Repository: doublegate/RustySNES

Length of output: 37167

Annotate E8.06 in the dossier as not cart-measurable.

Keep the assertion unchanged and add a [NOT CART-MEASURABLE] explanation linking docs/accuracysnes-plan.md §E8.06 and ticket T-04-E. Do not edit the generated coverage file; it already lists E8.06 as uncovered.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/accuracysnes-plan.md` around lines 296 - 301, Annotate the E8.06 dossier
entry in docs/accuracysnes-plan.md as [NOT CART-MEASURABLE], preserving its
existing assertion and explaining the limitation with links to §E8.06 and ticket
T-04-E. Do not modify the generated coverage file, which already records E8.06
as uncovered.

Sources: Path instructions, Learnings


Comment on lines +298 to +302
**The design was sound.** Two `KON` writes exactly 32 SPC cycles apart, `GAIN = $DF` (mode 6, linear
increase at rate 31) so `ENVX` climbs 2 per output sample, then read both voices and difference
them: **4** for the two-sample lead hardware gives, **2** for the one-sample lead a per-sample poll
would give. Both hardware outcomes — swallowed, or leading by two — are accepted, because which one
occurs depends on the phase the cart does not control; what no phase can produce is a one-sample
lead. RustySNES reports the collapse case, `ENVX` 0 against voice 7's `$26`.

**What killed it is the read window.** Each voice's `ENVX` is latched at its own tick of the DSP's
32-tick schedule, so the two registers do not update together and a reading taken between them is
one whole sample wrong — *exactly the size of the signal*. The fix is to bracket the voice-6 read
with two voice-7 reads and require them to agree, and the fix does not fit:

| three-reading window | of a 32-cycle sample |
|---|---|
| `dsp_read_to` ×3 (the ordinary form) | **39 cycles** — a straddle is certain |
| register-landed reads (`MOV Y,dp` / `MOV X,dp`, values parked in ports afterwards) | **21 cycles** — a straddle is likely |

Injecting the named bug (`KON` examined every sample) trips the **guard**, not the row's own code,
on both versions: the injected build's timing moves the update tick inside the window and voice 7
reads `$24` then `$26`. Per the standing rule, a row whose named injection fires the guard rather
than the assertion has not been demonstrated, and shipping it would mean shipping a scored row whose
failure code cannot be produced on demand.

**The finding, which is the reusable part:** *two voices' `ENVX` cannot be compared at
single-sample resolution from the cart.* The minimum three-read window is two-thirds of a sample and
the straddle error equals the signal. Any future row that needs to compare two voices' envelope
positions needs a different observable, not a tighter loop — the loop is already as tight as the
instruction set allows. `E8.06`'s swallow half is not separately assertable either: at any gap, both
poll rates swallow or spare voice 6 depending on phase, so the lead is what carries the claim.

Withdrawal verified byte-clean: removing it returned the ROM to checksum `$DA9E`, the value before
it was added. The two `MOV Y,dp` / `MOV X,dp` emitters went with it — this file carries only
opcodes a committed test exercises, and an unexercised encoding is an unverified one.

### An open question `B4.12` used to answer by accident

Does the V-IRQ flag re-assert while `V == VTIME` still holds — is it a one-shot per frame, or a
Expand Down
Loading