From 46e24993a5b5bcfbbbfd70f20bd76f708f947c04 Mon Sep 17 00:00:00 2001
From: Jesus Armando Anaya <armando@robomous.ai>
Date: Tue, 18 Aug 2026 16:56:42 -0700
Subject: [PATCH 1/4] fix(schema): count the blast radius in the narrowing
 confirmation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The narrowing confirmation dialog asked to confirm without saying what
confirming costs. It now states how many classes narrow and that zero
annotations use what is removed — a measured number, since blockers
is always empty on a preview that reaches this dialog. Drops the
'existing annotations are not touched' line, which promised something
about post-publish annotation state the kernel has not decided.
---
 frontend/ui-core/src/screens/SchemaEditor.tsx | 30 +++++++++++--
 frontend/ui-core/src/screens/screens.test.tsx | 43 +++++++++++++++++++
 2 files changed, 69 insertions(+), 4 deletions(-)

diff --git a/frontend/ui-core/src/screens/SchemaEditor.tsx b/frontend/ui-core/src/screens/SchemaEditor.tsx
index 7580b3c6..6cb89983 100644
--- a/frontend/ui-core/src/screens/SchemaEditor.tsx
+++ b/frontend/ui-core/src/screens/SchemaEditor.tsx
@@ -1250,7 +1250,26 @@ function describeDestructiveClasses(classes: readonly string[]): string {
   return `${named.slice(0, -1).join(", ")}, and ${named.at(-1) ?? "another class"}`;
 }
 
-/** Retryable: a publishable preview says the change narrows the contract. */
+/**
+ * Retryable: a publishable preview says the change narrows the contract.
+ *
+ * The counts are the point. A confirmation that asks "are you sure?" without
+ * saying what yes costs is a speed bump, and the two numbers worth saying are
+ * both already measured: how many classes narrow, and how many annotations are
+ * at risk. The second is always zero here — a preview carrying blockers is
+ * refused outright and never reaches this dialog — and a measured zero is the
+ * reason the publish is offered at all, so it is stated rather than implied.
+ *
+ * It says nothing about what becomes of annotations *after* the publish. An
+ * open batch pinned to the outgoing version can still write the removed class,
+ * and whether that is tolerated or forbidden is not something this dialog is
+ * entitled to answer.
+ *
+ * A shape removed from a class and the class itself removed are indistinguishable
+ * here: the wire's change record carries the class name but not the geometry, so
+ * the copy counts classes, which is true of both, rather than guessing which
+ * happened.
+ */
 function DestructiveDialog({
   preview,
   pending,
@@ -1268,11 +1287,14 @@ function DestructiveDialog({
       <DialogContent data-testid="destructive-dialog">
         <DialogTitle>This narrows the schema</DialogTitle>
         <DialogDescription>
-          This change narrows the schema for {describeDestructiveClasses(destructiveClasses)}.
+          <span className="tabular-nums">{formatCount(destructiveClasses.length)}</span>{" "}
+          {destructiveClasses.length === 1 ? "class narrows" : "classes narrow"}:{" "}
+          {describeDestructiveClasses(destructiveClasses)}.
         </DialogDescription>
         <DialogDescription>
-          Existing annotations are not touched. Saving anyway publishes the new version and leaves
-          earlier ones exactly as they are — a version is immutable.
+          No annotations use what this removes — that is why it can be published at all. Publishing
+          creates a new version; the versions before it keep everything they already declared,
+          because a version is immutable.
         </DialogDescription>
         <DialogFooter>
           <Button variant="secondary" onClick={onCancel}>
diff --git a/frontend/ui-core/src/screens/screens.test.tsx b/frontend/ui-core/src/screens/screens.test.tsx
index 9c627a9e..90b8b3c3 100644
--- a/frontend/ui-core/src/screens/screens.test.tsx
+++ b/frontend/ui-core/src/screens/screens.test.tsx
@@ -522,6 +522,14 @@ describe("the schema editor", () => {
     const dialog = await screen.findByTestId("destructive-dialog");
     expect(dialog.textContent).toContain("lane");
     expect(dialog.textContent).not.toContain("internal wording must not appear");
+    // The blast radius, counted: DESIGN.md requires a confirmation to name what
+    // it costs. `blockers` is empty on every preview that reaches this dialog,
+    // so the zero is measured rather than assumed.
+    expect(dialog.textContent).toContain("1 class narrows");
+    expect(dialog.textContent).toContain("No annotations use what this removes");
+    // The removed promise. It described what happens to annotations *after* the
+    // publish, which the kernel has not decided, so the dialog stops claiming it.
+    expect(dialog.textContent).not.toContain("Existing annotations are not touched");
     expect(
       sent.some(
         (request) =>
@@ -550,6 +558,41 @@ describe("the schema editor", () => {
     expect(new URL(publishRequest?.url ?? "").searchParams.get("allow_destructive")).toBe("true");
   });
 
+  it("counts every narrowing class in the confirmation", async () => {
+    projectWithSchema();
+    handlers.push((request) => {
+      if (request.method !== "POST" || !new URL(request.url).pathname.endsWith("/schema/preview")) {
+        return undefined;
+      }
+      return {
+        status: 200,
+        body: {
+          is_refused: false,
+          blockers: [],
+          diff: {
+            is_destructive: true,
+            destructive_classes: ["lane", "sign"],
+            changes: [
+              { kind: "destructive", label_class: "lane", attribute: null, detail: "class 'lane' removed" },
+              { kind: "destructive", label_class: "sign", attribute: null, detail: "class 'sign' removed" },
+            ],
+          },
+        },
+      };
+    });
+
+    render(mount(<ProjectScreen projectId={PROJECT} tab="schema" />));
+    await screen.findByTestId("schema-editor");
+    await removeClass(1);
+    await userEvent.click(screen.getByTestId("save-schema"));
+
+    const dialog = await screen.findByTestId("destructive-dialog");
+    expect(dialog.textContent).toContain("2 classes narrow");
+    expect(dialog.textContent).toContain("lane");
+    expect(dialog.textContent).toContain("sign");
+    expect(dialog.textContent).toContain("No annotations use what this removes");
+  });
+
   it("prevents repeated confirmation while its second preview is pending", async () => {
     projectWithSchema();
     let previews = 0;

From 51f06a4b87668bf912b06b0febed0944f98ade1e Mon Sep 17 00:00:00 2001
From: Jesus Armando Anaya <armando@robomous.ai>
Date: Tue, 18 Aug 2026 17:01:22 -0700
Subject: [PATCH 2/4] docs: correct schema editor preview prose to match
 shipped behavior

The SchemaEditor docstring and docs/ui.md both asserted the editor does
not call schema/preview and that publishing's 409 is the sole way a
narrowing refusal surfaces. The editor calls preview twice, before a
class leaves the draft and before a publish, so both surfaces now
describe that flow and how it relates to the publish's own 409.
---
 docs/ui.md                                    | 27 ++++++++++++-------
 frontend/ui-core/src/screens/SchemaEditor.tsx | 19 +++++++------
 2 files changed, 29 insertions(+), 17 deletions(-)

diff --git a/docs/ui.md b/docs/ui.md
index 38cba0c8..a83e78eb 100644
--- a/docs/ui.md
+++ b/docs/ui.md
@@ -221,8 +221,10 @@ one guards emitting an **incomplete copy of something that stays intact**. The
 kernel never catches the three together and neither does the UI: three dialogs,
 three questions.
 
-There is no pre-export validation route, so consent is the schema editor's shape:
-attempt → read `LOSSY_EXPORT_NOT_CONSENTED` off the 409 → ask → retry with the flag.
+There is no pre-export validation route, so consent here is attempt-shaped: attempt → read
+`LOSSY_EXPORT_NOT_CONSENTED` off the 409 → ask → retry with the flag. The schema editor no
+longer has this shape - it previews first - and the difference is exactly the routed preview
+that export lacks.
 `FormatOut.lossy` makes the question predictable in advance, because lossiness is
 declared by the **format** - a bbox-only format loses a polygon whether or not
 today's dataset holds one.
@@ -844,13 +846,20 @@ which is the lost update `STALE_WRITE` exists to prevent, and "Close" would leav
 editor showing a draft the server no longer recognises. Reloading is the only remedy that
 does not either lose work or leave the screen lying.
 
-`SchemaService.preview` **is** routed, at `POST .../schema/preview` - it answers both gates
-the publish itself would, `is_destructive` and `is_refused`, without writing anything. The
-editor does not call it: nothing is locked between a preview and a publish, so somebody
-could label a class in the gap and turn a preview that looked safe into a refusal, and a
-call the editor never makes cannot disagree with the publish that follows it. The publish's
-own 409 is what actually decides, and making that refusal legible - not pre-empting it - is
-the editor's whole job here, exactly as `SchemaEditor`'s own docstring states it.
+`SchemaService.preview` is routed at `POST .../schema/preview` - it answers both gates the
+publish itself would, `is_destructive` and `is_refused`, without writing anything - and
+**the editor calls it**, once before a class leaves the draft and once before a publish.
+Both narrowing questions are therefore asked before anything is sent. A class that already
+carries labels never reaches a publish request at all: it gets one terminal dialog naming
+the annotations and assets that block it, counted, and no button that starts a save the
+dialog knows will be refused. A class that carries none gets one confirmation, which names
+how many classes narrow and states that no annotations are at risk.
+
+That does not demote the 409. Nothing is locked between a preview and the publish, so
+somebody can label a class in the gap and turn a preview that looked safe into a refusal -
+which is why the publish's own refusal stays authoritative, and why it renders through the
+same blocker view the preview feeds rather than through a second presentation that could
+drift from it. The preview removes a doomed round trip; it does not decide.
 
 `compare` **is** routed since #231, and it answers the neighbouring question - what
 two *published* versions did to each other. The version navigator uses it, and never
diff --git a/frontend/ui-core/src/screens/SchemaEditor.tsx b/frontend/ui-core/src/screens/SchemaEditor.tsx
index 6cb89983..4a435861 100644
--- a/frontend/ui-core/src/screens/SchemaEditor.tsx
+++ b/frontend/ui-core/src/screens/SchemaEditor.tsx
@@ -59,16 +59,19 @@
  * one is not — so a TypeScript copy would drift, and the drift would read as a
  * screen calling a change safe that the API then refuses.
  *
- * ## A preview exists, and it is advisory rather than authoritative
+ * ## The preview leads, and the publish still decides
  *
  * `compare` answers what two *published* versions did to each other. `POST
- * .../schema/preview` answers the harder question — what publishing *this*
- * draft would do — and is routed: `SchemaService.preview` is not the missing
- * method a comment here used to claim. Routing it does not remove the need for
- * the refusal surface below, though: a preview is advisory because nothing is
- * locked between it and a publish, so the two can disagree by the time Save is
- * actually pressed. The publish's own 409 stays the authoritative answer, and
- * making that refusal legible — not pre-empting it — is the editor's actual job.
+ * .../schema/preview` answers the harder question — what publishing *this* draft
+ * would do — and the editor calls it twice: before a class leaves the draft, and
+ * before a publish. That is what removes the round trip that was doomed before it
+ * was sent, and it is why a class already carrying labels is refused in one
+ * terminal dialog rather than after two confirmations that contradict it.
+ *
+ * It does not make the preview authoritative. Nothing is locked between a preview
+ * and the publish, so somebody can label a class in the gap; the publish's own 409
+ * is still the answer, and it renders through the same blocker view the preview
+ * feeds, so the two paths cannot drift apart.
  *
  * **Two 409s, and only one is retryable.** This is the exact case `docs/api.md`
  * exists for:

From 2070f9dd67b35f1eeab9d5221948b7dd1610cf61 Mon Sep 17 00:00:00 2001
From: Jesus Armando Anaya <armando@robomous.ai>
Date: Tue, 18 Aug 2026 17:05:54 -0700
Subject: [PATCH 3/4] docs: correct fourth stale reference to the schema
 editor's old export shape

DatasetScreen.tsx's file docstring still described the schema editor as
attempt-shaped for export consent, the same claim already corrected in
docs/ui.md and SchemaEditor.tsx. The schema editor previews first, so
DatasetScreen's docstring now says the same thing they do.
---
 frontend/ui-core/src/screens/DatasetScreen.tsx | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/frontend/ui-core/src/screens/DatasetScreen.tsx b/frontend/ui-core/src/screens/DatasetScreen.tsx
index 33c2dd57..94c70aff 100644
--- a/frontend/ui-core/src/screens/DatasetScreen.tsx
+++ b/frontend/ui-core/src/screens/DatasetScreen.tsx
@@ -18,8 +18,10 @@
  * and the UI keeps them apart too: the delete dialog, the schema dialog and this
  * one are three.
  *
- * There is no pre-export validation route, so consent is the schema editor's shape:
+ * There is no pre-export validation route, so consent here is attempt-shaped:
  * attempt, read `LOSSY_EXPORT_NOT_CONSENTED` off the 409, ask, retry with the flag.
+ * The schema editor no longer has this shape — it previews first — and the
+ * difference is exactly the routed preview that export lacks.
  * `FormatOut.lossy` is what makes the question predictable — it is declared by the
  * *format*, because a bbox-only format loses a polygon whether or not today's
  * dataset holds one.

From d09b575827a999be36b09e7154bfaa807410c951 Mon Sep 17 00:00:00 2001
From: Jesus Armando Anaya <armando@robomous.ai>
Date: Tue, 18 Aug 2026 17:16:13 -0700
Subject: [PATCH 4/4] fix(schema): correct destructive-dialog copy for the
 add-required-attribute case

The dialog said 'no annotations use what this removes,' which is false
when the destructive change is an added required attribute rather than
a removal. Replace with kind-agnostic copy that states the measured
fact for all four destructive shapes, and update docs/ui.md and a
DatasetScreen docstring that referenced the old phrasing or leaned on
past-tense/forward-looking language.
---
 docs/ui.md                                     | 8 ++++----
 frontend/ui-core/src/screens/DatasetScreen.tsx | 2 +-
 frontend/ui-core/src/screens/SchemaEditor.tsx  | 5 ++---
 frontend/ui-core/src/screens/screens.test.tsx  | 4 ++--
 4 files changed, 9 insertions(+), 10 deletions(-)

diff --git a/docs/ui.md b/docs/ui.md
index a83e78eb..86ae7041 100644
--- a/docs/ui.md
+++ b/docs/ui.md
@@ -222,8 +222,8 @@ kernel never catches the three together and neither does the UI: three dialogs,
 three questions.
 
 There is no pre-export validation route, so consent here is attempt-shaped: attempt → read
-`LOSSY_EXPORT_NOT_CONSENTED` off the 409 → ask → retry with the flag. The schema editor no
-longer has this shape - it previews first - and the difference is exactly the routed preview
+`LOSSY_EXPORT_NOT_CONSENTED` off the 409 → ask → retry with the flag. The schema editor does
+not have this shape - it previews first - and the difference is exactly the routed preview
 that export lacks.
 `FormatOut.lossy` makes the question predictable in advance, because lossiness is
 declared by the **format** - a bbox-only format loses a polygon whether or not
@@ -849,11 +849,11 @@ does not either lose work or leave the screen lying.
 `SchemaService.preview` is routed at `POST .../schema/preview` - it answers both gates the
 publish itself would, `is_destructive` and `is_refused`, without writing anything - and
 **the editor calls it**, once before a class leaves the draft and once before a publish.
-Both narrowing questions are therefore asked before anything is sent. A class that already
+Both are therefore answered before any publish is sent. A class that already
 carries labels never reaches a publish request at all: it gets one terminal dialog naming
 the annotations and assets that block it, counted, and no button that starts a save the
 dialog knows will be refused. A class that carries none gets one confirmation, which names
-how many classes narrow and states that no annotations are at risk.
+how many classes narrow and states that nothing already labeled is invalidated.
 
 That does not demote the 409. Nothing is locked between a preview and the publish, so
 somebody can label a class in the gap and turn a preview that looked safe into a refusal -
diff --git a/frontend/ui-core/src/screens/DatasetScreen.tsx b/frontend/ui-core/src/screens/DatasetScreen.tsx
index 94c70aff..7590a0e7 100644
--- a/frontend/ui-core/src/screens/DatasetScreen.tsx
+++ b/frontend/ui-core/src/screens/DatasetScreen.tsx
@@ -20,7 +20,7 @@
  *
  * There is no pre-export validation route, so consent here is attempt-shaped:
  * attempt, read `LOSSY_EXPORT_NOT_CONSENTED` off the 409, ask, retry with the flag.
- * The schema editor no longer has this shape — it previews first — and the
+ * The schema editor does not have this shape — it previews first — and the
  * difference is exactly the routed preview that export lacks.
  * `FormatOut.lossy` is what makes the question predictable — it is declared by the
  * *format*, because a bbox-only format loses a polygon whether or not today's
diff --git a/frontend/ui-core/src/screens/SchemaEditor.tsx b/frontend/ui-core/src/screens/SchemaEditor.tsx
index 4a435861..85df2fa0 100644
--- a/frontend/ui-core/src/screens/SchemaEditor.tsx
+++ b/frontend/ui-core/src/screens/SchemaEditor.tsx
@@ -1295,9 +1295,8 @@ function DestructiveDialog({
           {describeDestructiveClasses(destructiveClasses)}.
         </DialogDescription>
         <DialogDescription>
-          No annotations use what this removes — that is why it can be published at all. Publishing
-          creates a new version; the versions before it keep everything they already declared,
-          because a version is immutable.
+          No existing annotation becomes invalid — that is why this can be published at all.
+          Publishing adds a new version; earlier versions keep what they declared.
         </DialogDescription>
         <DialogFooter>
           <Button variant="secondary" onClick={onCancel}>
diff --git a/frontend/ui-core/src/screens/screens.test.tsx b/frontend/ui-core/src/screens/screens.test.tsx
index 90b8b3c3..2f98915a 100644
--- a/frontend/ui-core/src/screens/screens.test.tsx
+++ b/frontend/ui-core/src/screens/screens.test.tsx
@@ -526,7 +526,7 @@ describe("the schema editor", () => {
     // it costs. `blockers` is empty on every preview that reaches this dialog,
     // so the zero is measured rather than assumed.
     expect(dialog.textContent).toContain("1 class narrows");
-    expect(dialog.textContent).toContain("No annotations use what this removes");
+    expect(dialog.textContent).toContain("No existing annotation becomes invalid");
     // The removed promise. It described what happens to annotations *after* the
     // publish, which the kernel has not decided, so the dialog stops claiming it.
     expect(dialog.textContent).not.toContain("Existing annotations are not touched");
@@ -590,7 +590,7 @@ describe("the schema editor", () => {
     expect(dialog.textContent).toContain("2 classes narrow");
     expect(dialog.textContent).toContain("lane");
     expect(dialog.textContent).toContain("sign");
-    expect(dialog.textContent).toContain("No annotations use what this removes");
+    expect(dialog.textContent).toContain("No existing annotation becomes invalid");
   });
 
   it("prevents repeated confirmation while its second preview is pending", async () => {