docs(design): microVM Runner V2b — in-guest supervisor + vsock exec control plane (RIG-2493) - #643
Merged
Merged
Conversation
|
Compass engineering docs preview: https://compass-runner-rig-2493-v2b.compass-eng-docs.pages.dev Deployed from Changed pages: |
rigel-mintaka
added a commit
that referenced
this pull request
Aug 26, 2026
…, U3b ordering (RIG-2493) Address the four findings from the review pass on #643 (0 high, 2 medium, 2 low), all internal-consistency drift the record's own decisions already resolved: - U1 now explicitly owns the additive `boot_nonce` field on `HealthResponse` (medium): the Global Constraint and §(e) mandate it and U2/U4 consume it, but no task's stated deliverable produced it. Named in the U1 body and Interfaces list as field 4. - §(c) Create assembles a fixed guest CID (3) + fixed guestd port (medium), matching the OQ-F recommendation the body designs against, instead of a per-session "fresh CID ≥ 3 and port" — per-session uniqueness rides the AF_UNIX socket paths, since nothing routes on the CID. - Plan ordering names the U3 → U3b type dependency (low): U3's waitFunc constructs U3b's portable exit-signal error, so under OQ-G option 1 U3b lands with or just before U3; under option 2 U3's contract and the U5 kill/wait row change. - U2 Interfaces cites `healthService`'s definition (`health.go:14-40`) threaded through `serveVsock`/`serveHandshake` (`vsock.go:27-41`) instead of a call site (low). Ledger-impact: none Refs RIG-2493 Co-authored-by: Matt Wilkinson <matt@rigel.build>
rigel-mintaka
force-pushed
the
compass-runner/rig-2493-v2b-design
branch
from
August 26, 2026 04:26
56ac7cb to
7c5868c
Compare
rigel-mintaka
added a commit
that referenced
this pull request
Aug 27, 2026
…, U3b ordering (RIG-2493) Address the four findings from the review pass on #643 (0 high, 2 medium, 2 low), all internal-consistency drift the record's own decisions already resolved: - U1 now explicitly owns the additive `boot_nonce` field on `HealthResponse` (medium): the Global Constraint and §(e) mandate it and U2/U4 consume it, but no task's stated deliverable produced it. Named in the U1 body and Interfaces list as field 4. - §(c) Create assembles a fixed guest CID (3) + fixed guestd port (medium), matching the OQ-F recommendation the body designs against, instead of a per-session "fresh CID ≥ 3 and port" — per-session uniqueness rides the AF_UNIX socket paths, since nothing routes on the CID. - Plan ordering names the U3 → U3b type dependency (low): U3's waitFunc constructs U3b's portable exit-signal error, so under OQ-G option 1 U3b lands with or just before U3; under option 2 U3's contract and the U5 kill/wait row change. - U2 Interfaces cites `healthService`'s definition (`health.go:14-40`) threaded through `serveVsock`/`serveHandshake` (`vsock.go:27-41`) instead of a call site (low). Ledger-impact: none Refs RIG-2493 Co-authored-by: Matt Wilkinson <matt@rigel.build>
rigel-mintaka
force-pushed
the
compass-runner/rig-2493-v2b-design
branch
2 times, most recently
from
August 27, 2026 18:23
91508a5 to
7fc61e9
Compare
…ontrol plane (RIG-2493) Details the frozen parent's schedule-critical V2b milestone (microvm-runner.md § Plan V2b): grow compass-guestd into the real in-guest supervisor serving an additive GuestControl exec surface (Exec/ExecStream/Signal/Provision over the V2a proto seed), and fill MicroVMRuntime's Create/Start/Exec/ExecStreaming/Stop/Remove so the microVM backend behaves identically to PodmanCLI through the ContainerRuntime interface. Sibling detailing record to the V2a boot-spike record, under the same compass-elastic-session-runtime design directory. Resolves the forks the parent left to detailing — the exec surface (a), the guestd supervisor + fail-closed gate (b), the MicroVMRuntime methods (c), Stop/Remove teardown (d), and the exec-transport auth question (e) — and batches seven Open Questions (OQ-A..G) for a pre-freeze ruling, four of them load-bearing. Status: PROPOSED. Ledger-impact: none — details forks the frozen parent already framed and resolves them within its decisions; no new DECISIONS.md row (OQ-A auth and OQ-G error-taxonomy are candidates for promotion if Matt wants them citable outside this lineage). Refs RIG-2493 Co-authored-by: Matt Wilkinson <matt@rigel.build>
…, U3b ordering (RIG-2493) Address the four findings from the review pass on #643 (0 high, 2 medium, 2 low), all internal-consistency drift the record's own decisions already resolved: - U1 now explicitly owns the additive `boot_nonce` field on `HealthResponse` (medium): the Global Constraint and §(e) mandate it and U2/U4 consume it, but no task's stated deliverable produced it. Named in the U1 body and Interfaces list as field 4. - §(c) Create assembles a fixed guest CID (3) + fixed guestd port (medium), matching the OQ-F recommendation the body designs against, instead of a per-session "fresh CID ≥ 3 and port" — per-session uniqueness rides the AF_UNIX socket paths, since nothing routes on the CID. - Plan ordering names the U3 → U3b type dependency (low): U3's waitFunc constructs U3b's portable exit-signal error, so under OQ-G option 1 U3b lands with or just before U3; under option 2 U3's contract and the U5 kill/wait row change. - U2 Interfaces cites `healthService`'s definition (`health.go:14-40`) threaded through `serveVsock`/`serveHandshake` (`vsock.go:27-41`) instead of a call site (low). Ledger-impact: none Refs RIG-2493 Co-authored-by: Matt Wilkinson <matt@rigel.build>
…s non-goal (RIG-2493)
Matt ruled the one load-bearing scope fork: no interface is frozen; the
prototype may unfreeze any contract. That lifts the sole blocker on OQ-G and
collapses the two other freeze-gated forks.
- OQ-G resolved (option 1, now unconditional): adopt the portable exported
runtime.ExitStatusError{Code, Signal} and widen isDeliberateKill via
errors.As with the *exec.ExitError fallback + podman-row regression guard.
U3b is no longer gated; the interface alternative is dropped in favor of the
concrete struct.
- OQ-B / OQ-D resolved to their recommendations (ExecStreamRequest/Response
direction-specific oneofs; ratified U4 MicroVMConfig field set).
- Batch preamble records that freeze-gated forks are settled by adopting the
recommendation, and that OQ-A (auth) and OQ-C (mount-owner) remain genuine
design choices tracked outside this record — reversible, not merge-blockers.
- No-podman-regression constraint reworded: U3b's isDeliberateKill widening is
a scoped additive exception, no longer conditional.
Adds an explicit non-goal V2b must not foreclose: containers inside the guest
(dev/build sandboxes). An in-guest container runtime is an ordinary ExecStream
child; the isolation boundary is the VM, not the guest uid. Tracked as its own
milestone (RIG-2850) under the parent V-plan.
Refs RIG-2493
Refs RIG-2850
Co-authored-by: Matt Wilkinson <matt@rigel.build>
Review of the rulings fold caught one stale conditional the fold missed: the Plan dependency-ordering paragraph still framed U3b as "gated on Matt's OQ-G ruling" and branched on option 1 vs option 2. OQ-G is resolved to option 1 and U3b is unconditional everywhere else in the record; this sentence now matches — U3b produces the portable exit-signal error type and lands with or just before U3, no gate, no option-2 branch. Refs RIG-2493 Co-authored-by: Matt Wilkinson <matt@rigel.build>
…/dumb-init (RIG-2493)
Ground the V2b exec surface §(a) and the PID-1 supervisor/reaper §(b) in the
proven prior art, adopting it as a reference model rather than vendored code.
- Exec RPC shape cites kata-containers agent.proto (AgentService):
ExecProcess/SignalProcess/WaitProcess ("wait & reap like waitpid(2)") + the
stdio verbs, plus the two shape invariants V2b reuses — exit code carried in
the wait response (not a transport error) and empty exec_id → signal the
whole session (our Stop path).
- Reaper/signal model cites tini and dumb-init: PID-1 zombie reaping,
signal-forwarding to the process group, child exit-code propagation.
- Records the four walls (language, transport, scope, host interface) that make
outright adoption wrong and keep the code a reference. Confirms the current
Go/Connect/one-session V2b design unchanged.
No design change; grounds an already-settled approach for the U2 implementer.
Refs RIG-2493
Co-authored-by: Matt Wilkinson <matt@rigel.build>
rigel-mintaka
force-pushed
the
compass-runner/rig-2493-v2b-design
branch
from
August 27, 2026 21:13
7fc61e9 to
44c52ec
Compare
mattwilkinsonn
approved these changes
Aug 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Details the frozen parent's schedule-critical V2b milestone
(microvm-runner.md § Plan V2b): grow compass-guestd into the real in-guest
supervisor serving an additive GuestControl exec surface
(Exec/ExecStream/Signal/Provision over the V2a proto seed), and fill
MicroVMRuntime's Create/Start/Exec/ExecStreaming/Stop/Remove so the microVM
backend behaves identically to PodmanCLI through the ContainerRuntime
interface.
Sibling detailing record to the V2a boot-spike record, under the same
compass-elastic-session-runtime design directory. Resolves the forks the parent
left to detailing — the exec surface (a), the guestd supervisor + fail-closed
gate (b), the MicroVMRuntime methods (c), Stop/Remove teardown (d), and the
exec-transport auth question (e) — and batches seven Open Questions (OQ-A..G)
for a pre-freeze ruling, four of them load-bearing.
Status: PROPOSED.
Ledger-impact: none — details forks the frozen parent already framed and
resolves them within its decisions; no new DECISIONS.md row (OQ-A auth and OQ-G
error-taxonomy are candidates for promotion if Matt wants them citable outside
this lineage).
Refs RIG-2493
Co-authored-by: Matt Wilkinson matt@rigel.build