fix(#1468): fingerprint framework runtime bundle + no-cache serving safety net

The page-runtime bundle (/static/dist/dazzle.min.{js,css}) was emitted
non-fingerprinted with a multi-hour max-age, so returning users ran the cached
OLD bundle for ~4h after a deploy — the #1465 dzTable crash fix "didn't take"
until the cache expired.

Fix (two layers):
1. build_app_chrome content-hashes the bundle URLs (dazzle.min.<hash>.js) in
   production/staging — immutable + instant propagation — for the dominant
   app/workspace/page path and every site reading app.state.fragment_chrome_*.
   Gated by asset_fingerprint.should_fingerprint() (mirrors should_bundle_assets:
   on in prod/staging, off in dev/test and under [ui] active_development), so
   dev/test keep plain URLs (stable assertions; the existing 18 literal-URL
   tests are unaffected).
2. CombinedStaticFiles serves any /static/dist/* requested at its plain
   (non-fingerprinted) URL no-cache — a safety net so emission sites that
   hardcode the path (auth/profile/signing pages) still propagate fixes
   immediately instead of staling. Fingerprinted requests stay immutable.

Adds [ui] active_development (no-cache iteration opt-out) and [ui]
static_max_age (cache duration for non-fingerprinted non-bundle assets) —
the "mature site vs active development" distinction.

Adversarial review caught that fingerprinting alone missed the hardcoded
emission sites; the serving-layer safety net covers them in one place.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: claude

.claude/CLAUDE.md

@@ -374,4 +374,4 @@ Example: `examples/ops_dashboard` has working `bar_chart` (FK `group_by: system`
 - **KG re-seeding**: `ensure_seeded()` checks a version key; bump it in `seed.py` when TOML data changes.
 
 ---
-**Version**: 0.86.15 | **Python**: 3.12+ | **Status**: Production Ready
+**Version**: 0.86.16 | **Python**: 3.12+ | **Status**: Production Ready

CHANGELOG.md

@@ -9,6 +9,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.86.16] - 2026-06-24
+
+### Fixed
+- **#1468 framework runtime bundle no longer serves stale to returning users after a deploy.** `/static/dist/dazzle.min.{js,css}` (+ `dazzle-icons.min.js`) was emitted non-fingerprinted with a multi-hour `max-age`, so after a deploy returning visitors kept running the cached old bundle for up to ~4h — a JS *crash* fix (e.g. #1465) "didn't take" until the cache expired. Two-layer fix: **(1)** `build_app_chrome` now content-hashes the framework bundle URLs (`dazzle.min.<hash>.js`) in production/staging — immutable long cache + instant propagation — for the dominant app/workspace/page path (and every site that reads `app.state.fragment_chrome_*`); **(2)** a serving-layer safety net in `CombinedStaticFiles` serves any `/static/dist/*` requested at its plain URL `no-cache`, so emission sites that hardcode the path (auth/profile/signing pages) still propagate fixes immediately rather than staling for hours.
+
+### Added
+- **`[ui] active_development` and `[ui] static_max_age` (dazzle.toml).** `active_development = true` opts a deployed site out of fingerprinting/immutable caching in favour of `no-cache` revalidation (fast iteration on a staging/dev deploy). `static_max_age = <seconds>` configures the cache duration for non-fingerprinted, non-bundle static assets (default 1h; fingerprinted assets are always immutable). Realises the "mature site vs site under active development" distinction.
+
+### Agent Guidance
+- **Fingerprinting is env-gated.** `dazzle.page.runtime.asset_fingerprint.should_fingerprint()` is on only in `DAZZLE_ENV=production`/`staging` and off under `[ui] active_development` — so dev/test see plain `/static/dist/...` URLs (stable assertions). New framework HTML that emits a `/static/dist/*` URL should route it through `fingerprint_static_url()` for the immutable optimization; if it can't, the `no-cache` serving safety net still guarantees correctness.
+
 ## [0.86.15] - 2026-06-24
 
 ### Fixed

ROADMAP.md

@@ -1,7 +1,7 @@
 # DAZZLE Development Roadmap
 
 **Last Updated**: 2026-06-16
-**Current Version**: v0.86.15
+**Current Version**: v0.86.16
 
 For past releases, see [CHANGELOG.md](CHANGELOG.md).
 

homebrew/dazzle.rb

@@ -10,10 +10,10 @@ class Dazzle < Formula
 
   desc "DSL-first application framework with LLM-assisted development"
   homepage "https://github.com/manwithacat/dazzle"
-  version "0.86.15"
+  version "0.86.16"
   license "MIT"
 
-  url "https://github.com/manwithacat/dazzle/archive/refs/tags/v0.86.15.tar.gz"
+  url "https://github.com/manwithacat/dazzle/archive/refs/tags/v0.86.16.tar.gz"
   sha256 "PLACEHOLDER_SOURCE_SHA256"
 
   # pydantic-core requires Rust to build from source, so use pre-built wheels

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dazzle-dsl"
-version = "0.86.15"
+version = "0.86.16"
 description = "DAZZLE — declarative SaaS framework with built-in compliance (SOC 2, ISO 27001), provable RBAC, and graph features"
 readme = "README.md"
 requires-python = ">=3.12"

src/dazzle/core/manifest.py

@@ -661,6 +661,18 @@ class ProjectManifest:
     signing: SigningConfig = field(default_factory=SigningConfig)  # #1283 phase 8
     framework_version: str | None = None
     cdn: bool = False  # Local-first; opt-in via [ui] cdn = true in dazzle.toml
+    # #1468: a site under active development can opt out of content-hash
+    # fingerprinting + immutable caching of the framework runtime bundle.
+    # When true, asset URLs stay plain (`/static/dist/dazzle.min.js`) and
+    # `/static/dist/*` is served `Cache-Control: no-cache` so every rebuilt
+    # bundle is picked up on the next load. Default false = mature-site
+    # behaviour: fingerprinted URLs + immutable long cache in production.
+    # Set via `[ui] active_development = true` in dazzle.toml.
+    active_development: bool = False
+    # Cache duration (seconds) for NON-fingerprinted static assets in
+    # production. Fingerprinted assets are always immutable/1yr regardless.
+    # None = framework default (1h). Set via `[ui] static_max_age = 300`.
+    static_max_age: int | None = None
     # Asset bundling mode. Resolved at request time by `should_bundle_assets()`:
     #   "auto"   = bundle when DAZZLE_ENV=production, individual scripts in dev (default)
     #   "always" = bundle in every environment (perf testing / staging)
@@ -1034,6 +1046,14 @@ def load_manifest(path: Path) -> ProjectManifest:
     assets_mode = ui_data.get("assets", "auto")
     if assets_mode not in ("auto", "always", "never"):
         raise ValueError(f"[ui] assets must be 'auto', 'always', or 'never'; got {assets_mode!r}")
+    active_development_enabled = bool(ui_data.get("active_development", False))
+    static_max_age_value = ui_data.get("static_max_age")
+    if static_max_age_value is not None and (
+        not isinstance(static_max_age_value, int) or static_max_age_value < 0
+    ):
+        raise ValueError(
+            f"[ui] static_max_age must be a non-negative integer; got {static_max_age_value!r}"
+        )
 
     # Parse [extensions] section (#786)
     extensions_data = data.get("extensions", {})
@@ -1127,6 +1147,8 @@ def load_manifest(path: Path) -> ProjectManifest:
         signing=signing_config,
         framework_version=project.get("framework_version"),
         cdn=cdn_enabled,
+        active_development=active_development_enabled,
+        static_max_age=static_max_age_value,
         assets=assets_mode,
         favicon=favicon_path,
         app_theme=app_theme_name,

src/dazzle/http/runtime/static_files.py

@@ -45,8 +45,19 @@ class CombinedStaticFiles(StaticFiles):
     the original file and served with ``Cache-Control: immutable``.
     """
 
-    def __init__(self, directories: list[Path], **kwargs: Any) -> None:
+    def __init__(
+        self,
+        directories: list[Path],
+        *,
+        default_max_age: int | None = None,
+        active_development: bool = False,
+        **kwargs: Any,
+    ) -> None:
         self._extra_dirs = [d for d in directories[:-1] if d.is_dir()]
+        # #1468: cache policy for NON-fingerprinted assets. Fingerprinted
+        # (content-hashed) assets are always immutable regardless of these.
+        self._default_max_age = _DEFAULT_MAX_AGE if default_max_age is None else default_max_age
+        self._active_development = active_development
         primary = directories[-1] if directories else Path(".")
         super().__init__(directory=str(primary), **kwargs)
 
@@ -96,10 +107,28 @@ def file_response(
             is_fingerprinted = bool(FINGERPRINT_RE.search(os.path.basename(request_path)))
 
             ext = os.path.splitext(str(full_path))[1].lower()
-            if is_fingerprinted or ext in _IMMUTABLE_EXTENSIONS:
+            if self._active_development:
+                # #1468: a site under active development serves everything
+                # no-cache so each rebuild is picked up on the next load. The
+                # content hash (when present) still guarantees byte-correctness;
+                # no-cache just forces ETag revalidation → 304 when unchanged.
+                # Checked first so even a stale fingerprinted URL from a prior
+                # deploy revalidates instead of staying immutable.
+                response.headers["Cache-Control"] = "no-cache"
+            elif is_fingerprinted or ext in _IMMUTABLE_EXTENSIONS:
                 response.headers["Cache-Control"] = (
                     f"public, max-age={_IMMUTABLE_MAX_AGE}, immutable"
                 )
+            elif "/dist/" in request_path:
+                # #1468 safety net: the framework runtime bundle requested at its
+                # plain (non-fingerprinted) URL — i.e. from an HTML emission site
+                # that hardcodes `/static/dist/...` instead of reading the
+                # fingerprinted app-chrome URLs — must revalidate every load so a
+                # deploy's JS/CSS fix is never served stale for hours. The
+                # fingerprinted emissions (the dominant app-page path) take the
+                # immutable branch above; this guarantees correctness for any
+                # emission site that isn't (yet) wired to fingerprint.
+                response.headers["Cache-Control"] = "no-cache"
             else:
-                response.headers["Cache-Control"] = f"public, max-age={_DEFAULT_MAX_AGE}"
+                response.headers["Cache-Control"] = f"public, max-age={self._default_max_age}"
         return response

src/dazzle/http/runtime/subsystems/system_routes.py

@@ -28,6 +28,8 @@ def _mount_static_files(
     *,
     project_root: Any = None,
     extra_static_dirs: Any = None,
+    active_development: bool = False,
+    static_max_age: int | None = None,
 ) -> None:
     """Mount the framework + project static file routes on ``app``.
 
@@ -78,7 +80,15 @@ def _mount_static_files(
                 name="project_themes",
             )
 
-    app.mount("/static", CombinedStaticFiles(directories=dirs), name="static")
+    app.mount(
+        "/static",
+        CombinedStaticFiles(
+            directories=dirs,
+            default_max_age=static_max_age,
+            active_development=active_development,
+        ),
+        name="static",
+    )
 
 
 class SystemRoutesSubsystem:
@@ -690,6 +700,11 @@ async def diagnostics(
         # sites read `app.state.fragment_chrome` and thread the
         # css_links / js_scripts / theme / font_preconnect kwargs into
         # `dispatch_render_page`.
+        # #1468: static-cache policy from [ui], resolved here and applied at the
+        # mount below. Defaults are mature-site behaviour (immutable fingerprints
+        # + framework default max-age for non-fingerprinted assets).
+        static_active_development = False
+        static_max_age: int | None = None
         try:
             from pathlib import Path
 
@@ -700,6 +715,9 @@ async def diagnostics(
                 manifest_path = Path(ctx.project_root) / "dazzle.toml"
                 if manifest_path.exists():
                     mf = load_manifest(manifest_path)
+            if mf is not None:
+                static_active_development = bool(getattr(mf, "active_development", False))
+                static_max_age = getattr(mf, "static_max_age", None)
 
             chrome = resolve_app_chrome(
                 appspec,
@@ -726,6 +744,8 @@ async def diagnostics(
                 ctx.app,
                 project_root=ctx.project_root,
                 extra_static_dirs=ctx.extra_static_dirs,
+                active_development=static_active_development,
+                static_max_age=static_max_age,
             )
         except ImportError:
             pass  # dazzle_page not installed — static files served externally

src/dazzle/mcp/semantics_kb/core.toml

@@ -3,7 +3,7 @@
 
 [meta]
 category = "Core Constructs"
-version = "0.86.15"
+version = "0.86.16"
 
 [concepts.entity]
 category = "Core Construct"

src/dazzle/page/runtime/app_chrome.py

@@ -23,6 +23,7 @@
 from typing import Any
 
 from dazzle.core import ir
+from dazzle.page.runtime.asset_fingerprint import fingerprint_static_url
 
 logger = logging.getLogger(__name__)
 
@@ -153,11 +154,13 @@ def resolve_app_chrome(
     # Manifest-level config (favicon, cdn toggle).
     favicon = _DEFAULT_FAVICON
     use_cdn = False
+    active_development = False
     manifest_theme: str | None = None
     if manifest is not None:
         if getattr(manifest, "favicon", None):
             favicon = str(manifest.favicon)
         use_cdn = bool(getattr(manifest, "cdn", False))
+        active_development = bool(getattr(manifest, "active_development", False))
         manifest_theme = getattr(manifest, "app_theme", None) or None
 
     # Theme name: env > DSL > manifest > None.
@@ -232,6 +235,17 @@ def resolve_app_chrome(
     if appspec is not None and getattr(appspec, "guides", None):
         js_scripts.append("/static/js/dz-onboarding.js")
 
+    # #1468: content-hash the framework bundle URLs (prod/staging only) so a
+    # deploy's JS/CSS fixes reach returning visitors immediately instead of
+    # after the cached bundle's max-age. No-op in dev/test/active-development.
+    css_links = [
+        fingerprint_static_url(u, active_development=active_development) for u in css_links
+    ]
+    js_scripts = [
+        fingerprint_static_url(u, active_development=active_development) for u in js_scripts
+    ]
+    favicon = fingerprint_static_url(favicon, active_development=active_development)
+
     return AppChrome(
         css_links=tuple(css_links),
         js_scripts=tuple(js_scripts),