From 0584ac8bc5042ee7b258d33d05a10e4ff4e2109c Mon Sep 17 00:00:00 2001
From: Ray <mailtangyu@gmail.com>
Date: Thu, 23 Jul 2026 23:59:55 +0800
Subject: [PATCH] fix: track pageindex/_validation.py
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

360ab66 and 0a78f1d moved collection-name validation into this new module
and import it from cloud.py/local.py/sqlite.py, but the file itself was
never added — a fresh checkout of dev fails at import.
---
 pageindex/_validation.py | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100644 pageindex/_validation.py

diff --git a/pageindex/_validation.py b/pageindex/_validation.py
new file mode 100644
index 0000000..17890a3
--- /dev/null
+++ b/pageindex/_validation.py
@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from .errors import PageIndexError
+
+
+MAX_COLLECTION_NAME_LENGTH = 255
+
+
+def validate_collection_name(name: str) -> None:
+    """Validate the collection-name contract shared by local and cloud modes.
+
+    Collection names are logical identifiers, not filesystem paths.  Keep this
+    in sync with the cloud folder API, which accepts any non-empty Unicode
+    string up to 255 characters.
+    """
+    invalid = (
+        not isinstance(name, str)
+        or not name
+        or len(name) > MAX_COLLECTION_NAME_LENGTH
+    )
+    if not invalid:
+        try:
+            name.encode("utf-8")
+        except UnicodeEncodeError:
+            # JSON/database boundaries require Unicode scalar values; lone UTF-16
+            # surrogates are Python strings but cannot be encoded as valid UTF-8.
+            invalid = True
+    if invalid:
+        raise PageIndexError(
+            f"Invalid collection name: {name!r}. "
+            f"Must be a non-empty string of valid Unicode with at most "
+            f"{MAX_COLLECTION_NAME_LENGTH} characters."
+        )