refactor(test-guest): model OpenShell artifact sources

Signed-off-by: Evan Lezar <elezar@nvidia.com>

Author: elezar

.github/workflows/conformance.yml

@@ -173,11 +173,11 @@ jobs:
             --distro fedora \
             --with podman-rootless \
             --with selinux \
-            --copy "${candidate_cli_package[0]}:/var/lib/openshell-conformance/candidate/openshell.rpm" \
-            --copy "${candidate_gateway_package[0]}:/var/lib/openshell-conformance/candidate/openshell-gateway.rpm" \
+            --copy "${candidate_cli_package[0]}:/var/lib/openshell-test-guest/artifacts/openshell.rpm" \
+            --copy "${candidate_gateway_package[0]}:/var/lib/openshell-test-guest/artifacts/openshell-gateway.rpm" \
             --copy conformance-input/openshell-conformance:/tmp/openshell-conformance \
             --copy nix/test-guest/conformance-plans/gateway-upgrade-restart.toml:/tmp/conformance-plan.toml \
-            --provision openshell-rpm-latest-release \
+            --provision openshell-latest-release-rpm-source \
+            --provision openshell-candidate-rpm-source \
             --provision gateway-podman \
-            --provision openshell-rpm-gateway-upgrade \
             -- /tmp/openshell-conformance run --plan /tmp/conformance-plan.toml

nix/test-guest/README.md

@@ -51,9 +51,12 @@ nix/test-guest/
 └── provisioners/
     └── roles/
         ├── gateway-podman/
-        ├── openshell-development/
-        ├── openshell-rpm/
-        └── openshell-rpm-gateway-upgrade/
+        ├── openshell-candidate-binaries-source/
+        ├── openshell-binaries-contract/
+        ├── openshell-candidate-rpm-source/
+        ├── openshell-rpm-contract/
+        ├── openshell-latest-release-rpm-source/
+        └── openshell-rpm-source/
 ```
 
 - `default.nix` assembles the guest and cache flake apps. It selects host architecture and acceleration, supplies the runtime tools, and exposes distro profiles and configuration playbooks as Nix-store catalogs.
@@ -144,18 +147,25 @@ nix run .#test-guest -- \
 
 Configurations are Ansible playbooks stored under `nix/test-guest/configuration/`. Ansible runs on the host using the VM's ephemeral SSH key and loopback port. The guest does not install Ansible.
 
-Configurations run in the order provided on the command line. OpenShell packages and copied files are installed after all configurations succeed.
-
-`--install` packages and `--copy` files are applied by a dedicated per-run
-Ansible playbook. `--copy` preserves each source file's ordinary permission
-bits. They are not stored in prepared VM cache entries.
+Configurations run in the order provided on the command line. Package and file
+artifacts are applied after all configurations succeed. `--install` installs a
+generic Debian or RPM package directly; `--copy` stages a file at a guest path
+and preserves its ordinary permission bits. Neither is stored in prepared VM
+cache entries.
 
 ## System provisioners
 
-`--provision NAME` applies a target-specific system setup after packages and
+`--provision NAME` applies target-specific system setup after packages and
 copied artifacts are present. Unlike `--with`, provisioners are not cached.
-They can therefore install and start an OpenShell system without coupling the
-prepared guest image to a particular build or driver configuration.
+Stage OpenShell artifacts with `--copy`, then use an ordered source installer
+provisioner to make OpenShell available without coupling the prepared guest
+image to a particular build or driver configuration.
+
+OpenShell source provisioners run in command-line order. The first source
+installs and publishes the initial OpenShell state; later sources only make
+their packages and target-side apply commands available. This lets a scenario
+prepare guest state before initial installation and gives lifecycle actions the
+exact source artifacts they must install later.
 
 Provisioners that support gateway continuity install a target-control command:
 
@@ -182,23 +192,26 @@ timeout_secs = 120
 EOF
 ```
 
-`openshell-development` expects these copied guest paths:
+`openshell-candidate-binaries-source` makes staged raw candidate artifacts available.
+When it is the first OpenShell source provisioner, it installs them into the
+candidate binary OpenShell state. Stage these guest paths with `--copy`:
 
-- `/usr/local/bin/openshell`
-- `/usr/local/bin/openshell-gateway`
-- `/usr/local/lib/openshell-sandbox.tar`
+- `/var/lib/openshell-test-guest/artifacts/openshell`
+- `/var/lib/openshell-test-guest/artifacts/openshell-gateway`
+- `/var/lib/openshell-test-guest/artifacts/openshell-sandbox.tar`
 
-Compose it with `gateway-podman` to configure a rootless Podman
-gateway. For example, run conformance after the provisioners complete:
+Compose the binary candidate source with `gateway-podman` to configure
+a rootless Podman gateway. For example, run conformance after the provisioners
+complete:
 
 ```shell
 nix run .#test-guest -- \
   --distro fedora --with podman-rootless --with selinux \
-  --copy ./openshell:/usr/local/bin/openshell \
+  --copy ./openshell:/var/lib/openshell-test-guest/artifacts/openshell \
   --copy ./openshell-conformance:/usr/local/bin/openshell-conformance \
-  --copy ./openshell-gateway:/usr/local/bin/openshell-gateway \
-  --copy ./openshell-sandbox.tar:/usr/local/lib/openshell-sandbox.tar \
-  --provision openshell-development \
+  --copy ./openshell-gateway:/var/lib/openshell-test-guest/artifacts/openshell-gateway \
+  --copy ./openshell-sandbox.tar:/var/lib/openshell-test-guest/artifacts/openshell-sandbox.tar \
+  --provision openshell-candidate-binaries-source \
   --provision gateway-podman \
   -- /usr/local/bin/openshell-conformance run --plan - <<'EOF'
 version = 1
@@ -214,16 +227,32 @@ timeout_secs = 120
 EOF
 ```
 
-`openshell-rpm` expects OpenShell to have been installed with `--install`. It
-uses the RPM-owned `/usr/bin` binaries and `openshell-gateway` user service,
-without copied development artifacts or a supervisor archive. Compose it with
-`gateway-podman` before an RPM action such as
-`openshell-rpm-gateway-upgrade`.
+`openshell-candidate-rpm-source` makes staged candidate RPMs available and publishes a
+target-side candidate apply command. Stage the CLI and gateway packages as
+`/var/lib/openshell-test-guest/artifacts/openshell.rpm` and
+`/var/lib/openshell-test-guest/artifacts/openshell-gateway.rpm`.
+
+`openshell-latest-release-rpm-source` downloads the latest stable OpenShell GitHub
+release for the guest architecture, stores its versioned RPMs under
+`/var/lib/openshell-conformance/baseline`, and publishes a target-side
+latest-release apply command.
+
+For an upgrade test, order the latest-release source first so it initializes the
+guest, then make the candidate source available for the lifecycle action:
+
+```shell
+--provision openshell-latest-release-rpm-source \
+--provision openshell-candidate-rpm-source \
+--provision gateway-podman
+```
+
+The upgrade plan applies the candidate source and then uses the independent
+gateway-restart action to verify continuity across a subsequent gateway restart.
 
-`openshell-rpm-latest-release` downloads and installs the latest stable
-OpenShell GitHub release for the guest architecture, then publishes the same
-RPM installation contract. Compose it with `gateway-podman` and an
-RPM gateway action when testing an upgrade from the current release.
+`openshell-binaries-contract`, `openshell-rpm-contract`, and
+`openshell-rpm-source` are internal composition roles used by the public source
+provisioners. They are listed for the runner's role resolution but are not
+normal `--provision` entry points.
 
 Versioned plans under `nix/test-guest/conformance-plans/` bind conformance
 scenarios to the stable action-command contracts installed by provisioners.

nix/test-guest/conformance-plans/gateway-upgrade-restart.toml

@@ -15,8 +15,8 @@ scenario = "sandbox-continuity"
 workload_expectation = "reconciled"
 
 [[runs.actions]]
-name = "gateway-upgrade"
-command = "/home/openshell/.local/bin/openshell-test-guest-gateway-upgrade"
+name = "rpm-apply-candidate"
+command = "/home/openshell/.local/bin/openshell-test-guest-rpm-apply-candidate"
 timeout_secs = 120
 
 [[runs.actions]]

nix/test-guest/default.nix

@@ -40,12 +40,13 @@ let
   ];
 
   provisionerRoles = [
-    "openshell-development"
-    "openshell-rpm"
-    "openshell-rpm-latest-release"
+    "openshell-candidate-binaries-source"
+    "openshell-binaries-contract"
+    "openshell-candidate-rpm-source"
+    "openshell-rpm-contract"
+    "openshell-latest-release-rpm-source"
+    "openshell-rpm-source"
     "gateway-podman"
-    "openshell-rpm-gateway-reinstall"
-    "openshell-rpm-gateway-upgrade"
   ];
 
   mkDistroProfile =

nix/test-guest/provisioners/roles/gateway-podman/tasks/main.yml

@@ -22,11 +22,13 @@
       - openshell_gateway_bin is defined
       - openshell_gateway_service is defined
       - openshell_gateway_endpoint is defined
-      - openshell_install_source in ['development', 'rpm']
+      - openshell_install_source in ['binaries', 'rpm']
       - openshell_podman_mode == 'rootless'
     fail_msg: >-
-      gateway-podman requires an earlier OpenShell installation role and a
-      podman-rootless test-guest configuration.
+      gateway-podman requires an earlier OpenShell source provisioner, such as
+      openshell-candidate-binaries-source, openshell-candidate-rpm-source, or
+      openshell-latest-release-rpm-source, and a podman-rootless test-guest
+      configuration.
 
 - name: Resolve the gateway service account
   ansible.builtin.getent:
@@ -39,9 +41,9 @@
     openshell_gateway_service_uid: "{{ ansible_facts.getent_passwd.openshell[1] }}"
     openshell_gateway_service_home: "{{ ansible_facts.getent_passwd.openshell[4] }}"
 
-- name: Configure a development gateway
+- name: Configure a candidate binary gateway
   ansible.builtin.include_tasks: development-gateway.yml
-  when: openshell_install_source == 'development'
+  when: openshell_install_source == 'binaries'
 
 - name: Enable the gateway service account user manager
   ansible.builtin.command:

nix/test-guest/provisioners/roles/openshell-binaries-contract/defaults/main.yml

@@ -0,0 +1,11 @@
+---
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+openshell_binaries_contract_cli_bin: /usr/local/bin/openshell
+openshell_binaries_contract_gateway_bin: /usr/local/bin/openshell-gateway
+openshell_binaries_contract_sandbox_archive: /usr/local/lib/openshell-sandbox.tar
+openshell_binaries_contract_gateway_service: openshell-test-guest-gateway.service
+openshell_binaries_contract_gateway_endpoint: http://127.0.0.1:8080
+openshell_binaries_contract_state_root: /home/openshell/.local/share/openshell-test-guest
+openshell_binaries_contract_supervisor_image: localhost/openshell/supervisor:test-guest

nix/test-guest/provisioners/roles/openshell-binaries-contract/tasks/main.yml

@@ -0,0 +1,32 @@
+---
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+- name: Verify installed candidate binaries
+  ansible.builtin.stat:
+    path: "{{ item }}"
+  loop:
+    - "{{ openshell_binaries_contract_cli_bin }}"
+    - "{{ openshell_binaries_contract_gateway_bin }}"
+    - "{{ openshell_binaries_contract_sandbox_archive }}"
+  register: openshell_binaries_contract_artifacts
+
+- name: Require installed candidate binaries
+  ansible.builtin.assert:
+    that: item.stat.exists
+    fail_msg: "missing required candidate binary: {{ item.item }}"
+  loop: "{{ openshell_binaries_contract_artifacts.results }}"
+  loop_control:
+    label: "{{ item.item }}"
+
+- name: Publish candidate binary OpenShell installation
+  ansible.builtin.set_fact:
+    openshell_install_source: binaries
+    openshell_cli_bin: "{{ openshell_binaries_contract_cli_bin }}"
+    openshell_gateway_bin: "{{ openshell_binaries_contract_gateway_bin }}"
+    openshell_gateway_service: "{{ openshell_binaries_contract_gateway_service }}"
+    openshell_gateway_endpoint: "{{ openshell_binaries_contract_gateway_endpoint }}"
+    openshell_gateway_state_root: "{{ openshell_binaries_contract_state_root }}"
+    openshell_supervisor_source: archive
+    openshell_supervisor_archive: "{{ openshell_binaries_contract_sandbox_archive }}"
+    openshell_supervisor_image: "{{ openshell_binaries_contract_supervisor_image }}"

nix/test-guest/provisioners/roles/openshell-candidate-binaries-source/defaults/main.yml

@@ -0,0 +1,22 @@
+---
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+openshell_binaries_candidate_staging_dir: /var/lib/openshell-test-guest/artifacts
+openshell_binaries_candidate_cli_artifact: "{{ openshell_binaries_candidate_staging_dir }}/openshell"
+openshell_binaries_candidate_gateway_artifact: "{{ openshell_binaries_candidate_staging_dir }}/openshell-gateway"
+openshell_binaries_candidate_sandbox_artifact: "{{ openshell_binaries_candidate_staging_dir }}/openshell-sandbox.tar"
+openshell_binaries_candidate_cli_bin: /usr/local/bin/openshell
+openshell_binaries_candidate_gateway_bin: /usr/local/bin/openshell-gateway
+openshell_binaries_candidate_sandbox_archive: /usr/local/lib/openshell-sandbox.tar
+openshell_binaries_candidate_apply_command: /home/openshell/.local/bin/openshell-test-guest-binaries-apply-candidate
+openshell_binaries_candidate_artifacts:
+  - source: "{{ openshell_binaries_candidate_cli_artifact }}"
+    destination: "{{ openshell_binaries_candidate_cli_bin }}"
+    mode: "0755"
+  - source: "{{ openshell_binaries_candidate_gateway_artifact }}"
+    destination: "{{ openshell_binaries_candidate_gateway_bin }}"
+    mode: "0755"
+  - source: "{{ openshell_binaries_candidate_sandbox_artifact }}"
+    destination: "{{ openshell_binaries_candidate_sandbox_archive }}"
+    mode: "0644"

nix/test-guest/provisioners/roles/openshell-candidate-binaries-source/tasks/main.yml

@@ -0,0 +1,52 @@
+---
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+- name: Verify candidate OpenShell binaries
+  ansible.builtin.stat:
+    path: "{{ item.source }}"
+  loop: "{{ openshell_binaries_candidate_artifacts }}"
+  register: openshell_binaries_candidate_artifact_stats
+
+- name: Require candidate OpenShell binaries
+  ansible.builtin.assert:
+    that: item.stat.exists
+    fail_msg: "missing candidate OpenShell binary: {{ item.item.source }}"
+  loop: "{{ openshell_binaries_candidate_artifact_stats.results }}"
+  loop_control:
+    label: "{{ item.item.source }}"
+
+- name: Create the candidate binary apply command directory
+  ansible.builtin.file:
+    path: "{{ openshell_binaries_candidate_apply_command | dirname }}"
+    state: directory
+    mode: "0700"
+
+- name: Install the candidate binary apply command
+  ansible.builtin.copy:
+    dest: "{{ openshell_binaries_candidate_apply_command }}"
+    mode: "0700"
+    content: |
+      #!/usr/bin/env bash
+      set -Eeuo pipefail
+      {% for artifact in openshell_binaries_candidate_artifacts %}
+      sudo install -D -m {{ artifact.mode }} -- {{ artifact.source | quote }} {{ artifact.destination | quote }}
+      {% endfor %}
+
+- name: Determine whether the candidate binaries are the initial OpenShell source
+  ansible.builtin.set_fact:
+    openshell_binaries_candidate_is_initial: "{{ openshell_install_source is not defined }}"
+
+- name: Install candidate binaries as the initial OpenShell state
+  ansible.builtin.command:
+    cmd: "{{ openshell_binaries_candidate_apply_command }}"
+  when: openshell_binaries_candidate_is_initial
+
+- name: Publish the initial candidate binary OpenShell contract
+  ansible.builtin.include_role:
+    name: openshell-binaries-contract
+  vars:
+    openshell_binaries_contract_cli_bin: "{{ openshell_binaries_candidate_cli_bin }}"
+    openshell_binaries_contract_gateway_bin: "{{ openshell_binaries_candidate_gateway_bin }}"
+    openshell_binaries_contract_sandbox_archive: "{{ openshell_binaries_candidate_sandbox_archive }}"
+  when: openshell_binaries_candidate_is_initial

nix/test-guest/provisioners/roles/openshell-candidate-rpm-source/defaults/main.yml

@@ -0,0 +1,7 @@
+---
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+openshell_rpm_candidate_staging_dir: /var/lib/openshell-test-guest/artifacts
+openshell_rpm_candidate_cli_package: "{{ openshell_rpm_candidate_staging_dir }}/openshell.rpm"
+openshell_rpm_candidate_gateway_package: "{{ openshell_rpm_candidate_staging_dir }}/openshell-gateway.rpm"