build: a new compile-time ceiling declares itself or does not land

The convention that tunables live in system/parameters.zig with their
reasoning attached predates this and got 2% compliance — 5 of 235. A
convention with no teeth is how a bare `const maximum_devices = 64` reached
an AMD desktop and cost it USB and storage. This is the same rule with a
gate behind it.

tools/check-bounds.py finds every bound-shaped declaration — a `maximum_*`
const with a literal value, or a type with a literal array length — and
requires the five-field block above it: what it counts, who decides its
size, what it protects, what happens at the limit, and how anyone finds out.

The at-limit vocabulary is closed: refuse, degrade, truncate, grow. There is
deliberately no way to spell "silent", no way to spell "drop", and nothing
meaning "allow", so the behaviours that did the damage cannot be written
down. Truncation is legal only carrying a marker the reader can see, which
is why klog_maximum_message qualifies and a USB descriptor cut at 512 bytes
does not.

An array length that names a declared bound is not itself a bound; only
literal lengths are flagged, which pushes ceilings toward having names.

The 273 that predate the rule are allowlisted so this lands without a
tree-wide sweep in front of it, and that list may only shrink: declaring a
bound means deleting its line, and the check fails on a stale entry too.
Nothing may be added.

Wired into `zig build test` and available alone as `zig build bounds`. Not
in the default build — it reads the whole tree, and a red bounds check
should not stop you booting a kernel.

Five are now declared rather than allowlisted. Writing them out is its own
argument: maximum_devices reads "protects: nothing — this is a sizing guess
about someone else's computer", and maximum_tasks now carries the fact that
it has been raised twice, each time by something that outgrew it.

Verified the gate refuses an undeclared bound, a declared one using
forbidden vocabulary, and an allowlist entry that has since been declared.
Suite 115/115.
This commit is contained in:
Daniel Samson
2026-08-08 11:27:27 +01:00
parent 568823a4fb
commit f4eb88e7d2
7 changed files with 537 additions and 4 deletions
+13
View File
@@ -397,6 +397,19 @@ pub fn build(b: *std.Build) void {
// here (compiled for the host rather than inheriting a freestanding target) —
// which also compile-checks that the three-way split stays self-consistent.
const test_step = b.step("test", "Run tests");
// Every compile-time ceiling states what it counts, who decides its size, what it
// protects, what happens when it is reached, and how anyone finds out
// (docs/os-development/bounds.md). The ~273 that predate the rule are listed in
// tools/bounds-allowlist.txt so this could land without a tree-wide sweep first;
// that list may only shrink. Part of `test` rather than the default build: it reads
// the whole tree, and a red bounds check should not stop you booting a kernel.
const bounds_check = b.addSystemCommand(&.{ "python3", "tools/check-bounds.py" });
bounds_check.setCwd(b.path("."));
const bounds_step = b.step("bounds", "Check that every compile-time ceiling declares itself");
bounds_step.dependOn(&bounds_check.step);
test_step.dependOn(&bounds_check.step);
for ([_][]const u8{
"system/boot-handoff.zig",
"system/abi.zig",