decisions/entry

The record of an occurrence: append-only entries. Everything that happened to it, and every input that informed it, is an entry. Nothing is updated in place, so “what was known at time T” is the entries up to T, and decisions/occurrence.fold turns entries into where the occurrence stands.

A record may begin, before its recommendation, with expectations (Expected: a trigger was received and work is in flight) and failed attempts (AttemptFailed), in any order, and with the Expired entry that ended it before it began: a newer event superseded it, or its own deadline passed. After an expiry by deadline a Recommended entry may still follow, and the occurrence starts expired. Otherwise a record begins with Recommended.

to_stored and from_stored are the only translation between an entry and the text a store keeps, so an adapter never parses an entry.

Event may gain variants in a minor release. Code that matches it should keep a _ branch, or use the queries of decisions/occurrence.

Target-independent: builds for Erlang and JavaScript.

Types

One entry: its place in the record, when it was appended, and what happened.

pub type Entry(output) {
  Entry(seq: Int, at: timestamp.Timestamp, event: Event(output))
}

Constructors

What happened.

pub type Event(output) {
  AttemptFailed(
    point: String,
    trigger: vocabulary.Trigger,
    subject: vocabulary.Subject,
    failure: model.Failure,
    evidence: List(vocabulary.Ref),
  )
  Expected(
    point: String,
    trigger: vocabulary.Trigger,
    subject: vocabulary.Subject,
    valid_until: option.Option(timestamp.Timestamp),
  )
  Recommended(
    point: String,
    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(from: String, facts: List(#(String, vocabulary.Fact)))
  PolicyApplied(
    version: Int,
    outcome: policy.Outcome,
    sampled: Bool,
    later: List(policy.Step),
  )
  Opened(by: String, drifted: List(vocabulary.Ref))
  Expanded(by: String, read: String, result: vocabulary.Ref)
  Noted(by: String, note: String)
  Decided(
    by: String,
    verdict: vocabulary.Verdict(output),
    seen: Int,
    holds: List(String),
  )
  VerdictRefused(
    by: String,
    verdict: vocabulary.Verdict(output),
    seen: Int,
    reason: String,
  )
  Reviewed(by: String, verdict: vocabulary.Verdict(output))
  Held(until: timestamp.Timestamp)
  Withdrawn(by: String)
  Released(
    key: String,
    tool: String,
    relied: List(vocabulary.Ref),
  )
  Effected(effect: vocabulary.Effect)
  Refused(reason: String)
  Expired(cause: vocabulary.ExpiryCause)
  Assessed(assessment: vocabulary.Assessment(output))
}

Constructors

  • AttemptFailed(
      point: String,
      trigger: vocabulary.Trigger,
      subject: vocabulary.Subject,
      failure: model.Failure,
      evidence: List(vocabulary.Ref),
    )

    A recommender failed under this key before any recommendation existed. Appended by decisions.record_failure, in a transaction of its own.

    Arguments

    evidence

    Evidence the application stored about the attempt, such as the exchange that did not decode.

  • Expected(
      point: String,
      trigger: vocabulary.Trigger,
      subject: vocabulary.Subject,
      valid_until: option.Option(timestamp.Timestamp),
    )

    A recommendation is expected under this key, about this subject: the trigger was received and the model is at work. Appended by decisions.expect, in the transaction that received the trigger, so that happened can supersede the work in flight before it is recommended. valid_until is the occurrence’s own deadline, when the application gave one (decisions.expect_until); a later expectation may only bring it earlier.

  • Recommended(
      point: String,
      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),
    )

    The recommendation the occurrence began with.

    Arguments

    point

    The decision point this is an occurrence of.

    requester

    Who asked, when a person did.

  • Informed(from: String, facts: List(#(String, vocabulary.Fact)))

    A consulted decision point’s final output, as facts.

  • PolicyApplied(
      version: Int,
      outcome: policy.Outcome,
      sampled: Bool,
      later: List(policy.Step),
    )

    What the policy said, and what it will say as the occurrence waits. Appended again each time waiting changes the answer.

  • Opened(by: String, drifted: List(vocabulary.Ref))

    The card was shown to a validator. drifted holds the newer revision of each input, in the context or among the model’s reads, that changed since the model read it.

  • Expanded(by: String, read: String, result: vocabulary.Ref)

    The validator opened more than the card showed; result is the captured evidence of what that read returned.

  • Noted(by: String, note: String)

    What the validator brought from outside the card.

  • Decided(
      by: String,
      verdict: vocabulary.Verdict(output),
      seen: Int,
      holds: List(String),
    )

    A verdict the occurrence waited for. seen is the entry that showed the card the verdict was given on; holds the decision sets the validator held then, which decide which alternative of an Either their approval counts toward.

  • VerdictRefused(
      by: String,
      verdict: vocabulary.Verdict(output),
      seen: Int,
      reason: String,
    )

    A verdict whose release the guard or the gated tool refused, so the verdict’s transaction rolled back. Appended afterwards by decisions.record_refusal, in a transaction of its own. It changes no status.

  • Reviewed(by: String, verdict: vocabulary.Verdict(output))

    A verdict after the fact, on a sampled and released occurrence.

  • Held(until: timestamp.Timestamp)

    The accepted output waits until until before release, and its decider may withdraw it meanwhile.

  • Withdrawn(by: String)
  • Released(key: String, tool: String, relied: List(vocabulary.Ref))

    The final output reached the gated tool named tool. relied is the evidence the tool’s guard read to allow it.

  • Effected(effect: vocabulary.Effect)

    What became of the release outside the database.

  • Refused(reason: String)

    The guard or the gated tool refused a release that nobody was waiting on, so the occurrence ended.

  • Expired(cause: vocabulary.ExpiryCause)
  • Assessed(assessment: vocabulary.Assessment(output))

Values

pub fn from_stored(
  stored: store.Stored,
  output: wire.Codec(o),
) -> Result(Entry(o), String)

The entry back from the store. An error means the text does not decode with this point’s codec: the record belongs to another point, or the codec changed in a way the stored text does not survive.

pub fn kind(event: Event(output)) -> String

The stable name of an entry’s kind, as a store keeps it.

pub const kinds: List(String)

Every kind name, in the order of Event.

pub fn point_of(stored: store.Stored) -> Result(String, Nil)

The point a stored record belongs to, read from its first entry without decoding the output. Error(Nil) when the entry names none.

pub fn to_stored(
  entry: Entry(o),
  output: wire.Codec(o),
) -> Result(store.Stored, String)

The entry as a store keeps it. An error means the point’s codec cannot encode an output the entry carries.

✨ Search Document