# Collaborator presence

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](#applylifecycle)                             | function    | Apply one lifecycle event, returning the new session set and what left.              |
| [ClientEndpoint](#clientendpoint)                             | interface   | The device and tab, which is the level a reconnect PRESERVES.                        |
| [coarser](#coarser)                                           | function    | —                                                                                    |
| [COLLABORATOR_PRESENCE_FAULTS](#collaborator_presence_faults) | constant    | Every fault this module can report.                                                  |
| [CollaboratorPaint](#collaboratorpaint)                       | interface   | A collaborator's paint, as a renderer reports it.                                    |
| [CollaboratorPresenceFault](#collaboratorpresencefault)       | type        | —                                                                                    |
| [compositedTextContrast](#compositedtextcontrast)             | function    | The text contrast that actually reaches the reader.                                  |
| [containerBucketFor](#containerbucketfor)                     | function    | The bucket size for a time base, in that base's own units.                           |
| [DeclaredExpiryRecord](#declaredexpiryrecord)                 | interface   | A record a host wrote when a session expired, as declared for checking.              |
| [DeclaredWrite](#declaredwrite)                               | interface   | A write a host declares it performs when presence changes.                           |
| [DEFAULT_SERIES_BUDGET](#default_series_budget)               | constant    | The cardinality a presence metric may declare.                                       |
| [degradeAnchor](#degradeanchor)                               | function    | Reduce an anchor to the precision a viewer is permitted, or drop it.                 |
| [DEPARTURE_CAUSES](#departure_causes)                         | enumeration | Why a participant is no longer in the room.                                          |
| [DepartureCause](#departurecause)                             | type        | —                                                                                    |
| [departureNotice](#departurenotice)                           | function    | What each audience is told when somebody leaves.                                     |
| [distinguishingPresenceCues](#distinguishingpresencecues)     | function    | Which cues actually tell two collaborators apart.                                    |
| [DURABLE_SURFACES](#durable_surfaces)                         | enumeration | The durable surfaces presence must not reach.                                        |
| [DurableSurface](#durablesurface)                             | type        | —                                                                                    |
| [endpointKey](#endpointkey)                                   | function    | —                                                                                    |
| [ExpiryReconciliation](#expiryreconciliation)                 | interface   | What a sweep may say about a session it stopped hearing from.                        |
| [expiryRecordFaults](#expiryrecordfaults)                     | function    | —                                                                                    |
| [EXPOSURE_REASONS](#exposure_reasons)                         | enumeration | —                                                                                    |
| [ExposureDecision](#exposuredecision)                         | interface   | —                                                                                    |
| [exposureFor](#exposurefor)                                   | function    | The join of two permissions, refusing to derive the second from the first.           |
| [ExposureReason](#exposurereason)                             | type        | —                                                                                    |
| [hasOutlivedItsLease](#hasoutliveditslease)                   | function    | Whether a session is past the lease it was granted.                                  |
| [LabelDeclaration](#labeldeclaration)                         | interface   | A metric label, with the size of the domain it is drawn from.                        |
| [LARGE_TEXT_CONTRAST_FLOOR](#large_text_contrast_floor)       | constant    | —                                                                                    |
| [LEASE_FAULTS](#lease_faults)                                 | enumeration | —                                                                                    |
| [LeaseFault](#leasefault)                                     | type        | —                                                                                    |
| [LeasePolicy](#leasepolicy)                                   | interface   | The lease, as data.                                                                  |
| [leasePolicyFaults](#leasepolicyfaults)                       | function    | —                                                                                    |
| [LIFECYCLE_EVENTS](#lifecycle_events)                         | enumeration | What has happened to a connection.                                                   |
| [LIFECYCLE_FAULTS](#lifecycle_faults)                         | enumeration | —                                                                                    |
| [LifecycleEvent](#lifecycleevent)                             | type        | —                                                                                    |
| [LifecycleFault](#lifecyclefault)                             | type        | —                                                                                    |
| [lifecycleFaults](#lifecyclefaults)                           | function    | The transition properties, checked against a before/after pair.                      |
| [LifecycleInput](#lifecycleinput)                             | interface   | —                                                                                    |
| [LifecycleObservation](#lifecycleobservation)                 | interface   | —                                                                                    |
| [LifecycleOutcome](#lifecycleoutcome)                         | interface   | —                                                                                    |
| [MetricDeclaration](#metricdeclaration)                       | interface   | —                                                                                    |
| [MIN_HEARTBEATS_PER_LEASE](#min_heartbeats_per_lease)         | constant    | —                                                                                    |
| [MINTING_FAULTS](#minting_faults)                             | enumeration | —                                                                                    |
| [MintingFault](#mintingfault)                                 | type        | —                                                                                    |
| [mintingFaults](#mintingfaults)                               | function    | Minting checks over a set of sessions, live and historical.                          |
| [narrower](#narrower)                                         | function    | The narrower (more private) of two exposures.                                        |
| [NON_TEXT_CONTRAST_FLOOR](#non_text_contrast_floor)           | constant    | —                                                                                    |
| [OPERATIONAL_RETENTION_DAYS](#operational_retention_days)     | constant    | How long presence telemetry may be kept.                                             |
| [permittedPrecision](#permittedprecision)                     | function    | The precision a viewer may be told about THIS anchor.                                |
| [PERSISTENCE_FAULTS](#persistence_faults)                     | enumeration | —                                                                                    |
| [PersistenceFault](#persistencefault)                         | type        | —                                                                                    |
| [persistenceFaults](#persistencefaults)                       | function    | —                                                                                    |
| [PRESENCE_EXPOSURES](#presence_exposures)                     | enumeration | How much of a person a viewer is told, from most to least.                           |
| [PRESENCE_STANDINGS](#presence_standings)                     | enumeration | What the SERVER concludes about a session, from its own clock.                       |
| [PresenceExposure](#presenceexposure)                         | type        | —                                                                                    |
| [PresenceFinding](#presencefinding)                           | interface   | —                                                                                    |
| [PresenceLocation](#presencelocation)                         | interface   | Where in the workbench a session is, and what it has selected.                       |
| [PresenceRenderObservation](#presencerenderobservation)       | interface   | —                                                                                    |
| [PresenceRoom](#presenceroom)                                 | interface   | The object the room is about.                                                        |
| [PresenceSession](#presencesession)                           | interface   | One connection's presence, as the server holds it.                                   |
| [PresenceStanding](#presencestanding)                         | type        | —                                                                                    |
| [PresenceSubject](#presencesubject)                           | interface   | The subject of a presence disclosure, as the room holds them.                        |
| [PresenceViewer](#presenceviewer)                             | interface   | The viewer a publication decision is being made for.                                 |
| [PRESENT_STANDINGS](#present_standings)                       | enumeration | The standings a room may still show a participant for.                               |
| [pseudonymFor](#pseudonymfor)                                 | function    | A handle that is stable inside one room and means nothing outside it.                |
| [PUBLICATION_FAULTS](#publication_faults)                     | enumeration | —                                                                                    |
| [PublicationContext](#publicationcontext)                     | interface   | —                                                                                    |
| [PublicationFault](#publicationfault)                         | type        | —                                                                                    |
| [publicationFaults](#publicationfaults)                       | function    | What a room actually sent one viewer, checked against what it was allowed to.        |
| [publishedIdentity](#publishedidentity)                       | function    | —                                                                                    |
| [PublishedIdentity](#publishedidentity)                       | interface   | The identity a room is told about, which is a strictly smaller thing than the actor. |
| [PublishedParticipant](#publishedparticipant)                 | interface   | One subject as it was actually served to one viewer.                                 |
| [PublishedRoom](#publishedroom)                               | interface   | What one viewer was actually sent for one room.                                      |
| [reconcileMissedDisconnects](#reconcilemisseddisconnects)     | function    | —                                                                                    |
| [RENDERING_FAULTS](#rendering_faults)                         | enumeration | —                                                                                    |
| [RenderingFault](#renderingfault)                             | type        | —                                                                                    |
| [renderingFaults](#renderingfaults)                           | function    | —                                                                                    |
| [REPORTED_ACTIVITIES](#reported_activities)                   | enumeration | What the client says it is doing, as reported.                                       |
| [ReportedActivity](#reportedactivity)                         | type        | —                                                                                    |
| [RetiredSession](#retiredsession)                             | interface   | A session that has left the room, and when the server last saw it.                   |
| [ROOM_ACTOR_KINDS](#room_actor_kinds)                         | enumeration | The kinds of actor that may appear in a room at all.                                 |
| [roomRoster](#roomroster)                                     | function    | —                                                                                    |
| [rosterCountFaults](#rostercountfaults)                       | function    | The roster check a host's own count is measured against.                             |
| [RosterEntry](#rosterentry)                                   | interface   | The room, counted the way a person would count it.                                   |
| [sameAnchor](#sameanchor)                                     | function    | Structural equality for anchors, used to compare served against permitted.           |
| [SELECTION_PRECISIONS](#selection_precisions)                 | enumeration | How precisely a viewer may be told where somebody is.                                |
| [SelectionPrecision](#selectionprecision)                     | type        | —                                                                                    |
| [seriesCardinality](#seriescardinality)                       | function    | The number of time series a metric declares, which is the product.                   |
| [SESSION_SCHEMA_FAULTS](#session_schema_faults)               | enumeration | —                                                                                    |
| [sessionIdDisclosesSubject](#sessioniddisclosessubject)       | function    | Whether a session id discloses who its subject is.                                   |
| [SessionSchemaFault](#sessionschemafault)                     | type        | —                                                                                    |
| [sessionSchemaFaults](#sessionschemafaults)                   | function    | The checks that can be made against one session record alone.                        |
| [standingAt](#standingat)                                     | function    | What the server concludes about a session at an instant it is given.                 |
| [SubjectPresencePolicy](#subjectpresencepolicy)               | interface   | What the deployment has decided about being seen, per subject.                       |
| [TELEMETRY_FAULTS](#telemetry_faults)                         | enumeration | —                                                                                    |
| [TelemetryFault](#telemetryfault)                             | type        | —                                                                                    |
| [telemetryFaults](#telemetryfaults)                           | function    | —                                                                                    |
| [TEMPORAL_CONTAINER_FLICKS](#temporal_container_flicks)       | constant    | How coarse a temporal position becomes at `container` precision, in flicks.          |
| [TEXT_CONTRAST_FLOOR](#text_contrast_floor)                   | constant    | The contrast floors this module measures against.                                    |
| [UnobservedReader](#unobservedreader)                         | interface   | A role whose reading must not be visible, declared by the deployment.                |
| [ViewerStructureAccess](#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.

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

```ts
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](./identity.md#actorid)                                                  | required | —                                                               |
| `label`              | `string`                                                                          | required | The label shown, or the pseudonym. Empty when nothing is shown. |
| `colour`             | [Srgb](./signals.md#srgb)                                                         | required | —                                                               |
| `highlightAlpha`     | `number`                                                                          | required | 0..1. The alpha the selection wash is drawn at.                 |
| `background`         | [Srgb](./signals.md#srgb)                                                         | required | The page under the wash.                                        |
| `ink`                | [Srgb](./signals.md#srgb)                                                         | required | The authored text drawn over the wash.                          |
| `largeText`          | `boolean`                                                                         | required | —                                                               |
| `cues`               | `readonly StatusCueReading[]` — [StatusCueReading](./signals.md#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

```ts
| SessionSchemaFault
| MintingFault
| PublicationFault
| LifecycleFault
| LeaseFault
| RenderingFault
| PersistenceFault
| TelemetryFault
```

#### compositedTextContrast

The text contrast that actually reaches the reader.

```ts
compositedTextContrast(paint: CollaboratorPaint): number
```

#### containerBucketFor

The bucket size for a time base, in that base's own units.

```ts
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](./identity.md#actorref) | required | —                                                                  |
| `departedAt`               | `Instant \| null` — [Instant](./identity.md#instant)    | required | —                                                                  |
| `lastSeenAt`               | `Instant \| null` — [Instant](./identity.md#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](#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.

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

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

#### departureNotice

What each audience is told when somebody leaves.

```ts
departureNotice(cause: DepartureCause, recipient: 'room' | 'subject'): string
```

#### distinguishingPresenceCues

Which cues actually tell two collaborators apart.

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

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

#### endpointKey

```ts
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](./identity.md#actorid) | required | —                                                             |
| `lastSeenAt`        | [Instant](./identity.md#instant) | required | The last heartbeat the SERVER stamped. Not a departure.       |
| `sweptAt`           | [Instant](./identity.md#instant) | required | When the sweep ran.                                           |
| `unheardForSeconds` | `number`                         | required | How long the gap was, in seconds, at the moment of the sweep. |

#### expiryRecordFaults

```ts
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](#presenceexposure) | required | —     |
| `reason`   | [ExposureReason](#exposurereason)     | required | —     |

#### exposureFor

The join of two permissions, refusing to derive the second from the first.

```ts
exposureFor(viewer: PresenceViewer, subject: PresenceSubject, room: PresenceRoom, policy: SubjectPresencePolicy | null, unobserved: readonly UnobservedReader[]): ExposureDecision
```

#### ExposureReason

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

#### hasOutlivedItsLease

Whether a session is past the lease it was granted.

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

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

#### LeasePolicy

The lease, as data.

| Field              | Type     | Required | Notes |
| ------------------ | -------- | -------- | ----- |
| `heartbeatSeconds` | `number` | required | —     |
| `leaseSeconds`     | `number` | required | —     |
| `graceSeconds`     | `number` | required | —     |

#### leasePolicyFaults

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

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

#### LifecycleFault

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

#### lifecycleFaults

The transition properties, checked against a before/after pair.

```ts
lifecycleFaults(observation: LifecycleObservation): readonly PresenceFinding[]
```

#### LifecycleInput

| Field             | Type                                                               | Required | Notes                                                            |
| ----------------- | ------------------------------------------------------------------ | -------- | ---------------------------------------------------------------- |
| `sessions`        | `readonly PresenceSession[]` — [PresenceSession](#presencesession) | required | —                                                                |
| `event`           | [LifecycleEvent](#lifecycleevent)                                  | required | —                                                                |
| `sessionId`       | `string \| null`                                                   | required | The connection the event is about, for connection-scoped events. |
| `endpoint`        | `ClientEndpoint \| null` — [ClientEndpoint](#clientendpoint)       | required | The endpoint reconnecting, for `reconnected`.                    |
| `actorId`         | `ActorId \| null` — [ActorId](./identity.md#actorid)               | required | —                                                                |
| `objectId`        | `string \| null`                                                   | required | —                                                                |
| `at`              | [Instant](./identity.md#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](#presencesession) | required | —                                                           |
| `input`          | [LifecycleInput](#lifecycleinput)                                  | required | —                                                           |
| `outcome`        | [LifecycleOutcome](#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](#presencesession) | required | —     |
| `retired`  | `readonly RetiredSession[]` — [RetiredSession](#retiredsession)    | required | —     |

#### MetricDeclaration

| Field           | Type                                                                  | Required | Notes |
| --------------- | --------------------------------------------------------------------- | -------- | ----- |
| `name`          | `string`                                                              | required | —     |
| `labels`        | `readonly LabelDeclaration[]` — [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

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

#### mintingFaults

Minting checks over a set of sessions, live and historical.

```ts
mintingFaults(sessions: readonly PresenceSession[], retired: readonly RetiredSession[] = []): readonly PresenceFinding[]
```

#### narrower

The narrower (more private) of two exposures.

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

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

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

#### persistenceFaults

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

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

#### PresenceFinding

| Field     | Type                                                    | Required | Notes                                                           |
| --------- | ------------------------------------------------------- | -------- | --------------------------------------------------------------- |
| `kind`    | [CollaboratorPresenceFault](#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](./identity.md#revisionref)                            | required | —                                                               |
| `selection`    | `StableAnchor \| null` — [StableAnchor](./identity.md#stableanchor) | required | Null when the client is in the object but has selected nothing. |

#### PresenceRenderObservation

| Field           | Type                                                                     | Required | Notes                                                            |
| --------------- | ------------------------------------------------------------------------ | -------- | ---------------------------------------------------------------- |
| `paints`        | `readonly CollaboratorPaint[]` — [CollaboratorPaint](#collaboratorpaint) | required | —                                                                |
| `palette`       | [ContractPalette](./signals.md#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](./identity.md#tenantid)                                               | required | —     |
| `workspace`   | `string \| null`                                                                 | required | —     |
| `sensitivity` | `readonly SensitivityClass[]` — [SensitivityClass](./plugin.md#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](./identity.md#actorref)                   | required | —                                                                     |
| `tenant`          | [TenantId](./identity.md#tenantid)                   | required | —                                                                     |
| `workspace`       | `string \| null`                                     | required | —                                                                     |
| `endpoint`        | [ClientEndpoint](#clientendpoint)                    | required | —                                                                     |
| `location`        | [PresenceLocation](#presencelocation)                | required | —                                                                     |
| `openedAt`        | [Instant](./identity.md#instant)                     | required | SERVER. When this connection was accepted.                            |
| `lastHeartbeatAt` | [Instant](./identity.md#instant)                     | required | SERVER. The stamp of the most recent heartbeat actually received.     |
| `reportedAt`      | `Instant \| null` — [Instant](./identity.md#instant) | required | CLIENT. What the client believed the time was. Evidence, never input. |
| `reported`        | [ReportedActivity](#reportedactivity)                | required | —                                                                     |
| `leaseSeconds`    | `number`                                             | required | The lease this session was granted, in seconds.                       |

#### PresenceStanding

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

#### PresenceSubject

The subject of a presence disclosure, as the room holds them.

| Field        | Type                                               | Required | Notes |
| ------------ | -------------------------------------------------- | -------- | ----- |
| `actorId`    | [ActorId](./identity.md#actorid)                   | required | —     |
| `tenant`     | [TenantId](./identity.md#tenantid)                 | required | —     |
| `workspaces` | `readonly string[]`                                | required | —     |
| `standing`   | [IdentityStanding](./mentions.md#identitystanding) | required | —     |

#### PresenceViewer

The viewer a publication decision is being made for.

| Field                | Type                               | Required | Notes                                                |
| -------------------- | ---------------------------------- | -------- | ---------------------------------------------------- |
| `actor`              | [ActorRef](./identity.md#actorref) | required | —                                                    |
| `tenant`             | [TenantId](./identity.md#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.

```ts
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](#presenceroom)                                                                                               | required | —                                                             |
| `viewer`     | [PresenceViewer](#presenceviewer)                                                                                           | required | —                                                             |
| `access`     | [ViewerStructureAccess](#viewerstructureaccess)                                                                             | required | —                                                             |
| `subjects`   | `readonly PresenceSubject[]` — [PresenceSubject](#presencesubject)                                                          | required | —                                                             |
| `policies`   | `readonly SubjectPresencePolicy[]` — [SubjectPresencePolicy](#subjectpresencepolicy)                                        | required | —                                                             |
| `unobserved` | `readonly UnobservedReader[]` — [UnobservedReader](#unobservedreader)                                                       | required | —                                                             |
| `selections` | `ReadonlyMap<ActorId, StableAnchor \| null>` — [ActorId](./identity.md#actorid), [StableAnchor](./identity.md#stableanchor) | required | The authoritative selection per subject, before minimisation. |
| `served`     | [PublishedRoom](#publishedroom)                                                                                             | required | —                                                             |

#### PublicationFault

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

#### publicationFaults

What a room actually sent one viewer, checked against what it was allowed to.

```ts
publicationFaults(context: PublicationContext): readonly PresenceFinding[]
```

#### publishedIdentity

```ts
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](./identity.md#actorid)                       | required | —                                                                                                                                                                                                                                                                                                                                                                                           |
| `kind`       | [MentionSubjectKind](./mentions.md#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](./identity.md#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](#presenceexposure)                                 | required | —     |
| `identity`  | `PublishedIdentity \| null` — [PublishedIdentity](#publishedidentity) | required | —     |
| `pseudonym` | `string \| null`                                                      | required | —     |
| `selection` | `StableAnchor \| null` — [StableAnchor](./identity.md#stableanchor)   | required | —     |
| `subjectId` | [ActorId](./identity.md#actorid)                                      | required | —     |

#### PublishedRoom

What one viewer was actually sent for one room.

| Field          | Type                                                                              | Required | Notes                                                           |
| -------------- | --------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------- |
| `viewerId`     | [ActorId](./identity.md#actorid)                                                  | required | —                                                               |
| `objectId`     | `string`                                                                          | required | —                                                               |
| `participants` | `readonly PublishedParticipant[]` — [PublishedParticipant](#publishedparticipant) | required | —                                                               |
| `othersCount`  | `number`                                                                          | required | The "and N others" figure, which must not count anybody hidden. |

#### reconcileMissedDisconnects

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

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

#### renderingFaults

```ts
renderingFaults(observation: PresenceRenderObservation): readonly PresenceFinding[]
```

#### REPORTED_ACTIVITIES

What the client says it is doing, as reported.

Values: `interacting`, `idle`, `backgrounded`

#### ReportedActivity

```ts
(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](./identity.md#actorid)  | required | —                                                            |
| `endpoint`   | [ClientEndpoint](#clientendpoint) | required | —                                                            |
| `cause`      | [DepartureCause](#departurecause) | required | —                                                            |
| `lastSeenAt` | [Instant](./identity.md#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

```ts
roomRoster(sessions: readonly PresenceSession[], objectId: string, now: Instant, policy: LeasePolicy): readonly RosterEntry[]
```

#### rosterCountFaults

The roster check a host's own count is measured against.

```ts
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](./identity.md#actorid)                                | required | —                                                       |
| `endpoints`             | `readonly ClientEndpoint[]` — [ClientEndpoint](#clientendpoint) | required | —                                                       |
| `sessionIds`            | `readonly string[]`                                             | required | —                                                       |
| `standing`              | [PresenceStanding](#presencestanding)                           | required | The most present standing across this actor's sessions. |
| `mostRecentHeartbeatAt` | [Instant](./identity.md#instant)                                | required | —                                                       |

#### sameAnchor

Structural equality for anchors, used to compare served against permitted.

```ts
sameAnchor(first: StableAnchor, second: StableAnchor): boolean
```

#### SELECTION_PRECISIONS

How precisely a viewer may be told where somebody is.

Values: `exact`, `container`, `entity`, `none`

#### SelectionPrecision

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

#### seriesCardinality

The number of time series a metric declares, which is the product.

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

```ts
sessionIdDisclosesSubject(sessionId: string, actor: ActorRef): boolean
```

#### SessionSchemaFault

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

#### sessionSchemaFaults

The checks that can be made against one session record alone.

```ts
sessionSchemaFaults(session: PresenceSession): readonly PresenceFinding[]
```

#### standingAt

What the server concludes about a session at an instant it is given.

```ts
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](./identity.md#actorid)          | required | —                                                                            |
| `consent` | `'granted' \| 'withheld' \| 'unrecorded'` | required | —                                                                            |
| `ceiling` | [PresenceExposure](#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

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

#### telemetryFaults

```ts
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](./identity.md#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](./identity.md#blockid) | required | —                                                                  |
| `readableFieldRoots` | `readonly string[]`                                     | required | Fields the viewer may see, by first path segment. Empty means all. |
| `ceiling`            | [SelectionPrecision](#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.json`
- `libs/oshun/workbench-kit/src/collaborator-presence.ts`
