ref(etl-api): deprecate POST update-publication endpoint

crates/etl-api/src/routes/sources/publications.rs

@@ -186,8 +186,12 @@ pub(crate) async fn read_publication(
 }
 
 #[utoipa::path(
-    summary = "Update a publication",
-    description = "Replaces the publication's table list on the given source.",
+    summary = "Update a publication (deprecated)",
+    description = "Replaces the publication's table list on the given source.\n\n\
+        **Deprecated**: This endpoint uses `POST` for full replacement, which is \
+        semantically misleading because the request appears additive but actually \
+        replaces the entire table list. A replacement is being designed. See \
+        https://github.com/supabase/etl/issues/459.",
     tag = "Publications",
     request_body = UpdatePublicationRequest,
     params(
@@ -231,7 +235,16 @@ pub(crate) async fn update_publication(
     let publication = Publication { name: publication_name, tables: publication.tables };
     data::publications::update_publication(&publication, &source_pool).await?;
 
-    Ok(HttpResponse::Ok().finish())
+    // RFC 9745 §2.1 requires the Deprecation field to be an sf-date.
+    // The value is the Unix timestamp for 2026-05-15 00:00 UTC, the date
+    // this deprecation took effect.
+    Ok(HttpResponse::Ok()
+        .insert_header(("Deprecation", "@1778803200"))
+        .insert_header((
+            "Link",
+            "<https://github.com/supabase/etl/issues/459>; rel=\"deprecation\"",
+        ))
+        .finish())
 }
 
 #[utoipa::path(