Rule
A built image must carry the identity of its bytes. Before any portal swap: stamp == built HEAD == target, asserted pre-swap, DEPLOYED_SHA populated, fail loud on divergence. Never trust a version label over the bytes.
The live install advances only via the self-upgrade pipeline. No surface hand-advances the root clone HEAD or the running portal:
- No
git checkout origin/main/pull/reseton the root clone to “update.” - No manual portal rebuild (
docker compose build/up,redeploy-portal) to “update.” - The governed
/ops/self-upgraderunner/promoter owns quiescence, recovery-point creation, image rebuild/swap, health evidence, and rollback.
Why
On 2026-06-05 the live install ran an image stamped e7ef3331 (June 5) but containing ~June-3 bytes — no device-catalog.ts, migrations stopping at 20260603030000, /api/v1/device-catalog returning 404. Three divergent source states existed, none equal to origin/main. The label lied about the bytes. The root cause was two competing source-advance engines (a host-clone dpf/install promoter vs. a /workspace my-changes image-sync) that hand-advanced source outside the governed pipeline. When the identity of an image is its label rather than its bytes, every downstream consumer — operator, gate, rollback — builds on a false premise. The fix is to make the bytes load-bearing: assert the three-way equality before swap and refuse to deploy on divergence (BI-5B6C1C35), and let only the self-upgrade pipeline move the live install.
How To Apply
- At build/promote time, stamp the image with the built HEAD and assert it equals the intended target; populate
DEPLOYED_SHA. - Before swap, re-assert stamp == bytes == target; on any mismatch, fail loud — do not deploy a mislabeled image.
- Route every live-install advance through
/ops/self-upgrade(or the governed runner/promoter). Never hand-advance the root clone HEAD or rebuild the portal as an “update.” - When diagnosing a “stale portal,” check the bytes (files present, migration tip, route behavior), not the version label.
Decision Dimensions
governance_compliance: 0.8— only the governed pipeline advances the live install.blast_radius: -0.7— a mislabeled image deployed to the live install corrupts every downstream assumption.evidence_density: 0.7— the deployed SHA and pre-swap assertion are the evidence that the bytes are the target.long_term_maintainability: 0.5— one source-advance engine instead of competing ones.
Related
runtime-gates-via-shared-lease— verify before swap; never rebuild the live portal to verify.build-gate-mandatory— the live-portal refresh rule and self-upgrade path.fix-the-seed-not-the-runtime— patch the source, not the running bytes by hand.never-fabricate— the bytes are ground truth, not the label.- AGENTS.md §17 — operational summary.
- Unified Delivery Surfaces spec §4.3 — design context.
Origin
Unified Delivery Surfaces spec, 2026-06-05. Tracked as BI-5B6C1C35; relates to the governed platform-upgrade lifecycle design.