C4 DONE: document the NetBox sandbox loop; add the upstream-write guard it exposed ...

C4 (Stage 2 close-out) -- the sandbox loop is now documented in two places, no
rationale duplicated: docs/dc-dc-netbox-buildout-scope.md section 8 (design: why a
sandbox, the fidelity check + its 2026-07-14 hardening, the write-guard table, the
WAF trap, C2 preconditions) and runbooks/dc-dc-phase1-office1-standup.md Step 10b
(the dump->seed->apply->verify->gated-write sequence, two-host/two-token separation).
Drafted by a subagent, corrected against this session's own fixes before placement.

The guard C4 exposed: roles-aggregates-import.py and dc-dc-prefixes-import.py had NO
hostname gate -- until today the WAF 403 was the only thing stopping an accidental
--commit to the apex, and the UA fix removed that accidental safety. Both now gate a
non-sandbox --commit behind --yes-write-upstream (SANDBOX_HOSTS allowlist), matching
d115-office-carve.py -- so all three write-capable importers behave identically. This
is defence-in-depth with the whole-plan preflights (which prevent a half-write).

Tests: prefixes-import 86->91 (refused without the flag + writes nothing; allowed
with it; sandbox host needs no flag). roles-aggregates 20->24. GAUNTLET ALL GREEN (58).

Stage 2: C1/C3/C4 DONE. C2 (production write) is the only item left -- gated, with
preconditions now documented (re-verify sandbox under the hardened check, run from
office1-netbox, --yes-write-upstream, approve each mutation).

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

Fix the WAF User-Agent gap: the two pynetbox importers could never write upstream ...

A C2 blocker, measured 2026-07-14: upstream netbox.baldurkeep.com 403s the default
Python User-Agent (references/platform-traps.md) -- curl->200, urllib/pynetbox->403.
The stdlib tools (prod-draft-dump/sandbox-seed/d115-office-carve) already send an
accepted UA, but roles-aggregates-import.py and dc-dc-prefixes-import.py built
pynetbox.api() with the DEFAULT UA and never overrode it. So they would 403 against
upstream -- they could only ever have written to the WAF-less sandbox, never to the
apex C2 must feed. The gap was invisible because every real run so far hit the sandbox.

Fix: get_nb() sets nb.http_session.headers["User-Agent"] = "curl/8.5.0" in both
(same value/rationale as the stdlib tools; pynetbox exposes its requests.Session).

Tests: prefixes-import 85->86 (the fake now has .http_session; the UA is asserted at
RUNTIME, not by source grep). roles-aggregates 19->20. GAUNTLET ALL GREEN (58).

Still open for C2 (logged in the changelog): pynetbox is NOT on vcloud, so the two
importers must run on office1-netbox (has pynetbox 7.0.0); the sandbox re-verify
needs the operator-held token; the upstream write stays operator-gated.

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

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-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