docs(arch-vm-ext4-volume): pkg cache on the in-VM ext4 volume (volume-aware) - #674

No actionable comments were generated in the recent review. 🎉

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

sdd-validate — Architecture boundary findings

Boundary resolved: Architecture (PR adds docs/specs/08-spec-vm-ext4-volume/architecture.md under docs/specs/).

Gate set applied: Architecture gates 1–4.

Tracking issue: #583 (sdd:triage, full-path feature).

Gate 1 — Decision and rationale present

Result: Pass.

The "Chosen approach" section clearly states the chosen design (two-disk RAW virtio-blk topology: read-only shared /dev/vda + per-VM writable ext4 /dev/vdb) and the reasoning behind each element: the EXDEV hardlink constraint is resolved by construction; guest-side first-boot mkfs.ext4 keyed on superblock detection is idempotent and platform-portable (macOS has no mke2fs); loud failure on /dev/vdb mount is required once user data lives on the volume. Decision and rationale are both present.

Gate 2 — Alternatives considered

Result: Pass.

The "Alternatives considered" section enumerates five alternatives, each with a named rejection rationale grounded in concrete evidence:

• qcow2 data disk / backing-file overlay — rejected: no Qcow2 DiskFormat variant exists (raw.rs:40-44); no host-side overlay-creation path in libkrun; metadata-corruption surface on hard-kill.
• VolumeProvisioner trait abstraction — rejected (YAGNI): Phase-2 reflink provisioner is a pure host-side strategy swap with no guest/boot-path change; three speculative provisioners do not justify a trait.
• Host-side mkfs.ext4 before disk attach — rejected: macOS has no mke2fs/mkfs.ext4.
• Silent tmpfs fallback on mount failure — rejected: session worktrees are user data with no host copy; a ghost READY on a fallback volume is a data-loss posture.
• full sync mode as default — rejected: macOS/HVF benchmarks (Proof Artifact 4, 2026-07-07) show full is ≈12× slower than relaxed (3.1 GB/s vs 254 MB/s) while relaxed still honours VIRTIO_BLK_F_FLUSH.

Gate 3 — Consistent with existing decisions

Result: Pass.

No decisions/ directory exists in this repository, so there are no accepted ADRs to contradict. The document references ADR-0001 (error-handling strategy) and its application is consistent with it — VolumeError in volume.rs uses thiserror (library crate); stop.rs uses anyhow context (application crate) — and with the coding standards in CLAUDE.md.

Gate 4 — No implementation detail masquerading as a decision

Result: Warning.

The "Chosen approach" and "Alternatives considered" sections capture genuine cross-cutting decisions (disk topology, provisioning strategy, failure-mode semantics, sync-mode default). The "Data and interface changes" section, however, intermingles interface-level design with task-level specifics that sit below the cross-cutting threshold for an architecture record:

• Specific Rust function signatures with full parameter lists and return types (e.g. krun_add_disk3, mount_state_volume, quiesce_state_volume).
• File:line-number references into the current codebase (raw.rs:39, main.rs:302-305, store.rs:353-367, rpc.rs:384-413).
• Byte-offset constants (0x53EF at offset 1080) and shell-out command flags (mkfs.ext4 -F, e2fsck -p).

These are not coding preferences dressed as architecture decisions (the gate's core concern), and their presence does not obscure the architectural choices. They are more naturally home in a task sub-issue's "files in scope" or implementation notes. Worth trimming in future architecture records to keep the cross-cutting signal clear. No hand-off required.

Summary

No Blockers. No needs-human applied. No lifecycle label move (architecture boundary; lifecycle moves are at the implementation boundary only).

Generated by sdd-validate for issue #674 · ◷

Generated by sdd-validate for issue #674 · ◷