matrx-orm 3.1.146__tar.gz → 3.1.148__tar.gz

{matrx_orm-3.1.146 → matrx_orm-3.1.148}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.146
+Version: 3.1.148
 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.146 → matrx_orm-3.1.148}/matrx_orm/__init__.py

@@ -241,6 +241,7 @@ from .core.registry import (
 from .core.relations import ManyToManyField
 from .core.rls_session import rls_session
 from .core.session_context import (
+    ACTOR_AGENT_GUC,
     ACTOR_SYSTEM_GUC,
     ACTOR_TIER_GUC,
     VALID_TIERS,
@@ -654,6 +655,7 @@ __all__ = [
     "acquire_connection",
     "set_local_guc",
     "SessionContextProvider",
+    "ACTOR_AGENT_GUC",
     "ACTOR_SYSTEM_GUC",
     "ACTOR_TIER_GUC",
     "VALID_TIERS",

{matrx_orm-3.1.146 → matrx_orm-3.1.148}/matrx_orm/core/expressions.py

@@ -1120,6 +1120,7 @@ def _parse_lookup_simple(key: str) -> tuple[str, str]:
         "startswith",
         "endswith",
         "exclude",
+        "user_visible",
     }
     if "__" in key:
         parts = key.rsplit("__", 1)

{matrx_orm-3.1.146 → matrx_orm-3.1.148}/matrx_orm/core/session_context.py

@@ -35,6 +35,7 @@ from contextlib import asynccontextmanager, contextmanager
 from contextvars import ContextVar
 from dataclasses import dataclass
 from typing import Any, Literal
+from uuid import UUID
 
 logger = logging.getLogger("matrx_orm.core.session_context")
 
@@ -110,6 +111,12 @@ ActorTier = Literal["code", "ai", "human"]
 
 ACTOR_TIER_GUC = "app.actor_tier"
 ACTOR_SYSTEM_GUC = "app.actor_system"
+# DD-211: WHICH AGENT, when an agent is the one writing. The database reads it
+# through ``platform.declared_actor_agent()`` and names the ``agent`` rung when
+# it resolves ``records.confirmation.agent_write_born_confirmed`` -- which is
+# what makes a per-agent born-confirmed exception a real setting instead of a
+# control that saves a value nothing honours.
+ACTOR_AGENT_GUC = "app.actor_agent"
 
 VALID_TIERS: frozenset[str] = frozenset({"code", "ai", "human"})
 
@@ -120,10 +127,25 @@ class ActorRef:
 
     tier: ActorTier
     system: str | None = None
+    #: The agent definition id, when the writer IS an agent (DD-211). A
+    #: person's write never carries one -- the database refuses the pair
+    #: ``tier="human"`` + an agent, because "a person did this" and "agent X
+    #: did this" are two different authors.
+    agent: str | None = None
 
     def as_gucs(self) -> dict[str, str]:
-        """The two session GUCs this actor implies."""
-        return {ACTOR_TIER_GUC: self.tier, ACTOR_SYSTEM_GUC: self.system or ""}
+        """The session GUCs this actor implies.
+
+        ``app.actor_agent`` is always emitted, empty when no agent is writing:
+        the GUCs are transaction-local and a *stale* agent left over from an
+        outer declaration would attribute this block's writes to the wrong
+        agent. Empty is read as "no agent" by ``platform.declared_actor_agent``.
+        """
+        return {
+            ACTOR_TIER_GUC: self.tier,
+            ACTOR_SYSTEM_GUC: self.system or "",
+            ACTOR_AGENT_GUC: self.agent or "",
+        }
 
 
 _current_actor: ContextVar[ActorRef | None] = ContextVar("_provenance_actor", default=None)
@@ -154,16 +176,33 @@ def declared_actor_gucs() -> dict[str, str]:
     return actor.as_gucs()
 
 
-def _validated_actor(tier: str, system: str, *, caller: str) -> ActorRef:
+def _validated_actor(tier: str, system: str, agent: str | None, *, caller: str) -> ActorRef:
     if tier not in VALID_TIERS:
         raise ValueError(f"{caller} tier must be one of {sorted(VALID_TIERS)}; got {tier!r}")
     if not system or not system.strip():
         raise ValueError(f"{caller} requires a non-empty system (who specifically)")
-    return ActorRef(tier=tier, system=system.strip())  # type: ignore[arg-type]
+    cleaned = (agent or "").strip() or None
+    if cleaned is not None:
+        if tier == "human":
+            # The database refuses this pair outright (23514). Refusing it here
+            # too means the door that made the mistake learns at the call site
+            # rather than on whichever write happens to land first.
+            raise ValueError(
+                f"{caller} was given tier='human' AND agent={cleaned!r}. A person's write carries "
+                "no agent: either the person is the author (drop the agent) or the agent is "
+                "(declare tier='ai' and the agent that is running)."
+            )
+        try:
+            UUID(cleaned)
+        except ValueError as exc:
+            raise ValueError(
+                f"{caller} agent must be the uuid of an agent.definition row; got {cleaned!r}"
+            ) from exc
+    return ActorRef(tier=tier, system=system.strip(), agent=cleaned)  # type: ignore[arg-type]
 
 
 @contextmanager
-def declaring_actor(tier: ActorTier, system: str) -> Iterator[ActorRef]:
+def declaring_actor(tier: ActorTier, system: str, agent: str | None = None) -> Iterator[ActorRef]:
     """Synchronous form of :func:`declared_actor` - same ContextVar, no await.
 
     A write door is often a plain function (``queue_message_create``), and the
@@ -173,7 +212,7 @@ def declaring_actor(tier: ActorTier, system: str) -> Iterator[ActorRef]:
     (``matrx_orm.session.op``) and the flush re-declares it per row. Nothing
     here touches a connection.
     """
-    actor = _validated_actor(tier, system, caller="declaring_actor")
+    actor = _validated_actor(tier, system, agent, caller="declaring_actor")
     token = _current_actor.set(actor)
     try:
         yield actor
@@ -182,7 +221,9 @@ def declaring_actor(tier: ActorTier, system: str) -> Iterator[ActorRef]:
 
 
 @asynccontextmanager
-async def declared_actor(tier: ActorTier, system: str) -> AsyncIterator[ActorRef]:
+async def declared_actor(
+    tier: ActorTier, system: str, agent: str | None = None
+) -> AsyncIterator[ActorRef]:
     """Declare the actor for the block WITHOUT opening a transaction.
 
     The declaration is a ContextVar, so the GUCs land when the work inside
@@ -195,9 +236,11 @@ async def declared_actor(tier: ActorTier, system: str) -> AsyncIterator[ActorRef
     transaction, so a chokepoint that opened one would break every handler that
     acts as the user.
     """
-    actor = _validated_actor(tier, system, caller="declared_actor")
+    actor = _validated_actor(tier, system, agent, caller="declared_actor")
     token = _current_actor.set(actor)
-    logger.debug("provenance: declared tier=%s system=%s", actor.tier, actor.system)
+    logger.debug(
+        "provenance: declared tier=%s system=%s agent=%s", actor.tier, actor.system, actor.agent
+    )
     try:
         yield actor
     finally:
@@ -205,6 +248,7 @@ async def declared_actor(tier: ActorTier, system: str) -> AsyncIterator[ActorRef
 
 
 __all__ = [
+    "ACTOR_AGENT_GUC",
     "ACTOR_SYSTEM_GUC",
     "ACTOR_TIER_GUC",
     "VALID_TIERS",

{matrx_orm-3.1.146 → matrx_orm-3.1.148}/matrx_orm/query/executor.py

@@ -32,6 +32,12 @@ _BULK_HYDRATION_THREAD_THRESHOLD = 200
 
 _SKIP_PARAM = object()
 
+# The path field family the `__user_visible` lookup is registered on. The lookup
+# emits `files.is_user_visible_path(<column>)`, an IMMUTABLE predicate over a
+# logical file path; applying it to any other column would test the wrong value,
+# so the lookup raises instead.
+_USER_VISIBLE_PATH_FIELDS = frozenset({"file_path", "folder_path"})
+
 _PARAM_RE = re.compile(r"\$(\d+)")
 # Plain SQL identifier — same trust model as conflict_writes._IDENT_RE. Used for
 # the primary-key name interpolated into the pk-ordered locking sub-select.
@@ -351,6 +357,8 @@ class QueryExecutor:
         "startswith",
         "endswith",
         "exclude",
+        # Path-family predicate lookup (see _USER_VISIBLE_PATH_FIELDS)
+        "user_visible",
         # JSONB operators
         "json_key",
         "json_has_key",
@@ -444,6 +452,41 @@ class QueryExecutor:
             return f"{field} LIKE {placeholder}", f"%{_escape_like(value)}"
         if operator == "exclude":
             return f"{field} != {placeholder}", value
+        if operator == "user_visible":
+            # `file_path__user_visible=True` -> files.is_user_visible_path(file_path) = $n
+            #
+            # ONE EXPRESSION, not merely one rule. Postgres's predicate-implication
+            # prover matches a partial index whose predicate contains a function call
+            # only against the SAME expression in the query: spelling the rule as
+            # `path NOT LIKE 'system-files/%' AND ...` does NOT imply
+            # `files.is_user_visible_path(path)`, so the index is lost (measured live
+            # 2026-09-13: cost 11,177 with Sort+Filter vs 13.83 Index Only Scan for
+            # the identical predicate spelled as the function call). This named lookup
+            # is how every consumer -- the change feed, the tree RPC and both partial
+            # index predicates -- spells one expression. It is NOT a raw-SQL escape
+            # hatch: matrx-orm deliberately has none, and the emitted call is fixed.
+            column = field.rsplit(".", 1)[-1].strip('"')
+            if column not in _USER_VISIBLE_PATH_FIELDS:
+                raise QueryError(
+                    message=(
+                        f"The `__user_visible` lookup is registered on the path field "
+                        f"family {sorted(_USER_VISIBLE_PATH_FIELDS)} and cannot be applied "
+                        f"to {column!r}: files.is_user_visible_path() takes a logical file "
+                        f"path, so applying it to another column would silently test the "
+                        f"wrong value."
+                    ),
+                    details={"query": f"{field} __user_visible"},
+                )
+            if not isinstance(value, bool):
+                raise QueryError(
+                    message=(
+                        f"The `__user_visible` lookup is boolean-valued; got "
+                        f"{type(value).__name__} ({value!r}). Pass True for user-visible "
+                        f"rows or False for their complement."
+                    ),
+                    details={"query": f"{field} __user_visible"},
+                )
+            return f"files.is_user_visible_path({field}) = {placeholder}", value
         # JSONB operators
         if operator == "json_key":
             # value is either a bare key (non-null test) or (key, expected_value)

{matrx_orm-3.1.146 → matrx_orm-3.1.148}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.146"
+version = "3.1.148"
 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.146 → matrx_orm-3.1.148}/tests/level1/test_standalone_write_session_context.py

@@ -79,7 +79,9 @@ async def test_declared_write_keeps_the_queue_and_lands_gucs_in_its_transaction(
         (
             "begin",
             "test",
-            {"app.actor_tier": "ai", "app.actor_system": "tool:instance_create"},
+            # DD-211: the agent is always emitted, empty when no agent is writing, so a
+            # nested declaration can never inherit an outer block's agent.
+            {"app.actor_tier": "ai", "app.actor_system": "tool:instance_create", "app.actor_agent": ""},
         ),
         ("write", "test", "INSERT INTO content_ir.kind_instance DEFAULT VALUES RETURNING id"),
         ("commit", "test"),
@@ -111,7 +113,11 @@ async def test_declared_write_without_a_queue_opens_its_own_transaction(monkeypa
         configure_session_context(None)
 
     assert rows == [{"id": 3}]
-    assert events[0] == ("begin", "test", {"app.actor_tier": "human", "app.actor_system": "user-1"})
+    assert events[0] == (
+        "begin",
+        "test",
+        {"app.actor_tier": "human", "app.actor_system": "user-1", "app.actor_agent": ""},
+    )
     assert events[-1] == ("commit", "test")
 
 

matrx_orm-3.1.148/tests/test_user_visible_lookup.py

@@ -0,0 +1,52 @@
+"""The `__user_visible` path lookup (folder-sync SPEC-SERVER S25).
+
+ONE EXPRESSION, not merely one rule: the change feed, `public.get_user_file_tree`
+and both partial index predicates must spell the visibility rule as the identical
+call `files.is_user_visible_path(<column>)`, because Postgres's predicate-implication
+prover only matches an index predicate containing a function call against the same
+expression. These tests pin the emitted SQL text, so a refactor that "simplifies" the
+lookup into LIKE conjuncts fails here instead of silently losing the index.
+"""
+
+import pytest
+
+from matrx_orm.core.expressions import _parse_lookup_simple
+from matrx_orm.exceptions import QueryError
+from matrx_orm.query.executor import QueryExecutor
+
+
+def test_lookup_is_parsed_as_an_operator_not_a_column():
+    assert QueryExecutor._parse_lookup("file_path__user_visible") == ("file_path", "user_visible")
+    assert _parse_lookup_simple("file_path__user_visible") == ("file_path", "user_visible")
+
+
+@pytest.mark.parametrize(
+    ("field", "expected"),
+    [
+        ("file_path", "files.is_user_visible_path(file_path) = $1"),
+        ("files.files.file_path", "files.is_user_visible_path(files.files.file_path) = $1"),
+        ("folder_path", "files.is_user_visible_path(folder_path) = $1"),
+    ],
+)
+def test_emits_the_predicate_call_verbatim(field, expected):
+    sql, param = QueryExecutor._build_condition(field, "user_visible", True, 1)
+    assert sql == expected
+    assert param is True
+
+
+def test_false_is_the_complement_not_a_negated_spelling():
+    sql, param = QueryExecutor._build_condition("file_path", "user_visible", False, 7)
+    assert sql == "files.is_user_visible_path(file_path) = $7"
+    assert param is False
+
+
+def test_a_non_path_column_raises_instead_of_testing_the_wrong_value():
+    with pytest.raises(QueryError) as exc:
+        QueryExecutor._build_condition("files.files.file_name", "user_visible", True, 1)
+    assert "path field family" in str(exc.value)
+
+
+def test_a_non_boolean_value_raises():
+    with pytest.raises(QueryError) as exc:
+        QueryExecutor._build_condition("file_path", "user_visible", "true", 1)
+    assert "boolean-valued" in str(exc.value)