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
-
UndecidedNothing 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).effectis the latest report of what happened outside the database,Nonewhile nothing is known: no report yet, or the latest one isUncertain. -
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
-
Attempt( at: timestamp.Timestamp, trigger: vocabulary.Trigger, failure: model.Failure, evidence: List(vocabulary.Ref), )
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
-
NoEntriesThere are no entries.
-
NotYet(pending: Pending)The record has not begun: it is expected, holds failed attempts, or was superseded before it began.
-
NoRecommendationThe 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
-
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), )Arguments
- point
-
The decision point it is an occurrence of.
- entries
-
Every entry, failed attempts included, in sequence order.
- attempts
-
Failed attempts made before the recommendation.
- informed
-
Facts consulted decision points returned.
- policy_version
-
The policy version the occurrence was given, once the policy answered.
- later
-
What the applied policy will say as the occurrence goes on waiting.
- sampled
-
Sampled for a review after release.
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
-
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), )Arguments
- since
-
When the record was first written.
- expected
-
decisions.expectordecisions.expect_untilrecorded that a recommendation is expected. - valid_until
-
The record’s own deadline: the earliest its expectations carry (
decisions.expect_until),Nonewhen none does.
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.
consultingnames the decision point it waits for, when the policy consulted one. -
Awaiting(eligible: policy.Eligible)Waiting for verdicts from whoever
eligibleadmits. -
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
untilbefore 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_byset, 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).