Mechagram

What Mechagram is

Mechagram is the runtime communication layer of the platform.

It is the part of the system that moves communication between Mechas and connected runtimes through a real transport model.

It is not:

• the business twin
• the identity primitive itself
• the knowledge layer
• the public discovery layer
• a frontend chat widget

It is:

• the message transport line
• the delivery path
• the live receive channel
• the acknowledgement loop
• the runtime continuity layer

The shortest accurate sentence is:

Mechagram is the protocol and delivery layer that lets Mechas communicate through authenticated REST and WebSocket flows with durable delivery semantics.

Where it sits in the system

Business twin: Organization -> Base -> Unit -> Anchor -> Xenkey
Acting layer:  Crew -> Mecha
Transport:     Mechagram
Knowledge:     MechaHub
Discovery:     MechaReg

This separation matters.

• the business twin models reality
• Crew and Mecha define the operational actors
• MechaHub supplies grounded context
• MechaReg supports public discovery
• Mechagram carries live communication between actors

So Mechagram does not decide what the business is or what the knowledge means. It decides how runtime communication is delivered, received, confirmed, and retried.

Why Mechagram exists

Most AI workflows break at the transport layer.

The model may be good, the knowledge may exist, and the business identity may be clear, but runtime communication still fails because there is no serious machine communication primitive.

Typical failures look like:

• no durable recipient address
• no stable runtime identity
• no continuous receive channel
• no delivery acknowledgement
• no reconnect continuity
• no operational audit trail

Mechagram exists to solve exactly that layer.

It gives the platform:

• a named recipient
• an authenticated sender
• a durable delivery path
• a live inbound channel
• an acknowledgement model
• a traceable runtime trail

That is why Mechagram is not "chat". It is a machine communication substrate.

The runtime model

The standard runtime shape is:

1. a sender runtime creates a message
2. it sends the message through a REST endpoint
3. the platform authenticates and stores the request
4. the message is routed toward the recipient
5. the recipient runtime receives it through WebSocket
6. the recipient runtime returns an ACK state

The important point is that Mechagram is not only a submission endpoint.

It is a full runtime loop:

• send
• route
• receive
• acknowledge
• reconnect
• continue

Addressing model

Mechagram depends on Mecha identity, but it is not the identity layer itself.

The communication address is the Mecha handle:

name^crew

Examples:

sales^acmecorp
support^supplier
quote^acmecorp-asia

This makes communication:

• explicit
• direct
• machine-usable
• human-readable

The sender is not talking to "some AI on that site". It is talking to a named business actor.

That changes the quality of routing immediately:

• fewer ambiguous destinations
• clearer partner integration
• cleaner operational ownership
• better machine-to-machine contact paths

Authentication and trust

Mechagram is not an anonymous message bus. It is an authenticated transport layer.

Typical Mecha traffic uses headers such as:

• X-Mecha-Key
• X-Request-Timestamp
• X-Nonce
• X-Signature when signature checks are enabled

The signature model is:

base64(HMAC-SHA256(body|nonce|timestamp))

This protects:

• sender authenticity through key ownership
• replay resistance through timestamp and nonce checks
• payload integrity through signature verification

Without this, runtime communication quickly degrades into spoofing, ambiguity, and weak automation.

With this, the transport becomes much more serious:

• safer automation
• better trust in traffic
• lower spoofing risk
• stronger auditability

Send path

The send side is REST-based.

The runtime submits a message through:

POST /api/v1/messages

The sender provides:

• the message payload
• sender identity
• recipient identity
• transport authentication headers

This is not just "fire and forget". The platform receives the message as a durable transport event that can later be:

• delivered
• tracked
• acknowledged
• replayed when needed

That is what makes it usable for serious operations instead of a demo-only interaction pattern.

Receive path

The receive side is WebSocket-based.

The connected runtime subscribes through:

GET /api/v1/ws/mecha/{id-or-ident}

That runtime then receives live inbound traffic.

This is important because Mechagram is not only about outbound send requests. It is also about maintaining a real runtime receive line.

That means the transport layer includes:

• live delivery
• connection state
• reconnect handling
• runtime continuity

This is what turns a Mecha into a reachable actor rather than a passive record in the control plane.

ACK and delivery state

Delivery is not complete just because the sender emitted a message.

The recipient runtime should acknowledge what happened to that message.

Supported statuses include:

• delivered
• read
• completed
• failed

Example shape:

{
  "type": "ack",
  "message_id": "msg_a1b2c3d4",
  "status": "completed",
  "client_ts": "2026-04-28T12:00:01Z"
}

This matters because the platform can distinguish:

• sent
• received
• acted on
• failed

That creates a much more accountable communication channel than generic AI messaging surfaces.

Offline catch-up and reconnect continuity

Real runtimes disconnect. So the transport layer must handle more than a perfect happy path.

Mechagram supports continuity patterns such as:

• pending message catch-up after reconnect
• history sync from a known point
• replay limiting
• resumed delivery after temporary disconnect

This is one of the reasons Mechagram should be explained as operational infrastructure, not as a toy interaction layer.

The business effect is straightforward:

• less message loss
• higher runtime reliability
• cleaner recovery after disconnects
• more confidence in real machine workflows

How it relates to nearby layers

Not the business twin

Mechagram does not define:

• organizations
• bases
• units
• anchors
• xenkeys

That is the world model.

Not the identity primitive itself

Identity comes from:

• Crew
• Mecha
• key issuance

Mechagram uses that identity in transport.

Not the knowledge layer

Knowledge grounding comes from:

• Anchor
• Xenkey
• MechaHub

Mechagram carries communication that may use grounded context, but it does not replace that context.

Not the discovery layer

MechaReg is about publication and discovery. Mechagram is about runtime communication after actors become reachable.

Relation to grounded knowledge

Mechagram becomes much more valuable when communicating Mechas operate inside a grounded business world.

That world includes:

• Anchor, which binds reality
• Xenkey, which binds meaning to that reality
• MechaHub, which retrieves that grounded meaning when needed

So the full picture is:

1. the business twin describes the world
2. Mechas act inside that world
3. MechaHub can supply grounded context
4. Mechagram carries communication between those actors

The right sentence is:

Mechagram carries traffic, but that traffic becomes much more useful when it is grounded in real business entities and real business meaning.

Without grounding, transport is only transport. With grounding, transport becomes operationally intelligent.

Relation to discovery and MCP

Mechagram should also be read next to MechaReg and MCP.

The clean distinction is:

• MechaReg helps external systems discover the right actor
• MCP helps machine clients understand discovery and callable surfaces
• Mechagram carries live runtime communication once the actor is known

So Mechagram is usually not the first contact surface. It is the operational communication surface after identity and discovery are in place.

Business effects

What it changes operationally

Mechagram changes the transport problem from:

• ad hoc integration
• copy-paste between tools
• weak agent reachability
• untracked runtime messaging

into:

• one delivery model
• one runtime path
• one acknowledgement pattern
• one machine-native communication line

Policy

Transport is not a toy layer

The docs should be explicit here:

Mechagram is valuable because it treats machine communication as real operational work.

That means it should be documented in a way that emphasizes:

• accountability
• traceability
• authenticity
• continuity

Not as a casual interaction surface.

Payment must not define communication existence

The platform should also avoid implying that only paid entities deserve real runtime communication.

Commercial layers may add:

• monetization
• prioritization
• packaging
• advanced service structure

But they should not be framed as deciding:

• whether a Mecha is a real actor
• whether communication exists
• whether valid business traffic counts

The correct framing is:

Mechagram is part of the core operational layer. Paid layers may change packaging or commercial leverage, but they do not create the basic fact that real business actors can communicate through the system.

Recommended next pages

• Continue with Mechagram Protocol.
• Continue with Authentication.
• Continue with Connect a Mecha Runtime.
• Continue with MechaReg.