Stado
On this page

Host release capability

The release capability owns the complete lifecycle of release declarations on a registry host: declare or promote a desired version, compare the live host to that declaration, deliver only upgrades, activate a staged self-repair, and attest provenance. Desired host state is never inferred from Desktop, an installed version, or an ad-hoc registry field. It is read from targets[].managed_versions; immutable artifact identity and digest are read from the canonical release manifest.

Invocations

  • stado release version declare --host <TARGET> --binary <NAME> --version <X.Y.Z> [--json]
  • stado release version unset --host <TARGET> --binary <NAME> [--json]
  • stado release version promote --host <TARGET> --binary <NAME> --version <X.Y.Z> [--json]
  • stado release version show --host <TARGET> [--binary <NAME>] [--json]
  • stado release version converge --host <TARGET> [--binary <NAME>] [--json]
  • stado release staged activate --host <TARGET> --product <NAME> --env-file <PATH> --port <PORT> [--json]
  • stado release provenance --host <TARGET> [--json]

staged activate assumes no product: the product, its deployment env file and the port the activated release answers on are each named, and a missing one is refused by the parser with exit 2. Stado Desktop's Activate a verified staged release form requires the same three fields.

version show is read-only. version converge delivers host-behind and host-missing declared versions through the same manifest-verified host delivery path. It refuses host-ahead; it never rewrites desired state from a live machine. Each binary carries the reporter's seven fields without translation: binary, version, root, unit, state, attestation, and receipt, followed by the declared version, verdict, and detail. A target with an empty managed_versions object returns top-level state: "undeclared", an empty binaries list, and a zero exit status.

host-missing is the verdict for a host that carries no artefact at all: the version reporter answered, and there is nothing on the host to compare the declaration against — the host declares a binary it does not carry. It is deliberately not unknown. unknown is a failed measurement, and is still never delivered to. host-missing is a successful measurement of an absence, so version show exits non-zero on it and prints N declared binary/binaries are not on this host at all; stado release version converge delivers the first copy, and version converge delivers that first copy. Nothing is replaced and no process is interrupted, because no process on the host is running the declared binary.

Every version show or version converge visit, declared or undeclared, also refreshes the host's software report: one row per program the host carries — $HOME/.stado/bin, every declared unit's program, the release-control products rolled out to the target, and the artefact roots the drift read resolved — with its path, version, SHA-256 and release or unmanaged provenance, written to the observation store the way observation records every look that decays. stado release status never contacts a host; it judges each rollout target against this report and against its age, so this visit is what keeps that verdict current, and a report nobody refreshes reads reported stale on every target. The text report ends with one line, software=observed recorded=just now: <PROGRAMS> program(s), <RELEASED> release, <UNMANAGED> unmanaged, <SCRIPTS> script(s), and --json carries the same report under software — host, state, observed, detail, reported, release, unmanaged, scripts and programs — exactly as release status will read it. A host the channel cannot read is recorded as unverified with the channel's refusal in detail, and reported on stderr as <TARGET>: cannot read what software it runs, recorded as unverified: <REFUSAL>; a report this process could not write is <TARGET>: the software report was not refreshed: <SENTENCE>. Neither changes the exit status, which stays the drift gate above: the report's freshness is release status's finding, not this command's. The visit runs over one authenticated session — the target's key is fetched from Skarbiec once and the route chosen once — and the bin directory is classified in a single command on the host, so a host with thousands of retired helper scripts is read in minutes rather than one round trip per file.

provenance reads delivery receipts as well as build manifests, and states which of the two accounted for each artefact. The table carries an ACCOUNTED column whose value is manifest, release-receipt or unprovenanced, and --json carries accounted_by beside receipt, version, platform, archive_sha256, unresolved, helper_scripts and delivery_markers. A receipt accounts for an artefact only when the artefact digest it recorded equals the installed bytes, so the record always describes the file in place rather than one that was once there. That is why the receipt a delivery writes at $HOME/.stado/releases/<binary>/<version>/<platform>/release-receipt.json carries artifact_sha256, the digest of the installed file, beside sha256, the digest of the archive the manifest named: one is what this host has, the other is what the channel published, and only the first can answer for a file on disk.

A delivery's report names the receipt it wrote under receipt, or, under receipt_unwritten, the receipt path and the host shell's own words for why it could not be written or made owner-only (or that its version/platform directory is not there). Each is null when the other answered. A receipt missing from a host is therefore either a delivery made before receipts or one whose report said why, never an unexplained gap.

Non-executable files in ~/.stado/bin, including stado.release-version markers, are counted separately rather than treated as artefacts. An artefact whose commit no local checkout can resolve is reported as unmeasured, could not be resolved against any checkout here, which is unmeasured rather than unreachable. An unavailable measurement is not evidence that the revision is unreachable.

Declarations

  • Host desired versions: canonical registry document, targets[].managed_versions.
  • Host release platform: canonical registry document, targets[].release_platform.
  • Deliverable products/platforms: stado-rs/data/catalog/products.json, compiled in through src/deploy/products/mod.rs.
  • Immutable artifact identity and SHA-256: the signed stado://releases/<product>/<version>/<platform>/release.json, verified against release.sig with the registry's release trust keys.
  • Staged activation coordinate: the deployment env file --env-file names; it declares <PRODUCT>_RELEASE_VERSION, <PRODUCT>_RELEASE_SHA256, and STADO_RELEASE_LOCAL_ROOT.
  • Provenance: the host's delivered artifact and provenance declarations under $HOME/.stado/releases and $HOME/.stado/provenance, and the delivery receipt beside each delivered artefact at $HOME/.stado/releases/<binary>/<version>/<platform>/release-receipt.json.

Exact refusal sentences

Values in angle brackets are filled with the declaration or observation that caused the refusal.

  • Missing requested managed version: <TARGET> declares no <BINARY> version; add it to targets[].managed_versions with stado release version declare --host <TARGET> --binary <BINARY> --version X.Y.Z (the command is backtick-quoted in terminal output).
  • Invalid managed version: <TARGET> declares <BINARY> version "<VALUE>", which is not an exact semantic version; set targets[].managed_versions.<BINARY> to a version such as 0.5.1.
  • Unknown release platform: <TARGET> declares release_platform "<PLATFORM>", which cannot carry a managed release: "<PLATFORM>" is not a published release platform; expected one of darwin-arm64, linux-amd64; set targets[].release_platform to a published platform.
  • Host-ahead converge refusal: <BINARY>: runs <INSTALLED>, newer than the declared <DECLARED> — refused to downgrade the host; move the declaration instead: stado release version declare --host <TARGET> --binary <BINARY> --version <INSTALLED>.
  • Missing registry target during declaration: <TARGET> is missing from registry.targets; add the host declaration before declaring a managed version.
  • Missing registry target during promotion: <TARGET> is missing from registry.targets; add the host declaration before promoting a release.
  • Invalid managed-version object: <TARGET> declares managed_versions as a non-object; replace targets[].managed_versions with an object.
  • Missing staged coordinate: the deployment env file declares no <KEY>; add it to the deployment env file before activating a staged release.
  • Invalid staged digest: the deployment env file declares <KEY>="<VALUE>", which is not a sha256 digest; replace it with the staged archive's 64-character digest.
  • Unresolvable staged path: the deployment env file declares path "<PATH>", which cannot be resolved without running a shell; replace it with $HOME, ${HOME}, ~, or an absolute path.
  • Staged digest mismatch: the staged archive hashes to <OBSERVED>, but the deployment env file declares <DECLARED>; stage the declared archive or update the deployment env declaration.
  • Unusable deployment env file: staged release coordinates are declared in <ENV_FILE>, which could not be used: <TARGET>: <STATE> — <DETAIL>; restore the deployment env file before activating. The middle is the fetch's own report, so a file that is missing (exit as not found) is told apart from one that could not be read or whose bytes did not arrive intact (exit as an infrastructure failure).
  • Failed staged installer: <TARGET>: the staged installer for <PRODUCT> <VERSION> failed with exit <CODE>: <LAST ERROR LINE>, before the version and API are compared.
  • Unreported runtime link: <TARGET>: the activation run did not report the runtime link after installing|after the settle window|at all; whether the release held is unknown. The link is read once after the installer and once after the settle window, and a reading that is missing is said rather than compared against a blank.
  • Unsupported staged host platform: <TARGET> reports no supported staged-release platform; add this OS/architecture to the release platform declaration before activating.
  • Missing staged archive: <TARGET> declares a staged release but <ARCHIVE> is missing; stage the declared archive before activating it.
  • Unreadable installed version: <TARGET>: the installed version could not be read: <HOST ERROR>. A host without the release's package file answers an empty version and is activated; a read the host refused is not taken as one. The API check before and after activation is refused the same way when the host channel fails, instead of reading as an API that was silent.
  • Provenance read failure: <TARGET>: cannot read provenance manifests: <HOST ERROR>; repair the named host channel/file refusal and rerun provenance.
  • Missing or invalid signed release manifest and missing immutable objects are refused before mutation. The sentence includes the exact stado://releases/... URI and directs the operator to publish a new immutable version when a coordinate cannot be completed.

Stado Desktop

The Hosts inspector has a Release state section backed by stado release version show --host <TARGET> --json. It displays the command's top-level declared/undeclared state, exact refusal, declared version and verdict, and every reporter field (binary, version, root, unit, state, attestation, receipt), and below the binaries the software report that visit wrote, with its observed program, release, unmanaged and script counts. When the host could not be read, a warning panel carries the report's state and the refusal in the host's own words. The section reads on host selection and offers an explicit refresh. It does not calculate drift or desired versions itself and does not expose version converge as an unconfirmed UI action.

Source: this website