Changelog

What it does

Adds a MSG transport type for APIs where the address is a named subject (like mesh.registry.register) rather than a URL path. Subjects are dot-delimited strings published to a message broker.

The (reply) modifier indicates request/reply semantics (like HTTP request/response). Without it, the message is fire-and-forget. Parameterized subjects work like HTTP path params: MSG mesh.agent.{agent_id}.inbox.

Why it's needed

MAPI v0.94 defined six transport types, all assuming HTTP endpoints or WebSocket paths. But APIs built on NATS, MQTT, AMQP, and Kafka use a different addressing model entirely—there's no URL, no HTTP method, no path. Without MSG, these APIs simply couldn't be described in MAPI.

What it does

Adds a ## Subscription: heading type with a SUB transport for pub/sub patterns. Agents declare interest in a topic pattern and receive matching messages over time.

Wildcards use NATS-style syntax: * matches exactly one token, > matches one or more tokens (must be at end). MQTT equivalents (+ and #) map directly.

Why it's needed

Pub/sub is arguably more common than webhooks in backend systems. MAPI v0.94's event model was limited to webhooks (HTTP callbacks to a registered URL). But in message-oriented architectures, subscribers connect to a shared bus and declare interest in topic patterns—no callback URL, no HTTP involved. This is the dominant event model in NATS, MQTT, Kafka, Redis Pub/Sub, and RabbitMQ.

What it does

Adds a ## Lifecycle: heading with a ~~~states block that defines a state machine: which states a resource can be in, which transitions are valid, and optionally which capabilities trigger them.

The * wildcard means "from any non-terminal state." Capability IDs in brackets are optional—when present, they link transitions to specific capabilities for code generation.

Why it's needed

Many systems have resources that transition through states over multiple interactions—tasks, orders, deployments, CI/CD pipelines. Previously, these state machines had to be described in prose within Logic Constraints, which is fragile and hard for LLMs to reason about programmatically. Structured state definitions let LLMs understand what states exist, which transitions are legal, and what "terminal" means.

What it does

Adds a direction field to capability metadata. The default outbound means "you call this" (the existing assumption). The new inbound value means "you implement a handler for this"—other agents send messages here and you must respond.

Why it's needed

MAPI v0.94 implicitly assumed a client-server model: the document describes a service, the reader is the client. But in peer-to-peer protocols, every agent is both client and server simultaneously. Without this distinction, an LLM can't tell whether to generate a function call (outbound) or an event handler (inbound). One metadata field solves it cleanly.

What it does

Adds a ## Envelope: heading for defining the wire format that wraps all messages. In HTTP, wire format is implicit (headers, status codes). In message protocols, every message is wrapped in an envelope carrying identity, correlation IDs, tracing, and the payload.

When an Envelope is defined, each capability's Input and Output schemas describe the contents of the envelope's payload field—not the full wire message. This composition rule is explicit in the spec so LLMs know to construct the envelope and nest the payload inside it.

Why it's needed

An LLM generating code to send a message over a bus needs to construct the full envelope—not just the payload. Without a structured envelope definition, the LLM would have to guess at wire format from scattered Logic Constraints, or the spec author would have to redundantly include envelope fields in every capability's Input schema.

What it does

Adds three metadata fields for message bus capabilities:

delivery — at_most_once (fire-and-forget), at_least_once (may duplicate, use idempotency), or exactly_once (requires broker support like JetStream or Kafka transactions).

ordering — unordered, ordered (publish order within subject), or partition_ordered (ordered within partition key).

consumer_group — When set, only one member of the group receives each message (load balancing). Without it, all subscribers get every message (fan-out).

Why it's needed

Delivery guarantees, ordering, and consumer groups are fundamental to message-oriented architectures. They affect how code must be written—at-least-once delivery means handlers must be idempotent, consumer groups mean you need graceful rebalancing, partition ordering constrains how you can parallelize. Making these explicit in metadata lets LLMs generate correct code rather than assuming defaults that may not hold.

All seven reference cards have been updated for v0.95:

MAPI-AUTHOR — New transport strings, message bus examples, envelope/lifecycle/direction guidance.

MAPI-CONSUMER — MSG/SUB transport patterns, direction awareness, envelope composition rules.

MAPI-VALIDATOR — Validation rules for all new heading types, transport patterns, states blocks, and messaging metadata.

MAPI-AUTH — Transport-layer auth patterns for message protocols.

ASYNCAPI-TO-MAPI — Kafka/AMQP/NATS now map to MSG/SUB transports instead of the previous WS workaround.

MAPI-TO-OPENAPI — Guidance on handling MSG/SUB capabilities (no OpenAPI equivalent).