# Mentions

Which people a picker may offer, why a guessed id and a typo have to fail
identically, what a search response must not vary with, how a naming that
arrives in pasted markup is checked again at submission, and what happens to a
name in a paragraph when the person it names is erased.

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

## Summary

- `src/mentions.ts`

| Entry point                     | Runtime class | Authorized by |
| ------------------------------- | ------------- | ------------- |
| `@oshun/workbench-kit/mentions` | `contract`    | S8.4          |

## Exports

| Symbol                                                    | Kind        | Summary                                                                                                           |
| --------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
| [ACKNOWLEDGEMENT_FAULTS](#acknowledgement_faults)         | enumeration | —                                                                                                                 |
| [AcknowledgementFault](#acknowledgementfault)             | type        | —                                                                                                                 |
| [acknowledgementFaults](#acknowledgementfaults)           | function    | —                                                                                                                 |
| [AcknowledgementView](#acknowledgementview)               | interface   | What a surface actually put in front of the author.                                                               |
| [acknowledgeToAuthor](#acknowledgetoauthor)               | function    | —                                                                                                                 |
| [AUDIENCE_NOTE_KEY](#audience_note_key)                   | constant    | The fixed sentence a group mention gets, with no numbers in it.                                                   |
| [AVATAR_REFERENCES](#avatar_references)                   | enumeration | —                                                                                                                 |
| [AvatarReference](#avatarreference)                       | type        | —                                                                                                                 |
| [AvatarSession](#avatarsession)                           | interface   | Per-session avatar handles.                                                                                       |
| [BODY_REGIONS](#body_regions)                             | enumeration | Where in a body an occurrence sits.                                                                               |
| [BodyRegion](#bodyregion)                                 | type        | —                                                                                                                 |
| [CandidateView](#candidateview)                           | interface   | —                                                                                                                 |
| [classifyOccurrence](#classifyoccurrence)                 | function    | The eight cases the item names, decided in one place.                                                             |
| [DELIVERY_FAULTS](#delivery_faults)                       | enumeration | —                                                                                                                 |
| [DeliveryContext](#deliverycontext)                       | interface   | —                                                                                                                 |
| [DeliveryFault](#deliveryfault)                           | type        | —                                                                                                                 |
| [DirectoryEntry](#directoryentry)                         | interface   | One identity the host's directory can offer, with the facts a scope decision needs and nothing else.              |
| [DISCLOSURE_CHANNELS](#disclosure_channels)               | enumeration | The seven channels the item names, as data.                                                                       |
| [DisclosureChannel](#disclosurechannel)                   | type        | —                                                                                                                 |
| [DISCOVERY_FAULTS](#discovery_faults)                     | enumeration | —                                                                                                                 |
| [DiscoveryFault](#discoveryfault)                         | type        | —                                                                                                                 |
| [discoveryFaults](#discoveryfaults)                       | function    | —                                                                                                                 |
| [DiscoverySurface](#discoverysurface)                     | interface   | What the deployment says it does, for the three channels a value cannot show.                                     |
| [DISPOSITION_PERMISSIVENESS](#disposition_permissiveness) | constant    | How much each disposition discloses, as data.                                                                     |
| [EDGE_FAULTS](#edge_faults)                               | enumeration | —                                                                                                                 |
| [EdgeFault](#edgefault)                                   | type        | —                                                                                                                 |
| [ERASED_MENTION_LABEL](#erased_mention_label)             | constant    | What an erased mention leaves behind in the prose.                                                                |
| [GROUP_SUBJECT_KINDS](#group_subject_kinds)               | enumeration | The kinds whose recipients are DERIVED, and therefore have to be pinned.                                          |
| [IDENTITY_STANDINGS](#identity_standings)                 | enumeration | Where an identity stands NOW.                                                                                     |
| [identityResidue](#identityresidue)                       | function    | What the field-walking erasure sweep cannot see.                                                                  |
| [IdentityStanding](#identitystanding)                     | type        | —                                                                                                                 |
| [isDiscoverable](#isdiscoverable)                         | function    | Whether one identity is discoverable by this searcher in this scope.                                              |
| [isGroupKind](#isgroupkind)                               | function    | —                                                                                                                 |
| [issueAvatarRef](#issueavatarref)                         | function    | —                                                                                                                 |
| [LIFECYCLE_FAULTS](#lifecycle_faults)                     | enumeration | —                                                                                                                 |
| [LifecycleFault](#lifecyclefault)                         | type        | —                                                                                                                 |
| [lifecycleFaults](#lifecyclefaults)                       | function    | —                                                                                                                 |
| [LifecycleObservation](#lifecycleobservation)             | interface   | What a host says it does across a mention's life.                                                                 |
| [MENTION_FAULTS](#mention_faults)                         | constant    | —                                                                                                                 |
| [MENTION_RENDERS](#mention_renders)                       | enumeration | —                                                                                                                 |
| [MENTION_SCHEMA_FAULTS](#mention_schema_faults)           | enumeration | —                                                                                                                 |
| [MENTION_SUBJECT_KINDS](#mention_subject_kinds)           | enumeration | What a mention can name.                                                                                          |
| [MentionAcknowledgement](#mentionacknowledgement)         | interface   | —                                                                                                                 |
| [MentionDelivery](#mentiondelivery)                       | interface   | —                                                                                                                 |
| [mentionDeliveryKey](#mentiondeliverykey)                 | function    | The idempotency key: one comment, one person, one naming.                                                         |
| [MentionFault](#mentionfault)                             | type        | —                                                                                                                 |
| [MentionFinding](#mentionfinding)                         | interface   | —                                                                                                                 |
| [mentionHeadline](#mentionheadline)                       | function    | —                                                                                                                 |
| [MentionOccurrence](#mentionoccurrence)                   | interface   | —                                                                                                                 |
| [MentionPolicy](#mentionpolicy)                           | interface   | What the deployment permits. Supplied by the host; the kit holds no roster.                                       |
| [MentionReference](#mentionreference)                     | interface   | The stored reference: stable, tenant-scoped, and carrying no display data.                                        |
| [MentionRender](#mentionrender)                           | interface   | What a reader is shown, and the reference they are handed with it.                                                |
| [MentionRenderKind](#mentionrenderkind)                   | type        | —                                                                                                                 |
| [MentionResolution](#mentionresolution)                   | type        | The outcome of resolving one occurrence at submission.                                                            |
| [MentionSchemaFault](#mentionschemafault)                 | type        | —                                                                                                                 |
| [mentionSchemaFaults](#mentionschemafaults)               | function    | —                                                                                                                 |
| [MentionScope](#mentionscope)                             | interface   | Where a mention is being made, and what the object permits.                                                       |
| [MentionSubjectKind](#mentionsubjectkind)                 | type        | —                                                                                                                 |
| [MentionSummary](#mentionsummary)                         | interface   | —                                                                                                                 |
| [MINIMUM_PREFIX_CODE_POINTS](#minimum_prefix_code_points) | constant    | Below this, a prefix matches too much of any directory to be a query.                                             |
| [Naming](#naming)                                         | interface   | One naming inside a comment: an occurrence and the people it reaches.                                             |
| [newAvatarSession](#newavatarsession)                     | function    | —                                                                                                                 |
| [OCCURRENCE_DISPOSITIONS](#occurrence_dispositions)       | enumeration | What happens to one naming, for one person.                                                                       |
| [OCCURRENCE_REASONS](#occurrence_reasons)                 | enumeration | —                                                                                                                 |
| [OCCURRENCE_RULE_ORDER](#occurrence_rule_order)           | constant    | The order the rules run in, as data.                                                                              |
| [OccurrenceCase](#occurrencecase)                         | interface   | —                                                                                                                 |
| [OccurrenceContext](#occurrencecontext)                   | interface   | —                                                                                                                 |
| [OccurrenceDisposition](#occurrencedisposition)           | type        | —                                                                                                                 |
| [occurrenceFaults](#occurrencefaults)                     | function    | Compare what a host did against what the rule says, and report only the cases where the host was MORE permissive. |
| [OccurrenceOutcome](#occurrenceoutcome)                   | interface   | —                                                                                                                 |
| [OccurrenceReason](#occurrencereason)                     | type        | —                                                                                                                 |
| [PASTED_TOKEN_PATHS](#pasted_token_paths)                 | enumeration | —                                                                                                                 |
| [PastedTokenPath](#pastedtokenpath)                       | type        | —                                                                                                                 |
| [PinnedRecipient](#pinnedrecipient)                       | interface   | A person a group mention actually reached, pinned at resolution.                                                  |
| [planDeliveries](#plandeliveries)                         | function    | Turn one COMMENT's namings into the deliveries they produce.                                                      |
| [PREFETCH_SETS](#prefetch_sets)                           | enumeration | —                                                                                                                 |
| [PrefetchSet](#prefetchset)                               | type        | —                                                                                                                 |
| [Probe](#probe)                                           | interface   | —                                                                                                                 |
| [probeForOracle](#probefororacle)                         | function    | The abuse test: given probes whose ground truth is known, which channel told the attacker which was which?        |
| [ProbeGroundTruth](#probegroundtruth)                     | type        | —                                                                                                                 |
| [RecipientContext](#recipientcontext)                     | interface   | What the recipient's preferences and locale say, from S7.19's vocabulary.                                         |
| [renderMention](#rendermention)                           | function    | Render one occurrence for one reader.                                                                             |
| [RenderRequest](#renderrequest)                           | interface   | —                                                                                                                 |
| [RESOLUTION_DEPENDENCIES](#resolution_dependencies)       | enumeration | —                                                                                                                 |
| [RESOLUTION_DEPENDS_ON](#resolution_depends_on)           | constant    | The axis, as data.                                                                                                |
| [RESOLUTION_REFUSALS](#resolution_refusals)               | enumeration | —                                                                                                                 |
| [ResolutionDependency](#resolutiondependency)             | type        | —                                                                                                                 |
| [ResolutionRefusal](#resolutionrefusal)                   | type        | —                                                                                                                 |
| [ResolutionRequest](#resolutionrequest)                   | interface   | —                                                                                                                 |
| [resolveMention](#resolvemention)                         | function    | Resolve one occurrence, under the AUTHOR's scope, at submission.                                                  |
| [responseDifferences](#responsedifferences)               | function    | Which observable fields two responses disagree on, as channel names.                                              |
| [SEARCH_FAULTS](#search_faults)                           | enumeration | —                                                                                                                 |
| [SEARCH_PLANS](#search_plans)                             | enumeration | —                                                                                                                 |
| [Searcher](#searcher)                                     | interface   | The actor doing the searching, and the scopes they hold.                                                          |
| [SearchFault](#searchfault)                               | type        | —                                                                                                                 |
| [searchFaults](#searchfaults)                             | function    | The negative tests S8.4.b asks for, over a directory a host actually served.                                      |
| [searchIdentities](#searchidentities)                     | function    | The search, and the property is that its result is a function ONLY of the visible set.                            |
| [SearchPlan](#searchplan)                                 | type        | —                                                                                                                 |
| [SearchRequest](#searchrequest)                           | interface   | —                                                                                                                 |
| [SearchResponse](#searchresponse)                         | interface   | Everything a caller can observe about a search.                                                                   |
| [SentDelivery](#sentdelivery)                             | interface   | A delivery a host says it actually sent, for the adversarial pass over it.                                        |
| [sentDeliveryFaults](#sentdeliveryfaults)                 | function    | The check over what was sent, which is a different question from what was planned.                                |
| [summarizeMentions](#summarizementions)                   | function    | —                                                                                                                 |
| [TOTAL_SOURCES](#total_sources)                           | enumeration | —                                                                                                                 |
| [TotalSource](#totalsource)                               | type        | —                                                                                                                 |
| [UNRESOLVED_RENDERS](#unresolved_renders)                 | enumeration | —                                                                                                                 |
| [UnresolvedRender](#unresolvedrender)                     | type        | —                                                                                                                 |

## Shapes

#### ACKNOWLEDGEMENT_FAULTS

Values: `acknowledgement-reports-the-delivery`,
`acknowledgement-counts-who-could-not-be-reached`,
`acknowledgement-names-a-group-mentions-recipients`,
`acknowledgement-discloses-a-recipients-standing`,
`acknowledgement-hides-what-did-not-resolve`

#### AcknowledgementFault

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

#### acknowledgementFaults

```ts
acknowledgementFaults(view: AcknowledgementView, truth: MentionAcknowledgement, subject = 'acknowledgement'): readonly MentionFinding[]
```

#### AcknowledgementView

What a surface actually put in front of the author.

| Field                        | Type                | Required | Notes                                                                    |
| ---------------------------- | ------------------- | -------- | ------------------------------------------------------------------------ |
| `recordedShown`              | `number`            | required | —                                                                        |
| `unresolvedShown`            | `number`            | required | —                                                                        |
| `deliveredCountShown`        | `number \| null`    | required | Non-null when the surface told the author how many were delivered.       |
| `unreachableCountShown`      | `number \| null`    | required | Non-null when it told them how many could not be reached.                |
| `recipientsNamed`            | `readonly string[]` | required | Recipients of a group mention, named to the author.                      |
| `recipientStandingDisclosed` | `boolean`           | required | Whether any recipient's standing was disclosed — held, suspended, muted. |
| `noteKey`                    | `string \| null`    | required | —                                                                        |

#### acknowledgeToAuthor

```ts
acknowledgeToAuthor(resolutions: readonly MentionResolution[]): MentionAcknowledgement
```

#### AUDIENCE_NOTE_KEY

The fixed sentence a group mention gets, with no numbers in it.

Value: `'mention.scoped-to-the-audience'`

#### AVATAR_REFERENCES

Values: `issued-per-session`, `derived-from-the-subject-id`, `none`

#### AvatarReference

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

#### AvatarSession

Per-session avatar handles.

| Field    | Type                  | Required | Notes |
| -------- | --------------------- | -------- | ----- |
| `salt`   | `string`              | required | —     |
| `issued` | `Map<string, string>` | required | —     |

#### BODY_REGIONS

Where in a body an occurrence sits.

Values: `authored`, `quoted`, `system-generated`

#### BodyRegion

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

#### CandidateView

| Field       | Type                                      | Required | Notes                                                                     |
| ----------- | ----------------------------------------- | -------- | ------------------------------------------------------------------------- |
| `subjectId` | `string`                                  | required | —                                                                         |
| `kind`      | [MentionSubjectKind](#mentionsubjectkind) | required | —                                                                         |
| `label`     | `string`                                  | required | What to show. A display string, and the reference is never built from it. |
| `avatarRef` | `string \| null`                          | required | An issued handle, never a function of the subject. Null when none exists. |

#### classifyOccurrence

The eight cases the item names, decided in one place.

```ts
classifyOccurrence(context: OccurrenceContext): OccurrenceOutcome
```

#### DELIVERY_FAULTS

Values: `two-deliveries-under-one-key`,
`source-context-sent-to-somebody-who-may-not-read-the-target`,
`source-context-sent-after-the-target-was-erased`,
`rendered-in-the-authors-locale`, `urgency-outside-the-taxonomy`,
`preference-silenced-a-naming`, `naming-collapsed-into-a-digest`,
`retraction-deleted-rather-than-withdrawn`,
`delivery-to-a-recipient-the-mention-never-pinned`

#### DeliveryContext

| Field           | Type                                              | Required | Notes                                                            |
| --------------- | ------------------------------------------------- | -------- | ---------------------------------------------------------------- |
| `commentId`     | `string`                                          | required | —                                                                |
| `namings`       | `readonly Naming[]` — [Naming](#naming)           | required | —                                                                |
| `commentState`  | [CommentState](./comment-threads.md#commentstate) | required | —                                                                |
| `targetState`   | `'live' \| 'deleted' \| 'erased'`                 | required | —                                                                |
| `deliveredKeys` | `readonly string[]`                               | required | Keys already delivered, from the host's outbox.                  |
| `urgency`       | `string`                                          | required | —                                                                |
| `authorLocale`  | `string`                                          | required | —                                                                |
| `sourceContext` | `string \| null`                                  | required | The excerpt this naming would carry, or null when there is none. |

#### DeliveryFault

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

#### DirectoryEntry

One identity the host's directory can offer, with the facts a scope decision
needs and nothing else.

| Field           | Type                                      | Required | Notes                                                                |
| --------------- | ----------------------------------------- | -------- | -------------------------------------------------------------------- |
| `subjectId`     | `string`                                  | required | —                                                                    |
| `kind`          | [MentionSubjectKind](#mentionsubjectkind) | required | —                                                                    |
| `tenant`        | [TenantId](./identity.md#tenantid)        | required | —                                                                    |
| `workspaces`    | `readonly string[]`                       | required | Workspaces this identity belongs to. Empty means tenant-wide.        |
| `matchKeys`     | `readonly string[]`                       | required | Match keys the host will search on — display name, handle, alias.    |
| `standing`      | [IdentityStanding](#identitystanding)     | required | —                                                                    |
| `canReadTarget` | `boolean`                                 | required | Whether this identity can read the object the mention would land on. |

#### DISCLOSURE_CHANNELS

The seven channels the item names, as data.

Values: `timing`, `result-count`, `avatar`, `error`, `autocomplete`,
`copied-markup`, `stable-id`

#### DisclosureChannel

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

#### DISCOVERY_FAULTS

Values: `filter-applied-after-retrieval`, `total-counted-before-the-filter`,
`avatar-reference-derived-from-the-subject-id`,
`avatar-served-outside-the-mention-scope`,
`concealment-distinguishable-from-a-miss`,
`autocomplete-prefetched-the-directory`, `filtering-done-on-the-client`,
`pasted-token-trusted-as-written`, `unresolved-mention-rendered-as-an-identity`,
`unresolved-mention-rendered-as-an-error`, `prefix-minimum-below-the-floor`,
`prefix-minimum-claimed-as-a-control`

#### DiscoveryFault

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

#### discoveryFaults

```ts
discoveryFaults(surface: DiscoverySurface, subject = 'mention-search'): readonly MentionFinding[]
```

#### DiscoverySurface

What the deployment says it does, for the three channels a value cannot show.

| Field                               | Type                                  | Required | Notes                                                   |
| ----------------------------------- | ------------------------------------- | -------- | ------------------------------------------------------- |
| `plan`                              | [SearchPlan](#searchplan)             | required | —                                                       |
| `totalSource`                       | [TotalSource](#totalsource)           | required | —                                                       |
| `avatarReference`                   | [AvatarReference](#avatarreference)   | required | —                                                       |
| `avatarServedWithinTheMentionScope` | `boolean`                             | required | —                                                       |
| `missAndConcealmentAreOneOutcome`   | `boolean`                             | required | Whether a miss and a concealment produce one outcome.   |
| `autocompletePrefetch`              | [PrefetchSet](#prefetchset)           | required | —                                                       |
| `filteringHappens`                  | `'server' \| 'client'`                | required | —                                                       |
| `pastedTokenPath`                   | [PastedTokenPath](#pastedtokenpath)   | required | —                                                       |
| `unresolvedRender`                  | [UnresolvedRender](#unresolvedrender) | required | —                                                       |
| `minimumPrefix`                     | `number`                              | required | —                                                       |
| `prefixMinimumClaimedAsAControl`    | `boolean`                             | required | What the deployment claims the prefix minimum achieves. |

#### DISPOSITION_PERMISSIVENESS

How much each disposition discloses, as data.

#### EDGE_FAULTS

Values: `quoted-mention-delivered`, `self-mention-delivered`,
`duplicate-mention-delivered-twice`, `edit-removed-mention-left-live`,
`suspended-recipient-delivered`, `departed-recipient-delivered`,
`erased-recipient-delivered`, `withdrawn-comment-still-naming`,
`mention-on-deleted-content-carried-its-context`,
`inaccessible-target-mention-carried-its-context`

#### EdgeFault

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

#### ERASED_MENTION_LABEL

What an erased mention leaves behind in the prose.

Value: `'mention.erased'`

#### GROUP_SUBJECT_KINDS

The kinds whose recipients are DERIVED, and therefore have to be pinned.

Values: `team`, `role`, `on-call`

#### IDENTITY_STANDINGS

Where an identity stands NOW.

Values: `active`, `suspended`, `departed`, `erased`

#### identityResidue

What the field-walking erasure sweep cannot see.

```ts
identityResidue(occurrences: readonly MentionOccurrence[], erasedSubjects: readonly string[], bodyOf: (commentId: string) => string | null): readonly MentionFinding[]
```

#### IdentityStanding

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

#### isDiscoverable

Whether one identity is discoverable by this searcher in this scope.

```ts
isDiscoverable(scope: MentionScope, searcher: Searcher, entry: DirectoryEntry): boolean
```

#### isGroupKind

```ts
isGroupKind(kind: MentionSubjectKind): boolean
```

#### issueAvatarRef

```ts
issueAvatarRef(session: AvatarSession, subjectId: string): string
```

#### LIFECYCLE_FAULTS

Values: `resolution-deferred-to-read-time`, `resolved-under-the-readers-scope`,
`eligibility-not-revalidated-at-submission`, `fan-out-rederived-at-read-time`,
`departed-identity-presented-as-redacted`, `departed-identity-rendered-as-live`,
`historical-mention-re-resolved`,
`unresolvable-mention-rendered-with-an-identity`,
`erased-reference-left-in-the-body`, `erased-name-left-in-the-prose`,
`erased-identity-left-in-a-pinned-fan-out`

#### LifecycleFault

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

#### lifecycleFaults

```ts
lifecycleFaults(observations: readonly LifecycleObservation[]): readonly MentionFinding[]
```

#### LifecycleObservation

What a host says it does across a mention's life.

| Field                                | Type                                         | Required | Notes                                                                    |
| ------------------------------------ | -------------------------------------------- | -------- | ------------------------------------------------------------------------ |
| `mentionId`                          | `string`                                     | required | —                                                                        |
| `resolvedAt`                         | `'submission' \| 'read'`                     | required | —                                                                        |
| `resolvedUnder`                      | `'the-authors-scope' \| 'the-readers-scope'` | required | —                                                                        |
| `fanOutDerivedAt`                    | `'resolution' \| 'read'`                     | required | —                                                                        |
| `eligibilityRevalidatedAtSubmission` | `boolean`                                    | required | —                                                                        |
| `renderForDeparted`                  | [MentionRenderKind](#mentionrenderkind)      | required | —                                                                        |
| `renderForAReaderWhoMayNotResolve`   | [MentionRenderKind](#mentionrenderkind)      | required | —                                                                        |
| `departedPresentedAsRedacted`        | `boolean`                                    | required | Whether a departed identity is presented using the redaction vocabulary. |
| `historicalMentionReResolved`        | `boolean`                                    | required | Whether a historical mention is re-resolved against today's directory.   |

#### MENTION_FAULTS

#### MENTION_RENDERS

Values: `linked`, `historical`, `plain`, `removed`

#### MENTION_SCHEMA_FAULTS

Values: `reference-that-is-the-typed-text`, `reference-carrying-display-data`,
`alias-kind-the-policy-forbids`, `alias-kind-this-build-cannot-resolve`,
`group-mention-with-no-pinned-recipients`, `human-mention-carrying-a-fan-out`,
`recipient-pinned-with-no-instant`, `fan-out-over-the-policy-ceiling`,
`occurrence-with-no-position-in-the-body`, `occurrence-with-no-typed-text`,
`reference-scoped-to-another-tenant`, `reference-resolved-before-it-was-typed`

#### MENTION_SUBJECT_KINDS

What a mention can name.

Values: `human`, `team`, `role`, `on-call`

#### MentionAcknowledgement

| Field        | Type                                                                     | Required | Notes                                                                                                                                     |
| ------------ | ------------------------------------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `recorded`   | `number`                                                                 | required | Namings that resolved. A fact about the author's own text.                                                                                |
| `unresolved` | `number`                                                                 | required | Namings that did not. Also a fact about their own text — a typo and a concealment arrive here as one number, which is what makes it safe. |
| `refused`    | `readonly ResolutionRefusal[]` — [ResolutionRefusal](#resolutionrefusal) | required | —                                                                                                                                         |
| `noteKey`    | `string \| null`                                                         | required | Present when any naming was a group. Never a count.                                                                                       |

#### MentionDelivery

| Field                | Type                                            | Required | Notes                                             |
| -------------------- | ----------------------------------------------- | -------- | ------------------------------------------------- |
| `key`                | `string`                                        | required | —                                                 |
| `recipient`          | [ActorId](./identity.md#actorid)                | required | —                                                 |
| `kind`               | `'mention'`                                     | required | —                                                 |
| `disposition`        | [OccurrenceDisposition](#occurrencedisposition) | required | —                                                 |
| `reason`             | [OccurrenceReason](#occurrencereason)           | required | —                                                 |
| `urgency`            | `string`                                        | required | —                                                 |
| `locale`             | `string`                                        | required | —                                                 |
| `sourceContext`      | `string \| null`                                | required | —                                                 |
| `contextDisposition` | `AuthorizationDisposition`                      | required | What the excerpt's own authorization came out as. |

#### mentionDeliveryKey

The idempotency key: one comment, one person, one naming.

```ts
mentionDeliveryKey(commentId: string, recipient: ActorId): string
```

#### MentionFault

```ts
| MentionSchemaFault
| SearchFault
| DiscoveryFault
| LifecycleFault
| EdgeFault
| DeliveryFault
| AcknowledgementFault
```

#### MentionFinding

| Field     | Type                          | Required | Notes |
| --------- | ----------------------------- | -------- | ----- |
| `kind`    | [MentionFault](#mentionfault) | required | —     |
| `subject` | `string`                      | required | —     |
| `detail`  | `string`                      | required | —     |

#### mentionHeadline

```ts
mentionHeadline(summary: MentionSummary): string
```

#### MentionOccurrence

| Field        | Type                                                               | Required | Notes                                                                     |
| ------------ | ------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------- |
| `mentionId`  | `string`                                                           | required | —                                                                         |
| `commentId`  | `string`                                                           | required | —                                                                         |
| `threadId`   | `string`                                                           | required | —                                                                         |
| `offset`     | `number`                                                           | required | Where in the body it sits. Decision 6 needs a position, not just a token. |
| `length`     | `number`                                                           | required | —                                                                         |
| `region`     | [BodyRegion](#bodyregion)                                          | required | —                                                                         |
| `typedText`  | `string`                                                           | required | What the author typed, verbatim.                                          |
| `reference`  | `MentionReference \| null` — [MentionReference](#mentionreference) | required | Null until submission resolves it; null forever if it never did.          |
| `recipients` | `readonly PinnedRecipient[]` — [PinnedRecipient](#pinnedrecipient) | required | Empty for `human`; the pinned fan-out for every group kind.               |
| `authoredBy` | [ActorRef](./identity.md#actorref)                                 | required | —                                                                         |
| `createdAt`  | [Instant](./identity.md#instant)                                   | required | —                                                                         |

#### MentionPolicy

What the deployment permits. Supplied by the host; the kit holds no roster.

| Field                         | Type                                                                        | Required | Notes                                                              |
| ----------------------------- | --------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------ |
| `permittedKinds`              | `readonly MentionSubjectKind[]` — [MentionSubjectKind](#mentionsubjectkind) | required | —                                                                  |
| `mayMentionBeyondTheAudience` | `boolean`                                                                   | required | Whether a mention may name somebody who cannot read the target.    |
| `maxFanOut`                   | `number`                                                                    | required | The largest fan-out a single group mention may produce.            |
| `resolvableKinds`             | `readonly MentionSubjectKind[]` — [MentionSubjectKind](#mentionsubjectkind) | required | Alias kinds whose resolution this deployment can actually perform. |

#### MentionReference

The stored reference: stable, tenant-scoped, and carrying no display data.

| Field       | Type                                      | Required | Notes |
| ----------- | ----------------------------------------- | -------- | ----- |
| `kind`      | [MentionSubjectKind](#mentionsubjectkind) | required | —     |
| `subjectId` | `string`                                  | required | —     |
| `tenant`    | [TenantId](./identity.md#tenantid)        | required | —     |

#### MentionRender

What a reader is shown, and the reference they are handed with it.

| Field       | Type                                                               | Required | Notes                                             |
| ----------- | ------------------------------------------------------------------ | -------- | ------------------------------------------------- |
| `render`    | [MentionRenderKind](#mentionrenderkind)                            | required | —                                                 |
| `text`      | `string`                                                           | required | —                                                 |
| `reference` | `MentionReference \| null` — [MentionReference](#mentionreference) | required | Null unless the reader may resolve this identity. |

#### MentionRenderKind

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

#### MentionResolution

The outcome of resolving one occurrence at submission.

```ts
| { readonly outcome: 'resolved'; readonly reference: MentionReference; readonly recipients: readonly PinnedRecipient[]; }
| { readonly outcome: 'unresolved'; readonly reason: 'no-such-identity-here' }
| { readonly outcome: 'refused'; readonly reason: ResolutionRefusal; readonly detail: string }
```

#### MentionSchemaFault

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

#### mentionSchemaFaults

```ts
mentionSchemaFaults(occurrences: readonly MentionOccurrence[], policy: MentionPolicy, tenant: TenantId): readonly MentionFinding[]
```

#### MentionScope

Where a mention is being made, and what the object permits.

| Field                 | Type                                                      | Required | Notes                                                      |
| --------------------- | --------------------------------------------------------- | -------- | ---------------------------------------------------------- |
| `tenant`              | [TenantId](./identity.md#tenantid)                        | required | —                                                          |
| `workspace`           | `string \| null`                                          | required | —                                                          |
| `targetId`            | `string`                                                  | required | —                                                          |
| `threadVisibility`    | [ThreadVisibility](./comment-threads.md#threadvisibility) | required | —                                                          |
| `targetMaxVisibility` | [ThreadVisibility](./comment-threads.md#threadvisibility) | required | The widest the target permits, from S8.2's `TargetPolicy`. |
| `policy`              | [MentionPolicy](#mentionpolicy)                           | required | —                                                          |

#### MentionSubjectKind

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

#### MentionSummary

| Field                 | Type                                                                                       | Required | Notes                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------ |
| `total`               | `number`                                                                                   | required | —                                                                        |
| `resolved`            | `number`                                                                                   | required | —                                                                        |
| `unresolved`          | `number`                                                                                   | required | —                                                                        |
| `quoted`              | `number`                                                                                   | required | —                                                                        |
| `byKind`              | `Readonly<Record<MentionSubjectKind, number>>` — [MentionSubjectKind](#mentionsubjectkind) | required | —                                                                        |
| `distinctPeopleNamed` | `number`                                                                                   | required | People actually reached, counted once however many namings reached them. |

#### MINIMUM_PREFIX_CODE_POINTS

Below this, a prefix matches too much of any directory to be a query.

Value: `2`

#### Naming

One naming inside a comment: an occurrence and the people it reaches.

| Field                   | Type                                                                  | Required | Notes |
| ----------------------- | --------------------------------------------------------------------- | -------- | ----- |
| `occurrence`            | [MentionOccurrence](#mentionoccurrence)                               | required | —     |
| `recipients`            | `readonly RecipientContext[]` — [RecipientContext](#recipientcontext) | required | —     |
| `stillPresentInTheBody` | `boolean`                                                             | required | —     |

#### newAvatarSession

```ts
newAvatarSession(salt: string): AvatarSession
```

#### OCCURRENCE_DISPOSITIONS

What happens to one naming, for one person.

Values: `deliver`, `withhold-context`, `hold`, `record-only`, `retract`,
`refuse`

#### OCCURRENCE_REASONS

Values: `a-quotation-replays-a-naming-it-does-not-make`,
`the-mention-was-removed-by-an-edit`, `removed-before-anything-was-sent`,
`the-identity-was-erased`, `the-author-named-themselves`,
`the-same-person-named-twice-in-one-comment`,
`already-delivered-under-this-key`, `the-identity-has-left`,
`the-identity-is-suspended`, `the-comment-is-no-longer-published`,
`the-target-is-gone`, `the-recipient-cannot-read-the-target`,
`nothing-stands-in-the-way`

#### OCCURRENCE_RULE_ORDER

The order the rules run in, as data.

#### OccurrenceCase

| Field     | Type                                            | Required | Notes                       |
| --------- | ----------------------------------------------- | -------- | --------------------------- |
| `context` | [OccurrenceContext](#occurrencecontext)         | required | —                           |
| `actual`  | [OccurrenceDisposition](#occurrencedisposition) | required | What the host actually did. |

#### OccurrenceContext

| Field                                 | Type                                              | Required | Notes                                                                |
| ------------------------------------- | ------------------------------------------------- | -------- | -------------------------------------------------------------------- |
| `occurrence`                          | [MentionOccurrence](#mentionoccurrence)           | required | —                                                                    |
| `recipient`                           | [ActorId](./identity.md#actorid)                  | required | —                                                                    |
| `standing`                            | [IdentityStanding](#identitystanding)             | required | —                                                                    |
| `recipientCanReadTarget`              | `boolean`                                         | required | —                                                                    |
| `commentState`                        | [CommentState](./comment-threads.md#commentstate) | required | —                                                                    |
| `targetState`                         | `'live' \| 'deleted' \| 'erased'`                 | required | —                                                                    |
| `stillPresentInTheBody`               | `boolean`                                         | required | False once an edit has taken the mention out of the body.            |
| `alreadyDeliveredUnderThisKey`        | `boolean`                                         | required | Whether something has already gone out under this occurrence's key.  |
| `firstNamingOfThisPersonInTheComment` | `boolean`                                         | required | False for the second and later namings of one person in one comment. |

#### OccurrenceDisposition

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

#### occurrenceFaults

Compare what a host did against what the rule says, and report only the cases
where the host was MORE permissive.

```ts
occurrenceFaults(cases: readonly OccurrenceCase[]): readonly MentionFinding[]
```

#### OccurrenceOutcome

| Field         | Type                                            | Required | Notes |
| ------------- | ----------------------------------------------- | -------- | ----- |
| `disposition` | [OccurrenceDisposition](#occurrencedisposition) | required | —     |
| `reason`      | [OccurrenceReason](#occurrencereason)           | required | —     |

#### OccurrenceReason

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

#### PASTED_TOKEN_PATHS

Values: `resolved-under-the-pasters-scope`, `trusted-as-written`

#### PastedTokenPath

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

#### PinnedRecipient

A person a group mention actually reached, pinned at resolution.

| Field       | Type                             | Required | Notes |
| ----------- | -------------------------------- | -------- | ----- |
| `actorId`   | [ActorId](./identity.md#actorid) | required | —     |
| `derivedAt` | [Instant](./identity.md#instant) | required | —     |

#### planDeliveries

Turn one COMMENT's namings into the deliveries they produce.

```ts
planDeliveries(context: DeliveryContext, taxonomy: NotificationTaxonomy): { readonly deliveries: readonly MentionDelivery[]; readonly findings: readonly MentionFinding[]; }
```

#### PREFETCH_SETS

Values: `none`, `the-visible-set`, `the-tenant-directory`

#### PrefetchSet

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

#### Probe

| Field      | Type                                  | Required | Notes |
| ---------- | ------------------------------------- | -------- | ----- |
| `label`    | `string`                              | required | —     |
| `truth`    | [ProbeGroundTruth](#probegroundtruth) | required | —     |
| `response` | [SearchResponse](#searchresponse)     | required | —     |

#### probeForOracle

The abuse test: given probes whose ground truth is known, which channel told the
attacker which was which?

```ts
probeForOracle(probes: readonly Probe[]): readonly DisclosureChannel[]
```

#### ProbeGroundTruth

```ts
'nothing-there' | 'there-but-hidden';
```

#### RecipientContext

What the recipient's preferences and locale say, from S7.19's vocabulary.

| Field              | Type                                  | Required | Notes                                                     |
| ------------------ | ------------------------------------- | -------- | --------------------------------------------------------- |
| `actorId`          | [ActorId](./identity.md#actorid)      | required | —                                                         |
| `standing`         | [IdentityStanding](#identitystanding) | required | —                                                         |
| `canReadTarget`    | `boolean`                             | required | —                                                         |
| `locale`           | `string`                              | required | —                                                         |
| `channel`          | `string`                              | required | —                                                         |
| `urgencyThreshold` | `string`                              | required | The weakest urgency this recipient wants on this channel. |
| `muted`            | `boolean`                             | required | Whether the recipient has muted this category outright.   |

#### renderMention

Render one occurrence for one reader.

```ts
renderMention(request: RenderRequest): MentionRender
```

#### RenderRequest

| Field                  | Type                                    | Required | Notes                                                                |
| ---------------------- | --------------------------------------- | -------- | -------------------------------------------------------------------- |
| `occurrence`           | [MentionOccurrence](#mentionoccurrence) | required | —                                                                    |
| `reader`               | [Searcher](#searcher)                   | required | —                                                                    |
| `scope`                | [MentionScope](#mentionscope)           | required | —                                                                    |
| `standingNow`          | [IdentityStanding](#identitystanding)   | required | —                                                                    |
| `discoverableToReader` | `boolean`                               | required | Whether this READER may learn the subject exists.                    |
| `historicalLabel`      | `string \| null`                        | required | A name the host can still supply for somebody who has left, or null. |

#### RESOLUTION_DEPENDENCIES

Values: `nothing`, `membership`, `the-object`, `the-instant`

#### RESOLUTION_DEPENDS_ON

The axis, as data.

#### RESOLUTION_REFUSALS

Values: `kind-not-permitted`, `kind-not-resolvable`, `fan-out-over-the-ceiling`

#### ResolutionDependency

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

#### ResolutionRefusal

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

#### ResolutionRequest

| Field              | Type                                                                                                                                                                           | Required | Notes                                                                                                                                                                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `typedText`        | `string`                                                                                                                                                                       | required | —                                                                                                                                                                                                                                                                        |
| `claimed`          | `MentionReference \| null` — [MentionReference](#mentionreference)                                                                                                             | required | What the client claims this text refers to — from the picker, from pasted markup, or from an API caller who typed it by hand. Untrusted by construction: the whole of decision 1 is that this field and a picker result are indistinguishable here, so both are checked. |
| `scope`            | [MentionScope](#mentionscope)                                                                                                                                                  | required | —                                                                                                                                                                                                                                                                        |
| `author`           | [Searcher](#searcher)                                                                                                                                                          | required | —                                                                                                                                                                                                                                                                        |
| `directory`        | `readonly DirectoryEntry[]` — [DirectoryEntry](#directoryentry)                                                                                                                | required | —                                                                                                                                                                                                                                                                        |
| `at`               | [Instant](./identity.md#instant)                                                                                                                                               | required | —                                                                                                                                                                                                                                                                        |
| `deriveRecipients` | `(reference: MentionReference, at: Instant) => readonly ActorId[]` — [ActorId](./identity.md#actorid), [Instant](./identity.md#instant), [MentionReference](#mentionreference) | required | How the host derives a group's members at an instant.                                                                                                                                                                                                                    |

#### resolveMention

Resolve one occurrence, under the AUTHOR's scope, at submission.

```ts
resolveMention(request: ResolutionRequest): MentionResolution
```

#### responseDifferences

Which observable fields two responses disagree on, as channel names.

```ts
responseDifferences(a: SearchResponse, b: SearchResponse): readonly DisclosureChannel[]
```

#### SEARCH_FAULTS

Values: `candidate-outside-the-searchers-tenant`,
`candidate-outside-the-searchers-workspace`,
`candidate-of-a-kind-the-policy-forbids`,
`candidate-who-cannot-read-the-target`,
`searcher-who-cannot-read-the-target-was-served`, `erased-identity-offered`,
`thread-wider-than-the-target-permits`

#### SEARCH_PLANS

Values: `predicate-in-query`, `retrieve-then-filter`

#### Searcher

The actor doing the searching, and the scopes they hold.

| Field           | Type                               | Required | Notes                                          |
| --------------- | ---------------------------------- | -------- | ---------------------------------------------- |
| `actor`         | [ActorRef](./identity.md#actorref) | required | —                                              |
| `tenant`        | [TenantId](./identity.md#tenantid) | required | —                                              |
| `workspaces`    | `readonly string[]`                | required | —                                              |
| `canReadTarget` | `boolean`                          | required | Whether this actor may read the target at all. |

#### SearchFault

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

#### searchFaults

The negative tests S8.4.b asks for, over a directory a host actually served.

```ts
searchFaults(scope: MentionScope, searcher: Searcher, served: readonly DirectoryEntry[]): readonly MentionFinding[]
```

#### searchIdentities

The search, and the property is that its result is a function ONLY of the
visible set.

```ts
searchIdentities(request: SearchRequest): SearchResponse
```

#### SearchPlan

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

#### SearchRequest

| Field          | Type                                                            | Required | Notes                                                |
| -------------- | --------------------------------------------------------------- | -------- | ---------------------------------------------------- |
| `scope`        | [MentionScope](#mentionscope)                                   | required | —                                                    |
| `searcher`     | [Searcher](#searcher)                                           | required | —                                                    |
| `directory`    | `readonly DirectoryEntry[]` — [DirectoryEntry](#directoryentry) | required | —                                                    |
| `query`        | `string`                                                        | required | —                                                    |
| `limit`        | `number`                                                        | required | —                                                    |
| `avatars`      | `AvatarSession \| null` — [AvatarSession](#avatarsession)       | required | —                                                    |
| `latencyClass` | `string \| null`                                                | optional | Filled from a real measurement by the host, or null. |

#### SearchResponse

Everything a caller can observe about a search.

| Field            | Type                                                         | Required | Notes                                                                                                                     |
| ---------------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `results`        | `readonly CandidateView[]` — [CandidateView](#candidateview) | required | —                                                                                                                         |
| `total`          | `number \| null`                                             | required | How many matched, AFTER the visibility predicate — or null when the deployment withholds it, which is also a fine answer. |
| `truncated`      | `boolean`                                                    | required | —                                                                                                                         |
| `errorCode`      | `string \| null`                                             | required | —                                                                                                                         |
| `prefixTooShort` | `boolean`                                                    | required | —                                                                                                                         |
| `latencyClass`   | `string \| null`                                             | required | —                                                                                                                         |

#### SentDelivery

A delivery a host says it actually sent, for the adversarial pass over it.

| Field                    | Type                                                          | Required | Notes                                                          |
| ------------------------ | ------------------------------------------------------------- | -------- | -------------------------------------------------------------- |
| `key`                    | `string`                                                      | required | —                                                              |
| `recipient`              | [ActorId](./identity.md#actorid)                              | required | —                                                              |
| `recipientCanReadTarget` | `boolean`                                                     | required | —                                                              |
| `targetState`            | `'live' \| 'deleted' \| 'erased'`                             | required | —                                                              |
| `sourceContext`          | `string \| null`                                              | required | —                                                              |
| `locale`                 | `string`                                                      | required | —                                                              |
| `authorLocale`           | `string`                                                      | required | —                                                              |
| `localeSource`           | `'the-recipient' \| 'the-author' \| 'the-deployment-default'` | required | Where the rendered locale came from.                           |
| `collapsedIntoADigest`   | `boolean`                                                     | required | —                                                              |
| `retraction`             | `'withdrawn' \| 'deleted' \| null`                            | required | For a retraction: what the host did to the existing reference. |

#### sentDeliveryFaults

The check over what was sent, which is a different question from what was
planned.

```ts
sentDeliveryFaults(sent: readonly SentDelivery[]): readonly MentionFinding[]
```

#### summarizeMentions

```ts
summarizeMentions(occurrences: readonly MentionOccurrence[]): MentionSummary
```

#### TOTAL_SOURCES

Values: `after-the-filter`, `before-the-filter`, `withheld`

#### TotalSource

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

#### UNRESOLVED_RENDERS

Values: `the-literal-text`, `a-name-looked-up-from-the-reference`,
`an-error-naming-the-reference`

#### UnresolvedRender

```ts
(typeof UNRESOLVED_RENDERS)[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 |
| ---------------------------------------------------- | -------------- | ----- |
| `DirectoryEntry.tenant`                              | `TenantId`     | —     |
| `DiscoverySurface.avatarServedWithinTheMentionScope` | `boolean`      | —     |
| `MentionReference.tenant`                            | `TenantId`     | —     |
| `MentionScope.tenant`                                | `TenantId`     | —     |
| `PinnedRecipient.actorId`                            | `ActorId`      | —     |
| `RecipientContext.actorId`                           | `ActorId`      | —     |
| `RenderRequest.scope`                                | `MentionScope` | —     |
| `ResolutionRequest.scope`                            | `MentionScope` | —     |
| `Searcher.actor`                                     | `ActorRef`     | —     |
| `Searcher.tenant`                                    | `TenantId`     | —     |
| `SearchRequest.scope`                                | `MentionScope` | —     |

## Idempotency and concurrency

Not applicable: nothing on this page is retried or applied twice: these are
declarations, not operations.

## Pagination

| Symbol                     | Type     | Notes                                                                     |
| -------------------------- | -------- | ------------------------------------------------------------------------- |
| `MentionOccurrence.offset` | `number` | Where in the body it sits. Decision 6 needs a position, not just a token. |

## State and failure

| Symbol                                             | Type                           | Notes                                                 |
| -------------------------------------------------- | ------------------------------ | ----------------------------------------------------- | --------- | --- |
| `DeliveryContext.commentState`                     | `CommentState`                 | —                                                     |
| `DeliveryContext.targetState`                      | `'live'                        | 'deleted'                                             | 'erased'` | —   |
| `DiscoverySurface.missAndConcealmentAreOneOutcome` | `boolean`                      | Whether a miss and a concealment produce one outcome. |
| `MentionAcknowledgement.refused`                   | `readonly ResolutionRefusal[]` | —                                                     |
| `OccurrenceContext.commentState`                   | `CommentState`                 | —                                                     |
| `OccurrenceContext.targetState`                    | `'live'                        | 'deleted'                                             | 'erased'` | —   |
| `RESOLUTION_REFUSALS`                              | `enumeration`                  | —                                                     |
| `ResolutionRefusal`                                | `type`                         | —                                                     |
| `SearchResponse.errorCode`                         | `string                        | null`                                                 | —         |
| `SentDelivery.targetState`                         | `'live'                        | 'deleted'                                             | 'erased'` | —   |

## Compatibility

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

## Deprecation

| Symbol             | Type          | Notes |
| ------------------ | ------------- | ----- |
| `LIFECYCLE_FAULTS` | `enumeration` | —     |
| `LifecycleFault`   | `type`        | —     |
| `lifecycleFaults`  | `function`    | —     |

## Evidence

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