Subject naming reference

A consolidated reference for naming inside Matrix subjects, mounts, ops, and URL paths. Each grammar is given as a regex where one applies.

Wire grammar

{root}.{mount}.$facet

Token	Allowed characters	Examples
{root}	regex ^[a-zA-Z0-9]([a-zA-Z0-9._-]*[a-zA-Z0-9])?$	COM.NIMBLETEC.RICHARD-SANTOMAURO, space.spc-9c3a417e
{mount}	dot-delimited identifiers, lowercase	chat.conversation, system.gateway.http
$facet	one of $inbox, $events, $exit, $reply	$inbox

The root regex is the only one enforced by code today (projects/matrix-3/packages/core/src/transport/NatsTransport.ts:108):

static readonly ROOT_PATTERN = /^[a-zA-Z0-9]([a-zA-Z0-9._-]*[a-zA-Z0-9])?$/;

Mount paths are checked at the application layer (e.g., system.registry).

Mount path conventions

• Lowercase dot-separated identifiers.
• Top-level token identifies the package family: system.*, chat.*, flowpad.*, host.*.
• Children share the parent prefix: chat.conversation, chat.identity.
• No spaces, no leading/trailing dots, no >/* (NATS wildcards).
• Hyphens allowed within a token: system.gateway-http is valid (though dots-and-camelCase is the more common style: system.gateway.http).

Op naming

<area>.<verb>             ← most ops, e.g. registry.resolve
<area>.<noun>.<verb>      ← nested namespaces, e.g. devices.runtimes.list
$<verb>                   ← system commands, e.g. $introspect
$<verb>.<modifier>        ← scoped system commands, e.g. $cognitive.set

Verbs follow REST-ish conventions:

Verb	Use
list	enumerate, with pagination if returning more than a few
get	fetch one record
register / unregister	claim / release
start / stop / cancel	lifecycle
add / remove	mutate a collection
claim / release	reservation semantics
resolve	lookup with provider info
search	filter with multiple criteria
heartbeat	keep-alive
validate	check without side effect
import / export	data transfer
refresh	renew a token / reload state

Event naming

<area>.<past-tense-verb>

Pattern	Examples
<area>.added / .removed	runtimes.added, runtimes.removed, devices.added
<area>.registered / .unregistered	registry.registered, service.deregistered
<area>.heartbeat	registry.heartbeat, devices.heartbeat
<area>.<noun>-changed	state.preferences-changed
<area>.<noun>.<verb>	factotum.credential-stored

Past tense for "this happened" events. Imperative is reserved for ops.

URL grammars

appName    /^[a-z0-9][a-z0-9-]*$/
spacePath  /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$/
routeKey   v1 compatibility alias for spacePath (same shape)

Source: WORKSTREAMS/core-and-packaging/MATRIX-DISCOVERY-METADATA-SPEC.md § "Universal Vocabulary".

Examples:

Type	Valid	Invalid
appName	chat, flowpad, inference-settings	Chat, chat_v2, chat.app, 1chat
spacePath	acme.support, alt.stories.ghost-stories.funny	ACME.support, acme..support, acme.

Forbidden in URLs

• The internal mount path (chat.conversation) is NOT a URL segment.
• The wire root (COM.NIMBLETEC.RICHARD-SANTOMAURO) is NOT a URL segment.
• appName segments are user-typed handles; mount paths are internal.
• publicNamespace (space.<spacePath>) is internal — never appears in URLs.

URL shape is /<spacePath>/<appName>/... (or /apps/<appName>/... on local Hosts without a Space). The internal mount appears nowhere.

Reserved facet names

Facet	Direction	Use
$inbox	inbound	actor receives ops here
$events	outbound	pub/sub events
$reply.<cid>	actor → caller	request/reply correlation
$exit	child → parent	lifecycle exit signal
$state	actor → watchers	KV last-value updates (handled by JetStream)
$stream.<name>	actor → consumers	durable stream (target shape)
$blackboard.<fact>	shared	marketplace facts (target)

See Reserved subjects for the full table.

Field name conventions

Inside payloads, JSON field names use camelCase:

{
  "logicalMount": "chat.conversation",
  "providerRuntimeId": "rt-chat-dev-01",
  "heartbeatTtlMs": 30000
}

Snake_case (heartbeat_ttl_ms) is not used.

See also

• Subjects — wire-format intro.
• Subject grammar — formal rules.
• Authority roots — root forms.
• Reserved subjects — full facet list.
• MATRIX-DISCOVERY-METADATA-SPEC.md — appName / spacePath.