docs(cuinterpose): explain host carriers, memory IPC, and restore ordering

[galletas1712]

Summary

Refs #295 (approved).

Describe the implemented host-carrier-only design in concrete terms: processes, threads, CUDA calls, allocation ownership, tickets, memory costs, and failure behavior.

Review boundary

Includes capture and restore sequence diagrams, four multicast restore operations, the intercepted-API table, simplified pseudocode, namespace limits, and artifact compatibility. PageBroker/CustomStorage is separate work, not a shim backend. A two-worker example connects the fixed-layout VMM ticket and peer request to allocation/mapping records in cuinterpose.state; additional examples show the inline IPC ticket, multicast binding, host-carrier ownership, and manifest. Binary encodings and abbreviated excerpts are labeled explicitly. All six YAML examples parse, and all four diagrams pass Mermaid 11 syntax validation.

Stack and compatibility

The stack starts directly on main; it does not depend on the PageBroker GPU-transfer branch or #323. The shim only saves shared creator bytes through host carriers. Never-shared allocations remain native CUDA state. The stack removes launch-job/jobfile support, and older jobfile-dependent or draft shim artifacts are rejected rather than migrated.

PageBroker and native CustomStorage changes are separate. No PR in this stack adds that implementation.

Order	PR	Scope
1	#326	C preload frontend and private ABI
2	#327	typed identities and peer transport
3	#328	process identity and peer export service
4	#329	VMM ownership and allocation lifecycle
5	#342	implement CUDA memory IPC over tracked VMM
6	#330	host-carrier storage for shared allocation bytes
7	#331	multicast tracking and reconstruction
8	#332	Rust lifecycle coordinator
9	#333	package frontend, Rust backend, and coordinator
10	#334	deliver CUDA tools and enable opt-in preload
11	#335	coordinate cuinterpose capture and restore without jobfiles
12	#336	deliver CUDA tools without rewriting workload commands
13	#337	explain host carriers, memory IPC, and restore ordering
14	#338	unit, integration, and GPU lifecycle coverage

Validation

Validation of the assembled implementation:

• Full API, agent, and operator Go tests; key agent race tests.
• Rust workspace tests, strict Clippy, GNU/musl builds, ABI/ELF checks, packaged frontend/fake-driver tests, and memory-IPC regressions.
• Helm tests/lint, Python manifest/report tests, repository lint, and make check in a clean disposable worktree.
• A small real-agent CRIU cross-node test passed on two GPU nodes, covering memory IPC, private/shared VMM, multicast/graph replay, bytes, and original addresses. It preceded only the final manifest-format guard; that guard has local regression coverage.

GLM testing without CustomStorage was cancelled at the user's request and is not a pass. GLM qualification uses a separate composition with CustomStorage; previous experimental GLM results are not qualification of this rebuilt stack. The installed test driver is not claimed to be a stock-driver qualification.

Tests above were run on the assembled implementation, not claimed independently for every source-only intermediate PR. The standard-library cleanup was validated with Rust workspace tests and strict Clippy, GNU/musl builds and packaged fake-driver tests, plus targeted pod-contract and CUDA-agent Go tests. Physical-GPU tests were not rerun for this cleanup; the earlier GPU results above remain attributed to the pre-cleanup implementation.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}