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:
| Function | Why it exists |
|---|---|
load | Reads an occurrence and locks it, even when it does not exist yet, so two deliveries of one trigger cannot both admit it |
append | Adds entries and replaces the head in one write; refuses a sequence number it holds and a second release |
waiting | Finds the undecided occurrences of a point about a subject, for superseding, in a stable order |
schedule | Replaces an occurrence’s pending wake-ups; an empty list cancels them |
settled | Admits one durable notice that an occurrence settled, so what follows can start |
atomically | A savepoint around the guard and the gated tool, so a tool that writes and then refuses leaves nothing behind |
now | The store’s clock, read after the lock |
new_id | An 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.
Pendingwhile the record has not begun (expected, or holding only failed attempts). Store it withstatus_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
financeunderEither([SomeoneElseHolding("finance"), AnyoneHolding("head")])) is not listed, so a queue may still show them the card, andopenrefuses them withNotEligible. Empty unless the status isAwaiting. - 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,
Nonewhen 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.happenedloadsdecisions.subject_lock(point, subject)(prefixdecisions.subject-lock:) to serialise on a subject. Loading must not create a row, head or anything elsewaitingor 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
seq1 and each next one the next number. The store refuses withConflicta sequence number it already holds, a gap, and a secondreleasedentry 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,AwaitingorHeld(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
bodyinside a savepoint. When it returnsError, everything it wrote is undone and the transaction stays usable; when it returnsOk, its writes stay. The outerResultis 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(), notnow(). The desk reads it afterloadhas 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), sodecisions/conformancedoes 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
releasedentry, 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_oncefinds 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
-
Stored( seq: Int, at: timestamp.Timestamp, kind: String, event: String, )
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
-
Wake(point: String, occurrence: String, at: timestamp.Timestamp)
Values
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".