fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/peering/budget/meter.py

@@ -0,0 +1,100 @@
+"""The constants of budget/1.0 and the metering primitives: what one message
+costs and which side owes it. Separate because it holds no node state - every
+other module in the package charges through these and the tests read them
+directly.
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from fleetmesh_core.accounting import accounting, window
+from fleetmesh_core.storage import negentropy, sync
+
+# Lists that grew for as long as the node ran. Findings feed the reporter and
+# the tests read them, so they stay lists, trimmed on the tick.
+KEEP_FINDINGS: int = 1000
+
+PIURI: str = 'https://fleetmesh.org/budget/1.0'
+AMEND: str = 'https://fleetmesh.org/peering/1.0/amend'
+SYNC: str = sync.PIURI
+ZERO: str = accounting.ZERO
+C: Mapping[str, Any] = window.C['grant']
+TOLERANCE: float = C['divergence_tolerance']
+
+
+class Meter:
+    def __init__(self) -> None:
+        self.c: dict[str, int] = dict.fromkeys(sync.COUNTERS, 0)
+
+    def add(self, name: str, n: int = 1) -> None:
+        self.c[name] = self.c.get(name, 0) + n
+
+    def snapshot(self) -> dict[str, int]:
+        return {k: v for k, v in self.c.items() if v}
+
+
+def _ranges(frame_hex: str) -> int:
+    try:
+        return len(negentropy.decode_message(bytes.fromhex(frame_hex)))
+    except Exception:
+        return 0
+
+
+METERED: tuple[str, ...] = ('id', 'type', 'thid', 'body', 'attachments')
+
+
+def metered_bytes(message: Mapping[str, Any]) -> int:
+    """What both sides charge for one message: the parts the protocol wrote.
+    Addressing and created_time are added by the transport on the way out and
+    would make the sender's count differ from the receiver's."""
+    return sync.wire_bytes({k: v for k, v in message.items() if k in METERED})
+
+
+def _observe(session_meter: Meter, deliverer_meter: Meter, message: Mapping[str, Any],
+             from_initiator: bool) -> None:
+    """Charge one sync/1.0 message: the session to its initiator, the events
+    to whoever delivered them.
+
+    Two different things cross in a sync session and they are owed to
+    different sides. Opening it, asking, reconciling, and the bytes both ways
+    are the SESSION, and a session is paid for by whoever opened it, under
+    the grant the other side issued - sync_wire's docstring says so and the
+    reference Session binds each side to exactly that grant. Events are
+    different: an event is pushed into the receiver by whoever sent it,
+    whichever side opened the session, and `events_in` is the receiver's
+    limit on exactly that. The receiver prices duplicates against the
+    deliverer for the same reason, and `observe_session` already does.
+
+    This used to charge whoever SENT each message and then mirror the bytes
+    onto the other side's meter. On a symmetric peering the phantom that
+    produced appeared identically in the issuer's measurement and the
+    subject's claim - both sides run this code - so the two errors cancelled
+    and nobody saw it for a week. The first asymmetric peering exposed it:
+    New York pulled from a newcomer that never pulled back, booked the bytes
+    it RECEIVED as the newcomer's consumption of New York's grant, and when
+    the newcomer sent no receipt - it had delivered nothing into a converged
+    shard and had nothing to claim - priced that as active silence. Fifty
+    windows of S2 against a stranger's node on its first contact with the
+    mesh, for answering.
+    """
+    wb = metered_bytes(message)
+    kind = message.get('type', '').rsplit('/', 1)[1]
+    body = message.get('body', {})
+    # The session, to its initiator. Direction is relative to the responder,
+    # because that is what the grant's limits name.
+    session_meter.add('bytes_in' if from_initiator else 'bytes_out', wb)
+    if from_initiator:
+        if kind == 'open':
+            session_meter.add('conn_open')
+            session_meter.add('req')
+            session_meter.add('sync_ranges', _ranges(body.get('initial_frame', '')))
+        elif kind == 'need':
+            session_meter.add('req')
+        elif kind == 'range':
+            session_meter.add('sync_ranges', _ranges(body.get('frame', '')))
+    elif kind == 'range':
+        # A reconciliation's frames go both ways and are one cost.
+        session_meter.add('sync_ranges', _ranges(body.get('frame', '')))
+    # The events, to whoever pushed them.
+    if kind == 'deliver':
+        deliverer_meter.add('events_in', sync.delivered(dict(message)))

node/planes/peering/budget/receipts.py

@@ -0,0 +1,439 @@
+"""The receipt chain, both ends: this node as subject writing receipts and
+the farewell, and as issuer reading receipts, closes and acks off the wire.
+Separate because it is the whole of what budget/1.0 puts on the wire; the
+pricing of a window is windows.py.
+"""
+from __future__ import annotations
+
+import secrets
+from typing import Any, Mapping, Optional
+
+from fleetmesh_core.accounting import accounting, window
+from fleetmesh_core.wire.interfaces import ReceiptBody
+from fleetmesh_core.wire.wire_types import BudgetBody, BudgetCloseBody, BudgetReceiptAckBody, Message, ReceiptAckStatus
+from fleetmesh_core.wire import validate
+from fleetmesh_core.identity.did import did_nostr
+from node.storage import accounts as accounts_mod, grants as grants_mod
+from .chain import OutChain
+from .meter import C, PIURI, ZERO
+from .shape import BudgetShape
+
+
+class ReceiptsMixin:
+    # ---- subject: receipts out -------------------------------------------------
+    def _msg(self: BudgetShape, kind: str, body: BudgetBody, peer: str, piuri: str = PIURI) -> Message[BudgetBody]:
+        msg: Message[BudgetBody] = {
+            'id': 'budget-%s-%s' % (kind, secrets.token_hex(4)),
+            'type': '%s/%s' % (piuri, kind),
+            'from': self.ks.did,
+            'to': [did_nostr(peer)],
+            'body': body,
+        }
+        return msg
+
+    def receipt_due(self: BudgetShape, peer: str, now: int) -> bool:
+        row = self.grants.get(peer, grants_mod.RECEIVED)
+        if row is None or row['status'] != 'live':
+            return False
+        cadence = (row['payload'].get('receipt') or [600])[0]
+        epoch = self.epoch(peer, grants_mod.RECEIVED, now)
+        state = self.chain_out.get(peer, {}).get(epoch)
+        claim = self._meter(self.usage_of_me, peer, epoch).snapshot()
+        if not claim:
+            return False
+        if state is None:
+            return True
+        return state.sent_at is not None and (now - state.sent_at >= cadence) and (claim != state.last)
+
+    def send_receipt(
+        self: BudgetShape,
+        peer: str,
+        now: Optional[int] = None,
+        final: bool = False,
+        epoch: Optional[int] = None,
+    ) -> tuple[ReceiptBody, str]:
+        now_val = now if now is not None else self.clock()
+        row = self.grants.get(peer, grants_mod.RECEIVED)
+        assert row is not None
+        epoch_val = self.epoch(peer, grants_mod.RECEIVED, now_val) if epoch is None else epoch
+        # The grant a receipt names is the one that governed its window. The
+        # chain is per window and is never restarted because the grant changed:
+        # that restart, met by an issuer expecting seq N, was an S2 misreport
+        # filed against an honest node every time a window was amended.
+        governing = self.governing(peer, grants_mod.RECEIVED, epoch_val) or row
+        with self._lock:
+            state = self.chain_out.setdefault(peer, {}).setdefault(epoch_val, OutChain(grant=governing['envelope_id']))
+            state.grant = governing['envelope_id']
+            counters = self._meter(self.usage_of_me, peer, epoch_val).snapshot()
+            body = accounting.sign_receipt(
+                ReceiptBody(grant=governing['envelope_id'], window=epoch_val, seq=state.seq,
+                            prev=state.prev, counters=counters, at=now_val), self.ks.node_sk)
+            head = accounting.link(body)
+            # The heads this node produced, in sequence order. An ack carries
+            # the head the receiver holds, and without our own list that number
+            # is unreadable - it has been arriving on every ack since the
+            # protocol was written and being thrown away. With the list it says
+            # exactly how many receipts behind the receiver is.
+            state.seq, state.prev, state.sent_at, state.last = state.seq + 1, head, now_val, counters
+            state.heads = state.heads + [head]
+            if self.accounts is not None:
+                # Before the message leaves, not after: a receipt this node has
+                # sent and does not remember sending is the whole bug.
+                self.accounts.put_chain(peer, epoch_val, state.to_dict())
+                self.accounts.put_meter(peer, epoch_val, accounts_mod.OF_ME, counters, now_val)
+        # A receipt is a live wrap, and the attempt to make it store-and-forward
+        # is written down here because the reason it failed is not in the code.
+        #
+        # The case for storing it stands: a receipt lost while a subscription is
+        # down is priced as active silence, S2, unpublishable, and on
+        # 2026-09-05 that took a peering apart in both directions for eleven
+        # windows. So it was moved to kind 1059 on 2026-09-06, like the close
+        # that follows it. Seventeen hours later every peering in the mesh was
+        # pricing every other S2 every window: `relay.pocketstr.com` ACCEPTS a
+        # kind 1059 - the publish returns OK and no drop is recorded - and does
+        # not deliver it to a live subscription. A probe put both kinds through
+        # the same relay to the same subscription; the 21059 arrived and the
+        # 1059 did not.
+        #
+        # So the sender cannot tell accepted from delivered, and the whole
+        # store-and-forward binding is only as real as the relays under it.
+        # Anything this protocol sends stored - a grant amendment, a complaint
+        # notice, a window close, a withdrawal - has the same hole on this
+        # deployment, and had it before this change: moving receipts onto that
+        # path is what made it visible. Fixing it properly is choosing relays
+        # that serve 1059, or re-sending on an ack that never comes, and it is
+        # not something to decide while the mesh cannot account.
+        if final:
+            close = BudgetCloseBody(grant=governing['envelope_id'], window=epoch_val, final_receipt_head=head, counters=counters)
+            sent = self.wire_client.send(peer, self._msg('receipt', body, peer))
+            self.wire_client.send(peer, self._msg('close', close, peer), stored=True)
+        else:
+            sent = self.wire_client.send(peer, self._msg('receipt', body, peer))
+        # The publish result was thrown away. It does not prove delivery - a
+        # relay that accepts a message and never serves it returns exactly this
+        # - but a receipt NO relay would take has certainly not arrived, and
+        # that was invisible too. Cheap, and it is the half of the question the
+        # sender can answer on its own.
+        if sent and not any(ok for ok, _note in sent.values()):
+            self.unpublished.append((peer, epoch_val, body['seq'], now_val))
+            self.refusals.refuse('receipt-out', 'no relay accepted the receipt', subject=peer, at=now_val,
+                                 detail={'window': epoch_val, 'seq': body['seq'],
+                                         'relays': {u: n for u, (_ok, n) in sent.items()}})
+        return body, head
+
+    def _ack_lag(self: BudgetShape, peer: str, body: Mapping[str, Any]) -> int:
+        """How many receipts behind the receiver is, from the ack it just sent.
+
+        Every ack carries the head of the chain the receiver holds. This node
+        holds the head of every receipt it produced, in order, so the two
+        together say exactly where the receiver has got to - and that number
+        has been on the wire since the protocol was written, unread. A relay
+        that accepts a receipt and never serves it looks identical to a
+        delivered one from the publish result; it does not look identical
+        here.
+
+        Zero when the receiver is level, or when the head is one this node
+        cannot place - a fresh window, a peer that restarted, an ack for a
+        window already forgotten. Not knowing is not the same as being behind,
+        and reporting a lag this node cannot substantiate is the mistake every
+        other diagnosis here has had to be corrected for. Caller holds the lock.
+        """
+        head = body.get('head')
+        if not isinstance(head, str):
+            return 0
+        for epoch in sorted(self.chain_out.get(peer, {}), reverse=True):
+            heads = self.chain_out[peer][epoch].heads
+            if not heads:
+                continue
+            if head not in heads:
+                continue
+            idx = heads.index(head)
+            furthest = self.ack_head.get(peer)
+            if furthest is not None and furthest[0] == epoch and furthest[1] > idx:
+                # An ack for an older head arriving after one for a newer:
+                # two receipts sent in the same second come back over
+                # different relays in either order. The peer has not gone
+                # backwards; this is the later-sent ack arriving late.
+                return 0
+            self.ack_head[peer] = (epoch, idx)
+            behind = len(heads) - 1 - idx
+            if behind:
+                self.ack_lag[peer] = (epoch, behind, self.clock())
+            else:
+                self.ack_lag.pop(peer, None)
+            return behind
+        return 0
+
+    def farewell(self: BudgetShape, now: Optional[int] = None) -> list[tuple[Any, ...]]:
+        """Say what this node used, to every peer, before it stops.
+
+        A node that vanished mid-window left its issuer with traffic measured
+        and no receipt, which is active silence: an S2 floor, and S2 drops the
+        tier to probation. A tier is only ever raised by a person, so the
+        upgrade this specification REQUIRES for a digest change - roll every
+        node in one pass or they decline to peer - cost every peering its seeded
+        tier, every time. Measured on the test mesh: one fleet restart, an S2 at
+        every peering, every streak back to zero, and an operator-seeded trusted
+        grant pending demotion.
+
+        It is the third layer at which an operator restart was being read as
+        dishonesty, after the session abort and the standing streak. The answer
+        is the same as it was there: say something rather than vanish. A receipt
+        for the open window is a claim, and an honest node's window then prices
+        on its own numbers.
+
+        Nothing here waits on an answer and nothing here may raise: a node that
+        could not say goodbye must still stop.
+        """
+        now_val = now if now is not None else self.clock()
+        did: list[tuple[Any, ...]] = []
+        for peer in self._peers():
+            try:
+                row = self.grants.get(peer, grants_mod.RECEIVED)
+                if row is None or row['status'] != 'live':
+                    continue
+                epoch = self.epoch(peer, grants_mod.RECEIVED, now_val)
+                if not self._meter(self.usage_of_me, peer, epoch).snapshot():
+                    continue          # nothing used this window; silence is honest
+                body, _head = self.send_receipt(peer, now_val)
+                did.append(('farewell receipt', peer, epoch, body['seq']))
+            except Exception as e:
+                did.append(('farewell failed', peer, '%s: %s' % (type(e).__name__, e)))
+        return did
+
+    def final_due(self: BudgetShape, peer: str, now: int) -> Optional[int]:
+        """The previous window closed and my last word on it is stale: say the
+        final word while the grace period is open. Traffic after the last
+        receipt is priced by divergence, so a node that syncs near the end of
+        a window and then only ticks in the next one would look like a liar."""
+        row = self.grants.get(peer, grants_mod.RECEIVED)
+        if row is None or row['status'] != 'live':
+            return None
+        w = row['payload'].get('window') or C['window_seconds_default']
+        prev = accounting.epoch(now, w) - 1
+        if now > accounting.window_bounds(prev, w)[1] + accounting.window_grace(w):
+            return None
+        meter = self.usage_of_me.get(peer, {}).get(prev)
+        if meter is None or not meter.snapshot():
+            return None
+        state = self.chain_out.get(peer, {}).get(prev)
+        if state is not None and (state.final or state.last == meter.snapshot()):
+            return None
+        return prev
+
+    # ---- issuer: receipts in ---------------------------------------------------
+    def on_receipt(self: BudgetShape, peer: str, body: Any, now: Optional[int] = None) -> Message[BudgetReceiptAckBody]:
+        now_val = now if now is not None else self.clock()
+        why = validate.check_body('budget', 'receipt', body)
+        if why is not None:
+            # Not a claim, not an offence: a receipt this node cannot read is
+            # answered so the subject learns at once, and counted, and that is all.
+            #
+            # The seq is echoed like every other refusal branch echoes it. This
+            # one answered 0 whatever it was sent, so a subject at seq 5 heard
+            # that seq 0 was divergent and could not tell which receipt the
+            # answer was about - an answer that identifies nothing, in the one
+            # branch whose whole purpose is to tell the subject at once. The
+            # ack body is {seq, head, status} and says nothing about why, so
+            # the reason lives in the refusal channel, where `meshnode
+            # refusals` reads it. A body that is not a mapping has no seq to
+            # echo and that is the one case that still answers 0.
+            self.refusals.refuse('receipt', why, subject=peer, at=now_val)
+            seq = body.get('seq') if isinstance(body, dict) else None
+            return self._msg('receipt-ack', BudgetReceiptAckBody(
+                seq=seq if isinstance(seq, int) and not isinstance(seq, bool) else 0,
+                head=ZERO, status='divergent'), peer)
+        row = self.grants.get(peer, grants_mod.ISSUED)
+        epoch = body['window']
+        # A receipt is a claim about a window this grant could be about. One
+        # naming a window that will never close is never evaluated and never
+        # forgotten - forget_before only drops what is older than the horizon -
+        # so a peer naming a fresh future window per message takes as much of
+        # this node's memory and disk as it cares to. One naming a window long
+        # past is answerable by nothing either. Neither is an offence: it is a
+        # claim nobody can be held to, so it is refused the way an unreadable
+        # receipt is, counted and not stored.
+        #
+        # The upper bound is the CURRENT window, not the next one. A receipt
+        # about a window that has not opened yet claims usage that has not
+        # happened, and the one extra epoch that used to be accepted was a
+        # whole window of storage a peer could fill ahead of time; clock skew
+        # is already absorbed by the fact that a receipt about the window that
+        # just closed remains acceptable for KEEP_WINDOWS more.
+        current = self.epoch(peer, grants_mod.ISSUED, now_val)
+        oldest = current - self.KEEP_WINDOWS
+        if not isinstance(epoch, int) or isinstance(epoch, bool) or not (oldest <= epoch <= current):
+            self.refusals.refuse('receipt', 'names a window this grant cannot be about',
+                                 subject=peer, at=now_val,
+                                 detail={'window': epoch, 'acceptable': [oldest, current]})
+            return self._msg('receipt-ack', BudgetReceiptAckBody(seq=body.get('seq', 0), head=ZERO, status='divergent'), peer)
+        # The one divergent branch that recorded no reason, and the one that
+        # fired. Every receipt on a four-node mesh was refused here for an hour
+        # while budget_rejected stayed empty, so an operator saw an S2 a window
+        # with no claim earns and nothing at all about why the claim was
+        # refused. A refusal that is not counted is indistinguishable from
+        # silence, which is the thing this protocol is least able to afford.
+        if row is None:
+            self.refusals.refuse('receipt', 'no grant issued to this peer', subject=peer, at=now_val)
+            return self._msg('receipt-ack', BudgetReceiptAckBody(seq=body['seq'], head=ZERO, status='divergent'), peer)
+        acceptable = self._acceptable_grants(peer, epoch)
+        if body['grant'] not in acceptable:
+            self.refusals.refuse('receipt', 'names a grant that did not govern that window',
+                                 subject=peer, at=now_val,
+                                 detail={'window': epoch, 'named': body['grant'][:16],
+                                         'acceptable': [g[:16] for g in sorted(acceptable)]})
+            return self._msg('receipt-ack', BudgetReceiptAckBody(seq=body['seq'], head=ZERO, status='divergent'), peer)
+        limits = (self.governing(peer, grants_mod.ISSUED, epoch) or row)['payload']['limits']
+        with self._lock:
+            chain = self.receipts_in.setdefault(peer, {}).setdefault(epoch, [])
+            # The chain expects the next sequence number, not the length it
+            # happens to have: once a gap is tolerated those stop being the
+            # same number, and reading the expectation off the length would
+            # refuse every receipt after the first gap for the rest of the
+            # window - the failure this is here to end.
+            expected_seq = chain[-1]['seq'] + 1 if chain else 0
+            expected_prev = accounting.link(chain[-1]) if chain else ZERO
+            problems: list[str] = []
+            # A receipt's `at` is the subject's clock. constants.json states a
+            # tolerance of max_clock_skew_seconds and nothing in this project
+            # read it, while the specification says drift beyond it produces
+            # *unearned* divergence - a wrong answer from honest nodes, whose
+            # remedy is NTP rather than the ladder. So this is a diagnosis and
+            # not a finding: pricing a bad clock as dishonesty is the mistake
+            # two other things here have already had to be corrected for. It is
+            # recorded so an operator staring at an unexplained divergence has
+            # somewhere to look.
+            at = int(body.get('at', now_val))
+            drift = abs(at - now_val)
+            # A receipt dated before this node started is one a relay held
+            # while it was down - the peers' farewells, replayed on the
+            # resubscription - and is late, not drifted; nothing here can tell
+            # the two apart, so it is not written down as either. Dated after
+            # this clock, or late by more than this node has been up, it is
+            # a clock and nothing else.
+            if drift > C['max_clock_skew_seconds'] and (at > now_val or at >= self.started):
+                self.clock_drift.append((peer, epoch, drift, now_val))
+                if self.strain is not None:
+                    self.strain.record('drift', peer=peer)
+            if not accounting.verify_receipt(body, peer):
+                # An unsigned receipt is not a claim anyone can be held to, so it
+                # is not a claim. Saying so at once is the only way the subject
+                # learns before the window closes on it.
+                problems.append('no valid subject signature over the chain link')
+            # A gap is the wire, and a rewrite is the subject.
+            #
+            # This required seq == len(chain) and refused anything else, so one
+            # receipt lost in transit cost the whole window: the subject went
+            # on incrementing, every later receipt was refused as a chain
+            # break, and the window closed on a claim missing everything after
+            # the hole. It only ever cleared at the boundary, because the chain
+            # is keyed per epoch. Seventeen hours of a four-node mesh were
+            # priced that way, against peers that had sent every receipt.
+            #
+            # What the strict form bought was the ability to say a subject had
+            # OMITTED a receipt on purpose, as distinct from the wire dropping
+            # one. That distinction was never really available - the transport
+            # demonstrably drops them - and it was being resolved against the
+            # subject every time. What it must not give up is the guarantee
+            # that a subject cannot understate, and that survives whole:
+            # counters are cumulative and monotonic, a counter that goes
+            # backwards is still refused, and the most recent receipt alone
+            # bounds the claim. A skipped middle receipt therefore buys the
+            # subject nothing, and a missing tail is already priced as the
+            # under-claim it is.
+            #
+            # Behind the expectation is a different thing and stays a fault: a
+            # receipt at a sequence already held is a rewrite of what the
+            # subject signed, which is exactly what the chain exists to refuse.
+            seq = body.get('seq')
+            gap = 0
+            if not isinstance(seq, int) or isinstance(seq, bool) or seq < expected_seq:
+                problems.append('seq %s, expected %d or later' % (seq, expected_seq))
+            elif seq > expected_seq:
+                gap = seq - expected_seq
+            if not gap and body.get('prev') != expected_prev:
+                # Only checkable with no gap: the links the wire lost are the
+                # ones that would have joined this receipt to the last one held.
+                problems.append('prev does not chain')
+            if chain:
+                for k, v in body.get('counters', {}).items():
+                    if v < chain[-1]['counters'].get(k, 0):
+                        problems.append('counter %s went backwards' % k)
+            if problems:
+                self.findings.append((peer, epoch, 'S2', 'receipt chain: %s' % '; '.join(problems)))
+                head = expected_prev
+                status: ReceiptAckStatus = 'divergent'
+            else:
+                if gap:
+                    # A diagnosis and not a finding, recorded the way clock
+                    # drift is: an operator reading an unexplained under-claim
+                    # has somewhere to look, and nothing crosses the wire.
+                    self.receipt_gaps.append((peer, epoch, expected_seq, seq, now_val))
+                chain.append(body)
+                head = accounting.link(body)
+                self.heads_in.setdefault(peer, {})[epoch] = head
+                if self.accounts is not None:
+                    self.accounts.put_receipt(peer, epoch, body)
+                # A receipt for a window this node has already priced. The
+                # window is not reopened here - that writes grants and fires
+                # the reporter, and this runs inside an inbound handler under
+                # the lock - it is queued for the tick, where every other
+                # evaluation happens.
+                if (peer, epoch) in self.evaluated:
+                    self.reopen.add((peer, epoch))
+                measured = self._meter(self.usage_by, peer, epoch).snapshot()
+                ev = window.evaluate_window(limits, measured, body['counters'])
+                # evaluate_window already classifies each limit; this ack is
+                # about MISREPORT only, so a limit counts as divergent when
+                # its class is worse than the overrun alone would have earned.
+                # The hand-rolled `divergence > TOLERANCE` that stood here was
+                # a second copy of classify()'s threshold, and ignored the
+                # sample floor evaluate_window applies, so a receipt could be
+                # acked divergent for a window the tick then scored S0.
+                divergent = any(d['severity'] != window.classify(d['overrun'], 0.0)
+                                for d in ev['per_limit'].values())
+                status = 'divergent' if divergent else 'accepted'
+        return self._msg('receipt-ack', BudgetReceiptAckBody(seq=body.get('seq', 0), head=head, status=status), peer)
+
+    def on_close(self: BudgetShape, peer: str, body: Any, now: Optional[int] = None) -> Message[BudgetReceiptAckBody]:
+        now_val = now if now is not None else self.clock()
+        why = validate.check_body('budget', 'close', body)
+        if why is not None:
+            self.refusals.refuse('close', why, subject=peer, at=now_val)
+            return self._msg('receipt-ack', BudgetReceiptAckBody(seq=0, head=ZERO, status='divergent'), peer)
+        epoch = body['window']
+        w = self._window_of(peer, grants_mod.ISSUED)
+        head = self.heads_in.get(peer, {}).get(epoch, ZERO)
+        final = body.get('final_receipt_head') == head and accounting.close_is_final(
+            now_val, accounting.window_bounds(epoch, w)[1], w)
+        return self._msg('receipt-ack', BudgetReceiptAckBody(
+            seq=len(self.receipts_in.get(peer, {}).get(epoch, [])),
+            head=head, status='final' if final else 'accepted'), peer)
+
+    def handle_receipt(self: BudgetShape, inbound: Any, sender: str) -> tuple[Any, ...]:
+        msg = getattr(inbound, 'message', inbound)
+        body = msg.get('body')
+        reply = self.on_receipt(sender, body)
+        self.wire_client.reply(inbound, reply, sender=sender)
+        return ('acked-out', sender, reply['body']['status'])
+
+    def handle_close(self: BudgetShape, inbound: Any, sender: str) -> tuple[Any, ...]:
+        msg = getattr(inbound, 'message', inbound)
+        body = msg.get('body')
+        reply = self.on_close(sender, body)
+        self.wire_client.reply(inbound, reply, sender=sender)
+        return ('acked-out', sender, reply['body']['status'])
+
+    def handle_receipt_ack(self: BudgetShape, inbound: Any, sender: str) -> tuple[Any, ...]:
+        msg = getattr(inbound, 'message', inbound)
+        body = msg.get('body')
+        why = validate.check_body('budget', 'receipt-ack', body)
+        if why is not None:
+            self.refusals.refuse('receipt-ack', why, subject=sender)
+            return ('ignored', sender, 'malformed receipt-ack: ' + why)
+        with self._lock:
+            self.acks[sender] = body
+            behind = self._ack_lag(sender, body)
+        if behind:
+            return ('acked', sender, '%s, %d receipt(s) behind' % (body['status'], behind))
+        return ('acked', sender, body['status'])

node/planes/peering/budget/shape.py

@@ -0,0 +1,101 @@
+"""The shape of a Budget as its mixins see it.
+
+The one class is split across receipts.py, windows.py, tick.py and core.py by
+concern, but every method reads instance state set in Budget.__init__ and
+calls methods that live on another of those modules. Each mixin method
+annotates `self` as this Protocol so the checker knows what is on it without
+the mixins inheriting from one another, stubbing each other's methods, or
+falling back to Any. It is a declaration only; Budget satisfies it
+structurally and nothing here runs.
+"""
+from __future__ import annotations
+
+import threading
+from typing import Any, Callable, Mapping, Optional, Protocol
+
+from fleetmesh_core.accounting import standing
+from fleetmesh_core.wire.interfaces import ReceiptBody
+from fleetmesh_core.wire.wire_types import BudgetBody, BudgetReceiptAckBody, GoverningRow, Message
+from node.compartment import Refusals, stores
+from node.storage import grants as grants_mod
+from .chain import OutChain
+from .evaluation import Evaluation, Repricing
+from .meter import Meter
+
+
+class BudgetShape(Protocol):
+    # class attributes on Budget and Compartment
+    KEEP_WINDOWS: int
+    TROUBLE_WINDOW: int
+    # set in Compartment.__init__
+    refusals: Refusals
+    # set in WireProtocol.__init__
+    wire_client: Any
+    # set in Budget.__init__, in that order
+    strain: Optional[Any]
+    accounts: Optional[Any]
+    ks: Any
+    transport: Any
+    grants: grants_mod.GrantStore
+    peering: Any
+    clock: Callable[[], int]
+    ledger: standing.Ledger
+    _lock: threading.RLock
+    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]]
+    evaluations: stores.Ring[Evaluation]
+    findings: stores.Ring[tuple[Any, ...]]
+    zero_until: dict[str, int]
+    idle: dict[str, int]
+    clock_drift: stores.Ring[tuple[Any, ...]]
+    started: int
+    receipt_gaps: stores.Ring[tuple[Any, ...]]
+    ack_lag: dict[str, tuple[int, int, int]]
+    ack_head: dict[str, tuple[int, int]]
+    unpublished: stores.Ring[tuple[Any, ...]]
+    on_evaluated: list[Callable[[Evaluation], Any]]
+    reopen: set[tuple[str, int]]
+    repriced: list[Repricing]
+    on_repriced: list[Callable[[str, int, str, str], Any]]
+    # set by the tick, the first time it forgets
+    _forgotten_to: int
+
+    # core.py
+    def _save_meters(self, peer: Optional[str] = None, epoch: Optional[int] = None) -> None: ...
+    def _window_of(self, peer: str, direction: grants_mod.GrantDirection) -> int: ...
+    def _peers(self) -> list[str]: ...
+    def governing(self, peer: str, direction: grants_mod.GrantDirection, epoch: int) -> Optional[GoverningRow]: ...
+    def _acceptable_grants(self, peer: str, epoch: int) -> set[str]: ...
+    def epoch(self, peer: str, direction: grants_mod.GrantDirection, at: Optional[int] = None) -> int: ...
+    def _meter(self, table: dict[str, dict[int, Meter]], peer: str, epoch: int) -> Meter: ...
+
+    # receipts.py
+    def _msg(self, kind: str, body: BudgetBody, peer: str, piuri: str = ...) -> Message[BudgetBody]: ...
+    def receipt_due(self, peer: str, now: int) -> bool: ...
+    def send_receipt(self, peer: str, now: Optional[int] = None, final: bool = False,
+                     epoch: Optional[int] = None) -> tuple[ReceiptBody, str]: ...
+    def _ack_lag(self, peer: str, body: Mapping[str, Any]) -> int: ...
+    def final_due(self, peer: str, now: int) -> Optional[int]: ...
+    def on_receipt(self, peer: str, body: Any, now: Optional[int] = None) -> Message[BudgetReceiptAckBody]: ...
+    def on_close(self, peer: str, body: Any, now: Optional[int] = None) -> Message[BudgetReceiptAckBody]: ...
+    def handle_receipt(self, inbound: Any, sender: str) -> tuple[Any, ...]: ...
+    def handle_close(self, inbound: Any, sender: str) -> tuple[Any, ...]: ...
+    def handle_receipt_ack(self, inbound: Any, sender: str) -> tuple[Any, ...]: ...
+
+    # windows.py
+    def evaluate(self, peer: str, epoch: int, now: Optional[int] = None) -> Optional[Evaluation]: ...
+    def publish_pending(self, peer: str, now: Optional[int] = None) -> Optional[Mapping[str, Any]]: ...
+    def _over(self, limits: Mapping[str, Any], counters: Mapping[str, Any], opening: bool = False) -> Optional[str]: ...
+    def closeable(self, peer: str, now: int) -> list[int]: ...
+    def reopen_due(self, peer: str) -> list[int]: ...
+    def reprice(self, peer: str, epoch: int, now: Optional[int] = None) -> Optional[Repricing]: ...
+
+    # tick.py
+    def _tick_peer(self, peer: str, now_val: int) -> list[tuple[Any, ...]]: ...
+    def _forget_old(self, now: int) -> None: ...
+    def _forget_in_memory(self, horizon: int) -> None: ...