[epic][packaging] Satellite build environment — substrate in an image, not a second build

[danieljoppi]

Sub-epic of #192. How satellite work gets a build environment, decided in ADR-0015.

The decision this implements

Split the image, not the build. A satellite substrate (ns3-leo, Hypatia, Silva's ns3-satellite) is a third-party ns-3 module that must be present in the ns-3 tree — an image concern. But nothing in the AntHocNet module is satellite-specific: core/ is one algorithm, the ns-3 adapter is one Ipv4RoutingProtocol, the #203 multi-interface fix made the data path correct for any topology rather than adding a satellite mode, and isl-grid (#214) is an example rather than a build variant. The only real difference between the regimes is which ns-3 modules are enabled, which is one existing configure line naming both sets.

So: one binary, one configure line, scenario differences in examples and flags. Two builds would drift, and a satellite result would stop being comparable to a MANET one — quietly, with both builds still working. See the ADR for the full argument and the rejected alternatives.

Why this is not blocked on #193 — it unblocks it

Publishing a satellite base image now would bake in a substrate choice #193 has not made. But inverted, this is the missing piece: the decisive question in #197/#198/#200 — can a third-party Ipv4RoutingProtocol be installed on this substrate's nodes, or is its forwarding hard-wired? — can only be answered by a build, and no container runtime is available in the agent environment. A parameterised, unpublished image target is that build.

Hence two phases, in order.

Children

Phase	Ticket	What
1	(child below)	Parameterised sat target in docker/Dockerfile.ns3 + a manually-dispatched workflow that builds ns-3 + a candidate substrate and attempts to install AntHocNet on it. Unpublished. This is the spike harness for #197/#198/#200
2	(child below)	Promote the winner to a published ns3-sat / anthocnet-ns3-sat GHCR image following the existing three-tier tag pattern, once #193 concludes

Constraints

• Satellite CI runs on one ns-3 version, in the manner of the existing validation-anchor and determinism gates (3.42 only) — not the full 3.36–3.48 matrix. The matrix is already the long pole (the 3.36 leg alone is ~8 min) and the substrates support narrower ranges anyway.
• No substrate is vendored into this repository. The repo deliberately does not vendor a simulator (AGENTS.md), and a substrate is part of the simulator installation — vendoring would also drag a third party's licence and release cadence into ours.
• The default images do not change. Adding a substrate to them would either constrain the matrix to the substrate's narrower ns-3 support or break the legs outside it, and would make every MANET build pay for a module it never loads.
• Any behavioural claim from a satellite image still goes through the benchmark-results skill for the noise verdict; an image is a build environment, not a result.

Done when

A satellite substrate can be built and exercised reproducibly from a documented command, docker/README.md describes the resulting image dimension, and the substrate spikes have the environment they need to return a verdict. Phase 2 additionally requires #193 to have chosen.

Related

#192 (parent track), #193 (substrate selection — phase 2 waits on it, phase 1 serves it), #197 / #198 / #200 (the spikes phase 1 unblocks), #195 (own module — a different branch of the track, and the ADR further weakens it), #214 (isl-grid — satellite-shaped scenario needing no special build), ADR-0015, ADR-0002 (the invariant this protects), docker/README.md, .github/workflows/images.yml.

[danieljoppi]

Added a third child: #237 — satellite validation anchors.

The epic covered how the environment gets built (#234 phase 1, #235 phase 2) but not how we know the environment is trustworthy. That gap is the #51 risk repeated: there, the single-hop anchor failing to read ~100% caught a stock 802.11 unicast loss that had been corrupting every number in the repo for every protocol. A new substrate plus a new image plus a new topology, all arriving together, is the same risk class.

The useful property is that satellite anchors can be much stronger than the MANET ones. The MANET anchors are literature-derived and approximate ("AODV ≈ 90–100%"). On a p2p ISL grid with fixed delays there is no channel randomness, so expected values are analytically derivable — e.g. delay must equal h·d + s, which #214 already demonstrated (4×4 torus, 2 hops × 5 ms → 10.39 ms measured).

Two of the anchors exist specifically to validate this epic's output and have no MANET analogue:

• S6 image equivalence — the same logical topology run in the plain image via isl-grid and in the satellite image with the substrate's motion frozen must agree. That is the check that a substrate's ISL model matches one we already trust, and it is only possible because [benchmark][ns3] ISL-grid scenario — routable satellite topology with no orbital mobility #214 gave us a reference.
• S7 substrate-presence null test — isl-grid unchanged in both images must give identical numbers. That directly tests ADR-0015's "one binary" premise; if it ever fails, the ADR is wrong and needs revisiting rather than patching.

Sequencing note that matters for this epic: S1/S2/S5 are runnable today against the existing images, with no substrate at all. Recording those reference values before #234 lands is what makes S6/S7 meaningful later — without them there is nothing to compare the substrate image against.

---

Generated by Claude Code

[danieljoppi]

#237's substrate-free anchors are done and merged (PR #238, ed82017), which changes this epic's readiness rather than just its checklist.

The reference values the substrate image will be judged against now exist, measured on a real ns-3.42 build:

Anchor	Measured	Analytic expectation
single-isl	PDR 100.0%, delay 5.1 ms	h=1, d=5 → 5 ms floor + 0.1 ms serialisation
hop-delay	delay 10.4 ms, PDR 100.0%	h=2, d=5 → 10 ms floor + 0.4 ms
determinism (isl-grid)	identical rows	identity

Why this matters for #234/#235 specifically: S6 (image equivalence) and S7 (substrate-presence null test) are comparisons, and until now there was nothing to compare to. There is now. When the phase-1 image lands, "does the substrate's ISL model agree with the one we trust?" becomes a diff against these exact numbers rather than a judgement call.

S7 in particular is now a sharp test of ADR-0015's central premise: run isl-grid unchanged in the plain image and in the substrate image and require anthocnet,1,4,4,16,32,5.0,2,100.0,10.4,11.0,4.10,12.180,19.480,0.00 byte-for-byte in both. If it differs, installing a substrate perturbs our protocol, the "one binary" claim is false, and the ADR needs overturning rather than patching.

One thing #234's implementer should know: the anchors run on the ns-3.42 leg via check-sat-anchors.sh, and the script already accepts an ISL delay as its third argument — so pointing them at a substrate image is a matter of the tree path, not new gate code.

---

Generated by Claude Code