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 | enumeration | — |
| AcknowledgementFault | type | — |
| acknowledgementFaults | function | — |
| AcknowledgementView | interface | What a surface actually put in front of the author. |
| acknowledgeToAuthor | function | — |
| AUDIENCE_NOTE_KEY | constant | The fixed sentence a group mention gets, with no numbers in it. |
| AVATAR_REFERENCES | enumeration | — |
| AvatarReference | type | — |
| AvatarSession | interface | Per-session avatar handles. |
| BODY_REGIONS | enumeration | Where in a body an occurrence sits. |
| BodyRegion | type | — |
| CandidateView | interface | — |
| classifyOccurrence | function | The eight cases the item names, decided in one place. |
| DELIVERY_FAULTS | enumeration | — |
| DeliveryContext | interface | — |
| DeliveryFault | type | — |
| DirectoryEntry | interface | One identity the host's directory can offer, with the facts a scope decision needs and nothing else. |
| DISCLOSURE_CHANNELS | enumeration | The seven channels the item names, as data. |
| DisclosureChannel | type | — |
| DISCOVERY_FAULTS | enumeration | — |
| DiscoveryFault | type | — |
| discoveryFaults | function | — |
| DiscoverySurface | interface | What the deployment says it does, for the three channels a value cannot show. |
| DISPOSITION_PERMISSIVENESS | constant | How much each disposition discloses, as data. |
| EDGE_FAULTS | enumeration | — |
| EdgeFault | type | — |
| ERASED_MENTION_LABEL | constant | What an erased mention leaves behind in the prose. |
| GROUP_SUBJECT_KINDS | enumeration | The kinds whose recipients are DERIVED, and therefore have to be pinned. |
| IDENTITY_STANDINGS | enumeration | Where an identity stands NOW. |
| identityResidue | function | What the field-walking erasure sweep cannot see. |
| IdentityStanding | type | — |
| isDiscoverable | function | Whether one identity is discoverable by this searcher in this scope. |
| isGroupKind | function | — |
| issueAvatarRef | function | — |
| LIFECYCLE_FAULTS | enumeration | — |
| LifecycleFault | type | — |
| lifecycleFaults | function | — |
| LifecycleObservation | interface | What a host says it does across a mention's life. |
| MENTION_FAULTS | constant | — |
| MENTION_RENDERS | enumeration | — |
| MENTION_SCHEMA_FAULTS | enumeration | — |
| MENTION_SUBJECT_KINDS | enumeration | What a mention can name. |
| MentionAcknowledgement | interface | — |
| MentionDelivery | interface | — |
| mentionDeliveryKey | function | The idempotency key: one comment, one person, one naming. |
| MentionFault | type | — |
| MentionFinding | interface | — |
| mentionHeadline | function | — |
| MentionOccurrence | interface | — |
| MentionPolicy | interface | What the deployment permits. Supplied by the host; the kit holds no roster. |
| MentionReference | interface | The stored reference: stable, tenant-scoped, and carrying no display data. |
| MentionRender | interface | What a reader is shown, and the reference they are handed with it. |
| MentionRenderKind | type | — |
| MentionResolution | type | The outcome of resolving one occurrence at submission. |
| MentionSchemaFault | type | — |
| mentionSchemaFaults | function | — |
| MentionScope | interface | Where a mention is being made, and what the object permits. |
| MentionSubjectKind | type | — |
| MentionSummary | interface | — |
| MINIMUM_PREFIX_CODE_POINTS | constant | Below this, a prefix matches too much of any directory to be a query. |
| Naming | interface | One naming inside a comment: an occurrence and the people it reaches. |
| newAvatarSession | function | — |
| OCCURRENCE_DISPOSITIONS | enumeration | What happens to one naming, for one person. |
| OCCURRENCE_REASONS | enumeration | — |
| OCCURRENCE_RULE_ORDER | constant | The order the rules run in, as data. |
| OccurrenceCase | interface | — |
| OccurrenceContext | interface | — |
| OccurrenceDisposition | type | — |
| occurrenceFaults | function | Compare what a host did against what the rule says, and report only the cases where the host was MORE permissive. |
| OccurrenceOutcome | interface | — |
| OccurrenceReason | type | — |
| PASTED_TOKEN_PATHS | enumeration | — |
| PastedTokenPath | type | — |
| PinnedRecipient | interface | A person a group mention actually reached, pinned at resolution. |
| planDeliveries | function | Turn one COMMENT's namings into the deliveries they produce. |
| PREFETCH_SETS | enumeration | — |
| PrefetchSet | type | — |
| Probe | interface | — |
| probeForOracle | function | The abuse test: given probes whose ground truth is known, which channel told the attacker which was which? |
| ProbeGroundTruth | type | — |
| RecipientContext | interface | What the recipient's preferences and locale say, from S7.19's vocabulary. |
| renderMention | function | Render one occurrence for one reader. |
| RenderRequest | interface | — |
| RESOLUTION_DEPENDENCIES | enumeration | — |
| RESOLUTION_DEPENDS_ON | constant | The axis, as data. |
| RESOLUTION_REFUSALS | enumeration | — |
| ResolutionDependency | type | — |
| ResolutionRefusal | type | — |
| ResolutionRequest | interface | — |
| resolveMention | function | Resolve one occurrence, under the AUTHOR's scope, at submission. |
| responseDifferences | function | Which observable fields two responses disagree on, as channel names. |
| SEARCH_FAULTS | enumeration | — |
| SEARCH_PLANS | enumeration | — |
| Searcher | interface | The actor doing the searching, and the scopes they hold. |
| SearchFault | type | — |
| searchFaults | function | The negative tests S8.4.b asks for, over a directory a host actually served. |
| searchIdentities | function | The search, and the property is that its result is a function ONLY of the visible set. |
| SearchPlan | type | — |
| SearchRequest | interface | — |
| SearchResponse | interface | Everything a caller can observe about a search. |
| SentDelivery | interface | A delivery a host says it actually sent, for the adversarial pass over it. |
| sentDeliveryFaults | function | The check over what was sent, which is a different question from what was planned. |
| summarizeMentions | function | — |
| TOTAL_SOURCES | enumeration | — |
| TotalSource | type | — |
| UNRESOLVED_RENDERS | enumeration | — |
| 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#
(typeof ACKNOWLEDGEMENT_FAULTS)[number];
acknowledgementFaults#
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#
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#
(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#
(typeof BODY_REGIONS)[number];
CandidateView#
| Field | Type | Required | Notes |
|---|---|---|---|
subjectId |
string |
required | — |
kind |
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.
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 |
required | — |
commentState |
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#
(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 | required | — |
tenant |
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 | 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#
(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#
(typeof DISCOVERY_FAULTS)[number];
discoveryFaults#
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 | required | — |
totalSource |
TotalSource | required | — |
avatarReference |
AvatarReference | required | — |
avatarServedWithinTheMentionScope |
boolean |
required | — |
missAndConcealmentAreOneOutcome |
boolean |
required | Whether a miss and a concealment produce one outcome. |
autocompletePrefetch |
PrefetchSet | required | — |
filteringHappens |
'server' | 'client' |
required | — |
pastedTokenPath |
PastedTokenPath | required | — |
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#
(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.
identityResidue(occurrences: readonly MentionOccurrence[], erasedSubjects: readonly string[], bodyOf: (commentId: string) => string | null): readonly MentionFinding[]
IdentityStanding#
(typeof IDENTITY_STANDINGS)[number];
isDiscoverable#
Whether one identity is discoverable by this searcher in this scope.
isDiscoverable(scope: MentionScope, searcher: Searcher, entry: DirectoryEntry): boolean
isGroupKind#
isGroupKind(kind: MentionSubjectKind): boolean
issueAvatarRef#
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#
(typeof LIFECYCLE_FAULTS)[number];
lifecycleFaults#
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 | required | — |
renderForAReaderWhoMayNotResolve |
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 |
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 | required | — |
kind |
'mention' |
required | — |
disposition |
OccurrenceDisposition | required | — |
reason |
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.
mentionDeliveryKey(commentId: string, recipient: ActorId): string
MentionFault#
| MentionSchemaFault
| SearchFault
| DiscoveryFault
| LifecycleFault
| EdgeFault
| DeliveryFault
| AcknowledgementFault
MentionFinding#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
MentionFault | required | — |
subject |
string |
required | — |
detail |
string |
required | — |
mentionHeadline#
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 | required | — |
typedText |
string |
required | What the author typed, verbatim. |
reference |
MentionReference | null — MentionReference |
required | Null until submission resolves it; null forever if it never did. |
recipients |
readonly PinnedRecipient[] — PinnedRecipient |
required | Empty for human; the pinned fan-out for every group kind. |
authoredBy |
ActorRef | required | — |
createdAt |
Instant | required | — |
MentionPolicy#
What the deployment permits. Supplied by the host; the kit holds no roster.
| Field | Type | Required | Notes |
|---|---|---|---|
permittedKinds |
readonly 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 |
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 | required | — |
subjectId |
string |
required | — |
tenant |
TenantId | required | — |
MentionRender#
What a reader is shown, and the reference they are handed with it.
| Field | Type | Required | Notes |
|---|---|---|---|
render |
MentionRenderKind | required | — |
text |
string |
required | — |
reference |
MentionReference | null — MentionReference |
required | Null unless the reader may resolve this identity. |
MentionRenderKind#
(typeof MENTION_RENDERS)[number];
MentionResolution#
The outcome of resolving one occurrence at submission.
| { 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#
(typeof MENTION_SCHEMA_FAULTS)[number];
mentionSchemaFaults#
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 | required | — |
workspace |
string | null |
required | — |
targetId |
string |
required | — |
threadVisibility |
ThreadVisibility | required | — |
targetMaxVisibility |
ThreadVisibility | required | The widest the target permits, from S8.2's TargetPolicy. |
policy |
MentionPolicy | required | — |
MentionSubjectKind#
(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 |
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 | required | — |
recipients |
readonly RecipientContext[] — RecipientContext |
required | — |
stillPresentInTheBody |
boolean |
required | — |
newAvatarSession#
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 | required | — |
actual |
OccurrenceDisposition | required | What the host actually did. |
OccurrenceContext#
| Field | Type | Required | Notes |
|---|---|---|---|
occurrence |
MentionOccurrence | required | — |
recipient |
ActorId | required | — |
standing |
IdentityStanding | required | — |
recipientCanReadTarget |
boolean |
required | — |
commentState |
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#
(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.
occurrenceFaults(cases: readonly OccurrenceCase[]): readonly MentionFinding[]
OccurrenceOutcome#
| Field | Type | Required | Notes |
|---|---|---|---|
disposition |
OccurrenceDisposition | required | — |
reason |
OccurrenceReason | required | — |
OccurrenceReason#
(typeof OCCURRENCE_REASONS)[number];
PASTED_TOKEN_PATHS#
Values: resolved-under-the-pasters-scope, trusted-as-written
PastedTokenPath#
(typeof PASTED_TOKEN_PATHS)[number];
PinnedRecipient#
A person a group mention actually reached, pinned at resolution.
planDeliveries#
Turn one COMMENT's namings into the deliveries they produce.
planDeliveries(context: DeliveryContext, taxonomy: NotificationTaxonomy): { readonly deliveries: readonly MentionDelivery[]; readonly findings: readonly MentionFinding[]; }
PREFETCH_SETS#
Values: none, the-visible-set, the-tenant-directory
PrefetchSet#
(typeof PREFETCH_SETS)[number];
Probe#
| Field | Type | Required | Notes |
|---|---|---|---|
label |
string |
required | — |
truth |
ProbeGroundTruth | required | — |
response |
SearchResponse | required | — |
probeForOracle#
The abuse test: given probes whose ground truth is known, which channel told the attacker which was which?
probeForOracle(probes: readonly Probe[]): readonly DisclosureChannel[]
ProbeGroundTruth#
'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 | required | — |
standing |
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.
renderMention(request: RenderRequest): MentionRender
RenderRequest#
| Field | Type | Required | Notes |
|---|---|---|---|
occurrence |
MentionOccurrence | required | — |
reader |
Searcher | required | — |
scope |
MentionScope | required | — |
standingNow |
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#
(typeof RESOLUTION_DEPENDENCIES)[number];
ResolutionRefusal#
(typeof RESOLUTION_REFUSALS)[number];
ResolutionRequest#
| Field | Type | Required | Notes |
|---|---|---|---|
typedText |
string |
required | — |
claimed |
MentionReference | null — 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 | required | — |
author |
Searcher | required | — |
directory |
readonly DirectoryEntry[] — DirectoryEntry |
required | — |
at |
Instant | required | — |
deriveRecipients |
(reference: MentionReference, at: Instant) => readonly ActorId[] — ActorId, Instant, MentionReference |
required | How the host derives a group's members at an instant. |
resolveMention#
Resolve one occurrence, under the AUTHOR's scope, at submission.
resolveMention(request: ResolutionRequest): MentionResolution
responseDifferences#
Which observable fields two responses disagree on, as channel names.
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 | required | — |
tenant |
TenantId | required | — |
workspaces |
readonly string[] |
required | — |
canReadTarget |
boolean |
required | Whether this actor may read the target at all. |
SearchFault#
(typeof SEARCH_FAULTS)[number];
searchFaults#
The negative tests S8.4.b asks for, over a directory a host actually served.
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.
searchIdentities(request: SearchRequest): SearchResponse
SearchPlan#
(typeof SEARCH_PLANS)[number];
SearchRequest#
| Field | Type | Required | Notes |
|---|---|---|---|
scope |
MentionScope | required | — |
searcher |
Searcher | required | — |
directory |
readonly DirectoryEntry[] — DirectoryEntry |
required | — |
query |
string |
required | — |
limit |
number |
required | — |
avatars |
AvatarSession | null — 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 |
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 | 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.
sentDeliveryFaults(sent: readonly SentDelivery[]): readonly MentionFinding[]
summarizeMentions#
summarizeMentions(occurrences: readonly MentionOccurrence[]): MentionSummary
TOTAL_SOURCES#
Values: after-the-filter, before-the-filter, withheld
TotalSource#
(typeof TOTAL_SOURCES)[number];
UNRESOLVED_RENDERS#
Values: the-literal-text, a-name-looked-up-from-the-reference,
an-error-naming-the-reference
UnresolvedRender#
(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.jsonlibs/oshun/workbench-kit/src/mentions.ts