Changelog 2026-07-09 -- $DC selector convention for lib-net.sh/lib-hosts.sh (DOCFIX-151)

No live infrastructure touched -- library-script additions + test harness only. Closes tooling gap register item #1 in docs/dc-dc-deployment-workflow.md, which explicitly BLOCKED the Stage 5 "high reuse" claim (phase-01..08 runbooks reused per-DC) from being operationally true.

Item

1. DOCFIX-151 -- lib_net_select_dc() / lib_hosts_select_dc()

FILES: scripts/lib-net.sh, scripts/lib-hosts.sh, new tests/dc-selector/run-tests.sh.

WHAT: added one opt-in selector function to each library, following the same pattern as the existing $REPO convention (DOCFIX-139/141) -- an explicit, measured selector, never an inferred default.

• lib_net_select_dc() in lib-net.sh: dc0/dc1 are both a no-op (D-101, ADOPTED 2026-07-09, rules DC1 inherits DC0's v4 plane layout UNCHANGED -- so there is deliberately no second copy of the CIDR literals to drift out of sync with the first); dc2 FAILS LOUD (no NetBox-assigned literals exist yet -- gap #3, still open); an unknown token FAILS LOUD.
• lib_hosts_select_dc() in lib-hosts.sh: dc0 is a no-op (the real, enrolled VR0 four-host set); dc1 AND dc2 BOTH fail loud -- unlike the network side, DC1's host inventory does not exist yet either (its node VMs haven't been created by opentofu/modules/node-vm or enrolled in MAAS), so aliasing dc1 to dc0's real hosts would be a silent-reuse bug, not a valid inheritance. This asymmetry (lib_net_select_dc dc1 no-ops, lib_hosts_select_dc dc1 fails) is intentional and is called out in both the changelog and the source comments so a future reader isn't confused by the two libraries behaving differently for the same DC token.

Backward compatible by construction: sourcing either file with no further action is completely unaffected -- every existing script that sources lib-net.sh/lib-hosts.sh today never calls the new functions, so nothing about its behavior changes. This is an additive, opt-in mechanism.

VERIFIED:

• New harness tests/dc-selector/run-tests.sh: 21/21 PASS. Covers: backward compatibility (flat vars unaffected by sourcing alone), dc0/dc1 no-op + dc2/unknown-token/missing-arg fail-loud for the net selector, dc0 no-op + dc1/dc2/unknown-token/missing-arg fail-loud for the hosts selector, error messages cite the correct blocking reason (NetBox gap vs. no-enrollment), and an explicit assertion that the dc1 asymmetry between the two libraries is real and intentional (not a bug).
• Caught and fixed a real bug in the harness itself while writing it: the first draft piped lib_net_select_dc dc2 2>&1 >/dev/null | grep -q "NetBox" under set -o pipefail -- since the selector function's own exit code is 1 (by design, for the fail-loud case), pipefail made the whole pipeline report failure even when grep matched correctly. Fixed by capturing stderr into a variable via command substitution instead of piping through grep, so the assertion checks message content independent of the (expected-nonzero) selector exit code.
• bash scripts/repo-lint.sh: 0 fail, 1 documented legacy WARN (unchanged).
• bash scripts/run-tests-all.sh: confirmed via git stash A/B that the SAME 23 pre-existing failures (all either "jq required" -- not installed on this Windows workstation -- or live juju/cloud-dependent suites like cloud-assert/preflight/tenant-*, none of which touch lib-net.sh/lib-hosts.sh) exist identically with and without this change. dc-selector itself and vault-kv-health (the only other harness that sources either library) both PASS cleanly. This session is running from the operator's workstation, not the vopenstack-jesse jumphost -- no live cloud/juju/MAAS access is expected or required for tonight's prep work (operator instruction, 2026-07-09 evening).

REVERT: git checkout HEAD~ -- scripts/lib-net.sh scripts/lib-hosts.sh && rm -rf tests/dc-selector (safe -- no other script calls either new function yet, so nothing downstream depends on their presence).

Next actionable step

Tooling gap register item #1 CLOSED. Stage 5's runbook (Juju controller + OpenStack bundle, per DC) can now honestly claim the phase-01..08 reuse path IS DC-safe once it's written to call lib_net_select_dc "$DC" / lib_hosts_select_dc "$DC" explicitly -- that call-site wiring is part of authoring the Stage 5 runbook itself (task list item), not this delivery. Gap #3 (NetBox multi-DC import pipeline) is the next dependency: dc2 remains fail-loud in both libraries until it closes.