archy/docs/public-application-update-worker.md

Public application update owner

The public profile updates the backend, dashboard and their packaged runtime helpers. It does not run a Debian/kernel transaction. The original root-signed manifest must authorize application_update: {version: 2, mode: "signed-application-runtime"} and exactly the backend/frontend component pair. Existing or partial D09/C01 ownership always selects its protected admission route; missing managed file descriptors or failed transport cannot authorize a public fallback. The earlier version 1 pair-only policy remains recognized for compatibility and focused transaction qualification.

Transaction boundary

The installed root-owned verifier authenticates the original signed JSON. Root preparation copies the authenticated downloads into immutable snapshots, then submission installs the current owner's embedded Python as an independent PID1 worker. Its journal and snapshots live below /var/lib/archipelago-public-transactions. The manager's response acknowledges submission; it does not acknowledge successful installation.

Before replacement the worker verifies the running manager, stops it, drains maintenance timers, freezes both code preimages and the fixed runtime domain listed in scripts/public_update_runtime.py, and records their identities. The domain contains application code, radio helpers, relevant systemd units, existing nginx routing, and the public-runtime ownership record. Optional kiosk, audio and gamepad helpers remain absent when the previous installation omitted them. The worker preserves service enablement decisions and restores only timers that were already active. An in-flight maintenance job refuses the attempt.

The incoming dashboard retains the existing validated nginx routing template. A root-owned record binds the executing backend hash and release version to the transaction. On that startup, the backend skips the older nontransactional host runtime promotion and repair routines. Normal application startup, container reconciliation and API behavior continue after the code owner releases startup.

All code mutation follows durable preparation. Boot recovery is durably linked before the transaction becomes current. It restores interrupted transactions before the manager, doctor and NPM maintenance units can start. A submission interrupted before publishing its pointer can recover only while its original predecessor remains the current completed transaction. Old recovery units cannot operate on a newer transaction. Retried upgrades after rollback reuse only the previous owner's exact known service dependencies. Every forward or reverse replacement checks the complete installed and saved identity domains; foreign edits and corrupt preimages are retained for reconciliation. Success requires the actual /proc/PID/exe hash, backend health/version, exact served frontend entry bytes, and exact installed code/runtime identities. Recovery is resumable and must verify the old running pair before reporting restored.

The manager namespace hides the frontend's runtime bootstrap input after a runtime transaction. This prevents an authenticated historical binary from repromoting that payload on rollback and deleting restored private app sources. The host owner and nginx retain the complete authenticated frontend. A durable transaction marker also holds maintenance services and timers while startup is being verified. If the historical binary re-enables a previously disabled timer, recovery removes only its exact standard enablement link before releasing the pause; foreign links remain a reconciliation error.

No worker destination is a wallet, container store, app data directory or install/uninstall/stopped record. The application prefix directory itself gains root custody so an application cannot rename installation paths; this does not recursively change ownership of its children or data. Original downloads, retired trees and failures remain available; there is no evidence garbage collection.

First upgrade from a historical installer

An older updater such as 1.9.1 replaces its code pair, writes the pending verification marker, deletes staging, then restarts the newly installed daemon. The successor handles that marker before host bootstrap or application recovery. It remains in Type=notify startup, extending the bounded startup timeout while an independent root operation admits the migration.

That operation fetches manifest.json and legacy-manifest-VERSION.json from the successor's fixed HTTPS release attachment origin. Both original documents must verify under the pinned release root. It fetches the signed incoming artifacts again because historical staging no longer exists. The historical backend backup must match its old signed artifact; the frontend backup must match its signed archive, allowing only the documented existing routing-template mutation and Companion bytes already present in the signed incoming release. Signed old static extras are preserved when the new archive does not supersede them. Arbitrary backup scripts are never accepted as executable recovery input.

The installed incoming pair is checked against those authenticated images before queuing the same runtime transaction. Its frozen old pair can be restored even if the worker dies before runtime preparation. The exact pending marker is retained inside the transaction on completion or recovery. A changed marker is not deleted. Interruption before the independent owner has admitted the upgrade still belongs to the historical installer's recovery behavior; that limitation must be tested with the actual older artifact, not inferred from worker fixtures.

The new installed binary is already the older authenticated installer's chosen executable. This startup handoff is distinct from executing an uninstalled candidate to establish its own verification authority. Publication uses a separate appointed verifier and clean build receipt.

Protected and custom installations

The fixed public layout is /usr/local/bin/archipelago, /opt/archipelago/web-ui, User=archipelago, no extra ExecStart arguments, backend port 5678 and dashboard port 80. Custom layouts, special preimage inodes and unresolved foreign ownership refuse conversion. Protected nodes retain their release-bound D09/OS plans and admission; a generic public manifest does not replace that authorization.

A source bundle can also be emitted with python3 scripts/package-public-update-worker.py --output /new/output/worker.py. This creates no installation or authority. A separately reviewed root-custody installation is required before an older client without the successor's dispatch can invoke its fixed apply command with original signed JSON on stdin. No frontend-downloaded bundle is automatically executed as root. Status and manual recovery stay available through the independent retained worker after rollback.

Qualification

The PID1 fixture uses a private disconnected container store without host mounts. It retains each frozen attempt, journal and transaction. It has explicit fixture ELF, signature and download doubles, and exercises real service replacement, runtime files, startup handoff, crash boundaries and a full PID1 restart. These results do not qualify a production signature, actual product startup, public availability or physical acceptance. Those gates require their own evidence. Backend tests run through scripts/test-backend-isolated.sh.