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, WireProtocol

The 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.

name: str = 'peering'
reads: tuple[str, ...] = ('policy',)
config_cls

alias of PolicyConfig

requires: tuple[str, ...] = ()
piuris: tuple[str, ...] = ('https://fleetmesh.org/peering/1.0',)
exact_types: tuple[str, ...] = ('https://didcomm.org/discover-features/2.0/queries',)
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

start()[source]

Everything that needs the rest of the node to exist already.

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:
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.

Parameters:

inbound (Any)

Return type:

tuple[Any, …] | None

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.

Parameters:

now (int | None)

Return type:

list[tuple[Any, …]]

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.

Parameters:
Return type:

Issued

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.

Parameters:
Return type:

PeeringDecision

tick(now)[source]

Periodic work. Runs due EVERY jobs when not overridden.

Parameters:

now (int)

Return type:

list[tuple[Any, …]]

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.

Return type:

list[str]

abstract: ClassVar[bool] = False
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'}}
live: tuple[str, ...] = ()

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: ParamBlock

BudgetConfig(DERIVED: ‘bool’ = False, tolerance: ‘float’ = 0.1, keep_windows: ‘int’ = 168, keep_findings: ‘int’ = 1000)

key: ClassVar[str] = 'budget'
name = 'budget'
DERIVED: bool = False
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))
tolerance: float = 0.1
keep_windows: int = 168
keep_findings: int = 1000
__init__(DERIVED=False, tolerance=0.1, keep_windows=168, keep_findings=1000)
Parameters:
Return type:

None

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.

name: str = 'budget'
piuris: tuple[str, ...] = ('https://fleetmesh.org/budget/1.0',)
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=()),)
KEEP_WINDOWS: int = 168
evaluations: Ring[Evaluation]
findings: Ring[tuple[Any, ...]]
clock_drift: Ring[tuple[Any, ...]]
receipt_gaps: Ring[tuple[Any, ...]]
unpublished: Ring[tuple[Any, ...]]
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))
start()[source]

Everything that needs the rest of the node to exist already.

Return type:

None

__init__(keystore, transport, grant_store, peering, clock=None, ledger=None, accounts=None, strain=None, node=None, events=None, reporter=None)[source]
Parameters:
Return type:

None

strain: Any | None
accounts: Any | None
events: Any | None
reporter: Any | None
ks: Any
transport: Any
grants: GrantStore
peering: Any
ledger: Ledger
usage_by: dict[str, dict[int, Meter]]
usage_of_me: dict[str, dict[int, Meter]]
receipts_in: dict[str, dict[int, list[ReceiptBody]]]
heads_in: dict[str, dict[int, str]]
chain_out: dict[str, dict[int, OutChain]]
acks: dict[str, Mapping[str, Any]]
evaluated: set[tuple[str, int]]
zero_until: dict[str, int]
idle: dict[str, int]
started: int
ack_lag: dict[str, tuple[int, int, int]]
ack_head: dict[str, tuple[int, int]]
on_evaluated: list[Callable[[Evaluation], Any]]
reopen: set[tuple[str, int]]
repriced: list[Repricing]
on_repriced: list[Callable[[str, int, str, str], Any]]
WINDOW_MEMO_SECONDS: float = 2.0
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:
  • peer (str)

  • direction (Literal['issued', 'received'])

  • epoch (int)

Return type:

GoverningRow | None

epoch(peer, direction, at=None)[source]
Parameters:
  • peer (str)

  • direction (Literal['issued', 'received'])

  • at (int | None)

Return type:

int

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”.

Parameters:

at (int | None)

Return type:

dict[str, int]

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.

Parameters:
Return type:

None

observe_in(peer, message, i_initiated=False)[source]

A sync message the peer sent me.

Parameters:
Return type:

None

observe_out(peer, message, i_initiated=True)[source]

A sync message I sent the peer.

Parameters:
Return type:

None

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.

Parameters:
Return type:

None

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:

list[ReceiptRefusedRow]

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.

Return type:

list[str]

stop()[source]

Say what this node used before it goes. Never raises.

Return type:

list[tuple[Any, …]]

abstract: ClassVar[bool] = False
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'}}
live: tuple[str, ...] = ()
run(stop, interval=5.0)[source]
Parameters:
Return type:

None

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.

name: str = 'capacity'
reads: tuple[str, ...] = ('capacity',)
config_cls

alias of CapacityConfig

live: tuple[str, ...] = ('capacity',)
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)
__init__(budget, total=None, clock=None, node=None, grants=None, amend=None)[source]
Parameters:
Return type:

None

set_total(total)[source]

Take up a new declaration. Returns True if it changed.

Parameters:

total (Mapping[str, Any] | None)

Return type:

bool

declared()[source]
Return type:

bool

measure(now=None)[source]

The open window, summed across every peer. See Budget.aggregate.

Parameters:

now (int | None)

Return type:

dict[str, int]

pressure(now=None)[source]
Parameters:

now (int | None)

Return type:

tuple[float, str | None]

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.

Parameters:

now (int | None)

Return type:

list[tuple[str, str]]

refusing()[source]
Return type:

bool

narrowing()[source]
Return type:

bool

amending()[source]
Return type:

bool

leafing()[source]
Return type:

bool

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:

str

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.

Parameters:
Return type:

bool

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.

Parameters:
Return type:

Mapping[str, Any] | None

forget(peer)[source]
Parameters:

peer (str)

Return type:

None

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.

Parameters:

now (int)

Return type:

list[tuple[Any, …]]

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.

Return type:

list[str]

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.

Parameters:

peer (str)

Return type:

str

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.

Parameters:

now (int | None)

Return type:

list[tuple[Any, …]]

restore_grants(now=None)[source]

Give back what a shed took, held inside the tier each peer holds now.

Parameters:

now (int | None)

Return type:

list[tuple[Any, …]]

show()[source]
Return type:

Mapping[str, Any]

suggested()[source]
Return type:

Mapping[str, Any]

abstract: ClassVar[bool] = False
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'}}
state(now=None)[source]

What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.

Parameters:

now (int | None)

Return type:

CapacityStateReport

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: ParamBlock

ReporterConfig(DERIVED: ‘bool’ = False, report_ttl: ‘int’ = 2592000, finding_windows: ‘int’ = 168, publish_tries: ‘int’ = 3)

key: ClassVar[str] = 'reporter'
name = 'reporter'
DERIVED: bool = False
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))
report_ttl: int = 2592000
finding_windows: int = 168
publish_tries: int = 3
__init__(DERIVED=False, report_ttl=2592000, finding_windows=168, publish_tries=3)
Parameters:
  • DERIVED (bool)

  • report_ttl (int)

  • finding_windows (int)

  • publish_tries (int)

Return type:

None

class fleetmesh_node.planes.peering.reporter.core.Reporter[source]

Bases: FindingsMixin, PublishMixin, ReadingMixin, WireProtocol

Findings 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.

name: str = 'reporter'
piuris: tuple[str, ...] = ('https://fleetmesh.org/complaint/1.0', 'https://fleetmesh.org/standing/1.0')
reads: tuple[str, ...] = ('projection',)
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))
start()[source]

Everything that needs the rest of the node to exist already.

Return type:

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]
Parameters:
Return type:

None

regrant: Callable[[str, str, int], Any] | None
ks: Any
accounts: Any | None
project: bool
projected: Ring[NostrEvent]
labeled: Ring[NostrEvent]
transport: Any
grants: GrantStore
relays: list[str]
ledger: Ledger
events: Any | None
discovery: Any | None
budget: Any | None
timeout: float
published: Ring[NostrEvent]
unpublishable: Ring[tuple[str, int, str, list[str]]]
notices_in: Table[str, ComplaintNoticeBody]
remedies_in: Table[str, ComplaintRemedyBody]
log: Ring[tuple[Any, ...]]
abstract: ClassVar[bool] = False
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'}}
live: tuple[str, ...] = ()
on_report_read: list[Callable[[str, str, str, bool, bool], Any]]
pending: list[Finding]
property forward_clock: Callable[[str, int], int] | None
property rejected: list[tuple[str | None, str, str]]
state()[source]

What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.

Return type:

ReporterStateReport

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.

Return type:

list[str]

withdraw_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Any

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: ParamBlock

StrainConfig(DERIVED: ‘bool’ = False, max_directions: ‘int’ = 4096)

key: ClassVar[str] = 'strain'
name = 'strain'
DERIVED: bool = False
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),)
max_directions: int = 4096
__init__(DERIVED=False, max_directions=4096)
Parameters:
  • DERIVED (bool)

  • max_directions (int)

Return type:

None

class fleetmesh_node.planes.peering.strain.compartment.StrainLedger[source]

Bases: Compartment

What 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.

name: str = 'strain'
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=()))
__init__(accounts=None, clock=None, tier_of=None, node=None, ledger=None)[source]
Parameters:
Return type:

None

accounts: Any | None
tier_of: Callable[[str], str]
counts: Table[tuple[str, str, str], dict[str, int]]
last: Table[tuple[str, str, str], dict[str, int]]
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.

Parameters:
  • kind (str)

  • peer (str | None)

  • shard (str | None)

  • transport (str | None)

  • at (int | None)

  • n (int)

Return type:

tuple[str, str, str] | None

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.

Parameters:

kind (str | None)

Return type:

dict[tuple[str, str, str], int]

weight(kind=None)[source]
Parameters:

kind (str | None)

Return type:

float

multiple(kind=None)[source]
Parameters:

kind (str | None)

Return type:

float

reserve(base, kind=None)[source]
Parameters:
Return type:

float

tick(now)[source]

Periodic work. Runs due EVERY jobs when not overridden.

Parameters:

now (int)

Return type:

list[tuple[Any, …]]

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.

Return type:

list[str]

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.

Return type:

list[str]

flag_tree()[source]
Return type:

FlagTreeReport

abstract: ClassVar[bool] = False
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'}}
live: tuple[str, ...] = ()
state()[source]

What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.

Return type:

StrainStateReport

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.

Parameters:

entry (Any)

Return type:

tuple[str, int]

fleetmesh_node.planes.peering.trust.compartment.tiers(trust)[source]

The policy’s view: peer -> tier.

Parameters:

trust (Mapping[str, Any] | None)

Return type:

dict[str, str]

class fleetmesh_node.planes.peering.trust.compartment.TrustConfig[source]

Bases: ParamBlock

TrustConfig(DERIVED: ‘bool’ = False, max_decisions: ‘int’ = 4096)

key: ClassVar[str] = 'trust'
name = 'trust'
DERIVED: bool = False
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),)
max_decisions: int = 4096
__init__(DERIVED=False, max_decisions=4096)
Parameters:
  • DERIVED (bool)

  • max_decisions (int)

Return type:

None

class fleetmesh_node.planes.peering.trust.compartment.Trust[source]

Bases: Compartment

name: str = 'trust'
reads: tuple[str, ...] = ('trust',)
live: tuple[str, ...] = ('trust',)
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=()),)
__init__(grant_store, policy, regrant, clock=None, node=None)[source]
Parameters:
Return type:

None

grants: GrantStore
policy: Any
regrant: Callable[[str, str, int], Any]
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.

Parameters:

now (int)

Return type:

list[tuple[Any, …]]

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.

Return type:

list[str]

abstract: ClassVar[bool] = False
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'}}