AIR Reference

This page helps read AIR produced by the compiler. AIR is the Touba execution contract between source, manifest, runtime, and traces.

Produce AIR

Terminal

touba compile source.tb --out program.air.json

The current machine contract is touba-air-v1, with touba-air-capabilities-v1 and touba-air-json-canonical-v1 profiles. Unknown versions, profiles, or root extensions are rejected before execution.

Main Fields

Field	Role
air_schema_version	logical AIR schema version
air_capability_profile	Capability profile
air_json_profile	Canonical JSON profile
module	compiled Touba module
imports	imports declared in the current module: types, constants, and executable components
definitions.constants	module constants produced by define
definitions.types	module types and fields
definitions.functions	pure functions
definitions.tools	tools, signatures, and requirements
definitions.skills	skills and associated graphs
definitions.agents	agents, uses, callable_by, scopes
definitions.strategies	executable strategies
definitions.triggers	governed event entries
budgets.run	run budgets when present in AIR
execution_graphs	executable nodes and transitions
trace_points	anchors useful for traces

Qualified References

Qualified references connect AIR, manifest, and traces.

AIR references

tool:examples.search/SearchDatasets
agent:examples.search/Researcher
strategy:examples.search/RunDatasetResearch
trigger:examples.daily_research/DailyResearchSchedule

Imports

AIR can carry explicit imports:

AIR excerpt

{
  "imports": [
    {
      "kind": "function",
      "name": "NormalizeQuery",
      "from_module": "examples.common",
      "target_ref": "function:examples.common/NormalizeQuery"
    }
  ]
}

The import keeps the canonical reference of the source module. It creates no grant, secret, memory scope, agent caller, manifest, or handler.

Prepared AIR contains the resolved definitions required by imports: types, constants, functions, tools, skills, agents, strategies, and memories. The runtime executes this prepared AIR; the compiler resolves sources.

Tools

A tool in AIR can carry:

• signature.inputs
• signature.output_type
• required_capabilities
• required_secrets
• memory_accesses

The handler is not in AIR. The handler path lives in the manifest.

Typed Agents

When present, AirAgent.signature declares inputs and output_type. Typed call_agent nodes carry named arguments from with and a result_binding from into. The runtime validates inputs and final output without copying raw values into agent_interface_* trace events. A missing signature cannot be reconstructed from uses; enriched calls require an explicit resolved signature, local or imported from project sources. Imports preserve specialist identity and the original callable_by rules.

A pure record TypeName { ... } expression becomes construct_record, with its nominal type_ref and complete, unique, name-sorted record_fields (name / value_ref). Evaluation creates a fresh JSON value, without interpreting source text or host code.

Lists and text

Source	AIR expression	Operands
[value for item in items if condition]	list_comprehension	List, value, optional condition
concat(a, b)	list_concat	Two lists with compatible types
join(texts, separator)	text_join	Text list, text separator

A comprehension carries a local value_ref binding and a list:… result type. Its filter runs before the output expression. Order is preserved and input lists remain unchanged. The runtime checks types and the iteration limit. text_join returns builtin:Text.

Strategy calls

call_strategy targets a strategy with an explicit interface. Arguments follow takes order and the result is checked against gives. Incompatible arguments are refused before entering the subworkflow. The node retains target_ref, arguments and result_binding; it creates no new run, budget or authority.

Triggers

A trigger in AIR carries:

• its trigger_ref;
• the event family, for example schedule;
• the target strategy;
• static arguments;
• max_runs_per_day and timeout_ms limits.

AIR does not say that the trigger is active in the current environment. Activation lives in the manifest.

Run Budgets

The source limits run block produces budgets.run. Every entry contains value and the limit’s full source_ref. This excerpt omits those locations and is not executable AIR. Imported-module limits combine by minimum, retaining the winning declaration’s provenance.

AIR excerpt

{
  "budgets": {
    "run": {
      "max_steps": { "value": 100 },
      "max_tool_calls": { "value": 20 },
      "max_provider_calls": { "value": 4 }
    }
  }
}

The manifest can restrict these limits with run_limits. It cannot silently broaden them.

These budgets are runtime limits. Token accounting, provider cost, and distributed quotas are separate accounting layers.

Graphs

Graphs carry nodes such as:

• immutable local binding
• function call
• tool call
• skill call
• agent call
• branch
• loop
• give
• human validation
• user interaction

Explicit arguments come from with. Result bindings come from into. Immutable local values come from bind.

Constants and Local Bindings

define appears in definitions.constants. Its value is a typed literal, never a secret.

bind appears as a graph node with kind = "bind". The node evaluates an AIR expression and creates a local name for following nodes.

The runtime can trace that a binding was created, but the exact value is not exposed by default.

What AIR Excludes

info

• Secret values
• Environment values
• ask user answers
• Human decisions supplied at execution
• Handler code
• Raw memory content
• Raw external trigger payload
• Verified / Unverified proof

Parallel node

parallel_call carries target_ref, collection_ref, item_binding, arguments, max_concurrency, max_items, result_binding and source_ref. It belongs to a skill or strategy and calls a target with an explicit output. Machine validation rejects missing or invalid bounds and unknown fields; arguments are type-checked before admission. Branches reuse the target graph; all-join publishes an ordered complete list. The minimal reference runtime excludes this concurrent profile; the native Touba runtime implements it.