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:

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

  • OwnAct

    The recommender is a person acting on their own authority.

  • Below(fact: String, limit: Float)

    The number fact is below limit. Build it with below.

  • AtLeast(fact: String, limit: Float)

    The number fact is at least limit. Build it with at_least.

  • Is(fact: String, value: vocabulary.Fact)

    The fact equals value. Build it with is.

  • 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)

    count different validators, each admitted by of, approving the output that stands. A correction replaces that output, and approvals of the earlier output stop counting. of may hold Either, but no Several at any depth: check refuses that with NestedSeveral, 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.

  • WrongKind(fact: String, declared: fact.Kind, used: fact.Kind)

    The policy compares a fact as one type and the point declares another.

  • TooFewApprovals(count: Int)

    Several asks for fewer than one approval.

  • SampleOutOfRange(per_cent: Int)

    PerCent is outside 0 to 100.

  • NestedSeveral

    A Several inside another Several, directly or through Either. Approvals are counted once, by the outer count, so an inner count would be silently ignored.

  • EmptyEither

    An Either with no alternative: the occurrence would wait in no queue, for nobody.

  • NonPositiveHold(milliseconds: Int)

    A Proceed holds 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. sample picks 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’s withdrawn_by set may withdraw it meanwhile. It takes the place of the point’s with_hold for 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 eligible admits.

  • Consult(point: String)

    Ask the decision point named point first. Its final output returns as facts through decisions.inform, and the policy current at that moment is read again with them. A policy that would consult the same point twice falls to otherwise. A later answer (a Step) that consults asks the point the same way; consulting drops the remaining steps.

One version of a point’s policy.

pub type Policy {
  Policy(version: Int, rules: List(Rule), otherwise: Outcome)
}

Constructors

  • Policy(version: Int, rules: List(Rule), otherwise: Outcome)

“When this condition holds, this is the outcome.”

pub type Rule {
  When(condition: Condition, then: Outcome)
}

Constructors

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

  • Never

    No 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 from Never in storage, so a policy read back is == to the one written.

A later answer of the same policy: after waiting after whole minutes, it says outcome.

pub type Step {
  Step(after: Int, outcome: Outcome)
}

Constructors

  • Step(after: Int, outcome: Outcome)

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 at_least(key: fact.Key(Float), limit: Float) -> Condition

The number is at least limit.

pub fn below(key: fact.Key(Float), limit: Float) -> Condition

The number is below limit.

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 decoder() -> decode.Decoder(Policy)

Decodes a policy written by to_json.

pub fn describe(fault: Fault) -> String

A fault as one line of text, for an operator.

pub fn eligible_decoder() -> decode.Decoder(Eligible)

Decodes an eligibility written by eligible_to_json.

pub fn eligible_to_json(eligible: Eligible) -> json.Json

An eligibility as 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(key: fact.Key(a), value: a) -> Condition

The fact equals value.

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 known(key: fact.Key(a)) -> Condition

The fact is present.

pub fn outcome_decoder() -> decode.Decoder(Outcome)

Decodes an outcome written by outcome_to_json.

pub fn outcome_to_json(outcome: Outcome) -> json.Json

An outcome as JSON.

pub fn reads(policy: Policy) -> List(String)

Every fact the policy reads, each once.

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 step_to_json(step: Step) -> json.Json

A step as 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.

pub fn to_json(policy: Policy) -> json.Json

The policy as JSON, for storing and exporting.

pub fn waited(minutes: Int) -> Condition

“Unanswered for at least this many minutes”: a condition over decisions/fact.waited_minutes.

✨ Search Document