# Notification routing

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](#acknowledgement_sources)                 | enumeration | How the recipient said they had seen it.                                         |
| [AcknowledgementSource](#acknowledgementsource)                     | type        | —                                                                                |
| [ACTOR_SLOT_NAMES](#actor_slot_names)                               | enumeration | Slot names that name the actor behind an event.                                  |
| [ACTORLESS_AUTHORITIES](#actorless_authorities)                     | enumeration | The authorities whose transitions have no actor and must not carry one.          |
| [applyTiming](#applytiming)                                         | function    | Decide when a notice goes out (S8.7.f).                                          |
| [AUDIENCE_GROUNDS](#audience_grounds)                               | enumeration | The reasons a person is on the list for an event.                                |
| [AudienceCandidate](#audiencecandidate)                             | interface   | One reason one person is on the list, as the host resolved it.                   |
| [AudienceGround](#audienceground)                                   | type        | —                                                                                |
| [AudienceRequest](#audiencerequest)                                 | interface   | Everything resolution needs that is a property of the EVENT, not the person.     |
| [authorityRank](#authorityrank)                                     | function    | —                                                                                |
| [bypassFaults](#bypassfaults)                                       | function    | Check the bypass threshold itself against the taxonomy and the floor.            |
| [capUsage](#capusage)                                               | function    | How much of a cap is spent at a given moment. Counts deliveries only.            |
| [CHANNEL_EXPOSURES](#channel_exposures)                             | enumeration | How far a transport carries what it is given, least exposing first.              |
| [CHANNEL_READINESS](#channel_readiness)                             | enumeration | Why a channel is or is not usable for one person right now.                      |
| [CHANNEL_ROUTING_FAULTS](#channel_routing_faults)                   | enumeration | —                                                                                |
| [ChannelBinding](#channelbinding)                                   | interface   | —                                                                                |
| [channelBindingFaults](#channelbindingfaults)                       | function    | Check the bindings themselves, independently of any one routing decision.        |
| [ChannelExposure](#channelexposure)                                 | type        | —                                                                                |
| [ChannelReadiness](#channelreadiness)                               | type        | —                                                                                |
| [ChannelRequest](#channelrequest)                                   | interface   | —                                                                                |
| [ChannelRoutingFault](#channelroutingfault)                         | type        | —                                                                                |
| [comparePrecedence](#compareprecedence)                             | function    | Order two matching settings. Authority first, then specificity (decision 5).     |
| [composePreference](#composepreference)                             | function    | Compose every applicable preference into one decision (S8.7.c).                  |
| [CONSENT_GATED_EXPOSURES](#consent_gated_exposures)                 | enumeration | The exposures a person must have explicitly agreed to.                           |
| [DELIVERY_LIFECYCLE_FAULTS](#delivery_lifecycle_faults)             | enumeration | —                                                                                |
| [DELIVERY_OBLIGATIONS](#delivery_obligations)                       | enumeration | How strongly the platform is obliged to deliver.                                 |
| [DELIVERY_STATES](#delivery_states)                                 | enumeration | —                                                                                |
| [DELIVERY_TRANSITIONS](#delivery_transitions)                       | constant    | The machine, as data.                                                            |
| [DeliveryEvent](#deliveryevent)                                     | interface   | —                                                                                |
| [deliveryKey](#deliverykey)                                         | function    | The key that makes two deliveries the same delivery.                             |
| [DeliveryLifecycleFault](#deliverylifecyclefault)                   | type        | —                                                                                |
| [DeliveryObligation](#deliveryobligation)                           | type        | —                                                                                |
| [DeliveryState](#deliverystate)                                     | type        | —                                                                                |
| [deliveryTransition](#deliverytransition)                           | function    | —                                                                                |
| [DeliveryTransition](#deliverytransition)                           | interface   | —                                                                                |
| [DEPLOYMENT_ONLY_SCOPES](#deployment_only_scopes)                   | enumeration | The scopes only a deployment may author.                                         |
| [DERIVED_GROUNDS](#derived_grounds)                                 | enumeration | The grounds whose membership was DERIVED and must therefore be pinned.           |
| [DIGESTABLE_OBLIGATIONS](#digestable_obligations)                   | enumeration | The obligations a digest may hold. Decision 7's boundary, as data.               |
| [DISPOSITIONS_THAT_STOP_A_NOTICE](#dispositions_that_stop_a_notice) | enumeration | The dispositions under which no notice is produced at all.                       |
| [EVENT_REGISTRY_FAULTS](#event_registry_faults)                     | enumeration | —                                                                                |
| [EVENT_SOURCES](#event_sources)                                     | enumeration | Where an event comes from, which decides what can be trusted about it.           |
| [EventRegistration](#eventregistration)                             | interface   | One registered event kind.                                                       |
| [EventRegistryFault](#eventregistryfault)                           | type        | —                                                                                |
| [eventRegistryFaults](#eventregistryfaults)                         | function    | Check one deployment's event registry (S8.7.a).                                  |
| [EventSource](#eventsource)                                         | type        | —                                                                                |
| [EXPOSURE_CEILING](#exposure_ceiling)                               | constant    | The most exposing transport a class of value may travel on.                      |
| [exposurePermits](#exposurepermits)                                 | function    | Whether a field's value may travel at this exposure.                             |
| [exposureRank](#exposurerank)                                       | function    | —                                                                                |
| [fieldsForExposure](#fieldsforexposure)                             | function    | Re-render one notice's fields for a transport (decision 9).                      |
| [fieldsForNotice](#fieldsfornotice)                                 | function    | The fields as they must reach the renderer, for this transport and reader.       |
| [foldGrounds](#foldgrounds)                                         | function    | Fold every ground that reached one person into one recipient (decision 2).       |
| [FrequencyCap](#frequencycap)                                       | interface   | A ceiling on how often a person may be INTERRUPTED on one channel.               |
| [GROUND_OBLIGATION_FLOOR](#ground_obligation_floor)                 | constant    | The obligation a ground carries on its own, whatever the event says.             |
| [GROUND_RESOLUTION_DEPENDS_ON](#ground_resolution_depends_on)       | constant    | What each ground's resolution is a function of.                                  |
| [GROUNDS_OUTSIDE_THE_AUDIENCE](#grounds_outside_the_audience)       | enumeration | The one ground that reaches outside the object's audience (decision 4).          |
| [InterruptionLedger](#interruptionledger)                           | interface   | What actually happened on a channel, kept apart from what was prevented.         |
| [isDerivedGround](#isderivedground)                                 | function    | —                                                                                |
| [isTerminalDelivery](#isterminaldelivery)                           | function    | —                                                                                |
| [isUsable](#isusable)                                               | function    | Whether a binding can carry a notice to this person at this moment.              |
| [LifecycleContext](#lifecyclecontext)                               | interface   | —                                                                                |
| [lifecycleFaults](#lifecyclefaults)                                 | function    | Check one transition against the machine (S8.7.g).                               |
| [NON_ACKNOWLEDGING_SOURCES](#non_acknowledging_sources)             | enumeration | The sources that are not an acknowledgement.                                     |
| [NotificationRoutingFault](#notificationroutingfault)               | type        | —                                                                                |
| [obligationRank](#obligationrank)                                   | function    | —                                                                                |
| [PlannedDelivery](#planneddelivery)                                 | interface   | One decided delivery: exactly the argument the delivery system demands.          |
| [planNotifications](#plannotifications)                             | function    | Turn one event into the deliveries it produces.                                  |
| [PlanRequest](#planrequest)                                         | interface   | —                                                                                |
| [PREFERENCE_AUTHORITIES](#preference_authorities)                   | enumeration | WHO set a preference, strongest first.                                           |
| [PREFERENCE_COMPOSITION_FAULTS](#preference_composition_faults)     | enumeration | —                                                                                |
| [PREFERENCE_DECISIONS](#preference_decisions)                       | enumeration | What a composed preference decides.                                              |
| [PREFERENCE_SCOPES](#preference_scopes)                             | enumeration | HOW SPECIFIC a preference is, most specific first. The second axis.              |
| [PreferenceAuthority](#preferenceauthority)                         | type        | —                                                                                |
| [PreferenceCompositionFault](#preferencecompositionfault)           | type        | —                                                                                |
| [PreferenceContext](#preferencecontext)                             | interface   | What the event and recipient are, for matching a setting's scope.                |
| [PreferenceDecision](#preferencedecision)                           | type        | —                                                                                |
| [PreferenceOutcome](#preferenceoutcome)                             | interface   | —                                                                                |
| [preferenceParityFaults](#preferenceparityfaults)                   | function    | Check a decision a host says it composed, against the settings it had.           |
| [PreferenceScope](#preferencescope)                                 | type        | —                                                                                |
| [PreferenceSetting](#preferencesetting)                             | interface   | —                                                                                |
| [quietHoursRelease](#quiethoursrelease)                             | function    | The instant a hold placed at `at` is released (decision 6's second half).        |
| [quietHoursSpanMinutes](#quiethoursspanminutes)                     | function    | How long a hold entered at `at` actually lasts, in minutes.                      |
| [QuietHoursWindow](#quiethourswindow)                               | interface   | When somebody does not want to be interrupted.                                   |
| [RECIPIENT_FAULTS](#recipient_faults)                               | enumeration | —                                                                                |
| [RECIPIENT_SIDE_READINESS](#recipient_side_readiness)               | enumeration | The readiness values that are facts about the person rather than the build.      |
| [RecipientProfile](#recipientprofile)                               | interface   | Everything about one recipient that is a property of THEM, not of the event.     |
| [RecipientResolutionFault](#recipientresolutionfault)               | type        | —                                                                                |
| [RenderedNotice](#renderednotice)                                   | interface   | What a host says it rendered and is about to hand to the delivery system.        |
| [RenderRequest](#renderrequest)                                     | interface   | —                                                                                |
| [rendersClassesOnly](#rendersclassesonly)                           | function    | Whether this recipient gets classes rather than values, whatever the fields say. |
| [RESOLUTION_PARITY_FAULTS](#resolution_parity_faults)               | enumeration | Compare the kit's derivation with the audience a host says it resolved.          |
| [ResolutionParityFault](#resolutionparityfault)                     | type        | —                                                                                |
| [resolutionParityFaults](#resolutionparityfaults)                   | function    | —                                                                                |
| [ResolvedRecipient](#resolvedrecipient)                             | interface   | One person, every reason they are on the list, and the strongest of them.        |
| [resolveRecipients](#resolverecipients)                             | function    | Turn one event's candidates into the people it will be delivered to (S8.7.b).    |
| [routeChannel](#routechannel)                                       | function    | Walk the fallback chain and choose a transport (S8.7.e).                         |
| [RoutingFinding](#routingfinding)                                   | interface   | —                                                                                |
| [scopeRank](#scoperank)                                             | function    | —                                                                                |
| [settingMatches](#settingmatches)                                   | function    | Whether one setting applies to this event, recipient and channel.                |
| [SILENCEABLE_OBLIGATIONS](#silenceable_obligations)                 | enumeration | What a preference may do to an obligation.                                       |
| [strongerObligation](#strongerobligation)                           | function    | The stronger of two obligations. Decision 2's fold, as one function.             |
| [TEMPLATE_FAULTS](#template_faults)                                 | enumeration | —                                                                                |
| [TemplateFault](#templatefault)                                     | type        | —                                                                                |
| [templateFaults](#templatefaults)                                   | function    | Check one rendered notice (S8.7.d).                                              |
| [templateSlots](#templateslots)                                     | function    | The slot names a template actually contains, in order of first appearance.       |
| [TERMINAL_DELIVERY_STATES](#terminal_delivery_states)               | enumeration | —                                                                                |
| [TimeOfDay](#timeofday)                                             | interface   | A time of day, with no date and no zone. The two are separate on purpose.        |
| [TIMING_DISPOSITIONS](#timing_dispositions)                         | enumeration | —                                                                                |
| [TIMING_FAULTS](#timing_faults)                                     | enumeration | —                                                                                |
| [TimingDisposition](#timingdisposition)                             | type        | —                                                                                |
| [TimingFault](#timingfault)                                         | type        | —                                                                                |
| [TimingRequest](#timingrequest)                                     | interface   | —                                                                                |
| [TRANSITION_AUTHORITIES](#transition_authorities)                   | enumeration | Who causes a transition, which is the whole of decision 12.                      |
| [TransitionAuthority](#transitionauthority)                         | type        | —                                                                                |
| [windowWraps](#windowwraps)                                         | function    | Whether a window crosses midnight.                                               |
| [withheldFields](#withheldfields)                                   | function    | Fields whose values are withheld from this render, for whatever reason.          |
| [withinQuietHours](#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](./identity.md#actorid)                     | required | —                                                                                |
| `tenant`            | [TenantId](./identity.md#tenantid)                   | required | —                                                                                |
| `ground`            | [AudienceGround](#audienceground)                    | required | —                                                                                |
| `derivedAt`         | `Instant \| null` — [Instant](./identity.md#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](./mentions.md#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](#eventregistration)                                  | required | —                                                                           |
| `tenant`               | [TenantId](./identity.md#tenantid)                                       | required | —                                                                           |
| `occurredAt`           | [Instant](./identity.md#instant)                                         | required | —                                                                           |
| `actor`                | `ActorRef \| null` — [ActorRef](./identity.md#actorref)                  | required | The actor behind the event. Null for a `scheduled` one, which has none.     |
| `candidates`           | `readonly AudienceCandidate[]` — [AudienceCandidate](#audiencecandidate) | required | —                                                                           |
| `maxFanOut`            | `number`                                                                 | required | The largest audience a single event may produce, as the deployment sets it. |
| `escalationResolvedAt` | `Instant \| null` — [Instant](./identity.md#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](#channelexposure)   | required | —                                                                                      |
| `readiness`       | [ChannelReadiness](#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](#channelbinding) | required | —                                                                           |
| `obligation`        | [DeliveryObligation](#deliveryobligation)                       | required | —                                                                           |
| `recipientStanding` | [IdentityStanding](./mentions.md#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[] }
```

#### CONSENT_GATED_EXPOSURES

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](#deliverystate)                                                   | required | —                                                                               |
| `to`                    | [DeliveryState](#deliverystate)                                                   | required | —                                                                               |
| `at`                    | [Instant](./identity.md#instant)                                                  | required | —                                                                               |
| `actor`                 | `ActorRef \| null` — [ActorRef](./identity.md#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](#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](#deliverystate)             | required | —     |
| `to`             | [DeliveryState](#deliverystate)             | required | —     |
| `authority`      | [TransitionAuthority](#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](#eventsource)                                                   | required | —                                                                 |
| `category`               | `string`                                                                      | required | —                                                                 |
| `audienceGrounds`        | `readonly AudienceGround[]` — [AudienceGround](#audienceground)               | required | The grounds this event's audience may be drawn from.              |
| `defaultUrgency`         | `string`                                                                      | required | —                                                                 |
| `obligation`             | [DeliveryObligation](#deliveryobligation)                                     | required | —                                                                 |
| `sensitivity`            | `SensitivityClass \| null` — [SensitivityClass](./plugin.md#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](./identity.md#instant) | required | —     |
| `suppressedByTheCap` | `readonly Instant[]` — [Instant](./identity.md#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](./identity.md#actorid) | required | —                                                                    |
| `channel`                  | `string`                         | required | —                                                                    |
| `maxAttempts`              | `number`                         | required | —                                                                    |
| `addressPreviouslyBounced` | `boolean`                        | required | Whether the address was permanently bounced before this event.       |
| `plannedAt`                | [Instant](./identity.md#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](./identity.md#actorid)                                | required | —                                                                       |
| `tenant`     | [TenantId](./identity.md#tenantid)                              | required | —                                                                       |
| `grounds`    | `readonly AudienceGround[]` — [AudienceGround](#audienceground) | required | —                                                                       |
| `obligation` | [DeliveryObligation](#deliveryobligation)                       | required | —                                                                       |
| `channel`    | `string`                                                        | required | —                                                                       |
| `exposure`   | [ChannelExposure](#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](#timingdisposition)                         | required | —                                                                       |
| `releaseAt`  | `Instant \| null` — [Instant](./identity.md#instant)            | required | —                                                                       |
| `state`      | [DeliveryState](#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](#eventregistration)                               | required | —     |
| `audience`        | [AudienceRequest](#audiencerequest)                                   | required | —     |
| `profiles`        | `readonly RecipientProfile[]` — [RecipientProfile](#recipientprofile) | required | —     |
| `project`         | `string`                                                              | required | —     |
| `domain`          | `string`                                                              | required | —     |
| `now`             | [Instant](./identity.md#instant)                                      | required | —     |
| `bypassThreshold` | `string`                                                              | required | —     |
| `ambiguityPolicy` | [AmbiguityPolicy](./assignments.md#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](#deliveryobligation) | required | —     |

#### PreferenceDecision

```ts
(typeof PREFERENCE_DECISIONS)[number];
```

#### PreferenceOutcome

| Field        | Type                                                                     | Required | Notes                                                  |
| ------------ | ------------------------------------------------------------------------ | -------- | ------------------------------------------------------ |
| `decision`   | [PreferenceDecision](#preferencedecision)                                | required | —                                                      |
| `decidedBy`  | `PreferenceSetting \| null` — [PreferenceSetting](#preferencesetting)    | required | The setting that decided, or null where the floor did. |
| `considered` | `readonly PreferenceSetting[]` — [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](#preferenceauthority) | required | —                                                                          |
| `scope`            | [PreferenceScope](#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](#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](#timeofday) | required | —                                    |
| `end`       | [TimeOfDay](#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](./identity.md#actorid)                                         | required | —     |
| `roles`            | `readonly string[]`                                                      | required | —     |
| `settings`         | `readonly PreferenceSetting[]` — [PreferenceSetting](#preferencesetting) | required | —     |
| `bindings`         | `readonly ChannelBinding[]` — [ChannelBinding](#channelbinding)          | required | —     |
| `preferredChannel` | `string`                                                                 | required | —     |
| `quietHours`       | `QuietHoursWindow \| null` — [QuietHoursWindow](#quiethourswindow)       | required | —     |
| `cap`              | `FrequencyCap \| null` — [FrequencyCap](#frequencycap)                   | required | —     |
| `ledger`           | [InterruptionLedger](#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](#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](./assignments.md#wallclock) | required | The event's instant as this notice printed it.                             |

#### RenderRequest

| Field                    | Type                                    | Required | Notes |
| ------------------------ | --------------------------------------- | -------- | ----- |
| `registration`           | [EventRegistration](#eventregistration) | required | —     |
| `fields`                 | `readonly SummaryField[]`               | required | —     |
| `recipient`              | [ResolvedRecipient](#resolvedrecipient) | required | —     |
| `exposure`               | [ChannelExposure](#channelexposure)     | required | —     |
| `occurredAt`             | [Instant](./identity.md#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](./identity.md#actorid)                                | required | —                                                                        |
| `tenant`            | [TenantId](./identity.md#tenantid)                              | required | —                                                                        |
| `grounds`           | `readonly AudienceGround[]` — [AudienceGround](#audienceground) | required | Every ground that reached this person, sorted. Decision 2 keeps the set. |
| `obligation`        | [DeliveryObligation](#deliveryobligation)                       | required | —                                                                        |
| `insideTheAudience` | `boolean`                                                       | required | Whether every ground that reached them is one that implies access.       |
| `targetDisposition` | `AuthorizationDisposition`                                      | required | —                                                                        |
| `standing`          | [IdentityStanding](./mentions.md#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](#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](./identity.md#instant)                                   | required | —                                                                       |
| `occurredAt`      | [Instant](./identity.md#instant)                                   | required | —                                                                       |
| `registration`    | [EventRegistration](#eventregistration)                            | required | —                                                                       |
| `obligation`      | [DeliveryObligation](#deliveryobligation)                          | required | —                                                                       |
| `urgency`         | `string`                                                           | required | —                                                                       |
| `exposure`        | [ChannelExposure](#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](#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](#frequencycap)             | required | —                                                                       |
| `ledger`          | [InterruptionLedger](#interruptionledger)                          | required | —                                                                       |
| `ambiguityPolicy` | [AmbiguityPolicy](./assignments.md#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`
