[JoeMatt]

Release v3.10.0

Ship TV mode and controller library navigation, Pro Controller controls, fullscreen menu auto-hide/native breakout-window chrome, multi-disc playlists and per-disc state resume, opt-in emulation threading with achievements/netplay, and optional Neuro API support.

Include the completed AtariAge follow-ups: GPU/DSP MMULT address persistence/wrap (#1048), live PIT/MEMCON1 readback (#1047), GT regression coverage (#1049), and the reproduced Fast blitter DSTA2 computed-Z destination-lane correction (#1051, backport 338e2b65).

Core options and savestate format v17 carry over. Emulation threading remains experimental and off by default; Tools/debugger and GDB require inline mode. The three version copies, release notes, WHATSNEW and boot matrices are included. This GitFlow release targets master.

Refs #1036

Validation

Combined core candidate 344dc0bc on Mac Studio. 62118c06 adds validation docs/matrices; 24ae1bdb imports the TOM PR's follow-up screenshot reference. Neither changes emulation sources.

• Core build, C89 lint and full make TEST_EXPORTS=1 test: passed. Three skips: missing optional Fountain live-abort fixture, CHSE-capable chdman and one-session Red Book disc. Host-sensitive network checks ran and passed.
• Explicit private-ROM audio pair: Skyhammer and Iron Soldier 2 clipping passed; Iron Soldier 1 presence passed.
• Updated release candidate 378c15af: all 93 blitter command checks pass; acid baseline has 152 cases, 149 pass / 3 established known failures, zero regressions and zero missing. C89 lint passes. The new DSTA2 GT ROM and all associated regression tests are included unchanged from fix(blitter): use A2 destination lanes for GT computed Z #1051. Earlier source-session RetroArch testing confirmed red before / green after the fix.
• Fresh final-core Studio matrices (b5e40090, matrix input identity 67acceb9dc39, committed in f6e2e7b7): 155 cartridge titles in HLE/BIOS and 28 CD title/mode rows. Against both v3.9.1 and pre-GT candidate 24ae1bdb: zero backward moves, zero added/removed rows, no new watchdog signatures or asymmetries. Three existing cartridge asymmetries are unchanged. All four matrix comparisons and the sweep pipeline exited 0.
• App build and full CTest: 159 passed, zero failed/skipped, including 53 emulation-thread tests.
• Screenshot regression suite on Studio: 10 passed, 0 failed after importing the reference update. All 86 changed pixels are the Jagniccc PIT profiling digits; geometry and frame count are unchanged. The new PNG exactly matches Linux/macOS ARM64 CI captures. Strict pixel comparison remains enabled.
• Independent reviews of combined core changes and screenshot provenance: no findings.
• Incoming MMULT/TOM regressions failed on original code; MMULT row/column/consecutive/wrap and savestate checks now pass. Original netlists checked during release review. Source-session RetroArch validation confirms filled polygon geometry, live PIT counter and matching MEMCON1 values. GT negative control fails when comparison is removed.
• Playlist regressions cover invalid entries, hidden per-disc ownership, equal slots, stem collisions, warm-cache lookup and real inline/threaded resume. Windows expectations now normalize native path separators, fixing the three failed Windows library jobs.
• Existing focused Studio windowed checks cover inline/threaded operation, settings, fullscreen hover/F1/restore/persistence and native-only chrome. POSIX installer hermetic tests: 208 passed. Clean-machine Windows qualification remains tracked separately in [app] Qualify core/app installer and update flows on clean macOS, Linux and Windows #840.

Merge is authorized after all applicable checks on the latest PR head and release build are green and unresolved reviews are addressed. Follow the live head rather than an older validation snapshot. Fresh private-ROM boot matrices on the final core candidate are complete; published-package qualification remains a pre-tag check; tagging, published-asset verification, master-to-develop back-merge and downstream info/site updates are separate publication work.

Tracker reconciliation

Confirmed AtariAge bug tickets belong to v3.10.0. The 4.0 milestone tracks threaded debugging/display pacing, stable-default qualification, completed TV pages/Auto mode and package/install/update validation. The hardware timing campaign and dual-Jaguar rollback remain separate future work. See #254 and #371.

[github-actions]

App packages

Built from 304867b (workflow run).
Shared release-candidate packages (prerelease filenames). Package verification: success.

Platform	Download	Size
Linux x86_64: Flatpak bundle (.flatpak)	app-package-flatpak	19.3 MB
Linux aarch64: .AppImage + .deb	app-package-linux-aarch64	44.5 MB
Linux x86_64: .AppImage + .deb	app-package-linux-x86_64	46.0 MB
macOS (universal): .zip	app-package-macos-universal	30.4 MB
Windows ARM64: portable .zip + -setup.exe	app-package-windows-arm64	41.8 MB
Windows x64: portable .zip + -setup.exe	app-package-windows-x64	45.5 MB

Downloading an artifact needs a GitHub login. macOS: Developer ID signed and notarized (PRs from forks get
no signing secrets and stay ad-hoc signed: right-click > Open, or xattr -dr com.apple.quarantine "Virtual Jaguar.app").
Windows: not code-signed yet, SmartScreen may warn. Linux AppImage: chmod +x it.

_{Updated by CI at 2026-10-21T00:28:23.082Z}

[github-actions]

🌙 Kimi review

Verdict: one real defect in the core changes — the new MEMCON1 open-bus readback in TOMReadable() is unreachable dead code due to an address-masking bug; everything else shown looks consistent with its stated intent.

Findings

src/tom/tom.c:~2052 — TOMReadable() masks with 0xFFFE, so the MEMCON1 fallback can never fire. TOMReadByte() receives the full address (0xF00050 etc. — that's what the PIT/MEMCON1 special cases above it compare against, and it's why the old TOMReadWord had to apply its own offset &= 0x3FFF). Inside TOMReadable(), word = offset & 0xFFFE therefore retains the 0xF00000 base for every TOM-space access. All the decoded-range tests (word <= 0x000A, word == 0x0020, 0x0050, 0x00E0…) can never match, and the final word >= 0x2000 is true for the entire TOM register file. So every write-only register read falls through to tomRam8[offset & 0x3FFF] and returns the stored byte — exactly the old behavior — while the return tomRam8[MEMCON1 + (offset & 1)] branch is dead. The mask presumably wants to be offset & 0x3FFE (TOM's 16 KB window). This contradicts the release's own claim of "matching MEMCON1 values" from #1047: with this bug, a game polling MEMCON1 through an undecoded address gets stale register data, not the live MEMCON1 float — worth re-running whichever test purported to cover that path, because the code as written cannot produce it.

Notes on the rest (shown portion)

• MMULT changes (gpu.c, dsp.c): the 0xF03000 | (x & 0xFFC) / 0xF1B000 | (x & 0xFFC) wrap and the writeback of the running counter are internally consistent and idempotent across the write path (GPUWriteLong case 0x08) and both DSP MMULT implementations. The stated grounding (SYSTOLIC.NET MACOUNT as a live 10-bit counter) is the right kind of evidence; I have no basis to dispute it, and per the JTRM the persistence-across-instructions behavior is the previously-missing half.
• Blitter DSTA2 lane selection: picks destination phrase mode and destination X consistently in both the strip-init and lane-advance sites. C89-clean (declarations sit at the top of their blocks).
• PIT readback: TOMReadPIT() derives counters from the scheduled callback expiration without advancing time, which matches the stated constraint. One thing I can't verify from the diff: that eventTime in the event list is remaining-time (decremented by SubtractEventTimes) rather than absolute — if it were absolute, the reads would return garbage. GetTimeToNextEvent's existing semantics suggest remaining, so likely fine. Note prescaler == 0 returns 0 for both counters; if that's meant to encode "timer disabled," it's a hardware claim the diff doesn't substantiate, but it matches the old "read back the written value" behavior closely enough not to be a regression.
• TOMReadWord de-masking: removing offset &= 0x3FFF changes word reads at 0xF000E0/E1 (now consistent with the byte path: 0 and IRQ control) — appears deliberate and harmless, but it's a behavior change riding along silently.
• event.c GetCallbackTime: C89-clean, no interaction with list ordering. Fine.
• jaguar.c/dac.c accessor swaps are behavior-neutral (same underlying word reads).

Coverage caveat

197 of the changed files were truncated from the diff — everything under app/ beyond the headers shown, plus tests. The headers shown (EmuThread, FrameExchange, InputSnapshot, LateLatch, PacingClock, the desktop/TV nav headers) are desktop-app C++, outside the core constraints, and I saw nothing in them I'd confidently call a defect from declarations alone — but I have not reviewed their implementations, the savestate-format claims (v17 "carries over"), or the playlist/state-resume logic those headers advertise. The finding above is limited to the core emulation sources that were shown.

_{4 generated/vendored file(s) excluded from review.}

_{Diff truncated before review — large PR. 197 changed file(s) not reviewed: app/src/pad_profile.h, app/src/perf.h, app/src/perf_trace.h, app/src/remap.h, app/src/video.h, app/src/window_chrome.h, app/src/debug/audio_ring.h, app/src/debug/debug_session.h, app/src/neuro/neuro_actions.h, app/src/neuro/neuro_agent.h +187 more.}

[github-actions]

🌙 Kimi review

Verdict: no confident defects in the emulation changes shown; the core C is C89-clean and the MMULT/blitter/PIT logic is internally consistent. Two items deserve a confirmation before merge, plus the usual scope caveat for the truncated app-side files.

Findings / verification points, most significant first:

1. src/tom/tom.c:~2040 — TOMReadPIT returns 0 whenever tomTimerPrescaler == 0, but prescaler 0 (period 1) is a legal running configuration on hardware — there is no "prescaler zero disables the PIT" rule in the JTRM. This guard is only harmless if the PIT callback is never scheduled when the prescaler is 0 (i.e., the write path refuses to schedule). The scheduling code is in the truncated portion of the diff, so I can't confirm. If TOMPITCallback can be live with prescaler 0, reads of PIT0/PIT1 will report 0 while the timer runs. Worth one line of confirmation, or drop the !tomTimerPrescaler term and rely on the usecs < 0.0 (not-queued) check alone.

2. src/core/state.h (not in diff) — dsp_pointer_to_matrix / gpu_pointer_to_matrix are now live architectural state that persists across instructions (SYSTOLIC MACOUNT), not just a write-only register shadow. If they were previously omitted from the savestate region on the assumption that games always write the pointer before MMULT, that assumption is now false: MMULT → save → load → MMULT without a rewrite would resume at a stale address — exactly the state-outside-a-saved-region defect class that broke run-ahead. The release notes say "savestate checks now pass," which suggests this is covered, but the field-level confirmation isn't visible in this diff.

Notes on things I checked and am satisfied with:

• C89: all new declarations (list/count/i in GetCallbackTime, usecs/tick/clocks/period in TOMReadPIT, dst_phrase_mode, the two dst_x locals) sit at the top of their blocks. The declaration-after-statement in HalflineCallback is pre-existing context, not introduced here.
• TOMGetVP()/TOMGetVI() substitutions (jaguar.c, dac.c) are required by the tom.c change — after the IODEC float-through, a bus read of VP/VI returns MEMCON1 — and are value-equivalent to the old masked bus read. One thing to grep before merge: that no other internal core code (OP, video, tests) still reads write-only video registers via TOMReadWord, since those now silently return MEMCON1 bytes. The two fixed call sites suggest you already swept this.
• dac.c change is read-path-only (same stored VP value, different accessor), and the validation lists both the clipping pair (Skyhammer, IS2) and the IS1 presence test, which satisfies the both-tests rule.
• MMULT wrap arithmetic (0xF1B000 | ((addr + 4) & 0xFFC), GPU equivalent) is self-consistent between the register write handler (gpu.c 0x08 case) and the opcode, and the persisted full address re-masks correctly on the next MMULT. The DSP-side register write handler isn't visible in the diff — if it still stores the raw written value while the GPU side now stores the masked full address, readback semantics differ between the two cores; likely intentional/harmless, but it's the one asymmetry I couldn't close out.
• TOMReadWord general path dropping offset &= 0x3FFF is safe: TOMReadByte masks internally and its special cases expect full addresses.
• Blitter DSTA2 fix selects the destination phrase mode/x consistently at both the lane-init and lane-advance sites; px_phrase is initialized (0) so the advance block can't read it uninitialized when the gouraud flags are off.

Scope caveat: 197 of the changed files (the entire app/ C++ side — EmuThread, FrameExchange, LateLatch, PacingClock, playlists, TV mode, Neuro) were truncated out of this review. The findings above cover only the core emulation sources, the acid runner, and the headers shown; nothing in the app layer has been reviewed.

_{4 generated/vendored file(s) excluded from review.}

_{Diff truncated before review — large PR. 197 changed file(s) not reviewed: app/src/pad_profile.h, app/src/perf.h, app/src/perf_trace.h, app/src/remap.h, app/src/video.h, app/src/window_chrome.h, app/src/debug/audio_ring.h, app/src/debug/debug_session.h, app/src/neuro/neuro_actions.h, app/src/neuro/neuro_agent.h +187 more.}

[JoeMatt]

Checked the findings in the earlier review and the follow-up review against release head 2165519e, with a fresh build and build-identity verification.

• MEMCON1 masking finding is invalid. 0xFFFE clears all bits above bit 15: 0xF00026 & 0xFFFE == 0x0026, not 0xF00026. Thus TOMReadable() returns false for that write-only offset and the MEMCON1 fallback is reachable. Existing test/test_tom_readback.c::memcon_fallback exercises full 0xF00000 + offset addresses across nine undecoded/write-only offsets, high/low bytes, words, longwords, and changing MEMCON1. All five TOM readback test groups passed, zero failures/skips.
• Zero-prescaler concern is invalid. Read directly from the primary Technical Reference Manual v8 PDF, page 16, PIT[0-1]: “If the first register contains zero the timer is disabled.” Existing TOMResetPIT() also only schedules a callback for nonzero tomTimerPrescaler; the read guard matches that existing scheduling behavior. The full-width/disabled-counter test passed.
• Event times are remaining times. SubtractEventTimes() subtracts elapsed time from every eventTime; GetCallbackTime() reads that remaining value.
• MMULT matrix counters are serialized. GPUStateSave/GPUStateLoad and DSPStateSave/DSPStateLoad explicitly save/load gpu_pointer_to_matrix and dsp_pointer_to_matrix. All eight MMULT regression tests passed, including consecutive multiplication, row/column modes, wrap and address-counter save/load round trips. DSP MTXA writes already use 0xF1B000 | (data & 0x000FFC).
• Internal video reads were checked. VP/VI use the new internal accessors. The remaining fixed-address internal TOMReadWord(0xF00006, ...) reads VC, which is readable; other call sites are generic bus dispatch. No additional fixed-address internal read of a write-only video register was found.

No emulation source change is justified by these findings. Logs: vj1042-tom-review-test.log and vj1042-mmult-review-test.log retained locally. The app-file truncation remains a real coverage limitation of these bot reviews; the separately documented app tests/reviews are separate evidence, not a claim that this bot reviewed those implementations.

[JoeMatt]

Completed a separate review of the app areas omitted from the truncated bot review: emulation-thread ownership/lifecycle and frame handoff, audio/snapshots, playlist/disc/state ownership, achievement callbacks and event lifetimes, Neuro transport/actions/profiles, controller holds and release guards, desktop/TV focus and library launches, pacing/late latch, and shared window/build changes.

Found and fixed: parseHex converted profile addresses/CRCs to 32 bits before checking their range. A watch at 0x100000100 silently became RAM address 0x100; fractional numeric addresses were accepted too. Commit 444ee32 rejects non-integer, non-finite, negative and overflowing values before conversion. Four new assertions failed against the previous parser; the fixed Neuro unit and loopback tests pass. No other demonstrated app defect was found in this review.

Validation: fresh app build completed; the full CTest run passed 159/160, with the sole Neuro failure traced to an old parser object compiled during the initial build before the fix. After rebuilding the parser in both the app and test targets, all three Neuro tests passed. All 160 distinct app checks are validated. The core/harness inputs are unchanged, so the previously refreshed private-ROM matrices remain applicable.

CI: the reported package-template failure was ruby: command not found on the temporary runner. Ruby is installed there, and b8164d8 makes the dependency explicit for future runners. Both Homebrew files are now checked separately (ruby -c file1 file2 only checked the first). The same commit consolidates four lightweight source-validation jobs onto one runner, retaining all ten original validation/install commands and independent failure reporting. Platform build/test coverage is unchanged. Workflow validation and locally rendered manifest checks pass.

The app-review hold is cleared. Merge still waits for all fresh applicable PR and Release checks on b8164d8 plus any new review feedback. No final tag/publication is authorized.

[JoeMatt]

Consolidated duplicate app-package builds in 2e46ca4.

For a same-repository release/** PR whose merge tree exactly equals its head tree, the PR now verifies and links the Release push workflow's package set. Other PRs, forks, manual app builds, and merge trees containing different content keep independent package builds.

The shared PR gate requires the newest exact-head/branch/repository Release push run, all twelve package/runtime jobs successful, and all six nonempty, unexpired package artifact groups. Pending/failing/cancelled/skipped jobs and missing artifacts cannot pass. It rechecks live head/tree and rerun attempts. The waiting gate uses a hosted runner so it cannot occupy the Studio runner needed by Release metadata jobs.

Native app tests/TSan, all Release packaging tests, signing, artifact names/14-day retention, and release artifact/checksum collection are preserved. The sticky PR download comment points directly to the canonical artifacts (shared filenames use prerelease). This replaces twelve duplicate package jobs with a planning job and one waiting verifier: ten fewer runner allocations per eligible PR.

Validation: 17 safety tests pass, Node syntax and actionlint structural/expression checks pass. A read-only live API check confirmed #1042's matching tree and correct canonical-run selection; it correctly refused readiness while package jobs remained pending. Fresh CI is now required on 2e46ca44; merge remains gated on the complete latest PR and Release results. No new builds were dispatched manually.

[JoeMatt]

Production core CI consolidation is now pushed in 3c68316.

For same-repository release PRs whose synthetic merge tree exactly matches the head tree, C/C++ CI now reuses ten compile-only Release targets: macOS Intel, WASM, four Android ABIs, iOS, tvOS, Vita, and Switch. This saves eight runner allocations per eligible PR. Other PRs, forks, manual runs, and differing merge trees retain independent builds.

The seven native compiler/test rows and their production → TEST_EXPORTS → production transitions remain unchanged, as do MSVC, sanitizers, coverage, clang-tidy, and SwiftPM. Android SIMD assertions and Mach-O production export checks also run on the canonical Release builds. A workflow contract checks matching compiler/SDK settings before sharing is allowed.

The new Verify and retain shared production cores check must pass: it verifies the exact-head Release push run, successful canonical jobs, all ten raw and ten shipped artifact groups, and downloaded binary provenance/hash/production ABI metadata. It then uploads the original ten C/C++ artifact names. Final Release archives, split-debug artifacts, and checksums are preserved; raw intermediates are excluded from final release assets. The existing shared app-package verification remains required too.

Validation: 30 Node safety tests pass, the Ruby workflow/toolchain contract passes, workflow structural/expression lint and shell checks pass, and the original compiler matrix/native test steps were compared against the prior version. No emulator source or boot-matrix inputs changed. Fresh PR and Release CI must finish before merge.