docs(architecture): ADR 0018 — substrate pivot to Unikraft (Accepted) - #5
Merged
Merged
Conversation
Phase-1 PR B research found that upstream `hermit-os/kernel` does not expose a public raw-frame API — every relevant layer is `pub(crate)` and the application-facing `hermit-abi` is POSIX sockets only. A firewall is a forwarding device; the socket layer terminates flows and cannot pass them through. The previous draft of ADR 0018 (closed PR #4) proposed forking hermit-os/kernel. That's been rejected on reconsideration: a fork papers over a substrate mismatch (Hermit's model is "app uses network stack"; ours is "app IS network stack") rather than fixing the underlying choice. This ADR pivots the substrate back to **Unikraft** (the original ADR 0001 choice) while keeping Rust as the application language and smoltcp::wire as the parser library. Both of those clauses from ADR 0017 stay live; only the Hermit substrate clause is superseded. The two reasons ADR 0017 cited for choosing Hermit over Unikraft don't survive contact with the implementation: - "Rust-native single toolchain" was true but the Rust we'd write has to fight Hermit's design intent. - "Unikraft's value-add (C library catalog) is mostly libs we no longer use" was wrong: we DO want one specific piece — `lib-uknetdev` — which is exactly the raw-frame device API the thurward data path needs per ADR 0013 and chapter 02. Four alternatives weighed and rejected: fork hermit-os/kernel, distroless Linux + Rust + AF_PACKET, wait for upstream Hermit PR, MirageOS. Each rejection cites the architecture requirement(s) it would violate or the asymmetric cost. Status: Proposed. The ADR ends with three confirmation questions for the deciders. On acceptance, a follow-up PR updates ADR 0017 (status note), ADR 0001 (status note), the chapter docs that name Hermit specifically, ADR 0010's supply-chain section, and the in-progress `versions.lock` (currently lists Hermit TBDs from PR #3).
LeTuR
force-pushed
the
docs/adr-0018-substrate-pivot-unikraft
branch
from
May 25, 2026 21:27
8a75f4f to
9ccd17c
Compare
LeTuR
changed the title
3 tasks
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
1 participant
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.
Summary
Status: Accepted. Pivots the v1 substrate back to Unikraft (the original ADR 0001 choice). Keeps Rust as the application language and
smoltcp::wireas the parser library — those clauses from ADR 0017 stay live; only the Hermit substrate clause is superseded.Why
Phase-1 PR B research surfaced that upstream
hermit-os/kernelexposes no public raw-frame API. ADR 0017's two reasons for choosing Hermit over Unikraft don't hold up against the implementation:lib-uknetdev, exactly the raw-frame API ADR 0013 / chapter 02 specifyThe previous draft of ADR 0018 (closed PR #4) proposed forking
hermit-os/kernel. Rejected on reconsideration: a fork papers over a substrate mismatch rather than picking the right primitive.Decisions recorded in this ADR
The three confirmation questions raised when the ADR was Proposed have been answered:
lib-rustmaturity is a real cost; first-build (phase-1 PR B) is the gating signal.What this PR doesn't do
The ADR's "Migration" section lists 5 mechanical follow-ups (ADR 0017/0001 status notes, chapter doc Hermit references, ADR 0010 supply-chain section,
versions.lock). Those land in a single immediate follow-up PR after this one merges. Splitting keeps the decision diff small and reviewable.Test plan