@agentsdock/server 1.0.7-beta.5

package/server/agentsdock_team_hub/database.py

@@ -0,0 +1,310 @@
+"""SQLite connection and append-only migration support for Team Hub."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+from importlib import resources
+import os
+from pathlib import Path
+import re
+import sqlite3
+import stat
+import threading
+import time
+from typing import Iterator
+
+
+MIGRATION_NAME = re.compile(r"^(?P<version>[0-9]{4})_(?P<name>[a-z0-9_]+)\.sql$")
+MIGRATION_PACKAGE = "agentsdock_team_hub.migrations"
+
+
+class MigrationError(RuntimeError):
+    """Raised when the on-disk schema and embedded migration chain disagree."""
+
+
+@dataclass(frozen=True)
+class Migration:
+    version: int
+    name: str
+    source: str
+    sha256: str
+
+
+def _embedded_migrations() -> tuple[Migration, ...]:
+    discovered: list[Migration] = []
+    root = resources.files(MIGRATION_PACKAGE)
+    for entry in root.iterdir():
+        match = MIGRATION_NAME.fullmatch(entry.name)
+        if match is None:
+            continue
+        source = entry.read_text(encoding="utf-8")
+        discovered.append(
+            Migration(
+                version=int(match.group("version")),
+                name=match.group("name"),
+                source=source,
+                sha256=hashlib.sha256(source.encode("utf-8")).hexdigest(),
+            )
+        )
+    discovered.sort(key=lambda item: item.version)
+    expected = list(range(1, len(discovered) + 1))
+    actual = [item.version for item in discovered]
+    if not discovered or actual != expected:
+        raise MigrationError(
+            f"Team Hub migrations must be contiguous from 0001; found {actual}"
+        )
+    return tuple(discovered)
+
+
+MIGRATIONS = _embedded_migrations()
+LATEST_SCHEMA_VERSION = MIGRATIONS[-1].version
+
+
+_INITIALIZATION_LOCKS_GUARD = threading.Lock()
+_INITIALIZATION_LOCKS: dict[str, threading.Lock] = {}
+
+
+def _initialization_lock(database: str) -> threading.Lock:
+    """Serialize first-open WAL setup and migration within this process.
+
+    SQLite's busy timeout does not reliably cover a simultaneous
+    ``PRAGMA journal_mode=WAL`` on a brand-new database. A process lock avoids
+    that common desktop/service race; the bounded retry below also covers a
+    second Team Hub process opening the same file at the same time.
+    """
+
+    with _INITIALIZATION_LOCKS_GUARD:
+        return _INITIALIZATION_LOCKS.setdefault(database, threading.Lock())
+
+
+def _retry_locked(operation, *, timeout_seconds: float = 8.0):
+    deadline = time.monotonic() + timeout_seconds
+    delay = 0.01
+    while True:
+        try:
+            return operation()
+        except sqlite3.OperationalError as exc:
+            message = str(exc).lower()
+            if "locked" not in message and "busy" not in message:
+                raise
+            if time.monotonic() >= deadline:
+                raise
+            time.sleep(delay)
+            delay = min(delay * 2, 0.25)
+
+
+def _statements(source: str) -> Iterator[str]:
+    """Split trusted migration SQL without breaking trigger bodies."""
+
+    pending = ""
+    for line in source.splitlines(keepends=True):
+        pending += line
+        if sqlite3.complete_statement(pending):
+            statement = pending.strip()
+            pending = ""
+            if statement:
+                yield statement
+    if pending.strip():
+        raise MigrationError("migration ends with an incomplete SQL statement")
+
+
+def _configure(connection: sqlite3.Connection) -> None:
+    connection.row_factory = sqlite3.Row
+    connection.execute("PRAGMA foreign_keys = ON")
+    if int(connection.execute("PRAGMA foreign_keys").fetchone()[0]) != 1:
+        raise MigrationError("SQLite foreign-key enforcement could not be enabled")
+    connection.execute("PRAGMA busy_timeout = 5000")
+    connection.execute("PRAGMA synchronous = FULL")
+    connection.execute("PRAGMA secure_delete = ON")
+
+
+def _open_secure_database_file(target: Path) -> int:
+    """Open a regular owner-only file before SQLite can create or mutate it."""
+
+    if os.name == "nt":
+        raise MigrationError(
+            "Team Hub database ACL hardening is not implemented for Windows hosts"
+        )
+    parent = target.parent.lstat()
+    if not stat.S_ISDIR(parent.st_mode) or parent.st_uid != os.getuid():
+        raise PermissionError(
+            "Team Hub database directory must be an owner-controlled real directory"
+        )
+    parent_mode = stat.S_IMODE(parent.st_mode)
+    if parent_mode & 0o022:
+        raise PermissionError("Team Hub database directory must not be group/world writable")
+    flags = os.O_RDWR | os.O_CREAT
+    flags |= getattr(os, "O_CLOEXEC", 0)
+    flags |= getattr(os, "O_NOFOLLOW", 0)
+    descriptor = os.open(target, flags, 0o600)
+    try:
+        opened = os.fstat(descriptor)
+        if not stat.S_ISREG(opened.st_mode):
+            raise PermissionError("Team Hub database must be a regular file")
+        if opened.st_nlink != 1:
+            raise PermissionError("Team Hub database must not be hard-linked")
+        os.fchmod(descriptor, 0o600)
+        if stat.S_IMODE(os.fstat(descriptor).st_mode) != 0o600:
+            raise PermissionError("Team Hub database permissions are not owner-only")
+        return descriptor
+    except BaseException:
+        os.close(descriptor)
+        raise
+
+
+def _has_current_wal_migrations(connection: sqlite3.Connection) -> bool:
+    """Verify an existing WAL schema without contending for its writer lock.
+
+    Every new connection checks the complete bounded ledger and user_version
+    in one read snapshot. No path/inode cache can bypass checksum checks after
+    another connection changes the ledger or a database is replaced. Anything
+    other than the exact current chain still uses the serialized migration
+    path, including its existing error reporting for invalid/newer schemas.
+    """
+
+    connection.execute("BEGIN")
+    try:
+        if str(connection.execute("PRAGMA journal_mode").fetchone()[0]).lower() != "wal":
+            return False
+        if connection.execute(
+            "SELECT 1 FROM sqlite_master "
+            "WHERE type = 'table' AND name = 'schema_migrations'"
+        ).fetchone() is None:
+            return False
+        applied = [
+            tuple(row)
+            for row in connection.execute(
+                "SELECT version, name, sha256 FROM schema_migrations "
+                "ORDER BY version LIMIT ?",
+                (len(MIGRATIONS) + 1,),
+            )
+        ]
+        user_version = int(connection.execute("PRAGMA user_version").fetchone()[0])
+        return user_version == LATEST_SCHEMA_VERSION and applied == [
+            (migration.version, migration.name, migration.sha256)
+            for migration in MIGRATIONS
+        ]
+    except sqlite3.OperationalError as exc:
+        # Another first opener may be changing the journal mode. Let the
+        # existing initialization lock and bounded retry handle that race.
+        if "locked" in str(exc).lower() or "busy" in str(exc).lower():
+            return False
+        raise
+    finally:
+        if connection.in_transaction:
+            connection.execute("ROLLBACK")
+
+
+def open_database(path: str | os.PathLike[str] = ":memory:") -> sqlite3.Connection:
+    """Open a hardened SQLite connection and apply every embedded migration."""
+
+    database = os.fspath(path)
+    secure_descriptor: int | None = None
+    if database != ":memory:":
+        target = Path(database).expanduser()
+        target.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        secure_descriptor = _open_secure_database_file(target)
+        database = str(target)
+    try:
+        connection = sqlite3.connect(database, isolation_level=None, timeout=5.0)
+        if secure_descriptor is not None:
+            opened = os.fstat(secure_descriptor)
+            linked = os.stat(database, follow_symlinks=False)
+            if (opened.st_dev, opened.st_ino) != (linked.st_dev, linked.st_ino):
+                connection.close()
+                raise PermissionError("Team Hub database path changed while opening")
+            os.close(secure_descriptor)
+            secure_descriptor = None
+        _configure(connection)
+        if database == ":memory:":
+            apply_migrations(connection)
+        elif not _has_current_wal_migrations(connection):
+            with _initialization_lock(os.path.realpath(database)):
+                _retry_locked(lambda: connection.execute("PRAGMA journal_mode = WAL"))
+                _retry_locked(lambda: apply_migrations(connection))
+        return connection
+    except BaseException:
+        if secure_descriptor is not None:
+            os.close(secure_descriptor)
+        if "connection" in locals():
+            connection.close()
+        raise
+
+
+def apply_migrations(connection: sqlite3.Connection) -> int:
+    """Apply and checksum-verify the immutable migration chain."""
+
+    if connection.in_transaction:
+        raise MigrationError("migrations require an autocommit connection")
+    _configure(connection)
+    connection.execute(
+        """
+        CREATE TABLE IF NOT EXISTS schema_migrations (
+            version INTEGER PRIMARY KEY,
+            name TEXT NOT NULL,
+            sha256 TEXT NOT NULL CHECK(length(sha256) = 64),
+            applied_at INTEGER NOT NULL
+        )
+        """
+    )
+    connection.execute("BEGIN IMMEDIATE")
+    try:
+        # Read the ledger only after taking the writer lock. A second process
+        # opening the same fresh/outdated database then observes the first
+        # process's committed migration rather than replaying stale decisions.
+        applied = {
+            int(row["version"]): (str(row["name"]), str(row["sha256"]))
+            for row in connection.execute(
+                "SELECT version, name, sha256 FROM schema_migrations ORDER BY version"
+            )
+        }
+        user_version = int(connection.execute("PRAGMA user_version").fetchone()[0])
+        applied_version = max(applied, default=0)
+        known_versions = {item.version for item in MIGRATIONS}
+        unknown_versions = sorted(set(applied).difference(known_versions))
+        if unknown_versions or user_version > LATEST_SCHEMA_VERSION:
+            raise MigrationError(
+                "database schema is newer than this Team Hub build "
+                f"(ledger={unknown_versions}, user_version={user_version})"
+            )
+        if user_version != applied_version:
+            raise MigrationError(
+                "SQLite user_version does not match the migration ledger "
+                f"({user_version} != {applied_version})"
+            )
+
+        for migration in MIGRATIONS:
+            recorded = applied.get(migration.version)
+            if recorded is not None:
+                if recorded != (migration.name, migration.sha256):
+                    raise MigrationError(
+                        f"migration {migration.version:04d}_{migration.name} checksum changed"
+                    )
+                continue
+            if migration.version != applied_version + 1:
+                raise MigrationError(
+                    f"cannot apply migration {migration.version}; "
+                    f"expected {applied_version + 1}"
+                )
+            for statement in _statements(migration.source):
+                normalized = statement.lstrip().upper()
+                if normalized.startswith(("BEGIN", "COMMIT", "ROLLBACK")):
+                    raise MigrationError(
+                        f"migration {migration.version} contains transaction control"
+                    )
+                connection.execute(statement)
+            connection.execute(
+                """
+                INSERT INTO schema_migrations(version, name, sha256, applied_at)
+                VALUES (?, ?, ?, CAST(strftime('%s', 'now') AS INTEGER))
+                """,
+                (migration.version, migration.name, migration.sha256),
+            )
+            connection.execute(f"PRAGMA user_version = {migration.version}")
+            applied_version = migration.version
+        connection.execute("COMMIT")
+        return applied_version
+    except BaseException:
+        connection.execute("ROLLBACK")
+        raise

package/server/agentsdock_team_hub/mail_hint_streams.py

@@ -0,0 +1,176 @@
+"""Bounded passive Mail stream leases; no sockets, workers, timers or polling.
+
+The transport owns its dedicated reader and bounded writer. Authority owners
+close leases at revoke/role/maintenance boundaries, waking idle readers and
+aborting an in-progress write before waiting for that writer to settle.
+"""
+
+from __future__ import annotations
+
+from contextlib import suppress
+import threading
+import time
+from typing import Any, Callable
+
+from .mail_hints import MailArrival, MailHintClosed, MailHintSubscription
+
+
+class MailHintScopeChanged(MailHintClosed):
+    status_code = 403
+
+
+class MailHintUnsupported(MailHintClosed):
+    status_code = 501
+
+
+class MailHintLease:
+    def __init__(
+        self, subscription: MailHintSubscription, snapshot: dict[str, Any], *,
+        hub_id: str, authorize: Callable[[], None], expires_at: float | None,
+        on_close: Callable[[], None] | None = None,
+        clock: Callable[[], float] = time.time,
+        close_code: Callable[[], int] | None = None,
+    ) -> None:
+        arrival = MailArrival.from_dict(snapshot)
+        if type(snapshot.get("reset")) is not bool or arrival.mailbox != subscription.mailbox:
+            raise ValueError("Mail stream snapshot is invalid")
+        if not isinstance(hub_id, str) or not hub_id or len(hub_id) > 240:
+            raise ValueError("Mail stream Hub identity is invalid")
+        self.snapshot = dict(snapshot)
+        self.hub_id = hub_id
+        self.recipient_server_id = arrival.recipient_server_id
+        self.expires_at = expires_at
+        self._subscription = subscription
+        self._authorize = authorize
+        self._on_close = on_close
+        self._clock = clock
+        self._close_code = close_code
+        self._latest = arrival
+        self._guard = threading.RLock()
+        self._writer = threading.RLock()
+        self._closed = False
+        self._aborter: Callable[[], None] | None = None
+
+    @property
+    def closed(self) -> bool:
+        with self._guard:
+            return self._closed
+
+    @property
+    def close_code(self) -> int:
+        return self._close_code() if self._close_code is not None else 1012
+
+    def set_aborter(self, aborter: Callable[[], None]) -> None:
+        if not callable(aborter):
+            raise ValueError("Mail stream aborter is invalid")
+        with self._guard:
+            self._aborter = aborter
+            closed = self._closed
+        if closed:
+            with suppress(Exception):
+                aborter()
+
+    def revalidate(self) -> None:
+        with self._guard:
+            if self._closed or (
+                self.expires_at is not None and self._clock() >= self.expires_at
+            ):
+                raise MailHintClosed("Mail stream authority is unavailable")
+        # No invocation on an idle wait. The authority owner rechecks current
+        # exact claims/binding; the gateway additionally rechecks the mTLS cert.
+        self._authorize()
+        with self._guard:
+            if self._closed:
+                raise MailHintClosed("Mail stream authority changed")
+
+    def take(self, timeout: float | None = None) -> MailArrival | None:
+        deadline = None if timeout is None else self._clock() + max(0.0, timeout)
+        while not self.closed:
+            now = self._clock()
+            boundaries = [value for value in (deadline, self.expires_at) if value is not None]
+            remaining = max(0.0, min(boundaries) - now) if boundaries else None
+            if remaining == 0:
+                self.close()
+                return None
+            try:
+                arrival = self._subscription.take(timeout=remaining)
+            except MailHintClosed:
+                self.close()
+                return None
+            if arrival is None:
+                self.close()
+                return None
+            with self._guard:
+                if self._closed:
+                    return None
+                previous = self._latest
+                if arrival.mailbox != previous.mailbox or (
+                    arrival.through_sequence == previous.through_sequence
+                    and arrival.arrival_id != previous.arrival_id
+                ):
+                    invalid = True
+                else:
+                    invalid = False
+                    if arrival.through_sequence <= previous.through_sequence:
+                        continue
+                    self._latest = arrival
+            if invalid:
+                self.close()
+                return None
+            return arrival
+        return None
+
+    def write(self, writer: Callable[[dict[str, Any]], None], cursor: dict[str, Any]) -> None:
+        value = MailArrival.from_dict(cursor)
+        if value.mailbox != self._subscription.mailbox or type(cursor.get("reset")) is not bool:
+            raise ValueError("Mail stream cursor is invalid")
+        with self._writer:
+            self.revalidate()
+            # The transport must bound write time and attach its socket aborter.
+            # close() marks closed before aborting, then drains this exact lock.
+            writer(dict(cursor))
+
+    def cancel(self) -> None:
+        """Wake/abort without waiting for a writer (safe on its event loop)."""
+        with self._guard:
+            if self._closed:
+                first = False
+                aborter = None
+            else:
+                first = True
+                self._closed = True
+                aborter, self._aborter = self._aborter, None
+        if first:
+            self._subscription.close()
+            if aborter is not None:
+                with suppress(Exception):
+                    aborter()
+
+    def close(self) -> None:
+        self.cancel()
+        with self._writer:
+            pass
+        with self._guard:
+            on_close, self._on_close = self._on_close, None
+        if on_close is not None:
+            on_close()
+
+
+def owned_mail_snapshot(store: Any, claims: Any, team_id: str,
+                        previous_cursor: dict[str, Any] | None) -> tuple[dict[str, Any], dict[str, Any] | None]:
+    """Derive ownership before handling a retained cursor from an old binding.
+
+    A changed recipient resets to current owned metadata, never querying the
+    old recipient's anchor. A supplied foreign team is still rejected. This is
+    transport recovery only; the public store cursor API remains strict.
+    """
+    previous = MailArrival.from_dict(previous_cursor) if previous_cursor is not None else None
+    if previous is not None and previous.team_id != team_id:
+        raise ValueError("Mail stream cursor belongs to another team")
+    owned = store.team_mail_arrival_snapshot(claims, team_id)
+    retained = previous_cursor
+    if previous is not None and previous.recipient_server_id != owned["recipient_server_id"]:
+        retained = None
+    if retained is not None:
+        owned = store.team_mail_arrival_snapshot(claims, team_id, previous_cursor=retained)
+    return owned, retained

package/server/agentsdock_team_hub/mail_hints.py

@@ -0,0 +1,201 @@
+"""Recipient-only Mail arrival metadata; no transport, polling, or authority.
+
+Callers must authenticate the exact mailbox before subscribing, then read a
+fresh durable snapshot. A subscription owns one replaceable pending cursor,
+not a queue of messages. Closing wakes its reader; this module starts no
+threads and never calls application callbacks or performs socket/database I/O.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+import threading
+from typing import Any
+
+
+MAX_MAIL_SEQUENCE = 9_007_199_254_740_991
+MAIL_IDENTIFIER_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,127}\Z")
+MAIL_ARRIVAL_ID_RE = re.compile(r"tmsg_[0-9a-f]{32}\Z")
+
+
+def _valid_identity(value: Any) -> bool:
+    return isinstance(value, str) and MAIL_IDENTIFIER_RE.fullmatch(value) is not None
+
+
+@dataclass(frozen=True)
+class MailArrival:
+    team_id: str
+    recipient_server_id: str
+    through_sequence: int
+    arrival_id: str | None
+
+    def __post_init__(self) -> None:
+        if not _valid_identity(self.team_id) or not _valid_identity(self.recipient_server_id):
+            raise ValueError("Mail arrival mailbox identity is invalid")
+        if type(self.through_sequence) is not int or not 0 <= self.through_sequence <= MAX_MAIL_SEQUENCE:
+            raise ValueError("Mail arrival sequence is invalid")
+        if self.through_sequence == 0:
+            if self.arrival_id is not None:
+                raise ValueError("An empty Mail cursor cannot have an arrival ID")
+        elif not isinstance(self.arrival_id, str) or MAIL_ARRIVAL_ID_RE.fullmatch(self.arrival_id) is None:
+            raise ValueError("Mail arrival ID is invalid")
+
+    @property
+    def mailbox(self) -> tuple[str, str]:
+        return self.team_id, self.recipient_server_id
+
+    def as_dict(self, *, reset: bool | None = None) -> dict[str, Any]:
+        value: dict[str, Any] = {
+            "version": 1,
+            "team_id": self.team_id,
+            "recipient_server_id": self.recipient_server_id,
+            "through_sequence": self.through_sequence,
+            "arrival_id": self.arrival_id,
+        }
+        if reset is not None:
+            if type(reset) is not bool:
+                raise ValueError("Mail cursor reset is invalid")
+            value["reset"] = reset
+        return value
+
+    @classmethod
+    def from_dict(cls, value: Any) -> MailArrival:
+        required = {"version", "team_id", "recipient_server_id", "through_sequence", "arrival_id"}
+        if (
+            not isinstance(value, dict)
+            or not required <= value.keys()
+            or value.keys() - required - {"reset"}
+            or type(value.get("version")) is not int
+            or value["version"] != 1
+            or ("reset" in value and type(value["reset"]) is not bool)
+        ):
+            raise ValueError("Mail arrival cursor is invalid")
+        return cls(value["team_id"], value["recipient_server_id"], value["through_sequence"], value["arrival_id"])
+
+
+class MailHintClosed(RuntimeError):
+    """The stream must detach; reconnect requires a fresh durable snapshot."""
+
+
+class MailHintCapacity(RuntimeError):
+    """A separate bounded Mail subscriber budget is exhausted."""
+
+
+class MailHintSubscription:
+    def __init__(self, broker: MailHintBroker, mailbox: tuple[str, str]) -> None:
+        self._broker = broker
+        self._changed = threading.Condition(broker._guard)
+        self.mailbox = mailbox
+        self._pending: MailArrival | None = None
+        self._latest: MailArrival | None = None
+        self._closed = False
+
+    @property
+    def closed(self) -> bool:
+        with self._broker._guard:
+            return self._closed
+
+    def take(self, timeout: float | None = None) -> MailArrival | None:
+        """Wait for one coalesced hint (or return None on timeout).
+
+        A future transport owns its reader/writer and cancellation. It must not
+        put this lifetime wait in shared interactive HTTP/default-worker slots.
+        """
+        with self._changed:
+            self._changed.wait_for(
+                lambda: self._closed or self._pending is not None, timeout=timeout
+            )
+            if self._closed:
+                raise MailHintClosed("Mail hint subscription is closed")
+            pending, self._pending = self._pending, None
+            return pending
+
+    def close(self) -> None:
+        self._broker._close_subscription(self)
+
+
+class MailHintBroker:
+    """Process-local, bounded, nonblocking publication to exact recipients.
+
+    This is deliberately not an authorization registry or a durable event bus.
+    Revoke/role/shutdown owners must close their subscriptions. Failed delivery
+    must close the transport so its next subscribe reads durable state again.
+    """
+
+    def __init__(self, *, max_subscriptions: int = 256, max_per_recipient: int = 4) -> None:
+        if type(max_subscriptions) is not int or not 1 <= max_subscriptions <= 4096:
+            raise ValueError("Mail subscription limit is invalid")
+        if type(max_per_recipient) is not int or not 1 <= max_per_recipient <= 64:
+            raise ValueError("Mail recipient subscription limit is invalid")
+        self._max_subscriptions = max_subscriptions
+        self._max_per_recipient = max_per_recipient
+        self._guard = threading.RLock()
+        self._subscriptions: dict[tuple[str, str], set[MailHintSubscription]] = {}
+        self._count = 0
+        self._closed = False
+
+    def subscribe(self, team_id: str, recipient_server_id: str) -> MailHintSubscription:
+        # Identity syntax is not authority. Store/transport must bind claims.
+        mailbox = MailArrival(team_id, recipient_server_id, 0, None).mailbox
+        with self._guard:
+            if self._closed:
+                raise MailHintClosed("Mail hint broker is closed")
+            current = self._subscriptions.get(mailbox, set())
+            if self._count >= self._max_subscriptions or len(current) >= self._max_per_recipient:
+                raise MailHintCapacity("Mail hint subscription limit reached")
+            subscription = MailHintSubscription(self, mailbox)
+            self._subscriptions.setdefault(mailbox, set()).add(subscription)
+            self._count += 1
+            return subscription
+
+    def publish(self, arrival: MailArrival) -> None:
+        if not isinstance(arrival, MailArrival):
+            raise ValueError("Mail hint must be a validated arrival")
+        with self._guard:
+            if self._closed:
+                return
+            for subscription in tuple(self._subscriptions.get(arrival.mailbox, ())):
+                previous = subscription._latest
+                if previous is not None:
+                    if arrival.through_sequence < previous.through_sequence:
+                        continue
+                    if arrival.through_sequence == previous.through_sequence:
+                        if arrival.arrival_id != previous.arrival_id:
+                            # Do not choose between incompatible histories.
+                            self._close_locked(subscription)
+                        continue
+                subscription._latest = arrival
+                subscription._pending = arrival
+                subscription._changed.notify()
+
+    def _close_locked(self, subscription: MailHintSubscription) -> None:
+        if subscription._closed:
+            return
+        subscription._closed = True
+        subscription._pending = None
+        subscription._latest = None
+        current = self._subscriptions.get(subscription.mailbox)
+        if current is not None:
+            current.discard(subscription)
+            if not current:
+                del self._subscriptions[subscription.mailbox]
+        self._count -= 1
+        subscription._changed.notify_all()
+
+    def _close_subscription(self, subscription: MailHintSubscription) -> None:
+        with self._guard:
+            self._close_locked(subscription)
+
+    def invalidate(self, team_id: str, recipient_server_id: str) -> None:
+        """Wake and retire exact recipients after a missed publication/revoke."""
+        with self._guard:
+            for subscription in tuple(self._subscriptions.get((team_id, recipient_server_id), ())):
+                self._close_locked(subscription)
+
+    def close(self) -> None:
+        with self._guard:
+            self._closed = True
+            for current in tuple(self._subscriptions.values()):
+                for subscription in tuple(current):
+                    self._close_locked(subscription)