matrx-orm 3.1.72__tar.gz → 3.1.74__tar.gz

{matrx_orm-3.1.72 → matrx_orm-3.1.74}/.gitignore

@@ -218,7 +218,7 @@ frontend/
 # Armani
 .history*
 .history/
-local_data/
+/local_data/
 local_reports_data/
 webscraper/quick_scrapes/temp/
 automation_matrix/ai_apis/fireworks/_dev/*
@@ -248,6 +248,7 @@ requirements_filtered.txt
 
 # Claude Code local worktrees and per-user settings
 .claude/worktrees/
+.worktrees/
 .claude/settings.local.json
 
 # Append-only snapshots from matrx_utils.update_history (unbounded; do not commit)
@@ -283,3 +284,4 @@ db/evidence/
 
 # Pooler contamination evidence — machine-local forensic capture, not source
 db/evidence/
+db/mirror/.env.mirror

{matrx_orm-3.1.72 → matrx_orm-3.1.74}/PKG-INFO

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

@@ -203,6 +203,12 @@ from .core.pool_watch import (
     connection_holder_census,
     register_pool_saturation_sink,
 )
+from .core.pooler_role import (
+    EmptyReadContaminationEvent,
+    PoolerRoleContamination,
+    SessionRoleChangeRefused,
+    register_contamination_sink,
+)
 from .core.pydantic_bridge import (
     validate_input as validate_model_input,
 )
@@ -573,6 +579,11 @@ __all__ = [
     "PoolSaturationEvent",
     "connection_holder_census",
     "register_pool_saturation_sink",
+    # ── Pooler role contamination ──────────────────────────────────────────────
+    "EmptyReadContaminationEvent",
+    "PoolerRoleContamination",
+    "SessionRoleChangeRefused",
+    "register_contamination_sink",
     # ── Signals ────────────────────────────────────────────────────────────────
     "Signal",
     "pre_create",

{matrx_orm-3.1.72 → matrx_orm-3.1.74}/matrx_orm/catalog.py

@@ -26,6 +26,7 @@ __all__ = [
     "softdelete_unique_conflicts",
     "qualified_relation_names",
     "trigger_function_usage",
+    "trigger_column_coverage",
     "column_privileges",
     "entity_capability_state",
 ]
@@ -487,6 +488,51 @@ async def trigger_function_usage(
     )
 
 
+async def trigger_column_coverage(
+    database: str,
+    *,
+    function_name: str,
+    column_names: list[str],
+) -> list[dict[str, Any]]:
+    """Return relations carrying any named column or the named trigger function."""
+    return await _query(
+        database,
+        """
+        WITH column_relations AS (
+          SELECT DISTINCT c.oid,
+                 n.nspname AS schema,
+                 c.relname AS table_name
+          FROM pg_attribute a
+          JOIN pg_class c ON c.oid = a.attrelid
+          JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE a.attname = ANY($2::text[])
+            AND a.attnum > 0
+            AND NOT a.attisdropped
+            AND c.relkind = 'r'
+        ), trigger_relations AS (
+          SELECT DISTINCT t.tgrelid AS oid,
+                 n.nspname AS schema,
+                 c.relname AS table_name
+          FROM pg_trigger t
+          JOIN pg_class c ON c.oid = t.tgrelid
+          JOIN pg_namespace n ON n.oid = c.relnamespace
+          JOIN pg_proc p ON p.oid = t.tgfoid
+          WHERE NOT t.tgisinternal
+            AND p.proname = $1
+        )
+        SELECT COALESCE(cols.schema, triggers.schema) AS schema,
+               COALESCE(cols.table_name, triggers.table_name) AS table_name,
+               (cols.oid IS NOT NULL) AS has_columns,
+               (triggers.oid IS NOT NULL) AS has_trigger
+        FROM column_relations cols
+        FULL OUTER JOIN trigger_relations triggers ON cols.oid = triggers.oid
+        ORDER BY 1, 2
+        """,
+        function_name,
+        column_names,
+    )
+
+
 async def foreign_keys_to_relation(
     database: str,
     *,

{matrx_orm-3.1.72 → matrx_orm-3.1.74}/matrx_orm/core/FEATURE.md

@@ -89,6 +89,10 @@ Verified against code: 2026-08-15.
 
 ## Change log
 
+- 2026-08-16: Kept the destructive transaction-pool contamination proof out of
+  the installable runtime package and isolated it under package tests; the
+  operator wrapper is SQL-free and runtime prose no longer resembles an
+  executable non-local role mutation.
 - 2026-08-15: Pinned transaction-local RLS role cleanup across success,
   exception, and early-return paths.
 - 2026-08-15: Added first-timeout pool holder census, host alarm seam, tracked raw-pool helper, and bounded cancellation-safe release.

{matrx_orm-3.1.72 → matrx_orm-3.1.74}/matrx_orm/core/async_db_manager.py

@@ -18,6 +18,11 @@ from matrx_orm.core.config import (
     resolve_pool_mode,
 )
 from matrx_orm.error_handling import handle_orm_operation
+from matrx_orm.core.pooler_role import (
+    VERIFY_EMPTY_READS,
+    assert_no_session_role_change,
+    reprove_empty_read,
+)
 from matrx_orm.core.tls import resolve_asyncpg_ssl
 from matrx_orm.exceptions import (
     AdapterError,
@@ -327,6 +332,25 @@ class AsyncDatabaseManager:
     _keepalive_tasks: dict[str, asyncio.Task] = {}  # per-config pool warmer
     _growth_locks: dict[str, asyncio.Lock] = {}
 
+    # Config names already resolved as "does an empty read need proving here?".
+    # Only a transaction-mode pool can be handed a server connection another
+    # client left wearing a role, so a direct Postgres pays nothing.
+    _empty_read_verification: dict[str, bool] = {}
+
+    @classmethod
+    def _verifies_empty_reads(cls, config_name: str) -> bool:
+        if not VERIFY_EMPTY_READS:
+            return False
+        cached = cls._empty_read_verification.get(config_name)
+        if cached is not None:
+            return cached
+        try:
+            verifies = resolve_pool_mode(get_database_config(config_name)) == "transaction"
+        except Exception:
+            verifies = False
+        cls._empty_read_verification[config_name] = verifies
+        return verifies
+
     @classmethod
     async def _replace_zero_connection_pool(cls, config_name: str, failed_pool: Any) -> bool:
         """Atomically discard a pool that has lost every physical connection."""
@@ -1025,6 +1049,11 @@ class AsyncDatabaseManager:
         ``.timeout()`` seam for known-long reads. ``None`` keeps the pool
         default.
         """
+        # Layer 1 of the pooler-role defence: SQL that would leave a borrowed role
+        # on a shared server connection never reaches Postgres. See
+        # matrx_orm/core/pooler_role.py for what that contamination does to reads.
+        assert_no_session_role_change(query)
+
         # Reuse the active transaction connection when available
         try:
             from matrx_orm.core.transaction import get_active_connection
@@ -1124,6 +1153,21 @@ class AsyncDatabaseManager:
                                 read_attempt + 1,
                                 query[:120],
                             )
+                        if not results and read_only and cls._verifies_empty_reads(config_name):
+                            # Layer 2: an empty result from a pooled connection is
+                            # unproven until a session that can state its own role
+                            # says so. A borrowed `authenticated` role returns ZERO
+                            # ROWS on an RLS table instead of raising.
+                            true_rows = await reprove_empty_read(
+                                conn,
+                                config_name=config_name,
+                                query=query,
+                                args=args,
+                                statement_timeout=statement_timeout,
+                                normalize=_normalize_record,
+                            )
+                            if true_rows is not None:
+                                return true_rows
                         return [_normalize_record(r) for r in results]
                     except asyncpg.exceptions.PostgresSyntaxError as e:
                         raise QueryError(

matrx_orm-3.1.74/matrx_orm/core/pooler_role.py

@@ -0,0 +1,290 @@
+"""Pooler role contamination — the ORM's two layers against a SILENT empty read.
+
+WHY THIS EXISTS (reproduced 2026-08-15, FOUND_DEFECTS "An ORM read returned ZERO
+ROWS against a table holding 4,060"):
+
+On a transaction-mode pooler (Supavisor / PgBouncer) routing is *per transaction*,
+so consecutive statements from ONE client connection execute on DIFFERENT server
+connections. A server connection that any client on the tenant left with a
+non-LOCAL ``SET ROLE`` comes back out of the shared pool still wearing that role.
+Our statement then runs as ``authenticated`` instead of ``postgres``.
+
+**On an RLS table that GRANTs SELECT to ``authenticated``, that does not raise —
+it returns ZERO ROWS.** Measured live against the platform pooler: a bare
+``SET ROLE authenticated`` issued on 8 connections made 22 of 40 subsequent ORM
+reads of ``seo.backlink_observation`` (4,060 rows) come back empty, with no
+exception, while an identity probe interleaved on the same pool reported
+``current_user=authenticated, session_user=postgres`` on 21 of 40 samples.
+
+Silent emptiness is indistinguishable from "there is no data" for every sweep,
+reconciler, digest and monitor in the platform: a broken read reports a quiet week
+forever and every scheduled run stays green. ``db/pooler_session.py`` already says
+it for the migration tools — **a privilege error must never be recorded as
+absence** — and this module extends that to every ORM read, because a per-caller
+defence does not scale.
+
+TWO INDEPENDENT LAYERS, each sufficient alone, each screaming when it fires:
+
+1. **Prevention — the ORM refuses to emit a session-scoped role change.**
+   ``assert_no_session_role_change`` rejects a bare ``SET ROLE`` /
+   ``SET SESSION AUTHORIZATION`` / ``set_config('role', …, false)`` on every query
+   that goes through the ORM. This closes the one source class the 2026-08-14
+   investigation could never catch statically: SQL authored at RUNTIME — the
+   admin ``sql`` tool, ``db_admin``, registered ``SQLQuery`` objects, agent
+   scratch scripts. ``scripts/check_pooler_role_scope.py`` guards committed code;
+   this guards everything else. The sanctioned ways to change role remain
+   ``matrx_orm.rls_session`` and ``db/pooler_session.py::impersonate``.
+
+2. **Reconciliation — an empty read is re-proved on a session that can prove its
+   role.** A zero-row result from a read-only query on a transaction-pool config
+   is re-run inside an explicit transaction (pinned to ONE server connection)
+   that starts with ``RESET ROLE``. If the rows are really there, the caller gets
+   the TRUE rows and the lie is reported through every registered sink. If the
+   session cannot be made clean, it RAISES rather than handing back an absence.
+
+Layer 2 follows the repo's guard doctrine: a guard that CAN reconcile MUST
+reconcile — we hold the correct answer, so killing the caller's request would be
+strictly worse than returning it loudly. It costs nothing on a non-empty read and
+nothing at all on a direct (session-mode) Postgres connection, where cross-client
+contamination cannot happen.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from collections.abc import Callable
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+from matrx_utils import vcprint
+
+logger = logging.getLogger("matrx_orm.pooler_role")
+
+# Turning this off re-arms a silent-data-loss class platform-wide. It exists so a
+# deployment on a genuinely unshared Postgres can skip the work, and so the cost
+# is a code change (reviewable) rather than an env var (invisible).
+VERIFY_EMPTY_READS = True
+
+# How many times a re-proof may try to obtain a session running as our own login
+# role before it gives up and raises. A contaminated server connection is repaired
+# in-transaction, so one retry is almost always enough.
+REPROVE_ATTEMPTS = 3
+
+# A role change that is NOT scoped to a transaction. ``SET LOCAL ROLE`` and
+# ``set_config('role', …, true)`` are safe and deliberately not matched.
+_NON_LOCAL_SET_ROLE = re.compile(r"(?im)(?:^|;)\s*SET\s+(?!LOCAL\b)ROLE\b")
+_NON_LOCAL_SET_AUTHORIZATION = re.compile(
+    r"(?im)(?:^|;)\s*SET\s+(?!LOCAL\b)SESSION\s+AUTHORIZATION\b"
+)
+_NON_LOCAL_SET_CONFIG_ROLE = re.compile(
+    r"(?is)set_config\s*\(\s*['\"]role['\"]\s*,.*?,\s*(?:false|'false'|\"false\")\s*\)"
+)
+
+# Cheap pre-filter so the overwhelming majority of queries pay a substring scan
+# rather than three regexes. Deliberately loose — a false hint costs microseconds,
+# a missed one costs the platform a silent empty read.
+_ROLE_HINTS = ("role", "authorization", "set_config")
+
+
+class SessionRoleChangeRefused(RuntimeError):
+    """A query tried to change the Postgres role for the whole session."""
+
+
+class PoolerRoleContamination(RuntimeError):
+    """A statement could not be pinned to a session running as our own login role."""
+
+
+class EmptyReadContaminationEvent(BaseModel):
+    """A read returned zero rows because the session was wearing a borrowed role."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    config_name: str
+    query: str
+    contaminated_role: str
+    login_role: str
+    true_row_count: int
+    occurred_at: datetime
+
+
+ContaminationSink = Callable[[EmptyReadContaminationEvent], None]
+
+_sinks: list[ContaminationSink] = []
+
+
+def register_contamination_sink(sink: ContaminationSink) -> None:
+    """Register a durable observer for proven silent-empty reads."""
+    if sink not in _sinks:
+        _sinks.append(sink)
+
+
+def reset_contamination_sinks() -> None:
+    """Clear process state for isolated tests."""
+    _sinks.clear()
+
+
+def assert_no_session_role_change(query: str) -> None:
+    """Refuse SQL that would leave a borrowed role on a pooled server connection.
+
+    Layer 1. Raises ``SessionRoleChangeRefused`` and names the sanctioned path;
+    it never rewrites the caller's SQL, because guessing which role a caller meant
+    is exactly the ambiguity a guard must not resolve on its own.
+    """
+    if not query:
+        return
+    lowered = query.lower()
+    if not any(hint in lowered for hint in _ROLE_HINTS):
+        return
+    if (
+        _NON_LOCAL_SET_ROLE.search(query)
+        or _NON_LOCAL_SET_AUTHORIZATION.search(query)
+        or _NON_LOCAL_SET_CONFIG_ROLE.search(query)
+    ):
+        vcprint(
+            "REFUSED: a session-scoped role change reached the ORM.\n"
+            f"  query: {query[:300]}\n"
+            "  On a transaction pooler this role rides the SHARED server connection "
+            "back into the pool, and the next client — any service on this tenant — "
+            "silently runs as that role. On an RLS table it does not error: it "
+            "returns ZERO ROWS, and absence gets recorded as fact.\n"
+            "  Use `async with rls_session(claims, role=...)` (ORM) or "
+            "`impersonate(conn, role)` (db/pooler_session.py). Both use SET LOCAL "
+            "ROLE inside a transaction and cannot leak.",
+            color="red",
+            style="bold",
+        )
+        raise SessionRoleChangeRefused(
+            "A session-scoped role change (SET ROLE / SET SESSION AUTHORIZATION / "
+            "a non-local set_config role change) may never be executed through the ORM — it "
+            "contaminates the shared pooler and turns other services' reads into "
+            "silent empty results. Use rls_session(...) / impersonate(...), which "
+            "issue SET LOCAL ROLE inside a transaction."
+        )
+
+
+async def emit_contamination(event: EmptyReadContaminationEvent) -> None:
+    """Scream about a proven silent-empty read, durably record it, fan out to sinks."""
+    vcprint(
+        "POOLER ROLE CONTAMINATION — an ORM read returned ZERO ROWS that were "
+        "really there.\n"
+        f"  config: {event.config_name}\n"
+        f"  session ran as: {event.contaminated_role} (login role "
+        f"{event.login_role})\n"
+        f"  true row count on a clean session: {event.true_row_count}\n"
+        f"  query: {event.query[:300]}\n"
+        "  The caller has been given the TRUE rows. Something on this Postgres "
+        "tenant issued a non-LOCAL SET ROLE; every other client is exposed until "
+        "those server connections cycle.",
+        color="red",
+        style="bold",
+    )
+    logger.error(
+        "[pooler-role] silent empty read repaired on %s (ran as %s, %d true rows): %s",
+        event.config_name,
+        event.contaminated_role,
+        event.true_row_count,
+        event.query[:200],
+    )
+    # Durable by default — a host should not have to wire anything for the
+    # platform's loudest data-integrity alarm to survive the process.
+    try:
+        from matrx_orm.session.fallback import record_error
+
+        await record_error(
+            PoolerRoleContamination(
+                f"read returned 0 rows as '{event.contaminated_role}'; "
+                f"{event.true_row_count} rows were really there"
+            ),
+            kind="pooler_role_contamination",
+            source_app="matrx-orm",
+            route=f"orm:{event.config_name}",
+            payload={
+                "config_name": event.config_name,
+                "query": event.query[:2000],
+                "contaminated_role": event.contaminated_role,
+                "login_role": event.login_role,
+                "true_row_count": event.true_row_count,
+            },
+        )
+    except Exception:
+        logger.exception("[pooler-role] could not durably record the contamination event")
+
+    for sink in list(_sinks):
+        try:
+            sink(event)
+        except Exception:
+            logger.exception("[pooler-role] contamination sink raised")
+
+
+async def reprove_empty_read(
+    conn: Any,
+    *,
+    config_name: str,
+    query: str,
+    args: tuple[Any, ...],
+    statement_timeout: float | None,
+    normalize: Callable[[Any], dict[str, Any]],
+) -> list[dict[str, Any]] | None:
+    """Re-run an empty read on a session proven to be running as US.
+
+    Layer 2. Returns the TRUE rows when the empty result was a lie, ``None`` when
+    the read was genuinely empty. Raises ``PoolerRoleContamination`` when a clean
+    session cannot be obtained at all — an unprovable absence is never a result.
+
+    ``conn`` must be a connection not currently inside a transaction; the explicit
+    transaction opened here is what pins every statement below to ONE server
+    connection, which is the only thing that makes ``RESET ROLE`` meaningful.
+    """
+    last_role: tuple[str, str] | None = None
+    for _ in range(REPROVE_ATTEMPTS):
+        async with conn.transaction():
+            await conn.execute("RESET ROLE")
+            identity = await conn.fetchrow("SELECT current_user, session_user")
+            current = identity["current_user"]
+            login = identity["session_user"]
+            if current != login:
+                last_role = (current, login)
+                continue
+            rows = await conn.fetch(query, *args, timeout=statement_timeout)
+            if not rows:
+                return None
+            true_rows = [normalize(r) for r in rows]
+
+        await emit_contamination(
+            EmptyReadContaminationEvent(
+                config_name=config_name,
+                query=query,
+                # The first read ran on a session we could not observe directly;
+                # what we can state is the role it was NOT running as.
+                contaminated_role="<not the login role>" if last_role is None else last_role[0],
+                login_role=login,
+                true_row_count=len(true_rows),
+                occurred_at=datetime.now(UTC),
+            )
+        )
+        return true_rows
+
+    current, login = last_role if last_role is not None else ("<unknown>", "<unknown>")
+    raise PoolerRoleContamination(
+        f"an empty read could not be proved: every attempt to pin a clean session "
+        f"landed as '{current}' (login role '{login}'). Anything this session could "
+        f"not see is a PRIVILEGE failure, not absence. Query: {query[:200]}"
+    )
+
+
+__all__ = [
+    "ContaminationSink",
+    "EmptyReadContaminationEvent",
+    "PoolerRoleContamination",
+    "REPROVE_ATTEMPTS",
+    "SessionRoleChangeRefused",
+    "VERIFY_EMPTY_READS",
+    "assert_no_session_role_change",
+    "emit_contamination",
+    "register_contamination_sink",
+    "reprove_empty_read",
+    "reset_contamination_sinks",
+]

matrx_orm-3.1.74/matrx_orm/schema_builder/FEATURE.md

@@ -0,0 +1,12 @@
+# Schema Builder
+
+The schema builder generates importable models and manager wrappers from live database metadata.
+
+## Manager method names
+
+- A generated manager must never contain duplicate method names; later definitions silently replace earlier behavior in Python.
+- When a table's singular and plural tokens are identical (for example, `entity_grants`), item methods keep the table token and collection methods use the `all_` prefix: `load_entity_grants(...)` and `load_all_entity_grants(...)`.
+- Relation collection wrappers follow the same rule, such as `get_all_entity_grants_with_iam_organizations()`.
+- Generated code must pass Ruff without unused imports or redefined methods.
+
+Guard: `packages/matrx-orm/tests/schema/test_base_generation.py`.

{matrx_orm-3.1.72 → matrx_orm-3.1.74}/matrx_orm/schema_builder/columns.py

@@ -27,6 +27,86 @@ _SQL_DYNAMIC_DEFAULT_KEYWORDS = frozenset(
 )
 
 
+def _parse_array_default(value: str) -> list[object]:
+    """Turn a non-empty PostgreSQL array default into a real Python list.
+
+    Handles the two spellings Postgres reports for the same thing:
+
+        ARRAY['react'::text, 'lucide-react'::text]   →  ['react', 'lucide-react']
+        '{chat_gpt,claude,gemini}'::text[]           →  ['chat_gpt', 'claude', 'gemini']
+
+    Returns ``[]`` for anything it cannot confidently parse — a nested array, a
+    quoted element containing a comma, a function call inside the literal. An
+    empty list is the same conservative answer the generator gave before, and it
+    is deliberately preferred over a half-parsed guess: a WRONG default is worse
+    than an absent one, because it looks authoritative.
+    """
+    text = value.strip()
+
+    if text.startswith("ARRAY["):
+        inner = text[len("ARRAY[") :]
+        close = inner.rfind("]")
+        if close == -1:
+            return []
+        elements = [e.strip() for e in inner[:close].split(",")]
+        # In ARRAY[...] every element is a SQL EXPRESSION, so a bare token is an
+        # identifier or a function call, not a string — refuse the whole default
+        # rather than stringify something the database would evaluate.
+        bare_is_a_string = False
+    else:
+        # '{a,b,c}'::text[] — take what is inside the FIRST quoted run, which is
+        # the array literal itself; everything after it is the cast.
+        open_brace = text.find("{")
+        close_brace = text.rfind("}")
+        if open_brace == -1 or close_brace <= open_brace:
+            return []
+        body = text[open_brace + 1 : close_brace]
+        if not body.strip():
+            return []
+        # A quoted element may legally contain a comma; splitting naively would
+        # invent elements. Refuse rather than guess.
+        if '"' in body:
+            return []
+        elements = [e.strip() for e in body.split(",")]
+        # Inside a curly ARRAY LITERAL an unquoted element IS its literal text —
+        # '{chat_gpt,claude}' means the two strings, not two identifiers. A
+        # numeric-typed array still parses its elements as numbers below.
+        bare_is_a_string = not _array_cast_is_numeric(text)
+
+    parsed: list[object] = []
+    for element in elements:
+        if not element:
+            return []
+        # Strip a per-element cast: 'react'::text → 'react'
+        item = re.sub(r"::[A-Za-z_][A-Za-z0-9_ .]*$", "", element).strip()
+        if item.startswith("'") and item.endswith("'") and len(item) >= 2:
+            parsed.append(item[1:-1].replace("''", "'"))
+            continue
+        try:
+            literal = ast.literal_eval(item)
+        except (ValueError, SyntaxError):
+            if bare_is_a_string:
+                parsed.append(item)
+                continue
+            return []
+        if not isinstance(literal, str | int | float | bool):
+            return []
+        parsed.append(literal)
+    return parsed
+
+
+_NUMERIC_ARRAY_CAST_RE = re.compile(
+    r"::\s*(?:small|big)?int(?:eger)?\d*\s*\[\]$|"
+    r"::\s*(?:numeric|decimal|real|double precision|float\d*)\s*\[\]$",
+    re.IGNORECASE,
+)
+
+
+def _array_cast_is_numeric(value: str) -> bool:
+    """Whether ``'{...}'::<type>[]`` casts to a numeric element type."""
+    return bool(_NUMERIC_ARRAY_CAST_RE.search(value.strip()))
+
+
 def is_sql_expression_default(value: object) -> bool:
     """Return whether a PostgreSQL default must be evaluated by the database."""
     if not isinstance(value, str):
@@ -1068,9 +1148,32 @@ class Column:
             elif value.startswith("ARRAY[]::") and value.endswith("[]"):
                 return {"blank": "[]", "generator": ""}
 
-            # Handle non-empty ARRAY[...] syntax: ARRAY['react'::text, 'lucide-react'::text, ...]
-            elif value.startswith("ARRAY["):
-                return {"blank": "[]", "generator": ""}
+            # 🚨 NON-EMPTY array defaults, BOTH Postgres spellings. Two separate
+            # bugs lived here and both were silent:
+            #
+            #   * ``'{a,b}'::text[]`` (the curly-literal spelling) matched NO
+            #     branch at all and fell through to the scalar handlers, which
+            #     wrapped the whole thing in quotes and emitted
+            #     ``default=''{a,b}'::text[]'`` — a Python SYNTAX ERROR that
+            #     makes the generated models file unimportable for the entire
+            #     repo. It was hand-patched in the output once (2026-08-16,
+            #     seo.ai_visibility_panel.engines) and the very next
+            #     regeneration re-broke it, because the generator was never
+            #     fixed. Patching generated output is not a fix.
+            #   * ``ARRAY['a'::text, 'b'::text]`` DID match, and silently
+            #     returned ``[]`` — so a column whose database default is 13
+            #     values got a Python default of zero values, and a model
+            #     instantiated in code disagreed with every row the DB wrote.
+            #     No error, no log, just a wrong default.
+            #
+            # Both are the same question — "what list does this default mean?" —
+            # so both go through one parser that answers it. Anything it cannot
+            # confidently parse returns an EMPTY list rather than a guess, which
+            # is the pre-existing (conservative) behaviour, never a syntax error.
+            elif value.startswith("ARRAY[") or (
+                value.startswith("'{") and "}'::" in value and value.endswith("[]")
+            ):
+                return {"blank": _parse_array_default(value), "generator": ""}
 
             # Handle simple numeric defaults (no quotes, no casting)
             # This includes integers, decimals, negative numbers, scientific notation