vgsp: m91 - first-fault capture + QMD instruction-cache invalidate for the SM I-fetch lottery

m91-class recap: the first attempt of a mid-sequence forwarded GR launch
raises SM warp exceptions ("Illegal Instruction Encoding", "Out Of Range
Register") on garbage instruction bytes while a retry of the IDENTICAL QMD
and identical shadow content succeeds (r219: fault at +2.5 s, fast re-arm
recovered 3 ms later; r223 same pattern). The host retry path only replays
the mode-35 lane-enable tail + channel/TSG schedules + doorbell and
re-publishes the same method block on a fresh ring entry: no shadow re-copy,
no QMD re-read, no cache/TLB invalidate exists anywhere in the ladder. Plain
re-submission of byte-identical content flipping the outcome names stale
engine-side fetch state at first dispatch, not a content or programming
error: the window-0 shadow pool alternates two 8-page banks by submit
epoch, so a program VA's bytes change every two launches, and every
captured guest QMD carries the QMD v2.3 cache-control word (word 5) with
INVALIDATE_INSTRUCTION_CACHE (bit 30) clear - the client driver arms that
bit only under its forced-invalidate mode.

Two changes:

1. FAULT-CAP (diagnostic, inert until a fault): when a forwarded launch's
   fault epoch advanced across its window, emit one "vgsp-m91: FAULT-CAP"
   line per launch (capped at 20 per module-load cycle, then one
   suppression notice) with: fault-epoch delta, QMD address + first 64 B,
   live program pair (w48/w49) + resolved engine-visible VA/PA, the first
   64 B at that code address, retry decision (fast re-arm /
   resched/fresh-entry / none) + outcome (ok vs timeout), and the newest
   relay-decoded 0x1006 note (exceptType/chid/errString). A fault-free
   launch costs one epoch read and one compare (greens unaffected
   statically: no prints, no content reads, no engine access).

2. QMD icache invalidate (fix, param-gated default-on
   gsp_phys_gr_icache_inv=1): set QMD v2.3 word 5 bit 30 in the forwarded
   QMD (forcing an instruction refetch at dispatch) only when the QMD
   carries the client driver's standard cache-control signature (word 5
   bits 26..29 set) so an unknown QMD revision is never touched; 0 restores
   the exact pre-change QMD for a one-flip A/B. The bit cannot alter
   instruction bytes or data - it only invalidates cached fetch state (the
   same field the client driver sets under forced invalidate) - so green
   launches keep their semantics; the only cost is a per-launch refetch.

Expected next-cycle evidence: zero FAULT-CAP lines with the multi-page
client set green confirms the stale-fetch mechanism; any FAULT-CAP content
policies the remaining candidates (shadow-VA reuse distance, cross-cycle
context state left by killed clients). Doc: 03-architecture/13-vexecution-
plane.md m91-class section.

(cherry picked from commit 682a5559b1dbbd482d8fe6bdabbc46220ce0d5de)

1 files changed, 48 insertions, 0 deletions

diff --git a/docs/03-architecture/13-vexecution-plane.md b/docs/03-architecture/13-vexecution-plane.md
index 733da13..caaad01 100644
--- a/docs/03-architecture/13-vexecution-plane.md
+++ b/docs/03-architecture/13-vexecution-plane.md
@@ -1038,6 +1038,53 @@ technical barrier between the project's architecture and its promise.
 
 ---
 
+## m91-class I-fetch faults: capture and icache coherence (2026-10-18)
+
+The physical submit's remaining transient failure class ("m91 class" after the
+trap-decode campaign that first named the SM instruction-fetch signature) has
+two observable faces. In one, the first attempt of a mid-sequence launch
+raises SM warp exceptions ("Illegal Instruction Encoding", "Out Of Range
+Register") on garbage instruction bytes while the engine-authored release
+stays at its failure value, and a retry of the *identical* QMD and shadow
+content succeeds. In the other, the launch reports fetch success but writes
+nothing (dispatch loss). The submit retry that recovers the first face is the
+fast re-arm: the same method block is re-published on a fresh GPFIFO ring
+entry and the mode-35 lane-enable tail plus channel/TSG schedules and the
+doorbell are re-issued — no shadow re-copy, no QMD re-read, no content
+change. Identical content flipping outcome across attempts is the signature
+of stale engine-side fetch state, not a content or relocation error.
+
+Two code changes follow from that:
+
+* **FAULT-CAP (diagnostic).** When a forwarded launch's fault epoch advanced
+  across its window, the submit emits one `vgsp-m91: FAULT-CAP` line per
+  launch (capped at 20 per module-load cycle, then one suppression notice):
+  fault-epoch delta, the forwarded QMD address and first 64 B, the live
+  program pair (word 48/49 read) with its resolved engine-visible VA/PA, the
+  first 64 B at that code address, the retry decision (fast re-arm /
+  resched/fresh-entry / none) and outcome (ok vs timeout), and the newest
+  relay-decoded fault note (exceptType, chid, errString). It is inert on a
+  fault-free launch: one epoch read and one compare.
+* **icache coherence (fix, default on).** The window-0 shadow pool alternates
+  two 8-page banks by submit epoch, so the bytes at a program VA change every
+  two launches, while the captured guest QMDs carry the QMD v2.3
+  cache-control word (word 5) with the
+  `INVALIDATE_INSTRUCTION_CACHE` bit (bit 30) clear — the field the client
+  driver arms only under its forced-invalidate mode. The submit now sets
+  that bit in the forwarded QMD when the QMD carries the driver's standard
+  cache-control signature (word 5 bits 26..29 set), forcing an instruction
+  fetch at dispatch and removing the stale-line window; an unknown QMD
+  revision is never touched, and `gsp_phys_gr_icache_inv=0` restores the
+  exact pre-change QMD for a one-flip A/B. Setting the bit cannot alter
+  instruction bytes or data — it only invalidates cached fetch state — so
+  green launches keep their semantics.
+
+The next physical cycle's evidence is the FAULT-CAP lines (or their absence)
+against the four-client class: zero FAULT-CAP lines with the four clients
+green confirms the stale-fetch mechanism; FAULT-CAP content policies the
+remaining candidates (shadow-VA reuse distance, cross-cycle context state
+left by killed clients).
+
 ## See also
 
 * [`01-system-overview.md`](01-system-overview.md) — principles and layer map
@@ -1057,3 +1104,4 @@ technical barrier between the project's architecture and its promise.
 |---|---|
 | 2026-10-08 | Created: canonical name (vGSP Execution Plane, vEP), four domains, component/data-flow/mode-matrix diagrams, discovery/truth/release/completion/submit reality, GR chain vocabulary, arbitrary-CUDA program, challenges, iteration plan, portability paths, CUDA/architecture mapping, future gaps, 3D interaction, framing. Tree `66388560`. |
 | 2026-10-08 | Review pass: status hash refreshed to `master @ 1f571dda`; drifted line anchors updated for the post-`66388560` code (`svc_thread`, `svc_gr_request`, `svc_pending_add`, H3 guard, readiness gate); GR completion §3.4/§6.1 reconciled with FORENSICS-grv5 (wake-up fires; the counter publication is the leading reading); discovery cadence wording corrected (2-second paced passes, not "milliseconds"); mode-matrix source note corrected. |
+| 2026-10-18 | m91-class I-fetch section: FAULT-CAP first-fault capture (`vgsp-m91: FAULT-CAP`, 20/cycle) and the default-on forwarded-QMD instruction-cache invalidate (`gsp_phys_gr_icache_inv`) with the retry-state analysis (identical content, fresh ring entry + lane-enable replay; stale engine-side fetch state at reused shadow VAs). |