Why presence is the one record in this kit that is allowed to vanish without anybody ending it, why being findable in a directory does not make somebody watchable, how a selection is coarsened for a reader who may not see where it points, what tells a reconnect apart from a second tab, and where an expired session comes back to life as a metric label.
Generated from libs/oshun/workbench-kit/src/collaborator-presence.ts by
node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs. Ledger:
S8.6. Do not edit by hand.
Summary#
src/collaborator-presence.ts
| Entry point | Runtime class | Authorized by |
|---|---|---|
@oshun/workbench-kit/collaborator-presence |
contract |
S8.6 |
Exports#
| Symbol | Kind | Summary |
|---|---|---|
| applyLifecycle | function | Apply one lifecycle event, returning the new session set and what left. |
| ClientEndpoint | interface | The device and tab, which is the level a reconnect PRESERVES. |
| coarser | function | — |
| COLLABORATOR_PRESENCE_FAULTS | constant | Every fault this module can report. |
| CollaboratorPaint | interface | A collaborator's paint, as a renderer reports it. |
| CollaboratorPresenceFault | type | — |
| compositedTextContrast | function | The text contrast that actually reaches the reader. |
| containerBucketFor | function | The bucket size for a time base, in that base's own units. |
| DeclaredExpiryRecord | interface | A record a host wrote when a session expired, as declared for checking. |
| DeclaredWrite | interface | A write a host declares it performs when presence changes. |
| DEFAULT_SERIES_BUDGET | constant | The cardinality a presence metric may declare. |
| degradeAnchor | function | Reduce an anchor to the precision a viewer is permitted, or drop it. |
| DEPARTURE_CAUSES | enumeration | Why a participant is no longer in the room. |
| DepartureCause | type | — |
| departureNotice | function | What each audience is told when somebody leaves. |
| distinguishingPresenceCues | function | Which cues actually tell two collaborators apart. |
| DURABLE_SURFACES | enumeration | The durable surfaces presence must not reach. |
| DurableSurface | type | — |
| endpointKey | function | — |
| ExpiryReconciliation | interface | What a sweep may say about a session it stopped hearing from. |
| expiryRecordFaults | function | — |
| EXPOSURE_REASONS | enumeration | — |
| ExposureDecision | interface | — |
| exposureFor | function | The join of two permissions, refusing to derive the second from the first. |
| ExposureReason | type | — |
| hasOutlivedItsLease | function | Whether a session is past the lease it was granted. |
| LabelDeclaration | interface | A metric label, with the size of the domain it is drawn from. |
| LARGE_TEXT_CONTRAST_FLOOR | constant | — |
| LEASE_FAULTS | enumeration | — |
| LeaseFault | type | — |
| LeasePolicy | interface | The lease, as data. |
| leasePolicyFaults | function | — |
| LIFECYCLE_EVENTS | enumeration | What has happened to a connection. |
| LIFECYCLE_FAULTS | enumeration | — |
| LifecycleEvent | type | — |
| LifecycleFault | type | — |
| lifecycleFaults | function | The transition properties, checked against a before/after pair. |
| LifecycleInput | interface | — |
| LifecycleObservation | interface | — |
| LifecycleOutcome | interface | — |
| MetricDeclaration | interface | — |
| MIN_HEARTBEATS_PER_LEASE | constant | — |
| MINTING_FAULTS | enumeration | — |
| MintingFault | type | — |
| mintingFaults | function | Minting checks over a set of sessions, live and historical. |
| narrower | function | The narrower (more private) of two exposures. |
| NON_TEXT_CONTRAST_FLOOR | constant | — |
| OPERATIONAL_RETENTION_DAYS | constant | How long presence telemetry may be kept. |
| permittedPrecision | function | The precision a viewer may be told about THIS anchor. |
| PERSISTENCE_FAULTS | enumeration | — |
| PersistenceFault | type | — |
| persistenceFaults | function | — |
| PRESENCE_EXPOSURES | enumeration | How much of a person a viewer is told, from most to least. |
| PRESENCE_STANDINGS | enumeration | What the SERVER concludes about a session, from its own clock. |
| PresenceExposure | type | — |
| PresenceFinding | interface | — |
| PresenceLocation | interface | Where in the workbench a session is, and what it has selected. |
| PresenceRenderObservation | interface | — |
| PresenceRoom | interface | The object the room is about. |
| PresenceSession | interface | One connection's presence, as the server holds it. |
| PresenceStanding | type | — |
| PresenceSubject | interface | The subject of a presence disclosure, as the room holds them. |
| PresenceViewer | interface | The viewer a publication decision is being made for. |
| PRESENT_STANDINGS | enumeration | The standings a room may still show a participant for. |
| pseudonymFor | function | A handle that is stable inside one room and means nothing outside it. |
| PUBLICATION_FAULTS | enumeration | — |
| PublicationContext | interface | — |
| PublicationFault | type | — |
| publicationFaults | function | What a room actually sent one viewer, checked against what it was allowed to. |
| publishedIdentity | function | — |
| PublishedIdentity | interface | The identity a room is told about, which is a strictly smaller thing than the actor. |
| PublishedParticipant | interface | One subject as it was actually served to one viewer. |
| PublishedRoom | interface | What one viewer was actually sent for one room. |
| reconcileMissedDisconnects | function | — |
| RENDERING_FAULTS | enumeration | — |
| RenderingFault | type | — |
| renderingFaults | function | — |
| REPORTED_ACTIVITIES | enumeration | What the client says it is doing, as reported. |
| ReportedActivity | type | — |
| RetiredSession | interface | A session that has left the room, and when the server last saw it. |
| ROOM_ACTOR_KINDS | enumeration | The kinds of actor that may appear in a room at all. |
| roomRoster | function | — |
| rosterCountFaults | function | The roster check a host's own count is measured against. |
| RosterEntry | interface | The room, counted the way a person would count it. |
| sameAnchor | function | Structural equality for anchors, used to compare served against permitted. |
| SELECTION_PRECISIONS | enumeration | How precisely a viewer may be told where somebody is. |
| SelectionPrecision | type | — |
| seriesCardinality | function | The number of time series a metric declares, which is the product. |
| SESSION_SCHEMA_FAULTS | enumeration | — |
| sessionIdDisclosesSubject | function | Whether a session id discloses who its subject is. |
| SessionSchemaFault | type | — |
| sessionSchemaFaults | function | The checks that can be made against one session record alone. |
| standingAt | function | What the server concludes about a session at an instant it is given. |
| SubjectPresencePolicy | interface | What the deployment has decided about being seen, per subject. |
| TELEMETRY_FAULTS | enumeration | — |
| TelemetryFault | type | — |
| telemetryFaults | function | — |
| TEMPORAL_CONTAINER_FLICKS | constant | How coarse a temporal position becomes at container precision, in flicks. |
| TEXT_CONTRAST_FLOOR | constant | The contrast floors this module measures against. |
| UnobservedReader | interface | A role whose reading must not be visible, declared by the deployment. |
| ViewerStructureAccess | interface | What the viewer may see of the object's structure. |
Shapes#
applyLifecycle#
Apply one lifecycle event, returning the new session set and what left.
applyLifecycle(input: LifecycleInput): LifecycleOutcome
ClientEndpoint#
The device and tab, which is the level a reconnect PRESERVES.
| Field | Type | Required | Notes |
|---|---|---|---|
deviceId |
string |
required | — |
tabId |
string |
required | — |
coarser#
coarser(first: SelectionPrecision, second: SelectionPrecision): SelectionPrecision
COLLABORATOR_PRESENCE_FAULTS#
Every fault this module can report.
CollaboratorPaint#
A collaborator's paint, as a renderer reports it.
| Field | Type | Required | Notes |
|---|---|---|---|
subjectId |
ActorId | required | — |
label |
string |
required | The label shown, or the pseudonym. Empty when nothing is shown. |
colour |
Srgb | required | — |
highlightAlpha |
number |
required | 0..1. The alpha the selection wash is drawn at. |
background |
Srgb | required | The page under the wash. |
ink |
Srgb | required | The authored text drawn over the wash. |
largeText |
boolean |
required | — |
cues |
readonly StatusCueReading[] — StatusCueReading |
required | The non-colour channels this collaborator is separated on. |
labelOccludesCaret |
boolean |
required | Whether the caret label is drawn over the insertion point. |
CollaboratorPresenceFault#
| SessionSchemaFault
| MintingFault
| PublicationFault
| LifecycleFault
| LeaseFault
| RenderingFault
| PersistenceFault
| TelemetryFault
compositedTextContrast#
The text contrast that actually reaches the reader.
compositedTextContrast(paint: CollaboratorPaint): number
containerBucketFor#
The bucket size for a time base, in that base's own units.
containerBucketFor(timeBase: TimeBase): number
DeclaredExpiryRecord#
A record a host wrote when a session expired, as declared for checking.
| Field | Type | Required | Notes |
|---|---|---|---|
sessionId |
string |
required | — |
actor |
ActorRef | null — ActorRef |
required | — |
departedAt |
Instant | null — Instant |
required | — |
lastSeenAt |
Instant | null — Instant |
required | — |
durable |
boolean |
required | Whether the host persisted this where an audit reader can find it. |
decidedFromClientInstant |
boolean |
required | Whether the value used to decide expiry came from the client. |
observed |
boolean |
required | — |
DeclaredWrite#
A write a host declares it performs when presence changes.
| Field | Type | Required | Notes |
|---|---|---|---|
surface |
DurableSurface | 'presence-cache' — DurableSurface |
required | — |
field |
string |
required | — |
entity |
string | null |
required | The entity the field sits on, for a durable surface. |
carriesSubjectIdentity |
boolean |
required | — |
carriesLocation |
boolean |
required | — |
DEFAULT_SERIES_BUDGET#
The cardinality a presence metric may declare.
Value: 10_000
degradeAnchor#
Reduce an anchor to the precision a viewer is permitted, or drop it.
degradeAnchor(anchor: StableAnchor, precision: SelectionPrecision, hierarchyDepth = 1): StableAnchor | null
DEPARTURE_CAUSES#
Why a participant is no longer in the room.
Values: closed, logged-out, lease-expired, superseded,
permission-lost, object-deleted, tenant-departed
DepartureCause#
(typeof DEPARTURE_CAUSES)[number];
departureNotice#
What each audience is told when somebody leaves.
departureNotice(cause: DepartureCause, recipient: 'room' | 'subject'): string
distinguishingPresenceCues#
Which cues actually tell two collaborators apart.
distinguishingPresenceCues(member: CollaboratorPaint, others: readonly CollaboratorPaint[]): readonly StatusCue[]
DURABLE_SURFACES#
The durable surfaces presence must not reach.
Values: authored-state, revision, audit-event, search-index, export,
backup, notification
DurableSurface#
(typeof DURABLE_SURFACES)[number];
endpointKey#
endpointKey(endpoint: ClientEndpoint): string
ExpiryReconciliation#
What a sweep may say about a session it stopped hearing from.
| Field | Type | Required | Notes |
|---|---|---|---|
sessionId |
string |
required | — |
actorId |
ActorId | required | — |
lastSeenAt |
Instant | required | The last heartbeat the SERVER stamped. Not a departure. |
sweptAt |
Instant | required | When the sweep ran. |
unheardForSeconds |
number |
required | How long the gap was, in seconds, at the moment of the sweep. |
expiryRecordFaults#
expiryRecordFaults(records: readonly DeclaredExpiryRecord[], sessions: readonly PresenceSession[], now: Instant, policy: LeasePolicy): readonly PresenceFinding[]
EXPOSURE_REASONS#
Values: viewer-cannot-read-the-object, subject-outside-the-viewers-tenant,
subject-not-discoverable-by-this-viewer, subject-reads-without-being-seen,
subject-withheld-consent, object-class-forbids-a-room,
workspace-does-not-overlap, allowed
ExposureDecision#
| Field | Type | Required | Notes |
|---|---|---|---|
exposure |
PresenceExposure | required | — |
reason |
ExposureReason | required | — |
exposureFor#
The join of two permissions, refusing to derive the second from the first.
exposureFor(viewer: PresenceViewer, subject: PresenceSubject, room: PresenceRoom, policy: SubjectPresencePolicy | null, unobserved: readonly UnobservedReader[]): ExposureDecision
ExposureReason#
(typeof EXPOSURE_REASONS)[number];
hasOutlivedItsLease#
Whether a session is past the lease it was granted.
hasOutlivedItsLease(session: PresenceSession, now: Instant): boolean
LabelDeclaration#
A metric label, with the size of the domain it is drawn from.
| Field | Type | Required | Notes |
|---|---|---|---|
name |
string |
required | — |
distinctValues |
number |
required | — |
identifies |
'actor' | 'session' | 'object' | 'tenant' | 'bucket' | 'none' |
required | — |
LARGE_TEXT_CONTRAST_FLOOR#
Value: 3
LEASE_FAULTS#
Values: lease-shorter-than-two-heartbeats, grace-longer-than-the-lease,
non-positive-interval, expiry-computed-from-a-client-supplied-instant,
expired-session-served-as-live, server-clock-ran-backwards,
absence-reported-as-a-departure-instant,
expiry-recorded-as-a-durable-event-with-an-actor,
sweep-claimed-a-session-it-did-not-observe
LeaseFault#
(typeof LEASE_FAULTS)[number];
LeasePolicy#
The lease, as data.
| Field | Type | Required | Notes |
|---|---|---|---|
heartbeatSeconds |
number |
required | — |
leaseSeconds |
number |
required | — |
graceSeconds |
number |
required | — |
leasePolicyFaults#
leasePolicyFaults(policy: LeasePolicy): readonly PresenceFinding[]
LIFECYCLE_EVENTS#
What has happened to a connection.
Values: opened, heartbeat, reconnected, backgrounded, foregrounded,
closed, logged-out, permission-lost, object-deleted, tenant-departed
LIFECYCLE_FAULTS#
Values: heartbeat-revived-an-expired-session,
reconnect-counted-as-a-second-participant,
tab-close-removed-an-actor-who-is-still-present,
session-replaced-without-retiring-the-old-connection,
subscription-outlived-the-permission-that-opened-it,
departure-cause-disclosed-to-the-room,
departure-cause-withheld-from-the-subject, deleted-object-still-has-a-room,
roster-counted-sessions-rather-than-people
LifecycleEvent#
(typeof LIFECYCLE_EVENTS)[number];
LifecycleFault#
(typeof LIFECYCLE_FAULTS)[number];
lifecycleFaults#
The transition properties, checked against a before/after pair.
lifecycleFaults(observation: LifecycleObservation): readonly PresenceFinding[]
LifecycleInput#
| Field | Type | Required | Notes |
|---|---|---|---|
sessions |
readonly PresenceSession[] — PresenceSession |
required | — |
event |
LifecycleEvent | required | — |
sessionId |
string | null |
required | The connection the event is about, for connection-scoped events. |
endpoint |
ClientEndpoint | null — ClientEndpoint |
required | The endpoint reconnecting, for reconnected. |
actorId |
ActorId | null — ActorId |
required | — |
objectId |
string | null |
required | — |
at |
Instant | required | SERVER stamp for this event. |
mintedSessionId |
string | null |
required | The connection id minted for a reconnected. |
LifecycleObservation#
| Field | Type | Required | Notes |
|---|---|---|---|
before |
readonly PresenceSession[] — PresenceSession |
required | — |
input |
LifecycleInput | required | — |
outcome |
LifecycleOutcome | required | — |
roomNotices |
ReadonlyMap<string, string> |
required | What the room was told about each departure, by session id. |
subjectNotices |
ReadonlyMap<string, string> |
required | What the subject was told, by session id. |
LifecycleOutcome#
| Field | Type | Required | Notes |
|---|---|---|---|
sessions |
readonly PresenceSession[] — PresenceSession |
required | — |
retired |
readonly RetiredSession[] — RetiredSession |
required | — |
MetricDeclaration#
| Field | Type | Required | Notes |
|---|---|---|---|
name |
string |
required | — |
labels |
readonly LabelDeclaration[] — LabelDeclaration |
required | — |
retentionDays |
number |
required | — |
MIN_HEARTBEATS_PER_LEASE#
Value: 2
MINTING_FAULTS#
Values: session-id-derived-from-the-actor, session-id-reused-across-actors,
session-id-reused-after-replacement
MintingFault#
(typeof MINTING_FAULTS)[number];
mintingFaults#
Minting checks over a set of sessions, live and historical.
mintingFaults(sessions: readonly PresenceSession[], retired: readonly RetiredSession[] = []): readonly PresenceFinding[]
narrower#
The narrower (more private) of two exposures.
narrower(first: PresenceExposure, second: PresenceExposure): PresenceExposure
NON_TEXT_CONTRAST_FLOOR#
Value: 3
OPERATIONAL_RETENTION_DAYS#
How long presence telemetry may be kept.
Value: 30
permittedPrecision#
The precision a viewer may be told about THIS anchor.
permittedPrecision(anchor: StableAnchor, access: ViewerStructureAccess): SelectionPrecision
PERSISTENCE_FAULTS#
Values: presence-written-to-authored-state,
presence-written-to-the-audit-log, presence-field-on-a-durable-entity,
presence-carried-into-an-export, presence-carried-into-a-notification
PersistenceFault#
(typeof PERSISTENCE_FAULTS)[number];
persistenceFaults#
persistenceFaults(writes: readonly DeclaredWrite[]): readonly PresenceFinding[]
PRESENCE_EXPOSURES#
How much of a person a viewer is told, from most to least.
Values: named, pseudonymous, counted, hidden
PRESENCE_STANDINGS#
What the SERVER concludes about a session, from its own clock.
Values: live, stale, expired, superseded, revoked, closed
PresenceExposure#
(typeof PRESENCE_EXPOSURES)[number];
PresenceFinding#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
CollaboratorPresenceFault | required | — |
subject |
string |
required | The session, actor, room, paint or metric the finding is about. |
detail |
string |
required | — |
PresenceLocation#
Where in the workbench a session is, and what it has selected.
| Field | Type | Required | Notes |
|---|---|---|---|
objectId |
string |
required | — |
revisionSeen |
RevisionRef | required | — |
selection |
StableAnchor | null — StableAnchor |
required | Null when the client is in the object but has selected nothing. |
PresenceRenderObservation#
| Field | Type | Required | Notes |
|---|---|---|---|
paints |
readonly CollaboratorPaint[] — CollaboratorPaint |
required | — |
palette |
ContractPalette | required | — |
announcements |
number |
required | How many times the live region announced in the observed window. |
transitions |
number |
required | How many join/leave transitions occurred in that window. |
caretContrast |
number |
required | The caret indicator's own colour against the page. |
PresenceRoom#
The object the room is about.
| Field | Type | Required | Notes |
|---|---|---|---|
objectId |
string |
required | — |
tenant |
TenantId | required | — |
workspace |
string | null |
required | — |
sensitivity |
readonly SensitivityClass[] — SensitivityClass |
required | — |
PresenceSession#
One connection's presence, as the server holds it.
| Field | Type | Required | Notes |
|---|---|---|---|
sessionId |
string |
required | Minted per connection. Replaced on reconnect; see . |
actor |
ActorRef | required | — |
tenant |
TenantId | required | — |
workspace |
string | null |
required | — |
endpoint |
ClientEndpoint | required | — |
location |
PresenceLocation | required | — |
openedAt |
Instant | required | SERVER. When this connection was accepted. |
lastHeartbeatAt |
Instant | required | SERVER. The stamp of the most recent heartbeat actually received. |
reportedAt |
Instant | null — Instant |
required | CLIENT. What the client believed the time was. Evidence, never input. |
reported |
ReportedActivity | required | — |
leaseSeconds |
number |
required | The lease this session was granted, in seconds. |
PresenceStanding#
(typeof PRESENCE_STANDINGS)[number];
PresenceSubject#
The subject of a presence disclosure, as the room holds them.
| Field | Type | Required | Notes |
|---|---|---|---|
actorId |
ActorId | required | — |
tenant |
TenantId | required | — |
workspaces |
readonly string[] |
required | — |
standing |
IdentityStanding | required | — |
PresenceViewer#
The viewer a publication decision is being made for.
| Field | Type | Required | Notes |
|---|---|---|---|
actor |
ActorRef | required | — |
tenant |
TenantId | required | — |
workspaces |
readonly string[] |
required | — |
canReadObject |
boolean |
required | — |
canDiscoverSubject |
boolean |
required | Whether the viewer may discover this subject at all. |
PRESENT_STANDINGS#
The standings a room may still show a participant for.
Values: live, stale
pseudonymFor#
A handle that is stable inside one room and means nothing outside it.
pseudonymFor(subject: ActorId, arrivalOrder: readonly ActorId[]): string | null
PUBLICATION_FAULTS#
Values: presence-derived-from-the-object-permission-alone,
identity-published-to-a-viewer-who-may-not-discover-it,
unobserved-reader-published, count-changed-by-a-hidden-participant,
consent-defaulted-without-a-recorded-answer,
selection-published-above-the-viewers-precision,
selection-anchored-in-a-block-the-viewer-cannot-read,
caret-offset-published-to-a-viewer-without-exact-precision,
pseudonymous-participant-served-without-a-handle,
delegation-grant-in-a-published-identity
PublicationContext#
| Field | Type | Required | Notes |
|---|---|---|---|
room |
PresenceRoom | required | — |
viewer |
PresenceViewer | required | — |
access |
ViewerStructureAccess | required | — |
subjects |
readonly PresenceSubject[] — PresenceSubject |
required | — |
policies |
readonly SubjectPresencePolicy[] — SubjectPresencePolicy |
required | — |
unobserved |
readonly UnobservedReader[] — UnobservedReader |
required | — |
selections |
ReadonlyMap<ActorId, StableAnchor | null> — ActorId, StableAnchor |
required | The authoritative selection per subject, before minimisation. |
served |
PublishedRoom | required | — |
PublicationFault#
(typeof PUBLICATION_FAULTS)[number];
publicationFaults#
What a room actually sent one viewer, checked against what it was allowed to.
publicationFaults(context: PublicationContext): readonly PresenceFinding[]
publishedIdentity#
publishedIdentity(actor: ActorRef): PublishedIdentity | null
PublishedIdentity#
The identity a room is told about, which is a strictly smaller thing than the actor.
| Field | Type | Required | Notes |
|---|---|---|---|
actorId |
ActorId | required | — |
kind |
MentionSubjectKind | required | Reused from mentions.ts rather than restated, because a room and a picker are showing the same directory and a second vocabulary would be the second identity model actors.ts refuses to build. Only human is reachable today — a team does not sit at a document — and the type is the wider one so that a deployment which puts a shared console in a room has somewhere to say so. |
onBehalfOf |
ActorId | null — ActorId |
required | The person whose authority is being used, when that is not the actor. |
PublishedParticipant#
One subject as it was actually served to one viewer.
| Field | Type | Required | Notes |
|---|---|---|---|
exposure |
PresenceExposure | required | — |
identity |
PublishedIdentity | null — PublishedIdentity |
required | — |
pseudonym |
string | null |
required | — |
selection |
StableAnchor | null — StableAnchor |
required | — |
subjectId |
ActorId | required | — |
PublishedRoom#
What one viewer was actually sent for one room.
| Field | Type | Required | Notes |
|---|---|---|---|
viewerId |
ActorId | required | — |
objectId |
string |
required | — |
participants |
readonly PublishedParticipant[] — PublishedParticipant |
required | — |
othersCount |
number |
required | The "and N others" figure, which must not count anybody hidden. |
reconcileMissedDisconnects#
reconcileMissedDisconnects(sessions: readonly PresenceSession[], now: Instant, policy: LeasePolicy): { readonly live: readonly PresenceSession[]; readonly reconciled: readonly ExpiryReconciliation[]; }
RENDERING_FAULTS#
Values: collaborators-separated-by-colour-alone,
collaborator-colour-outside-the-token-contract,
selection-wash-drops-authored-text-below-the-contrast-floor,
caret-indicator-below-the-non-text-contrast-floor,
presence-label-occludes-the-authoring-caret,
colour-reused-without-a-second-channel,
presence-announced-on-every-heartbeat, cue-that-reaches-neither-reader
RenderingFault#
(typeof RENDERING_FAULTS)[number];
renderingFaults#
renderingFaults(observation: PresenceRenderObservation): readonly PresenceFinding[]
REPORTED_ACTIVITIES#
What the client says it is doing, as reported.
Values: interacting, idle, backgrounded
ReportedActivity#
(typeof REPORTED_ACTIVITIES)[number];
RetiredSession#
A session that has left the room, and when the server last saw it.
| Field | Type | Required | Notes |
|---|---|---|---|
sessionId |
string |
required | — |
actorId |
ActorId | required | — |
endpoint |
ClientEndpoint | required | — |
cause |
DepartureCause | required | — |
lastSeenAt |
Instant | required | The last SERVER-observed heartbeat. Not a departure instant. |
ROOM_ACTOR_KINDS#
The kinds of actor that may appear in a room at all.
Values: human, delegated
roomRoster#
roomRoster(sessions: readonly PresenceSession[], objectId: string, now: Instant, policy: LeasePolicy): readonly RosterEntry[]
rosterCountFaults#
The roster check a host's own count is measured against.
rosterCountFaults(sessions: readonly PresenceSession[], objectId: string, now: Instant, policy: LeasePolicy, reportedCount: number): readonly PresenceFinding[]
RosterEntry#
The room, counted the way a person would count it.
| Field | Type | Required | Notes |
|---|---|---|---|
actorId |
ActorId | required | — |
endpoints |
readonly ClientEndpoint[] — ClientEndpoint |
required | — |
sessionIds |
readonly string[] |
required | — |
standing |
PresenceStanding | required | The most present standing across this actor's sessions. |
mostRecentHeartbeatAt |
Instant | required | — |
sameAnchor#
Structural equality for anchors, used to compare served against permitted.
sameAnchor(first: StableAnchor, second: StableAnchor): boolean
SELECTION_PRECISIONS#
How precisely a viewer may be told where somebody is.
Values: exact, container, entity, none
SelectionPrecision#
(typeof SELECTION_PRECISIONS)[number];
seriesCardinality#
The number of time series a metric declares, which is the product.
seriesCardinality(metric: MetricDeclaration): number
SESSION_SCHEMA_FAULTS#
Values: session-of-an-actor-kind-that-cannot-be-in-a-room,
session-for-an-erased-identity, heartbeat-before-the-session-opened,
lease-not-a-positive-number-of-seconds,
client-supplied-instant-used-as-a-server-stamp,
selection-anchored-at-a-revision-the-session-never-loaded,
session-outside-the-tenant-it-claims, endpoint-without-a-tab,
blank-session-identifier
sessionIdDisclosesSubject#
Whether a session id discloses who its subject is.
sessionIdDisclosesSubject(sessionId: string, actor: ActorRef): boolean
SessionSchemaFault#
(typeof SESSION_SCHEMA_FAULTS)[number];
sessionSchemaFaults#
The checks that can be made against one session record alone.
sessionSchemaFaults(session: PresenceSession): readonly PresenceFinding[]
standingAt#
What the server concludes about a session at an instant it is given.
standingAt(session: PresenceSession, now: Instant, policy: LeasePolicy): PresenceStanding
SubjectPresencePolicy#
What the deployment has decided about being seen, per subject.
| Field | Type | Required | Notes |
|---|---|---|---|
actorId |
ActorId | required | — |
consent |
'granted' | 'withheld' | 'unrecorded' |
required | — |
ceiling |
PresenceExposure | required | The most a viewer may ever be told about this subject, whatever else allows. |
TELEMETRY_FAULTS#
Values: metric-labelled-by-the-subject, metric-labelled-by-the-session,
metric-labelled-by-a-single-object, series-cardinality-over-budget,
presence-telemetry-retained-beyond-the-operational-window
TelemetryFault#
(typeof TELEMETRY_FAULTS)[number];
telemetryFaults#
telemetryFaults(metrics: readonly MetricDeclaration[], budget: number = DEFAULT_SERIES_BUDGET): readonly PresenceFinding[]
TEMPORAL_CONTAINER_FLICKS#
How coarse a temporal position becomes at container precision, in flicks.
TEXT_CONTRAST_FLOOR#
The contrast floors this module measures against.
Value: 4.5
UnobservedReader#
A role whose reading must not be visible, declared by the deployment.
| Field | Type | Required | Notes |
|---|---|---|---|
actorId |
ActorId | required | — |
because |
'support' | 'audit' | 'legal-hold' | 'conflict-check' | 'declared-policy' |
required | — |
ViewerStructureAccess#
What the viewer may see of the object's structure.
| Field | Type | Required | Notes |
|---|---|---|---|
readableBlocks |
readonly BlockId[] — BlockId |
required | — |
readableFieldRoots |
readonly string[] |
required | Fields the viewer may see, by first path segment. Empty means all. |
ceiling |
SelectionPrecision | required | The ceiling this viewer is allowed regardless of the anchor. |
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 |
| ------------------------------- | ------------- | ---------------------------------------------------- | ------------- | --- |
| DeclaredExpiryRecord.actor | ActorRef | null | — |
| ExpiryReconciliation.actorId | ActorId | — |
| LifecycleInput.actorId | ActorId | null | — |
| PresenceRoom.tenant | TenantId | — |
| PresenceSession.actor | ActorRef | — |
| PresenceSession.tenant | TenantId | — |
| PresenceSubject.actorId | ActorId | — |
| PresenceSubject.tenant | TenantId | — |
| PresenceViewer.actor | ActorRef | — |
| PresenceViewer.tenant | TenantId | — |
| PublishedIdentity.actorId | ActorId | — |
| RetiredSession.actorId | ActorId | — |
| ROOM_ACTOR_KINDS | enumeration | The kinds of actor that may appear in a room at all. |
| RosterEntry.actorId | ActorId | — |
| SubjectPresencePolicy.actorId | ActorId | — |
| SubjectPresencePolicy.consent | 'granted' | 'withheld' | 'unrecorded' | — |
| UnobservedReader.actorId | ActorId | — |
Idempotency and concurrency#
| Symbol | Type | Notes |
|---|---|---|
PresenceLocation.revisionSeen |
RevisionRef |
— |
Pagination#
Not applicable: nothing on this page returns a collection a caller reads in pages.
State and failure#
| Symbol | Type | Notes |
|---|---|---|
degradeAnchor |
function |
Reduce an anchor to the precision a viewer is permitted, or drop it. |
LifecycleObservation.outcome |
LifecycleOutcome |
— |
Compatibility#
Not applicable: nothing on this page is versioned independently of the package.
Deprecation#
| Symbol | Type | Notes |
|---|---|---|
applyLifecycle |
function |
Apply one lifecycle event, returning the new session set and what left. |
LIFECYCLE_EVENTS |
enumeration |
What has happened to a connection. |
LIFECYCLE_FAULTS |
enumeration |
— |
LifecycleEvent |
type |
— |
LifecycleFault |
type |
— |
lifecycleFaults |
function |
The transition properties, checked against a before/after pair. |
LifecycleOutcome.retired |
readonly RetiredSession[] |
— |
Evidence#
evidence/v1-workbenches/workbench-kit-export-map.jsonlibs/oshun/workbench-kit/src/collaborator-presence.ts