C64-dev/newLang/planning/claims/E01-S03.md

---

story: E01-S03 owner: e01_kernal_wrapper status: done started: 2026-11-07 depends-on: [E01-S02]

E01-S03 Claim

Intended change

Create an isolated C128 probe containing a reusable KERNAL call wrapper. From two compiler mappings (bank 0 and bank 1 RAM with 8K bottom common), the wrapper enters the KERNAL in the BASIC/KERNAL default mapping, passes A/X/Y in, returns A/X/Y/C out, and restores the exact compiler MMU state. The probe uses it for CHROUT, a drive-8 status read, and a device-not-present failure path.

File area

• src/platform/kernal-probe.s
• cfg/kernal-probe-c128.cfg
• scripts/build-kernal-probe.ps1
• scripts/verify-kernal-probe.ps1
• monitor/kernal-probe-*.txt
• docs/kernal-wrapper.md
• planning/claims/E01-S03.md
• generated files under build/

Acceptance evidence

• Character output and a disk-status call work from both compiler bank states (CHROUT lines visible; drive 8 returns 00, OK,00,00 from both).
• MMU state before and after each wrapper is identical (CR/RCR/P0/P1 compared after every call; $4000 bank marker intact).
• Carry/status and error values survive the wrapper contract (CHKIN on device 30: C=1, A=5, READST $80 in both states; carry-drop mutation is detected).
• Open channels are closed on success and failure (LDTND = 0 after both paths in both states).

Coordination notes

Builds on E01-S02 facts in docs/mmu-probe.md. Does not create mmu.s or the final compiler map; those belong to E01-S05 and later compiler stories.

Work log

• First layout overflowed the 8K common window by ~15 bytes; replaced the 13-byte KCALL macro with an inline-word call form (kcall_inline).
• Verifier autostarts a fresh D64 through a true-emulation 1541 and polls the completion byte, since true-drive load time varies.
• Monitor screenshot captured the black VDC window; switched to -exitscreenshotvicii.
• Observed that OPEN with no filename sends nothing, so device-not-present surfaces at CHKIN.
• Negative control: AND #$FB -> AND #$FA in the flag merge yields state results $EF and a failing verifier; source restored afterwards.

Completion

• Tests run: scripts/verify-kernal-probe.ps1 (three passing runs plus one mutation run); scripts/verify-mmu-probe.ps1; tests/grammar/validate.ps1.
• Results: result $FF, state results $FF/$FF, fail A $05/$05, READST $80/$80, status 00, OK,00,00 from both banks; screenshot shows NOVA128 KERNAL PROBE OK; regressions pass.
• Files changed: src/platform/kernal-probe.s, cfg/kernal-probe-c128.cfg, scripts/build-kernal-probe.ps1, scripts/verify-kernal-probe.ps1, monitor/kernal-probe-trace.txt, docs/kernal-wrapper.md, docs/architecture.md section 4.2, this claim.
• Remaining risks: unmaskable RESTORE NMI under bank 1 is untested (E01-S05); only a 1541 on device 8 tested, no burst/fast serial; the probe spans $1C01-$1FFA, 1018 of the 1023 bytes below $2000, so the real compiler must keep only wrappers and shared state in common RAM; VICE-only evidence.