# Plan 1 outcome — VT1200 board register model

Plan: `docs/superpowers/plans/2026-10-16-vt1200-board-model.md`
Spec: `docs/superpowers/specs/2026-10-16-vt1200-board-model-design.md`
Commits: `acb92d3e44ec..e23dadcfd4de` (7 commits)
Status: **all 4 tasks complete, final whole-branch review clean after one documentation-only fix wave.**

This file is the durable record; the SDD workspace was deleted after review, as the process
requires, with git history as the record.

## What was delivered

| Commit | What |
|---|---|
| `43f69738f405` | board register model extracted into a **MAME-free, unit-tested** class (`vt1200_board.h/.cpp`, `test_vt1200_board.cpp`); driver forwards to it |
| `db2caa555803` | fix round 1: switch knob made unambiguous (`0x70` raw bits vs position) and non-silent |
| `66fe15367b90` | per-window busy state machines |
| `a2f19b2d29a4` | the `0x5800000`/`0x5900000` DMA command/data pair |
| `2d7747a20d48` | configurable timings + the timing sweep and its honest findings |
| `8e18d81cef07` | fix round 1: verbatim sweep/differential/INTENB evidence into the tracked log |
| `e23dadcfd4de` | fix wave: documentation corrections (four windows, real callback trap, guessed DMA timing) |

Guarantees that hold: **no regression** — with no `VT1200_*` env vars set the driver still
reproduces the original wedge `PC=3FDCE400 samples=199`, argued structurally as well as
measured; 9 unit tests pass and the model compiles standalone with plain `g++`.

## The experiment's real result (negative, and valuable)

* The timing sweep is **flat**: `BUSY_W2` in `{1,2,4,8}` all give `total_distinct=59`. The
  reason is structural — `tick()` advances **once per emulated frame**, so busy durations of
  1/2/4/8 ticks are indistinguishable. Duration is the wrong axis.
* **The critical handshake is isolated to `0x06200000` (WIN2):**
  `BUSY_TICKS=0` -> stuck `PC=3FDCE400` (5 PCs); `BUSY_TICKS=0 BUSY_W2=1` -> 56 PCs at
  `PC=3F208950`; `BUSY_TICKS=0 BUSY_W3=1` -> still stuck.
* **`INTENB` never becomes non-zero** across 900 frames (`INTPEND=0400` throughout), so the
  level-0 interrupt boundary is still not crossed.

## Rulings I made (all of them, in order)

1. **Initialised a git repository in the project.** The directory was not under version
   control and the process needs an isolated tree plus per-task commits. A strict
   `.gitignore` excludes generated artifacts (160 MB AVI, RAM dumps, traces, core files,
   nested clones). *Cost if wrong:* a `.git` the user does not want; reversible with
   `rm -rf .git`.
2. **Pinned the `tick()` call site to the scanline callback**, guarded on
   `scanline == screen.visible_area().max_y`. The plan left it ambiguous and the
   `screen_update` alternative is wrong (it fires in small clip regions). *Cost if wrong:*
   busy machines advance at the wrong rate; one call site.
3. **Model policy: DeepSeek V4.1 (`deepseek/deepseek-flash`) preferred over V4**, per user
   guidance; `high` variant for implementers/reviewers, `max` for the final review. *Cost if
   wrong:* a task or two on a weaker model, with review coverage.
4. **Ran the memory-space investigation as a spike, not a plan**, with full Ghidra access —
   output is an answer plus durable artefacts, not product code. *Cost if wrong:* one
   worker's time; deliverables additive and write-isolated.
5. **Resumed Task 1's implementer on a different model for its fix round** (V4.1 vs its
   V4 Pro dispatch), keeping session context. *Cost if wrong:* none observed — the
   re-review found no new breakage.
6. **Treated the spike's VRAM finding as inference, not proof**, so the video plan's first
   task is an *empirical* determination (watchpoint `DPYADR`), not a static one. *Cost if
   wrong:* one wasted probe.
7. **Task 4's flat sweep stands as a successful outcome.** No improvement was claimed and
   none was fabricated; the negative result is the deliverable.

## Reviewer findings triaged as acceptable (not fixed, deliberately)

Thirteen minors were raised across the four tasks; the final review triaged them and
required only the three documentation corrections (now fixed). The rest were judged
acceptable: write-back latches on non-handshake reads; the handshake matching only the low
16 bits; `m_busy_ticks` default 2 -> 0; assorted test-coverage gaps; the unmasked key in
`set_window_busy_ticks`; the DMA defaults-off gate being untested; a WIN1 read ignoring the
register offset (inert while DMA defaults off); and cosmetic diagnostic wording.

**Two worth acting on before the next modelling round** (the reviewer's words): mask the
key in `set_window_busy_ticks`, and offset-gate the WIN1 DMA read so a WIN1 status bit is
not shadowed.

## Where the goal stands

This plan deliberately delivered only its slice. `INTENB` still never leaves zero and no
frame has been rendered — the spec's success criteria 2 and 3 remain open, to be met by the
two named follow-on plans: **video RAM + scanline renderer**, and **DUART / NVRAM / MAC ROM**.

The spike (`reference/memory-space-map.md`) plus this plan's findings tell the video plan
where to start: the framebuffer is not in main RAM, it is set at runtime via `DPYADR`, and
the most-touched unmodelled region is `0x5600000` (~110 accesses on the display/X-init path).