matrx-orm 3.1.196__tar.gz → 3.1.197__tar.gz

{matrx_orm-3.1.196 → matrx_orm-3.1.197}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.196
+Version: 3.1.197
 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.57
+Requires-Dist: matrx-utils>=2.0.58
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

{matrx_orm-3.1.196 → matrx_orm-3.1.197}/matrx_orm/platform_access.py

@@ -350,7 +350,7 @@ class EdgeAccessRequirement:
 #: the same authority as sharing — editor on both ends.
 CONVEYING_EDGE = EdgeAccessRequirement((("editor", "editor"),))
 
-#: An ordinary edge: authority over one end, visibility of the other.
+#: An ordinary edge: authority over one end, view access to the other.
 NON_CONVEYING_EDGE = EdgeAccessRequirement((("editor", "viewer"), ("viewer", "editor")))
 
 #: Fail-safe for an unregistered pair: assume it conveys. An edge type nobody

{matrx_orm-3.1.196 → matrx_orm-3.1.197}/matrx_orm/schema_builder/diff_preview.py

@@ -724,6 +724,7 @@ def preview_schema_changes(
     from dotenv import load_dotenv
     from matrx_orm.core.config import register_database_from_env
     from matrx_orm.schema_builder.common import DEBUG_CONFIG, OutputConfig
+    from matrx_orm.schema_builder.schema import entry_manager_flags
     from matrx_orm.schema_builder.schema_manager import SchemaManager
 
     caller_dir = Path(sys.argv[0]).parent.resolve()
@@ -794,7 +795,7 @@ def preview_schema_changes(
         schema_name = entry.get("schema", "public")
         include_tables = entry.get("include_tables") or None
         exclude_tables = entry.get("exclude_tables") or None
-        manager_flags = entry.get("manager_flags") or None
+        manager_flags = entry_manager_flags(cfg, entry)
 
         manager = SchemaManager(
             schema=schema_name,

{matrx_orm-3.1.196 → matrx_orm-3.1.197}/matrx_orm/schema_builder/runner.py

@@ -25,6 +25,7 @@ from matrx_orm.schema_builder.common import (
     OutputConfig,
 )
 from matrx_orm.schema_builder.helpers.git_checker import check_git_status
+from matrx_orm.schema_builder.schema import entry_manager_flags
 from matrx_orm.schema_builder.schema_manager import SchemaManager
 
 
@@ -355,7 +356,7 @@ def run_schema_generation(
 
         # manager_flags: yaml-level defaults for all tables in this generation run.
         # Per-table manager_config_overrides (from the databases section) stack on top.
-        manager_flags = entry.get("manager_flags") or None
+        manager_flags = entry_manager_flags(cfg, entry)
 
         # skip_unchanged_managers: when True, manager files for tables whose
         # model definition has not changed are not rewritten. Default False

{matrx_orm-3.1.196 → matrx_orm-3.1.197}/matrx_orm/schema_builder/schema.py

@@ -39,6 +39,27 @@ _MANAGER_FLAG_DEFAULTS: dict = {
 }
 
 
+# Generation-wide list of column names that never get generated filter helpers
+# (``load_*/filter_*_by_<column>`` manager methods and their ``filter_fields``
+# entry). Declared once at the top level of matrx_orm.yaml as
+# ``never_filter_columns: [...]``; a host uses it for a column it is retiring,
+# so no new code gains a helper that filters on it while the column still exists
+# (the model field stays until the column is dropped).
+NEVER_FILTER_COLUMNS_KEY = "never_filter_columns"
+EXCLUDE_FILTER_FIELDS_FLAG = "exclude_filter_fields"
+
+
+def entry_manager_flags(cfg: dict, entry: dict) -> dict | None:
+    """The manager flags for one ``generate[]`` entry: its own ``manager_flags``
+    plus the config-wide ``never_filter_columns`` as ``exclude_filter_fields``."""
+    flags = dict(entry.get("manager_flags") or {})
+    never = [str(c) for c in (cfg.get(NEVER_FILTER_COLUMNS_KEY) or [])]
+    if never:
+        own = list(flags.get(EXCLUDE_FILTER_FIELDS_FLAG) or [])
+        flags[EXCLUDE_FILTER_FIELDS_FLAG] = sorted(set(own) | set(never))
+    return flags or None
+
+
 class Schema:
     def __init__(
         self,

{matrx_orm-3.1.196 → matrx_orm-3.1.197}/matrx_orm/schema_builder/tables.py

@@ -1215,7 +1215,16 @@ class Table:
         MANAGER_CONFIG_OVERRIDES = get_manager_config(self.database_project)
 
         relations = self.get_all_relations_list()
-        filter_fields = [column.name for column in self.columns if column.is_default_filter_field]
+        # exclude_filter_fields is an input to this method, never a generated
+        # config key: it removes columns from filter_fields and is dropped from
+        # the flags merged below (see schema.entry_manager_flags).
+        global_manager_flags = dict(global_manager_flags or {})
+        excluded_filter_fields = set(global_manager_flags.pop("exclude_filter_fields", None) or ())
+        filter_fields = [
+            column.name
+            for column in self.columns
+            if column.is_default_filter_field and column.name not in excluded_filter_fields
+        ]
 
         m2m_config = self.to_python_many_to_many_config()
         m2m_relations = list(m2m_config.keys()) if m2m_config else None

{matrx_orm-3.1.196 → matrx_orm-3.1.197}/matrx_orm/session/telemetry.py

@@ -9,7 +9,7 @@ Emits structured telemetry at the Session boundary so operators can see:
 
 The OTel SDK is an OPTIONAL dependency. If ``opentelemetry`` isn't
 installed, every emit is a no-op. matrx-utils ``vcprint`` continues to
-provide dev-mode visibility regardless.
+provide dev-mode insight regardless.
 
 Wired up by ``matrx_orm.configure_session(...)`` which the host calls
 at startup. No-op when not configured.

{matrx_orm-3.1.196 → matrx_orm-3.1.197}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.196"
+version = "3.1.197"
 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.57",
+    "matrx-utils>=2.0.58",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",

{matrx_orm-3.1.196 → matrx_orm-3.1.197}/tests/level1/test_query_executor_sql.py

@@ -150,10 +150,10 @@ class TestBuildCondition:
         executor._full_query_dict = {"table": "workflow.definition", "joins": []}
         params = []
 
-        sql = executor._render_q(Q(visibility__in=("internal", "link", "public")), params)
+        sql = executor._render_q(Q(status__in=("queued", "running", "done")), params)
 
-        assert sql == "visibility = ANY($1)"
-        assert params == [("internal", "link", "public")]
+        assert sql == "status = ANY($1)"
+        assert params == [("queued", "running", "done")]
 
     def test_nin(self):
         sql, val = QueryExecutor._build_condition("status", "nin", ["failed", "canceled"], 2)

matrx_orm-3.1.197/tests/schema_builder/test_never_filter_columns.py

@@ -0,0 +1,70 @@
+"""A column named in ``never_filter_columns`` gets no generated filter helpers.
+
+A host retiring a column (aidream: access ladder T-13) lists it once at the top
+of matrx_orm.yaml. Every ``generate[]`` entry then leaves it out of the manager's
+``filter_fields`` — so no ``load_*/filter_*_by_<column>`` methods and no
+``filter_fields`` entry in the auto_config — while the model field itself is
+still generated. The flag is an input, never a key written into the auto_config
+(it would also reach ``generate_manager_class`` as an unknown keyword).
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import matrx_orm.schema_builder.tables as tables_mod
+from matrx_orm.schema_builder.schema import entry_manager_flags
+from matrx_orm.schema_builder.tables import Table
+
+
+def test_config_wide_list_reaches_every_entry() -> None:
+    cfg = {"never_filter_columns": ["retired_col"]}
+    assert entry_manager_flags(cfg, {}) == {"exclude_filter_fields": ["retired_col"]}
+    merged = entry_manager_flags(cfg, {"manager_flags": {"include_filter_fields": True, "exclude_filter_fields": ["other"]}})
+    assert merged == {"include_filter_fields": True, "exclude_filter_fields": ["other", "retired_col"]}
+
+
+def test_no_list_changes_nothing() -> None:
+    assert entry_manager_flags({}, {}) is None
+    assert entry_manager_flags({}, {"manager_flags": {"include_filter_fields": False}}) == {"include_filter_fields": False}
+
+
+def _fake_table() -> SimpleNamespace:
+    def col(name: str, filt: bool) -> SimpleNamespace:
+        return SimpleNamespace(name=name, is_default_filter_field=filt)
+
+    return SimpleNamespace(
+        database_project="p",
+        schema="s",
+        name="thing",
+        name_plural="things",
+        name_snake="thing",
+        python_model_name="Thing",
+        models_module_prefix="db",
+        columns=[col("status", True), col("retired_col", True), col("title", False)],
+        get_all_relations_list=lambda: [],
+        to_python_many_to_many_config=lambda: None,
+    )
+
+
+def _render(monkeypatch, flags):
+    seen: dict = {}
+    monkeypatch.setattr(tables_mod, "get_manager_config", lambda _p: {})
+    monkeypatch.setattr(tables_mod, "get_database_alias", lambda _p: "p")
+    monkeypatch.setattr(tables_mod, "generate_manager_class", lambda **kw: seen.update(kw) or "")
+    monkeypatch.setattr(tables_mod, "generate_dto_and_manager", lambda *_a: "")
+    table = _fake_table()
+    Table.to_python_manager_string(table, flags)
+    return table.base_class_auto_config, seen
+
+
+def test_listed_column_gets_no_filter_helpers(monkeypatch) -> None:
+    config, kwargs = _render(monkeypatch, entry_manager_flags({"never_filter_columns": ["retired_col"]}, {}))
+    assert config["filter_fields"] == ["status"]
+    assert "exclude_filter_fields" not in config
+    assert "exclude_filter_fields" not in kwargs
+
+
+def test_without_the_list_the_column_is_a_filter_field(monkeypatch) -> None:
+    config, _ = _render(monkeypatch, None)
+    assert config["filter_fields"] == ["status", "retired_col"]

{matrx_orm-3.1.196 → matrx_orm-3.1.197}/tests/session/test_session.py

@@ -246,7 +246,7 @@ async def test_pending_op_for_row_returns_latest(FakeMessage):
 
 
 # ---------------------------------------------------------------------------
-# Stack-walk pending visibility — the contract behind pending-aware reads
+# Stack-walk pending-op view — the contract behind pending-aware reads
 # for nested (child-agent) Sessions. A child Session MUST see ops its
 # ancestors queued-but-didn't-flush, or it re-INSERTs a reserved row and
 # the two coordinators collide on the PK at flush.

{matrx_orm-3.1.196 → matrx_orm-3.1.197}/tests/test_user_visible_lookup.py

@@ -1,7 +1,7 @@
 """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
+and both partial index predicates must spell the user-visible 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