feat: add host-side vgpu-perception library

Read-only consumer of the vgpu region: discovers it by structural invariants, samples frames and reads cursor/geometry/status under seqlock, and builds (never writes) the control frame. Built as a separate host CMake project; the memory-model dependency source path is supplied via -DLIBVMIE_PATH at configure time.

src/perception/CMakeLists.txt

@@ -0,0 +1,40 @@
+cmake_minimum_required(VERSION 3.18)              # add_subdirectory of vmie (needs find_program REQUIRED)
+project(vgpu-perception C)                        # standalone host project, native gcc
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+set(CMAKE_C_EXTENSIONS OFF)
+
+# vmie is our own library — reference its SOURCES by path, never a third_party copy.
+# LIBVMIE_PATH is supplied from OUTSIDE at configure time → no private path in the tree.
+set(LIBVMIE_PATH "" CACHE PATH "Path to the vmie library source tree (host memory model)")
+if(NOT LIBVMIE_PATH)
+    message(FATAL_ERROR "vgpu-perception: set -DLIBVMIE_PATH=/path/to/vmie/sources")
+endif()
+
+# Build vmie's static lib from its own sources. EXCLUDE_FROM_ALL: only the `vmie`
+# target we link is built (not vmie's CLI/scan demos or its guest exe). memmodel.h
+# arrives transitively via the vmie target's PUBLIC include dir — no manual include,
+# no vendored header to keep in sync.
+add_subdirectory(${LIBVMIE_PATH} ${CMAKE_BINARY_DIR}/vmie-build EXCLUDE_FROM_ALL)
+
+set(REPO ${CMAKE_CURRENT_SOURCE_DIR}/../..)       # repo root (this lives in src/perception)
+
+add_library(vgpu-perception STATIC
+    discover.c
+    sample.c
+    control.c)
+target_include_directories(vgpu-perception
+    PUBLIC  ${REPO}/include                        # vgpu_perception.h, vgpu_stream.h
+    PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include)   # perception-internal.h
+target_link_libraries(vgpu-perception PUBLIC vmie) # memmodel.h include comes transitively
+target_compile_options(vgpu-perception PRIVATE -O2 -Wall -Wextra)
+
+# table-driven test: invariant predicates + flat sampling smoke
+enable_testing()
+add_executable(vgpu-perception-test test/test_perception.c)
+target_include_directories(vgpu-perception-test
+    PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include)   # memmodel.h via vgpu-perception -> vmie (transitive)
+target_link_libraries(vgpu-perception-test PRIVATE vgpu-perception)
+target_compile_options(vgpu-perception-test PRIVATE -O2 -Wall -Wextra)
+add_test(NAME vgpu-perception-test COMMAND vgpu-perception-test)