The three check layers

Each clause in a writ declares its layer. The layer names who makes the decision. Because each clause declares its layer, you always know how much to trust the clause.

Layer	Who decides	Trust
letter	A machine	Complete.
judgment	A judge model	As much as you trust a model.
assent	A person	As much as you trust the person.

letter

A letter clause is a machine check: a path comparison, an exit code, or a count. The registrar makes the check on each action.

- { layer: letter, untouched: "tests/test_sync.py" }
- { layer: letter, run: "pytest -x -q", exit: 0 }

A letter check costs no money and takes little time, so the registrar can make the check on each action. The result is a fact.

judgment

A judgment clause is prose. A judge model reads the clause and the actions, and then makes a decision.

- { layer: judgment, clause: "The diff addresses the cause, not the symptom." }

The judge is never the holder model. An agent does not grade its own work.

A judgment check costs money, and each check spends part of the cost bound. The budget_share of the judge gives the part that the judge can spend. You must configure a judge before you use this layer.

A judgment result is an opinion. A judge model can be wrong in the same way that the holder model can be wrong.

assent

An assent clause asks a person. The run stops until the person answers.

grants:
  - open_pr: { requires: assent }

invariants:
  - { layer: assent, clause: "A person approves each change to the schema." }

You must configure an assent transport, which is cli, web, or both. A run with an assent clause and no transport stops with an error.

Assent is the most expensive layer, because a person must wait and then read. Use assent for the actions that a person cannot undo.

Move a clause down the layers

The most useful thing that you can do to a writ is to find the letter form of a judgment worry.

Take the worry “the agent must not cheat the test”:

# Judgment: a model decides what "cheat" means.
- { layer: judgment, clause: "The agent does not cheat the test." }

# Letter: the condition is exact, free, and checked on each action.
- { layer: letter, untouched: "tests/test_sync.py" }

The letter form is better in each way. It costs nothing, the registrar applies it to each action, and two readers cannot disagree about the result.

Some worries have no letter form. “The diff addresses the cause, not the symptom” is such a worry. Keep those at the judgment layer, and know that the result is an opinion.

What each layer costs

Layer	Money	Time	Result
letter	None	Milliseconds	A fact
judgment	Tokens	Seconds	An opinion
assent	None	Minutes or hours	A decision