@open-matrix/host-control (1.1.33)
Installation
@open-matrix:registry=npm install @open-matrix/host-control@1.1.33"@open-matrix/host-control": "1.1.33"About this package
@open-matrix/host-control
Host control for one HiveDock: hivedock.control, the actor every surface uses
to ask a running HiveDock for status, runtime lifecycle, configuration reload
and shutdown. The HiveDock supervisor (@matrix/runtime-host-engine) starts and
restarts the processes; this package keeps the bus protocol out of HTTP gateway
code. What a machine is, end to end, is in
docs/platform/machines.md.
Runtime details
runtime.describe { runtimeId } returns { ok, runtime } from the owning
supervisor. The runtime includes its name, package name and version, machine,
state, start time, restart count, last exit (code, signal, time and reason),
declared configuration, dependencies.requires, dependencies.requiredBy, and
protected. Dependencies come from the resolved deployment and loaded package
manifests. Manifest-declared secrets and conservative secret-shaped values are
withheld on both composition and compatibility paths. If package metadata is
unavailable, configuration values are withheld.
The supervisor refuses runtime.remove for a protected runtime even with
force: true. Protection is declared by source load lists or canonical
compositions for the platform foundation and its user-host counterparts;
runtime registration cannot change that policy. The operation is advertised by $introspect and the package
manifest and travels over the existing supervisor inbox/control socket.
Named runtime registration
runtime.register keeps three identities separate:
selectionchooses one immutable install record by package name, version and digest. It never selects alocal-pathrecord.sourceregisters one explicit workspace occurrence. It requires the exact HiveDock name, installation source, composition revision, absolute workspace path, manifest name/version, export, instance key/mount and configuration. The workspace remains source-followed; it is not reported as an immutable install and receives no invented artifact digest.recordis the legacy supervised-runtime shape. Itsconfigremains private runtime bootstrap data rather than installation settings.
A source occurrence is a canonical composition mutation. Host Control sends it
only through the configured-registration supervisor operation, so the existing
composition compare-and-swap and manifest configuration validation still own
the commit. The public receipt repeats the source and target identities but
never configuration values. Registration stages the occurrence; a separate
runtime.start for the returned instance key commits and activates that key.
{
"source": {
"targetHivedock": "selected-dock",
"targetSource": { "authorityRoot": "selected-home", "mount": "installations.selected-dock" },
"expectedCompositionRevision": 7,
"package": {
"workspacePath": "/absolute/workspace/package",
"name": "@example/worker",
"version": "1.0.0"
},
"export": "createStandaloneWorker",
"instance": { "key": "worker-two", "mount": "workers.two" },
"configuration": {}
}
}
Health history and host summary
runtime.stats { runtimeId? } returns the latest supervisor measurements.
runtime.stats.history { runtimeId, window } reads samples from the last window
milliseconds; runtime.events { runtimeId?, since } reads lifecycle transitions
since an ISO timestamp. Histories are bounded and held by the supervising process.
host.describe {} provides machine resources, HiveDock version, uptime, runtime
counts by state, and environments[] lifecycle/storage accounting. Each environment
reports name, state, stoppedAt, stoppedAtSource, imageBytes,
sharedImageBytes, volumeBytes, checkoutBytes, totalBytes,
reclaimableBytes, hold, and servesThisScreen; environmentInventoryError
explains why that inventory is absent instead of presenting missing Docker data as
zero. host.stats.history { window } returns five-second CPU, memory,
disk and network samples, bounded to 720 samples (one hour). All operations are
described by $introspect.
Host Control imports only alerts.evaluate on the observability health actor.
Failed evaluations emit a warning on the actor log stream and retry on the next
15-second pass; they are never silently treated as delivered.
runtime.logs { target, lines? } resolves a runtime by key, package, display name, or declared actor
mount and returns bounded, credential-redacted stdout and stderr from the owning supervisor. It is
the operation used by both matrix invoke and the Machines log panel.
Implementation boundaries
HostControlActor owns actor dispatch and the public operation descriptions.
Its collaborators own runtime lifecycle (RuntimeLifecycleOperations), runtime
logs, statistics and history (RuntimeObservabilityOperations), package changes
(PackageOperations), installed application projection
(ApplicationDirectoryProjection), and host status (HostStatusOperations).
HostTopologyClaims owns Registry claim renewal and lifecycle publication.
They use typed ports to reach the existing supervisor and actor context.
Operation names, payloads and responses remain on the same host-control surface.
Host operation audit
Runtime start, stop, restart and remove operations write one credential-redacted JSONL record to
<home>/audit/host-operations.jsonl; deployment starts and claim-loss stand-downs cross the same
boundary. The active file rotates before it would exceed 16 MiB. HiveDock retains the newest 15
rotations plus the active file (at most approximately 256 MiB), and reads across all retained files
newest-first. Older host-local rotations permanently expire: they are deleted and are not moved to
an archive. The central system.audit ledger has separate archive and chain-retention rules.
Audit strings use the shared CredentialShapes redactor and bounded field sizes before persistence.
The legacy _auditActor and _auditSession inputs remain caller-asserted labels, not authenticated
principals. Host audit I/O is best-effort and cannot replace or discard an already completed
supervisor result.
Activation containment (issue #621)
runtime.register followed by runtime.start for one staged runtime adopts only that key and the keys already staged in the pending plan. An unrelated alive runtime whose package bytes drifted since its launch (a build in a shared workbench rewrote its dist) is not replaced by that start: the engine emits deployment.package.replacement-deferred and lists the key under deferred in the start response. Whole-deployment operations (hivedock up, host.reconcile, targeted package.up) keep owning drift and still replace such runtimes. Receipts and the regression: host-activation-containment (docs/delivery/run-logs/issue-621/host-activation-containment.md, removed in fae11e283).
Device heartbeat scheduling and topology-claim expiry share the device-authorization contract: 15-second heartbeat intervals, with a three-interval (45-second) lease. The scheduler regression measures three interval firings with a controlled clock. Each heartbeat includes the local HiveDock identity in its authenticated payload. System auth joins it to the account device, and managed topology claims use that account device ID while retaining the HiveDock ID as their local runtime coordinate.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @open-matrix/contracts | 1.1.33 |
| @open-matrix/core | 1.1.33 |
| @open-matrix/package-runtime | 1.1.33 |
| @open-matrix/sqlite-store | 1.1.33 |
Development Dependencies
| ID | Version |
|---|---|
| @matrix/test-utils | 1.1.33 |
| @open-matrix/contracts | 1.1.33 |
| @open-matrix/core | 1.1.33 |
| @open-matrix/hivedock-supervisor-client | 1.1.33 |
| @open-matrix/nats-auth | 1.1.33 |
| @open-matrix/runtime-launcher3 | 1.1.33 |
| @types/node | ^20.0.0 |
| esbuild | ^0.25.0 |
| nats | ^2.29.3 |
| tsx | ^4.0.0 |
| typescript | ^5.3.0 |