Pass 1 -- W1.4: how planning artifacts map onto the layered module model

Worker: W1.4 (Phase 1, container-layer-elimination pass). Date: 2026-08-09. Scope: READ-ONLY. This is the conceptual backbone for Phase 4's module-workflow design (SCOPE-AND-EXECUTION-PLAN.md W4.2). Inputs read in full: SCOPE-AND-EXECUTION-PLAN.md, pass0-admin-report.md (Option 1 CONFIRMED at the Phase-0 gate, Section 7a), plus live repo survey below. No inferred values -- every claim below cites path:line or a directory listing taken this session.

1. What module structure ALREADY exists (survey, not proposal)

1.1 IaC modules -- opentofu/modules/ (12 modules, opentofu/modules/*)

Listing (find opentofu/modules -maxdepth 2 -type d, this session): base-image, cloudinit-vm, dc-planes, dc-storage-pool, maas-vm-host, mesh-link, netem-link, node-vm, office1-network, opnsense-edge, site-wan, wan-bridge.

Each module is already: (a) independently tofu validate-able (scripts/opentofu-validate.sh, opentofu/README.md:5-6,40-41 -- "validates EVERY module standalone"), (b) called from one or both of the two CURRENT roots -- the outer root opentofu/main.tf (vcloud provider) and the inner root opentofu/vr1-dc0-substrate/main.tf (qemu+ssh provider, D-123 Model B) -- and (c) already parameterized (no hardcoded DC identity inside a module body; the calling root supplies dc/CIDR/sizing values). This is a working IaC-module layer TODAY; the container-elim does not need to invent module mechanics, only re-home module CALLS from two roots into one and delete the modules that existed only to bridge the two-root split.

Outer-root calls (grep '^module "' opentofu/main.tf): vr1_dc0_storage, vr1_dc1_storage, office1_storage, office1_network, office1_opnsense, three mesh_* legs, ubuntu_noble_base, voffice1, netem_vr1_dc0_vr1_dc1, vr1_dc0_uplink, vr1_dc1_uplink, vvr1_dc0, vvr1_dc1 (opentofu/main.tf:35-537).

Inner-root calls (grep '^module "' opentofu/vr1-dc0-substrate/main.tf): inner_storage, vr1_dc0_planes, vr1_dc0_wan, vr1_dc0_opnsense, vr1_dc0_node (x12, D-121/R-3) (opentofu/vr1-dc0-substrate/main.tf:26-250).

The vvr1_dc0/vvr1_dc1 outer-root calls ARE the containment layer (pass0-admin-report.md Section 1.1); everything in the inner-root list is a module CALL that Option 1 re-homes, not a module BODY that changes shape (pass0-admin-report.md row 2: "module CALLS ... re-home into the outer/flat root -- bodies unchanged, provider changes").

1.2 Procedure/runbook modularity -- runbooks/dc-dc-phaseN-*.md + docs/dc-dc-deployment-workflow.md

docs/dc-dc-deployment-workflow.md already defines an 8-stage sequence (Stage 0 decision ratification through Stage 7 Designate/COS/Magnum), each stage with a fixed schema -- Goal / Build / Gate / Owns (D-numbers) / Reuse-vs-new / Authoring status -- and each stage's authoring status POINTS AT one runbooks/dc-dc-phaseN-*.md file:

Each runbook is already parameterized by $DC (lib_net_select_dc "$DC" / lib_hosts_select_dc "$DC", DOCFIX-151, docs/dc-dc-deployment-workflow.md:485-498) and each stage's close-out is gated by repo-lint + a harness sweep + a changelog + a branch-merge (docs/dc-dc-deployment-workflow.md:424-436, "Cross-cutting discipline"). This IS a procedure- module system already -- the container-elim pass does not need to invent the concept, only (a) rewrite Stage 3's content for the flat topology and (b) formalize the pattern the operator is asking for so it is named and reusable, not just an emergent convention.

Underneath the stage runbooks, two shared libraries act as the procedure layer's own "IaC modules": scripts/lib-net.sh and scripts/lib-hosts.sh -- every stage-4/5 script sources them for CIDR/host facts, keyed by the $DC selector (vr1-dc0/vr1-dc1, D-119). This is the existing parameterization mechanism the layer model below reuses rather than replaces.

1.3 Test-harness convention (governs BOTH module kinds)

• IaC: one shared gate, scripts/opentofu-validate.sh (tests/opentofu-validate/), validates every module standalone plus both roots.
• Procedure: per-script harnesses, tests/<script-name>/run-tests.sh (tool-index: "65 scripts with their own tests/<name>/ harness"; docs/tool-index.md:27).

No module of either kind ships without its harness (CLAUDE.md "Delivery" rule); this is already the repo norm the layer model's design principles (Section 4) restate for the new modules Option 1 introduces, not a new rule.

2. Proposed layer model

Six layers, named to match the EXISTING Stage numbers where a layer is Stage-owned, so the layer model is a REFRAME of what's already built, not a parallel taxonomy. "IaC or procedure" marks whether the layer's artifact is an OpenTofu module/root or a runbook+script procedure. Verify layers (L5) are cross-cutting and re-invoked at every layer boundary, not a one-time final step.

Layer-boundary rule (why this ordering, not invented): each layer's INPUT is the layer below's OUTPUT only -- L1 does not reach into L3, L3 does not dial L0 directly. The one place this rule is currently VIOLATED is exactly the container layer: the inner root (part of L2) dials OUT to a cross-host qemu+ssh provider (opentofu/main.tf:28-29, "a libvirt provider cannot be configured from a resource created in the same apply") because L2's outer half (vvr1_dcN) had to exist as infrastructure BEFORE L2's inner half (planes/nodes) could be declared. Option 1 removes this violation structurally (Section 3) -- it is the single clearest justification, in layer-model terms, for why flattening also SIMPLIFIES the module system, not just the topology.

3. How Option 1's changes map onto the layer model

D-143 stays a separate axis, threaded through every layer, not a layer of its own. The 10.12->10.13 re-IP touches L0's CIDR inputs, L2's node addressing, and L4's overlay files identically whether or not the container layer exists -- SCOPE-AND-EXECUTION-PLAN.md Section 7 requires the two changes stay distinguishable in the change-set, and the layer model above keeps that distinguishability structural: D-143 is a PARAMETER change at every layer's input; the container-elim is a LAYER-COUNT/BOUNDARY change at L1/L2/L5 specifically.

4. Design principles for the module system (repeatable + Roosevelt-transferable)

1. Parameterize by site token, not by hardcoded identity. The $DC selector convention (D-119, DOCFIX-151, lib_net_select_dc/lib_hosts_select_dc) already does this for the procedure layer; the IaC layer already does it structurally (no module body names a DC). Option 1's new artifacts (the client VM, the L5 isolation control) MUST take the same token rather than being written DC0-specific and copy-pasted for DC1 -- the exact anti-pattern dc-dc-deployment-workflow.md gap-register item 1 was created to close.
2. Every module ships its tested harness, no exception (CLAUDE.md "Delivery"; Section 1.3 above). A new L1 client-VM instantiation reuses opentofu-validate.sh's existing coverage (it's the same cloudinit-vm module, no new module body); the NEW L5 isolation control needs its own tests/<name>/run-tests.sh from day one, matching geneve-encap-assert.sh's and SEC-010's own precedent -- a mechanical --check, not a prose claim.
3. Idempotence at every layer. L0-L2 already get this from tofu apply; L3/L4 procedure modules must stay re-run-safe (the existing MAAS "READY not deployed" handoff and the preflight.sh drift-detection gate already enforce this at the L3/L4 boundary -- D-140's own "OWED BEFORE THE REVIEW" note on P8 drift-detection value is the same principle one layer up).
4. Clear layer boundaries -- no layer reaches past the one directly below it. Section 2's layer-boundary rule; the container layer is the one place this was violated (L2's inner half dialing a cross-host provider), and removing it is what makes the OTHER four principles easier to hold, not a side effect.
5. Findings/design stay LOGGED at their true layer, not folded upward. The rack-controller/ D-131/mirror placement question (Section 3) is explicitly NOT resolved here -- it is an L3 procedure-placement decision that this worker's L1/L2 mapping cannot answer without inventing a value, so it stays an open item for the phase administrator and Phase-2's tools workers.
6. D-140 is a DISTINCT axis from this layer model -- do not conflate. D-140 (docs/design-decisions.md:7781-7822) is PINNED, not ruled, and governs whether the L4 Juju layer ITSELF becomes OpenTofu-managed -- sequenced strictly AFTER "dc0 deploys and is HARDENED ... that deployment method is TESTED." It does not currently govern how L0-L2's IaC modules are structured (that structure already exists and predates D-140). The layer model above is written so that IF D-140 is later adopted, L4 becomes an IaC-module layer too WITHOUT changing L0-L3's shape -- but that is a future trigger, not something this pass proposes now.
7. Roosevelt-transfer lens applied per layer, not per artifact. L0's node-VM/netem-link shim (no bare-metal analog, dc-dc-deployment-workflow.md:11-14 Section-9 shim register) does NOT transfer; L1's client-VM pattern, L3's MAAS enlist procedure, and L4's Juju/bundle procedure ARE the D-138 Roosevelt bastion analog and the direct pre-Roosevelt bare-metal deliverable (pass0-admin-report.md Option-1 "For" bullet: "rehearsed early ... transfers to the pre-Roosevelt bare-metal test"). The layer model's job for Phase 4 is to keep these two classes visibly separate so the module-workflow design does not present shim-layer work as reusable.

5. Open questions for Phase 4 (not resolved by this worker)

1. L3 rack-role/D-131/mirror placement (Section 3, pass0-admin-report.md Section 6 item 3) -- unresolved; blocks writing the concrete L3 module change-set until ruled or proposed.
2. The L5 cross-DC isolation control's exact mechanism -- confirmed IN SCOPE (handling (a)) at the Phase-0 gate, but its concrete design (nftables rule set, --check gate shape, SEC-NNN number) is Phase-1/2 work, not yet started.
3. The site-down teardown primitive's replacement shape (module-scoped group-destroy) -- named as owed (Section 3, L5/cross-layer row) but not designed here; it is the biggest single piece of NEW tooling this layer model implies beyond re-homing existing module calls.
4. Biggest open question about the layering itself: whether L3 (MAAS enlist) and L4 (Juju deploy) should be reframed as OpenTofu-orchestrated procedure invocations once D-140 is eventually adopted (Section 4 item 6) -- this pass deliberately keeps them procedure modules now, consistent with D-140's PINNED status, but Phase 4's module-workflow design should name this as a FUTURE layer-model revision trigger rather than silently assuming procedure-only is permanent.