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, verify a release platform, 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 declare-version --host <TARGET> --binary <NAME> --version <X.Y.Z> [--json]
  • stado release declare-version --host <TARGET> --binary <NAME> --unset [--json]
  • stado release promote-version --host <TARGET> --binary <NAME> --version <X.Y.Z> [--json]
  • stado release host-state --host <TARGET> [--binary <NAME>] [--apply] [--json]
  • stado release verify-platform --host <TARGET> --repo <PATH> --ref <REVISION> [--json]
  • stado release activate-staged --host <TARGET> [--product <NAME>] [--env-file <PATH>] [--port <PORT>] [--json]
  • stado release provenance --host <TARGET> [--json]

host-state report mode is read-only. --apply 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 report mode exits non-zero on it and prints N declared binary/binaries are not on this host at all; re-run with --apply to deliver the first copy, and --apply delivers that first copy. Nothing is replaced and no process is interrupted, because no process on the host is running the declared binary. A leased account with nothing installed was delivered a pipeline-signed 0.16.42 exactly that way and read back verdict in-sync, attestation staged-match.

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.

Two readings the same command used to get wrong. A non-executable file in ~/.stado/bin — the delivery path's own stado.release-version marker among them — is counted separately instead of being rowed as an artefact, because it was a permanently unprovenanced row that no delivery could ever clear. And an artefact whose commit no local checkout could resolve is reported as unmeasured, could not be resolved against any checkout here, which is unmeasured rather than unreachable, instead of being counted as unreachable: nobody looked and somebody looked and could not get there are different findings, and only one of them is about the host.

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/products.json, compiled in through src/deploy/products/mod.rs.
  • Immutable artifact identity and SHA-256: stado://releases/<product>/<version>/<platform>/release.json (or the legacy release-manifest-<platform>.json accepted by the existing delivery reader).
  • Staged activation coordinate: the declared deployment env file, by default $HOME/.config/weles/worker.env; 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 declare-version --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 apply refusal: <BINARY>: runs <INSTALLED>, newer than the declared <DECLARED> — refused to downgrade the host; move the declaration instead: stado release declare-version --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.
  • Missing deployment env file: <TARGET> declares staged release coordinates in <ENV_FILE>, but that file could not be read (<STATE>); restore the deployment env file before activating.
  • 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.
  • Platform verification failure: <TARGET>: platform verification failed:\n<HOST OUTPUT>; the host output names the failed native journey to repair and rerun.
  • Provenance read failure: <TARGET>: cannot read provenance manifests: <HOST ERROR>; repair the named host channel/file refusal and rerun provenance.
  • Missing or invalid canonical release manifest and missing immutable objects are refused by the existing release-manifest reader before mutation. Its sentence includes the exact stado://releases/... declaration URI and directs the operator to publish a new immutable version when a coordinate cannot be completed.

Replaced host verbs

  • stado host declare-version
  • stado host promote-version
  • stado host activate-staged-release
  • stado host verify-release-platform
  • stado host release
  • stado host software
  • stado host provenance

None remains in stado host --help; there is no alias or deprecated wrapper.

Stado Desktop

The Hosts inspector has a Release state section backed by stado release host-state --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). The section reads on host selection and offers an explicit refresh. It does not calculate drift or desired versions itself and does not expose --apply as an unconfirmed UI action.

Source: this website