Eve library

Mentions

Evidence

Revision 1

On this page

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#

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 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 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#

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 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#

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 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#

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 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.

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

MentionFault#

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

MentionFinding#

Field Type Required Notes
kind 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 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#

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 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#

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 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#

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 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#

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 required —
reason 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 required —
derivedAt 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 required —
response 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 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.

ts
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#

ts
(typeof RESOLUTION_DEPENDENCIES)[number];

ResolutionRefusal#

ts
(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.

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 required —
tenant 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 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.

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