matrx-orm 3.1.243__tar.gz → 3.1.244__tar.gz

{matrx_orm-3.1.243 → matrx_orm-3.1.244}/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+- **Fix: an instance `update()` / `save()` runs a SQL expression instead of storing it.**
+  `row.update(metadata=JsonbMerge("metadata", {...}))` sent the expression through
+  `JSONField.get_db_prep_value`, and `json.dumps` wrote its attribute dict over the
+  column (1,328 live rows lost their metadata, 2026-10-22); a text column stored
+  `str(expression)`. `update_instance` and `bulk_update` now hand every expression to
+  the executor's SET compiler exactly as `update_where` does, and the instance ends
+  holding the computed value (re-read when RETURNING did not carry it). `F("col")` is
+  now a valid SET value. Every serialising path refuses an expression loudly with the
+  new `ExpressionAsDataError` (a `TypeError`): all `Field.get_db_prep_value`
+  implementations (wrapped per subclass), the json encoders (nested expressions), json
+  function arguments, and PostgREST adapter writes. New export `is_sql_expression`.
+  Guard: `tests/test_instance_update_runs_expressions.py` (9 live round trips; all 9
+  red on the prior code).
+
 - **Feature: entity doors in the associations engine.** A registry token may resolve to a
   *door* (`__entity_door__ = True`, `async load_by_ids(ids, *, actor_id) -> {id: row}`) instead of
   a Model, for nouns whose rows live behind the host's read doors (a record store). The engine

{matrx_orm-3.1.243 → matrx_orm-3.1.244}/PKG-INFO

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

@@ -129,7 +129,10 @@ from .core.expressions import (
     Like,
     Regex,
     JsonbConcat,
+    ExpressionAsDataError,
     JsonbMerge,
+    JsonbRemoveKeys,
+    is_sql_expression,
     JsonbObjectAgg,
     Lag,
     LastValue,
@@ -645,7 +648,10 @@ __all__ = [
     "ArrayIndex",
     "JsonText",
     "JsonbConcat",
+    "ExpressionAsDataError",
     "JsonbMerge",
+    "JsonbRemoveKeys",
+    "is_sql_expression",
     "JsonbObjectAgg",
     "Filter",
     "Case",

{matrx_orm-3.1.243 → matrx_orm-3.1.244}/matrx_orm/adapters/postgrest_client_adapter.py

@@ -225,6 +225,15 @@ class PostgRESTClientAdapter(BaseAdapter):
         filters = self._translate_filters(query_dict.get("filters", {}))
         data: dict | list = query_dict.get("data", {})
 
+        # PostgREST takes JSON rows, not SQL: an expression object here would be
+        # serialised as data. Refuse before anything is sent.
+        from matrx_orm.core.expressions import ExpressionAsDataError, is_sql_expression
+
+        for row in data if isinstance(data, list) else [data]:
+            for column, value in (row or {}).items():
+                if is_sql_expression(value):
+                    raise ExpressionAsDataError(column, value)
+
         logger.debug("[PostgRESTClientAdapter] %s %s", operation.upper(), table)
 
         try:

{matrx_orm-3.1.243 → matrx_orm-3.1.244}/matrx_orm/core/expressions.py

@@ -1575,6 +1575,34 @@ class JsonbMerge(Func):
         return f"JsonbMerge({self.args[0]!r}, {self.value!r})"
 
 
+class JsonbRemoveKeys(Func):
+    """``COALESCE(field, '{}'::jsonb) - $keys::text[]`` — atomically drop top-level
+    keys from a JSONB column (the removal sibling of :class:`JsonbMerge`), for use as
+    an ``.update()`` / ``update_where()`` SET value. Every other key is untouched;
+    a key that is absent is a no-op.
+
+    Usage::
+
+        await SiteKeywordValue.update_where(
+            {"id__in": ids}, metadata=JsonbRemoveKeys("metadata", ["serp_cluster"])
+        )
+    """
+
+    function = "JSONB_REMOVE_KEYS"
+
+    def __init__(self, field: str, keys: list[str] | tuple[str, ...]) -> None:
+        super().__init__(field)
+        self.keys = [str(k) for k in keys]
+
+    def as_sql(self, params: list[Any]) -> str:
+        inner = _render_func_arg(self.args[0], params)
+        params.append(self.keys)
+        return f"COALESCE({inner}, '{{}}'::jsonb) - ${len(params)}::text[]"
+
+    def __repr__(self) -> str:
+        return f"JsonbRemoveKeys({self.args[0]!r}, {self.keys!r})"
+
+
 class JsonbConcat(Func):
     """``a || b`` — jsonb concat of two RENDERABLE expressions (columns,
     ``F()``/``Excluded()`` references, or nested ``Func``s), top-level keys
@@ -2566,3 +2594,51 @@ class TsMatch:
             f"TsMatch({self.column!r}, config={self.config!r}, "
             f"column_is_tsvector={self.column_is_tsvector})"
         )
+
+
+# ---------------------------------------------------------------------------
+# Expression-as-data guard
+# ---------------------------------------------------------------------------
+
+# Expression types that carry no ``as_sql`` of their own (they are rendered by
+# their consumers) — listed so the predicate below still recognises them.
+_EXPRESSION_TYPES_WITHOUT_AS_SQL: tuple[type, ...] = (F, Q, OuterRef)
+
+
+def is_sql_expression(value: Any) -> bool:
+    """True when *value* is a SQL expression object, never a storable value.
+
+    Every class in this module is SQL: either it renders itself through
+    ``as_sql`` (``Func`` and all its subclasses — ``JsonbMerge``, ``Now``,
+    ``Coalesce``…, ``Expression``/``BinaryExpr`` increments, ``Case``,
+    ``Subquery``, ``Value``, ``Excluded``, predicates, ``Window``…) or it is
+    one of the few renderer-side references (``F``, ``Q``, ``OuterRef``).
+    ``as_sql`` is looked up on the CLASS, so a test double whose instance
+    answers every attribute (``MagicMock``) is not mistaken for SQL.
+    """
+    if value is None or isinstance(value, type):
+        return False
+    if isinstance(value, _EXPRESSION_TYPES_WITHOUT_AS_SQL):
+        return True
+    return any("as_sql" in vars(klass) for klass in type(value).__mro__)
+
+
+class ExpressionAsDataError(TypeError):
+    """A SQL expression object reached a path that would store it as data.
+
+    Raised instead of serialising the object (a jsonb column used to receive
+    ``{"args": [...], "value": ...}`` — the 2026-10-22 metadata loss on 1,328
+    rows). Expressions are compiled to SQL by ``Model.update_where`` /
+    ``QueryBuilder.update`` and by instance ``update()`` / ``save()``; every
+    other write path (INSERT, upsert data, filters) refuses them here.
+    """
+
+    def __init__(self, field_name: str | None, value: Any) -> None:
+        self.field_name = field_name
+        self.value = value
+        super().__init__(
+            f"{type(value).__name__} is a SQL expression, not a value — refusing to "
+            f"serialise {value!r} into field {field_name!r}. Expressions run as SQL only "
+            f"in an UPDATE SET: use Model.update_where(filters, {field_name}=...) or "
+            f"instance.update({field_name}=...)."
+        )

{matrx_orm-3.1.243 → matrx_orm-3.1.244}/matrx_orm/core/fields.py

@@ -44,7 +44,35 @@ def _strip_nul_bytes(value: Any) -> Any:
     return value
 
 
+def _refuse_expression_as_data(prep: Any) -> Any:
+    """Wrap a ``get_db_prep_value`` so a SQL expression object can never be
+    serialised as a stored value (``json.dumps`` / ``str()`` of a ``JsonbMerge``
+    wrote its attribute dict into live jsonb columns). Every Field subclass is
+    wrapped at class creation, so a new field type cannot forget the check."""
+    import functools
+
+    if getattr(prep, "_refuses_expressions", False):
+        return prep
+
+    @functools.wraps(prep)
+    def guarded(self: Any, value: Any, *args: Any, **kwargs: Any) -> Any:
+        from matrx_orm.core.expressions import ExpressionAsDataError, is_sql_expression
+
+        if is_sql_expression(value):
+            raise ExpressionAsDataError(getattr(self, "name", None), value)
+        return prep(self, value, *args, **kwargs)
+
+    guarded._refuses_expressions = True  # type: ignore[attr-defined]
+    return guarded
+
+
 class Field:
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        own = cls.__dict__.get("get_db_prep_value")
+        if own is not None:
+            cls.get_db_prep_value = _refuse_expression_as_data(own)  # type: ignore[method-assign]
+
     if TYPE_CHECKING:
 
         @overload
@@ -147,6 +175,8 @@ class Field:
             return None
         return value
 
+    get_db_prep_value = _refuse_expression_as_data(get_db_prep_value)
+
     def desc(self):
         """Mark this field for descending order."""
         self._order_direction = "DESC"
@@ -1166,6 +1196,13 @@ class JSONBField(Field, Generic[_JT]):
         import uuid as _uuid
         from decimal import Decimal as _Decimal
 
+        from matrx_orm.core.expressions import ExpressionAsDataError, is_sql_expression
+
+        # A SQL expression nested inside a json value is never data — degrading
+        # it to its attribute dict is exactly how JsonbMerge objects were stored.
+        if is_sql_expression(obj):
+            raise ExpressionAsDataError(None, obj)
+
         # Pydantic v2 — preferred for the JSON-mode dump that handles nested
         # exotic types correctly.
         model_dump = getattr(obj, "model_dump", None)

{matrx_orm-3.1.243 → matrx_orm-3.1.244}/matrx_orm/operations/FEATURE.md

@@ -34,6 +34,21 @@ READ depends on the database, not on the deploy. `catalog_select`:
 Guard: `tests/test_dynamic_select_unregistered.py` (failing before the fallback
 existed), plus `tests/level1/test_dynamic_crud.py` for the write-side refusals.
 
+## SQL expressions are compiled, never stored
+
+An expression object (`JsonbMerge`, `F(...) + 1`, `Coalesce`, `Now()`, `Case`,
+`Subquery`, `Value`, `Excluded`, any `Func` or class with `as_sql`, plus `F`/`Q`/
+`OuterRef`) is SQL, never data. `update_where`, `QueryBuilder.update`, instance
+`update()`/`save()` (`update_instance`) and `bulk_update` all hand it to the
+executor's SET compiler; the instance ends holding the database-computed value.
+Every other path that would serialise one — INSERT data, upsert rows, a json
+value nesting one, a json function argument, a PostgREST write — raises
+`ExpressionAsDataError` before anything is written (`Field.get_db_prep_value` is
+wrapped for every Field subclass, and the json encoders refuse nested ones).
+Predicate: `matrx_orm.is_sql_expression`. Guard:
+`tests/test_instance_update_runs_expressions.py` (live round trip on a disposable
+loopback Postgres, `ISOLATED_PG17_DSN`; red on the prior code).
+
 ## Event-loop safety
 
 - **Bulk row coercion never runs on the event loop.** `bulk_insert_ignore` and
@@ -51,6 +66,9 @@ Verified against `conflict_writes.py` and
 
 ## Change Log
 
+- 2026-10-22 — Instance `update()`/`save()`/`bulk_update` compile SQL expressions;
+  every serialising path refuses them (`ExpressionAsDataError`).
+
 - 2026-09-26 — Added the typed `update_where` guard to `upsert_with_conflict`.
 
 - 2026-09-11 — Added the live-catalog read fallback so an unregistered view or a

{matrx_orm-3.1.243 → matrx_orm-3.1.244}/matrx_orm/operations/db_functions.py

@@ -34,6 +34,16 @@ if TYPE_CHECKING:  # pragma: no cover
 _FUNCTION_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$")
 
 
+def _json_arg_default(obj: Any) -> str:
+    """``default=str`` for json-bound function args — except a SQL expression,
+    which must never be stringified into data."""
+    from matrx_orm.core.expressions import ExpressionAsDataError, is_sql_expression
+
+    if is_sql_expression(obj):
+        raise ExpressionAsDataError(None, obj)
+    return str(obj)
+
+
 def _render_call(function_name: str, args: tuple[Any, ...]) -> tuple[str, list[Any]]:
     if not _FUNCTION_NAME_RE.match(function_name):
         raise ValueError(f"call_db_function: invalid function name {function_name!r}")
@@ -47,7 +57,7 @@ def _render_call(function_name: str, args: tuple[Any, ...]) -> tuple[str, list[A
             values.append(arg)
         elif isinstance(arg, dict | list):
             placeholders.append(f"${index}::jsonb")
-            values.append(json.dumps(arg, ensure_ascii=False, default=str))
+            values.append(json.dumps(arg, ensure_ascii=False, default=_json_arg_default))
         else:
             placeholders.append(f"${index}")
             values.append(arg)

{matrx_orm-3.1.243 → matrx_orm-3.1.244}/matrx_orm/operations/update.py

@@ -9,7 +9,7 @@ from matrx_orm.core.types import UpdateResult
 from matrx_orm.exceptions import describe_db_exception
 from matrx_orm.state import StateManager
 
-from ..core.expressions import F
+from ..core.expressions import F, is_sql_expression
 from ..query.builder import QueryBuilder
 
 if TYPE_CHECKING:
@@ -286,7 +286,9 @@ async def bulk_update(
                 if field_name in model_cls._fields and hasattr(obj, field_name):
                     field = model_cls._fields[field_name]
                     value = getattr(obj, field_name)
-                    if value is not None:
+                    if is_sql_expression(value):
+                        update_data[field_name] = value  # compiled by the executor
+                    elif value is not None:
                         update_data[field_name] = field.get_db_prep_value(value)
 
             row_filter = dict(pk_filter)
@@ -310,6 +312,14 @@ async def bulk_update(
                     )
                 if result.rows_affected > 0:
                     rows_affected += 1
+                    # An expression field holds the database-computed value
+                    # afterwards, never the expression (a later save would
+                    # re-run it).
+                    if result.updated_rows:
+                        returned = result.updated_rows[0]
+                        for field_name, sent in update_data.items():
+                            if is_sql_expression(sent) and field_name in returned:
+                                setattr(obj, field_name, returned[field_name])
                     # Do NOT cache `obj` here. It is the CALLER's instance and is
                     # routinely a partial {pk + payload} stub (see
                     # session/flush.py), so writing it into the identity cache
@@ -461,6 +471,7 @@ async def update_instance(
         current_version = expected_version
 
     update_data: dict[str, Any] = {}
+    expression_fields: set[str] = set()
     field_names: Iterable[str] = (
         fields if fields is not None else [f for f in model_cls._fields if f not in pk_filter]
     )
@@ -473,7 +484,14 @@ async def update_instance(
             continue  # handled below — never depends on being in `fields`
         field = model_cls._fields[field_name]
         value = getattr(instance, field_name, None)
-        if value is not None:
+        if is_sql_expression(value):
+            # SQL, not data: hand it to the executor untouched so it compiles
+            # into the SET clause exactly as update_where() does. Running it
+            # through get_db_prep_value is what json-dumped JsonbMerge objects
+            # into live jsonb columns.
+            update_data[field_name] = value
+            expression_fields.add(field_name)
+        elif value is not None:
             update_data[field_name] = field.get_db_prep_value(value)
         elif field.nullable:
             update_data[field_name] = None
@@ -517,5 +535,20 @@ async def update_instance(
     elif version_field_name is not None and version_field_name in update_data:
         setattr(instance, version_field_name, update_data[version_field_name])
 
+    # An expression field must end holding the value the database computed —
+    # never the expression object, which a later save() would re-run (a second
+    # increment) or a reader would mistake for data. RETURNING normally covers
+    # it; re-read whatever it did not.
+    unresolved = [f for f in expression_fields if is_sql_expression(getattr(instance, f, None))]
+    if unresolved:
+        fresh = await QueryBuilder(model_cls).filter(**pk_filter).first()
+        if fresh is None:
+            raise ValueError(
+                f"{model_cls.__name__} {pk_filter}: updated, but the row could not be "
+                f"re-read to resolve expression fields {sorted(unresolved)}"
+            )
+        for f in unresolved:
+            setattr(instance, f, getattr(fresh, f, None))
+
     await post_save.send(model_cls, instance=instance, created=False)
     return instance

{matrx_orm-3.1.243 → matrx_orm-3.1.244}/matrx_orm/query/executor.py

@@ -1564,7 +1564,7 @@ class QueryExecutor:
             invalid_fields: list[str] = []
             skipped_fields: list[str] = []
 
-            from matrx_orm.core.expressions import Expression, Func, Subquery
+            from matrx_orm.core.expressions import F, Expression, Func, Subquery
 
             for k, v in kwargs.items():
                 if k in self.model._fields:
@@ -1600,6 +1600,9 @@ class QueryExecutor:
                     expr_sql = value.as_sql(params)
                     set_clause.append(f"{field_name} = {expr_sql}")
                     param_index = len(params) + 1
+                elif isinstance(value, F):
+                    # SET col = other_col (F validates the identifier).
+                    set_clause.append(f"{field_name} = {value.field_name}")
                 elif isinstance(value, Expression):
                     expr_sql = _render_update_expression(value, params)
                     set_clause.append(f"{field_name} = {expr_sql}")

{matrx_orm-3.1.243 → matrx_orm-3.1.244}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.243"
+version = "3.1.244"
 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.244/tests/test_instance_update_runs_expressions.py

@@ -0,0 +1,237 @@
+"""An instance ``update()`` / ``save()`` RUNS a SQL expression — it never stores one.
+
+THE INCIDENT (2026-10-22). ``row.update(metadata=JsonbMerge("metadata", {...}))`` sent
+the JsonbMerge object through ``JSONField.get_db_prep_value``; ``json.dumps`` degraded
+it to its attribute dict and wrote ``{"args": [...], "value": ...}`` over the metadata
+of 1,328 live rows. ``Model.update_where`` compiled the same object to SQL correctly;
+the instance path did not. A text column had the same hole (``str(expression)``).
+
+THE GUARD. Instance ``update()``/``save()`` and ``bulk_update`` hand expressions to the
+executor, which compiles them into the SET clause exactly as ``update_where`` does, and
+the instance ends holding the value the database computed. Every other path that would
+serialise an expression (INSERT data, a json value that nests one) raises
+``ExpressionAsDataError`` before anything is written.
+
+Every test does a real round trip and re-reads the row with raw SQL, so a stored
+expression cannot hide behind the in-memory instance. Needs a DISPOSABLE loopback
+Postgres (``ISOLATED_PG17_DSN``); it creates and drops its own tables.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from ipaddress import ip_address
+from urllib.parse import unquote, urlparse
+
+import pytest
+
+from matrx_orm import (
+    Coalesce,
+    ExpressionAsDataError,
+    F,
+    JsonbMerge,
+    Upper,
+)
+from matrx_orm.core.async_db_manager import AsyncDatabaseManager
+from matrx_orm.core.base import Model
+from matrx_orm.core.config import DatabaseProjectConfig, register_database, registry
+from matrx_orm.core.fields import CharField, IntegerField, JSONBField, TextField, UUIDField
+from matrx_orm.operations.update import bulk_update
+from matrx_orm.state import StateManager
+
+pytestmark = pytest.mark.asyncio
+
+_DB = "expr_guard_db"
+_SUFFIX = uuid.uuid4().hex[:8]
+_TABLE = f"expr_guard_{_SUFFIX}"
+
+
+class ExprRow(Model):
+    id = UUIDField(primary_key=True)
+    label = CharField(max_length=100, null=True)
+    note = TextField(null=True)
+    counter = IntegerField(null=True)
+    metadata = JSONBField(null=True)
+    _database = _DB
+    _table_name = _TABLE
+
+
+def _loopback_dsn() -> dict[str, str]:
+    dsn = os.environ.get("ISOLATED_PG17_DSN")
+    if not dsn:
+        pytest.skip("ISOLATED_PG17_DSN (a disposable loopback Postgres) is required")
+    u = urlparse(dsn)
+    host = (u.hostname or "").strip("[]")
+    try:
+        loopback = ip_address(host).is_loopback
+    except ValueError:
+        loopback = host == "localhost"
+    if not loopback:
+        raise RuntimeError(f"REFUSED: {host!r} is not loopback — this test creates tables.")
+    return {
+        "host": host,
+        "port": str(u.port or 5432),
+        "user": unquote(u.username or "postgres"),
+        "password": unquote(u.password or ""),
+        "database_name": (u.path or "/postgres").lstrip("/") or "postgres",
+    }
+
+
+@pytest.fixture
+async def db():
+    target = _loopback_dsn()
+    # Other suites clear the process-wide state registry; re-register this model.
+    StateManager.register_model(ExprRow)
+    registry._configs.pop(_DB, None)
+    if f"{_DB}_alias" in registry._used_aliases:
+        registry._used_aliases.remove(f"{_DB}_alias")
+    register_database(
+        DatabaseProjectConfig(
+            name=_DB,
+            alias=f"{_DB}_alias",
+            host=target["host"],
+            port=target["port"],
+            database_name=target["database_name"],
+            user=target["user"],
+            password=target["password"],
+            pool_min=1,
+            pool_max=2,
+            ssl=False,
+            write_queue_enabled=False,
+        )
+    )
+    async with AsyncDatabaseManager.get_connection(_DB) as conn:
+        await conn.execute(f"DROP TABLE IF EXISTS public.{_TABLE}")
+        await conn.execute(
+            f"CREATE TABLE public.{_TABLE} (id uuid PRIMARY KEY, label varchar(100), "
+            f"note text, counter integer, metadata jsonb)"
+        )
+    try:
+        yield
+    finally:
+        async with AsyncDatabaseManager.get_connection(_DB) as conn:
+            await conn.execute(f"DROP TABLE IF EXISTS public.{_TABLE}")
+        pool = AsyncDatabaseManager._pools.pop(_DB, None)
+        if pool is not None:
+            await pool.close()
+        AsyncDatabaseManager._pool_loops.pop(_DB, None)
+        AsyncDatabaseManager._locks.pop(_DB, None)
+        AsyncDatabaseManager._growth_locks.pop(_DB, None)
+        task = AsyncDatabaseManager._keepalive_tasks.pop(_DB, None)
+        if task is not None:
+            task.cancel()
+        registry._configs.pop(_DB, None)
+        if f"{_DB}_alias" in registry._used_aliases:
+            registry._used_aliases.remove(f"{_DB}_alias")
+
+
+async def _raw(row_id: str) -> dict | None:
+    async with AsyncDatabaseManager.get_connection(_DB) as conn:
+        rec = await conn.fetchrow(
+            f"SELECT label, note, counter, metadata::text AS metadata FROM public.{_TABLE} "
+            f"WHERE id = $1::uuid",
+            row_id,
+        )
+    if rec is None:
+        return None
+    out = dict(rec)
+    out["metadata"] = json.loads(out["metadata"]) if out["metadata"] is not None else None
+    return out
+
+
+async def _all_stored_text() -> list[str]:
+    async with AsyncDatabaseManager.get_connection(_DB) as conn:
+        rows = await conn.fetch(
+            f"SELECT coalesce(label,'') || '|' || coalesce(note,'') || '|' || "
+            f"coalesce(metadata::text,'') AS t FROM public.{_TABLE}"
+        )
+    return [r["t"] for r in rows]
+
+
+def _serialised_expression(text: str) -> bool:
+    return any(m in text for m in ('"args"', "JsonbMerge", "Expression(", "Func", "Upper("))
+
+
+async def _new(**values) -> ExprRow:
+    return await ExprRow.create(id=str(uuid.uuid4()), **values)
+
+
+async def test_instance_update_with_jsonb_merge_merges(db) -> None:
+    row = await _new(metadata={"views": 100, "keep": True})
+    await row.update(metadata=JsonbMerge("metadata", {"placement": {"slot": 3}}))
+
+    stored = (await _raw(row.id))["metadata"]
+    assert stored == {"views": 100, "keep": True, "placement": {"slot": 3}}
+    assert row.metadata == stored  # the computed value, not the expression
+
+
+async def test_instance_update_with_jsonb_merge_on_a_null_column(db) -> None:
+    row = await _new(metadata=None)
+    await row.update(metadata=JsonbMerge("metadata", {"classification": "a"}))
+    assert (await _raw(row.id))["metadata"] == {"classification": "a"}
+
+
+async def test_save_with_a_jsonb_merge_attribute_merges(db) -> None:
+    row = await _new(metadata={"views": 1})
+    row.metadata = JsonbMerge("metadata", {"extra": 2})
+    await row.save()
+    stored = (await _raw(row.id))["metadata"]
+    assert stored == {"views": 1, "extra": 2}
+    assert row.metadata == stored
+
+
+async def test_increments_run_once_and_a_later_save_does_not_rerun_them(db) -> None:
+    row = await _new(counter=None)
+    await row.update(counter=Coalesce(F("counter"), 0) + 7)  # BinaryExpr
+    assert row.counter == 7
+    await row.update(counter=F("counter") * 2)  # Expression
+    assert row.counter == 14
+    await row.save()  # nothing changed: must not re-apply anything
+    assert (await _raw(row.id))["counter"] == 14
+
+
+async def test_text_functions_and_column_references_run_as_sql(db) -> None:
+    row = await _new(label="quiet", note="n")
+    await row.update(label=Upper(F("label")))
+    assert (await _raw(row.id))["label"] == "QUIET"
+    await row.update(note=F("label"))
+    assert (await _raw(row.id))["note"] == "QUIET"
+    assert row.note == "QUIET"
+
+
+async def test_bulk_update_runs_expressions(db) -> None:
+    row = await _new(metadata={"a": 1})
+    row.metadata = JsonbMerge("metadata", {"b": 2})
+    assert await bulk_update(ExprRow, [row], ["metadata"]) == 1
+    stored = (await _raw(row.id))["metadata"]
+    assert stored == {"a": 1, "b": 2}
+    assert row.metadata == stored
+
+
+async def test_insert_with_an_expression_refuses_and_writes_nothing(db) -> None:
+    row_id = str(uuid.uuid4())
+    with pytest.raises(ExpressionAsDataError):
+        await ExprRow.create(id=row_id, metadata=JsonbMerge("metadata", {"a": 1}))
+    with pytest.raises(ExpressionAsDataError):
+        await ExprRow.create(id=row_id, label=Upper(F("label")))
+    assert await _raw(row_id) is None
+
+
+async def test_an_expression_nested_inside_json_refuses(db) -> None:
+    row = await _new(metadata={"a": 1})
+    with pytest.raises(ExpressionAsDataError):
+        await row.update(metadata={"placement": JsonbMerge("metadata", {"x": 1})})
+    assert (await _raw(row.id))["metadata"] == {"a": 1}
+
+
+async def test_no_stored_value_is_ever_a_serialised_expression(db) -> None:
+    """Drive every write shape at one table, then scan what Postgres holds."""
+    a = await _new(label="x", note="y", counter=1, metadata={"k": 1})
+    await a.update(metadata=JsonbMerge("metadata", {"m": 1}), label=Upper(F("label")))
+    a.note = F("label")
+    a.counter = F("counter") + 1
+    await a.save()
+    for text in await _all_stored_text():
+        assert not _serialised_expression(text), text