test(conformance): verify Snap status in Ubuntu VM

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

Author: elezar

.github/workflows/conformance.yml

@@ -101,6 +101,37 @@ jobs:
       checkout-ref: ${{ github.sha }}
     secrets: inherit
 
+  build-sandbox:
+    needs: version
+    permissions:
+      contents: read
+    uses: ./.github/workflows/build-binaries.yml
+    with:
+      package: openshell-sandbox
+      binary: openshell-sandbox
+      triple: x86_64-unknown-linux-musl
+      runner: linux-amd64-cpu8
+      dev-shell: .#devShells.x86_64-linux.musl
+      cargo-version: ${{ needs.version.outputs.cargo }}
+      checkout-ref: ${{ github.sha }}
+    secrets: inherit
+
+  build-snap:
+    needs: [build-cli, build-gateway, build-sandbox]
+    permissions:
+      actions: read
+      contents: read
+      packages: read
+    uses: ./.github/workflows/build-snap.yml
+    with:
+      checkout-ref: ${{ github.sha }}
+      artifact-layout: raw
+      arch: amd64
+      runner: linux-amd64-cpu8
+      cli-artifact-name: openshell-x86_64-unknown-linux-musl
+      gateway-artifact-name: openshell-gateway-x86_64-unknown-linux-gnu
+      supervisor-artifact-name: openshell-sandbox-x86_64-unknown-linux-musl
+
   build-rpm:
     needs: [version, build-cli, build-gateway]
     permissions:
@@ -181,3 +212,56 @@ jobs:
             --provision gateway-rootless-podman \
             --provision openshell-rpm-gateway-upgrade \
             -- /tmp/openshell-conformance run --plan /tmp/conformance-plan.toml
+
+  ubuntu-snap:
+    name: Ubuntu Snap with Docker Snap
+    needs: build-snap
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    permissions:
+      actions: read
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Enable KVM access
+        run: |
+          set -euo pipefail
+          if [[ ! -c /dev/kvm ]]; then
+            echo "::error::The runner did not expose /dev/kvm"
+            exit 1
+          fi
+          sudo chmod 0666 /dev/kvm
+          exec 3<>/dev/kvm
+          exec 3>&-
+
+      - uses: ./.github/actions/setup-nix
+
+      - name: Download Snap artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: snap-linux-amd64
+          path: snap-input
+
+      - name: Install Snap and verify gateway status
+        shell: bash
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          snaps=(snap-input/*.snap)
+          if [[ ${#snaps[@]} -ne 1 ]]; then
+            echo "expected one Snap artifact" >&2
+            printf 'Snap artifacts:\n' >&2
+            printf '  %s\n' snap-input/* >&2
+            exit 1
+          fi
+
+          OPENSHELL_TEST_GUEST_CACHE_DISABLE=1 nix run .#test-guest -- \
+            --distro ubuntu-24-04 \
+            --with snapd \
+            --with docker-snap \
+            --copy "${snaps[0]}:/var/lib/openshell-conformance/candidate/openshell.snap" \
+            --provision openshell-snap \
+            -- true

architecture/build.md

@@ -263,6 +263,12 @@ restart, while the scenario remains responsible for black-box sandbox
 continuity checks. The plan exposes opaque executable paths and timeouts rather
 than driver or package-manager configuration; target setup owns those details.
 
+The conformance workflow also builds a branch Snap for an Ubuntu QEMU guest.
+The guest installs snapd and Docker Snap, installs the unsigned candidate,
+connects its required interfaces, registers the local gateway, and verifies
+`openshell status`. Sandbox smoke conformance remains separate from this
+package-installation check.
+
 ## Python Wheel Packaging
 
 The generated protobuf/gRPC stubs under `python/openshell/_proto/` are gitignored

nix/test-guest/README.md

@@ -70,18 +70,18 @@ The root [`flake.nix`](../../flake.nix) exposes this directory as the `test-gues
 
 ## Supported configurations
 
-| Distro | Docker | Rootless Podman | SELinux | Package format |
-| --- | --- | --- | --- | --- |
-| Ubuntu 24.04 | Yes | No | No | `.deb` |
-| Ubuntu 26.04 | Yes | Yes | No | `.deb` |
-| CentOS Stream 10 | No | No | Yes | `.rpm` |
-| Fedora 44 | No | Yes | Yes | `.rpm` |
-| Rocky Linux 9 | Yes | No | Yes | `.rpm` |
+| Distro | Docker package | Docker Snap | Rootless Podman | SELinux | Package format |
+| --- | --- | --- | --- | --- | --- |
+| Ubuntu 24.04 | Yes | Yes | No | No | `.deb` |
+| Ubuntu 26.04 | Yes | Yes | Yes | No | `.deb` |
+| CentOS Stream 10 | No | No | No | Yes | `.rpm` |
+| Fedora 44 | No | No | Yes | Yes | `.rpm` |
+| Rocky Linux 9 | Yes | No | No | Yes | `.rpm` |
 
 The `snapd` configuration is available for Ubuntu and prepares snapd for
-local Snap lifecycle experiments. It does not install Docker, because the Snap
-gateway reproduction uses the Docker **Snap** and its `docker:docker-daemon`
-interface rather than the host-package Docker configuration.
+local Snap lifecycle experiments. Add `docker-snap` after `snapd` to install
+the Docker **Snap** and model the `docker:docker-daemon` interface used by the
+OpenShell Snap. This is separate from the host-package Docker configuration.
 
 `podman-rootless` configures the explicit rootless Podman guest setup used by
 OpenShell tests. It supports Fedora and Ubuntu 26.04 or later. Ubuntu adds the
@@ -331,27 +331,26 @@ nix run .#test-guest -- \
   -- openshell --version
 ```
 
-## Reproduce Snap gateway startup
+## Verify Snap gateway status
 
-The gateway Snap must be native to the guest architecture. Copy an existing
-Snap artifact and the reproduction script into a prepared Ubuntu guest, then
-run the script as root. It follows the Release Canary ordering exactly: install
-the Snap, connect Docker/log/system interfaces, and immediately query the
-gateway. On each failure it prints snapd and gateway journals.
+The candidate Snap must be native to the guest architecture. The `openshell-snap`
+provisioner installs it, connects the Docker/log/system interfaces, registers the
+local gateway, and waits for `openshell status`, matching the Release Canary
+validation flow.
 
 ```shell
 nix run .#test-guest -- \
   --distro ubuntu-24-04 \
   --with snapd \
+  --with docker-snap \
   --keep \
-  --copy ./openshell_*.snap:/tmp/openshell.snap \
-  --copy ./nix/test-guest/scripts/snap-gateway-repro.sh:/usr/local/bin/snap-gateway-repro \
-  -- sudo /usr/local/bin/snap-gateway-repro /tmp/openshell.snap 10 30
+  --copy ./openshell_*.snap:/var/lib/openshell-conformance/candidate/openshell.snap \
+  --provision openshell-snap \
+  -- true
 ```
 
 `--keep` retains the overlay and serial log when diagnosing a failure. The
-runner prints their location after shutdown. The final `30` accepts automatic
-recovery for up to 30 seconds; omit it to require the canary's immediate check.
+runner prints their location after shutdown.
 
 
 The destination must be an absolute guest path. Use bare octal permission bits
@@ -361,7 +360,8 @@ from `000` through `777` for explicit modes.
 
 ```text
 --distro NAME       Base distro: ubuntu-24-04, ubuntu-26-04, centos, fedora, or rocky
---with NAME         Apply docker, podman-rootless, selinux, or snapd; repeatable
+--with NAME         Apply docker, docker-snap, podman-rootless, selinux, or snapd; repeatable
+--provision NAME    Apply a post-artifact system provisioner; repeatable
 --install PATH      Install a .deb or .rpm package; repeatable
 --copy SRC:DEST[:MODE]
                     Copy a regular file into the guest; use MODE when provided,