Split the library into CORE / ENGINE / HANDLERS layers

CORE (src/core): vmie_mem — guest-physical substrate with a data-driven
segment map (replaces the hardcoded 4 GiB PCI-hole topology). ENGINE
(src/engine): x86-64 paging + Windows bring-up; produces the generic memory
model. HANDLERS (src/handlers): the signature/value/pointer scanners, which
now consume an OS-agnostic contract.

Keystone: gva_ctx is split into vmie_mem (core) + vmie (engine); the generic
access functions take vmie_mem* + cr3 and no longer compile in the Windows
offset table. New public contract include/memmodel.h (vmie_mem, mem_view_t,
vregion, task, range, the gva_* access); win32 surface in include/vmie.h.
Leak relocations: the PE parser, UTF-16 decode and CR3-recovery heuristics
move engine-side; the matcher stays a pure, source-agnostic handler, and the
pointer scanner takes a generic range[] instead of reaching into the process
enumerator.

src/core/gpa.c

@@ -0,0 +1,149 @@
+#include <stdint.h>
+#include <stddef.h>
+#include <string.h>
+#include <fcntl.h>
+#include <unistd.h>
+#include <sys/mman.h>
+#include <sys/stat.h>
+#include "core.h"
+
+#define RAM_H   (1ul<<32)
+#define PROT_RW (PROT_READ | PROT_WRITE)
+
+static void clean_ctx(vmie_mem* m) {
+    memset(m, 0, sizeof(vmie_mem));
+    m->fd = -1;
+}
+
+/* Resolve GPA `g` over the segment map: on success returns the seg covering it
+ * and the file offset of `g`; NULL if `g` falls outside every seg (a hole). The
+ * `g - s->gpa < s->len` test is one branch and folds the lower+upper bound. */
+__attribute__((hot))
+static const gpa_seg* gpa_seg_of(const vmie_mem* m, uint64_t g, uintptr_t* off) {
+    for (int i = 0; i < m->nseg; i++) {
+        const gpa_seg* s = &m->seg[i];
+        const uint64_t rel = g - s->gpa;
+        if (rel < s->len) {
+            *off = (uintptr_t)(s->file_off + rel);
+            return s;
+        }
+    }
+    return NULL;
+}
+
+/* `*offs` (a GPA) resolves to an in-file offset AND the whole [*, *+nmemb) range
+ * fits within its single seg. `nmemb > s->len - rel` is at once the file-bounds
+ * check and the no-straddle/seam reject (a range may not cross a seg boundary). */
+__attribute__((hot))
+static int out_of_bounds(vmie_mem* m, uintptr_t* offs, const size_t nmemb) {
+    const uint64_t g = *offs;
+    const gpa_seg* s = gpa_seg_of(m, g, offs);
+    return !s || nmemb > s->len - (g - s->gpa);
+}
+
+__attribute__((hot))
+int gpa_read(vmie_mem* m, uintptr_t offs, void* buf, const size_t nmemb) {
+    if (out_of_bounds(m, &offs, nmemb)) {
+        return -1;
+    }
+    memcpy(buf, m->pa + offs, nmemb);
+    return 0;
+}
+
+int gpa_write(vmie_mem* m, uintptr_t offs, const void* src, const size_t nmemb) {
+    if (out_of_bounds(m, &offs, nmemb)) {
+        return -1;
+    }
+    memcpy(m->pa + offs, src, nmemb);
+    return 0;
+}
+
+/* Zero-copy host pointer to [offs, offs+nmemb) GPA, or NULL if that range is not
+ * fully backed by the mapped image. Same split + bounds check as gpa_read. */
+__attribute__((hot))
+void* gpa_ptr(vmie_mem* m, uintptr_t offs, const size_t nmemb) {
+    if (out_of_bounds(m, &offs, nmemb)) {
+        return NULL;
+    }
+    return (uint8_t*)m->pa + offs;
+}
+
+/* segment table is well-formed against fsize: nonempty, in range, sorted, dense
+ * (each seg starts where the previous file span ended), all spans in-file. */
+static int segs_valid(const gpa_seg* segs, int nseg, uint64_t fsize) {
+    if (nseg < 1 || nseg > VMIE_MAX_SEGS) {
+        return 0;
+    }
+    uint64_t foff = 0;
+    for (int i = 0; i < nseg; i++) {
+        if (segs[i].file_off != foff
+            || segs[i].len == 0
+            || segs[i].len > fsize - foff
+            || (i > 0 && segs[i].gpa < segs[i - 1].gpa + segs[i - 1].len)) {
+            return 0;
+        }
+        foff += segs[i].len;
+    }
+    return 1;
+}
+
+__attribute__((cold))
+int gpa_open_segs(vmie_mem* m, const char* path, const gpa_seg* segs, int nseg) {
+    struct stat st;
+
+    if ((m->fd = open(path, O_RDWR)) < 0) {
+        goto ret_;
+    }
+
+    if (fstat(m->fd, &st) || !segs_valid(segs, nseg, (uint64_t)st.st_size)) {
+        goto close_;
+    }
+
+    if ((m->pa = mmap(NULL, st.st_size, PROT_RW, MAP_SHARED, m->fd, 0)) == MAP_FAILED) {
+      close_:
+        close(m->fd);
+      ret_:
+        clean_ctx(m);
+        return -1;
+    }
+
+    m->fsize = st.st_size;
+    m->nseg  = nseg;
+    memcpy(m->seg, segs, (size_t)nseg * sizeof *segs);
+
+    return 0;
+}
+
+/* Convenience: the classic single-`low` QEMU map. Below the 4 GiB PCI hole the
+ * file maps 1:1 ([0,low)->file[0,low)); at and above 4 GiB it resumes at file
+ * offset low. When low >= fsize the hole is never reached, so one inert identity
+ * seg covering the whole image suffices. */
+__attribute__((cold))
+int gpa_open(vmie_mem* m, const char* path, uintptr_t low) {
+    struct stat st;
+    if (stat(path, &st)) {
+        clean_ctx(m);
+        return -1;
+    }
+    const uint64_t fsize = (uint64_t)st.st_size;
+
+    const gpa_seg one[1] = { { 0, fsize, 0 } };
+    const gpa_seg two[2] = { { 0, low, 0 }, { RAM_H, fsize > low ? fsize - low : 0, low } };
+    const gpa_seg* segs = low >= fsize ? one : two;
+    const int      nseg = low >= fsize ? 1 : 2;
+
+    return gpa_open_segs(m, path, segs, nseg);
+}
+
+__attribute__((cold))
+void gpa_close(vmie_mem* m) {
+    if (m->pa) {
+        munmap(m->pa, m->fsize);
+    }
+
+    if (m->fd >= 0) {
+        close(m->fd);
+    }
+
+    clean_ctx(m);
+}