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.

system/kernel/devices-broker.zig

@@ -23,6 +23,14 @@ const abi = @import("abi");
 const platform = @import("platform");
 const device_abi = @import("device-abi");
 
+/// bound: device nodes for the whole machine — firmware-discovered plus every child a
+///        bus driver registers at runtime
+/// decided-by: hardware
+/// protects: nothing — this is a sizing guess about someone else's computer, which is
+///           why an AMD Ryzen booted with a working display, no USB and no storage
+/// at-limit: refuse — ENOSPC from device_register; `dropped` counts discovery losses
+/// observed-by: the bus driver's line naming the reason (pci-bus reconciles functions
+///              found against registered), and kernel.zig:203 for discovery drops
 pub const maximum_devices = 64;
 
 /// Cap on children a single parent may have. A zero-resource child (legal — a USB
@@ -31,6 +39,15 @@ pub const maximum_devices = 64;
 /// `device_register` and exhaust the whole table, permanently denying it to every other
 /// driver. This bounds the blast radius of one claim; a real quota (and a
 /// `device_release` to reclaim on exit) is future work — see docs/driver-model.md.
+///
+/// bound: children one claimed parent may register — in practice every PCI function on
+///        the machine, since pci-bus registers them all under the one host bridge
+/// decided-by: hardware
+/// protects: the shared device table, against a driver looping device_register — but
+///           it is a proxy for an authorisation the kernel does not perform, since any
+///           process may claim any unclaimed device (docs/bounds-track-plan.md phase 2)
+/// at-limit: refuse — ECHILDREN, distinct from a full table
+/// observed-by: pci-bus logs the reason per refused function, and warns at end of scan
 const maximum_children_per_parent = 16;
 
 var devices: [maximum_devices]device_abi.DeviceDescriptor = undefined;

system/kernel/iommu.zig

@@ -39,7 +39,20 @@ const page_size: u64 = abi.page_size;
 const page_mask: u64 = page_size - 1;
 const huge_page_size: u64 = 2 * 1024 * 1024;
 
-/// One domain per claimed PCI function. 64 mirrors devices-broker's device cap.
+/// One domain per claimed PCI function. Coupled to devices-broker's device cap — and
+/// coupled *in code*, by the comptime assert beside `confined` below, because when
+/// these two agreed only by this sentence the disagreement failed open.
+///
+/// Both VT-d and AMD-Vi report the number of domains they support in a capability
+/// register. We should be reading it rather than choosing 64 — docs/bounds-track-plan.md
+/// phase 4.
+///
+/// bound: IOMMU translation domains, one per claimed DMA-capable device
+/// decided-by: hardware
+/// protects: the statically sized domain and confinement tables
+/// at-limit: refuse — ECONFINE; the claim is rolled back and the device is not driven,
+///           because a claim that cannot be confined must not stand
+/// observed-by: the claiming driver's own line naming ECONFINE
 pub const maximum_domains = 64;
 pub const invalid_domain: u16 = 0xFFFF;