Merge branch 'rig-work'

rig/BOOTSTRAP.md

@@ -143,6 +143,10 @@ From here on this machine has curl, so **`make deps` is the short form** for
 every later run and every later copy of this directory. The container path is
 the first-time path.
 
+How the installer itself is tested — machine fixtures, clean containers, a
+Workspace snapshot, a throwaway WSL distro — is in
+[`docs/notes/installer-testing.md`](docs/notes/installer-testing.md).
+
 
 ## Prove the machine before blaming the project
 

rig/Makefile

@@ -70,8 +70,8 @@ tilt:                          ## dev loop  [up|down]                  (default
 # The counterpart to check: that one asks about the MACHINE and never fails,
 # this one asks about RIG and exits 1. Checks are written as the decisions they
 # defend, so a failure names what is being undone.
-selftest:                      ## does rig still do what it says? exits 1 if not
-	bash ctrl/selftest.sh
+selftest:                      ## does rig still do what it says? exits 1 if not  [install]
+	bash ctrl/selftest.sh $(ARGS)
 
 # The one-file versions of rig's tools, one folder per profile, for machines the
 # full rig is not going to. Generated from rig as it is, never edited by hand;

rig/README.md

@@ -110,7 +110,9 @@ cluster name, kube context, ports and paths — the same values every other rig
 script resolves through `ctrl/lib/config.sh` — so a copied and renamed rig, or a
 moved overlay, deploys into its own cluster with no edits.
 
-`make help` lists every target.
+`make help` lists every target. `make selftest` checks rig itself, the installer's
+detection included; `make selftest install` runs the installer on clean containers
+([`docs/notes/installer-testing.md`](docs/notes/installer-testing.md)).
 
 On a machine where Docker really is the only thing installed, `make deps` has
 nothing to download with — see [BOOTSTRAP.md](BOOTSTRAP.md), which runs the

rig/ctrl/deps.sh

@@ -3,7 +3,7 @@
 # Toolchain installer: detect the host, install pinned tools into $OUT_BIN, report
 # host actions it will not perform (no sudo, no apt). Usually via `make deps`.
 # Usage: deps.sh [detect [all] | list | verify [core|dev] | fetch [core|dev] [--to DIR] | install [core|dev]
-#                 | manifest NAME | manifests [--to DIR]]
+#                 | manifest NAME | manifests [--to DIR] | snapshot [DIR]]
 # Notes: docs/notes/deps.md
 
 set -euo pipefail
@@ -27,6 +27,14 @@ abspath() {
 
 OUT_BIN="${OUT_BIN:-$HOME/.local/bin}"
 HOST_ROOT="${HOST_ROOT:-/}"
+# A host fixture (docs/notes/installer-testing.md) is a root whose kernel files stand in
+# for this machine's; UNAME_S does the same for the one fact a file cannot carry.
+if [ "$HOST_ROOT" != / ]; then
+    if [ -r "$HOST_ROOT/proc/meminfo" ]; then MEMINFO="${MEMINFO:-$HOST_ROOT/proc/meminfo}"; fi
+    if [ -r "$HOST_ROOT/proc/sys/vm/overcommit_memory" ]; then
+        OVERCOMMIT_FILE="${OVERCOMMIT_FILE:-$HOST_ROOT/proc/sys/vm/overcommit_memory}"
+    fi
+fi
 DEPS_SOURCE="${DEPS_SOURCE:-upstream}"
 DEPS_ARTIFACTORY_URL="${DEPS_ARTIFACTORY_URL:-}"
 BAKED_BIN="${BAKED_BIN:-/opt/rig/bin}"
@@ -138,7 +146,7 @@ docker_pkg() {
 
 # Windows outside WSL (Git Bash, MSYS, Cygwin) fails confusingly; name it instead.
 require_linux() {
-    case "$(uname -s)" in
+    case "${UNAME_S:-$(uname -s)}" in
         MINGW*|MSYS*|CYGWIN*)
             cat >&2 <<'EOF'
 This has to run inside WSL, not Git Bash / MSYS / Cygwin.
@@ -157,7 +165,7 @@ EOF
     esac
 }
 
-is_wsl() { grep -qi microsoft /proc/version 2>/dev/null; }
+is_wsl() { grep -qi microsoft "$(host_file /proc/version)" 2>/dev/null; }
 
 detect() {
     echo "host"
@@ -765,6 +773,54 @@ fetch_manifests() {  # [--to DIR]
     done
 }
 
+# ── snapshot: this machine as a host fixture ───────────────────────────────
+# Writes what detect reads, cut down to what it needs — never the environment, the
+# home directory or the host name — plus the lines detect prints for it. A fact of
+# one machine: keep it with an overlay or in rig's local/, never in rig itself, and
+# replay it with ctrl/hosttest.sh. Notes: docs/notes/installer-testing.md
+snapshot() {
+    local dest r f
+    dest="$(abspath "${1:-host-snapshot}")"
+    if [ -n "$(ls -A "$dest" 2>/dev/null)" ]; then
+        echo "snapshot: $dest already holds something — pick an empty directory" >&2
+        exit 1
+    fi
+    r="$dest/root"
+    mkdir -p "$r/etc" "$r/proc/sys/vm"
+    f=$(host_file /etc/os-release)
+    if [ -r "$f" ]; then grep -E '^(PRETTY_NAME|NAME|VERSION_ID|ID|ID_LIKE)=' "$f" > "$r/etc/os-release"; fi
+    # The kernel release says WSL or not; the full build string names build hosts.
+    echo "Linux version $(awk '{print $3; exit}' "$(host_file /proc/version)" 2>/dev/null || uname -r)" > "$r/proc/version"
+    grep -E '^(MemTotal|MemAvailable|SwapTotal|SwapFree):' "${MEMINFO:-/proc/meminfo}" > "$r/proc/meminfo"
+    cat "${OVERCOMMIT_FILE:-/proc/sys/vm/overcommit_memory}" > "$r/proc/sys/vm/overcommit_memory" 2>/dev/null || true
+    f=$(host_file /etc/wsl.conf)
+    if [ -r "$f" ]; then
+        # Section headers and the two keys detect reads; a [user] default= names a person.
+        grep -E '^[[:space:]]*(\[[a-z0-9]+\]|systemd[[:space:]]*=|generateResolvConf[[:space:]]*=)' "$f" > "$r/etc/wsl.conf" || true
+    fi
+    f=$(ls "$HOST_ROOT"/mnt/c/Users/*/.wslconfig 2>/dev/null | head -1 || true)
+    if [ -n "$f" ] && grep -qE '^\s*memory\s*=' "$f"; then
+        mkdir -p "$r/mnt/c/Users/user"
+        { echo "[wsl2]"; grep -E '^\s*memory\s*=' "$f"; } > "$r/mnt/c/Users/user/.wslconfig"
+    fi
+    {
+        echo "# for the record; not replayed"
+        echo "arch=$(arch)"
+        echo "glibc=$(ldd --version 2>/dev/null | head -1 | grep -oE '[0-9]+\.[0-9]+$' || echo unknown)"
+        echo "taken=$(date -u +%Y-%m-%d)"
+    } > "$dest/facts.txt"
+    # The lines the fixture itself decides, as detect prints them for it now.
+    {
+        echo "# Written by deps.sh snapshot: what detect said about this machine."
+        env -u MEMINFO -u OVERCOMMIT_FILE HOST_ROOT="$r" bash "./$(basename "${BASH_SOURCE[0]}")" detect all 2>/dev/null \
+            | grep -E '^  (distro|memory|overcommit|systemd|resolv\.conf|wslconfig) |^  ! systemd|^  - resolv\.conf' \
+            | sed 's/^  /+ /'
+    } > "$dest/expect.txt"
+    echo "wrote $dest"
+    (cd "$dest" && find . -type f | sort | sed 's|^\./|  |')
+    echo "keep it with an overlay or in rig's local/, never in rig; replay it with rig's hosttest.sh"
+}
+
 # Baked mode copies binaries already in the image, so it needs no downloader.
 need_downloads() {
     require_amd64
@@ -781,10 +837,12 @@ case "$cmd" in
     manifest)  need_downloads
                fetch_manifest "${1:?usage: $0 manifest <METALLB|CERT_MANAGER|METRICS_SERVER>}" "$MANIFESTS_HOME" ;;
     manifests) need_downloads; fetch_manifests "$@" ;;
+    snapshot)  snapshot "${1:-}" ;;
     *)       echo "usage: $0 [detect [all]|list|verify|fetch|install|manifest NAME|manifests]" >&2
              echo "       install [core|dev]           (default dev)" >&2
              echo "       fetch   [core|dev] [--to DIR]" >&2
              echo "       manifests [--to DIR]         the addons' pinned manifests, verified" >&2
+             echo "       snapshot [DIR]               this machine as a host fixture (no secrets)" >&2
              echo "       OUT_BIN=<dir> overrides the install directory" >&2
              exit 1 ;;
 esac

rig/ctrl/hosttest.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Replay host fixtures: run `deps.sh detect all` against a stand-in machine and check
+# what it must (and must not) say. No docker, no network, no root.
+# Usage: hosttest.sh [FIXTURE_DIR...]    default: tests/hosts/*    exits 1 on a mismatch
+# A fixture is root/ (the files detect reads), expect.txt (+ must appear, - must not,
+# exit N), and an optional env (KEY=value lines). `deps.sh snapshot` writes one.
+# Notes: docs/notes/installer-testing.md
+set -uo pipefail
+cd "$(dirname "$0")"
+
+dirs=("$@")
+if [ ${#dirs[@]} -eq 0 ]; then dirs=(../tests/hosts/*/); fi
+
+rc=0 passed=0 failed=0
+for d in "${dirs[@]}"; do
+    d="${d%/}"
+    if [ ! -f "$d/expect.txt" ]; then
+        echo "  FAIL  $d: no expect.txt — not a host fixture" >&2
+        rc=1; failed=$((failed + 1)); continue
+    fi
+    # Only the fixture's own settings: the caller's HOST_ROOT, MEMINFO or UNAME_S
+    # must not leak into a replay.
+    run=(env -u HOST_ROOT -u MEMINFO -u OVERCOMMIT_FILE -u UNAME_S)
+    if [ -d "$d/root" ]; then run+=(HOST_ROOT="$(cd "$d/root" && pwd)"); fi
+    if [ -f "$d/env" ]; then
+        while IFS= read -r kv; do run+=("$kv"); done < <(grep -vE '^[[:space:]]*(#|$)' "$d/env")
+    fi
+    out=$("${run[@]}" bash ./deps.sh detect all 2>&1)
+    code=$?
+
+    bad=""
+    want_exit=0
+    while IFS= read -r line; do
+        case "$line" in
+            '+ '*)    grep -qF -- "${line#+ }" <<< "$out" || bad+=$'\n'"        missing: ${line#+ }" ;;
+            '- '*)    grep -qF -- "${line#- }" <<< "$out" && bad+=$'\n'"        present: ${line#- }" ;;
+            'exit '*) want_exit="${line#exit }" ;;
+        esac
+    done < <(grep -vE '^[[:space:]]*(#|$)' "$d/expect.txt")
+    if [ "$code" != "$want_exit" ]; then bad+=$'\n'"        exit:    $code, wanted $want_exit"; fi
+
+    if [ -z "$bad" ]; then
+        printf '  ok    %s\n' "$(basename "$d")"
+        passed=$((passed + 1))
+    else
+        printf '  FAIL  %s%s\n' "$(basename "$d")" "$bad"
+        rc=1; failed=$((failed + 1))
+    fi
+done
+
+printf '%d host fixture(s) as expected, %d not\n' "$passed" "$failed"
+exit "$rc"

rig/ctrl/installtest.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# The installer on clean machines: the generated kit (standalone/default/rigdeps.sh) in
+# stock distro containers, as a non-root user, the way it reaches a real machine.
+# Needs docker and the network; takes minutes. Exits 1 on a failure.
+# Usage: installtest.sh [IMAGE...]    default: ubuntu:22.04 debian:trixie-slim, then offline
+# Notes: docs/notes/installer-testing.md
+set -uo pipefail
+cd "$(dirname "$0")"
+
+KIT="$(cd .. && pwd)/standalone/default/rigdeps.sh"
+images=("$@")
+if [ ${#images[@]} -eq 0 ]; then images=(ubuntu:22.04 debian:trixie-slim); fi
+
+rc=0
+passed=0
+check() {   # name, expected, actual
+    if [ "$2" = "$3" ]; then
+        printf '  ok    %s\n' "$1"
+        passed=$((passed + 1))
+    else
+        printf '  FAIL  %s\n        expected: %s\n        got:      %s\n' "$1" "$2" "$3"
+        rc=1
+    fi
+}
+
+if ! docker info >/dev/null 2>&1; then
+    echo "installtest needs a running docker it can reach" >&2
+    exit 1
+fi
+# A stale kit would test yesterday's installer.
+if ! bash ./standalone.sh check >/dev/null 2>&1; then
+    echo "the kit is stale — run: make standalone" >&2
+    exit 1
+fi
+
+for img in "${images[@]}"; do
+    printf '\n%s\n' "$img"
+
+    # A stock image has no curl or wget: the installer must say so and stop, not
+    # half-install. This is the bootstrap paradox BOOTSTRAP.md describes.
+    out=$(docker run --rm -v "$KIT:/kit/rigdeps.sh:ro" "$img" bash /kit/rigdeps.sh install dev 2>&1)
+    code=$?
+    check "bare: install refuses" "1" "$code"
+    check "bare: and names what is missing" "yes" \
+        "$(grep -q 'neither curl nor wget' <<< "$out" && echo yes || echo no)"
+
+    # The one root step a machine owner takes, then everything else as a plain user —
+    # the Workspace's case: no sudo from the installer, tools in ~/.local/bin.
+    out=$(docker run --rm -v "$KIT:/kit/rigdeps.sh:ro" "$img" bash -c '
+        set -e
+        apt-get update -qq >/dev/null
+        DEBIAN_FRONTEND=noninteractive apt-get install -y -qq curl ca-certificates >/dev/null
+        useradd -m t
+        su t -s /bin/bash -c "
+            set -e
+            bash /kit/rigdeps.sh install dev
+            echo ==verify; PATH=\$HOME/.local/bin:\$PATH bash /kit/rigdeps.sh verify dev
+            echo ==manifests; bash /kit/rigdeps.sh manifests --to \$HOME/m
+            echo ==bin; ls \$HOME/.local/bin
+            echo ==m; ls \$HOME/m
+        "' 2>&1)
+    code=$?
+    check "user: install, verify and manifests succeed" "0" "$code"
+    check "user: the dev tier lands in ~/.local/bin" "ctlptl docker-compose jq kind kubectl tilt" \
+        "$(sed -n '/^==bin$/,/^==m$/p' <<< "$out" | grep -vE '^==' | sort | xargs)"
+    check "user: tells them to put it on PATH" "yes" \
+        "$(grep -q 'Put the toolchain on your PATH' <<< "$out" && echo yes || echo no)"
+    check "user: the three manifests, verified" "3" \
+        "$(sed -n '/^==m$/,$p' <<< "$out" | grep -c '\.yaml$')"
+    if [ "$code" -ne 0 ]; then printf '%s\n' "$out" | tail -15 | sed 's/^/        | /'; fi
+done
+
+# The air-gapped path: everything baked into the image, then run with no network at all.
+printf '\noffline (deps-full, --network none)\n'
+tag="rig-installtest:full"
+if docker build -q -f Dockerfile.deps --target deps-full -t "$tag" .. >/dev/null 2>&1; then
+    out=$(docker run --rm --network none --entrypoint bash "$tag" -c '
+        set -e
+        /work/rigdeps.sh install dev
+        /work/rigdeps.sh manifests --to /tmp/m
+        echo ==bin; ls /out/bin
+        echo ==m; ls /tmp/m' 2>&1)
+    code=$?
+    check "offline: install and manifests succeed" "0" "$code"
+    check "offline: the dev tier, from the image" "ctlptl docker-compose jq kind kubectl tilt" \
+        "$(sed -n '/^==bin$/,/^==m$/p' <<< "$out" | grep -vE '^==' | sort | xargs)"
+    check "offline: the three manifests, from the image" "3" \
+        "$(sed -n '/^==m$/,$p' <<< "$out" | grep -c '\.yaml$')"
+    if [ "$code" -ne 0 ]; then printf '%s\n' "$out" | tail -15 | sed 's/^/        | /'; fi
+    docker rmi -f "$tag" >/dev/null 2>&1 || true
+else
+    check "offline: the deps-full image builds" "yes" "no"
+fi
+
+printf '\n'
+if [ "$rc" -eq 0 ]; then
+    printf '%d install checks passed\n' "$passed"
+else
+    printf 'FAILED — the installer did not do on a clean machine what it says\n' >&2
+fi
+exit "$rc"

rig/ctrl/mem.sh

@@ -20,7 +20,7 @@ BUDGET_EXPLICIT=no    # whether --budget was given, which retires the guess belo
 
 # Refuse Git Bash / MSYS / Cygwin and kernels without /proc, with a clear message.
 require_linux() {
-    case "$(uname -s)" in
+    case "${UNAME_S:-$(uname -s)}" in
         MINGW*|MSYS*|CYGWIN*)
             cat >&2 <<'EOF'
 This has to run inside WSL, not Git Bash / MSYS / Cygwin.

rig/ctrl/selftest.sh

@@ -1,11 +1,14 @@
 #!/usr/bin/env bash
 # What rig has settled, written down as assertions: one decision per check.
 # No cluster, docker or network; exits 1 on failure (unlike `make check`).
-# Usage: make selftest   (or: bash ctrl/selftest.sh)
+# Usage: make selftest [install]   (or: bash ctrl/selftest.sh [install])
+#   install: the installer in clean containers — docker, network, minutes (installtest.sh)
 # Notes: docs/notes/selftest.md
 set -uo pipefail          # NOT -e: one failing check must not abort the rest
 cd "$(dirname "$0")"
 
+if [ "${1:-}" = install ]; then shift; exec bash ./installtest.sh "$@"; fi
+
 source ./lib/config.sh
 
 rc=0
@@ -316,6 +319,26 @@ check "✖ S7 no house path or host name in rig" "0" \
     "$(cd .. && grep -rIlE "$HOUSE_PAT" . --exclude-dir=def --exclude-dir=local --exclude=STALE.md 2>/dev/null | wc -l)"
 
 
+note "the installer detects what each kind of machine needs"
+# Host fixtures (tests/hosts/): a stand-in root per machine, detect run against it. The
+# expensive machines — the Workspace, a WSL install — are exactly the ones you cannot
+# rebuild to test on, so their shapes are replayed here instead.
+out="$(bash ./hosttest.sh 2>&1)"
+check "every host fixture detects as expected" "$(ls -d ../tests/hosts/*/ | wc -l) host fixture(s) as expected, 0 not" \
+    "$(tail -1 <<< "$out")"
+# A snapshot is carried off a machine that may be someone else's: it must hold only the
+# files detect reads, and nothing that names the machine or the person.
+SN="$TMP/snapshot/s"
+bash ./deps.sh snapshot "$SN" >/dev/null 2>&1
+check "snapshot writes only what detect reads" \
+    "expect.txt facts.txt root/etc/os-release root/proc/meminfo root/proc/sys/vm/overcommit_memory root/proc/version" \
+    "$( (cd "$SN" 2>/dev/null && find . -type f | sed 's|^\./||' | grep -vE '^root/(etc/wsl\.conf|mnt/c/Users/user/\.wslconfig)$' | sort | xargs) )"
+check "snapshot names no host, user or home" "0" \
+    "$(grep -rlE "$(hostname)|${USER:-nobody}|/home/" "$SN" 2>/dev/null | wc -l)"
+check "and replays as the machine it was taken on" "yes" \
+    "$(bash ./hosttest.sh "$SN" >/dev/null 2>&1 && echo yes || echo no)"
+
+
 note "the dev loop parses — needs tilt and kubectl, not a cluster"
 # A throwaway kubeconfig with kind-named entries (Tilt trusts kind contexts) and a
 # kubectl that swallows `apply`: the Tiltfile evaluates for real, nothing is contacted.

rig/docs/notes/deps.md

@@ -160,3 +160,7 @@ Read the command, THEN shift — and shift only if there is something there. A b
 ## manifest / manifests
 
 The manifests rig's own addons apply are pinned in versions.env like the binaries, and fetched by the same code: `resolve_url` for the source (upstream, artifactory, baked), `verify` for the sum. `manifest <NAME>` makes one present in `vendor/manifests/` (rig's folder, gitignored) and prints only its path, so an addon can apply it; a cached copy whose sum still matches is reused, one that does not is fetched again. `manifests [--to DIR]` fetches all three, which is how the deps-full image bakes them and how an offline machine is given them. Why the addons stopped applying URLs is in versions.md.
+
+## snapshot, and the test hooks
+
+`snapshot [DIR]` writes this machine as a host fixture: the files detect reads, cut down to what it needs (no environment, home or host name), plus the lines detect printed for it. It is in the kit, so the Workspace needs nothing else to take one. Detection reads through `HOST_ROOT`, `MEMINFO`, `OVERCOMMIT_FILE` and `UNAME_S`, so a fixture can stand in for a machine; with `HOST_ROOT` set, the first two default into it. How the fixtures, the clean-container run and the WSL recipe fit together: [installer-testing.md](installer-testing.md).

rig/docs/notes/installer-testing.md

@@ -0,0 +1,118 @@
+# Testing the installer
+
+## Why it needs its own tiers
+
+The installer is `ctrl/deps.sh`. What reaches a machine is its generated one-file kit,
+`standalone/default/rigdeps.sh`: the AWS Workspace gets that file and nothing else. The
+machines it must work on are exactly the ones you cannot rebuild to test on:
+- the Workspace cannot be recreated;
+- redoing WSL means rebuilding the machine you work on every day;
+- a fresh install happens once per machine, so a bug there is found by the one person least
+  able to diagnose it.
+
+So each tier is cheaper than the one after it, and each catches what the one before cannot.
+
+| tier | runs | needs | proves | cannot prove |
+| --- | --- | --- | --- | --- |
+| 1 host fixtures | every `make selftest` | nothing | detection reads each kind of machine right: distro, WSL, memory, overcommit, systemd, `.wslconfig`, the Git Bash refusal | that anything installs |
+| 2 clean containers | `make selftest install` | docker, network, ~1–2 min | a stock Ubuntu 22.04 / Debian refuses cleanly when bare, then installs, verifies and fetches the manifests **as a non-root user**; the offline image works with no network | WSL, the Workspace's own policies, docker itself |
+| 3a Workspace snapshot | by hand, when the Workspace changes | the kit, once, on the Workspace | tier 1 replays the real Workspace's shape from then on | its install (that is tier 2's Ubuntu 22.04 plus the real run) |
+| 3b WSL throwaway | by hand, before teaching or after a WSL change | a Windows machine | the whole path in a real WSL distro that is not your daily one | Windows-side setup (not built, see below) |
+
+## Tier 1 — host fixtures
+
+`tests/hosts/<name>/` is a stand-in machine:
+
+```
+root/        the files detect reads: etc/os-release, proc/version, proc/meminfo,
+             proc/sys/vm/overcommit_memory, etc/wsl.conf, mnt/c/Users/<u>/.wslconfig
+env          optional KEY=value lines, e.g. UNAME_S=MINGW64_NT-10.0 (a fact no file carries)
+expect.txt   "+ text" must appear, "- text" must not, "exit N" (default 0)
+```
+
+`bash ctrl/hosttest.sh [DIR...]` runs `deps.sh detect all` with `HOST_ROOT` pointing at the
+root (which also sets `MEMINFO` and `OVERCOMMIT_FILE`) and checks the lines. Only host facts are
+asserted: docker, PATH and the filesystem belong to the machine running the test.
+
+Shipped: `ubuntu-22.04` (the Workspace's shape: 7.6 GB, overcommit 1, swap in use),
+`debian-trixie`, `wsl-bare` (systemd off, no `.wslconfig`), `wsl-ready`, `git-bash`. To add a
+case, add a folder. Anything true of one real machine goes with an overlay or in `local/`,
+never here.
+
+## Tier 2 — clean containers
+
+`make selftest install` (`ctrl/installtest.sh [IMAGE...]`). It first refuses to run on a stale
+kit, then, for `ubuntu:22.04` and `debian:trixie-slim`:
+1. **bare:** `install` must refuse and name curl/wget — the bootstrap paradox;
+2. **after the one root step** (`apt-get install curl ca-certificates`), as a plain user:
+   `install dev`, `verify dev`, `manifests --to ~/m`. The dev tier lands in `~/.local/bin`,
+   the PATH advice is printed, and all three manifests are there, verified.
+
+Then it builds `deps-full` and runs `install` + `manifests` with `--network none`: the
+air-gapped path. Measured 2026-09-22: 15 checks, 75 s.
+
+## Tier 3a — the Workspace snapshot
+
+```bash
+bash rigdeps.sh snapshot ~/rig-host-snapshot     # on the Workspace; the kit is enough
+```
+
+It writes the files detect reads, cut down to what detect needs:
+- the `os-release` name fields;
+- the kernel release;
+- four meminfo numbers;
+- the overcommit value;
+- `wsl.conf`'s section headers and its two keys;
+- a `.wslconfig` memory line, under the neutral user `user`;
+- `facts.txt` (arch, glibc, date);
+- `expect.txt`, the lines detect printed for it.
+
+No environment, no home, no host name: selftest asserts both the file list and the absence
+of those.
+
+Carry the folder back, keep it in `local/hosts/workspace/` (gitignored) or with the overlay,
+and from then on:
+
+```bash
+bash ctrl/hosttest.sh local/hosts/workspace
+```
+
+Add your own `+`/`-` lines to its `expect.txt` for what must stay true there. Take a new one
+when the Workspace changes (an image update, a memory change).
+
+## Tier 3b — WSL, in a throwaway distro
+
+Never the distro you work in: a second one, imported from a rootfs, removed afterwards. WSL
+runs every distro in one VM, so this changes nothing in yours — **except that
+`wsl --shutdown` stops both**; don't run it while you work. From PowerShell:
+
+```powershell
+# a pristine Ubuntu 22.04 rootfs: from cloud-images.ubuntu.com/wsl/, or
+# `wsl --export Ubuntu-22.04 ubuntu-22.04.tar` of an untouched install kept for this
+wsl --import rig-test C:\wsl\rig-test .\ubuntu-22.04.tar
+wsl -d rig-test -u root -- bash -c "apt-get update && apt-get install -y curl ca-certificates && useradd -m t"
+copy .\rigdeps.sh \\wsl$\rig-test\home\t\
+wsl -d rig-test -u t -- bash -lc "cd ~ && bash rigdeps.sh detect all && bash rigdeps.sh install dev && bash rigdeps.sh verify dev && bash rigdeps.sh snapshot ~/snap"
+# carry \\wsl$\rig-test\home\t\snap back as a fixture, then:
+wsl --unregister rig-test
+```
+
+What to look for: detect says `WSL`, and names the systemd and `.wslconfig` steps; install and
+verify pass. This is the tier to run before teaching Windows users, or after a WSL update.
+Nothing in rig automates it: a throwaway-distro harness is the multi-distro machinery that
+was removed on purpose.
+
+## Not built: a Windows-host installer
+
+Everything above starts inside Linux. The Windows side — enabling WSL, getting a distro, and
+the tools a Windows user needs before rig (python and the like) — is still manual, in the
+README's "Starting from plain Windows". A Windows-host installer is recorded for the future,
+for teaching; it would need tier 3b's approach, a machine that is not your daily one, to test.
+
+## The hooks the tiers rely on
+
+`deps.sh` reads host files through `HOST_ROOT` (`host_file()`), memory through `MEMINFO`, the
+overcommit mode through `OVERCOMMIT_FILE`, the kernel name through `UNAME_S`, and WSL through
+`host_file /proc/version`. With `HOST_ROOT` set, `MEMINFO` and `OVERCOMMIT_FILE` default into
+it. The deps image relies on `HOST_ROOT=/host` for the same reason: a container asking about
+its host.

rig/docs/notes/selftest.md

@@ -89,3 +89,11 @@ The offline example profile must install rig's addons with no network. Each addo
 ## the examples are overlays that work as shipped
 
 `examples/` is what real overlays are copied from, so every addon there must parse, and every DAG must be valid Python. What they deploy is exercised by the parse checks above, not here.
+
+## the installer detects what each kind of machine needs
+
+The machines the installer must work on — the Workspace, a WSL install — are the ones you cannot rebuild to test on, so their shapes are replayed from fixtures (`tests/hosts/`, run by `hosttest.sh`). And a snapshot is carried off a machine that may be someone else's, so it must hold only what detect reads and nothing that names the machine or the person; that, and that it replays as the machine it was taken on, is asserted on a snapshot of the machine running the test.
+
+## make selftest install
+
+The installer on clean machines: stock Ubuntu 22.04 and Debian containers, the generated kit, a plain user; then the offline image with no network. Docker, network and a minute or two, so it is its own verb rather than part of the cheap run. See [installer-testing.md](installer-testing.md).

rig/standalone/default/Makefile

@@ -16,7 +16,7 @@ endif
 help:                          ## list targets
 	@grep -hE '^[a-z][a-z-]*:.*?##' $(MAKEFILE_LIST) | sed 's/:.*##/\t/' | expand -t16
 
-deps:                          ## rigdeps.sh  [detect|list|verify|fetch|install|manifest|manifests]  (default detect)
+deps:                          ## rigdeps.sh  [detect|list|verify|fetch|install|manifest|manifests|snapshot]  (default detect)
 	bash $(HERE)rigdeps.sh $(or $(ARGS),detect)
 
 mem:                           ## rigmini.sh  [status|push|all|backup|restore]  (default status)

rig/standalone/default/rigdeps.sh

@@ -128,7 +128,7 @@ load_config() {
 # Toolchain installer: detect the host, install pinned tools into $OUT_BIN, report
 # host actions it will not perform (no sudo, no apt). Usually via `make deps`.
 # Usage: deps.sh [detect [all] | list | verify [core|dev] | fetch [core|dev] [--to DIR] | install [core|dev]
-#                 | manifest NAME | manifests [--to DIR]]
+#                 | manifest NAME | manifests [--to DIR] | snapshot [DIR]]
 # Notes: docs/notes/deps.md
 
 set -euo pipefail
@@ -152,6 +152,14 @@ abspath() {
 
 OUT_BIN="${OUT_BIN:-$HOME/.local/bin}"
 HOST_ROOT="${HOST_ROOT:-/}"
+# A host fixture (docs/notes/installer-testing.md) is a root whose kernel files stand in
+# for this machine's; UNAME_S does the same for the one fact a file cannot carry.
+if [ "$HOST_ROOT" != / ]; then
+    if [ -r "$HOST_ROOT/proc/meminfo" ]; then MEMINFO="${MEMINFO:-$HOST_ROOT/proc/meminfo}"; fi
+    if [ -r "$HOST_ROOT/proc/sys/vm/overcommit_memory" ]; then
+        OVERCOMMIT_FILE="${OVERCOMMIT_FILE:-$HOST_ROOT/proc/sys/vm/overcommit_memory}"
+    fi
+fi
 DEPS_SOURCE="${DEPS_SOURCE:-upstream}"
 DEPS_ARTIFACTORY_URL="${DEPS_ARTIFACTORY_URL:-}"
 BAKED_BIN="${BAKED_BIN:-/opt/rig/bin}"
@@ -263,7 +271,7 @@ docker_pkg() {
 
 # Windows outside WSL (Git Bash, MSYS, Cygwin) fails confusingly; name it instead.
 require_linux() {
-    case "$(uname -s)" in
+    case "${UNAME_S:-$(uname -s)}" in
         MINGW*|MSYS*|CYGWIN*)
             cat >&2 <<'EOF'
 This has to run inside WSL, not Git Bash / MSYS / Cygwin.
@@ -282,7 +290,7 @@ EOF
     esac
 }
 
-is_wsl() { grep -qi microsoft /proc/version 2>/dev/null; }
+is_wsl() { grep -qi microsoft "$(host_file /proc/version)" 2>/dev/null; }
 
 detect() {
     echo "host"
@@ -890,6 +898,54 @@ fetch_manifests() {  # [--to DIR]
     done
 }
 
+# ── snapshot: this machine as a host fixture ───────────────────────────────
+# Writes what detect reads, cut down to what it needs — never the environment, the
+# home directory or the host name — plus the lines detect prints for it. A fact of
+# one machine: keep it with an overlay or in rig's local/, never in rig itself, and
+# replay it with ctrl/hosttest.sh. Notes: docs/notes/installer-testing.md
+snapshot() {
+    local dest r f
+    dest="$(abspath "${1:-host-snapshot}")"
+    if [ -n "$(ls -A "$dest" 2>/dev/null)" ]; then
+        echo "snapshot: $dest already holds something — pick an empty directory" >&2
+        exit 1
+    fi
+    r="$dest/root"
+    mkdir -p "$r/etc" "$r/proc/sys/vm"
+    f=$(host_file /etc/os-release)
+    if [ -r "$f" ]; then grep -E '^(PRETTY_NAME|NAME|VERSION_ID|ID|ID_LIKE)=' "$f" > "$r/etc/os-release"; fi
+    # The kernel release says WSL or not; the full build string names build hosts.
+    echo "Linux version $(awk '{print $3; exit}' "$(host_file /proc/version)" 2>/dev/null || uname -r)" > "$r/proc/version"
+    grep -E '^(MemTotal|MemAvailable|SwapTotal|SwapFree):' "${MEMINFO:-/proc/meminfo}" > "$r/proc/meminfo"
+    cat "${OVERCOMMIT_FILE:-/proc/sys/vm/overcommit_memory}" > "$r/proc/sys/vm/overcommit_memory" 2>/dev/null || true
+    f=$(host_file /etc/wsl.conf)
+    if [ -r "$f" ]; then
+        # Section headers and the two keys detect reads; a [user] default= names a person.
+        grep -E '^[[:space:]]*(\[[a-z0-9]+\]|systemd[[:space:]]*=|generateResolvConf[[:space:]]*=)' "$f" > "$r/etc/wsl.conf" || true
+    fi
+    f=$(ls "$HOST_ROOT"/mnt/c/Users/*/.wslconfig 2>/dev/null | head -1 || true)
+    if [ -n "$f" ] && grep -qE '^\s*memory\s*=' "$f"; then
+        mkdir -p "$r/mnt/c/Users/user"
+        { echo "[wsl2]"; grep -E '^\s*memory\s*=' "$f"; } > "$r/mnt/c/Users/user/.wslconfig"
+    fi
+    {
+        echo "# for the record; not replayed"
+        echo "arch=$(arch)"
+        echo "glibc=$(ldd --version 2>/dev/null | head -1 | grep -oE '[0-9]+\.[0-9]+$' || echo unknown)"
+        echo "taken=$(date -u +%Y-%m-%d)"
+    } > "$dest/facts.txt"
+    # The lines the fixture itself decides, as detect prints them for it now.
+    {
+        echo "# Written by deps.sh snapshot: what detect said about this machine."
+        env -u MEMINFO -u OVERCOMMIT_FILE HOST_ROOT="$r" bash "./$(basename "${BASH_SOURCE[0]}")" detect all 2>/dev/null \
+            | grep -E '^  (distro|memory|overcommit|systemd|resolv\.conf|wslconfig) |^  ! systemd|^  - resolv\.conf' \
+            | sed 's/^  /+ /'
+    } > "$dest/expect.txt"
+    echo "wrote $dest"
+    (cd "$dest" && find . -type f | sort | sed 's|^\./|  |')
+    echo "keep it with an overlay or in rig's local/, never in rig; replay it with rig's hosttest.sh"
+}
+
 # Baked mode copies binaries already in the image, so it needs no downloader.
 need_downloads() {
     require_amd64
@@ -906,10 +962,12 @@ case "$cmd" in
     manifest)  need_downloads
                fetch_manifest "${1:?usage: $0 manifest <METALLB|CERT_MANAGER|METRICS_SERVER>}" "$MANIFESTS_HOME" ;;
     manifests) need_downloads; fetch_manifests "$@" ;;
+    snapshot)  snapshot "${1:-}" ;;
     *)       echo "usage: $0 [detect [all]|list|verify|fetch|install|manifest NAME|manifests]" >&2
              echo "       install [core|dev]           (default dev)" >&2
              echo "       fetch   [core|dev] [--to DIR]" >&2
              echo "       manifests [--to DIR]         the addons' pinned manifests, verified" >&2
+             echo "       snapshot [DIR]               this machine as a host fixture (no secrets)" >&2
              echo "       OUT_BIN=<dir> overrides the install directory" >&2
              exit 1 ;;
 esac

rig/standalone/default/rigmini.sh

@@ -145,7 +145,7 @@ BUDGET_EXPLICIT=no    # whether --budget was given, which retires the guess belo
 
 # Refuse Git Bash / MSYS / Cygwin and kernels without /proc, with a clear message.
 require_linux() {
-    case "$(uname -s)" in
+    case "${UNAME_S:-$(uname -s)}" in
         MINGW*|MSYS*|CYGWIN*)
             cat >&2 <<'EOF'
 This has to run inside WSL, not Git Bash / MSYS / Cygwin.

rig/tests/hosts/debian-trixie/expect.txt

@@ -0,0 +1,7 @@
+# A plain native Debian with memory to spare and no swap.
++ distro      Debian GNU/Linux 13 (trixie)
++ native linux
++ memory      15861 MB total, 11264 MB available
++ overcommit  0 heuristic
+- in swap
+- WSL

rig/tests/hosts/debian-trixie/root/etc/os-release

@@ -0,0 +1,4 @@
+PRETTY_NAME="Debian GNU/Linux 13 (trixie)"
+NAME="Debian GNU/Linux"
+VERSION_ID="13"
+ID=debian

rig/tests/hosts/debian-trixie/root/proc/meminfo

@@ -0,0 +1,4 @@
+MemTotal:       16241664 kB
+MemAvailable:   11534336 kB
+SwapTotal:             0 kB
+SwapFree:              0 kB

rig/tests/hosts/debian-trixie/root/proc/sys/vm/overcommit_memory

@@ -0,0 +1 @@
+0

rig/tests/hosts/debian-trixie/root/proc/version

@@ -0,0 +1 @@
+Linux version 6.12.48+deb13-amd64

rig/tests/hosts/git-bash/env

@@ -0,0 +1 @@
+UNAME_S=MINGW64_NT-10.0-19045

rig/tests/hosts/git-bash/expect.txt

@@ -0,0 +1,5 @@
+# Git Bash on Windows: refused before anything runs, pointing at WSL.
+exit 1
++ This has to run inside WSL, not Git Bash / MSYS / Cygwin.
++ wsl --install
+- distro

rig/tests/hosts/ubuntu-22.04/expect.txt

@@ -0,0 +1,7 @@
+# A managed Ubuntu 22.04 machine: native, tight on memory, already swapping.
++ distro      Ubuntu 22.04.5 LTS
++ native linux
++ memory      7680 MB total, 1843 MB available, 4096 MB in swap
++ overcommit  1 always
+- WSL
+- systemd not enabled

rig/tests/hosts/ubuntu-22.04/root/etc/os-release

@@ -0,0 +1,5 @@
+PRETTY_NAME="Ubuntu 22.04.5 LTS"
+NAME="Ubuntu"
+VERSION_ID="22.04"
+ID=ubuntu
+ID_LIKE=debian

rig/tests/hosts/ubuntu-22.04/root/proc/meminfo

@@ -0,0 +1,4 @@
+MemTotal:        7864320 kB
+MemAvailable:    1887436 kB
+SwapTotal:       8388608 kB
+SwapFree:        4194304 kB

rig/tests/hosts/ubuntu-22.04/root/proc/sys/vm/overcommit_memory

@@ -0,0 +1 @@
+1

rig/tests/hosts/ubuntu-22.04/root/proc/version

@@ -0,0 +1 @@
+Linux version 6.8.0-1030-aws

rig/tests/hosts/wsl-bare/expect.txt

@@ -0,0 +1,7 @@
+# Fresh WSL: systemd off, resolv.conf generated, no .wslconfig — all three said.
++ Ubuntu 22.04.5 LTS  amd64, WSL
++ ! systemd not enabled in /etc/wsl.conf
++ - resolv.conf is WSL-generated
++ Enable systemd — add to /etc/wsl.conf:
++ Cap/raise the WSL VM memory
+- native linux

rig/tests/hosts/wsl-bare/root/etc/os-release

@@ -0,0 +1,4 @@
+PRETTY_NAME="Ubuntu 22.04.5 LTS"
+NAME="Ubuntu"
+VERSION_ID="22.04"
+ID=ubuntu

rig/tests/hosts/wsl-bare/root/proc/meminfo

@@ -0,0 +1,4 @@
+MemTotal:        8055020 kB
+MemAvailable:    7340032 kB
+SwapTotal:       2097152 kB
+SwapFree:        2097152 kB

rig/tests/hosts/wsl-bare/root/proc/version

@@ -0,0 +1 @@
+Linux version 5.15.167.4-microsoft-standard-WSL2

rig/tests/hosts/wsl-ready/expect.txt

@@ -0,0 +1,7 @@
+# WSL set up as BOOTSTRAP says: systemd on, resolv.conf pinned, VM memory set.
++ amd64, WSL
++ systemd     enabled in wsl.conf
++ resolv.conf pinned (generateResolvConf=false)
++ wslconfig   memory set: memory=12GB
+- systemd not enabled
+- Cap/raise the WSL VM memory

rig/tests/hosts/wsl-ready/root/etc/os-release

@@ -0,0 +1,4 @@
+PRETTY_NAME="Ubuntu 22.04.5 LTS"
+NAME="Ubuntu"
+VERSION_ID="22.04"
+ID=ubuntu

rig/tests/hosts/wsl-ready/root/etc/wsl.conf

@@ -0,0 +1,5 @@
+[boot]
+systemd=true
+
+[network]
+generateResolvConf=false

rig/tests/hosts/wsl-ready/root/mnt/c/Users/user/.wslconfig

@@ -0,0 +1,2 @@
+[wsl2]
+memory=12GB

rig/tests/hosts/wsl-ready/root/proc/meminfo

@@ -0,0 +1,4 @@
+MemTotal:        8055020 kB
+MemAvailable:    7340032 kB
+SwapTotal:       2097152 kB
+SwapFree:        2097152 kB

rig/tests/hosts/wsl-ready/root/proc/version

@@ -0,0 +1 @@
+Linux version 5.15.167.4-microsoft-standard-WSL2