From 68ef4c70d029b3e909e3143181a9f7724304a009 Mon Sep 17 00:00:00 2001
From: NagyZoltanPeter <113987313+NagyZoltanPeter@users.noreply.github.com>
Date: Thu, 25 Jun 2026 23:07:13 +0200
Subject: [PATCH] Move events back into interface-class source files (restore
 #3975 placement)

Reverses the earlier dedup-by-re-export: event TYPE definitions now live in the
interface classes, and the emptied decomposed event files are removed.

- MessageSeenEvent            -> logos_delivery/api/kernel_api.nim
- Message{Sent,Error,Propagated,Received}Event -> api/messaging_client_api.nim
- ChannelMessage{Received,Sent,Error}Event     -> api/reliable_channel_manager_api.nim
- EventConnectionStatusChange -> api/logos_delivery_api.nim

Deleted (became empty after the move):
- logos_delivery/waku/api/events/message_events.nim
- logos_delivery/messaging/api/events.nim
- logos_delivery/channels/api/events.nim
health_events.nim keeps its two remaining events (content/shard topic health).

Rewiring: each layer re-exports its interface module (waku->kernel_api,
messaging_client->messaging_client_api, reliable_channel->reliable_channel_manager_api,
which also re-exports messaging_client_api). Deep emitters/listeners
(subscription_manager, waku_node, waku_node/relay, node_health_monitor,
recv_service, send_service) import the owning interface module directly.
kernel_api stays below node level (types/topics/message/store-common) so the
node->kernel_api imports are acyclic. liblogosdelivery builds.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 logos_delivery/api/kernel_api.nim             | 13 ++++---
 logos_delivery/api/logos_delivery_api.nim     |  9 ++---
 logos_delivery/api/messaging_client_api.nim   | 32 ++++++++++++---
 .../api/reliable_channel_manager_api.nim      | 34 +++++++++++++---
 logos_delivery/channels/api/events.nim        | 39 -------------------
 logos_delivery/channels/reliable_channel.nim  |  3 +-
 logos_delivery/logos_delivery.nim             | 12 +++---
 logos_delivery/messaging/api/events.nim       | 30 --------------
 .../recv_service/recv_service.nim             |  7 ++--
 .../send_service/send_service.nim             |  2 +-
 logos_delivery/messaging/messaging_client.nim |  3 ++
 logos_delivery/waku/api/events/events.nim     |  9 +----
 .../waku/api/events/health_events.nim         |  6 +--
 .../waku/api/events/message_events.nim        | 10 -----
 .../health_monitor/node_health_monitor.nim    |  1 +
 .../waku/node/subscription_manager.nim        |  2 +-
 logos_delivery/waku/node/waku_node.nim        |  2 +-
 logos_delivery/waku/node/waku_node/relay.nim  |  2 +-
 logos_delivery/waku/waku.nim                  |  4 ++
 .../test_reliable_channel_send_receive.nim    |  2 +-
 20 files changed, 94 insertions(+), 128 deletions(-)
 delete mode 100644 logos_delivery/channels/api/events.nim
 delete mode 100644 logos_delivery/messaging/api/events.nim
 delete mode 100644 logos_delivery/waku/api/events/message_events.nim

diff --git a/logos_delivery/api/kernel_api.nim b/logos_delivery/api/kernel_api.nim
index 8be6f9d56..35cf7251f 100644
--- a/logos_delivery/api/kernel_api.nim
+++ b/logos_delivery/api/kernel_api.nim
@@ -4,19 +4,20 @@ 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_core/message
 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
 
+EventBroker:
+  # Internal event emitted when a message arrives from the network via any protocol
+  type MessageSeenEvent* = object
+    topic*: PubsubTopic
+    message*: WakuMessage
+
 # --- topic construction ---
 method buildContentTopic*(
     self: IKernel, appName: string, appVersion: uint32, name: string, encoding: string
diff --git a/logos_delivery/api/logos_delivery_api.nim b/logos_delivery/api/logos_delivery_api.nim
index acdd3725b..162159d8e 100644
--- a/logos_delivery/api/logos_delivery_api.nim
+++ b/logos_delivery/api/logos_delivery_api.nim
@@ -13,17 +13,16 @@ import results, chronos
 import brokers/event_broker
 import types as api_types
 
-# `EventConnectionStatusChange` lives in the decomposed health-events module.
-# Re-export it here so the orchestrator surfaces it without duplicating the type.
-import logos_delivery/waku/api/events/health_events as health_events
-
 export api_types, event_broker
-export health_events
 
 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")
 
diff --git a/logos_delivery/api/messaging_client_api.nim b/logos_delivery/api/messaging_client_api.nim
index 065bf25a3..f29a5cb41 100644
--- a/logos_delivery/api/messaging_client_api.nim
+++ b/logos_delivery/api/messaging_client_api.nim
@@ -2,17 +2,37 @@ 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
+import logos_delivery/waku/waku_core/message
 
 export event_broker, api_types
-export messaging_events
 
 type IMessagingClient* = ref object of RootObj
 
+EventBroker:
+  # Event emitted when a message is sent to the network
+  type MessageSentEvent* = object
+    requestId*: RequestId
+    messageHash*: string
+
+EventBroker:
+  # Event emitted when a message send operation fails
+  type MessageErrorEvent* = object
+    requestId*: RequestId
+    messageHash*: string
+    error*: string
+
+EventBroker:
+  # Confirmation that a message has been correctly delivered to some neighbouring nodes.
+  type MessagePropagatedEvent* = object
+    requestId*: RequestId
+    messageHash*: string
+
+EventBroker:
+  # Event emitted when a message is received via Waku
+  type MessageReceivedEvent* = object
+    messageHash*: string
+    message*: WakuMessage
+
 method subscribe*(
     self: IMessagingClient, contentTopic: ContentTopic
 ): Future[Result[void, string]] {.async: (raises: []), base.} =
diff --git a/logos_delivery/api/reliable_channel_manager_api.nim b/logos_delivery/api/reliable_channel_manager_api.nim
index 0a34994d9..c5266972a 100644
--- a/logos_delivery/api/reliable_channel_manager_api.nim
+++ b/logos_delivery/api/reliable_channel_manager_api.nim
@@ -3,14 +3,16 @@ import chronos, results
 import brokers/event_broker
 
 import logos_delivery/api/types as api_types
+import logos_delivery/channels/types as channel_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
+# The channel layer re-uses the messaging-layer message events (the `requestId`
+# is shared across layers), so it re-exports the messaging interface's event
+# surface and only adds the channel-level events that have no lower-layer
+# analogue (reassembled payload / senderId / channelId).
+import logos_delivery/api/messaging_client_api
 
 export event_broker, api_types
-export channel_events
+export channel_types, messaging_client_api
 
 type
   IReliableChannelManager* = ref object of RootObj
@@ -23,6 +25,28 @@ type
     ## `RequestId`s so the send state machine can be exercised end-to-end
     ## without a network.
 
+EventBroker:
+  type ChannelMessageReceivedEvent* = object
+    channelId*: ChannelId
+    senderId*: SdsParticipantID
+    payload*: seq[byte]
+
+EventBroker:
+  ## Emitted when every segment of a channel-level `send()` reached
+  ## `Confirmed`. Channel-level analogue of `MessageSentEvent`; the
+  ## `requestId` is the channel-layer parent returned by `send()`.
+  type ChannelMessageSentEvent* = object
+    channelId*: ChannelId
+    requestId*: RequestId
+
+EventBroker:
+  ## Emitted when a channel-level `send()` finalises with at least one
+  ## segment in `Failed`. Channel-level analogue of `MessageErrorEvent`.
+  type ChannelMessageErrorEvent* = object
+    channelId*: ChannelId
+    requestId*: RequestId
+    error*: string
+
 method createReliableChannel*(
     self: IReliableChannelManager,
     channelId: ChannelId,
diff --git a/logos_delivery/channels/api/events.nim b/logos_delivery/channels/api/events.nim
deleted file mode 100644
index 685059053..000000000
--- a/logos_delivery/channels/api/events.nim
+++ /dev/null
@@ -1,39 +0,0 @@
-## Reliable Channel layer API — event surface.
-##
-## Lifecycle events for individual segments (sent / propagated / errored)
-## are the same as the network-level ones the MessagingClient already
-## emits — `requestId` is shared across layers — so we just re-export
-## `messaging/api/events` and avoid declaring duplicates.
-##
-## Only the channel-level `MessageReceivedEvent` carries data that has
-## no analogue in the lower layer (reassembled application payload,
-## senderId, channelId), so it lives here.
-
-import logos_delivery/messaging/api/events as messaging_events
-import brokers/event_broker
-
-import logos_delivery/channels/types as channel_types
-
-export messaging_events, channel_types, event_broker
-
-EventBroker:
-  type ChannelMessageReceivedEvent* = object
-    channelId*: ChannelId
-    senderId*: SdsParticipantID
-    payload*: seq[byte]
-
-EventBroker:
-  ## Emitted when every segment of a channel-level `send()` reached
-  ## `Confirmed`. Channel-level analogue of `MessageSentEvent`; the
-  ## `requestId` is the channel-layer parent returned by `send()`.
-  type ChannelMessageSentEvent* = object
-    channelId*: ChannelId
-    requestId*: RequestId
-
-EventBroker:
-  ## Emitted when a channel-level `send()` finalises with at least one
-  ## segment in `Failed`. Channel-level analogue of `MessageErrorEvent`.
-  type ChannelMessageErrorEvent* = object
-    channelId*: ChannelId
-    requestId*: RequestId
-    error*: string
diff --git a/logos_delivery/channels/reliable_channel.nim b/logos_delivery/channels/reliable_channel.nim
index f81b9a0b0..dfaf96f94 100644
--- a/logos_delivery/channels/reliable_channel.nim
+++ b/logos_delivery/channels/reliable_channel.nim
@@ -26,14 +26,13 @@ import logos_delivery/api/reliable_channel_manager_api
 import logos_delivery/messaging/delivery_service/send_service
 import logos_delivery/waku/waku_core/topics
 
-import logos_delivery/channels/api/events
 import ./segmentation/segmentation
 import ./scalable_data_sync/scalable_data_sync
 import ./rate_limit_manager/rate_limit_manager
 import ./encryption/encryption
 
 export
-  types, reliable_channel_manager_api, send_service, events, segmentation,
+  types, reliable_channel_manager_api, send_service, segmentation,
   scalable_data_sync, rate_limit_manager, encryption
 
 const LipWireReliableChannelVersion* = "RELIABLE-CHANNEL-API/1"
diff --git a/logos_delivery/logos_delivery.nim b/logos_delivery/logos_delivery.nim
index 3c0f61d10..435bb968d 100644
--- a/logos_delivery/logos_delivery.nim
+++ b/logos_delivery/logos_delivery.nim
@@ -30,16 +30,17 @@ import
   ]
 export
   topics, relay, filter, lightpush, store, peer_manager, discovery, debug, health, ping
-import logos_delivery/waku/api/events/[message_events, health_events]
-export message_events, health_events
+# `MessageSeenEvent` is surfaced via `export waku` (Kernel interface); the
+# remaining waku health events live here.
+import logos_delivery/waku/api/events/health_events
+export health_events
 
 # Messaging layer
 import logos_delivery/messaging/messaging_client
 export messaging_client
 import logos_delivery/messaging/api/[subscription, send]
 export subscription, send
-import logos_delivery/messaging/api/events as messaging_api_events
-export messaging_api_events
+# Message* events are surfaced via `export messaging_client` (messaging interface).
 
 # Reliable Channel layer
 import logos_delivery/channels/reliable_channel_manager
@@ -48,8 +49,7 @@ import logos_delivery/channels/api/channel_lifecycle
 export channel_lifecycle
 import logos_delivery/channels/api/send as channel_send
 export channel_send
-import logos_delivery/channels/api/events as channels_api_events
-export channels_api_events
+# ChannelMessage* events are surfaced via `export reliable_channel_manager`.
 
 import logos_delivery/waku/factory/waku_conf
 import logos_delivery/waku/factory/app_callbacks
diff --git a/logos_delivery/messaging/api/events.nim b/logos_delivery/messaging/api/events.nim
deleted file mode 100644
index 89ec704b9..000000000
--- a/logos_delivery/messaging/api/events.nim
+++ /dev/null
@@ -1,30 +0,0 @@
-## Messaging layer API — event surface (messaging-level message events).
-import brokers/event_broker
-import logos_delivery/api/types
-import logos_delivery/waku/waku_core/message
-export event_broker, types
-
-EventBroker:
-  # Event emitted when a message is sent to the network
-  type MessageSentEvent* = object
-    requestId*: RequestId
-    messageHash*: string
-
-EventBroker:
-  # Event emitted when a message send operation fails
-  type MessageErrorEvent* = object
-    requestId*: RequestId
-    messageHash*: string
-    error*: string
-
-EventBroker:
-  # Confirmation that a message has been correctly delivered to some neighbouring nodes.
-  type MessagePropagatedEvent* = object
-    requestId*: RequestId
-    messageHash*: string
-
-EventBroker:
-  # Event emitted when a message is received via Waku
-  type MessageReceivedEvent* = object
-    messageHash*: string
-    message*: WakuMessage
diff --git a/logos_delivery/messaging/delivery_service/recv_service/recv_service.nim b/logos_delivery/messaging/delivery_service/recv_service/recv_service.nim
index a6e9701d9..25b35222d 100644
--- a/logos_delivery/messaging/delivery_service/recv_service/recv_service.nim
+++ b/logos_delivery/messaging/delivery_service/recv_service/recv_service.nim
@@ -13,12 +13,13 @@ import
     waku_store/client,
     waku_store/common,
     waku_filter_v2/client,
-    api/events/message_events,
-    api/events/health_events,
     waku_node,
     node/subscription_manager,
   ]
-import logos_delivery/messaging/api/events
+import
+  logos_delivery/api/kernel_api, # MessageSeenEvent
+  logos_delivery/api/messaging_client_api, # MessageReceivedEvent
+  logos_delivery/api/logos_delivery_api # EventConnectionStatusChange
 
 const MaxMessageLife = chronos.minutes(7) ## Max time we will keep track of rx messages
 
diff --git a/logos_delivery/messaging/delivery_service/send_service/send_service.nim b/logos_delivery/messaging/delivery_service/send_service/send_service.nim
index 5e21ac4ba..f77c6858c 100644
--- a/logos_delivery/messaging/delivery_service/send_service/send_service.nim
+++ b/logos_delivery/messaging/delivery_service/send_service/send_service.nim
@@ -19,7 +19,7 @@ import
     waku_lightpush/client,
     waku_lightpush/callbacks,
   ]
-import logos_delivery/messaging/api/events
+import logos_delivery/api/messaging_client_api
 
 logScope:
   topics = "send service"
diff --git a/logos_delivery/messaging/messaging_client.nim b/logos_delivery/messaging/messaging_client.nim
index 3bcf5ae1c..69c6c520b 100644
--- a/logos_delivery/messaging/messaging_client.nim
+++ b/logos_delivery/messaging/messaging_client.nim
@@ -7,6 +7,9 @@ import
   logos_delivery/waku/node/waku_node,
   logos_delivery/messaging/delivery_service/[recv_service, send_service]
 
+# Surfaces the messaging API interface (and its Message* events) to consumers.
+export messaging_client_api
+
 type
   MessagingClientConf* = object
     ## Per-layer config object for the messaging API.
diff --git a/logos_delivery/waku/api/events/events.nim b/logos_delivery/waku/api/events/events.nim
index 1340d60ba..e9f175e65 100644
--- a/logos_delivery/waku/api/events/events.nim
+++ b/logos_delivery/waku/api/events/events.nim
@@ -1,8 +1,3 @@
-import
-  ./[
-    message_events, filter_subscribe_events, health_events, peer_events,
-    discovery_events,
-  ]
+import ./[filter_subscribe_events, health_events, peer_events, discovery_events]
 
-export
-  message_events, filter_subscribe_events, health_events, peer_events, discovery_events
+export filter_subscribe_events, health_events, peer_events, discovery_events
diff --git a/logos_delivery/waku/api/events/health_events.nim b/logos_delivery/waku/api/events/health_events.nim
index d19de776b..fbf00debb 100644
--- a/logos_delivery/waku/api/events/health_events.nim
+++ b/logos_delivery/waku/api/events/health_events.nim
@@ -6,10 +6,8 @@ import logos_delivery/waku/waku_core/topics
 
 export protocol_health, topic_health
 
-# Notify health changes to node connectivity
-EventBroker:
-  type EventConnectionStatusChange* = object
-    connectionStatus*: ConnectionStatus
+# Note: `EventConnectionStatusChange` lives in `logos_delivery/api/logos_delivery_api`
+# (the top-level orchestrator interface owns the node-connectivity event).
 
 # Notify health changes to a subscribed topic
 # TODO: emit content topic health change events when subscribe/unsubscribe
diff --git a/logos_delivery/waku/api/events/message_events.nim b/logos_delivery/waku/api/events/message_events.nim
deleted file mode 100644
index 638d4f38a..000000000
--- a/logos_delivery/waku/api/events/message_events.nim
+++ /dev/null
@@ -1,10 +0,0 @@
-import brokers/event_broker
-import logos_delivery/api/types
-import logos_delivery/waku/[waku_core/message, waku_core/topics]
-export event_broker, types
-
-EventBroker:
-  # Internal event emitted when a message arrives from the network via any protocol
-  type MessageSeenEvent* = object
-    topic*: PubsubTopic
-    message*: WakuMessage
diff --git a/logos_delivery/waku/node/health_monitor/node_health_monitor.nim b/logos_delivery/waku/node/health_monitor/node_health_monitor.nim
index d55499d1a..1b2ea16e9 100644
--- a/logos_delivery/waku/node/health_monitor/node_health_monitor.nim
+++ b/logos_delivery/waku/node/health_monitor/node_health_monitor.nim
@@ -9,6 +9,7 @@ import
   libp2p/protocols/pubsub,
   libp2p/protocols/pubsub/rpc/messages,
   logos_delivery/api/types,
+  logos_delivery/api/logos_delivery_api, # EventConnectionStatusChange
   logos_delivery/waku/[
     waku_relay,
     waku_rln_relay,
diff --git a/logos_delivery/waku/node/subscription_manager.nim b/logos_delivery/waku/node/subscription_manager.nim
index 69f67ab3b..d0468749d 100644
--- a/logos_delivery/waku/node/subscription_manager.nim
+++ b/logos_delivery/waku/node/subscription_manager.nim
@@ -16,13 +16,13 @@ import
     waku_filter_v2/client as filter_client,
     waku_filter_v2/protocol as filter_protocol,
     api/events/health_events,
-    api/events/message_events,
     api/events/peer_events,
     requests/health_requests,
     node/peer_manager,
     node/health_monitor/topic_health,
     node/health_monitor/connection_status,
   ]
+import logos_delivery/api/kernel_api # MessageSeenEvent
 
 {.push raises: [].}
 
diff --git a/logos_delivery/waku/node/waku_node.nim b/logos_delivery/waku/node/waku_node.nim
index a329226cc..b00b2fe12 100644
--- a/logos_delivery/waku/node/waku_node.nim
+++ b/logos_delivery/waku/node/waku_node.nim
@@ -60,9 +60,9 @@ import
     requests/node_requests,
     requests/health_requests,
     api/events/health_events,
-    api/events/message_events,
     api/events/peer_events,
   ],
+  logos_delivery/api/kernel_api, # MessageSeenEvent
   logos_delivery/waku/discovery/waku_kademlia,
   logos_delivery/waku/net/[bound_ports, net_config],
   ./peer_manager,
diff --git a/logos_delivery/waku/node/waku_node/relay.nim b/logos_delivery/waku/node/waku_node/relay.nim
index f2a2772e0..57271be54 100644
--- a/logos_delivery/waku/node/waku_node/relay.nim
+++ b/logos_delivery/waku/node/waku_node/relay.nim
@@ -32,8 +32,8 @@ import
     node/waku_node,
     node/subscription_manager,
     node/peer_manager,
-    api/events/message_events,
   ]
+import logos_delivery/api/kernel_api # MessageSeenEvent
 
 export waku_relay.WakuRelayHandler
 
diff --git a/logos_delivery/waku/waku.nim b/logos_delivery/waku/waku.nim
index 65af3050b..d3b3b9ead 100644
--- a/logos_delivery/waku/waku.nim
+++ b/logos_delivery/waku/waku.nim
@@ -58,6 +58,10 @@ import
   ./factory/waku_conf,
   ./factory/waku_state_info
 
+# Surfaces the Kernel API interface (and its `MessageSeenEvent`) to consumers
+# of the Waku layer.
+export kernel_api
+
 logScope:
   topics = "wakunode waku"
 
diff --git a/tests/channels/test_reliable_channel_send_receive.nim b/tests/channels/test_reliable_channel_send_receive.nim
index 17ceb56ad..3a0a48c06 100644
--- a/tests/channels/test_reliable_channel_send_receive.nim
+++ b/tests/channels/test_reliable_channel_send_receive.nim
@@ -10,7 +10,7 @@ import ../testlib/[common, wakucore, wakunode, testasync]
 import logos_delivery
 import logos_delivery/waku/[waku_node, waku_core]
 import logos_delivery/waku/factory/waku_conf
-import logos_delivery/messaging/api/events as waku_message_events
+import logos_delivery/api/messaging_client_api as waku_message_events
 import tools/confutils/cli_args
 
 import logos_delivery/channels/reliable_channel_manager