Package management and distribution
Package management and distribution provide one path from pinned third-party inputs to usable Hermes environments and published releases. The system resolves packages for the current platform, verifies and stores their bytes, builds dependency environments that include selected plugins, and moves tested release artifacts through an ordered publication process.
System boundaries
The subsystem has two related responsibilities. Package management makes a local or build-time environment match declared dependency state. Distribution turns tested application builds into immutable artifacts and advances public update channels only after their identity and integrity are checked.
The package manager owns package pins, target support, installed state, tool exposure, and recovery. The release system owns native package receipts, candidate manifests, public feeds, Docker release identities, and channel promotion. They meet at the build boundary: release jobs use the package manager to create repeatable build inputs, then publish the resulting bytes without rebuilding them during promotion.
Package acquisition
Package pins
Package pins define the version and verified artifact set for each supported target. A lock entry carries resolved URLs and SHA-256 values, so an install does not need to re-create a download decision from a changing upstream index. Update checks may inspect upstream release indexes, but a real update changes the lock only after it finds a version or target-specific artifact that all required targets can use. (Related page: package resolution and environment builds)
References: pm/lock.py• L1-18 pm/update.py• L1-23 pm/package.py• L52-107
Artifact store
The artifact store is the shared byte source for installed tools and build operations. It keeps verified downloads by digest, stages package trees in scratch space, checks their expected layout and target architecture, then publishes each usable tree with an atomic move. This lets failed work leave the prior usable entry in place and lets several consumers reuse the same verified bytes.
The store also handles platform differences such as Windows, macOS, Linux, musl, and Android targets. A package can be unavailable on a target without being an error in the package definition; the resolver and callers must treat that gap as an explicit platform choice.
References: pm/store.py• L24-35 pm/store.py• L152-168 pm/store.py• L381-486 pm/package.py• L131-183
Installed state
Installed state records which lock identity is present and how that package changes the runtime environment. The record includes the store entry, target, artifact digests, realized tree digest, and environment contribution. Startup and diagnostics can therefore detect drift without downloading packages, while an explicit install can re-check the bytes and repair a changed entry.
References: pm/lock.py• L149-225 pm/lock.py• L241-279 pm/install.py• L299-305
Environment construction
Tool environments
Tools are installed from the same pinned store as application dependencies. Their dependency graph is walked before installation, and the resulting environment places complete managed tool chains ahead of host tools when Hermes runs commands. Internal package tools support setup and builds without becoming user-facing application roots.
References: pm/install.py• L563-645 pm/install.py• L1050-1133 pm/package.py• L52-71
Dependency environments
The project environment is a selected state, not just a directory. Its validity depends on the project lock, enabled extras, the selected plugin members, and the interpreter or platform that will install them. Hermes builds a fresh candidate generation, checks it, and records the generation only after it is ready. This prevents a failed dependency solve from replacing the active environment.
The environment can be rebuilt from the recorded dependency selection when its files are damaged or when a shipped code and lock set changes. Recovery validates the candidate with the candidate interpreter, so the repairing process does not rely on the environment it is repairing. (Related page: package resolution and environment builds)
References: pm/packages.py• L469-571 pm/install.py• L782-847 pm/recovery.py• L23-64 pm/recovery.py• L92-131
Plugin dependency union
Enabled plugins that declare Python packages join the core project as workspace members for one environment generation. Their source is copied into a writable build snapshot, and the generation stamp includes the member set and member content. A plugin change therefore causes a new solve even when the core lock and selected extras did not change. (Related page: package resolution and environment builds)
The following flow shows how a package or plugin input becomes an active environment or a release input.
flowchart LR
A[Lock and package declarations] --> B[Target resolution]
B --> C[Verified artifact store]
C --> D[Tool environment]
A --> E[Core project and enabled plugins]
E --> F[Candidate dependency generation]
D --> F
F --> G[Validated active environment]
D --> H[Build inputs]
G --> H
H --> I[Native release artifacts]
References: pm/workspace.py• L1-5 pm/workspace.py• L37-63 pm/workspace.py• L137-177 pm/packages.py• L490-510
Artifact distribution
Release candidates
Release jobs build native packages from an admitted source and stage them as candidate artifacts. Each package is recorded from its actual embedded identity and version. Receipts bind file paths, sizes, and digests to the release attempt, while a candidate manifest groups those receipts with smoke results and the source commit.
Promotion consumes that manifest instead of rebuilding or trusting workflow names. Windows, macOS, and Termux packages can be built by separate jobs, but the candidate assembly checks that the handoffs agree and that the candidate contains exactly the targets claimed by the release lanes.
References: scripts/…/release_artifacts.py• L76-156 scripts/…/release_artifacts.py• L179-248 scripts/…/channel_releases.py• L57-84
Release promotion
Stable publication is an ordered transaction over several delivery systems. A green build first leaves immutable versioned artifacts and receipts. The publication controller then validates the accepted candidate, writes public update feeds and package indexes, promotes Docker aliases, and advances the protected channel head. The final version tag records the custody of the accepted bytes.
Canary and one-off builds use separate channel or commit identities. They can publish diagnostics or preview feeds without changing the stable channel. A stable channel moves only when the release includes the complete desktop set that the channel serves.
References: scripts/…/release_artifacts.py• L255-309 scripts/…/release_artifacts.py• L359-395 scripts/…/channel_releases.py• L341-446 website/…/stable-releases.md• L1-7
Release recovery
Release recovery preserves the original claim, commit, lane set, receipts, and candidate bytes. A failed publication pass reruns the missing work and verifies each existing object before it continues. It does not replace accepted artifacts to repair a pointer, because the immutable receipt is the source of truth for what was tested.
The same principle applies locally. Package publication keeps the prior store entry available until the new entry and installed facts are committed. Environment recovery rebuilds the recorded graph and keeps the previous selected generation until the replacement passes validation.
References: scripts/…/channel_releases.py• L121-191 scripts/…/channel_releases.py• L236-256 pm/install.py• L326-369 pm/recovery.py• L53-64
Change checklist
When these files or sections are changed, remember to consider these:
- A package pin change must remain consistent across every supported target, its artifact digest, and the package's target-specific layout checks.
- A package environment contribution change must be reflected in recorded installed facts; otherwise activation can silently use an old PATH or runtime setting.
- A plugin workspace input change must update the environment stamp inputs so the active generation cannot be reused for a different member set.
- A release receipt or candidate-manifest schema change must remain compatible with candidate admission, materialization, promotion, and channel bootstrap readers.
- A new release target must be added to the lane claim, handoff receipt set, candidate package set, and public feed rules as one contract.
- A public pointer change must preserve the immutable artifact and read-back checks; pointers must never become the only record of accepted bytes.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A lock entry has no artifact for the current target | The package cannot be installed or staged | Target-aware lock validation and explicit package gaps |
| A downloaded archive has the wrong digest or unusable layout | The new store entry is rejected and the prior entry remains available | Digest verification, package verification, and atomic store publication |
| Plugin members change without a new generation stamp | The active environment can omit or retain the wrong plugin dependencies | Member content and identity are part of the environment stamp |
| A release receipt disagrees with the candidate manifest | Publication stops before public feeds or channel heads move | Receipt digest checks and candidate validation |
| Publication fails after one service is updated | A later retry may see a partial release state | Idempotent read-back checks and immutable versioned objects |
| The recorded environment is damaged or no longer matches the source lock | Hermes may fail at startup or run with stale dependencies | Fresh generation rebuild and candidate-interpreter validation |
Key files
| File | Why to read it |
|---|---|
| pm/package.py | Defines the package contract, dependency relationships, target gaps, verification, and environment contributions. |
| pm/lock.py | Describes the lock and installed-state identities that connect pins to realized bytes. |
| pm/store.py | Shows the verified, shared, atomic artifact-store boundary. |
| pm/install.py | Connects dependency graphs, store entries, runtime environment activation, and rollback. |
| pm/packages.py | Shows how tool packages and the project environment participate in the package graph. |
| pm/workspace.py | Explains how core and plugin sources become one dependency-solving input. |
| pm/recovery.py | Defines environment validation and recovery behavior. |
| scripts/…/release_artifacts.py | Defines candidate receipts, artifact materialization, feed publication, and promotion. |
| scripts/…/channel_releases.py | Coordinates protected channel admission, candidate matching, and release publication. |
| scripts/release.py | Provides the operator entry points for stable, canary, and one-off release flows. |
| .github/…/stable-release.yml | Shows the build, acceptance, candidate, and publication stages of a stable release. |
| website/…/stable-releases.md | Gives the operator-level release and recovery model. |