matrx-orm 3.1.39__tar.gz → 3.1.41__tar.gz

{matrx_orm-3.1.39 → matrx_orm-3.1.41}/CLAUDE.md

@@ -32,6 +32,9 @@ Every table that becomes a Model needs row identity: a single-column primary key
   subqueries. SQL-shaped strings fail closed: plain strings name validated
   columns only; compose casts, JSON paths, functions, ordering, joins, partial
   conflict targets, and filtered aggregates with the exported typed objects.
+  Large reconciliation/export scans call `.all(use_cache=False)` so returned
+  models do not quadratically populate the process identity cache. Contract:
+  [`matrx_orm/query/FEATURE.md`](matrx_orm/query/FEATURE.md).
 - **Migrations**: `MigrationDB`, `MigrationLoader`, `MigrationExecutor`, `makemigrations`, `migrate` — migrations declare explicit `dependencies` and apply in topological order (no multi-head/merge support yet).
 - **Admin router** (FastAPI): `admin_router` exposes read/write endpoints for any registered model.
 - **API layer** (optional `[api]` extra): `APIServer`, `APIConfig`, `TokenAuth`.

{matrx_orm-3.1.39 → matrx_orm-3.1.41}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.39
+Version: 3.1.41
 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.39 → matrx_orm-3.1.41}/matrx_orm/core/base.py

@@ -1292,17 +1292,17 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
         return run_sync(cls.delete_where(**filters))
 
     @classmethod
-    async def all(cls) -> list[Self]:
+    async def all(cls, *, use_cache: bool = True) -> list[Self]:
+        """Fetch every row, optionally bypassing identity-cache population."""
+
         try:
-            results: list[Self] = await QueryBuilder(model_cls=cls).all()
-            await StateManager.cache_bulk(model_class=cls, records=results)
-            return results
+            return await QueryBuilder(model_cls=cls).all(use_cache=use_cache)
         except ORMException as e:
             e.enrich(model=cls, operation="all")
             raise
 
     @classmethod
-    def all_sync(cls) -> list[Self]:
+    def all_sync(cls, *, use_cache: bool = True) -> list[Self]:
         """
         Synchronous wrapper for all().
         Use this in synchronous contexts to fetch all results without async/await.
@@ -1316,7 +1316,7 @@ class Model(RuntimeMixin, metaclass=ModelMeta):
             if "no running event loop" not in str(e):
                 raise
 
-        return run_sync(cls.all())
+        return run_sync(cls.all(use_cache=use_cache))
 
     async def save(self, **kwargs: Any) -> Self:
         """Save the current state of the model instance."""

matrx_orm-3.1.41/matrx_orm/query/FEATURE.md

@@ -0,0 +1,17 @@
+# Query execution
+
+`QueryBuilder` is the typed terminal-read and write layer behind every model.
+Application packages compose queries here; they never bypass it with SQL.
+
+## Large scans and the identity cache
+
+`.all()` populates `StateManager` by default so ordinary repeated identity reads
+remain fast. A large reconciliation, export, or historical scan must call
+`.all(use_cache=False)`. This still returns fully hydrated models and still
+merges pending session state, but it does not insert every result into the
+process identity cache.
+
+`Model.all(use_cache=False)` exposes the same behavior. The default remains
+`True` for compatibility. The cache bypass controls only cache population; it
+does not weaken database authorization, filters, hydration, or transaction
+semantics.

{matrx_orm-3.1.39 → matrx_orm-3.1.41}/matrx_orm/query/builder.py

@@ -778,7 +778,7 @@ class QueryBuilder(Generic[ModelT]):
         if len(pks) == 1 and not self.excludes and set(combined) <= {pks[0], f"{pks[0]}__in"}:
             values = combined.get(pks[0])
             in_values = combined.get(f"{pks[0]}__in")
-            targets = list(in_values) if isinstance(in_values, (list, tuple, set)) else []
+            targets = list(in_values) if isinstance(in_values, list | tuple | set) else []
             if values is not None:
                 targets.append(values)
             if targets and StateManager.is_registered(self.model):
@@ -802,9 +802,12 @@ class QueryBuilder(Generic[ModelT]):
     # Terminal async methods
     # ------------------------------------------------------------------
 
-    async def all(self) -> list[ModelT]:
+    async def all(self, *, use_cache: bool = True) -> list[ModelT]:
         """Fetch all matching records.
 
+        Pass ``use_cache=False`` for large scans that must not populate the
+        process identity cache.
+
         Session-aware: if an active Session has pending writes for this
         Model, the result merges pending state with DB rows. Pending
         INSERTs matching the filter appear in the result; pending UPDATEs
@@ -814,10 +817,12 @@ class QueryBuilder(Generic[ModelT]):
         try:
             executor = self._get_executor()
             results = await executor.all()
-            await StateManager.cache_bulk(self.model, results)
+            if use_cache:
+                await StateManager.cache_bulk(self.model, results)
             if debug:
                 vcprint(
-                    f"[BUILDER] all() cached {len(results)} records for {self.model.__name__}",
+                    f"[BUILDER] all() fetched {len(results)} records for "
+                    f"{self.model.__name__} (cache={use_cache})",
                     color="bright_gold",
                 )
             return _merge_pending_into_models(

{matrx_orm-3.1.39 → matrx_orm-3.1.41}/matrx_orm/secrets_battery/FEATURE.md

@@ -37,6 +37,25 @@ row whose owner columns don't match its item's owner.
 `editable=false` blocks human value changes (`FieldNotEditableError`); the owning
 service rotates via `system_rotation=True` / `rotate_credential_fields`.
 
+**`inject_into_sandbox=true` REQUIRES an env alias — refused otherwise.** A
+container environment is a NAME→value map, so a field with `key IS NULL` has
+nowhere to land and bulk resolution drops it. Accepting the flag anyway meant a
+user could switch "inject into sandbox" on and get nothing, forever, with no
+error — the silent-failure class this guard ends. Three layers, each sufficient
+alone, each loud:
+
+1. **Write refusal** — `create_credential_bundle` / `add_credential_field` /
+   `update_field_metadata` raise `SandboxInjectionWithoutEnvKeyError` (a
+   `ValueError`, so hosts answer 422 with the reason). `update_field_metadata`
+   judges the POST-patch state, so *clearing the alias of an already-injecting
+   field* is refused the same way. Setting `env_key` and the flag in ONE patch
+   is the supported fix and always passes.
+2. **Resolution scream** — `_keyed_for_sandbox` logs an ERROR naming the row ids
+   and skips them, so anything that got in around layer 1 is visible.
+3. **DB CHECK** `user_secrets_sandbox_injection_needs_key` (migration 0265) makes
+   the state unrepresentable; the column default moved `true` → `false` so the
+   database stops manufacturing violations on keyless inserts.
+
 Item surface: `create_credential_item` · `create_credential_bundle` (item + N
 fields, ONE transaction) · `get/list/update/delete_credential_item` (delete =
 soft, atomic across item + fields + grants) · `add_credential_field` ·
@@ -118,7 +137,10 @@ EXCLUDES `sealed` fields, so a browser-facing caller can never receive sealed
 plaintext through an env dump. Only trusted execution (service-token sandbox
 injection, in-process context hydration, provider adapters) passes `True`.
 Rows with `key IS NULL` (item fields without an env alias) never resolve into
-an environment in either mode.
+an environment in either mode — silently when nothing promised otherwise (a
+keyless item field is normal), but **LOUDLY when `for_sandbox=True`**: such a row
+is flagged for injection and cannot deliver, which is a defect (see the
+handling doctrine above).
 
 **Legacy key-based writes respect item discipline:** `create_user_secret(upsert=True)`,
 `update_user_secret`, and `delete_user_secret` REFUSE a target row that is
@@ -216,6 +238,7 @@ create, reveal, sealed denial, editable gate, rotate, item grants, soft delete).
 
 ## Change Log
 
+- 2026-07-26 — Closed the silent sandbox-injection gap: `SandboxInjectionWithoutEnvKeyError` at every field write path, a loud ERROR-and-skip in `for_sandbox` bulk resolution, and DB CHECK `user_secrets_sandbox_injection_needs_key` (+ column default `true`→`false`). Live at the time of the fix: 0 broken rows, but 61 keyless item fields were one toggle away from it.
 - 2026-07-23 — `update_field_metadata` primitive (metadata-only, version-preserving; `users.bump_user_secret_value_version` verified value-conditional live — no trigger change needed).
 - 2026-07-23 — Adversarial-review hardening: include_sealed-aware bulk env resolution (+ keyless-row exclusion), ItemManagedSecretError legacy-write guards + legacy audit rows, ItemGrantSpec per-grantee grants, reveal liveness filters, rotate liveness re-check + audits inside owning transactions.
 - 2026-07-23 — Phase 2: item layer (`items.py` — bundles, handling modes, stable resolution, item grants, transfer/fork), rotation primitives (`fernet_for_key`/`multi_fernet_for_keys`) + `scripts/rotate_credentials_key.py` (closes the no-rotation-script ticket), migration 0236 grants fixup (item-level grants possible).

{matrx_orm-3.1.39 → matrx_orm-3.1.41}/matrx_orm/secrets_battery/__init__.py

@@ -48,6 +48,7 @@ from .items import (
     FieldNotEditableError,
     FieldSpec,
     ItemGrantSpec,
+    SandboxInjectionWithoutEnvKeyError,
     SealedFieldError,
     add_credential_field,
     add_item_grant,
@@ -150,6 +151,7 @@ __all__ = [
     "FieldNotEditableError",
     "FieldSpec",
     "ItemGrantSpec",
+    "SandboxInjectionWithoutEnvKeyError",
     "SealedFieldError",
     "URI_MATCH_MODES",
     "add_credential_field",

{matrx_orm-3.1.39 → matrx_orm-3.1.41}/matrx_orm/secrets_battery/items.py

@@ -69,6 +69,18 @@ class FieldNotEditableError(PermissionError):
     (``rotate_credential_fields``), never by hand."""
 
 
+class SandboxInjectionWithoutEnvKeyError(ValueError):
+    """``inject_into_sandbox=true`` on a field that has no environment-variable
+    alias (``key``). A container environment is a NAME→value map: with no name
+    the value has nowhere to land, so the flag is a promise the platform cannot
+    keep — the field would silently never appear in any sandbox.
+
+    Refused LOUDLY at every write path instead of accepted-and-dropped (hosts
+    map ``ValueError`` → 422). Set an env alias in the same request (the vault
+    field-metadata patch takes ``env_key`` and ``inject_into_sandbox``
+    together) or leave injection off."""
+
+
 # ── Shapes ────────────────────────────────────────────────────────────────
 
 
@@ -175,6 +187,26 @@ def _validate_handling(handling: str) -> None:
         raise ValueError(f"handling must be one of {HANDLING_MODES}; got {handling!r}")
 
 
+def _validate_sandbox_injectable(
+    *,
+    field_key: str | None,
+    env_key: str | None,
+    inject_into_sandbox: bool,
+) -> None:
+    """LAYER 1 of the no-silent-injection guard: a field may only be flagged
+    for sandbox injection while it carries an env alias. See
+    :class:`SandboxInjectionWithoutEnvKeyError`. Layer 2 is the loud skip in
+    ``org_service`` bulk resolution; layer 3 is the DB CHECK
+    ``user_secrets_sandbox_injection_needs_key``."""
+    if inject_into_sandbox and not env_key:
+        raise SandboxInjectionWithoutEnvKeyError(
+            f"field {field_key or '<unnamed>'!r} cannot be injected into sandboxes without "
+            "an environment-variable alias (env_key) — a container env has no name to bind "
+            "the value to, so the flag would silently do nothing. Set env_key in the same "
+            "request, or leave inject_into_sandbox off."
+        )
+
+
 def _validate_uri_match_mode(mode: str) -> None:
     if mode not in URI_MATCH_MODES:
         raise ValueError(f"uri_match_mode must be one of {URI_MATCH_MODES}; got {mode!r}")
@@ -457,6 +489,11 @@ async def create_credential_bundle(
     for spec in fields:
         _validate_field_key(spec.field_key)
         _validate_handling(spec.handling)
+        _validate_sandbox_injectable(
+            field_key=spec.field_key,
+            env_key=spec.env_key,
+            inject_into_sandbox=spec.inject_into_sandbox,
+        )
         if not isinstance(spec.value, str):
             raise ValueError(f"field {spec.field_key!r}: value must be a string")
         if spec.field_key in seen:
@@ -667,6 +704,11 @@ async def add_credential_field(
     the item so field-level scoping stays consistent)."""
     _validate_field_key(spec.field_key)
     _validate_handling(spec.handling)
+    _validate_sandbox_injectable(
+        field_key=spec.field_key,
+        env_key=spec.env_key,
+        inject_into_sandbox=spec.inject_into_sandbox,
+    )
     if not isinstance(spec.value, str):
         raise ValueError("value must be a string")
     raw = await _require_item_raw(item_id)
@@ -837,6 +879,19 @@ async def update_field_metadata(
                 "a one-way door; rotate/replace the field instead of unsealing it"
             )
 
+        # The POST-patch state is what matters: enabling injection on a keyless
+        # field AND clearing the alias of an already-injecting field are the
+        # same silent breakage from opposite directions. Both are refused.
+        _validate_sandbox_injectable(
+            field_key=raw.get("field_key") or raw.get("key"),
+            env_key=(raw.get("key") if env_key is _UNSET else env_key),
+            inject_into_sandbox=(
+                bool(raw.get("inject_into_sandbox"))
+                if inject_into_sandbox is None
+                else inject_into_sandbox
+            ),
+        )
+
         updates: dict[str, Any] = {"updated_by": actor_id, "updated_at": datetime.now(UTC)}
         if inject_into_sandbox is not None:
             updates["inject_into_sandbox"] = inject_into_sandbox
@@ -1457,6 +1512,7 @@ __all__ = [
     "FieldNotEditableError",
     "FieldSpec",
     "ItemGrantSpec",
+    "SandboxInjectionWithoutEnvKeyError",
     "SealedFieldError",
     "add_credential_field",
     "create_credential_bundle",

{matrx_orm-3.1.39 → matrx_orm-3.1.41}/matrx_orm/secrets_battery/org_service.py

@@ -458,6 +458,31 @@ async def delete_org_secret(secret_id: str, *, actor_id: str) -> None:
     )
 
 
+def _keyed_for_sandbox(rows: list[dict[str, Any]], *, scope: str) -> list[dict[str, Any]]:
+    """LAYER 2 of the no-silent-injection guard (loud).
+
+    A row flagged ``inject_into_sandbox`` but carrying no env alias can never
+    land in a container environment — there is no name to bind it to. Every
+    write path REFUSES that combination
+    (:class:`~matrx_orm.secrets_battery.items.SandboxInjectionWithoutEnvKeyError`)
+    and a DB CHECK backs it, so anything arriving here got in around both:
+    direct SQL, an unguarded migration, or data that predates the guards.
+    Dropping it quietly is precisely the failure this exists to end."""
+    keyed = [r for r in rows if r.get("key")]
+    orphans = len(rows) - len(keyed)
+    if orphans:
+        logger.error(
+            "[secrets_battery] %d secret(s) in scope %s are flagged "
+            "inject_into_sandbox but have NO env alias (key IS NULL) — they can never reach "
+            "a sandbox and are being SKIPPED. This state is refused by every write path; "
+            "these rows bypassed it. ids=%s",
+            orphans,
+            scope,
+            sorted(str(r["id"]) for r in rows if not r.get("key")),
+        )
+    return keyed
+
+
 async def resolve_org_secrets(
     organization_id: str,
     *,
@@ -487,15 +512,21 @@ async def resolve_org_secrets(
         "organization_id": organization_id,
         "deleted_at__isnull": True,
         "is_active": True,
-        "key__isnull": False,
     }
     if not include_sealed:
         filters["handling__ne"] = "sealed"
     if for_sandbox:
+        # Keyless rows are pulled deliberately here so the injection guard can
+        # SCREAM about them (a keyless field flagged for injection is a defect);
+        # everywhere else a keyless item field is normal and silently skipped.
         filters["inject_into_sandbox"] = True
+    else:
+        filters["key__isnull"] = False
     if keys:
         filters["key__in"] = keys
     rows = await UserSecret.filter(**filters).values("id", "key", "value_encrypted", "access_mode")
+    if for_sandbox:
+        rows = _keyed_for_sandbox(rows, scope=f"organization {organization_id}")
     if not rows:
         return {}
 
@@ -567,15 +598,19 @@ async def resolve_effective_secrets(
         "user_id": user_id,
         "deleted_at__isnull": True,
         "is_active": True,
-        "key__isnull": False,
     }
     if not include_sealed:
         filters["handling__ne"] = "sealed"
     if for_sandbox:
+        # See resolve_org_secrets: keyless rows are pulled so the guard screams.
         filters["inject_into_sandbox"] = True
+    else:
+        filters["key__isnull"] = False
     if keys:
         filters["key__in"] = keys
-    rows = await UserSecret.filter(**filters).values("key", "value_encrypted")
+    rows = await UserSecret.filter(**filters).values("id", "key", "value_encrypted")
+    if for_sandbox:
+        rows = _keyed_for_sandbox(rows, scope=f"user {user_id}")
     for row in rows:
         try:
             resolved[str(row["key"])] = decrypt_value(row["value_encrypted"])

{matrx_orm-3.1.39 → matrx_orm-3.1.41}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.39"
+version = "3.1.41"
 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.39 → matrx_orm-3.1.41}/tests/level1/test_query_builder.py

@@ -1,11 +1,15 @@
 """Level 1: QueryBuilder — filter, exclude, order_by, limit, offset, select, _build_query."""
 
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
 import pytest
 from matrx_orm.core.base import Model, ModelMeta
 from matrx_orm.core.fields import CharField, IntegerField, UUIDField
 from matrx_orm.core.registry import ModelRegistry
 from matrx_orm.exceptions import DoesNotExist, PermissionDeniedError
 from matrx_orm.query.builder import QueryBuilder
+from matrx_orm.state import StateManager
 
 
 @pytest.fixture(autouse=True)
@@ -85,6 +89,20 @@ class TestQueryBuilderChaining:
         qb = QueryBuilder(M).filter()
         assert qb.filters == []
 
+    @pytest.mark.asyncio
+    async def test_all_can_skip_identity_cache_for_large_scans(self, monkeypatch):
+        M = _make_model()
+        rows = [M(id="00000000-0000-0000-0000-000000000001", name="Alice")]
+        executor = SimpleNamespace(all=AsyncMock(return_value=rows))
+        cache_bulk = AsyncMock()
+        monkeypatch.setattr(QueryBuilder, "_get_executor", lambda _self: executor)
+        monkeypatch.setattr(StateManager, "cache_bulk", cache_bulk)
+
+        result = await QueryBuilder(M).all(use_cache=False)
+
+        assert result == rows
+        cache_bulk.assert_not_awaited()
+
 
 class TestBuildQuery:
     def test_build_query_basic(self):

{matrx_orm-3.1.39 → matrx_orm-3.1.41}/tests/test_secrets_battery.py

@@ -246,6 +246,199 @@ async def test_resolve_effective_secrets_personal_branch_is_handling_aware(monke
     assert filters["key__isnull"] is False
 
 
+# ── The no-silent-sandbox-injection guard ─────────────────────────────────
+#
+# A field flagged inject_into_sandbox with no env alias (key IS NULL) can never
+# reach a container environment — the resolver has no name to bind it to. Before
+# these guards the flag was accepted and the row silently dropped, so a user
+# could switch "inject into sandbox" on and get nothing, forever, with no error.
+# Layer 1 = write refusal (below), layer 2 = loud skip at resolution,
+# layer 3 = DB CHECK user_secrets_sandbox_injection_needs_key.
+
+
+def test_injection_without_env_key_is_refused():
+    from matrx_orm.secrets_battery import SandboxInjectionWithoutEnvKeyError
+    from matrx_orm.secrets_battery.items import _validate_sandbox_injectable
+
+    with pytest.raises(SandboxInjectionWithoutEnvKeyError, match="env"):
+        _validate_sandbox_injectable(field_key="api_key", env_key=None, inject_into_sandbox=True)
+    with pytest.raises(SandboxInjectionWithoutEnvKeyError):
+        _validate_sandbox_injectable(field_key="api_key", env_key="", inject_into_sandbox=True)
+
+
+def test_injection_with_env_key_is_allowed():
+    from matrx_orm.secrets_battery.items import _validate_sandbox_injectable
+
+    _validate_sandbox_injectable(
+        field_key="api_key", env_key="ACME_API_KEY", inject_into_sandbox=True
+    )
+    # Keyless is perfectly normal as long as nothing promised injection.
+    _validate_sandbox_injectable(field_key="password", env_key=None, inject_into_sandbox=False)
+
+
+def test_injection_error_is_a_value_error_so_hosts_answer_422():
+    """The vault router maps ValueError → 422 with the message; a user who
+    flips the switch must SEE why, not get a silent 200."""
+    from matrx_orm.secrets_battery import SandboxInjectionWithoutEnvKeyError
+
+    assert issubclass(SandboxInjectionWithoutEnvKeyError, ValueError)
+
+
+@pytest.mark.asyncio
+async def test_create_credential_bundle_refuses_injection_without_env_key():
+    from matrx_orm.secrets_battery import (
+        FieldSpec,
+        SandboxInjectionWithoutEnvKeyError,
+        create_credential_bundle,
+    )
+
+    # Validation runs before any DB work, so this needs no database.
+    with pytest.raises(SandboxInjectionWithoutEnvKeyError):
+        await create_credential_bundle(
+            user_id="u1",
+            display_name="Acme",
+            fields=[FieldSpec(field_key="api_key", value="v", inject_into_sandbox=True)],
+        )
+
+
+def _noop_transaction(_name):
+    class _T:
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *exc):
+            return False
+
+    return _T()
+
+
+@pytest.mark.parametrize(
+    "stored,patch",
+    [
+        # The FE's exact flow: flip the switch on a keyless item field.
+        ({"key": None, "inject_into_sandbox": False}, {"inject_into_sandbox": True}),
+        # The same breakage from the other direction: clear the alias of a
+        # field that is already injecting.
+        ({"key": "ACME_KEY", "inject_into_sandbox": True}, {"env_key": None}),
+    ],
+)
+@pytest.mark.asyncio
+async def test_update_field_metadata_refuses_a_no_op_injection(monkeypatch, stored, patch):
+    from matrx_orm.secrets_battery import SandboxInjectionWithoutEnvKeyError, items
+
+    row = {
+        "id": "f1",
+        "credential_item_id": "i1",
+        "field_key": "api_key",
+        "handling": "revealable",
+        "editable": True,
+        "value_hint": "…",
+        "value_version": 1,
+        "is_active": True,
+        "description": None,
+        "created_at": "",
+        "updated_at": "",
+        "user_id": "u1",
+        "organization_id": None,
+        **stored,
+    }
+    monkeypatch.setattr(items, "UserSecret", _fake_user_secret([row], []))
+    monkeypatch.setattr(items, "transaction", _noop_transaction)
+    monkeypatch.setattr(items, "record_secret_audit", _noop_audit)
+
+    with pytest.raises(SandboxInjectionWithoutEnvKeyError):
+        await items.update_field_metadata("f1", actor_id="u1", **patch)
+
+
+@pytest.mark.asyncio
+async def test_update_field_metadata_allows_alias_and_injection_together(monkeypatch):
+    """The refusal must never be a dead end: naming the alias and enabling
+    injection in ONE patch is the supported fix, so it has to pass."""
+    from matrx_orm.secrets_battery import items
+
+    row = {
+        "id": "f1",
+        "credential_item_id": "i1",
+        "field_key": "api_key",
+        "key": None,
+        "handling": "revealable",
+        "editable": True,
+        "inject_into_sandbox": False,
+        "value_hint": "…",
+        "value_version": 1,
+        "is_active": True,
+        "description": None,
+        "created_at": "",
+        "updated_at": "",
+        "user_id": "u1",
+        "organization_id": None,
+    }
+    class _FakeUserSecret:
+        @classmethod
+        def filter(cls, **kw):
+            # The env-alias uniqueness probe must come back empty.
+            return _FakeQB([] if kw.get("key") == "ACME_KEY" else [row])
+
+        @classmethod
+        async def update_where(cls, *a, **kw):
+            class _R:
+                rows_affected = 1
+
+            return _R()
+
+    monkeypatch.setattr(items, "UserSecret", _FakeUserSecret)
+    monkeypatch.setattr(items, "transaction", _noop_transaction)
+    monkeypatch.setattr(items, "record_secret_audit", _noop_audit)
+
+    out = await items.update_field_metadata(
+        "f1", actor_id="u1", env_key="ACME_KEY", inject_into_sandbox=True
+    )
+    assert out.field_key == "api_key"
+
+
+@pytest.mark.asyncio
+async def test_resolve_for_sandbox_screams_and_skips_keyless_rows(monkeypatch, caplog):
+    """Layer 2: a row that got around the write guards is SKIPPED LOUDLY."""
+    import logging
+
+    from matrx_orm.secrets_battery import org_service
+
+    rows = [
+        {"id": "orphan-1", "key": None, "value_encrypted": b"x"},
+        {"id": "keyed-1", "key": "GOOD_KEY", "value_encrypted": b"y"},
+    ]
+    captured: list[dict] = []
+    monkeypatch.setattr(org_service, "UserSecret", _fake_user_secret(rows, captured))
+    monkeypatch.setattr(org_service, "decrypt_value", lambda b: "plain")
+
+    with caplog.at_level(logging.ERROR, logger=org_service.logger.name):
+        out = await org_service.resolve_effective_secrets("u1", None, for_sandbox=True)
+
+    assert out == {"GOOD_KEY": "plain"}
+    # The keyless row is pulled (not filtered away) precisely so it can scream.
+    assert "key__isnull" not in captured[0]
+    assert captured[0]["inject_into_sandbox"] is True
+    assert any(
+        r.levelno >= logging.ERROR and "orphan-1" in r.getMessage() for r in caplog.records
+    ), "a keyless injectable row must produce a loud ERROR naming it"
+
+
+@pytest.mark.asyncio
+async def test_non_sandbox_resolution_still_drops_keyless_rows_silently(monkeypatch, caplog):
+    """Keyless item fields are NORMAL outside sandbox injection (61 live rows
+    at the time of writing) — they must not generate alarm noise."""
+    import logging
+
+    from matrx_orm.secrets_battery import org_service
+
+    captured: list[dict] = []
+    monkeypatch.setattr(org_service, "UserSecret", _fake_user_secret([], captured))
+    with caplog.at_level(logging.ERROR, logger=org_service.logger.name):
+        await org_service.resolve_effective_secrets("u1", None)
+    assert captured[0]["key__isnull"] is False
+    assert not [r for r in caplog.records if r.levelno >= logging.ERROR]
+
+
 # ── Sealed reveal refusal + liveness filters ──────────────────────────────