Concepts

Six terms carry most of the weight. They are worth reading in order, because each one is defined in terms of the ones before it.

Actor

An actor is a model plus an adapter plus a role. It is the unit the runtime schedules, plans for and commits on behalf of. One model can only be one actor at a time; attaching twice is an error rather than a merge.

Adapter

An adapter describes one class of embodiment. It answers two questions — what can be observed, and what can be attempted — and provides the actuation that runs after a decision is approved. A port with forty cranes needs one gantry adapter, not forty.

Role

A role is the unit of authority. It grants a capability set, imposes constraints, and allocates resource budgets. Roles are declared in domain packs so they can be reused across places. Anything a role does not grant is unreachable, regardless of what the planner would prefer.

Goal

A goal is an objective expressed in the runtime’s own vocabulary, with a satisfaction predicate, an optional decomposition into sub-goals, and abandonment conditions. Goals are submitted by your systems — a dispatcher, a quest system, a scheduler — not invented by the agent.

Action

An action is a single declared operation an adapter exposes, with typed parameters, preconditions and a cost. The planner composes plans exclusively from declared actions; there is no path by which it calls arbitrary code at decision time.

Resource

A resource is anything finite an action spends or claims: currency, fuel, stock, cargo capacity, a berth, a runway clearance, an assignment. Resources move inside a transaction that applies whole or not at all.

How they compose

An actor is a model bound to an adapter and a role. It receives a goal. The planner decomposes that goal into actions drawn from the adapter’s surface and permitted by the role. Each action is validated, its resource costs are settled atomically, and only then does it actuate and commit.