Matrix Protocol

Appearance

Relative vs absolute addressing ​

A semantic topic can address an actor in the caller's own root (relative) or an actor in a different root (absolute / cross-root). The form differs: relative addresses use just the mount path, absolute addresses prefix the target root with a single slash separator.

Relative addressing ​

The default. The semantic topic names a mount inside the caller's transport root.

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

The transport's semanticToNats method prefixes its own root:

caller root: COM.NIMBLETEC.RICHARD-SANTOMAURO

chat/$events                   →  COM.NIMBLETEC.RICHARD-SANTOMAURO.chat.$events
chat.conversation/$inbox       →  COM.NIMBLETEC.RICHARD-SANTOMAURO.chat.conversation.$inbox
system.registry/$inbox         →  COM.NIMBLETEC.RICHARD-SANTOMAURO.system.registry.$inbox

This is the form used in 99% of intra-Host calls.

Absolute (cross-root) addressing ​

When the target lives under a different root, use the cross-root form: the target root, a slash, then the local-form mount and facet.

AI.HIVECAST.HOST/system.gateway.http/$inbox
COM.GMAIL.JANE-DOE/chat.conversation/$inbox

The transport's semanticToNats recognizes this case (lines 281–289):

typescript
const firstSlash = topic.indexOf('/');
if (firstSlash > 0) {
  const afterSlash = topic.slice(firstSlash + 1);
  if (!afterSlash.startsWith('$') && !afterSlash.startsWith('#')) {
    const targetRoot = topic.slice(0, firstSlash);
    const localTopic = afterSlash;
    return this._buildSubjectForRoot(targetRoot, localTopic);
  }
}

The disambiguation rule: if the first slash is followed by $ (a facet) or # (a wildcard), this is a relative address with a facet/wildcard. If the slash is followed by anything else, it's a cross-root address.

chat/$inbox             ← relative; first slash precedes a facet
chat/#                  ← relative; first slash precedes a wildcard
JANE-DOE/chat/$inbox    ← absolute; first slash precedes a non-facet word

Resulting wire form:

caller root: COM.NIMBLETEC.RICHARD-SANTOMAURO

AI.HIVECAST.HOST/system.gateway.http/$inbox
  → AI.HIVECAST.HOST.system.gateway.http.$inbox       (NOT prefixed with caller root!)

Why the cross-root form exists ​

NATS routes by subject, not by connection. When the transport publishes AI.HIVECAST.HOST.system.gateway.http.$inbox, NATS delivers to whichever connection has subscribed to that subject — possibly a leaf-node connected HiveCast Host, possibly a federation peer, possibly a local supervisor.

Federation across providers is built on this: a HiveCast Host's leaf connection propagates subscription interest for AI.HIVECAST.HOST.> to the hub, so any leaf publishing to a AI.HIVECAST.HOST.* subject reaches the right destination without extra routing logic on the caller's side.

ACL implications ​

Cross-root publishes succeed only if the caller's NATS account is permitted to publish there. The standard tier model:

TierCross-root publish allowed?
Free (subject-prefix isolation)denied — caller is restricted to its own root
Pro (subject-prefix + vault)denied — same as free
Enterprise (dedicated NATS account)allowed only via account imports/exports
Self-hosted with leaf to HiveCastallowed for cross-root federation subjects

For most product flows, cross-root calls go through system.gateway.http on the platform side, which acts as the trusted bridge. Direct cross-root publishes from a tenant Host are not the default.

Reply subjects under cross-root calls ​

When an actor at COM.NIMBLETEC.RICHARD-SANTOMAURO calls AI.HIVECAST.HOST/system.gateway.http/$inbox, the reply subject is in the caller's root, not the target's:

request:  AI.HIVECAST.HOST.system.gateway.http.$inbox
reply:    COM.NIMBLETEC.RICHARD-SANTOMAURO.$reply.<cid>

The replyTo envelope field carries the absolute form so the target knows which subject to publish back to. The target's transport sees the absolute subject and publishes there directly (its NATS account must be allowed to publish into the caller's reply namespace, or the request goes through _INBOX.* / _R_.* — see Request envelope).

Same address, different presentation ​

The matrix:// URL form is always absolute by intention:

matrix://richard-santomauro@nimbletec.com/chat

This resolves to the absolute subject form COM.NIMBLETEC.RICHARD-SANTOMAURO/chat/$inbox. The URL is the user-facing shape; the cross-root semantic topic is the internal shape; the dot-separated wire prefix is what NATS actually sees.

See also ​