fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/peering/reporter/publish.py

@@ -0,0 +1,285 @@
+"""Publishing a finding as a kind 30802 report, the relay-score projection
+that rides beside it, withdrawal, and the tick that drives all of it.
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+from fleetmesh_core.accounting import window  # noqa: E402
+from fleetmesh_core.crypto import giftwrap  # noqa: E402
+from fleetmesh_core.peering import complaint, projection, reports  # noqa: E402
+from fleetmesh_core.storage import store  # noqa: E402
+from fleetmesh_core.wire.interfaces import NostrEvent  # noqa: E402
+from node.storage import grants as grants_mod  # noqa: E402
+from node.protocols.nostr import client as relay  # noqa: E402
+from .constants import FINDING_WINDOWS, PUBLISH_TRIES, REPORT_TTL
+from .finding import Finding
+from .shape import ReporterShape
+
+from fleetmesh_core.identity.did import did_nostr as _did
+
+
+class PublishMixin:
+    def publish(self: ReporterShape, p: Finding, now: Optional[int] = None) -> Optional[NostrEvent]:
+        now_val = now if now is not None else self.clock()
+        worst = p.worst
+        observed = (worst[0], worst[1]['measured'], worst[1]['limit']) if worst else None
+        claimed = (worst[0], worst[1]['claimed']) if worst and worst[1].get('claimed') is not None else None
+        notice = (p.thid, p.notice_at) if p.thid else None
+        if not p.evidence:
+            # Nothing the subject signed exists for this window. Active silence is
+            # the case that can never produce one: the subject said nothing, so
+            # there is nothing of its own to quote. Do not invent a citation.
+            reason = ['the subject signed nothing this window that could be cited']
+            with self._lock:
+                p.unpublishable = reason
+                p.tries = PUBLISH_TRIES        # nothing about a closed window will change this
+            self._note_unpublishable(p, reason)
+            self._persist(p)
+            return None
+        # The grant this report cites travels with it. It is addressable under
+        # a blinded tag, so the one that governed a past window has already
+        # been replaced at that coordinate and no relay serves it; a report
+        # that did not carry its own became inadmissible to every reader
+        # within about an hour of being published.
+        envelope = self.grants.envelope_event(p.peer, grants_mod.ISSUED, p.grant)
+        ev = reports.build(self.ks.node_pk, p.peer, p.severity, p.grant, (p.epoch, p.epoch),
+                           p.evidence, now_val, REPORT_TTL, observed=observed, claimed=claimed, notice=notice,
+                           content='; '.join(str(w) for w in p.why)[:400] or p.source,
+                           grant_envelope=envelope)
+        at = self.forward_clock('report:' + p.peer, now_val) if self.forward_clock else now_val
+        signed = store.make_signed_event(self.ks.node_sk, at, 30802, ev['tags'], ev['content'])
+        # Do not publish what a reader will discard. A report whose evidence
+        # does not resolve to something the subject signed is inadmissible, and
+        # publishing it is pure cost: readers count it as unsupported, which
+        # raises this node's own false_report_rate and lowers what its word is
+        # worth. The finding stays local and the grant stays zeroed.
+        okay, reasons = reports.admissible(signed, self.ks.node_pk, self._resolver(), giftwrap.verify_event)
+        if not okay:
+            with self._lock:
+                p.unpublishable = reasons
+                p.tries = p.tries + 1
+            self._note_unpublishable(p, reasons)
+            self._persist(p)
+            return None
+        relay.publish_all(self.relays, signed, self.timeout)
+        self.ledger.reported_against(p.peer)
+        with self._lock:
+            p.report = signed
+            self.published.append(signed)
+        self._persist(p)
+        self._project(signed, now_val)
+        return signed
+
+    def _project(self: ReporterShape, report: NostrEvent, now: int) -> list[NostrEvent]:
+        """The relay score a client can read, derived from the report just published.
+
+        A NIP-85 kind 30385 per ws or wss endpoint the subject's descriptor
+        declares; see fleetmesh_core/projection.py for the shape and the reason it is
+        adverse only. A subject that declares no relay endpoint gets none:
+        there is nothing a client could connect to. Addressable under d = the
+        relay URL, so it is stamped forward like the report it follows.
+        """
+        if not self.project:
+            return []
+        subject = [t[1] for t in report['tags'] if t[0] == 'd'][0]
+        desc = self.transport.peers.descriptor(subject)
+        endpoints = projection.relay_endpoints(desc) if desc is not None else []
+        out: list[NostrEvent] = []
+        for ev in projection.project(report, endpoints, now):
+            d = [t[1] for t in ev['tags'] if t[0] == 'd'][0]
+            at = self.forward_clock('projection:' + d, now) if self.forward_clock else now
+            signed = store.make_signed_event(self.ks.node_sk, at, projection.KIND, ev['tags'], ev['content'])
+            relay.publish_all(self.relays, signed, self.timeout)
+            out.append(signed)
+        with self._lock:
+            for signed_ev in out:
+                self.projected.append(signed_ev)
+        try:
+            lbl_ev = projection.label(report, now)
+            at_lbl = self.forward_clock('label:' + subject, now) if self.forward_clock else now
+            signed_lbl = store.make_signed_event(self.ks.node_sk, at_lbl, projection.LABEL_KIND, lbl_ev['tags'], lbl_ev['content'])
+            relay.publish_all(self.relays, signed_lbl, self.timeout)
+            with self._lock:
+                self.labeled.append(signed_lbl)
+        except Exception:
+            pass
+        return out
+
+    def _note_unpublishable(self: ReporterShape, p: Finding, reasons: list[str]) -> None:
+        with self._lock:
+            self.unpublishable.append((p.peer, p.epoch, p.severity, reasons))
+
+    def _withdraw(self: ReporterShape, p: Finding, reason: str) -> None:
+        body = complaint.withdraw(self.clock(), reason)
+        self.wire_client.send(p.peer, complaint.message('withdraw', body, self.ks.did, _did(p.peer), thid=p.thid), stored=True)
+        p.withdrawn = True
+        self._persist(p)
+
+    def retract(self: ReporterShape, p: Finding, reason: str) -> Optional[str]:
+        """Withdraw a finding AND take back what it did. Returns the tier restored.
+
+        A withdrawal used to say the accusation was wrong and leave its whole
+        effect standing: the S2 stayed in the ledger, the demotion it earned
+        stayed in force, and the streak stayed broken. Clearing 297 of them off
+        a live mesh still left four peerings at probation that a person had to
+        seed back by hand, which is the whole of the argument that the command
+        was only half a command.
+
+        Not every withdrawal may do this. The ladder is one-way by design, so
+        the line is WHY the finding is going, not that it is:
+
+          - the verdict was wrong - a person says so, or a receipt arrived late
+            and the window was repriced - and the tier it produced goes with it.
+            Nothing is earned; the node returns to where it was before it made
+            a mistake it now admits.
+          - the peer misbehaved and then fixed it. That is the ladder working,
+            and giving the tier back for it would be a two-way ladder bought
+            with a fault, which antifragility.html rules out by name.
+
+        It is refused outright when this node still stands behind something
+        adverse and newer, because then the tier in force is not this finding's
+        doing and is not this finding's to lift.
+        """
+        self._withdraw(p, reason)
+        return self._restore(p)
+
+    def _restore(self: ReporterShape, p: Finding) -> Optional[str]:
+        """Take the window back out of the history, and the tier back off it."""
+        peer, epoch = p.peer, int(p.epoch)
+        was = self.ledger.forget_window(peer, epoch)
+        if self.accounts is not None:
+            self.accounts.put_evaluated(peer, epoch, None)
+        if was is None or was == 'S0':
+            return None
+        if any(e > epoch and sev != 'S0' for e, sev in self.ledger.windows.get(peer) or []):
+            return None
+        governing = self.grants.governing(peer, grants_mod.ISSUED, epoch)
+        before = governing['payload'].get('tier') if governing else None
+        held = self.ledger.tier.get(peer)
+        if not before or not window.outranks(before, held or 'probation'):
+            return None          # never a demotion, and never past where it stood
+        self.ledger.tier[peer] = before
+        if self.regrant is not None:
+            self.regrant(peer, before, self.clock())
+        self.log.append(('restored', peer, epoch, held, before))
+        return before
+
+    def withdraw(self: ReporterShape, peer: str, epoch: int, why: Optional[str] = None) -> Mapping[str, Any] | list[Mapping[str, Any]]:
+        """Withdraw one finding because a person said to.
+
+        Every other path to a withdrawal is the node deciding: a remedy landed
+        and the next window was clean, or the window was repriced. This one is
+        the operator, and it exists because the node cannot always find out on
+        its own that a finding was wrong. The two S2s that made it necessary
+        were about receipts that arrived after their window closed, and by the
+        time that was understood the windows had been priced under a build that
+        could not read them again.
+
+        A published report is not deleted. It carries its own expiration and
+        stands until it lapses; what a withdrawal does is tell the subject, on
+        the thread the notice opened, so the peer holding the accusation hears
+        that it is retracted from the node that made it.
+        """
+        with self._lock:
+            hit = [q for q in self.pending
+                   if q.peer == peer and q.epoch == int(epoch) and not q.withdrawn]
+        if not hit:
+            raise KeyError('no finding held about %s for window %s that is not already withdrawn'
+                           % (peer[:16], epoch))
+        out: list[Mapping[str, Any]] = []
+        for q in hit:
+            published = q.report
+            reason = why or 'withdrawn by the operator'
+            restored = self.retract(q, reason)
+            out.append({'peer': q.peer, 'window': q.epoch, 'was_published': published is not None,
+                        'report': published['id'] if published is not None else None,
+                        'restored': restored, 'why': reason})
+        return out[0] if len(out) == 1 else out
+
+    def tick(self: ReporterShape, now: Optional[int] = None) -> list[tuple[Any, ...]]:
+        """Publish what may be published; withdraw what a fix and a clean window earned.
+        Pending entries that are done - published or withdrawn - are dropped once
+        the report they made has itself expired; the list is not a history."""
+        with self._lock:
+            at = now if now is not None else self.clock()
+            horizon = at - REPORT_TTL
+            # A finding that became a report, or was withdrawn, waits for the
+            # report it made to expire. One that became NEITHER used to wait
+            # forever: the condition required a report or a withdrawal, and an
+            # unpublishable finding - active silence, where the subject signed
+            # nothing that could be cited - has neither and never will. So the
+            # list was not a history, as the line above says, except for
+            # exactly the entries that can never leave it. Four nodes carried
+            # 253 between them, all of them from one outage, none of them ever
+            # to be published, and every future silent window would have added
+            # another.
+            #
+            # Dropping one loses nothing that was doing any work. The remedy it
+            # earned was applied to the grant when the window closed, and
+            # standing/1.0 carries the severity in the ledger; the finding is
+            # only the paperwork for a report that cannot be written. It goes
+            # when the accounting under it goes, which is the point past which
+            # this node could not substantiate it to anyone, itself included.
+            done = []
+            for p in self.pending:
+                if p.done:
+                    if p.opened_at < horizon:
+                        done.append(p)
+                elif p.opened_at < at - FINDING_WINDOWS * (p.window_seconds or 3600):
+                    done.append(p)
+            self.pending = [p for p in self.pending if p not in done]  # not a store: the queue accounts keeps on disk, for persist=DURABLE
+        for p in done:
+            if self.accounts is not None:
+                self.accounts.drop_finding(p.fid)
+        now_val = now if now is not None else self.clock()
+        did: list[tuple[Any, ...]] = []
+        with self._lock:
+            # A finding that could not be published is retried, because a
+            # grant that did not resolve may be a relay that was down. One
+            # that has failed PUBLISH_TRIES times is not: it stays on the
+            # record, unpublished, and stops being attempted. Findings
+            # survive restarts now, so a permanent refusal that kept being
+            # retried logged the same line every half minute for as long as
+            # the node ran, and the list of them grew without bound.
+            todo = [p for p in self.pending if not p.done
+                    and p.tries < PUBLISH_TRIES]
+        for p in todo:
+            # `_notify` puts a complaint on the wire, so a subject whose
+            # descriptor no longer resolves raises here - and used to take
+            # every finding behind it in `todo` with it. Same fault as the
+            # budget's peer loop and the scheduler's before that: one
+            # unreachable peer is not a reason to stop working for the rest.
+            try:
+                did += self._tick_finding(p, now_val)
+            except Exception as e:
+                self.refusals.refuse('finding', 'the subject raised', subject=p.peer,
+                                     detail={'epoch': p.epoch,
+                                             'error': '%s: %s' % (type(e).__name__, e)}, at=now_val)
+                did.append(('finding failed', p.peer, p.epoch, '%s: %s' % (type(e).__name__, e)))
+        return did
+
+    def _tick_finding(self: ReporterShape, p: Finding, now_val: int) -> list[tuple[Any, ...]]:
+        """One finding's share of the tick: notice it, withdraw it, or publish it."""
+        if p.notice_at is None and p.severity in complaint.C['notice_required_for']:
+            # Opened and never noticed: the node stopped between the two.
+            # The notice is what the rule requires, so send it now and
+            # let the window run from here.
+            self._notify(p)
+            return [('noticed', p.peer, p.epoch)]
+        if not complaint.may_publish(p.severity, now_val, p.notice_at, p.window_seconds, reachable=True):
+            return []
+        remedy = p.remedy or {}
+        # fleetmesh_core.peering.complaint.resolve is the reference's reading of a remedy: every
+        # remedy_action but `contested` makes the finding withdraw-eligible.
+        # A local list of fix names restated the same rule and would drift
+        # from constants.remedy_actions on the next addition.
+        if remedy and complaint.resolve(remedy) == 'withdraw-eligible' and self.ledger.clean_windows(p.peer) >= 1:
+            self._withdraw(p, 'remedied: %s, and the next window was clean' % remedy['action'])
+            return [('withdrawn', p.peer, p.epoch)]
+        ev = self.publish(p, now_val)
+        if ev is not None:
+            return [('published', p.peer, p.epoch, ev['id'])]
+        if p.tries >= PUBLISH_TRIES:
+            return [('unpublishable', p.peer, p.epoch, p.severity,
+                     '; '.join(p.unpublishable or [])[:120])]
+        return []

node/planes/peering/reporter/reading.py

@@ -0,0 +1,193 @@
+"""Reading reports about a node, pricing a reporter's word, standing/1.0
+asks, and inbound dispatch for complaint/1.0 and standing/1.0 messages.
+"""
+from __future__ import annotations
+
+import secrets
+from typing import Any, Callable, Mapping, Optional
+from fleetmesh_core.accounting import standing, window  # noqa: E402
+from fleetmesh_core.crypto import giftwrap  # noqa: E402
+from fleetmesh_core.peering import complaint, reports  # noqa: E402
+from fleetmesh_core.wire.interfaces import NostrEvent  # noqa: E402
+from fleetmesh_core.wire import validate  # noqa: E402
+from node.protocols.nostr import client as relay  # noqa: E402
+from .shape import ReporterShape
+
+from fleetmesh_core.identity.did import did_nostr as _did
+
+
+class ReadingMixin:
+    # ---- the complaint, subject side ------------------------------------------
+    def answer_notice(self: ReporterShape, peer: str, msg: Mapping[str, Any], budget: Optional[Any] = None) -> Mapping[str, Any]:
+        """What this node says when accused. If our own meter agrees with their
+        observation we were over and say we will throttle; if it disagrees we
+        contest with our own count. Both are honest; neither erases the window."""
+        body = msg['body']
+        thid = msg.get('thid') or msg['id']
+        self.notices_in[thid] = body          # the oldest thread forgotten at the store's bound
+        ours = None
+        if budget is not None:
+            m = budget.usage_of_me.get(peer, {}).get(body.get('window'))
+            ours = m.snapshot() if m else {}
+        metric = body.get('metric')
+        if ours is not None and body.get('claimed') is not None and ours.get(metric, 0) != body.get('observed'):
+            remedy = complaint.remedy('contested', 'our meter says %s' % ours.get(metric, 0),
+                                      counter_evidence={'counters': ours, 'window': body.get('window')})
+        elif (body.get('observed') or 0) > (body.get('limit') or 0):
+            remedy = complaint.remedy('budget_throttled', 'over the limit on %s; throttling' % metric)
+        else:
+            remedy = complaint.remedy('clock_adjusted', 'no overrun on our side; checking the clock')
+        self.wire_client.send(peer, complaint.message('remedy', dict(remedy), self.ks.did, _did(peer), thid=thid), stored=True)
+        return dict(remedy)
+
+    # ---- reading ----------------------------------------------------------------
+    def _resolver(self: ReporterShape) -> Callable[[str], Optional[NostrEvent]]:
+        cache: dict[str, Optional[NostrEvent]] = {}
+
+        def resolve(eid: str) -> Optional[NostrEvent]:
+            if eid not in cache:
+                found = relay.query_all(self.relays, [{'ids': [eid]}], self.timeout)
+                cache[eid] = found[0] if found else None
+            return cache[eid]
+        return resolve
+
+    def reports_about(self: ReporterShape, target_pk: str) -> list[Mapping[str, Any]]:
+        """Every kind 30802 about a node, with admissibility decided here.
+
+        Reading a report is also the moment this node can price its reporter.
+        A report that is inadmissible is unsupported; one that is admissible
+        but whose own cited numbers do not produce the outcome it claims is
+        refuted. Both are contradicted, both are decidable here alone, and
+        both are what the third term of w(r) counts.
+        """
+        found = relay.query_all(self.relays, [{'kinds': [30802], '#d': [target_pk]}], self.timeout)
+        resolve = self._resolver()
+        out: list[Mapping[str, Any]] = []
+        for ev in found:
+            if not giftwrap.verify_event(ev):
+                continue
+            okay, reasons = reports.admissible(ev, ev['pubkey'], resolve, giftwrap.verify_event)
+            contradicted, why = (True, 'unsupported: %s' % '; '.join(reasons[:2])) if not okay else self._refuted(ev)
+            self.ledger.record_report(ev['pubkey'], ev['id'], contradicted)
+            if self.accounts is not None:
+                self.accounts.put_report_seen(ev['pubkey'], ev['id'], contradicted)
+            for cb in self.on_report_read:
+                cb(ev['pubkey'], target_pk, ev['id'], okay, contradicted)
+            out.append({
+                'event': ev,
+                'reporter': ev['pubkey'],
+                'admissible': okay,
+                'reasons': reasons,
+                'contradicted': contradicted,
+                'why': why,
+                'severity': next((t[1] for t in ev['tags'] if t[0] == 'outcome'), None),
+            })
+        return out
+
+    @staticmethod
+    def _refuted(ev: NostrEvent | Mapping[str, Any]) -> tuple[bool, str]:
+        """(refuted, why) for an admissible report, from its own tags.
+
+        A report states what it measured, what the subject claimed and what
+        the limit was, and the classifier is deterministic, so a reader needs
+        neither the grant nor anyone's agreement to check that the outcome
+        follows. A report that states no numbers is not refutable: it is a
+        finding this reader cannot check, not one it may hold against the
+        reporter.
+        """
+        tags = {t[0]: t for t in ev.get('tags', []) if t}
+        observed, claimed = tags.get('observed'), tags.get('claimed')
+        if not observed or len(observed) < 4:
+            return False, 'no observation to check'
+        try:
+            metric, measured, limit = observed[1], int(observed[2]), int(observed[3])
+            said = int(claimed[2]) if claimed and len(claimed) > 2 else None
+        except (TypeError, ValueError):
+            return False, 'observation is not numeric'
+        got, want = reports.refuted(ev, {metric: limit}, {metric: measured},
+                                    {metric: said} if said is not None else {},
+                                    window.evaluate_window)
+        return got, ('refuted: its own numbers give %s' % want) if got else 'the finding follows from its evidence'
+
+    def weight_of(self: ReporterShape, reporter_pk: str) -> float:
+        """What this node's own ledger says a reporter's word is worth.
+
+        The whole of w(r): the tier this node granted the reporter, how long
+        its clean streak is, and how often its reports have turned out to be
+        unsupported or refuted. That third term had never been passed, so a
+        reporter that filed nothing but refutable findings weighed exactly as
+        much as an honest one, and filing a false report cost nothing - which
+        is the price the attack surface says a reporter pays.
+        """
+        if not self.ledger.knows(reporter_pk):
+            return 0.0
+        contradicted, evaluated = self.ledger.report_record(reporter_pk)
+        return window.reporter_weight(self.ledger.tier[reporter_pk], self.ledger.clean_windows(reporter_pk),
+                                      contradicted, evaluated)
+
+    def view(self: ReporterShape, target_pk: str, own_severity: str = 'S0') -> tuple[str, list[Mapping[str, Any]]]:
+        rs: list[Mapping[str, Any]] = [{'severity': r['severity'], 'weight': self.weight_of(r['reporter'])}
+              for r in self.reports_about(target_pk) if r['admissible'] and r['severity']]
+        return window.view(own_severity, rs), rs
+
+    # ---- standing/1.0 -------------------------------------------------------------
+    def ask_standing(self: ReporterShape, peer_pk: str, target_pk: str, timeout: float = 15.0) -> tuple[Optional[str], Optional[Mapping[str, Any]]]:
+        msg = standing.message('ask', dict(standing.ask(_did(target_pk))), self.ks.did, _did(peer_pk),
+                               mid='standing-ask-%s' % secrets.token_hex(4))
+        reply = self.wire_client.request(peer_pk, msg, timeout=timeout)
+        if reply is None:
+            return None, None
+        return reply.message['type'].rsplit('/', 1)[1], reply.message['body']
+
+    # ---- dispatch -----------------------------------------------------------------
+    def handle_notice(self: ReporterShape, inbound: Any, sender: str, budget: Optional[Any] = None) -> Optional[tuple[Any, ...]]:
+        msg = getattr(inbound, 'message', inbound)
+        why = validate.check_body('complaint', 'notice', msg.get('body'))
+        if why is not None:
+            self.refusals.refuse('notice', why, subject=sender)
+            return ('ignored', sender, 'malformed notice: ' + why)
+        if budget is None:
+            budget = getattr(self, 'budget', None)
+        return ('remedied', sender, self.answer_notice(sender, msg, budget)['action'])
+
+    def handle_remedy(self: ReporterShape, inbound: Any, sender: str) -> Optional[tuple[Any, ...]]:
+        msg = getattr(inbound, 'message', inbound)
+        why = validate.check_body('complaint', 'remedy', msg.get('body'))
+        if why is not None:
+            self.refusals.refuse('remedy', why, subject=sender)
+            return ('ignored', sender, 'malformed remedy: ' + why)
+        thid = msg.get('thid') or msg.get('id')
+        self.remedies_in[thid] = msg['body']
+        with self._lock:
+            hit = [p for p in self.pending if p.thid == thid]
+            for p in hit:
+                p.remedy = msg['body']
+        for p in hit:
+            self._persist(p)
+        return ('remedy', sender, complaint.resolve(msg['body']))
+
+    def handle_withdraw(self: ReporterShape, inbound: Any, sender: str) -> Optional[tuple[Any, ...]]:
+        msg = getattr(inbound, 'message', inbound)
+        why = validate.check_body('complaint', 'withdraw', msg.get('body'))
+        if why is not None:
+            self.refusals.refuse('withdraw', why, subject=sender)
+            return ('ignored', sender, 'malformed withdraw: ' + why)
+        thid = msg.get('thid') or msg.get('id')
+        self.log.append(('withdrawn by', sender, msg['body']))
+        return ('withdrawn', sender, thid)
+
+    def handle_ask(self: ReporterShape, inbound: Any, sender: str) -> Optional[tuple[Any, ...]]:
+        msg = getattr(inbound, 'message', inbound)
+        why = validate.check_body('standing', 'ask', msg.get('body'))
+        if why is not None:
+            self.refusals.refuse('ask', why, subject=sender)
+            return ('ignored', sender, 'malformed ask: ' + why)
+        answer, body = self.ledger.answer(msg['body'], willing=True)
+        self.wire_client.send(sender, standing.message(answer, body, self.ks.did, _did(sender), thid=msg['id']))
+        return ('answered', sender, answer)
+
+    def handle_unknown(self: ReporterShape, inbound: Any, sender: str) -> tuple[Any, ...]:
+        msg = getattr(inbound, 'message', inbound)
+        t = str(msg.get('type', '')) if isinstance(msg, dict) else ''
+        kind = t.rsplit('/', 1)[1] if '/' in t else t
+        return ('ignored', sender, kind)

node/planes/peering/reporter/shape.py

@@ -0,0 +1,86 @@
+"""The shape of a Reporter as its mixins see it.
+
+The one class is split across findings.py, publish.py, reading.py and core.py
+by concern, the same way node/budget/ is split: each mixin method annotates
+`self` as this Protocol so the checker knows what is on it without the mixins
+inheriting from one another or falling back to Any. It is a declaration only;
+Reporter 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 ComplaintNoticeBody, ComplaintRemedyBody, NostrEvent
+from node.compartment import stores as st
+from node.storage import grants as grants_mod
+from node.compartment import Refusals
+from .finding import Finding, LimitDetail
+
+
+class ReporterShape(Protocol):
+    # class attributes on Reporter and Compartment
+    TROUBLE_WINDOW: int
+    # set in Compartment.__init__
+    refusals: Refusals
+    wire_client: Any
+    node: Any
+    # set in Reporter.__init__, in that order
+    regrant: Optional[Callable[[str, str, int], Any]]
+    ks: Any
+    accounts: Optional[Any]
+    project: bool
+    projected: st.Ring[NostrEvent]
+    labeled: st.Ring[NostrEvent]
+    transport: Any
+    grants: grants_mod.GrantStore
+    relays: list[str]
+    ledger: standing.Ledger
+    clock: Callable[[], int]
+    timeout: float
+    _lock: threading.RLock
+    pending: list[Finding]
+    published: st.Ring[NostrEvent]
+    unpublishable: st.Ring[tuple[str, int, str, list[str]]]
+    notices_in: st.Table[str, ComplaintNoticeBody]
+    remedies_in: st.Table[str, ComplaintRemedyBody]
+    log: st.Ring[tuple[Any, ...]]
+    forward_clock: Optional[Callable[[str, int], int]]
+    budget: Optional[Any]
+    on_report_read: list[Callable[[str, str, str, bool, bool], Any]]
+
+    # core.py
+    def _persist(self, p: Finding) -> None: ...
+    @property
+    def rejected(self) -> list[tuple[Optional[str], str, str]]: ...
+
+    # findings.py
+    def _open(self, peer: str, epoch: int, severity: str, evidence: list[Any],
+              worst: Optional[tuple[str, LimitDetail]], source: str,
+              raw: Any) -> Optional[Finding]: ...
+    def _notify(self, p: Finding) -> None: ...
+
+    # publish.py
+    def publish(self, p: Finding, now: Optional[int] = None) -> Optional[NostrEvent]: ...
+    def _project(self, report: NostrEvent, now: int) -> list[NostrEvent]: ...
+    def _note_unpublishable(self, p: Finding, reasons: list[str]) -> None: ...
+    def _withdraw(self, p: Finding, reason: str) -> None: ...
+    def withdraw(self, peer: str, epoch: int, why: Optional[str] = None) -> Mapping[str, Any] | list[Mapping[str, Any]]: ...
+    def retract(self, p: Finding, reason: str) -> Optional[str]: ...
+    def _restore(self, p: Finding) -> Optional[str]: ...
+    def _tick_finding(self, p: Finding, now_val: int) -> list[tuple[Any, ...]]: ...
+
+    # reading.py
+    def _resolver(self) -> Callable[[str], Optional[NostrEvent]]: ...
+    def reports_about(self, target_pk: str) -> list[Mapping[str, Any]]: ...
+    def _refuted(self, ev: Any) -> tuple[bool, str]: ...
+    def weight_of(self, reporter_pk: str) -> float: ...
+    def view(self, target_pk: str, own_severity: str = 'S0') -> tuple[str, list[Mapping[str, Any]]]: ...
+    def ask_standing(self, peer_pk: str, target_pk: str, timeout: float = 15.0) -> tuple[Optional[str], Optional[Mapping[str, Any]]]: ...
+    def answer_notice(self, peer: str, msg: Any, budget: Optional[Any] = None) -> Mapping[str, Any]: ...
+    def handle_notice(self, inbound: Any, sender: str, budget: Optional[Any] = None) -> Optional[tuple[Any, ...]]: ...
+    def handle_remedy(self, inbound: Any, sender: str) -> Optional[tuple[Any, ...]]: ...
+    def handle_withdraw(self, inbound: Any, sender: str) -> Optional[tuple[Any, ...]]: ...
+    def handle_ask(self, inbound: Any, sender: str) -> Optional[tuple[Any, ...]]: ...
+    def handle_unknown(self, inbound: Any, sender: str) -> tuple[Any, ...]: ...

node/planes/peering/reporter/types.py

@@ -0,0 +1,50 @@
+"""Types and records for the Reporter compartment."""
+from __future__ import annotations
+
+from typing import Any, Optional, TypedDict
+
+from fleetmesh_core.wire.interfaces import ComplaintRemedyBody, NostrEvent
+
+
+class LimitDetail(TypedDict, total=False):
+    """One per-limit entry of fleetmesh_core.accounting.window.evaluate's `detail`: what was
+    measured against what limit, and what the subject's receipt claimed."""
+    measured: float
+    claimed: Optional[float]
+    limit: float
+    overrun: float
+    divergence: float
+    severity: str
+
+
+class FindingDict(TypedDict, total=False):
+    """The JSON serialization shape of a Finding."""
+    subject: str
+    severity: str
+    evidence: list[tuple[Any, ...]]
+    worst: Optional[tuple[str, LimitDetail]]
+    source: str
+    grant: str
+    window_seconds: int
+    opened_at: int
+    notice_at: Optional[int]
+    thid: Optional[str]
+    remedy: Optional[ComplaintRemedyBody]
+    report: Optional[NostrEvent]
+    withdrawn: bool
+    why: list[Any]
+    measured: dict[str, float]
+    state: Optional[str]
+    limits: dict[str, float]
+    evidence_partial: bool
+    tries: int
+    unpublishable: Optional[list[str]]
+
+
+class ReporterStateReport(TypedDict):
+    pending: int
+    published: int
+    withdrawn: int
+    noticed: int
+    unpublishable: int
+    malformed: int

node/planes/peering/strain/__init__.py

@@ -0,0 +1,9 @@
+"""What this node has survived, and the reserves it sets.
+
+One-module compartment: everything is in compartment.py.
+"""
+from .compartment import StrainLedger
+from .types import FlagTreeReport, StrainStateReport
+
+__all__ = ['StrainLedger', 'FlagTreeReport', 'StrainStateReport']
+