Matrix Protocol

Appearance

Subjects ​

A subject is a dot-delimited name on NATS. In Matrix, subjects are how actors find each other, how requests reach inboxes, how replies come back, how events fan out, and how state records are watched.

The wire grammar is fixed. From CLAUDE.md Rule 11:

{root}.{mount}.$facet
ComponentMeaning
{root}The authority root — environment-level NATS namespace, e.g. COM.NIMBLETEC.RICHARD-SANTOMAURO
{mount}The dot-delimited logical mount path of an actor, e.g. system.llm or chat.conversation
$facetOne of $inbox, $events, $exit, $reply, or a generic facet

The standard facets ​

Source: projects/matrix-3/packages/core/src/transport/NatsTransport.ts lines 257–413 (semanticToNats / natsToSemantic).

FacetDirectionUse
$inboxclient → actorSend an op to an actor (request/reply or fire-and-forget)
$eventsactor → worldPub/sub events; subscribers fan out
$reply.{cid}actor → callerResponse to a correlated request
$exitchild → parentLifecycle exit signal for supervision
$stateactor → watchersLast-value KV updates (see Reference / Reserved subjects)

Examples (root = COM.NIMBLETEC.RICHARD-SANTOMAURO):

COM.NIMBLETEC.RICHARD-SANTOMAURO.system.llm.$inbox        ← send an op
COM.NIMBLETEC.RICHARD-SANTOMAURO.chat.$events             ← subscribe to chat events
COM.NIMBLETEC.RICHARD-SANTOMAURO.$reply.f12d-7af0         ← caller's reply subject
COM.NIMBLETEC.RICHARD-SANTOMAURO.chat.conversation.$inbox ← send to nested mount

The semantic vs wire distinction ​

Code outside the transport works with semantic topics (slash-separated):

system.llm/$inbox
chat/$events
chat.conversation/$inbox
$replies.f12d-7af0

The NatsTransport translates between semantic and wire forms via semanticToNats() and natsToSemantic(). The translation rules (verbatim from source):

system.llm/$inbox  →  com.example.system.llm.$inbox
$replies.abc-123   →  com.example.$reply.abc-123
system.llm/#       →  com.example.system.llm.>
#                  →  com.example.>
generic.topic      →  com.example.generic.topic

A mount uses dots internally (chat.conversation); the slash separates the mount from the facet (/$inbox, /$events). The wire form prefixes the root and replaces the slash with a dot (com.example.chat.conversation.$inbox).

Note: the slash is purely a semantic-layer notation. On the wire, NATS sees only dots. Wildcards likewise translate: # (semantic) becomes > (NATS), and + becomes *.

Cross-root addressing ​

A semantic topic with a leading <root>/<mount> form addresses another root without changing the local transport's root:

AI.HIVECAST.HOST/system.gateway.http/$inbox

The transport's _buildSubjectForRoot joins the target root tokens with the local-form mount and facet. This is how a browser at COM.NIMBLETEC.RICHARD-SANTOMAURO calls an actor at AI.HIVECAST.HOST without re-rooting its connection. See Relative vs absolute addressing.

Wildcards ​

NATS supports two wildcards. Matrix exposes them through their semantic forms:

SemanticNATSMatches
+*exactly one token
#>one or more tokens (rest of the subject)

Example: subscribing to all events under any chat conversation:

chat.conversation/+/$events    ← per-conversation events
chat/#                         ← everything under chat

Reply subjects ​

Request/reply correlation uses a per-request reply subject:

{root}.$reply.{correlationId}

The caller subscribes once on this subject before publishing the request to the target's $inbox. The actor publishes its response there, then the caller unsubscribes. Correlation IDs are short opaque tokens (see Correlation IDs).

The transport accepts an already-rooted reply subject directly:

typescript
// NatsTransport.semanticToNats — Source lines 273-275
if (topic.startsWith(this._rootPrefix) && topic.includes('.$reply.')) {
  return this._withPrefix(topic);
}

so that NATS-protocol native reply subjects (_INBOX.*) and our {root}.$reply.{cid} form interoperate without double-prefixing.

What is NOT a Matrix subject ​

  • The NATS _INBOX.* and _R_.* patterns are NATS protocol internals; they appear as replyTo metadata on incoming messages but do not follow the {root}.{mount}.$facet rule.
  • The system account $SYS.* subjects are NATS server internals.
  • Anything published outside the actor's authority root is a claim collision, not a valid Matrix subject — see Topic claims.

See also ​