virtualjaguar-libretro/docs/texture-dump.md

Texture dump + replacement (issue #369)

Design spec for virtualjaguar_texture_dump (deliverable 1: write every unique blit source tile a title uses to disk as PNG + manifest, so pack authors have something to redraw) and virtualjaguar_texture_replace (deliverable 2: present pack art in place of those tiles). The replacement pipeline consumes exactly the identity contract dump mode freezes — see "Replacement pipeline" below.

Status: both implemented. Dump: capture module src/tom/texdump.c, hook in src/tom/blitter_mmio.c, options in libretro.c / libretro_core_options.h, test gates in test/tools/test_texdump.c + test/expected/texdump_yarc.txt. Replacement: src/tom/texreplace.c (+ ShadowFBStoreRGB and, for >1x art, ShadowHiresStoreReplBlock in src/tom/shadowfb.c), gates in test/tools/test_texreplace.c. Remaining: indexed (≤8bpp) sources, tier 2 — the design is on issue #369 and summarised under "Tier status and limits".

Goals and non-goals

Goals (v3.4.0):

• Dump each unique blit source exactly once per session as a viewable PNG, plus an append-only manifest row.
• A stable identity contract: the hash a tile dumps under in v3.4.0 is the key the v3.5 replacement pipeline looks up, and the filename community authors save redrawn art under. Stable from day one is the target; the manifest carries a texdump v1 version marker so that if a re-key is ever forced, v2 is visible rather than silent.
• Pace-neutral and inert by construction: zero work when disabled beyond one branch; when enabled, zero effect on the emulated machine (provable via savestate digests).

Non-goals (v3.4.0):

• No replacement/lookup path (v3.5; >1x replacements ride the Stage 2 shadow surface, #367).
• No capture of OP-only sprites or GPU-computed surfaces (Doom's texture mapper). #369 scopes the HD-pack flow to the blitter; art that never passes through the blitter as a source is invisible here.
• No pack file-format spec beyond directory layout + hash filename + manifest columns. That minimal surface is the seed of the pack format; v3.5 extends it, never rewrites it.

Capture approach: register-described window at launch

Hook once at the shared blit-launch site (beside BlitMemoLaunch, before fast/accurate engine dispatch). When the option is on and the blit reads source data (SRCEN), walk the source rectangle as described by the blit registers (source channel base, flags, pixel size, pitch/width, B_COUNT) directly out of emulated memory at launch time. Hash it, dedupe, and on first sight render + write the PNG and manifest row.

Why register-described rather than tapping the engines' inner loops:

• Pace-neutral by construction. All work is host-side at launch; no per-pixel instrumentation in any engine; the bus model never sees a cycle of it.
• Engine-independent identity. Fast and accurate blitters have known read-pattern divergences (e.g. A2_PIXEL writeback). A hash derived from the register description is identical under both engines — a property the test suite asserts, and the reason a day-one stable contract is defensible at all.
• Exotic blits (scaled, phrase-alignment edge cases) may read slightly different bytes than the described window. For identity that is acceptable: the key must be deterministic and collision-free, not a byte-exact replay of the engine's read stream.

Source-channel selection (whether A1 or A2 is the reader) follows the same B_CMD decode the engines themselves use, computed once at launch. Implementation must verify the decode against docs/jtrm-blitter.md (address generators, B_CMD bits) — not against source-code comments.

Skipped (never hashed, never dumped): blits without SRCEN (pattern/Gouraud fills), described source windows larger than 1 MB (garbage-register guard), and blits whose described window falls outside populated address space.

The identity contract (what feeds the hash)

Key = FNV-1a 64 over a canonical little-endian serialization:

'VJTD' | version=1 | src_bpp | width(px,u16) | height(rows,u16)
      | source bytes, row-major, packed exactly as stored in memory

• src_bpp ∈ {1, 2, 4, 8, 16, 32} from the source channel's pixel-size field.
• Source bytes are the raw memory contents — index values for ≤8bpp, raw 16/32-bit pixel values otherwise — in stored byte order.
• Filename: <hash as 16 lower-case hex digits>.png.

The palette is deliberately NOT part of the key. This diverges from SNES/N64 HD-pack precedent (Mesen, Rice hash bytes+palette) for a hardware reason: those systems replace at the render-to-screen stage, where the palette is in hand. Our replacement happens at blit time, and the Jaguar blitter never sees a palette — CLUT lookup is an Object Processor display-time concept. At replacement time the pipeline has only the source bytes; two CLUT variants of one indexed tile are indistinguishable at the swap point. Keying dumps on bytes+palette would therefore mint keys the replacement pipeline can never discriminate, stranding every pack drawn against them. Bytes-only keys are the honest contract. Palette information is advisory metadata (below), never identity.

Collision risk: a title's unique-tile population is thousands to tens of thousands; birthday bound at 2^64 is negligible. FNV-1a 64 is already this repo's digest idiom (savestate digests, frame_hash_ab).

Rendering (advisory, not identity)

The PNG a hash dumps as is a preview for the author's benefit; the bytes are the contract.

• ≤8bpp (indexed): rendered through a snapshot of the relevant TOM CLUT slice taken at first-sight launch. The CLUT CRC is recorded in the manifest. If the same key is later seen under a different CLUT, no new PNG is written (same key, one file); the manifest gains an additional clut= sighting row. Authors of palette-animated art get the first palette as their preview and the manifest tells them others exist.
• 16bpp: the blitter cannot know whether values are CRY or RGB16 — that is also display-time interpretation. Option virtualjaguar_texdump_16bpp = cry (default) | rgb | both chooses the preview rendering; both writes <hash>-cry.png and <hash>-rgb.png. CRY conversion reuses the existing tables in src/tom/tom.c — no second implementation.
• 32bpp: direct RGB render.
• PNGs are fully opaque. Transparency on the Jaguar is a blit property (TRANSEN/DCOMPEN), not a tile property; observed flags are recorded per manifest row instead.

PNG encoder: in-tree miniz, one build define

No new vendored code. miniz 3.1.1 (already vendored for CHD in deps/libchdr) ships tdefl_write_image_to_png_file_in_memory_ex(); our unity TU currently disables the compressor with MINIZ_NO_DEFLATE_APIS, and upstream wrapped every disable in #ifndef guards precisely so dependents can restore them. Adding -DMINIZ_DEFLATE_APIS to the existing unity.o rule enables the encoder on every one of the 30+ targets, MSVC included, because miniz already compiles on all of them today. Cost ≈ 10–20 KB on a ~1.9 MB dylib. Encode happens at most once per unique hash; the in-memory PNG is written through the libretro VFS (rfopen/rfwrite), same as every other file this core touches.

Rejected alternatives: hand-rolled writer (new code to maintain vs one define); native platform encoders (ImageIO/WIC/libpng would be a per-platform matrix across a 16-target release CI, and consoles/Emscripten need the portable path anyway, so both would end up shipped).

On-disk layout

<system_dir>/vj_texdump/<CRC32 8-hex>/
    manifest.tsv
    <hash16>.png
    <hash16>-cry.png / <hash16>-rgb.png     (16bpp 'both' mode only)

• Directory named by cartridge CRC32 only (same identity titledb keys on); the human-readable title lives in the manifest header, so no filename sanitization across platforms.
• manifest.tsv, append-only, tab-separated:
  • header: # texdump v1 <tab> crc=<CRC32> <tab> title=<name>
  • first-sight row per hash: hash <tab> WxH <tab> bpp <tab> frame=<n> <tab> src=<addr> <tab> clut=<crc|-> <tab> flags=<transen,dcompen|->
  • additional-palette sighting: hash <tab> clut=<crc> <tab> frame=<n>
• Counts/statistics are deliberately not tracked (would force manifest rewrites); a summary line goes to the frontend log at unload.

Runtime behaviour and bounds

• Core options: virtualjaguar_texture_dump (disabled default, runtime-toggleable — capture is passive, no restart needed) and virtualjaguar_texdump_16bpp, the latter visible only while dump is enabled (same visibility machinery as virtualjaguar_bios_type).
• Dedupe set: open-addressed uint64 table, fixed 2^17 entries (1 MB host RAM, allocated on first enable, freed at retro_deinit). On overflow: warn once to the log, stop recording new tiles, keep running.
• All on the emulation thread; no locks, no queues. Worst realistic first-frames burst (a title blitting hundreds of unique tiles at boot) costs hashing + a few hundred small PNG encodes spread over the frames where each is first seen — a dev-facing feature is allowed a one-time hitch, and dedupe makes steady state near-free.
• Savestate: zero fields, no version bump. All dump state is host-transient; loading a state mid-session merely re-encounters hashes the dedupe set absorbs. (Lesson of #400: enhancement-path state outside the blob is the savestate blind spot — the design answer here is to have no state the machine can see.)
• iOS/static reset: retro_deinit frees the set, closes the manifest, resets every static (no dlclose on iOS).

Test gates (all in make test)

1. Contract freeze (determinism): test/roms/yarc.j64 (committed, public), 600 frames, dump on → the set of manifest hashes equals a committed golden list. Two consecutive runs produce identical sets. This is the CI tripwire that makes "stable from day one" real: any change that moves a hash fails loudly and forces a deliberate v2.
2. Engine independence: the same run under virtualjaguar_blitter=fast vs accurate yields identical hash sets. This asserts the property that justifies the contract; if it ever fails it is a real divergence finding, not a test to relax.
3. Inertness, off: dump disabled → per-frame framebuffer hashes identical to baseline (existing frame_hash_ab pattern).
4. Inertness, ON (the strong claim): dump enabled → per-frame framebuffer hashes AND savestate digests at frames 300/600 identical to disabled (hires_state_digest pattern: proves the emulated machine cannot observe the feature).
5. PNG validity: parse an emitted file's signature, IHDR, and chunk CRCs in the test harness (chunk CRC-32 verified against src/core/crc32.c — no external decoder dependency).
6. scripts/c89-lint.sh on every new file; new sources added to the MSVC compile list in c-cpp.yml.

File plan

• src/tom/texdump.c / .h — capture, hash, dedupe, CLUT snapshot, render, manifest, miniz PNG write. (~350 lines.)
• src/tom/blitter_mmio.c (or the shared launch site) — one call beside BlitMemoLaunch.
• libretro.c / libretro_core_options.h — options + visibility.
• Makefile.common, Makefile (-DMINIZ_DEFLATE_APIS on unity.o), .github/workflows/c-cpp.yml MSVC list, exports.list additions under TEST_EXPORTS for the probes.
• test/tools/test_texdump.c + test/expected/texdump_yarc.txt.
• docs/texture-dump.md — this document, plus an authoring section (directory layout, what the hash means, palette caveats) written at implementation time.

Authoring guide (for pack authors)

Turn on Texture Dump Mode (Options → Diagnostics) and play. Every unique source tile the game pushes through the blitter lands in

<RetroArch system dir>/vj_texdump/<cart CRC32 as 8 hex digits>/
    manifest.tsv         one row per unique tile (+ palette sightings)
    <hash16>.png         preview, named by the tile's identity hash

What to know before redrawing:

• The filename is the contract. <hash16> is the FNV-1a 64 key of the tile's raw bytes (plus bpp and dimensions). The v3.5 replacement pipeline will look art up under exactly this name — never rename the files. If the manifest header ever says something other than texdump v1, hashes from a different contract version are not interchangeable.
• The PNG is a preview, not the truth. For indexed (≤8bpp) tiles it was rendered through whatever CLUT the game had loaded the first time the tile was seen; the manifest row records that CLUT's CRC. A tile the game recolours via palette swaps appears ONCE (one hash, one file) with extra clut= sighting rows telling you other palettes exist. That is deliberate: the blitter never sees a palette, so two CLUT variants of one tile are indistinguishable at the point where replacement will happen. Draw for the tile, not for one palette.
• 16bpp tiles can be CRY or RGB16 — the hardware doesn't say. If a preview looks like noise, switch Texture Dump: 16bpp Preview to the other interpretation (or both) and reload; the hash (and therefore the filename) does not change.
• Transparency is a property of each blit, not of the tile; flags= in the manifest records the comparator bits seen on first sight. Previews are fully opaque.
• The manifest is append-only across sessions; play more of the game and new tiles simply append. Dedupe is per-session, so a replayed session may re-append rows for tiles already listed — rows are advisory, files are identity.

Replacement pipeline (deliverable 2 of 2)

virtualjaguar_texture_replace presents pack art in place of dumped tiles. Module: src/tom/texreplace.c; hooks around the engine dispatch in src/tom/blitter_mmio.c; presentation via ShadowFBStoreRGB in src/tom/shadowfb.c.

Pack layout

<system_dir>/vj_texpacks/<CRC32 8-hex>/<hash16>.png

Mirrors the dump layout, so an author's workflow is: dump, redraw, move one directory over. Only files named exactly <16 hex>.png are read; anything else in the directory (manifest copies, notes, PSDs) is ignored. Accepted PNGs: 8-bit depth, non-interlaced, color types 0/2/3/4/6 (gray, RGB, indexed, gray+alpha, RGBA). The whole pack is decoded ONCE into a host-side hash→pixels map — at content load, or on first enable — never at blit time.

Architecture: host-only, presentation-riding

The pipeline never touches the emulated machine. Not "restores it afterwards" — never touches it:

1. At blit launch (pre-dispatch) the SOURCE window is hashed with the same shared helpers dump mode uses (TexDumpDescribe / TexDumpSerialize / TexDumpHashKey — one implementation, frozen contract). A map hit with matching dimensions arms the launch, and the DESTINATION window is described before the engines write back the pointer registers.
2. The blit dispatches completely stock.
3. Post-dispatch, the destination window is walked host-side: every pixel whose RAM word now equals the source pixel captured pre-dispatch (the per-pixel straight-copy witness) gets its pack RGB888 stored into the true-color shadow framebuffer, tagged with that RAM value. The OP's existing shadow presentation path (ShadowFBLineFromRAM → the CRY scanline renderer) then presents the pack art; the value-check makes every entry self-invalidating when RAM moves on.

The witness makes wrong models harmless: transparent (BCOMPEN / DCOMPEN) pixels, shaded or Gouraud outputs, exotic step patterns — anything whose destination value is not the source value — simply never stores, and the stock pixel presents.

Consequences, all load-bearing:

• Zero savestate fields, zero RAM writes, zero bus-model time. Savestates, rewind, run-ahead and netplay see a bit-identical machine with or without a pack; only the presented frame differs. test/tools/test_texreplace.c asserts framebuffer hashes, savestate digests AND battery destination RAM are identical to replacement-off, while the shadow surface provably carries the pack art.
• Packs are true-color. Replacement RGB is presented through the shadow surface, so there is no RGB→CRY quantization anywhere in the pipeline. Alpha < 128 in a pack pixel means "keep the stock pixel" (transparency at blit time is still the game's business).
• The shadow surface is forced on while a pack is active, but the Gouraud-precision stores (the True Color feature proper) stay gated on virtualjaguar_true_color via the separate shadowFBPrecision flag — a replacement-only activation leaves every non-replaced pixel bit-identical to stock.
• The option is visible only when a pack directory exists for the loaded content (same SET_CORE_OPTIONS_DISPLAY machinery as the 16bpp-preview knob), and defaults to disabled.

Tier status and limits

• Tier 1 (shipped): 16bpp source tiles, 1x, straight-copy blits — the sprite/UI blit class dump mode was built for. Presentation requires the 16bpp OP path; GPU-computed surfaces (Doom's texture mapper) are out of scope, same as dump mode. Both 16bpp scanout modes present: CRY and RGB16-direct (issue #528, see "RGB16-direct scanout" below).
• Tier 3 (shipped): >1x pack art on the Nx shadow surface — see "Tier 3" below. Pack art may be authored at exactly N times the dumped dimensions while Internal Resolution is Nx, and is then presented per subpixel. 1x art is replicated into the Nx surface as well, which also removes tier 1's masking limitation.
• Known coherence limit: a replacement entry's RGB is pack art, not a function of the tagged value. A later non-blit write of the same 16-bit value to a replaced address keeps presenting pack RGB until the next store to that word. Stock true-color has the same tag scheme but is immune by construction (its RGB is derived from the value); for replacement this is a documented cosmetic edge.
• Interaction with internal resolution: resolved by tier 3 below. (Historically, at Nx the hi-res shadow surface won wherever its entries hit, so 1x replacements presented stock there.)
• Indexed (≤8bpp) sources (tier 2, not yet shipped): the pipeline cannot inject RGB into an indexed blit — the destination holds palette indices and the CLUT is applied per-object at OP render time. The planned design (notes on #369) keeps the host-only architecture: a byte-granular index shadow filled at the same post-blit witness point, resolved at the OP's indexed line-buffer write sites through the object's own palette base, presenting via the same shadow line buffer. Authors will supply index-map PNGs (gray or indexed color type; the sample value IS the Jaguar palette index), which keeps palette-swapped sprites faithful. Until it ships, indexed pack entries load but never present (counted in the session summary).

Tier 3: >1x pack art on the Nx shadow surface

The internal-resolution feature (#367) gives every stock 16-bit pixel word an N×N block of shadow subpixels, resolved by the OP into an Nx line buffer and rendered by tom_render_16bpp_cry_scanline_hires. Tier 3 puts pack art into exactly that pipeline.

Entry format was the whole problem: a shadowfb_sub is {value16, frac16}, a CRY decomposition, and pack RGB is not a function of the stock value. Rather than widen every entry to 8 bytes for every user, replacement rides a parallel per-page plane of N×N uint32 entries plus one extra bit in the same word tag (HIRES_TAG_REPL). That buys three properties for free:

• any ordinary ShadowHiresStoreCry/Block to the word rewrites the tag without the bit, so stale pack art self-clears through machinery that already exists (the same reason the tag scheme was chosen for true color);
• the value+epoch coherence check is unchanged and shared;
• a 1x run, or a 2x run with no pack, allocates nothing — planes are allocated per page on first pack write, and both the OP resolve and the scanline renderer hoist a single shadowHiresReplActive test.

Planes share SHADOWFB_HIRES_CAP_BYTES with the base pages, which is safe by arithmetic rather than by policy: at N=2 all 256 base pages are ~20.5 MB and all 256 replacement planes ~16.8 MB, ~37 MB against a 64 MB cap, and SHADOWFB_HIRES_MAX_N is 2 — a pack cannot starve base allocation. A plane allocation that does fail sets its own stopped flag, never hiresAllocStopped: running out of budget for pack art must degrade the pack, never the base hi-res feature.

Entry encoding is SHADOWFB_HIRES_REPL_VALID | RGB888, or 0 meaning "keep what is underneath" — so an author's alpha hole falls through to the Stage 2 supersampled content, not to a flat colour.

Dimension rule: exactly 1×, or exactly N× in both axes (N from the active internal resolution). Nothing in between: an arbitrary resize has no defined mapping onto stock pixel words, and silently rescaling would make the per-pixel straight-copy witness meaningless.

1× art is stored into the Nx surface too, replicated N×N. Without that, hi-res would mask 1x packs outright — the Nx line entry wins wherever it hits and the 1x shadow only shows through on a miss. This is why tier 3 removes a tier 1 limitation rather than only adding a capability.

The 1× representative of a stock word covered by N× art is the pack's top-left subpixel (recorded in the 1x shadow, so a hi-res resolve miss degrades to pack colour rather than to stock). Top-left, not an average: an average would invent a colour the author never drew.

Static content keeps its N× art (issue #528; was a tier-3 limit). Nx blocks carry the surface's frame epoch and stock supersampled content is only trusted for HIRES_EPOCH_WINDOW (16) presented frames. Pack art is exempt from that age check; only the stock sub block behind an author alpha hole still ages. Before the exemption, a tile blitted once and left on screen — a static HUD, a menu, a title card — showed crisp N× art for ~16 frames and then aged out to the 1× representative: the same tile as flat blocky top-left colours.

The exemption is safe because it adds no new failure class. The window bounds stale structure — an N×N interior derived from a write RAM no longer holds — and for pack art that class is already unbounded and already shipping at 1×, where the tier-1 shadow carries no epoch at all and is presenting the same tile's 1× representative at the same pixel on the same value check. Refusing the N× block therefore prevented no wrong-tile artifact; it only dropped that artifact's resolution. (Note shadowHiresResolveMissEpoch still counts such words: the resolve counters describe the stock block, so the counter climbing while pack art is on screen is expected.)

Asserted by gate 9, hires_static_persist, which steps real presented frames between the battery blits and the probe — nothing fakes the epoch, harness_step drives retro_run which drives ShadowHiresFrameTick — and first checks that the destination RAM is byte-unchanged across those frames, so "art gone" can only mean expiry. (The earlier claim that catching this needed a faked epoch was wrong; the battery simply never stepped any frames after blitting.)

Unchanged by tier 3: zero savestate fields, zero RAM writes, zero bus-model time. The replacement plane is a derived cache like every other shadow surface, dropped by ShadowHiresInvalidate on savestate load and when a pack is unloaded.

RGB16-direct scanout (issue #528)

Packs present on TOM's RGB16-direct scanout mode (TOMGetVideoMode() == 3) as well as CRY, at 1× and N× together. Both were wired in one change on purpose: tier 3 left RGB16 unwired at both resolutions precisely so a pack could not look different at 2× than at 1× for a reason unrelated to resolution, and doing half of it would have recreated exactly that defect.

A corpus census settled the "which titles" question the deferral left open — 157 ROMs, TOM VMODE sampled once per presented frame over 900 frames with scripted input: 66 titles reach mode 3 at all, 58 spend the majority of their frames there, and 32 never leave it. RGB16-direct is not a niche path; it is the majority scanout mode for a large slice of the library, including Alien vs Predator (parks at VMODE=$06C7 from frame 30 and never leaves), Rayman, Atari Karts, Iron Soldier 2, Towers II, Pinball Fantasies and Club Drive.

Mechanically the store side needed nothing: the shadow surfaces capture the raw 16-bit destination word, and TOM's video mode only decides how that word is interpreted at scanout. What was missing was a consumer, plus one bit to tell the two kinds of shadow entry apart:

• SHADOWFB_TAG_REPL (bit 17 of the 1× tag, mirroring HIRES_TAG_REPL on the Nx tag) marks an entry as pack art — absolute RGB888 the author drew — rather than a true-color CRY reconstruction, which is a decomposition of the 16-bit word through the chroma tables and is meaningless for a word being scanned out as RGB16. The RGB16 renderers substitute on that bit and only that bit; the CRY renderers mask it out and substitute on either kind. As with the Nx tag, an ordinary ShadowFBStoreCry rewrites the tag without the bit, so stale pack art self-clears.
• TomLinePackRGB() is the single seam both RGB16 renderers call per presented pixel — one source of truth for the substitution, and what gate 10 drives, the same way gate 4 drives ShadowFBLineFromRAM.
• True color is still not wired into either RGB16 renderer, for the original reason: track 3 is CRY-only, and substituting a CRY reconstruction there would show a colour nothing ever drew.

With no pack loaded, shadowFBReplActive and shadowHiresReplActive are both 0, the 1× RGB16 renderer takes a separate loop that is byte-for-byte the one that shipped before, and the Nx box-replication identity is untouched.

Test gates (all in make test)

test/tools/test_texreplace.c, on test/roms/yarc.j64 plus a scripted 9-tile blit battery (16bpp A2- and A1-sourced, a 16×16, a dimension-mismatched entry, an RGBA entry with alpha holes, an 8bpp and a 32bpp tier-skip entry):

1. nopack_inert — enabled with no pack ≡ disabled (framebuffer, savestate digests, battery destination RAM, gate off).
2. pack_machine_inert — enabled WITH a pack: the machine is still bit-identical to disabled.
3. pack_presents — every replaced destination word resolves (value-tagged) to the pack pixel's RGB; mismatched/holed/other-tier entries produce exactly no stores.
4. presentation_path — ShadowFBLineFromRAM lands pack RGB in the line buffer the scanline renderer reads.
5. determinism — two identical pack runs agree on everything.
6. hires_machine_inert — the four-way identity gate for tier 3: {1x, 2x} × {pack, no pack} all agree on savestate digests and on every battery destination, so neither the resolution option nor a pack — nor the two together — is observable to the emulated machine. Also asserts the Nx replacement plane stays inert (shadowHiresReplActive == 0) at 2x with no pack. Framebuffer hashes are deliberately not compared across resolutions: a 2x run presents twice the pixels by design, and the digests plus destination RAM are what carry the claim.
7. hires_pack_presents — at 2x the surface delivers: ShadowHiresLineFromRAM (the function op.c calls per 16bpp pixel) lands the expected per-subpixel RGB in the Nx line replacement plane the scanline renderer reads — 2× art at its own resolution, 1× art replicated, and nothing at all where the dimensions do not match. Production and delivery are separate failure points on this surface and only delivery fails silently (see the resolve-counter note in shadowfb.h), so this gate asserts delivery, not stores.
8. hires_determinism — two identical 2x pack runs agree.
9. hires_static_persist (#528) — a tile blitted once and then left alone still delivers its N× art after 24 real presented frames have carried the epoch past the 16-frame window (24 also stays far from the 256-frame epoch wrap, which clears every tag for an unrelated reason). Precondition, checked first: the battery destination RAM must be byte-unchanged across those frames, or the gate cannot tell expiry from a coherence miss.
10. rgb16_presents (#528) — TomLinePackRGB, the seam both RGB16 renderers call per presented pixel, delivers the pack at 1x and at 2x, and delivers only the pack: a true-color CRY reconstruction sitting in the same shadow line plane must never substitute on an RGB16 scanout. That second half is what carries the correctness claim — "substitute whenever the line entry hits" passes everything else in this file and fails here.

Both new gates were shown non-vacuous against deliberately broken builds rather than only against a baseline missing their symbols (#526's negative control was weaker than ideal on exactly that point): removing only the epoch exemption fails gate 9 alone, at 0/64 words delivered with RAM confirmed unchanged; dropping only the SHADOWFB_TAG_REPL requirement fails gate 10 alone, with 66 non-pack entries wrongly claimed at 1x and 65 at 2x.

The 2x pack is generated by the same first-principles code as the 1x one, with one tile deliberately left at 1× art (proving replication) and the dimension-mismatch tile moved to 3× (twice the dumped size is a legal tier-3 entry at 2x).

The synthetic pack is built from FIRST PRINCIPLES: the test computes each tile's hash from the documented contract and writes the PNGs itself, so a lookup hit also cross-checks the frozen contract against an independent implementation. (It caught a real test bug on first run: an LFU nibble of 3 is a NOT-copy, and the per-pixel witness correctly refused to store a single pixel.)

Authoring guide (replacement)

1. Turn on Texture Dump Mode and play; collect <system dir>/vj_texdump/<CRC32>/.
2. Redraw any tile you like. Keep the dumped pixel dimensions — or, if you run Internal Resolution at Nx, draw at exactly N× them in both axes for genuine higher-detail art. Any other size is skipped (one log line names the first offender). Draw in full RGB; alpha means "keep the original game pixel here".
3. Save under the SAME filename into <system dir>/vj_texpacks/<CRC32>/.
4. Enable Texture Replacement (Options → Video; it appears once the pack directory exists). No restart needed. The log reports pack ...: N/M PNGs loaded at load and a session summary at exit.

Open items carried into implementation — resolution

• B_CMD source-channel decode: verified against docs/jtrm-blitter.md — bit 0 SRCEN reads source from A2, or from A1 when DSTA2 (bit 11) is set. Implemented exactly so in TexDumpLaunch(); the engines' variable naming agrees.
• miniz linkage: tdefl_write_image_to_png_file_in_memory_ex links cleanly from outside the unity TU (plain extern function, no visibility annotations); the CI MSVC job compiles unity.c with /DMINIZ_DEFLATE_APIS to keep cl.exe honest. The fallback wrapper was not needed. The define lives in LIBCHDR_CFLAGS (Makefile.common) rather than on the unity.o rule alone so the theos_ios path — which compiles unity.c without that rule — gets it too.
• Golden-list population: yarc.j64 blits only its two boot-time code copies through SRCEN (it renders via the OP), and so does jagniccc.j64 — no in-tree public ROM is a meaningful tripwire by itself. Instead of a second ROM, test/tools/test_texdump.c drives a synthetic blit battery through the real bus/launch path (26 scripted tiles: every bpp, both source channels, plus a palette-change re-blit that must not mint a new hash). The committed golden list (test/expected/texdump_yarc.txt, 28 hashes) freezes the ROM tiles and the battery together.