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 | enumeration | — |
| AdapterFault | type | — |
| adapterForAnchor | function | Which anchor kinds each thread adapter is allowed to carry. |
| AnchorAdapterDeclaration | interface | One deployment's adapter for one anchor kind. |
| AnchorContext | interface | — |
| AnchorEdit | type | One edit, expressed in the coordinate space it acted on. |
| AnchorRegistry | interface | — |
| applyConfidenceThreshold | function | Turn a rebase the caller does not trust into an orphan. |
| buildAnchorRegistry | function | — |
| COMMENT_STATES | enumeration | What has happened to one comment. |
| CommentRecord | interface | — |
| CommentState | type | — |
| completeAdapterSet | function | Every adapter, at a stable identity, resolving and rebasing. |
| CONTENT_ORPHAN_CAUSES | enumeration | Causes that are statements about the content rather than about the build. |
| CONTEXT_FAULTS | enumeration | — |
| CONTEXT_KINDS | enumeration | The three things an adapter can preserve about where a comment was. |
| CONTEXT_KINDS_FOR_ANCHOR | constant | Which context kinds each anchor kind can honestly carry. |
| ContextCheckInput | interface | — |
| ContextFault | type | — |
| contextFaults | function | — |
| ContextKind | type | — |
| EDIT_WINDOW_MINUTES | constant | How long an author may edit their own comment, in minutes. |
| EDIT_WINDOW_STATES | enumeration | — |
| editWindowState | function | Whether a comment may still be edited. |
| EditWindowState | type | — |
| EXCERPT_CEILING_CODE_POINTS | constant | The hard ceiling on a stored excerpt, in Unicode code points. |
| flicksPerUnit | function | How many flicks one unit of a time base is, or null when it is not countable. |
| isAtLeastAsWide | function | Whether a reaches at least as many people as b. |
| LIFECYCLE_FAULTS | enumeration | — |
| LifecycleFault | type | — |
| lifecycleFaults | function | — |
| LifecycleInput | interface | — |
| MUTATING_OPERATIONS | enumeration | Operations that change stored state. The two that do not are the exception. |
| OperationAttempt | interface | — |
| ORPHAN_FAULTS | enumeration | — |
| OrphanFault | type | — |
| orphanFaults | function | — |
| OrphanPresentation | interface | — |
| ResolutionContext | interface | What the reader may be told about the target, and what the target now is. |
| resolutionHeadline | function | One line for an operator: what happened to a review's anchors. |
| ResolutionSummary | interface | — |
| resolveAnchor | function | Resolve an anchor against a later revision. |
| ResolveRequest | interface | — |
| REVIEW_JOURNEY_FAULTS | enumeration | — |
| ReviewJourneyFault | type | — |
| reviewJourneyFaults | function | — |
| ReviewJourneyObservation | interface | — |
| speakingFor | function | Whose authority a comment was made under. |
| summarizeResolutions | function | — |
| TargetPolicy | interface | What the object the thread hangs on permits. |
| TERMINAL_THREAD_STATES | enumeration | — |
| THREAD_FAULTS | constant | — |
| THREAD_OPERATIONS | enumeration | — |
| THREAD_SCHEMA_FAULTS | enumeration | — |
| THREAD_STATES | enumeration | Where a thread has got to. |
| THREAD_VISIBILITIES | enumeration | Who a thread is addressed to. |
| ThreadFault | type | — |
| ThreadFinding | interface | — |
| ThreadOperation | type | — |
| ThreadRecord | interface | — |
| ThreadSchemaFault | type | — |
| threadSchemaFaults | function | — |
| ThreadState | type | — |
| 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#
(typeof ADAPTER_FAULTS)[number];
adapterForAnchor#
Which anchor kinds each thread adapter is allowed to carry.
adapterForAnchor(anchor: StableAnchor): AnchorKind
AnchorAdapterDeclaration#
One deployment's adapter for one anchor kind.
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
AnchorKind | required | — |
adapterVersion |
number |
required | Bumped when the rebase rule changes. |
resolves |
boolean |
required | — |
rebases |
boolean |
required | — |
contextKinds |
readonly 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 | 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 |
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.
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, AnchorKind |
required | — |
applyConfidenceThreshold#
Turn a rebase the caller does not trust into an orphan.
applyConfidenceThreshold(resolution: AnchorResolution, threshold: number): AnchorResolution
buildAnchorRegistry#
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 | required | — |
createdAt |
Instant | required | — |
editedAt |
Instant | null — Instant |
required | Null until edited. Never before createdAt. |
state |
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#
(typeof COMMENT_STATES)[number];
completeAdapterSet#
Every adapter, at a stable identity, resolving and rebasing.
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 | required | — |
context |
AnchorContext | required | — |
policy |
TargetPolicy | required | — |
registry |
AnchorRegistry | required | — |
currentRevision |
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#
(typeof CONTEXT_FAULTS)[number];
contextFaults#
contextFaults(input: ContextCheckInput): readonly ThreadFinding[]
ContextKind#
(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.
editWindowState(comment: CommentRecord, thread: ThreadRecord, now: Instant, windowMinutes: number = EDIT_WINDOW_MINUTES): EditWindowState
EditWindowState#
(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.
flicksPerUnit(base: TimeBase): number | null
isAtLeastAsWide#
Whether a reaches at least as many people as b.
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#
(typeof LIFECYCLE_FAULTS)[number];
lifecycleFaults#
lifecycleFaults(input: LifecycleInput): readonly ThreadFinding[]
LifecycleInput#
| Field | Type | Required | Notes |
|---|---|---|---|
thread |
ThreadRecord | required | — |
attempts |
readonly OperationAttempt[] — OperationAttempt |
required | — |
now |
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 | required | — |
threadId |
string |
required | — |
commentId |
string | null |
required | For edit and reply: the comment acted on. Null elsewhere. |
actor |
ActorRef | required | — |
at |
Instant | required | — |
expectedThreadState |
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 |
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#
(typeof ORPHAN_FAULTS)[number];
orphanFaults#
orphanFaults(presentations: readonly OrphanPresentation[]): readonly ThreadFinding[]
OrphanPresentation#
| Field | Type | Required | Notes |
|---|---|---|---|
threadId |
string |
required | — |
resolution |
AnchorResolution | required | — |
originalAnchor |
StableAnchor | null — StableAnchor |
required | The anchor as it was taken. An orphan that drops it cannot be rescued. |
originalContext |
AnchorContext | null — AnchorContext |
required | — |
shownCause |
AnchorOrphanCause | null — AnchorOrphanCause |
required | What the surface tells the reader happened. |
rendered |
boolean |
required | Whether the thread is rendered at all. |
sensitivity |
SensitivityClass | null — 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 |
required | — |
timeBase |
TimeBase | null — 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.
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 |
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.
resolveAnchor(request: ResolveRequest): AnchorResolution
ResolveRequest#
| Field | Type | Required | Notes |
|---|---|---|---|
anchor |
StableAnchor | required | — |
at |
RevisionRef | required | The revision to resolve against. |
edits |
readonly AnchorEdit[] — AnchorEdit |
required | Every edit between the anchor's revision and at, in order. |
registry |
AnchorRegistry | required | — |
context |
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#
(typeof REVIEW_JOURNEY_FAULTS)[number];
reviewJourneyFaults#
reviewJourneyFaults(observations: readonly ReviewJourneyObservation[]): readonly ThreadFinding[]
ReviewJourneyObservation#
| Field | Type | Required | Notes |
|---|---|---|---|
threadId |
string |
required | — |
anchorKind |
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.
speakingFor(actor: ActorRef): string
summarizeResolutions#
summarizeResolutions(resolutions: readonly AnchorResolution[]): ResolutionSummary
TargetPolicy#
What the object the thread hangs on permits.
| Field | Type | Required | Notes |
|---|---|---|---|
targetId |
string |
required | — |
maxVisibility |
ThreadVisibility | required | The widest a thread on this object may be. |
sensitivity |
SensitivityClass | null — 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#
| ThreadSchemaFault
| AdapterFault
| ContextFault
| OrphanFault
| LifecycleFault
| ReviewJourneyFault
ThreadFinding#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
ThreadFault | required | — |
subject |
string |
required | — |
detail |
string |
required | — |
ThreadOperation#
(typeof THREAD_OPERATIONS)[number];
ThreadRecord#
| Field | Type | Required | Notes |
|---|---|---|---|
threadId |
string |
required | — |
targetId |
string |
required | — |
adapter |
AnchorKind | required | The anchor kind, which is also the adapter that owns this thread. |
anchor |
StableAnchor | required | — |
baseRevision |
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 | required | — |
state |
ThreadState | required | — |
openedAt |
Instant | required | — |
resolvedAt |
Instant | null — Instant |
required | — |
resolvedBy |
ActorRef | null — ActorRef |
required | — |
archivedAt |
Instant | null — Instant |
required | — |
comments |
readonly CommentRecord[] — CommentRecord |
required | — |
ThreadSchemaFault#
(typeof THREAD_SCHEMA_FAULTS)[number];
threadSchemaFaults#
threadSchemaFaults(threads: readonly ThreadRecord[], policies: readonly TargetPolicy[]): readonly ThreadFinding[]
ThreadState#
(typeof THREAD_STATES)[number];
ThreadVisibility#
(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.jsonlibs/oshun/workbench-kit/src/comment-threads.ts