Eve library

Notification routing

Evidence

Revision 1

On this page

How one event becomes a set of people, why a person reached as both an assignee and a muted team member must be told anyway, which transports a notice may fall back onto without disclosing more than it started with, why a nine-hour quiet window is eight hours one night a year and ten another, and which end of a delivery needs somebody to have decided it and which needs only a clock.

Generated from libs/oshun/workbench-kit/src/notification-routing.ts by node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs. Ledger: S8.7. Do not edit by hand.

Summary#

  • src/notification-routing.ts
Entry point Runtime class Authorized by
@oshun/workbench-kit/notification-routing contract S8.7

Exports#

Symbol Kind Summary
ACKNOWLEDGEMENT_SOURCES enumeration How the recipient said they had seen it.
AcknowledgementSource type —
ACTOR_SLOT_NAMES enumeration Slot names that name the actor behind an event.
ACTORLESS_AUTHORITIES enumeration The authorities whose transitions have no actor and must not carry one.
applyTiming function Decide when a notice goes out (S8.7.f).
AUDIENCE_GROUNDS enumeration The reasons a person is on the list for an event.
AudienceCandidate interface One reason one person is on the list, as the host resolved it.
AudienceGround type —
AudienceRequest interface Everything resolution needs that is a property of the EVENT, not the person.
authorityRank function —
bypassFaults function Check the bypass threshold itself against the taxonomy and the floor.
capUsage function How much of a cap is spent at a given moment. Counts deliveries only.
CHANNEL_EXPOSURES enumeration How far a transport carries what it is given, least exposing first.
CHANNEL_READINESS enumeration Why a channel is or is not usable for one person right now.
CHANNEL_ROUTING_FAULTS enumeration —
ChannelBinding interface —
channelBindingFaults function Check the bindings themselves, independently of any one routing decision.
ChannelExposure type —
ChannelReadiness type —
ChannelRequest interface —
ChannelRoutingFault type —
comparePrecedence function Order two matching settings. Authority first, then specificity (decision 5).
composePreference function Compose every applicable preference into one decision (S8.7.c).
CONSENT_GATED_EXPOSURES enumeration The exposures a person must have explicitly agreed to.
DELIVERY_LIFECYCLE_FAULTS enumeration —
DELIVERY_OBLIGATIONS enumeration How strongly the platform is obliged to deliver.
DELIVERY_STATES enumeration —
DELIVERY_TRANSITIONS constant The machine, as data.
DeliveryEvent interface —
deliveryKey function The key that makes two deliveries the same delivery.
DeliveryLifecycleFault type —
DeliveryObligation type —
DeliveryState type —
deliveryTransition function —
DeliveryTransition interface —
DEPLOYMENT_ONLY_SCOPES enumeration The scopes only a deployment may author.
DERIVED_GROUNDS enumeration The grounds whose membership was DERIVED and must therefore be pinned.
DIGESTABLE_OBLIGATIONS enumeration The obligations a digest may hold. Decision 7's boundary, as data.
DISPOSITIONS_THAT_STOP_A_NOTICE enumeration The dispositions under which no notice is produced at all.
EVENT_REGISTRY_FAULTS enumeration —
EVENT_SOURCES enumeration Where an event comes from, which decides what can be trusted about it.
EventRegistration interface One registered event kind.
EventRegistryFault type —
eventRegistryFaults function Check one deployment's event registry (S8.7.a).
EventSource type —
EXPOSURE_CEILING constant The most exposing transport a class of value may travel on.
exposurePermits function Whether a field's value may travel at this exposure.
exposureRank function —
fieldsForExposure function Re-render one notice's fields for a transport (decision 9).
fieldsForNotice function The fields as they must reach the renderer, for this transport and reader.
foldGrounds function Fold every ground that reached one person into one recipient (decision 2).
FrequencyCap interface A ceiling on how often a person may be INTERRUPTED on one channel.
GROUND_OBLIGATION_FLOOR constant The obligation a ground carries on its own, whatever the event says.
GROUND_RESOLUTION_DEPENDS_ON constant What each ground's resolution is a function of.
GROUNDS_OUTSIDE_THE_AUDIENCE enumeration The one ground that reaches outside the object's audience (decision 4).
InterruptionLedger interface What actually happened on a channel, kept apart from what was prevented.
isDerivedGround function —
isTerminalDelivery function —
isUsable function Whether a binding can carry a notice to this person at this moment.
LifecycleContext interface —
lifecycleFaults function Check one transition against the machine (S8.7.g).
NON_ACKNOWLEDGING_SOURCES enumeration The sources that are not an acknowledgement.
NotificationRoutingFault type —
obligationRank function —
PlannedDelivery interface One decided delivery: exactly the argument the delivery system demands.
planNotifications function Turn one event into the deliveries it produces.
PlanRequest interface —
PREFERENCE_AUTHORITIES enumeration WHO set a preference, strongest first.
PREFERENCE_COMPOSITION_FAULTS enumeration —
PREFERENCE_DECISIONS enumeration What a composed preference decides.
PREFERENCE_SCOPES enumeration HOW SPECIFIC a preference is, most specific first. The second axis.
PreferenceAuthority type —
PreferenceCompositionFault type —
PreferenceContext interface What the event and recipient are, for matching a setting's scope.
PreferenceDecision type —
PreferenceOutcome interface —
preferenceParityFaults function Check a decision a host says it composed, against the settings it had.
PreferenceScope type —
PreferenceSetting interface —
quietHoursRelease function The instant a hold placed at at is released (decision 6's second half).
quietHoursSpanMinutes function How long a hold entered at at actually lasts, in minutes.
QuietHoursWindow interface When somebody does not want to be interrupted.
RECIPIENT_FAULTS enumeration —
RECIPIENT_SIDE_READINESS enumeration The readiness values that are facts about the person rather than the build.
RecipientProfile interface Everything about one recipient that is a property of THEM, not of the event.
RecipientResolutionFault type —
RenderedNotice interface What a host says it rendered and is about to hand to the delivery system.
RenderRequest interface —
rendersClassesOnly function Whether this recipient gets classes rather than values, whatever the fields say.
RESOLUTION_PARITY_FAULTS enumeration Compare the kit's derivation with the audience a host says it resolved.
ResolutionParityFault type —
resolutionParityFaults function —
ResolvedRecipient interface One person, every reason they are on the list, and the strongest of them.
resolveRecipients function Turn one event's candidates into the people it will be delivered to (S8.7.b).
routeChannel function Walk the fallback chain and choose a transport (S8.7.e).
RoutingFinding interface —
scopeRank function —
settingMatches function Whether one setting applies to this event, recipient and channel.
SILENCEABLE_OBLIGATIONS enumeration What a preference may do to an obligation.
strongerObligation function The stronger of two obligations. Decision 2's fold, as one function.
TEMPLATE_FAULTS enumeration —
TemplateFault type —
templateFaults function Check one rendered notice (S8.7.d).
templateSlots function The slot names a template actually contains, in order of first appearance.
TERMINAL_DELIVERY_STATES enumeration —
TimeOfDay interface A time of day, with no date and no zone. The two are separate on purpose.
TIMING_DISPOSITIONS enumeration —
TIMING_FAULTS enumeration —
TimingDisposition type —
TimingFault type —
TimingRequest interface —
TRANSITION_AUTHORITIES enumeration Who causes a transition, which is the whole of decision 12.
TransitionAuthority type —
windowWraps function Whether a window crosses midnight.
withheldFields function Fields whose values are withheld from this render, for whatever reason.
withinQuietHours function Whether an instant falls inside the window, in the window's own zone.

Shapes#

ACKNOWLEDGEMENT_SOURCES#

How the recipient said they had seen it.

Values: acted-on-the-notice, marked-read, opened-the-centre

AcknowledgementSource#

ts
(typeof ACKNOWLEDGEMENT_SOURCES)[number];

ACTOR_SLOT_NAMES#

Slot names that name the actor behind an event.

Values: actor, author, by, who, triggeredBy

ACTORLESS_AUTHORITIES#

The authorities whose transitions have no actor and must not carry one.

Values: the-clock

applyTiming#

Decide when a notice goes out (S8.7.f).

ts
applyTiming(request: TimingRequest): { readonly disposition: TimingDisposition; readonly releaseAt: Instant | null; readonly findings: readonly RoutingFinding[]; }

AUDIENCE_GROUNDS#

The reasons a person is on the list for an event.

Values: explicit, assignee, reviewer, owner, mention, role, team, escalation, delegate

AudienceCandidate#

One reason one person is on the list, as the host resolved it.

Field Type Required Notes
actorId ActorId required —
tenant TenantId required —
ground AudienceGround required —
derivedAt Instant | null — Instant required When the membership behind this ground was derived.
grant string | null required The grant behind a delegate ground, as ActorRef's delegated variant carries.
standing IdentityStanding required —
targetDisposition AuthorizationDisposition required What authorization.ts returned for THIS person against the event's target.
locale string required —
zone string required An IANA zone name. The recipient's, never the sender's.

AudienceGround#

ts
(typeof AUDIENCE_GROUNDS)[number];

AudienceRequest#

Everything resolution needs that is a property of the EVENT, not the person.

Field Type Required Notes
eventKind string required —
registration EventRegistration required —
tenant TenantId required —
occurredAt Instant required —
actor ActorRef | null — ActorRef required The actor behind the event. Null for a scheduled one, which has none.
candidates readonly AudienceCandidate[] — AudienceCandidate required —
maxFanOut number required The largest audience a single event may produce, as the deployment sets it.
escalationResolvedAt Instant | null — Instant required When escalation was resolved, for an event that has that ground.

authorityRank#

ts
authorityRank(authority: PreferenceAuthority): number

bypassFaults#

Check the bypass threshold itself against the taxonomy and the floor.

ts
bypassFaults(bypassThreshold: string, mandatoryUrgencies: readonly string[], taxonomy: NotificationTaxonomy): readonly RoutingFinding[]

capUsage#

How much of a cap is spent at a given moment. Counts deliveries only.

ts
capUsage(cap: FrequencyCap, ledger: InterruptionLedger, at: Instant): { readonly used: number; readonly remaining: number; readonly exhausted: boolean }

CHANNEL_EXPOSURES#

How far a transport carries what it is given, least exposing first.

Values: in-product, account-mailbox, device-surface, carrier-plaintext, third-party-endpoint

CHANNEL_READINESS#

Why a channel is or is not usable for one person right now.

Values: ready, not-configured, degraded, unavailable, no-address, no-consent, unverified-address

CHANNEL_ROUTING_FAULTS#

Values: channel-outside-the-taxonomy, channel-the-delivery-system-cannot-reach, readiness-that-contradicts-the-binding, consent-inferred-from-holding-an-address, delivery-to-an-unverified-address, fallback-that-increases-exposure, fallback-behind-the-same-provider, fallback-chain-that-does-not-terminate, fallback-to-a-channel-that-is-not-bound, in-product-channel-offered-a-fallback, obliged-delivery-with-no-reachable-channel, recipient-with-no-delivery-profile, suspended-recipient-routed-outside-the-product

ChannelBinding#

Field Type Required Notes
channel string required —
exposure ChannelExposure required —
readiness ChannelReadiness required —
hasAddress boolean required Whether the platform holds an address, token or endpoint for this person.
consentGiven boolean required Whether the person agreed to be reached this way. Holding an address is not agreement.
addressVerified boolean required Whether the address has been proven to be theirs.
provider string required The provider the channel is bound to, for the shared-failure check.
fallback string | null required The channel to try when this one cannot be used, or null for a terminus.

channelBindingFaults#

Check the bindings themselves, independently of any one routing decision.

ts
channelBindingFaults(bindings: readonly ChannelBinding[], taxonomy: NotificationTaxonomy): readonly RoutingFinding[]

ChannelExposure#

ts
(typeof CHANNEL_EXPOSURES)[number];

ChannelReadiness#

ts
(typeof CHANNEL_READINESS)[number];

ChannelRequest#

Field Type Required Notes
subject string required —
preferred string required —
bindings readonly ChannelBinding[] — ChannelBinding required —
obligation DeliveryObligation required —
recipientStanding IdentityStanding required The recipient's standing, which bounds the transports before anything else.

ChannelRoutingFault#

ts
(typeof CHANNEL_ROUTING_FAULTS)[number];

comparePrecedence#

Order two matching settings. Authority first, then specificity (decision 5).

ts
comparePrecedence(a: PreferenceSetting, b: PreferenceSetting): number

composePreference#

Compose every applicable preference into one decision (S8.7.c).

ts
composePreference(settings: readonly PreferenceSetting[], context: PreferenceContext, taxonomy: NotificationTaxonomy): { readonly outcome: PreferenceOutcome; readonly findings: readonly RoutingFinding[] }

The exposures a person must have explicitly agreed to.

Values: carrier-plaintext, third-party-endpoint

DELIVERY_LIFECYCLE_FAULTS#

Values: transition-that-is-not-in-the-machine, departure-from-a-terminal-state, transition-with-no-actor, clock-driven-transition-carrying-an-actor, transition-with-no-reason, acknowledgement-inferred-from-opening-the-centre, acknowledgement-by-somebody-who-is-not-the-recipient, sent-with-no-provider-receipt, provider-transition-with-no-provider-receipt, permanent-bounce-retried, permanent-bounce-that-did-not-unverify-the-address, retry-under-a-new-key, retry-past-the-attempt-bound, deduped-against-nothing, deduped-against-its-own-key, transition-before-the-notice-was-planned

DELIVERY_OBLIGATIONS#

How strongly the platform is obliged to deliver.

Values: mandatory, required, optional

DELIVERY_STATES#

Values: planned, sent, delivered, failed, bounced, suppressed, deduped, expired, acknowledged

DELIVERY_TRANSITIONS#

The machine, as data.

DeliveryEvent#

Field Type Required Notes
key string required —
from DeliveryState required —
to DeliveryState required —
at Instant required —
actor ActorRef | null — ActorRef required Null wherever the authority has none, and required wherever it has one.
reason string | null required —
providerReceipt string | null required What the provider actually answered. Evidence for a provider transition.
againstKey string | null required For deduped, the key this one deduplicated against.
bounceIsPermanent boolean required For a bounce: whether it is permanent, and whether the address was un-verified.
addressUnverified boolean required —
acknowledgementSource AcknowledgementSource | null — AcknowledgementSource required —
attempt number required How many times this key has been sent, including this one.

deliveryKey#

The key that makes two deliveries the same delivery.

ts
deliveryKey(eventId: string, recipient: ActorId, channel: string): string

DeliveryLifecycleFault#

ts
(typeof DELIVERY_LIFECYCLE_FAULTS)[number];

DeliveryObligation#

ts
(typeof DELIVERY_OBLIGATIONS)[number];

DeliveryState#

ts
(typeof DELIVERY_STATES)[number];

deliveryTransition#

ts
deliveryTransition(from: DeliveryState, to: DeliveryState): DeliveryTransition | null

DeliveryTransition#

Field Type Required Notes
from DeliveryState required —
to DeliveryState required —
authority TransitionAuthority required —
requiresReason boolean required —

DEPLOYMENT_ONLY_SCOPES#

The scopes only a deployment may author.

Values: role

DERIVED_GROUNDS#

The grounds whose membership was DERIVED and must therefore be pinned.

Values: assignee, reviewer, owner, role, team, escalation, delegate

DIGESTABLE_OBLIGATIONS#

The obligations a digest may hold. Decision 7's boundary, as data.

Values: optional

DISPOSITIONS_THAT_STOP_A_NOTICE#

The dispositions under which no notice is produced at all.

Values: conceal, deny, unavailable

EVENT_REGISTRY_FAULTS#

Values: event-with-no-source, event-with-no-audience-ground, event-urgency-outside-the-taxonomy, event-category-outside-the-taxonomy, event-with-no-expiry, template-slot-with-no-declared-field, declared-field-that-the-template-never-uses, dedupe-key-that-is-not-a-function-of-the-event, dedupe-key-over-fields-the-event-does-not-declare, mandatory-event-that-is-digest-eligible, never-collapsed-kind-that-is-digest-eligible, escalation-ground-with-no-silence-window, silence-window-on-an-event-that-never-escalates, escalation-window-past-the-events-own-expiry, scheduled-event-whose-template-names-an-actor, sensitive-event-whose-template-prints-its-subject

EVENT_SOURCES#

Where an event comes from, which decides what can be trusted about it.

Values: authored, derived, scheduled

EventRegistration#

One registered event kind.

Field Type Required Notes
kind string required —
source EventSource required —
category string required —
audienceGrounds readonly AudienceGround[] — AudienceGround required The grounds this event's audience may be drawn from.
defaultUrgency string required —
obligation DeliveryObligation required —
sensitivity SensitivityClass | null — SensitivityClass required The strongest class any field of this event's template may carry.
summaryTemplate string required —
templateFields readonly string[] required The names of the fields the template's slots are filled from.
dedupeKeyFields readonly string[] required What makes two of these the same notice.
expiryMinutes number | null required How long the notice stays worth sending. Null is refused.
digestEligible boolean required —
escalationAfterMinutes number | null required How long an event may go unanswered before escalation resolves.

EventRegistryFault#

ts
(typeof EVENT_REGISTRY_FAULTS)[number];

eventRegistryFaults#

Check one deployment's event registry (S8.7.a).

ts
eventRegistryFaults(registry: readonly EventRegistration[], taxonomy: NotificationTaxonomy): readonly RoutingFinding[]

EventSource#

ts
(typeof EVENT_SOURCES)[number];

EXPOSURE_CEILING#

The most exposing transport a class of value may travel on.

exposurePermits#

Whether a field's value may travel at this exposure.

ts
exposurePermits(field: SummaryField, exposure: ChannelExposure): boolean

exposureRank#

ts
exposureRank(exposure: ChannelExposure): number

fieldsForExposure#

Re-render one notice's fields for a transport (decision 9).

ts
fieldsForExposure(fields: readonly SummaryField[], exposure: ChannelExposure): readonly SummaryField[]

fieldsForNotice#

The fields as they must reach the renderer, for this transport and reader.

ts
fieldsForNotice(fields: readonly SummaryField[], exposure: ChannelExposure, classOnly: boolean): readonly SummaryField[]

foldGrounds#

Fold every ground that reached one person into one recipient (decision 2).

ts
foldGrounds(candidates: readonly AudienceCandidate[], eventObligation: DeliveryObligation): ResolvedRecipient | null

FrequencyCap#

A ceiling on how often a person may be INTERRUPTED on one channel.

Field Type Required Notes
channel string required —
windowMinutes number required —
maxInterruptions number required —

GROUND_OBLIGATION_FLOOR#

The obligation a ground carries on its own, whatever the event says.

GROUND_RESOLUTION_DEPENDS_ON#

What each ground's resolution is a function of.

GROUNDS_OUTSIDE_THE_AUDIENCE#

The one ground that reaches outside the object's audience (decision 4).

Values: escalation

InterruptionLedger#

What actually happened on a channel, kept apart from what was prevented.

Field Type Required Notes
delivered readonly Instant[] — Instant required —
suppressedByTheCap readonly Instant[] — Instant required —

isDerivedGround#

ts
isDerivedGround(ground: AudienceGround): boolean

isTerminalDelivery#

ts
isTerminalDelivery(state: DeliveryState): boolean

isUsable#

Whether a binding can carry a notice to this person at this moment.

ts
isUsable(binding: ChannelBinding): boolean

LifecycleContext#

Field Type Required Notes
eventId string required —
recipient ActorId required —
channel string required —
maxAttempts number required —
addressPreviouslyBounced boolean required Whether the address was permanently bounced before this event.
plannedAt Instant required When the delivery entered planned. Nothing about it precedes this.

lifecycleFaults#

Check one transition against the machine (S8.7.g).

ts
lifecycleFaults(event: DeliveryEvent, context: LifecycleContext): readonly RoutingFinding[]

NON_ACKNOWLEDGING_SOURCES#

The sources that are not an acknowledgement.

Values: opened-the-centre

NotificationRoutingFault#

ts
| EventRegistryFault
| RecipientResolutionFault
| ResolutionParityFault
| PreferenceCompositionFault
| TemplateFault
| ChannelRoutingFault
| TimingFault
| DeliveryLifecycleFault

obligationRank#

ts
obligationRank(obligation: DeliveryObligation): number

PlannedDelivery#

One decided delivery: exactly the argument the delivery system demands.

Field Type Required Notes
key string required —
eventId string required —
eventKind string required —
recipient ActorId required —
tenant TenantId required —
grounds readonly AudienceGround[] — AudienceGround required —
obligation DeliveryObligation required —
channel string required —
exposure ChannelExposure required —
category string required —
urgency string required —
locale string required —
zone string required —
classOnly boolean required True where the notice must be composed from classes rather than values.
timing TimingDisposition required —
releaseAt Instant | null — Instant required —
state DeliveryState required —

planNotifications#

Turn one event into the deliveries it produces.

ts
planNotifications(request: PlanRequest): { readonly plan: readonly PlannedDelivery[]; readonly findings: readonly RoutingFinding[]; }

PlanRequest#

Field Type Required Notes
eventId string required —
registration EventRegistration required —
audience AudienceRequest required —
profiles readonly RecipientProfile[] — RecipientProfile required —
project string required —
domain string required —
now Instant required —
bypassThreshold string required —
ambiguityPolicy AmbiguityPolicy required —
taxonomy NotificationTaxonomy required —

PREFERENCE_AUTHORITIES#

WHO set a preference, strongest first.

Values: platform-floor, the-person, the-deployment

PREFERENCE_COMPOSITION_FAULTS#

Values: mandatory-notice-silenced-by-a-preference, required-notice-muted-rather-than-moved, preference-for-a-channel-the-taxonomy-does-not-have, role-scoped-preference-authored-by-the-person, scoped-preference-with-no-scope-value, global-preference-carrying-a-scope-value, preference-threshold-outside-the-taxonomy, digest-choice-on-an-event-that-may-not-be-digested, deployment-default-overriding-the-person, more-specific-setting-lost-to-a-broader-one, absence-of-a-preference-treated-as-a-mute

PREFERENCE_DECISIONS#

What a composed preference decides.

Values: deliver, digest, mute

PREFERENCE_SCOPES#

HOW SPECIFIC a preference is, most specific first. The second axis.

Values: event-kind, category, project, domain, role, global

PreferenceAuthority#

ts
(typeof PREFERENCE_AUTHORITIES)[number];

PreferenceCompositionFault#

ts
(typeof PREFERENCE_COMPOSITION_FAULTS)[number];

PreferenceContext#

What the event and recipient are, for matching a setting's scope.

Field Type Required Notes
eventKind string required —
category string required —
project string required —
domain string required —
roles readonly string[] required —
urgency string required —
channel string required —
obligation DeliveryObligation required —

PreferenceDecision#

ts
(typeof PREFERENCE_DECISIONS)[number];

PreferenceOutcome#

Field Type Required Notes
decision PreferenceDecision required —
decidedBy PreferenceSetting | null — PreferenceSetting required The setting that decided, or null where the floor did.
considered readonly PreferenceSetting[] — PreferenceSetting required Every setting that matched, strongest first.

preferenceParityFaults#

Check a decision a host says it composed, against the settings it had.

ts
preferenceParityFaults(claimed: PreferenceDecision, settings: readonly PreferenceSetting[], context: PreferenceContext, taxonomy: NotificationTaxonomy): readonly RoutingFinding[]

PreferenceScope#

ts
(typeof PREFERENCE_SCOPES)[number];

PreferenceSetting#

Field Type Required Notes
authority PreferenceAuthority required —
scope PreferenceScope required —
scopeValue string | null required What the scope is bound to — the category, project, domain or role name.
channel string | null required The channel this applies to, or null for every channel.
decision PreferenceDecision required —
urgencyThreshold string | null required The weakest urgency this setting still lets through. Null to apply always.

quietHoursRelease#

The instant a hold placed at at is released (decision 6's second half).

ts
quietHoursRelease(window: QuietHoursWindow, at: Instant, policy: AmbiguityPolicy): { readonly instant: Instant; readonly resolution: ZoneResolution }

quietHoursSpanMinutes#

How long a hold entered at at actually lasts, in minutes.

ts
quietHoursSpanMinutes(window: QuietHoursWindow, at: Instant, policy: AmbiguityPolicy): number

QuietHoursWindow#

When somebody does not want to be interrupted.

Field Type Required Notes
start TimeOfDay required —
end TimeOfDay required —
zone string required An IANA zone name — the RECIPIENT's.
behaviour QuietHoursBehaviour required —

RECIPIENT_FAULTS#

Values: recipient-in-another-tenant, ground-the-event-does-not-declare, derived-ground-with-no-pinned-instant, pinning-instant-on-a-ground-that-derives-nothing, audience-pinned-before-the-event-happened, escalation-resolved-at-event-time, escalation-resolved-before-the-silence-window-elapsed, delegate-with-no-grant, grant-on-a-ground-that-is-not-a-delegation, recipient-notified-of-their-own-act, recipient-whose-identity-has-been-erased, recipient-who-has-departed, recipient-with-no-locale, recipient-in-a-zone-the-platform-does-not-know, fan-out-over-the-ceiling

RECIPIENT_SIDE_READINESS#

The readiness values that are facts about the person rather than the build.

Values: no-address, no-consent, unverified-address

RecipientProfile#

Everything about one recipient that is a property of THEM, not of the event.

Field Type Required Notes
actorId ActorId required —
roles readonly string[] required —
settings readonly PreferenceSetting[] — PreferenceSetting required —
bindings readonly ChannelBinding[] — ChannelBinding required —
preferredChannel string required —
quietHours QuietHoursWindow | null — QuietHoursWindow required —
cap FrequencyCap | null — FrequencyCap required —
ledger InterruptionLedger required —

RecipientResolutionFault#

ts
(typeof RECIPIENT_FAULTS)[number];

RenderedNotice#

What a host says it rendered and is about to hand to the delivery system.

Field Type Required Notes
locale string required —
zone string required —
exposure ChannelExposure required —
summary string required —
plainAlternative string required The plain alternative: an email's text part, or what a screen reader gets.
targetLabel string | null required —
targetLink string | null required —
occurredAtWall WallClock required The event's instant as this notice printed it.

RenderRequest#

Field Type Required Notes
registration EventRegistration required —
fields readonly SummaryField[] required —
recipient ResolvedRecipient required —
exposure ChannelExposure required —
occurredAt Instant required —
targetLabelDisposition AuthorizationDisposition required —
senderLocale string required —

rendersClassesOnly#

Whether this recipient gets classes rather than values, whatever the fields say.

ts
rendersClassesOnly(recipient: ResolvedRecipient): boolean

RESOLUTION_PARITY_FAULTS#

Compare the kit's derivation with the audience a host says it resolved.

Values: recipient-the-derivation-did-not-produce, recipient-the-host-dropped, obligation-weaker-than-the-grounds-support, grounds-the-host-discarded

ResolutionParityFault#

ts
(typeof RESOLUTION_PARITY_FAULTS)[number];

resolutionParityFaults#

ts
resolutionParityFaults(derived: readonly ResolvedRecipient[], claimed: readonly ResolvedRecipient[]): readonly RoutingFinding[]

ResolvedRecipient#

One person, every reason they are on the list, and the strongest of them.

Field Type Required Notes
actorId ActorId required —
tenant TenantId required —
grounds readonly AudienceGround[] — AudienceGround required Every ground that reached this person, sorted. Decision 2 keeps the set.
obligation DeliveryObligation required —
insideTheAudience boolean required Whether every ground that reached them is one that implies access.
targetDisposition AuthorizationDisposition required —
standing IdentityStanding required —
locale string required —
zone string required —

resolveRecipients#

Turn one event's candidates into the people it will be delivered to (S8.7.b).

ts
resolveRecipients(request: AudienceRequest): { readonly recipients: readonly ResolvedRecipient[]; readonly findings: readonly RoutingFinding[]; }

routeChannel#

Walk the fallback chain and choose a transport (S8.7.e).

ts
routeChannel(request: ChannelRequest): { readonly chosen: ChannelBinding | null; readonly attempted: readonly string[]; readonly findings: readonly RoutingFinding[]; }

RoutingFinding#

Field Type Required Notes
kind NotificationRoutingFault required —
subject string required The event, recipient, channel, window or delivery the finding is about.
detail string required —

scopeRank#

ts
scopeRank(scope: PreferenceScope): number

settingMatches#

Whether one setting applies to this event, recipient and channel.

ts
settingMatches(setting: PreferenceSetting, context: PreferenceContext): boolean

SILENCEABLE_OBLIGATIONS#

What a preference may do to an obligation.

Values: optional

strongerObligation#

The stronger of two obligations. Decision 2's fold, as one function.

ts
strongerObligation(a: DeliveryObligation, b: DeliveryObligation): DeliveryObligation

TEMPLATE_FAULTS#

Values: rendered-in-the-senders-locale, time-rendered-outside-the-recipients-zone, summary-not-produced-by-the-renderer, value-the-exposure-may-not-carry, presence-disclosing-field-in-a-notification, plain-alternative-carrying-a-withheld-value, target-named-under-a-label-refusal, denied-target-offered-as-a-link, link-carrying-a-withheld-value, escalation-notice-composed-from-values, notice-rendered-for-a-different-exposure

TemplateFault#

ts
(typeof TEMPLATE_FAULTS)[number];

templateFaults#

Check one rendered notice (S8.7.d).

ts
templateFaults(request: RenderRequest, notice: RenderedNotice): readonly RoutingFinding[]

templateSlots#

The slot names a template actually contains, in order of first appearance.

ts
templateSlots(template: string): readonly string[]

TERMINAL_DELIVERY_STATES#

Values: bounced, suppressed, deduped, expired, acknowledged

TimeOfDay#

A time of day, with no date and no zone. The two are separate on purpose.

Field Type Required Notes
hour number required —
minute number required —

TIMING_DISPOSITIONS#

Values: send-now, hold-until-release, defer-to-digest, expired

TIMING_FAULTS#

Values: quiet-window-evaluated-as-a-simple-range, quiet-hours-release-at-a-wall-clock-that-does-not-exist, quiet-hours-evaluated-outside-the-recipients-zone, quiet-hours-that-suppress-rather-than-delay, quiet-hours-applied-to-a-mandatory-notice, bypass-threshold-outside-the-taxonomy, bypass-that-does-not-reach-the-mandatory-kinds, cap-counted-over-suppressions, cap-applied-to-the-in-product-channel, capped-notice-dropped-rather-than-deferred, held-past-its-own-expiry, digest-eligibility-decided-without-the-urgency

TimingDisposition#

ts
(typeof TIMING_DISPOSITIONS)[number];

TimingFault#

ts
(typeof TIMING_FAULTS)[number];

TimingRequest#

Field Type Required Notes
subject string required —
now Instant required —
occurredAt Instant required —
registration EventRegistration required —
obligation DeliveryObligation required —
urgency string required —
exposure ChannelExposure required —
channel string required The channel being routed, so a cap bound to another one does not apply.
recipientZone string required The recipient's zone, to be checked against the window's.
quietHours QuietHoursWindow | null — QuietHoursWindow required —
hostSaysQuiet boolean | null required Whether the HOST believes this instant is inside the window, or null.
bypassThreshold string required Urgencies at least this strong ignore quiet hours.
cap FrequencyCap | null — FrequencyCap required —
ledger InterruptionLedger required —
ambiguityPolicy AmbiguityPolicy required —
taxonomy NotificationTaxonomy required —

TRANSITION_AUTHORITIES#

Who causes a transition, which is the whole of decision 12.

Values: the-platform, the-provider, the-recipient, the-clock

TransitionAuthority#

ts
(typeof TRANSITION_AUTHORITIES)[number];

windowWraps#

Whether a window crosses midnight.

ts
windowWraps(window: QuietHoursWindow): boolean

withheldFields#

Fields whose values are withheld from this render, for whatever reason.

ts
withheldFields(fields: readonly SummaryField[], exposure: ChannelExposure): readonly SummaryField[]

withinQuietHours#

Whether an instant falls inside the window, in the window's own zone.

ts
withinQuietHours(window: QuietHoursWindow, at: Instant): boolean

Valid examples#

No committed fixture corpus covers this page's accepted cases; they are unit-level and live in the module's own spec.

Invalid examples#

No committed fixture corpus covers this page's refused cases; they are unit-level and live in the module's own spec.

Authorization and scope#

| Symbol | Type | Notes | | ------------------------------ | ----------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | ACTOR_SLOT_NAMES | enumeration | Slot names that name the actor behind an event. | | ACTORLESS_AUTHORITIES | enumeration | The authorities whose transitions have no actor and must not carry one. | | AudienceCandidate.actorId | ActorId | — | | AudienceCandidate.grant | string | null | The grant behind a delegate ground, as ActorRef's delegated variant carries. | | AudienceCandidate.tenant | TenantId | — | | AudienceRequest.actor | ActorRef | null | The actor behind the event. Null for a scheduled one, which has none. | | AudienceRequest.tenant | TenantId | — | | ChannelBinding.consentGiven | boolean | Whether the person agreed to be reached this way. Holding an address is not agreement. | | CONSENT_GATED_EXPOSURES | enumeration | The exposures a person must have explicitly agreed to. | | DeliveryEvent.actor | ActorRef | null | Null wherever the authority has none, and required wherever it has one. | | DEPLOYMENT_ONLY_SCOPES | enumeration | The scopes only a deployment may author. | | PlannedDelivery.tenant | TenantId | — | | PREFERENCE_SCOPES | enumeration | HOW SPECIFIC a preference is, most specific first. The second axis. | | PreferenceScope | type | — | | PreferenceSetting.scope | PreferenceScope | — | | PreferenceSetting.scopeValue | string | null | What the scope is bound to — the category, project, domain or role name. | | RecipientProfile.actorId | ActorId | — | | ResolvedRecipient.actorId | ActorId | — | | ResolvedRecipient.tenant | TenantId | — | | scopeRank | function | — |

Idempotency and concurrency#

Symbol Type Notes
DeliveryEvent.attempt number How many times this key has been sent, including this one.
EventRegistration.dedupeKeyFields readonly string[] What makes two of these the same notice.
LifecycleContext.maxAttempts number —

Pagination#

Not applicable: nothing on this page returns a collection a caller reads in pages.

State and failure#

Symbol Type Notes
DELIVERY_STATES enumeration —
DeliveryState type —
PlannedDelivery.state DeliveryState —
TERMINAL_DELIVERY_STATES enumeration —

Compatibility#

Not applicable: nothing on this page is versioned independently of the package.

Deprecation#

Symbol Type Notes
DELIVERY_LIFECYCLE_FAULTS enumeration —
DeliveryLifecycleFault type —
lifecycleFaults function Check one transition against the machine (S8.7.g).

Evidence#

  • evidence/v1-workbenches/workbench-kit-export-map.json
  • libs/oshun/workbench-kit/src/notification-routing.ts