Bindings and storage

The bindings record

A component declares its bindings in a bindings { … } record of its declaration. The record is checked, like the settings of a config { … } block, but it is a record of its own: a binding decides what the component may reach, so no configuration layer adds one or changes it.

The record has five fields, and each of them is optional:

Each binding is a package export

• Selected like every export. Each field is bound to an export of a package that you select in pack.ael and name in the file's header with refer <package> select <export>;, the same header that selects every package export; see Using packages.
• Your scopes apply. The nearest pack.ael that declares the package supplies it, as for any package.
• No secrets in source. Addresses and credentials come from your configuration, as references resolved when a run starts, and never appear in your source; see Configuration.

Resolved once per run

Bindings are resolved once, when a run is admitted, and pinned into the run's identity with its prompt, configuration and model binding. A change to a package, an address or a configuration value applies to the runs that start afterwards, never to a run already under way.

Only declared bindings

• Checked when you check. A use of memory, knowledge, storage or a database that the component did not declare is refused by the check, with a diagnostic that names the field.
• Handles only for what you declare. When a run starts, AEL creates handles only for the declared bindings, so there is nothing else for the run to reach.
• Nothing connects while you build. Checking, compiling or building a project with bindings opens no file, socket or process.
• Ceilings inside the budget. Every binding has ceilings that sit inside the run's budget and limits, and a call that would go past one is refused before it acts; see Budgets, retries and validation.
• Data, never authority. What a binding returns, such as a recalled memory or a retrieved document, is data: it never grants a permission or becomes an instruction.

Nodes, subagents and isolated components

• A node narrows its agent's. A node's record only narrows its agent's: a node never reaches a binding that its agent does not have.
• A subagent receives grants. A subagent draws on the budget, deadline and cancellation of the agent that spawned it, and holds only the permissions and resources that agent grants it, or, when it is isolated, only the resources it declares itself. It declares no storage point of its own and no memory that outlives it: when it is not isolated, a storage, memory, knowledge or database handle reaches it only as an explicit grant from its spawner, always a part of what the spawner holds. See Subagents.
• An isolated component holds only its own. You mark an agent, node or subagent as isolated: it always runs in a sandbox in its own process, outside the shared communication layer, reachable only through the edges you declare and holding only the resources it declares itself. Isolation needs the isolation facilities of Linux and runs only on the Linux target the documentation names for it: on macOS, on Windows, on microcontroller boards, on other Linux targets and on any host without those facilities, an isolated component is refused, never run without isolation. Its bindings are exactly those it declares in its own record, with nothing inherited and nothing granted in through a spawn or an edge. An isolated subagent receives no grant: it holds only the bindings it declares itself, and never a storage point of its own. See Isolated components, and Communication between agents for its edges.

The storage point

A run is durable only when its agent declares a storage point, a storage package you select that keeps the run's state in a directory, in object storage or in an SQL database you run; without one, the run runs to completion and keeps nothing.

• The storage binding is the storage point. A run keeps its journal, its memory and its stored data there, and a run whose agent declares a storage point resumes and survives restarts; see Durable runs and approval.
• Without one, nothing is kept. The run keeps its state only in the running program. Resuming a run, or reading the status or events of an earlier run, is refused.
• A failure fails closed. When the storage point fails at a checkpoint, the run fails: it never continues with weaker durability, and usage whose outcome is unknown stays counted.
• Your own database, on your own machine too. A local SQL database you run can be the storage point of a run on your own machine, as a database on a server can.
• The packages. Optional storage packages keep data in files on a local or mounted path or in object storage, and connect to SQL databases you run; each can be an agent's storage point. The Package catalog describes them.

The storage point of AEL Cloud

In AEL Cloud, a run whose agent declares the platform's storage point resumes after an interruption, with its state kept by AEL Cloud. The agent declares it with the reserved value platform:

bindings { storage: platform; }

• platform names AEL Cloud's storage point, so your application names no bucket or database of the service.
• A run on your own machine refuses storage: platform, with an error that names the rule; there, the storage point is a storage package you select.

AEL Cloud describes the service.

Database bindings

A database binding runs only the statements you write: a query a model proposes is data, and it runs only when a validator you write admits it.

The SQL contract that database packages implement has prepared statements with placeholders for their values, typed rows and transactions; see the Package catalog.

Knowledge, memory and skills

• Knowledge. Optional vector-store packages index and search your knowledge for retrieval, in a database you run. A knowledge binding names the store an agent retrieves from; Retrieval over your documents shows retrieval from end to end.
• Memory. Long-term memory keeps the scopes, retention and deletion rules of Memory and state.
• Skills. A skill is a versioned, reusable bundle of instructions, typed tools and functions that an agent or subagent loads through the skills it declares; its tools run only where the agent's permissions allow, and it adds nothing the agent did not declare. Skills describes them.

Bindings and model bindings

A model binding is another thing: model: binding("primary_model") in a node's config { … } block names the model endpoint the node calls, which your configuration or the deployment defines; see Models and providers. The bindings { … } record names the packages that hold a component's memory, skills, knowledge, storage and databases.

Honest limits

• AEL itself contains no database. You run the database and choose the directory or the bucket, and a binding to a system that cannot be reached returns a typed error.
• A run is durable only with a storage point: without one, no restart, resume or later status read finds it.
• A storage point keeps a run's records; it does not make an effect outside your program happen exactly once. See Side effects.