archy/docs/target-specific-release-manifests.md

Target-specific OS manifests with shared application artifacts

OS-plan v1 binds one exact package inventory, preservation receipt and boot state. Different targets therefore use separately signed manifests. This does not change the OS execution contract or weaken its inventory checks.

The backend and frontend archive are built once from the same clean annotated release tag. The logical OS component remains os-update-plan.json, as required by native validation and D09 release identity. Its public filename is os-update-plan-<plan-sha256>.json; the corresponding signed manifest is published as manifest-<plan-sha256>.json. Asset names contain no target names or addresses. Keep the mapping from target to plan digest in private operator configuration.

Preparation and test deployment

First prepare and qualify the real target transactions, authenticated Debian archives, preservation observations and boot-state bindings. A cached solver simulation or synthetic transaction is not a production OS plan.

After the shared artifacts exist at releases/vVERSION/, run once per plan:

python3 scripts/prepare-target-release.py --version VERSION --os-plan /private/path/plan.json

This preserves the shared application artifacts and stages only the exact plan and a new unsigned manifest:

releases/vVERSION/os-update-plan-PLAN_SHA256.json
releases/pending/vVERSION/targets/PLAN_SHA256/manifest.json

Existing pending manifests are never overwritten. Preparation grants no installation, signing or publication authority. Use the existing operator signer on the explicit pending path when the signed bytes are required by the guarded OS admission workflow; keep mnemonic material out of agent sessions and files.

Complete combined disposable qualification, then guarded test deployments on the appointed targets, before final release publication. Deployment must use each target's exact plan/manifest and shared app artifact hashes. Preserve existing data, administrator recovery, services and stopped/uninstalled decisions. Record actual installed results separately from source and disposable tests.

ISO and publication

The ISO's common app payload can be built from a selected signed pending target manifest without publishing the feed first:

flock /tmp/opencode/release-heavy.lock bash scripts/build-iso-release.sh --os-plan-sha256 PLAN_SHA256

This selects a signed input; it does not turn the target's OS plan into a generic fresh-install plan. Existing ISO payload, smoke, QEMU and signing gates remain.

After target test deployment and authorized release publication, publish each target's signed manifest with the existing protected verifier/build appointment:

flock /tmp/opencode/release-heavy.lock bash scripts/publish-release-assets.sh VERSION GITEA_REMOTE PLAN_SHA256

All manifest and ISO signature checks precede API mutation. The publisher reuses shared immutable assets, uploads the selected plan, verifies downloads, then uploads and verifies its signed target manifest. A mismatching existing asset is retained and fails verification; it is not replaced silently.

Target manifests are explicit release inputs, not automatic global-feed promotion. An operator-appointed ARCHIPELAGO_UPDATE_URL can select the exact target manifest using the existing native override. Do not point a general feed at an arbitrary target baseline. Source history and public asset verification remain separate from installed and physical acceptance.