# How Forma works

> What you send, what you get back, and what a verdict promises.

Forma turns a request in plain language into an artifact — a chart, a figure —
and tells you whether it holds up. Every answer is checked against a versioned set of rules before it is returned to you.

## The contract

1. You send an **intent** to an **oracle** — a named service for one kind of
   artifact, such as `chart`, `vector-graphics` or `coverage-policy`: what you want, in plain
   language.
2. You get back a **verdict**. `valid` comes with the artifact. `invalid` comes
   with the reason it was refused. `error` means the failure was ours.
3. A `valid` answer carries **`verified_by`**, which identifies the exact version of the rules it was
   checked against.

Forma's **check** accepts an answer only if it follows the oracle's rules. The
rules are versioned and not published; `verified_by` identifies the version that
accepted an answer: `chart@6baf09f0` is the `chart` rules at that version.

Most calls come back in about two seconds; allow up to 120 seconds for the
slowest. A call is counted in [credits](https://docs.formalogic.io/limits) rather than requests.

## What this buys you

**A refusal is a real answer.** Most of what an API of this kind can do wrong is
return something well-formed and wrong. Here, an answer that does not pass the
rules is not handed to you as if it did — you are told. That is the product,
which is why a refusal is [billable](https://docs.formalogic.io/verdicts).

**The rules are versioned on their own.** The rules that accept an answer are
separate from whatever produced it, and they carry their own version — see
[Citations](https://docs.formalogic.io/citations). How answers are produced will change; what your
citation points at does not.

**You write intent, never rules.** There is no endpoint that takes rules.
You describe the outcome you want in plain language; deciding what satisfies it
is our side of the line, and it stays our side so we can keep making it better
without breaking anything you wrote.

## What it does not do

It does not check meaning. A `valid` artifact is well-formed and follows the
rules; it is not necessarily the chart you meant — a valid chart of the wrong
column is still valid. Look at what you got.

It does not guarantee an answer. Some intents cannot be satisfied and the honest
result is `invalid`.

It does not guarantee the same answer twice. See
[Determinism](https://docs.formalogic.io/citations#determinism).

It does not stream. A call returns when the verdict does.