Dispatching and Listening Pattern

The Core registry functions are intentionally small. A caller creates or receives a registry, registers listeners, then applies a hook or dispatches an event with payload and request context.

Hook pattern

Hooks are ordered by priority in `core/hooks/hook_registry.php`. Higher `priority` values run first. The dispatcher in `core/hooks/hook_dispatcher.php` carries the current payload forward only when a listener returns an array.

$hooks = amv_core_hook_registry_create();

$hooks = amv_core_hook_listener_register(
    $hooks,
    'content.article.before_save',
    static function (array $payload, array $context, array $metadata): array {
        $payload['title'] = trim((string) ($payload['title'] ?? ''));
        return $payload;
    },
    120,
    ['provider_key' => 'content_manager']
);

$result = amv_core_hook_apply($hooks, 'content.article.before_save', $articlePayload, $context);
$articlePayload = $result['payload'];

Check `failures` after dispatch. Invalid names return `invalid_hook_name`; broken listeners are reported as `listener_failed` instead of crashing the whole rail.

Event pattern

Events are notification-style. The dispatcher in `core/events/event_dispatcher.php` calls every listener with the same payload and context.

$events = amv_core_event_registry_create();

$events = amv_core_event_listener_register(
    $events,
    'content.article.published',
    static function (array $payload, array $context, array $metadata): void {
        // Queue a notification, index search content, or schedule follow-up work here.
    },
    ['provider_key' => 'notifications']
);

$result = amv_core_event_dispatch($events, 'content.article.published', [
    'article_uuid' => $articleUuid,
    'actor_uuid' => $actorUuid,
], $context);

Listener guidance

Listeners should accept missing optional payload fields, validate anything security-sensitive, and avoid direct output. A listener should return quickly or hand long work to the owning queue or scheduler.