The updater is part of the reliability model
A client update changes executable code while local state may describe an active assignment. Treating update as a simple package install risks leaving an engine running under assumptions from the old version, or replacing the supervisor while progress files are still being written. OpenPuzzle therefore treats the update path as an execution-control operation.
The safe path checks the available release, verifies the package selected by the release manifest, stops managed execution through the normal runtime controls, installs the new package and then lets the updated client reconcile state.
Why the portable filename contains a hash prefix
OpenPuzzle releases include a package named with the version and the first eight hexadecimal characters of its SHA-256 digest, for example the 1.0.17 portable package. The full digest remains in SHA256SUMS.txt. The short prefix is not a replacement for full checksum verification; it makes the selected asset visibly tied to the manifest while the updater still validates the complete hash.
The manifest intentionally contains one valid portable package entry for the updater path. This keeps discovery deterministic and prevents an ambiguous release from silently selecting between several similarly named packages.
Stop before replacement
For an active client, safe stop is preferable to installing over a running supervisor. The runtime marker, persisted execution state and workspace process metadata are all checked using the same process-identity rules. Only a process that belongs to the current boot and matches the stored identity can be treated as the managed process.
This matters because update is exactly the kind of event that can expose stale state. A machine may have rebooted since the assignment was written, or a PID may already belong to an unrelated process. The updater must not use package installation as an excuse to bypass those safety checks.
Release assets should be reproducible enough to audit
The release publishes the normal Debian package, its checksum, a tar archive, its checksum, the portable Debian asset and the updater manifest. For OpenPuzzle 1.0.17 the portable package is byte-for-byte identical to the standard Debian package; the distinct name is an updater discovery contract rather than a different binary build.
Keeping the package bytes identical reduces the number of artifacts that need independent functional interpretation. A user who installs the standard package and a user who updates through the portable asset receive the same packaged client.
Why verification happens before installation
A downloaded file is untrusted until its digest matches the published manifest. The client therefore hashes the asset before invoking the package manager. A mismatch is a terminal updater error, not a warning. That ordering avoids handing corrupted or unexpectedly modified bytes to the installer.