Architecture Decision Records¶

The "why" behind the repository's structure and the protocol's deliberate deviations, one decision per file (ADR-0001 explains the practice). All ADRs below are Accepted; where one has been partly superseded or updated, the note says so — the ADR itself carries the detail.

ADR	Decision
0001	Record architecture decisions as ADRs in `docs/adr/`.
0002	One simulator-agnostic algorithm core; thin per-simulator adapters (NS-2, NS-3). The repo's load-bearing invariant.
0003	The core is pure: it returns `RouteDecision`s and performs no I/O; adapters execute them.
0004	Ants are POD value types (`AntMessage`) with a single canonical wire codec — no header-resident pointers.
0005	NS-2 installation is an idempotent, anchor-based source patch — never a forked simulator tree or line-numbered diff.
0006	A 1-byte on-wire protocol version (`kWireVersion`), no negotiation — golden rule 4's foundation.
0007	Keep virtual pheromone / proactive diffusion, but config-gate it so the ablation is runnable. Partly superseded on one point by ADR-0016.
0008	Neighbour liveness via two detectors (hello timeout + MAC transmit-failure fast path); `INeighborProvider` is advisory.
0009	The wire carries path observations, not computed state — backward ants carry the path, nodes compute pheromone locally.
0010	Data forwarding is prev-hop-excluded stochastic; per-flow stickiness is gated and default off.
0011	`NodeAddress` is the node's IP, treated opaquely; broadcast is a `RouteAction`, never an address.
0012	Evaporation is a secondary, time-proportional safety net — the sources have no evaporation term. Updated 2026-08-01 (#262): virtual aging moved onto the same tick/factor as regular.
0013	Track every bug and finding as a GitHub issue (label taxonomy, evidence, acceptance criteria) — the cross-session traceability discipline.
0014	Agent skills are script-first: analysis and validation run in scripts, raw data stays out of LLM context.
0015	One AntHocNet build; the satellite substrate lives in the container image — no separate satellite binary.
0016	Reactive ants may follow the diffusion gradient (directed discovery), gated and default off.
0017	The congestion signal (`ILinkState`) is per-next-hop; its implementation is selected by what the build instantiates (wifi vs point-to-point/ISL).
0018	The proactive emission gate compares virtual and regular pheromone per link, not best-vs-best — cancels the h/(h−1) hop ceiling.
0019	A network family (FANET, VANET, …) is a scenario concern: mobility models, presets, preflight rules, anchors and metrics — never family-specific protocol defaults.
0020	Security ships inside the same implementation behind attributes, default off, with the default path provably byte-identical — no fork, no second binary.

Adding an ADR¶

Number sequentially (NNNN-short-slug.md), follow the existing Context / Decision / Alternatives / Consequences shape, and add a row here. When a change alters a documented decision, update the ADR (or supersede it with a new one) in the same PR — see AGENTS.md "Conventions".