a73x

8951743b

docs: record what the test gates rest on

a73x   2026-08-06 09:12

Commit message
docs: record what the test gates rest on

Reviewing the gate plan surfaced four claims nothing had written down: that
image servers send Content-Length, so a truncated download errors before the
checksum compare; that /usr/local/bin is on every agent's PATH, so a fatal
startup preflight cannot refuse a host that would have worked; and that
lowest-free-first allocation is a contract rather than a coincidence, which is
what makes an address-reuse assertion mean anything.
docs/assumptions.md
Old New
@@ -62,6 +62,31 @@ one at all.
62 zero guests. What sleep does to a host *running* VMs is untested, and neither 62 zero guests. What sleep does to a host *running* VMs is untested, and neither
63 reconcile nor lost-VM detection was designed for it. 63 reconcile nor lost-VM detection was designed for it.
64 64
65 ### Image servers send Content-Length
66
67 A truncated download therefore errors inside the copy, before the checksum is
68 compared—so reaching a mismatch means the artifact genuinely is not what was
69 pinned. Underpins treating a checksum mismatch as permanent rather than
70 retrying it twice more for the same verdict.
71 **Unverified**: a length-less identity response, or an HTTP/2 stream closed
72 cleanly early, would truncate indistinguishably. Real image hosts send it.
73
74 ### `/usr/local/bin` is on every agent's PATH
75
76 The startup preflight resolves `cloud-hypervisor` the same way the provisioner
77 later will, so a fatal preflight cannot refuse to start a host that would
78 otherwise have worked. Underpins making the check fatal at all.
79 **Partly proven**: it is where bootstrap installs, and systemd's default PATH
80 covers it. A fleet-wide roll is the moment this would bite, so a cold-start run
81 must pass before one.
82
83 ### Lowest-free-first allocation is a property, not an implementation detail
84
85 Reaping a VM frees its exact address for the next allocation, which is what
86 makes "the address came back" a meaningful assertion rather than a coincidence.
87 **Proven** in code (`ipalloc`), but nothing pins it as a contract—a future
88 allocator that randomised would silently weaken the address-reuse gate.
89
65 ### Fleet hosts can reach the image server locally 90 ### Fleet hosts can reach the image server locally
66 91
67 Serving guest images from the box that serves eitri.sh assumes every host 92 Serving guest images from the box that serves eitri.sh assumes every host