cloud-dog-api-kit 0.13.0__py3-none-any.whl

cloud_dog_api_kit/a2a/events.py

@@ -0,0 +1,1123 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — A2A change-event broadcast primitive
+#
+# Licence: Apache-2.0 — Cloud-Dog AI Platform
+# Owner: Cloud-Dog, Viewdeck Engineering Limited
+# Description: Platform primitive for broadcasting service-side configuration
+#   change events to downstream subscribers via SSE. Satisfies the shared
+#   CFG-06 (A2A broadcast) template requirement across services. Closes
+#   W28A-1002-INVESTIGATE finding that the platform previously provided no
+#   shared primitive, forcing each service to implement bespoke SSE/websocket
+#   pipelines.
+# Related requirements: CFG-06 (service-template), FR17.1
+# Related architecture: SA1
+# Related tests: UT_A2AEvents
+# Recent Change History:
+#   - 2026-04-23: W28A-1002-APPLY-A — new submodule added (v0.10.0).
+#   - 2026-04-24: W28A-1002-EXTEND-R1 — common-package additions (v0.11.0):
+#       PersistentEventBroadcaster (file-backed JSONL + WAL + replay),
+#       HTTPIngestAdapter (cross-process publisher REST ingress),
+#       WebSocketAdapter (WS subscriber surface alongside SSE),
+#       RESTPollAdapter (cursor-paginated JSON poll surface).
+#       0.10.0 API (ConfigChangeEvent + EventBroadcaster + InMemoryEventBroadcaster
+#       + create_a2a_events_router) preserved unchanged — file-mcp 1938743 adopt
+#       must continue to work without modification.
+#   - 2026-04-23: W28A-1002-EXTEND-R1b — configurable presentation-layer
+#       transforms (v0.12.0). ALL ADDITIONS ARE OPTIONAL KWARGS WITH DEFAULTS
+#       THAT PRESERVE 0.11.0 BEHAVIOUR EXACTLY (full backward-compat):
+#         * ConfigChangeEvent.to_dict(alias_map=None) — rename fields for
+#           services with legacy external contracts (e.g., index-retriever's
+#           entity_type/entity_id/created_at).
+#         * RESTPollAdapter(envelope_shape="with_cursor"|"events_only",
+#           field_mapping=None, order="oldest_first"|"newest_first",
+#           event_id_format="int"|"uuid_string") — presentation-layer
+#           transforms over the canonical envelope.
+#         * WebSocketAdapter(field_mapping=None) — rename fields in WS frames.
+#         * HTTPIngestAdapter(accept_legacy_fields=False) — accept legacy
+#           body-field aliases on ingest.
+#       The canonical envelope (PS-72 §A2A-change-events) remains AUTHORITATIVE;
+#       configurable mappings are PRESENTATION-LAYER transforms, not alternate
+#       envelopes. Services may preserve external contracts without diverging
+#       from the canonical platform representation internally.
+
+"""A2A configuration-change-event broadcast primitive.
+
+Usage in any service's A2A server::
+
+    from cloud_dog_api_kit.a2a.events import (
+        ConfigChangeEvent,
+        InMemoryEventBroadcaster,
+        create_a2a_events_router,
+    )
+
+    broadcaster = InMemoryEventBroadcaster()
+    app.include_router(create_a2a_events_router(broadcaster))
+
+    # On a CRUD operation:
+    await broadcaster.publish(
+        ConfigChangeEvent(
+            service="file-mcp-server",
+            resource="user",
+            action="create",
+            identifier=user_id,
+            actor=principal_id,
+            after=user_mapping,
+        )
+    )
+
+The router exposes:
+
+- ``GET {base_path}`` — SSE stream of live events. Accepts ``?after_id=N`` to
+  replay recent history before streaming live.
+- ``GET {base_path}/history`` — JSON list of recent events.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+import tempfile
+from collections import deque
+from collections.abc import AsyncIterator, Callable, Mapping
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Awaitable, Literal, Optional, Protocol, Union, runtime_checkable
+from uuid import uuid4
+
+from fastapi import APIRouter, Body, Depends, FastAPI, HTTPException, Query, Request, status
+from fastapi.responses import JSONResponse, StreamingResponse
+from starlette.websockets import WebSocket, WebSocketDisconnect
+
+
+_UTC = timezone.utc
+
+
+def _utc_now() -> datetime:
+    """Return a timezone-aware UTC timestamp (frozen dataclasses need a callable default)."""
+    return datetime.now(_UTC)
+
+
+@dataclass(frozen=True)
+class ConfigChangeEvent:
+    """A configuration change event emitted by a service CRUD surface.
+
+    Fields:
+        service:       Emitting service identifier (e.g. ``"file-mcp-server"``).
+        resource:      Entity type (e.g. ``"user"``, ``"group"``, ``"api_key"``, ``"profile"``).
+        action:        Verb (``"create"``, ``"update"``, ``"delete"``, ``"revoke"``).
+        identifier:    Entity identifier (user_id, group_id, profile_name, ...).
+        actor:         Principal id who initiated the change (None = system / unknown).
+        correlation_id: Request-id / trace-id for cross-service propagation.
+        before:        Previous entity state (None for create actions).
+        after:         New entity state (None for delete/revoke actions).
+        outcome:       ``"success"`` or ``"error"``.
+        timestamp:     UTC timestamp when the event was constructed.
+        event_id:      Monotonic id assigned by the broadcaster on publish (0 until published).
+    """
+
+    service: str
+    resource: str
+    action: str
+    identifier: str
+    actor: Optional[str] = None
+    correlation_id: Optional[str] = None
+    before: Optional[Mapping[str, Any]] = None
+    after: Optional[Mapping[str, Any]] = None
+    outcome: str = "success"
+    timestamp: datetime = field(default_factory=_utc_now)
+    event_id: int = 0
+
+    def to_dict(self, alias_map: Optional[Mapping[str, str]] = None) -> dict[str, Any]:
+        """Render as a JSON-serialisable mapping for SSE / REST output.
+
+        Args:
+            alias_map: Optional mapping of canonical-field-name → legacy-alias
+                (e.g. ``{"resource": "entity_type", "identifier": "entity_id",
+                "timestamp": "created_at"}``). When provided, each canonical
+                key is renamed to its alias in the output dict. Keys not
+                present in ``alias_map`` are emitted unchanged. The dataclass
+                itself is NOT mutated — the rename is presentation-layer only.
+
+                Added in 0.12.0 (W28A-1002-EXTEND-R1b) to support services
+                with legacy external contracts. See PS-72 §A2A-change-events:
+                the canonical envelope is authoritative; alias_map is a
+                presentation-layer transform.
+
+                When ``alias_map`` is ``None`` (default), behaviour is
+                identical to 0.11.0 (backward-compat invariant).
+        """
+        payload = asdict(self)
+        # asdict converts datetime to datetime; normalise to ISO-8601 UTC.
+        ts = self.timestamp
+        if ts.tzinfo is None:
+            ts = ts.replace(tzinfo=_UTC)
+        payload["timestamp"] = ts.isoformat().replace("+00:00", "Z")
+        # Mapping (before/after) may contain non-JSON types — coerce opaque values to str via default below.
+        if alias_map:
+            return _apply_field_mapping(payload, alias_map)
+        return payload
+
+    def with_event_id(self, event_id: int) -> "ConfigChangeEvent":
+        """Return a copy with a stamped event id (frozen dataclass → replace)."""
+        return ConfigChangeEvent(
+            service=self.service,
+            resource=self.resource,
+            action=self.action,
+            identifier=self.identifier,
+            actor=self.actor,
+            correlation_id=self.correlation_id,
+            before=self.before,
+            after=self.after,
+            outcome=self.outcome,
+            timestamp=self.timestamp,
+            event_id=event_id,
+        )
+
+
+@runtime_checkable
+class EventBroadcaster(Protocol):
+    """Protocol for a service-local A2A change-event broadcaster."""
+
+    async def publish(self, event: ConfigChangeEvent) -> ConfigChangeEvent:
+        """Assign an event id, fan out to live subscribers, retain in history.
+
+        Returns the stamped event so callers can log the id.
+        """
+        ...
+
+    def subscribe(self) -> AsyncIterator[ConfigChangeEvent]:
+        """Return an async iterator of live events.
+
+        The caller is responsible for cancelling the iterator (e.g. via
+        ``aclose()``); the broadcaster removes the subscriber queue on exit.
+        """
+        ...
+
+    def history(self, after_id: int = 0, limit: int = 100) -> list[ConfigChangeEvent]:
+        """Return the recent history window, ids strictly greater than ``after_id``."""
+        ...
+
+
+class InMemoryEventBroadcaster:
+    """Async in-memory fan-out broadcaster with bounded history.
+
+    - History: ``collections.deque(maxlen=history_size)`` — bounded FIFO.
+    - Monotonic event-id counter (starts at 1).
+    - Subscribers: each ``subscribe()`` registers an ``asyncio.Queue``
+      with ``subscriber_queue_size`` slots; slow subscribers are coped with
+      via ``put_nowait`` drops (history retains the event for later replay).
+
+    Suitable for a single-process service. For multi-process deployments or
+    replay-across-restart, consider a persistent backend (future scope —
+    W28A-1002-APPLY-A-CONVERGE).
+    """
+
+    def __init__(
+        self,
+        *,
+        history_size: int = 1000,
+        subscriber_queue_size: int = 256,
+    ) -> None:
+        if history_size <= 0:
+            raise ValueError("history_size must be positive")
+        if subscriber_queue_size <= 0:
+            raise ValueError("subscriber_queue_size must be positive")
+        self._history: deque[ConfigChangeEvent] = deque(maxlen=history_size)
+        self._history_size = history_size
+        self._queue_size = subscriber_queue_size
+        self._subscribers: set[asyncio.Queue[ConfigChangeEvent]] = set()
+        self._next_id = 1
+        self._lock = asyncio.Lock()
+
+    @property
+    def history_size(self) -> int:
+        """Maximum number of events retained in memory."""
+        return self._history_size
+
+    @property
+    def subscriber_count(self) -> int:
+        """Number of active subscribers (for observability / tests)."""
+        return len(self._subscribers)
+
+    async def publish(self, event: ConfigChangeEvent) -> ConfigChangeEvent:
+        """Stamp, store, fan out."""
+        async with self._lock:
+            stamped = event.with_event_id(self._next_id)
+            self._next_id += 1
+            self._history.append(stamped)
+            subscribers = list(self._subscribers)
+        for queue in subscribers:
+            try:
+                queue.put_nowait(stamped)
+            except asyncio.QueueFull:
+                # Slow subscriber; drop this event for them. History is still
+                # authoritative — on reconnect they pull via /history?after_id=.
+                continue
+        return stamped
+
+    async def subscribe(self) -> AsyncIterator[ConfigChangeEvent]:
+        """Async iterator yielding live events until cancelled."""
+        queue: asyncio.Queue[ConfigChangeEvent] = asyncio.Queue(maxsize=self._queue_size)
+        async with self._lock:
+            self._subscribers.add(queue)
+        try:
+            while True:
+                event = await queue.get()
+                yield event
+        finally:
+            async with self._lock:
+                self._subscribers.discard(queue)
+
+    def history(self, after_id: int = 0, limit: int = 100) -> list[ConfigChangeEvent]:
+        """Return recent events with ``event_id > after_id``, newest last, capped at ``limit``."""
+        if limit <= 0:
+            return []
+        if limit > self._history_size:
+            limit = self._history_size
+        # deque is iterated in insertion order (oldest first).
+        out: list[ConfigChangeEvent] = [
+            evt for evt in self._history if evt.event_id > int(after_id or 0)
+        ]
+        # Return the *latest* N when more than limit match, preserving order.
+        if len(out) > limit:
+            out = out[-limit:]
+        return out
+
+
+def _apply_field_mapping(
+    payload: dict[str, Any], field_mapping: Mapping[str, str]
+) -> dict[str, Any]:
+    """Rename canonical keys in ``payload`` to their aliases per ``field_mapping``.
+
+    Preserves insertion order of the input dict. Keys not present in
+    ``field_mapping`` are emitted unchanged. If a target alias collides with an
+    existing key in the payload that is not itself being renamed away, the
+    alias overwrites (caller responsibility to choose non-conflicting aliases).
+
+    This is a presentation-layer helper — it never mutates the source object.
+    W28A-1002-EXTEND-R1b (0.12.0).
+    """
+    if not field_mapping:
+        return dict(payload)
+    out: dict[str, Any] = {}
+    for key, value in payload.items():
+        out[field_mapping.get(key, key)] = value
+    return out
+
+
+def _int_event_id_to_uuid(event_id: int) -> str:
+    """Deterministically map an integer event_id to a stable UUID string.
+
+    Used by ``RESTPollAdapter(event_id_format="uuid_string")`` to preserve
+    legacy UUID-string contracts without requiring the broadcaster to change
+    its internal monotonic int counter. The mapping is deterministic so the
+    same event_id always yields the same UUID across process restarts.
+
+    Uses uuid5 over a fixed platform namespace derived from the DNS namespace.
+    W28A-1002-EXTEND-R1b (0.12.0).
+    """
+    from uuid import NAMESPACE_DNS, uuid5
+
+    return str(uuid5(NAMESPACE_DNS, f"cloud-dog-a2a-event:{int(event_id)}"))
+
+
+def _sse_frame(event: ConfigChangeEvent) -> str:
+    """Render a single ConfigChangeEvent as an SSE frame."""
+    data = json.dumps(event.to_dict(), default=str, separators=(",", ":"))
+    return f"id: {event.event_id}\nevent: config_change\ndata: {data}\n\n"
+
+
+def create_a2a_events_router(
+    broadcaster: EventBroadcaster,
+    *,
+    base_path: str = "/a2a/events",
+    keepalive_seconds: float = 15.0,
+    history_limit_cap: int = 1000,
+) -> APIRouter:
+    """Create a FastAPI router exposing SSE stream + history endpoints.
+
+    Args:
+        broadcaster: An ``EventBroadcaster`` implementation (usually
+            ``InMemoryEventBroadcaster`` held on ``app.state``).
+        base_path: Mount path for the SSE endpoint. ``/history`` is appended
+            for the JSON history endpoint. Defaults to ``"/a2a/events"``.
+        keepalive_seconds: Interval between SSE keepalive comment frames.
+            Needed so reverse-proxies (Traefik, nginx) with an idle-read
+            timeout don't tear down a quiet stream.
+        history_limit_cap: Maximum ``limit`` value accepted by ``/history``.
+    """
+    if not base_path.startswith("/"):
+        raise ValueError("base_path must start with '/'")
+    base_path = base_path.rstrip("/") or "/a2a/events"
+    history_path = f"{base_path}/history"
+
+    router = APIRouter()
+
+    @router.get(base_path, include_in_schema=True)
+    async def stream_events(  # type: ignore[no-untyped-def]
+        request: Request,
+        after_id: int = Query(default=0, ge=0),
+    ) -> StreamingResponse:
+        """Stream configuration change events as a server-sent-events feed."""
+
+        async def _gen() -> AsyncIterator[bytes]:
+            # 1) Replay history strictly greater than after_id (bounded).
+            for evt in broadcaster.history(after_id=after_id, limit=history_limit_cap):
+                if await request.is_disconnected():
+                    return
+                yield _sse_frame(evt).encode("utf-8")
+            # 2) Subscribe for live events, interleave with keepalives.
+            subscription = broadcaster.subscribe()
+            try:
+                while True:
+                    if await request.is_disconnected():
+                        break
+                    try:
+                        evt = await asyncio.wait_for(
+                            subscription.__anext__(), timeout=keepalive_seconds
+                        )
+                    except asyncio.TimeoutError:
+                        yield b": keepalive\n\n"
+                        continue
+                    except StopAsyncIteration:
+                        break
+                    yield _sse_frame(evt).encode("utf-8")
+            finally:
+                aclose = getattr(subscription, "aclose", None)
+                if aclose is not None:
+                    try:
+                        await aclose()
+                    except Exception:
+                        pass
+
+        return StreamingResponse(
+            _gen(),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache",
+                "X-Accel-Buffering": "no",
+            },
+        )
+
+    @router.get(history_path, include_in_schema=True)
+    async def events_history(  # type: ignore[no-untyped-def]
+        after_id: int = Query(default=0, ge=0),
+        limit: int = Query(default=100, ge=1, le=history_limit_cap),
+    ) -> JSONResponse:
+        """Return recent configuration change events as JSON (newest last)."""
+        events = [evt.to_dict() for evt in broadcaster.history(after_id=after_id, limit=limit)]
+        return JSONResponse({"events": events})
+
+    return router
+
+
+# ---------------------------------------------------------------------------
+# W28A-1002-EXTEND-R1 (0.11.0) — common-package additions
+#
+# The following four classes extend the 0.10.0 primitive to cover all 5
+# bespoke CFG-06 architectures (expert-agent HTTP-bridge, sql-agent file-queue,
+# imap-mcp JSONL+WS, index-retriever REST-poll, chat-client SSE) via additive
+# adapters. The 0.10.0 API above is unchanged — file-mcp 0.10.0 adoption must
+# continue to work without modification (backward compat binding).
+#
+# Canonical envelope (PS-72 §A2A-change-events — formalised by W28A-F3e-APPLY):
+#   {type: str, topic: str, timestamp: str ISO8601, payload: dict}
+#
+# Mapping to the 0.10.0 ConfigChangeEvent:
+#   type      = action        (create / update / delete / revoke)
+#   topic     = resource      (user / group / api_key / profile / ...)
+#   timestamp = timestamp.isoformat() with "Z" suffix
+#   payload   = after (for create/update) or before (for delete) + actor/correlation_id
+#
+# All new adapters interoperate with BOTH InMemoryEventBroadcaster and
+# PersistentEventBroadcaster via the EventBroadcaster Protocol.
+# ---------------------------------------------------------------------------
+
+
+def _serialise_event(event: ConfigChangeEvent) -> str:
+    """JSONL-line serialisation of a ConfigChangeEvent for file-backed stores."""
+    return json.dumps(event.to_dict(), default=str, separators=(",", ":"))
+
+
+def _deserialise_event(line: str) -> Optional[ConfigChangeEvent]:
+    """Parse a JSONL line back into a ConfigChangeEvent. Returns None on malformed input."""
+    line = line.strip()
+    if not line:
+        return None
+    try:
+        data = json.loads(line)
+    except (json.JSONDecodeError, ValueError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    ts_raw = data.get("timestamp")
+    ts: datetime
+    if isinstance(ts_raw, str):
+        try:
+            # Accept both trailing Z and +00:00 forms.
+            ts_str = ts_raw.replace("Z", "+00:00") if ts_raw.endswith("Z") else ts_raw
+            ts = datetime.fromisoformat(ts_str)
+            if ts.tzinfo is None:
+                ts = ts.replace(tzinfo=_UTC)
+        except ValueError:
+            ts = _utc_now()
+    else:
+        ts = _utc_now()
+    try:
+        event_id = int(data.get("event_id", 0) or 0)
+    except (TypeError, ValueError):
+        event_id = 0
+    try:
+        return ConfigChangeEvent(
+            service=str(data.get("service", "")),
+            resource=str(data.get("resource", "")),
+            action=str(data.get("action", "")),
+            identifier=str(data.get("identifier", "")),
+            actor=data.get("actor"),
+            correlation_id=data.get("correlation_id"),
+            before=data.get("before"),
+            after=data.get("after"),
+            outcome=str(data.get("outcome", "success")),
+            timestamp=ts,
+            event_id=event_id,
+        )
+    except Exception:
+        return None
+
+
+class PersistentEventBroadcaster:
+    """File-backed JSONL broadcaster with WAL semantics, replay-on-startup + bounded retention.
+
+    Drop-in for services that need crash-safe A2A event delivery across process
+    restarts (sql-agent cross-process file-queue, imap-mcp JSONL tailing).
+
+    Storage layout::
+
+        <store_path>            — append-only JSONL file (WAL) holding the
+                                  most recent `retention` events.
+        <store_path>.rotated.1  — optional pre-rotation snapshot (kept briefly
+                                  during rotation to avoid data loss on crash
+                                  between truncate + rewrite).
+
+    Guarantees:
+        * Every `publish` writes the event + ``fsync`` before returning; the
+          event id reflects its position in the durable log.
+        * On construction, replays the JSONL store and rebuilds in-memory
+          history up to ``retention`` most recent events.
+        * When the log exceeds ``retention * 2`` events (measured by line count
+          at startup or by in-memory counter at runtime), it rotates: snapshot
+          the latest ``retention`` events, rewrite the primary file atomically.
+        * Subscriber fan-out is identical to ``InMemoryEventBroadcaster``
+          (bounded queues, put_nowait drop-on-full with history as fallback).
+
+    Usage::
+
+        broadcaster = PersistentEventBroadcaster(Path("/var/lib/svc/events.jsonl"))
+        app.include_router(create_a2a_events_router(broadcaster))
+
+    Args:
+        store_path: Path to the JSONL store file. Parent directory is created
+            automatically if missing. Path may be str or Path.
+        retention: Maximum number of events retained (both in the file after
+            rotation and in-memory history window). Must be positive.
+        subscriber_queue_size: Per-subscriber queue capacity for live fan-out.
+    """
+
+    def __init__(
+        self,
+        store_path: Union[str, Path],
+        *,
+        retention: int = 10_000,
+        subscriber_queue_size: int = 256,
+    ) -> None:
+        if retention <= 0:
+            raise ValueError("retention must be positive")
+        if subscriber_queue_size <= 0:
+            raise ValueError("subscriber_queue_size must be positive")
+        self._store_path = Path(store_path)
+        self._store_path.parent.mkdir(parents=True, exist_ok=True)
+        self._retention = retention
+        self._queue_size = subscriber_queue_size
+        self._history: deque[ConfigChangeEvent] = deque(maxlen=retention)
+        self._subscribers: set[asyncio.Queue[ConfigChangeEvent]] = set()
+        self._lock = asyncio.Lock()
+        self._next_id = 1
+        # Replay on startup — rebuild in-memory state from the durable log.
+        self._replay_from_disk()
+
+    # ------------------------------------------------------------------ lifecycle
+    def _replay_from_disk(self) -> None:
+        """Load persisted events into memory; update monotonic id cursor."""
+        if not self._store_path.is_file():
+            return
+        events: list[ConfigChangeEvent] = []
+        max_id = 0
+        with self._store_path.open("r", encoding="utf-8") as fh:
+            for line in fh:
+                evt = _deserialise_event(line)
+                if evt is None:
+                    continue
+                events.append(evt)
+                if evt.event_id > max_id:
+                    max_id = evt.event_id
+        # Retain only the newest `retention` (file may exceed it if rotation was
+        # interrupted; trim here so in-memory history matches the bound).
+        if len(events) > self._retention:
+            events = events[-self._retention :]
+        for evt in events:
+            self._history.append(evt)
+        self._next_id = max_id + 1
+
+    # ------------------------------------------------------------------ properties
+    @property
+    def store_path(self) -> Path:
+        return self._store_path
+
+    @property
+    def retention(self) -> int:
+        return self._retention
+
+    @property
+    def history_size(self) -> int:
+        return self._retention
+
+    @property
+    def subscriber_count(self) -> int:
+        return len(self._subscribers)
+
+    # ------------------------------------------------------------------ protocol
+    async def publish(self, event: ConfigChangeEvent) -> ConfigChangeEvent:
+        """Stamp id, append to JSONL + fsync, fan out to subscribers."""
+        async with self._lock:
+            stamped = event.with_event_id(self._next_id)
+            self._next_id += 1
+            self._append_and_fsync(stamped)
+            self._history.append(stamped)
+            # Opportunistic rotation when we cross 2x retention on disk.
+            self._maybe_rotate_locked()
+            subscribers = list(self._subscribers)
+        for queue in subscribers:
+            try:
+                queue.put_nowait(stamped)
+            except asyncio.QueueFull:
+                continue
+        return stamped
+
+    async def subscribe(self) -> AsyncIterator[ConfigChangeEvent]:
+        queue: asyncio.Queue[ConfigChangeEvent] = asyncio.Queue(maxsize=self._queue_size)
+        async with self._lock:
+            self._subscribers.add(queue)
+        try:
+            while True:
+                event = await queue.get()
+                yield event
+        finally:
+            async with self._lock:
+                self._subscribers.discard(queue)
+
+    def history(self, after_id: int = 0, limit: int = 100) -> list[ConfigChangeEvent]:
+        if limit <= 0:
+            return []
+        if limit > self._retention:
+            limit = self._retention
+        out: list[ConfigChangeEvent] = [
+            evt for evt in self._history if evt.event_id > int(after_id or 0)
+        ]
+        if len(out) > limit:
+            out = out[-limit:]
+        return out
+
+    # ------------------------------------------------------------------ internals
+    def _append_and_fsync(self, event: ConfigChangeEvent) -> None:
+        """Append a single event to the JSONL file with durability."""
+        line = _serialise_event(event) + "\n"
+        # Open in append binary mode for atomic single-line writes.
+        fd = os.open(
+            str(self._store_path),
+            os.O_WRONLY | os.O_CREAT | os.O_APPEND,
+            0o644,
+        )
+        try:
+            os.write(fd, line.encode("utf-8"))
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+
+    def _line_count(self) -> int:
+        if not self._store_path.is_file():
+            return 0
+        count = 0
+        with self._store_path.open("rb") as fh:
+            for _ in fh:
+                count += 1
+        return count
+
+    def _maybe_rotate_locked(self) -> None:
+        """If the durable log has grown past 2x retention, rewrite it atomically."""
+        if self._line_count() <= self._retention * 2:
+            return
+        # Snapshot the most recent `retention` events from in-memory history
+        # (which is authoritative because replay + append keep them in sync).
+        events_to_keep = list(self._history)
+        # Write to a sibling tempfile + atomic rename.
+        tmp_fd, tmp_name = tempfile.mkstemp(
+            prefix=self._store_path.name + ".rot.",
+            dir=str(self._store_path.parent),
+        )
+        try:
+            with os.fdopen(tmp_fd, "w", encoding="utf-8") as tmp_fh:
+                for evt in events_to_keep:
+                    tmp_fh.write(_serialise_event(evt) + "\n")
+                tmp_fh.flush()
+                os.fsync(tmp_fh.fileno())
+            os.replace(tmp_name, str(self._store_path))
+        except Exception:
+            # Best-effort cleanup of the tempfile on failure.
+            with contextlib.suppress(OSError):
+                os.unlink(tmp_name)
+            raise
+
+
+class HTTPIngestAdapter:
+    """HTTP-POST ingress adapter for cross-process publishers.
+
+    Closes the expert-agent pattern where an APIServer in one process publishes
+    ConfigChangeEvents to a separate A2AServer process that owns the broadcaster
+    and client-facing surfaces. Instead of a bespoke `/broadcast` endpoint per
+    service, mount this adapter on the A2AServer process and POST to it from
+    upstream publishers.
+
+    Routes mounted (relative to ``mount_path``)::
+
+        POST <mount_path>/{topic}        — publish a single event to a topic
+        POST <mount_path>/{topic}/event  — alias for explicit /event suffix
+
+    Request body (both routes)::
+
+        {
+            "action": "create",            # required
+            "identifier": "user_123",      # required
+            "service": "expert-agent",     # optional (adapter_service default)
+            "actor": "admin",              # optional
+            "correlation_id": "req-42",    # optional
+            "before": {...},               # optional
+            "after": {...},                # optional
+            "outcome": "success"           # optional, default "success"
+        }
+
+    The path segment ``{topic}`` is mapped to ``ConfigChangeEvent.resource``.
+    The optional ``auth_dependency`` callable enforces caller authentication
+    (e.g., API-key or bearer-token validation); leave None for open ingestion.
+
+    Args:
+        broadcaster: Target broadcaster (InMemoryEventBroadcaster or
+            PersistentEventBroadcaster or any EventBroadcaster).
+        mount_path: Base path for the ingress routes. Default "/broadcast".
+        adapter_service: Default value for ``ConfigChangeEvent.service`` when
+            the request body omits it. None = required in body.
+        auth_dependency: Optional FastAPI dependency callable for auth guard.
+    """
+
+    def __init__(
+        self,
+        broadcaster: EventBroadcaster,
+        *,
+        mount_path: str = "/broadcast",
+        adapter_service: Optional[str] = None,
+        auth_dependency: Optional[Callable[..., Any]] = None,
+        # W28A-1002-EXTEND-R1b (0.12.0) — optional legacy-alias ingest.
+        accept_legacy_fields: bool = False,
+    ) -> None:
+        if not mount_path.startswith("/"):
+            raise ValueError("mount_path must start with '/'")
+        self._broadcaster = broadcaster
+        self._mount_path = mount_path.rstrip("/") or "/broadcast"
+        self._adapter_service = adapter_service
+        self._auth = auth_dependency
+        # W28A-1002-EXTEND-R1b: when True, accept legacy field names on ingest
+        # (``entity_type`` as alias for topic/``resource``, ``entity_id`` as
+        # alias for ``identifier``). Default False preserves 0.11.0 strict
+        # canonical-field ingress contract.
+        self._accept_legacy_fields = accept_legacy_fields
+
+    @property
+    def mount_path(self) -> str:
+        """Mount path for the POST ingress routes (read-only)."""
+        return self._mount_path
+
+    def router(self) -> APIRouter:
+        """Return a FastAPI router implementing the POST endpoints."""
+        router = APIRouter()
+        auth_dep = self._auth
+
+        # Build dependencies list (FastAPI will evaluate auth_dep on each call
+        # and raise HTTPException if it returns falsy / raises).
+        deps = [Depends(auth_dep)] if auth_dep is not None else []
+
+        accept_legacy = self._accept_legacy_fields
+
+        async def _ingest(topic: str, body: dict[str, Any]) -> dict[str, Any]:
+            # Body validation — accept dict only; required fields action + identifier.
+            if not isinstance(body, dict):
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="Request body must be a JSON object",
+                )
+            action = body.get("action")
+            identifier = body.get("identifier")
+            # W28A-1002-EXTEND-R1b: accept legacy field names when opted-in.
+            if accept_legacy and (identifier is None or identifier == ""):
+                identifier = body.get("entity_id")
+            if not isinstance(action, str) or not action:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="Field 'action' is required and must be a non-empty string",
+                )
+            if not isinstance(identifier, str) or not identifier:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="Field 'identifier' is required and must be a non-empty string",
+                )
+            service_name = body.get("service") or self._adapter_service
+            if not isinstance(service_name, str) or not service_name:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="Field 'service' is required (either in body or via adapter_service default)",
+                )
+            evt = ConfigChangeEvent(
+                service=service_name,
+                resource=topic,
+                action=action,
+                identifier=identifier,
+                actor=body.get("actor"),
+                correlation_id=body.get("correlation_id"),
+                before=body.get("before"),
+                after=body.get("after"),
+                outcome=body.get("outcome", "success"),
+            )
+            stamped = await self._broadcaster.publish(evt)
+            return {
+                "event_id": stamped.event_id,
+                "topic": stamped.resource,
+                "published_at": stamped.timestamp.isoformat().replace("+00:00", "Z"),
+            }
+
+        @router.post(f"{self._mount_path}/{{topic}}", dependencies=deps)
+        async def broadcast_topic(
+            topic: str,
+            body: dict[str, Any] = Body(...),
+        ) -> dict[str, Any]:
+            return await _ingest(topic, body)
+
+        @router.post(f"{self._mount_path}/{{topic}}/event", dependencies=deps)
+        async def broadcast_topic_event(
+            topic: str,
+            body: dict[str, Any] = Body(...),
+        ) -> dict[str, Any]:
+            return await _ingest(topic, body)
+
+        return router
+
+    def mount(self, app: FastAPI) -> None:
+        """Convenience: include the ingress router into a FastAPI app."""
+        app.include_router(self.router())
+
+
+class WebSocketAdapter:
+    """WebSocket subscriber surface alongside the SSE router.
+
+    Closes the imap-mcp + expert-agent WS subscriber pattern by providing a
+    standardised WebSocket endpoint that clients can use instead of (or in
+    addition to) the SSE route. The endpoint replays history first (honouring
+    ``after_id`` query param), then streams live events as JSON text frames
+    until the client disconnects.
+
+    Frame format (one JSON object per text frame)::
+
+        {
+            "event_id": 42,
+            "type": "config_change",
+            "service": "...",
+            "resource": "...",
+            "action": "...",
+            "identifier": "...",
+            "timestamp": "2026-04-24T12:00:00Z",
+            "payload": { ... }    # ConfigChangeEvent.to_dict() merged in
+        }
+
+    Args:
+        broadcaster: Source broadcaster for history + live events.
+        mount_path: WebSocket path. Default ``"/a2a/events/ws"``.
+        history_limit_cap: Maximum history replay on connect.
+    """
+
+    def __init__(
+        self,
+        broadcaster: EventBroadcaster,
+        *,
+        mount_path: str = "/a2a/events/ws",
+        history_limit_cap: int = 1000,
+        # W28A-1002-EXTEND-R1b (0.12.0) — optional presentation-layer transform.
+        field_mapping: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        if not mount_path.startswith("/"):
+            raise ValueError("mount_path must start with '/'")
+        self._broadcaster = broadcaster
+        self._mount_path = mount_path
+        self._history_limit_cap = history_limit_cap
+        # W28A-1002-EXTEND-R1b: field_mapping (optional) renames canonical
+        # fields in every frame to legacy aliases. None (DEFAULT) = 0.11.0
+        # canonical field names.
+        self._field_mapping: Optional[dict[str, str]] = (
+            dict(field_mapping) if field_mapping else None
+        )
+
+    @property
+    def mount_path(self) -> str:
+        """WebSocket mount path (read-only)."""
+        return self._mount_path
+
+    def router(self) -> APIRouter:
+        """Return a FastAPI router implementing the WebSocket endpoint."""
+        router = APIRouter()
+        broadcaster = self._broadcaster
+        history_limit_cap = self._history_limit_cap
+        field_mapping = self._field_mapping
+
+        def _frame(evt: ConfigChangeEvent) -> str:
+            return json.dumps(evt.to_dict(alias_map=field_mapping), default=str)
+
+        @router.websocket(self._mount_path)
+        async def ws_endpoint(websocket: WebSocket) -> None:
+            # Parse ``after_id`` from query params (default 0).
+            after_id_raw = websocket.query_params.get("after_id", "0")
+            try:
+                after_id = max(0, int(after_id_raw))
+            except (TypeError, ValueError):
+                after_id = 0
+            await websocket.accept()
+            try:
+                # 1) Replay history strictly greater than after_id.
+                for evt in broadcaster.history(after_id=after_id, limit=history_limit_cap):
+                    await websocket.send_text(_frame(evt))
+                # 2) Subscribe for live events.
+                subscription = broadcaster.subscribe()
+                try:
+                    async for evt in subscription:
+                        await websocket.send_text(_frame(evt))
+                finally:
+                    aclose = getattr(subscription, "aclose", None)
+                    if aclose is not None:
+                        with contextlib.suppress(Exception):
+                            await aclose()
+            except WebSocketDisconnect:
+                # Graceful client-side disconnect — nothing to do.
+                return
+            except Exception:
+                # Close server-side on unexpected failure to free subscriber slot.
+                with contextlib.suppress(Exception):
+                    await websocket.close()
+                raise
+
+        return router
+
+    def mount(self, app: FastAPI) -> None:
+        """Convenience: include the WebSocket router into a FastAPI app."""
+        app.include_router(self.router())
+
+
+class RESTPollAdapter:
+    """REST-poll surface over the broadcaster history.
+
+    Closes the index-retriever + admin-SPA REST-poll client contract. Returns
+    JSON ``{"events": [...], "cursor": <next>}`` envelope for clients that
+    cannot (or prefer not to) use SSE/WebSocket. Cursor is a monotonic
+    ``event_id`` integer — pass back via ``?since=<cursor>`` to fetch the next
+    batch.
+
+    Default contract (0.11.0-compat)::
+
+        GET <mount_path>?since=<cursor>&limit=<n>
+        →
+        {
+            "events": [<ConfigChangeEvent.to_dict()>, ...],
+            "cursor": <event_id of last event in the batch, or echoed since>
+        }
+
+    - First poll (``since=0`` or omitted) returns the first ``limit`` events.
+    - Subsequent polls with ``since=<cursor>`` return events with
+      ``event_id > since``.
+    - An empty result returns ``{"events": [], "cursor": <since>}`` (idempotent).
+    - ``limit`` is clamped to ``history_limit_cap`` (default 1000).
+
+    Args:
+        broadcaster: Source broadcaster.
+        mount_path: REST-poll path. Default ``"/a2a/events"``. Services that
+            also expose the SSE router on the same path should mount this
+            adapter at a distinct path (e.g. ``"/a2a/events/poll"``) to avoid
+            content-type collision.
+        history_limit_cap: Maximum ``limit`` accepted per poll.
+        default_limit: Default ``limit`` when the client omits the query param.
+
+    W28A-1002-EXTEND-R1b (0.12.0) — ALL OPTIONAL, presentation-layer only.
+    Defaults preserve 0.11.0 behaviour byte-for-byte (backward-compat
+    invariant).
+
+        envelope_shape:
+            * ``"with_cursor"`` (DEFAULT) — 0.11.0 shape ``{"events":[...],
+              "cursor": N}``.
+            * ``"events_only"`` — legacy shape ``{"events":[...]}`` (no cursor
+              key). Used by index-retriever's bespoke ``GET /a2a/events`` that
+              admin-SPA + e2e tests depend on.
+        field_mapping:
+            Optional mapping of canonical-field-name → legacy-alias applied to
+            every event dict emitted. E.g. ``{"resource": "entity_type",
+            "identifier": "entity_id", "timestamp": "created_at"}`` emits
+            events with legacy field names without changing the canonical
+            dataclass. ``None`` (DEFAULT) preserves 0.11.0 canonical field
+            names.
+        order:
+            * ``"oldest_first"`` (DEFAULT) — 0.11.0 cursor-pagination semantics.
+            * ``"newest_first"`` — reverse the batch before emitting (legacy
+              index-retriever contract). Pagination cursors still advance
+              over the full id range; ordering is a presentation transform
+              over the batch window.
+        event_id_format:
+            * ``"int"`` (DEFAULT) — 0.11.0 monotonic integer.
+            * ``"uuid_string"`` — deterministic UUID string derived from the
+              monotonic int via uuid5. Used by legacy contracts that expect
+              UUID-typed event_ids. The cursor remains an integer (the
+              cursor is a pagination token, not a client-visible event key).
+
+    Canonical envelope (PS-72 §A2A-change-events) is AUTHORITATIVE; the
+    above configuration surface implements PRESENTATION-LAYER transforms so
+    services can preserve external contracts without diverging from the
+    canonical platform representation internally.
+    """
+
+    def __init__(
+        self,
+        broadcaster: EventBroadcaster,
+        *,
+        mount_path: str = "/a2a/events",
+        history_limit_cap: int = 1000,
+        default_limit: int = 100,
+        # W28A-1002-EXTEND-R1b (0.12.0) — all optional, defaults = 0.11.0 shape.
+        envelope_shape: Literal["with_cursor", "events_only"] = "with_cursor",
+        field_mapping: Optional[Mapping[str, str]] = None,
+        order: Literal["oldest_first", "newest_first"] = "oldest_first",
+        event_id_format: Literal["int", "uuid_string"] = "int",
+    ) -> None:
+        if not mount_path.startswith("/"):
+            raise ValueError("mount_path must start with '/'")
+        if history_limit_cap <= 0:
+            raise ValueError("history_limit_cap must be positive")
+        if default_limit <= 0:
+            raise ValueError("default_limit must be positive")
+        if envelope_shape not in ("with_cursor", "events_only"):
+            raise ValueError(
+                "envelope_shape must be 'with_cursor' or 'events_only'"
+            )
+        if order not in ("oldest_first", "newest_first"):
+            raise ValueError("order must be 'oldest_first' or 'newest_first'")
+        if event_id_format not in ("int", "uuid_string"):
+            raise ValueError("event_id_format must be 'int' or 'uuid_string'")
+        self._broadcaster = broadcaster
+        self._mount_path = mount_path
+        self._history_limit_cap = history_limit_cap
+        self._default_limit = default_limit
+        self._envelope_shape = envelope_shape
+        self._field_mapping: Optional[dict[str, str]] = (
+            dict(field_mapping) if field_mapping else None
+        )
+        self._order = order
+        self._event_id_format = event_id_format
+
+    @property
+    def mount_path(self) -> str:
+        """REST-poll mount path (read-only)."""
+        return self._mount_path
+
+    def router(self) -> APIRouter:
+        """Return a FastAPI router implementing the REST-poll endpoint."""
+        router = APIRouter()
+        broadcaster = self._broadcaster
+        cap = self._history_limit_cap
+        default_limit = self._default_limit
+        envelope_shape = self._envelope_shape
+        field_mapping = self._field_mapping
+        order = self._order
+        event_id_format = self._event_id_format
+
+        def _render_event(evt: ConfigChangeEvent) -> dict[str, Any]:
+            payload = evt.to_dict(alias_map=field_mapping)
+            if event_id_format == "uuid_string":
+                # The canonical ``event_id`` key may have been renamed via
+                # field_mapping — rewrite the correct output key.
+                out_key = (
+                    field_mapping.get("event_id", "event_id")
+                    if field_mapping
+                    else "event_id"
+                )
+                payload[out_key] = _int_event_id_to_uuid(int(evt.event_id))
+            return payload
+
+        @router.get(self._mount_path)
+        async def poll(
+            since: int = Query(default=0, ge=0),
+            limit: Optional[int] = Query(default=None, ge=1),
+        ) -> JSONResponse:
+            effective_limit = default_limit if limit is None else limit
+            if effective_limit > cap:
+                effective_limit = cap
+            # REST-poll cursor semantics require OLDEST-first pagination from
+            # the since cursor. broadcaster.history() returns the newest N when
+            # matches exceed limit, which is correct for SSE "most recent N"
+            # replay but NOT for paging — fetch a wider window (cap) then trim
+            # the oldest `effective_limit`.
+            window = broadcaster.history(after_id=since, limit=cap)
+            events = window[:effective_limit]
+            # Cursor is computed from the oldest-first batch regardless of
+            # presentation order — it is a pagination token over monotonic
+            # event_ids, not a client-ordered key.
+            next_cursor = events[-1].event_id if events else since
+            if order == "newest_first":
+                events = list(reversed(events))
+            payload_events = [_render_event(evt) for evt in events]
+            if envelope_shape == "events_only":
+                return JSONResponse({"events": payload_events})
+            return JSONResponse({"events": payload_events, "cursor": next_cursor})
+
+        return router
+
+    def mount(self, app: FastAPI) -> None:
+        """Convenience: include the REST-poll router into a FastAPI app."""
+        app.include_router(self.router())
+
+
+__all__ = [
+    "ConfigChangeEvent",
+    "EventBroadcaster",
+    "HTTPIngestAdapter",
+    "InMemoryEventBroadcaster",
+    "PersistentEventBroadcaster",
+    "RESTPollAdapter",
+    "WebSocketAdapter",
+    "create_a2a_events_router",
+]