Matrix Protocol

Appearance

Singleton claims ​

A singleton claim is a mount that may have exactly one live provider per authority root. The system control plane is built on these — having two of system.registry running under the same root is silent corruption.

The singleton list ​

Source: WORKSTREAMS/core-and-packaging/MATRIX-AUTHORITY-MODEL.md § Rules. Quoted: "Singleton authority mounts have one live owner per authority root. system.runtimes, system.registry, system.devices, system.auth, host.control. Two matrix up calls for the same singleton on one Host = silent claim collision (see AGENTS.md § Worker Bootstrap Gotchas)."

MountAuthority
system.runtimesphysical runtime/process inventory
system.registrylogical mount claims
system.deviceslinked-Device inventory
system.authnamespace claims, host-link redemption
host.controlhost-local supervisor

Why these are singletons ​

Each owns canonical state for one authority root:

  • system.registry is the single source of truth for "who serves what". Two registries means two answers to the same question.
  • system.runtimes is the single inventory of running processes. Two inventories means two slightly-different lists.
  • system.devices is the single linked-Device facade for one principal/Space. Two of them means two presence histories.
  • system.auth is the namespace authority. Two of them means two conflicting namespace claims.
  • host.control is the per-Host supervisor. Two of them means two competing reconcilers.

Multiple readers are fine and expected — that's what registry.resolve and runtimes.list are for. Multiple writers for the same authority root corrupt the picture.

How collisions manifest today ​

system.registry does NOT actively reject a second registry.register for a singleton. Both registrations are accepted; the second silently shadows the first in resolve order. The catalog reflects whichever the registry returns first.

The collision signature in practice:

  • Two host-control runtimes spawn (a stale one didn't tear down on hivecast stop).
  • Both register themselves with system.registry under the same authority root.
  • host.status returns the second one's view; the first's reconciler still runs in the background, fighting over runtimes.
  • Symptoms: random restarts, mounts that "go away and come back" without obvious cause, devices flicking between online and offline.

The fix is not in the registry — it's at the supervisor layer. Host Service is supposed to ensure exactly one of each singleton per Host. When it fails (process leak, leaked PID file), the result is the silent-collision class of bug.

Detection ​

Today, the only reliable way to detect a singleton collision is to inspect registry.providers { logicalMount: 'system.registry' } and check for more than one provider:

bash
matrix invoke system.registry registry.providers '{"logicalMount":"system.registry"}'

If providers.length > 1, there's a collision.

hivecast doctor does some of this for the system mounts but does not catch every case. Targeted detection is on the workstream/typecheck-clean and supervision workstream backlogs.

Status: target state. A first-class singleton-collision detector at the registry level (rejecting the second registration for a singleton mount) is filed but not yet implemented. Today, ops policy + supervisor discipline carry the load.

What singleton does NOT mean ​

  • It does not mean "one per Host". It means "one per authority root". A HiveCast platform Host can host many tenant Spaces, each with its own set of singletons. The cross-tenant boundary is enforced by NATS account ACL and by the authority-root tagging on every claim.
  • It does not mean "globally unique". Cross-root singletons are isolated. system.registry under COM.NIMBLETEC.RICHARD-SANTOMAURO and system.registry under AI.HIVECAST.HOST are entirely separate actors.
  • It does not mean replication is impossible. Future product modes may load-balance singleton ops across processes, but only when the actor contract explicitly supports that mode (today: none do).

CLAUDE.md restatement ​

The repo-level CLAUDE.md echoes this rule:

"Singleton system mounts (system.runtimes, system.registry, system.devices, system.auth, host.control) must have one live owner per authority root. Multiple processes may provide load-balanced product services later only when the actor contract explicitly supports that mode. Do not let two actors claim the same singleton subjects by accident."

Worker-cell implications ​

For Docker-based dev containers (the worker-cells topology), each cell is a separate Host with its own authority root if you intend to run a singleton there. Two cells sharing one authority root and both running system.registry is a collision; they need separate roots.

The two-runtime dev topology (matrix-web + matrix-edge in one Host) is NOT a singleton collision because both runtimes share one Host — they both connect to the same system.registry, neither runs its own.

See also ​