Runtime wire roots

A runtime wire root is the wire prefix used by one specific runtime when it lives in a sub-scope of the host wire root. It is the way Matrix supports workspace and project sub-namespaces without spinning up a separate Host.

When you need a sub-scope

Most runtimes share the host wire root directly. For these, the host wire root is also the runtime wire root, and there is nothing to configure.

A sub-scope is useful when:

A development workspace wants its own namespace under the user's account root (COM.NIMBLETEC.RICHARD-SANTOMAURO.projects.gateway-refactor).
A test runtime wants isolation under a CI host root (COM.TEST.LOCAL-DEV.run-12345).
A HiveCast worker container wants a sub-namespace under the platform root (AI.HIVECAST.HOST.silo-7).

In each case, the runtime keeps the host wire root as its parent and adds a scope token under it.

Configuration

The runtime wire root is built from two environment fields:

json

{
  "runtime": {
    "root": "COM.NIMBLETEC.RICHARD-SANTOMAURO",
    "scope": "projects.gateway-refactor",
    "cascade": true,
    "runtimeId": "gateway-refactor-dev"
  }
}

Resulting wire prefix:

COM.NIMBLETEC.RICHARD-SANTOMAURO.projects.gateway-refactor

Scoped actors publish/subscribe under this combined prefix:

COM.NIMBLETEC.RICHARD-SANTOMAURO.projects.gateway-refactor.system.gateway.http.$inbox

Source: projects/matrix-3/packages/docs/content/architecture/bus-addressing.md § "Scoped Addressing".

Cascade

When runtime.cascade = true, the transport additionally subscribes to the parent root for any binding the scoped runtime does not provide. This makes inherited services discoverable:

runtime.root    = COM.NIMBLETEC.RICHARD-SANTOMAURO
runtime.scope   = projects.gateway-refactor
runtime.cascade = true

scoped subject:    COM.NIMBLETEC.RICHARD-SANTOMAURO.projects.gateway-refactor.system.gateway.http.$inbox
inherited subject: COM.NIMBLETEC.RICHARD-SANTOMAURO.system.inference.$inbox  ← seen via cascade

Behavior with cascade enabled:

A request for system.inference resolves to the parent-root provider if the scoped runtime has none of its own.
A request for system.gateway.http goes to the scoped provider (the closer one wins).

Cascade is opt-in. The default is cascade: false, which gives the scoped runtime a strict-isolation namespace.

Status: target state for cascade resolution. The transport supports cross-root subjects through _buildSubjectForRoot (see NatsTransport.ts lines 559–594), but a fully automatic cascade resolver across system.registry is workstream material — see WORKSTREAMS/runtime-environment-multi-instance/. The current product codebase relies on explicit cross-root addressing (see Relative vs absolute addressing) rather than registry-driven cascade.

Runtime identity vs runtime wire root

These are different. Runtime identity (runtimeId) names the process. Runtime wire root names the namespace the process publishes to. Two processes can share a wire root (multi-provider mounts), and one process can have only one wire root.

Concept	Example	Stable across
`runtimeId`	`gateway-refactor-dev`	this process only
Runtime wire root	`COM.NIMBLETEC.RICHARD-SANTOMAURO.projects.gateway-refactor`	environment lifetime

system.runtimes records the runtimeId. system.registry records the wire root and local mount alongside the logical mount claim — see registry.register accepts runtimeWireRoot (the wire prefix) and localMount (the mount under that prefix).

What sub-scopes do NOT do

They do not change the authority root. The Space identity (and ownership) is governed by system.auth; sub-scopes inherit the same authority root.
They do not provide isolation between scopes if both connect to the same NATS server with the same credentials. NATS ACL is the actual isolation boundary.
They do not nest beyond two levels in current code. The cascade lookup stops at the parent root.

Runtime wire roots ​

When you need a sub-scope ​

Configuration ​

Cascade ​

Runtime identity vs runtime wire root ​

What sub-scopes do NOT do ​