3.1.2. Peering Plane (fleetmesh_node.planes.peering)
The Peering Plane oversees bilateral node relationships, economic limits, capacity shedding, network diagnostic reports, and trust scores.
3.1.2.1. Peering Session Compartment
The Peering compartment: construction, the grant writers (issue, decide), the reconciler that is its tick, and the compartment contract. The handshake itself is in handshake.py; the envelope in envelope.py.
- class fleetmesh_node.planes.peering.peering.core.Peering[source]
Bases:
HandshakeMixin,WireProtocolThe handshake and the grants, as a compartment.
Its tick is the reconciler: an amend is a notification and the addressable kind 30801 is what the grant IS, so a subject reads the coordinate rather than waiting to be told. Its refusals are every amend it would not act on and every peering it turned away - the path that recorded nothing at all on the night every amend on the mesh was lost.
- config_cls
alias of
PolicyConfig
- HANDLERS: tuple[Handler, ...] = (Handler(kind='https://didcomm.org/discover-features/2.0/queries', run='handle_discover', schema=None, doc='answer discover-features/2.0 query', exact=True, reads=(), writes=()), Handler(kind='propose', run='handle_propose', schema=None, doc='answer peering proposal', exact=False, reads=(), writes=('grants',)), Handler(kind='accept', run='handle_accept', schema=None, doc='take peering acceptance', exact=False, reads=(), writes=('grants',)), Handler(kind='amend', run='handle_amend', schema=None, doc='take amended grant', exact=False, reads=(), writes=('grants',)), Handler(kind='terminate', run='handle_terminate', schema=None, doc='tear down peering', exact=False, reads=(), writes=('grants',)))
- OUTBOUND: tuple[Outbound, ...] = (Outbound('propose', reply=('offer', 'decline')), Outbound('offer', reply=('accept',)), Outbound('accept'), Outbound('decline'), Outbound('amend'), Outbound('terminate'))
- COMMANDS: tuple[Any, ...] = (Command(key='show', name='Peering', description='the peerings this node holds, and when each grant was last reconciled', tags=('peering', 'status'), parameters=(), permission='peering/show', process=(), run='state', reply='{peers, reconciled, refused}', reads=(), writes=()),)
- STORES: tuple[Store, ...] = (Store(key='log', description='what the handshake did with each message, newest last', kind='ring', shape=<class 'tuple'>, bound=500, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='_reconciled', description='when each peer grant coordinate was last read', kind='table', shape=<class 'int'>, bound=4096, evict='lru', keyed_by='peer', persist='memory', sensitive=False, tags=()))
- CHANNELS: tuple[Any, ...] = (Channel(name='grant_issued', description='A peering grant was issued or amended for a peer', level='info', wire=<function _wire_grant>, say='peering grant issued to {peer} (cause: {cause}, tier: {tier})', tags=('peering', 'grant')), Channel(name='peer_connected', description='A peer completed the peering handshake and connected', level='info', wire=<function _wire_peer>, say='peer connected: {peer} as {role} via {transport}', tags=('peering', 'handshake')), Channel(name='peering_declined', description='Peering proposal was declined', level='trouble', wire=None, say='peering proposal declined from {peer}: {reason}', tags=('peering', 'decline')), Channel(name='peering_terminated', description='Peering relationship was terminated', level='note', wire=None, say='peering terminated with {peer}: {reason}', tags=('peering', 'terminate')))
- METRICS: tuple[Any, ...] = (Metric(name='peering_grants_issued', description='Grants issued or amended.', kind='counter', unit='', labels=(), counts='grant_issued', sample=None, buckets=(), tags=('peering', 'grant')), Metric(name='peering_peers_connected', description='Peers connected.', kind='counter', unit='', labels=(), counts='peer_connected', sample=None, buckets=(), tags=('peering', 'handshake')), Metric(name='peering_proposals_declined', description='Peering proposals declined.', kind='counter', unit='', labels=(), counts='peering_declined', sample=None, buckets=(), tags=('peering', 'decline')), Metric(name='peering_relationships_terminated', description='Peering relationships terminated.', kind='counter', unit='', labels=(), counts='peering_terminated', sample=None, buckets=(), tags=('peering', 'terminate')))
- NEEDS: tuple[Any, ...] = (Need(key='keystore', source='ks', block=None, late=False, getter=False, path=None, field=None), Need(key='my_descriptor', source='descriptor', block=None, late=False, getter=False, path=None, field=None), Need(key='my_public_descriptor', source='public_descriptor', block=None, late=False, getter=False, path=None, field=None), Need(key='peers', source='peers', block=None, late=False, getter=False, path=None, field=None), Need(key='transport', source='transport', block=None, late=False, getter=False, path=None, field=None), Need(key='relay_urls', source='relays', block=None, late=False, getter=False, path=None, field=None), Need(key='grant_store', source='stores.grants', block=None, late=False, getter=False, path=None, field=None), Need(key='policy', source='policy', block=None, late=False, getter=False, path=None, field=None), Need(key='node_class', source='node_class', block=None, late=False, getter=False, path=None, field=None), Need(key='timeout', source='timeout', block=None, late=False, getter=False, path=None, field=None), Need(key='events', source='events', block=None, late=False, getter=False, path=None, field=None), Need(key='capacity', source='capacity', block=None, late=True, getter=False, path=None, field=None))
- bind(capacity)[source]
The node’s own ceiling, through which a stranger is refused. Capacity ticks after budget, which ticks after peering, so it is bound once all three exist.
- Parameters:
capacity (Any)
- Return type:
None
- __init__(keystore, my_descriptor, peers, transport, relay_urls, grant_store=None, policy=None, node_class='edge', clock=None, timeout=15.0, capacity=None, node=None, publisher=None, host=None, events=None, my_public_descriptor=None)[source]
- Parameters:
keystore (Any)
my_descriptor (Any)
peers (Any)
transport (Any)
grant_store (GrantStore | None)
policy (Any | None)
node_class (str)
timeout (float)
capacity (Any | None)
node (Any | None)
publisher (Callable[[Sequence[str], Any, float], dict[str, tuple[bool, str]]] | None)
host (PeeringHost | None)
events (Any | None)
my_public_descriptor (Any)
- Return type:
None
- handle_discover(inbound)[source]
discover-features/2.0: a peer asks what this node speaks and is answered from the descriptor, by fleetmesh_core/peering’s disclose, so the answer cannot name a protocol the descriptor does not. Anyone may ask; the answer is what the descriptor already says in public.
- reconcile(now=None)[source]
Take up a grant that changed, without waiting to be told.
An amend is a notification; the addressable kind 30801 is what the grant IS, and this method is that sentence made true. A subject used to learn of a new grant only from a peering/1.0/amend, which travels as a stored gift wrap - kind 1059, one of the four messages the specification says must survive an offline recipient.
A relay is not obliged to keep one. relay.pocketstr.com answers a kind 1059 publish with OK and true, and then neither stores it nor serves it back to the recipient itself. Every amend on a four-node mesh was lost that way for a night. The two ends then name different grants for ever: every receipt is refused as divergent, so every window closes with no claim, so every window is active silence, so every peering earns an S2 that nobody did anything to deserve, and the tier falls to probation where only a person can raise it.
Asking the coordinate costs one query per peering and depends on nothing arriving. A protocol that must not conclude anything from an absence must also not depend on a presence.
- property refused: list[Refusal]
The last refusals, as the typed tuple Refusals keeps (positional reads still work; a NamedTuple is a tuple).
- issue(peer, payload, cause, reason, effective_epoch, now=None, on_clamp=None)[source]
Write, publish and record one grant, and tell the subject why.
effective_epoch is the window this grant governs from. Passing the window already running is what breaks a receipt chain, so a caller that means “from the next boundary” should say so with decide instead of working it out here.
Raises GrantUnpublished if no relay took the envelope, having recorded nothing: a grant the subject cannot fetch is worse than no grant. Raises ValueError for a cause the schema does not define.
- decide(peer, payload, reason, severity, decided_epoch)[source]
Decide a grant now and let it take effect at the next boundary.
An amend inside a window makes the two ends name different grants for the rest of it: the subject’s receipts still cite the grant it holds, the issuer has moved on, and every one is refused as naming a grant that did not govern that window. The window then closes on a claim one receipt short of what was measured, which is divergence, which is an S2 against a node that did nothing wrong.
So a decision is written down and published at the boundary. The store keeps one pending grant per peer and a later decision replaces an earlier one, which is how an operator’s word outranks the ladder’s without either having to know about the other.
- state()[source]
What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.
- Return type:
PeeringStateReport
- trouble()[source]
What an operator should be told without having to ask for it.
Everything here is WRONG: a watcher reds on it and a deploy fails on it. Something worth reading that is not a fault goes in notes(). May return a list of strings or typed Trouble instances.
- commands: Mapping[str, CommandSpec] = {'show': {'args': {}, 'does': 'the peerings this node holds, and when each grant was last reconciled', 'reply': '{peers, reconciled, refused}', 'subsystem': 'peering'}}
3.1.2.2. Budget & Credit Metering Compartment
The Budget subsystem itself: construction and restore, the meters, the window arithmetic, what the sync layer reports, and the Compartment contract. Separate from the mixins because this is where the state they all share is created; the mixins are the concerns that act on it.
- class fleetmesh_node.planes.peering.budget.core.BudgetConfig[source]
Bases:
ParamBlockBudgetConfig(DERIVED: ‘bool’ = False, tolerance: ‘float’ = 0.1, keep_windows: ‘int’ = 168, keep_findings: ‘int’ = 1000)
- name = 'budget'
- PARAMS: tuple[Parameter[Any], ...] = (Parameter(key='tolerance', name='Divergence Tolerance', description='Ratio by which measured usage may exceed limit before divergence', type=<class 'float'>, default=0.1, must='', tags=('budget', 'tolerance'), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=0.0, maximum=1.0, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='keep_windows', name='Keep Windows', description='Number of closed windows retained before pruning', type=<class 'int'>, default=168, must='', tags=('budget', 'history'), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=1, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='keep_findings', name='Keep Findings', description='Maximum adverse findings kept in memory', type=<class 'int'>, default=1000, must='', tags=('budget', 'findings'), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=10, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True))
- class fleetmesh_node.planes.peering.budget.core.Budget[source]
Bases:
ReceiptsMixin,WindowsMixin,TickMixin,WireProtocol- requires: tuple[str, ...] = ('peering', 'strain')
The accounting, as a compartment the operator can watch.
Its refusals are the ones that mattered: a receipt this node would not read, one naming a window this grant cannot be about, and one naming a grant that did not govern the window. That last was refused silently for a night on a four-node mesh while every window closed as active silence, and nothing anywhere said the two ends were naming different grants. It goes through the channel every compartment has now.
Its stop is the farewell: a node that vanishes mid-window leaves its issuer with traffic measured and no receipt, which is an S2 nobody earned.
- config_cls
alias of
BudgetConfig
- CHANNELS: tuple[Any, ...] = (Channel(name='window_evaluated', description='A closed window was evaluated against peer limits', level='note', wire=<function _wire_evaluated>, say='evaluated window {epoch} for peer {peer} severity {severity}', tags=('budget', 'evaluation')), Channel(name='window_repriced', description='A peer limit was repriced under AIMD congestion control', level='note', wire=<function _wire_repriced>, say='repriced peer {peer} for window {epoch}: {was} -> {now}', tags=('budget', 'repricing')), Channel(name='receipt_refused', description='A receipt from a peer was refused', level='trouble', wire=None, say='receipt refused from peer {peer}: {reason}', tags=('budget', 'receipt')))
- METRICS: tuple[Any, ...] = (Metric(name='budget_windows_evaluated', description='Windows evaluated.', kind='counter', unit='', labels=(), counts='window_evaluated', sample=None, buckets=(), tags=('budget', 'evaluation')), Metric(name='budget_windows_repriced', description='Windows repriced under AIMD.', kind='counter', unit='', labels=(), counts='window_repriced', sample=None, buckets=(), tags=('budget', 'repricing')), Metric(name='budget_receipts_refused', description='Receipts refused from peers.', kind='counter', unit='', labels=(), counts='receipt_refused', sample=None, buckets=(), tags=('budget', 'receipt')))
- OUTBOUND: tuple[Outbound, ...] = (Outbound('receipt', reply=('receipt-ack',)), Outbound('close'), Outbound('receipt-ack'))
- HANDLERS: tuple[Handler, ...] = (Handler(kind='receipt', run='handle_receipt', schema=None, doc='answer inbound budget/1.0 receipt', exact=False, reads=(), writes=()), Handler(kind='close', run='handle_close', schema=None, doc='answer inbound budget/1.0 window close', exact=False, reads=(), writes=()), Handler(kind='receipt-ack', run='handle_receipt_ack', schema=None, doc='take inbound budget/1.0 receipt-ack', exact=False, reads=(), writes=()))
- STORES: tuple[Store, ...] = (Store(key='evaluations', description='completed window evaluations', kind='ring', shape=<class 'fleetmesh_node.planes.peering.budget.evaluation.Evaluation'>, bound=1000, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='findings', description='adverse window findings', kind='ring', shape=<class 'tuple'>, bound=1000, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='clock_drift', description='receipt clock drift events', kind='ring', shape=<class 'tuple'>, bound=1000, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='receipt_gaps', description='receipt sequence gaps', kind='ring', shape=<class 'tuple'>, bound=1000, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='unpublished', description='receipts unpublishable to relays', kind='ring', shape=<class 'tuple'>, bound=1000, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()))
- COMMANDS: tuple[Any, ...] = (Command(key='show', name='Budget', description='what this node is accounting: peers metered, windows evaluated, findings held', tags=('budget', 'status'), parameters=(), permission='budget/show', process=(), run='state', reply='{peers, windows_evaluated, findings, grants_waiting_for_a_boundary, clock_drift, receipt_chains_open, idle_streaks, rejected, receipts_refused}', reads=(), writes=()),)
- NEEDS: tuple[Any, ...] = (Need(key='keystore', source='ks', block=None, late=False, getter=False, path=None, field=None), Need(key='transport', source='transport', block=None, late=False, getter=False, path=None, field=None), Need(key='grant_store', source='stores.grants', block=None, late=False, getter=False, path=None, field=None), Need(key='peering', source='peering', block=None, late=False, getter=False, path=None, field=None), Need(key='ledger', source='ledger', block=None, late=False, getter=False, path=None, field=None), Need(key='accounts', source='stores.accounts', block=None, late=False, getter=False, path=None, field=None), Need(key='strain', source='strain', block=None, late=False, getter=False, path=None, field=None), Need(key='events', source='events', block=None, late=False, getter=False, path=None, field=None), Need(key='reporter', source='reporter', block=None, late=True, getter=False, path=None, field=None))
- __init__(keystore, transport, grant_store, peering, clock=None, ledger=None, accounts=None, strain=None, node=None, events=None, reporter=None)[source]
- grants: GrantStore
- governing(peer, direction, epoch)[source]
The grant that governed one window, which is what the window is priced under and what a receipt for it names.
- Parameters:
- Return type:
GoverningRow | None
- aggregate(at=None)[source]
What every peer together is doing to this node, in the open window.
The issuer frame - usage_by is what a peer did to me - because that is the frame a ceiling is about. A grant bounds one peer and nothing bounded the node, so this is the number capacity measures pressure against.
Windows are per peering, so each peer contributes its own open epoch. With the default window that is one hour for all of them; with mixed windows it is still each peer’s current promise, which is the honest reading of “what is happening to me now”.
- observe(peer, message, i_initiated, outbound)[source]
One sync message, charged to the session’s initiator.
If I opened the session it is my usage under the peer’s grant, whichever way this message went; if the peer opened it, it is the peer’s usage under mine. The wire knows who opened it by the thid.
An open is flushed before this returns, because the counter it moves is the one this node’s own guard reads to decide whether it may open the next session. observe_session flushes at session END, which bounds the loss to one session in flight - and one session in flight is exactly what a restart loses. The node then reloaded a meter one short, throttled() found room that was not there, and the node opened a session the grant did not cover while believing it did. The peer measured the overrun and priced it: S1 on conn_rate at 5 over a grant of 4, which cost a peer 51 clean windows for restarting. See I15 in docs/audit-2026-10-07-4-issues.md, where the arithmetic is reproduced. Nothing else here needs to be durable this early - the volume counters are reconciled by the receipt and their divergence floor already absorbs a lost session by construction - so this is the one message kind that writes through.
- observe_session(peer, role, result)[source]
After a session: duplicates the peer delivered to me count against them, and both meters for this peer reach the store.
usage_of_me was written down at every receipt - send_receipt puts the meter before the message leaves - and usage_by was written only by the tick. So a node that stopped between ticks came back having forgotten some of what a peer had done to it while remembering all of what it had done to the peer, and an issuer that under-measures reads an honest claim as too high: divergence, and an S2 misreport against a peer that did nothing but keep working across somebody else’s crash. The asymmetry was the bug. A session is the natural boundary, the same one the other side already uses, and it bounds the loss to one session in flight rather than a whole tick interval.
- property rejected: Counter[str]
The refusal counts, under the name the health block and the suites already use. One channel, two readers.
- state()[source]
What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.
- Return type:
BudgetStateReport
- receipts_refused()[source]
The windows this node would not take a receipt for, because the two ends name different grants. Five at most: it is a fault to fix, not a history to read, and the counts keep the history.
- Return type:
- trouble()[source]
What an operator should be told without having to ask for it.
Everything here is WRONG: a watcher reds on it and a deploy fails on it. Something worth reading that is not a fault goes in notes(). May return a list of strings or typed Trouble instances.
- commands: Mapping[str, CommandSpec] = {'show': {'args': {}, 'does': 'what this node is accounting: peers metered, windows evaluated, findings held', 'reply': '{peers, windows_evaluated, findings, grants_waiting_for_a_boundary, clock_drift, receipt_chains_open, idle_streaks, rejected, receipts_refused}', 'subsystem': 'budget'}}
3.1.2.3. Capacity Shedding Compartment
The node’s own ceiling, held across ticks, and the shed ladder it drives.
fleetmesh_core/capacity.py is the arithmetic and states why there is no default total. This is the part that remembers: which rungs are engaged and since when, what a grant’s limits were before a shed so they can be handed back, and the largest window this machine has actually carried so an operator has a number to start from rather than a blank.
The total is read from config under capacity and is live. An operator may set it, raise it or delete it while the node runs and the next tick follows the file, which is the same contract every other live key has: the file is the interface and the daemon follows it.
- class fleetmesh_node.planes.peering.capacity.compartment.Capacity[source]
Bases:
Compartment- requires: tuple[str, ...] = ('budget',)
The node’s own ceiling, as a compartment the operator can watch.
What it declares: the config key capacity, live; one control command; a state an operator reads; the trouble it is in; and every peering it turned away, with the reason, in the refusal channel every compartment has. Before that channel existed a full node declined a stranger and recorded nothing, so the only trace of the first shed rung was a line in somebody’s journal.
- config_cls
alias of
CapacityConfig
- NEEDS: tuple[Any, ...] = (Need(key='budget', source='budget', block=None, late=False, getter=False, path=None, field=None), Need(key='total', source=None, block=<class 'fleetmesh_node.config.compartments.CapacityConfig'>, late=False, getter=False, path=None, field='total'), Need(key='grants', source='stores.grants', block=None, late=False, getter=False, path=None, field=None), Need(key='amend', source='amend', block=None, late=False, getter=False, path=None, field=None))
- COMMANDS: tuple[Any, ...] = (Command(key='show', name='Capacity', description='the declared total, the pressure on it, the rungs engaged and the largest window carried', tags=('capacity', 'status'), parameters=(), permission='capacity/show', process=(), run='show', reply='{declared, total, pressure, binding, rungs, held, since, measured, peak, suggested, note}', reads=(), writes=()),)
- STORES: tuple[Store, ...] = (Store(key='log', description='rungs engaged and released, newest last', kind='ring', shape=<class 'fleetmesh_node.planes.peering.capacity.types.RungChange'>, bound=200, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='before', description='the limits each peer held before a shed, to give back', kind='table', shape=<class 'dict'>, bound=4096, evict='refuse', keyed_by='peer', persist='snapshot', sensitive=False, tags=()), Store(key='peak', description='the largest window carried, per counter', kind='table', shape=<class 'int'>, bound=64, evict='refuse', keyed_by='counter', persist='snapshot', sensitive=False, tags=()))
- CHANNELS: tuple[Any, ...] = (Channel(name='rung_engaged', description='A capacity shed ladder rung engaged under pressure', level='trouble', wire=None, say='capacity shed rung {rung} engaged at {pressure}% pressure on {binding}', tags=('capacity', 'shed')), Channel(name='rung_released', description='A capacity shed ladder rung released as pressure eased', level='note', wire=None, say='capacity shed rung {rung} released', tags=('capacity', 'shed')))
- METRICS: tuple[Any, ...] = (Metric(name='capacity_rungs_engaged', description='Times a capacity shed rung engaged.', kind='counter', unit='', labels=(), counts='rung_engaged', sample=None, buckets=(), tags=('capacity', 'shed')), Metric(name='capacity_rungs_released', description='Times a capacity shed rung released.', kind='counter', unit='', labels=(), counts='rung_released', sample=None, buckets=(), tags=('capacity', 'shed')))
- LIFECYCLE: Lifecycle = Lifecycle(breaker=Breaker(failures=5, window=300, backoff=(30, 600)), restart=False, snapshot=1)
- transitions(now=None)[source]
Recompute and return the rungs that changed, as (action, what).
The caller acts on the transitions rather than on the state, because a shed and a restore each cost the peers an amend and neither should happen twice for one crossing.
- why()[source]
The message a decline carries. Names the binding counter and nothing else: a stranger learns this node is full, never who is filling it.
- Return type:
- remember(peer, limits)[source]
Keep what a shed is about to take. False when the table is full: the caller must not take what it could not promise to give back.
- restore_for(peer, tier)[source]
What this peer should get back, or None if nothing was taken.
Held inside the ceilings of the tier it holds NOW, because the ladder may have lowered it while the shed was on and a restore must never undo a remedy.
- tick(now)[source]
Recompute pressure and act on the rungs that changed.
Transitions and not state: a shed and a restore each cost the peers an amend, and neither should happen twice for one crossing of a threshold.
Then one invariant, checked every tick rather than on a transition: nothing is held back while amend_down is off. The transition alone misses the restart - the ladder comes back empty, so a shed that was on is never seen to release, and before (carried) would sit there with the peers still cut. Normally before is empty here and this is one length check.
- trouble()[source]
What an operator should be told without having to ask for it.
Everything here is WRONG: a watcher reds on it and a deploy fails on it. Something worth reading that is not a fault goes in notes(). May return a list of strings or typed Trouble instances.
- refuse_peering(peer)[source]
A stranger turned away because this node is full.
Recorded rather than only answered: a decline is not a finding, but a node that is refusing peerings and cannot say how many is a node whose operator finds out from somebody else.
- shed_grants(now=None)[source]
Reduce every live grant because this node is full, not because anyone misbehaved. What each peer held is remembered so it can be given back.
- restore_grants(now=None)[source]
Give back what a shed took, held inside the tier each peer holds now.
- commands: Mapping[str, CommandSpec] = {'show': {'args': {}, 'does': 'the declared total, the pressure on it, the rungs engaged and the largest window carried', 'reply': '{declared, total, pressure, binding, rungs, held, since, measured, peak, suggested, note}', 'subsystem': 'capacity'}}
3.1.2.4. Network Trouble Reporter Compartment
The Reporter subsystem itself: construction and restore, what survives a restart, and the Compartment contract. Separate from the mixins because this is where the state they all share is created; the mixins are the concerns that act on it.
- class fleetmesh_node.planes.peering.reporter.core.ReporterConfig[source]
Bases:
ParamBlockReporterConfig(DERIVED: ‘bool’ = False, report_ttl: ‘int’ = 2592000, finding_windows: ‘int’ = 168, publish_tries: ‘int’ = 3)
- name = 'reporter'
- PARAMS: tuple[Parameter[Any], ...] = (Parameter(key='report_ttl', name='Report TTL', description='Time-to-live in seconds for signed reports', type=<class 'int'>, default=2592000, must='', tags=('reporter', 'retention'), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=86400, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='finding_windows', name='Finding Windows Horizon', description='Window horizon for substantiated findings', type=<class 'int'>, default=168, must='', tags=('reporter', 'history'), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=1, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='publish_tries', name='Publish Tries', description='Maximum publish attempts before finding marked unpublishable', type=<class 'int'>, default=3, must='', tags=('reporter', 'publish'), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=1, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True))
- class fleetmesh_node.planes.peering.reporter.core.Reporter[source]
Bases:
FindingsMixin,PublishMixin,ReadingMixin,WireProtocolFindings on their way to a report, as a compartment.
Its refusals are complaint and standing messages without the shape of their type, which were kept in a list nothing rendered. Its trouble is the one an operator most needs and would otherwise never see: a finding this node holds and cannot publish, because the subject signed nothing that window and active silence is unreportable by design.
- piuris: tuple[str, ...] = ('https://fleetmesh.org/complaint/1.0', 'https://fleetmesh.org/standing/1.0')
- config_cls
alias of
ReporterConfig
- CHANNELS: tuple[Any, ...] = (Channel(name='report_published', description='A signed report was published to relays', level='note', wire=None, say='published report {report_id} on peer {peer}', tags=('reporter', 'publish')), Channel(name='report_withdrawn', description='A finding or report was withdrawn by operator', level='note', wire=None, say='withdrew report on peer {peer} window {window}', tags=('reporter', 'withdraw')), Channel(name='finding_unpublishable', description='An adverse finding could not be published to relays', level='trouble', wire=None, say='finding on peer {peer} window {window} unpublishable: {reason}', tags=('reporter', 'trouble')))
- METRICS: tuple[Any, ...] = (Metric(name='reporter_reports_published', description='Reports published.', kind='counter', unit='', labels=(), counts='report_published', sample=None, buckets=(), tags=('reporter', 'publish')), Metric(name='reporter_reports_withdrawn', description='Reports withdrawn.', kind='counter', unit='', labels=(), counts='report_withdrawn', sample=None, buckets=(), tags=('reporter', 'withdraw')), Metric(name='reporter_findings_unpublishable', description='Findings unpublishable.', kind='counter', unit='', labels=(), counts='finding_unpublishable', sample=None, buckets=(), tags=('reporter', 'trouble')))
- OUTBOUND: tuple[Outbound, ...] = (Outbound('notice', reply=('remedy',)), Outbound('remedy'), Outbound('withdraw'), Outbound('ask', reply=('tell', 'decline')), Outbound('tell'), Outbound('decline'))
- HANDLERS: tuple[Handler, ...] = (Handler(kind='notice', run='handle_notice', schema=None, doc='answer complaint notice', exact=False, reads=(), writes=()), Handler(kind='remedy', run='handle_remedy', schema=None, doc='receive complaint remedy', exact=False, reads=(), writes=()), Handler(kind='withdraw', run='handle_withdraw', schema=None, doc='receive complaint withdrawal', exact=False, reads=(), writes=()), Handler(kind='ask', run='handle_ask', schema=None, doc='answer standing ask from ledger', exact=False, reads=(), writes=()), Handler(kind='*', run='handle_unknown', schema=None, doc='ignore unknown complaint or standing kind by name', exact=False, reads=(), writes=()))
- COMMANDS: tuple[Any, ...] = (Command(key='show', name='Reporter Status', description='findings held, reports published, and what cannot be published at all', tags=('reporter', 'status'), parameters=(), permission='reporter/show', process=(), run='state', reply='{pending, published, withdrawn, unpublishable, noticed, malformed}', reads=(), writes=()), Command(key='withdraw', name='Withdraw Finding', description="withdraw a finding this node made about one window, published or not; the operator's call", tags=('reporter', 'withdraw'), parameters=(Parameter(key='peer', name='peer', description='peer pubkey or did', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='window', name='window', description='window number', type=<class 'int'>, default=0, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='why', name='why', description='reason for withdrawal', type=<class 'str'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='reporter/withdraw', process=(), run='withdraw_cmd', reply='{peer, window, was_published, report, why}', reads=(), writes=()))
- STORES: tuple[Store, ...] = (Store(key='published', description='kind 30802 reports this node signed, newest last', kind='ring', shape=<class 'dict'>, bound=256, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='projected', description='kind 30385 relay scores this node signed, newest last', kind='ring', shape=<class 'dict'>, bound=256, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='labeled', description='kind 1985 labels this node signed, newest last', kind='ring', shape=<class 'dict'>, bound=256, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='unpublishable', description='findings it may not publish, as (peer, window, severity, reasons)', kind='ring', shape=<class 'tuple'>, bound=200, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='notices_in', description='complaint notices received, where this node is the subject', kind='table', shape=<class 'dict'>, bound=1000, evict='oldest', keyed_by='thid', persist='memory', sensitive=False, tags=()), Store(key='remedies_in', description='remedies received, where this node is the issuer', kind='table', shape=<class 'dict'>, bound=1000, evict='oldest', keyed_by='thid', persist='memory', sensitive=False, tags=()), Store(key='log', description='withdrawals against this node and tiers it restored, newest last', kind='ring', shape=<class 'tuple'>, bound=500, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()))
- NEEDS: tuple[Any, ...] = (Need(key='keystore', source='ks', block=None, late=False, getter=False, path=None, field=None), Need(key='transport', source='transport', block=None, late=False, getter=False, path=None, field=None), Need(key='grant_store', source='stores.grants', block=None, late=False, getter=False, path=None, field=None), Need(key='relay_urls', source='relays', block=None, late=False, getter=False, path=None, field=None), Need(key='ledger', source='ledger', block=None, late=False, getter=False, path=None, field=None), Need(key='project', source='cfg', block=None, late=False, getter=False, path=None, field='projection'), Need(key='timeout', source='timeout', block=None, late=False, getter=False, path=None, field=None), Need(key='accounts', source='stores.accounts', block=None, late=False, getter=False, path=None, field=None), Need(key='regrant', source='regrant', block=None, late=False, getter=False, path=None, field=None), Need(key='events', source='events', block=None, late=False, getter=False, path=None, field=None), Need(key='discovery', source='discovery', block=None, late=True, getter=False, path=None, field=None), Need(key='budget', source='budget', block=None, late=True, getter=False, path=None, field=None))
- __init__(keystore, transport, grant_store, relay_urls, ledger=None, clock=None, timeout=15.0, node=None, project=True, accounts=None, regrant=None, events=None, discovery=None, budget=None)[source]
- projected: Ring[NostrEvent]
- labeled: Ring[NostrEvent]
- grants: GrantStore
- published: Ring[NostrEvent]
- notices_in: Table[str, ComplaintNoticeBody]
- remedies_in: Table[str, ComplaintRemedyBody]
- commands: Mapping[str, CommandSpec] = {'show': {'args': {}, 'does': 'findings held, reports published, and what cannot be published at all', 'reply': '{pending, published, withdrawn, unpublishable, noticed, malformed}', 'subsystem': 'reporter'}, 'withdraw': {'args': {'peer': 'required', 'why': 'optional', 'window': 'required'}, 'does': "withdraw a finding this node made about one window, published or not; the operator's call", 'reply': '{peer, window, was_published, report, why}', 'subsystem': 'reporter'}}
- state()[source]
What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.
- Return type:
ReporterStateReport
3.1.2.5. Strain Monitor Compartment
What this node has survived, and the reserves it sets.
fleetmesh_core/strain.py is the arithmetic and states why this is safe to act on. This is the part that records and remembers.
Everything here was already being thrown away. A restart, a peer that went quiet mid-session, a relay that dropped its subscription, a clock that drifted past tolerance - the node correctly refuses to make any of them a finding about a peer, and then discards them, so the information goes out with the accusation.
Nothing recorded here crosses the wire and nothing here is a finding. What it does is thicken what this node holds in hand: how long it keeps accounting a vanished peer might still need, and how long it goes on trying a door that was closed. A node that has weathered a thing becomes better prepared for that thing, which is the only kind of adaptation an attacker gains nothing by provoking.
- class fleetmesh_node.planes.peering.strain.compartment.StrainConfig[source]
Bases:
ParamBlockStrainConfig(DERIVED: ‘bool’ = False, max_directions: ‘int’ = 4096)
- name = 'strain'
- PARAMS: tuple[Parameter[Any], ...] = (Parameter(key='max_directions', name='Max Directions', description='Maximum directions tracked in strain ledger', type=<class 'int'>, default=4096, must='', tags=('strain', 'reserves'), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),)
- class fleetmesh_node.planes.peering.strain.compartment.StrainLedger[source]
Bases:
CompartmentWhat this node has survived, as a compartment the operator can watch.
It reads no config and changes nothing about any peer: what it holds is the node’s own reserves. Its trouble is the flag tree - a node whose strain is nearly all one direction is structurally dependent on that peer and will snap when it leaves, and nothing else in the protocol says so.
- config_cls
alias of
StrainConfig
- CHANNELS: tuple[Any, ...] = (Channel(name='strain_recorded', description='Strain event recorded in ledger', level='note', wire=None, say='strain event {kind} recorded', tags=('strain', 'reserves')),)
- METRICS: tuple[Any, ...] = (Metric(name='strain_events_recorded', description='Times strain events were recorded.', kind='counter', unit='', labels=(), counts='strain_recorded', sample=None, buckets=(), tags=('strain', 'reserves')),)
- NEEDS: tuple[Any, ...] = (Need(key='accounts', source='stores.accounts', block=None, late=False, getter=False, path=None, field=None), Need(key='ledger', source='ledger', block=None, late=False, getter=False, path=None, field=None))
- COMMANDS: tuple[Any, ...] = (Command(key='show', name='Strain', description='what this node has survived, by direction, and the reserves it sets', tags=('strain', 'status'), parameters=(), permission='strain/show', process=(), run='state', reply='{kinds, directions, weighted_directions, reserve_multiple, dominant_share, flag_tree}', reads=(), writes=()),)
- STORES: tuple[Store, ...] = (Store(key='counts', description='strain counts per direction and kind', kind='table', shape=<class 'dict'>, bound=4096, evict='lru', keyed_by='direction', persist='memory', sensitive=False, tags=()), Store(key='last', description='strain last timestamp per direction and kind', kind='table', shape=<class 'dict'>, bound=4096, evict='lru', keyed_by='direction', persist='memory', sensitive=False, tags=()))
- record(kind, peer=None, shard=None, transport=None, at=None, n=1)[source]
One thing survived. Silently ignores a kind the digest does not name, so a caller cannot invent a category that no reserve reads.
- by_direction(kind=None)[source]
direction -> how much stress came from it. Magnitude is collected here and deliberately thrown away by ref_strain.weigh, which caps each direction: one peer moves this node by at most one direction’s worth.
- trouble()[source]
What an operator should be told without having to ask for it.
Everything here is WRONG: a watcher reds on it and a deploy fails on it. Something worth reading that is not a fault goes in notes(). May return a list of strings or typed Trouble instances.
- notes()[source]
What an operator would want to read, that is not a fault.
A relay cooling after a rate-limit, a peer that announced it is leaving: the node behaving, and the reason a quiet mesh is quiet. Kept apart from trouble() so no reader has to classify prose. May return a list of strings or typed Note instances.
- commands: Mapping[str, CommandSpec] = {'show': {'args': {}, 'does': 'what this node has survived, by direction, and the reserves it sets', 'reply': '{kinds, directions, weighted_directions, reserve_multiple, dominant_share, flag_tree}', 'subsystem': 'strain'}}
3.1.2.6. Trust & Reputation Compartment
The operator’s own decisions about peers, carried out once each.
A tier is only ever raised by a person. The ladder earns standing with observed time; the specification says an operator MAY seed a tier for a node it knows out of band, recorded as a signed event and reversible. meshnode trust writes that decision to the config file and this compartment is what acts on it.
It ran inside the node’s tick before, which meant a seed that could not be applied - no peering yet, or a regrant that came back empty - was skipped in silence. An operator who had written a decision and watched nothing happen had no way to ask why. Every skip is a refusal here.
- fleetmesh_node.planes.peering.trust.compartment.decision(entry)[source]
A trust entry is {‘tier’: t, ‘at’: unix} - or, from before decisions were dated, the bare tier, which counts as decided at time zero.
- fleetmesh_node.planes.peering.trust.compartment.tiers(trust)[source]
The policy’s view: peer -> tier.
- class fleetmesh_node.planes.peering.trust.compartment.TrustConfig[source]
Bases:
ParamBlockTrustConfig(DERIVED: ‘bool’ = False, max_decisions: ‘int’ = 4096)
- name = 'trust'
- PARAMS: tuple[Parameter[Any], ...] = (Parameter(key='max_decisions', name='Max Decisions', description='Maximum trust decisions remembered', type=<class 'int'>, default=4096, must='', tags=('trust', 'policy'), required=False, choices=(), verify_regex='', live=True, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),)
- class fleetmesh_node.planes.peering.trust.compartment.Trust[source]
Bases:
Compartment- config_cls
alias of
TrustConfig
- CHANNELS: tuple[Any, ...] = (Channel(name='trust_applied', description='Trust decision applied for peer', level='note', wire=None, say='trust decision applied for peer {peer}', tags=('trust', 'policy')), Channel(name='trust_refused', description='Trust decision refused for peer', level='trouble', wire=None, say='trust decision refused for peer {peer}: {reason}', tags=('trust', 'policy')))
- METRICS: tuple[Any, ...] = (Metric(name='trust_decisions_applied', description='Times trust decisions were applied.', kind='counter', unit='', labels=(), counts='trust_applied', sample=None, buckets=(), tags=('trust', 'policy')), Metric(name='trust_decisions_refused', description='Times trust decisions were refused.', kind='counter', unit='', labels=(), counts='trust_refused', sample=None, buckets=(), tags=('trust', 'policy')))
- NEEDS: tuple[Any, ...] = (Need(key='grant_store', source='stores.grants', block=None, late=False, getter=False, path=None, field=None), Need(key='policy', source='policy', block=None, late=False, getter=False, path=None, field=None), Need(key='regrant', source='regrant', block=None, late=False, getter=False, path=None, field=None))
- COMMANDS: tuple[Any, ...] = (Command(key='show', name='Trust', description='the decisions this operator has made, and which of them are still in force: carried out is not the same as true, and the ladder can move a seeded peer', tags=('trust', 'status'), parameters=(), permission='trust/show', process=(), run='state', reply='{decided, in_force, pending, overridden, waiting}', reads=(), writes=()),)
- STORES: tuple[Store, ...] = (Store(key='_said', description='refused decisions said once, per peer', kind='table', shape=<class 'tuple'>, bound=4096, evict='lru', keyed_by='peer', persist='memory', sensitive=False, tags=()),)
- grants: GrantStore
- tick(now)[source]
Carry out each dated decision in the config once.
A decision is compared with the record of decisions applied, kept beside the grants, and not with the grant’s tier: comparing tiers made the seed re-issue trusted on the tick after every demotion the ladder earned, so the ladder never held and every re-issue was one more amend. A decision written while the node was down is still found on the first tick back, because the record is on disk too. Applying a seed also drops any grant the ladder had waiting for the boundary: the operator’s word is the later one.
- standing()[source]
Each decision, and what has become of it.
Three states, not two. applied used to mean “this dated decision was carried out at some point”, and an operator read it as “the tier I chose is the tier in force”. Those diverge the moment the ladder demotes a seeded peer: the seed is recorded as applied, this compartment correctly declines to re-issue it - re-issuing on every demotion is what made the ladder never hold, and the dated record is the fix for that - and the operator’s decision quietly stops being true.
Seen on the mesh. A node seeded trusted was demoted to probation in a run of S1 windows, and twelve hours later trust still said applied: 1, waiting: [] while every window ran under a probation ceiling the operator had never chosen. Nothing was wrong with the mechanism. The report was answering a different question from the one being asked of it.
waiting decided, not carried out yet pending carried out, and published at the next window boundary in force carried out, and the grant says so overridden carried out, and the ladder has since moved it
Only the last needs a person, which is why only the last is trouble. pending exists because a decision no longer lands the moment it is made: publishing a grant inside a running window breaks the subject’s receipt chain for the rest of it, so every decision waits for the boundary. Without this state, the hour between deciding and landing would read as overridden and shout for a person who need do nothing.
- Return type:
list[TrustStandingRow]
- state()[source]
What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.
- Return type:
TrustStateReport
- trouble()[source]
A decision waiting on a peering that does not exist yet is not trouble - it is what a seed written before the peering looks like, and the policy will apply it to the next handshake. A decision that reached a live peering and could not be written is. So is one the ladder has since overridden, because that one looks applied and is not in force, and only a person can decide which of the two answers should stand.
- commands: Mapping[str, CommandSpec] = {'show': {'args': {}, 'does': 'the decisions this operator has made, and which of them are still in force: carried out is not the same as true, and the ladder can move a seeded peer', 'reply': '{decided, in_force, pending, overridden, waiting}', 'subsystem': 'trust'}}