docs(arch-minvmd-networking-gvproxy): minvmd networking — gvproxy userspace net for VM sessions - #445

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/specs/03-spec-minvmd-networking-gvproxy/architecture.md`:
- Line 38: The function signature check_network_policy references a PolicyError
type that is not defined in the net.rs module specification. Add the PolicyError
type definition to the net.rs module API section in the architecture.md file,
defining it as an enum or struct that includes at least one variant for
representing policy violation errors. If PolicyError is intended to be a type
alias or re-export from another module, explicitly document this relationship in
the module specification instead.
- Line 48: The specification at line 48 describing the spawn_gvproxy(gvproxy_fd)
call before the VMM child does not document the synchronization requirements
between gvproxy and VMM initialization. Add documentation clarifying whether the
supervisor must wait for gvproxy to signal readiness (such as by listening on
the socketpair FD) before spawning the VMM child, or whether they can be spawned
concurrently. Include explanation of how the synchronization prevents race
conditions where the VMM's virtio-net device might attempt to connect before
gvproxy is fully initialized, and specify any guarantees about initialization
order and timing.
- Line 47: The current specification at line 47 only documents clearing
FD_CLOEXEC on the gvproxy-side FD but omits the requirement for the VMM-side FD.
Add explicit documentation to clarify that FD_CLOEXEC must also be cleared on
the VMM-side FD in the supervisor before spawning the VMM child process. This
ensures the VMM-side FD survives the child's fork()+exec() boundary and prevents
unintended closure during the exec operation. The requirement should be stated
alongside the existing gvproxy-side FD_CLOEXEC clearing requirement.
- Around line 52-53: Expand the exit paths description to specify failure
handling semantics when calling gvproxy_child.kill() and gvproxy_child.wait(),
including how the supervisor should handle EINTR during reaping, whether there
are timeout constraints on wait operations, and what happens if reaping fails.
Additionally, provide a definition or reference for StartingGuard (e.g., cite
where it is defined in the codebase), explain its role as a RAII guard, and
clarify how its drop implementation integrates with the gvproxy reaping
requirement so implementers understand the complete lifecycle hook point.
- Around line 88-91: The specification for the conditional logic in the apply()
method is incomplete because it does not define the error handling behavior when
net_mode is set to NetworkMode::GvProxy but net_fd is None (indicating gvproxy
failed to spawn). Add documentation to the spec clarifying the intended behavior
in this scenario: specify whether apply() should treat this as a hard error that
causes the function to fail and log an error, log a warning and silently fall
back to TSI mode, or handle it in some other defined way. This clarification
should be added to the section describing the conditional branches in apply() to
prevent ambiguity during implementation and ensure consistent behavior across
platforms.

---

Outside diff comments:
In `@docs/specs/03-spec-minvmd-networking-gvproxy/architecture.md`:
- Around line 177-184: In the Verification section, clarify that the
minimald_session_e2e test binary referenced in lines 180-182 does not yet exist
and will be created as part of a future implementation PR (since this is an
architecture-only specification). Additionally, replace the statement in line
182 that says "The architecture sub-issue is created as a child of tracking
issue minimal#404" with language that accurately reflects that this is an
architecture specification document (not an issue) that is linked from or
referenced in the tracking issue minimal#404, and will remain open for follow-up
implementation work.

---

Nitpick comments:
In `@docs/specs/03-spec-minvmd-networking-gvproxy/architecture.md`:
- Line 91: Correct the capitalization of the operating system name in the
English prose descriptions on lines 91 and 97. Change references from "macos" to
"macOS" when describing the operating system in your text (for example, "removes
the macOS gate" instead of "removes the macos gate"), but preserve the exact
lowercase spelling when citing actual code symbols like #[cfg(target_os =
"macos")], which should remain unchanged to match the actual source code.