Eve library

Anchored comment threads

Evidence

Revision 1

On this page

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#

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

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

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

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

ts
(typeof ORPHAN_FAULTS)[number];

orphanFaults#

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

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

ts
(typeof REVIEW_JOURNEY_FAULTS)[number];

reviewJourneyFaults#

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

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

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

ThreadFinding#

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

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