HiveCast Platform

Appearance

Package versions ​

A package version today is whatever dist/ content the HiveCast wrapper bundled at release time. There is no registry pull, no per-Device version selection, no signed manifest. This page documents what works, what is target, and the operator workarounds.

Today: bundled-with-wrapper ​

hivecast install lays out <host-home>/.matrix/packages/<package-name>/ from the wrapper's bundled dist/node_modules/. So:

  • A Host's package versions are determined by which wrapper version is installed.
  • Upgrading a package = upgrading the wrapper.
  • Downgrading = downgrading the wrapper.
  • Different versions on different Hosts = different wrapper versions installed on different Hosts.

The wrapper version is visible:

bash
hivecast --version
# Returns the wrapper's package version, e.g. 0.1.24

The bundled package versions are visible by inspecting <host-home>/.matrix/packages/<name>/package.json.

Why this works for now ​

The launch model is: apt install hivecast (on a Device) and the user gets a coherent set of package versions known to work together. This is good enough for the first launch — every Device runs the same package set, no version drift, no compatibility matrix.

It does not scale to:

  • Different users running different Director versions.
  • Pinning a security-critical package to a specific patch version.
  • Staging a new package version on one Device before fleet-wide rollout.

Target: registry-pull ​

Per WORKSTREAMS/docker-npm-parity/ and ARCHITECTURE-PLATFORM-TOPOLOGY.md §8 (Package Pipeline), the target model is:

  • Packages publish to a Gitea-as-npm-registry.
  • Devices configure one or more registries.
  • Runtime records carry a version field.
  • A reconciler pulls the configured version into the package store.
  • Profile changes (see Deployment profiles) drive version transitions.

The plumbing for "Gitea behaves like an npm registry" exists in the architecture; the wire-up to runtime records does not.

Version field on runtime records ​

The runtime record schema accepts a version field, but the supervisor today ignores it (uses the bundled version unconditionally). The field exists as forward-compat for the registry-pull model. Setting it does no harm and lets profile authors record intent.

Working with multiple wrapper versions ​

If you need to run different package versions on different Hosts in the same fleet:

  • Install matched wrapper versions per Host (apt install hivecast=0.1.24 vs 0.1.25).
  • Pin per-Host with apt-mark hold hivecast.
  • Track which version each Host runs in your inventory tool (the platform doesn't track this for you yet).

This is operational pain. The registry-pull target eliminates it.

Building and shipping a new version ​

Operators publishing a new package version today:

  1. Edit the package source under projects/matrix-3/packages/<name>/.
  2. Bump version in package.json.
  3. Build (pnpm build:affected or node build.mjs per-package).
  4. Cut a new wrapper release (the wrapper bundles dist/node_modules/).
  5. Distribute the wrapper (apt, manual rsync, etc.).
  6. Each Device runs hivecast stop && apt upgrade hivecast && hivecast start.

This is the present-state release process. It works; it is not self-service for end users.

Compatibility matrix ​

There is no compatibility matrix today. The implicit guarantee is "the package set bundled with one wrapper version is mutually compatible." The explicit cross-version compatibility table that a registry-pull model would need does not exist.

Signing and integrity ​

Today: no signing. The bundled dist/ is whatever the wrapper publisher built. Tampering is detected only by general OS-level package-manager signing of the wrapper itself.

Target: signed package manifests, signature verification at install time, configurable trust roots. None of this exists.

Per-Space / per-fleet versions ​

Target: a Space could pin its own package versions independent of other Spaces. A fleet could roll forward independently. None implemented.

See also ​

Source: projects/matrix-3/packages/hivecast/bin/hivecast.mjs for the bundled-install behavior. WORKSTREAMS/docker-npm-parity/ for the target. ARCHITECTURE/ARCHITECTURE-PLATFORM-TOPOLOGY.md §8 for the registry pipeline design.