feat(agent): track POSIX CUDA VMM state

[galletas1712]

Summary

Layer 7 of the eleven-PR cuinterpose stack #293. Closed PR #214 is intentionally not in the active stack.

This PR implements running-state POSIX CUDA VMM tracking without checkpoint/restore lifecycle mechanics.

cuMemCreate has an explicit three-way gate:

Requested handle type	Runtime behavior	Checkpoint behavior
0	Private allocation passes through natively	Allowed
Exactly CU_MEM_HANDLE_TYPE_POSIX_FILE_DESCRIPTOR	Tracked and virtualized	Supported
Any other nonzero type, including FABRIC or combinations	Passes through to the driver	Refused by #216 preflight

Only successful unsupported exportable creations increment the process-wide diagnostic. It is intentionally sticky for that process generation because cuinterpose did not track the resource and cannot prove that releasing one handle eliminated every derived sharing dependency. FABRIC logs once that checkpoint will be refused. A fork child discards inherited CUDA state and starts with a fresh count.

Tracked allocations receive stable random allocation IDs and tagged logical handles. Repeated imports and retained handles collapse onto one real driver handle per allocation per process. Mappings are indexed by address range; access grants merge by location; partial/ambiguous operations are refused; a possibly partial driver access failure marks state unknown so inspection fails closed.

On first POSIX export, the creator performs one real CUDA export, keeps that descriptor in the export cache under the allocation ID, and returns a sealed ticket FD to the application. An importing shim reads the ticket, connects to the original creator endpoint, requests the ticket's participant/resource/allocation identity, receives a fresh descriptor over SCM_RIGHTS, imports it, and returns another logical handle. The random allocation ID is the opaque resource identity and export-cache key. Re-export by an importer still names the original creator.

A non-ticket descriptor import passes through and is counted as live raw sharing until its driver handle is released. #216 refuses checkpoint while that count is nonzero. The export cache has independent locking, in-flight pinning, drain-on-drop, and lifecycle quiesce/resume so peer requests remain serviceable without the main state lock.

The library constructor establishes the participant ID and /snapshot-control/cuinterpose-<namespace-pid>.sock. CUINTERPOSE_PARTICIPANT_ID is the explicit identity override used by tests and controlled launchers. The socket is mode 0600; the Pod-local control emptyDir is mounted through a container-name subPath, so ordinary other Pods have no filesystem path to it and Snapshot-managed target containers receive isolated views. The workload Pod remains one trust domain if its author deliberately gives a sidecar the reserved volume. This boundary does not claim protection from node root or an equivalently privileged workload. Fork children discard inherited CUDA bookkeeping and lazily create a new identity/socket on first CUDA activity. Control-endpoint ownership uses scoped cleanup and direct returns rather than goto.

Stack boundary

Based on #216. #292 adds the isolated current allocation-content storage module; #218 invokes it from SAVE_ALLOCATIONS/LOAD_ALLOCATIONS and implements unicast teardown/rebuild.

Validation

The pinned CUDA 13.1 builder passes 13 tracking tests, 9 table/cache tests, and 9 protocol tests with ASan/UBSan where configured. Coverage includes private/POSIX/FABRIC gate behavior, handle alias collapse, range mapping/access semantics, ticket exchange through a forked child, raw import accounting, listener concurrency, descriptor exhaustion, and table churn. make test passes in all Go modules. The final published stack head 0eae9c4f9b66093332f00a332afaf56048e1e64a passed the full make check gate, the CUDA 13.1 production build, and all 73 sanitizer-backed native cuinterpose tests. Its physical-GPU suite passed all 3 tests with no skips on two DRA-assigned NVIDIA B200 GPUs. The unicast test kept an explicit allocation-ID ticket-backed peer mapping per worker live across capture and restore; the multicast test required a nonzero multicast VA and shim-logical handle, exercised BindAddr, and passed its collective and captured-graph replay. Detailed hardware evidence and measurements are in #220.

[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.}

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[galletas1712]

Superseded by the replacement 13-PR C-frontend/Rust-backend cuinterpose draft stack: https://github.com/ai-dynamo/snapshot/stack/339 (#326–#338), tracking approved proposal #295. The new stack preserves one reviewable stage per PR, with tests collected in #338 and the design in #337. PageBroker transfer changes remain a separate dependency. Closing this older C implementation; retaining its branch and discussion for reference.