PAUIOps releases: One manifest as the source of truth

Publishing a desktop or server binary is often treated as the last step of a build. In practice, release metadata is part of the product. An installer needs to know which version belongs to a channel, which file matches the current platform, and which checksum proves the download arrived unchanged. The website must show the same facts without maintaining a second, drifting copy.

The PAUIOps Manager release pipeline is designed around one rule: the published manifest is the source of truth. The download page, channel pointers, and installer all derive their answers from the same release record.

This field note explains why that structure matters and how it supports verification and rollback.

The failure mode: several “latest versions”

A manual release can easily update only part of the system:

• The binary exists, but the website still advertises the previous version.
• The download button points to a file that was renamed during upload.
• The installer hard-codes a different version from the release page.
• The checksum belongs to a local build, not the file actually served over HTTPS.
• A beta release accidentally becomes the stable download.

Each copy of version metadata creates another opportunity for drift. Fixing this with a longer checklist helps, but the stronger solution is to remove duplicate authorities.

One manifest drives every consumer

PAUIOps publishes a release history manifest at public/releases/index.json. That manifest contains the release records and channel pointers used by the website. The stable, beta, and development channels also have small channel manifests for runtime resolution.

The release layout is deliberately predictable:

releases/
  index.json
  stable.json
  beta.json
  dev.json
  latest.json
  <version>/
    pauiops-<version>-<os>-<architecture>
    pauiops-<version>-<os>-<architecture>.sha256
    checksums.txt
    release.json
    version.txt

The website reads the history manifest to render real versions, dates, platforms, file sizes, and checksums. The install script resolves a channel manifest at runtime, then downloads the exact filename and checksum declared there. There is no separate version string to update in the page component after publication.

Immutable version directories simplify recovery

Files inside a published version directory are immutable. A later release gets a new directory rather than overwriting the previous binary.

That produces several operational advantages:

• A checksum remains meaningful because the file behind the URL does not change.
• Existing installations can refer to an older artifact during investigation.
• Rollback can move a channel pointer without rebuilding the previous version.
• Caches do not need to guess whether an unchanged URL now contains different bytes.
• The release history remains auditable.

“Latest” is therefore a pointer, not a mutable binary. latest.json mirrors the stable channel for compatibility, while the versioned asset retains its permanent address.

The publisher owns the complete transaction

The deployment command does more than compile. For an approved semantic version, it performs the release responsibilities as one workflow:

1. Validate the version and target configuration.
2. Build each configured operating-system and architecture target.
3. Calculate SHA-256 checksums from the built artifacts.
4. Generate version and release metadata.
5. Stage the complete version directory.
6. Update release history and the selected channel pointer.
7. Publish the staged data to the configured release destination.
8. Verify the public artifacts when a live destination is available.

A dry-run mode previews the work without building or publishing. That makes the release plan reviewable before it mutates the public channel.

The list of platforms is configuration, not repeated shell logic. Adding a supported target is one controlled change, and validation can confirm that every declared artifact appears in the generated metadata.

Checksums verify bytes, not intent

SHA-256 allows the installer to verify that the downloaded bytes match the manifest. The expected checksum must come from trusted release metadata and must describe the exact public artifact.

The installer flow is:

Resolve channel manifest
    ↓
Select platform artifact
    ↓
Download artifact
    ↓
Calculate local SHA-256
    ↓
Compare with published checksum
    ↓
Install only on an exact match

A checksum does not prove that a binary is free of bugs or that the build environment was trustworthy. It protects a narrower and still important boundary: the artifact being installed is the artifact described by the release record. Signing and stronger supply-chain attestations can extend that model, but they do not remove the need for deterministic file identity.

Publishing must be atomic from the reader's perspective

The dangerous sequence is to update the stable channel before all versioned files are reachable. During that window, installers resolve a version whose binary or checksum returns 404.

The safer order publishes immutable assets first, verifies their presence, and moves the channel pointer last. Readers either see the previous complete release or the new complete release. They should not see a half-published version.

When publication targets a remote directory, copying files is not the same as proving the public website serves them. The verification step must request the actual HTTPS URLs used by installers. That catches mount mistakes, stale containers, reverse-proxy rewrites, and uploads sent to a directory the live service does not expose.

Honest empty states are part of release safety

Before the first release exists, the PAUIOps website does not fabricate a version, file size, checksum, or download link. It renders an explicit “not published” state.

This may look less polished than a placeholder download, but it prevents a more damaging experience: a confident interface that points to a nonexistent or unverified artifact. The same rule applies when a manifest cannot be read. Availability is not inferred from a marketing configuration value.

Honest states also make operational problems visible sooner. A missing release cannot be mistaken for a frontend styling bug when the interface clearly reports that no verified artifact is published.

Channel rollback is a metadata operation

Because old version directories remain available, rollback does not require rebuilding the previous release. The operator selects a known version from the release history and repoints the affected channel to its existing metadata.

Rollback still requires verification:

• Confirm the old artifact and checksum are publicly reachable.
• Move only the intended channel.
• Verify the channel manifest over HTTPS.
• Run the installer in a non-production target or its test harness.
• Record why the newer release was withdrawn.

Keeping stable, beta, and development pointers separate prevents an experimental release from silently changing the production path.

Validation belongs before and after publication

PAUIOps uses checks at several layers:

• Content validation confirms the site can interpret the release schema.
• Release validation checks metadata, platform coverage, paths, and checksums.
• Installer tests exercise channel and platform resolution.
• The production website build proves the download UI can consume the manifest.
• Live HTTP verification proves that the public server exposes the files expected by the manifest.

Local success and live success answer different questions. A valid manifest on disk does not prove the reverse proxy serves it, and a 200 response does not prove the downloaded file matches the declared checksum. Both sides are necessary.

Lessons from making metadata authoritative

The design can be summarized in a few rules:

1. Choose one source of truth. Website copy, installers, and automation should read it rather than repeat it.
2. Publish immutable artifacts. Mutability belongs in small channel pointers, not versioned binaries.
3. Move pointers last. A channel should never refer to an incomplete release.
4. Verify the public path. The destination directory is not the user-facing URL.
5. Keep failure honest. Unknown or unpublished data should not be replaced by plausible-looking placeholders.
6. Design rollback before the first incident. Retained artifacts and explicit channel pointers make recovery a controlled metadata change.

A release pipeline is successful when every consumer agrees on what exists and can prove the bytes it received. Making the manifest authoritative reduced the number of places that can disagree and turned publication from a collection of manual edits into one verifiable transaction.