Eve library

Approval workflows

Evidence

Revision 1

On this page

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.

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 required —
pool ReviewerPool required —
reviewer 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 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 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#

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

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

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