Host wire roots

A host wire root is the NATS subject prefix that all actors on a single Host share. It is the {root} token in the wire grammar. Host wire root is transport-level, not application-level — it is owned by the environment configuration, not by any package.

Source: four-operational-units doc in projects/matrix-3/packages/docs/content/architecture/four-operational-units.md § "Environment". Quoted: "An environment does NOT own package code. It does not own package identity. It does not own actor declarations." Conversely, the environment does own the wire root.

What it is

When you start a Host, the environment config gives the runtime a single top-level wire root. Examples seen in the running system today:

COM.NIMBLETEC.RICHARD-SANTOMAURO
COM.GMAIL.RICHARDMATHEWSANTOMAURO
AI.HIVECAST.HOST
COM.OPEN-MATRIX.LOCAL.DIRECTOR
COM.TEST.LOCAL-DEV

Every subject the Host's transport publishes or subscribes to is prefixed with this root. The transport rejects publishes that would land outside it — the wire-format ACL boundary that prevents one Host from accidentally addressing another Host's namespace.

Where it comes from

The host wire root is configured in the environment file at <package>/.matrix/<env>.environment.json:

{
  "name": "dev",
  "runtime": {
    "root": "COM.OPEN-MATRIX.LOCAL.DIRECTOR",
    "runtimeId": "director-dev"
  }
}

The runner reads this file, constructs a NatsTransport with the root option, and the constructor validates the format:

// 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])?$/;

// NatsTransport.ts:117
const root = options.root ?? options.realm;
if (!root || root.trim().length === 0) {
  throw new Error('NatsTransport: root (or realm) is required');
}
if (!NatsTransport.ROOT_PATTERN.test(root)) {
  throw new Error(`NatsTransport: invalid root "${root}". ...`);
}

Note: realm is a deprecated alias for root. New code uses root; the realm getter and INatsTransportOptions.realm field exist only for back-compat and emit no runtime warnings.

Host wire root vs authority root

These are different concepts that often coincide but are independent:

Concept	Where defined	What it controls
Host wire root	environment file runtime.root	NATS subject prefix at the transport level
Authority root	system.auth Space record / account	who owns mounts, singleton ownership, ACL

For the common case of a single-tenant local Host, both are the same value (COM.NIMBLETEC.RICHARD-SANTOMAURO). For HiveCast-hosted multi-tenant silos, multiple authority roots can share one host wire root prefix, with NATS account isolation enforcing the per-tenant boundary inside.

The four-operational-units source explicitly separates them:

"Wire prefix is determined by the environment config (runtime.root + optional runtime.scope). It is transport-level, not application-level."

Conventions

Pattern	Meaning
COM.<DOMAIN>.<USERNAME>	user-rooted account, derived from email
COM.<DOMAIN> (or <TLD>.<DOMAIN>)	organization-rooted Host
AI.HIVECAST.HOST	platform-owned Host (HiveCast)
COM.OPEN-MATRIX.LOCAL.<NAME>	local development Host
COM.TEST.LOCAL-<NAME>	test/CI Host
space.<spaceId> (lowercase)	new-format Space-rooted Host

The legacy uppercase form survives because it is what every running production deployment uses today. New Space roots use the lowercase space.<spaceId> form per the Gate 2.2 decision documented on Authority roots.

Inspecting the live root

A live Host exposes its wire root through several surfaces:

• host.control exports host.status which includes the configured root.
• The transport object's .root getter returns the value (NatsTransport.ts line 156).
• Actors running on the Host can read it from MatrixContext services (config.runtime.root).

Changing the host wire root

You don't. Once a Host is running with a given root, all its persisted state (JetStream KV, runtime records, link records) is keyed under that root. Changing the root requires a fresh install or a guided migration.

The expected path is: install with the desired root, run with that root, back up, decommission. There is no in-place rename.

Cascade

A Host MAY run runtimes inside a sub-scope. The runtime wire root is then {host-root}.{scope}. See Runtime wire roots for the cascade rules.

See also

• Subject grammar — where {root} fits in the wire form.
• Authority roots — the security/ownership concept, distinct from host wire root.
• Runtime wire roots — per-runtime scoping.
• Four operational units — environment vs package vs runner vs host.