matrx-orm 3.1.3__tar.gz → 3.1.5__tar.gz

{matrx_orm-3.1.3 → matrx_orm-3.1.5}/CLAUDE.md

@@ -20,6 +20,7 @@ matrx-orm is a standalone async Postgres ORM (`Model`, `QueryBuilder`, migration
 - **`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.
 - **Read-only models** (`_read_only = True`): a model that can be queried but NEVER written through the ORM — every write path raises `ReadOnlyModelError` (enforced at `QueryExecutor.insert/bulk_insert/upsert/update/delete`, so it covers all of `create`/`save`/`update`/`delete`/`update_where`/`delete_where`/`upsert`/`bulk_*`). Used for DB-managed tables the app must not mutate. The canonical **`auth.users`** model is baked into the schema generator (`get_string_user_model`) as the full, curated Supabase auth schema (safe columns only — no password/token fields), `_read_only`, bound per-database. Read a user's profile/metadata there; mutate users only through Supabase Auth (GoTrue).
+- **Connection-level type codecs** (`async_db_manager._init_connection_default`): every pooled connection decodes **uuid → `str`**, **vector → `list[float]`**, and **json/jsonb → `dict`/`list`** at the driver boundary — the TYPE decides the decode, never the call path. So `call_function` scalar/rows, raw fetches, and field hydration all agree; a caller must **never `json.loads` a fetched json/jsonb value** (it's already decoded; the 2026-07-13 `build_agent_context` crash was a jsonb RPC fetched pre-codec as a raw string). Encoding: a pre-serialised JSON `str` passes through untouched; a native dict/list is dumped (`_encode_json`). Pinned by `tests/level1/test_connection_codecs.py`.
 - **Query layer**: `QueryBuilder`, expressions (`F`, `Q`), window functions, CTEs, subqueries.
 - **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.

{matrx_orm-3.1.3 → matrx_orm-3.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.3
+Version: 3.1.5
 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.3 → matrx_orm-3.1.5}/matrx_orm/core/async_db_manager.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import json
 import logging
 import os
 import traceback
@@ -143,6 +144,23 @@ def _decode_vector(value: str) -> list[float]:
     return [float(x) for x in inner.split(",")]
 
 
+def _encode_json(value: Any) -> str:
+    """Encode a Python value bound to a ``json``/``jsonb`` parameter.
+
+    A ``str`` passes through untouched — every existing ORM write path
+    (``JSONField.get_db_prep_value``, ``JsonbMerge``, ``call_function``'s
+    ``_bind_args``) pre-serialises to a JSON string, and asyncpg's built-in
+    codec (which this replaces) also required ``str``. Anything else (dict,
+    list, int, ...) is serialised here with the same coercion hook the field
+    layer uses, so binding a native container directly now also works.
+    """
+    if isinstance(value, str):
+        return value
+    from matrx_orm.core.fields import JSONBField
+
+    return json.dumps(value, default=JSONBField._json_default)
+
+
 async def _init_connection_default(conn: asyncpg.Connection) -> None:
     """Register custom type codecs on each new connection.
 
@@ -166,6 +184,28 @@ async def _init_connection_default(conn: asyncpg.Connection) -> None:
         format="text",
     )
 
+    # json/jsonb → dict/list (decode) and str-or-native → json text (encode).
+    #
+    # Without this codec asyncpg hands json/jsonb values back as RAW JSON
+    # STRINGS. The field layer papered over that (``JSONField.to_python`` does
+    # ``json.loads``), but every fetch path that bypasses field hydration —
+    # ``call_function`` scalar/rows, ``field=`` dereference, sql_executor rows
+    # — returned a ``str`` where the caller expected a ``dict``. That is
+    # exactly the 2026-07-13 ``build_agent_context`` crash ("'str' object has
+    # no attribute 'get'"): a jsonb-returning RPC moved from PostgREST (which
+    # decodes) to ``call_function`` (which didn't). Decoding at the driver
+    # boundary kills the whole class: the DRIVER knows the value is jsonb, so
+    # the type — not the call path — decides the decode. ``to_python`` already
+    # passes non-str values through, so field hydration is unaffected.
+    for _json_type in ("json", "jsonb"):
+        await conn.set_type_codec(
+            _json_type,
+            encoder=_encode_json,
+            decoder=json.loads,
+            schema="pg_catalog",
+            format="text",
+        )
+
     # pgvector → list[float]
     #
     # The ``vector`` type lives in whichever schema the pgvector extension was

{matrx_orm-3.1.3 → matrx_orm-3.1.5}/matrx_orm/core/db_function.py

@@ -14,7 +14,11 @@ hand-write `SELECT schema.func(...)` itself — call this instead.
 
 Three return modes:
   * ``mode="scalar"`` (default) — the function returns one usable value
-    (text, integer, boolean, ...); we ``fetchval`` it.
+    (text, integer, boolean, ...); we ``fetchval`` it. A ``json``/``jsonb``
+    return value arrives as a decoded ``dict``/``list`` (never a raw JSON
+    string) — the pool's connection-level codec
+    (``async_db_manager._init_connection_default``) decodes at the driver
+    boundary. Callers must NOT ``json.loads`` a result.
   * ``mode="none"`` — the function's return value is discarded (e.g. it
     returns a composite/row type the caller doesn't need decoded). We
     ``execute`` the statement instead of ``fetchval``, which never attempts
@@ -37,12 +41,12 @@ composite; the single field still comes back scalar, through ``fetchval``.
 alongside a row-set, is a caller bug, not a valid combination).
 
 A ``dict``/``list`` positional argument is JSON-serialised and its
-placeholder is cast explicitly (``$N::jsonb``) — asyncpg has no jsonb
-encoder, so a bare dict would bind as an unsupported parameter type and
-raise. This mirrors the same trick ``JsonbMerge`` already uses for
-ORM-generated ``UPDATE`` statements (see
-``matrx_orm.core.expressions.JsonbMerge``) — it is not a special case, it is
-how every jsonb-typed function parameter must be bound.
+placeholder is cast explicitly (``$N::jsonb``). The pool's connection-level
+json codec (``async_db_manager._encode_json``) passes the pre-serialised
+string through untouched, so this never double-encodes. This mirrors the
+same trick ``JsonbMerge`` already uses for ORM-generated ``UPDATE``
+statements (see ``matrx_orm.core.expressions.JsonbMerge``) — it is not a
+special case, it is how every jsonb-typed function parameter is bound.
 
 A genuine Postgres **array** parameter (``uuid[]``, ``text[]``, ...) is a
 different shape from jsonb — asyncpg natively encodes a Python ``list`` as a

{matrx_orm-3.1.3 → matrx_orm-3.1.5}/matrx_orm/core/expressions.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
+from datetime import date, datetime
+from decimal import Decimal
 from typing import Any, TYPE_CHECKING
+from uuid import UUID
 
 if TYPE_CHECKING:
     pass
@@ -533,6 +536,70 @@ def _render_func_arg(arg: Any, params: list[Any]) -> str:
     return f"${len(params)}"
 
 
+# ---------------------------------------------------------------------------
+# Type-anchoring for bound literals in a CASE branch
+# ---------------------------------------------------------------------------
+#
+# Postgres infers a bare `$N`'s type from its surrounding context. A CASE whose
+# THEN/ELSE branches are ALL bound params has NO anchor to infer from, so it
+# falls back to `text` — and asyncpg then refuses to encode a Python int/bool/
+# float into that text slot:
+#
+#     invalid input for query argument $5: 0 (expected str, got int)
+#
+# Verified live (project txzxabzwovsujtloxrus):
+#     PREPARE p AS SELECT 1 FROM t ORDER BY CASE WHEN lower(name) = $1
+#                                                THEN $2 ELSE $3 END;
+#     -> parameter_types = {text,text,text}      # $2/$3 silently become text
+#     ... THEN $2::bigint ELSE $3::bigint END
+#     -> parameter_types = {text,bigint,bigint}  # anchored
+#
+# So a CASE-branch literal is bound WITH an explicit cast: the value stays
+# parameterized (zero injection surface) and Postgres gets its type anchor.
+# Anywhere else (`col = $N`, `func($N)`) the column/signature already supplies
+# the anchor, which is why this is scoped to CASE rather than applied to every
+# bound literal — a blanket `::text` would break `uuid_col = $N`.
+#
+# Order matters: bool before int (bool IS a subclass of int), datetime before
+# date (datetime IS a subclass of date).
+_PG_LITERAL_CASTS: tuple[tuple[type, str], ...] = (
+    (bool, "boolean"),
+    (int, "bigint"),
+    (float, "double precision"),
+    (Decimal, "numeric"),
+    (datetime, "timestamptz"),
+    (date, "date"),
+    (UUID, "uuid"),
+)
+
+
+def _pg_cast_for_literal(value: Any) -> str | None:
+    """The Postgres type to anchor a bound Python literal to, or None if unknown."""
+    for py_type, pg_type in _PG_LITERAL_CASTS:
+        if isinstance(value, py_type):
+            return pg_type
+    return None
+
+
+def _render_case_result(arg: Any, params: list[Any]) -> str:
+    """Render a CASE THEN/ELSE branch, type-anchoring any bound literal.
+
+    Identical to :func:`_render_func_arg` for columns/expressions; the ONLY
+    difference is that a bound literal gets an explicit `::type` cast, because a
+    CASE branch is a context Postgres cannot infer a param's type from.
+    """
+    if arg is None:
+        # An unadorned NULL is unknown-typed too, but it unifies with whatever
+        # the sibling branch resolves to — no cast needed, and none is possible.
+        return "NULL"
+    if isinstance(arg, str) or hasattr(arg, "as_sql") or isinstance(arg, F):
+        # Bare strings are column names, per the Func-arg convention.
+        return _render_func_arg(arg, params)
+    params.append(arg)
+    cast = _pg_cast_for_literal(arg)
+    return f"${len(params)}::{cast}" if cast else f"${len(params)}"
+
+
 # ---------------------------------------------------------------------------
 # Case / When — conditional CASE WHEN ... THEN ... ELSE ... END expression
 # ---------------------------------------------------------------------------
@@ -552,8 +619,13 @@ class When:
 
     Usage::
 
-        When("lower(e.name) = $1", phrase, then=0)                    # -> WHEN lower(e.name) = $1 THEN $2
+        When("lower(e.name) = $1", phrase, then=0)                    # -> WHEN lower(e.name) = $1 THEN $2::bigint
         When("ed.src_id = ANY($1::uuid[])", ids, then="ed.dst_id")    # then = bare column, not bound
+
+    A bound ``then``/``default`` literal is rendered WITH an explicit ``::type``
+    cast — a CASE branch gives Postgres no type to infer from, so an unadorned
+    ``$N`` silently resolves to ``text`` and asyncpg then rejects a Python int
+    ("expected str, got int"). See :func:`_render_case_result`.
     """
 
     def __init__(self, condition: str, *condition_params: Any, then: Any) -> None:
@@ -569,7 +641,7 @@ class When:
             params.extend(self.condition_params)
         else:
             cond_sql = self.condition
-        then_sql = _render_func_arg(self.then, params)
+        then_sql = _render_case_result(self.then, params)
         return f"WHEN {cond_sql} THEN {then_sql}"
 
     def __repr__(self) -> str:
@@ -615,7 +687,7 @@ class Case:
         for w in self.whens:
             parts.append(w.as_sql(params))
         if self.default is not None:
-            parts.append(f"ELSE {_render_func_arg(self.default, params)}")
+            parts.append(f"ELSE {_render_case_result(self.default, params)}")
         parts.append("END")
         return " ".join(parts)
 
@@ -708,9 +780,10 @@ class JsonbMerge(Func):
     sibling, expressible directly on ``Model.update_where`` (no manager
     needed).
 
-    ``value`` is JSON-serialised here (never left to the caller) so it binds
-    as a plain string param cast to ``jsonb`` — asyncpg has no jsonb codec
-    registered, so a bare dict param would bind as text and fail the cast.
+    ``value`` is JSON-serialised here (never left to the caller) and binds
+    as a string param cast to ``jsonb``. The pool's connection-level json
+    codec (``async_db_manager._encode_json``) passes pre-serialised strings
+    through untouched, so this never double-encodes.
 
     Usage::
 

{matrx_orm-3.1.3 → matrx_orm-3.1.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.3"
+version = "3.1.5"
 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.3 → matrx_orm-3.1.5}/tests/level1/test_case_when.py

@@ -48,14 +48,14 @@ def test_case_rejects_non_when_args():
 def test_single_when_with_literal_then_and_default():
     params: list = []
     sql = Case(When("status = 'paid'", then=1), default=0).as_sql(params)
-    assert sql == "CASE WHEN status = 'paid' THEN $1 ELSE $2 END"
+    assert sql == "CASE WHEN status = 'paid' THEN $1::bigint ELSE $2::bigint END"
     assert params == [1, 0]
 
 
 def test_when_condition_with_bound_param():
     params: list = []
     sql = Case(When("lower(e.name) = $1", "acme corp", then=0), default=1).as_sql(params)
-    assert sql == "CASE WHEN lower(e.name) = $1 THEN $2 ELSE $3 END"
+    assert sql == "CASE WHEN lower(e.name) = $1 THEN $2::bigint ELSE $3::bigint END"
     assert params == ["acme corp", 0, 1]
 
 
@@ -75,7 +75,7 @@ def test_when_then_bare_column_name_not_bound():
 def test_no_default_omits_else_clause():
     params: list = []
     sql = Case(When("x = 1", then=0)).as_sql(params)
-    assert sql == "CASE WHEN x = 1 THEN $1 END"
+    assert sql == "CASE WHEN x = 1 THEN $1::bigint END"
     assert "ELSE" not in sql
 
 
@@ -86,14 +86,14 @@ def test_multiple_when_branches():
         When("tier = 'silver'", then=2),
         default=1,
     ).as_sql(params)
-    assert sql == "CASE WHEN tier = 'gold' THEN $1 WHEN tier = 'silver' THEN $2 ELSE $3 END"
+    assert sql == "CASE WHEN tier = 'gold' THEN $1::bigint WHEN tier = 'silver' THEN $2::bigint ELSE $3::bigint END"
     assert params == [3, 2, 1]
 
 
 def test_condition_params_shift_past_existing_params():
     params: list = ["existing"]
     sql = Case(When("name = $1", "bob", then=1), default=0).as_sql(params)
-    assert sql == "CASE WHEN name = $2 THEN $3 ELSE $4 END"
+    assert sql == "CASE WHEN name = $2 THEN $3::bigint ELSE $4::bigint END"
     assert params == ["existing", "bob", 1, 0]
 
 
@@ -110,7 +110,7 @@ def test_nested_case():
     params: list = []
     inner = Case(When("b = 1", then=2), default=3)
     sql = Case(When("a = 1", then=inner), default=0).as_sql(params)
-    assert sql == "CASE WHEN a = 1 THEN CASE WHEN b = 1 THEN $1 ELSE $2 END ELSE $3 END"
+    assert sql == "CASE WHEN a = 1 THEN CASE WHEN b = 1 THEN $1::bigint ELSE $2::bigint END ELSE $3::bigint END"
     assert params == [2, 3, 0]
 
 
@@ -167,7 +167,7 @@ def test_case_in_order_by():
         "-amount",
     )
     sql, params = QueryExecutor(qb._build_query())._build_query()
-    assert "ORDER BY CASE WHEN status = $1 THEN $2 ELSE $3 END ASC, amount DESC" in sql
+    assert "ORDER BY CASE WHEN status = $1 THEN $2::bigint ELSE $3::bigint END ASC, amount DESC" in sql
     assert params == ["paid", 0, 1]
 
 
@@ -181,7 +181,7 @@ def test_case_in_order_by_with_nulls_last():
     )
     sql, params = QueryExecutor(qb._build_query())._build_query()
     assert (
-        "ORDER BY CASE WHEN lower(status) = $1 THEN $2 ELSE $3 END ASC, "
+        "ORDER BY CASE WHEN lower(status) = $1 THEN $2::bigint ELSE $3::bigint END ASC, "
         "amount DESC NULLS LAST" in sql
     )
     assert params == ["paid", 0, 1]
@@ -264,3 +264,83 @@ def test_join_without_on_params_still_works_unchanged():
     sql, params = QueryExecutor(qb._build_query())._build_query()
     assert "INNER JOIN rag.kg_entities AS e2 ON e2.id = ed.src_id" in sql
     assert params == []
+
+
+# ── Type anchoring: the bug this cast exists to prevent ──────────────────────
+#
+# REGRESSION GUARD. Do NOT "simplify" the `::type` casts out of a CASE branch.
+#
+# Postgres infers a bare `$N`'s type from context. A CASE whose THEN/ELSE
+# branches are ALL bound params has NO context to infer from, so PG resolves
+# them to `text` — and asyncpg then refuses to encode a Python int:
+#
+#     asyncpg.exceptions.DataError:
+#     invalid input for query argument $5: 0 (expected str, got int)
+#
+# Verified live (project txzxabzwovsujtloxrus):
+#     ORDER BY CASE WHEN lower(name) = $1 THEN $2      ELSE $3      END
+#         -> parameter_types = {text,text,text}        # WRONG, and silent
+#     ORDER BY CASE WHEN lower(name) = $1 THEN $2::bigint ELSE $3::bigint END
+#         -> parameter_types = {text,bigint,bigint}    # anchored
+#
+# This shipped broken: every matrx-rag `rag_search` call died in _entity_recall
+# (2026-07-13). The tests above had PINNED the unanchored SQL, so the suite was
+# green while the feature was 100% down.
+
+
+def test_bound_case_literals_are_type_anchored_not_bare_params():
+    """A bound THEN/ELSE literal MUST carry an explicit cast — a bare `$N` in a
+    CASE branch is silently typed `text` by Postgres and blows up on an int."""
+    params: list = []
+    sql = Case(When("lower(e.name) = $1", "acme", then=0), default=1).as_sql(params)
+    # The int literals are bound (never inlined) AND anchored.
+    assert "THEN $2::bigint" in sql
+    assert "ELSE $3::bigint" in sql
+    assert params == ["acme", 0, 1]
+    # No branch may render as a bare, unanchored parameter.
+    assert "THEN $2 " not in sql and not sql.endswith("THEN $2")
+    assert "ELSE $3 " not in sql and "ELSE $3 END" not in sql
+
+
+@pytest.mark.parametrize(
+    "value,expected_cast",
+    [
+        (0, "bigint"),
+        (42, "bigint"),
+        (True, "boolean"),          # bool BEFORE int — bool is a subclass of int
+        (False, "boolean"),
+        (1.5, "double precision"),
+    ],
+)
+def test_case_literal_cast_per_python_type(value, expected_cast):
+    params: list = []
+    sql = Case(When("x = 1", then=value)).as_sql(params)
+    assert sql == f"CASE WHEN x = 1 THEN $1::{expected_cast} END"
+    assert params == [value]
+
+
+def test_bool_then_is_boolean_not_bigint():
+    """Guards the isinstance ordering: `isinstance(True, int)` is True, so a
+    naive int-first map would render a bool as ::bigint."""
+    params: list = []
+    sql = Case(When("x = 1", then=True), default=False).as_sql(params)
+    assert "::boolean" in sql
+    assert "::bigint" not in sql
+
+
+def test_string_then_is_still_a_bare_column_not_a_cast_param():
+    """The str-is-a-column-name convention is UNCHANGED by the anchoring —
+    a str `then` must not suddenly start binding as `$N::text`."""
+    params: list = []
+    sql = Case(When("a = 1", then="ed.dst_id"), default="ed.src_id").as_sql(params)
+    assert sql == "CASE WHEN a = 1 THEN ed.dst_id ELSE ed.src_id END"
+    assert params == []
+
+
+def test_none_then_renders_null_not_an_anchorless_param():
+    """A bound NULL is unknown-typed too; render it inline so it unifies with
+    the sibling branch instead of becoming another text param."""
+    params: list = []
+    sql = Case(When("a = 1", then=None), default=5).as_sql(params)
+    assert sql == "CASE WHEN a = 1 THEN NULL ELSE $1::bigint END"
+    assert params == [5]

matrx_orm-3.1.5/tests/level1/test_connection_codecs.py

@@ -0,0 +1,93 @@
+"""Level 1: connection-level type codecs (``_init_connection_default``).
+
+The pool registers codecs so driver-boundary decoding is uniform across EVERY
+fetch path — model hydration, ``call_function``, sql_executor. The json/jsonb
+codec exists because asyncpg's default returns jsonb as a RAW JSON STRING;
+only the field layer decoded it, so any path that bypassed field hydration
+(e.g. ``call_function(mode="scalar")`` on a jsonb-returning RPC) handed
+callers a ``str`` where they expected a ``dict`` — the 2026-07-13
+``build_agent_context`` crash. These tests pin the registration and the
+encoder's str-pass-through contract so that class of bug stays extinct.
+"""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import AsyncMock
+
+import pytest
+
+from matrx_orm.core.async_db_manager import (
+    _encode_json,
+    _init_connection_default,
+)
+
+
+class _FakeConn:
+    def __init__(self) -> None:
+        self.set_type_codec = AsyncMock()
+        # The vector-schema lookup in _init_connection_default; None = pgvector
+        # not installed, the only legitimate skip.
+        self.fetchval = AsyncMock(return_value=None)
+
+
+class TestJsonCodecRegistration:
+    @pytest.mark.asyncio
+    async def test_registers_json_and_jsonb_decoders(self) -> None:
+        conn = _FakeConn()
+        await _init_connection_default(conn)  # type: ignore[arg-type]
+        registered = {
+            call.args[0]: call.kwargs for call in conn.set_type_codec.await_args_list
+        }
+        for type_name in ("json", "jsonb"):
+            assert type_name in registered, (
+                f"{type_name} codec not registered — jsonb values fetched outside "
+                f"field hydration (call_function scalar/rows) will come back as "
+                f"raw JSON strings again (the build_agent_context crash class)."
+            )
+            kwargs = registered[type_name]
+            assert kwargs["decoder"] is json.loads
+            assert kwargs["encoder"] is _encode_json
+            assert kwargs["schema"] == "pg_catalog"
+
+    @pytest.mark.asyncio
+    async def test_uuid_codec_still_registered(self) -> None:
+        conn = _FakeConn()
+        await _init_connection_default(conn)  # type: ignore[arg-type]
+        assert "uuid" in {c.args[0] for c in conn.set_type_codec.await_args_list}
+
+
+class TestEncodeJson:
+    def test_str_passes_through_untouched(self) -> None:
+        # Every existing write path (JSONField.get_db_prep_value, JsonbMerge,
+        # call_function._bind_args) pre-serialises to str; double-encoding
+        # would corrupt every jsonb write in the platform.
+        assert _encode_json('{"a": 1}') == '{"a": 1}'
+        assert _encode_json("plain") == "plain"
+
+    def test_dict_and_list_serialised(self) -> None:
+        assert json.loads(_encode_json({"a": 1})) == {"a": 1}
+        assert json.loads(_encode_json([1, "b"])) == [1, "b"]
+
+    def test_non_native_values_degrade_via_field_hook(self) -> None:
+        # Same coercion hook the field layer uses (JSONBField._json_default):
+        # a weird value degrades instead of crashing the write.
+        class Weird:
+            __slots__ = ()
+
+            def __repr__(self) -> str:
+                return "<weird>"
+
+        # The exact degrade shape belongs to _json_default's own contract;
+        # what THIS codec guarantees is: never crash, always emit valid JSON.
+        out = _encode_json({"w": Weird()})
+        assert isinstance(json.loads(out), dict)
+
+
+class TestDecodeContract:
+    def test_decoder_yields_native_containers(self) -> None:
+        # json.loads is the registered decoder — pin the shapes callers rely on.
+        assert json.loads('{"variables": {}}') == {"variables": {}}
+        assert json.loads("[1, 2]") == [1, 2]
+        assert json.loads('"scalar"') == "scalar"
+        assert json.loads("null") is None