Changelog 2026-08-02 (part 3) -- the Stage-5 deploy input is corrected before the deploy

Session changelog (GA-R2/D1: ONE per session). Branch dc-dc-stage5-preconditions. Session open reconciled at HEAD c620f99: repo-lint 0 fail / 1 legacy warn, ledger-scan 3 open decisions / 28 open SEC / next-free D-141, DOCFIX-208, BUNDLEFIX-053. Status claims live in docs/CURRENT-STATE.md ONLY.

Scope: the item both the 2026-08-02 (part 2) close and docs/CURRENT-STATE.md name as the next session's FIRST item -- the preflight-P2 / phase-4 machines-overlay asymmetry -- worked to completion ahead of the bundle deploy.

Item 1 -- DOCFIX-208: the phase-4 dc0 deploy command was missing a load-bearing overlay

WHAT WAS WRONG. runbooks/dc-dc-phase4-juju-bundle-per-dc.md told the operator to deploy vr1-dc0 as bundle.yaml + vr1-dc0-vips.yaml + vr1-dc0-octavia-pki.yaml, omitting overlays/vr1-dc0-machines.yaml. Its stated reason -- "there is no overlays/vr1-dc0-machines.yaml" (:527-528) -- had been FALSE since 2026-07-29, when that file was created (changelog-20260729 item 3.8). scripts/preflight.sh:144-145 folds the file into the merged input that gate P2 validates, so P2 was grading an input the deploy would not have passed.

WHY IT WAS NOT HYGIENE. The classification carried into this session was "DOCFIX-shaped ... likely bundles with the outstanding D-138 run-location DOCFIX" (changelog-20260802-queued-items item 5, finding 2). That is too low: the disputed artifact is the argument list of the very next live mutation. Executed as written, a dc0 deploy would have taken TWO independent injuries, neither of which surfaces as a deploy error:

No provider bridge mapping. bundle.yaml:494 states bridge-interface-mappings "IS NOT IN THIS FILE, and must never be re-added here" -- the overlay is its ONLY source. ovn-chassis would deploy with no br-ex mapping and tenant networks would come up with no external path. This is exactly the defect the 2026-07-29 move out of the base bundle was made to fix, reintroduced by stale prose.
15 unreachable package sources. Per the 2026-07-31 GA-R5 ruling ("Point origin/source at the mirrored UCA, per-DC overlay") the same overlay repoints 12 openstack-origin + 3 ceph source at the in-DC mirror. Without it those charms fetch ubuntu-cloud.archive.canonical.com, MEASURED UNREACHABLE from a node (000) under the D-107 airgap -- a failure at package-install time.

MEASURED, NOT REASONED. Deep-merging bundle.yaml against the overlay:

overlay top-level keys: ['applications']        <- NO machines: block at all
apps in overlay: 16
  ovn-chassis.bridge-interface-mappings: ADDS
  barbican / magnum / octavia / ceph-mon / ceph-osd / ceph-radosgw : OVERRIDES  (6)
  cinder, designate, glance, keystone, neutron-api, nova-cloud-controller,
  nova-compute, openstack-dashboard, placement                    : ADDS      (9)
base ovn-chassis options: {'ovn-bridge-mappings': 'physnet1:br-ex',
                           'prefer-chassis-as-gw': True}

THIS CORRECTS THIS REPO'S OWN EARLIER FINDING (GA-R1 C2). docs/CURRENT-STATE.md recorded 2026-07-31 that "the only delta it makes to the merged input is ovn-chassis.options.bridge-interface-mappings". That was TRUE WHEN TAKEN and was overtaken HOURS LATER IN THE SAME SESSION by the UCA build. Sixteen applications, not one. The correcting capture is folded into the same CURRENT-STATE entry rather than replacing it.

THE FILE NAME IS WHAT MISLED THE RUNBOOK. dc0 genuinely needs no machines RETAG -- bundle.yaml's machines block already reads tags=openstack-vr1-dc0,<role> -- and the old table row said so correctly. The error was concluding from that true fact that the FILE is unnecessary. The overlay is the per-DC HAND-MAINTAINED overlay and its applications: half is load-bearing; its own header says so and says not to add a machines: block for symmetry.

WHAT CHANGED (runbooks/dc-dc-phase4-juju-bundle-per-dc.md, 6 sites):

4.1 table -- the "machines retag" row becomes overlays/${DC}-machines.yaml, REQUIRED for BOTH DCs, with the measured 16-app delta and the reason the old reading was wrong.
4.1 prose -- the "Do not interpolate a machines overlay path for vr1-dc0" paragraph replaced. The never-silently-skip-an-overlay rule is KEPT (it is right, and it is why a dc1 deploy cannot merge dc0 tags); only its dc0 exemption goes.
4.2 dry-run block (dc0) -- machines overlay added, order vips -> machines -> pki.
4.3 deploy block (dc0) -- same, so 4.2 and 4.3 remain identical but for --dry-run.
Step 7 dry-run block (dc0) -- same. This block CONTRADICTED ITS OWN paragraph four lines above ("dropping the VIP or machines overlay here would present juju with an input that contradicts the running model"), and the "Same overlay-set rules" sentence beneath it repeated the dc0 exemption; both fixed.
4.2 preamble -- the VERIFY-LIVE pointer was dc1-only; now names both halves (dc1's machines-block retag, BOTH DCs' applications.options merge).

NOT CHANGED, because it was already right: scripts/preflight.sh P2 and runbooks/phase-01-bundle-deploy.md:199-201 both assemble the three-overlay set behind a [ -f ] guard. This was one wrong surface, not two disagreeing.

Revert: git revert this commit. The runbook returns to a dc0 command that omits a required overlay -- do not revert without also re-opening the finding in docs/CURRENT-STATE.md.

Item 2 -- the 4.2 gate could not have caught it, so it gained two assertions

The standing rule that a checker which cannot fail is not a gate applies to the gate as much as the command. Step 4.2's four gate items read the machines block, the machine count, the VIP prefixes, and overlay-path errors. The machines overlay's entire payload is under applications:, so all four would have passed a dc0 deploy with no provider bridge mapping and 15 unreachable package sources. Two added:

Item 5 -- ovn-chassis shows THREE options, not one. bridge-interface-mappings must appear ALONGSIDE ovn-bridge-mappings: physnet1:br-ex and prefer-chassis-as-gw: true. This is the VERIFY-LIVE assertion both overlays' headers demand and that NO offline check can make: provider-bundle-check.py's _deep_merge merges key-by-key BY CONSTRUCTION, so validating through it cannot distinguish a key-by-key merge from a map REPLACE. Only the live dry-run can. If only the new key appears, the physnet mapping and the B2 gateway-chassis election are both gone from the deploy input and provider egress dies by a different route than the defect item 1 fixes. Also: exactly TWO MACs, a third means a wrong node.
Item 6 -- every openstack-origin / ceph source resolves to an address this DC's nodes can reach. Names dc1's deliberate absence of the block as D-135's experiment RESULT, so a later reader does not "fix" the asymmetry.

>>> ITEMS 5 AND 6 AS FIRST WRITTEN WERE THEMSELVES CHECKERS THAT COULD NOT FAIL, AND WERE REMOVED WITHIN THE HOUR. SEE ITEM 3. <<< Left recorded here rather than edited out: the mistake is the point.

Revert: n/a -- superseded by item 3 in this same session.

Item 3 -- the dry-run graded the gate, and three of its items failed

THE RUN. docs/audit/stage5-dryrun-dc0-20260802.txt (400 lines). From the dc0 rack (D-138), model vr1-dc0, juju 3.6.27, model EMPTY at run time. Deploy input sha256-verified against HEAD immediately before the run, not inherited from the prior close: all five tracked files match, PKI overlay unchanged at 5fc117f1 mode 0600 (hashed, never read). EXIT 0.

PASSED: nine machines 0-8; all 9 constraint lines arch=amd64 tags=openstack-vr1-dc0,<role> in the 3/2/4 split, none naming the other DC; all three overlays consumed without a path error. Also settled the ceph-osd tags=openstack item CURRENT-STATE deferred to this gate: the plan places ceph-osd/0..3 on machines 5-8 by explicit placement and the bare tag never appears -- the exposure remains a later UNPLACED add-unit, which this deploy does not perform.

THE INSTRUMENT FINDING. Measured at both verbosities: juju deploy --dry-run on a bundle prints ONLY located charms, upload/deploy lines, BARE machine ids, placement and relations. No application options, no VIPs, at any verbosity. Greps over the --debug capture: bridge-interface-mappings 0, physnet1 0, openstack-origin 0, cloud-archive 0, prefer-chassis 0. The only 10.12.4. hits are the controller's own API addresses; the only vip hit is the echoed command line. --debug adds exactly one thing -- the per-machine constraint lines (bundlehandler.go:1035).

Three consequences, all fixed here:

Gate item 1 (tags) was ungradable by the command as written. The named command is now --dry-run --debug, with the measurement quoted as the reason so nobody drops the flag as noise.
The PRE-EXISTING VIP item could never have failed -- "every VIP in the plan is on THIS DC's prefixes", when no VIP is ever in the plan. REMOVED, and the property relocated IN WRITING to preflight P2, which already asserts the VIP bands over the same merged input. Per the standing rule, the assertion was replaced with the true invariant and the move is stated, not silently dropped.
My own items 5 and 6, written earlier this session, had the same defect. REMOVED. The properties are real, so they became new Step 4.4 -- a juju config read run the moment juju deploy returns, before the model settles. That is the only thing that can prove the merge: _deep_merge in provider-bundle-check.py merges key-by-key BY CONSTRUCTION, so it cannot distinguish a key-by-key merge from a map REPLACE, and the dry-run sees no options at all.

OWNED. I added two assertions that could not fail to the very gate whose purpose was to catch a defect that had survived precisely because nothing could see it. They were caught by the live run, not by re-reading my own work -- instance fourteen of this repo's instrument-currency pattern and the second consecutive session where measurement, not review, was the catching agent.

ALSO CORRECTED: both machines overlays' VERIFY-LIVE headers, which instructed the reader to assert the options merge "at the live dry-run". Measured impossible. Corrected in place (not deleted) and pointed at Step 4.4. dc1's header additionally notes the split that dc0's does not have: dc1's machines BLOCK is visible in the --debug plan and is gradable at 4.2; only its options half is not.

Revert: git revert. Restores a gate with three ungradable items and two overlay headers naming an impossible check.

Item 4 -- LOGGED, NOT FIXED (hard rule 1)

runbooks/phase-00-teardown-maas-reset.md:233 runs provider-bundle-check.py with the vips overlay ONLY, so it grades a narrower input than either preflight P2 or the deploy command. Not deploy-blocking (teardown-time check), DOCFIX material for the same fold.
The runbook says bundle.yaml ships "NO designate" for this stage; the plan deploys four designate applications and places designate/0 on 0/lxd/5. One of the two is wrong and it is not resolvable from the runbook. NOT deploy-blocking -- designate deploying early costs containers, not correctness. The bullet is annotated in place so no session reads it as a fact about the current bundle; the underlying question (does D-106 leave designate in the Stage-5 bundle?) is unanswered and left for the operator.

Both recorded in docs/CURRENT-STATE.md, neither actioned.

Item 5 -- the instrument finding GRADUATES out of the changelog

references/platform-traps.md gains a Juju section: what a bundle --dry-run prints, what it does not print at any verbosity, the two grep decoys (the controller's own API addresses look like VIPs from the DC's band; --debug echoes the command line so overlay FILENAMES hit), and the three consequences -- a dry-run cannot verify an options merge, --debug is load-bearing for any tags/constraints assertion, and juju config on the deployed model is the only instrument that settles the merge question. It generalizes past this repo's phase-4 gate to any bundle deploy in the chain, so a changelog was the wrong home for it (standing rule: durable observations graduate to their repo surface).

Revert: drop the section. Not recommended -- it is the reusable half.

Item 6 -- Step 4.4's own read hardened, and its unproven status stated

Two corrections to the block written in item 3, both before it ever runs:

The --format=json read indexed ["settings"][key]["value"] directly. A missing key raises KeyError, and a traceback printed into a results column reads like output -- this repo has a logged instance of an assertion being satisfied by a traceback. Now .get(...) with a visible <<UNSET-OR-APP-ABSENT>> sentinel, documented as a FAILURE rather than a blank.
Step 4.4 is AUTHORED, NOT EXERCISED. It is written against a measured instrument but has never run -- the model was empty when it was written, so its first execution is at deploy time. Stated in the runbook itself, with the instruction to report a shape correction rather than work around one, and a note that designate appears in its loop while an unresolved contradiction says the bundle should not carry designate at this stage.
Revert: restore the direct index. Do not.

Gates at delivery: bash scripts/repo-lint.sh -- 0 fail, 1 warn (the legacy D-001..018 ASCII carve-out). provider-bundle-check.py over the dc0 merged input PASS. Both machines overlays re-parsed after editing (dc0: applications only, 16 apps; dc1: applications + machines). No script changed, so no harness is implicated; the gauntlet's last full run stands at ALL GREEN (98) from the 2026-08-02 (part 2) close.

THE DEPLOY IS NOT RUN. Step 4.3 is a gated mutation and awaits operator approval. This session stops at the dry-run.