<-Controller Go to ToC Storage ->

1 Reference Model

Figure 1 depicts the Reference Model of Communication.

Figure 1 - Reference Model of Communication

Figure 1 – Reference Model of Communication

Communication is how data moves: between the AIMs of a Module, between the User Agent and the boundary of the Module, between a Module and AIMs on other machines, and between Controllers. Every way data moves is a Channel or a Storage, and every Channel is served by a transport behind one interface. The Controller decides which end may reach which Channel; the transports carry the data.

Table 1 – Elements of Communication

Element Definition
Channel Joins one Output Port to the Input Ports the Topology connects to it. It has an identity, a behaviour at each reader and a transport.
Channel end The Output Port that writes to a Channel, or an Input Port that reads from it. The boundary Ports of a Module are Channel ends too, held by the User Agent.
Handle What an AIM, or the User Agent, holds to act on its own ends, bound by the Controller together with a Grant. No other access to a Channel exists.
Message Data or an Object, as the schema of its Data Type defines it, with the Controller’s stamp.
Payload A large part of an Object – speech, a picture, a LiDAR sweep – that may travel apart from its Message.
Transport What carries the Messages of a Channel and, where it can, its payloads.
Payload channel What carries, beside the link of two Controllers, the payloads that travel apart from their Messages. The two Controllers open it, under the credentials of the link; it carries no Messages.
Control path Carries the life-cycle signals of the Controller. No AIM can write to it.

2 Channels

A Channel has an identity: the Module instance, and the AIM Instance, Data Type and Port Number of its writer. The Controller opens both ends of every Channel the Topology declares, through its transport, and gives each AIM, and the User Agent at the boundary, only the handles to its own ends. An AIM cannot open a Channel of its own, and the AIMs never know which transport serves a Channel.

Channels are unicast from each writer: one Output Port writes to a Channel, which delivers each Message to every Input Port it joins. The Communication component is turned on jointly with the Controller and need not be persistent.

3 Messages

A Message is Data or Data with attached Qualifier (Object). Within one process it need not be serialised; it is serialised when it leaves the process. A reader knows what a Message is from its Data Type and its Qualifier, if present, before reading its data.

The life-cycle signals – START, STOP, PAUSE, RESUME, the High-Priority Messages – are the Controller’s own, carried on its control path, which no AIM can write. All other Messages – the Normal-Priority Messages, of MPAI-AIF defined types – are Messages on Channels.

MPAI-AIF V3.0 has no separate Event mechanism. An occurrence that AIMs must react to is a Message on a Channel. An occurrence concerning the execution of a Module is a change in the status of an AIM – Alive, Degraded, Dead – which the Controller reports through the status functions of the Controller API, and which triggers the policy the Module declares for degradation and the on Degraded: section of its Workflow.

4 Transports

Table 2 lists the transports.

Table 2 – Transports

Transport Ends Messages Payloads
Controller Any Relayed by the Controller Through the Controller
InProcess One process In-memory bounded queue of Objects Shared without copying
Bus The AIMs of one Module, on one machine One Channel for a Data Type: any number of writers and readers; each reader keeps the last value written by any writer Shared without copying
PointToPoint Two processes of one machine Length-prefixed JSON over a local socket or pipe Shared-memory ring created by the Controller
Remote An end on another machine Length-prefixed JSON over TLS, addressed by Module instance, AIM Instance, Data Type and Port Number Inlined, or apart on the payload channel of the link
External A Port of another Controller As Remote, with the writing Controller’s stamp As Remote

The transport of a Channel is decided in this order: where an end is an AIM placed on another machine, Remote; otherwise the transport the Output Port’s Metadata states; the Controller transport where it states none. An Input Port may state which transports it accepts; where the Output Port’s transport is not among them, the Module does not load. A transport is never silently replaced by a slower one.

A Bus is the exception to Channels that are unicast from each writer: it is one Channel for a Data Type in a Module, which any number of AIMs write and any number of AIMs read. Its members are, by Data Type, the Output Ports of the Module’s AIMs whose Metadata states the transport Bus and the Input Ports that accept Bus; no Topology joins them, and an Input Port that accepts Bus may also accept other transports and be joined by the Topology as any Input Port. A Message written by any member is put into every reader end, which keeps one value: the last written, by anyone. A writer that is also a reader reads what it wrote. A Module has one Bus for a Data Type. A Controller shall not start a Module whose Bus has an end on another machine.

On the Remote transport, a reader end on another machine keeps the behaviour its Input Port declares, and a blocking reader holds the writer across machines as on one: a Message is acknowledged once it is put into its reader end. A link that fails delivers nothing more: the AIM at its far end is DEGRADED, and the writer goes on. The control path of an AIM that executes apart from the Controller and the Channels to it share one link.

MPAI-MAS is not a transport of MPAI-AIF: it is built on MPAI-AIF and carries the Controller API between a Remote Client Application and a Service (MPAI as a Service). A Controller reaches an AIM that executes apart from it through the Remote transport.

A Controller provides the InProcess, the Bus and the Controller transports, and the Remote transport for a Channel with an end on another machine. An Output Port may declare the transport of its Channel; where it does not, the Channel uses the Controller’s default transport, and a Channel with an end on another machine uses Remote. A Controller shall not start a Module if a Channel requires a transport the Controller does not provide, or one that a reader of the Channel does not accept.

On the Remote and External transports a payload that was written by reference travels apart on the payload channel of the link: a TLS connection that the two Controllers open beside the link of the Messages, admitted by the same credentials and subject to the same Grant checks. The Messages are the control of an exchange and the payloads its data: the link carries no payload that travels apart, and the payload channel carries no Message. A payload channel that fails is a link that fails.

5 Port behaviour

An Input Port may declare its behaviour (Table 3).

Table 3 – Behaviour of an Input Port

Property Meaning
Depth The number of Messages the Port holds.
Overflow What a write to a full Port does: Block, DropOldest or DropNewest.
MaxAge The age beyond which a Message is discarded rather than delivered.
AcceptedTransports The transports the Port accepts.

A Port that declares none is Block, with a Depth of the Implementation’s choosing and no MaxAge – the behaviour suited to an exchange. Messages dropped or discarded are counted. Every blocking operation takes a timeout.

A loop needs its feedback declared. A feedback input that Blocks deadlocks the loop when inputs come faster than it turns, since the writer of the feedback waits on a full Port that only new inputs empty. A feedback input therefore keeps its latest value: Depth 1, DropOldest.

6 Communication in the two execution models

A Module is executed by exchange or continuously, as its Metadata declares (Execution). The two models communicate differently (Table 4).

Table 4 – Communication in the two execution models

Exchange Continuous
User Agent at the boundary Writes the inputs it has to boundary Input Ports, then reads the boundary Output Ports it wants. Over MPAI-MAS, an exchange closes at the first Output read after one or more Input writes: that read runs the Module on the inputs written. Binds devices to boundary Ports for the life of the Workflow. Messages flow as streams.
Port behaviour Block, the default. A Port receives at most one Message in an exchange. As each Input Port declares: a sensor stream typically with MaxAge and DropOldest; a feedback input with Depth 1 and DropOldest.
Nothing produced A boundary Output Port that produced nothing returns NOT_PRODUCED, which is not an error. The Port has no pending Message. A reader selects among the Ports with pending Messages.
Waiting No suspension: a Module never waits for an input the User Agent did not undertake to give. No suspension at the boundary either. A required input that delivers nothing within its MaxAge makes the AIM DEGRADED.

An exchange is a special case of continuous execution: Messages written to the boundary, each AIM run once on what it has received, the Outputs read. The same Channels, transports and Port behaviours serve both.

7 Payloads

A large payload may travel apart from its Message. The writer places it on the path of its Channel, and the Object carries its length and a reference to it, as the schemas of media Objects allow. The Qualifier always travels in the Message if present, so that a reader knows what a payload is before fetching it. Only a reader at the far end of that Channel can resolve the reference, and a payload is freed when every reader has released it or its Port’s MaxAge has passed. A reference means nothing outside the Controller that issued it: at the boundary of a Controller a payload either is inlined or, on the Remote and External transports, travels apart on the payload channel of the link.

The writer of an Object decides whether its data travel inline or by reference, within the forms its Data Type allows; no size threshold applies. A reference issued by a Controller has the form aif:payload/<Channel>/<sequence>, where <Channel> identifies the Channel as <Module>/<writer AIM>.<DataType>#<PortNumber>. It is valid only within the Controller that issued it, and is released when every reader of the Channel has taken the Message or the largest MaxAge of its readers has passed. Where a Message leaves the Controller that issued its references, the Controller does as follows. To the User Agent, and over MPAI-MAS, it replaces each reference with the data. To an AIM that executes apart, and to another Controller, it either replaces each reference with the data, or replaces it with a reference that the receiving Controller can resolve on the payload channel of the link; the Message then carries, with the Qualifier, the length of the payload and a hash of it. The Message is signed, and the signature covers the length and the hash. The receiving Controller fetches the payload when its reader asks for it, checks it against the length and the hash, and refuses and counts a payload that does not match (COM-8). The payload is freed on the writing side under the rules above.

8 Time

A Controller has one time base, declared in its Metadata. Every Message is stamped, when written, with the time on that base, through the handle the Controller bound; the writer supplies no stamp. A Message written on another machine is stamped on the same base: the machine moves its clock by the offset of the Controller’s, measured over the link when a Module starts there.

A time an Object carries of its own – the time of its acquisition, for instance – is a different fact, and travels in the Object. An AIM that must run at a period, or complete within a deadline, declares Period or Deadline in its Metadata, and a Controller that cannot honour them refuses the Module when it is started.

What executes an AIM apart from the Controller stamps Messages on the time base of the Controller it serves: before running the AIMs placed there, it estimates the offset of the Controller’s clock from its own by request and response, taking the Controller’s time as of the midpoint of the fastest of several exchanges. MaxAge is measured on the local monotonic clock from the arrival of a Message. Controllers stamp in UTC; a Message between Controllers carries the identifier and the stamp of the Controller that wrote it. How a Controller keeps its clock close to UTC – for instance with GNSS or gPTP in a vehicle – is a matter of the Implementation.

9 Between Controllers

A Controller exchanges Messages with Controllers on other machines through the External Ports of its Module, over the External transport, only with Controllers admitted by a Trust Authority it trusts, and only as that Authority’s policy allows.

A Trust Authority admits a Controller: it verifies the Controller’s attestation and the conditions of its service, and issues a credential naming the Controller, the role in which it is admitted and the time for which it is valid. Two Controllers open a link when each presents a credential of the same Trust Authority and the Authority’s policy allows their roles to exchange. The identifier of a Controller (controllerID) is valid from the opening of the link until it is closed: the Controller leaves, its credential expires, or it can no longer be reached.

A Controller trusts a Trust Authority because its User so decided – by entering a city that has one, by joining a service that is one – and the User Agent passes that decision to it (Basic API 3.9). Where Controllers find each other is a matter of the deployment: by announcements in range, as vehicles do, or at a rendezvous the Trust Authority gives.

On a link, what an External Output Port gives may be written to the External Input Ports of the same Data Type of the other Controller. A Message from another Controller carries that Controller’s identifier and stamp, and is signed by it. The signature covers the content of the Message, the Port it is for (its Data Type and Port Number) and the stamp, so that none of them can be changed on the way. A Controller refuses a signed Message whose stamp is not within a short time of its own clock, and one it has received before, and counts what it refuses. A payload that travels apart on the payload channel is given only to the Controllers that the Message that offers it concerns.

Trust is not kept from the opening of a link. While a link is open, a Controller checks that the credential of the Controller at its other end, and the anchor that issued it, are still valid, and closes the link when they are not. Every such decision – a link accepted or closed, a Message or a payload refused – is recorded in the Trace of the Controller (Zero Trust and Profiles).

9.1 Bouts

Where the instances of a flow of one Data Type are given often and the link is narrow – a vehicle and a roadside unit, an edge server – most of each instance repeats the one before it. A Controller may then give the flow in a Bout: what the instances have in common is given once, as a Zstandard dictionary (RFC 8878), and each instance travels as one Zstandard frame compressed with it. The instance that the receiver decompresses is exactly the instance that was given, an ordinary instance of its Data Type.

A Bout is given by a Controller: on an External Port, to the other Controllers of the link, and on a boundary Output Port of a Module, to the User Agent. A User Agent may give a Bout on a boundary Input Port of a Module, to its Controller, when it holds an Instance Credential that this Controller issued to it (Basic API 3.1.3): it then makes, compresses and signs the Bout and its Bout Instances as a Controller does, with the key of that credential, and what this section says of the Controller that gives a Bout applies to it. When the Controller is destroyed, the credential is revoked and the Bouts the User Agent gives are closed. Inside a Module there are no Bouts. The AIMs read and write full instances; the Controllers make, compress, sign, verify and decompress.

  1. The Controller gives the Bout (AIF-BOU) before the first Bout Instance. The Bout states the Data Type and Port Number of the flow, its BoutID – an integer from 32768 to 2147483647, the range RFC 8878 leaves to private use, which the Controller does not reuse while its anchor is valid, nor a User Agent while its Instance Credential is valid – the Dictionary, whose Dictionary_ID is the BoutID and whose content is the canonical form (PTF-JSON-CANON-V1) of an instance of the flow, the SigningMode, the MaxInstanceLength and, where it is given at intervals, the RepeatInterval.
  2. The Bout, and each Bout Instance, is signed as every Message between Controllers (COM-12) – by a User Agent, with the key of its Instance Credential – over its content, the Port it is for and the stamp of its writer, which its Binding states: Data Type#Port Number@stamp/BoutID. How it is protected is specified by MPAI-PTF.
  3. A Bout Instance is the canonical form of the full instance, with its Data Exchange Metadata, compressed as one Zstandard frame with the Dictionary. The frame carries its Dictionary_ID and its Frame_Content_Size. On a link, it travels as the binary payload of the Message, not inside JSON text.
  4. A receiver checks a Bout Instance in this order, and refuses it, and counts it, at the first check that fails: (a) the Dictionary_ID of the frame names a Bout that the receiver has accepted (PTF AcceptBout) and that is in force on this Port; (b) the Frame_Content_Size is present and not larger than the MaxInstanceLength of the Bout – checked before decompressing; (c) the decompressed bytes are canonical JSON and validate against the JSON Schema of the Data Type; (d) the Binding names this Port and the BoutID, its stamp is fresh (COM-13), and its Sequence is larger than any accepted in the Bout; (e) the Signature, or in a Chain the chain value and, when it arrives, the signature that ends its segment, verify (PTF). Then the instance is delivered as an ordinary Message.
  5. A receiver that is given a Bout Instance of a Bout it does not hold refuses it, and may ask the Controller that gives the flow for the Bout (Basic API 3.10 and 5.6). A Controller repeats a Bout every RepeatInterval milliseconds where the Bout states one.
  6. When the Dictionary no longer serves – a new Spatial Qualifier, another M-Instance – the Controller gives a new Bout with a new BoutID, and closes the previous one (PTF CloseBout). After it is closed, the instances of a Bout are refused.
  7. An instance is stored decompressed, with its Data Exchange Metadata, so that it can be read and verified without its Bout.
  8. When two Controllers link (Basic API 3.9), each states which of its Ports accept Bouts in the AIM Metadata of its Module (Bout of each Port), which the other reads with MPAI_AIFM_External_List (Basic API 5.1); a Port that does not accept them is given full instances.

10 Security

Every read and write passes through a handle the Controller bound, and the transport checks the Grant of that handle at every operation, not once at opening. Messages are immutable once written. Between processes, Channels are authenticated local channels; between machines and between Controllers, Messages travel over TLS, and payloads are inlined or travel over the payload channel, which is TLS as well. The handles of a stopped Module are dead (Zero Trust and Profiles).

11 Requirements

Table 5 – Requirements of Communication

# Requirement
COM-1 Data shall move between AIMs, and between a User Agent and a Module, only on Channels the Controller established, or through Storage.
COM-2 A Channel shall be addressed by Data Type and Port Number, never by a Port name.
COM-3 A Message shall carry its Qualifier, if present, including when its payload travels apart.
COM-4 A transport shall check the Grant of a handle at every operation.
COM-5 A transport shall not be replaced by another that the Input Port does not accept, nor silently by a slower one.
COM-6 Every Message shall be stamped on the Controller’s time base when written; the writer shall supply no stamp.
COM-7 A payload that crosses the boundary of a Controller shall be inlined or shall travel on the payload channel of the link; it shall not travel as a reference the receiving Controller cannot resolve.
COM-8 Messages dropped or discarded shall be counted.
COM-9 A Controller shall open a link with another Controller only when both hold credentials of the same Trust Authority in roles its policy allows to exchange.
COM-10 A Controller shall trust a Trust Authority only as its User Agent states, and accept it only if it proves that it holds the anchor stated.
COM-11 A payload that travels on a payload channel shall match the length and the hash that the signed Message carries; one that does not shall be refused and counted.
COM-12 A Message from another Controller shall be signed by its sender over its content, the Port it is for and its stamp.
COM-13 A Controller shall refuse a signed Message from another Controller whose stamp is not fresh, or that it has received before, and shall count what it refuses.
COM-14 A payload on the payload channel shall be given only to a Controller that the Message that offers it concerns.
COM-15 A Controller shall close a link when the credential of the Controller at its other end, or the anchor that issued it, is no longer valid, and shall record in its Trace every trust decision on a link.
COM-16 A Bout shall be given only by a Controller, on an External Port or on a boundary Output Port, signed as COM-12 requires, or by a User Agent, on a boundary Input Port, signed with the key of an Instance Credential issued to it by the Controller that receives it; in both cases before its first Bout Instance.
COM-17 A Bout Instance shall be one Zstandard frame of the canonical form of the instance, carrying the Dictionary_ID of the Bout and its Frame_Content_Size.
COM-18 A receiver shall refuse, and count, a Bout Instance whose Bout it has not accepted or that is closed, whose content size exceeds MaxInstanceLength, whose decompressed instance does not validate, or whose Binding, Sequence, Signature or chain does not verify, checking them in the order of 9.1.
COM-19 A Controller shall not reuse a BoutID while its anchor is valid, nor a User Agent while its Instance Credential is valid.
COM-20 An instance received in a Bout shall be stored decompressed, with its Data Exchange Metadata.
COM-21 A Controller shall issue an Instance Credential to a User Agent only after verifying that the User Agent holds the key its Cryptographic Instance Identity names, and shall revoke it, and close the Bouts the User Agent gives, when it is destroyed.

<-Controller Go to ToC Storage ->