Execution Model

Touba compiles your program to AIR. The runtime then applies that contract and produces an execution trace.

The model proposes. Touba checks the call. Your handlers perform the action and the trace records its execution.

Source .tb

The .tb file is the user-readable program.

It can declare:

• types;
• pure functions;
• tools;
• skills;
• agents;
• strategies;
• logical memories.

AIR

AIR is the central contract between the language, runtime, CLI, VS Code extension, and inspection tools.

It carries declarations, execution graphs, arguments, bindings, pure expressions, required capabilities, required secrets, human interactions, invocation authority, and memory scopes.

AIR keeps environment-sensitive material outside the compiled contract:

• real secret values;
• handler code;
• answers collected during execution;
• environment configuration.

Runtime

The runtime executes AIR.

In a Touba graph, give returns the result of the current path and stop stops that path. Instructions after a terminal return do not execute; the compiler reports them as UnreachableStatement.

For a tool, it verifies the manifest before launching a handler:

Structure

declared tool -> manifest binding -> grants and limits -> handler -> result

The runtime can refuse execution before the handler if a grant, secret, memory scope, agent caller, or payload does not satisfy the contract.

For an agent driven by a provider, the runtime adds a bounded sequential loop:

Structure

agent -> model input -> catalog if requested -> authorized resource -> observation -> next decision

The model proposes. The runtime verifies uses, callable_by, signatures, manifest, secrets, scopes, and step limits before executing or refusing.

Composition, concurrency and recovery

Source calls and if, for, while controls follow their declared order. parallel distributes a typed list across a target under explicit ceilings, then joins results in input order. Groups can nest; invocation data stays isolated while budgets and cancellation remain run-wide.

Before the group's first call, Touba checks list size and all arguments. When a branch fails, it stops new starts and waits for active calls to settle cooperatively. It publishes no successful partial result and does not undo external effects already engaged.

A human pause preserves the call stack and, in parallel groups, branch continuations. Resume revalidates authority without redispatching completed calls. Preserve private checkpoints and effect journals: public traces alone cannot resume execution. The recovery guide explains which mechanism to use and its crash boundaries.

Trace

The trace makes execution observable.

It records calls, pauses, resumes, authorizations, and refusals. The user_interaction_answered event summarizes an answer without copying its value. Raw provider observations stay outside the trace. show messages are returned separately in messages; the trace records the event and its references, not the text. Keep secrets out of business outputs too.

Touba Surfaces

Touba surfaces include the CLI, textual inspection, LSP server, and VS Code extension.

They display what exists in AIR or traces. They do not invent semantics absent from the runtime.