# Suggestions

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](#acceptance_confidence_threshold) | constant    | The confidence a rebase must reach before an acceptance may rely on it.        |
| [ACCEPTANCE_FAULTS](#acceptance_faults)                             | enumeration | —                                                                              |
| [AcceptanceAudit](#acceptanceaudit)                                 | interface   | What a host actually wrote, checked against the proposal it claims to be.      |
| [AcceptanceFault](#acceptancefault)                                 | type        | —                                                                              |
| [acceptanceFaults](#acceptancefaults)                               | function    | —                                                                              |
| [AcceptanceOutcome](#acceptanceoutcome)                             | type        | —                                                                              |
| [AcceptanceRecord](#acceptancerecord)                               | interface   | —                                                                              |
| [AcceptanceRequest](#acceptancerequest)                             | interface   | —                                                                              |
| [acceptSuggestion](#acceptsuggestion)                               | function    | Admit a proposal, or say why not.                                              |
| [CapabilityExercise](#capabilityexercise)                           | interface   | What a host decided when somebody exercised one of the four rights.            |
| [CapabilityGrant](#capabilitygrant)                                 | interface   | —                                                                              |
| [CapabilityRule](#capabilityrule)                                   | interface   | How a deployment ties two rights together.                                     |
| [CHECK_VERDICTS](#check_verdicts)                                   | enumeration | What one check found.                                                          |
| [CheckVerdict](#checkverdict)                                       | type        | —                                                                              |
| [DependencyState](#dependencystate)                                 | interface   | —                                                                              |
| [ENDING_FAULTS](#ending_faults)                                     | enumeration | —                                                                              |
| [ENDING_KINDS](#ending_kinds)                                       | enumeration | —                                                                              |
| [EndingContext](#endingcontext)                                     | interface   | —                                                                              |
| [EndingFault](#endingfault)                                         | type        | —                                                                              |
| [endingFaults](#endingfaults)                                       | function    | Whether ending a proposal ended it and did nothing else.                       |
| [EndingKind](#endingkind)                                           | type        | —                                                                              |
| [EVIDENCE_KINDS](#evidence_kinds)                                   | enumeration | What a proposal offers in support of itself.                                   |
| [EvidenceKind](#evidencekind)                                       | type        | —                                                                              |
| [ISOLATION_FAULTS](#isolation_faults)                               | enumeration | —                                                                              |
| [IsolationFault](#isolationfault)                                   | type        | —                                                                              |
| [isolationFaults](#isolationfaults)                                 | function    | Whether showing a proposal left the document, and its author's work, alone.    |
| [isTerminalSuggestionState](#isterminalsuggestionstate)             | function    | —                                                                              |
| [LINK_FAULTS](#link_faults)                                         | enumeration | —                                                                              |
| [LinkFault](#linkfault)                                             | type        | —                                                                              |
| [linkFaults](#linkfaults)                                           | function    | —                                                                              |
| [LinkObservation](#linkobservation)                                 | interface   | —                                                                              |
| [partSelectionRefusals](#partselectionrefusals)                     | function    | Which selections of parts may be admitted together.                            |
| [PERMISSION_FAULTS](#permission_faults)                             | enumeration | —                                                                              |
| [PermissionFault](#permissionfault)                                 | type        | —                                                                              |
| [PermissionMatrix](#permissionmatrix)                               | interface   | —                                                                              |
| [permissionMatrixFaults](#permissionmatrixfaults)                   | function    | —                                                                              |
| [PREVIEW_SURFACES](#preview_surfaces)                               | enumeration | How a proposal is shown. Only the first can reach the authoring buffer.        |
| [PreviewObservation](#previewobservation)                           | interface   | One rendering of a proposal, described by the surface that rendered it.        |
| [PreviewSurface](#previewsurface)                                   | type        | —                                                                              |
| [ProposedOperation](#proposedoperation)                             | interface   | One atomic part of a proposal.                                                 |
| [proposingAuthorities](#proposingauthorities)                       | function    | Every authority that has put content into this object, from the history alone. |
| [revalidate](#revalidate)                                           | function    | The six questions, asked at the moment of acceptance.                          |
| [REVALIDATION_CHECKS](#revalidation_checks)                         | enumeration | The six the item names, in the order they are cheapest to answer.              |
| [REVALIDATION_FAULTS](#revalidation_faults)                         | enumeration | —                                                                              |
| [RevalidationCheck](#revalidationcheck)                             | type        | —                                                                              |
| [RevalidationFault](#revalidationfault)                             | type        | —                                                                              |
| [RevalidationInput](#revalidationinput)                             | interface   | —                                                                              |
| [RevalidationReport](#revalidationreport)                           | interface   | —                                                                              |
| [STATE_FOR_ENDING](#state_for_ending)                               | constant    | The state each ending kind puts a proposal into. One mapping, not two.         |
| [SUGGESTION_CAPABILITIES](#suggestion_capabilities)                 | enumeration | —                                                                              |
| [SUGGESTION_FAULTS](#suggestion_faults)                             | constant    | —                                                                              |
| [SUGGESTION_SCHEMA_FAULTS](#suggestion_schema_faults)               | enumeration | —                                                                              |
| [SUGGESTION_STATES](#suggestion_states)                             | enumeration | Where a proposal has got to.                                                   |
| [SuggestionCapability](#suggestioncapability)                       | type        | —                                                                              |
| [SuggestionEnding](#suggestionending)                               | type        | How a proposal ended without being admitted.                                   |
| [SuggestionEvidence](#suggestionevidence)                           | interface   | —                                                                              |
| [SuggestionFault](#suggestionfault)                                 | type        | —                                                                              |
| [SuggestionFinding](#suggestionfinding)                             | interface   | —                                                                              |
| [suggestionHeadline](#suggestionheadline)                           | function    | One line for an operator: what happened to a review's proposals.               |
| [SuggestionLedger](#suggestionledger)                               | interface   | —                                                                              |
| [SuggestionRecord](#suggestionrecord)                               | interface   | A proposal, as it is stored.                                                   |
| [SuggestionSchemaFault](#suggestionschemafault)                     | type        | —                                                                              |
| [suggestionSchemaFaults](#suggestionschemafaults)                   | function    | Every way a stored proposal can be incoherent on its own terms.                |
| [SuggestionState](#suggestionstate)                                 | type        | —                                                                              |
| [summarizeSuggestions](#summarizesuggestions)                       | function    | —                                                                              |
| [targetsOf](#targetsof)                                             | function    | Every entity this module's records address, for a host walking a workbench.    |
| [TERMINAL_SUGGESTION_STATES](#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](#suggestionrecord)             | required | —                                                                 |
| `revision`                | [RevisionRecord](./concurrency.md#revisionrecord) | required | —                                                                 |
| `head`                    | [RevisionRecord](./concurrency.md#revisionrecord) | required | —                                                                 |
| `appliedAt`               | [StableAnchor](./identity.md#stableanchor)        | required | The anchor the change was written at.                             |
| `revalidation`            | [RevalidationReport](#revalidationreport)         | required | —                                                                 |
| `after`                   | [SuggestionRecord](#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](./identity.md#actorref)     | required | —                                                              |
| `at`               | [Instant](./identity.md#instant)       | required | —                                                              |
| `acceptedParts`    | `readonly string[]`                    | required | The parts admitted. Never empty.                               |
| `producedRevision` | [RevisionId](./identity.md#revisionid) | required | —                                                              |
| `amended`          | `boolean`                              | required | Whether the accepter changed the proposal before admitting it. |
| `reason`           | `string`                               | required | —                                                              |

#### AcceptanceRequest

| Field                     | Type                                              | Required | Notes                                                             |
| ------------------------- | ------------------------------------------------- | -------- | ----------------------------------------------------------------- |
| `suggestion`              | [SuggestionRecord](#suggestionrecord)             | required | —                                                                 |
| `parts`                   | `readonly string[]`                               | required | The parts to admit.                                               |
| `accepter`                | [ActorRef](./identity.md#actorref)                | required | —                                                                 |
| `head`                    | [RevisionRecord](./concurrency.md#revisionrecord) | required | The revision the acceptance is written onto.                      |
| `newRevisionId`           | [RevisionId](./identity.md#revisionid)            | required | —                                                                 |
| `contentHash`             | [Sha256Hex](./identity.md#sha256hex)              | required | —                                                                 |
| `at`                      | [Instant](./identity.md#instant)                  | required | —                                                                 |
| `reason`                  | `string`                                          | required | —                                                                 |
| `amended`                 | `boolean`                                         | required | Whether the accepter changed the proposal before admitting it.    |
| `revalidation`            | [RevalidationReport](#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](#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](#suggestioncapability) | required | —     |

#### CapabilityRule

How a deployment ties two rights together.

| Field      | Type                                          | Required | Notes |
| ---------- | --------------------------------------------- | -------- | ----- |
| `held`     | [SuggestionCapability](#suggestioncapability) | required | —     |
| `other`    | [SuggestionCapability](#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](./identity.md#revisionid)                        | required | The revision it was at when the proposal was written. |
| `atAcceptance` | `RevisionId \| null` — [RevisionId](./identity.md#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](./identity.md#sha256hex)                               | required | The object's content hash before and after the ending. Must not move. |
| `contentHashAfter`  | [Sha256Hex](./identity.md#sha256hex)                               | required | —                                                                     |
| `headBefore`        | [RevisionId](./identity.md#revisionid)                             | required | —                                                                     |
| `headAfter`         | [RevisionId](./identity.md#revisionid)                             | required | —                                                                     |
| `audited`           | `boolean`                                                          | required | —                                                                     |
| `successor`         | `SuggestionRecord \| null` — [SuggestionRecord](#suggestionrecord) | required | The proposal named by a supersession, when the host could find it.    |
| `now`               | [Instant](./identity.md#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
```

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

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

#### linkFaults

```ts
linkFaults(observation: LinkObservation): readonly SuggestionFinding[]
```

#### LinkObservation

| Field                                   | Type                                                                    | Required | Notes                                                                |
| --------------------------------------- | ----------------------------------------------------------------------- | -------- | -------------------------------------------------------------------- |
| `suggestionId`                          | `string`                                                                | required | —                                                                    |
| `suggestionState`                       | [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](./comment-threads.md#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](#capabilitygrant) | required | —     |
| `rules`  | `readonly CapabilityRule[]` — [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](#previewsurface)                                               | required | —                                                                                                                       |
| `computedAgainst`               | [RevisionId](./identity.md#revisionid)                                          | required | The revision the projection was computed on top of.                                                                     |
| `baseRevision`                  | [RevisionId](./identity.md#revisionid)                                          | required | The proposal's base revision.                                                                                           |
| `rebase`                        | `AnchorResolution \| null` — [AnchorResolution](./identity.md#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](./identity.md#revisionid)                                          | required | The revision the editor's dirty flag compares against while it is shown.                                                |
| `editorBaseRevision`            | [RevisionId](./identity.md#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](./identity.md#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](./concurrency.md#changetype)             | required | —                                                                    |
| `significance` | [DiffSignificance](./concurrency.md#diffsignificance) | required | —                                                                    |
| `path`         | `readonly string[]`                                   | required | Stable, sortable address. Rendered by a client; never parsed by one. |
| `anchor`       | [StableAnchor](./identity.md#stableanchor)            | required | —                                                                    |
| `from`         | [DiffValue](./concurrency.md#diffvalue)               | required | —                                                                    |
| `to`           | [DiffValue](./concurrency.md#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](#suggestionrecord)                                           | required | —                                                                              |
| `head`                   | [RevisionRef](./identity.md#revisionref)                                        | required | The revision the acceptance would be written onto.                             |
| `anchorResolution`       | `AnchorResolution \| null` — [AnchorResolution](./identity.md#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](#dependencystate)              | required | —                                                                              |
| `evaluatedAt`            | [PreconditionEvaluatedAt](./concurrency.md#preconditionevaluatedat)             | required | S2.10's distinction: a check taken at submit is a check taken too early.       |
| `at`                     | [Instant](./identity.md#instant)                                                | required | —                                                                              |

#### RevalidationReport

| Field        | Type                                                                                                                         | Required | Notes                                             |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------- |
| `verdicts`   | `Readonly<Record<RevalidationCheck, CheckVerdict>>` — [CheckVerdict](#checkverdict), [RevalidationCheck](#revalidationcheck) | required | —                                                 |
| `admissible` | `boolean`                                                                                                                    | required | Whether an acceptance may proceed on this report. |
| `findings`   | `readonly SuggestionFinding[]` — [SuggestionFinding](#suggestionfinding)                                                     | required | —                                                 |
| `applyAt`    | `StableAnchor \| null` — [StableAnchor](./identity.md#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](#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](#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](#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](./identity.md#tenantid)                                          | required | —                                                                       |
| `targetId`             | `string`                                                                    | required | —                                                                       |
| `threadId`             | `string \| null`                                                            | required | The discussion this proposal is argued in, when there is one.           |
| `proposer`             | [ActorRef](./identity.md#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](./identity.md#revisionref)                                    | required | The revision the proposal was written against.                          |
| `anchor`               | [StableAnchor](./identity.md#stableanchor)                                  | required | Where in that revision the proposal is aimed.                           |
| `operations`           | `readonly ProposedOperation[]` — [ProposedOperation](#proposedoperation)    | required | —                                                                       |
| `rationale`            | `string`                                                                    | required | Why. Required and non-empty: a patch with no argument is a demand.      |
| `evidence`             | `readonly SuggestionEvidence[]` — [SuggestionEvidence](#suggestionevidence) | required | —                                                                       |
| `dependsOn`            | `readonly string[]`                                                         | required | Objects the proposal assumes exist, revalidated at acceptance.          |
| `state`                | [SuggestionState](#suggestionstate)                                         | required | —                                                                       |
| `proposedAt`           | [Instant](./identity.md#instant)                                            | required | —                                                                       |
| `expiresAt`            | `Instant \| null` — [Instant](./identity.md#instant)                        | required | When it lapses on its own. Null for a proposal that waits indefinitely. |
| `acceptance`           | `AcceptanceRecord \| null` — [AcceptanceRecord](#acceptancerecord)          | required | —                                                                       |
| `ending`               | `SuggestionEnding \| null` — [SuggestionEnding](#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`
