feat(config): support portable images and retention recovery

AGENTS.md

@@ -111,17 +111,24 @@ execution machine's role separately, and keep the signing authority elsewhere.
 
 ## Current configuration contract
 
-The development compatibility baseline is ci-fleet
-`689c7c00deb0eebcb25f2284334a9f7168a25575`. Fresh strict configurations require
+The ordinary-CI compatibility baseline is merged ci-fleet
+`840fb9be8a1c69404a5eebcf17855eff13c6c928`. It includes PR157 maintenance
+and unused-pending support. Template acceptance, adopter import and host
+activation remain separate gates. Fresh strict configurations require
 `managed_images` with exact nonzero controller and runner image IDs for each
 selected engine and architecture. Initializer callers must supply architecture
-and both image IDs. Public fixtures use placeholders and non-strict validation.
+and both image scalars. The selected runtime source capability chooses original
+config digests for portable engines and exact opaque Docker IDs for older
+engines. Derived runtime IDs and host binding proof remain outside Git. Public
+fixtures use placeholders and non-strict validation.
 Keep manager-only staging limited to engine-ref changes against a complete
 previous configuration. Preserve incumbent runtime evidence through staging and
 image-policy introduction. Do not weaken next-engine, network or storage gates.
-Both bootstrap revisions require prior integrated target-engine sidecar evidence
-for configured reporting/network capabilities. Stage it with the incumbent
-compatible contract before importing the new manager-staging contract.
+Both bootstrap revisions and ordinary image-enforced upgrades require prior
+integrated target-engine evidence, including controllers without optional blocks.
+Prepare explicit incumbent evidence first, retain active/pending records through
+bootstrap and promote only after runtime verification. Any unused-pending
+cancellation route needs its reviewed supporting engine; never fabricate prior state.
 Managed-image policy changes need explicit updater/manual migration handling
 even when fleet schema remains v3. Keep cache endpoints and bypass hosts in
 protected host-local configuration. See [managed images](docs/MANAGED-IMAGES.md)
@@ -156,3 +163,16 @@ and [APT cache](docs/APT-CACHE.md). Development support is not publication of
 - When reviewing, report missing or inaccurate documentation as a finding.
 - Before declaring the work complete, check updated examples, commands, links, and configuration names. Run applicable documentation checks.
 - When creating or updating a PR, state the documentation impact in its description. In all cases, include the assessment in the completion summary. List updated documents, or explain why no documentation changes are needed. Report any remaining gaps.
+
+## Required delivery order
+
+Complete engine acceptance first, then implement, validate and review the actual
+template specification, import that exact reviewed revision into the adopter,
+then perform authorized deployment. Follow-up issues alone do not complete the
+template or adopter steps. Candidate engines run only on isolated test machines.
+Preserve customized adopter validation, private test inventories, required workflows,
+policy, evidence, delivery configuration, historical compatibility and TEMPLATE_RELEASE
+through a reviewed ownership map. Never replace the private suite with upstream
+local_validate.py or policy tests. Repository suites precede installation rehearsal
+because installed fleet-role markers block validation. A modest rehearsal cannot
+substitute for actual target capacity and resource admission.

README.md

@@ -23,7 +23,7 @@ flowchart LR
 ## Start a private organization configuration
 
 1. Create a **private** repository from this public template.
-2. Review the engine revision and obtain exact controller and runner image IDs
+2. Review the engine revision and obtain controller and runner image scalars
    for each target architecture through the [managed-image procedure](docs/MANAGED-IMAGES.md).
    Build verification needs a separately authorized isolated build host. Clone
    the configuration repository and initialize its first project and controller:
@@ -38,8 +38,8 @@ flowchart LR
      --max-runners 1 \
      --engine-ref REVIEWED_ENGINE_COMMIT_SHA \
      --architecture amd64 \
-     --controller-image-digest sha256:REVIEWED_CONTROLLER_IMAGE_ID \
-     --runner-image-digest sha256:REVIEWED_RUNNER_IMAGE_ID
+     --controller-image-digest sha256:REVIEWED_CONTROLLER_SCALAR \
+     --runner-image-digest sha256:REVIEWED_RUNNER_SCALAR
    ```
 
 3. Edit `fleet.json` to add the organization's real logical mappings.
@@ -147,15 +147,15 @@ Core support for trusted local evidence merged through
 `67beabbddaad73c19f15bc3baa227779bc88dc96`. Its
 [complete engine validation](https://github.com/RandomDevelopment/ci-fleet/issues/135#issuecomment-6200457374)
 passed outside Actions. The development compatibility baseline is now
-`689c7c00deb0eebcb25f2284334a9f7168a25575`. Trusted host acceptance still needs
+`840fb9be8a1c69404a5eebcf17855eff13c6c928`. Trusted host acceptance still needs
 an independent signing authority, compatible managers and tested recovery.
 Earlier standalone tooling is published in [v1.1.0](docs/RELEASE.md#published-v110-release).
 The current systemd suite and managed-image support are unreleased.
 Publication does not activate host policy.
 
 ## Reviewed compatibility and release state
 
-`template-compatibility.json` pins the reviewed embedded template to ci-fleet commit `689c7c00deb0eebcb25f2284334a9f7168a25575`. It records schema and validator/initializer support, optional capabilities, standalone safety checks, and fictional examples pinned to that same engine with placeholder image IDs. `engine-rollout-evidence.json` records active per-controller capability evidence in the shape consumed by that pinned core. New status-reporting, Docker network-policy, and default-bridge fields require prior-state evidence.
+`template-compatibility.json` pins the reviewed embedded template to ci-fleet commit `840fb9be8a1c69404a5eebcf17855eff13c6c928`. It records schema and validator/initializer support, optional capabilities, standalone safety checks, and fictional examples pinned to that same engine with placeholder image IDs. `engine-rollout-evidence.json` records active per-controller capability evidence in the shape consumed by that pinned core. New status-reporting, Docker network-policy, and default-bridge fields require prior-state evidence. Managed-image scalars follow the selected runtime source's capability, with portable config digests kept separate from derived host runtime IDs.
 
 Remove storage-retention admission in an earlier integrated change and verify
 convergence before changing `engine_ref`. The reviewed evidence format has no
@@ -164,12 +164,21 @@ the new engine and daemon inventory before a later re-admission change.
 Adding or retaining admission also requires current and previous controller
 states to be `active` or `drained`. Remove admission when disabling a
 controller, and enable it without admission before a later admission change.
-For any reporting or Docker network capabilities that remain active, use
-exactly two integrated commits:
+For ordinary image-enforced upgrades, including controllers without optional
+reporting/network blocks, use two integrated commits:
 
 1. Keep `fleet.json` and `engine-rollout-evidence.json` on engine A. Add reviewed engine B capability evidence to optional adopter-owned `next-engine-rollout-evidence.json`, using the same schema-version-1 record shape.
 2. Change `engine_ref` to engine B, promote the matching sidecar record to `engine-rollout-evidence.json`, and remove the sidecar when it has no remaining staged records.
 
+Image-free adopters instead follow the separate [manager bootstrap and evidence
+preparation sequence](docs/MANAGED-IMAGES.md#upgrade-an-image-free-adopter). Import
+the actual reviewed template into the adopter before any rollout. The
+[ownership map](docs/UPDATING.md#import-ownership-for-engine-specification-updates)
+preserves private tests, policy, workflows and release records. The selected
+merged engine includes PR157 maintenance and unused-pending preparation support.
+Template validation/review and the adopter import remain separate gates before
+authorized host activation.
+
 The default examples and initializer omit optional fields because their engine capability has not been staged. The [network-policy review fragment](examples/docker-network-policy.json) shows syntax only. Before private activation, replace its RFC 5737 CIDRs with reviewed operational pools and bridge values. Storage retention stays absent by default and has a separate engine-first admission rule. Follow [Docker policy adoption and rollback](docs/UPDATING.md#optional-docker-network-and-storage-policy).
 
 Capacity telemetry is another engine capability. A private adopter may
@@ -179,13 +188,14 @@ update does not select an engine or activate sampling on an adopter host.
 
 Fresh strict configurations require `managed_images`, keyed by full engine
 commit and `amd64` or `arm64`, with different nonzero controller and runner
-`sha256:` image IDs. The initializer requires those inputs and validates them
-before replacing its output. Public example IDs are placeholders and fail
+`sha256:` image scalars. The selected runtime source chooses config-digest or
+legacy opaque-ID semantics. The initializer validates those inputs before
+replacing its output. Public example values are placeholders and fail
 strict validation. Existing image-free adopters must use the
 [manager bootstrap migration](docs/MANAGED-IMAGES.md#upgrade-an-image-free-adopter).
-For configured reporting/network capabilities, integrate reviewed target-engine
-sidecar evidence under the incumbent contract before importing the new staging
-contract. Both bootstrap revisions require it and retain incumbent runtime evidence.
+Import the reviewed specification, then prepare incumbent and target evidence
+through a supporting trusted validator. Both bootstrap revisions require prior
+target evidence for every controller and retain incumbent runtime evidence.
 Importing new files or changing only `engine_ref` cannot complete that migration.
 
 The optional [host-local APT cache](docs/APT-CACHE.md) needs no fleet field.
@@ -308,8 +318,8 @@ size.
 The public ci-fleet engine owns the host installer. Run it from a reviewed,
 immutable ci-fleet checkout on a separately authorized isolated target host.
 This template checkout does not contain the installer. Before bootstrap, follow
-the reviewed [host prerequisites and identity setup](https://github.com/RandomDevelopment/ci-fleet/blob/689c7c00deb0eebcb25f2284334a9f7168a25575/docs/DESIRED-STATE.md#prepare-host-local-identity)
-and [GitHub App setup](https://github.com/RandomDevelopment/ci-fleet/blob/689c7c00deb0eebcb25f2284334a9f7168a25575/docs/GITHUB-APP-SETUP.md).
+the reviewed [host prerequisites and identity setup](https://github.com/RandomDevelopment/ci-fleet/blob/840fb9be8a1c69404a5eebcf17855eff13c6c928/docs/DESIRED-STATE.md#prepare-host-local-identity)
+and [GitHub App setup](https://github.com/RandomDevelopment/ci-fleet/blob/840fb9be8a1c69404a5eebcf17855eff13c6c928/docs/GITHUB-APP-SETUP.md).
 They require Debian 12 or newer, Docker Engine and Compose v2, the documented
 host tools and direct local socket access, Docker disk use below 80%, protected
 host identity and private key, GitHub App/runner-group provisioning, and read-only

docs/LOCAL-VALIDATION.md

@@ -28,8 +28,12 @@ Preparation installs the shared executor and a revision/hash manifest under
 `/usr/local/lib/ci-fleet-validation` and creates a locked execution account and
 protected workspace parent. It adds no daemon, timer or unique fleet state.
 Use a Linux VM or remote prepared worker from macOS or Windows. Shared executor support merged in core [PR #144](https://github.com/RandomDevelopment/ci-fleet/pull/144)
-at `689c7c00deb0eebcb25f2284334a9f7168a25575`. The development configuration-policy baseline now uses that same commit,
-but executor and policy pins remain independent inputs. Pinning an executor
+at `689c7c00deb0eebcb25f2284334a9f7168a25575`. The ordinary-CI
+configuration-policy baseline is `840fb9be8a1c69404a5eebcf17855eff13c6c928`.
+The executor remains independently pinned to the reviewed
+`689c7c00deb0eebcb25f2284334a9f7168a25575` implementation. Engine merge,
+template acceptance and host activation remain separate.
+Executor and policy pins are independent inputs. Pinning an executor
 alone does not adopt the managed-image contract or activate a runtime.
 
 Never execute candidate scripts on an active fleet host or a machine holding
@@ -114,9 +118,10 @@ not a value inferred from candidate files or its remote. Only
 fixtures. Never supply that identity for an adopter. The suite preserves the
 public fixture's origin identity in isolated checkouts so upstream-only tests
 do not silently disappear after cloning from a local path. Fictional upstream
-reference configurations run non-strict checks. Managed-image migration ordering
-applies to strict adopters; fictional upstream pin/image changes are not host
-migrations. Both modes retain optional-capability predecessor and evidence checks. Initialized adopters must pass
+reference configurations use non-strict validation for pin/image updates.
+Strict adopters require managed-image target-evidence promotion. Both modes
+retain reporting/network predecessor and evidence checks when configured.
+Initialized adopters must pass
 strict validation, including transition checks against committed prior fleet,
 active evidence and next-engine evidence when a prior integrated state exists.
 
@@ -161,7 +166,7 @@ The pinned engine checks current state. The independently committed template
 validator enforces the reviewed standalone transition rules and active/next
 evidence, including the standalone next-engine, network and storage safety checks.
 Both checks finish before any candidate initializer or test program executes.
-Fresh initialized adopters need reviewed managed image IDs. Image-free adopter
+Fresh initialized adopters need reviewed managed image scalars. Image-free adopter
 staging needs its complete committed predecessor and retained active/next-engine
 evidence; the all-zero no-prior-state sentinel cannot authorize that migration.
 Use a suite that supports [managed-image migration](MANAGED-IMAGES.md), not the
@@ -279,6 +284,9 @@ SHAs with their complete ancestry. Engine-policy and trusted-suite fetches
 include only their selected commit and its ancestry. Checkouts inherit no
 unrelated branches or tags, and the standalone suite needs no inherited release
 refs. Updater and release-update tests still use their isolated release fixtures.
+Fetches retain received packs with `--keep` instead of unpacking small histories
+into many loose files. This reduces repeated seed-copy and manifest work while
+preserving the selected histories and every verification step.
 
 Before freezing a seed manifest, the harness records the intended source main
 ref and normalizes origins. Suite and public-template source origins name the