Skip to content

ByteTerrace/Puck / .claude/skills/gaming-bricks

gaming-bricks

Verified

Fixes Puck GB/GBC/GBA and NES/Famicom (HGD) emulators: CPU, PPU/STAT timing, APU, links, snapshots and Post batteries (--cosim, --filter). Cartridges: rom-forge.

FileKindSize
SKILL.mdskill md17.2 KB
evals/e01-stop-with-pending-interrupt/graders/hands-back-stage-and-skip-counts.mdmarkdown562 B
evals/e01-stop-with-pending-interrupt/graders/names-execute-stop.mdmarkdown68 B
evals/e01-stop-with-pending-interrupt/graders/names-the-pending-stage.mdmarkdown84 B
evals/e01-stop-with-pending-interrupt/graders/pad-byte-rule.mdmarkdown702 B
evals/e01-stop-with-pending-interrupt/graders/post-filter.mdmarkdown65 B
evals/e01-stop-with-pending-interrupt/graders/skill-fired.mdmarkdown36 B
evals/e01-stop-with-pending-interrupt/graders/sst-oracle-conflict.mdmarkdown735 B
evals/e01-stop-with-pending-interrupt/prompt.mdmarkdown621 B
evals/e02-gba-siocnt-partner-ready/graders/closes-reference-and-open-item.mdmarkdown682 B
evals/e02-gba-siocnt-partner-ready/graders/derive-from-the-cable-partner.mdmarkdown694 B
evals/e02-gba-siocnt-partner-ready/graders/names-link-replay-stage.mdmarkdown68 B
evals/e02-gba-siocnt-partner-ready/graders/names-pack-sio-control.mdmarkdown71 B
evals/e02-gba-siocnt-partner-ready/graders/proves-partner-present-and-absent.mdmarkdown707 B
evals/e02-gba-siocnt-partner-ready/graders/skill-fired.mdmarkdown36 B
evals/e02-gba-siocnt-partner-ready/prompt.mdmarkdown482 B
evals/e03-mode0-interrupt-delay/graders/checks-screenshot-regressions.mdmarkdown978 B
evals/e03-mode0-interrupt-delay/graders/coupled-contract.mdmarkdown705 B
evals/e03-mode0-interrupt-delay/graders/diagnostics-only.mdmarkdown715 B
evals/e03-mode0-interrupt-delay/graders/skill-fired.mdmarkdown36 B
evals/e03-mode0-interrupt-delay/graders/stat-trace.mdmarkdown69 B
evals/e03-mode0-interrupt-delay/prompt.mdmarkdown424 B
evals/e04-cosim-short-run-proves-nothing/graders/boot-logo-dominates.mdmarkdown539 B
evals/e04-cosim-short-run-proves-nothing/graders/cpu-stream-is-not-a-ppu-verdict.mdmarkdown644 B
evals/e04-cosim-short-run-proves-nothing/graders/record-count-check.mdmarkdown575 B
evals/e04-cosim-short-run-proves-nothing/graders/reruns-past-boot.mdmarkdown439 B
evals/e04-cosim-short-run-proves-nothing/graders/skill-fired.mdmarkdown36 B
evals/e04-cosim-short-run-proves-nothing/prompt.mdmarkdown432 B
evals/e05-snapshot-field-added/graders/current-version.mdmarkdown71 B
evals/e05-snapshot-field-added/graders/field-listed-once.mdmarkdown691 B
evals/e05-snapshot-field-added/graders/skill-fired.mdmarkdown36 B
evals/e05-snapshot-field-added/graders/transfer-state.mdmarkdown88 B
evals/e05-snapshot-field-added/prompt.mdmarkdown294 B
evals/e06-idle-fast-path-equivalence/graders/names-equivalence-law.mdmarkdown77 B
evals/e06-idle-fast-path-equivalence/graders/names-the-reference.mdmarkdown89 B
evals/e06-idle-fast-path-equivalence/graders/skill-fired.mdmarkdown36 B
evals/e06-idle-fast-path-equivalence/graders/stale-clock-agreement.mdmarkdown702 B
evals/e06-idle-fast-path-equivalence/prompt.mdmarkdown426 B
evals/e07-firmware-toolchain-cache/graders/cache-policy.mdmarkdown526 B
evals/e07-firmware-toolchain-cache/prompt.mdmarkdown578 B
references/hardware-and-oracles.mdmarkdown25.4 KB

references/hardware-and-oracles.md

View on GitHub
# GamingBrick hardware and oracle contract

This reference holds the specialized cross-generation facts that are not
obvious from the repository layout. Verify changing stage inventories,
diagnostic switches, asset variables, and known limitations against current
source and the two Post READMEs.

## Contents

- [Architecture](#1-architecture)
- [Clock and event order](#2-clock-and-event-order)
- [Snapshots and host boundaries](#3-snapshots-and-host-boundaries)
- [GB PPU timing](#4-gb-ppu-timing)
- [Oracle discipline](#5-oracle-discipline)

## 1. Architecture

- Emulated state advances only from the integer tick clock and explicit
  inputs or configuration. Do not introduce wall-clock time, randomness, or
  floating point into emulated logic.
- GB software runs through one shared SM83 core parameterized by
  `ConsoleModel`, which is revision-valued (`Dmg0`…`DmgC`, `Mgb`, `Sgb`,
  `Sgb2`, `Cgb0`…`CgbE`, `Agb`, `Ags`). Components ask a named question on
  `ConsoleModelExtensions` and cache the answer through `ApplyModel`; do not
  fork the core, and do not switch on a revision inside `Sm83`/`Ppu`/`Apu`.
- The ARM7TDMI core is the separate GBA-native machine. Cartridge selection
  chooses between the compatibility costume and native machine; both share
  the master-clock and link abstractions where the hardware does.
- Cross-generation link sessions must remain replay-identical. Different
  console generations may change capabilities, but not the determinism
  contract.

## 2. Clock and event order

### Master clock

The unified integer tick base is 2²⁴ ticks per second:

- DMG and normal-speed CGB run at 2²² ticks per second.
- Double-speed CGB runs its processor at 2²³ ticks per second; the display, and
  the host's pacing (`HumbleGamingBrickCore.CycleRate`), stay at 2²² dots per
  second in every model.
- GBA runs at 2²⁴ ticks per second.
- One GBA tick is one 16.777216 MHz CPU cycle; one frame is 280,896 cycles.

Keep all conversions exact and carry remainders. Do not confuse GBA CPU cycles
with display dots.

### GB serial and timer

- The serial shifter advances on each falling edge of DIV counter bit 8 in
  normal mode or bit 3 in CGB-fast mode.
- Detect the edge on the free-running counter. Writing SC arms a transfer but
  does not reset or re-phase the clock. The acceptance `boot_sclk_align`
  case pins the rule: edges align to the counter's reset
  time, never to when SC is written.
- TIMA increments on the falling edge of the TAC-selected DIV bit while
  enabled. A DIV write can therefore cause a timer increment, and the
  four-tick reload-delay precedence remains observable.
- At equal timestamps, advance the timer before serial. This tie-break is
  load-bearing for cross-generation link lock.

The Humble `link-churn` stage and acceptance ROMs are the executable evidence.
For a DMG result-signature reader, observe the intended SB write through
`SerialComponent.ByteQueued`; the output routine can re-arm an unfinished
normal-clock transfer.

### AGB serial clock ownership

- Normal 8/32-bit external-clock transfers stay armed without scheduling a local
  completion, even with a cable partner attached. Only an internally clocked
  peer supplies the completing transfer. Internal-clock transfers can finish
  alone and receive idle-high data.
- A peer-delivered completion cancels any superseded local completion event;
  changing clock selection while busy must not leave a second interrupt queued.
- `serial-clock` gates both normal widths and rates, delayed master startup,
  busy release and single-interrupt delivery. `firmware-multiboot` separately
  checks native normal-mode payload exchange and multiplayer download.

### Audio

Integer PCM12/PCM34 channel outputs are the emulated contract, and they are
latched: a channel publishes a new level only when its generator steps, its
envelope moves, or a register write reaches it, and a channel whose DAC is off
holds the level it last published. Floating-point mixing is presentation only
and must never feed state.

The unit runs on two clocks. Its CPU-domain tick follows the DIV-APU bit —
bit 12 of the DIV counter, or bit 13 in double-speed mode: the falling edge
advances the 512 Hz divider (length at 256 Hz, sweep at 128 Hz, the envelope
reload pre-count at 64 Hz), and the rising edge half a period later arms the
envelope clocks, which the next falling edge steps. The generators — duty
positions, the wave fetcher, and the noise counter that clocks the LFSR — run
on a fixed 2 MiHz audio clock, two whole dots per tick, derived by halving the
per-dot stream `ApuGeneratorClock` delivers. The noise channel is a 14-bit
counter with an edge detector on the NR43-selected bit, not a shift-scaled
period, which is why two (divisor, shift) pairs naming one rate step the LFSR
at the same instants.

A read and a write reach the unit at different points inside their machine
cycle — a write on the drive instant, a read `LeadingTCyclesBeforeRead` later
(`Sm83.Decode.cs`) — so a read observes one more audio tick than the write that set
the event up. The generators carry
that skew in their countdown loads; the write-side predicates undo it by
looking one tick ahead (`PeekSquare`, `PeekWaveFetch`). Move one and the other
has to move with it.

Where the skew is *observable* follows from how a machine cycle divides into
audio ticks, and the two speeds differ. At normal speed a machine cycle spans
two audio ticks, so the read strobe stays inside the same 1 MiHz half that the
duty counter and the noise counter are quoted against and the skew moves no
edge a reader can see. Under double speed a machine cycle is exactly one audio
tick, so the same skew carries the first generator edge a whole step past where
the reader expects it — which is why a square or noise *trigger* loads the skew
only under double speed (`ApuComponent.TriggerReadStrobeSkew`), while the wave
fetcher and the sweep unit, quoted against the 2 MiHz clock directly, carry it
at both speeds. Applying it unconditionally costs ten sample-accurate cases;
omitting it costs seven. This is the single mechanism behind the whole
`channel_*_align` / `_align_cpu` / `_duty` family.

Chasing an audio timing case is trace-led, not swept: run the co-simulation
(`--cosim <rom> --sameboy … --boot … --model cgb --kind cpu`, budget past the
boot animation), then walk the two `artifacts/gb-post/cosim/*.cosim.bin`
streams for the first divergence in *content* rather than cycle stamp — the
cycle column diverges harmlessly on a shared prologue long before any test
runs. The SameSuite alignment ROMs are unrolled sweeps that retrigger a
channel, burn one more `NOP` per iteration, and read PCM12/PCM34; the
divergence lands on the iteration where the observed edge moves, which names
the tick the model is off by.

## 3. Snapshots and host boundaries

Both machines implement mid-frame `Snapshot`, `Restore`, and `Fork` through
`Puck.Machines`: `StateWriter`, `StateReader`, `SnapshotSection`, the FNV-1a
fingerprint, and `SnapshotImage`, behind `ISnapshotable` components. Component
identity and discovery order remain machine-specific.

The DI-owning instance/fork/pool lifecycle also lives in `Puck.Machines`, as
one generic triad closed over an `ISnapshotableMachine` marker interface:
`MachineInstance<TMachine, TConfiguration>`, `MachineFork<TMachine,
TConfiguration>`, and `MachineInstancePool<TMachine, TConfiguration>`. Each
brick re-exposes its own closure under a bare name (`MachineFork`/
`MachineInstance` for `Puck.HumbleGamingBrick`, `AgbMachineFork`/
`AgbMachineInstance` for `Puck.AdvancedGamingBrick`) through a `global using`
alias in that project's `GlobalUsings.cs` — searching for a declared
`class AgbMachineInstance` finds nothing; the type lives in
`src/Puck.Machines/MachineInstance.cs` under the generic name.

- Snapshot bytes are the state-of-record determinism surface.
- Every component of both cores lists its snapshotted fields once, in a
  `TransferState` (a Humble mapper's `TransferRegisters`) generic over
  `IStateTransfer`; `SaveState` and `LoadState` run that list through
  `StateSaveTransfer` and `StateLoadTransfer`. A part a component owns (an AGB
  PSG channel, a Direct Sound FIFO, the shared `RationalRateAccumulator`) moves
  through its own `TransferState` inside the owner's list. An AGB peripheral's
  scheduled event moves through `AgbScheduler.TransferEvent`, which re-arms it
  on load. Load-only work (a derived mask, a range check, re-derived timer
  events) follows the transfer in `LoadState`.
- No file records a component's layout. A deliberate layout change raises
  `CurrentVersion` of `MachineIdentity` (Humble) or `AgbMachineIdentity`
  (Advanced), which the core's checkpoint identity names.
  `ComponentSnapshotRoundTripLawTests` in `tests/Puck.HumbleGamingBrick.Tests` and
  `tests/Puck.AdvancedGamingBrick.Tests` seeds each component's fields from
  their names, saves, loads into a differently seeded twin and requires the
  same bytes back, so a field saved but not loaded fails.
- `--hash-divergence` localizes a mismatch between two executions in one
  process and one build.
- Use `--dump-snapshot` and an offline section-table diff for cross-build byte
  comparisons.
- Host audio drains integer `short` samples from presentation-side rings.
  Attaching a sink may gate presentation work, never emulated audio advance.
- Convert host delta time to cycles with exact rational arithmetic and carry
  the remainder between updates.
- Native AGB `StepHalted` yields after one idle cycle and pending DMA when no
  wake interrupt is committed. CPU steps include these idle advances; never
  wait indefinitely inside a step, because queued input and linked peers
  must run to produce keypad or serial wake requests. Wake latency stays on
  the bus, and snapshots preserve the halted pipeline.
- Both screen engines default to bundled Puck firmware and cold startup.
  `fast` skips startup but retains the selected firmware; AGB still executes
  SWI services and IRQ dispatch from that image. An optional final `bios=<path>`
  selects an external image. AGB's standalone `stub` remains an explicit fast
  diagnostic mode, not a BIOS implementation. Explicit low-level configurations
  retain their documented diagnostic defaults; `AgbFirmware` and `HgbFirmware`
  own the bundled-image configuration helpers.
- Restoring AGB state clears queued presentation PCM while retaining the
  serialized emit phase. The output rate remains host configuration; configure
  an audio-rendering fork before restoring its snapshot. Firmware presentation
  gates check typed/raw restore and fresh PCM replay.
- AGB save restoration requests a host-side flush independently of the
  serialized dirty flag. Disk writes flush a same-directory temporary before
  replacement and retain pending state on failure. Keep this persistence
  bookkeeping outside snapshot bytes. `host-persistence` gates restore,
  forced flush and replacement retry; `lifecycle` gates halted steps, DMA
  count widths and audio reconfiguration.

## 4. GB PPU timing

Treat the STAT and memory-lock schedule as one coupled contract. Do not adjust
one lag constant in isolation.

- A visible line's schedule, in dots from the line boundary: LY register write
  and OAM STAT pulse at 2, polled mode 2 at 3, polled mode 3 with the memory
  locks at 83, the pixel loop engaging at 88, screen column 0 at 96 + `SCX % 8`,
  the internal mode-3-to-0 edge (the 160th pixel popping) with the polled STAT
  flip and the VRAM unlocks at 255 + `SCX % 8`, and the mode-0 interrupt at
  256 + `SCX % 8`. The internal edge drives HDMA.
- SameBoy's own line runs three dots ahead of ours, its schedule numbered one
  dot higher (its LX 3 is our dot 2): its line origin is one dot before ours and
  it runs the first line after an LCD enable 448 dots long where we run 452, so
  every one of our register edges lands three dots later in absolute time than
  the corresponding SameBoy edge. That gap is not slack — it is the exact
  compensation for the two cores' read conventions. Our CPU latches an I/O read
  two T-cycles into the access (`LeadingTCyclesBeforeRead` in `Sm83.Decode.cs`), so a
  read whose machine cycle begins at dot C observes every edge through C+2;
  SameBoy reads at the drive instant, and its display state machine runs on a
  half-dot grid whose `GB_SLEEP` executes an event only once time has passed it,
  so its read observes edges strictly before C. Equal observation therefore
  requires our edge at SameBoy's edge plus three, which is what the schedule
  above already produces. The `--cosim` CPU stream on `lcdon_timing-GS`,
  `lcdon_write_timing-GS`, `hblank_ly_scx_timing-GS` and
  `intr_2_mode0_timing_sprites` is divergence-free for 120 frames against a
  boot-ROM-booted SameBoy, which is the evidence.
- Do not re-derive the schedule by moving the PPU onto SameBoy's dots. Every
  decomposition of that idea — moving the read convention and first-line length
  together, holding the pipeline while moving the LYC interrupt or the read view,
  shortening the first line with a +3 polled-event phase, or moving only the pixel
  pipeline — is measured and refuted: each fails named acceptance cases or closes
  the `lycint_dmgpalette_during_m3_*` rows while losing far more of the mealybug,
  AGE and gambatte screenshot corpus, and the corpus is the gate (SameBoy's pixel
  dots and the corpus disagree by two dots). The measurements live in
  [Refuted PPU schedule decompositions](../../../../docs/emulation/hgb/post-and-conformance.md#refuted-ppu-schedule-decompositions).
- The pixel pipeline carries the same three-dot offset the register edges do, and
  the `--cosim` `ppu-pixel` walk cannot show it: that walk compares content only
  and reports our own cycle. Measure the offset with SameBoy's per-dot trace
  (external display instrumentation whose `abs=` is an exact master T-cycle) against the pixel
  records' own stamps in `puck.cosim.bin`. On `lycint_dmgpalette_during_m3_1` at
  LY 1 our column x pops three master cycles after SameBoy's, which is why we
  paint the mid-mode-3 palette from x 155 where SameBoy paints from x 157 — its
  logged pixel cycle is up to half a dot early, absorbing one of the three.
- A `--cosim` run under about 60 frames proves nothing about the ROM: the DMG
  boot ROM's logo scroll occupies them, so every ROM produces the same stream and
  the same record count. Give a CPU-stream comparison at least 120 frames, and
  check the record count differs per ROM before believing a clean result.
- `01-read_timing` diverges from SameBoy at frame 107 on a TIMA read (`pc=C2C3`,
  `hl=FF05`: SameBoy 0x01, ours 0x00, on the same master cycle and the same
  instruction) while both pass the ROM's own verdict. It survives disabling the
  display's write phases, so it is the timer's own read-observation gap, not a
  write phase.
- An I/O write does not always reach the component on its machine cycle's drive
  instant, and the display — not the CPU — is what says so. `WriteCycle` routes
  a write inside `LCDC`…`WX` to `ISystemBus.RecordDisplayWrite`, which records it
  in flight (the register, the value held, the value arriving) and returns the
  T-cycles the commit is displaced from the drive instant, negative early. The
  next access's drive instant always stays four T-cycles after this one's. A
  register that also *settles* spends the T-cycle before its commit in
  transition: `OpenDisplayWriteSettle` opens that window, and `Ppu.WriteRegister`
  closes it, so the record is zero at an instruction boundary and no snapshot
  carries it. The phases, in `Ppu.RecordWrite`: a monochrome palette register
  settles from two T-cycles early and commits one early; a Color palette register
  commits one early, two from revision D (`SamplesPaletteWriteEarly`); monochrome
  SCY commits one early and SCX two; the monochrome status register settles from
  the drive instant and commits one T-cycle late; monochrome WX settles from the
  drive instant with the arriving value already on its line. The control
  register's own phase is skipped on the LCD-enable edge — that write is also the
  enable, and pulling it two T-cycles early moves the first line's origin, which
  the LCD-on tables are calibrated against. SameBoy's `conflict_t` map
  (`Core/sm83_cpu.c`) is the corroborating source and carries phases this core
  does not model: both LCDC glitch flags, and two that are measured and held
  back rather than merely absent.
- Color LYC and WX committing one T-cycle late at single speed, together with a
  Color STAT settling window that holds the coincidence source across the
  transition, is refuted: it repairs fourteen gambatte rows and breaks eleven
  recorded passes, all in the `miscmstatirq/lycstatwirq_trigger_*` and
  `lycEnable/late_ff41|ff45_enable_lcdoffset1_*` families.
- Color SCX commits two T-cycles early at double speed (SameBoy's
  `cgb_double_conflict_map[GB_IO_SCX]`), which is one whole line dot there. Four
  `scx_during_m3/*_ds_*` rows are pixel-exact under it and six others fall by
  hundreds to thousands of pixels (9581→8866, 14833→14404, 12096→11810);
  `scx_during_m3/scx_during_m3_spx2_ds` and its `scx_attrib` sibling rise from 8
  to 16 because the earlier commit crosses one background fetch's tile-index step,
  so one more tile column takes the new coarse scroll. That riser is exactly eight
  pixels wide — x 136-143 of LY 0, the only difference between the two renders.
- The settling view is per consumer, which is the whole reason the record beats a
  value the CPU writes into the register file. Inside the settling T-cycle each
  of the display's own consumers samples the register at its own depth:
  `MixerBackgroundPalette`/`MixerObjectPalette0`/`MixerObjectPalette1` read the
  wire-OR of held and arriving, because a monochrome palette keeps driving while
  the new value lands; `InterruptStatSelect` reads every source enabled, because
  a monochrome status write releases its select lines first; `MixerControl` lets
  only the background-enable bit through; `ObjectControl` additionally drops an
  object-enable bit going low while a fetch runs, or at the start of a column on
  every package but the compact monochrome one
  (`DropsObjectEnableAtColumnStart`). Every other consumer reads the register
  field directly and therefore sees the held value, which is what the fetcher and
  the window comparisons want.
- Expressing those phases is why the bus primitives defer. `ReadCycle` leaves the
  two T-cycles it did not tick on `m_busCycleDebt`, `InternalCycle` banks four
  without ticking, and `WriteDisplayRegisterCycle` can therefore commit before its
  own drive instant. Every read of component state that is not itself a bus
  access (`ServiceInterrupt`'s two mask reads, STOP's and HALT's pending checks,
  `NoteOamCorruption`'s object-scan row) and every machine cycle the CPU spends
  off the bus (`IdleMachineCycle`) settles the debt first, and `StepInstruction`
  settles it before returning, so the debt is always zero at an instruction
  boundary and no snapshot carries it.
- No write phase can close the mid-mode-3 write families, and the reason is
  measured, not suspected. The schedule above puts our register edges three dots
  later in absolute time than SameBoy's precisely so a CPU *read* (latched two
  T-cycles into its access) observes what SameBoy's read (taken at the drive
  instant) does. A CPU *write* gets no such compensation: both cores commit it at
  the same absolute T-cycle, so against the display's own dots our write lands
  three dots early. A case that writes and then reads is still calibrated, which
  is why the acceptance interrupt and LCD-on families are green; a case whose
  verdict is the picture itself has no read to compensate it, which is why every
  mid-mode-3 screenshot family is off by a whole number of columns. On
  `lycint_dmgpalette_during_m3_1` the `ppu-pixel` stream is
  index-aligned and both cores commit BGP at the same absolute cycle, yet SameBoy
  paints from LY 1 x 157 and we paint from x 155 — the two-column error the
  corpus run reports as 286 differing pixels (143 lines x 2 columns), with the
  `lycint_*_3`/`_4` pair three columns out at 429. Moving both conventions together
  does close this family, and costs more elsewhere than it closes — see the
  refuted decompositions above.
- CPU-visible state trails the internal edge by: polled STAT, VRAM read and
  VRAM write, and OAM write by zero dots; OAM read by zero on monochrome and
  one on Color; the mode-0 interrupt by one, reduced to zero on Color at single
  speed. Double speed adds one dot to the polled STAT flip.
- STAT mode 0 and VRAM-read availability change together. A game that polls
  STAT and then reads VRAM depends on that ordering.
- The OAM STAT pulse fires on the LY write, one dot before STAT shows mode 2.
  Its tail overlaps the comparison-valid dot so a held LY=LYC condition does
  not retrigger.
- OAM writes remain available during the scan's first machine cycle and the
  first four entry-latency dots. VRAM writes also land there; reads do not.
- The window hand-over is immediate — the WX match drops the background FIFO
  and rewinds the fetcher, and the classic window penalty is the refill. There
  is no separate activation stall beyond the one extra dot monochrome silicon
  spends when WX is 0 with a non-zero `SCX % 8`.
- Tick the object fetcher before the pixel pop. From the second background
  tile onward, `ObjectFetchDot` may treat the high-data-byte address dot as
  ready once the first push has landed; the first fetch retains the read-dot
  threshold. The reason is oracle skew, not hardware: the SameBoy oracle
  advances its fetcher after the pop, so from the line's second tile the
  check-time fetcher state trails it by one step, and the allowance
  reconciles the two while the object stall stays dot-exact against SameBoy,
  including `intr_2_mode0_timing_sprites`. Pop-then-fetch with the allowance
  dropped rests on moving the line onto SameBoy's dots, which is refuted above,
  so the allowance stays.
- Our first line after an LCD enable is four dots longer than SameBoy's, so each
  enable slides our pipeline four dots against its oracle. On some ROMs the two
  happen to land together (`m3_bgp_change`'s pixel stream is dot-identical); on
  others they sit apart, which is what keeps gambatte's
  `lycint_dmgpalette_during_m3_*` off pixel-exact (their first pixel divergence is
  two columns, LY 1 x 155 against SameBoy's x 157) while their non-interrupt
  siblings improved. No
  write phase closes both: committing the monochrome palette writes
  (`Ppu.RecordWrite`'s `BGP`/`OBP0`/`OBP1` case) one T-cycle early instead of
  two moves those four ROMs from 286/429 to 143 and costs fifteen others. Closing
  it means the first line's length, which the register families pin — see the
  refuted decompositions above.
- The remaining PPU frontier is the mealybug `m3_lcdc_*` and `m3_wx_*`
  signatures. They turn on the write glitches SameBoy models in `sm83_cpu.c`
  (`tile_sel_glitch`, `wx_just_changed`,
  `disable_window_pixel_insertion_glitch`). The write-in-flight record reaches
  the PPU state each of them needs, so they are expressible as settling views on
  the same rule rather than as special cases; what still blocks them is the
  two-dot disagreement between SameBoy's pixel dots and the screenshot corpus
  above, not the write path.

The acceptance cases pinning this schedule by name: `hblank_ly_scx_timing`
(its 51/50/49 SCX pattern), the `intr_2_*` family, `intr_1_2`,
`stat_irq_blocking`, and the `lcdon_timing`/`lcdon_write_timing` tables —
moving one lag constant unbalances several of them at once. Diagnose failures
with the Humble Post `--stat-trace` and `--render` tools, then confirm the
relevant stage rather than treating a trace as a gate.

## 5. Oracle discipline

External suites and co-simulators are evidence, never repository gates. A
self-checking Post stage or golden replay is a gate.

- Normalize mGBA or ares traces before comparing them: cumulative cycle
  counters can reset at frame boundaries, so compare per-instruction deltas;
  Puck's exposed ARM PC is four bytes ahead because of pipeline
  representation; direct boot and BIOS boot have different initial state.
- The SingleStepTests/sm83 corpus has documented conflicts for STOP (`10`) and
  EI (`fb`). The corpus models STOP as a flat one-byte instruction, while the
  core consumes the pad byte when no interrupt is pending and leaves it when
  one is pending (`ExecuteStop` in `Sm83.Decode.cs`; the pending test is
  `IE & IF`, independent of IME). The Tier-A `sm83-stop-pending-interrupt`
  stage covers the pending edge the corpus cannot. The corpus also re-arms EI
  when IME is already enabled, while the acceptance `ei_sequence` behavior
  pins the core's no-op. Keep these as explicit oracle-conflict skips in the
  `sst-sm83` stage, not silent exclusions.
- BESS import/export is diagnostic cross-emulator evidence. Its
  self-consistency checks do not turn a foreign emulator into a gate.
- The Multiplayer SIOCNT SD/SI ready lines, derived from cable-partner
  presence, are unmodeled. Verify `AgbSerialController.PackSioControl` before
  relying on this limitation; when implemented, add a stage over a committed
  partner-polling micro-ROM and update this reference with it.

Keep proprietary ROMs, retail BIOS images, and external corpora outside the repository.
Original bundled Puck firmware is the exception: its generated images and
permissive licenses are package inputs, verified against their source by `puck firmware`.
Local retail images may serve as black-box test oracles, never as bundled
payloads or instruction sources for replacement firmware. Use the
current Post README and command-line parser as the authority for environment
variables and supported diagnostic switches.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall