matrx-orm 3.1.22__tar.gz → 3.1.24__tar.gz

{matrx_orm-3.1.22 → matrx_orm-3.1.24}/CLAUDE.md

@@ -32,6 +32,7 @@ Every table that becomes a Model needs row identity: a single-column primary key
 - **Adapters**: `AsyncPostgreSQLAdapter`, `SupabaseAdapter`, `PostgRESTClientAdapter`.
 - **Signals**: `pre_create`, `post_create`, `pre_save`, `post_save`, `pre_delete`, `post_delete`.
 - **Schema builder** (`matrx_orm.schema_builder`): code generation for Python + TypeScript type definitions from the DB schema. Postgres **VIEWs** are emitted as **read-only `Model` classes** into the same schema models file (on by default; per-entry `output.include_views: false` opts a schema out, `output.exclude_views: [...]` skips individual views). View models get no manager/DTO/base-class/auto_config (views are not writable), synthesize `_primary_keys` from an `id` column (else the first column, for cache-key/`load_by_id` only), and emit plain typed fields with **no `ForeignKey`** (views carry no FK metadata — nothing cross-schema to resolve). Never hand-write a view model again.
+- **Secrets battery** (`matrx_orm.secrets`): the ONE canonical user-credential vault — `users.user_secrets` CRUD + the platform's single Fernet primitive, keyed by `CREDENTIALS_ENCRYPTION_KEY`. Any package: `configure_secrets(db_config_name=...)` once, then `await require_user_secret(user_id, key)`. No package ever calls another service to resolve a credential. Contract: [`matrx_orm/secrets/FEATURE.md`](matrx_orm/secrets/FEATURE.md).
 - **Polymorphic associations** (`matrx_orm.associations`): `EntityRegistry` (token→Model) + `Associations` — a registry-driven, **ownership-gated** edge engine over a host's polymorphic edge table. Every `source→target` hop is org-scoped *and* the resolved target's `org_id` is re-verified (fail-closed, screams on mismatch), so a hop can't widen access past the tenant boundary. Hardcodes no table names — the host wires its own edge + token-registry models.
 
 Public API is defined explicitly in `matrx_orm/__init__.py` (100+ exports). Treat changes there as semver-breaking.
@@ -98,6 +99,15 @@ uv run pytest packages/matrx-orm/tests
 
 Tests must run against a Postgres instance the developer provides (or a testcontainers-based fixture). No sibling matrx package is needed. If a test needs `matrx-connect`, that's a sign the test is in the wrong package.
 
+Host generators may expose a focused schema pass by forwarding
+`only_schemas={...}` to `run_schema_generation`; aidream's focused package-model
+command is `uv run python db/generate.py --schema <schema> --models-only`.
+`models_only=True` skips unrelated schema/type/helper outputs but still performs
+live introspection and writes the canonical generated Model file. The unfiltered
+command remains the release-wide regeneration path. A package target may declare
+`dependency_schemas` in `db/matrx_orm.yaml`; a focused pass then introspects only
+the target and those explicitly named cross-schema FK dependencies.
+
 ---
 
 ## Known issues

{matrx_orm-3.1.22 → matrx_orm-3.1.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.22
+Version: 3.1.24
 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
@@ -23,6 +23,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
 Requires-Dist: asyncpg>=0.31.0
+Requires-Dist: cryptography>=43.0
 Requires-Dist: gitpython>=3.1.40
 Requires-Dist: matrx-utils>=1.0.20
 Requires-Dist: psycopg-pool>=3.2.5

{matrx_orm-3.1.22 → matrx_orm-3.1.24}/matrx_orm/operations/conflict.py

@@ -40,6 +40,29 @@ Example::
 from __future__ import annotations
 
 from dataclasses import dataclass
+import re
+from typing import Any
+
+
+_IDENTIFIER_RE = re.compile(r"^[a-z_][a-z0-9_]*$")
+
+
+def _identifier(value: str) -> str:
+    if not _IDENTIFIER_RE.fullmatch(value):
+        raise ValueError(f"ConflictTarget column must be a simple identifier: {value!r}")
+    return value
+
+
+def _literal(value: Any) -> str:
+    if value is None:
+        return "NULL"
+    if isinstance(value, bool):
+        return "TRUE" if value else "FALSE"
+    if isinstance(value, int | float):
+        return str(value)
+    if isinstance(value, str):
+        return "'" + value.replace("'", "''") + "'"
+    raise TypeError(f"Unsupported ConflictTarget literal: {type(value).__name__}")
 
 
 @dataclass(frozen=True)
@@ -83,5 +106,36 @@ class ConflictTarget:
                     "ConflictTarget(where=...) must be a non-empty string when provided"
                 )
 
+    @classmethod
+    def partial(
+        cls,
+        columns: list[str] | tuple[str, ...],
+        *,
+        coalesce: dict[str, Any] | None = None,
+        where_is_null: tuple[str, ...] = (),
+        where_is_not_null: tuple[str, ...] = (),
+        where_equals: dict[str, Any] | None = None,
+    ) -> ConflictTarget:
+        """Build an expression/partial-index target without SQL at call sites."""
+        coalesce = coalesce or {}
+        unknown = set(coalesce) - set(columns)
+        if unknown:
+            raise ValueError(f"coalesce columns are not in conflict target: {sorted(unknown)}")
+        expressions = [
+            f"COALESCE({_identifier(column)}, {_literal(coalesce[column])})"
+            if column in coalesce
+            else _identifier(column)
+            for column in columns
+        ]
+        predicates = [f"{_identifier(column)} IS NULL" for column in where_is_null]
+        predicates.extend(
+            f"{_identifier(column)} IS NOT NULL" for column in where_is_not_null
+        )
+        predicates.extend(
+            f"{_identifier(column)} = {_literal(value)}"
+            for column, value in (where_equals or {}).items()
+        )
+        return cls(expressions=expressions, where=" AND ".join(predicates) or None)
+
 
 __all__ = ["ConflictTarget"]

{matrx_orm-3.1.22 → matrx_orm-3.1.24}/matrx_orm/query/executor.py

@@ -168,6 +168,15 @@ def _shift_param_refs(sql: str, delta: int) -> str:
     return "".join(out)
 
 
+def _render_update_expression(value: Any, params: list[Any]) -> str:
+    """Render an expression after existing SET params without reusing $1..$N."""
+    sub_params: list[Any] = []
+    sql = value.as_sql(sub_params)
+    sql = _shift_param_refs(sql, len(params))
+    params.extend(sub_params)
+    return sql
+
+
 # Postgres' wire protocol caps a single statement at 65535 bind parameters and
 # asyncpg enforces a 32767 (int16) limit. We chunk bulk writes well under that
 # so the per-row column count never pushes a batch over the edge.
@@ -417,7 +426,7 @@ class QueryExecutor:
             return f"{field} <@ {placeholder}::jsonb", v
         if operator == "json_path":
             # field #>> '{key1,key2}' = $1  (value is (path_tuple, expected))
-            if isinstance(value, (list, tuple)):
+            if isinstance(value, list | tuple):
                 path = "{" + ",".join(str(p) for p in value) + "}"
                 return f"{field} #>> {placeholder}", path
             return f"{field} #>> {placeholder}", str(value)
@@ -581,7 +590,7 @@ class QueryExecutor:
         for agg in aggregations:
             name = agg["name"]
             func = agg["function"]
-            if isinstance(func, (_Subquery, _Exists)):
+            if isinstance(func, _Subquery | _Exists):
                 # Correlated scalar subquery in the SELECT list — its as_sql needs
                 # the OUTER table so OuterRef("x") resolves to <table>.x. Params land
                 # here (SELECT position, before WHERE) — correct textual order.
@@ -656,7 +665,7 @@ class QueryExecutor:
                 from matrx_orm.core.expressions import Exists as ExistsExpr
                 from matrx_orm.core.expressions import TsMatch as TsMatchExpr
 
-                if isinstance(item, (ExistsExpr, TsMatchExpr)):
+                if isinstance(item, ExistsExpr | TsMatchExpr):
                     where_conditions.append(item.as_sql(table, params))
                 elif isinstance(item, ColumnComparison):
                     where_conditions.append(item.as_sql(params))
@@ -695,7 +704,7 @@ class QueryExecutor:
                 field_name, operator = self._parse_lookup(key)
                 agg_func = agg_by_alias.get(field_name)
                 if agg_func is not None:
-                    if isinstance(agg_func, (_Subquery, _Exists)):
+                    if isinstance(agg_func, _Subquery | _Exists):
                         field_expr = agg_func.as_sql(table, params)
                     elif hasattr(agg_func, "as_sql"):
                         field_expr = agg_func.as_sql(params)
@@ -1331,10 +1340,7 @@ class QueryExecutor:
                     set_clause.append(f"{field_name} = {expr_sql}")
                     param_index = len(params) + 1
                 elif isinstance(value, Expression):
-                    sub_params: list[Any] = []
-                    expr_sql = value.as_sql(sub_params)
-                    for sp in sub_params:
-                        params.append(sp)
+                    expr_sql = _render_update_expression(value, params)
                     set_clause.append(f"{field_name} = {expr_sql}")
                     param_index = len(params) + 1
                 elif hasattr(value, "as_sql"):
@@ -1343,10 +1349,7 @@ class QueryExecutor:
                     # duck-typed convention as _render_func_arg's fallback, so
                     # SET col = CASE WHEN ... END works in .update()/
                     # .update_where() without hardcoding every expression class.
-                    sub_params = []
-                    expr_sql = value.as_sql(sub_params)
-                    for sp in sub_params:
-                        params.append(sp)
+                    expr_sql = _render_update_expression(value, params)
                     set_clause.append(f"{field_name} = {expr_sql}")
                     param_index = len(params) + 1
                 else:

{matrx_orm-3.1.22 → matrx_orm-3.1.24}/matrx_orm/schema_builder/runner.py

@@ -51,8 +51,68 @@ def _load_yaml(path: Path) -> dict[str, Any]:
         return yaml.safe_load(f) or {}
 
 
+def _select_generation_targets(
+    generate_entries: list[dict[str, Any]],
+    only_schemas: set[str] | None,
+) -> tuple[list[dict[str, Any]], dict[str, set[str] | None]]:
+    selected = list(generate_entries)
+    scoped_by_database: dict[str, set[str] | None] = {}
+    if not only_schemas:
+        return selected, scoped_by_database
+    selected = [
+        entry for entry in selected if entry.get("schema", "public") in only_schemas
+    ]
+    found = {entry.get("schema", "public") for entry in selected}
+    missing = only_schemas - found
+    if missing:
+        raise ValueError(
+            "matrx-orm generation requested unknown schema target(s): "
+            + ", ".join(sorted(missing))
+        )
+    for entry in selected:
+        database_name = entry.get("database")
+        if not database_name:
+            continue
+        if "dependency_schemas" not in entry:
+            scoped_by_database[database_name] = None
+            continue
+        existing = scoped_by_database.get(database_name, set())
+        if existing is None:
+            continue
+        existing.add(entry.get("schema", "public"))
+        existing.update(entry.get("dependency_schemas") or [])
+        scoped_by_database[database_name] = existing
+    return selected, scoped_by_database
+
+
+def _database_registration_plan(
+    databases: list[dict[str, Any]],
+    scoped_by_database: dict[str, set[str] | None],
+    *,
+    focused: bool,
+    models_only: bool,
+) -> list[dict[str, Any]]:
+    plan: list[dict[str, Any]] = []
+    for database in databases:
+        name = database.get("name")
+        if focused and name not in scoped_by_database:
+            continue
+        item = dict(database)
+        scoped = scoped_by_database.get(name)
+        if focused and scoped is not None:
+            item["additional_schemas"] = sorted(scoped)
+        item["pool_min"] = 1 if models_only else None
+        item["pool_max"] = 4 if models_only else None
+        plan.append(item)
+    return plan
+
+
 def run_schema_generation(
-    config_path: str | Path = "matrx_orm.yaml", skip_git_check: bool = False
+    config_path: str | Path = "matrx_orm.yaml",
+    skip_git_check: bool = False,
+    *,
+    only_schemas: set[str] | None = None,
+    models_only: bool = False,
 ) -> None:
     """
     Read a matrx_orm.yaml config file, register all databases, apply debug
@@ -192,6 +252,13 @@ def run_schema_generation(
             ignore_path_prefixes=_ignore_prefixes,
         )
 
+    # Resolve targets before database registration. A focused package-model
+    # pass should not connect to unrelated databases, and targets may declare
+    # the schemas needed to resolve their cross-schema foreign keys.
+    generate_list, scoped_schemas_by_database = _select_generation_targets(
+        cfg.get("generate", []), only_schemas
+    )
+
     # -------------------------------------------------------------------------
     # Register databases
     # -------------------------------------------------------------------------
@@ -202,7 +269,13 @@ def run_schema_generation(
         )
         return
 
-    for db in databases:
+    registration_plan = _database_registration_plan(
+        databases,
+        scoped_schemas_by_database,
+        focused=bool(only_schemas),
+        models_only=models_only,
+    )
+    for db in registration_plan:
         name = db.get("name")
         prefix = db.get("env_prefix")
         if not name or not prefix:
@@ -221,19 +294,19 @@ def run_schema_generation(
             field_overrides=db.get("field_overrides") or {},
             manager_config_overrides=db.get("manager_config_overrides") or {},
             env_var_overrides=db.get("env_var_overrides") or {},
+            pool_min=db["pool_min"],
+            pool_max=db["pool_max"],
         )
 
     # -------------------------------------------------------------------------
     # Run generation for each configured target
     # -------------------------------------------------------------------------
-    generate_list = cfg.get("generate", [])
     if not generate_list:
         vcprint(
             "[MATRX ORM] No entries in 'generate' — databases registered but nothing generated.",
             color="yellow",
         )
         return
-
     # model_name_prefix is RETIRED. The schema-aware model_registry (keyed on
     # (schema, class_name)) makes same-named tables across schemas coexist with
     # clean, prefix-free class names. A lingering prefix would silently re-create
@@ -309,7 +382,8 @@ def run_schema_generation(
                 output_overrides=output_overrides,
             )
             manager.initialize()
-            manager.schema.generate_schema_files()
+            if not models_only:
+                manager.schema.generate_schema_files()
             manager.schema.generate_models()
             vcprint(
                 f"[MATRX ORM] Done — database='{db_name}' schema='{schema}'\n",
@@ -337,14 +411,20 @@ def run_schema_generation(
             _close_pools()
             raise
 
-    _write_host_models_aggregator(
-        generate_list, python_root, output_config, host_schema_model_names
-    )
+    if not models_only:
+        _write_host_models_aggregator(
+            generate_list, python_root, output_config, host_schema_model_names
+        )
 
     # Declarative host→package DB wiring: resolve each incorporated package's
     # DB_REQUIREMENTS manifest against the inventory just written above and emit
     # the aidream-side wiring module. Only when writing Python directly to disk.
-    if cfg.get("package_wiring") and output_config.python and output_config.save_direct:
+    if (
+        not models_only
+        and cfg.get("package_wiring")
+        and output_config.python
+        and output_config.save_direct
+    ):
         try:
             from matrx_orm.schema_builder.package_wiring import generate_package_wiring
 

{matrx_orm-3.1.22 → matrx_orm-3.1.24}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.22"
+version = "3.1.24"
 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" }
@@ -44,6 +44,7 @@ dependencies = [
     "matrx-utils>=1.0.20",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
+    "cryptography>=43.0",
 ]
 
 [project.urls]

{matrx_orm-3.1.22 → matrx_orm-3.1.24}/tests/level1/test_conflict_target.py

@@ -74,6 +74,26 @@ def test_conflict_target_normalises_list_to_tuple() -> None:
     assert t.expressions == ("lower(name)", "kind")
 
 
+def test_typed_partial_target_renders_coalesce_and_predicates() -> None:
+    target = ConflictTarget.partial(
+        ["project_id", "region", "status"],
+        coalesce={"region": ""},
+        where_is_null=("deleted_at",),
+        where_is_not_null=("host_resource_id",),
+        where_equals={"status": "active"},
+    )
+
+    assert target.expressions == ("project_id", "COALESCE(region, '')", "status")
+    assert target.where == (
+        "deleted_at IS NULL AND host_resource_id IS NOT NULL AND status = 'active'"
+    )
+
+
+def test_typed_partial_target_rejects_non_identifier_columns() -> None:
+    with pytest.raises(ValueError, match="simple identifier"):
+        ConflictTarget.partial(["project_id; DROP TABLE x"])
+
+
 # ── Executor SQL shape ───────────────────────────────────────────────────────
 
 

{matrx_orm-3.1.22 → matrx_orm-3.1.24}/tests/level1/test_expression_primitives.py

@@ -24,7 +24,7 @@ from matrx_orm.core.expressions import (
     _iter_subquery_conditions,
 )
 from matrx_orm.core.expressions import Q
-from matrx_orm.query.executor import QueryExecutor
+from matrx_orm.query.executor import QueryExecutor, _render_update_expression
 
 
 # ── Array functions ─────────────────────────────────────────────────────────
@@ -262,3 +262,21 @@ def test_binary_expr_duck_types_as_sql_for_the_executor_fallback():
     assert hasattr(expr, "as_sql")
     params: list = []
     assert expr.as_sql(params) == "(COALESCE(weight, $1) + $2)"
+
+
+def test_multiple_update_expressions_shift_parameters_across_set_fields():
+    from matrx_orm import Coalesce, F
+
+    params: list = ["fetched-at", "task-id"]
+    request_sql = _render_update_expression(F("request_count") + 1, params)
+    provider_sql = _render_update_expression(
+        Coalesce(F("provider_cost"), 0) + 0.12, params
+    )
+    estimated_sql = _render_update_expression(
+        Coalesce(F("estimated_cost"), 0) + 0.10, params
+    )
+
+    assert request_sql == "request_count + $3"
+    assert provider_sql == "(COALESCE(provider_cost, $4) + $5)"
+    assert estimated_sql == "(COALESCE(estimated_cost, $6) + $7)"
+    assert params == ["fetched-at", "task-id", 1, 0, 0.12, 0, 0.10]

matrx_orm-3.1.24/tests/schema_builder/test_focused_generation_plan.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import pytest
+
+from matrx_orm.schema_builder.runner import (
+    _database_registration_plan,
+    _select_generation_targets,
+)
+
+
+def test_focused_target_scopes_dependencies_and_skips_unrelated_database() -> None:
+    entries = [
+        {
+            "database": "main",
+            "schema": "seo",
+            "dependency_schemas": ["auth", "iam", "platform"],
+        },
+        {"database": "cms", "schema": "public"},
+    ]
+    selected, scoped = _select_generation_targets(entries, {"seo"})
+    plan = _database_registration_plan(
+        [
+            {"name": "main", "additional_schemas": ["seo", "web", "auth"]},
+            {"name": "cms", "additional_schemas": ["history"]},
+        ],
+        scoped,
+        focused=True,
+        models_only=True,
+    )
+
+    assert selected == [entries[0]]
+    assert scoped == {"main": {"seo", "auth", "iam", "platform"}}
+    assert [item["name"] for item in plan] == ["main"]
+    assert plan[0]["additional_schemas"] == ["auth", "iam", "platform", "seo"]
+    assert (plan[0]["pool_min"], plan[0]["pool_max"]) == (1, 4)
+
+
+def test_focused_target_without_dependencies_preserves_full_database_scope() -> None:
+    entries = [{"database": "main", "schema": "web"}]
+    _, scoped = _select_generation_targets(entries, {"web"})
+    plan = _database_registration_plan(
+        [{"name": "main", "additional_schemas": ["web", "auth", "iam"]}],
+        scoped,
+        focused=True,
+        models_only=False,
+    )
+
+    assert scoped == {"main": None}
+    assert plan[0]["additional_schemas"] == ["web", "auth", "iam"]
+    assert (plan[0]["pool_min"], plan[0]["pool_max"]) == (None, None)
+
+
+def test_unknown_focused_schema_fails_before_registration() -> None:
+    with pytest.raises(ValueError, match="unknown schema target.*missing"):
+        _select_generation_targets(
+            [{"database": "main", "schema": "seo"}],
+            {"missing"},
+        )

matrx_orm-3.1.24/tests/test_secrets_battery.py

@@ -0,0 +1,135 @@
+"""Secrets battery — crypto + contract tests (no DB required).
+
+The DB-facing CRUD is exercised through aidream's existing user_secrets
+tests; here we pin the parts that must never drift: key resolution,
+round-trips, mask shape, env parsing, and the historical-compatibility
+guarantee that a ciphertext written by the old aidream implementation
+decrypts with the battery.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+
+import pytest
+
+from matrx_orm.secrets import crypto
+
+
+@pytest.fixture(autouse=True)
+def _clean_crypto_state(monkeypatch):
+    crypto.reset_encryption_for_tests()
+    monkeypatch.delenv("CREDENTIALS_ENCRYPTION_KEY", raising=False)
+    monkeypatch.delenv("SUPABASE_SECRET_KEY", raising=False)
+    yield
+    crypto.reset_encryption_for_tests()
+
+
+def _fernet_key() -> str:
+    from cryptography.fernet import Fernet
+
+    return Fernet.generate_key().decode()
+
+
+def test_no_key_is_loud():
+    with pytest.raises(RuntimeError, match="no encryption key configured"):
+        crypto.get_fernet()
+
+
+def test_string_round_trip_env_key(monkeypatch):
+    monkeypatch.setenv("CREDENTIALS_ENCRYPTION_KEY", _fernet_key())
+    ct = crypto.encrypt_value("s3cret-value")
+    assert isinstance(ct, bytes)
+    assert crypto.decrypt_value(ct) == "s3cret-value"
+
+
+def test_empty_string_round_trips(monkeypatch):
+    monkeypatch.setenv("CREDENTIALS_ENCRYPTION_KEY", _fernet_key())
+    assert crypto.decrypt_value(crypto.encrypt_value("")) == ""
+
+
+def test_payload_round_trip(monkeypatch):
+    monkeypatch.setenv("CREDENTIALS_ENCRYPTION_KEY", _fernet_key())
+    payload = {"api_key": "abc", "nested": {"n": 1}}
+    assert crypto.decrypt_payload(crypto.encrypt_payload(payload)) == payload
+
+
+def test_configure_encryption_overrides_env(monkeypatch):
+    monkeypatch.setenv("CREDENTIALS_ENCRYPTION_KEY", _fernet_key())
+    injected = _fernet_key()
+    crypto.configure_encryption(injected)
+    ct = crypto.encrypt_value("via-injected-key")
+    # Same key injected fresh must decrypt; env key must NOT have been used.
+    crypto.reset_encryption_for_tests()
+    crypto.configure_encryption(injected)
+    assert crypto.decrypt_value(ct) == "via-injected-key"
+
+
+def test_non_fernet_key_is_sha256_derived_like_legacy(monkeypatch):
+    """A non-44-char CREDENTIALS_ENCRYPTION_KEY derives via SHA-256 —
+    byte-identical to the historical aidream implementation, so every
+    existing ciphertext keeps decrypting."""
+    from cryptography.fernet import Fernet
+
+    monkeypatch.setenv("CREDENTIALS_ENCRYPTION_KEY", "some-passphrase-style-key")
+    legacy = Fernet(base64.urlsafe_b64encode(hashlib.sha256(b"some-passphrase-style-key").digest()))
+    legacy_ct = legacy.encrypt(b"written-by-old-code")
+    assert crypto.get_fernet().decrypt(legacy_ct) == b"written-by-old-code"
+
+
+def test_supabase_seed_fallback_derivation(monkeypatch):
+    from cryptography.fernet import Fernet
+
+    monkeypatch.setenv("SUPABASE_SECRET_KEY", "seed-material")
+    derived = Fernet(base64.urlsafe_b64encode(hashlib.sha256(b"seed-material").digest()))
+    assert crypto.get_fernet().decrypt(derived.encrypt(b"x")) == b"x"
+
+
+def test_mask_value_shapes():
+    assert crypto.mask_value("") == ""
+    assert crypto.mask_value("ghp_1234567890abcd") == "ghp_…abcd"
+    short = crypto.mask_value("abcd")
+    assert "…" in short and len(short) <= 5
+
+
+def test_type_guards(monkeypatch):
+    monkeypatch.setenv("CREDENTIALS_ENCRYPTION_KEY", _fernet_key())
+    with pytest.raises(TypeError):
+        crypto.encrypt_value(123)  # type: ignore[arg-type]
+    with pytest.raises(TypeError):
+        crypto.decrypt_value("not-bytes")  # type: ignore[arg-type]
+
+
+def test_parse_env_text():
+    from matrx_orm.secrets import parse_env_text
+
+    text = """
+    # comment
+    export FOO=bar
+    QUOTED="with spaces"
+    SINGLE='sq'
+    EMPTY=
+    novalue
+    """
+    pairs = dict(parse_env_text(text))
+    assert pairs == {"FOO": "bar", "QUOTED": "with spaces", "SINGLE": "sq", "EMPTY": ""}
+
+
+def test_public_api_surface():
+    import matrx_orm.secrets as s
+
+    for name in (
+        "configure_secrets",
+        "require_user_secret",
+        "get_user_secret",
+        "create_user_secret",
+        "update_user_secret",
+        "delete_user_secret",
+        "list_user_secrets",
+        "bulk_upsert_from_env_text",
+        "encrypt_payload",
+        "decrypt_payload",
+        "UserSecret",
+    ):
+        assert hasattr(s, name), name