altcodepro-polydb-python 2.3.26__tar.gz → 2.3.28__tar.gz

{altcodepro_polydb_python-2.3.26/src/altcodepro_polydb_python.egg-info → altcodepro_polydb_python-2.3.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: altcodepro-polydb-python
-Version: 2.3.26
+Version: 2.3.28
 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.26 → altcodepro_polydb_python-2.3.28}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "altcodepro-polydb-python"
-version = "2.3.26"
+version = "2.3.28"
 description = "Production-ready multi-cloud database abstraction layer with connection pooling, retry logic, and thread safety"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

{altcodepro_polydb_python-2.3.26 → altcodepro_polydb_python-2.3.28/src/altcodepro_polydb_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: altcodepro-polydb-python
-Version: 2.3.26
+Version: 2.3.28
 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.26 → altcodepro_polydb_python-2.3.28}/src/altcodepro_polydb_python.egg-info/SOURCES.txt

@@ -78,7 +78,9 @@ src/polydb/services/security_service.py
 tests/test_atomic_decrement.py
 tests/test_aws.py
 tests/test_azure.py
+tests/test_azure_queue_receipt_handle.py
 tests/test_azure_table_empty_filter.py
+tests/test_azure_table_unpack_entity.py
 tests/test_blockchain.py
 tests/test_cloud_factory.py
 tests/test_gcp.py

{altcodepro_polydb_python-2.3.26 → altcodepro_polydb_python-2.3.28}/src/polydb/adapters/AzureQueueAdapter.py

@@ -46,6 +46,20 @@ class AzureQueueAdapter(QueueAdapter):
         name = re.sub(r"-+", "-", name)  # collapse multiple dashes
         return name.strip("-")
 
+    @staticmethod
+    def _encode_receipt(message_id: str, pop_receipt: str) -> str:
+        # Azure needs BOTH message_id and pop_receipt to delete/update a
+        # message, but the generic queue contract (WorkerPool, SQSAdapter)
+        # only ever carries a single opaque `receipt_handle` string end to
+        # end. Pack both into one string here so ack()/nack() can recover
+        # them without any caller needing to know Azure's two-part scheme.
+        return f"{message_id}|{pop_receipt}"
+
+    @staticmethod
+    def _decode_receipt(receipt_handle: str) -> "tuple[str, str]":
+        message_id, _, pop_receipt = (receipt_handle or "").partition("|")
+        return message_id, pop_receipt
+
     def _initialize_client(self) -> None:
         """Initialize Azure Queue client"""
         from azure.storage.queue import QueueServiceClient
@@ -114,6 +128,13 @@ class AzureQueueAdapter(QueueAdapter):
                     {
                         "id": msg.id,
                         "pop_receipt": msg.pop_receipt,
+                        # WorkerPool (and the generic UDL queue contract)
+                        # reads this key to ack/nack. Without it, ack() is
+                        # always skipped (falsy receipt_handle), the message
+                        # is never deleted, and it silently reappears once
+                        # Azure's visibility timeout elapses — replaying the
+                        # same task forever even after it already ran.
+                        "receipt_handle": self._encode_receipt(msg.id, msg.pop_receipt),
                         "body": payload,
                     }
                 )
@@ -156,8 +177,14 @@ class AzureQueueAdapter(QueueAdapter):
         Preferred usage:
             ack(pop_receipt=..., message_id=...)
 
-        If message_id is not provided, this will fail safely.
+        Generic callers (WorkerPool, storage_router.queue_ack) only pass a
+        single `receipt_handle` positionally and never supply message_id —
+        in that case `pop_receipt` here is actually the combined value
+        produced by `receive()` (`"<message_id>|<pop_receipt>"`), so decode
+        it rather than failing.
         """
+        if not message_id:
+            message_id, pop_receipt = self._decode_receipt(pop_receipt)
         if not message_id:
             raise QueueError("AzureQueueAdapter.ack requires message_id")
         queue_name = self._normalize_queue_name(queue_name)
@@ -166,3 +193,34 @@ class AzureQueueAdapter(QueueAdapter):
             queue_name=queue_name,
             pop_receipt=pop_receipt,
         )
+
+    def nack(
+        self,
+        queue_name: str,
+        ack_id: str,
+        *,
+        delay: Optional[int] = None,
+    ) -> bool:
+        """
+        Make a message visible again (optionally after `delay` seconds)
+        without deleting it, instead of leaving it to reappear only once
+        Azure's default visibility timeout elapses.
+
+        `ack_id` is the combined `"<message_id>|<pop_receipt>"` receipt
+        handle produced by `receive()`. Matches the positional order used
+        by storage_router.queue_nack: nack(queue_name, ack_id, delay=...).
+        """
+        message_id, pop_receipt = self._decode_receipt(ack_id)
+        if not message_id:
+            raise QueueError("AzureQueueAdapter.nack requires a receipt_handle from receive()")
+        try:
+            queue_name = self._normalize_queue_name(queue_name)
+            queue_client = self._get_queue(queue_name)
+            queue_client.update_message(
+                message_id,
+                pop_receipt=pop_receipt,
+                visibility_timeout=delay or 0,
+            )
+            return True
+        except Exception as e:
+            raise QueueError(f"Azure Queue nack failed: {e}")

{altcodepro_polydb_python-2.3.26 → altcodepro_polydb_python-2.3.28}/src/polydb/adapters/AzureTableStorageAdapter.py

@@ -255,7 +255,7 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
 
         return entity
 
-    def _unpack_entity(self, entity: JsonDict) -> JsonDict:
+    def _unpack_entity(self, model: type, entity: JsonDict) -> JsonDict:
         if not entity:
             return {}
 
@@ -263,6 +263,9 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
         raw.pop("etag", None)
         raw.pop("ETag", None)
         raw.pop("Timestamp", None)
+        # Internal: which model a row belongs to, used only to isolate models
+        # sharing a table. Never part of the public record shape.
+        raw.pop(_MODEL_FIELD, None)
 
         keymap_str = raw.pop("__keymap__", None)
         keymap: Dict[str, str] = {}
@@ -272,26 +275,30 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
             except Exception:
                 keymap = {}
 
-        out: JsonDict = {}
-
-        pk = raw.get("PartitionKey")
-        rk = raw.get("RowKey")
-        if pk is not None:
-            out["PartitionKey"] = pk
-        if rk is not None:
-            out["RowKey"] = rk
+        pk = raw.pop("PartitionKey", None)
+        rk = raw.pop("RowKey", None)
 
+        out: JsonDict = {}
         for k, v in raw.items():
-            if k in ("PartitionKey", "RowKey"):
-                continue
-
-            if k.startswith("_") or k in (_MODEL_FIELD,):
+            if k.startswith("_"):
                 out[k] = v
                 continue
 
             orig_key = keymap.get(k, k)
             out[orig_key] = self._decode_value(v)
 
+        # PartitionKey/RowKey are Azure Table Storage's own physical column
+        # names — never return them as-is. Map each back to the domain field
+        # it was derived from (model's declared partition_key/sort_key, same
+        # resolution _get_pk_rk used to write them), so the same field name
+        # round-trips on read as it did on write. Guarded so we never clobber
+        # a real property that already carries the value (the common case —
+        # pk/rk fields are usually also stored as regular properties).
+        pk_field, rk_field = self._pk_rk_field_names(model)
+        if pk is not None and pk_field not in out:
+            out[pk_field] = pk
+        if rk is not None and rk_field not in out:
+            out[rk_field] = rk
         if "id" not in out and rk is not None:
             out["id"] = rk
 
@@ -491,7 +498,7 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
 
             table_client.upsert_entity(reference_entity)
 
-            restored = self._unpack_entity(entity)
+            restored = self._unpack_entity(model, entity)
             restored["id"] = safe_rk
 
             return restored
@@ -517,7 +524,7 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
 
             restored_entity = self._restore_overflow_properties(entity_dict)
 
-            out = self._unpack_entity(restored_entity)
+            out = self._unpack_entity(model, restored_entity)
             if "id" not in out:
                 out["id"] = safe_rk
 
@@ -589,7 +596,7 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
 
                 restored_entity = self._restore_overflow_properties(ent_dict)
 
-                out = self._unpack_entity(restored_entity)
+                out = self._unpack_entity(model, restored_entity)
 
                 if "id" not in out and "RowKey" in ent_dict:
                     out["id"] = ent_dict["RowKey"]
@@ -705,7 +712,7 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
                 for ent in page:
                     ent_dict = dict(ent)
                     restored = self._restore_overflow_properties(ent_dict)
-                    out = self._unpack_entity(restored)
+                    out = self._unpack_entity(model, restored)
                     if "id" not in out and "RowKey" in ent_dict:
                         out["id"] = ent_dict["RowKey"]
                     items.append(out)

{altcodepro_polydb_python-2.3.26 → altcodepro_polydb_python-2.3.28}/src/polydb/adapters/MongoDBAdapter.py

@@ -50,7 +50,9 @@ class MongoDBAdapter(NoSQLKVAdapter):
                     self.mongo_uri,
                     maxPoolSize=int(os.getenv("MONGODB_MAX_POOL_SIZE", "10")),
                     minPoolSize=int(os.getenv("MONGODB_MIN_POOL_SIZE", "1")),
-                    serverSelectionTimeoutMS=5000,
+                    serverSelectionTimeoutMS=int(
+                        os.getenv("MONGODB_SERVER_SELECTION_TIMEOUT_MS", "5000")
+                    ),
                 )
 
                 self._client.server_info()

{altcodepro_polydb_python-2.3.26 → altcodepro_polydb_python-2.3.28}/src/polydb/base/NoSQLKVAdapter.py

@@ -34,6 +34,22 @@ class NoSQLKVAdapter:
         self._lock = threading.Lock()
         self.max_size = 1024 * 1024  # 1MB
 
+    def _pk_rk_field_names(self, model: type) -> Tuple[str, str]:
+        """
+        The domain field names PK/RK were derived from — the mirror image of
+        _get_pk_rk's field resolution. Adapters use this to translate a
+        physical PartitionKey/RowKey (or pk/sk, whatever the backend calls
+        them) back into the model's own field name before returning a record,
+        instead of leaking storage-internal column names to callers. Falls
+        back to the same defaults _get_pk_rk uses (tenant_id / id) when a
+        model declares no explicit mapping, so unmapped models still round-
+        trip cleanly on upsert without erroring.
+        """
+        meta = getattr(model, "__polydb__", {})
+        pk_field = meta.get("pk_field") or meta.get("partition_key", "tenant_id")
+        rk_field = meta.get("rk_field") or meta.get("sort_key", "id")
+        return pk_field, rk_field
+
     def _get_pk_rk(self, model: type, data: JsonDict) -> Tuple[str, str]:
         """Extract PK/RK from model metadata"""
         meta = getattr(model, "__polydb__", {})

{altcodepro_polydb_python-2.3.26 → altcodepro_polydb_python-2.3.28}/src/polydb/databaseFactory.py

@@ -109,8 +109,8 @@ class EngineOverride:
 
 @dataclass
 class _ResolvedAdapters:
-    sql: PostgreSQLAdapter
-    nosql: NoSQLKVAdapter
+    sql: Optional[PostgreSQLAdapter]
+    nosql: Optional[NoSQLKVAdapter]
     engine_name: str
 
 
@@ -233,35 +233,38 @@ class DatabaseFactory:
     def _resolve_adapters(
         self, model_name: str, storage: str, override: Optional[EngineOverride] = None
     ) -> _ResolvedAdapters:
+        # Only construct the adapter this call actually needs. Every caller
+        # (create/read/update/upsert/delete/query*) branches on `storage` and
+        # touches exactly one of .sql/.nosql — building both unconditionally
+        # meant a purely-SQL deployment with no reachable NoSQL backend (or
+        # vice versa) failed on every single call, not just ones that needed
+        # the missing engine.
+        def _build(engine: "EngineConfig") -> _ResolvedAdapters:
+            return _ResolvedAdapters(
+                sql=engine.sql() if storage == "sql" else None,
+                nosql=engine.nosql() if storage == "nosql" else None,
+                engine_name=engine.name,
+            )
+
         if override:
             engine = self._engine_by_name.get(override.engine_name)
             if engine is None:
                 raise AdapterConfigurationError(
                     f"Unknown engine '{override.engine_name}'. Available: {list(self._engine_by_name)}"
                 )
-            return _ResolvedAdapters(
-                sql=engine.sql(), nosql=engine.nosql(), engine_name=engine.name
-            )
+            return _build(engine)
 
         for engine in self._engines:
             if storage == "sql" and engine.sql_models and model_name in engine.sql_models:
-                return _ResolvedAdapters(
-                    sql=engine.sql(), nosql=engine.nosql(), engine_name=engine.name
-                )
+                return _build(engine)
             if storage == "nosql" and engine.nosql_models and model_name in engine.nosql_models:
-                return _ResolvedAdapters(
-                    sql=engine.sql(), nosql=engine.nosql(), engine_name=engine.name
-                )
+                return _build(engine)
 
         for engine in self._engines:
             if storage == "sql" and engine.is_default_sql:
-                return _ResolvedAdapters(
-                    sql=engine.sql(), nosql=engine.nosql(), engine_name=engine.name
-                )
+                return _build(engine)
             if storage == "nosql" and engine.is_default_nosql:
-                return _ResolvedAdapters(
-                    sql=engine.sql(), nosql=engine.nosql(), engine_name=engine.name
-                )
+                return _build(engine)
 
         raise AdapterConfigurationError(f"No engine for model='{model_name}' storage='{storage}'")
 
@@ -543,14 +546,32 @@ class DatabaseFactory:
             if self._is_sql(meta, engine_override):
                 result = adapters.sql.update(meta.table, entity_id, data)
             else:
+                # A scalar entity_id is usually the record's "id" property,
+                # not its physical PartitionKey/RowKey — those come from the
+                # model's declared pk_field/rk_field (x-metadata partition_key
+                # /sort_key), which for most schema models is a different
+                # field entirely (e.g. Artifact: pk=project_slug, rk=
+                # template_key). Recover both from the patch payload, or —
+                # more reliably — from the record loaded just above as
+                # `before`, so a plain id-addressed update() still lands on
+                # the entity's real physical key instead of a mismatched
+                # default partition / the id used as a row key it never had.
                 pkey = data.get("PartitionKey") or data.get("partition_key") or data.get("pk")
-                en_id = entity_id
+                if not pkey and meta.pk_field:
+                    pkey = data.get(meta.pk_field)
                 if not pkey and before:
                     pkey = (
                         before.get("PartitionKey")
                         or before.get("partition_key")
                         or before.get("pk")
+                        or (before.get(meta.pk_field) if meta.pk_field else None)
                     )
+                rkey = None
+                if meta.rk_field and meta.rk_field != "id":
+                    rkey = data.get(meta.rk_field) or (
+                        before.get(meta.rk_field) if before else None
+                    )
+                en_id = entity_id
                 if pkey:
                     if isinstance(en_id, dict):
                         en_pk = (
@@ -560,8 +581,16 @@ class DatabaseFactory:
                         )
                         if not en_pk:
                             en_id["partition_key"] = pkey
+                        en_rk = (
+                            en_id.get("RowKey")
+                            or en_id.get("row_key")
+                            or en_id.get("rk")
+                            or en_id.get("id")
+                        )
+                        if not en_rk and rkey:
+                            en_id["row_key"] = rkey
                     elif isinstance(en_id, str):
-                        en_id = {"partition_key": pkey, "id": entity_id}
+                        en_id = {"partition_key": pkey, "row_key": rkey or entity_id}
 
                 cls = (
                     model
@@ -702,7 +731,23 @@ class DatabaseFactory:
                     if isinstance(model, type)
                     else type(name, (), {"__polydb__": meta.__dict__})
                 )
-                result = adapters.nosql.delete(cls, entity_id, etag=etag)
+                # Same physical-key recovery as update() (see there for why a
+                # scalar entity_id alone isn't enough once a model's pk_field
+                # /rk_field differ from "id").
+                en_id = entity_id
+                if not isinstance(en_id, dict) and before:
+                    pkey = (
+                        before.get("PartitionKey")
+                        or before.get("partition_key")
+                        or before.get("pk")
+                        or (before.get(meta.pk_field) if meta.pk_field else None)
+                    )
+                    if pkey:
+                        rkey = None
+                        if meta.rk_field and meta.rk_field != "id":
+                            rkey = before.get(meta.rk_field)
+                        en_id = {"partition_key": pkey, "row_key": rkey or entity_id}
+                result = adapters.nosql.delete(cls, en_id, etag=etag)
             success = True
             if self._enable_cache and self._cache:
                 try:

altcodepro_polydb_python-2.3.28/tests/test_azure_queue_receipt_handle.py

@@ -0,0 +1,141 @@
+"""
+tests/test_azure_queue_receipt_handle.py
+=========================================
+Regression coverage for the receipt_handle contract on AzureQueueAdapter.
+
+Bug this guards against: `receive()` used to return only `id` and
+`pop_receipt`, never the `receipt_handle` key that WorkerPool (and every
+other adapter's ack contract) reads. That made
+`WorkerPool._process_message`'s `msg.get("receipt_handle")` always `None`,
+so the ack branch was silently skipped, the message was never deleted, and
+Azure redelivered it once its visibility timeout elapsed — replaying the
+same task forever even after it had already run to completion.
+
+These tests mock the Azure SDK entirely (no live Azurite needed) and only
+exercise the adapter's own encode/decode + ack/nack wiring.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+# test_atomic_decrement.py stubs sys.modules["azure"] et al. with bare,
+# path-less ModuleType objects (guarded by `if _mod not in sys.modules`) so
+# it can run without cloud SDKs installed. If it collects before this file
+# (alphabetically it does), that stub wins the module cache for the rest of
+# the process, and the adapter's lazy `from azure.core.exceptions import
+# ...` imports then fail with "'azure' is not a package" -- even though the
+# real azure SDK is installed here. Drop any such stubs so this file always
+# imports the genuine package fresh.
+for _name in list(sys.modules):
+    if _name == "azure" or _name.startswith("azure."):
+        del sys.modules[_name]
+
+from polydb.adapters.AzureQueueAdapter import AzureQueueAdapter
+
+
+def _make_adapter() -> AzureQueueAdapter:
+    # Bypass the real Azure SDK entirely -- when the full suite runs
+    # together, other providers' tests leave azure.storage.queue in a state
+    # where importing QueueServiceClient from it fails (a pre-existing
+    # cross-test import-cache issue, unrelated to this adapter). Skipping
+    # `_initialize_client` sidesteps that import altogether; these tests
+    # only care about the adapter's own encode/decode + ack/nack wiring.
+    with patch.object(AzureQueueAdapter, "_initialize_client", lambda self: None):
+        adapter = AzureQueueAdapter(connection_string="UseDevelopmentStorage=true")
+    adapter._client = MagicMock()
+    return adapter
+
+
+def _mock_queue_client(adapter: AzureQueueAdapter, queue_name: str = "default") -> MagicMock:
+    client = MagicMock()
+    adapter._queues[adapter._normalize_queue_name(queue_name)] = client
+    return client
+
+
+class TestReceiveReturnsReceiptHandle:
+    def test_receive_includes_receipt_handle_key(self):
+        adapter = _make_adapter()
+        client = _mock_queue_client(adapter)
+
+        raw_msg = MagicMock()
+        raw_msg.id = "msg-123"
+        raw_msg.pop_receipt = "pop-abc"
+        raw_msg.content = json.dumps({"hello": "world"})
+        client.receive_messages.return_value = [raw_msg]
+
+        [received] = adapter.receive(queue_name="default", max_messages=1)
+
+        assert received["id"] == "msg-123"
+        assert received["pop_receipt"] == "pop-abc"
+        assert "receipt_handle" in received
+        assert received["receipt_handle"]  # truthy -- WorkerPool checks `if receipt_handle`
+
+    def test_receipt_handle_round_trips_through_decode(self):
+        message_id, pop_receipt = AzureQueueAdapter._decode_receipt(
+            AzureQueueAdapter._encode_receipt("msg-123", "pop-abc")
+        )
+        assert message_id == "msg-123"
+        assert pop_receipt == "pop-abc"
+
+
+class TestAckAcceptsSingleReceiptHandle:
+    def test_ack_with_generic_single_arg_deletes_using_decoded_parts(self):
+        """Mirrors how WorkerPool/storage_router actually call ack():
+        queue.ack(receipt_handle, queue_name) -- a single positional value,
+        never a separate message_id.
+        """
+        adapter = _make_adapter()
+        client = _mock_queue_client(adapter)
+
+        receipt_handle = AzureQueueAdapter._encode_receipt("msg-123", "pop-abc")
+        result = adapter.ack(receipt_handle, "default")
+
+        assert result is True
+        client.delete_message.assert_called_once_with("msg-123", "pop-abc")
+
+    def test_ack_still_supports_explicit_message_id(self):
+        adapter = _make_adapter()
+        client = _mock_queue_client(adapter)
+
+        result = adapter.ack("pop-abc", "default", message_id="msg-123")
+
+        assert result is True
+        client.delete_message.assert_called_once_with("msg-123", "pop-abc")
+
+    def test_ack_raises_if_receipt_handle_has_no_message_id(self):
+        adapter = _make_adapter()
+        _mock_queue_client(adapter)
+
+        with pytest.raises(Exception):
+            adapter.ack("", "default")
+
+
+class TestNack:
+    def test_nack_updates_visibility_without_deleting(self):
+        adapter = _make_adapter()
+        client = _mock_queue_client(adapter)
+
+        receipt_handle = AzureQueueAdapter._encode_receipt("msg-123", "pop-abc")
+        result = adapter.nack("default", receipt_handle, delay=30)
+
+        assert result is True
+        client.update_message.assert_called_once_with(
+            "msg-123", pop_receipt="pop-abc", visibility_timeout=30
+        )
+        client.delete_message.assert_not_called()
+
+    def test_nack_defaults_delay_to_zero(self):
+        adapter = _make_adapter()
+        client = _mock_queue_client(adapter)
+
+        receipt_handle = AzureQueueAdapter._encode_receipt("msg-123", "pop-abc")
+        adapter.nack("default", receipt_handle)
+
+        client.update_message.assert_called_once_with(
+            "msg-123", pop_receipt="pop-abc", visibility_timeout=0
+        )

altcodepro_polydb_python-2.3.28/tests/test_azure_table_unpack_entity.py

@@ -0,0 +1,76 @@
+"""Unit tests for AzureTableStorageAdapter._unpack_entity (no Azurite needed).
+
+Contract: PartitionKey/RowKey/__polydb_model__ are Azure Table Storage
+internals and must never leak into a returned record. Each gets mapped back
+to the domain field it was derived from (the model's declared
+partition_key/sort_key — the same fields _get_pk_rk used to write them), and
+only fills in that field if it isn't already present from a regular stored
+property. Models with no explicit mapping still round-trip cleanly via the
+same defaults _get_pk_rk uses (tenant_id / id) instead of erroring.
+"""
+
+import pytest
+
+pytest.importorskip("azure.data.tables")  # adapter needs the SDK to import
+
+from polydb.adapters.AzureTableStorageAdapter import AzureTableStorageAdapter  # noqa: E402
+
+
+class _ArtifactComment:
+    __name__ = "ArtifactComment"
+    __polydb__ = {"partition_key": "artifact_id", "sort_key": "created_at"}
+
+
+class _Unmapped:
+    __name__ = "Unmapped"
+    # no __polydb__ at all
+
+
+def _adapter():
+    return object.__new__(AzureTableStorageAdapter)  # bypass live-connection __init__
+
+
+def test_mapped_model_remaps_pk_rk_and_strips_internals():
+    entity = {
+        "PartitionKey": "artifact-123",
+        "RowKey": "2026-07-13T21_04_53",
+        "__polydb_model__": "ArtifactComment",
+        "artifact_id": "artifact-123",
+        "created_at": "2026-07-13T21:04:53",
+        "body": "hello",
+    }
+    out = _adapter()._unpack_entity(_ArtifactComment, entity)
+    assert "PartitionKey" not in out
+    assert "RowKey" not in out
+    assert "__polydb_model__" not in out
+    assert out["artifact_id"] == "artifact-123"
+    assert out["created_at"] == "2026-07-13T21:04:53"  # real property wins over RowKey
+    assert out["body"] == "hello"
+
+
+def test_unmapped_model_falls_back_without_erroring():
+    entity = {
+        "PartitionKey": "t1",
+        "RowKey": "row1",
+        "__polydb_model__": "Unmapped",
+        "email": "user@x.com",
+    }
+    out = _adapter()._unpack_entity(_Unmapped, entity)
+    assert "PartitionKey" not in out
+    assert "RowKey" not in out
+    assert "__polydb_model__" not in out
+    assert out["tenant_id"] == "t1"
+    assert out["id"] == "row1"
+    assert out["email"] == "user@x.com"
+
+
+def test_pk_rk_fill_in_only_when_field_missing():
+    entity = {
+        "PartitionKey": "artifact-999",
+        "RowKey": "row-1",
+        "__polydb_model__": "ArtifactComment",
+        "body": "no explicit artifact_id property",
+    }
+    out = _adapter()._unpack_entity(_ArtifactComment, entity)
+    assert out["artifact_id"] == "artifact-999"
+    assert out["created_at"] == "row-1"