fix(site-publish): retain immutable route history

Authored-By: OpenAI (GPT-5) <noreply@openai.com>

README.md

@@ -133,8 +133,10 @@ any route's mutable objects change.
 Mutable default and override partitions receive their final cache policy before
 the matching prefix-scoped stale deletion, so publication never exposes a
 provisional cache policy or a pointer to a missing immutable target.
-Generated Ingress annotations retain each bucket's prior route and immutable paths. When a move
+Generated Ingress annotations retain each bucket's prior route and all immutable
-places that retired prefix inside the new sync scope, only its declared
+key prefixes. The prefixes are bucket-relative and carried forward after a rule
+is removed or renamed, so later deployments and route moves cannot forget them.
+When a move places a retired prefix inside the new sync scope, only its declared
 immutable subtrees are excluded; a current-file collision fails publication.
 The bucket-keyed history rejects a protected-to-public transition even when the
 artifact is renamed; publishing that artifact publicly requires a new bucket.

scripts/deploy.py

@@ -178,29 +178,40 @@ def publish_route_immutables(artifact, route, site_dir, credential_env_names=Non
             publish_immutable_rule(artifact, route, rule, html_dir, aws_env)
 
 
+def immutable_key_prefixes(artifact, route):
+    """Return immutable partitions as bucket-relative key prefixes."""
+    route_prefix = route["path"].strip("/")
+    return [
+        "/".join(part for part in (route_prefix, rule["path"]) if part)
+        for rule in artifact["cache_rules"] if _is_immutable(rule)
+    ]
+
+
+def retained_immutable_paths(artifact, route, previous_contract):
+    """Carry all bucket history forward so later route moves cannot delete it."""
+    previous_paths = previous_contract["immutable_paths"] if previous_contract else []
+    return sorted(set(previous_paths) | set(immutable_key_prefixes(artifact, route)))
+
+
 def retired_immutable_filters(artifact, route, html_dir, previous_contract):
-    """Protect immutable keys only when an old route falls inside the new scope."""
+    """Protect historical immutable keys that fall inside the current sync scope."""
     if not previous_contract:
         return []
     current_prefix = route["path"].strip("/")
-    previous_prefix = previous_contract["path"].strip("/")
-    if current_prefix:
-        marker = f"{current_prefix}/"
-        if previous_prefix == current_prefix:
-            previous_prefix = ""
-        elif not previous_prefix.startswith(marker):
-            return []
-        else:
-            previous_prefix = previous_prefix[len(marker):]
     filters = []
-    current_immutable = {
+    current_immutable = set(immutable_key_prefixes(artifact, route))
-        rule["path"] for rule in artifact["cache_rules"] if _is_immutable(rule)
-    }
     for immutable_path in previous_contract["immutable_paths"]:
-        retired_path = "/".join(part for part in (previous_prefix, immutable_path) if part)
+        if immutable_path in current_immutable:
+            continue
+        if current_prefix:
+            marker = f"{current_prefix}/"
+            if not immutable_path.startswith(marker):
+                continue
+            retired_path = immutable_path[len(marker):]
+        else:
+            retired_path = immutable_path
         collision = html_dir / retired_path
-        if (immutable_path not in current_immutable and collision.exists()
+        if collision.exists() and any(path.is_file() for path in collision.rglob("*")):
-                and any(path.is_file() for path in collision.rglob("*"))):
             raise RuntimeError(
                 f"current artifact collides with retired immutable partition: {retired_path}"
             )
@@ -308,18 +319,20 @@ def ensure_bucket_aliases(site_name, aliases, admin_token):
             raise
 
 
-def render_site_manifests(site_name, action_dir, app_dir, manifests_dir, cfg):
+def render_site_manifests(
+    site_name, action_dir, app_dir, manifests_dir, cfg, previous_contracts=None,
+):
     """Always re-render manifests from current site.yaml. Templates own
     domain + aliases, so changes propagate without manual edits."""
     manifests_dir.mkdir(parents=True, exist_ok=True)
     artifact_by_name = {artifact["name"]: artifact for artifact in cfg["artifacts"]}
+    previous_contracts = previous_contracts or {}
     routes = []
     for route in cfg["routes"]:
         artifact = artifact_by_name[route["artifact"]]
         resource_name = k8s_name(site_name) if cfg["compatibility"] else f"{k8s_name(site_name)}-{route['name']}"
-        immutable_paths = [
+        previous = previous_contracts.get(artifact["bucket"])
-            rule["path"] for rule in artifact["cache_rules"] if _is_immutable(rule)
+        immutable_paths = retained_immutable_paths(artifact, route, previous)
-        ]
         routes.append({
             **route, "resource_name": resource_name, "artifact_config": artifact,
             "immutable_paths_json": json.dumps(immutable_paths, separators=(",", ":")),
@@ -413,7 +426,9 @@ def deploy_static(site_name, site_dir, action_dir, token, cfg):
     if cfg["compatibility"]:
         ensure_bucket_aliases(site_name, cfg["aliases"], os.environ.get("GARAGE_ADMIN_TOKEN"))
 
-    render_site_manifests(site_name, action_dir, app_dir, manifests_dir, cfg)
+    render_site_manifests(
+        site_name, action_dir, app_dir, manifests_dir, cfg, previous_contracts,
+    )
 
     commit_and_push(apps_dir, f"Deploy {site_name}", token)
 

tests/test_contract.py

@@ -473,7 +473,7 @@ class PublishingTests(unittest.TestCase):
             ):
                 deploy.s3_sync(artifact, route, root, previous_contract={
                     "path": "/foo", "access": "public", "artifact": "distributions",
-                    "immutable_paths": ["releases"],
+                    "immutable_paths": ["foo/releases"],
                 })
             rendered = [" ".join(command) for command in commands]
             self.assertTrue(all("foo/releases/*" in command for command in rendered[:2]))
@@ -484,7 +484,7 @@ class PublishingTests(unittest.TestCase):
         previous = {
             "baseline-dist": {
                 "path": "/dist", "access": "protected", "artifact": "old-name",
-                "immutable_paths": ["releases"],
+                "immutable_paths": ["dist/releases"],
             }
         }
         with self.assertRaisesRegex(RuntimeError, "cannot become public while reusing protected"):
@@ -521,7 +521,7 @@ class PublishingTests(unittest.TestCase):
             html = Path(tmp)
             filters = deploy.retired_immutable_filters(artifact, route, html, {
                 "path": "/dist", "access": "public", "artifact": "distributions",
-                "immutable_paths": ["releases"],
+                "immutable_paths": ["dist/releases"],
             })
             self.assertEqual(["--exclude", "releases/*"], filters)
             (html / "releases").mkdir()
@@ -529,9 +529,44 @@ class PublishingTests(unittest.TestCase):
             with self.assertRaisesRegex(RuntimeError, "collides with retired immutable"):
                 deploy.retired_immutable_filters(artifact, route, html, {
                     "path": "/dist", "access": "public", "artifact": "distributions",
-                    "immutable_paths": ["releases"],
+                    "immutable_paths": ["dist/releases"],
                 })
 
+    def test_retired_immutable_history_survives_the_following_deployment(self):
+        cfg = normalize_site_config(fixture("split-site.yaml"), "baseline.fritzlab.net")
+        artifact = next(item for item in cfg["artifacts"] if item["name"] == "distributions")
+        artifact["cache_rules"] = [
+            rule for rule in artifact["cache_rules"] if rule["path"] != "releases"
+        ]
+        route = next(item for item in cfg["routes"] if item["artifact"] == "distributions")
+        route["path"] = "/"
+        previous = {
+            "baseline-dist": {
+                "path": "/foo", "access": "public", "artifact": "distributions",
+                "immutable_paths": ["foo/releases"],
+            }
+        }
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            app_dir = root / "app"
+            manifests = app_dir / "manifests"
+            app_dir.mkdir()
+            deploy.render_site_manifests(
+                "baseline.fritzlab.net", ROOT, app_dir, manifests, cfg, previous,
+            )
+            following = deploy.previous_route_contracts(app_dir)
+            self.assertEqual(["foo/releases"], following["baseline-dist"]["immutable_paths"])
+            html = root / "html"
+            html.mkdir()
+            first_filters = deploy.retired_immutable_filters(
+                artifact, route, html, previous["baseline-dist"],
+            )
+            following_filters = deploy.retired_immutable_filters(
+                artifact, route, html, following["baseline-dist"],
+            )
+            self.assertEqual(["--exclude", "foo/releases/*"], first_filters)
+            self.assertEqual(first_filters, following_filters)
+
     def test_later_route_immutable_failure_stops_all_mutable_publication(self):
         cfg = normalize_site_config(fixture("split-site.yaml"), "baseline.fritzlab.net")
         with tempfile.TemporaryDirectory() as tmp: