summaryrefslogtreecommitdiff
path: root/modules/swarm
diff options
context:
space:
mode:
authorClaudius "keldu" Holeksa <mail@keldu.de>2026-11-13 14:12:49 +0100
committerClaudius "keldu" Holeksa <mail@keldu.de>2026-11-13 14:12:49 +0100
commite821d617802ebbfff756844e4d9720342fc78a4e (patch)
tree1dcf33b84698b5074218e44ea491b77a9c23ee66 /modules/swarm
parent0c0087ef9482634273ec1a23d3a915754f94926d (diff)
downloadlibs-lbm-e821d617802ebbfff756844e4d9720342fc78a4e.tar.gz
Swarm POCdev
Diffstat (limited to 'modules/swarm')
-rw-r--r--modules/swarm/.nix/derivation.nix38
-rw-r--r--modules/swarm/SConstruct75
-rw-r--r--modules/swarm/c++/SConscript27
-rw-r--r--modules/swarm/c++/capability.hpp199
-rw-r--r--modules/swarm/c++/capacity.hpp236
-rw-r--r--modules/swarm/c++/interpret.hpp113
-rw-r--r--modules/swarm/c++/message.hpp140
-rw-r--r--modules/swarm/c++/probe_search.hpp198
-rw-r--r--modules/swarm/c++/registry.hpp427
-rw-r--r--modules/swarm/c++/run.hpp193
-rw-r--r--modules/swarm/c++/signal.hpp52
-rw-r--r--modules/swarm/c++/swarm.hpp11
-rw-r--r--modules/swarm/c++/wire.hpp119
-rw-r--r--modules/swarm/tests/SConscript32
-rw-r--r--modules/swarm/tests/capacity.cpp234
-rw-r--r--modules/swarm/tests/interpret.cpp133
-rw-r--r--modules/swarm/tests/probe_search.cpp202
-rw-r--r--modules/swarm/tests/registry.cpp298
-rw-r--r--modules/swarm/tests/run.cpp158
-rw-r--r--modules/swarm/tests/signal.cpp82
-rw-r--r--modules/swarm/tests/wire.cpp381
21 files changed, 3348 insertions, 0 deletions
diff --git a/modules/swarm/.nix/derivation.nix b/modules/swarm/.nix/derivation.nix
new file mode 100644
index 0000000..afd07ef
--- /dev/null
+++ b/modules/swarm/.nix/derivation.nix
@@ -0,0 +1,38 @@
+{ lib
+, stdenv
+, scons
+, clang-tools
+, forstio
+, pname
+, version
+, kel
+}:
+
+stdenv.mkDerivation {
+ pname = "${pname}-swarm";
+ inherit version;
+ src = ./..;
+
+ nativeBuildInputs = [
+ scons
+ clang-tools
+ ];
+
+ # The module itself is forstio free -- it is schemas and arithmetic. forstio
+ # is here only for the test runner, exactly as in modules/core.
+ buildInputs = [
+ forstio.core
+ kel.lbm.core
+ ];
+
+ doCheck = true;
+
+ checkPhase = ''
+ scons test
+ ./bin/tests
+ '';
+
+ preferLocalBuild = true;
+
+ outputs = [ "out" "dev" ];
+}
diff --git a/modules/swarm/SConstruct b/modules/swarm/SConstruct
new file mode 100644
index 0000000..089305e
--- /dev/null
+++ b/modules/swarm/SConstruct
@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+
+import sys
+import os
+import os.path
+import glob
+import re
+
+
+if sys.version_info < (3,):
+ def isbasestring(s):
+ return isinstance(s,basestring)
+else:
+ def isbasestring(s):
+ return isinstance(s, (str,bytes))
+
+def add_kel_source_files(self, sources, filetype, lib_env=None, shared=False, target_post=""):
+
+ if isbasestring(filetype):
+ dir_path = self.Dir('.').abspath
+ filetype = sorted(glob.glob(dir_path+"/"+filetype))
+
+ for path in filetype:
+ target_name = re.sub( r'(.*?)(\.cpp|\.c\+\+)', r'\1' + target_post, path )
+ if shared:
+ target_name+='.os'
+ sources.append( self.SharedObject( target=target_name, source=path ) )
+ else:
+ target_name+='.o'
+ sources.append( self.StaticObject( target=target_name, source=path ) )
+ pass
+
+def isAbsolutePath(key, dirname, env):
+ assert os.path.isabs(dirname), "%r must have absolute path syntax" % (key,)
+env_vars = Variables(
+ args=ARGUMENTS
+)
+
+env_vars.Add('prefix',
+ help='Installation target location of build results and headers',
+ default='/usr/local/',
+ validator=isAbsolutePath
+)
+
+env=Environment(ENV=os.environ, variables=env_vars, CPPPATH=[],
+ CPPDEFINES=['SAW_UNIX'],
+ CXXFLAGS=[
+ '-std=c++20',
+ '-g',
+ '-Wall',
+ '-Wextra'
+ ],
+ LIBS=[
+ 'forstio-core'
+ ]
+);
+env.__class__.add_source_files = add_kel_source_files
+env.Tool('compilation_db');
+env.cdb = env.CompilationDatabase('compile_commands.json');
+
+env.objects = [];
+env.sources = [];
+env.headers = [];
+env.targets = [];
+
+Export('env')
+SConscript('c++/SConscript')
+SConscript('tests/SConscript')
+
+env.Alias('cdb', env.cdb);
+env.Alias('all', [env.targets]);
+env.Default('all');
+
+
+env.Alias('install', '$prefix')
diff --git a/modules/swarm/c++/SConscript b/modules/swarm/c++/SConscript
new file mode 100644
index 0000000..4071add
--- /dev/null
+++ b/modules/swarm/c++/SConscript
@@ -0,0 +1,27 @@
+#!/bin/false
+
+import os
+import os.path
+import glob
+
+
+Import('env')
+
+dir_path = Dir('.').abspath
+
+swarm_env = env.Clone();
+
+swarm_env.sources = sorted(glob.glob(dir_path + "/*.cpp"));
+swarm_env.headers = sorted(glob.glob(dir_path + "/*.hpp"));
+
+env.sources += swarm_env.sources;
+env.headers += swarm_env.headers;
+
+# Header only, like core. The StaticLibrary exists so dependents have something
+# to name; it is built from zero translation units.
+objects = []
+swarm_env.add_source_files(objects, swarm_env.sources, shared=False);
+env.library_static = swarm_env.StaticLibrary('#build/kel-lbm-swarm', [objects]);
+
+env.Install('$prefix/lib/', env.library_static);
+env.Install('$prefix/include/kel/lbm/swarm/', swarm_env.headers);
diff --git a/modules/swarm/c++/capability.hpp b/modules/swarm/c++/capability.hpp
new file mode 100644
index 0000000..8497969
--- /dev/null
+++ b/modules/swarm/c++/capability.hpp
@@ -0,0 +1,199 @@
+#pragma once
+
+#include <kel/lbm/abstract/schema.hpp>
+
+/**
+ * What a worker tells the orchestrator about itself.
+ *
+ * The envelope is deliberately backend agnostic: common fields, then one
+ * section named by "kind". Browsers running WebGL2 and native processes are
+ * both first class worker kinds, and the swarm is meant to take WebGPU runners
+ * later; a string tag survives version skew where a positional format does not.
+ *
+ * A worker of another kind carries its own section instead. Nothing has to
+ * carry a section it has no business describing, because each kind gets its own
+ * full capability type -- see CapabilityOf below and the hello variants in
+ * message.hpp.
+ */
+namespace kel {
+namespace lbm {
+namespace sch {
+
+/**
+ * Queryable WebGL2 limits, straight from glGetIntegerv.
+ *
+ * Worth knowing which of these actually bind. max_draw_buffers and
+ * max_color_attachments are guaranteed to be only 4, and since a D2Q9 lattice
+ * needs ceil(9/4) = 3 render targets they are the limits that decide whether a
+ * descriptor fits in a single pass at all. The rest are either generous in
+ * practice or bound by memory long before they bind by count.
+ */
+using GlLimits = Struct<
+ Member<UInt32, "max_texture_size">,
+ Member<UInt32, "max_3d_texture_size">,
+ Member<UInt32, "max_array_texture_layers">,
+ Member<UInt32, "max_draw_buffers">,
+ Member<UInt32, "max_color_attachments">,
+ Member<UInt32, "max_texture_image_units">,
+ Member<UInt32, "max_combined_texture_image_units">,
+ Member<UInt32, "max_renderbuffer_size">,
+ Member<UInt32, "max_fragment_uniform_vectors">,
+ Member<FixedArray<UInt32, 2u>, "max_viewport_dims">
+>;
+
+/**
+ * Extension and context properties.
+ *
+ * color_buffer_float is a hard gate: without EXT_color_buffer_float a float
+ * texture is not color renderable and there is no f32 solver on this device at
+ * all. The others are reported so the orchestrator can decide, not so the
+ * worker can.
+ */
+using GlFeatures = Struct<
+ Member<Bool, "webgl2">,
+ Member<Bool, "offscreen_canvas">,
+ Member<Bool, "color_buffer_float">,
+ Member<Bool, "color_buffer_half_float">,
+ Member<Bool, "texture_float_linear">,
+ Member<Bool, "float_blend">,
+ Member<Bool, "parallel_shader_compile">,
+ Member<Bool, "disjoint_timer_query">
+>;
+
+/**
+ * What the worker measured, as opposed to what it was told.
+ *
+ * There is no queryable "available VRAM" in WebGL2 -- navigator.deviceMemory is
+ * system RAM and unrelated -- and max_texture_size overstates capacity by
+ * roughly a hundredfold on a typical desktop. So these come from an actual
+ * allocation trial.
+ *
+ * probed_bytes_max is the largest allocation that survived; probed_bytes_safe
+ * applies safety_factor to leave room for the canvas, the compositor and other
+ * tabs. Both are reported so the orchestrator can apply its own policy rather
+ * than inheriting the worker's.
+ *
+ * probe_hit_texture_size_bound distinguishes "ran out of memory" from "ran into
+ * max_texture_size", which are very different signals about a device.
+ */
+using GlBudget = Struct<
+ Member<UInt64, "probed_bytes_max">,
+ Member<UInt64, "probed_bytes_safe">,
+ Member<UInt32, "probe_trials">,
+ Member<Bool, "context_lost_during_probe">,
+ Member<Bool, "probe_hit_texture_size_bound">,
+ Member<Float32, "safety_factor">
+>;
+
+/**
+ * One feasible way to lay a lattice out in textures on this device.
+ *
+ * This type has three jobs and keeping it as one type is what stops them
+ * drifting: it is an element of the capability report, it is the assignment
+ * message the orchestrator sends back, and it is the input to the shader
+ * preamble generator.
+ *
+ * The slot tables are the indirection that makes pixel stuffing expressible --
+ * slot_tex_of_q[i] / slot_cmp_of_q[i] say which texture and which channel
+ * direction i lives in, and the aux tables do the same for the non
+ * distribution fields packed into otherwise idle slots.
+ */
+using PackingPlan = Struct<
+ Member<String, "layout">,
+ Member<String, "aux_mode">,
+ Member<UInt8, "d">,
+ Member<UInt8, "q">,
+ Member<UInt8, "ghost">,
+ Member<UInt8, "storage_bits">,
+ Member<UInt8, "slots_per_texel">,
+ Member<UInt8, "textures_df">,
+ Member<UInt8, "textures_aux">,
+ Member<UInt8, "states">,
+ Member<UInt8, "passes">,
+ Member<UInt8, "idle_slots">,
+ Member<FixedArray<UInt32, 3u>, "domain">,
+ Member<FixedArray<UInt32, 2u>, "tiles">,
+ Member<Bool, "tiles_pow2">,
+ Member<FixedArray<UInt32, 2u>, "texture_size">,
+ Member<UInt64, "bytes_total">,
+ Member<UInt64, "bytes_useful">,
+ Member<Array<UInt8, 1u>, "slot_tex_of_q">,
+ Member<Array<UInt8, 1u>, "slot_cmp_of_q">,
+ Member<Array<UInt8, 1u>, "slot_tex_of_aux">,
+ Member<Array<UInt8, 1u>, "slot_cmp_of_aux">,
+ Member<Array<String, 1u>, "aux_names">
+>;
+
+using WebGl2Capability = Struct<
+ Member<GlLimits, "limits">,
+ Member<GlFeatures, "features">,
+ Member<GlBudget, "budget">,
+ Member<Array<PackingPlan, 1u>, "feasible">
+>;
+
+/**
+ * A worker that is a process rather than a browser tab.
+ *
+ * Native workers are not only a test fixture -- they are a worker kind in their
+ * own right, and the orchestrator should be able to hand them real work. What
+ * they report is correspondingly different: there is no texture budget to probe
+ * because there are no textures, so the interesting numbers are threads and
+ * addressable memory.
+ */
+using NativeCapability = Struct<
+ Member<UInt32, "threads">,
+ Member<UInt64, "memory_bytes">,
+ Member<String, "cpu">,
+ Member<Bool, "has_sycl">
+>;
+
+/**
+ * The part every worker reports, whatever it is.
+ *
+ * This is deliberately the *whole* type rather than a prefix of a larger one.
+ * Decoding runs strict, so a struct naming every backend section would oblige a
+ * browser to describe a CPU and a native process to describe a texture budget.
+ * Instead the common part stands alone and is enough to route on: decode this,
+ * read "kind", then decode again as the matching full type below. The backend
+ * section is skipped on the first pass because unknown keys always are.
+ */
+using WorkerCapability = Struct<
+ Member<String, "worker_id">,
+ Member<String, "kind">,
+ Member<String, "schema_version">,
+ Member<UInt64, "reported_at_ms">,
+ Member<String, "user_agent">
+>;
+
+/**
+ * The common part plus exactly one backend section. One alias per kind, so
+ * adding a kind never widens what the existing ones have to fill in.
+ */
+template <typename Section, string_literal Key>
+using CapabilityOf = Struct<
+ Member<String, "worker_id">,
+ Member<String, "kind">,
+ Member<String, "schema_version">,
+ Member<UInt64, "reported_at_ms">,
+ Member<String, "user_agent">,
+ Member<Section, Key>
+>;
+
+using WebGl2WorkerCapability = CapabilityOf<WebGl2Capability, "webgl2">;
+using NativeWorkerCapability = CapabilityOf<NativeCapability, "native">;
+
+/**
+ * The small, frequently resent part: enough to monitor a worker without
+ * re-sending its capability. Rides along on pong so a heartbeat doubles as a
+ * status update.
+ */
+using WorkerLive = Struct<
+ Member<String, "state">,
+ Member<UInt64, "uptime_ms">,
+ Member<UInt64, "steps_done">,
+ Member<String, "last_error">
+>;
+
+} // namespace sch
+} // namespace lbm
+} // namespace kel
diff --git a/modules/swarm/c++/capacity.hpp b/modules/swarm/c++/capacity.hpp
new file mode 100644
index 0000000..4073405
--- /dev/null
+++ b/modules/swarm/c++/capacity.hpp
@@ -0,0 +1,236 @@
+#pragma once
+
+#include <cstdint>
+
+/**
+ * How much lattice fits on a worker.
+ *
+ * This is pure arithmetic over a descriptor's Q and a device's reported limits,
+ * with no GL and no schema, which is the point: the orchestrator needs it to
+ * size assignments, the worker needs it to drive its allocation trial, and
+ * neither reason is a good one to make it untestable without a browser.
+ *
+ * Everything is constexpr so the ceilings can be asserted at compile time
+ * against a descriptor rather than discovered on a device that happens to be
+ * minimum spec.
+ */
+namespace kel {
+namespace lbm {
+namespace swarm {
+
+/**
+ * A WebGL2 implementation is only *guaranteed* these. Real desktop values are
+ * far higher, but a plan that relies on more than this is a plan that works on
+ * the developer's machine.
+ */
+struct webgl2_guaranteed {
+ static constexpr uint32_t max_texture_size = 2048u;
+ static constexpr uint32_t max_3d_texture_size = 256u;
+ static constexpr uint32_t max_array_texture_layers = 256u;
+ static constexpr uint32_t max_draw_buffers = 4u;
+ static constexpr uint32_t max_color_attachments = 4u;
+ static constexpr uint32_t max_texture_image_units = 16u;
+};
+
+/**
+ * Packing a Q-direction lattice into RGBA textures.
+ *
+ * One texel holds four scalars, so a descriptor needs ceil(Q/4) textures and
+ * wastes whatever is left over. The leftovers are not merely waste: the aux
+ * fields (the per cell info flag, later the particle fields) can be stuffed
+ * into them, which is why idle_slots is reported rather than just computed.
+ */
+struct packing_math {
+ static constexpr uint64_t slots_per_texel = 4u;
+
+ static constexpr uint64_t planes(uint64_t q){
+ return (q + slots_per_texel - 1u) / slots_per_texel;
+ }
+
+ static constexpr uint64_t idle_slots(uint64_t q){
+ return planes(q) * slots_per_texel - q;
+ }
+
+ /**
+ * Aux planes needed once the idle slots have been used. Stuffing only
+ * works when the leftovers are big enough; D2Q9 has three idle slots, so
+ * a single info flag fits but the four fields a PSM run wants do not.
+ */
+ static constexpr uint64_t aux_planes(uint64_t q, uint64_t aux_scalars,
+ bool stuffed){
+ if(stuffed and aux_scalars <= idle_slots(q)){
+ return 0u;
+ }
+ return (aux_scalars + slots_per_texel - 1u) / slots_per_texel;
+ }
+
+ static constexpr uint64_t bytes_per_texel(uint64_t storage_bits){
+ return slots_per_texel * storage_bits / 8u;
+ }
+
+ /**
+ * Distributions are double buffered for the ping pong; aux fields are not,
+ * since nothing writes them during a step.
+ */
+ static constexpr uint64_t bytes_per_cell(uint64_t q, uint64_t states,
+ uint64_t aux_scalars, bool stuffed,
+ uint64_t storage_bits = 32u){
+ const uint64_t tex = states * planes(q) + aux_planes(q, aux_scalars, stuffed);
+ return tex * bytes_per_texel(storage_bits);
+ }
+
+ /**
+ * Render targets needed per pass, against what the device allows.
+ *
+ * This is the limit that actually decides whether a descriptor is usable.
+ * Collision couples every direction, so a multi-pass split has to re-read
+ * all planes and recompute rho and u in each pass -- roughly double the
+ * arithmetic for the same bandwidth. Worth detecting rather than
+ * stumbling into.
+ */
+ static constexpr uint64_t passes(uint64_t q, uint64_t mrt){
+ if(mrt == 0u){
+ return 0u;
+ }
+ return (planes(q) + mrt - 1u) / mrt;
+ }
+
+ static constexpr bool fits_single_pass(uint64_t q, uint64_t mrt){
+ return passes(q, mrt) == 1u;
+ }
+};
+
+/**
+ * Integer square root by bisection.
+ *
+ * std::sqrt is not constexpr before C++26 and this has to run at compile time
+ * for the ceiling assertions. Exactness also matters more than speed here: a
+ * domain edge that rounds up by one costs a whole row of cells against a
+ * budget that was measured, not guessed.
+ */
+constexpr uint64_t isqrt(uint64_t value){
+ if(value < 2u){
+ return value;
+ }
+
+ uint64_t low = 1u;
+ uint64_t high = (value / 2u) + 1u;
+
+ while(low < high){
+ const uint64_t mid = low + (high - low + 1u) / 2u;
+ if(mid <= value / mid){
+ low = mid;
+ } else {
+ high = mid - 1u;
+ }
+ }
+
+ return low;
+}
+
+/**
+ * A 2D domain and what it costs.
+ */
+struct domain_2d {
+ uint64_t nx;
+ uint64_t ny;
+
+ constexpr uint64_t cells() const { return nx * ny; }
+};
+
+struct capacity_math {
+ /**
+ * Cells the texture dimension allows, independent of memory.
+ *
+ * On a typical desktop this is around a hundred times looser than what
+ * memory actually permits, which is exactly why the worker measures
+ * instead of trusting it -- but it is still a hard ceiling and a worker
+ * that hits *this* one is telling you something different about itself
+ * than a worker that ran out of memory.
+ */
+ static constexpr uint64_t texture_bound_cells_2d(uint64_t max_texture_size,
+ uint64_t ghost){
+ const uint64_t pad = 2u * ghost;
+ if(max_texture_size <= pad){
+ return 0u;
+ }
+ const uint64_t edge = max_texture_size - pad;
+ return edge * edge;
+ }
+
+ static constexpr uint64_t cells_from_bytes(uint64_t bytes,
+ uint64_t bytes_per_cell){
+ if(bytes_per_cell == 0u){
+ return 0u;
+ }
+ return bytes / bytes_per_cell;
+ }
+
+ static constexpr uint64_t max_cells_2d(uint64_t budget_bytes,
+ uint64_t bytes_per_cell,
+ uint64_t max_texture_size,
+ uint64_t ghost){
+ const uint64_t by_memory = cells_from_bytes(budget_bytes, bytes_per_cell);
+ const uint64_t by_texture = texture_bound_cells_2d(max_texture_size, ghost);
+ return (by_memory < by_texture) ? by_memory : by_texture;
+ }
+
+ /**
+ * Largest domain of a given aspect ratio that fits in a cell count.
+ *
+ * Aspect arrives as a ratio of integers rather than a float so the result
+ * is reproducible across the orchestrator and the worker; they must agree
+ * exactly or an assignment will not fit the allocation the worker made.
+ *
+ * Rounds down on both axes, and clamps each edge to what the texture
+ * dimension allows, so the answer is always feasible rather than merely
+ * close.
+ */
+ static constexpr domain_2d fit_domain_2d(uint64_t cells,
+ uint64_t aspect_num,
+ uint64_t aspect_den,
+ uint64_t max_texture_size,
+ uint64_t ghost){
+ if(cells == 0u or aspect_num == 0u or aspect_den == 0u){
+ return domain_2d{0u, 0u};
+ }
+
+ // ny = sqrt(cells * den / num), nx = ny * num / den
+ uint64_t ny = isqrt((cells * aspect_den) / aspect_num);
+ if(ny == 0u){
+ ny = 1u;
+ }
+ uint64_t nx = (ny * aspect_num) / aspect_den;
+ if(nx == 0u){
+ nx = 1u;
+ }
+
+ const uint64_t pad = 2u * ghost;
+ const uint64_t edge = (max_texture_size > pad) ? (max_texture_size - pad) : 0u;
+ if(edge == 0u){
+ return domain_2d{0u, 0u};
+ }
+ if(nx > edge){
+ nx = edge;
+ }
+ if(ny > edge){
+ ny = edge;
+ }
+
+ // Rounding up through the aspect ratio can overshoot the budget by a
+ // row; give the row back rather than hand out a domain that does not
+ // fit the measurement.
+ while(nx * ny > cells and ny > 1u){
+ --ny;
+ }
+ while(nx * ny > cells and nx > 1u){
+ --nx;
+ }
+
+ return domain_2d{nx, ny};
+ }
+};
+
+} // namespace swarm
+} // namespace lbm
+} // namespace kel
diff --git a/modules/swarm/c++/interpret.hpp b/modules/swarm/c++/interpret.hpp
new file mode 100644
index 0000000..1b2dcfa
--- /dev/null
+++ b/modules/swarm/c++/interpret.hpp
@@ -0,0 +1,113 @@
+#pragma once
+
+#include "capability.hpp"
+#include "capacity.hpp"
+
+#include <kel/lbm/abstract/data.hpp>
+
+#include <cstdint>
+#include <iomanip>
+#include <sstream>
+#include <string>
+
+/**
+ * Turning a reported capability into the one number the orchestrator needs:
+ * how much lattice this worker can hold.
+ *
+ * Quoted in D2Q9 cells so worker kinds are directly comparable. A browser's
+ * figure comes from its measured texture budget; a native worker's from
+ * addressable memory. Neither is a promise -- both ignore everything else
+ * happening on the machine -- but a planning figure that means the same thing
+ * across kinds is what makes a heterogeneous registry useful rather than
+ * decorative.
+ *
+ * Here rather than in the orchestrator because it is pure and therefore worth
+ * testing, and because the browser worker may eventually want to reason about
+ * its own capacity the same way the orchestrator does.
+ */
+namespace kel {
+namespace lbm {
+namespace swarm {
+
+/**
+ * The reference packing every capacity figure is quoted in: D2Q9, double
+ * buffered, the info flag stuffed into an idle slot. 96 bytes per cell.
+ */
+constexpr uint64_t reference_bytes_per_cell(){
+ return packing_math::bytes_per_cell(9u, 2u, 1u, true);
+}
+
+namespace impl {
+
+inline std::string human_bytes(uint64_t bytes){
+ std::ostringstream oss;
+ oss << std::fixed << std::setprecision(1);
+
+ if(bytes >= (1ull << 30)){
+ oss << (static_cast<double>(bytes) / static_cast<double>(1ull << 30))
+ << " GiB";
+ } else if(bytes >= (1ull << 20)){
+ oss << (static_cast<double>(bytes) / static_cast<double>(1ull << 20))
+ << " MiB";
+ } else {
+ oss << bytes << " B";
+ }
+
+ return oss.str();
+}
+
+} // namespace impl
+
+inline uint64_t webgl2_capacity_cells(const data<sch::WebGl2Capability> &cap){
+ const uint64_t budget = cap.get<"budget">().get<"probed_bytes_safe">().get();
+ const uint64_t max_tex = cap.get<"limits">().get<"max_texture_size">().get();
+
+ // Both bounds, tighter wins -- a worker can be limited by either, and
+ // which one it is says something different about the device.
+ return capacity_math::max_cells_2d(budget, reference_bytes_per_cell(),
+ max_tex, 0u);
+}
+
+inline uint64_t native_capacity_cells(const data<sch::NativeCapability> &cap){
+ const uint64_t memory = cap.get<"memory_bytes">().get();
+
+ // No texture dimension to bind against, so memory is the only limit. Take
+ // a quarter of it: the rest of the machine exists.
+ return capacity_math::cells_from_bytes(memory / 4u,
+ reference_bytes_per_cell());
+}
+
+inline std::string webgl2_summary(const data<sch::WebGl2Capability> &cap){
+ std::ostringstream oss;
+
+ oss << "tex " << cap.get<"limits">().get<"max_texture_size">().get()
+ << ", mrt " << cap.get<"limits">().get<"max_draw_buffers">().get()
+ << ", budget " << impl::human_bytes(
+ cap.get<"budget">().get<"probed_bytes_safe">().get());
+
+ if(not cap.get<"features">().get<"color_buffer_float">().get()){
+ // Without this there is no float render target and so no solver at
+ // all. Worth shouting about rather than leaving to be inferred.
+ oss << " [NO FLOAT RENDER]";
+ }
+
+ return oss.str();
+}
+
+inline std::string native_summary(const data<sch::NativeCapability> &cap){
+ std::ostringstream oss;
+
+ oss << cap.get<"threads">().get() << " threads, "
+ << impl::human_bytes(cap.get<"memory_bytes">().get())
+ << ", " << cap.get<"cpu">().stl_string();
+
+ if(cap.get<"has_sycl">().get()){
+ oss << ", sycl";
+ }
+
+ return oss.str();
+}
+
+} // namespace swarm
+} // namespace lbm
+} // namespace kel
diff --git a/modules/swarm/c++/message.hpp b/modules/swarm/c++/message.hpp
new file mode 100644
index 0000000..aba5a9c
--- /dev/null
+++ b/modules/swarm/c++/message.hpp
@@ -0,0 +1,140 @@
+#pragma once
+
+#include "capability.hpp"
+
+#include <string_view>
+
+/**
+ * The worker/orchestrator control protocol.
+ *
+ * Every message is a JSON object carrying the same three leading members --
+ * "type", "worker_id", "seq" -- followed by whatever that type adds. Decoding
+ * happens in two stages (see wire.hpp): read MsgHeader to learn the type, then
+ * decode the full typed struct.
+ *
+ * The reason the protocol is shaped this way rather than as a tagged union is
+ * that sch::Union has no JSON codec. It turns out not to matter: the Struct
+ * decoder skips keys it does not recognise, so reading a header out of a full
+ * message is well defined and costs one extra parse of a short string.
+ *
+ * A versioning note that the strictness buys and charges for. Wire codecs run
+ * strict, so a *missing* member is an error while an *unknown* member is
+ * ignored. That means a newer sender talking to an older receiver is fine, but
+ * an older sender talking to a newer receiver fails as soon as the newer side
+ * adds a member. Adding a field to a message is therefore a breaking change in
+ * one direction, which is what schema_version in the hello/welcome exchange is
+ * for -- catch the mismatch deliberately instead of discovering it as a
+ * confusing decode error.
+ */
+namespace kel {
+namespace lbm {
+
+namespace sch {
+
+/**
+ * Prepends the common members so each message type only states what it adds.
+ */
+template <typename... Members>
+using Envelope = Struct<
+ Member<String, "type">,
+ Member<String, "worker_id">,
+ Member<UInt64, "seq">,
+ Members...
+>;
+
+/// Just the common members. Decoded first to learn which type follows.
+using MsgHeader = Envelope<>;
+
+/**
+ * worker -> orchestrator. First message on the channel.
+ *
+ * MsgHello carries only the common capability fields, which is enough to learn
+ * the worker kind. Decode it first, read capability.kind, then decode the same
+ * text again as the matching variant below -- the backend section is skipped on
+ * the first pass because unknown keys always are.
+ *
+ * The alternative, one hello naming every backend section, does not work: wire
+ * codecs run strict, so it would oblige a browser to describe a CPU.
+ */
+using MsgHello = Envelope<Member<WorkerCapability, "capability">>;
+
+using MsgHelloWebGl2 = Envelope<Member<WebGl2WorkerCapability, "capability">>;
+using MsgHelloNative = Envelope<Member<NativeWorkerCapability, "capability">>;
+
+/// orchestrator -> worker. Confirms registration and sets the heartbeat pace.
+using MsgWelcome = Envelope<
+ Member<UInt64, "heartbeat_ms">,
+ Member<String, "schema_version">
+>;
+
+/// orchestrator -> worker.
+using MsgPing = Envelope<Member<UInt64, "sent_at_ms">>;
+
+/**
+ * worker -> orchestrator. Echoes sent_at_ms so round trip time is measured
+ * against the orchestrator's own clock and the two machines never have to agree
+ * on what time it is.
+ */
+using MsgPong = Envelope<
+ Member<UInt64, "sent_at_ms">,
+ Member<UInt64, "worker_now_ms">,
+ Member<WorkerLive, "live">
+>;
+
+/// worker -> orchestrator. Initialised and idle.
+using MsgReady = Envelope<Member<WorkerLive, "live">>;
+
+/// worker -> orchestrator. Unsolicited: a state change or an error.
+using MsgStatus = Envelope<Member<WorkerLive, "live">>;
+
+} // namespace sch
+
+/**
+ * Wire values for the "type" member.
+ *
+ * Deliberately strings rather than an integer enum: the orchestrator and the
+ * worker are built from the same source today but will not always be, and a
+ * string tag misread is a routing failure you can see in a log, where an
+ * integer tag misread is a silently wrong payload.
+ */
+namespace msg {
+inline constexpr std::string_view hello = "hello";
+inline constexpr std::string_view welcome = "welcome";
+inline constexpr std::string_view ping = "ping";
+inline constexpr std::string_view pong = "pong";
+inline constexpr std::string_view ready = "ready";
+inline constexpr std::string_view status = "status";
+
+/// orchestrator -> everyone. A run begins or ends.
+inline constexpr std::string_view run_start = "run_start";
+inline constexpr std::string_view run_end = "run_end";
+} // namespace msg
+
+/**
+ * Values for WorkerLive's "state". The orchestrator owns stale and gone -- a
+ * worker never reports those about itself, they are conclusions drawn from
+ * missed heartbeats.
+ */
+namespace wstate {
+inline constexpr std::string_view registered = "registered";
+inline constexpr std::string_view ready = "ready";
+inline constexpr std::string_view busy = "busy";
+inline constexpr std::string_view error = "error";
+inline constexpr std::string_view stale = "stale";
+inline constexpr std::string_view gone = "gone";
+} // namespace wstate
+
+/**
+ * Bumped whenever a message or capability schema changes shape. Compared on
+ * hello/welcome so a mismatch is reported rather than hit as a decode failure.
+ */
+inline constexpr std::string_view schema_version = "1";
+
+/// Worker kinds, the tag selecting which capability section is populated.
+namespace wkind {
+inline constexpr std::string_view webgl2 = "webgl2";
+inline constexpr std::string_view native = "native";
+} // namespace wkind
+
+} // namespace lbm
+} // namespace kel
diff --git a/modules/swarm/c++/probe_search.hpp b/modules/swarm/c++/probe_search.hpp
new file mode 100644
index 0000000..f678937
--- /dev/null
+++ b/modules/swarm/c++/probe_search.hpp
@@ -0,0 +1,198 @@
+#pragma once
+
+#include <cstdint>
+
+/**
+ * Finding out how much a device will actually give you.
+ *
+ * WebGL2 reports limits but not capacity. MAX_TEXTURE_SIZE on a typical desktop
+ * implies something like 25 GB of lattice, roughly a hundred times what the GPU
+ * will really hand over, and there is no query for the real figure --
+ * navigator.deviceMemory is system RAM and unrelated. So capacity is measured:
+ * try an allocation, see whether it survives, adjust.
+ *
+ * The strategy lives here rather than next to the GL calls because it is
+ * ordinary arithmetic and deserves to be tested as such. The caller owns the
+ * part that cannot be tested without a browser -- actually allocating -- and
+ * feeds the answers back in:
+ *
+ * allocation_search search{cfg};
+ * while(not search.done()){
+ * search.report(try_allocate(search.candidate()));
+ * }
+ * use(search.best_cells());
+ *
+ * Grow by doubling until something fails, then bisect. Doubling finds the right
+ * order of magnitude in a handful of steps even when devices differ by a factor
+ * of a thousand; bisecting then tightens it without the linear crawl a pure
+ * step search would need.
+ */
+namespace kel {
+namespace lbm {
+namespace swarm {
+
+class allocation_search {
+public:
+ struct config {
+ /**
+ * First attempt. Deliberately small: the opening trial should succeed
+ * on anything that can run at all, because a failure here means the
+ * device is unusable rather than merely modest.
+ */
+ uint64_t start_cells = 65536u;
+
+ /**
+ * Hard ceiling from the texture dimension, in cells. Zero means no
+ * ceiling. Reaching it is a different answer from running out of
+ * memory and is reported separately.
+ */
+ uint64_t ceiling_cells = 0u;
+
+ /// Bisection steps once a failure has bracketed the answer. Four gets
+ /// within about a sixteenth of the bracket, which is finer than the
+ /// figure deserves given it is a moving target anyway.
+ uint64_t bisect_steps = 4u;
+
+ /// Backstop so a device that answers inconsistently cannot spin.
+ uint64_t max_trials = 32u;
+ };
+
+ explicit allocation_search(config cfg) : cfg_{cfg} {
+ candidate_ = cfg_.start_cells;
+
+ if(cfg_.ceiling_cells > 0u and candidate_ > cfg_.ceiling_cells){
+ candidate_ = cfg_.ceiling_cells;
+ }
+
+ if(candidate_ == 0u){
+ phase_ = phase::finished;
+ }
+ }
+
+ bool done() const { return phase_ == phase::finished; }
+
+ /// The cell count to attempt next. Meaningless once done().
+ uint64_t candidate() const { return candidate_; }
+
+ /// Largest allocation that survived. Zero means nothing did.
+ uint64_t best_cells() const { return best_; }
+
+ uint64_t trials() const { return trials_; }
+
+ /**
+ * True when the search stopped because the texture dimension ran out
+ * rather than because memory did. Worth distinguishing: one says the
+ * device is small, the other says it is oddly shaped.
+ */
+ bool hit_ceiling() const { return hit_ceiling_; }
+
+ void report(bool ok){
+ if(phase_ == phase::finished){
+ return;
+ }
+
+ ++trials_;
+
+ if(phase_ == phase::grow){
+ report_grow(ok);
+ } else {
+ report_bisect(ok);
+ }
+
+ if(trials_ >= cfg_.max_trials){
+ phase_ = phase::finished;
+ }
+ }
+
+private:
+ enum class phase { grow, bisect, finished };
+
+ void report_grow(bool ok){
+ if(not ok){
+ failed_at_ = candidate_;
+
+ if(best_ == 0u){
+ // Even the opening attempt failed. There is nothing to
+ // bisect between, and the honest answer is zero.
+ phase_ = phase::finished;
+ return;
+ }
+
+ phase_ = phase::bisect;
+ advance_bisect();
+ return;
+ }
+
+ best_ = candidate_;
+
+ if(cfg_.ceiling_cells > 0u and candidate_ >= cfg_.ceiling_cells){
+ // The texture dimension, not memory, is what stopped us.
+ hit_ceiling_ = true;
+ phase_ = phase::finished;
+ return;
+ }
+
+ uint64_t next = candidate_ * 2u;
+ if(next < candidate_){
+ // Overflow. Nothing sane gets here, but silently wrapping to a
+ // tiny candidate would turn a huge device into a small one.
+ phase_ = phase::finished;
+ return;
+ }
+ if(cfg_.ceiling_cells > 0u and next > cfg_.ceiling_cells){
+ next = cfg_.ceiling_cells;
+ }
+ if(next == candidate_){
+ phase_ = phase::finished;
+ return;
+ }
+
+ candidate_ = next;
+ }
+
+ void report_bisect(bool ok){
+ if(ok){
+ best_ = candidate_;
+ } else {
+ failed_at_ = candidate_;
+ }
+ advance_bisect();
+ }
+
+ void advance_bisect(){
+ if(bisects_done_ >= cfg_.bisect_steps){
+ phase_ = phase::finished;
+ return;
+ }
+ if(failed_at_ <= best_ + 1u){
+ // Bracket closed; there is nothing left between them.
+ phase_ = phase::finished;
+ return;
+ }
+
+ const uint64_t mid = best_ + ((failed_at_ - best_) / 2u);
+ if(mid == best_ or mid == failed_at_){
+ phase_ = phase::finished;
+ return;
+ }
+
+ candidate_ = mid;
+ ++bisects_done_;
+ }
+
+ config cfg_;
+
+ phase phase_ = phase::grow;
+ uint64_t candidate_ = 0u;
+ /// Largest known good.
+ uint64_t best_ = 0u;
+ /// Smallest known bad.
+ uint64_t failed_at_ = 0u;
+ uint64_t trials_ = 0u;
+ uint64_t bisects_done_ = 0u;
+ bool hit_ceiling_ = false;
+};
+
+} // namespace swarm
+} // namespace lbm
+} // namespace kel
diff --git a/modules/swarm/c++/registry.hpp b/modules/swarm/c++/registry.hpp
new file mode 100644
index 0000000..6159a72
--- /dev/null
+++ b/modules/swarm/c++/registry.hpp
@@ -0,0 +1,427 @@
+#pragma once
+
+#include "capability.hpp"
+
+#include <kel/lbm/abstract/data.hpp>
+
+#include <cstdint>
+#include <iomanip>
+#include <map>
+#include <mutex>
+#include <optional>
+#include <sstream>
+#include <string>
+#include <vector>
+
+/**
+ * Who is connected, how healthy they are, and how much they can hold.
+ *
+ * Deliberately free of any transport. The registry never sees a socket, a peer
+ * connection or a data channel -- it is given a session id and timestamps, and
+ * it answers with decisions. Two reasons:
+ *
+ * 1. modules/swarm is compiled by em++ as well as by the host compiler, and
+ * libdatachannel does not exist in a browser. Anything in here that
+ * touched it would make the worker unbuildable.
+ * 2. The liveness state machine is the part most worth testing and the part
+ * least convenient to test through a real connection. Every entry point
+ * takes `now_ms` explicitly rather than reading a clock, so a test can
+ * drive a worker from healthy to dropped in a few microseconds and assert
+ * each transition on the way.
+ *
+ * Resolving a session id back to something sendable is the caller's job.
+ */
+namespace kel {
+namespace lbm {
+namespace swarm {
+
+enum class worker_state {
+ /// Connected, peer connection up, but no hello yet.
+ signalling,
+ /// Hello received and accepted.
+ registered,
+ /// Worker says it is initialised and idle.
+ ready,
+ /// Missed enough heartbeats to be doubtful, not enough to give up.
+ stale,
+};
+
+inline const char *to_string(worker_state state){
+ switch(state){
+ case worker_state::signalling: return "signalling";
+ case worker_state::registered: return "registered";
+ case worker_state::ready: return "ready";
+ case worker_state::stale: return "stale";
+ }
+ return "?";
+}
+
+/**
+ * Liveness thresholds.
+ *
+ * At namespace scope rather than nested in registry so it is a complete type
+ * where the constructor default argument needs it.
+ */
+struct worker_thresholds {
+ /// Missed pings before a worker is called stale.
+ uint64_t stale_after = 3u;
+ /// Missed pings before it is dropped entirely.
+ uint64_t drop_after = 6u;
+};
+
+/**
+ * What the orchestrator knows about one worker.
+ *
+ * Note which id is which. session_id is assigned by the orchestrator and is
+ * unique by construction; worker_id is whatever the worker called itself and is
+ * neither unique nor trustworthy. The registry is keyed on the former and
+ * merely carries the latter, so two workers choosing the same name is a display
+ * annoyance rather than a collision.
+ */
+struct worker_record {
+ std::string session_id;
+ std::string worker_id;
+ std::string kind;
+
+ worker_state state = worker_state::signalling;
+
+ uint64_t connected_at_ms = 0u;
+ uint64_t registered_at_ms = 0u;
+ uint64_t last_seen_ms = 0u;
+
+ /// Sequence of the most recent ping, so a late pong can be told from a
+ /// current one rather than silently resetting the miss counter.
+ uint64_t ping_seq = 0u;
+ uint64_t outstanding_pings = 0u;
+ uint64_t pongs = 0u;
+
+ /// Exponentially weighted mean round trip, milliseconds. Negative until
+ /// the first pong lands.
+ double rtt_ewma_ms = -1.0;
+
+ /**
+ * Roughly how many lattice cells this worker could hold, derived from what
+ * it reported. The whole point of a capability is to answer this, so it is
+ * computed once on registration rather than recomputed per query.
+ */
+ uint64_t capacity_cells = 0u;
+
+ /// Short human readable form of the capability, for the monitor.
+ std::string summary;
+
+ /// Last live block the worker sent, on a pong or a status.
+ data<sch::WorkerLive> live;
+};
+
+/**
+ * The orchestrator's only shared mutable state.
+ *
+ * libdatachannel delivers callbacks on its own threads and the heartbeat runs
+ * on another, so everything here is behind one mutex. The interface is
+ * deliberately coarse -- whole operations rather than accessors -- so callers
+ * cannot hold a reference to a record past the lock, which is the usual way a
+ * design like this goes wrong.
+ */
+class registry {
+public:
+ using thresholds = worker_thresholds;
+
+ explicit registry(worker_thresholds limits = {}) : limits_{limits} {}
+
+ void add_session(const std::string &session_id, uint64_t now_ms){
+ std::lock_guard<std::mutex> lock{mutex_};
+
+ worker_record rec;
+ rec.session_id = session_id;
+ rec.state = worker_state::signalling;
+ rec.connected_at_ms = now_ms;
+ rec.last_seen_ms = now_ms;
+
+ records_[session_id] = std::move(rec);
+ }
+
+ /// Returns false if the session is gone.
+ bool mark_registered(const std::string &session_id,
+ const std::string &worker_id, const std::string &kind,
+ uint64_t capacity_cells, std::string summary,
+ uint64_t now_ms){
+ std::lock_guard<std::mutex> lock{mutex_};
+
+ auto iter = records_.find(session_id);
+ if(iter == records_.end()){
+ return false;
+ }
+
+ auto &rec = iter->second;
+ rec.worker_id = worker_id;
+ rec.kind = kind;
+ rec.capacity_cells = capacity_cells;
+ rec.summary = std::move(summary);
+ rec.state = worker_state::registered;
+ rec.registered_at_ms = now_ms;
+ rec.last_seen_ms = now_ms;
+
+ return true;
+ }
+
+ bool mark_ready(const std::string &session_id, data<sch::WorkerLive> live,
+ uint64_t now_ms){
+ std::lock_guard<std::mutex> lock{mutex_};
+
+ auto iter = records_.find(session_id);
+ if(iter == records_.end()){
+ return false;
+ }
+
+ iter->second.state = worker_state::ready;
+ iter->second.live = std::move(live);
+ iter->second.last_seen_ms = now_ms;
+
+ return true;
+ }
+
+ bool update_live(const std::string &session_id, data<sch::WorkerLive> live,
+ uint64_t now_ms){
+ std::lock_guard<std::mutex> lock{mutex_};
+
+ auto iter = records_.find(session_id);
+ if(iter == records_.end()){
+ return false;
+ }
+
+ iter->second.live = std::move(live);
+ iter->second.last_seen_ms = now_ms;
+
+ return true;
+ }
+
+ /**
+ * Records a pong. `echoed_sent_at_ms` is the orchestrator's own timestamp
+ * coming back, so round trip needs no agreement between the two clocks.
+ * Ignores the liveness effect of a pong whose sequence is not current.
+ */
+ bool record_pong(const std::string &session_id, uint64_t seq,
+ uint64_t echoed_sent_at_ms, data<sch::WorkerLive> live,
+ uint64_t now_ms){
+ std::lock_guard<std::mutex> lock{mutex_};
+
+ auto iter = records_.find(session_id);
+ if(iter == records_.end()){
+ return false;
+ }
+
+ auto &rec = iter->second;
+
+ if(seq != rec.ping_seq){
+ // A pong for a ping we have already given up on. Counting it would
+ // paper over a worker that is consistently one beat behind, so the
+ // liveness side is left alone; the message still proves the channel
+ // works, which is worth recording.
+ rec.last_seen_ms = now_ms;
+ return true;
+ }
+
+ rec.outstanding_pings = 0u;
+ ++rec.pongs;
+ rec.last_seen_ms = now_ms;
+ rec.live = std::move(live);
+
+ // Guard against a clock that went backwards rather than producing a
+ // negative round trip.
+ const double rtt = (now_ms > echoed_sent_at_ms)
+ ? static_cast<double>(now_ms - echoed_sent_at_ms)
+ : 0.0;
+
+ if(rec.rtt_ewma_ms < 0.0){
+ rec.rtt_ewma_ms = rtt;
+ } else {
+ // Smoothing factor chosen to react within a few beats without
+ // letting one slow sample dominate.
+ constexpr double alpha = 0.25;
+ rec.rtt_ewma_ms = (alpha * rtt) + ((1.0 - alpha) * rec.rtt_ewma_ms);
+ }
+
+ // A worker that answers again stops being doubtful. It goes back to
+ // registered rather than ready, because readiness is something only the
+ // worker can assert.
+ if(rec.state == worker_state::stale){
+ rec.state = worker_state::registered;
+ }
+
+ return true;
+ }
+
+ /// Removes a session. Returns the record if there was one.
+ std::optional<worker_record> remove(const std::string &session_id){
+ std::lock_guard<std::mutex> lock{mutex_};
+
+ auto iter = records_.find(session_id);
+ if(iter == records_.end()){
+ return std::nullopt;
+ }
+
+ worker_record rec = std::move(iter->second);
+ records_.erase(iter);
+
+ return rec;
+ }
+
+ /**
+ * One heartbeat tick.
+ *
+ * Bumps the ping sequence and the miss counter for every session, applies
+ * the stale and drop thresholds, and returns what to do. Nothing is sent
+ * from here -- the registry has nothing to send on, and in the orchestrator
+ * sending runs callbacks, which while holding this lock is how it would
+ * deadlock.
+ */
+ struct tick_result {
+ struct ping_target {
+ std::string session_id;
+ uint64_t seq;
+ };
+
+ std::vector<ping_target> to_ping;
+ /// Sessions that passed drop_after; already removed from the registry.
+ std::vector<worker_record> dropped;
+ /// Sessions that just crossed into stale, for logging.
+ std::vector<std::string> newly_stale;
+ };
+
+ tick_result tick(uint64_t now_ms){
+ (void) now_ms;
+
+ tick_result out;
+
+ std::lock_guard<std::mutex> lock{mutex_};
+
+ for(auto iter = records_.begin(); iter != records_.end(); ){
+ auto &rec = iter->second;
+
+ // A session still negotiating has no channel to ping on. It is not
+ // unhealthy, it is just not up yet, so the thresholds do not apply.
+ if(rec.state == worker_state::signalling){
+ ++iter;
+ continue;
+ }
+
+ if(rec.outstanding_pings >= limits_.drop_after){
+ out.dropped.push_back(rec);
+ iter = records_.erase(iter);
+ continue;
+ }
+
+ if(rec.outstanding_pings >= limits_.stale_after and
+ rec.state != worker_state::stale){
+ rec.state = worker_state::stale;
+ out.newly_stale.push_back(rec.session_id);
+ }
+
+ ++rec.ping_seq;
+ ++rec.outstanding_pings;
+
+ out.to_ping.push_back(
+ tick_result::ping_target{rec.session_id, rec.ping_seq});
+
+ ++iter;
+ }
+
+ return out;
+ }
+
+ std::size_t size() const {
+ std::lock_guard<std::mutex> lock{mutex_};
+ return records_.size();
+ }
+
+ /// Snapshot for display. Copies, so the caller holds no lock.
+ std::vector<worker_record> snapshot() const {
+ std::lock_guard<std::mutex> lock{mutex_};
+
+ std::vector<worker_record> out;
+ out.reserve(records_.size());
+ for(const auto &entry : records_){
+ out.push_back(entry.second);
+ }
+
+ return out;
+ }
+
+private:
+ mutable std::mutex mutex_;
+ std::map<std::string, worker_record> records_;
+ worker_thresholds limits_;
+};
+
+namespace impl {
+
+inline std::string human_cells(uint64_t cells){
+ std::ostringstream oss;
+ oss << std::fixed << std::setprecision(1);
+
+ if(cells >= 1000000000ull){
+ oss << (static_cast<double>(cells) / 1e9) << "G";
+ } else if(cells >= 1000000ull){
+ oss << (static_cast<double>(cells) / 1e6) << "M";
+ } else if(cells >= 1000ull){
+ oss << (static_cast<double>(cells) / 1e3) << "k";
+ } else {
+ oss << cells;
+ }
+
+ return oss.str();
+}
+
+} // namespace impl
+
+/// Renders a snapshot as a fixed width table.
+inline std::string render_table(const std::vector<worker_record> &records,
+ uint64_t now_ms){
+ std::ostringstream oss;
+
+ oss << " " << std::left
+ << std::setw(6) << "sess"
+ << std::setw(18) << "worker"
+ << std::setw(9) << "kind"
+ << std::setw(12) << "state"
+ << std::setw(9) << "rtt"
+ << std::setw(8) << "pongs"
+ << std::setw(8) << "seen"
+ << std::setw(8) << "cells"
+ << "detail" << "\n";
+
+ for(const auto &rec : records){
+ std::ostringstream rtt;
+ if(rec.rtt_ewma_ms < 0.0){
+ rtt << "-";
+ } else {
+ rtt << std::fixed << std::setprecision(1) << rec.rtt_ewma_ms << "ms";
+ }
+
+ std::ostringstream seen;
+ const uint64_t age = (now_ms > rec.last_seen_ms)
+ ? (now_ms - rec.last_seen_ms) : 0u;
+ seen << (age / 1000u) << "s";
+
+ oss << " " << std::left
+ << std::setw(6) << rec.session_id
+ << std::setw(18) << (rec.worker_id.empty() ? "-" : rec.worker_id)
+ << std::setw(9) << (rec.kind.empty() ? "-" : rec.kind)
+ << std::setw(12) << to_string(rec.state)
+ << std::setw(9) << rtt.str()
+ << std::setw(8) << rec.pongs
+ << std::setw(8) << seen.str()
+ << std::setw(8) << impl::human_cells(rec.capacity_cells)
+ << rec.summary << "\n";
+ }
+
+ if(records.empty()){
+ oss << " (no workers)\n";
+ }
+
+ return oss.str();
+}
+
+} // namespace swarm
+} // namespace lbm
+} // namespace kel
diff --git a/modules/swarm/c++/run.hpp b/modules/swarm/c++/run.hpp
new file mode 100644
index 0000000..b11bdf5
--- /dev/null
+++ b/modules/swarm/c++/run.hpp
@@ -0,0 +1,193 @@
+#pragma once
+
+#include "message.hpp"
+
+#include <kel/lbm/abstract/data.hpp>
+
+#include <cstdint>
+#include <string>
+#include <string_view>
+#include <string_view>
+
+/**
+ * Run identity.
+ *
+ * There is none in the library today: outputs land in a directory named after
+ * the example, with `<field>_<step>.vtk` inside, so a rerun silently
+ * overwrites the one before it and nothing records what parameters produced
+ * what. A swarm makes that worse rather than better -- several workers write
+ * concurrently, and a result arriving for an unknown run has to be refusable.
+ *
+ * A run id is therefore the first thing the orchestrator mints and the thing
+ * every transfer names. It is sortable, unique, and safe as a directory name:
+ *
+ * 20261112T094501Z-a3f19c
+ *
+ * UTC so that two machines agree, second resolution because runs are not
+ * started faster than that by a human, and six hex digits of entropy so that
+ * two started in the same second by a script still differ.
+ */
+namespace kel {
+namespace lbm {
+namespace sch {
+
+using RunDescriptor = Struct<
+ Member<String, "run_id">,
+ Member<String, "name">,
+ Member<UInt64, "created_at_ms">,
+ Member<String, "schema_version">,
+ /**
+ * Whether halo exchange was on. False until milestone 3, and recorded
+ * rather than assumed: slices run with clamped edges until then, so the
+ * seams are wrong, and a stored result should say so rather than leave
+ * someone to mistake a seam artefact for a solver bug years later.
+ */
+ Member<Bool, "halo_exchange">,
+ /// Opaque to everything here: whatever the admin endpoint was handed.
+ Member<String, "params_json">
+>;
+
+} // namespace sch
+
+namespace swarm {
+
+namespace impl {
+
+/**
+ * Civil date from a day count since 1970-01-01, by Howard Hinnant's algorithm.
+ *
+ * Deliberately not gmtime_r: this is pure arithmetic, so it needs no locale,
+ * no timezone database and no thread safety caveat, and it can be exercised
+ * directly in a test rather than through whatever the host libc happens to
+ * believe. It is also the same on a browser as on the orchestrator, which
+ * matters when both ends format or parse an id.
+ */
+struct civil_date {
+ int64_t year;
+ uint32_t month; ///< 1-12
+ uint32_t day; ///< 1-31
+};
+
+constexpr civil_date civil_from_days(int64_t z){
+ z += 719468;
+ const int64_t era = (z >= 0 ? z : z - 146096) / 146097;
+ const uint64_t doe = static_cast<uint64_t>(z - era * 146097);
+ const uint64_t yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365;
+ const int64_t y = static_cast<int64_t>(yoe) + era * 400;
+ const uint64_t doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
+ const uint64_t mp = (5 * doy + 2) / 153;
+ const uint64_t d = doy - (153 * mp + 2) / 5 + 1;
+ const uint64_t m = mp + (mp < 10 ? 3 : -9);
+ return civil_date{y + (m <= 2 ? 1 : 0), static_cast<uint32_t>(m),
+ static_cast<uint32_t>(d)};
+}
+
+inline void append_padded(std::string &out, uint64_t value, uint32_t width){
+ char buffer[20];
+ uint32_t written = 0u;
+ do {
+ buffer[written++] = static_cast<char>('0' + (value % 10u));
+ value /= 10u;
+ } while(value > 0u and written < sizeof(buffer));
+
+ for(uint32_t i = written; i < width; ++i){
+ out.push_back('0');
+ }
+ for(uint32_t i = written; i > 0u; --i){
+ out.push_back(buffer[i - 1u]);
+ }
+}
+
+inline void append_hex(std::string &out, uint64_t value, uint32_t digits){
+ static constexpr char table[] = "0123456789abcdef";
+ for(uint32_t i = digits; i > 0u; --i){
+ out.push_back(table[(value >> ((i - 1u) * 4u)) & 0xfu]);
+ }
+}
+
+} // namespace impl
+
+/**
+ * Formats a run id.
+ *
+ * Takes the clock and the entropy rather than reading them, for the same
+ * reason the registry takes `now_ms`: a test can then pin both and assert the
+ * exact string, instead of matching a pattern and hoping.
+ *
+ * Only the low 24 bits of `entropy` are used.
+ */
+inline std::string make_run_id(uint64_t now_ms, uint64_t entropy){
+ const int64_t seconds = static_cast<int64_t>(now_ms / 1000u);
+ const int64_t days = (seconds >= 0) ? (seconds / 86400)
+ : ((seconds - 86399) / 86400);
+ const uint64_t secs_of_day = static_cast<uint64_t>(seconds - days * 86400);
+
+ const auto date = impl::civil_from_days(days);
+
+ std::string out;
+ out.reserve(24u);
+
+ impl::append_padded(out, static_cast<uint64_t>(date.year), 4u);
+ impl::append_padded(out, date.month, 2u);
+ impl::append_padded(out, date.day, 2u);
+ out.push_back('T');
+ impl::append_padded(out, secs_of_day / 3600u, 2u);
+ impl::append_padded(out, (secs_of_day / 60u) % 60u, 2u);
+ impl::append_padded(out, secs_of_day % 60u, 2u);
+ out.push_back('Z');
+ out.push_back('-');
+ impl::append_hex(out, entropy, 6u);
+
+ return out;
+}
+
+/**
+ * Whether a string could have come from make_run_id.
+ *
+ * The sink uses a run id as a directory name, so this is also the check that
+ * keeps a hostile id from escaping the storage root -- there is no '/', no
+ * '.', and nothing but a fixed shape of digits and hex.
+ */
+inline bool is_run_id(std::string_view id){
+ if(id.size() != 23u){
+ return false;
+ }
+
+ auto digit = [&](std::size_t i){ return id[i] >= '0' and id[i] <= '9'; };
+ auto hex = [&](std::size_t i){
+ return (id[i] >= '0' and id[i] <= '9') or (id[i] >= 'a' and id[i] <= 'f');
+ };
+
+ for(std::size_t i = 0u; i < 8u; ++i){
+ if(not digit(i)){ return false; }
+ }
+ if(id[8] != 'T'){ return false; }
+ for(std::size_t i = 9u; i < 15u; ++i){
+ if(not digit(i)){ return false; }
+ }
+ if(id[15] != 'Z'){ return false; }
+ if(id[16] != '-'){ return false; }
+ for(std::size_t i = 17u; i < 23u; ++i){
+ if(not hex(i)){ return false; }
+ }
+
+ return true;
+}
+
+} // namespace swarm
+
+namespace sch {
+
+using MsgRunStart = Envelope<Member<RunDescriptor, "run">>;
+using MsgRunEnd = Envelope<Member<String, "run_id">, Member<String, "outcome">>;
+
+} // namespace sch
+
+namespace run_outcome {
+inline constexpr std::string_view finished = "finished";
+inline constexpr std::string_view cancelled = "cancelled";
+inline constexpr std::string_view failed = "failed";
+} // namespace run_outcome
+
+} // namespace lbm
+} // namespace kel
diff --git a/modules/swarm/c++/signal.hpp b/modules/swarm/c++/signal.hpp
new file mode 100644
index 0000000..e8d76bd
--- /dev/null
+++ b/modules/swarm/c++/signal.hpp
@@ -0,0 +1,52 @@
+#pragma once
+
+#include <kel/lbm/abstract/schema.hpp>
+
+#include <string_view>
+
+/**
+ * WebRTC signalling, carried over the WebSocket that precedes the data channel.
+ *
+ * This is a different protocol from the control messages in message.hpp and
+ * deliberately so: signalling exists only to get a peer connection established,
+ * after which everything moves to the data channel. It lives here rather than
+ * in the orchestrator because both the browser worker and the native test
+ * worker have to speak it, and one definition is the only way they cannot
+ * disagree.
+ *
+ * The shapes mirror what a browser hands you, with one deliberate difference:
+ * an ICE candidate arrives from JS as {candidate, sdpMid, sdpMLineIndex} and is
+ * sent on as {type:"candidate", candidate, mid}. Normalising at the JS boundary
+ * keeps the wire uniform -- every message here is a struct with a "type" -- at
+ * the cost of three lines in the worker's transport glue.
+ */
+namespace kel {
+namespace lbm {
+namespace sch {
+
+/// Stage one of the same two stage decode the control protocol uses.
+using SignalHeader = Struct<Member<String, "type">>;
+
+/// "offer" or "answer".
+using SignalDescription = Struct<
+ Member<String, "type">,
+ Member<String, "sdp">
+>;
+
+/// "candidate". mid may be empty; libdatachannel treats that as unhinted.
+using SignalCandidate = Struct<
+ Member<String, "type">,
+ Member<String, "candidate">,
+ Member<String, "mid">
+>;
+
+} // namespace sch
+
+namespace sig {
+inline constexpr std::string_view offer = "offer";
+inline constexpr std::string_view answer = "answer";
+inline constexpr std::string_view candidate = "candidate";
+} // namespace sig
+
+} // namespace lbm
+} // namespace kel
diff --git a/modules/swarm/c++/swarm.hpp b/modules/swarm/c++/swarm.hpp
new file mode 100644
index 0000000..a7c066f
--- /dev/null
+++ b/modules/swarm/c++/swarm.hpp
@@ -0,0 +1,11 @@
+#pragma once
+
+#include "capability.hpp"
+#include "capacity.hpp"
+#include "interpret.hpp"
+#include "message.hpp"
+#include "run.hpp"
+#include "probe_search.hpp"
+#include "registry.hpp"
+#include "signal.hpp"
+#include "wire.hpp"
diff --git a/modules/swarm/c++/wire.hpp b/modules/swarm/c++/wire.hpp
new file mode 100644
index 0000000..7c7c7d0
--- /dev/null
+++ b/modules/swarm/c++/wire.hpp
@@ -0,0 +1,119 @@
+#pragma once
+
+#include "message.hpp"
+
+#include <kel/lbm/abstract/data.hpp>
+#include <kel/lbm/abstract/json.hpp>
+
+#include <string>
+#include <string_view>
+
+/**
+ * Encoding and decoding control messages.
+ *
+ * Everything here runs the JSON codec in strict mode. That is not the codec's
+ * default, and the default is wrong for a wire: codec_config<enc::Json>::strict
+ * is false so that config files can state only their deviations, which means a
+ * worker sending "{}" would decode cleanly into a default constructed struct.
+ * A registration that silently becomes all zeroes is precisely the failure this
+ * protocol must not have, so strict is set explicitly on every wire codec.
+ *
+ * Strict only governs *missing* members. Unknown members are skipped by the
+ * Struct decoder, which is what makes the two stage decode below work and what
+ * lets a newer worker talk to an older orchestrator.
+ */
+namespace kel {
+namespace lbm {
+namespace swarm {
+
+namespace impl {
+template <typename Schema>
+codec<Schema, enc::Json> make_wire_codec(){
+ codec_config<enc::Json> cfg;
+ cfg.strict = true;
+ // Control messages nest at most capability -> webgl2 -> feasible -> plan,
+ // so the default guard against pathological input is already generous.
+ return codec<Schema, enc::Json>{cfg};
+}
+} // namespace impl
+
+/**
+ * Serialise a message to the text that goes on the data channel.
+ */
+template <typename Schema>
+error_or<std::string> encode_message(const data<Schema> &msg){
+ auto wire_codec = impl::make_wire_codec<Schema>();
+
+ data<Schema, enc::Json> out;
+ auto eov = wire_codec.encode(msg, out);
+ if(eov.is_error()){
+ return std::move(eov.get_error());
+ }
+
+ return out.stl_string();
+}
+
+/**
+ * Decode text into a known message type. Fails if any member is absent.
+ */
+template <typename Schema>
+error_or<data<Schema>> decode_message(std::string_view text){
+ auto wire_codec = impl::make_wire_codec<Schema>();
+
+ data<Schema, enc::Json> in{text};
+ data<Schema> out;
+ auto eov = wire_codec.decode(in, out);
+ if(eov.is_error()){
+ return std::move(eov.get_error());
+ }
+
+ return out;
+}
+
+/**
+ * Stage one: read just the common members so the caller learns which type to
+ * decode. The payload is skipped rather than parsed into anything, so this
+ * succeeds for every message type and fails only on genuinely malformed input
+ * or a message missing the common members.
+ */
+inline error_or<data<sch::MsgHeader>> peek_header(std::string_view text){
+ return decode_message<sch::MsgHeader>(text);
+}
+
+/**
+ * Fills in the members every message shares. Kept in one place so a message
+ * built by the orchestrator and one built by the worker cannot disagree about
+ * the shape of the envelope.
+ */
+template <typename Schema>
+void set_envelope(data<Schema> &msg, std::string_view type,
+ std::string_view worker_id, uint64_t seq){
+ msg.template get<"type">().set(std::string{type});
+ msg.template get<"worker_id">().set(std::string{worker_id});
+ msg.template get<"seq">().set(seq);
+}
+
+/**
+ * Convenience for the common shape: build a message, stamp the envelope.
+ */
+template <typename Schema>
+data<Schema> make_message(std::string_view type, std::string_view worker_id,
+ uint64_t seq){
+ data<Schema> msg;
+ set_envelope(msg, type, worker_id, seq);
+ return msg;
+}
+
+/// Reads the "type" of an already decoded header.
+inline std::string_view header_type(const data<sch::MsgHeader> &hdr){
+ return hdr.template get<"type">().stl_view();
+}
+
+/// Reads the "worker_id" of an already decoded header.
+inline std::string_view header_worker_id(const data<sch::MsgHeader> &hdr){
+ return hdr.template get<"worker_id">().stl_view();
+}
+
+} // namespace swarm
+} // namespace lbm
+} // namespace kel
diff --git a/modules/swarm/tests/SConscript b/modules/swarm/tests/SConscript
new file mode 100644
index 0000000..d1b381e
--- /dev/null
+++ b/modules/swarm/tests/SConscript
@@ -0,0 +1,32 @@
+#!/bin/false
+
+import os
+import os.path
+import glob
+
+
+Import('env')
+
+dir_path = Dir('.').abspath
+
+# Environment for base library
+test_cases_env = env.Clone();
+
+test_cases_env.Append(LIBS=['forstio-test']);
+
+test_cases_env.sources = sorted(glob.glob(dir_path + "/*.cpp"))
+test_cases_env.headers = sorted(glob.glob(dir_path + "/*.hpp"))
+
+env.sources += test_cases_env.sources;
+env.headers += test_cases_env.headers;
+
+objects_static = []
+test_cases_env.add_source_files(objects_static, test_cases_env.sources, shared=False);
+test_cases_env.program = test_cases_env.Program('#bin/tests', [objects_static]);
+# , env.library_static]);
+
+# Set Alias
+env.Alias('test', test_cases_env.program);
+env.Alias('check', test_cases_env.program);
+
+env.targets += ['test','check'];
diff --git a/modules/swarm/tests/capacity.cpp b/modules/swarm/tests/capacity.cpp
new file mode 100644
index 0000000..c269aa1
--- /dev/null
+++ b/modules/swarm/tests/capacity.cpp
@@ -0,0 +1,234 @@
+#include <forstio/test/suite.hpp>
+
+#include "../c++/capacity.hpp"
+
+namespace {
+using namespace kel::lbm::swarm;
+
+/**
+ * The packing arithmetic is small enough that the interesting thing to test is
+ * not that it computes, but that the ceilings it implies are the ones we think
+ * they are. These are compile time assertions on purpose: they are statements
+ * about which descriptors are usable, and the answer should not depend on
+ * running the test on a particular device.
+ */
+
+SAW_TEST("Packing / planes and idle slots per descriptor"){
+ // D1Q3, D2Q5, D2Q9, D3Q19, D3Q27.
+ static_assert(packing_math::planes(3u) == 1u, "D1Q3 needs one texture");
+ static_assert(packing_math::planes(5u) == 2u, "D2Q5 needs two textures");
+ static_assert(packing_math::planes(9u) == 3u, "D2Q9 needs three textures");
+ static_assert(packing_math::planes(19u) == 5u, "D3Q19 needs five textures");
+ static_assert(packing_math::planes(27u) == 7u, "D3Q27 needs seven textures");
+
+ static_assert(packing_math::idle_slots(3u) == 1u, "D1Q3 wastes one slot");
+ static_assert(packing_math::idle_slots(5u) == 3u, "D2Q5 wastes three slots");
+ static_assert(packing_math::idle_slots(9u) == 3u, "D2Q9 wastes three slots");
+ static_assert(packing_math::idle_slots(19u) == 1u, "D3Q19 wastes one slot");
+ static_assert(packing_math::idle_slots(27u) == 1u, "D3Q27 wastes one slot");
+
+ SAW_EXPECT(true, "static asserts carry this one");
+}
+
+SAW_TEST("Packing / slots are a partition of the texels"){
+ // planes*4 is exactly Q plus the waste, for every Q. Cheap, but it is the
+ // invariant every slot table depends on.
+ for(uint64_t q = 1u; q <= 64u; ++q){
+ const uint64_t total = packing_math::planes(q) * packing_math::slots_per_texel;
+ SAW_EXPECT(total == q + packing_math::idle_slots(q),
+ "planes*4 must be Q plus the idle slots");
+ SAW_EXPECT(packing_math::idle_slots(q) < packing_math::slots_per_texel,
+ "Waste below a full texel, or a plane was over allocated");
+ }
+}
+
+/**
+ * The limit that decides whether a descriptor is usable at all. WebGL2
+ * guarantees only four colour attachments, so the 3D descriptors cannot write
+ * their whole distribution in one pass on a conformant minimum spec device.
+ * Asserting it here means we learn it from a test rather than from a browser.
+ */
+SAW_TEST("Packing / single pass only reaches Q <= 16 at guaranteed limits"){
+ constexpr uint64_t mrt = webgl2_guaranteed::max_draw_buffers;
+
+ static_assert(packing_math::fits_single_pass(9u, mrt),
+ "D2Q9 must fit one pass on any conformant WebGL2");
+ static_assert(packing_math::fits_single_pass(5u, mrt), "D2Q5 must fit");
+ static_assert(packing_math::fits_single_pass(3u, mrt), "D1Q3 must fit");
+
+ static_assert(not packing_math::fits_single_pass(19u, mrt),
+ "D3Q19 must not claim a single pass at guaranteed limits");
+ static_assert(not packing_math::fits_single_pass(27u, mrt),
+ "D3Q27 must not claim a single pass at guaranteed limits");
+
+ static_assert(packing_math::passes(19u, mrt) == 2u, "D3Q19 needs two passes");
+ static_assert(packing_math::passes(27u, mrt) == 2u, "D3Q27 needs two passes");
+
+ // Sixteen is the boundary: four planes, four attachments.
+ static_assert(packing_math::fits_single_pass(16u, mrt), "Q=16 is the last that fits");
+ static_assert(not packing_math::fits_single_pass(17u, mrt), "Q=17 must not fit");
+
+ SAW_EXPECT(packing_math::passes(9u, 0u) == 0u,
+ "A device reporting no draw buffers must not divide by zero");
+}
+
+SAW_TEST("Packing / stuffing aux fields into idle slots"){
+ // D2Q9 has three idle slots, so a lone info flag rides along free...
+ static_assert(packing_math::aux_planes(9u, 1u, true) == 0u,
+ "One aux scalar must fit D2Q9's idle slots");
+ // ...but the four fields a PSM run wants do not.
+ static_assert(packing_math::aux_planes(9u, 4u, true) == 1u,
+ "Four aux scalars must not fit three idle slots");
+ // Unstuffed always pays for its own plane.
+ static_assert(packing_math::aux_planes(9u, 1u, false) == 1u,
+ "Unstuffed aux must take a plane of its own");
+
+ // D3Q19 and D3Q27 have exactly one idle slot, so info is free there too.
+ static_assert(packing_math::aux_planes(19u, 1u, true) == 0u, "D3Q19 stuffs info");
+ static_assert(packing_math::aux_planes(27u, 1u, true) == 0u, "D3Q27 stuffs info");
+
+ SAW_EXPECT(true, "static asserts carry this one");
+}
+
+SAW_TEST("Packing / bytes per cell"){
+ // D2Q9, double buffered, info stuffed: 2*3 textures * 16 bytes.
+ static_assert(packing_math::bytes_per_cell(9u, 2u, 1u, true) == 96u,
+ "D2Q9 stuffed must be 96 bytes per cell");
+ // Unstuffed adds a plane: 2*3 + 1 textures.
+ static_assert(packing_math::bytes_per_cell(9u, 2u, 1u, false) == 112u,
+ "D2Q9 unstuffed must be 112 bytes per cell");
+ static_assert(packing_math::bytes_per_cell(19u, 2u, 1u, true) == 160u,
+ "D3Q19 stuffed must be 160 bytes per cell");
+ static_assert(packing_math::bytes_per_cell(27u, 2u, 1u, true) == 224u,
+ "D3Q27 stuffed must be 224 bytes per cell");
+
+ SAW_EXPECT(true, "static asserts carry this one");
+}
+
+SAW_TEST("Capacity / integer square root is exact"){
+ static_assert(isqrt(0u) == 0u, "isqrt(0)");
+ static_assert(isqrt(1u) == 1u, "isqrt(1)");
+ static_assert(isqrt(2u) == 1u, "isqrt(2)");
+ static_assert(isqrt(3u) == 1u, "isqrt(3)");
+ static_assert(isqrt(4u) == 2u, "isqrt(4)");
+
+ // The property, not just the samples: isqrt(n)^2 <= n < (isqrt(n)+1)^2.
+ for(uint64_t n = 0u; n < 4096u; ++n){
+ const uint64_t r = isqrt(n);
+ SAW_EXPECT(r * r <= n, "isqrt must not overshoot");
+ SAW_EXPECT((r + 1u) * (r + 1u) > n, "isqrt must not undershoot");
+ }
+
+ // Exact squares near the top of the range, where a float sqrt would drift.
+ const uint64_t big = 3037000499u;
+ SAW_EXPECT(isqrt(big * big) == big, "isqrt must stay exact for large squares");
+ SAW_EXPECT(isqrt(big * big - 1u) == big - 1u, "isqrt must round down");
+}
+
+SAW_TEST("Capacity / the texture bound is the squared usable edge"){
+ // Ghost eats a ring off each side, so the edge is S - 2G.
+ static_assert(capacity_math::texture_bound_cells_2d(2048u, 0u) == 2048u * 2048u,
+ "No ghost means the full edge");
+ static_assert(capacity_math::texture_bound_cells_2d(2048u, 1u) == 2046u * 2046u,
+ "A one cell ring costs two off the edge");
+
+ // A device whose texture dimension cannot even hold the ring has no room.
+ static_assert(capacity_math::texture_bound_cells_2d(2u, 1u) == 0u,
+ "An edge consumed entirely by ghost leaves nothing");
+
+ SAW_EXPECT(true, "static asserts carry this one");
+}
+
+/**
+ * The headline number: how much lattice a worker can actually hold. The point
+ * of the test is the relationship between the two bounds, since on real
+ * hardware the texture bound is roughly a hundred times looser than memory and
+ * a capacity model that used it would be badly wrong.
+ */
+SAW_TEST("Capacity / memory binds before texture size on real devices"){
+ constexpr uint64_t bpc = packing_math::bytes_per_cell(9u, 2u, 1u, true);
+ static_assert(bpc == 96u, "D2Q9 stuffed");
+
+ // A typical desktop: 16384 max texture, 512MB of budget.
+ constexpr uint64_t desktop_tex = 16384u;
+ constexpr uint64_t budget = 512ull * 1024ull * 1024ull;
+
+ constexpr uint64_t by_texture = capacity_math::texture_bound_cells_2d(desktop_tex, 0u);
+ constexpr uint64_t by_memory = capacity_math::cells_from_bytes(budget, bpc);
+
+ static_assert(by_memory < by_texture,
+ "Memory has to be the binding constraint on a typical desktop");
+ static_assert(by_texture / by_memory > 40u,
+ "The texture bound should be looser by a wide margin, not a hair");
+
+ constexpr uint64_t cells = capacity_math::max_cells_2d(budget, bpc, desktop_tex, 0u);
+ static_assert(cells == by_memory, "max_cells must take the tighter bound");
+
+ SAW_EXPECT(cells * bpc <= budget, "The answer has to fit the budget it came from");
+}
+
+SAW_TEST("Capacity / minimum spec can be texture bound instead"){
+ constexpr uint64_t bpc = packing_math::bytes_per_cell(9u, 2u, 1u, true);
+
+ // Guaranteed limits with a generous budget: now the texture dimension is
+ // what runs out first, which is a different thing to report upstream.
+ constexpr uint64_t tex = webgl2_guaranteed::max_texture_size;
+ constexpr uint64_t budget = 4ull * 1024ull * 1024ull * 1024ull;
+
+ constexpr uint64_t by_texture = capacity_math::texture_bound_cells_2d(tex, 1u);
+ constexpr uint64_t by_memory = capacity_math::cells_from_bytes(budget, bpc);
+
+ static_assert(by_texture < by_memory, "Texture size must bind at minimum spec");
+ static_assert(capacity_math::max_cells_2d(budget, bpc, tex, 1u) == by_texture,
+ "max_cells must take the tighter bound here too");
+
+ SAW_EXPECT(true, "static asserts carry this one");
+}
+
+SAW_TEST("Capacity / a fitted domain always fits"){
+ constexpr uint64_t bpc = packing_math::bytes_per_cell(9u, 2u, 1u, true);
+
+ // Sweep budgets and aspect ratios; the invariant is that the answer never
+ // exceeds the cell count it was given, and never exceeds the texture edge.
+ const uint64_t aspects[][2] = {{1u,1u}, {4u,1u}, {1u,4u}, {16u,9u}, {2u,1u}};
+ const uint64_t tex = 16384u;
+ const uint64_t ghost = 1u;
+ const uint64_t edge = tex - 2u * ghost;
+
+ for(uint64_t mb = 1u; mb <= 2048u; mb *= 2u){
+ const uint64_t budget = mb * 1024ull * 1024ull;
+ const uint64_t cells = capacity_math::max_cells_2d(budget, bpc, tex, ghost);
+
+ for(const auto& a : aspects){
+ const auto dom = capacity_math::fit_domain_2d(cells, a[0], a[1], tex, ghost);
+
+ SAW_EXPECT(dom.cells() <= cells,
+ "A fitted domain must not exceed the measured capacity");
+ SAW_EXPECT(dom.nx <= edge and dom.ny <= edge,
+ "A fitted domain must not exceed the texture edge");
+ SAW_EXPECT(dom.nx > 0u and dom.ny > 0u,
+ "A non zero budget must yield a non empty domain");
+ SAW_EXPECT(dom.cells() * bpc <= budget,
+ "The domain must fit the byte budget it was derived from");
+ }
+ }
+}
+
+SAW_TEST("Capacity / fitting respects the requested aspect"){
+ // 4:1 on a square-ish budget should come out roughly four times as wide as
+ // it is tall. Exactness is not the claim -- flooring twice costs a little --
+ // but the shape has to be recognisably what was asked for.
+ const auto dom = capacity_math::fit_domain_2d(1024u * 256u, 4u, 1u, 16384u, 0u);
+
+ SAW_EXPECT(dom.nx > dom.ny, "A 4:1 request must be wider than tall");
+ const uint64_t ratio_x100 = (dom.nx * 100u) / dom.ny;
+ SAW_EXPECT(ratio_x100 >= 380u and ratio_x100 <= 420u,
+ "A 4:1 request must land near 4:1");
+
+ // Degenerate inputs are answered, not asserted on.
+ const auto zero = capacity_math::fit_domain_2d(0u, 4u, 1u, 16384u, 0u);
+ SAW_EXPECT(zero.cells() == 0u, "No capacity means no domain");
+ const auto bad = capacity_math::fit_domain_2d(1024u, 0u, 1u, 16384u, 0u);
+ SAW_EXPECT(bad.cells() == 0u, "A degenerate aspect must not divide by zero");
+}
+}
diff --git a/modules/swarm/tests/interpret.cpp b/modules/swarm/tests/interpret.cpp
new file mode 100644
index 0000000..53374f1
--- /dev/null
+++ b/modules/swarm/tests/interpret.cpp
@@ -0,0 +1,133 @@
+#include <forstio/test/suite.hpp>
+
+#include "../c++/interpret.hpp"
+
+#include <string>
+
+namespace {
+namespace sch {
+using namespace kel::lbm::sch;
+}
+using namespace kel::lbm;
+using namespace kel::lbm::swarm;
+
+/**
+ * The orchestrator's webgl2 branch cannot be reached by the native worker, and
+ * reaching it with a real browser means a human in the loop. These cover the
+ * part of it that is pure: turning a reported capability into a capacity and a
+ * summary line.
+ */
+
+data<sch::WebGl2Capability> make_gl(uint64_t safe_bytes, uint64_t max_tex,
+ bool float_render = true){
+ data<sch::WebGl2Capability> gl;
+ gl.get<"limits">().get<"max_texture_size">().set(
+ static_cast<uint32_t>(max_tex));
+ gl.get<"limits">().get<"max_draw_buffers">().set(8u);
+ gl.get<"budget">().get<"probed_bytes_safe">().set(safe_bytes);
+ gl.get<"features">().get<"color_buffer_float">().set(float_render);
+ return gl;
+}
+
+data<sch::NativeCapability> make_native(uint64_t memory, uint32_t threads,
+ bool sycl = false){
+ data<sch::NativeCapability> nat;
+ nat.get<"threads">().set(threads);
+ nat.get<"memory_bytes">().set(memory);
+ nat.get<"cpu">().set(std::string{"x86_64"});
+ nat.get<"has_sycl">().set(sycl);
+ return nat;
+}
+
+SAW_TEST("Interpret / the reference packing is D2Q9 double buffered"){
+ static_assert(reference_bytes_per_cell() == 96u,
+ "Capacity figures are quoted in 96 byte D2Q9 cells");
+ SAW_EXPECT(true, "static assert carries this one");
+}
+
+SAW_TEST("Interpret / a browser's capacity comes from its measured budget"){
+ // 512MiB safe budget on a roomy device: memory binds, not texture size.
+ const auto gl = make_gl(512ull * 1024ull * 1024ull, 16384u);
+ const uint64_t cells = webgl2_capacity_cells(gl);
+
+ SAW_EXPECT(cells == (512ull * 1024ull * 1024ull) / 96u,
+ "Capacity is the budget divided by the reference cell size");
+ SAW_EXPECT(cells * 96u <= 512ull * 1024ull * 1024ull,
+ "and must fit the budget it came from");
+}
+
+SAW_TEST("Interpret / a small texture dimension binds before memory"){
+ // Generous budget, minimum spec texture size: the texture bound wins.
+ const auto gl = make_gl(4ull * 1024ull * 1024ull * 1024ull, 2048u);
+ const uint64_t cells = webgl2_capacity_cells(gl);
+
+ SAW_EXPECT(cells == 2048ull * 2048ull,
+ "The texture dimension is the binding constraint here");
+}
+
+SAW_TEST("Interpret / a device that measured nothing has no capacity"){
+ // What a worker reports when the probe failed outright -- the case the
+ // node self test produces, and the one a browser produces on a device
+ // with no float render target.
+ const auto gl = make_gl(0u, 16384u, false);
+ SAW_EXPECT(webgl2_capacity_cells(gl) == 0u,
+ "No measured budget means no capacity, not a guess from the limits");
+}
+
+SAW_TEST("Interpret / the summary says when a device cannot render float"){
+ const auto usable = make_gl(256ull * 1024ull * 1024ull, 16384u, true);
+ const std::string ok_line = webgl2_summary(usable);
+ SAW_EXPECT(ok_line.find("tex 16384") != std::string::npos,
+ "The summary names the texture limit");
+ SAW_EXPECT(ok_line.find("256.0 MiB") != std::string::npos,
+ "and the budget, in units a human reads");
+ SAW_EXPECT(ok_line.find("NO FLOAT RENDER") == std::string::npos,
+ "A usable device is not flagged");
+
+ const auto broken = make_gl(0u, 16384u, false);
+ SAW_EXPECT(webgl2_summary(broken).find("NO FLOAT RENDER") != std::string::npos,
+ "A device with no float render target is flagged loudly, since that "
+ "is the difference between slow and impossible");
+}
+
+SAW_TEST("Interpret / a native worker's capacity leaves room for the machine"){
+ const auto nat = make_native(32ull * 1024ull * 1024ull * 1024ull, 16u);
+ const uint64_t cells = native_capacity_cells(nat);
+
+ // A quarter of memory, because the rest of the machine exists.
+ SAW_EXPECT(cells == (32ull * 1024ull * 1024ull * 1024ull / 4u) / 96u,
+ "Native capacity is a quarter of memory in reference cells");
+ SAW_EXPECT(cells * 96u * 4u <= 32ull * 1024ull * 1024ull * 1024ull,
+ "and stays well inside what the machine has");
+}
+
+SAW_TEST("Interpret / native and browser capacities are comparable"){
+ // The point of quoting both in the same unit: a registry holding a mix of
+ // kinds can rank them against each other.
+ const auto gl = make_gl(2ull * 1024ull * 1024ull * 1024ull, 16384u);
+ const auto nat = make_native(8ull * 1024ull * 1024ull * 1024ull, 8u);
+
+ const uint64_t browser_cells = webgl2_capacity_cells(gl);
+ const uint64_t native_cells = native_capacity_cells(nat);
+
+ // 2GiB measured vs 8GiB/4 = 2GiB planned: the same, which is the check
+ // that one unit really is being used for both.
+ SAW_EXPECT(browser_cells == native_cells,
+ "Equivalent budgets must produce equal capacities across kinds");
+}
+
+SAW_TEST("Interpret / the native summary reports what a process can know"){
+ const std::string plain = native_summary(
+ make_native(8ull * 1024ull * 1024ull * 1024ull, 4u));
+ SAW_EXPECT(plain.find("4 threads") != std::string::npos, "thread count");
+ SAW_EXPECT(plain.find("8.0 GiB") != std::string::npos, "memory");
+ SAW_EXPECT(plain.find("x86_64") != std::string::npos, "architecture");
+ SAW_EXPECT(plain.find("sycl") == std::string::npos,
+ "and does not claim sycl when there is none");
+
+ const std::string with_sycl = native_summary(
+ make_native(8ull * 1024ull * 1024ull * 1024ull, 4u, true));
+ SAW_EXPECT(with_sycl.find("sycl") != std::string::npos,
+ "but says so when there is");
+}
+}
diff --git a/modules/swarm/tests/probe_search.cpp b/modules/swarm/tests/probe_search.cpp
new file mode 100644
index 0000000..42f852b
--- /dev/null
+++ b/modules/swarm/tests/probe_search.cpp
@@ -0,0 +1,202 @@
+#include <forstio/test/suite.hpp>
+
+#include "../c++/capacity.hpp"
+#include "../c++/probe_search.hpp"
+
+#include <string>
+
+namespace {
+using namespace kel::lbm::swarm;
+
+/**
+ * Runs a search against a simulated device whose real capacity is `truth`,
+ * returning the outcome. This is the whole point of keeping the strategy apart
+ * from the GL calls: a device that would take a browser and several seconds to
+ * interrogate is a predicate here.
+ */
+struct probe_outcome {
+ uint64_t best;
+ uint64_t trials;
+ bool hit_ceiling;
+};
+
+probe_outcome run_against(uint64_t truth, allocation_search::config cfg = {}){
+ allocation_search search{cfg};
+
+ while(not search.done()){
+ search.report(search.candidate() <= truth);
+ }
+
+ return probe_outcome{search.best_cells(), search.trials(),
+ search.hit_ceiling()};
+}
+
+SAW_TEST("Probe / never reports more than the device can do"){
+ // The property that matters most. Over-reporting means the orchestrator
+ // hands out a domain that does not fit, and the worker fails at the point
+ // where it is least convenient.
+ const uint64_t truths[] = {
+ 65536u, 100000u, 1000000u, 2097152u, 5600000u, 12345678u,
+ 99999999u, 1u << 28,
+ };
+
+ for(uint64_t truth : truths){
+ const auto out = run_against(truth);
+ SAW_EXPECT(out.best <= truth,
+ "A probe must never claim more than the device allows");
+ }
+}
+
+SAW_TEST("Probe / gets close to the real capacity"){
+ // Within a quarter is plenty: the figure is a planning estimate against a
+ // budget that shifts as other tabs come and go.
+ const uint64_t truths[] = {
+ 200000u, 1000000u, 3000000u, 5600000u, 22000000u,
+ };
+
+ for(uint64_t truth : truths){
+ const auto out = run_against(truth);
+ SAW_EXPECT(out.best * 4u >= truth * 3u,
+ std::string{"Probe landed too far below the truth for "}
+ + std::to_string(truth));
+ }
+}
+
+SAW_TEST("Probe / converges in a handful of trials"){
+ // Doubling then bisecting should cost a dozen or so attempts even across
+ // three orders of magnitude of device.
+ allocation_search::config cfg;
+
+ for(uint64_t truth = 65536u; truth < (1ull << 30); truth *= 3u){
+ const auto out = run_against(truth, cfg);
+ SAW_EXPECT(out.trials <= cfg.max_trials,
+ "The backstop must hold");
+ SAW_EXPECT(out.trials <= 20u,
+ std::string{"Too many trials for truth "} + std::to_string(truth));
+ }
+}
+
+SAW_TEST("Probe / a device that cannot do the opening attempt reports zero"){
+ allocation_search::config cfg;
+ cfg.start_cells = 65536u;
+
+ const auto out = run_against(1000u, cfg);
+ SAW_EXPECT(out.best == 0u,
+ "Failing the smallest attempt must report no capacity, not a guess");
+ SAW_EXPECT(out.trials == 1u, "and must not keep trying");
+}
+
+SAW_TEST("Probe / the texture ceiling is reported, not confused with memory"){
+ allocation_search::config cfg;
+ cfg.ceiling_cells = 1000000u;
+
+ // Memory is effectively unlimited here, so the ceiling is what stops it.
+ const auto out = run_against(1ull << 40, cfg);
+ SAW_EXPECT(out.best == cfg.ceiling_cells, "It reaches the ceiling exactly");
+ SAW_EXPECT(out.hit_ceiling,
+ "and says the texture dimension stopped it, not memory");
+
+ // Whereas a device that runs out of memory first must not claim the
+ // ceiling stopped it -- those are different things to report upstream.
+ const auto mem = run_against(300000u, cfg);
+ SAW_EXPECT(not mem.hit_ceiling,
+ "Running out of memory below the ceiling is not a ceiling hit");
+ SAW_EXPECT(mem.best <= 300000u, "and still must not over-report");
+}
+
+SAW_TEST("Probe / a ceiling below the opening attempt is clamped"){
+ allocation_search::config cfg;
+ cfg.start_cells = 65536u;
+ cfg.ceiling_cells = 1024u;
+
+ allocation_search search{cfg};
+ SAW_EXPECT(search.candidate() == 1024u,
+ "The first attempt must not exceed the ceiling");
+
+ const auto out = run_against(1ull << 30, cfg);
+ SAW_EXPECT(out.best == 1024u, "and the answer is the ceiling");
+ SAW_EXPECT(out.hit_ceiling, "reported as such");
+}
+
+SAW_TEST("Probe / a zero ceiling means no capacity at all"){
+ allocation_search::config cfg;
+ cfg.ceiling_cells = 0u;
+ cfg.start_cells = 0u;
+
+ allocation_search search{cfg};
+ SAW_EXPECT(search.done(), "Nothing to try means the search is already over");
+ SAW_EXPECT(search.best_cells() == 0u, "and the answer is zero");
+}
+
+SAW_TEST("Probe / reporting after completion is ignored"){
+ allocation_search search{allocation_search::config{}};
+ while(not search.done()){
+ search.report(false);
+ }
+
+ const uint64_t trials = search.trials();
+ search.report(true);
+ SAW_EXPECT(search.trials() == trials,
+ "A late answer must not restart a finished search");
+ SAW_EXPECT(search.best_cells() == 0u, "nor change the result");
+}
+
+/**
+ * A device that answers inconsistently -- which a real one can, since memory
+ * pressure moves while you are measuring -- must still terminate.
+ */
+SAW_TEST("Probe / an unreliable device still terminates"){
+ allocation_search::config cfg;
+
+ // Alternating yes/no regardless of size.
+ {
+ allocation_search search{cfg};
+ bool flip = true;
+ uint64_t guard = 0u;
+ while(not search.done()){
+ search.report(flip);
+ flip = not flip;
+ SAW_EXPECT(++guard < 1000u, "The search must terminate");
+ }
+ SAW_EXPECT(search.trials() <= cfg.max_trials, "within the backstop");
+ }
+
+ // Always yes, unbounded device: the doubling has to stop somewhere.
+ {
+ allocation_search search{cfg};
+ uint64_t guard = 0u;
+ while(not search.done()){
+ search.report(true);
+ SAW_EXPECT(++guard < 1000u, "Unbounded success must still terminate");
+ }
+ SAW_EXPECT(search.trials() <= cfg.max_trials, "within the backstop");
+ }
+}
+
+/**
+ * The probe answers in cells; the orchestrator wants a domain. Checking the
+ * two compose means the number that comes off a device is usable as it stands.
+ */
+SAW_TEST("Probe / the measured capacity feeds the domain fitting"){
+ constexpr uint64_t bpc = packing_math::bytes_per_cell(9u, 2u, 1u, true);
+ const uint64_t max_tex = 16384u;
+
+ // A device good for about 512MB of lattice.
+ const uint64_t truth = capacity_math::cells_from_bytes(
+ 512ull * 1024ull * 1024ull, bpc);
+
+ allocation_search::config cfg;
+ cfg.ceiling_cells = capacity_math::texture_bound_cells_2d(max_tex, 0u);
+
+ const auto out = run_against(truth, cfg);
+ SAW_EXPECT(out.best <= truth, "Measured capacity must not exceed the truth");
+ SAW_EXPECT(not out.hit_ceiling,
+ "Memory binds well before the texture dimension on a device like this");
+
+ const auto dom = capacity_math::fit_domain_2d(out.best, 4u, 1u, max_tex, 0u);
+ SAW_EXPECT(dom.cells() <= out.best,
+ "The fitted domain must fit what was actually measured");
+ SAW_EXPECT(dom.cells() * bpc <= 512ull * 1024ull * 1024ull,
+ "and therefore fit in the memory the device really had");
+}
+}
diff --git a/modules/swarm/tests/registry.cpp b/modules/swarm/tests/registry.cpp
new file mode 100644
index 0000000..45ebab3
--- /dev/null
+++ b/modules/swarm/tests/registry.cpp
@@ -0,0 +1,298 @@
+#include <forstio/test/suite.hpp>
+
+#include "../c++/message.hpp"
+#include "../c++/registry.hpp"
+
+#include <string>
+
+namespace {
+namespace sch {
+using namespace kel::lbm::sch;
+}
+using namespace kel::lbm;
+using namespace kel::lbm::swarm;
+
+/**
+ * The registry takes `now_ms` at every entry point rather than reading a clock,
+ * so these tests drive a worker from healthy to dropped in microseconds. Doing
+ * this against a real connection would mean sleeping through several heartbeat
+ * intervals and hoping the timing held.
+ */
+
+data<sch::WorkerLive> some_live(){
+ data<sch::WorkerLive> live;
+ live.get<"state">().set(std::string{wstate::ready});
+ live.get<"uptime_ms">().set(0u);
+ live.get<"steps_done">().set(0u);
+ live.get<"last_error">().set(std::string{""});
+ return live;
+}
+
+/**
+ * Registers one worker into an existing registry. Fills in place rather than
+ * returning one: registry holds a mutex, so it is neither copyable nor movable.
+ */
+void register_one(registry &reg){
+ reg.add_session("w1", 1000u);
+ reg.mark_registered("w1", "alpha", std::string{wkind::native}, 1000u,
+ "test worker", 1000u);
+}
+
+worker_record only(const registry &reg){
+ auto snap = reg.snapshot();
+ return snap.empty() ? worker_record{} : snap.front();
+}
+
+SAW_TEST("Registry / a session starts in signalling and is not pinged"){
+ registry reg;
+ reg.add_session("w1", 100u);
+
+ SAW_EXPECT(reg.size() == 1u, "The session is tracked");
+ SAW_EXPECT(only(reg).state == worker_state::signalling,
+ "A fresh session has not said hello yet");
+
+ // Crucially the thresholds must not apply before a hello. A worker still
+ // negotiating is not unhealthy, and counting misses against it would drop
+ // it before it ever had a channel to answer on.
+ for(uint64_t i = 0u; i < 20u; ++i){
+ auto result = reg.tick(200u + i);
+ SAW_EXPECT(result.to_ping.empty(), "A signalling session is not pinged");
+ SAW_EXPECT(result.dropped.empty(), "A signalling session is not dropped");
+ }
+ SAW_EXPECT(reg.size() == 1u, "It is still there after many ticks");
+}
+
+SAW_TEST("Registry / registration records the capability"){
+ registry reg;
+ register_one(reg);
+ const auto rec = only(reg);
+
+ SAW_EXPECT(rec.state == worker_state::registered, "hello moves it on");
+ SAW_EXPECT(rec.worker_id == "alpha", "The self reported name is kept");
+ SAW_EXPECT(rec.kind == wkind::native, "The kind is kept");
+ SAW_EXPECT(rec.capacity_cells == 1000u, "The capacity is kept");
+ SAW_EXPECT(rec.session_id == "w1", "Keyed on the assigned id");
+}
+
+SAW_TEST("Registry / registering an unknown session fails rather than creating one"){
+ registry reg;
+ SAW_EXPECT(not reg.mark_registered("ghost", "a", "native", 1u, "", 1u),
+ "A hello from a session that has gone must not resurrect it");
+ SAW_EXPECT(reg.size() == 0u, "and must not invent a record");
+}
+
+SAW_TEST("Registry / a ping is outstanding until its pong"){
+ registry reg;
+ register_one(reg);
+
+ auto t1 = reg.tick(2000u);
+ SAW_EXPECT(t1.to_ping.size() == 1u, "One worker, one ping");
+ SAW_EXPECT(t1.to_ping.front().seq == 1u, "Sequences start at one");
+ SAW_EXPECT(only(reg).outstanding_pings == 1u, "The ping is outstanding");
+
+ reg.record_pong("w1", 1u, 2000u, some_live(), 2020u);
+ SAW_EXPECT(only(reg).outstanding_pings == 0u, "The pong clears it");
+ SAW_EXPECT(only(reg).pongs == 1u, "and is counted");
+}
+
+SAW_TEST("Registry / round trip is measured against our own clock"){
+ registry reg;
+ register_one(reg);
+
+ reg.tick(2000u);
+ // The worker echoes the timestamp we sent, so no clock agreement needed.
+ reg.record_pong("w1", 1u, 2000u, some_live(), 2040u);
+ SAW_EXPECT(only(reg).rtt_ewma_ms == 40.0,
+ "The first sample seeds the average exactly");
+
+ // Second sample at 80ms: 0.25*80 + 0.75*40 = 50.
+ reg.tick(3000u);
+ reg.record_pong("w1", 2u, 3000u, some_live(), 3080u);
+ const double rtt = only(reg).rtt_ewma_ms;
+ SAW_EXPECT(rtt > 49.9 and rtt < 50.1, "Smoothing weights the history");
+}
+
+SAW_TEST("Registry / a clock that goes backwards does not produce a negative rtt"){
+ registry reg;
+ register_one(reg);
+
+ reg.tick(2000u);
+ // Echoed timestamp later than now. Should clamp, not underflow into a
+ // huge positive via unsigned subtraction.
+ reg.record_pong("w1", 1u, 5000u, some_live(), 2000u);
+ SAW_EXPECT(only(reg).rtt_ewma_ms == 0.0, "A backwards clock reads as zero");
+}
+
+/**
+ * The transition that actually matters, and the one that is tedious to provoke
+ * against a live connection.
+ */
+SAW_TEST("Registry / stale then dropped, at the configured thresholds"){
+ worker_thresholds limits;
+ limits.stale_after = 2u;
+ limits.drop_after = 4u;
+
+ registry reg{limits};
+ register_one(reg);
+ uint64_t t = 2000u;
+
+ // Beat 1 and 2: outstanding climbs, still considered healthy.
+ auto b1 = reg.tick(t += 100u);
+ SAW_EXPECT(b1.newly_stale.empty(), "One miss is not yet doubtful");
+ SAW_EXPECT(only(reg).state == worker_state::registered, "still registered");
+
+ auto b2 = reg.tick(t += 100u);
+ SAW_EXPECT(b2.newly_stale.empty(), "Two outstanding, threshold not crossed yet");
+
+ // Beat 3 sees outstanding == 2, which meets stale_after.
+ auto b3 = reg.tick(t += 100u);
+ SAW_EXPECT(b3.newly_stale.size() == 1u, "Crossing into stale is reported once");
+ SAW_EXPECT(b3.newly_stale.front() == "w1", "and names the session");
+ SAW_EXPECT(only(reg).state == worker_state::stale, "and is recorded");
+
+ // Reported once, not every beat afterwards -- otherwise the log fills up.
+ auto b4 = reg.tick(t += 100u);
+ SAW_EXPECT(b4.newly_stale.empty(), "Stale is announced once, not repeatedly");
+ SAW_EXPECT(only(reg).state == worker_state::stale, "and it stays stale");
+
+ // Beat 5 sees outstanding == 4, which meets drop_after.
+ auto b5 = reg.tick(t += 100u);
+ SAW_EXPECT(b5.dropped.size() == 1u, "It is dropped at the threshold");
+ SAW_EXPECT(b5.dropped.front().worker_id == "alpha",
+ "The dropped record is handed back so the caller can log it");
+ SAW_EXPECT(reg.size() == 0u, "and removed from the registry");
+ SAW_EXPECT(b5.to_ping.empty(), "A dropped session is not also pinged");
+}
+
+SAW_TEST("Registry / answering again clears stale"){
+ worker_thresholds limits;
+ limits.stale_after = 2u;
+ limits.drop_after = 10u;
+
+ registry reg{limits};
+ register_one(reg);
+ uint64_t t = 2000u;
+
+ reg.tick(t += 100u);
+ reg.tick(t += 100u);
+ auto b3 = reg.tick(t += 100u);
+ SAW_EXPECT(only(reg).state == worker_state::stale, "It went stale");
+
+ // The worker comes back, answering the ping that is actually outstanding.
+ reg.record_pong("w1", b3.to_ping.front().seq, t, some_live(), t + 5u);
+
+ SAW_EXPECT(only(reg).state == worker_state::registered,
+ "Answering clears the doubt");
+ SAW_EXPECT(only(reg).outstanding_pings == 0u, "and resets the miss count");
+}
+
+SAW_TEST("Registry / recovery does not silently restore readiness"){
+ // Readiness is something only the worker can assert, so a recovered worker
+ // goes back to registered and has to say 'ready' again.
+ worker_thresholds limits;
+ limits.stale_after = 1u;
+ limits.drop_after = 10u;
+
+ registry reg{limits};
+ register_one(reg);
+ reg.mark_ready("w1", some_live(), 1500u);
+ SAW_EXPECT(only(reg).state == worker_state::ready, "It was ready");
+
+ reg.tick(2000u);
+ auto b2 = reg.tick(2100u);
+ SAW_EXPECT(only(reg).state == worker_state::stale, "Then it went quiet");
+
+ reg.record_pong("w1", b2.to_ping.front().seq, 2100u, some_live(), 2110u);
+ SAW_EXPECT(only(reg).state == worker_state::registered,
+ "Recovery must not reassert readiness on the worker's behalf");
+}
+
+/**
+ * A worker consistently one beat behind would otherwise look perfectly healthy:
+ * every tick adds a miss, every late pong clears it, and the miss count never
+ * reaches the threshold.
+ */
+SAW_TEST("Registry / a stale sequence pong does not clear the miss count"){
+ registry reg;
+ register_one(reg);
+
+ auto b1 = reg.tick(2000u);
+ const uint64_t old_seq = b1.to_ping.front().seq;
+
+ reg.tick(2100u);
+ reg.tick(2200u);
+ SAW_EXPECT(only(reg).outstanding_pings == 3u, "Three pings outstanding");
+
+ // Answer the first one, long after it was superseded.
+ reg.record_pong("w1", old_seq, 2000u, some_live(), 2250u);
+
+ SAW_EXPECT(only(reg).outstanding_pings == 3u,
+ "A pong for a superseded ping must not clear the misses");
+ SAW_EXPECT(only(reg).pongs == 0u, "nor count as an answer");
+ SAW_EXPECT(only(reg).last_seen_ms == 2250u,
+ "but it does prove the channel is alive");
+}
+
+SAW_TEST("Registry / removal returns the record once"){
+ registry reg;
+ register_one(reg);
+
+ auto gone = reg.remove("w1");
+ SAW_EXPECT(gone.has_value(), "Removing returns what was removed");
+ SAW_EXPECT(gone->worker_id == "alpha", "with its contents intact");
+ SAW_EXPECT(reg.size() == 0u, "and empties the registry");
+
+ // Idempotent: several teardown paths converge on this and whichever
+ // arrives first should win without the others erroring.
+ SAW_EXPECT(not reg.remove("w1").has_value(), "A second removal is a no-op");
+}
+
+SAW_TEST("Registry / many workers are ticked independently"){
+ worker_thresholds limits;
+ limits.stale_after = 2u;
+ limits.drop_after = 3u;
+
+ registry reg{limits};
+ for(uint64_t i = 0u; i < 5u; ++i){
+ const std::string id = "w" + std::to_string(i);
+ reg.add_session(id, 1000u);
+ reg.mark_registered(id, "worker" + std::to_string(i), "native",
+ 1000u * i, "", 1000u);
+ }
+
+ uint64_t t = 1000u;
+ for(int beat = 0; beat < 3; ++beat){
+ auto result = reg.tick(t += 100u);
+ // w3 keeps answering; everyone else goes quiet.
+ for(const auto &target : result.to_ping){
+ if(target.session_id == "w3"){
+ reg.record_pong("w3", target.seq, t, some_live(), t + 1u);
+ }
+ }
+ }
+
+ auto result = reg.tick(t += 100u);
+ SAW_EXPECT(result.dropped.size() == 4u, "The four silent workers are dropped");
+ SAW_EXPECT(reg.size() == 1u, "The responsive one survives");
+ SAW_EXPECT(only(reg).session_id == "w3", "and it is the right one");
+}
+
+SAW_TEST("Registry / the table renders without a worker and with one"){
+ registry reg;
+ SAW_EXPECT(render_table(reg.snapshot(), 0u).find("(no workers)")
+ != std::string::npos, "An empty registry says so");
+
+ registry one;
+ register_one(one);
+ one.tick(2000u);
+ one.record_pong("w1", 1u, 2000u, some_live(), 2010u);
+
+ const std::string table = render_table(one.snapshot(), 3000u);
+ SAW_EXPECT(table.find("alpha") != std::string::npos, "The worker is listed");
+ SAW_EXPECT(table.find("native") != std::string::npos, "with its kind");
+ SAW_EXPECT(table.find("10.0ms") != std::string::npos, "and its round trip");
+ // 1000 cells renders as a bare count, not scaled.
+ SAW_EXPECT(table.find("1.0k") != std::string::npos,
+ "and a human readable capacity");
+}
+}
diff --git a/modules/swarm/tests/run.cpp b/modules/swarm/tests/run.cpp
new file mode 100644
index 0000000..b7cd8f5
--- /dev/null
+++ b/modules/swarm/tests/run.cpp
@@ -0,0 +1,158 @@
+#include <forstio/test/suite.hpp>
+
+#include "../c++/run.hpp"
+#include "../c++/wire.hpp"
+
+#include <set>
+#include <string>
+
+namespace {
+namespace sch {
+using namespace kel::lbm::sch;
+}
+using namespace kel::lbm;
+using namespace kel::lbm::swarm;
+
+/// 2026-11-12T09:45:01Z, as milliseconds since the epoch.
+constexpr uint64_t reference_ms = 1794476701000ull;
+
+SAW_TEST("Run / the id has the documented shape"){
+ // Pinned exactly rather than pattern matched: make_run_id takes its clock
+ // and entropy, so the whole string is determined and a drift in either
+ // half should fail loudly.
+ const std::string id = make_run_id(reference_ms, 0xa3f19cull);
+ SAW_EXPECT(id == "20261112T094501Z-a3f19c",
+ std::string{"unexpected run id: "} + id);
+ SAW_EXPECT(id.size() == 23u, "and the fixed width the sink relies on");
+}
+
+SAW_TEST("Run / only the low 24 bits of entropy are used"){
+ const std::string a = make_run_id(reference_ms, 0xffffffffffffffffull);
+ SAW_EXPECT(a == "20261112T094501Z-ffffff", "the top bits are discarded");
+
+ const std::string b = make_run_id(reference_ms, 0x0ull);
+ SAW_EXPECT(b == "20261112T094501Z-000000", "and zero pads rather than shortens");
+}
+
+SAW_TEST("Run / ids sort chronologically as plain strings"){
+ // The point of the format: `ls` and a std::map give time order for free,
+ // with no parsing anywhere.
+ const std::string earlier = make_run_id(reference_ms, 0xffffffull);
+ const std::string later = make_run_id(reference_ms + 1000u, 0x000000ull);
+
+ SAW_EXPECT(earlier < later,
+ "A later run must sort after an earlier one even with lower entropy");
+
+ // Across a month and a year boundary, where a naive format breaks.
+ SAW_EXPECT(make_run_id(reference_ms, 0u)
+ < make_run_id(reference_ms + 30ull * 86400000ull, 0u),
+ "and across a month");
+}
+
+SAW_TEST("Run / the civil date conversion handles the awkward cases"){
+ using kel::lbm::swarm::impl::civil_from_days;
+
+ // The epoch itself.
+ {
+ const auto d = civil_from_days(0);
+ SAW_EXPECT(d.year == 1970 and d.month == 1u and d.day == 1u, "epoch");
+ }
+ // A leap day, which is where a hand-rolled conversion usually goes wrong.
+ {
+ const auto d = civil_from_days(19782); // 2024-02-29
+ SAW_EXPECT(d.year == 2024 and d.month == 2u and d.day == 29u,
+ "2024 is a leap year and the 29th exists");
+ }
+ // 2000 was a leap year despite being a century.
+ {
+ const auto d = civil_from_days(11016); // 2000-02-29
+ SAW_EXPECT(d.year == 2000 and d.month == 2u and d.day == 29u,
+ "the 400 year rule");
+ }
+ // The day after the 2024 leap day, so an off-by-one shows.
+ {
+ const auto d = civil_from_days(19783);
+ SAW_EXPECT(d.year == 2024 and d.month == 3u and d.day == 1u, "march 1st");
+ }
+}
+
+SAW_TEST("Run / midnight and the last second of a day format correctly"){
+ // 2026-11-12T00:00:00Z
+ const uint64_t midnight = (reference_ms / 86400000ull) * 86400000ull;
+ SAW_EXPECT(make_run_id(midnight, 0u) == "20261112T000000Z-000000",
+ "midnight is all zeroes, not blank");
+
+ SAW_EXPECT(make_run_id(midnight + 86399000ull, 0u)
+ == "20261112T235959Z-000000", "and the last second is 235959");
+
+ // One more second rolls the date rather than producing 24:00:00.
+ SAW_EXPECT(make_run_id(midnight + 86400000ull, 0u)
+ == "20261113T000000Z-000000", "which rolls into the next day");
+}
+
+/**
+ * The sink uses a run id as a directory name, so this is the check that stops
+ * a hostile id escaping the storage root.
+ */
+SAW_TEST("Run / validation rejects anything that is not the exact shape"){
+ SAW_EXPECT(is_run_id(make_run_id(reference_ms, 0xabcdefull)),
+ "what make_run_id produces must validate");
+
+ const char *bad[] = {
+ "",
+ "20261112T094501Z", // no entropy
+ "20261112T094501Z-a3f19", // one short
+ "20261112T094501Z-a3f19cd", // one long
+ "20261112t094501Z-a3f19c", // lowercase separator
+ "20261112T094501Z-A3F19C", // uppercase hex
+ "20261112T094501Z-a3f19g", // 'g' is not hex
+ "2026111 T094501Z-a3f19c", // space
+ "../../etc/passwd000000Z-a3f19c", // the reason this function exists
+ "20261112T094501Z/a3f19c", // a separator that is a path one
+ };
+
+ for(const char *id : bad){
+ SAW_EXPECT(not is_run_id(id),
+ std::string{"must be rejected: "} + id);
+ }
+}
+
+SAW_TEST("Run / distinct entropy gives distinct ids within one second"){
+ std::set<std::string> seen;
+ for(uint64_t e = 0u; e < 512u; ++e){
+ seen.insert(make_run_id(reference_ms, e));
+ }
+ SAW_EXPECT(seen.size() == 512u,
+ "Two runs started in the same second must not collide");
+}
+
+SAW_TEST("Run / a run descriptor round trips on the wire"){
+ auto start = make_message<sch::MsgRunStart>(msg::run_start, "orch", 0u);
+
+ auto &run = start.get<"run">();
+ run.get<"run_id">().set(make_run_id(reference_ms, 0xa3f19cull));
+ run.get<"name">().set(std::string{"poiseuille 1024x256"});
+ run.get<"created_at_ms">().set(reference_ms);
+ run.get<"schema_version">().set(std::string{schema_version});
+ run.get<"halo_exchange">().set(false);
+ run.get<"params_json">().set(std::string{R"({"nx":1024,"ny":256})"});
+
+ auto eo_text = encode_message<sch::MsgRunStart>(start);
+ SAW_EXPECT(not eo_text.is_error(), "a run start encodes");
+
+ auto eo_hdr = peek_header(eo_text.get_value());
+ SAW_EXPECT(not eo_hdr.is_error(), "and routes");
+ SAW_EXPECT(header_type(eo_hdr.get_value()) == msg::run_start, "as a run start");
+
+ auto eo_back = decode_message<sch::MsgRunStart>(eo_text.get_value());
+ SAW_EXPECT(not eo_back.is_error(), "and decodes");
+
+ const auto &back = eo_back.get_value().get<"run">();
+ SAW_EXPECT(back.get<"run_id">().stl_view() == "20261112T094501Z-a3f19c",
+ "the id survives");
+ SAW_EXPECT(not back.get<"halo_exchange">().get(),
+ "and the record that the seams were clamped survives with it");
+ SAW_EXPECT(back.get<"params_json">().stl_view() == R"({"nx":1024,"ny":256})",
+ "the opaque params survive being nested inside JSON");
+}
+}
diff --git a/modules/swarm/tests/signal.cpp b/modules/swarm/tests/signal.cpp
new file mode 100644
index 0000000..fc12193
--- /dev/null
+++ b/modules/swarm/tests/signal.cpp
@@ -0,0 +1,82 @@
+#include <forstio/test/suite.hpp>
+
+#include "../c++/signal.hpp"
+#include "../c++/wire.hpp"
+
+namespace {
+namespace sch {
+using namespace kel::lbm::sch;
+}
+using namespace kel::lbm;
+using namespace kel::lbm::swarm;
+
+SAW_TEST("Signal / an offer round trips"){
+ data<sch::SignalDescription> desc;
+ desc.get<"type">().set(std::string{sig::offer});
+ desc.get<"sdp">().set(std::string{"v=0\r\no=- 1 1 IN IP4 127.0.0.1\r\n"});
+
+ auto eo_text = encode_message<sch::SignalDescription>(desc);
+ SAW_EXPECT(not eo_text.is_error(), "An offer must encode");
+
+ auto eo_back = decode_message<sch::SignalDescription>(eo_text.get_value());
+ SAW_EXPECT(not eo_back.is_error(), "An offer must decode");
+ SAW_EXPECT(eo_back.get_value().get<"type">().stl_view() == sig::offer,
+ "type survives");
+ // SDP is multi-line and full of characters JSON has to escape; that it
+ // comes back byte for byte is the only interesting property here.
+ SAW_EXPECT(eo_back.get_value().get<"sdp">().stl_view()
+ == "v=0\r\no=- 1 1 IN IP4 127.0.0.1\r\n",
+ "SDP must survive escaping unchanged");
+}
+
+SAW_TEST("Signal / a candidate round trips"){
+ data<sch::SignalCandidate> cand;
+ cand.get<"type">().set(std::string{sig::candidate});
+ cand.get<"candidate">().set(std::string{"candidate:1 1 UDP 100 10.0.0.1 5000 typ host"});
+ cand.get<"mid">().set(std::string{"0"});
+
+ auto eo_text = encode_message<sch::SignalCandidate>(cand);
+ SAW_EXPECT(not eo_text.is_error(), "A candidate must encode");
+
+ auto eo_back = decode_message<sch::SignalCandidate>(eo_text.get_value());
+ SAW_EXPECT(not eo_back.is_error(), "A candidate must decode");
+ SAW_EXPECT(eo_back.get_value().get<"mid">().stl_view() == "0", "mid survives");
+}
+
+SAW_TEST("Signal / the header routes without knowing the payload"){
+ data<sch::SignalDescription> desc;
+ desc.get<"type">().set(std::string{sig::answer});
+ desc.get<"sdp">().set(std::string{"v=0"});
+ auto eo_text = encode_message<sch::SignalDescription>(desc);
+ SAW_EXPECT(not eo_text.is_error(), "encodes");
+
+ auto eo_hdr = decode_message<sch::SignalHeader>(eo_text.get_value());
+ SAW_EXPECT(not eo_hdr.is_error(), "A header read must skip the sdp");
+ SAW_EXPECT(eo_hdr.get_value().get<"type">().stl_view() == sig::answer,
+ "Header reports answer");
+}
+
+SAW_TEST("Signal / an empty mid is carried rather than dropped"){
+ // libdatachannel accepts an unhinted candidate, so the empty string has to
+ // survive the round trip as an empty string and not become a decode error.
+ data<sch::SignalCandidate> cand;
+ cand.get<"type">().set(std::string{sig::candidate});
+ cand.get<"candidate">().set(std::string{"candidate:1 1 UDP 100 10.0.0.1 5000 typ host"});
+ cand.get<"mid">().set(std::string{""});
+
+ auto eo_text = encode_message<sch::SignalCandidate>(cand);
+ SAW_EXPECT(not eo_text.is_error(), "encodes");
+ auto eo_back = decode_message<sch::SignalCandidate>(eo_text.get_value());
+ SAW_EXPECT(not eo_back.is_error(), "An empty mid must still decode");
+ SAW_EXPECT(eo_back.get_value().get<"mid">().stl_view().empty(),
+ "An empty mid stays empty");
+}
+
+SAW_TEST("Signal / a candidate missing its mid is rejected"){
+ // Strictness applies here too: a signalling message that lost a member in
+ // transit should fail loudly rather than add a candidate with no mid.
+ auto eo = decode_message<sch::SignalCandidate>(
+ R"({"type":"candidate","candidate":"candidate:1 1 UDP 100 10.0.0.1 5000 typ host"})");
+ SAW_EXPECT(eo.is_error(), "A missing mid must be an error");
+}
+}
diff --git a/modules/swarm/tests/wire.cpp b/modules/swarm/tests/wire.cpp
new file mode 100644
index 0000000..5238619
--- /dev/null
+++ b/modules/swarm/tests/wire.cpp
@@ -0,0 +1,381 @@
+#include <forstio/test/suite.hpp>
+
+#include "../c++/wire.hpp"
+
+#include <string>
+
+namespace {
+namespace sch {
+using namespace kel::lbm::sch;
+}
+using namespace kel::lbm;
+using namespace kel::lbm::swarm;
+
+/**
+ * Builds a filled-in live block. Every member is set, because the wire codecs
+ * run strict and a half built message is exactly what these tests are trying
+ * to catch elsewhere.
+ */
+data<sch::WorkerLive> make_live(){
+ data<sch::WorkerLive> live;
+ live.get<"state">().set(std::string{wstate::ready});
+ live.get<"uptime_ms">().set(1234u);
+ live.get<"steps_done">().set(42u);
+ live.get<"last_error">().set(std::string{""});
+ return live;
+}
+
+SAW_TEST("Wire / pong round trips unchanged"){
+ auto msg = make_message<sch::MsgPong>(msg::pong, "worker-7", 19u);
+ msg.get<"sent_at_ms">().set(1000u);
+ msg.get<"worker_now_ms">().set(2000u);
+ msg.get<"live">() = make_live();
+
+ auto eo_text = encode_message<sch::MsgPong>(msg);
+ SAW_EXPECT(not eo_text.is_error(), "Encoding a complete message must succeed");
+ const std::string text = eo_text.get_value();
+
+ auto eo_back = decode_message<sch::MsgPong>(text);
+ SAW_EXPECT(not eo_back.is_error(), "Decoding our own output must succeed");
+ auto& back = eo_back.get_value();
+
+ SAW_EXPECT(back.get<"type">().stl_view() == msg::pong, "type survives");
+ SAW_EXPECT(back.get<"worker_id">().stl_view() == "worker-7", "worker_id survives");
+ SAW_EXPECT(back.get<"seq">().get() == 19u, "seq survives");
+ SAW_EXPECT(back.get<"sent_at_ms">().get() == 1000u, "echoed timestamp survives");
+ SAW_EXPECT(back.get<"worker_now_ms">().get() == 2000u, "worker clock survives");
+ SAW_EXPECT(back.get<"live">().get<"steps_done">().get() == 42u,
+ "Nested struct members survive");
+ SAW_EXPECT(back.get<"live">().get<"state">().stl_view() == wstate::ready,
+ "Nested strings survive");
+}
+
+SAW_TEST("Wire / welcome and ping round trip"){
+ auto wel = make_message<sch::MsgWelcome>(msg::welcome, "worker-1", 0u);
+ wel.get<"heartbeat_ms">().set(2000u);
+ wel.get<"schema_version">().set(std::string{schema_version});
+
+ auto eo_text = encode_message<sch::MsgWelcome>(wel);
+ SAW_EXPECT(not eo_text.is_error(), "welcome encodes");
+ auto eo_back = decode_message<sch::MsgWelcome>(eo_text.get_value());
+ SAW_EXPECT(not eo_back.is_error(), "welcome decodes");
+ SAW_EXPECT(eo_back.get_value().get<"heartbeat_ms">().get() == 2000u,
+ "heartbeat survives");
+
+ auto png = make_message<sch::MsgPing>(msg::ping, "worker-1", 5u);
+ png.get<"sent_at_ms">().set(999u);
+ auto eo_ptext = encode_message<sch::MsgPing>(png);
+ SAW_EXPECT(not eo_ptext.is_error(), "ping encodes");
+ auto eo_pback = decode_message<sch::MsgPing>(eo_ptext.get_value());
+ SAW_EXPECT(not eo_pback.is_error(), "ping decodes");
+ SAW_EXPECT(eo_pback.get_value().get<"sent_at_ms">().get() == 999u,
+ "ping timestamp survives");
+}
+
+/**
+ * The two stage decode is the whole reason this protocol works without a
+ * tagged union: reading the header out of a full message has to succeed for
+ * every message type, skipping whatever payload it does not know about.
+ */
+SAW_TEST("Wire / the header can be read out of any message"){
+ auto png = make_message<sch::MsgPing>(msg::ping, "w-a", 1u);
+ png.get<"sent_at_ms">().set(7u);
+ auto eo_png = encode_message<sch::MsgPing>(png);
+ SAW_EXPECT(not eo_png.is_error(), "ping encodes");
+
+ auto eo_hdr = peek_header(eo_png.get_value());
+ SAW_EXPECT(not eo_hdr.is_error(),
+ "Reading a header out of a ping must skip the payload, not fail");
+ SAW_EXPECT(header_type(eo_hdr.get_value()) == msg::ping, "Header reports ping");
+ SAW_EXPECT(header_worker_id(eo_hdr.get_value()) == "w-a", "Header reports the id");
+
+ auto pong = make_message<sch::MsgPong>(msg::pong, "w-b", 2u);
+ pong.get<"sent_at_ms">().set(1u);
+ pong.get<"worker_now_ms">().set(2u);
+ pong.get<"live">() = make_live();
+ auto eo_pong = encode_message<sch::MsgPong>(pong);
+ SAW_EXPECT(not eo_pong.is_error(), "pong encodes");
+
+ auto eo_hdr2 = peek_header(eo_pong.get_value());
+ SAW_EXPECT(not eo_hdr2.is_error(),
+ "A nested struct payload must also be skippable");
+ SAW_EXPECT(header_type(eo_hdr2.get_value()) == msg::pong, "Header reports pong");
+ SAW_EXPECT(header_worker_id(eo_hdr2.get_value()) == "w-b", "Header reports the id");
+}
+
+/**
+ * The failure this protocol must not have. codec_config<enc::Json>::strict
+ * defaults to false so that config files can omit their defaults; on a wire
+ * that would let a worker send "{}" and have it decode into a silently zeroed
+ * registration.
+ */
+SAW_TEST("Wire / an empty object is rejected, not defaulted"){
+ auto eo = decode_message<sch::MsgPing>("{}");
+ SAW_EXPECT(eo.is_error(),
+ "An empty object must not decode into a default constructed message");
+}
+
+SAW_TEST("Wire / a missing member is rejected at every nesting depth"){
+ // Top level: seq absent.
+ {
+ auto eo = decode_message<sch::MsgPing>(
+ R"({"type":"ping","worker_id":"w","sent_at_ms":1})");
+ SAW_EXPECT(eo.is_error(), "A missing top level member must fail");
+ }
+ // One level down: live is present but incomplete. This is the case that
+ // matters most, since strictness has to reach into nested structs or a
+ // half filled capability would register cleanly.
+ {
+ auto eo = decode_message<sch::MsgPong>(
+ R"({"type":"pong","worker_id":"w","seq":1,"sent_at_ms":1,)"
+ R"("worker_now_ms":2,"live":{"state":"ready"}})");
+ SAW_EXPECT(eo.is_error(), "A missing nested member must fail");
+ }
+ // And the complete form of the same message must still pass, so the test
+ // above is not just rejecting everything.
+ {
+ auto eo = decode_message<sch::MsgPong>(
+ R"({"type":"pong","worker_id":"w","seq":1,"sent_at_ms":1,)"
+ R"("worker_now_ms":2,"live":{"state":"ready","uptime_ms":0,)"
+ R"("steps_done":0,"last_error":""}})");
+ SAW_EXPECT(not eo.is_error(), "The complete message must still decode");
+ }
+}
+
+/**
+ * Forward compatibility in the direction that works: a newer worker sending
+ * members an older orchestrator has never heard of still registers.
+ */
+SAW_TEST("Wire / unknown members are skipped"){
+ auto eo = decode_message<sch::MsgPing>(
+ R"({"type":"ping","worker_id":"w","seq":3,"sent_at_ms":8,)"
+ R"("future_field":{"nested":[1,2,3]},"another":"x"})");
+ SAW_EXPECT(not eo.is_error(),
+ "A newer sender's extra members must be skipped, not rejected");
+ SAW_EXPECT(eo.get_value().get<"seq">().get() == 3u, "Known members still land");
+ SAW_EXPECT(eo.get_value().get<"sent_at_ms">().get() == 8u, "and keep their values");
+}
+
+SAW_TEST("Wire / malformed input errors rather than defaulting"){
+ const char* bad[] = {
+ "",
+ "{",
+ R"({"type":"ping","worker_id":"w","seq":1,"sent_at_ms":1)", // truncated
+ R"({"type":"ping","worker_id":"w","seq":1,"sent_at_ms":1}})", // trailing
+ R"({"type":"ping","worker_id":"w","seq":"not a number","sent_at_ms":1})",
+ "[1,2,3]",
+ "null",
+ };
+
+ for(const char* text : bad){
+ auto eo = decode_message<sch::MsgPing>(text);
+ SAW_EXPECT(eo.is_error(), std::string{"Malformed input must error: "} + text);
+ }
+}
+
+/**
+ * The capability envelope is the largest thing on the wire and the one whose
+ * shape has to survive being read by a process built from different source.
+ */
+SAW_TEST("Wire / hello carries a capability round trip"){
+ auto hello = make_message<sch::MsgHelloWebGl2>(msg::hello, "worker-9", 0u);
+
+ auto& cap = hello.get<"capability">();
+ cap.get<"worker_id">().set(std::string{"worker-9"});
+ cap.get<"kind">().set(std::string{wkind::webgl2});
+ cap.get<"schema_version">().set(std::string{schema_version});
+ cap.get<"reported_at_ms">().set(1700000000000u);
+ cap.get<"user_agent">().set(std::string{"test-agent"});
+
+ auto& gl = cap.get<"webgl2">();
+
+ auto& lim = gl.get<"limits">();
+ lim.get<"max_texture_size">().set(16384u);
+ lim.get<"max_3d_texture_size">().set(2048u);
+ lim.get<"max_array_texture_layers">().set(2048u);
+ lim.get<"max_draw_buffers">().set(8u);
+ lim.get<"max_color_attachments">().set(8u);
+ lim.get<"max_texture_image_units">().set(16u);
+ lim.get<"max_combined_texture_image_units">().set(32u);
+ lim.get<"max_renderbuffer_size">().set(16384u);
+ lim.get<"max_fragment_uniform_vectors">().set(224u);
+ lim.get<"max_viewport_dims">().at({{0u}}).set(16384u);
+ lim.get<"max_viewport_dims">().at({{1u}}).set(16384u);
+
+ auto& feat = gl.get<"features">();
+ feat.get<"webgl2">().set(true);
+ feat.get<"offscreen_canvas">().set(true);
+ feat.get<"color_buffer_float">().set(true);
+ feat.get<"color_buffer_half_float">().set(true);
+ feat.get<"texture_float_linear">().set(false);
+ feat.get<"float_blend">().set(false);
+ feat.get<"parallel_shader_compile">().set(true);
+ feat.get<"disjoint_timer_query">().set(false);
+
+ auto& bud = gl.get<"budget">();
+ bud.get<"probed_bytes_max">().set(536870912u);
+ bud.get<"probed_bytes_safe">().set(322122547u);
+ bud.get<"probe_trials">().set(14u);
+ bud.get<"context_lost_during_probe">().set(false);
+ bud.get<"probe_hit_texture_size_bound">().set(false);
+ bud.get<"safety_factor">().set(0.6f);
+
+ // One feasible plan, enough to prove the array of nested structs survives.
+ {
+ data<sch::PackingPlan> plan;
+ plan.get<"layout">().set(std::string{"plain2d"});
+ plan.get<"aux_mode">().set(std::string{"stuffed"});
+ plan.get<"d">().set(2u);
+ plan.get<"q">().set(9u);
+ plan.get<"ghost">().set(0u);
+ plan.get<"storage_bits">().set(32u);
+ plan.get<"slots_per_texel">().set(4u);
+ plan.get<"textures_df">().set(3u);
+ plan.get<"textures_aux">().set(0u);
+ plan.get<"states">().set(2u);
+ plan.get<"passes">().set(1u);
+ plan.get<"idle_slots">().set(3u);
+ plan.get<"domain">().at({{0u}}).set(1024u);
+ plan.get<"domain">().at({{1u}}).set(256u);
+ plan.get<"domain">().at({{2u}}).set(1u);
+ plan.get<"tiles">().at({{0u}}).set(1u);
+ plan.get<"tiles">().at({{1u}}).set(1u);
+ plan.get<"tiles_pow2">().set(true);
+ plan.get<"texture_size">().at({{0u}}).set(1024u);
+ plan.get<"texture_size">().at({{1u}}).set(256u);
+ plan.get<"bytes_total">().set(1024u * 256u * 96u);
+ plan.get<"bytes_useful">().set(1024u * 256u * 96u);
+
+ for(uint64_t i = 0u; i < 9u; ++i){
+ auto eo = plan.get<"slot_tex_of_q">().add(data<sch::UInt8>{static_cast<uint8_t>(i / 4u)});
+ SAW_EXPECT(not eo.is_error(), "slot_tex_of_q grows");
+ auto eo2 = plan.get<"slot_cmp_of_q">().add(data<sch::UInt8>{static_cast<uint8_t>(i % 4u)});
+ SAW_EXPECT(not eo2.is_error(), "slot_cmp_of_q grows");
+ }
+ auto eo3 = plan.get<"slot_tex_of_aux">().add(data<sch::UInt8>{2u});
+ SAW_EXPECT(not eo3.is_error(), "slot_tex_of_aux grows");
+ auto eo4 = plan.get<"slot_cmp_of_aux">().add(data<sch::UInt8>{1u});
+ SAW_EXPECT(not eo4.is_error(), "slot_cmp_of_aux grows");
+ auto eo5 = plan.get<"aux_names">().add(data<sch::String>{std::string{"info"}});
+ SAW_EXPECT(not eo5.is_error(), "aux_names grows");
+
+ auto eo6 = gl.get<"feasible">().add(std::move(plan));
+ SAW_EXPECT(not eo6.is_error(), "feasible grows");
+ }
+
+ auto eo_text = encode_message<sch::MsgHelloWebGl2>(hello);
+ SAW_EXPECT(not eo_text.is_error(), "A complete capability must encode");
+
+ // The header has to be readable out of the biggest message we have.
+ auto eo_hdr = peek_header(eo_text.get_value());
+ SAW_EXPECT(not eo_hdr.is_error(), "The header must survive a large payload");
+ SAW_EXPECT(header_type(eo_hdr.get_value()) == msg::hello, "Header reports hello");
+
+ // Routing pass: the common fields alone are enough to learn the kind, and
+ // the webgl2 section is skipped because it is not named here.
+ auto eo_route = decode_message<sch::MsgHello>(eo_text.get_value());
+ SAW_EXPECT(not eo_route.is_error(), "The routing decode must succeed");
+ SAW_EXPECT(eo_route.get_value().get<"capability">().get<"kind">().stl_view()
+ == wkind::webgl2, "The routing decode must report the kind");
+
+ auto eo_back = decode_message<sch::MsgHelloWebGl2>(eo_text.get_value());
+ SAW_EXPECT(not eo_back.is_error(), "A complete capability must decode");
+ auto& back = eo_back.get_value().get<"capability">();
+
+ SAW_EXPECT(back.get<"kind">().stl_view() == wkind::webgl2, "kind survives");
+ SAW_EXPECT(back.get<"webgl2">().get<"limits">().get<"max_texture_size">().get()
+ == 16384u, "Deeply nested integers survive");
+ SAW_EXPECT(back.get<"webgl2">().get<"features">().get<"color_buffer_float">().get(),
+ "Booleans survive");
+ SAW_EXPECT(back.get<"webgl2">().get<"budget">().get<"probe_trials">().get() == 14u,
+ "Budget survives");
+
+ auto& feasible = back.get<"webgl2">().get<"feasible">();
+ SAW_EXPECT(feasible.meta().flat_at(0u).get() == 1u, "One plan came back");
+ auto& plan_back = feasible.at({{0u}});
+ SAW_EXPECT(plan_back.get<"q">().get() == 9u, "Plan Q survives");
+ SAW_EXPECT(plan_back.get<"layout">().stl_view() == "plain2d", "Plan layout survives");
+ SAW_EXPECT(plan_back.get<"slot_tex_of_q">().meta().flat_at(0u).get() == 9u,
+ "The slot table keeps its length");
+ SAW_EXPECT(plan_back.get<"slot_tex_of_q">().at({{8u}}).get() == 2u,
+ "Direction 8 lives in texture 2");
+ SAW_EXPECT(plan_back.get<"slot_cmp_of_q">().at({{8u}}).get() == 0u,
+ "Direction 8 lives in channel 0");
+ SAW_EXPECT(plan_back.get<"aux_names">().at({{0u}}).stl_view() == "info",
+ "Arrays of strings survive");
+}
+
+/**
+ * A worker of a kind we do not know about still has to be readable far enough
+ * to find out that we do not know about it. This is the envelope earning its
+ * keep.
+ */
+SAW_TEST("Wire / an unknown worker kind is still routable"){
+ const char* text =
+ R"({"type":"hello","worker_id":"w-x","seq":0,)"
+ R"("capability":{"worker_id":"w-x","kind":"webgpu","schema_version":"1",)"
+ R"("reported_at_ms":1,"user_agent":"a","webgpu":{"whatever":true}}})";
+
+ auto eo_hdr = peek_header(text);
+ SAW_EXPECT(not eo_hdr.is_error(),
+ "An unknown backend section must not stop the header decoding");
+ SAW_EXPECT(header_type(eo_hdr.get_value()) == msg::hello, "Still a hello");
+ SAW_EXPECT(header_worker_id(eo_hdr.get_value()) == "w-x", "Still identifiable");
+
+ // The routing decode succeeds and names the kind, which is exactly what it
+ // is for: an unusable worker is still an identifiable worker.
+ auto eo_route = decode_message<sch::MsgHello>(text);
+ SAW_EXPECT(not eo_route.is_error(),
+ "The common fields of an unknown kind must still decode");
+ SAW_EXPECT(eo_route.get_value().get<"capability">().get<"kind">().stl_view()
+ == "webgpu", "The orchestrator learns which kind it cannot use");
+
+ // Decoding it as a webgl2 hello must fail, because "webgl2" is absent --
+ // that is the orchestrator learning it cannot use this worker, which is a
+ // different and better outcome than a zeroed capability.
+ auto eo_full = decode_message<sch::MsgHelloWebGl2>(text);
+ SAW_EXPECT(eo_full.is_error(),
+ "A webgl2 decode of a webgpu worker must fail rather than zero fill");
+}
+/**
+ * Native workers are a worker kind, not a test fixture, so the same routing has
+ * to work for them -- and crucially a native hello must not be obliged to carry
+ * a texture budget it has no way to measure.
+ */
+SAW_TEST("Wire / a native worker registers without a webgl section"){
+ auto hello = make_message<sch::MsgHelloNative>(msg::hello, "n-1", 0u);
+
+ auto& cap = hello.get<"capability">();
+ cap.get<"worker_id">().set(std::string{"n-1"});
+ cap.get<"kind">().set(std::string{wkind::native});
+ cap.get<"schema_version">().set(std::string{schema_version});
+ cap.get<"reported_at_ms">().set(1700000000000u);
+ cap.get<"user_agent">().set(std::string{"kel-lbm-worker-native"});
+
+ auto& nat = cap.get<"native">();
+ nat.get<"threads">().set(16u);
+ nat.get<"memory_bytes">().set(34359738368u);
+ nat.get<"cpu">().set(std::string{"x86_64"});
+ nat.get<"has_sycl">().set(false);
+
+ auto eo_text = encode_message<sch::MsgHelloNative>(hello);
+ SAW_EXPECT(not eo_text.is_error(), "A native hello must encode");
+
+ // Routes the same way a browser does.
+ auto eo_route = decode_message<sch::MsgHello>(eo_text.get_value());
+ SAW_EXPECT(not eo_route.is_error(), "A native hello must route");
+ SAW_EXPECT(eo_route.get_value().get<"capability">().get<"kind">().stl_view()
+ == wkind::native, "Routing reports native");
+
+ auto eo_back = decode_message<sch::MsgHelloNative>(eo_text.get_value());
+ SAW_EXPECT(not eo_back.is_error(), "A native hello must decode");
+ SAW_EXPECT(eo_back.get_value().get<"capability">().get<"native">()
+ .get<"threads">().get() == 16u, "Thread count survives");
+
+ // And the point of the restructure: this text has no webgl2 section at all,
+ // so a decode that demands one has to fail rather than zero fill.
+ auto eo_wrong = decode_message<sch::MsgHelloWebGl2>(eo_text.get_value());
+ SAW_EXPECT(eo_wrong.is_error(),
+ "A native worker must not decode as a webgl2 one");
+}
+}