Engineering practice: Preventing version mismatch in static releases

This case study covers only the website’s static release chain. It does not represent customer count, product outcomes, or commercial results.

Symptom: Styles disappear after routing and the page looks blank

A browser may reuse old HTML after the release script has removed hashed CSS and JavaScript from an older version. That HTML then references missing assets, appearing as broken styling, a missing Cookie panel, or abnormal content.

The first failure boundary is not SSR

Astro already builds the home page as complete static HTML. The problem occurs at the “old HTML → removed hashed asset” release boundary, not because the server failed to prerender home.

Fix: Revalidate HTML and keep hashed assets available

HTML
  Cache-Control: no-cache, max-age=0, must-revalidate

/_astro/*
  Cache-Control: public, max-age=31536000, immutable

Each release atomically switches the current version while accumulating content-hashed assets in a shared cross-version directory. If two files with the same hash name contain different content, the release fails immediately to preserve immutable semantics.

Gate: Restore the previous version on failure

• Verify that the release manifest matches the target version.
• Sample a real hashed asset and confirm its one-year immutable cache header.
• Confirm that home-page HTML uses a revalidation cache policy.
• If any check fails, atomically restore the pre-release current symlink.

Complete operational constraints live in deployment documentation and release scripts in the source repository; the public page states only verified mechanisms.