Capacity Management, Load Shedding & Strain Ledgers

Problem Architecture

Static Ceilings and Naive Ramps

Evaluating bilateral grants with static limits introduces two critical vulnerabilities:

• Unproven capacity: An idle peer sending minimal traffic can restore peak bandwidth limits under naive additive increase, claiming capacity without handling real volume.
• Trunk exhaustion: Multiple peerings operating within individual limits can collectively overload host hardware. Without an aggregate host ceiling, incoming demand exhausts memory and drops active sockets.

The meshnode daemon resolves both issues by tying additive recovery to active utilization and enforcing an aggregate host capacity ladder.

Subsystem 01 · node/capacity.py

Aggregate Capacity and the Load-Shedding Ladder

A node declares its aggregate capacity ceiling under capacity in config.json. This configuration is live: operators can adjust or remove ceilings on a running node, and the daemon applies changes on its next scheduler tick.

# Inspect current capacity and load-shedding status
python3 -m node.meshnode capacity /var/lib/meshnode

# Output:
# aggregate capacity:  events_in 500,000 / hr   bytes_in 500 MB / hr
# current pressure:    42% (peak observed: 68%)
# engaged rungs:       none (normal operations)
# historical peak:     window 496810 (340,120 events)

Subsystem 02 · node/strain.py

Strain Ledgers and Topological Balance

Transient network anomalies—such as client reconnects, temporary socket timeouts, dropped subscriptions, and minor clock drift—occur routinely. Fleetmesh treats these events as local operational noise rather than formal fraud disputes.

The StrainLedger subsystem in node/strain.py stores survived anomalies in accounts.sqlite. These records remain local to the node and adjust internal operational parameters:

• Accounting retention: Extends the receipt retention window for peers with frequent reconnects, allowing clean reconciliation without sequence breaks.
• Backoff calibration: Dynamically sets retry timers based on observed socket recovery durations.

Directional Dominance

When a node receives most volume from a single upstream partner, it develops topological fragility. If that sole peer fails, the dependent node loses connectivity.

StrainLedger groups telemetry by direction (a tuple of (peer, shard, transport)) and weights observations using the peer trust tier:

• Probation tier: Weighted at 0.0. Unverified accounts cannot alter node strain metrics or trigger directional alerts.
• Anchor and Core tiers: Weighted at 1.0. Established peers contribute to topological health indicators.
• Dominant share threshold: When any single peer exceeds 70% of total weighted strain, the node emits a directional dependency warning, indicating that the operator should establish additional peerings.

# Inspect strain metrics and directional topology
python3 -m node.meshnode strain /var/lib/meshnode

# Output:
# distinct directions: 4
# dominant share:      31% (f22c163a211c50e3 / bristol / wss)
# flag tree status:    healthy (no unilateral structural dependence)
# reserve multiple:    1.2x (normal backoff and retention)

Core Invariants

Resilience Invariants

• Reward verified throughput: Rate recovery requires verified, receipted events within negotiated grants. Ping packets and empty frames carry zero recovery credit.
• Local defensive adaptation: Strain metrics adjust local buffers and retry schedules. They do not confer global governance weights or authority over remote peers.
• Manual tier elevation: Capacity algorithms adjust parameters within an assigned grant tier. Promoting a peer to a higher trust tier requires explicit operator action.