kernel: validate learned semaphore maps and post guest GPU events

- admit {GPU VA -> PA} pairs only when the preceding bytes form a valid
  client memory descriptor header (type 0/1, CPU+GPU mapped bits), prefer
  validated pairs over headerless candidates under first-wins dedup, and
  invalidate the translation cache on every rebuild; fixes stale identity
  entries shadowing live pool pages and lets the guest UVM channel
  bring-up complete on its own
- capture OS event allocations (class 0x79) and post event records
  (function 0x1003) into the guest status queue when a channel's busy
  notification is consumed, with a broadcast fallback, serialized with
  replies via a queue lock
- add BAR0 shadow introspection (dump_bar0/scan_bar0) and guest-side
  diagnostic scripts for the VM cycle

1 files changed, 18 insertions, 0 deletions

diff --git a/docs/03-architecture/06-host-module-and-hybrid-model.md b/docs/03-architecture/06-host-module-and-hybrid-model.md
index 5849071..15545a4 100644
--- a/docs/03-architecture/06-host-module-and-hybrid-model.md
+++ b/docs/03-architecture/06-host-module-and-hybrid-model.md
@@ -175,6 +175,23 @@ interface). That is enough to:
 * inspect push buffers and page tables,
 * and later, create page tables for server-owned ranges.
 
+Releases are recognised in the decoded method stream in both of the encodings
+the driver uses: the copy-engine `SET_SEMAPHORE_A/B` + `LAUNCH_DMA` group and
+the TURING+ `SET_REPORT_SEMAPHORE_A..D` group
+(`{offset_upper, offset_lower, payload, operation}`, operation 0 = release),
+which is how the host class ends a push. The learned translation cache is
+page-granular, so all semaphore slots of one page resolve from one entry.
+
+One class of pages is not derivable from the structures above: client
+mappings created by `mmap()` on the control device, where the kernel driver
+maps sysmem pages into the process and the *same* numeric address doubles as
+the GPU VA (observed live: a 2 MB shared mapping of the control device, and
+push releases whose semaphore address equals the mapped client VA). Those
+pages have no leaf PTEs in the GPU page tables (the client delegates them),
+and the kernel-side bookkeeping records physical pages without a GPU VA.
+Until a durable join is implemented, a session can feed verified pairs with
+the `sema_map_add` debug parameter.
+
 ## 5. The forwarding path (design)
 
 ```
@@ -219,6 +236,7 @@ emulated device inspectable without rebuilding:
 | `poke_fill=<gpa>,<v>,<n>` | fill a range |
 | `fill_vidmem=<v>` | fill the VRAM shadow |
 | `sema_probe=<gpu_va>[,count]` | probe a semaphore VA and nearby state in guest memory |
+| `sema_map_add=<va>,<pa>` | teach the service one verified `{GPU VA -> guest PA}` pair |
 | `dump_guest=<gpa>,<len>` | dump guest physical memory (length capped) |
 
 These are development-grade but production-useful: they are how the memory