ADR-0008 — Page-split thresholds
Above 150 devices or 5 zones, output becomes a multi-page site. The thresholds are fixed, not configurable.
Status: accepted
marrow build emits a multi-page site rather than a single file when a topology
has more than 150 devices or more than 5 top-level zones containing
devices. Either condition alone trips it. --single forces one file; there is
no flag to force a site, and the numbers are not user-configurable.
This is the weakest of the eight records against the "hard to reverse, surprising, real trade-off" bar. The numbers are tuned constants, easily changed. What's worth recording is the decision not to make them a user option, and the page-granularity rules that follow from splitting at all.
Why
Two limits converge around a few hundred devices: a reader stops being able to find anything on one canvas, and SVG stops being a sensible rendering target. Splitting addresses both.
Making the threshold configurable was rejected. A user tuning it is really
asking one of two questions — "can I have a single file?" (answered by
--single) or "can I have an inventory table for a small network?" (a feature
request about pages, not about a number). Exposing the constant invites tuning
that produces worse output while looking like a supported knob.
Assumed: essentially all of the above. SITE_DEVICE_THRESHOLD = 150 and
SITE_ZONE_THRESHOLD = 5 are described in the source as "hard rules from the
v2 plan — no page may carry more devices than a reader (or a renderer) can
handle", with no record of how the numbers were chosen or whether
configurability was considered.
Consequences
Two output shapes to support forever, both of which must hold to the same guarantees — offline, deterministic, overlap-free.
Page granularity is controlled by zone nesting, not by a setting. Only top-level zones get pages, and a page covers its whole subtree. So the nesting level an author chooses determines the shape of the built site — an indirect consequence of a structural choice, which is easy to be surprised by.
Documentation promotes a device to its own page. A device earns a
device-360 page if it's tier core, distribution, or edge, or carries a note,
or carries a config. Writing notes changes the site's structure.
Cross-page links need ghosts. A link crossing a page boundary terminates in a dimmed, dashed stub that navigates to the device's own page, so nothing is silently dropped at an edge. That mechanism exists only because of this decision.
--single on a huge topology produces a heavy page, and that's the user's
call to make.
Considered and rejected
A --site flag to force the multi-page shape on small topologies. Not
implemented. If the motivation is wanting the inventory table on a small
network, the right fix is making that available rather than misusing a size
threshold.
Configurable thresholds. Rejected — see above.