altcodepro-polydb-python 2.3.22__py3-none-any.whl → 2.3.24__py3-none-any.whl

{altcodepro_polydb_python-2.3.22.dist-info → altcodepro_polydb_python-2.3.24.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: altcodepro-polydb-python
-Version: 2.3.22
+Version: 2.3.24
 Summary: Production-ready multi-cloud database abstraction layer with connection pooling, retry logic, and thread safety
 Author: AltCodePro
 Project-URL: Homepage, https://github.com/altcodepro/polydb-python

{altcodepro_polydb_python-2.3.22.dist-info → altcodepro_polydb_python-2.3.24.dist-info}/RECORD

@@ -1,15 +1,15 @@
-altcodepro_polydb_python-2.3.22.dist-info/licenses/LICENSE,sha256=9X8GLocsBwy-5aR5JGOt2SAMDDPs9Qv-YnqmHBHOXrw,1067
+altcodepro_polydb_python-2.3.24.dist-info/licenses/LICENSE,sha256=9X8GLocsBwy-5aR5JGOt2SAMDDPs9Qv-YnqmHBHOXrw,1067
 polydb/PolyDB.py,sha256=MG7-nV59zDvrUQwXNEgV4eetHCeW9TYY9DQqtxu_r7k,23543
 polydb/__init__.py,sha256=zx6yhNfaMDdshdDdcj4F8Vp9phCBA71mRFVi68IUELM,1459
 polydb/advanced_query.py,sha256=cxMB-EB-qT3bWXJlhmjnMCUtrzogORWyoEfS50Dy7go,4280
 polydb/batch.py,sha256=_DjWZa1ZXYSk6MLKqFe0eT7SYVRZtYNqZb9bI8Y2sao,4566
 polydb/cache.py,sha256=JBXF1XEK-fY80ar8SDE893Z1Z116YtXAEG0PaJ0Nkcw,7658
 polydb/cloudDatabaseFactory.py,sha256=Gp6L__YtgrkGahD8B7ItzXMHCoj2ZUGDjXLS9w0TujY,17780
-polydb/databaseFactory.py,sha256=u20sy8bA09A0jTO2vLxGznssdcaxChQf21FBpooL2oA,40265
+polydb/databaseFactory.py,sha256=uBzX7K-k_aFHLQyFemy3XIe3lsOjAvjRFfaC6phITlA,41470
 polydb/decorators.py,sha256=L_WP2uXP_k8Ac49SUm-mthbM4jWI-XYfHXEyKzumOww,43062
 polydb/errors.py,sha256=jF_55fbfg6b6mBc116dzU_uBG9qiIKbr5jvmDuJx-Jw,1573
 polydb/json_safe.py,sha256=R5PrqAGirqjYKPyy-8KH-lSXjLH0FPr2TSGozy4eheU,149
-polydb/models.py,sha256=9uu_BaJ95194n-vnd0Rx9KLc6aPS-mxn10P4W5grUcI,8155
+polydb/models.py,sha256=GBdyGNzLu7skKNMp2cZySsM_peEHB3QhhbsnKAS15D8,8942
 polydb/monitoring.py,sha256=UMm3ybyRJjAQi-prXXMLl9zuHhnhMnYBzMD3XWK66y8,9571
 polydb/multitenancy.py,sha256=9kyY98RpKg8xDy9ejB_MyV_YzF7eZd4uxashw5S8vlg,6408
 polydb/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -24,7 +24,7 @@ polydb/validation.py,sha256=a1o1d02k3c6PWQwkBbw_0nEmIgrdB5RR8OcpNQMn4cA,4810
 polydb/adapters/AzureBlobStorageAdapter.py,sha256=4vD55Z8DBTzBK66jIJbo5bNMY-AQ61MlP0-P2Fv_JgQ,7083
 polydb/adapters/AzureFileStorageAdapter.py,sha256=VZNprqlBXCuWUgtqClNT-NrQmRf-XFYEiRA2BLbf-Sc,7046
 polydb/adapters/AzureQueueAdapter.py,sha256=5PrKAX4OQxUD5nReZKrInF_mjQVdFcj2aYd0Xp-HjjQ,5254
-polydb/adapters/AzureTableStorageAdapter.py,sha256=bC8_URjM60Vyncf0WXzg2s1WbqdmbNj2YJJe1XUzQF4,29358
+polydb/adapters/AzureTableStorageAdapter.py,sha256=Gu7Xmi1Q79sUHNAEj6YMohF-Oy1Ar35d7OT1qUHKGOE,26198
 polydb/adapters/BlockchainBlobAdapter.py,sha256=D01Yua9mkKfaQrxKYApblIyI6DSP0dtNAh4Tav51HJ4,3299
 polydb/adapters/BlockchainFileAdapter.py,sha256=G749xOVpG20HuKS8zCgi6PMjoJNu-YXK7zitygjLdzM,8335
 polydb/adapters/BlockchainKVAdapter.py,sha256=UFYHyTgvdW-sZUBqyHEG3Cdx6wSTiF2QowEVWL3XPTg,4564
@@ -36,7 +36,7 @@ polydb/adapters/GCPFilestoreAdapter.py,sha256=yjFQQwsWYWc8mo8XwMViVTWb5_D--xAyTM
 polydb/adapters/GCPPubSubAdapter.py,sha256=7XNots2VA0ReEDku-rjg-OTYmftIpx5UgnXYDdXNkOo,8692
 polydb/adapters/GCPStorageAdapter.py,sha256=9yS1Jhcn5_rCRdZ5uOqcRW6Ba-UNb6VOYpwENP-C6Qk,7133
 polydb/adapters/MongoDBAdapter.py,sha256=vX3SAHDLbTnHABGesES9N-gYSQqPqdqFLJgd7pYWZzw,7471
-polydb/adapters/PostgreSQLAdapter.py,sha256=6JPr-Szs3y98TjU9m2hEV4Kpa_-phNY3GcXAufgdWtc,34888
+polydb/adapters/PostgreSQLAdapter.py,sha256=lUe65kpJkTu6R1Tc1zgl63Fa1PI44UVbWRTKRUSSGak,36579
 polydb/adapters/S3Adapter.py,sha256=5R0zHAL2SkGFjp1L3bp-IU468bXYdSf6nKx974MN104,7586
 polydb/adapters/S3CompatibleAdapter.py,sha256=jpafqbAjA8-irdXBrfXa1QJySIzrcUQ6UrFt5h5FAEc,7006
 polydb/adapters/SQSAdapter.py,sha256=1vfbNoqIDy-b8t2xcxy91SoxSYBPFDfUh7yCQWxdS84,5778
@@ -50,7 +50,7 @@ polydb/audit/__init__.py,sha256=Z7-y5djq3glQ2Yun6nj-13Efpj3oGz9Qc0veS2g06Y4,245
 polydb/audit/context.py,sha256=-A1FMtmr-2snVAHpTrVT80u-D_MCaqX6AoV4Ku2bz_o,1955
 polydb/audit/manager.py,sha256=KzaaOf5bDfr4M-CkCAZBG_U_4xIBCKDLRAf3hsm-DAk,1236
 polydb/audit/models.py,sha256=NapdH5dXU9GMoP9ccbDFaeMWvWbwoh2B5N7Nd3Ci6Cg,3745
-polydb/base/NoSQLKVAdapter.py,sha256=oa3MT7Z6E5zsF6mDeqjaMfefScKXJgne79LkB7dN8ZA,11557
+polydb/base/NoSQLKVAdapter.py,sha256=aYEnXG3PZVQbpneSgfToJAhJAsRHUxwazIvjRmT-Qak,13588
 polydb/base/ObjectStorageAdapter.py,sha256=VeJ3qXET6H0xd3lJpE8-WSsKs8EyK9S0-9VNR0EJzME,2288
 polydb/base/QueueAdapter.py,sha256=jFgyG-SUK4nhRNxm2NbzUbwnA9b_5iAC-ikLSUpXRwk,799
 polydb/base/SharedFilesAdapter.py,sha256=kXbJmtn_cwEyAZ-1AvFrmesCLSwu43ycTV3S4BmwrO4,853
@@ -60,7 +60,7 @@ polydb/observability/logging.py,sha256=gv1SshNjaSkmR98Uv7Qbwq3gkeQUzVCA4ichqHKL6
 polydb/services/__init__.py,sha256=nMolMXzmhejRSm7f42kU9fCHF0GIpqpejN2kywuBsUQ,241
 polydb/services/compliance_service.py,sha256=-0ncX7PrXy4-NuyWXIv65cLUsqz0jXzb3LtsD8rlrXE,4983
 polydb/services/security_service.py,sha256=q7GzK6sbMnBBsc4fuL4oXTd-ui2b-MYQyrWTBvdVNSk,5062
-altcodepro_polydb_python-2.3.22.dist-info/METADATA,sha256=cy4CiBLSydIYi2-bkyCUBIZP0jKvQNVg9OiX1PJ7U9Q,12359
-altcodepro_polydb_python-2.3.22.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-altcodepro_polydb_python-2.3.22.dist-info/top_level.txt,sha256=WgLFWJoYjUhwvyPxJFl6jYLrVFuBJDX3OABf4ocwk_E,7
-altcodepro_polydb_python-2.3.22.dist-info/RECORD,,
+altcodepro_polydb_python-2.3.24.dist-info/METADATA,sha256=oChx1wdfnxF14DH2I2WvFTJWrceIEvoJ-88gzaCXlvY,12359
+altcodepro_polydb_python-2.3.24.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+altcodepro_polydb_python-2.3.24.dist-info/top_level.txt,sha256=WgLFWJoYjUhwvyPxJFl6jYLrVFuBJDX3OABf4ocwk_E,7
+altcodepro_polydb_python-2.3.24.dist-info/RECORD,,

polydb/adapters/AzureTableStorageAdapter.py

@@ -31,9 +31,6 @@ _BASE64_RE = re.compile(r"^[A-Za-z0-9+/]*={0,2}$")
 # ensures model isolation across the same table
 _MODEL_FIELD = "__polydb_model__"
 
-# ─── NEW: HTTP transport tuning ──────────────────────────────────────────────
-# Default Azure SDK has no read timeout. A sync call from an async event loop
-# can park forever. These are overridable via env so ops can tune per env.
 _CONNECT_TIMEOUT = float(os.getenv("AZURE_TABLE_CONNECT_TIMEOUT", "10"))
 _READ_TIMEOUT = float(os.getenv("AZURE_TABLE_READ_TIMEOUT", "30"))
 _RETRY_TOTAL = int(os.getenv("AZURE_TABLE_RETRY_TOTAL", "3"))
@@ -50,15 +47,6 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
     - Blob overflow for entities > 1MB
     - Model isolation using __polydb_model__
     - Always returns id (derived from RowKey if missing)
-
-    Performance / safety guarantees:
-    - One TableServiceClient per adapter instance.
-    - One TableClient cached per table for the adapter's lifetime.
-    - create_table_if_not_exists runs ONCE per table per adapter lifetime.
-    - Explicit connect/read timeouts on the HTTP transport so a slow or
-      mis-configured endpoint fails fast instead of hanging the caller.
-    - No mutation of instance state inside read/write paths (was the
-      previous `self._table_client = ...` race hazard).
     """
 
     AZURE_TABLE_MAX_SIZE = 60 * 1024  # 1MB
@@ -84,12 +72,7 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
         self._blob_service = None
         self._client_lock = threading.Lock()
 
-        # ─── NEW: caches ────────────────────────────────────────────────────
-        # _ensured_tables: table names for which create_table_if_not_exists
-        # has already succeeded on this adapter instance.
-        # _table_clients_cache: TableClient handles by table name.
-        # _cache_lock: protects both caches from concurrent get/put.
-        self._ensured_tables: set[str] = set()
+        self._ensured_tables: set = set()
         self._table_clients_cache: Dict[str, Any] = {}
         self._cache_lock = threading.Lock()
 
@@ -102,11 +85,6 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
 
             with self._client_lock:
                 if not self._client:
-                    # ─── CHANGED: explicit transport timeouts + retry budget ──
-                    # connection_timeout / read_timeout are honoured by the
-                    # azure-core RequestsTransport. retry_total caps the
-                    # SDK's built-in retry policy so a hard failure surfaces
-                    # in seconds, not minutes.
                     self._client = TableServiceClient.from_connection_string(
                         self.connection_string,
                         connection_timeout=_CONNECT_TIMEOUT,
@@ -155,7 +133,6 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
         if v is None:
             return None
 
-        # Treat empty containers as absent — let the row omit the property.
         if isinstance(v, (list, tuple, dict)) and len(v) == 0:
             return None
 
@@ -187,14 +164,14 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
     def _decode_value(self, v: Any) -> Any:
         if isinstance(v, str):
             if v.startswith(_JSON_PREFIX):
-                payload = v[len(_JSON_PREFIX) :]
+                payload = v[len(_JSON_PREFIX):]
                 try:
                     return json.loads(payload)
                 except Exception:
                     return v
 
             if v.startswith(_BYTES_PREFIX):
-                payload = v[len(_BYTES_PREFIX) :].strip()
+                payload = v[len(_BYTES_PREFIX):].strip()
                 if (len(payload) % 4) == 1:
                     return v
                 if not _BASE64_RE.match(payload):
@@ -248,11 +225,6 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
     # Entity pack/unpack
     # -----------------------------
     def _pack_entity(self, model: type, pk: str, rk: str, data: JsonDict) -> JsonDict:
-        """Pack data into Azure Table Storage entity format.
-
-        This version is much simpler, more readable, and fixes the fragile
-        revmap/skey logic that was likely causing normal fields to disappear.
-        """
         entity: JsonDict = {
             "PartitionKey": pk,
             "RowKey": rk,
@@ -263,27 +235,21 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
         for orig_key, orig_val in (data or {}).items():
             orig_key_str = str(orig_key)
 
-            # Skip Azure-reserved or special keys
             if orig_key_str in self._RESERVED or orig_key_str in ("PartitionKey", "RowKey"):
                 continue
 
-            # Sanitize property name so it is valid for Azure Table Storage
             skey = self._sanitize_prop_name(orig_key)
 
-            # Prevent key collisions (extremely rare but safe)
             base = skey
             counter = 1
             while skey in entity:
                 skey = f"{base}_{counter}"
                 counter += 1
 
-            # Remember the original key name so _unpack_entity can restore it
             keymap[skey] = orig_key_str
 
-            # Encode the value (must return something Azure Table accepts)
             entity[skey] = self._encode_value(orig_val)
 
-        # Store keymap only if we actually have fields (internal use)
         if keymap:
             entity["__keymap__"] = json.dumps(keymap, default=json_safe)
 
@@ -319,7 +285,6 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
             if k in ("PartitionKey", "RowKey"):
                 continue
 
-            # keep internal metadata fields too
             if k.startswith("_") or k in (_MODEL_FIELD,):
                 out[k] = v
                 continue
@@ -327,14 +292,12 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
             orig_key = keymap.get(k, k)
             out[orig_key] = self._decode_value(v)
 
-        # ✅ guarantee id for tests & ergonomics
         if "id" not in out and rk is not None:
             out["id"] = rk
 
         return out
 
     def _sanitize_blob_part(self, value: str) -> str:
-        # Blob-safe: lowercase, alphanumeric + dash only
         s = str(value).lower()
         s = re.sub(r"[^a-z0-9\-]", "-", s)
         s = re.sub(r"-+", "-", s)
@@ -346,8 +309,6 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
     def _blob_key(self, pk: str, rk: str, checksum: str) -> str:
         safe_pk = self._sanitize_blob_part(pk)
         safe_rk = self._sanitize_blob_part(rk)
-
-        # Flat structure (avoid deep paths)
         return f"{safe_pk}-{safe_rk}-{checksum}.json"
 
     def _blob_upload(self, blob_key: str, data_bytes: bytes):
@@ -375,18 +336,14 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
     # Required NoSQLKVAdapter hooks
     # -----------------------------
     def _sanitize_table_name(self, name: str) -> str:
-        """Convert collection_name to valid Azure Table name (alphanumeric only)."""
         if not name:
             return "defaulttable"
 
-        # Remove all invalid characters, keep only letters and numbers
         sanitized = re.sub(r"[^a-zA-Z0-9]", "", name)
 
-        # Must start with a letter
         if sanitized and sanitized[0].isdigit():
             sanitized = "t" + sanitized
 
-        # Must be 3-63 characters
         if len(sanitized) < 3:
             sanitized = sanitized + "table"
         if len(sanitized) > 63:
@@ -395,10 +352,6 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
         return sanitized.lower()
 
     def _get_table_name(self, model: type) -> str:
-        """
-        Extract collection_name from UDL model definition.
-        """
-        # Primary source: UDL definition
         definition = getattr(model, "__udl_definition__", None)
         if definition:
             metadata = getattr(definition, "x_metadata", {}) or {}
@@ -406,41 +359,22 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
             if collection_name:
                 return self._sanitize_table_name(collection_name)
 
-        # Fallback: __polydb__ metadata
         polydb_meta = getattr(model, "__polydb__", None)
         if isinstance(polydb_meta, dict):
             collection = polydb_meta.get("collection") or polydb_meta.get("collection_name")
             if collection:
                 return self._sanitize_table_name(str(collection))
 
-        # Last resort
         return os.getenv("AZURE_TABLE_NAME", "defaulttable") or "defaulttable"
 
     def _get_table_client(self, model: type):
-        """
-        Return a TableClient for the model, ensuring the table exists.
-
-        ─── CHANGED ────────────────────────────────────────────────────────
-        Both the table existence check AND the TableClient handle are now
-        cached per adapter instance. The previous version ran
-        create_table_if_not_exists on every read/write/query/delete — a
-        hot-loop seed of 100 records produced ~300 unnecessary network
-        round-trips. Now:
-
-          - First call for a table:  1 HTTP call (create_table_if_not_exists)
-                                     + 1 cheap local TableClient construction.
-          - All subsequent calls:    O(1) dict lookup, no network.
-        """
         table_name = self._get_table_name(model)
 
-        # Fast path: already ensured + client cached.
         cached = self._table_clients_cache.get(table_name)
         if cached is not None and table_name in self._ensured_tables:
             return cached
 
         with self._cache_lock:
-            # Re-check inside the lock to avoid duplicate ensures under
-            # concurrent first-touch.
             cached = self._table_clients_cache.get(table_name)
             already_ensured = table_name in self._ensured_tables
 
@@ -449,12 +383,9 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
                     self._client.create_table_if_not_exists(table_name)
                     logger.info(f"✅ Azure Table ensured/created: {table_name}")
                 except Exception as e:
-                    # TableAlreadyExists is normal and safe to ignore
                     msg = str(e)
                     if "TableAlreadyExists" not in msg and "already exists" not in msg.lower():
                         logger.warning(f"Could not create table {table_name}: {e}")
-                # Mark as ensured regardless — either it exists now or we
-                # logged the failure; we won't retry on every op.
                 self._ensured_tables.add(table_name)
 
             if cached is None:
@@ -464,19 +395,13 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
             return cached
 
     def _restore_overflow_properties(self, entity_dict: JsonDict) -> JsonDict:
-        """Detect and restore any large properties stored in Blob Storage.
-
-        Called by both _get_raw and _query_raw.
-        """
         restored = {}
 
         for k, v in entity_dict.items():
-            # Internal fields (starting with _) are kept as-is
             if k.startswith("_"):
                 restored[k] = v
                 continue
 
-            # Is this an overflow metadata JSON string?
             if isinstance(v, str) and v.startswith("{") and '"_overflow":' in v:
                 try:
                     metadata = json.loads(v)
@@ -491,10 +416,8 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
                         restored[k] = v
                         continue
 
-                    # Download real value from blob
                     blob_data = self._blob_download(blob_key)
 
-                    # Optional but very safe: checksum validation
                     if checksum:
                         actual_checksum = hashlib.md5(blob_data).hexdigest()
                         if actual_checksum != checksum:
@@ -502,7 +425,6 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
                                 f"Checksum mismatch for blob {blob_key} (property '{k}')"
                             )
 
-                    # Restore original value
                     actual_value = json.loads(blob_data.decode("utf-8"))
                     restored[k] = actual_value
                     logger.debug(f"Restored large property '{k}' from blob: {blob_key}")
@@ -511,11 +433,9 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
 
                 except Exception as e:
                     logger.error(f"Failed to restore overflow property '{k}': {e}")
-                    # Fall back to raw metadata instead of crashing
                     restored[k] = v
                     continue
 
-            # Normal (non-overflow) property
             restored[k] = v
 
         return restored
@@ -523,20 +443,11 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
     @retry(max_attempts=3, delay=1.0, exceptions=(NoSQLError,))
     def _put_raw(self, model: type, pk: str, rk: str, data: JsonDict) -> JsonDict:
         try:
-            # ─── CHANGED: local variable, not self._table_client ────────────
-            # The old pattern `self._table_client = self._get_table_client(...)`
-            # was a race hazard: two concurrent writes on different models
-            # could swap each other's client mid-call. Local variable is
-            # safe and identical in cost since the client is now cached.
             table_client = self._get_table_client(model)
             safe_pk = self._sanitize_pk_rk(pk)
             safe_rk = self._sanitize_pk_rk(rk)
-            # Pack entity (encoded for Azure Table)
             entity = self._pack_entity(model, safe_pk, safe_rk, data)
-            # ---------------------------------------------------
-            # SIZE ESTIMATION (use ORIGINAL payload, not packed)
-            # ---------------------------------------------------
-            MAX_PROPERTY_CHARS = 30 * 1024  # ~30K safe under UTF-16 32K limit
+            MAX_PROPERTY_CHARS = 30 * 1024
 
             def _is_large_string(val: Any) -> bool:
                 return isinstance(val, str) and len(val) > MAX_PROPERTY_CHARS
@@ -573,7 +484,7 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
                     continue
                 if k in large_val_dict:
                     metadata = large_val_dict[k]
-                    reference_entity[k] = json.dumps(metadata, default=json_safe)  # ← JSON string
+                    reference_entity[k] = json.dumps(metadata, default=json_safe)
                     logger.info(f"Overflow reference stored for {k} → {metadata['_blob_key']}")
                 else:
                     reference_entity[k] = v
@@ -596,17 +507,14 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
         try:
             safe_pk = self._sanitize_pk_rk(pk)
             safe_rk = self._sanitize_pk_rk(rk)
-            # ─── CHANGED: local variable ────────────────────────────────────
             table_client = self._get_table_client(model)
 
             entity = table_client.get_entity(safe_pk, safe_rk)
             entity_dict = dict(entity)
 
-            # Model isolation check
             if entity_dict.get(_MODEL_FIELD) != model.__qualname__:
                 return None
 
-            # Restore any large fields that were moved to blob
             restored_entity = self._restore_overflow_properties(entity_dict)
 
             out = self._unpack_entity(restored_entity)
@@ -625,10 +533,8 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
         self, model: type, filters: Dict[str, Any], limit: Optional[int]
     ) -> List[JsonDict]:
         try:
-            # ─── CHANGED: local variable ────────────────────────────────────
             table_client = self._get_table_client(model)
 
-            # Build query filter (your original logic kept unchanged)
             eff_filters = dict(filters or {})
             parts: List[str] = []
             for orig_k, orig_v in eff_filters.items():
@@ -670,12 +576,10 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
             for ent in entities:
                 ent_dict = dict(ent)
 
-                # Restore any large fields from blob
                 restored_entity = self._restore_overflow_properties(ent_dict)
 
                 out = self._unpack_entity(restored_entity)
 
-                # Guarantee 'id' field
                 if "id" not in out and "RowKey" in ent_dict:
                     out["id"] = ent_dict["RowKey"]
 
@@ -693,12 +597,10 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
     @retry(max_attempts=3, delay=1.0, exceptions=(NoSQLError,))
     def _delete_raw(self, model: type, pk: str, rk: str, etag: Optional[str]) -> JsonDict:
         try:
-            # ─── CHANGED: local variable ────────────────────────────────────
             table_client = self._get_table_client(model)
             safe_pk = self._sanitize_pk_rk(pk)
             safe_rk = self._sanitize_pk_rk(rk)
 
-            # read to check model + overflow
             try:
                 entity = table_client.get_entity(safe_pk, safe_rk)
                 entity_dict = dict(entity)
@@ -719,16 +621,100 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
         except Exception as e:
             raise NoSQLError(f"Azure Table delete failed: {str(e)}")
 
+    # -----------------------------
+    # Pagination overrides
+    # -----------------------------
+
+    @property
+    def capabilities(self):
+        from ..models import BackendCapabilities
+        return BackendCapabilities(
+            server_order=False,
+            server_filter=True,
+            native_cursor=True,
+            supports_count=False,
+        )
+
+    def query_paged(self, model: type, request) -> "PageResult":
+        """Use Azure native continuation tokens when no ORDER BY; fall back to in-memory sort."""
+        from ..models import PageResult
+
+        if request.order_by:
+            # Azure Table has no ORDER BY — fall back to in-memory sort via base class
+            return super().query_paged(model, request)
+
+        table_client = self._get_table_client(model)
+        eff_filters = dict(request.filters or {})
+        parts: List[str] = []
+        for orig_k, orig_v in eff_filters.items():
+            if orig_v is None:
+                continue
+            if orig_k in ("partition_key", "PartitionKey"):
+                sk = "PartitionKey"
+            elif orig_k in ("row_key", "RowKey"):
+                sk = "RowKey"
+            else:
+                sk = self._sanitize_prop_name(orig_k)
+            ev = self._encode_value(orig_v)
+            if ev is None:
+                parts.append(f"{sk} eq null")
+            elif isinstance(ev, bool):
+                parts.append(f"{sk} eq {str(ev).lower()}")
+            elif isinstance(ev, (int, float)):
+                parts.append(f"{sk} eq {ev}")
+            elif isinstance(ev, datetime):
+                iso = ev.isoformat()
+                if not iso.endswith("Z"):
+                    iso += "Z"
+                parts.append(f"{sk} eq datetime'{iso}'")
+            else:
+                sval = str(ev).replace("'", "''")
+                parts.append(f"{sk} eq '{sval}'")
+        query_filter = " and ".join(parts) if parts else None
+
+        azure_ct = None
+        if request.cursor:
+            cd = self._decode_cursor(request.cursor)
+            if cd.get("type") == "azure":
+                azure_ct = cd.get("token")
+
+        try:
+            paged = table_client.query_entities(
+                query_filter=query_filter,
+                results_per_page=request.limit,
+            )
+            page_iter = paged.by_page(continuation_token=azure_ct)
+            try:
+                page = next(iter(page_iter))
+                items = []
+                for ent in page:
+                    ent_dict = dict(ent)
+                    restored = self._restore_overflow_properties(ent_dict)
+                    out = self._unpack_entity(restored)
+                    if "id" not in out and "RowKey" in ent_dict:
+                        out["id"] = ent_dict["RowKey"]
+                    items.append(out)
+                next_azure_ct = page_iter.continuation_token
+            except StopIteration:
+                items = []
+                next_azure_ct = None
+        except Exception as e:
+            raise NoSQLError(f"Azure Table paged query failed: {str(e)}")
+
+        if request.fields:
+            field_set = set(request.fields)
+            items = [{k: v for k, v in item.items() if k in field_set} for item in items]
+
+        next_cursor = None
+        if next_azure_ct:
+            next_cursor = self._encode_cursor({"type": "azure", "token": next_azure_ct})
+
+        return PageResult(items=items, next_cursor=next_cursor, has_more=bool(next_azure_ct))
+
     # -----------------------------
     # Lifecycle
     # -----------------------------
     def close(self) -> None:
-        """Close cached clients. Safe to call multiple times.
-
-        ─── NEW ─────────────────────────────────────────────────────────────
-        Hook this into PolyDB shutdown so HTTP sessions don't leak on
-        application exit. Caches are cleared so a re-init starts clean.
-        """
         with self._cache_lock:
             for tc in self._table_clients_cache.values():
                 try:

polydb/adapters/PostgreSQLAdapter.py

@@ -6,6 +6,7 @@ from typing import Any, Iterator, List, Optional, Tuple, Union
 import hashlib
 from contextlib import contextmanager
 import json
+import base64
 from decimal import Decimal
 from datetime import datetime, date
 
@@ -16,7 +17,7 @@ from psycopg2.extras import Json
 from ..errors import DatabaseError, ConnectionError, InsufficientBalanceError
 from ..retry import retry
 from ..utils import validate_table_name, validate_column_name
-from ..query import QueryBuilder
+from ..query import QueryBuilder, Operator
 from ..types import JsonDict, Lookup
 
 
@@ -129,8 +130,6 @@ class PostgreSQLAdapter:
         try:
             conn = self._pool.getconn()  # type: ignore
 
-            # Only ping if the connection is in an error state (closed/broken),
-            # not on every call. TCP keepalives handle staleness detection.
             if conn.closed:
                 self.logger.warning("Closed connection detected from pool, closing and retrying")
                 self._pool.putconn(conn, close=True)  # type: ignore
@@ -650,6 +649,61 @@ class PostgreSQLAdapter:
             if own_conn and conn:
                 self._return_connection(conn)
 
+    # ---------------------------------------------------------------------
+    # PAGED QUERY (generic PageRequest / PageResult)
+    # ---------------------------------------------------------------------
+
+    @property
+    def capabilities(self):
+        from ..models import BackendCapabilities
+        return BackendCapabilities(
+            server_order=True,
+            server_filter=True,
+            native_cursor=False,
+            supports_count=True,
+        )
+
+    def query_paged(self, table: str, request, tx: Optional[Any] = None):
+        """Server-side ORDER BY + LIMIT/OFFSET with opaque offset cursor."""
+        from ..models import PageResult
+
+        offset = 0
+        if request.cursor:
+            try:
+                cd = json.loads(base64.b64decode(request.cursor.encode()).decode())
+                offset = cd.get("offset", 0)
+            except Exception:
+                offset = 0
+
+        builder = QueryBuilder()
+        for k, v in (request.filters or {}).items():
+            builder.where(k, Operator.EQ, v)
+        if request.order_by:
+            builder.order_by(request.order_by, descending=request.order_desc)
+        builder.skip(offset)
+        builder.take(request.limit + 1)
+        if request.fields:
+            builder.select_fields(request.fields)
+
+        results = self.query_linq(table, builder, tx=tx)
+        if isinstance(results, int):
+            return PageResult(items=[], has_more=False)
+
+        has_more = len(results) > request.limit
+        if has_more:
+            results = results[:request.limit]
+
+        next_cursor = None
+        if has_more:
+            cursor_data = {
+                "offset": offset + request.limit,
+                "order_by": request.order_by,
+                "desc": request.order_desc,
+            }
+            next_cursor = base64.b64encode(json.dumps(cursor_data).encode()).decode()
+
+        return PageResult(items=results, next_cursor=next_cursor, has_more=has_more)
+
     # ---------------------------------------------------------------------
     # EXECUTE RAW SQL
     # ---------------------------------------------------------------------
@@ -673,7 +727,6 @@ class PostgreSQLAdapter:
         cursor = None
         try:
             cursor = conn.cursor()
-            # Log operation shape only, never parameter values
             self.logger.debug("Executing raw SQL (%d params)", len(params or []))
             exec_params = self._serialize_params(params or [])
             self._timed_execute(cursor, sql, exec_params, operation="execute", table="")
@@ -913,7 +966,6 @@ class PostgreSQLAdapter:
 
     # ---------------------------------------------------------------------
     # SAVEPOINTS
-    # Security: use pg_sql.Identifier to prevent SQL injection via savepoint names.
     # ---------------------------------------------------------------------
 
     def begin_savepoint(self, name: str, tx: Any) -> None:

polydb/base/NoSQLKVAdapter.py

@@ -1,6 +1,7 @@
 # src/polydb/adapters/NoSQLKVAdapter.py
 from __future__ import annotations
 
+import base64
 import hashlib
 import json
 import threading
@@ -317,3 +318,58 @@ class NoSQLKVAdapter:
             results = unique
 
         return results
+
+    # ---------------------------------------------------------------
+    # Generic pagination API (opaque cursor, works for all NoSQL)
+    # ---------------------------------------------------------------
+
+    @property
+    def capabilities(self) -> "BackendCapabilities":
+        from ..models import BackendCapabilities
+        return BackendCapabilities()
+
+    def _encode_cursor(self, data: dict) -> str:
+        return base64.b64encode(json.dumps(data, default=json_safe).encode()).decode()
+
+    def _decode_cursor(self, cursor: str) -> dict:
+        try:
+            return json.loads(base64.b64decode(cursor.encode()).decode())
+        except Exception:
+            return {}
+
+    def query_paged(self, model: type, request: "PageRequest") -> "PageResult":
+        """In-memory pagination with opaque offset cursor. Subclasses may override."""
+        from ..models import PageResult
+
+        offset = 0
+        if request.cursor:
+            cd = self._decode_cursor(request.cursor)
+            offset = cd.get("offset", 0)
+
+        builder = QueryBuilder()
+        for k, v in (request.filters or {}).items():
+            builder.where(k, Operator.EQ, v)
+        if request.order_by:
+            builder.order_by(request.order_by, descending=request.order_desc)
+        builder.skip(offset)
+        builder.take(request.limit + 1)
+        if request.fields:
+            builder.select_fields(request.fields)
+
+        results = self.query_linq(model, builder)
+        if isinstance(results, int):
+            return PageResult(items=[], has_more=False)
+
+        has_more = len(results) > request.limit
+        if has_more:
+            results = results[:request.limit]
+
+        next_cursor = None
+        if has_more:
+            next_cursor = self._encode_cursor({
+                "offset": offset + request.limit,
+                "order_by": request.order_by,
+                "desc": request.order_desc,
+            })
+
+        return PageResult(items=results, next_cursor=next_cursor, has_more=has_more)

polydb/databaseFactory.py

@@ -34,6 +34,7 @@ from .audit.manager import AuditManager
 from .audit.context import AuditContext
 from .query import Operator, QueryBuilder
 from .cloudDatabaseFactory import CloudDatabaseFactory
+from .models import PageRequest, PageResult
 import re as _re
 
 logger = logging.getLogger(__name__)
@@ -60,12 +61,7 @@ def _is_unique_violation(exc: BaseException) -> bool:
     return any(m in s for m in _UNIQUE_VIOLATION_MARKERS)
 
 
-def _parse_unique_violation_columns(exc: BaseException) -> list[str]:
-    """
-    Pull the conflicting column names out of a Postgres unique-violation error.
-    Postgres formats them as:  Key (col1, col2)=(val1, val2) already exists.
-    Returns [] if the message doesn't carry that detail.
-    """
+def _parse_unique_violation_columns(exc: BaseException) -> list:
     m = _UNIQUE_KEY_RE.search(str(exc))
     if not m:
         return []
@@ -124,12 +120,6 @@ class _ResolvedAdapters:
 
 
 def _extract_meta(model: Union[type, str]) -> ModelMeta:
-    """
-    Extract storage metadata from model class.
-
-    If model is a string, return a default NoSQL meta (UDL resolves the
-    class before calling PolyDB, so string fallback is safe).
-    """
     if isinstance(model, type):
         raw = getattr(model, "__polydb__", None)
         if raw:
@@ -143,7 +133,6 @@ def _extract_meta(model: Union[type, str]) -> ModelMeta:
                 cache=raw.get("cache", False),
                 cache_ttl=raw.get("cache_ttl"),
             )
-    # Default for dynamic/string models
     return ModelMeta(storage="nosql", table=None, collection=None)
 
 
@@ -237,14 +226,13 @@ class DatabaseFactory:
         self._engine_by_name: Dict[str, EngineConfig] = {e.name: e for e in self._engines}
         self._provider_name = self._engines[0].cloud_factory.provider.value
 
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
     # ENGINE ROUTING
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
 
     def _resolve_adapters(
         self, model_name: str, storage: str, override: Optional[EngineOverride] = None
     ) -> _ResolvedAdapters:
-        # 1. Per-call override
         if override:
             engine = self._engine_by_name.get(override.engine_name)
             if engine is None:
@@ -255,7 +243,6 @@ class DatabaseFactory:
                 sql=engine.sql(), nosql=engine.nosql(), engine_name=engine.name
             )
 
-        # 2. Explicit allow-list
         for engine in self._engines:
             if storage == "sql" and engine.sql_models and model_name in engine.sql_models:
                 return _ResolvedAdapters(
@@ -266,7 +253,6 @@ class DatabaseFactory:
                     sql=engine.sql(), nosql=engine.nosql(), engine_name=engine.name
                 )
 
-        # 3. Default fallback
         for engine in self._engines:
             if storage == "sql" and engine.is_default_sql:
                 return _ResolvedAdapters(
@@ -291,9 +277,9 @@ class DatabaseFactory:
             storage = "sql" if (meta.storage == "sql" and meta.table) else "nosql"
         return self._resolve_adapters(name, storage, override)
 
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
     # ENGINE MANAGEMENT
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
 
     def register_engine(self, engine: EngineConfig) -> None:
         if engine.name in self._engine_by_name:
@@ -326,9 +312,9 @@ class DatabaseFactory:
                 return e.nosql()
         return self._engines[0].nosql()
 
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
     # HELPERS
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
 
     def _inject_audit_fields(self, data: JsonDict, is_create: bool = False) -> JsonDict:
         data = dict(data)
@@ -360,9 +346,9 @@ class DatabaseFactory:
             return False
         return meta.storage == "sql" and bool(meta.table)
 
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
     # CREATE
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
 
     def create(
         self,
@@ -393,13 +379,8 @@ class DatabaseFactory:
                 except Exception as exc:
                     if not _is_unique_violation(exc):
                         raise
-                    # Half-ran scenario / re-activation / replay. The record already
-                    # exists with these unique-key columns. Preserve idempotent
-                    # "create or update" semantics by routing to UPDATE keyed on the
-                    # exact columns that conflicted (parsed from the Postgres error).
                     conflict_cols = _parse_unique_violation_columns(exc)
                     if not conflict_cols or not all(c in data for c in conflict_cols):
-                        # Can't determine the conflict — re-raise so the caller sees it.
                         raise
                     where = {c: data[c] for c in conflict_cols}
                     logger.warning(
@@ -407,8 +388,6 @@ class DatabaseFactory:
                         meta.table,
                         conflict_cols,
                     )
-                    # Drop the conflict columns from the UPDATE SET clause — they're
-                    # already the matching key.
                     update_data = {k: v for k, v in data.items() if k not in conflict_cols}
                     result = adapters.sql.update(meta.table, where, update_data)
             else:
@@ -426,7 +405,10 @@ class DatabaseFactory:
                 after_plain = self.encryption.decrypt_fields(result, encrypted_fields)
             success = True
             if self._enable_cache and self._cache:
-                self._cache.invalidate(name)
+                try:
+                    self._cache.invalidate(name)
+                except Exception as _ce:
+                    logger.warning("Cache invalidate failed (non-fatal): %s", _ce)
             return after_plain
 
         try:
@@ -442,9 +424,9 @@ class DatabaseFactory:
         except Exception:
             raise
 
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
     # READ
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
 
     def read(
         self,
@@ -484,10 +466,12 @@ class DatabaseFactory:
                 raw = [self.encryption.decrypt_fields(r, encrypted_fields) for r in raw]
             if self._cache and use_external_cache and not no_cache:
                 ttl = cache_ttl or getattr(meta, "cache_ttl", 300)
-                self._cache.set(name, query or {}, raw, ttl)
+                try:
+                    self._cache.set(name, query or {}, raw, ttl)
+                except Exception as _ce:
+                    logger.warning("Cache set failed (non-fatal): %s", _ce)
             return raw
 
-        # Check external cache first
         if self._cache and use_external_cache and not no_cache:
             cached = self._cache.get(name, query or {})
             if cached is not None:
@@ -520,9 +504,9 @@ class DatabaseFactory:
         )
         return rows[0] if rows else None
 
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
     # UPDATE
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
 
     def update(
         self,
@@ -591,7 +575,10 @@ class DatabaseFactory:
                 after_plain = self.encryption.decrypt_fields(result, encrypted_fields)
             success = True
             if self._enable_cache and self._cache:
-                self._cache.invalidate(name)
+                try:
+                    self._cache.invalidate(name)
+                except Exception as _ce:
+                    logger.warning("Cache invalidate failed (non-fatal): %s", _ce)
             return after_plain
 
         try:
@@ -607,9 +594,9 @@ class DatabaseFactory:
         except Exception:
             raise
 
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
     # UPSERT
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
 
     def upsert(
         self,
@@ -648,7 +635,10 @@ class DatabaseFactory:
                 after_plain = self.encryption.decrypt_fields(result, encrypted_fields)
             success = True
             if self._enable_cache and self._cache:
-                self._cache.invalidate(name)
+                try:
+                    self._cache.invalidate(name)
+                except Exception as _ce:
+                    logger.warning("Cache invalidate failed (non-fatal): %s", _ce)
             return after_plain
 
         try:
@@ -664,9 +654,9 @@ class DatabaseFactory:
         except Exception:
             raise
 
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
     # DELETE
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
 
     def delete(
         self,
@@ -715,7 +705,10 @@ class DatabaseFactory:
                 result = adapters.nosql.delete(cls, entity_id, etag=etag)
             success = True
             if self._enable_cache and self._cache:
-                self._cache.invalidate(name)
+                try:
+                    self._cache.invalidate(name)
+                except Exception as _ce:
+                    logger.warning("Cache invalidate failed (non-fatal): %s", _ce)
             return result
 
         try:
@@ -731,9 +724,9 @@ class DatabaseFactory:
         except Exception:
             raise
 
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
     # QUERY (LINQ-style)
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
 
     def query_linq(
         self,
@@ -765,9 +758,9 @@ class DatabaseFactory:
                 return result
         return self._run(_op)
 
-    # ──────────────────────────────────────────────────────────────────────
-    # PAGINATION
-    # ──────────────────────────────────────────────────────────────────────
+    # ────────────────────────────────────────────────────────────────────
+    # PAGINATION (legacy simple)
+    # ────────────────────────────────────────────────────────────────────
 
     def read_page(
         self,
@@ -814,9 +807,40 @@ class DatabaseFactory:
                 return result
         return self._run(_op)
 
-    # ══════════════════════════════════════════════════════════════════════
+    # ────────────────────────────────────────────────────────────────────
+    # PAGINATION (generic — order_by, cursor, field projection)
+    # ────────────────────────────────────────────────────────────────────
+
+    def query_paged(
+        self,
+        model: Union[type, str],
+        request: PageRequest,
+        *,
+        engine_override: Optional[EngineOverride] = None,
+    ) -> PageResult:
+        """Unified pagination with order_by, opaque cursor, and field projection.
+
+        Routes to the best backend implementation:
+        - PostgreSQL: server-side ORDER BY + LIMIT/OFFSET
+        - Azure Table (no order_by): native continuation tokens
+        - Azure Table (with order_by) / all other NoSQL: in-memory sort + offset cursor
+        """
+        name = _model_name(model)
+        meta = _extract_meta(model)
+        adapters = self._adapters_for(model, meta, engine_override)
+
+        if self._is_sql(meta, engine_override):
+            return adapters.sql.query_paged(meta.table, request)
+
+        cls = (
+            model if isinstance(model, type)
+            else type(name, (), {"__polydb__": meta.__dict__})
+        )
+        return adapters.nosql.query_paged(cls, request)
+
+    # ═══════════════════════════════════════════════════════════════════════════════
     # BLOB STORAGE
-    # ══════════════════════════════════════════════════════════════════════
+    # ═══════════════════════════════════════════════════════════════════════════════
 
     def upload_blob(
         self,
@@ -865,9 +889,9 @@ class DatabaseFactory:
         )
         return storage.list(prefix)
 
-    # ══════════════════════════════════════════════════════════════════════
+    # ═══════════════════════════════════════════════════════════════════════════════
     # QUEUE
-    # ══════════════════════════════════════════════════════════════════════
+    # ═══════════════════════════════════════════════════════════════════════════════
 
     def send_queue(
         self,
@@ -914,9 +938,9 @@ class DatabaseFactory:
             else queue.delete(message_id, queue_name)
         )
 
-    # ══════════════════════════════════════════════════════════════════════
+    # ═══════════════════════════════════════════════════════════════════════════════
     # FILE STORAGE
-    # ══════════════════════════════════════════════════════════════════════
+    # ═══════════════════════════════════════════════════════════════════════════════
 
     def write_file(
         self, path: str, data: Union[bytes, str], *, adapter_name: str = "files"
@@ -936,9 +960,9 @@ class DatabaseFactory:
         files = self._engines[0].cloud_factory.get_files(adapter_name)
         return files.list(directory)
 
-    # ══════════════════════════════════════════════════════════════════════
+    # ═══════════════════════════════════════════════════════════════════════════════
     # CACHE
-    # ══════════════════════════════════════════════════════════════════════
+    # ═══════════════════════════════════════════════════════════════════════════════
 
     def set_cache(self, model: str, key: Any, value: Any, ttl: int = 300) -> None:
         if self._cache:

polydb/models.py

@@ -3,8 +3,8 @@
 Data models and configurations
 """
 
-from dataclasses import dataclass
-from typing import Optional, List, Callable, Any
+from dataclasses import dataclass, field
+from typing import Optional, List, Callable, Any, Dict
 from enum import Enum
 
 
@@ -43,6 +43,38 @@ class QueryOptions:
     count_only: bool = False
 
 
+@dataclass
+class BackendCapabilities:
+    """Describes what a storage backend can push down natively."""
+
+    server_order: bool = False
+    server_filter: bool = False
+    native_cursor: bool = False
+    supports_count: bool = True
+
+
+@dataclass
+class PageRequest:
+    """Unified pagination request passed to query_paged()."""
+
+    filters: Optional[Dict[str, Any]] = None
+    order_by: Optional[str] = None
+    order_desc: bool = False
+    limit: int = 50
+    cursor: Optional[str] = None
+    fields: Optional[List[str]] = None
+
+
+@dataclass
+class PageResult:
+    """Unified pagination result returned by query_paged()."""
+
+    items: List[Any] = field(default_factory=list)
+    next_cursor: Optional[str] = None
+    has_more: bool = False
+    total: Optional[int] = None
+
+
 # ============================================================
 # CONFIG CLASSES (TYPED)
 # ============================================================