<-AI Modules Go to ToC Communication ->
1 Reference Model
Figure 1 depicts the Reference Model of the Controller.
Figure 1 – Reference Model of the Controller
The Controller is responsible for the life cycle of a Module. One Controller runs one Module. The Controller is driven by a User Agent; controls the AIMs of the Module, in its own process or through AIM hosts; is the trust authority of the Module; and uses the MPAI Store, Communication, Storage, Access and Trusted Services. The Controller decides; it need not carry the data it decides about.
2 Functions
The Controller:
- obtains the Metadata of a Module and the Implementations it names from the MPAI Store or from local storage, and verifies them;
- builds the Module from its Metadata, resolving the Topology once, at load time, into connections of AIM, Data Type and Port Number. Metadata the Controller cannot resolve does not load, and the Controller says why;
- verifies each AIM before it runs, as trust authority of the Module (6);
- instantiates the AIMs, placing each as its Relation states: in its own process, or on the AIM host named for it (8);
- establishes every Channel the Topology declares, chooses its transport, issues its Grants and binds each AIM’s Port handles (Communication). An AIM cannot open a Channel of its own;
- binds each AIM’s Storage handles (Storage);
- executes the Module in the model its Metadata declares – by exchange or continuously (Execution) – and starts, pauses, resumes and stops it and its AIMs;
- keeps the status of each AIM and applies the Module’s policy when one degrades (7);
- keeps one time base, and stamps every Message and every Storage write;
- keeps the sessions of its clients, and deletes what a session kept when it ends;
- records every Channel creation, Grant, life-cycle change, Storage write and trust decision.
3 Components
Table 1 – Components of the Controller
| Component | Function |
| Module loader | Obtains the Metadata of the Module and the Implementations it names, verifies them against the MPAI Store, and resolves the Topology into typed connections. |
| Life-cycle manager | Instantiates and places the AIMs; starts, pauses, resumes and stops the Module and its AIMs; restarts an AIM that fails, at most its RestartLimit times; releases what was placed when a Module is refused or stops. |
| Executor | Runs the Module by exchange or continuously, as its Metadata declares. One executor serves both models, an exchange being a special case of continuous execution. |
| Channel manager | Establishes the Channels the Topology declares, chooses their transports, issues a Grant for each Channel end and binds the AIMs’ Port handles. |
| Storage binder | Binds the handles through which each AIM reaches its Private Storage, the Private Storage of the Module and Shared Storage, under the rules of the data. |
| Status keeper | Keeps the status of each AIM – ALIVE, DEGRADED, DEAD – with what it reported, and applies the Module’s OnDegraded policy. |
| Trust authority | Verifies AIMs and AIM hosts before they run, issues their credentials and Grants, and decides every trust question of the Module. |
| Time base and Trace | Keeps one time base; stamps every Message and Storage write; keeps the Trace of the Module, signed and hash-chained so that a gap or an alteration is evident. |
| Sessions | Keeps one session per client of a Service, and deletes what the Module kept for it when the session ends. |
4 Interfaces
Table 2 – Interfaces of the Controller
| Interface | Between | Function |
| Controller API, User Agent face | User Agent and Controller | Initialise and destroy the Controller; start, pause, resume and stop the Module; stop one of its AIMs; inquire the status of its AIMs with what they reported; write to a boundary Input Port and read from a boundary Output Port by Data Type and Port Number, with a timeout; place and collect large payloads by reference; initialise a Shared Storage scope and reach Storage as its rules allow; start and stop the record of the boundary; manage resources (Basic API). |
| Controller API, AIM face | AIMs and Controller | Read and write the AIM’s own Ports by Data Type and Port Number, with a timeout; select among Ports with pending Messages; count pending and dropped Messages; place, fetch and release payloads; read the time; report; where allowed, send life-cycle requests to other AIMs of the Module and use External Ports (Basic API). |
| Trust interface | AIMs and Controller | An AIM presents its identity, credentials and the attestation of what it runs, and receives its admission (6). |
| Host control and Trust Protocol | Controller and AIM host | Mutual establishment of trust when the link is opened; then instantiate, start, pause, resume and stop an AIM on the host, and obtain its status and reports (8). |
| Channels between Controllers | Controller and another Controller | Messages between External Ports of Modules run by different Controllers, each carrying its writer’s stamp and signed by its sender (9). |
| Store API | Controller and MPAI Store | Find, retrieve and verify Metadata and Implementations (MPAI Store). |
| Communication and Storage | Controller and Communication, Storage | Create Channels and Storage scopes and the handles to them (Communication, Storage). |
| Security API | Controller and Trusted Services | Cryptography, attestation, secure storage and secure communication (Security API). |
Each call of the Controller API returns a named outcome (Table 3). A User Agent can therefore tell apart what did not happen from what went wrong.
Table 3 – Outcomes of the Controller API
| Outcome | Meaning |
| OK | The call succeeded. |
| NOT_PRODUCED | The Output Port produced nothing in this exchange. This is not an error. |
| TIMEOUT | Nothing arrived within the timeout of the call. |
| NO_SUCH_PORT | No Port of that Data Type and Port Number exists. |
| TYPE_NOT_ACCEPTED | The Port does not accept the Data Type of the datum. |
| NOT_STARTED | The Module or the AIM is not running. |
| NOT_AUTHORISED | The caller has no Grant for the operation. |
| NOT_TRUSTED | The Module was refused: an Implementation or a model is not what the MPAI Store approved. |
| FAILED | The operation failed for another reason, which the Controller states. |
5 Life cycle of a Module
Table 4 – Life cycle of a Module
| # | Step | What the Controller does |
| 1 | Load | Obtains the AIM Instance Metadata of the Module and validates it; obtains the Implementations it names. |
| 2 | Verify | Checks each Implementation and each model against what the MPAI Store approved and the settings declare. Refuses the Module, NOT_TRUSTED, where they differ. |
| 3 | Build | Resolves the Topology into connections of AIM, Data Type and Port Number. Metadata that cannot be resolved does not load. |
| 4 | Place and instantiate | Instantiates each AIM in its own process, or on the AIM host named for it; admits each AIM and host through the Trust interface and the Trust Protocol. |
| 5 | Bind | Establishes the Channels, issues the Grants, binds the Port and Storage handles. |
| 6 | Execute | Runs the Module by exchange or continuously; pauses and resumes it when requested. |
| 7 | Stop | Stops the AIMs, revokes the Grants – the handles of a stopped Module are dead – and releases what was placed. The outputs already delivered stand. |
A Controller may keep the Implementations it built after a Module stops, so that returning to an Application does not load its models again. This is safe because an AIM keeps no state of an interaction between executions, and requires that an AIM serving several Modules or clients at once be safe to call concurrently.
6 Trust authority
The Controller is the trust authority of its Module:
- Policy decision. The Controller alone decides which AIM may reach which Port, Storage key or payload, from the Module’s Metadata as approved by the MPAI Store. It issues a Grant for each Channel end – a credential that admits exactly that end, for that Module instance.
- Policy enforcement is by the transports and the Storage: every read and write passes through a handle the Controller bound, and the Grant is checked at every operation, not once at opening.
- Identity. Every AIM Instance has an identity – Implementer ID, Implementation ID and the fingerprint of its Implementation. The Controller and every AIM host are Trust Anchors. Every Module instance has an identifier assigned by its Controller.
- Verification. As the Verifier of MPAI-PTF, the Controller checks identity, credential, life-cycle state, evidence of what the AIM runs, and policy before an AIM runs. Each decision is recorded in the Trace.
A Controller runs only code it has verified. Trust within one process is established once, before its code runs; everything that crosses the boundary of a verified process is verified at every interaction (Zero Trust and Profiles).
7 Status and degradation
An AIM is ALIVE, DEGRADED or DEAD. An error on a Channel, the loss of the link to the host of an AIM, an exception thrown by an AIM, a required Port that delivers nothing within its MaxAge, a persistent Deadline miss, or a report by which an AIM says it fell back makes the AIM DEGRADED. The Controller starts again an AIM that fails, at most its RestartLimit times; beyond that, the Module’s policy applies (Table 5).
Table 5 – OnDegraded policies
| Policy | What the Controller does |
| StopModule | The default. The run ends and the Module is stopped; the outputs already delivered stand and the others are not produced. |
| StopAIM | The degraded AIM is stopped and the others go on without it. |
| Continue | The others go on, and the degraded AIM runs again at the next exchange. |
A report does not trigger the policy. The User Agent learns what happened from the outcome of its calls and from the status, and may retry, inform its user, stop an AIM or stop the Module. Anything richer – a fallback, bringing a vehicle to a safe stop – is not the Controller’s to decide: it is written into the Module as AIMs.
8 AIM hosts
An AIM host is a program that runs AIMs of a Module on another machine, on the Controller’s orders: it instantiates an AIM, runs, pauses, resumes and stops it, and reports its status. It runs no graph, decides nothing and keeps no Module: the host is the Controller’s instrument, not a Controller. The Controller admits a host by the Trust Protocol, and the host proves which Implementation it runs. A host that goes makes each of its AIMs DEGRADED, and the Module’s policy applies.
9 Several Controllers
One Controller runs one Module. A system of several Modules is run by several Controllers – for example, each Application of a Service under a Controller Instance of its own. Modules run by different Controllers exchange Messages through their External Ports over Channels between Controllers, each Message signed by its sender and carrying its writer’s stamp. A Sub-AIM on another machine does not call for a second Controller: the Module’s Controller controls it through an AIM host.
The Basic API supports interaction between Controllers: a Controller may request Controllers in range to open Remote Ports, and react to what other Controllers send through them. The Controllers may so implement a collective behaviour of their choice – a main Controller to whose information the others react, or no main Controller and a collective logic in all of them.
A Controller may place AIM Instances of its Module on AIM hosts on other machines. An AIM host instantiates, runs, pauses, resumes and stops the AIMs placed on it on the request of the Controller and reports their status; it executes no Topology and takes no decision, and the Module remains the Controller’s. If the link to an AIM host is lost, the Controller treats every AIM placed there as Degraded. A Controller does not manage other Controllers: Controllers running Modules of the same type deal with each other as peers, through External Ports (Communication).
10 Implementations
A Controller can be tailored to its execution environment: a process on a High-Performance Computing system, a library function on a resource-constrained board. There is always a Controller, even in a lightweight Implementation. The Controller API is a control plane: it governs which AIM may reach which Port, when an AIM runs and what it may obtain, and does not prescribe how the bytes of a Message travel. An Implementation in which the Controller hands a Message to an AIM and takes one back conforms, as does one in which an AIM reads and writes its own Ports through handles the Controller bound.
11 Requirements
Table 6 – Requirements of the Controller
| # | Requirement |
| CTR-1 | A Controller shall run one Module, built from its Metadata. The Metadata is authoritative: no AIM, Channel or Port that it does not declare shall exist. |
| CTR-2 | A Controller shall run only Implementations and models it has verified against the MPAI Store. |
| CTR-3 | A Controller shall admit an AIM or an AIM host only after verifying it, and shall record every trust decision. |
| CTR-4 | A Controller shall address Ports by Data Type and Port Number, never by name. |
| CTR-5 | A Controller shall stamp every Message and every Storage write with its time base. |
| CTR-6 | A Controller shall return a named outcome for every call of the Controller API. |
| CTR-7 | A Controller shall apply the OnDegraded policy the Module’s Metadata declares, and shall not otherwise alter the behaviour of the Module. |
| CTR-8 | A Controller shall delete what a session kept when the session ends. |
