Pass 2 -- W2.4: module decomposition (which tools become procedure-modules; the IaC/procedure layering)

Worker: W2.4 (Phase 2, container-layer-elimination pass). Date: 2026-08-09. Scope: READ-ONLY. Builds on the L0-L5 layer model adopted at Phase 1 (pass1-w4-module-planning.md, consolidated in pass1-admin-report.md Section 5) and the Option-1-confirmed target (pass0-admin-report.md Section 7a). Inputs read in full: SCOPE-AND-EXECUTION-PLAN.md, pass0-admin-report.md, pass1-admin-report.md, pass1-w4-module-planning.md, docs/tool-index.md, plus a live inventory of scripts/, tests/*/, and script headers taken this session (cited by path throughout). D-140 (L4-as-IaC) is PINNED, not ruled -- treated as a future trigger, not folded into this decomposition (per CLAUDE.md instruction and pass1-w4-module-planning.md Section 4 item 6).

1. Method

Every script under scripts/ matching the task's deploy-path filter (preflight, cloud-assert, phase-NN-*, lib-*, dc-*, maas-*, site-*, carve-*, geneve-encap-assert, opentofu-validate) was read (header + role), placed on the L0-L5 model, classed as IaC / procedure / library / gate, and checked against tests/ for a harness (ls tests/*/ cross-referenced by basename; a script with no matching tests/<name>/ dir is flagged NO). 51 scripts matched the filter; opentofu/modules/* (12 IaC modules) are W2.1's domain and are cited here only at the handoff boundary (Section 4), not re-decomposed.

2. Script -> module decomposition table

Legend: kind = IaC (OpenTofu-owned) / Procedure (bash/python driving live MAAS/juju/OS state) / Library (sourced, no independent action) / Gate (procedure, but its sole job is verify, never mutate by default). Layer per Section 2 of pass1-w4-module-planning.md. Harness = tests/<name>/run-tests.sh exists (checked live this session).

Shape of the decomposition (this filtered set of 51 scripts): 4 library units (2 with a dedicated selector-mechanism harness, 2 flagged for W2.2), 13 gates (verify-only, cross-cutting L5 or layer-scoped calculators), 34 procedure modules (L1-L4), of which 32/34 ship a harness today and 2 do not (maas-fabric-prune.sh / maas_fabric_classify.py -- a pre-existing gap, unrelated to container-elim, logged here because this pass's harness-discipline principle (pass1-w4-module-planning.md Section 4 item 2) would otherwise silently wave it through).

3. What a "procedure module" IS in this repo's terms -- the contract

Grounded entirely in patterns that already exist (pass1-w4-module-planning.md Section 1.2-1.3; docs/tool-index.md; CLAUDE.md "Delivery"), not invented for this pass. A procedure module is:

1. A named, single-purpose script under scripts/, one file = one job (the repo's existing granularity -- dc-rack-net.sh does rack-net only, dc-mirror.sh does the mirror only; no script is asked to do two jobs at once).
2. $SITE/$DC-parameterized, never DC-hardcoded -- the DOCFIX-151 convention (lib_net_select_dc "$DC" / lib_hosts_select_dc "$DC"), or a positional <site> argument read by the same underlying selector (every dc-*.sh / maas-*.sh script in Section 2 takes <site> this way). This is the mechanism that lets one module body run DC0 today and DC1 tomorrow without a copy-paste fork -- named explicitly as the anti-pattern to avoid in pass1-w4-module-planning.md Section 4 item 1.
3. Independently testable with its own harness -- tests/<script-name>/run-tests.sh (docs/tool-index.md:27, "65 scripts with their own tests/<name>/ harness"; CLAUDE.md "Delivery": "every script change ships with its tests/<name>/run-tests.sh harness green"). Section 2's table shows this held for 32/34 procedure modules in the filtered set.
4. Declared inputs, declared outputs, a stated exit contract. The pattern is explicit in the library layer already (lib-validate.sh's 0/1/2/3/4 PASS/FAIL/HOLD/PASS_PENDING_MANUAL/SKIPPED vocabulary) and echoed in every gate script (geneve-encap-assert.sh: "Exit: 0 all pass | 1 any FAIL | 2 usage/precondition"). A procedure module's inputs are its CLI args + whatever it reads live (never a baked table -- hard rule 2); its outputs are the mutation it performs (or, in check mode, the PASS/FAIL verdict) plus what it leaves behind for the layer above to consume (e.g. dc-node-carve.sh leaves a carved br-ex; dc-node-v6-carve.py needs that br-ex to already exist -- an explicit inter-module input/output chain, not implicit state).
5. Idempotent, safe to re-run. Universal across the table's procedure modules: check/apply split with apply DRY by default and --commit required to mutate (dc-region-topology.sh, dc-plane-ipam.sh, phase-00-maas-standup.sh); install actions that no-op when already correct (dc-rack-net.sh, dc-mirror.sh, site-tailscale.sh explicitly say "idempotent; safe to re-run").
6. Composes onto the layer strictly below it, never reaches past it. The layer-boundary rule from pass1-w4-module-planning.md Section 2: an L3 module's live inputs come from L2's output (MAC-pinned node VMs) or L1's output (a reachable MAAS region), never by dialing L0 or L2's infrastructure directly (Section 4 makes this concrete for the container-elim case).
7. Ships with a changelog entry + a revert, and is repo-lint clean (CLAUDE.md "Delivery" -- applies identically to procedure and IaC modules; not a procedure-only rule, restated here so the contract is complete).

Precedent this contract is built on, not invented against: the $DC-parameterized Stage runbooks (DOCFIX-151, docs/dc-dc-deployment-workflow.md:485-498) already run this exact contract at the stage granularity (one runbook file, $DC-selected, gated by repo-lint + a harness sweep + a changelog + a branch-merge per stage close-out, docs/dc-dc-deployment-workflow.md:424-436). A procedure module is the SAME contract one level down -- the runbook is the composition of several procedure-module invocations in a stated order; the module is the individually-testable unit the runbook calls.

4. The IaC <-> procedure BOUNDARY, stated precisely

The boundary is identity, not orchestration. OpenTofu owns everything up to "a booted libvirt domain exists, with its network identity (MAC per NIC, and any statically-assigned IP) correctly wired to the right plane bridges." The procedure layer begins at the first live dial into that object -- an SSH session, a MAAS API call, a libvirt power query -- and by design never reads OpenTofu state. It re-derives everything it needs from LIVE, independently observable identity: MAC address, hostname, or a fresh API/SSH probe. This is not a convenience; it is a stated design rule with its own incident history:

lib-hosts.sh:6-11 -- "WHY hostname-keyed (NOT system_id-keyed): MAAS system_ids are minted fresh on every (re-)enrollment... The stable identities are the hostname and the libvirt domain name, so every map here keys on hostname and the live system_id is resolved AT RUNTIME."

dc-node-v6-carve.py -- "EVERYTHING IS DERIVED FROM LIVE STATE -- there is no plane table here (hard rule 2): site membership <- the MAAS tag openstack-."

maas-node-power.sh:8-9 -- "Domains are matched to MAAS machines BY MAC ADDRESS -- never by name, because MAAS assigns its own random hostnames at enlistment."

Concretely, at each L1/L2 -> L3 handoff point in Section 2's table:

• Node VMs (L2, modules/node-vm) -> MAAS commissioning (L3): the handoff artifact is the MAC address baked into the libvirt domain XML (IaC output) that MAAS discovers at commissioning and maas-node-power.sh later matches power config against (procedure input). No file, no state read, no data pipe crosses the boundary -- only a MAC address that both sides independently observe.
• Client VM / edges / voffice1 (L1, modules/cloudinit-vm) -> install procedures (L1/L3): the handoff artifact is a reachable IP + a cloud-init-seeded initial state (IaC output); site-headend-install.sh / dc-rack-net.sh / site-tailscale.sh then dial in over SSH and configure from there, keyed by hostname/IP resolved live (lib-hosts.sh), never by reading opentofu/*.tfstate.
• DC edge WAN (L1) -> egress verification (L5): dc-egress-check.sh probes the live path end to end; it does not consult tofu at all.

Why this rule matters here specifically -- it is the diagnostic for the container-elim's core defect. pass1-w4-module-planning.md Section 2 already names the ONE place this boundary rule is currently violated: the inner root (opentofu/vr1-dc0-substrate/main.tf) dials OUT to a qemu+ssh provider INTO the outer root's own vvr1_dc0 output, because "a libvirt provider cannot be configured from a resource created in the same apply" (opentofu/main.tf:28-29). That is IaC reaching into IaC across a live-dial boundary that should only ever be crossed by a procedure module -- L2's inner half is doing L2-to-L2 what only L2-to-L3 is supposed to do (dial a live object by observed identity, not by direct provider coupling). Option 1 removes the violation structurally: with one flat root, L2 is IaC end to end (module bodies only, no cross-host provider dial), and the FIRST live dial into anything L2 produced is L3's MAAS commissioning -- exactly where the boundary rule says it should be. This is the single clearest argument, in module-decomposition terms, for why flattening also simplifies the module system and not merely the topology (echoing pass1-w4-module-planning.md Section 2's own framing).

Boundary summary table:

5. Option-1's new tools, mapped onto the decomposition

Net new procedure-module bodies this pass's decomposition surfaces: exactly TWO -- the (a) cross-DC isolation gate and the teardown-primitive. Everything else Option 1 needs is either (i) a new instance of an existing IaC module type (the client VM), or (ii) an existing procedure module re-targeted at a new host via its existing <site>/host-argument parameterization (no body change). This matches pass1-w4-module-planning.md Section 1's framing: "the container-elim does not need to invent module mechanics, only re-home."

6. Open items (not resolved by this worker; feed the Phase-2 administrator / Phase 4)

1. lib-identity.sh's harness status -- not independently verified this session; flagged for W2.2 (its assigned dimension, lib-hosts/lib-net containment-keyed values).
2. maas-fabric-prune.sh / maas_fabric_classify.py have no harness -- pre-existing gap, unrelated to container-elim causally, but the harness-discipline principle this pass restates (Section 3 item 3) would be inconsistent if silently excluded; logged for the Phase-2 administrator to route (build-a-harness item vs. accept-as-a-named-exception).
3. The teardown-primitive's exact shape depends on W2.1's root-topology design (the OPEN fork from pass1-admin-report.md Section 7 item 1) -- this worker places its LAYER, not its final form. Feed forward to whichever worker/administrator resolves the fork.
4. The rack-controller-remainder placement ruling (Section 5 row 4) is the actual blocker for writing the FINAL L3 change-set (which scripts get new call-site arguments); this worker confirms readiness (no tooling gap) but cannot pick a value (hard rule 2).
5. opentofu/modules/*'s own decomposition (W2.1's domain) was consulted only at the boundary (Section 4) -- this doc does not re-derive the IaC-module inventory or recommend root-splitting; that is W2.1's report to write.

7. Verification note

Every script's role/kind/layer classification in Section 2 is grounded in a direct header read this session (paths cited); harness presence was checked live via ls tests/*/ cross-referenced against each script's basename, not assumed from the tool-index's aggregate counts. The two "NO harness" flags and the lib-identity.sh open item are the only claims in this doc not independently confirmed against a second source. No mutation performed; no live cloud state queried; findings are LOGGED only, per the pass's read-only-planning charter.