Graft PR#3975 interface layer onto decomposed foundation (events deduped)

Add IKernel/IMessagingClient/IReliableChannelManager/ILogosDelivery interface
classes under logos_delivery/api/. The EventBroker types PR#3975 hoisted into
these files already exist in PR#3989's decomposed */api/events/ modules, so the
interface files re-export those modules instead of redefining the types
(avoids 8 duplicate EventBroker definitions). api/types.nim kept at the
foundation version (ChannelId stays in channels/types.nim, which the decomposed
modules import).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

logos_delivery/api/kernel_api.nim

@@ -0,0 +1,202 @@
+import std/options
+import chronos, results
+import brokers/event_broker
+
+import logos_delivery/api/types as api_types
+import logos_delivery/waku/waku_core/topics/pubsub_topic
+import logos_delivery/waku/waku_store/common as store_types
+
+# The Kernel-layer event surface lives in the decomposed `waku/api/events`
+# modules (see PR api-shape phase2). Re-export it here so the events remain
+# reachable at the interface level without duplicating the EventBroker types.
+import logos_delivery/waku/api/events/message_events as kernel_events
+
+export event_broker
+export api_types, pubsub_topic, store_types
+export kernel_events
+
+type IKernel* = ref object of RootObj
+
+# --- topic construction ---
+method buildContentTopic*(
+    self: IKernel, appName: string, appVersion: uint32, name: string, encoding: string
+): Future[Result[ContentTopic, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.buildContentTopic not implemented")
+
+method buildPubsubTopic*(
+    self: IKernel, topicName: string
+): Future[Result[PubsubTopic, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.buildPubsubTopic not implemented")
+
+method defaultPubsubTopic*(
+    self: IKernel
+): Future[Result[PubsubTopic, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.defaultPubsubTopic not implemented")
+
+# --- relay ---
+method relayPublish*(
+    self: IKernel, pubsubTopic: PubsubTopic, message: WakuMessage, timeoutMs: uint32
+): Future[Result[int, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.relayPublish not implemented")
+
+method relaySubscribe*(
+    self: IKernel, pubsubTopic: PubsubTopic
+): Future[Result[bool, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.relaySubscribe not implemented")
+
+method relayUnsubscribe*(
+    self: IKernel, pubsubTopic: PubsubTopic
+): Future[Result[bool, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.relayUnsubscribe not implemented")
+
+method relayAddProtectedShard*(
+    self: IKernel, clusterId: uint16, shardId: uint16, publicKey: string
+): Future[Result[bool, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.relayAddProtectedShard not implemented")
+
+method relayConnectedPeers*(
+    self: IKernel, pubsubTopic: PubsubTopic
+): Future[Result[seq[string], string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.relayConnectedPeers not implemented")
+
+method relayPeersInMesh*(
+    self: IKernel, pubsubTopic: PubsubTopic
+): Future[Result[seq[string], string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.relayPeersInMesh not implemented")
+
+# --- filter ---
+method filterSubscribe*(
+    self: IKernel,
+    pubsubTopic: Option[PubsubTopic],
+    contentTopics: seq[ContentTopic],
+    peer: string,
+): Future[Result[bool, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.filterSubscribe not implemented")
+
+method filterUnsubscribe*(
+    self: IKernel,
+    pubsubTopic: Option[PubsubTopic],
+    contentTopics: seq[ContentTopic],
+    peer: string,
+): Future[Result[bool, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.filterUnsubscribe not implemented")
+
+method filterUnsubscribeAll*(
+    self: IKernel, peer: string
+): Future[Result[bool, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.filterUnsubscribeAll not implemented")
+
+# --- lightpush ---
+method lightpushPublish*(
+    self: IKernel, pubsubTopic: PubsubTopic, message: WakuMessage, peer: string
+): Future[Result[string, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.lightpushPublish not implemented")
+
+# --- store ---
+method storeQuery*(
+    self: IKernel, request: StoreQueryRequest, peer: string, timeoutMs: int
+): Future[Result[StoreQueryResponse, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.storeQuery not implemented")
+
+# --- peer management ---
+method connect*(
+    self: IKernel, peers: seq[string], timeoutMs: uint32
+): Future[Result[bool, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.connect not implemented")
+
+method disconnectPeerById*(
+    self: IKernel, peerId: string
+): Future[Result[bool, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.disconnectPeerById not implemented")
+
+method disconnectAllPeers*(
+    self: IKernel
+): Future[Result[bool, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.disconnectAllPeers not implemented")
+
+method dialPeer*(
+    self: IKernel, peerAddr: string, protocol: string, timeoutMs: int
+): Future[Result[bool, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.dialPeer not implemented")
+
+method dialPeerById*(
+    self: IKernel, peerId: string, protocol: string, timeoutMs: int
+): Future[Result[bool, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.dialPeerById not implemented")
+
+method peerIdsFromPeerstore*(
+    self: IKernel
+): Future[Result[seq[string], string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.peerIdsFromPeerstore not implemented")
+
+method connectedPeersInfo*(
+    self: IKernel
+): Future[Result[seq[string], string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.connectedPeersInfo not implemented")
+
+method connectedPeers*(
+    self: IKernel
+): Future[Result[seq[string], string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.connectedPeers not implemented")
+
+method peerIdsByProtocol*(
+    self: IKernel, protocol: string
+): Future[Result[seq[string], string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.peerIdsByProtocol not implemented")
+
+# --- discovery ---
+method dnsDiscovery*(
+    self: IKernel, enrTreeUrl: string, nameServer: string, timeoutMs: int
+): Future[Result[seq[string], string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.dnsDiscovery not implemented")
+
+method discv5UpdateBootnodes*(
+    self: IKernel, bootnodes: seq[string]
+): Future[Result[bool, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.discv5UpdateBootnodes not implemented")
+
+method startDiscv5*(
+    self: IKernel
+): Future[Result[bool, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.startDiscv5 not implemented")
+
+method stopDiscv5*(
+    self: IKernel
+): Future[Result[bool, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.stopDiscv5 not implemented")
+
+method peerExchangeRequest*(
+    self: IKernel, numPeers: uint64
+): Future[Result[int, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.peerExchangeRequest not implemented")
+
+# --- debug / info ---
+method version*(
+    self: IKernel
+): Future[Result[string, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.version not implemented")
+
+method listenAddresses*(
+    self: IKernel
+): Future[Result[seq[string], string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.listenAddresses not implemented")
+
+method myEnr*(
+    self: IKernel
+): Future[Result[string, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.myEnr not implemented")
+
+method myPeerId*(
+    self: IKernel
+): Future[Result[string, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.myPeerId not implemented")
+
+method metrics*(
+    self: IKernel
+): Future[Result[string, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.metrics not implemented")
+
+method pingPeer*(
+    self: IKernel, peerAddr: string, timeoutMs: int
+): Future[Result[int64, string]] {.async: (raises: []), base.} =
+  return err("Interface IKernel.pingPeer not implemented")

logos_delivery/api/logos_delivery_api.nim

@@ -0,0 +1,33 @@
+## `LogosDelivery` is the project entry point. It is a pure concentrator: it
+## owns exactly one instance of each API layer
+##
+##   Waku  <-  MessagingClient  <-  ReliableChannelManager
+##
+## and chains them together (each layer drives the one below it). Every layer
+## keeps its own, separate public API — `LogosDelivery` only wires them up and
+## drives the shared `new` / `start` / `stop` lifecycle.
+
+{.push raises: [].}
+
+import results, chronos
+import brokers/event_broker
+import types as api_types
+
+export api_types, event_broker
+
+type
+  ## Entry point. Holds one instance of each API layer.
+  ILogosDelivery* = ref object of RootObj
+
+EventBroker:
+  type EventConnectionStatusChange* = object
+    connectionStatus*: ConnectionStatus
+
+method start*(self: ILogosDelivery): Future[Result[void, string]] {.async, base.} =
+  return err("ILogosDelivery.start not implemented")
+
+method stop*(self: ILogosDelivery): Future[Result[void, string]] {.async, base.} =
+  return err("ILogosDelivery.stop not implemented")
+
+method isOnline*(self: ILogosDelivery): Future[Result[bool, string]] {.async, base.} =
+  return err("ILogosDelivery.isOnline not implemented")

logos_delivery/api/messaging_client_api.nim

@@ -0,0 +1,29 @@
+import chronos, results
+import brokers/event_broker
+
+import logos_delivery/api/types as api_types
+
+# The messaging-layer event surface lives in the decomposed
+# `messaging/api/events` module. Re-export it here so the events stay reachable
+# at the interface level without duplicating the EventBroker types.
+import logos_delivery/messaging/api/events as messaging_events
+
+export event_broker, api_types
+export messaging_events
+
+type IMessagingClient* = ref object of RootObj
+
+method subscribe*(
+    self: IMessagingClient, contentTopic: ContentTopic
+): Future[Result[void, string]] {.async: (raises: []), base.} =
+  return err("Interface IMessagingClient.subscribe not implemented")
+
+method unsubscribe*(
+    self: IMessagingClient, contentTopic: ContentTopic
+): Result[void, string] {.base, raises: [].} =
+  return err("Interface IMessagingClient.unsubscribe not implemented")
+
+method send*(
+    self: IMessagingClient, envelope: MessageEnvelope
+): Future[Result[RequestId, string]] {.async: (raises: []), base.} =
+  return err("Interface IMessagingClient.send not implemented")

logos_delivery/api/reliable_channel_manager_api.nim

@@ -0,0 +1,46 @@
+import chronos, results
+
+import brokers/event_broker
+
+import logos_delivery/api/types as api_types
+
+# The channel-layer event surface lives in the decomposed `channels/api/events`
+# module. Re-export it here so the events stay reachable at the interface level
+# without duplicating the EventBroker types.
+import logos_delivery/channels/api/events as channel_events
+
+export event_broker, api_types
+export channel_events
+
+type
+  IReliableChannelManager* = ref object of RootObj
+
+  SendHandler* = proc(envelope: MessageEnvelope): Future[Result[RequestId, string]] {.
+    async: (raises: [CatchableError]), gcsafe
+  .}
+    ## Egress dispatch boundary. Typically wraps `MessagingClient.send`;
+    ## tests inject a fake that records calls and returns canned
+    ## `RequestId`s so the send state machine can be exercised end-to-end
+    ## without a network.
+
+method createReliableChannel*(
+    self: IReliableChannelManager,
+    channelId: ChannelId,
+    contentTopic: ContentTopic,
+    senderId: SdsParticipantID,
+    sendHandler: SendHandler = nil,
+): Result[ChannelId, string] {.base.} =
+  return err("Interface IReliableChannelManager.createReliableChannel not implemented")
+
+method closeChannel*(
+    self: IReliableChannelManager, channelId: ChannelId
+): Future[Result[void, string]] {.async: (raises: []), base.} =
+  return err("Interface IReliableChannelManager.closeChannel not implemented")
+
+method send*(
+    self: IReliableChannelManager,
+    channelId: ChannelId,
+    appPayload: seq[byte],
+    ephemeral: bool = false,
+): Future[Result[RequestId, string]] {.async: (raises: []), base.} =
+  return err("Interface IReliableChannelManager.send not implemented")