# Anchored comment threads

Whether a comment still points where it pointed after somebody else edited the
document, which of the six things went wrong when it does not, why a build that
has no adapter for an anchor must say so rather than report a deletion, and what
an orphaned thread has to keep so a human can put it back.

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

## Summary

- `src/comment-threads.ts`

| Entry point                            | Runtime class | Authorized by |
| -------------------------------------- | ------------- | ------------- |
| `@oshun/workbench-kit/comment-threads` | `contract`    | S8.2          |

## Exports

| Symbol                                                      | Kind        | Summary                                                                       |
| ----------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------- |
| [ADAPTER_FAULTS](#adapter_faults)                           | enumeration | —                                                                             |
| [AdapterFault](#adapterfault)                               | type        | —                                                                             |
| [adapterForAnchor](#adapterforanchor)                       | function    | Which anchor kinds each thread adapter is allowed to carry.                   |
| [AnchorAdapterDeclaration](#anchoradapterdeclaration)       | interface   | One deployment's adapter for one anchor kind.                                 |
| [AnchorContext](#anchorcontext)                             | interface   | —                                                                             |
| [AnchorEdit](#anchoredit)                                   | type        | One edit, expressed in the coordinate space it acted on.                      |
| [AnchorRegistry](#anchorregistry)                           | interface   | —                                                                             |
| [applyConfidenceThreshold](#applyconfidencethreshold)       | function    | Turn a rebase the caller does not trust into an orphan.                       |
| [buildAnchorRegistry](#buildanchorregistry)                 | function    | —                                                                             |
| [COMMENT_STATES](#comment_states)                           | enumeration | What has happened to one comment.                                             |
| [CommentRecord](#commentrecord)                             | interface   | —                                                                             |
| [CommentState](#commentstate)                               | type        | —                                                                             |
| [completeAdapterSet](#completeadapterset)                   | function    | Every adapter, at a stable identity, resolving and rebasing.                  |
| [CONTENT_ORPHAN_CAUSES](#content_orphan_causes)             | enumeration | Causes that are statements about the content rather than about the build.     |
| [CONTEXT_FAULTS](#context_faults)                           | enumeration | —                                                                             |
| [CONTEXT_KINDS](#context_kinds)                             | enumeration | The three things an adapter can preserve about where a comment was.           |
| [CONTEXT_KINDS_FOR_ANCHOR](#context_kinds_for_anchor)       | constant    | Which context kinds each anchor kind can honestly carry.                      |
| [ContextCheckInput](#contextcheckinput)                     | interface   | —                                                                             |
| [ContextFault](#contextfault)                               | type        | —                                                                             |
| [contextFaults](#contextfaults)                             | function    | —                                                                             |
| [ContextKind](#contextkind)                                 | type        | —                                                                             |
| [EDIT_WINDOW_MINUTES](#edit_window_minutes)                 | constant    | How long an author may edit their own comment, in minutes.                    |
| [EDIT_WINDOW_STATES](#edit_window_states)                   | enumeration | —                                                                             |
| [editWindowState](#editwindowstate)                         | function    | Whether a comment may still be edited.                                        |
| [EditWindowState](#editwindowstate)                         | type        | —                                                                             |
| [EXCERPT_CEILING_CODE_POINTS](#excerpt_ceiling_code_points) | constant    | The hard ceiling on a stored excerpt, in Unicode code points.                 |
| [flicksPerUnit](#flicksperunit)                             | function    | How many flicks one unit of a time base is, or null when it is not countable. |
| [isAtLeastAsWide](#isatleastaswide)                         | function    | Whether `a` reaches at least as many people as `b`.                           |
| [LIFECYCLE_FAULTS](#lifecycle_faults)                       | enumeration | —                                                                             |
| [LifecycleFault](#lifecyclefault)                           | type        | —                                                                             |
| [lifecycleFaults](#lifecyclefaults)                         | function    | —                                                                             |
| [LifecycleInput](#lifecycleinput)                           | interface   | —                                                                             |
| [MUTATING_OPERATIONS](#mutating_operations)                 | enumeration | Operations that change stored state. The two that do not are the exception.   |
| [OperationAttempt](#operationattempt)                       | interface   | —                                                                             |
| [ORPHAN_FAULTS](#orphan_faults)                             | enumeration | —                                                                             |
| [OrphanFault](#orphanfault)                                 | type        | —                                                                             |
| [orphanFaults](#orphanfaults)                               | function    | —                                                                             |
| [OrphanPresentation](#orphanpresentation)                   | interface   | —                                                                             |
| [ResolutionContext](#resolutioncontext)                     | interface   | What the reader may be told about the target, and what the target now is.     |
| [resolutionHeadline](#resolutionheadline)                   | function    | One line for an operator: what happened to a review's anchors.                |
| [ResolutionSummary](#resolutionsummary)                     | interface   | —                                                                             |
| [resolveAnchor](#resolveanchor)                             | function    | Resolve an anchor against a later revision.                                   |
| [ResolveRequest](#resolverequest)                           | interface   | —                                                                             |
| [REVIEW_JOURNEY_FAULTS](#review_journey_faults)             | enumeration | —                                                                             |
| [ReviewJourneyFault](#reviewjourneyfault)                   | type        | —                                                                             |
| [reviewJourneyFaults](#reviewjourneyfaults)                 | function    | —                                                                             |
| [ReviewJourneyObservation](#reviewjourneyobservation)       | interface   | —                                                                             |
| [speakingFor](#speakingfor)                                 | function    | Whose authority a comment was made under.                                     |
| [summarizeResolutions](#summarizeresolutions)               | function    | —                                                                             |
| [TargetPolicy](#targetpolicy)                               | interface   | What the object the thread hangs on permits.                                  |
| [TERMINAL_THREAD_STATES](#terminal_thread_states)           | enumeration | —                                                                             |
| [THREAD_FAULTS](#thread_faults)                             | constant    | —                                                                             |
| [THREAD_OPERATIONS](#thread_operations)                     | enumeration | —                                                                             |
| [THREAD_SCHEMA_FAULTS](#thread_schema_faults)               | enumeration | —                                                                             |
| [THREAD_STATES](#thread_states)                             | enumeration | Where a thread has got to.                                                    |
| [THREAD_VISIBILITIES](#thread_visibilities)                 | enumeration | Who a thread is addressed to.                                                 |
| [ThreadFault](#threadfault)                                 | type        | —                                                                             |
| [ThreadFinding](#threadfinding)                             | interface   | —                                                                             |
| [ThreadOperation](#threadoperation)                         | type        | —                                                                             |
| [ThreadRecord](#threadrecord)                               | interface   | —                                                                             |
| [ThreadSchemaFault](#threadschemafault)                     | type        | —                                                                             |
| [threadSchemaFaults](#threadschemafaults)                   | function    | —                                                                             |
| [ThreadState](#threadstate)                                 | type        | —                                                                             |
| [ThreadVisibility](#threadvisibility)                       | type        | —                                                                             |

## Shapes

#### ADAPTER_FAULTS

Values: `anchor-kind-with-no-adapter`, `two-adapters-for-one-anchor-kind`,
`adapter-for-an-unknown-anchor-kind`,
`adapter-that-rebases-what-it-cannot-resolve`, `adapter-with-no-version`,
`adapter-that-preserves-no-context`,
`adapter-that-claims-a-context-kind-its-anchor-cannot-carry`,
`rebasing-adapter-on-an-identity-that-does-not-survive-an-edit`

#### AdapterFault

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

#### adapterForAnchor

Which anchor kinds each thread adapter is allowed to carry.

```ts
adapterForAnchor(anchor: StableAnchor): AnchorKind
```

#### AnchorAdapterDeclaration

One deployment's adapter for one anchor kind.

| Field            | Type                                                   | Required | Notes                                                                                                    |
| ---------------- | ------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------- |
| `kind`           | [AnchorKind](./identity.md#anchorkind)                 | required | —                                                                                                        |
| `adapterVersion` | `number`                                               | required | Bumped when the rebase rule changes.                                                                     |
| `resolves`       | `boolean`                                              | required | —                                                                                                        |
| `rebases`        | `boolean`                                              | required | —                                                                                                        |
| `contextKinds`   | `readonly ContextKind[]` — [ContextKind](#contextkind) | required | —                                                                                                        |
| `identitySource` | `BlockIdentitySource`                                  | required | Where this adapter's addresses come from. S7.8 found the three and that only the first survives an edit. |

#### AnchorContext

| Field                 | Type                                                                          | Required | Notes                                                               |
| --------------------- | ----------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------- |
| `threadId`            | `string`                                                                      | required | —                                                                   |
| `capturedAt`          | [RevisionRef](./identity.md#revisionref)                                      | required | The revision this was captured from. Must be the anchor's own.      |
| `excerpt`             | `string \| null`                                                              | required | Code points of the passage, or null where the adapter takes none.   |
| `thumbnailDigest`     | `string \| null`                                                              | required | A digest of a stored thumbnail, or null. Never the bytes.           |
| `structuralPath`      | `readonly string[]`                                                           | required | Labels of the containing structure, root-first.                     |
| `capturedSensitivity` | `SensitivityClass \| null` — [SensitivityClass](./plugin.md#sensitivityclass) | required | The class of the material this was taken from, at capture.          |
| `sealed`              | `boolean`                                                                     | required | Whether the stored excerpt is sealed by S3.13's field protection.   |
| `withheldIsDeclared`  | `boolean`                                                                     | required | Whether the surface tells the reader the context is being withheld. |

#### AnchorEdit

One edit, expressed in the coordinate space it acted on.

```ts
EditBase & ( | { readonly space: 'entity' } | { readonly space: 'field'; readonly path: readonly string[]; readonly becomes: readonly (readonly string[])[]; } | { readonly space: 'text'; readonly blockId: BlockId; readonly at: number; readonly removed: number; readonly inserted: number; readonly becomes: readonly BlockId[]; readonly prefixShift: number; } | { readonly space: 'time'; readonly fromFlicks: number; readonly deltaFlicks: number; } | { readonly space: 'graph'; readonly target: 'node' | 'edge' | 'port'; readonly id: string; readonly becomes: readonly string[]; } | { readonly space: 'canvas'; readonly objectId: string; readonly part: string | null; readonly becomes: readonly string[]; } | { readonly space: 'hierarchy'; readonly nodeId: string; readonly toPath: readonly string[] | null; } )
```

#### AnchorRegistry

| Field    | Type                                                                                                                                                | Required | Notes |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----- |
| `byKind` | `ReadonlyMap<AnchorKind, AnchorAdapterDeclaration>` — [AnchorAdapterDeclaration](#anchoradapterdeclaration), [AnchorKind](./identity.md#anchorkind) | required | —     |

#### applyConfidenceThreshold

Turn a rebase the caller does not trust into an orphan.

```ts
applyConfidenceThreshold(resolution: AnchorResolution, threshold: number): AnchorResolution
```

#### buildAnchorRegistry

```ts
buildAnchorRegistry(declarations: readonly AnchorAdapterDeclaration[]): { readonly registry: AnchorRegistry; readonly findings: readonly ThreadFinding[]; }
```

#### COMMENT_STATES

What has happened to one comment.

Values: `published`, `edited`, `withdrawn`, `redacted`

#### CommentRecord

| Field                  | Type                                                 | Required | Notes                                                         |
| ---------------------- | ---------------------------------------------------- | -------- | ------------------------------------------------------------- |
| `commentId`            | `string`                                             | required | —                                                             |
| `threadId`             | `string`                                             | required | —                                                             |
| `parentCommentId`      | `string \| null`                                     | required | Null for the comment that opened the thread.                  |
| `author`               | [ActorRef](./identity.md#actorref)                   | required | —                                                             |
| `createdAt`            | [Instant](./identity.md#instant)                     | required | —                                                             |
| `editedAt`             | `Instant \| null` — [Instant](./identity.md#instant) | required | Null until edited. Never before `createdAt`.                  |
| `state`                | [CommentState](#commentstate)                        | required | —                                                             |
| `presentedAsAutomated` | `boolean`                                            | required | Whether the surface presents this comment as machine-written. |
| `attributedTo`         | `string`                                             | required | The identity the surface displays this comment under.         |

#### CommentState

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

#### completeAdapterSet

Every adapter, at a stable identity, resolving and rebasing.

```ts
completeAdapterSet(): readonly AnchorAdapterDeclaration[]
```

#### CONTENT_ORPHAN_CAUSES

Causes that are statements about the content rather than about the build.

Values: `deleted`, `replaced`, `migrated`, `ambiguous`

#### CONTEXT_FAULTS

Values: `context-captured-at-a-different-revision-than-the-anchor`,
`excerpt-past-the-declared-budget`, `declared-budget-past-the-ceiling`,
`context-that-carries-a-presence-disclosing-class`,
`context-of-a-protected-class-stored-unsealed`,
`context-refreshed-from-a-later-revision`,
`context-retained-after-its-source-was-erased`,
`context-withheld-without-saying-so`,
`context-for-a-kind-the-adapter-does-not-preserve`

#### CONTEXT_KINDS

The three things an adapter can preserve about where a comment was.

Values: `excerpt`, `thumbnail`, `structural`

#### CONTEXT_KINDS_FOR_ANCHOR

Which context kinds each anchor kind can honestly carry.

#### ContextCheckInput

| Field                | Type                                     | Required | Notes                                                                 |
| -------------------- | ---------------------------------------- | -------- | --------------------------------------------------------------------- |
| `thread`             | [ThreadRecord](#threadrecord)            | required | —                                                                     |
| `context`            | [AnchorContext](#anchorcontext)          | required | —                                                                     |
| `policy`             | [TargetPolicy](#targetpolicy)            | required | —                                                                     |
| `registry`           | [AnchorRegistry](#anchorregistry)        | required | —                                                                     |
| `currentRevision`    | [RevisionRef](./identity.md#revisionref) | required | The revision the thread is being READ against, which is not its base. |
| `excerptBudget`      | `number`                                 | required | The deployment's excerpt budget, at or under the ceiling.             |
| `readerMaySeeTarget` | `boolean`                                | required | Whether this reader may currently see the target's content.           |

#### ContextFault

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

#### contextFaults

```ts
contextFaults(input: ContextCheckInput): readonly ThreadFinding[]
```

#### ContextKind

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

#### EDIT_WINDOW_MINUTES

How long an author may edit their own comment, in minutes.

Value: `15`

#### EDIT_WINDOW_STATES

Values: `open`, `closed-by-time`, `closed-by-a-reply`

#### editWindowState

Whether a comment may still be edited.

```ts
editWindowState(comment: CommentRecord, thread: ThreadRecord, now: Instant, windowMinutes: number = EDIT_WINDOW_MINUTES): EditWindowState
```

#### EditWindowState

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

#### EXCERPT_CEILING_CODE_POINTS

The hard ceiling on a stored excerpt, in Unicode code points.

Value: `512`

#### flicksPerUnit

How many flicks one unit of a time base is, or null when it is not countable.

```ts
flicksPerUnit(base: TimeBase): number | null
```

#### isAtLeastAsWide

Whether `a` reaches at least as many people as `b`.

```ts
isAtLeastAsWide(a: ThreadVisibility, b: ThreadVisibility): boolean
```

#### LIFECYCLE_FAULTS

Values: `operation-with-no-authorization-check`,
`unauthorized-operation-applied`, `mutation-with-no-expected-revision`,
`mutation-against-a-thread-state-it-was-not-in`, `edit-after-the-window-closed`,
`edit-that-names-no-comment`, `reply-to-an-archived-thread`,
`reopen-of-an-archived-thread`, `state-change-with-no-audit-record`,
`navigate-to-an-orphaned-anchor-with-no-refusal`, `link-that-pins-no-revision`,
`notification-that-quotes-the-comment-body`,
`resolve-with-no-notice-to-the-thread`, `read-operation-recorded-as-a-mutation`

#### LifecycleFault

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

#### lifecycleFaults

```ts
lifecycleFaults(input: LifecycleInput): readonly ThreadFinding[]
```

#### LifecycleInput

| Field               | Type                                                                  | Required | Notes |
| ------------------- | --------------------------------------------------------------------- | -------- | ----- |
| `thread`            | [ThreadRecord](#threadrecord)                                         | required | —     |
| `attempts`          | `readonly OperationAttempt[]` — [OperationAttempt](#operationattempt) | required | —     |
| `now`               | [Instant](./identity.md#instant)                                      | required | —     |
| `editWindowMinutes` | `number`                                                              | optional | —     |

#### MUTATING_OPERATIONS

Operations that change stored state. The two that do not are the exception.

Values: `create`, `reply`, `edit`, `resolve`, `reopen`, `archive`

#### OperationAttempt

| Field                       | Type                                                                            | Required | Notes                                                                  |
| --------------------------- | ------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------- |
| `operationId`               | `string`                                                                        | required | —                                                                      |
| `operation`                 | [ThreadOperation](#threadoperation)                                             | required | —                                                                      |
| `threadId`                  | `string`                                                                        | required | —                                                                      |
| `commentId`                 | `string \| null`                                                                | required | For `edit` and `reply`: the comment acted on. Null elsewhere.          |
| `actor`                     | [ActorRef](./identity.md#actorref)                                              | required | —                                                                      |
| `at`                        | [Instant](./identity.md#instant)                                                | required | —                                                                      |
| `expectedThreadState`       | [ThreadState](#threadstate)                                                     | required | The thread state the caller believed it was acting on.                 |
| `expectedRevision`          | `string \| null`                                                                | required | The revision the caller believed the target was at. Null where absent. |
| `authorizationChecked`      | `boolean`                                                                       | required | Whether an object-level authorization decision was taken (S4.3).       |
| `authorized`                | `boolean`                                                                       | required | —                                                                      |
| `applied`                   | `boolean`                                                                       | required | Whether the attempt was carried out.                                   |
| `notified`                  | `boolean`                                                                       | required | Whether a notification was emitted, and whether it quoted the comment. |
| `notificationQuotedTheBody` | `boolean`                                                                       | required | —                                                                      |
| `audited`                   | `boolean`                                                                       | required | Whether an audit record was written.                                   |
| `linkPinsRevision`          | `boolean`                                                                       | required | For `link`: whether the produced link pins a revision.                 |
| `navigationTarget`          | `AnchorResolution \| null` — [AnchorResolution](./identity.md#anchorresolution) | required | For `navigate`: the resolution of the anchor being navigated to.       |
| `navigationRefusalShown`    | `boolean`                                                                       | required | For `navigate`: whether the surface reported that it could not go.     |

#### ORPHAN_FAULTS

Values: `orphan-that-dropped-the-original-anchor`,
`orphan-with-no-original-context`,
`orphan-shown-a-cause-that-is-not-the-one-computed`,
`unsupported-reported-as-a-fact-about-the-content`,
`permission-hidden-orphan-rendered-for-a-presence-disclosing-class`,
`resolved-anchor-presented-as-an-orphan`, `orphan-presented-as-resolved`

#### OrphanFault

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

#### orphanFaults

```ts
orphanFaults(presentations: readonly OrphanPresentation[]): readonly ThreadFinding[]
```

#### OrphanPresentation

| Field             | Type                                                                               | Required | Notes                                                                  |
| ----------------- | ---------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------- |
| `threadId`        | `string`                                                                           | required | —                                                                      |
| `resolution`      | [AnchorResolution](./identity.md#anchorresolution)                                 | required | —                                                                      |
| `originalAnchor`  | `StableAnchor \| null` — [StableAnchor](./identity.md#stableanchor)                | required | The anchor as it was taken. An orphan that drops it cannot be rescued. |
| `originalContext` | `AnchorContext \| null` — [AnchorContext](#anchorcontext)                          | required | —                                                                      |
| `shownCause`      | `AnchorOrphanCause \| null` — [AnchorOrphanCause](./identity.md#anchororphancause) | required | What the surface tells the reader happened.                            |
| `rendered`        | `boolean`                                                                          | required | Whether the thread is rendered at all.                                 |
| `sensitivity`     | `SensitivityClass \| null` — [SensitivityClass](./plugin.md#sensitivityclass)      | required | —                                                                      |

#### ResolutionContext

What the reader may be told about the target, and what the target now is.

| Field                   | Type                                                                          | Required | Notes                                                                       |
| ----------------------- | ----------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------- |
| `targetVisibleToReader` | `boolean`                                                                     | required | Whether this reader may see the object the thread hangs on at all.          |
| `sensitivity`           | `SensitivityClass \| null` — [SensitivityClass](./plugin.md#sensitivityclass) | required | —                                                                           |
| `timeBase`              | `TimeBase \| null` — [TimeBase](./identity.md#timebase)                       | required | The time base the target is expressed in NOW, or null when it did not move. |

#### resolutionHeadline

One line for an operator: what happened to a review's anchors.

```ts
resolutionHeadline(summary: ResolutionSummary): string
```

#### ResolutionSummary

| Field                     | Type                                                                                                 | Required | Notes                                                                                                          |
| ------------------------- | ---------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `total`                   | `number`                                                                                             | required | —                                                                                                              |
| `resolvedCount`           | `number`                                                                                             | required | —                                                                                                              |
| `rebasedCount`            | `number`                                                                                             | required | —                                                                                                              |
| `orphanedCount`           | `number`                                                                                             | required | —                                                                                                              |
| `byCause`                 | `Readonly<Record<AnchorOrphanCause, number>>` — [AnchorOrphanCause](./identity.md#anchororphancause) | required | —                                                                                                              |
| `everyAnchorAccountedFor` | `boolean`                                                                                            | required | Whether every anchor either survived or is explicitly orphaned — the parent's evidence clause, as one boolean. |
| `unexamined`              | `number`                                                                                             | required | —                                                                                                              |

#### resolveAnchor

Resolve an anchor against a later revision.

```ts
resolveAnchor(request: ResolveRequest): AnchorResolution
```

#### ResolveRequest

| Field      | Type                                                | Required | Notes                                                        |
| ---------- | --------------------------------------------------- | -------- | ------------------------------------------------------------ |
| `anchor`   | [StableAnchor](./identity.md#stableanchor)          | required | —                                                            |
| `at`       | [RevisionRef](./identity.md#revisionref)            | required | The revision to resolve against.                             |
| `edits`    | `readonly AnchorEdit[]` — [AnchorEdit](#anchoredit) | required | Every edit between the anchor's revision and `at`, in order. |
| `registry` | [AnchorRegistry](#anchorregistry)                   | required | —                                                            |
| `context`  | [ResolutionContext](#resolutioncontext)             | required | —                                                            |

#### REVIEW_JOURNEY_FAULTS

Values: `anchor-not-focusable`,
`thread-unreachable-from-its-anchor-by-keyboard`,
`anchor-unreachable-from-its-thread-by-keyboard`,
`round-trip-that-does-not-restore-the-position`,
`announcement-that-omits-what-the-comment-is-attached-to`,
`orphaned-thread-announced-as-anchored`, `anchor-marked-by-colour-alone`,
`thread-order-that-does-not-follow-the-document`

#### ReviewJourneyFault

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

#### reviewJourneyFaults

```ts
reviewJourneyFaults(observations: readonly ReviewJourneyObservation[]): readonly ThreadFinding[]
```

#### ReviewJourneyObservation

| Field                      | Type                                   | Required | Notes                                                                  |
| -------------------------- | -------------------------------------- | -------- | ---------------------------------------------------------------------- |
| `threadId`                 | `string`                               | required | —                                                                      |
| `anchorKind`               | [AnchorKind](./identity.md#anchorkind) | required | —                                                                      |
| `anchorFocusable`          | `boolean`                              | required | Whether the mark on the document can take focus.                       |
| `anchorToThreadByKeyboard` | `boolean`                              | required | Whether a keyboard alone gets from the anchor to the thread.           |
| `threadToAnchorByKeyboard` | `boolean`                              | required | Whether a keyboard alone gets from the thread back to the anchor.      |
| `focusBefore`              | `string`                               | required | Where focus landed after the round trip, and where it started.         |
| `focusAfterReturn`         | `string`                               | required | —                                                                      |
| `announcement`             | `string`                               | required | What a screen reader said on landing in the thread.                    |
| `orphaned`                 | `boolean`                              | required | Whether the resolution says the anchor is orphaned.                    |
| `anchorCues`               | `readonly string[]`                    | required | Non-colour marks distinguishing the anchor from surrounding content.   |
| `threadOrder`              | `readonly string[]`                    | required | The order threads are reached in, and document order for the same set. |
| `documentOrder`            | `readonly string[]`                    | required | —                                                                      |

#### speakingFor

Whose authority a comment was made under.

```ts
speakingFor(actor: ActorRef): string
```

#### summarizeResolutions

```ts
summarizeResolutions(resolutions: readonly AnchorResolution[]): ResolutionSummary
```

#### TargetPolicy

What the object the thread hangs on permits.

| Field           | Type                                                                          | Required | Notes                                                                    |
| --------------- | ----------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------ |
| `targetId`      | `string`                                                                      | required | —                                                                        |
| `maxVisibility` | [ThreadVisibility](#threadvisibility)                                         | required | The widest a thread on this object may be.                               |
| `sensitivity`   | `SensitivityClass \| null` — [SensitivityClass](./plugin.md#sensitivityclass) | required | The class of what is stored on the object, or null for ordinary content. |
| `erased`        | `boolean`                                                                     | required | Whether the source content has been erased under S5's deletion rules.    |
| `authoredBy`    | `string \| null`                                                              | required | Who authored the object under review, where the host can say.            |

#### TERMINAL_THREAD_STATES

Values: `archived`

#### THREAD_FAULTS

#### THREAD_OPERATIONS

Values: `create`, `reply`, `edit`, `resolve`, `reopen`, `archive`, `link`,
`navigate`

#### THREAD_SCHEMA_FAULTS

Values: `two-threads-with-one-id`, `two-comments-with-one-id`,
`comment-filed-under-another-thread`, `reply-to-a-comment-in-another-thread`,
`reply-to-a-comment-that-does-not-exist`, `reply-cycle`,
`thread-with-no-comments`, `thread-on-a-target-with-no-declared-policy`,
`thread-anchored-at-a-revision-that-is-not-its-base`,
`thread-whose-adapter-does-not-match-its-anchor`,
`comment-edited-before-it-was-created`,
`comment-marked-edited-with-no-edit-time`,
`comment-with-an-edit-time-not-marked-edited`,
`thread-resolved-before-its-last-comment`, `resolved-thread-with-no-resolver`,
`resolver-recorded-on-an-open-thread`, `archived-thread-with-no-archive-time`,
`thread-visibility-wider-than-its-target-permits`,
`machine-authored-comment-presented-as-a-person`,
`delegated-comment-attributed-to-the-principal-alone`,
`comment-attributed-to-somebody-who-did-not-write-it`,
`thread-resolved-by-the-reviewed-party-with-no-answer`

#### THREAD_STATES

Where a thread has got to.

Values: `open`, `resolved`, `archived`

#### THREAD_VISIBILITIES

Who a thread is addressed to.

Values: `tenant`, `reviewers`, `participants`, `author-only`

#### ThreadFault

```ts
| ThreadSchemaFault
| AdapterFault
| ContextFault
| OrphanFault
| LifecycleFault
| ReviewJourneyFault
```

#### ThreadFinding

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

#### ThreadOperation

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

#### ThreadRecord

| Field          | Type                                                         | Required | Notes                                                                                                                                                                                   |
| -------------- | ------------------------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `threadId`     | `string`                                                     | required | —                                                                                                                                                                                       |
| `targetId`     | `string`                                                     | required | —                                                                                                                                                                                       |
| `adapter`      | [AnchorKind](./identity.md#anchorkind)                       | required | The anchor kind, which is also the adapter that owns this thread.                                                                                                                       |
| `anchor`       | [StableAnchor](./identity.md#stableanchor)                   | required | —                                                                                                                                                                                       |
| `baseRevision` | [RevisionRef](./identity.md#revisionref)                     | required | The revision the author was looking at. Must be the revision the anchor was taken at — two fields that disagree describe a comment written about one revision and addressed to another. |
| `visibility`   | [ThreadVisibility](#threadvisibility)                        | required | —                                                                                                                                                                                       |
| `state`        | [ThreadState](#threadstate)                                  | required | —                                                                                                                                                                                       |
| `openedAt`     | [Instant](./identity.md#instant)                             | required | —                                                                                                                                                                                       |
| `resolvedAt`   | `Instant \| null` — [Instant](./identity.md#instant)         | required | —                                                                                                                                                                                       |
| `resolvedBy`   | `ActorRef \| null` — [ActorRef](./identity.md#actorref)      | required | —                                                                                                                                                                                       |
| `archivedAt`   | `Instant \| null` — [Instant](./identity.md#instant)         | required | —                                                                                                                                                                                       |
| `comments`     | `readonly CommentRecord[]` — [CommentRecord](#commentrecord) | required | —                                                                                                                                                                                       |

#### ThreadSchemaFault

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

#### threadSchemaFaults

```ts
threadSchemaFaults(threads: readonly ThreadRecord[], policies: readonly TargetPolicy[]): readonly ThreadFinding[]
```

#### ThreadState

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

#### ThreadVisibility

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

## Valid examples

No committed fixture corpus covers this page's accepted cases; they are
unit-level and live in the module's own spec.

## Invalid examples

No committed fixture corpus covers this page's refused cases; they are
unit-level and live in the module's own spec.

## Authorization and scope

| Symbol                                  | Type       | Notes                                                            |
| --------------------------------------- | ---------- | ---------------------------------------------------------------- |
| `OperationAttempt.actor`                | `ActorRef` | —                                                                |
| `OperationAttempt.authorizationChecked` | `boolean`  | Whether an object-level authorization decision was taken (S4.3). |
| `OperationAttempt.authorized`           | `boolean`  | —                                                                |

## Idempotency and concurrency

| Symbol                              | Type                          | Notes                                                                                                                                                                                   |
| ----------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `ContextCheckInput.currentRevision` | `RevisionRef`                 | The revision the thread is being READ against, which is not its base.                                                                                                                   |
| `LifecycleInput.attempts`           | `readonly OperationAttempt[]` | —                                                                                                                                                                                       |
| `OperationAttempt.expectedRevision` | `string                       | null`                                                                                                                                                                                   | The revision the caller believed the target was at. Null where absent. |
| `OperationAttempt.linkPinsRevision` | `boolean`                     | For `link`: whether the produced link pins a revision.                                                                                                                                  |
| `ThreadRecord.baseRevision`         | `RevisionRef`                 | The revision the author was looking at. Must be the revision the anchor was taken at — two fields that disagree describe a comment written about one revision and addressed to another. |

## Pagination

Not applicable: nothing on this page returns a collection a caller reads in
pages.

## State and failure

| Symbol                                    | Type           | Notes                                                              |
| ----------------------------------------- | -------------- | ------------------------------------------------------------------ |
| `COMMENT_STATES`                          | `enumeration`  | What has happened to one comment.                                  |
| `CommentRecord.state`                     | `CommentState` | —                                                                  |
| `CommentState`                            | `type`         | —                                                                  |
| `EDIT_WINDOW_STATES`                      | `enumeration`  | —                                                                  |
| `editWindowState`                         | `function`     | Whether a comment may still be edited.                             |
| `EditWindowState`                         | `type`         | —                                                                  |
| `OperationAttempt.expectedThreadState`    | `ThreadState`  | The thread state the caller believed it was acting on.             |
| `OperationAttempt.navigationRefusalShown` | `boolean`      | For `navigate`: whether the surface reported that it could not go. |
| `TERMINAL_THREAD_STATES`                  | `enumeration`  | —                                                                  |
| `THREAD_STATES`                           | `enumeration`  | Where a thread has got to.                                         |
| `ThreadRecord.state`                      | `ThreadState`  | —                                                                  |
| `ThreadState`                             | `type`         | —                                                                  |

## Compatibility

| Symbol                                    | Type     | Notes                                |
| ----------------------------------------- | -------- | ------------------------------------ |
| `AnchorAdapterDeclaration.adapterVersion` | `number` | Bumped when the rebase rule changes. |

## Deprecation

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

## Evidence

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