`nx_emu_uefi.nx` source

↩ module page · 1368 lines · 76880 B
1// nx_emu_uefi.nx -- the sovereign UEFI EXECUTION-PROOF harness (NOS execution gate).
2//
3// A purpose-built minimal x86-64 interpreter WITH a flat memory model + stack + a hooked
4// UEFI SystemTable, just enough to EXECUTE the entry of an emitted nx_boot_uefi*.efi and
5// PROVE it does what it claims -- the in-house analog of running the RV64 boot stub on
6// rv64im_min_sim (no qemu, no real laptop).  It sets up a mock SystemTable/ConOut whose
7// OutputString is a sentinel HOOK; when the executed code calls it, we CAPTURE the UTF-16
8// string it asked to print.  A correct nx_boot_uefi prints "NISHI"; the buggy off-by-one
9// variant would capture garbage -- so this is a real gate, not a structural rubber-stamp.
10//
11// Memory is the flat image space with ImageBase=0: .text loaded at its RVA (0x1000), so
12// RIP-relative leas resolve to the real string RVAs.  Mock UEFI placed elsewhere in MEM.
13//
14// Decoded forms (exactly what the nx_boot_uefi* / nx_gop_efi emitters produce):
15//   50+r push r64 | 58+r pop r64 | C3 ret | 31 /r xor r/m,r (reg-direct)
16//   48 83 grp1 (add/sub/and/cmp imm8) | 48 C7 mov r64,imm32 | 48 C1/D3 shr | 48 01/29/39 add/sub/cmp
17//   48 31 /r xor r64,r64 (reg-direct) | 48 89 /r mov store | 48 8B /r mov load (disp8/SIB+disp8/disp32/reg)
18//   48 8D lea [rip+disp32] (mod00) or [SIB-base+disp8] (mod01) | B8+rd mov r32,imm32 (zero-extended)
19//   FC cld | F3 AB rep stosd (one interpreter step, bounds-refused -34)
20//   FF /2 call [base+disp8] (mod01) or call r64 (mod11) -- HOOK-aware
21//   EB FE jmp $ -> distinct HOLD return: a painting app KEEPS the screen; the verdict is then
22//     decided by MEASURING the modeled framebuffer (color read from the artifact, never assumed):
23//     nonzero color AND 100% fill -> PAINTED-AND-HOLDING, anything less -> RED.
24// Mock UEFI hooks: ConOut->OutputString (capture) | BootServices->GetMemoryMap (writes 0x1800) |
25//   BootServices->LocateProtocol (GUID-CHECKED: only the GOP GUID is served, wrong GUID -> -33)
26//   -> modeled GOP: gop->Mode->FrameBufferBase/Size = a real 1280x800x32 in-MEM framebuffer
27//      (mirrors the OVMF oracle mode, so sovereign + foreign engines judge the same geometry).
28// Usage: nx_emu_uefi <path.efi> [expect-prefix] | nx_emu_uefi selftest   (4 teeth incl. negative controls)
29// Gate: captured console output begins "NISHI" -> GREEN.  Log -> knowledge/status/nishi_os.log
30// Sovereign: syscalls only, no gcc/qemu/.sh.  license_tier: ORIGINAL
31import "nx_syscalls.nx"
32const RET_MAGIC_200000: i64 = 200000
33
34const MEMSZ:        i64 = 0x800000    // raised for AI2: the served AI blob sits above the kernel window
35const HOOK:         i64 = 0x9000
36const RET_SENTINEL: i64 = 0xC0DE
37const ST_ADDR:      i64 = 0x4000
38const CO_ADDR:      i64 = 0x4800
39const FV_ADDR:      i64 = 0x4900
40const STACK_TOP:    i64 = 0x20000  // RAISED: the loader's virtual image (code + reserves) now ends
                                 // near 0x8DC0, and a stack growing down from 0x8000 would have
                                 // grown straight into the assistant reserve. A stack that shares
                                 // an address with the data it is loading is the modelled-
                                 // peripheral bug wearing different clothes -- moved, not shrunk.
45const BS_ADDR:      i64 = 0x4C00
46const HOOK2:        i64 = 0x9100
47const HOOK3:        i64 = 0x9200
48const HOOK4:        i64 = 0x9300
49const HOOK5:        i64 = 0x9400
50const CI_ADDR:      i64 = 0x4A00
51const KEYQ_ADDR:    i64 = 0x4B00
52const EFI_NOT_READY: i64 = 6
53const EFI_NOT_FOUND: i64 = 14         // what real firmware returns for a file that is not there --
                                    // the ABSENT assistant file must look exactly like this
55const EFI_INVALID_PARAM: i64 = 2
56const EFI_BUFFER_TOO_SMALL: i64 = 5
57// N4: the firmware handoff is modeled with REAL protocol teeth, not a rubber stamp --
58// GetMemoryMap is a genuine two-call sequence and ExitBootServices REFUSES a stale MapKey,
59// which is the classic UEFI mistake. EBS_STATE tracks whether firmware has been surrendered;
60// after that, every firmware service must FAIL, because that is what real hardware does.
61const MM_REQ_BYTES: i64 = 0x1800      // DEFAULT modeled map size (see MM_SIZE_SLOT -- this is a
                                    // MODEL, not a measurement: real EDK2 returned 0x18F0 on the
                                    // same payload, debt 1786237098. A rung that asserts an exact
                                    // ram-map size against this organ is asserting THIS CONSTANT.)
65const MM_SIZE_SLOT: i64 = 0x4D10      // caller-settable via --mmsize; 0 = unset -> MM_REQ_BYTES.
                                    // Lives in MEM (not a global) so the selftest fixtures, which
                                    // mmap fresh zeroed memory, keep the default BY CONSTRUCTION.
68const MM_DESC_SIZE: i64 = 0x30        // EFI_MEMORY_DESCRIPTOR stride
69const MM_MAPKEY:    i64 = 0x5AFEC0DE  // the key a SUCCESSFUL GetMemoryMap issues
70const EBS_STATE:    i64 = 0x4D00      // [0]=exited?  [8]=issued map key
71// N1-full: model the UEFI file-read chain the shim must use to load its OWN kernel off the ESP.
72// Every step is GUID- or handle-checked so a wrong protocol is REFUSED rather than served.
73const HOOK6:        i64 = 0x9500      // BootServices->HandleProtocol
74const HOOK7:        i64 = 0x9600      // SimpleFileSystem->OpenVolume
75const HOOK8:        i64 = 0x9700      // File->Open
76const HOOK9:        i64 = 0x9800      // File->Read
77// FS-2: BootServices->LocateHandleBuffer. The loader must stop ASSUMING the optional file is on the
78// volume it booted from and start SEARCHING every filesystem the firmware knows about. The model
79// therefore serves TWO volumes and puts the assistant file ONLY on the second one -- a loader that
80// checks just its own volume fails this harness by construction, which is the whole point.
81const HOOK10:       i64 = 0x9900      // BootServices->LocateHandleBuffer (BS + 0x138)
82const DEV2_HANDLE:  i64 = 0x501100    // the DATA partition's device handle
83const FS2_ADDR:     i64 = 0x502100    // its EFI_SIMPLE_FILE_SYSTEM
84const ROOT2_ADDR:   i64 = 0x503100    // its root EFI_FILE
85const HBUF_ADDR:    i64 = 0x509000    // the handle array firmware hands back
86const HCNT_ADDR:    i64 = 0x50A000    // and its count
87// ⚠These MUST live outside the guest image. First placement (0x5200-0x5700) landed INSIDE the
88// loaded .text -- directly on the embedded KERNEL.NXE at 0x5280 -- so wiring the vtables silently
89// corrupted the payload, its checksum failed, and the shim took its refusal path to a black
90// screen. ★★★★★A MODELED PERIPHERAL PLACED INSIDE THE GUEST'S ADDRESS SPACE IS NOT A PERIPHERAL,
91// IT IS MEMORY CORRUPTION WEARING A DEVICE'S NAME. Image ~0x1000-0x6400, framebuffer to 0x4E8000.
92const LI_ADDR:      i64 = 0x500000    // EFI_LOADED_IMAGE_PROTOCOL  (+0x18 DeviceHandle)
93const DEV_HANDLE:   i64 = 0x501000    // the ESP device handle we hand back
94const FS_ADDR:      i64 = 0x502000    // EFI_SIMPLE_FILE_SYSTEM      (+0x08 OpenVolume)
95const ROOT_ADDR:    i64 = 0x503000    // root EFI_FILE_PROTOCOL      (+0x08 Open)
96const FILE_ADDR:    i64 = 0x504000    // opened EFI_FILE_PROTOCOL    (+0x20 Read)
97const KFILE_LEN:    i64 = 0x505000    // [0] = served file length
98const KFILE_DATA:   i64 = 0x580000
99// AI2: the OPTIONAL assistant file is a SECOND named file on the same modeled ESP. Modeling it as a
100// distinct handle+buffer (not a second read of the same one) is what lets Open() be NAME-AWARE, which
101// is the only way the harness can exercise "the file is absent" -- the default state of the toggle.
102const AIFILE_ADDR:  i64 = 0x507000    // opened EFI_FILE_PROTOCOL for the AI blob
103const AIFILE_LEN:   i64 = 0x508000    // [0] = served AI blob length (0 = ABSENT, Open must refuse)
104const AIFILE_DATA:  i64 = 0x600000    // served AI bytes (above the kernel window, inside MEMSZ)
105// HW1 (A16 spore): a modeled PCI config-space window. CONFIG_ADDRESS (0xCF8) is a SELECTOR --
106// writing it chooses which register a subsequent read returns, and changes no device state.
107// CONFIG_DATA (0xCFC) is READ ONLY here: a write to it would mutate a device's configuration,
108// so it is refused by construction. That is the whole never-brick rule for bus enumeration.
109const PCI_ADDR_PORT: i64 = 0xCF8
110const PCI_DATA_PORT: i64 = 0xCFC
111const PCI_LATCH:     i64 = 0x506000   // last value written to CONFIG_ADDRESS
112const PCI_NDEV:      i64 = 3          // modeled devices on bus 0, functions 0    // served file bytes (well clear of the framebuffer)
113// N4b: a modeled PS/2 controller. After ExitBootServices there is no ConIn, so a real OS talks
114// to the 8042 directly: port 0x64 is status (bit0 = a byte is waiting), port 0x60 is the data
115// register. Both are READS -- nothing here writes hardware state.
116const PS2_STATE:    i64 = 0x4E00      // [0]=count [8]=index [16+8i]=scancodes
117const PS2_PORT_STATUS: i64 = 0x64
118const PS2_PORT_DATA:   i64 = 0x60
119const GOP_ADDR:     i64 = 0x5000
120const MODE_ADDR:    i64 = 0x5100
121const FB_ADDR:      i64 = 0x100000
122const FB_SIZE:      i64 = 0x3E8000
123const FB_W_PIX:     i64 = 1280
124const FB_H_PIX:     i64 = 800
125
126// reg indices: 0 rax 1 rcx 2 rdx 3 rbx 4 rsp 5 rbp 6 rsi 7 rdi
127const R_RAX: i64 = 0
128const R_RCX: i64 = 1
129const R_RDX: i64 = 2
130const R_RSP: i64 = 4
131const R_RDI: i64 = 7
132
133// ===== flat-memory access ========================================================
134func m_r8(mem: *u8, a: i64) -> i64 { return mem[a] as i64 }
135func m_r64(mem: *u8, a: i64) -> i64 {
  var v: i64 = 0; var i: i64 = 0
  while i < 8 { v = v | ((mem[a + i] as i64) << (8 * i)); i = i + 1 }
  return v
139}
140func m_w64(mem: *u8, a: i64, v: i64) -> i64 {
  var i: i64 = 0
  while i < 8 { mem[a + i] = ((v >> (8 * i)) & 0xff) as u8; i = i + 1 }
  return 0
144}
145func m_w16(mem: *u8, a: i64, v: i64) -> i64 {
  mem[a] = (v & 0xff) as u8; mem[a + 1] = ((v >> 8) & 0xff) as u8; return 0
147}
148// little-endian imm32, sign-extended (operands live in MEM alongside code)
149func m_i32(mem: *u8, off: i64) -> i64 {
  var v: i64 = (mem[off] as i64) | ((mem[off+1] as i64) << 8) | ((mem[off+2] as i64) << 16) | ((mem[off+3] as i64) << 24)
  if (v & 0x80000000) != 0 { v = v - (1 << 32) }
  return v
153}
154// unsigned 32 from a file buffer (PE header fields)
155func f_u32(fb: *u8, off: i64) -> i64 {
  return (fb[off] as i64) | ((fb[off+1] as i64) << 8) | ((fb[off+2] as i64) << 16) | ((fb[off+3] as i64) << 24)
157}
158func sx8(b: i64) -> i64 { if b >= 128 { return b - 256 } return b }
159
160// capture the UTF-16LE string at mem[straddr] (low bytes) into out[]; return new outn
161func cap_str(mem: *u8, straddr: i64, out: *u8, outn: i64) -> i64 {
  var a: i64 = straddr; var n: i64 = outn; var go: i64 = 1
  while go == 1 {
      let lo: i64 = mem[a] as i64
      let hi: i64 = mem[a + 1] as i64
      if (lo | (hi << 8)) == 0 { go = 0 } else { out[n] = lo as u8; n = n + 1; a = a + 2 }
  }
  return n
169}
170
171// EFI_GRAPHICS_OUTPUT_PROTOCOL_GUID 9042a9de-23dc-4a38-96fb-7aded080516a (UEFI-spec bytes, mixed-endian).
172// Restated from the spec here so the reader never borrows the writer's table -- LocateProtocol REFUSES (-33)
173// any other GUID instead of handing out the modeled GOP for whatever is asked.
174// EFI_LOADED_IMAGE_PROTOCOL_GUID 5B1B31A1-9562-11d2-8E3F-00A0C969723B
175func li_guid_b(i: i64) -> i64 {
  if i==0 { return 0xA1 } if i==1 { return 0x31 } if i==2 { return 0x1B } if i==3 { return 0x5B }
  if i==4 { return 0x62 } if i==5 { return 0x95 } if i==6 { return 0xD2 } if i==7 { return 0x11 }
  if i==8 { return 0x8E } if i==9 { return 0x3F } if i==10 { return 0x00 } if i==11 { return 0xA0 }
  if i==12 { return 0xC9 } if i==13 { return 0x69 } if i==14 { return 0x72 } return 0x3B
180}
181// EFI_SIMPLE_FILE_SYSTEM_PROTOCOL_GUID 964E5B22-6459-11D2-8E39-00A0C969723B
182func fs_guid_b(i: i64) -> i64 {
  if i==0 { return 0x22 } if i==1 { return 0x5B } if i==2 { return 0x4E } if i==3 { return 0x96 }
  if i==4 { return 0x59 } if i==5 { return 0x64 } if i==6 { return 0xD2 } if i==7 { return 0x11 }
  if i==8 { return 0x8E } if i==9 { return 0x39 } if i==10 { return 0x00 } if i==11 { return 0xA0 }
  if i==12 { return 0xC9 } if i==13 { return 0x69 } if i==14 { return 0x72 } return 0x3B
187}
188// Compare the UTF-16LE filename at mem[at] against one of the two names this modeled ESP serves.
189// which: 0 = "KERNEL.NXE", 1 = "NISHI.AI". The table is restated here rather than shared with the
190// loader's table -- a reader that borrows the writer's bytes cannot catch the writer's typo.
191func esp_name_ch(which: i64, i: i64) -> i64 {
  if which == 0 {
      if i==0 { return 0x4B } if i==1 { return 0x45 } if i==2 { return 0x52 } if i==3 { return 0x4E }
      if i==4 { return 0x45 } if i==5 { return 0x4C } if i==6 { return 0x2E } if i==7 { return 0x4E }
      if i==8 { return 0x58 } if i==9 { return 0x45 } return 0
  }
  if i==0 { return 0x4E } if i==1 { return 0x49 } if i==2 { return 0x53 } if i==3 { return 0x48 }
  if i==4 { return 0x49 } if i==5 { return 0x2E } if i==6 { return 0x41 } if i==7 { return 0x49 }
  return 0
200}
201func u16_name_is(mem: *u8, at: i64, which: i64) -> i64 {
  var i: i64 = 0
  var go: i64 = 1
  while go == 1 {
      let want: i64 = esp_name_ch(which, i)
      let lo: i64 = mem[at + i * 2] as i64
      let hi: i64 = mem[at + i * 2 + 1] as i64
      if hi != 0 { return 0 }
      if lo != want { return 0 }
      if want == 0 { go = 0 }
      i = i + 1
  }
  return 1
214}
215func guid_eq(mem: *u8, at: i64, which: i64) -> i64 {
  var i: i64 = 0
  while i < 16 {
      var want: i64 = 0
      if which == 0 { want = li_guid_b(i) } else { want = fs_guid_b(i) }
      if (mem[at + i] as i64) != want { return 0 }
      i = i + 1
  }
  return 1
224}
225
226
227// The N1-full file-chain hooks, in ONE place so the selftest exercises exactly what the
228// interpreter runs. Returns 0 = handled OK, negative = refusal sentinel, 1 = not my hook.
229// The modeled bus: three devices at slots 0,1,2. Everything else reads back all-ones, which is
230// exactly how real hardware says "nothing here" -- so the kernel's enumeration must treat
231// 0xFFFFFFFF as absence rather than as a device, or it will invent hardware.
232func pci_cfg_read(latch: i64) -> i64 {
  if (latch & 0x80000000) == 0 { return 0xFFFFFFFF }      // enable bit clear
  let bus: i64 = (latch >> 16) & 0xFF
  let dev: i64 = (latch >> 11) & 0x1F
  let fun: i64 = (latch >> 8) & 0x07
  let off: i64 = latch & 0xFC
  if bus != 0 { return 0xFFFFFFFF }
  if fun != 0 { return 0xFFFFFFFF }
  if dev >= PCI_NDEV { return 0xFFFFFFFF }
  if off == 0 {
      if dev == 0 { return 0x12378086 }                   // host bridge   (vendor 8086)
      if dev == 1 { return 0x100E8086 }                   // network       (vendor 8086)
      return 0x00281AF4                                    // virtio block  (vendor 1AF4)
  }
  if off == 8 {
      if dev == 0 { return 0x06000001 }                   // class 06 bridge
      if dev == 1 { return 0x02000001 }                   // class 02 network
      return 0x01000001                                    // class 01 storage
  }
  return 0
252}
253
254func emu_hook_call(mem: *u8, tgt: i64, reg: *i64) -> i64 {
  if tgt == HOOK6 {                       // HandleProtocol(rcx=handle, rdx=&GUID, r8=&iface)
      if guid_eq(mem, reg[R_RDX], 0) == 1 {
          m_w64(mem, reg[8], LI_ADDR); reg[R_RAX] = 0; return 0
      }
      if guid_eq(mem, reg[R_RDX], 1) == 1 {
          // Two volumes now: the boot ESP and the DATA partition. Serve each its OWN filesystem,
          // and refuse anything else -- a handle we did not hand out must never resolve.
          if reg[R_RCX] == DEV_HANDLE { m_w64(mem, reg[8], FS_ADDR); reg[R_RAX] = 0; return 0 }
          if reg[R_RCX] == DEV2_HANDLE { m_w64(mem, reg[8], FS2_ADDR); reg[R_RAX] = 0; return 0 }
          return 0 - 39
      }
      return 0 - 33                                        // any other protocol: REFUSED
  }
  if tgt == HOOK7 {                       // OpenVolume(rcx=This, rdx=&root)
      if reg[R_RCX] == FS_ADDR { m_w64(mem, reg[R_RDX], ROOT_ADDR); reg[R_RAX] = 0; return 0 }
      if reg[R_RCX] == FS2_ADDR { m_w64(mem, reg[R_RDX], ROOT2_ADDR); reg[R_RAX] = 0; return 0 }
      return 0 - 39
  }
  if tgt == HOOK10 {                      // LocateHandleBuffer(rcx=SearchType, rdx=&GUID,
                                          //   r8=SearchKey, r9=&count, [rsp+0x20]=&buffer)
      if reg[R_RCX] != 2 { return 0 - 43 }               // ByProtocol only -- AllHandles would
                                                         // hand back handles we never checked
      if guid_eq(mem, reg[R_RDX], 1) == 0 { return 0 - 33 }
      m_w64(mem, HBUF_ADDR + 0, DEV_HANDLE)
      m_w64(mem, HBUF_ADDR + 8, DEV2_HANDLE)
      m_w64(mem, reg[9], 2)
      m_w64(mem, m_r64(mem, reg[R_RSP] + 0x20), HBUF_ADDR)
      reg[R_RAX] = 0
      return 0
  }
  if tgt == HOOK8 {                       // Open(rcx=This, rdx=&new, r8=name, r9=mode)
      if reg[R_RCX] != ROOT_ADDR { if reg[R_RCX] != ROOT2_ADDR { return 0 - 39 } }
      if reg[9] != 1 { return 0 - 40 }    // READ only -- a writable open of the boot volume is
                                          // refused by construction (never-brick posture)
      // NAME-AWARE. Serving whatever is asked for would make "the optional file is missing" an
      // UNTESTABLE state, and that state is the DEFAULT of the assistant toggle -- the one the
      // harness most needs to exercise. Unknown name -> EFI_NOT_FOUND, exactly like real firmware.
      if u16_name_is(mem, reg[8], 1) == 1 {                  // L"NISHI.AI"
          // MODELLED DELIBERATELY: the assistant file lives ONLY on the DATA volume. A loader that
          // opens it on its own boot volume gets NOT_FOUND here and must go looking.
          if reg[R_RCX] != ROOT2_ADDR { reg[R_RAX] = EFI_NOT_FOUND; return 0 }
          if m_r64(mem, AIFILE_LEN) <= 0 { reg[R_RAX] = EFI_NOT_FOUND; return 0 }
          m_w64(mem, reg[R_RDX], AIFILE_ADDR); reg[R_RAX] = 0; return 0
      }
      if u16_name_is(mem, reg[8], 0) == 1 {                  // L"KERNEL.NXE" -- boot volume only
          if reg[R_RCX] != ROOT_ADDR { reg[R_RAX] = EFI_NOT_FOUND; return 0 }
          if m_r64(mem, KFILE_LEN) <= 0 { reg[R_RAX] = EFI_NOT_FOUND; return 0 }
          m_w64(mem, reg[R_RDX], FILE_ADDR); reg[R_RAX] = 0; return 0
      }
      reg[R_RAX] = EFI_NOT_FOUND; return 0
  }
  if tgt == HOOK9 {                       // Read(rcx=This, rdx=&size, r8=buf)
      if reg[R_RCX] == AIFILE_ADDR {                          // the optional assistant blob
          let ahave: i64 = m_r64(mem, AIFILE_LEN)
          var awant: i64 = m_r64(mem, reg[R_RDX])
          if awant > ahave { awant = ahave }
          var ai: i64 = 0
          while ai < awant { mem[reg[8] + ai] = mem[AIFILE_DATA + ai]; ai = ai + 1 }
          m_w64(mem, reg[R_RDX], awant)
          reg[R_RAX] = 0
          return 0
      }
      if reg[R_RCX] != FILE_ADDR { return 0 - 39 }
      let have: i64 = m_r64(mem, KFILE_LEN)
      var want: i64 = m_r64(mem, reg[R_RDX])
      if want > have { want = have }
      var ci: i64 = 0
      while ci < want { mem[reg[8] + ci] = mem[KFILE_DATA + ci]; ci = ci + 1 }
      m_w64(mem, reg[R_RDX], want)
      reg[R_RAX] = 0
      return 0
  }
  return 1
328}
329
330func gop_guid_b(i: i64) -> i64 {
  if i==0 { return 0xDE } if i==1 { return 0xA9 } if i==2 { return 0x42 } if i==3 { return 0x90 }
  if i==4 { return 0xDC } if i==5 { return 0x23 } if i==6 { return 0x38 } if i==7 { return 0x4A }
  if i==8 { return 0x96 } if i==9 { return 0xFB } if i==10 { return 0x7A } if i==11 { return 0xDE }
  if i==12 { return 0xD0 } if i==13 { return 0x80 } if i==14 { return 0x51 } return 0x6A
335}
336
337// ===== the interpreter: run from entry RVA; capture ConOut output into out; return outn or -err =====
338func emu_run(mem: *u8, entry: i64, out: *u8, trace: i64) -> i64 {
  let reg: *i64 = sys_mmap(8 * 16) as *i64
  var pc: i64 = entry
  var outn: i64 = 0
  reg[R_RSP] = STACK_TOP
  reg[R_RSP] = reg[R_RSP] - 8
  m_w64(mem, reg[R_RSP], RET_SENTINEL)   // so the entry's final ret stops us
  reg[R_RCX] = 0x1234                     // ImageHandle
  reg[R_RDX] = ST_ADDR                    // SystemTable*
  var steps: i64 = 0
  var flagv: i64 = 0                          // last cmp/sub result (for jcc); ZF=(==0) SF=(<0)
  while steps < RET_MAGIC_200000 {
      steps = steps + 1
      // An emulator must never fault on guest behaviour -- a wild pc is the GUEST's bug and must
      // be REFUSED with evidence, not turned into a host segfault that says nothing.
      if pc < 0 { e_p("EMU-WILDPC negative\n" as *u8); return 0 - 36 }
      if (pc + 16) > MEMSZ {
          e_p("EMU-WILDPC pc=0x" as *u8); e_fx(1, pc); e_p(" step=" as *u8); e_fn(1, steps); e_p("\n" as *u8)
          return 0 - 36
      }
      if trace == 1 {
          e_p("T pc=0x" as *u8); e_fx(1, pc); e_p(" op=0x" as *u8); e_fx(1, mem[pc] as i64)
          e_p(" rdi=0x" as *u8); e_fx(1, reg[7]); e_p(" rcx=0x" as *u8); e_fx(1, reg[R_RCX])
          e_p(" rsi=0x" as *u8); e_fx(1, reg[6]); e_p("\n" as *u8)
      }
      let b: i64 = mem[pc] as i64
      var rexR: i64 = 0
      var rexB: i64 = 0
      var is_rexw: i64 = 0
      if b == 0x48 { is_rexw = 1 }
      if b == 0x4C { is_rexw = 1; rexR = 1 }       // REX.WR -> r8/r9 as lea destinations
      if b == 0x49 { is_rexw = 1; rexB = 1 }       // REX.WB -> r8/r9 as r/m dest. N1-full adds
                                                   // EXACTLY mov r9,imm32 (49 C7 C1): Open()'s
                                                   // READ mode rides r9 and lea cannot carry an
                                                   // immediate. Every other 49-prefixed op is
                                                   // REFUSED below, not silently run as its
                                                   // 48-prefixed twin.
      var is_jcc: i64 = 0
      if b >= 0x74 { if b <= 0x7F { is_jcc = 1 } }  // conditional jumps
      if b == 0xC3 {                                 // ret
          let tgt: i64 = m_r64(mem, reg[R_RSP])
          reg[R_RSP] = reg[R_RSP] + 8
          if tgt == RET_SENTINEL { return outn }     // clean program return
          pc = tgt
      } else { if b == 0xFF {                        // call: [base+disp8] (/2 mod01) or r64 (/2 mod11)
          let m: i64 = mem[pc + 1] as i64
          let ffdig: i64 = (m >> 3) & 7
          if ffdig != 2 { if ffdig != 4 { return 0 - 21 } }
          let ffmod: i64 = (m >> 6) & 3
          if ffdig == 4 {                            // FF /4: jmp r64 (FF E0 = jmp rax) -- the shim->NXE handoff
              if ffmod != 3 { return 0 - 21 }
              pc = reg[m & 7]
          } else {
          // ONE hook dispatch for BOTH call forms. They were split once, and a firmware service
          // reachable via `call [mem]` was then INVISIBLE via `call rax` -- the emulator jumped
          // into the hook's address as if it were code (sentinel -29).
          // ★A HOOK REGISTERED ON ONE CALL FORM IS NOT REGISTERED ON THE MECHANISM.
          var tgt: i64 = 0
          var ilen: i64 = 0
          if ffmod == 3 { tgt = reg[m & 7]; ilen = 2 }                              // call r64
          if ffmod == 1 {                                                            // call [base+disp8]
              tgt = m_r64(mem, reg[m & 7] + sx8(mem[pc + 2] as i64)); ilen = 3
          }
          if ilen == 0 { return 0 - 22 }
          var hooked: i64 = 1
          // Once boot services are exited, the firmware is GONE. Any further service call is a
          // use-after-free on real hardware; the model refuses it loudly instead of pretending.
          if m_r64(mem, EBS_STATE) == 1 {
              if tgt == HOOK { return 0 - 37 }
              if tgt == HOOK2 { return 0 - 37 }
              if tgt == HOOK3 { return 0 - 37 }
              if tgt == HOOK4 { return 0 - 37 }
              if tgt == HOOK5 { return 0 - 37 }
              if tgt == HOOK10 { return 0 - 37 }
          }
          if tgt == HOOK {                           // ConOut->OutputString(rcx=This, rdx=CHAR16*)
              outn = cap_str(mem, reg[R_RDX], out, outn)
              reg[R_RAX] = 0                         // EFI_SUCCESS
          } else { if tgt == HOOK2 {
              // GetMemoryMap(rcx=&MapSize, rdx=MapBuf, r8=&MapKey, r9=&DescSize, [rsp+0x20]=&Ver)
              // Real two-call protocol: too small (or NULL buffer) -> BUFFER_TOO_SMALL + the
              // required size; big enough -> SUCCESS + a MapKey that ExitBootServices will check.
              let want: i64 = m_r64(mem, reg[R_RCX])
              var mmreq: i64 = m_r64(mem, MM_SIZE_SLOT)  // 0 = unset (selftest fixtures) -> default
              if mmreq <= 0 { mmreq = MM_REQ_BYTES }
              if reg[R_RDX] == 0 { m_w64(mem, reg[R_RCX], mmreq); reg[R_RAX] = EFI_BUFFER_TOO_SMALL }
              else { if want < mmreq { m_w64(mem, reg[R_RCX], mmreq); reg[R_RAX] = EFI_BUFFER_TOO_SMALL }
              else {
                  m_w64(mem, reg[R_RCX], mmreq)             // actual bytes written
                  if reg[8] != 0 { m_w64(mem, reg[8], MM_MAPKEY) }
                  if reg[9] != 0 { m_w64(mem, reg[9], MM_DESC_SIZE) }
                  m_w64(mem, EBS_STATE + 8, MM_MAPKEY)       // the key now outstanding
                  reg[R_RAX] = 0
              } }
          } else { if tgt == HOOK5 {                 // ExitBootServices(rcx=ImageHandle, rdx=MapKey)
              let issued: i64 = m_r64(mem, EBS_STATE + 8)
              if issued == 0 { reg[R_RAX] = EFI_INVALID_PARAM }        // never got a map
              else { if reg[R_RDX] != issued { reg[R_RAX] = EFI_INVALID_PARAM }  // STALE key refused
              else {
                  m_w64(mem, EBS_STATE, 1)           // firmware surrendered; the kernel owns the machine
                  reg[R_RAX] = 0
              } }
          } else { if tgt == HOOK10 { hooked = 2 } else { if tgt == HOOK6 { hooked = 2 } else { if tgt == HOOK7 { hooked = 2
          } else { if tgt == HOOK8 { hooked = 2 } else { if tgt == HOOK9 { hooked = 2
          } else { if tgt == HOOK3 {                 // BootServices->LocateProtocol(rcx=&GUID, r8=&iface)
              var gi: i64 = 0                        // the GUID is CHECKED: wrong protocol -> refused
              while gi < 16 { if (mem[reg[R_RCX] + gi] as i64) != gop_guid_b(gi) { return 0 - 33 } gi = gi + 1 }
              m_w64(mem, reg[8], GOP_ADDR)           // *r8 = the modeled GOP interface
              reg[R_RAX] = 0
          } else { if tgt == HOOK4 {                 // ConIn->ReadKeyStroke(rcx=This, rdx=EFI_INPUT_KEY*)
              let qn: i64 = m_r64(mem, KEYQ_ADDR)    // scripted keys drain in order, then NOT_READY
              let qi: i64 = m_r64(mem, KEYQ_ADDR + 8)
              if qi < qn {
                  m_w16(mem, reg[R_RDX], m_r64(mem, KEYQ_ADDR + 16 + qi * 16))       // ScanCode
                  m_w16(mem, reg[R_RDX] + 2, m_r64(mem, KEYQ_ADDR + 16 + qi * 16 + 8)) // UnicodeChar
                  m_w64(mem, KEYQ_ADDR + 8, qi + 1)
                  reg[R_RAX] = 0                     // EFI_SUCCESS
              } else {
                  reg[R_RAX] = EFI_NOT_READY         // an empty queue is NOT-READY, never a fake key
              }
          } else { hooked = 0 } } } } } } } } } }
          if hooked == 2 {
              let hr: i64 = emu_hook_call(mem, tgt, reg)
              if hr < 0 { return hr }
              pc = pc + ilen
          } else {
          if hooked == 1 { pc = pc + ilen } else {   // a real call: push the return address
              reg[R_RSP] = reg[R_RSP] - 8
              m_w64(mem, reg[R_RSP], pc + ilen)
              pc = tgt
          } } }
      } else { if is_rexw == 1 {                     // REX.W (0x48) or REX.WR (0x4C) -- flat dispatch
          let op: i64 = mem[pc + 1] as i64
          var hd: i64 = 0
          // REX.WB is implemented for ONE opcode. Letting the other handlers fire with rexB set
          // would silently write the WRONG register -- the /digit lesson applied to prefixes:
          // ★AN OPCODE IMPLEMENTED FOR ONE PREFIX IS NOT IMPLEMENTED, IT IS MIS-EXECUTED.
          if rexB == 1 { if op != 0xC7 {
              e_p("EMU-UNDECODED REX.WB op=0x" as *u8); e_fx(1, op)
              e_p(" at pc=0x" as *u8); e_fx(1, pc); e_p("\n" as *u8)
              return 0 - 28
          } }
          if op == 0x83 {                            // grp1 r/m64,imm8 (reg-direct): add/sub/and/cmp
              let m: i64 = mem[pc + 2] as i64
              let imm: i64 = sx8(mem[pc + 3] as i64)
              let dig: i64 = (m >> 3) & 7
              if dig == 0 { reg[m & 7] = reg[m & 7] + imm }
              if dig == 5 { reg[m & 7] = reg[m & 7] - imm }
              if dig == 4 { reg[m & 7] = reg[m & 7] & imm }
              if dig == 7 { flagv = reg[m & 7] - imm }
              pc = pc + 4; hd = 1
          }
          if op == 0x81 {                            // grp1 r/m64,imm32 -- a stride that outgrew imm8
              let m81: i64 = mem[pc + 2] as i64
              let imm81: i64 = m_i32(mem, pc + 3)
              let dig81: i64 = (m81 >> 3) & 7
              if dig81 == 0 { reg[m81 & 7] = reg[m81 & 7] + imm81 }
              if dig81 == 5 { reg[m81 & 7] = reg[m81 & 7] - imm81 }
              if dig81 == 4 { reg[m81 & 7] = reg[m81 & 7] & imm81 }
              if dig81 == 7 { flagv = reg[m81 & 7] - imm81 }
              pc = pc + 7; hd = 1
          }
          if op == 0xC7 { reg[(rexB * 8) + ((mem[pc + 2] as i64) & 7)] = m_i32(mem, pc + 3); pc = pc + 7; hd = 1 }  // mov r/m64,imm32 (rexB -> r8/r9)
          if op == 0xC1 {                            // grp2 r/m64, imm8 -- /4 = shl, /5 = shr
              // ⚠This decoded EVERY 0xC1 as shr, ignoring the /digit, so `shl rax,11` silently
              // executed as a RIGHT shift and the PCI slot never entered the selector (the latch
              // sat at 0x80000000 for all 32 slots). ★★★★★AN OPCODE IMPLEMENTED FOR ONE /DIGIT
              // IS NOT IMPLEMENTED -- IT IS MIS-EXECUTED FOR THE OTHERS.
              let m: i64 = mem[pc + 2] as i64
              let dig: i64 = (m >> 3) & 7
              let amt: i64 = mem[pc + 3] as i64
              if dig == 4 { reg[m & 7] = reg[m & 7] << amt; pc = pc + 4; hd = 1 }
              if dig == 5 { reg[m & 7] = reg[m & 7] >> amt; pc = pc + 4; hd = 1 }
          }
          if op == 0xD3 {                            // grp2 r/m64, CL -- /4 = shl, /5 = shr
              let m: i64 = mem[pc + 2] as i64
              let dig3: i64 = (m >> 3) & 7
              if dig3 == 4 { reg[m & 7] = reg[m & 7] << (reg[1] & 63); pc = pc + 3; hd = 1 }
              if dig3 == 5 { reg[m & 7] = reg[m & 7] >> (reg[1] & 63); pc = pc + 3; hd = 1 }
          }
          if op == 0x31 { let m: i64 = mem[pc + 2] as i64; reg[m & 7] = reg[m & 7] ^ reg[(m >> 3) & 7]; pc = pc + 3; hd = 1 }  // xor r64,r64 (reg-direct)
          if op == 0x0F {                            // two-byte opcode: 0F AF /r = imul r64,r/m64
              if (mem[pc + 2] as i64) == 0xAF {      // signed multiply -- the AI1 multiply-accumulate
                  let m: i64 = mem[pc + 3] as i64
                  if ((m >> 6) & 3) == 3 { reg[(m >> 3) & 7] = reg[(m >> 3) & 7] * reg[m & 7]; pc = pc + 4; hd = 1 }
              }
          }
          if op == 0x01 { let m: i64 = mem[pc + 2] as i64; reg[m & 7] = reg[m & 7] + reg[(m >> 3) & 7]; pc = pc + 3; hd = 1 }
          if op == 0x29 { let m: i64 = mem[pc + 2] as i64; reg[m & 7] = reg[m & 7] - reg[(m >> 3) & 7]; pc = pc + 3; hd = 1 }
          if op == 0x39 { let m: i64 = mem[pc + 2] as i64; flagv = reg[m & 7] - reg[(m >> 3) & 7]; pc = pc + 3; hd = 1 }
          if op == 0x21 { let m: i64 = mem[pc + 2] as i64; reg[m & 7] = reg[m & 7] & reg[(m >> 3) & 7]; pc = pc + 3; hd = 1 }
          if op == 0x89 {                            // mov r/m64,r64 (reg-direct / [reg+disp8] store)
              let m: i64 = mem[pc + 2] as i64
              let mod89: i64 = (m >> 6) & 3
              let src89: i64 = (rexR * 8) + ((m >> 3) & 7)
              if mod89 == 3 { reg[m & 7] = reg[src89]; pc = pc + 3; hd = 1 }
              if mod89 == 1 {
                  if (m & 7) == 4 { m_w64(mem, reg[R_RSP] + sx8(mem[pc + 4] as i64), reg[src89]); pc = pc + 5; hd = 1 }
                  else { m_w64(mem, reg[m & 7] + sx8(mem[pc + 3] as i64), reg[src89]); pc = pc + 4; hd = 1 }
              }
          }
          if op == 0x8B {                            // mov r64,[base+disp8|SIB+disp8|base+disp32] or reg-direct
              let m: i64 = mem[pc + 2] as i64
              let mod: i64 = (m >> 6) & 3
              let dst: i64 = (m >> 3) & 7
              if mod == 1 {
                  if (m & 7) == 4 {                  // SIB form (no-index assumed): base from the SIB byte
                      reg[dst] = m_r64(mem, reg[(mem[pc + 3] as i64) & 7] + sx8(mem[pc + 4] as i64)); pc = pc + 5; hd = 1
                  } else {
                      reg[dst] = m_r64(mem, reg[m & 7] + sx8(mem[pc + 3] as i64)); pc = pc + 4; hd = 1
                  }
              }
              if mod == 2 { if (m & 7) != 4 { reg[dst] = m_r64(mem, reg[m & 7] + m_i32(mem, pc + 3)); pc = pc + 7; hd = 1 } }
              if mod == 0 {                          // mov r64,[base]  -- no disp (AI1 vector walk)
                  if (m & 7) != 4 { if (m & 7) != 5 { reg[dst] = m_r64(mem, reg[m & 7]); pc = pc + 3; hd = 1 } }
              }
              if mod == 3 { reg[dst] = reg[m & 7]; pc = pc + 3; hd = 1 }
          }
          if op == 0x8D {                            // lea r64,[rip+disp32] (mod00) | [SIB-base+disp8] (mod01)
              let m: i64 = mem[pc + 2] as i64
              let lmod: i64 = (m >> 6) & 3
              if lmod == 0 { reg[(rexR * 8) + ((m >> 3) & 7)] = (pc + 7) + m_i32(mem, pc + 3); pc = pc + 7; hd = 1 }
              if lmod == 1 {
                  if (m & 7) == 4 {                  // lea r64,[rsp+disp8] shape (no-index SIB)
                      reg[(rexR * 8) + ((m >> 3) & 7)] = reg[(mem[pc + 3] as i64) & 7] + sx8(mem[pc + 4] as i64); pc = pc + 5; hd = 1
                  } else {                           // lea r64,[base+disp8]
                      reg[(rexR * 8) + ((m >> 3) & 7)] = reg[m & 7] + sx8(mem[pc + 3] as i64); pc = pc + 4; hd = 1
                  }
              }
          }
          if hd == 0 {
              e_p("EMU-UNDECODED rex=0x" as *u8); e_fx(1, b); e_p(" op=0x" as *u8); e_fx(1, op)
              e_p(" modrm=0x" as *u8); e_fx(1, mem[pc + 2] as i64)
              e_p(" at pc=0x" as *u8); e_fx(1, pc); e_p("\n" as *u8)
              return 0 - 28
          }
      } else { if b == 0x31 {                        // xor r/m,r (reg-direct)
          let m: i64 = mem[pc + 1] as i64
          reg[m & 7] = reg[m & 7] ^ reg[(m >> 3) & 7]
          pc = pc + 2
      } else { if is_jcc == 1 {                      // jcc rel8 (74 jz/75 jnz/7C jl/7D jge/7E jle/7F jg)
          let rel: i64 = sx8(mem[pc + 1] as i64)
          var taken: i64 = 0
          if b == 0x74 { if flagv == 0 { taken = 1 } }
          if b == 0x75 { if flagv != 0 { taken = 1 } }
          if b == 0x7C { if flagv < 0 { taken = 1 } }
          if b == 0x7D { if flagv >= 0 { taken = 1 } }
          if b == 0x7E { if flagv <= 0 { taken = 1 } }
          if b == 0x7F { if flagv > 0 { taken = 1 } }
          if taken == 1 { pc = (pc + 2) + rel } else { pc = pc + 2 }
      } else { if b == 0xEB {                        // jmp rel8; EB FE self-jump = the app deliberately HOLDS
          let rel: i64 = sx8(mem[pc + 1] as i64)
          if rel == (0 - 2) { return 0 - 90 }        // distinct HOLD return -- judged by MEASURING the framebuffer, not an error
          pc = (pc + 2) + rel
      } else { if b == 0xE9 {                        // jmp rel32 (a loop body >127B needs it)
          pc = (pc + 5) + m_i32(mem, pc + 1)
      } else { if b == 0x0F {                        // 0F 85 = jnz rel32 (loops >127B)
          let two: i64 = mem[pc + 1] as i64
          if two == 0x85 {                                          // jnz rel32
              if flagv != 0 { pc = (pc + 6) + m_i32(mem, pc + 2) } else { pc = pc + 6 }
          } else { if two == 0x84 {                                 // jz rel32
              if flagv == 0 { pc = (pc + 6) + m_i32(mem, pc + 2) } else { pc = pc + 6 }
          } else { return 0 - 42 } }
      } else { if b == 0xBA {                        // mov edx,imm32 (the port selector)
          var pv: i64 = m_i32(mem, pc + 1)
          if pv < 0 { pv = pv + (1 << 32) }
          reg[R_RDX] = pv
          pc = pc + 5
      } else { if b == 0xEF {                        // OUT dx,eax -- CONFIG_ADDRESS ONLY
          if reg[R_RDX] != PCI_ADDR_PORT {
              // A port WRITE anywhere else can mutate device or firmware state. Refused, and
              // named, rather than quietly permitted. (never-brick, rule 26)
              e_p("EMU-PORT refused OUT to port 0x" as *u8); e_fx(1, reg[R_RDX]); e_p("
611" as *u8)
              return 0 - 41
          }
          m_w64(mem, PCI_LATCH, reg[R_RAX] & 0xFFFFFFFF)
          pc = pc + 1
      } else { if b == 0xED {                        // IN eax,dx -- CONFIG_DATA ONLY
          if reg[R_RDX] != PCI_DATA_PORT {
              e_p("EMU-PORT refused IN from port 0x" as *u8); e_fx(1, reg[R_RDX]); e_p("
619" as *u8)
              return 0 - 41
          }
          let plat: i64 = m_r64(mem, PCI_LATCH)
          reg[R_RAX] = pci_cfg_read(plat)
          pc = pc + 1
      } else { if b == 0xE4 {                        // IN al,imm8 -- modeled PS/2 only
          let port: i64 = mem[pc + 1] as i64
          if port == PS2_PORT_STATUS {
              let n: i64 = m_r64(mem, PS2_STATE)
              let ix: i64 = m_r64(mem, PS2_STATE + 8)
              if ix < n { reg[R_RAX] = 1 } else { reg[R_RAX] = 0 }   // bit0 = byte waiting
          } else { if port == PS2_PORT_DATA {
              let n2: i64 = m_r64(mem, PS2_STATE)
              let ix2: i64 = m_r64(mem, PS2_STATE + 8)
              if ix2 < n2 {
                  reg[R_RAX] = m_r64(mem, PS2_STATE + 16 + ix2 * 8)
                  m_w64(mem, PS2_STATE + 8, ix2 + 1)
              } else { reg[R_RAX] = 0 }
          } else {
              // Any other port is REFUSED. An emulator that invents a value for an unmodeled
              // port teaches the kernel that made-up hardware works.
              e_p("EMU-PORT refused unmodeled port 0x" as *u8); e_fx(1, port); e_p("
642" as *u8)
              return 0 - 38
          } }
          pc = pc + 2
      } else { if b == 0xFC {                        // cld (this model is always forward)
          pc = pc + 1
      } else { if b == 0xF3 {                        // F3 AB rep stosd: eax -> rcx dwords at [rdi], ONE interpreter step
          if (mem[pc + 1] as i64) != 0xAB { return 0 - 27 }
          let cval: i64 = reg[R_RAX] & 0xFFFFFFFF
          while reg[R_RCX] > 0 {
              if reg[R_RDI] < 0 { return 0 - 34 }    // store outside modeled memory = refused, never wrapped
              if (reg[R_RDI] + 4) > MEMSZ { return 0 - 34 }
              mem[reg[R_RDI]] = (cval & 0xff) as u8
              mem[reg[R_RDI] + 1] = ((cval >> 8) & 0xff) as u8
              mem[reg[R_RDI] + 2] = ((cval >> 16) & 0xff) as u8
              mem[reg[R_RDI] + 3] = ((cval >> 24) & 0xff) as u8
              reg[R_RDI] = reg[R_RDI] + 4
              reg[R_RCX] = reg[R_RCX] - 1
          }
          pc = pc + 2
      } else { if b >= 0xB8 {
          if b <= 0xBF {                             // mov r32,imm32 (B8+rd, zero-extends into r64)
              var iv: i64 = m_i32(mem, pc + 1)
              if iv < 0 { iv = iv + (1 << 32) }
              reg[b - 0xB8] = iv
              pc = pc + 5
          } else { return 0 - 29 }
      } else { if b >= 0x50 {                        // push/pop r64 (0x50..0x5F)
          if b <= 0x57 {
              reg[R_RSP] = reg[R_RSP] - 8
              m_w64(mem, reg[R_RSP], reg[b - 0x50])
              pc = pc + 1
          } else { if b <= 0x5F {
              reg[b - 0x58] = m_r64(mem, reg[R_RSP])
              reg[R_RSP] = reg[R_RSP] + 8
              pc = pc + 1
          } else { return 0 - 20 } }
      } else {
          // an undecoded opcode must say WHICH one and WHERE -- a bare sentinel costs a build
          // cycle every time. (Learned twice today: name the failing tooth, name the failing byte.)
          e_p("EMU-UNDECODED opcode=0x" as *u8); e_fx(1, b)
          e_p(" next=0x" as *u8); e_fx(1, mem[pc + 1] as i64)
          e_p(" at pc=0x" as *u8); e_fx(1, pc); e_p(" step=" as *u8); e_fn(1, steps); e_p("\n" as *u8)
          return 0 - 29
      } } } } } } } } } } } } } } } }   // <- closes the dispatch chain ONLY, back to loop depth
      // ⚠ONE closer per `} else { if …` link. This pile has now been wrong three times while
      // adding opcodes; ALWAYS re-run the brace-depth counter after touching the dispatch.
  }                         // <- closes `while`
  // ⚠The pile above was ONE closer too long for a day: it ended the FUNCTION, so the next line
  // closed the loop and everything below fell OUTSIDE emu_run -- silently, because a stray
  // statement at module level is not an error. Symptom: segfault with ZERO output (the exit
  // block got a synthesized return of param0, main read that pointer as a length and wrote far
  // past a 512-byte buffer). ★★★★★A DEEP ELSE-CHAIN HIDES ITS OWN MIS-NESTING -- COUNT BRACE
  // DEPTH MECHANICALLY, NEVER BY EYE. I blamed the compiler first; the compiler was innocent.
  return 0 - 30                                       // step cap: a runaway, OR a live event loop
697}
698
699// ===== I/O + log =================================================================
700func e_p(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } sys_write(1, s, n); return 0 }
701func e_fp(fd: i64, s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } sys_write(fd, s, n); return 0 }
702func e_fn(fd: i64, v: i64) -> i64 {
  let bb: *u8 = sys_mmap(28); var m: i64 = v; if m < 0 { m = 0 - m }
  let t: *u8 = sys_mmap(28); var k: i64 = 0
  if m == 0 { t[0] = 48; k = 1 }
  while m > 0 { t[k] = (48 + (m % 10)) as u8; m = m / 10; k = k + 1 }
  var i: i64 = 0; while i < k { bb[i] = t[k - 1 - i]; i = i + 1 }
  sys_write(fd, bb, k); return 0
709}
710
711// hex print (8 digits) -- the measured fill color is reported in the artifact's own terms
712func e_fx(fd: i64, v: i64) -> i64 {
  let hx: *u8 = "0123456789ABCDEF" as *u8
  let bb: *u8 = sys_mmap(16)
  var i: i64 = 0
  while i < 8 { bb[i] = hx[(v >> (28 - 4 * i)) & 15]; i = i + 1 }
  sys_write(fd, bb, 8); return 0
718}
719
720// Dump the modeled framebuffer as a 24-bit BMP so the operator SEES what the sovereign lane
721// measured -- the picture and the verdict come from the SAME bytes (no second render path).
722func fb_dump_bmp(mem: *u8, base: i64, w: i64, h: i64, path: *u8) -> i64 {
  let rowb: i64 = w * 3
  var pad: i64 = 0
  while ((rowb + pad) % 4) != 0 { pad = pad + 1 }
  let imgsz: i64 = (rowb + pad) * h
  let total: i64 = 54 + imgsz
  let bm: *u8 = sys_mmap(total + 4096)
  bm[0] = 66 as u8; bm[1] = 77 as u8                       // "BM"
  m_w32b(bm, 2, total); m_w32b(bm, 10, 54)
  m_w32b(bm, 14, 40); m_w32b(bm, 18, w); m_w32b(bm, 22, h)
  bm[26] = 1 as u8; bm[28] = 24 as u8                      // planes=1, bpp=24
  m_w32b(bm, 34, imgsz)
  var y: i64 = 0
  while y < h {
      let srow: i64 = base + (h - 1 - y) * w * 4           // BMP rows are bottom-up
      var d: i64 = 54 + y * (rowb + pad)
      var x: i64 = 0
      while x < w {
          bm[d]     = mem[srow + x * 4]                    // B
          bm[d + 1] = mem[srow + x * 4 + 1]                // G
          bm[d + 2] = mem[srow + x * 4 + 2]                // R
          d = d + 3
          x = x + 1
      }
      y = y + 1
  }
  let fd: i64 = sys_openat_wr(path, 0x1a4)
  if fd < 0 { return 0 - 1 }
  sys_write(fd, bm, total)
  sys_close(fd)
  return total
753}
754func m_w32b(b: *u8, o: i64, v: i64) -> i64 {
  b[o] = (v & 0xff) as u8; b[o+1] = ((v >> 8) & 0xff) as u8
  b[o+2] = ((v >> 16) & 0xff) as u8; b[o+3] = ((v >> 24) & 0xff) as u8
  return 0
758}
759
760// atoi for the small positive coordinates the pixel probe takes
761func s_atoi(s: *u8) -> i64 {
  var v: i64 = 0; var i: i64 = 0
  while s[i] != (0 as u8) {
      let d: i64 = (s[i] as i64) - 48
      if d < 0 { return 0 - 1 }
      if d > 9 { return 0 - 1 }
      v = v * 10 + d; i = i + 1
  }
  return v
770}
771
772// --px <x> <y> : print the exact dword at one pixel. Generic harness verb -- the emulator learns
773// no kernel geometry, the CALLER states the coordinate, so a rung can assert a computed value
774// without the emulator being taught what that value means.
775func px_probe(mem: *u8, base: i64, argc: i64, argv: *i64) -> i64 {
  var i: i64 = 2
  while i < (argc - 2) {
      if s_eq(argv[i] as *u8, "--px" as *u8) == 1 {
          let x: i64 = s_atoi(argv[i + 1] as *u8)
          let y: i64 = s_atoi(argv[i + 2] as *u8)
          if x < 0 { return 0 }
          if y < 0 { return 0 }
          let a: i64 = base + (y * FB_W_PIX + x) * 4
          let d: i64 = (mem[a] as i64) | ((mem[a+1] as i64) << 8) | ((mem[a+2] as i64) << 16) | ((mem[a+3] as i64) << 24)
          e_p("NOS-PX x=" as *u8); e_fn(1, x); e_p(" y=" as *u8); e_fn(1, y)
          e_p(" value=" as *u8); e_fn(1, d); e_p(" hex=0x" as *u8); e_fx(1, d); e_p("\n" as *u8)
          return d
      }
      i = i + 1
  }
  return 0
792}
793
794// --shot <out.bmp>, scanned at ANY argv position -- the same treatment --kernel and --aifile
795// already get. It was previously read at argv[2] in the HOLD branch and argv[4] in the EVENT-LOOP
796// branch, so the position a caller needed depended on which path the payload happened to take, and
797// getting it wrong produced NO FILE, NO ERROR and EXIT 0. A FEATURE THAT ONLY FAILS SILENTLY IS
798// INDISTINGUISHABLE FROM ONE THAT WAS NEVER COMPILED IN, so the success path now announces itself.
799// One flag, one meaning, one implementation, two call sites.  Debt 1786236016.
800// The scan ends on a FLAG, never by clobbering its own cursor: a loop that exits by overshooting
801// its index destroys the position it was searching for.
802func shot_if_asked(mem: *u8, base: i64, argc: i64, argv: *i64) -> i64 {
  var i: i64 = 2
  var found: i64 = 0
  while i < (argc - 1) {
      if s_eq(argv[i] as *u8, "--shot" as *u8) == 1 {
          if found == 0 {
              let sp: *u8 = argv[i + 1] as *u8
              let bw: i64 = fb_dump_bmp(mem, base, FB_W_PIX, FB_H_PIX, sp)
              e_p("NOS-SHOT: wrote " as *u8); e_fn(1, bw); e_p("B BMP -> " as *u8)
              e_p(sp); e_p("\n" as *u8)
              found = 1
          }
      }
      i = i + 1
  }
  return found
818}
819
820func s_eq(a: *u8, b: *u8) -> i64 {
  var i: i64 = 0
  while a[i] != (0 as u8) { if a[i] != b[i] { return 0 } i = i + 1 }
  if b[i] != (0 as u8) { return 0 }
  return 1
825}
826
827// MEASURE the modeled framebuffer: color := first dword (never assumed from any emitter constant),
828// outp[0]=color outp[1]=dwords-matching-color outp[2]=total-dwords outp[3]=zero-dwords
829// outp[4]=adjacent-transitions (a SCENE has many; a wash has 0; an unpainted hole shows in zeros).
830func fb_measure(mem: *u8, base: i64, size: i64, outp: *i64) -> i64 {
  let ndw: i64 = size / 4
  let color: i64 = (mem[base] as i64) | ((mem[base+1] as i64) << 8) | ((mem[base+2] as i64) << 16) | ((mem[base+3] as i64) << 24)
  var matches: i64 = 0
  var zeros: i64 = 0
  var trans: i64 = 0
  var prev: i64 = color
  var i: i64 = 0
  while i < ndw {
      let o: i64 = base + i * 4
      let d: i64 = (mem[o] as i64) | ((mem[o+1] as i64) << 8) | ((mem[o+2] as i64) << 16) | ((mem[o+3] as i64) << 24)
      if d == color { matches = matches + 1 }
      if d == 0 { zeros = zeros + 1 }
      if d != prev { trans = trans + 1 }
      prev = d
      i = i + 1
  }
  outp[0] = color; outp[1] = matches; outp[2] = ndw; outp[3] = zeros; outp[4] = trans
  return matches
849}
850
851// PURE verdict for a HOLDING app (testable without waiting on a real image):
852// 1 = PAINTED-AND-HOLDING (uniform nonzero wash covers 100%)
853// 2 = SCENE-PAINTED-AND-HOLDING (every dword nonzero AND >=4 transitions = a composed scene)
854// 0 = not painted (any zero dword, or a black wash)
855func hold_verdict(color: i64, matches: i64, ndw: i64, zeros: i64, trans: i64) -> i64 {
  if ndw <= 0 { return 0 }
  if color != 0 { if matches == ndw { return 1 } }
  if zeros == 0 { if trans >= 4 { return 2 } }
  return 0
860}
861
862// selftest byte writers
863func st_w(mem: *u8, o: i64, v: i64) -> i64 { mem[o] = (v & 0xff) as u8; return o + 1 }
864func st_i32(mem: *u8, o: i64, v: i64) -> i64 {
  st_w(mem, o, v); st_w(mem, o + 1, v >> 8); st_w(mem, o + 2, v >> 16); st_w(mem, o + 3, v >> 24); return o + 4
866}
867
868// ===== in-process teeth (every selftest run refutable; negative controls are the point) ======
869// T1 hold-without-paint must NOT read as painted. T2 full paint + hold IS painted. T3 partial
870// paint must NOT read as painted (the 1000-permil bar has a bite). T4 wrong GUID is refused -33.
871func emu_selftest() -> i64 {
  let out: *u8 = sys_mmap(512)
  let mm: *i64 = sys_mmap(48) as *i64
  var pass: i64 = 0
875
  // T1: EB FE only -- HOLDS, framebuffer untouched (zero) -> not painted
  var mem: *u8 = sys_mmap(MEMSZ)
  var o: i64 = 0x1000
  o = st_w(mem, o, 0xEB); o = st_w(mem, o, 0xFE)
  var r: i64 = emu_run(mem, 0x1000, out, 0)
  var c: i64 = 0
  if r == (0 - 90) { fb_measure(mem, 0x2000, 0x400, mm); if mm[0] == 0 { c = 1 } }
  if c == 1 { pass = pass + 1; e_p("EMU-T1 hold-unpainted GREEN\n" as *u8) } else { e_p("EMU-T1 RED\n" as *u8) }
884
  // T2: mov rdi/rcx/eax + cld + rep stosd + hold -> painted 256/256, color as written
  mem = sys_mmap(MEMSZ)
  o = 0x1000
  o = st_w(mem, o, 0x48); o = st_w(mem, o, 0xC7); o = st_w(mem, o, 0xC7); o = st_i32(mem, o, 0x2000)
  o = st_w(mem, o, 0x48); o = st_w(mem, o, 0xC7); o = st_w(mem, o, 0xC1); o = st_i32(mem, o, 0x100)
  o = st_w(mem, o, 0xB8); o = st_i32(mem, o, 0x00AA8844)
  o = st_w(mem, o, 0xFC)
  o = st_w(mem, o, 0xF3); o = st_w(mem, o, 0xAB)
  o = st_w(mem, o, 0xEB); o = st_w(mem, o, 0xFE)
  r = emu_run(mem, 0x1000, out, 0)
  c = 0
  if r == (0 - 90) {
      fb_measure(mem, 0x2000, 0x400, mm)
      if mm[0] == 0x00AA8844 { if mm[1] == 256 { if mm[2] == 256 { c = 1 } } }
  }
  if c == 1 { pass = pass + 1; e_p("EMU-T2 painted-and-holding GREEN\n" as *u8) } else { e_p("EMU-T2 RED\n" as *u8) }
901
  // T3: same but only half the dwords -> 128/256, must NOT be full
  mem = sys_mmap(MEMSZ)
  o = 0x1000
  o = st_w(mem, o, 0x48); o = st_w(mem, o, 0xC7); o = st_w(mem, o, 0xC7); o = st_i32(mem, o, 0x2000)
  o = st_w(mem, o, 0x48); o = st_w(mem, o, 0xC7); o = st_w(mem, o, 0xC1); o = st_i32(mem, o, 0x80)
  o = st_w(mem, o, 0xB8); o = st_i32(mem, o, 0x00AA8844)
  o = st_w(mem, o, 0xFC)
  o = st_w(mem, o, 0xF3); o = st_w(mem, o, 0xAB)
  o = st_w(mem, o, 0xEB); o = st_w(mem, o, 0xFE)
  r = emu_run(mem, 0x1000, out, 0)
  c = 0
  if r == (0 - 90) { fb_measure(mem, 0x2000, 0x400, mm); if mm[1] == 128 { if mm[2] == 256 { c = 1 } } }
  if c == 1 { pass = pass + 1; e_p("EMU-T3 partial-refused GREEN\n" as *u8) } else { e_p("EMU-T3 RED\n" as *u8) }
915
  // T4: LocateProtocol with a WRONG (all-zero) GUID -> refused with -33
  mem = sys_mmap(MEMSZ)
  o = 0x1000
  o = st_w(mem, o, 0x48); o = st_w(mem, o, 0xC7); o = st_w(mem, o, 0xC0); o = st_i32(mem, o, HOOK3)
  o = st_w(mem, o, 0x48); o = st_w(mem, o, 0xC7); o = st_w(mem, o, 0xC1); o = st_i32(mem, o, 0x3000)
  o = st_w(mem, o, 0xFF); o = st_w(mem, o, 0xD0)
  r = emu_run(mem, 0x1000, out, 0)
  if r == (0 - 33) { pass = pass + 1; e_p("EMU-T4 guid-refused GREEN\n" as *u8) } else { e_p("EMU-T4 RED\n" as *u8) }
924
  // T5: five distinct bands covering the whole region -> SCENE verdict (2), not uniform, not red
  mem = sys_mmap(MEMSZ)
  o = 0x1000
  o = st_w(mem, o, 0xFC)
  var bi: i64 = 0
  while bi < 5 {
      var bcnt: i64 = 51
      if bi == 4 { bcnt = 52 }
      o = st_w(mem, o, 0x48); o = st_w(mem, o, 0xC7); o = st_w(mem, o, 0xC7); o = st_i32(mem, o, 0x2000 + bi * 204)
      o = st_w(mem, o, 0x48); o = st_w(mem, o, 0xC7); o = st_w(mem, o, 0xC1); o = st_i32(mem, o, bcnt)
      o = st_w(mem, o, 0xB8); o = st_i32(mem, o, 0x11111111 * (bi + 1))
      o = st_w(mem, o, 0xF3); o = st_w(mem, o, 0xAB)
      bi = bi + 1
  }
  o = st_w(mem, o, 0xEB); o = st_w(mem, o, 0xFE)
  r = emu_run(mem, 0x1000, out, 0)
  c = 0
  if r == (0 - 90) {
      fb_measure(mem, 0x2000, 0x400, mm)
      if hold_verdict(mm[0], mm[1], mm[2], mm[3], mm[4]) == 2 { c = 1 }
  }
  if c == 1 { pass = pass + 1; e_p("EMU-T5 scene-verdict GREEN\n" as *u8) } else { e_p("EMU-T5 RED\n" as *u8) }
947
  // T6: full-region fill EXCEPT one zero dword -> a hole means NOT painted (verdict 0)
  mem = sys_mmap(MEMSZ)
  o = 0x1000
  o = st_w(mem, o, 0x48); o = st_w(mem, o, 0xC7); o = st_w(mem, o, 0xC7); o = st_i32(mem, o, 0x2000)
  o = st_w(mem, o, 0x48); o = st_w(mem, o, 0xC7); o = st_w(mem, o, 0xC1); o = st_i32(mem, o, 255)
  o = st_w(mem, o, 0xB8); o = st_i32(mem, o, 0x66666666)
  o = st_w(mem, o, 0xFC)
  o = st_w(mem, o, 0xF3); o = st_w(mem, o, 0xAB)
  o = st_w(mem, o, 0xEB); o = st_w(mem, o, 0xFE)
  r = emu_run(mem, 0x1000, out, 0)
  c = 0
  if r == (0 - 90) {
      fb_measure(mem, 0x2000, 0x400, mm)
      if hold_verdict(mm[0], mm[1], mm[2], mm[3], mm[4]) == 0 { c = 1 }
  }
  if c == 1 { pass = pass + 1; e_p("EMU-T6 hole-refused GREEN\n" as *u8) } else { e_p("EMU-T6 RED\n" as *u8) }
964
  // T7: the ConIn hook DRAINS a scripted queue exactly once per key and then reports NOT-READY.
  // Queue of 2; the program reads 3 times -> 2 successes then a refusal, and rax proves which.
  mem = sys_mmap(MEMSZ)
  m_w64(mem, CI_ADDR + 0x08, HOOK4)
  m_w64(mem, KEYQ_ADDR, 2)
  m_w64(mem, KEYQ_ADDR + 8, 0)
  m_w64(mem, KEYQ_ADDR + 16 + 8, 65)                 // 'A'
  m_w64(mem, KEYQ_ADDR + 32 + 8, 66)                 // 'B'
  o = 0x1000
  o = st_w(mem, o, 0x48); o = st_w(mem, o, 0xC7); o = st_w(mem, o, 0xC1); o = st_i32(mem, o, CI_ADDR)
  o = st_w(mem, o, 0x48); o = st_w(mem, o, 0xC7); o = st_w(mem, o, 0xC2); o = st_i32(mem, o, 0x3000)
  var kk: i64 = 0
  while kk < 3 {                                     // 3 reads against a 2-key queue
      o = st_w(mem, o, 0x48); o = st_w(mem, o, 0x8B); o = st_w(mem, o, 0x41); o = st_w(mem, o, 0x08)
      o = st_w(mem, o, 0xFF); o = st_w(mem, o, 0xD0)
      kk = kk + 1
  }
  o = st_w(mem, o, 0xEB); o = st_w(mem, o, 0xFE)
  r = emu_run(mem, 0x1000, out, 0)
  c = 0
  if r == (0 - 90) {
      if m_r64(mem, KEYQ_ADDR + 8) == 2 {            // exactly 2 drained, never 3
          if (mem[0x3002] as i64) == 66 { c = 1 }    // the LAST delivered key was 'B'
      }
  }
  if c == 1 { pass = pass + 1; e_p("EMU-T7 conin-drain GREEN\n" as *u8) } else { e_p("EMU-T7 RED\n" as *u8) }
991
  // T8: the N1-full file chain end to end THROUGH THE SAME emu_hook_call the interpreter uses,
  // plus its refusals. A hook nobody has exercised is not a hook.
  mem = sys_mmap(MEMSZ)
  m_w64(mem, LI_ADDR + 0x18, DEV_HANDLE)
  m_w64(mem, KFILE_LEN, 8)
  var gi2: i64 = 0
  while gi2 < 16 { mem[0x3000 + gi2] = li_guid_b(gi2) as u8; mem[0x3100 + gi2] = fs_guid_b(gi2) as u8; gi2 = gi2 + 1 }
  var kb2: i64 = 0
  while kb2 < 8 { mem[KFILE_DATA + kb2] = (0x41 + kb2) as u8; kb2 = kb2 + 1 }
  let rg: *i64 = sys_mmap(8 * 16) as *i64
  var c8: i64 = 1
  rg[R_RCX] = 0x1234; rg[R_RDX] = 0x3000; rg[8] = 0x3200
  if emu_hook_call(mem, HOOK6, rg) != 0 { c8 = 0 }
  if m_r64(mem, 0x3200) != LI_ADDR { c8 = 0 }
  rg[R_RCX] = m_r64(mem, LI_ADDR + 0x18); rg[R_RDX] = 0x3100; rg[8] = 0x3208
  if emu_hook_call(mem, HOOK6, rg) != 0 { c8 = 0 }
  if m_r64(mem, 0x3208) != FS_ADDR { c8 = 0 }
  rg[R_RCX] = 0xDEAD; rg[R_RDX] = 0x3100; rg[8] = 0x3210
  if emu_hook_call(mem, HOOK6, rg) != (0 - 39) { c8 = 0 }
  rg[R_RCX] = FS_ADDR; rg[R_RDX] = 0x3218
  if emu_hook_call(mem, HOOK7, rg) != 0 { c8 = 0 }
  if m_r64(mem, 0x3218) != ROOT_ADDR { c8 = 0 }
  // Open() is NAME-AWARE now, so the test must present a real UTF-16LE name. The names are
  // RESTATED here as literals rather than read from esp_name_ch -- a test that borrows the
  // implementation's table cannot catch the implementation's typo.
  let knm: *u8 = "KERNEL.NXE" as *u8
  var ni: i64 = 0
  while knm[ni] != (0 as u8) { m_w16(mem, 0x3300 + ni * 2, knm[ni] as i64); ni = ni + 1 }
  m_w16(mem, 0x3300 + ni * 2, 0)
  let anm: *u8 = "NISHI.AI" as *u8
  var ai2: i64 = 0
  while anm[ai2] != (0 as u8) { m_w16(mem, 0x3340 + ai2 * 2, anm[ai2] as i64); ai2 = ai2 + 1 }
  m_w16(mem, 0x3340 + ai2 * 2, 0)
  let xnm: *u8 = "PASSWD.TXT" as *u8
  var xi: i64 = 0
  while xnm[xi] != (0 as u8) { m_w16(mem, 0x3380 + xi * 2, xnm[xi] as i64); xi = xi + 1 }
  m_w16(mem, 0x3380 + xi * 2, 0)
  rg[R_RCX] = ROOT_ADDR; rg[R_RDX] = 0x3220; rg[8] = 0x3300; rg[9] = 3
  if emu_hook_call(mem, HOOK8, rg) != (0 - 40) { c8 = 0 }
  rg[9] = 1
  if emu_hook_call(mem, HOOK8, rg) != 0 { c8 = 0 }
  if m_r64(mem, 0x3220) != FILE_ADDR { c8 = 0 }
  // NEG: a file this ESP does not serve is EFI_NOT_FOUND, never a silently-served handle.
  rg[R_RDX] = 0x3230; rg[8] = 0x3380
  m_w64(mem, 0x3230, 0)
  if emu_hook_call(mem, HOOK8, rg) != 0 { c8 = 0 }
  if rg[R_RAX] != EFI_NOT_FOUND { c8 = 0 }
  if m_r64(mem, 0x3230) != 0 { c8 = 0 }
  // The OPTIONAL assistant file: ABSENT (len 0) must be NOT_FOUND -- this is the DEFAULT state of
  // the toggle, and the state the loader must survive. Then present -> its own distinct handle.
  rg[R_RDX] = 0x3238; rg[8] = 0x3340
  m_w64(mem, 0x3238, 0)
  if emu_hook_call(mem, HOOK8, rg) != 0 { c8 = 0 }
  if rg[R_RAX] != EFI_NOT_FOUND { c8 = 0 }
  if m_r64(mem, 0x3238) != 0 { c8 = 0 }
  m_w64(mem, AIFILE_LEN, 4)
  var ab2: i64 = 0
  while ab2 < 4 { mem[AIFILE_DATA + ab2] = (0x61 + ab2) as u8; ab2 = ab2 + 1 }
  // FS-2: even WITH the file present, the BOOT volume must still refuse it -- the assistant file
  // lives on the DATA volume, and this is the check that makes "search every volume" testable.
  if emu_hook_call(mem, HOOK8, rg) != 0 { c8 = 0 }
  if rg[R_RAX] != EFI_NOT_FOUND { c8 = 0 }
  if m_r64(mem, 0x3238) != 0 { c8 = 0 }
  rg[R_RCX] = ROOT2_ADDR
  if emu_hook_call(mem, HOOK8, rg) != 0 { c8 = 0 }
  if m_r64(mem, 0x3238) != AIFILE_ADDR { c8 = 0 }
  // and the DATA volume must NOT serve the kernel: one file, one home.
  rg[R_RDX] = 0x3248; rg[8] = 0x3300
  m_w64(mem, 0x3248, 0)
  if emu_hook_call(mem, HOOK8, rg) != 0 { c8 = 0 }
  if rg[R_RAX] != EFI_NOT_FOUND { c8 = 0 }
  // LocateHandleBuffer hands back BOTH device handles, by protocol, with a real count
  rg[R_RSP] = 0x7000
  m_w64(mem, 0x7020, 0x7100)
  rg[R_RCX] = 2; rg[R_RDX] = 0x3100; rg[8] = 0; rg[9] = 0x7108
  if emu_hook_call(mem, HOOK10, rg) != 0 { c8 = 0 }
  if m_r64(mem, 0x7108) != 2 { c8 = 0 }
  let hb: i64 = m_r64(mem, 0x7100)
  if m_r64(mem, hb) != DEV_HANDLE { c8 = 0 }
  if m_r64(mem, hb + 8) != DEV2_HANDLE { c8 = 0 }
  rg[R_RCX] = 1                                     // AllHandles must be REFUSED, not served
  if emu_hook_call(mem, HOOK10, rg) != (0 - 43) { c8 = 0 }
  rg[R_RCX] = ROOT_ADDR
  // and its Read serves the AI bytes, NOT the kernel's
  m_w64(mem, 0x3240, 64)
  rg[R_RCX] = AIFILE_ADDR; rg[R_RDX] = 0x3240; rg[8] = 0x3500
  if emu_hook_call(mem, HOOK9, rg) != 0 { c8 = 0 }
  if m_r64(mem, 0x3240) != 4 { c8 = 0 }
  var ax2: i64 = 0
  while ax2 < 4 { if (mem[0x3500 + ax2] as i64) != (0x61 + ax2) { c8 = 0 } ax2 = ax2 + 1 }
  m_w64(mem, AIFILE_LEN, 0)
  rg[R_RCX] = ROOT_ADDR; rg[R_RDX] = 0x3220; rg[8] = 0x3300; rg[9] = 1
  if emu_hook_call(mem, HOOK8, rg) != 0 { c8 = 0 }
  m_w64(mem, 0x3228, 64)
  rg[R_RCX] = FILE_ADDR; rg[R_RDX] = 0x3228; rg[8] = 0x3400
  if emu_hook_call(mem, HOOK9, rg) != 0 { c8 = 0 }
  if m_r64(mem, 0x3228) != 8 { c8 = 0 }
  var rb2: i64 = 0
  while rb2 < 8 { if (mem[0x3400 + rb2] as i64) != (0x41 + rb2) { c8 = 0 } rb2 = rb2 + 1 }
  if c8 == 1 { pass = pass + 1; e_p("EMU-T8 esp-file-chain GREEN
1092" as *u8) } else { e_p("EMU-T8 RED
1093" as *u8) }
1094
  let lf: i64 = sys_openat_append("knowledge/status/nishi_os.log" as *u8, 0x1a4)
  if lf >= 0 {
      e_fp(lf, "NOSEMU selftest teeth=" as *u8); e_fn(lf, pass); e_fp(lf, "of8 verdict=" as *u8)
      if pass == 8 { e_fp(lf, "GREEN\n" as *u8) } else { e_fp(lf, "RED\n" as *u8) }
      sys_close(lf)
  }
  if pass == 8 {
      e_p("EMU-SELFTEST GREEN 8/8\n" as *u8)
      sys_exit(0); return 0
  }
  e_p("EMU-SELFTEST RED\n" as *u8)
  sys_exit(1); return 1
1107}
1108
1109func main(argc: i64, argv: *i64) -> i64 {
  var path: *u8 = "_offc/nx_boot_uefi.efi" as *u8
  if argc >= 2 { path = argv[1] as *u8 }
  if argc >= 2 { if s_eq(path, "selftest" as *u8) == 1 { return emu_selftest() } }
1113
  // load the .efi
  let lenp: *i64 = sys_mmap(16) as *i64
  let fb: *u8 = sys_read_file(path, lenp)
  let flen: i64 = lenp[0]
  if flen <= 0 { e_p("NOS-EXEC REFUSED: cannot read " as *u8); e_p(path); e_p("\n" as *u8); sys_exit(2); return 2 }
1119
  // parse the PE: entry RVA + first section (.text) load
  let entry: i64 = f_u32(fb, 0x98 + 16)
  let vaddr: i64 = f_u32(fb, 0x188 + 12)
  let rawsz: i64 = f_u32(fb, 0x188 + 16)
  let rawptr: i64 = f_u32(fb, 0x188 + 20)
1125
  let mem: *u8 = sys_mmap(MEMSZ)
  var i: i64 = 0
  while i < rawsz { mem[vaddr + i] = fb[rawptr + i]; i = i + 1 }
1129
  // mock UEFI: SystemTable + ConOut + FirmwareVendor string, OutputString = HOOK sentinel
  m_w64(mem, ST_ADDR + 0x18, FV_ADDR)     // SystemTable->FirmwareVendor
  m_w64(mem, ST_ADDR + 0x40, CO_ADDR)     // SystemTable->ConOut
  m_w64(mem, CO_ADDR + 0x08, HOOK)        // ConOut->OutputString
  m_w64(mem, ST_ADDR + 0x30, CI_ADDR)     // SystemTable->ConIn
  m_w64(mem, CI_ADDR + 0x08, HOOK4)       // ConIn->ReadKeyStroke (hook, scripted queue)
  m_w64(mem, ST_ADDR + 0x60, BS_ADDR)     // SystemTable->BootServices
  m_w64(mem, BS_ADDR + 0x38, HOOK2)       // BootServices->GetMemoryMap (hook)
  m_w64(mem, BS_ADDR + 0xE8, HOOK5)       // BootServices->ExitBootServices (UEFI spec offset)
  m_w64(mem, BS_ADDR + 0x98, HOOK6)       // BootServices->HandleProtocol
  m_w64(mem, BS_ADDR + 0x138, HOOK10)     // BootServices->LocateHandleBuffer (FS-2 volume search)
  m_w64(mem, FS2_ADDR + 0x08, HOOK7)      // the DATA volume's OpenVolume
  m_w64(mem, ROOT2_ADDR + 0x08, HOOK8)    // its root Open
  m_w64(mem, LI_ADDR + 0x18, DEV_HANDLE)  // LoadedImage->DeviceHandle (the ESP we booted from)
  m_w64(mem, FS_ADDR + 0x08, HOOK7)       // SimpleFileSystem->OpenVolume
  m_w64(mem, ROOT_ADDR + 0x08, HOOK8)     // EFI_FILE->Open
  m_w64(mem, FILE_ADDR + 0x20, HOOK9)     // EFI_FILE->Read
  m_w64(mem, AIFILE_ADDR + 0x20, HOOK9)   // the OPTIONAL assistant file needs its OWN Read slot.
                                          // Omitting it made [rcx+0x20] read 0 and the loader
                                          // `call rax` jumped to address 0 -- the emulator refused
                                          // with EMU-UNDECODED at pc=0 rather than pretending.
                                          // A SECOND HANDLE IS A SECOND VTABLE, NOT A SECOND NAME.
  m_w64(mem, BS_ADDR + 0x140, HOOK3)      // BootServices->LocateProtocol (hook, GUID-checked)
  m_w64(mem, GOP_ADDR + 0x18, MODE_ADDR)  // gop->Mode
  m_w64(mem, MODE_ADDR + 0x18, FB_ADDR)   // Mode->FrameBufferBase (a real in-MEM framebuffer)
  m_w64(mem, MODE_ADDR + 0x20, FB_SIZE)   // Mode->FrameBufferSize = 1280x800x4 (mirrors the OVMF oracle mode)
  // FirmwareVendor = UTF-16 "NISHI-FW"
  m_w16(mem, FV_ADDR + 0,  0x4E); m_w16(mem, FV_ADDR + 2,  0x49); m_w16(mem, FV_ADDR + 4,  0x53)
  m_w16(mem, FV_ADDR + 6,  0x48); m_w16(mem, FV_ADDR + 8,  0x49); m_w16(mem, FV_ADDR + 10, 0x2D)
  m_w16(mem, FV_ADDR + 12, 0x46); m_w16(mem, FV_ADDR + 14, 0x57); m_w16(mem, FV_ADDR + 16, 0x00)
1160
  // scripted keyboard: nx_emu_uefi <img> --keys <ascii-string>  (each char = one ReadKeyStroke
  // SUCCESS in order; the queue then reports NOT-READY forever, exactly like idle firmware)
  var nkeys: i64 = 0
  if argc >= 4 {
      if s_eq(argv[2] as *u8, "--keys" as *u8) == 1 {
          let ks: *u8 = argv[3] as *u8
          while ks[nkeys] != (0 as u8) {
              m_w64(mem, KEYQ_ADDR + 16 + nkeys * 16, 0)                 // ScanCode 0 = a unicode key
              m_w64(mem, KEYQ_ADDR + 16 + nkeys * 16 + 8, ks[nkeys] as i64)
              nkeys = nkeys + 1
          }
          m_w64(mem, KEYQ_ADDR, nkeys)
          m_w64(mem, KEYQ_ADDR + 8, 0)
          var pk: i64 = 0
          while pk < nkeys {
              m_w64(mem, PS2_STATE + 16 + pk * 8, ks[pk] as i64)
              pk = pk + 1
          }
          m_w64(mem, PS2_STATE, nkeys)
          m_w64(mem, PS2_STATE + 8, 0)
      }
  }
1183
  // N1-full: --kernel <file> makes the modeled ESP serve REAL bytes -- a harness that invents
  // file contents proves nothing. Scanned at ANY argv position (the --keys positional trap is
  // not being extended to a second flag). Without --kernel the served length is 0, Read hands
  // back nothing, and the shim's magic check takes its NXE! refusal path -- so the missing-file
  // negative control costs nothing to run.
  var ka: i64 = 2
  while (ka + 1) < argc {
      if s_eq(argv[ka] as *u8, "--aifile" as *u8) == 1 {
          let alp: *i64 = sys_mmap(16) as *i64
          let ab: *u8 = sys_read_file(argv[ka + 1] as *u8, alp)
          let alen: i64 = alp[0]
          if alen <= 0 { e_p("NOS-EXEC REFUSED: cannot read --aifile\n" as *u8); sys_exit(2); return 2 }
          if alen > 0x100000 { e_p("NOS-EXEC REFUSED: --aifile exceeds the modeled window (0x100000)\n" as *u8); sys_exit(2); return 2 }
          var ac: i64 = 0
          while ac < alen { mem[AIFILE_DATA + ac] = ab[ac]; ac = ac + 1 }
          m_w64(mem, AIFILE_LEN, alen)
      }
      // --mmsize <bytes>: pin the modeled GetMemoryMap size. Real EDK2 returned 0x18F0 where this
      // organ models 0x1800 (debt 1786237098), so a rung that needs to assert a ram-map value must
      // be able to state the one it MEASURED rather than inherit ours. Decimal.
      if s_eq(argv[ka] as *u8, "--mmsize" as *u8) == 1 {
          let mmv: i64 = s_atoi(argv[ka + 1] as *u8)
          if mmv <= 0 { e_p("NOS-EXEC REFUSED: --mmsize must be a positive decimal byte count\n" as *u8); sys_exit(2); return 2 }
          m_w64(mem, MM_SIZE_SLOT, mmv)
          e_p("NOS-MMSIZE: modeled GetMemoryMap size PINNED to " as *u8); e_fn(1, mmv)
          e_p(" (default " as *u8); e_fn(1, MM_REQ_BYTES); e_p(" is a MODEL, not a measurement)\n" as *u8)
      }
      if s_eq(argv[ka] as *u8, "--kernel" as *u8) == 1 {
          let klp: *i64 = sys_mmap(16) as *i64
          let kb: *u8 = sys_read_file(argv[ka + 1] as *u8, klp)
          let klen: i64 = klp[0]
          if klen <= 0 { e_p("NOS-EXEC REFUSED: cannot read --kernel file\n" as *u8); sys_exit(2); return 2 }
          if klen > 0x60000 { e_p("NOS-EXEC REFUSED: --kernel exceeds the modeled ESP window (0x60000)\n" as *u8); sys_exit(2); return 2 }
          var kc: i64 = 0
          while kc < klen { mem[KFILE_DATA + kc] = kb[kc]; kc = kc + 1 }
          m_w64(mem, KFILE_LEN, klen)
      }
      ka = ka + 1
  }
1223
  let out: *u8 = sys_mmap(512)
  var tracen: i64 = 0
  if argc >= 3 { if s_eq(argv[2] as *u8, "--trace" as *u8) == 1 { tracen = 1 } }
  let outn: i64 = emu_run(mem, entry, out, tracen)
1228
  // -30 = the step cap. For an EVENT-LOOP kernel that is NOT an error: a live poll loop is what
  // an OS does. Judge it the same way as a hold -- by MEASURING the screen it owns.
  if outn == (0 - 90) { } else { if outn == (0 - 30) { } else { if outn < 0 {
      e_p("NOS-EXEC RED: interpreter sentinel " as *u8); e_fn(1, outn); e_p(" on " as *u8); e_p(path); e_p("\n" as *u8)
      let lf3: i64 = sys_openat_append("knowledge/status/nishi_os.log" as *u8, 0x1a4)
      if lf3 >= 0 { e_fp(lf3, "NOSEXEC name=" as *u8); e_fp(lf3, path); e_fp(lf3, " err=" as *u8); e_fn(lf3, outn); e_fp(lf3, " verdict=RED\n" as *u8); sys_close(lf3) }
      sys_exit(1); return 1
  } } }
1237
  if outn == (0 - 30) {                   // live event loop: measure, report keys consumed
      let fbb2: i64 = m_r64(mem, MODE_ADDR + 0x18)
      let fbs2: i64 = m_r64(mem, MODE_ADDR + 0x20)
      let m2: *i64 = sys_mmap(48) as *i64
      fb_measure(mem, fbb2, fbs2, m2)
      let drained: i64 = m_r64(mem, KEYQ_ADDR + 8)
      px_probe(mem, fbb2, argc, argv)
      let hv2: i64 = hold_verdict(m2[0], m2[1], m2[2], m2[3], m2[4])
      shot_if_asked(mem, fbb2, argc, argv)
      let ebs: i64 = m_r64(mem, EBS_STATE)
      e_p("NOS-EXEC: " as *u8); e_p(path); e_p(" RUNS an event loop; keys_consumed=" as *u8)
      e_fn(1, drained); e_p("/" as *u8); e_fn(1, nkeys); e_p(" zeros=" as *u8); e_fn(1, m2[3])
      e_p(" transitions=" as *u8); e_fn(1, m2[4])
      e_p(" firmware_exited=" as *u8); e_fn(1, ebs); e_p("\n" as *u8)
      // every scripted key must actually have been READ. Scripting NO keys is not a failure --
      // it proves the screen, just not the input; say exactly that instead of crying RED.
      var kok: i64 = 0
      if drained == nkeys { kok = 1 }
      let lf4: i64 = sys_openat_append("knowledge/status/nishi_os.log" as *u8, 0x1a4)
      if lf4 >= 0 {
          e_fp(lf4, "NOSRUN name=" as *u8); e_fp(lf4, path)
          e_fp(lf4, " executed=sovereign-x86-emu loop=1 keys_consumed=" as *u8); e_fn(lf4, drained)
          e_fp(lf4, " of=" as *u8); e_fn(lf4, nkeys)
          e_fp(lf4, " zeros=" as *u8); e_fn(lf4, m2[3])
          e_fp(lf4, " transitions=" as *u8); e_fn(lf4, m2[4])
          e_fp(lf4, " firmware_exited=" as *u8); e_fn(lf4, ebs)
          e_fp(lf4, " verdict=" as *u8)
          if hv2 > 0 { if kok == 1 { e_fp(lf4, "RUNNING-AND-PAINTED\n" as *u8) } else { e_fp(lf4, "RED\n" as *u8) } }
          else { e_fp(lf4, "RED\n" as *u8) }
          sys_close(lf4)
      }
      if hv2 > 0 { if kok == 1 {
          e_p("NOS-EXEC GREEN: RUNNING-AND-PAINTED -- the kernel owns the screen" as *u8)
          if nkeys > 0 { e_p(" AND consumed every scripted keystroke" as *u8) } else { e_p(" (no keys scripted: input not exercised)" as *u8) }
          e_p(" (sovereign, no qemu)\n" as *u8)
          sys_exit(0); return 0
      } }
      e_p("NOS-EXEC RED: event loop ran but the screen or the key trace did not check out\n" as *u8)
      sys_exit(1); return 1
  }
1278
  if outn == (0 - 90) {                   // EB FE: the app parks HOLDING the screen -- measure, don't error
      let fbbase: i64 = m_r64(mem, MODE_ADDR + 0x18)
      let fbsize: i64 = m_r64(mem, MODE_ADDR + 0x20)
      let mm: *i64 = sys_mmap(48) as *i64
      fb_measure(mem, fbbase, fbsize, mm)
      let color: i64 = mm[0]
      let matches: i64 = mm[1]
      let ndw: i64 = mm[2]
      let zeros: i64 = mm[3]
      let trans: i64 = mm[4]
      var permil: i64 = 0
      if ndw > 0 { permil = (matches * 1000) / ndw }
      px_probe(mem, fbbase, argc, argv)
      let hv: i64 = hold_verdict(color, matches, ndw, zeros, trans)
      shot_if_asked(mem, fbbase, argc, argv)
      e_p("NOS-EXEC: " as *u8); e_p(path); e_p(" HOLDS (EB FE); modeled-GOP fill " as *u8)
      e_fn(1, matches); e_p("/" as *u8); e_fn(1, ndw); e_p(" dwords " as *u8); e_fn(1, permil)
      e_p(" permil zeros=" as *u8); e_fn(1, zeros); e_p(" transitions=" as *u8); e_fn(1, trans)
      e_p(" firmware_exited=" as *u8); e_fn(1, m_r64(mem, EBS_STATE))
      e_p(" ps2_consumed=" as *u8); e_fn(1, m_r64(mem, PS2_STATE + 8))
      e_p("/" as *u8); e_fn(1, m_r64(mem, PS2_STATE))
      e_p(" color=0x" as *u8); e_fx(1, color); e_p("\n" as *u8)
      let lf2: i64 = sys_openat_append("knowledge/status/nishi_os.log" as *u8, 0x1a4)
      if lf2 >= 0 {
          e_fp(lf2, "NOSEXEC name=" as *u8); e_fp(lf2, path)
          e_fp(lf2, " executed=sovereign-x86-emu hold=1 fb_dwords=" as *u8); e_fn(lf2, ndw)
          e_fp(lf2, " match_dwords=" as *u8); e_fn(lf2, matches)
          e_fp(lf2, " fill_permil=" as *u8); e_fn(lf2, permil)
          e_fp(lf2, " zeros=" as *u8); e_fn(lf2, zeros)
          e_fp(lf2, " transitions=" as *u8); e_fn(lf2, trans)
          e_fp(lf2, " firmware_exited=" as *u8); e_fn(lf2, m_r64(mem, EBS_STATE))
          e_fp(lf2, " ps2_consumed=" as *u8); e_fn(lf2, m_r64(mem, PS2_STATE + 8))
          e_fp(lf2, " color=0x" as *u8); e_fx(lf2, color)
          e_fp(lf2, " verdict=" as *u8)
          if hv == 1 { e_fp(lf2, "PAINTED-AND-HOLDING\n" as *u8) }
          if hv == 2 { e_fp(lf2, "SCENE-PAINTED-AND-HOLDING\n" as *u8) }
          if hv == 0 { e_fp(lf2, "RED\n" as *u8) }
          sys_close(lf2)
      }
      if hv == 1 {
          e_p("NOS-EXEC GREEN: PAINTED-AND-HOLDING -- the app filled 100.0% of the modeled framebuffer and holds the screen (sovereign, no qemu)\n" as *u8)
          sys_exit(0); return 0
      }
      if hv == 2 {
          e_p("NOS-EXEC GREEN: SCENE-PAINTED-AND-HOLDING -- every pixel written, composed multi-color scene, screen held (sovereign, no qemu)\n" as *u8)
          sys_exit(0); return 0
      }
      e_p("NOS-EXEC RED: the app holds but the modeled framebuffer is not fully painted\n" as *u8)
      sys_exit(1); return 1
  }
1329
  if outn < 0 {
      e_p("NOS-EXEC RED: interpreter sentinel " as *u8); e_fn(1, outn); e_p(" on " as *u8); e_p(path); e_p("\n" as *u8)
      let lf: i64 = sys_openat_append("knowledge/status/nishi_os.log" as *u8, 0x1a4)
      if lf >= 0 { e_fp(lf, "NOSEXEC name=" as *u8); e_fp(lf, path); e_fp(lf, " err=" as *u8); e_fn(lf, outn); e_fp(lf, " verdict=RED\n" as *u8); sys_close(lf) }
      sys_exit(1); return 1
  }
1336
  // assert: captured console output begins with the expected prefix (default "NISHI",
  // override via argv[2] so the gate is reusable per rung -- exact match keeps its teeth)
  out[outn] = 0 as u8
  var exp: *u8 = "NISHI" as *u8
  if argc >= 3 { exp = argv[2] as *u8 }
  var ok: i64 = 1
  var j: i64 = 0
  while exp[j] != (0 as u8) {
      if j >= outn { ok = 0 } else { if out[j] != exp[j] { ok = 0 } }
      j = j + 1
  }
  if j == 0 { ok = 0 }
1349
  e_p("NOS-EXEC: " as *u8); e_p(path); e_p(" entry=0x" as *u8); e_fn(1, entry)
  e_p(" captured-console=[" as *u8); sys_write(1, out, outn); e_p("] chars=" as *u8); e_fn(1, outn); e_p("\n" as *u8)
1352
  let lf: i64 = sys_openat_append("knowledge/status/nishi_os.log" as *u8, 0x1a4)
  if lf >= 0 {
      e_fp(lf, "NOSEXEC name=" as *u8); e_fp(lf, path)
      e_fp(lf, " executed=sovereign-x86-emu console_chars=" as *u8); e_fn(lf, outn)
      e_fp(lf, " expect=" as *u8); e_fp(lf, exp); e_fp(lf, " verdict=" as *u8)
      if ok == 1 { e_fp(lf, "GREEN\n" as *u8) } else { e_fp(lf, "RED\n" as *u8) }
      sys_close(lf)
  }
1361
  if ok == 1 {
      e_p("NOS-EXEC GREEN: emitted .efi EXECUTES on the sovereign x86 emu and prints the expected output (boot-proof, no qemu/laptop)\n" as *u8)
      sys_exit(0); return 0
  }
  e_p("NOS-EXEC RED: console output did not begin with the expected prefix\n" as *u8)
  sys_exit(1); return 1
1368}
nx_emu_uefi.nx source

`nx_emu_uefi.nx` source
