decisions/view

The card as a document: what a person, or another system, is shown. Everything on it is resolved from the record: the context the model started from, what the model read beyond it, and what validators opened since, each with the content as it was read and, when it has changed since, the newer revision.

context runs a point’s Reader against the record alone, so the card gets the same typed value the model got, and a reader that asks for more than the model read is told NotRecorded.

A view crosses a process boundary as JSON (to_json, format "decision-card.v1"), with the allowed verdicts and, when the point’s codec carries one, the output’s JSON Schema. A verdict returns as JSON that only the point’s own codec decodes (verdict).

import decisions/view

let document = view.of(card, content: recorded_content)
let assert Ok(brief) =
  view.context(decisions.shown(card), with: read_brief, content: recorded_content)

Target-independent: builds for Erlang and JavaScript.

Types

One way the occurrence can be accepted: need approvals from holders of any of sets, of which it has have. Under Either there is one per alternative; under Several(count, of) one, needing count.

pub type Alternative {
  Alternative(sets: List(String), have: Int, need: Int)
}

Constructors

  • Alternative(sets: List(String), have: Int, need: Int)

Who has approved the output that stands, and what each way of accepting it still needs. The occurrence is accepted when any one alternative has as many approvals as it needs. Both lists are empty once it no longer waits.

pub type Approvals {
  Approvals(by: List(String), alternatives: List(Alternative))
}

Constructors

  • Approvals(by: List(String), alternatives: List(Alternative))

One input, with its content as it was read. now is the newer revision when the input changed after the model read it.

pub type Item {
  Item(
    ref: vocabulary.Ref,
    content: Result(String, model.Failure),
    now: option.Option(vocabulary.Ref),
  )
}

Constructors

What a card shows.

pub type View(output) {
  View(
    occurrence: String,
    seen: Int,
    point: String,
    subject: vocabulary.Subject,
    status: String,
    waiting_for: List(String),
    approvals: Approvals,
    pushed: List(Item),
    pulled: List(Item),
    opened: List(#(String, Item)),
    notes: List(#(String, String)),
    recommendation: vocabulary.Recommendation(output),
    standing: output,
    allowed: vocabulary.Verdicts,
  )
}

Constructors

  • View(
      occurrence: String,
      seen: Int,
      point: String,
      subject: vocabulary.Subject,
      status: String,
      waiting_for: List(String),
      approvals: Approvals,
      pushed: List(Item),
      pulled: List(Item),
      opened: List(#(String, Item)),
      notes: List(#(String, String)),
      recommendation: vocabulary.Recommendation(output),
      standing: output,
      allowed: vocabulary.Verdicts,
    )

    Arguments

    seen

    The entry that showed the card. With occurrence it is the ticket a verdict comes back with.

    waiting_for

    The decision sets it waits for.

    pushed

    The context the model started from.

    pulled

    What the model received beyond it.

    opened

    What validators opened beyond the card, as #(read, item).

    notes

    What validators entered, as #(by, note).

    recommendation

    What the recommender proposed.

    standing

    The output a verdict on this card would be about: the recommendation’s, or the latest correction’s. An approval approves this output.

Values

pub fn codec(output: wire.Codec(o)) -> codec.Codec(View(o))

The "decision-card.v1" document as a json_blueprint codec, given the point’s output codec: encode a view to serve a card with a schema (for example as a typed MCP tool result), decode one on the client side.

The document holds the occurrence and its ticket fields (occurrence, seen), point, subject, status, waiting_for, approvals (by, and alternatives, each with sets, have and need), the inputs as read (context, model_read, opened, each item with ref, content, unavailable and changed_to), notes, the recommendation, the standing_output, the allowed verdicts, and the output’s output_schema (null for a plain codec). The recommender, its explanation and its signals keep the JSON form of decisions/wire.

Decoding is faithful except for an input that could not be resolved: it comes back as ReadFailed with the reason’s text, whatever failure it was.

pub fn context(
  shown: occurrence.Occurrence(o),
  with reader: fn(vocabulary.Manifest, model.Sources) -> Result(
    context,
    model.Failure,
  ),
  content content: fn(vocabulary.Ref) -> Result(
    String,
    model.Failure,
  ),
) -> Result(context, model.Failure)

The context as the model received it, as the point’s own type. The reader runs against the record alone: the context references and the reads on the recommendation, resolved by content. It returns what the model’s reader returned, or NotRecorded for a read the model never received.

pub fn of(
  card: decisions.Card(o),
  content content: fn(vocabulary.Ref) -> Result(
    String,
    model.Failure,
  ),
) -> View(o)

What a card shows. content resolves a reference to the evidence it names: the content as it was read, whatever the world says now. The point’s name and allowed verdicts come from the card, so a view can never be built against the wrong point.

pub fn ticket_decoder() -> decode.Decoder(decisions.Ticket)

The ticket fields of a card document, read back by a client.

pub fn to_json(
  view: View(o),
  output: wire.Codec(o),
) -> Result(json.Json, String)

The view as a "decision-card.v1" document. A client needs none of the point’s code to show it, approve or reject it; with output_schema it can also build a correction form. It is exactly what codec encodes, so a client can decode it typed and check it against codec’s schema. An error means the codec cannot encode an output the card holds.

pub fn verdict(
  text: String,
  output: wire.Codec(o),
) -> Result(vocabulary.Verdict(o), json.DecodeError)

A verdict that arrived as JSON text, decoded with the point’s codec. A correction whose output is not this point’s output does not decode.

pub fn verdict_to_json(
  verdict: vocabulary.Verdict(o),
  output: wire.Codec(o),
) -> Result(json.Json, String)

A verdict as JSON, as a client sends it back.

✨ Search Document