Invariants

An invariant is a condition that must stay true during the whole run. The registrar checks each invariant while the run continues, not at the end.

invariants:
  - { layer: letter, no_edits_outside: ["src/**"] }
  - { layer: letter, untouched: "tests/test_sync.py" }
  - { layer: judgment, clause: "Changes stay minimal.", checkpoint: each_edit }

An invariant is different from a satisfaction clause. A satisfaction clause says when the work is complete. An invariant says what the agent must not do while the work continues.

Letter invariants

A letter invariant is a machine check. The registrar makes the check before each action. There are two forms.

no_edits_outside

The agent can change a file only when a pattern in the list matches the file.

invariants:
  - { layer: letter, no_edits_outside: ["src/**", "docs/*.md"] }

untouched

The agent cannot change the named file.

invariants:
  - { layer: letter, untouched: "tests/test_sync.py" }

This form stops the most common way that an agent cheats a test: the agent changes the test instead of the code.

An invariant takes exactly one of these two forms. To state both conditions, write two invariants.

Judgment invariants

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

invariants:
  - { layer: judgment, clause: "Changes stay minimal.", checkpoint: each_edit }

You must configure a judge before you use this layer.

checkpoint

The checkpoint field states when the judge makes the check. The default checkpoint is at_satisfaction.

Value	The judge makes the check
`each_edit`	After each change to a file.
`at_satisfaction`	When the satisfaction clauses pass.
`{ each_n_iterations: 5 }`	After each 5 iterations.

A frequent checkpoint finds a problem early, and costs more. Each check spends part of the cost bound.

Assent invariant syntax

The language accepts an assent invariant, but the current runtime does not run it.

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

writ plan marks this clause as unsupported. writ issue stops before it starts the run. Do not use an assent invariant until the selected adapter marks it as enforced.

Prefer the letter layer

Where you can, state a worry as a letter invariant. A machine check is exact, it costs nothing, and it applies to each action.

Take the worry “the agent must not cheat the test”. As a judgment clause, a model decides what “cheat” means. As a letter invariant, the condition is exact:

invariants:
  - { layer: letter, untouched: "{failing_test_file}" }

What happens at a breach

An invariant breach starts the on_invariant_breach remedy. The managed operational response is inform with 3 strikes. The registrar tells the model which clause failed. The first and second occurrences of the same blocked action can continue. Its third occurrence halts the run. A different action has a separate strike count.