# 2026-07-15 -- DOCFIX-195: office1-netbox holds the VR1 IPAM APEX role (working draft); apex write-back deferred; C2 redefined

## Why

Operator ruling (2026-07-15): **`office1-netbox` (10.10.1.10) HOLDS THE IPAM APEX ROLE during VR1** --
it is the authoritative NetBox every consuming system (OpenTofu, MAAS, overlays, the Juju bundle)
derives its values from. It is a *working draft* (edited as the buildout proceeds), but it is the apex.
**`netbox.baldurkeep.com` does not get a write at all during VR1**; it is the eventual production apex,
frozen as a READ-ONLY v1 reference draft and not consulted by VR1 systems. Merging `office1-netbox` back
into `netbox.baldurkeep.com` is a deferred maybe at the very end -- NOT a Stage 2 gate.

**Confirmed while scoping:** no live system config points at any NetBox URL (`opentofu/`, `scripts/`,
`lib-*.sh` carry none) -- "consuming systems use office1-netbox as apex" is a value-DERIVATION workflow
(we read NetBox by hand to populate `lib-net.sh`/tfvars/bundle), not a live API wiring, so no config
repoint is needed; this is a documentation change only.

The repo encoded the OPPOSITE model: it called `netbox.baldurkeep.com` the "apex/source of truth" and
`office1-netbox` a throwaway "sandbox", and defined close-out **C2** (the last open Stage 2 gate, and
the branch->`main` merge trigger) as an operator-gated write that feeds the carve UPSTREAM. Under the
ruling that write does not happen in Stage 2, so C2-as-written was wrong.

**Finding surfaced while drafting (new, previously unlogged):** D-120 Step 6 registers `10.10.1.0/24`'s
child ranges (`ipam/ip-ranges`) and the two service IPs (`ipam/ip-addresses`). Those object classes are
NOT covered by the sandbox loop -- `prod-draft-dump.py`'s `ENDPOINTS` and `sandbox-fidelity-check.py`'s
`KEY`/`EXPECTED_NEW` both stop at rirs/roles/regions/sites/aggregates/prefixes. So the hardened fidelity
check cannot verify the D-120 load; that verification needs a tool extension (+ harness) or a recorded
manual read-back. C2 now records this as a tooling gap and an open C2-execution sub-question.

This is a DOCFIX, not a D-NNN: it defers the apex WRITE and does not revoke D-010 (netbox.baldurkeep.com
remains the eventual source of truth). Doc-only; no script or live-cloud change.

## What changed (all documentation)

1. **`docs/dc-dc-deployment-workflow.md`** -- Stage 2 State-paragraph NetBox bullet + the **C2** row.
   C2 redefined: office1-netbox holds the COMPLETE validated dataset (carve + roles + both DCs + the
   D-120 child ranges + service IPs), verified by (i) a hardened-fidelity-check re-run on the shared
   objects and (ii) a load+verify of the D-120 objects; the tooling gap is logged; apex write-back
   deferred. C2 stays **OPEN**.
2. **`docs/dc-dc-netbox-buildout-scope.md`** -- section 8.1 (inverted the upstream/office1 roles: office1
   is the record, the apex is a read-only v1 draft, merge-back deferred) and section 8.6 (retitled and
   rewritten from "Feeding the delta upstream" to "office1-netbox holds the validated dataset; apex
   write-back DEFERRED", with the D-120 tooling gap and the deferred-merge-back procedure).
3. **`docs/session-ledger.md`** -- five spots corrected (D-120 Step 6 item; OPEN-WORK item 2; the
   NetBox WRITE-PATH BUGS preamble; the fidelity-recheck sequence note; the PINNED merge-point bullet)
   plus a NEW PINNED bullet recording the deferred apex write-back. All edits are in narrative sections;
   the machine-derived block was not touched.
4. **`docs/design-decisions.md`** -- a dated Note under **D-010** recording the VR1-phase apex role
   (office1-netbox is the working-draft apex; apex write-back deferred; defers the write, does not
   revoke D-010), AND a pointer on **D-103**'s "NetBox remains the IPAM apex; MAAS and overlays consume
   NetBox values" bullet naming office1-netbox as that apex during VR1.
5. **`netbox/README.md`** -- a banner so the `NETBOX_URL=https://netbox.baldurkeep.com` examples are not
   mistaken for the VR1 write target (that is office1-netbox; the apex URL is for the deferred merge-back
   only, gated by `--yes-write-upstream`).

## Also logged (NOT actioned here)

- **Tooling gap:** the sandbox dumper + fidelity check do not cover `ip-ranges`/`ip-addresses`; the
  D-120 load cannot be machine-verified until they are extended (each with its harness) or a manual
  read-back is recorded. This is the real remaining C2-execution work.
- **Durability finding:** `office1-netbox` is now load-bearing VR1 IPAM state on a lab VM; its
  backup/durability matters once it is the record (log-only; not part of this DOCFIX).

## Revert

Each item is an isolated text edit; revert individually:

1. `git checkout HEAD -- docs/dc-dc-deployment-workflow.md`
2. `git checkout HEAD -- docs/dc-dc-netbox-buildout-scope.md`
3. `git checkout HEAD -- docs/session-ledger.md`
4. `git checkout HEAD -- docs/design-decisions.md`
5. `git checkout HEAD -- netbox/README.md`
6. `git rm docs/changelog-20260715-docfix195-c2-netbox-of-record.md`

Reverting restores the prior "feed the carve upstream = C2" framing across all five docs. No code paths,
scripts, harnesses, or live NetBox state are affected by this change or its revert.