NetBox write-path hardening: the bugs that would have corrupted the apex at C2 ...

Found by adversarial review during D-119; independent of the naming work. These
are what would have bitten during C2 (the production IPAM write Stage 2 needs).

1. roles-aggregates-import.py STILL died half-way through a production write. The
   preflight added on 2026-07-13 -- after this same script committed 4 roles, 400'd
   on the 5th and left the apex half-populated -- only covered role-NAME collisions.
   The ARIN RIR lookup and validate_ula_48() both still ran BELOW the first write,
   so an apex without ARIN, or a typo'd ORG_ULA_48, would commit 5 roles (and the
   RIRs) and THEN die, with no rollback. The exact failure the preflight was added
   to prevent, still armed one section lower. The RIR half of the preflight loop was
   a literal no-op. Both checks moved INTO the preflight.
   A preflight that does not cover every die() downstream of the first write is not
   a preflight.

2. sandbox-fidelity-check.py could return a FALSE GREEN -- and it is the script we
   have been citing as PROOF the sandbox is a faithful replica. It field-compared
   only SHARED objects; the planned delta was checked merely as a SUBSET of
   EXPECTED_NEW. With ZERO of the 36 DC prefixes created, extra={} -> unexpected={}
   -> it printed "Nothing lost, nothing stray" and exited 0. EXPECTED_NEW was an
   upper bound masquerading as an assertion. It is now BOTH bounds, and delta
   prefixes are checked for scope and role (the 17-prefix scope-drop bug relocated
   into the delta, where the old check was structurally blind).

3. dc-dc-prefixes-import.py died mid-loop on a missing role -- find_role() was
   resolved lazily INSIDE the write loop. Against upstream as it stands TODAY (no
   six-plane roles), a --commit creates the site + 4 prefixes then dies on the 5th:
   a half-written datacenter. Now a whole-plan preflight resolves every role first.

4. The test fake was KINDER THAN REALITY at the failure point: fake_pynetbox.get()
   returned matches[0] on a multi-match where real pynetbox RAISES. NetBox permits
   duplicate prefixes (the importer's own docstring anticipates them vs vr0-dc0), so
   this would blow up in production while the harness sailed through. It now raises.

TESTS: tests/sandbox-fidelity-check/ is NEW (10/10) -- the checker shipped with NO
harness at all, which is exactly why the false green survived; T3 reproduces it, and
T1 derives its expectation from the checker's own EXPECTED_NEW rather than re-typing
it. roles-aggregates-import 16->19, asserting BY POSITION that ARIN and the ULA are
validated before the first create (the old harness only checked the WORD "PREFLIGHT"
appeared -- green while the landmine was armed).

GAUNTLET ALL GREEN (58). repo-lint 0 fail. Zero NetBox writes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

D-119: region-qualify the VR1 DC namespace -- C3 / gap #19 CLOSED (Stage 3 unblocked) ...

THE BUG: the token `dc0` meant TWO DIFFERENT CLOUDS depending on the file --
VR0's LIVE testcloud in scripts/lib-net.sh, VR1's FIRST DC in the NetBox
importer. One string, two clouds, one of them in production.

THE RULING (operator): the repo adopts the apex's names verbatim.
  vr0-dc0  VR0's DC0        the LIVE testcloud (a DIFFERENT region)
  vr1-dc0  VR1's FIRST  DC  GUA 2602:f3e2:f02::/48
  vr1-dc1  VR1's SECOND DC  GUA 2602:f3e2:f03::/48
Bare dc0/dc1/dc2 are now REJECTED LOUDLY everywhere.

D-119 COMPLETES D-117, it does not reverse it: it executes D-117's own amendment
across the three surfaces D-117 never touched. ZERO NetBox writes -- the apex was
already correct and self-consistent (MEASURED: f02::/48 -> vr1-dc0, f03::/48 ->
vr1-dc1); the REPO was the only surface out of step. Renaming the apex to match
the repo was considered and REJECTED (production IPAM write; VR1 would become the
only 1-indexed region; and vr1-dc1 would mean VR1's FIRST DC while vr0-dc1 means
VR0's SECOND).

THE PRIZE: the importer's DC->site map is now an IDENTITY -- there is no offset
table left to get wrong, and an assert enforces it. The original defect was
precisely a WRONG LOOKUP TABLE. The bug class is deleted, not defended.

TWO REAL BUGS the naming fix ALONE would NOT have closed (found by review sweep):

- BREAK-1: descriptions were built with f"VR1 {dc.upper()} ..." -- under D-119 that
  renders "VR1 VR1-DC0 provider-public" on all 36 prefixes. Same class as the
  original bug (deriving a label by munging a token), hidden in the description
  field where slug-focused review missed it. Now looked up from SITES[name].

- BREAK-2 (the important one): DC_GUA_PREFIX was NEVER cross-checked against --dc.
  `--dc vr1-dc0 DC_GUA_PREFIX=<f03>` was ACCEPTED: it writes the SECOND DC's GUA,
  carved with the FIRST DC's ULA nibble, scoped to the FIRST DC's site -- a
  silently mis-bound datacenter assembled from two disagreeing sources. Identity-
  mapping the slug leaves the ADDRESSING free-floating. Now guarded by EXPECTED_GUA.

ALSO: vdc1/vdc2 -> vvr1-dc0/vvr1-dc1 (D-114 amendment). D-114's own DR primitive is
`virsh destroy vdc1`, which read as "destroy VR1 DC1" while MEANING "destroy VR1
DC0". A mislabelled destroy command in a DR drill is not cosmetic. Neither VM is
built, so it is free. voffice1/Office1 KEEP their number (operator ruling).
Env var: DC1_/DC2_V4_SUPERNET -> VR1_DC1_V4_SUPERNET (both old names rejected).
rbd-mirror's --site-name aligned: `--dc vr1-dc0 --site-name dc1` was a re-created
two-namespace collision on one command line.

TESTS: dc-selector 21->30, prefixes-import 40->82 (identity invariant; EXPECTED_GUA
in BOTH mismatch directions; mismatched run writes NOTHING; matching pair still
succeeds; no munged description). GAUNTLET ALL GREEN (57). repo-lint 0 fail.
The old harnesses PINNED THE WRONG MAPPING -- they would have gone green while
enforcing the bug.

THE tofu apply IS NOT DONE -- IT IS GATED. Plan: 11 to add, 0 to change, 11 to
destroy (libvirt object names are ForceNew; moved{} makes the plan reviewable but
cannot suppress a replace). MEASURED SAFE: all 11 are EMPTY -- no guests, no
volumes, Stage 3 hasn't run. Office1's live objects are not in the plan.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

C1 follow-ups: verify the RDNSS we never set; correct a revert line that did not revert ...

Two defects in the C1 changelog, both found on review:

1. The RA advertises `RDNSS 2602:f3e2:f01:1` -- a field we never set; OPNsense
   auto-defaulted it to the edge's own LAN v6 address. Same failure class we avoided
   with mode=unmanaged (advertising a service that may not exist), one field over,
   and it slipped in BECAUSE the field was left unset. CHECKED: the edge's Unbound
   really does answer DNS on that v6 address (dig from voffice1 resolves; it works
   with no v6 egress because Unbound queries upstream over v4). Correct -- but by
   luck, not design. Set RDNSS explicitly when this RA config is reused on the
   DC0/DC1 edges at Stage 3.

   Bonus: this makes "services binding v6" EVIDENCE rather than inference -- a real
   v6-bound service answering real queries.

2. The address-revert line said `--commit 10.10.0.1 lan :: 64`, which does NOT clear
   the field -- it would SET the unspecified address. The script cannot express a
   clear at all (4 args required, address validated). Shipping an unverified revert
   is exactly what the delivery rule exists to prevent. Replaced with the honest
   GUI clear + a note that a --clear flag would be the real fix.

repo-lint 0 fail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Office1 LAN IPv6 is LIVE and proven on the wire -- Stage 2 close-out C1 CLOSED ...

The last build item on Office1. Executed against the live edge, verified against
the kernel and the wire, not by {"result":"saved"}.

  scripts/opnsense-set-interface-v6.sh --commit 10.10.0.1 lan 2602:f3e2:f01:1 64
  POST /api/radvd/settings/addEntry {"entries":{...,"mode":"unmanaged"}}
  POST /api/radvd/service/reconfigure

PROVEN: address on the kernel (ifconfig, not the config file); radvd advertising
2602:f3e2:f01:/64 AdvAutonomous/AdvOnLink with no M/O flags; voffice1
autoconfigured ...:5054:ff:fe6a:87e5 by SLAAC + an RA-learned route; edge->voffice1
GUA ping 0.0% loss. The neighbour MAC matches voffice1's known Kea lease hwaddr.
No collateral damage: v4 10.10.0.1 intact, Kea DHCPv4 still serving udp/67, the
compose-net route still good.

mode=unmanaged is DELIBERATELY not the model's default. `stateless` sets the RA
Other-config flag, pointing clients at a DHCPv6 server -- and Kea DHCPv6 is
enabled=0 with no daemon running. The default would have advertised a server that
does not exist. Field names, the request key (addBase('entries','entries')), the
mode values and the apply endpoint were all READ OFF THE EDGE, not recalled.

OPERATOR RULING -- the v6 NAT was NOT built. A v4-to-v6 NAT (a second OPNsense, or
nginx) was proposed to simulate the v6 the lab will not forward. Withdrawn: it
contradicts D-101 ("native GUA routing, no NAT66"), D-115's amendment says the
missing egress is the upstream's problem and not ours, and a translation box is
precisely the component Roosevelt will NOT have -- maximum delta for zero proof.
nginx is an L7 proxy, not NAT, and proves nothing about RA/ICMPv6/Ceph-over-v6.
Ruling: configure IPv6 internally now; configure the IPv6 edge AFTER deployment.

TRAP recorded: voffice1 has forwarding=1 + accept_ra=0 and STILL autoconfigured --
netplan/systemd-networkd processes RA in USERSPACE, independent of the sysctl.

WAN v6 leg stays DEFERRED: re-measured today, v6 internet is 100% loss from vcloud
while v4 is fine. Internet GUA reachability remains UNPROVABLE in VR1.

repo-lint 0 fail; opnsense-set-interface-v6 harness 40/40.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Consolidate to one session; close last night's two delivery gaps ...

Work had fragmented across FOUR concurrent Claude sessions on this one clone,
including two --permission-mode auto background agents (idle 14-15h, still
holding auto-approve rights against the live cloud) and a second interactive
session that got the same "resume last night's work" prompt six minutes before
this one and started bootstrapping in parallel. All terminated; the supervising
daemon stopped (it had respawned the agents once -- killing the child is not
enough). Working tree was clean and 3-ahead throughout; nothing lost.

Last night's three commits were made by the auto-permission agent and left
UNPUSHED and UNDOCUMENTED. Both closed:

- Pushed 6ed6b9a..522ba7d (the D-113 amendment + the v6 script existed only on
  local disk; a jumphost rebuild would have lost them).
- changelog-20260714-opnsense-set-interface-v6.md -- the delivery rule wants
  harness + lint + changelog-with-revert; the script shipped with the first two.
  Records that it is WRITTEN AND TESTED but NEVER RUN with --commit (C1 is open).

Ledger:
- Machine block re-seeded: next-free D was STALE at 114 (actually 119; D-114..118
  are all ADOPTED), and SEC-008 was missing.
- Logged a ledger-scan DEFECT: it reports D-115 as PROPOSED/OPEN, but D-115 is
  ADOPTED -- the scan matches "PROPOSED/OPEN" in body prose instead of reading the
  Status line. The status twin of the decoy-token rule. Logged, not fixed.
- CORRECTED pinned item 1a, which still instructed the REST API for the LAN IPv6.
  That path does not exist (D-113 amendment, measured). It would have sent the
  next session at a dead end.

repo-lint 0 fail; opnsense-set-interface-v6 harness 40/40.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

opnsense-set-interface-v6: script the LAN IPv6 the REST API cannot set (D-113 amendment) ...

Operator ruling 2026-07-14: take the PHP-model-over-SSH path, not a GUI click and
not the unproven VIP path. Rationale: the DC0 and DC1 edges get the same treatment
at Stage 3, so this must be a script, not a manual step paid three times.

WHY THIS EXISTS: measured on the live Office1 edge (OPNsense 26.1) -- there is NO
REST endpoint for a base interface's ipaddrv6. Interfaces > [LAN] is served by the
LEGACY page /interfaces.php?if=lan; only the Devices and Neighbors sub-trees were
ever migrated to MVC. D-113(a2)'s claim that "interfaces" are API-covered was
inferred from DHCP/firewall being API-native, never measured, and is false.

WHY IT IS NOT THE FORBIDDEN config.xml PUSH -- the distinction is the whole point:
it never AUTHORS a config. It ships opnsense-set-iface-v6.php, which loads the
edge's LIVE config through OPNsense's own Config singleton, mutates exactly two
leaf fields (ipaddrv6, subnetv6), and lets the vendor's own code serialize it --
byte-for-byte the code path interfaces.php runs on Save. Nothing is replaced
wholesale, so the API-managed Kea DHCP and the 8 firewall rules cannot be
clobbered. Same principle as opnsense-bootstrap-apikey.sh, which mints a key by
calling the vendor's own model rather than re-implementing its $6$ crypt format:
call the interface, do not re-implement the internals.

Safety properties, all pinned by the harness (40/40):
  - DRY BY DEFAULT in both halves; --commit required to write.
  - The interface COUNT is asserted unchanged before saving AND re-asserted on a
    fresh forceReload() read-back. A silent structural drop on a live router fails
    loud rather than being found later by a ping that stopped.
  - Only ipaddrv6/subnetv6 may be assigned -- the harness counts the assignments.
  - Values validated locally BEFORE they ever reach the router.
  - Remote commands go through `sh -s`: root's shell on the edge is TCSH, where a
    $(...) in a quoted remote command dies QUIETLY.
  - Ground truth is the KERNEL (ifconfig), never the config file or a self-report.

NOT YET RUN against the edge -- that is the next, individually-gated step.
repo-lint 0 fail; gauntlet ALL GREEN (57 harnesses, +1).

Revert: git revert HEAD  (removes both scripts + the harness; the edge is untouched)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ZBxzAbmqwLW7jEmMG23Xw

D-113 AMENDMENT: "interfaces: the REST API" is FALSE -- base-interface addressing has no API ...

Measured on the live Office1 edge (OPNsense 26.1), while starting the D-115 q3
IPv6 deployment. D-113(a2)'s rationale asserts "everything else -- DHCP,
firewall, interfaces: the REST API." The interfaces half was never measured; it
was inferred from DHCP and firewall being API-native, and it is wrong.

Interfaces > [LAN] is served by /interfaces.php?if=lan -- a LEGACY PHP page.
Only the Devices and Neighbors sub-trees were migrated to MVC. There is no API
call that sets LAN's ipaddrv6. Measured: LAN vtnet0 currently has 10.10.0.1/24
and NO IPv6 at all.

What IS API-native (measured, not assumed): radvd (/api/radvd/settings/*,
currently 0 entries), Kea DHCPv6 (/api/kea/*), and Virtual IPs
(/api/interfaces/vip_settings/*, modes ipalias|carp|proxyarp on wan|lan|lo0).

This does NOT reopen (a2). The prohibition D-113 adopted is on hand-authored
config.xml and full rendered pushes -- the clobber path. D-113 separately
records "GUI access is a REQUIREMENT" as the constraint that eliminated VyOS and
plain-Linux, so a one-time operator GUI edit is the vendor interface the
decision PRESERVED, not a violation of it.

It DOES mean the chain is not fully API-scriptable for any edge needing IPv6 --
Office1 now, DC0/DC1 at Stage 3. Logged the open experiment: the radvd model has
NO prefix field (it derives the prefix from the interface's configured IPv6), so
whether an ipalias VIP satisfies that generator is UNKNOWN and is NOT assumed.

Doc only. No cloud state touched -- the audit was entirely read-only (GET).
repo-lint: 0 fail (1 documented legacy warn).

Revert: git revert HEAD

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ZBxzAbmqwLW7jEmMG23Xw

Pin Stage 2 as the branch merge point; reconcile the Stage 2 tracker; log the OpenTofu naming collision (gap #19) ...

Operator ruling 2026-07-14: branch dc-dc-stage1-phase0-first-exec merges to
main at STAGE 2 CLOSE, not at session end. Recorded in the ledger's PINNED
section (a ruling, not an open question) and in the workflow doc's Stage 2
section, which now carries the C1..C5 close-out checklist that defines what
"closed" means. This is NEW policy: main has never taken a feature merge, so
all 52 commits of VR1 work live only on the branch.

The Stage 2 status block was STALE -- it still listed MAAS-region, LXD, the
LXD-KVM-host registration and both composed service machines as NOT DONE. All
of that landed 2026-07-13, and the route enable + the D-115 carve import have
landed since. Corrected against measured state; the doc has now drifted three
times and says so. Stage 2 is in CLOSE-OUT, not build.

GAP #19 (new, BLOCKING Stage 3): "dc1" now names two different datacenters.
D-117 moved the repo to the apex's 0-indexed convention on the IMPORT PATH
ONLY. opentofu/main.tf still says dc1_planes/dc2_storage for VR1's FIRST and
SECOND DCs, and lib-net.sh's dc0 means VR0's DC0 -- a different region, and a
RUNNING cloud. So the next DC we deploy is simultaneously apex vr1-dc0,
OpenTofu dc1_*, and a $DC value that collides with the live testcloud. A
mechanical sed would hand VR1's first DC VR0's deployed literals. Nothing in
opentofu/ gains a new DC-keyed module until this is closed.

Docs only -- no script, no tooling, no cloud state touched.
repo-lint: 0 fail (1 documented legacy warn).

Revert: git revert HEAD

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ZBxzAbmqwLW7jEmMG23Xw

D-118 ADOPTED (org ULA fd50:840e:74e2::/48); VR1 DC0 + DC1 IMPORTED; roles importer bug fixed ...

D-118: ORG_ULA_48 = fd50:840e:74e2::/48. RFC 4193 valid (fd -> L=1, 40-bit Global
ID 0x50840e74e2, /48 -> 256 x /56 for D-101's per-DC /56). The load-bearing check
is NOT the RFC conformance -- it is that it does NOT collide with Tailscale's
fd7a:115c:a1e0::/48: office1-tailscale runs --accept-routes, so an overlap would
have been a LIVE tailnet routing conflict, not a paper one.

Provenance stated honestly: the 'CSPRNG-generated' claim cannot be re-verified.
It does not change the ruling (RFC 4193's SHA1 construction is a SHOULD; the
requirement is a pseudo-random 40-bit Global ID). Regenerating would only swap in
a different random number at the cost of re-editing 7 places.

Corrects a FALSE claim: changelog-20260711 called this value 'ratified' when no
D-number ever assigned it. That phantom ratification is why it read as settled for
two days. Same failure mode as D-117: a document asserting authority it lacked.

IMPORTED into the sandbox: six-plane roles + 2 RIRs + 5 aggregates, then VR1 DC0
(18 prefixes) and VR1 DC1 (18). The D-117 fix is now LIVE-PROVEN, not just green
offline: --dc dc0 -> apex site VR1 DC0 (id=8), --dc dc1 -> VR1 DC1 (id=9). ULA
reads DC.NN in the 4th hextet per D-111 (fd50:840e:74e2:220:: .. :350::).

A REAL BUG, found by running roles-aggregates-import.py for the first time for
real: it checked existence by SLUG only, but NetBox also enforces UNIQUE NAMES.
The draft's legacy role 'Replication' (slug repl) blocks the six-plane role (slug
replication, name Replication) -- so it created 4 roles, 400'd on the 5th, and
DIED, leaving the apex HALF-POPULATED with no RIRs, no aggregates, no rollback.
It had never met a NetBox holding the real draft (only empty ones) and it SHIPPED
WITH NO HARNESS. That is why it survived.
  - six-plane role renamed 'Replication Plane' (slug unchanged -- lib-net.sh
    SPACES6 and the prefix importer look up 'replication')
  - the script now PREFLIGHTS every name/slug and writes NOTHING unless the whole
    plan is viable. An IPAM importer that can die partway corrupts what it
    populates.
  - tests/roles-aggregates-import/ CREATED: 16/16 PASS.

Final state PROVEN by sandbox-fidelity-check (now carrying the full planned
delta): the sandbox is the upstream draft + EXACTLY D-115 + D-117 + D-118 --
every shared object field-identical, nothing lost, nothing stray. 90 -> 134
prefixes.

repo-lint 0 fail. run-tests-all: ALL GREEN (56 harnesses).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ZBxzAbmqwLW7jEmMG23Xw

Prove the sandbox is a FAITHFUL replica, not just a count-matching one ...

netbox/sandbox-fidelity-check.py (+4 assertions in tests/sandbox-seed, 22/22 PASS)

Counts and idempotency CANNOT prove a faithful seed. The region-scope bug proved
it: 17 of 90 prefixes silently lost their scope, every count still matched, and
re-runs were still perfectly idempotent. It was caught by LUCK on a spot-check
that happened to print 'site None'. This is that catch, made deliberate.

Method needs no new plumbing: prod-draft-dump.py is READ-ONLY, so point it at the
sandbox and diff the two JSON dumps FIELD BY FIELD.

RESULT: every shared object is field-level IDENTICAL to upstream, and the delta is
EXACTLY the expected D-115 additions (+edge role, +vr1-off1 site, +8 prefixes).
Nothing missing, nothing unexpected. The sandbox is a PROVEN baseline -- which is
what the later feed-back diff to production depends on.

Also de-misdirects docs/dc-dc-netbox-buildout-scope.md, which still told the next
person to run '--dc dc2' with DC2_V4_SUPERNET -- both of which the new guards now
REJECT by name. Its G5 recommendation (rename the APEX to vr1-dc1/vr1-dc2) is
marked SUPERSEDED: D-117 ruled the opposite. ORG_ULA_48 is now listed there as
UNASSIGNED and BLOCKING, not as a settled literal.

Disclosure: D-117 Option B is PARTIALLY executed -- the import path and the scope
doc are done; the $DC shell selector and the runbook DC prose are NOT. Recorded
in the ledger so 'D-117 ADOPTED' is not misread as 'fully renamed'.

repo-lint 0 fail. run-tests-all: ALL GREEN (55 harnesses).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ZBxzAbmqwLW7jEmMG23Xw

D-115 office carve IMPORTED into the Office1 NetBox; DC import blocked on ORG_ULA_48 ...

netbox/d115-office-carve.py (+ tests/d115-office-carve/ 20/20 PASS)

Applied to the Office1 sandbox: site vr1-off1, roles office + edge (edge is NEW),
and 8 prefixes. Idempotent (re-run: 0 created / 11 present).

  10.10.0.0/16      office container   the Office v4 block, /22 per office
  10.10.0.0/22      office container   VR1 Off1's /22
  10.10.0.0/24      office active      office1-local LAN   (Kea on the edge)
  10.10.1.0/24      office active      lxdbr0 compose net  (MAAS DHCP)
  172.30.0.0/16     edge   container   NEW Edge role; mirrors v6 2602:f3e2:fe::/48
  172.30.1.0/24     edge   active      office1-wan, the simulated ISP uplink
  2602:f3e2:f01:/56  office container  mirrors VR0 Off0's e01:/56
  2602:f3e2:f01:/64  office active     office subnet (NOT deployed; v6 has no egress)

Every address was already RUNNING. D-115 blesses what is deployed -- zero
renumber. What it fixes is that three of them were SQUAT: on the wire with no
allocation behind them.

Writing upstream is GATED IN CODE: the tool refuses a non-sandbox target unless
given --yes-write-upstream. Feeding the production apex is an operator decision,
never a side effect of running an import.

BLOCKED, deliberately: dc-dc-prefixes-import.py --dc dc0 CANNOT run. It needs
ORG_ULA_48, which is still UNASSIGNED (gap G3; the scope doc recommends
fd50:840e:74e2::/48 but no ADOPTED decision assigns it -- grep ORG_ULA
design-decisions.md returns nothing). Using it anyway would be an inferred value
(hard rule 2). This is a DECISION gate, not a tooling gap: the tooling is fixed,
tested and ready. Recorded in the ledger with the exact commands to unblock.

Also: docs/vr1-office1-as-built.md gains the IPAM table, and records that the
Tailscale 10.10.0.0/22 route is now ENABLED (edge GUI reachable from the
workstation with no tunnel), superseding the tunnel instructions.

repo-lint 0 fail. run-tests-all: ALL GREEN (55 harnesses).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ZBxzAbmqwLW7jEmMG23Xw

NetBox sandbox seeded from the upstream draft (129 objects) + the two-phase tooling ...

The Office1 sandbox NetBox was EMPTY, and no seeder existed. The documented loop
(upstream draft -> sandbox -> simulate -> feed back) had no first step.

netbox/prod-draft-dump.py   READ-ONLY dump of the upstream draft -> JSON artifact
netbox/sandbox-seed.py      applies that JSON to a SANDBOX. Dry by default.
netbox/draft/vr1-draft.json the reviewable artifact (90 prefixes, 23 roles, ...)

TWO PHASES, deliberately, rather than one source->dest script:
  - the upstream token never travels (dump runs on vcloud; seed runs on
    office1-netbox, where the sandbox token already lives)
  - 'the sim NEVER writes upstream' becomes STRUCTURAL: the script that writes
    has no upstream credential and no upstream URL, and REFUSES to write to the
    instance the draft was read from (self-configuring via the draft's _source,
    so it keeps working if upstream ever moves -- a hostname denylist would not)
  - the JSON is diffable: you can read what is about to be written

Applied to the sandbox: 129 created, then verified idempotent (0 created / 129
present on re-run). vr1-dc0 -> f02::/48 and vr1-dc1 -> f03::/48, matching the
apex exactly, which is what D-117 exists to guarantee.

TWO BUGS FOUND AND FIXED WHILE BUILDING IT:
  1. The dry run mapped only dcim.site scopes, so REGION-scoped prefixes lost
     their scope -- 17 of 90 upstream, including the ENTIRE VR1 region-scoped
     draft. Caught by a spot-check printing 'site None'. Fixed + reseeded
     (--update), now bound to region VR1.
  2. The upstream-refusal guard sat AFTER json.load() and after the banner: it
     was dead code for any malformed draft and READ as safe. Guards go first.
     The harness now proves it actually refuses.

tests/sandbox-seed/: 18/18 PASS. repo-lint 0 fail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ZBxzAbmqwLW7jEmMG23Xw

D-117 ADOPTED (B, DC-only): fix the off-by-one site binding + make the importer dry-by-default ...

Operator ruling: rename the DC numbers to match the NetBox apex; the office
keeps its number (Office1 -> new site vr1-off1, so nothing deployed changes).

netbox/dc-dc-prefixes-import.py:
  --dc dc1|dc2  ->  --dc dc0|dc1, bound to the APEX slugs measured live:
    dc0 -> vr1-dc0 (2602:f3e2:f02::/48)    dc1 -> vr1-dc1 (f03::/48)
  It previously mapped dc1 -> vr1-dc1 while treating f02::/48 as dc1, i.e. it
  would have written VR1 DC0's prefixes to the OTHER DC's site.
  Now DRY BY DEFAULT with --commit (it used to write with no flag at all).
  A dry run against a FRESH NetBox now plans the site too (_PlannedSite) rather
  than bailing with 'no site id' -- previewing an empty apex is the whole point.
  DC2_V4_SUPERNET is REJECTED BY NAME (retired) rather than silently ignored.
  Every 'DCn' in prose is region-qualified: 'DC0' meant VR0's rehearsal DC in
  some sentences and VR1's first DC in others. No sed could have caught that.

tests/dc-dc-prefixes-import/: 73 checks ALL PASS, incl. regression guards that
  the dry run creates NOTHING, that --dc dc0 never touches vr1-dc1, and that the
  invented vr1-dc2 site is never created.

FOUND, RECORDED, NOT YET FIXED (D-117 amendment): scripts/lib-net.sh carries a
SECOND, colliding $DC namespace where dc0 already means VR0's DC0. Renaming
VR1's dc1->dc0 there would collide with VR0. Proposed fix: region-qualify the
shell selector to the apex slugs (vr0-dc0/vr1-dc0/vr1-dc1). Does not block the
import; the two selectors are NOT interchangeable meanwhile.

repo-lint 0 fail. run-tests-all: ALL GREEN (53 harnesses).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ZBxzAbmqwLW7jEmMG23Xw

D-117 (PROPOSED): VR1 site naming collision blocks the NetBox import ...

Measured live against the apex: prod NetBox binds 2602:f3e2:f02::/48 -> site
VR1 DC0, but dc-dc-prefixes-import.py maps --dc dc1 -> slug vr1-dc1 and treats
f02::/48 as dc1. The addressing agrees; the labels are off by one. Because that
importer has NO --commit (it WRITES BY DEFAULT), running it as documented against
a prod-seeded NetBox would silently bind DC1's prefixes to the other DC's site.

This is the known G5 gap, promoted to a decision because it blocks the import.
Options A/B/C recorded; A (rename the two skeletal apex sites) recommended, with
the slug-collision rename ORDER called out as a trap.

Also records the upstream-NetBox User-Agent WAF trap in platform-traps.md: the
same token that works from curl gets 403 from urllib/requests/pynetbox. It will
bite pynetbox and looks exactly like an auth failure.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ZBxzAbmqwLW7jEmMG23Xw

D-116 ADOPTED: no Office1-local GitBucket -- keep using git.baldurkeep.com ...

Operator ruling: "we've decided not to build a separate one on the test cloud. We will continue to
use the current setup and create new repos for deployment tasks as needed."

SUPERSEDES the GitBucket half of D-103 (which gave Office1 three service VMs) and removes GitBucket
from Stage 2's build list entirely. Office1's MAAS-composed service machines are now exactly TWO --
office1-netbox and office1-tailscale -- and both are LIVE.

WHAT THIS ACTUALLY CLOSES, and why it is a simplification rather than a deferral: the Stage 2 runbook
carried an OPEN QUESTION about the Office1-local GitBucket -- "what it mirrors, and under what repo
path, is not decided" -- because a SECOND GitBucket alongside the pre-existing git.baldurkeep.com
raised a real authority/mirroring question nobody had answered. That question is now MOOT. There is
one git service, it is the existing one, and it is authoritative.

Recorded explicitly in D-116 so nobody misreads the scope: D-107's per-DC ARTIFACT mirror (OS/package
artifacts for node provisioning) is a SEPARATE concern and is NOT affected. And if Roosevelt later
wants a site-local git service, that is a fresh decision against real requirements -- not something
this ruling forecloses.

Applied everywhere it was an instruction, not just recorded:
- runbooks/dc-dc-phase1-office1-standup.md: Step 11 replaced with a TOMBSTONE (kept rather than
  deleted -- step numbering is referenced elsewhere, and someone WILL come looking after reading
  D-103); removed from the sequence, the compose steps, and the open-questions list.
- docs/dc-dc-deployment-workflow.md: dropped from Stage 2's Build and, importantly, from its GATE --
  "GitBucket serving" is no longer a gate condition.
- docs/design-decisions.md: D-103 annotated in place with the supersession, so grepping for GitBucket
  lands on the amendment rather than the stale instruction.
- docs/vr1-office1-as-built.md + session ledger updated.

repo-lint 0 fail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Tailscale: office1-tailscale joined the SELF-HOSTED tailnet as the Office1 subnet router ...

Operator's control plane is self-hosted (https://tailscale.baldurkeep.com:443), NOT Tailscale's
public one -- so the public login-URL flow from the previous commit was void. Node reset off
controlplane.tailscale.com and re-enrolled against the operator's server with their auth key.

REACHABILITY PROVEN FIRST, not assumed: DNS + TCP 443 + HTTPS to tailscale.baldurkeep.com confirmed
from the node BEFORE running `tailscale up`, so a failure would have been a network fact rather than
a confusing registration error.

AS BROUGHT UP: --login-server=https://tailscale.baldurkeep.com:443 --authkey=<from 0600 file>
--advertise-routes=10.10.0.0/22 --accept-routes --accept-dns=false --hostname=office1-tailscale

Online as 100.64.0.53 (fd7a:115c:a1e0::35), no health warnings, advertising 10.10.0.0/22 -- exactly
the D-115 Office1 carve, so D-107's "Office1 ONLY" front door is enforced by the CARVE itself rather
than by policy alone.

ONE DELIBERATE DEVIATION from the operator's usual command: --accept-dns=false. This is a
MAAS-managed machine and MAAS's bind9 serves its internal names; letting the tailnet take over DNS
would break that resolution. Flagged rather than silently applied -- trivial to flip if MagicDNS is
wanted here.

OPERATOR ACTION STILL REQUIRED: the 10.10.0.0/22 route is ADVERTISED but must be ENABLED on the
control server (Headscale: `headscale routes enable`) before other tailnet nodes route to Office1.
Once enabled, the whole Office1 carve -- edge GUI, MAAS UI, NetBox -- is reachable from the tailnet
with NO SSH tunnels, superseding most of the tunnel commands in the as-built doc.

SECRET HANDLING: the auth key was written by the operator to a 0600 file OUTSIDE this session,
consumed BY PATH, never printed into context, and the copy shipped to the node was SHREDDED after
enrolment (tailscaled holds its own node key now). Tracked as SEC-008 -- a rotation obligation, not
a delete-me, since the key remains on vcloud for re-enrolment.

docs/vr1-office1-as-built.md updated with the tailnet addresses, the exact bring-up command, the
DNS deviation, and the pending route-enable step.

repo-lint 0 fail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Office1: edge route to the compose net + Tailscale subnet router + an as-built connection reference ...

THE ROUTE -- and an OUTAGE I CAUSED AND REVERTED. Adding a LAN gateway on OPNsense for voffice1
SILENTLY STOLE THE DEFAULT ROUTE: the edge's default flipped from 172.30.1.1 (ISP) to 10.10.0.20,
and the site lost egress. Root cause: OPNsense's `defaultgw` field in the API output is DERIVED
FROM `priority` (lower = more preferred), NOT from the value you send -- I sent defaultgw="0", it
came back True, and I had ALREADY run `reconfigure` before reading anything back. Detected within
~2 minutes by checking egress, reverted by deleting the gateway; default route and egress restored.

Redone SAFELY: add the gateway, READ THE CONFIG BACK, verify WAN_GW is still the default, and only
THEN apply. WAN_GW is now priority 1 (explicitly preferred); OFFICE1_LXD_GW is 255. Verified after
apply: default still 172.30.1.1, egress OK, and the edge now routes 10.10.1.0/24 -> 10.10.0.20 and
reaches NetBox. The lesson is in the as-built doc's trap list.

Also re-learned the hard way: root's shell on the edge is tcsh, so `2>&1` in my verification command
died with "Ambiguous output redirect" -- the exact trap already written down in this repo's standing
lessons. Feed remote commands to `sh -s`.

TAILSCALE: office1-tailscale composed by MAAS (2 cores / 2 GiB / 25 GB -- VR0's sizing), deployed
Ubuntu 24.04, Tailscale 1.98.8 installed, IP forwarding on, brought up as a SUBNET ROUTER advertising
10.10.0.0/22 -- exactly the D-115 Office1 carve, so "Office1 only" (D-107) is enforced by the carve
itself. Authenticated via the login-URL flow, NOT an auth key: no tailnet secret passes through the
session. PENDING OPERATOR: authorize the node, and approve the 10.10.0.0/22 route in the admin
console. The tailnet ACL/tag policy remains operator design (runbook open question 5).

NEW: docs/vr1-office1-as-built.md -- the operator-requested connection reference. Every value
MEASURED, not planned: networks + who owns DHCP on each, hosts/services/levels, how to reach each
thing from vcloud AND from a workstation, where every credential lives, and the site's standing
traps. Explicitly NOT an address authority -- NetBox is the IPAM apex; this is operational.

Also noted: MAAS's bind9 intermittently SERVFAILs a first-time external lookup and succeeds on
retry (seen twice -- docker registry, tailscale.com). Retry before diagnosing.

repo-lint 0 fail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

office1-netbox DEPLOYED: NetBox 4.6.4 live on the Office1 headend, three levels deep ...

MAAS composed the machine, PXE-booted it, commissioned it, and DEPLOYED Ubuntu 24.04.4 onto it --
an LXD VM inside voffice1, inside vcloud, which is itself a KVM guest. NetBox 4.6.4 (Django 6.0.6)
runs on it and its API returns HTTP 200. The D-114 chain is complete in its final form.

FOUR FINDINGS. TWO ARE NOW GUARDED IN CODE.

1. MAAS-DISCOVERED SUBNETS HAVE NO GATEWAY (FIXED). MAAS discovers the compose subnet from lxdbr0's
   interface, and that discovery carries no gateway_ip. The first deploy produced a machine that
   LOOKED healthy -- it had an address and DNS even resolved (MAAS's bind9 is link-local) -- but had
   NO default route and NO egress. It only surfaces when the first apt install hangs.
   scripts/site-headend-install.sh now sets gateway_ip on the compose subnet; the harness asserts it
   (19/19). office1-netbox was released and REDEPLOYED to prove the fix rather than hand-patching a
   route onto the running box.

2. NETBOX 4.6 v2 TOKENS: THE WIRE FORMAT IS `nbt_<key>.<plaintext>`, NOT THE API's `token` FIELD.
   NetBox 4.6 hashes tokens: `key` is a 12-char PREFIX, plus `plaintext` and an hmac_digest.
   Authentication infers the version FROM A PREFIX (TOKEN_PREFIX = 'nbt_') and splits on '.'. So the
   57-char assembled form is what authenticates. POST /api/users/tokens/provision/ returns `key` and
   `token` as SEPARATE fields, and the `token` field alone is NOT usable -- present it raw and NetBox
   parses it as a legacy v1 token and returns 403 "Invalid v1 token", an error that names v1 while
   you are holding a v2 token. Anything scripted against this NetBox (including
   netbox/dc-dc-prefixes-import.py and any pynetbox client) must ASSEMBLE the token.
   Also: netbox-docker's SUPERUSER_API_TOKEN env is NOT honored on this version, and hand-building a
   Token row trips the DB's enforce_version_dependent_fields constraint. Call the interface; do not
   re-implement it -- the same lesson this repo already learned minting OPNsense API keys, which I
   proceeded to re-learn the hard way.

3. A WRONG HYPOTHESIS, RECORDED BECAUSE THE MISTAKE IS REUSABLE. When the token kept 403-ing I
   concluded that rotating SECRET_KEY after NetBox had initialised must have broken the token HMAC
   pepper, and I WIPED THE DATABASE (docker compose down -v) to re-init. That was WRONG -- the 403
   was purely the wire format above. The wipe was harmless because the DB was empty, but the
   reasoning was not: on a populated NetBox it would have been destructive. "Invalid v1 token" is a
   FORMAT error, not a crypto or key-rotation error. Read the auth code before reaching for a
   destructive reset.

4. netbox-docker ships a PUBLIC default SECRET_KEY (it is in the public repo) -- session-forgery
   material on any reachable instance. Rotated to a generated value. (SKIP_SUPERUSER=true is the
   shipped default, so no default admin/admin exists.)

All secrets (SECRET_KEY, admin password, API token) generated ON the VM, stored 0600 under
/root/netbox-secrets/, never printed into the session.

REACHABILITY CAVEAT, not solved: NetBox is on 10.10.1.201, behind voffice1's NAT. Reachable from
voffice1, NOT from office1-local or a workstation. Making it reachable needs a static route for
10.10.1.0/24 via 10.10.0.20 on the OPNsense edge -- a live edge change, deliberately NOT done
unilaterally.

NEXT: import the D-115 carve into this NetBox.

repo-lint 0 fail. tests/site-headend-install 19/19 PASS.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Ledger: pin Office1 LAN IPv6 as the next step after the NetBox deploy (D-115 q3) ...

Operator sequenced it: NetBox first, then dual-stack. Pinned with its known limit attached so the
next session cannot mistake internal v6 for working v6 -- IPv6 does not egress the lab (measured),
so the LAN leg proves addressing/RA/services-binding and nothing about internet GUA reachability.
The WAN v6 leg is DEFERRED: it would be a path to nowhere and untestable.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

D-115 ADOPTED: v4 stays role-based; Office = /22 per office; DC2 moves INSIDE the Cloud /16 ...

Operator ruled all three questions:
1. v4 stays ROLE-BASED, fill the missing roles (v6 keeps its region hierarchy; v4 is pooled by
   function -- v6 is abundant, v4 is scarce). No DC renumber; D-101's inherit-DC0-unchanged
   economy is preserved.
2. /22 per office. VR1 Office1 = 10.10.0.0/22 -- which BLESSES the deployed LAN (10.10.0.0/24) and
   LXD compose net (10.10.1.0/24) exactly. ZERO deployment renumber.
3. Register AND deploy dual-stack on Office1 now.

THE CARVE. New v4 roles: Office (10.10.0.0/16, /22 per office) and Edge (172.30.0.0/16, mirroring
v6's Edge Networks fe::/48) so the simulated ISP uplinks stop living inside the Corp OOB block --
office1-wan's 172.30.1.0/24 becomes legitimate. DC2 moves from 10.13.0.0/19 to 10.12.64.0/19,
INSIDE the Cloud /16: free (DC1 holds 10.12.{4,8,12,16,32,36}), still routable to DC1 over the
dark fiber. docs/dc-dc-netbox-buildout-scope.md is corrected -- its 10.13.0.0/19 recommendation sat
outside every allocated block and would have had DC2 squatting too.
v6 is determined by the existing pattern, no design freedom: Office1 = 2602:f3e2:f01:/56 with
a /64 office subnet, plus a "VR1 Off1" site. (VR0 Off0 = e01:/56 -> /64; Eugene's Charnelton =
101:/56. VR1's office /48 already existed and we were simply not using it.)

MEASURED CONSTRAINT, attached before anyone builds on a false premise: IPv6 DOES NOT EGRESS THE LAB.
vcloud has global v6 and a v6 default route, and the v6 gateway IS reachable (RA and L2 work) -- but
v6 INTERNET is unreachable (2606:4700:4700::1111 and 2001:4860:4860::8888 both 100% loss; v4 from the
same host is fine). So deploying dual-stack on Office1 proves v6 ADDRESSING/RA/services-binding-v6 --
most of D-101's family matrix, worth doing -- but it CANNOT prove v6 internet reachability. Public
GUA reachability (v6 public API endpoints, tenant GUA egress) is UNPROVABLE IN VR1 until the lab's
upstream carries v6. That is outside this cloud and this repo. Do not schedule a VR1 test that
depends on it, and do not read a green internal-v6 result as "v6 works end to end".

The NetBox WRITE is deliberately NOT done unilaterally: netbox.baldurkeep.com is production, the
standing architecture is read=source / write=feedback-only, and the Office1 sandbox NetBox (composed,
Ready, not yet deployed) is where this carve gets simulated first.

repo-lint 0 fail -- and its L5 collision guard did its job, catching that my amendment header read
as a second DEFINITION of D-115. Renamed to the AMENDMENT form the guard exempts rather than
weakening the rule.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

D-115 PROPOSED: Office1 addressing -- the office carve, and the four v4 role gaps it exposed ...

Operator challenge during deployment testing ("I thought there were corp office subnet carves in
the planning") -- and they were right. I had checked for COLLISIONS but never asked the IPAM apex
whether Office1 had an ASSIGNED carve. It does, in v6, and we were not using it.

MEASURED against the live NetBox (read-only), not the repo -- the repo's planning docs cover only
the DC planes, so grepping them would never have found this:

IPv6 is a complete region-hierarchical model. Every region gets a /40; sites are /48s on a FIXED
slot pattern: X00=infrastructure, X01=OFFICES, X02/X03=datacenters. VR1's office /48 ALREADY EXISTS
(2602:f3e2:f01::/48). Offices take one /56 each, then a /64 subnet -- VR0 Off0 = e01:/56 ->
e01:/64; Eugene's Charnelton = 101:/56. So Office1's v6 has NO design freedom: it is
2602:f3e2:f01:/56 + a /64. Office1 currently has NO IPv6 AT ALL -- D-101's dual-stack family
matrix silently skipped the office.

FOUR v4 GAPS, none previously known:
1. There is NO Office role in v4. Office1's LAN (10.10.0.0/24) and LXD compose net (10.10.1.0/24)
   are squat -- colliding with nothing, blessed by nothing.
2. DC2's planned 10.13.0.0/19 is OUTSIDE the Cloud /16 (10.12.0.0/16). The scope doc recommends it;
   NetBox never allocated it. DC2 was already set to squat and nobody had noticed.
3. office1-wan (172.30.1.0/24) squats INSIDE 172.16.0.0/12 "Corp OOB Private" -- and it is not OOB,
   it is a simulated ISP uplink. A wrong-ROLE problem, not just an unregistered one.
4. "Edge Networks" has a v6 /48 (2602:f3e2:fe::/48) but NO v4 counterpart, so the ISP-sim WAN
   segments have nowhere legitimate to live in v4.

THE TENSION TO RULE ON: v6 here is region-hierarchical, v4 is role-based. That asymmetry is
defensible -- v6 is abundant so it gets geography, v4 is scarce so it gets pooled by function.
Mirroring v6's region tree in v4 would force RENUMBERING DC1 off 10.12.x, breaking exactly the
inherit-DC0-unchanged economy D-101 bought to reuse VR0's bundle. Large cost for tidiness.

Recommended option (a): keep v4 role-based and fill the MISSING roles -- an Office /16 carved /22
per office (VR1 Office1 = 10.10.0.0/22, which BLESSES the deployed LAN + compose net exactly, zero
renumber), an Edge role (172.30.0.0/16, mirroring v6's fe::/48) so the ISP-sim WANs stop living in
the OOB block, and DC2 pulled INSIDE the Cloud /16 at 10.12.64.0/19 (free; DC1<->DC2 stay routable).
Option (b) mirrors v6 and renumbers the DCs. Option (c) ratifies the squat verbatim -- rejected.

PROPOSED, not adopted: presenting options, not picking. Nothing is blocked -- Office1 is live and
routing. But the renumber cost is LOWEST RIGHT NOW, before NetBox and GitBucket deploy onto it.

repo-lint 0 fail. No live system touched (NetBox reads were read-only).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Office1 headend LIVE: MAAS 3.7.2 + LXD 5.21 on voffice1. D-114 PROVEN END TO END. ...

MAAS composed, PXE-booted and COMMISSIONED its first VM inside voffice1. The model works.

  vcloud            (L1 -- itself a KVM guest, measured)
    +- voffice1     (L2)  MAAS 3.7.2 region+rack + PostgreSQL 16.14 + LXD 5.21.5
         +- office1-netbox (L3)  LXD VIRTUAL-MACHINE, MAAS-composed, MAAS-PXE-booted,
                                 leased 10.10.1.100 from MAAS, status READY, 2c/4096MiB detected

THE L3 PROOF IS NOW DEFINITIVE. Earlier today we could only say nested KVM was AVAILABLE
(/dev/kvm + svm present). Now a guest has actually BOOTED, PXE'd, COMMISSIONED and reported its
hardware three levels deep. D-114's Office1 gate is CLEARED. This reproduces VR0's `lxd` +
`tailscale` pattern exactly -- and the Juju-created LXD CONTAINERS remain invisible to MAAS, as in VR0.

THE DHCP SPLIT IS STRUCTURAL, NOT CONVENTIONAL:
  10.10.0.0/24 (site LAN)   -> Kea on the OPNsense edge   MAAS dhcp_on=False
  10.10.1.0/24 (lxdbr0)     -> MAAS                        MAAS dhcp_on=True
Separate L2s; lxdbr0 is never bridged onto the site LAN, so they cannot see each other. The
installer asserts after configuring DHCP that MAAS owns NO other subnet, and hard-fails otherwise.

NEW: scripts/site-headend-install.sh + tests/site-headend-install/ (18/18 PASS). It is the sequence
we ACTUALLY EXECUTED, codified -- not written from docs -- and reusable verbatim for DC1/DC2. Its
--check mode was run against the live voffice1 and reports every item OK.

FOUR TRAPS, ALL HIT FOR REAL TODAY, ALL NOW ENCODED AND HARNESS-ASSERTED:
1. `lxd init --auto` FAILS on a MAAS host. It brings up lxdbr0 with LXD's own DHCP+DNS, which starts
   a dnsmasq; dnsmasq binds the WILDCARD 0.0.0.0:53 and MAAS's bind9 already holds :53. The error
   names the BRIDGE address ("failed to create listening socket for 10.10.1.1"), which sends you
   hunting the wrong thing. `ipv4.dhcp=false` + `dns.mode=none` are NOT enough -- LXD still spawns
   dnsmasq. The fix is raw.dnsmasq="port=0". Verified after: dnsmasq holds ZERO :53 and ZERO :67.
2. `lxc` READS CONFIG FROM STDIN. Piped to `bash -s` over ssh, the first unredirected `lxc` call
   EATS THE REST OF THE SCRIPT as YAML and everything after it silently vanishes. Every lxc call now
   ends in </dev/null. Same class as the OPNsense tcsh trap.
3. LXD snap track changes are ONE-WAY -- install DIRECTLY onto 5.21/stable, never via `latest`.
   MAAS 3.6/3.7 is incompatible with LXD >= 6.7. (Bonus: core.trust_password exists in 5.21, gone in
   6.x -- the pin also preserves the scriptable registration path.)
4. MAAS DHCP on the compose network ONLY. --compose-cidr is REQUIRED with no default so it can never
   be picked by accident.

DISCIPLINE: every MAAS/LXD flag was read from the tool's own --help ON THE BOX before use (maas init,
createadmin, vm-host compose), not trusted from docs. All secrets (DB, admin, API key, LXD trust) are
generated on the target, stored 0600 under /root/maas-secrets/, and never printed into the session.

10.10.1.0/24 IS AN UNBLESSED ALLOCATION -- chosen deliberately (DC1=10.12.x, DC2=10.13.0.0/19, tenant
pool=10.20.0.0/16 per D-016; the obvious 10.20.x would have COLLIDED with tenant space), but NetBox
has not assigned it. Register once NetBox exists -- it is one of the VMs this headend composes.

Also: the ops skill is now tuned to this exact stack (new references/platform-traps.md with a
verbatim-error -> cause index; the OPNsense section that still routed sessions into the DELETED
config-ISO path is replaced). Upstream corroboration found for two of our own findings: the libvirt
provider's release notes document that an "in-place" domain update undefines and re-defines the
domain (our measured guest-bounce), and there is an upstream issue for the AppArmor denial.

Gauntlet ALL GREEN (53 harnesses). repo-lint 0 fail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

D-114 follow-through: fix node-vm's nested-virt defect NOW; voffice1 pinned to a reserved address ...

Operator ruling: fixes land as we find them -- only DC1 DEPLOYMENT is gated, not DC1 fixes.

1. modules/node-vm: UNCONDITIONAL `cpu = { mode = "host-passthrough" }`. Same defect just found in
   cloudinit-vm: with no cpu block libvirt hands the guest a generic emulated CPU with NO svm. A DC
   node runs nova-compute, so it MUST run KVM guests -- there is no correct value other than this,
   hence no knob that could only ever be set wrong (contrast cloudinit-vm, where it IS a real per-VM
   decision, and opnsense-edge, which disables svm as correct hardening for a router). Not yet
   instantiated, so no live call breaks. Without it the DC nodes would have come up looking healthy
   and been unable to launch a single instance -- surfacing in Stage 5 as an inscrutable scheduler error.

2. voffice1 moved off the dynamic pool onto a RESERVED address. It first took 10.10.0.100 -- the
   first address of Kea's pool (.100-.199). A MAAS region controller must not hold an address that
   can move. Added a Kea host reservation via the D-113(a2) REST API (a second live exercise of that
   write path): 52:54:00:6a:87:e5 -> 10.10.0.20, deliberately OUTSIDE the pool. add_reservation ->
   "saved", service/reconfigure -> "ok". Rebooted; voffice1 came back on 10.10.0.20, .100 released,
   /dev/kvm still present. Done now because nothing depends on the address yet.

3. runbooks/dc-dc-phase1-office1-standup.md rewritten to the D-114 model (was: three sibling service
   VMs + an unruled Option A/B fork -- it would have actively misdirected whoever ran it). New
   sequence: voffice1 via tofu -> first contact (lease/SSH/nested-KVM) -> MAAS on voffice1 -> LXD
   (5.21 LTS) -> register LXD as a MAAS VM host -> MAAS-COMPOSE NetBox/GitBucket/Tailscale. The
   MAAS/LXD command lines carry explicit PENDING VERIFICATION markers rather than fabricated flags.
   docs/dc-dc-deployment-workflow.md Stage 2 + gap register updated to match.

repo-lint 0 fail. opentofu-validate PASS.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

D-114: voffice1 is LIVE. cloudinit-vm gains nested virt -- it was silently broken for the model ...

APPLIED, operator-approved: 5 added, 0 changed, 0 destroyed. The running OPNsense edge was NOT
touched (confirmed by plan BEFORE apply -- no in-place update, so no repeat of the 2026-07-13
guest bounce).

THE MODULE WAS SILENTLY BROKEN FOR D-114'S ENTIRE MODEL. modules/cloudinit-vm's libvirt_domain
had NO `cpu` block. With none, libvirt renders a GENERIC EMULATED CPU exposing no `svm` -- and
LXD *virtual machines* are qemu/KVM guests, so NO service VM could ever have been composed into
voffice1. D-114 would have failed at its first step with a confusing "KVM not available" that
pointed nowhere near OpenTofu. Measured proof of the masking: host is an AMD EPYC 9965; a
default-CPU guest was handed an "Opteron_G3".

Fix: `cpu { mode = "host-passthrough" }` always, plus a new `expose_nested_virt` variable with NO
default -- a real per-VM decision. true = pass `svm` through (required for D-114's containment
VMs); false = disable it, matching modules/opnsense-edge. The operator asked whether the edge's
`svm` disable was a leftover of the failed OPNsense deploy: it is NOT. It was tried as a
triple-fault fix on 2026-07-12, did NOT resolve it (the real cause was the memory unit), and was
retained on hardening grounds. A router has no business seeing nested virt. It stays disabled there.

voffice1 as built (MEASURED): Ubuntu 24.04.4 LTS, 16 vCPU / 32 GiB / 600 GiB, single NIC on
office1-local, reports the real EPYC CPU with svm on all 16 cores and /dev/kvm PRESENT, egress to
1.1.1.1 at 4.6ms THROUGH the edge. Cloud-init deliberately MINIMAL (identity + key + guest agent);
MAAS and LXD go in as separate GATED steps rather than buried in a first-boot script that either
silently works or silently does not. The SSH pubkey is read via file(var...) at plan time -- key
material never enters a command line, the repo, or an agent's context; the tfvars holding the path
stays gitignored. network_config matches the NIC by GLOB, not a guessed kernel name (an inferred
value); it came up enp1s0.

TWO GATES CLEARED:
1. KEA HAS SERVED ITS FIRST REAL DHCP LEASE. Standing open item: the daemon was proven, the
   SERVICE never was (office1-local had no client). voffice1 -- the first client ever on that LAN
   -- took 10.10.0.100, hwaddr 52:54:00:6a:87:e5 (matches its NIC), hostname voffice1, state
   active, read back through the D-113(a2) REST API. DHCP now works end to end.
2. D-114's NESTING PROBE PASSES AT L3. Stated honestly: this proves nested KVM is AVAILABLE. The
   DEFINITIVE proof is a guest actually booting inside voffice1 -- that lands with the first
   composed LXD VM. Not recording L3 as fully proven until then.

FINDING, logged NOT actioned (DC1 is gated behind Office1 per D-114): modules/node-vm has the SAME
missing-cpu-block defect. DC nodes run nova-compute, which needs working KVM -- without the fix
they will come up unable to run a single instance. MUST be fixed before Stage 3.

opentofu-validate PASS, repo-lint 0 fail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

D-114 ADOPTED: VR1 site containment VMs + MAAS-composed LXD VMs for the non-stack machines ...

Operator ruling. AMENDS D-103 (which gave Office1 three sibling service VMs on vcloud).

WHAT THE OPERATOR'S SCREENSHOTS PROVED -- and where I was wrong. I had grepped bundle.yaml,
found only Juju's `lxd:N` CONTAINER placements, and concluded "there is no VR0 precedent for
MAAS composing LXD VMs -- zero." FLATLY WRONG. VR0's MAAS (3.7.2) has an `lxd` machine
registered back into MAAS as an LXD KVM host (LXD 5.21.4), and `tailscale` is a VM COMPOSED
BY MAAS INSIDE IT. The bundle's Juju LXD containers and MAAS's LXD VM host are TWO DIFFERENT
LXD usages in the same cloud; reading only the bundle collapses them into one. Recorded in the
decision because the error is instructive.

The ruling:
1. Non-stack machines (NetBox, GitBucket, Tailscale) become MAAS-COMPOSED LXD VMs -- MAAS-visible,
   enlisted/commissioned/deployed/powered. This is VR0's proven `lxd` + `tailscale` pattern per
   site, at ~2 cores / 2 GiB each. The Juju-deployed OpenStack services stay in Juju-created LXD
   CONTAINERS, invisible to MAAS, exactly as in VR0 -- per the operator, that visibility is not wanted.
2. Each site gets a containment VM (voffice1/vdc1/vdc2). The decisive rationale is the operator's:
   full-facility snapshots, and simulating total geographical failure of a facility. D-108's DR
   drill currently has NO honest "hard-down a DC" primitive -- `virsh destroy vdc1` IS that primitive.
   The flat model cannot offer this at any price.
3. Office1 FIRST, fully up; DC1 GATED behind it.
4. LXD pinned to the 5.21 LTS track: MAAS 3.6/3.7 is INCOMPATIBLE with LXD >= 6.7 (endpoint
   consolidation vs pinned pylxd 2.3.5). VR0 is on 5.21.4 -- safe by timing, now safe by decision.

KNOWN RISK: vcloud is itself a KVM guest (measured), so a containment VM puts servers one level
deeper than VR0 runs them. Office1 IS the nesting probe -- LXD VMs are qemu/KVM guests, so it
needs nested KVM at the same L3 depth the DCs would (an earlier draft of the entry said Office1
needed none; corrected in-entry). Office1 is simply the cheap place to prove it: no OpenStack,
no Ceph. DC1's gate additionally proves L4, the depth VR0 has never exercised.

Bonus: voffice1 booting on office1-local takes the FIRST REAL DHCP LEASE from Kea -- a path
proven only at the daemon level, never end to end.

repo-lint 0 fail. No live system touched.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Fold the AppArmor/libvirt rule into scripts/prereqs -- it gated every VR1 VM boot ...

`/var/lib/libvirt/vr1/** rwk,` in /etc/apparmor.d/local/abstractions/libvirt-qemu had
been applied BY HAND on vcloud and existed ONLY as host state. Nothing in the repo
carried it, so a rebuild or a second host walked straight back into the same wall.

Why it matters: libvirt's stock abstractions/libvirt-qemu grants qemu only the DEFAULT
pool path (/var/lib/libvirt/images). VR1 uses a custom pool parent, which is not in that
abstraction, so AppArmor blocks qemu even with perfect POSIX permissions. The domain
DEFINES fine, then fails to start with a bare qemu "Permission denied" -- and NOTHING in
the libvirt error names AppArmor. It cost a session on 2026-07-12 (DOCFIX-186), was
logged as a PREREQ candidate, and was never actioned until the ledger collapse resurfaced it.

New: scripts/prereqs/install-apparmor-libvirt.sh, wired into install-all.sh (after
install-virtualization -- it edits libvirt's own profile dir) and reported by
check-prereqs.sh.

- Idempotent and deliberately QUIET on a good host: if the rule is present it exits 0
  having touched nothing -- it does NOT reload apparmor or bounce libvirtd. Those happen
  only on the run that actually adds the rule.
- Writes to local/, the vendor-sanctioned override include, so it survives package upgrades.
- Pool parent is a variable (VR1_POOL_PARENT, default /var/lib/libvirt/vr1), not a literal.
- Non-AppArmor hosts report N/A and SUCCEED -- no manufactured failure on a host it
  does not apply to.

Verification: tests/prereqs 32/32 PASS (was 24/24) -- the new cases drive DETECTION off a
pool parent guaranteed absent from the profile, so the negative path is deterministic on
any host: a false OK from --check IS the bug, --dry-run must plan and mutate nothing, and
the planned rule must be exactly `<parent>/** rwk,`. Full gauntlet ALL GREEN (52 harnesses),
repo-lint 0 fail. Run live on vcloud: --check reports OK and leaves the profile byte-identical,
confirming the already-satisfied path is a true no-op.

No host state was mutated by this change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Ledger collapse: close the coverage gap in the carry-forward ...

The collapse commit's guards (lint, ASCII, ledger-scan, size) validated FORM, not
COVERAGE. Two ledger regions had only been keyword-grepped, not read. Read them.
Three items surfaced; each was VERIFIED against the repo rather than trusted:

- run-tests-all.sh dirtying the tree with 37 spurious mode-change diffs: NOW FIXED
  (the fakebin stubs are committed 100755 -- 36 of them, measured). Not carried.
- `scripts/opnsense-apply-config.sh` (once "wanted"): SUPERSEDED, and dangerous to
  build -- its snapshot/scp/install/reboot flow IS the config.xml path D-113(a2)
  deleted. Recorded as "do not build this", so nobody resurrects it from the history.
- The tcsh trap it taught is REAL and carried forward: root's shell on the OPNsense
  edge is tcsh, so `$(...)` in a quoted remote command dies with "Illegal variable
  name" -- QUIETLY. It already cost a silently no-op'd pre-install snapshot. Always
  feed remote commands to `sh -s`.

Also carried (this one matters and was nowhere in the open lists): DHCP HAS NEVER
SERVED A REAL LEASE. kea-dhcp4 is bound to udp/67 with the subnet+pool intact, but
office1-local has no client host, so the DAEMON is proven and the SERVICE is not.
The first VM on office1-local (the Stage 2 headend VMs) is the real test -- logged
as that stage's gate rather than an assumption.

Plus a measured doc-accuracy finding: SEC-007 says "D-112(c) makes SSH the only
management path", but the edge's web GUI IS listening on the LAN (10.10.0.1:443,
HTTPS 200) and is correctly firewalled off on the WAN. Not an exposure -- OPNsense
default, and D-113 kept OPNsense *because* the GUI is an operator requirement -- but
the wording is imprecise. Logged, not actioned (hard rule 1).

Guards: repo-lint 0 fail (1 documented legacy warn), 0 non-ASCII. No live system
touched; the edge probes were read-only TCP/HTTP reachability checks.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Collapse the three ledger streams into one; reconcile against repo ground truth ...

The ledger carried three separately-owned parallel stream sections (main-chat,
jumphost, shared) plus ~30 append-only session narratives -- 2189 lines, several
of them contradicting each other and the repo. Collapsed to ONE stream, 222 lines,
carrying only what is still OPEN plus the facts that live nowhere else.

The narrative is NOT lost: it is in this commit's parent (f81177a) and, durably,
in the 65 docs/changelog-*.md files, design-decisions.md, and the incident reports.

RECONCILED (repo ground truth wins over any stream's self-claim; all verified):
- machine-derived block was STALE: said D=111/DOCFIX=162/BUNDLEFIX=012 and listed
  only SEC-001/003/004. Re-seeded from today's scan: D=114/DOCFIX=195/BUNDLEFIX=013,
  six open SEC rows (001/003/004/005/006/007).
- main-chat called backlog items 6/7/8 "not started". FALSE -- keystone-policy-drift.sh,
  cloud-snapshot.sh and tests/tenant-acceptance/ all exist. Delivered by the jumphost
  stream; this was the cross-stream reconcile the ledger itself had pending.
- item 3 remainder (fold vault-kv-health into cloud-assert): VERIFIED still open.
- item 5 (tenant-cluster-create.sh): VERIFIED still absent.
- R-3/D-063: ledger claimed CLOSED, handoff doc still says PROPOSED/OPEN. D-063 is
  RESOLVED/CLOSED in design-decisions.md -- so the HANDOFF DOC is the stale one.
  Carried forward as an open item rather than fixed here (hard rule 1).
- D-076: not this repo's to work. D-076..D-099 is a RESERVED source-project band
  (D-110), so its "uncommitted worktree draft" was never here. No work lost.
- "beta cluster left at node_count=2" was STALE -- the 2026-07-08 audit found no beta
  cluster and no foil1 tenant. Retired.

CARRIED FORWARD (would have been operationally lost -- the skill loads this file):
the API-managed-DHCP edge trap; "updated in-place" still BOUNCES the guest; do not
re-implement OPNsense's key crypto, call the interface; config ISO can never be read
on a nano image; guide<->skill coupling (repo-lint L8); controller model is
admin/controller; State facts; Project-completion.

NEW, measured this session: the apparmor rule /var/lib/libvirt/vr1/** GATES EVERY VR1
VM BOOT but exists only as host state -- it is NOT in scripts/prereqs/, so a rebuild
hits the identical foundational failure. Logged as an open item.

Guards: repo-lint 0 fail (1 documented legacy warn), 0 non-ASCII, ledger-scan
reconciles against the re-seeded machine block. No live system touched.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

APPLIED + CORRECTION: "updated in-place" does NOT mean "no restart" -- the apply bounced the edge ...

The config_seed/cdrom removal is APPLIED to the live Office1 edge. Apply complete: 0 added,
1 changed, 1 destroyed. `tofu plan` now reports "No changes" -- repo and state are back in sync,
so Stage 3 cannot trip over the divergence.

CORRECTION, recorded because the prediction was WRONG and the mistake is reusable:

I predicted the apply would NOT interrupt the guest, on the grounds that the plan said
"libvirt_domain.vm will be updated IN-PLACE". THE APPLY RESTARTED THE GUEST. Measured: uptime went
from 8:36 to 6 secs across the apply. The dmacvicar/libvirt provider redefines the domain to apply
a disk-list change and BOUNCES it -- a ~30s outage during which the edge was neither routing nor
serving DHCP.

"updated in-place" means the RESOURCE is not replaced. It says NOTHING about whether the GUEST
keeps running. Do not read it as "no interruption" -- that is exactly what I did.

STAGE 3 CONSEQUENCE (the reason this is worth a commit of its own): any future tofu apply that
touches a libvirt_domain's devices -- on a DC edge, or on a node VM -- must be assumed to BOUNCE
THE GUEST, and scheduled/gated as an outage rather than a no-op config tidy-up.

Recovery was clean and needed no intervention. Post-boot, measured: kea-dhcp4 running and bound
udp4 10.10.0.1:67 with subnet 10.10.0.0/24 + pool .100-.199 intact; WAN 172.30.1.2, LAN 10.10.0.1,
default route 172.30.1.1; egress to 1.1.1.1 at 0.0% packet loss; 8 LAN pass rules in pf; serial
console + getty alive (DOCFIX-192 holds). The cdrom is gone from the persistent domain XML.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B6Fzre1CxCY8tzwFCudu57

D-113(a2) COMPLETE: DELETE the config.xml path (template, renderer, ISO builder) ...

Operator ruling ("I'll defer to your lean"): the OPNsense config.xml template is DELETED, not
reduced.

WHY DELETED RATHER THAN REDUCED: the (a2) plan was to shrink the template to a minimal bootstrap
(sshd + root key + console + a seeded API key). That proved UNNECESSARY -- every one of those is
covered without a config.xml at all:

  sshd + root key            -> the D-112(c) console bootstrap (proven on Office1)
  an API key                 -> scripts/opnsense-bootstrap-apikey.sh (OPNsense's OWN model; no GUI
                                click, no re-implemented crypto)
  DHCP/firewall/interfaces   -> the REST API (proven read AND write)

So the provisioning chain has NO config.xml anywhere:
  boot factory nano -> console bootstrap -> mint API key -> configure over REST

A config.xml renderer that nobody should ever run is not a safety net -- it is a loaded gun
pointed at a live router. The 2026-07-13 safety sweep is the evidence: the repo still contained
runbook steps telling an operator to render a config and push it to the edge, which by then would
have CLOBBERED live API-managed DHCP.

DELETED: opentofu/templates/opnsense-config.xml.tmpl; scripts/opnsense-render-config.sh +
tests/opnsense-render-config/; scripts/opnsense-build-config-iso.sh +
tests/opnsense-build-config-iso/; the opnsense-edge module's config_seed volume + cdrom disk and
its config_iso_path variable; the xorriso/genisoimage prereq (it existed ONLY for the ISO
builder). Gauntlet 54 -> 52 harnesses (the two deleted scripts took their harnesses with them --
expected arithmetic, not a regression). All files remain in git history.
opentofu/templates/README.md is now a TOMBSTONE explaining what happened and what to use instead.

THE LIVE CHANGE IS NOT APPLIED IN THIS COMMIT. Removing the module's ISO wiring touches an
INSTANTIATED resource (libvirt_volume.config_seed is in tfstate). Measured with `tofu plan` first:

  module.office1_opnsense.libvirt_domain.vm will be updated IN-PLACE
  module.office1_opnsense.libvirt_volume.config_seed will be destroyed
  Plan: 0 to add, 1 to change, 1 to destroy.

NO replacement of the running domain -- confirmed explicitly. A replacement would have DESTROYED
the live, routing, DHCP-serving edge, and would have been grounds to stop.

A LINT GUARD DID ITS JOB: repo-lint's L3 (runbooks must not reference missing scripts) went RED on
the tombstone notes, because they named the deleted paths. The rule was RIGHT and it has no
opt-out (only L4 does). Rather than weaken a guard that exists to stop runbooks pointing at dead
scripts, the tombstones were reworded to name the bare filename instead of the scripts/ path. The
guard stays fully intact; the information is preserved.

Verification: repo-lint 0 fail; opentofu-validate PASS (root + 10/10 modules standalone);
gauntlet ALL GREEN (52).

Revert: git revert this commit (restores template/renderer/ISO builder/harnesses), then
`cd opentofu && tofu apply` to re-create the (inert) config_seed volume + cdrom.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B6Fzre1CxCY8tzwFCudu57