fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/peering/budget/tick.py

@@ -0,0 +1,110 @@
+"""The scheduler's tick: what is due for every peer, and the retention
+horizon. Separate because it is the one place the receipts and the windows
+are driven from, and the one place that forgets.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from fleetmesh_core.accounting import accounting
+from node.storage import grants as grants_mod
+from .meter import C, KEEP_FINDINGS
+from .shape import BudgetShape
+
+
+class TickMixin:
+    # ---- the scheduler's tick ---------------------------------------------------
+    def tick(self: BudgetShape, now: Optional[int] = None) -> list[tuple[Any, ...]]:
+        """Send due receipts; evaluate closed windows. Returns what it did."""
+        now_val = now if now is not None else self.clock()
+        did: list[tuple[Any, ...]] = []
+        self._save_meters()
+        self._forget_old(now_val)
+        for lst in (self.findings, self.clock_drift, self.receipt_gaps, self.unpublished, self.evaluations):
+            if isinstance(lst, list) and len(lst) > KEEP_FINDINGS:
+                del lst[:len(lst) - KEEP_FINDINGS]
+        for peer in self._peers():
+            try:
+                did += self._tick_peer(peer, now_val)
+            except Exception as e:
+                # One peer must not end the tick for the others. A peer whose
+                # descriptor no longer resolves - it expired, or it declares a
+                # protocol digest this node refuses - raised TransportError out
+                # of `send_receipt`, and every peer after it in `grants.peers()`
+                # order silently missed its receipts for that window. On the
+                # 2026-09-26 roll that was three of four nodes, once a window,
+                # for as long as one peer stayed behind the digest.
+                #
+                # `scheduler.py` already learned this and says so at its own two
+                # call sites. This is the same fault in the compartment that
+                # owes the receipts.
+                self.refusals.refuse('accounting', 'the peer raised', subject=peer,
+                                     detail={'error': '%s: %s' % (type(e).__name__, e)}, at=now_val)
+                did.append(('accounting failed', peer, '%s: %s' % (type(e).__name__, e)))
+        return did
+
+    def _tick_peer(self: BudgetShape, peer: str, now_val: int) -> list[tuple[Any, ...]]:
+        """One peer's share of the tick: its grant, its receipts, its windows."""
+        did: list[tuple[Any, ...]] = []
+        out = self.publish_pending(peer, now_val)
+        if out is not None:
+            did.append(('grant published', peer, out['payload']['tier'], out['envelope']['id']))
+        prev = self.final_due(peer, now_val)
+        if prev is not None:
+            body, head = self.send_receipt(peer, now_val, final=True, epoch=prev)
+            self.chain_out[peer][prev].final = True
+            did.append(('final receipt', peer, prev, body['seq']))
+        if self.receipt_due(peer, now_val):
+            body, head = self.send_receipt(peer, now_val)
+            did.append(('receipt', peer, body['seq']))
+        for e in self.reopen_due(peer):
+            rp = self.reprice(peer, e, now_val)
+            if rp:
+                did.append(('repriced', peer, e, rp.was, rp.severity))
+        for e in self.closeable(peer, now_val):
+            ev = self.evaluate(peer, e, now_val)
+            if ev:
+                did.append(('evaluated', peer, e, ev.severity))
+        return did
+
+    def _forget_old(self: BudgetShape, now: int) -> None:
+        """Drop accounting for windows nothing can still be said about.
+
+        Both halves of it. This forgot the disk and not the memory the disk is
+        written back from: `_save_meters` walks usage_by and usage_of_me and
+        writes every epoch in them, so meters deleted on one tick were re-
+        inserted on the next, while the receipts and the evaluated marker
+        beside them stayed gone.
+
+        A window in that state - metered, no receipt, no record of having been
+        priced - is exactly the shape of active silence, and it was priced as
+        such. On the live mesh nyc3 held meters from epoch 496806 against
+        receipts that began at 496818, and re-priced the twelve windows between
+        as S2 on every restart, a batch at a time, against a peer that had done
+        nothing. It was pricing its own retention policy as the peer's fault.
+        """
+        if self.accounts is None:
+            return
+        oldest = min((self._window_of(p, grants_mod.ISSUED) for p in self._peers()),
+                     default=C['window_seconds_default'])
+        keep = self.KEEP_WINDOWS
+        if self.strain is not None:
+            # A reserve, not a constant. A node that has watched peers vanish
+            # and come back keeps their accounting longer, so a chain still
+            # links when one does. Counted by direction, so one peer
+            # disappearing over and over buys a single direction's patience.
+            keep = int(self.strain.reserve(self.KEEP_WINDOWS, 'partition'))
+        horizon = accounting.epoch(now, oldest) - keep
+        if horizon > getattr(self, '_forgotten_to', -1):
+            self.accounts.forget_before(horizon)
+            self._forget_in_memory(horizon)
+            self._forgotten_to = horizon
+
+    def _forget_in_memory(self: BudgetShape, horizon: int) -> None:
+        """The same cutoff, applied to what the tick writes back."""
+        with self._lock:
+            for table in (self.usage_by, self.usage_of_me, self.receipts_in):
+                for by_epoch in table.values():
+                    for e in [e for e in by_epoch if e < horizon]:
+                        by_epoch.pop(e, None)
+            self.reopen = {(pk, e) for pk, e in self.reopen if e >= horizon}  # not a store: pruned horizon

node/planes/peering/budget/types.py

@@ -0,0 +1,67 @@
+"""Types and records for the Budget compartment."""
+from __future__ import annotations
+
+from typing import Mapping, Optional, TypedDict
+
+from fleetmesh_core.wire.interfaces import ReceiptBody, SilenceEvaluation, WindowEvaluationDetail
+from node.interfaces import ReceiptRefusedRow
+
+
+class OutChainDict(TypedDict, total=False):
+    """The JSON serialization shape of an OutChain."""
+    grant: str
+    seq: int
+    prev: str
+    sent_at: Optional[int]
+    last: Optional[dict[str, int]]
+    heads: list[str]
+    final: bool
+
+
+class EvaluationDict(TypedDict, total=False):
+    """The JSON serialization shape of an Evaluation."""
+    peer: str
+    epoch: int
+    state: str
+    measured: dict[str, int]
+    claimed: Optional[dict[str, int]]
+    tier_before: str
+    grant: str
+    limits: Mapping[str, int | float]
+    severity: Optional[str]
+    note: str
+    detail: dict[str, WindowEvaluationDetail | SilenceEvaluation]
+    tier_after: Optional[str]
+    limits_after: Optional[Mapping[str, int | float]]
+    effective_from: Optional[int]
+    receipt_heads: list[str]
+    receipts: list[ReceiptBody]
+
+
+class RepricingDict(TypedDict):
+    """The JSON serialization shape of a Repricing."""
+    peer: str
+    epoch: int
+    was: str
+    severity: str
+    state: str
+    measured: dict[str, int]
+    claimed: Optional[dict[str, int]]
+    receipts: int
+    remedy_cancelled: bool
+    at: int
+
+
+class BudgetStateReport(TypedDict):
+    peers: int
+    windows_evaluated: int
+    findings: int
+    grants_waiting_for_a_boundary: int
+    clock_drift: int
+    receipt_gaps: int
+    receipts_behind: dict[str, int]
+    receipts_unpublished: int
+    receipt_chains_open: int
+    idle_streaks: dict[str, int]
+    rejected: dict[str, int]
+    receipts_refused: list[ReceiptRefusedRow]

node/planes/peering/budget/windows.py

@@ -0,0 +1,346 @@
+"""The window, priced: evaluate a closed one, publish the grant it decided
+on, enforce the grant in force, and reprice on a late receipt. Separate
+because this is where fleetmesh_core/window.py's ladder is applied and a grant is
+changed; nothing here reads the wire.
+"""
+from __future__ import annotations
+
+import secrets
+from typing import Any, Mapping, Optional
+
+from fleetmesh_core.accounting import accounting, window
+from fleetmesh_core.storage import sync
+from node.storage import grants as grants_mod
+from .evaluation import Evaluation, Repricing
+from .meter import C, KEEP_FINDINGS, Meter
+from .shape import BudgetShape
+
+
+class WindowsMixin:
+    # ---- issuer: closing windows ---------------------------------------------
+    def evaluate(self: BudgetShape, peer: str, epoch: int, now: Optional[int] = None) -> Optional[Evaluation]:
+        """One closed window against one subject. Returns the evaluation record."""
+        now_val = now if now is not None else self.clock()
+        row = self.grants.get(peer, grants_mod.ISSUED)
+        if row is None or row['status'] != 'live':
+            return None
+        # Priced under the grant that governed the window, not the one that is
+        # current when the grace period ends: a window that ran under one set
+        # of limits and was judged under another was a finding about nothing.
+        governed = self.governing(peer, grants_mod.ISSUED, epoch) or row
+        limits, tier = governed['payload']['limits'], governed['payload']['tier']
+        # The remedy applies to the grant that will be in force, which is the
+        # one already waiting for the boundary if a window was closed before
+        # this one in the same grace period, and otherwise the current one.
+        pending = self.grants.pending(peer)
+        base = pending['payload'] if pending else row['payload']
+        measured = self.usage_by.get(peer, {}).get(epoch, Meter()).snapshot()
+        receipts = self.receipts_in.get(peer, {}).get(epoch, [])
+        state, claimed = accounting.window_claim(receipts, measured)
+        rec = Evaluation(peer=peer, epoch=epoch, state=state, measured=measured, claimed=claimed,
+                         tier_before=tier, grant=governed['envelope_id'], limits=limits)
+        if state == 'not-evaluated':
+            rec.note = 'nothing moved and nothing was claimed'
+            self.idle[peer] = self.idle.get(peer, 0) + 1
+            # Capacity earned in one busy week used to sit there a year later as
+            # surface nobody was watching: a limit moved up on a clean window
+            # and down on a fault and never decayed. A grant that has measured
+            # nothing for long enough gives some of itself back, down to where a
+            # peering opens and never below. Nothing happened, which is the whole
+            # of the reason, so it is amended with cause disuse and is not a
+            # finding about anyone.
+            if self.idle[peer] >= C['decay_idle_windows'] and base.get('limits'):
+                decayed = window.decay(base['limits'], base['tier'])
+                decayed = {k: (int(v) if float(v).is_integer() else v) for k, v in decayed.items()}
+                if decayed != base['limits']:
+                    # Disuse is not a finding: the pending row carries no
+                    # severity and `_apply_pending` reads that absence as the
+                    # cause. GrantStore.put_pending annotates severity as str
+                    # although it stores NULL here (node/grants.py, not owned
+                    # by this change).
+                    self.grants.put_pending(
+                        peer, dict(base, limits=decayed, blinding=secrets.token_bytes(32).hex()),
+                        'decayed after %d windows that measured nothing' % self.idle[peer],
+                        None,
+                        accounting.epoch(now_val, self._window_of(peer, grants_mod.ISSUED)))
+                    rec.note += '; grant decayed for disuse'
+                self.idle[peer] = 0
+            self.evaluations.append(rec)
+            self.evaluated.add((peer, epoch))
+            if self.accounts is not None:
+                self.accounts.put_evaluated(peer, epoch, None)
+            return rec
+        # A window with no receipt is still a window that was measured. Silence
+        # is a floor of S2 and not a ceiling: skipping the arithmetic here - which
+        # is what this did - priced a peer that flooded and said nothing BELOW the
+        # same peer reporting it honestly, because honest excess reaches S3 on
+        # overrun alone. fleetmesh_core/badpeer.py plugged into a node is what found it, and
+        # it is the same inversion the severity ladder itself had. An absent claim
+        # is the empty claim, which is how vectors/window.json has always priced
+        # "no receipt at all".
+        self.idle[peer] = 0
+        ev = window.evaluate_window(limits, measured, claimed or {})
+        severity, detail = ev['severity'], ev['per_limit']
+        if state == 'active-silence':
+            severity = window.worse(severity, 'S2')
+            detail = dict(detail, silence=accounting.silence(measured))
+            self.findings.append((peer, epoch, severity, 'traffic measured and no receipt: active silence'))
+        for name, d in ev['per_limit'].items():
+            if d['severity'] != 'S0':
+                self.findings.append((peer, epoch, d['severity'], '%s: %s' % (name, d)))
+        # The clean branch grows each limit by what this window actually carried.
+        new_limits, new_tier, note = window.adjust(base['limits'], base['tier'], severity, measured)
+        if severity == 'S3':
+            self.zero_until[peer] = now_val + C['s3_zero_hours'] * 3600
+        rounded = {k: (int(v) if float(v).is_integer() else v) for k, v in new_limits.items()}
+        new_payload = dict(base, limits=rounded, tier=new_tier, blinding=secrets.token_bytes(32).hex())
+        decided = accounting.epoch(now_val, self._window_of(peer, grants_mod.ISSUED))
+        self.grants.put_pending(peer, new_payload, '%s after %s' % (note, severity), severity, decided)
+        self.ledger.record(peer, epoch, severity, new_tier)
+        rec.severity, rec.detail, rec.note = severity, detail, note
+        rec.tier_after, rec.limits_after, rec.effective_from = new_tier, rounded, decided + 1
+        self.evaluations.append(rec)
+        self.evaluated.add((peer, epoch))
+        if self.accounts is not None:
+            self.accounts.put_evaluated(peer, epoch, severity, new_tier)
+        rec.receipt_heads = [accounting.link(r) for r in receipts]
+        rec.receipts = list(receipts)          # the bodies, which are the evidence
+        for cb in self.on_evaluated:
+            cb(rec)
+        return rec
+
+    def publish_pending(self: BudgetShape, peer: str, now: Optional[int] = None) -> Optional[Mapping[str, Any]]:
+        """At a window boundary, the grant the last evaluation decided on goes
+        out: written, published as a new kind 30801 at the same coordinate, and
+        the subject told with peering/1.0/amend. Returns the envelope or None."""
+        now_val = now if now is not None else self.clock()
+        pend = self.grants.pending(peer)
+        if pend is None:
+            return None
+        w = self._window_of(peer, grants_mod.ISSUED)
+        current = accounting.epoch(now_val, w)
+        if current <= pend['decided_epoch']:
+            return None
+        row = self.grants.get(peer, grants_mod.ISSUED)
+        if row is None or row['status'] != 'live':
+            self.grants.clear_pending(peer)
+            return None
+        payload = pend['payload']
+        # The tier ceiling is enforced where a grant is written and not only
+        # where one is computed. window.adjust holds its own result inside the
+        # tier it returns, but the thing the specification constrains is the
+        # grant that reaches the wire, and a pending payload can have been
+        # decided by an older build and slept through a restart. If this ever
+        # fires the defect is upstream, so it is recorded against this node.
+        # A pending grant with no severity was not decided by the ladder. The only
+        # path that writes one is decay, so this is where disuse reaches the wire.
+        cause = 'remedy' if pend.get('severity') else 'disuse'
+        # The clamp, the envelope, the store, the amend: peering owns all of it
+        # now. This used to be its own copy of that procedure, and it was the
+        # only copy that clamped the payload to its tier ceiling.
+        out = self.peering.issue(peer, payload, cause, pend['note'], effective_epoch=current, now=now_val,
+                                 on_clamp=lambda pk, tier, over: self.findings.append(
+                                     ('self', None, None,
+                                      'pending grant for %s carried limits above the %s ceiling: %s'
+                                      % (pk[:8], tier, over))))
+        # What standing tells a third party about this peer is the tier of the
+        # grant in force, so it moves when the grant does. The operator path
+        # used to set this itself the moment a person decided; now that every
+        # decision lands at the boundary, the boundary is where it belongs, and
+        # both paths get it from the same line.
+        if self.ledger is not None:
+            self.ledger.tier[peer] = out['payload'].get('tier')
+        return {'envelope': out['envelope'], 'payload': out['payload'],
+                'published': out['published'], 'severity': pend['severity']}
+
+    # ---- the grant, enforced ----------------------------------------------------
+    def _over(self: BudgetShape, limits: Mapping[str, Any], counters: Mapping[str, Any], opening: bool = False) -> Optional[str]:
+        """The first limit a session would go past, or None. `opening` adds
+        the connection and request the open itself costs. The reference's own
+        `Grant.exceeded` decides, so what is refused here is exactly what the
+        ladder would price, under the same grant.counter_of mapping."""
+        c = dict(counters)
+        if opening:
+            c['conn_open'] = c.get('conn_open', 0) + 1
+            c['req'] = c.get('req', 0) + 1
+        over = sync.Grant('', '', limits).exceeded(c)
+        if not over:
+            return None
+        name = sorted(over)[0]
+        return '%s %s over the grant\'s %s' % (name, c.get(window.counter_of(name), 0), limits[name])
+
+    def throttled(self: BudgetShape, peer: str, now: Optional[int] = None) -> Optional[str]:
+        """Why this node must not open a session with the peer right now, or
+        None. Read from the grant it holds: revoked, zero, or a limit the
+        window's usage so far has reached."""
+        now_val = now if now is not None else self.clock()
+        row = self.grants.get(peer, grants_mod.RECEIVED)
+        if row is None or row['status'] != 'live':
+            return 'no live grant from the peer'
+        limits = row['payload'].get('limits', {})
+        if row['payload'].get('tier') == 'revoked' or not any(limits.values()):
+            return 'the grant is zero'
+        epoch = self.epoch(peer, grants_mod.RECEIVED, now_val)
+        used = self._meter(self.usage_of_me, peer, epoch).snapshot()
+        return self._over(limits, used, opening=True)
+
+    def granted_rate(self: BudgetShape, peer: str) -> tuple[int, int]:
+        """(sessions the grant allows per window, the window in seconds).
+
+        What a cadence is derived from when none is configured: the rate the
+        peer actually granted, so a tier promotion changes how often this node
+        pulls without anybody editing a number beside it.
+        """
+        row = self.grants.get(peer, grants_mod.RECEIVED)
+        w = self._window_of(peer, grants_mod.RECEIVED)
+        if row is None or row['status'] != 'live':
+            return (0, w)
+        limits = row['payload'].get('limits', {})
+        return (int(limits.get('conn_rate', 0) or 0), w)
+
+    def sessions_left(self: BudgetShape, peer: str, now: Optional[int] = None) -> tuple[int, int]:
+        """How many more sessions this node may open with the peer in the
+        window that is running, and when that window closes.
+
+        The pair the scheduler needs to pace itself from the contract rather
+        than from a configured number. `conn_rate` is what the peer granted
+        per window; `conn_open` is what this node has already spent of it, and
+        it is read from the meter, which is the record the peer also prices -
+        not a private clock the scheduler keeps on the side.
+
+        Returns (0, close) when the budget is spent, which is a wait rather
+        than a refusal: the allowance returns when the window turns.
+        """
+        now_val = now if now is not None else self.clock()
+        row = self.grants.get(peer, grants_mod.RECEIVED)
+        if row is None or row['status'] != 'live':
+            return (0, now_val)
+        limits = row['payload'].get('limits', {})
+        allowed = int(limits.get('conn_rate', 0) or 0)
+        w = self._window_of(peer, grants_mod.RECEIVED)
+        epoch = self.epoch(peer, grants_mod.RECEIVED, now_val)
+        closes = accounting.window_bounds(epoch, w)[1]
+        if row['payload'].get('tier') == 'revoked' or allowed <= 0:
+            return (0, closes)
+        used = self._meter(self.usage_of_me, peer, epoch).snapshot()
+        spent = int(used.get(window.counter_of('conn_rate'), 0) or 0)
+        return (max(0, allowed - spent), closes)
+
+    def refuses(self: BudgetShape, peer: str, now: Optional[int] = None) -> Optional[str]:
+        """Why this node must not serve the peer's session, or None. Read from
+        the grant it issued and governing now, plus an S3 zero still running."""
+        now_val = now if now is not None else self.clock()
+        if self.zero_until.get(peer, 0) > now_val:
+            return 'zeroed after S3 until %d' % self.zero_until[peer]
+        row = self.grants.get(peer, grants_mod.ISSUED)
+        if row is None or row['status'] != 'live':
+            return 'no live grant to the peer'
+        epoch = self.epoch(peer, grants_mod.ISSUED, now_val)
+        limits = (self.governing(peer, grants_mod.ISSUED, epoch) or row)['payload'].get('limits', {})
+        if row['payload'].get('tier') == 'revoked' or not any(limits.values()):
+            return 'the grant is zero'
+        used = self._meter(self.usage_by, peer, epoch).snapshot()
+        return self._over(limits, used)
+
+    def closeable(self: BudgetShape, peer: str, now: int) -> list[int]:
+        """Epochs of my grant to this peer that have closed and passed grace."""
+        w = self._window_of(peer, grants_mod.ISSUED)
+        current = accounting.epoch(now, w)
+        # The window a receipt may not name is a window that may not be priced.
+        # on_receipt refuses one outside this bound as "answerable by nothing",
+        # and a verdict reached where no answer is admissible is not a verdict:
+        # the subject cannot refute it, and the evidence to support it is what
+        # this node deliberately threw away. Same bound, both directions.
+        oldest = current - self.KEEP_WINDOWS
+        with self._lock:      # the sync thread grows these; see _save_meters
+            seen = set(self.usage_by.get(peer, {})) | set(self.receipts_in.get(peer, {}))
+        out: list[int] = []
+        for e in sorted(seen):
+            if e < oldest:
+                continue
+            if e < current and (peer, e) not in self.evaluated and now >= accounting.window_bounds(e, w)[1] + accounting.window_grace(w):
+                out.append(e)
+        return out
+
+    def reopen_due(self: BudgetShape, peer: str) -> list[int]:
+        """Windows already priced that a receipt has since landed on. Draining
+        the queue is what makes a reprice happen once and not on every tick."""
+        with self._lock:
+            mine = sorted(e for pk, e in self.reopen if pk == peer)
+            self.reopen -= {(peer, e) for e in mine}
+        return mine
+
+    def reprice(self: BudgetShape, peer: str, epoch: int, now: Optional[int] = None) -> Optional[Repricing]:
+        """Price one window again, because a receipt covering it arrived late.
+
+        A window closes on the clock and is judged once its grace has run, and
+        the subject's last receipt for it can arrive after that: the grace is
+        window_grace_fraction of the window - 360 seconds at the default - and
+        a control-plane gap of 882 seconds has been measured on a running mesh.
+        What the issuer holds then is a claim missing its tail, which is
+        arithmetically indistinguishable from a claim that was understated. So
+        an honest peer earns the S2 misreport floor for a delivery gap, and
+        cannot refute it: the published classifier run over the receipt it did
+        sign returns S2, correctly. That is the fourth layer at which something
+        other than dishonesty has been priced as dishonesty, after the session
+        abort, the standing streak, and the node that vanishes mid-window which
+        `farewell` answers. The first three were fixed by saying something
+        rather than nothing; this one cannot be, because the subject did say it
+        and the wire lost it. So the issuer reads again instead.
+
+        **A reprice may only lower a severity, and that is not a courtesy.**
+        The receipt chain appends and does nothing else - seq, prev and every
+        counter are checked before a receipt is stored - so a late receipt is
+        the tail of a claim the subject had already committed to, and can only
+        move that claim toward what was measured. A second reading that came
+        out worse would therefore not be a later truth but a different one, and
+        a node that could be made to price harder by a late receipt would hand
+        every peer a way to worsen a verdict it had already earned. If the new
+        reading is not strictly better, the first one stands and nothing here
+        happens.
+        """
+        now_val = now if now is not None else self.clock()
+        was = self.ledger.severity_of(peer, epoch)
+        if was is None:
+            return None
+        row = self.grants.get(peer, grants_mod.ISSUED)
+        if row is None or row['status'] != 'live':
+            return None
+        governed = self.governing(peer, grants_mod.ISSUED, epoch) or row
+        limits = governed['payload']['limits']
+        measured = self.usage_by.get(peer, {}).get(epoch, Meter()).snapshot()
+        receipts = self.receipts_in.get(peer, {}).get(epoch, [])
+        state, claimed = accounting.window_claim(receipts, measured)
+        if state == 'not-evaluated':
+            return None
+        severity = window.evaluate_window(limits, measured, claimed or {})['severity']
+        if state == 'active-silence':
+            severity = window.worse(severity, 'S2')
+        if severity == was or window.worse(severity, was) != was:
+            return None
+        self.ledger.amend(peer, epoch, severity)
+        if self.accounts is not None:
+            self.accounts.put_evaluated(peer, epoch, severity, self.ledger.tier.get(peer))
+        # The remedy is cancelled only where cancelling it is the whole answer:
+        # the window was clean and the grant that would have punished it has
+        # not been issued yet. A reading that is milder but still adverse
+        # leaves the stricter remedy standing rather than deriving a new one
+        # from a base that is already gone, and a remedy that has reached the
+        # wire is a signed artefact this must not quietly unwind. The record is
+        # corrected in every case; only the unissued grant is withdrawn, and
+        # the direction of the error is the strict one either way. A tier the
+        # ladder dropped stays dropped, because raising one is a person's
+        # decision and nothing here is a person.
+        pend = self.grants.pending(peer)
+        cancelled = False
+        if severity == 'S0' and pend is not None and pend.get('severity') == was:
+            self.grants.clear_pending(peer)
+            cancelled = True
+        rec = Repricing(peer=peer, epoch=epoch, was=was, severity=severity, state=state,
+                        measured=measured, claimed=claimed, receipts=len(receipts),
+                        remedy_cancelled=cancelled, at=now_val)
+        self.repriced.append(rec)
+        del self.repriced[:-KEEP_FINDINGS]
+        for cb in self.on_repriced:
+            cb(peer, epoch, was, severity)
+        return rec

node/planes/peering/capacity/__init__.py

@@ -0,0 +1,7 @@
+"""The node's own ceiling, held across ticks, and the shed ladder it drives.
+
+One-module compartment: everything is in compartment.py.
+"""
+from .compartment import Capacity
+
+__all__ = ['Capacity']