docs(architecture): apply adr 0018 migration (hermit → unikraft)

Mechanical follow-up to ADR 0018 (substrate pivot to Unikraft).
Updates the status notes on ADR 0017 + ADR 0001, the supply-chain
text in ADR 0010, the Hermit-specific references in the chapter
docs (00-overview, 02-packet-path, 03-rule-model, 06-deployment,
08-security-model, 09-limitations), the two canonical mermaid
sources (packet-path.mmd, rule-compilation.mmd), and retargets
versions.lock from Hermit TBDs to Unikraft TBDs.

Specifically:

- ADR 0017: Status changed to "Accepted (substrate clause superseded
  by ADR 0018; language clause + smoltcp::wire clause stay live)";
  added forward-pointer; supersedes-line clarified to be language
  clause only of ADR 0001.
- ADR 0001: Status changed from "Superseded by ADR 0017" to "Accepted
  (substrate clause restored by ADR 0018; language clause superseded
  by ADR 0017)"; banner rewritten to explain the restoration arc.
- ADR 0010 supply-chain section: pinned-deps list updated from
  "Hermit framework revision" to "Unikraft revision plus each
  selected lib-* component revision".
- Chapter docs: Hermit-specific descriptions softened to "the
  substrate" or rewritten to reference Unikraft's `lib-uknetdev`.
  The "Hermit framework maturity" subsection of 09-limitations
  becomes "`lib-rust` on Unikraft is early-adopter territory" — same
  risk surfaced for the new substrate. The "No bare-metal direct
  boot" section now cites both ADR 0017 and ADR 0018 (both keep
  bare-metal out of v1 scope; ADR 0017's "Hermit isn't ready"
  framing is replaced with the substrate-agnostic "v1 hypervisor
  only" framing).
- versions.lock: hermit_revision/hermit_rust_target replaced with
  unikraft_revision/unikraft_libs/unikraft_lib_revisions. lib-*
  selection inlined per ADR 0018.

ADRs 0003, 0008, 0009, 0013, 0014, 0016 still mention Hermit in
their historical text. Those are intentionally NOT edited — they
record the state at the time of writing and the supersession chain
(ADR 0001 → 0017 → 0018) makes the current state findable.

`cargo test` clean on the PR A rule pipeline; no source changes in
this PR.

Author: LeTuR

docs/architecture/00-overview.md

@@ -5,7 +5,7 @@ the [decision records](decisions/) in order; then the topical chapters.*
 
 ## What thurward is
 
-A minimalistic open-source firewall packaged as a Hermit unikernel
+A minimalistic open-source firewall packaged as a Unikraft unikernel
 written in Rust. It sits **inline between two networks**, filters
 traffic on **source CIDR, destination port, and FQDN**, performs
 **SNAT/masquerade and static DNAT**, and is configured by editing
@@ -16,14 +16,16 @@ collector — no in-band telemetry traffic. v1 is **single-VM**; HA
 and bare-metal direct boot are both deferred to v2.
 
 It is **not** a Linux firewall with extra steps. The OS substrate is
-[Hermit](https://hermit-os.org/); the entire data path (parser,
-conntrack, filter, NAT, TX) is Rust, using `smoltcp::wire` for typed
-packet parsing and writing every other layer ourselves — no in-image
-TCP/IP socket layer between the driver and the filter. The image is
-a single signed unikernel that boots in milliseconds and exposes no
-shell, no mgmt port, no userspace utilities. See
-[ADR 0017](decisions/0017-hermit-rust-substrate.md) and
-[ADR 0013](decisions/0013-zig-fast-path-on-uknetdev.md).
+[Unikraft](https://unikraft.org/) (via `lib-uknetdev` for raw frame
+access); the entire data path (parser, conntrack, filter, NAT, TX)
+is Rust, using `smoltcp::wire` for typed packet parsing and writing
+every other layer ourselves — no in-image TCP/IP socket layer
+between the driver and the filter. The image is a single signed
+unikernel that boots in milliseconds and exposes no shell, no mgmt
+port, no userspace utilities. See
+[ADR 0018](decisions/0018-substrate-pivot-unikraft.md) (substrate),
+[ADR 0017](decisions/0017-hermit-rust-substrate.md) (language +
+parser), and [ADR 0013](decisions/0013-zig-fast-path-on-uknetdev.md).
 
 ## Why
 
@@ -104,9 +106,9 @@ LAN clients
 │  │   ├─ DNS proxy + fqdn_set                │    │
 │  │   └─ observability emitter (vsock)       │    │
 │  ├──────────────────────────────────────────┤    │
-│  │  Hermit virtio-net + virtio-vsock        │    │
+│  │  Unikraft lib-uknetdev + virtio-vsock    │    │
 │  ├──────────────────────────────────────────┤    │
-│  │  Hermit unikernel core                   │    │
+│  │  Unikraft unikernel core                 │    │
 │  └──────────────────────────────────────────┘    │
 └────────┬──────────────────────────┬──────────────┘
          │ NIC 0 (LAN)              │ NIC 1 (WAN)
@@ -119,9 +121,10 @@ LAN clients
 
 Note: there is no TCP/IP socket layer in the image. `smoltcp` is
 linked only for its `wire` / parser modules; the Rust data plane
-owns the forwarding loop directly
+owns the forwarding loop directly via Unikraft's `lib-uknetdev`
 ([ADR 0013](decisions/0013-zig-fast-path-on-uknetdev.md),
-[ADR 0017](decisions/0017-hermit-rust-substrate.md)).
+[ADR 0017](decisions/0017-hermit-rust-substrate.md),
+[ADR 0018](decisions/0018-substrate-pivot-unikraft.md)).
 
 (System context, packet path, deployment topology, and the rule/IaC
 flow are documented in chapters 01, 02, 06, and 10 respectively, with
@@ -132,9 +135,10 @@ proper diagrams.)
 - **Unikernel** — a single-purpose operating system image where the
   application and the kernel libraries are linked into one binary.
   Boots on a hypervisor; no shell, no users, no multi-process model.
-- **Hermit** — a Rust-native unikernel framework. Application runs in
-  kernel space; `cargo build --target x86_64-unknown-hermit` produces
-  the image.
+- **Unikraft** — a modular unikernel framework. Application runs in
+  kernel space; the build (`Kraftfile` + `lib-rust` + selected
+  `lib-*` components) produces a single image. Per
+  [ADR 0018](decisions/0018-substrate-pivot-unikraft.md).
 - **smoltcp** — a `no_std` Rust TCP/IP stack. thurward links only its
   `wire` (parser/builder) modules — not its socket or interface layers
   — so the application keeps direct control over the forwarding loop.

docs/architecture/02-packet-path.md

@@ -5,8 +5,9 @@ the filter sits, where NAT happens, and what the fast path looks like.*
 
 The decisions framing this chapter:
 
-- [ADR 0017](decisions/0017-hermit-rust-substrate.md) — substrate is
-  Hermit + Rust + smoltcp wire types (no socket layer).
+- [ADR 0018](decisions/0018-substrate-pivot-unikraft.md) — substrate
+  is Unikraft + Rust + smoltcp wire types (no socket layer);
+  language clause via [ADR 0017](decisions/0017-hermit-rust-substrate.md).
 - [ADR 0013](decisions/0013-zig-fast-path-on-uknetdev.md) — the
   application owns the data path; no in-image TCP/IP socket layer
   between the driver and the filter.
@@ -25,7 +26,7 @@ WAN interface traverses the following sequence:
 sequenceDiagram
     autonumber
     participant NIC0 as virtio-net (LAN)
-    participant POLL as Hermit RX poll
+    participant POLL as uknetdev RX poll
     participant PARSE as Rust parse (smoltcp::wire)
     participant CT as conntrack
     participant FILT as filter
@@ -65,10 +66,10 @@ destination IPs (see [ADR 0014](decisions/0014-stateful-nat.md) §
 
 ## Where the code lives
 
-Hermit exposes the virtio-net device through a low-level RX/TX
-descriptor API; thurward's Rust crate calls into it directly. The
-`main` function spawns one **RX poll thread per interface**, each
-running:
+Unikraft's `lib-uknetdev` exposes each virtio-net device through a
+low-level RX/TX descriptor API; thurward's Rust crate calls into it
+directly. The `main` function spawns one **RX poll thread per
+interface**, each running:
 
 ```rust
 // src/dataplane.rs — sketch, not the implementation
@@ -121,7 +122,7 @@ The filter does NOT do payload inspection. No DPI, no L7 — just the
   per-thread conntrack shards (the 5–10 Gbps stretch in
   [ADR 0013](decisions/0013-zig-fast-path-on-uknetdev.md)) is additive,
   not a redesign.
-- **Hot-loop discipline:** no allocator calls, no syscalls (Hermit's
+- **Hot-loop discipline:** no allocator calls, no syscalls (the
   unikernel model — application runs in kernel space — helps here),
   batched RX/TX descriptors, slice-based smoltcp parsers that don't
   copy, branch-prediction-friendly common-case parsing.

docs/architecture/03-rule-model.md

@@ -99,7 +99,7 @@ Cargo `build.rs` script compiles `rules.yaml` into a packed Rust
 ```mermaid
 flowchart LR
     A[rules.yaml] -->|build.rs| B[OUT_DIR/rules_table.rs]
-    B --> C[cargo build --target x86_64-unknown-hermit]
+    B --> C[Unikraft build with lib-rust]
     C --> F[thurward image]
     G[schemas/rules.schema.json] -.validates.-> A
     style A fill:#dae8fc,stroke:#6c8ebf

docs/architecture/06-deployment.md

@@ -6,10 +6,11 @@ and the [decision records](decisions/).*
 
 The deployment model is dictated by:
 
-- [ADR 0017](decisions/0017-hermit-rust-substrate.md) — Hermit
-  unikernel + Rust; the same image runs on two v1 targets (QEMU/KVM
-  and Firecracker). Bare-metal direct boot is deferred to v2 — see
-  [09 — Limitations](09-limitations.md).
+- [ADR 0018](decisions/0018-substrate-pivot-unikraft.md) — Unikraft
+  unikernel substrate; [ADR 0017](decisions/0017-hermit-rust-substrate.md)
+  — Rust language clause. The same image runs on two v1 targets
+  (QEMU/KVM and Firecracker). Bare-metal direct boot is deferred to
+  v2 — see [09 — Limitations](09-limitations.md).
 - [ADR 0013](decisions/0013-zig-fast-path-on-uknetdev.md) — the app
   owns the data path; no in-image TCP/IP socket layer (smoltcp's
   wire/parser modules only).
@@ -33,8 +34,8 @@ The deployment model is dictated by:
 
 Steps 1 and 2 happen on a developer/operator workstation (or in CI if
 preferred). Step 3 happens on the target host. The artifact crossing
-the boundary is **one signed Hermit unikernel image plus its cosign
-signature and SLSA-3 attestation**
+the boundary is **one signed Unikraft unikernel image plus its
+cosign signature and SLSA-3 attestation**
 ([ADR 0010](decisions/0010-supply-chain-hardening.md)).
 
 Both v1 deployment paths consume the same image; only the launcher
@@ -56,7 +57,7 @@ cd thurward
 # edit rules.yaml — VS Code / Helix will pull schemas/rules.schema.json
 # automatically for autocomplete + inline validation
 $EDITOR rules.yaml
-make build               # wraps `cargo build --release --target x86_64-unknown-hermit`
+make build               # wraps the Unikraft + Rust build flow (Kraftfile + lib-rust)
 make run                 # wraps the QEMU invocation below
 ```
 
@@ -65,7 +66,7 @@ make run                 # wraps the QEMU invocation below
 ```bash
 qemu-system-x86_64 \
   -enable-kvm -cpu host -smp 1 -m 128M \
-  -kernel target/x86_64-unknown-hermit/release/thurward \
+  -kernel build/thurward_kvm-x86_64 \
   -netdev bridge,id=lan,br=br-lan -device virtio-net-pci,netdev=lan \
   -netdev bridge,id=wan,br=br-wan -device virtio-net-pci,netdev=wan \
   -device vhost-vsock-pci,guest-cid=3
@@ -109,16 +110,18 @@ A reference `thurward.service` systemd unit is shipped in `contrib/`:
 it runs `firecracker` with two virtio NICs, one virtio-vsock device
 (CID 3, host port 9000 for observability), and the current image; it
 restarts on failure. On rule changes, replace `current.image` and
-`systemctl restart thurward` — the restart is fast (Firecracker
-sub-10ms boot + Hermit sub-10ms boot), but **flows in progress drop**
+`systemctl restart thurward` — the restart is fast (Firecracker and
+unikernel boot are both sub-10ms), but **flows in progress drop**
 because v1 has no HA ([09 — Limitations](09-limitations.md)).
 
 ## Bare-metal — deferred to v2
 
 A previous revision of this chapter described a third path (bare-metal
-x86_64 EFI direct boot). [ADR 0017](decisions/0017-hermit-rust-substrate.md)
-walks that back: Hermit's bare-metal story isn't ready for the v1
-promise. Bare-metal is a known v2 direction; see
+x86_64 EFI direct boot). Per
+[ADR 0017](decisions/0017-hermit-rust-substrate.md) and
+[ADR 0018](decisions/0018-substrate-pivot-unikraft.md), bare-metal is
+out of scope for v1 regardless of substrate; v1 ships hypervisor
+targets only. Bare-metal is a known v2 direction; see
 [09 — Limitations](09-limitations.md) for the trade-off and the v2
 options under consideration.
 
@@ -142,8 +145,8 @@ operational story are the same.
 
 | Lives on the host          | Lives in the image                                                                     |
 | -------------------------- | -------------------------------------------------------------------------------------- |
-| Linux bridges              | Hermit unikernel core                                                                  |
-| TAP devices                | Hermit virtio-net + virtio-vsock drivers                                               |
+| Linux bridges              | Unikraft unikernel core (`lib-ukboot`, `lib-ukalloc`, `lib-uksched`)                   |
+| TAP devices                | `lib-uknetdev` + `lib-ukbus-virtio` (virtio-net + virtio-vsock drivers)                |
 | `vhost_vsock` module       | smoltcp (wire/parser layer only)                                                       |
 | `cosign` + `slsa-verifier` | Rust data plane (parse, conntrack, filter, NAT, TX)                                    |
 | Collector stack            | Compiled rule + DNAT table (Rust module generated by `build.rs` from rules.yaml)       |

docs/architecture/08-security-model.md

@@ -58,10 +58,12 @@ In words:
 2. **CI build environment** is pinned (Nix flake or container SHA).
    Network-isolated; deps fetched against a content-addressed proxy.
 3. **Build inputs** (Rust toolchain channel + components, every
-   transitive crate in `Cargo.lock`, the Hermit framework revision,
-   the smoltcp crate version) are pinned in `versions.lock`. CI
-   fails on drift. See
-   [ADR 0017](decisions/0017-hermit-rust-substrate.md) and
+   transitive crate in `Cargo.lock`, the Unikraft revision plus each
+   selected `lib-*` component revision, the smoltcp crate version)
+   are pinned in `versions.lock`. CI fails on drift. See
+   [ADR 0018](decisions/0018-substrate-pivot-unikraft.md) (substrate),
+   [ADR 0017](decisions/0017-hermit-rust-substrate.md) (language +
+   parser), and
    [ADR 0010](decisions/0010-supply-chain-hardening.md).
 4. **Build output** is reproducible — byte-identical given the same
    inputs.

docs/architecture/09-limitations.md

@@ -65,23 +65,23 @@ environment, thurward v1 is not for you.
 
 ## No bare-metal direct boot (v1)
 
-A prior revision of this architecture lifted bare-metal x86_64 EFI
-direct boot to a v1 first-class target on Unikraft. The substrate
-switch to Hermit ([ADR 0017](decisions/0017-hermit-rust-substrate.md))
-walks that back: Hermit's bare-metal story is less mature than
-Unikraft's, and rather than weaken either the substrate decision or
-the bare-metal promise, v1 commits to Hermit and defers bare-metal
-to v2.
-
 v1 targets are **QEMU/KVM** and **Firecracker** only
-([06 — Deployment](06-deployment.md)). If you need a dedicated-hardware
-deployment today, run a small Linux+KVM appliance image on the box and
-launch Firecracker (Path B) on top.
-
-The v2 ADR for bare-metal will revisit the trade-off: Hermit may have
-matured, or a Linux+KVM appliance image may be the pragmatic answer,
-or a different unikernel's bare-metal story may have caught up
-(Unikraft on ARM, MirageOS, etc.).
+([06 — Deployment](06-deployment.md)). Bare-metal x86_64 EFI direct
+boot is deferred to v2 — per
+[ADR 0017](decisions/0017-hermit-rust-substrate.md) and
+[ADR 0018](decisions/0018-substrate-pivot-unikraft.md), both
+substrate-related decisions explicitly keep bare-metal out of v1
+scope. Unikraft does have a credible bare-metal direct-boot story,
+but v1 does not exercise it.
+
+If you need a dedicated-hardware deployment today, run a small
+Linux+KVM appliance image on the box and launch Firecracker (Path B)
+on top.
+
+The v2 ADR for bare-metal will revisit the trade-off: Unikraft's
+bare-metal target may be ready to lift, or a Linux+KVM appliance
+image may remain the pragmatic answer, or a different unikernel's
+bare-metal story may have caught up (MirageOS, etc.).
 
 ARM in general is also not in v1.
 
@@ -139,24 +139,28 @@ For Path A (QEMU) and Path B (Firecracker), the host kernel must have
 `vhost_vsock` loaded (`modprobe vhost_vsock`). Without it, the
 observability channel doesn't open.
 
-## Hermit framework maturity
+## `lib-rust` on Unikraft is early-adopter territory
 
-Hermit ([ADR 0017](decisions/0017-hermit-rust-substrate.md)) is
-actively developed but has a smaller user base than Unikraft. Expect
-a narrower set of example projects and Stack Overflow answers when
-diagnosing build or runtime issues. Upstream patches for bugs we
-hit may take longer to land than they would on a larger framework.
+Unikraft's Rust integration (`lib-rust`) is less mature than its C
+support. Some Rust crates that assume a hosted runtime (`std::*`) may
+not build cleanly inside the image — the hot loop is already
+`no_std`-friendly per [ADR 0013](decisions/0013-zig-fast-path-on-uknetdev.md),
+but adding new runtime dependencies needs a `no_std` check. Build-
+time crates run on the host and aren't subject to this constraint.
+Upstream patches we contribute to `lib-rust` may take longer to land
+than they would in Unikraft's C ecosystem.
 
 ## Toolchain pinning is heavier than the prior Zig stack
 
-The Rust + Hermit + smoltcp stack pins more moving parts than the
-prior Zig + Unikraft stack did: `rust-toolchain.toml` (rustup channel
-+ components), `Cargo.lock` (every transitive crate), the Hermit
-framework revision, and the smoltcp crate version all live in
-`versions.lock` (see
-[ADR 0010](decisions/0010-supply-chain-hardening.md)). Upgrades are
-deliberate, reviewed actions with reproducibility re-validation —
-not passive `cargo update` runs.
+The Rust + Unikraft + smoltcp stack pins more moving parts than the
+prior Zig stack did: `rust-toolchain.toml` (rustup channel +
+components), `Cargo.lock` (every transitive crate), the Unikraft
+revision plus each selected `lib-*` component revision, and the
+smoltcp crate version all live in `versions.lock` (see
+[ADR 0010](decisions/0010-supply-chain-hardening.md) and
+[ADR 0018](decisions/0018-substrate-pivot-unikraft.md)). Upgrades
+are deliberate, reviewed actions with reproducibility re-validation
+— not passive `cargo update` runs.
 
 ## Out of scope explicitly
 

docs/architecture/decisions/0001-unikraft-as-os-substrate.md

@@ -1,17 +1,25 @@
-# ADR 0001 — Unikraft as OS substrate (superseded)
+# ADR 0001 — Unikraft as OS substrate
 
-**Status:** Superseded by [ADR 0017](0017-hermit-rust-substrate.md)
+**Status:** Accepted (substrate clause restored by
+[ADR 0018](0018-substrate-pivot-unikraft.md); language clause
+superseded by [ADR 0017](0017-hermit-rust-substrate.md) — original
+Zig choice replaced with Rust)
 **Date:** 2026-05-23
-**Superseded:** 2026-05-25
+**Superseded:** 2026-05-25 (substrate clause originally) —
+2026-05-25 (substrate clause restored)
 **Deciders:** magicletur
 
-> **Superseded.** thurward does not ship on Unikraft. The substrate
-> chosen for v1 is **Hermit** — see
-> [ADR 0017](0017-hermit-rust-substrate.md). This ADR is preserved
-> because the *non*-Unikraft alternatives analysis below (why not
-> stripped Linux, why not Alpine + Rust, etc.) still applies and is
-> referenced by ADR 0017 as the canonical "why a unikernel at all"
-> argument.
+> **Substrate clause restored.** thurward ships on **Unikraft** for
+> v1, with Rust as the application language (per
+> [ADR 0017](0017-hermit-rust-substrate.md)'s language clause) and
+> `lib-uknetdev` for raw frame access (per
+> [ADR 0018](0018-substrate-pivot-unikraft.md)). The original
+> language clause of this ADR (Zig) is superseded by ADR 0017; the
+> substrate clause was briefly superseded by ADR 0017 and restored
+> by ADR 0018 after phase-1 implementation found Hermit was the
+> wrong substrate shape for a forwarding device. The original
+> alternatives analysis below (why not stripped Linux, why not
+> Alpine + Rust, etc.) still applies.
 
 ## What survives from this ADR