Colony Arena swarm-routing ⌥

How the site runs and ships

The original core, compiled

Every simulation on this site runs the protocol's own C++ routing code, the same core/ the ns-3 benchmarks run, compiled to WebAssembly from the protocol's repository at a pinned commit. Nothing is rewritten in JavaScript and nothing is vendored. This page shows how that code is compiled, proven identical, packaged and deployed.

Play AntHocNet The compile Package and deploy

The simulation is the real core

AntHocNet's routing logic lives once, in core/: simulator-agnostic C++14 that takes time, randomness, neighbours and timers through ports and returns decisions. The browser build compiles exactly these core sources, unmodified, at the commit this site pins (6c8a3452c263):

  • core/src/pheromone_table.cpp
  • core/src/pheromone_engine.cpp
  • core/src/ant_history.cpp
  • core/src/ant_message_codec.cpp
  • core/src/ant_router_logic.cpp
  • core/src/link_metric_registry.cpp

Around them, the browser adapter (site/anthocnet/src/: the world, mobility and radio in sim.cpp, the scenarios, and the Embind binding in bindings.cpp) only moves packets and carries out the core's decisions. The JavaScript draws what the WebAssembly module reports; it holds no routing logic (AntHocNet ADR-0021).

From the C++ core to the pageThe compile: the protocol's core sources at the pinned commit and the browser adapter go through Emscripten's CMake toolchain with floating-point contraction off; the result is a WebAssembly module and its ES-module loader, which the game's engine.js imports, cache-busted by the module's hash.core/ (C++14)the protocol's repoat the pinned commitbrowser adaptersite/anthocnet/srcsim · scenarios · bindemcmake + CMakeemsdk 4.0.10-ffp-contract=offanthocnet.wasm+ anthocnet.jscreateAntHocNet()the gameengine.js imports it?v=<sha256>
The compile. The core sources come from the protocol's repository at the pinned commit, never from a copy here.

Proof: byte-identical to the native build

"The same code" is checked, not claimed. The same sources are built twice, natively and to WebAssembly, and both builds of the trace runner replay every built-in scenario. Every ant and data transmission, reception, route change, queue and drop is written with its simulated time; the two traces must match byte for byte, and so must the scenario features' link-rule checks. It runs on every pull request here and on every core/ pull request in AntHocNet, whose CI fetches this adapter.

Native vs WebAssembly parityThe parity gate: the same sources build a native and a WebAssembly trace runner; both run every scenario for seeds 1, 2, 7 and 42 over 120 simulated seconds; the traces are compared byte for byte and must also show delivered packets.same sourcescore/ + adapternative buildahn-web-traceg++ / clangWASM buildahn-web-traceemcc, nodeevery scenarioseeds 1 2 7 42120 s simulateddiffbyte-identicaland delivering
Determinism makes the comparison possible: randomness is drawn into named locals, mobility uses arithmetic sine and cosine, never libm trigonometry.

Package and deploy

One script builds the site, locally and in CI (tools/build-site.sh); one workflow gates and ships it (.github/workflows/pages.yml). A newer core reaches the site only through a protocols.lock bump pull request, which runs every step before anything is published.

From a pinned commit to the live siteThe deploy pipeline: pin the commit in protocols.lock, check the protocol out at it, overlay this repository's browser adapter as its web directory, compile the core to WebAssembly, assemble the game, docs, API and hub, prove parity, run the tests, crawls and browser smokes with axe, deploy from main to GitHub Pages, and smoke the live site.1 pinprotocols.lock40-char SHA2 fetchcheckoutat the pin3 overlaysite/anthocnet→ its web/4 compilecore → WASMemsdk 4.0.105 assemblegame · docs · APIhub · this page6 proveparitybyte-identical7 checktests · crawlssmokes + axe8 deploymain onlyGitHub Pages9 verifylive smokemodule hash
Pull requests run steps 1 to 7; main also deploys and verifies the live site.
The pipeline step by step
Step and whereWhat happensRun it
1. Pin
protocols.lock		One line per protocol: repository, 40-character commit, tag. It changes only by pull request, and that PR runs every gate below.python3 tools/lock.py AntHocNet commit
2. Fetch
.github/workflows/pages.yml		actions/checkout checks the protocol out at the pinned commit (locally, tools/build-site.sh fetches it). Its core/, docs/, api/ and toolchain pins come from there.tools/build-site.sh build/site
3. Overlay
tools/build-site.sh		site/anthocnet/ (the browser adapter, the game and the site shell) is laid over the checkout as its web/. Nothing of the protocol is copied into this repository.—
4. Compile
site/anthocnet/CMakeLists.txt		Emscripten (emsdk 4.0.10, the protocol's own pin) compiles the core's C++ sources and the adapter into anthocnet.wasm plus its ES-module loader anthocnet.js, as C++14, Release, -ffp-contract=off.emcmake cmake -S web -B web/build-wasm && cmake --build web/build-wasm --target anthocnet
5. Assemble
site/anthocnet/build-pages.sh		The game with the module (cache-busted by the module's sha256), the protocol's mkdocs docs at docs/, its Doxygen API at api/, all under one top bar, plus the old-URL redirects. Then tools/render_hub.py writes the hub, every project space and this page.web/build-pages.sh
6. Prove
site/anthocnet/test/parity.sh		The same sources are built natively and to WebAssembly; both run every built-in scenario for seeds 1, 2, 7 and 42 over 120 simulated seconds, and the decision traces must be byte-identical.web/test/parity.sh 120 "1 2 7 42"
7. Check
.github/workflows/pages.yml		The protocol's web tests (quests, translations, Nest coverage, tuning bench, campaign levels, labs), both crawls (every link, asset and anchor), and both browser smokes with axe, in day and night.node site/anthocnet/test/smoke.mjs …; node test/hub-smoke.mjs …
8. Deploy
actions/deploy-pages		Only main deploys: the assembled tree is uploaded as the Pages artifact and published. Pull requests run every step above and stop here.—
9. Verify
site/anthocnet/test/live-smoke.mjs		After the deploy, the live site must serve the module this build made (its hash in engine.js), the game must deliver packets, the docs, API and 404 must carry the top bar, and the hub and every project space must answer 200. A failure opens a tracking issue.—

The full write-up, with the local commands and the toolchain pins, is docs/pipeline.md; the decision behind it is ADR-0001.