From 01ed0f30805a8af5f5a17cbdd1df4599828278ec Mon Sep 17 00:00:00 2001
From: Sebastian Krupinski <krupinski01@gmail.com>
Date: Wed, 5 Aug 2026 22:04:26 -0400
Subject: [PATCH] feat: Introduce event listener registration contract

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
---
 core/lib/Kernel.php                           |  2 ++
 core/lib/Module/Module.php                    |  4 ++--
 .../Event/EventListenerRegistrarInterface.php | 21 +++++++++++++++++++
 shared/lib/Event/EventListenerRegistry.php    |  2 +-
 4 files changed, 26 insertions(+), 3 deletions(-)
 create mode 100644 shared/lib/Event/EventListenerRegistrarInterface.php

diff --git a/core/lib/Kernel.php b/core/lib/Kernel.php
index 588c923..0655e35 100644
--- a/core/lib/Kernel.php
+++ b/core/lib/Kernel.php
@@ -30,6 +30,7 @@ use KTXC\Logger\TenantAwareLogger;
 use KTXF\Event\DeferredEventProcessorInterface;
 use KTXF\Event\EventDispatcher;
 use KTXF\Event\EventDispatcherInterface;
+use KTXF\Event\EventListenerRegistrarInterface;
 use KTXF\Event\EventListenerRegistry;
 use KTXF\Cache\EphemeralCacheInterface;
 use KTXF\Cache\PersistentCacheInterface;
@@ -410,6 +411,7 @@ class Kernel implements KernelInterface
             
             EventDispatcherInterface::class => \DI\get(EventDispatcher::class),
             DeferredEventProcessorInterface::class => \DI\get(EventDispatcher::class),
+            EventListenerRegistrarInterface::class => \DI\get(EventListenerRegistry::class),
             // Ephemeral Cache - for short-lived data (sessions, rate limits, challenges)
             EphemeralCacheInterface::class => function(ContainerInterface $c) use ($projectDir) {
                 $storeType = $c->has('cache.ephemeral') ? $c->get('cache.ephemeral') : 'file';
diff --git a/core/lib/Module/Module.php b/core/lib/Module/Module.php
index b962036..adb1222 100644
--- a/core/lib/Module/Module.php
+++ b/core/lib/Module/Module.php
@@ -12,7 +12,7 @@ use KTXC\Service\TenantFirewallLogService;
 use KTXC\Service\TenantFirewallRuleService;
 use KTXC\Service\TenantFirewallStatusService;
 use KTXF\Event\DeliveryMode;
-use KTXF\Event\EventListenerRegistry;
+use KTXF\Event\EventListenerRegistrarInterface;
 use KTXF\Event\SecurityEvent;
 use KTXF\Module\ModuleBrowserInterface;
 use KTXF\Module\ModuleConsoleInterface;
@@ -26,7 +26,7 @@ use KTXF\Module\ModuleInstanceAbstract;
 class Module extends ModuleInstanceAbstract implements ModuleConsoleInterface, ModuleBrowserInterface
 {
     public function __construct(
-        private readonly EventListenerRegistry $events,
+        private readonly EventListenerRegistrarInterface $events,
     ) {
     }
 
diff --git a/shared/lib/Event/EventListenerRegistrarInterface.php b/shared/lib/Event/EventListenerRegistrarInterface.php
new file mode 100644
index 0000000..4780a22
--- /dev/null
+++ b/shared/lib/Event/EventListenerRegistrarInterface.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\Event;
+
+interface EventListenerRegistrarInterface
+{
+    /**
+     * @param class-string $service
+     */
+    public function listen(
+        string $module,
+        string $event,
+        string $service,
+        string $method,
+        DeliveryMode $delivery = DeliveryMode::Immediate,
+        int $priority = 0,
+        FailurePolicy $failurePolicy = FailurePolicy::Continue,
+    ): void;
+}
diff --git a/shared/lib/Event/EventListenerRegistry.php b/shared/lib/Event/EventListenerRegistry.php
index 624b189..c8919a8 100644
--- a/shared/lib/Event/EventListenerRegistry.php
+++ b/shared/lib/Event/EventListenerRegistry.php
@@ -6,7 +6,7 @@ namespace KTXF\Event;
 
 use Psr\Container\ContainerInterface;
 
-final class EventListenerRegistry
+final class EventListenerRegistry implements EventListenerRegistrarInterface
 {
     /** @var array<string, list<EventListenerDefinition>> */
     private array $listeners = [];