matrx-orm 3.1.205__tar.gz → 3.1.207__tar.gz

{matrx_orm-3.1.205 → matrx_orm-3.1.207}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.205
+Version: 3.1.207
 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
@@ -26,7 +26,7 @@ Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: cbor2<7,>=6.1.3
 Requires-Dist: cryptography>=43.0
 Requires-Dist: gitpython>=3.1.40
-Requires-Dist: matrx-utils>=2.0.60
+Requires-Dist: matrx-utils>=2.0.61
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

{matrx_orm-3.1.205 → matrx_orm-3.1.207}/matrx_orm/__init__.py

@@ -260,6 +260,9 @@ from .core.relations import ManyToManyField
 from .core.admin_lane import ADMIN_LANE_GUC, admin_lane
 from .core.rls_session import rls_session
 from .core.session_context import (
+    CONVERSATION_GUC,
+    current_conversation,
+    declaring_conversation,
     ACTOR_AGENT_GUC,
     ACTOR_SYSTEM_GUC,
     ACTOR_TIER_GUC,
@@ -711,6 +714,9 @@ __all__ = [
     "ActorTier",
     "canonical_actor_tier",
     "configure_session_context",
+    "CONVERSATION_GUC",
+    "current_conversation",
+    "declaring_conversation",
     "current_actor",
     "current_tier",
     "declared_actor",

{matrx_orm-3.1.205 → matrx_orm-3.1.207}/matrx_orm/core/session_context.py

@@ -214,9 +214,14 @@ def declared_actor_gucs() -> dict[str, str]:
     """The session GUCs the currently declared actor implies.
 
     This is the provider a host passes to :func:`configure_session_context`.
-    Empty when nothing declared an actor: the DB resolver then applies its
-    documented default (``user`` with an identity present, ``system`` without)
-    and logs that it did.
+    Empty when nothing declared an actor: the DB resolver then answers
+    ``system`` (an identity is whose authority the write ran under, never proof
+    a person typed it; only a person's own PostgREST request is ``user`` without
+    a declaration) and logs that it did. On a tier-stamped table an undeclared
+    write under a person's identity is stamped ``system``/``undeclared`` and
+    reported to ``ops.system_error``; one with no identity is refused (23514).
+    So a door that writes for a person declares ``user`` and one that writes
+    for an agent declares ``agent``.
 
     The WORKFLOW CHAIN rides the same provider (it is part of "who is writing":
     the store copies it onto every record-changed event's ``actor.chain``), so a
@@ -227,9 +232,64 @@ def declared_actor_gucs() -> dict[str, str]:
     chain = _current_chain.get()
     if chain is not None:
         out[WORKFLOW_CHAIN_GUC] = chain.as_json()
+    conversation = _current_conversation.get()
+    if conversation is not None:
+        out[CONVERSATION_GUC] = conversation
     return out
 
 
+# ---------------------------------------------------------------------------
+# THE CONVERSATION — which chat conversation the writing agent is in (lane 5
+# VISION-REACH wave 4, 2026-10-02).
+#
+# The store enforces the organization's "Agent changes to this organization's
+# data" setting at its own doors (``custom._agent_change_gate``). Under the
+# default ``ask`` an agent changes freely only a Table it made IN THIS
+# CONVERSATION, so the door has to know the conversation, and the only way a
+# fact reaches a SECURITY DEFINER door is a transaction-local GUC. It rides the
+# same provider as the actor, so every top-level transaction opened inside the
+# declaration carries ``app.conversation_id``. It is an ADDRESS, never
+# authority: it can only ever match a Table the store itself stamped as made in
+# that conversation (``custom.agent_table_origin``).
+# ---------------------------------------------------------------------------
+
+CONVERSATION_GUC = "app.conversation_id"
+
+_current_conversation: ContextVar[str | None] = ContextVar("_declared_conversation", default=None)
+
+
+def current_conversation() -> str | None:
+    """The conversation declared by the innermost open declaration, if any."""
+    return _current_conversation.get()
+
+
+@contextmanager
+def declaring_conversation(conversation_id: str | UUID | None) -> Iterator[str | None]:
+    """Every transaction opened inside this block names ``conversation_id`` to the database.
+
+    ``None`` (or blank) clears an outer declaration for the block: a call that belongs to
+    no conversation must never inherit another one's exemption. A value that is not a
+    uuid is not declared, and says so in the log, because the database would read it as
+    no conversation anyway and a silent drop is how an exemption goes missing unnoticed.
+    """
+    cleaned: str | None = None
+    if conversation_id is not None and str(conversation_id).strip():
+        try:
+            cleaned = str(UUID(str(conversation_id).strip()))
+        except ValueError:
+            logger.warning(
+                "declaring_conversation: %r is not a conversation id (a uuid), so this block "
+                "names no conversation to the database; a Table the agent made in it will "
+                "ask a person under the organization's default setting.",
+                conversation_id,
+            )
+    token = _current_conversation.set(cleaned)
+    try:
+        yield cleaned
+    finally:
+        _current_conversation.reset(token)
+
+
 # ---------------------------------------------------------------------------
 # THE WORKFLOW CHAIN — which workflow run is writing (lane CHAIR-RECORD-CHANGED).
 #
@@ -368,6 +428,7 @@ async def declared_actor(
 
 
 __all__ = [
+    "CONVERSATION_GUC",
     "WORKFLOW_CHAIN_GUC",
     "WorkflowChain",
     "current_workflow_chain",
@@ -391,5 +452,7 @@ __all__ = [
     "declared_actor",
     "declared_actor_gucs",
     "declaring_actor",
+    "current_conversation",
+    "declaring_conversation",
     "session_context_gucs",
 ]

{matrx_orm-3.1.205 → matrx_orm-3.1.207}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.205"
+version = "3.1.207"
 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" }
@@ -41,7 +41,7 @@ dependencies = [
     "gitpython>=3.1.40",
     "psycopg[binary]>=3.2.5",
     "psycopg-pool>=3.2.5",
-    "matrx-utils>=2.0.60",
+    "matrx-utils>=2.0.61",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",