decisions/occurrence

Where an occurrence stands is a fold of its entries. This module is the whole lifecycle as one pure function, apply, and the read side of the record.

An occurrence moves through nine statuses:

Recommended ──policy──▶ Awaiting ──verdicts──▶ Accepted ──▶ Held ──▶ Released
     │  ╲                  │  ╲                   │           │ ╲
     │   consulting        │   Rejected           │           │  Withdrawn
     ▼                     ▼                      ▼           ▼
  Expired               Expired                Refused     Refused

Accepted lasts only inside a verb: an accepted output is held or released in the same transaction. Released, Rejected, Expired, Withdrawn and Refused are settled: nothing changes the outcome after that. Only assessments, effect reports and recorded refusals are appended to a settled occurrence, and, on a sampled one, its review and the showings, notes and expansions that lead to it. This is invariant I3 of decisions/testing, which lists the same entries.

import decisions/occurrence

case occurrence.final(known) {
  Some(output) -> show(output)
  None -> show_waiting(known.status)
}

Status may gain variants in a minor release; match it with a _ branch where a new status needs no decision of yours.

Target-independent: builds for Erlang and JavaScript.

Types

What really happened to an occurrence, as a follower or an agent tells someone: the settled truth, never a status in between.

It may gain variants in a minor release; keep a _ branch where a new one needs no decision of yours.

pub type Account(output) {
  Undecided
  Done(
    final: output,
    key: String,
    effect: option.Option(vocabulary.Effect),
  )
  TurnedDown(by: String, reason: vocabulary.Reason)
  Lapsed(cause: vocabulary.ExpiryCause)
  TakenBack(by: String)
  Blocked(reason: String)
}

Constructors

  • Undecided

    Nothing final yet: it waits for the policy, a consulted point or verdicts, or it is accepted and held, and can still be withdrawn.

  • Done(
      final: output,
      key: String,
      effect: option.Option(vocabulary.Effect),
    )

    Released with this final output under the release key (the key an outside effect is sent under). effect is the latest report of what happened outside the database, None while nothing is known: no report yet, or the latest one is Uncertain.

  • TurnedDown(by: String, reason: vocabulary.Reason)

    A validator rejected it.

  • Lapsed(cause: vocabulary.ExpiryCause)

    It can no longer be decided: the validity passed or an event superseded it.

  • TakenBack(by: String)

    The decider, or someone entitled to, withdrew it during its hold.

  • Blocked(reason: String)

    The guard or the gated tool refused to release it.

A recommender’s failed attempt under the occurrence’s key, before its recommendation.

pub type Attempt {
  Attempt(
    at: timestamp.Timestamp,
    trigger: vocabulary.Trigger,
    failure: model.Failure,
    evidence: List(vocabulary.Ref),
  )
}

Constructors

Who accepted the final output: a policy version, or the validator whose verdict completed the acceptance.

pub type Decider {
  ByPolicy(version: Int)
  ByValidator(subject: String)
}

Constructors

  • ByPolicy(version: Int)
  • ByValidator(subject: String)

Why entries do not fold into an occurrence.

pub type NotBegun {
  NoEntries
  NotYet(pending: Pending)
  NoRecommendation
}

Constructors

  • NoEntries

    There are no entries.

  • NotYet(pending: Pending)

    The record has not begun: it is expected, holds failed attempts, or was superseded before it began.

  • NoRecommendation

    The entries before the recommendation are not an expectation, a failed attempt or a supersession, or no recommendation follows the supersession. A store holding this was written by something other than the desk.

An occurrence: the record and everything folded from it.

pub type Occurrence(output) {
  Occurrence(
    id: String,
    point: String,
    entries: List(entry.Entry(output)),
    attempts: List(Attempt),
    trigger: vocabulary.Trigger,
    parent: option.Option(vocabulary.Parent),
    subject: vocabulary.Subject,
    requester: option.Option(String),
    context: vocabulary.Manifest,
    recommendation: vocabulary.Recommendation(output),
    valid_until: option.Option(timestamp.Timestamp),
    informed: List(#(String, vocabulary.Fact)),
    policy_version: option.Option(Int),
    later: List(policy.Step),
    sampled: Bool,
    status: Status(output),
  )
}

Constructors

A record that has not begun: no recommendation yet. A trigger was received (expected), or a recommender failed under the key (attempts), or both. ended is what ended it before it began: a newer event that superseded it, after which nothing is recommended, or its own deadline, after which a recommendation is still recorded and starts expired.

pub type Pending {
  Pending(
    id: String,
    point: String,
    subject: vocabulary.Subject,
    since: timestamp.Timestamp,
    expected: Bool,
    attempts: List(Attempt),
    valid_until: option.Option(timestamp.Timestamp),
    ended: option.Option(vocabulary.ExpiryCause),
  )
}

Constructors

Who answers for an occurrence’s outcome.

It may gain variants in a minor release; keep a _ branch where a new one needs no decision of yours.

pub type Responsible {
  ThePolicy(version: Int)
  APerson(subject: String)
}

Constructors

  • ThePolicy(version: Int)

    The policy, at this version, let it proceed.

  • APerson(subject: String)

    A person: the validator whose verdict settled it, or who withdrew it.

Where an occurrence stands. Each status carries what is meaningful in it.

pub type Status(output) {
  Recommended(consulting: option.Option(String))
  Awaiting(eligible: policy.Eligible)
  Accepted(final: output, by: Decider)
  Held(final: output, until: timestamp.Timestamp, by: Decider)
  Released(final: output, key: String, by: Decider)
  Rejected(reason: vocabulary.Reason)
  Expired(cause: vocabulary.ExpiryCause)
  Withdrawn(by: String)
  Refused(reason: String)
}

Constructors

  • Recommended(consulting: option.Option(String))

    Recommended and not yet settled by the policy. consulting names the decision point it waits for, when the policy consulted one.

  • Awaiting(eligible: policy.Eligible)

    Waiting for verdicts from whoever eligible admits.

  • Accepted(final: output, by: Decider)

    Accepted and not yet held or released. A verb never ends here.

  • Held(final: output, until: timestamp.Timestamp, by: Decider)

    Accepted, and waiting until until before release.

  • Released(final: output, key: String, by: Decider)

    The final output reached the gated tool under key.

  • Rejected(reason: vocabulary.Reason)

    A validator rejected it, for reason. Nothing is released.

  • Expired(cause: vocabulary.ExpiryCause)

    It can no longer be decided or released: its validity passed while it waited, or an event superseded it, while it waited or was held.

  • Withdrawn(by: String)

    The decider, or a holder of the point’s withdrawn_by set, took the held output back.

  • Refused(reason: String)

    The guard or the gated tool refused a release nobody waited on.

Values

pub fn account(occurrence: Occurrence(o)) -> Account(o)

What really happened, by status: see Account.

pub fn admits(
  occurrence: Occurrence(o),
  eligible: policy.Eligible,
  subject: String,
  holds: List(String),
) -> Bool

Whether one validator, holding holds, is admitted by eligible, whatever approvals it still needs: AnyoneHolding admits a holder of the set; SomeoneElseHolding a holder who neither asked nor recommended it as their own act; Either whoever any alternative admits; Several whoever its inner eligibility admits.

pub fn apply(
  occurrence: Occurrence(o),
  entry: entry.Entry(o),
) -> Occurrence(o)

One more entry. An entry that is not legal from the current status leaves the status as it is; the desk never writes one.

pub fn approvals(
  occurrence: Occurrence(o),
) -> List(#(String, List(String)))

Who has approved the output that stands, with the decision sets each held when they did, in order. A correction counts as its author’s approval of the corrected output.

pub fn as_of(
  occurrence: Occurrence(o),
  at: timestamp.Timestamp,
) -> Result(Occurrence(o), NotBegun)

The occurrence as it was known at at: only the entries appended at or before it. Error when it had not been recommended yet.

pub fn assessments(
  occurrence: Occurrence(o),
) -> List(vocabulary.Assessment(o))

What proved true later, in order.

pub fn decided_by(
  occurrence: Occurrence(o),
) -> option.Option(Responsible)

Who decided: the policy version or the validator that accepted it (also for an output later held, released or refused by the tool), the validator who rejected it, or who withdrew it. None while it waits and when it expired, since nobody decided.

pub fn drift(occurrence: Occurrence(o)) -> List(vocabulary.Ref)

The inputs marked as changed the last time the card was shown: newer revisions of context references and of the model’s reads.

pub fn due(
  occurrence: Occurrence(o),
) -> option.Option(timestamp.Timestamp)

When the occurrence next needs attention: the end of its validity while it waits, the end of its hold while it is held.

pub fn earliest(
  times: List(timestamp.Timestamp),
) -> option.Option(timestamp.Timestamp)

The earliest of some times, None when there are none.

pub fn effect(
  occurrence: Occurrence(o),
) -> option.Option(vocabulary.Effect)

The latest report of what the release did outside the database.

pub fn expansions(
  occurrence: Occurrence(o),
) -> List(#(String, vocabulary.Ref))

What validators opened beyond the card, as #(read, evidence).

pub fn final(occurrence: Occurrence(o)) -> option.Option(o)

The final output, once one is accepted.

pub fn fold(
  id: String,
  entries: List(entry.Entry(o)),
) -> Result(Occurrence(o), NotBegun)

Fold a record. An expectation, failed attempts and a supersession may come first; the recommendation, when there is one, follows them.

pub fn has_lapsed(
  occurrence: Occurrence(o),
  now: timestamp.Timestamp,
) -> Bool

Undecided, and its validity ended at or before now. No verdict, answer or policy step is accepted for it any more, whether or not the wake-up that expires it was delivered.

pub fn head(occurrence: Occurrence(o)) -> store.Head

The head a store keeps beside this occurrence: what the desk writes with every append, and what decisions/testing compares a store’s head with.

pub fn head_status(status: Status(o)) -> store.Status

The status as a head keeps it.

pub fn is_met(
  occurrence: Occurrence(o),
  eligible: policy.Eligible,
) -> Bool

Whether the approvals of the output that stands satisfy eligible. One approval admitted by it satisfies AnyoneHolding and SomeoneElseHolding; Several(count, of) needs count different approvers each admitted by of; Either is satisfied when any one of its alternatives is, each judged on the same approvals. So Either([Several(2, AnyoneHolding("finance")), AnyoneHolding("head")]) accepts on two finance approvals or on one by the head, never on one finance approval.

pub fn is_settled(status: Status(o)) -> Bool

Nothing further can happen to the outcome.

pub fn is_undecided(status: Status(o)) -> Bool

Still waiting for the policy, a consulted point, or verdicts.

pub fn notes(
  occurrence: Occurrence(o),
) -> List(#(String, String))

What validators entered from outside the card, as #(by, note).

pub fn pending_has_lapsed(
  pending: Pending,
  now: timestamp.Timestamp,
) -> Bool

Whether a record that has not begun reached its own deadline at or before now, and has not ended yet. Nothing more is expected or attempted under it, whether or not the wake-up that expires it was delivered.

pub fn pending_head(pending: Pending) -> store.Head

The head a store keeps beside a record that has not begun: Pending while it waits, due at its own deadline when it has one; Expired once a newer event superseded it or its deadline passed.

pub fn pending_wake_times(
  pending: Pending,
) -> List(timestamp.Timestamp)

Every time at which a wake-up must be delivered for a record that has not begun: its own deadline while it has not ended, none otherwise.

pub fn policy_answers(
  occurrence: Occurrence(o),
) -> List(#(timestamp.Timestamp, policy.Outcome))

Every answer the policy gave, with the time it gave it.

pub fn recommended_at(
  occurrence: Occurrence(o),
) -> timestamp.Timestamp

When the recommendation was appended.

pub fn refusals(
  occurrence: Occurrence(o),
) -> List(#(String, vocabulary.Verdict(o), String))

Verdicts whose release was refused and rolled back, as #(by, verdict, reason).

pub fn relied(occurrence: Occurrence(o)) -> List(vocabulary.Ref)

The evidence the tool’s guard read to allow the release.

pub fn reviews(
  occurrence: Occurrence(o),
) -> List(#(String, vocabulary.Verdict(o)))

Verdicts given after the fact, on a sampled occurrence.

pub fn seen(occurrence: Occurrence(o)) -> List(#(String, Int))

For each verdict, who gave it and the entry that showed the card it was given on.

pub fn standing(occurrence: Occurrence(o)) -> #(o, List(String))

The output that stands and who has approved exactly that output, in order. A correction replaces the output and counts as its corrector’s approval; approvals of the earlier output no longer count.

pub fn status_name(status: Status(o)) -> String

The stable name of a status, as a head keeps it.

pub fn verdict(
  occurrence: Occurrence(o),
) -> option.Option(#(String, vocabulary.Verdict(o)))

The first verdict the occurrence waited for, when a validator gave one.

pub fn verdicts(
  occurrence: Occurrence(o),
) -> List(#(String, vocabulary.Verdict(o)))

Every verdict the occurrence waited for, in order. More than one when the policy asked for several approvals.

pub fn wake_times(
  occurrence: Occurrence(o),
) -> List(timestamp.Timestamp)

Every time at which a wake-up must be delivered for the occurrence as it stands: the end of a hold, or the end of validity and each later policy answer while it waits. Empty once it settles.

pub fn was_expected(occurrence: Occurrence(o)) -> Bool

Whether the recommendation was expected first (decisions.expect or decisions.expect_until).

✨ Search Document