Adaptive policy

Optimise for the mission.

The eight strategies rank links by what the probes measure: round trip, jitter, loss, capacity, queue delay. A mission often cares about something else — a cellular bearer billed per megabyte, a transmitter’s emission signature, a relay’s flight time, a signal that is fading while its latency still looks fine, a noise floor on the rise. Operators say what matters in two layers: declarative rules in the node’s signed configuration and, for what rules cannot say, a small sandboxed script. Both read what Atlas measures, what other programs on the vehicle know and where the vehicle is, and both are evaluated twice a second, never per packet.

Opt-in · [policy]At the tick, never per packet
Layer 1 · Rules

Declarative rules in the node’s configuration

Each [[policy.rule]] pairs a condition over the link table’s variables (when = 'link.bearer == "cellular"') with one or more actions: exclude, silent, weight, prefer, standby, deny_classes, only_classes, and hold timers so a noisy reading does not flap. Rules are described by the schema, compiled and type-checked by atlasd config check, pushed and signed with the fleet configuration like [scheduler], applied hot, and listed on the dashboard, where every effect on a link names the rule that caused it. the grammar ↗

Layer 2 · Script

A sandboxed script for what rules cannot say

A rule reads one row at a time. Ranking, arithmetic across links and “the two best by SNR” need the whole table, so [policy] script holds a small function, fn decide(rows, node, policy), written in Rhai — inline, or in a file of its own named by script_file. It receives the same link table and returns per-link verdicts, bounded in operations and wall time, and it can be replayed against recorded telemetry before it is pushed. the script ↗

Other programs

What the vehicle knows, not only what Atlas measures

Other programs on the vehicle can feed the policy: the mission computer’s phase, a payload’s listening window, a battery level, a jamming detector’s verdict. Each external variable is declared with a type and a maximum age; a value older than that reads as unknown, so a dead sensor never fires a rule, and an operator’s one-shot order can be declared to hold until replaced. A program sends its values over the telemetry socket atlasd already runs; a shell script or a cron job uses atlasd policy var set. external variables ↗

Places

Areas on the map, and silence inside them

A [[policy.zone]] is a circle or a polygon; a rule asks inside_zone('sigint-belt') against the node’s own position fix, and the silent action keeps Atlas from sending anything on a link — traffic, probes, replies — while another link carries. by place ↗

What it shapes

The candidate set and the ranking, not the strategy

Rules do not switch the strategy itself. The strategies keep their own dwell and hysteresis, and flipping between them on a variable would fight those state machines. Policy decides which links each strategy may use, in which tier and at what weight, and which traffic classes stay off a link; the configured strategy then decides per packet among what is left. the strategies ↗

Where it lives

On the node, as configuration

No controller computes verdicts and no service is asked. Link selection is exactly what must keep working when the network is degraded, so the policy is configuration: the signed fleet push delivers it to every node, and a node cut off from everyone keeps its policy and keeps applying it.

At the tick

Policy shapes the inputs. The packet path never runs it.

Every variable Atlas measures changes at probe cadence, 250 ms, or slower, and another program’s value as often as it sends one. Evaluating them per packet would recompute the same answer thousands of times and put an interpreter on the hot path. So the policy is evaluated once per tick on its own thread, and the data path reads the last result.

WHAT THE TABLE READS · ATLAS’S OWN MEASUREMENTS AND OTHER PROGRAMS ON THE VEHICLE Atlas measuresprobes · adapters · peers · quota Other programsext.producer.name · socket or CLI Position fixthe declared zones · node.zones a fed value older than its max_age_ms reads as absent: a silent source never fires a rule AT THE POLICY TICK · EVERY 500 MS BY DEFAULT · ITS OWN THREAD Link tableone row per peer × link Rulescompiled · for / hold timers Scriptoptional · bounded Verdict tableexclude · silent · tier · weight · classes built by the stats loop from the link monitor, LSDB, peers, quota and the store of fed values each effect names its rule a failure costs one tick an explanation per row read, never run: the last published table, one lock read PER PACKET · THE DATA PATH · NO RULE, NO SCRIPT Packetfrom the tunnel Link scoresstamped with the verdict Guard stepsexclude · class · tier · rank Strategyany of the eight Linkits own socket a table older than max(4 × tick, 3 s) is ignored: the strategy decides alone the guards keep one carrying link for the node and for each class while one is alive
THE SOURCESwhat Atlas measures, the values other programs feed over the telemetry socket, and the position fix with the declared zones; a fed value older than its maximum age reads as absent
AT THE TICKlink table → rules → script → a published verdict table, on the policy’s own thread, every 500 ms by default
PER PACKETthe data path reads the last table and applies fixed guard steps; it never evaluates a rule or calls a script
IF THE TICK STOPSa table older than max(4 × tick, 3 s) is ignored and the strategy decides alone
The input

One table, built where the facts already are

Every tick_ms (500 by default, 100 to 60 000) the engine’s stats loop — the one place that holds the link monitor, the routing database, the peer table, the quota meter and the live configuration — builds the link table and hands it to the policy thread through a one-slot channel. A row is one peer and one link, because link measurements are per peer, as the scheduler sees them. If the thread is still busy, the tick is skipped and counted.

Fed values

Another program’s value, fresh or absent

Values other programs send land in a store beside the engine, not in the policy. Each variable has one freshness window, its max_age_ms, 10 s unless declared: at each tick the store hands over the last value while it is younger than that, and absent once it is older. The producer may send faster or slower; only the window matters. A source that falls silent therefore reads as unknown and fires nothing; the journal records policy.var_stale once when its value lapses and policy.var_fresh once when it is back. An operator’s one-shot order is declared with hold = true instead, or sent once with --hold: that value holds until it is replaced and never goes stale. A window far longer than the tick is never a fault. When one spans a hundred ticks or more, atlasd policy check and the dashboard’s findings add a line of advice, not a warning, that a slower tick would do less work if no other rule needs the fast one; config check does not report it.

The evaluator

A thread of its own, with no I/O and no clock

The evaluator compiles the rules and the script when the configuration changes, evaluates them over the rows, applies the onset and hold timers, combines the verdicts and publishes a verdict table with an explanation per row. It does no I/O and has no clock of its own: the tick time is an input. A panic inside it is caught, the table resets to neutral and the event is journaled.

The data path

Three fixed guard steps, then the rank

When the scheduler asks for a peer’s link scores, each score is stamped with its link’s last verdict — one read of a shared table already taken for the scores. Then, over the alive candidates: exclude drops excluded links, unless that would leave none; class drops links that deny the packet’s class, unless that would leave none; tier keeps the best tier present, preferred, else normal, else standby; rank divides each link’s cost by its weight for the strategies that rank by cost, and multiplies the configured weights for weighted round-robin. Pure functions over a few dozen links, in nanoseconds.

Safety anchors

Four things no policy can change.

A policy is operator code running beside the data path of a link that may be the only one a vehicle has. These four properties hold for every rule set and every script, and the evaluator is built around them.

Anchor 1 · Deterministic

The data path stays deterministic and script-free.

Policy shapes the scheduler’s inputs at a tick, never per packet. The per-packet path reads the last published verdict table and applies three fixed guard steps; it never evaluates a rule or calls a script, and nothing on the send path holds a handle to the evaluator. Ten thousand scheduling decisions in a row leave the evaluation count where it was.

Anchor 2 · Trusted as config

A script is as trusted as the rest of the configuration.

It is text in [policy], so it travels inside the same signed fleet push, appears in the same configuration diff and is refused by the same config check that refuses a broken [scheduler]. A policy that does not compile is refused before it applies — by the apply watcher before the live file is touched, and by the signer and every receiving node before a push is signed or adopted. The script may also come from script_file, a file next to the configuration read only locally; signing embeds its text and SHA-256, so a push still carries the script itself and a node never reads a file a push names. The script has no include and no network or disk access.

Anchor 3 · Degrades, never stops

A broken or slow policy degrades to the built-in strategy, never to no traffic.

A failing or slow script costs at most one tick and falls back to its last good answer, then to no script effect: the rules and the built-in strategy. Five failures in a row quarantine it for a minute. If the evaluator stalls, the data path ignores a table older than max(4 × tick, 3 s) and the strategy decides alone. the ladder ↗

Anchor 4 · Never mute

No policy can leave a node or a traffic class without a carrying link.

Whenever a link is alive, at least one carries — for the whole node and for each class. Exclude every link and the guard keeps them all; deny a class everywhere and the class keeps its links. The dashboard marks such a link “restored by the last-link guarantee”. Silence obeys the same floor: a link held silent is released the moment no other link is alive. Property tests assert it over random link tables, rule sets and script outcomes, and that a failing script never changes the rules-only verdict.

The guarantee, measured. In the namespace harness a rule excluding one of two links moved a 60 × 1 kB burst onto the other within a tick — 68 kB more on the carrying link, 3.7 kB of probes on the excluded one — and atlasd policy explain named the rule. With the carrying link taken down, the excluded link carried again, shown as restored by the last-link guarantee. Measured
Missions

What a mission optimises for, in a few lines.

Each story below is one of the commented policy examples, with its rules exactly as written. Every example is compiled and replayed by the test suite, so the text here never drifts from what the daemon accepts. Copy one into a node’s configuration, adjust the link names and thresholds, then check and replay it before pushing.

Cost

A metered cellular bearer carries only when the free links cannot

A ground vehicle bonds a mesh radio, a depot Wi-Fi uplink and an LTE modem billed per megabyte. LTE stands by: it carries the moment the free links are down, and nothing while either is alive. Once the month’s budget is spent it carries only if it is the last link left.

Reads link.bearer, link.metered, link.over_budget

01-metered-cellular-last.toml
[policy]
enabled = true

[[policy.rule]]
name = "metered-standby"
when = 'link.bearer == "cellular" or link.metered'
standby = true
note = "Billed per MB: only when no free link is alive."

[[policy.rule]]
name = "budget-spent"
when = "link.over_budget"
exclude = true
note = "Quota spent: last resort only (the last-link guarantee keeps it if nothing else lives)."

A metered link sheds heavy classes as its quota burns down

A border post’s satellite modem has a 50 GB month. Past 70 % Video stops using it, past 85 % Bulk too, past 95 % it stands by for everything; command and control and telemetry keep it to the end.

Reads link.metered, link.quota_used_pct

11-quota-burn.toml
[policy]
enabled = true

[[policy.rule]]
name = "quota-70-no-video"
when = "link.metered and link.quota_used_pct > 70"
deny_classes = ["Video"]

[[policy.rule]]
name = "quota-85-no-bulk"
when = "link.metered and link.quota_used_pct > 85"
deny_classes = ["Video", "Bulk"]

[[policy.rule]]
name = "quota-95-standby"
when = "link.metered and link.quota_used_pct > 95"
standby = true

A per-megabyte satellite link with 600 ms of round trip carries Bulk only

An outpost has a microwave hop and a GEO terminal billed per megabyte. The round trip ruins voice and makes command and control sluggish; the bill makes video unaffordable. The satellite carries Bulk — store-and-forward reports, logs — and stands by for everything else, so if the microwave hop fails every class uses it rather than nothing.

Reads link.bearer, link.rtt_ms

06-satellite-bulk-only.toml
[policy]
enabled = true

[[policy.rule]]
name = "satellite-bulk-only"
when = 'link.bearer == "satellite" or link.rtt_ms > 450'
only_classes = ["Bulk"]
note = "Per-MB and 600 ms: Bulk and store-and-forward only."

[[policy.rule]]
name = "satellite-standby"
when = 'link.bearer == "satellite"'
standby = true

A shared civilian backhaul is used lightly in office hours

A field hospital borrows the town’s fibre. During weekday office hours its traffic is weighted down on the fibre and carries no Bulk, and the hospital’s own satellite and radio links take the rest; outside those hours it may use the fibre freely. Times are UTC.

Reads node.weekday, node.utc_hour, link.tags

08-shared-backhaul-hours.toml
[policy]
enabled = true

[[policy.link]]
name = "town-fibre"
tags = ["shared-backhaul"]

[[policy.rule]]
name = "backhaul-office-hours"
when = '''"shared-backhaul" in link.tags
         and node.weekday <= 5
         and node.utc_hour >= 6 and node.utc_hour < 18'''
weight = 0.2
deny_classes = ["Bulk"]
Emission and energy

EMCON: traffic stays on wired or directional links

A command post has a fibre run, a directional point-to-point radio and an omnidirectional mesh radio, and an omnidirectional transmitter is a beacon for direction finding. When the commander orders emission control, the operator pushes mode = "emcon"; at the next tick every omnidirectional emitter stops carrying while a wired or directional link lives, and pushing mode = "normal" undoes it. An excluded radio still sends its probes; silent = true in place of exclude = true stops those too while another link is alive, and what the radio emits by itself stays outside Atlas.

Reads policy.mode, link.bearer, link.tags

02-emcon.toml
[policy]
enabled = true
mode = "emcon"          # "normal" outside EMCON

[[policy.link]]
name = "p2p-5ghz"
tags = ["directional"]

[[policy.link]]
name = "fibre0"
tags = ["wired"]

[[policy.rule]]
name = "emcon-quiet-omni"
when = '''policy.mode == "emcon"
         and link.bearer in ["wifi", "cellular", "radio", "bluetooth", "mesh", "satellite"]
         and "directional" not in link.tags'''
exclude = true
note = "Omnidirectional emitters are silent in EMCON."

A battery-powered relay is used last and sheds Bulk first

A relay drone bridges two valleys, and every forwarded packet costs flight time. The ground stations use it last and never for Bulk — log uploads and file transfers avoid it entirely while any other path is alive. The rule keys on the role the relay declares, node_role = "relay".

Reads peer.role

03-battery-relay.toml
[policy]
enabled = true

[[policy.rule]]
name = "relay-last"
when = 'peer.role == "relay"'
standby = true
deny_classes = ["Bulk"]
note = "Battery relay: last resort, and never for Bulk."
Signal and spectrum

A link whose RSSI is falling is weighted down before it drops

A UGV drives away on Wi-Fi with an L-band radio as the long leg. The Wi-Fi round trip looks perfect until the link collapses, because radio retries hide the decline; the RSSI trend shows it seconds earlier. A fading link below −75 dBm is weighted down so traffic moves to the radio while Wi-Fi still carries, with a 5 s hold against noisy readings.

Reads link.rssi_slope_db_per_s, link.rssi_dbm

04-rssi-falling.toml
[policy]
enabled = true

[[policy.rule]]
name = "rssi-falling"
when = "link.rssi_slope_db_per_s < -1.0 and link.rssi_dbm < -75"
weight = 0.3
for_ms = 1000
hold_ms = 5000

[[policy.rule]]
name = "rssi-weak"
when = "link.rssi_dbm < -85"
weight = 0.1
hold_ms = 5000

Jamming onset: Control leaves first, the rest in steps

A barrage jammer ramps up on a UAS’s RFD900 pair and the noise floor rises from −110 dBm. Control moves to the other links at the first rise, Voice at the next step, Position and Telemetry at the third; only a link drowned in noise is excluded. Each step holds 10 s, so the classes return in reverse order without flapping — and a class denied everywhere keeps the radio: Control is moved, never cut.

Reads link.noise_dbm, link.snr_db

05-jamming-onset.toml
[policy]
enabled = true

[[policy.rule]]
name = "noise-1-control"
when = "link.noise_dbm > -100"
deny_classes = ["Control"]
for_ms = 1000
hold_ms = 10000

[[policy.rule]]
name = "noise-2-voice"
when = "link.noise_dbm > -95"
deny_classes = ["Control", "Voice"]
for_ms = 1000
hold_ms = 10000

[[policy.rule]]
name = "noise-3-telemetry"
when = "link.noise_dbm > -90"
deny_classes = ["Control", "Voice", "Position", "Telemetry"]
for_ms = 1000
hold_ms = 10000

[[policy.rule]]
name = "noise-4-drowned"
when = "link.snr_db < 3"
exclude = true
for_ms = 2000
hold_ms = 15000

Predicted risk keeps command and control off a link

A UAV flies a survey line behind a hill. The terrain model and the range envelope already raise the scheduler’s loss figure for the link about to be shadowed; the operator wants more for C2. As soon as the predicted risk passes 30 %, Control and Position leave that link, even while it is still the fastest for video.

Reads link.risk_pct

13-prediction-risk.toml
[policy]
enabled = true

[[policy.rule]]
name = "predicted-shadow-no-c2"
when = "link.risk_pct > 30"
deny_classes = ["Control", "Position"]
hold_ms = 3000

A serial radio with a filling buffer keeps C2 and sheds video

An RFD900 at 64 kbit/s of air rate shares its airtime between MAVLink and a thumbnail video. When the radio reports its transmit buffer more than 75 % full, the next video frame would sit ahead of the next command for seconds, so Video and Bulk leave the radio until the buffer recovers.

Reads link.type, link.buffer_fill_pct

14-radio-buffer.toml
[policy]
enabled = true

[[policy.rule]]
name = "radio-buffer-full"
when = 'link.type == "serial" and link.buffer_fill_pct > 75'
deny_classes = ["Video", "Bulk"]
for_ms = 500
hold_ms = 3000

A link that just came back is on probation

A Wi-Fi link at the edge of range comes up, carries for ten seconds, dies, comes back. Each time it comes up the default strategy moves traffic onto it, and each time it dies that traffic is lost until the probes notice. A link alive for less than 30 s is weighted down, so it has to prove itself before it becomes the primary again.

Reads link.alive, link.state_age_s

12-probation.toml
[policy]
enabled = true

[[policy.rule]]
name = "probation"
when = "link.alive and link.state_age_s < 30"
weight = 0.25

The intent behind the last-link guarantee, written down

An operator excludes every link losing more than half its packets. During a heavy jamming episode every link crosses that line at once. The engine ignores the exclusions and all of them carry, shown on the dashboard as restored by the last-link guarantee; the note states the intent so a reader does not have to know the guarantee.

Reads link.loss_pct

10-last-resort.toml
[policy]
enabled = true

[[policy.rule]]
name = "drop-lossy"
when = "link.loss_pct > 50"
exclude = true
for_ms = 2000
hold_ms = 5000
note = "Never the last alive link: the engine keeps one carrying regardless."
Motion and place

A fast-moving vehicle relay loses Voice until speed settles

A convoy’s lead vehicle carries a mesh node. Above 15 m/s its mesh links hand over between neighbours every few seconds, each hand-over a burst of loss and reordering that voice hears and file transfers do not. Voice avoids the mesh while the vehicle or its peer moves fast, and returns 20 s after the speed drops, so a stop at a junction does not bounce it back and forth.

Reads node.speed_mps, peer.speed_mps, link.bearer

07-fast-vehicle-voice.toml
[policy]
enabled = true

[[policy.rule]]
name = "moving-fast-no-voice"
when = 'link.bearer == "mesh" and (node.speed_mps > 15 or peer.speed_mps > 15)'
deny_classes = ["Voice"]
for_ms = 2000
hold_ms = 20000

Convoy: prefer the vehicles within 400 m

Six vehicles stretch over several kilometres, each reaching some others over short-range radios and all of them over a long-range one. Short hops to vehicles within 400 m are preferred and leave the long-range channel to those who need it; links to peers more than 3 km away are weighted down because they are about to break.

Reads peer.distance_m

09-convoy.toml
[policy]
enabled = true

[[policy.rule]]
name = "convoy-near"
when = "peer.distance_m < 400"
prefer = true

[[policy.rule]]
name = "convoy-far"
when = "peer.distance_m > 3000"
weight = 0.5
By place · zones and silence

Inside watched airspace, only the slow modem talks

Rules can name areas on the map. Inside a declared zone — a circle or a polygon — a vehicle can drop to a single, simpler link and hold the others silent: Atlas sends nothing on a silenced link, not even its probes, for as long as another link carries.

A UAV carries a 5 GHz mesh radio, an LTE modem and a 57.6 kbit/s serial telemetry modem of the kind small drones carry. Two areas on its route are airspace watched by signals intelligence: a ridge with reported direction-finding coverage, drawn as a polygon, and a suspected intercept site with a 4 km radius. Inside either, the mesh radio and the LTE modem go silent and the modem carries command, position and telemetry, the traffic profile of a small drone with only a telemetry link. An aircraft that has lost its position fix stays quiet too: without the last clause a lost fix would leave the zone test unknown and the rule would not fire. The 30 s hold keeps a track along a boundary from flapping, and if the modem dies the silenced links are released and probe again. What the radios emit by themselves — the Wi-Fi interface’s beacons, the LTE modem’s registration with its cell — stays outside Atlas.

Reads inside_zone(), node.lat_deg, link.tags

17-zone-emcon.toml
[policy]
enabled = true

[[policy.link]]
name = "modem"
tags = ["cover"]

[[policy.zone]]
name = "sigint-belt"
note = "Reported direction-finding coverage along the ridge"
polygon = [
  { lat = 42.7310, lon = 23.2520 },
  { lat = 42.7550, lon = 23.3010 },
  { lat = 42.7400, lon = 23.3620 },
  { lat = 42.7080, lon = 23.3390 },
  { lat = 42.7120, lon = 23.2760 },
]

[[policy.zone]]
name = "listening-post"
note = "Suspected intercept site, 4 km radius"
circle = { lat = 42.6650, lon = 23.4100, radius_m = 4000 }

[[policy.rule]]
name = "zone-emcon"
when = '''"cover" not in link.tags
          and (inside_zone("sigint-belt") or inside_zone("listening-post") or not present(node.lat_deg))'''
silent = true
hold_ms = 30000
note = "Inside watched airspace only the cover modem talks; Atlas sends nothing on the others."

[[policy.rule]]
name = "zone-cover-profile"
when = '''"cover" in link.tags
          and (inside_zone("sigint-belt") or inside_zone("listening-post") or not present(node.lat_deg))'''
only_classes = ["Control", "Position", "Telemetry"]
hold_ms = 30000
note = "The cover modem carries what a small telemetry-only drone would."
Other programs on the vehicle · external variables

The mission computer’s phase decides which link carries what

A UAS’s mission computer knows what the aircraft is doing — in transit, on ingress, on station over the target, on egress — and atlasd does not. The mission computer declares the phase and sends it once a second over the telemetry socket. On station the high-rate C-band datalink is preferred for the sensor feed; on ingress and egress the omnidirectional emitters drop Video and Bulk; in transit the metered satellite modem stands by. Because the configuration declares the variable, a misspelt phase is refused at config check. Each phase counts for 3 s: if the mission computer falls silent for longer, the phase reads as unknown, no rule on it fires, and the dashboard shows it stale.

Reads ext.payload.mission_phase, link.tags, link.metered

18-mission-phase.toml
[policy]
enabled = true

[[policy.var]]
producer = "payload"
name = "mission_phase"
type = "enum"
values = ["transit", "ingress", "on_station", "egress"]
max_age_ms = 3000
description = "Mission phase from the mission computer"

[[policy.link]]
name = "cband"
tags = ["datalink"]

[[policy.link]]
name = "mesh"
tags = ["emitter"]

[[policy.rule]]
name = "on-station-datalink"
when = "ext.payload.mission_phase == 'on_station' and 'datalink' in link.tags"
prefer = true
note = "On station the sensor feed rides the high-rate datalink."

[[policy.rule]]
name = "ingress-low-profile"
when = "ext.payload.mission_phase in ['ingress', 'egress'] and 'emitter' in link.tags"
deny_classes = ["Video", "Bulk"]
note = "On ingress and egress the omni emitters carry only what flight needs."

[[policy.rule]]
name = "transit-metered-standby"
when = "ext.payload.mission_phase == 'transit' and link.metered"
standby = true
note = "In transit the per-MB satellite modem waits."

A listening payload keeps our 2.4 GHz transmitters quiet

A ground vehicle carries a passive spectrum monitor, and our own 2.4 GHz transmitters desensitise it. For each listening window the payload sets a flag, every 500 ms; while it is true the 2.4 GHz links go silent and traffic moves to the 5 GHz radio and the wired tether, and when the window closes they come back on their next probe answer. Each value counts for 1.5 s, so if the payload stops sending, the flag goes stale and the links are not held silent: a dead payload never mutes the vehicle.

Reads ext.payload.rf_quiet, link.tags

19-rf-posture.toml
[policy]
enabled = true

[[policy.var]]
producer = "payload"
name = "rf_quiet"
type = "bool"
max_age_ms = 1500
description = "The passive receiver is listening: keep 2.4 GHz quiet"

[[policy.link]]
name = "wifi24"
tags = ["band-2g4"]

[[policy.link]]
name = "mesh24"
tags = ["band-2g4"]

[[policy.rule]]
name = "payload-listening"
when = "ext.payload.rf_quiet and 'band-2g4' in link.tags"
silent = true
note = "Our 2.4 GHz transmitters stay off while the receiver listens."

A battery level fed by a cron job sheds the satellite terminal

A solar-powered relay mast runs on a battery, and atlasd reads no battery level of its own. A cron job does, once a minute, and hands it over with atlasd policy var set. Below 30 % the power-hungry satellite terminal stops carrying Video and Bulk; below 15 % it stands by and transmits only when nothing else is alive. A reading counts for five minutes, so a missed cron run or two does not drop it. The value changes about once a minute, so this policy ticks every 30 s; at the default 500 ms tick atlasd policy check would add the advice that each value is evaluated about 600 times before it can go stale, which is wasted work rather than a fault.

Reads ext.power.battery_pct, link.tags

20-battery-cron.toml
[policy]
enabled = true
tick_ms = 30000

[[policy.var]]
producer = "power"
name = "battery_pct"
type = "float"
unit = "%"
max_age_ms = 300000
description = "Mast battery state of charge (cron, from the charge controller)"

[[policy.link]]
name = "satcom"
tags = ["high-power"]

[[policy.rule]]
name = "battery-low-shed"
when = "ext.power.battery_pct < 30 and 'high-power' in link.tags"
deny_classes = ["Video", "Bulk"]
hold_ms = 600000
note = "Below 30 % the satellite terminal carries no Video or Bulk."

[[policy.rule]]
name = "battery-critical-standby"
when = "ext.power.battery_pct < 15 and 'high-power' in link.tags"
standby = true
hold_ms = 600000
note = "Below 15 % the satellite terminal transmits only as the last link."

A jamming detector moves command and control off the jammed band

The jamming-onset example infers a jammer from the radio’s own noise floor. This vehicle has a dedicated detector, a spectrum sensor with its own classifier, that reports every 500 ms whether a jammer is present and in which band. When it reports one, Control and Position leave the links in that band at once and the satellite link is preferred for them; the move holds 10 s after the detector clears. Each report counts for 1.5 s, so a detector that goes silent reads as unknown and a dead sensor never holds the vehicle in the jammed posture.

Reads ext.sensor.jammer_detected, ext.sensor.jammer_band, link.tags

21-jammer-detected.toml
[policy]
enabled = true

[[policy.var]]
producer = "sensor"
name = "jammer_detected"
type = "bool"
max_age_ms = 1500
description = "Jamming detector: a jammer is present"

[[policy.var]]
producer = "sensor"
name = "jammer_band"
type = "enum"
values = ["l", "s", "c", "unknown"]
max_age_ms = 1500
description = "Jamming detector: the band it sees the jammer in"

[[policy.link]]
name = "radio-l"
tags = ["band-l"]

[[policy.link]]
name = "radio-c"
tags = ["band-c"]

[[policy.link]]
name = "satcom"
tags = ["satellite"]

[[policy.rule]]
name = "jammed-l"
when = "ext.sensor.jammer_detected and ext.sensor.jammer_band in ['l', 'unknown'] and 'band-l' in link.tags"
deny_classes = ["Control", "Position"]
hold_ms = 10000

[[policy.rule]]
name = "jammed-c"
when = "ext.sensor.jammer_detected and ext.sensor.jammer_band in ['c', 'unknown'] and 'band-c' in link.tags"
deny_classes = ["Control", "Position"]
hold_ms = 10000

[[policy.rule]]
name = "jammed-satcom-first"
when = "ext.sensor.jammer_detected and 'satellite' in link.tags"
prefer = true
hold_ms = 10000

An operator’s one-shot order holds until it is replaced

The commander of a ground vehicle orders it quiet on its omnidirectional emitters for the next leg. Nobody keeps sending an order: the operator gives it once, from the vehicle’s console or over SSH, with atlasd policy var set --producer operator posture=silent, and later sets posture=normal. The declaration says hold = true, so the value holds until it is replaced and never goes stale; the dashboard shows it Fresh, holding until replaced. While the posture is silent, Atlas sends nothing on the mesh radio and the LTE modem, not even probes, and the directional datalink carries; silence holds only while another link is alive. Until the operator sets it, the posture is never fed and nothing is silenced. A value that should lapse keeps a max_age_ms instead, and a single value can be sent with --hold to hold once on a variable that has a window.

Reads ext.operator.posture, link.tags

23-operator-posture.toml
[policy]
enabled = true

[[policy.var]]
producer = "operator"
name = "posture"
type = "enum"
values = ["normal", "silent"]
hold = true
description = "Emission posture ordered by the operator"

[[policy.link]]
name = "mesh"
tags = ["omni"]

[[policy.link]]
name = "lte"
tags = ["omni"]

[[policy.link]]
name = "datalink"
tags = ["directional"]

[[policy.rule]]
name = "operator-silent"
when = "ext.operator.posture == 'silent' and 'omni' in link.tags"
silent = true
note = "Ordered quiet: the omnidirectional emitters send nothing until the posture is set back to normal."
Scripts · what a rule cannot see

The two radios with the best SNR carry, the rest stand by

A ground station has four sector radios towards a swarm. Running all four doubles the spectrum footprint for little gain: the two with the best signal-to-noise ratio carry, the other two stand by and take over when one of the two degrades or dies. Ranking across links is what a rule cannot do, so the script sorts the radios by SNR at every tick; a 3 dB margin keeps the choice from swapping between two radios with nearly equal SNR.

Reads link.snr_db, link.bearer, link.alive

16-script-best-two-by-snr.toml
[policy]
enabled = true
script = '''
fn decide(rows, node, policy) {
    let out = #{};
    let radios = [];
    for r in rows {
        if r.link.bearer == "radio" && r.link.alive && r.link.snr_db != () { radios.push(r); }
    }
    radios.sort(|a, b| if a.link.snr_db > b.link.snr_db { -1 } else if a.link.snr_db < b.link.snr_db { 1 } else { 0 });
    if radios.len() <= 2 { return out; }
    let cut = radios[1].link.snr_db - 3.0;
    for i in 2..radios.len() {
        let r = radios[i];
        if r.link.snr_db < cut {
            out[r.key] = #{ standby: true, reason: `SNR ${r.link.snr_db} dB: not in the best two` };
        }
    }
    out
}
'''

The metered link helps only when the free links are saturated

The first example keeps LTE on standby until the free links are down. This operator wants more: LTE should also help when the free links are alive but full, and only then. The script finds the least-loaded free link towards each peer; when even that one is above 85 % of its capacity, LTE joins with a low weight, and otherwise it stays on standby. The reason it gives is shown on the dashboard.

Reads link.metered, link.util_pct, link.alive

15-script-metered-overflow.toml
[policy]
enabled = true
script_max_operations = 50000
script_time_ms = 10
script = '''
fn decide(rows, node, policy) {
    let out = #{};
    // Least utilisation among free (unmetered) alive links, per peer.
    let least = #{};
    for r in rows {
        if r.link.metered || !r.link.alive || r.link.util_pct == () { continue; }
        let p = `${r.peer.id}`;
        if !least.contains(p) || r.link.util_pct < least[p] { least[p] = r.link.util_pct; }
    }
    for r in rows {
        if !r.link.metered { continue; }
        let p = `${r.peer.id}`;
        if least.contains(p) && least[p] > 85.0 {
            out[r.key] = #{ weight: 0.3, reason: `free links saturated (${least[p]} %)` };
        } else {
            out[r.key] = #{ standby: true, reason: "free links have headroom" };
        }
    }
    out
}
'''

The script in its own file, reading the mission phase and the zones

The mission-phase operator wants more than rules: on station, the link with the best SNR carries the sensor feed and every other emitter drops Video, and inside the watched zone the script leaves the decision to the rules. The script grew past a screenful, so it lives in its own file next to the configuration, with an editor’s colouring and a diff of its own. config check and atlasd policy check read the file; signing embeds its text and SHA-256, so the signed configuration carries the script itself.

Reads node.ext.payload.mission_phase, node.zones, link.snr_db, link.alive

22-script-file.toml
[policy]
enabled = true
script_file = "22-mission-phase.rhai"

[[policy.var]]
producer = "payload"
name = "mission_phase"
type = "enum"
values = ["transit", "ingress", "on_station", "egress"]
max_age_ms = 3000
description = "Mission phase from the mission computer"

[[policy.zone]]
name = "watched"
circle = { lat = 42.6650, lon = 23.4100, radius_m = 4000 }
22-mission-phase.rhai
fn decide(rows, node, policy) {
    let out = #{};
    let phase = node.ext.payload.mission_phase;   // () while absent or stale
    if phase != "on_station" { return out; }
    if node.zones != () && "watched" in node.zones { return out; }   // the rules decide there

    // The best SNR among alive emitters, per peer.
    let best = #{};
    for r in rows {
        if !r.link.alive || r.link.snr_db == () { continue; }
        let p = `${r.peer.id}`;
        if !best.contains(p) || r.link.snr_db > best[p].snr {
            best[p] = #{ key: r.key, snr: r.link.snr_db };
        }
    }
    for r in rows {
        let p = `${r.peer.id}`;
        if !best.contains(p) || r.link.snr_db == () { continue; }
        if r.key == best[p].key {
            out[r.key] = #{ weight: 2.0, reason: `best SNR on station (${r.link.snr_db} dB)` };
        } else {
            out[r.key] = #{ deny_classes: ["Video"], reason: "on station: Video rides the best-SNR link" };
        }
    }
    out
}
In practice

Write, check, replay, push, watch, explain.

A policy reaches a fleet the way the rest of its configuration does, with two steps that configuration never had: it can be run against the node’s live link table before it applies, and against recorded link tables to see what it would have done.

Write

Rules, and a script if one is needed, under [policy] in the node’s configuration. The commented mission examples above are the starting point.

Check

atlasd policy check compiles the rules and the script and prints each rule with its actions; with --now it evaluates them against the running daemon’s last input and prints the verdicts it would publish. atlasd config check reports the same errors as fatal findings, with the rule and the column. Both list the declared variables with their maximum age, the zones and the script’s source. atlasd policy check also adds a line of advice when a variable’s window spans a hundred ticks or more, since a slower tick would then do less work.

Replay

atlasd policy replay runs the candidate over a recording in recorded time, timers and script fallback behaving as live, and prints per tick each link’s verdict, the strategy’s pick with and without the policy, every change, and per link the share of time excluded, on standby, weighted or class-capped, with flaps per minute.

Sign and push

With the fleet configuration, from atlasd config sign-epoch or the dashboard’s Push. [roles.<role>.policy] overlays target one role. A broken policy is refused when signing and again on receipt; an accepted one applies at the next tick, without a restart. A script_file is read and embedded with its SHA-256 at signing; a push that still names a file, or whose script no longer matches its hash, is refused.

Watch

The dashboard’s Current configuration → Policy lists the mode, the tick, every rule with how many rows it holds now, the script’s state and counters, and the per-link verdicts. The link table gains a Policy column — excluded, standby, × 0.3, no Control — whose tooltip names the rule and its condition. Conditions are coloured wherever they are printed, and a Policy variables view lists every variable by group and every external one by producer, with a Fresh, Stale or Never fed chip, its age and the rules that read it; zones, silent links and findings sit beside the rules.

Explain

atlasd policy explain answers “why is this link not carrying?” from the live snapshot: per row its state, every rule that touched it with its condition, the script’s reason and printed lines, and the variables it read; above the rows it prints the script’s source, the silent links, the zones and the findings.

shell — check, replay, explain
atlasd policy check 04-rssi-falling.toml               # compiles? which rules?
atlasd policy check 04-rssi-falling.toml --now         # verdicts against the live link table
atlasd policy replay --journal /var/lib/atlas/journal/nexus0.policy-inputs.jsonl \
                     --policy 04-rssi-falling.toml     # what it would have done
atlasd policy explain --link wifi                      # on the node, once pushed
atlasd policy var list --ext                           # fed variables: fresh, holding, stale or never fed
atlasd config check — a mistyped variable
policy.rule[0].when: `fading`: at column 1: unknown variable `link.rssi` (did you mean `link.rssi_dbm`?)
atlasd policy check — example 20 without its tick_ms: advice, not a warning
$ atlasd policy check battery.toml
  ✓ battery.toml: policy compiles — 2 rules, no script
  mode normal  tick 500 ms
  ● ext.power.battery_pct  float  max age 300000 ms — Mast battery state of charge (cron, from the charge controller)
  ● battery-low-shed  deny Video/Bulk  ext.power.battery_pct < 30 and 'high-power' in link.tags
      for 0 ms, hold 600000 ms
  ● battery-critical-standby  standby  ext.power.battery_pct < 15 and 'high-power' in link.tags
      for 0 ms, hold 600000 ms
  → policy.rule[0]: rules `battery-low-shed`, `battery-critical-standby` read `ext.power.battery_pct`, whose value counts for 300000 ms (max_age_ms), and the policy ticks every 500 ms: each value is evaluated about 600 times before it can go stale. Advice only: if no other rule needs the fast tick, a slower tick_ms does less work; the window, not the tick, decides when the value lapses.
States

Five answers to “why is this link not carrying?”

Every row is in one of five states: carrying candidate; held: a better tier is alive; excluded; restored by the last-link guarantee; dead. The scheduler view’s decision line and its selection timeline append the policy’s effect — “policy: cellular standby (cellular-last)” — so the moment the policy moved traffic is marked where the traffic moved. A silenced link reads “silent (no probes, no traffic)” in the link table, its dialog and the scheduler view. the dashboard ↗

API

The same answers, machine-readable

/api/stats carries a policy block — mode, tick, evaluations, the table’s age, the rules with the variables each reads, the script’s state, counters and source, every row’s verdict, state and causes, the variable catalogue with each external variable’s freshness, the findings, the zones and the silent links — beside the full input table, and each link and each scheduler decision carries its own verdict. The journal records policy.applied, policy.script_failed, policy.script_quarantined, policy.script_recovered, policy.evaluator_failed, policy.var_stale, policy.var_fresh, policy.var_refused, policy.link_silenced and policy.link_unsilenced. the API ↗

Layer 1 · Rules

A condition, one or more actions, two timers.

Rules are TOML in the node’s configuration. Conditions are compiled and type-checked against the variable catalogue, so an unknown variable — with a “did you mean” hint — a string compared with a number, an ordered comparison of strings or a condition that is not true or false is a fatal finding at config check, with the column.

config.toml — the [policy] grammar
[policy]
enabled = true            # default false; true with no rules = observe only
tick_ms = 500             # evaluation cadence, 100–60000
mode = "normal"           # policy.mode; any short word

[[policy.link]]           # operator facts about a [[link]], by name
name = "satcom"
tags = ["metered", "emitter"]

[[policy.var]]            # a value another program feeds: ext.payload.mission_phase
producer = "payload"
name = "mission_phase"
type = "enum"                             # bool, int, float, string or enum
values = ["transit", "ingress", "on_station", "egress"]
max_age_ms = 3000                         # 100–86400000, 10000 unless set; absent once older

[[policy.zone]]           # a circle, or a polygon of 3–64 vertices
name = "listening-post"
circle = { lat = 42.6650, lon = 23.4100, radius_m = 4000 }

[[policy.rule]]
name = "cellular-last"                    # unique, [a-z0-9_-], 1–48
when = 'link.bearer == "cellular"'        # condition (below)
standby = true                            # one or more actions
note = "Metered: carries only when the free links cannot."
for_ms = 0                                # condition must hold this long first
hold_ms = 0                               # stays engaged this long after it clears
ActionEffect on the row
exclude = trueThe link carries nothing for this peer, unless that would leave no link alive.
silent = trueExcluded, and Atlas sends nothing on the link — no traffic, no probes, no probe or handshake replies, no keepalives — while another link is alive. Silence is per link, for every peer.
weight = w(0, 100]. The link’s ranking cost is divided by w: 0.5 looks twice as slow. Weights of several rules multiply.
prefer = trueTier preferred: used ahead of normal links.
standby = trueTier standby: used only when no preferred or normal link is alive.
deny_classes = [..]These traffic classes avoid the link: Control, Voice, Position, Telemetry, Video, Bulk.
only_classes = [..]Only these classes use the link; every other class is denied.

Combination is order-independent: any exclusion excludes, a silent row silences its link node-wide, weights multiply (clamped to [0.001, 100]), standby beats prefer, denied classes are the union. Every effect records the rule that caused it.

Language

Small, and checked before it runs

and or not (also && || !), == != < <= > >=, + - * /, in and not in over lists, strings in single or double quotes, numbers such as 1_000 or 2.5e3, true and false, the functions present(x), abs(x), min(…) and max(…), the place functions inside_zone('name'), inside_polygon('name'), inside_circle(lat, lon, radius_m) and distance_to_m(lat, lon), and parentheses. An ext. variable compiles only when [[policy.var]] declares it, and an enum is compared only with its declared values. At most 2 048 bytes, 512 tokens and a depth of 32 per condition, and at most 256 rules.

Absent values

A missing measurement never fires a rule

A variable the daemon does not have for a row right now — no telemetry adapter, no position fix — is absent, never zero. Absent values follow three-valued logic: arithmetic on absent is absent, a comparison with absent is unknown, false and unknown is false, true or unknown is true, not unknown is unknown. A rule fires only when its condition is true, so a missing measurement never fires a rule, not even through not. present(x) is the explicit test, and division by zero is absent.

Timers

Onset and hold, against flapping

for_ms makes a condition hold at every tick for that long before the rule engages; hold_ms keeps it engaged until the condition has been not-true for that long. Both are per rule and per row, measured at tick time, up to an hour. They are what keeps a rule on a noisy variable, such as RSSI or the noise floor, from flapping.

Mode and tags

Facts only the operator knows

[policy] mode is the mission mode, any short word — normal, emcon — read by rules as policy.mode and changed by a configuration edit or a fleet push, applied at the next tick. [[policy.link]] attaches tags to a link by name — directional, wired, emitter, shared-backhaul — for what no measurement can tell.

Zones

Areas on the map, tested against our own fix

Up to 32 [[policy.zone]], each a circle of 1 m to 1 000 km, measured by great-circle distance, or a polygon of 3 to 64 vertices, concave shapes included. node.zones lists the zones the node’s own fix is inside, and inside_zone('x') reads it, so without a position fix a zone rule is unknown and does not fire; a policy that wants a lost fix to count as inside says so: inside_zone('x') or not present(node.lat_deg). inside_circle and distance_to_m work from the same fix. A zone a rule names but nobody declared is refused at config check, with the names that are declared, and the dashboard’s Zones table shows inside, outside or unknown and the distance to each.

Silence

A link Atlas sends nothing on

silent = true is the parked state relay election already uses, driven by the policy. The transport refuses every datagram on the link, whichever path asks — data, probes, replies, keepalives — the probe loop skips it, and the link monitor holds it without counting it dead. It holds only while another link is alive: when the rule clears, the verdict table goes stale or every other link dies, the link is released and comes back alive on its first probe answer. The journal records policy.link_silenced and policy.link_unsilenced.

Layer 2 · Script

One function, the whole table, hard bounds.

When a decision needs the other rows — rank the radios, compare a metered link with the load on the free ones — a script sees the whole table at once. Its verdicts combine with the rules’ exactly like one more rule, named script.

config.toml — a script beside the rules
[policy]
script = '''
fn decide(rows, node, policy) {
    let out = #{};
    for r in rows {
        let s = r.link.rssi_slope_db_per_s;
        if s != () && s < -1.5 { out[r.key] = #{ weight: 0.3, reason: "RSSI falling" }; }
    }
    out
}
'''
script_max_operations = 200000   # 1 000 – 5 000 000
script_time_ms = 20              # 1 – 200, and at most a quarter of tick_ms
script_stale_ms = 5000           # how long a last good result may stand in
config.toml — the script in its own file
[policy]
enabled = true
script_file = "policy.rhai"      # next to the config, or an absolute path
atlasd policy check — which script runs
$ atlasd policy check 22-script-file.toml
  ✓ 22-script-file.toml: policy compiles — 0 rules, a script
  mode normal  tick 500 ms
  script from file 22-mission-phase.rhai · 1115 bytes · sha256 9be979b6e2b23ad3
  ● ext.payload.mission_phase  enum (transit, ingress, on_station, egress)  max age 3000 ms — Mission phase from the mission computer
  ● zone watched  circle 42.66500, 23.41000 r 4000 m
In

The rows, the node, the mode

rows is one map per row, #{ key: "wifi@3", link: #{…}, peer: #{…} }, with every link and peer variable; an absent value is (). node holds the node variables — node.zones among them, and every external variable as node.ext.<producer>.<name>, including those only a producer declared — and policy the mode. geo_distance_m(lat1, lon1, lat2, lon2) measures between two points.

Out

Verdicts by row or by link

A map keyed by a row ("wifi@3") or a link name ("wifi", every row of that link), each value a map of exclude, silent, weight, prefer, standby, deny_classes, only_classes and a reason — or () for no opinion. An unknown key, link or class, or a weight out of range, fails the run.

Prints

Debugging that stays on the node

Up to eight print(x) lines of 200 characters per run are kept and shown by atlasd policy explain and by replay. Nothing reaches standard output.

From a file

A script that grew past a screenful

A policy script can live in its own file; when the policy is pushed to the fleet, the script’s text and its SHA-256 travel inside the signed configuration, so no node ever loads a file named by a push. script_file names it, relative to the configuration or absolute; the daemon reads it with the configuration, as do config check, the dashboard’s validation and atlasd policy check, and a missing or unreadable file is a fatal finding. atlasd config sign-epoch and the dashboard’s push replace it with the text and script_origin = { file, sha256 }; a pushed policy that still names a file, or whose text no longer matches its hash, is refused. script and script_file together are an error, and atlasd policy check prints which source it used.

Bound, per runLimit
Operationsscript_max_operations · 200 000 (1 000 – 5 000 000)
Wall timescript_time_ms · 20 ms (1 – 200, ≤ ¼ tick) · checked every 256 operations
Stand-inscript_stale_ms · 5 000 ms for a last good result
Call depth16
Expression depth64 (32 inside functions)
Sizesstring 4 096 B · array 4 096 items · map 512 entries
Source64 KiB, inline or in the file

With operations, sizes and depth bounded, the run’s memory is bounded too.

The sandbox

No clock, no randomness, no I/O

The engine runs without a clock, a random source, modules, custom syntax or eval, with strict variables. A decide taking three parameters must exist, and that is checked when the script compiles — at config check, not at the first tick. Same inputs and times, same outputs.

Why Rhai

Source the operator can read back

The script ships as source text, inline in the TOML or in a file embedded at signing, readable in the configuration diff and on the dashboard, with errors reported at config check by line and column. It needs no toolchain, adds no JIT to the daemon and is written in Rust like the rest of it. A ten-link table takes tens of microseconds, well inside the tick; a compiled module would be faster per operation, opaque in a diff, and need a toolchain to author.

The fallback ladder

Every failure is one step down. The floor is the built-in strategy.

Rules cannot fail at run time: they are compiled and type-checked before they apply, and absent values are unknown rather than errors. What can fail is the script and the evaluator, and each failure moves the node one step towards the strategy it would run without a policy — counted, journaled and visible in the snapshot.

ONE STEP DOWN PER FAILURE · BACK UP AT THE NEXT GOOD RUN Rules + scriptthe policy as written Rules + last good script resulterror, limit or bad result · up to 5 s old Rules + built-in strategyno script effect · 5 failures: 60 s quarantine Built-in strategyevaluator stalled or failed verdicts every tick policy.script_failed script.state = last_good script.state = fallback policy.script_quarantined · retried after 60 s table older than max(4 × tick, 3 s) ignored policy.evaluator_failed · table reset to neutral FLOOR · ONE CARRYING LINK FOR THE NODE AND EACH CLASS · NEVER NO TRAFFIC
SCRIPT FAILSits last good result stands in for up to 5 s, then the rules alone with the built-in strategy
FIVE IN A ROWthe script is quarantined for 60 s, then retried
EVALUATOR STALLSa table older than max(4 × tick, 3 s) is ignored: the built-in strategy alone
THE FLOORone carrying link for the node and each class while one is alive — never no traffic
FailureWhat happensSeen as
Rule evaluationCannot fail: compiled and type-checked; absent values are unknown.—
Script error, operation or time limit, bad resultThis tick uses the script’s last good result if it is younger than script_stale_ms, else no script effect: rules and the built-in strategy.Counters script_failures, script_timeouts; journal policy.script_failed, first of a run then at most once a minute; script.state last_good or fallback
Five script failures in a rowThe script is quarantined for 60 s, not run, then retried.Journal policy.script_quarantined; script.state = quarantined
Panic in the evaluatorThe table resets to neutral; the evaluator is rebuilt on the next configuration change.Journal policy.evaluator_failed, as an error
Evaluator stallsThe data path ignores a table older than max(4 × tick, 3 s): the built-in strategy.policy.table_age_ms in the snapshot
Every link excluded, or every link denies a classThe guard keeps them all.Row state restored, by the last-link guarantee
A silenced link would be the last one aliveThe silence is released; the link probes again and carries.Journal policy.link_unsilenced
An external source falls silentIts variable reads as absent once its last value is older than max_age_ms: rules on it do not fire, and the script sees (). A value that holds until replaced stays in force.Journal policy.var_stale once, policy.var_fresh on recovery; Stale or Never fed on the dashboard
A producer sends a wrong valueThat value is refused and counted; the other values in the same line are kept.Journal policy.var_refused, at most once a minute per producer; the last refusal on the dashboard
A configuration with a broken rule or script, an undeclared external variable, an unknown zone or an unreadable script fileRefused by config check, by the apply watcher before the live file is touched, and by the signer and every receiving node before a push is signed or adopted.A fatal finding with the rule’s index and the column
The variable catalogue

What a condition can read.

About fifty variables the daemon already has, one row per peer and link, the zones the node’s own fix is inside, and the values other programs on the vehicle feed. Units are in the names. A value the daemon does not have for that row right now — or a fed value whose source has gone quiet — is absent, never zero, and an absent value never fires a rule.

VariableUnitWhat it is
Link
link.name · link.id—The [[link]] name and its index.
link.typestringdirect, relay or serial.
link.bearerstringThe bearer kind: wifi, cellular, ethernet, radio, bluetooth, mesh, relay, satellite, unknown — declared on the link, else derived on the host.
link.tagslistOperator-declared in [[policy.link]].
link.alive · link.parkedboolEvidence-required liveness; parked by relay election.
link.rtt_ms · link.jitter_msmsProbe round trip, smoothed; its jitter.
link.loss_pct · link.probe_loss_pct%Measured loss, from the data path when present; the 20-probe window alone.
link.risk_pct · link.sched_loss_pct%The prediction’s predicted loss for this row; the loss the scheduler ranks by, the larger of measured and predicted.
link.delivery_ms · link.queue_delay_msmsExpected delivery time of a 1 400-byte packet; the standing-queue, kernel or serial queue delay.
link.capacity_mbps · link.capacity_declaredMbit/s · boolThe declared capacity, and whether it was set in the configuration.
link.util_pct%Traffic over the load window divided by capacity; may exceed 100.
link.metered · link.quota_used_pct · link.over_budgetbool · % · boolThe link has a quota; the share of this period’s budget used; the budget is spent.
Adapter telemetry · absent when older than 5 s or never reported
link.rssi_dbm · link.rssi_remote_dbmdBmSignal strength at this end and at the far end.
link.noise_dbm · link.noise_remote_dbmdBmNoise floor at this end and at the far end.
link.snr_dbdBRSSI minus noise, when both are present.
link.rssi_slope_db_per_sdB/sThe RSSI trend the prediction uses; negative is fading.
link.buffer_fill_pct%How full the radio’s transmit buffer is, as its adapter reports it; 0 is empty, 100 is full.
link.rx_errors · link.fec_correctedcountReceive errors and FEC corrections reported by the adapter.
link.telemetry_age_ssAge of the last adapter report, present up to 60 s.
Timing
link.state_age_ssTime since this row’s liveness last changed.
link.since_response_ssTime since the last probe answer.
link.missed_probescountConsecutive unanswered probes.
Peer
peer.id · peer.name—The peer and its advertised node name.
peer.rolestringIts advertised role: ground-station, uav, ugv, usv, dismount, relay, or a fleet’s own.
peer.distance_mmGreat-circle distance between our fix and its advertised position; needs both.
peer.speed_mps · peer.position_age_sm/s · sHorizontal speed from its advertised velocity; the advert’s age.
peer.alive_linkscountOur links alive to this peer.
Node
node.name · node.rolestringOur node name and role.
node.lat_deg · node.lon_deg · node.alt_m° · ° · mOur position fix: static configuration, the telemetry socket or the position API; absent without a fix, or once a live fix is older than 30 s.
node.speed_mpsm/sOur horizontal speed, reported or derived from consecutive fixes.
node.zoneslistThe names of the declared zones our fix is inside; absent without a fix.
node.utc_hour · node.utc_minute_of_day · node.weekdayh · min · ISOThe system clock in UTC; weekday 1 is Monday, 7 Sunday.
node.clock_syncedboolThe kernel reports a disciplined clock: NTP, PTP or GPS.
node.links_alive · node.uptime_scount · sLocal links alive to at least one peer; daemon uptime.
policy.modestringThe operator’s mission mode from [policy] mode.
Zones · functions over our own fix, unknown without one
inside_zone('name')boolOur fix is inside the declared zone, circle or polygon.
inside_polygon('name')boolThe same for a polygon zone; naming a circle is refused at config check.
inside_circle(lat, lon, radius_m)boolOur fix is within radius_m of a point written in the rule.
distance_to_m(lat, lon)mGreat-circle distance from our fix to a point.
External · fed by other programs, absent once stale
ext.<producer>.<name>as declaredA value another program on the vehicle feeds: a bool, an int, a float, a string of up to 64 bytes, or one of up to 16 enum values. Rules read the variables the configuration declares in [[policy.var]]; the script also sees those a producer declared alone.
ext.payload.mission_phaseenumFor example the mission computer’s phase — transit, ingress, on_station, egress — once a second.
ext.power.battery_pct%For example a mast battery’s state of charge, from a cron job once a minute.
External variables

Declared, fed, then fresh or absent.

config.toml — the contract rules may read
[[policy.var]]
producer = "payload"          # [a-z][a-z0-9_], up to 24
name = "mission_phase"        # [a-z][a-z0-9_], up to 32 → ext.payload.mission_phase
type = "enum"                 # bool | int | float | string | enum
values = ["transit", "ingress", "on_station", "egress"]   # enum only, 1–16
max_age_ms = 3000             # optional, 100 – 86 400 000; default 10 000: older reads as absent
# or, instead of max_age_ms: hold = true (every value holds until replaced)
description = "Mission phase from the mission computer"
unit = ""
telemetry socket — a producer’s two lines, and a value that holds
{"policy_var_declare":{"producer":"payload","name":"mission_phase","type":"enum","values":["transit","ingress","on_station","egress"],"max_age_ms":3000,"description":"Mission phase from the mission computer"},"ack":true}
{"policy_var_set":{"producer":"payload","values":{"mission_phase":"ingress"}}}
{"policy_var_set":{"producer":"operator","values":{"posture":"silent"},"hold":true}}
shell — the same from a script or a cron job
atlasd policy var declare --producer power --name battery_pct --type float \
                          --max-age 5m --unit %       # ms, or 500ms, 3s, 2m, 1h
atlasd policy var set --producer power battery_pct=71.5
atlasd policy var declare --producer operator --name posture --type enum \
                          --values normal,silent --hold
atlasd policy var set --producer operator posture=silent    # holds until replaced
atlasd policy var list --ext                 # fresh, holding, stale or never fed; age; producer uid and pid
atlasd policy check — a misspelt phase
$ atlasd policy check phase-typo.toml
  ✗ phase-typo.toml: policy.rule[0].when: `ingress-quiet`: at column 30: `ingres` is not a value of `ext.payload.mission_phase` (transit, ingress, on_station, egress)
The contract

Rules read what the configuration declares

A rule may read an external variable only when [[policy.var]] declares it. The configuration is the typed contract that config check and the epoch signer check, so a pushed policy compiles the same on every node, whichever producers happen to be running; a misspelt enum value or an undeclared ext. variable is refused with the column. A producer may declare more variables, which the script and the dashboard see, and may declare a configured one again to fill its description and unit — never with another type or with enum values the configuration does not list. The configuration’s maximum age, or its hold, wins.

Feeding

Two lines on the socket atlasd already runs

A program connects to the telemetry socket — the one adapters use, with [telemetry] enabled = true — sends a policy_var_declare line and then policy_var_set lines carrying any number of values. With "ack": true the daemon answers one line, {"ok":true} or the refusal; without it nothing is written back. A shell script or a cron job uses atlasd policy var declare and atlasd policy var set, which print the daemon’s refusal when there is one. null is an explicit “unknown now”.

Fresh or absent

A silent source reads as unknown

A value older than its max_age_ms — 10 s unless declared otherwise — reads as absent, so the three-valued logic applies and a silent source never fires a rule. The window is the whole rule: the producer may send faster or slower, and nothing counts periods. Going stale, or never being fed after the declaration, is journaled once as policy.var_stale, and recovery once as policy.var_fresh. Whether a dead source means “quiet” or “carry on” is the rule’s to say: not (ext.payload.rf_quiet == false) is true while the flag is absent.

Holds

An order given once stays given

An operator’s order is said once and nobody re-sends it. A declaration with hold = true (--hold on atlasd policy var declare, "hold":true on the socket) makes every value hold until it is replaced: it never goes stale, the dashboard shows it Fresh with “holds until replaced”, and no policy.var_stale is journaled for it. Until it is first set it reads as absent, so nothing fires on an order not yet given. A single value can also be sent with hold — atlasd policy var set --hold, or "hold":true on a policy_var_set line — and holds until replaced even on a variable that has a window; the next value sent without hold returns to the window. hold together with max_age_ms is refused.

Who sent it

Producers named, and checked by the kernel

Each producer is identified by its name and by the user and process id of the socket’s peer, taken from the kernel rather than from the line. The first line under a producer name binds it to that user, and lines under that name from another user are refused. A wrong value is refused and counted — journaled as policy.var_refused at most once a minute per producer — and the other values in the same line are kept.

Bounds

Small, and bounded per node

64 external variables and 16 producers per node; producer names up to 24 characters and variable names up to 32; maximum ages from 100 ms to a day; strings up to 64 bytes; enums of 1 to 16 values; socket lines up to 64 KiB. A producer declares again on every connection, and a cron job on every run: both are idempotent.

Seen

Which sources are fresh, at a glance

atlasd policy var list and atlasd policy explain --vars print every variable by group with its value and cadence and, for an external one, fresh, stale or never fed, its age, its maximum age or that it holds until replaced, the producer’s user and process id, who declared it, its counts and the last refusal. The dashboard’s Policy variables view shows the same, one group per producer, with a Fresh, Stale or Never fed chip and the rules that read each variable; the update column reads “producer · max age 3 s”, “producer · max age 10 s (default)” or “producer · holds until replaced”.

A spectrum sensor beside the network7:00 · plays from YouTube
Boundaries

What a policy can and cannot reach.

Stated in the same font size as everything above.

Inputs

What the daemon reads, and what it is told

The catalogue is what atlasd measures, what its configuration says and what other programs on the vehicle feed it. atlasd itself reads no battery or power level, no carrier state and no per-link link speed; a program that knows one feeds it as an external variable, as the battery cron job does. External variables are this node’s own: a peer’s battery level is not carried in its adverts. A monetary cost is expressed through metered, quota use and tags.

Classes

A cap is a deny, and needs the classes

A traffic class leaves a link or keeps it; there is no per-class byte-rate cap on a link, which would need a token bucket per class and link on the data path. Class actions act on the transport classes, which exist with [qos] enabled = true, and apply where a packet’s class is known — on the originating node’s path. A relay forwarding transit traffic applies exclude, tier and weight. the classes ↗

Weights

What a weight moves with classes on

With transport classes on, a weight scales the share a striped class (Aggregate or FEC) puts on each link. Single-best and duplicate classes are placed by the class’s own cost; move them with prefer, standby or exclude.

Silence

Silent is what Atlas sends, per link

A silenced link carries nothing from Atlas — no traffic, no probes, no replies — while another link is alive. What the radio emits by itself is outside Atlas: a Wi-Fi interface still beacons or probes for its network, a cellular modem stays registered with its cell, a serial radio may send its own heartbeat; switching a radio off or to receive-only is its adapter’s or the vehicle’s. Silence is per link and node-wide, not per peer: its guarantee counts any other alive link towards any peer, so a peer reachable only over a silenced link loses contact while another link carries to other peers. A link that is only excluded still sends its probes, and the never-mute guarantee carries traffic on it if every quieter link is down.

Zones

Flat areas, from our own fix

A zone has no altitude band and no time window — a rule combines a zone with node.utc_hour — and no polygon may cross the antimeridian. A boundary has no hysteresis beyond hold_ms. Membership is computed from the node’s own fix; without one a zone rule is unknown.

Lifetimes

What survives a restart, and when a file is read

Declarations a producer sends do not survive a daemon restart; declarations in the configuration do, and a producer declares again when it reconnects. The script file is not watched: an edit to it applies with the next configuration apply or restart, and the SHA-256 on the dashboard says which text runs.

Replay

Per peer where the recording is

A recording made while the policy was enabled holds every variable of every row. A recording of plain snapshots from a node with the policy off replays node-wide, one row per link from the snapshot’s per-link figures, without the per-peer variables.

Request an evaluation

Tell us what your mission optimises for.

Bring the bearers, what each one costs you and when it has to go quiet. The answer is a policy you can replay against your own recordings before it is pushed.