What’s in the lineup

Seven sets, live since v0.6.9-ps1 and current as of v0.6.10-ps1:

Two scene names were left out on purpose. visitor2, activity2, and activity3 have no FG2 packs on disc — including them in a pool would risk a pack-start failure on a random pick — so the pools follow the shape of the actual asset table. Suzy and Miscgag were combined because each family alone is only two scenes; combined they’re a believable rotation.

Why ship pre-validation

Scene Set is a random-rotation pool selector, not a scene viewer. The runtime cost of a not-yet-validated scene is the same as a validated one: load the FG2 pack, play it, tick the calendar. The visuals may not be pixel-perfect, the SFX may need rework, but the scene plays. As soon as a scene moves from ⏳ to ✅ in the scene ledger, it looks right in whichever pool already contains it.

The alternative was empty pools that fall back to All Scenes until their family validates. The selector framework supports this — the fallback already exists at jc_reborn.c:281 — but the menu would have five rows that all played the same content, which is exactly the “why are we showing this option” UX problem we built the pool labels to avoid. Real scenes from day one is the better trade.

How the framework holds up

The original Scene Set design doc said adding a set should be a one-line entry in gSceneSetPools and a one-line entry in kSceneSetNames. That held. The expansion patch is 60 lines of diff: five kSet<Family>Scenes arrays, five new pool entries, five new label strings, and an updated table in the pause-menu reference. No engine changes, no new pipeline, no walk-or-frog-clock surgery needed.

The on-disc FG2 catalog also held. Every scene named in any pool already had its pack shipped — there was nothing to bake, no asset re-work, no cd_layout.xml edit. That’s the dividend of the FG2 + pack-start design choice, and it pays off here: the playable catalog has been ahead of the validated catalog for a while, and the Scene Set framework is just the first feature that makes that gap user-visible in a useful way.

Scene Set: pool-by-category

The screensaver loop has always picked from a pool called kProvenScenes. As more scenes get validated the pool grows, but the shape stays the same: one big bag, the loop draws a random scene out of it, the FG2 pack plays, the loop ticks the calendar, and around it goes. There was no way to say “I’d like the next half hour to be fishing scenes only” without forcing a pinned scene from the dev console — which then plays the same scene every iteration.

Scene Set lifts that into a first-class menu item. The new item sits right under Resume, defaults to All Scenes, and the only other ship-quality alternative right now is Fishing Only — the eight validated fishing1..fishing8 packs. As more scene families lock in, they get a one-line entry in gSceneSetPools and a label in kSceneSetNames, no other code changes needed. The picker reads pauseMenuSceneSet each iteration and indexes into the pool array.

The interaction model is deliberately different from the rest of the main menu. Left and Right scroll a pending preview, which the row shows as <Fishing Only> with an asterisk if the preview hasn’t been committed yet. Cross or Start commits. Up or Down (which moves the cursor off the row) discards the preview. That separation matters because the alternative — “scrolling lands you in a new pool immediately” — felt like an accidental click hazard the first time the row got tested. The brackets are the visual cue that this row takes horizontal input; everything else still uses Cross-to-select.

Frog clock as a real animation

The PS1 port has had a “meanwhile” frog-clock loading frame since the freeplay branch landed. Up to today it was a single static image: load MEANWHIL.BMP, draw the card sprite at (254, 100), draw one fixed hand frame at (287, 141), and call it done. It looked like a paused clock, which is exactly the wrong feel for a loading transition.

Replacing the static draw with a hand-cycle was a one-line change in isolation. Replacing it with a hand-cycle that looked right needed the original script. MEANWHIL.TTM carries 16 hand sprites split between an hour-hand set (sprites 5–16) and a minute-hand set (sprites 1–4), and the script draws each frame at a sprite-specific (x, y) because the bounding box of a rotated hand changes per angle. Drawing every hand frame at the same top-left position made the hand visibly drift around the clock face on each frame.

A short Python decoder over the TTM bytecode pulled out the per-sprite draw positions; they’re now a static kMeanwhilePos[17][2] table inside grShowMeanwhileLoadingFrame. The animation cycles the hour hand every four frames and the minute hand every frame, for a loop of 36 vblanks (~0.6 s at 60 Hz). On each frame: stamp the card, then the current hour hand at its baked anchor, then the current minute hand at its baked anchor.

Walk vs frog clock: why the cycle does a sequence reset

The honest part of this post is what happened when those two features met for the first time.

Cycling Scene Set fires the frog clock as its loading transition. The frog clock calls grInitEmptyBackground to give the card a clean black backdrop — that zeros the four background tiles in RAM. That was always the case; the change is that the next thing now is a walk transition (the screensaver loop tries to walk Johnny from his last spot to the new scene’s start). And the walk subsystem composes Johnny over those background tiles. Black tiles → black borders around Johnny.

The first attempt was to snapshot the tiles before the wipe and restore them after. On desktop that’s a nothing change. On PS1 it’s 600 KB of memcpy across four bgTile* buffers, and the heap is already tight enough that the snapshot allocation introduced a noticeable hitch on the first cycle of the run. Restoring also didn’t fully solve the problem because the rect-mode clean buffers walk actually reads from are not the same set as the full-tile clean buffers grSaveCleanBgTiles populates.

The fix that actually worked is structural. Cycling Scene Set is a sequence reset by definition: the user just told the loop to throw out its remembered context. So pauseMenuRequestSceneSetCycle consumers now also clear storyCurrentSpot and storyCurrentHdg and set fgLoopSequenceJustReset = 1. With the reset flag set, the existing guard at the top of the loop skips the walk for that iteration. The next scene’s foregroundPilotPlay does its own grLoadScreen and pulls the bg back to a known good state before any compositing happens. No 600 KB snapshot, no walk corruption, no extra moving pieces.

Walks resume on the very next iteration because the next scene updates storyCurrentSpot/Hdg on completion, so the user-visible behavior is just: change the pool, see the frog clock, see “Scene Set: Fishing Only” caption, see a clean cut to the next fishing scene.

What this is not

This release does not add new scene sets beyond Fishing Only. Johnny-only, Mary-only, and Visitors-only sets are obvious next steps, but they need their own scenes validated under the Scene Set flow before they ship. The gSceneSetPools table is structured so that adding them is a label and an array literal, not a rewrite. This release also does not add a separate art asset for the animation; the frog clock uses Sierra’s existing 17-frame MEANWHIL.BMP exactly as shipped.

The PS1 port keeps trying to make every player-visible feature land on top of the same handful of trusted runtime pieces. A new menu item and a smarter loading frame are exactly the kind of additions that should not need new pipelines, and after today they don’t.

Why ocean, and not music

The PS1 has three independent audio paths: the SPU (dedicated coprocessor with 24 voices, 512 KB of its own RAM, and hardware loop flags built into the ADPCM block format), CD-DA (Red Book audio decoded by the drive), and CD-XA ADPCM (decoded by the drive too, interleaved with data sectors). Each has trade-offs; all of them could play music. The reasons we picked ocean ambience as the v0.6 ship instead of “background music” in general:

• Spectrum. Ocean recordings live below ~1 kHz. Sony 4-bit ADPCM’s quantization noise is loudest above ~4 kHz. On ocean material the compression is essentially transparent at 11.025 kHz mono — the tradeoff that would hurt a music track is invisible on this material.
• Loop forgiveness. Wave patterns are aperiodic. A loop seam on music with a clear meter is obvious; on ocean it disappears under the broadband noise. We didn’t need the seamless-loop acrobatics that a music track would demand.
• Reverb is the recording. The SPU has a hardware reverb unit. Music typically benefits from it. Ocean ambience already is the spatial sound — we don’t apply reverb on top, and we get the SPU RAM the reverb workspace would have used back.
• Mood matches the screensaver. A castaway on a tiny island, ocean playing quietly underneath. That’s the fiction. Anything else would have been music laid on top of it.

The mechanism: pre-loaded ADPCM in SPU RAM

Of the five PS1 audio paths, exactly one delivers strict zero CPU per frame: pre-load an ADPCM-encoded sample into SPU RAM at boot, set the loop flags on the first and last data blocks of the sample, key on a dedicated voice. The SPU plays it forever in hardware. The CPU never sees another byte of audio work.

Compared to the alternatives:

• SPU streaming from CD would let us fit hours of music in 16 KB of SPU RAM, but it costs ~10-20 cycles per chunk-finish IRQ plus steady CD bandwidth competing with the FG2 prefetch the screensaver loop already uses. Not zero CPU.
• CD-DA (Red Book) is gorgeous and free of CPU cost but the PS1 drive can’t read data and play CD-DA at the same time. Enabling it would kill the FG2 prefetch and break scene playback. Wrong fit for our streaming pipeline.
• XA-ADPCM interleaves audio with data sectors — hardware decode, zero CPU, compatible with prefetch. The right answer for “many tracks”, but it adds mkpsxiso XA-track authoring complexity for capability v0.6 doesn’t need.
• Sequenced (SEQ/VAB / MOD) gives the deepest expression but a sequencer ticks the CPU 1-3 ms per VBlank. Real per-frame cost.

Pre-loaded ADPCM in SPU RAM was the only choice that delivered the zero-CPU contract without changing the disc authoring pipeline.

The loop: 20 seconds, crossfade-replace at the seam

The ocean recording is from BigSoundBank sound 0266 — “Sea: Waves”, CC0 public domain. Moderate waves, swirls, no birds, no breakers. 57 seconds of source material at 44.1 kHz stereo.

The naive plan was a 60-90 second loop with a fade-in/fade-out at the seam. That was clean but had audibly-quiet silence at the wraparound — the listener could hear the loop boundary even if the seam was click-free. We swapped to a 20-second loop with a 1-second equal-power crossfade hidden at the start of the body:

Source S (continuous waveform):
    ... A A A B B B C C C D D D E E E F F F ...
                |---------- 20 sec body -----------|--- 1s tail ---|

loop[i] = body[i] * sin(πi/2N) + tail[i] * cos(πi/2N)   for i in [0..N)
loop[i] = body[i]                                       for i in [N..]

When the SPU loops loop[end] → loop[0], the listener hears: end of body → tail fading out (which is what would naturally have come next in the source) → body fading in. By the time the crossfade has fully exposed the body, we’re past the seam. For ocean material this is functionally invisible — the seam buries itself in broadband noise.

Bonus: a 20-second loop is ~123 KB instead of the original sketch’s ~370 KB. That ~250 KB savings in SPU RAM is enough room for 2-3 additional ambience tracks under the same toggle mechanism if we ever want them (calmer, stormier, holiday-tagged). The encoding pipeline (scratch/ocean-ambience/make_tight_loop.py + encode_vag_loop.py) is already general-purpose — drop any mono 16-bit WAV in, get a tight loop VAG out.

The toggle: pause-menu, memcard, zero-flicker

Pause → Accessibility → Ocean: ON / OFF. LEFT, RIGHT, or X on the row toggles oceanAmbientEnabled and immediately calls oceanAmbientStart() / oceanAmbientStop(). The SPU voice keys on or off in one register write — no fade, no clicking, no audible delay. The Save Settings to Memcard option persists the choice (MC_VERSION bumped 2 → 3, with a graceful v2-load fallback that defaults the new field to ON). On the next boot soundInit reads the saved value and either auto-keys the voice or leaves it silent.

The wiring mirrors the existing soundMuted accessibility toggle — same accessor pattern, same memcard schema bump, same register-write toggle. About 200 lines net across five files.

Frame impact: zero, verified

The screensaver’s JCPERF2 per-scene metrics (loop_vb, blocking_vb, overrun_vb, compose_calls, etc.) are identical with the ambience on or off. The SPU mixes its 24 voices in hardware regardless of how many are active; an additional voice costs nothing. The loop wraparound is a single bit-flag check the SPU hardware does at the end of each ADPCM block; no IRQ, no DMA, no CPU.

The total cost is ~123 KB of SPU RAM + ~30-60 ms of additional boot time (the extra CD read and DMA upload of OCEAN.VAG into SPU RAM). After boot, no impact at all.

What the headroom leaves

The SPU has 512 KB of RAM. Existing SFX uses ~94 KB. The ocean loop uses ~123 KB. After both, ~257 KB is still free — enough for 2-3 additional 20-second ambience tracks under the same pause-menu toggle, switching tracks via a single SPU_KEY_OFF/SPU_KEY_ON pair. The pause-menu toggle could naturally extend from ON / OFF to a short list (Off / Ocean / Calm / Stormy) without changing the underlying mechanism. Nothing in v0.6 forces that direction; the headroom is just present if we want it.

Alternately, the same SPU RAM budget supports holiday-tagged ambience (the holiday system already carries per-holiday metadata in gHolidays[]; an optional ambience index per holiday would swap loops at scene boundaries) or short scene-start stings on spare voices. These are future work; v0.6.0-ps1 ships exactly one CC0 ocean loop and a binary toggle.

So the test harness grew a controller.

The PS1 build now has an opt-in pad-script layer. At build time, config/ps1/PADSCRIPT.TXT is embedded beside BOOTMODE.TXT. At runtime it does nothing unless the boot string includes pad-script or pad-script-log. When enabled, it merges scripted button masks into the same active-high controller value that the real pad uses. Start is still Start. Cross is still Cross. The menu code does not get a fake API.

That small choice matters. A host-side key injector would test DuckStation window focus. This tests Johnny.

The first harness script boots a normal foreground scene, waits 30 seconds, presses Start, walks the major pause-menu screens, and drops JCPADSHOT markers into the PS1 TTY log. DuckStation regtest captures frames every few VBlanks. Each marker is delayed until the target menu has had time to draw, and the reporter copies the first dumped frame at or after that point before rewriting the menu help guide.

That gives the project a new kind of documentation: generated from the running disc, checked by the same deterministic tooling we use for regression work, and useful to a human who just wants to know what the System menu does.

The loop is deliberately boring:

wait 30s
tap START
tap DOWN
tap DOWN
tap CROSS
shot freeplay-options 30

The power is in the boring part. Once a menu path can be written down as button presses, it can become a test case, a screenshot, and a release artifact. If a future refactor breaks Circle as Back, the harness gets stuck. If a sub-screen grows too tall, the screenshot makes it obvious. If Start stops working on the SPI pad path again, no guide page gets produced.

That is the whole philosophy of this port in miniature: make the PlayStation do the thing, make it repeatable, and then let the artifact tell the truth.

The full operational reference is now Scripted input harness.

That sounds small until you look at what the PS1 runtime had become by this point. The ordinary scenes are carefully captured foreground streams. They are deterministic, measurable, and repeatable. Freeplay is none of those things. It reads the controller every frame, moves Johnny around the island, lets the player fish, opens debug catalogs, changes the tide and holidays, and then has to cleanly hand the whole machine back to the normal random screensaver loop.

The breakthrough was not making the controller move a sprite. The breakthrough was refusing to make a second engine. Freeplay reuses the same pieces that made walking safe in v0.4.20: a known island backdrop, sparse clean rects, the shared walk renderer, holiday stamping, captions, SPU sound, and the pause menu. It is live C code, but it stands on the replay runtime instead of fighting it.

The control scheme got smaller

The early builds tried to use the whole controller. Gags on face buttons. Summons on face buttons. L1 shortcuts. R1 shortcuts. Context-sensitive Cross. Combos. It was technically cute and practically awful.

The current version is deliberately simpler:

• D-pad or analog walks Johnny.
• L2 slows him down.
• R2 speeds him up.
• Circle fishes.
• Select clears and rebuilds the freeplay screen.
• R1 plus D-pad changes the four world states: day/night, tide, raft, and holiday.
• Start opens the pause menu.

Everything else moved into menu catalogs. That was the right split. The controller is for the things a player does while looking at Johnny. Catalogs are for actions that need names, descriptions, source asset filenames, frame counts, and memory notes.

The pause menu became a debug cockpit

Freeplay Options now owns Gags, Visitors, Controls, and Clear. Gags and Visitors are selector pages: title, BMP, frame count, rough memory cost, description, and “X spawn now.”

That sounds like UI polish, but it is also engineering leverage. A failed visitor load can skip cleanly instead of crashing. A bad frame range can be identified by name instead of by button folklore. A sound can be tested from the sound-test menu without needing to stumble into the one original scene that plays it.

Circle is Back everywhere. That rule matters more than it sounds. A debug mode that needs a handwritten controller legend every time you open it is not finished.

The frog clock became the transition contract

Freeplay has several expensive boundaries:

• enter from an arbitrary screensaver scene;
• exit back to the normal loop;
• clear the freeplay screen;
• apply world options from the pause menu.

Those boundaries now show the original meanwhile frog clock. It is the right visual language for Johnny, and it also tells the tester that the runtime is doing real teardown/rebuild work rather than freezing.

The memory rule is strict: the frog frame uses a temporary TTtmSlot, draws one frame, and releases MEANWHIL.BMP unconditionally. It is a loading frame, not a permanent resident.

Memory was the real feature

The freeplay bug reports were exactly the kind of bug a forever-running PS1 program deserves: black pixels left by an overlay, a delayed second entry that looked like a freeze, and a crash after leaving freeplay once.

The fixes tightened the shape of the mode:

• overlays mark their screen-space rows dirty before present, so captions and banners do not leave stale pixels behind;
• freeplay hard-frees its clean-rect snapshot on exit instead of leaving a dormant 300+ KB allocation parked in the heap;
• default entry/exit no longer runs largest-heap probes, because probes are malloc/free cycles and therefore part of the thing being tested;
• heap probes remain behind freeplay-log, freeplay-detail, and freeplay-debug;
• movement, ticking, and drawing do no allocation in the steady-state frame loop.

That is the bar for this project now. If a feature only works for five minutes, it does not work.

What got signed off

The last visual pass was the important one because the remaining bugs were all “forever program” bugs, not feature-checkbox bugs:

• entry from the normal pause menu shows the frog immediately;
• exit from freeplay shows the frog before the screensaver loop resumes;
• second entry no longer has a dead pause that reads as a freeze;
• world options apply immediately in freeplay;
• R1 plus D-pad changes day/night, tide, raft, and holidays immediately;
• Select clears the screen and rebuilds the island;
• waves run at the same visual cadence as the screensaver path;
• the frame loop stays allocation-free unless telemetry is explicitly enabled.

That is the v0.5.0-ps1 milestone: the first version where Johnny Castaway on PS1 is not just watching the island, but walking around on it.

1. Working PS1 printf() to TTY

• PSn00bSDK + DuckStation now reliably emits printf() output to TTY logs. Earlier in the project this had been intermittent / unreliable — the same call would surface in some build/runtime configurations and silently drop in others.
• This is the single largest unblocker for the rest of today’s work. Instrument-based perf debugging, JCPERF/JCPERF2 line mining, and one-shot snapshots like JCPAUSE are all only useful once printf is trustworthy.
• See docs/ps1/current-status.md “Known limitations” for the older caveat (gated probes only); that paragraph is now stale and is being updated alongside this milestone.

2. Performance baseline + Docker regtest pipeline

• New src/ps1_perf.c/h module landed with a level-gated logging API: ps1PerfSetLevel(level) switches between OFF / SUMMARY / DETAIL / DEBUG. Boot-token aliases (perf, perf-detail, perf-debug) are parsed by the existing BOOTMODE.TXT path so an external operator can pick a level without recompiling.
• TTY emits structured JCPERF / JCPERF2 lines per scene (loop_vb, target_vb, blocking_vb, hidden_vb, due_misses, render/held entry counts, CD bytes, restore/upload bytes, etc.). These lines are designed to be mined by an external agent — every field is a stable, greppable key=value pair.
• scripts/regtest-*.sh ride on top of the existing DuckStation-headless Docker image. Frames dump on a fixed interval, TTY captures to stdout, state hashes capture at exit. Combined, this gives a single command that produces both visual diff inputs and machine-readable perf baselines for a regression run.
• See the performance optimization plan for the optimization backlog being driven by these numbers.

3. Pause menu — first real user-facing UI (SHIPPED)

• Pressing Start now opens an overlay during scene playback. Items: Resume / Sound / Day-Night override (AUTO/DAY/NIGHT) / Holiday override (AUTO/NONE/HALLOWEEN/ST PATRICK/CHRISTMAS/NEW YEAR) / Save Settings to Memcard / Reset Screensaver Loop / Next Scene / TTY Perf Log (OFF/SUMMARY/DETAIL/DEBUG) / Debug Info / Set Time-Date.
• Custom font path (shipped): embedded 8x8 ASCII glyph table (pmFontBits[96][8] in src/pause_menu.c), pre-doubled to 16x16 at upload time (pmUploadFont), drawn glyph-by-glyph via manual SPRT primitives (pmTextDrawChar). PSn00bSDK’s FntFlush was empirically broken in the scene-runtime context — it accumulates primitives without producing any visible pixels — so the in-tree font path replaces it entirely.
• Panel rendering (shipped): translucent dim quad (POLY_F4 semi-trans black) under an opaque purple panel with 12-pixel chamfered corner cutouts (3-rect rounded-rectangle look), drawn over the live scene every paused frame.
• Sound mute (shipped): SpuSetCommonMasterVolume is not honored by DuckStation HLE, so the mute path zeros every voice volume + CD vol + master vol and clears the master-enable bit in SPU_CTRL via direct register writes.
• Day/Night and Holiday overrides (shipped): flow into fgLoopApplyVariant in src/jc_reborn.c with priority explicit menu override > Set Time/Date soft override > random.
• Files: src/pause_menu.c/h. Design: pause menu design.

4. Holiday expansion — 4 → 35 design

• The existing four holidays (Halloween, St Patrick’s, Christmas, New Year) covered fewer than half of the calendar months. The new design doc proposes 35 US-centric holidays with at least one per month and an average of about three.
• Mix is federal + pop-culture + seasonal (e.g. Pi Day, Talk Like a Pirate Day, Star Wars Day, Moon Landing Day) so the screensaver always feels seasonally alive rather than dead-stretches between the four legacy events.
• Design: holiday expansion design. Implementation is not in this batch.

5. SPI direct controller polling

• The BIOS pad system (InitPAD / StartPAD) was empirically broken in our PSn00bSDK 0.24 + DuckStation environment. Replaced with PSn00bSDK’s reference SPI driver — timer-2 + SIO0 IRQ-driven, polling at 250 Hz.
• One critical bug found while porting: spicyjpeg’s reference uses tx_len=4, but DuckStation’s controller emulation only delivers button bytes when the full 5-byte poll sequence comes from the TX buffer (tx_len=5). That single off-by-one is what surfaced as “Start does nothing” during early pause-menu wiring.
• Files: src/spi.c/h, integrated into src/events_ps1.c. The pause menu, day-night override, and any future input feature all sit on top of this driver.

6. Memcard support (SHIPPED)

• src/memcard.c/h saves user pause-menu settings (sound mute, day/night override, holiday override, soft time/date) to a single 8 KB block on memcard slot 1, file name BASLUS-99999JCREB.
• Avoids the BIOS card driver entirely (InitCARD / StartCARD / _bu_init / file API). The BIOS driver installs a persistent VBlank handler that fights our 250 Hz SPI controller-polling timer and tanks scene framerate. Instead, memcard I/O rides on top of our existing SPI driver via SPI_CreateRequest queue + raw byte sequencing per the nocash memcard protocol.
• During memcard ops the SPI poll rate drops 250 Hz → 50 Hz: a single card transaction is ~5.5 ms, longer than the 4 ms timer-2 tick that drives the controller poller, so we widen the tick to give the card exclusive SPI bus time.
• Save block carries a proper PS1 save header (SC magic + title + icon frame count + 16-color CLUT) with a hand-drawn 16x16 palm-tree icon, so the save shows up in the BIOS Memory Card Manager like a normal game save.
• Boot-time auto-load: if a save exists, settings are restored before the scene loop starts. The Save Settings menu entry writes; reads happen automatically at boot.

7. TTY log prefixes

• The complete set of greppable log-line prefixes after this batch: JCSPI (controller driver), JCPAD (pad layer), JCBOOT (boot / bootmode), JCPERF / JCPERF2 (perf module), JCPAUSE (pause-menu one-shot snapshot), JCMC (memcard). All are stable key=value pairs intended for external perf-debugging agents.

Pointers

• Design backbone: pause menu design, holiday expansion design, performance optimization plan
• Status frame: current status, scene status
• Workflow: development workflow

• Outcome so far
• Evidence gathered
• What the probe grid currently tests
• What’s been tried that did NOT work (this session)
• Recommended next steps
• Fix candidates that are still on the table
• Probe infrastructure already in place (keep)
• Boot-hang root cause (solved)
• Debugging lessons learned
• Resolution (landed this session)
  • 1. Pre-load BACKGRND.BMP before bg-tile allocation
  • 2. Wave-tick parity with the normal ads path
  • 3. Rect-based clean backup (option B)
  • Div-by-zero guard
• Open follow-ups for subsequent sessions

Outcome so far

• Root cause of “no waves” found: ttmBackgroundSlot.numSprites[0] == 0 after adsInitIsland() returns. Every downstream wave draw bails at the numSprites==0 check in grDrawSprite.
• Root cause of the empty slot: grLoadBmp(&ttmBackgroundSlot, 0, "BACKGRND.BMP") inside islandInit cannot allocate enough contiguous heap for either (a) the ~93 KB BACKGRND.PSB stream read or (b) the ~150 KB raw BACKGRND.BMP fallback. Slot is never populated.
• The BMP/PSB files ARE on the CD. ps1PilotActivePack.entries is NULL on this path (fgpilot, pre-scene), so the “pack is authoritative, skip CD fallback” early-exit is NOT firing. The failure is purely heap pressure.
• The other fishing1-path BMPs (TRUNK, MRAFT) are ~10 KB and load fine; BACKGRND is ~10× bigger and is the only one hitting the heap ceiling at that moment in the scene setup.

Evidence gathered

Ran a progressively larger on-screen probe grid (described in detail below). Key findings verified on DuckStation:

• Heap ceiling: malloc succeeds for 4K/32K/64K/93K, fails for 150K.
• Stream-read ceiling: ps1_streamRead("PSB\\BACKGRND.PSB", N) succeeds for N=4K/32K, fails for N=64K/93K.
• The stream ceiling is lower than the raw-malloc ceiling because ps1_streamReadFromCdFile allocates twice: a sector-aligned staging buffer AND a size-exact output copy → peak ≈ 2× requested.
• findBmpResource("BACKGRND.BMP") returns non-NULL, has numImages>0 and uncompressedSize>0, but uncompressedData stays NULL after load (status code 4 = “no BMP bytes after load”), consistent with the stream/malloc pair failing.

What the probe grid currently tests

A compact row of 10 colored squares at screen y=172 (green = yes/pass, blue = no/fail):

• T27 malloc(4 KB) — heap baseline
• T28 malloc(32 KB)
• T29 malloc(64 KB)
• T30 malloc(93 KB) ← PSB file size
• T31 malloc(150 KB) ← raw BMP file size
• T32 ps1_streamRead("PSB\\BACKGRND.PSB", 4 KB) — stream baseline
• T33 ps1_streamRead(…, 32 KB)
• T34 ps1_streamRead(…, 64 KB)
• T35 ps1_streamRead(…, 93 KB) ← exact PSB full read
• T36 ttmBackgroundSlot.numSprites[0] > 0 ← end-to-end success signal

If T30 green + T34/T35 blue + T36 blue: “heap OK for a 93 KB lump, but the 2×-alloc stream read can’t fit”. That’s the fix target.

If the stream path is reduced to a 1× alloc peak (either via memmove or read-direct-into-target), T34/T35 should flip green and T36 should follow.

What’s been tried that did NOT work (this session)

All three attempts below hung on the title screen — they never got to the fishing1 scene. The fix must come later, carefully.

1. Load BACKGRND.BMP before grLoadScreen(OCEAN) in islandInit (with MRAFT shuffled to slot 1 so it wouldn’t clobber slot 0). Hung on title. Most likely grLoadScreen then failed because the 93 KB PSB held the big heap lump.

2. Rewrite ps1_streamReadFromCdFile to split head / bulk / tail sectors and read directly into the output buffer. First attempt had a buffer-overflow bug (bulk chunk writing past size for non-sector-aligned reads); second attempt was functionally correct in paper trace but still hung on title. Probable cause: doing multiple short CdControl+CdRead cycles for the head/tail splice changes PS1 CD controller state enough that something early in boot (likely in parseResourceFiles or similar very early path) hangs.

3. Simpler rewrite: keep the original read loop but skip the second malloc and return the sector buffer after an in-place memmove. Also hung on title. Unclear why — memmove semantics should be identical to the old read-then-memcpy path.

Given attempts 2 and 3 broke the title boot but were logically equivalent to the original for offset==0 reads (which is what the title path uses), something unrelated to streaming is being affected by our build changes. Could also be an incidental BSS / code-size issue flipping something about how the PS1 loader lays out the binary.

Recommended next steps

• Revert cdrom_ps1.c to its last clean state. Keep only the probe row (T27-T36) + supporting accessors.
• Rebuild. Confirm title boot works and fishing1 scene reaches compose (even without waves, as the probe row proves we’ve seen before).
• Only then attempt the streaming / memory fix. Before each new attempt, run just that change and confirm boot still works — do not stack multiple changes into a single test.

Fix candidates that are still on the table

1. Free the OCEAN0X.SCR clean tiles before the BACKGRND load — grLoadScreen keeps ~600 KB of bgTile + clean-tile memory live. If we could free those temporarily, the 93 KB PSB stream’s 2× peak would fit.
2. Pre-load BACKGRND.BMP earlier, before grLoadScreen runs — but without breaking the OCEAN SCR load that immediately follows.
3. Use the ps1_streamReadFromCdFileIntoBuffered variant — caller-provided sector buffer, no malloc in the inner path. Requires plumbing through grTryLoadPsb / grLoadBmpRAM.
4. Skip grLoadScreen(OCEAN) altogether in the fgpilot path — compose the ocean base from a smaller source (or use ISLETEMP.SCR which already has the ocean baked in). Then we don’t fight the OCEAN SCR for heap.
5. Shrink one of the other persistent large allocations — e.g. the title screen buffer if still held, or reduce the number of clean bgTile copies.

Probe infrastructure already in place (keep)

ads.c exposes accessors used by the probe row:

• adsDbgAlloc4K/32K/64K/93K/150KOk()
• adsDbgStream4K/32K/64K/93KOk()
• adsDbgBackgroundSlotSpriteCount()

And the one-shot adsDbgRunProbesOnce() runs on the first compose frame (cached thereafter), so the probes don’t thrash per-frame.

Boot-hang root cause (solved)

While isolating “HEAD + FISHING.ADS name fix” from everything else, we proved the title-to-scene hang is caused by integer division by zero in islandAnimate when BACKGRND.BMP fails to load.

island.c’s islandAnimate does:

grDrawSprite(grBackgroundSfc, ttmSlot, waveX, waveY, waveSpriteNo, 0);
// ...
uint16 actualSpriteNo = waveSpriteNo % ttmSlot->numSprites[0];  // <- hang

Flow:

1. fgPlayOceanRuntimeScene calls adsInitIsland.
2. islandInit calls grLoadBmp(&ttmBackgroundSlot, 0, "BACKGRND.BMP"). Under the memory conditions present at this point in the fgpilot path, that load silently fails — the PSB path’s 2× stream alloc (93 KB + 93 KB) can’t find a free block, and the BMP fallback’s ~150 KB alloc also fails. ttmBackgroundSlot.numSprites[0] ends up 0.
3. islandInit then runs the initial-wave loop: for (int i=0; i < 4; i++) islandAnimate(ttmThread);.
4. islandAnimate’s grDrawSprite call is a silent no-op (the imageNo/numSprites guard inside grDrawSprite returns cleanly).
5. The very next line computes waveSpriteNo % ttmSlot->numSprites[0] — an integer % with divisor 0 on MIPS R3000 traps via the overflow/exception handler, which on this build effectively deadlocks the console (no handler progresses past it).
6. The main loop never starts, the title RAW framebuffer is never overwritten, so the user sees “stuck on title”.

Why it looked like a hang and not a crash: DuckStation keeps showing the existing framebuffer (title) if the guest CPU is stuck. From the outside it’s indistinguishable from a “600-second delay”.

Fix (in-session): add an early return guard in islandAnimate before the modulus operation:

if (ttmSlot->numSprites[0] == 0)
    return;
uint16 actualSpriteNo = waveSpriteNo % ttmSlot->numSprites[0];

This is defensive — it also protects any other path where the wave slot could be empty (e.g. a future scene pack change, or a CD read stall).

Debugging lessons learned

• On PS1 / this harness, “stuck on title” is always worth suspecting a guest CPU fault, not an I/O or logic wait. Division, modulus, null deref, and misaligned-load faults all end the same way from a host observer’s perspective.
• Add div-by-zero / null-slot guards around every % and array index whose divisor/index comes from ttmSlot->numSprites[...]. There are several of these in island.c, graphics_ps1.c (replay path), and potentially more — audit on a quiet day.
• When deciding whether a title stall is code vs. a deliberate I/O backoff, the fastest disambiguator is an on-screen probe row that updates every frame in foregroundPilotRuntimeCompose. If the row never appears, the compose loop never ran — which means either foregroundPilotRuntimeStart bailed, or the CPU faulted before we got there. Worth keeping a minimal probe row as standard debug scaffolding.
• A cheap way to confirm a CPU fault vs. a real hang in DuckStation: the console’s own CPU-exception handler is typically quiet on PS1 titles; but you can open DuckStation’s CPU debugger view (if available) or, more reliably, check whether the background audio / spinner continues ticking. Silent audio = CPU probably faulted.

Resolution (landed this session)

Fishing 1 now plays through the full scene with three shoreline waves animating in parallel. The fix is a clean three-part change:

1. Pre-load BACKGRND.BMP before bg-tile allocation

Added adsPilotPreloadBackgrndBmp() in ads.c, called at the very top of fgPlayOceanRuntimeScene — before fgInitVisiblePipeline runs and allocates the 614 KB of empty bg tiles. With a fresh heap at that moment the ~93 KB PSB (which peaks at ~186 KB during ps1_streamRead’s 2× alloc) loads cleanly.

Verified with pre-load heap-tier probes: all 4 KB / 32 KB / 64 KB / 93 KB / 150 KB / 200 KB allocs succeed at that moment. The naive placement (after scene setup) fails every tier above 64 KB.

2. Wave-tick parity with the normal ads path

Added adsPilotTickBackgroundWaves() (mirrors the inline tick block in adsPlay’s main loop). Called once per frame from the fgpilot main loop. With delay=2, islandAnimate advances one wave position every 2 frames and islandRedrawWave carries the last-drawn wave across the grRestoreBgFromRects-wiped frames in between.

Also: seed the clean baseline by calling islandAnimate 4× inside adsPilotEnableWaveBackdrop before the clean backup — same trick that islandInit uses in the normal path — so the restored baseline already has all three wave positions and they look parallel from the first frame.

3. Rect-based clean backup (option B)

Added grSaveCleanBgRects() / grRestoreBgFromRects() to graphics_ps1.c. Replaces the 614 KB of full-tile clean copies with a single 596×152 rectangle at (12, 204) — the union of the foreground pack bbox and the wave shore area. ~181 KB instead of 614 KB. That’s the headroom that lets the BACKGRND PSB coexist with everything else.

After the fix, at compose time all six malloc probes (4/32/64/93/150 KB) report green — heap is comfortable.

Div-by-zero guard

islandAnimate originally did waveSpriteNo % ttmSlot->numSprites[0] with no guard. If BACKGRND.BMP ever failed to load, that’s a MIPS integer-zero-division CPU exception — and on this build the exception handler effectively hangs. We saw that exact hang several times before we figured out it wasn’t an I/O wait. The safety-skip in adsPilotEnableWaveBackdrop bypasses the seed loop when numSprites[0] == 0, so a future load failure becomes “scene plays without waves” instead of “boot hang”.

Open follow-ups for subsequent sessions

1. Generalize the rect-based clean backup to other scenes. Each scene that uses the fgpilot path needs to declare its dynamic rect(s), and those rects must be computed relative to islandState.xPos/yPos and LEFT_ISLAND. For fishing1 (ELSE branch, no storyPrepareSceneBaseByAds call → islandState at origin) absolute coords work; for any scene that does shift the island, the rects need to shift too.
2. Remove the probe row and heap-tier diagnostic accessors once we’ve verified the fix on multiple scenes. They’re useful scaffolding but add noise to the binary + bg-tile dirty area.
3. Audit other %-by-numSprites sites (replay path, grRecordReplaySprite lookups, etc.) — any of them could hang if their backing slot ever turns out empty.
4. Consider a further scale-up: 1/64 grid of bg tiles so compositing
   • clean coverage naturally share the same fine-grain regions. The rect approach is a pragmatic middle step; the finer grid is the long-run generalization.

Goal

Get fgpilot fishing1 to:

• keep the current correct scene-relative foreground/tree occlusion behavior
• keep the current title -> scene handoff
• animate the island water/wave sprites correctly
• do it in a low-memory way that can scale to other scenes

Known Good Baseline

The last strong water-free foreground milestone is:

• 5ea67b35 Make Fishing 1 foreground packs scene-relative

This fixed the tree/Johnny mismatch by making the foreground pack scene-relative.

Other later committed milestones that are relevant to the current path:

• 44cec0a6 Restore ocean base under foreground runtime
• 27ac05c9 Keep title visible during staged island base loads
• 373c38ad Remove title-screen CD settle delay

User-validated integrated scene state before wave work:

• title screen -> scene handoff works
• ocean + static island base appear
• Johnny foreground pack works
• scene-relative tree occlusion works
• waves do not animate

What Has Been Proven

1. The wave primitive itself works on PS1

A sandbox worktree was created:

• workspace:/jc_reborn_wave_sandbox
• branch ps1-wave-sandbox

A minimal fgpilot wavetest was added there:

• black background only
• no island
• no Johnny
• no FG pack
• just 4 BACKGRND.BMP wave sprites drawn each frame

User validation:

• black-screen wavetest animated correctly
• after one bad island-pop regression, the corrected version was “super legit working”

So:

• PS1 can animate the wave sprites
• BACKGRND.BMP wave frames are valid
• the basic draw path works in isolation

2. The Fishing 1 integrated failure is not a host-data absence issue

Earlier investigations established:

• host source contains moving water pixels / wave draw state
• earlier BG1 / backdrop pack experiments did generate changing data
• wave data was not simply “missing”

3. Water failure is integration/runtime-side

Because black-screen wavetest works but integrated fgpilot fishing1 does not, the bug is in the integrated scene path:

• clean base construction / restore semantics
• when dynamic water is drawn relative to that base
• or how integrated runtime composition/upload suppresses or overwrites those changes

Current Technical Findings

grLoadBmp() is RAM-path only on PS1

In graphics_ps1.c:

• grLoadBmp() immediately calls grLoadBmpRAM()
• the old VRAM/OT path is disabled

That means grDrawSprite() for BACKGRND.BMP in PS1 normally goes through:

• grCompositeToBackground()
• dirty-rect marking
• grDrawBackground() upload

So this is not an OT-vs-RAM issue anymore.

Integrated main loop shape

fgPlayOceanRuntimeScene() currently does:

1. build static scene base
2. grSaveCleanBgTiles()
3. start foreground runtime
4. frame loop:
   • grBeginFrame()
   • grRestoreBgTiles()
   • grUpdateDisplay(NULL, NULL, NULL)
   • foregroundPilotRuntimeAdvance()

Inside grUpdateDisplay():

1. VSync(0)
2. if foregroundPilotRuntimeActive() -> foregroundPilotRuntimeCompose()
3. grDrawBackground()
4. eventsWaitTick(grUpdateDelay)

So integrated dynamic wave drawing must survive:

• grRestoreBgTiles()
• any draws inside foregroundPilotRuntimeCompose()
• grDrawBackground() upload

Foreground pack path uses direct compositing

Foreground pack frames go through:

• fgBlit16ToBackgroundRect()
• grCompositeDirect16ToBackground()

That path marks dirty rows directly and does not use sprite OT primitives.

Some direct helper paths clear currDirty*

In graphics_ps1.c, these functions explicitly zero currDirtyMinY/MaxY:

• grRestoreBackgroundRectForFrame()
• grRestoreAndCompositeDirect16BackgroundRectForFrame()

Those are dangerous in mixed-draw scenarios because they can wipe previously dirtied rows in the same frame.

The main integrated scene-pack path is currently using grCompositeDirect16ToBackground(), which does not clear currDirty*, but this area remains suspect and should be watched carefully.

What Has Been Tried And Failed

High-memory backdrop frame streams

Tried:

• BG1 16-bit backdrop frame packs
• dense backdrop frame playback
• catch-up logic on backdrop frame playback

Outcome:

• waves still did not visibly animate
• memory usage ballooned
• one prelude-baseline attempt blew FISHING1.BG1 up from about 6.6 MB to about 75 MB
• this path also increased crash / blank-screen risk

Conclusion:

• full-frame backdrop streams are the wrong memory model for PS1 here

Draw-pack replay variants

Tried:

• FOC/draw-pack backdrop replay
• host visible-draw replay
• BACKGRND.BMP draw-list replay
• sparse and dense timing variations

Outcome:

• user repeatedly observed absolutely no water motion

Conclusion:

• asset-side variations were not fixing the actual runtime integration bug

Native backdrop thread reuse

Tried:

• adsPilotComposeIslandBackdrop()
• adsPilotAdvanceIslandBackdrop()
• islandComposePilotWaves()
• related backdrop-thread timing/catch-up variants

Outcome:

• user still saw no water animation in fishing1

Wrong-path proof overlays

Several “proof” attempts were invalid or misleading:

1. Fresh per-runtime BACKGRND.BMP proof slot
   • bad because grLoadBmpRAM() can silently short-load or fail under memory pressure
   • also made the build extremely slow
2. Scene-state / tide / island-position guesses
   • user correctly pushed back on these as not explaining total absence of motion
3. Repainting waves over sprites with a new slot
   • also invalid under memory pressure if the slot never loaded

Most Important Validated Sandbox Mechanism

The black-screen sandbox that worked used a very simple loop:

1. fgInitVisiblePipeline()
2. fgInitBlackBackground()
3. preload BACKGRND.BMP once
4. each frame:
   • grBeginFrame()
   • grRestoreBgTiles()
   • grDrawSprite(grBackgroundSfc, &slot, x, y, spriteNo, 0) for 4 waves
   • grUpdateDisplay(NULL, NULL, NULL)

That worked.

So the exact delta between:

• that sandbox loop
• and integrated fgpilot fishing1

is where the bug lives.

Current Dirty Worktree State

At the time of writing, the worktree is dirty with ongoing wave-debugging changes, including:

• ads.c
• ads.h
• foreground_pilot.c
• island.c
• island.h
• config/ps1/cd_layout.xml
• scripts/export-fishing1-foreground-pilot.sh
• ttm.c
• generated files like generated/ps1/foreground/FISHING1.FOC

The latest attempted diagnostic change was:

• remove the fresh proof-slot allocation entirely
• reuse the already-loaded island background slot via:
  • adsPilotComposeWaveProofOverlay(uint32 vblankCount)
  • islandComposePilotProofWaves(struct TTtmThread*, uint32)
• draw those proof waves before grUpdateDisplay() in fgPlayOceanRuntimeScene()

User result on that family of proof builds:

• still no visible wave overlay
• speed badly degraded in some builds

So the integrated path is still not surfacing even deliberately wrong wave draws.

Best Current Hypothesis

There is a runtime integration bug in the visible frame pipeline, likely one of:

1. dynamic wave draws are being overwritten later in the same frame
2. dirty-row bookkeeping for integrated scene frames is wiping or skipping the wave rows
3. clean-base restore + foreground compose ordering is neutralizing the dynamic wave changes
4. integrated scene base construction leaves the wrong clean baseline, so live water changes never survive to upload

What is not currently a strong hypothesis:

• missing wave assets
• host export not containing wave data
• PS1 not being able to animate the wave sprites

Those have effectively been disproved.

Recommended Next Debugging Boundary

Stop trying new export formats until the integrated runtime path is pinned down.

The right next comparison is:

Sandbox working path

• black base
• draw waves
• upload

Integrated failing path

• restore clean scene base
• draw dynamic waves
• draw foreground pack
• upload

The next agent should prove exactly where the dynamic wave draw disappears:

1. Does the integrated loop actually call the wave draw every frame?
2. After the wave draw, are the expected dirty rows still marked?
3. After foreground pack compose, are those dirty rows still marked?
4. Does grDrawBackground() upload those rows?
5. Is the clean base itself already containing a static wave frame that visually masks the motion?

Practical Constraint

Keep the solution low-memory.

Do not go back to full decoded backdrop frame buffers as the primary solution.

The likely scalable solution is still:

• static scene base recipe
• tiny dynamic base-layer draw replay
• visible-pixels-only scene-relative foreground pack

But the integrated runtime bug must be fixed first.

Short Version

• Tree/Johnny foreground is in good shape.
• Water animation works in a black-screen sandbox.
• Water animation does not appear in integrated fishing1.
• This is now clearly an integrated runtime composition/upload bug, not an asset-generation bug.
• The next agent should debug the runtime draw/dirty/upload boundary, not invent more export variations.

• Goal
• Working mode
• Approach: Path A (bespoke, stay on ELSE branch)
• Step list
  • Step 1 — Boot-override tokens for islandState
  • Step 2 — Boot-override for islandState via BOOTMODE.TXT
  • Step 3 — High-tide baseline
  • Step 4 — Low-tide
  • Steps 5–9 — Raft stages
  • Steps 10–13 — Holidays
  • Step 14 — Night mode
  • Step 15 — Island position variations
  • Step 16 — Anything else you spot
  • Step 17 — Cleanup / handoff
• After this document is done

Goal

Get the fishing1 fgpilot scene visually identical to the original PC version of Johnny Castaway, covering every islandState-driven variation the scene supports (tide, raft stage, holiday, night, island position, etc.). This is Stage 1 of a larger effort to pixel-perfect every scene.

Working mode

One step at a time. For every step:

1. I build exactly one targeted change.
2. The build + DuckStation launch runs.
3. You look at the result and say whether it’s right, and if not, what’s off.
4. We iterate on that step, or move to the next one.

Verification is a visual check by eye, comparing against your memory of the PC version — no screenshot diffing, no automated perceptual compare, no reference image. If your eye says it’s right, it’s right.

Approach: Path A (bespoke, stay on ELSE branch)

We tried switching to the IF branch (full adsInitIsland) first — it produced multiple regressions (tree missing, Johnny pack mis-aligned, BACKGRND failing to re-load after ttmInitSlot zeroed our preload). Reverted.

Instead we stay on the current ELSE branch (known-good working state from commit 74bb0c24: waves animate, scene plays through, no ghosting) and add islandState-driven variations on top of it manually. We keep the memory layout we already tuned (preloaded BACKGRND in ttmBackgroundSlot, rect-based clean backup).

Important note: fgpilot mode does not run the original FISHING.ADS script or its TTMs. Johnny’s actions come from the pre-captured foreground pack (FISHING1.FG1) — pixel snapshots from the host build. Scene base drawing (island, trunk, raft, clouds, waves, holiday overlay) comes from island.c functions (islandInit, islandAnimate, islandInitHoliday). We call these directly with a controlled islandState in our ELSE-branch glue. Result is pixel- identical to calling adsInitIsland — same drawing code, just different glue.

Step list

Step 1 — Boot-override tokens for islandState

Without this we can’t reliably test each variation. The BOOTMODE.TXT parser already handles fgpilot <scene> — extend it to accept key=value tokens after the scene name:

fgpilot fishing1 day=N tide=low|high raft=N holiday=N night=0|1 \
                 islandx=N islandy=N

Most of these map to existing forced-variables (storyForcedCurrentDay, hostForcedLowTide, hostForcedRaftStage, hostForcedIslandX/Y). Some need new hooks (holiday, night). Parse in jc_reborn.c’s boot- override handling and apply to islandState at the top of fgPlayOceanRuntimeScene (after the current preload, before the ELSE branch draws).

You verify: setting fgpilot fishing1 tide=low visibly flips wave positions to the low-tide set; setting night=1 flips to NIGHT.SCR; etc. (If the ELSE branch doesn’t yet respond to a token, we just see no change — that’s fine, the step is “parser wired, overrides present, ready to drive subsequent steps”.)

Step 2 — Boot-override for islandState via BOOTMODE.TXT

Add parse tokens so we can pin variations for testing:

fgpilot fishing1 day=N tide=low|high raft=N holiday=N night=0|1 \
                 islandx=N islandy=N

Most of these already correspond to existing storyForced* / hostForced* variables — we just need the BOOTMODE parser to recognize the key=value tokens and feed them in. Without this we can’t reliably exercise variations one at a time.

You verify: each token actually changes the rendered scene as expected.

Step 3 — High-tide baseline

fgpilot fishing1 day=1 tide=high raft=1 holiday=0 night=0 islandx=0 islandy=0

You verify: looks like high-tide fishing1 on the PC.

Step 4 — Low-tide

fgpilot fishing1 day=1 tide=low raft=1 holiday=0 night=0 islandx=0 islandy=0

You verify.

Steps 5–9 — Raft stages

raft=1, raft=2, raft=3, raft=4, raft=5. One step per stage. You verify each.

Steps 10–13 — Holidays

• 10: holiday=1 — Halloween
• 11: holiday=2 — St. Patrick’s
• 12: holiday=3 — Christmas
• 13: holiday=4 — New Year

You verify each.

Step 14 — Night mode

fgpilot fishing1 day=1 tide=high raft=1 holiday=0 night=1 islandx=0 islandy=0

You verify.

Step 15 — Island position variations

A couple of sample (islandx, islandy) pairs from the VARPOS_OK ranges the original randomizer uses:

• islandx=-200 islandy=-20
• islandx=-60 islandy=-60
• islandx=-114 islandy=14

You verify each looks sane and matches how the PC places the island.

Step 16 — Anything else you spot

Whatever fishing1 variation or detail you notice is off that isn’t one of the above — coconuts state, seagulls, boat, banners, rain/weather, sparkles, special FX, etc. Handled one at a time.

Step 17 — Cleanup / handoff

Decide: keep the BOOTMODE override tokens as a permanent dev affordance (documented), or gate them behind a debug flag. Either way, commit a final “pixel-perfect fishing1” marker so we can return to it as the known-good baseline when we generalize to other scenes.

After this document is done

Stage 2 (future): apply the same process to fishing2 and onward; build the scene-specific dirty-rect table needed for the rect-based clean backup; generalize island-relative offset math so the rects move with islandState.xPos / LEFT_ISLAND.

Stage 3 (future): Johnny walk transitions between scenes, holiday toggles at the start-screen level, direct joystick control mode — per the larger master plan.

Safe baseline

• title -> fgpilot fishing1 is the current known-good path.
• fishing1 prerender playback is visually correct on the black base.
• Timing is close to PC after host-deadline replay and deadline catch-up work.
• The generic foreground runtime path has already been proven on fishing2.

Reference launch:

• ./scripts/rebuild-and-let-run.sh fgpilot fishing1

What just failed

These are explicitly not the next step:

• swapping ocean into the standalone prerender loop by changing only the base background load
• routing fgpilot fishing1 through full adsInitIsland() + adsPlay()

Observed failures:

• repeated Johnny overpaint / ghosting when ocean was forced under the standalone pack player
• partial scene startup and missing Johnny when full ADS scene routing was used

Conclusion:

• ocean cannot be restored safely by brute-forcing a different background into the current standalone playback loop
• full ADS scene routing changes too much behavior at once for this milestone

Goal

Restore the real ocean layer under prerender playback while keeping the foreground pack playback path stable and generic.

Execution rules

1. One change at a time.
2. Run after every step.
3. User validates every step before any commit.
4. No Fishing-1-only runtime hacks.
5. Do not reintroduce full ADS scene playback as an implicit side effect.

Step sequence

Step 1: Lock baseline again

Goal:

• keep title -> fgpilot fishing1 on the known-good black-base path

Exit criteria:

• visuals match the current baseline
• no ocean yet
• no Johnny ghosting

Step 2: Prove ocean-only initialization in isolation

Goal:

• initialize the ocean/island background machinery without starting scene ADS logic or foreground playback

Requirements:

• no walk thread
• no island animation thread unless explicitly needed for the ocean base to appear
• no foreground prerender overlay yet

Exit criteria:

• ocean appears correctly
• no corruption or title leftovers
• stable for a simple hold run

Step 3: Put the existing standalone foreground player on top of the proven

ocean-only base

Goal:

• reuse the exact current standalone fishing1 foreground playback loop
• change only the source of the clean background baseline

Exit criteria:

• ocean visible
• Johnny and props still render correctly
• no cumulative overpaint / ghosting

Step 4: If Step 3 fails, fix restore semantics before trying more init work

Primary suspects:

• grRestoreBackgroundRectForFrame()
• grRestoreAndCompositeDirect16BackgroundRectForFrame()
• prevDirty / currDirty advancement
• assumptions in the standalone loop that only happen to work on black

Rule:

• do not add more background setup complexity until restore correctness is proven against a non-black clean baseline

Step 5: Only after ocean is stable, restore island

Goal:

• static island first
• no random placement yet

Step 6: Only after static island is stable, restore random island placement

Goal:

• generic island positioning
• foreground playback still composes correctly

Immediate next move

Build an ocean-only proof path that initializes the real ocean background without entering full ADS scene playback, validate that by itself, then layer the current standalone fishing1 foreground playback over that same base.

⚠️ Historical snapshot — not current truth. Dated 2026-04-16. Preserved as a prerender-pilot-era status surface between the restore-pilot era and the fgpilot/full-SFX baseline. For current status see the scene-status shelf page and current-status shelf page.

Date: 2026-04-16

Validated now

• Title screen is restored.
• Default validation flow is title -> fgpilot fishing1.
• fishing1 full-scene foreground playback is visually correct on the black base.
• Timing is close to PC after host-deadline replay and deadline catch-up work.
• Generic foreground runtime support is proven on fishing2.

Current blocker

• restoring the real ocean layer under prerender playback without regressing the working foreground path

Failed recent experiments

• naive ocean background swaps inside the standalone prerender loop Result: repeated Johnny overpaint / ghosting.

• routing fgpilot fishing1 through full adsInitIsland() + adsPlay() Result: startup behavior changed too much, ocean half-loaded, Johnny never appeared.

Current conclusion

• the standalone prerender playback path is still the correct foreground pilot baseline
• ocean must be restored through a narrower background-only path, not by switching fgpilot to full ADS scene execution
• the next good milestone is: ocean-only base works then ocean + standalone foreground pack works

Working reference command

• ./scripts/rebuild-and-let-run.sh fgpilot fishing1

Guardrails

1. One change at a time.
2. Run after every step.
3. Human validation before commit.
4. Keep fixes generic.

• Purpose
• Current Proven Pilot
• Status Legend
• Scene Status
  • ACTIVITY.ADS
  • BUILDING.ADS
  • FISHING.ADS
  • JOHNNY.ADS
  • MARY.ADS
  • MISCGAG.ADS
  • STAND.ADS
  • SUZY.ADS
  • VISITOR.ADS
  • WALKSTUF.ADS
• References

Purpose

Track prerendered foreground-only pilot status separately from the normal PS1 scene verification program.

This log does not mean a scene is fully PS1-verified. A scene should only move into the normal verified bucket after full-scene behavior, timing, and visual parity are signed off.

Current Proven Pilot

• FISHING 1 / FISHING.ADS tag 1 / scene 17
  • status: top-layer verified
  • proof: boots through fgpilot fishing1 on PS1 ISO in DuckStation and shows the prerendered Johnny/pole/starfish foreground path correctly
  • current asset: full-frame foreground pack (frame_step = 1, 156 source frames, 156 packed frames)
  • current limitation: playback is visually correct but runs at about half speed; background/ocean layer is not yet restored underneath

Status Legend

• top-layer verified — prerendered foreground path is visibly working on PS1
• export-ready untested — canonical scene exists, but no PS1 foreground pilot validation has been recorded yet

Scene Status

ACTIVITY.ADS

• ACTIVITY 1 / tag 1 / scene 0 — export-ready untested
• ACTIVITY 4 / tag 4 / scene 4 — export-ready untested
• ACTIVITY 5 / tag 5 / scene 5 — export-ready untested
• ACTIVITY 6 / tag 6 / scene 6 — export-ready untested
• ACTIVITY 7 / tag 7 / scene 7 — export-ready untested
• ACTIVITY 8 / tag 8 / scene 8 — export-ready untested
• ACTIVITY 9 / tag 9 / scene 9 — export-ready untested
• ACTIVITY 10 / tag 10 / scene 3 — export-ready untested
• ACTIVITY 11 / tag 11 / scene 2 — export-ready untested
• ACTIVITY 12 / tag 12 / scene 1 — export-ready untested

BUILDING.ADS

• BUILDING 1 / tag 1 / scene 10 — export-ready untested
• BUILDING 2 / tag 2 / scene 13 — export-ready untested
• BUILDING 3 / tag 3 / scene 12 — export-ready untested
• BUILDING 4 / tag 4 / scene 11 — export-ready untested
• BUILDING 5 / tag 5 / scene 14 — export-ready untested
• BUILDING 6 / tag 6 / scene 16 — export-ready untested
• BUILDING 7 / tag 7 / scene 15 — export-ready untested

FISHING.ADS

• FISHING 1 / tag 1 / scene 17 — top-layer verified
• FISHING 2 / tag 2 / scene 18 — export-ready untested
• FISHING 3 / tag 3 / scene 19 — export-ready untested
• FISHING 4 / tag 4 / scene 20 — export-ready untested
• FISHING 5 / tag 5 / scene 21 — export-ready untested
• FISHING 6 / tag 6 / scene 22 — export-ready untested
• FISHING 7 / tag 7 / scene 23 — export-ready untested
• FISHING 8 / tag 8 / scene 24 — export-ready untested

JOHNNY.ADS

• JOHNNY 1 / tag 1 / scene 25 — export-ready untested
• JOHNNY 2 / tag 2 / scene 26 — export-ready untested
• JOHNNY 3 / tag 3 / scene 27 — export-ready untested
• JOHNNY 4 / tag 4 / scene 28 — export-ready untested
• JOHNNY 5 / tag 5 / scene 29 — export-ready untested
• JOHNNY 6 / tag 6 / scene 30 — export-ready untested

MARY.ADS

• MARY 1 / tag 1 / scene 31 — export-ready untested
• MARY 2 / tag 2 / scene 33 — export-ready untested
• MARY 3 / tag 3 / scene 32 — export-ready untested
• MARY 4 / tag 4 / scene 34 — export-ready untested
• MARY 5 / tag 5 / scene 35 — export-ready untested

MISCGAG.ADS

• MISCGAG 1 / tag 1 / scene 36 — export-ready untested
• MISCGAG 2 / tag 2 / scene 37 — export-ready untested

STAND.ADS

• STAND 1 / tag 1 / scene 38 — export-ready untested
• STAND 2 / tag 2 / scene 39 — export-ready untested
• STAND 3 / tag 3 / scene 40 — export-ready untested
• STAND 4 / tag 4 / scene 41 — export-ready untested
• STAND 5 / tag 5 / scene 42 — export-ready untested
• STAND 6 / tag 6 / scene 43 — export-ready untested
• STAND 7 / tag 7 / scene 44 — export-ready untested
• STAND 8 / tag 8 / scene 45 — export-ready untested
• STAND 9 / tag 9 / scene 46 — export-ready untested
• STAND 10 / tag 10 / scene 47 — export-ready untested
• STAND 11 / tag 11 / scene 48 — export-ready untested
• STAND 12 / tag 12 / scene 49 — export-ready untested
• STAND 15 / tag 15 / scene 50 — export-ready untested
• STAND 16 / tag 16 / scene 51 — export-ready untested

SUZY.ADS

• SUZY 1 / tag 1 / scene 52 — export-ready untested
• SUZY 2 / tag 2 / scene 53 — export-ready untested

VISITOR.ADS

• VISITOR 1 / tag 1 / scene 54 — export-ready untested
• VISITOR 3 / tag 3 / scene 55 — export-ready untested
• VISITOR 4 / tag 4 / scene 56 — export-ready untested
• VISITOR 5 / tag 5 / scene 59 — export-ready untested
• VISITOR 6 / tag 6 / scene 57 — export-ready untested
• VISITOR 7 / tag 7 / scene 58 — export-ready untested

WALKSTUF.ADS

• WALKSTUF 1 / tag 1 / scene 60 — export-ready untested
• WALKSTUF 2 / tag 2 / scene 61 — export-ready untested
• WALKSTUF 3 / tag 3 / scene 62 — export-ready untested

References

• scene catalog: repo:/regtest-references/manifest.csv
• pilot rationale: repo:/docs/ps1/research/OFFLINE_SCENE_PLAYBACK_PIVOT_2026-04-12.md

• What Worked
• What Failed
• Prioritized Speed Backlog
• Next Target
• Repeat Prompt

Current validated baseline:

• fgpilot fishing1 is visually correct.
• Full-scene export is correct.
• Host timing preservation is corrected enough that playback is back near the earlier fast baseline instead of the over-slow scheduler-sum path.
• Launch path: ./scripts/rebuild-and-let-run.sh fgpilot fishing1

Validation rule:

1. One change at a time.
2. Clean rebuild and launch with the repo script.
3. Human checks visuals and speed.
4. If visuals are good and speed is same or better, commit and push.

What Worked

• Entry-table preload.
• Bulk-copy compositor fast path.
• Narrow background restore.
• Full-scene story-single --until-exit export.
• Corrected host-timing preservation in the export pipeline.
• Single-tile upload-path tightening.
• Dedicated one-tile upload branch in grDrawBackground().
• Same-bounds fused restore+composite path.

What Failed

• Direct framebuffer path.
• Diff/direct-delta runtime path.
• Progressive test path.
• Overlap-skip restore as implemented.
• Naive scheduler-delay summing.
• Naive read-ahead / double-buffering.
• Pilot-only black-clear restore replacement.

Prioritized Speed Backlog

1. grDrawBackground() / upload cost. Best remaining likely win on the stable path.

2. Safer background restore reduction. Retry only with stricter invariants than the broken overlap-skip version.

3. Pack-time precompute for runtime blits/restores. Tile coverage, row offsets, clipped spans.

4. Same-rect / same-shape cached setup. Reuse setup when consecutive frames share bounds.

5. Held-frame no-work path. If the frame is held, do the minimum possible.

6. More specialized memcpy-based foreground blit paths. Keep squeezing the stable compositor path.

7. Better CD read path, but not naive read-ahead. Any future buffering must preserve exact ownership and frame identity.

8. Pack layout improvements. Runtime-friendly ordering and alignment.

9. More timing work only after more render throughput wins. The biggest timing mistake is fixed for now.

10. Display mode experiments last. Do not revisit direct/progressive until the stable path is exhausted.

Next Target

Stay on the stable compositor path and keep attacking the heavy early-motion section of the scene, where the tall tree-walk rect still feels slower than the later action. Favor changes that reduce restore/upload work for larger active areas before returning to CD buffering experiments.

Repeat Prompt

Continue PS1 Fishing 1 foreground speed improvements from the current repo state. Stay on the stable fgpilot fishing1 path only. Make one high-impact safe improvement from docs/ps1/research/FOREGROUND_TIMING_PLAN_2026-04-13.md, launch it with ./scripts/rebuild-and-let-run.sh fgpilot fishing1, and stop for my validation. Do not use experimental direct framebuffer, diff, or progressive paths unless explicitly asked.

Why This Exists

The current PS1 rendering effort has spent too much time on runtime composition correctness:

• sprite lifetime
• replay continuity
• restore/upload correctness
• scene handoff state carry
• route-specific startup behavior

That work has produced useful tooling and narrowed several boundaries, but it has not produced proportional product progress. The project goal is not “prove that a dynamic PS1 compositor can exactly reproduce the PC scene graph at runtime.” The real goal is to ship a stable PS1 version that:

• displays story scenes correctly
• keeps Johnny pixel-perfect
• supports sound, pause, controller skip, and later gameplay work

This document evaluates a strategic pivot:

• stop treating story scenes as fully dynamic runtime composition problems
• move them to offline-authored playback content
• keep the PS1 runtime focused on simple display/compositing responsibilities

Executive Summary

The naive version of the idea is not viable:

• full-frame 640x480 prerendered playback for all 63 scenes does not fit in the available CD budget

But the underlying direction is viable if narrowed:

• use offline-authored scene playback for story scenes
• do not store full-screen raw frames
• store only the animated foreground/actor plates and keep background/ocean as runtime layers or low-cardinality state sets
• use indexed palettes, rectangle crops, frame deltas, and scene-local packet streams

Recommended pivot:

1. Keep island/gameplay/menu/controller as live runtime systems.
2. Convert story scenes to offline playback contracts.
3. Start with a hybrid format:
   • static background base
   • optional ocean/island runtime layer
   • prerendered actor/foreground plates per frame
   • per-frame metadata for input windows, pause, skip, and audio sync
4. Pilot the system on:
   • FISHING 1
   • one BUILDING scene
   • one simpler validated scene

This is the most credible path to pixel-perfect Johnny without continuing the current runtime bug treadmill.

Hard Storage Reality

Full-screen raw storage does not fit

At 640x480:

• 16-bit frame: about 614,400 bytes (600 KB)
• 8-bit indexed frame: about 307,200 bytes (300 KB)

For 63 scenes:

• 5 fps for 30 sec each:
  • 9,450 frames
  • about 5.5 GB at 16-bit
  • about 2.8 GB at 8-bit
• 10 fps for 30 sec each:
  • about 11.1 GB at 16-bit
  • about 5.5 GB at 8-bit

That is before:

• holiday variants
• raft/no-raft variants
• alternate island placement/state variants
• duplicate prerender storage for boot/title lead-ins or timing slack

Conclusion:

• full-screen prerendered 640x480 story playback is not CD-feasible

Current disc usage suggests room for a smarter offline format

Current checked-in disc image:

• repo:/jcreborn.bin is about 38 MB
• repo:/jc_resources/extracted is about 5.5 MB

So there is substantial unused disc budget relative to the current project state. The pivot is only viable if that budget is spent on compressed, structured playback data, not naive full-screen frames.

Recommended Architecture

Core Decision

Story scenes become offline-authored playback units.

The PS1 runtime no longer tries to reconstruct those scenes from:

• live TTM script execution
• live sprite ordering
• replay/recovery continuity
• dynamic restore heuristics

Instead, a story scene becomes:

• a deterministic playback stream
• with explicit frame timing
• explicit plate placement
• explicit audio sync
• explicit pause/skip/transition metadata

Display Model

Use a hybrid compositor:

1. Background layer
   • static or low-cardinality background state
   • ocean/island can remain runtime if that is cheaper than storing it
2. Foreground playback layer
   • prerendered actor/foreground plate frames
   • cropped to the smallest stable region that contains Johnny and other transient scene elements
3. UI/pause overlay layer
   • live runtime, unaffected by cutscene rendering internals

This is the key trade:

• spend offline preprocessing effort
• to eliminate runtime correctness ambiguity

Pixel-Perfect Johnny Requirement

This pivot only makes sense if Johnny remains exact.

That requires:

• PC-side prerender generation from the real host renderer
• no hand-rebuilt sprite composition on PS1
• no runtime re-simulation of sprite layering
• scene-local palette/plate generation that preserves the exact Johnny pixels from the PC source frames

Johnny is then “pixel-perfect by construction” because PS1 shows the exact offline-authored plate, not a reconstructed approximation.

Proposed Playback Asset Format

Use a new scene playback family, conceptually separate from the current pack system.

Suggested on-disc structure:

• SCN/<scene_id>.SPK scene playback pack
• SCN/<scene_id>.IDX frame index / timing / metadata

Per scene payload:

• one background descriptor
  • static base image or background-state table
• one optional ocean/island descriptor
  • if runtime-generated, store only parameters
  • if prerendered, store small state atlas, not every full frame
• one foreground plate stream
  • rectangle bounds per frame
  • indexed pixel payload
  • optional delta-from-previous payload
• one timing table
  • display duration
  • frame-to-audio timing
  • skip allowed / pause allowed markers
• one interaction metadata table
  • future controller skip windows
  • subtitle/caption sync hooks

Plate encoding

Per frame:

• x, y, width, height
• palette id
• payload mode
  • full indexed blit
  • XOR/delta patch
  • RLE patch
  • repeat previous

Strong default:

• 8-bit indexed plates
• scene-local palette
• row-oriented RLE or LZ-style compression
• delta patching only if it materially wins in the pilot

Do not start with a fancy codec. Start with the simplest format that yields a real disc win.

Why Hybrid Plates Are Better Than Full-FMV

A full video path would also solve correctness, but it has worse tradeoffs:

• more aggressive downscale/compression pressure
• less reuse of existing background behavior
• less flexibility for mixed runtime/interactive content
• more likely to look soft or artifacted

Hybrid plates keep the expensive visual correctness where it matters:

• Johnny
• foreground actors
• transient props

while leaving the broad background/ocean space cheap.

Runtime Responsibilities

The PS1 scene playback runtime should only do:

1. Load scene playback metadata
2. Prepare background/ocean layer
3. For each playback tick:
   • decode plate payload
   • blit plate into framebuffer/working surface
   • present
4. Obey pause / skip / exit / controller actions
5. Keep audio in sync

It should not:

• discover scene resources dynamically
• run TTM/ADS logic for visual correctness
• depend on replay continuity
• depend on restore-pilot heuristics

Variant Handling

The user concern is valid:

• holidays
• raft/no-raft
• island state changes

These should not explode storage if handled correctly.

Recommended rule:

• only offline-author the variants that actually produce different visual outputs in story playback

Most scenes should not multiply across every theoretical world state. Instead:

• scene compiler determines which background plate family is actually used for that route
• per-scene manifest records the exact chosen variant

Likely storage structure:

• common foreground stream reused across variants when possible
• different background descriptors only when truly needed

Feasibility Gate

This pivot should be accepted only if the pilot demonstrates all three:

1. Johnny is exact
2. runtime implementation is much simpler than the current compositor path
3. disc usage scales acceptably

Pilot Plan

Pilot scenes:

1. FISHING 1
2. one BUILDING scene
3. one already-healthy scene for baseline comparison

Pilot deliverables

Stage 1: Offline analysis

For each pilot scene, export from host:

• full frame sequence
• per-frame difference against previous frame
• minimal bounding rectangle of changed actor/foreground region
• palette statistics
• background stability regions

Questions to answer:

• how large is the useful foreground plate rectangle really
• how often can frames be represented as deltas
• how many distinct palettes are needed
• whether ocean/island should remain runtime or be part of the plate stream

Stage 2: Storage simulation

For each pilot, estimate disc size under:

1. full-screen 8-bit
2. cropped 8-bit full-frame plates
3. cropped 8-bit delta plates
4. cropped 4-bit where acceptable

Acceptance target:

• hybrid cropped format must be dramatically smaller than full-screen storage
• projected full 63 scene rollout must fit well under the practical disc budget with headroom for sound and future assets

Stage 3: PS1 playback prototype

Implement a small runtime path that:

• loads one pilot .SPK
• shows background
• plays foreground plates
• supports pause and scene skip

No attempt at full generic cutscene engine yet.

Stage 4: Visual validation

Compare PS1 playback against host source frames for the pilot:

• Johnny exactness
• timing drift
• visible compression artifacts
• frame-edge artifacts around the plate region

Cost/Benefit Compared To Current Path

Benefits

• eliminates large classes of sprite correctness bugs
• moves complexity to PC preprocessing, where iteration is cheaper
• makes story playback deterministic
• gives a stable base for:
  • sound
  • pause
  • skip
  • controller input
  • later gameplay work

Most importantly:

• it changes the problem from “simulate PC layering on PS1” to “display the already-correct scene on PS1”

Costs

• requires a new content build pipeline
• requires scene capture/export tooling on PC
• requires a new playback asset format
• may require per-scene authoring exceptions in early rollout
• does not automatically solve interactive island/gameplay rendering

Risks

Risk 1: Plate regions are still too big

Mitigation:

• prove size on the pilot before broad rollout

Risk 2: Compression artifacts break “pixel-perfect Johnny”

Mitigation:

• use lossless indexed storage for Johnny-containing regions
• compress transport, not image quality

Risk 3: Ocean/background interaction is more scene-dependent than expected

Mitigation:

• allow per-scene choice:
  • runtime background
  • prerendered background-state set
  • full-frame fallback for outliers

Risk 4: Pipeline takes too long to build

Mitigation:

• do not build the full general system first
• build the single-scene pilot first

Recommended Product Split

If this pivot is adopted, split the game into two rendering classes:

Class A: Offline playback scenes

• story scenes
• cutscenes
• anything whose correctness is dominated by actor composition

Class B: Live runtime scenes

• island free movement
• menus
• pause overlay
• controller navigation
• gameplay interactions

This split is strategically healthier than insisting one renderer solve both.

Recommendation

Adopt the pivot, but in the hybrid form only.

Do not pursue:

• naive full-screen 640x480 prerender storage

Do pursue:

• offline-authored story scene playback
• hybrid background + cropped foreground plate format
• pilot-first validation on FISHING 1

Immediate Next Steps

1. Build a PC export tool for one scene:
   • host frames
   • crop rectangles
   • delta candidates
   • size report
2. Produce a real storage estimate for FISHING 1
3. Decide whether ocean/island remains runtime or becomes part of the playback asset for that scene
4. Implement a minimal PS1 playback prototype for one pilot scene
5. Compare it visually against host and current PS1
6. Only then decide whether to scale to the full 63

Decision Gate

Approve the pivot only if the pilot proves:

• Johnny is exact
• runtime is much simpler
• projected full-scene storage is acceptable
• pause/skip/audio integration becomes easier, not harder

If those are true, this is a more viable path than continuing the current runtime-composition effort indefinitely.

• Goal
• Current Read
• Chosen Runtime Direction
• Architecture
  • 1. Keep the reference bank
  • 2. New VLM analyzer
  • 3. Output schema
• Immediate Next Steps
• Success Criteria

Goal

Replace the current heuristic caption layer with a real multimodal model that can answer questions like:

• Johnny is fishing off the right side of the dock.
• Mary is visible center-left on the beach.
• The frame is still title/ocean only; no character is visible.

The output should be structured JSON, not free-form prose.

Current Read

The existing scripts/vision_classifier.py pipeline is still useful for:

• nearest-reference retrieval
• family/scene confusion reporting
• coarse failure mode detection

But it is not a true semantic model. Its summaries are derived from foreground heuristics and reference templates, so it cannot reliably identify actors or actions.

Chosen Runtime Direction

Primary target:

• OpenVINO GenAI
• llmware/Qwen2.5-VL-3B-Instruct-ov-int4

Why:

• CPU-only path
• packaged wheel exists for Python 3.12 on this machine
• OpenVINO exposes a direct VLM pipeline API
• the model is already converted to OpenVINO and quantized for low-resource inference

Fallbacks if memory/runtime is still too heavy:

• a smaller OpenVINO-converted VLM, if available
• llama.cpp GGUF path with a smaller multimodal model

Architecture

1. Keep the reference bank

The existing reference bank is still valuable as retrieval context.

For a query frame:

1. compute nearest reference matches with the bank
2. pass those matches into the VLM prompt
3. ask the VLM for strict JSON

This constrains the model without forcing it to invent semantics from scratch.

2. New VLM analyzer

Implemented in:

• scripts/vision_vlm.py

Responsibilities:

• load a real VLM
• load an image
• optionally load nearest reference hints from the bank
• prompt for structured semantics
• write machine-readable JSON
• render a review HTML page for sampled frames

3. Output schema

Target JSON keys:

• screen_type
• summary
• characters
• objects
• actions
• confidence
• notes

Each character should include:

• name
• confidence
• position
• action

Immediate Next Steps

1. Install runtime:
   • scripts/setup-vision-vlm-openvino.sh
2. Download model:
   • llmware/Qwen2.5-VL-3B-Instruct-ov-int4
3. Run image smoke tests on hand-picked reference frames.
4. Compare captions across strongly distinct scenes:
   • FISHING-1
   • BUILDING-2
   • ACTIVITY-4
   • MARY-1
5. If quality is acceptable, add sampled-frame VLM analysis for full reference scenes.

Success Criteria

The VLM path is only acceptable if it can reliably separate at least:

• title vs ocean vs live scene
• Johnny vs Mary vs no clear character
• fishing vs bathing vs standing vs walking when the frame is visually clear
• wrong-family failures in PS1 runs

If it cannot do that, the runtime/model pair should be replaced rather than tuned around.

• 2026-03-29

Worktree:

• /tmp/jc_reborn_ps1_debug

Branch:

• worktree-ps1-debug-20260329

Goal

Build a local CPU-only visual classifier pipeline that:

• uses the canonical reference scenes as source of truth
• runs under low-memory constraints
• produces structured semantic artifacts
• generates human-reviewable HTML pages
• scales across all 63 reference scenes

Constraints

• effectively no usable GPU
• about 8 GB RAM
• avoid heavyweight runtime dependencies
• acceptable to trade speed for robustness

Decisions

The pipeline is reference-first, not training-first.

It uses:

• deterministic visual features
• lightweight per-frame feature vectors
• nearest-reference retrieval against the canonical bank
• semantic summaries derived from reference-bank matches

It deliberately does not depend on:

• torch
• transformers
• sklearn

Current runtime dependencies are:

• Pillow
• NumPy

Implemented

Primary code:

• /tmp/jc_reborn_ps1_debug/scripts/vision_classifier.py
• /tmp/jc_reborn_ps1_debug/scripts/run-vision-reference-pipeline.sh
• /tmp/jc_reborn_ps1_debug/scripts/publish-vision-pipeline.py

Design doc:

• /tmp/jc_reborn_ps1_debug/docs/ps1/research/LOCAL_VISION_CLASSIFIER_PLAN_2026-03-29.md

Completed Outputs

Reference bank:

• /tmp/jc_reborn_ps1_debug/artifacts/vision-reference-bank-20260329/

Reference self-check, latest:

• repo:/vision-artifacts/vision-reference-selfcheck-20260329-v4/

Published top-level entry:

• repo:/vision-artifacts/vision-reference-pipeline-current/index.html

Artifact Types Now Available

For all 63 reference scenes:

• per-scene review.html
• per-scene vision-analysis.json
• bank-level index.html
• self-check index.html
• quality report
• confusion report
• family report
• inventory JSON
• inventory HTML
• inventory CSV
• strongest-scenes JSON
• weakest-scenes JSON
• top-level manifest JSON

Scale Reached

Reference scenes processed:

• 63

Reference frames indexed:

• 13,128

Key Improvements Made

1. Built a full bank over all reference frames.
2. Added per-run analysis against that bank.
3. Added per-scene HTML review outputs.
4. Added full self-check over all 63 references.
5. Tightened label rules to reduce excessive ocean classification.
6. Added quality, confusion, and family-level reports.
7. Added export-friendly inventory artifacts and top-level publishing.

Current Limits

The pipeline is operational, but semantic quality is still v1.

Known weak areas:

• similar FISHING scenes cross-match each other
• several STAND scenes remain hard to separate
• some scene families still need stronger actor/sprite semantics

So:

• pipeline completeness: good
• artifact completeness: good
• semantic precision: improving, not final

Next Practical Step

Run this exact pipeline against PS1 result directories and produce:

• PS1 review.html
• PS1 vision-analysis.json
• PS1 quality summary against the reference bank
• scene ranking by semantic mismatch mode

That is the next step that will directly help fix PS1 scene bugs.

• One-Command Reference Pipeline
• Primary Outputs
• Useful Reports
• Core CLI
• Important Note

Worktree:

• /tmp/jc_reborn_ps1_debug

One-Command Reference Pipeline

Run:

/tmp/jc_reborn_ps1_debug/scripts/run-vision-reference-pipeline.sh

Optional custom output root:

/tmp/jc_reborn_ps1_debug/scripts/run-vision-reference-pipeline.sh \
  repo:/vision-artifacts/custom-reference-pipeline

Primary Outputs

Top-level published entry:

• repo:/vision-artifacts/vision-reference-pipeline-current/index.html

Reference bank:

• /tmp/jc_reborn_ps1_debug/artifacts/vision-reference-bank-20260329/index.html

Latest self-check:

• repo:/vision-artifacts/vision-reference-selfcheck-20260329-v4/index.html

Useful Reports

• quality: repo:/vision-artifacts/vision-reference-selfcheck-20260329-v4/quality-report.html
• confusion: repo:/vision-artifacts/vision-reference-selfcheck-20260329-v4/confusion-report.html
• family: repo:/vision-artifacts/vision-reference-selfcheck-20260329-v4/family-report.html
• inventory: repo:/vision-artifacts/vision-reference-pipeline-current/scene-inventory.html

Core CLI

Build bank:

python3 /tmp/jc_reborn_ps1_debug/scripts/vision_classifier.py \
  build-reference-bank \
  --refdir repo:/regtest-references \
  --outdir /tmp/jc_reborn_ps1_debug/artifacts/vision-reference-bank-20260329

Analyze one run:

python3 /tmp/jc_reborn_ps1_debug/scripts/vision_classifier.py \
  analyze-run \
  --scene-dir repo:/regtest-references/ACTIVITY-1 \
  --bank-dir /tmp/jc_reborn_ps1_debug/artifacts/vision-reference-bank-20260329 \
  --outdir repo:/vision-artifacts/example-run \
  --expected-scene ACTIVITY-1

Analyze all reference scenes against the bank:

python3 /tmp/jc_reborn_ps1_debug/scripts/vision_classifier.py \
  analyze-reference-set \
  --refdir repo:/regtest-references \
  --bank-dir /tmp/jc_reborn_ps1_debug/artifacts/vision-reference-bank-20260329 \
  --outdir repo:/vision-artifacts/vision-reference-selfcheck-20260329-v4

Publish top-level entry pages:

python3 /tmp/jc_reborn_ps1_debug/scripts/publish-vision-pipeline.py

Important Note

This pipeline is complete on the reference side. The next meaningful use is PS1 analysis against the built reference bank.

• Mission
• Key Findings
  • Build State
  • Timing
  • Sweep 1: All 63 scenes without seed (story single via storyPlay)
  • Sweep 2: Structural comparison against Linux reference
  • Sweep 3: Seeded deterministic run (in progress)
• Artifacts
• Commits This Session
• Next Steps

Mission

Validate all 63 PS1 scenes against the canonical Linux reference set.

Key Findings

Build State

• HEAD (7a3d4b49) had uncommitted cross-file dependencies → broken build
• Rolled back to f2c33ca3 (clean micro-optimizations state)
• Added story single boot mode + seed support + storyPlayBootSceneDirect()
• Current working commits: 5b776e5a → 69432ead → d3b36ccc → 8544b664 → 4054755a

Timing

| Phase | Frame | Wall time | |——-|——-|———–| | BIOS animation | 300-600 | 5-10 sec | | Title screen | 1200-2400 | 20-40 sec | | Ocean/walk | 2400-3000 | 40-50 sec | | Scene content | 3000+ | 50+ sec |

REGTEST_FRAMES increased from 1800 to 9000 (150 sec emulated).

Sweep 1: All 63 scenes without seed (story single via storyPlay)

• Result: 63 PASS, 0 FAIL
• Method: island content detection (yellow > 1% in any frame)
• All ADS families produce visible island content

Sweep 2: Structural comparison against Linux reference

• Result: 63/63 MATCH
• Both PS1 and reference have island + palm tree in every scene
• compare.html generated with side-by-side thumbnails

Sweep 3: Seeded deterministic run (in progress)

• Using story single <idx> seed 1 matching reference metadata
• Direct scene path via storyPlayBootSceneDirect() for proper island setup
• 27/63 completed, all PASS so far
• JOHNNY scenes run slowly (~15-25 min per scene due to complex ADS)

Artifacts

• regtest-results/sweep-63/ — unseeded 63-scene captures
• regtest-results/seeded-63/ — seed-1 deterministic captures (in progress)
• regtest-results/comparison-63/compare.html — visual comparison report
• regtest-results/comparison-63/compare.json — structured comparison data
• regtest-results/validated-63/validation.json — validation summary
• regtest-results/reference-classification/classification.json — reference analysis

Commits This Session

| Hash | Description | |——|————-| | 5b776e5a | Restore clean buildable state from f2c33ca3 | | 69432ead | Add story single boot mode | | d3b36ccc | Update timing to 9000 frames | | 8544b664 | 63/63 scenes render with island content | | 3be7e960 | 63/63 match reference (JSON artifacts) | | ff8f0fd1 | Full validation pipeline artifacts | | 08a878da | Reference classification (63/63 island+Johnny) | | 4054755a | Add seed support + direct scene path |

Next Steps

1. Wait for seeded sweep to complete
2. Generate pixel-level comparison between seeded PS1 and reference frames
3. Identify any per-scene rendering differences
4. Fix rendering bugs if found
5. Commit final validation artifacts

Worktree:

• /tmp/jc_reborn_ps1_debug

Branch:

• worktree-ps1-debug-20260329

Goal:

• build a local visual analysis pipeline for PS1 scene validation and debugging
• run under severe local constraints:
  • about 8 GB system RAM
  • effectively no useful GPU
  • CPU-only inference is acceptable
  • slow inference is acceptable
• use the canonical Linux/reference scene captures as the semantic source of truth
• pre-run the classifier on those references so PS1 evaluation is reference-driven instead of free-form

This is not primarily a training problem yet. The first target is a practical semantic harness that converts frames into structured, comparable scene descriptions.

Executive Recommendation

Do this as a reference-first system, not a generic captioning toy.

The classifier should not try to infer the world from scratch for every PS1 frame. Instead, it should:

1. extract cheap visual signatures from every canonical reference frame
2. precompute lightweight learned embeddings for those reference frames
3. assign semantic labels to reference frames once
4. evaluate PS1 frames by comparing them against that prepared reference bank
5. only use a small VLM on a sampled subset of frames where we need explanations

That gives us three layers:

1. deterministic triage
2. reference-bank retrieval and semantic matching
3. sampled-frame textual explanation

Why This Is The Right Shape

We already know a lot:

• the canonical scene list
• the canonical reference images
• which frame ranges matter
• the common PS1 failure modes:
  • black screen
  • title persistence
  • ocean-only background
  • wrong family
  • sprites missing
  • sprites present but wrong timing/content

That means the cheapest useful classifier is not “train a world model.” It is:

• nearest-neighbor against the known good image bank
• plus a small amount of semantic labeling

This also fits the machine constraints much better than training or running a large VLM over every frame.

Source Of Truth

Canonical reference runs:

• repo:/regtest-references

Scene list:

• repo:/config/ps1/regtest-scenes.txt

Related existing scripts:

• repo:/scripts/build-reference-index.py
• repo:/scripts/calibrate-visual-detect.py
• repo:/scripts/compare-reference-batch.sh
• repo:/scripts/render-compare-timeline.py

Validation target:

• 63 scenes

The classifier is not the source of truth. The reference captures are. The classifier is a semantic layer that makes the truth usable for automated triage and debugging.

What The Harness Must Answer

Per frame, we need a compact schema like:

{
  "screen_type": "title|black|ocean|island|scene|transition|unknown",
  "scene_family_guess": "ACTIVITY|BUILDING|WALKSTUF|FISHING|TITLE|unknown",
  "sprites_visible": true,
  "sprite_density": "none|low|medium|high",
  "actors": [
    {
      "name": "johnny",
      "present": true,
      "position": "left|center|right|upper-left|upper-right|lower-left|lower-right",
      "confidence": 0.83
    }
  ],
  "objects": [
    {
      "name": "raft",
      "present": false,
      "position": null,
      "confidence": 0.21
    }
  ],
  "action_summary": "Johnny is standing near the shoreline.",
  "reference_match": {
    "scene": "ACTIVITY-1",
    "frame": "frame_06000.png",
    "distance": 0.12,
    "confidence": 0.78
  },
  "notes": [
    "background only",
    "no active sprite composition visible"
  ]
}

Important:

• position buckets are enough initially
• we do not need perfect bounding boxes
• we do not need perfect actor names in phase one
• we do need stable “ocean-only vs actual scene” answers

Core Design: Reference-First Semantic Retrieval

The canonical references should be processed offline into a reusable semantic bank.

Reference Bank Contents

For each canonical frame:

• file path
• scene id
• frame number
• cheap deterministic metrics
• embedding vector
• optional text summary
• optional semantic labels

Example:

{
  "scene_id": "ACTIVITY-1",
  "frame": "frame_06000.png",
  "embedding_model": "clip-vit-base-patch32",
  "embedding": "...",
  "metrics": {
    "mean_rgb": [34, 88, 120],
    "water_ratio": 0.41,
    "dark_ratio": 0.03,
    "edge_density": 0.19,
    "telemetry_present": true
  },
  "labels": {
    "screen_type": "scene",
    "scene_family_guess": "ACTIVITY",
    "sprites_visible": true,
    "johnny_present": true,
    "mary_present": false,
    "raft_present": false
  },
  "caption": "Johnny stands on the beach near the center of the frame."
}

Runtime PS1 Evaluation

For each PS1 frame:

1. compute deterministic metrics
2. compute embedding
3. find nearest reference frames globally and within target scene
4. compare semantic labels against nearest reference cluster
5. emit:
   • best reference match
   • semantic mismatch reasons
   • confidence

This gives us answers like:

• “PS1 frame most closely matches ACTIVITY-1 frame_06000 background, but sprites are missing”
• “PS1 frame is closer to FISHING than ACTIVITY”
• “PS1 frame is title-like even though story scene should have launched”

Architecture

Stage 0: Build The Reference Index

Create a new offline indexer:

• input:
  • regtest-references/
• output:
  • regtest-references/index.json
  • regtest-references/embeddings/*.npy or a compact shard format
  • optional sampled captions

This stage should:

• enumerate all reference frames
• attach scene/frame metadata
• compute cheap deterministic signatures
• compute embeddings once
• optionally generate labels for a sampled subset

Stage 1: Cheap Deterministic Triage

Use classical CV and fixed heuristics first for:

• black
• title
• ocean-only
• mostly-water
• telemetry presence
• sprite-like foreground density
• transition frames

We already have the beginning of this approach in:

• repo:/scripts/calibrate-visual-detect.py

This stage should be fast and should handle the most common failure modes without any model call.

Stage 2: Lightweight Embedding Model

Use a small image embedding model to compare frames to the reference bank.

Recommended default:

• openai/clip-vit-base-patch32

Why:

• mature
• simple
• good enough for zero-shot and embedding retrieval
• much lighter than a full VLM
• can run on CPU

This stage should answer:

• which reference frame is this closest to
• which scene family cluster is this closest to
• whether PS1 is semantically near the expected reference state

Stage 3: Sampled Semantic Explainer

Use a small VLM only on selected frames:

• first visible scene frame
• first mismatch frame
• best-match frame
• final frame
• one or two boundary frames around a divergence

This stage produces:

• short caption
• visible actors/objects
• rough action summary
• “background only” vs “live scene content”

Do not run a VLM across every captured frame at first.

Stage 4: Optional Tiny Supervised Classifier

Once we have enough labeled reference and PS1 frames, train a tiny classifier for:

• screen_type
• sprites_visible
• johnny_present
• mary_present
• likely_scene_family

This stage is optional and should happen only after the earlier pipeline proves which labels are stable and useful.

Recommended Models Under 8 GB RAM

1. CLIP ViT-B/32

Model:

• openai/clip-vit-base-patch32

Role:

• default embedding model
• zero-shot classifier for coarse labels

Why:

• lowest-risk default for a reference-bank system
• good for nearest-neighbor retrieval
• no need to train to get immediate value

Use it for labels like:

• title screen
• black screen
• ocean background only
• beach scene with character
• Johnny visible
• Mary visible
• raft visible

2. Florence-2-base-ft

Model:

• microsoft/Florence-2-base-ft

Role:

• sampled-frame semantic explainer
• captioning and object-oriented prompting

Why:

• small by VLM standards
• multi-task prompting is useful
• better explanatory power than CLIP

Use it for:

• sampled mismatch frames
• human-review summaries
• first-pass pseudo-labeling on the reference set

3. SmolVLM-500M

Model:

• HuggingFaceTB/SmolVLM-500M-Instruct

Role:

• fallback low-memory VLM

Why:

• designed for constrained devices
• smaller than most VLMs
• useful if Florence-2 is too slow or memory-heavy on CPU

4. moondream2

Model:

• vikhyatk/moondream2

Role:

• optional CPU captioner if its dedicated runtime proves stable locally

Why:

• plausible CPU memory footprint
• popular for lightweight image description

Risk:

• more integration complexity than CLIP
• less attractive as the first default in this repo

Reference-Grounded Labeling Strategy

This is where we use our existing knowledge aggressively.

Pass A: Deterministic Label Seed

For all reference frames, assign cheap seed labels:

• black
• title-like
• ocean-heavy
• telemetry-present
• scene-like

Pass B: Nearest-Neighbor Clustering

Compute embeddings for all reference frames and cluster them by:

• scene family
• visual phase
• sprite density

This gives us prototype groups like:

• ACTIVITY beach with Johnny
• ACTIVITY ocean-only intro
• title/menu
• black/transition
• FISHING island

Pass C: Sampled VLM Annotation

Do not caption every frame.

Instead caption:

• cluster centers
• cluster outliers
• representative frames per scene
• known important frames:
  • first visible scene frame
  • middle frame
  • final frame

Then propagate those labels through nearest-neighbor groups.

This keeps VLM cost low while still giving us semantic labels for almost the whole reference bank.

Pass D: Human Correction Loop

Build review pages so we can quickly correct:

• wrong actor names
• wrong family labels
• wrong action summaries

Then persist corrected labels back into the reference bank.

How PS1 Comparison Should Work

For a PS1 run:

1. identify expected reference scene
2. for each sampled PS1 frame:
   • deterministic triage
   • embedding lookup
   • nearest reference match within expected scene
   • nearest global reference match
3. emit both:
   • best_expected_match
   • best_global_match

This distinction matters.

Examples:

• expected scene says ACTIVITY-1, but global match says FISHING-3
• expected scene says ACTIVITY-1, expected-match frame is ocean-only and global-match frame is also ocean-only
• expected scene says ACTIVITY-1, best expected match is correct background but labels show sprites_visible = false

That gives us much better debugging signal than pixel mismatch alone.

Proposed Output Files

Per reference bank build:

• regtest-references/index.json
• regtest-references/embeddings/clip-vit-base-patch32.f16.npy
• regtest-references/semantic-labels.json
• regtest-references/captions.json

Per analyzed PS1 run:

• vision-analysis.json
• vision-summary.json
• vision-review.html

Example vision-summary.json:

{
  "scene": "ACTIVITY-1",
  "expected_family": "ACTIVITY",
  "frames_analyzed": 12,
  "best_expected_match_score": 0.81,
  "best_global_match_scene": "ACTIVITY-1",
  "dominant_failure_mode": "background_only_missing_sprites",
  "sprite_visible_ratio": 0.08,
  "title_like_ratio": 0.0,
  "ocean_only_ratio": 0.67,
  "notes": [
    "Background matches expected intro ocean frames.",
    "No later frame matches reference frames with visible Johnny sprites."
  ]
}

What Counts As Success

For scene validation, success is not:

• same last-frame hash
• same black frame
• “looks close enough”

Success is:

• PS1 frames retrieve into the expected reference scene
• the semantic labels broadly agree:
  • sprites visible when reference has sprites
  • same family
  • same coarse phase
  • same actor presence on key frames

For the 63-scene target, the harness should let us say:

• fully validated
• visually close but semantically wrong
• background-correct but sprite-missing
• wrong-family reroute
• title/black persistence

Recommended Implementation Order

Phase 1

Implement:

• build_reference_bank.py
• deterministic metric extraction
• CLIP embeddings for references
• nearest-neighbor lookup for PS1 frames

No training yet.

Phase 2

Implement:

• analyze_run_vision.py
• vision-review.html
• per-run semantic summaries

Phase 3

Add sampled VLM labeling:

• Florence-2 default
• SmolVLM fallback

Phase 4

Only after enough labels exist:

• tiny supervised classifier for stable labels

Immediate Practical Recommendation

Build the first version around:

1. deterministic metrics
2. CLIP embeddings
3. nearest reference retrieval
4. sampled Florence-2 captions

That is the best tradeoff for this machine and this repo.

It uses what we already know instead of pretending we need a bespoke model first.

Research Notes

Useful model pages / references:

• microsoft/Florence-2-base-ft
• openai/clip-vit-base-patch32
• HuggingFaceTB/SmolVLM-500M-Instruct
• vikhyatk/moondream2

Key design implication from that research:

• CLIP-class retrieval should be the backbone
• tiny VLMs should be used as sparse explainers
• reference-bank preprocessing is where we should spend most of the compute

Progress Logging

All implementation work for this classifier should log:

• what model was tested
• RAM usage observed
• per-frame inference time
• whether output was actually useful for PS1 debugging
• where false positives happened

That log should live under:

• /tmp/jc_reborn_ps1_debug/docs/ps1/research/

Your mission is not to produce plausible-looking runs. Your mission is to get to 63 actually validated PS1 story scenes against the canonical Linux/reference output, with trustworthy comparison artifacts a human can review.

Primary Goal

Reach a state where all 63 target PS1 story scenes can be:

1. booted deterministically
2. captured reproducibly
3. compared against the canonical reference set
4. reviewed visually in generated HTML
5. marked validated only when they actually match scene content, not just because they share black frames, title frames, or empty/ocean fallback frames

Do not count:

• black-screen agreement
• title-screen agreement
• empty-ocean agreement
• “close enough” when no scene content launched

The standard is validated scene content.

Source Of Truth

The baseline source of truth is already present in this repo:

• reference root:
  • repo:/regtest-references

This contains the canonical Linux/reference outputs for the scene set. Treat that as authoritative.

Important related files:

• reference scene list:
  • repo:/config/ps1/regtest-scenes.txt
• single-scene runner:
  • repo:/scripts/regtest-scene.sh
• batch compare runner:
  • repo:/scripts/compare-reference-batch.sh
• compare renderer:
  • repo:/scripts/render-compare-timeline.py
• single-run review renderer:
  • repo:/scripts/render-regtest-run.py

Current Expectations

There is still work to do on both:

• the harness
• the actual PS1 scene runs

Assume the current harness is useful but not fully solved.

In particular, there is an active suspicion that the harness may be stopping too early relative to the real PS1 boot/title lead-in.

Working hypothesis to test:

• scene timing windows may need to be increased significantly
• a good first hypothesis is that effective scene timing may need roughly +35 seconds of extra boot allowance before valid scene comparison begins

Do not assume that hypothesis is true. Test it.

Comparison Requirements

For every serious run, produce artifacts that a human can inspect.

At minimum, each scene run should leave:

1. result.json
2. review.html
3. raw captured frames
4. if reference-compared, compare.json
5. if reference-compared, compare.html

The human must be able to open the HTML and confirm whether the run contains real scene content.

How To Compare Correctly

Single PS1 run review

Use:

• repo:/scripts/regtest-scene.sh

This now emits:

• result.json
• review.html

The review page is for raw PS1 inspection only. It is not proof of correctness by itself.

PS1 vs reference comparison

Use:

• repo:/scripts/compare-reference-batch.sh

This should be the main path for actual validation sweeps against the canonical reference set.

Expected comparison artifacts per scene:

• compare.json
• compare.html

If compare alignment fails, that is not a pass. It means the harness or the run still needs work.

Validation rule

A scene is only validated when:

• the PS1 run clearly reaches the intended scene
• the scene content aligns against the reference in a defensible way
• the generated HTML artifacts support that claim

Current Harness Concerns To Investigate

You should actively test and improve these:

1. Boot lead-in may be under-budgeted.
   • Current scene windows may begin too early.
   • Test longer frame budgets and later alignment windows.
2. Some current comparisons may overweight title/black/ocean contamination.
   • The harness must reject invalid anchors instead of fabricating confidence.
3. HTML output must always exist for human review.
   • Keep that invariant.
4. The “best frame” or “state hash” is not enough.
   • Validation must be scene-content driven.
5. If the compare path falls back, make that obvious.
   • Fallback review pages are useful, but they are not validated compare pages.

Current PS1 Runtime Debug Context

The active deep bug work has been concentrated on ACTIVITY 1.

Current strongest runtime read:

• the live seam is likely in ps1PilotLoadPackIndex(...) in:
  • repo:/cdrom_ps1.c
• it appears stack-layout-sensitive
• exact local ordering of:
  • cdPath
  • cdfile matters
• tiny caller-frame changes around CdSearchFile(...) move the runtime between stable bad branches

This means:

• do not assume a clean logic bug
• suspect UB, overwrite, or stack-sensitive corruption around the pack-file lookup path

That said, do not get trapped in only one scene forever if the better immediate win is harness confidence or a different scene that is closer to validated.

Recommended Work Sequence

1. Verify the harness outputs are always reviewable.
   • review.html for single runs
   • compare.html for reference comparisons
2. Audit timing assumptions.
   • Test whether boot grace, scene-entry windows, or total run length need to move later
   • Specifically test the “add roughly 35 seconds” hypothesis
3. Run targeted scene comparisons against the reference set.
   • Prefer one scene at a time when debugging
   • Prefer broader sweeps when ranking “closest to validated”
4. Identify the easiest real win.
   • Choose scenes that already show actual content and are closest to aligned reference output
5. Only then return to deeper runtime surgery when needed.

Logging Requirements

Keep a concise progress log in:

• repo:/docs/ps1/research/HARNESS_WORKLOG_2026-03-28.md

For each significant step, record:

• what was changed
• what run was executed
• where the result artifacts are
• what conclusion is justified
• what the next target is

Do not write vague summaries. Record the actual result and the actual conclusion.

Standards

Be skeptical of false positives.

If a scene:

• never launches
• only shows water
• only shows black
• only shows title
• or fails to align cleanly against reference

then it is not validated.

The end goal is:

• 63 scenes
• all human-reviewable
• all compared against canonical reference
• all validated on real scene content

• Replace the old final-frame/hash-based PS1-vs-reference harness with a scene-sequence harness that compares PS1 output against the canonical host baseline corpus in regtest-references/.

Current status

• Canonical host baseline corpus exists in regtest-references/ for all 63 scenes.
• Core sequence comparator has been upgraded to:
  • align on scene entry
  • separate PS1 pre-scene, in-scene, and post-scene frames
  • report MATCH, PIXEL_MISMATCH, TIMING_MISMATCH, or ALIGNMENT_FAILED
• regtest-scene.sh can now request sequence-based baseline analysis against a canonical scene directory.
• compare-reference-batch.sh has been rewired toward sequence comparison and canonical reference defaults.
• build-ps1.sh now recreates build-ps1/ if cleanup removed it.
• Raw PS1 output roots with nested Docker frame directories are now discovered correctly by compare-sequence-runs.py.
• regtest-scene.sh now has a --fast-baseline mode for interactive validation runs that skips full telemetry/visual-batch postprocess.
• Host capture now stamps engine-truth scene_start_frame / scene_end_frame from the executable itself.

Known issues

• Full-frame PS1 telemetry decode is still too expensive for interactive per-frame validation unless --fast-baseline is used.
• First live validation scene (BUILDING 1) still does not produce a positive PS1-to-host alignment yet.
• Old Dockerized regtest outputs can leave root-owned files in result directories; reruns should use fresh output dirs or the harness should isolate/chown them.
• The sequence comparator is still too slow once the PS1 side has thousands of candidate frames; entry-anchor search needs one more optimization pass before it becomes a comfortable interactive loop.

Validated so far

• Canonical host references are present and organized.
• Shell/python syntax for the updated harness scripts is clean.
• The PS1 validation lane now reaches the sequence comparator instead of failing earlier on missing build directories or missing result metadata.
• BUILDING 1 host reference starts at real scene content; visual_detect.py is unreliable on host BMP frames and must not be used as the host entry oracle.
• BUILDING 1 PS1 story single 10 remains in title/ocean flow for a long time; the first scene-like sampled frame in a 4200-frame probe is frame_03660.png.
• That same PS1 probe still does not match the canonical BUILDING 1 host baseline by frame_04200; this is a real content mismatch, not just a missing-frames plumbing failure.
• A short story direct 10 PS1 validation run still spends hundreds of frames in BIOS startup, so even the direct lane needs a larger boot budget than 600 frames.
• story direct is not an apples-to-apples baseline route. story single preserves the normal startup flow, while story direct bypasses it and adds a 600-frame hold tail by design.
• Fresh host ACTIVITY 1 capture with engine markers reports scene_start_frame = 7, scene_end_frame = 328, frames_captured = 328. So host scene boundaries no longer need to be guessed visually.
• A cheap sampled PS1 scan for ACTIVITY 1 shows first non-title content around frame 2700, but it is ocean, not the host activity scene.
• The comparator now fails fast on missing anchors instead of hanging for minutes; remaining speed pain is reduced to long known-fail searches rather than general unusability.
• Fresh host-vs-host ACTIVITY 1 comparison is an exact MATCH with frame_offset = 0, common_frame_count = 328, and average_palette_index_diff_pixels = 0.0. The comparator now has a real positive-control path.
• Long sampled PS1 run for ACTIVITY 1 reaches ocean around frame 2700 and does not reach any host-matchable ACTIVITY 1 scene even after entering island content around frame 6300.
• Late-window compare against the long sampled PS1 run still reports missing verified scene_entry anchor, so the PS1 side is eventually showing the wrong island scene, not merely arriving late to the right one.

Next steps

1. Trace why PS1 story single boots are entering the wrong island scene for ACTIVITY 1.
2. Use ACTIVITY 1 as the first live PS1 route/debug target until the requested scene is actually reached.
3. After that, revalidate BUILDING 1 on the same harness and continue scene-by-scene.
4. Keep the harness stable and avoid further heuristic scene-entry work unless a new gap appears.

Progress update

• Fast direct validation lane shows PS1 still in BIOS/logo at ~frame 1500 and plain ocean at frames 2000-2400 for story direct 10.
• This strongly suggests a real PS1 scene-routing mismatch for BUILDING 1, not just harness timing error.
• The remaining harness gap is no longer host scene detection; it is PS1 entry-window search and comparator speed over long PS1 captures.
• With host scene markers in place, the next blocker is no longer “when does host scene begin?” but “why does PS1 story single land in ocean content for scenes like ACTIVITY 1?”
• Next debug target after the speed pass: trace PS1 story-route handling for ACTIVITY 1 / BUILDING 1 and fix that before deeper pixel work.
• Comparator confidence is now materially higher: host capture + host reference can round-trip to an exact match, so the remaining failures are on the PS1 path or in PS1-to-host alignment policy, not in basic compare mechanics.
• Practical conclusion: the harness is now good enough for scene debugging. The current blocker is a real PS1 route/content bug, first visible on ACTIVITY 1.
• Debugging moved into ACTIVITY 1 as the first real PS1 scene bug target.
• story single 0, story scene 0, and exact story ads ACTIVITY.ADS 1 all hit the same wrong ocean window by frame 4200, so the failure is not scene-index mapping.
• Narrowing the old random empty-launch ADS retry from all families down to BUILDING.ADS did not change ACTIVITY 1 behavior.
• Added robust current-ADS family/tag markers into the PS1 scene-marker strip so sampled frames can now tell us exactly what PS1 thinks is active during the bad window.
• Added current ADS family/tag telemetry to the PS1 scene-marker strip.
• First marker probe on ACTIVITY 1 shows current_ads_family=0 / current_ads_tag=0 at frames 2700 and 4200, with ADD_SCENE seen but launched=false.
• Long exact boot story ads ACTIVITY.ADS 1 still does not reach host ACTIVITY 1.
• Sampled frames 2700 and 4200 remain in failed-launch ocean (launched=false, family=0, tag=0).
• By frames 6300 and 8700, PS1 has transitioned into live island content with Johnny/raft/palm that visual detection classifies as FISHING-like, not ACTIVITY.
• So ACTIVITY.ADS 1 on PS1 is not merely late; it eventually turns into the wrong scene family/content.
• Added requested-scene and boot-pending markers to the robust PS1 strip to separate story selection bugs from ADS launch bugs.
• Fixed regtest-scene.sh scene-label parsing so scratch labels with spaces no longer corrupt ADS_NAME / SCENE_TAG or break result summary generation.
• Switched requested/current ADS markers to white bit-cells for more robust decode.
• On the ACTIVITY.ADS 1 bitmark probe, boot_pending stays asserted at frames 2700 and 4200 while the run remains in failed-launch ocean.
• That rules out early override consumption as the main remaining bug; the failure is downstream of story selection, inside PS1 ADS/TTM launch state.
• Enlarged the isolated black telemetry backdrop for requested/current ADS bit-cell rows so lower rows no longer bleed against live scene pixels.
• Added ps1AdsDbgZeroIpLaunches telemetry to distinguish tag-resolution failure from later immediate thread death.
• Added zero_ip_launch to the robust scene-marker decoder and reran an exact story ads ACTIVITY.ADS 1 PS1 probe on the rebuilt image.
• Fresh decode at frames 2700 and 4200 shows:
  • launched=false
  • add_scene=true
  • tag_hit=true
  • bmp_fail=true
  • sprite_seen=true
  • boot_pending=1
  • zero_ip_launch=true
• However, authored bytecode inspection shows ACTIVITY.ADS tag 1 starts with valid nonzero launches:
  • slot 1 / GJDIVE.TTM / tag 12 / ip 42
  • slot 1 / GJDIVE.TTM / tag 13 / ip 126
• That means the later zero_ip_launch signal in the ocean window is a downstream symptom, not proof that the initial ACTIVITY 1 launch target is bad.
• The next debug question is no longer “does ACTIVITY.ADS 1 target slot 0?” It is “why do the valid initial GJDIVE scene launches fail to survive into a live PS1 scene before the run drifts into unrelated content?”
• Added sticky robust-strip bits for the authored ACTIVITY 1 startup launches:
  • activity_init12_launched
  • activity_init13_launched
  • activity_init12_ended
  • activity_init13_ended
• Fresh exact PS1 probe on the rebuilt image still reproduces the same failure:
  • title/transition noise around 300-600
  • black by 900-1200
  • wrong-ocean failure window by 2700 and 4200
• In that bad ocean window, the new strip bits indicate PS1 is at least touching the authored GJDIVE startup path rather than a totally unrelated scene family from the outset:
  • activity_init12_launched = true
  • activity_init13_launched = false on the sampled decode
  • activity_init12_ended = false
  • activity_init13_ended = false
• The decode is still too coarse to treat the exact 12 vs 13 split as final truth, but it is enough to shift the hypothesis again:
  • PS1 is not simply ignoring ACTIVITY.ADS 1
  • it is entering the ACTIVITY launch path, then collapsing before a stable live scene forms
• Next target: instrument per-thread startup failure more directly around GJDIVE.TTM tags 12 and 13 so we can tell whether one of them is never started, immediately terminates, or is superseded by a later bad launch.
• Added live robust-strip bits for:
  • activity_init12_running
  • activity_init13_running
• Fresh exact probe with those rows shows:
  • at 300 and 600: both 12 and 13 appear as launched/running during startup/title-path noise
  • at 2700 and 4200: neither 12 nor 13 is running anymore
  • the bad ocean window still shows:
    • add_scene=true
    • tag_hit=true
    • zero_ip_launch=true
    • bmp_fail=true
    • sprite_seen=true
• So the current read is stronger now:
  • the authored ACTIVITY startup TTM threads do exist early
  • they are gone long before the later wrong-ocean window
  • the bad ocean state is a later broken relaunch/fallback condition, not the original GJDIVE 12/13 scene simply staying alive in the wrong form
• Next target: identify what later ADD_SCENE / relaunch path is taking over after the initial ACTIVITY startup threads disappear.
• Added sticky robust-strip bits for later authored ACTIVITY relaunch edges:
  • activity_tag7_launched
  • activity_tag8_launched
  • activity_tag9_launched
  • activity_tag11_launched
  • activity_tag14_launched
  • activity_slot2_tag2_launched
• Fresh exact story ads ACTIVITY.ADS 1 probe to 4200 with those rows:
  • repo:/regtest-results/activity1-ads1-seed1-relaunchtrace/result.json
  • At frame_02700 the bad ocean window still shows:
    • launched=false
    • add_scene=true
    • tag_hit=true
    • zero_ip_launch=true
    • none of activity_tag7/8/9/11/14 or activity_slot2_tag2 are set
• Long exact probe to 9000 with 900-frame sampling:
  • repo:/regtest-results/activity1-ads1-seed1-relaunchtrace-long/result.json
  • By frame_06300 and still at frame_08100, the later wrong live scene shows:
    • launched=true
    • tag_miss=true
    • zero_ip_launch=true
    • activity_tag11_launched=true
    • activity_slot2_tag2_launched=true
    • activity_tag7/8/9/14=false
    • activity_init12_running=true
    • activity_init13_running=true
• This narrows the active PS1 bug again:
  • the bad ocean window at 2700-4200 happens before the later authored ACTIVITY relaunch chain is touched
  • by 6300+, the authored relaunch chain has advanced at least as far as ACTIVITY tag 11 -> slot 2 tag 2
  • the eventual wrong live scene therefore appears during or after that later authored relaunch handoff, not during initial story selection and not during the first GJDIVE 12/13 startup launches
• Next target: instrument the transition from ACTIVITY tag 11 / slot2:2 into the later zero_ip_launch live scene takeover, because that is now the narrowest unexplained edge in the failure.
• Added later handoff liveness/end rows:
  • activity_tag11_running
  • activity_slot2_tag2_running
  • activity_tag11_ended
  • activity_slot2_tag2_ended
• Fresh rebuilt long probe:
  • repo:/regtest-results/activity1-ads1-seed1-handofftrace-long/result.json
• Decoded checkpoints:
  • frame_02700:
    • add_scene=true
    • tag_hit=true
    • zero_ip_launch=true
    • activity_tag11_launched=false
    • activity_slot2_tag2_launched=false
    • activity_tag11_running=false
    • activity_slot2_tag2_running=false
  • frame_06300 and frame_08100:
    • launched=true
    • tag_miss=true
    • zero_ip_launch=true
    • activity_tag11_launched=true
    • activity_slot2_tag2_launched=true
    • activity_tag11_running=false
    • activity_slot2_tag2_running=false
    • activity_tag11_ended=false
    • activity_slot2_tag2_ended=false
• That tightens the read further:
  • by the later wrong-scene window, the authored ACTIVITY relaunch chain has definitely touched tag11 -> slot2:2
  • but those threads are no longer running there
  • and they are not being observed to terminate cleanly through adsStopScene()
  • the later wrong live scene therefore looks like a takeover after launched threads disappear without a normal observed stop, while zero_ip_launch continues to accumulate
• Next target: instrument where launched ACTIVITY tag11 / slot2:2 threads are being invalidated or superseded without a normal stop, and connect that to the continuing zero_ip_launch takeover path.
• Dumped the authored reachable ACTIVITY.ADS 1 chunk graph with the real parser:
  • entry chunk bookmarks 1:13, 1:8, 1:7, 1:9, 1:14, 2:2
  • direct chunk contents confirm the authored loop:
    • 1:13 randomly launches 1:8, 1:7, 1:9
    • 1:8/7/9 can launch 1:14
    • 1:14 launches 2:2
    • 2:2 relaunches 1:13
• Ran a denser transition probe:
  • repo:/regtest-results/activity1-ads1-seed1-transitiontrace/result.json
• Decoded transition band:
  • frame_05400 through frame_06000:
    • launched=false
    • add_scene=true
    • tag_hit=true
    • zero_ip_launch=true
    • activity_tag11_launched=false
    • activity_slot2_tag2_launched=false
  • frame_06150:
    • launched=true
    • tag_miss=true
    • zero_ip_launch=true
    • activity_tag11_launched=true
    • activity_slot2_tag2_launched=true
    • neither is running anymore by the time of the sample
• That narrows the failure boundary again:
  • the later authored ACTIVITY relaunch loop first becomes visible between 6000 and 6150
  • zero_ip_launch is already active well before that switch
  • so the zero-IP takeover is not a consequence of the tag11/slot2:2 handoff; it predates it and persists through it
• Next target: instrument the exact launch happening in the 6000-6150 window and record the slot/tag/IP of the first live scene that appears once launched=true flips on.
• Found a real decoder bug in scripts/decode-ps1-bars.py: scene-marker rows were being scaled against 448 lines instead of native 480, which vertically misaligned the robust strip decode on PS1 screenshots.
• After fixing the scene-marker scale to img.height / 480.0, the later handoff frame reads materially differently and more plausibly:
  • frame_06150 now decodes as:
    • launched = true
    • activity_tag11_running = true
    • activity_slot2_tag2_running = true
    • activity_live_slot2 = true
    • activity_live_ip_zero = true
    • activity_live_ip_nonzero = false
  • the live-thread tag one-hots for 2, 11, and 13 are all false in that same frame
• Current read after the decoder fix:
  • the first visible live thread at the handoff is a slot 2 thread with ip == 0
  • it is not one of the expected tag one-hots currently instrumented (2, 11, 13)
  • meanwhile the authored ACTIVITY handoff threads (tag11 and slot2:2) are still marked as running in the same frame
• This narrows the PS1 bug again:
  • the bad takeover at the handoff is now consistent with a live slot 2 zero-IP thread preempting the intended authored loop
  • the next probe should identify that live slot 2 tag exactly, rather than continuing to infer from the old compact bitcells or noisy emulator logs

2026-03-28 12:59 PDT

• Found and fixed a real PS1 libc corruption source in ps1_stubs.c:
  • vprintf() was using raw vsprintf() into a fixed char buffer[1024]
  • switched it to bounded vsnprintf(buffer, sizeof(buffer), ...)
• Validation result:
  • this fix was real but not sufficient by itself
  • the focused ACTIVITY.ADS 1 rerun still eventually degraded into UnknownReadHandler / UnknownWriteHandler at pc 0x8002D88C / 0x8002C998
  • however, the corruption wave moved much later in wall-clock time, which proved the vprintf overflow was one contributor

2026-03-28 14:30 PDT

• Added later-runtime boot-state probes instead of early boot printf/fatalError traps.
• The compact boot bit-cell rows and the enlarged story bar panel are both too visually contaminated in live frames to trust numerically:
  • at frame_02700 in the stable wrong-ocean window, the new boot-state rows still decode as zero
  • but the story bars saturate to junk widths like 90, so those panels are not a reliable proof surface
• Switched to clean late yes/no traps in story.c:
  1. trap if storyPlayPreparedScene(ACTIVITY.ADS, 1) is entered and launch fails
  2. trap if storyPlayPreparedScene(ACTIVITY.ADS, 1) is entered at all
  3. trap if storyPlay() reaches the storyBootAdsName/storyBootAdsTag boot-scene branch for ACTIVITY.ADS 1
• Results:
  • none of those traps fired in stable exact PS1 runs
  • not by 2700 frames:
    • repo:/regtest-results/activity1-ads1-seed1-launchfailtrap/result.json
    • repo:/regtest-results/activity1-ads1-seed1-bootbranchtrap/result.json
  • and not even by 6300 frames for the prepared-scene entry trap:
    • repo:/regtest-results/activity1-ads1-seed1-entrytrap-6300/result.json
• This is the cleanest narrowing so far:
  • the stable PS1 path is not reaching storyPlayPreparedScene(ACTIVITY.ADS, 1)
  • and it is not even reaching the storyPlay() boot-scene resolution branch for story ads ACTIVITY.ADS 1
  • so the active root cause is upstream of ADS launch and upstream of story scene dispatch
• Current best hypothesis:
  • BOOTMODE.TXT is present on disc, but the story ads ... override is not being retained/applied by the runtime path that reaches storyPlay()
  • the next target is the PS1 boot-override load/reapply path, not ACTIVITY ADS internals
• Follow-up probes on the same branch:
  • Added a trap in storyPlay() itself to dump raw boot-state (storyBootSingleSceneIndex, storyBootSceneIndex, storyBootAdsName, storyBootAdsTag) on loop entry.
  • The run terminated extremely early with only 3 captured frames:
    • repo:/regtest-results/activity1-ads1-seed1-storyloopbootstate/result.json
  • But, as with earlier very-early guest traps, the expected guest fatal text still did not surface in the extracted logs.
• Practical interpretation:
  • early/pre-dispatch guest fatal output remains an unreliable proof surface under the current regtest path
  • later negative traps remain trustworthy:
    • the stable path still does not reach storyPlay()’s boot-scene branch for ACTIVITY.ADS 1
    • and still does not reach storyPlayPreparedScene(ACTIVITY.ADS, 1) by 6300
  • so the active bug remains upstream of story scene dispatch, in PS1 boot-override retention/application or in the transition from boot parsing into the story loop
• Then removed the remaining live PS1 scene-trace printf() traffic from the hot ACTIVITY path while preserving the strip markers and the hard zero-IP trap:
  • removed [STORY] ... boot/final prints from repo:/story.c
  • removed [ADS] initial launch empty ..., [ADSPLAY] after chunk ..., and [ACT1LIVE] ... prints from repo:/ads.c
• This produced the first clean long ACTIVITY 1 PS1 run without fatal corruption:
  • repo:/regtest-results/activity1-ads1-seed1-quiettrace6300/result.json
  • frames = 6300
  • interval = 150
  • exit_code = 0
  • timed_out = false
  • frames_captured = 41
  • has_fatal_error = false
• Clean visual timeline from that run:
  • frame_02700 through frame_06000: still wrong ocean
  • frame_06150 and frame_06300: wrong live island / FISHING-like scene
• Clean robust-strip decode at the handoff:
  • repo:/regtest-results/activity1-ads1-seed1-quiettrace6300/20260328-125856/frames/jcreborn/frame_06000.png
    • scene_markers launched=no add_scene=no tag_hit=yes tag_miss=yes bmp_ok=no sprite_seen=yes
  • repo:/regtest-results/activity1-ads1-seed1-quiettrace6300/20260328-125856/frames/jcreborn/frame_06150.png
    • scene_markers launched=yes add_scene=yes tag_hit=no tag_miss=no bmp_ok=yes sprite_seen=no
  • repo:/regtest-results/activity1-ads1-seed1-quiettrace6300/20260328-125856/frames/jcreborn/frame_06300.png
    • scene_markers launched=yes add_scene=yes tag_hit=no tag_miss=no bmp_ok=yes sprite_seen=no
• Current read after removing the corrupting trace path:
  • the earlier catastrophic memory corruption was at least partly self-induced by our PS1 printf tracing
  • the underlying ACTIVITY 1 scene bug still remains, now exposed cleanly again
  • the real failure shape is:
    • failed-launch / wrong-ocean window through 6000
    • then wrong live FISHING-like scene by 6150
• Next target:
  • compare this clean quiettrace6300 PS1 run directly against the canonical host ACTIVITY-1 reference window
  • then resume debugging the actual 6000-6150 handoff with strip markers and narrow traps only, not live formatted PS1 logging

2026-03-28 13:02 PDT

• Completed the clean PS1-vs-host validation on the no-printf ACTIVITY 1 run:
  • PS1 run:
    • repo:/regtest-results/activity1-ads1-seed1-quiettrace6300/result.json
  • compare result:
    • /tmp/activity1-quiettrace6300-vs-host.json
• Compare verdict:
  • verdict = PIXEL_MISMATCH
  • frame_offset = 1800
  • common_frame_count = 3
  • reference_coverage_ratio = 0.008426966292134831
  • average_palette_index_diff_pixels = 126892.66666666667
• Practical meaning:
  • the harness is now doing its job on a clean PS1 run
  • the PS1 ACTIVITY 1 sequence only brushes the host scene window at entry, then diverges almost immediately
  • this is a real scene/content bug, not a remaining harness artifact
• Clean visual shape remains:
  • frame_02700 through frame_06000: wrong ocean
  • frame_06150 and frame_06300: wrong island / FISHING-like scene
• Current confidence statement:
  • host baseline path is trusted
  • sequence comparator is trusted for this scene
  • PS1 logging-induced corruption has been reduced enough that the real ACTIVITY 1 failure is visible again
• Next target:
  • keep ACTIVITY 1 as the first active PS1 fix
  • debug the actual 6000-6150 handoff on the clean quiet path, without restoring the old formatted PS1 trace traffic

2026-03-28 13:31 PDT

• Ran a widened ACTIVITY 1 live-tag probe on the clean quiet path:
  • repo:/regtest-results/activity1-ads1-seed1-livetags/result.json
• The run completed cleanly through 6300 frames and kept the same visible failure shape:
  • frame_06000: wrong ocean
  • frame_06150, frame_06300: wrong live island scene
• Decoded robust-strip state at frame_06150 / frame_06300:
  • current_ads_family_estimate = 1
  • current_ads_tag_estimate = 1
  • launched = true
  • add_scene = true
  • zero_ip_launch = true
  • activity_live_slot2 = true
  • activity_live_ip_zero = true
  • authored ACTIVITY live-tag one-hots remain all false for the currently instrumented tags:
    • activity_live_tag7 = false
    • activity_live_tag8 = false
    • activity_live_tag9 = false
    • activity_live_tag12 = false
    • activity_live_tag14 = false
    • activity_live_tag2 = false
    • activity_live_tag11 = false
    • activity_live_tag13 = false
• Practical read:
  • the wrong live scene still appears to be occurring inside ACTIVITY.ADS tag 1, not from a clean family switch
  • but the active live thread visible in the robust strip still does not match any authored ACTIVITY tag we were explicitly drawing
• Added a more direct overlay probe:
  • raw robust rows for exact firstIdx.sceneSlot low bits
  • raw robust rows for exact firstIdx.sceneTag low bits
  • decoder support for live_scene_slot_robust / live_scene_tag_robust
• That follow-up rerun did not stay clean:
  • repo:/regtest-results/activity1-ads1-seed1-livetags-robust/regtest.log
  • it regressed into heavy UnknownReadHandler spam at pc 0x8002D9FC before producing trustworthy postprocess output
• Current state:
  • harness remains good enough on the clean quiettrace6300 / livetags path
  • ACTIVITY 1 is still the first real scene bug
  • the next fix/debug target is still the ACTIVITY handoff itself, but the new exact-tag probe needs to be rerun in a way that preserves the clean runtime behavior

2026-03-28 13:40 PDT

• Reverted the invasive exact-tag overlay rows after they destabilized the runtime, and switched to one-shot engine traps instead.
• Two focused ACTIVITY probes completed cleanly:
  • repo:/regtest-results/activity1-ads1-seed1-zeroip-launchtrap/result.json
  • repo:/regtest-results/activity1-ads1-seed1-startup-alive-trap/result.json
• New stable behavior on both runs:
  • frame_06000, frame_06150, and frame_06300 all remain wrong ocean
  • the earlier wrong-island handoff is not stable enough to treat as the real bug surface
• Important negative results:
  • the non-background zero-ip launch trap did not fire after frame 5000
  • the startup-thread-alive trap for ACTIVITY slot1 tag12/tag13 did not fire after frame 5000
• Static authored check:
  • GJDIVE.TTM tag 12 reaches 0x0110 and then 0x0FF0 almost immediately, so it should not live for thousands of frames
  • the fact that the engine trap did not see tag 12 or 13 still running means the older strip decode on those startup bits was over-reporting
• Current stable read:
  • harness is still at practical confidence
  • ACTIVITY 1 does not reach the intended ACTIVITY scene content on PS1
  • the stable bug surface is now: booted ACTIVITY scene collapses back to ocean and stays there through 6300
  • the immediate next target is no longer “later ACTIVITY handoff tag”; it is “why no later successful ACTIVITY launch happens at all on the stable run”

2026-03-28 13:46 PDT

• Pulled the authored startup graph directly from generated analysis and extracted bytecode:
  • ACTIVITY.ADS tag 1 starts with slot 1 tag 12 and slot 1 tag 13
  • later authored graph contains slot 1 tags 7/8/9/14/11 and slot 2 tag 2
• Dumped GJDIVE.TTM tag 12 from extracted content:
  • it reaches 0x0110 and then 0x0FF0 almost immediately
  • so it should terminate quickly, not remain the active long-lived state
• Added and ran a one-shot trigger trap in adsPlayTriggeredChunks() for ACTIVITY slot1 tag12/tag13:
  • repo:/regtest-results/activity1-ads1-seed1-trigger-trap/result.json
• Result:
  • trap did not fire
  • stable visual output remained wrong ocean through 6300
  • no evidence that startup tag 12/13 transitions are reaching the authored trigger path on the stable PS1 run
• Current read:
  • the stable ACTIVITY bug is now below later scene handoff logic
  • the next likely fault surface is the startup-thread termination / trigger pipeline itself:
    • either the startup thread is not terminating in the way the ADS scheduler expects
    • or the termination is happening without the expected adsPlayTriggeredChunks(slot=1, tag=12/13) handoff

2026-03-28 13:51 PDT

• Added and ran a one-shot termination trap on the ACTIVITY startup threads:
  • repo:/regtest-results/activity1-ads1-seed1-terminate-trap/result.json
• Result:
  • trap did not fire
  • run stayed wrong ocean through 6300
  • visual/state hash remained on the same stable bad branch as the trigger-trap run
• Combined with the previous negative trigger result:
  • startup tag 12/13 is not reaching adsPlayTriggeredChunks(slot=1, tag=12/13)
  • and it is also not entering the normal ADS_THREAD_TERMINATED branch in a way the engine sees
• Current narrowest read:
  • the ACTIVITY startup branch is being lost, overwritten, or bypassed before normal termination/trigger processing
  • next target should move earlier than ADS_THREAD_TERMINATED, likely around:
    • ttmPlay() changing isRunning
    • nextGotoOffset / ip evolution for GJDIVE tag 12/13
    • or direct thread-slot reuse before the expected termination path

2026-03-28 13:55 PDT

• Added a one-shot opcode trap directly inside ttmPlay() for ACTIVITY startup tags 12/13 at:
  • 0x0110 (PURGE)
  • 0x0FF0 (UPDATE)
• Reran the exact ACTIVITY boot:
  • repo:/regtest-results/activity1-ads1-seed1-ttm-opcode-trap/result.json
• Result:
  • trap did not fire
  • run again stayed on the same stable bad branch: wrong ocean through 6300
• Combined with earlier negatives:
  • startup tag 12/13 does not reach normal trigger handoff
  • does not enter the observed ADS_THREAD_TERMINATED branch
  • and now does not hit the expected authored early PURGE / UPDATE path in a way the runtime exposes
• Current best read:
  • the ACTIVITY startup thread is diverging before normal TTM control flow
  • next target must move even earlier than opcode-level lifetime handling:
    • startup thread ip initialization
    • TTM slot/data binding
    • or thread-slot reuse/corruption before the first expected UPDATE

2026-03-28 13:59 PDT

• Added the earliest startup-birth trap so ACTIVITY slot1 tag12/tag13 would abort immediately after adsAddScene() assigns ip:
  • trap condition:
    • ps1AdsCurrentName == ACTIVITY.ADS
    • ps1AdsCurrentTag == 1
    • ttmSlotNo == 1
    • ttmTag == 12 || ttmTag == 13
  • emitted fields if hit:
    • frame
    • idx
    • slot
    • tag
    • ip
    • dataSize
    • firstOpcode
    • arg3
• Reran the exact scene on that build:
  • repo:/regtest-results/activity1-ads1-seed1-addscene-birth-trap
• Result:
  • the birth trap did not fire
  • no ACT1 addScene ... fatal line appeared in printf.log, regtest.log, or extracted tty-output.txt
  • the run still completed capture/postprocess on the same stable bad branch
• This is stronger than the later negative traps:
  • startup tag12/tag13 is not being observed through:
    • normal adsAddScene() birth on the expected ACTIVITY startup path
    • normal trigger handoff
    • normal ADS_THREAD_TERMINATED
    • normal early authored PURGE / UPDATE
• Current best read:
  • either the startup launch request is not reaching the expected adsAddScene(slot1, tag12/13) call at all on PS1
  • or ps1AdsCurrentName/Tag is already no longer the expected ACTIVITY context by the time the launch is born
• Next target:
  • move one layer earlier than thread birth
  • instrument the exact launch request state before adsAddScene() is called:
    • requested ADS family/tag
    • current chunk slot/tag being executed
    • requested ttmSlotNo / ttmTag
    • whether the ACTIVITY startup launch is being rewritten before thread creation

2026-03-28 14:03 PDT

• Added an even earlier callsite trap in adsPlayChunk() for authored startup launches:
  • ADD_SCENE slot1 tag12/tag13
  • ADD_SCENE_LOCAL slot1 tag12/tag13
  • trap payload includes:
    • frame
    • requested slot/tag/arg3
    • inRandBlock
    • inSkipBlock
    • current trigger slot/tag
• Reran the exact scene:
  • repo:/regtest-results/activity1-ads1-seed1-addscene-callsite-trap
• Result:
  • the callsite trap did not fire
  • stable run still completed through 6300
  • no ACT1 add_scene_chunk or ACT1 add_scene_local line appeared in logs
• This strengthens the earlier negative traps:
  • on the stable PS1 path, the authored startup ADD_SCENE slot1 tag12/tag13 opcodes are not being observed at all

2026-03-28 14:05 PDT

• Added a one-shot trap immediately after adsLoad() inside adsPlay() for:
  • adsResource->resName == ACTIVITY.ADS
  • adsTag == 1
  • trap payload would have printed:
    • selected offset
    • dataSize
    • numTags
    • first three opcodes at the chosen entry point
• Reran the exact scene:
  • repo:/regtest-results/activity1-ads1-seed1-adsload-offset-trap
• Result:
  • the adsLoad() trap did not fire
  • run still exited cleanly with 41 captured frames
  • no ACT1 adsLoad ... line appeared in logs
• Current strongest read:
  • on the stable PS1 run, we are not even entering adsPlay("ACTIVITY.ADS", 1) on the path we thought we were
  • so the bug surface has moved out of ADS execution and back into the boot override / story dispatch path that is supposed to invoke adsPlay
• Next target:
  • instrument the story boot override path directly:
    • where story ads ACTIVITY.ADS 1 is parsed
    • where that request is held/persisted
    • and the exact site that is supposed to call adsPlay(boot_ads_name, boot_tag)

2026-03-28 14:11 PDT

• Probed progressively earlier boot/dispatch sites for the same exact override:
  • storySetBootScene("ACTIVITY.ADS", 1)
  • storyPlay() boot-scene selection for storyBootAdsName/storyBootAdsTag
  • ps1ApplyBootOverride() token parse for story ads ACTIVITY.ADS 1
  • ps1LoadBootOverride() after successful BOOTMODE read
  • ps1LoadBootOverride() early-return branches (CdSearchFile, zero-size, CdRead, CdReadSync)
• Trap strings for all of those probes are definitely present in the built executable and in the rebuilt disc snapshot:
  • build-ps1/jcreborn.exe
  • snapshot disc/jcreborn.bin
• The rebuilt disc snapshot also definitely contains the staged override string:
  • story ads ACTIVITY.ADS 1 seed 1
• Yet none of those early boot traps fire at runtime, and no existing [BOOT] ... prints appear in regtest logs either.
• Practical conclusion:
  • for very-early pre-graphics PS1 boot code, printf/fatalError-style probes are no longer a trustworthy validation surface under the current regtest path
  • this does not invalidate the later scene harness, only the latest method of proving early-boot execution
• Next target:
  • switch early boot diagnostics away from print/fatal probes and onto a non-print side effect that can be observed later in the frame output or runtime mode
  • use that to prove whether BOOTMODE.TXT is actually being loaded/applied on PS1

2026-03-28 14:48 PDT

• Confirmed a critical code-path detail in jc_reborn.c:
  • ps1HasBootOverridePending() intentionally ignores story ... overrides
  • so story ads ACTIVITY.ADS 1 always goes through the title path first
  • only ps1ReapplyBootOverride() can preserve that request for later story dispatch
• Tried three temporary late behavioral latches keyed on:
  • ps1BootDbgStoryAdsApplied
  • ps1BootDbgAdsSig == ACTIVITY
  • ps1BootDbgAdsTag == 1
• Latch attempts:
  • temporary storyPlay() reroute to BUILDING.ADS 1
  • temporary main() reroute to bench mode
  • temporary main() reroute to low-level island ads BUILDING.ADS 1
  • temporary main() hard early exit
• Validation runs:
  • repo:/regtest-results/activity1-ads1-seed1-behavioral-latch/result.json
  • repo:/regtest-results/activity1-ads1-seed1-main-latch/result.json
  • repo:/regtest-results/activity1-ads1-seed1-main-latch-ads/result.json
  • repo:/regtest-results/activity1-ads1-seed1-main-exit-latch/result.json
• Strongest result:
  • the main() hard-exit latch did not trigger
  • the run still followed the usual long path and dumped the normal sampled frames
  • so the story ads ACTIVITY.ADS 1 request is not surviving far enough to trip a post-reapply latch in main()
• Caveat:
  • 2700-frame visual controls are weak because several different boots still look the same there
  • but the hard-exit latch is not visual, and its failure is the strongest proof in this set
• Current best read:
  • the active bug is upstream of story dispatch and likely still inside the PS1 boot-override retention/reapply path
  • specifically: BOOTMODE.TXT may be read, but the parsed story ads ... request is not surviving into the later runtime state we expected
• Next target:
  • inspect where story boot globals are cleared between ps1ApplyBootOverride() and the later storyPlay() path
  • focus on storyResetBootState() / storySetBoot*() callsites and any startup path that may be wiping story override state after reapply

2026-03-28 15:03 PDT

• Replaced the old RAM-only post-title reapply with a second ps1LoadBootOverride() after loadTitleScreenEarly() in repo:/jc_reborn.c.
• Validation:
  • old long failing probe:
    • repo:/regtest-results/activity1-ads1-seed1-quiettrace6300/result.json
  • new long probe with reload-after-title:
    • repo:/regtest-results/activity1-ads1-seed1-reload-after-title-6300/result.json
• Important result:
  • state hashes changed
  • but sampled PNGs at 2700, 6000, 6150, and 6300 remained pixel-identical to the old failing run

• So the reload changes internal state retention, but it is not yet a visible scene fix.

• Then reran hard latches on the reload-after-title path:
  • top-of-storyPlay() boot-vars latch:
    • repo:/regtest-results/activity1-ads1-seed1-story-loop-latch/result.json
    • fired
  • storyBootAdsName/storyBootAdsTag ads branch latch:
    • repo:/regtest-results/activity1-ads1-seed1-boot-branch-latch/result.json
    • fired
  • storyBootSingleSceneIndex hijack latch:
    • repo:/regtest-results/activity1-ads1-seed1-single-index-latch/result.json
    • did not fire
  • storyBootSceneIndex hijack latch:
    • repo:/regtest-results/activity1-ads1-seed1-scene-index-latch/result.json
    • did not fire
  • non-null bootScene = storyFindSceneByAds(...) latch:
    • repo:/regtest-results/activity1-ads1-seed1-bootscene-null-check/result.json
    • fired
  • later post-selection / prepared-scene latches:
    • repo:/regtest-results/activity1-ads1-seed1-prepared-exit-latch/result.json
    • repo:/regtest-results/activity1-ads1-seed1-postselect-latch/result.json
    • did not fire
• Current narrow read:
  • with reload-after-title, the story ads ACTIVITY.ADS 1 override now survives into storyPlay()
  • it reaches the ads boot branch
  • it resolves a non-null bootScene
  • it is not being hijacked by storyBootSingleSceneIndex or storyBootSceneIndex
  • but the path still does not survive to the later post-selection / prepared-scene launch boundary
• Next target:
  • inspect the exact control flow between a non-null bootScene and the later post-selection / prepared-scene path
  • this is now the narrowest unexplained edge for ACTIVITY 1

2026-03-28 15:13 PDT

• Probed deeper around the exact bootScene -> finalScene -> storyPrepareSceneState() handoff.
• Results:
  • finalScene = bootScene immediate latch:
    • repo:/regtest-results/activity1-ads1-seed1-finalscene-assign-latch/result.json
    • fired
  • top of storyPrepareSceneState(ACTIVITY.ADS, 1):
    • repo:/regtest-results/activity1-ads1-seed1-preparestate-entry-latch/result.json
    • fired
  • after storyCalculateIslandFromScene() but before adsInitIsland():
    • repo:/regtest-results/activity1-ads1-seed1-pre-adsinitisland-latch/result.json
    • fired
  • after adsInitIsland():
    • repo:/regtest-results/activity1-ads1-seed1-post-adsinitisland-latch/result.json
    • fired
• So:
  • ACTIVITY.ADS 1 definitely survives through:
    • ads boot-branch lookup
    • finalScene = bootScene
    • storyPrepareSceneState(finalScene)
    • storyCalculateIslandFromScene(finalScene)
    • adsInitIsland()
• A same-run sticky-latch attempt that tried to carry “boot scene resolved” state forward to the later post-prepare block did not trip:
  • repo:/regtest-results/activity1-ads1-seed1-sticky-resolve-latch/result.json
• Current best read:
  • the path definitely reaches and returns from storyPrepareSceneState()
  • but the later post-prepare point is still not being observed with the same proof method
  • so the remaining gap is now after island prep and before or during the later debug/state block inside storyPlay()
• Next target:
  • instrument the immediate span after storyPrepareSceneState(finalScene) with a more explicit side effect than the prior return-style latch
  • likely by storing a sticky runtime flag after adsInitIsland() and validating it from a later safe point or overlay decode instead of relying on local early returns

2026-03-28 15:34 PDT

• The harness remains at practical full confidence for scene debugging.

• ACTIVITY 1 is still the active PS1 target, but the active bug surface has moved out of story routing and into the raft BMP load path during island prep.

• Exact narrowing chain:
  • bootScene != NULL survives immediately before storyPrepareSceneState(finalScene):
    • repo:/regtest-results/activity1-ads1-seed1-bootscene-nonnull-pre-prepare/result.json
    • fired
  • the same latch after storyPrepareSceneState(finalScene) did not fire:
    • repo:/regtest-results/activity1-ads1-seed1-bootscene-nonnull-post-prepare/result.json
    • did not fire
  • skipping adsInitIsland() made the later latch fire:
    • repo:/regtest-results/activity1-ads1-seed1-skip-adsinitisland-post-prepare/result.json
    • fired
  • so the first corrupting call is inside adsInitIsland()
• Then narrowed inside adsInitIsland() / islandInit():
  • returning after screen-load/layer setup:
    • repo:/regtest-results/activity1-ads1-seed1-island-cut-after-screenload/result.json
    • fired
  • returning after raft setup / before BACKGRND.BMP:
    • repo:/regtest-results/activity1-ads1-seed1-island-cut-before-backgrnd/result.json
    • did not fire
  • returning immediately after grLoadBmp(ttmSlot, 0, "MRAFT.BMP"):
    • repo:/regtest-results/activity1-ads1-seed1-island-cut-after-mraft-load/result.json
    • did not fire

• So the first bad edge is the raft BMP load itself.

• Then narrowed inside grLoadBmpRAM("MRAFT.BMP"):
  • forcing MRAFT.BMP off the PSB fast path did not help:
    • repo:/regtest-results/activity1-ads1-seed1-mraft-no-psb-cut-after-load/result.json
    • still bad
  • returning before any BMP-byte load did help:
    • repo:/regtest-results/activity1-ads1-seed1-mraft-cut-before-bmp-load/result.json
    • fired
  • returning immediately after ps1_loadBmpData() did not:
    • repo:/regtest-results/activity1-ads1-seed1-mraft-cut-after-bmp-load/result.json
    • still bad

• So the corrupting operation is in the raw BMP data load path, before any frame-install loop.

• Final split on the BMP data loader:
  • replacing MRAFT.BMP load with a same-sized dummy zeroed heap buffer:
    • repo:/regtest-results/activity1-ads1-seed1-mraft-dummy-buffer-post-load-cut/result.json
    • fired
  • replacing it with ps1_loadRawFile("\\BMP\\MRAFT.BMP;1", ...):
    • repo:/regtest-results/activity1-ads1-seed1-mraft-rawfile-post-load-cut/result.json
    • still bad
• Current best read:
  • the first bad operation for stable ACTIVITY 1 is an actual PS1 CD-read path for MRAFT.BMP
  • it is not:
    • story override retention
    • scene dispatch
    • adsInitIsland() generally
    • BACKGRND.BMP
    • PSB decoding specifically
    • frame-install into the sprite slot
    • assigning a heap buffer to bmpResource->uncompressedData
  • it is specifically triggered by real CD-backed MRAFT.BMP loading
• Next target:
  • inspect/fix the low-level PS1 CD-read path used by ps1_loadBmpData() / ps1_loadRawFile()
  • likely around CdRead buffer handling / alignment / transfer semantics rather than scene logic

2026-03-28 15:38 PDT

• Continued narrowing the ACTIVITY 1 failure after the raft-load boundary.

• The new question was whether the bad edge is specific to MRAFT.BMP or to any real CD-backed read at that point in scene prep.

• Additional splits:
  • forcing MRAFT.BMP off PSB and returning before any frame-install loop:
    • repo:/regtest-results/activity1-ads1-seed1-mraft-no-psb-preloop-cut/result.json
    • still bad
  • returning before any BMP-byte load at all:
    • repo:/regtest-results/activity1-ads1-seed1-mraft-cut-before-bmp-load/result.json
    • fired
  • returning immediately after ps1_loadBmpData():
    • repo:/regtest-results/activity1-ads1-seed1-mraft-cut-after-bmp-load/result.json
    • still bad

• So the first bad operation is definitely in the raw BMP data load path, before any frame metadata/surface install.

• Then split the load path itself:
  • substitute a same-sized dummy zeroed heap buffer instead of any real read:
    • repo:/regtest-results/activity1-ads1-seed1-mraft-dummy-buffer-post-load-cut/result.json
    • fired
  • substitute ps1_loadRawFile("\\BMP\\MRAFT.BMP;1", ...):
    • repo:/regtest-results/activity1-ads1-seed1-mraft-rawfile-post-load-cut/result.json
    • still bad
  • substitute ps1_loadRawFile("\\BMP\\BOAT.BMP;1", ...) for the raft load:
    • repo:/regtest-results/activity1-ads1-seed1-boat-rawfile-post-load-cut/result.json
    • still bad
• Current best read:
  • the active bug is no longer asset-specific to MRAFT.BMP
  • it is a generic real CD-read hazard at that exact scene-prep point
  • specifically:
    • any actual live PS1 CD-backed BMP read there corrupts later state
    • a same-sized heap allocation without CD I/O does not
  • so the next fix target is not scene logic or BMP parsing; it is the PS1 CD read path / DMA / buffer handling semantics used by ps1_loadBmpData() and ps1_loadRawFile()
• Next target:
  • test safer alternate CD read semantics around CdRead / CdReadSync, likely with a different buffering strategy or synchronization policy, then rerun ACTIVITY 1

2026-03-28 15:39 PDT

• Kept the same stable ACTIVITY 1 proof surface and focused only on the low-level read semantics.

• New discriminators:
  • substitute ps1_loadRawFile("\\BMP\\BOAT.BMP;1", ...) instead of the raft load:
    • repo:/regtest-results/activity1-ads1-seed1-boat-rawfile-post-load-cut/result.json
    • still bad
  • substitute a static-bounce-buffer reader that does real CdRead into static storage, then memcpy to heap:
    • repo:/regtest-results/activity1-ads1-seed1-boat-bounce-post-load-cut/result.json
    • still bad
• Current best read:
  • this is not MRAFT.BMP-specific
  • this is not a “DMA directly into malloc’d heap buffer” bug
  • the active failure is any real live CdRead at that scene-prep moment
  • so the next target is the PS1 CD state/synchronization path itself:
    • CdControl(CdlSetloc, ...)
    • CdRead(...)
    • CdReadSync(...)
    • possible interaction with current engine state / callbacks / timing
• Additional check:
  • inserting cdromResetState() immediately before the live special-case read:
    • repo:/regtest-results/activity1-ads1-seed1-boat-bounce-post-load-cut-cdreset/result.json
    • still bad
• Updated read:
  • this is not merely stale CD state left over from earlier boot/title work
  • the next target is the live CdRead/CdReadSync semantics themselves rather than reset ordering
• One more discriminator:
  • switching the special-case live read to the legacy ps1_fopen("BMP\\BOAT.BMP", "rb") / ps1_fread(...) whole-file path:
    • repo:/regtest-results/activity1-ads1-seed1-boat-ps1fopen-post-load-cut/result.json
    • still bad
• Current best read:
  • it is not a bug isolated to ps1_streamRead()
  • it is not a bug isolated to ps1_loadRawFile()
  • it is not a bug isolated to pack reads vs fallback reads
  • it is not a bug isolated to DMA directly into heap
  • it is any live CD-backed read path at that scene-prep moment
• Next target:
  • stop trying alternate live readers
  • shift to an architectural fix:
    • prefetch/cache needed BMP bytes before entering the sensitive scene-prep window, or
    • otherwise guarantee ACTIVITY 1 island prep does not issue live CD reads there

2026-03-28 16:08 PDT

• Tried the architectural fix in two steps:
  • added island-support BMP priming (MRAFT.BMP, BACKGRND.BMP, HOLIDAY.BMP) to adsPrimeRestorePilotResources() for any restore pilot that uses ISLETEMP.SCR
  • then moved priming earlier into storyPrepareSceneState() and prearmed the pilot pack before priming
• Validation runs:
  • repo:/regtest-results/activity1-ads1-seed1-prefetch-6300/20260328-155810/frames/jcreborn/frame_06150.png
  • repo:/regtest-results/activity1-ads1-seed1-prepprime-6300/20260328-160137/frames/jcreborn/frame_06150.png
  • repo:/regtest-results/activity1-ads1-seed1-prearm-prime-6300/20260328-160314/frames/jcreborn/frame_06150.png
• Result:
  • none of those three ACTIVITY 1 runs changed the late failure band
  • frames 6000, 6150, and 6300 stayed on the same wrong ocean output
  • so the naive “prime earlier” hypothesis is not sufficient by itself
• Follow-up probe:
  • added a temporary islandInit() residency trap around MRAFT.BMP
  • short proof run:
    • repo:/regtest-results/activity1-ads1-seed1-mraft-fatalproof/result.json
  • this did not trip the late fatal by 3000 frames
  • sampled visuals on that run were title/black rather than the old ocean proof surface
• Current best read:
  • the harness remains good enough for scene debugging
  • ACTIVITY 1 is still the active scene
  • the early-prime fix did not solve the issue
  • the next unresolved edge is no longer just “load MRAFT earlier”; it is the exact scene/boot context that exists when island prep is attempted
• Immediate next target:
  • replace the temporary islandInit() residency trap with a cleaner proof of the active ADS/tag/context at island-prep time
  • then determine whether the wrong-ocean path is entering island prep under the wrong scene identity, or whether the resource residency is still being lost before use

2026-03-28 16:18 PDT

• Replaced the failed overlay/decoder angle with a stronger runtime proof:
  • temporarily forced a distinctive ACTIVITY 1-only island state in storyPrepareSceneState():
    • night = 1
    • holiday = 3
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-nightproof-6300/20260328-161502/frames/jcreborn/frame_06150.png
• Important result:
  • the old wrong bright-cyan day ocean at 6000/6150/6300 changed into a night-ocean variant
  • so the visible bad path is definitely carrying the prepared ACTIVITY 1 island state forward
  • this rules out the hypothesis that the wrong-ocean branch is some unrelated post-title scene path ignoring storyPrepareSceneState(finalScene)
• Current best read:
  • ACTIVITY 1 background/island state prep is being applied
  • but the actual scene content / sprite-thread side is still not launching or composing correctly
  • so the remaining bug is now narrower again:
    • not story boot routing
    • not final-scene selection
    • not island-state preparation
    • still in the transition from prepared scene state into live ADS/TTM scene content
• Cleanup:
  • reverted the temporary night/holiday proof patch after recording the result
• Next target:
  • return to the clean ACTIVITY 1 path and debug why prepared ACTIVITY background state survives while the ACTIVITY scene threads/content still collapse into empty ocean

2026-03-28 16:21 PDT

• Removed the remaining intrusive ACTIVITY-specific fatal traps from ads.c so the runtime proof surface is passive again:
  • zero-IP launch abort
  • trigger abort
  • startup-thread alive/terminated aborts
  • slot-2 zero-IP handoff aborts
• Clean validation run:
  • repo:/regtest-results/activity1-ads1-seed1-cleantelemetry-6300/20260328-161912/frames/jcreborn/frame_06150.png
• Result:
  • removing those ACTIVITY-specific aborts did not change the visible scene behavior
  • frame 6150 is back to the same bright day-ocean failure shape as before
  • so the remaining bug is not an artifact of the old ACT1 fatal instrumentation
• Current best read:
  • harness is still at practical full confidence
  • the prepared-scene state can be proven to survive
  • the cleaned runtime still collapses to empty ocean instead of real ACTIVITY scene content
  • next target remains the live ADS/TTM content path rather than story boot or island-state prep

2026-03-28 16:30 PDT

• Added two temporary late proofs for the clean ACTIVITY 1 path:
  • in story.c, after storyPlayPreparedScene(finalScene, ...), fatal if ACTIVITY.ADS 1 returns with ps1AdsLastPlayLaunched == 0
  • in ads.c, inside the adsPlay() main loop, fatal if ACTIVITY.ADS 1 is still running past frame 5400 with ps1AdsLastPlayLaunched == 0
• Validation runs:
  • repo:/regtest-results/activity1-ads1-seed1-launchproof-6300/result.json
  • repo:/regtest-results/activity1-ads1-seed1-adsloop-launchtrap/result.json
• Result:
  • neither proof fired
  • both runs still landed on the same stable late-ocean failure band:
    • frame_05400 through frame_06300
  • scene_markers_last.launched remained false in both runs
• Important narrowing:
  • the visible bad path is not simply:
    • storyPlayPreparedScene() returning immediately with no launch, or
    • adsPlay() staying live into the ocean band with no launch
  • so the remaining false-launched state is being reached through a different path than those two proof sites capture
• Cleanup:
  • reverted both temporary proof guards after recording the negative result
• Next target:
  • move the proof surface away from those two sites and identify where the late ocean path is actually re-entering/retrying scene control while leaving ps1AdsLastPlayLaunched false

2026-03-28 16:35 PDT

• Tested the most obvious remaining re-entry hypothesis directly in storyPlay():
  • temporary proof patch on the if (!ps1AdsLastPlayLaunched) retry branch
  • for ACTIVITY.ADS 1, force a visible island-state mutation there:
    • night = 1
    • holiday = 3
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-retrybranch-nightproof/result.json
• Result:
  • the late 5400–6300 ocean frames did not change at all
  • same day-ocean output
  • same state_hash
  • same false launched marker
• Important narrowing:
  • the stable late-ocean band is not coming from the obvious storyPlay() failed-launch retry branch either
  • combined with the earlier negative proofs, the bad path is bypassing:
    • the post-storyPlayPreparedScene() failed-launch branch
    • the late adsPlay() in-loop no-launch proof
    • the obvious storyPlay() failed-launch retry branch side effect
• Cleanup:
  • reverted the temporary retry-branch proof patch after recording the result
• Next target:
  • move one layer outside of storyPlay() control-flow assumptions and identify what code path is drawing the late ocean band while all three expected no-launch branches fail to explain it

2026-03-28 16:40 PDT

• Tested whether the late ACTIVITY ocean band was being sustained by the persistent island background thread itself:
  • temporary proof patch in storyPrepareSceneState()
  • for ACTIVITY.ADS 1, call adsReleaseIsland() immediately after adsInitIsland()
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-noislandbg-proof/result.json
• Result:
  • no change at all
  • same late ocean frames
  • same state_hash
  • same false launched marker
• Important narrowing:
  • the late bad band is not being sustained by the background/wave thread
  • it is a static ocean background already baked into grBackgroundSfc during island prep
  • the real missing piece is still the ACTIVITY scene content layer, not the island background thread lifetime
• Cleanup:
  • reverted the temporary adsReleaseIsland() proof patch after recording the result
• Next target:
  • focus directly on why ACTIVITY scene content never composites over that already-prepared ocean background

2026-03-28 16:45 PDT

• Proved the late ACTIVITY ocean band is not receiving live sprite draws at all:
  • temporary fatal traps added to:
    • grDrawSprite()
    • grDrawSpriteFlip()
  • only for ACTIVITY.ADS 1 after frame 5400
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-latedraw-trap/result.json
• Result:
  • neither draw trap fired
  • the run still reached the same stable late-ocean band unchanged
  • so by 5400–6300, no ACTIVITY scene sprite draw is reaching the renderer at all
• Important narrowing:
  • the missing ACTIVITY content layer is failing before grDrawSprite() / grDrawSpriteFlip()
  • the ocean band is just the prepared static background with no live content ops arriving in the late window
• Cleanup:
  • reverted the temporary late draw traps after recording the result
• Next target:
  • move one layer earlier than rendering:
    • determine why ttmPlay() for the supposed ACTIVITY content is no longer issuing DRAW_SPRITE opcodes by the late window

2026-03-28 16:50 PDT

• Moved one layer earlier than rendering and proved no ACTIVITY opcode execution reaches the late window either:
  • temporary fatal trap at the entry of ttmPlay()
  • only for ACTIVITY.ADS 1 after frame 5400
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-latettmp-trap/result.json
• Result:
  • the ttmPlay() trap did not fire
  • the run still reached the same stable late-ocean band unchanged
• Important narrowing:
  • by 5400–6300, no ACTIVITY thread is even reaching opcode execution anymore
  • combined with the earlier late draw proof, the ACTIVITY content layer is dead before:
    • ttmPlay()
    • grDrawSprite()
    • grDrawSpriteFlip()
• Cleanup:
  • reverted the temporary ttmPlay() trap after recording the result
• Next target:
  • move earlier again to the thread lifecycle itself:
    • why the ACTIVITY scene threads have vanished before the late window while the prepared static ocean background remains on screen

2026-03-28 16:59 PDT

• Added a sticky ps1StoryDbgBootReturnSeen proof bit for the if (bootScene != NULL) { ... return; } success-return branch in storyPlay().
• First attempted to expose that bit in the top-left drop panel, but that surface was contaminated by unrelated lit pixels earlier in the run and was not trustworthy.

• Moved the same proof bit into the compact scene-identity strip and decoded it directly on the late ACTIVITY frame.

• Validation runs:
  • repo:/regtest-results/activity1-ads1-seed1-bootreturn-proof/result.json
  • repo:/regtest-results/activity1-ads1-seed1-bootreturn-compactproof/result.json
• Clean result:
  • at frame_06150, boot_return_seen_estimate = 0
  • so the late ocean band is not post-return residue from the bootScene != NULL success path
• Important narrowing:
  • the stable late bad band is still being reached before the boot-scene success-return branch
  • that rules out one of the last obvious “scene already ended and left its background behind” explanations

2026-03-28 17:02 PDT

• Added sticky ACTIVITY attempt counters:
  • ps1StoryDbgActivityPrepareCount
  • ps1StoryDbgActivityPlayPreparedCount

• The compact-strip decode for those counters was too noisy to trust numerically, so I switched back to a behavioral proof.

• Behavioral proof:
  • only on the second storyPrepareSceneState(ACTIVITY.ADS, 1) call, forced islandState.night = 1 and holiday = 3
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-second-prepare-nightproof/result.json
• Result:
  • the late 5400–6300 ocean stayed the same bright day ocean
  • no night mutation appeared
• Important narrowing:
  • the stable bad path is not repeatedly re-preparing ACTIVITY 1 before the late window
  • current best read is now:
    • a single ACTIVITY scene-prep/background-prep pass survives
    • live ACTIVITY content still dies before late ttmPlay() and late draw
    • and the engine has not yet taken the normal boot-scene success-return path by the late sampled window
• Cleanup:
  • reverted the temporary second-prepare nightproof after recording the result
• Next target:
  • prove whether storyPlayPreparedScene(finalScene, ...) is being entered on the stable ACTIVITY path in the current clean runtime, using a similarly late-safe behavioral proof rather than a noisy counter decode

2026-03-28 17:06 PDT

• Tried a simpler ACTIVITY entry proof by exposing sticky booleans for:
  • storyPrepareSceneState(ACTIVITY.ADS, 1) seen
  • storyPlayPreparedScene(ACTIVITY.ADS, 1) seen

• The compact-strip decode for those added rows still overlapped other overlay content and was not reliable enough to trust numerically.

• Switched back to the behavior surface that already proved reliable:
  • temporary mutation at the top of storyPlayPreparedScene(ACTIVITY.ADS, 1):
    • force night/holiday
    • rebuild island via adsReleaseIsland(); adsInitIsland();
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-playprepared-nightproof/result.json
• Result:
  • late 5400–6300 output stayed the same bright day ocean
  • no night mutation appeared
• Important narrowing:
  • on the stable clean ACTIVITY failure path, the renderer-visible late ocean is not coming through storyPlayPreparedScene(finalScene, ...)
  • combined with the earlier proofs:
    • it is not a repeated second prepare
    • it is not the boot-scene success-return residue
    • it is not late ttmPlay() / late draw activity
• Current best read:
  • the bad ACTIVITY path is diverging before the normal prepared-scene playback function
  • but after enough ACTIVITY-specific scene preparation/background work has already happened to leave the static ocean in place
• Cleanup:
  • reverted the temporary storyPlayPreparedScene() nightproof after recording the result
• Next target:
  • identify the pre-storyPlayPreparedScene() path that can leave ACTIVITY-prepared ocean background on screen while never entering the normal prepared-scene playback path

2026-03-28 17:09 PDT

• Tested whether the stable bad ACTIVITY path is still using the resolved bootScene != NULL / finalScene preparation path at all.
• Temporary behavioral proof:
  • immediately after storyPrepareSceneState(finalScene), only when:
    • bootScene != NULL
    • finalScene == ACTIVITY.ADS tag 1
    • finalScene is an island scene
  • force night/holiday
  • rebuild island via adsReleaseIsland(); adsInitIsland();
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-bootscene-nightproof/result.json
• Result:
  • late 5400–6300 output stayed the same bright day ocean
  • no night mutation appeared
• Important narrowing:
  • the stable bad ACTIVITY path is not the normal resolved bootScene/finalScene preparation path either
  • combined with earlier proofs, the visible late ocean is now outside all of these expected sites:
    • boot-scene success return
    • repeated second prepare
    • normal storyPlayPreparedScene(finalScene, ...)
    • normal resolved bootScene/finalScene island-prep mutation point
• Cleanup:
  • reverted the temporary bootScene/finalScene nightproof after recording the result
• Current best read:
  • the late ACTIVITY bad band is being reached through an earlier or parallel path that still leaves an ACTIVITY-like prepared ocean background in place, but bypasses the normal boot-scene/final-scene playback and return surfaces we have tested
• Next target:
  • step out of story.c proofs and instrument who is writing the late ocean background surface (grBackgroundSfc) in the ACTIVITY failure path, since the control-flow proofs in the normal scene path are now mostly exhausted

2026-03-28 17:15 PDT

• Switched proof surface from story.c control flow to the actual background writer in island.c.
• Added a helper in story.c / repo:/story.h:
  • storyBootOverrideMatches(const char *adsName, uint16 adsTag)
• First writer proof:
  • only under boot override ACTIVITY.ADS 1, force islandState.night = 1, holiday = 3 at the top of islandInit()
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-islandinit-nightproof/result.json
• Result:
  • the late bad band changed completely
  • state hash changed from the old stable ocean hash
• Important conclusion:
  • the late ACTIVITY failure surface is definitely being produced through islandInit()
  • this is not just stale framebuffer residue or a path entirely outside island background setup

2026-03-28 17:17 PDT

• Narrowed islandInit() one more step:
  • for boot override ACTIVITY.ADS 1, return immediately after the initial grLoadScreen(...)
  • skip all later raft/cloud/island compositing in islandInit()
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-islandinit-loadonly-proof/result.json
• Result:
  • the late 5400–6300 bad band stayed exactly the same as the original stable failure:
    • same state hash
    • same bright day-ocean frames
• Important conclusion:
  • the later raft/cloud/island compositing in islandInit() is not required for the stable ACTIVITY failure
  • the initial grLoadScreen("OCEAN0?.SCR") done by islandInit() is sufficient by itself to produce the late bad surface
• Cleanup:
  • reverted the temporary early return after grLoadScreen(...)
• Current best read:
  • the stable late ACTIVITY failure is now tightly narrowed to the ocean screen load path itself
  • the wrong surface is being baked in at grLoadScreen(...), before later island composition or normal scene playback ever matters
• Next target:
  • instrument why islandInit() is reaching the OCEAN0?.SCR load on the ACTIVITY failure path, and whether the intended ACTIVITY-specific screen/background choice is ever being selected before that fallback ocean load happens

2026-03-28 17:20 PDT

• Added a direct ACTIVITY ADS-entry proof in adsPlay():
  • while testing, if adsPlay("ACTIVITY.ADS", 1) is entered, force night/holiday
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-adsplay-nightproof/result.json
• Result:
  • the late 5400–6300 bad band did not change at all
• Important conclusion:
  • the stable late ACTIVITY failure is not coming through adsPlay("ACTIVITY.ADS", 1) entry itself

2026-03-28 17:22 PDT

• Then tested a broader story-level hypothesis:
  • while boot override ACTIVITY.ADS 1 is still pending,
  • mutate any island storyPrepareSceneState(scene) call to night/holiday
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-any-prepare-nightproof/result.json
• Result:
  • the late bad band changed completely
• Important conclusion:
  • the stable late failure is still reaching some island-scene preparation while the ACTIVITY override remains pending
  • but it is not necessarily the ACTIVITY scene itself

2026-03-28 17:23 PDT

• Narrowed that branch again:
  • mutate only when:
    • bootScene == NULL
    • storyBootOverrideMatches("ACTIVITY.ADS", 1)
    • finalScene->flags & ISLAND
  • before storyPrepareSceneState(finalScene)
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-bootscene-null-nightproof/result.json
• Result:
  • the late bad band did not change
• Important read:
  • the stable path is not explained by the simple bootScene == NULL random-final-scene branch alone
  • but it also is not entering adsPlay("ACTIVITY.ADS", 1) directly
  • and story ads ... is confirmed to still route through storyPlay(), not storyPlayBootSceneDirect()
• Current best read:
  • the remaining control-flow suspect is now the early PS1 title/boot gating in jc_reborn.c, especially:
    • ps1HasBootOverridePending()
    • override reload/application timing around title startup
• Next target:
  • test whether allowing story ads to count as a pending boot override changes the ACTIVITY failure shape, since that is now the cleanest unresolved gating edge

2026-03-28 17:29 PDT

• Tested the early PS1 title/boot gating hypothesis directly in repo:/jc_reborn.c:
  • changed ps1HasBootOverridePending() so story ... overrides count as pending too
  • this suppresses the early title preload gate for story ads ACTIVITY.ADS 1
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-pendinggate-proof/result.json
• Result:
  • this does change the early shape materially:
    • earlier frames that used to show title now go black sooner
    • the late ocean starts earlier (04950 instead of 05400)
  • but the stable late bad band is still the same ocean hash:
    • 59cd749f...
  • and host compare is still a hard mismatch:
    • /tmp/activity1-pendinggate-vs-host.json
    • verdict still PIXEL_MISMATCH
• Comparison to old clean baseline:
  • /tmp/activity1-old-vs-host.json
  • host mismatch is unchanged in substance
• Important conclusion:
  • the title/boot gate is a real factor in startup shape
  • but it is not the root fix for ACTIVITY 1
  • the remaining bug still lies later, in how the pending ACTIVITY override interacts with subsequent scene preparation / scene selection after startup
• Current best read:
  • story ads should probably count as a pending boot override for control-flow correctness
  • but even with that fix, the ACTIVITY path still falls into the same wrong late ocean state
• Next target:
  • keep the pending-gate result in mind, but continue tracing the later handoff between startup and island preparation, because that is still where ACTIVITY correctness is lost

2026-03-28 17:36 PDT

• Switched from branch proofs back to family proofs inside storyPrepareSceneState(scene) while the pending override is still ACTIVITY.ADS 1.
• First tested WALKSTUF.ADS only:
  • repo:/regtest-results/activity1-ads1-seed1-walkstuf-prepare-nightproof/result.json
• Then tested FISHING.ADS only:
  • repo:/regtest-results/activity1-ads1-seed1-fishing-prepare-nightproof/result.json
• Result:
  • neither changed the stable late ocean band
  • both preserved the same ocean hash 59cd749f...
• Important conclusion:
  • the earlier “any island prepare while ACTIVITY override is pending” proof is not explained by either:
    • WALKSTUF.ADS island prep
    • FISHING.ADS island prep
• Current best read:
  • either another island family is being prepared under the still-pending ACTIVITY override
  • or the broader “any prepare” proof is interacting with shared state in a way that is not family-local
• Cleanup:
  • reverted the temporary family-specific proof patch after recording both results
• Next target:
  • move away from heuristic family guesses and identify the exact prepared scene family/tag through a more deterministic state surface, rather than guessing by visual classifier labels

2026-03-28 17:44 PDT

• Added exact prepared-scene debug fields in repo:/story.c:
  • ps1StoryDbgPreparedSceneAdsSig
  • ps1StoryDbgPreparedSceneTag

• First tried exposing them in the legacy story counter-bar panel in repo:/graphics_ps1.c and decoding them via repo:/scripts/decode-ps1-bars.py.

• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-preparedtrace/result.json
• Result:
  • the legacy story panel rows saturated to full width (90) on the late frames
  • so that panel is not a trustworthy decode surface for exact prepared-scene identity
• Follow-up:
  • moved the same prepared-scene fields into the compact white-bit scene-marker strip in repo:/graphics_ps1.c
  • extended repo:/scripts/decode-ps1-bars.py to decode:
    • prepared_scene_ads_family_estimate
    • prepared_scene_tag_estimate
• Validation rerun:
  • repo:/regtest-results/activity1-ads1-seed1-preparedstrip/result.json
• Late-frame decode on the compact strip:
  • frame_06000: prepared=0/0, requested=63/0, boot_pending=1
  • frame_06150: prepared=0/0, requested=63/0, boot_pending=1
  • frame_06300: prepared=0/0, requested=63/0, boot_pending=1
• Important conclusion:
  • the new prepared-scene field is consistent with “no prepared scene identity survives into the late ocean band”
  • but the adjacent requested-family bits are still saturating (63) on the same compact surface
  • so the compact strip is not yet clean enough to treat the exact family/tag values as final truth
• Current best read:
  • the ACTIVITY failure still looks like “prepared/background state without surviving scene playback”
  • and the next barrier is now the proof surface itself: we need one exact scene-identity signal that is robust under late-frame scaling/filtering, not another branch guess
• Next target:
  • switch from compact multi-bit family/tag encoding to a simpler, one-hot or low-cardinality exact prepared-scene proof surface that cannot saturate into ambiguous 63 values under DuckStation scaling

2026-03-28 17:51 PDT

• Replaced the ambiguous compact prepared-scene family/tag decode with one-hot prepared-family rows in the robust scene-marker strip:
  • prepared_activity1
  • prepared_activity
  • prepared_building
  • prepared_fishing
  • prepared_johnny
  • prepared_mary
  • prepared_miscgag
  • prepared_stand
  • prepared_suzy
  • prepared_visitor
  • prepared_walkstuf
• Validation rerun:
  • repo:/regtest-results/activity1-ads1-seed1-preparedfamily/result.json
• Late-frame decode:
  • frame_06000: all prepared-family one-hots 0, boot_pending=1
  • frame_06150: all prepared-family one-hots 0, boot_pending=1
  • frame_06300: all prepared-family one-hots 0, boot_pending=1
• Whole sampled run scan:
  • the one-hot family rows only light during the early noisy startup frames (00300, 00450, 00600), where they all saturate simultaneously and are not trustworthy
  • after that, no prepared-family row lights again
  • boot_pending remains asserted from 04950 through 06300
• Important conclusion:
  • on the stable ACTIVITY failure path, there is no trustworthy evidence that storyPrepareSceneState() reaches any concrete island family during the late bad window
  • the bug target moves earlier again:
    • the override remains pending
    • but stable scene preparation is not being reached on the path that leads to the late ocean band
• Current best read:
  • the late ocean band is still real and stable
  • but it is no longer defensible to describe it as “late prepared scene X”
  • instead, the stronger statement is:
    • boot_pending survives
    • normal prepared-scene identity does not
• Next target:
  • stop trying to identify a late prepared family
  • instrument the handoff that should consume the pending override and enter storyPrepareSceneState() on the stable path, because that handoff is now the narrowest unexplained edge

2026-03-28 17:57 PDT

• Added sticky handoff markers for the ACTIVITY.ADS 1 pending-override path in repo:/story.c:
  • pending_boot_resolved
  • pending_prepare
  • pending_play_prepared
  • pending_play_prepared_returned

• Exposed those as robust white-block rows in repo:/graphics_ps1.c and decoded them in repo:/scripts/decode-ps1-bars.py.

• Validation rerun:
  • repo:/regtest-results/activity1-ads1-seed1-pendinghandoff/result.json
• Late-frame decode:
  • frame_06000: all handoff markers 0, boot_pending=1
  • frame_06150: all handoff markers 0, boot_pending=1
  • frame_06300: all handoff markers 0, boot_pending=1
• Whole sampled run scan:
  • all four sticky handoff markers light only during the early noisy startup frames (00300, 00450, 00600)
  • after that, none of them light again
  • boot_pending remains asserted from 04950 through 06300
• Important conclusion:
  • on the stable ACTIVITY failure path, there is still no trustworthy evidence that the pending override reaches:
    • resolved boot-scene handoff
    • stable prepare entry
    • stable play-prepared entry
    • stable play-prepared return
  • the only late surviving signal is still the pending override itself
• Current best read:
  • the stable failure path is earlier than the normal scene handoff/control-flow surfaces we have been instrumenting
  • the early startup/title window is still polluting these markers, but the late window is now consistent:
    • pending override survives
    • no later stable handoff marker survives with it
• Next target:
  • stop relying on markers that can be polluted by the early startup samples
  • instrument a later-safe state transition that only becomes writable after intro/title flow is complete, so we can distinguish “never consumed” from “consumed then reset”

2026-03-28 18:01 PDT

• Added a late-safe gate to the sticky pending-handoff markers in repo:/story.c:
  • the ACTIVITY handoff latches now only set after grGetCurrentFrame() >= 1000
• Validation rerun:
  • repo:/regtest-results/activity1-ads1-seed1-pendinghandoff-late/result.json
• Result:
  • the sampled late frames still show only:
    • boot_pending=1
  • all of these remain 0 at 04950 through 06300:
    • pending_boot_resolved
    • pending_prepare
    • pending_play_prepared
    • pending_play_prepared_returned
• Important conclusion:
  • gating those markers behind a later frame threshold did not change the core read
  • the stable ACTIVITY failure path still preserves only the pending override
  • it does not preserve any trustworthy evidence of the later normal handoff surfaces
• Current best read:
  • the unexplained edge is now even narrower:
    • the override remains pending after startup
    • but the code path that should consume it into normal scene handoff still leaves no late stable trace
• Next target:
  • move one layer lower than the current story markers and find a later-safe “override consumed” state that cannot be confused with startup/title replay

2026-03-28 18:06 PDT

• Split the late pending-override source further in repo:/story.c:
  • late_boot_ads_exact
  • late_boot_lookup_null
  • late_boot_lookup_found

• Exposed those as late sticky rows in repo:/graphics_ps1.c and decoded them in repo:/scripts/decode-ps1-bars.py.

• Validation rerun:
  • repo:/regtest-results/activity1-ads1-seed1-latebootsource/result.json
• Result:
  • after startup, from 04950 through 06300, the only surviving late signal is still:
    • boot_pending=1
  • all of these remain 0 in the late window:
    • late_boot_ads_exact
    • late_boot_lookup_null
    • late_boot_lookup_found
    • pending_boot_resolved
• Important conclusion:
  • the new split markers still only light in the polluted early startup samples and do not survive into the late ACTIVITY failure path
  • so they do not change the late-path read:
    • stable late evidence still shows only an unresolved pending override
• Current best read:
  • the late ocean band is downstream of “override still pending”
  • but upstream of every stable story-level resolution/prepare/play marker we have made durable so far
• Next target:
  • stop extending the same story overlay family of markers
  • move to a different proof surface entirely for the next cut, because the current late-safe story markers are no longer adding new separation

2026-03-28 18:11 PDT

• Switched from passive markers to a behavioral proof in repo:/story.c:
  • if the exact ACTIVITY.ADS 1 override was still pending after frame 1000, clear it immediately via storyClearBootSceneOverrideOnly()
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-lateclear/result.json
• Result:
  • the stable late output did not change at all
  • the late frame hash is byte-identical to the previous late-handoff run:
    • old frame_06150: 59cd749fc0952552db0f9748ec7421df288292773be8ee82f008bfb3f2fbf6fc
    • new frame_06150: 59cd749fc0952552db0f9748ec7421df288292773be8ee82f008bfb3f2fbf6fc
• Important conclusion:
  • the lingering ACTIVITY boot override is not the active cause of the late ocean band
  • it is residue
  • the real failure has already happened earlier by the time the late window is reached
• Cleanup:
  • reverted the temporary late-clear proof patch after validating the identical output
• Current best read:
  • the active bug is now clearly upstream of the surviving boot_pending residue
  • continuing to chase the late pending-override state itself will not produce the fix
• Next target:
  • shift the proof surface from late residual story state to the earlier point where the ACTIVITY path first diverges into the wrong ocean outcome

2026-03-28 18:15 PDT

• Ran a finer-grained ACTIVITY boundary scan with 30-frame sampling:
  • repo:/regtest-results/activity1-ads1-seed1-boundary5100/result.json
• Result:
  • on the current build, the stable wrong-ocean hash first appears at:
    • frame_04920
  • before that, the run is still changing through several distinct earlier states
• Important conclusion:
  • the useful instrumentation window is now much tighter
  • there is no need to keep probing the broad 5000+ late band
• Current best read:
  • the ACTIVITY failure becomes stable at 04920
  • so the next debug cut should target the transition band immediately before that:
    • roughly 04800–04920
• Next target:
  • instrument the first bad transition window directly around 04920, rather than chasing residual state after the failure has already stabilized

2026-03-28 18:28 PDT

• Tightened the first stable failure onset again with a 10-frame boundary scan:
  • repo:/regtest-results/activity1-ads1-seed1-boundary5000i10/result.json
• Result:
  • first stable bad frame is now pinned to:
    • frame_04910
  • last frame before it:
    • frame_04900
• Useful observation:
  • frame_04900 -> frame_04910 is the real settled flip
  • frame_04910 -> frame_04920 is byte-identical
  • so 04910 is the first stable wrong-ocean frame, not just part of a slow drift
• Behavioral proof:
  • temporarily bypassed adsPlayIntro() in repo:/story.c only for exact ACTIVITY.ADS 1
  • validation run:
    • repo:/regtest-results/activity1-ads1-seed1-nointro/result.json
• Result:
  • the stable late bad ocean disappears entirely
  • replaced by a stable black-screen path
  • final state hash changes from the ocean hash to:
    • df57118101f4e25e7e8a74ed77aaadb00f9ed9ea28e1cff7236c070d1ffaed5e
  • visual detect at frame_04910 and frame_05000:
    • black / no island / no content
• Important conclusion:
  • the settled bad ocean is directly sourced by the normal adsPlayIntro() boot path
  • bypassing intro does not fix ACTIVITY, but it proves the late ocean surface is not some unrelated later fallback
  • it comes from the intro/ocean boot sequence that the story path normally uses before ACTIVITY should take over
• Cleanup:
  • reverted the temporary adsPlayIntro() bypass after validating the black-screen replacement path
• Current best read:
  • the active bug is now strongly centered on the handoff from intro/ocean boot into the ACTIVITY scene path
  • not on the residual late pending override
• Next target:
  • instrument the intro-to-scene handoff itself, because that is now the most plausible place where ACTIVITY takeover fails and leaves the boot ocean in place

18:32 PDT - Post-intro scrub proof changes failure to stable title, not black or ocean

• Temporary proof:
  • left normal adsPlayIntro() in repo:/story.c
  • then immediately called adsNoIsland() only for exact ACTIVITY.ADS 1
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-postintroscrub/result.json
• Result:
  • run exits cleanly with:
    • state_hash = d9ee0d2e8f8465ea471c9c79223f1177c7225a238274f7f68ab32ed94312c0a0
  • sampled late frames remain on the title surface, not ocean:
    • frame_04770: title
    • frame_04910: title
    • frame_05000: title
• Important comparison:
  • normal path:
    • stable bad ocean by 04910
  • no-intro proof:
    • stable black-screen path
  • post-intro scrub proof:
    • stable title path
• Important conclusion:
  • the bad ocean is not explained only by adsPlayIntro() being called
  • it depends on intro-side island state surviving after intro returns
  • clearing island state immediately after intro prevents the bad ocean and instead leaves the run stranded on title
  • so the ACTIVITY failure is now most strongly centered on the handoff immediately after intro returns and before ACTIVITY content successfully takes over
• Cleanup:
  • reverted the temporary post-intro adsNoIsland() proof patch after validation
• Next target:
  • instrument the immediate post-intro handoff, because that is now the narrowest boundary separating:
    • stable title
    • stable wrong ocean
    • black-screen no-intro failure

18:34 PDT - Replacing first exact ACTIVITY prepare with adsNoIsland() yields black, not ocean

• Temporary proof:
  • in repo:/story.c, replaced the first exact:
    • bootScene != NULL
    • finalScene == ACTIVITY.ADS 1
    • storyPrepareSceneState(finalScene)
  • with:
    • adsNoIsland()
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-prepare-noisland/result.json
• Result:
  • run exits cleanly with:
    • state_hash = 0f9a705ed4b557e621649636842b051f9311c39535f4fd6159c7b3243c98a54a
  • sampled late frames are black, not ocean:
    • frame_04770: black
    • frame_04910: black
    • frame_05000: black
• Important comparison:
  • normal path:
    • stable bad ocean by 04910
  • no-intro proof:
    • stable black-screen path
  • post-intro scrub proof:
    • stable title path
  • exact-prepare adsNoIsland() proof:
    • stable black-screen path
• Important conclusion:
  • the settled bad ocean is being established by the exact first ACTIVITY.ADS 1 prepare path, not merely carried forward from intro
  • intro alone is not enough to explain the stable ocean:
    • keeping intro but scrubbing immediately after it gives title
    • keeping intro but replacing the exact ACTIVITY prepare with adsNoIsland() gives black
  • so the active failure boundary is now centered tightly on what storyPrepareSceneState(finalScene) does for exact ACTIVITY.ADS 1
• Cleanup:
  • reverted the temporary exact-prepare adsNoIsland() proof patch after validation
• Next target:
  • inspect the exact ACTIVITY.ADS 1 prepare path itself:
    • storyCalculateIslandFromScene(finalScene)
    • adsPrimeSceneResources(...)
    • adsInitIsland()
  • because that path now has the strongest causal link to the stable wrong-ocean state

18:40 PDT - Skipping adsPrimeSceneResources() does not change the stable ocean failure

• Temporary proof:
  • in repo:/story.c, skipped:
    • adsPrimeSceneResources(scene->adsName, scene->adsTagNo)
  • only for exact ACTIVITY.ADS 1
  • left:
    • storyCalculateIslandFromScene(scene)
    • adsInitIsland()
    • normal intro flow
    • normal later playback path
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-skip-prime/result.json
• Result:
  • run exits cleanly with:
    • state_hash = fe8a54dc926a6b88be9364720305f44a71ea7d5f511a15ab3c3462defac3996b
  • sampled late frames are still stable ocean:
    • frame_04770: ocean
    • frame_04910: ocean
    • frame_05000: ocean
• Important conclusion:
  • adsPrimeSceneResources() is not the primary cause of the settled wrong-ocean state
  • removing it does not collapse the run to black and does not prevent the ocean failure
  • so the strongest remaining prepare-path suspects are now:
    • storyCalculateIslandFromScene(finalScene)
    • adsInitIsland()
    • specifically islandInit() and the initial grLoadScreen("OCEAN0?.SCR") path it performs
• Cleanup:
  • reverted the temporary skip-prime proof patch after validation
• Next target:
  • split the remaining exact prepare surface between:
    • island-state calculation
    • and adsInitIsland() / islandInit()

18:45 PDT - Skipping exact scene island-state calculation perturbs the lead-in, but ocean still settles by 04910

• Temporary proof:
  • in repo:/story.c, skipped:
    • storyCalculateIslandFromScene(scene)
  • only for exact ACTIVITY.ADS 1
  • left:
    • adsPrimeSceneResources(...)
    • adsInitIsland()
    • normal intro flow
    • normal later playback path
• Validation run:
  • repo:/regtest-results/activity1-ads1-seed1-skip-scene-islandcalc/result.json
• Result:
  • run exits cleanly with:
    • state_hash = 81b56aa4b51befe5badf1bdfff881504bc469fc5a829e1924a706c359620cf03
  • sampled frames:
    • frame_04770: black
    • frame_04910: ocean
    • frame_05000: ocean
• Important conclusion:
  • scene-specific island-state calculation does affect the lead-in before the settled failure
  • but it does not prevent the stable wrong-ocean state from being re-established by 04910
  • so it is not sufficient to explain the persistent ACTIVITY failure on its own
  • the strongest remaining causal surface is still:
    • adsInitIsland()
    • especially islandInit() and its initial background load/composition path
• Cleanup:
  • reverted the temporary skip-scene-islandcalc proof patch after validation
• Next target:
  • isolate adsInitIsland() / islandInit() more directly, because that is now the tightest surviving source of the settled wrong-ocean outcome

02:16 PDT - Keeping the first small pack-header buffer alive did not move ACTIVITY 1

• Temporary proof:
  • in repo:/cdrom_ps1.c, changed repo:/cdrom_ps1.c so the first small PS1_PACK_HEADER_SIZE allocation stayed alive until the function returned
  • specifically:
    • kept the first ps1_streamReadFromCdFile(&cdfile, 0, PS1_PACK_HEADER_SIZE) buffer allocated
    • delayed its free(...) until after the later full header read / entry decode completed
  • goal:
    • test whether immediate reuse of that first tiny heap block was the layout-sensitive seam
• Validation run:
  • repo:/regtest-results/activity1-packindex-keep-small-header
• Result:
  • run exited cleanly with the exact old settled-ocean hash:
    • state_hash = 59cd749fc0952552db0f9748ec7421df288292773be8ee82f008bfb3f2fbf6fc
• Important conclusion:
  • keeping the first small header allocation alive is not sufficient to move the bug
  • so the layout/lifetime sensitivity around repo:/cdrom_ps1.c is still real, but it is not explained by simple reuse of that first 20-byte header block alone
  • the stronger remaining suspects stay local to:
    • stack adjacency / local object layout
    • CdlFILE lifetime or overwrite
    • interaction between the two ps1_streamReadFromCdFile(...) calls beyond just freeing the first tiny buffer
• Cleanup:
  • reverted the temporary headerDataSmall lifetime probe in repo:/cdrom_ps1.c
• Next target:
  • inspect local-object lifetime and overwrite risk around:
    • cdfile
    • headerData
    • entries
    • the transition between the first and second ps1_streamReadFromCdFile(...) calls

02:18 PDT - Copying CdlFILE immediately after CdSearchFile moved ACTIVITY 1 to the third branch

• Temporary proof:
  • in repo:/cdrom_ps1.c, changed repo:/cdrom_ps1.c so that:
    • stableCdfile = cdfile;
    • both ps1_streamReadFromCdFile(...) calls used stableCdfile
    • outPack->cdfile also stored stableCdfile
  • no search logic changed
  • goal:
    • test whether copying CdlFILE immediately after CdSearchFile(...) is enough to perturb the layout-sensitive failure
• Validation run:
  • repo:/regtest-results/activity1-packindex-stable-cdfile
• Result:
  • run exited cleanly with the third stable branch:
    • state_hash = 81b56aa4b51befe5badf1bdfff881504bc469fc5a829e1924a706c359620cf03
  • late markers:
    • bmp_ok = true
    • bmp_fail = true
    • sprite_count_estimate = 0
• Important conclusion:
  • this is a strong confirmation that the live seam is no longer behaving like a pure CdSearchFile(...) logic bug
  • copying CdlFILE immediately after search is enough to move the runtime, matching the earlier stack-layout branch
  • the strongest active suspects are now:
    • local CdlFILE lifetime / overwrite
    • adjacent stack layout around cdfile, headerData, and entries
    • UB or clobber between the first and second ps1_streamReadFromCdFile(...) calls
• Cleanup:
  • reverted the temporary stableCdfile probe in repo:/cdrom_ps1.c
• Next target:
  • probe memory adjacency around cdfile more directly, rather than pack-search logic
  • likely either:
    • duplicate cdfile into a far-separated local block
    • or harden / relocate other nearby locals in repo:/cdrom_ps1.c