Eve library

Suggestions

Evidence

Revision 1

On this page

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#

ts
(typeof ACCEPTANCE_FAULTS)[number];

acceptanceFaults#

ts
acceptanceFaults(audit: AcceptanceAudit): readonly SuggestionFinding[]

AcceptanceOutcome#

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

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

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

ts
(typeof ENDING_FAULTS)[number];

endingFaults#

Whether ending a proposal ended it and did nothing else.

ts
endingFaults(before: SuggestionRecord, after: SuggestionRecord, context: EndingContext): readonly SuggestionFinding[]

EndingKind#

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

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

ts
(typeof ISOLATION_FAULTS)[number];

isolationFaults#

Whether showing a proposal left the document, and its author's work, alone.

ts
isolationFaults(suggestion: SuggestionRecord, observation: PreviewObservation): readonly SuggestionFinding[]

isTerminalSuggestionState#

ts
isTerminalSuggestionState(state: SuggestionState): boolean

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#

ts
(typeof LINK_FAULTS)[number];

linkFaults#

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

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

ts
(typeof PERMISSION_FAULTS)[number];

PermissionMatrix#

Field Type Required Notes
grants readonly CapabilityGrant[] — CapabilityGrant required —
rules readonly CapabilityRule[] — CapabilityRule required —

permissionMatrixFaults#

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

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

ts
proposingAuthorities(history: readonly RevisionRecord[]): readonly string[]

revalidate#

The six questions, asked at the moment of acceptance.

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

ts
(typeof REVALIDATION_CHECKS)[number];

RevalidationFault#

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

ts
(typeof SUGGESTION_CAPABILITIES)[number];

SuggestionEnding#

How a proposal ended without being admitted.

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

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

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

ts
(typeof SUGGESTION_SCHEMA_FAULTS)[number];

suggestionSchemaFaults#

Every way a stored proposal can be incoherent on its own terms.

ts
suggestionSchemaFaults(suggestions: readonly SuggestionRecord[]): readonly SuggestionFinding[]

SuggestionState#

ts
(typeof SUGGESTION_STATES)[number];

summarizeSuggestions#

ts
summarizeSuggestions(suggestions: readonly SuggestionRecord[], history: readonly RevisionRecord[]): SuggestionLedger

targetsOf#

Every entity this module's records address, for a host walking a workbench.

ts
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.json
  • libs/oshun/workbench-kit/src/suggestions.ts