# Beacon Specification (SPECS)

## Overview
Beacon is a high-performance, PSR-14 compliant event management system. It is designed to be decoupled, utilizing `BeaconContracts` for interfaces and providing an enterprise-grade engine with middleware support, attribute-based discovery, and telemetry.

---

## 1. Core Interfaces (BeaconContracts)
The foundation of Beacon must be defined in `getphred/beacon-contracts`.

- **EventDispatcherInterface**: Extends `Psr\EventDispatcher\EventDispatcherInterface`.
- **ListenerProviderInterface**: Extends `Psr\EventDispatcher\ListenerProviderInterface`.
- **SubscriberInterface**: Defines `getSubscribedEvents(): array`.
- **StoppableEventInterface**: Extends `Psr\EventDispatcher\StoppableEventInterface`.
- **DispatchMiddlewareInterface**: Defines `handle(object $event, callable $next): object`.

---

## 2. Event Dispatcher (The Engine)
The primary implementation of the dispatcher.

- **PSR-14 Compliance**: Must correctly handle event objects and return them.
- **Middleware Support**: Implements an "Onion" style pipeline.
    - Global middleware can intercept every dispatch.
    - Middleware can modify the event or stop propagation.
- **Resiliency Modes**:
    - `FAIL_FAST`: Stops execution on the first listener exception.
    - `CONTINUE`: Logs the error, dispatches a `DispatchFailed` internal event, and moves to the next listener.
- **Telemetry**: Internal tracking of listener execution time and memory usage.

---

## 3. Listener Provider & Resolution
The logic for finding who cares about an event.

- **Priority Handling**: Listeners are sorted by priority (higher integer runs first).
- **Inheritance Resolution**: 
    - Automatically resolves listeners for the event class, its parents, and its interfaces.
    - Must include a performance toggle to disable interface scanning.
- **Wildcard Support**:
    - Support dot-notation wildcards (e.g., `user.*`, `*.created`).
    - Pattern matching converted to optimized regex with internal caching.
- **Lazy Loading**: Integration with a PSR-11 container to instantiate listeners only when they are about to be called.

---

## 4. Discovery & Registration
Mechanisms to register listeners without manual configuration.

- **Attribute Discovery**: 
    - Support `#[AsEventListener(event: string, priority: int)]`.
    - Support `#[AsSubscriber]`.
- **Listener Discovery Service**:
    - Scans directories for classes with Beacon attributes.
    - Integrates with PSR-16 cache to avoid scanning on every request.
- **Manual Registration**:
    - `addListener(string $event, callable $listener, int $priority = 0)`
    - `addSubscriber(SubscriberInterface $subscriber)`

---

## 5. Event Objects & Context
Enhancing the standard event pattern.

- **Event Envelope**: 
    - A wrapper to carry immutable metadata (e.g., `request_id`, `user_id`, `timestamp`).
    - Uses a `ContextMap` for type-safe metadata access.
- **Stoppable Trait**: Provide `CanStopPropagation` trait for easy implementation of `StoppableEventInterface`.

---

## 6. Testing Utilities
- **EventCollector**: A listener that gathers all dispatched events for assertions.
- **PHPUnit Assertions**: Traits for `assertEventDispatched`, `assertEventNotDispatched`, and `assertListenerCalled`.