matrx-orm 3.1.48__tar.gz → 3.1.49__tar.gz

{matrx_orm-3.1.48 → matrx_orm-3.1.49}/.gitignore

@@ -38,6 +38,8 @@ lib64/
 # Re-allow them explicitly so frontend builds don't ship without their lib layer.
 !apps/dashboard/src/lib/
 !apps/dashboard/src/lib/**
+!apps/dashboard/src/features/crawler/lib/
+!apps/dashboard/src/features/crawler/lib/**
 !apps/workflow-studio/src/lib/
 !apps/workflow-studio/src/lib/**
 parts/

{matrx_orm-3.1.48 → matrx_orm-3.1.49}/CLAUDE.md

@@ -20,6 +20,7 @@ Every table that becomes a Model needs row identity: a single-column primary key
 ## What this package provides
 
 - **Config / project registry** (`matrx_orm.core.config`): `DatabaseProjectConfig`, `register_database`, `register_database_from_env`, `get_database_config`, `get_manager_config`, `DatabaseRegistry`. A single process can run multiple named database projects concurrently.
+- 🚨 **ONE CONNECTION, REQUIRED** (`matrx_orm.platform_db`): `register_platform_db(name, ...)` + `platform_connection_url()` — the ONLY sanctioned way any Matrx service or package turns env vars into a pool. One set of variables (`SUPABASE_MATRIX_*`), owned here; TLS is a deployment input (`SUPABASE_MATRIX_SSL`), never hardcoded; **RAISES** if it isn't given a database — no degraded mode. Every package's `bootstrap_db()` is one call to it. A package may absolutely run on its OWN Postgres — that is a change of VALUES, never a new variable name; what it may never have is a *second candidate* or a fallback chain. `register_database_from_env` is the low-level primitive underneath — **application and package code must not call it directly** (guard: `scripts/check_one_database.py`, blocking in release).
 - **Core model layer**: `Model`, `BaseManager`, `BaseDTO`, `ModelView`, `model_registry`, plus 50+ field types (`CharField`, `IntegerField`, `ForeignKey`, `ManyToManyField`, `JSONField`, …).
 - **`MatrxEntity`** (`matrx_orm/entity.py`) — **the platform entity contract as an ORM primitive.** A table registered in `platform.entity_types` generates as a `MatrxEntity` (everything else stays a plain `Model`) and gets the behavior instead of every consumer hand-wiring it: `await page.versions()` (not a query on `history.row_versions`), `await page.restore(3)` (not a `version_restore` RPC + a cache bust — `restore()` busts the cache itself), `Note.alive()` / `.dead()` / `.soft_delete()` / `.undelete()`, and `Page.capabilities()`. Capability flags (`_entity_token`, `_is_versioned`, `_has_soft_delete`, `_is_org_scoped`, `_rls_variant`) are **stamped by the generator from the LIVE DATABASE** (does the table really carry the `_version_capture` trigger? a `deleted_at` column?) — never from `entity_types`' own flags, which are wrong on 61 of its 242 rows. **The database is truth; a flag is a claim.** Using a capability an entity does not declare RAISES (`EntityCapabilityError`) and names the fix — it never returns silently-wrong data, and `is_deleted` refuses to answer from a column a partial fetch never loaded. Drift guard: `scripts/check_entity_drift.py` (loud, non-blocking, in `release.sh`).
 - **Change tracking** — every instance records which columns were **loaded** (a SELECTed row, or the caller's kwargs) and which were **changed**. `save()` writes only those, so `.only("id","email")` + `save()` can never NULL the columns it never fetched (it used to — silent data loss). Mutable containers (jsonb/arrays) are always rewritten when loaded, because `obj.metadata["k"]=1` cannot be seen by `__setattr__`; **reassigning** (`obj.metadata = {...}`) is tracked precisely and is the sanctioned way. `Model._hydrate()` is the ONE row→model entry point.
@@ -72,7 +73,7 @@ register_database_from_env(
 
 Inside this package:
 
-- **Never** call `os.environ[...]` outside `config.py` and the `schema_builder` CLI. All env-var reads must go through `register_database_from_env` with an explicit prefix.
+- **Never** call `os.environ[...]` outside `config.py`, `platform_db.py` and the `schema_builder` CLI. All env-var reads go through `register_database_from_env` with an explicit prefix — and for a Matrx service that means `register_platform_database`, never a hand-picked prefix. **Never invent a new env var meaning "the database"** (`*_DATABASE_URL`, `MATRX_*_POSTGRES_*`): the name already exists and is `SUPABASE_MATRIX_*`.
 - The schema-builder tools (`ADMIN_PYTHON_ROOT`, `ADMIN_TS_ROOT`, etc.) MUST accept the same values as function kwargs; env vars are only the fallback for CLI convenience.
 - Transaction default (`MATRX_DEFAULT_DATABASE`) is acceptable but must be overrideable per-call.
 

{matrx_orm-3.1.48 → matrx_orm-3.1.49}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.48
+Version: 3.1.49
 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.48 → matrx_orm-3.1.49}/matrx_orm/__init__.py

@@ -35,8 +35,15 @@ from .core.connections import (
     open_listener_connection,
 )
 from .entity import EntityCapabilityError, MatrxEntity
+from .platform_db import (
+    PLATFORM_DB_ENV_OVERRIDES,
+    PLATFORM_DB_ENV_PREFIX,
+    platform_connection_url,
+    register_platform_db,
+)
 from .core.diagnostics import collect_pool_diagnostics, log_pool_diagnostics
 from .core.introspection import introspect_columns, introspect_rls_policies, schema_exists
+from .core.one_database import OneDatabaseReport, PoolIdentity, audit_one_database
 from .core.listen import notify, ping
 from .core.tls import resolve_asyncpg_ssl, resolve_asyncpg_ssl_from_dsn
 from .operations.bulk_update_values import bulk_update_by_pk
@@ -333,6 +340,10 @@ __all__ = [
     "DatabaseProjectConfig",
     "register_database",
     "register_database_from_env",
+    "register_platform_db",
+    "platform_connection_url",
+    "PLATFORM_DB_ENV_PREFIX",
+    "PLATFORM_DB_ENV_OVERRIDES",
     "register_database_alias",
     "resolve_database_name",
     "is_database_registered",
@@ -358,6 +369,9 @@ __all__ = [
     "EntityCapabilityError",
     "ArrayArg",
     # ── pg_catalog introspection (read-only) ───────────────────────────────────
+    "audit_one_database",
+    "OneDatabaseReport",
+    "PoolIdentity",
     "introspect_columns",
     "introspect_rls_policies",
     "schema_exists",

{matrx_orm-3.1.48 → matrx_orm-3.1.49}/matrx_orm/core/async_db_manager.py

@@ -285,11 +285,37 @@ _init_vector_codec = _init_connection_default
 
 @dataclass(frozen=True, slots=True)
 class ConnectionIdentity:
-    """The role/database a pool is actually connected as."""
+    """The role/database a pool is actually connected as — asked, never assumed.
+
+    ``server_addr`` / ``server_port`` / ``cluster_id`` answer the *physical*
+    question "am I talking to the same Postgres as everyone else?", which env
+    vars cannot answer (a var set on one server and not another is invisible to
+    any static check). ``physical_key`` is the comparable form: two pools with
+    different keys are two different databases, full stop.
+
+    The physical fields are best-effort — a Unix socket has no
+    ``inet_server_addr()`` and ``pg_control_system()`` needs ``pg_monitor`` — so
+    they are optional and the key degrades gracefully rather than lying.
+    """
 
     current_user: str
     session_user: str
     database: str
+    server_addr: str | None = None
+    server_port: int | None = None
+    cluster_id: str | None = None
+
+    @property
+    def physical_key(self) -> str:
+        """The comparable identity of the physical database behind this pool.
+
+        Prefers the cluster's ``system_identifier`` (unique per Postgres data
+        directory) and falls back to the server address/port. The database name
+        is always part of the key: two logical databases in one cluster are still
+        two databases.
+        """
+        cluster = self.cluster_id or f"{self.server_addr or '?'}:{self.server_port or '?'}"
+        return f"{cluster}/{self.database}"
 
 
 class AsyncDatabaseManager:
@@ -518,12 +544,27 @@ class AsyncDatabaseManager:
         async with pool.acquire() as conn:
             row = await conn.fetchrow(
                 "SELECT current_user AS current_user, session_user AS session_user, "
-                "current_database() AS database"
+                "current_database() AS database, "
+                "host(inet_server_addr()) AS server_addr, "
+                "inet_server_port() AS server_port"
             )
+            # The cluster's system_identifier is the strongest physical-identity
+            # signal (unique per data directory) but needs pg_monitor, so it is
+            # best-effort: a NULL here just degrades physical_key to addr:port.
+            cluster_id: str | None = None
+            try:
+                cluster_id = await conn.fetchval(
+                    "SELECT system_identifier::text FROM pg_control_system()"
+                )
+            except Exception:  # noqa: BLE001 — insufficient privilege is normal
+                cluster_id = None
         return ConnectionIdentity(
             current_user=row["current_user"],
             session_user=row["session_user"],
             database=row["database"],
+            server_addr=row["server_addr"],
+            server_port=row["server_port"],
+            cluster_id=cluster_id,
         )
 
     @classmethod

matrx_orm-3.1.49/matrx_orm/core/one_database.py

@@ -0,0 +1,210 @@
+"""ONE DATABASE guard (runtime layer) — do the registered pools actually agree?
+
+There is ONE database. The static twin (``scripts/check_one_database.py`` in the
+host repo) proves the CODE resolves only ``SUPABASE_MATRIX_*``; it cannot see an
+env var set on a server, a pool registered by a caller, or a hostname that points
+somewhere unexpected. This layer asks the connections themselves and compares
+their PHYSICAL identity — cluster ``system_identifier`` (or server address/port)
+plus database name.
+
+WHY (verified 2026-08-09): matrx-scraper's standalone service bound the LIVE,
+shared ``scraper.*`` tables to a Coolify-local Postgres while ``web.*`` went to
+Matrx Main — 14 rows sat in the second database, invisible to the platform, and
+boot logged it as "optional legacy database registered". Two pools in one process
+pointing at two different Postgres instances is the observable signature of that
+bug, and this is the check that would have screamed on the first boot.
+
+Posture (root CLAUDE.md): **scream, never crash.** A divergence is a red banner
+and a durable ops record for the host to file; killing a running service over it
+would trade a silent data split for an outage. Callers that genuinely need a
+second database declare it (``sanctioned_separate``) — aidream's separate CMS
+product database is the only one today.
+
+Usage (host startup, or any standalone package service boot)::
+
+    from matrx_orm.core.one_database import audit_one_database
+
+    report = await audit_one_database(
+        platform_config_name="supabase_automation_matrix",
+        sanctioned_separate=("cms",),
+    )
+    if not report.ok:
+        ...  # persist report.findings() to your ops ledger
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+
+from matrx_utils import vcprint
+
+from matrx_orm.core.async_db_manager import AsyncDatabaseManager, ConnectionIdentity
+
+# How long a single identity probe may take before it is recorded as a failure.
+# A pool that cannot answer "who are you" at boot is itself worth reporting.
+PROBE_TIMEOUT_SECONDS = 20.0
+
+
+@dataclass(frozen=True)
+class PoolIdentity:
+    """One registered matrx-orm config and the physical database it reached."""
+
+    config_name: str
+    identity: ConnectionIdentity | None = None
+    error: str | None = None
+
+    @property
+    def physical_key(self) -> str | None:
+        return self.identity.physical_key if self.identity is not None else None
+
+    def describe(self) -> str:
+        if self.identity is None:
+            return f"{self.config_name}: PROBE FAILED — {self.error}"
+        ident = self.identity
+        where = f"{ident.server_addr or '?'}:{ident.server_port or '?'}"
+        cluster = f" cluster={ident.cluster_id}" if ident.cluster_id else ""
+        return f"{self.config_name}: {ident.database} @ {where}{cluster} as {ident.current_user}"
+
+
+@dataclass(frozen=True)
+class OneDatabaseReport:
+    """The result of comparing every registered pool against the platform pool."""
+
+    platform_config: str
+    platform: PoolIdentity | None
+    pools: list[PoolIdentity] = field(default_factory=list)
+    divergent: list[PoolIdentity] = field(default_factory=list)
+    probe_failures: list[PoolIdentity] = field(default_factory=list)
+    sanctioned_separate: tuple[str, ...] = ()
+
+    @property
+    def ok(self) -> bool:
+        """True when every non-sanctioned pool reached the same physical database."""
+        return (
+            not self.divergent and self.platform is not None and self.platform.identity is not None
+        )
+
+    def findings(self) -> list[dict[str, str]]:
+        """Flat, persistable records — one per divergent pool, for an ops ledger."""
+        platform_key = self.platform.physical_key if self.platform else None
+        out: list[dict[str, str]] = []
+        for pool in self.divergent:
+            out.append(
+                {
+                    "config_name": pool.config_name,
+                    "physical_key": pool.physical_key or "<unknown>",
+                    "platform_config": self.platform_config,
+                    "platform_physical_key": platform_key or "<unknown>",
+                    "detail": pool.describe(),
+                }
+            )
+        return out
+
+    def render_banner(self) -> str:
+        """The red banner text. Names every pool so the split is unmissable."""
+        lines = "\n".join(f"##   {pool.describe()}" for pool in self.pools)
+        platform_key = (self.platform.physical_key if self.platform else None) or "<unknown>"
+        return (
+            "\n"
+            "############################################################################\n"
+            f"##  TWO DATABASES IN ONE PROCESS — {len(self.divergent)} pool(s) do NOT point at\n"
+            f"##  the platform database ({self.platform_config} = {platform_key}).\n"
+            "##  There is ONE database. A pool bound elsewhere means live tables are\n"
+            "##  being written where the platform will never see them (2026-08-09:\n"
+            "##  matrx-scraper wrote 14 rows to a Coolify-local Postgres this way).\n"
+            "##  FIX: resolve every pool from SUPABASE_MATRIX_* — see\n"
+            "##  packages/matrx-scraper/matrx_scraper/db/__init__.py::register_platform_db\n"
+            "############################################################################\n"
+            f"{lines}\n"
+            "############################################################################"
+        )
+
+
+async def _probe(config_name: str) -> PoolIdentity:
+    try:
+        identity = await asyncio.wait_for(
+            AsyncDatabaseManager.connection_identity(config_name),
+            timeout=PROBE_TIMEOUT_SECONDS,
+        )
+    except Exception as exc:  # noqa: BLE001 — a probe never breaks boot
+        return PoolIdentity(config_name=config_name, error=f"{type(exc).__name__}: {exc}")
+    return PoolIdentity(config_name=config_name, identity=identity)
+
+
+async def audit_one_database(
+    *,
+    platform_config_name: str,
+    sanctioned_separate: tuple[str, ...] | list[str] = (),
+    scream: bool = True,
+) -> OneDatabaseReport:
+    """Compare every registered pool's physical database against the platform's.
+
+    Asks each connection who it is (never re-reads env — env is the thing that
+    lied). Returns the report; screams a red banner when pools disagree or the
+    platform pool itself cannot be reached. Never raises.
+
+    ``sanctioned_separate`` names configs that are deliberately a different
+    physical database (aidream's ``cms`` product database). Anything else that
+    diverges is the bug.
+    """
+    from matrx_orm.core.config import get_all_database_project_names, resolve_database_name
+
+    separate = {resolve_database_name(name) for name in sanctioned_separate}
+    platform = resolve_database_name(platform_config_name)
+    names = sorted(set(get_all_database_project_names()))
+
+    probes = await asyncio.gather(*(_probe(name) for name in names))
+    by_name = {probe.config_name: probe for probe in probes}
+    platform_probe = by_name.get(platform)
+
+    platform_key = platform_probe.physical_key if platform_probe else None
+    divergent = [
+        probe
+        for probe in probes
+        if probe.config_name != platform
+        and probe.config_name not in separate
+        and probe.identity is not None
+        and platform_key is not None
+        and probe.physical_key != platform_key
+    ]
+    failures = [probe for probe in probes if probe.identity is None]
+
+    report = OneDatabaseReport(
+        platform_config=platform,
+        platform=platform_probe,
+        pools=list(probes),
+        divergent=divergent,
+        probe_failures=failures,
+        sanctioned_separate=tuple(sorted(separate)),
+    )
+
+    if not scream:
+        return report
+
+    # A pool that cannot answer is an unverified pool — say so every time, not
+    # only on the happy path.
+    for probe in failures:
+        vcprint(f"[one-database] pool probe failed: {probe.describe()}", color="yellow")
+
+    if divergent:
+        vcprint(report.render_banner(), color="red")
+    elif platform_probe is None or platform_probe.identity is None:
+        detail = platform_probe.error if platform_probe else "not registered"
+        vcprint(
+            f"[one-database] cannot verify pool agreement — the platform config "
+            f"{platform!r} did not answer ({detail}). The check is NOT trustworthy "
+            "until it does.",
+            color="red",
+        )
+    else:
+        extra = f" (+{len(separate)} declared-separate)" if separate else ""
+        vcprint(
+            f"[one-database] {len(probes) - len(separate)} pool(s) all resolve the ONE "
+            f"database: {platform_key}{extra}.",
+            color="green",
+        )
+    return report
+
+
+__all__ = ["OneDatabaseReport", "PoolIdentity", "audit_one_database"]

matrx_orm-3.1.49/matrx_orm/platform_db.py

@@ -0,0 +1,138 @@
+"""THE ONE DATABASE — the single place any Matrx package resolves Postgres.
+
+**Read this before you conclude anything about "which database" a package uses.**
+
+There is exactly ONE database per deployment. Every Matrx package — matrx-rag,
+matrx-files, matrx-scraper, matrx-seo, matrx-runtime, and every future one —
+puts its schema in that same Postgres. `rag.*`, `files.*`, `scraper.*`, `web.*`,
+`seo.*`, `runtime.*` are schemas in ONE database, not databases.
+
+WHERE that database lives is a DEPLOYMENT input, not a code decision. Today the
+hosted product points at Supabase (project `txzxabzwovsujtloxrus`); a client who
+wants to own their data points the SAME five variables at THEIR Postgres and the
+entire platform moves with them. That is the whole design: one connection, set
+once, per deployment.
+
+    {PLATFORM_DB_ENV_PREFIX}_HOST
+    {PLATFORM_DB_ENV_PREFIX}_PORT
+    {PLATFORM_DB_ENV_PREFIX}_DATABASE_NAME
+    {PLATFORM_DB_ENV_PREFIX}_USER
+    {PLATFORM_DB_ENV_PREFIX}_PASSWORD
+
+**ONE connection, REQUIRED — never a chain of candidates.** A package takes
+exactly one database connection, from exactly one set of variables. If resolution
+fails, this module RAISES: no degraded mode, no "optional" binding, no quiet
+reach for `DATABASE_URL`, a `<PKG>_DATABASE_URL`, or a `<PKG>_POSTGRES_*` set.
+
+This does NOT mean a package may not own a database. **Every matrx-* package
+ships its own schemas and migrations and can create and run them on a Postgres of
+its own, standalone — that independence is a requirement, never remove it.** What
+a package may not have is a SECOND CANDIDATE for where it connects.
+
+That prohibition is not stylistic — it is the fix for a real incident. Each
+package used to resolve `<PKG>_DATABASE_URL` → `DATABASE_URL` → `<PKG>_POSTGRES_*`.
+Coolify injects a `DATABASE_URL` into every service automatically, so the
+standalone scraper silently bound the LIVE, SHARED `scraper.*` tables to a
+service-local Postgres and wrote 14 rows the platform never saw. A fallback
+ladder does not add resilience; it hands the choice of database to whatever the
+host happens to have set. The defect is the CHAIN, not the destination.
+
+Guard: `scripts/check_one_database.py` fails the build if any package
+reintroduces such a variable. If you are tempted to add one, you want a
+different VALUE for these five variables in that deployment — not a new variable.
+"""
+
+from __future__ import annotations
+
+import os
+from urllib.parse import quote
+
+__all__ = [
+    "PLATFORM_DB_ENV_PREFIX",
+    "PLATFORM_DB_ENV_OVERRIDES",
+    "platform_connection_url",
+    "register_platform_db",
+]
+
+# The ONE database's env prefix. Historical name — it predates the platform
+# being Postgres-agnostic and says nothing about the engine. Any Postgres works.
+PLATFORM_DB_ENV_PREFIX = "SUPABASE_MATRIX"
+
+# `..._DATABASE_NAME` rather than the default `..._NAME`, because `..._NAME` is
+# already used elsewhere to mean "name of a registered matrx-orm config".
+PLATFORM_DB_ENV_OVERRIDES = {"NAME": "SUPABASE_MATRIX_DATABASE_NAME"}
+
+
+def _missing_env_message(package: str) -> str:
+    who = f"{package}: " if package else ""
+    return (
+        f"{who}cannot resolve the platform database — set "
+        f"{PLATFORM_DB_ENV_PREFIX}_HOST/_PORT/_DATABASE_NAME/_USER/_PASSWORD. "
+        "These five variables ARE the database: point them at Supabase, at a "
+        "client's Postgres, or at a local instance. There is exactly one "
+        "database connection per deployment — one set of variables, required. "
+        "There is no second candidate to try, and adding one would let the host "
+        "silently decide which database this package lands in."
+    )
+
+
+def platform_connection_url(*, package: str = "") -> str:
+    """Build the ONE database's connection URL for ad-hoc / migration use.
+
+    Raises ``RuntimeError`` if the five variables are not fully set. There is
+    deliberately no fallback — see the module docstring.
+    """
+    host = os.environ.get(f"{PLATFORM_DB_ENV_PREFIX}_HOST")
+    user = os.environ.get(f"{PLATFORM_DB_ENV_PREFIX}_USER")
+    password = os.environ.get(f"{PLATFORM_DB_ENV_PREFIX}_PASSWORD")
+    database = os.environ.get(PLATFORM_DB_ENV_OVERRIDES["NAME"]) or "postgres"
+    port = os.environ.get(f"{PLATFORM_DB_ENV_PREFIX}_PORT") or "5432"
+
+    if not (host and user and password):
+        raise RuntimeError(_missing_env_message(package))
+
+    return (
+        f"postgresql://{quote(user, safe='')}:{quote(password, safe='')}"
+        f"@{host}:{port}/{database}"
+    )
+
+
+def register_platform_db(
+    name: str,
+    *,
+    additional_schemas: list[str],
+    pool_min: int = 1,
+    pool_max: int = 5,
+    ssl: object | None = None,
+    package: str = "",
+) -> None:
+    """Register matrx-orm config ``name`` against the ONE database.
+
+    ``name`` is a matrx-orm *config name* (e.g. ``"matrx_rag"``), NOT a
+    database — every package's models bake a config name so a host can alias it
+    onto an already-open pool. This function is what standalone boot calls when
+    no host did that.
+
+    ``ssl`` defaults to ``None``, which lets ``{PREFIX}_SSL`` decide (matrx-orm
+    itself defaults to ``"require"``). That is what makes a plain local or
+    client-owned Postgres reachable: set ``SUPABASE_MATRIX_SSL=disable``. Do not
+    hardcode a TLS posture here.
+
+    Idempotent. Raises ``RuntimeError`` if the environment is incomplete.
+    """
+    from matrx_orm import is_database_registered, register_database_from_env
+
+    if is_database_registered(name):
+        return
+
+    ok = register_database_from_env(
+        name=name,
+        env_prefix=PLATFORM_DB_ENV_PREFIX,
+        additional_schemas=additional_schemas,
+        env_var_overrides=dict(PLATFORM_DB_ENV_OVERRIDES),
+        pool_min=pool_min,
+        pool_max=pool_max,
+        ssl=ssl,
+    )
+    if not ok:
+        raise RuntimeError(_missing_env_message(package))

{matrx_orm-3.1.48 → matrx_orm-3.1.49}/matrx_orm/query/FEATURE.md

@@ -15,3 +15,11 @@ process identity cache.
 `True` for compatibility. The cache bypass controls only cache population; it
 does not weaken database authorization, filters, hydration, or transaction
 semantics.
+
+## Aggregate projections
+
+A scalar `.aggregate(...)` projects only its aggregate expressions. It never
+inherits the model query's default `*` projection. A grouped aggregate with no
+explicit `.values(...)` projects the grouped columns plus its aggregate
+expressions. These shapes keep every generated aggregate valid in PostgreSQL
+without forcing callers to add a redundant projection.

{matrx_orm-3.1.48 → matrx_orm-3.1.49}/matrx_orm/query/executor.py

@@ -583,6 +583,12 @@ class QueryExecutor:
                             reason="group_by() entries require a column name or typed expression",
                             details={"entry": repr(f)},
                         )
+            elif aggregations:
+                # A scalar aggregate owns the entire projection. Keeping the
+                # default ``*`` would emit ``SELECT *, COUNT(...)`` and make
+                # Postgres require every model column in a nonexistent GROUP
+                # BY clause.
+                pass
             elif select_related or explicit_joins:
                 # Need explicit table prefix to avoid ambiguity with joined columns
                 select_parts.insert(0, f"{self._base_ref()}.*")

{matrx_orm-3.1.48 → matrx_orm-3.1.49}/matrx_orm/secrets_battery/crypto.py

@@ -4,7 +4,7 @@ Fernet, keyed by ``CREDENTIALS_ENCRYPTION_KEY``. Every package and every
 deployment that reads or writes encrypted credentials holds the SAME key and
 uses THIS module — there is no privileged decryptor anywhere, and no second
 Fernet instance may ever be created (`aidream.services.user_secrets.encryption`
-and `aidream.services.scraper.credentials` delegate here).
+and `aidream.services.web_credentials.credentials` delegate here).
 
 Key resolution (identical to the historical aidream implementation so every
 existing ciphertext keeps decrypting):

{matrx_orm-3.1.48 → matrx_orm-3.1.49}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.48"
+version = "3.1.49"
 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.48 → matrx_orm-3.1.49}/tests/level1/test_join_and_aggregate.py

@@ -307,12 +307,20 @@ class TestBaseManagerAggregate:
         # before terminating. (aggregate() on the builder also accepts kw.)
         qb = qb.annotate(total=Sum("amount"), n=Count("id"))
         sql, params = QueryExecutor(qb._build_query())._build_query()
+        assert "SELECT *" not in sql.split(" FROM ")[0]
         assert "SUM(amount) AS total" in sql
         assert "COUNT(id) AS n" in sql
         assert "FROM orders" in sql
         assert "WHERE status = $1" in sql
         assert params == ["paid"]
 
+    def test_aggregate_composite_distinct_has_no_model_projection(self):
+        CE = _make_chunk_entity_model()
+        qb = CE.filter().annotate(pairs=Count("entity_id", "chunk_id", distinct=True))
+        sql, _ = QueryExecutor(qb._build_query())._build_query()
+        select_clause = sql.split(" FROM ")[0]
+        assert select_clause == "SELECT COUNT(DISTINCT (entity_id, chunk_id)) AS pairs"
+
 
 class TestValuesDeduplicatesAnnotateAliases:
     """Regression: ``.values("col", "alias")`` after ``.annotate(alias=Count())``

matrx_orm-3.1.49/tests/test_one_database.py

@@ -0,0 +1,105 @@
+"""THE ONE DATABASE — pin the single resolver every Matrx package shares.
+
+These tests fail if someone reintroduces a way for one package's schema to land
+in a different Postgres than the rest of the platform.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from matrx_orm import platform_db
+
+REPO = Path(__file__).resolve().parents[3]
+
+# Every retired per-package connection variable. None of these may ever again
+# influence where a schema lands.
+RETIRED_VARS = [
+    "DATABASE_URL",
+    "RAG_DATABASE_URL",
+    "FILES_DATABASE_URL",
+    "RUNTIME_DATABASE_URL",
+    "SCRAPER_DATABASE_URL",
+    "MATRX_RAG_POSTGRES_HOST",
+    "MATRX_FILES_POSTGRES_HOST",
+    "MATRX_RUNTIME_POSTGRES_HOST",
+    "MATRX_SCRAPER_POSTGRES_HOST",
+]
+
+
+def _clear_platform_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    for suffix in ("HOST", "PORT", "USER", "PASSWORD", "DATABASE_NAME"):
+        monkeypatch.delenv(f"SUPABASE_MATRIX_{suffix}", raising=False)
+
+
+def test_connection_url_ignores_every_retired_second_database_var(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A service-local Postgres URL must NOT be able to fork a live schema."""
+    _clear_platform_env(monkeypatch)
+    for var in RETIRED_VARS:
+        monkeypatch.setenv(var, "postgresql://a:b@rogue-postgres.internal:5434/rogue")
+
+    with pytest.raises(RuntimeError) as exc:
+        platform_db.platform_connection_url(package="matrx-test")
+
+    # It raises rather than silently binding to the rogue host, and the message
+    # tells the reader what the ONE database actually is.
+    assert "rogue-postgres" not in str(exc.value)
+    assert "SUPABASE_MATRIX_HOST" in str(exc.value)
+
+
+def test_connection_url_builds_from_the_five_platform_vars(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("SUPABASE_MATRIX_HOST", "db.example.com")
+    monkeypatch.setenv("SUPABASE_MATRIX_PORT", "6543")
+    monkeypatch.setenv("SUPABASE_MATRIX_USER", "svc")
+    monkeypatch.setenv("SUPABASE_MATRIX_PASSWORD", "p@ss/word")
+    monkeypatch.setenv("SUPABASE_MATRIX_DATABASE_NAME", "postgres")
+
+    url = platform_db.platform_connection_url()
+
+    # Password is URL-quoted, not naively interpolated.
+    assert url == "postgresql://svc:p%40ss%2Fword@db.example.com:6543/postgres"
+
+
+def test_a_client_owned_postgres_is_just_different_values(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The whole point: relocating the platform is a VALUE change, not a new var."""
+    monkeypatch.setenv("SUPABASE_MATRIX_HOST", "localhost")
+    monkeypatch.setenv("SUPABASE_MATRIX_PORT", "5432")
+    monkeypatch.setenv("SUPABASE_MATRIX_USER", "postgres")
+    monkeypatch.setenv("SUPABASE_MATRIX_PASSWORD", "postgres")
+    monkeypatch.setenv("SUPABASE_MATRIX_DATABASE_NAME", "matrx")
+
+    assert (
+        platform_db.platform_connection_url()
+        == "postgresql://postgres:postgres@localhost:5432/matrx"
+    )
+
+
+def test_register_platform_db_leaves_tls_to_the_deployment() -> None:
+    """ssl defaults to None so SUPABASE_MATRIX_SSL governs — a local Postgres
+    with TLS off must remain reachable."""
+    import inspect
+
+    sig = inspect.signature(platform_db.register_platform_db)
+    assert sig.parameters["ssl"].default is None
+
+
+def test_repo_guard_reports_clean() -> None:
+    """The build-blocking guard must pass on the current tree."""
+    script = REPO / "scripts" / "check_one_database.py"
+    if not script.exists():  # package used outside the monorepo
+        pytest.skip("monorepo guard script not present")
+
+    result = subprocess.run(
+        [sys.executable, str(script)], capture_output=True, text=True, cwd=REPO
+    )
+    assert result.returncode == 0, result.stdout + result.stderr