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 | interface | — |
| admitToDigest | function | Decide whether a planned delivery may enter a digest at all. |
| CAP_SCOPES | enumeration | — |
| CapScope | type | — |
| CHANNEL_SEND_OUTCOMES | enumeration | — |
| ChannelSendOutcome | type | — |
| ChannelSendRecord | interface | — |
| CLASSIFICATION_FAULTS | enumeration | — |
| ClassificationFault | type | — |
| classifyPair | function | Decide how two waiting entries relate (S8.8.b). |
| coalesceDigest | function | Fold a window's arrivals into what the recipient actually receives (S8.8). |
| CoalesceOutcome | interface | — |
| CoalesceRequest | interface | — |
| composeDigestContent | function | Fold a window's members into what may be said about them (S8.8.d). |
| CREDENTIAL_BEARING_PARAMS | enumeration | Query and fragment parameter names that carry a credential. |
| decideDigestSend | function | Decide whether this window may be sent, and say what is wrong if it may not (S8.8.e). |
| DEDUPE_COMPONENTS | enumeration | The seven things a dedupe identity is made of. |
| DEDUPE_KEY_FAULTS | enumeration | — |
| DedupeComponent | type | — |
| DedupeIdentity | interface | One resolved dedupe identity: a value for each component. |
| 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). |
| DedupeKeySpec | interface | One deployment's declared dedupe key, checked against the event registry. |
| DIGEST_ADMISSION_FAULTS | enumeration | — |
| DIGEST_ADMISSION_REFUSALS | enumeration | Why a notice marked defer-to-digest is not admitted. |
| DIGEST_CADENCES | enumeration | How often a digest goes out. |
| DIGEST_CAP_FAULTS | enumeration | — |
| DIGEST_CLAIM_FAULTS | enumeration | — |
| DIGEST_CONTENT_FAULTS | enumeration | — |
| DIGEST_RELATIONS | enumeration | — |
| DIGEST_SCHEDULE_FAULTS | enumeration | — |
| DigestAdmissionFault | type | — |
| DigestAdmissionRefusal | type | — |
| DigestAudience | interface | What the reader may see AT COMPOSITION TIME, which is not when they were added to the audience. |
| DigestCadence | type | — |
| DigestCap | interface | One ceiling, with BOTH of its numbers. |
| DigestCapFault | type | — |
| digestCapFaults | function | Check a cap and the storm it was supposed to survive (S8.8.f). |
| DigestClaim | interface | — |
| DigestClaimFault | type | — |
| DigestContent | interface | The aggregate, as this module computes it. |
| DigestContentFault | type | — |
| DigestContentRequest | interface | — |
| DigestEntry | interface | One notice waiting in a digest. |
| DigestFinding | interface | — |
| digestIdempotencyKey | function | The key that makes one digest send idempotent (decision 9). |
| DigestLink | interface | — |
| DigestRelation | type | — |
| DigestRendering | interface | What the host actually rendered, so the content check has a second opinion. |
| DigestSchedule | interface | One recipient's digest schedule on one channel. |
| DigestScheduleFault | type | — |
| DigestSendRequest | interface | — |
| DigestWindow | interface | — |
| ENTRY_OUTCOMES | enumeration | What happened to the thing an entry is about. |
| EntryOutcome | type | — |
| EventInstance | interface | One arrived event, in exactly the terms a key is computed over. |
| HOST_SEND_INTENTS | enumeration | What the host says it is about to do with this window. |
| HostSendIntent | type | — |
| nextWindowClose | function | The next instant this schedule's window closes, strictly after at (S8.8.c). |
| NotificationDigestFault | type | — |
| OUTCOMES_A_DIGEST_MUST_NAME | enumeration | The outcomes a digest must name individually rather than count. |
| OVERFLOW_POLICIES | enumeration | What happens to what a cap displaces. |
| OverflowPolicy | type | — |
| RelationClaim | interface | The host's own reading of a pair, so the check has something to disagree with. |
| RelationVerdict | interface | — |
| scheduleFaults | function | Check one schedule against the notice it is about to hold (S8.8.c). |
| ScheduleRequest | interface | — |
| SEND_DECISIONS | enumeration | — |
| SendDecision | type | — |
| StormRequest | interface | — |
| WINDOW_STATES | enumeration | The states a window passes through. |
| WindowClose | interface | — |
| windowSpanMinutes | function | How long the interval ending at the next close actually is, in minutes. |
| WindowState | type | — |
Shapes#
AdmissionRequest#
| Field | Type | Required | Notes |
|---|---|---|---|
delivery |
PlannedDelivery | required | — |
registration |
EventRegistration | required | — |
schedule |
DigestSchedule | required | — |
occurredAt |
Instant | required | — |
now |
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.
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#
(typeof CAP_SCOPES)[number];
CHANNEL_SEND_OUTCOMES#
Values: not-attempted, sent, failed
ChannelSendOutcome#
(typeof CHANNEL_SEND_OUTCOMES)[number];
ChannelSendRecord#
| Field | Type | Required | Notes |
|---|---|---|---|
channel |
string |
required | — |
outcome |
ChannelSendOutcome | required | — |
attemptedAt |
Instant | null — 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#
(typeof CLASSIFICATION_FAULTS)[number];
classifyPair#
Decide how two waiting entries relate (S8.8.b).
classifyPair(a: DigestEntry, b: DigestEntry, claim: RelationClaim | null): RelationVerdict
coalesceDigest#
Fold a window's arrivals into what the recipient actually receives (S8.8).
coalesceDigest(request: CoalesceRequest): CoalesceOutcome
CoalesceOutcome#
| Field | Type | Required | Notes |
|---|---|---|---|
individual |
readonly 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 | required | — |
notificationCount |
number |
required | What this recipient actually receives. The item's evidence, as a number. |
findings |
readonly DigestFinding[] — DigestFinding |
required | — |
CoalesceRequest#
| Field | Type | Required | Notes |
|---|---|---|---|
subject |
string |
required | — |
entries |
readonly DigestEntry[] — DigestEntry |
required | — |
cap |
DigestCap | required | — |
audience |
DigestAudience | required | — |
links |
readonly DigestLink[] — DigestLink |
required | — |
taxonomy |
NotificationTaxonomy |
required | — |
composeDigestContent#
Fold a window's members into what may be said about them (S8.8.d).
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).
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#
(typeof DEDUPE_COMPONENTS)[number];
DedupeIdentity#
One resolved dedupe identity: a value for each component.
| Field | Type | Required | Notes |
|---|---|---|---|
recipient |
ActorId | required | — |
tenant |
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.
dedupeIdentityComponents(key: string): readonly string[]
dedupeIdentityKey#
The dedupe key for an identity.
dedupeIdentityKey(identity: DedupeIdentity): string
dedupeIdentityOf#
Build the dedupe identity for one instance (S8.8.a's other half).
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#
(typeof DEDUPE_KEY_FAULTS)[number];
dedupeKeyFaults#
Check a declared dedupe key against the event it claims to identify (S8.8.a).
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 |
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#
(typeof DIGEST_ADMISSION_FAULTS)[number];
DigestAdmissionRefusal#
(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 | required | — |
tenant |
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 | required | — |
DigestCadence#
(typeof DIGEST_CADENCES)[number];
DigestCap#
One ceiling, with BOTH of its numbers.
| Field | Type | Required | Notes |
|---|---|---|---|
scope |
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 | required | — |
DigestCapFault#
(typeof DIGEST_CAP_FAULTS)[number];
digestCapFaults#
Check a cap and the storm it was supposed to survive (S8.8.f).
digestCapFaults(request: StormRequest): { readonly bound: number; readonly findings: readonly DigestFinding[]; }
DigestClaim#
| Field | Type | Required | Notes |
|---|---|---|---|
holder |
string |
required | — |
claimedAt |
Instant | required | — |
leaseExpiresAt |
Instant | required | — |
fencingToken |
number |
required | Monotonic from the store, so a resumed worker is behind rather than equal. |
idempotencyKey |
string |
required | — |
DigestClaimFault#
(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 |
required | — |
targets |
readonly string[] |
required | — |
outcomes |
Readonly<Record<EntryOutcome, number>> — EntryOutcome |
required | — |
earliest |
Instant | null — Instant |
required | — |
latest |
Instant | null — Instant |
required | — |
failures |
readonly string[] |
required | Entry ids the digest must NAME rather than count. |
blockers |
readonly string[] |
required | — |
links |
readonly 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#
(typeof DIGEST_CONTENT_FAULTS)[number];
DigestContentRequest#
| Field | Type | Required | Notes |
|---|---|---|---|
subject |
string |
required | — |
entries |
readonly DigestEntry[] — DigestEntry |
required | — |
audience |
DigestAudience | required | — |
links |
readonly DigestLink[] — DigestLink |
required | — |
taxonomy |
NotificationTaxonomy |
required | — |
rendering |
DigestRendering | null — 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 | required | — |
tenant |
TenantId | required | — |
target |
string |
required | — |
transitionFrom |
string | null |
required | — |
transitionTo |
string | null |
required | — |
urgency |
string |
required | — |
obligation |
DeliveryObligation | required | — |
channel |
string |
required | — |
exposure |
ChannelExposure | required | — |
outcome |
EntryOutcome | required | — |
occurredAt |
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 | 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 |
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 | 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).
digestIdempotencyKey(tenant: TenantId, recipient: ActorId, channel: string, windowId: string): string
DigestLink#
| Field | Type | Required | Notes |
|---|---|---|---|
target |
string |
required | — |
href |
string |
required | — |
DigestRelation#
(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 |
required | — |
targetsRendered |
readonly string[] |
required | — |
withheldCountRendered |
number | null |
required | Non-null where the host renders a hidden remainder. |
earliestRendered |
Instant | null — Instant |
required | — |
latestRendered |
Instant | null — 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 | required | — |
channel |
string |
required | — |
exposure |
ChannelExposure | required | — |
cadence |
DigestCadence | required | — |
anchor |
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 | required | — |
maxDelayMinutes |
number |
required | The longest an item may wait, however far away the next close is. |
quietHours |
QuietHoursWindow | null — QuietHoursWindow |
required | — |
urgencyCeiling |
string |
required | Urgencies at or above this are never digested at all. |
DigestScheduleFault#
(typeof DIGEST_SCHEDULE_FAULTS)[number];
DigestSendRequest#
| Field | Type | Required | Notes |
|---|---|---|---|
window |
DigestWindow | required | — |
members |
readonly DigestEntry[] — DigestEntry |
required | — |
now |
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 |
required | The claim this window held on its previous attempt, if there was one. |
lateArrivals |
readonly DigestEntry[] — DigestEntry |
required | Entries that arrived after the close. |
channelOutcomes |
readonly ChannelSendRecord[] — ChannelSendRecord |
required | — |
retriesTheWholeWindow |
boolean |
required | True where a retry re-sends the whole window rather than the failed channel. |
concurrentClaims |
readonly DigestClaim[] — DigestClaim |
required | — |
hostIntent |
HostSendIntent | required | — |
DigestWindow#
| Field | Type | Required | Notes |
|---|---|---|---|
windowId |
string |
required | — |
recipient |
ActorId | required | — |
tenant |
TenantId | required | — |
channel |
string |
required | — |
opensAt |
Instant | required | — |
closesAt |
Instant | required | — |
state |
WindowState | required | — |
entryIds |
readonly string[] |
required | — |
claim |
DigestClaim | null — 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#
(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#
(typeof HOST_SEND_INTENTS)[number];
nextWindowClose#
The next instant this schedule's window closes, strictly after at (S8.8.c).
nextWindowClose(schedule: DigestSchedule, at: Instant): WindowClose
NotificationDigestFault#
| 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#
(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 | 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 | required | — |
winner |
string | null |
required | For supersedes, the entry id that wins. Null otherwise. |
findings |
readonly DigestFinding[] — DigestFinding |
required | — |
scheduleFaults#
Check one schedule against the notice it is about to hold (S8.8.c).
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 | required | — |
now |
Instant | required | — |
previousClosedAt |
Instant | null — Instant |
required | The close before this one, so a fixed-span implementation is visible. |
oldestOccurredAt |
Instant | null — Instant |
required | The oldest item already waiting. Max delay is measured from it. |
urgency |
string |
required | — |
registration |
EventRegistration | required | — |
hostClosesAt |
Instant | null — 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#
(typeof SEND_DECISIONS)[number];
StormRequest#
| Field | Type | Required | Notes |
|---|---|---|---|
subject |
string |
required | — |
cap |
DigestCap | required | — |
entries |
readonly DigestEntry[] — DigestEntry |
required | — |
channel |
string |
required | — |
now |
Instant | required | — |
ledger |
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 |
required | Null where the schedule cannot be resolved at all. |
resolution |
ZoneResolution | null — ZoneResolution |
required | — |
findings |
readonly DigestFinding[] — DigestFinding |
required | — |
windowSpanMinutes#
How long the interval ending at the next close actually is, in minutes.
windowSpanMinutes(schedule: DigestSchedule, at: Instant): number | null
WindowState#
(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.jsonlibs/oshun/workbench-kit/src/notification-digests.ts