From d5330fc9764bc2fad48c946290de5252a01b8f53 Mon Sep 17 00:00:00 2001
From: Rongsong Shen <rshen@shenrs.eu>
Date: Wed, 22 Jul 2026 12:00:05 +0000
Subject: [PATCH] feat(admin-config-tool): wire xceadmin into HA deploy/test
 skills
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

deploy-ha.sh's --build-config path (task 4.2) pointed at
src/xceadmin/.venv/bin/xceadmin, broken by today's meson/nix rewiring
(xceadmin no longer builds a venv there). Fixed to search the meson
build dir (xce.build/build.release/build.dbg), a nix-installed
result/bin, then PATH.

/xce-deploy-ha's SKILL.md never mentioned xceadmin or --build-config
(predates task 4.2) — documented both.

/xce-test-ha's run-ha-soak.sh hard-required a pre-existing cluster.bin
under ha/data/, exit 2 if missing, with no xceadmin path at all. Now
always builds cluster.bin fresh from src/configs/*.yaml via xceadmin
before every soak run, same resolution order as deploy-ha.sh.

ha/data/cluster.bin is no longer a checked-in fixture: removed from
git tracking and gitignored. It was stale relative to xceadmin's
output anyway (different hash from a different, older generation
path) -- the xceadmin-built one matches the known-good golden-fixture
hash from admin-config-tool task 5.4.
---
 .claude/skills/xce-deploy-ha/SKILL.md     |  22 +++++++++++++++++++--
 .claude/skills/xce-test-ha/SKILL.md       |   4 ++--
 .claude/skills/xce-test-ha/run-ha-soak.sh |  23 +++++++++++++++++++++-
 .gitignore                                |   4 ++++
 ha/data/cluster.bin                       | Bin 4768 -> 0 bytes
 src/tools/deploy-ha.sh                    |  22 ++++++++++++++++++---
 6 files changed, 67 insertions(+), 8 deletions(-)
 delete mode 100644 ha/data/cluster.bin

diff --git a/.claude/skills/xce-deploy-ha/SKILL.md b/.claude/skills/xce-deploy-ha/SKILL.md
index 0dfbffec..b51bc069 100644
--- a/.claude/skills/xce-deploy-ha/SKILL.md
+++ b/.claude/skills/xce-deploy-ha/SKILL.md
@@ -32,10 +32,13 @@ disown`) before relying on subagent dispatch for unattended use.
 ## Prerequisites
 
 - Build must be current: run `/xce-build controller` first if binary is stale
-- TLS certs and a `cluster.bin` must exist under `ha/data/`:
+- TLS certs must exist under `ha/data/`:
   - `ha/data/xce.crt`
   - `ha/data/xce.key`
-  - `ha/data/cluster.bin`
+- `ha/data/cluster.bin` — either already present, or built automatically by
+  `deploy-ha.sh` from `src/configs/*.yaml` via `xceadmin` (see Step 3). Run
+  `/xce-build xceadmin` first (or `nix build .#xcecore`) so a built
+  `xceadmin` binary exists for that auto-build path to find.
 
 ## Arguments
 
@@ -78,6 +81,21 @@ PEERS="localhost:9991,localhost:9992,localhost:9993"  # from args
 bash src/tools/deploy-ha.sh "$BINARY" "$DATADIR" "$TOP" "$PEERS"
 ```
 
+Add `--build-config` (anywhere in the args) to force a fresh `cluster.bin`
+rebuild from `src/configs/*.yaml` via `xceadmin` even if `$DATADIR/cluster.bin`
+already exists — useful after editing the example configs:
+
+```bash
+bash src/tools/deploy-ha.sh --build-config "$BINARY" "$DATADIR" "$TOP" "$PEERS"
+```
+
+Without the flag, an existing `$DATADIR/cluster.bin` is left untouched; one
+is auto-built via `xceadmin` only if missing. `xceadmin` is resolved from
+the meson build dir (`xce.build/xceadmin/.venv/bin/xceadmin` by default,
+also checks `build.release`/`build.dbg`), a nix-built `result/bin/xceadmin`,
+or `PATH` — in that order. If none is found, the script errors and tells
+you to run `/xce-build xceadmin` or `nix build .#xcecore` first.
+
 This:
 - Creates `$TOP/certs/`, `$TOP/controller/ctrl-{1..N}/conf`, `$TOP/controller/ctrl-{1..N}/data`, `$TOP/logs/`
 - Copies `xce.crt` and `xce.key` into the shared `$TOP/certs/` dir
diff --git a/.claude/skills/xce-test-ha/SKILL.md b/.claude/skills/xce-test-ha/SKILL.md
index ec8f5430..b03e8923 100644
--- a/.claude/skills/xce-test-ha/SKILL.md
+++ b/.claude/skills/xce-test-ha/SKILL.md
@@ -361,7 +361,7 @@ XCE_HA_ROUNDS=10 XCE_HA_TOP=/tmp/my-ha-run nix develop ./src --command bash "$SK
 | Env var | Meaning | Default |
 |---|---|---|
 | `XCE_HA_TOP` | deploy directory | `/home/claude/tmp/xce-ha-deploy` |
-| `XCE_HA_DATADIR` | config/certs source (`cluster.bin`, `xce.crt`, `xce.key`) | `<repo>/ha/data` |
+| `XCE_HA_DATADIR` | config/certs dir (`xce.crt`, `xce.key`; `cluster.bin` freshly built here by `xceadmin` every run, not a fixture) | `<repo>/ha/data` |
 | `XCE_HA_MODE` | `sequential`, `chaotic`, `force-snapshot`, `factstream`, `array-soak`, or `array-chaos-retry` (its `--flag` wins) | `sequential` |
 | `XCE_HA_BIN` | `xce_controller` binary (point at real-fs release for the gate) | `<repo>/src/xce.build/controller/xce_controller` |
 | `XCE_HA_XT` | `xce_test` binary | `<repo>/src/xce.build/controller/xce_test` |
@@ -385,7 +385,7 @@ XCE_HA_ROUNDS=10 XCE_HA_TOP=/tmp/my-ha-run nix develop ./src --command bash "$SK
 
 ## What the driver does (maps to the requested steps)
 
-1. **Preconditions** — verifies `xce_controller`, `xce_test`, `cluster.bin`, and certs exist.
+1. **Preconditions** — verifies `xce_controller`, `xce_test`, and certs exist; builds `cluster.bin` fresh under `XCE_HA_DATADIR` via `xceadmin` (resolved from the meson build dir, a nix-installed prefix, or `PATH`, in that order — fails with a clear message if none is found; run `/xce-build xceadmin` or `nix build .#xcecore` first).
 2. **Deploy** — `src/tools/deploy-ha.sh` into `XCE_HA_TOP` with nodes
    `ctrl-1=localhost:9991, ctrl-2=localhost:9992, ctrl-3=localhost:9993`,
    using config/certs from `XCE_HA_DATADIR`.
diff --git a/.claude/skills/xce-test-ha/run-ha-soak.sh b/.claude/skills/xce-test-ha/run-ha-soak.sh
index bab90fc7..b6340e14 100755
--- a/.claude/skills/xce-test-ha/run-ha-soak.sh
+++ b/.claude/skills/xce-test-ha/run-ha-soak.sh
@@ -302,7 +302,28 @@ kill_node() {
 # ── Preconditions ────────────────────────────────────────────────────────────
 [ -x "$BIN" ] || { echo "[xce-test-ha] FAIL: controller binary missing: $BIN (run /xce-build controller)" >&2; exit 2; }
 [ -x "$XT" ] || { echo "[xce-test-ha] FAIL: xce_test missing: $XT (run /xce-build controller)" >&2; exit 2; }
-[ -r "$DATADIR/cluster.bin" ] || { echo "[xce-test-ha] FAIL: cluster.bin missing under $DATADIR" >&2; exit 2; }
+# cluster.bin is always (re)built fresh from src/configs/*.yaml via xceadmin
+# -- no pre-created/checked-in cluster.bin fixture is used or kept around
+# any more (ha/data/cluster.bin was removed from git tracking accordingly).
+# Same xceadmin resolution order as deploy-ha.sh's --build-config path
+# (meson build dir, then a nix-installed prefix, then PATH).
+XCEADMIN=""
+for candidate in \
+    "$REPO/src/xce.build/xceadmin/.venv/bin/xceadmin" \
+    "$REPO/src/build.release/xceadmin/.venv/bin/xceadmin" \
+    "$REPO/src/build.dbg/xceadmin/.venv/bin/xceadmin" \
+    "$REPO/src/result/bin/xceadmin" \
+    "$(command -v xceadmin 2>/dev/null || true)"
+do
+    [ -n "$candidate" ] && [ -x "$candidate" ] && { XCEADMIN="$candidate"; break; }
+done
+if [ -z "$XCEADMIN" ]; then
+    echo "[xce-test-ha] FAIL: no xceadmin binary found to build cluster.bin (run /xce-build xceadmin or nix build .#xcecore)" >&2
+    exit 2
+fi
+echo "[xce-test-ha] building cluster.bin under $DATADIR via $XCEADMIN"
+"$XCEADMIN" config build "$REPO/src/configs" -o "$DATADIR/cluster.bin" \
+    || { echo "[xce-test-ha] FAIL: xceadmin config build failed" >&2; exit 2; }
 [ -r "$DATADIR/xce.crt" ] && [ -r "$DATADIR/xce.key" ] || { echo "[xce-test-ha] FAIL: certs missing under $DATADIR" >&2; exit 2; }
 
 trap cleanup EXIT INT TERM
diff --git a/.gitignore b/.gitignore
index 91ccefa5..c03949f0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -33,3 +33,7 @@ ucai-formatter-cache.local.json
 /final_suite_run.log
 /xce-durability-*.log
 /xce-ha-soak*.log
+
+# --- session checkpoint 2026-07-22: cluster.bin is always freshly built by
+# xceadmin now (deploy-ha.sh / run-ha-soak.sh), never a checked-in fixture ---
+ha/data/cluster.bin
diff --git a/ha/data/cluster.bin b/ha/data/cluster.bin
deleted file mode 100644
index 81c33b525f69e7d24e04e95eb0a89d98d563b925..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 4768
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
F1^`D&B8LC~

diff --git a/src/tools/deploy-ha.sh b/src/tools/deploy-ha.sh
index 4753af32..10d2d721 100755
--- a/src/tools/deploy-ha.sh
+++ b/src/tools/deploy-ha.sh
@@ -32,9 +32,25 @@ BINARY=$(realpath "$BINARY")
 # Requirements 8.3/8.4/8.5: rebuild cluster.bin when --build-config is
 # passed or none exists yet; otherwise leave an existing one untouched.
 if [ "$BUILD_CONFIG" = "1" ] || [ ! -f "$DATADIR/cluster.bin" ]; then
-    XCEADMIN="$SCRIPT_DIR/../xceadmin/.venv/bin/xceadmin"
-    if [ ! -x "$XCEADMIN" ]; then
-        echo "Error: $XCEADMIN not found -- run 'xce-build.sh xceadmin' first"
+    # xceadmin is meson-built now (src/xceadmin/meson.build), not a plain
+    # `pip install -e .` venv checked out under src/xceadmin/ -- its build
+    # output lives under whichever meson build dir xce-build.sh's profile
+    # picked, or under a nix-installed prefix's bin/. Try each in turn.
+    XCEADMIN=""
+    for candidate in \
+        "$SCRIPT_DIR/../xce.build/xceadmin/.venv/bin/xceadmin" \
+        "$SCRIPT_DIR/../build.release/xceadmin/.venv/bin/xceadmin" \
+        "$SCRIPT_DIR/../build.dbg/xceadmin/.venv/bin/xceadmin" \
+        "$SCRIPT_DIR/../result/bin/xceadmin" \
+        "$(command -v xceadmin 2>/dev/null || true)"
+    do
+        if [ -n "$candidate" ] && [ -x "$candidate" ]; then
+            XCEADMIN="$candidate"
+            break
+        fi
+    done
+    if [ -z "$XCEADMIN" ]; then
+        echo "Error: xceadmin binary not found -- run 'xce-build.sh xceadmin' or 'nix build .#xcecore' first"
         exit 1
     fi
     "$XCEADMIN" config build "$SCRIPT_DIR/../configs" -o "$DATADIR/cluster.bin"