Artifact Manifest, Rollout, and Rollback Coherence

Working case

Release 47 of the case dashboard works in two regions. Release 48 adds a new report panel and moves a worker file. During a staged rollout, some users keep release-47 HTML open while a regional cache serves release-48 assets. The deployment process preserves all release-47 hashed files, publishes release-48 files first, then switches the HTML pointer. If error rates rise, operators switch the document pointer back to release 47 without deleting either asset set. A release record names both the asset manifest and the API compatibility window.

Implementation boundary

function mayPromote(manifest, availablePaths) {
  return manifest.assets.every(asset => availablePaths.has(asset.path));
}
console.log(mayPromote({ assets: [{ path: '/assets/case-47.js' }, { path: '/assets/report-47.js' }] }, new Set(['/assets/case-47.js'])));
// Output: false

Produce the manifest from final build output, including paths, byte sizes, digests, and toolchain identity. Upload immutable assets before changing the document or edge pointer. Verify every manifest path from each target region and check that the response bytes match the digest. Keep HTML short-lived or revalidated so new navigation can pick up the current pointer; do not apply the same cache rule to hashed assets. Design API changes to serve both current and still-open client builds during the rollout window. Revoke an old asset only after observing no supported clients request it or after a stated maximum lifetime has passed.

Cost and boundaries

Retaining two or more releases consumes storage, but usually much less than the cost of broken sessions. The manifest check is O(number of emitted assets) requests if done naively; sample or batch checks while ensuring every critical entry is covered. An overly long HTML cache can hold users on an old build, while an overly short hashed-asset cache wastes bandwidth. Track failed chunk loads, mixed-version API errors, rollback time, and oldest active client version. A service worker may add another cache layer and must be included in the rehearsal.

Failure trace

A deployment switches HTML before uploading a lazy-loaded chunk to one region. The first page paints correctly, but opening the report panel fails. Another rollback restores HTML while a worker still points at a removed file. Rehearse both failures across a cold browser and an open tab. Verify the old and new manifests during promotion, after rollback, and after cache propagation. The operator must be able to identify exactly which digest is missing, rather than diagnosing a generic blank page.

Verification

• Every manifest asset exists before the HTML pointer changes.
• An old open tab can lazy-load after the new release.
• Rollback restores compatible HTML and API behavior.

Practice drill

Construct manifest 47 with an entry for the report panel, then publish manifest 48 with one new chunk. Before flipping the pointer, simulate a missing regional object and require the promotion gate to stop. After promotion, keep a release-47 tab open and trigger its lazy load. Roll back to 47 while a release-48 tab remains open, then verify both clients can load their remaining assets and call a compatible API.

Decision note

Promote one immutable artifact set; switch the document pointer only after every required asset is available.

Common Mistakes

• Rebuilding separately in staging and production.
• Treating a successful first paint as proof all lazy chunks exist.
• Deleting old assets as soon as a new HTML pointer is live.

Connected lessons

Build Project: frontend artifact promotion and rollback and review Web Development: embedded interfaces and build integrity quiz; follow Frontend Build and Artifact Integrity; Locked Dependency Resolution and Clean Installs; Dependency Admission, Install Scripts, and Provenance; External Asset Integrity and Module Resolution; Continuous Integration and Release Gates; Regional Routing, Static and Private Cache Boundaries.