Pass 1 -- W1.2: deployment-workflow doc + stage/gate structure vs the layered-module framing

Worker: W1.2 (Phase 1, container-layer-elimination pass). Date: 2026-08-09. Scope: docs/dc-dc-deployment-workflow.md (stage identity, gates, tooling gap register) and the G-series gate register in docs/CURRENT-STATE.md section 6, read against the CONFIRMED Phase-0 outcome (pass0-admin-report.md): Option 1 (flat node VMs on vcloud libvirt + per-DC non-hypervisor vr1-dcN-client VM), cross-DC isolation handling (a) (new vcloud-level host-isolation control, new SEC-NNN row, mechanical --check gate), MAAS region unchanged (vr1-dcN-maas-01). READ-ONLY. No inferred values -- every claim below cites path:line from docs/dc-dc-deployment-workflow.md, docs/CURRENT-STATE.md, docs/design-decisions.md, or pass0-admin-report.md.

0. A framing correction before the analysis (measured, not inferred)

The task brief's example -- "does the Stage-2 substrate / bootstrap-gate stage collapse" -- names the wrong stage number. Measured against the workflow doc:

• Stage 2 (docs/dc-dc-deployment-workflow.md:60-146) is the Office1 SITE standup (D-114): it builds voffice1, a different containment VM (MAAS-region + LXD 5.21-track + MAAS-composed service VMs). Pass0 confirmed voffice1 is explicitly NOT container-layer (pass0-admin-report.md:19,60, "Office1 arm ... NOT container-layer"). Container-elim does not touch Stage 2's shape. This distinction matters for module design later in this doc: the project will carry TWO different "containment VM" patterns going forward -- one retired (Model B vvr1-dcN), one kept (voffice1's D-114 LXD-composition model) -- and a future session must not conflate them.
• Stage 3 (docs/dc-dc-deployment-workflow.md:149-197) is the actual bootstrap-gate / two-root Model-B DC-substrate stage -- its own Build line says it verbatim: "D-123 Model B (TWO OpenTofu roots + a bootstrap gate between)" (:154). This is the stage container-elim restructures. All findings below key off Stage 3, not Stage 2.

1. Stage-by-stage change table

2. G-series gate register: which are keyed to the container layer

Read against docs/CURRENT-STATE.md section 6 (:7786-7813) in full.

• G9 (DC0 outer apply, :7803) -- keyed to the two-stage apply by its own SEC dependency note: "SEC-010's transit FORWARD-drop is applied+verified at deploy step B via site-headend-install.sh --host-nodes --check on vvr1-dc0 (gate G10)". This gate is CLOSED (historical, dc0's checkpoint build) -- it does not reopen, but it is the template the next DC-substrate apply gate (whatever supersedes it for the 10.13 rebuild) must NOT copy verbatim: under Option 1 there is no outer/inner split for it to key off, so a redrawn gate is a SINGLE apply-and-verify, not a two-step G9+G10 pair.
• G10 (:7804, deploy steps B-E) -- the sub-items most exposed:
  • "SEC-010 --host-nodes --check on vvr1-dc0" -- this exact check RETIRES with site-headend-install.sh's node-host mode (pass0-admin-report.md:87). Its REPLACEMENT is the new cross-DC host-isolation control's own --check (the confirmed Phase-0 gate handling (a), pass0-admin-report.md:288-291) -- but that control is scoped to the WHOLE vcloud host (both DCs' co-residency), not to a single DC's apply step, so it likely does NOT slot into a per-DC G10-style gate at all; it is closer in shape to a Stage-1-level, apply-once gate (see Section 4). This is a genuine stage-home question for Phase 1/2 design, not resolved by this worker's dimension alone -- flagged forward.
  • "depth-4 nested boot" -- becomes depth-2 (Section 1, Stage 3 row).
  • "D-125 foreign-MAC egress test" -- the MECHANISM changes (no bridge-in to test the isolation of), but an analogous direct-NAT egress-isolation assertion is still owed; do not read this as "the egress gate goes away", only that what it tests changes shape.
  • "MAAS reachability + TF_VAR_maas_api_key" and "netem placeholder" -- both UNAFFECTED (Plane-2/mesh concerns, not containment-layer concerns).
• G12 (:7806, vr1-dc1 build) -- CLOSED/historical, but it is the fullest worked example of what a per-DC Stage-3 gate sequence looks like today (outer apply -> Step B SEC-010 check -> inner apply -> rack standup -> commissioning). Its structure is the thing that collapses; future sessions writing the reshaped gate should read G12's own text as "the shape being replaced," not as a template to repeat.
• G17 (:7811, per-DC artifact source reachable from a node) -- OPEN today, and its check literals directly name the containment-VM-hosted mirror address (10.12.8.4 for dc0). As covered in Section 1's Stage-4 row: this gate's eventual close needs BOTH the D-143 address-family edit and the container-elim placement edit, kept distinguishable per the SCOPE plan's instruction.
• G18 (:7813, lb-mgmt IPAM apex) -- no container-layer dependency found; Octavia's charm-owned lb-mgmt network is unrelated to the substrate hypervisor topology. Named here only to confirm it was checked and correctly excluded (a "manufactured contradiction" risk this repo's own instrument-currency record warns about -- do not let G18 get swept into the container-elim change-set by proximity in the same table).
• G1-G8, G11, G13, G15, G16 -- read; no container-layer dependency found in any of them (audit/ratification gates, D-068/D-071 rulings, office1 edge state-surgery gates). Confirmed by direct read of :7795-7802,7805,7807,7809-7810, not assumed from gate NAME.
• G14 (:7808, open SEC rows) -- indirect only: container-elim MIGRATES several credential residencies (SEC-026/-028/-029, vm-secret-locations rack rows, per pass0 row 8) and ADDS at least one new SEC-NNN row for the cross-DC isolation control -- both are G14 COUNT-affecting events when they land, not gate-SHAPE changes. Flag for whoever next runs ledger-scan.sh after this pass's changes land, so the count is not read as unexplained drift (the project's own instrument-currency lesson #25 applies directly here).

Net finding: exactly one G-series gate concept is directly restructured (G9/G10's DC-apply sequence); one is a placement-pending intersection with D-143 (G17); the rest are either unaffected or affected only as a downstream credential-count/ledger consequence (G14). No gate needs to be DELETED outright -- G9/G10's successor for the 10.13 rebuild is a simplified redraw, not a removal, since a substrate apply + SEC verification + boot proof + egress test are all still real checks, just fewer steps and one execution host instead of two.

3. Tooling gap register -- what closes, reshapes, or is added

Read against docs/dc-dc-deployment-workflow.md:447-1354 in full.

• Gap #2 (OpenTofu, :499-578) -- RESHAPES. The still-open line "tofu plan/apply has NOT been exercised for the Stage 3 DC substrate" (:537) changes SCOPE under Option 1: the first real exercise of Stage-3 apply becomes a single flat-root apply, not an outer+bootstrap +inner sequence. The module inventory itself shrinks: modules/wan-bridge (D-125 bridge-in) is DELETED (pass0 row 3); the inner-root files (opentofu/vr1-dc0-substrate/, vr1-dc1-substrate/) RETIRE as separate roots, their module CALLS folding into the outer/flat root (pass0 row 2). modules/maas-vm-host's target changes from vvr1-dc0's inner virsh to vcloud's own virsh directly (pass0-w4-targets.md:109-111) -- this closes the DOCFIX-179 deferral note this gap still carries (:553-554, "deliberately NOT maas_vm_host_machine") differently than originally anticipated, since there is no longer an inner virsh to register.
• Gap #17 (per-site ISP uplink, :857-933) -- STAYS CLOSED, but its "how it was actually closed" mechanism description (:894-904, the bridge-in shape: outer NAT + inner bridge onto br-vr1-dcN-wan) becomes HISTORICAL under Option 1's direct-NAT attachment (pass0-w4-targets.md:88-93, "exactly like Office1's edge does today ... Model A's item 8"). Flag so a future reader does not rebuild the retired bridge-in mechanism by reading this gap's closing note as current practice; a doc-currency addendum is owed here at the point the container-elim ruling lands, not a reopening of the gap itself.
• Gap #19b ($DC region-qualified namespace, :976-1038) -- UNAFFECTED. D-119's region-qualified selectors (vr1-dc0/vr1-dc1) are an IPAM/naming-layer fix, orthogonal to hypervisor nesting depth.
• Gap #20 (host->site reachability / site-baseleg.sh, :1039-1109) -- verdict likely still holds, but the reasoning chain it rests on shifts and should be RE-VERIFIED, not carried forward silently. Today's "no leg required on vcloud" verdict (:1075-1093) rests on D-128: "no vcloud-originated DC operation exists ... Plane 2 ... EXECUTES on voffice1". Under Option 1 the SUBSTRATE build itself now originates from vcloud directly via a local qemu:///system provider (Section 1, Stage 3 row) -- but that is Plane 1 (host-VM creation), the SAME category D-128 already assigns to vcloud today for the outer root, not a new vcloud-originated L3 dial into a DC's own MAAS/Juju/openstack layer (which stays Plane 2, via voffice1, or D-138's client VM). The verdict's PREMISE is therefore probably unchanged, but this gap's own text explicitly warns "If a future change makes vcloud originate to a DC directly, this verdict expires and branch 1 applies" (:1092) -- container-elim is exactly such a change to the SUBSTRATE layer, even if not to the Plane-2 boundary, so a fresh re-measurement (not an inference from today's text) is owed once the flat root is built. Named here as a Phase-2/3 tooling-review item, not resolved by this worker.
• Gap #21 (per-DC Tailscale, :1189-1310) -- UNAFFECTED in shape. The tailscale router VM (vr1-dcN-tailscale-01, utility .7) is already one of the 12 flat node-VM siblings inside today's inner root (pass0 table row 2's "12 node VMs") and folds into the flat root exactly like every other node VM -- same re-homing mechanism, no gap-content change. Confirmed explicitly so it is not mis-swept into the container-elim change-set by proximity (it is a D-129(iii) item, not a D-123/Model-B item).
• Gap #22 (ceph-rbd-mirror HA, :1310-1354) -- NOT a consumer. Confirmed by direct read; this is a D-108 application-layer HA question, unrelated to substrate nesting. Named to record it was checked, per this repo's "a clean negative still needs the check shown" discipline.
• New gap to REGISTER (not yet in the doc): the cross-DC adjacency control itself (pass0-admin-report.md Section 5, handling (a)) has no register entry today because it is a Phase-0-confirmed-but-not-yet-designed deliverable. It should land as a NEW numbered item in this register (next-free per the register's own numbering, distinct from the D-NNN/SEC-NNN numbering it also needs) once Phase 1/2 design work produces its concrete shape, so it is trackable the same way every other gap here is.

4. The current stage/gate flow re-expressed as layered modules (first sketch)

Per SCOPE-AND-EXECUTION-PLAN.md:40-43, "module" means BOTH IaC (OpenTofu) modules for the substrate AND procedure/runbook modules for the orchestration layered on top. This sketch maps today's Stage 1-7 flow onto that split, incorporating Option 1 and the (a) isolation control.

IaC-MODULE LAYER (OpenTofu, vcloud-executed, Plane 1 -- D-128)
  [1] vcloud-host-prep         (Stage 1)  -- ONCE.  pools, mesh triangle, MTU, nested-KVM base.
  [2] office1-site             (Stage 2)  -- ONCE.  voffice1 containment VM (D-114, UNCHANGED
                                              by this pass -- kept as its own IaC module, its
                                              LXD-compose half stays a procedure step inside it).
  [3] cross-dc-isolation       (NEW)      -- ONCE, vcloud-level. The Phase-0-confirmed (a)
                                              deliverable: nftables/isolation artifact +
                                              mechanical --check + new SEC-NNN row. STAGE-HOME
                                              OPEN (Section 2): candidate slots are (i) folded
                                              into [1] as a host-prep-time control, applied once
                                              and re-verified whenever a second DC lands, or
                                              (ii) its own micro-module invoked once, before the
                                              first per-DC substrate apply. Phase-1/2 design item,
                                              not resolved here.
  [4] dc-substrate-flat        (Stage 3)  -- PER DC (dc0, dc1, futureN). The collapsed module:
                                              6 planes + edge + 12 node VMs + client VM, ONE
                                              apply. Directly supersedes today's
                                              outer+bootstrap-gate+inner three-part sequence.
                                              Gate: single apply-and-verify (Section 2) --
                                              SEC check via [3], depth-2 boot, direct-NAT egress
                                              isolation test.

PROCEDURE-MODULE LAYER (scripted/runbook, mixed Plane 1/2/DC-local execution)
  [5] maas-enlist-commission   (Stage 4)  -- PER DC. Unaffected mechanically; artifact-mirror/
                                              rack-controller/D-131-forwarder PLACEMENT is an
                                              input this module now takes as a parameter (client
                                              VM vs maas-01 vs retire -- pass0 Section 6 item 3),
                                              not a hardcoded containment-VM address.
  [6] juju-bundle-deploy       (Stage 5)  -- PER DC. D-138's client role executes here, now on
                                              the [4]-created client VM instead of the retired
                                              containment VM. STAYS a procedure module, not an
                                              IaC module, by the ALREADY-RULED D-140 pin (Section
                                              1, Stage 5 row) -- this pass's module design must
                                              not silently fold Juju into [4].
  [7] dr-failover-drill        (Stage 6)  -- PER DC (or cross-DC pair). Unaffected.
  [8] designate-cos-magnum     (Stage 7)  -- PER DC. Unaffected.

TEARDOWN (mirrors the IaC layer, module-scoped)
  [T] tofu destroy -target=module.<dc>   -- PER DC, one call per [4] module instance -- the
                                             candidate re-earning of D-123's lost one-command
                                             site-down (Section 1, teardown row).

Sequencing note for W4.3 (not this worker's dimension, flagged forward): [3] cross-DC isolation logically needs to exist and be verified BEFORE the second DC's [4] apply lands (otherwise dc0-alone co-residency has nothing yet to leak into, but dc0+dc1 co-residency does) -- this is a real ordering constraint on the module-invocation sequence Phase 4 designs, not merely a stage-numbering question.

5. Top risks for this dimension

1. The (a) isolation control has no stage home yet -- it is a confirmed Phase-0 DESIGN REQUIREMENT with no gate row, no stage slot, and no register entry (Section 3, "New gap to register"). If Phase 1/2 do not give it one explicitly, it risks being built ad hoc and under-gated relative to the SEC-010 pattern it is explicitly modeled on.
2. G17's dual-cause edit (D-143 address + container-elim placement) is easy to under-scope if a future session only remembers the address-family half; this doc names both causes explicitly so neither is dropped.
3. D-140 is an easy module-design trap -- the layered-module goal's own IaC-modules-for- substrate framing could tempt folding Stage 5 (Juju) into the IaC layer "while we're at it"; D-140 already RULES that OUT for this redeploy (pinned to end-of-deployment review). Phase 4 must treat Stage 5 as a procedure module, full stop, for the 10.13 rebuild.
4. Stage 3's "Owns" D-number list is stale the moment Option 1 is ruled formally (D-123, D-125 both need their Phase-4-framed amendment text); this doc's Section 1 table can serve as the input list for that edit but does not itself perform it (out of scope, GA-R5 territory).

6. Sources consulted (path:line, for the adversarial-check pass)

docs/dc-dc-deployment-workflow.md (full read, 1354 lines); docs/CURRENT-STATE.md:7786-7835 (section 6 gate register + section 7 version pins); docs/design-decisions.md:7118-7180 (D-138 full text), :7781-7787 (D-140 full text), :8083-8143 (D-143 excerpt); pass0-admin-report.md (full read); pass0-w4-targets.md:1-220 (full read, targeted at execution-host/plane detail not fully covered in the admin report's synthesis).