"""Database-abstraction layer.

All hierarchy / tree / advanced query logic must live here so that the
business layer never depends on SQLite- or PostgreSQL-specific features
(Rule #22). SQLite implementation lives in ``hierarchy.py``. A future
``postgresql.py`` can drop in without changing callers.

Sub-modules
-----------
- :mod:`~simorgh.core.db.hierarchy`  — tree operations (instance + ID-based wrappers)
- :mod:`~simorgh.core.db.scoped`     — ScopedManager / ScopedSoftDeleteManager

Usage
-----
Import tree helpers directly from the sub-module to avoid circular imports
(``core.models`` imports ``core.db.scoped``, so ``core.db.__init__`` must not
re-import from ``hierarchy`` at module load time)::

    from simorgh.core.db.hierarchy import get_ancestors, get_descendants, move_node_by_id
    from simorgh.core.db.hierarchy import ancestors_of, descendants_of, move_node
    from simorgh.core.db.scoped import ScopedManager, ScopedSoftDeleteManager

JSONField compatibility note
-----------------------------
All models use ``django.db.models.JSONField`` (Django 3.1+ built-in) which
works identically on SQLite (dev/test) and PostgreSQL (prod). No
``django.contrib.postgres.fields.JSONField`` is used anywhere.

ArrayField note
---------------
No ``ArrayField`` is used in any model. Where an ordered list is needed,
``JSONField`` with ``default=list`` is used instead, preserving SQLite
compatibility.
"""