From a17fe4739b14084e92350fb2ad5f145786541ef3 Mon Sep 17 00:00:00 2001
From: ssavutu <ssavutu@gmail.com>
Date: Fri, 28 Aug 2026 01:35:53 -0400
Subject: [PATCH 1/2] Stop a second article with the same title becoming the
 first one

Creating an article whose title already existed filed a second row on the
same slug. POST derived the slug from the title with no uniqueness check,
and only the dashboard's quick-draft path deduped -- client-side, with a
probe loop the full editor's New Article form never ran. Every screen then
addressed articles by slug alone, so opening the new article loaded the
older one, and the autosave that followed wrote over both: UPDATE ... WHERE
`slug` = ? matches every duplicate, and clientFoundRows reports the match
count, so nothing looked wrong. Production carried two letters in exactly
that state, one of them with its body replaced by a letter from 2022.

Reserve the slug server-side on create. The MySQL named lock is held on the
candidate rather than on the stem it was derived from: two creates can reach
the same candidate from different stems -- one titled "Foo" that becomes
foo-2, one whose slug is literally foo-2 -- and a lock on the stem would let
both insert it. The response now carries the id and the slug that were
actually written, because the server may not have stored the one it was sent.

Address articles by id everywhere else. The editor routes carry
/articles/:id/:slug/edit, the write endpoints accept ?id=, and a request that
arrives with a slug alone resolves to a single row -- preferring the caller's
archive state, then the lowest id -- before it reads, locks or writes. One
rule now governs the edit lease, the mutation lock, the excerpt derivation
and the public detail read, so the row a request locks is the row it reads
and the row it writes. Legacy /articles/:slug links keep working and resolve
the same way. Renaming a slug onto one another article holds answers 409
rather than quietly recreating the collision.

Two deadlocks surfaced while testing this, both the same shape: a handler
waiting on the connection pool while holding part of it. Create kept its
dedicated slug-lock connection across the pooled writes that follow the
insert, and the detail read kept its result rows open across the author
lookup. Neither is reachable at the production pool size; both hang outright
at the single connection the integration tests use, which is why the create
path had no working test.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WuLVSbPvAr2o4m7CqzLEVu
---
 frontend/src/App.tsx                          |   2 +
 frontend/src/pages/DashboardPage.tsx          |  15 +-
 frontend/src/pages/articleView.tsx            |  14 +-
 frontend/src/pages/commentsView.tsx           |   2 +-
 frontend/src/pages/editArticleView.test.tsx   |  25 +-
 frontend/src/pages/editArticleView.tsx        |  43 +-
 frontend/src/pages/seoView.tsx                |   2 +-
 server/docs/docs.go                           |  23 +-
 server/docs/swagger.json                      |  23 +-
 server/docs/swagger.yaml                      |  16 +
 .../internal/database/article_categories.go   |   6 -
 server/internal/database/crud.go              |   6 +-
 server/internal/database/http_models.go       | 105 ++++
 server/internal/handlers/article_edit_lock.go |  35 +-
 .../article_patch_integration_test.go         | 320 +++++++++++-
 server/internal/handlers/handlers.go          | 472 +++++++++++++++---
 server/internal/handlers/handlers_test.go     |  13 +-
 server/internal/models/api_responses.go       |   5 +
 18 files changed, 999 insertions(+), 128 deletions(-)

diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index 91bcdff..81b539a 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -120,8 +120,10 @@ export default function App() {
         <Routes>
           <Route path="/" element={<DashboardPage />} />
           <Route path="/articles" element={<ArticleView excludeType="developing-stories" />} />
+          <Route path="/articles/:id/:slug/edit" element={<EditArticleView />} />
           <Route path="/articles/:slug/edit" element={<EditArticleView />} />
           <Route path="/developing-stories" element={<DevelopingStoriesView />} />
+          <Route path="/developing-stories/:id/:slug/edit" element={<EditArticleView />} />
           <Route path="/developing-stories/:slug/edit" element={<EditArticleView />} />
           <Route path="/articles/new" element={<EditArticleView />} />
           <Route path="/developing-stories/new" element={<ComingSoon page="New developing story" />} />
diff --git a/frontend/src/pages/DashboardPage.tsx b/frontend/src/pages/DashboardPage.tsx
index 8b3c5d5..2a72e67 100644
--- a/frontend/src/pages/DashboardPage.tsx
+++ b/frontend/src/pages/DashboardPage.tsx
@@ -35,6 +35,9 @@ interface RecentArticle {
   published_date: string | null
 }
 
+const editArticlePath = (article: Pick<RecentArticle, "id" | "slug">) =>
+  `/articles/${encodeURIComponent(String(article.id))}/${encodeURIComponent(article.slug)}/edit`
+
 interface ApiStats {
   totalArticles: number | null
   publishedArticles: number | null
@@ -244,9 +247,11 @@ export default function DashboardPage() {
         throw new Error(`Save failed (${response.status})`)
       }
 
+      const created = (await response.json().catch(() => null)) as { id?: number | string; slug?: string } | null
+      const createdSlug = created?.slug || slug
       let confirmed = false
       for (let attempt = 0; attempt < 5; attempt += 1) {
-        const verifyResponse = await apiFetch(`/v1/articles/${encodeURIComponent(slug)}`)
+        const verifyResponse = await apiFetch(`/v1/articles/${encodeURIComponent(createdSlug)}`)
         if (verifyResponse.ok) {
           confirmed = true
           break
@@ -270,7 +275,11 @@ export default function DashboardPage() {
         }
       }
 
-      navigate(`/articles/${encodeURIComponent(slug)}/edit`)
+      if (created?.id !== undefined && created.id !== null) {
+        navigate(`/articles/${encodeURIComponent(String(created.id))}/${encodeURIComponent(createdSlug)}/edit`)
+      } else {
+        navigate(`/articles/${encodeURIComponent(createdSlug)}/edit`)
+      }
     } catch (err) {
       const message = err instanceof Error ? err.message : "Unable to save draft."
       setDraftError(message)
@@ -436,7 +445,7 @@ export default function DashboardPage() {
                       <tr
                         key={article.id}
                         className="hover:bg-muted/40 cursor-pointer transition-colors group"
-                        onClick={() => navigate(`/articles/${article.slug}/edit`)}
+                        onClick={() => navigate(editArticlePath(article))}
                       >
                         <td className="px-5 py-2.5 font-medium group-hover:text-primary transition-colors max-w-[240px] truncate">
                           {article.title}
diff --git a/frontend/src/pages/articleView.tsx b/frontend/src/pages/articleView.tsx
index e3828f8..2e986ff 100644
--- a/frontend/src/pages/articleView.tsx
+++ b/frontend/src/pages/articleView.tsx
@@ -488,10 +488,10 @@ function ArticleView({ pageTitle = "Articles", fixedType, excludeType }: Article
   const effectiveTotalCount = Math.max(totalArticleCount, (page * pageSize) + articles.length)
   const totalPages = Math.max(1, Math.ceil(effectiveTotalCount / pageSize))
   const listLabel = pageTitle.toLowerCase()
-  const editPathForSlug = (slug: string) =>
+  const editPathForArticle = (item: ArticleItem) =>
     fixedType === "developing-stories"
-      ? `/developing-stories/${encodeURIComponent(slug)}/edit`
-      : `/articles/${encodeURIComponent(slug)}/edit`
+      ? `/developing-stories/${encodeURIComponent(item.id)}/${encodeURIComponent(item.slug ?? "")}/edit`
+      : `/articles/${encodeURIComponent(item.id)}/${encodeURIComponent(item.slug ?? "")}/edit`
 
   // subsectionRows walks the section, then each subsection on the trail, and
   // keeps the levels that actually have children to offer.
@@ -562,7 +562,7 @@ function ArticleView({ pageTitle = "Articles", fixedType, excludeType }: Article
     setDeleteError(null)
     setDeletingArticleId(item.id)
     try {
-      const response = await apiFetch(`/v1/articles/${encodeURIComponent(item.slug)}`, {
+      const response = await apiFetch(`/v1/articles/${encodeURIComponent(item.slug)}?id=${encodeURIComponent(item.id)}`, {
         method: "DELETE",
       })
       if (!response.ok) {
@@ -589,7 +589,7 @@ function ArticleView({ pageTitle = "Articles", fixedType, excludeType }: Article
     setDeleteError(null)
     setDeletingArticleId(item.id)
     try {
-      const response = await apiFetch(`/v1/articles/${encodeURIComponent(item.slug)}/restore`, {
+      const response = await apiFetch(`/v1/articles/${encodeURIComponent(item.slug)}/restore?id=${encodeURIComponent(item.id)}`, {
         method: "PATCH",
       })
       if (!response.ok) {
@@ -830,7 +830,7 @@ function ArticleView({ pageTitle = "Articles", fixedType, excludeType }: Article
                         <Link
                           className="block min-w-0 truncate rounded-sm hover:text-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/40"
                           title={item.title}
-                          to={editPathForSlug(item.slug)}
+                          to={editPathForArticle(item)}
                         >
                           {item.title}
                         </Link>
@@ -883,7 +883,7 @@ function ArticleView({ pageTitle = "Articles", fixedType, excludeType }: Article
                         disabled={!item.slug}
                         onClick={() => {
                           if (!item.slug) return
-                          navigate(editPathForSlug(item.slug))
+                          navigate(editPathForArticle(item))
                         }}
                         title={item.slug ? "Edit" : "Edit unavailable"}
                         type="button"
diff --git a/frontend/src/pages/commentsView.tsx b/frontend/src/pages/commentsView.tsx
index 9a3061b..2288915 100644
--- a/frontend/src/pages/commentsView.tsx
+++ b/frontend/src/pages/commentsView.tsx
@@ -454,7 +454,7 @@ export default function CommentsView() {
             {comments.map((comment) => {
               const actionsDisabled = busyCommentId !== null
               const hasMappedArticle = comment.article_slug && comment.article_id > 0
-              const articlePath = hasMappedArticle ? `/articles/${encodeURIComponent(comment.article_slug)}/edit` : ""
+              const articlePath = hasMappedArticle ? `/articles/${encodeURIComponent(String(comment.article_id))}/${encodeURIComponent(comment.article_slug)}/edit` : ""
               const publicPath = comment.article_slug ? `${siteUrl}/article/${comment.article_slug}` : ""
 
               return (
diff --git a/frontend/src/pages/editArticleView.test.tsx b/frontend/src/pages/editArticleView.test.tsx
index 76ba91d..e21303c 100644
--- a/frontend/src/pages/editArticleView.test.tsx
+++ b/frontend/src/pages/editArticleView.test.tsx
@@ -105,12 +105,15 @@ vi.mock("../components/SeoAnalysis", () => ({ default: () => null }))
 
 const patchCalls = () => apiCalls.filter((call) => call.method === "PATCH")
 
-const renderEditor = async () => {
+const renderEditor = async (
+  initialEntry = `/articles/${ARTICLE_SLUG}/edit`,
+  routePath = "/articles/:slug/edit",
+) => {
   const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime })
   render(
-    <MemoryRouter initialEntries={[`/articles/${ARTICLE_SLUG}/edit`]}>
+    <MemoryRouter initialEntries={[initialEntry]}>
       <Routes>
-        <Route path="/articles/:slug/edit" element={<EditArticleView />} />
+        <Route path={routePath} element={<EditArticleView />} />
       </Routes>
     </MemoryRouter>,
   )
@@ -168,6 +171,22 @@ describe("EditArticleView autosave", () => {
     expect(patches[0].body?.content).toContain("and more")
   })
 
+  it("loads and saves by id when the editor route carries one", async () => {
+    const user = await renderEditor(
+      `/articles/42/${ARTICLE_SLUG}/edit`,
+      "/articles/:id/:slug/edit",
+    )
+
+    expect(apiCalls.some((call) => call.method === "GET" && call.url === `/v1/articles/${ARTICLE_SLUG}?id=42`)).toBe(true)
+
+    await user.type(screen.getByTestId("article-body"), " and more")
+    await waitOutAutosave()
+
+    const patches = patchCalls()
+    expect(patches).toHaveLength(1)
+    expect(patches[0].url).toBe(`/v1/articles/${ARTICLE_SLUG}?id=42`)
+  })
+
   it("does not unpublish a live article when the editor only selects Draft", async () => {
     articleStatus = "published"
     articlePublishedDate = "2025-03-04T15:30:00Z"
diff --git a/frontend/src/pages/editArticleView.tsx b/frontend/src/pages/editArticleView.tsx
index f95f08a..3ffd6f3 100644
--- a/frontend/src/pages/editArticleView.tsx
+++ b/frontend/src/pages/editArticleView.tsx
@@ -269,8 +269,11 @@ const clearArticleListCache = () => {
 function EditArticleView() {
   const navigate = useNavigate()
   const apiFetch = useApiFetch()
-  const { slug: rawSlug } = useParams<{ slug: string }>()
+  const { id: rawID, slug: rawSlug } = useParams<{ id?: string; slug: string }>()
   const slug = useMemo(() => (rawSlug ? decodeURIComponent(rawSlug) : ""), [rawSlug])
+  const articleID = useMemo(() => (rawID && /^\d+$/.test(rawID) ? rawID : ""), [rawID])
+  const articleQuery = articleID ? `?id=${encodeURIComponent(articleID)}` : ""
+  const articleApiPath = slug ? `/v1/articles/${encodeURIComponent(slug)}${articleQuery}` : ""
   const isNew = !rawSlug
 
   const [slugInput, setSlugInput] = useState("")
@@ -423,7 +426,7 @@ function EditArticleView() {
       setError(null)
       setSuccessMessage(null)
       try {
-        const response = await apiFetch(`/v1/articles/${encodeURIComponent(slug)}`)
+        const response = await apiFetch(articleApiPath)
         if (!response.ok) {
           throw new Error(await readErrorMessage(response, `Could not load article (${response.status})`))
         }
@@ -496,7 +499,7 @@ function EditArticleView() {
     return () => {
       cancelled = true
     }
-  }, [apiFetch, slug, isNew])
+  }, [apiFetch, articleApiPath, slug, isNew])
 
   // Try to claim an advisory edit lock while this article is open. If someone
   // else already holds it we surface who, block editing, and keep re-checking
@@ -507,7 +510,7 @@ function EditArticleView() {
     if (isNew || !slug) return
     setLockChecking(true)
     try {
-      const response = await apiFetch(`/v1/articles/${encodeURIComponent(slug)}/edit-lock`, { method: "PUT" })
+      const response = await apiFetch(`/v1/articles/${encodeURIComponent(slug)}/edit-lock${articleQuery}`, { method: "PUT" })
       if (response.status === 409) {
         const payload = (await response.json().catch(() => null)) as { holder_name?: string } | null
         setLockedBy(payload?.holder_name?.trim() || "another editor")
@@ -520,7 +523,7 @@ function EditArticleView() {
     } finally {
       setLockChecking(false)
     }
-  }, [apiFetch, slug, isNew])
+  }, [apiFetch, articleQuery, slug, isNew])
 
   useEffect(() => {
     if (isNew || !slug) return
@@ -532,7 +535,7 @@ function EditArticleView() {
     const release = () => {
       if (released) return
       released = true
-      void apiFetch(`/v1/articles/${encodeURIComponent(slug)}/edit-lock`, {
+      void apiFetch(`/v1/articles/${encodeURIComponent(slug)}/edit-lock${articleQuery}`, {
         method: "DELETE",
         keepalive: true,
       }).catch(() => {})
@@ -544,7 +547,7 @@ function EditArticleView() {
       window.removeEventListener("beforeunload", release)
       release()
     }
-  }, [apiFetch, slug, isNew, acquireLock])
+  }, [apiFetch, articleQuery, slug, isNew, acquireLock])
 
   useEffect(() => {
     let cancelled = false
@@ -817,11 +820,21 @@ function EditArticleView() {
           body: JSON.stringify(createPayload),
         })
         if (!response.ok) {
-          throw new Error(`Create failed (${response.status})`)
+          throw new Error(await readErrorMessage(response, `Create failed (${response.status})`))
         }
         clearArticleListCache()
         setSuccessMessage("Article created.")
-        navigate("/articles")
+        // The server owns the slug: a title or slug another article already uses
+        // comes back with a suffix. Land on the new article rather than the list
+        // so the editor is looking at the slug that was actually stored.
+        const created = (await response.json().catch(() => null)) as { id?: number; slug?: string } | null
+        if (created?.id && created.slug) {
+          navigate(`/articles/${encodeURIComponent(String(created.id))}/${encodeURIComponent(created.slug)}/edit`, {
+            replace: true,
+          })
+        } else {
+          navigate("/articles")
+        }
         return
       }
 
@@ -856,7 +869,7 @@ function EditArticleView() {
         noindex: noIndex,
       }
 
-      const response = await apiFetch(`/v1/articles/${encodeURIComponent(slug)}`, {
+      const response = await apiFetch(articleApiPath, {
         method: "PATCH",
         headers: {
           "Content-Type": "application/json",
@@ -864,7 +877,10 @@ function EditArticleView() {
         body: JSON.stringify(payload),
       })
       if (!response.ok) {
-        throw new Error(`Save failed (${response.status})`)
+        // A rename onto a slug another article holds comes back 409 with a
+        // message worth showing: the generic text would read as a save that
+        // failed for no reason.
+        throw new Error(await readErrorMessage(response, `Save failed (${response.status})`))
       }
       if (nextTiming) {
         setPublishTiming(nextTiming)
@@ -886,7 +902,8 @@ function EditArticleView() {
         // The route still points at the old slug, which no longer resolves, so
         // move the editor onto the new one before anything refetches.
         setPendingSlug(null)
-        navigate(`/articles/${encodeURIComponent(slugToSave)}/edit`, { replace: true })
+        const basePath = articleID ? `/articles/${encodeURIComponent(articleID)}` : "/articles"
+        navigate(`${basePath}/${encodeURIComponent(slugToSave)}/edit`, { replace: true })
       }
     } catch (err) {
       const message = err instanceof Error ? err.message : "Unable to save article."
@@ -918,7 +935,7 @@ function EditArticleView() {
     }, AUTOSAVE_DELAY_MS)
 
     return () => window.clearTimeout(timer)
-  }, [articleSnapshot, isAutoSaving, isLoading, isNew, isSaving, lockedBy, selectedAuthorIds, selectedCategorySlugs])
+  }, [articleApiPath, articleID, articleSnapshot, isAutoSaving, isLoading, isNew, isSaving, lockedBy, selectedAuthorIds, selectedCategorySlugs])
 
   const inputClass ="w-full px-3 py-2 rounded-lg border border-border bg-background text-sm text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-primary/40 focus:border-primary transition"
   const selectClass = "w-full px-3 py-2 rounded-lg border border-border bg-background text-sm text-foreground focus:outline-none focus:ring-2 focus:ring-primary/40 focus:border-primary transition"
diff --git a/frontend/src/pages/seoView.tsx b/frontend/src/pages/seoView.tsx
index b1d1d43..7ee97d5 100644
--- a/frontend/src/pages/seoView.tsx
+++ b/frontend/src/pages/seoView.tsx
@@ -213,7 +213,7 @@ export default function SeoView() {
               <button
                 key={`${issue.article_id}-${idx}`}
                 type="button"
-                onClick={() => navigate(`/articles/${encodeURIComponent(issue.slug)}/edit`)}
+                onClick={() => navigate(`/articles/${encodeURIComponent(String(issue.article_id))}/${encodeURIComponent(issue.slug)}/edit`)}
                 className={`flex items-start gap-3 rounded-xl border p-4 text-left transition-colors ${
                   issue.type === "error"
                     ? "border-destructive/30 bg-destructive/5 hover:bg-destructive/10"
diff --git a/server/docs/docs.go b/server/docs/docs.go
index b10c0b8..abf6f4e 100644
--- a/server/docs/docs.go
+++ b/server/docs/docs.go
@@ -194,6 +194,7 @@ const docTemplate = `{
                         "BearerAuth": []
                     }
                 ],
+                "description": "The slug is deduplicated on the way in: a title or slug that another article already uses is stored with a numeric suffix. The response carries the id and the slug that were actually written.",
                 "consumes": [
                     "application/json"
                 ],
@@ -214,7 +215,10 @@ const docTemplate = `{
                 ],
                 "responses": {
                     "201": {
-                        "description": "Created"
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/models.ArticleCreateResponse"
+                        }
                     },
                     "400": {
                         "description": "Bad Request",
@@ -227,6 +231,12 @@ const docTemplate = `{
                         "schema": {
                             "$ref": "#/definitions/models.ErrorResponse"
                         }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/models.ErrorResponse"
+                        }
                     }
                 }
             }
@@ -4514,6 +4524,17 @@ const docTemplate = `{
                 }
             }
         },
+        "models.ArticleCreateResponse": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "integer"
+                },
+                "slug": {
+                    "type": "string"
+                }
+            }
+        },
         "models.ArticleDetailResponse": {
             "type": "object",
             "properties": {
diff --git a/server/docs/swagger.json b/server/docs/swagger.json
index 899d164..6acbbd8 100644
--- a/server/docs/swagger.json
+++ b/server/docs/swagger.json
@@ -191,6 +191,7 @@
                         "BearerAuth": []
                     }
                 ],
+                "description": "The slug is deduplicated on the way in: a title or slug that another article already uses is stored with a numeric suffix. The response carries the id and the slug that were actually written.",
                 "consumes": [
                     "application/json"
                 ],
@@ -211,7 +212,10 @@
                 ],
                 "responses": {
                     "201": {
-                        "description": "Created"
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/models.ArticleCreateResponse"
+                        }
                     },
                     "400": {
                         "description": "Bad Request",
@@ -224,6 +228,12 @@
                         "schema": {
                             "$ref": "#/definitions/models.ErrorResponse"
                         }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/models.ErrorResponse"
+                        }
                     }
                 }
             }
@@ -4511,6 +4521,17 @@
                 }
             }
         },
+        "models.ArticleCreateResponse": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "integer"
+                },
+                "slug": {
+                    "type": "string"
+                }
+            }
+        },
         "models.ArticleDetailResponse": {
             "type": "object",
             "properties": {
diff --git a/server/docs/swagger.yaml b/server/docs/swagger.yaml
index 4660bdc..1993529 100644
--- a/server/docs/swagger.yaml
+++ b/server/docs/swagger.yaml
@@ -163,6 +163,13 @@ definitions:
       total_count:
         type: integer
     type: object
+  models.ArticleCreateResponse:
+    properties:
+      id:
+        type: integer
+      slug:
+        type: string
+    type: object
   models.ArticleDetailResponse:
     properties:
       authors:
@@ -1362,6 +1369,9 @@ paths:
     post:
       consumes:
       - application/json
+      description: 'The slug is deduplicated on the way in: a title or slug that another
+        article already uses is stored with a numeric suffix. The response carries
+        the id and the slug that were actually written.'
       parameters:
       - description: Article
         in: body
@@ -1372,6 +1382,8 @@ paths:
       responses:
         "201":
           description: Created
+          schema:
+            $ref: '#/definitions/models.ArticleCreateResponse'
         "400":
           description: Bad Request
           schema:
@@ -1380,6 +1392,10 @@ paths:
           description: Internal Server Error
           schema:
             $ref: '#/definitions/models.ErrorResponse'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/models.ErrorResponse'
       security:
       - BearerAuth: []
       summary: Create an article
diff --git a/server/internal/database/article_categories.go b/server/internal/database/article_categories.go
index ab37d1f..47b4b65 100644
--- a/server/internal/database/article_categories.go
+++ b/server/internal/database/article_categories.go
@@ -100,12 +100,6 @@ func normalizeCategoryList(categories []string) []string {
 	return out
 }
 
-// execer is satisfied by both *sql.DB and *sql.Tx, so the write-path helpers can
-// join a caller's transaction.
-type execer interface {
-	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
-}
-
 // ReplaceArticleCategories rewrites one article's rows. Delete-then-insert
 // rather than a diff: an article carries a handful of categories, and the
 // simpler operation cannot leave a stale row behind.
diff --git a/server/internal/database/crud.go b/server/internal/database/crud.go
index dd3d7d0..0baa4f1 100644
--- a/server/internal/database/crud.go
+++ b/server/internal/database/crud.go
@@ -7,6 +7,10 @@ import (
 	"strings"
 )
 
+type execer interface {
+	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
+}
+
 func Select(ctx context.Context, conn *sql.DB, table string, cols []string, where string, args ...any) (*sql.Rows, error) {
 	if len(cols) == 0 {
 		return nil, fmt.Errorf("select requires at least one column")
@@ -20,7 +24,7 @@ func Select(ctx context.Context, conn *sql.DB, table string, cols []string, wher
 	return conn.QueryContext(ctx, query, args...)
 }
 
-func Insert(ctx context.Context, conn *sql.DB, table string, cols []string, values ...any) (sql.Result, error) {
+func Insert(ctx context.Context, conn execer, table string, cols []string, values ...any) (sql.Result, error) {
 	if len(cols) == 0 {
 		return nil, fmt.Errorf("insert requires at least one column")
 	}
diff --git a/server/internal/database/http_models.go b/server/internal/database/http_models.go
index c63a551..e531258 100644
--- a/server/internal/database/http_models.go
+++ b/server/internal/database/http_models.go
@@ -34,6 +34,10 @@ var ArticleSortByColumn = map[string]string{
 	string(models.ArticleSortByCommentStatus): "comment_status",
 }
 
+type queryRower interface {
+	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
+}
+
 var AuthorColumns = []string{"id", "display_name", "first_name", "last_name", "email", "login", "archived_at"}
 
 // articleRow is the landing zone for a scanned article: every column at its
@@ -649,6 +653,21 @@ func GetArticleContentBySlug(ctx context.Context, conn *sql.DB, slug string) (st
 	return text.String, nil
 }
 
+// GetArticleContentByID is GetArticleContentBySlug for a request that knows
+// which row it is patching. Slugs are not unique, so deriving an excerpt from a
+// slug lookup can read a different article's body than the one being written.
+func GetArticleContentByID(ctx context.Context, conn *sql.DB, id int64) (string, error) {
+	var text sql.NullString
+	err := conn.QueryRowContext(ctx, "SELECT `text` FROM `articles` WHERE `id` = ?", id).Scan(&text)
+	if errors.Is(err, sql.ErrNoRows) {
+		return "", nil
+	}
+	if err != nil {
+		return "", err
+	}
+	return text.String, nil
+}
+
 func ParsePublishedAt(value string) *time.Time {
 	if strings.TrimSpace(value) == "" {
 		return nil
@@ -793,6 +812,92 @@ func CanonicalizeSlug(value string) string {
 	return normalizeSlug(value)
 }
 
+// ArticleSlugBase is the stem every generated slug is built from: the caller's
+// slug if it gave one, otherwise the title, otherwise a constant. Creation paths
+// must all derive it the same way -- the base names the lock that keeps two
+// concurrent creates from picking the same candidate.
+func ArticleSlugBase(requested, title string) string {
+	base := normalizeSlug(requested)
+	if base == "" {
+		base = normalizeSlug(title)
+	}
+	if base == "" {
+		base = "article"
+	}
+	return base
+}
+
+// ArticleSlugExists reports whether any article already carries the slug,
+// archived rows included: an archived article still owns its permalink, and
+// restoring it must not collide with something created in the meantime.
+func ArticleSlugExists(ctx context.Context, conn queryRower, slug string) (bool, error) {
+	var exists int
+	err := conn.QueryRowContext(ctx, "SELECT 1 FROM `articles` WHERE `slug` = ? LIMIT 1", slug).Scan(&exists)
+	if errors.Is(err, sql.ErrNoRows) {
+		return false, nil
+	}
+	if err != nil {
+		return false, err
+	}
+	return true, nil
+}
+
+// ArticleSlugTakenByOther is ArticleSlugExists for the rename paths, which must
+// ignore the row doing the renaming: saving an article without touching its slug
+// would otherwise report the article's own slug as a collision. An excludeID of
+// 0 excludes nothing, which is the right answer for a slug that resolves to no
+// row at all.
+func ArticleSlugTakenByOther(ctx context.Context, conn queryRower, slug string, excludeID int64) (bool, error) {
+	var exists int
+	err := conn.QueryRowContext(ctx,
+		"SELECT 1 FROM `articles` WHERE `slug` = ? AND `id` <> ? LIMIT 1", slug, excludeID,
+	).Scan(&exists)
+	if errors.Is(err, sql.ErrNoRows) {
+		return false, nil
+	}
+	if err != nil {
+		return false, err
+	}
+	return true, nil
+}
+
+// ResolveArticleIDBySlug picks the row a slug-only request addresses. Slugs are
+// not unique -- the index is deliberately non-UNIQUE, see EnsureArticlesSlugIndex
+// -- so "the article with this slug" has to be a rule rather than an assumption:
+// prefer the archive state the caller is working in, then take the lowest id.
+// Every path that resolves a slug uses this one function, so the row a request
+// locks is the row it reads and the row it writes.
+//
+// A slug that matches nothing returns (0, nil): the caller's own query reports
+// that as a 404 on its row count, and failing here would turn one missing
+// article into a 500.
+func ResolveArticleIDBySlug(ctx context.Context, conn queryRower, slug string, archived bool) (int64, error) {
+	state := "IS NULL"
+	if archived {
+		state = "IS NOT NULL"
+	}
+	var id int64
+	err := conn.QueryRowContext(ctx,
+		"SELECT `id` FROM `articles` WHERE `slug` = ? AND `archived_at` "+state+" ORDER BY `id` LIMIT 1", slug,
+	).Scan(&id)
+	if err == nil {
+		return id, nil
+	}
+	if !errors.Is(err, sql.ErrNoRows) {
+		return 0, err
+	}
+	err = conn.QueryRowContext(ctx,
+		"SELECT `id` FROM `articles` WHERE `slug` = ? ORDER BY `id` LIMIT 1", slug,
+	).Scan(&id)
+	if errors.Is(err, sql.ErrNoRows) {
+		return 0, nil
+	}
+	if err != nil {
+		return 0, err
+	}
+	return id, nil
+}
+
 func IsCanonicalSlug(value string) bool {
 	trimmed := strings.TrimSpace(value)
 	if trimmed == "" {
diff --git a/server/internal/handlers/article_edit_lock.go b/server/internal/handlers/article_edit_lock.go
index 08319c8..a4fd8a6 100644
--- a/server/internal/handlers/article_edit_lock.go
+++ b/server/internal/handlers/article_edit_lock.go
@@ -3,7 +3,6 @@ package handlers
 import (
 	"database/sql"
 	"net/http"
-	"strings"
 	"time"
 
 	"server/internal/middleware"
@@ -36,9 +35,9 @@ type articleEditLockResponse struct {
 // @Router /v1/articles/{slug}/edit-lock [put]
 func AcquireArticleEditLock(conn *sql.DB) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
-		slug := strings.TrimSpace(r.PathValue("slug"))
-		if !isValidCanonicalSlug(slug) {
-			writeError(w, http.StatusBadRequest, "slug must be canonical")
+		target, err := articleTargetFromRequest(r)
+		if err != nil {
+			writeError(w, http.StatusBadRequest, err.Error())
 			return
 		}
 		user, ok := middleware.UserFromContext(r.Context())
@@ -46,13 +45,22 @@ func AcquireArticleEditLock(conn *sql.DB) http.HandlerFunc {
 			writeError(w, http.StatusForbidden, "forbidden")
 			return
 		}
-		lease, granted := articleEditLeases.Acquire(slug, user.ID, user.Name)
+		// The lease is keyed by row, so two editors on the same article take the
+		// same key whether they arrived on the id-qualified route or on a legacy
+		// /articles/:slug link. Keying by whatever the URL happened to carry
+		// would hand both of them the lock.
+		target, err = resolveArticleTarget(r.Context(), conn, target, false)
+		if err != nil {
+			writeError(w, http.StatusInternalServerError, err.Error())
+			return
+		}
+		lease, granted := articleEditLeases.Acquire(target.lockKey(), user.ID, user.Name)
 		status := http.StatusOK
 		if !granted {
 			status = http.StatusConflict
 		}
 		writeJSON(w, status, articleEditLockResponse{
-			Slug:       slug,
+			Slug:       target.slug,
 			HeldBySelf: granted,
 			HolderID:   lease.HolderID,
 			HolderName: lease.HolderName,
@@ -74,9 +82,9 @@ func AcquireArticleEditLock(conn *sql.DB) http.HandlerFunc {
 // @Router /v1/articles/{slug}/edit-lock [delete]
 func ReleaseArticleEditLock(conn *sql.DB) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
-		slug := strings.TrimSpace(r.PathValue("slug"))
-		if !isValidCanonicalSlug(slug) {
-			writeError(w, http.StatusBadRequest, "slug must be canonical")
+		target, err := articleTargetFromRequest(r)
+		if err != nil {
+			writeError(w, http.StatusBadRequest, err.Error())
 			return
 		}
 		user, ok := middleware.UserFromContext(r.Context())
@@ -84,7 +92,14 @@ func ReleaseArticleEditLock(conn *sql.DB) http.HandlerFunc {
 			writeError(w, http.StatusForbidden, "forbidden")
 			return
 		}
-		articleEditLeases.Release(slug, user.ID)
+		// Resolved the same way AcquireArticleEditLock resolves it, or the
+		// release would miss the lease the acquire took.
+		target, err = resolveArticleTarget(r.Context(), conn, target, false)
+		if err != nil {
+			writeError(w, http.StatusInternalServerError, err.Error())
+			return
+		}
+		articleEditLeases.Release(target.lockKey(), user.ID)
 		w.WriteHeader(http.StatusNoContent)
 	}
 }
diff --git a/server/internal/handlers/article_patch_integration_test.go b/server/internal/handlers/article_patch_integration_test.go
index ba7302d..e8014d9 100644
--- a/server/internal/handlers/article_patch_integration_test.go
+++ b/server/internal/handlers/article_patch_integration_test.go
@@ -3,10 +3,13 @@ package handlers
 import (
 	"context"
 	"database/sql"
+	"encoding/json"
 	"net/http"
 	"net/http/httptest"
 	"os"
+	"strconv"
 	"strings"
+	"sync"
 	"testing"
 	"time"
 
@@ -68,10 +71,11 @@ func articlePatchTestDB(t *testing.T) *sql.DB {
 		CREATE TABLE articles (
 			id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
 			title LONGTEXT,
-			slug VARCHAR(255) NOT NULL UNIQUE,
+			slug VARCHAR(255) NOT NULL,
 			description LONGTEXT,
 			excerpt LONGTEXT,
 			tags LONGTEXT,
+			metadata LONGTEXT,
 			`+"`text`"+` LONGTEXT,
 			categories LONGTEXT,
 			authors LONGTEXT,
@@ -139,6 +143,17 @@ func patchArticleRequest(slug, body string) *http.Request {
 	return req.WithContext(middleware.ContextWithUser(req.Context(), &models.User{ID: 1, Name: "Editor", Role: models.RoleEditor}))
 }
 
+func patchArticleRequestWithID(slug string, id int64, body string) *http.Request {
+	req := httptest.NewRequest(http.MethodPatch, "/v1/articles/"+slug+"?id="+strconv.FormatInt(id, 10), strings.NewReader(body))
+	req.SetPathValue("slug", slug)
+	return req.WithContext(middleware.ContextWithUser(req.Context(), &models.User{ID: 1, Name: "Editor", Role: models.RoleEditor}))
+}
+
+func postArticleRequest(body string) *http.Request {
+	req := httptest.NewRequest(http.MethodPost, "/v1/articles", strings.NewReader(body))
+	return req.WithContext(middleware.ContextWithUser(req.Context(), &models.User{ID: 1, Name: "Editor", Role: models.RoleEditor}))
+}
+
 func articlePubDate(t *testing.T, conn *sql.DB, slug string) sql.NullTime {
 	t.Helper()
 	var pubDate sql.NullTime
@@ -148,6 +163,309 @@ func articlePubDate(t *testing.T, conn *sql.DB, slug string) sql.NullTime {
 	return pubDate
 }
 
+func TestPostArticleHTTP_DuplicateTitleGetsUniqueSlug(t *testing.T) {
+	conn := articlePatchTestDB(t)
+	if _, err := conn.ExecContext(context.Background(),
+		"INSERT INTO articles (title, slug, `text`, categories) VALUES (?, ?, ?, ?)",
+		"Letter from the editor", "letter-from-the-editor", "Old body", "News",
+	); err != nil {
+		t.Fatalf("seed article: %v", err)
+	}
+
+	rec := httptest.NewRecorder()
+	body := `{"title":"Letter from the editor","content":"New body","status":"draft",` +
+		`"comment_status":"open","photo_url":"","categories":["News"],"authors":[]}`
+	PostArticles(conn).ServeHTTP(rec, postArticleRequest(body))
+
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("post status = %d, want 201; body = %s", rec.Code, rec.Body.String())
+	}
+	var created models.ArticleCreateResponse
+	if err := json.Unmarshal(rec.Body.Bytes(), &created); err != nil {
+		t.Fatalf("decode created article: %v", err)
+	}
+	if created.Slug != "letter-from-the-editor-2" {
+		t.Fatalf("created slug = %q, want letter-from-the-editor-2", created.Slug)
+	}
+
+	var count int
+	if err := conn.QueryRowContext(context.Background(),
+		"SELECT COUNT(*) FROM articles WHERE title = ?",
+		"Letter from the editor",
+	).Scan(&count); err != nil {
+		t.Fatalf("count articles: %v", err)
+	}
+	if count != 2 {
+		t.Fatalf("matching title count = %d, want 2", count)
+	}
+}
+
+func TestArticlePatchHTTP_IDQualifiedPatchOnlyUpdatesThatRow(t *testing.T) {
+	conn := articlePatchTestDB(t)
+	result, err := conn.ExecContext(context.Background(),
+		"INSERT INTO articles (title, slug, `text`, categories) VALUES (?, ?, ?, ?), (?, ?, ?, ?)",
+		"Original", "letter-from-the-editor", "Old body", "News",
+		"Duplicate", "letter-from-the-editor", "New draft", "News",
+	)
+	if err != nil {
+		t.Fatalf("seed duplicated slug articles: %v", err)
+	}
+	firstID, err := result.LastInsertId()
+	if err != nil {
+		t.Fatalf("first insert id: %v", err)
+	}
+	secondID := firstID + 1
+
+	rec := httptest.NewRecorder()
+	body := `{"title":"Edited duplicate","excerpt":"","content":"Edited body",` +
+		`"comment_status":"open","photo_url":"","breaking_news":false,"categories":["News"],` +
+		`"tags":[],"authors":[],"focus_keyword":"","meta_description":"","seo_title":""}`
+	PatchArticle(conn).ServeHTTP(rec, patchArticleRequestWithID("letter-from-the-editor", secondID, body))
+
+	if rec.Code != http.StatusNoContent {
+		t.Fatalf("patch status = %d, want 204; body = %s", rec.Code, rec.Body.String())
+	}
+
+	var firstTitle, firstText, secondTitle, secondText string
+	if err := conn.QueryRowContext(context.Background(), "SELECT title, `text` FROM articles WHERE id = ?", firstID).Scan(&firstTitle, &firstText); err != nil {
+		t.Fatalf("read first article: %v", err)
+	}
+	if err := conn.QueryRowContext(context.Background(), "SELECT title, `text` FROM articles WHERE id = ?", secondID).Scan(&secondTitle, &secondText); err != nil {
+		t.Fatalf("read second article: %v", err)
+	}
+	if firstTitle != "Original" || firstText != "Old body" {
+		t.Fatalf("first article changed to title=%q text=%q", firstTitle, firstText)
+	}
+	if secondTitle != "Edited duplicate" || secondText != "Edited body" {
+		t.Fatalf("second article = title %q text %q, want edited row", secondTitle, secondText)
+	}
+}
+
+// The newsroom's report, end to end: an editor opens New Article, types a title
+// another article already carries, and leaves the slug field blank. Before the
+// id-qualified routes this filed a second row on the same slug, and every
+// screen that addressed the article by slug then showed the FIRST one -- so the
+// new article "became" the old one.
+func TestArticleFlowHTTP_SecondArticleWithTheSameTitleStaysItsOwnArticle(t *testing.T) {
+	conn := articlePatchTestDB(t)
+	if _, err := conn.ExecContext(context.Background(),
+		"INSERT INTO articles (title, slug, `text`, categories, pub_date) VALUES (?, ?, ?, ?, ?)",
+		"Letter from the editor", "letter-from-the-editor", "Last term's letter.", "News", "2025-01-05 12:00:00",
+	); err != nil {
+		t.Fatalf("seed the existing letter: %v", err)
+	}
+
+	// The editor's New Article form sends an empty slug; the server derives it.
+	rec := httptest.NewRecorder()
+	body := `{"title":"Letter from the editor","slug":"","content":"This term's letter.",` +
+		`"status":"draft","comment_status":"open","photo_url":"","categories":["News"],"authors":[]}`
+	PostArticles(conn).ServeHTTP(rec, postArticleRequest(body))
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("post status = %d, want 201; body = %s", rec.Code, rec.Body.String())
+	}
+	var created models.ArticleCreateResponse
+	if err := json.Unmarshal(rec.Body.Bytes(), &created); err != nil {
+		t.Fatalf("decode created article: %v", err)
+	}
+	if created.Slug != "letter-from-the-editor-2" {
+		t.Fatalf("created slug = %q, want letter-from-the-editor-2", created.Slug)
+	}
+
+	// Opening it in the CMS must load the new letter, not the old one.
+	rec = httptest.NewRecorder()
+	getReq := httptest.NewRequest(http.MethodGet, "/v1/articles/"+created.Slug+"?id="+strconv.FormatInt(created.ID, 10), nil)
+	getReq.SetPathValue("slug", created.Slug)
+	getReq = getReq.WithContext(middleware.ContextWithUser(getReq.Context(), &models.User{ID: 1, Name: "Editor", Role: models.RoleEditor}))
+	GetArticle(conn).ServeHTTP(rec, getReq)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("get status = %d, want 200; body = %s", rec.Code, rec.Body.String())
+	}
+	if !strings.Contains(rec.Body.String(), "This term's letter.") {
+		t.Fatalf("editor opened the wrong article: %s", rec.Body.String())
+	}
+
+	// And saving it must not write over the old one.
+	rec = httptest.NewRecorder()
+	patch := `{"title":"Letter from the editor","content":"This term's letter, edited.","comment_status":"open"}`
+	PatchArticle(conn).ServeHTTP(rec, patchArticleRequestWithID(created.Slug, created.ID, patch))
+	if rec.Code != http.StatusNoContent {
+		t.Fatalf("patch status = %d, want 204; body = %s", rec.Code, rec.Body.String())
+	}
+
+	var oldText string
+	if err := conn.QueryRowContext(context.Background(),
+		"SELECT `text` FROM articles WHERE slug = ?", "letter-from-the-editor",
+	).Scan(&oldText); err != nil {
+		t.Fatalf("read the existing letter: %v", err)
+	}
+	if oldText != "Last term's letter." {
+		t.Fatalf("the existing letter was overwritten: %q", oldText)
+	}
+}
+
+// The duplicates already in production keep their shared slug until someone
+// renames one, so a slug-only read has to answer with the same row every time
+// rather than whichever the scan reached first.
+func TestGetArticleHTTP_DuplicateSlugResolvesToTheSameRowEveryTime(t *testing.T) {
+	conn := articlePatchTestDB(t)
+	if _, err := conn.ExecContext(context.Background(),
+		"INSERT INTO articles (title, slug, `text`, categories, pub_date) VALUES (?, ?, ?, ?, ?), (?, ?, ?, ?, ?)",
+		"Original", "letter-from-the-editor", "The first letter.", "News", "2025-01-05 12:00:00",
+		"Duplicate", "letter-from-the-editor", "The second letter.", "News", "2025-02-05 12:00:00",
+	); err != nil {
+		t.Fatalf("seed duplicated slug articles: %v", err)
+	}
+
+	for attempt := 0; attempt < 3; attempt++ {
+		rec := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodGet, "/v1/articles/letter-from-the-editor", nil)
+		req.SetPathValue("slug", "letter-from-the-editor")
+		GetArticle(conn).ServeHTTP(rec, req)
+		if rec.Code != http.StatusOK {
+			t.Fatalf("get status = %d, want 200; body = %s", rec.Code, rec.Body.String())
+		}
+		if !strings.Contains(rec.Body.String(), "The first letter.") {
+			t.Fatalf("attempt %d resolved to a different row: %s", attempt, rec.Body.String())
+		}
+	}
+}
+
+func TestArticlePatchHTTP_ExcerptDerivesFromThePatchedRow(t *testing.T) {
+	conn := articlePatchTestDB(t)
+	result, err := conn.ExecContext(context.Background(),
+		"INSERT INTO articles (title, slug, `text`, categories) VALUES (?, ?, ?, ?), (?, ?, ?, ?)",
+		"Original", "letter-from-the-editor", "The body of the first letter.", "News",
+		"Duplicate", "letter-from-the-editor", "The body of the second letter.", "News",
+	)
+	if err != nil {
+		t.Fatalf("seed duplicated slug articles: %v", err)
+	}
+	firstID, err := result.LastInsertId()
+	if err != nil {
+		t.Fatalf("first insert id: %v", err)
+	}
+	secondID := firstID + 1
+
+	// A blank excerpt with no content in the patch is the editor's ordinary
+	// save, and the derived summary has to come from the row being written.
+	rec := httptest.NewRecorder()
+	body := `{"excerpt":"","comment_status":"open"}`
+	PatchArticle(conn).ServeHTTP(rec, patchArticleRequestWithID("letter-from-the-editor", secondID, body))
+
+	if rec.Code != http.StatusNoContent {
+		t.Fatalf("patch status = %d, want 204; body = %s", rec.Code, rec.Body.String())
+	}
+
+	var excerpt string
+	if err := conn.QueryRowContext(context.Background(), "SELECT excerpt FROM articles WHERE id = ?", secondID).Scan(&excerpt); err != nil {
+		t.Fatalf("read second article: %v", err)
+	}
+	if !strings.Contains(excerpt, "second letter") {
+		t.Fatalf("excerpt = %q, want it derived from the second article's body", excerpt)
+	}
+}
+
+func TestArticlePatchHTTP_RenameOntoTakenSlugConflicts(t *testing.T) {
+	conn := articlePatchTestDB(t)
+	result, err := conn.ExecContext(context.Background(),
+		"INSERT INTO articles (title, slug, `text`, categories) VALUES (?, ?, ?, ?), (?, ?, ?, ?)",
+		"Taken", "letter-from-the-editor", "Old body", "News",
+		"Renaming", "a-second-letter", "New body", "News",
+	)
+	if err != nil {
+		t.Fatalf("seed articles: %v", err)
+	}
+	firstID, err := result.LastInsertId()
+	if err != nil {
+		t.Fatalf("first insert id: %v", err)
+	}
+	secondID := firstID + 1
+
+	rec := httptest.NewRecorder()
+	body := `{"slug":"letter-from-the-editor","comment_status":"open"}`
+	PatchArticle(conn).ServeHTTP(rec, patchArticleRequestWithID("a-second-letter", secondID, body))
+
+	if rec.Code != http.StatusConflict {
+		t.Fatalf("patch status = %d, want 409; body = %s", rec.Code, rec.Body.String())
+	}
+
+	var slug string
+	if err := conn.QueryRowContext(context.Background(), "SELECT slug FROM articles WHERE id = ?", secondID).Scan(&slug); err != nil {
+		t.Fatalf("read renamed article: %v", err)
+	}
+	if slug != "a-second-letter" {
+		t.Fatalf("slug = %q, want the rename rejected", slug)
+	}
+}
+
+// A save that leaves the slug alone still sends it, so the collision check has
+// to ignore the row doing the saving.
+func TestArticlePatchHTTP_ResavingItsOwnSlugIsNotAConflict(t *testing.T) {
+	conn := articlePatchTestDB(t)
+	if _, err := conn.ExecContext(context.Background(),
+		"INSERT INTO articles (title, slug, `text`, categories) VALUES (?, ?, ?, ?)",
+		"Only", "letter-from-the-editor", "Old body", "News",
+	); err != nil {
+		t.Fatalf("seed article: %v", err)
+	}
+
+	rec := httptest.NewRecorder()
+	body := `{"slug":"letter-from-the-editor","title":"Edited","comment_status":"open"}`
+	PatchArticle(conn).ServeHTTP(rec, patchArticleRequest("letter-from-the-editor", body))
+
+	if rec.Code != http.StatusNoContent {
+		t.Fatalf("patch status = %d, want 204; body = %s", rec.Code, rec.Body.String())
+	}
+}
+
+// A create that reuses a title also has to survive concurrently, which is the
+// case the per-candidate slug lock exists for.
+func TestPostArticleHTTP_ConcurrentDuplicateTitlesGetDistinctSlugs(t *testing.T) {
+	conn := articlePatchTestDB(t)
+	// The shared test pool is a single connection; the create path needs one
+	// for its slug lock and the pool for everything after it.
+	conn.SetMaxOpenConns(4)
+	conn.SetMaxIdleConns(4)
+
+	body := `{"title":"Letter from the editor","content":"Body","status":"draft",` +
+		`"comment_status":"open","photo_url":"","categories":["News"],"authors":[]}`
+
+	const creates = 4
+	slugs := make(chan string, creates)
+	var wg sync.WaitGroup
+	for i := 0; i < creates; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			rec := httptest.NewRecorder()
+			PostArticles(conn).ServeHTTP(rec, postArticleRequest(body))
+			if rec.Code != http.StatusCreated {
+				t.Errorf("post status = %d, want 201; body = %s", rec.Code, rec.Body.String())
+				return
+			}
+			var created models.ArticleCreateResponse
+			if err := json.Unmarshal(rec.Body.Bytes(), &created); err != nil {
+				t.Errorf("decode created article: %v", err)
+				return
+			}
+			slugs <- created.Slug
+		}()
+	}
+	wg.Wait()
+	close(slugs)
+
+	seen := map[string]bool{}
+	for slug := range slugs {
+		if seen[slug] {
+			t.Fatalf("slug %q was handed out twice", slug)
+		}
+		seen[slug] = true
+	}
+	if len(seen) != creates {
+		t.Fatalf("got %d distinct slugs, want %d", len(seen), creates)
+	}
+}
+
 func TestArticlePatchHTTP_PublishedSaveKeepsOriginalPublishDate(t *testing.T) {
 	conn := articlePatchTestDB(t)
 	original := time.Date(2025, 3, 4, 15, 30, 0, 0, time.UTC)
diff --git a/server/internal/handlers/handlers.go b/server/internal/handlers/handlers.go
index f404cd1..9d62848 100644
--- a/server/internal/handlers/handlers.go
+++ b/server/internal/handlers/handlers.go
@@ -4,7 +4,9 @@ import (
 	"context"
 	"database/sql"
 	"encoding/json"
+	"errors"
 	"fmt"
+	"hash/fnv"
 	"log/slog"
 	"net"
 	"net/http"
@@ -69,6 +71,196 @@ func writeError(w http.ResponseWriter, status int, msg string) {
 	writeJSON(w, status, models.ErrorResponse{Error: msg})
 }
 
+type articleTarget struct {
+	slug  string
+	id    int64
+	hasID bool
+}
+
+func articleTargetFromRequest(r *http.Request) (articleTarget, error) {
+	slug := strings.TrimSpace(r.PathValue("slug"))
+	if !isValidCanonicalSlug(slug) {
+		return articleTarget{}, fmt.Errorf("slug must be canonical")
+	}
+	rawID := strings.TrimSpace(r.URL.Query().Get("id"))
+	if rawID == "" {
+		return articleTarget{slug: slug}, nil
+	}
+	id, err := strconv.ParseInt(rawID, 10, 64)
+	if err != nil || id <= 0 {
+		return articleTarget{}, fmt.Errorf("id must be a positive integer")
+	}
+	return articleTarget{slug: slug, id: id, hasID: true}, nil
+}
+
+// resolveArticleTarget pins a slug-only request to one row before anything reads
+// or locks. Slugs are not unique, so without this the same request could lock
+// one duplicate, read a second and write a third; the legacy /articles/:slug
+// links that predate the id-qualified routes all arrive this way. The archived
+// flag says which state the caller works in, so a restore resolves the archived
+// twin and a save resolves the live one.
+//
+// A slug matching no row leaves the target unresolved. The handler's own query
+// then reports the 404 on its row count, which is the same answer it gave before.
+func resolveArticleTarget(ctx context.Context, conn *sql.DB, target articleTarget, archived bool) (articleTarget, error) {
+	if target.hasID {
+		return target, nil
+	}
+	id, err := db.ResolveArticleIDBySlug(ctx, conn, target.slug, archived)
+	if err != nil {
+		return target, err
+	}
+	if id == 0 {
+		return target, nil
+	}
+	target.id = id
+	target.hasID = true
+	return target, nil
+}
+
+func (target articleTarget) lockKey() string {
+	if target.hasID {
+		return fmt.Sprintf("id:%d", target.id)
+	}
+	return "slug:" + target.slug
+}
+
+func (target articleTarget) articleWhere() (string, []any) {
+	if target.hasID {
+		return "`id` = ? AND `slug` = ?", []any{target.id, target.slug}
+	}
+	return "`slug` = ?", []any{target.slug}
+}
+
+func (target articleTarget) articleWhereArchived(archived bool) (string, []any) {
+	where, args := target.articleWhere()
+	if archived {
+		return where + " AND `archived_at` IS NOT NULL", args
+	}
+	return where + " AND `archived_at` IS NULL", args
+}
+
+// errArticleSlugLockBusy separates "another create holds this slug" from a
+// broken database, so the caller can answer 503 and invite a retry instead of
+// reporting a server fault.
+var errArticleSlugLockBusy = errors.New("timed out waiting for the article slug lock")
+
+func articleCreateDBLockName(candidate string) string {
+	// MySQL caps a lock name at 64 characters and slugs in the corpus run to
+	// 154, so the name is a hash rather than the slug itself. A collision only
+	// serializes two unrelated creates, which is the behaviour we want anyway.
+	hash := fnv.New64a()
+	_, _ = hash.Write([]byte(candidate))
+	return "article-create:" + strconv.FormatUint(hash.Sum64(), 36)
+}
+
+func acquireArticleCreateDBLock(ctx context.Context, conn *sql.Conn, candidate string) (func(), error) {
+	lockName := articleCreateDBLockName(candidate)
+	var acquired sql.NullInt64
+	if err := conn.QueryRowContext(ctx, "SELECT GET_LOCK(?, 10)", lockName).Scan(&acquired); err != nil {
+		return nil, err
+	}
+	if !acquired.Valid || acquired.Int64 != 1 {
+		return nil, errArticleSlugLockBusy
+	}
+	return func() {
+		var released sql.NullInt64
+		_ = conn.QueryRowContext(context.Background(), "SELECT RELEASE_LOCK(?)", lockName).Scan(&released)
+	}, nil
+}
+
+// reserveArticleSlug returns a free slug and the lock that keeps it free until
+// the insert lands.
+//
+// The lock is held on the CANDIDATE, not on the stem it was derived from. Two
+// creates can reach the same candidate from different stems -- one titled "Foo"
+// whose slug becomes foo-2, one whose slug is literally foo-2 -- and a lock on
+// the stem would let those two run concurrently and both insert foo-2. The
+// candidate is the thing that has to be unique, so the candidate is the thing
+// that is locked.
+func reserveArticleSlug(ctx context.Context, conn *sql.Conn, requested, title string) (string, func(), error) {
+	base := db.ArticleSlugBase(requested, title)
+	for suffix := 1; suffix <= 100; suffix++ {
+		candidate := base
+		if suffix > 1 {
+			candidate = fmt.Sprintf("%s-%d", base, suffix)
+		}
+		release, err := acquireArticleCreateDBLock(ctx, conn, candidate)
+		if err != nil {
+			return "", nil, err
+		}
+		taken, err := db.ArticleSlugExists(ctx, conn, candidate)
+		if err != nil {
+			release()
+			return "", nil, err
+		}
+		if !taken {
+			return candidate, release, nil
+		}
+		release()
+	}
+	return "", nil, fmt.Errorf("every slug from %q to %q is already taken", base, fmt.Sprintf("%s-%d", base, 100))
+}
+
+// insertArticleWithUniqueSlug holds a pooled connection for exactly as long as
+// the slug reservation and the insert need it.
+//
+// The connection is dedicated because GET_LOCK is scoped to one, and it is
+// released here rather than deferred to the end of the request because
+// everything the create does afterwards -- authors, categories, taxonomy counts
+// -- goes back to the pool. A handler that held this connection across those
+// calls would be waiting on the pool while holding part of it, which deadlocks
+// outright once the pool is the single connection the integration tests use.
+func insertArticleWithUniqueSlug(ctx context.Context, conn *sql.DB, body *models.ArticleInput) (int64, error) {
+	lockedConn, err := conn.Conn(ctx)
+	if err != nil {
+		return 0, err
+	}
+	defer lockedConn.Close()
+
+	slug, releaseSlug, err := reserveArticleSlug(ctx, lockedConn, body.Slug, body.Title)
+	if err != nil {
+		return 0, err
+	}
+	defer releaseSlug()
+	body.Slug = slug
+
+	result, err := db.Insert(ctx, lockedConn, "articles",
+		[]string{"title", "slug", "description", "text", "excerpt", "categories", "pub_date", "mod_date", "priority", "breaking_news", "comment_status", "photo_url", "tags", "metadata", "focus_keyword", "meta_description", "seo_title", "creation_date", "scheduled_pub_date", "canonical_url", "noindex", "photo_alt"},
+		db.ArticleInputToDBFields(*body)...,
+	)
+	if err != nil {
+		return 0, err
+	}
+	return result.LastInsertId()
+}
+
+// rejectTakenSlug answers 409 when a rename would land on a slug another article
+// already holds. Creation dedupes silently because it picked the slug itself; a
+// rename carries a slug the editor typed, and quietly storing a different one
+// would leave them looking at a permalink the site does not serve.
+func rejectTakenSlug(w http.ResponseWriter, r *http.Request, conn *sql.DB, target articleTarget, newSlug string) bool {
+	if newSlug == "" || newSlug == target.slug {
+		return false
+	}
+	// An unresolved target is a slug that matches no article. That is a 404, and
+	// the caller's own write reports it as one; answering 409 here would explain
+	// the wrong problem.
+	if !target.hasID {
+		return false
+	}
+	taken, err := db.ArticleSlugTakenByOther(r.Context(), conn, newSlug, target.id)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, err.Error())
+		return true
+	}
+	if taken {
+		writeError(w, http.StatusConflict, "slug is already taken by another article")
+		return true
+	}
+	return false
+}
+
 // publicReadCacheControl bounds how stale a public read may be.
 //
 // Without a Cache-Control header every intermediary picks its own heuristic,
@@ -359,14 +551,12 @@ func reconcileTaxonomyArticleCounts(ctx context.Context, conn *sql.DB, oldCatego
 	return nil
 }
 
-func loadArticleCategoriesByArchiveState(ctx context.Context, conn *sql.DB, slug string, archived bool) ([]string, bool, error) {
-	query := "SELECT categories FROM articles WHERE slug = ? AND archived_at IS NULL LIMIT 1"
-	if archived {
-		query = "SELECT categories FROM articles WHERE slug = ? AND archived_at IS NOT NULL LIMIT 1"
-	}
+func loadArticleCategoriesByArchiveState(ctx context.Context, conn *sql.DB, target articleTarget, archived bool) ([]string, bool, error) {
+	where, args := target.articleWhereArchived(archived)
+	query := "SELECT categories FROM articles WHERE " + where + " LIMIT 1"
 
 	var raw sql.NullString
-	err := conn.QueryRowContext(ctx, query, slug).Scan(&raw)
+	err := conn.QueryRowContext(ctx, query, args...).Scan(&raw)
 	if err == sql.ErrNoRows {
 		return nil, false, nil
 	}
@@ -379,10 +569,11 @@ func loadArticleCategoriesByArchiveState(ctx context.Context, conn *sql.DB, slug
 // last_pub_date remembers the publish date an article had before it was pulled
 // back to draft, so re-publishing restores the original date instead of stamping
 // today's. See articlePatchDateColumns.
-func loadArticlePublishDate(ctx context.Context, conn *sql.DB, slug string) (publishedAt, lastPublishedAt sql.NullTime, err error) {
+func loadArticlePublishDate(ctx context.Context, conn *sql.DB, target articleTarget) (publishedAt, lastPublishedAt sql.NullTime, err error) {
+	where, args := target.articleWhereArchived(false)
 	err = conn.QueryRowContext(ctx,
-		"SELECT pub_date, last_pub_date FROM articles WHERE slug = ? AND archived_at IS NULL LIMIT 1",
-		slug,
+		"SELECT pub_date, last_pub_date FROM articles WHERE "+where+" LIMIT 1",
+		args...,
 	).Scan(&publishedAt, &lastPublishedAt)
 	if err == sql.ErrNoRows {
 		return sql.NullTime{}, sql.NullTime{}, nil
@@ -1657,6 +1848,24 @@ func GetSearch(conn *sql.DB, embedder QueryEmbedder) http.HandlerFunc {
 	}
 }
 
+// scanOneArticle reads the first row of a single-article query and releases the
+// connection before returning, so the caller is free to make its follow-up
+// queries. It takes the (rows, err) pair straight from the query call.
+func scanOneArticle(rows *sql.Rows, queryErr error) (models.Article, bool, error) {
+	if queryErr != nil {
+		return models.Article{}, false, queryErr
+	}
+	defer rows.Close()
+	if !rows.Next() {
+		return models.Article{}, false, rows.Err()
+	}
+	a, err := db.ScanArticle(rows)
+	if err != nil {
+		return models.Article{}, false, err
+	}
+	return a, true, rows.Close()
+}
+
 // articleDetailCondition builds the WHERE clause for a single-article lookup.
 // The endpoint is public and returns the FULL article body, so an anonymous
 // caller is restricted to live content: knowing or guessing a slug must not
@@ -1664,11 +1873,18 @@ func GetSearch(conn *sql.DB, embedder QueryEmbedder) http.HandlerFunc {
 // to the same 404 as a nonexistent slug, so the response never reveals that the
 // article exists. Editors are identified by OptionalAuth on the route and still
 // see everything.
+//
+// The ORDER BY is not decoration. Slugs are not unique, so without it a slug
+// carried by two published articles answers with whichever row the scan reached
+// first -- which can differ between two requests for the same URL, and puts
+// whichever one won into a shared cache. Lowest id is the same rule the editor
+// paths resolve by, so the public page and the editor agree on which article a
+// duplicated slug means.
 func articleDetailCondition(r *http.Request) string {
 	if _, isEditor := middleware.UserFromContext(r.Context()); isEditor {
-		return "`slug` = ?"
+		return "`slug` = ? ORDER BY `id` LIMIT 1"
 	}
-	return "`slug` = ? AND `pub_date` IS NOT NULL AND `pub_date` <= UTC_TIMESTAMP() AND `archived_at` IS NULL"
+	return "`slug` = ? AND `pub_date` IS NOT NULL AND `pub_date` <= UTC_TIMESTAMP() AND `archived_at` IS NULL ORDER BY `id` LIMIT 1"
 }
 
 // @Summary Get an article by slug
@@ -1683,9 +1899,9 @@ func articleDetailCondition(r *http.Request) string {
 // @Router /v1/articles/{slug} [get]
 func GetArticle(conn *sql.DB) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
-		slug := strings.TrimSpace(r.PathValue("slug"))
-		if !isValidCanonicalSlug(slug) {
-			writeError(w, http.StatusBadRequest, "slug must be canonical")
+		target, err := articleTargetFromRequest(r)
+		if err != nil {
+			writeError(w, http.StatusBadRequest, err.Error())
 			return
 		}
 		// This endpoint is public and returns the FULL article body, so an
@@ -1694,21 +1910,36 @@ func GetArticle(conn *sql.DB) http.HandlerFunc {
 		// The miss falls through to the same 404 as a nonexistent slug, so the
 		// response does not reveal that the article exists at all. Editors are
 		// identified by OptionalAuth on the route and still see everything.
-		rows, err := db.Select(r.Context(), conn, "articles", db.ArticleColumns, articleDetailCondition(r), slug)
+		where := articleDetailCondition(r)
+		args := []any{target.slug}
+		if _, isEditor := middleware.UserFromContext(r.Context()); isEditor {
+			// Resolve even without an ?id=: an editor who followed a legacy
+			// /articles/:slug link must load the row a later save will write,
+			// and "whichever duplicate the scan reached first" is not that row.
+			target, err = resolveArticleTarget(r.Context(), conn, target, false)
+			if err != nil {
+				writeError(w, http.StatusInternalServerError, err.Error())
+				return
+			}
+			if target.hasID {
+				where, args = target.articleWhere()
+				where += " LIMIT 1"
+			}
+		}
+		// Scanned and closed in one step, before anything else queries. An open
+		// *sql.Rows holds its pooled connection, and the author lookup below
+		// wants a second one -- a handler that kept both would be waiting on a
+		// pool it is itself holding, which stalls outright once the pool is the
+		// single connection the integration tests use.
+		a, found, err := scanOneArticle(db.Select(r.Context(), conn, "articles", db.ArticleColumns, where, args...))
 		if err != nil {
 			writeError(w, http.StatusInternalServerError, err.Error())
 			return
 		}
-		defer rows.Close()
-		if !rows.Next() {
+		if !found {
 			writeError(w, http.StatusNotFound, "article not found")
 			return
 		}
-		a, err := db.ScanArticle(rows)
-		if err != nil {
-			writeError(w, http.StatusInternalServerError, err.Error())
-			return
-		}
 		articles := []models.Article{a}
 		if err := db.PopulateArticleAuthors(r.Context(), conn, articles); err != nil {
 			writeError(w, http.StatusInternalServerError, err.Error())
@@ -2192,10 +2423,12 @@ func DeleteComment(conn *sql.DB) http.HandlerFunc {
 // @Summary Create an article
 // @Tags articles
 // @Accept json
+// @Description The slug is deduplicated on the way in: a title or slug that another article already uses is stored with a numeric suffix. The response carries the id and the slug that were actually written.
 // @Param body body models.ArticleInput true "Article"
-// @Success 201
+// @Success 201 {object} models.ArticleCreateResponse
 // @Failure 400 {object} models.ErrorResponse
 // @Failure 500 {object} models.ErrorResponse
+// @Failure 503 {object} models.ErrorResponse
 // @Security BearerAuth
 // @Router /v1/articles [post]
 func PostArticles(conn *sql.DB) http.HandlerFunc {
@@ -2220,17 +2453,15 @@ func PostArticles(conn *sql.DB) http.HandlerFunc {
 			writeError(w, http.StatusBadRequest, "canonical_url must be an absolute http(s) URL")
 			return
 		}
-		fields := db.ArticleInputToDBFields(body)
-		result, err := db.Insert(r.Context(), conn, "articles",
-			[]string{"title", "slug", "description", "text", "excerpt", "categories", "pub_date", "mod_date", "priority", "breaking_news", "comment_status", "photo_url", "tags", "metadata", "focus_keyword", "meta_description", "seo_title", "creation_date", "scheduled_pub_date", "canonical_url", "noindex", "photo_alt"},
-			fields...,
-		)
-		if err != nil {
-			writeError(w, http.StatusInternalServerError, err.Error())
-			return
-		}
-		articleID, err := result.LastInsertId()
+		// Two editors filing "Letter from the editor" on the same afternoon is
+		// the ordinary case, not the rare one, so the slug is deduped rather
+		// than rejected. body.Slug comes back carrying whatever was reserved.
+		articleID, err := insertArticleWithUniqueSlug(r.Context(), conn, &body)
 		if err != nil {
+			if errors.Is(err, errArticleSlugLockBusy) {
+				writeError(w, http.StatusServiceUnavailable, err.Error())
+				return
+			}
 			writeError(w, http.StatusInternalServerError, err.Error())
 			return
 		}
@@ -2257,8 +2488,8 @@ func PostArticles(conn *sql.DB) http.HandlerFunc {
 		if body.Status == models.ArticleStatusPublished {
 			action = "article_published"
 		}
-		activity.LogRequest(r, action, body.Title, "slug", strings.TrimSpace(body.Slug), "article_id", articleID)
-		w.WriteHeader(http.StatusCreated)
+		activity.LogRequest(r, action, body.Title, "slug", body.Slug, "article_id", articleID)
+		writeJSON(w, http.StatusCreated, models.ArticleCreateResponse{ID: articleID, Slug: body.Slug})
 	}
 }
 
@@ -2275,23 +2506,31 @@ func PostArticles(conn *sql.DB) http.HandlerFunc {
 // @Router /v1/articles/{slug} [put]
 func PutArticle(conn *sql.DB) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
-		slug := strings.TrimSpace(r.PathValue("slug"))
-		if !isValidCanonicalSlug(slug) {
-			writeError(w, http.StatusBadRequest, "slug must be canonical")
+		target, err := articleTargetFromRequest(r)
+		if err != nil {
+			writeError(w, http.StatusBadRequest, err.Error())
 			return
 		}
-		unlock := articleEditLocks.Lock(slug)
-		defer unlock()
 		if !requireArticleWriteRole(w, r) {
 			return
 		}
+		// Resolve before locking: the lock has to name the row, not the slug,
+		// or a request arriving on a legacy /articles/:slug URL and one on the
+		// id-qualified route would take different keys for the same article.
+		target, err = resolveArticleTarget(r.Context(), conn, target, false)
+		if err != nil {
+			writeError(w, http.StatusInternalServerError, err.Error())
+			return
+		}
+		unlock := articleEditLocks.Lock(target.lockKey())
+		defer unlock()
 		var body models.Article
 		if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
 			writeError(w, http.StatusBadRequest, "invalid JSON")
 			return
 		}
 		if strings.TrimSpace(body.Slug) == "" {
-			body.Slug = slug
+			body.Slug = target.slug
 		} else if !isValidCanonicalSlug(body.Slug) {
 			writeError(w, http.StatusBadRequest, "slug must be canonical")
 			return
@@ -2300,16 +2539,20 @@ func PutArticle(conn *sql.DB) http.HandlerFunc {
 			writeError(w, http.StatusBadRequest, "canonical_url must be an absolute http(s) URL")
 			return
 		}
-		oldCategories, isActiveArticle, err := loadArticleCategoriesByArchiveState(r.Context(), conn, slug, false)
+		if rejectTakenSlug(w, r, conn, target, strings.TrimSpace(body.Slug)) {
+			return
+		}
+		oldCategories, isActiveArticle, err := loadArticleCategoriesByArchiveState(r.Context(), conn, target, false)
 		if err != nil {
 			writeError(w, http.StatusInternalServerError, err.Error())
 			return
 		}
 		fields := db.ArticleToDBFields(body)
-		fields = append(fields, slug)
+		where, whereArgs := target.articleWhere()
+		fields = append(fields, whereArgs...)
 		result, err := db.Update(r.Context(), conn, "articles",
 			[]string{"title", "slug", "excerpt", "text", "categories", "pub_date", "mod_date", "priority", "breaking_news", "comment_status", "photo_url", "focus_keyword", "meta_description", "seo_title", "scheduled_pub_date", "canonical_url", "noindex", "photo_alt"},
-			"`slug` = ?",
+			where,
 			fields...,
 		)
 		if err != nil {
@@ -2328,12 +2571,23 @@ func PutArticle(conn *sql.DB) http.HandlerFunc {
 		// See PatchArticle: featuring is exclusive, so the previous pick is
 		// cleared once this one is safely written.
 		if body.IsFeatured {
-			if err := db.ClearFeaturedExcept(r.Context(), conn, body.Slug); err != nil {
+			var err error
+			if target.hasID {
+				err = db.ClearFeaturedExceptID(r.Context(), conn, target.id)
+			} else {
+				err = db.ClearFeaturedExcept(r.Context(), conn, body.Slug)
+			}
+			if err != nil {
 				writeError(w, http.StatusInternalServerError, err.Error())
 				return
 			}
 		}
-		if err := db.ReplaceArticleAuthorsBySlug(r.Context(), conn, body.Slug, authorIDsFromOverviews(body.Authors)); err != nil {
+		if target.hasID {
+			err = db.ReplaceArticleAuthors(r.Context(), conn, target.id, authorIDsFromOverviews(body.Authors))
+		} else {
+			err = db.ReplaceArticleAuthorsBySlug(r.Context(), conn, body.Slug, authorIDsFromOverviews(body.Authors))
+		}
+		if err != nil {
 			if err == sql.ErrNoRows {
 				writeError(w, http.StatusNotFound, "article not found")
 				return
@@ -2346,7 +2600,12 @@ func PutArticle(conn *sql.DB) http.HandlerFunc {
 		// the article is filed, which is true of archived rows too -- they are
 		// excluded by the listing's own archived_at predicate, not by being
 		// missing from here.
-		if err := db.ReplaceArticleCategoriesBySlug(r.Context(), conn, body.Slug, body.Categories); err != nil {
+		if target.hasID {
+			err = db.ReplaceArticleCategories(r.Context(), conn, target.id, body.Categories)
+		} else {
+			err = db.ReplaceArticleCategoriesBySlug(r.Context(), conn, body.Slug, body.Categories)
+		}
+		if err != nil {
 			writeError(w, http.StatusInternalServerError, err.Error())
 			return
 		}
@@ -2374,28 +2633,35 @@ func PutArticle(conn *sql.DB) http.HandlerFunc {
 // @Router /v1/articles/{slug} [patch]
 func PatchArticle(conn *sql.DB) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
-		slug := strings.TrimSpace(r.PathValue("slug"))
-		if !isValidCanonicalSlug(slug) {
-			writeError(w, http.StatusBadRequest, "slug must be canonical")
+		target, err := articleTargetFromRequest(r)
+		if err != nil {
+			writeError(w, http.StatusBadRequest, err.Error())
 			return
 		}
-		unlock := articleEditLocks.Lock(slug)
-		defer unlock()
 		if !requireArticleWriteRole(w, r) {
 			return
 		}
+		// See PutArticle: the lock names the resolved row, so every route that
+		// reaches this article contends on the same key.
+		target, err = resolveArticleTarget(r.Context(), conn, target, false)
+		if err != nil {
+			writeError(w, http.StatusInternalServerError, err.Error())
+			return
+		}
+		unlock := articleEditLocks.Lock(target.lockKey())
+		defer unlock()
 		var body map[string]any
 		if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
 			writeError(w, http.StatusBadRequest, "invalid JSON")
 			return
 		}
 		var authorIDs *[]int64
-		oldCategories, isActiveArticle, err := loadArticleCategoriesByArchiveState(r.Context(), conn, slug, false)
+		oldCategories, isActiveArticle, err := loadArticleCategoriesByArchiveState(r.Context(), conn, target, false)
 		if err != nil {
 			writeError(w, http.StatusInternalServerError, err.Error())
 			return
 		}
-		currentPublishedAt, lastPublishedAt, err := loadArticlePublishDate(r.Context(), conn, slug)
+		currentPublishedAt, lastPublishedAt, err := loadArticlePublishDate(r.Context(), conn, target)
 		if err != nil {
 			writeError(w, http.StatusInternalServerError, err.Error())
 			return
@@ -2433,6 +2699,7 @@ func PatchArticle(conn *sql.DB) http.HandlerFunc {
 		}
 		var publishedDateValue any
 		var scheduledDateValue any
+		renamedSlug := ""
 		featuring := false
 		publishedDateSet := false
 		var statusValue models.ArticleStatus
@@ -2535,7 +2802,15 @@ func PatchArticle(conn *sql.DB) http.HandlerFunc {
 				// from the body rather than from whatever the loop has processed.
 				content, _ := body["content"].(string)
 				if strings.TrimSpace(content) == "" {
-					stored, err := db.GetArticleContentBySlug(r.Context(), conn, slug)
+					// By id where there is one: a slug lookup can read a
+					// different article's body than the one being written.
+					var stored string
+					var err error
+					if target.hasID {
+						stored, err = db.GetArticleContentByID(r.Context(), conn, target.id)
+					} else {
+						stored, err = db.GetArticleContentBySlug(r.Context(), conn, target.slug)
+					}
 					if err != nil {
 						writeError(w, http.StatusInternalServerError, err.Error())
 						return
@@ -2585,6 +2860,7 @@ func PatchArticle(conn *sql.DB) http.HandlerFunc {
 					writeError(w, http.StatusBadRequest, "slug must be canonical")
 					return
 				}
+				renamedSlug = trimmed
 				setCols = append(setCols, column)
 				setArgs = append(setArgs, trimmed)
 			default:
@@ -2600,11 +2876,15 @@ func PatchArticle(conn *sql.DB) http.HandlerFunc {
 			writeError(w, http.StatusBadRequest, "no valid fields to update")
 			return
 		}
-		targetSlug := slug
+		if rejectTakenSlug(w, r, conn, target, renamedSlug) {
+			return
+		}
+		targetSlug := target.slug
 		setCols = append(setCols, "mod_date")
 		setArgs = append(setArgs, time.Now().UTC().Format("2006-01-02 15:04:05"))
 		if len(setCols) > 0 {
-			result, err := db.Update(r.Context(), conn, "articles", setCols, "`slug` = ?", append(setArgs, slug)...)
+			where, whereArgs := target.articleWhere()
+			result, err := db.Update(r.Context(), conn, "articles", setCols, where, append(setArgs, whereArgs...)...)
 			if err != nil {
 				writeError(w, http.StatusInternalServerError, err.Error())
 				return
@@ -2626,13 +2906,24 @@ func PatchArticle(conn *sql.DB) http.HandlerFunc {
 		// card, and leaving the old pick flagged would make the tiebreak, not
 		// the editor, decide which story runs.
 		if featuring {
-			if err := db.ClearFeaturedExcept(r.Context(), conn, targetSlug); err != nil {
+			var err error
+			if target.hasID {
+				err = db.ClearFeaturedExceptID(r.Context(), conn, target.id)
+			} else {
+				err = db.ClearFeaturedExcept(r.Context(), conn, targetSlug)
+			}
+			if err != nil {
 				writeError(w, http.StatusInternalServerError, err.Error())
 				return
 			}
 		}
 		if authorIDs != nil {
-			if err := db.ReplaceArticleAuthorsBySlug(r.Context(), conn, targetSlug, *authorIDs); err != nil {
+			if target.hasID {
+				err = db.ReplaceArticleAuthors(r.Context(), conn, target.id, *authorIDs)
+			} else {
+				err = db.ReplaceArticleAuthorsBySlug(r.Context(), conn, targetSlug, *authorIDs)
+			}
+			if err != nil {
 				if err == sql.ErrNoRows {
 					writeError(w, http.StatusNotFound, "article not found")
 					return
@@ -2644,7 +2935,12 @@ func PatchArticle(conn *sql.DB) http.HandlerFunc {
 		// nextCategories is oldCategories unless this patch carried a categories
 		// field, so an unrelated patch rewrites the index to what it already
 		// held rather than clearing it.
-		if err := db.ReplaceArticleCategoriesBySlug(r.Context(), conn, targetSlug, nextCategories); err != nil {
+		if target.hasID {
+			err = db.ReplaceArticleCategories(r.Context(), conn, target.id, nextCategories)
+		} else {
+			err = db.ReplaceArticleCategoriesBySlug(r.Context(), conn, targetSlug, nextCategories)
+		}
+		if err != nil {
 			writeError(w, http.StatusInternalServerError, err.Error())
 			return
 		}
@@ -2654,11 +2950,11 @@ func PatchArticle(conn *sql.DB) http.HandlerFunc {
 				return
 			}
 		}
-		target := targetSlug
+		logTarget := targetSlug
 		if rawTitle, ok := body["title"].(string); ok && strings.TrimSpace(rawTitle) != "" {
-			target = strings.TrimSpace(rawTitle)
+			logTarget = strings.TrimSpace(rawTitle)
 		}
-		activity.LogRequest(r, "article_updated", target, "slug", targetSlug)
+		activity.LogRequest(r, "article_updated", logTarget, "slug", targetSlug)
 		w.WriteHeader(http.StatusNoContent)
 	}
 }
@@ -2673,17 +2969,25 @@ func PatchArticle(conn *sql.DB) http.HandlerFunc {
 // @Router /v1/articles/{slug} [delete]
 func DeleteArticle(conn *sql.DB) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
-		slug := strings.TrimSpace(r.PathValue("slug"))
-		if !isValidCanonicalSlug(slug) {
-			writeError(w, http.StatusBadRequest, "slug must be canonical")
+		target, err := articleTargetFromRequest(r)
+		if err != nil {
+			writeError(w, http.StatusBadRequest, err.Error())
 			return
 		}
-		unlock := articleEditLocks.Lock(slug)
-		defer unlock()
 		if !requireArticleWriteRole(w, r) {
 			return
 		}
-		categories, found, err := loadArticleCategoriesByArchiveState(r.Context(), conn, slug, false)
+		// See PutArticle. The archive state matters here: a slug shared by an
+		// archived row and a live one has to resolve to the one this handler
+		// can actually act on.
+		target, err = resolveArticleTarget(r.Context(), conn, target, false)
+		if err != nil {
+			writeError(w, http.StatusInternalServerError, err.Error())
+			return
+		}
+		unlock := articleEditLocks.Lock(target.lockKey())
+		defer unlock()
+		categories, found, err := loadArticleCategoriesByArchiveState(r.Context(), conn, target, false)
 		if err != nil {
 			writeError(w, http.StatusInternalServerError, err.Error())
 			return
@@ -2692,7 +2996,8 @@ func DeleteArticle(conn *sql.DB) http.HandlerFunc {
 			writeError(w, http.StatusNotFound, "article not found")
 			return
 		}
-		result, err := conn.ExecContext(r.Context(), "UPDATE `articles` SET `archived_at` = NOW() WHERE `slug` = ? AND `archived_at` IS NULL", slug)
+		where, args := target.articleWhereArchived(false)
+		result, err := conn.ExecContext(r.Context(), "UPDATE `articles` SET `archived_at` = NOW() WHERE "+where, args...)
 		if err != nil {
 			writeError(w, http.StatusInternalServerError, err.Error())
 			return
@@ -2705,7 +3010,7 @@ func DeleteArticle(conn *sql.DB) http.HandlerFunc {
 			writeError(w, http.StatusInternalServerError, err.Error())
 			return
 		}
-		activity.LogRequest(r, "article_deleted", slug)
+		activity.LogRequest(r, "article_deleted", target.slug, "article_id", target.id)
 		w.WriteHeader(http.StatusNoContent)
 	}
 }
@@ -2720,17 +3025,25 @@ func DeleteArticle(conn *sql.DB) http.HandlerFunc {
 // @Router /v1/articles/{slug}/restore [patch]
 func RestoreArticle(conn *sql.DB) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
-		slug := strings.TrimSpace(r.PathValue("slug"))
-		if !isValidCanonicalSlug(slug) {
-			writeError(w, http.StatusBadRequest, "slug must be canonical")
+		target, err := articleTargetFromRequest(r)
+		if err != nil {
+			writeError(w, http.StatusBadRequest, err.Error())
 			return
 		}
-		unlock := articleEditLocks.Lock(slug)
-		defer unlock()
 		if !requireArticleWriteRole(w, r) {
 			return
 		}
-		categories, found, err := loadArticleCategoriesByArchiveState(r.Context(), conn, slug, true)
+		// See PutArticle. The archive state matters here: a slug shared by an
+		// archived row and a live one has to resolve to the one this handler
+		// can actually act on.
+		target, err = resolveArticleTarget(r.Context(), conn, target, true)
+		if err != nil {
+			writeError(w, http.StatusInternalServerError, err.Error())
+			return
+		}
+		unlock := articleEditLocks.Lock(target.lockKey())
+		defer unlock()
+		categories, found, err := loadArticleCategoriesByArchiveState(r.Context(), conn, target, true)
 		if err != nil {
 			writeError(w, http.StatusInternalServerError, err.Error())
 			return
@@ -2739,7 +3052,8 @@ func RestoreArticle(conn *sql.DB) http.HandlerFunc {
 			writeError(w, http.StatusNotFound, "article not found")
 			return
 		}
-		result, err := conn.ExecContext(r.Context(), "UPDATE `articles` SET `archived_at` = NULL WHERE `slug` = ? AND `archived_at` IS NOT NULL", slug)
+		where, args := target.articleWhereArchived(true)
+		result, err := conn.ExecContext(r.Context(), "UPDATE `articles` SET `archived_at` = NULL WHERE "+where, args...)
 		if err != nil {
 			writeError(w, http.StatusInternalServerError, err.Error())
 			return
@@ -2752,7 +3066,7 @@ func RestoreArticle(conn *sql.DB) http.HandlerFunc {
 			writeError(w, http.StatusInternalServerError, err.Error())
 			return
 		}
-		activity.LogRequest(r, "article_restored", slug)
+		activity.LogRequest(r, "article_restored", target.slug, "article_id", target.id)
 		w.WriteHeader(http.StatusNoContent)
 	}
 }
diff --git a/server/internal/handlers/handlers_test.go b/server/internal/handlers/handlers_test.go
index 2d5d850..bf66064 100644
--- a/server/internal/handlers/handlers_test.go
+++ b/server/internal/handlers/handlers_test.go
@@ -432,6 +432,9 @@ func TestArticleDetailCondition_AnonymousSeesOnlyLiveArticles(t *testing.T) {
 	if !strings.Contains(got, "`archived_at` IS NULL") {
 		t.Fatalf("anonymous lookup must exclude archived articles, got %q", got)
 	}
+	if !strings.Contains(got, "ORDER BY `id` LIMIT 1") {
+		t.Fatalf("lookup must resolve duplicates deterministically, got %q", got)
+	}
 }
 
 func TestArticleDetailCondition_EditorSeesEverything(t *testing.T) {
@@ -440,9 +443,17 @@ func TestArticleDetailCondition_EditorSeesEverything(t *testing.T) {
 
 	got := articleDetailCondition(req)
 
-	if got != "`slug` = ?" {
+	if !strings.HasPrefix(got, "`slug` = ?") {
+		t.Fatalf("editor lookup must match on the slug, got %q", got)
+	}
+	if strings.Contains(got, "pub_date") || strings.Contains(got, "archived_at") {
 		t.Fatalf("editor lookup must not be narrowed, got %q", got)
 	}
+	// Duplicated slugs make "the article" a choice, and it has to be the same
+	// choice every time.
+	if !strings.Contains(got, "ORDER BY `id` LIMIT 1") {
+		t.Fatalf("lookup must resolve duplicates deterministically, got %q", got)
+	}
 }
 
 // A draft created in the CMS has neither authors nor categories until an editor
diff --git a/server/internal/models/api_responses.go b/server/internal/models/api_responses.go
index 87f9a69..493b621 100644
--- a/server/internal/models/api_responses.go
+++ b/server/internal/models/api_responses.go
@@ -78,6 +78,11 @@ type ArticlesResponse struct {
 	Pagination Pagination        `json:"pagination"`
 }
 
+type ArticleCreateResponse struct {
+	ID   int64  `json:"id"`
+	Slug string `json:"slug"`
+}
+
 type AuthorsResponse struct {
 	Authors    []AuthorOverview `json:"authors"`
 	Pagination Pagination       `json:"pagination"`

From 597fb6a6297e8684f2cb7fab7767ada69a207fae Mon Sep 17 00:00:00 2001
From: ssavutu <ssavutu@gmail.com>
Date: Fri, 28 Aug 2026 01:36:21 -0400
Subject: [PATCH 2/2] Add a report for articles that already share a slug

The fix stops new collisions; it does not repair the rows that predate it.
Slugs are not unique in the corpus -- the index is deliberately non-UNIQUE,
see EnsureArticlesSlugIndex -- so finding the affected articles is a query
somebody has to run, and deciding which of a pair keeps the permalink is a
rule somebody has to pick.

Report-only by default: it prints each shared slug, which row currently
serves it, and which rows are shadowed. The row that keeps the bare slug is
the one the site serves today -- lowest id among the non-archived rows, or
the lowest id overall if the whole group is archived -- which is what
GetArticle resolves to, so the repair never moves a URL a reader or a search
engine already has. Only rows that had no working permalink get renamed, and
they take the first free numeric suffix, the same rule the create path uses.

Archived rows are included. They keep their slug in the trash and would
collide again the moment someone restores one.

Run against production 2026-08-28: five shared slugs across 10187 articles,
two of them a published letter shadowing a draft filed the same day.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WuLVSbPvAr2o4m7CqzLEVu
---
 scripts/report_duplicate_slugs.py | 305 ++++++++++++++++++++++++++++++
 1 file changed, 305 insertions(+)
 create mode 100644 scripts/report_duplicate_slugs.py

diff --git a/scripts/report_duplicate_slugs.py b/scripts/report_duplicate_slugs.py
new file mode 100644
index 0000000..4e78800
--- /dev/null
+++ b/scripts/report_duplicate_slugs.py
@@ -0,0 +1,305 @@
+#!/usr/bin/env python3
+"""List the articles that share a slug, and optionally give each one its own.
+
+Two articles can carry the same slug: `articles`.`slug` has a prefix index and
+no UNIQUE constraint (see EnsureArticlesSlugIndex for why), and until the
+id-qualified editor routes landed, creating an article whose title matched an
+existing one filed a second row on the same slug. The CMS then addressed
+articles by slug alone, so opening either one loaded the first match -- the
+newer article "became" the older one.
+
+  python ./scripts/report_duplicate_slugs.py \
+      --cms-dsn 'triangle_user@tcp(10.248.40.183:4006)/triangle' --skip-ssl
+
+The password comes from CMS_DB_PASSWORD (or a prompt), never from argv.
+Read-only by default: it prints the groups and exits. Pass --apply to rename
+the shadowed rows.
+
+WHICH ROW KEEPS THE BARE SLUG. The one the site serves today: the lowest id
+among the non-archived rows, or the lowest id overall if every row in the group
+is archived. That is exactly what GetArticle resolves a duplicated slug to, so
+the repair never moves a URL a reader or Google already has -- it only gives a
+working permalink to the rows that had none. The others are renamed with the
+same numeric suffix the create path would have picked, first free wins.
+
+Re-runnable: a second run finds nothing, because the first left one row per
+slug. Archived rows are included -- they keep their slug in the trash and would
+otherwise collide again the moment someone restores one.
+"""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+DSN_RE = re.compile(
+    r"^(?P<user>[^:@/]+)(?::(?P<password>[^@]*))?@tcp\((?P<host>[^:)]+)(?::(?P<port>\d+))?\)/(?P<database>[^?]+)"
+)
+
+# The server stops at -100 (see reserveArticleSlug); a repair that searched
+# further would hand out a slug the create path could never reach.
+MAX_SUFFIX = 100
+
+
+class Fail(Exception):
+    """A preflight or verification failure with a human-readable reason."""
+
+
+def info(msg: str) -> None:
+    print(f"  {msg}")
+
+
+def step(msg: str) -> None:
+    print(f"\n==> {msg}")
+
+
+def warn(msg: str) -> None:
+    # stdout is block-buffered when piped; flush so warnings land in sequence
+    # with the surrounding progress output instead of ahead of all of it.
+    sys.stdout.flush()
+    print(f"  WARNING: {msg}", file=sys.stderr)
+    sys.stderr.flush()
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Report (and optionally repair) articles that share a slug."
+    )
+    parser.add_argument(
+        "--cms-dsn",
+        required=True,
+        help="CMS database: user:password@tcp(host:port)/database (password optional)",
+    )
+    parser.add_argument(
+        "--apply",
+        action="store_true",
+        help="rename the shadowed rows; without it the script only reports",
+    )
+    parser.add_argument(
+        "--skip-ssl",
+        action="store_true",
+        help=(
+            "connect without TLS. Needed via the MaxScale proxy (10.248.40.183:4006), "
+            "which does not offer TLS while MariaDB clients 11.4+ require it by default; "
+            "the backend reaches it the same way over the internal LAN."
+        ),
+    )
+    return parser.parse_args()
+
+
+def resolve_dsn(dsn: str, label: str, password_env: str) -> dict:
+    match = DSN_RE.match(dsn.strip())
+    if not match:
+        raise Fail(f"--{label}-dsn must look like user:password@tcp(host:port)/database")
+
+    parts = match.groupdict()
+    target = {
+        "user": parts["user"],
+        "host": parts["host"],
+        "port": int(parts["port"] or 3306),
+        "database": parts["database"],
+        "password": parts["password"] or os.getenv(password_env) or "",
+    }
+    if not target["password"]:
+        if not sys.stdin.isatty():
+            raise Fail(f"no password for {label}: set {password_env}, or run interactively.")
+        target["password"] = getpass.getpass(f"Password for {target['user']}@{target['host']} ({label}): ")
+    return target
+
+
+def mysql_client() -> str:
+    for candidate in ("mariadb", "mysql"):
+        if shutil.which(candidate):
+            return candidate
+    raise Fail("neither `mariadb` nor `mysql` is on PATH; install a MariaDB client.")
+
+
+class Client:
+    """Runs SQL against one target without ever putting the password in argv."""
+
+    def __init__(self, target: dict, skip_ssl: bool = False):
+        self.target = target
+        self.binary = mysql_client()
+        # An option file keeps the password out of `ps` and shell history. 0600,
+        # in a private temp dir, removed on exit.
+        self._dir = tempfile.mkdtemp(prefix="triangle-dupe-slugs-")
+        self.defaults = Path(self._dir) / "my.cnf"
+        self.defaults.write_text(
+            "[client]\n"
+            f"host={target['host']}\n"
+            f"port={target['port']}\n"
+            f"user={target['user']}\n"
+            f"password={target['password']}\n"
+            + ("ssl=0\n" if skip_ssl else ""),
+            encoding="utf-8",
+        )
+        self.defaults.chmod(0o600)
+
+    def cleanup(self) -> None:
+        shutil.rmtree(self._dir, ignore_errors=True)
+
+    def rows(self, sql: str) -> list[list[str]]:
+        cmd = [self.binary, f"--defaults-file={self.defaults}", self.target["database"], "-N", "-B", "-e", sql]
+        done = subprocess.run(cmd, capture_output=True, text=True)
+        if done.returncode != 0:
+            raise Fail(f"query failed on {self.target['database']}: {done.stderr.strip()}")
+        return [line.split("\t") for line in done.stdout.splitlines() if line]
+
+    def execute_script(self, statements: list[str]) -> None:
+        """Run many statements in one transaction, fed over stdin so the payload
+        never has to fit in an argv-sized -e argument."""
+        script = Path(self._dir) / "repair.sql"
+        script.write_text(
+            "START TRANSACTION;\n" + "\n".join(statements) + "\nCOMMIT;\n",
+            encoding="utf-8",
+        )
+        cmd = [self.binary, f"--defaults-file={self.defaults}", self.target["database"]]
+        with script.open("rb") as handle:
+            done = subprocess.run(cmd, stdin=handle, capture_output=True, text=True)
+        if done.returncode != 0:
+            raise Fail(f"repair failed on {self.target['database']}: {done.stderr.strip()}")
+
+
+def quote(value: str) -> str:
+    """Single-quoted SQL literal. These strings come from the database, so they
+    get escaped rather than trusted."""
+    escaped = value.replace("\\", "\\\\").replace("'", "\\'")
+    return f"'{escaped}'"
+
+
+def load_duplicate_groups(cms: Client) -> dict[str, list[dict]]:
+    """Every row whose slug is shared, newest-last within each group."""
+    rows = cms.rows(
+        "SELECT a.`id`, a.`slug`, COALESCE(a.`title`, ''), "
+        "  a.`pub_date` IS NOT NULL AND a.`pub_date` <= UTC_TIMESTAMP(), "
+        "  a.`archived_at` IS NOT NULL "
+        "FROM `articles` a "
+        "JOIN (SELECT `slug` FROM `articles` GROUP BY `slug` HAVING COUNT(*) > 1) d "
+        "  ON d.`slug` = a.`slug` "
+        "ORDER BY a.`slug`, a.`id`"
+    )
+    groups: dict[str, list[dict]] = {}
+    for row in rows:
+        if len(row) < 5:
+            continue
+        groups.setdefault(row[1], []).append(
+            {
+                "id": int(row[0]),
+                "slug": row[1],
+                "title": row[2],
+                "live": row[3] == "1",
+                "archived": row[4] == "1",
+            }
+        )
+    return groups
+
+
+def load_all_slugs(cms: Client) -> set[str]:
+    return {row[0] for row in cms.rows("SELECT `slug` FROM `articles`") if row}
+
+
+def keeper_of(group: list[dict]) -> dict:
+    """The row the site serves for this slug today, which is the row that keeps
+    it. Mirrors GetArticle: non-archived first, then lowest id."""
+    active = [row for row in group if not row["archived"]]
+    return min(active or group, key=lambda row: row["id"])
+
+
+def next_free_slug(base: str, taken: set[str]) -> str:
+    for suffix in range(2, MAX_SUFFIX + 1):
+        candidate = f"{base}-{suffix}"
+        if candidate not in taken:
+            return candidate
+    raise Fail(f"every slug from {base}-2 to {base}-{MAX_SUFFIX} is already taken")
+
+
+def describe(row: dict, keeper: bool) -> str:
+    state = "archived" if row["archived"] else ("live" if row["live"] else "draft")
+    marker = "keeps slug" if keeper else "SHADOWED"
+    return f"#{row['id']:<7} {state:<8} {marker:<10} {row['title'][:60]}"
+
+
+def main() -> int:
+    args = parse_args()
+    cms_client: Client | None = None
+
+    try:
+        cms_client = Client(resolve_dsn(args.cms_dsn, "cms", "CMS_DB_PASSWORD"), skip_ssl=args.skip_ssl)
+
+        step("Scanning for shared slugs")
+        groups = load_duplicate_groups(cms_client)
+        if not groups:
+            info("No article shares a slug with another. Nothing to do.")
+            return 0
+        shadowed_total = sum(len(rows) - 1 for rows in groups.values())
+        info(f"{len(groups)} slug(s) shared by {shadowed_total + len(groups)} article(s)")
+
+        step("Groups")
+        taken = load_all_slugs(cms_client)
+        renames: list[tuple[dict, str]] = []
+        for slug, rows in sorted(groups.items()):
+            keeper = keeper_of(rows)
+            info(f"{slug}")
+            for row in rows:
+                is_keeper = row["id"] == keeper["id"]
+                info(f"    {describe(row, is_keeper)}")
+                if is_keeper:
+                    continue
+                candidate = next_free_slug(slug, taken)
+                taken.add(candidate)
+                renames.append((row, candidate))
+
+        # A group whose shadowed rows are all archived costs nothing today: the
+        # trash is not served. It still gets renamed, because restoring one
+        # would put the collision straight back.
+        live_shadowed = [row for row, _ in renames if not row["archived"] and row["live"]]
+        if live_shadowed:
+            warn(
+                f"{len(live_shadowed)} published article(s) are unreachable on the public site: "
+                "their slug serves a different article."
+            )
+
+        step("Applying" if args.apply else "Planned renames")
+        for row, candidate in renames:
+            info(f"#{row['id']:<7} {row['slug']}  ->  {candidate}")
+        if not args.apply:
+            info("")
+            info("Read-only run: nothing written. Re-run with --apply to rename the shadowed rows.")
+            return 0
+
+        statements = [
+            f"UPDATE `articles` SET `slug` = {quote(candidate)} WHERE `id` = {row['id']};"
+            for row, candidate in renames
+        ]
+        cms_client.execute_script(statements)
+        info(f"{len(statements)} article(s) renamed.")
+
+        remaining = load_duplicate_groups(cms_client)
+        if remaining:
+            raise Fail(f"{len(remaining)} slug(s) are still shared; re-run to see them")
+        info("Every article now has its own slug.")
+
+        # article_categories and articles_authors both key on articles.id, and
+        # the taxonomy counts bucket by category, so a slug rename touches
+        # neither. Only the permalink moves, and only for rows that had no
+        # working permalink to begin with.
+        info("No index or count rebuild needed; ask the public site to purge its cache for the renamed paths.")
+        return 0
+
+    except Fail as err:
+        print(f"\nERROR: {err}", file=sys.stderr)
+        return 1
+    finally:
+        if cms_client:
+            cms_client.cleanup()
+
+
+if __name__ == "__main__":
+    sys.exit(main())