Package events

Package and runtime lifecycle events are emitted by system.runtimes (physical runtime inventory), host.control (per-Host supervision), and system.factotum (when a package's required credentials change).

This page enumerates them from the security perspective: which events are signal for "something changed in this principal's surface area."

Runtime events

system.runtimes (the RuntimeManagerActor) maintains the authoritative runtime inventory. Its events surface lifecycle transitions:

Event (typical name)	When
runtimes.registered { runtimeId, packageRef, ... }	A runtime was registered
runtimes.unregistered { runtimeId }	A runtime was unregistered
runtimes.health { runtimeId, status }	Health state changed

Exact event names depend on the implementation in projects/matrix-3/packages/system-runtimes/src/RuntimeManagerActor.ts. Subscribe to <authority-root>.system.runtimes.$events.> to see everything.

devices.runtimes.register events also flow through system.devices. The Devices facade re-keys runtimes under a Device record; emitting separate Device-runtime events from there is target state.

Package install / remove events

Today, package install is performed by host.control and mx-cli; the durable record lives in <host-home>/runtimes/<runtime-id>/runtime.json. Install/remove emits implementation-defined events on <authority-root>.host.control.$events.>.

Operationally:

• A new runtime.json file appearing under <host-home>/runtimes/ indicates a new runtime registered.
• A runtime.json.bak may indicate a self-heal of corrupt records (post bootstrap parse-and-skip).

The "this principal installed package X at time T" record is implicit in the runtime.json's registeredAt field plus the principal context of the local Host's Host Link.

Credential events affecting packages

When a package depends on a provider credential, system.factotum's events affect whether the package functions:

Event	Effect on packages
factotum.credential-stored { provider }	Inference catalog learns the provider is available; chat/director can now route to it
factotum.credential-deleted { provider }	Routes that depended on this provider start failing with factotum.needkey
factotum.credential-refreshed { provider, newExpiresAt }	Inflight calls succeed; no user impact
factotum.credential-expired { provider }	Routes start failing; UI prompts user to reconnect
factotum.needkey { provider, requestedBy }	Lease attempted with no credential; UI surfaces "add a credential for X"

These are the auth-relevant package events. They tell you which packages will start/stop working as credentials come and go.

What is NOT a package event today

Per-op invocation:

• A package actor receiving a $prompt envelope is NOT logged.
• A package actor's response is NOT logged.

Per-package authorization:

• "Is this principal allowed to invoke chat?" is not a per-op gate today. The op-name gating in static accepts is the only check.
• A target-state per-op capability check would emit <actor>.invocation.allowed / <actor>.invocation.denied events.

Subscribing

# All package-related events under this root:
nats sub "<authority-root>.system.runtimes.$events.>"
nats sub "<authority-root>.system.devices.$events.>"
nats sub "<authority-root>.host.control.$events.>"
nats sub "<authority-root>.system.factotum.$events.>"

Operator runbook

"Has this principal installed any new packages today?"

Today: inspect <host-home>/runtimes/ modification times across the principal's Hosts. Cross-reference with system.runtimes registry to see which packageRef each runtime serves.

"Is any runtime running under a revoked Host Link?"

Today: not directly answerable from events. Cross-reference auth.hostLink.list for revoked links with the Host's devices.runtimes.list. Revoked links cannot post heartbeats, so runtimes under them go stale; the cross-reference identifies them.

"Did the user remove a credential while a package was using it?"

Today: subscribe to factotum.credential-deleted events. The requestedBy field on factotum.needkey events that follow tells you which actor mount tried to use the (now missing) credential.

See also

• Device events — Device lifecycle events.
• Admin actions — what should be tracked.
• Security logs — overall log story.

Source: runtime events from projects/matrix-3/packages/system-runtimes/src/RuntimeManagerActor.ts; credential events from projects/matrix-3/packages/system-factotum/dist/index.jsstatic emits declaration.