theory StarForth_Keyboard_Words
  imports StarForth_Base
begin

(* =========================================================================
   Mirrors: src/word_source/keyboard_words.c
   Registers: KBD-SCAN KBD-DEBUG VKBD-EVENT VKBD-DEBUG KEY-EVENT ALT+TAB

   Part of the Stadium console fabric work (FABRIC.md items 4.3.5/4.4v/
   4.4y). All six words are registered UNCONDITIONALLY regardless of
   build/arch, but every body is gated on `__STARKERNEL__` (and, for the
   amd64-specific/riscv64-aarch64-specific pairs, the target architecture
   too). Outside the matching kernel+arch combination, every one of these
   six falls through to a fixed, hardware-independent fallback --
   identically to framebuffer_words.c, and reachable the same way (a
   plain hosted `make` build).

   ── Scope ─────────────────────────────────────────────────────────────
   The fallback (non-kernel-or-wrong-arch) behaviour of all six words is
   fully modelled: every one reduces to a fixed constant push (or, for
   ALT+TAB, a true no-op). CORRECTED 2026-08-14: all six push via C's
   `vm_push()` (src/stack_management.c:75), which bounds-checks internally
   -- the earlier "no capacity guard" claim here was a gap in this theory's
   abstract push model, not a real defect in the C; see proof/FINDINGS.md
   §2. The real (matching kernel+arch) hardware-polling bodies are NOT
   modelled: i8042_pop_scancode/virtio_input_pop_event/
   console_fb_toggle_graphics are all raw hardware/interrupt-state reads
   with no vm_state counterpart, the same class of gap as every other
   hardware-boundary word in this console-fabric group. `sk_key_event_poll`
   is a small pure function (bit 7 of an XT scancode byte / a virtio-input
   value field, both external to vm_state either way) -- its fallback
   branch (`return 0`) is what's modelled here as part of KEY-EVENT's
   fallback; its two hardware branches are not.
   ======================================================================== *)

(* ── KBD-SCAN ( -- c -1 | 0 ) : fallback pushes 0 ────────────────────────── *)

definition forth_kbd_scan_fallback :: "vm_state \<Rightarrow> vm_state" where
  "forth_kbd_scan_fallback vm = vm\<lparr>data_stack := 0 # data_stack vm\<rparr>"

lemma kbd_scan_fallback_pushes_zero:
  "data_stack (forth_kbd_scan_fallback vm) = 0 # data_stack vm"
  by (simp add: forth_kbd_scan_fallback_def)

(* ── KBD-DEBUG ( -- isr_count spurious_count ) : fallback pushes 0 0 ─────── *)

definition forth_kbd_debug_fallback :: "vm_state \<Rightarrow> vm_state" where
  "forth_kbd_debug_fallback vm = vm\<lparr>data_stack := 0 # 0 # data_stack vm\<rparr>"

lemma kbd_debug_fallback_pushes_zeros:
  "data_stack (forth_kbd_debug_fallback vm) = 0 # 0 # data_stack vm"
  by (simp add: forth_kbd_debug_fallback_def)

(* ── VKBD-EVENT ( -- code value -1 | 0 ) : fallback pushes 0 ────────────── *)

definition forth_vkbd_event_fallback :: "vm_state \<Rightarrow> vm_state" where
  "forth_vkbd_event_fallback vm = vm\<lparr>data_stack := 0 # data_stack vm\<rparr>"

lemma vkbd_event_fallback_pushes_zero:
  "data_stack (forth_vkbd_event_fallback vm) = 0 # data_stack vm"
  by (simp add: forth_vkbd_event_fallback_def)

(* ── VKBD-DEBUG ( -- isr_count ) : fallback pushes 0 ─────────────────────── *)

definition forth_vkbd_debug_fallback :: "vm_state \<Rightarrow> vm_state" where
  "forth_vkbd_debug_fallback vm = vm\<lparr>data_stack := 0 # data_stack vm\<rparr>"

lemma vkbd_debug_fallback_pushes_zero:
  "data_stack (forth_vkbd_debug_fallback vm) = 0 # data_stack vm"
  by (simp add: forth_vkbd_debug_fallback_def)

(* ── KEY-EVENT ( -- keycode pressed -1 | 0 ) : fallback pushes 0 ────────── *)
(* sk_key_event_poll's fallback branch (neither ARCH_AMD64 nor riscv64/
   aarch64 under __STARKERNEL__) returns 0 without touching its out-params;
   kbw_key_event's `else` branch then pushes a single 0. *)

definition forth_key_event_fallback :: "vm_state \<Rightarrow> vm_state" where
  "forth_key_event_fallback vm = vm\<lparr>data_stack := 0 # data_stack vm\<rparr>"

lemma key_event_fallback_pushes_zero:
  "data_stack (forth_key_event_fallback vm) = 0 # data_stack vm"
  by (simp add: forth_key_event_fallback_def)

(* ── ALT+TAB ( -- ) : fallback is a true no-op ───────────────────────────── *)

definition forth_alt_tab_fallback :: "vm_state \<Rightarrow> vm_state" where
  "forth_alt_tab_fallback vm = vm"

lemma alt_tab_fallback_identity: "forth_alt_tab_fallback vm = vm"
  by (simp add: forth_alt_tab_fallback_def)

lemma alt_tab_kernel_not_modelled: True
  \<comment> \<open>Kernel build: console_fb_toggle_graphics() -- console/framebuffer
     mode-toggle state, no vm_state counterpart.\<close>
  by simp

lemma keyboard_kernel_bodies_not_modelled: True
  \<comment> \<open>All five hardware-polling words' real (kernel+matching-arch) bodies
     -- i8042_pop_scancode/virtio_input_pop_event and their associated ISR
     counters (g_i8042_isr_count/g_spurious_count/g_virtio_input_isr_count,
     themselves file-scope C statics/externs) -- are not modelled. Same
     class of gap as every hardware-boundary word in this group.\<close>
  by simp

end