fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/peering/reporter/core.py

@@ -0,0 +1,299 @@
+"""The Reporter subsystem itself: construction and restore, what survives a
+restart, and the Compartment contract. Separate from the mixins because this is
+where the state they all share is created; the mixins are the concerns that
+act on it.
+"""
+from __future__ import annotations
+
+import dataclasses
+import threading
+from typing import Any, Callable, Mapping, Optional, Sequence
+
+from node.config.parameter import Parameter, ParamBlock
+from node.channels import Channel, NOTE, TROUBLE, bus as eventbus_mod
+from node.metrics import COUNTER, Metric
+from fleetmesh_core.accounting import standing  # noqa: E402
+from fleetmesh_core.peering import complaint  # noqa: E402
+from fleetmesh_core.wire.interfaces import ComplaintNoticeBody, ComplaintRemedyBody, NostrEvent  # noqa: E402
+from node.storage import grants as grants_mod  # noqa: E402
+from node.compartment import stores as st  # noqa: E402
+from node.compartment import Command, Handler, Need, Outbound, WireProtocol  # noqa: E402
+from .constants import FINDING_WINDOWS, KEEP_LOG, KEEP_SIGNED, KEEP_THREADS, KEEP_UNPUBLISHABLE, PUBLISH_TRIES, REPORT_TTL
+from .finding import Finding
+from .findings import FindingsMixin
+from .publish import PublishMixin
+from .reading import ReadingMixin
+from .types import ReporterStateReport
+
+@dataclasses.dataclass(frozen=True)
+class ReporterConfig(ParamBlock):
+    key = 'reporter'
+    name = 'reporter'
+    DERIVED: bool = False
+    PARAMS = (
+        Parameter(
+            key='report_ttl', name='Report TTL',
+            description='Time-to-live in seconds for signed reports',
+            type=int, default=REPORT_TTL, minimum=86400,
+            tags=('reporter', 'retention'),
+        ),
+        Parameter(
+            key='finding_windows', name='Finding Windows Horizon',
+            description='Window horizon for substantiated findings',
+            type=int, default=FINDING_WINDOWS, minimum=1,
+            tags=('reporter', 'history'),
+        ),
+        Parameter(
+            key='publish_tries', name='Publish Tries',
+            description='Maximum publish attempts before finding marked unpublishable',
+            type=int, default=PUBLISH_TRIES, minimum=1,
+            tags=('reporter', 'publish'),
+        ),
+    )
+    report_ttl: int = REPORT_TTL
+    finding_windows: int = FINDING_WINDOWS
+    publish_tries: int = PUBLISH_TRIES
+
+
+class Reporter(FindingsMixin, PublishMixin, ReadingMixin, WireProtocol):
+    """Findings on their way to a report, as a compartment.
+
+    Its refusals are complaint and standing messages without the shape of their
+    type, which were kept in a list nothing rendered. Its trouble is the one an
+    operator most needs and would otherwise never see: a finding this node holds
+    and cannot publish, because the subject signed nothing that window and
+    active silence is unreportable by design.
+    """
+
+    name: str = 'reporter'
+    piuris: tuple[str, ...] = (complaint.PIURI, standing.PIURI)
+    reads: tuple[str, ...] = ('projection',)
+    config_cls = ReporterConfig
+    CHANNELS = (
+        Channel('report_published', 'A signed report was published to relays',
+                level=NOTE, say='published report {report_id} on peer {peer}',
+                tags=('reporter', 'publish')),
+        Channel('report_withdrawn', 'A finding or report was withdrawn by operator',
+                level=NOTE, say='withdrew report on peer {peer} window {window}',
+                tags=('reporter', 'withdraw')),
+        Channel('finding_unpublishable', 'An adverse finding could not be published to relays',
+                level=TROUBLE, say='finding on peer {peer} window {window} unpublishable: {reason}',
+                tags=('reporter', 'trouble')),
+    )
+    METRICS = (
+        Metric(name='reporter_reports_published', description='Reports published.',
+               kind=COUNTER, counts='report_published', tags=('reporter', 'publish')),
+        Metric(name='reporter_reports_withdrawn', description='Reports withdrawn.',
+               kind=COUNTER, counts='report_withdrawn', tags=('reporter', 'withdraw')),
+        Metric(name='reporter_findings_unpublishable', description='Findings unpublishable.',
+               kind=COUNTER, counts='finding_unpublishable', tags=('reporter', 'trouble')),
+    )
+    OUTBOUND = (
+        Outbound('notice', reply='remedy', doc='notify peer of adverse finding'),
+        Outbound('remedy', doc='submit remedy in response to complaint notice'),
+        Outbound('withdraw', doc='withdraw complaint finding'),
+        Outbound('ask', reply=('tell', 'decline'), doc='query peer standing'),
+        Outbound('tell', doc='answer standing query with peer streak'),
+        Outbound('decline', doc='decline standing query'),
+    )
+    HANDLERS = (
+        Handler('notice', run='handle_notice', doc='answer complaint notice'),
+        Handler('remedy', run='handle_remedy', doc='receive complaint remedy'),
+        Handler('withdraw', run='handle_withdraw', doc='receive complaint withdrawal'),
+        Handler('ask', run='handle_ask', doc='answer standing ask from ledger'),
+        Handler('*', run='handle_unknown', doc='ignore unknown complaint or standing kind by name'),
+    )
+    COMMANDS = (
+        Command(
+            key='show',
+            name='Reporter Status',
+            description='findings held, reports published, and what cannot be published at all',
+            tags=('reporter', 'status'),
+            permission='reporter/show',
+            run='state',
+            reply='{pending, published, withdrawn, unpublishable, noticed, malformed}',
+        ),
+        Command(
+            key='withdraw',
+            name='Withdraw Finding',
+            description="withdraw a finding this node made about one window, published or not; the operator's call",
+            tags=('reporter', 'withdraw'),
+            parameters=(
+                Parameter(key='peer', name='peer', description='peer pubkey or did', type=str, default='', required=True),
+                Parameter(key='window', name='window', description='window number', type=int, default=0, required=True),
+                Parameter(key='why', name='why', description='reason for withdrawal', type=str, default=None, required=False),
+            ),
+            permission='reporter/withdraw',
+            run='withdraw_cmd',
+            reply='{peer, window, was_published, report, why}',
+        ),
+    )
+
+    # What it keeps. The three lists of signed events and the log grew by one
+    # per report, score, label or complaint message for the life of the
+    # process, and `remedies_in` - written by any peer that sends a remedy -
+    # was trimmed only when a finding expired. `published` is still counted
+    # whole in `state`, from the ring's inserts. `pending` is not here: it is
+    # the queue `accounts` keeps on disk, for a durable store to declare.
+    STORES = (
+        st.Store(key='published', description='kind 30802 reports this node signed, newest last',
+                 kind=st.RING, shape=dict, bound=KEEP_SIGNED),
+        st.Store(key='projected', description='kind 30385 relay scores this node signed, newest last',
+                 kind=st.RING, shape=dict, bound=KEEP_SIGNED),
+        st.Store(key='labeled', description='kind 1985 labels this node signed, newest last',
+                 kind=st.RING, shape=dict, bound=KEEP_SIGNED),
+        st.Store(key='unpublishable', description='findings it may not publish, as (peer, window, severity, reasons)',
+                 kind=st.RING, shape=tuple, bound=KEEP_UNPUBLISHABLE),
+        st.Store(key='notices_in', description='complaint notices received, where this node is the subject',
+                 kind=st.TABLE, shape=dict, bound=KEEP_THREADS, keyed_by='thid'),
+        st.Store(key='remedies_in', description='remedies received, where this node is the issuer',
+                 kind=st.TABLE, shape=dict, bound=KEEP_THREADS, keyed_by='thid'),
+        st.Store(key='log', description='withdrawals against this node and tiers it restored, newest last',
+                 kind=st.RING, shape=tuple, bound=KEEP_LOG),
+    )
+
+    published: st.Ring[NostrEvent]
+    projected: st.Ring[NostrEvent]
+    labeled: 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, ...]]
+
+    NEEDS = (
+        Need('keystore', 'ks'),
+        Need('transport'),
+        Need('grant_store', 'stores.grants'),
+        Need('relay_urls', 'relays'),
+        Need('ledger'),
+        Need('project', 'cfg', field='projection'),
+        Need('timeout'),
+        Need('accounts', 'stores.accounts'),
+        Need('regrant'),
+        Need('events'),
+        Need('discovery', late=True),
+        Need('budget', late=True),
+    )
+
+    def start(self) -> None:
+        if self.events is not None:
+            events = self.events
+            self.on_report_read.append(lambda *a: events.emit(eventbus_mod.TOPIC_REPORT_ADMITTED, *a))
+
+    def __init__(
+        self,
+        keystore: Any,
+        transport: Any,
+        grant_store: grants_mod.GrantStore,
+        relay_urls: Sequence[str],
+        ledger: Optional[standing.Ledger] = None,
+        clock: Optional[Callable[[], int]] = None,
+        timeout: float = 15.0,
+        node: Optional[Any] = None,
+        project: bool = True,
+        accounts: Optional[Any] = None,
+        regrant: Optional[Callable[[str, str, int], Any]] = None,
+        events: Optional[Any] = None,
+        discovery: Optional[Any] = None,
+        budget: Optional[Any] = None,
+    ) -> None:
+        super().__init__(node, clock)
+        # The node call that re-issues a grant when a tier is restored;
+        # suites that pass a fake node and nothing else get it off that.
+        self.regrant: Optional[Callable[[str, str, int], Any]] = regrant if regrant is not None else getattr(node, 'regrant', None)
+        self.ks: Any = keystore
+        self.accounts: Optional[Any] = accounts  # where pending findings survive a restart; None keeps them in memory
+        self.project: bool = True if project is None else bool(project)    # publish the kind 30385 relay score beside each report
+        self.projected: st.Ring[NostrEvent]      # the kind 30385 events this node put on the relays
+        self.labeled: st.Ring[NostrEvent]        # the kind 1985 NIP-32 labels this node put on the relays
+        self.transport: Any = transport
+        self.grants: grants_mod.GrantStore = grant_store
+        self.relays: list[str] = list(relay_urls)  # not a store: the configured relays
+        self.ledger: standing.Ledger = ledger if ledger is not None else standing.Ledger()
+        self.events: Optional[Any] = events
+        self.discovery: Optional[Any] = discovery
+        self.budget: Optional[Any] = budget
+        self._forward_clock: Optional[Callable[[str, int], int]] = None
+        # After the ledger exists and not before it. This read the store into
+        # `self.ledger` four lines above the line that creates it, so a node
+        # started fresh was fine and a node restarted after it had read one
+        # report of anyone's died on the way up with AttributeError - a crash
+        # loop that only ever reached the nodes doing the most work. Two of a
+        # four-node mesh went down this way at once.
+        if accounts is not None:
+            for reporter, rid, bad in accounts.reports_seen():
+                self.ledger.record_report(reporter, rid, bad)
+        self.timeout: float = timeout
+        self._lock: threading.RLock = threading.RLock()
+        self.pending: list[Finding] = []               # not a store: findings on their way to a report - the queue accounts keeps on disk, for persist=DURABLE
+        self.published: st.Ring[NostrEvent]      # kind 30802 events this node put on the relays
+        self.unpublishable: st.Ring[tuple[str, int, str, list[str]]]  # findings it may not publish: no evidence a reader can check
+        self.notices_in: st.Table[str, ComplaintNoticeBody]      # thid -> notice body received (we are the subject)
+        # Refusals go through the compartment channel. `rejected` stays as a
+        # view in the shape two suites and the health block already read.
+        self.remedies_in: st.Table[str, ComplaintRemedyBody]     # thid -> remedy body received (we are the issuer)
+        self.log: st.Ring[tuple[Any, ...]]
+        self.on_report_read: list[Callable[[str, str, str, bool, bool], Any]] = []   # (reporter, target, id, admissible, contradicted)
+        if accounts is not None:
+            self.pending = [Finding.from_dict(b) for b in accounts.findings()]  # not a store: loaded from accounts, for persist=DURABLE
+
+    @property
+    def forward_clock(self) -> Optional[Callable[[str, int], int]]:
+        if self._forward_clock is not None:
+            return self._forward_clock
+        if getattr(self, 'discovery', None) is not None:
+            return getattr(self.discovery, 'forward_clock', None)
+        return None
+
+    @forward_clock.setter
+    def forward_clock(self, fn: Optional[Callable[[str, int], int]]) -> None:
+        self._forward_clock = fn
+
+    # ---- what survives a restart -------------------------------------------------
+    def _persist(self, p: Finding) -> None:
+        """Write a pending finding down. Called at every change of its state:
+        opened, noticed, remedied, published, unpublishable, withdrawn.
+
+        Four nodes on three machines showed why. Two London nodes priced two
+        peers S2 at a window close, sent the notices, and were restarted eight
+        minutes later for an unrelated fix. The findings, their evidence and
+        the notice threads were memory only. The window passed and the reports
+        the notices had promised never came, and nothing said so.
+        """
+        if self.accounts is None:
+            return
+        self.accounts.put_finding(p.fid, p.peer, p.epoch, p.to_dict())
+
+    # ---- the compartment contract -------------------------------------------------
+    @property
+    def rejected(self) -> list[tuple[Optional[str], str, str]]:
+        return [(r.subject, r.kind, r.why) for r in self.refusals.last(200)]
+
+    def state(self) -> ReporterStateReport:
+        held = [p for p in self.pending if not p.done]
+        return {
+            'pending': len(held),
+            'published': self.published.inserts,
+            'withdrawn': sum(1 for p in self.pending if p.withdrawn),
+            'noticed': sum(1 for p in held if p.notice_at is not None),
+            'unpublishable': len(self.unpublishable),
+            'malformed': len(self.rejected),
+        }
+
+    def trouble(self) -> list[str]:
+        stuck = self.unpublishable
+        if not stuck:
+            return []
+        # The operator's own view of a rule the specification states and nothing
+        # else surfaces: a window of active silence cannot produce a kind 30802,
+        # because the subject signed nothing that window and no reader could
+        # check either half of the claim. The remedy is local and complete.
+        return [
+            '%d finding(s) can never be published - the subject signed nothing those windows. '
+            'The grant is cut locally and standing/1.0 still carries the streak' % len(stuck)
+        ]
+
+    def withdraw_cmd(self, args: Mapping[str, Any]) -> Any:
+        return self.withdraw(str(args['peer']), int(args['window']), args.get('why'))
+
+

node/planes/peering/reporter/finding.py

@@ -0,0 +1,74 @@
+"""A finding on its way to a report, as one record.
+
+The reporter used to carry each pending finding as a dict of twenty-odd
+string keys, mutated by four mixins and thawed from JSON on restart. A key
+misspelt in one mixin read as `None` in the next and nothing said so. This is
+the same record with its fields written down once; the JSON edge is
+`to_dict` / `from_dict`, and everything between the store and the wire reads
+attributes.
+
+The shape is the one `_open` built and `_thaw` read back: JSON made the
+tuples lists, and the code reads evidence entries, the worst limit and
+session findings positionally, so `from_dict` gives them their shape back.
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field, fields
+from typing import Any, Mapping, Optional, cast
+from fleetmesh_core.wire.interfaces import ComplaintRemedyBody, NostrEvent  # noqa: E402
+
+__all__ = ['Finding', 'LimitDetail']
+
+
+from .types import LimitDetail, FindingDict
+
+
+@dataclass(slots=True)
+class Finding:
+    fid: str
+    peer: str
+    epoch: int
+    severity: str
+    # ('receipt', id, receipt) / ('envelope', id, env) / ('event', id) - headed by kind
+    evidence: list[tuple[Any, ...]]
+    # (metric, {'measured', 'limit', 'claimed', ...}) for a per-limit finding; None for silence
+    worst: Optional[tuple[str, LimitDetail]]
+    source: str                                   # 'window' | 'session'
+    grant: str                                    # envelope id of the grant that governed it
+    window_seconds: int
+    opened_at: int
+    notice_at: Optional[int] = None
+    thid: Optional[str] = None                    # the complaint thread the notice opened
+    remedy: Optional[ComplaintRemedyBody] = None  # the subject's remedy body, if one came
+    report: Optional[NostrEvent] = None           # the signed kind 30802, once published
+    withdrawn: bool = False
+    why: list[Any] = field(default_factory=list)  # session findings, read positionally
+    measured: dict[str, float] = field(default_factory=dict)   # metric -> what this node counted
+    state: Optional[str] = None
+    limits: dict[str, float] = field(default_factory=dict)     # metric -> the grant's ceiling
+    evidence_partial: bool = False
+    tries: int = 0                                # publish attempts that came back inadmissible
+    unpublishable: Optional[list[str]] = None     # why the last attempt was refused
+
+    # ---- the JSON edge ---------------------------------------------------------
+    def to_dict(self) -> FindingDict:
+        return cast(FindingDict, asdict(self))
+
+    @classmethod
+    def from_dict(cls, body: Mapping[str, Any]) -> 'Finding':
+        """A finding read back from the store, or built by a test from a
+        plain mapping. Unknown keys are dropped; missing optional ones take
+        their defaults, so a record written by an older build still thaws."""
+        known = {f.name for f in fields(cls)}
+        p = {k: v for k, v in body.items() if k in known}
+        p['evidence'] = [tuple(e) for e in (p.get('evidence') or [])]
+        w = p.get('worst')
+        p['worst'] = (w[0], w[1]) if w else None
+        p['why'] = [tuple(x) if isinstance(x, list) else x for x in (p.get('why') or [])]
+        return cls(**p)
+
+    # ---- what the mixins ask ---------------------------------------------------
+    @property
+    def done(self) -> bool:
+        """Published or withdrawn: nothing further will happen to it."""
+        return self.report is not None or self.withdrawn

node/planes/peering/reporter/findings.py

@@ -0,0 +1,171 @@
+"""Findings in: a window the budget evaluated, or a session the sync layer
+ran. Each is a verdict of fleetmesh_core/'s arithmetic against one peer under one grant
+this node issued, and what happens next is the specification's complaint
+rule, executed.
+"""
+from __future__ import annotations
+
+import secrets
+from typing import Any, Mapping, Optional, cast
+from fleetmesh_core.accounting import accounting, window  # noqa: E402
+from fleetmesh_core.crypto import giftwrap  # noqa: E402
+from fleetmesh_core.peering import complaint, reports  # noqa: E402
+from fleetmesh_core.storage import replication  # noqa: E402
+from node.storage import grants as grants_mod  # noqa: E402
+from node.protocols.nostr import client as relay  # noqa: E402
+from node.planes.peering.budget.evaluation import Evaluation, evaluation_like  # noqa: E402
+from .constants import LIMIT_METRICS
+from .finding import Finding, LimitDetail
+from .shape import ReporterShape
+
+from fleetmesh_core.identity.did import did_nostr as _did
+
+
+class FindingsMixin:
+    # ---- findings in --------------------------------------------------------
+    def on_evaluated(self: ReporterShape, rec: Evaluation | Mapping[str, Any]) -> Optional[Finding]:
+        """A window the budget closed. Adverse outcomes become pending reports."""
+        rec = evaluation_like(rec)
+        sev = rec.severity
+        if sev not in reports.ADVERSE:
+            return None
+        detail = rec.detail
+        worst: Optional[tuple[str, LimitDetail]] = None
+        for name, d in detail.items():
+            # per-limit entries carry a measurement; the silence entry carries none
+            if isinstance(d, dict) and d.get('severity') == sev and 'measured' in d:
+                worst = (str(name), cast(LimitDetail, d))
+                break
+        # The subject's own signed claim, carried whole. A head alone resolves to
+        # nothing: no relay serves a receipt.
+        #
+        # Only the gap-free, chain-verified prefix is carried. The budget
+        # stores a receipt that arrived after a lost link (docs/mechanisms.md
+        # 9g), but a verifier holds cited chains to fleetmesh_core.accounting.verify_chain,
+        # which is strict, so a report that attached the stored list whole
+        # was inadmissible whenever the wire had dropped one receipt. What is
+        # cut is noted on the pending record as evidence_partial.
+        signed = [r for r in rec.receipts if accounting.verify_receipt(r, rec.peer)]
+        admissible, partial = accounting.admissible_prefix(signed)
+        evidence = [('receipt', reports.evidence_id(r), r) for r in admissible]
+        raw = dict(rec.to_dict(), evidence_partial=partial)
+        return self._open(rec.peer, rec.epoch, sev, evidence, worst, 'window', raw)
+
+    def on_repriced(self: ReporterShape, peer: str, epoch: int, was: str, severity: str) -> Optional[list[tuple[str, int]]]:
+        """A window this node priced was read again and came out lower, because
+        the subject's receipt for it arrived after the grace had run.
+
+        The finding that window raised is no longer this node's finding. An
+        unpublished one is dropped before it can become a public record; a
+        published one is withdrawn, which is what complaint/1.0 has a withdraw
+        for and what this node already does when a remedy lands and the next
+        window is clean. Left alone it would stand for the whole of REPORT_TTL
+        as a permanent record of a delivery gap.
+
+        Only a correction to S0 withdraws. A reading that is milder but still
+        adverse leaves the report standing rather than replacing it with a
+        second one about the same window, which is the same strict direction
+        the budget takes when it declines to cancel a remedy it cannot rebuild.
+        """
+        if severity in reports.ADVERSE:
+            return None
+        with self._lock:
+            hit = [q for q in self.pending
+                   if q.peer == peer and q.epoch == epoch and not q.withdrawn]
+        why = 'repriced %s after a receipt for that window arrived late' % was
+        out: list[tuple[str, int]] = []
+        for q in hit:
+            if q.report is None and not q.thid:
+                # Nothing was ever said about it: no notice, no report. There
+                # is no one to tell, so telling no one is the withdrawal - but
+                # the standing it cost is still this node's to give back.
+                with self._lock:
+                    q.withdrawn = True
+                self._persist(q)
+                self._restore(q)
+            else:
+                # A receipt arrived late and the window was repriced: the
+                # verdict was wrong about a fact, so it takes its tier with it.
+                self.retract(q, why)
+            out.append((q.peer, q.epoch))
+        return out
+
+    def on_session(self: ReporterShape, peer: str, role: str, result: Mapping[str, Any]) -> Optional[Finding]:
+        """A sync session ended. Its S3 findings carry the events themselves."""
+        if role != 'initiator':
+            return None
+        worst = max((f[0] for f in result.get('findings', [])), default='S0', key=window.SEV_ORDER.index)
+        if worst not in reports.ADVERSE:
+            return None
+        # An envelope citation carries the signed hop; a public event needs
+        # only its id. Both are tuples headed by the kind.
+        evidence: list[tuple[Any, ...]] = []
+        for item in result.get('evidence', []):
+            ev, env = (item.get('event'), item.get('envelope')) if isinstance(item, dict) else (item, None)
+            # The envelope is the better citation: the peer signed the hop even
+            # when somebody else wrote the event, so it proves the peer sent this.
+            if env is not None and replication.signed_by(env, peer):
+                evidence.append(('envelope', reports.evidence_id(env), env))
+            elif ev is not None and giftwrap.verify_event(ev) and ev.get('pubkey') == peer:
+                evidence.append(('event', ev['id']))
+                relay.publish_all(self.relays, ev, self.timeout)      # a public event needs no copy
+        row = self.grants.get(peer, grants_mod.ISSUED)
+        epoch = self.clock() // ((row['payload'].get('window') if row else None) or 3600)
+        return self._open(peer, epoch, worst, evidence, None, 'session', result)
+
+    def _open(
+        self: ReporterShape,
+        peer: str,
+        epoch: int,
+        severity: str,
+        evidence: list[Any],
+        worst: Optional[tuple[str, LimitDetail]],
+        source: str,
+        raw: Mapping[str, Any],
+    ) -> Optional[Finding]:
+        row = self.grants.get(peer, grants_mod.ISSUED)
+        if row is None:
+            return None
+        now = self.clock()
+        # A window is reported under the grant that governed it, which the
+        # budget names; the published report had named the current grant while
+        # its evidence was a receipt under the one before.
+        p = Finding(
+            fid=secrets.token_hex(8),
+            peer=peer, epoch=epoch, severity=severity, evidence=evidence, worst=worst,
+            source=source, grant=(raw.get('grant') if source == 'window' else None) or row['envelope_id'],
+            window_seconds=row['payload'].get('window', 3600),
+            opened_at=now,
+            why=[f for f in raw.get('findings', [])] if source == 'session' else [],
+            measured=raw.get('measured') or {}, state=raw.get('state'),
+            limits=dict((raw.get('limits') if source == 'window' else None) or row['payload'].get('limits', {})),
+            evidence_partial=bool(raw.get('evidence_partial', False)),
+        )
+        with self._lock:
+            self.pending.append(p)
+        self._persist(p)
+        if severity in complaint.C['notice_required_for']:
+            self._notify(p)
+        elif severity in complaint.C['immediate']:
+            self.publish(p, now)      # may return None: see publish()
+        return p
+
+    # ---- the complaint, issuer side -------------------------------------------
+    def _notify(self: ReporterShape, p: Finding) -> None:
+        worst = p.worst
+        if worst is None:
+            # No per-limit finding: active silence. Name the metric that moved most.
+            moved = {k: v for k, v in p.measured.items() if k in LIMIT_METRICS}
+            metric = max(moved, key=lambda k: moved[k]) if moved else 'bytes_in'
+            detail: LimitDetail = {'measured': moved.get(metric, 0), 'limit': p.limits.get(metric, 0), 'claimed': None}
+            why = 'traffic measured and no receipt: active silence'
+        else:
+            metric, detail = worst
+            why = '; '.join(str(w) for w in p.why)[:200]
+        body = complaint.notice(p.severity, p.grant, p.epoch, metric, detail, self.clock(),
+                                p.window_seconds, description=why)
+        # ref builds a typed body; the DIDComm envelope takes the plain mapping.
+        msg = complaint.message('notice', dict(body), self.ks.did, _did(p.peer), mid='complaint-%s' % secrets.token_hex(4))
+        self.wire_client.send(p.peer, msg, stored=True)
+        p.notice_at, p.thid = self.clock(), msg['id']
+        self._persist(p)