docs: define global t-cycle scheduler contract

Author: pakitovic

AI/ARCHITECTURE.md

@@ -66,6 +66,32 @@ For an early-stage repo, a simplified equivalent is acceptable as long as these
 - For the PPU, that shared T-cycle timeline is also the dot timeline; dot-by-dot behavior is the intended baseline.
 - Long-running hardware operations triggered by MMIO writes, such as OAM DMA, should become explicit in-flight subsystem state on that shared timeline rather than immediate bulk side effects.
 
+## Global scheduler policy
+
+- The DMG core must have one global scheduler that advances the whole machine on one deterministic T-cycle timeline.
+- A `GlobalScheduler` plus `step_t_cycle()`-style entry point, or an equally explicit equivalent, is the preferred architectural shape.
+- Do not run PPU, timer, APU, serial, joypad, DMA, or interrupt production as unsynchronized threads or independently clocked loops inside the core.
+- The recommended per-T-cycle phase order is:
+  1. external event ingress
+  2. master clock / shared system-counter tick
+  3. resolution of free-running counter-derived edges
+  4. autonomous peripheral ticks
+  5. bus arbitration for the current T-cycle
+  6. CPU micro-operation
+  7. MMIO side-effect commit
+  8. interrupt aggregation into `IF`
+  9. CPU wake / interrupt-accept evaluation
+- This phase order is an architectural contract for observable behavior, not a claim that Nintendo published one canonical internal scheduler.
+- Another internal decomposition is acceptable only if it preserves the same observable dependencies for PPU mode visibility, DMA blocking, timer overflow delay, serial completion timing, joypad visible-edge timing, MMIO visibility, and CPU interrupt acceptance.
+- Phase `3` is for events derived from the free-running shared clock. Device-local MMIO semantics such as `DIV` reset effects, `FF46` DMA start, `SC.7` transfer start, or `LCDC.7` LCD transitions still belong to the device that owns the register when the access commits in phase `7`.
+- The scheduler should keep one cycle-local context object or equivalent that can carry at least:
+  - the global T-cycle index
+  - current-cycle external events
+  - already-derived counter-edge signals
+  - current ownership or arbitration facts
+  - queued side effects and interrupt requests
+- The scheduler coordinates ordering and synchronization points; it must not reimplement timer, PPU, DMA, serial, joypad, APU, cartridge, or CPU-local quirks internally.
+
 ## Console model policy
 
 - The core must expose an explicit console model concept.
@@ -125,6 +151,10 @@ to immediately materialize as a separate directory.
 - stable per-T-cycle subsystem stepping order
 - explicit global synchronization points
 - orchestration between CPU, PPU, DMA, timer, APU, and peripherals
+- ingress of timestamped external events such as host input changes or external serial clocks
+- explicit separation between free-running device ticks, bus arbitration, MMIO commit, interrupt aggregation, and CPU wake / accept points
+- cycle-local context and tracing support so phase order remains visible in code and logs
+- subsystem-facing APIs that keep stage boundaries explicit, for example free-running tick, CPU step, MMIO commit, and interrupt-request aggregation steps, even if final names differ
 
 ### `bus/`
 
@@ -134,6 +164,7 @@ to immediately materialize as a separate directory.
 - access arbitration
 - integration of cartridge, VRAM, WRAM, OAM, I/O, HRAM, IE, and boot ROM mapping
 - modeling of access restrictions and conflicts when hardware makes them visible
+- two-layer arbitration made of decode / nominal ownership followed by requester-aware access policy
 - routing of OAM and `FEA0-FEFF` access attempts and CPU-provided address-bearing micro-events into the DMG-family OAM corruption path when applicable
 - MMIO routing to the subsystem-owned register contract for each mapped address
 - one source of truth for MMIO ownership, model availability, access class, and read/write side-effect policy
@@ -154,6 +185,7 @@ to immediately materialize as a separate directory.
 - fixed-priority pending selection
 - MMIO exposure of `FF0F` and `FFFF`
 - separation between controller-owned request state and CPU-owned `IME` / acceptance flow
+- aggregation of source requests into `IF` without collapsing that step into CPU dispatch
 
 ### `boot/`
 
@@ -200,6 +232,7 @@ to immediately materialize as a separate directory.
 - DIV / TIMA / TMA / TAC
 - edge-sensitive timer timing
 - timer interrupt request generation
+- ownership of the timer overflow pipeline, including the delayed `IF` request relative to logical overflow
 
 ### `joypad/`
 
@@ -210,6 +243,7 @@ to immediately materialize as a separate directory.
 - joypad interrupt generation through the shared interrupt-controller path
 - input-driven wake signaling for CPU `STOP` integration
 - separation between frontend input collection and emulated joypad semantics
+- distinction between hardware-facing button changes, visible `JOYP` changes, joypad IRQ requests, and `STOP` wake signaling
 
 ### `serial/`
 
@@ -219,6 +253,7 @@ to immediately materialize as a separate directory.
 - peer or link-endpoint boundary
 - serial interrupt generation through the shared interrupt-controller path
 - separation between emulated serial hardware and any host transport implementation
+- ownership of transfer-complete detection, `SC.7` clear timing, and completion-triggered serial IRQ requests
 
 ### `cartridge/`
 
@@ -287,6 +322,7 @@ to immediately materialize as a separate directory.
 
 ## Ownership boundary notes
 
+- The scheduler owns phase order, cycle context, and subsystem call order; it must not become a second implementation of timer, PPU, DMA, serial, joypad, or CPU rules.
 - The boot subsystem owns firmware assets, model-aware boot configuration, and boot-ROM enable/disable state.
 - The boot subsystem also owns the source-of-truth startup snapshot for direct-boot entry, while the target subsystems still own the live semantics of their registers once execution begins.
 - The DMA subsystem owns transfer state and transfer requests over time.
@@ -298,8 +334,10 @@ to immediately materialize as a separate directory.
 - Frontends, test harnesses, and tooling should provide serial peers, scripted bits, loopback, or external clock pulses through a serial-endpoint boundary rather than by writing received bytes directly into `SB`.
 - The serial subsystem owns the translation from MMIO-visible `SB` / `SC` plus peer-provided bits and clocks into live transfer progress, `SB` intermediate state, and serial interrupt requests.
 - The timer owns the shared divider/system-counter state and visible `DIV`, while the APU owns `DIV-APU`, frame-sequencer state, channel-active state, DAC state, mixer state, and HPF state derived from that shared timing source.
+- The bus owns central decode, requester arbitration, and blocked-access policy; CPU, DMA, and future transfer engines must not bypass that one policy path with caller-specific memory shortcuts.
 - The bus applies boot mapping, DMA contention, and blocked-access semantics using that subsystem state; CPU code should not embed those rules directly.
 - The bus owns address decode and MMIO dispatch, but the device that owns a register must own its read, write, and side-effect semantics.
+- The interrupt controller owns `IF` / `IE` state and fixed-priority pending selection, but it does not decide when the CPU actually accepts an interrupt or wakes from `HALT` / `STOP`.
 - The cartridge owns the meaning of persistent RAM and RTC content, while the save backend owns durable storage mechanics such as file format, paths, versioning, and atomic replacement.
 - Save-state machinery must not be smuggled into the cartridge persistence boundary; CPU, PPU, APU, WRAM, and other console-owned state belong to a different system.
 - MMIO metadata should be centralized enough that readable bits, writable bits, dynamic bits, reserved bits, and model-specific availability are not re-declared ad hoc in several modules.

AI/EXECUTION.md

@@ -33,6 +33,14 @@
 - Prefer reproducible validation over intuition.
 - Preserve the project's T-cycle timing foundation; do not introduce M-cycle-first scheduling shortcuts as a local convenience.
 
+## When touching the global scheduler or cross-subsystem ordering
+
+- Preserve the fixed per-T-cycle phase contract defined by `AI/ARCHITECTURE.md` and `AI/TIMING-AND-ACCURACY.md`.
+- Update the matching hardware docs together when the observable ordering of DMA, PPU mode visibility, MMIO side effects, interrupt visibility, or CPU acceptance changes.
+- Keep requester arbitration, MMIO commit, and interrupt aggregation explicit; do not replace them with ad hoc subsystem-to-subsystem calls just because one local test passes.
+- Add or update focused cross-subsystem tests such as DMA-vs-CPU, delayed timer `IF`, serial completion plus IRQ, joypad visible-edge IRQ, `HALT` / IRQ priority, and `STAT`-versus-bus coherence.
+- Prefer cycle traces over aggregate instruction summaries when validating scheduler work.
+
 ## Definition of done
 
 - Behavior is implemented consistently with hardware semantics and project architecture.

AI/ROADMAP.md

@@ -148,6 +148,30 @@ For the authoritative structure and boundaries, see
 
 ---
 
+## Cross-cutting scheduler foundation workstream
+
+This workstream spans the early roadmap because the scheduler contract must be
+fixed before later CPU, DMA, PPU, timer, serial, joypad, and APU work can stay
+coherent without refactoring.
+
+1. **Explicit scheduler phases** (`Phase 0`)
+   Goal: refactor stepping around one visible `step_t_cycle()`-style entry point with fixed per-T-cycle phases.
+   Acceptance criteria: the phase order is explicit and stable, there are no hidden cross-calls that bypass it, the scheduler owns ordering rather than reimplementing subsystem rules, and one `CycleContext`-style object or equivalent carries current-cycle events, derived signals, ownership facts, and queued side effects or IRQ requests.
+2. **Central arbitration** (`Phase 1`)
+   Goal: unify decode, ownership, and access policy behind one requester-aware bus path.
+   Acceptance criteria: CPU and DMA use the same arbitration route, decode/ownership and access-policy layers stay distinct, and DMG OAM DMA correctly leaves CPU with HRAM only.
+3. **IRQ aggregation layer** (`Phase 2`)
+   Goal: separate source request, `IF` visibility, and CPU acceptance.
+   Acceptance criteria: PPU, timer, serial, and joypad only request; the CPU accepts by `IME/IE/IF` and fixed priority; timer keeps its delayed one-M-cycle request timing.
+4. **Cycle logging** (`Phase 0`, expanded later)
+   Goal: make the actual ordering visible per T-cycle.
+   Acceptance criteria: traces can expose phase, bus owner, CPU micro-op, PPU mode, DMA activity, timer or serial events, and `IF/IE/IME`.
+5. **Global-order regression tests** (`Phase 2` onward)
+   Goal: lock down the scheduler invariants at cross-subsystem boundaries.
+   Acceptance criteria: focused tests cover DMA versus CPU, delayed timer `IF`, serial completion plus IRQ, joypad visible `High -> Low` plus IRQ, `HALT` / IRQ priority, and `STAT`-versus-bus coherence.
+
+---
+
 ## Recommended implementation order
 
 ### Phase 0 — Verification, debugging, and base architecture infrastructure
@@ -200,8 +224,10 @@ This phase must define:
 
 - base hardware types in `model/`
 - T-cycle scheduler skeleton
+- explicit per-T-cycle phase order with one `step_t_cycle()`-style top-level entry point
 - definition of responsibilities by module
 - initial interfaces between CPU, bus, PPU, DMA, timer, cartridge, and debugger
+- a cycle-local context shape carrying external events, derived signals, ownership facts, and queued side effects or IRQ requests
 - conventions to avoid mixing frontend logic with core logic
 
 #### Done criteria
@@ -210,7 +236,9 @@ This phase must define:
 - the project can run base tests against `gb-core`
 - there is a reusable minimum tracing infrastructure
 - the scheduler has a defined notion of T-cycle advancement
+- the scheduler phase order is explicit in code and docs rather than implicit in subsystem call chains
 - the responsibility split between modules is fixed
+- cycle traces can expose enough per-T-cycle state to debug scheduler ordering issues
 - the core does not depend on `gb-cli`, `gb-desktop`, or `gb-web` to function
 - the architecture is prepared to incorporate CGB without contaminating DMG behavior yet
 
@@ -253,6 +281,7 @@ Build the real foundation of the emulated system on top of which CPU, timer, DMA
 - global stepping by T-cycle
 - explicit notion of dot compatible with the PPU
 - stable stepping order for subsystems inside the scheduler
+- explicit ordering between external-event ingress, shared-counter advance, derived edges, free-running peripherals, bus arbitration, CPU micro-ops, MMIO commit, IRQ aggregation, and CPU wake / accept
 
 ##### Bus and memory map
 
@@ -261,6 +290,7 @@ Build the real foundation of the emulated system on top of which CPU, timer, DMA
 - modeling of echo RAM and unusable areas
 - access arbitration infrastructure
 - one central decode path across `0x0000-0xFFFF` with explicit owner and access policy per region
+- distinct decode / ownership and access-policy layers in that arbitration path
 - centralized MMIO register routing instead of a generic RAM-like `FF00-FF7F` block
 
 ##### Base cartridge
@@ -293,9 +323,11 @@ Build the real foundation of the emulated system on top of which CPU, timer, DMA
 #### Done criteria
 
 - the system can advance by T-cycles consistently
+- the scheduler phase order is stable, explicit, and shared across subsystems instead of encoded through call-site accidents
 - all memory accesses go through `bus/`
 - the memory map is modeled completely for DMG
 - every DMG address region has an explicit owner, read behavior, write behavior, and blocked-access policy where applicable
+- bus arbitration resolves decode/ownership before applying requester-specific restrictions, and DMA-versus-CPU precedence is centralized instead of duplicated
 - every MMIO address in `0xFF00-0xFF7F` and `0xFFFF` has an explicit routed owner and contract rather than accidental default byte-storage behavior
 - mixed MMIO registers are represented as per-field contracts rather than as plain read/write bytes plus a coarse mask
 - the cartridge subsystem parses `0x0100-0x014F` into a typed header structure and preserves CGB/SGB compatibility flags for later work
@@ -423,6 +455,7 @@ Build a truly temporal CPU core, where observable behavior emerges from internal
 - real temporal effect of EI and DI
 - interrupt priority
 - interrupt acceptance timing
+- explicit separation between source request, `IF` aggregation, CPU wake, and CPU interrupt acceptance
 - HALT
 - STOP
 - HALT bug
@@ -433,6 +466,7 @@ Build a truly temporal CPU core, where observable behavior emerges from internal
 - instructions generate their real bus accesses
 - the timer advances with the global scheduler
 - interrupts and HALT are integrated into the real execution flow
+- source requests become visible in `IF` before the CPU accepts them, and timer keeps its delayed request timing instead of being flattened into same-cycle overflow service
 - direct-boot timer state does not fake `DIV` or related registers through disconnected visible-only initialization
 - real boot executes through the same CPU fetch/decode/execute engine used for the rest of the machine
 - real boot reaches cartridge code only through an executed `FF50` write and next-fetch handoff
@@ -470,11 +504,13 @@ Integrate OAM DMA as a real transfer mechanism inside the system architecture, c
 - real temporal copy progression
 - integration with bus arbitration
 - observability of DMA start, progress, and completion
+- scheduler-visible DMA state that bus arbitration can use on the same T-cycle
 
 #### Done criteria
 
 - the transfer is not implemented as an instantaneous memory copy
 - arbitration correctly reflects DMA effects on concurrent accesses
+- CPU-versus-DMA precedence is decided centrally through bus arbitration instead of CPU-local blocking logic
 - the system can trace DMA over time
 
 #### Risks if delayed too much
@@ -697,6 +733,7 @@ Complete basic system peripherals on top of an already consolidated bus, schedul
 - serial interrupt generation driven by real transfer completion rather than by transfer start
 - serial port functional at the emulated hardware level
 - trace tools to observe both peripherals
+- scheduler-visible regression coverage for their IRQ timing and CPU wake interactions
 
 #### Done criteria
 
@@ -716,6 +753,7 @@ Complete basic system peripherals on top of an already consolidated bus, schedul
 - serial interrupt requests occur only at transfer completion, when the eighth shift clears `SC.7`
 - both are integrated through the bus and scheduler
 - their interrupts and states are observable and testable
+- their event timing does not depend on frame callbacks or host timers bypassing the T-cycle scheduler
 
 #### Joypad implementation breakdown
 

AI/TIMING-AND-ACCURACY.md

@@ -52,6 +52,25 @@ When implementing timing:
 - When external documentation expresses a timing rule in M-cycles or microseconds, restate the corresponding T-cycle value in project docs and code whenever that rule becomes behaviorally relevant or is recorded as deferred validation work.
 - Keep the timing model clean enough that future CGB double-speed behavior can be expressed as an extension of the same temporal foundation rather than a separate clocking design.
 
+## Global scheduler rule
+
+- The core should advance through one fixed per-T-cycle scheduler contract, not through ad hoc call chains between subsystems.
+- The recommended ordering is:
+  1. external event ingress
+  2. master clock / shared system-counter tick
+  3. free-running counter-derived edge resolution
+  4. autonomous peripheral ticks
+  5. bus arbitration
+  6. CPU micro-operation
+  7. MMIO side-effect commit
+  8. interrupt aggregation into `IF`
+  9. CPU wake / interrupt-accept evaluation
+- This is a project-level deterministic ordering rule chosen to preserve documented dependencies; it is not presented as the one true internal Nintendo implementation.
+- Free-running divider-derived events such as timer input edges and `DIV-APU` edge detection belong to step `3`, after the shared counter advances and before autonomous peripherals consume those edges.
+- Immediate MMIO effects produced by a write on the access T-cycle, such as `DIV` reset behavior, `FF46` DMA start, `SC.7` transfer start, or `LCDC.7` LCD transitions, still belong to the owning device when the access commits in step `7`.
+- `IF` updates from hardware sources belong to step `8`; CPU acceptance is a later CPU-owned decision and must not be collapsed into the producer path.
+- Another internal implementation shape is acceptable only if these same observable dependencies remain true.
+
 ## Practical timing rule
 
 - CPU, PPU, timer, APU, DMA, and bus-visible effects should be expressible on a shared T-cycle timeline.
@@ -80,3 +99,5 @@ When implementing timing:
 - Slow APU control clocks such as length, envelope, and CH1 sweep must remain distinct from each channel's own fast waveform timer and from the host sample or resampler cadence.
 - Host-rate sample production should observe already-stepped hardware state; it must not become the clock that drives the APU core.
 - When cartridge hardware uses wall-clock-like progression outside powered-on execution, such as battery-backed `MBC3` RTC advance between sessions, model that through an explicit elapsed-time source at the persistence boundary and restate any powered-on bus-visible timing rule in T-cycles when it becomes behaviorally relevant.
+- Timer, joypad, serial, and the APU frame sequencer must not be tied to video-frame or VBlank callbacks; they live on the shared machine timeline even when their visible effects are unrelated to the LCD.
+- Bus restrictions and MMIO-visible state must tell one coherent story on that timeline. For example, `STAT.mode`, VRAM/OAM accessibility, DMA blocking, `SC.7`, `TIMA/TMA/IF`, and visible `JOYP` state must align with the same current-cycle machine state the scheduler uses internally.