Device actor ops

system.devices exposes a fixed set of ops. The full surface is declared in SystemDevicesActor.accepts at projects/matrix-3/packages/system/src/SystemDevicesActor.ts:67-76. This page enumerates each one with payload and return.

Op surface

// projects/matrix-3/packages/system/src/SystemDevicesActor.ts:67-76
static override accepts: Record<string, unknown> = {
  'devices.status':            { description: 'Report linked-device facade status' },
  'devices.register':          { description: 'Register a linked HiveCast compute participant in this namespace' },
  'devices.heartbeat':         { description: 'Refresh linked-device presence heartbeat' },
  'devices.deregister':        { description: 'Mark a linked device offline' },
  'devices.list':              { description: 'List linked devices for one principal/Space' },
  'devices.get':               { description: 'Get one linked device within the requested principal/Space scope' },
  'devices.runtimes.register': { description: 'Register a runtime under a linked device in the same principal scope' },
  'devices.runtimes.list':     { description: 'List runtimes for one linked device' },
};

devices.status

Lightweight readiness probe. Returns:

{
  ok: true;
  mount: string;          // typically 'system.devices'
  status: 'ready';
  count: number;          // number of in-memory device records
}

devices.register

Register or refresh a Device record (called primarily by host.control).

Payload:

Field	Type	Notes
deviceId or hostId	string	Required. Reads via readDeviceId(payload).
hostName	string	Mutable label.
deviceSlug	string	Stable projection key.
hostLinkId	string	Active link id.
principalId	string	Owner.
spaceId	string	Space.
authorityRoot	string	Bus authority root.
publicNamespace	string	Typed namespace claim.
routeKey	string	v1 alias.
linkStatus	'active' | 'revoked'	Mirror of cloud Host Link status.
heartbeatTtlMs	number	TTL hint. Default 45_000.
metadata	object	Free-form non-secret metadata.

Returns:

{
  ok: boolean;
  deviceId: string;
  created: boolean;       // true if this is the first time we saw deviceId
}

{ ok: false } when the previous record's identity scope disagrees with the new payload (see Ownership).

devices.heartbeat

Refresh lastHeartbeatAt on an existing record. Lighter than devices.register because it does not re-validate the full record.

Payload:

Field	Type	Notes
deviceId or hostId	string	Required.
principalId	string	Optional scope check.
heartbeatTtlMs	number	If present, updates the record's TTL.

Returns:

{
  ok: boolean;
  known: boolean;         // false if no record exists for deviceId
  deviceId: string;
}

devices.deregister

Mark a Device record offline. Payload identifies the Device by deviceId / hostId and optional scope. Returns { ok, known, deviceId }. Emits devices.offline { deviceId, reason: 'deregistered' }.

devices.list

List Devices, scoped.

Payload:

Field	Type	Notes
principalId	string	When set, also lists Host Link projections from auth.hostLink.list.
spaceId	string	Filter.
authorityRoot	string	Filter.
publicNamespace	string	Filter.
routeKey	string	Filter.
deviceId	string	Filter to a single Device.
includeOffline	boolean	Default false. When true, includes offline and revoked views.

Returns:

{
  ok: true;
  count: number;
  devices: IDeviceView[];
}

The list is sorted ascending by deviceId and run through compactDeviceViews() (see Device records).

devices.get

Get one Device within the requested scope.

Payload:

Field	Type	Notes
deviceId or hostId	string	Required.
principalId, spaceId, authorityRoot, publicNamespace, routeKey	string	Scope check.

Returns:

{
  ok: boolean;
  device: IDeviceView | null;
}

If the record is in memory and matches scope, returns it directly. If not in memory but a Host Link exists for the principal, returns a source: 'host-link' projection.

devices.runtimes.register

Register a runtime under a Device record.

Payload:

Field	Type	Notes
deviceId or hostId	string	Required.
runtimeId	string	Required.
principalId, spaceId, authorityRoot, publicNamespace, routeKey, hostLinkId	string	Scope check; must agree with the existing Device record.
runtimeWireRoot	string	Bus root.
runtimeMount, controlMount	string	Logical mounts.
packageRef, packageDir, environmentName, app	string	Package identity.
status	string	Default 'running'.
mountCount	number
localMounts	string[]
webapp	object
metadata	object

Returns:

{
  ok: boolean;
  deviceId: string;
  runtimeId: string;
  created: boolean;       // true if first time we saw this runtimeId for this device
}

{ ok: false } when the Device record does not exist or the scope check fails.

devices.runtimes.list

List runtimes for one Device.

Payload:

Field	Type	Notes
deviceId or hostId	string	Required.
principalId, spaceId, authorityRoot, publicNamespace, routeKey	string	Scope check.

Returns:

{
  ok: boolean;
  deviceId: string;
  count: number;
  runtimes: IDeviceRuntimeRecord[];   // sorted by runtimeId
}

Events emitted

Event	When
devices.added { deviceId }	First time a device record is created via devices.register.
devices.offline { deviceId, reason: 'timeout' }	_pruneStaleDevices() ages a record past its heartbeatTtlMs.
devices.offline { deviceId, reason: 'deregistered' }	devices.deregister succeeds.

host.control emits device.heartbeat and device.heartbeat.failed events on its own actor mount, NOT on system.devices.

See also

• Device schema — return shapes.
• Inventory / Heartbeats — usage patterns.
• Inventory / Ownership — scope check rules for register / heartbeat / deregister / runtimes.register.

Source: projects/matrix-3/packages/system/src/SystemDevicesActor.ts (accepts at lines 67-76; method bodies at lines 116-346).