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 | interface | — |
| authorityOf | function | Whose authority an actor is acting on. |
| ConflictDisclosure | interface | — |
| deriveOutcome | function | What the workflow has come to, from its stages. |
| eligibility | function | Whether this reviewer may take a seat in this stage, and why not where they may not. |
| ELIGIBILITY_REASONS | enumeration | The reasons an actor is or is not eligible for a stage. |
| EligibilityQuestion | interface | — |
| EligibilityReason | type | — |
| KINDS_THAT_MAY_NOT_JUDGE | enumeration | Actor kinds that may never hold a seat in an approval. |
| LIFECYCLES_THAT_FORBID_APPROVAL | enumeration | Object lifecycle states in which no approval may be collected at all. |
| POPULATION_RULES | constant | The truth table, written out as data so a test can assert it row by row. |
| populationRule | function | — |
| PopulationRule | interface | — |
| QuorumReading | interface | — |
| readQuorum | function | The stage's quorum over a set of seats. |
| REVIEWER_POPULATIONS | enumeration | The nine populations the item names, and the three columns that matter. |
| ReviewerPool | interface | — |
| ReviewerPopulation | type | — |
| ReviewerProfile | interface | — |
| SeatState | interface | — |
| STAGE_KINDS | enumeration | What a stage does with the verdicts it collects. |
| STAGE_VERDICTS | enumeration | What one reviewer said. |
| StageDefinition | interface | — |
| StageKind | type | — |
| StageObservation | interface | — |
| stageStanding | function | The stage's own quorum, checked against S2.13's signature rules as well. |
| StageVerdict | type | — |
| TERMINAL_OUTCOMES | enumeration | Outcomes after which nothing further may be recorded. |
| WORKFLOW_FAULTS | enumeration | — |
| WORKFLOW_OUTCOMES | enumeration | How a whole workflow ends, and the two that are not verdicts. |
| WORKFLOW_ROLES | enumeration | A named role in the workflow's own vocabulary, used by the separation-of-duties rules. |
| WorkflowDefinition | interface | — |
| WorkflowFault | type | — |
| workflowFaults | function | The workflow audit. |
| WorkflowFinding | interface | — |
| workflowHeadline | function | The sentence the audit reports. |
| WorkflowObservation | interface | — |
| WorkflowOutcome | type | — |
| WorkflowRole | type | — |
| workflowSummary | function | — |
| WorkflowSummary | interface | — |
Shapes#
ApprovalTarget#
| Field | Type | Required | Notes |
|---|---|---|---|
targetId |
string |
required | — |
revision |
RevisionId | required | — |
proposedBy |
string |
required | The revision each earlier stage was judged against, by stage. |
authorityOf#
Whose authority an actor is acting on.
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.
deriveOutcome(observation: WorkflowObservation): WorkflowOutcome
eligibility#
Whether this reviewer may take a seat in this stage, and why not where they may not.
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 | required | — |
pool |
ReviewerPool | required | — |
reviewer |
ReviewerProfile | required | — |
objectLifecycle |
string |
required | — |
EligibilityReason#
(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#
populationRule(population: ReviewerPopulation): PopulationRule
PopulationRule#
| Field | Type | Required | Notes |
|---|---|---|---|
population |
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.
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#
(typeof REVIEWER_POPULATIONS)[number];
ReviewerProfile#
| Field | Type | Required | Notes |
|---|---|---|---|
actor |
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 | 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 | required | — |
order |
number |
required | Position in the workflow. Stages run in ascending order. |
role |
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#
(typeof STAGE_KINDS)[number];
StageObservation#
| Field | Type | Required | Notes |
|---|---|---|---|
stageId |
string |
required | — |
seats |
readonly SeatState[] — SeatState |
required | — |
records |
readonly SignoffRecord[] — SignoffRecord |
required | Signatures collected in this stage, in the shape S2.13 records them. |
signedAgainstRevision |
Readonly<Record<string, RevisionId>> — 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 |
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.
stageStanding(stage: StageDefinition, observation: StageObservation, requirement: HumanGateRequirement, authorId: string): { readonly quorum: QuorumReading; readonly signatureFaults: number }
StageVerdict#
(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 |
required | — |
WorkflowFault#
(typeof WORKFLOW_FAULTS)[number];
workflowFaults#
The workflow audit.
workflowFaults(observations: readonly WorkflowObservation[]): readonly WorkflowFinding[]
WorkflowFinding#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
WorkflowFault | required | — |
subject |
string |
required | — |
detail |
string |
required | — |
workflowHeadline#
The sentence the audit reports.
workflowHeadline(summary: WorkflowSummary): string
WorkflowObservation#
| Field | Type | Required | Notes |
|---|---|---|---|
definition |
WorkflowDefinition | required | — |
target |
ApprovalTarget | required | — |
materialChangeSinceStart |
boolean |
required | The revision the target was on when each stage's signatures were taken. |
outcome |
WorkflowOutcome | required | — |
stages |
readonly StageObservation[] — StageObservation |
required | — |
disclosures |
readonly ConflictDisclosure[] — ConflictDisclosure |
required | — |
roleHistory |
Readonly<Record<WorkflowRole, readonly string[]>> — 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 |
required | — |
reviewers |
readonly ReviewerProfile[] — ReviewerProfile |
required | — |
objectLifecycle |
string |
required | — |
WorkflowOutcome#
(typeof WORKFLOW_OUTCOMES)[number];
WorkflowRole#
(typeof WORKFLOW_ROLES)[number];
workflowSummary#
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.jsonlibs/oshun/workbench-kit/src/approval-workflows.ts