From a2897861992602f2b6db2cd8b0d12bff80fdf06d Mon Sep 17 00:00:00 2001
From: Olivier 'reivilibre <oliverw@matrix.org>
Date: Wed, 13 May 2026 17:54:48 +0100
Subject: [PATCH] Describe NonNegativeStrictInt reason for preference

---
 synapse/types/__init__.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/synapse/types/__init__.py b/synapse/types/__init__.py
index 62084ef119..223a007a3b 100644
--- a/synapse/types/__init__.py
+++ b/synapse/types/__init__.py
@@ -208,7 +208,10 @@ For a Sentinel for internal (non-API-facing) use, instead consider
 NonNegativeStrictInt = Annotated[StrictInt, annotated_types.Ge(0)]
 """A strict integer that must be greater than or equal to zero.
 
-Should be preferred in place of Pydantic's own (lax) NonNegativeInt.
+Should be preferred in place of Pydantic's own (lax) NonNegativeInt,
+which will coerce strings to integers in a way that does not agree with
+the Matrix specification (and would risk backing us into a backward compatibility
+hole where we had to support input forms we didn't intend).
 """