feat: module architecture improvements — session keys, dependency graph, event dispatcher, deactivation hooks

Six targeted improvements to the modular monolith platform:

1. Fix AddressBook session key prefix to follow module.<id>.* convention
2. Move ADDRESS_BOOK_VIEW permission constant from core PermissionService into module
3. Add declarative JSON schema for module manifests (.agents/contracts/)
4. Add `requires` field with missing-dependency and circular-dependency detection
5. Add lightweight fire-and-forget event dispatcher (user.created/deleted/login/logout)
6. Add module deactivation hook interface and CLI script (bin/module-deactivate.php)

Includes 15 new architecture/unit tests covering all new functionality.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

tests/Unit/Module/AddressBookAuthorizationPolicyTest.php

@@ -38,7 +38,7 @@ final class AddressBookAuthorizationPolicyTest extends TestCase
     public function testAllowedWithPermission(): void
     {
         $permissionService = $this->permissionGatewayAllowing([
-            5 => [PermissionService::ADDRESS_BOOK_VIEW],
+            5 => [AddressBookAuthorizationPolicy::PERMISSION_KEY],
         ]);
 
         $policy = new AddressBookAuthorizationPolicy($permissionService);

tests/Unit/Module/LayoutContextProviderTest.php

@@ -38,7 +38,7 @@ final class LayoutContextProviderTest extends TestCase
         $container = new AppContainer();
 
         $session = [
-            'available_departments_by_tenant' => [
+            'module.addressbook.departments_by_tenant' => [
                 [
                     'tenant' => ['uuid' => 'abc', 'description' => 'Tenant A'],
                     'departments' => [['id' => 1, 'description' => 'Dept 1']],

tests/Unit/Module/ModuleEventDispatcherTest.php

@@ -0,0 +1,100 @@
+<?php
+
+namespace MintyPHP\Tests\Unit\Module;
+
+use MintyPHP\App\AppContainer;
+use MintyPHP\App\Module\Contracts\EventListener;
+use MintyPHP\App\Module\ModuleEventDispatcher;
+use PHPUnit\Framework\TestCase;
+
+final class ModuleEventDispatcherTest extends TestCase
+{
+    public function testDispatchCallsRegisteredListeners(): void
+    {
+        $called = false;
+        $capturedEvent = '';
+        $capturedPayload = [];
+
+        $listener = new class ($called, $capturedEvent, $capturedPayload) implements EventListener {
+            public function __construct(
+                private bool &$called,
+                private string &$capturedEvent,
+                private array &$capturedPayload
+            ) {
+            }
+
+            public function handle(string $event, array $payload): void
+            {
+                $this->called = true;
+                $this->capturedEvent = $event;
+                $this->capturedPayload = $payload;
+            }
+        };
+
+        $container = new AppContainer();
+        $container->set($listener::class, static fn () => $listener);
+
+        $dispatcher = new ModuleEventDispatcher(
+            ['user.deleted' => [['class' => $listener::class, 'method' => 'handle']]],
+            $container
+        );
+
+        $dispatcher->dispatch('user.deleted', ['user_id' => 42]);
+
+        self::assertTrue($called);
+        self::assertSame('user.deleted', $capturedEvent);
+        self::assertSame(['user_id' => 42], $capturedPayload);
+    }
+
+    public function testDispatchIsNoOpForUnknownEvent(): void
+    {
+        $container = new AppContainer();
+        $dispatcher = new ModuleEventDispatcher([], $container);
+
+        // Should not throw
+        $dispatcher->dispatch('unknown.event', ['data' => 'test']);
+
+        self::addToAssertionCount(1);
+    }
+
+    public function testDispatchContinuesAfterListenerException(): void
+    {
+        $secondCalled = false;
+
+        $failingListener = new class () implements EventListener {
+            public function handle(string $event, array $payload): void
+            {
+                throw new \RuntimeException('Listener failure');
+            }
+        };
+
+        $successListener = new class ($secondCalled) implements EventListener {
+            public function __construct(private bool &$called)
+            {
+            }
+
+            public function handle(string $event, array $payload): void
+            {
+                $this->called = true;
+            }
+        };
+
+        $container = new AppContainer();
+        $container->set($failingListener::class, static fn () => $failingListener);
+        $container->set($successListener::class, static fn () => $successListener);
+
+        $dispatcher = new ModuleEventDispatcher(
+            [
+                'user.created' => [
+                    ['class' => $failingListener::class, 'method' => 'handle'],
+                    ['class' => $successListener::class, 'method' => 'handle'],
+                ],
+            ],
+            $container
+        );
+
+        $dispatcher->dispatch('user.created', ['user_id' => 1]);
+
+        self::assertTrue($secondCalled, 'Second listener should be called even after the first one throws');
+    }
+}

tests/Unit/Module/SessionProviderTest.php

@@ -39,22 +39,22 @@ final class SessionProviderTest extends TestCase
 
     public function testPopulateWithInvalidUserClearsSessionKey(): void
     {
-        $_SESSION['available_departments_by_tenant'] = [['tenant' => 'old']];
+        $_SESSION['module.addressbook.departments_by_tenant'] = [['tenant' => 'old']];
 
         $provider = new AddressBookSessionProvider();
         $provider->populate(['id' => 0], $this->emptyContainer());
 
-        self::assertArrayNotHasKey('available_departments_by_tenant', $_SESSION);
+        self::assertArrayNotHasKey('module.addressbook.departments_by_tenant', $_SESSION);
     }
 
     public function testPopulateWithMissingUserIdClearsSessionKey(): void
     {
-        $_SESSION['available_departments_by_tenant'] = [['tenant' => 'old']];
+        $_SESSION['module.addressbook.departments_by_tenant'] = [['tenant' => 'old']];
 
         $provider = new AddressBookSessionProvider();
         $provider->populate([], $this->emptyContainer());
 
-        self::assertArrayNotHasKey('available_departments_by_tenant', $_SESSION);
+        self::assertArrayNotHasKey('module.addressbook.departments_by_tenant', $_SESSION);
     }
 
     public function testPopulateReturnsEarlyWhenContainerMissesDependencies(): void
@@ -69,19 +69,19 @@ final class SessionProviderTest extends TestCase
             // in production, bindings are always registered before providers run.
         }
 
-        self::assertArrayNotHasKey('available_departments_by_tenant', $_SESSION);
+        self::assertArrayNotHasKey('module.addressbook.departments_by_tenant', $_SESSION);
     }
 
     public function testClearRemovesSessionKey(): void
     {
-        $_SESSION['available_departments_by_tenant'] = [
+        $_SESSION['module.addressbook.departments_by_tenant'] = [
             ['tenant' => ['uuid' => 'abc'], 'departments' => []],
         ];
 
         $provider = new AddressBookSessionProvider();
         $provider->clear();
 
-        self::assertArrayNotHasKey('available_departments_by_tenant', $_SESSION);
+        self::assertArrayNotHasKey('module.addressbook.departments_by_tenant', $_SESSION);
     }
 
     public function testClearIsIdempotent(): void
@@ -90,6 +90,6 @@ final class SessionProviderTest extends TestCase
         $provider = new AddressBookSessionProvider();
         $provider->clear();
 
-        self::assertArrayNotHasKey('available_departments_by_tenant', $_SESSION);
+        self::assertArrayNotHasKey('module.addressbook.departments_by_tenant', $_SESSION);
     }
 }