# Digest coalescing and deduplication

What makes two notices the same notice and why the key that answers it must not
carry the event id, which of four relationships a pair of waiting notices is in
and why a mention may be deduplicated but never aggregated, why a daily digest
is twenty-three hours long one night a year and twenty-five another and starts
on a different day for every locale, what an aggregate may say about items its
reader was removed from while it waited, and why the thing that makes a digest
send exactly once is the window rather than what is inside it.

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

## Summary

- `src/notification-digests.ts`

| Entry point                                 | Runtime class | Authorized by |
| ------------------------------------------- | ------------- | ------------- |
| `@oshun/workbench-kit/notification-digests` | `contract`    | S8.8          |

## Exports

| Symbol                                                      | Kind        | Summary                                                                                         |
| ----------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
| [AdmissionRequest](#admissionrequest)                       | interface   | —                                                                                               |
| [admitToDigest](#admittodigest)                             | function    | Decide whether a planned delivery may enter a digest at all.                                    |
| [CAP_SCOPES](#cap_scopes)                                   | enumeration | —                                                                                               |
| [CapScope](#capscope)                                       | type        | —                                                                                               |
| [CHANNEL_SEND_OUTCOMES](#channel_send_outcomes)             | enumeration | —                                                                                               |
| [ChannelSendOutcome](#channelsendoutcome)                   | type        | —                                                                                               |
| [ChannelSendRecord](#channelsendrecord)                     | interface   | —                                                                                               |
| [CLASSIFICATION_FAULTS](#classification_faults)             | enumeration | —                                                                                               |
| [ClassificationFault](#classificationfault)                 | type        | —                                                                                               |
| [classifyPair](#classifypair)                               | function    | Decide how two waiting entries relate (S8.8.b).                                                 |
| [coalesceDigest](#coalescedigest)                           | function    | Fold a window's arrivals into what the recipient actually receives (S8.8).                      |
| [CoalesceOutcome](#coalesceoutcome)                         | interface   | —                                                                                               |
| [CoalesceRequest](#coalescerequest)                         | interface   | —                                                                                               |
| [composeDigestContent](#composedigestcontent)               | function    | Fold a window's members into what may be said about them (S8.8.d).                              |
| [CREDENTIAL_BEARING_PARAMS](#credential_bearing_params)     | enumeration | Query and fragment parameter names that carry a credential.                                     |
| [decideDigestSend](#decidedigestsend)                       | function    | Decide whether this window may be sent, and say what is wrong if it may not (S8.8.e).           |
| [DEDUPE_COMPONENTS](#dedupe_components)                     | enumeration | The seven things a dedupe identity is made of.                                                  |
| [DEDUPE_KEY_FAULTS](#dedupe_key_faults)                     | enumeration | —                                                                                               |
| [DedupeComponent](#dedupecomponent)                         | type        | —                                                                                               |
| [DedupeIdentity](#dedupeidentity)                           | interface   | One resolved dedupe identity: a value for each component.                                       |
| [dedupeIdentityComponents](#dedupeidentitycomponents)       | function    | The components of a key, read back out of it.                                                   |
| [dedupeIdentityKey](#dedupeidentitykey)                     | function    | The dedupe key for an identity.                                                                 |
| [dedupeIdentityOf](#dedupeidentityof)                       | function    | Build the dedupe identity for one instance (S8.8.a's other half).                               |
| [DedupeKeyFault](#dedupekeyfault)                           | type        | —                                                                                               |
| [dedupeKeyFaults](#dedupekeyfaults)                         | function    | Check a declared dedupe key against the event it claims to identify (S8.8.a).                   |
| [DedupeKeySpec](#dedupekeyspec)                             | interface   | One deployment's declared dedupe key, checked against the event registry.                       |
| [DIGEST_ADMISSION_FAULTS](#digest_admission_faults)         | enumeration | —                                                                                               |
| [DIGEST_ADMISSION_REFUSALS](#digest_admission_refusals)     | enumeration | Why a notice marked `defer-to-digest` is not admitted.                                          |
| [DIGEST_CADENCES](#digest_cadences)                         | enumeration | How often a digest goes out.                                                                    |
| [DIGEST_CAP_FAULTS](#digest_cap_faults)                     | enumeration | —                                                                                               |
| [DIGEST_CLAIM_FAULTS](#digest_claim_faults)                 | enumeration | —                                                                                               |
| [DIGEST_CONTENT_FAULTS](#digest_content_faults)             | enumeration | —                                                                                               |
| [DIGEST_RELATIONS](#digest_relations)                       | enumeration | —                                                                                               |
| [DIGEST_SCHEDULE_FAULTS](#digest_schedule_faults)           | enumeration | —                                                                                               |
| [DigestAdmissionFault](#digestadmissionfault)               | type        | —                                                                                               |
| [DigestAdmissionRefusal](#digestadmissionrefusal)           | type        | —                                                                                               |
| [DigestAudience](#digestaudience)                           | interface   | What the reader may see AT COMPOSITION TIME, which is not when they were added to the audience. |
| [DigestCadence](#digestcadence)                             | type        | —                                                                                               |
| [DigestCap](#digestcap)                                     | interface   | One ceiling, with BOTH of its numbers.                                                          |
| [DigestCapFault](#digestcapfault)                           | type        | —                                                                                               |
| [digestCapFaults](#digestcapfaults)                         | function    | Check a cap and the storm it was supposed to survive (S8.8.f).                                  |
| [DigestClaim](#digestclaim)                                 | interface   | —                                                                                               |
| [DigestClaimFault](#digestclaimfault)                       | type        | —                                                                                               |
| [DigestContent](#digestcontent)                             | interface   | The aggregate, as this module computes it.                                                      |
| [DigestContentFault](#digestcontentfault)                   | type        | —                                                                                               |
| [DigestContentRequest](#digestcontentrequest)               | interface   | —                                                                                               |
| [DigestEntry](#digestentry)                                 | interface   | One notice waiting in a digest.                                                                 |
| [DigestFinding](#digestfinding)                             | interface   | —                                                                                               |
| [digestIdempotencyKey](#digestidempotencykey)               | function    | The key that makes one digest send idempotent (decision 9).                                     |
| [DigestLink](#digestlink)                                   | interface   | —                                                                                               |
| [DigestRelation](#digestrelation)                           | type        | —                                                                                               |
| [DigestRendering](#digestrendering)                         | interface   | What the host actually rendered, so the content check has a second opinion.                     |
| [DigestSchedule](#digestschedule)                           | interface   | One recipient's digest schedule on one channel.                                                 |
| [DigestScheduleFault](#digestschedulefault)                 | type        | —                                                                                               |
| [DigestSendRequest](#digestsendrequest)                     | interface   | —                                                                                               |
| [DigestWindow](#digestwindow)                               | interface   | —                                                                                               |
| [ENTRY_OUTCOMES](#entry_outcomes)                           | enumeration | What happened to the thing an entry is about.                                                   |
| [EntryOutcome](#entryoutcome)                               | type        | —                                                                                               |
| [EventInstance](#eventinstance)                             | interface   | One arrived event, in exactly the terms a key is computed over.                                 |
| [HOST_SEND_INTENTS](#host_send_intents)                     | enumeration | What the host says it is about to do with this window.                                          |
| [HostSendIntent](#hostsendintent)                           | type        | —                                                                                               |
| [nextWindowClose](#nextwindowclose)                         | function    | The next instant this schedule's window closes, strictly after `at` (S8.8.c).                   |
| [NotificationDigestFault](#notificationdigestfault)         | type        | —                                                                                               |
| [OUTCOMES_A_DIGEST_MUST_NAME](#outcomes_a_digest_must_name) | enumeration | The outcomes a digest must name individually rather than count.                                 |
| [OVERFLOW_POLICIES](#overflow_policies)                     | enumeration | What happens to what a cap displaces.                                                           |
| [OverflowPolicy](#overflowpolicy)                           | type        | —                                                                                               |
| [RelationClaim](#relationclaim)                             | interface   | The host's own reading of a pair, so the check has something to disagree with.                  |
| [RelationVerdict](#relationverdict)                         | interface   | —                                                                                               |
| [scheduleFaults](#schedulefaults)                           | function    | Check one schedule against the notice it is about to hold (S8.8.c).                             |
| [ScheduleRequest](#schedulerequest)                         | interface   | —                                                                                               |
| [SEND_DECISIONS](#send_decisions)                           | enumeration | —                                                                                               |
| [SendDecision](#senddecision)                               | type        | —                                                                                               |
| [StormRequest](#stormrequest)                               | interface   | —                                                                                               |
| [WINDOW_STATES](#window_states)                             | enumeration | The states a window passes through.                                                             |
| [WindowClose](#windowclose)                                 | interface   | —                                                                                               |
| [windowSpanMinutes](#windowspanminutes)                     | function    | How long the interval ending at the next close actually is, in minutes.                         |
| [WindowState](#windowstate)                                 | type        | —                                                                                               |

## Shapes

#### AdmissionRequest

| Field                | Type                                                             | Required | Notes                                                     |
| -------------------- | ---------------------------------------------------------------- | -------- | --------------------------------------------------------- |
| `delivery`           | [PlannedDelivery](./notification-routing.md#planneddelivery)     | required | —                                                         |
| `registration`       | [EventRegistration](./notification-routing.md#eventregistration) | required | —                                                         |
| `schedule`           | [DigestSchedule](#digestschedule)                                | required | —                                                         |
| `occurredAt`         | [Instant](./identity.md#instant)                                 | required | —                                                         |
| `now`                | [Instant](./identity.md#instant)                                 | required | —                                                         |
| `taxonomy`           | `NotificationTaxonomy`                                           | required | —                                                         |
| `hostDropsOnRefusal` | `boolean`                                                        | required | True where the host discards a notice the digest refuses. |

#### admitToDigest

Decide whether a planned delivery may enter a digest at all.

```ts
admitToDigest(request: AdmissionRequest): { readonly admitted: boolean; readonly refusal: DigestAdmissionRefusal | null; readonly fallback: 'send-now' | 'drop' | null; readonly findings: readonly DigestFinding[]; }
```

#### CAP_SCOPES

Values: `recipient`, `event-type`, `channel`

#### CapScope

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

#### CHANNEL_SEND_OUTCOMES

Values: `not-attempted`, `sent`, `failed`

#### ChannelSendOutcome

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

#### ChannelSendRecord

| Field         | Type                                                 | Required | Notes |
| ------------- | ---------------------------------------------------- | -------- | ----- |
| `channel`     | `string`                                             | required | —     |
| `outcome`     | [ChannelSendOutcome](#channelsendoutcome)            | required | —     |
| `attemptedAt` | `Instant \| null` — [Instant](./identity.md#instant) | required | —     |

#### CLASSIFICATION_FAULTS

Values: `duplicate-suppressed-across-recipients`, `aggregation-across-tenants`,
`aggregation-across-channels`, `protected-kind-aggregated`,
`supersession-across-targets`, `supersession-across-families`,
`supersession-decided-by-arrival-order`,
`superseded-failure-erased-from-the-digest`,
`one-dedupe-key-over-two-different-bodies`,
`independent-events-treated-as-duplicates`,
`exact-duplicate-treated-as-a-new-notice`

#### ClassificationFault

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

#### classifyPair

Decide how two waiting entries relate (S8.8.b).

```ts
classifyPair(a: DigestEntry, b: DigestEntry, claim: RelationClaim | null): RelationVerdict
```

#### coalesceDigest

Fold a window's arrivals into what the recipient actually receives (S8.8).

```ts
coalesceDigest(request: CoalesceRequest): CoalesceOutcome
```

#### CoalesceOutcome

| Field               | Type                                                         | Required | Notes                                                                    |
| ------------------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------------------ |
| `individual`        | `readonly DigestEntry[]` — [DigestEntry](#digestentry)       | required | Notices that go out on their own, in the source of truth's order.        |
| `digests`           | `readonly (readonly string[])[]`                             | required | One list of member entry ids per digest that goes out.                   |
| `summarized`        | `readonly string[]`                                          | required | Members past the ceiling. Represented by a count, never discarded.       |
| `suppressed`        | `readonly string[]`                                          | required | Exact duplicates, and superseded entries a digest need not name.         |
| `content`           | [DigestContent](#digestcontent)                              | required | —                                                                        |
| `notificationCount` | `number`                                                     | required | What this recipient actually receives. The item's evidence, as a number. |
| `findings`          | `readonly DigestFinding[]` — [DigestFinding](#digestfinding) | required | —                                                                        |

#### CoalesceRequest

| Field      | Type                                                   | Required | Notes |
| ---------- | ------------------------------------------------------ | -------- | ----- |
| `subject`  | `string`                                               | required | —     |
| `entries`  | `readonly DigestEntry[]` — [DigestEntry](#digestentry) | required | —     |
| `cap`      | [DigestCap](#digestcap)                                | required | —     |
| `audience` | [DigestAudience](#digestaudience)                      | required | —     |
| `links`    | `readonly DigestLink[]` — [DigestLink](#digestlink)    | required | —     |
| `taxonomy` | `NotificationTaxonomy`                                 | required | —     |

#### composeDigestContent

Fold a window's members into what may be said about them (S8.8.d).

```ts
composeDigestContent(request: DigestContentRequest): { readonly content: DigestContent; readonly findings: readonly DigestFinding[]; }
```

#### CREDENTIAL_BEARING_PARAMS

Query and fragment parameter names that carry a credential.

Values: `token`, `access_token`, `auth`, `key`, `signature`, `sig`, `otp`,
`code`

#### decideDigestSend

Decide whether this window may be sent, and say what is wrong if it may not
(S8.8.e).

```ts
decideDigestSend(request: DigestSendRequest): { readonly decision: SendDecision; readonly findings: readonly DigestFinding[]; }
```

#### DEDUPE_COMPONENTS

The seven things a dedupe identity is made of.

Values: `recipient`, `event-family`, `target`, `transition`, `urgency`,
`channel`, `window`

#### DEDUPE_KEY_FAULTS

Values: `dedupe-key-without-the-recipient`,
`dedupe-key-without-the-event-family`, `dedupe-key-without-the-target`,
`dedupe-key-without-the-transition`, `dedupe-key-without-the-urgency`,
`dedupe-key-without-the-channel`, `dedupe-key-without-a-window`,
`dedupe-key-with-no-horizon`, `dedupe-key-over-the-rendered-summary`,
`dedupe-key-carrying-the-event-id`,
`dedupe-key-that-disagrees-with-the-registration`,
`dedupe-window-longer-than-the-notices-own-expiry`,
`dedupe-key-field-absent-from-the-event`, `dedupe-component-that-is-blank`,
`dedupe-key-built-from-another-events-registration`

#### DedupeComponent

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

#### DedupeIdentity

One resolved dedupe identity: a value for each component.

| Field        | Type                               | Required | Notes                                                             |
| ------------ | ---------------------------------- | -------- | ----------------------------------------------------------------- |
| `recipient`  | [ActorId](./identity.md#actorid)   | required | —                                                                 |
| `tenant`     | [TenantId](./identity.md#tenantid) | required | —                                                                 |
| `family`     | `string`                           | required | The level above kind at which a supersession can be expressed.    |
| `target`     | `string`                           | required | The object or scope the notice is about.                          |
| `transition` | `string`                           | required | `from>to`, or the empty string for an event with no state change. |
| `urgency`    | `string`                           | required | —                                                                 |
| `channel`    | `string`                           | required | —                                                                 |
| `windowId`   | `string`                           | required | The window this identity is scoped to. Decision 3's horizon.      |

#### dedupeIdentityComponents

The components of a key, read back out of it.

```ts
dedupeIdentityComponents(key: string): readonly string[]
```

#### dedupeIdentityKey

The dedupe key for an identity.

```ts
dedupeIdentityKey(identity: DedupeIdentity): string
```

#### dedupeIdentityOf

Build the dedupe identity for one instance (S8.8.a's other half).

```ts
dedupeIdentityOf(instance: EventInstance, registration: EventRegistration, delivery: { readonly recipient: ActorId; readonly tenant: TenantId; readonly channel: string; readonly urgency: string; }, windowId: string): { readonly identity: DedupeIdentity | null; readonly findings: readonly DigestFinding[] }
```

#### DedupeKeyFault

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

#### dedupeKeyFaults

Check a declared dedupe key against the event it claims to identify (S8.8.a).

```ts
dedupeKeyFaults(spec: DedupeKeySpec, registration: EventRegistration): readonly DigestFinding[]
```

#### DedupeKeySpec

One deployment's declared dedupe key, checked against the event registry.

| Field                 | Type                                                               | Required | Notes                                                                    |
| --------------------- | ------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------ |
| `eventKind`           | `string`                                                           | required | —                                                                        |
| `components`          | `readonly DedupeComponent[]` — [DedupeComponent](#dedupecomponent) | required | The components this deployment's key is built from.                      |
| `sourceFields`        | `readonly string[]`                                                | required | The event fields the `target` and `transition` components are read from. |
| `windowMinutes`       | `number \| null`                                                   | required | How long one key suppresses a repeat. Null is a key with no horizon.     |
| `overRenderedSummary` | `boolean`                                                          | required | True where the key is computed over the RENDERED summary.                |
| `carriesTheEventId`   | `boolean`                                                          | required | True where the key carries the event's own id.                           |

#### DIGEST_ADMISSION_FAULTS

Values: `defer-to-digest-on-a-notice-that-may-not-be-digested`,
`refused-notice-dropped-rather-than-sent`

#### DIGEST_ADMISSION_REFUSALS

Why a notice marked `defer-to-digest` is not admitted.

Values: `not-deferred-to-a-digest`, `obligation-above-optional`,
`registration-not-digest-eligible`, `kind-that-is-never-collapsed`,
`urgency-at-or-above-the-ceiling`, `in-product-channel`, `already-expired`

#### DIGEST_CADENCES

How often a digest goes out.

Values: `hourly`, `daily`, `weekly`

#### DIGEST_CAP_FAULTS

Values: `cap-without-an-item-ceiling`, `cap-without-a-digest-ceiling`,
`overflow-set-to-drop-at-the-bottom-of-the-ladder`,
`overflow-that-drops-a-notice-above-optional`,
`overflow-that-drops-a-protected-kind`,
`overflow-that-escalates-an-optional-notice`,
`mandatory-notice-inside-a-digest`, `summarized-remainder-that-states-no-count`,
`digest-cap-counted-over-items-rather-than-digests`,
`storm-that-produced-one-notification-per-event`,
`critical-event-lost-in-a-storm`, `cap-applied-to-something-it-is-not-scoped-to`

#### DIGEST_CLAIM_FAULTS

Values: `send-without-a-claim`, `send-from-a-window-that-has-not-closed`,
`concurrent-claims-on-one-window`, `claim-write-from-an-expired-lease`,
`claim-write-behind-the-fencing-token`,
`idempotency-key-computed-over-the-members`,
`idempotency-key-that-is-not-a-function-of-the-window`,
`reclaimed-window-that-mints-a-new-key`,
`late-arrival-added-to-a-claimed-window`,
`late-arrival-with-no-successor-window`, `retry-that-reopens-every-channel`,
`partial-failure-recorded-as-a-whole-failure`, `empty-digest-sent`,
`digest-of-one`, `window-abandoned-with-its-members-still-in-it`,
`window-claimed-before-it-closed`,
`send-by-a-worker-that-does-not-hold-the-claim`,
`member-that-occurred-before-the-window-opened`,
`channel-outcome-that-does-not-say-when`

#### DIGEST_CONTENT_FAULTS

Values: `aggregate-counted-an-item-the-recipient-may-no-longer-see`,
`hidden-item-disclosed-as-a-count`,
`link-to-an-object-the-recipient-may-not-open`,
`link-carrying-a-credential-into-an-exposed-channel`,
`actor-named-where-identity-is-protected`,
`class-only-digest-that-names-a-target`,
`digest-count-over-deliveries-rather-than-events`,
`digest-that-states-no-target-count`,
`digest-target-count-that-disagrees-with-its-members`,
`digest-count-that-disagrees-with-its-members`,
`digest-times-taken-from-arrival-rather-than-occurrence`,
`failure-folded-into-the-count`,
`member-addressed-to-somebody-other-than-the-digests-reader`,
`member-from-another-tenant-in-the-digest`,
`member-rendered-for-a-less-exposed-channel-than-the-digest`,
`class-only-member-folded-into-a-value-bearing-digest`,
`target-named-in-an-aggregate-whose-own-summary-withheld-it`,
`digest-rendered-below-its-strongest-member`

#### DIGEST_RELATIONS

Values: `exact-duplicate`, `supersedes`, `aggregateable`, `independent`

#### DIGEST_SCHEDULE_FAULTS

Values: `digest-schedule-in-an-unknown-zone`,
`weekly-digest-without-a-week-shape`,
`digest-window-computed-outside-the-recipients-zone`,
`digest-window-advanced-by-a-fixed-span`,
`digest-window-close-that-disagrees-with-the-recipients-clock`,
`digest-window-close-at-a-wall-clock-that-does-not-exist`,
`digest-window-close-at-a-repeated-wall-clock`,
`item-held-past-its-maximum-delay`, `digest-on-the-in-product-channel`,
`quiet-hours-hold-past-the-maximum-delay`,
`two-windows-due-at-the-same-instant`,
`urgency-at-or-above-the-ceiling-deferred-to-a-digest`,
`digest-ceiling-outside-the-taxonomy`,
`digest-cadence-longer-than-the-notices-own-expiry`

#### DigestAdmissionFault

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

#### DigestAdmissionRefusal

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

#### DigestAudience

What the reader may see AT COMPOSITION TIME, which is not when they were added
to the audience.

| Field                  | Type                                                         | Required | Notes                                                                     |
| ---------------------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------------------- |
| `recipient`            | [ActorId](./identity.md#actorid)                             | required | —                                                                         |
| `tenant`               | [TenantId](./identity.md#tenantid)                           | required | —                                                                         |
| `visibleTargets`       | `readonly string[]`                                          | required | Targets this reader may know the existence of, now.                       |
| `openableTargets`      | `readonly string[]`                                          | required | Targets this reader may open, now. Never assumed from the first list.     |
| `namedActorsPermitted` | `boolean`                                                    | required | Whether an actor may be named to this reader at all.                      |
| `classOnly`            | `boolean`                                                    | required | True where this reader gets classes rather than values (S8.7 decision 4). |
| `exposure`             | [ChannelExposure](./notification-routing.md#channelexposure) | required | —                                                                         |

#### DigestCadence

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

#### DigestCap

One ceiling, with BOTH of its numbers.

| Field               | Type                              | Required | Notes                                                                 |
| ------------------- | --------------------------------- | -------- | --------------------------------------------------------------------- |
| `scope`             | [CapScope](#capscope)             | required | —                                                                     |
| `key`               | `string`                          | required | —                                                                     |
| `windowMinutes`     | `number`                          | required | —                                                                     |
| `maxDigests`        | `number \| null`                  | required | How many digests may go out in the window. Null is no ceiling at all. |
| `maxItemsPerDigest` | `number \| null`                  | required | How many items one digest may carry. Null is no ceiling at all.       |
| `overflow`          | [OverflowPolicy](#overflowpolicy) | required | —                                                                     |

#### DigestCapFault

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

#### digestCapFaults

Check a cap and the storm it was supposed to survive (S8.8.f).

```ts
digestCapFaults(request: StormRequest): { readonly bound: number; readonly findings: readonly DigestFinding[]; }
```

#### DigestClaim

| Field            | Type                             | Required | Notes                                                                      |
| ---------------- | -------------------------------- | -------- | -------------------------------------------------------------------------- |
| `holder`         | `string`                         | required | —                                                                          |
| `claimedAt`      | [Instant](./identity.md#instant) | required | —                                                                          |
| `leaseExpiresAt` | [Instant](./identity.md#instant) | required | —                                                                          |
| `fencingToken`   | `number`                         | required | Monotonic from the store, so a resumed worker is behind rather than equal. |
| `idempotencyKey` | `string`                         | required | —                                                                          |

#### DigestClaimFault

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

#### DigestContent

The aggregate, as this module computes it.

| Field              | Type                                                                     | Required | Notes                                                                  |
| ------------------ | ------------------------------------------------------------------------ | -------- | ---------------------------------------------------------------------- |
| `eventCount`       | `number`                                                                 | required | —                                                                      |
| `targetCount`      | `number`                                                                 | required | —                                                                      |
| `actors`           | `readonly ActorId[]` — [ActorId](./identity.md#actorid)                  | required | —                                                                      |
| `targets`          | `readonly string[]`                                                      | required | —                                                                      |
| `outcomes`         | `Readonly<Record<EntryOutcome, number>>` — [EntryOutcome](#entryoutcome) | required | —                                                                      |
| `earliest`         | `Instant \| null` — [Instant](./identity.md#instant)                     | required | —                                                                      |
| `latest`           | `Instant \| null` — [Instant](./identity.md#instant)                     | required | —                                                                      |
| `failures`         | `readonly string[]`                                                      | required | Entry ids the digest must NAME rather than count.                      |
| `blockers`         | `readonly string[]`                                                      | required | —                                                                      |
| `links`            | `readonly DigestLink[]` — [DigestLink](#digestlink)                      | required | —                                                                      |
| `strongestUrgency` | `string \| null`                                                         | required | The strongest urgency any member carries, or null for an empty digest. |
| `withheld`         | `number`                                                                 | required | How many members this reader may no longer see.                        |

#### DigestContentFault

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

#### DigestContentRequest

| Field       | Type                                                            | Required | Notes                                                          |
| ----------- | --------------------------------------------------------------- | -------- | -------------------------------------------------------------- |
| `subject`   | `string`                                                        | required | —                                                              |
| `entries`   | `readonly DigestEntry[]` — [DigestEntry](#digestentry)          | required | —                                                              |
| `audience`  | [DigestAudience](#digestaudience)                               | required | —                                                              |
| `links`     | `readonly DigestLink[]` — [DigestLink](#digestlink)             | required | —                                                              |
| `taxonomy`  | `NotificationTaxonomy`                                          | required | —                                                              |
| `rendering` | `DigestRendering \| null` — [DigestRendering](#digestrendering) | required | What the host rendered, or null to ask only for the aggregate. |

#### DigestEntry

One notice waiting in a digest.

| Field                | Type                                                               | Required | Notes                                                                    |
| -------------------- | ------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------ |
| `entryId`            | `string`                                                           | required | —                                                                        |
| `eventId`            | `string`                                                           | required | —                                                                        |
| `eventKind`          | `string`                                                           | required | —                                                                        |
| `family`             | `string`                                                           | required | —                                                                        |
| `recipient`          | [ActorId](./identity.md#actorid)                                   | required | —                                                                        |
| `tenant`             | [TenantId](./identity.md#tenantid)                                 | required | —                                                                        |
| `target`             | `string`                                                           | required | —                                                                        |
| `transitionFrom`     | `string \| null`                                                   | required | —                                                                        |
| `transitionTo`       | `string \| null`                                                   | required | —                                                                        |
| `urgency`            | `string`                                                           | required | —                                                                        |
| `obligation`         | [DeliveryObligation](./notification-routing.md#deliveryobligation) | required | —                                                                        |
| `channel`            | `string`                                                           | required | —                                                                        |
| `exposure`           | [ChannelExposure](./notification-routing.md#channelexposure)       | required | —                                                                        |
| `outcome`            | [EntryOutcome](#entryoutcome)                                      | required | —                                                                        |
| `occurredAt`         | [Instant](./identity.md#instant)                                   | required | The instant the thing happened. The only instant that orders a digest.   |
| `sequence`           | `number`                                                           | required | The source of truth's per-target sequence. Decides supersession.         |
| `receivedAt`         | [Instant](./identity.md#instant)                                   | required | When this reached the accumulator.                                       |
| `contentFingerprint` | `string`                                                           | required | A hash of the rendered body, so two entries can be compared without it.  |
| `summaryFields`      | `readonly SummaryField[]`                                          | required | —                                                                        |
| `actor`              | `ActorId \| null` — [ActorId](./identity.md#actorid)               | required | —                                                                        |
| `classOnly`          | `boolean`                                                          | required | True where this notice must be composed from classes rather than values. |
| `dedupeKey`          | `string`                                                           | required | —                                                                        |

#### DigestFinding

| Field     | Type                                                | Required | Notes                                                       |
| --------- | --------------------------------------------------- | -------- | ----------------------------------------------------------- |
| `kind`    | [NotificationDigestFault](#notificationdigestfault) | required | —                                                           |
| `subject` | `string`                                            | required | The key, entry, window, digest or cap the finding is about. |
| `detail`  | `string`                                            | required | —                                                           |

#### digestIdempotencyKey

The key that makes one digest send idempotent (decision 9).

```ts
digestIdempotencyKey(tenant: TenantId, recipient: ActorId, channel: string, windowId: string): string
```

#### DigestLink

| Field    | Type     | Required | Notes |
| -------- | -------- | -------- | ----- |
| `target` | `string` | required | —     |
| `href`   | `string` | required | —     |

#### DigestRelation

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

#### DigestRendering

What the host actually rendered, so the content check has a second opinion.

| Field                   | Type                                                    | Required | Notes                                                |
| ----------------------- | ------------------------------------------------------- | -------- | ---------------------------------------------------- |
| `eventCountRendered`    | `number`                                                | required | —                                                    |
| `targetCountRendered`   | `number \| null`                                        | required | Null where the digest states no object count at all. |
| `actorsRendered`        | `readonly ActorId[]` — [ActorId](./identity.md#actorid) | required | —                                                    |
| `targetsRendered`       | `readonly string[]`                                     | required | —                                                    |
| `withheldCountRendered` | `number \| null`                                        | required | Non-null where the host renders a hidden remainder.  |
| `earliestRendered`      | `Instant \| null` — [Instant](./identity.md#instant)    | required | —                                                    |
| `latestRendered`        | `Instant \| null` — [Instant](./identity.md#instant)    | required | —                                                    |
| `failuresNamed`         | `readonly string[]`                                     | required | The entry ids the digest names individually.         |
| `urgencyRendered`       | `string \| null`                                        | required | The urgency the digest itself went out at.           |

#### DigestSchedule

One recipient's digest schedule on one channel.

| Field             | Type                                                                                        | Required | Notes                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------- |
| `recipient`       | [ActorId](./identity.md#actorid)                                                            | required | —                                                                         |
| `channel`         | `string`                                                                                    | required | —                                                                         |
| `exposure`        | [ChannelExposure](./notification-routing.md#channelexposure)                                | required | —                                                                         |
| `cadence`         | [DigestCadence](#digestcadence)                                                             | required | —                                                                         |
| `anchor`          | [TimeOfDay](./notification-routing.md#timeofday)                                            | required | The wall clock the window closes at. Only the minute is read when hourly. |
| `zone`            | `string`                                                                                    | required | An IANA zone name — the RECIPIENT's.                                      |
| `locale`          | `string`                                                                                    | required | Decides which day a week begins on. Read only by the weekly cadence.      |
| `ambiguityPolicy` | [AmbiguityPolicy](./assignments.md#ambiguitypolicy)                                         | required | —                                                                         |
| `maxDelayMinutes` | `number`                                                                                    | required | The longest an item may wait, however far away the next close is.         |
| `quietHours`      | `QuietHoursWindow \| null` — [QuietHoursWindow](./notification-routing.md#quiethourswindow) | required | —                                                                         |
| `urgencyCeiling`  | `string`                                                                                    | required | Urgencies at or above this are never digested at all.                     |

#### DigestScheduleFault

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

#### DigestSendRequest

| Field                      | Type                                                                     | Required | Notes                                                                        |
| -------------------------- | ------------------------------------------------------------------------ | -------- | ---------------------------------------------------------------------------- |
| `window`                   | [DigestWindow](#digestwindow)                                            | required | —                                                                            |
| `members`                  | `readonly DigestEntry[]` — [DigestEntry](#digestentry)                   | required | —                                                                            |
| `now`                      | [Instant](./identity.md#instant)                                         | required | —                                                                            |
| `holder`                   | `string`                                                                 | required | The worker asking, and the token the store gave it.                          |
| `fencingToken`             | `number`                                                                 | required | —                                                                            |
| `hostIdempotencyKey`       | `string`                                                                 | required | The key the HOST computed for this send.                                     |
| `hostKeyAfterALateArrival` | `string \| null`                                                         | required | The same host key, recomputed after one more member landed.                  |
| `previousClaim`            | `DigestClaim \| null` — [DigestClaim](#digestclaim)                      | required | The claim this window held on its previous attempt, if there was one.        |
| `lateArrivals`             | `readonly DigestEntry[]` — [DigestEntry](#digestentry)                   | required | Entries that arrived after the close.                                        |
| `channelOutcomes`          | `readonly ChannelSendRecord[]` — [ChannelSendRecord](#channelsendrecord) | required | —                                                                            |
| `retriesTheWholeWindow`    | `boolean`                                                                | required | True where a retry re-sends the whole window rather than the failed channel. |
| `concurrentClaims`         | `readonly DigestClaim[]` — [DigestClaim](#digestclaim)                   | required | —                                                                            |
| `hostIntent`               | [HostSendIntent](#hostsendintent)                                        | required | —                                                                            |

#### DigestWindow

| Field               | Type                                                | Required | Notes                                                               |
| ------------------- | --------------------------------------------------- | -------- | ------------------------------------------------------------------- |
| `windowId`          | `string`                                            | required | —                                                                   |
| `recipient`         | [ActorId](./identity.md#actorid)                    | required | —                                                                   |
| `tenant`            | [TenantId](./identity.md#tenantid)                  | required | —                                                                   |
| `channel`           | `string`                                            | required | —                                                                   |
| `opensAt`           | [Instant](./identity.md#instant)                    | required | —                                                                   |
| `closesAt`          | [Instant](./identity.md#instant)                    | required | —                                                                   |
| `state`             | [WindowState](#windowstate)                         | required | —                                                                   |
| `entryIds`          | `readonly string[]`                                 | required | —                                                                   |
| `claim`             | `DigestClaim \| null` — [DigestClaim](#digestclaim) | required | —                                                                   |
| `attempt`           | `number`                                            | required | Which attempt this is. A reclaim after a dead worker is the second. |
| `successorWindowId` | `string \| null`                                    | required | The window a late arrival belongs to.                               |

#### ENTRY_OUTCOMES

What happened to the thing an entry is about.

Values: `in-progress`, `succeeded`, `failed`, `blocked`

#### EntryOutcome

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

#### EventInstance

One arrived event, in exactly the terms a key is computed over.

| Field            | Type                               | Required | Notes |
| ---------------- | ---------------------------------- | -------- | ----- |
| `eventId`        | `string`                           | required | —     |
| `kind`           | `string`                           | required | —     |
| `family`         | `string`                           | required | —     |
| `fields`         | `Readonly<Record<string, string>>` | required | —     |
| `transitionFrom` | `string \| null`                   | required | —     |
| `transitionTo`   | `string \| null`                   | required | —     |

#### HOST_SEND_INTENTS

What the host says it is about to do with this window.

Values: `digest`, `single-notice`, `nothing`

#### HostSendIntent

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

#### nextWindowClose

The next instant this schedule's window closes, strictly after `at` (S8.8.c).

```ts
nextWindowClose(schedule: DigestSchedule, at: Instant): WindowClose
```

#### NotificationDigestFault

```ts
| DedupeKeyFault
| ClassificationFault
| DigestScheduleFault
| DigestContentFault
| DigestClaimFault
| DigestCapFault
| DigestAdmissionFault
```

#### OUTCOMES_A_DIGEST_MUST_NAME

The outcomes a digest must name individually rather than count.

Values: `failed`, `blocked`

#### OVERFLOW_POLICIES

What happens to what a cap displaces.

Values: `summarize`, `escalate`, `drop`

#### OverflowPolicy

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

#### RelationClaim

The host's own reading of a pair, so the check has something to disagree with.

| Field              | Type                              | Required | Notes                                                               |
| ------------------ | --------------------------------- | -------- | ------------------------------------------------------------------- |
| `relation`         | [DigestRelation](#digestrelation) | required | —                                                                   |
| `winner`           | `string \| null`                  | required | The entry the host says wins a supersession.                        |
| `decidedByArrival` | `boolean`                         | required | True where the host decided the winner by which one arrived first.  |
| `loserRetained`    | `boolean`                         | required | True where the host keeps the losing entry's outcome in the digest. |

#### RelationVerdict

| Field      | Type                                                         | Required | Notes                                                     |
| ---------- | ------------------------------------------------------------ | -------- | --------------------------------------------------------- |
| `relation` | [DigestRelation](#digestrelation)                            | required | —                                                         |
| `winner`   | `string \| null`                                             | required | For `supersedes`, the entry id that wins. Null otherwise. |
| `findings` | `readonly DigestFinding[]` — [DigestFinding](#digestfinding) | required | —                                                         |

#### scheduleFaults

Check one schedule against the notice it is about to hold (S8.8.c).

```ts
scheduleFaults(request: ScheduleRequest): { readonly closesAt: Instant | null; readonly releaseAt: Instant | null; readonly findings: readonly DigestFinding[]; }
```

#### ScheduleRequest

| Field              | Type                                                             | Required | Notes                                                                 |
| ------------------ | ---------------------------------------------------------------- | -------- | --------------------------------------------------------------------- |
| `subject`          | `string`                                                         | required | —                                                                     |
| `schedule`         | [DigestSchedule](#digestschedule)                                | required | —                                                                     |
| `now`              | [Instant](./identity.md#instant)                                 | required | —                                                                     |
| `previousClosedAt` | `Instant \| null` — [Instant](./identity.md#instant)             | required | The close before this one, so a fixed-span implementation is visible. |
| `oldestOccurredAt` | `Instant \| null` — [Instant](./identity.md#instant)             | required | The oldest item already waiting. Max delay is measured from it.       |
| `urgency`          | `string`                                                         | required | —                                                                     |
| `registration`     | [EventRegistration](./notification-routing.md#eventregistration) | required | —                                                                     |
| `hostClosesAt`     | `Instant \| null` — [Instant](./identity.md#instant)             | required | When the HOST believes this window closes, or null.                   |
| `hostZone`         | `string`                                                         | required | The zone the host computed in, which is not always the one it read.   |
| `taxonomy`         | `NotificationTaxonomy`                                           | required | —                                                                     |

#### SEND_DECISIONS

Values: `send-as-a-digest`, `send-as-a-single-notice`, `skip-empty`, `refuse`

#### SendDecision

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

#### StormRequest

| Field                         | Type                                                               | Required | Notes                                                          |
| ----------------------------- | ------------------------------------------------------------------ | -------- | -------------------------------------------------------------- |
| `subject`                     | `string`                                                           | required | —                                                              |
| `cap`                         | [DigestCap](#digestcap)                                            | required | —                                                              |
| `entries`                     | `readonly DigestEntry[]` — [DigestEntry](#digestentry)             | required | —                                                              |
| `channel`                     | `string`                                                           | required | —                                                              |
| `now`                         | [Instant](./identity.md#instant)                                   | required | —                                                              |
| `ledger`                      | [InterruptionLedger](./notification-routing.md#interruptionledger) | required | Digests actually delivered on this channel, for .              |
| `hostUsedAgainstTheDigestCap` | `number`                                                           | required | How much of the digest ceiling the host believes it has spent. |
| `hostNotificationCount`       | `number`                                                           | required | How many notifications the host produced for these entries.    |
| `hostIndividualEntryIds`      | `readonly string[]`                                                | required | The entries the host sent as notifications of their own.       |
| `overflowLineStatesTheCount`  | `boolean`                                                          | required | True where the overflow line says how many it stands for.      |

#### WINDOW_STATES

The states a window passes through.

Values: `open`, `closed`, `claimed`, `sent`, `failed`, `abandoned`

#### WindowClose

| Field        | Type                                                                         | Required | Notes                                              |
| ------------ | ---------------------------------------------------------------------------- | -------- | -------------------------------------------------- |
| `instant`    | `Instant \| null` — [Instant](./identity.md#instant)                         | required | Null where the schedule cannot be resolved at all. |
| `resolution` | `ZoneResolution \| null` — [ZoneResolution](./assignments.md#zoneresolution) | required | —                                                  |
| `findings`   | `readonly DigestFinding[]` — [DigestFinding](#digestfinding)                 | required | —                                                  |

#### windowSpanMinutes

How long the interval ending at the next close actually is, in minutes.

```ts
windowSpanMinutes(schedule: DigestSchedule, at: Instant): number | null
```

#### WindowState

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

## 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                                                |
| ------------------------------------- | -------------------- | ---------------------------------------------------- | --- |
| `CAP_SCOPES`                          | `enumeration`        | —                                                    |
| `CapScope`                            | `type`               | —                                                    |
| `DedupeIdentity.tenant`               | `TenantId`           | —                                                    |
| `DigestAudience.namedActorsPermitted` | `boolean`            | Whether an actor may be named to this reader at all. |
| `DigestAudience.tenant`               | `TenantId`           | —                                                    |
| `DigestCap.scope`                     | `CapScope`           | —                                                    |
| `DigestContent.actors`                | `readonly ActorId[]` | —                                                    |
| `DigestEntry.actor`                   | `ActorId             | null`                                                | —   |
| `DigestEntry.tenant`                  | `TenantId`           | —                                                    |
| `DigestRendering.actorsRendered`      | `readonly ActorId[]` | —                                                    |
| `DigestWindow.tenant`                 | `TenantId`           | —                                                    |

## Idempotency and concurrency

| Symbol                                 | Type                     | Notes                                                                         |
| -------------------------------------- | ------------------------ | ----------------------------------------------------------------------------- | --- |
| `ChannelSendRecord.attemptedAt`        | `Instant                 | null`                                                                         | —   |
| `DEDUPE_COMPONENTS`                    | `enumeration`            | The seven things a dedupe identity is made of.                                |
| `DEDUPE_KEY_FAULTS`                    | `enumeration`            | —                                                                             |
| `DedupeComponent`                      | `type`                   | —                                                                             |
| `dedupeIdentityComponents`             | `function`               | The components of a key, read back out of it.                                 |
| `dedupeIdentityKey`                    | `function`               | The dedupe key for an identity.                                               |
| `dedupeIdentityOf`                     | `function`               | Build the dedupe identity for one instance (S8.8.a's other half).             |
| `DedupeKeyFault`                       | `type`                   | —                                                                             |
| `dedupeKeyFaults`                      | `function`               | Check a declared dedupe key against the event it claims to identify (S8.8.a). |
| `DigestClaim.idempotencyKey`           | `string`                 | —                                                                             |
| `DigestEntry.dedupeKey`                | `string`                 | —                                                                             |
| `DigestEntry.sequence`                 | `number`                 | The source of truth's per-target sequence. Decides supersession.              |
| `digestIdempotencyKey`                 | `function`               | The key that makes one digest send idempotent (decision 9).                   |
| `DigestSendRequest.concurrentClaims`   | `readonly DigestClaim[]` | —                                                                             |
| `DigestSendRequest.hostIdempotencyKey` | `string`                 | The key the HOST computed for this send.                                      |
| `DigestWindow.attempt`                 | `number`                 | Which attempt this is. A reclaim after a dead worker is the second.           |

## Pagination

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

## State and failure

| Symbol                                    | Type                                     | Notes                                                           |
| ----------------------------------------- | ---------------------------------------- | --------------------------------------------------------------- |
| `AdmissionRequest.hostDropsOnRefusal`     | `boolean`                                | True where the host discards a notice the digest refuses.       |
| `CHANNEL_SEND_OUTCOMES`                   | `enumeration`                            | —                                                               |
| `ChannelSendOutcome`                      | `type`                                   | —                                                               |
| `ChannelSendRecord.outcome`               | `ChannelSendOutcome`                     | —                                                               |
| `DIGEST_ADMISSION_REFUSALS`               | `enumeration`                            | Why a notice marked `defer-to-digest` is not admitted.          |
| `DigestAdmissionRefusal`                  | `type`                                   | —                                                               |
| `DigestContent.failures`                  | `readonly string[]`                      | Entry ids the digest must NAME rather than count.               |
| `DigestContent.outcomes`                  | `Readonly<Record<EntryOutcome, number>>` | —                                                               |
| `DigestEntry.outcome`                     | `EntryOutcome`                           | —                                                               |
| `DigestRendering.failuresNamed`           | `readonly string[]`                      | The entry ids the digest names individually.                    |
| `DigestSendRequest.channelOutcomes`       | `readonly ChannelSendRecord[]`           | —                                                               |
| `DigestWindow.state`                      | `WindowState`                            | —                                                               |
| `ENTRY_OUTCOMES`                          | `enumeration`                            | What happened to the thing an entry is about.                   |
| `EntryOutcome`                            | `type`                                   | —                                                               |
| `OUTCOMES_A_DIGEST_MUST_NAME`             | `enumeration`                            | The outcomes a digest must name individually rather than count. |
| `StormRequest.overflowLineStatesTheCount` | `boolean`                                | True where the overflow line says how many it stands for.       |
| `WINDOW_STATES`                           | `enumeration`                            | The states a window passes through.                             |
| `WindowState`                             | `type`                                   | —                                                               |

## Compatibility

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

## Deprecation

Not applicable: nothing on this page can be deprecated on its own; the package
version is its lifecycle.

## Evidence

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