Device schema

This page is the on-the-wire reference. It is generated by reading SystemDevicesActor.ts and listing every field of every record. The overview pages explain why each field exists; this page just enumerates the contract.

IDeviceRecord (in-memory storage)

Source: projects/matrix-3/packages/system/src/SystemDevicesActor.ts:27-46.

Field	Type	Required	Notes
deviceId	string	yes	== hostId. Stable Device identity for the lifetime of the link.
hostName	string	no	Mutable human label. NOT displayName.
deviceSlug	string	no	Stable address-safe management projection key.
hostLinkId	string	no	Active Host Link id; hostlink_<24 hex>.
principalId	string	no	Owner; p_<sha20>.
spaceId	string	no	Space; spc_<hex>.
linkStatus	'active' | 'revoked'	no	Mirror of cloud Host Link status.
authorityRoot	string	no	Bus / security / runtime root.
publicNamespace	string	no	Typed namespace claim, e.g. space.alt.stories.
routeKey	string	no	v1 alias for spacePath.
status	'online' | 'offline'	yes	Presence status only.
source	'presence'	yes	In-memory storage source is always 'presence'.
registeredAt	number (ms)	yes	First registration time.
updatedAt	number (ms)	yes	Last mutation time.
lastHeartbeatAt	number (ms)	yes	Last successful heartbeat time.
heartbeatTtlMs	number	yes	TTL after which presence ages to offline. Default 45_000.
metadata	Record<string, unknown>	yes	Free-form non-secret metadata, e.g. { source: 'host-control', reason, cloudUrl?, deviceRegistryRoot? }.
runtimes	Map<string, IDeviceRuntimeRecord>	yes	Keyed by runtimeId.

IDeviceView (wire return shape)

Source: projects/matrix-3/packages/system/src/SystemDevicesActor.ts:48-53.

IDeviceView extends IDeviceRecord minus runtimes / status / source, with these widened fields:

Field	Type	Notes
source	'presence' | 'host-link' | 'merged'	See Device records.
status	'online' | 'offline' | 'linked' | 'revoked'	Computed from presence and Host Link status.
runtimeCount	number	Length of the flattened runtimes array.
runtimes	IDeviceRuntimeRecord[]	Flattened, sorted by runtimeId.

All other IDeviceRecord fields are passed through unchanged.

IDeviceRuntimeRecord

Source: projects/matrix-3/packages/system/src/SystemDevicesActor.ts:9-25.

Field	Type	Required	Notes
runtimeId	string	yes	Unique runtime id within this Host.
runtimeWireRoot	string	no	Bus authority root the runtime publishes under. Used by host.control to filter advertised runtimes.
runtimeMount	string	no	Logical mount of the runtime's root actor.
controlMount	string	no	Logical mount of the runtime's control actor.
packageRef	string	no	Package identifier, e.g. @open-matrix/chat.
packageDir	string	no	Local source path; useful for dev.
environmentName	string	no	'dev', 'hivecast', etc.
app	string	no	App name for browser packages.
status	string	yes	'running', 'starting', 'stopped', 'unknown', etc.
mountCount	number	no	Count of logical mounts the runtime publishes.
localMounts	readonly string[]	no	Sorted list of local mount paths.
webapp	Record<string, unknown>	no	{ routePrefix, displayName, icon, navOrder, ... } for browser packages.
registeredAt	number (ms)	yes	First registration time.
updatedAt	number (ms)	yes	Last mutation time.
metadata	Record<string, unknown>	yes	Free-form non-secret metadata.

Source enum

Where the source value comes from in IDeviceView:

presence    -- only the in-memory _devices map has this device
              (no Host Link found for the principal scope)
host-link   -- only auth.hostLink.list has this device
              (durable record exists; no live presence)
merged      -- both, AND deviceCanMergeWithHostLink() returned true

Status enum

online   -- presence record, last heartbeat within heartbeatTtlMs
offline  -- presence record, last heartbeat older than heartbeatTtlMs
linked   -- Host Link 'active' but no live presence
revoked  -- Host Link 'revoked' (regardless of presence)

compactDeviceViews() may demote a presence-online view to revoked when the Host Link merge produces revoked.

Identifiers — by-name regex/format quick reference

Identifier	Format	Source
installId	install_<20 hex chars>	randomBytes(10).toString('hex')
hostId	host_<20 hex chars>	generateHostId()
hostLinkId	hostlink_<24 hex chars>	generateHostLinkId()
principalId	p_<20 hex chars>	stablePrincipalId(issuer, subject) (sha256 hash slice)
spaceId	space_<20 hex chars>	generateSpaceId() (randomBytes(10).toString('hex'))
deviceSlug	kebab-lowercase, ≤64 chars	deviceSlugFromLabel() then allocateDeviceSlug()
userCode	XXXX-XXXX (32-char alphabet, no I/O/0/1)	generateDeviceUserCode()
deviceCode	base64url, 32 random bytes	generateDeviceCode()
hostLinkToken	hlink_<base64url 32 bytes>	generateHostLinkHeartbeatToken()
authorityRoot	space.<spaceId> for new Spaces	per Authority Model

See also

• Host link schema — paired schema cloud-side.
• Device actor ops — what produces and consumes these shapes.
• Inventory / Device records — narrative view of these fields.

Source: projects/matrix-3/packages/system/src/SystemDevicesActor.ts.