HiveCast Platform

Appearance

Actor surfaces ​

This page enumerates the bus ops on the major platform actors. Every op is callable via:

bash
matrix invoke <mount> <op> '<json-payload>'

Or programmatically over the bus.

system.auth ​

The largest surface. Source: projects/matrix-3/packages/system-auth/src/index.ts:140-352.

Status / probe ​

  • auth.status — health probe.
  • auth.google.status — is Google OIDC configured?

Sessions ​

  • auth.session.validate — { token } → { claims }.
  • auth.session.create — internal: mint a session for a known principal.
  • auth.session.revoke — { headers } → { revoked }. Reads cookie from headers, revokes the underlying jti.
  • auth.cookie.clear — returns the Set-Cookie value to clear the session.
  • auth.identity.resolve — { headers, loopback? } → { identity: { principalId, authenticated, localClient, ... } }.

Principals ​

  • auth.principal.ensure — { issuer, subject, ... } upsert.
  • auth.principal.get — { principalId } → { principal }.
  • auth.principal.list — → { principals: [...] }.
  • auth.principal.authorityRoot — { principalId } → { root }.
  • auth.principal.setWorkspaceRealm — legacy.

Credentials ​

  • auth.credential.list — credential metadata (no secret values).
  • auth.nats.account.ensure — ensure principal has a NATS account.

Namespaces ​

  • auth.namespace.check — { routeKey | publicNamespace } → { available }.
  • auth.namespace.claim — claim a path.
  • auth.namespace.resolve — resolve a path to its Space.
  • auth.namespace.list — list claims for a principal.

Spaces ​

  • auth.space.create — { principalId, authorityRoot? } → { space }.
  • auth.space.default — read or set the default Space.
  • auth.space.get — fetch by spaceId.
  • auth.hostLink.create — { principalId, spaceId?, hostId?, scopes? } → { hostLink }.
  • auth.hostLink.get — { hostLinkId | hostId | principalId } → { hostLink }.
  • auth.hostLink.list — { principalId } → { hostLinks }.
  • auth.hostLink.revoke — flip status to revoked, revoke NATS user public keys.
  • auth.hostLink.refresh — refresh lastRefreshedAt.
  • auth.hostLink.credentials.refresh — issue fresh device-scoped NATS user JWT.
  • auth.hostLink.verifyHeartbeat — { token, ... } → { hostLink }. Constant-time HMAC compare.

Device-flow (CLI pairing) ​

  • auth.device.start, auth.device.status, auth.device.approve, auth.device.poll, auth.device.exchange, auth.device.cancel.

Pair-flow (browser pairing) ​

  • auth.pair.start, auth.pair.status, auth.pair.approve, auth.pair.exchange, auth.pair.cancel.

Google OIDC ​

  • auth.google.login — { redirect } → { url, state }.
  • auth.google.callback — { code, state } → { redirect, cookie, principal, session }.

system.devices ​

The account-facing Device facade. Implementation in projects/matrix-3/packages/system/.

  • devices.list — { principalId?, includeOffline?, includeRevoked? } → { devices }.
  • devices.get — { deviceId | deviceSlug } → { device }.
  • devices.heartbeat — internal, called by gateway.
  • devices.runtimes.list — { deviceId } → { runtimes }.
  • devices.runtimes.register — internal, called by host.control.

system.runtimes ​

Source: projects/matrix-3/packages/system-runtimes/src/RuntimeManagerActor.ts:156-171.

  • runtimes.list (alias runtimes.ps) — runtime inventory.
  • runtimes.status — runtime + deployment slice status.
  • runtimes.instances — declared and observed deployment instances.
  • runtimes.reconcile — reload installed package state.
  • runtimes.start / stop / reload / remove / restart — lifecycle on a mount.
  • runtimes.register — runtime self-registers.
  • runtimes.deregister — remove from registry.
  • runtimes.heartbeat — runtime liveness.
  • runtimes.registered — list registered runtimes in this namespace.

host.control ​

The Host Service control mount. Source: projects/matrix-3/packages/host-control/src/index.ts.

  • host.status — supervisor status.
  • host.restart — cycle every runtime.
  • runtimes.declare — write a runtime record.
  • runtimes.list — list local runtime records.
  • runtimes.get — one runtime record.
  • runtimes.start / stop / reload / restart — supervisor-managed lifecycle.
  • runtimes.remove — delete the record + stop.

system.registry ​

Logical mount registry. Source: projects/matrix-3/packages/system-platform/src/ServiceRegistryActor.ts.

  • registry.list — known mount claims.
  • registry.get — one claim.
  • registry.claim — runtime publishes a logical mount.
  • registry.release — runtime releases a mount.

system.factotum ​

Per CLAUDE.md Rule 4, the credential authority. Implementation in projects/matrix-3/packages/system-factotum/. Ops here are credential-store reads/writes only — never expose plaintext to other actors.

See also ​

  • Platform APIs — HTTP endpoints that wrap many of these ops.
  • Database ownership — which actor owns which store.
  • Devices / Pairing — flows using auth.device.* and auth.pair.*.
  • WORKSTREAMS/core-and-packaging/ACTOR-COMMUNICATION-CONTRACT.md — every op must declare description per Rule 3.

Source: projects/matrix-3/packages/system-auth/src/index.ts:140-352 for the full auth.* op declaration. system-runtimes/src/RuntimeManagerActor.ts:156-171 for runtime ops.