Why a proposed change is neither a comment nor an edit, how it is shown without reaching the document or the author's unsaved work, which of the six questions has to be re-asked at the moment somebody admits it, and how a revision records both the person whose words it carries and the person who let them in.
Generated from libs/oshun/workbench-kit/src/suggestions.ts by
node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs. Ledger:
S8.3. Do not edit by hand.
Summary#
src/suggestions.ts
| Entry point | Runtime class | Authorized by |
|---|---|---|
@oshun/workbench-kit/suggestions |
contract |
S8.3 |
Exports#
| Symbol | Kind | Summary |
|---|---|---|
| ACCEPTANCE_CONFIDENCE_THRESHOLD | constant | The confidence a rebase must reach before an acceptance may rely on it. |
| ACCEPTANCE_FAULTS | enumeration | — |
| AcceptanceAudit | interface | What a host actually wrote, checked against the proposal it claims to be. |
| AcceptanceFault | type | — |
| acceptanceFaults | function | — |
| AcceptanceOutcome | type | — |
| AcceptanceRecord | interface | — |
| AcceptanceRequest | interface | — |
| acceptSuggestion | function | Admit a proposal, or say why not. |
| CapabilityExercise | interface | What a host decided when somebody exercised one of the four rights. |
| CapabilityGrant | interface | — |
| CapabilityRule | interface | How a deployment ties two rights together. |
| CHECK_VERDICTS | enumeration | What one check found. |
| CheckVerdict | type | — |
| DependencyState | interface | — |
| ENDING_FAULTS | enumeration | — |
| ENDING_KINDS | enumeration | — |
| EndingContext | interface | — |
| EndingFault | type | — |
| endingFaults | function | Whether ending a proposal ended it and did nothing else. |
| EndingKind | type | — |
| EVIDENCE_KINDS | enumeration | What a proposal offers in support of itself. |
| EvidenceKind | type | — |
| ISOLATION_FAULTS | enumeration | — |
| IsolationFault | type | — |
| isolationFaults | function | Whether showing a proposal left the document, and its author's work, alone. |
| isTerminalSuggestionState | function | — |
| LINK_FAULTS | enumeration | — |
| LinkFault | type | — |
| linkFaults | function | — |
| LinkObservation | interface | — |
| partSelectionRefusals | function | Which selections of parts may be admitted together. |
| PERMISSION_FAULTS | enumeration | — |
| PermissionFault | type | — |
| PermissionMatrix | interface | — |
| permissionMatrixFaults | function | — |
| PREVIEW_SURFACES | enumeration | How a proposal is shown. Only the first can reach the authoring buffer. |
| PreviewObservation | interface | One rendering of a proposal, described by the surface that rendered it. |
| PreviewSurface | type | — |
| ProposedOperation | interface | One atomic part of a proposal. |
| proposingAuthorities | function | Every authority that has put content into this object, from the history alone. |
| revalidate | function | The six questions, asked at the moment of acceptance. |
| REVALIDATION_CHECKS | enumeration | The six the item names, in the order they are cheapest to answer. |
| REVALIDATION_FAULTS | enumeration | — |
| RevalidationCheck | type | — |
| RevalidationFault | type | — |
| RevalidationInput | interface | — |
| RevalidationReport | interface | — |
| STATE_FOR_ENDING | constant | The state each ending kind puts a proposal into. One mapping, not two. |
| SUGGESTION_CAPABILITIES | enumeration | — |
| SUGGESTION_FAULTS | constant | — |
| SUGGESTION_SCHEMA_FAULTS | enumeration | — |
| SUGGESTION_STATES | enumeration | Where a proposal has got to. |
| SuggestionCapability | type | — |
| SuggestionEnding | type | How a proposal ended without being admitted. |
| SuggestionEvidence | interface | — |
| SuggestionFault | type | — |
| SuggestionFinding | interface | — |
| suggestionHeadline | function | One line for an operator: what happened to a review's proposals. |
| SuggestionLedger | interface | — |
| SuggestionRecord | interface | A proposal, as it is stored. |
| SuggestionSchemaFault | type | — |
| suggestionSchemaFaults | function | Every way a stored proposal can be incoherent on its own terms. |
| SuggestionState | type | — |
| summarizeSuggestions | function | — |
| targetsOf | function | Every entity this module's records address, for a host walking a workbench. |
| TERMINAL_SUGGESTION_STATES | enumeration | Every state but proposed, and that includes partially-accepted. |
Shapes#
ACCEPTANCE_CONFIDENCE_THRESHOLD#
The confidence a rebase must reach before an acceptance may rely on it.
Value: 0.95
ACCEPTANCE_FAULTS#
Values: part-admitted-without-the-part-it-requires,
parts-on-one-path-admitted-apart,
acceptance-on-an-inadmissible-revalidation,
acceptance-by-an-automated-actor, acceptance-by-an-erased-actor,
acceptance-with-no-reason, acceptance-onto-a-head-of-another-entity,
acceptance-by-the-proposer,
acceptance-crediting-the-accepter-s-own-authority,
acceptance-whose-revision-credits-nobody,
acceptance-crediting-somebody-who-did-not-propose-it,
acceptance-whose-revision-is-authored-by-the-proposer,
acceptance-whose-revision-names-another-proposal,
acceptance-that-lost-the-base-revision,
acceptance-whose-parent-is-not-the-head,
acceptance-that-did-not-advance-the-sequence,
acceptance-applied-at-the-original-anchor-after-a-rebase,
acceptance-that-left-parts-in-a-live-state,
acceptance-that-changed-the-proposal, acceptance-with-no-audit-record
AcceptanceAudit#
What a host actually wrote, checked against the proposal it claims to be.
| Field | Type | Required | Notes |
|---|---|---|---|
suggestion |
SuggestionRecord | required | — |
revision |
RevisionRecord | required | — |
head |
RevisionRecord | required | — |
appliedAt |
StableAnchor | required | The anchor the change was written at. |
revalidation |
RevalidationReport | required | — |
after |
SuggestionRecord | required | The proposal as it stands after the acceptance. |
audited |
boolean |
required | — |
selfAcceptancePermitted |
boolean |
required | Whether this deployment lets a proposer admit their own proposal. |
AcceptanceFault#
(typeof ACCEPTANCE_FAULTS)[number];
acceptanceFaults#
acceptanceFaults(audit: AcceptanceAudit): readonly SuggestionFinding[]
AcceptanceOutcome#
| { readonly outcome: 'refused'; readonly refusals: readonly SuggestionFinding[] }
| { readonly outcome: 'accepted'; readonly revision: RevisionRecord; readonly acceptance: AcceptanceRecord; readonly suggestion: SuggestionRecord; readonly unaccepted: readonly string[]; readonly recordedAsADirectEdit: boolean; }
AcceptanceRecord#
| Field | Type | Required | Notes |
|---|---|---|---|
acceptedBy |
ActorRef | required | — |
at |
Instant | required | — |
acceptedParts |
readonly string[] |
required | The parts admitted. Never empty. |
producedRevision |
RevisionId | required | — |
amended |
boolean |
required | Whether the accepter changed the proposal before admitting it. |
reason |
string |
required | — |
AcceptanceRequest#
| Field | Type | Required | Notes |
|---|---|---|---|
suggestion |
SuggestionRecord | required | — |
parts |
readonly string[] |
required | The parts to admit. |
accepter |
ActorRef | required | — |
head |
RevisionRecord | required | The revision the acceptance is written onto. |
newRevisionId |
RevisionId | required | — |
contentHash |
Sha256Hex | required | — |
at |
Instant | required | — |
reason |
string |
required | — |
amended |
boolean |
required | Whether the accepter changed the proposal before admitting it. |
revalidation |
RevalidationReport | required | — |
selfAcceptancePermitted |
boolean |
required | Whether this deployment lets a proposer admit their own proposal. |
acceptSuggestion#
Admit a proposal, or say why not.
acceptSuggestion(request: AcceptanceRequest): AcceptanceOutcome
CapabilityExercise#
What a host decided when somebody exercised one of the four rights.
| Field | Type | Required | Notes |
|---|---|---|---|
exerciseId |
string |
required | — |
actorId |
string |
required | — |
capability |
SuggestionCapability | required | — |
disposition |
string | null |
required | The disposition the object-level decision returned, or null if none was taken. |
permitted |
boolean |
required | — |
CapabilityGrant#
| Field | Type | Required | Notes |
|---|---|---|---|
actorId |
string |
required | — |
capabilities |
readonly SuggestionCapability[] — SuggestionCapability |
required | — |
CapabilityRule#
How a deployment ties two rights together.
| Field | Type | Required | Notes |
|---|---|---|---|
held |
SuggestionCapability | required | — |
other |
SuggestionCapability | required | — |
relation |
'confers' | 'requires' |
required | — |
CHECK_VERDICTS#
What one check found.
Values: passed, moved, refused, not-checked
CheckVerdict#
(typeof CHECK_VERDICTS)[number];
DependencyState#
| Field | Type | Required | Notes |
|---|---|---|---|
dependencyId |
string |
required | — |
present |
boolean |
required | — |
atProposal |
RevisionId | required | The revision it was at when the proposal was written. |
atAcceptance |
RevisionId | null — RevisionId |
required | Where it is now. Null when the host did not look. |
ENDING_FAULTS#
Values: ending-that-mutated-the-content, ending-that-advanced-the-head,
ending-with-no-reason, ending-that-did-not-change-the-state,
terminal-proposal-ended-again, withdrawal-recorded-as-a-rejection,
rejection-recorded-as-a-withdrawal, expiry-recorded-before-its-time,
live-proposal-past-its-expiry, supersession-whose-successor-is-missing,
supersession-by-a-proposal-on-another-target,
supersession-by-a-proposal-that-predates-it,
supersession-that-left-the-discussion-behind,
ended-proposal-whose-record-changed, ending-with-no-audit-record
ENDING_KINDS#
Values: rejected, withdrawn, expired, superseded
EndingContext#
| Field | Type | Required | Notes |
|---|---|---|---|
contentHashBefore |
Sha256Hex | required | The object's content hash before and after the ending. Must not move. |
contentHashAfter |
Sha256Hex | required | — |
headBefore |
RevisionId | required | — |
headAfter |
RevisionId | required | — |
audited |
boolean |
required | — |
successor |
SuggestionRecord | null — SuggestionRecord |
required | The proposal named by a supersession, when the host could find it. |
now |
Instant | required | — |
EndingFault#
(typeof ENDING_FAULTS)[number];
endingFaults#
Whether ending a proposal ended it and did nothing else.
endingFaults(before: SuggestionRecord, after: SuggestionRecord, context: EndingContext): readonly SuggestionFinding[]
EndingKind#
(typeof ENDING_KINDS)[number];
EVIDENCE_KINDS#
What a proposal offers in support of itself.
Values: gate-run, source-citation, measurement, prior-revision,
policy-clause
EvidenceKind#
(typeof EVIDENCE_KINDS)[number];
ISOLATION_FAULTS#
Values: projection-written-into-the-authoring-buffer,
projection-moved-the-dirty-comparison, projection-set-the-dirty-flag,
projection-that-wrote-a-revision, autosave-armed-over-a-projection,
dirty-counted-from-keystrokes-under-a-projection,
projection-over-a-moved-document-with-no-rebase,
projection-over-an-orphaned-anchor, projection-not-labelled-as-proposed,
projection-that-locked-the-document,
projection-of-a-part-that-is-not-in-the-proposal,
projection-of-a-part-without-the-part-it-requires,
semantic-diff-that-counts-a-presentation-change,
semantic-diff-that-omits-a-semantic-change
IsolationFault#
(typeof ISOLATION_FAULTS)[number];
isolationFaults#
Whether showing a proposal left the document, and its author's work, alone.
isolationFaults(suggestion: SuggestionRecord, observation: PreviewObservation): readonly SuggestionFinding[]
isTerminalSuggestionState#
isTerminalSuggestionState(state: SuggestionState): boolean
LINK_FAULTS#
Values: resolving-the-discussion-ended-the-proposal,
accepting-the-proposal-resolved-the-discussion,
discussion-and-proposal-presented-as-one-state,
discussion-archived-with-a-live-proposal,
proposal-admitted-over-an-unanswered-objection,
proposal-linked-to-a-discussion-about-another-target,
proposal-reachable-from-the-discussion-and-not-back,
discussion-reachable-from-the-proposal-and-not-back,
link-that-names-a-discussion-with-no-state
LinkFault#
(typeof LINK_FAULTS)[number];
linkFaults#
linkFaults(observation: LinkObservation): readonly SuggestionFinding[]
LinkObservation#
| Field | Type | Required | Notes |
|---|---|---|---|
suggestionId |
string |
required | — |
suggestionState |
SuggestionState | required | — |
suggestionTargetId |
string |
required | — |
threadId |
string | null |
required | The discussion this proposal is argued in. Null when there is none. |
threadState |
ThreadState | null — ThreadState |
required | The thread's own state, when the host looked it up. |
threadTargetId |
string | null |
required | — |
presentedAsOneState |
boolean |
required | Whether the surface renders one control for both. |
resolvingTheThreadEndedTheProposal |
boolean |
required | Whether resolving the discussion changed the proposal's state. |
acceptingTheProposalResolvedTheThread |
boolean |
required | Whether admitting the proposal changed the discussion's state. |
unansweredObjections |
number |
required | Objections in the discussion that nobody had answered at acceptance. |
reachableFromTheThread |
boolean |
required | — |
reachableFromTheProposal |
boolean |
required | — |
partSelectionRefusals#
Which selections of parts may be admitted together.
partSelectionRefusals(suggestion: SuggestionRecord, selection: readonly string[]): readonly SuggestionFinding[]
PERMISSION_FAULTS#
Values: direct-edit-confers-proposing, proposing-requires-direct-edit,
proposing-confers-acceptance, direct-edit-confers-acceptance,
acceptance-confers-approval, approval-confers-acceptance,
acceptance-granted-without-direct-edit,
rule-between-a-capability-and-itself,
rule-that-confers-and-requires-the-same-pair, capability-granted-to-nobody,
unknown-capability-granted,
capability-exercised-with-no-object-level-decision,
capability-permitted-against-a-refusing-decision,
capability-refused-against-an-allowing-decision
PermissionFault#
(typeof PERMISSION_FAULTS)[number];
PermissionMatrix#
| Field | Type | Required | Notes |
|---|---|---|---|
grants |
readonly CapabilityGrant[] — CapabilityGrant |
required | — |
rules |
readonly CapabilityRule[] — CapabilityRule |
required | — |
permissionMatrixFaults#
permissionMatrixFaults(matrix: PermissionMatrix, exercises: readonly CapabilityExercise[] = []): readonly SuggestionFinding[]
PREVIEW_SURFACES#
How a proposal is shown. Only the first can reach the authoring buffer.
Values: inline-in-the-document, side-by-side, patch-only
PreviewObservation#
One rendering of a proposal, described by the surface that rendered it.
| Field | Type | Required | Notes |
|---|---|---|---|
previewId |
string |
required | — |
suggestionId |
string |
required | — |
surface |
PreviewSurface | required | — |
computedAgainst |
RevisionId | required | The revision the projection was computed on top of. |
baseRevision |
RevisionId | required | The proposal's base revision. |
rebase |
AnchorResolution | null — AnchorResolution |
required | The resolution of the proposal's anchor against computedAgainst, when the two differ. Null when nothing was resolved. |
writtenIntoTheAuthoringBuffer |
boolean |
required | Whether the projection was written into the editor's authoring buffer. |
dirtyComparedAgainst |
RevisionId | required | The revision the editor's dirty flag compares against while it is shown. |
editorBaseRevision |
RevisionId | required | The editor's own base, which the projection must not have moved. |
dirtySource |
'compared-against-the-base' | 'counted-keystrokes' |
required | — |
dirtyBefore |
boolean |
required | — |
dirtyAfter |
boolean |
required | — |
revisionsWritten |
readonly RevisionId[] — RevisionId |
required | Revisions the host wrote while rendering. Must be empty. |
autosaveArmed |
boolean |
required | Whether an autosave was armed while the projection was displayed. |
labelledAsProposed |
boolean |
required | Whether the surface labels the projection as proposed rather than authored. |
authoringStillPermitted |
boolean |
required | Whether the author could still edit the document underneath. |
shownParts |
readonly string[] |
required | The parts the projection showed. |
semanticDiffParts |
readonly string[] |
required | The parts the surface counted as the semantic diff. |
PreviewSurface#
(typeof PREVIEW_SURFACES)[number];
ProposedOperation#
One atomic part of a proposal.
| Field | Type | Required | Notes |
|---|---|---|---|
partId |
string |
required | — |
changeType |
ChangeType | required | — |
significance |
DiffSignificance | required | — |
path |
readonly string[] |
required | Stable, sortable address. Rendered by a client; never parsed by one. |
anchor |
StableAnchor | required | — |
from |
DiffValue | required | — |
to |
DiffValue | required | — |
requires |
readonly string[] |
required | Parts this one cannot be admitted without. |
proposingAuthorities#
Every authority that has put content into this object, from the history alone.
proposingAuthorities(history: readonly RevisionRecord[]): readonly string[]
revalidate#
The six questions, asked at the moment of acceptance.
revalidate(input: RevalidationInput): RevalidationReport
REVALIDATION_CHECKS#
The six the item names, in the order they are cheapest to answer.
Values: target-revision, anchor, schema, authorization, validation,
dependencies
REVALIDATION_FAULTS#
Values: accepted-without-resolving-the-anchor,
accepted-onto-an-orphaned-anchor, accepted-on-a-rebase-below-the-threshold,
accepted-under-a-schema-that-moved,
accepted-without-checking-the-proposer-s-authorization,
accepted-on-a-lapsed-authorization,
accepted-without-revalidating-the-content,
accepted-content-that-no-longer-validates,
dependency-not-checked-at-acceptance, dependency-absent-at-acceptance,
revalidated-at-submit-rather-than-at-apply,
accepted-after-the-proposal-expired,
accepted-a-proposal-that-had-already-ended,
head-that-belongs-to-another-entity
RevalidationCheck#
(typeof REVALIDATION_CHECKS)[number];
RevalidationFault#
(typeof REVALIDATION_FAULTS)[number];
RevalidationInput#
| Field | Type | Required | Notes |
|---|---|---|---|
suggestion |
SuggestionRecord | required | — |
head |
RevisionRef | required | The revision the acceptance would be written onto. |
anchorResolution |
AnchorResolution | null — AnchorResolution |
required | The proposal's anchor resolved against head, or null if nothing resolved it. |
confidenceThreshold |
number |
optional | — |
proposerStillPermitted |
boolean | null |
required | Whether the PROPOSER would still be permitted to make this proposal. |
contentStillValid |
boolean | null |
required | Whether the proposed content still validates. Null when nobody ran it. |
dependencies |
readonly DependencyState[] — DependencyState |
required | — |
evaluatedAt |
PreconditionEvaluatedAt | required | S2.10's distinction: a check taken at submit is a check taken too early. |
at |
Instant | required | — |
RevalidationReport#
| Field | Type | Required | Notes |
|---|---|---|---|
verdicts |
Readonly<Record<RevalidationCheck, CheckVerdict>> — CheckVerdict, RevalidationCheck |
required | — |
admissible |
boolean |
required | Whether an acceptance may proceed on this report. |
findings |
readonly SuggestionFinding[] — SuggestionFinding |
required | — |
applyAt |
StableAnchor | null — StableAnchor |
required | The anchor the change must be applied at. |
STATE_FOR_ENDING#
The state each ending kind puts a proposal into. One mapping, not two.
SUGGESTION_CAPABILITIES#
Values: propose, edit-directly, accept, approve
SUGGESTION_FAULTS#
SUGGESTION_SCHEMA_FAULTS#
Values: two-proposals-with-one-id, two-parts-with-one-id,
proposal-with-no-parts, part-that-requires-itself,
part-that-requires-a-part-that-is-not-in-the-proposal, requirement-cycle,
part-that-proposes-the-value-already-there, proposal-with-no-rationale,
evidence-with-no-reference,
proposal-anchored-at-a-revision-that-is-not-its-base,
part-anchored-at-a-revision-that-is-not-its-base,
proposal-anchored-against-another-entity,
proposal-that-expires-before-it-was-made,
expired-proposal-that-declared-no-expiry,
terminal-proposal-with-neither-an-acceptance-nor-an-ending,
live-proposal-carrying-an-ending, live-proposal-carrying-an-acceptance,
proposal-both-accepted-and-ended, state-that-does-not-match-its-ending,
accepted-proposal-that-names-no-revision, acceptance-with-no-parts,
acceptance-of-a-part-that-is-not-in-the-proposal,
whole-acceptance-recorded-as-partial, partial-acceptance-recorded-as-whole,
machine-authored-proposal-presented-as-a-person,
delegated-proposal-attributed-to-the-principal-alone,
proposal-attributed-to-somebody-who-did-not-write-it
SUGGESTION_STATES#
Where a proposal has got to.
Values: proposed, accepted, partially-accepted, rejected, withdrawn,
expired, superseded
SuggestionCapability#
(typeof SUGGESTION_CAPABILITIES)[number];
SuggestionEnding#
How a proposal ended without being admitted.
| { readonly kind: 'rejected'; readonly by: ActorRef; readonly at: Instant; readonly reason: string; }
| { readonly kind: 'withdrawn'; readonly by: ActorRef; readonly at: Instant; readonly reason: string; }
| { readonly kind: 'expired'; readonly at: Instant }
| { readonly kind: 'superseded'; readonly by: ActorRef; readonly at: Instant; readonly supersededBy: string; readonly reason: string; }
SuggestionEvidence#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
EvidenceKind | required | — |
reference |
string |
required | What the reader follows. Required and non-empty. |
note |
string |
required | The proposer's own words about it. May be empty; the reference may not. |
SuggestionFault#
| SuggestionSchemaFault
| IsolationFault
| PermissionFault
| RevalidationFault
| AcceptanceFault
| EndingFault
| LinkFault
SuggestionFinding#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
SuggestionFault | required | — |
subject |
string |
required | — |
detail |
string |
required | — |
suggestionHeadline#
One line for an operator: what happened to a review's proposals.
suggestionHeadline(ledger: SuggestionLedger): string
SuggestionLedger#
| Field | Type | Required | Notes |
|---|---|---|---|
total |
number |
required | — |
byState |
Readonly<Record<SuggestionState, number>> — SuggestionState |
required | — |
admitted |
number |
required | Proposals that produced a revision, whole or in part. |
credited |
number |
required | Admitted proposals whose revision credits the proposer. |
uncredited |
number |
required | — |
SuggestionRecord#
A proposal, as it is stored.
| Field | Type | Required | Notes |
|---|---|---|---|
suggestionId |
string |
required | — |
tenant |
TenantId | required | — |
targetId |
string |
required | — |
threadId |
string | null |
required | The discussion this proposal is argued in, when there is one. |
proposer |
ActorRef | required | — |
attributedTo |
string |
required | The identity the surface displays the proposal under. |
presentedAsAutomated |
boolean |
required | Whether the surface presents this proposal as machine-written. |
baseRevision |
RevisionRef | required | The revision the proposal was written against. |
anchor |
StableAnchor | required | Where in that revision the proposal is aimed. |
operations |
readonly ProposedOperation[] — ProposedOperation |
required | — |
rationale |
string |
required | Why. Required and non-empty: a patch with no argument is a demand. |
evidence |
readonly SuggestionEvidence[] — SuggestionEvidence |
required | — |
dependsOn |
readonly string[] |
required | Objects the proposal assumes exist, revalidated at acceptance. |
state |
SuggestionState | required | — |
proposedAt |
Instant | required | — |
expiresAt |
Instant | null — Instant |
required | When it lapses on its own. Null for a proposal that waits indefinitely. |
acceptance |
AcceptanceRecord | null — AcceptanceRecord |
required | — |
ending |
SuggestionEnding | null — SuggestionEnding |
required | — |
SuggestionSchemaFault#
(typeof SUGGESTION_SCHEMA_FAULTS)[number];
suggestionSchemaFaults#
Every way a stored proposal can be incoherent on its own terms.
suggestionSchemaFaults(suggestions: readonly SuggestionRecord[]): readonly SuggestionFinding[]
SuggestionState#
(typeof SUGGESTION_STATES)[number];
summarizeSuggestions#
summarizeSuggestions(suggestions: readonly SuggestionRecord[], history: readonly RevisionRecord[]): SuggestionLedger
targetsOf#
Every entity this module's records address, for a host walking a workbench.
targetsOf(suggestions: readonly SuggestionRecord[]): readonly EntityId[]
TERMINAL_SUGGESTION_STATES#
Every state but proposed, and that includes partially-accepted.
Values: accepted, partially-accepted, rejected, withdrawn, expired,
superseded
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 |
|---|---|---|
CapabilityExercise.actorId |
string |
— |
CapabilityGrant.actorId |
string |
— |
PERMISSION_FAULTS |
enumeration |
— |
PermissionFault |
type |
— |
PermissionMatrix.grants |
readonly CapabilityGrant[] |
— |
permissionMatrixFaults |
function |
— |
SuggestionRecord.tenant |
TenantId |
— |
Idempotency and concurrency#
| Symbol | Type | Notes |
|---|---|---|
AcceptanceAudit.revision |
RevisionRecord |
— |
AcceptanceRecord.producedRevision |
RevisionId |
— |
AcceptanceRequest.newRevisionId |
RevisionId |
— |
PreviewObservation.baseRevision |
RevisionId |
The proposal's base revision. |
PreviewObservation.editorBaseRevision |
RevisionId |
The editor's own base, which the projection must not have moved. |
PreviewObservation.revisionsWritten |
readonly RevisionId[] |
Revisions the host wrote while rendering. Must be empty. |
SuggestionRecord.baseRevision |
RevisionRef |
The revision the proposal was written against. |
Pagination#
Not applicable: nothing on this page returns a collection a caller reads in pages.
State and failure#
| Symbol | Type | Notes |
| ------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------- |
| AcceptanceOutcome | type | — |
| CHECK_VERDICTS | enumeration | What one check found. |
| CheckVerdict | type | — |
| isTerminalSuggestionState | function | — |
| LinkObservation.presentedAsOneState | boolean | Whether the surface renders one control for both. |
| LinkObservation.suggestionState | SuggestionState | — |
| LinkObservation.threadState | ThreadState | null | The thread's own state, when the host looked it up. |
| partSelectionRefusals | function | Which selections of parts may be admitted together. |
| RevalidationReport.verdicts | Readonly<Record<RevalidationCheck, CheckVerdict>> | — |
| STATE_FOR_ENDING | constant | The state each ending kind puts a proposal into. One mapping, not two. |
| SUGGESTION_STATES | enumeration | Where a proposal has got to. |
| SuggestionLedger.byState | Readonly<Record<SuggestionState, number>> | — |
| SuggestionRecord.state | SuggestionState | — |
| SuggestionState | type | — |
| TERMINAL_SUGGESTION_STATES | enumeration | Every state but proposed, and that includes partially-accepted. |
Compatibility#
Not applicable: nothing on this page is versioned independently of the package.
Deprecation#
Not applicable: nothing on this page can be deprecated on its own; the package version is its lifecycle.
Evidence#
evidence/v1-workbenches/workbench-kit-export-map.jsonlibs/oshun/workbench-kit/src/suggestions.ts