matrx-orm 3.1.37__tar.gz → 3.1.38__tar.gz

{matrx_orm-3.1.37 → matrx_orm-3.1.38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.37
+Version: 3.1.38
 Summary: Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching
 Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
 Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current

{matrx_orm-3.1.37 → matrx_orm-3.1.38}/matrx_orm/associations.py

@@ -196,6 +196,15 @@ class Associations:
         self._org = org_field
         self._role = role_field
         self._role_available = True  # refined by _validate_field_bindings when introspectable
+        # Optional edge-document columns (platform.associations carries them;
+        # a minimal host edge table may not). Passing the kwarg against a
+        # table without the column raises loudly at call time.
+        self._optional_cols: dict[str, bool] = {
+            "payload_kind": True,
+            "payload": True,
+            "label": True,
+            "position": True,
+        }
         self._validate_field_bindings()
 
     def _validate_field_bindings(self) -> None:
@@ -230,6 +239,8 @@ class Associations:
         # role is OPTIONAL on the edge table — engines over role-less edge
         # tables keep working; passing a role against one raises at call time.
         self._role_available = self._role in fields
+        for col in self._optional_cols:
+            self._optional_cols[col] = col in fields
 
     # ---- writes ----------------------------------------------------------
 
@@ -257,6 +268,10 @@ class Associations:
         metadata: dict[str, Any] | None = None,
         created_by: str | None = None,
         verify: bool = True,
+        payload_kind: str | None = None,
+        payload: dict[str, Any] | None = None,
+        label: str | None = None,
+        position: int | None = None,
     ) -> Any:
         """Idempotently create the ``source -> target`` edge in ``org_id``.
 
@@ -288,6 +303,17 @@ class Associations:
             defaults["metadata"] = metadata
         if created_by is not None:
             defaults["created_by"] = created_by
+        extras = {"payload_kind": payload_kind, "payload": payload, "label": label, "position": position}
+        for col, value in extras.items():
+            if value is None:
+                continue
+            if not self._optional_cols.get(col, True):
+                model_name = getattr(self._assoc, "__name__", str(self._assoc))
+                raise ValueError(
+                    f"{col}={value!r} was passed but edge model {model_name} has no "
+                    f"{col!r} column — add the column or drop the argument."
+                )
+            defaults[col] = value
         lookup = {
             self._st: source.type,
             self._si: source.id,
@@ -300,8 +326,14 @@ class Associations:
         elif role is not None:
             self._role_filter(role)  # raises with the loud config message
         edge, created = await self._assoc.get_or_create(defaults=defaults, **lookup)
-        if not created and metadata is not None and getattr(edge, "metadata", None) != metadata:
-            edge = await edge.update(metadata=metadata)
+        if not created:
+            updates = {
+                col: value
+                for col, value in {"metadata": metadata, **extras}.items()
+                if value is not None and getattr(edge, col, None) != value
+            }
+            if updates:
+                edge = await edge.update(**updates)
         return edge
 
     async def dissociate(

{matrx_orm-3.1.37 → matrx_orm-3.1.38}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.37"
+version = "3.1.38"
 description = "Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching"
 readme = "README.md"
 license = { text = "MIT" }

{matrx_orm-3.1.37 → matrx_orm-3.1.38}/tests/level1/test_associations.py

@@ -262,6 +262,45 @@ async def test_load_gated_returns_system_vocabulary_cross_org():
     assert [t.id for t in targets] == ["k1"]
 
 
+@pytest.mark.asyncio
+async def test_associate_writes_and_replaces_payload_document():
+    a = _assoc()
+    _seed_n1_p1()
+    src, tgt = EntityRef("note", "n1"), EntityRef("project", "p1")
+    e1 = await a.associate(
+        src, tgt, org_id="org1", role="reviewed_by",
+        payload_kind="plan_review", payload={"review_date": "2026-07-25"},
+        label="Review", position=1,
+    )
+    assert e1.payload_kind == "plan_review" and e1.payload == {"review_date": "2026-07-25"}
+    assert e1.label == "Review" and e1.position == 1
+    # repeat call: passed values full-replace; omitted (None) stay untouched
+    e2 = await a.associate(
+        src, tgt, org_id="org1", role="reviewed_by",
+        payload={"review_date": "2026-07-26", "notes": "x"},
+    )
+    assert e2 is e1 and e2.payload == {"review_date": "2026-07-26", "notes": "x"}
+    assert e2.payload_kind == "plan_review" and e2.label == "Review"
+    assert len(AssociationRow._rows) == 1
+
+
+@pytest.mark.asyncio
+async def test_associate_payload_against_payloadless_table_raises():
+    from types import SimpleNamespace
+
+    cols = ("source_type", "source_id", "target_type", "target_id", "org_id", "role", "metadata")
+    model = type(
+        "_MiniEdge", (_FakeBase,), {"_meta": SimpleNamespace(fields={c: object() for c in cols})}
+    )
+    a = Associations(association_model=model, registry=_token_registry())
+    _seed_n1_p1()
+    with pytest.raises(ValueError, match="payload_kind"):
+        await a.associate(
+            EntityRef("note", "n1"), EntityRef("project", "p1"),
+            org_id="org1", payload_kind="plan_review",
+        )
+
+
 @pytest.mark.asyncio
 async def test_associate_verify_false_skips_endpoint_check():
     a = _assoc()  # no endpoints seeded at all