feat: close phase 0 infrastructure baseline (#1)

* feat: close phase 0 infrastructure baseline

* ci: speed up tooling checks and enforce local verification

Author: pakitovic

.cargo/config.toml

@@ -3,6 +3,7 @@ fmt-check = "fmt --all --check"
 lint = "clippy --workspace --all-targets -- -D warnings"
 tests = "test --workspace"
 cov = "llvm-cov --workspace --summary-only"
+cov-check = "llvm-cov -p gb-core -p gb-test-runner --summary-only --fail-under-lines 90 --fail-under-regions 90 --fail-under-functions 90"
 cov-html = "llvm-cov --workspace --html"
 cov-lcov = "llvm-cov --workspace --lcov --output-path lcov.info"
 deny-check = "deny check"

.githooks/pre-push

@@ -1,4 +1,4 @@
 #!/usr/bin/env sh
 set -eu
 
-cargo tests
+make check

.github/workflows/ci.yml

@@ -18,11 +18,23 @@ jobs:
         with:
           components: rustfmt, clippy, llvm-tools
 
-      - name: Install cargo tools
-        run: |
-          cargo install --locked cargo-llvm-cov
-          cargo install --locked cargo-deny
-          cargo install --locked typos-cli
+      - name: Cache Rust artifacts
+        uses: Swatinem/rust-cache@v2
+
+      - name: Install cargo-llvm-cov
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-llvm-cov
+
+      - name: Install cargo-deny
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-deny
+
+      - name: Install typos-cli
+        uses: taiki-e/install-action@v2
+        with:
+          tool: typos-cli
 
       - name: Rustfmt
         run: cargo fmt-check

AI/ARCHITECTURE.md

@@ -324,6 +324,9 @@ to immediately materialize as a separate directory.
 - watchpoints
 - snapshots
 - state inspection
+- freeze typed breakpoint/watchpoint target categories early enough that `PC`,
+  memory, MMIO, and cartridge-visible state do not need a public API redesign
+  once CPU and bus hooks become real
 - targeted subsystem viewers or equivalent structured dumps for CPU, scheduler, PPU, DMA, APU, IRQ, and cartridge state
 - internal analysis and comparison tools
 - utilities for synchronization and trace-debug workflows

AI/ROADMAP.md

@@ -276,6 +276,13 @@ Boundary note: Phase `0` fixes architecture, tracing, and the scheduler
 skeleton. Phase `1` is where that skeleton becomes hardware-visible stepping,
 arbitration, MMIO, and startup behavior.
 
+Status note (`2026-03-15`): Phase `0` baseline is closed in the current repo.
+The project now has the documented test layout, `gb-test-runner` contract
+crate, typed debugger breakpoints/watchpoints, `Machine` plus
+`step_t_cycle()`, explicit scheduler phases, stubbed subsystem boundaries,
+typed debug snapshots, and deterministic scheduler-aligned subsystem trace
+hooks. Remaining work moves to Phase `1`.
+
 ---
 
 ### Phase 1 — Temporal foundation and hardware access

AI/TESTING.md

@@ -49,6 +49,7 @@ Every subsystem change should aim to leave behind one of these:
 - The harness should support at least framebuffer capture and serial / link-port capture when the ROM exposes machine-readable output there.
 - Prefer serial / link-port capture for suites such as Blargg `cpu_instrs` when that path is available, because it avoids treating a scrolling framebuffer as the primary machine-readable result channel.
 - Each ROM case should define a timeout, an explicit pass/fail rule, and retained failure artifacts such as serial output, framebuffer output, trace excerpts, and optional snapshots.
+- During early Phase `0`, `gb-test-runner` may still be a contract-only crate, but it should already own typed ROM-case and suite metadata including console model, startup mode, execution mode, emulation-progress timeout, explicit pass/fail rule, requested captures, and retained failure-artifact policy.
 - The minimum DMG closure baseline should include automated CPU / interrupt coverage through `retrio/gb-test-roms` or equivalent Blargg automation, `dmg-acid2` for basic DMG PPU validation, and `mealybug-tearoom-tests` for fine PPU rendering / timing validation.
 - Keep explicit roadmap space for broader closure suites such as Mooneye / Gekkio coverage, SameSuite, GB Accuracy Tests, 144p Test Suite, and MBC3 RTC-focused ROMs.
 
@@ -83,9 +84,30 @@ Every subsystem change should aim to leave behind one of these:
 - New production code should normally introduce automated unit tests or integration tests in the same change.
 - Prefer unit tests for local logic and integration tests when the behavior only becomes meaningful across subsystem boundaries.
 - Treat "code first, tests later" as an exception that must be justified explicitly, not as the default workflow.
+- Before opening or updating a pull request, run at least `make check` locally so formatting, clippy, tests, typos, and `cargo deny` failures do not first surface in CI.
+- When a change touches CI, coverage, dependency policy, repo tooling, or other workflow-critical infrastructure, run `make ci` locally as well before the PR is updated.
+- For the current infrastructure-heavy stage, keep `gb-core` and `gb-test-runner` at or above `90%` line, region, and function coverage as a guardrail, but do not satisfy that threshold with hollow tests that only exercise trivial getters or app placeholders.
 - When immediate automated coverage is temporarily impractical, record the missing test coverage, the reason it is deferred, and the remaining risk in the change report; add a roadmap TODO as well if the gap is concrete and non-trivial.
 - ROM-based validation and oracle comparison complement automated tests; they do not replace the expectation that new code should usually leave behind unit or integration coverage.
 
+## Phase 0 baseline test layout
+
+- Until dedicated tooling such as `gb-test-runner` exists, keep the initial automated-validation baseline inside `crates/gb-core`.
+- Keep subsystem-local invariant tests close to the production code under `crates/gb-core/src/**`.
+- Keep public-API and cross-module smoke coverage under `crates/gb-core/tests/*.rs`.
+- Keep shared integration-test helpers under `crates/gb-core/tests/common/`.
+- Reserve `crates/gb-core/tests/fixtures/roms/` for ROM fixtures and synthetic cartridge images used by automated harnesses.
+- Reserve `crates/gb-core/tests/fixtures/traces/` for golden trace artifacts and other debugger-facing snapshots.
+- During early Phase `0`, prefer stable UTF-8 text trace fixtures with explicit `seq=`, `subsystem=`, `level=`, and quoted `message=` fields so ordering regressions can be locked down before richer scheduler-visible traces exist.
+- During early Phase `0`, cover `ConsoleModel`, `StartupMode`, `ExecutionMode`, and `CompatibilityPolicy` defaults explicitly so DMG-first behavior and future CGB extension seams remain stable before scheduler and loader work land.
+- During early Phase `0`, cover `SchedulerPhase` order, the global T-cycle counter, and `CycleContext` reset semantics explicitly so later subsystem work cannot smuggle timing assumptions in through accidental call order.
+- During early Phase `0`, cover the single top-level `step_t_cycle()` machine entry point explicitly so the core keeps one deterministic timing boundary instead of growing multiple unsynchronized stepping APIs.
+- During early Phase `0`, cover subsystem-boundary wiring explicitly so `Machine` ownership of CPU, bus, PPU, DMA, timer, boot, and cartridge remains stable before Phase `1` introduces hardware-visible behavior.
+- During early Phase `0`, lock one deterministic trace order for stubbed CPU, bus, PPU, DMA, timer, boot, and cartridge hooks relative to scheduler phases so later subsystem implementation can grow observability without silently redefining trace chronology.
+- During early Phase `0`, expose typed breakpoint and watchpoint contracts for `PC`, memory, MMIO, and cartridge-visible state even before CPU and bus evaluation hooks are fully wired, so debugger tooling can grow without redefining its public targets later.
+- During early Phase `0`, treat debugger snapshots as typed inspection artifacts only; lock their contents with tests, but keep them explicitly separate from the whole-machine save-state work reserved for Phase `8`.
+- Keep the Phase `0` baseline fast, deterministic, and frontend-independent; `gb-core` validation must not require `gb-cli`, desktop, web, or host-specific I/O.
+
 ## ROM-based validation policy
 
 Map tests to the subsystem they validate:

Cargo.lock

@@ -1,3 +1,3 @@
 [workspace]
-members = ["crates/gb-core", "crates/gb-cli"]
+members = ["crates/gb-core", "crates/gb-test-runner", "crates/gb-cli"]
 resolver = "2"

Cargo.toml

@@ -1,13 +1,14 @@
-.PHONY: help setup hooks tools typos check ci
+.PHONY: help setup hooks tools typos check ci cov-check
 
 help:
 	@echo "Available targets:"
 	@echo "  make setup  - Configure project environment and install local cargo tools"
 	@echo "  make hooks  - Configure git hooks path to .githooks"
 	@echo "  make tools  - Install local cargo tools used by this repository"
 	@echo "  make typos  - Run typos spellcheck"
-	@echo "  make check  - Run local checks (fmt, clippy, test, typos, deny)"
-	@echo "  make ci     - Run CI-like pipeline locally including LCOV coverage"
+	@echo "  make check  - Run the required local checks before push/PR (fmt, clippy, test, typos, deny)"
+	@echo "  make ci     - Run the full CI-like pipeline locally including coverage artifacts"
+	@echo "  make cov-check - Enforce >=90% coverage on gb-core and gb-test-runner"
 
 setup: hooks tools
 
@@ -32,4 +33,8 @@ check:
 	cargo deny-check
 
 ci: check
+	cargo cov-check
 	cargo cov-lcov
+
+cov-check:
+	cargo cov-check

Makefile

@@ -24,6 +24,7 @@ The current workspace already uses the `crates/`-based layout, leaving other com
 ```text
 crates/
   gb-core/    Pure emulation logic
+  gb-test-runner/  Typed ROM-harness contracts and validation helpers
   gb-cli/     Current CLI frontend
 AI/           Architecture, roadmap, and technical documentation
 Makefile      Local verification pipeline and utilities
@@ -33,7 +34,7 @@ Mid-term planned extensions, not yet materialized as separate crates:
 
 - `gb-desktop`
 - `gb-web`
-- additional tooling such as a test runner, debugger, and utilities
+- additional tooling such as richer debugger and utilities
 - host persistence/save adapters outside the core, with any cartridge-facing persistence contract kept narrow and typed inside `gb-core`
 - broader integration tests and ROM suites
 
@@ -68,6 +69,7 @@ make setup
 
 ```bash
 cargo cov
+cargo cov-check
 cargo cov-html
 cargo cov-lcov
 ```
@@ -79,6 +81,9 @@ make check
 make ci
 ```
 
+Before opening or updating a PR, run at least `make check` locally.
+When changing CI, coverage, dependency policy, or repository tooling, run `make ci` locally as well so failures such as `cargo deny` do not first appear in GitHub Actions.
+
 
 ## Documentation