archy/docs/os-updates.md

Debian and kernel updates

The candidate adds release-bound Debian package updates to the protected D09 update path. Application activation, package installation and kernel activation are separate results. Source integration and test results are not installed-node or release acceptance. See the executor contract for the exact authority and input formats.

What the System Update screen means

Open Settings → Updates (/dashboard/settings/update).

Display	Meaning
Current application	Running Archipelago application version, not the Debian or kernel version.
Installed OS	Owner-observed Debian installation. Unknown means it has not been reliably observed.
Installed target kernel	Verified installed kernel image; this alone does not mean it is running.
Running kernel	Fresh owner observation of the kernel currently executing.
Reboot required	Yes, No, or Unknown from the protected owner. Unknown is not No.
Post-boot verification	Verified only after the owner confirms the required new boot, kernel/build and payload provenance, package state and external preservation evidence.
OS updater upgrade required	The installed owner cannot execute this protocol. An administrator must complete the approved prerequisite installation.
OS update needs administrator recovery	The retained transaction is incomplete or uncertain; packages may already be partially installed.

The phases are prepare, download, verified-for-installation, apply-intent, installed-package verification, reboot-required, and postboot-confirmed. VERIFIED means downloaded packages are ready for installation. It does not mean the packages are installed. REBOOT_REQUIRED does not claim post-boot success. Generic D09 application completion never implies kernel activation.

Status is refreshed on the page. A disconnect or failed inspection clears prior verification rather than continuing to display a stale success. “No newer application release offered” does not claim the OS is fully updated.

Reboot and recovery

Updates do not automatically reboot. The update screen adds no reboot operation. Reboot must use a separately authorized existing power operation, including its C01 admission, clock/epoch and recovery requirements.

If package installation fails or the outcome is unknown:

1. Keep the retained journal and package/boot evidence. Ask the administrator to inspect the original transaction and current dpkg state.
2. Do not repeatedly apply the release, rerun maintainer scripts, or automatically execute dpkg --configure -a. Repair needs separately reviewed authority.
3. Application recovery restores application code/configuration only. It does not roll back Debian packages, undo maintainer scripts, restore financial databases, or guarantee the previous kernel will boot.
4. Preserve wallets, node identities, persistent data, settings, and explicit stop/uninstall decisions. Recovery never authorizes another payment.

Supported transaction scope

• Debian bookworm or trixie, matching the already-installed suite, on amd64 or arm64. This is not a Debian release-upgrade facility.
• Exact, reviewed whole APT dependency transaction from the three Debian pockets (base, updates and security) and all four components (main, contrib, non-free, non-free-firmware). Repository/index/package hashes and Debian signatures are checked. Expired metadata or solver drift refuses the transaction.
• Explicit reviewed removals, preserving protected custody packages and installed versioned kernel images. No purge, autoremove, automatic repair or downgrade.
• New versioned Debian kernel installation and metapackage upgrades. Package-only transactions may retain the current kernel, but still require authenticated kernel archive/provenance and a fresh post-maintenance boot.
• A maintenance operation must establish exclusive package-writer custody and approve Debian maintainer-script/service interruptions and preservation evidence.

Current limitations

• Foreign dpkg architectures are refused. Vendor/Pi kernels are not qualified.
• In-place replacement of an installed versioned kernel image is refused. Merely saving its old vmlinuz while replacing same-release modules is not sound fallback. Such a transaction needs a separately qualified boot-environment implementation.
• Boot verification is operational provenance, not measured boot. Physical boot selection, firmware behavior and preservation acceptance require artifact/node qualification, not a source test.
• Exact pre-install inventory pins are host-specific. A different node's plan is not automatically valid for this node, even for the same application version.
• A root-owned preservation assertion is an external authority input; it is not a proof that arbitrary Debian maintainer scripts cannot affect application data.

How the release binds the OS plan

The producer requires a reviewed os-update-plan.json. Its exact hash and size are a release component alongside backend and frontend. The manifest also carries os_update: {"version": 1, "plan_sha256": "…"} with the same hash. The ordinary release-root signature covers this metadata and every component identity.

The client verifies the original signed JSON before using a typed UI/download view. Mirror URL rewriting does not change the sorted D09 component identity. The typed state is not a substitute for the original signed manifest: independent owner admission verifies the original document and binds its exact raw bytes, plan hash, verifier digest and one-use maintenance authority. Changing the plan, backend, frontend or release identity requires matching reviewed authorization. Initial verifier installation must match the already appointed prerequisite native backend, with retained protected verifier custody. A different executable cannot become the release-root verifier merely by supplying its hash in a plan; later custody changes require a separate approved transition.

Production has no unsigned OS fallback. Updated clients refuse unsigned OS offers, missing owner capability, mismatched plans and uncertain package outcomes. Historical application-only manifests retain their explicitly legacy handling; this must not be confused with OS update permission.

Existing nodes and the no-ISO prerequisite

An older updater cannot grant itself the new protected owner or reinterpret unrecognized metadata as permission. Previously shipped binaries that ignore unknown manifest fields cannot be retroactively made safe by adding a version field. Their prerequisite/bootstrap and feed eligibility must be qualified before offering an integrated OS release.

scripts/os_updater_bootstrap.py prepares an inert root-custody generation from an independently authenticated, machine-specific administrator approval. It checks current executable/inventory pins, candidate source pins, independent administrator identity, unresolved authority and interrupted-generation guards. Its result is PREPARED_NOT_ACTIVATED: it does not install/activate the owner, issue maintenance grants, run APT, restart services or reboot.

scripts/os_updater_activate.py implements the separate, one-shot administrator activation step. It revalidates machine/current/candidate executable pins, protected package inventory, admission and OS input hashes, the fixed verifier, existing D09 and actual OS transaction directories, and externally established package-writer exclusion/manager drain. A durable activation intent makes a lost reply or interruption a reconciliation case, not permission to retry installation. It installs/provisions the owner and requests prerequisite activation through the existing owner tool. Its successful result is D09_PREREQUISITE_ACTIVATED with os_transaction_applied: false; the subsequent OS transaction still needs normal owner admission and apply authority. The preparation helper alone is not that installation, and source inspection is not bootstrap acceptance. Never work around an existing ledger by deleting it, reuse a previous approval, or weaken release-root, grant, preservation, C01 power or clock/epoch checks.

Integration test matrix

Check	Evidence / status
Exact OS component hash/size and changed release identity	Python producer binding tests pass.
Invalid/helper-only/duplicate-key plan refusal	Python producer binding tests pass.
Signed manifest canonical roundtrip, typed state and mirror rewrite	Backend regression passes. Test key only, never a production signature.
Plan/backend/source tamper and stripped-signature refusal	Backend regression passes through normal production verification code.
Owner archive and frontend runtime dependency/schema byte agreement	Actual package producer regression passes. Complete provisioner import closure remains under correction.
Owner inspection → strict wire → client projection	Actual owner/journal/checkpoint roundtrips pass for install/partial failure, postboot and later stale boot, corrupt journal, signed-input/selected-identity drift and legacy inspection.
Legacy/unknown/mismatched capability and partial-dpkg refusal	Client/backend wire tests pass. Missing extension is explicitly unsupported; owner UNKNOWN is recovery even when qualification reports unsupported.
Installed/running/reboot/postboot distinctions and disconnect clearing	Frontend component and actual page/RPC tests pass.
Existing D09 grants, receipts and continuity	Existing disposable lifecycle regression passes.
No-ISO bootstrap controls	Existing unprivileged bootstrap fixtures; no installation acceptance inferred.
Real APT/dpkg and Debian archive-chain validation	Separate executor-lane evidence in the contract.
Immutable artifact, actual boot, installed-node preservation, UI UAT	Separate release gates; not implied by the tests above.

Detailed per-run receipts and current remaining gaps are recorded in the release work area's OS-OTA-STATUS-INTEGRATION-20261103.md integration report.

Fresh 2.1 image update authority

The fresh-image host-policy provisioner disables and masks unattended APT writers, stock nftables flushing and the legacy Archipelago self-update service/timer. It removes only its marked snapshot build-source file, installs Debian runtime sources, disables periodic package mutation and automatic reboot, and records reviewed-signed-D09 as package authority. D09 still requires its existing exclusive package-lock and competing-writer checks; these masks do not exclude an administrator's manual APT command or confer installation authority.

No operator review cadence has been appointed. The image records review_cadence: not-appointed, rather than claiming automatic security patching. A signed reviewed D09 package transaction and its installed/postboot verification remain necessary. Existing nodes are not migrated by the offline helper.