decisions/policy
A policy is versioned data that holds every condition for proceeding without a person. It reads nothing but the recommender and named facts: the output’s facts, the recommender’s signals, what consulted points returned, and the time waited.
Because it is data, a policy can be stored as a row, published by a
write, compared with ==, exported with to_json and read back with
decoder. check (or decisions.publishable, which supplies a
point’s declared facts) refuses a policy that reads a fact the point
never declares or compares a fact of the wrong type.
import decisions/fact
import decisions/policy.{
AnyoneHolding, Ask, Never, OwnAct, Policy, Proceed, When,
}
let amount = fact.number("amount")
let refunds =
Policy(
version: 2,
rules: [
When(OwnAct, Proceed(Never, None)),
When(policy.below(amount, 100.0), Proceed(Never, None)),
],
otherwise: Ask(AnyoneHolding("finance")),
)
The first rule whose condition holds decides; otherwise decides when
none does. A condition over an absent fact is unknown, stays unknown
under Not, and never matches, so what is unknown never proceeds.
Open questions, recorded here because a policy cannot yet say them:
- A condition cannot read who recommended, beyond
OwnAct. An application that needs “this model version” repeats it as a signal. - Eligibility cannot say “two approvals, at least one by a senior”.
EitherandSeveralcombine alternatives and counts; anAllover alternatives (each satisfied by the same approvals) would be a small addition todecisions/occurrence.is_met, and is not built.
Outcome, Eligible and Condition may gain variants in a minor
release. Code that matches them should keep a _ branch.
Target-independent: builds for Erlang and JavaScript.
Types
A condition over the recommender and named facts.
pub type Condition {
OwnAct
Below(fact: String, limit: Float)
AtLeast(fact: String, limit: Float)
Is(fact: String, value: vocabulary.Fact)
Known(fact: String)
All(List(Condition))
AnyOf(List(Condition))
Not(Condition)
}
Constructors
-
OwnActThe recommender is a person acting on their own authority.
-
Below(fact: String, limit: Float)The number fact is below
limit. Build it withbelow. -
AtLeast(fact: String, limit: Float)The number fact is at least
limit. Build it withat_least. -
Is(fact: String, value: vocabulary.Fact)The fact equals
value. Build it withis. -
Known(fact: String)The fact is present, such as a consulted point’s answer.
-
All(List(Condition))Every condition holds.
-
AnyOf(List(Condition))At least one condition holds.
-
Not(Condition)The condition does not hold. Unknown stays unknown.
Who may give the verdict an occurrence waits for.
pub type Eligible {
AnyoneHolding(set: String)
SomeoneElseHolding(set: String)
Either(List(Eligible))
Several(count: Int, of: Eligible)
}
Constructors
-
AnyoneHolding(set: String)Any holder of the decision set.
-
SomeoneElseHolding(set: String)A holder of the set other than whoever asked, and other than a person recommending it as their own act.
-
Either(List(Eligible))Whoever is eligible under any of these. It is satisfied when any one alternative is satisfied by the approvals given so far. It must have at least one alternative (
EmptyEither). -
Several(count: Int, of: Eligible)countdifferent validators, each admitted byof, approving the output that stands. A correction replaces that output, and approvals of the earlier output stop counting.ofmay holdEither, but noSeveralat any depth:checkrefuses that withNestedSeveral, because approvals are counted once, by the outer count.
Why a policy cannot be published for a point.
pub type Fault {
UndeclaredFact(fact: String)
WrongKind(fact: String, declared: fact.Kind, used: fact.Kind)
TooFewApprovals(count: Int)
SampleOutOfRange(per_cent: Int)
NestedSeveral
EmptyEither
NonPositiveHold(milliseconds: Int)
}
Constructors
-
UndeclaredFact(fact: String)The policy reads a fact the point never declares. It would never match and would silently ask.
-
The policy compares a fact as one type and the point declares another.
-
TooFewApprovals(count: Int)Severalasks for fewer than one approval. -
SampleOutOfRange(per_cent: Int)PerCentis outside 0 to 100. -
NestedSeveralA
Severalinside anotherSeveral, directly or throughEither. Approvals are counted once, by the outer count, so an inner count would be silently ignored. -
EmptyEitherAn
Eitherwith no alternative: the occurrence would wait in no queue, for nobody. -
NonPositiveHold(milliseconds: Int)A
Proceedholds for zero or a negative number of milliseconds.
What the policy says about a recommendation.
pub type Outcome {
Proceed(sample: Sample, hold: option.Option(duration.Duration))
Ask(eligible: Eligible)
Consult(point: String)
}
Constructors
-
Proceed(sample: Sample, hold: option.Option(duration.Duration))Proceed without a person.
samplepicks which released occurrences wait for a review after the fact.hold, when present, is an undo window on this decision: the accepted output waits that long before release, and its decider or a holder of the point’swithdrawn_byset may withdraw it meanwhile. It takes the place of the point’swith_holdfor this acceptance; without it, the point’s hold, if any, applies. Stored as"hold_ms"; a stored policy without it has no hold. -
Ask(eligible: Eligible)Wait for a verdict from whoever
eligibleadmits. -
Consult(point: String)Ask the decision point named
pointfirst. Its final output returns as facts throughdecisions.inform, and the policy current at that moment is read again with them. A policy that would consult the same point twice falls tootherwise. A later answer (aStep) that consults asks the point the same way; consulting drops the remaining steps.
Which proceeding occurrences are reviewed after the fact. Sampling is a function of the occurrence’s id, so a replay samples alike.
pub type Sample {
Never
PerCent(Int)
}
Constructors
-
NeverNo released occurrence is sampled. Stored as
"sample": null. -
PerCent(Int)About this many in a hundred are sampled;
PerCent(0)samples none and stays distinct fromNeverin storage, so a policy read back is==to the one written.
Values
pub fn approvals(eligible: Eligible) -> Int
The fewest approvals that can satisfy an eligibility: for Either, the
fewest of its alternatives. Whether given approvals satisfy it depends
on who gave them; decisions/occurrence.is_met decides that.
pub fn check(
policy: Policy,
declared declared: List(#(String, fact.Kind)),
) -> Result(Nil, List(Fault))
Refuse a policy that reads a fact not in declared, compares a fact as
the wrong type, asks for fewer than one approval, or samples outside 0
to 100 per cent. Every fault is listed. waited_minutes is always
declared.
pub fn eligible_decoder() -> decode.Decoder(Eligible)
Decodes an eligibility written by eligible_to_json.
pub fn evaluate(
policy: Policy,
by: vocabulary.Recommender,
facts: List(#(String, vocabulary.Fact)),
) -> Outcome
What the policy says for this recommender and these facts.
pub fn is_sampled(sample: Sample, id: String) -> Bool
Whether an occurrence with this id is sampled. It is a function of the id, so the same occurrence is always sampled or never, and a replay samples alike. The id is hashed with SHA-256, so the share is uniform whatever the ids look like, sequential keys included.
pub fn outcome_decoder() -> decode.Decoder(Outcome)
Decodes an outcome written by outcome_to_json.
pub fn sets(eligible: Eligible) -> List(String)
The decision sets whose queues an eligibility puts an occurrence in.
pub fn step_decoder() -> decode.Decoder(Step)
Decodes a step written by step_to_json.
pub fn timeline(
policy: Policy,
by: vocabulary.Recommender,
facts: List(#(String, vocabulary.Fact)),
waited waited: Int,
) -> #(Outcome, List(Step))
What the policy says after waited minutes, and each later answer it
will give as the occurrence goes on waiting with nothing else changing.
The desk computes this when it applies the policy and keeps it on the
record, so while an occurrence waits it keeps the version it was given:
a wake-up applies the steps without reading the policy again. Steps
that have passed are applied in order up to the first that proceeds,
consults, or asks for what the standing approvals meet (see
decisions.wake), so a late wake-up skips no step that would have
accepted. A
consulted point’s answer is the one moment the policy is read again,
and then the version current at that moment applies. Every
PolicyApplied entry records the version that gave its answer.