decisions/store

The storage port: everything the desk needs from a store, always inside the caller’s transaction. An adapter implements Port once for its store; decisions/memory is the one in this package, and decisions/conformance checks any adapter against the contract below.

The port has eight functions. Each exists because a guarantee rests on the store and the core cannot provide it alone:

FunctionWhy it exists
loadReads an occurrence and locks it, even when it does not exist yet, so two deliveries of one trigger cannot both admit it
appendAdds entries and replaces the head in one write; refuses a sequence number it holds and a second release
waitingFinds the undecided occurrences of a point about a subject, for superseding, in a stable order
scheduleReplaces an occurrence’s pending wake-ups; an empty list cancels them
settledAdmits one durable notice that an occurrence settled, so what follows can start
atomicallyA savepoint around the guard and the gated tool, so a tool that writes and then refuses leaves nothing behind
nowThe store’s clock, read after the lock
new_idAn id for an occurrence admitted without a key

The port offers no way to take, acknowledge or postpone a wake-up or a notice. Delivery belongs to the runtime that drives the desk: the supervised runtime of decisions_otp (its sweeper and dispatcher), and the Grind workers of decisions_postgres. The port only records what is pending.

Inspection is not part of the port. It is what an adapter supplies so that decisions/conformance and decisions/testing can look at what it stored.

Target-independent: builds for Erlang and JavaScript.

Types

What the store keeps beside an occurrence’s entries, so that queues and superseding can find it without decoding an entry. The desk writes it with every append.

pub type Head {
  Head(
    point: String,
    subject: vocabulary.Subject,
    status: Status,
    awaiting: List(String),
    due: option.Option(timestamp.Timestamp),
    arrived: timestamp.Timestamp,
    approved: List(String),
    may_not_decide: List(String),
    review_pending: Bool,
  )
}

Constructors

  • Head(
      point: String,
      subject: vocabulary.Subject,
      status: Status,
      awaiting: List(String),
      due: option.Option(timestamp.Timestamp),
      arrived: timestamp.Timestamp,
      approved: List(String),
      may_not_decide: List(String),
      review_pending: Bool,
    )

    Arguments

    point

    The decision point’s name.

    status

    Where the occurrence stands. Pending while the record has not begun (expected, or holding only failed attempts). Store it with status_name.

    awaiting

    The decision sets whose queues the occurrence waits in. Empty unless the status is Awaiting.

    due

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

    arrived

    When the recommendation arrived, or the first attempt when there is no recommendation yet. A queue orders by due, then by this.

    approved

    Who has approved the output that stands. A queue leaves a card out for a validator who already approved it.

    may_not_decide

    Who may not decide this occurrence whatever sets they hold: whoever already approved the output that stands, and the person who asked or recommended it as their own act when every alternative of the eligibility bars them. A queue leaves the card out for them. Someone barred only under the one alternative they qualify for (the requester holding only finance under Either([SomeoneElseHolding("finance"), AnyoneHolding("head")])) is not listed, so a queue may still show them the card, and open refuses them with NotEligible. Empty unless the status is Awaiting.

    review_pending

    Sampled, released, and not yet reviewed.

What an adapter lets tests see of its store. decisions/conformance and decisions/testing read through it; the desk never does.

pub type Inspection(tx) {
  Inspection(
    occurrences: fn(tx, String) -> Result(
      List(String),
      StoreError,
    ),
    head: fn(tx, String) -> Result(
      option.Option(Head),
      StoreError,
    ),
    wakes: fn(tx) -> Result(List(Wake), StoreError),
    notices: fn(tx) -> Result(List(Notice), StoreError),
  )
}

Constructors

  • Inspection(
      occurrences: fn(tx, String) -> Result(List(String), StoreError),
      head: fn(tx, String) -> Result(option.Option(Head), StoreError),
      wakes: fn(tx) -> Result(List(Wake), StoreError),
      notices: fn(tx) -> Result(List(Notice), StoreError),
    )

    Arguments

    occurrences

    The ids of every record of a point, in any order.

    head

    The head of a record, None when there is none.

    wakes

    Every pending wake-up.

    notices

    Every settlement notice admitted, in the order admitted.

A durable notice that an occurrence of point settled.

pub type Notice {
  Notice(point: String, occurrence: String)
}

Constructors

  • Notice(point: String, occurrence: String)

Everything the desk needs from a store. Every function runs in the caller’s transaction tx.

pub type Port(tx) {
  Port(
    load: fn(tx, String) -> Result(List(Stored), StoreError),
    append: fn(tx, String, Head, List(Stored)) -> Result(
      Nil,
      StoreError,
    ),
    waiting: fn(tx, String, vocabulary.Subject) -> Result(
      List(String),
      StoreError,
    ),
    schedule: fn(tx, String, String, List(timestamp.Timestamp)) -> Result(
      Nil,
      StoreError,
    ),
    settled: fn(tx, String, String) -> Result(Nil, StoreError),
    atomically: fn(
      tx,
      fn(tx) -> Result(List(vocabulary.Ref), String),
    ) -> Result(Result(List(vocabulary.Ref), String), StoreError),
    now: fn(tx) -> timestamp.Timestamp,
    new_id: fn(tx) -> String,
  )
}

Constructors

  • Port(
      load: fn(tx, String) -> Result(List(Stored), StoreError),
      append: fn(tx, String, Head, List(Stored)) -> Result(
        Nil,
        StoreError,
      ),
      waiting: fn(tx, String, vocabulary.Subject) -> Result(
        List(String),
        StoreError,
      ),
      schedule: fn(tx, String, String, List(timestamp.Timestamp)) -> Result(
        Nil,
        StoreError,
      ),
      settled: fn(tx, String, String) -> Result(Nil, StoreError),
      atomically: fn(
        tx,
        fn(tx) -> Result(List(vocabulary.Ref), String),
      ) -> Result(Result(List(vocabulary.Ref), String), StoreError),
      now: fn(tx) -> timestamp.Timestamp,
      new_id: fn(tx) -> String,
    )

    Arguments

    load

    The occurrence’s entries in sequence order, and a lock on its id for the rest of the transaction. The lock is taken when no entry exists too: a second transaction that loads the same id waits until the first ends, then sees what it stored. Empty when there is none.

    The core also loads ids that never hold entries, purely as locks: decisions.happened loads decisions.subject_lock(point, subject) (prefix decisions.subject-lock:) to serialise on a subject. Loading must not create a row, head or anything else waiting or an inspection could see; the lock alone must last until the transaction ends.

    append

    Append entries after the last one and replace the head. The first entry has seq 1 and each next one the next number. The store refuses with Conflict a sequence number it already holds, a gap, and a second released entry for one occurrence. Entries are never changed or removed.

    waiting

    The ids of a point’s occurrences about a subject whose head status is Pending, Recommended, Awaiting or Held (is_waiting): records that have not begun, and occurrences nothing of which has been released. In ascending id order, so that every transaction locks several occurrences in one order. An adapter may leave out an occurrence it has set aside as poison (a record that no longer decodes), so that one bad record does not stop a supersession; the PostgreSQL adapter does.

    schedule

    Replace every pending wake-up of a point’s occurrence with one at each of these times. An empty list cancels them all. A wake-up the store already delivered is not affected.

    settled

    Admit a durable notice that a point’s occurrence settled. The desk calls it once per occurrence.

    atomically

    Run body inside a savepoint. When it returns Error, everything it wrote is undone and the transaction stays usable; when it returns Ok, its writes stay. The outer Result is the savepoint’s own failure. The body’s error text belongs to the desk: pass it back unchanged and do not interpret it. When the body raises, undo its writes and let the raise continue.

    now

    The wall clock at the moment of the call, at any resolution: the desk keeps whole milliseconds (rounded down), and every time it stores, schedules or puts on a head is a whole millisecond. It is not the start of the transaction: in PostgreSQL clock_timestamp(), not now(). The desk reads it after load has taken the lock, so a verb that waited for the lock is stamped with when it ran, and it never stores an entry earlier than the one before it. One process cannot check this clause honestly (a frozen clock looks the same), so decisions/conformance does not; the multi-process suites do.

    new_id

    A new, unique occurrence id.

Where an occurrence stands, as its head keeps it: the nine statuses of decisions/occurrence.Status without their payloads, and Pending for a record that has not begun: a recommendation is expected (decisions.expect) or only failed attempts are recorded. A record superseded before it began is Expired.

pub type Status {
  Pending
  Recommended
  Awaiting
  Accepted
  Held
  Released
  Rejected
  Expired
  Withdrawn
  Refused
}

Constructors

  • Pending
  • Recommended
  • Awaiting
  • Accepted
  • Held
  • Released
  • Rejected
  • Expired
  • Withdrawn
  • Refused

Why the store refused or failed.

pub type StoreError {
  Conflict(detail: String)
  Contended(detail: String)
  Unavailable(detail: String)
}

Constructors

  • Conflict(detail: String)

    The write breaks the contract: a sequence number the store already holds, a second released entry, or entries that do not follow the last one. Roll the transaction back. Running it again from the start reloads the record, so it is safe, but a conflict that repeats points at a second writer that does not take the lock.

  • Contended(detail: String)

    Contention: a deadlock, or a lock wait that timed out. The store wrote nothing. Roll the transaction back and run it again from the start; that is safe.

  • Unavailable(detail: String)

    The store could not do it and the outcome is unknown: a lost connection, a timeout after the commit was sent. Roll back; before running it again, read the record to see whether it committed (every verb is safe to repeat on what it finds: recommend_once finds its occurrence, a verdict sent again on the same card stands).

An entry as the store keeps it. kind is the entry’s kind (see decisions/entry.kind), kept as a column so the store can hold “at most one released per occurrence” behind a unique key. event is the entry’s JSON text, which only the point’s codec decodes.

pub type Stored {
  Stored(
    seq: Int,
    at: timestamp.Timestamp,
    kind: String,
    event: String,
  )
}

Constructors

A wake-up the store holds: deliver decisions.wake (or the point’s decisions.waker) for occurrence at at.

pub type Wake {
  Wake(
    point: String,
    occurrence: String,
    at: timestamp.Timestamp,
  )
}

Constructors

Values

pub fn describe(error: StoreError) -> String

The error as one line of text.

pub fn is_waiting(status: Status) -> Bool

Whether waiting returns a record with this status: it has not begun, or it is recommended, awaiting or held, so nothing has been released and an event can still supersede it.

pub fn parse_status(name: String) -> Result(Status, Nil)

The status a stored name stands for.

pub fn status_name(status: Status) -> String

The stable name a store keeps for a status, such as "awaiting".

pub const statuses: List(Status)

Every status, in the order of Status.

✨ Search Document