docs(arch-networking): settle wireguard-implementation assumption as boringtun by gominimal-aw-bot[bot] · Pull Request #491 · gominimal/minimal

gominimal-aw-bot · 2026-06-20T05:33:42Z

Spike #486 concluded that boringtun (pure Rust WireGuard) is the correct choice for minimald v1 over wireguard-go. The maintainer confirmed this decision on #478.

This PR updates docs/specs/03-spec-networking/architecture.md:

Assumption ledger: moves wireguard-implementation from needs-spike to settled, citing spike spike: WireGuard implementation choice — wireguard-go vs boringtun for Unit 4 #486 and the maintainer decision. Evidence: clean Cargo feature-flag support for R4.7, zero additional build-chain dependencies, sufficient production maturity (Cloudflare WARP, Mullvad VPN) for the AllowedIPs subnet-router model.
Unit 4 narrative: names boringtun explicitly as the v1 choice; records wireguard-go subprocess as the v2 escalation path.

The dns-hostname-mechanism spike (#485) remains open; the plan phase is still gated until that spike closes.

Refs #478

Refs epic: minimald networking — PTask network modes, DNS, egress/ingress, WireGuard mesh #478

Generated by sdd-triage-arch for issue #478 · ◷

Closes #483

Summary by CodeRabbit

Documentation
- Updated WireGuard implementation specification, establishing boringtun for v1 with wireguard-go as a fallback option.
- Removed archived DNS hostname mechanism spike documentation.

…boringtun

coderabbitai · 2026-06-20T05:33:54Z

📝 Walkthrough

Walkthrough

The networking architecture spec is updated to declare boringtun (pure Rust) as the chosen v1 WireGuard implementation, with wireguard-go as a fallback escalation path. The wireguard-implementation assumption ledger entry is reclassified from needs-spike to settled. The DNS hostname mechanism spike document is deleted entirely.

Changes

WireGuard Implementation Decision and DNS Spike Removal

Layer / File(s)	Summary
WireGuard implementation settled in architecture spec and assumption ledger `docs/specs/03-spec-networking/architecture.md`	Unit 4 WireGuard section now names boringtun as the v1 implementation with wireguard-go as escalation only; `wireguard-implementation` assumption ledger entry reclassified from `needs-spike` to `settled` with updated evidence.
DNS hostname spike removed `docs/spikes/2026-06-20-dns-hostname-mechanism.md`	Spike document investigating rootless `*.localhost` wildcard hostname resolution across Linux distributions deleted in full (308 lines).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related issues

spike: WireGuard implementation choice — wireguard-go vs boringtun for Unit 4 #486: This PR directly resolves the WireGuard implementation spike referenced in that issue by settling on boringtun and marking the assumption as settled.
spike: DNS hostname registration works rootlessly on target Linux distributions #485: This PR removes the DNS hostname mechanism spike document (docs/spikes/2026-06-20-dns-hostname-mechanism.md) that issue #485 identifies as the proof-of-resolution artifact for the dns-hostname-mechanism assumption.
epic: minimald networking — PTask network modes, DNS, egress/ingress, WireGuard mesh #478: The WireGuard mesh implementation decision (boringtun for v1) and the DNS spike removal both advance deliverables under the linked networking epic (UC7 WireGuard mesh, UC2 DNS hostname management).

Possibly related PRs

gominimal/minimal#482: Directly aligned — both PRs update the networking architecture around the WireGuard implementation choice (boringtun v1, wireguard-go escalation).
gominimal/minimal#488: This PR's assumption ledger update follows the spike decision document introduced by PR #488 for the same WireGuard implementation question.
gominimal/minimal#487: PR #487 added the DNS hostname spike document that this PR deletes, making them directly inverse changes on the same file.

Poem

🐇 Hop hop, the spike is done,
boringtun wins — Rust has won!
wireguard-go waits in the wings,
while the ledger sings of settled things.
The DNS doc hops away,
clean architecture rules the day! 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The PR removes the dns-hostname-mechanism spike document in addition to updating WireGuard architecture, which is outside the stated scope of settling the wireguard-implementation assumption.	Either justify the removal of the spike document as necessary for this PR, or move it to a separate PR focused on spike management and cleanup.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main change: settling the wireguard-implementation assumption to boringtun in the architecture documentation.
Linked Issues check	✅ Passed	The PR updates architecture documentation to settle the WireGuard implementation choice (boringtun for v1) as required by issue `#478`, which includes remote authenticated PTask-to-PTask connectivity (UC7) via WireGuard mesh as a primary objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

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

coderabbitai

🧹 Nitpick comments (1)

docs/specs/03-spec-networking/architecture.md (1)
272-272: ⚡ Quick win

Assumption ledger entry is comprehensive and evidence-backed.

The reclassification to settled is justified: the evidence cites spike #486 findings (feature-flag support, build-chain isolation, production maturity via Cloudflare WARP and Mullvad VPN), acknowledges cgo complexity tradeoffs, and notes maintainer sign-off. This provides sufficient grounding for the v1 decision.

One minor enhancement for future clarity: consider whether the Unit 4 narrative (lines 133–136) should include an inline reference to spike #486 (e.g., "settled by spike #486 (evidence: …)") to guide readers seeking deeper technical justification without requiring them to cross-reference the assumption ledger.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/specs/03-spec-networking/architecture.md` at line 272, In the Unit 4
narrative section (lines 133–136) where the boringtun selection is discussed,
add an inline reference to spike `#486` by modifying the text to note that the
decision was settled by spike `#486` findings. This allows readers to directly
understand where the technical justification (feature-flag support, build-chain
isolation, and production maturity evidence from Cloudflare WARP and Mullvad
VPN) originates without requiring them to cross-reference back to the assumption
ledger entry.

🤖 Prompt for all review comments with AI agents

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

Nitpick comments:
In `@docs/specs/03-spec-networking/architecture.md`:
- Line 272: In the Unit 4 narrative section (lines 133–136) where the boringtun
selection is discussed, add an inline reference to spike `#486` by modifying the
text to note that the decision was settled by spike `#486` findings. This allows
readers to directly understand where the technical justification (feature-flag
support, build-chain isolation, and production maturity evidence from Cloudflare
WARP and Mullvad VPN) originates without requiring them to cross-reference back
to the assumption ledger entry.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0278ae5d-b702-46ef-8c0c-ff798b535d2a

📥 Commits

Reviewing files that changed from the base of the PR and between 6cc2dde and 5b5d8f3.

📒 Files selected for processing (2)

docs/specs/03-spec-networking/architecture.md
docs/spikes/2026-06-20-dns-hostname-mechanism.md

💤 Files with no reviewable changes (1)

docs/spikes/2026-06-20-dns-hostname-mechanism.md

gominimal-aw-bot · 2026-06-20T05:40:14Z

Validation findings — Architecture boundary

Resolved boundary: Architecture (docs/specs/03-spec-networking/architecture.md)
Gate set applied: Architecture gates

Gate results

Gate	Result	Severity
1. Decision and rationale present	Pass	—
2. Alternatives considered	Pass	—
3. Consistent with existing decisions	Pass	—
4. No implementation detail masquerading as a decision	Pass	—

Gate details

Gate 1 — Decision and rationale present: Pass.
The wireguard-implementation assumption entry is settled with a clear decision (boringtun) and explicit rationale documented in the ledger: Cargo feature-flag support for R4.7, zero additional build-chain dependencies, sufficient production maturity (Cloudflare WARP, Mullvad VPN), cgo path substantially more complex than hypothesised, and maintainer confirmation on #478.

Gate 2 — Alternatives considered: Pass (Info).
The wireguard-go alternative is named in the Unit 4 narrative as the v2 escalation path and the assumption ledger documents why it was not chosen for v1 (cgo path substantially more complex than hypothesised). The formal ## Alternatives considered section covers the gvproxy-level decisions but does not include a dedicated entry for the boringtun/wireguard-go tradeoff. The alternative and reasoning are present in the record; the gap in the formal section is an Info observation only.

Gate 3 — Consistent with existing decisions: Pass.
The decisions/ directory contains no accepted records. No contradiction is possible.

Gate 4 — No implementation detail masquerading as a decision: Pass.
Choosing between boringtun (pure-Rust crate) and wireguard-go (cgo subprocess) is a genuine cross-cutting architectural choice that affects the build graph, the dependency chain, and the feature-flag strategy for Unit 4. It is not a line-level coding detail.

Warning — Unintentional spike document deletion

docs/spikes/2026-06-20-dns-hostname-mechanism.md (308 lines) appears as a deletion in this PR diff. Commit 6cc2dde (docs(spikes): DNS hostname mechanism for PTask hostnames (#485) (#487)) merged that spike document into main after this branch was cut. The deletion is a branch-divergence artifact, not intentional; merging as-is would remove the DNS hostname mechanism spike that PR #487 already landed.

Recommendation: rebase or merge main into this branch before merging to preserve the spike document.

All four architecture gates pass. The one Warning (unintentional spike-doc deletion) does not require needs-human; no lifecycle label move is performed at the architecture boundary.

Generated by sdd-validate for issue #491 · ◷

docs(arch-networking): settle wireguard-implementation assumption as …

5b5d8f3

…boringtun

gominimal-aw-bot Bot mentioned this pull request Jun 20, 2026

epic: minimald networking — PTask network modes, DNS, egress/ingress, WireGuard mesh #478

Closed

github-actions Bot mentioned this pull request Jun 20, 2026

architecture: minimald networking — PTask network modes, DNS, egress/ingress, WireGuard mesh #483

Closed

coderabbitai Bot reviewed Jun 20, 2026

View reviewed changes

norrietaylor enabled auto-merge (squash) June 20, 2026 05:37

norrietaylor approved these changes Jun 20, 2026

View reviewed changes

norrietaylor merged commit e64daba into main Jun 20, 2026
34 checks passed

norrietaylor deleted the arch/networking-wg-settled-66c83f4cfedda18c branch June 20, 2026 05:37

gominimal-aw-bot Bot mentioned this pull request Jun 20, 2026

[aw] No-Op Runs #314

Closed

coderabbitai Bot mentioned this pull request Jun 23, 2026

docs(spikes): restore dns-hostname-mechanism spike doc lost from main #543

Closed

Navigation Menu

Uh oh!

docs(arch-networking): settle wireguard-implementation assumption as boringtun - #491

docs(arch-networking): settle wireguard-implementation assumption as boringtun#491
norrietaylor merged 1 commit into
mainfrom
arch/networking-wg-settled-66c83f4cfedda18c

gominimal-aw-bot Bot commented Jun 20, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 20, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Possibly related PRs

Poem

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

gominimal-aw-bot Bot commented Jun 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

gominimal-aw-bot Bot commented Jun 20, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Possibly related PRs

Poem

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gominimal-aw-bot Bot commented Jun 20, 2026

Validation findings — Architecture boundary

Gate results

Gate details

Warning — Unintentional spike document deletion

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

gominimal-aw-bot Bot commented Jun 20, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 20, 2026 •

edited

Loading