Resolution order

NotificationCompass evaluates a preference in this order:

1. Required-context check, which blocks when no context is available.
2. Mandatory definition or channel rule.
3. Enforced context policy.
4. Explicit context preference.
5. Explicit global preference.
6. Default context policy.
7. Definition default for the current context.
8. Definition default for the channel.
9. Channel-level default inside the definition.
10. Opt-in fallback, which disables the notification.
11. Global channel default from configuration.
12. Package default from configuration.

The first matching rule wins. A required context is a prerequisite rather than a fallback value: when it is missing, the result is disabled with the context_required reason and global preferences are not consulted. A mandatory result is always enabled and is not modifiable.

Context policies come from NotificationContextPreferenceStore. A default policy applies after user preferences, while an enforced policy takes precedence over them. This distinction lets a community, team, organization, or workspace choose between a suggestion and a rule for all its members. The resolved source is context_policy, and its mode is exposed on ResolvedPreference::$mode.

$preference = $user->effectiveNotificationPreference(
    'booking.created',
    'mail',
    new NotificationContext('organization', 42),
);

$preference->enabled;
$preference->reason->value;
$preference->source;
$preference->isModifiable();

reason is a NotificationDecisionReason code that can be stored in logs or asserted in tests. It distinguishes mandatory rules, user preferences, context policies, defaults, and gate failures such as undeclared channels or unauthorized contexts.