feat(site-publish): add split-surface publishing

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

scripts/deploy.py

@@ -176,6 +176,12 @@ def s3_sync(artifact, route, site_dir, credential_env_names=None):
     exclude_args = [arg for pattern in artifact["excludes"] for arg in ("--exclude", pattern)]
     if artifact["excludes"]:
         print(f"Excluding patterns: {artifact['excludes']}")
+    # Validate and publish every append-only target before a mutable channel can
+    # point at it. Partial immutable success is safe; partial mutable success is
+    # not.
+    for rule in artifact["cache_rules"]:
+        if _is_immutable(rule):
+            publish_immutable_rule(artifact, route, rule, html_dir, aws_env)
     print(f"Syncing artifact {artifact['name']} → {destination} via {endpoint}")
     # Sync and deletion are scoped to the current route prefix. A route move
     # leaves its old bucket partition intact but unreachable after the old
@@ -201,7 +207,6 @@ def s3_sync(artifact, route, site_dir, credential_env_names=None):
         if not rule["path"]:
             continue
         if _is_immutable(rule):
-            publish_immutable_rule(artifact, route, rule, html_dir, aws_env)
             continue
         include = f"{rule['path'].rstrip('/')}/*"
         child_filters = [arg for path in specific_paths

tests/test_contract.py

@@ -379,21 +379,26 @@ class PublishingTests(unittest.TestCase):
             (html / "channels").mkdir()
             (html / "releases" / "1.0.js").write_text("release")
             (html / "channels" / "stable.json").write_text("channel")
-            commands = []
+            commands, events = [], []
 
             def capture(command, **kwargs):
                 commands.append((command, kwargs["env"]))
+                events.append("mutable")
+
+            def publish_immutable(*_args):
+                events.append("immutable")
 
             secret = "secret-must-not-appear"
             output = io.StringIO()
             with patch.dict(os.environ, {
                 "DIST_S3_ACCESS_KEY": "dist-key", "DIST_S3_SECRET_KEY": secret
             }, clear=False), patch.object(deploy, "run", side_effect=capture), \
-                    patch.object(deploy, "publish_immutable_rule") as immutable_publish, \
+                    patch.object(deploy, "publish_immutable_rule", side_effect=publish_immutable) as immutable_publish, \
                     redirect_stdout(output):
                 deploy.s3_sync(artifact, route, root)
 
             self.assertTrue(all(secret not in " ".join(command) for command, _ in commands))
+            self.assertEqual("immutable", events[0])
             self.assertNotIn(secret, output.getvalue())
             self.assertTrue(all(call_env["AWS_ACCESS_KEY_ID"] == "dist-key" for _, call_env in commands))
             self.assertTrue(all("DIST_S3_SECRET_KEY" not in call_env for _, call_env in commands))