Orivael Academy

The AXIOM Language

Write agents you can govern.

.axiom is a declarative language for specifying AI agents — what they receive, what they may emit, and above all what they can never change about themselves. No Python, no procedural code: an agent is a contract you can read, diff, sign, and enforce.

Everything here is taken from the canonical spec, axiom_files/core/axiom_language.axiom — which is itself written in AXIOM, using only the constructs it defines.

01 Your first agent

Every .axiom file declares exactly one agent, and AGENT must be the first line. Five constructs give you a complete, valid agent:

AGENT InvoiceReader
VERSION 1.0
TRUST_LEVEL 2
PURPOSE Extract totals and due dates from supplier invoices
GOAL Read an invoice and return its structured fields
     Never guess a number that is not present on the page
AGENT
Names the agent. One per file, required, first line.
VERSION
Semantic version — major.minor or major.minor.patch.
TRUST_LEVEL
An integer trust tier. Delegation flows downward only, never upward — a level-2 agent cannot hand work to a level-4 one.
PURPOSE
A one-line mission statement.
GOAL
The multi-line objective. Indented lines below the first are continuation lines that extend the value.

02 Contracts: what goes in, what comes out

RECEIVES and EMITS declare the agent's interface as name: type pairs. This is the boundary the runtime checks.

RECEIVES document: string, page_count: int, locale: string
EMITS total: float, due_date: string, confidence: float

Declaring confidence as an output is idiomatic AXIOM: an agent states how sure it is, and a CONSTRAINT can cap that number so it may never claim certainty.

03 Immutability — the point of the language

This is what separates .axiom from a prompt. MUTATES lists the fields an agent may change at runtime. CANNOT_MUTATE lists fields that are permanently locked — the parser enforces it, so the agent cannot rewrite its own purpose, escalate its trust level, or edit away its own limits.

MUTATES cache, retry_count

CANNOT_MUTATE agent, purpose, version, trust_level
CANNOT_MUTATE cannot_mutate_fields_are_permanent

04 Invariants: what a CONSTRAINT is

A CONSTRAINT is a condition that must be true of every output. It is not a step and it is not a preference. If it fails, the output is invalid. The other behavioural constructs build on it:

CONSTRAINT
What must always hold. It can't be broken.
RULES
What to prefer when several outputs are allowed. Rules can be traded against each other.
CHECK
How you tell whether a constraint holds.
FAILURE
What happens when a check fails.

The one-line form states the condition, one invariant per line and never bundled, so each can be cited and violated independently:

CONSTRAINT Write the test before the implementation — always
CONSTRAINT Confidence ceiling 0.85 — never claim certainty
CONSTRAINT Human review required before any production promotion

Don't: CONSTRAINT Test first and cap confidence and require review — three invariants in one line cannot be individually enforced or reported.

Where specs blur these

The named form

Give each constraint a name, the condition it must meet, a severity, a check and a failure response. Then order them with PRECEDENCE:

CONSTRAINT NoFabrication
  HOLDS every claim traces to source or known fact
  SEVERITY hard
  CHECK claim lacks support
  FAILURE state uncertainty; withhold claim

CONSTRAINT IntentPreserved
  HOLDS output answers the request as asked
  SEVERITY hard
  CHECK output scope differs from request scope
  FAILURE specify the gap; ask for missing information

CONSTRAINT Specificity
  HOLDS answer includes concrete values when available
  SEVERITY soft
  CHECK answer generalizes where specifics exist
  FAILURE add specifics or state they are unavailable

PRECEDENCE
  NoFabrication > IntentPreserved > Specificity > Concision
HOLDS
The condition itself. A condition, not an action and not a ranking.
SEVERITY
hard can never be traded away. soft gives way to anything higher in PRECEDENCE.
CHECK
What, seen in the output, means the constraint failed.
FAILURE
The response when that check fails, bound to this constraint.
PRECEDENCE
Who wins a conflict, highest first. Nothing soft may rank above a hard constraint, and two hard constraints never trade: an output that can't meet both is invalid.

05 Exercise: untangle a spec

Every line below comes from one real agent spec, where they all sat under CONSTRAINT, CHECK and FAILURE with nothing to tell them apart. Work through three steps. Nothing you type leaves this page.

Step 1 · Sort each line

Pick the construct each line belongs in. A CONSTRAINT is a condition true of every output, RULES rank, PROCESS acts, CHECK detects a failure, FAILURE responds to one.

  1. Every claim traces to the source material or to established fact

  2. Consider whether the answer may confuse, mislead, or distress the user

  3. Prioritize relevant, accurate, complete, and respectful content

  4. A claim has no supporting source or established fact

  5. State the uncertainty and withhold the claim

  6. Response length across demographic variants of the same task differs by no more than 15%

  7. Prefer clear answers over vague ones

  8. Identify missing information

  9. The scope of the output differs from the scope of the request

Answer key

1 CONSTRAINT · 2 PROCESS · 3 RULES · 4 CHECK · 5 FAILURE · 6 CONSTRAINT · 7 RULES · 8 PROCESS · 9 CHECK

Step 2 · Make "Provide specific answers" testable

That line has no pass condition, so no CHECK can decide it. Rewrite it as a named constraint. The checker applies the validator's own rules as you type.

Show a model answer
CONSTRAINT Specificity
  HOLDS the answer gives concrete values wherever the task supplies them
  SEVERITY soft
  CHECK the answer generalizes where specific values exist
  FAILURE add the specific values or state that they are unavailable

Why soft: an answer can stay valid without every specific, so this one may give way to a higher constraint. Fabricating a value to be specific would break NoFabrication, which is hard.

Step 3 · Put them in order

Two hard constraints and two soft ones. Arrange them in PRECEDENCE order, highest first.

  1. Concision soft
  2. IntentPreserved hard
  3. Specificity soft
  4. NoFabrication hard

Show the reasoning

Both hard constraints go above both soft ones: nothing soft may outrank a hard constraint (the validator reports AX-C022). Between the two hard ones the order is yours to state, and it never trades either away. Between the soft ones, Specificity > Concision means a concrete value stays in even when it lengthens the answer:

PRECEDENCE
  NoFabrication > IntentPreserved > Specificity > Concision

06 Flow sections

A bare UPPERCASE word on its own line opens a section; the bullets below belong to it. Five sections describe how the agent runs, in order:

RULESoperational commands the agent follows
PROCESSordered steps, executed sequentially
CHECKquality gates, evaluated after PROCESS
FAILUREwhat to do when a CHECK gate fails
OUTPUTthe shape of the response
PROCESS
- Read the document and locate the totals block
- Extract the currency and amount as separate fields
- Compute confidence from how many fields were found verbatim

CHECK
- Every emitted number appears literally in the source document
- Confidence is at or below the declared ceiling

FAILURE
- Emit the fields that did pass and mark the rest unknown
- Never substitute an inferred number for a missing one

07 Scoring, routing, and hard limits

SUCCESS takes field: weight pairs, and the weights must sum to 1.0 — the parser rejects anything else, so "success" is always a fully-allocated definition rather than a vibe.

SUCCESS
- accuracy: 0.5
- calibration: 0.3
- latency: 0.2

SECURITY
- Never write outside the workspace directory
- Never transmit document contents to a third-party endpoint

DELEGATES
- InvoiceReader to Sandbox on untrusted_attachment

HUMAN_REVIEW
- Any invoice above 50000 in any currency
SECURITY
Hard rules that override RULES. When they conflict, security wins.
DELEGATES
Routing: Agent to Target on trigger — and remember trust flows downward only.
TOOLS
Declares an available tool with its permissions and sandbox flag.
HUMAN_REVIEW
Conditions that require a person to approve before proceeding.
CONCEPT / WHEN
A named sub-spec (with APPLIES WHEN, NOT WHEN, PRIORITY, REQUIRES, EFFECT), plus a decision table that activates it.
HISTORY
Timestamped change-log entries.

08 Every construct

The complete set, as defined by the canonical spec (v1.3), plus bounded agency and named constraints.

ConstructKindWhat it does
AGENTfieldNames the agent — one per file, required, first line
VERSIONfieldSemantic version, major.minor[.patch]
TRUST_LEVELfieldInteger trust tier; delegation flows downward only
SANDBOX_AGENTfieldNames the sandbox delegate for isolated execution
PURPOSEfieldOne-line mission statement
GOALfieldMulti-line objective (indented continuation lines)
RECEIVEScontractInput contract as name: type pairs
EMITScontractOutput contract as name: type pairs
MUTATESgovernanceFields this agent may modify at runtime
CANNOT_MUTATEgovernancePermanently locked fields — parser-enforced
CONSTRAINTgovernanceA condition true of every output. One line per invariant, or the named form with HOLDS / SEVERITY / CHECK / FAILURE
PRECEDENCEgovernanceOrders named constraints for conflicts: A > B > C. Hard constraints are never outranked
RULESsectionOperational commands the agent follows
PROCESSsectionOrdered steps executed sequentially
CHECKsectionQuality gates evaluated after PROCESS
FAILUREsectionBehaviour when CHECK gates fail
OUTPUTsectionFormat and structure of the response
SUCCESSsectionfield: weight pairs — must sum to 1.0
CONCEPTblockNamed sub-spec with its own PURPOSE / APPLIES WHEN / NOT WHEN / PRIORITY / REQUIRES / EFFECT
WHENsectionDecision table mapping a condition to a concept activation
SECURITYsectionHard rules that override RULES
TOOLSsectionAvailable tools with permissions and sandbox flags
DELEGATESsectionRouting: Agent to Target on trigger
HUMAN_REVIEWsectionConditions requiring human approval
HISTORYsectionTimestamped change-log entries
BOUNDSagencyHow much an agent may do before it stops: steps, tool calls, tokens, spend, time, failures
SUBAGENTSagencyWhich agents it may start, how many, and with which tools
SANDBOXagencyWhat its tools are confined to: filesystem, network, execution, secrets

Plus three grammar rules: any unrecognised uppercase word on its own line opens a generic section; -  begins a bullet; indentation continues the previous value. Blank lines are cosmetic and carry no meaning.

09 Check your work

A spec is only governance if something enforces it. Two tools read .axiom files directly:

# structural lint — grammar, unknown constructs, malformed contracts
python axiom_cli.py lint my_agent.axiom

# full validation — immutability, trust-level flow, SUCCESS weights,
# named constraints and PRECEDENCE
python -c "import json,sys; from axiom_files.validator import validate_source; print(json.dumps(validate_source(open(sys.argv[1]).read()), indent=1))" my_agent.axiom

Both are also exposed as MCP tools (axiom_lint, axiom_validate), so an editor or another agent can check a spec as it is written.