ucomm 0.0.1__py3-none-any.whl

ucomm/__init__.py

@@ -0,0 +1,56 @@
+"""ucomm: universal communicator middleware for Ethereum Swarm (working title)."""
+
+from .attention import Decision, Intensity, PolicyState, SenderContext, decide
+from .contact import ContactCard, make_contact_card, verify_contact_card
+from .daemon import (
+    ChannelDirectory,
+    Dashboard,
+    DashboardItem,
+    DirectoryEntry,
+    build_dashboard,
+    directory_read_state,
+)
+from .envelope import AttentionClaim, Envelope, EventKind, Genesis, GenesisError, TimeWindow
+from .hints import HintSink, HintSource, InMemoryHints
+from .log import AuthorLog, merge_causal, read_state
+from .rendezvous import InMemoryRendezvous, Rendezvous
+from .signing import InvalidSignature, address_of, sign_envelope, verify_envelope
+from .store import RecordStoreAuthorLog, envelope_to_record, record_to_envelope
+
+__all__ = [
+    "AttentionClaim",
+    "AuthorLog",
+    "ChannelDirectory",
+    "ContactCard",
+    "Dashboard",
+    "DashboardItem",
+    "Decision",
+    "DirectoryEntry",
+    "Envelope",
+    "EventKind",
+    "Genesis",
+    "GenesisError",
+    "HintSink",
+    "HintSource",
+    "InMemoryHints",
+    "InMemoryRendezvous",
+    "Intensity",
+    "InvalidSignature",
+    "PolicyState",
+    "RecordStoreAuthorLog",
+    "Rendezvous",
+    "SenderContext",
+    "TimeWindow",
+    "address_of",
+    "build_dashboard",
+    "decide",
+    "directory_read_state",
+    "envelope_to_record",
+    "make_contact_card",
+    "merge_causal",
+    "read_state",
+    "record_to_envelope",
+    "sign_envelope",
+    "verify_contact_card",
+    "verify_envelope",
+]

ucomm/attention.py

@@ -0,0 +1,116 @@
+"""Attention layer: priority algebra and policy engine (ATTENTION.md).
+
+Pure and deterministic by design: decide(envelope, policy, now) -> Decision is a
+function of its arguments only. All mutable state (ceilings, offsets, thresholds,
+reputation ratchet) lives in PolicyState, owned by the daemon.
+
+Receiver sovereignty: this module consumes AttentionClaim data and never
+constructs envelopes. One-way dependency: attention -> envelope, never reverse.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import IntEnum
+
+from .envelope import Envelope, EventKind, PubKey
+
+
+class Intensity(IntEnum):
+    """Graded notification output (ATTENTION.md section 3)."""
+
+    FILED = 0        # silently filed; dashboard history only
+    BADGE = 1        # badge / dashboard, no interruption
+    SOFT = 2         # ring once / vibrate only
+    FULL = 3         # full alert
+    BREAKTHROUGH = 4 # overrides DND
+
+
+# Residual thresholds for grading, in log-scale priority units.
+SOFT_BAND = 5          # |residual| <= SOFT_BAND counts as "near threshold"
+BREAKTHROUGH_MARGIN = 20
+
+
+@dataclass(frozen=True)
+class PolicyState:
+    """Receiver-local policy snapshot. Never published, never negotiated."""
+
+    threshold: int  # current global threshold; DND = high value
+    default_ceiling_known: int = 40
+    default_ceiling_stranger: int = 0
+    wot_ceiling_slope: int = 10  # ceiling = base - slope * wot_distance (ATTENTION 5)
+    contact_ceilings: Mapping[PubKey, int] = field(default_factory=dict)
+    channel_offsets: Mapping[str, int] = field(default_factory=dict)
+    endpoint_offset: int = 0  # e.g. raised while in an interactive session
+    bond_credit: int = 10  # credibility bonus when valid collateral attached
+
+
+@dataclass(frozen=True)
+class SenderContext:
+    """What the receiver knows about the sender (from identity/WoT + recsys)."""
+
+    known_contact: bool
+    wot_distance: int | None = None  # None = no path
+    recsys_prior: int = 0  # advisory prior from RECOMMENDATION.md section 6
+    collateral_valid: bool = False
+
+
+@dataclass(frozen=True)
+class Decision:
+    intensity: Intensity
+    effective_priority: int
+    residual: int
+    ceiling_applied: int
+
+
+def ceiling_for(sender: PubKey, ctx: SenderContext, policy: PolicyState) -> int:
+    """Per-sender priority ceiling (ATTENTION.md sections 2, 5)."""
+    if sender in policy.contact_ceilings:
+        return policy.contact_ceilings[sender]
+    if ctx.known_contact:
+        return policy.default_ceiling_known
+    if ctx.wot_distance is not None:
+        base = policy.default_ceiling_known
+        return max(
+            policy.default_ceiling_stranger,
+            base - policy.wot_ceiling_slope * ctx.wot_distance + ctx.recsys_prior,
+        )
+    return policy.default_ceiling_stranger + ctx.recsys_prior
+
+
+def decide(env: Envelope, ctx: SenderContext, policy: PolicyState, now: float) -> Decision:
+    """Map one control-plane envelope to a graded notification intensity.
+
+    Pure function: (envelope, sender context, policy state, clock) -> Decision.
+    """
+    if env.kind is not EventKind.INVITATION or env.attention is None:
+        return Decision(Intensity.FILED, 0, -(10**6), 0)
+
+    claim = env.attention
+    if not claim.relevance.active(now):
+        return Decision(Intensity.FILED, 0, -(10**6), 0)  # expired -> timeline
+
+    cap = ceiling_for(env.author, ctx, policy)
+    credibility = policy.bond_credit if ctx.collateral_valid else 0
+
+    effective = (
+        min(claim.claimed_priority, cap)
+        + policy.channel_offsets.get(env.channel, 0)
+        + policy.endpoint_offset
+        + credibility
+    )
+    residual = effective - policy.threshold
+
+    if residual > BREAKTHROUGH_MARGIN:
+        intensity = Intensity.BREAKTHROUGH
+    elif residual > SOFT_BAND:
+        intensity = Intensity.FULL
+    elif residual > 0:
+        intensity = Intensity.SOFT
+    elif residual > -SOFT_BAND:
+        intensity = Intensity.BADGE
+    else:
+        intensity = Intensity.FILED
+
+    return Decision(intensity, effective, residual, cap)

ucomm/bee.py

@@ -0,0 +1,51 @@
+"""Real Swarm-backed author logs (M1).
+
+Thin adapter from `RecordStoreAuthorLog` (`ucomm.store`) to recordstore's Bee
+backends -- `BeeBytesStore` + `SwarmFeedPointer` -- instead of the in-memory
+ones used for M0 prototyping. This is the "drop-in swap, not a rewrite"
+ROADMAP.md promised: `RecordStoreAuthorLog` only ever needed a
+`recordstore.RecordStore`; it never knew or cared whether that store was
+backed by memory or a live Bee node.
+
+Feeds need an IMMUTABLE postage batch (see CLAUDE.md, "Swarm facts to
+respect"). This module never buys one -- pass an existing usable batch id
+(`GET /stamps` on the target node), bought e.g. with
+`POST /stamps/{amount}/{depth}?immutable=true` or swarmfs's `StampManager`.
+"""
+
+from __future__ import annotations
+
+from recordstore import BeeBytesStore, RecordStore, SwarmFeedPointer
+
+from .envelope import ChannelId, PubKey
+from .signing import address_of
+from .store import RecordStoreAuthorLog
+
+
+def feed_topic(channel: ChannelId, author: PubKey) -> str:
+    """Feed topic namespacing one author's per-channel log."""
+    return f"ucomm/log/{channel}/{author}"
+
+
+def open_author_feed_log(
+    api_url: str, channel: ChannelId, *, signer_hex: str, postage_batch_id: str,
+) -> tuple[RecordStore, RecordStoreAuthorLog]:
+    """Open `signer_hex`'s own log for `channel`, backed by a real Swarm feed.
+
+    `signer_hex` is the author's private key (hex); the feed owner (and
+    hence `Envelope.author`, via `ucomm.signing.address_of`) is derived from
+    it. Returns `(store, log)`: append through `log`, then call
+    `store.commit()` to actually publish -- appends are staged locally until
+    then, same as any other `RecordStore` (issue K-4's batching model, not a
+    new one for Bee).
+    """
+    from bee.swarm.keys import PrivateKey
+
+    author: PubKey = address_of(PrivateKey.from_hex(signer_hex))
+    pointer = SwarmFeedPointer(
+        api_url, feed_topic(channel, author),
+        signer=signer_hex, postage_batch_id=postage_batch_id,
+    )
+    bytes_store = BeeBytesStore(api_url, postage_batch_id=postage_batch_id)
+    store = RecordStore(bytes_store, pointer=pointer)
+    return store, RecordStoreAuthorLog(store, channel, author)

ucomm/bridges/__init__.py

@@ -0,0 +1,8 @@
+"""Bridges: adapters converting external protocols into ucomm envelopes.
+
+DESIGN.md section 10: every bridge is an inbox adapter into the same
+envelope schema and policy engine ucomm uses natively -- the "attention
+firewall" is a unified inbox across everything, not just Swarm-native
+channels. Kept out of the top-level `ucomm` namespace, same reasoning as
+`ucomm.profiles`: a layer above the kernel, not part of it.
+"""

ucomm/bridges/imap.py

@@ -0,0 +1,215 @@
+"""IMAP bridge: envelope adapter for email (issue D-5).
+
+DESIGN.md section 10: bridges convert an external protocol's events into
+the same envelope schema and policy engine ucomm uses natively, so the
+attention firewall covers inboxes that already exist. This module has two
+layers:
+
+- **Pure conversion** (`envelope_from_email`, `invitation_for_email`,
+  `bridge_author`): raw email -> envelope(s), fully offline and
+  unit-testable with synthetic messages (stdlib `email` objects) -- no
+  network. This is the part with real test coverage against arbitrary
+  input.
+- **Live fetch** (`ImapMailbox`): connects to a real mailbox via
+  `IMAPClient` (per CLAUDE.md's "use established libraries, not raw
+  `imaplib`" convention) and calls the pure layer per message. This part
+  is only unit-tested against a fake client double -- it hasn't been
+  verified against a real IMAP server yet (no test mailbox available when
+  this was written), the same caveat `ucomm.bee` had before its first live
+  Bee run.
+
+Bridged authorship is NOT the same guarantee as a native ucomm signature.
+An email's `From:` address is only as trustworthy as SMTP/DKIM made it --
+ucomm doesn't re-verify that. Bridged envelopes are left unsigned
+(`sig=""`); `verify_envelope` on one is always `False`, honestly, never
+silently treated as verified.
+
+Every bridged email gets a paired `INVITATION` (DESIGN.md section 3.2, two
+planes -- the message body is content, the invitation is a small pointer
+to it, `refs`-only, no payload duplication) with a naive default
+`AttentionClaim`. That claim is exactly as advisory as any sender's claim
+ever is (CLAUDE.md invariant 1): the receiver's own policy engine decides
+how loud a bridged email actually is, not the quality of this default.
+
+This bridge is read-only by design (IMAP fetch only, `select_folder(...,
+readonly=True)`) -- it ingests existing mail into the unified dashboard,
+it does not send. Composing/replying would need SMTP, a distinct and
+separate capability this module doesn't provide.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from email import message_from_bytes
+from email.message import Message
+from email.utils import parsedate_to_datetime
+from typing import cast
+
+from imapclient import IMAPClient
+
+from ..envelope import (
+    AttentionClaim,
+    ChannelId,
+    Envelope,
+    EventHash,
+    EventKind,
+    MediaDescriptor,
+    PubKey,
+    TimeWindow,
+)
+
+_BRIDGE_AUTHOR_PREFIX = "bridge:imap:"
+
+DEFAULT_RELEVANCE_SECONDS = 7 * 24 * 3600  # a week: mail is async, not urgent by default
+
+
+def bridge_author(email_address: str) -> PubKey:
+    """A deterministic, clearly-namespaced pseudo-author for a bridged sender.
+
+    Not a real signing key's address -- visibly different in shape (a
+    `bridge:imap:` prefix) so it can never be confused with, or collide
+    with, one. Bridged envelopes are unsigned; nothing should treat this
+    as an authenticated identity.
+    """
+    digest = hashlib.sha256(email_address.strip().lower().encode("utf-8")).hexdigest()
+    return f"{_BRIDGE_AUTHOR_PREFIX}{digest}"
+
+
+def _extract_body(msg: Message) -> tuple[str, str]:
+    """Return (mime type, text) for the best available non-attachment part.
+
+    Prefers text/plain over text/html, matching the mail profile's
+    text-only media declaration; either can be added properly (real
+    multipart/attachment media kinds) once a profile needs it.
+    """
+    if msg.is_multipart():
+        for wanted in ("text/plain", "text/html"):
+            for part in msg.walk():
+                if part.get_content_type() == wanted and not part.get_filename():
+                    # get_payload(decode=True) always returns bytes|None here;
+                    # the stub's wider return type doesn't narrow on `decode`.
+                    payload = cast("bytes | None", part.get_payload(decode=True)) or b""
+                    charset = part.get_content_charset() or "utf-8"
+                    return wanted, payload.decode(charset, errors="replace")
+        return "text/plain", ""
+    payload = cast("bytes | None", msg.get_payload(decode=True)) or b""
+    charset = msg.get_content_charset() or "utf-8"
+    return msg.get_content_type() or "text/plain", payload.decode(charset, errors="replace")
+
+
+def _received_at(msg: Message, *, default: float) -> float:
+    date_header = msg.get("Date")
+    if date_header:
+        try:
+            return parsedate_to_datetime(date_header).timestamp()
+        except (TypeError, ValueError):
+            pass
+    return default
+
+
+def envelope_from_email(
+    msg: Message, channel: ChannelId, seq: int, refs: tuple[EventHash, ...] = (),
+) -> Envelope:
+    """Convert one email into a `MESSAGE` envelope. Pure; no network."""
+    sender = msg.get("From", "")
+    mime, body = _extract_body(msg)
+    return Envelope(
+        channel=channel, author=bridge_author(sender), seq=seq,
+        kind=EventKind.MESSAGE, refs=refs,
+        media=MediaDescriptor(mime=mime), inline=body.encode("utf-8"),
+    )
+
+
+def invitation_for_email(
+    msg: Message, channel: ChannelId, seq: int, message_hash: EventHash, now: float,
+    *, importance: int = 5, urgency: int = 5,
+    relevance_seconds: float = DEFAULT_RELEVANCE_SECONDS,
+) -> Envelope:
+    """The paired attention request for a bridged email.
+
+    `refs=(message_hash,)` only -- a small pointer to the message envelope,
+    never the body itself (two planes, CLAUDE.md invariant 3). `now` is the
+    fallback "received at" when the email has no parseable `Date:` header.
+    """
+    sender = msg.get("From", "")
+    received = _received_at(msg, default=now)
+    return Envelope(
+        channel=channel, author=bridge_author(sender), seq=seq,
+        kind=EventKind.INVITATION, refs=(message_hash,),
+        attention=AttentionClaim(
+            importance=importance, urgency=urgency,
+            relevance=TimeWindow(start=received, end=received + relevance_seconds),
+        ),
+    )
+
+
+class ImapMailbox:
+    """Live IMAP fetch loop: pulls new mail via `IMAPClient` and converts
+    each message with the pure functions above.
+
+    Uses UIDs, not sequence numbers, to track what's new -- UIDs are
+    stable across sessions per IMAP semantics, sequence numbers aren't.
+    Fetch state (last-seen UID, next `seq` per bridged author) lives on
+    this object, in-process only; persisting it across restarts (so a
+    fresh run doesn't re-fetch everything) is separate, not-yet-built
+    work -- the same "in-memory first" step `AuthorLog` went through
+    before `RecordStoreAuthorLog`.
+    """
+
+    def __init__(self, client: IMAPClient, channel: ChannelId) -> None:
+        self._client = client
+        self.channel = channel
+        self._last_uid: int | None = None
+        self._next_seq: dict[PubKey, int] = {}
+
+    @classmethod
+    def connect(
+        cls, host: str, username: str, password: str, channel: ChannelId,
+        *, folder: str = "INBOX", port: int | None = None, ssl: bool = True,
+    ) -> ImapMailbox:
+        """Connect, log in, and select `folder` read-only -- this bridge
+        only ever reads (see the module docstring: composing/sending
+        would need SMTP, which this doesn't provide)."""
+        client = IMAPClient(host, port=port, ssl=ssl, use_uid=True)
+        client.login(username, password)
+        client.select_folder(folder, readonly=True)
+        return cls(client, channel)
+
+    def close(self) -> None:
+        self._client.logout()
+
+    def fetch_new(self, now: float) -> list[Envelope]:
+        """Fetch and convert messages newer than the last call.
+
+        Advances internal state; safe to call repeatedly as a poll loop.
+        Returns a flat `[message, invitation, message, invitation, ...]`
+        list, in the shape `ucomm.daemon.build_dashboard`/
+        `directory_read_state` already expect as one channel's events.
+        """
+        uids = self._new_uids()
+        if not uids:
+            return []
+        fetched = self._client.fetch(uids, ["RFC822"])
+        envelopes: list[Envelope] = []
+        for uid in uids:
+            msg = message_from_bytes(fetched[uid][b"RFC822"])
+            author = bridge_author(msg.get("From", ""))
+            seq = self._next_seq.get(author, 1)
+            message_env = envelope_from_email(msg, self.channel, seq)
+            invitation = invitation_for_email(
+                msg, self.channel, seq + 1, message_env.event_hash(), now,
+            )
+            envelopes.extend((message_env, invitation))
+            self._next_seq[author] = seq + 2
+            self._last_uid = uid
+        return envelopes
+
+    def _new_uids(self) -> list[int]:
+        if self._last_uid is None:
+            return sorted(self._client.search(["ALL"]))
+        uids = self._client.search(["UID", f"{self._last_uid + 1}:*"])
+        # RFC 3501 section 9: a "n:*" range is defined to include the
+        # mailbox's highest UID even when nothing is actually >= n --
+        # filter that back out rather than re-processing the top message
+        # on every poll that finds nothing new.
+        return sorted(uid for uid in uids if uid > self._last_uid)

ucomm/contact.py

@@ -0,0 +1,83 @@
+"""Out-of-band contact exchange (M1).
+
+Before any channel exists, two parties need a minimal way to hand each
+other an address they can trust really corresponds to a key someone
+controls, over a transport with no verification of its own -- a pasted
+string, a QR code, a business card. `ContactCard` is that minimum: an
+address plus a self-attestation signature, domain-separated from envelope
+signing so a card can never be replayed as (or forged from) a signed
+envelope. It catches a copy/paste error or an active tamperer on the
+exchange channel before any channel or message exists.
+
+This is deliberately NOT the identity-wot library (ROADMAP.md: root keys,
+device delegation, petnames, attestations -- a standalone project tracking
+the ecosystem "Swarm ID" work). No delegation, no petnames (DESIGN.md
+section 7: petnames are local, never part of what's exchanged), no
+rendezvous (that's issue K-5 / milestone M3, for *unsolicited* contact --
+this is for two parties already coordinating out-of-band). Just: prove
+control of an address before anyone builds a channel around it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from bee.swarm.errors import BeeError
+from bee.swarm.keys import PrivateKey, verify_signature
+from bee.swarm.typed_bytes import EthAddress, Signature
+
+from .envelope import PubKey
+from .signing import address_of
+
+_DOMAIN = b"ucomm-contact-card-v1:"
+_STR_PREFIX = "ucomm-contact-v1:"
+
+
+def _card_bytes(address: PubKey) -> bytes:
+    """Domain-separated from `ucomm.signing`'s envelope bytes: an envelope
+    signature can never be replayed as a contact card, or vice versa."""
+    return _DOMAIN + address.encode("ascii")
+
+
+@dataclass(frozen=True)
+class ContactCard:
+    """A self-attested address: proof its holder controls the signing key.
+
+    Not proof of *who* holds it -- that's for the receiver's own local
+    petname/WoT judgment (DESIGN.md section 7), never something a card
+    asserts about itself.
+    """
+
+    address: PubKey
+    sig: str
+
+    def to_str(self) -> str:
+        """Compact form safe to paste, email, or encode as a QR code."""
+        return f"{_STR_PREFIX}{self.address}:{self.sig}"
+
+    @classmethod
+    def from_str(cls, s: str) -> ContactCard:
+        if not s.startswith(_STR_PREFIX):
+            raise ValueError(f"not a ucomm contact card: {s!r}")
+        rest = s[len(_STR_PREFIX):]
+        address, sep, sig = rest.partition(":")
+        if not sep:
+            raise ValueError(f"malformed contact card: {s!r}")
+        return cls(address=address, sig=sig)
+
+
+def make_contact_card(key: PrivateKey) -> ContactCard:
+    """Self-attest `key`'s address: proof of control, not proof of identity."""
+    address = address_of(key)
+    signature = key.sign(_card_bytes(address))
+    return ContactCard(address=address, sig=signature.to_hex())
+
+
+def verify_contact_card(card: ContactCard) -> bool:
+    """True iff `card.sig` really proves control of `card.address`."""
+    try:
+        signature = Signature.from_hex(card.sig)
+        expected = EthAddress.from_hex(card.address)
+    except BeeError:
+        return False
+    return verify_signature(signature, _card_bytes(card.address), expected)

ucomm/daemon.py

@@ -0,0 +1,149 @@
+"""Notification daemon core: channel directory + graded dashboard (M2).
+
+DESIGN.md section 10: the user keeps a private channel directory (every
+channel they participate in, across all apps, with local per-channel policy
+overrides); one notification daemon per device computes effective priority
+over it and emits a graded dashboard -- active requests ordered by priority
+(including sub-threshold ones, silently filed), plus an obsolete timeline for
+expired ones.
+
+Resolves the open question in DESIGN.md section 12: the dashboard is a
+projection, not authoritative state. `build_dashboard` is a pure function of
+(directory, channel events, policy, sender contexts, clock) -- like
+`ucomm.attention.decide`, its output is never stored, only recomputed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Mapping
+from dataclasses import dataclass
+
+from .attention import Decision, PolicyState, SenderContext, decide
+from .envelope import ChannelId, Envelope, EventHash, EventKind, PubKey
+from .log import merge_causal, read_state
+
+
+@dataclass(frozen=True)
+class DirectoryEntry:
+    """One participated channel, with local-only policy overrides.
+
+    Mute is a large negative `channel_offset`, not a separate mechanism
+    (ATTENTION.md section 2 / DESIGN.md section 11) -- so there's no
+    `muted` field here to duplicate it.
+    """
+
+    channel: ChannelId
+    profile: str | None = None
+    channel_offset: int = 0
+
+
+class ChannelDirectory:
+    """Every channel the user participates in, across all apps (DESIGN.md
+    section 10). Purely local and private: never signed, never synced --
+    unlike the channels it lists, the directory itself has no merge rule,
+    because there's exactly one writer, the local user.
+    """
+
+    def __init__(self) -> None:
+        self._entries: dict[ChannelId, DirectoryEntry] = {}
+
+    def add(self, entry: DirectoryEntry) -> None:
+        self._entries[entry.channel] = entry
+
+    def remove(self, channel: ChannelId) -> None:
+        self._entries.pop(channel, None)
+
+    def __iter__(self) -> Iterator[DirectoryEntry]:
+        return iter(self._entries.values())
+
+    def __contains__(self, channel: ChannelId) -> bool:
+        return channel in self._entries
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    @property
+    def channel_offsets(self) -> dict[ChannelId, int]:
+        """Directory-derived offsets, ready to merge into a `PolicyState`."""
+        return {e.channel: e.channel_offset for e in self._entries.values()}
+
+
+@dataclass(frozen=True)
+class DashboardItem:
+    channel: ChannelId
+    envelope: Envelope
+    decision: Decision
+
+
+@dataclass(frozen=True)
+class Dashboard:
+    """A graded view over active/obsolete attention requests -- a
+    projection, never persisted (DESIGN.md section 12)."""
+
+    active: tuple[DashboardItem, ...]    # relevance still active; sorted by
+                                          # effective_priority, highest first
+    obsolete: tuple[DashboardItem, ...]  # relevance window has passed
+
+
+def build_dashboard(
+    directory: ChannelDirectory,
+    channel_events: Mapping[ChannelId, Iterable[Envelope]],
+    policy: PolicyState,
+    sender_contexts: Mapping[PubKey, SenderContext],
+    now: float,
+    *,
+    default_sender_context: SenderContext | None = None,
+) -> Dashboard:
+    """Compute the dashboard fresh from current state.
+
+    Never store the result -- call this again next time. It's cheap, and
+    recomputing is the only way the dashboard can't drift from the channels
+    and policy it's derived from (same discipline as `decide()` itself).
+
+    Only `INVITATION` envelopes carrying an `AttentionClaim` are dashboard
+    material -- ordinary messages aren't "requests" in DESIGN.md section 10's
+    sense and are silently skipped, matching `decide()`'s own treatment of
+    them (a trivial FILED sentinel) rather than cluttering the timeline.
+
+    Callers pass unmerged events (e.g. every member's raw log); each
+    channel's stream is merged internally, so a duplicate delivery or an
+    event reachable through two members' logs is counted once, not twice.
+    """
+    unknown_ctx = default_sender_context or SenderContext(known_contact=False)
+    active: list[DashboardItem] = []
+    obsolete: list[DashboardItem] = []
+
+    for entry in directory:
+        for env in merge_causal(channel_events.get(entry.channel, ())):
+            if env.kind is not EventKind.INVITATION or env.attention is None:
+                continue
+            ctx = sender_contexts.get(env.author, unknown_ctx)
+            item = DashboardItem(entry.channel, env, decide(env, ctx, policy, now))
+            if env.attention.relevance.active(now):
+                active.append(item)
+            else:
+                obsolete.append(item)
+
+    active.sort(key=lambda item: item.decision.effective_priority, reverse=True)
+    return Dashboard(active=tuple(active), obsolete=tuple(obsolete))
+
+
+def directory_read_state(
+    directory: ChannelDirectory,
+    channel_events: Mapping[ChannelId, Iterable[Envelope]],
+) -> dict[ChannelId, dict[PubKey, EventHash]]:
+    """Read-state (`ucomm.log.read_state`) for every channel in the
+    directory, rolled up into one view (issue D-3).
+
+    `ucomm.profiles.chat.ChatChannel.read_state` already does this for one
+    channel; the daemon needs it across every channel a user is in,
+    regardless of profile -- possible without profile-specific code because
+    `RECEIPT`'s meaning (`ucomm.log.read_state`'s docstring) is a kernel
+    convention, not a chat-profile one. Callers pass unmerged events; each
+    channel's stream is merged internally so callers don't have to remember
+    to do it themselves.
+    """
+    return {
+        entry.channel: read_state(merge_causal(channel_events.get(entry.channel, ())))
+        for entry in directory
+    }