# Approval workflows

Who may judge a change, how many of them the stage needs once recusals and
absences are told apart, in what order the stages run, what disqualifies a
reviewer who proposed an earlier revision or holds the proposer's authority, and
what a change of revision or of policy does to an approval already given.

Generated from `libs/oshun/workbench-kit/src/approval-workflows.ts` by
`node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs`. Ledger:
S8.1. Do not edit by hand.

## Summary

- `src/approval-workflows.ts`

| Entry point                               | Runtime class | Authorized by |
| ----------------------------------------- | ------------- | ------------- |
| `@oshun/workbench-kit/approval-workflows` | `contract`    | S8.1          |

## Exports

| Symbol                                                              | Kind        | Summary                                                                                |
| ------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------- |
| [ApprovalTarget](#approvaltarget)                                   | interface   | —                                                                                      |
| [authorityOf](#authorityof)                                         | function    | Whose authority an actor is acting on.                                                 |
| [ConflictDisclosure](#conflictdisclosure)                           | interface   | —                                                                                      |
| [deriveOutcome](#deriveoutcome)                                     | function    | What the workflow has come to, from its stages.                                        |
| [eligibility](#eligibility)                                         | function    | Whether this reviewer may take a seat in this stage, and why not where they may not.   |
| [ELIGIBILITY_REASONS](#eligibility_reasons)                         | enumeration | The reasons an actor is or is not eligible for a stage.                                |
| [EligibilityQuestion](#eligibilityquestion)                         | interface   | —                                                                                      |
| [EligibilityReason](#eligibilityreason)                             | type        | —                                                                                      |
| [KINDS_THAT_MAY_NOT_JUDGE](#kinds_that_may_not_judge)               | enumeration | Actor kinds that may never hold a seat in an approval.                                 |
| [LIFECYCLES_THAT_FORBID_APPROVAL](#lifecycles_that_forbid_approval) | enumeration | Object lifecycle states in which no approval may be collected at all.                  |
| [POPULATION_RULES](#population_rules)                               | constant    | The truth table, written out as data so a test can assert it row by row.               |
| [populationRule](#populationrule)                                   | function    | —                                                                                      |
| [PopulationRule](#populationrule)                                   | interface   | —                                                                                      |
| [QuorumReading](#quorumreading)                                     | interface   | —                                                                                      |
| [readQuorum](#readquorum)                                           | function    | The stage's quorum over a set of seats.                                                |
| [REVIEWER_POPULATIONS](#reviewer_populations)                       | enumeration | The nine populations the item names, and the three columns that matter.                |
| [ReviewerPool](#reviewerpool)                                       | interface   | —                                                                                      |
| [ReviewerPopulation](#reviewerpopulation)                           | type        | —                                                                                      |
| [ReviewerProfile](#reviewerprofile)                                 | interface   | —                                                                                      |
| [SeatState](#seatstate)                                             | interface   | —                                                                                      |
| [STAGE_KINDS](#stage_kinds)                                         | enumeration | What a stage does with the verdicts it collects.                                       |
| [STAGE_VERDICTS](#stage_verdicts)                                   | enumeration | What one reviewer said.                                                                |
| [StageDefinition](#stagedefinition)                                 | interface   | —                                                                                      |
| [StageKind](#stagekind)                                             | type        | —                                                                                      |
| [StageObservation](#stageobservation)                               | interface   | —                                                                                      |
| [stageStanding](#stagestanding)                                     | function    | The stage's own quorum, checked against S2.13's signature rules as well.               |
| [StageVerdict](#stageverdict)                                       | type        | —                                                                                      |
| [TERMINAL_OUTCOMES](#terminal_outcomes)                             | enumeration | Outcomes after which nothing further may be recorded.                                  |
| [WORKFLOW_FAULTS](#workflow_faults)                                 | enumeration | —                                                                                      |
| [WORKFLOW_OUTCOMES](#workflow_outcomes)                             | enumeration | How a whole workflow ends, and the two that are not verdicts.                          |
| [WORKFLOW_ROLES](#workflow_roles)                                   | enumeration | A named role in the workflow's own vocabulary, used by the separation-of-duties rules. |
| [WorkflowDefinition](#workflowdefinition)                           | interface   | —                                                                                      |
| [WorkflowFault](#workflowfault)                                     | type        | —                                                                                      |
| [workflowFaults](#workflowfaults)                                   | function    | The workflow audit.                                                                    |
| [WorkflowFinding](#workflowfinding)                                 | interface   | —                                                                                      |
| [workflowHeadline](#workflowheadline)                               | function    | The sentence the audit reports.                                                        |
| [WorkflowObservation](#workflowobservation)                         | interface   | —                                                                                      |
| [WorkflowOutcome](#workflowoutcome)                                 | type        | —                                                                                      |
| [WorkflowRole](#workflowrole)                                       | type        | —                                                                                      |
| [workflowSummary](#workflowsummary)                                 | function    | —                                                                                      |
| [WorkflowSummary](#workflowsummary)                                 | interface   | —                                                                                      |

## Shapes

#### ApprovalTarget

| Field        | Type                                   | Required | Notes                                                         |
| ------------ | -------------------------------------- | -------- | ------------------------------------------------------------- |
| `targetId`   | `string`                               | required | —                                                             |
| `revision`   | [RevisionId](./identity.md#revisionid) | required | —                                                             |
| `proposedBy` | `string`                               | required | The revision each earlier stage was judged against, by stage. |

#### authorityOf

Whose authority an actor is acting on.

```ts
authorityOf(actor: ActorRef): string
```

#### ConflictDisclosure

| Field                  | Type             | Required | Notes                                                     |
| ---------------------- | ---------------- | -------- | --------------------------------------------------------- |
| `conflictId`           | `string`         | required | —                                                         |
| `disclosedBy`          | `string`         | required | —                                                         |
| `stageId`              | `string`         | required | —                                                         |
| `detailIsConfidential` | `boolean`        | required | Whether the disclosure carries confidential detail.       |
| `recused`              | `boolean`        | required | Whether the disclosing reviewer stepped out of the stage. |
| `overriddenBy`         | `string \| null` | required | Who overrode the recusal, or null where nobody did.       |

#### deriveOutcome

What the workflow has come to, from its stages.

```ts
deriveOutcome(observation: WorkflowObservation): WorkflowOutcome
```

#### eligibility

Whether this reviewer may take a seat in this stage, and why not where they may
not.

```ts
eligibility(question: EligibilityQuestion): EligibilityReason
```

#### ELIGIBILITY_REASONS

The reasons an actor is or is not eligible for a stage.

Values: `eligible`, `wrong-tenant`, `not-in-the-pool`,
`lacks-the-specialist-qualification`, `delegated-scope-does-not-cover-this`,
`object-lifecycle-forbids-it`, `not-assigned`, `actor-kind-may-not-judge`

#### EligibilityQuestion

| Field             | Type                                | Required | Notes |
| ----------------- | ----------------------------------- | -------- | ----- |
| `stage`           | [StageDefinition](#stagedefinition) | required | —     |
| `pool`            | [ReviewerPool](#reviewerpool)       | required | —     |
| `reviewer`        | [ReviewerProfile](#reviewerprofile) | required | —     |
| `objectLifecycle` | `string`                            | required | —     |

#### EligibilityReason

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

#### KINDS_THAT_MAY_NOT_JUDGE

Actor kinds that may never hold a seat in an approval.

Values: `service`, `system`, `delegated`, `redacted`

#### LIFECYCLES_THAT_FORBID_APPROVAL

Object lifecycle states in which no approval may be collected at all.

Values: `draft`, `withdrawn`, `archived`, `deleted`

#### POPULATION_RULES

The truth table, written out as data so a test can assert it row by row.

#### populationRule

```ts
populationRule(population: ReviewerPopulation): PopulationRule
```

#### PopulationRule

| Field                | Type                                      | Required | Notes |
| -------------------- | ----------------------------------------- | -------- | ----- |
| `population`         | [ReviewerPopulation](#reviewerpopulation) | required | —     |
| `countsTowardQuorum` | `boolean`                                 | required | —     |
| `staysInThePool`     | `boolean`                                 | required | —     |
| `lowersTheBar`       | `boolean`                                 | required | —     |

#### QuorumReading

| Field         | Type      | Required | Notes                                                        |
| ------------- | --------- | -------- | ------------------------------------------------------------ |
| `declared`    | `number`  | required | The stage's declared quorum before any reduction.            |
| `required`    | `number`  | required | What it is after recusals shrank the pool.                   |
| `approving`   | `number`  | required | Distinct authorities that approved.                          |
| `poolSize`    | `number`  | required | Distinct authorities still able to take part.                |
| `satisfied`   | `boolean` | required | —                                                            |
| `unreachable` | `boolean` | required | True where the bar can no longer be reached by anybody left. |

#### readQuorum

The stage's quorum over a set of seats.

```ts
readQuorum(stage: StageDefinition, seats: readonly SeatState[]): QuorumReading
```

#### REVIEWER_POPULATIONS

The nine populations the item names, and the three columns that matter.

Values: `eligible`, `completed`, `approving`, `rejecting`, `abstaining`,
`recused`, `replaced`, `unavailable`, `delegated`

#### ReviewerPool

| Field                   | Type                | Required | Notes                                                         |
| ----------------------- | ------------------- | -------- | ------------------------------------------------------------- |
| `poolId`                | `string`            | required | —                                                             |
| `tenant`                | `string`            | required | —                                                             |
| `members`               | `readonly string[]` | required | —                                                             |
| `requiredQualification` | `string \| null`    | required | A qualification every member of this pool must hold to judge. |

#### ReviewerPopulation

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

#### ReviewerProfile

| Field              | Type                                                                                   | Required | Notes                                                                                                                                    |
| ------------------ | -------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `actor`            | [ActorRef](./identity.md#actorref)                                                     | required | —                                                                                                                                        |
| `tenant`           | `string`                                                                               | required | —                                                                                                                                        |
| `qualifications`   | `readonly string[]`                                                                    | required | —                                                                                                                                        |
| `assignedStageIds` | `readonly string[]`                                                                    | required | The stages this actor was assigned to, where the workflow assigns rather than opening to a pool. Empty means the pool is the assignment. |
| `delegation`       | `{ readonly fromActorId: string; readonly scopeStageIds: readonly string[]; } \| null` | required | A delegated authority this actor holds, or null.                                                                                         |

#### SeatState

| Field         | Type                                      | Required | Notes                                                                     |
| ------------- | ----------------------------------------- | -------- | ------------------------------------------------------------------------- |
| `actorId`     | `string`                                  | required | The person occupying the seat.                                            |
| `authorityId` | `string`                                  | required | The authority the seat draws on: the same actor, or whoever delegated it. |
| `population`  | [ReviewerPopulation](#reviewerpopulation) | required | —                                                                         |

#### STAGE_KINDS

What a stage does with the verdicts it collects.

Values: `sequential`, `parallel`, `conditional`, `escalation`, `veto`

#### STAGE_VERDICTS

What one reviewer said.

Values: `approved`, `rejected`, `abstained`

#### StageDefinition

| Field            | Type                          | Required | Notes                                                                    |
| ---------------- | ----------------------------- | -------- | ------------------------------------------------------------------------ |
| `stageId`        | `string`                      | required | —                                                                        |
| `kind`           | [StageKind](#stagekind)       | required | —                                                                        |
| `order`          | `number`                      | required | Position in the workflow. Stages run in ascending order.                 |
| `role`           | [WorkflowRole](#workflowrole) | required | The role a signature in this stage is given in.                          |
| `quorum`         | `number`                      | required | How many distinct authorities must approve.                              |
| `poolId`         | `string`                      | required | The pool this stage draws from, by identifier.                           |
| `repeatOnChange` | `boolean`                     | required | Whether a material change to the target reopens this stage.              |
| `condition`      | `string \| null`              | required | For `conditional`: the declared condition, or null where it always runs. |
| `vetoHolders`    | `readonly string[]`           | required | For `veto`: the authorities that hold it. Empty on every other kind.     |
| `escalatesFrom`  | `string \| null`              | required | For `escalation`: the stage it escalates from, or null.                  |
| `deadlineHours`  | `number \| null`              | required | How long the stage has, in hours, before it is escalated or expires.     |

#### StageKind

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

#### StageObservation

| Field                             | Type                                                                            | Required | Notes                                                                     |
| --------------------------------- | ------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------- |
| `stageId`                         | `string`                                                                        | required | —                                                                         |
| `seats`                           | `readonly SeatState[]` — [SeatState](#seatstate)                                | required | —                                                                         |
| `records`                         | `readonly SignoffRecord[]` — [SignoffRecord](./plugin.md#signoffrecord)         | required | Signatures collected in this stage, in the shape S2.13 records them.      |
| `signedAgainstRevision`           | `Readonly<Record<string, RevisionId>>` — [RevisionId](./identity.md#revisionid) | required | The revision each signature was given against.                            |
| `signedUnderPolicyVersion`        | `Readonly<Record<string, string>>`                                              | required | The workflow policy version each signature was given under.               |
| `appliedQuorum`                   | `number`                                                                        | required | The quorum the deployment actually enforced for this stage.               |
| `completedAt`                     | `Instant \| null` — [Instant](./identity.md#instant)                            | required | —                                                                         |
| `reopenedSinceLastMaterialChange` | `boolean`                                                                       | required | Whether this stage was reopened after the target last changed materially. |
| `vetoedBy`                        | `string \| null`                                                                | required | —                                                                         |

#### stageStanding

The stage's own quorum, checked against S2.13's signature rules as well.

```ts
stageStanding(stage: StageDefinition, observation: StageObservation, requirement: HumanGateRequirement, authorId: string): { readonly quorum: QuorumReading; readonly signatureFaults: number }
```

#### StageVerdict

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

#### TERMINAL_OUTCOMES

Outcomes after which nothing further may be recorded.

Values: `approved`, `rejected`, `vetoed`, `withdrawn`, `expired`

#### WORKFLOW_FAULTS

Values: `workflow-has-no-stage`, `two-stages-claim-one-position`,
`veto-stage-names-no-holder`, `veto-held-by-someone-outside-the-pool`,
`conditional-stage-states-no-condition`,
`escalation-from-a-stage-that-does-not-exist`,
`escalation-before-the-stage-it-escalates`,
`stage-with-a-deadline-nobody-escalates-to`, `quorum-larger-than-the-pool`,
`quorum-below-one`, `seat-counted-twice-for-one-authority`,
`quorum-unreachable-by-anybody-left`, `unavailability-lowered-the-bar`,
`applied-quorum-below-what-the-populations-justify`,
`stage-approved-out-of-order`, `stage-completed-while-an-earlier-one-is-open`,
`reviewer-not-eligible-for-the-stage-they-judged`, `self-approval`,
`separation-of-duties-broken-across-revisions`,
`separation-of-duties-laundered-through-a-delegation`,
`conflict-disclosed-without-a-recusal-or-an-override`,
`recusal-override-by-the-conflicted-party`, `recusal-override-by-the-proposer`,
`conflict-detail-required-to-count-the-quorum`,
`approval-against-a-revision-that-has-moved`,
`approval-against-a-policy-version-that-has-moved`,
`material-change-did-not-reopen-a-repeat-on-change-stage`,
`record-added-after-a-terminal-outcome`,
`veto-recorded-without-ending-the-workflow`, `workflow-not-observed`

#### WORKFLOW_OUTCOMES

How a whole workflow ends, and the two that are not verdicts.

Values: `approved`, `rejected`, `vetoed`, `withdrawn`, `expired`, `in-progress`

#### WORKFLOW_ROLES

A named role in the workflow's own vocabulary, used by the separation-of-duties
rules.

Values: `proposer`, `reviewer`, `approver`, `publisher`

#### WorkflowDefinition

| Field           | Type                                                               | Required | Notes                                                                                                                                                     |
| --------------- | ------------------------------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workflowId`    | `string`                                                           | required | —                                                                                                                                                         |
| `policyVersion` | `string`                                                           | required | The version of THIS DEFINITION, pinned into every signature collected under it (S8.1.g). Without it a stored approval cannot say which rule it satisfied. |
| `stages`        | `readonly StageDefinition[]` — [StageDefinition](#stagedefinition) | required | —                                                                                                                                                         |

#### WorkflowFault

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

#### workflowFaults

The workflow audit.

```ts
workflowFaults(observations: readonly WorkflowObservation[]): readonly WorkflowFinding[]
```

#### WorkflowFinding

| Field     | Type                            | Required | Notes |
| --------- | ------------------------------- | -------- | ----- |
| `kind`    | [WorkflowFault](#workflowfault) | required | —     |
| `subject` | `string`                        | required | —     |
| `detail`  | `string`                        | required | —     |

#### workflowHeadline

The sentence the audit reports.

```ts
workflowHeadline(summary: WorkflowSummary): string
```

#### WorkflowObservation

| Field                      | Type                                                                                | Required | Notes                                                                       |
| -------------------------- | ----------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------- |
| `definition`               | [WorkflowDefinition](#workflowdefinition)                                           | required | —                                                                           |
| `target`                   | [ApprovalTarget](#approvaltarget)                                                   | required | —                                                                           |
| `materialChangeSinceStart` | `boolean`                                                                           | required | The revision the target was on when each stage's signatures were taken.     |
| `outcome`                  | [WorkflowOutcome](#workflowoutcome)                                                 | required | —                                                                           |
| `stages`                   | `readonly StageObservation[]` — [StageObservation](#stageobservation)               | required | —                                                                           |
| `disclosures`              | `readonly ConflictDisclosure[]` — [ConflictDisclosure](#conflictdisclosure)         | required | —                                                                           |
| `roleHistory`              | `Readonly<Record<WorkflowRole, readonly string[]>>` — [WorkflowRole](#workflowrole) | required | Every authority that has ever held each role on this object, all revisions. |
| `recordsAfterTerminal`     | `number`                                                                            | required | Records added after the workflow reached a terminal outcome.                |
| `pools`                    | `readonly ReviewerPool[]` — [ReviewerPool](#reviewerpool)                           | required | —                                                                           |
| `reviewers`                | `readonly ReviewerProfile[]` — [ReviewerProfile](#reviewerprofile)                  | required | —                                                                           |
| `objectLifecycle`          | `string`                                                                            | required | —                                                                           |

#### WorkflowOutcome

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

#### WorkflowRole

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

#### workflowSummary

```ts
workflowSummary(observations: readonly WorkflowObservation[]): WorkflowSummary
```

#### WorkflowSummary

| Field                 | Type     | Required | Notes |
| --------------------- | -------- | -------- | ----- |
| `workflows`           | `number` | required | —     |
| `stages`              | `number` | required | —     |
| `seats`               | `number` | required | —     |
| `deadlocked`          | `number` | required | —     |
| `outcomesDisagreeing` | `number` | required | —     |
| `disclosures`         | `number` | required | —     |
| `recusals`            | `number` | required | —     |

## 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                          |
| ------------------------ | ---------- | ------------------------------ |
| `ReviewerPool.tenant`    | `string`   | —                              |
| `ReviewerProfile.actor`  | `ActorRef` | —                              |
| `ReviewerProfile.tenant` | `string`   | —                              |
| `SeatState.actorId`      | `string`   | The person occupying the seat. |

## Idempotency and concurrency

| Symbol                                   | Type                                   | Notes                                          |
| ---------------------------------------- | -------------------------------------- | ---------------------------------------------- |
| `ApprovalTarget.revision`                | `RevisionId`                           | —                                              |
| `StageObservation.signedAgainstRevision` | `Readonly<Record<string, RevisionId>>` | The revision each signature was given against. |

## Pagination

Not applicable: nothing on this page returns a collection a caller reads in
pages.

## State and failure

| Symbol                                | Type              | Notes                                                         |
| ------------------------------------- | ----------------- | ------------------------------------------------------------- |
| `deriveOutcome`                       | `function`        | What the workflow has come to, from its stages.               |
| `STAGE_VERDICTS`                      | `enumeration`     | What one reviewer said.                                       |
| `StageVerdict`                        | `type`            | —                                                             |
| `TERMINAL_OUTCOMES`                   | `enumeration`     | Outcomes after which nothing further may be recorded.         |
| `WORKFLOW_OUTCOMES`                   | `enumeration`     | How a whole workflow ends, and the two that are not verdicts. |
| `WorkflowObservation.outcome`         | `WorkflowOutcome` | —                                                             |
| `WorkflowOutcome`                     | `type`            | —                                                             |
| `WorkflowSummary.outcomesDisagreeing` | `number`          | —                                                             |

## Compatibility

| Symbol                                      | Type                               | Notes                                                                                                                                                     |
| ------------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `StageObservation.signedUnderPolicyVersion` | `Readonly<Record<string, string>>` | The workflow policy version each signature was given under.                                                                                               |
| `WorkflowDefinition.policyVersion`          | `string`                           | The version of THIS DEFINITION, pinned into every signature collected under it (S8.1.g). Without it a stored approval cannot say which rule it satisfied. |

## Deprecation

| Symbol                                | Type          | Notes                                                                 |
| ------------------------------------- | ------------- | --------------------------------------------------------------------- |
| `EligibilityQuestion.objectLifecycle` | `string`      | —                                                                     |
| `LIFECYCLES_THAT_FORBID_APPROVAL`     | `enumeration` | Object lifecycle states in which no approval may be collected at all. |
| `WorkflowObservation.objectLifecycle` | `string`      | —                                                                     |

## Evidence

- `evidence/v1-workbenches/workbench-kit-export-map.json`
- `libs/oshun/workbench-kit/src/approval-workflows.ts`
